altitude-design 0.3.2 → 0.4.1

package/dist/guidance/components/EditRegion/README.md

@@ -0,0 +1,263 @@
+# EditRegion
+
+Edit several fields of one record where the record is shown, and save them together as one write. Use it when two or more related values change together (a contact's name, email and role; a task's title, assignee and due date): several `InlineEdit`s would save one at a time and could leave the record half-changed, and a `Dialog` would cover the neighbouring records people look at to judge what a reasonable value is.
+
+```tsx
+<EditRegion label="Contact" value={contact} onValueChange={setContact}
+  validate={(draft) => draft.email.includes('@') ? undefined : { email: 'Enter an email address.' }}
+  onSave={async (draft, { previousValue, changed }) => {
+    const result = await api.patchContact(contact.id, pick(draft, changed), contact.revision);
+    return result.ok ? { ok: true, value: result.contact } : { ok: false, error: result.message, fieldErrors: result.fieldErrors };
+  }}>
+  <EditRegionView>
+    <strong>{contact.name}</strong> <span>{contact.email}</span>
+  </EditRegionView>
+  <EditRegionForm>
+    {(field) => <>
+      <Field label="Name" required error={field.error('name')}><Input {...field('name')} /></Field>
+      <Field label="Email" required error={field.error('email')}><Input type="email" {...field('email')} /></Field>
+      <Field label="Role"><Select {...field.value('role')} items={roles} /></Field>
+      <Switch {...field.checked('notify')} label="Email them when this project changes" />
+    </>}
+  </EditRegionForm>
+</EditRegion>
+```
+
+## Elevation
+
+- **Read mode** is the record on the ground (level 0): the values as text and a visible ghost “Edit <label>” button.
+- **Editing** lifts the region into a static raised card (level 1, `surface-raised`, `elev-1`, a `line-control` border), as an `Accordion` lid lifts over its compartment. The card's padding and border are there in read mode too, transparent, under a matching negative margin, so lifting changes colour and shadow but never moves the record. Leave room for that margin either side: `space-3` plus 1px, or 22px with `layout="in-place"`. It doesn't lift on hover: it's being worked in, not offered. The fields inside are openings: empty wells, filled flush, invalid trenches, as `Input`, `Select` and `Field` draw them.
+- **Saving** uses `Surface status="pending"`: after `dur-grace` it hovers at level 2, so a fast save shows nothing. **A known failure** drops to the failed trench with a critical `Alert` inside the editor; the draft stays. **Accepted** values settle back to the ground with one afterglow for the region, however many fields changed.
+- **An outside change** while editing keeps the draft, blocks Save and shows a caution `Alert` “This record changed” with “Use current values”.
+
+The words carry every state without height: the form's name, the button labels, `aria-invalid` and error text on fields, `aria-busy` on the form while saving, and the polite status (“Checking”, “Saving changes”, “Saved” or the error), which is announced, never shown, and clears itself after `dur-linger`. The afterglow fills the padded card, so it never sits against the text. Under forced colours the editor is a raised Surface with a border; under `contrast="more"` it gets level 1's ink slab.
+
+## Props
+
+| Prop | |
+|---|---|
+| `label` | names the region: the form is “Edit <label>” |
+| `value`, `onValueChange` | the committed record, and a synchronous setter for the accepted canonical record (no network write) |
+| `onSave(draft, { previousValue, changed })` | the sole write. Return `{ ok: true, value }` with the canonical record, or `{ ok: false, error, fieldErrors? }` for a known failure. A throw or malformed result shows a generic retry message |
+| `validate(draft)` | on Save: an error per field, or `undefined`; sync or a promise |
+| `open`, `defaultOpen`, `onOpenChange` | control the session. Closing a controlled region doesn't cancel a dispatched save |
+| `disabled`, `initialFocus`, `focusFallback`, `isEqual` | as `InlineEdit`; `initialFocus` names a field key; `isEqual` compares one field's values (default `Object.is`) |
+| `editLabel`, `saveLabel`, `cancelLabel` | default “Edit <label>”, “Save changes”, “Cancel” |
+| `settleDuration` | how long the afterglow takes to fade after a save, in ms. Default 5000 (shorter than `dur-settle`, because the person is watching the change) |
+| `layout` | `'form'` (default): editing opens your form. `'in-place'`: each value's well opens where its text is (below) |
+
+Parts: `EditRegionView` (read mode; `trigger={false}` to place `EditRegionTrigger` yourself), `EditRegionValue` (one value in read mode, named by its field; `reserve` for labelled rows), `EditRegionForm` (edit mode; children may be a function of the draft binder; `actions={false}` to place `EditRegionActions` yourself), `EditRegionTrigger`, `EditRegionActions`.
+
+The binder: `field(key)` for text controls (`value` + `onChange`, `readOnly` while locked), `field.value(key)` for `Select`, `Combobox` and `Slider` (`value` + `onValueChange`), `field.checked(key)` for `Switch` and `Checkbox`, `field.error(key)` for the field's `Field`, and `field.draft`. Each binding carries `data-field`, which `initialFocus` and error focus use.
+
+## In place: `layout="in-place"`
+
+With `layout="in-place"` the fields open where the values are, as a single `InlineEdit` does, instead of a form replacing the record.
+
+```tsx
+<EditRegion layout="in-place" label={person.name} value={person} onValueChange={…} onSave={…}>
+  <EditRegionView>
+    <span className="name"><EditRegionValue field="name">{person.name}</EditRegionValue></span>
+    <span className="meta"><EditRegionValue field="email">{person.email}</EditRegionValue> · <EditRegionValue field="role">{roleName}</EditRegionValue></span>
+  </EditRegionView>
+  <EditRegionForm>
+    {(field) => <>
+      <div className="name"><Field label="Name" error={field.error('name')}><Input {...field('name')} /></Field></div>
+      <div className="meta-row">
+        <Field label="Email" error={field.error('email')}><Input {...field('email')} /></Field>
+        <Field label="Role"><Select {...field.value('role')} items={roles} /></Field>
+      </div>
+    </>}
+  </EditRegionForm>
+</EditRegion>
+```
+
+- **Mark each read value** with `EditRegionValue field="…"`, using the same key you bind. A field whose text opens where its value was simply appears; one that opens elsewhere (a control wider or taller than its text pushes the next one along) fades in there. Nothing slides.
+- **Lay the fields out where the values were**, in the same wrappers, so each control takes the value's font. Controls reach 13px past their column on each side, the inset their text sits at, so the text lines up and the well reaches into the gutter: leave 26px more between columns than you want to see. Give rows fixed columns (a grid) rather than columns sized by what's typed, so nothing reflows while the editor opens. The form adds no spacing of its own.
+- **A `Field`'s label is announced, not shown**: the record around the field already names it (a row's label, the value's place). Its error, `aria-invalid` and description still work.
+- **Labelled rows**: `EditRegionValue reserve` gives a read value its control's height and inset now. In a list of label–value rows, Edit all then moves nothing, and only the actions row is added at the end.
+
+## Behaviour
+
+- Edit opens the form and focuses the first field (or `initialFocus`). Tab moves through the fields and out to the page; blur and outside clicks do nothing to the session (no save on blur, as `InlineEdit`).
+- Enter in a single-line field saves; Ctrl/Cmd+Enter in a textarea saves. Nothing acts during IME composition. Escape cancels, except while a popup inside (a Select's list) is open: that Escape closes the popup, and the next one cancels. Escape never cancels a dispatched save; it announces “Saving changes. Wait for the result.”
+- Saving an unchanged draft closes without a write. `changed` lists only the fields that differ, so the application can send a patch.
+- Validation errors mark each field and focus the first invalid one; typing in a field clears its error. A save's `fieldErrors` are shown the same way, beside the `error` Alert.
+- One write per record may be in flight: Save, Enter and repeated presses dispatch once. While saving, text fields are read-only and choice controls disabled.
+- An observed `value` change during a save latches a conflict: the result is never published, and the message says the save may have completed. The application must reconcile its server state.
+- Completion returns focus to the Edit button only if focus was still in the editor. Unmounting invalidates pending work and suppresses publication.
+- Inside another `<form>`, the editor is a `role="group"` instead of a form, so forms don't nest.
+
+## You provide
+
+The record, the write (with a server-side revision or equivalent concurrency guard), validation policy, and reconciliation of interrupted writes, exactly as for `InlineEdit`. EditRegion doesn't autosave, keep history, or roll back a dispatched write.
+
+## Do and don't
+
+- **Do** keep the record's neighbours visible: that's why it edits in place.
+- **Do** use `InlineEdit` for a single value; EditRegion is for values that must change together.
+- **Don't** put more than about five fields in one region. A long form belongs in a `Sheet` beside the page.
+- **Don't** update `value` optimistically from `onSave`: an observed change is treated as someone else's write.
+
+## Demo and verification
+
+The `EditRegion` section of `build/previews.txt` lists three people with access; each row is an in-place EditRegion over a fictional people service with revisions. Below it, trip details are label–value rows with reserved values. A collapsed harness picks a save fixture (`success`, `slow`, `fail-once`, `conflict-during-save`) and applies an outside update. `node checks/edit-region.mjs` (from `build/`, after rendering previews; `ALT_FIXTURE_ROOT` selects React 19 fixtures) covers editing in place (fields hold their place on every frame while the editor grows, the record below is pushed through the glide, lifting never moves the record, each field opens at its value's x, reserved values open exactly where they were, the padded afterglow, the announcement that clears itself), opening and focus, unchanged saves, one write per save, `changed`, validation and error focus, Escape with an open Select, IME Enter, failure and retry, pending lock, both conflict paths, focus return, and a 320/960px layout in both schemes under reduced motion, forced colours and `contrast="more"`.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`EditRegion` as first used in its preview:
+
+```tsx
+import { EditRegion, EditRegionForm, EditRegionValue, EditRegionView, Field, Input, Select, Switch } from 'altitude-design';
+
+<EditRegion layout="in-place" label={person.name} editLabel={`Edit ${person.name}`} value={erFields(person)} validate={validate}
+  onValueChange={canonical => setPeople(people => people.map(p => p.id === person.id ? { ...server.current.get(person.id), ...canonical } : p))}
+  onSave={save(person)}>
+  <EditRegionView>
+    <span className="er-name"><EditRegionValue field="name">{person.name}</EditRegionValue></span>
+    <span className="er-meta"><EditRegionValue field="email">{person.email}</EditRegionValue> · <EditRegionValue field="role">{ER_ROLES.find(r => r.value === person.role).label}</EditRegionValue>{person.notify ? <> · <EditRegionValue field="notify">Gets updates</EditRegionValue></> : ''}</span>
+  </EditRegionView>
+  <EditRegionForm>
+    {field => <>
+      <div className="er-name-edit"><Field label="Name" required error={field.error('name')}><Input {...field('name')} autoComplete="off" /></Field></div>
+      <div className="er-meta-edit">
+        <Field label="Email" required error={field.error('email')}><Input {...field('email')} type="email" autoComplete="off" /></Field>
+        <Field label="Role"><Select {...field.value('role')} items={ER_ROLES} /></Field>
+        <Switch {...field.checked('notify')} label="Gets updates" />
+      </div>
+    </>}
+  </EditRegionForm>
+</EditRegion>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`er-list`, `er-name`, `er-meta`, `er-name-edit`, `er-meta-edit`, `er-harness`, `er-harness-controls`, `er-log`, `er-sheet`, `er-sheet-head`, `er-sheet-grid`, `er-demo` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Button, EditRegion, EditRegionForm, EditRegionTrigger, EditRegionValue, EditRegionView, Field, Input, Select, Switch } from 'altitude-design';
+
+const ER_ROLES = [{ value: 'owner', label: 'Owner' }, { value: 'editor', label: 'Editor' }, { value: 'viewer', label: 'Viewer' }];
+const ER_PEOPLE = Object.freeze([
+  Object.freeze({ id: 'p-mara', name: 'Mara Quist', email: 'mara@northwind.example', role: 'owner', notify: true, revision: 1 }),
+  Object.freeze({ id: 'p-ines', name: 'Inés Ortega', email: 'ines@northwind.example', role: 'editor', notify: false, revision: 1 }),
+  Object.freeze({ id: 'p-tobi', name: 'Tobi Adeyemi', email: 'tobi@northwind.example', role: 'viewer', notify: true, revision: 1 }),
+]);
+const ER_FIXTURES = ['success', 'slow', 'fail-once', 'conflict-during-save'];
+const erWait = ms => new Promise(resolve => setTimeout(resolve, ms));
+const erFields = ({ revision, id, ...fields }) => fields;
+
+// A fictional people service with revisions: a stale write is rejected, an accepted one returns the canonical record.
+function EditRegionExample({ fixture }) {
+  const server = React.useRef(new Map(ER_PEOPLE.map(p => [p.id, { ...p }])));
+  const [people, setPeople] = React.useState(() => ER_PEOPLE.map(p => ({ ...p })));
+  const [log, setLog] = React.useState([]);
+  const failed = React.useRef(false);
+  const trace = event => setLog(log => [...log, event]);
+  const reconcile = id => setPeople(people => people.map(p => p.id === id ? { ...server.current.get(id) } : p));
+  const externalUpdate = () => {
+    const current = server.current.get('p-mara');
+    server.current.set('p-mara', { ...current, email: 'm.quist@northwind.example', revision: current.revision + 1 });
+    trace({ event: 'external-update', id: 'p-mara', revision: current.revision + 1 }); reconcile('p-mara');
+  };
+  const save = person => async (draft, { changed }) => {
+    trace({ event: 'requested', id: person.id, expectedRevision: person.revision, changed });
+    await erWait(fixture === 'slow' ? 1400 : 250);
+    if (fixture === 'fail-once' && !failed.current) { failed.current = true; trace({ event: 'rejected', id: person.id }); return { ok: false, error: 'We couldn’t reach the people service. Your changes are still here. Try again.' }; }
+    if (fixture === 'conflict-during-save') { externalUpdate(); await erWait(300); }
+    const current = server.current.get(person.id);
+    if (current.revision !== person.revision) { trace({ event: 'rejected-stale', id: person.id }); return { ok: false, error: 'Someone else changed this person. Review the current details.' }; }
+    if ([...server.current.values()].some(p => p.id !== person.id && p.email === draft.email.trim())) return { ok: false, error: 'Check the highlighted field.', fieldErrors: { email: 'Someone else already uses this email.' } };
+    const next = { ...current, ...draft, name: draft.name.trim(), email: draft.email.trim(), revision: current.revision + 1 };
+    server.current.set(person.id, next);
+    trace({ event: 'committed', id: person.id, revision: next.revision, changed });
+    return { ok: true, value: erFields(next) };
+  };
+  const validate = draft => {
+    const errors = {};
+    if (!draft.name.trim()) errors.name = 'Enter a name.';
+    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(draft.email.trim())) errors.email = 'Enter an email address, like name@example.com.';
+    return Object.keys(errors).length ? errors : undefined;
+  };
+  return <>
+    <section aria-labelledby="er-title">
+      <h2 id="er-title">People with access</h2>
+      <ul className="er-list">
+        {people.map(person => <li key={person.id}>
+          <EditRegion layout="in-place" label={person.name} editLabel={`Edit ${person.name}`} value={erFields(person)} validate={validate}
+            onValueChange={canonical => setPeople(people => people.map(p => p.id === person.id ? { ...server.current.get(person.id), ...canonical } : p))}
+            onSave={save(person)}>
+            <EditRegionView>
+              <span className="er-name"><EditRegionValue field="name">{person.name}</EditRegionValue></span>
+              <span className="er-meta"><EditRegionValue field="email">{person.email}</EditRegionValue> · <EditRegionValue field="role">{ER_ROLES.find(r => r.value === person.role).label}</EditRegionValue>{person.notify ? <> · <EditRegionValue field="notify">Gets updates</EditRegionValue></> : ''}</span>
+            </EditRegionView>
+            <EditRegionForm>
+              {field => <>
+                <div className="er-name-edit"><Field label="Name" required error={field.error('name')}><Input {...field('name')} autoComplete="off" /></Field></div>
+                <div className="er-meta-edit">
+                  <Field label="Email" required error={field.error('email')}><Input {...field('email')} type="email" autoComplete="off" /></Field>
+                  <Field label="Role"><Select {...field.value('role')} items={ER_ROLES} /></Field>
+                  <Switch {...field.checked('notify')} label="Gets updates" />
+                </div>
+              </>}
+            </EditRegionForm>
+          </EditRegion>
+        </li>)}
+      </ul>
+    </section>
+    <TripSheet />
+    <details className="er-harness">
+      <summary>Fixture controls</summary>
+      <p>Documentation harness only: change Mara's record on the “server” while it's being edited.</p>
+      <div className="er-harness-controls"><Button onClick={externalUpdate}>Apply external update to Mara</Button></div>
+      <output className="er-log" data-er-log="" aria-label="Fixture operation log">{JSON.stringify(log, null, 2)}</output>
+    </details>
+  </>;
+}
+
+// Labelled rows whose values already have their controls' height (EditRegionValue reserve): Edit all moves nothing.
+const ER_SEATS = [{ value: 'aisle', label: 'Aisle' }, { value: 'window', label: 'Window' }, { value: 'any', label: 'No preference' }];
+function TripSheet() {
+  const [trip, setTrip] = React.useState({ traveller: 'Mara Quist', email: 'mara@northwind.example', phone: '', seat: 'aisle' });
+  const validate = draft => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(draft.email.trim()) ? undefined : { email: 'Enter an email address, like name@example.com.' };
+  const rows = [['traveller', 'Traveller'], ['email', 'Email'], ['phone', 'Phone'], ['seat', 'Seat']];
+  return <section className="er-sheet" aria-labelledby="er-sheet-title">
+    <EditRegion layout="in-place" label="Trip details" editLabel="Edit all trip details" value={trip} validate={validate} onValueChange={setTrip}
+      onSave={async draft => { await erWait(250); return { ok: true, value: { ...draft, traveller: draft.traveller.trim(), email: draft.email.trim(), phone: draft.phone.trim() } }; }}>
+      <EditRegionView trigger={false}>
+        <div className="er-sheet-head"><h2 id="er-sheet-title">Trip details</h2><EditRegionTrigger>Edit all</EditRegionTrigger></div>
+        <dl className="er-sheet-grid">{rows.map(([key, label]) => <React.Fragment key={key}><dt>{label}</dt><dd>
+          <EditRegionValue field={key} reserve>{key === 'seat' ? ER_SEATS.find(s => s.value === trip.seat).label : trip[key] || <span className="er-meta">Not set</span>}</EditRegionValue>
+        </dd></React.Fragment>)}</dl>
+      </EditRegionView>
+      <EditRegionForm>
+        {field => <>
+          <div className="er-sheet-head"><h2>Trip details</h2></div>
+          <dl className="er-sheet-grid">
+            <dt>Traveller</dt><dd><Field label="Traveller" required error={field.error('traveller')}><Input {...field('traveller')} autoComplete="off" /></Field></dd>
+            <dt>Email</dt><dd><Field label="Email" required error={field.error('email')}><Input {...field('email')} type="email" autoComplete="off" /></Field></dd>
+            <dt>Phone</dt><dd><Field label="Phone"><Input {...field('phone')} type="tel" placeholder="Add a phone number" autoComplete="off" /></Field></dd>
+            <dt>Seat</dt><dd><Field label="Seat"><Select {...field.value('seat')} items={ER_SEATS} /></Field></dd>
+          </dl>
+        </>}
+      </EditRegionForm>
+    </EditRegion>
+  </section>;
+}
+
+export default function App() {
+  const [fixture, setFixture] = React.useState('success');
+  const [mounted, setMounted] = React.useState({ fixture: 'success', epoch: 0 });
+  return <div className="er-demo">
+    <EditRegionExample key={mounted.epoch} fixture={mounted.fixture} />
+    <details className="er-harness">
+      <summary>Choose the next fixture</summary>
+      <div className="er-harness-controls">
+        <label>Save fixture<select value={fixture} onChange={event => setFixture(event.target.value)}>{ER_FIXTURES.map(name => <option key={name}>{name}</option>)}</select></label>
+        <Button onClick={() => setMounted({ fixture, epoch: mounted.epoch + 1 })}>Reset example</Button>
+      </div>
+    </details>
+  </div>;
+}
+```
+<!-- /example -->

package/dist/guidance/components/EmptyState/README.md

@@ -0,0 +1,66 @@
+# EmptyState
+
+What a list, board, search or page shows when it has nothing to show: a statement of what's empty, why, and one obvious next step.
+
+**Why it's sunk.** An empty region isn't a problem (that's `Alert`) and it isn't a settled container (that's `Card`): it's a space waiting to receive, where the record hasn't landed yet. So it's an opening, a well cut into the page (`surface-well`, `well`) with a dashed `line-control` rim, the same below-ground signal as an empty field or an armed `DropZone`: sunken things want content. Its actions are ordinary raised buttons standing in it, the primary one at level 2. Pointing at or tabbing to the primary action deepens the well to a trench and darkens its rim to `ink-muted`, showing where the record it creates will land. When it appears it sinks in from flush (`dur-travel-1`, `ease-sink`), the inverse of new content arriving lifted; it never pulses or loops, because an empty state must never beg.
+
+**Without height.** The rim is dashed while the region is empty, and the title says so in words; the icon is in `currentColor`. Under forced colours the rim is a dashed `CanvasText` border, like every sunk surface; with `contrast="more"` it turns solid.
+
+**Accessibility.** It's a `section` named by its title (`aria-labelledby`, an `h3` by default; set `headingLevel` to fit the page's outline) and described by its description. Actions are real buttons or links in the normal tab order: nothing is focused for you and nothing traps focus. When an empty follows something the person did (a filter or a search that matched nothing), pass `announce` and it's said politely once it appears: `true` says the title, a string says that.
+
+**You provide:** `title` (what's empty, as a statement), usually a `description` (why, or what will appear here), an `icon` (a Lucide line icon), and `action` (one primary `Button` whose label starts with a verb). Optionally `secondary` (a ghost `Button` or a link), `children` (extra content above the actions), `size="sm"` for a widget or a list, and `announce`.
+
+- Do name what's empty and what to do: "No gift ideas yet" and **Add idea**, not "Nothing here" and **OK**.
+- Do say which kind of empty it is in words: nothing yet, nothing matches, or you can't see it. Colour and height don't tell them apart.
+- Do give it one primary action at most; a second one is `secondary`, quieter.
+- Don't use it for an error that stopped content loading: that's a problem to fix, an `Alert`.
+- Don't raise it into a card, or make it the only thing on a page that's still loading: show a `Skeleton` until you know it's empty.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`EmptyState` as first used in its preview:
+
+```tsx
+import { Button, EmptyState } from 'altitude-design';
+
+<EmptyState icon={<Gift />} title="No gift ideas yet" headingLevel={2}
+  description="Ideas you save stay private to you until you share them."
+  action={<Button variant="primary">Add idea</Button>}
+  secondary={<Button variant="ghost">Import a list</Button>} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`two`, `lab`, `side`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Button, EmptyState } from 'altitude-design';
+
+const Gift = () => <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.75" strokeLinecap="round" strokeLinejoin="round"><rect x="3" y="8" width="18" height="4" rx="1" /><path d="M12 8v13M19 12v7a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2v-7M7.5 8a2.5 2.5 0 0 1 0-5C10 3 12 8 12 8s2-5 4.5-5a2.5 2.5 0 0 1 0 5" /></svg>;
+const Search = () => <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.75" strokeLinecap="round"><circle cx="11" cy="11" r="7" /><path d="M20 20l-3.5-3.5" /></svg>;
+const Bell = () => <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.75" strokeLinecap="round" strokeLinejoin="round"><path d="M6 8a6 6 0 0 1 12 0c0 7 3 9 3 9H3s3-2 3-9M10.3 21a1.94 1.94 0 0 0 3.4 0" /></svg>;
+export default function App() {
+  const [q, setQ] = React.useState('lamp');
+  return (
+    <div className="two">
+      <div><div className="lab">md · a page with nothing yet</div>
+        <EmptyState icon={<Gift />} title="No gift ideas yet" headingLevel={2}
+          description="Ideas you save stay private to you until you share them."
+          action={<Button variant="primary">Add idea</Button>}
+          secondary={<Button variant="ghost">Import a list</Button>} />
+      </div>
+      <div className="side">
+        <div><div className="lab">sm · a widget</div>
+          <EmptyState size="sm" icon={<Bell />} title="You're all caught up" description="New mentions and replies appear here." />
+        </div>
+        <div><div className="lab">sm · after a search</div>
+          {q ? <EmptyState size="sm" icon={<Search />} title={`No ideas match \u201C${q}\u201D`} announce="No matching ideas"
+            description="Try another word, or clear the search." action={<Button size="sm" onClick={() => setQ('')}>Clear search</Button>} />
+            : <p className="cap">Search cleared.</p>}
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+<!-- /example -->

package/dist/guidance/components/FeatureGate/README.md

@@ -0,0 +1,67 @@
+# FeatureGate
+
+A feature that needs another plan, shown to people on a plan that doesn't include it: "Export to CSV · Business", "SAML SSO · Enterprise", a menu item with a lock.
+
+**Elevation: locked, not disabled.** Disabled means "nothing happens": flush, `ink-faint`, skipped by the keyboard and often by screen readers. Then the people who rely on those never learn the feature exists, and `ink-faint` fails contrast. **A locked control does something**: it explains the plan and offers the upgrade. So it stays live:
+- it keeps the wrapped control's own build and normal ink;
+- **it lifts when pointed at** (hover is a promise);
+- it carries a lock and a flush `Badge` plate naming the plan.
+
+Pressing it opens a `Popover` (level 3): "Available on Business", what the plan adds, and "Upgrade to Business" as the popover's one primary action, with "Compare plans" if you give `compareHref`. When this person can't upgrade (`canUpgrade={false}`, not an admin), the button becomes "Ask an admin to upgrade to Business."
+
+**Accessibility.** The control stays a button with `aria-haspopup="dialog"`. **It's never `aria-disabled`.** Its name includes the requirement ("Export to CSV, requires Business plan"). It's reachable and activatable by keyboard, Escape closes the explanation, and focus returns to the control. The wrapped control's `onClick` and `disabled` are dropped: what it does while locked is explain.
+
+**Props:** `requires`; `description`; `onUpgrade`; `compareHref`; `canUpgrade` (default true); `children` (one control).
+
+**You provide:** the control, the plan it needs, what the plan adds, and where upgrading goes.
+
+```tsx
+<FeatureGate requires="Business" onUpgrade={() => openBilling('business')}
+  description="Export any view to CSV and schedule exports by email.">
+  <Button variant="secondary">Export to CSV</Button>
+</FeatureGate>
+```
+
+- Do keep locked features visible, so people know they exist.
+- Do say what the plan adds, not just its name.
+- Don't use `disabled` for a feature that needs another plan.
+- Don't hide the upgrade from people who can't buy it; tell them who can.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`FeatureGate` as first used in its preview:
+
+```tsx
+import { Button, FeatureGate } from 'altitude-design';
+
+<FeatureGate requires="Business" description="Export any view to CSV, and schedule exports by email." onUpgrade={() => setSaid('Opening plans…')} compareHref="#/billing/plans">
+  <Button variant="secondary">Export to CSV</Button>
+</FeatureGate>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`col`, `row`, `cap` are the preview page's own layout classes, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Button, FeatureGate } from 'altitude-design';
+
+export default function App() {
+  const [said, setSaid] = React.useState('');
+  return (
+    <div className="col">
+      <div className="row">
+        <Button variant="secondary">Export view</Button>
+        <FeatureGate requires="Business" description="Export any view to CSV, and schedule exports by email." onUpgrade={() => setSaid('Opening plans…')} compareHref="#/billing/plans">
+          <Button variant="secondary">Export to CSV</Button>
+        </FeatureGate>
+        <FeatureGate requires="Enterprise" description="Sign in with your identity provider (Okta, Azure AD, Google)." canUpgrade={false}>
+          <Button variant="ghost">SAML SSO</Button>
+        </FeatureGate>
+      </div>
+      <p className="cap" role="status">{said || 'Locked features keep their ink, lift when pointed at and are reachable by keyboard; pressing one explains the plan. Without permission to upgrade, it says to ask an admin.'}</p>
+    </div>
+  );
+}
+```
+<!-- /example -->

package/dist/guidance/components/Field/README.md

@@ -0,0 +1,46 @@
+# Field
+
+Pairs one control with its label, an optional hint and an error message that emerges beneath it.
+
+`Field` wires the `id`, `aria-describedby`, `required` and `invalid` props onto its single child, so the label, hint and error are announced with the control. Existing child description IDs are preserved and deduplicated with the rendered hint and error IDs. Both hint and error stay available when an error is shown; the control sinks to its invalid state, and the message emerges from under the field (`alt-emerge`, `dur-travel-2`) in `critical` with an icon.
+
+**You provide:** `label`, optionally `hint`, `error` (a string or node; falsy when valid) and `required`, and exactly one control as the child. A child’s `required` prop is preserved unless Field explicitly supplies one.
+
+- Do write the error as the fix: "Use at least 5 characters", not "Invalid input".
+- Don't show an error before the person has finished with the field; validate on blur or submit.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`Field` as first used in its preview:
+
+```tsx
+import { Field, Input } from 'altitude-design';
+
+<Field label="Workspace name" hint="Shown to everyone you invite.">
+  <Input defaultValue="Northwind Studio" />
+</Field>
+```
+
+The full preview, as rendered in Storybook and checked in CI (`grid` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { Field, Input } from 'altitude-design';
+
+export default function App() {
+  const [v, setV] = React.useState('acme');
+  const err = v.length < 5 ? 'Use at least 5 characters.' : null;
+  return (
+    <div className="grid">
+      <Field label="Workspace name" hint="Shown to everyone you invite.">
+        <Input defaultValue="Northwind Studio" />
+      </Field>
+      <Field label="URL slug" required error={err}>
+        <Input value={v} onChange={(e) => setV(e.target.value)} />
+      </Field>
+    </div>
+  );
+}
+```
+<!-- /example -->

package/dist/guidance/components/FilterBar/README.md

@@ -0,0 +1,132 @@
+# FilterBar
+
+Build and change a query as a row of conditions, each edited in place: “Status is In review”, “Assignee is Mara Quist”, “Updated between 1 Oct and 20 Oct”. Click a condition's field, operator or value to change just that part; add one with Add filter; remove one with its ×. Pair it with `DataTable`'s `relevance` so the results filter in place: matches rise, misses sink, and nothing reshuffles.
+
+```tsx
+const fields: FilterField[] = [
+  { key: 'status', label: 'Status', type: 'enum', options: statuses },
+  { key: 'assignee', label: 'Assignee', type: 'enum', options: people, searchable: true },
+  { key: 'updated', label: 'Updated', type: 'date' },          // before, after, between
+  { key: 'title', label: 'Title', type: 'text' },              // contains, does not contain
+];
+
+<FilterBar fields={fields} value={filters} onValueChange={setFilters} match={match} onMatchChange={setMatch} resultCount={visible.length} />
+<DataTable rows={rows} relevance={(r) => filters.length ? (matches(r, filters) ? 'match' : 'miss') : undefined} … />
+```
+
+The value is local query state, `{ id, field, operator, value }[]`, so there's no pending state: the application decides what each condition means (`matches` above). Dates are ISO `'YYYY-MM-DD'` strings; `between` takes `{ start, end }`.
+
+## Elevation
+
+- **The bar and its conditions** are part of what you're looking at, so they're on the ground: each condition is a plate stamped flush like a Badge, split into segments (field · condition · value · ×).
+- **A segment** opens a picker, so it lifts one level when pointed at or open (hover is a promise). Pickers float at level 3, as `Select`'s list does.
+- **A condition waiting for its value** keeps that segment as an opening: a small dashed well reading “Choose a value”. **Add filter** is an opening too, a dashed well that deepens to a trench under the pointer.
+- **A changed condition** is re-stamped (down 3px, settling), as a Badge whose label changes.
+- **Adding** a condition: the field list sinks, then the new condition's value picker rises. The two never move at once.
+
+Without height: the bar is a toolbar named “Filters” (or your `aria-label`); each condition is a group named by its sentence; each segment says what it is and what it does (“Value: In review. Change value”); the remove button names the condition; changes announce the new sentence and, with `resultCount`, the count (“Status is Done. 12 results”). Forced colours: conditions 1px, openings dashed, pickers 2px. `contrast="more"`: a hovered segment gets a 2px slab.
+
+## Keyboard
+
+The bar is one Tab stop (the toolbar pattern): ←/→ move between segments (mirrored in RTL), Home/End go to the ends. Enter, Space or ↓ opens a segment's picker; in a list, ↑/↓, Home/End and Enter choose; Escape closes it and leaves focus on the segment. Delete or Backspace on any segment removes its whole condition; focus moves to the next condition, else the previous, else Add filter. Text and number pickers apply on Enter; a date range applies once it has both ends.
+
+## Props
+
+| Prop | |
+|---|---|
+| `fields` | `{ key, label, type, options?, searchable?, operators? }`; operators default by type |
+| `value`, `onValueChange` | the conditions |
+| `match`, `onMatchChange` | `'all'` or `'any'`, shown as a segment once there are two conditions |
+| `resultCount` | announced after each change |
+| `createId`, `aria-label`, `className` | |
+
+`filterValueText(field, value)` gives a value as words, for your own summaries.
+
+## You provide
+
+What each condition means for your rows, and the results. Saved views and nested groups (A and (B or C)) aren't covered.
+
+## Do and don't
+
+- **Do** pair it with `relevance` so the result set changes in place.
+- **Do** keep fields to the handful people actually filter by; a long field list gets a search field automatically past eight.
+- **Don't** use it for a one-off search box: that's an `Input` in the table's toolbar.
+
+## Demo and verification
+
+The `FilterBar` section of `build/previews.txt` filters an issue table in place. `node checks/filter-bar.mjs` (from `build/`; `ALT_FIXTURE_ROOT` selects React 19 fixtures) covers the one Tab stop and arrow keys, opening and closing pickers, changing a value and an operator, the announcement with its count, re-stamping, Add filter with its field-then-value sequence and the empty value opening, text and date-range values, Match all/any, removal with focus repair, the paired table's relevance, and 320/960px layouts in both schemes under reduced motion, forced colours and `contrast="more"`.
+
+## Nested groups
+
+Automation rules, segments and advanced search need nested logic: "Plan is Pro **and** any of (Country is Germany, Seats > 50)". Pass a `FilterTree` and `nesting={2}`:
+
+```tsx
+<FilterBar fields={fields} nesting={2} value={tree} onValueChange={setTree} />
+// tree: { match: 'all', items: [Filter | { id, match: 'any', items: Filter[] }] }
+```
+
+A group is drawn as **a flush bracket on the ground**: a 1px `line-control` rule around its own conditions, with its own all/any switch (shown even with one condition) and its own Add filter. Groups are part of the record of the query, not live surfaces. Depth is capped at one level of groups so it never becomes a code editor, and groups follow the top level's conditions. "+ Add group" starts an "any of" group, and removing a group's last condition removes the group. `filterSentence(fields, tree)` reads the whole expression in words, and it's announced as it changes. `value: Filter[]` keeps working as before.
+
+<!-- example: generated from build/previews.txt by build/previews.mjs. Edit the preview, not this section. -->
+## Example
+
+`FilterBar` as first used in its preview:
+
+```tsx
+import { FilterBar } from 'altitude-design';
+
+<FilterBar aria-label="Filter issues" fields={FB_FIELDS} value={filters} onValueChange={setFilters} match={match} onMatchChange={setMatch} resultCount={count} />
+```
+
+The full preview, as rendered in Storybook and checked in CI (`fb-demo` is the preview page's own layout class, not Altitude's):
+
+```tsx
+import * as React from 'react';
+import { DataTable, FilterBar } from 'altitude-design';
+
+const FB_STATUSES = [{ value: 'todo', label: 'To do' }, { value: 'progress', label: 'In progress' }, { value: 'review', label: 'In review' }, { value: 'done', label: 'Done' }];
+const FB_PEOPLE = [{ value: 'mara', label: 'Mara Quist' }, { value: 'ines', label: 'Inés Ortega' }, { value: 'tobi', label: 'Tobi Adeyemi' }, { value: 'wen', label: 'Li Wen' }];
+const FB_FIELDS = [
+  { key: 'status', label: 'Status', type: 'enum', options: FB_STATUSES },
+  { key: 'assignee', label: 'Assignee', type: 'enum', options: FB_PEOPLE, searchable: true },
+  { key: 'updated', label: 'Updated', type: 'date' },
+  { key: 'title', label: 'Title', type: 'text' },
+  { key: 'points', label: 'Points', type: 'number' },
+];
+const FB_ROWS = [
+  { id: 'a', title: 'Search results page', status: 'review', assignee: 'mara', updated: '2026-10-21', points: 5 },
+  { id: 'b', title: 'Billing address form', status: 'progress', assignee: 'ines', updated: '2026-10-12', points: 3 },
+  { id: 'c', title: 'Search filters', status: 'todo', assignee: 'tobi', updated: '2026-09-30', points: 8 },
+  { id: 'd', title: 'Invoice emails', status: 'done', assignee: 'wen', updated: '2026-10-02', points: 2 },
+  { id: 'e', title: 'Onboarding checklist', status: 'review', assignee: 'ines', updated: '2026-10-19', points: 3 },
+];
+const fbTest = (row, f) => {
+  if (f.value === undefined || f.value === '') return true;
+  const v = row[f.field];
+  switch (f.operator) {
+    case 'is': return v === f.value; case 'is not': return v !== f.value;
+    case 'contains': return v.toLowerCase().includes(String(f.value).toLowerCase()); case 'does not contain': return !v.toLowerCase().includes(String(f.value).toLowerCase());
+    case '=': return v === f.value; case '>': return v > f.value; case '<': return v < f.value;
+    case 'before': return v < f.value; case 'after': return v > f.value; case 'between': return v >= f.value.start && v <= f.value.end;
+  }
+  return true;
+};
+export default function App() {
+  const [filters, setFilters] = React.useState([{ id: 'f1', field: 'status', operator: 'is', value: 'review' }]);
+  const [match, setMatch] = React.useState('all');
+  const matches = row => match === 'all' ? filters.every(f => fbTest(row, f)) : filters.some(f => fbTest(row, f));
+  const count = FB_ROWS.filter(matches).length;
+  return <div className="fb-demo">
+    <FilterBar aria-label="Filter issues" fields={FB_FIELDS} value={filters} onValueChange={setFilters} match={match} onMatchChange={setMatch} resultCount={count} />
+    <DataTable aria-label="Issues" rows={FB_ROWS} getRowId={r => r.id} relevance={r => filters.length ? (matches(r) ? 'match' : 'miss') : undefined}
+      columns={[
+        { key: 'title', header: 'Title' },
+        { key: 'status', header: 'Status', cell: r => FB_STATUSES.find(s => s.value === r.status).label },
+        { key: 'assignee', header: 'Assignee', cell: r => FB_PEOPLE.find(p => p.value === r.assignee).label },
+        { key: 'updated', header: 'Updated' },
+        { key: 'points', header: 'Points', align: 'end' },
+      ]} />
+  </div>;
+}
+```
+<!-- /example -->