widget

type BootstrapMode string

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

type Definition struct {
	Name      string
	Position  Position
	Bootstrap BootstrapMode
	Slots     []Slot
	Signals   map[string]SignalSource
	SSE       []SSEBinding
	RPCs      []RPCEndpoint

	// Skeleton is the host's chrome wrapper. If nil, the framework
	// uses a sensible default for the chosen Position (FloatingPanel
	// for corners, Modal for Center, etc.). Most hosts leave this
	// nil and use a preset.
	Skeleton func(slots map[string]render.HTML) render.HTML

	// ExtraCSS is host-supplied CSS appended after the framework's
	// chrome rules in the per-widget stylesheet (/<StylePath>). Use
	// for content styling (slot innards, host-specific class names)
	// that doesn't fit in the page theme. Generate it through
	// core-ui/style.NewStyleSheet for token consistency, or pass an
	// already-resolved CSS string.
	ExtraCSS func() string

	// Modal flags
	Backdrop            bool // dim the page behind the widget
	CloseOnEscape       bool // ESC closes the widget
	CloseOnClickOutside bool

	// Role is the ARIA role applied to the widget root element.
	// Defaults to "dialog" for backdrop'd widgets and is left empty
	// for plain panels / floating surfaces. Use "alertdialog" for
	// widgets that demand the user's immediate attention.
	Role string

	// LabelledBy is the id of an element (typically a heading) inside
	// the slot HTML that names this widget for screen readers. Becomes
	// aria-labelledby on the widget root. The host is responsible for
	// putting a matching id on the element.
	LabelledBy string

	// DescribedBy is the id of an element inside the slot HTML that
	// provides supplementary description for the widget. Becomes
	// aria-describedby on the widget root.
	DescribedBy string

	// Hidden=true means the widget is registered but NOT auto-mounted
	// on page load. A button with data-fui-open="<name>" calls
	// __gofastr.openWidget(name) to mount it on demand. Use for
	// modals + drawers that should appear in response to user action.
	Hidden bool

	// DeepLinkKey is the URL query parameter that controls open state
	// for this widget — e.g. "modal". When the request URL contains
	// `?<DeepLinkKey>=<DeepLinkValue>`, the SSR layer renders the
	// widget open at first paint AND the runtime mirrors open/close to
	// pushState so refresh/share/back-button all stay consistent.
	//
	// Empty (the default) disables deep-linking — the widget remains
	// purely click-driven via data-fui-open.
	//
	// Only meaningful for Hidden widgets (modal / drawer). Toasts and
	// dropdowns intentionally do NOT support deep links.
	DeepLinkKey string
	// DeepLinkValue is the literal value of DeepLinkKey that opens
	// THIS widget. Multiple widgets can share the same DeepLinkKey
	// ("modal") as long as their DeepLinkValue is distinct
	// ("user-edit", "confirm-delete").
	DeepLinkValue string
	// DeepLinkParams lists additional query parameters whose values
	// should be mirrored into named signals when the widget opens via
	// deep link. e.g. ["user_id"] with URL `?modal=user-edit&user_id=42`
	// seeds signal "user_id"="42" before the slot renders.
	DeepLinkParams []string

	// Routes scopes the widget to specific request paths. When non-
	// empty, the SSR layer and the runtime catalog only expose this
	// widget on pages whose path is accepted by at least one matcher.
	// Empty (the default) means "available on every page" — the
	// behaviour before per-page scoping shipped.
	//
	// Constructed via the Builder methods .Pages, .PagesPrefix,
	// .PagesMatch (or manually for advanced cases).
	Routes []RouteMatcher

	// DragDismiss enables pointer-driven drag-to-dismiss for bottom-edge
	// widgets. The chrome renders a visible drag-handle bar at the top
	// of the panel; the runtime listens for pointerdown/move/up on the
	// handle (and on the panel itself) and closes the widget when the
	// user drags past a distance + velocity threshold. Snaps back to
	// the resting position when released earlier.
	//
	// Only meaningful for Bottom (and bottom-edge) positions today;
	// silently no-op elsewhere.
	DragDismiss bool

	// Asset path overrides. Default routes are derived from Name.
	BootstrapPath string // default: /core-ui/widget/<name>/bootstrap.js
	StylePath     string // default: /core-ui/widget/<name>/style.css
	StatePath     string // default: /core-ui/widget/<name>/state
}

type Position string

type RPCEndpoint struct {
	Method         string // "POST" by default
	Path           string
	Handler        http.Handler
	ResponseSignal string
}

type RouteMatcher func(path string) bool

type SSEBinding struct {
	Path   string `json:"path"`   // e.g. "/.kiln/events"
	Event  string `json:"event"`  // e.g. "world_edit"
	Signal string `json:"signal"` // e.g. "page"

	// Refetch=true tells the runtime to re-fetch /state and apply the
	// signal's fresh value instead of using the SSE event's payload.
	// Use when the signal source is server-rendered (HTML, derived
	// state) and the SSE event is just a "something changed" trigger.
	Refetch bool `json:"refetch,omitempty"`

	// Reload=true tells the runtime to do a full page reload on this
	// event. Useful for events that change which page is rendered at
	// the current URL (kiln add_page / delete_page / add_route /
	// delete_route). Signal is ignored when Reload is set.
	Reload bool `json:"reload,omitempty"`

	// Match optionally filters the binding to events whose JSON
	// payload contains all the listed key=value pairs. Useful when
	// the SSE channel multiplexes by event type (e.g. "world_edit")
	// and the host wants to react only to specific ops.
	Match map[string]string `json:"match,omitempty"`
}

type SignalFunc func() (any, error)

type SignalSource interface {
	Read() (any, error)
}

type Slot struct {
	Name      string
	Component component.Component
}