@ghxstship/xos-ui 0.0.0-stage → 4.16.0

package/src/lib/undo-stack.ts

@@ -0,0 +1,125 @@
+/**
+ * The session's undo stack (Section 11.7, ADR 0044, ADR 0082): the last 50 reversible actions in
+ * this tab, in order. Cmd or Ctrl+Z undoes the latest and Shift+Cmd or Ctrl+Z redoes it (each shell
+ * answers the registry's `undo` and `redo` shortcuts); inside a text field the keys stay the field's
+ * own. Atlas and Gateway share this module (`@xos/ui/undo`); each app's bundle holds its own stack.
+ *
+ * Every entry undoes through the server: a bulk change sends its inverse rows back through the
+ * same RPC, a trashed record is restored. The server refuses an undo that would overwrite a later
+ * change by someone else, and the entry then stays where it was, so nothing is lost silently. Toasts
+ * show one entry; their Undo button and Cmd or Ctrl+Z act on the same stack.
+ */
+
+export type UndoResult = { readonly ok: true } | { readonly ok: false; readonly message: string };
+
+export interface UndoAction {
+  /** What the action did, in a sentence: "Changed 3 records." */
+  readonly label: string;
+  readonly undo: () => Promise<UndoResult>;
+  /** Redoes the action; without it, an undone action leaves the stack. */
+  readonly redo?: () => Promise<UndoResult>;
+  /** False when the caller shows its own Undo toast; the shell shows one otherwise. */
+  readonly toast?: boolean;
+  /** The toast button's label when undoing is not a plain undo, such as "Move back" (B4); Undo by default. */
+  readonly actionLabel?: string;
+}
+
+export interface UndoEntry extends UndoAction {
+  readonly id: number;
+}
+
+export type UndoEvent =
+  | { readonly kind: "pushed"; readonly entry: UndoEntry }
+  | { readonly kind: "undone" | "redone"; readonly entry: UndoEntry }
+  | { readonly kind: "failed"; readonly entry: UndoEntry; readonly message: string }
+  | { readonly kind: "empty"; readonly direction: "undo" | "redo" };
+
+export const UNDO_LIMIT = 50;
+
+export interface UndoStack {
+  push(action: UndoAction): UndoEntry;
+  /** Undoes the latest action, or the given one (a toast's Undo button). */
+  undo(id?: number): Promise<void>;
+  redo(): Promise<void>;
+  /** Whether an action is still undoable (a toast hides its button once it is not). */
+  has(id: number): boolean;
+  size(): { readonly past: number; readonly future: number };
+  subscribe(listener: (event: UndoEvent) => void): () => void;
+}
+
+export function createUndoStack(limit = UNDO_LIMIT): UndoStack {
+  let past: UndoEntry[] = [];
+  let future: UndoEntry[] = [];
+  let next = 1;
+  let busy = false;
+  const listeners = new Set<(event: UndoEvent) => void>();
+  const emit = (event: UndoEvent) => {
+    for (const listener of listeners) listener(event);
+  };
+
+  return {
+    push(action) {
+      const entry: UndoEntry = { ...action, id: next };
+      next += 1;
+      past = [...past, entry].slice(-limit);
+      future = [];
+      emit({ kind: "pushed", entry });
+      return entry;
+    },
+    async undo(id) {
+      if (busy) return;
+      const entry = id === undefined ? past.at(-1) : past.find((e) => e.id === id);
+      if (!entry) {
+        emit({ kind: "empty", direction: "undo" });
+        return;
+      }
+      busy = true;
+      try {
+        const result = await entry.undo();
+        if (!result.ok) {
+          emit({ kind: "failed", entry, message: result.message });
+          return;
+        }
+        past = past.filter((e) => e !== entry);
+        if (entry.redo) future = [...future, entry].slice(-limit);
+        emit({ kind: "undone", entry });
+      } catch (error) {
+        emit({ kind: "failed", entry, message: error instanceof Error ? error.message : "" });
+      } finally {
+        busy = false;
+      }
+    },
+    async redo() {
+      if (busy) return;
+      const entry = future.at(-1);
+      if (!entry?.redo) {
+        emit({ kind: "empty", direction: "redo" });
+        return;
+      }
+      busy = true;
+      try {
+        const result = await entry.redo();
+        if (!result.ok) {
+          emit({ kind: "failed", entry, message: result.message });
+          return;
+        }
+        future = future.filter((e) => e !== entry);
+        past = [...past, entry].slice(-limit);
+        emit({ kind: "redone", entry });
+      } catch (error) {
+        emit({ kind: "failed", entry, message: error instanceof Error ? error.message : "" });
+      } finally {
+        busy = false;
+      }
+    },
+    has: (id) => past.some((e) => e.id === id),
+    size: () => ({ past: past.length, future: future.length }),
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+  };
+}
+
+/** The tab's stack; it survives client navigation and ends with the tab. */
+export const undoStack: UndoStack = createUndoStack();

package/src/marketing.ts

@@ -0,0 +1,33 @@
+/**
+ * The Marketing layer for public pages (design handoff section 10, decision D20). A server
+ * component imports from here: the components that hold no state use no hooks and no context, so
+ * they render on the server and send no JavaScript, and the five that hold state (MarketingNav,
+ * PersonaSwitcher, PricingTable, CodeSample and MarketingFooter) are client modules of their own
+ * (ADR 0027). The server-rendered ones that print a shared string or format a number take the
+ * page's `locale` and `messages` (`flattenMessages` turns a locale's nested `ui` catalog into that
+ * form); the five client ones read the nearest XOSProvider.
+ *
+ * Styles: import "@xos/ui/marketing.css" after "@xos/ui/styles.css".
+ */
+export type * from "./Marketing/Marketing.types.ts";
+export { marketingCopy, type MarketingCopy } from "./Marketing/marketing-copy.ts";
+export { flattenMessages, type Messages } from "./lib/i18n.ts";
+export { ButtonLink } from "./Marketing/ButtonLink.tsx";
+export { MarketingSection } from "./Marketing/MarketingSection.tsx";
+export { MarketingHero } from "./Marketing/MarketingHero.tsx";
+export { ScreenshotFrame } from "./Marketing/ScreenshotFrame.tsx";
+export { ProofStatStrip } from "./Marketing/ProofStatStrip.tsx";
+export { GateLifecycleRail } from "./Marketing/GateLifecycleRail.tsx";
+export { SurfaceTriptych } from "./Marketing/SurfaceTriptych.tsx";
+export { FeatureGrid } from "./Marketing/FeatureGrid.tsx";
+export { ComparisonTable } from "./Marketing/ComparisonTable.tsx";
+export { PriceDisplay } from "./Marketing/PriceDisplay.tsx";
+export { FAQ } from "./Marketing/FAQ.tsx";
+export { Testimonial } from "./Marketing/Testimonial.tsx";
+export { LogoSlotWall } from "./Marketing/LogoSlotWall.tsx";
+export { AIDisclosureBadge } from "./Marketing/AIDisclosureBadge.tsx";
+export { MarketingNav } from "./Marketing/MarketingNav.tsx";
+export { PersonaSwitcher } from "./Marketing/PersonaSwitcher.tsx";
+export { PricingTable } from "./Marketing/PricingTable.tsx";
+export { CodeSample } from "./Marketing/CodeSample.tsx";
+export { MarketingFooter } from "./Marketing/MarketingFooter.tsx";

package/src/pwa/action-outcome.tsx

@@ -0,0 +1,81 @@
+"use client";
+
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
+
+/**
+ * Runs a callback when a form's server action succeeded, for funnel signals (A146, ADR 0052) and the like, while the
+ * form keeps the server action itself in useActionState, so it still posts without JavaScript (ADR 0001).
+ *
+ * A form that stays on the page sees its result in an effect. A form whose row leaves the page with the result (an
+ * answer that leaves the review queue once reviewed) never commits that result, so it cannot: the revalidated page
+ * drops it in the same commit. Wrap such rows in an ActionOutcomeScope, which stays mounted. A form that left while
+ * its action was pending counts as succeeded when the scope's `token`, the page's account of what those forms change,
+ * changed in the same commit; a refused action leaves the row and the token as they were.
+ */
+
+interface Waiting {
+  readonly succeeded: () => void;
+  left: boolean;
+}
+
+const OutcomeScope = createContext<Map<object, Waiting> | null>(null);
+
+export function ActionOutcomeScope({ token, children }: { token: string; children: ReactNode }) {
+  const [waiting] = useState(() => new Map<object, Waiting>());
+  const last = useRef(token);
+  useEffect(() => {
+    if (last.current === token) return;
+    last.current = token;
+    for (const [form, entry] of waiting) {
+      if (!entry.left) continue;
+      waiting.delete(form);
+      entry.succeeded();
+    }
+  }, [token, waiting]);
+  return <OutcomeScope value={waiting}>{children}</OutcomeScope>;
+}
+
+/**
+ * Calls `onSuccess` once for each result of the form's action that `succeeded` accepts, `state` and `pending` being
+ * what useActionState returned. Inside an ActionOutcomeScope it also covers a form that leaves with its result.
+ */
+export function useActionOutcome<S>(
+  state: S,
+  pending: boolean,
+  succeeded: (state: S) => boolean,
+  onSuccess: (() => void) | undefined,
+): void {
+  const scope = useContext(OutcomeScope);
+  const [form] = useState(() => ({}));
+  const seen = useRef(state);
+  const latest = useRef({ succeeded, onSuccess });
+  useLayoutEffect(() => {
+    latest.current = { succeeded, onSuccess };
+  });
+  useEffect(() => {
+    if (!pending || !scope) return;
+    scope.set(form, { succeeded: () => latest.current.onSuccess?.(), left: false });
+  }, [pending, scope, form]);
+  useEffect(() => {
+    if (state === seen.current) return;
+    seen.current = state;
+    scope?.delete(form);
+    if (latest.current.succeeded(state)) latest.current.onSuccess?.();
+  }, [state, scope, form]);
+  useEffect(() => {
+    const entry = scope?.get(form);
+    if (entry) entry.left = false;
+    return () => {
+      const waiting = scope?.get(form);
+      if (waiting) waiting.left = true;
+    };
+  }, [scope, form]);
+}

package/src/pwa/analytics.ts

@@ -0,0 +1,236 @@
+/**
+ * The browser side of consent-gated product analytics (Section 11.14, A96, ADR 0052). Apps load this module only
+ * when their consent seam said yes, and it stops itself when the browser sends Global Privacy Control. Events carry
+ * a route template (never the path), a workflow and a step, keyed to a random session key kept in sessionStorage,
+ * and go to the app's own /api/product-events in small batches. Nothing goes to another origin.
+ */
+
+export type WorkflowEvent = "Workflow Started" | "Workflow Step" | "Workflow Completed";
+
+interface QueuedEvent {
+  readonly occurredAt: string;
+  readonly name: "Page Viewed" | WorkflowEvent;
+  readonly route?: string;
+  readonly workflow?: string;
+  readonly step?: number;
+}
+
+/** A workflow event a signal records (packages/data product-workflows.ts parseWorkflowSignal). */
+export interface WorkflowSignalEvent {
+  readonly workflow: string;
+  readonly name: WorkflowEvent;
+  readonly step?: number;
+}
+
+/**
+ * Workflow funnel signals (A146): the app's registry, passed in so this module carries none. A signal is
+ * `<workflow>:start`, `<workflow>:step<n>` or `<workflow>:done`, from a page view (`forRoute`), a `data-workflow`
+ * attribute or a window event named `eventName`.
+ */
+export interface WorkflowSignals {
+  readonly eventName: string;
+  readonly parse: (signal: unknown) => WorkflowSignalEvent | null;
+  readonly forRoute: (template: string) => readonly string[];
+}
+
+export interface ProductAnalyticsOptions {
+  readonly endpoint: string;
+  /** Turns a path into its route template, so no slug, key or token leaves the browser. */
+  readonly template: (path: string) => string;
+  /** Sends a batch; defaults to a keepalive POST. */
+  readonly send?: (body: string) => void;
+  readonly now?: () => Date;
+  /** Records workflow funnel events from signals; without it only page views are recorded. */
+  readonly workflows?: WorkflowSignals;
+}
+
+export interface ProductAnalytics {
+  pageViewed(path: string): void;
+  workflow(code: string, event: WorkflowEvent, step?: number): void;
+  flush(): void;
+  /** Sends what is queued and stops listening. */
+  stop(): void;
+}
+
+const SESSION_KEY = "xos-analytics-session";
+const STARTED_KEY = "xos-analytics-started";
+// Elements that signal when activated; any other marked element (but a form) signals when it appears.
+const INTERACTIVE =
+  "a,button,input,select,textarea,summary,[role=button],[role=link],[role=menuitem],[role=option],[role=tab]";
+const BATCH = 10;
+const FLUSH_MS = 5000;
+
+function sessionKey(): string {
+  try {
+    const stored = window.sessionStorage.getItem(SESSION_KEY);
+    if (stored) return stored;
+    const fresh = crypto.randomUUID();
+    window.sessionStorage.setItem(SESSION_KEY, fresh);
+    return fresh;
+  } catch {
+    return crypto.randomUUID();
+  }
+}
+
+/** True when the browser sends Global Privacy Control, which turns analytics off whatever was chosen. */
+export function globalPrivacyControl(): boolean {
+  return (
+    (navigator as Navigator & { globalPrivacyControl?: boolean }).globalPrivacyControl === true
+  );
+}
+
+/** Workflows this browser session started, so a step or completion counts only after its start. */
+function startedWorkflows(): Set<string> {
+  try {
+    const stored = JSON.parse(window.sessionStorage.getItem(STARTED_KEY) ?? "[]") as unknown;
+    return new Set(Array.isArray(stored) ? stored.filter((v) => typeof v === "string") : []);
+  } catch {
+    return new Set();
+  }
+}
+
+function rememberStarted(started: Set<string>): void {
+  try {
+    window.sessionStorage.setItem(STARTED_KEY, JSON.stringify([...started]));
+  } catch {
+    // Storage blocked: the set lasts as long as the page.
+  }
+}
+
+const NOOP: ProductAnalytics = {
+  pageViewed: () => undefined,
+  workflow: () => undefined,
+  flush: () => undefined,
+  stop: () => undefined,
+};
+
+export function productAnalytics(options: ProductAnalyticsOptions): ProductAnalytics {
+  if (globalPrivacyControl()) return NOOP;
+  const key = sessionKey();
+  const now = options.now ?? (() => new Date());
+  const send =
+    options.send ??
+    ((body: string) => {
+      void fetch(options.endpoint, {
+        method: "POST",
+        keepalive: true,
+        credentials: "same-origin",
+        headers: { "Content-Type": "application/json" },
+        body,
+      }).catch(() => undefined);
+    });
+  let queue: QueuedEvent[] = [];
+  let timer: ReturnType<typeof setTimeout> | null = null;
+
+  const flush = () => {
+    if (timer !== null) clearTimeout(timer);
+    timer = null;
+    if (queue.length === 0) return;
+    const events = queue.slice(0, 25);
+    queue = queue.slice(25);
+    send(JSON.stringify({ sessionKey: key, events }));
+  };
+  const add = (event: QueuedEvent) => {
+    queue.push(event);
+    if (queue.length >= BATCH) flush();
+    else timer ??= setTimeout(flush, FLUSH_MS);
+  };
+  const listening = new AbortController();
+  const { signal: until } = listening;
+  window.addEventListener("pagehide", flush, { signal: until });
+  document.addEventListener(
+    "visibilitychange",
+    () => {
+      if (document.visibilityState === "hidden") flush();
+    },
+    { signal: until },
+  );
+  let observer: MutationObserver | null = null;
+
+  const workflows = options.workflows;
+  const started = workflows ? startedWorkflows() : new Set<string>();
+  // A signal the registry names becomes an event. A step or a completion counts only once the session started the
+  // workflow, so a return visit to a finished packet or an empty queue is not a completion.
+  const signal = (value: unknown) => {
+    const event = workflows?.parse(value);
+    if (!event) return;
+    if (event.name === "Workflow Started") {
+      started.add(event.workflow);
+      rememberStarted(started);
+    } else if (!started.has(event.workflow)) return;
+    add({
+      occurredAt: now().toISOString(),
+      name: event.name,
+      workflow: event.workflow,
+      ...(event.step === undefined ? {} : { step: event.step }),
+    });
+  };
+  if (workflows) {
+    const seen = new WeakSet<Element>();
+    const appeared = (root: ParentNode) => {
+      const marked = [
+        ...(root instanceof Element && root.matches("[data-workflow]") ? [root] : []),
+        ...root.querySelectorAll("[data-workflow]"),
+      ];
+      for (const el of marked) {
+        if (seen.has(el) || el.matches(INTERACTIVE) || el instanceof HTMLFormElement) continue;
+        seen.add(el);
+        signal(el.getAttribute("data-workflow"));
+      }
+    };
+    window.addEventListener(workflows.eventName, (e) => signal((e as CustomEvent).detail), {
+      signal: until,
+    });
+    document.addEventListener(
+      "click",
+      (e) => {
+        const el = e.target instanceof Element ? e.target.closest("[data-workflow]") : null;
+        if (el?.matches(INTERACTIVE)) signal(el.getAttribute("data-workflow"));
+      },
+      { capture: true, signal: until },
+    );
+    document.addEventListener(
+      "submit",
+      (e) => {
+        if (e.target instanceof HTMLFormElement) signal(e.target.getAttribute("data-workflow"));
+      },
+      { capture: true, signal: until },
+    );
+    appeared(document);
+    const watcher = new MutationObserver((records) => {
+      for (const r of records) {
+        if (r.type === "attributes" && r.target instanceof Element) appeared(r.target);
+        for (const node of r.addedNodes) if (node instanceof Element) appeared(node);
+      }
+    });
+    watcher.observe(document.documentElement, {
+      childList: true,
+      subtree: true,
+      attributes: true,
+      attributeFilter: ["data-workflow"],
+    });
+    observer = watcher;
+  }
+
+  return {
+    pageViewed(path) {
+      const route = options.template(path);
+      add({ occurredAt: now().toISOString(), name: "Page Viewed", route });
+      for (const s of workflows?.forRoute(route) ?? []) signal(s);
+    },
+    workflow(code, event, step) {
+      add({
+        occurredAt: now().toISOString(),
+        name: event,
+        workflow: code,
+        ...(step === undefined ? {} : { step }),
+      });
+    },
+    flush,
+    stop() {
+      flush();
+      listening.abort();
+      observer?.disconnect();
+    },
+  };
+}

package/src/pwa/browser-push.tsx

@@ -0,0 +1,132 @@
+"use client";
+
+import { useEffect, useState, type ReactElement } from "react";
+import { Button } from "../Button/Button.tsx";
+import { Card } from "../Surface/Surface.tsx";
+import {
+  currentPushSubscription,
+  pushSupported,
+  subscribeToPush,
+  unsubscribeFromPush,
+} from "./client.ts";
+
+/** The app's copy for the browser notifications setting (A96); apps pass their own catalog strings. */
+export interface BrowserPushLabels {
+  readonly title: string;
+  readonly body: string;
+  readonly turnOn: string;
+  readonly turnOff: string;
+  readonly on: string;
+  readonly off: string;
+  readonly blocked: string;
+  readonly unsupported: string;
+  readonly unavailable: string;
+  readonly failed: string;
+}
+
+export interface BrowserPushSettingProps {
+  /** The VAPID public key, base64url; null when the platform has not set one up. */
+  readonly vapidPublicKey: string | null;
+  readonly labels: BrowserPushLabels;
+  /** Saves the subscription (PushSubscription.toJSON()) for the signed-in person; false when it did not. */
+  readonly onRegister: (subscription: PushSubscriptionJSON) => Promise<boolean>;
+  /** Revokes this browser's endpoint for the signed-in person. */
+  readonly onRevoke: (endpoint: string) => Promise<boolean>;
+}
+
+type State = "loading" | "on" | "off" | "blocked" | "unsupported" | "unavailable";
+
+/**
+ * Browser notifications for this browser (Section 4.10, A65-023): turned on only when the person asks, which is
+ * when the browser asks its permission, and off again in one action. Quiet hours and channel choices stay with the
+ * notification settings around it, since browser pushes ride the Push channel.
+ */
+export function BrowserPushSetting({
+  vapidPublicKey,
+  labels,
+  onRegister,
+  onRevoke,
+}: BrowserPushSettingProps): ReactElement {
+  const [state, setState] = useState<State>("loading");
+  const [busy, setBusy] = useState(false);
+  const [failed, setFailed] = useState(false);
+
+  useEffect(() => {
+    let live = true;
+    const settle = (next: State) => {
+      if (live) setState(next);
+    };
+    if (vapidPublicKey === null) settle("unavailable");
+    else if (!pushSupported()) settle("unsupported");
+    else if (Notification.permission === "denied") settle("blocked");
+    else
+      void currentPushSubscription().then(
+        (s) => settle(s ? "on" : "off"),
+        () => settle("off"),
+      );
+    return () => {
+      live = false;
+    };
+  }, [vapidPublicKey]);
+
+  const turnOn = async () => {
+    if (vapidPublicKey === null) return;
+    setBusy(true);
+    setFailed(false);
+    const result = await subscribeToPush(vapidPublicKey);
+    if (!result.ok) {
+      if (result.reason === "blocked") setState("blocked");
+      else if (result.reason === "unsupported") setState("unsupported");
+      else setFailed(true);
+    } else if (await onRegister(result.subscription)) setState("on");
+    else {
+      await unsubscribeFromPush();
+      setFailed(true);
+    }
+    setBusy(false);
+  };
+
+  const turnOff = async () => {
+    setBusy(true);
+    setFailed(false);
+    const endpoint = await unsubscribeFromPush();
+    if (endpoint !== null && !(await onRevoke(endpoint))) setFailed(true);
+    setState("off");
+    setBusy(false);
+  };
+
+  const status =
+    state === "on"
+      ? labels.on
+      : state === "off"
+        ? labels.off
+        : state === "blocked"
+          ? labels.blocked
+          : state === "unsupported"
+            ? labels.unsupported
+            : state === "unavailable"
+              ? labels.unavailable
+              : "";
+  return (
+    <Card title={labels.title}>
+      <p className="m-0 text-text-13 text-text-secondary">{labels.body}</p>
+      <p role="status" className="m-0 text-text-13" data-push-state={state}>
+        {status}
+      </p>
+      {state === "on" ? (
+        <Button onClick={() => void turnOff()} disabled={busy}>
+          {labels.turnOff}
+        </Button>
+      ) : state === "off" ? (
+        <Button variant="primary" icon="Bell" onClick={() => void turnOn()} disabled={busy}>
+          {labels.turnOn}
+        </Button>
+      ) : null}
+      {failed ? (
+        <span role="alert" className="text-text-12 text-danger-text">
+          {labels.failed}
+        </span>
+      ) : null}
+    </Card>
+  );
+}