@zag-js/core 1.34.1 → 1.35.1

package/README.md

@@ -5,18 +5,18 @@ machines** with addition of extra features we need for our components.
 
 ## Features
 
-- Finite states (non-nested)
+- Finite states with optional nested (hierarchical) states
 - Initial state
 - Transitions (object or strings)
 - Context
 - Entry actions
 - Exit actions
-- Delayed timeout actions (basically `setTimeout`)
-- Delayed interval actions (basically `setInterval`)
 - Transition actions
+- Effects
 - Boolean guard helpers (`and`, `or`, `not`)
-- Basic spawn helpers
-- Activities (for state nodes)
+
+> Note: The core package is intentionally minimal. It doesn't include delayed transitions, interval scheduling, spawn
+> helpers, or activities. Use actions/effects to perform side effects.
 
 > To better understand the state machines, we strongly recommend going though the
 > [xstate docs](https://xstate.js.org/docs/) and videos. It'll give you the foundations you need.
@@ -46,34 +46,101 @@ const toggleMachine = createMachine({
     active: { on: { TOGGLE: "inactive" } },
   },
 })
+```
+
+**Usage (service via adapter):**
+
+```js
+import { createMachine } from "@zag-js/core"
+import { VanillaMachine } from "@zag-js/vanilla"
+
+const machine = createMachine({
+  initialState() {
+    return "inactive"
+  },
+  states: {
+    inactive: { on: { TOGGLE: "active" } },
+    active: { on: { TOGGLE: "inactive" } },
+  },
+})
 
-toggleMachine.start()
-console.log(toggleMachine.state.value) // => "inactive"
+const service = new VanillaMachine(machine)
+service.start()
 
-toggleMachine.send("TOGGLE")
-console.log(toggleMachine.state.value) // => "active"
+service.subscribe(() => {
+  console.log(service.state.get())
+})
 
-toggleMachine.send("TOGGLE")
-console.log(toggleMachine.state.value) // => "inactive"
+service.send({ type: "TOGGLE" })
+service.send({ type: "TOGGLE" })
+service.stop()
 ```
 
-**Usage (service):**
+### Nested states (dot notation)
 
-```js
+```ts
 import { createMachine } from "@zag-js/core"
 
-const toggleMachine = createMachine({...})
-toggleMachine.start()
-
-toggleService.subscribe((state) => {
-  console.log(state.value)
+const machine = createMachine({
+  initialState() {
+    return "dialog"
+  },
+  states: {
+    dialog: {
+      tags: ["overlay"],
+      initial: "closed",
+      states: {
+        closed: { on: { OPEN: { target: "dialog.open" } } },
+        open: { on: { CLOSE: { target: "dialog.closed" } } },
+      },
+      // parent-level transitions still work
+      on: { RESET: { target: "dialog.closed" } },
+    },
+  },
 })
 
-toggleService.send("TOGGLE")
-toggleService.send("TOGGLE")
-toggleService.stop()
+// service.state.matches("dialog.open") === true when nested state is active
 ```
 
+### State IDs and `#id` targets
+
+Use `id` on a state node when you want to target it explicitly from anywhere in the machine.
+
+```ts
+import { createMachine } from "@zag-js/core"
+
+const machine = createMachine({
+  initialState() {
+    return "dialog"
+  },
+  states: {
+    dialog: {
+      initial: "open",
+      states: {
+        focused: {
+          id: "dialogFocused",
+        },
+        open: {
+          initial: "idle",
+          states: {
+            idle: {
+              on: {
+                CLOSE: { target: "#dialogFocused" },
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+})
+```
+
+Notes:
+
+- `#id` targets resolve by state node `id` (XState-style).
+- State IDs must be unique within a machine.
+
 ## API
 
 ### `createMachine(config, options)`
@@ -87,39 +154,20 @@ Creates a new finite state machine from the config.
 
 **Returns:**
 
-A `Machine`, which provides:
-
-- `machine.initialState`: the machine's resolved initial state
-- `machine.start()`: the function to start the machine in the specified initial state.
-- `machine.stop()`: the function to stop the machine completely. It also cleans up all scheduled actions and timeouts.
-- `machine.transition(state, event)`: a transition function that returns the next state given the current `state` and
-  `event`. It also performs any delayed, entry or exit side-effects.
-- `machine.send(event)`: a transition function instructs the machine to execute a transition based on the event.
-- `machine.onTransition(fn)`: a function that gets called when the machine transition function instructs the machine to
-  execute a transition based on the event.
-- `machine.onChange(fn)`: a function that gets called when the machine's context value changes.
-- `machine.state`: the state object that describes the machine at a specific point in time. It contains the following
-  properties:
-  - `value`: the current state value
-  - `previousValue`: the previous state value
-  - `event`: the event that triggered the transition to the current state
-  - `nextEvents`: the list of events the machine can respond to at its current state
-  - `tags`: the tags associated with this state
-  - `done`: whether the machine that reached its final state
-  - `context`: the current context value
-  - `matches(...)`: a function used to test whether the current state matches one or more state values
+A machine definition object consumed by framework adapters (React, Solid, Svelte, Vue, Preact, Vanilla) to create a
+runtime service.
 
 The machine config has this schema:
 
 ### Machine config
 
-- `id` (string) - an identifier for the type of machine this is. Useful for debugging.
-- `context` (object) - the extended state data that represents quantitative data (string, number, objects, etc) that can
-  be modified in the machine.
-- `initial` (string) - the key of the initial state.
-- `states` (object) - an object mapping state names (keys) to states
-- `on` (object) - an global mapping of event types to transitions. If specified, this event will called if the state
-  node doesn't handle the emitted event.
+- `initialState` (function) - returns the machine's initial state value.
+- `states` (object) - mapping of state names to state configs. Supports nested `states` and `initial` for child states.
+- `on` (object) - optional global transitions available from any state.
+- `context` (function) - returns bindable context fields.
+- `computed` (object) - derived values based on context, props, refs.
+- `entry` / `exit` / `effects` - root-level actions/effects.
+- `implementations` (object) - lookup tables for `actions`, `guards`, `effects`.
 
 ### State config
 

package/dist/create-machine.d.mts

@@ -0,0 +1,19 @@
+import { MachineSchema, GuardFn, Machine, Transition, Params } from './types.mjs';
+
+declare function createGuards<T extends MachineSchema>(): {
+    and: (...guards: Array<GuardFn<T> | T["guard"]>) => (params: any) => boolean;
+    or: (...guards: Array<GuardFn<T> | T["guard"]>) => (params: any) => boolean;
+    not: (guard: GuardFn<T> | T["guard"]) => (params: any) => boolean;
+};
+declare function createMachine<T extends MachineSchema>(config: Machine<T>): Machine<T>;
+declare function setup<T extends MachineSchema>(): {
+    guards: {
+        and: (...guards: (T["guard"] | GuardFn<T>)[]) => (params: any) => boolean;
+        or: (...guards: (T["guard"] | GuardFn<T>)[]) => (params: any) => boolean;
+        not: (guard: T["guard"] | GuardFn<T>) => (params: any) => boolean;
+    };
+    createMachine: (config: Machine<T>) => Machine<T>;
+    choose: (transitions: Transition<T> | Transition<T>[]) => ({ choose }: Params<T>) => T["action"][] | undefined;
+};
+
+export { createGuards, createMachine, setup };

package/dist/create-machine.d.ts

@@ -0,0 +1,19 @@
+import { MachineSchema, GuardFn, Machine, Transition, Params } from './types.js';
+
+declare function createGuards<T extends MachineSchema>(): {
+    and: (...guards: Array<GuardFn<T> | T["guard"]>) => (params: any) => boolean;
+    or: (...guards: Array<GuardFn<T> | T["guard"]>) => (params: any) => boolean;
+    not: (guard: GuardFn<T> | T["guard"]) => (params: any) => boolean;
+};
+declare function createMachine<T extends MachineSchema>(config: Machine<T>): Machine<T>;
+declare function setup<T extends MachineSchema>(): {
+    guards: {
+        and: (...guards: (T["guard"] | GuardFn<T>)[]) => (params: any) => boolean;
+        or: (...guards: (T["guard"] | GuardFn<T>)[]) => (params: any) => boolean;
+        not: (guard: T["guard"] | GuardFn<T>) => (params: any) => boolean;
+    };
+    createMachine: (config: Machine<T>) => Machine<T>;
+    choose: (transitions: Transition<T> | Transition<T>[]) => ({ choose }: Params<T>) => T["action"][] | undefined;
+};
+
+export { createGuards, createMachine, setup };

package/dist/create-machine.js

@@ -0,0 +1,70 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/create-machine.ts
+var create_machine_exports = {};
+__export(create_machine_exports, {
+  createGuards: () => createGuards,
+  createMachine: () => createMachine,
+  setup: () => setup
+});
+module.exports = __toCommonJS(create_machine_exports);
+var import_state = require("./state.cjs");
+function createGuards() {
+  return {
+    and: (...guards) => {
+      return function andGuard(params) {
+        return guards.every((str) => params.guard(str));
+      };
+    },
+    or: (...guards) => {
+      return function orGuard(params) {
+        return guards.some((str) => params.guard(str));
+      };
+    },
+    not: (guard) => {
+      return function notGuard(params) {
+        return !params.guard(guard);
+      };
+    }
+  };
+}
+function createMachine(config) {
+  (0, import_state.ensureStateIndex)(config);
+  return config;
+}
+function setup() {
+  return {
+    guards: createGuards(),
+    createMachine: (config) => {
+      return createMachine(config);
+    },
+    choose: (transitions) => {
+      return function chooseFn({ choose }) {
+        return choose(transitions)?.actions;
+      };
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createGuards,
+  createMachine,
+  setup
+});

package/dist/create-machine.mjs

@@ -0,0 +1,43 @@
+// src/create-machine.ts
+import { ensureStateIndex } from "./state.mjs";
+function createGuards() {
+  return {
+    and: (...guards) => {
+      return function andGuard(params) {
+        return guards.every((str) => params.guard(str));
+      };
+    },
+    or: (...guards) => {
+      return function orGuard(params) {
+        return guards.some((str) => params.guard(str));
+      };
+    },
+    not: (guard) => {
+      return function notGuard(params) {
+        return !params.guard(guard);
+      };
+    }
+  };
+}
+function createMachine(config) {
+  ensureStateIndex(config);
+  return config;
+}
+function setup() {
+  return {
+    guards: createGuards(),
+    createMachine: (config) => {
+      return createMachine(config);
+    },
+    choose: (transitions) => {
+      return function chooseFn({ choose }) {
+        return choose(transitions)?.actions;
+      };
+    }
+  };
+}
+export {
+  createGuards,
+  createMachine,
+  setup
+};

package/dist/index.d.mts

@@ -1,257 +1,7 @@
-import { isActiveElement } from '@zag-js/dom-query';
-
-interface Props {
-    [key: string | symbol]: any;
-}
-type TupleTypes<T extends any[]> = T[number];
-type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
-declare function mergeProps<T extends Props>(...args: Array<T | undefined>): UnionToIntersection<TupleTypes<T[]>>;
-
-type NoInfer<T> = [T][T extends any ? 0 : never];
-declare function memo<TDeps extends any[], TDepArgs, TResult>(getDeps: (depArgs: TDepArgs) => [...TDeps], fn: (args: NoInfer<[...TDeps]>, deps: TDepArgs) => TResult, opts?: {
-    onChange?: ((result: TResult) => void) | undefined;
-}): (depArgs: TDepArgs) => TResult;
-
-type Dict = Record<string, any>;
-interface ComputedParams<T extends Dict> {
-    context: BindableContext<T>;
-    event: EventType<T["event"]>;
-    prop: PropFn<T>;
-    refs: BindableRefs<T>;
-    scope: Scope;
-    computed: ComputedFn<T>;
-}
-interface ContextParams<T extends Dict> {
-    prop: PropFn<T>;
-    bindable: BindableFn;
-    scope: Scope;
-    getContext: () => BindableContext<T>;
-    getComputed: () => ComputedFn<T>;
-    getRefs: () => BindableRefs<T>;
-    getEvent: () => EventType<T["event"]>;
-    flush: (fn: VoidFunction) => void;
-}
-interface PropFn<T extends Dict> {
-    <K extends keyof T["props"]>(key: K): T["props"][K];
-}
-interface ComputedFn<T extends Dict> {
-    <K extends keyof T["computed"]>(key: K): T["computed"][K];
-}
-type AnyFunction = () => string | number | boolean | null | undefined;
-type TrackFn = (deps: AnyFunction[], fn: VoidFunction) => void;
-interface BindableParams<T> {
-    defaultValue?: T | undefined;
-    value?: T | undefined;
-    hash?: ((a: T) => string) | undefined;
-    isEqual?: ((a: T, b: T | undefined) => boolean) | undefined;
-    onChange?: ((value: T, prev: T | undefined) => void) | undefined;
-    debug?: string | undefined;
-    sync?: boolean | undefined;
-}
-type ValueOrFn<T> = T | ((prev: T) => T);
-interface Bindable<T> {
-    initial: T | undefined;
-    ref: any;
-    get: () => T;
-    set(value: ValueOrFn<T>): void;
-    invoke(nextValue: T, prevValue: T): void;
-    hash(value: T): string;
-}
-interface BindableRefs<T extends Dict> {
-    set<K extends keyof T["refs"]>(key: K, value: T["refs"][K]): void;
-    get<K extends keyof T["refs"]>(key: K): T["refs"][K];
-}
-interface BindableContext<T extends Dict> {
-    set<K extends keyof T["context"]>(key: K, value: ValueOrFn<T["context"][K]>): void;
-    get<K extends keyof T["context"]>(key: K): T["context"][K];
-    initial<K extends keyof T["context"]>(key: K): T["context"][K];
-    hash<K extends keyof T["context"]>(key: K): string;
-}
-interface BindableRef<T> {
-    get: () => T;
-    set: (next: T) => void;
-}
-interface BindableFn {
-    <K>(params: () => BindableParams<K>): Bindable<K>;
-    cleanup: (fn: VoidFunction) => void;
-    ref: <T>(defaultValue: T) => BindableRef<T>;
-}
-interface Scope {
-    id?: string | undefined;
-    ids?: Record<string, any> | undefined;
-    getRootNode: () => ShadowRoot | Document | Node;
-    getById: <T extends Element = HTMLElement>(id: string) => T | null;
-    getActiveElement: () => HTMLElement | null;
-    isActiveElement: (elem: HTMLElement | null) => boolean;
-    getDoc: () => typeof document;
-    getWin: () => typeof window;
-}
-type EventType<T = any> = T & {
-    previousEvent?: (T & {
-        [key: string]: any;
-    }) | undefined;
-    src?: string | undefined;
-    [key: string]: any;
-};
-type EventObject = EventType<{
-    type: string;
-}>;
-interface Params<T extends Dict> {
-    prop: PropFn<T>;
-    action: (action: T["action"][]) => void;
-    context: BindableContext<T>;
-    refs: BindableRefs<T>;
-    track: TrackFn;
-    flush: (fn: VoidFunction) => void;
-    event: EventType<T["event"]> & {
-        current: () => EventType<T["event"]>;
-        previous: () => EventType<T["event"]>;
-    };
-    send: (event: EventType<T["event"]>) => void;
-    computed: ComputedFn<T>;
-    scope: Scope;
-    state: Bindable<T["state"]> & {
-        matches: (...values: T["state"][]) => boolean;
-        hasTag: (tag: T["tag"]) => boolean;
-    };
-    choose: ChooseFn<T>;
-    guard: (key: T["guard"] | GuardFn<T>) => boolean | undefined;
-}
-type GuardFn<T extends Dict> = (params: Params<T>) => boolean;
-interface Transition<T extends Dict> {
-    target?: T["state"] | undefined;
-    actions?: T["action"][] | undefined;
-    guard?: T["guard"] | GuardFn<T> | undefined;
-    reenter?: boolean | undefined;
-}
-type MaybeArray<T> = T | T[];
-type ChooseFn<T extends Dict> = (transitions: MaybeArray<Omit<Transition<T>, "target">>) => Transition<T> | undefined;
-interface PropsParams<T extends Dict> {
-    props: Partial<T["props"]>;
-    scope: Scope;
-}
-interface RefsParams<T extends Dict> {
-    prop: PropFn<T>;
-    context: BindableContext<T>;
-}
-type ActionsOrFn<T extends Dict> = T["action"][] | ((params: Params<T>) => T["action"][] | undefined);
-type EffectsOrFn<T extends Dict> = T["effect"][] | ((params: Params<T>) => T["effect"][] | undefined);
-interface Machine<T extends Dict> {
-    debug?: boolean | undefined;
-    props?: ((params: PropsParams<T>) => T["props"]) | undefined;
-    context?: ((params: ContextParams<T>) => {
-        [K in keyof T["context"]]: Bindable<T["context"][K]>;
-    }) | undefined;
-    computed?: {
-        [K in keyof T["computed"]]: (params: ComputedParams<T>) => T["computed"][K];
-    } | undefined;
-    initialState: (params: {
-        prop: PropFn<T>;
-    }) => T["state"];
-    entry?: ActionsOrFn<T> | undefined;
-    exit?: ActionsOrFn<T> | undefined;
-    effects?: EffectsOrFn<T> | undefined;
-    refs?: ((params: RefsParams<T>) => T["refs"]) | undefined;
-    watch?: ((params: Params<T>) => void) | undefined;
-    on?: {
-        [E in T["event"]["type"]]?: Transition<T> | Array<Transition<T>>;
-    } | undefined;
-    states: {
-        [K in T["state"]]: {
-            tags?: T["tag"][] | undefined;
-            entry?: ActionsOrFn<T> | undefined;
-            exit?: ActionsOrFn<T> | undefined;
-            effects?: EffectsOrFn<T> | undefined;
-            on?: {
-                [E in T["event"]["type"]]?: Transition<T> | Array<Transition<T>>;
-            } | undefined;
-        };
-    };
-    implementations?: {
-        guards?: {
-            [K in T["guard"]]: (params: Params<T>) => boolean;
-        } | undefined;
-        actions?: {
-            [K in T["action"]]: (params: Params<T>) => void;
-        } | undefined;
-        effects?: {
-            [K in T["effect"]]: (params: Params<T>) => void | VoidFunction;
-        } | undefined;
-    } | undefined;
-}
-interface MachineBaseProps {
-    id?: string | undefined;
-    ids?: Record<string, any> | undefined;
-    getRootNode?: (() => ShadowRoot | Document | Node) | undefined;
-    [key: string]: any;
-}
-interface MachineSchema {
-    props?: MachineBaseProps | undefined;
-    context?: Record<string, any> | undefined;
-    refs?: Record<string, any> | undefined;
-    computed?: Record<string, any> | undefined;
-    state?: string | undefined;
-    tag?: string | undefined;
-    guard?: string | undefined;
-    action?: string | undefined;
-    effect?: string | undefined;
-    event?: ({
-        type: string;
-    } & Dict) | undefined;
-}
-type State<T extends MachineSchema> = Bindable<T["state"]> & {
-    hasTag: (tag: T["tag"]) => boolean;
-    matches: (...values: T["state"][]) => boolean;
-};
-type Service<T extends MachineSchema> = {
-    getStatus: () => MachineStatus;
-    state: State<T> & {
-        matches: (...values: T["state"][]) => boolean;
-        hasTag: (tag: T["tag"]) => boolean;
-    };
-    context: BindableContext<T>;
-    send: (event: EventType<T["event"]>) => void;
-    prop: PropFn<T>;
-    scope: Scope;
-    computed: ComputedFn<T>;
-    refs: BindableRefs<T>;
-    event: EventType<T["event"]> & {
-        current: () => EventType<T["event"]>;
-        previous: () => EventType<T["event"]>;
-    };
-};
-declare enum MachineStatus {
-    NotStarted = "Not Started",
-    Started = "Started",
-    Stopped = "Stopped"
-}
-declare const INIT_STATE = "__init__";
-
-declare function createGuards<T extends MachineSchema>(): {
-    and: (...guards: Array<GuardFn<T> | T["guard"]>) => (params: any) => boolean;
-    or: (...guards: Array<GuardFn<T> | T["guard"]>) => (params: any) => boolean;
-    not: (guard: GuardFn<T> | T["guard"]) => (params: any) => boolean;
-};
-declare function createMachine<T extends MachineSchema>(config: Machine<T>): Machine<T>;
-declare function setup<T extends MachineSchema>(): {
-    guards: {
-        and: (...guards: (T["guard"] | GuardFn<T>)[]) => (params: any) => boolean;
-        or: (...guards: (T["guard"] | GuardFn<T>)[]) => (params: any) => boolean;
-        not: (guard: T["guard"] | GuardFn<T>) => (params: any) => boolean;
-    };
-    createMachine: (config: Machine<T>) => Machine<T>;
-    choose: (transitions: Transition<T> | Transition<T>[]) => ({ choose }: Params<T>) => T["action"][] | undefined;
-};
-
-declare function createScope(props: Pick<Scope, "id" | "ids" | "getRootNode">): {
-    getRootNode: () => Document | ShadowRoot;
-    getDoc: () => Document;
-    getWin: () => Window & typeof globalThis;
-    getActiveElement: () => HTMLElement | null;
-    isActiveElement: typeof isActiveElement;
-    getById: <T extends Element = HTMLElement>(id: string) => T | null;
-    id?: string | undefined | undefined;
-    ids?: Record<string, any> | undefined;
-};
-
-export { type ActionsOrFn, type Bindable, type BindableContext, type BindableFn, type BindableParams, type BindableRefs, type ChooseFn, type ComputedFn, type EffectsOrFn, type EventObject, type GuardFn, INIT_STATE, type Machine, type MachineSchema, MachineStatus, type Params, type PropFn, type Scope, type Service, type Transition, type ValueOrFn, createGuards, createMachine, createScope, memo, mergeProps, setup };
+export { mergeProps } from './merge-props.mjs';
+export { memo } from './memo.mjs';
+export { createGuards, createMachine, setup } from './create-machine.mjs';
+export { ensureStateIndex, findTransition, getExitEnterStates, getStateChain, getStateDefinition, hasTag, matchesState, resolveStateValue } from './state.mjs';
+export { ActionsOrFn, Bindable, BindableContext, BindableFn, BindableParams, BindableRefs, ChooseFn, ComputedFn, EffectsOrFn, EventObject, GuardFn, INIT_STATE, Machine, MachineSchema, MachineState, MachineStatus, Params, PropFn, Scope, Service, Transition, TransitionMap, TransitionMatch, TransitionSet, ValueOrFn } from './types.mjs';
+export { createScope } from './scope.mjs';
+import '@zag-js/dom-query';