combobox

Documentation

Overview

Package combobox implements the WAI-ARIA Combobox 1.2 pattern as a server-rendered input that's bound to a debounced RPC dropdown.

The Go-side renders the label, input, and an empty listbox. The runtime (core-ui/runtime/runtime.js) handles:

• Debounced input events (via existing data-fui-rpc-trigger="input"
• data-fui-rpc-debounce-ms="N") firing the search RPC.
• Keyboard navigation: ArrowUp/Down/Home/End move highlight, Enter selects, Esc closes (twice clears input), Tab closes.
• aria-expanded + aria-activedescendant updates on every move.
• Click-to-pick on options.
• Outside-click closes.
• Auto-open on focus when the listbox already has options.

Server contract for the search RPC handler:

• Request body: form-encoded with `query=<text>` (whatever the input's `name` attribute is — default "q").
• Response: `<li role="option" id="...">label</li>` fragments, swapped into the listbox via data-fui-rpc-signal. Each option SHOULD carry a `data-value` attribute that becomes the input's selected value on pick — if absent, the option's textContent is used.
• To indicate "no results", emit a single `<li role="option" aria-disabled="true">No results</li>` — the keyboard nav skips disabled options.

Index

• Variables
• func Render(cfg Config) render.HTML
• type Config

Variables

var Style = registry.RegisterStyle("combobox", styleFn)

Style is the registered stylesheet handle. CSS auto-loads on first appearance via the runtime's data-fui-comp scanner. Apps override the visual defaults via theme tokens.

Functions

func Render

func Render(cfg Config) render.HTML

Render renders the combobox shell: label, input with combobox semantics, and the empty listbox the search RPC populates.

Types

type Config

type Config struct {
	// ID is the input element id; the listbox id is `<ID>-listbox`.
	// Required.
	ID string

	// Name is the form-submit name on the input. Required.
	Name string

	// Label is the visible <label> text associated with the input.
	// Required.
	Label string

	// RPCPath is the search endpoint. Required. POST with form-encoded
	// body whose first field is `<Name>=<query>`.
	RPCPath string

	// SignalName is the data-fui-rpc-signal value used to swap the
	// listbox HTML on every search response. Required.
	SignalName string

	// DebounceMs is the input debounce window. Default 250.
	DebounceMs int

	// Placeholder is the input placeholder text.
	Placeholder string

	// EmptyHTML is HTML rendered into the listbox at first paint when
	// no options are server-rendered. Pass an empty string to start
	// with an empty hidden listbox (the typical case — the listbox
	// auto-opens once the user types and the server returns options).
	EmptyHTML string

	// LabelHidden visually hides the label (still announced to AT).
	// Use when the surrounding context makes the label redundant.
	LabelHidden bool

	// Class is added to the wrapper's class list.
	Class string
}

Config configures a combobox.