@gyral/core 0.0.0 → 0.1.0

package/dist/drivers-scope.js

@@ -0,0 +1,48 @@
+// Tree-scoped driver overrides (gyral-czi.35, ADR 0006 addendum): which driver a command uses.
+// Resolution: el.drivers → nearest driver provider (across shadow roots) → spec.drivers →
+// the command's own driver. Mirrors <gyral-stores> (ADR 0013) for stores.
+import { isServer } from 'lit';
+const onServer = isServer;
+/** Provider element name: `<gyral-drivers .drivers=${{ http: fake }}>…</gyral-drivers>`. */
+export const DRIVERS_ELEMENT = 'gyral-drivers';
+// Elements registered with provideDrivers() (any element can act as a provider).
+const provided = new WeakMap();
+/**
+ * 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 `<gyral-drivers>` element with a `.drivers` property works the same way.
+ */
+export function provideDrivers(element, drivers) {
+    provided.set(element, drivers);
+    return () => {
+        if (provided.get(element) === drivers)
+            provided.delete(element);
+    };
+}
+function overridesOf(node) {
+    const registered = provided.get(node);
+    if (registered !== undefined)
+        return registered;
+    if (node.localName !== DRIVERS_ELEMENT)
+        return undefined;
+    return node.drivers;
+}
+/**
+ * The override for `name` from the nearest provider that has one. Providers nest: an inner
+ * provider without that driver lets an outer one supply it. Commands never run on the server,
+ * so there is nothing to resolve there.
+ */
+export function providedDriver(host, name) {
+    if (onServer)
+        return undefined;
+    for (let node = host.parentNode; node !== null;) {
+        if (node instanceof Element) {
+            const driver = overridesOf(node)?.[name];
+            if (driver !== undefined)
+                return driver;
+        }
+        node = node instanceof ShadowRoot ? node.host : node.parentNode;
+    }
+    return undefined;
+}
+//# sourceMappingURL=drivers-scope.js.map

package/dist/drivers-scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"drivers-scope.js","sourceRoot":"","sources":["../src/drivers-scope.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,0FAA0F;AAC1F,0EAA0E;AAC1E,OAAO,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAC;AAG/B,MAAM,QAAQ,GAAY,QAAQ,CAAC;AAEnC,4FAA4F;AAC5F,MAAM,CAAC,MAAM,eAAe,GAAG,eAAe,CAAC;AAE/C,iFAAiF;AACjF,MAAM,QAAQ,GAAG,IAAI,OAAO,EAA4B,CAAC;AAEzD;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,OAAgB,EAAE,OAAwB;IACvE,QAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC/B,OAAO,GAAG,EAAE;QACV,IAAI,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,OAAO;YAAE,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAClE,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,IAAa;IAChC,MAAM,UAAU,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,UAAU,KAAK,SAAS;QAAE,OAAO,UAAU,CAAC;IAChD,IAAI,IAAI,CAAC,SAAS,KAAK,eAAe;QAAE,OAAO,SAAS,CAAC;IACzD,OAAQ,IAAgD,CAAC,OAAO,CAAC;AACnE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,IAAa,EAAE,IAAY;IACxD,IAAI,QAAQ;QAAE,OAAO,SAAS,CAAC;IAC/B,KAAK,IAAI,IAAI,GAAgB,IAAI,CAAC,UAAU,EAAE,IAAI,KAAK,IAAI,GAAG,CAAC;QAC7D,IAAI,IAAI,YAAY,OAAO,EAAE,CAAC;YAC5B,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;YACzC,IAAI,MAAM,KAAK,SAAS;gBAAE,OAAO,MAAM,CAAC;QAC1C,CAAC;QACD,IAAI,GAAG,IAAI,YAAY,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC;IAClE,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC","sourcesContent":["// Tree-scoped driver overrides (gyral-czi.35, ADR 0006 addendum): which driver a command uses.\n// Resolution: el.drivers → nearest driver provider (across shadow roots) → spec.drivers →\n// the command's own driver. Mirrors <gyral-stores> (ADR 0013) for stores.\nimport { isServer } from 'lit';\nimport type { AnyDriver, DriverOverrides } from './command.js';\n\nconst onServer: boolean = isServer;\n\n/** Provider element name: `<gyral-drivers .drivers=${{ http: fake }}>…</gyral-drivers>`. */\nexport const DRIVERS_ELEMENT = 'gyral-drivers';\n\n// Elements registered with provideDrivers() (any element can act as a provider).\nconst provided = new WeakMap<Element, DriverOverrides>();\n\n/**\n * Makes `element` a driver provider for every Gyral component below it (including inside\n * shadow roots). Returns a function that removes the overrides. Use it on a test container\n * or an app root; a `<gyral-drivers>` element with a `.drivers` property works the same way.\n */\nexport function provideDrivers(element: Element, drivers: DriverOverrides): () => void {\n  provided.set(element, drivers);\n  return () => {\n    if (provided.get(element) === drivers) provided.delete(element);\n  };\n}\n\nfunction overridesOf(node: Element): DriverOverrides | undefined {\n  const registered = provided.get(node);\n  if (registered !== undefined) return registered;\n  if (node.localName !== DRIVERS_ELEMENT) return undefined;\n  return (node as Element & { drivers?: DriverOverrides }).drivers;\n}\n\n/**\n * The override for `name` from the nearest provider that has one. Providers nest: an inner\n * provider without that driver lets an outer one supply it. Commands never run on the server,\n * so there is nothing to resolve there.\n */\nexport function providedDriver(host: Element, name: string): AnyDriver | undefined {\n  if (onServer) return undefined;\n  for (let node: Node | null = host.parentNode; node !== null;) {\n    if (node instanceof Element) {\n      const driver = overridesOf(node)?.[name];\n      if (driver !== undefined) return driver;\n    }\n    node = node instanceof ShadowRoot ? node.host : node.parentNode;\n  }\n  return undefined;\n}\n"]}

package/dist/element-directive.d.ts

@@ -0,0 +1,20 @@
+import { nothing } from 'lit';
+import { Directive, type ElementPart, type PartInfo } from 'lit/directive.js';
+/**
+ * Base for element directives (`<input ${invalid(errors)}>`): they act on the element they are
+ * placed on and render nothing. Subclasses declare their arguments as `Args` and implement
+ * `apply`. Wrap the class with `directive()` (re-exported from core) to get the template
+ * function. Element parts are not rendered on the server, so `apply` only runs in the browser.
+ *
+ *   class Focus extends ElementDirective<[when: boolean]> {
+ *     apply(el: Element, [when]: [boolean]) { if (when && el instanceof HTMLElement) el.focus(); }
+ *   }
+ *   export const focusWhen = directive(Focus);
+ */
+export declare abstract class ElementDirective<Args extends unknown[]> extends Directive {
+    constructor(info: PartInfo);
+    /** Called on every render with the directive's current arguments. */
+    abstract apply(element: Element, args: Args): void;
+    render(...args: Args): typeof nothing;
+    update(part: ElementPart, args: Args): typeof nothing;
+}

package/dist/element-directive.js

@@ -0,0 +1,31 @@
+import { nothing } from 'lit';
+import { Directive, PartType } from 'lit/directive.js';
+/**
+ * Base for element directives (`<input ${invalid(errors)}>`): they act on the element they are
+ * placed on and render nothing. Subclasses declare their arguments as `Args` and implement
+ * `apply`. Wrap the class with `directive()` (re-exported from core) to get the template
+ * function. Element parts are not rendered on the server, so `apply` only runs in the browser.
+ *
+ *   class Focus extends ElementDirective<[when: boolean]> {
+ *     apply(el: Element, [when]: [boolean]) { if (when && el instanceof HTMLElement) el.focus(); }
+ *   }
+ *   export const focusWhen = directive(Focus);
+ */
+export class ElementDirective extends Directive {
+    constructor(info) {
+        super(info);
+        if (info.type !== PartType.ELEMENT) {
+            throw new Error(`${new.target.name} must be used on an element: <el \${directive(…)}>`);
+        }
+    }
+    // Lit reads the directive's arguments from render(); update() does the work.
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    render(...args) {
+        return nothing;
+    }
+    update(part, args) {
+        this.apply(part.element, args);
+        return nothing;
+    }
+}
+//# sourceMappingURL=element-directive.js.map

package/dist/element-directive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-directive.js","sourceRoot":"","sources":["../src/element-directive.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAC9B,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAmC,MAAM,kBAAkB,CAAC;AAExF;;;;;;;;;;GAUG;AACH,MAAM,OAAgB,gBAAyC,SAAQ,SAAS;IAC9E,YAAY,IAAc;QACxB,KAAK,CAAC,IAAI,CAAC,CAAC;QACZ,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,OAAO,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,oDAAoD,CAAC,CAAC;QAC1F,CAAC;IACH,CAAC;IAKD,6EAA6E;IAC7E,6DAA6D;IACpD,MAAM,CAAC,GAAG,IAAU;QAC3B,OAAO,OAAO,CAAC;IACjB,CAAC;IAEQ,MAAM,CAAC,IAAiB,EAAE,IAAU;QAC3C,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAC/B,OAAO,OAAO,CAAC;IACjB,CAAC;CACF","sourcesContent":["import { nothing } from 'lit';\nimport { Directive, PartType, type ElementPart, type PartInfo } from 'lit/directive.js';\n\n/**\n * Base for element directives (`<input ${invalid(errors)}>`): they act on the element they are\n * placed on and render nothing. Subclasses declare their arguments as `Args` and implement\n * `apply`. Wrap the class with `directive()` (re-exported from core) to get the template\n * function. Element parts are not rendered on the server, so `apply` only runs in the browser.\n *\n *   class Focus extends ElementDirective<[when: boolean]> {\n *     apply(el: Element, [when]: [boolean]) { if (when && el instanceof HTMLElement) el.focus(); }\n *   }\n *   export const focusWhen = directive(Focus);\n */\nexport abstract class ElementDirective<Args extends unknown[]> extends Directive {\n  constructor(info: PartInfo) {\n    super(info);\n    if (info.type !== PartType.ELEMENT) {\n      throw new Error(`${new.target.name} must be used on an element: <el \\${directive(…)}>`);\n    }\n  }\n\n  /** Called on every render with the directive's current arguments. */\n  abstract apply(element: Element, args: Args): void;\n\n  // Lit reads the directive's arguments from render(); update() does the work.\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  override render(...args: Args): typeof nothing {\n    return nothing;\n  }\n\n  override update(part: ElementPart, args: Args): typeof nothing {\n    this.apply(part.element, args);\n    return nothing;\n  }\n}\n"]}

package/dist/element-types.d.ts

@@ -0,0 +1,34 @@
+import type { LitElement } from 'lit';
+import type { DriverOverrides } from './command.js';
+import type { StoreOverrides } from './store.js';
+import type { ComponentSpec, Tagged } from './types.js';
+/** The custom element class produced by `define()`. */
+export interface GyralElement<S, M extends Tagged> extends LitElement {
+    /** 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
+     * `<gyral-stores>` 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[];
+}
+export interface GyralElementClass<S, M extends Tagged, P, O extends Tagged = never> {
+    /** Instances expose their declared props as settable properties. */
+    new (): GyralElement<S, M> & {
+        -readonly [K in keyof P]: P[K];
+    };
+    readonly spec: ComponentSpec<S, M, P>;
+    readonly tagName: string;
+    /** Type-only: the outputs this component emits (read by `child()`). */
+    readonly outputs?: O;
+}

package/dist/element-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=element-types.js.map

package/dist/element-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-types.js","sourceRoot":"","sources":["../src/element-types.ts"],"names":[],"mappings":"","sourcesContent":["import type { LitElement } from 'lit';\nimport type { DriverOverrides } from './command.js';\nimport type { StoreOverrides } from './store.js';\nimport type { ComponentSpec, Tagged } from './types.js';\n\n/** The custom element class produced by `define()`. */\nexport interface GyralElement<S, M extends Tagged> extends LitElement {\n  /** Current model state. */\n  readonly state: S;\n  /** Feeds a message through `update`, as if an intent had produced it. */\n  send(msg: M): void;\n  /** Per-instance driver substitutions by name (test fakes). Checked before the spec's. */\n  drivers: DriverOverrides;\n  /**\n   * Per-instance store instances by store name (tests, islands). Checked before the nearest\n   * `<gyral-stores>` provider and the document default (ADR 0013).\n   */\n  stores: StoreOverrides;\n  /**\n   * Messages applied through `update` right after `init`, before the first render. The server\n   * uses it to render a rejected form with the same reducer as the JS path (ADR 0008). Ignored\n   * when the element resumes from a hydration seed (the seed already contains their effect).\n   */\n  initialMessages: readonly Tagged[];\n}\n\nexport interface GyralElementClass<S, M extends Tagged, P, O extends Tagged = never> {\n  /** Instances expose their declared props as settable properties. */\n  new (): GyralElement<S, M> & { -readonly [K in keyof P]: P[K] };\n  readonly spec: ComponentSpec<S, M, P>;\n  readonly tagName: string;\n  /** Type-only: the outputs this component emits (read by `child()`). */\n  readonly outputs?: O;\n}\n"]}

package/dist/focus.d.ts

@@ -0,0 +1,27 @@
+import type { Command } from './command.js';
+/** Marker driver: `define()` handles focus commands itself. */
+export declare const FOCUS: {
+    readonly name: "@gyral/focus";
+    readonly run: () => undefined;
+};
+export 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;
+}
+/** The input of a `focus()` command. */
+export interface FocusInput extends FocusOptions {
+    readonly selector: string;
+}
+/**
+ * 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:
+ *
+ *   NextPage: (s, m) => [{ ...s, page: m.page }, [focus('h2', { preventScroll: true })]]
+ *
+ * Non-focusable targets (a heading) need `tabindex="-1"` in the view.
+ */
+export declare function focus(selector: string, options?: FocusOptions): Command<never>;
+/** Runs a focus command against `root` (called by define() after the update completes). */
+export declare function runFocus(root: ParentNode, tag: string, input: FocusInput): void;

package/dist/focus.js

@@ -0,0 +1,30 @@
+/** Marker driver: `define()` handles focus commands itself. */
+export const FOCUS = {
+    name: '@gyral/focus',
+    run: () => undefined,
+};
+/**
+ * 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:
+ *
+ *   NextPage: (s, m) => [{ ...s, page: m.page }, [focus('h2', { preventScroll: true })]]
+ *
+ * Non-focusable targets (a heading) need `tabindex="-1"` in the view.
+ */
+export function focus(selector, options = {}) {
+    const input = { selector, ...options };
+    return { driver: FOCUS, input, onSuccess: () => undefined };
+}
+/** Runs a focus command against `root` (called by define() after the update completes). */
+export function runFocus(root, tag, input) {
+    const target = root.querySelector(input.selector);
+    if (!(target instanceof HTMLElement || target instanceof SVGElement)) {
+        console.warn(`<${tag}> focus("${input.selector}") matched no focusable element.`);
+        return;
+    }
+    target.focus({ preventScroll: input.preventScroll ?? false });
+    if (input.select === true && 'select' in target && typeof target.select === 'function') {
+        target.select();
+    }
+}
+//# sourceMappingURL=focus.js.map

package/dist/focus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"focus.js","sourceRoot":"","sources":["../src/focus.ts"],"names":[],"mappings":"AAKA,+DAA+D;AAC/D,MAAM,CAAC,MAAM,KAAK,GAAG;IACnB,IAAI,EAAE,cAAc;IACpB,GAAG,EAAE,GAAG,EAAE,CAAC,SAAS;CACZ,CAAC;AAcX;;;;;;;GAOG;AACH,MAAM,UAAU,KAAK,CAAC,QAAgB,EAAE,UAAwB,EAAE;IAChE,MAAM,KAAK,GAAe,EAAE,QAAQ,EAAE,GAAG,OAAO,EAAE,CAAC;IACnD,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,SAAS,EAAE,CAAC;AAC9D,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,QAAQ,CAAC,IAAgB,EAAE,GAAW,EAAE,KAAiB;IACvE,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAClD,IAAI,CAAC,CAAC,MAAM,YAAY,WAAW,IAAI,MAAM,YAAY,UAAU,CAAC,EAAE,CAAC;QACrE,OAAO,CAAC,IAAI,CAAC,IAAI,GAAG,YAAY,KAAK,CAAC,QAAQ,kCAAkC,CAAC,CAAC;QAClF,OAAO;IACT,CAAC;IACD,MAAM,CAAC,KAAK,CAAC,EAAE,aAAa,EAAE,KAAK,CAAC,aAAa,IAAI,KAAK,EAAE,CAAC,CAAC;IAC9D,IAAI,KAAK,CAAC,MAAM,KAAK,IAAI,IAAI,QAAQ,IAAI,MAAM,IAAI,OAAO,MAAM,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;QACtF,MAA2B,CAAC,MAAM,EAAE,CAAC;IACxC,CAAC;AACH,CAAC","sourcesContent":["// Focus management from the model (gyral-czi.28). Moving focus is a side effect, so the model\n// asks for it with a command; define() runs it against the component's own render root after\n// the render that the same reducer caused, so the element to focus already exists.\nimport type { Command } from './command.js';\n\n/** Marker driver: `define()` handles focus commands itself. */\nexport const FOCUS = {\n  name: '@gyral/focus',\n  run: () => undefined,\n} as const;\n\nexport interface FocusOptions {\n  /** Don't scroll the element into view (default `false`: the browser scrolls if needed). */\n  readonly preventScroll?: boolean;\n  /** Also select the text of an input or textarea. */\n  readonly select?: boolean;\n}\n\n/** The input of a `focus()` command. */\nexport interface FocusInput extends FocusOptions {\n  readonly selector: string;\n}\n\n/**\n * A command that focuses the first element matching `selector` inside this component (its\n * shadow root, or its own children in light-DOM mode) once the current update has rendered:\n *\n *   NextPage: (s, m) => [{ ...s, page: m.page }, [focus('h2', { preventScroll: true })]]\n *\n * Non-focusable targets (a heading) need `tabindex=\"-1\"` in the view.\n */\nexport function focus(selector: string, options: FocusOptions = {}): Command<never> {\n  const input: FocusInput = { selector, ...options };\n  return { driver: FOCUS, input, onSuccess: () => undefined };\n}\n\n/** Runs a focus command against `root` (called by define() after the update completes). */\nexport function runFocus(root: ParentNode, tag: string, input: FocusInput): void {\n  const target = root.querySelector(input.selector);\n  if (!(target instanceof HTMLElement || target instanceof SVGElement)) {\n    console.warn(`<${tag}> focus(\"${input.selector}\") matched no focusable element.`);\n    return;\n  }\n  target.focus({ preventScroll: input.preventScroll ?? false });\n  if (input.select === true && 'select' in target && typeof target.select === 'function') {\n    (target as HTMLInputElement).select();\n  }\n}\n"]}

package/dist/forms.d.ts

@@ -0,0 +1,59 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { FieldIssue, FormFields, IntentParser, IntentRejected } from './types.js';
+/** A form's schema, shared by the client component and (with @gyral/ssr) the server route. */
+export interface FormDefinition<Schema extends StandardSchemaV1> {
+    readonly _tag: 'FormDefinition';
+    readonly schema: Schema;
+}
+export declare function defineForm<Schema extends StandardSchemaV1>(schema: Schema): FormDefinition<Schema>;
+export type FormValue = FormDataEntryValue | readonly FormDataEntryValue[];
+/**
+ * FormData to a plain object. The same function runs on the server, so both sides agree.
+ * Repeated names become arrays; a `name[]` suffix always yields an array (named `name`).
+ * Values stay strings (or Files): the schema coerces them.
+ */
+export declare function formDataToObject(data: FormData): Readonly<Record<string, FormValue>>;
+type Out<Schema extends StandardSchemaV1> = StandardSchemaV1.InferOutput<Schema>;
+/** The text fields of a parsed form, for re-filling it after a rejection. */
+export declare function formFields(data: Readonly<Record<string, FormValue>>): FormFields;
+export type FormResult<T> = {
+    readonly ok: true;
+    readonly data: T;
+} | {
+    readonly ok: false;
+    readonly rejected: IntentRejected;
+};
+/**
+ * Validates submitted form data exactly as `form()` does. The no-JS server path
+ * (`formAction` in @gyral/ssr) uses it, so both paths produce the same `IntentRejected`.
+ */
+export declare function validateForm<Schema extends StandardSchemaV1>(definition: FormDefinition<Schema> | Schema, intent: string, data: FormData): FormResult<Out<Schema>> | Promise<FormResult<Out<Schema>>>;
+/**
+ * Intent parser for a `<form data-intent>` 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.
+ */
+export declare function form<Schema extends StandardSchemaV1, M>(definition: FormDefinition<Schema> | Schema, toMsg: (data: Out<Schema>, formData: FormData) => M | undefined): IntentParser<M>;
+/**
+ * Intent parser for one control (pair with `data-intent-on="input"` for live checks).
+ * Validates `checked` for checkboxes and radios, otherwise `value`.
+ */
+export declare function field<Schema extends StandardSchemaV1, M>(schema: Schema, toMsg: (value: Out<Schema>) => M | undefined): IntentParser<M>;
+/**
+ * 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.
+ */
+export declare function fieldErrors(issues: readonly FieldIssue[]): Readonly<Record<string, readonly string[]>>;
+/**
+ * A Standard Schema for `IntentRejected` as a server sends it (`formAction` answering JSON).
+ * Used by `submitForm` in @gyral/http to recognise a 422 rejection; usable with any decoder.
+ */
+export declare const intentRejectedSchema: StandardSchemaV1<unknown, IntentRejected>;
+/** A server's JSON answer to a valid form post that would have redirected without JS. */
+export interface FormRedirected {
+    readonly _tag: 'Redirected';
+    readonly location: string;
+}
+/** The `location` of a `FormRedirected` answer (from `formAction` in @gyral/ssr), if it is one. */
+export declare function redirectedTo(body: unknown): string | undefined;
+export {};

package/dist/forms.js

@@ -0,0 +1,138 @@
+export function defineForm(schema) {
+    return { _tag: 'FormDefinition', schema };
+}
+/**
+ * FormData to a plain object. The same function runs on the server, so both sides agree.
+ * Repeated names become arrays; a `name[]` suffix always yields an array (named `name`).
+ * Values stay strings (or Files): the schema coerces them.
+ */
+export function formDataToObject(data) {
+    const out = {};
+    for (const key of new Set(data.keys())) {
+        const values = data.getAll(key);
+        const [first] = values;
+        if (key.endsWith('[]'))
+            out[key.slice(0, -2)] = values;
+        else if (values.length === 1 && first !== undefined)
+            out[key] = first;
+        else
+            out[key] = values;
+    }
+    return out;
+}
+const segment = (s) => String(typeof s === 'object' ? s.key : s);
+function toIssues(issues, fallbackPath) {
+    return issues.map((issue) => {
+        const path = issue.path?.map(segment).join('.') ?? '';
+        return { path: path === '' ? fallbackPath : path, message: issue.message };
+    });
+}
+function parse(schema, value, intent, fallbackPath, toMsg) {
+    const settle = (result) => result.issues === undefined
+        ? toMsg(result.value)
+        : { _tag: 'IntentRejected', intent, issues: toIssues(result.issues, fallbackPath) };
+    const result = schema['~standard'].validate(value);
+    return result instanceof Promise ? result.then(settle) : settle(result);
+}
+/** The text fields of a parsed form, for re-filling it after a rejection. */
+export function formFields(data) {
+    const out = {};
+    for (const [key, value] of Object.entries(data)) {
+        if (typeof value === 'string')
+            out[key] = value;
+        else if (Array.isArray(value))
+            out[key] = value.filter((v) => typeof v === 'string');
+    }
+    return out;
+}
+const schemaOf = (definition) => ('_tag' in definition ? definition.schema : definition);
+/**
+ * Validates submitted form data exactly as `form()` does. The no-JS server path
+ * (`formAction` in @gyral/ssr) uses it, so both paths produce the same `IntentRejected`.
+ */
+export function validateForm(definition, intent, data) {
+    const raw = formDataToObject(data);
+    const values = formFields(raw);
+    const rejected = (issues) => ({
+        ok: false,
+        rejected: { _tag: 'IntentRejected', intent, issues, values },
+    });
+    const settle = (result) => result.issues === undefined
+        ? { ok: true, data: result.value }
+        : rejected(toIssues(result.issues, ''));
+    const result = schemaOf(definition)['~standard'].validate(raw);
+    return result instanceof Promise ? result.then(settle) : settle(result);
+}
+/**
+ * Intent parser for a `<form data-intent>` 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.
+ */
+export function form(definition, toMsg) {
+    return (input) => {
+        const { formData } = input;
+        if (formData === undefined)
+            return undefined;
+        const toParsed = (r) => r.ok ? toMsg(r.data, formData) : r.rejected;
+        const result = validateForm(definition, input.name, formData);
+        return result instanceof Promise ? result.then(toParsed) : toParsed(result);
+    };
+}
+/**
+ * Intent parser for one control (pair with `data-intent-on="input"` for live checks).
+ * Validates `checked` for checkboxes and radios, otherwise `value`.
+ */
+export function field(schema, toMsg) {
+    return (input) => {
+        const name = input.target.getAttribute('name') ?? input.name;
+        return parse(schema, input.checked ?? input.value, input.name, name, toMsg);
+    };
+}
+/**
+ * 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.
+ */
+export function fieldErrors(issues) {
+    const out = {};
+    for (const { path, message } of issues)
+        (out[path] ??= []).push(message);
+    return out;
+}
+const isRecord = (value) => typeof value === 'object' && value !== null;
+const isIssue = (value) => isRecord(value) && typeof value['path'] === 'string' && typeof value['message'] === 'string';
+const isFields = (value) => isRecord(value) &&
+    Object.values(value).every((v) => typeof v === 'string' || (Array.isArray(v) && v.every((x) => typeof x === 'string')));
+/**
+ * A Standard Schema for `IntentRejected` as a server sends it (`formAction` answering JSON).
+ * Used by `submitForm` in @gyral/http to recognise a 422 rejection; usable with any decoder.
+ */
+export const intentRejectedSchema = {
+    '~standard': {
+        version: 1,
+        vendor: 'gyral',
+        validate: (value) => {
+            if (!isRecord(value) ||
+                value['_tag'] !== 'IntentRejected' ||
+                typeof value['intent'] !== 'string' ||
+                !Array.isArray(value['issues']) ||
+                !value['issues'].every(isIssue) ||
+                (value['values'] !== undefined && !isFields(value['values']))) {
+                return { issues: [{ message: 'Expected an IntentRejected message' }] };
+            }
+            const rejected = {
+                _tag: 'IntentRejected',
+                intent: value['intent'],
+                issues: value['issues'],
+                ...(value['values'] === undefined ? {} : { values: value['values'] }),
+            };
+            return { value: rejected };
+        },
+    },
+};
+/** The `location` of a `FormRedirected` answer (from `formAction` in @gyral/ssr), if it is one. */
+export function redirectedTo(body) {
+    return isRecord(body) && body['_tag'] === 'Redirected' && typeof body['location'] === 'string'
+        ? body['location']
+        : undefined;
+}
+//# sourceMappingURL=forms.js.map

package/dist/forms.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"forms.js","sourceRoot":"","sources":["../src/forms.ts"],"names":[],"mappings":"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","sourcesContent":["// Forms, client half (docs/design-docs/0008-forms.md). Schemas are any Standard Schema v1.\nimport type { StandardSchemaV1 } from '@standard-schema/spec';\nimport type { FieldIssue, FormFields, IntentInput, IntentParser, IntentRejected } from './types.js';\n\n/** A form's schema, shared by the client component and (with @gyral/ssr) the server route. */\nexport interface FormDefinition<Schema extends StandardSchemaV1> {\n  readonly _tag: 'FormDefinition';\n  readonly schema: Schema;\n}\n\nexport function defineForm<Schema extends StandardSchemaV1>(\n  schema: Schema,\n): FormDefinition<Schema> {\n  return { _tag: 'FormDefinition', schema };\n}\n\nexport type FormValue = FormDataEntryValue | readonly FormDataEntryValue[];\n\n/**\n * FormData to a plain object. The same function runs on the server, so both sides agree.\n * Repeated names become arrays; a `name[]` suffix always yields an array (named `name`).\n * Values stay strings (or Files): the schema coerces them.\n */\nexport function formDataToObject(data: FormData): Readonly<Record<string, FormValue>> {\n  const out: Record<string, FormValue> = {};\n  for (const key of new Set(data.keys())) {\n    const values = data.getAll(key);\n    const [first] = values;\n    if (key.endsWith('[]')) out[key.slice(0, -2)] = values;\n    else if (values.length === 1 && first !== undefined) out[key] = first;\n    else out[key] = values;\n  }\n  return out;\n}\n\nconst segment = (s: PropertyKey | StandardSchemaV1.PathSegment): string =>\n  String(typeof s === 'object' ? s.key : s);\n\nfunction toIssues(\n  issues: ReadonlyArray<StandardSchemaV1.Issue>,\n  fallbackPath: string,\n): FieldIssue[] {\n  return issues.map((issue) => {\n    const path = issue.path?.map(segment).join('.') ?? '';\n    return { path: path === '' ? fallbackPath : path, message: issue.message };\n  });\n}\n\ntype Out<Schema extends StandardSchemaV1> = StandardSchemaV1.InferOutput<Schema>;\ntype Parsed<M> = M | IntentRejected | undefined;\n\nfunction parse<Schema extends StandardSchemaV1, M>(\n  schema: Schema,\n  value: unknown,\n  intent: string,\n  fallbackPath: string,\n  toMsg: (data: Out<Schema>) => M | undefined,\n): Parsed<M> | Promise<Parsed<M>> {\n  const settle = (result: StandardSchemaV1.Result<Out<Schema>>): Parsed<M> =>\n    result.issues === undefined\n      ? toMsg(result.value)\n      : { _tag: 'IntentRejected', intent, issues: toIssues(result.issues, fallbackPath) };\n  const result = schema['~standard'].validate(value);\n  return result instanceof Promise ? result.then(settle) : settle(result);\n}\n\n/** The text fields of a parsed form, for re-filling it after a rejection. */\nexport function formFields(data: Readonly<Record<string, FormValue>>): FormFields {\n  const out: Record<string, string | readonly string[]> = {};\n  for (const [key, value] of Object.entries(data)) {\n    if (typeof value === 'string') out[key] = value;\n    else if (Array.isArray(value)) out[key] = value.filter((v) => typeof v === 'string');\n  }\n  return out;\n}\n\nconst schemaOf = <Schema extends StandardSchemaV1>(\n  definition: FormDefinition<Schema> | Schema,\n): Schema => ('_tag' in definition ? definition.schema : definition);\n\nexport type FormResult<T> =\n  | { readonly ok: true; readonly data: T }\n  | { readonly ok: false; readonly rejected: IntentRejected };\n\n/**\n * Validates submitted form data exactly as `form()` does. The no-JS server path\n * (`formAction` in @gyral/ssr) uses it, so both paths produce the same `IntentRejected`.\n */\nexport function validateForm<Schema extends StandardSchemaV1>(\n  definition: FormDefinition<Schema> | Schema,\n  intent: string,\n  data: FormData,\n): FormResult<Out<Schema>> | Promise<FormResult<Out<Schema>>> {\n  const raw = formDataToObject(data);\n  const values = formFields(raw);\n  const rejected = (issues: readonly FieldIssue[]): FormResult<Out<Schema>> => ({\n    ok: false,\n    rejected: { _tag: 'IntentRejected', intent, issues, values },\n  });\n  const settle = (result: StandardSchemaV1.Result<Out<Schema>>): FormResult<Out<Schema>> =>\n    result.issues === undefined\n      ? { ok: true, data: result.value }\n      : rejected(toIssues(result.issues, ''));\n  const result = schemaOf(definition)['~standard'].validate(raw);\n  return result instanceof Promise ? result.then(settle) : settle(result);\n}\n\n/**\n * Intent parser for a `<form data-intent>` submission, validated by a schema. `toMsg` also\n * gets the raw `FormData`, for sending the submission to the server (`submitForm` in\n * @gyral/http) after it passed client-side validation.\n */\nexport function form<Schema extends StandardSchemaV1, M>(\n  definition: FormDefinition<Schema> | Schema,\n  toMsg: (data: Out<Schema>, formData: FormData) => M | undefined,\n): IntentParser<M> {\n  return (input: IntentInput) => {\n    const { formData } = input;\n    if (formData === undefined) return undefined;\n    const toParsed = (r: FormResult<Out<Schema>>): Parsed<M> =>\n      r.ok ? toMsg(r.data, formData) : r.rejected;\n    const result = validateForm(definition, input.name, formData);\n    return result instanceof Promise ? result.then(toParsed) : toParsed(result);\n  };\n}\n\n/**\n * Intent parser for one control (pair with `data-intent-on=\"input\"` for live checks).\n * Validates `checked` for checkboxes and radios, otherwise `value`.\n */\nexport function field<Schema extends StandardSchemaV1, M>(\n  schema: Schema,\n  toMsg: (value: Out<Schema>) => M | undefined,\n): IntentParser<M> {\n  return (input: IntentInput) => {\n    const name = input.target.getAttribute('name') ?? input.name;\n    return parse(schema, input.checked ?? input.value, input.name, name, toMsg);\n  };\n}\n\n/**\n * Groups issues by field name. Call it in the `IntentRejected` reducer and keep the result in\n * state: `invalid()` re-applies an error only when it gets a new array.\n */\nexport function fieldErrors(\n  issues: readonly FieldIssue[],\n): Readonly<Record<string, readonly string[]>> {\n  const out: Record<string, string[]> = {};\n  for (const { path, message } of issues) (out[path] ??= []).push(message);\n  return out;\n}\n\nconst isRecord = (value: unknown): value is Readonly<Record<string, unknown>> =>\n  typeof value === 'object' && value !== null;\n\nconst isIssue = (value: unknown): value is FieldIssue =>\n  isRecord(value) && typeof value['path'] === 'string' && typeof value['message'] === 'string';\n\nconst isFields = (value: unknown): value is FormFields =>\n  isRecord(value) &&\n  Object.values(value).every(\n    (v) => typeof v === 'string' || (Array.isArray(v) && v.every((x) => typeof x === 'string')),\n  );\n\n/**\n * A Standard Schema for `IntentRejected` as a server sends it (`formAction` answering JSON).\n * Used by `submitForm` in @gyral/http to recognise a 422 rejection; usable with any decoder.\n */\nexport const intentRejectedSchema: StandardSchemaV1<unknown, IntentRejected> = {\n  '~standard': {\n    version: 1,\n    vendor: 'gyral',\n    validate: (value) => {\n      if (\n        !isRecord(value) ||\n        value['_tag'] !== 'IntentRejected' ||\n        typeof value['intent'] !== 'string' ||\n        !Array.isArray(value['issues']) ||\n        !value['issues'].every(isIssue) ||\n        (value['values'] !== undefined && !isFields(value['values']))\n      ) {\n        return { issues: [{ message: 'Expected an IntentRejected message' }] };\n      }\n      const rejected: IntentRejected = {\n        _tag: 'IntentRejected',\n        intent: value['intent'],\n        issues: value['issues'],\n        ...(value['values'] === undefined ? {} : { values: value['values'] }),\n      };\n      return { value: rejected };\n    },\n  },\n};\n\n/** A server's JSON answer to a valid form post that would have redirected without JS. */\nexport interface FormRedirected {\n  readonly _tag: 'Redirected';\n  readonly location: string;\n}\n\n/** The `location` of a `FormRedirected` answer (from `formAction` in @gyral/ssr), if it is one. */\nexport function redirectedTo(body: unknown): string | undefined {\n  return isRecord(body) && body['_tag'] === 'Redirected' && typeof body['location'] === 'string'\n    ? body['location']\n    : undefined;\n}\n"]}

package/dist/hydration.d.ts

@@ -0,0 +1,36 @@
+import type { PropertyDeclaration } from 'lit';
+/** Host attribute holding the JSON seed. Removed once the client has read it. */
+export declare const SEED_ATTRIBUTE = "data-gyral-seed";
+export interface Seed {
+    /**
+     * The server's state. Omitted when it equals what `init(props)` returns for the seeded
+     * props (gyral-czi 4k7.10): the client recomputes it instead of reading a second copy of
+     * data the props already carry.
+     */
+    readonly state?: unknown;
+    readonly props: Readonly<Record<string, unknown>>;
+}
+/** JSON equality: seeds are JSON, so two values that serialize alike hydrate alike. */
+export declare const sameJson: (a: unknown, b: unknown) => boolean;
+type Declarations = Readonly<Record<string, PropertyDeclaration>>;
+/**
+ * Server side: records the element's state and its props that are not already present as
+ * attributes (property bindings such as `.items=${data}` are not in the HTML otherwise).
+ * The SSR renderer escapes attribute values, so the JSON is HTML-safe.
+ */
+export declare function writeSeed(host: Element, state: unknown, props: Readonly<Record<string, unknown>>, declarations: Declarations, initialState?: {
+    readonly value: unknown;
+}): void;
+/**
+ * Client side, right after hydration (gyral-4k7.12, ADR 0012): Lit SSR writes nothing for
+ * an empty primitive (`''`, `null`, `undefined`), so `<!--lit-part--><!--/lit-part-->`
+ * has no Text node between the markers. Hydration still records the primitive as the
+ * part's committed value, and the next text commit writes `.data` into the
+ * `<!--/lit-part-->` comment instead. Restore the empty Text node a client render would
+ * have created. Harmless for `nothing` and empty iterables, which clear or insert before
+ * the end marker. Shadow roots below `root` are handled by their own hosts.
+ */
+export declare function fillEmptyTextParts(root: Node): void;
+/** Client side: reads and removes the seed, if this element was server-rendered by Gyral. */
+export declare function takeSeed(host: Element): Seed | undefined;
+export {};

package/dist/hydration.js

@@ -0,0 +1,72 @@
+import { warnJsonHazard } from './json-safety.js';
+/** Host attribute holding the JSON seed. Removed once the client has read it. */
+export const SEED_ATTRIBUTE = 'data-gyral-seed';
+/** JSON equality: seeds are JSON, so two values that serialize alike hydrate alike. */
+export const sameJson = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+function attributeName(name, decl) {
+    if (decl.attribute === false)
+        return undefined;
+    return typeof decl.attribute === 'string' ? decl.attribute : name.toLowerCase();
+}
+/**
+ * Server side: records the element's state and its props that are not already present as
+ * attributes (property bindings such as `.items=${data}` are not in the HTML otherwise).
+ * The SSR renderer escapes attribute values, so the JSON is HTML-safe.
+ */
+export function writeSeed(host, state, props, declarations, initialState) {
+    const carried = {};
+    for (const [name, value] of Object.entries(props)) {
+        const decl = declarations[name] ?? {};
+        const attr = attributeName(name, decl);
+        if (value !== undefined && (attr === undefined || !host.hasAttribute(attr))) {
+            carried[name] = value;
+        }
+    }
+    const derivable = initialState !== undefined && sameJson(state, initialState.value);
+    const seed = derivable ? { props: carried } : { state, props: carried };
+    warnJsonHazard(`<${host.localName}>`, seed, 'seed');
+    host.setAttribute(SEED_ATTRIBUTE, JSON.stringify(seed));
+}
+/**
+ * Client side, right after hydration (gyral-4k7.12, ADR 0012): Lit SSR writes nothing for
+ * an empty primitive (`''`, `null`, `undefined`), so `<!--lit-part--><!--/lit-part-->`
+ * has no Text node between the markers. Hydration still records the primitive as the
+ * part's committed value, and the next text commit writes `.data` into the
+ * `<!--/lit-part-->` comment instead. Restore the empty Text node a client render would
+ * have created. Harmless for `nothing` and empty iterables, which clear or insert before
+ * the end marker. Shadow roots below `root` are handled by their own hosts.
+ */
+export function fillEmptyTextParts(root) {
+    const doc = root.ownerDocument ?? root;
+    const walker = doc.createTreeWalker(root, NodeFilter.SHOW_COMMENT);
+    const empty = [];
+    for (let node = walker.nextNode(); node !== null; node = walker.nextNode()) {
+        const next = node.nextSibling;
+        if (node.data === 'lit-part' &&
+            next instanceof Comment &&
+            next.data === '/lit-part') {
+            empty.push(node);
+        }
+    }
+    for (const start of empty)
+        start.after(doc.createTextNode(''));
+}
+/** Client side: reads and removes the seed, if this element was server-rendered by Gyral. */
+export function takeSeed(host) {
+    const raw = host.getAttribute(SEED_ATTRIBUTE);
+    if (raw === null)
+        return undefined;
+    host.removeAttribute(SEED_ATTRIBUTE);
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== 'object')
+            return undefined;
+        const props = parsed.props ?? {};
+        return 'state' in parsed ? { state: parsed.state, props } : { props };
+    }
+    catch (error) {
+        console.error(`<${host.localName}> has an unreadable ${SEED_ATTRIBUTE}`, error);
+        return undefined;
+    }
+}
+//# sourceMappingURL=hydration.js.map

package/dist/hydration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydration.js","sourceRoot":"","sources":["../src/hydration.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,iFAAiF;AACjF,MAAM,CAAC,MAAM,cAAc,GAAG,iBAAiB,CAAC;AAYhD,uFAAuF;AACvF,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,CAAU,EAAE,CAAU,EAAW,EAAE,CAC1D,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;AAI1C,SAAS,aAAa,CAAC,IAAY,EAAE,IAAyB;IAC5D,IAAI,IAAI,CAAC,SAAS,KAAK,KAAK;QAAE,OAAO,SAAS,CAAC;IAC/C,OAAO,OAAO,IAAI,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;AAClF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CACvB,IAAa,EACb,KAAc,EACd,KAAwC,EACxC,YAA0B,EAC1B,YAA0C;IAE1C,MAAM,OAAO,GAA4B,EAAE,CAAC;IAC5C,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QACtC,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACvC,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;YAC5E,OAAO,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;QACxB,CAAC;IACH,CAAC;IACD,MAAM,SAAS,GAAG,YAAY,KAAK,SAAS,IAAI,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC;IACpF,MAAM,IAAI,GAAS,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;IAC9E,cAAc,CAAC,IAAI,IAAI,CAAC,SAAS,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IACpD,IAAI,CAAC,YAAY,CAAC,cAAc,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;AAC1D,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAU;IAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,aAAa,IAAK,IAAiB,CAAC;IACrD,MAAM,MAAM,GAAG,GAAG,CAAC,gBAAgB,CAAC,IAAI,EAAE,UAAU,CAAC,YAAY,CAAC,CAAC;IACnE,MAAM,KAAK,GAAc,EAAE,CAAC;IAC5B,KAAK,IAAI,IAAI,GAAG,MAAM,CAAC,QAAQ,EAAE,EAAE,IAAI,KAAK,IAAI,EAAE,IAAI,GAAG,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC;QAC3E,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC;QAC9B,IACG,IAAgB,CAAC,IAAI,KAAK,UAAU;YACrC,IAAI,YAAY,OAAO;YACvB,IAAI,CAAC,IAAI,KAAK,WAAW,EACzB,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,IAAe,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,KAAK;QAAE,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC,CAAC;AACjE,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,QAAQ,CAAC,IAAa;IACpC,MAAM,GAAG,GAAG,IAAI,CAAC,YAAY,CAAC,cAAc,CAAC,CAAC;IAC9C,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IACnC,IAAI,CAAC,eAAe,CAAC,cAAc,CAAC,CAAC;IACrC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAyB,CAAC;QACvD,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QACpE,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC;QACjC,OAAO,OAAO,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC;IACxE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,SAAS,uBAAuB,cAAc,EAAE,EAAE,KAAK,CAAC,CAAC;QAChF,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC","sourcesContent":["// Server-render seeds (docs/design-docs/0012-ssr.md). The server writes each element's\n// state, plus the props an attribute can't carry, into one attribute; the client reads it\n// before its first (hydrating) render so both sides render the same template.\nimport type { PropertyDeclaration } from 'lit';\nimport { warnJsonHazard } from './json-safety.js';\n\n/** Host attribute holding the JSON seed. Removed once the client has read it. */\nexport const SEED_ATTRIBUTE = 'data-gyral-seed';\n\nexport interface Seed {\n  /**\n   * The server's state. Omitted when it equals what `init(props)` returns for the seeded\n   * props (gyral-czi 4k7.10): the client recomputes it instead of reading a second copy of\n   * data the props already carry.\n   */\n  readonly state?: unknown;\n  readonly props: Readonly<Record<string, unknown>>;\n}\n\n/** JSON equality: seeds are JSON, so two values that serialize alike hydrate alike. */\nexport const sameJson = (a: unknown, b: unknown): boolean =>\n  JSON.stringify(a) === JSON.stringify(b);\n\ntype Declarations = Readonly<Record<string, PropertyDeclaration>>;\n\nfunction attributeName(name: string, decl: PropertyDeclaration): string | undefined {\n  if (decl.attribute === false) return undefined;\n  return typeof decl.attribute === 'string' ? decl.attribute : name.toLowerCase();\n}\n\n/**\n * Server side: records the element's state and its props that are not already present as\n * attributes (property bindings such as `.items=${data}` are not in the HTML otherwise).\n * The SSR renderer escapes attribute values, so the JSON is HTML-safe.\n */\nexport function writeSeed(\n  host: Element,\n  state: unknown,\n  props: Readonly<Record<string, unknown>>,\n  declarations: Declarations,\n  initialState?: { readonly value: unknown },\n): void {\n  const carried: Record<string, unknown> = {};\n  for (const [name, value] of Object.entries(props)) {\n    const decl = declarations[name] ?? {};\n    const attr = attributeName(name, decl);\n    if (value !== undefined && (attr === undefined || !host.hasAttribute(attr))) {\n      carried[name] = value;\n    }\n  }\n  const derivable = initialState !== undefined && sameJson(state, initialState.value);\n  const seed: Seed = derivable ? { props: carried } : { state, props: carried };\n  warnJsonHazard(`<${host.localName}>`, seed, 'seed');\n  host.setAttribute(SEED_ATTRIBUTE, JSON.stringify(seed));\n}\n\n/**\n * Client side, right after hydration (gyral-4k7.12, ADR 0012): Lit SSR writes nothing for\n * an empty primitive (`''`, `null`, `undefined`), so `<!--lit-part--><!--/lit-part-->`\n * has no Text node between the markers. Hydration still records the primitive as the\n * part's committed value, and the next text commit writes `.data` into the\n * `<!--/lit-part-->` comment instead. Restore the empty Text node a client render would\n * have created. Harmless for `nothing` and empty iterables, which clear or insert before\n * the end marker. Shadow roots below `root` are handled by their own hosts.\n */\nexport function fillEmptyTextParts(root: Node): void {\n  const doc = root.ownerDocument ?? (root as Document);\n  const walker = doc.createTreeWalker(root, NodeFilter.SHOW_COMMENT);\n  const empty: Comment[] = [];\n  for (let node = walker.nextNode(); node !== null; node = walker.nextNode()) {\n    const next = node.nextSibling;\n    if (\n      (node as Comment).data === 'lit-part' &&\n      next instanceof Comment &&\n      next.data === '/lit-part'\n    ) {\n      empty.push(node as Comment);\n    }\n  }\n  for (const start of empty) start.after(doc.createTextNode(''));\n}\n\n/** Client side: reads and removes the seed, if this element was server-rendered by Gyral. */\nexport function takeSeed(host: Element): Seed | undefined {\n  const raw = host.getAttribute(SEED_ATTRIBUTE);\n  if (raw === null) return undefined;\n  host.removeAttribute(SEED_ATTRIBUTE);\n  try {\n    const parsed = JSON.parse(raw) as Partial<Seed> | null;\n    if (parsed === null || typeof parsed !== 'object') return undefined;\n    const props = parsed.props ?? {};\n    return 'state' in parsed ? { state: parsed.state, props } : { props };\n  } catch (error) {\n    console.error(`<${host.localName}> has an unreadable ${SEED_ATTRIBUTE}`, error);\n    return undefined;\n  }\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+export { command, defineDriver } from './command.js';
+export type { AnyDriver, Command, CommandHandlers, Concurrency, Driver, DriverContext, DriverOverrides, Next, RetryPolicy, } from './command.js';
+export { child, emit } from './children.js';
+export { focus } from './focus.js';
+export type { FocusOptions } from './focus.js';
+export { invokersSupported } from './invokers.js';
+export type { CommandInfo } from './invokers.js';
+export { ISLAND_ATTRIBUTE } from './islands.js';
+export type { HydrateStrategy } from './islands.js';
+export type { ChildSource, OutputSource } from './children.js';
+export { define } from './define.js';
+export { changed, defineStore, send } from './store.js';
+export type { AnyStore, AnyStoreInstance, Store, StoreChanged, StoreInstance, StoreOverrides, StoreRef, StoreSendInput, SeedCheck, StoreResolver, StoreSpec, StoreUpdate, } from './store.js';
+export { STORE_SEND } from './store.js';
+export { resetDocumentStores, scriptSafeJson, STORE_SEED_ATTRIBUTE, StoreRegistry, STORES_ELEMENT, withStoreScope, } from './store-scope.js';
+export { defineStoresProvider } from './stores-provider.js';
+export { DRIVERS_ELEMENT, provideDrivers } from './drivers-scope.js';
+export { jsonHazard, warnJsonHazard } from './json-safety.js';
+export { random, randomDriver, randomInt, toInt, type RandomInput } from './random.js';
+export { defineForm, field, fieldErrors, form, formDataToObject, formFields, intentRejectedSchema, redirectedTo, validateForm, } from './forms.js';
+export type { FormDefinition, FormRedirected, FormResult, FormValue } from './forms.js';
+export { ElementDirective } from './element-directive.js';
+export { runInit } from './init.js';
+export { invalid } from './invalid.js';
+export { findInScope, labelledBy } from './accessible-name.js';
+export { liveBoolean } from './live-boolean.js';
+export { textarea, textareaMarkup } from './textarea.js';
+export { DEVTOOLS_ENABLED as devtoolsEnabled, devLiveComponents as devtoolsLiveComponents, } from '#devtools';
+export { DEVTOOLS_GLOBAL } from './devtools-events.js';
+export type { CommandPhase, CommandTraceEvent, DevComponentRef, DevEvent, DevtoolsHook, } from './devtools-events.js';
+export type { TextareaAttribute, TextareaOptions } from './textarea.js';
+export type { Styles } from './styles.js';
+export { HIDDEN_MARKER, HYDRATE_KEY, isLightComponent, LIGHT_ATTRIBUTE } from './light-dom.js';
+export type { GyralElement, GyralElementClass } from './define.js';
+export type { ComponentSpec, Ctx, FieldIssue, FormFields, IntentInput, IntentNames, IntentParser, IntentRejected, Intents, PropDeclarations, Hydrated, PropsChanged, Stateless, StoreReader, Tagged, Update, } from './types.js';
+export { css, html, nothing, svg, unsafeCSS } from 'lit';
+export { directive } from 'lit/directive.js';
+export { classMap } from 'lit/directives/class-map.js';
+export { keyed } from 'lit/directives/keyed.js';
+export { live } from 'lit/directives/live.js';
+export { repeat } from 'lit/directives/repeat.js';
+export { styleMap } from 'lit/directives/style-map.js';