@menapo/machine 0.0.0-stage → 0.1.0

package/dist/naming-Csj5186j.js

@@ -0,0 +1,492 @@
+import { r as fail } from "./dev-BAz6e3W-.js";
+import { c as swap, f as DEV, n as hook, p as dev, t as Interpreter, u as bit } from "./instance-BM2UqeXW.js";
+//#region src/parts/compile.ts
+const HANDLER = /^on[A-Z]/;
+const cache = /* @__PURE__ */ new WeakMap();
+/** Splits `machine.parts` for `naming`, once per machine and naming. */
+function compile(machine, naming) {
+	let byNaming = cache.get(machine);
+	if (!byNaming) cache.set(machine, byNaming = /* @__PURE__ */ new Map());
+	let compiled = byNaming.get(naming);
+	if (compiled) return compiled;
+	const parts = [];
+	let size = 0;
+	const config = machine.c.parts ?? {};
+	for (const name of Object.keys(config)) {
+		const statics = [];
+		const keys = [];
+		const fns = [];
+		const on = [];
+		const part = config[name];
+		for (const key of Object.keys(part)) {
+			const value = part[key];
+			if (HANDLER.test(key)) on.push([naming(key), value]);
+			else if (typeof value === "function") {
+				keys.push(naming(key));
+				fns.push(value);
+			} else statics.push([naming(key), value]);
+		}
+		const template = Object.fromEntries(statics);
+		template.id = void 0;
+		template["data-scope"] = machine.c.name ?? "machine";
+		template["data-part"] = name;
+		template["data-state"] = void 0;
+		for (const key of keys) template[key] = void 0;
+		for (const [key] of on) template[key] = void 0;
+		parts.push({
+			name,
+			statics,
+			keys,
+			fns,
+			on,
+			at: size,
+			template
+		});
+		size += fns.length;
+	}
+	const record = Object.fromEntries(parts.map((part) => [part.name, void 0]));
+	byNaming.set(naming, compiled = {
+		parts,
+		size,
+		record
+	});
+	return compiled;
+}
+//#endregion
+//#region src/parts/component.ts
+/**
+* A machine rendered by a framework (PLAN §4.4, §4.6, §5.4, §5.5): the
+* interpreter plus its parts, ids, elements and `expose`, and the lifecycle
+* the glue drives. Only the glue creates one, so a machine used without a
+* framework (`start`) ships none of this.
+*
+* - **Parts** are rebuilt only when a field one of their attribute functions
+*   read has changed (the change mask, accumulated between renders), and
+*   only into a copy of the previous object, which keeps its shape, its
+*   static attributes and its handlers (S3: "a precompiled shape"). A part
+*   whose values came out the same returns the same object.
+* - **Handlers** are made once per instance, so their identity never changes.
+* - **The view version** (`snapshot`) moves only when a part, `expose` or
+*   what the component read through the view itself changed: React renders
+*   once per visible change and never for an unhandled event (S3).
+* - **Effects and timers** start once the framework has committed the DOM
+*   (D13): never on a server, after the first commit, and after each commit
+*   that follows an event entering a state with effects.
+*/
+/** `instance.b`: the interpreter's IDLE, BUSY and STOPPED. */
+const IDLE = 0;
+const BUSY = 1;
+const STOPPED = 2;
+/**
+* Elements by part, read from the document when asked: a class per machine.
+* A part not in the document reads `undefined`, as does every part where
+* there is no document (a server render).
+*/
+const elementClasses = /* @__PURE__ */ new WeakMap();
+function elements(machine, ids) {
+	let Elements = elementClasses.get(machine);
+	if (!Elements) {
+		class Found {
+			$;
+			constructor(ids) {
+				this.$ = ids;
+			}
+		}
+		for (const part of Object.keys(machine.c.parts ?? {})) Object.defineProperty(Found.prototype, part, { get() {
+			return typeof document === "object" ? document.getElementById(this.$[part]) ?? void 0 : void 0;
+		} });
+		elementClasses.set(machine, Elements = Found);
+	}
+	return new Elements(ids);
+}
+/**
+* A part's props object copied with its new state: the precompiled shape
+* S3 asked for. Each of a machine's first eight parts is copied at a spread
+* of its own, so V8 sees one shape at each and copies it as a block; one
+* spread for every part sees them all and copies key by key, about three
+* times slower (`bench/machine`'s `props.changed`).
+*/
+function copy(p, old, state) {
+	let next;
+	switch (p) {
+		case 0:
+			next = { ...old };
+			break;
+		case 1:
+			next = { ...old };
+			break;
+		case 2:
+			next = { ...old };
+			break;
+		case 3:
+			next = { ...old };
+			break;
+		case 4:
+			next = { ...old };
+			break;
+		case 5:
+			next = { ...old };
+			break;
+		case 6:
+			next = { ...old };
+			break;
+		case 7:
+			next = { ...old };
+			break;
+		default: next = { ...old };
+	}
+	next["data-state"] = state;
+	return next;
+}
+/** The first listener of every component: collects what changed between renders. */
+function collect(instance) {
+	instance.cc |= instance.mask;
+}
+/** True when `at` is the leaf or one of its ancestors, or one of a parallel configuration's states. */
+function active(leaf, at) {
+	if (leaf.a) return leaf.a.includes(at);
+	for (let s = leaf; s; s = s.up) if (s === at) return true;
+	return false;
+}
+/**
+* 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.
+*/
+var View = class {
+	$;
+	t;
+	u;
+	constructor(component, track, listen) {
+		this.$ = component;
+		this.t = track;
+		this.u = listen;
+	}
+	get parts() {
+		this.t?.();
+		return this.$.record();
+	}
+	get state() {
+		this.t?.();
+		this.$.wa |= 1;
+		return this.$.s.path;
+	}
+	get is() {
+		this.t?.();
+		this.$.wa |= 1;
+		return this.$.is;
+	}
+	get context() {
+		this.t?.();
+		const { $ } = this;
+		$.wa |= bit($.M.nm.length - $.M.pn.length) - 1 << 1;
+		return $.context;
+	}
+	get send() {
+		return this.$.send;
+	}
+	setProps(props) {
+		this.$.setProps(props);
+	}
+	/**
+	* 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() {
+		if (this.u) this.u.stop();
+		else this.$.unmount();
+	}
+	/** Calls `listener` after each visible change. */
+	subscribe(listener) {
+		const { $, u } = this;
+		if (u) return u.subscribe(listener);
+		let seen = $.snapshot();
+		return $.subscribe(() => {
+			const now = $.snapshot();
+			if (now !== seen) {
+				seen = now;
+				listener();
+			}
+		});
+	}
+};
+const viewClasses = /* @__PURE__ */ new WeakMap();
+/** A view of `component`: {@link View}, with a getter for each key `expose` returns, on a class made once per machine. */
+function viewOf(component, track, listen) {
+	let Of = viewClasses.get(component.M);
+	if (!Of) {
+		Of = class extends View {};
+		for (const key of Object.keys(component.exposed() ?? {})) Object.defineProperty(Of.prototype, key, {
+			enumerable: true,
+			get() {
+				this.t?.();
+				this.$.snapshot();
+				return this.$.exposed()[key];
+			}
+		});
+		viewClasses.set(component.M, Of);
+	}
+	return new Of(component, track, listen);
+}
+/**
+* Dev only: props given as a function where the framework reads them as an
+* object on each render (React, Preact, plain code), which would ignore them.
+*/
+function objectProps(machine, props, framework) {
+	if (typeof props === "function") fail("PROPS", machine.c.name ?? "machine", `useMachine was given props as a function, which only Vue, Svelte and Solid read; in ${framework} pass the props object itself, on each render: useMachine(machine, { … }).`);
+}
+/** What the glue's adapters create: a component of `machine`, named for the framework. */
+const component = (machine, naming) => (id, owner) => new Component(machine, owner, id, naming);
+var Component = class extends Interpreter {
+	/** The instance id: the framework's (`useId`), or the owner's `id`. */
+	id;
+	/** The framework's attribute names. */
+	nm;
+	/** Bits changed since the last snapshot. */
+	cc = 0;
+	/** Bits the component read through its view (`state`, `is`, `context`). */
+	wa = 0;
+	/** The view version. */
+	pv = 0;
+	/** 1 while mounted: effects may start. */
+	y = 0;
+	/** 1 when effects wait for a commit, which a render must bring. */
+	fx = 0;
+	/** Effects deferred until the next commit. */
+	w;
+	/** Parts, once rendered. */
+	rd;
+	/** `expose`'s last result and the bits it read. */
+	xo;
+	xr = 0;
+	ir;
+	er;
+	constructor(machine, owner, id, naming) {
+		super(machine, void 0, owner);
+		this.id = owner?.id ?? id;
+		this.nm = naming;
+		this.l = [collect];
+	}
+	/** `data-scope`: the machine's name. */
+	get scope() {
+		return this.M.c.name ?? "machine";
+	}
+	/** `ids.<part>`: `<name>:<id>:<part>`, stable for the instance and the same on server and client. */
+	get ids() {
+		if (!this.ir) {
+			const ids = {};
+			const prefix = `${this.scope}:${this.id}:`;
+			for (const part of Object.keys(this.M.c.parts ?? {})) ids[part] = prefix + part;
+			this.ir = ids;
+		}
+		return this.ir;
+	}
+	/** `el.<part>`: the part's element, found by its id when read. */
+	get el() {
+		return this.er ??= elements(this.M, this.ids);
+	}
+	activate(states) {
+		if (this.y) {
+			(this.w ??= []).push(...states);
+			this.fx = 1;
+		}
+	}
+	exit(at) {
+		const w = this.w;
+		if (w) {
+			const k = w.indexOf(at);
+			if (k >= 0) w.splice(k, 1);
+		}
+		super.exit(at);
+	}
+	/**
+	* 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) {
+		if (!states.length || this.b === STOPPED) return;
+		if (this.b === BUSY) return super.activate(states);
+		this.b = BUSY;
+		try {
+			super.activate(states);
+			this.settle();
+			hook?.(this);
+		} finally {
+			if (this.b === BUSY) {
+				this.b = IDLE;
+				this.q = this.n = void 0;
+				if (DEV) dev.acting = 0;
+			}
+		}
+	}
+	/** After the first commit (and again after StrictMode's remount): starts what the active states run. */
+	mount() {
+		if (this.b === STOPPED && !this.s.fi) this.b = IDLE;
+		this.y = 1;
+		const chain = [];
+		const all = this.s.a;
+		if (all) {
+			for (const at of all) if (at.af || at.ef) chain.push(at);
+		} else for (let at = this.s; at; at = at.up) if (at.af || at.ef) chain.unshift(at);
+		this.w = void 0;
+		this.begin(chain);
+	}
+	unmount() {
+		this.y = 0;
+		this.stop();
+	}
+	/** After a commit: starts the timers and effects of states entered since, that are still active. */
+	commit() {
+		const w = this.w;
+		if (w && this.y) {
+			this.w = void 0;
+			this.begin(w.filter((at) => active(this.s, at)));
+		}
+	}
+	/**
+	* 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() {
+		const changed = this.cc;
+		if ((changed || this.fx) && (this.rd || this.xo)) {
+			this.cc = 0;
+			let moved = this.fx || changed & this.wa;
+			this.fx = 0;
+			const rd = this.rd;
+			if (rd) {
+				const { po, pr, pa } = rd;
+				const parts = rd.pc.parts;
+				const path = this.s.path;
+				for (let p = 0; p < parts.length; p++) {
+					if (!(pr[p] & changed)) continue;
+					const { keys, fns, at } = parts[p];
+					const outer = swap(0);
+					let dirty = false;
+					for (let k = 0; k < fns.length; k++) {
+						const value = fns[k](this);
+						if (value !== pa[at + k]) {
+							pa[at + k] = value;
+							dirty = true;
+						}
+					}
+					pr[p] = swap(outer) | 1;
+					const old = po[p];
+					if (!dirty && old["data-state"] === path) continue;
+					const next = copy(p, old, path);
+					for (let k = 0; k < keys.length; k++) next[keys[k]] = pa[at + k];
+					po[p] = next;
+					moved = 1;
+				}
+			}
+			if (this.xr & changed) {
+				this.exposed(true);
+				moved = 1;
+			}
+			if (moved) this.pv++;
+		}
+		return this.pv;
+	}
+	/** Renders every part the first time: each from its compiled template, then the instance's values. */
+	render() {
+		this.cc = this.fx = 0;
+		const pc = compile(this.M, this.nm);
+		this.exposed(true);
+		const rd = {
+			pc,
+			po: Array.from({ length: pc.parts.length }),
+			pr: Array.from({ length: pc.parts.length }),
+			pa: Array.from({ length: pc.size }),
+			rec: void 0,
+			rv: -1,
+			vo: void 0,
+			vv: -1
+		};
+		const path = this.s.path;
+		const ids = this.ids;
+		for (let p = 0; p < pc.parts.length; p++) {
+			const { name, keys, fns, at, on, template } = pc.parts[p];
+			const outer = swap(0);
+			for (let k = 0; k < fns.length; k++) rd.pa[at + k] = fns[k](this);
+			rd.pr[p] = swap(outer) | 1;
+			const object = copy(p, template, path);
+			object.id = ids[name];
+			for (let k = 0; k < keys.length; k++) object[keys[k]] = rd.pa[at + k];
+			for (const [key, handler] of on) object[key] = typeof handler === "string" ? () => this.dispatch(handler) : (event) => handler(this, event);
+			rd.po[p] = object;
+		}
+		return this.rd = rd;
+	}
+	/** What `expose` returns, computed again when `again` or not yet. */
+	exposed(again) {
+		const expose = this.M.c.expose;
+		if (expose && (again || !this.xo)) {
+			const outer = swap(0);
+			this.xo = expose(this);
+			this.xr = swap(outer);
+			if (DEV) {
+				for (const key of Object.keys(this.xo ?? {})) if (key in View.prototype || key === "$" || key === "t" || key === "u") fail("EXPOSE_KEY", this.M.name, `expose returns "${key}", which useMachine's result has already; rename it.`);
+			}
+		}
+		return this.xo;
+	}
+	/** Every part's props object, by part: the same record until one changes. */
+	record() {
+		const pv = this.snapshot();
+		const rd = this.rd ?? this.render();
+		if (rd.rv !== pv || !rd.rec) {
+			const { parts, record } = rd.pc;
+			const out = { ...record };
+			for (let p = 0; p < parts.length; p++) out[parts[p].name] = rd.po[p];
+			rd.rec = out;
+			rd.rv = pv;
+		}
+		return rd.rec;
+	}
+	/** The view for the current version, for frameworks that compare by identity: a new one only when something shown changed. */
+	view() {
+		const pv = this.snapshot();
+		const rd = this.rd ?? this.render();
+		if (rd.vv !== pv || !rd.vo) {
+			rd.vo = viewOf(this);
+			rd.vv = pv;
+		}
+		return rd.vo;
+	}
+};
+//#endregion
+//#region ../glue/src/naming.ts
+/** React's names whose DOM name is not their lowercase form. */
+const DOM = {
+	htmlFor: "for",
+	className: "class",
+	onDoubleClick: "onDblClick"
+};
+/** React's name as the DOM spells it, still camel-cased: `htmlFor` is `for`, `onDoubleClick` `onDblClick`. */
+const dom = (key) => DOM[key] ?? key;
+/** React: names as written. */
+const react = (key) => key;
+/** Preact and Solid take React's names but the DOM's attributes, and lowercase an event's name themselves. */
+const jsx = dom;
+/** Svelte and the DOM itself: lowercase (`onclick`, `tabindex`, `for`). */
+const lower = (key) => dom(key).toLowerCase();
+/**
+* Vue derives an event's name from the rest of an `on…` key, hyphenating
+* capitals (`onKeyDown` would listen for `key-down`), so a handler is
+* `onKeydown`; other names stay, but for the DOM's attributes.
+*/
+const vue = (key) => {
+	const name = dom(key);
+	return /^on[A-Z]/.test(name) ? name.slice(0, 3) + name.slice(3).toLowerCase() : name;
+};
+//#endregion
+export { component as a, vue as i, lower as n, objectProps as o, react as r, viewOf as s, jsx as t };

package/dist/records-7FFepzo9.js

@@ -0,0 +1,10 @@
+//#region src/features/records.ts
+const records = /* @__PURE__ */ new WeakMap();
+const recorded = (instance, history) => records.get(instance)?.get(history);
+function record(instance, history, states) {
+	let map = records.get(instance);
+	if (!map) records.set(instance, map = /* @__PURE__ */ new Map());
+	map.set(history, states);
+}
+//#endregion
+export { recorded as n, records as r, record as t };

package/dist/source-DdFTPjID.js

@@ -0,0 +1,15 @@
+//#region ../glue/src/source.ts
+/** Equal own values: a render passing equal props does not set them again. */
+function same(a, b) {
+	if (a === b) return true;
+	if (!a || !b) return false;
+	const keys = Object.keys(a);
+	if (keys.length !== Object.keys(b).length) return false;
+	for (const key of keys) if (!Object.is(a[key], b[key])) return false;
+	return true;
+}
+let ids = 0;
+/** An id for frameworks that give none (Svelte, vanilla): unique on the page, not across a server and its client. */
+const nextId = () => `m${++ids}`;
+//#endregion
+export { same as n, nextId as t };

package/dist/test.d.ts

@@ -0,0 +1,63 @@
+import { _ as InstanceOf, i as AnyMachine, k as StartOptions, n as AnyEvent, u as EventOf } from "./types-Bk8svtO6.js";
+import { t as Step } from "./inspect-C3qosuCm.js";
+//#region src/test/machine.d.ts
+/** What a test machine adds to the instance. */
+interface TestControls {
+  /** Moves its clock forward by `ms`, firing the timers due, in time order. */
+  advance(ms: number): void;
+  /** Fires every pending timer, and those they set, in time order, until none is left. */
+  runAll(): void;
+  /** Timers set on its clock and not yet fired or cleared. */
+  readonly pending: number;
+  /** Every event it took, from `machine.start`, with the state after it and what it changed. */
+  readonly steps: readonly Step[];
+  /** The states it settled in, from the initial one; a state repeated in a row counts once. */
+  readonly path: readonly string[];
+  /**
+   * Sends each event in turn; `machine.after` fires the next pending timer
+   * instead. A path from `paths()` replays this way.
+   */
+  play(events: readonly AnyEvent[]): void;
+}
+type TestMachine<M extends AnyMachine> = InstanceOf<M> & TestControls;
+/**
+ * Starts `machine` for a test: events run synchronously, timers wait for
+ * `advance` or `runAll`, and every event taken is recorded in `steps` and
+ * `path`.
+ */
+export declare function testMachine<M extends AnyMachine>(machine: M, options?: StartOptions<M>): TestMachine<M>;
+//#endregion
+//#region src/test/paths.d.ts
+type EventsOf<M extends AnyMachine> = NonNullable<M["types"]>["events"];
+interface PathOptions<M extends AnyMachine> extends StartOptions<M> {
+  /** Events in a path at most; 6 when left out. */
+  readonly depth?: number;
+  /** Paths at most; finding more is an error that says what to narrow. 1000 when left out. */
+  readonly limit?: number;
+  /**
+   * The data to try for events that carry some: each entry is sent as one
+   * event (`ADD: [{ by: 1 }, { by: -1 }]`). An event not listed is sent
+   * without data.
+   */
+  readonly events?: { readonly [K in keyof EventsOf<M> & string]?: readonly Omit<EventOf<EventsOf<M>, K>, "type">[]; };
+}
+interface Path {
+  /** The events, in order; `machine.after` stands for the next timer firing. */
+  readonly events: readonly AnyEvent[];
+  /** The state before the first event and after each one. */
+  readonly states: readonly string[];
+}
+/**
+ * Every path from the initial state that passes no state twice, up to
+ * `depth` events. A path ends when it reaches a final state, a state where
+ * nothing it can send does anything, `depth`, or a state with context it
+ * passed through before; the step back is part of the path, so every
+ * transition taken is covered. Events are those the current state handles,
+ * plus `machine.after` while a timer is pending. A state is its path and
+ * its context and props, compared as JSON, and what its history states
+ * recorded. In a parallel configuration the state is every active leaf, and
+ * the events tried are those any active state handles.
+ */
+export declare function paths<M extends AnyMachine>(machine: M, options?: PathOptions<M>): Path[];
+//#endregion
+export type { Path, PathOptions, Step, TestControls, TestMachine };