interactive

package
v0.87.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 12, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package interactive provides declarative interactivity primitives for GoFastr components. It wraps arbitrary render.HTML with data-cui-* attributes the runtime understands, RPC calls, signal bindings, widget chaining, without writing any JavaScript.

Usage: 

interactive.OnClick(btn,
    interactive.Post("/api/like").OnSuccess(interactive.SetSignal("count")),
)

The package only emits attributes the runtime already handles (data-cui-rpc, data-cui-signal, data-cui-open, etc.) plus new ones added for chaining (data-cui-rpc-open, data-cui-rpc-signal).

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AnimateOnSignal 

func AnimateOnSignal(html render.HTML, signalName, cssClass string) render.HTML

AnimateOnSignal wraps an element so it gets a CSS class when a signal is truthy and loses it when falsy. Used for CSS transition-driven animations like slide-down, fade, etc.

Panics if signalName or cssClass is empty.

func BindAttr added in v0.42.0 

func BindAttr(html render.HTML, signal, attr string) render.HTML

BindAttr wraps an HTML element whose attribute tracks a signal. Injects data-cui-signal, data-cui-signal-mode="attr", and data-cui-signal-attr="<attr>". Use when a signal should drive a single attribute (e.g. aria-expanded, data-active) rather than text content.

func BindHTML added in v0.42.0 

func BindHTML(html render.HTML, signal string) render.HTML

BindHTML wraps an HTML region whose innerHTML is replaced with the signal value (the trusted-HTML path). Injects data-cui-signal and data-cui-signal-mode="html". Use for an island slot an RPC re-renders server-side and returns as a fragment.

func BindText added in v0.42.0 

func BindText(html render.HTML, signal string) render.HTML

BindText wraps an HTML element whose textContent tracks a signal (HTML-escaped). Injects data-cui-signal and data-cui-signal-mode="text". This is the default mode, a bare data-cui-signal with no mode behaves identically, but emitting the mode explicitly documents intent.

func CancelEdit 

func CancelEdit(html render.HTML, signalName string) render.HTML

CancelEdit wraps an element so clicking it sets a signal to false, closing the inline-edit mode. Typically used on a cancel button inside the edit form.

func ClosePaneOnClick added in v0.42.0 

func ClosePaneOnClick(html render.HTML, pane string) render.HTML

ClosePaneOnClick wraps an HTML element so clicking it closes a side pane. Maps to data-hui-pane-close="<pane>". A non-empty pane ("secondary" or "tertiary") closes that specific pane; an empty pane emits data-hui-pane-close="" and closes the topmost open pane. Any other value panics. 

func Dropdown(trigger, panel render.HTML) render.HTML

func EditToggle 

func EditToggle(html render.HTML, signalName string) render.HTML

EditToggle wraps an element so clicking it toggles a boolean signal. Semantic alias for ToggleLocal used in inline-edit patterns: clicking the text span enters edit mode.

func IncLocal 

func IncLocal(html render.HTML, signalName string, delta int) render.HTML

IncLocal wraps an HTML element so clicking it increments a numeric signal by delta (default 1). No RPC is fired. Panics if signalName is a reserved signal name.

func LiveSearch 

func LiveSearch(form render.HTML, action Action, debounceMs int) render.HTML

LiveSearch wraps a form element so input changes fire debounced RPCs. The search input should be the first <input> inside the form. Results are written into the signal named by the action's OnSuccess effect (typically via SetSignal).

debounceMs controls the delay between keystrokes and the RPC call. If debounceMs is 0, a default of 300ms is used.

func OnClick 

func OnClick(html render.HTML, action Action) render.HTML

OnClick wraps an HTML element so that clicking it fires the action. The element must be a clickable element (button, a, etc.).

func OnSubmit 

func OnSubmit(html render.HTML, action Action) render.HTML

OnSubmit wraps a form element so that submitting it fires the action.

func OpenOnClick added in v0.42.0 

func OpenOnClick(html render.HTML, widget string) render.HTML

OpenOnClick wraps an HTML element so clicking it opens a registered widget surface. Maps to data-cui-open="<widget>". This is the click-to-open trigger, distinct from OpenWidget, which opens a widget only after a successful RPC (data-cui-rpc-open).

func OpenPaneOnClick added in v0.42.0 

func OpenPaneOnClick(html render.HTML, pane string) render.HTML

OpenPaneOnClick wraps an HTML element so clicking it opens the named side pane. Maps to data-hui-pane-open-control="<pane>". Panics unless pane is "secondary" or "tertiary".

func OptimisticUpdate 

func OptimisticUpdate(action Action, idle, success render.HTML) render.HTML

func PaneKey added in v0.44.0 

func PaneKey(html render.HTML, key string) render.HTML

PaneKey labels a pane trigger with the identity of what it opens, the ticket id, the record slug, whatever the pane will show. Maps to data-hui-pane-key="<key>".

It is only read on hosts that opted into URL round-tripping with ui.PaneHostConfig.DeepLinkParam: opening through a keyed trigger writes `?<param>=<pane>:<key>`, so refreshing or sharing that URL reproduces the open pane, and Back closes it. Compose it with OpenPaneOnClick (or a manual data-hui-pane-open-control) on the same element: 

interactive.PaneKey(
    interactive.OpenPaneOnClick(row, "secondary"), ticket.ID)

An unkeyed trigger still opens its pane; it just leaves the URL unchanged, which is the right behavior for a pane whose contents have no addressable identity. On a host without DeepLinkParam the attribute is inert.

The key lands in the URL verbatim, so keep it to record identifiers. The server must look it up rather than trusting it. See ui.PaneDeepLink.

func Reveal 

func Reveal(html render.HTML, animationType string) render.HTML

Reveal wraps an element so it animates in when it enters the viewport. The animationType determines the direction ("fade-up", "fade-in", "slide-left", "slide-right"). Empty → "fade-in". The element renders visible without JS (progressive enhancement); reveal.js adds the hidden state on boot and removes it on intersection.

func SectionMenu 

func SectionMenu(cfg SectionMenuConfig) render.HTML

SectionMenu renders the desktop rail plus the mobile trigger button. Mount the matching drawer once with SectionMenuDrawer.

func SectionMenuDrawer 

func SectionMenuDrawer(cfg SectionMenuConfig) *widget.Builder

SectionMenuDrawer returns the mobile drawer widget for a SectionMenu, a left-edge preset.Drawer (backdrop + click-outside / Escape close + scroll lock + focus trap) carrying the same menu body. Mount it once at startup: 

widget.MountBuilder(router, interactive.SectionMenuDrawer(cfg))

func SetLocal 

func SetLocal(html render.HTML, signalName, value string) render.HTML

SetLocal wraps an HTML element so clicking it sets a signal to a fixed value. No RPC is fired, the update is instant. Panics if signalName is a reserved signal name.

func SignalAttrAllowed added in v0.45.0 

func SignalAttrAllowed(htmlAttr string) bool

SignalAttrAllowed reports whether a signal binding may write the named HTML attribute. Matching is case-insensitive: HTML attribute names are case-insensitive to the parser, so `OnClick` is an event handler no matter how it was cased.

Exported so both emitters of data-cui-signal-attr, BindAttr here and core-ui/store's Slice.BindAttr, enforce the same list instead of growing a second copy.

func SwapPaneOnClick added in v0.86.0 

func SwapPaneOnClick(html render.HTML, pane string) render.HTML

SwapPaneOnClick wraps an HTML element so clicking it opens the named side pane and closes its sibling (one open pane at a time). Maps to data-hui-pane-swap="<pane>". Panics unless pane is "secondary" or "tertiary".

func ToastOnClick added in v0.42.0 

func ToastOnClick(html render.HTML, t Toast) render.HTML

ToastOnClick wraps an HTML element so clicking it fires a toast with the given config. Maps to data-cui-toast="<json>". The JSON is compact (no whitespace) with HTML escaping disabled, matching what call sites hand-write today; render.Attr then escapes the value for the attribute context.

func ToggleLocal 

func ToggleLocal(html render.HTML, signalName string) render.HTML

ToggleLocal wraps an HTML element so clicking it toggles a boolean signal. No RPC is fired. Panics if signalName is a reserved signal name.

Types

type Action 

type Action struct {
	// contains filtered or unexported fields
}

Action describes an RPC call triggered by click or submit.

func Delete 

func Delete(path string) Action

Delete creates a DELETE action. Panics if path does not start with "/".

func Get 

func Get(path string) Action

Get creates a GET action. Panics if path does not start with "/".

func Patch 

func Patch(path string) Action

Patch creates a PATCH action. Panics if path does not start with "/".

func Post 

func Post(path string) Action

Post creates a POST action. Panics if path does not start with "/".

func Put 

func Put(path string) Action

Put creates a PUT action. Panics if path does not start with "/".

func (Action) Attrs added in v0.42.0 

func (a Action) Attrs() map[string]string

Attrs returns the data-cui-* attributes this Action would inject, as a plain map[string]string. It is the same map OnClick/OnSubmit splice into the opening tag, exported so a call site can merge it into an existing attribute map (an render.Tag attrs map or a ui.*Config ExtraAttrs) and let render.Tag's sorted writer place every attribute in the same order a hand-written map would. Prefer this over the wrapper functions whenever byte-identical attribute ordering matters (the wrappers append at the tag's first '>', which can reorder attributes relative to a sorted map render).

The returned map is a fresh copy; mutating it does not affect the Action. It is assignable directly to html.Attrs (a map[string]string alias) and to render.Tag's attrs argument.

func (Action) OnErrorToast added in v0.87.0 

func (a Action) OnErrorToast(title string) Action

OnErrorToast makes a refused or failed RPC visible: on a non-2xx answer (or a network error) the runtime shows an error toast titled title, with the server's JSON "error" message as its body. Without it a non-form RPC that fails ends in silence (a form already reports its refusals beside the fields). An empty title falls back to "Request failed". 

interactive.Delete("/api/orders/42").
    OnSuccess(interactive.Navigate("/orders")).
    OnErrorToast("Could not delete this order.")

Maps to data-cui-rpc-error-toast="title".

func (Action) OnSuccess 

func (a Action) OnSuccess(effects ...Effect) Action

OnSuccess adds effects that run when the RPC returns 2xx.

func (Action) OnSuccessToast added in v0.87.0 

func (a Action) OnSuccessToast(title string) Action

OnSuccessToast shows a success toast titled title on a 2xx answer, before any OnSuccess(Navigate) runs. The toast rides the stack outside the swapped region, so it survives the navigation that follows it — the save that lands the reader back on the record page still says "Saved". 

interactive.Post("/api/orders").
    OnSuccessToast("Order created.").
    OnSuccess(interactive.Navigate("/orders"))

Maps to data-cui-rpc-success-toast="title".

func (Action) OnSuccessToastAction added in v0.87.0 

func (a Action) OnSuccessToastAction(label string, next Action) Action

OnSuccessToastAction puts one action on the OnSuccessToast toast: a button labelled label that runs next when pressed, with next's own toasts and navigation. The toast stays up for ten seconds, paused while hovered or focused, so there is time to press it. The button carries next's RPC wiring and nothing else, so next may not carry a confirm: it panics on one, and on an empty label. The action rides the success toast, so an Action that renders without OnSuccessToast panics too. 

interactive.Delete("/api/invoices/42").
    OnSuccessToast("Invoice deleted").
    OnSuccessToastAction("Undo", interactive.Post("/api/invoices/42/_restore").
        WithBody(`{}`).OnSuccessToast("Invoice restored"))

Maps to data-cui-rpc-success-action='{"label":…,"attrs":{…}}'.

func (Action) WithBody added in v0.42.0 

func (a Action) WithBody(body string) Action

WithBody attaches a static JSON body to the action, the payload sent for a non-form RPC (a button click that isn't inside a <form>). Maps to data-cui-rpc-body="<json>". The runtime sends it verbatim as the request body with Content-Type: application/json.

Panics if json is not valid JSON (json.Valid), so a malformed body fails loudly at build/render time rather than producing a runtime request the server rejects. For form-backed RPCs the runtime serializes the form fields itself, do not call WithBody there.

func (Action) WithConfirm added in v0.12.0 

func (a Action) WithConfirm(message string) Action

WithConfirm gates the action behind a PRE-FLIGHT confirmation. Before the RPC is dispatched, the runtime opens the kit's confirm dialog with message; cancelling aborts the request entirely, so the RPC never fires. Because the gate runs *before* the request, not after it succeeds, it is a property of the Action itself, not an OnSuccess effect. 

interactive.OnClick(saveBtn,
    interactive.Post("/api/items/42/publish").
        WithConfirm("Publish this item to every customer?"),
)

It is WithConfirmDialog(Confirm{Message: message}): reach for that to title the dialog, name the accept button or mark the action destructive. A page with no confirm dialog registered (no kit imported) falls back to window.confirm, so the gate never opens.

Maps to data-cui-confirm="message".

func (Action) WithConfirmDialog added in v0.87.0 

func (a Action) WithConfirmDialog(c Confirm) Action

WithConfirmDialog gates the action behind the kit's confirm dialog, spelled in full. Use it for destructive actions (delete, revoke, drop), where the dialog names what goes and the accept button says so in the danger variant: 

interactive.Delete("/api/items/42").
    WithConfirmDialog(interactive.Confirm{
        Title:   "Delete item?",
        Message: "This cannot be undone.",
        Accept:  "Delete",
        Danger:  true,
    })

Panics on an empty Message: a confirmation that says nothing asks nothing. Maps to data-cui-confirm, data-cui-confirm-title, data-cui-confirm-accept and data-cui-confirm-tone="danger".

type Confirm added in v0.3.2 

type Confirm struct {
	Title   string
	Message string
	Accept  string
	Danger  bool
}

Confirm is what a pre-flight confirmation says: the dialog's title, its message, the accept button's label, and whether accepting destroys something (Danger draws the accept button in the danger variant). Only Message is required; an empty Title or Accept keeps the kit dialog's own ("Are you sure?", "Confirm").

type Effect 

type Effect interface {
	// contains filtered or unexported methods
}

Effect is something that happens after an RPC response.

func AfterDisable added in v0.3.2 

func AfterDisable() Effect

AfterDisable permanently disables the trigger element on 2xx RPC success (sets aria-disabled="true" and, for buttons/inputs, disabled=true). Use with AfterText for "Saved ✓" / "Revealed ✓" feedback. Maps to the boolean attribute data-cui-rpc-after-disable.

func AfterText added in v0.3.2 

func AfterText(text string) Effect

AfterText replaces the trigger element's text content with text on 2xx RPC success. One-shot, subsequent re-clicks are idempotent via data-cui-rpc-after-done. Pair with AfterDisable for "Saved ✓" feedback. Maps to data-cui-rpc-after-text="text".

func CloseWidget 

func CloseWidget() Effect

CloseWidget closes the enclosing widget on RPC success. Maps to data-cui-rpc-close="true". 

func Navigate(path string) Effect

Navigate does an SPA navigation on RPC success. Maps to data-cui-rpc-navigate="path".

func OpenWidget 

func OpenWidget(name string) Effect

OpenWidget opens a named widget when the RPC succeeds. Maps to data-cui-rpc-open="name".

func PushState added in v0.3.2 

func PushState(path string) Effect

PushState applies a URL update via history.pushState after 2xx RPC success without triggering a fetch. The server-supplied X-Gofastr-Push-State header takes precedence over this attribute when both are present. Maps to data-cui-push-state="path".

func ResetForm 

func ResetForm() Effect

ResetForm resets the enclosing form on RPC success. Maps to data-cui-rpc-reset="true".

func ScrollTo added in v0.3.2 

func ScrollTo(selector string) Effect

ScrollTo smooth-scrolls the element matching selector into view on 2xx RPC success. Use to direct the user's eye at newly-inserted content. Maps to data-cui-rpc-scroll-to="selector".

func SetSignal 

func SetSignal(name string) Effect

SetSignal pushes the RPC response into a named client-side signal. Maps to data-cui-rpc-signal="name". Panics if name contains a double quote or is a reserved signal name.

type SectionGroup 

type SectionGroup struct {
	Label   string
	Eyebrow string // optional ordinal/kicker shown before the label (e.g. "01")
	Items   []SectionItem
	// Collapsed starts the group closed in the mobile drawer. A group holding
	// the active item is forced open regardless. (The desktop rail always
	// shows every group expanded.)
	Collapsed bool
}

SectionGroup is a labelled, collapsible cluster of items.

type SectionItem 

type SectionItem struct {
	Label  string
	Href   string
	Active bool // marks the current page (aria-current="page" + .is-active)
}

SectionItem is one navigable link in a SectionMenu group.

type SectionMenuConfig 

type SectionMenuConfig struct {
	// Lead is an optional ungrouped item rendered above the groups
	// (e.g. an "Overview" / index link).
	Lead   *SectionItem
	Groups []SectionGroup
	// AriaLabel names the nav landmark (e.g. "Documentation sections").
	AriaLabel string
	// TriggerLabel is the mobile trigger button's text. Default "Menu".
	TriggerLabel string
	// DrawerName is the widget name shared by the trigger button
	// (data-cui-open) and SectionMenuDrawer. Required for the mobile sheet;
	// must be unique per distinct menu on a site.
	DrawerName string
	// FillColumn is for a menu placed in a column its host already pins
	// at a fixed height (a ui.ContentRow{Sticky: true} nav column): on
	// desktop the rail drops its own sticky offset and viewport cap,
	// fills the column top to bottom and scrolls its overflow there. In
	// normal flow leave it off and the rail sticks on its own.
	FillColumn bool
	Class      string
	ID         string
}

SectionMenuConfig configures a SectionMenu and its drawer.

type Toast added in v0.42.0 

type Toast struct {
	Variant string `json:"variant,omitempty"` // "success" | "warning" | "danger" | "info" | "neutral"; defaults to "info"
	Title   string `json:"title,omitempty"`   // required by the runtime, a toast with no title is dropped
	Body    string `json:"body,omitempty"`    // optional supporting copy
	Stack   string `json:"stack,omitempty"`   // named [data-cui-toast-stack] container; empty → the auto stack
	TTLMs   int    `json:"ttl,omitempty"`     // auto-dismiss delay in ms; 0 → persistent (manual dismiss only)
}

Toast is the config for a click-fired toast notification. Zero fields are omitted from the emitted JSON, so a Toast{Variant, Title, Body, TTLMs} marshals to exactly {"variant":…,"title":…,"body":…,"ttl":…}, the shape call sites hand-write. The feedback module's toast runtime (`headless-feedback` `__gofastr.toast`) reads these keys: variant, title, body, ttl, stack.

type ToastAction added in v0.87.0 

type ToastAction struct {
	Label string            `json:"label"`
	Attrs map[string]string `json:"attrs"`
}

ToastAction is a toast's one button as the runtime reads it: its label and the RPC attributes it carries. Build it with NewToastAction; a server toast carries it as ui.ToastTrigger.Action.

func NewToastAction added in v0.87.0 

func NewToastAction(label string, next Action) *ToastAction

NewToastAction is a toast button labelled label that runs next. The button carries next's RPC wiring and nothing else, so it panics on an empty label, on a next that is no RPC, and on a next carrying any other attribute (a confirm, a signal).

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.