@eifi1/ui-kit 0.45.0 → 0.46.1

package/src/sync/hooks.ts

@@ -0,0 +1,98 @@
+import { useCallback, useEffect, useState, useSyncExternalStore } from "react";
+import { liveQuery } from "dexie";
+import type { SyncStatus } from "../shell/sync-status-indicator";
+import type { SyncDb } from "./db";
+import type { SyncEngine, SyncEngineState } from "./engine";
+
+/**
+ * Keep `engine` running while it is mounted: started on mount, stopped on unmount or when
+ * the engine changes (a company switch builds a new engine on its own database, D15).
+ * `null` runs nothing — signed out, or a computer marked shared. Mount once, in the
+ * signed-in layout (kastlan's `useHandoverSyncLoop`).
+ */
+export function useSyncWorker(engine: SyncEngine | null): void {
+  useEffect(() => {
+    if (!engine) return;
+    engine.start();
+    return () => engine.stop();
+  }, [engine]);
+}
+
+const IDLE: SyncEngineState = {
+  phase: "idle",
+  online: true,
+  counts: { pending: 0, waiting: 0, blocked: 0, rejected: 0 },
+  lastSyncedAt: null,
+  nextRetryAt: null,
+};
+const noEngine = () => () => undefined;
+const idle = () => IDLE;
+
+/**
+ * The engine's state as the kit's `SyncStatusIndicator` reads it (§2.3): `pending` = queued
+ * and in flight (and the steps' pending), `waitingForPlan` = `waiting`, `blocked` = `blocked`
+ * + `rejected`, `lastSyncedAt` from `meta`. `onSync` is "Sync now". Without an engine, an
+ * idle status that follows the browser's connection.
+ *
+ * With a `null` engine (signed out, or a computer marked shared) `status.online` follows
+ * `navigator.onLine` and its `online`/`offline` events, so an app may lean on
+ * `status.online` for its own offline lock (kastlan's offline write lock) whether or not an
+ * engine runs.
+ */
+export function useSyncStatus(engine: SyncEngine | null): { status: SyncStatus; onSync: () => Promise<void> } {
+  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: SyncStatus = {
+    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: () => void) {
+  window.addEventListener("online", listener);
+  window.addEventListener("offline", listener);
+  return () => {
+    window.removeEventListener("online", listener);
+    window.removeEventListener("offline", listener);
+  };
+}
+const readOnline = () => navigator.onLine !== false;
+
+/**
+ * A read of the copy that follows every change to it (Dexie's `liveQuery`; kastlan's
+ * `useLive`). `deps` names what `query` reads; `query` itself is rebuilt every render.
+ * `query` gets the app's own database type (`HandoverDb`). Without a database (not open
+ * yet) it answers `isLoading: true`, so a page shows no "empty" before the copy opens.
+ */
+export function useSyncQuery<T, D extends SyncDb = SyncDb>(
+  db: D | null,
+  query: (db: D) => Promise<T>,
+  deps: readonly unknown[],
+): { data: T | undefined; isLoading: boolean } {
+  const [state, setState] = useState<{ data: T | undefined; isLoading: boolean }>({ data: undefined, isLoading: true });
+  useEffect(() => {
+    if (!db) return;
+    const subscription = liveQuery(() => query(db)).subscribe({
+      next: (data) => setState({ data, isLoading: false }),
+      error: () => setState({ data: undefined, isLoading: false }),
+    });
+    return () => subscription.unsubscribe();
+    // `query` is rebuilt every render; `deps` names what it reads.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [db, ...deps]);
+  return db ? state : NO_COPY;
+}
+
+const NO_COPY = { data: undefined, isLoading: true } as const;

package/src/sync/testing.ts

@@ -0,0 +1,73 @@
+import type { SyncRequestBody, SyncResponseBody } from "./wire";
+
+/*
+ * `@eifi1/ui-kit/sync/testing` — a scripted `/sync` server for an app's tests of the engine
+ * (docs/local-first-harmonization.md §2.3). Pass `transport.send` as the engine's `send`.
+ * Imports nothing (no Dexie): it is the engine's `send`, not a store.
+ */
+
+/** 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 error an axios client throws: `isAxiosError`, and `response` only with an answer. */
+function wireError(fail: "offline" | number, data?: unknown): Error {
+  const err = new Error(fail === "offline" ? "Network Error" : `Request failed with status code ${fail}`);
+  return Object.assign(err, {
+    isAxiosError: true,
+    response: fail === "offline" ? undefined : { status: fail, data: data ?? {} },
+  });
+}
+
+/**
+ * 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 function createFakeSyncTransport(): FakeSyncTransport {
+  const script: FakeSyncAnswer[] = [];
+  let nextPk = 100;
+  const transport: FakeSyncTransport = {
+    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 : undefined);
+      }
+      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;
+}

package/src/sync/wire.ts

@@ -0,0 +1,61 @@
+/*
+ * The `/sync` wire as the engine speaks it: server-kit's `eifi1_server_kit.sync` shapes
+ * (SyncRequest, SyncResponse, SyncRefusal, SyncRejection, SyncPageCursor; keksdose's, which
+ * are canon, D10), plus kastlan's `pk` on a pulled change. Types only.
+ */
+
+/** 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/src/sync.ts

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

package/src/tour/tour-labels.ts

@@ -10,5 +10,6 @@ export const DEFAULT_TOUR_LABELS: TourLabels = {
   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}`,
 };

package/src/tour/tour.tsx

@@ -48,6 +48,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>;
@@ -60,6 +88,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;
 }
@@ -479,6 +509,48 @@ function TourOverlay({
     return () => el.removeEventListener("click", onClick);
   }, [ready, spotted, index, step, onNext]);
 
+  // An interactive step (see `TourStep.interactive`): only while the target is lit — a
+  // step whose target is missing centres its card over a full scrim, modal as ever.
+  const interactive = spotted && !!step.target && !!(step.interactive || step.awaitInput);
+
+  // awaitInput: advance once the target's fields hold another value than when the step
+  // was armed, checked when focus leaves the target or Enter is pressed in it — on the
+  // next macrotask, after the field's own blur/Enter commit has rendered. A value the
+  // number pad typed fires no native `change`, so comparing is what catches it.
+  useEffect(() => {
+    if (!ready || !spotted || !step.awaitInput || !step.target) return;
+    const el = queryVisibleTarget(step.target) as HTMLElement | null;
+    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: FocusEvent) => {
+      if (e.relatedTarget instanceof Node && el.contains(e.relatedTarget)) return;
+      check();
+    };
+    const onKeyDown = (e: KeyboardEvent) => {
+      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]);
+
   // Keyboard: Esc skips, Enter and the reading-direction arrow advance (→ in LTR,
   // ← in RTL), the other arrow goes back. On awaitClick steps Enter is ignored (it
   // would fire the target's click AND advance) — the forward arrow stays as an escape
@@ -490,12 +562,18 @@ function TourOverlay({
   // The same goes for arrows in a text field a step's `action` might contain.
   useEffect(() => {
     const onKey = (e: KeyboardEvent) => {
+      // On an interactive step a key pressed in the target, or in a layer it opened (the
+      // number pad's Escape, a menu's arrows), is the page's. The card's and the bare
+      // page's (focus on <body>) stay the tour's.
+      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;
@@ -512,7 +590,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;
 
@@ -532,9 +610,12 @@ function TourOverlay({
   return createPortal(
     <div
       ref={rootRef}
-      className="pointer-events-none fixed inset-0 z-[60]"
+      // z-[45] on an interactive step: over the top bar (z-40), under the z-50 layers the
+      // target opens. See `TourStep.interactive`.
+      className={cn("pointer-events-none fixed inset-0", interactive ? "z-[45]" : "z-[60]")}
       role="dialog"
-      aria-modal="true"
+      aria-modal={interactive ? undefined : "true"}
+      data-tour-interactive={interactive ? "" : undefined}
       aria-label={step.title}
       dir={dir}
     >
@@ -590,6 +671,18 @@ function TourOverlay({
   );
 }
 
+/** The values of the fields at or inside `el`, as one string to compare (`awaitInput`). */
+function fieldValues(el: Element): string {
+  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 as HTMLInputElement).value,
+    )
+    .join("\u0000");
+}
+
 /** Does the focused element handle `key` itself? Enter on a button or link, and any
  *  editing key in a text field or select, is the control's — not the tour's. */
 function ownsKey(target: EventTarget | null, key: string): boolean {
@@ -792,16 +885,16 @@ function TourCard({
                 way forward on any step whose anchor happens not to be rendered
                 for this user (a guest sees no "add account" button), leaving the
                 undocumented ArrowRight key as the sole escape. */}
-            {!(step.awaitClick && step.target && rect) && (
+            {!((step.awaitClick || step.awaitInput) && step.target && rect) && (
               <Button variant="brand" onClick={onNext} className={cn("px-2.5 py-1 text-xs")}>
                 {isLast ? labels.done : labels.next}
               </Button>
             )}
           </div>
         </div>
-        {step.awaitClick && step.target && rect && (
+        {(step.awaitClick || step.awaitInput) && step.target && rect && (
           <div className="text-center text-xs italic text-placeholder">
-            {labels.awaitClickHint}
+            {step.awaitInput && !step.awaitClick ? labels.awaitInputHint : labels.awaitClickHint}
           </div>
         )}
       </div>