# @gyral/core > Gyral core: Model-View-Intent web components on the web platform, with their own view layer. Source: https://gyral.dev/docs/api/core/ Gyral core: Model-View-Intent web components on the web platform, with their own view layer. ```sh npm install @gyral/core ``` > **Writing code? Start from working code, not from this page.** [Recipes](https://gyral.dev/docs/recipes/) has a task list with filters and a signup form, with their tests; [Forms](https://gyral.dev/docs/forms/) opens with a complete validated form; [Getting started](https://gyral.dev/docs/getting-started/) builds a first component. Adapt the closest example and check it, then look a name up here when you are about to call it. Generated from the package's type declarations. Entry points: [`@gyral/core`](#gyralcore), [`@gyral/core/storage`](#gyralcorestorage), [`@gyral/core/indexeddb`](#gyralcoreindexeddb), [`@gyral/core/vite`](#gyralcorevite), [`@gyral/core/eslint`](#gyralcoreeslint). ## `@gyral/core` ### Functions | Name | Summary | | --- | --- | | [`call`](#core-call) | A command that calls `method` with `args` on the first element matching `selector` inside this component (its shadow root, or its own children in light-DOM mode) once the current update has rendered: | | [`changed`](#core-changed) | Narrows a `StoreChanged` message to one store's typed state, or `undefined`. | | [`child`](#core-child) | Intent parser for a child component's outputs, typed by the child's output union. | | [`command`](#core-command) | Builds a command whose mappers are typed by the driver's input, output and error. | | [`componentsReady`](#core-componentsready) | Resolves once every rendered tag the component loader knows (in the document and in the shadow roots of components it defined) is defined, and the page has settled. | | [`css`](#core-css) | Component CSS: `` css`p { margin-block: ${GAP}px; }` ``. | | [`define`](#core-define) | Compiles a Model-View-Intent spec into a custom element and registers it under `tag`. | | [`defineDriver`](#core-definedriver) | Defines a driver. | | [`defineForm`](#core-defineform) | | | [`defineHook`](#core-definehook) | Defines an element hook: a small behaviour attached to the element it sits on. | | [`defineStore`](#core-definestore) | Defines a store. | | [`each`](#core-each) | A keyed list. | | [`field`](#core-field) | Intent parser for one control (pair with `data-intent-on="input"` for live checks). | | [`fieldErrors`](#core-fielderrors) | Groups issues by field name. | | [`focus`](#core-focus) | A command that focuses the first element matching `selector` inside this component (its shadow root, or its own children in light-DOM mode) once the current update has rendered: | | [`form`](#core-form) | Intent parser for a `

` submission, validated by a schema. | | [`html`](#core-html) | The template tag: `` html`

${s.text}

` ``. | | [`intentsOf`](#core-intentsof) | A component's intent names as a module-level constant, so pure list rows can name intents without passing them through `pick` (rows must be pure). | | [`invalid`](#core-invalid) | Mirrors model errors to native validity: `setCustomValidity` and `aria-invalid`. | | [`keyed`](#core-keyed) | Renders `value`, and replaces it with a fresh copy whenever `key` changes: a form cleared after sending, a CSS animation restarted, a child component reset. | | [`outputs`](#core-outputs) | `emit`, typed by a component's output union (the 4th `define` type parameter), so an output of the wrong shape fails to compile. | | [`provideDrivers`](#core-providedrivers) | Makes `element` a driver provider for every Gyral component below it (including inside shadow roots). | | [`raw`](#core-raw) | Trusted markup from your own code (Markdown output, JSON-LD), parsed in a child hole and re-parsed only when the string changes. | | [`retry`](#core-retry) | The same driver (same name, so substitution by name still works), with `run` retried when it rejects: up to `policy.times` more attempts, after `delayMs` (doubling from it with `backoff: 'exponential'`; a random part of it with `jitter`), and only for failures `retryIf` accepts. | | [`send`](#core-send) | A command that sends `msg` to the component's instance of `store`. | | [`settled`](#core-settled) | Resolves once the page is quiet: every connected Gyral host has rendered its latest state, view-transition updates have run, focus commands and outputs have been delivered, and messages have stopped arriving (a stream's next value, already on its way in a microtask, is waited for; long-lived commands themselves are not). | | [`subscription`](#core-subscription) | A streaming driver over a source Gyral doesn't own. | | [`svg`](#core-svg) | The SVG fragment tag: `` svg`` ``. | #### `call` ```ts function call(selector: string, method: string, ...args: readonly unknown[]): Command; ``` A command that calls `method` with `args` on the first element matching `selector` inside this component (its shadow root, or its own children in light-DOM mode) once the current update has rendered: ```ts Start: (s) => [{ ...s, playing: true }, [call('video', 'play')]] Join: (s, m) => [s, [call('room-stage', 'join', m.room)]] ``` `args` must be plain data (structured-cloneable), so the command stays data a test can compare. A missing element or method, or a method that throws or rejects, is reported through the error channel (ADR 0024); the error's cause says which. #### `changed` ```ts function changed(store: StoreRef, msg: StoreChanged): { readonly state: S; readonly prev: S; } | undefined; ``` Narrows a `StoreChanged` message to one store's typed state, or `undefined`. #### `child` ```ts function child(source: ChildSource, toMsg: (output: O, el: E) => M | undefined): (input: IntentInput) => ReturnType>; ``` Intent parser for a child component's outputs, typed by the child's output union. `el` is the child element, for reading its props (an item id, for example). Pass `() => Child` when the class isn't defined yet, e.g. a component that contains itself; annotate the constant's type so TypeScript accepts the self-reference: ```ts const Folder: GyralElementClass = define()('x-folder', { intent: { Child: child(() => Folder, (out, el) => …) }, … }); ``` #### `command` ```ts function command(driver: Driver, input: I, handlers?: CommandHandlers): Command; ``` Builds a command whose mappers are typed by the driver's input, output and error. Without handlers (or without `onSuccess`) it answers with no message: `command(log, line)` is a `Command`, which fits any `Command`. #### `componentsReady` ```ts function componentsReady(): Promise; ``` Resolves once every rendered tag the component loader knows (in the document and in the shadow roots of components it defined) is defined, and the page has settled. Await it in browser tests and page scripts after the loader has run (page scripts placed after it; in tests, import `virtual:gyral/components` first). #### `css` ```ts function css(strings: TemplateStringsArray, ...values: readonly CssValue[]): StyleSource; ``` Component CSS: `` css`p { margin-block: ${GAP}px; }` ``. Strings and numbers are inserted as written, so values from your own constants need no wrapper. #### `define` ```ts function define(): (tag: string, spec: ComponentSpec) => GyralElementClass; function define(): Definer; ``` Compiles a Model-View-Intent spec into a custom element and registers it under `tag`. Two calls (ADR 0023): the first takes the types, the second the tag and spec, from whose `intent` keys it infers the component's intent names. ```ts define()('x-counter', { init, intent: { Increment: … }, update, view }) ``` With no type arguments, `define()('x-badge', spec)` infers the state, messages, props and intent names from the spec. Guide: https://gyral.dev/docs/components/ #### `defineDriver` ```ts function defineDriver(spec: Driver | DriverToken | string): Driver; ``` Defines a driver. Given an implementation (`run`), it returns it as is, so literals infer `I`, `O` and `E`. Given only a name, it returns a typed **token**: commands built from it are typed, and it runs only when a provider (`provideDrivers`) or `el.drivers` supplies a driver of that name. A command whose token nothing provides fails with G0043, naming the driver. #### `defineForm` ```ts function defineForm(schema: Schema, options?: FormOptions): FormDefinition; ``` #### `defineHook` ```ts function defineHook(spec: HookSpec ): (...args: A) => HookResult ; ``` Defines an element hook: a small behaviour attached to the element it sits on. #### `defineStore` ```ts function defineStore(name: string, spec: StoreSpec): Store; ``` Defines a store. `name` keys it in registries, seeds and overrides, so keep it unique. #### `each` ```ts function each(items: readonly T[], key: (item: T) => string | number, row: (item: T) => ChildValue): ListResult; function each(items: readonly T[], key: (item: T) => string | number, row: (item: T, picked: P) => ChildValue, pick: (item: T) => P): ListResult; ``` A keyed list. `key` must give each item a unique string or number; `row` must depend only on its arguments: a row re-renders only when its item object or its `pick` result changes. #### `field` ```ts function field(schema: Schema, toMsg: (value: Out) => M | undefined): (input: IntentInput) => ReturnType>; ``` Intent parser for one control (pair with `data-intent-on="input"` for live checks). Validates `checked` for checkboxes and radios, otherwise `value`. #### `fieldErrors` ```ts function fieldErrors(issues: readonly FieldIssue[]): Readonly>; ``` Groups issues by field name. Call it in the `IntentRejected` reducer and keep the result in state: `invalid()` re-applies an error only when it gets a new array. #### `focus` ```ts function focus(selector: string, options?: FocusOptions): Command; ``` A command that focuses the first element matching `selector` inside this component (its shadow root, or its own children in light-DOM mode) once the current update has rendered: ```ts NextPage: (s, m) => [{ ...s, page: m.page }, [focus('h2', { preventScroll: true })]] ``` Non-focusable targets (a heading) need `tabindex="-1"` in the view. #### `form` ```ts function form(definition: FormDefinition | Schema, toMsg: (data: Out, formData: FormData) => M | undefined): (input: IntentInput) => ReturnType>; ``` Intent parser for a `` submission, validated by a schema. `toMsg` also gets the raw `FormData`, for sending the submission to the server (`submitForm` in `@gyral/http`) after it passed client-side validation. #### `html` ```ts const html: (strings: TemplateStringsArray, ...values: unknown[]) => TemplateResult ``` The template tag: `` html`
${s.text}
` ``. #### `intentsOf` ```ts function intentsOf(): IntentNames>; ``` A component's intent names as a module-level constant, so pure list rows can name intents without passing them through `pick` (rows must be pure). The same object the view gets as `i`, typed by the component's class (ADR 0023). A row that names intents this way needs an explicit return type, or the row, the view and the class infer each other in a circle: ```ts const i = intentsOf(); const Row = (t: Todo): TemplateResult => html``; ``` #### `invalid` ```ts const invalid: (errors?: Errors) => HookResult<[errors?: Errors]> ``` Mirrors model errors to native validity: `setCustomValidity` and `aria-invalid`. ```ts ``` The custom error clears when the control fires `input` or `change` (the user edited it), when the bound errors become `undefined` or empty (the model cleared them), or when a submit finds the error stale (the value changed without an event, e.g. set from code): then the error is dropped and the form is submitted again once. An error is applied again only when a new value arrives (keep `fieldErrors()` results in state): `client` runs only when the errors change. #### `keyed` ```ts function keyed(key: string | number, value: ChildValue): ListResult; ``` Renders `value`, and replaces it with a fresh copy whenever `key` changes: a form cleared after sending, a CSS animation restarted, a child component reset. #### `outputs` ```ts function outputs(): (output: O) => Command; ``` `emit`, typed by a component's output union (the 4th `define` type parameter), so an output of the wrong shape fails to compile. A module-level constant, like `intentsOf()`: ```ts type Out = { readonly _tag: 'Picked'; readonly id: number }; const emit = outputs(); // in update: Pick: (s, m) => [s, [emit({ _tag: 'Picked', id: m.id })]] ``` Costs nothing at run time: it returns `emit` itself. #### `provideDrivers` ```ts function provideDrivers(element: Element, drivers: DriverOverrides): () => void; ``` Makes `element` a driver provider for every Gyral component below it (including inside shadow roots). Returns a function that removes the overrides. Use it on a test container or an app root; a `` element with a `.drivers` property works the same way. #### `raw` ```ts function raw(html: string): RawResult; ``` Trusted markup from your own code (Markdown output, JSON-LD), parsed in a child hole and re-parsed only when the string changes. Never pass user input. #### `retry` ```ts function retry(driver: Driver, policy: RetryPolicy): Driver; ``` The same driver (same name, so substitution by name still works), with `run` retried when it rejects: up to `policy.times` more attempts, after `delayMs` (doubling from it with `backoff: 'exponential'`; a random part of it with `jitter`), and only for failures `retryIf` accepts. An abort (the command switched away, the component disconnected) ends it at once and is never retried. Wrap where the driver is chosen: `provideDrivers` at app setup, `el.drivers`, or a test fake. ```ts const api = retry(makeHttpDriver({ baseUrl: '/api', timeoutMs: 8000 }), { times: 3, delayMs: 300, backoff: 'exponential', jitter: true, retryIf: retryableHttpError, }); const feed = retry(subscription('feed', connect), { times: Infinity, delayMs: 1000 }); ``` #### `send` ```ts function send(store: Store, msg: NoInfer): Command; ``` A command that sends `msg` to the component's instance of `store`. Writes are commands. #### `settled` ```ts function settled(): Promise; ``` Resolves once the page is quiet: every connected Gyral host has rendered its latest state, view-transition updates have run, focus commands and outputs have been delivered, and messages have stopped arriving (a stream's next value, already on its way in a microtask, is waited for; long-lived commands themselves are not). Rejects with the loop guard's error when rendering never settles in development (components feeding each other). ```ts el.send({ _tag: 'Increment' }); await settled(); ``` #### `subscription` ```ts function subscription(name: string, subscribe: (emit: (value: O) => void, ctx: SubscriptionContext) => Unsubscribe, options?: SubscriptionOptions): Driver; ``` A streaming driver over a source Gyral doesn't own. `subscribe` starts listening, calls `emit` with each value (it may emit the current value at once) and returns how to stop (a function, or an object with `unsubscribe()`). The subscription lasts while the command runs; aborting it (lane `switch`, disconnect) releases the source, and emits after that are ignored. Substitute it by `name` in tests. ```ts const cart = subscription('cart', (emit) => { emit(reduxStore.getState()); return reduxStore.subscribe(() => emit(reduxStore.getState())); }); // subscriptions: () => [command(cart, undefined, { onSuccess: (c) => ({ _tag: 'Cart', c }) })] ``` #### `svg` ```ts const svg: (strings: TemplateStringsArray, ...values: unknown[]) => TemplateResult ``` The SVG fragment tag: `` svg`` ``. Its top level is SVG content, so it renders only inside an ``, or `` (Open Graph uses `property`). | | [`HookAttributes`](#core-hookattributes) | Attributes a hook's server half adds to the start tag (`true`: present, no value). | | [`HookResult`](#core-hookresult) | What a hook returns in a template: ``. | | [`HookSpec`](#core-hookspec) | | | [`Hydrated`](#core-hydrated) | Framework message: the component is live in the browser (ADR 0012 addendum). | | [`HydrateStrategy`](#core-hydratestrategy) | When a server-rendered component hydrates. | | [`IntentInput`](#core-intentinput) | What the intent layer sees when an element's intent fires. | | [`IntentNames`](#core-intentnames) | A component's intent names, the keys of its `intent` object, as the view's `i` and as `intentsOf()`, so `data-intent=${i.Increment}` is checked (ADR 0023). | | [`IntentParser`](#core-intentparser) | Parses a platform event into one message variant, `IntentRejected`, or `undefined` to decline it: a synchronous `undefined` passes the event to the next intent outward for the same event. | | [`IntentRejected`](#core-intentrejected) | Framework message: an intent's input failed schema validation (ADR 0008). | | [`Intents`](#core-intents) | Intent parsers keyed by intent name (ADR 0001, ADR 0023). | | [`JsonValue`](#core-jsonvalue) | A JSON value: what a JSON-LD block holds. | | [`ListResult`](#core-listresult) | A keyed list for a child hole: what `each(…)` returns. | | [`Next`](#core-next) | What a reducer (or `init`) returns: new state, optionally with commands to run. | | [`OutputEvent`](#core-outputevent) | The `gyral-output` event a child dispatches on its host for each output (ADR 0010): `detail` is the output. | | [`OutputsOf`](#core-outputsof) | The output union of a `define()` class: `OutputsOf`. | | [`OutputSource`](#core-outputsource) | Anything `child()` can read an output type from: a `define()` class. | | [`ParserCtx`](#core-parserctx) | What an intent parser gets besides the input: the reducers' context plus the component's current state, read-only. | | [`ParseResult`](#core-parseresult) | What an intent parser returns: a message, `IntentRejected` (invalid input), or `undefined` to decline the event. | | [`ParserFor`](#core-parserfor) | The parser for intent name `K` (ADR 0023): a name that is a message tag parses into that variant; any other name is an intent of its own whose parser may produce any message. | | [`Prop`](#core-prop) | One declared prop: what a builder returns. | | [`PropDeclarations`](#core-propdeclarations) | The prop builders for props type `P`: one `prop.*` builder per key. | | [`PropGuard`](#core-propguard) | A plain type guard, accepted by `prop.value` and `prop.json` in place of a schema. | | [`PropKind`](#core-propkind) | | | [`PropsChanged`](#core-propschanged) | Framework message: declared props changed after the first render (ADR 0007). | | [`PropsOf`](#core-propsof) | The props type of a table of builders: `PropsOf`. | | [`RawResult`](#core-rawresult) | Trusted markup for a child hole: what `raw(html)` returns. | | [`Reducer`](#core-reducer) | One entry of `update`: takes the state, one message (`Msg`, a variant of `M` or a framework message) and the read-only context, and returns the next state, optionally with commands that produce more `M` messages. | | [`RetryPolicy`](#core-retrypolicy) | How `retry(driver, policy)` retries a rejected run (retry.ts). | | [`SeedCheck`](#core-seedcheck) | The result of checking a seed against a store's schema. | | [`ShadowOption`](#core-shadowoption) | `spec.shadow`: `true` (the default) or an object for a shadow root, `false` for light DOM. | | [`StandardSchemaV1`](#core-standardschemav1) | The Standard Schema interface. | | [`Stateless`](#core-stateless) | State of a component that keeps none (a pure view of its props). | | [`Store`](#core-store) | | | [`StoreChanged`](#core-storechanged) | Framework message: a store this component reads changed (ADR 0013). | | [`StoreInstance`](#core-storeinstance) | A live store: one per page on the client, one per request on the server, one per test. | | [`StoreOverrides`](#core-storeoverrides) | Store instances substituted by store name (tests, islands). | | [`StoreReader`](#core-storereader) | Reads a declared store's current state, typed by the store (ADR 0013). | | [`StoreRef`](#core-storeref) | What `ctx.read()` accepts: anything that names a store and carries its state type. | | [`StoreResolver`](#core-storeresolver) | Finds a store's instance in a scope (a registry). | | [`StoreSpec`](#core-storespec) | | | [`StoreUpdate`](#core-storeupdate) | One pure reducer per message tag, like a component's `update` but without context. | | [`Styles`](#core-styles) | What `spec.styles` accepts: `css` values, plain CSS strings (e.g. | | [`StyleSource`](#core-stylesource) | What `css` returns: CSS text, mapped to one shared `CSSStyleSheet` in the browser. | | [`SubscriptionContext`](#core-subscriptioncontext) | | | [`SubscriptionOptions`](#core-subscriptionoptions) | Driver options a subscription may set. | | [`Tagged`](#core-tagged) | Every message is a tagged object; the tag is also the intent name used in markup. | | [`TemplateResult`](#core-templateresult) | What `html` returns: a template plus this render's values. | | [`Unsubscribe`](#core-unsubscribe) | How to stop listening: a function, or an object with `unsubscribe()` (RxJS, XState). | | [`Update`](#core-update) | One pure reducer per message tag (exhaustive by construction), plus optional reducers for framework messages. | | [`Variant`](#core-variant) | The member of message union `M` whose tag is `K`: `Variant`. | #### `AnyDriver` ```ts type AnyDriver = Driver; ``` Any driver, with its input type erased. Every `Driver` (from `defineDriver`, `subscription`, a test fake) is assignable to it as is: no cast. #### `AnyStore` ```ts interface AnyStore { readonly name: string; instance(initial?: never): AnyStoreInstance; checkSeed(seed: unknown): SeedCheck; } ``` Any store, with its types erased (for declarations and registries). #### `AnyStoreInstance` ```ts interface AnyStoreInstance { readonly store: AnyStore; readonly state: unknown; send(msg: never): void; subscribe(listener: (state: unknown, prev: unknown) => void): () => void; dispose(): void; /** * Called by the registry that holds this instance, so the store's `send(other, msg)` * commands reach `other`'s instance in the same scope. */ bindScope?(resolve: StoreResolver): void; } ``` Any store instance, with its types erased. #### `CallInput` ```ts interface CallInput { readonly selector: string; readonly method: string; readonly args: readonly unknown[]; } ``` The input of a `call()` command. #### `ChildSource` ```ts type ChildSource = OutputSource | (() => OutputSource); ``` A child class, or a function returning it (for recursive or later-defined components). #### `ChildValue` ```ts type ChildValue = string | number | boolean | null | undefined | typeof nothing | TemplateResult | ListResult | RawResult | readonly ChildValue[]; ``` Everything a child hole accepts. #### `Command` ```ts interface Command { readonly driver: AnyDriver; readonly input: unknown; /** Concurrency lane. Default: the driver's name. */ readonly key?: string; readonly concurrency?: Concurrency; readonly onSuccess: (output: unknown) => M | undefined; /** If omitted, a failure is reported to the error channel (ADR 0024, G0041). */ readonly onFailure?: (error: unknown) => M | undefined; } ``` A side effect described as data, plus pure mappers from its outcome to messages. Commands that answer with no message (`focus()`, `call()`, `navigate()`) are `Command`, which fits wherever a `Command` is expected: no type argument needed. #### `CommandHandlers` ```ts interface CommandHandlers { readonly onSuccess?: (output: O) => MS | undefined; readonly onFailure?: (error: E) => MF | undefined; readonly key?: string; readonly concurrency?: Concurrency; } ``` How a command's outcome becomes a message. Every field is optional: without `onSuccess` the command answers with nothing (`Command`); without `onFailure` a failure is reported to the error channel (ADR 0024). #### `CommandInfo` ```ts interface CommandInfo { /** The command, e.g. `--clear`. */ readonly command: string; /** The invoker (the button) that sent it. */ readonly source: Element | undefined; } ``` #### `ComponentSpec` ```ts type ComponentSpec = SpecBody & IntentField & UpdateField & InitField; ``` A component spec. `N` is the component's intent names, the keys of `intent` (ADR 0023). #### `Concurrency` ```ts type Concurrency = 'merge' | 'switch' | 'exhaust' | 'queue'; ``` How commands in the same lane interact. See ADR 0006 for the table. #### `CssValue` ```ts type CssValue = string | number | StyleSource; ``` A `css` interpolation: inserted as written (another `css` value inserts its text). #### `Ctx` ```ts interface Ctx
{ /** Props from above. */ readonly props: P; /** Stores from the side: `read(cart).lines`. The store must be in `spec.stores`. */ readonly read: StoreReader; } ``` Read-only context handed to every reducer and to the view (ADR 0007, 0013). #### `Definer` ```ts type Definer = (tag: string, spec: ComponentSpec) => GyralElementClass; ``` The second call of `define()`: takes the tag and the spec, infers the intent names. #### `Driver` ```ts interface Driver { readonly name: string; readonly run: (input: I, ctx: DriverContext) => O | Promise; /** Default policy for this driver's commands. Default `'merge'`. */ readonly concurrency?: Concurrency; /** Turns a thrown or rejected value into this driver's typed error. */ readonly toError?: (cause: unknown) => E; } ``` Performs one kind of side effect. A plain object: easy to fake in tests. #### `DriverContext` ```ts interface DriverContext { /** Aborts when the command is switched away or its component disconnects. */ readonly signal: AbortSignal; /** * Delivers an extra result while the command runs (streaming drivers: routers, timers, * sockets). Each value goes through the command's `onSuccess`. Ignored once the command * has settled or been aborted. A streaming `run` usually never resolves; abort ends it. */ readonly emit: (output: O) => void; } ``` #### `DriverOverrides` ```ts type DriverOverrides = Readonly>; ``` Drivers substituted by name (test fakes, configured instances): `el.drivers`, `provideDrivers`. Annotate a driver map with this type (or `Record`), not `Record>`, which rejects drivers with a typed input. #### `DriverToken` ```ts interface DriverToken { readonly name: string; readonly concurrency?: Concurrency; readonly toError?: (cause: unknown) => E; } ``` A driver with no implementation of its own (`defineDriver('session')`): commands built from it are typed by `I`, `O` and `E`, and it runs only when `provideDrivers` or `el.drivers` supplies a driver of that name (ADR 0006 addendum "Driver tokens"). #### `Errored` ```ts interface Errored { readonly _tag: 'Errored'; readonly phase: 'update' | 'parse' | 'command'; readonly error: GyralError; } ``` Framework message (ADR 0024): an update, an intent parser or a command of this component failed. The failure was reported (`reportError`, or claimed by an ancestor's boundary) and changed nothing; reduce it to show an error state or to reset. A failure while reducing `Errored` is reported and not sent again. #### `ErrorPhase` ```ts type ErrorPhase = 'init' | 'update' | 'view' | 'parse' | 'command' | 'hook' | 'store' | 'subscribe'; ``` Where a failure happened. #### `FieldIssue` ```ts interface FieldIssue { readonly path: string; readonly message: string; } ``` One validation problem. `path` is dot-joined and matches the field's `name`. #### `FieldName` ```ts type FieldName = In extends Readonly> ? keyof In & string : string; ``` The definition's field names, when its input is an object; otherwise any string. #### `FocusOptions` ```ts interface FocusOptions { /** Don't scroll the element into view (default `false`: the browser scrolls if needed). */ readonly preventScroll?: boolean; /** Also select the text of an input or textarea. */ readonly select?: boolean; /** * If nothing matches after this render, keep the request and focus the target as soon as a * later render of this component produces it; a newer `focus()` from the component replaces * it, and after one second it gives up with the usual warning. `settled()` doesn't wait for it. */ readonly wait?: boolean; } ``` #### `FormAssociation` ```ts interface FormAssociation { readonly value: (state: S, ctx: Ctx
) => FormControlValue; readonly state?: (state: S, ctx: Ctx
) => FormControlValue; readonly validity?: (state: S, ctx: Ctx
) => FormControlValidity | undefined; } ``` Pure model projections applied by Gyral to the host's ElementInternals (ADR 0008). #### `FormControlValidity` ```ts interface FormControlValidity { readonly flags: ValidityStateFlags; readonly message: string; readonly anchor?: string; } ``` Native constraint flags and a validation bubble anchor in the component's render root. #### `FormControlValue` ```ts type FormControlValue = string | File | FormData | null; ``` A native submitted value, or null to omit this component from the submission. #### `FormDefinition` ```ts interface FormDefinition { readonly _tag: 'FormDefinition'; readonly schema: Schema; /** The fields listed as secret (names containing `password`, `passcode`, `csrf` or `xsrf` are secret too). */ readonly secret: readonly string[]; /** * Validates submitted form data exactly as `form()` does; the server's `formAction` uses it, * so both paths produce the same `IntentRejected` (`intent` defaults to `''`). */ readonly validate: (data: FormData, intent?: string) => FormResult> | Promise>>; /** The submitted text values without secrets: what a re-rendered form may show again. */ readonly values: (data: FormData) => FormValues; } ``` A form's schema, shared by the client component and (with `@gyral/ssr`) the server route. #### `FormDisabled` ```ts interface FormDisabled { readonly _tag: 'FormDisabled'; readonly disabled: boolean; } ``` Framework message: the host or its fieldset changed the effective disabled state. #### `FormFields` ```ts type FormFields = Readonly>; ``` Submitted text values of a form (Files are dropped: they can't be re-filled). #### `FormOptions` ```ts interface FormOptions { /** * Fields whose submitted values are never sent back: not in `IntentRejected.values`, not in * `values()`, not in the devtools timeline. Any posted field name may be listed, including * fields outside the schema. Names containing `password`, `passcode`, `csrf` or `xsrf` are * secret without being listed (the browser never restores a password field either, and a * CSRF token must come fresh from the server, not from the echo). */ readonly secret?: readonly (FieldName | (string & {}))[]; } ``` #### `FormReset` ```ts interface FormReset { readonly _tag: 'FormReset'; } ``` Framework message: the owning native form was reset. #### `FormResult` ```ts type FormResult = { readonly ok: true; readonly data: T; } | { readonly ok: false; readonly rejected: IntentRejected; }; ``` #### `FormStateRestore` ```ts interface FormStateRestore { readonly _tag: 'FormStateRestore'; readonly state: FormControlValue; readonly mode: 'restore' | 'autocomplete'; } ``` Framework message: native session restoration or autofill supplied control state. #### `FormValue` ```ts type FormValue = FormDataEntryValue | readonly FormDataEntryValue[]; ``` #### `FormValues` ```ts type FormValues = In extends Readonly> ? { readonly [K in keyof In & string]?: string | readonly string[]; } : FormFields; ``` A form's submitted text values, keyed by the definition's fields, for re-rendering the form with what was typed (sticky fields). The same shape as `IntentRejected.values`: repeated names (and `name[]`) are arrays; `File`s and secret fields are left out. #### `GyralElement` ```ts interface GyralElement extends HTMLElement { /** Current model state. */ readonly state: S; /** Feeds a message through `update`, as if an intent had produced it. */ send(msg: M): void; /** Per-instance driver substitutions by name (test fakes). Checked before the spec's. */ drivers: DriverOverrides; /** * Per-instance store instances by store name (tests, islands). Checked before the nearest * `` provider and the document default (ADR 0013). */ stores: StoreOverrides; /** * Messages applied through `update` right after `init`, before the first render. The server * uses it to render a rejected form with the same reducer as the JS path (ADR 0008). Ignored * when the element resumes from a hydration seed (the seed already contains their effect). */ initialMessages: readonly Tagged[]; } ``` The custom element `define()` produces: a plain `HTMLElement`. Tests wait for rendering with `settled()`. #### `GyralElementClass` ```ts interface GyralElementClass { /** Instances expose their declared props as settable properties. */ new (): GyralElement & { -readonly [K in keyof P]: P[K]; }; readonly spec: ComponentSpec; readonly tagName: string; /** Native custom-element registration flag, true when the spec opts into forms. */ readonly formAssociated?: boolean; /** Type-only: the outputs this component emits (read by `child()`). */ readonly outputs?: O; /** Type-only: the component's intent names, the keys of `intent` (read by `intentsOf()`). */ readonly intentNames?: N; } ``` #### `Head` ```ts interface Head { readonly title: string; readonly description?: string; /** Absolute URL, usually `new URL(match.path, origin).href` (ADR 0009 "Canonical paths"). */ readonly canonical?: string; /** ``, e.g. `'noindex, follow'`. */ readonly robots?: string; /** Later entries win over earlier ones with the same name or property. */ readonly meta?: readonly HeadMeta[]; /** Later entries win over earlier ones with the same attributes other than `href`. */ readonly links?: readonly HeadLink[]; /** Structured data, each written as one `