component

type ActionDef ¶

type ActionDef struct {
	Event    string                  // "click", "submit", "input", "change", "keydown", etc.
	Handler  func(*ComponentContext) // the server-side handler (runs in Go)
	Server   bool                    // if true, this action must run on the server
	Debounce int                     // debounce in milliseconds (0 = no debounce)

	// ClientJS is the JavaScript handler body. This is what gets compiled
	// into the actions.js bundle. It receives a `params` object with:
	//   params.value  : input value (for input/change events)
	//   params.*      : any data-param-* attributes from the trigger element
	//
	// Available runtime helpers via `G` (window.__gofastr):
	//   G.getState(key, default)   G.setState(key, value)
	//   G.updateText(sel, text)    G.updateHTML(sel, html)
	//   G.toast(msg)               G.navigate(path)
	//   G.addClass(sel, cls)       G.removeClass(sel, cls)
	//
	// Example: "G.setState('count', G.getState('count', 0) + 1); G.updateText('[data-count]', G.getState('count', 0));"
	ClientJS string
}

ActionDef defines a single event handler within a component.

func On(event string, handler func(*ComponentContext), opts ...ActionOption) ActionDef

type ActionOption ¶

type ActionOption func(*ActionDef)

ActionOption is a functional option for ActionDef.

func WithClientJS(js string) ActionOption

type ActionRegistry ¶

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

ActionRegistry holds all registered actions for a component.

func ExtractActions(c Component) *ActionRegistry

func NewActionRegistry() *ActionRegistry

func (r *ActionRegistry) All() []ActionDef

func (r *ActionRegistry) Get(eventName string) (ActionDef, bool)

func (r *ActionRegistry) HasActions() bool

func (r *ActionRegistry) Register(action ActionDef)

type Component ¶

type Component interface {
	Render() render.HTML
}

Component is the base interface for all UI components. A component describes its appearance via Render.

type ComponentBase ¶

type ComponentBase struct {
	ID    string
	Class string
}

ComponentBase provides common fields for all components. Embed this in your component structs for convenience.

type ComponentContext ¶

type ComponentContext struct {
	// Ctx is the request context the action arrived on. Nil is treated as
	// context.Background(), so a ComponentContext built by hand (tests,
	// in-process invocation) is still safe to use as a context.
	Ctx context.Context

	// Event data
	EventName string
	TargetID  string
	Params    map[string]string

	// State access
	StateGetter func(key string) any
	StateSetter func(key string, value any)
}

ComponentContext holds the execution context for a component action. It provides access to event data and component state.

It also IS a context.Context: an action handler receives this value and nothing else, so anything the handler needs from the request has to be reachable through it. That includes the caller. The server-action endpoint's own contract says "a handler that mutates anything must check authorization itself", and with no request context threaded through, handler.GetUser had nothing to read and that check was unimplementable. Passing it to any context-taking API — a DB call, an authorization lookup, handler.GetUser — now works.

func NewComponentContext(eventName, targetID string, params map[string]string) *ComponentContext

func NewComponentContextFor(ctx context.Context, eventName, targetID string, params map[string]string) *ComponentContext

func (ctx *ComponentContext) Deadline() (time.Time, bool)

func (ctx *ComponentContext) Done() <-chan struct{}

func (ctx *ComponentContext) Err() error

func (ctx *ComponentContext) GetState(key string) any

func (ctx *ComponentContext) Param(name string) string

func (ctx *ComponentContext) ParamInt(name string) (int, error)

func (ctx *ComponentContext) SetState(key string, value any)

func (ctx *ComponentContext) Value(key any) any

type ContextComponent ¶

type ContextComponent interface {
	RenderCtx(ctx context.Context) render.HTML
}

ContextComponent is the optional ctx-aware render interface. Implementations receive the request context and can branch on auth state, locale, or any other request-scoped value that isn't loaded into struct fields by Load(ctx).

The framework prefers RenderCtx over Render when both exist. ContextComponent intentionally does NOT embed Component, a type that only wants the ctx-aware shape can satisfy Component via the ContextOnly{} embed below, avoiding the `func (c) Render() HTML { return c.RenderCtx(context.Background()) }` boilerplate.

type ContextOnly ¶

type ContextOnly struct{}

ContextOnly is a zero-byte embed helper for components that only want to implement RenderCtx. Embedding it provides a Render() satisfying the Component interface; that Render is never called when the type also implements RenderCtx (the framework dispatch prefers RenderCtx and skips Render in that case).

type Home struct {
    component.ContextOnly
    // ... your fields
}
func (h *Home) RenderCtx(ctx context.Context) render.HTML { ... }

No need to write a Render() stub on Home, ContextOnly provides one.

func (ContextOnly) Render() render.HTML

type ErrorBoundary ¶

type ErrorBoundary interface {
	RenderError(err error) render.HTML
}

ErrorBoundary is implemented by components that provide a custom error fallback.

type InteractiveComponent ¶

type InteractiveComponent interface {
	Component
	Actions()
}

InteractiveComponent extends Component with event handling. Components that implement this interface can respond to user events.

type Lifecycle ¶

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

Lifecycle manages mount, update, and unmount hooks.

func NewLifecycle() *Lifecycle

func (l *Lifecycle) HasMountHooks() bool

func (l *Lifecycle) OnMount(fn LifecycleHook)

func (l *Lifecycle) OnUnmount(fn LifecycleHook)

func (l *Lifecycle) OnUpdate(fn LifecycleHook)

func (l *Lifecycle) TriggerMount()

func (l *Lifecycle) TriggerUnmount()

func (l *Lifecycle) TriggerUpdate()

type LifecycleHook ¶

type LifecycleHook func()

LifecycleHook is a function that runs at a specific point in a component's life.

type ServerCall ¶

type ServerCall struct {
	Action string
	Params map[string]string
}

ServerCall represents a call that should be executed on the server.

func Server(action string, params ...string) *ServerCall

type Widget ¶

type Widget struct {
	ID        string          // unique widget ID (used for data-widget attribute)
	Component Component       // the component that renders this widget
	Actions   *ActionRegistry // extracted actions from the component
}

Widget is a self-contained interactive unit that serves as a hydration boundary. Widgets are hydrated incrementally on first user interaction. Components inside a Widget are compiled to JS for client-side execution.

func NewWidget(id string, comp Component) *Widget

func (w *Widget) IsInteractive() bool

func (w *Widget) Render() render.HTML