altitude-design 0.2.0 → 0.3.0

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

@@ -0,0 +1,102 @@
+// Import pattern (project/framework/patterns/import.md): upload a CSV, map its columns, fix the rows that have problems,
+// review, then import as a job with a receipt. A column's Select fills when it's mapped, so what's left shows; invalid
+// cells lie in a trench on critical-soft (DataGrid showInvalid); the problem count is said as it changes; the import
+// can be cancelled and ends with what was imported, skipped and why.
+// The lines between the preview markers are its "ImportPattern" 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));
+const STEPS = [{ title: 'Upload' }, { title: 'Map columns' }, { title: 'Fix problems' }, { title: 'Review' }, { title: 'Import' }];
+const SOURCE = [{ key: 'c0', header: 'Full name', sample: 'Ada Lovelace' }, { key: 'c1', header: 'E-mail', sample: 'ada@example.com' }, { key: 'c2', header: 'Company', sample: 'Analytical Ltd' }, { key: 'c3', header: 'Notes', sample: 'Met at the conference' }];
+const TARGETS = [{ value: 'name', label: 'Name (required)' }, { value: 'email', label: 'Email (required)' }, { value: 'company', label: 'Company' }, { value: 'skip', label: 'Don’t import' }];
+const FILE = [
+  ['Ada Lovelace', 'ada@example.com', 'Analytical Ltd', ''], ['Grace Hopper', 'grace@example', 'Navy Labs', 'Follow up'], ['Alan Turing', 'alan@example.com', 'Bletchley', ''],
+  ['', 'nameless@example.com', 'Unknown', ''], ['Katherine Johnson', 'katherine@example.com', 'NASA', ''], ['Ada Lovelace', 'ada@example.com', 'Analytical Ltd', 'Duplicate'],
+  ['Hedy Lamarr', 'hedy@example.com', 'MGM', ''], ['Edsger Dijkstra', 'edsger@@example.com', 'TU Eindhoven', ''],
+].map((r, i) => ({ id: 'r' + i, line: i + 2, c0: r[0], c1: r[1], c2: r[2], c3: r[3] }));
+const problemsIn = (row, map) => {
+  const col = (t) => Object.keys(map).find((k) => map[k] === t);
+  const out = [];
+  const n = col('name'), e = col('email');
+  if (n && !String(row[n]).trim()) out.push({ key: n, message: 'Enter a name.' });
+  if (e && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(String(row[e]))) out.push({ key: e, message: 'This isn’t an email address.' });
+  return out;
+};
+function App() {
+  const [step, setStep] = React.useState(0);
+  const [queue, setQueue] = React.useState(/** @type {A.UploadItem[]} */ ([]));
+  const [map, setMap] = React.useState(/** @type {Record<string, string>} */ ({}));
+  const [rows, setRows] = React.useState(FILE);
+  const [onlyProblems, setOnlyProblems] = React.useState(false);
+  const [progress, setProgress] = React.useState(0);
+  const [cancelled, setCancelled] = React.useState(false);
+  const stop = React.useRef(false);
+  const heading = React.useRef(/** @type {HTMLHeadingElement | null} */ (null));
+  const go = (n) => { setStep(n); requestAnimationFrame(() => heading.current?.focus()); };
+  const upload = async (name) => {
+    setQueue([{ id: 'f', name, state: 'uploading', progress: 40 }]); await wait(300);
+    setQueue([{ id: 'f', name, state: 'uploading', progress: 100 }]); await wait(300);
+    setQueue([{ id: 'f', name, state: 'done' }]); await wait(300); go(1);
+  };
+  const missing = ['name', 'email'].filter((t) => !Object.values(map).includes(t)).map((t) => (t === 'name' ? 'Name' : 'Email'));
+  const mapped = SOURCE.filter((s) => map[s.key] && map[s.key] !== 'skip');
+  const bad = rows.filter((r) => problemsIn(r, map).length);
+  const problemCount = rows.reduce((n, r) => n + problemsIn(r, map).length, 0);
+  const emailCol = Object.keys(map).find((k) => map[k] === 'email');
+  const seen = new Set(), dupes = new Set();
+  rows.forEach((r) => { if (problemsIn(r, map).length || !emailCol) return; const e = String(r[emailCol]); if (seen.has(e)) dupes.add(r.id); seen.add(e); });
+  const importing = rows.filter((r) => !problemsIn(r, map).length && !dupes.has(r.id));
+  const run = async () => {
+    go(4); stop.current = false; setCancelled(false);
+    for (let i = 1; i <= importing.length; i++) { await wait(350); if (stop.current) { setCancelled(true); return; } setProgress(i); }
+    go(5);
+  };
+  const H = (text) => <h3 ref={heading} tabIndex={-1} className="im-sub">{text}</h3>;
+  return (
+    <main className="im-page">
+      <h2 className="im-h">Import contacts</h2>
+      <A.Stepper steps={STEPS} current={step} aria-label="Import steps" onStepChange={step < 4 ? (i) => go(i) : undefined} />
+      {step === 0 && <section className="im-step">{H('Upload a CSV file')}
+        <A.DropZone accept=".csv,text/csv" multiple={false} onFiles={(f) => f[0] && upload(f[0].name)} queue={queue}>
+          <p className="im-note">Drop a .csv file here or choose one. The first row should name the columns.</p>
+        </A.DropZone>
+        <div><A.Button onClick={() => upload('contacts.csv')}>Use the sample file</A.Button></div>
+      </section>}
+      {step === 1 && <section className="im-step">{H('Map columns to fields')}
+        <p className="im-note">Choose the field each column of contacts.csv goes into.</p>
+        <div className="im-map">{SOURCE.map((s) => <A.Field key={s.key} label={s.header} hint={`For example, “${s.sample}”`}>
+          <A.Select value={map[s.key] || ''} placeholder="Not mapped" onValueChange={(v) => setMap((m) => ({ ...m, [s.key]: v }))} items={TARGETS} />
+        </A.Field>)}</div>
+        <p className="im-note" role="status">{missing.length ? `Map these required fields: ${missing.join(', ')}.` : 'Every required field is mapped.'}</p>
+        <div><A.Button variant="primary" disabled={missing.length > 0} onClick={() => go(2)}>Continue</A.Button></div>
+      </section>}
+      {step === 2 && <section className="im-step">{H('Fix problems')}
+        <p className="im-note" role="status">{problemCount ? `${problemCount} ${problemCount === 1 ? 'problem' : 'problems'} left in ${bad.length} ${bad.length === 1 ? 'row' : 'rows'}. Rows with problems are skipped.` : 'No problems left.'}</p>
+        <A.Switch label="Only rows with problems" checked={onlyProblems} onCheckedChange={setOnlyProblems} />
+        <A.DataGrid aria-label="Rows to import" showInvalid rows={onlyProblems ? bad : rows} getRowId={(r) => r.id} getRowLabel={(r) => `row ${r.line}`}
+          columns={[{ key: 'line', header: 'Row', align: 'end', width: 64 }, ...mapped.map((s) => ({ key: s.key, header: TARGETS.find((t) => t.value === map[s.key])?.label.replace(' (required)', '') || s.header, editable: true,
+            validate: (v, row) => problemsIn({ ...row, [s.key]: v }, map).find((p) => p.key === s.key)?.message }))]}
+          onCellSave={({ rowId, key, draft }) => { setRows((all) => all.map((r) => (r.id === rowId ? { ...r, [key]: draft } : r))); return { ok: true }; }} />
+        <div className="im-actions"><A.Button onClick={() => go(1)}>Back to mapping</A.Button><A.Button variant="primary" onClick={() => go(3)}>Continue</A.Button></div>
+      </section>}
+      {step === 3 && <section className="im-step">{H('Review the import')}
+        <p className="im-lead">{importing.length} contacts will be imported. {dupes.size + bad.length} rows will be skipped: {dupes.size} {dupes.size === 1 ? 'duplicate' : 'duplicates'} and {bad.length} with problems.</p>
+        <div className="im-actions"><A.Button onClick={() => go(2)}>Fix more rows</A.Button><A.Button variant="primary" onClick={run}>Import {importing.length} contacts</A.Button></div>
+      </section>}
+      {step === 4 && <section className="im-step">{H(cancelled ? 'Import cancelled' : 'Importing contacts')}
+        {cancelled ? <><p className="im-lead">{progress} of {importing.length} contacts were imported before you cancelled; the rest weren’t. Importing again skips the ones already imported.</p><div><A.Button onClick={() => { setProgress(0); go(3); }}>Back to review</A.Button></div></> : <>
+          <A.Progress value={progress} max={importing.length} aria-label="Importing contacts" />
+          <p className="im-note" role="status">Importing {progress} of {importing.length}</p>
+          <div><A.Button onClick={() => { stop.current = true; }}>Cancel import</A.Button></div></>}
+      </section>}
+      {step === 5 && <section className="im-step">{H('Import finished')}
+        <dl className="im-receipt"><div><dt>Imported</dt><dd>{importing.length} contacts</dd></div><div><dt>Skipped</dt><dd>{dupes.size} {dupes.size === 1 ? 'duplicate' : 'duplicates'}</dd></div><div><dt>Failed</dt><dd>{bad.length} {bad.length === 1 ? 'row' : 'rows'} with problems</dd></div></dl>
+        <div className="im-actions"><A.Button>Download skipped rows (CSV)</A.Button><A.Button variant="ghost" onClick={() => { setQueue([]); setMap({}); setRows(FILE); setProgress(0); go(0); }}>Import another file</A.Button></div>
+      </section>}
+    </main>
+  );
+}
+// preview:end
+export default App;

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

@@ -0,0 +1,106 @@
+// Members pattern (project/framework/patterns/members.md): invite people by email with a role, see pending invitations,
+// change someone's role, remove someone. An invitation awaiting acceptance is settled (ground, an "Invited" plate);
+// only sending it hovers. Role changes apply now, per row. The only owner can't demote themselves, and the reason is
+// said where the control would be. Removing someone names what they lose.
+// The lines between the preview markers are its "MembersPattern" 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));
+const ROLES = [
+  { value: 'admin', label: 'Admin', description: 'Manages members, billing and every project.' },
+  { value: 'member', label: 'Member', description: 'Creates and edits projects they can see.' },
+  { value: 'viewer', label: 'Viewer', description: 'Sees projects and leaves comments. Can’t edit.' },
+];
+const roleName = (v) => (v === 'owner' ? 'Owner' : ROLES.find((r) => r.value === v)?.label);
+function MemberRow({ person, me, owners, fail, onRole, onRemove, onResend, onRevoke }) {
+  const [write, setWrite] = React.useState(/** @type {A.DepthProps['status']} */ (undefined));
+  const row = React.useRef(null);
+  const remove = A.useConsequentialAction({
+    target: person.name, consequence: `${person.name} loses access to ${person.projects} projects and every shared dashboard. Their work stays in the workspace.`,
+    requiresConfirmation: true, focusFallback: () => document.getElementById('mb-heading'),
+    execute: async () => { await wait(700); onRemove(person); return { ok: true, value: person.id }; },
+    messages: { pending: `Removing ${person.name}`, succeeded: `${person.name} was removed` },
+  });
+  const { style, ...depth } = A.useDepth({ status: write, settle: person.invitedAt ? true : undefined });
+  const changeRole = async (role) => {
+    const before = person.role; onRole(person.id, role); setWrite('pending');
+    await wait(800);
+    if (fail.current) { onRole(person.id, before); setWrite('failed'); } else setWrite('committed');
+  };
+  const onlyOwner = person.role === 'owner' && owners === 1;
+  return (
+    <A.TableRow ref={row} rowId={person.id} {...depth} style={style}>
+      <A.TableCell><div className="mb-who"><A.Avatar name={person.name} size={28} /><div><div className="mb-name">{person.name}{person.id === me && ' (you)'}</div><div className="mb-email">{person.email}</div></div></div></A.TableCell>
+      <A.TableCell>
+        {person.invited ? <span className="mb-invited"><A.Badge>Invited</A.Badge> {roleName(person.role)} · sent {person.sent}</span>
+          : onlyOwner ? <span className="mb-reason">Owner. You’re the only owner, so your role can’t change. Transfer ownership first.</span>
+          : <div className="mb-role"><A.Select aria-label={`Role for ${person.name}`} value={person.role} onValueChange={changeRole} items={ROLES.map(({ value, label }) => ({ value, label }))} />
+              <span className="mb-write" role="status">{write === 'pending' ? 'Changing role…' : write === 'failed' ? 'Couldn’t change the role. Try again.' : write === 'committed' ? 'Role changed' : ''}</span></div>}
+      </A.TableCell>
+      <A.TableCell align="end">
+        {person.invited ? <div className="mb-actions"><A.Button size="sm" variant="ghost" onClick={() => onResend(person)}>Resend</A.Button><A.Button size="sm" variant="ghost" onClick={() => onRevoke(person)}>Revoke</A.Button></div>
+          : onlyOwner || person.id === me ? null
+          : <A.Button size="sm" variant="ghost" onClick={remove.request}>Remove</A.Button>}
+        <A.Dialog open={['confirming', 'pending', 'failed'].includes(remove.phase)} background="stationary" size="sm" dismissible={remove.phase !== 'pending'}
+          onOpenChange={(o) => { if (!o) remove.cancel(); }} title={`Remove ${person.name}?`} description={remove.consequence}
+          footer={<><A.Button disabled={remove.phase === 'pending'} onClick={remove.cancel}>Keep {person.name.split(' ')[0]}</A.Button><A.Button variant="danger" disabled={remove.phase === 'pending'} onClick={remove.confirm}>{remove.phase === 'pending' ? 'Removing' : `Remove ${person.name.split(' ')[0]}`}</A.Button></>} />
+      </A.TableCell>
+    </A.TableRow>
+  );
+}
+function App() {
+  const me = 'u1';
+  const [people, setPeople] = React.useState([
+    { id: 'u1', name: 'Maya Chen', email: 'maya@acme.dev', role: 'owner', projects: 14 },
+    { id: 'u2', name: 'Theo Marsh', email: 'theo@acme.dev', role: 'admin', projects: 9 },
+    { id: 'u3', name: 'Ines Duarte', email: 'ines@acme.dev', role: 'member', projects: 4 },
+    { id: 'i1', name: 'sam@acme.dev', email: 'Invitation', role: 'member', invited: true, sent: 'yesterday', projects: 0 },
+  ]);
+  const [emails, setEmails] = React.useState(/** @type {string[]} */ ([]));
+  const [role, setRole] = React.useState('member');
+  const [sending, setSending] = React.useState(false);
+  const [status, setStatus] = React.useState('');
+  const [failNext, setFailNext] = React.useState(false);
+  const fail = React.useRef(false); fail.current = failNext;
+  const owners = people.filter((p) => p.role === 'owner').length;
+  const send = async () => {
+    setSending(true); setStatus('Sending invites…');
+    await wait(900);
+    const known = new Set(people.map((p) => p.name).concat(people.map((p) => p.email)));
+    const fresh = emails.filter((e) => !known.has(e)), already = emails.length - fresh.length;
+    const at = Date.now();
+    setPeople((list) => list.concat(fresh.map((e, i) => ({ id: 'i' + at + i, name: e, email: 'Invitation', role, invited: true, sent: 'just now', invitedAt: at, projects: 0 }))));
+    setEmails([]); setSending(false);
+    setStatus([fresh.length && `${fresh.length} ${fresh.length === 1 ? 'invite' : 'invites'} sent`, already && `${already} ${already === 1 ? 'address is' : 'addresses are'} already in the workspace`].filter(Boolean).join(', ') + '.');
+  };
+  return (
+    <main className="mb-page">
+      <h2 id="mb-heading" tabIndex={-1} className="mb-h">Members</h2>
+      <A.Card className="mb-invite" aria-labelledby="mb-invite-h">
+        <h3 id="mb-invite-h" className="mb-sub">Invite people</h3>
+        <A.Field label="Email addresses" hint="Separate addresses with commas, or paste a list.">
+          <A.TagInput value={emails} onValueChange={setEmails} noun={['address', 'addresses']} placeholder="name@acme.dev" disabled={sending}
+            normalize={(t) => t.trim().toLowerCase()} validate={(t) => (/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(t) ? undefined : `${t} isn’t an email address.`)} />
+        </A.Field>
+        <div className="mb-roles"><span id="mb-role-label" className="mb-legend">Role</span>
+          <A.RadioGroup value={role} onValueChange={setRole} aria-labelledby="mb-role-label">{ROLES.map((r) => <A.Radio key={r.value} value={r.value} label={r.label} description={r.description} />)}</A.RadioGroup>
+        </div>
+        <div><A.Button variant="primary" loading={sending} disabled={!emails.length} onClick={send}>{sending ? 'Sending invites' : emails.length > 1 ? `Send ${emails.length} invites` : 'Send invite'}</A.Button></div>
+      </A.Card>
+      <A.Switch label="Make the next role change fail" checked={failNext} onCheckedChange={setFailNext} />
+      <A.Table aria-label="Members and invitations">
+        <A.TableHeader><A.TableRow><A.TableHead>Person</A.TableHead><A.TableHead>Role</A.TableHead><A.TableHead align="end"><span className="mb-vh">Actions</span></A.TableHead></A.TableRow></A.TableHeader>
+        <A.TableBody>{people.map((p) => <MemberRow key={p.id} person={p} me={me} owners={owners} fail={fail}
+          onRole={(id, r) => setPeople((l) => l.map((x) => (x.id === id ? { ...x, role: r } : x)))}
+          onRemove={(x) => { setPeople((l) => l.filter((y) => y.id !== x.id)); setStatus(`${x.name} was removed.`); }}
+          onResend={(x) => setStatus(`Invite resent to ${x.name}.`)}
+          onRevoke={(x) => { setPeople((l) => l.filter((y) => y.id !== x.id)); setStatus(`Invitation to ${x.name} revoked.`); document.getElementById('mb-heading')?.focus(); }} />)}</A.TableBody>
+      </A.Table>
+      <A.WorkflowStatus>{status}</A.WorkflowStatus>
+    </main>
+  );
+}
+// preview:end
+export default App;

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

@@ -0,0 +1,70 @@
+// Onboarding pattern (project/framework/patterns/onboarding.md): a setup checklist whose tasks are stamped done by the
+// app when they actually happen (never by clicking the item), with progress as a Meter; empty regions open with their
+// one action instead of a tour; a short tour only when someone asks for it; "What's new" with a count only for unseen
+// items. Every surface can be dismissed and found again from Help.
+// The lines between the preview markers are its "OnboardingPattern" 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 TASKS = [
+  { id: 'project', title: 'Create a project', about: 'Somewhere to keep your work.' },
+  { id: 'invite', title: 'Invite your team', about: 'Work goes faster together.' },
+  { id: 'connect', title: 'Connect a data source', about: 'Bring in what you already have.', action: 'Connect a data source' },
+  { id: 'billing', title: 'Add billing details', about: 'Needed before your trial ends on 14 November.', action: 'Add billing details' },
+];
+function App() {
+  const [done, setDone] = React.useState(/** @type {Record<string, boolean>} */ ({ project: true, invite: true }));
+  const [guide, setGuide] = React.useState(true);
+  const [sources, setSources] = React.useState(/** @type {string[]} */ ([]));
+  const [tour, setTour] = React.useState(false);
+  const [seen, setSeen] = React.useState(false);
+  const count = TASKS.filter((t) => done[t.id]).length;
+  const happen = (id) => setDone((d) => ({ ...d, [id]: true }));
+  return (
+    <main className="ob-page">
+      <header className="ob-head"><h2 className="ob-h">Acme workspace</h2>
+        <div className="ob-tools">
+          <A.Popover aria-label="What’s new" align="end" onOpenChange={(o) => { if (o) setSeen(true); }}
+            trigger={<A.Button size="sm" variant="ghost" id="ob-new">What’s new{!seen && <A.Badge variant="count" aria-label="2 unseen">2</A.Badge>}</A.Button>}>
+            <div className="ob-news"><A.Timeline aria-label="Recent changes" groupBy="none" locale="en-IE">
+              <A.TimelineItem key="n1" time="2026-10-28T09:00:00Z" isNew={!seen}>Saved views: keep a filter and come back to it</A.TimelineItem>
+              <A.TimelineItem key="n2" time="2026-10-21T09:00:00Z" isNew={!seen}>The sidebar now groups projects by team</A.TimelineItem>
+              <A.TimelineItem key="n3" time="2026-10-07T09:00:00Z">Export any table as CSV</A.TimelineItem>
+            </A.Timeline></div>
+          </A.Popover>
+          <A.Button size="sm" variant="ghost" id="ob-help" onClick={() => setGuide(true)}>Help: setup guide</A.Button>
+        </div>
+      </header>
+      {guide && <A.Card className="ob-guide" aria-labelledby="ob-guide-h">
+        <div className="ob-row"><h3 id="ob-guide-h" className="ob-sub">Set up your workspace</h3>
+          <A.Button size="sm" variant="ghost" onClick={() => setGuide(false)}>{count === TASKS.length ? 'Hide setup guide' : 'Skip for now'}</A.Button></div>
+        <A.Meter label="Setup" value={count} max={TASKS.length} format={(v) => `${v}`} />
+        <p className="ob-note">Tasks are checked off when you do them, wherever you do them.</p>
+        <ol className="ob-tasks">{TASKS.map((t) => <li key={t.id} className="ob-task" data-done={done[t.id] ? '' : undefined}>
+          <div><div className="ob-title">{t.title}</div><div className="ob-note">{t.about}</div></div>
+          {done[t.id] ? <A.Badge tone="positive">Done</A.Badge> : t.action ? <A.Button size="sm" onClick={() => document.getElementById('ob-' + t.id)?.scrollIntoView({ block: 'center' })}>{t.action}</A.Button> : null}
+        </li>)}</ol>
+      </A.Card>}
+      {!guide && <p className="ob-note" role="status">Setup guide hidden. Open it again any time from Help.</p>}
+      <section className="ob-section" aria-labelledby="ob-sources-h" id="ob-connect">
+        <h3 id="ob-sources-h" className="ob-sub">Data sources</h3>
+        {sources.length ? <ul className="ob-list">{sources.map((s) => <li key={s}>{s}</li>)}</ul>
+          : <A.EmptyState size="sm" title="No data sources yet" description="Connect a database or a spreadsheet and its tables appear here."
+              action={<A.Button variant="primary" onClick={() => { setSources(['Sales database']); happen('connect'); }}>Connect a data source</A.Button>} />}
+      </section>
+      <section className="ob-section" aria-labelledby="ob-billing-h" id="ob-billing">
+        <h3 id="ob-billing-h" className="ob-sub">Billing</h3>
+        {done.billing ? <p className="ob-note">Card ending 4242 on file.</p> : <div><A.Button onClick={() => happen('billing')}>Add billing details</A.Button></div>}
+      </section>
+      <nav aria-label="Projects" className="ob-nav" id="ob-sidebar"><span className="ob-note">Design team</span><A.Link href="#/p/1">Website refresh</A.Link><A.Link href="#/p/2">Brand kit</A.Link></nav>
+      <div><A.Button size="sm" variant="ghost" onClick={() => setTour(true)}>Show me what changed in the sidebar</A.Button></div>
+      <A.Tour open={tour} onOpenChange={setTour} steps={[
+        { target: '#ob-sidebar', title: 'Projects are grouped by team', body: 'Each team’s projects sit under its name. Drag a project to move it.' },
+        { target: '#ob-new', title: 'Find changes here', body: 'What’s new lists every change, so you can come back to this later.' },
+      ]} />
+    </main>
+  );
+}
+// preview:end
+export default App;

package/dist/guidance/references/build/fixtures/patterns/screen-layout-decision.jsx

@@ -0,0 +1,74 @@
+// Screen layout pattern (project/framework/patterns/screen-layout.md), the decision frame.
+//   Task: a billing lead decides whether to refund a customer's October invoice.
+//   Lead: the choice and its consequence. Primary action: Approve refund. Next: the next request in the queue.
+// The question is the title; the consequence in words and the two choices sit straight under it, before the evidence.
+// Declining asks for its reason in place; Cancel returns focus to Decline. Once decided, the outcome replaces the choice
+// and takes focus. The lines between the preview markers are its "ScreenLayoutDecision" 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.
+// preview-name: ScreenLayoutDecision
+import * as React from 'react';
+import * as A from 'altitude-design';
+// preview:start
+function App() {
+  const [phase, setPhase] = React.useState(/** @type {'deciding' | 'declining' | 'sending' | 'approved' | 'declined'} */ ('deciding'));
+  const [reason, setReason] = React.useState('');
+  const [reasonError, setReasonError] = React.useState('');
+  const declineRef = React.useRef(/** @type {HTMLButtonElement | null} */ (null));
+  const outcome = React.useRef(/** @type {HTMLDivElement | null} */ (null));
+  const [sending, setSending] = React.useState(/** @type {'approved' | 'declined' | null} */ (null));
+  const decide = (result) => {
+    if (result === 'declined' && !reason.trim()) { setReasonError('Say why, so Support can tell Northwind.'); document.getElementById('ld-reason')?.focus(); return; }
+    setSending(result); setPhase('sending');
+    window.setTimeout(() => { setPhase(result); requestAnimationFrame(() => outcome.current?.focus()); }, 600);
+  };
+  const cancel = () => { setPhase('deciding'); setReasonError(''); requestAnimationFrame(() => declineRef.current?.focus()); };
+  const done = phase === 'approved' || phase === 'declined';
+  return (
+    <main className="ld-page">
+      <A.PageHeader breadcrumb={<A.Breadcrumb items={[{ label: 'Refund requests', href: '#/refunds' }, { label: 'R-1042' }]} />}>
+        <A.PageHeaderTitle>Refund €420 to Northwind?</A.PageHeaderTitle>
+        <A.PageHeaderDescription>Asked by Jon Park in Support, today at 09:12.</A.PageHeaderDescription>
+      </A.PageHeader>
+      {done ? (
+        <div className="ld-choice" role="status" tabIndex={-1} ref={outcome}>
+          <p className="ld-consequence">{phase === 'approved' ? 'Refund approved. €420 goes back to the card ending 4242 in 5–10 days, and the October invoice is marked refunded.' : 'Refund declined. Jon has your reason to send to Northwind.'}</p>
+          <div><A.Link href="#/refunds/R-1043">Next request: Halcyon, €96 (2 more waiting)</A.Link></div>
+        </div>
+      ) : (
+        <section className="ld-choice" aria-labelledby="ld-choice-h">
+          <h2 id="ld-choice-h" className="ld-sr">Your decision</h2>
+          <p className="ld-consequence">Approving sends €420 back to Northwind’s card ending 4242 in 5–10 days and marks their October invoice refunded. A refund can’t be taken back once it’s sent.</p>
+          {phase === 'declining' || (phase === 'sending' && sending === 'declined') ? <>
+            <A.Field label="Why decline?" hint="Jon sends this to Northwind." error={reasonError || undefined}>
+              <A.Textarea id="ld-reason" rows={3} value={reason} onChange={(e) => { setReason(e.target.value); setReasonError(''); }}
+                onKeyDown={(e) => { if (e.key === 'Escape') cancel(); }} />
+            </A.Field>
+            <div className="ld-actions">
+              <A.Button variant="primary" loading={phase === 'sending'} onClick={() => decide('declined')}>Send decline</A.Button>
+              <A.Button variant="ghost" onClick={cancel} disabled={phase === 'sending'}>Cancel</A.Button>
+            </div>
+          </> : (
+            <div className="ld-actions">
+              <A.Button variant="primary" loading={phase === 'sending'} onClick={() => decide('approved')}>Approve refund</A.Button>
+              <A.Button ref={declineRef} onClick={() => { setPhase('declining'); requestAnimationFrame(() => document.getElementById('ld-reason')?.focus()); }} disabled={phase === 'sending'}>Decline</A.Button>
+            </div>
+          )}
+        </section>
+      )}
+      <section className="ld-evidence" aria-labelledby="ld-why-h">
+        <h2 id="ld-why-h" className="ld-sub">Why they’re asking</h2>
+        <blockquote className="ld-quote">“We moved to annual billing on 2 October, but the monthly invoice still went out. We were charged twice for October.”</blockquote>
+        <A.PropertyList layout="inline" aria-label="The invoice">
+          <A.PropertyListItem label="Invoice" value="INV-2026-1017, 1 October" />
+          <A.PropertyListItem label="Amount" value="€420.00" />
+          <A.PropertyListItem label="Annual plan" value="Started 2 October, paid €4,536" />
+          <A.PropertyListItem label="Customer since" value="March 2023" />
+          <A.PropertyListItem label="Refunds before" value="None" />
+        </A.PropertyList>
+      </section>
+    </main>
+  );
+}
+// preview:end
+export default App;

package/dist/guidance/references/build/fixtures/patterns/screen-layout-editor.jsx

@@ -0,0 +1,56 @@
+// Screen layout pattern (project/framework/patterns/screen-layout.md), the focused editor frame.
+//   Task: a product manager writes this week's release note and publishes it.
+//   Lead: the note being written. Primary action: Publish. Next: the published note's place on the changelog.
+// No navigation sidebar, a breadcrumb back; the draft fills the column with its details beside it, narrower and quieter;
+// saving is a status in the header, not a second button. The lines between the preview markers are its
+// "ScreenLayoutEditor" 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.
+// preview-name: ScreenLayoutEditor
+import * as React from 'react';
+import * as A from 'altitude-design';
+// preview:start
+const AUDIENCES = [{ value: 'everyone', label: 'Everyone' }, { value: 'admins', label: 'Workspace admins' }];
+function App() {
+  const [title, setTitle] = React.useState('Saved views, and a faster sidebar');
+  const [body, setBody] = React.useState('You can now save a filtered view of any table and come back to it from the sidebar.\n\nThe sidebar also opens twice as fast in large workspaces.');
+  const [audience, setAudience] = React.useState('everyone');
+  const [sync, setSync] = React.useState(/** @type {A.SyncState} */ ('saved'));
+  const [titleError, setTitleError] = React.useState('');
+  const [phase, setPhase] = React.useState(/** @type {'draft' | 'publishing' | 'published'} */ ('draft'));
+  const timer = React.useRef(0);
+  const outcome = React.useRef(/** @type {HTMLParagraphElement | null} */ (null));
+  const edit = (set) => (e) => { set(e.target.value); setSync('saving'); clearTimeout(timer.current); timer.current = window.setTimeout(() => setSync('saved'), 700); };
+  const publish = () => {
+    if (!title.trim()) { setTitleError('Give the note a title.'); document.getElementById('le-title')?.focus(); return; }
+    setPhase('publishing');
+    window.setTimeout(() => { setPhase('published'); requestAnimationFrame(() => outcome.current?.focus()); }, 600);
+  };
+  return (
+    <main className="le-page">
+      <A.PageHeader breadcrumb={<A.Breadcrumb items={[{ label: 'Release notes', href: '#/notes' }, { label: 'Week 44' }]} />}
+        actions={<A.SyncIndicator state={sync} />}
+        primary={phase === 'published' ? undefined : <A.Button variant="primary" loading={phase === 'publishing'} onClick={publish}>Publish</A.Button>}>
+        <A.PageHeaderTitle>Week 44 release note</A.PageHeaderTitle>
+      </A.PageHeader>
+      {phase === 'published' && <p className="le-outcome" role="status" tabIndex={-1} ref={outcome}>Published. Week 44 is at the top of the changelog and in everyone’s What’s new. <A.Link href="#/changelog">View the changelog</A.Link></p>}
+      <div className="le-body">
+        <section className="le-draft" aria-label="Draft">
+          <A.Field label="Title" error={titleError || undefined}>
+            <A.Input id="le-title" value={title} readOnly={phase !== 'draft'} onChange={(e) => { setTitleError(''); edit(setTitle)(e); }} />
+          </A.Field>
+          <A.Field label="Note">
+            <A.Textarea className="le-text" rows={14} value={body} readOnly={phase !== 'draft'} onChange={edit(setBody)} />
+          </A.Field>
+        </section>
+        <aside className="le-side" aria-labelledby="le-side-h">
+          <h2 id="le-side-h" className="le-sub">Details</h2>
+          <A.Field label="Who sees it"><A.Select items={AUDIENCES} value={audience} onValueChange={(v) => setAudience(String(v))} disabled={phase !== 'draft'} /></A.Field>
+          <p className="le-note">Publishing adds it to the changelog and to What’s new for {audience === 'everyone' ? 'everyone' : 'workspace admins'}.</p>
+          <p className="le-note">Last week: “Export any table as CSV”.</p>
+        </aside>
+      </div>
+    </main>
+  );
+}
+// preview:end
+export default App;

package/dist/guidance/references/build/fixtures/patterns/screen-layout-report.jsx

@@ -0,0 +1,42 @@
+// Screen layout pattern (project/framework/patterns/screen-layout.md), the report frame.
+//   Task: the growth team reads how October's signups went after the pricing change.
+//   Lead: a chart whose takeaway is the heading. Primary action: none (reading is the task). Next: the cohort report.
+// The takeaway is written from the data shown; the secondary numbers follow, smaller and grouped, never a row of equal
+// cards above the chart. The lines between the preview markers are its "ScreenLayoutReport" 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.
+// preview-name: ScreenLayoutReport
+import * as React from 'react';
+import * as A from 'altitude-design';
+// preview:start
+// Daily signups for October 2026: about 40 a day, then about 80 a day from the pricing change on the 14th.
+const SIGNUPS = Array.from({ length: 31 }, (_, i) => ({ day: `2026-10-${String(i + 1).padStart(2, '0')}`, signups: (i < 13 ? 41 : 82) + Math.round(4 * Math.sin(i * 2.3)) - (new Date(Date.UTC(2026, 9, i + 1)).getUTCDay() % 6 === 0 ? 6 : 0) }));
+const total = SIGNUPS.reduce((n, d) => n + d.signups, 0);
+const before = SIGNUPS.slice(0, 13), after = SIGNUPS.slice(13);
+const mean = (rows) => Math.round(rows.reduce((n, d) => n + d.signups, 0) / rows.length);
+function App() {
+  return (
+    <main className="lr-page">
+      <A.PageHeader breadcrumb={<A.Breadcrumb items={[{ label: 'Reports', href: '#/reports' }, { label: 'Signups' }]} />}
+        actions={<A.Button variant="secondary">Export CSV</A.Button>}>
+        <A.PageHeaderTitle>Signups, October 2026</A.PageHeaderTitle>
+      </A.PageHeader>
+      <A.ChartContainer className="lr-lead" title="Daily signups" takeaway={`Signups doubled after the pricing change on 14 October, from ${mean(before)} a day to ${mean(after)}`}
+        config={{ signups: { label: 'Signups' } }} aspect={2.6} zero
+        summary={`${total.toLocaleString('en-IE')} signups in October. From 1 to 13 October about ${mean(before)} a day; from 14 October, when the free plan gained a third project, about ${mean(after)} a day.`}>
+        <A.LineChart data={SIGNUPS} x="day" />
+      </A.ChartContainer>
+      <section className="lr-more" aria-labelledby="lr-more-h">
+        <h2 id="lr-more-h" className="lr-sub">Around it</h2>
+        <A.StatGroup aria-label="October in numbers">
+          <A.Stat label="Signups in October" value={total} change={{ value: 0.41, vs: 'September' }} good="up" locale="en-IE" />
+          <A.Stat label="Became paying within 7 days" value="6.1%" help="5.8% in September" />
+          <A.Stat label="Cancelled in their first week" value={38} change={{ value: -0.12, vs: 'September' }} good="down" locale="en-IE" />
+        </A.StatGroup>
+        <p className="lr-note">Paid conversion held while signups doubled, so the new free-plan signups aren’t lower-intent so far. <A.Link href="#/reports/cohorts">See the October cohort</A.Link></p>
+      </section>
+    </main>
+  );
+}
+// preview:end
+export default App;

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

@@ -0,0 +1,73 @@
+// Settings pattern (project/framework/patterns/settings.md): a workspace settings page. General fields are saved
+// together as one draft with a SaveBar; notification switches apply immediately, each reporting its own write; billing
+// is read-only for this person, with the reason in words; the danger zone deletes through a typed confirmation.
+// The lines between the preview markers are its "SettingsPattern" 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 [failNext, setFailNext] = React.useState(false);
+  const fail = React.useRef(false); fail.current = failNext;
+  const [saved, setSaved] = React.useState({ name: 'Acme', url: 'acme' });
+  const general = A.useEditRecord({
+    initialValue: saved, validationMode: 'submit',
+    validate: (d) => ({ ...(d.name.trim() ? {} : { name: 'Enter a workspace name.' }), ...(/^[a-z0-9-]+$/.test(d.url) ? {} : { url: 'Use lowercase letters, numbers and hyphens.' }) }),
+    save: async (draft) => { await wait(800); if (fail.current) return { ok: false, error: 'We couldn’t reach the server. Your changes are still here.' }; setSaved(draft); return { ok: true, value: draft }; },
+  });
+  const [prefs, setPrefs] = React.useState({ digest: true, mentions: true });
+  const [writes, setWrites] = React.useState({ digest: undefined, mentions: undefined });
+  const apply = async (key, value) => {
+    setPrefs((p) => ({ ...p, [key]: value })); setWrites((w) => ({ ...w, [key]: 'pending' }));
+    await wait(900);
+    if (fail.current) { setPrefs((p) => ({ ...p, [key]: !value })); setWrites((w) => ({ ...w, [key]: 'failed' })); }
+    else setWrites((w) => ({ ...w, [key]: 'committed' }));
+  };
+  const [deleted, setDeleted] = React.useState(false);
+  const [typed, setTyped] = React.useState('');
+  const heading = React.useRef(null);
+  const remove = A.useConsequentialAction({
+    target: 'Acme workspace', consequence: 'Delete Acme, its 12 projects and 1,204 files for all 8 members. This can’t be undone.',
+    requiresConfirmation: true, focusFallback: () => heading.current,
+    execute: async () => { await wait(900); if (fail.current) return { ok: false, error: 'We couldn’t delete the workspace. Nothing was removed. Try again.' }; setDeleted(true); return { ok: true, value: 'acme' }; },
+    messages: { pending: 'Deleting Acme workspace', succeeded: 'Acme workspace deleted' },
+  });
+  const confirming = ['confirming', 'pending', 'failed'].includes(remove.phase);
+  const field = (key, label, hint) => <A.Field label={label} hint={hint} error={general.errors[key]}><A.Input id={'ws-' + key} value={general.draft[key]} onChange={(e) => general.setField(key, e.target.value)} /></A.Field>;
+  if (deleted) return <main className="st-page"><h2 ref={heading} tabIndex={-1} className="st-h">Workspace deleted</h2><p>Acme and everything in it were deleted.</p><A.WorkflowStatus>{remove.status}</A.WorkflowStatus></main>;
+  return (
+    <main className="st-page">
+      <h2 ref={heading} tabIndex={-1} className="st-h">Workspace settings</h2>
+      <nav aria-label="Settings sections" className="st-nav"><a href="#st-general">General</a><a href="#st-notify">Notifications</a><a href="#st-billing">Billing</a><a href="#st-danger">Danger zone</a></nav>
+      <A.Switch label="Make the next change fail" checked={failNext} onCheckedChange={setFailNext} />
+      <A.SettingsSection id="st-general" title="General" description="Saved together: change what you need, then save once.">
+        <form className="st-form" noValidate onSubmit={(e) => { e.preventDefault(); void general.submit(); }}>
+          <A.ErrorSummary errors={Object.entries(general.errors).map(([k, message]) => ({ id: 'ws-' + k, label: k === 'name' ? 'Workspace name' : 'Workspace URL', message }))} focusKey={general.submitCount} />
+          {field('name', 'Workspace name', 'Shown to everyone in the workspace.')}
+          {field('url', 'Workspace URL', 'altitude.app/' + general.draft.url)}
+        </form>
+      </A.SettingsSection>
+      <A.SettingsSection id="st-notify" title="Notifications" description="Each change applies as soon as you make it.">
+        <A.SettingsRow label="Weekly digest" description="A summary of activity every Monday." status={writes.digest}><A.Switch checked={prefs.digest} onCheckedChange={(v) => apply('digest', v)} /></A.SettingsRow>
+        <A.SettingsRow label="Mentions" description="Email me when someone mentions me." status={writes.mentions}><A.Switch checked={prefs.mentions} onCheckedChange={(v) => apply('mentions', v)} /></A.SettingsRow>
+      </A.SettingsSection>
+      <A.SettingsSection id="st-billing" title="Billing" readOnlyReason="Only workspace owners can change billing details. Ask Maya Chen.">
+        <A.SettingsRow label="Billing email" description="Invoices and receipts go here."><A.Input defaultValue="finance@acme.dev" /></A.SettingsRow>
+      </A.SettingsSection>
+      <A.SettingsSection id="st-danger" title="Danger zone" tone="critical">
+        <A.SettingsRow label="Delete workspace" description={remove.consequence}><A.Button variant="danger" onClick={remove.request}>Delete workspace</A.Button></A.SettingsRow>
+      </A.SettingsSection>
+      <A.WorkflowStatus>{general.status || remove.status}</A.WorkflowStatus>
+      <A.SaveBar record={general} />
+      <A.Dialog open={confirming} background="stationary" dismissible={remove.phase !== 'pending'} onOpenChange={(o) => { if (!o) { remove.cancel(); setTyped(''); } }} returnFocus={() => heading.current}
+        title="Delete Acme workspace?" description={remove.consequence}
+        footer={<><A.Button disabled={remove.phase === 'pending'} onClick={() => { remove.cancel(); setTyped(''); }}>Keep workspace</A.Button><A.Button variant="danger" disabled={typed !== 'Acme' || remove.phase === 'pending'} onClick={remove.phase === 'failed' ? remove.retry : remove.confirm}>{remove.phase === 'pending' ? 'Deleting workspace' : remove.phase === 'failed' ? 'Try deleting again' : 'Delete workspace'}</A.Button></>}>
+        <A.Field label="Type Acme to confirm"><A.Input value={typed} onChange={(e) => setTyped(e.target.value)} autoComplete="off" /></A.Field>
+        {remove.error && <p role="alert">{remove.error}</p>}
+      </A.Dialog>
+    </main>
+  );
+}
+// preview:end
+export default App;