@menapo/machine 0.0.0-stage → 0.1.0

package/dist/component-DDXOyYUI.d.ts

@@ -0,0 +1,147 @@
+import { n as Tables, o as Interpreter, t as State } from "./machine-BstWHtWL.js";
+//#region src/parts/compile.d.ts
+/** A framework's attribute name for a part key: React keeps `onClick`, Svelte writes `onclick`. */
+type Naming = (key: string) => string;
+/** An attribute function or a handler as the instance calls it. */
+type AttrFn = (view: never) => unknown;
+type HandlerFn = (view: never, event: unknown) => void;
+interface Part {
+  readonly name: string;
+  /** Static attributes, renamed, in the order written. */
+  readonly statics: readonly (readonly [string, unknown])[];
+  /** Attribute functions' names, renamed, and the functions. */
+  readonly keys: readonly string[];
+  readonly fns: readonly AttrFn[];
+  /** Handlers: the renamed key, and an event name or a function of `(view, domEvent)`. */
+  readonly on: readonly (readonly [string, string | HandlerFn])[];
+  /** Where its attribute values start in an instance's values array. */
+  readonly at: number;
+  /**
+   * Its props object with every key in place, values to come: an
+   * instance's first object is a copy, so every instance's has one shape.
+   */
+  readonly template: Readonly<Record<string, unknown>>;
+}
+interface Compiled {
+  readonly parts: readonly Part[];
+  /** `api.parts` with every part's key in place: each view's is a copy. */
+  readonly record: Readonly<Record<string, undefined>>;
+  /** Attribute functions over every part: an instance's values array is this long. */
+  readonly size: number;
+}
+//#endregion
+//#region src/parts/component.d.ts
+type Owner = Readonly<Record<string, unknown>>;
+type Props = Record<string, unknown>;
+/** What tells a vanilla view of visible changes and stops it (the vanilla adapter), else the view itself. */
+interface Listen {
+  subscribe(listener: () => void): () => void;
+  stop(): void;
+}
+/**
+ * What `useMachine` returns: `state`, `is`, `send`, `context`, `parts`, and
+ * a getter for each value `expose` returns (a class per machine adds them).
+ * Every getter reads the component's current snapshot, after the
+ * framework's tracker (`t`: Vue, Svelte and Solid record the read; React
+ * and Preact have none). React and Preact get a new one per view version,
+ * since they compare by identity (React's Compiler too); the others keep
+ * one for the component's life. Reading `state`, `is` or `context` marks
+ * them watched, so a change to them renders even when no part shows it.
+ */
+declare class View {
+  readonly $: Component;
+  readonly t: (() => unknown) | undefined;
+  readonly u: Listen | undefined;
+  constructor(component: Component, track?: () => unknown, listen?: Listen);
+  get parts(): Readonly<Record<string, Readonly<Props>>>;
+  get state(): string;
+  get is(): (state: string) => boolean;
+  get context(): object;
+  get send(): Interpreter["send"];
+  setProps(props: object): void;
+  /**
+   * Stops the instance as an unmount does: its effects and timers, and in
+   * plain code its listeners. A framework's glue does it when the component
+   * goes; plain code calls it when the element goes.
+   */
+  stop(): void;
+  /** Calls `listener` after each visible change. */
+  subscribe(listener: () => void): () => void;
+}
+/** What a component keeps once rendered. */
+interface Rendered {
+  readonly pc: Compiled;
+  /** Per part: its props object and the bits its attribute functions read. */
+  readonly po: Props[];
+  readonly pr: number[];
+  /** Every part's attribute values, from each part's `at`. */
+  readonly pa: unknown[];
+  /** `api.parts` for {@link rv}, the version it was made at. */
+  rec: Readonly<Record<string, Readonly<Props>>> | undefined;
+  rv: number;
+  /** The view for {@link vv}, the version it was made at (React, Preact). */
+  vo: View | undefined;
+  vv: number;
+}
+declare class Component extends Interpreter {
+  /** The instance id: the framework's (`useId`), or the owner's `id`. */
+  readonly id: string;
+  /** The framework's attribute names. */
+  readonly nm: Naming;
+  /** Bits changed since the last snapshot. */
+  cc: number;
+  /** Bits the component read through its view (`state`, `is`, `context`). */
+  wa: number;
+  /** The view version. */
+  pv: number;
+  /** 1 while mounted: effects may start. */
+  y: number;
+  /** 1 when effects wait for a commit, which a render must bring. */
+  fx: number;
+  /** Effects deferred until the next commit. */
+  w: State[] | undefined;
+  /** Parts, once rendered. */
+  rd: Rendered | undefined;
+  /** `expose`'s last result and the bits it read. */
+  xo: Props | undefined;
+  xr: number;
+  ir: Owner | undefined;
+  er: object | undefined;
+  constructor(machine: Tables, owner: Owner | undefined, id: string, naming: Naming);
+  /** `data-scope`: the machine's name. */
+  get scope(): string;
+  /** `ids.<part>`: `<name>:<id>:<part>`, stable for the instance and the same on server and client. */
+  get ids(): Owner;
+  /** `el.<part>`: the part's element, found by its id when read. */
+  get el(): object;
+  activate(states: readonly State[]): void;
+  exit(at: State): void;
+  /**
+   * Starts what `states` run as one step (D3): what an effect sends waits
+   * until every effect has started, then runs to completion and is told,
+   * as when the core starts them. Inside a listener (the vanilla glue
+   * commits there) the event being handled does that.
+   */
+  begin(states: readonly State[]): void;
+  /** After the first commit (and again after StrictMode's remount): starts what the active states run. */
+  mount(): void;
+  unmount(): void;
+  /** After a commit: starts the timers and effects of states entered since, that are still active. */
+  commit(): void;
+  /**
+   * The view version: brings parts and `expose` up to date, and moves only
+   * when something shown changed. Before the first render it does nothing,
+   * so creating a component builds no parts.
+   */
+  snapshot(): number;
+  /** Renders every part the first time: each from its compiled template, then the instance's values. */
+  render(): Rendered;
+  /** What `expose` returns, computed again when `again` or not yet. */
+  exposed(again?: boolean): Props | undefined;
+  /** Every part's props object, by part: the same record until one changes. */
+  record(): Readonly<Record<string, Readonly<Props>>>;
+  /** The view for the current version, for frameworks that compare by identity: a new one only when something shown changed. */
+  view(): View;
+}
+//#endregion
+export { View as t };

package/dist/dev-BAz6e3W-.js

@@ -0,0 +1,79 @@
+//#region src/core/dev.ts
+/**
+* Dev errors and warnings (PLAN §4.11): each names the machine, what went
+* wrong and the fix, behind a code. Every caller sits behind `if (DEV)`, so
+* none of this reaches a production bundle.
+*/
+/** `[machine:CODE] name: message`. */
+const message = (code, machine, text) => `[machine:${code}] ${machine}: ${text}`;
+function fail(code, machine, text) {
+	throw new Error(message(code, machine, text));
+}
+const warned = /* @__PURE__ */ new Set();
+/** Warns once per distinct message, so a send in a loop does not flood the console. */
+function warnOnce(code, machine, text) {
+	const line = message(code, machine, text);
+	if (warned.has(line)) return;
+	warned.add(line);
+	console.warn(line);
+}
+/** Edit distance, for "did you mean". */
+function distance(a, b) {
+	let row = Array.from({ length: b.length + 1 }, (_, i) => i);
+	for (let i = 1; i <= a.length; i++) {
+		const next = [i];
+		for (let j = 1; j <= b.length; j++) next[j] = Math.min(row[j] + 1, next[j - 1] + 1, row[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+		row = next;
+	}
+	return row[b.length];
+}
+/** `; did you mean "closed"?` for the nearest of `options`, or "" when none is close. */
+function suggest(name, options) {
+	let best = "";
+	let score = Math.max(2, Math.floor(name.length / 3)) + 1;
+	for (const option of options) {
+		const d = distance(name.toLowerCase(), option.toLowerCase());
+		if (d < score) [best, score] = [option, d];
+	}
+	return best ? `; did you mean "${best}"?` : "";
+}
+/** Keys users bring from XState and Zag, with what they are called here. */
+const RENAMED = {
+	target: "to",
+	guard: "if",
+	cond: "if",
+	actions: "do",
+	effects: "effect",
+	onEntry: "entry",
+	onExit: "exit"
+};
+/** Fails on a key `config` should not have, naming the right one. */
+function checkKeys(config, allowed, machine, where) {
+	for (const key of Object.keys(config)) {
+		if (allowed.includes(key)) continue;
+		fail("UNKNOWN_KEY", machine, `${where} has an unknown key "${key}"${RENAMED[key] ? `; use "${RENAMED[key]}".` : suggest(key, allowed) || "."} Allowed: ${allowed.join(", ")}.`);
+	}
+}
+/** The DOM's spellings a part may not use, and React's, which every glue maps to its framework's. */
+const SPELLED = {
+	class: "className",
+	for: "htmlFor"
+};
+/**
+* Dev only: each part's handlers send an event some state handles, or are
+* functions; its keys are spelled as React spells them (`@menapo/glue/naming`).
+* Checked by the normaliser, so the plugin's compilation fails the build on
+* them, and when a compiled machine loads in development.
+*/
+function checkParts(config, name, handled) {
+	const parts = config.parts ?? {};
+	for (const part of Object.keys(parts)) for (const key of Object.keys(parts[part])) {
+		const value = parts[part][key];
+		if (/^on[A-Z]/.test(key)) {
+			if (typeof value !== "string" && typeof value !== "function") fail("BAD_HANDLER", name, `part "${part}" has ${key}: ${String(value)}; an on* key takes an event name or a function of (view, event).`);
+			if (typeof value === "string" && !handled.has(value)) fail("UNKNOWN_EVENT", name, `part "${part}" sends "${value}" from ${key}, which no state handles${suggest(value, handled) || "."} Handle it in a state's \`on\`, or send another event.`);
+		} else if (key in SPELLED || /^on[a-z]/.test(key)) fail("PART_KEY", name, `part "${part}" has "${key}"; parts use React's spellings, which each framework's glue maps to its own, so write "${SPELLED[key] ?? `on${key[2].toUpperCase()}${key.slice(3)}`}"${key in SPELLED ? "" : " with the event's words capitalised (onKeyDown, onDoubleClick)"}.`);
+	}
+}
+//#endregion
+export { warnOnce as a, suggest as i, checkParts as n, fail as r, checkKeys as t };

package/dist/dom.d.ts

@@ -0,0 +1,187 @@
+//#region src/dom/dismiss.d.ts
+interface DismissOptions {
+  /**
+   * Escape, a platform close request (Android's back gesture), or a
+   * `<dialog>` that closed without the machine (`<form method="dialog">`,
+   * a close request the page may not cancel).
+   */
+  onEscape?: () => void;
+  /** A pointer press, or focus, outside the element. */
+  onOutside?: () => void;
+  /** Presses and focus here are not outside: the trigger, so its own click toggles. */
+  exclude?: Element | null;
+}
+/**
+ * Reports Escape and interaction outside `element` to the machine instead
+ * of closing anything itself, so a controlled overlay can refuse (PLAN D9).
+ * Layers stack: Escape goes to the top layer with `onEscape`, and a press
+ * or focus outside to the top layer with `onOutside`, so Escape in a nested
+ * menu or dialog closes the inner one alone. A layer above is part of the
+ * one below: a press in a menu opened from a dialog is not outside the
+ * dialog. Escape that no layer handles is left to the page and the browser.
+ *
+ * On a modal `<dialog>`, a press on the `::backdrop` counts as outside, and
+ * Escape is reported without the browser closing the dialog behind the
+ * machine's back (`closedby` is not Baseline). When it closes all the same,
+ * `onEscape` hears it, and a machine that stays open gets it shown again.
+ */
+export declare function dismiss(element: Element, options: DismissOptions): () => void;
+//#endregion
+//#region src/dom/focus-trap.d.ts
+/**
+ * Keeps keyboard focus inside `container`, a modal overlay that is not a
+ * `<dialog>` (PLAN §4.5, §11): focus moves in (`[autofocus]`, else the first
+ * tabbable element, else the container), Tab and Shift+Tab wrap at the ends
+ * and are otherwise the browser's, focus that leaves is brought back (to
+ * the next element when Tab took it out, else to where it was), and the
+ * cleanup returns focus to where it was, or to `<body>` when that element
+ * is gone.
+ *
+ * Focus may sit in a layer opened above it with `dismiss` or another
+ * `focusTrap` (a menu, wherever it is rendered). A container with nothing
+ * to focus gets `tabindex="-1"` while the trap lasts.
+ *
+ * A modal `<dialog>` opened with `showModal()` needs none of this: the
+ * browser moves focus in, makes the page inert and restores focus on
+ * `close()`, and lets Tab reach its own UI, as it intends for every page.
+ */
+export declare function focusTrap(container: HTMLElement): () => void;
+//#endregion
+//#region src/dom/hide-others.d.ts
+/**
+ * Makes everything outside `keep` inert: out of the accessibility tree,
+ * unfocusable and deaf to the pointer, with no `aria-hidden` walk or focus
+ * trap to keep in step (PLAN D15, S5). For a modal overlay that is not a
+ * `<dialog>`; `showModal()` does the same for a `<dialog>`. An overlay in a
+ * shadow root keeps its hosts, and the rest of its shadow tree is hidden.
+ *
+ * Live regions with nothing focusable inside stay outside it, so
+ * announcements keep reaching screen readers, and elements the page made
+ * inert itself are left as they are. A layer opened above while it lasts
+ * (`dismiss` or `focusTrap`: a menu from the overlay, rendered elsewhere)
+ * is kept too, until that layer goes.
+ */
+export declare function hideOthers(...keep: Element[]): () => void;
+//#endregion
+//#region src/dom/live-region.d.ts
+/**
+ * Announces `message` to screen readers while the effect runs: politely
+ * (`status`), or interrupting (`alert`) when `assertive`. The cleanup
+ * withdraws it if it is still showing.
+ *
+ * The region lives in the topmost modal `<dialog>` open when the message
+ * lands, since everything outside a modal dialog is inert and silent, else
+ * in `<body>`;
+ * `hideOthers` leaves live regions out. It is created once and kept: a
+ * screen reader only follows regions that existed before their text changed.
+ */
+export declare function liveRegion(message: string, options?: {
+  assertive?: boolean;
+}): () => void;
+//#endregion
+//#region src/dom/place.d.ts
+/**
+ * Where a floating element goes next to its anchor: the arithmetic behind
+ * `popper`, with no DOM, so it is tested on plain numbers. Coordinates are
+ * the viewport's, as `getBoundingClientRect()` gives them.
+ */
+type Side = "top" | "right" | "bottom" | "left";
+/** A side, aligned to the anchor's centre, or to its start or end edge. */
+type Placement = Side | `${Side}-start` | `${Side}-end`;
+//#endregion
+//#region src/dom/popper.d.ts
+interface PopperOptions {
+  /** Default `"bottom"`. */
+  placement?: Placement;
+  /** Gap from the anchor in pixels; default 8. */
+  offset?: number;
+  /** Space kept from the viewport's edges; default 8. */
+  padding?: number;
+  /** Move to the opposite side when this one lacks room; default true. */
+  flip?: boolean;
+  /** Slide along the anchor to stay in the viewport; default true. */
+  shift?: boolean;
+  /** An element inside the floating one, moved to point at the anchor's centre. */
+  arrow?: HTMLElement | null;
+  /** Give the floating element the anchor's width (a listbox under its input). */
+  sameWidth?: boolean;
+}
+/**
+ * Keeps `floating` next to `anchor` while it is shown: placed, flipped and
+ * shifted inside the viewport, and moved again when either resizes, the
+ * window resizes or anything scrolls, once per animation frame
+ * (PLAN §4.5; no `popover` or anchor positioning while they are not Baseline
+ * widely available, D16).
+ *
+ * `floating` is positioned `fixed`, so its containing block must be the
+ * viewport: render it outside transformed, filtered or `contain`ed
+ * ancestors (a portal). The placement taken is set as `data-placement`
+ * for styles that depend on the side, the arrow's among them.
+ */
+export declare function popper(anchor: Element, floating: HTMLElement, options?: PopperOptions): () => void;
+//#endregion
+//#region src/dom/presence.d.ts
+/**
+ * Calls `onDone` once `element`'s CSS animations and transitions have
+ * finished, its `::before`, `::after` and `::backdrop`'s included, so a closing state can leave the element mounted until its exit
+ * animation ends (PLAN §4.5). Called after the state change that starts the
+ * animation: reading the element's animations applies its new styles first.
+ *
+ * Done on the next microtask when nothing runs, when the user prefers
+ * reduced motion, or when an animation is cancelled; infinite animations
+ * (a spinner inside the styles) are not waited for. The cleanup stops a
+ * pending call, for a state left before the animation ended.
+ *
+ * A `<dialog>` animates out only while it is open: `close()` it after
+ * `onDone`, in the cleanup of a state that holds both `open` and `closing`.
+ */
+export declare function presence(element: Element, onDone: () => void): () => void;
+//#endregion
+//#region src/dom/scroll-lock.d.ts
+/**
+ * Stops the page from scrolling under a modal overlay; the platform has no
+ * such lock (S5). Nested locks count: the page scrolls again when the last
+ * one is cleaned up.
+ *
+ * Hiding the root's overflow removes a classic scrollbar, so its width is
+ * added to the root's padding on the scrollbar's side and exposed as
+ * `--scrollbar-width` for fixed elements that must not shift either;
+ * under `scrollbar-gutter: stable` the space stays, and both are 0.
+ */
+export declare function scrollLock(): () => void;
+//#endregion
+//#region src/dom/spread.d.ts
+/**
+ * `spread(element, part)`: a part's props on an element without a framework
+ * (PLAN §4.4, §5.5's vanilla row), as `{...part}` does in JSX. Only what
+ * changed since the last spread onto the element is written; handlers are
+ * one listener per event type, which calls the part's current handler.
+ *
+ * - `on<event>`: the handler for `<event>`.
+ * - `aria-*` and `data-*`: the value as text, `false` included.
+ * - `value`, `checked`, `selected` and `indeterminate`: the element's
+ *   property, as frameworks set them (the attribute is only the default).
+ * - Others: `true` is the attribute present and empty; `false`, `null` and
+ *   `undefined` remove it.
+ */
+export declare function spread(element: Element, part: object): void;
+//#endregion
+//#region src/dom/typeahead.d.ts
+/**
+ * Typeahead for a part's `onKeyDown`: the item in `container` whose text
+ * starts with what was typed within the last second, or undefined. Items
+ * are the container's options, menu items and tree items that are not
+ * `aria-disabled` or hidden; the current one is the key's target, or the
+ * element its `aria-activedescendant` names. A key it uses has its default
+ * prevented, so a Space inside a query does not activate the item.
+ *
+ * ```ts
+ * onKeyDown: ({ el, send }, event) => {
+ *   const item = typeahead(event, el.content);
+ *   if (item) send("HIGHLIGHT", { id: item.id });
+ * },
+ * ```
+ */
+export declare function typeahead(event: KeyboardEvent, container: Element): HTMLElement | undefined;
+//#endregion
+export type { DismissOptions, Placement, PopperOptions };