@gyral/core 0.0.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# @gyral/core
+
+## 0.2.0
+
+### Minor Changes
+
+- 74054b3: Smaller and faster, with no public API change:
+
+  - **No Effect.** The command interpreter is now plain TypeScript with no runtime dependencies,
+    so `@gyral/core` depends only on Lit. An empty app drops from about 49 KiB to about 11 KiB
+    gzipped, starts faster and uses less memory; rendering speed is unchanged (ADR 0015).
+  - **Template whitespace minification.** `html` and `svg` remove indentation whitespace between
+    tags (once per template, on server and client alike), so lists build far fewer DOM nodes and
+    bulk list updates are 9–22% faster. Inline spacing is kept as one space; `<pre>`,
+    `<textarea>`, `<script>`, `<style>`, attributes and comments are unchanged. For exact
+    whitespace under CSS `white-space: pre*`, use `html` from `lit`.
+  - **lit-html leak guidance.** lit-html 3.3.1 and later leak a comment node per removed
+    `repeat()` item (lit/lit#5298). Development builds warn once when an affected version is
+    loaded; pin lit-html to 3.3.0 with an override until it is fixed upstream
+    (docs/references/consumer-setup.md). New `create-gyral` apps are pinned.
+
+### Patch Changes
+
+- a7275e8: Copyright and package author are Mike Zupper.
+- fa0156a: `focus()` returned by a reducer whose update renders inside a View Transition now runs after
+  the new view has rendered, instead of before it (it used to warn "matched no focusable element").
+
+## 0.1.0
+
+### Minor Changes
+
+- 8b5f5ca: First public release.

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 The Zoop Troop, Inc.
+Copyright (c) 2026 Mike Zupper
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/NOTICE

@@ -0,0 +1,11 @@
+Gyral
+Copyright (c) 2026 Mike Zupper
+
+Gyral is inspired by Cycle.js (https://github.com/cyclejs/cyclejs), released
+under the MIT License:
+
+  The MIT License (MIT)
+  Copyright (c) 2015-2019 The Cycle.js Core Team
+
+Gyral is a new implementation. Where ideas, APIs or example programs are adapted
+from Cycle.js, this notice applies.

package/README.md

@@ -1,10 +1,50 @@
 # @gyral/core
 
-**Coming soon — https://gyral.dev**
+Model-View-Intent web components on [Lit](https://lit.dev) and the web platform. _Inspired by [Cycle.js](https://cycle.js.org)._ Intent parses platform events into typed messages, the model is a set of pure reducers, and the view is a pure template that names intents. Side effects are commands: data that drivers run at the edges.
 
-Gyral core: Model-View-Intent web components on Lit and the web platform. Inspired by Cycle.js.
+## Install
 
-This 0.0.0 release only reserves the name. Watch
-[github.com/gyraljs/gyral](https://github.com/gyraljs/gyral) for the first real release.
+```sh
+pnpm add @gyral/core lit
+```
 
-MIT © The Zoop Troop, Inc.
+## Example
+
+```ts
+import { define, html } from '@gyral/core';
+
+type Msg = { _tag: 'Increment' } | { _tag: 'Decrement' };
+
+define<{ count: number }, Msg>('gy-counter', {
+  init: () => ({ count: 0 }),
+  intent: {
+    Increment: () => ({ _tag: 'Increment' }),
+    Decrement: () => ({ _tag: 'Decrement' }),
+  },
+  update: {
+    Increment: (s) => ({ count: s.count + 1 }),
+    Decrement: (s) => ({ count: s.count - 1 }),
+  },
+  view: (s, i) => html`
+    <output>${s.count}</output>
+    <button type="button" data-intent=${i.Decrement}>Decrement</button>
+    <button type="button" data-intent=${i.Increment}>Increment</button>
+  `,
+});
+```
+
+`@gyral/core/vite` exports `gyralVitePreset()`, the Vite/Vitest settings every Gyral app needs
+(one copy of Lit, Lit modules pre-bundled).
+
+## Documentation
+
+Guides and API reference: **[gyral.dev](https://gyral.dev)**. Source, issues and the
+consumer setup guide (peer dependencies, Vite preset, SSR checklist):
+[github.com/gyraljs/gyral](https://github.com/gyraljs/gyral).
+
+> Status: pre-alpha. APIs change between 0.x releases.
+
+## License
+
+MIT © Mike Zupper. See LICENSE and NOTICE (Cycle.js attribution). Gyral, gyraljs and
+the Gyral logo are trademarks of Mike Zupper.

package/dist/accessible-name.d.ts

@@ -0,0 +1,19 @@
+import { ElementDirective } from './element-directive.js';
+/** The element with `id`, searched from `from`'s own root outward to the document. */
+export declare function findInScope(from: Element, id: string): Element | null;
+/**
+ * Names the element after the element with `id`, even outside this component's shadow root:
+ *
+ *   <form aria-label=${props.label} ${labelledBy('page-title')}>
+ *
+ * Uses `ariaLabelledByElements` (ARIA element reflection) where the browser has it, so the name
+ * stays in sync with the heading. Elsewhere it sets `aria-label` from `fallback`, or from the
+ * target's text. Element directives don't run on the server, so render a plain `aria-label` too
+ * (from a `label` prop) for the no-JS page: `aria-labelledby` wins over it once set.
+ */
+declare class LabelledBy extends ElementDirective<[id: string, fallback?: string]> {
+    #private;
+    apply(el: Element, [id, fallback]: [id: string, fallback?: string]): void;
+}
+export declare const labelledBy: (id: string, fallback?: string | undefined) => import("lit/directive.js").DirectiveResult<typeof LabelledBy>;
+export {};

package/dist/accessible-name.js

@@ -0,0 +1,56 @@
+// Accessible names across shadow boundaries (gyral-czi.26). `aria-labelledby="page-title"` inside
+// a shadow root can't see an id in the page, so a form or landmark in a component would be
+// nameless. `labelledBy(id)` resolves the id outward through the shadow-including ancestors.
+import { directive } from 'lit/directive.js';
+import { ElementDirective } from './element-directive.js';
+/** ARIA element reflection: newly available Baseline, so feature-detected (ADR 0003). */
+const reflects = (el) => 'ariaLabelledByElements' in el;
+/** The element with `id`, searched from `from`'s own root outward to the document. */
+export function findInScope(from, id) {
+    for (let root = from.getRootNode();;) {
+        const found = 'getElementById' in root ? root.getElementById(id) : null;
+        if (found !== null && found !== from)
+            return found;
+        if (!(root instanceof ShadowRoot))
+            return null;
+        root = root.host.getRootNode();
+    }
+}
+/**
+ * Names the element after the element with `id`, even outside this component's shadow root:
+ *
+ *   <form aria-label=${props.label} ${labelledBy('page-title')}>
+ *
+ * Uses `ariaLabelledByElements` (ARIA element reflection) where the browser has it, so the name
+ * stays in sync with the heading. Elsewhere it sets `aria-label` from `fallback`, or from the
+ * target's text. Element directives don't run on the server, so render a plain `aria-label` too
+ * (from a `label` prop) for the no-JS page: `aria-labelledby` wins over it once set.
+ */
+class LabelledBy extends ElementDirective {
+    #applied = '';
+    apply(el, [id, fallback]) {
+        const key = `${id}\u0000${fallback ?? ''}`;
+        if (key === this.#applied)
+            return;
+        this.#applied = key;
+        // The labelling element may render after this one (a later sibling); try again once.
+        if (!this.#name(el, id, fallback)) {
+            queueMicrotask(() => {
+                this.#name(el, id, fallback);
+            });
+        }
+    }
+    #name(el, id, fallback) {
+        const target = findInScope(el, id);
+        if (target !== null && reflects(el)) {
+            el.ariaLabelledByElements = [target];
+            return true;
+        }
+        const text = fallback ?? target?.textContent.trim() ?? '';
+        if (text !== '')
+            el.setAttribute('aria-label', text);
+        return target !== null;
+    }
+}
+export const labelledBy = directive(LabelledBy);
+//# sourceMappingURL=accessible-name.js.map

package/dist/accessible-name.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"accessible-name.js","sourceRoot":"","sources":["../src/accessible-name.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,2FAA2F;AAC3F,6FAA6F;AAC7F,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAM1D,yFAAyF;AACzF,MAAM,QAAQ,GAAG,CAAC,EAAW,EAAoB,EAAE,CAAC,wBAAwB,IAAI,EAAE,CAAC;AAEnF,sFAAsF;AACtF,MAAM,UAAU,WAAW,CAAC,IAAa,EAAE,EAAU;IACnD,KAAK,IAAI,IAAI,GAAS,IAAI,CAAC,WAAW,EAAE,IAAK,CAAC;QAC5C,MAAM,KAAK,GAAG,gBAAgB,IAAI,IAAI,CAAC,CAAC,CAAE,IAAyB,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAC9F,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC;QACnD,IAAI,CAAC,CAAC,IAAI,YAAY,UAAU,CAAC;YAAE,OAAO,IAAI,CAAC;QAC/C,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;IACjC,CAAC;AACH,CAAC;AAID;;;;;;;;;GASG;AACH,MAAM,UAAW,SAAQ,gBAAiD;IACxE,QAAQ,GAAG,EAAE,CAAC;IAEd,KAAK,CAAC,EAAW,EAAE,CAAC,EAAE,EAAE,QAAQ,CAAkC;QAChE,MAAM,GAAG,GAAG,GAAG,EAAE,SAAS,QAAQ,IAAI,EAAE,EAAE,CAAC;QAC3C,IAAI,GAAG,KAAK,IAAI,CAAC,QAAQ;YAAE,OAAO;QAClC,IAAI,CAAC,QAAQ,GAAG,GAAG,CAAC;QACpB,qFAAqF;QACrF,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,EAAE,QAAQ,CAAC,EAAE,CAAC;YAClC,cAAc,CAAC,GAAG,EAAE;gBAClB,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,EAAE,QAAQ,CAAC,CAAC;YAC/B,CAAC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,KAAK,CAAC,EAAW,EAAE,EAAU,EAAE,QAA4B;QACzD,MAAM,MAAM,GAAG,WAAW,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;QACnC,IAAI,MAAM,KAAK,IAAI,IAAI,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;YACpC,EAAE,CAAC,sBAAsB,GAAG,CAAC,MAAM,CAAC,CAAC;YACrC,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,IAAI,GAAG,QAAQ,IAAI,MAAM,EAAE,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC;QAC1D,IAAI,IAAI,KAAK,EAAE;YAAE,EAAE,CAAC,YAAY,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;QACrD,OAAO,MAAM,KAAK,IAAI,CAAC;IACzB,CAAC;CACF;AAED,MAAM,CAAC,MAAM,UAAU,GAAG,SAAS,CAAC,UAAU,CAAC,CAAC","sourcesContent":["// Accessible names across shadow boundaries (gyral-czi.26). `aria-labelledby=\"page-title\"` inside\n// a shadow root can't see an id in the page, so a form or landmark in a component would be\n// nameless. `labelledBy(id)` resolves the id outward through the shadow-including ancestors.\nimport { directive } from 'lit/directive.js';\nimport { ElementDirective } from './element-directive.js';\n\ninterface Reflecting extends Element {\n  ariaLabelledByElements: readonly Element[] | null;\n}\n\n/** ARIA element reflection: newly available Baseline, so feature-detected (ADR 0003). */\nconst reflects = (el: Element): el is Reflecting => 'ariaLabelledByElements' in el;\n\n/** The element with `id`, searched from `from`'s own root outward to the document. */\nexport function findInScope(from: Element, id: string): Element | null {\n  for (let root: Node = from.getRootNode(); ;) {\n    const found = 'getElementById' in root ? (root as DocumentOrShadow).getElementById(id) : null;\n    if (found !== null && found !== from) return found;\n    if (!(root instanceof ShadowRoot)) return null;\n    root = root.host.getRootNode();\n  }\n}\n\ntype DocumentOrShadow = Document | ShadowRoot;\n\n/**\n * Names the element after the element with `id`, even outside this component's shadow root:\n *\n *   <form aria-label=${props.label} ${labelledBy('page-title')}>\n *\n * Uses `ariaLabelledByElements` (ARIA element reflection) where the browser has it, so the name\n * stays in sync with the heading. Elsewhere it sets `aria-label` from `fallback`, or from the\n * target's text. Element directives don't run on the server, so render a plain `aria-label` too\n * (from a `label` prop) for the no-JS page: `aria-labelledby` wins over it once set.\n */\nclass LabelledBy extends ElementDirective<[id: string, fallback?: string]> {\n  #applied = '';\n\n  apply(el: Element, [id, fallback]: [id: string, fallback?: string]): void {\n    const key = `${id}\\u0000${fallback ?? ''}`;\n    if (key === this.#applied) return;\n    this.#applied = key;\n    // The labelling element may render after this one (a later sibling); try again once.\n    if (!this.#name(el, id, fallback)) {\n      queueMicrotask(() => {\n        this.#name(el, id, fallback);\n      });\n    }\n  }\n\n  #name(el: Element, id: string, fallback: string | undefined): boolean {\n    const target = findInScope(el, id);\n    if (target !== null && reflects(el)) {\n      el.ariaLabelledByElements = [target];\n      return true;\n    }\n    const text = fallback ?? target?.textContent.trim() ?? '';\n    if (text !== '') el.setAttribute('aria-label', text);\n    return target !== null;\n  }\n}\n\nexport const labelledBy = directive(LabelledBy);\n"]}

package/dist/children.d.ts

@@ -0,0 +1,37 @@
+import type { Command } from './command.js';
+import type { IntentParser, Tagged } from './types.js';
+/** Marker driver: `define()` handles emit commands itself, synchronously ordered. */
+export declare const EMIT: {
+    readonly name: "@gyral/emit";
+    readonly run: () => undefined;
+};
+/**
+ * A command that sends `output` to the parent component. The parent receives it as an
+ * intent on the child element: `<my-child data-intent=${i.Picked}>` + `child(MyChild, …)`.
+ */
+export declare function emit(output: Tagged & Readonly<Record<string, unknown>>): Command<never>;
+/**
+ * Sends an output to the parent component. A microtask keeps outputs in order and out of the
+ * parent's render pass; the event bubbles through the parent's shadow tree only (not composed).
+ */
+export declare function dispatchOutput(host: Element, output: unknown): void;
+/** Anything `child()` can read an output type from: a `define()` class. */
+export interface OutputSource<O extends Tagged, E extends Element> {
+    new (): E;
+    /** Type-only marker for the component's output union. Never set at runtime. */
+    readonly outputs?: O;
+}
+/** A child class, or a function returning it (for recursive or later-defined components). */
+export type ChildSource<O extends Tagged, E extends Element> = OutputSource<O, E> | (() => OutputSource<O, E>);
+/**
+ * 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:
+ *
+ *   const Folder: GyralElementClass<State, Msg, Props, Out> = define('x-folder', {
+ *     intent: { Child: child(() => Folder, (out, el) => …) }, …
+ *   });
+ */
+export declare function child<O extends Tagged, E extends Element, M>(source: ChildSource<O, E>, toMsg: (output: O, el: E) => M | undefined): IntentParser<M>;

package/dist/children.js

@@ -0,0 +1,49 @@
+import { OUTPUT_EVENT } from './intent.js';
+/** Marker driver: `define()` handles emit commands itself, synchronously ordered. */
+export const EMIT = {
+    name: '@gyral/emit',
+    run: () => undefined,
+};
+/**
+ * A command that sends `output` to the parent component. The parent receives it as an
+ * intent on the child element: `<my-child data-intent=${i.Picked}>` + `child(MyChild, …)`.
+ */
+export function emit(output) {
+    return { driver: EMIT, input: output, onSuccess: () => undefined };
+}
+/**
+ * Sends an output to the parent component. A microtask keeps outputs in order and out of the
+ * parent's render pass; the event bubbles through the parent's shadow tree only (not composed).
+ */
+export function dispatchOutput(host, output) {
+    queueMicrotask(() => {
+        if (!host.isConnected)
+            return;
+        host.dispatchEvent(new CustomEvent(OUTPUT_EVENT, { detail: output, bubbles: true, composed: false }));
+    });
+}
+// Classes have a prototype; arrow functions (the lazy form) do not.
+const resolveSource = (source) => 'prototype' in source && source.prototype !== undefined
+    ? source
+    : source();
+/**
+ * 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:
+ *
+ *   const Folder: GyralElementClass<State, Msg, Props, Out> = define('x-folder', {
+ *     intent: { Child: child(() => Folder, (out, el) => …) }, …
+ *   });
+ */
+export function child(source, toMsg) {
+    return (input) => {
+        const type = resolveSource(source); // resolved per event, so the lazy form never hits TDZ
+        if (!(input.target instanceof type) || input.detail === undefined)
+            return undefined;
+        // Sound: only `emit()` from a component of this class dispatches this detail.
+        return toMsg(input.detail, input.target);
+    };
+}
+//# sourceMappingURL=children.js.map

package/dist/children.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"children.js","sourceRoot":"","sources":["../src/children.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,qFAAqF;AACrF,MAAM,CAAC,MAAM,IAAI,GAAG;IAClB,IAAI,EAAE,aAAa;IACnB,GAAG,EAAE,GAAG,EAAE,CAAC,SAAS;CACZ,CAAC;AAEX;;;GAGG;AACH,MAAM,UAAU,IAAI,CAAC,MAAkD;IACrE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,SAAS,EAAE,CAAC;AACrE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,IAAa,EAAE,MAAe;IAC3D,cAAc,CAAC,GAAG,EAAE;QAClB,IAAI,CAAC,IAAI,CAAC,WAAW;YAAE,OAAO;QAC9B,IAAI,CAAC,aAAa,CAChB,IAAI,WAAW,CAAC,YAAY,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAClF,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAaD,oEAAoE;AACpE,MAAM,aAAa,GAAG,CACpB,MAAyB,EACL,EAAE,CACtB,WAAW,IAAI,MAAM,IAAI,MAAM,CAAC,SAAS,KAAK,SAAS;IACrD,CAAC,CAAE,MAA6B;IAChC,CAAC,CAAE,MAAmC,EAAE,CAAC;AAE7C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,KAAK,CACnB,MAAyB,EACzB,KAA0C;IAE1C,OAAO,CAAC,KAAkB,EAAE,EAAE;QAC5B,MAAM,IAAI,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,sDAAsD;QAC1F,IAAI,CAAC,CAAC,KAAK,CAAC,MAAM,YAAY,IAAI,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QACpF,8EAA8E;QAC9E,OAAO,KAAK,CAAC,KAAK,CAAC,MAAW,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAChD,CAAC,CAAC;AACJ,CAAC","sourcesContent":["// Child components: props down, outputs up (docs/design-docs/0010-child-components.md).\nimport type { Command } from './command.js';\nimport { OUTPUT_EVENT } from './intent.js';\nimport type { IntentInput, IntentParser, Tagged } from './types.js';\n\n/** Marker driver: `define()` handles emit commands itself, synchronously ordered. */\nexport const EMIT = {\n  name: '@gyral/emit',\n  run: () => undefined,\n} as const;\n\n/**\n * A command that sends `output` to the parent component. The parent receives it as an\n * intent on the child element: `<my-child data-intent=${i.Picked}>` + `child(MyChild, …)`.\n */\nexport function emit(output: Tagged & Readonly<Record<string, unknown>>): Command<never> {\n  return { driver: EMIT, input: output, onSuccess: () => undefined };\n}\n\n/**\n * Sends an output to the parent component. A microtask keeps outputs in order and out of the\n * parent's render pass; the event bubbles through the parent's shadow tree only (not composed).\n */\nexport function dispatchOutput(host: Element, output: unknown): void {\n  queueMicrotask(() => {\n    if (!host.isConnected) return;\n    host.dispatchEvent(\n      new CustomEvent(OUTPUT_EVENT, { detail: output, bubbles: true, composed: false }),\n    );\n  });\n}\n\n/** Anything `child()` can read an output type from: a `define()` class. */\nexport interface OutputSource<O extends Tagged, E extends Element> {\n  new (): E;\n  /** Type-only marker for the component's output union. Never set at runtime. */\n  readonly outputs?: O;\n}\n\n/** A child class, or a function returning it (for recursive or later-defined components). */\nexport type ChildSource<O extends Tagged, E extends Element> =\n  OutputSource<O, E> | (() => OutputSource<O, E>);\n\n// Classes have a prototype; arrow functions (the lazy form) do not.\nconst resolveSource = <O extends Tagged, E extends Element>(\n  source: ChildSource<O, E>,\n): OutputSource<O, E> =>\n  'prototype' in source && source.prototype !== undefined\n    ? (source as OutputSource<O, E>)\n    : (source as () => OutputSource<O, E>)();\n\n/**\n * Intent parser for a child component's outputs, typed by the child's output union.\n * `el` is the child element, for reading its props (an item id, for example).\n *\n * Pass `() => Child` when the class isn't defined yet, e.g. a component that contains\n * itself; annotate the constant's type so TypeScript accepts the self-reference:\n *\n *   const Folder: GyralElementClass<State, Msg, Props, Out> = define('x-folder', {\n *     intent: { Child: child(() => Folder, (out, el) => …) }, …\n *   });\n */\nexport function child<O extends Tagged, E extends Element, M>(\n  source: ChildSource<O, E>,\n  toMsg: (output: O, el: E) => M | undefined,\n): IntentParser<M> {\n  return (input: IntentInput) => {\n    const type = resolveSource(source); // resolved per event, so the lazy form never hits TDZ\n    if (!(input.target instanceof type) || input.detail === undefined) return undefined;\n    // Sound: only `emit()` from a component of this class dispatches this detail.\n    return toMsg(input.detail as O, input.target);\n  };\n}\n"]}

package/dist/command.d.ts

@@ -0,0 +1,63 @@
+import type { IntentRejected } from './types.js';
+/** How commands in the same lane interact. See ADR 0006 for the table. */
+export type Concurrency = 'merge' | 'switch' | 'exhaust' | 'queue';
+export interface RetryPolicy {
+    /** Retries after the first failure. */
+    readonly times: number;
+    /** Delay before each retry (the base delay for exponential backoff). Default 0. */
+    readonly delayMs?: number;
+    readonly backoff?: 'fixed' | 'exponential';
+}
+export interface DriverContext<O = unknown> {
+    /** 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;
+}
+/** Performs one kind of side effect. A plain object: easy to fake in tests. */
+export interface Driver<I, O, E = unknown> {
+    readonly name: string;
+    readonly run: (input: I, ctx: DriverContext<O>) => O | Promise<O>;
+    /** Default policy for this driver's commands. Default `'merge'`. */
+    readonly concurrency?: Concurrency;
+    readonly retry?: RetryPolicy;
+    /** Turns a thrown or rejected value into this driver's typed error. */
+    readonly toError?: (cause: unknown) => E;
+}
+/** Any driver, with its input type erased. */
+export type AnyDriver = Driver<never, unknown>;
+/** Drivers substituted by name (test fakes, configured instances). */
+export type DriverOverrides = Readonly<Record<string, AnyDriver>>;
+/** A side effect described as data, plus pure mappers from its outcome to messages. */
+export interface Command<M> {
+    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, failures are logged and dropped. */
+    readonly onFailure?: (error: unknown) => M | undefined;
+}
+export interface CommandHandlers<O, E, MS, MF = MS> {
+    readonly onSuccess: (output: O) => MS | undefined;
+    readonly onFailure?: (error: E) => MF | undefined;
+    readonly key?: string;
+    readonly concurrency?: Concurrency;
+}
+/**
+ * What a reducer (or `init`) returns: new state, optionally with commands to run. Commands may
+ * also answer with the framework message `IntentRejected` (e.g. `submitForm` in @gyral/http
+ * when the server rejects a form), which goes to the optional `IntentRejected` reducer.
+ */
+export type Next<S, M> = S | readonly [S, ReadonlyArray<Command<M | IntentRejected>>];
+/** Identity helper so driver literals infer `I`, `O` and `E`. */
+export declare function defineDriver<I, O, E = unknown>(driver: Driver<I, O, E>): Driver<I, O, E>;
+/** Builds a command whose mappers are typed by the driver's input, output and error. */
+export declare function command<I, O, E, MS, MF = MS>(driver: Driver<I, O, E>, input: I, handlers: CommandHandlers<O, E, MS, MF>): Command<MS | MF>;
+/** Splits a reducer result into state and commands. State is never an array (ADR 0006). */
+export declare function splitNext<S, M>(next: Next<S, M>): readonly [S, ReadonlyArray<Command<M | IntentRejected>>];

package/dist/command.js

@@ -0,0 +1,26 @@
+/** Identity helper so driver literals infer `I`, `O` and `E`. */
+export function defineDriver(driver) {
+    return driver;
+}
+/** Builds a command whose mappers are typed by the driver's input, output and error. */
+// Two message parameters so success and failure may produce different variants.
+export function command(driver, input, handlers) {
+    const { onFailure, key, concurrency } = handlers;
+    return {
+        driver: driver,
+        input,
+        // Sound: the interpreter only passes this driver's output and toError() result.
+        onSuccess: (output) => handlers.onSuccess(output),
+        ...(onFailure === undefined ? {} : { onFailure: (error) => onFailure(error) }),
+        ...(key === undefined ? {} : { key }),
+        ...(concurrency === undefined ? {} : { concurrency }),
+    };
+}
+/** Splits a reducer result into state and commands. State is never an array (ADR 0006). */
+export function splitNext(next) {
+    if (Array.isArray(next) && next.length === 2 && Array.isArray(next[1])) {
+        return next;
+    }
+    return [next, []];
+}
+//# sourceMappingURL=command.js.map

package/dist/command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.js","sourceRoot":"","sources":["../src/command.ts"],"names":[],"mappings":"AAqEA,iEAAiE;AACjE,MAAM,UAAU,YAAY,CAAoB,MAAuB;IACrE,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,wFAAwF;AACxF,gFAAgF;AAChF,MAAM,UAAU,OAAO,CACrB,MAAuB,EACvB,KAAQ,EACR,QAAuC;IAEvC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,EAAE,GAAG,QAAQ,CAAC;IACjD,OAAO;QACL,MAAM,EAAE,MAAM;QACd,KAAK;QACL,gFAAgF;QAChF,SAAS,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,MAAW,CAAC;QACtD,GAAG,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,KAAc,EAAE,EAAE,CAAC,SAAS,CAAC,KAAU,CAAC,EAAE,CAAC;QAC5F,GAAG,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC;QACrC,GAAG,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC;KACtD,CAAC;AACJ,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,SAAS,CACvB,IAAgB;IAEhB,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACvE,OAAO,IAAgE,CAAC;IAC1E,CAAC;IACD,OAAO,CAAC,IAAS,EAAE,EAAE,CAAC,CAAC;AACzB,CAAC","sourcesContent":["// Effects as data (docs/design-docs/0006-effects-and-drivers.md). Plain TypeScript only:\nimport type { IntentRejected } from './types.js';\n// the interpreter lives in ./internal/ (ADR 0015).\n\n/** How commands in the same lane interact. See ADR 0006 for the table. */\nexport type Concurrency = 'merge' | 'switch' | 'exhaust' | 'queue';\n\nexport interface RetryPolicy {\n  /** Retries after the first failure. */\n  readonly times: number;\n  /** Delay before each retry (the base delay for exponential backoff). Default 0. */\n  readonly delayMs?: number;\n  readonly backoff?: 'fixed' | 'exponential';\n}\n\nexport interface DriverContext<O = unknown> {\n  /** Aborts when the command is switched away or its component disconnects. */\n  readonly signal: AbortSignal;\n  /**\n   * Delivers an extra result while the command runs (streaming drivers: routers, timers,\n   * sockets). Each value goes through the command's `onSuccess`. Ignored once the command\n   * has settled or been aborted. A streaming `run` usually never resolves; abort ends it.\n   */\n  readonly emit: (output: O) => void;\n}\n\n/** Performs one kind of side effect. A plain object: easy to fake in tests. */\nexport interface Driver<I, O, E = unknown> {\n  readonly name: string;\n  readonly run: (input: I, ctx: DriverContext<O>) => O | Promise<O>;\n  /** Default policy for this driver's commands. Default `'merge'`. */\n  readonly concurrency?: Concurrency;\n  readonly retry?: RetryPolicy;\n  /** Turns a thrown or rejected value into this driver's typed error. */\n  readonly toError?: (cause: unknown) => E;\n}\n\n/** Any driver, with its input type erased. */\nexport type AnyDriver = Driver<never, unknown>;\n\n/** Drivers substituted by name (test fakes, configured instances). */\nexport type DriverOverrides = Readonly<Record<string, AnyDriver>>;\n\n/** A side effect described as data, plus pure mappers from its outcome to messages. */\nexport interface Command<M> {\n  readonly driver: AnyDriver;\n  readonly input: unknown;\n  /** Concurrency lane. Default: the driver's name. */\n  readonly key?: string;\n  readonly concurrency?: Concurrency;\n  readonly onSuccess: (output: unknown) => M | undefined;\n  /** If omitted, failures are logged and dropped. */\n  readonly onFailure?: (error: unknown) => M | undefined;\n}\n\nexport interface CommandHandlers<O, E, MS, MF = MS> {\n  readonly onSuccess: (output: O) => MS | undefined;\n  readonly onFailure?: (error: E) => MF | undefined;\n  readonly key?: string;\n  readonly concurrency?: Concurrency;\n}\n\n/**\n * What a reducer (or `init`) returns: new state, optionally with commands to run. Commands may\n * also answer with the framework message `IntentRejected` (e.g. `submitForm` in @gyral/http\n * when the server rejects a form), which goes to the optional `IntentRejected` reducer.\n */\nexport type Next<S, M> = S | readonly [S, ReadonlyArray<Command<M | IntentRejected>>];\n\n/** Identity helper so driver literals infer `I`, `O` and `E`. */\nexport function defineDriver<I, O, E = unknown>(driver: Driver<I, O, E>): Driver<I, O, E> {\n  return driver;\n}\n\n/** Builds a command whose mappers are typed by the driver's input, output and error. */\n// Two message parameters so success and failure may produce different variants.\nexport function command<I, O, E, MS, MF = MS>(\n  driver: Driver<I, O, E>,\n  input: I,\n  handlers: CommandHandlers<O, E, MS, MF>,\n): Command<MS | MF> {\n  const { onFailure, key, concurrency } = handlers;\n  return {\n    driver: driver,\n    input,\n    // Sound: the interpreter only passes this driver's output and toError() result.\n    onSuccess: (output) => handlers.onSuccess(output as O),\n    ...(onFailure === undefined ? {} : { onFailure: (error: unknown) => onFailure(error as E) }),\n    ...(key === undefined ? {} : { key }),\n    ...(concurrency === undefined ? {} : { concurrency }),\n  };\n}\n\n/** Splits a reducer result into state and commands. State is never an array (ADR 0006). */\nexport function splitNext<S, M>(\n  next: Next<S, M>,\n): readonly [S, ReadonlyArray<Command<M | IntentRejected>>] {\n  if (Array.isArray(next) && next.length === 2 && Array.isArray(next[1])) {\n    return next as readonly [S, ReadonlyArray<Command<M | IntentRejected>>];\n  }\n  return [next as S, []];\n}\n"]}

package/dist/define.d.ts

@@ -0,0 +1,9 @@
+import type { GyralElementClass } from './element-types.js';
+import type { ComponentSpec, Tagged } from './types.js';
+export type { GyralElement, GyralElementClass } from './element-types.js';
+/**
+ * Compiles a Model-View-Intent spec into a custom element and registers it under `tag`.
+ * See docs/design-docs/0001-mvi-parsed-intent.md, 0006-effects-and-drivers.md, 0007-props.md
+ * 0008-forms.md and 0012-ssr.md.
+ */
+export declare function define<S, M extends Tagged, P extends object = object, O extends Tagged = never>(tag: string, spec: ComponentSpec<S, M, P>): GyralElementClass<S, M, P, O>;