@menapo/machine 0.0.0-stage → 0.1.0

package/dist/types-Bk8svtO6.d.ts

@@ -0,0 +1,580 @@
+//#region src/parts/types.d.ts
+type Global = typeof globalThis;
+/**
+ * An event where the DOM's types are not loaded (a server's program, this
+ * package's own): what handlers read most, one shape for every name.
+ */
+interface BareEvent {
+  readonly type: string;
+  readonly key: string;
+  preventDefault(): void;
+}
+/** The DOM's event class `N` where the DOM's types are loaded, else a {@link BareEvent}. */
+type DomEvent<N extends string> = Global extends { [K in N]: {
+  prototype: infer E;
+}; } ? E : BareEvent;
+/**
+ * The DOM event a handler gets, by its name's prefix (`onKeyDown` a
+ * `KeyboardEvent`, `onPointerMove` a `PointerEvent`); a framework passes its
+ * own event object (React's synthetic event), which has the same fields.
+ */
+interface PartEvents {
+  readonly onKey: DomEvent<"KeyboardEvent">;
+  readonly onClick: DomEvent<"MouseEvent">;
+  readonly onDblClick: DomEvent<"MouseEvent">;
+  readonly onDoubleClick: DomEvent<"MouseEvent">;
+  readonly onAuxClick: DomEvent<"MouseEvent">;
+  readonly onContextMenu: DomEvent<"MouseEvent">;
+  readonly onMouse: DomEvent<"MouseEvent">;
+  readonly onPointer: DomEvent<"PointerEvent">;
+  readonly onWheel: DomEvent<"WheelEvent">;
+  readonly onTouch: DomEvent<"TouchEvent">;
+  readonly onDrag: DomEvent<"DragEvent">;
+  readonly onDrop: DomEvent<"DragEvent">;
+  readonly onFocus: DomEvent<"FocusEvent">;
+  readonly onBlur: DomEvent<"FocusEvent">;
+  readonly onBeforeInput: DomEvent<"InputEvent">;
+  readonly onInput: DomEvent<"Event">;
+  readonly onChange: DomEvent<"Event">;
+  readonly onSubmit: DomEvent<"SubmitEvent">;
+  readonly onReset: DomEvent<"Event">;
+  readonly onScroll: DomEvent<"Event">;
+  readonly onSelect: DomEvent<"Event">;
+  readonly onInvalid: DomEvent<"Event">;
+  readonly onToggle: DomEvent<"Event">;
+  readonly onCopy: DomEvent<"ClipboardEvent">;
+  readonly onCut: DomEvent<"ClipboardEvent">;
+  readonly onPaste: DomEvent<"ClipboardEvent">;
+  readonly onComposition: DomEvent<"CompositionEvent">;
+  readonly onAnimation: DomEvent<"AnimationEvent">;
+  readonly onTransition: DomEvent<"TransitionEvent">;
+}
+/** The event handler `K` gets: `PartEvent<"onKeyDown">` is a `KeyboardEvent`. */
+type PartEvent<K extends string = string> = { [P in keyof PartEvents]: K extends `${P}${string}` ? PartEvents[P] : never; }[keyof PartEvents] extends (infer E) ? [E] extends [never] ? DomEvent<"Event"> : E : never;
+/**
+ * A handler: a function of the view and the DOM event. Written as a method,
+ * so a handler of a narrower event (a `KeyboardEvent`) stands where one of
+ * any event is expected.
+ */
+type Handler<V, E> = {
+  h(view: V, event: E): unknown;
+}["h"];
+/** What a part's key holds when no handler prefix names it: a static value or an attribute function. */
+type Attribute<V> = string | number | boolean | null | undefined | Handler<V, unknown>;
+/**
+ * A part as written: static values, attribute functions of the view and
+ * `on*` handlers (one of the machine's events `Ev`, or a function of the view
+ * and the DOM event, typed by the handler's name: {@link PartEvents}).
+ */
+type PartConfig<V, Ev extends string = string> = {
+  readonly [key: string]: Attribute<V>;
+  readonly [key: `onKey${string}`]: Ev | Handler<V, PartEvents["onKey"]>;
+  readonly [key: `onClick${string}`]: Ev | Handler<V, PartEvents["onClick"]>;
+  readonly [key: `onDblClick${string}`]: Ev | Handler<V, PartEvents["onDblClick"]>;
+  readonly [key: `onDoubleClick${string}`]: Ev | Handler<V, PartEvents["onDoubleClick"]>;
+  readonly [key: `onAuxClick${string}`]: Ev | Handler<V, PartEvents["onAuxClick"]>;
+  readonly [key: `onContextMenu${string}`]: Ev | Handler<V, PartEvents["onContextMenu"]>;
+  readonly [key: `onMouse${string}`]: Ev | Handler<V, PartEvents["onMouse"]>;
+  readonly [key: `onPointer${string}`]: Ev | Handler<V, PartEvents["onPointer"]>;
+  readonly [key: `onWheel${string}`]: Ev | Handler<V, PartEvents["onWheel"]>;
+  readonly [key: `onTouch${string}`]: Ev | Handler<V, PartEvents["onTouch"]>;
+  readonly [key: `onDrag${string}`]: Ev | Handler<V, PartEvents["onDrag"]>;
+  readonly [key: `onDrop${string}`]: Ev | Handler<V, PartEvents["onDrop"]>;
+  readonly [key: `onFocus${string}`]: Ev | Handler<V, PartEvents["onFocus"]>;
+  readonly [key: `onBlur${string}`]: Ev | Handler<V, PartEvents["onBlur"]>;
+  readonly [key: `onBeforeInput${string}`]: Ev | Handler<V, PartEvents["onBeforeInput"]>;
+  readonly [key: `onInput${string}`]: Ev | Handler<V, PartEvents["onInput"]>;
+  readonly [key: `onChange${string}`]: Ev | Handler<V, PartEvents["onChange"]>;
+  readonly [key: `onSubmit${string}`]: Ev | Handler<V, PartEvents["onSubmit"]>;
+  readonly [key: `onReset${string}`]: Ev | Handler<V, PartEvents["onReset"]>;
+  readonly [key: `onScroll${string}`]: Ev | Handler<V, PartEvents["onScroll"]>;
+  readonly [key: `onSelect${string}`]: Ev | Handler<V, PartEvents["onSelect"]>;
+  readonly [key: `onInvalid${string}`]: Ev | Handler<V, PartEvents["onInvalid"]>;
+  readonly [key: `onToggle${string}`]: Ev | Handler<V, PartEvents["onToggle"]>;
+  readonly [key: `onCopy${string}`]: Ev | Handler<V, PartEvents["onCopy"]>;
+  readonly [key: `onCut${string}`]: Ev | Handler<V, PartEvents["onCut"]>;
+  readonly [key: `onPaste${string}`]: Ev | Handler<V, PartEvents["onPaste"]>;
+  readonly [key: `onComposition${string}`]: Ev | Handler<V, PartEvents["onComposition"]>;
+  readonly [key: `onAnimation${string}`]: Ev | Handler<V, PartEvents["onAnimation"]>;
+  readonly [key: `onTransition${string}`]: Ev | Handler<V, PartEvents["onTransition"]>;
+};
+/** `parts`: one {@link PartConfig} per part name. */
+type PartsConfig<V> = {
+  readonly [part: string]: PartConfig<V>;
+};
+/** The attributes every part gets (PLAN §4.4). */
+interface PartBase {
+  readonly id: string;
+  readonly "data-scope": string;
+  readonly "data-part": string;
+  /** The active path: `"open"`, `"form.editing"`. */
+  readonly "data-state": string;
+}
+/** A part's props as the component spreads them: statics as written, functions' results, handlers. */
+type PartProps<P> = PartBase & { readonly [K in keyof P]: K extends `on${string}` ? (event?: unknown) => void : P[K] extends ((...args: never) => infer R) ? R : P[K]; };
+/**
+ * What `useMachine` returns: the state, `is`, `send`, `context`, each
+ * part's props, and what `expose` returns.
+ */
+type Api<M extends AnyMachine> = {
+  readonly state: TypesOf<M>["leaves"];
+  readonly is: (state: TypesOf<M>["paths"]) => boolean;
+  readonly send: Send<EventUnion<TypesOf<M>["events"]>>;
+  readonly context: Readonly<TypesOf<M>["context"]>;
+  readonly parts: { readonly [K in keyof TypesOf<M>["parts"]]: PartProps<TypesOf<M>["parts"][K]>; };
+  /** Calls `listener` after each visible change: what code outside a framework's rendering listens to. */
+  subscribe(listener: () => void): () => void;
+  /** New owner props, for code without a framework: a framework passes them on each render. */
+  setProps(props: UseProps<M>): void;
+  /**
+   * Stops the instance (its effects, timers and listeners), for code without
+   * a framework when the element goes: a framework's glue does it on unmount.
+   */
+  stop(): void;
+} & Readonly<TypesOf<M>["exposed"]>;
+/**
+ * What a component passes: the owner props `start` takes, and an `id` for
+ * the parts' ids when the framework has none to give. Vue, Svelte and
+ * Solid also take a function returning them, read reactively.
+ */
+type UseProps<M extends AnyMachine> = TypesOf<M>["owner"] & {
+  readonly id?: string;
+};
+//#endregion
+//#region src/core/types.d.ts
+declare const PAYLOAD: unique symbol;
+declare const BOUND_VALUE: unique symbol;
+declare const FEATURE: unique symbol;
+declare const REGIONS: unique symbol;
+/** An event's data, declared in `events` with `payload<T>()` (D7). */
+interface Payload<T extends object> {
+  readonly [PAYLOAD]: T;
+}
+/** What a machine without `events` accepts: any event name, any data. */
+type AnyEvents = {
+  readonly [type: string]: null;
+};
+/** The event `K` of `E`: `{ type: "ADD"; by: number }`. */
+type EventOf<E, K extends keyof E> = K extends string ? Readonly<{
+  type: K;
+} & (E[K] extends Payload<infer P> ? P : unknown)> : never;
+/** Every event of `E`, as a discriminated union. */
+type EventUnion<E> = { [K in keyof E & string]: EventOf<E, K>; }[keyof E & string];
+/**
+ * The events the machine itself raises: entering the initial state, an
+ * `after` timer, and an owner changing a bound prop the machine follows.
+ */
+type MachineEvent = {
+  readonly type: "machine.start";
+} | {
+  readonly type: "machine.after";
+} | {
+  readonly type: "machine.props";
+} | DoneEvent;
+/** What a parallel state's `done` transition gets: every region reached a final state. */
+interface DoneEvent {
+  readonly type: "machine.done";
+}
+/** Any event object: what `send` hands along unchanged. */
+interface AnyEvent {
+  readonly type: string;
+}
+/**
+ * A name `send` does not know meets this, beside the names it does: the
+ * message is the fix (an argument gets no "Did you mean" from TypeScript).
+ */
+type Unknown<K extends string> = `${K} is not an event of this machine: send one of its events, or declare it in \`events\``;
+type EventName<K extends string, Types extends string> = K extends Types ? K : Types | Unknown<K>;
+type PayloadOf<Ev> = Omit<Ev, "type">;
+type SendArgs<All extends AnyEvent, K> = string extends All["type"] ? [payload?: object] : [keyof PayloadOf<Extract<All, {
+  type: K;
+}>>] extends [never] ? [] : {} extends PayloadOf<Extract<All, {
+  type: K;
+}>> ? [payload?: PayloadOf<Extract<All, {
+  type: K;
+}>>] : [payload: PayloadOf<Extract<All, {
+  type: K;
+}>>];
+/**
+ * Both send forms, typed and equivalent (D7): `send("ADD", { by: 2 })` and
+ * `send({ type: "ADD", by: 2 })`. A send made while an event is being
+ * handled runs once that event is done, before the outer `send` returns.
+ *
+ * One signature, not two overloads: a wrong name then gets one error, not
+ * "No overload matches this call" with one per form. `string & {}` keeps
+ * the event names as completions while letting any name through to the
+ * message.
+ */
+interface Send<All extends AnyEvent> {
+  <const T extends All["type"] | (string & {}) | AnyEvent>(event: T extends string ? EventName<T, All["type"]> : T extends {
+    readonly type: infer K extends string;
+  } ? K extends All["type"] ? All : {
+    readonly type: EventName<K, All["type"]>;
+  } : All, ...payload: T extends string ? SendArgs<All, T> : []): void;
+}
+/** A controlled-or-uncontrolled prop declared with `bindable()` (D9). */
+interface Bindable<V> {
+  readonly [BOUND_VALUE]?: V;
+  readonly value: V;
+}
+type BoundKeys<PC> = { [K in keyof PC]: PC[K] extends Bindable<unknown> ? K : never; }[keyof PC];
+type ValueOf<T> = T extends Bindable<infer V> ? V : T;
+/**
+ * Props as actions read them: plain props are read-only, a bindable one
+ * can be written (`props.value = next`), which asks the owner when it is
+ * controlled.
+ */
+type PropsOf<PC> = { -readonly [K in keyof PC as PC[K] extends Bindable<unknown> ? K : never]: ValueOf<PC[K]>; } & { readonly [K in keyof PC as PC[K] extends Bindable<unknown> ? never : K]: PC[K]; };
+/**
+ * What the owner passes (`start(m, { props })`, `setProps`): every prop
+ * optional; for each bindable `x`, also `defaultX` and `onXChange`.
+ */
+type OwnerProps<PC> = { readonly [K in keyof PC]?: ValueOf<PC[K]>; } & { readonly [K in BoundKeys<PC> & string as `default${Capitalize<K>}`]?: ValueOf<PC[K]>; } & { readonly [K in BoundKeys<PC> & string as `on${Capitalize<K>}Change`]?: (value: ValueOf<PC[K]>) => void; };
+/** What a derived function reads. */
+interface DerivedView<C, P> {
+  readonly context: Readonly<C>;
+  readonly props: Readonly<P>;
+  readonly state: string;
+  is(state: string): boolean;
+}
+/** `derived`: a function per value. */
+type DerivedConfig<C, P> = {
+  readonly [name: string]: (view: DerivedView<C, P>) => unknown;
+};
+/** The values `derived`'s functions return. */
+type DerivedOf<DC> = { readonly [K in keyof DC]: DC[K] extends ((view: never) => infer R) ? R : never; };
+/**
+ * What guards, actions and effects receive: the instance, read through
+ * destructuring (`({ context, event, send }) => …`). Inside the config,
+ * `state` and `is` take any string (checked in development): the state tree
+ * is inferred from the very object they sit in. A started instance types
+ * them to the machine's paths.
+ */
+interface View<C = {}, P = {}, D = {}, All extends AnyEvent = AnyEvent, Ev extends AnyEvent = All | MachineEvent, Path extends string = string, Leaf extends string = string, Part extends string = string> {
+  /** The machine's own data; actions write it directly (D5). */
+  readonly context: C;
+  readonly props: P;
+  readonly derived: D;
+  /** The event being handled, narrowed to the handler's own. */
+  readonly event: Ev;
+  /** The active path: `"open"`, `"form.editing"`. */
+  readonly state: Leaf;
+  readonly send: Send<All>;
+  /** True in `state` and in every state inside it. */
+  readonly is: (state: Path) => boolean;
+  /**
+   * Each part's id (`ids.content`), the same on the server and the client
+   * (PLAN §4.4). Only a component (`useMachine`) has parts: in an instance
+   * `start` or `testMachine` made, every id reads `undefined`.
+   */
+  readonly ids: { readonly [K in Part]: string | undefined; };
+  /**
+   * Each part's element, found by its id when read (`el.content`): effects
+   * start once the DOM is committed (D13), so a part the component renders
+   * is there. A part it does not render reads `undefined`, as does every
+   * part on a server and in an instance `start` or `testMachine` made.
+   */
+  readonly el: { readonly [K in Part]: DomElement | undefined; };
+}
+/** The DOM's `HTMLElement` where the DOM's types are loaded. */
+type DomElement = typeof globalThis extends {
+  HTMLElement: {
+    prototype: infer E;
+  };
+} ? E : object;
+/**
+ * The view of everything but actions: guards, effects, attribute functions
+ * and `expose` read context and never write it (D5; development throws on a
+ * write), so their `context` is read-only.
+ */
+type Reading<V extends {
+  readonly context: unknown;
+}> = Omit<V, "context"> & {
+  readonly context: Readonly<V["context"]>;
+};
+type Action<V> = (view: V) => void;
+type Guard<V extends {
+  readonly context: unknown;
+}> = (view: Reading<V>) => boolean;
+/** What an effect may return: a cleanup, or nothing to clean up. */
+type EffectResult = (() => void) | void | false | null | undefined;
+type Effect<V extends {
+  readonly context: unknown;
+}> = (view: Reading<V>) => EffectResult;
+/**
+ * A list of transitions or implementations. Not `readonly T[]`: a union
+ * holding an array type keeps TypeScript from pointing an error inside a
+ * `{ to, if, do }` object at the key that is wrong.
+ */
+interface List<T> {
+  readonly [index: number]: T;
+  readonly length: number;
+}
+/** One implementation or several: a function, or the name of one in `actions` / `effects`. */
+type Some<T> = T | List<T>;
+/**
+ * A transition (D6): a target, an action that stays in the state, or
+ * `{ to, if, do }` with every key optional. `T` is every target the state
+ * may name: a sibling's name (or an ancestor's sibling's), a child
+ * (`".editing"`) or a path from the root (`"#form.editing"`). `A` and `G`
+ * name the machine's `actions` and `guards`.
+ */
+type Transition<T extends string, V extends {
+  readonly context: unknown;
+}, A extends string = never, G extends string = never> = T | Action<V> | {
+  readonly to?: T;
+  readonly if?: G | Guard<V>;
+  readonly do?: Some<A | Action<V>>;
+};
+/** One transition, or several tried in order: the first whose `if` passes wins. */
+type Transitions<T extends string, V extends {
+  readonly context: unknown;
+}, A extends string = never, G extends string = never> = Transition<T, V, A, G> | List<Transition<T, V, A, G>>;
+/**
+ * The states, as `defineMachine` infers them: each name maps to its
+ * children's tree, and a leaf to `unknown`. TypeScript reads a config that
+ * holds functions in two passes, and in the first one a subtree whose
+ * states hold only functions has no children yet: its tree comes from its
+ * `initial` alone, with `any` for the one child that names. Such a subtree
+ * may then be named any way (`string`), so the first pass never rejects
+ * what the second one checks; the second has the whole tree.
+ */
+type Loose<T> = unknown extends T ? never : 0 extends 1 & T[keyof T] ? string : { [K in keyof T & string]: K | `${K}.${Loose<T[K]>}`; }[keyof T & string];
+/** The names of a tree's top states: the plain targets its children may use. */
+type Names<T> = unknown extends T ? never : 0 extends 1 & T[keyof T] ? string : keyof T & string;
+/**
+ * The paths of a tree: every state's, parents included (what `is()`
+ * takes), and the leaves' (what `state` is). Members of an interface, not
+ * aliases, so hovers and errors list the paths instead of naming the alias.
+ */
+interface Tree<T> {
+  readonly paths: { [K in keyof T & string]: K | (unknown extends T[K] ? never : `${K}.${Tree<T[K]>["paths"]}`); }[keyof T & string];
+  readonly leaves: { [K in keyof T & string]: unknown extends T[K] ? K : `${K}.${Tree<T[K]>["leaves"]}`; }[keyof T & string];
+}
+/** What `parallel` marks: a state whose children are regions. */
+interface Regions {
+  readonly [REGIONS]: true;
+}
+/**
+ * Which states are parallel, read from the same `states` object as the tree
+ * but into a tree of its own, `Q` (PLAN §11, question 24): a parallel state
+ * is {@link Regions} there, any other its children's marks. The state tree
+ * cannot hold it: a state's children are inferred into one type, and a
+ * second source for that type replaces the children instead of joining them.
+ */
+type Marks<Q> = { readonly [K in keyof Q]?: Mark<Q[K]>; };
+interface Mark<T> {
+  readonly type?: T extends Regions ? {
+    readonly [FEATURE]?: T;
+  } : unknown;
+  readonly states?: Marks<T>;
+}
+/** The paths of the history pseudo-states in a tree of {@link Marks}: never active, so neither `state` nor `is()` names them. */
+type HistoryPaths<Q> = { [K in keyof Q & string]: Q[K] extends "history" ? K : `${K}.${HistoryPaths<Q[K]>}`; }[keyof Q & string];
+/** Whether a tree of {@link Marks} holds a parallel state. */
+type HasParallel<Q> = Q extends Regions ? true : Q extends object ? true extends { [K in keyof Q]: HasParallel<Q[K]>; }[keyof Q] ? true : false : false;
+/**
+ * What `state` holds: one leaf's path, or, in a machine with parallel
+ * states, the active leaves joined by spaces in document order
+ * (`"editor.bold.on editor.save.dirty"`). The order of keys is not a type,
+ * so the leaves after the first are a `string`.
+ */
+type LeafOf<S, Q> = HasParallel<Q> extends true ? Leaves<S, Q> | `${Leaves<S, Q>} ${string}` : Leaves<S, Q>;
+type Leaves<S, Q> = Exclude<Tree<S>["leaves"], HistoryPaths<Q>>;
+/** What `is()` takes: every state's path but a history pseudo-state's. */
+type PathOf<S, Q> = Exclude<Tree<S>["paths"], HistoryPaths<Q>>;
+/** The views handlers get, built once per machine: one for every event, one per event, one for `done`. */
+interface Handlers<C, P, D, E, Part extends string> {
+  readonly any: View<C, P, D, EventUnion<E>, EventUnion<E> | MachineEvent, string, string, Part>;
+  readonly done: View<C, P, D, EventUnion<E>, DoneEvent, string, string, Part>;
+  readonly on: { readonly [K in keyof E & string]: View<C, P, D, EventUnion<E>, string extends keyof E ? EventUnion<E> : EventOf<E, K>, string, string, Part>; };
+}
+/** What every state of one machine may refer to: its named implementations and its top targets. */
+interface Refs {
+  readonly actions: string;
+  readonly guards: string;
+  readonly effects: string;
+  /** The top states' names, and `"#form.editing"` for every state. */
+  readonly root: string;
+}
+interface AnyView {
+  readonly context: unknown;
+}
+interface AnyHandlers {
+  readonly any: AnyView;
+  readonly done: AnyView;
+  readonly on: {
+    readonly [event: string]: AnyView;
+  };
+}
+type On<H extends AnyHandlers, N extends Refs, T extends string> = { readonly [K in keyof H["on"]]?: Transitions<T, H["on"][K], N["actions"], N["guards"]>; };
+/** Each child of a state whose children tree is `U`; `Up` is what its ancestors let it name. */
+type StatesOf<H extends AnyHandlers, N extends Refs, U, Up extends string> = { readonly [K in keyof U]: StateConfig<H, N, U[K], Up>; };
+/**
+ * One state. `U` is its children's tree, which TypeScript infers through
+ * `states` and, in its first pass, `initial` (see `Loose`); every other use
+ * of it is `NoInfer`. Contextual types walk the generic mapped `states` key
+ * by key, so a handler's view never waits for the tree.
+ */
+interface StateConfig<H extends AnyHandlers, N extends Refs, U, Up extends string> {
+  readonly initial?: keyof U & string;
+  readonly states?: StatesOf<H, N, U, Up | NoInfer<Names<U>>>;
+  readonly on?: On<H, N, NoInfer<Up | N["root"] | `.${Loose<U>}`>>;
+  readonly entry?: Some<N["actions"] | Action<H["any"]>>;
+  readonly exit?: Some<N["actions"] | Action<H["any"]>>;
+  /** Runs while the state is active; a returned function cleans up on exit (D13). */
+  readonly effect?: Some<N["effects"] | Effect<H["any"]>>;
+  /** Timers set on entry and cleared on exit: `{ 10_000: "failure" }`. */
+  readonly after?: {
+    readonly [ms: number]: Transitions<NoInfer<Up | N["root"] | `.${Loose<U>}`>, H["any"], N["actions"], N["guards"]>;
+  };
+  /** Eventless transitions, checked after every event and on entry. */
+  readonly always?: Transitions<NoInfer<Up | N["root"] | `.${Loose<U>}`>, H["any"], N["actions"], N["guards"]>;
+  /**
+   * `"final"`: at the top level it ends the machine and resolves `done`; in
+   * a region of a parallel state it ends the region. `parallel`, imported
+   * from `@menapo/machine`: the children are regions, all active at once.
+   */
+  readonly type?: "final" | Parallel | History;
+  /** A parallel state's: taken once every one of its regions is in a final state. */
+  readonly done?: Transitions<NoInfer<Up | N["root"] | `.${Loose<U>}`>, H["done"], N["actions"], N["guards"]>;
+}
+/** `type: parallel`: the state's children are regions, all active at once (PLAN §4.9). */
+interface Parallel {
+  readonly [FEATURE]: Regions;
+}
+/** The `type` of a history pseudo-state. */
+interface History {
+  readonly [FEATURE]: "history";
+}
+/** What `history()` returns: a pseudo-state that re-enters where its parent was when last exited. */
+interface HistoryState {
+  readonly type: History;
+}
+/**
+ * The default of `actions`, `guards` and `effects` before TypeScript has
+ * read them: any name. Once read, only theirs.
+ */
+interface Unnamed {
+  readonly [name: string]: unknown;
+}
+/** The names a map declares, or none when the machine has no such map. */
+type NamesOf<T> = string extends keyof T ? never : keyof T & string;
+type ViewIn<C, PC, E, DC, PN extends string> = View<C, PropsOf<PC>, DerivedOf<DC>, EventUnion<E>, EventUnion<E> | MachineEvent, string, string, PN>;
+interface MachineConfig<C, PC, E, DC, A, G, F, S, PS = {}, X = {}, PN extends string = never, Q = unknown> {
+  /** Names the machine in dev errors; `"machine"` when left out. */
+  readonly name?: string;
+  readonly context?: C;
+  readonly props?: PC;
+  readonly events?: E;
+  /**
+   * Cached values of context, props and the state, recomputed when what
+   * they read changes. The intersection gives the functions their view
+   * while `DC` is inferred from them, so actions can read their results.
+   */
+  readonly derived?: DC & DerivedConfig<NoInfer<C>, PropsOf<NoInfer<PC>>>;
+  /**
+   * Named implementations (D8): written once, used by name in any state
+   * (`do: "save"`, `if: "valid"`, `effect: "load"`), replaced with
+   * `provide`. They get every event, so they narrow `event.type` themselves.
+   */
+  readonly actions?: A & {
+    readonly [name: string]: Action<ViewIn<NoInfer<C>, NoInfer<PC>, NoInfer<E>, NoInfer<DC>, NoInfer<PN>>>;
+  };
+  readonly guards?: G & {
+    readonly [name: string]: Guard<ViewIn<NoInfer<C>, NoInfer<PC>, NoInfer<E>, NoInfer<DC>, NoInfer<PN>>>;
+  };
+  readonly effects?: F & {
+    readonly [name: string]: Effect<ViewIn<NoInfer<C>, NoInfer<PC>, NoInfer<E>, NoInfer<DC>, NoInfer<PN>>>;
+  };
+  readonly initial: keyof S & string;
+  readonly states: Marks<Q> & StatesOf<Handlers<NoInfer<C>, PropsOf<NoInfer<PC>>, DerivedOf<NoInfer<DC>>, NoInfer<E>, NoInfer<PN>>, {
+    readonly actions: keyof NoInfer<A> & string;
+    readonly guards: keyof NoInfer<G> & string;
+    readonly effects: keyof NoInfer<F> & string;
+    readonly root: NoInfer<Names<S> | `#${Loose<S>}`>;
+  }, S, never>;
+  /** Transitions every state takes unless it handles the event itself. */
+  readonly on?: On<Handlers<NoInfer<C>, PropsOf<NoInfer<PC>>, DerivedOf<NoInfer<DC>>, NoInfer<E>, NoInfer<PN>>, {
+    readonly actions: keyof NoInfer<A> & string;
+    readonly guards: keyof NoInfer<G> & string;
+    readonly effects: keyof NoInfer<F> & string;
+    readonly root: never;
+  }, NoInfer<Names<S> | `#${Loose<S>}` | `.${Loose<S>}`>>;
+  /**
+   * The component's DOM attributes, per part (PLAN §4.4): static values,
+   * attribute functions re-evaluated when what they read changes, and
+   * `on*` handlers (an event name, or a function of the view and the DOM
+   * event), created once per instance.
+   */
+  readonly parts?: PS & { readonly [K in PN]: PartConfig<Reading<ViewIn<NoInfer<C>, NoInfer<PC>, NoInfer<E>, NoInfer<DC>, NoInfer<PN>>>, keyof NoInfer<E> & string>; };
+  /** What `useMachine` returns beside `state`, `is`, `send`, `context` and `parts` (PLAN §4.6). */
+  readonly expose?: (view: Reading<ViewIn<NoInfer<C>, NoInfer<PC>, NoInfer<E>, NoInfer<DC>, NoInfer<PN>>>) => X;
+}
+/** The names of a machine's `actions`, `guards` and `effects`, for `provide`. */
+interface Named {
+  readonly actions: string;
+  readonly guards: string;
+  readonly effects: string;
+}
+/** A machine `defineMachine` made, carrying its config's types to `start`. */
+interface Machine<C = {}, PC = {}, E = AnyEvents, DC = {}, Path extends string = string, Leaf extends string = string, N extends Named = Named, PS = {}, X = {}> {
+  /** Never set: the types `start`, `provide` and the instance read. */
+  readonly types?: {
+    readonly context: C;
+    readonly props: PC;
+    readonly events: E;
+    readonly derived: DC;
+    readonly paths: Path;
+    readonly leaves: Leaf;
+    readonly named: N;
+    readonly owner: OwnerProps<PC>;
+    readonly parts: PS;
+    readonly exposed: X;
+  };
+}
+/** Any machine, for `start`'s constraint. */
+type AnyMachine = Machine<unknown, unknown, unknown, unknown, string, string, Named, unknown, unknown>;
+type TypesOf<M extends AnyMachine> = NonNullable<M["types"]>;
+/**
+ * What guards, actions and effects of machine `M` receive, every event
+ * included: the type of a function `provide` supplies, or of one written
+ * outside the machine that its actions call.
+ */
+type ViewOf<M extends AnyMachine> = View<TypesOf<M>["context"], PropsOf<TypesOf<M>["props"]>, DerivedOf<TypesOf<M>["derived"]>, EventUnion<TypesOf<M>["events"]>, EventUnion<TypesOf<M>["events"]> | MachineEvent, string, string, keyof TypesOf<M>["parts"] & string>;
+/** `provide(machine, implementations)`: any of the machine's named implementations. */
+interface Implementations<M extends AnyMachine> {
+  readonly actions?: Replacing<TypesOf<M>["named"]["actions"], Action<ViewOf<M>>>;
+  readonly guards?: Replacing<TypesOf<M>["named"]["guards"], Guard<ViewOf<M>>>;
+  readonly effects?: Replacing<TypesOf<M>["named"]["effects"], Effect<ViewOf<M>>>;
+}
+/**
+ * Replacements for the names `N`: none when the machine declares no such
+ * map (an empty mapped type would take any key, unchecked).
+ */
+type Replacing<N extends string, F> = [N] extends [never] ? {
+  readonly [name: string]: never;
+} : { readonly [K in N]?: F; };
+/** `start(machine, options)`: initial context fields and the owner's props. */
+interface StartOptions<M extends AnyMachine> {
+  readonly context?: Partial<TypesOf<M>["context"]>;
+  readonly props?: TypesOf<M>["owner"];
+}
+type Listener<I> = (instance: I) => void;
+/** A started machine (PLAN §4.8): `state` and `is` take its paths. */
+interface Instance<C = {}, PC = {}, E = AnyEvents, DC = {}, Path extends string = string, Leaf extends string = string> extends Omit<View<C, PropsOf<PC>, DerivedOf<DC>, EventUnion<E>, EventUnion<E> | MachineEvent, Path, Leaf>, "ids" | "el"> {
+  /** The context fields and props the last notification changed, by name. */
+  readonly changed: readonly string[];
+  /** Called once per event that changed something, with the instance. */
+  subscribe(listener: Listener<this>): () => void;
+  /** The owner's props, as a component passes them on each render. */
+  setProps(props: OwnerProps<PC>): void;
+  /** Resolves when the machine reaches a top-level final state. */
+  readonly done: Promise<void>;
+  /** Stops effects and timers; later sends are ignored. */
+  stop(): void;
+}
+/** The instance `start` returns for machine `M`. */
+type InstanceOf<M extends AnyMachine> = M extends Machine<infer C, infer PC, infer E, infer DC, infer Path, infer Leaf> ? Instance<C, PC, E, DC, Path, Leaf> : never;
+//#endregion
+export { StateConfig as A, PartProps as B, OwnerProps as C, PropsOf as D, Payload as E, ViewOf as F, UseProps as H, Api as I, PartBase as L, Transitions as M, Unnamed as N, Send as O, View as P, PartConfig as R, NamesOf as S, PathOf as T, PartsConfig as V, InstanceOf as _, Bindable as a, MachineConfig as b, Effect as c, EventUnion as d, Guard as f, Instance as g, Implementations as h, AnyMachine as i, Transition as j, StartOptions as k, EffectResult as l, HistoryState as m, AnyEvent as n, DerivedView as o, History as p, AnyEvents as r, DoneEvent as s, Action as t, EventOf as u, LeafOf as v, Parallel as w, MachineEvent as x, Machine as y, PartEvent as z };

package/dist/vicss.d.ts

@@ -0,0 +1,19 @@
+import { i as AnyMachine } from "./types-Bk8svtO6.js";
+//#region src/vicss.d.ts
+/** A vicss preset: named conditions, as `defineConfig({ conditions })` takes them. */
+export interface ConditionsPreset {
+  readonly conditions: Readonly<Record<string, string | string[]>>;
+}
+/**
+ * The conditions of every state of `machines`, by name: the machine's
+ * `name` then the state's path, in camelCase (`dialogOpen`,
+ * `wizardFormEditing`). A state holds while it is active, as `is()` says: a
+ * leaf when `data-state` lists it, a parent while it lists a leaf inside it;
+ * in a machine with parallel states `data-state` lists one leaf per region,
+ * so every region's states hold at once. History states are never active
+ * and get none. Use a condition on a part's own element, the one its
+ * props are spread on, beside its vicss style (`{...api.parts.content}
+ * {...sx(s.content)}`).
+ */
+export declare function conditions(...machines: readonly AnyMachine[]): ConditionsPreset;
+//#endregion

package/dist/vicss.js

@@ -0,0 +1,51 @@
+import { r as fail } from "./dev-BAz6e3W-.js";
+//#region src/vicss.ts
+/**
+* `@menapo/machine/vicss`: the vicss conditions preset generated from the
+* machines' anatomies (PLAN D2). Every part of a machine carries
+* `data-scope` (the machine's `name`) and `data-state` (the active leaves,
+* PLAN §4.4), so each state is a condition on the part's element:
+* `presets: [conditions(dialog)]` in `vicss.config.ts` gives `_dialogOpen`
+* and `_dialogClosed`, and a recipe styles a part per state with no class
+* toggled by hand and no state name written twice.
+*
+* Read from the machine's tables, runtime-normalised or compiled, when the
+* config loads; nothing here ships to the browser, and it imports nothing
+* from vicss: the preset is plain config data.
+*/
+const word = (text) => text.split(/[^A-Za-z0-9]+/).filter(Boolean).map((part) => part[0].toUpperCase() + part.slice(1)).join("");
+/** A CSS attribute value inside double quotes. */
+const quoted = (value) => `"${value.replace(/["\\]/g, "\\$&")}"`;
+/**
+* The conditions of every state of `machines`, by name: the machine's
+* `name` then the state's path, in camelCase (`dialogOpen`,
+* `wizardFormEditing`). A state holds while it is active, as `is()` says: a
+* leaf when `data-state` lists it, a parent while it lists a leaf inside it;
+* in a machine with parallel states `data-state` lists one leaf per region,
+* so every region's states hold at once. History states are never active
+* and get none. Use a condition on a part's own element, the one its
+* props are spread on, beside its vicss style (`{...api.parts.content}
+* {...sx(s.content)}`).
+*/
+function conditions(...machines) {
+	const out = {};
+	for (const machine of machines) {
+		const tables = machine;
+		const scope = tables.c.name ?? "machine";
+		const capitalised = word(scope);
+		const prefix = capitalised.charAt(0).toLowerCase() + capitalised.slice(1);
+		const element = `&[data-scope=${quoted(scope)}]`;
+		const parents = new Set(tables.ss.map((state) => state.up));
+		for (const state of tables.ss) {
+			if (state.h !== void 0) continue;
+			const name = prefix + state.path.split(".").map(word).join("");
+			const condition = parents.has(state) ? [`${element}[data-state^=${quoted(`${state.path}.`)}]`, `${element}[data-state*=${quoted(` ${state.path}.`)}]`] : `${element}[data-state~=${quoted(state.path)}]`;
+			const taken = out[name];
+			if (taken !== void 0 && String(taken) !== String(condition)) fail("CONDITION", scope, `the vicss condition "${name}" names state "${state.path}" here and a state of another machine; give the machines names that differ in more than punctuation or case.`);
+			out[name] = condition;
+		}
+	}
+	return { conditions: out };
+}
+//#endregion
+export { conditions };