altitude-design 0.2.1 → 0.3.0

package/dist/guidance/references/build/fixtures/patterns/sync.jsx

@@ -0,0 +1,78 @@
+// Sync pattern (project/framework/patterns/sync.md): each change stays pending until the server acknowledges it, and the
+// SyncIndicator counts the queue; offline, changes wait and nothing claims to be saved; a conflict shows both versions,
+// theirs in their presence colour with their name, and asks keep mine, keep theirs or keep both; an expiring session
+// asks in a stationary dialog and keeps the draft.
+// The lines between the preview markers are its "SyncPattern" preview (scripts/pattern-previews.mjs copies them);
+// build/checks/pattern-types.mjs type-checks this file against the public declarations and fails if the two differ.
+import * as React from 'react';
+import * as A from 'altitude-design';
+// preview:start
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+function App() {
+  const [online, setOnline] = React.useState(true);
+  const live = React.useRef(true); live.current = online;
+  const [tasks, setTasks] = React.useState([
+    { id: 't1', title: 'Draft the launch email', done: true }, { id: 't2', title: 'Book the venue', done: false }, { id: 't3', title: 'Send the press kit', done: false },
+  ]);
+  const [writes, setWrites] = React.useState(/** @type {Record<string, 'pending' | 'committed' | 'failed'>} */ ({}));
+  const [syncedAt, setSyncedAt] = React.useState(new Date());
+  const [conflict, setConflict] = React.useState(/** @type {{ mine: string, theirs: string } | null} */ (null));
+  const [brief, setBrief] = React.useState('Launch on 4 December, in Lisbon.');
+  const [message, setMessage] = React.useState('');
+  const [expiring, setExpiring] = React.useState(false);
+  const [left, setLeft] = React.useState(120);
+  React.useEffect(() => { if (!expiring) return; const t = setInterval(() => setLeft((s) => Math.max(0, s - 1)), 1000); return () => clearInterval(t); }, [expiring]);
+  const queue = Object.keys(writes).filter((k) => writes[k] === 'pending');
+  const send = async (ids) => {
+    await wait(700);
+    if (!live.current) return;
+    setWrites((w) => { const n = { ...w }; ids.forEach((id) => { n[id] = 'committed'; }); return n; });
+    setSyncedAt(new Date());
+  };
+  const toggle = (id, done) => { setTasks((l) => l.map((t) => (t.id === id ? { ...t, done } : t))); setWrites((w) => ({ ...w, [id]: 'pending' })); void send([id]); };
+  const goOnline = (v) => { setOnline(v); live.current = v; if (v && queue.length) void send(queue); };
+  const resolve = (choice) => {
+    if (!conflict) return;
+    setBrief(choice === 'mine' ? conflict.mine : choice === 'theirs' ? conflict.theirs : `${conflict.mine}\n${conflict.theirs}`);
+    setMessage(choice === 'mine' ? 'Kept your version. Jane Park’s version is in the history.' : choice === 'theirs' ? 'Kept Jane Park’s version. Yours is in the history.' : 'Kept both versions, one after the other.');
+    setConflict(null); setSyncedAt(new Date());
+    requestAnimationFrame(() => document.getElementById('sy-brief-h')?.focus());
+  };
+  const minutes = Math.ceil(left / 60);
+  return (
+    <main className="sy-page">
+      <header className="sy-head"><h2 className="sy-h">Launch plan</h2>
+        <A.SyncIndicator state={conflict ? 'conflict' : !online ? 'offline' : queue.length ? 'saving' : 'saved'} pending={queue.length} conflicts={conflict ? 1 : 0} lastSyncedAt={syncedAt}
+          onOpenConflicts={() => document.getElementById('sy-conflict-h')?.focus()} />
+      </header>
+      <div className="sy-demo">
+        <A.Switch label="Online" checked={online} onCheckedChange={goOnline} />
+        <A.Button size="sm" disabled={!!conflict} onClick={() => setConflict({ mine: 'Launch on 4 December, in Lisbon.', theirs: 'Launch on 11 December, in Porto.' })}>Simulate a conflict</A.Button>
+        <A.Button size="sm" onClick={() => { setLeft(120); setExpiring(true); }}>Simulate session expiry</A.Button>
+      </div>
+      <section aria-labelledby="sy-tasks-h" className="sy-section"><h3 id="sy-tasks-h" className="sy-sub">Tasks</h3>
+        <ul className="sy-tasks">{tasks.map((t) => <li key={t.id}><A.Surface level={0} status={writes[t.id]} className="sy-task">
+          <A.Checkbox label={t.title} checked={t.done} onCheckedChange={(v) => toggle(t.id, v)} />
+          <span className="sy-state">{writes[t.id] === 'pending' ? (online ? 'Saving…' : 'Waiting to sync') : ''}</span>
+        </A.Surface></li>)}</ul>
+      </section>
+      <section aria-labelledby="sy-brief-h" className="sy-section"><h3 id="sy-brief-h" tabIndex={-1} className="sy-sub">Brief</h3>
+        {conflict ? <A.Surface level={1} className="sy-conflict" role="group" aria-labelledby="sy-conflict-h">
+          <h4 id="sy-conflict-h" tabIndex={-1} className="sy-ch">Changed by Jane Park while you were editing</h4>
+          <div className="sy-versions">
+            <div className="sy-version"><div className="sy-who">Your version</div><p>{conflict.mine}</p></div>
+            <div className="sy-version" data-presence="2"><div className="sy-who"><A.Avatar name="Jane Park" size={20} /> Jane Park’s version</div><p>{conflict.theirs}</p></div>
+          </div>
+          <div className="sy-actions"><A.Button onClick={() => resolve('mine')}>Keep mine</A.Button><A.Button onClick={() => resolve('theirs')}>Keep theirs</A.Button><A.Button onClick={() => resolve('both')}>Keep both</A.Button></div>
+        </A.Surface> : <p className="sy-brief">{brief}</p>}
+      </section>
+      <p className="sy-note" role="status">{message}</p>
+      <A.Dialog open={expiring} background="stationary" dismissible={false} size="sm" onOpenChange={setExpiring}
+        title={left > 0 ? `Your session ends in ${minutes} ${minutes === 1 ? 'minute' : 'minutes'}` : 'Your session ended'}
+        description={left > 0 ? 'Stay signed in to keep working. Your unsaved changes are kept on this device either way.' : 'Sign in again to continue. Your unsaved changes are kept on this device.'}
+        footer={<><A.Button onClick={() => setExpiring(false)}>Sign out</A.Button><A.Button variant="primary" onClick={() => setExpiring(false)}>{left > 0 ? 'Stay signed in' : 'Sign in again'}</A.Button></>} />
+    </main>
+  );
+}
+// preview:end
+export default App;

package/dist/guidance/references/project/components/src/pattern-async-collection.tsx

@@ -0,0 +1,57 @@
+import * as React from 'react';
+import { useIsoLayoutEffect } from './core';
+export type CollectionPhase = 'loading' | 'refreshing' | 'populated' | 'empty' | 'no-results' | 'failed';
+export interface AsyncCollectionOptions<T, Q> {
+  initialQuery: Q;
+  /** Own query semantics, permissions, pagination and URL/history in the application. Abort is advisory. */
+  load: (query: Q, context: { signal: AbortSignal }) => readonly T[] | Promise<readonly T[]>;
+  getKey: (item: T) => string;
+  isFiltered: (query: Q) => boolean;
+  /** preserve deliberately retains keys absent from the current page/filter; reconcile deleted identities in the app. */
+  selection: 'clear-on-query' | 'preserve';
+  messages?: Partial<{ loading: string; refreshing: string; empty: string; noResults: string; failed: string; results: (count: number) => string }>;
+}
+/** Stale-response-safe collection, with explicit selection policy. See altitude-design/guidance/patterns/async-collection.md. */
+export function useAsyncCollection<T, Q>(options: AsyncCollectionOptions<T, Q>) {
+  const [state, setState] = React.useState(() => ({ query: options.initialQuery, items: [] as readonly T[], phase: 'loading' as CollectionPhase,
+    error: '', status: '', selectedKeys: new Set<string>() as ReadonlySet<string> }));
+  const current = React.useRef(state);
+  const config = React.useRef(options); config.current = options;
+  const mounted = React.useRef(false), loaded = React.useRef(false), generation = React.useRef(0);
+  const active = React.useRef<AbortController | null>(null);
+  const publish = (patch: Partial<typeof state>) => { current.current = { ...current.current, ...patch }; if (mounted.current) setState(current.current); };
+  const fetchItems = async (query: Q) => {
+    const run = ++generation.current;
+    active.current?.abort(); const controller = new AbortController(); active.current = controller;
+    const opts = config.current;
+    const messages = { loading: 'Loading results', refreshing: 'Refreshing results', empty: 'No records yet', noResults: 'No matching results',
+      failed: 'We couldn’t load the results. Try again.', results: (count: number) => `${count} ${count === 1 ? 'result' : 'results'}`, ...opts.messages };
+    publish({ phase: loaded.current ? 'refreshing' : 'loading', error: '', status: loaded.current ? messages.refreshing : messages.loading });
+    try {
+      const items = await opts.load(query, { signal: controller.signal });
+      if (!mounted.current || run !== generation.current) return;
+      if (!Array.isArray(items)) throw Error('Expected items');
+      const keys = items.map(opts.getKey);
+      if (keys.some(key => typeof key !== 'string' || !key) || new Set(keys).size !== keys.length) throw Error('Expected unique stable keys');
+      loaded.current = true;
+      const phase = items.length ? 'populated' : opts.isFiltered(query) ? 'no-results' : 'empty';
+      publish({ items, phase, status: phase === 'populated' ? messages.results(items.length) : phase === 'no-results' ? messages.noResults : messages.empty });
+    } catch {
+      if (mounted.current && run === generation.current) publish({ phase: 'failed', error: messages.failed, status: messages.failed });
+    }
+  };
+  useIsoLayoutEffect(() => { mounted.current = true; void fetchItems(current.current.query);
+    return () => { mounted.current = false; generation.current++; active.current?.abort(); }; }, []);
+  const setQuery = (query: Q) => {
+    publish({ query, ...(config.current.selection === 'clear-on-query' ? { selectedKeys: new Set<string>() } : {}) });
+    void fetchItems(query);
+  };
+  const clearSelection = () => publish({ selectedKeys: new Set<string>() });
+  return { ...state, setQuery, refresh: () => { void fetchItems(current.current.query); }, reset: () => setQuery(config.current.initialQuery), clearSelection,
+    toggleSelection: (key: string) => {
+      const selected = new Set(current.current.selectedKeys);
+      if (selected.has(key)) selected.delete(key);
+      else if (current.current.items.some(item => config.current.getKey(item) === key)) selected.add(key);
+      publish({ selectedKeys: selected });
+    } };
+}

package/dist/guidance/references/project/components/src/pattern-consequential-action.tsx

@@ -0,0 +1,77 @@
+import * as React from 'react';
+import { useIsoLayoutEffect } from './core';
+export type ActionResult<T> = { ok: true; value: T } | { ok: false; error: string };
+export type UndoResult = { ok: true } | { ok: false; error: string };
+export type ConsequentialPhase = 'idle' | 'confirming' | 'pending' | 'failed' | 'succeeded' | 'undoing' | 'undone';
+interface ActionBase<T> {
+  /** Render target and consequence alongside the trigger and in any confirmation. */
+  target: string;
+  consequence: string;
+  execute: () => ActionResult<T> | Promise<ActionResult<T>>;
+  /** Connected, visible next logical destination when the original trigger disappears. */
+  focusFallback?: () => HTMLElement | null;
+  messages?: Partial<{ pending: string; succeeded: string; failed: string; undoing: string; undone: string }>;
+}
+export type ConsequentialActionOptions<T> = ActionBase<T> & (
+  { requiresConfirmation: true; undo?: (result: T) => UndoResult | Promise<UndoResult> } |
+  { requiresConfirmation: false; undo: (result: T) => UndoResult | Promise<UndoResult> }
+);
+const focusable = (element: HTMLElement | null | undefined): element is HTMLElement => !!element?.isConnected &&
+  !element.closest('[inert]') && !element.matches(':disabled,[aria-disabled="true"]') && element.getClientRects().length > 0 &&
+  getComputedStyle(element).visibility !== 'hidden';
+/** Confirmation records intent; only execute success records completion. Undo is offered only with an application-supplied inverse.
+ * Compose Dialog/Alert/Button with the returned content and states. See altitude-design/guidance/patterns/consequential-action.md. */
+export function useConsequentialAction<T>(options: ConsequentialActionOptions<T>) {
+  const [state, setState] = React.useState({ phase: 'idle' as ConsequentialPhase, error: '', status: '', result: undefined as T | undefined });
+  const current = React.useRef(state), mounted = React.useRef(false), trigger = React.useRef<HTMLElement | null>(null);
+  const active = React.useRef(options);
+  const returnFocus = React.useRef(false);
+  const failedOperation = React.useRef<'execute' | 'undo'>('execute');
+  const messages = { pending: 'Completing action', succeeded: 'Action completed', failed: 'We couldn’t complete the action. Try again.',
+    undoing: 'Undoing action', undone: 'Action undone', ...options.messages };
+  useIsoLayoutEffect(() => { mounted.current = true; return () => { mounted.current = false; }; }, []);
+  const publish = (patch: Partial<typeof state>) => { current.current = { ...current.current, ...patch }; if (mounted.current) setState(current.current); };
+  const restoreFocus = () => {
+    // Don't steal focus when the person deliberately moved elsewhere during a pending operation.
+    const focused = document.activeElement;
+    if (focused && focused !== document.body && focused !== trigger.current && !focused.closest('[role="dialog"],[role="alertdialog"]')) return;
+    const target = focusable(trigger.current) ? trigger.current : active.current.focusFallback?.();
+    if (focusable(target)) target.focus();
+  };
+  const execute = async () => {
+    if (!mounted.current || !['idle', 'confirming', 'failed', 'undone'].includes(current.current.phase)) return;
+    failedOperation.current = 'execute'; publish({ phase: 'pending', error: '', status: messages.pending });
+    let result: ActionResult<T>;
+    try { result = await active.current.execute(); } catch { result = { ok: false, error: messages.failed }; }
+    if (!mounted.current) return;
+    if (!result || typeof result !== 'object' || (result.ok === true ? !('value' in result) : result.ok !== false || !result.error || typeof result.error !== 'string')) result = { ok: false, error: messages.failed };
+    if (!result.ok) publish({ phase: 'failed', error: result.error, status: result.error });
+    else { returnFocus.current = true; publish({ phase: 'succeeded', result: result.value, status: messages.succeeded }); }
+  };
+  const undo = async () => {
+    if (!active.current.undo || !mounted.current || !(current.current.phase === 'succeeded' || (current.current.phase === 'failed' && failedOperation.current === 'undo'))) return;
+    failedOperation.current = 'undo'; publish({ phase: 'undoing', error: '', status: messages.undoing });
+    let result: UndoResult;
+    try { result = await active.current.undo!(current.current.result as T); } catch { result = { ok: false, error: messages.failed }; }
+    if (!mounted.current) return;
+    if (!result || typeof result !== 'object' || (result.ok !== true && (result.ok !== false || typeof result.error !== 'string' || !result.error))) result = { ok: false, error: messages.failed };
+    if (!result.ok) publish({ phase: 'failed', error: result.error, status: result.error });
+    else { returnFocus.current = true; publish({ phase: 'undone', status: messages.undone }); }
+  };
+  useIsoLayoutEffect(() => { if (returnFocus.current) { returnFocus.current = false; restoreFocus(); } }, [state.phase]);
+  const content = state.phase === 'idle' || state.phase === 'undone' ? options : active.current;
+  return { ...state, target: content.target, consequence: content.consequence,
+    canUndo: !!active.current.undo && (state.phase === 'succeeded' || (state.phase === 'failed' && failedOperation.current === 'undo')),
+    request: () => {
+      if (!['idle', 'undone'].includes(current.current.phase)) return;
+      active.current = options;
+      trigger.current = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+      if (options.requiresConfirmation) publish({ phase: 'confirming', error: '', status: '' }); else void execute();
+    },
+    confirm: () => { if (current.current.phase === 'confirming') void execute(); },
+    cancel: () => { if (current.current.phase === 'confirming' || (current.current.phase === 'failed' && failedOperation.current === 'execute')) {
+      returnFocus.current = true; publish({ phase: 'idle', error: '', status: '' });
+    } },
+    retry: () => { if (current.current.phase === 'failed') return failedOperation.current === 'undo' ? undo() : execute(); },
+    undo: active.current.undo ? undo : undefined };
+}

package/dist/guidance/references/project/components/src/pattern-edit-record.tsx

@@ -0,0 +1,127 @@
+import * as React from 'react';
+import { useIsoLayoutEffect } from './core';
+
+export type FieldErrors<T> = Partial<Record<keyof T, string>>;
+export type EditRecordResult<T> = { ok: true; value: T } | { ok: false; error: string; errors?: FieldErrors<T> };
+export type EditRecordPhase = 'editing' | 'invalid' | 'submitting' | 'saved' | 'failed';
+export type LeaveReason = 'cancel' | 'back' | 'navigation';
+export interface EditRecordOptions<T extends object> {
+  /** Initial snapshot only. Use reset to deliberately adopt another record; keep snapshots immutable. */
+  initialValue: T;
+  validate: (draft: T) => FieldErrors<T>;
+  /** Submit validates every field; blur additionally validates the blurred field. Corrections revalidate visible errors. */
+  validationMode: 'submit' | 'blur';
+  save: (draft: T, context: { previousValue: T }) => EditRecordResult<T> | Promise<EditRecordResult<T>>;
+  /** Supply semantic equality for nested values. The default compares top-level fields with Object.is. */
+  isEqual?: (a: T, b: T) => boolean;
+  messages?: Partial<{ saving: string; saved: string; failed: string; invalid: string; newerEdits: string }>;
+}
+const shallowEqual = <T extends object>(a: T, b: T) => Object.keys(a).length === Object.keys(b).length &&
+  Object.keys(a).every(key => Object.is(a[key as keyof T], b[key as keyof T]));
+const cleanErrors = <T,>(errors: FieldErrors<T>): FieldErrors<T> => Object.fromEntries(
+  Object.entries(errors).filter(([, value]) => typeof value === 'string' && value.length > 0)) as FieldErrors<T>;
+
+/** Small record workflow. Persistence, concurrency/version checks, authorization and route interception belong to the app.
+ * See altitude-design/guidance/patterns/edit-record.md. A response never replaces edits made after dispatch.
+ */
+export function useEditRecord<T extends object>(options: EditRecordOptions<T>) {
+  const [state, setState] = React.useState(() => ({ draft: options.initialValue, baseline: options.initialValue,
+    errors: {} as FieldErrors<T>, error: '', phase: 'editing' as EditRecordPhase, status: '', submitCount: 0 }));
+  const current = React.useRef(state);
+  const revision = React.useRef(0);
+  const mounted = React.useRef(false);
+  const leaving = React.useRef(false);
+  const messages = { saving: 'Saving changes', saved: 'Changes saved', failed: 'We couldn’t save your changes. Try again.',
+    invalid: 'Check the highlighted fields.', newerEdits: 'The earlier changes were saved. Your newer edits still need saving.', ...options.messages };
+  useIsoLayoutEffect(() => { mounted.current = true; return () => { mounted.current = false; }; }, []);
+  const publish = (patch: Partial<typeof state>) => { current.current = { ...current.current, ...patch }; if (mounted.current) setState(current.current); };
+  const equal = options.isEqual || shallowEqual;
+  const validate = (draft: T) => cleanErrors(options.validate(draft));
+  const setDraft = (draft: T) => {
+    revision.current++;
+    const previous = current.current;
+    const visible = Object.keys(previous.errors) as (keyof T)[];
+    const checked = visible.length ? validate(draft) : {} as FieldErrors<T>;
+    const errors = Object.fromEntries(visible.filter(key => checked[key]).map(key => [key, checked[key]])) as FieldErrors<T>;
+    publish({ draft, errors, error: '', status: previous.phase === 'submitting' ? previous.status : '',
+      phase: previous.phase === 'submitting' ? 'submitting' : Object.keys(errors).length ? 'invalid' : 'editing' });
+  };
+  const validateField = (key: keyof T) => {
+    if (options.validationMode !== 'blur' || current.current.phase === 'submitting') return;
+    const checked = validate(current.current.draft);
+    const errors = { ...current.current.errors }; delete errors[key]; if (checked[key]) errors[key] = checked[key];
+    publish({ errors, phase: Object.keys(errors).length ? 'invalid' : 'editing' });
+  };
+  const validateAll = () => {
+    if (current.current.phase === 'submitting') return false;
+    const errors = validate(current.current.draft);
+    publish({ errors, phase: Object.keys(errors).length ? 'invalid' : 'editing', error: '',
+      status: Object.keys(errors).length ? messages.invalid : '', submitCount: current.current.submitCount + 1 });
+    return Object.keys(errors).length === 0;
+  };
+  const submit = async (): Promise<EditRecordResult<T> | undefined> => {
+    if (!mounted.current || current.current.phase === 'submitting') return;
+    const snapshot = current.current;
+    const errors = validate(snapshot.draft);
+    if (Object.keys(errors).length) { publish({ errors, phase: 'invalid', status: messages.invalid, error: '', submitCount: snapshot.submitCount + 1 }); return; }
+    const dispatchedRevision = revision.current;
+    // Synchronous lock precedes invocation, protecting repeated and reentrant activation.
+    publish({ errors: {}, error: '', phase: 'submitting', status: messages.saving, submitCount: snapshot.submitCount + 1 });
+    let result: EditRecordResult<T>;
+    try { result = await options.save(snapshot.draft, { previousValue: snapshot.baseline }); }
+    catch { result = { ok: false, error: messages.failed }; }
+    if (!mounted.current) return;
+    if (!result || typeof result !== 'object' || (result.ok === true ? !result.value || typeof result.value !== 'object' : result.ok !== false || typeof result.error !== 'string' || !result.error)) result = { ok: false, error: messages.failed };
+    const newer = dispatchedRevision !== revision.current;
+    if (result.ok) publish({ baseline: result.value, ...(newer ? {} : { draft: result.value }),
+      phase: newer ? 'editing' : 'saved', status: newer ? messages.newerEdits : messages.saved });
+    else publish({ phase: 'failed', error: result.error, status: result.error, errors: newer ? current.current.errors : cleanErrors(result.errors || {}) });
+    return result;
+  };
+  const reset = (value: T = current.current.baseline) => {
+    if (current.current.phase === 'submitting') return false;
+    revision.current++; publish({ draft: value, baseline: value, phase: 'editing', errors: {}, error: '', status: '' }); return true;
+  };
+  /** Wire every cancel/Back/router transition through this adapter. It does not intercept history or cancel server writes.
+   * Pending writes block leaving; dirty drafts require an explicit app-owned discard decision. */
+  const requestLeave = async (reason: LeaveReason, confirmDiscard: (context: { reason: LeaveReason; draft: T }) => boolean | Promise<boolean>) => {
+    if (current.current.phase === 'submitting' || leaving.current) return false;
+    if (equal(current.current.draft, current.current.baseline)) return true;
+    const seen = revision.current; leaving.current = true;
+    try {
+      const discard = await confirmDiscard({ reason, draft: current.current.draft });
+      if (!mounted.current || !discard || seen !== revision.current || (current.current.phase as EditRecordPhase) === 'submitting') return false;
+      return reset();
+    } finally { leaving.current = false; }
+  };
+  return { ...state, dirty: !equal(state.draft, state.baseline), setDraft,
+    setField: <K extends keyof T>(key: K, value: T[K]) => setDraft({ ...current.current.draft, [key]: value }),
+    validateField, validateAll, submit, reset, requestLeave };
+}
+
+export interface ErrorSummaryProps {
+  errors: readonly { id: string; label: string; message: string }[];
+  title?: string;
+  /** Change after an unsuccessful submit to focus the summary. Omit to keep focus where it is. */
+  focusKey?: number;
+  className?: string;
+}
+/** Render from the same errors passed to Field; use each input's actual id. Inline Field owns alert announcements. */
+export function ErrorSummary({ errors, title = 'Check these fields', focusKey, className }: ErrorSummaryProps) {
+  const ref = React.useRef<HTMLDivElement>(null);
+  const id = React.useId();
+  const focusedKey = React.useRef<number | undefined>(undefined);
+  useIsoLayoutEffect(() => {
+    if (focusKey && errors.length && focusedKey.current !== focusKey) { focusedKey.current = focusKey; ref.current?.focus(); }
+  }, [focusKey, errors.length]);
+  if (!errors.length) return null;
+  return <div ref={ref} tabIndex={-1} role="region" aria-labelledby={id} className={['alt-error-summary', className].filter(Boolean).join(' ')}>
+    <h2 id={id}>{title}</h2><ul>{errors.map(error => <li key={error.id}><a href={`#${encodeURIComponent(error.id)}`}
+      onClick={event => { const input = document.getElementById(error.id); if (input) { event.preventDefault(); input.focus(); input.scrollIntoView({ block: 'nearest' }); } }}>
+      {error.label}: {error.message}</a></li>)}</ul>
+  </div>;
+}
+/** Place outside any aria-busy region so pending and completion remain announced. */
+export function WorkflowStatus({ children, className }: { children?: React.ReactNode; className?: string }) {
+  return <div className={className} role="status" aria-live="polite" aria-atomic="true">{children}</div>;
+}

package/dist/guidance/references/project/components/src/pattern-review-submit.tsx

@@ -0,0 +1,47 @@
+import * as React from 'react';
+import { useIsoLayoutEffect } from './core';
+import { useEditRecord } from './pattern-edit-record';
+import type { FieldErrors } from './pattern-edit-record';
+export type ReviewSubmitResult<T, R> = { ok: true; receipt: R } | { ok: false; error: string; errors?: FieldErrors<T> };
+export interface ReviewSubmitOptions<T extends object, R> {
+  /** Supply any recovered draft here. Durable storage, step dependencies and cross-session resume are application responsibilities. */
+  initialValue: T;
+  validate: (draft: T) => FieldErrors<T>;
+  submit: (draft: T) => ReviewSubmitResult<T, R> | Promise<ReviewSubmitResult<T, R>>;
+  isEqual?: (a: T, b: T) => boolean;
+  messages?: Partial<{ submitting: string; complete: string; failed: string; invalid: string }>;
+}
+/** Review/correct/submit composition with a persistent application-provided receipt. No automatic persistence or fabricated resume.
+ * See altitude-design/guidance/patterns/review-submit.md. Mount a new workflow to start a distinct transaction after completion. */
+export function useReviewSubmit<T extends object, R>(options: ReviewSubmitOptions<T, R>) {
+  const [stage, setStage] = React.useState<'editing' | 'review' | 'submitting' | 'complete'>('editing');
+  const [receipt, setReceipt] = React.useState<R>();
+  const current = React.useRef(stage), mounted = React.useRef(false), accepted = React.useRef<R | undefined>(undefined);
+  useIsoLayoutEffect(() => { mounted.current = true; return () => { mounted.current = false; }; }, []);
+  const messages = { submitting: 'Sending your answers', complete: 'Your answers were received', failed: 'We couldn’t send your answers. Try again.', invalid: 'Check the highlighted fields.', ...options.messages };
+  const form = useEditRecord({ initialValue: options.initialValue, validate: options.validate, validationMode: 'submit', isEqual: options.isEqual,
+    messages: { saving: messages.submitting, saved: messages.complete, failed: messages.failed, invalid: messages.invalid },
+    save: async draft => {
+      const result = await options.submit(draft);
+      if (result?.ok === true && result.receipt !== undefined && result.receipt !== null) { accepted.current = result.receipt; return { ok: true, value: draft }; }
+      if (result?.ok === false) return result;
+      return { ok: false, error: messages.failed };
+    } });
+  const move = (next: typeof stage) => { current.current = next; if (mounted.current) setStage(next); };
+  const editable = () => current.current === 'editing';
+  return { draft: form.draft, errors: form.errors, error: form.error, status: form.status, submitCount: form.submitCount,
+    dirty: form.dirty, phase: stage, receipt,
+    setDraft: (value: T) => { if (editable()) form.setDraft(value); },
+    setField: <K extends keyof T>(key: K, value: T[K]) => { if (editable()) form.setField(key, value); },
+    review: () => { if (editable() && form.validateAll()) move('review'); },
+    correct: () => { if (current.current === 'review') move('editing'); },
+    submit: async () => {
+      if (current.current !== 'review') return;
+      move('submitting');
+      const result = await form.submit();
+      if (!mounted.current) return;
+      if (result?.ok) { setReceipt(accepted.current); move('complete'); }
+      else move('review');
+    },
+    requestLeave: form.requestLeave };
+}

package/dist/guidance/references/project/components/src/settings.tsx

@@ -0,0 +1,79 @@
+import * as React from 'react';
+import { cx, Icons, useDepth } from './core';
+import type { DepthProps } from './core';
+
+/* ───────────────────────── Settings ───────────────────────── */
+
+export interface SettingsSectionProps extends Omit<React.HTMLAttributes<HTMLElement>, 'title'> {
+  /** Every section has a heading; it names the region. */
+  title: React.ReactNode;
+  description?: React.ReactNode;
+  /** 'critical': the danger zone. A critical rim and the same height as every other section. */
+  tone?: 'critical';
+  /** Default 2. */
+  headingLevel?: 2 | 3;
+  /** Why this person can't change these settings ("Only workspace admins can change billing details"). The rows are disabled and say why. */
+  readOnlyReason?: React.ReactNode;
+}
+/**
+ * One section of a settings page: a raised Card (level 1) with a heading and rows. The danger zone is the same card with
+ * a critical rim, never higher or louder: its consequences are said in its rows' words.
+ */
+export function SettingsSection({ title, description, tone, headingLevel = 2, readOnlyReason, className, children, ...rest }: SettingsSectionProps) {
+  const id = React.useId();
+  const H = `h${headingLevel}` as 'h2';
+  return (
+    <section className={cx('alt-card alt-settings-section', className)} data-tone={tone} aria-labelledby={id + '-title'} {...rest}>
+      <header className="alt-settings-head">
+        <H className="alt-settings-title" id={id + '-title'}>{title}</H>
+        {description && <p className="alt-settings-desc">{description}</p>}
+        {readOnlyReason && <p className="alt-settings-readonly" id={id + '-ro'}><Icons.Lock size={14} aria-hidden="true" />{readOnlyReason}</p>}
+      </header>
+      {readOnlyReason
+        ? <fieldset className="alt-settings-rows" disabled aria-describedby={id + '-ro'}>{children}</fieldset>
+        : <div className="alt-settings-rows">{children}</div>}
+    </section>
+  );
+}
+
+export interface SettingsRowProps extends DepthProps {
+  label: React.ReactNode;
+  /** What the setting does, beside its label. */
+  description?: React.ReactNode;
+  /** Replaces the description and marks the control invalid. */
+  error?: React.ReactNode;
+  /**
+   * The words for an apply-now control's write. Defaults: pending "Saving…", committed "Saved", failed "Couldn't save
+   * this change. Try again." Pass the status of the write the control made; the row hovers while it's pending.
+   */
+  statusText?: Partial<Record<'pending' | 'committed' | 'failed', React.ReactNode>>;
+  className?: string;
+  /** Exactly one control: Switch, Select, Input, Button… It's labelled and described by the row. */
+  children: React.ReactElement<any>;
+}
+/**
+ * A setting: label and description on the start side, the control on the end side, stacked when the section is narrow.
+ * A control that applies immediately reports its write through `status` (pending hovers, committed lands, failed drops
+ * into a trench), with the state in words. Fields saved together belong to one draft with a SaveBar instead.
+ */
+export function SettingsRow({ label, description, error, status, settle, heldBy, relevance, statusText, className, children }: SettingsRowProps) {
+  const id = React.useId();
+  const controlId = children.props.id || id + '-control';
+  const { style, ...depth } = useDepth({ settle, status, heldBy, relevance });
+  const words = status && ({ pending: 'Saving…', committed: 'Saved', failed: 'Couldn’t save this change. Try again.', ...statusText })[status];
+  const describedBy = [children.props['aria-describedby'], (error || description) && id + '-desc', words && id + '-status'].filter(Boolean).join(' ') || undefined;
+  return (
+    <div className={cx('alt-settings-row', className)} {...depth} style={style}>
+      <div className="alt-settings-text">
+        <label className="alt-settings-label" htmlFor={controlId}>{label}</label>
+        {error
+          ? <p className="alt-settings-error" id={id + '-desc'} role="alert"><Icons.AlertCircle size={14} />{error}</p>
+          : description && <p className="alt-settings-rowdesc" id={id + '-desc'}>{description}</p>}
+      </div>
+      <div className="alt-settings-control">
+        {React.cloneElement(children, { id: controlId, 'aria-describedby': describedBy, ...(error ? { invalid: true } : null) })}
+        <span className="alt-settings-status" id={id + '-status'} role="status">{words}</span>
+      </div>
+    </div>
+  );
+}

package/dist/guidance/references/scripts/build-framework-fixture.mjs

@@ -0,0 +1,20 @@
+// Runnable reference fixture using one installed Altitude/React graph.
+// Consumer prerequisite: npm install --save-dev esbuild
+// node PATH/TO/THIS/SCRIPT --out PATH
+import { build } from 'esbuild';
+import { createRequire } from 'node:module';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+const args=process.argv.slice(2),output=args[args.indexOf('--out')+1];
+if(!args.includes('--out')||!output||output.startsWith('--'))throw Error('Supply --out PATH for the generated preview files.');
+const out=resolve(output),require=createRequire(resolve(process.cwd(),'package.json'));
+const pkg=dirname(require.resolve('altitude-design/package.json'));
+const fixture=resolve(dirname(fileURLToPath(import.meta.url)),'../build/fixtures/pattern-workflows.tsx');
+mkdirSync(out,{recursive:true});
+await build({stdin:{contents:`import * as React from 'react'; import {createRoot} from 'react-dom/client'; import {AltitudeProvider} from 'altitude-design'; import {PatternWorkflows} from ${JSON.stringify(fixture)}; createRoot(document.getElementById('root')).render(<AltitudeProvider><PatternWorkflows/></AltitudeProvider>);`,loader:'tsx',resolveDir:process.cwd()},
+  alias:{react:dirname(require.resolve('react/package.json')),'react-dom':dirname(require.resolve('react-dom/package.json')),'altitude-design':resolve(pkg,'dist/index.js')},
+  bundle:true,format:'iife',outfile:resolve(out,'bundle.js'),define:{'process.env.NODE_ENV':'"development"'}});
+writeFileSync(resolve(out,'altitude.css'),readFileSync(resolve(pkg,'dist/altitude.no-fonts.css')));
+writeFileSync(resolve(out,'index.html'),'<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Altitude workflow examples</title><link rel="stylesheet" href="altitude.css"><style>main{max-width:48rem;margin:auto;padding:1rem}section{margin-block:2rem;display:grid;gap:1rem}form{display:grid;gap:1rem}h1,h2,p,li{overflow-wrap:anywhere}button{margin-inline-end:.5rem}</style><body><div id="root"></div><script src="bundle.js"></script></body></html>');
+console.log(`Open ${resolve(out,'index.html')}. This demo uses in-memory data; reload resets it.`);