Go API

Full generated documentation is on pkg.go.dev. This page is the map: what exists, and why.

Package `alacris`

import alacris "github.com/bmartel/alacris-go"

Elements


`E(tag string) *Element`	Start an element. An invalid custom element name is recorded as an error.
`(*Element) Prop(name string, v any)`	Set a component prop, encoded from its Go type. `nil` omits it.
`(*Element) PropRaw(name, value string)`	Set an already-encoded prop value.
`(*Element) Props(map[string]any)`	Several props, applied in sorted key order.
`(*Element) Attr(name string, v any)`	An ordinary HTML attribute; a false bool disappears.
`(*Element) Attrs(templ.Attributes)`	Spread an attribute map.
`(*Element) ID(string)`	Set `id`. Required for anything the live layer patches.
`(*Element) Class(...string)` / `ClassIf(bool, ...string)`	Append class names.
`(*Element) Style(property, value string)`	One sanitized inline declaration.
`(*Element) Var(name, value string)`	A CSS custom property; `--` optional.
`(*Element) Vars(map[string]string)`	Several custom properties.
`(*Element) Apply(VarSet, map[string]string)`	Custom properties checked against a contract.
`(*Element) On(event, action string)`	Forward a CustomEvent to a live action.
`(*Element) Slot(name string, c templ.Component)`	Fill a slot, wrapped in a `<div>`.
`(*Element) SlotAs(tag, name string, c templ.Component)`	Fill a slot with a chosen wrapper.
`(*Element) Children(templ.Component)` / `Text(string)`	Set children explicitly.
`(*Element) Err() error`	The first problem recorded while building.
`(*Element) Render(ctx, w) error`	Implements `templ.Component`.

Encoding


`AttrName(prop string) string`	Prop name to attribute name, matching `define.js` exactly.
`EncodeProp(v any) (string, bool, error)`	The prop encoding rules. `ok` is false when the attribute should be omitted.
`EncodeAttr(v any) (string, bool, bool, error)`	The HTML attribute rules.
`IsZero(v any) bool`	Reflective zero check, used by generated wrappers for named types.
`MaxSafeInteger`	`1<<53 - 1`. Beyond it, encoding is an error.
`ErrUnsafeInteger`, `ErrNonFiniteFloat`	Sentinels for the two numeric refusals.
`ValidTagName(string) error`	The rule `customElements.define` enforces.
`ValidAttrName(string) error`	Rejects names that would change a start tag’s structure.

The runtime


`RuntimeHandler() http.Handler`	Serves the vendored runtime, by file name, at any mount point.
`Assets() fs.FS`	The vendored files, for your own asset pipeline.
`SetCacheHeaders(http.Header, *http.Request, etag string)`	The caching policy: immutable when the URL is versioned, revalidated otherwise.
`RuntimeVersion`	The alacris version vendored in this module.
`UIVersion`	The `@alacris/ui` version vendored in `assets/ui/`.
`TrustedTypesPolicy`	`"alacris"`. Allow it under a trusted-types CSP.
`DefaultBase`	`"/_alacris/"`.
`AssetCore`, `AssetCoreDev`, `AssetStore`, `AssetContext`, `AssetSignal`, `AssetLive`, `AssetUI`, `AssetUITheme`	Served file names.

Page setup


`Config`	Base, Dev, Modules, Imports, Live, Page, Endpoint, Nonce, Version, UI, Theme.
`Scripts(Config) templ.Component`	The import map, your modules, the UI bootstrap, and the live client. Goes in `<head>`.
`(Config) ImportMap() map[string]string`	The specifiers it produces, for a bundler or a test.
`Pending`	The stylesheet that hides elements until they are defined.

Theming


`Vars(names ...string) VarSet`	A contract from full property names. What generated code uses.
`NewVarSet(prefix string, keys ...string) VarSet`	A contract from a prefix and camelCase keys, mirroring `vars()`.
`(VarSet) Name(key) string`, `Names() []string`, `Apply(*Element, map[string]string)`	The contract, and applying it.
`Theme`, `ThemeColors`, `ThemeOverrides`	The `applyTheme` config, set on `Config.Theme`.

Package `ui`

import "github.com/bmartel/alacris-go/ui"

Typed wrappers for every Alacris UI component, generated from the vendored sources. Enable the JavaScript with alacris.Config{UI: true}. See Alacris UI.


`Button`, `TextField`, `Dialog`, …	One constructor per tag.
`Tags` / `Pending()`	For `alacris.Pending`.
`ButtonVars`, …	Per-component theming contracts.
`ButtonElement(sess, id)`	Typed live handles.

Package `gen`

import "github.com/bmartel/alacris-go/gen"

For building the generator into your own tooling. The CLI is the usual way in.


`Load(paths ...string) (*Manifest, error)`	Read components from JS files, directories, or manifests.
`ParseFile`, `ParseDir`, `ParseSource`	The scanner directly.
`Generate(*Manifest, Options) ([]File, error)`	Manifest to Go source.
`WriteFiles(dir string, []File)`	Write, skipping files whose contents did not change.
`Stale(dir string, []File) ([]string, error)`	Generated files this run did not produce.
`ReadManifest`, `WriteManifest`	The JSON form.
`Manifest`, `Component`, `Prop`, `Event`, `Field`, `Slot`, `CSSProp`, `Import`	The manifest schema.
`Options`	Package, Import, Optional, StripPrefix, RelativeTo.
`Kind`	`KindString`, `KindNumber`, `KindBool`, `KindJSON`.

Package `live`

import "github.com/bmartel/alacris-go/live"


`New(opts ...Options) *Server`	A running server. Close it.
`Mount(http.ServeMux, base string, Server)`	Runtime, client and endpoints in one call.
`(Server) NewSession(w, r) Session`	One per page render. Reads or sets the cookie that authorises the browser, so it must run before anything is written.
`(Server) Session(id) (Session, bool)`, `Sessions() []*Session`	Look them up.
`(*Server) Broadcast(...Patch)`	Send to every session.
`(*Server) On(action string, Handler)`	A server-wide handler.
`(*Server) Close()`	End every session and stop the collector.
`On[T](Server, action, func(Ctx, T) error)`	A handler with the detail decoded into `T`.
`OnSession[T](Session, action, func(Ctx, T) error)`	The same, for one page.

Sessions


`(*Session) ID() string`	The page id to put in the page. Not a secret; the capability is the cookie.
`(*Session) Context() context.Context`	Lives as long as the session. The context to render `SetHTML` with, not the request’s, which has finished by the time `OnOpen` runs.
`(*Session) Element(id) Handle`	A handle for patching one element.
`(*Session) Send(...Patch)`	Queue patches. Never blocks, never fails.
`(*Session) Batch(func())`	Coalesce into one frame.
`(Session) OnOpen(func(Session))`	Runs on every attach, including reconnects.
`(*Session) Set(key, value any)` / `Get(key any)`	Per-page state.
`(*Session) On(action string, Handler)`	A handler for this page, beating the server-wide one.
`(*Session) Connected() bool`, `Closed() bool`, `Close()`	Lifecycle.

Handles and patches


`(Handle) Set(name string, v any)`	Write a component prop by its JavaScript name.
`(Handle) SetAttr(name string, v any)`	An attribute; `nil` removes it.
`(Handle) Class(name string, on bool)`	Toggle a class.
`(Handle) Props(map[string]any)`	Several props, one frame.
`(Handle) SetHTML(ctx, slot string, templ.Component) error`	Replace one slot’s children.
`Prop`, `Attr`, `Class`, `HTML`, `Reload`	Patch constructors.
`Patch`, `Op`	The wire shape. See Wire protocol.

Context


`Ctx`	Session, Action, Element, Detail, Request.
`(*Ctx) Bind(v any) error`	Decode the event detail, strictly.
`(*Ctx) Handle() Handle`	The element that emitted the event.
`(*Ctx) Context() context.Context`	The request’s context.
`Options`	TTL, Buffer, MaxDetail, MaxSessions, Heartbeat, AllowOrigin, Logger, Now, and the Cookie* fields.
`Secure`	`SecureAuto`, `SecureAlways`, `SecureNever`: whether the cookie carries Secure.
`DefaultCookieName`	`"alacris_live"`.
`ErrClosed`	Returned when a session has ended.

Package `app`

import "github.com/bmartel/alacris-go/app"

A nested module. Hosts the same http.Handler in an OS webview. Opening a window needs -tags desktop. See Desktop apps.


`Run(Options) error`	Gated loopback, open a window, block until it closes.
`New(Options) App`, `(App) Open()`, `(App) Run()`, `(App) NewWindow()`	The same, split, for a second window.
`Listen(Options) (*Host, error)`	Loopback HTTP only. No display, no desktop tag, no host token.
`(*Host) URL()`, `BootstrapURL(path)`, `Shutdown(ctx)`	Bound origin, first-navigation URL, graceful stop.
`Window`	`SetTitle`, `SetSize`, `SetPosition`, `Center`, `Minimize`, `Maximize`, `Fullscreen`, `Show`, `Hide`, `Focus`, `SetAlwaysOnTop`, `SetDecorations`, `SetBadge`, `Close`, `RegisterShortcut`.
`Menu`, `MenuItem`, `DefaultMenu`, `EditMenu`, `Tray`	Native menu bar and status item. `Do` is a Go callback.
`OpenFile`, `SaveFile`, `SaveAs`, `Message`, `Confirm`	OS dialogs. `ErrCanceled` on dismiss.
`Notify`, `OpenURL`, `RevealInFileManager`, `WriteClipboard`, `ReadClipboard`	OS helpers. No desktop tag.
`DataDir`, `CacheDir`	Identifier-scoped directories.
`Updater`, `ApplyAndRelaunch`, `Relaunch`, `FinishPendingUpdate`	ed25519-signed updates and process replace.
`ErrNoDesktop`, `ErrAlreadyRunning`, `ErrCanceled`, `ErrNoShortcut`