@gyral/core 0.0.0 → 0.2.0

package/dist/textarea.js

@@ -0,0 +1,85 @@
+// <textarea> support (gyral-czi.34). Lit can't bind inside <textarea>: its content is raw
+// text, so `html\`<textarea>${v}</textarea>\`` throws during SSR ("Unexpected final
+// partIndex") and never updates in the browser. `textarea()` renders the element as a static,
+// escaped template (correct no-JS markup and a hydration match), then keeps it in sync by
+// setting properties and attributes on the same element.
+import { noChange } from 'lit';
+import { Directive, directive, PartType } from 'lit/directive.js';
+import { html as staticHtml, unsafeStatic } from 'lit/static-html.js';
+const escapeText = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+const escapeAttr = (s) => escapeText(s).replace(/"/g, '&quot;');
+const ATTR_NAME = /^[a-zA-Z_:][-a-zA-Z0-9_:.]*$/;
+function attrMarkup(attrs) {
+    return Object.entries(attrs ?? {})
+        .map(([name, value]) => {
+        if (!ATTR_NAME.test(name))
+            throw new Error(`textarea(): invalid attribute name "${name}"`);
+        if (value === false || value === null || value === undefined)
+            return '';
+        return value === true ? ` ${name}` : ` ${name}="${escapeAttr(String(value))}"`;
+    })
+        .join('');
+}
+/** The markup the server writes, and the client's first render: escaped, no bindings inside. */
+export function textareaMarkup({ value, attrs }) {
+    return `<textarea${attrMarkup(attrs)}>${escapeText(value)}</textarea>`;
+}
+function findTextarea(part) {
+    for (let node = part.startNode?.nextSibling; node && node !== part.endNode; node = node.nextSibling) {
+        if (node instanceof HTMLTextAreaElement)
+            return node;
+    }
+    return undefined;
+}
+function syncAttributes(el, attrs) {
+    for (const [name, value] of Object.entries(attrs ?? {})) {
+        if (value === false || value === null || value === undefined)
+            el.removeAttribute(name);
+        else
+            el.setAttribute(name, value === true ? '' : String(value));
+    }
+}
+class TextareaDirective extends Directive {
+    /** The model value last applied, so typing isn't overwritten by an unchanged model. */
+    #applied;
+    constructor(info) {
+        super(info);
+        if (info.type !== PartType.CHILD) {
+            throw new Error('textarea() must be used in a child position: html`${textarea({…})}`');
+        }
+    }
+    render(options) {
+        return staticHtml `${unsafeStatic(textareaMarkup(options))}`;
+    }
+    update(part, [options]) {
+        const el = findTextarea(part);
+        if (el === undefined) {
+            // First render (client) or hydration (server markup already in place): same template.
+            this.#applied = options.value;
+            return this.render(options);
+        }
+        syncAttributes(el, options.attrs);
+        if (this.#applied === undefined) {
+            // Hydration: the server's element is already here. Keep whatever the user typed before
+            // the script loaded; only later model changes write the value.
+            this.#applied = options.value;
+            return noChange;
+        }
+        if (options.value !== this.#applied) {
+            this.#applied = options.value;
+            if (el.value !== options.value)
+                el.value = options.value;
+        }
+        return noChange;
+    }
+}
+/**
+ * A `<textarea>` whose content comes from the model, safe for SSR and hydration:
+ *
+ *   ${textarea({ value: s.message, attrs: { name: 'message', rows: 5, required: true,
+ *                                            'data-intent': i.Message } })}
+ *
+ * Text typed before or after hydration is kept until the model's value changes.
+ */
+export const textarea = directive(TextareaDirective);
+//# sourceMappingURL=textarea.js.map

package/dist/textarea.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"textarea.js","sourceRoot":"","sources":["../src/textarea.ts"],"names":[],"mappings":"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","sourcesContent":["// <textarea> support (gyral-czi.34). Lit can't bind inside <textarea>: its content is raw\n// text, so `html\\`<textarea>${v}</textarea>\\`` throws during SSR (\"Unexpected final\n// partIndex\") and never updates in the browser. `textarea()` renders the element as a static,\n// escaped template (correct no-JS markup and a hydration match), then keeps it in sync by\n// setting properties and attributes on the same element.\nimport { noChange } from 'lit';\nimport { Directive, directive, PartType, type ChildPart, type PartInfo } from 'lit/directive.js';\nimport { html as staticHtml, unsafeStatic } from 'lit/static-html.js';\n\nexport type TextareaAttribute = string | number | boolean | null | undefined;\n\nexport interface TextareaOptions {\n  /** The model's value. Applied to the live element only when the model changes. */\n  readonly value: string;\n  /** Attributes such as name, id, rows, required, maxlength, data-intent, aria-invalid. */\n  readonly attrs?: Readonly<Record<string, TextareaAttribute>>;\n}\n\nconst escapeText = (s: string): string =>\n  s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');\nconst escapeAttr = (s: string): string => escapeText(s).replace(/\"/g, '&quot;');\nconst ATTR_NAME = /^[a-zA-Z_:][-a-zA-Z0-9_:.]*$/;\n\nfunction attrMarkup(attrs: TextareaOptions['attrs']): string {\n  return Object.entries(attrs ?? {})\n    .map(([name, value]) => {\n      if (!ATTR_NAME.test(name)) throw new Error(`textarea(): invalid attribute name \"${name}\"`);\n      if (value === false || value === null || value === undefined) return '';\n      return value === true ? ` ${name}` : ` ${name}=\"${escapeAttr(String(value))}\"`;\n    })\n    .join('');\n}\n\n/** The markup the server writes, and the client's first render: escaped, no bindings inside. */\nexport function textareaMarkup({ value, attrs }: TextareaOptions): string {\n  return `<textarea${attrMarkup(attrs)}>${escapeText(value)}</textarea>`;\n}\n\nfunction findTextarea(part: ChildPart): HTMLTextAreaElement | undefined {\n  for (\n    let node = part.startNode?.nextSibling;\n    node && node !== part.endNode;\n    node = node.nextSibling\n  ) {\n    if (node instanceof HTMLTextAreaElement) return node;\n  }\n  return undefined;\n}\n\nfunction syncAttributes(el: HTMLTextAreaElement, attrs: TextareaOptions['attrs']): void {\n  for (const [name, value] of Object.entries(attrs ?? {})) {\n    if (value === false || value === null || value === undefined) el.removeAttribute(name);\n    else el.setAttribute(name, value === true ? '' : String(value));\n  }\n}\n\nclass TextareaDirective extends Directive {\n  /** The model value last applied, so typing isn't overwritten by an unchanged model. */\n  #applied: string | undefined;\n\n  constructor(info: PartInfo) {\n    super(info);\n    if (info.type !== PartType.CHILD) {\n      throw new Error('textarea() must be used in a child position: html`${textarea({…})}`');\n    }\n  }\n\n  override render(options: TextareaOptions): unknown {\n    return staticHtml`${unsafeStatic(textareaMarkup(options))}`;\n  }\n\n  override update(part: ChildPart, [options]: [TextareaOptions]): unknown {\n    const el = findTextarea(part);\n    if (el === undefined) {\n      // First render (client) or hydration (server markup already in place): same template.\n      this.#applied = options.value;\n      return this.render(options);\n    }\n    syncAttributes(el, options.attrs);\n    if (this.#applied === undefined) {\n      // Hydration: the server's element is already here. Keep whatever the user typed before\n      // the script loaded; only later model changes write the value.\n      this.#applied = options.value;\n      return noChange;\n    }\n    if (options.value !== this.#applied) {\n      this.#applied = options.value;\n      if (el.value !== options.value) el.value = options.value;\n    }\n    return noChange;\n  }\n}\n\n/**\n * A `<textarea>` whose content comes from the model, safe for SSR and hydration:\n *\n *   ${textarea({ value: s.message, attrs: { name: 'message', rows: 5, required: true,\n *                                            'data-intent': i.Message } })}\n *\n * Text typed before or after hydration is kept until the model's value changes.\n */\nexport const textarea = directive(TextareaDirective);\n"]}

package/dist/transitions.d.ts

@@ -0,0 +1,9 @@
+/** True when a view transition may run now (API present, motion not reduced). */
+export declare function canTransition(): boolean;
+/**
+ * Runs `update` inside `document.startViewTransition` when allowed, otherwise directly.
+ * `update` must resolve once the DOM reflects the new state. The returned promise settles when
+ * `update` has run. A transition skipped by a newer one still runs its update (per spec); its
+ * rejected `ready` is expected and swallowed.
+ */
+export declare function withViewTransition(update: () => Promise<void>): Promise<void>;

package/dist/transitions.js

@@ -0,0 +1,26 @@
+// View Transitions for define() components (ADR 0001 addendum). An ADR 0003 enhancement:
+// without the API, or with reduced motion requested, updates render normally.
+const supportsViewTransitions = (doc) => 'startViewTransition' in doc;
+const ignore = () => undefined;
+/** True when a view transition may run now (API present, motion not reduced). */
+export function canTransition() {
+    if (typeof document === 'undefined' || !supportsViewTransitions(document))
+        return false;
+    return !window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+}
+/**
+ * Runs `update` inside `document.startViewTransition` when allowed, otherwise directly.
+ * `update` must resolve once the DOM reflects the new state. The returned promise settles when
+ * `update` has run. A transition skipped by a newer one still runs its update (per spec); its
+ * rejected `ready` is expected and swallowed.
+ */
+export function withViewTransition(update) {
+    if (!canTransition() || !supportsViewTransitions(document))
+        return update();
+    return new Promise((resolve, reject) => {
+        const transition = document.startViewTransition(() => update().then(resolve, reject));
+        transition.ready.catch(ignore);
+        transition.finished.catch(ignore);
+    });
+}
+//# sourceMappingURL=transitions.js.map

package/dist/transitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transitions.js","sourceRoot":"","sources":["../src/transitions.ts"],"names":[],"mappings":"AAAA,yFAAyF;AACzF,8EAA8E;AAW9E,MAAM,uBAAuB,GAAG,CAAC,GAAa,EAA4C,EAAE,CAC1F,qBAAqB,IAAI,GAAG,CAAC;AAE/B,MAAM,MAAM,GAAG,GAAS,EAAE,CAAC,SAAS,CAAC;AAErC,iFAAiF;AACjF,MAAM,UAAU,aAAa;IAC3B,IAAI,OAAO,QAAQ,KAAK,WAAW,IAAI,CAAC,uBAAuB,CAAC,QAAQ,CAAC;QAAE,OAAO,KAAK,CAAC;IACxF,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,kCAAkC,CAAC,CAAC,OAAO,CAAC;AACxE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAA2B;IAC5D,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,uBAAuB,CAAC,QAAQ,CAAC;QAAE,OAAO,MAAM,EAAE,CAAC;IAC5E,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,UAAU,GAAG,QAAQ,CAAC,mBAAmB,CAAC,GAAG,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;QACtF,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAC/B,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;AACL,CAAC","sourcesContent":["// View Transitions for define() components (ADR 0001 addendum). An ADR 0003 enhancement:\n// without the API, or with reduced motion requested, updates render normally.\n\ninterface ViewTransitionLike {\n  readonly ready: Promise<unknown>;\n  readonly finished: Promise<unknown>;\n}\n\ninterface ViewTransitionDocument {\n  startViewTransition(update: () => Promise<void>): ViewTransitionLike;\n}\n\nconst supportsViewTransitions = (doc: Document): doc is Document & ViewTransitionDocument =>\n  'startViewTransition' in doc;\n\nconst ignore = (): void => undefined;\n\n/** True when a view transition may run now (API present, motion not reduced). */\nexport function canTransition(): boolean {\n  if (typeof document === 'undefined' || !supportsViewTransitions(document)) return false;\n  return !window.matchMedia('(prefers-reduced-motion: reduce)').matches;\n}\n\n/**\n * Runs `update` inside `document.startViewTransition` when allowed, otherwise directly.\n * `update` must resolve once the DOM reflects the new state. The returned promise settles when\n * `update` has run. A transition skipped by a newer one still runs its update (per spec); its\n * rejected `ready` is expected and swallowed.\n */\nexport function withViewTransition(update: () => Promise<void>): Promise<void> {\n  if (!canTransition() || !supportsViewTransitions(document)) return update();\n  return new Promise((resolve, reject) => {\n    const transition = document.startViewTransition(() => update().then(resolve, reject));\n    transition.ready.catch(ignore);\n    transition.finished.catch(ignore);\n  });\n}\n"]}

package/dist/types.d.ts

@@ -0,0 +1,186 @@
+import type { PropertyDeclaration } from 'lit';
+import type { Styles } from './styles.js';
+import type { CommandInfo } from './invokers.js';
+import type { HydrateStrategy } from './islands.js';
+import type { DriverOverrides, Next } from './command.js';
+import type { AnyStore, StoreChanged, StoreRef } from './store.js';
+/** Every message is a tagged object; the tag is also the intent name used in markup. */
+export interface Tagged {
+    readonly _tag: string;
+}
+/** What the intent layer sees when a `data-intent` element fires its trigger event. */
+export interface IntentInput {
+    /** The `data-intent` value (a message tag). */
+    readonly name: string;
+    readonly event: Event;
+    /** The element carrying `data-intent`. */
+    readonly target: Element;
+    /** `value` of the input, select, textarea or button that carries the intent. */
+    readonly value: string | undefined;
+    /** `checked` for checkbox and radio inputs. */
+    readonly checked: boolean | undefined;
+    /** Submitted data (including the submitter button) when the intent is on a `<form>`. */
+    readonly formData: FormData | undefined;
+    /** The output a child component emitted, when the intent is on a child element. */
+    readonly detail: unknown;
+    /** `KeyboardEvent.key` for `keydown`/`keyup` intents. */
+    readonly key: string | undefined;
+    /** For `toggle` intents (popover, `<details>`): the state it changed to. */
+    readonly newState: 'open' | 'closed' | undefined;
+    /** For `command` intents: the invoker's command (e.g. `--clear`) and source (gyral-czi.6). */
+    readonly command: CommandInfo | undefined;
+}
+/** Reads a declared store's current state, typed by the store (ADR 0013). */
+export type StoreReader = <S>(store: StoreRef<S>) => S;
+/** Read-only context handed to every reducer and to the view (ADR 0007, 0013). */
+export interface Ctx<P> {
+    /** Props from above. */
+    readonly props: P;
+    /** Stores from the side: `read(cart).lines`. The store must be in `spec.stores`. */
+    readonly read: StoreReader;
+}
+/** Framework message: declared props changed after the first render (ADR 0007). */
+export interface PropsChanged<P> {
+    readonly _tag: 'PropsChanged';
+    readonly props: P;
+    readonly prev: P;
+}
+/**
+ * Framework message: the component is live in the browser (ADR 0012 addendum). Sent once,
+ * after the first client render has completed, to every client-side instance. Use it for
+ * progressive enhancement: render the no-JS form on the server and in the first client render
+ * (so hydration matches), then switch to the enhanced UI in the `Hydrated` reducer.
+ */
+export interface Hydrated {
+    readonly _tag: 'Hydrated';
+    /** `true` when the instance resumed from server-rendered markup (a hydration seed). */
+    readonly serverRendered: boolean;
+}
+/** One validation problem. `path` is dot-joined and matches the field's `name`. */
+export interface FieldIssue {
+    readonly path: string;
+    readonly message: string;
+}
+/** Submitted text values of a form (Files are dropped: they can't be re-filled). */
+export type FormFields = Readonly<Record<string, string | readonly string[]>>;
+/** Framework message: an intent's input failed schema validation (ADR 0008). */
+export interface IntentRejected {
+    readonly _tag: 'IntentRejected';
+    /** The `data-intent` name whose input was rejected. */
+    readonly intent: string;
+    readonly issues: readonly FieldIssue[];
+    /**
+     * For `form()` rejections: what the user submitted, so the view can re-fill the form. On
+     * the no-JS path (ADR 0008 server half) the server re-renders the page from this.
+     */
+    readonly values?: FormFields | undefined;
+}
+type ParseResult<M> = M | IntentRejected | undefined;
+/**
+ * Parses a platform event into one message variant, `IntentRejected`, or `undefined` to
+ * ignore it. May be async because schema validation may be.
+ */
+export type IntentParser<M> = (input: IntentInput) => ParseResult<M> | Promise<ParseResult<M>>;
+type Variant<M extends Tagged, K extends M['_tag']> = Extract<M, {
+    readonly _tag: K;
+}>;
+/** Intent parsers keyed by the message tag they produce. Messages from drivers need none. */
+export type Intents<M extends Tagged> = {
+    readonly [K in M['_tag']]?: IntentParser<Variant<M, K>>;
+};
+type Reducer<S, M, Msg, P> = (state: S, msg: Msg, ctx: Ctx<P>) => Next<S, M>;
+/**
+ * One pure reducer per message tag (exhaustive by construction), plus optional reducers
+ * for framework messages. Reducers may return commands.
+ */
+export type Update<S, M extends Tagged, P = object> = {
+    readonly [K in M['_tag']]: Reducer<S, M, Variant<M, K>, P>;
+} & {
+    readonly PropsChanged?: Reducer<S, M, PropsChanged<P>, P>;
+    readonly IntentRejected?: Reducer<S, M, IntentRejected, P>;
+    readonly StoreChanged?: Reducer<S, M, StoreChanged, P>;
+    readonly Hydrated?: Reducer<S, M, Hydrated, P>;
+};
+/** Typed intent names handed to the view, so `data-intent=${i.Increment}` is checked. */
+export type IntentNames<M extends Tagged> = {
+    readonly [K in M['_tag']]: K;
+};
+/**
+ * One prop's declaration: Lit's `PropertyDeclaration` plus Gyral's honesty rule (ADR 0007
+ * addendum). A prop is `undefined` until a parent, an attribute or a hydration seed sets it,
+ * so a prop whose type excludes `undefined` must say how that is guaranteed:
+ * - `required: true`: a missing value is a bug, reported once per instance at first render;
+ * - `default: value`: used whenever the element's value is `undefined`.
+ * A prop whose type includes `undefined` needs neither.
+ */
+export type PropDeclaration<T> = PropertyDeclaration & (undefined extends T ? {
+    readonly required?: false;
+    readonly default?: T;
+} : {
+    readonly required: true;
+    readonly default?: undefined;
+} | {
+    readonly required?: false;
+    readonly default: T;
+});
+export type PropDeclarations<P> = {
+    readonly [K in keyof P]-?: PropDeclaration<P[K]>;
+};
+/** State of a component that keeps none (a pure view of its props). Its `init` is optional. */
+export type Stateless = Readonly<Record<string, never>>;
+/** Initial model state (and optional commands), computed from props on first render. */
+type Init<S, M, P> = (props: P) => Next<S, M>;
+type InitField<S, M extends Tagged, P> = Stateless extends S ? {
+    readonly init?: Init<S, M, P>;
+} : {
+    readonly init: Init<S, M, P>;
+};
+export type ComponentSpec<S, M extends Tagged, P> = SpecBody<S, M, P> & InitField<S, M, P>;
+interface SpecBody<S, M extends Tagged, P> {
+    /** Lit reactive property declarations: the component's inputs. */
+    readonly props?: PropDeclarations<P>;
+    /** INTENT: platform events to messages. */
+    readonly intent: Intents<M>;
+    /** MODEL: pure state transitions. */
+    readonly update: Update<S, M, P>;
+    /** VIEW: pure function of state and props. Name intents in markup; never attach closures. */
+    readonly view: (state: S, intents: IntentNames<M>, ctx: Ctx<P>) => unknown;
+    /**
+     * Shadow-root styles: `css` templates, plain CSS strings, `CSSStyleSheet`s, or arrays of
+     * them. Ignored (with a warning) when `shadow: false`.
+     */
+    readonly styles?: Styles;
+    /**
+     * `false` renders the view as the element's own light-DOM children (ADR 0014): document CSS
+     * applies, and the server writes plain children instead of a `<template shadowrootmode>`.
+     * For page-level components (listings, articles). No `<slot>`s and no `styles`. Default `true`.
+     */
+    readonly shadow?: boolean;
+    /**
+     * When a server-rendered instance hydrates (gyral-4k7.4): `load` (default), `idle`,
+     * `visible` (scrolled into view) or `interaction` (first pointer/focus). Client-only
+     * renders are unaffected.
+     */
+    readonly hydrate?: HydrateStrategy;
+    /** Extra event types that may trigger intents via `data-intent-on` (e.g. `pointerdown`). */
+    readonly events?: readonly string[];
+    /** Driver substitutions by name, for every instance (ADR 0006). */
+    readonly drivers?: DriverOverrides;
+    /**
+     * Stores this component reads with `ctx.read(store)` and writes with `send(store, msg)`.
+     * Their changes re-render it (and reach the optional `StoreChanged` reducer). ADR 0013.
+     */
+    readonly stores?: readonly AnyStore[];
+    /**
+     * Return `true` to render this state change inside a View Transition (route changes, list
+     * reorders). Skipped without browser support or when reduced motion is requested.
+     */
+    readonly viewTransition?: (prev: S, next: S, msg: Tagged) => boolean;
+    /**
+     * Boolean facts about the state, exposed to CSS as custom states:
+     * `states: (s) => ({ loading: s._tag === 'Loading' })` enables `:host(:state(loading))` and
+     * `gy-x:state(loading)`. Applied after each render; feature-detected; not on the server.
+     */
+    readonly states?: (state: S) => Readonly<Record<string, boolean>>;
+}
+export {};

package/dist/types.js

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

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"","sourcesContent":["import type { PropertyDeclaration } from 'lit';\nimport type { Styles } from './styles.js';\nimport type { CommandInfo } from './invokers.js';\nimport type { HydrateStrategy } from './islands.js';\nimport type { DriverOverrides, Next } from './command.js';\nimport type { AnyStore, StoreChanged, StoreRef } from './store.js';\n\n/** Every message is a tagged object; the tag is also the intent name used in markup. */\nexport interface Tagged {\n  readonly _tag: string;\n}\n\n/** What the intent layer sees when a `data-intent` element fires its trigger event. */\nexport interface IntentInput {\n  /** The `data-intent` value (a message tag). */\n  readonly name: string;\n  readonly event: Event;\n  /** The element carrying `data-intent`. */\n  readonly target: Element;\n  /** `value` of the input, select, textarea or button that carries the intent. */\n  readonly value: string | undefined;\n  /** `checked` for checkbox and radio inputs. */\n  readonly checked: boolean | undefined;\n  /** Submitted data (including the submitter button) when the intent is on a `<form>`. */\n  readonly formData: FormData | undefined;\n  /** The output a child component emitted, when the intent is on a child element. */\n  readonly detail: unknown;\n  /** `KeyboardEvent.key` for `keydown`/`keyup` intents. */\n  readonly key: string | undefined;\n  /** For `toggle` intents (popover, `<details>`): the state it changed to. */\n  readonly newState: 'open' | 'closed' | undefined;\n  /** For `command` intents: the invoker's command (e.g. `--clear`) and source (gyral-czi.6). */\n  readonly command: CommandInfo | undefined;\n}\n\n/** Reads a declared store's current state, typed by the store (ADR 0013). */\nexport type StoreReader = <S>(store: StoreRef<S>) => S;\n\n/** Read-only context handed to every reducer and to the view (ADR 0007, 0013). */\nexport interface Ctx<P> {\n  /** Props from above. */\n  readonly props: P;\n  /** Stores from the side: `read(cart).lines`. The store must be in `spec.stores`. */\n  readonly read: StoreReader;\n}\n\n/** Framework message: declared props changed after the first render (ADR 0007). */\nexport interface PropsChanged<P> {\n  readonly _tag: 'PropsChanged';\n  readonly props: P;\n  readonly prev: P;\n}\n\n/**\n * Framework message: the component is live in the browser (ADR 0012 addendum). Sent once,\n * after the first client render has completed, to every client-side instance. Use it for\n * progressive enhancement: render the no-JS form on the server and in the first client render\n * (so hydration matches), then switch to the enhanced UI in the `Hydrated` reducer.\n */\nexport interface Hydrated {\n  readonly _tag: 'Hydrated';\n  /** `true` when the instance resumed from server-rendered markup (a hydration seed). */\n  readonly serverRendered: boolean;\n}\n\n/** One validation problem. `path` is dot-joined and matches the field's `name`. */\nexport interface FieldIssue {\n  readonly path: string;\n  readonly message: string;\n}\n\n/** Submitted text values of a form (Files are dropped: they can't be re-filled). */\nexport type FormFields = Readonly<Record<string, string | readonly string[]>>;\n\n/** Framework message: an intent's input failed schema validation (ADR 0008). */\nexport interface IntentRejected {\n  readonly _tag: 'IntentRejected';\n  /** The `data-intent` name whose input was rejected. */\n  readonly intent: string;\n  readonly issues: readonly FieldIssue[];\n  /**\n   * For `form()` rejections: what the user submitted, so the view can re-fill the form. On\n   * the no-JS path (ADR 0008 server half) the server re-renders the page from this.\n   */\n  // `| undefined` so schemas with plain optional fields (valibot `optional`) can produce it.\n  readonly values?: FormFields | undefined;\n}\n\ntype ParseResult<M> = M | IntentRejected | undefined;\n\n/**\n * Parses a platform event into one message variant, `IntentRejected`, or `undefined` to\n * ignore it. May be async because schema validation may be.\n */\nexport type IntentParser<M> = (input: IntentInput) => ParseResult<M> | Promise<ParseResult<M>>;\n\ntype Variant<M extends Tagged, K extends M['_tag']> = Extract<M, { readonly _tag: K }>;\n\n/** Intent parsers keyed by the message tag they produce. Messages from drivers need none. */\nexport type Intents<M extends Tagged> = {\n  readonly [K in M['_tag']]?: IntentParser<Variant<M, K>>;\n};\n\ntype Reducer<S, M, Msg, P> = (state: S, msg: Msg, ctx: Ctx<P>) => Next<S, M>;\n\n/**\n * One pure reducer per message tag (exhaustive by construction), plus optional reducers\n * for framework messages. Reducers may return commands.\n */\nexport type Update<S, M extends Tagged, P = object> = {\n  readonly [K in M['_tag']]: Reducer<S, M, Variant<M, K>, P>;\n} & {\n  readonly PropsChanged?: Reducer<S, M, PropsChanged<P>, P>;\n  readonly IntentRejected?: Reducer<S, M, IntentRejected, P>;\n  readonly StoreChanged?: Reducer<S, M, StoreChanged, P>;\n  readonly Hydrated?: Reducer<S, M, Hydrated, P>;\n};\n\n/** Typed intent names handed to the view, so `data-intent=${i.Increment}` is checked. */\nexport type IntentNames<M extends Tagged> = { readonly [K in M['_tag']]: K };\n\n/**\n * One prop's declaration: Lit's `PropertyDeclaration` plus Gyral's honesty rule (ADR 0007\n * addendum). A prop is `undefined` until a parent, an attribute or a hydration seed sets it,\n * so a prop whose type excludes `undefined` must say how that is guaranteed:\n * - `required: true`: a missing value is a bug, reported once per instance at first render;\n * - `default: value`: used whenever the element's value is `undefined`.\n * A prop whose type includes `undefined` needs neither.\n */\nexport type PropDeclaration<T> = PropertyDeclaration &\n  (undefined extends T\n    ? { readonly required?: false; readonly default?: T }\n    : | { readonly required: true; readonly default?: undefined }\n      | { readonly required?: false; readonly default: T });\n\nexport type PropDeclarations<P> = { readonly [K in keyof P]-?: PropDeclaration<P[K]> };\n\n/** State of a component that keeps none (a pure view of its props). Its `init` is optional. */\nexport type Stateless = Readonly<Record<string, never>>;\n\n/** Initial model state (and optional commands), computed from props on first render. */\ntype Init<S, M, P> = (props: P) => Next<S, M>;\n\n// `init` may be omitted only when an empty object is a valid state (Stateless, all-optional).\ntype InitField<S, M extends Tagged, P> = Stateless extends S\n  ? { readonly init?: Init<S, M, P> }\n  : { readonly init: Init<S, M, P> };\n\nexport type ComponentSpec<S, M extends Tagged, P> = SpecBody<S, M, P> & InitField<S, M, P>;\n\ninterface SpecBody<S, M extends Tagged, P> {\n  /** Lit reactive property declarations: the component's inputs. */\n  readonly props?: PropDeclarations<P>;\n  /** INTENT: platform events to messages. */\n  readonly intent: Intents<M>;\n  /** MODEL: pure state transitions. */\n  readonly update: Update<S, M, P>;\n  /** VIEW: pure function of state and props. Name intents in markup; never attach closures. */\n  readonly view: (state: S, intents: IntentNames<M>, ctx: Ctx<P>) => unknown;\n  /**\n   * Shadow-root styles: `css` templates, plain CSS strings, `CSSStyleSheet`s, or arrays of\n   * them. Ignored (with a warning) when `shadow: false`.\n   */\n  readonly styles?: Styles;\n  /**\n   * `false` renders the view as the element's own light-DOM children (ADR 0014): document CSS\n   * applies, and the server writes plain children instead of a `<template shadowrootmode>`.\n   * For page-level components (listings, articles). No `<slot>`s and no `styles`. Default `true`.\n   */\n  readonly shadow?: boolean;\n  /**\n   * When a server-rendered instance hydrates (gyral-4k7.4): `load` (default), `idle`,\n   * `visible` (scrolled into view) or `interaction` (first pointer/focus). Client-only\n   * renders are unaffected.\n   */\n  readonly hydrate?: HydrateStrategy;\n  /** Extra event types that may trigger intents via `data-intent-on` (e.g. `pointerdown`). */\n  readonly events?: readonly string[];\n  /** Driver substitutions by name, for every instance (ADR 0006). */\n  readonly drivers?: DriverOverrides;\n  /**\n   * Stores this component reads with `ctx.read(store)` and writes with `send(store, msg)`.\n   * Their changes re-render it (and reach the optional `StoreChanged` reducer). ADR 0013.\n   */\n  readonly stores?: readonly AnyStore[];\n  /**\n   * Return `true` to render this state change inside a View Transition (route changes, list\n   * reorders). Skipped without browser support or when reduced motion is requested.\n   */\n  readonly viewTransition?: (prev: S, next: S, msg: Tagged) => boolean;\n  /**\n   * Boolean facts about the state, exposed to CSS as custom states:\n   * `states: (s) => ({ loading: s._tag === 'Loading' })` enables `:host(:state(loading))` and\n   * `gy-x:state(loading)`. Applied after each render; feature-detected; not on the server.\n   */\n  readonly states?: (state: S) => Readonly<Record<string, boolean>>;\n}\n"]}

package/dist/vite.d.ts

@@ -0,0 +1,25 @@
+/** Every Lit package: resolve exactly one copy, even when Gyral is linked from elsewhere. */
+export declare const LIT_PACKAGES: readonly string[];
+/**
+ * Lit modules that Gyral imports or re-exports. Pre-bundling them up front stops Vite from
+ * discovering them mid-run, which reloads the page and fails the first browser test run.
+ */
+export declare const LIT_PREBUNDLE: readonly string[];
+export interface GyralViteOptions {
+    /** More modules to pre-bundle (e.g. 'lit/directives/unsafe-html.js'). */
+    readonly optimize?: readonly string[];
+}
+export interface GyralViteConfig {
+    readonly resolve: {
+        readonly dedupe: string[];
+    };
+    readonly optimizeDeps: {
+        readonly include: string[];
+    };
+}
+/**
+ * Spread into a Vite config, or into each Vitest project:
+ *
+ *   export default defineConfig({ ...gyralVitePreset(), build: { … } });
+ */
+export declare function gyralVitePreset(options?: GyralViteOptions): GyralViteConfig;

package/dist/vite.js

@@ -0,0 +1,37 @@
+// Vite / Vitest settings every Gyral app needs (gyral-a7r, docs/references/consumer-setup.md).
+// Plain data, no imports: safe to load from vite.config.ts and vitest.config.ts.
+/** Every Lit package: resolve exactly one copy, even when Gyral is linked from elsewhere. */
+export const LIT_PACKAGES = [
+    'lit',
+    'lit-html',
+    'lit-element',
+    '@lit/reactive-element',
+    '@lit-labs/ssr',
+    '@lit-labs/ssr-client',
+];
+/**
+ * Lit modules that Gyral imports or re-exports. Pre-bundling them up front stops Vite from
+ * discovering them mid-run, which reloads the page and fails the first browser test run.
+ */
+export const LIT_PREBUNDLE = [
+    'lit',
+    'lit/directive.js',
+    'lit/static-html.js',
+    'lit/directives/class-map.js',
+    'lit/directives/keyed.js',
+    'lit/directives/live.js',
+    'lit/directives/repeat.js',
+    'lit/directives/style-map.js',
+];
+/**
+ * Spread into a Vite config, or into each Vitest project:
+ *
+ *   export default defineConfig({ ...gyralVitePreset(), build: { … } });
+ */
+export function gyralVitePreset(options = {}) {
+    return {
+        resolve: { dedupe: [...LIT_PACKAGES] },
+        optimizeDeps: { include: [...new Set([...LIT_PREBUNDLE, ...(options.optimize ?? [])])] },
+    };
+}
+//# sourceMappingURL=vite.js.map

package/dist/vite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite.js","sourceRoot":"","sources":["../src/vite.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,iFAAiF;AAEjF,6FAA6F;AAC7F,MAAM,CAAC,MAAM,YAAY,GAAsB;IAC7C,KAAK;IACL,UAAU;IACV,aAAa;IACb,uBAAuB;IACvB,eAAe;IACf,sBAAsB;CACvB,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAsB;IAC9C,KAAK;IACL,kBAAkB;IAClB,oBAAoB;IACpB,6BAA6B;IAC7B,yBAAyB;IACzB,wBAAwB;IACxB,0BAA0B;IAC1B,6BAA6B;CAC9B,CAAC;AAYF;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,UAA4B,EAAE;IAC5D,OAAO;QACL,OAAO,EAAE,EAAE,MAAM,EAAE,CAAC,GAAG,YAAY,CAAC,EAAE;QACtC,YAAY,EAAE,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,aAAa,EAAE,GAAG,CAAC,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE;KACzF,CAAC;AACJ,CAAC","sourcesContent":["// Vite / Vitest settings every Gyral app needs (gyral-a7r, docs/references/consumer-setup.md).\n// Plain data, no imports: safe to load from vite.config.ts and vitest.config.ts.\n\n/** Every Lit package: resolve exactly one copy, even when Gyral is linked from elsewhere. */\nexport const LIT_PACKAGES: readonly string[] = [\n  'lit',\n  'lit-html',\n  'lit-element',\n  '@lit/reactive-element',\n  '@lit-labs/ssr',\n  '@lit-labs/ssr-client',\n];\n\n/**\n * Lit modules that Gyral imports or re-exports. Pre-bundling them up front stops Vite from\n * discovering them mid-run, which reloads the page and fails the first browser test run.\n */\nexport const LIT_PREBUNDLE: readonly string[] = [\n  'lit',\n  'lit/directive.js',\n  'lit/static-html.js',\n  'lit/directives/class-map.js',\n  'lit/directives/keyed.js',\n  'lit/directives/live.js',\n  'lit/directives/repeat.js',\n  'lit/directives/style-map.js',\n];\n\nexport interface GyralViteOptions {\n  /** More modules to pre-bundle (e.g. 'lit/directives/unsafe-html.js'). */\n  readonly optimize?: readonly string[];\n}\n\nexport interface GyralViteConfig {\n  readonly resolve: { readonly dedupe: string[] };\n  readonly optimizeDeps: { readonly include: string[] };\n}\n\n/**\n * Spread into a Vite config, or into each Vitest project:\n *\n *   export default defineConfig({ ...gyralVitePreset(), build: { … } });\n */\nexport function gyralVitePreset(options: GyralViteOptions = {}): GyralViteConfig {\n  return {\n    resolve: { dedupe: [...LIT_PACKAGES] },\n    optimizeDeps: { include: [...new Set([...LIT_PREBUNDLE, ...(options.optimize ?? [])])] },\n  };\n}\n"]}

package/package.json

@@ -1,16 +1,10 @@
 {
   "name": "@gyral/core",
-  "version": "0.0.0",
-  "description": "Coming soon — https://gyral.dev",
-  "keywords": [
-    "gyral",
-    "web-components",
-    "lit",
-    "mvi"
-  ],
+  "version": "0.2.0",
+  "description": "Gyral core: Model-View-Intent web components on Lit and the web platform. Inspired by Cycle.js.",
   "license": "MIT",
-  "author": "The Zoop Troop, Inc.",
-  "homepage": "https://gyral.dev",
+  "author": "Mike Zupper",
+  "homepage": "https://github.com/gyraljs/gyral/tree/main/packages/core#readme",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/gyraljs/gyral.git",
@@ -19,7 +13,41 @@
   "bugs": {
     "url": "https://github.com/gyraljs/gyral/issues"
   },
-  "publishConfig": {
-    "access": "public"
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "default": "./dist/vite.js"
+    }
+  },
+  "imports": {
+    "#devtools": {
+      "development": "./dist/devtools.js",
+      "default": "./dist/devtools-off.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "@standard-schema/spec": "1.1.0"
+  },
+  "peerDependencies": {
+    "lit": "^3.3.0"
+  },
+  "devDependencies": {
+    "lit": "3.3.3"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build-package.mjs"
   }
-}
+}