@eifi1/ui-kit 0.45.0 → 0.46.0

package/dist/sync/hooks.js

@@ -0,0 +1,67 @@
+"use client";
+import { useCallback, useEffect, useState, useSyncExternalStore } from "react";
+import { liveQuery } from "dexie";
+function useSyncWorker(engine) {
+  useEffect(() => {
+    if (!engine) return;
+    engine.start();
+    return () => engine.stop();
+  }, [engine]);
+}
+const IDLE = {
+  phase: "idle",
+  online: true,
+  counts: { pending: 0, waiting: 0, blocked: 0, rejected: 0 },
+  lastSyncedAt: null,
+  nextRetryAt: null
+};
+const noEngine = () => () => void 0;
+const idle = () => IDLE;
+function useSyncStatus(engine) {
+  const state = useSyncExternalStore(
+    engine ? engine.subscribe : noEngine,
+    engine ? engine.getState : idle,
+    engine ? engine.getState : idle
+  );
+  const browserOnline = useSyncExternalStore(subscribeOnline, readOnline, () => true);
+  const onSync = useCallback(async () => {
+    await engine?.syncNow();
+  }, [engine]);
+  const status = {
+    phase: state.phase,
+    online: engine ? state.online : browserOnline,
+    pending: state.counts.pending,
+    waitingForPlan: state.counts.waiting,
+    blocked: state.counts.blocked + state.counts.rejected,
+    lastSyncedAt: state.lastSyncedAt
+  };
+  return { status, onSync };
+}
+function subscribeOnline(listener) {
+  window.addEventListener("online", listener);
+  window.addEventListener("offline", listener);
+  return () => {
+    window.removeEventListener("online", listener);
+    window.removeEventListener("offline", listener);
+  };
+}
+const readOnline = () => navigator.onLine !== false;
+function useSyncQuery(db, query, deps) {
+  const [state, setState] = useState({ data: void 0, isLoading: true });
+  useEffect(() => {
+    if (!db) return;
+    const subscription = liveQuery(() => query(db)).subscribe({
+      next: (data) => setState({ data, isLoading: false }),
+      error: () => setState({ data: void 0, isLoading: false })
+    });
+    return () => subscription.unsubscribe();
+  }, [db, ...deps]);
+  return db ? state : NO_COPY;
+}
+const NO_COPY = { data: void 0, isLoading: true };
+export {
+  useSyncQuery,
+  useSyncStatus,
+  useSyncWorker
+};
+//# sourceMappingURL=hooks.js.map

package/dist/sync/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/sync/hooks.ts"],"sourcesContent":["import { useCallback, useEffect, useState, useSyncExternalStore } from \"react\";\nimport { liveQuery } from \"dexie\";\nimport type { SyncStatus } from \"../shell/sync-status-indicator\";\nimport type { SyncDb } from \"./db\";\nimport type { SyncEngine, SyncEngineState } from \"./engine\";\n\n/**\n * Keep `engine` running while it is mounted: started on mount, stopped on unmount or when\n * the engine changes (a company switch builds a new engine on its own database, D15).\n * `null` runs nothing — signed out, or a computer marked shared. Mount once, in the\n * signed-in layout (kastlan's `useHandoverSyncLoop`).\n */\nexport function useSyncWorker(engine: SyncEngine | null): void {\n  useEffect(() => {\n    if (!engine) return;\n    engine.start();\n    return () => engine.stop();\n  }, [engine]);\n}\n\nconst IDLE: SyncEngineState = {\n  phase: \"idle\",\n  online: true,\n  counts: { pending: 0, waiting: 0, blocked: 0, rejected: 0 },\n  lastSyncedAt: null,\n  nextRetryAt: null,\n};\nconst noEngine = () => () => undefined;\nconst idle = () => IDLE;\n\n/**\n * The engine's state as the kit's `SyncStatusIndicator` reads it (§2.3): `pending` = queued\n * and in flight (and the steps' pending), `waitingForPlan` = `waiting`, `blocked` = `blocked`\n * + `rejected`, `lastSyncedAt` from `meta`. `onSync` is \"Sync now\". Without an engine, an\n * idle status that follows the browser's connection.\n */\nexport function useSyncStatus(engine: SyncEngine | null): { status: SyncStatus; onSync: () => Promise<void> } {\n  const state = useSyncExternalStore(\n    engine ? engine.subscribe : noEngine,\n    engine ? engine.getState : idle,\n    engine ? engine.getState : idle,\n  );\n  const browserOnline = useSyncExternalStore(subscribeOnline, readOnline, () => true);\n  const onSync = useCallback(async () => {\n    await engine?.syncNow();\n  }, [engine]);\n  const status: SyncStatus = {\n    phase: state.phase,\n    online: engine ? state.online : browserOnline,\n    pending: state.counts.pending,\n    waitingForPlan: state.counts.waiting,\n    blocked: state.counts.blocked + state.counts.rejected,\n    lastSyncedAt: state.lastSyncedAt,\n  };\n  return { status, onSync };\n}\n\nfunction subscribeOnline(listener: () => void) {\n  window.addEventListener(\"online\", listener);\n  window.addEventListener(\"offline\", listener);\n  return () => {\n    window.removeEventListener(\"online\", listener);\n    window.removeEventListener(\"offline\", listener);\n  };\n}\nconst readOnline = () => navigator.onLine !== false;\n\n/**\n * A read of the copy that follows every change to it (Dexie's `liveQuery`; kastlan's\n * `useLive`). `deps` names what `query` reads; `query` itself is rebuilt every render.\n * `query` gets the app's own database type (`HandoverDb`). Without a database (not open\n * yet) it answers `isLoading: true`, so a page shows no \"empty\" before the copy opens.\n */\nexport function useSyncQuery<T, D extends SyncDb = SyncDb>(\n  db: D | null,\n  query: (db: D) => Promise<T>,\n  deps: readonly unknown[],\n): { data: T | undefined; isLoading: boolean } {\n  const [state, setState] = useState<{ data: T | undefined; isLoading: boolean }>({ data: undefined, isLoading: true });\n  useEffect(() => {\n    if (!db) return;\n    const subscription = liveQuery(() => query(db)).subscribe({\n      next: (data) => setState({ data, isLoading: false }),\n      error: () => setState({ data: undefined, isLoading: false }),\n    });\n    return () => subscription.unsubscribe();\n    // `query` is rebuilt every render; `deps` names what it reads.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [db, ...deps]);\n  return db ? state : NO_COPY;\n}\n\nconst NO_COPY = { data: undefined, isLoading: true } as const;\n"],"mappings":";AAAA,SAAS,aAAa,WAAW,UAAU,4BAA4B;AACvE,SAAS,iBAAiB;AAWnB,SAAS,cAAc,QAAiC;AAC7D,YAAU,MAAM;AACd,QAAI,CAAC,OAAQ;AACb,WAAO,MAAM;AACb,WAAO,MAAM,OAAO,KAAK;AAAA,EAC3B,GAAG,CAAC,MAAM,CAAC;AACb;AAEA,MAAM,OAAwB;AAAA,EAC5B,OAAO;AAAA,EACP,QAAQ;AAAA,EACR,QAAQ,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,UAAU,EAAE;AAAA,EAC1D,cAAc;AAAA,EACd,aAAa;AACf;AACA,MAAM,WAAW,MAAM,MAAM;AAC7B,MAAM,OAAO,MAAM;AAQZ,SAAS,cAAc,QAAgF;AAC5G,QAAM,QAAQ;AAAA,IACZ,SAAS,OAAO,YAAY;AAAA,IAC5B,SAAS,OAAO,WAAW;AAAA,IAC3B,SAAS,OAAO,WAAW;AAAA,EAC7B;AACA,QAAM,gBAAgB,qBAAqB,iBAAiB,YAAY,MAAM,IAAI;AAClF,QAAM,SAAS,YAAY,YAAY;AACrC,UAAM,QAAQ,QAAQ;AAAA,EACxB,GAAG,CAAC,MAAM,CAAC;AACX,QAAM,SAAqB;AAAA,IACzB,OAAO,MAAM;AAAA,IACb,QAAQ,SAAS,MAAM,SAAS;AAAA,IAChC,SAAS,MAAM,OAAO;AAAA,IACtB,gBAAgB,MAAM,OAAO;AAAA,IAC7B,SAAS,MAAM,OAAO,UAAU,MAAM,OAAO;AAAA,IAC7C,cAAc,MAAM;AAAA,EACtB;AACA,SAAO,EAAE,QAAQ,OAAO;AAC1B;AAEA,SAAS,gBAAgB,UAAsB;AAC7C,SAAO,iBAAiB,UAAU,QAAQ;AAC1C,SAAO,iBAAiB,WAAW,QAAQ;AAC3C,SAAO,MAAM;AACX,WAAO,oBAAoB,UAAU,QAAQ;AAC7C,WAAO,oBAAoB,WAAW,QAAQ;AAAA,EAChD;AACF;AACA,MAAM,aAAa,MAAM,UAAU,WAAW;AAQvC,SAAS,aACd,IACA,OACA,MAC6C;AAC7C,QAAM,CAAC,OAAO,QAAQ,IAAI,SAAsD,EAAE,MAAM,QAAW,WAAW,KAAK,CAAC;AACpH,YAAU,MAAM;AACd,QAAI,CAAC,GAAI;AACT,UAAM,eAAe,UAAU,MAAM,MAAM,EAAE,CAAC,EAAE,UAAU;AAAA,MACxD,MAAM,CAAC,SAAS,SAAS,EAAE,MAAM,WAAW,MAAM,CAAC;AAAA,MACnD,OAAO,MAAM,SAAS,EAAE,MAAM,QAAW,WAAW,MAAM,CAAC;AAAA,IAC7D,CAAC;AACD,WAAO,MAAM,aAAa,YAAY;AAAA,EAGxC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC;AAChB,SAAO,KAAK,QAAQ;AACtB;AAEA,MAAM,UAAU,EAAE,MAAM,QAAW,WAAW,KAAK;","names":[]}

package/dist/sync/testing.d.ts

@@ -0,0 +1,28 @@
+import type { SyncRequestBody, SyncResponseBody } from "./wire.js";
+/** One scripted answer: a body, a function of the request, or a failure. */
+export type FakeSyncAnswer = SyncResponseBody | ((body: SyncRequestBody) => SyncResponseBody | Promise<SyncResponseBody>) | {
+    fail: "offline";
+} | {
+    fail: number;
+    data?: unknown;
+};
+export interface FakeSyncTransport {
+    /** The engine's `send`. */
+    send(body: SyncRequestBody, signal?: AbortSignal): Promise<SyncResponseBody>;
+    /** Every request received, in order (the body as sent). */
+    readonly requests: SyncRequestBody[];
+    /** Queue answers for the next requests, in order; past them the default answers. */
+    answer(...answers: FakeSyncAnswer[]): void;
+    /** The next request meets no connection (an axios-like error with no response). */
+    failOffline(): void;
+    /** The next request answers `status` (a 5xx, a 402 `{code}`, a 403). */
+    failStatus(status: number, data?: unknown): void;
+    /** The default answer's server knowledge, raised by one for every request. */
+    knowledge: number;
+}
+/**
+ * The default answer echoes every pushed change as applied, with a server id (`pk`, 100 on),
+ * and an empty pull besides; `knowledge` goes up by one each request. Script anything else
+ * with `answer(...)`, `failOffline()` and `failStatus(...)`.
+ */
+export declare function createFakeSyncTransport(): FakeSyncTransport;

package/dist/sync/testing.js

@@ -0,0 +1,41 @@
+"use client";
+function wireError(fail, data) {
+  const err = new Error(fail === "offline" ? "Network Error" : `Request failed with status code ${fail}`);
+  return Object.assign(err, {
+    isAxiosError: true,
+    response: fail === "offline" ? void 0 : { status: fail, data: data ?? {} }
+  });
+}
+function createFakeSyncTransport() {
+  const script = [];
+  let nextPk = 100;
+  const transport = {
+    requests: [],
+    knowledge: 0,
+    answer: (...answers) => void script.push(...answers),
+    failOffline: () => void script.push({ fail: "offline" }),
+    failStatus: (status, data) => void script.push({ fail: status, data }),
+    async send(body) {
+      transport.requests.push(structuredClone(body));
+      const next = script.shift();
+      if (next && typeof next === "object" && "fail" in next) {
+        throw wireError(next.fail, "data" in next ? next.data : void 0);
+      }
+      if (typeof next === "function") return next(body);
+      if (next) return next;
+      transport.knowledge += 1;
+      return {
+        server_knowledge: transport.knowledge,
+        changes: body.changes.map((change) => ({ ...change, pk: change.op === "delete" ? null : nextPk++ })),
+        rejections: [],
+        refused: null,
+        page_cursor: null
+      };
+    }
+  };
+  return transport;
+}
+export {
+  createFakeSyncTransport
+};
+//# sourceMappingURL=testing.js.map

package/dist/sync/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/sync/testing.ts"],"sourcesContent":["import type { SyncRequestBody, SyncResponseBody } from \"./wire\";\n\n/*\n * `@eifi1/ui-kit/sync/testing` — a scripted `/sync` server for an app's tests of the engine\n * (docs/local-first-harmonization.md §2.3). Pass `transport.send` as the engine's `send`.\n * Imports nothing (no Dexie): it is the engine's `send`, not a store.\n */\n\n/** One scripted answer: a body, a function of the request, or a failure. */\nexport type FakeSyncAnswer =\n  | SyncResponseBody\n  | ((body: SyncRequestBody) => SyncResponseBody | Promise<SyncResponseBody>)\n  | { fail: \"offline\" }\n  | { fail: number; data?: unknown };\n\nexport interface FakeSyncTransport {\n  /** The engine's `send`. */\n  send(body: SyncRequestBody, signal?: AbortSignal): Promise<SyncResponseBody>;\n  /** Every request received, in order (the body as sent). */\n  readonly requests: SyncRequestBody[];\n  /** Queue answers for the next requests, in order; past them the default answers. */\n  answer(...answers: FakeSyncAnswer[]): void;\n  /** The next request meets no connection (an axios-like error with no response). */\n  failOffline(): void;\n  /** The next request answers `status` (a 5xx, a 402 `{code}`, a 403). */\n  failStatus(status: number, data?: unknown): void;\n  /** The default answer's server knowledge, raised by one for every request. */\n  knowledge: number;\n}\n\n/** The error an axios client throws: `isAxiosError`, and `response` only with an answer. */\nfunction wireError(fail: \"offline\" | number, data?: unknown): Error {\n  const err = new Error(fail === \"offline\" ? \"Network Error\" : `Request failed with status code ${fail}`);\n  return Object.assign(err, {\n    isAxiosError: true,\n    response: fail === \"offline\" ? undefined : { status: fail, data: data ?? {} },\n  });\n}\n\n/**\n * The default answer echoes every pushed change as applied, with a server id (`pk`, 100 on),\n * and an empty pull besides; `knowledge` goes up by one each request. Script anything else\n * with `answer(...)`, `failOffline()` and `failStatus(...)`.\n */\nexport function createFakeSyncTransport(): FakeSyncTransport {\n  const script: FakeSyncAnswer[] = [];\n  let nextPk = 100;\n  const transport: FakeSyncTransport = {\n    requests: [],\n    knowledge: 0,\n    answer: (...answers) => void script.push(...answers),\n    failOffline: () => void script.push({ fail: \"offline\" }),\n    failStatus: (status, data) => void script.push({ fail: status, data }),\n    async send(body) {\n      transport.requests.push(structuredClone(body));\n      const next = script.shift();\n      if (next && typeof next === \"object\" && \"fail\" in next) {\n        throw wireError(next.fail, \"data\" in next ? next.data : undefined);\n      }\n      if (typeof next === \"function\") return next(body);\n      if (next) return next;\n      transport.knowledge += 1;\n      return {\n        server_knowledge: transport.knowledge,\n        changes: body.changes.map((change) => ({ ...change, pk: change.op === \"delete\" ? null : nextPk++ })),\n        rejections: [],\n        refused: null,\n        page_cursor: null,\n      };\n    },\n  };\n  return transport;\n}\n"],"mappings":";AA+BA,SAAS,UAAU,MAA0B,MAAuB;AAClE,QAAM,MAAM,IAAI,MAAM,SAAS,YAAY,kBAAkB,mCAAmC,IAAI,EAAE;AACtG,SAAO,OAAO,OAAO,KAAK;AAAA,IACxB,cAAc;AAAA,IACd,UAAU,SAAS,YAAY,SAAY,EAAE,QAAQ,MAAM,MAAM,QAAQ,CAAC,EAAE;AAAA,EAC9E,CAAC;AACH;AAOO,SAAS,0BAA6C;AAC3D,QAAM,SAA2B,CAAC;AAClC,MAAI,SAAS;AACb,QAAM,YAA+B;AAAA,IACnC,UAAU,CAAC;AAAA,IACX,WAAW;AAAA,IACX,QAAQ,IAAI,YAAY,KAAK,OAAO,KAAK,GAAG,OAAO;AAAA,IACnD,aAAa,MAAM,KAAK,OAAO,KAAK,EAAE,MAAM,UAAU,CAAC;AAAA,IACvD,YAAY,CAAC,QAAQ,SAAS,KAAK,OAAO,KAAK,EAAE,MAAM,QAAQ,KAAK,CAAC;AAAA,IACrE,MAAM,KAAK,MAAM;AACf,gBAAU,SAAS,KAAK,gBAAgB,IAAI,CAAC;AAC7C,YAAM,OAAO,OAAO,MAAM;AAC1B,UAAI,QAAQ,OAAO,SAAS,YAAY,UAAU,MAAM;AACtD,cAAM,UAAU,KAAK,MAAM,UAAU,OAAO,KAAK,OAAO,MAAS;AAAA,MACnE;AACA,UAAI,OAAO,SAAS,WAAY,QAAO,KAAK,IAAI;AAChD,UAAI,KAAM,QAAO;AACjB,gBAAU,aAAa;AACvB,aAAO;AAAA,QACL,kBAAkB,UAAU;AAAA,QAC5B,SAAS,KAAK,QAAQ,IAAI,CAAC,YAAY,EAAE,GAAG,QAAQ,IAAI,OAAO,OAAO,WAAW,OAAO,SAAS,EAAE;AAAA,QACnG,YAAY,CAAC;AAAA,QACb,SAAS;AAAA,QACT,aAAa;AAAA,MACf;AAAA,IACF;AAAA,EACF;AACA,SAAO;AACT;","names":[]}

package/dist/sync/wire.d.ts

@@ -0,0 +1,50 @@
+/** One row's delta on the wire. */
+export interface SyncWireChange {
+    entity: string;
+    id: string;
+    op: "upsert" | "delete";
+    data?: Record<string, unknown> | null;
+    /** The device's edit time on a push (D2). */
+    updated_at?: string | null;
+    /** The server's id of the row, on a pull (kastlan). */
+    pk?: number | null;
+    knowledge?: number | null;
+}
+/** Where a paged pull stopped (server-kit `SyncPageCursor`); handed back as it came. */
+export interface SyncPageCursor {
+    entity: string;
+    knowledge?: number | null;
+    id?: string | null;
+    window_end: number;
+}
+export interface SyncRequestBody {
+    scope: string;
+    last_knowledge: number;
+    changes: SyncWireChange[];
+    /** This client keeps refused changes and reads `refused` and `rejections` (D1). */
+    refusals: true;
+    /** The device's clock as the body is built, fresh for every request (D2 amendment). */
+    client_now: string;
+    paged?: boolean;
+    page_cursor?: SyncPageCursor | null;
+}
+/** The WHOLE push refused (a lapsed plan): the pull is served all the same. */
+export interface SyncRefusalBody {
+    code: string;
+    detail: string;
+    change_ids: string[];
+}
+/** One pushed change the server did not apply, with its reason. */
+export interface SyncRejectionBody {
+    change_id: string;
+    code: string;
+    detail: string;
+}
+export interface SyncResponseBody {
+    server_knowledge: number;
+    changes: SyncWireChange[];
+    refused?: SyncRefusalBody | null;
+    rejections?: SyncRejectionBody[];
+    /** Set while the pull did not fit one page; `null` on the last page (D12). */
+    page_cursor?: SyncPageCursor | null;
+}

package/dist/sync/wire.js

@@ -0,0 +1,2 @@
+"use client";
+//# sourceMappingURL=wire.js.map

package/dist/sync/wire.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/sync.d.ts

@@ -0,0 +1,7 @@
+export { createSyncDb, SYNC_DB_STORES } from "./sync/db.js";
+export type { CreateSyncDbOptions, OutboxChange, OutboxStatus, SyncDb, SyncDbUpgrade, SyncedRow, SyncMetaEntry } from "./sync/db.js";
+export { createSyncEngine, DEFAULT_HOLD_CODES, DEFAULT_SYNC_BACKOFF_MS, releaseSyncEngine, syncEngineFor } from "./sync/engine.js";
+export type { SyncCounts, SyncEngine, SyncEngineOptions, SyncEngineState, SyncRoundResult, SyncStep, SyncStepContext, SyncStepResult, } from "./sync/engine.js";
+export { useSyncQuery, useSyncStatus, useSyncWorker } from "./sync/hooks.js";
+export type { SyncPageCursor, SyncRefusalBody, SyncRejectionBody, SyncRequestBody, SyncResponseBody, SyncWireChange, } from "./sync/wire.js";
+export { isOfflineError, readLocalFirst, stampAfter, writeLocalFirst } from "./offline/local-first.js";

package/dist/sync.js

@@ -0,0 +1,22 @@
+"use client";
+import { createSyncDb, SYNC_DB_STORES } from "./sync/db.js";
+import { createSyncEngine, DEFAULT_HOLD_CODES, DEFAULT_SYNC_BACKOFF_MS, releaseSyncEngine, syncEngineFor } from "./sync/engine.js";
+import { useSyncQuery, useSyncStatus, useSyncWorker } from "./sync/hooks.js";
+import { isOfflineError, readLocalFirst, stampAfter, writeLocalFirst } from "./offline/local-first.js";
+export {
+  DEFAULT_HOLD_CODES,
+  DEFAULT_SYNC_BACKOFF_MS,
+  SYNC_DB_STORES,
+  createSyncDb,
+  createSyncEngine,
+  isOfflineError,
+  readLocalFirst,
+  releaseSyncEngine,
+  stampAfter,
+  syncEngineFor,
+  useSyncQuery,
+  useSyncStatus,
+  useSyncWorker,
+  writeLocalFirst
+};
+//# sourceMappingURL=sync.js.map

package/dist/sync.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/sync.ts"],"sourcesContent":["// `@eifi1/ui-kit/sync` — local-first phase 3 (docs/local-first-harmonization.md §2.3, 0.46):\n// the sync engine on a Dexie copy, its worker and status hooks, and the live read of the copy.\n//\n// The only entry point that imports `dexie` — an optional peer for that reason. It never loads\n// `/offline`'s TanStack and idb-keyval peers: the leaf utilities both entries export live in\n// one module of their own (src/offline/local-first.ts). NOT re-exported from the main barrel.\nexport { createSyncDb, SYNC_DB_STORES } from \"./sync/db\";\nexport type { CreateSyncDbOptions, OutboxChange, OutboxStatus, SyncDb, SyncDbUpgrade, SyncedRow, SyncMetaEntry } from \"./sync/db\";\nexport { createSyncEngine, DEFAULT_HOLD_CODES, DEFAULT_SYNC_BACKOFF_MS, releaseSyncEngine, syncEngineFor } from \"./sync/engine\";\nexport type {\n  SyncCounts,\n  SyncEngine,\n  SyncEngineOptions,\n  SyncEngineState,\n  SyncRoundResult,\n  SyncStep,\n  SyncStepContext,\n  SyncStepResult,\n} from \"./sync/engine\";\nexport { useSyncQuery, useSyncStatus, useSyncWorker } from \"./sync/hooks\";\nexport type {\n  SyncPageCursor,\n  SyncRefusalBody,\n  SyncRejectionBody,\n  SyncRequestBody,\n  SyncResponseBody,\n  SyncWireChange,\n} from \"./sync/wire\";\nexport { isOfflineError, readLocalFirst, stampAfter, writeLocalFirst } from \"./offline/local-first\";\n"],"mappings":";AAMA,SAAS,cAAc,sBAAsB;AAE7C,SAAS,kBAAkB,oBAAoB,yBAAyB,mBAAmB,qBAAqB;AAWhH,SAAS,cAAc,eAAe,qBAAqB;AAS3D,SAAS,gBAAgB,gBAAgB,YAAY,uBAAuB;","names":[]}

package/dist/tour/tour-labels.js

@@ -5,6 +5,7 @@ const DEFAULT_TOUR_LABELS = {
   skip: "Skip",
   done: "Done",
   awaitClickHint: "Click the highlighted element to continue",
+  awaitInputHint: "Enter a value in the highlighted field to continue",
   step: (c, t) => `${c} / ${t}`
 };
 export {

package/dist/tour/tour-labels.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/tour/tour-labels.ts"],"sourcesContent":["// The English words of ./tour, in a module with no component code: the English catalogue\n// (src/i18n/defaults.ts) imports them without the component, so `en` loads as one chunk\n// like the other languages (0.34, KS U8). ./tour re-exports them.\n\nimport type { TourLabels } from \"./tour\";\n\nexport const DEFAULT_TOUR_LABELS: TourLabels = {\n  next: \"Next\",\n  back: \"Back\",\n  skip: \"Skip\",\n  done: \"Done\",\n  awaitClickHint: \"Click the highlighted element to continue\",\n  step: (c, t) => `${c} / ${t}`,\n};\n"],"mappings":";AAMO,MAAM,sBAAkC;AAAA,EAC7C,MAAM;AAAA,EACN,MAAM;AAAA,EACN,MAAM;AAAA,EACN,MAAM;AAAA,EACN,gBAAgB;AAAA,EAChB,MAAM,CAAC,GAAG,MAAM,GAAG,CAAC,MAAM,CAAC;AAC7B;","names":[]}
+{"version":3,"sources":["../../src/tour/tour-labels.ts"],"sourcesContent":["// The English words of ./tour, in a module with no component code: the English catalogue\n// (src/i18n/defaults.ts) imports them without the component, so `en` loads as one chunk\n// like the other languages (0.34, KS U8). ./tour re-exports them.\n\nimport type { TourLabels } from \"./tour\";\n\nexport const DEFAULT_TOUR_LABELS: TourLabels = {\n  next: \"Next\",\n  back: \"Back\",\n  skip: \"Skip\",\n  done: \"Done\",\n  awaitClickHint: \"Click the highlighted element to continue\",\n  awaitInputHint: \"Enter a value in the highlighted field to continue\",\n  step: (c, t) => `${c} / ${t}`,\n};\n"],"mappings":";AAMO,MAAM,sBAAkC;AAAA,EAC7C,MAAM;AAAA,EACN,MAAM;AAAA,EACN,MAAM;AAAA,EACN,MAAM;AAAA,EACN,gBAAgB;AAAA,EAChB,gBAAgB;AAAA,EAChB,MAAM,CAAC,GAAG,MAAM,GAAG,CAAC,MAAM,CAAC;AAC7B;","names":[]}

package/dist/tour/tour.d.ts

@@ -30,6 +30,34 @@ export interface TourStep {
      *  first, then the tour steps forward on a microtask. The spotlight hole stays
      *  click-through to the target; the rest of the page does not. */
     awaitClick?: boolean;
+    /**
+     * The spotlighted control is for USING, not only for looking at (0.46, keksdose live
+     * #436): the layers it opens sit above the scrim and work. A plain step's overlay is
+     * `z-[60]`, over every kit layer, so a field whose number pad (`NumberPadSheet`), a
+     * select's menu or a popover opens at `z-50` opened UNDER the shields, where nothing
+     * could be tapped. Here the overlay drops to `z-[45]`: still over the top bar and the
+     * page (`z-40` and below, still dimmed and shielded), under every `z-50` layer the
+     * target opens — so an app's own layer wants `z-50` or more to clear it. Keys pressed
+     * in the target or in such a layer are theirs (Escape closes the pad, arrows walk a
+     * list); from the card the tour's keys work as on any step. The overlay is not
+     * `aria-modal` then, and carries `data-tour-interactive`.
+     *
+     * The card is in the same layer as the scrim, so an open pad or sheet may cover it
+     * until it closes. Requires `target`. A `HoverMenu` (`z-40`, the top bar's menus) stays
+     * under the scrim: point an `awaitClick` step at its trigger instead.
+     */
+    interactive?: boolean;
+    /**
+     * Advance once a value was ENTERED in the spotlighted control (0.46, keksdose live
+     * #436) — `awaitClick` for a field. Implies `interactive`. Counted when focus leaves
+     * the target (the number pad's Done, a Tab, a tap elsewhere), or Enter is pressed in
+     * it, and one of its fields (`input`, `textarea`, `select`: the target itself or
+     * inside it) then holds another value than when the step began; a native `change`
+     * (a select, a checkbox) counts at once. The card swaps Next for `awaitInputHint`,
+     * as for `awaitClick`. A picker whose value is not a field's (the kit's `Select`
+     * button) has nothing to compare: call `useTour().next()` from its `onChange`.
+     */
+    awaitInput?: boolean;
     /** Runs before the step is shown — e.g. navigate to a route, open a panel.
      *  May be async; the step waits for it, then locates the target. */
     beforeStep?: () => void | Promise<void>;
@@ -41,6 +69,8 @@ export interface TourLabels {
     done: string;
     /** Shown in place of the Next button on an `awaitClick` step. */
     awaitClickHint: string;
+    /** Shown in place of the Next button on an `awaitInput` step (0.46). */
+    awaitInputHint: string;
     /** Step counter, e.g. (2, 7) => "2 / 7". */
     step: (current: number, total: number) => string;
 }

package/dist/tour/tour.js

@@ -225,14 +225,51 @@ function TourOverlay({
     el.addEventListener("click", onClick, { once: true });
     return () => el.removeEventListener("click", onClick);
   }, [ready, spotted, index, step, onNext]);
+  const interactive = spotted && !!step.target && !!(step.interactive || step.awaitInput);
+  useEffect(() => {
+    if (!ready || !spotted || !step.awaitInput || !step.target) return;
+    const el = queryVisibleTarget(step.target);
+    if (!el) return;
+    const read = () => fieldValues(el);
+    const before = read();
+    let timer = 0;
+    let done = false;
+    const check = () => {
+      window.clearTimeout(timer);
+      timer = window.setTimeout(() => {
+        if (done || read() === before) return;
+        done = true;
+        onNext();
+      }, 0);
+    };
+    const onFocusOut = (e) => {
+      if (e.relatedTarget instanceof Node && el.contains(e.relatedTarget)) return;
+      check();
+    };
+    const onKeyDown = (e) => {
+      if (e.key === "Enter") check();
+    };
+    el.addEventListener("focusout", onFocusOut);
+    el.addEventListener("keydown", onKeyDown);
+    el.addEventListener("change", check);
+    return () => {
+      window.clearTimeout(timer);
+      el.removeEventListener("focusout", onFocusOut);
+      el.removeEventListener("keydown", onKeyDown);
+      el.removeEventListener("change", check);
+    };
+  }, [ready, spotted, index, step, onNext]);
   useEffect(() => {
     const onKey = (e) => {
+      if (interactive && e.target instanceof Node && e.target !== document.body && !rootRef.current?.contains(e.target)) {
+        return;
+      }
       if (e.key === "Escape") {
         onSkip();
         return;
       }
       if (e.key === "Enter") {
-        if (step.awaitClick || ownsKey(e.target, "Enter")) return;
+        if (step.awaitClick || step.awaitInput || ownsKey(e.target, "Enter")) return;
         e.preventDefault();
         onNext();
         return;
@@ -248,7 +285,7 @@ function TourOverlay({
     };
     document.addEventListener("keydown", onKey);
     return () => document.removeEventListener("keydown", onKey);
-  }, [isFirst, step, onNext, onPrev, onSkip]);
+  }, [isFirst, step, interactive, onNext, onPrev, onSkip]);
   if (!ready) return null;
   const pad = step.padding ?? 8;
   const spot = rect ? { top: rect.top - pad, left: rect.left - pad, width: rect.width + pad * 2, height: rect.height + pad * 2 } : null;
@@ -257,9 +294,10 @@ function TourOverlay({
       "div",
       {
         ref: rootRef,
-        className: "pointer-events-none fixed inset-0 z-[60]",
+        className: cn("pointer-events-none fixed inset-0", interactive ? "z-[45]" : "z-[60]"),
         role: "dialog",
-        "aria-modal": "true",
+        "aria-modal": interactive ? void 0 : "true",
+        "data-tour-interactive": interactive ? "" : void 0,
         "aria-label": step.title,
         dir,
         children: [
@@ -318,6 +356,12 @@ function TourOverlay({
     document.body
   );
 }
+function fieldValues(el) {
+  const fields = el.matches("input,textarea,select") ? [el] : Array.from(el.querySelectorAll("input,textarea,select"));
+  return fields.map(
+    (f) => f instanceof HTMLInputElement && (f.type === "checkbox" || f.type === "radio") ? String(f.checked) : f.value
+  ).join("\0");
+}
 function ownsKey(target, key) {
   if (!(target instanceof HTMLElement)) return false;
   if (target.isContentEditable) return true;
@@ -435,10 +479,10 @@ function TourCard({
             /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-2", children: [
               /* @__PURE__ */ jsx("span", { className: "whitespace-nowrap text-xs tabular-nums text-placeholder", children: labels.step(index + 1, total) }),
               !isFirst && /* @__PURE__ */ jsx(Button, { variant: "secondary", onClick: onBack, className: "px-2.5 py-1 text-xs", children: labels.back }),
-              !(step.awaitClick && step.target && rect) && /* @__PURE__ */ jsx(Button, { variant: "brand", onClick: onNext, className: cn("px-2.5 py-1 text-xs"), children: isLast ? labels.done : labels.next })
+              !((step.awaitClick || step.awaitInput) && step.target && rect) && /* @__PURE__ */ jsx(Button, { variant: "brand", onClick: onNext, className: cn("px-2.5 py-1 text-xs"), children: isLast ? labels.done : labels.next })
             ] })
           ] }),
-          step.awaitClick && step.target && rect && /* @__PURE__ */ jsx("div", { className: "text-center text-xs italic text-placeholder", children: labels.awaitClickHint })
+          (step.awaitClick || step.awaitInput) && step.target && rect && /* @__PURE__ */ jsx("div", { className: "text-center text-xs italic text-placeholder", children: step.awaitInput && !step.awaitClick ? labels.awaitInputHint : labels.awaitClickHint })
         ] })
       ]
     }