@zag-js/core 1.35.0 → 1.35.1

package/README.md

@@ -102,6 +102,45 @@ const machine = createMachine({
 // 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)`

package/dist/state.js

@@ -31,20 +31,36 @@ __export(state_exports, {
 });
 module.exports = __toCommonJS(state_exports);
 var STATE_DELIMITER = ".";
+var ABSOLUTE_PREFIX = "#";
 var stateIndexCache = /* @__PURE__ */ new WeakMap();
+var stateIdIndexCache = /* @__PURE__ */ new WeakMap();
 function joinStatePath(parts) {
   return parts.join(STATE_DELIMITER);
 }
 function isAbsoluteStatePath(value) {
   return value.includes(STATE_DELIMITER);
 }
+function isExplicitAbsoluteStatePath(value) {
+  return value.startsWith(ABSOLUTE_PREFIX);
+}
+function stripAbsolutePrefix(value) {
+  return isExplicitAbsoluteStatePath(value) ? value.slice(ABSOLUTE_PREFIX.length) : value;
+}
 function appendStatePath(base, segment) {
   return base ? `${base}${STATE_DELIMITER}${segment}` : segment;
 }
 function buildStateIndex(machine) {
   const index = /* @__PURE__ */ new Map();
+  const idIndex = /* @__PURE__ */ new Map();
   const visit = (basePath, state) => {
     index.set(basePath, state);
+    const stateId = state.id;
+    if (stateId) {
+      if (idIndex.has(stateId)) {
+        throw new Error(`Duplicate state id: ${stateId}`);
+      }
+      idIndex.set(stateId, basePath);
+    }
     const childStates = state.states;
     if (!childStates) return;
     for (const [childKey, childState] of Object.entries(childStates)) {
@@ -57,15 +73,20 @@ function buildStateIndex(machine) {
     if (!topState) continue;
     visit(topKey, topState);
   }
-  return index;
+  return { index, idIndex };
 }
 function ensureStateIndex(machine) {
   const cached = stateIndexCache.get(machine);
   if (cached) return cached;
-  const index = buildStateIndex(machine);
+  const { index, idIndex } = buildStateIndex(machine);
   stateIndexCache.set(machine, index);
+  stateIdIndexCache.set(machine, idIndex);
   return index;
 }
+function getStatePathById(machine, stateId) {
+  ensureStateIndex(machine);
+  return stateIdIndexCache.get(machine)?.get(stateId);
+}
 function toSegments(value) {
   if (!value) return [];
   return String(value).split(STATE_DELIMITER).filter(Boolean);
@@ -112,6 +133,14 @@ function hasStatePath(machine, value) {
 }
 function resolveStateValue(machine, value, source) {
   const stateValue = String(value);
+  if (isExplicitAbsoluteStatePath(stateValue)) {
+    const stateId = stripAbsolutePrefix(stateValue);
+    const statePath = getStatePathById(machine, stateId);
+    if (!statePath) {
+      throw new Error(`Unknown state id: ${stateId}`);
+    }
+    return resolveAbsoluteStateValue(machine, statePath);
+  }
   if (!isAbsoluteStatePath(stateValue) && source) {
     const sourceSegments = toSegments(source);
     for (let index = sourceSegments.length; index >= 1; index--) {

package/dist/state.mjs

@@ -1,19 +1,35 @@
 // src/state.ts
 var STATE_DELIMITER = ".";
+var ABSOLUTE_PREFIX = "#";
 var stateIndexCache = /* @__PURE__ */ new WeakMap();
+var stateIdIndexCache = /* @__PURE__ */ new WeakMap();
 function joinStatePath(parts) {
   return parts.join(STATE_DELIMITER);
 }
 function isAbsoluteStatePath(value) {
   return value.includes(STATE_DELIMITER);
 }
+function isExplicitAbsoluteStatePath(value) {
+  return value.startsWith(ABSOLUTE_PREFIX);
+}
+function stripAbsolutePrefix(value) {
+  return isExplicitAbsoluteStatePath(value) ? value.slice(ABSOLUTE_PREFIX.length) : value;
+}
 function appendStatePath(base, segment) {
   return base ? `${base}${STATE_DELIMITER}${segment}` : segment;
 }
 function buildStateIndex(machine) {
   const index = /* @__PURE__ */ new Map();
+  const idIndex = /* @__PURE__ */ new Map();
   const visit = (basePath, state) => {
     index.set(basePath, state);
+    const stateId = state.id;
+    if (stateId) {
+      if (idIndex.has(stateId)) {
+        throw new Error(`Duplicate state id: ${stateId}`);
+      }
+      idIndex.set(stateId, basePath);
+    }
     const childStates = state.states;
     if (!childStates) return;
     for (const [childKey, childState] of Object.entries(childStates)) {
@@ -26,15 +42,20 @@ function buildStateIndex(machine) {
     if (!topState) continue;
     visit(topKey, topState);
   }
-  return index;
+  return { index, idIndex };
 }
 function ensureStateIndex(machine) {
   const cached = stateIndexCache.get(machine);
   if (cached) return cached;
-  const index = buildStateIndex(machine);
+  const { index, idIndex } = buildStateIndex(machine);
   stateIndexCache.set(machine, index);
+  stateIdIndexCache.set(machine, idIndex);
   return index;
 }
+function getStatePathById(machine, stateId) {
+  ensureStateIndex(machine);
+  return stateIdIndexCache.get(machine)?.get(stateId);
+}
 function toSegments(value) {
   if (!value) return [];
   return String(value).split(STATE_DELIMITER).filter(Boolean);
@@ -81,6 +102,14 @@ function hasStatePath(machine, value) {
 }
 function resolveStateValue(machine, value, source) {
   const stateValue = String(value);
+  if (isExplicitAbsoluteStatePath(stateValue)) {
+    const stateId = stripAbsolutePrefix(stateValue);
+    const statePath = getStatePathById(machine, stateId);
+    if (!statePath) {
+      throw new Error(`Unknown state id: ${stateId}`);
+    }
+    return resolveAbsoluteStateValue(machine, statePath);
+  }
   if (!isAbsoluteStatePath(stateValue) && source) {
     const sourceSegments = toSegments(source);
     for (let index = sourceSegments.length; index >= 1; index--) {

package/dist/types.d.mts

@@ -109,8 +109,9 @@ type ChildStateKey<S extends string, Parent extends string> = S extends `${Paren
 type ParentPath<S extends string> = S extends `${infer Parent}.${string}` ? Parent : never;
 type AncestorPaths<S extends string> = S | (ParentPath<S> extends never ? never : AncestorPaths<ParentPath<S>>);
 type RelativeStateTarget<S extends string, Source extends string> = ChildStateKey<S, AncestorPaths<Source>>;
+type StateIdTarget = `#${string}`;
 interface Transition<T extends Dict, Source extends string | undefined = string | undefined> {
-    target?: T["state"] | (Source extends string ? RelativeStateTarget<T["state"], Source> : never) | undefined;
+    target?: T["state"] | StateIdTarget | (Source extends string ? RelativeStateTarget<T["state"], Source> : never) | undefined;
     actions?: T["action"][] | undefined;
     guard?: T["guard"] | GuardFn<T> | undefined;
     reenter?: boolean | undefined;
@@ -134,6 +135,7 @@ interface RefsParams<T extends Dict> {
 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 MachineState<T extends Dict, Parent extends string = string> {
+    id?: string | undefined;
     tags?: T["tag"][] | undefined;
     entry?: ActionsOrFn<T> | undefined;
     exit?: ActionsOrFn<T> | undefined;

package/dist/types.d.ts

@@ -109,8 +109,9 @@ type ChildStateKey<S extends string, Parent extends string> = S extends `${Paren
 type ParentPath<S extends string> = S extends `${infer Parent}.${string}` ? Parent : never;
 type AncestorPaths<S extends string> = S | (ParentPath<S> extends never ? never : AncestorPaths<ParentPath<S>>);
 type RelativeStateTarget<S extends string, Source extends string> = ChildStateKey<S, AncestorPaths<Source>>;
+type StateIdTarget = `#${string}`;
 interface Transition<T extends Dict, Source extends string | undefined = string | undefined> {
-    target?: T["state"] | (Source extends string ? RelativeStateTarget<T["state"], Source> : never) | undefined;
+    target?: T["state"] | StateIdTarget | (Source extends string ? RelativeStateTarget<T["state"], Source> : never) | undefined;
     actions?: T["action"][] | undefined;
     guard?: T["guard"] | GuardFn<T> | undefined;
     reenter?: boolean | undefined;
@@ -134,6 +135,7 @@ interface RefsParams<T extends Dict> {
 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 MachineState<T extends Dict, Parent extends string = string> {
+    id?: string | undefined;
     tags?: T["tag"][] | undefined;
     entry?: ActionsOrFn<T> | undefined;
     exit?: ActionsOrFn<T> | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zag-js/core",
-  "version": "1.35.0",
+  "version": "1.35.1",
   "description": "A minimal implementation of xstate fsm for UI machines",
   "keywords": [
     "ui-machines",
@@ -25,8 +25,8 @@
     "url": "https://github.com/chakra-ui/zag/issues"
   },
   "dependencies": {
-    "@zag-js/utils": "1.35.0",
-    "@zag-js/dom-query": "1.35.0"
+    "@zag-js/utils": "1.35.1",
+    "@zag-js/dom-query": "1.35.1"
   },
   "devDependencies": {
     "clean-package": "2.2.0"