@sableui/react 0.17.0 → 0.19.0

package/llms/tasks/building-a-tool.md

@@ -1,11 +1,15 @@
 # Task: building a tool (workspace register)
 
-An editor, a canvas app, a console — anything whose primary interaction is
-*operating on something* rather than reading and navigating.
+An editor, a canvas app, a console, or a records workspace (an issue tracker, a
+support queue, a pipeline): anything whose primary interaction is *operating on
+something* rather than reading and navigating.
 
 If the primary interaction is reading down a page, stop: you want
 [building-a-page.md](./building-a-page.md). A dashboard that scrolls is a page
-with dense content, not a workspace.
+with dense content, not a workspace. A tracker or inbox where people work
+through records one at a time, with the selected one open beside the list, is a
+workspace. Start that one from the `TrackerPage` pattern
+(`sable pattern TrackerPage --skeleton`) and read "A records workspace" below.
 
 ## The shell
 
@@ -29,12 +33,88 @@ hierarchy do not automatically transfer to dense operating surfaces.
 </Workspace>
 ```
 
+Every slot is optional; the body is always the one growing row. A bar that
+belongs to one column (a list's breadcrumbs and view switch, with the inspector
+running the full height beside it, as in Linear) is a `WorkspaceBar` placed first
+inside that column, not the `toolbar` slot.
+
 `Workspace` sets the compact density scope for its whole subtree. Nothing
 hardcodes a height: every control reads `--control-*`, so the same
 `<Button size="md">` is 40px on a page and 32px here. A `Dialog` opened from
 inside resets to comfortable, because a modal is a page-register surface even
 when a tool launched it.
 
+## A records workspace
+
+The shape of an issue tracker, a support queue or a CRM pipeline. Every piece
+below exists, so the build is composition; `sable pattern TrackerPage
+--skeleton` has the whole tree.
+
+```tsx
+<Workspace statusBar={<StatusBar>…</StatusBar>} bottomNav={<BottomNav>…</BottomNav>}>
+  <PanelGroup>
+    <Panel label="Navigation" width={220} narrow="sheet" side="left"
+           open={narrow ? navOpen : true} onOpenChange={setNavOpen} scroll={false}>
+      <Sidebar variant="inline">
+        <SidebarHeader><SidebarBrand mark={…} label="Studio" />{search}</SidebarHeader>
+        <SidebarNav>
+          <SidebarItem icon={…} label="Inbox" badge={…} />
+          <SidebarGroup label="Workspace">{items}</SidebarGroup>
+        </SidebarNav>
+        <SidebarFooter>
+          <Menu>
+            <MenuTrigger render={<SidebarAccount avatar={<Avatar size="2xs" … />} label="Emma Lee" detail="Studio" />} />
+            <MenuContent side="top" align="start">{settings, appearance, sign out}</MenuContent>
+          </Menu>
+        </SidebarFooter>
+      </Sidebar>
+    </Panel>
+    <WorkspaceCanvas className="flex flex-col">
+      <WorkspaceBar><Breadcrumbs>…</Breadcrumbs></WorkspaceBar>
+      <WorkspaceBar><Tabs><TabsList variant="pill">…</TabsList></Tabs></WorkspaceBar>
+      {filters}
+      <DataTable groupBy={(r) => r.status} groups={…} isRowSelected={…} onRowClick={…} />
+    </WorkspaceCanvas>
+    <Panel label="Details" width={320} narrow="sheet" open={selected != null}
+           onOpenChange={(o) => !o && setSelected(null)} scroll={false}>
+      <PanelSection title="Properties"><PropertyRow label="Status">…</PropertyRow></PanelSection>
+    </Panel>
+  </PanelGroup>
+</Workspace>
+```
+
+The decisions that keep it one system:
+
+- **One grid down the rail.** SidebarBrand, SidebarItem, SidebarGroup and
+  SidebarAccount share the icon and label columns, and inside the compact scope
+  they take 32px rows on their own. Do not drop SideNav, an Entity or a stack of
+  ghost Buttons into the rail: each brings its own insets.
+- **The account is one row and a menu.** Settings, appearance (light, dark,
+  system) and sign-out go in the SidebarAccount's menu, not in a Settings button
+  above it or a badge beside it. Its detail line ("Studio · Demo") carries what a
+  badge would.
+- **One table, grouped.** Rows grouped by state are one `DataTable` with
+  `groupBy`: one header, columns that line up, a count and an add action per
+  group. Not one table per group inside Collapsibles.
+- **The inspector renders once.** `Panel narrow="sheet"` docks it on a desktop
+  and makes it a Sheet below `lg`. Not a media-query hook plus a second copy in a
+  Sheet. The nav rail does the same from the left, and fills its sheet.
+- **Reading inside the tool is page-sized.** An overview, a description, notes or
+  a docs tab goes in `<Density value="comfortable">`, or its prose renders at the
+  11px chrome tier.
+- **A view switch in chrome is a pill.** `TabsList variant="pill"`: its fill takes
+  the compact `--button-radius`, about 5px, so it reads as a segment. Underline
+  tabs are the page-section idiom.
+- **Ship both modes, and a way to switch.** The look is a preset with light and
+  dark; SableThemeProvider applies it, and the account menu or a Settings dialog
+  holds the mode switch. A tool asked to be compact and technical takes
+  `type-base` (13 or 14) in the preset, which rebuilds the whole type scale,
+  instead of per-tier overrides.
+- **State has a shape.** A status with more than on and off (partly done, in
+  review) can be an app-owned glyph, but give it a label (`role="img"`,
+  `aria-label`) and colour it from the palette (`var(--yellow-500)`) so it
+  follows the mode.
+
 ## What you will need, and what to avoid reaching for
 
 | you want | use | NOT |
@@ -46,6 +126,17 @@ when a tool launched it.
 | a colour property | `ColorField` | `<input type="color">` — OS dialog, ignores the theme, wrong size |
 | ambient document facts | `StatusBar` | a toolbar — status is glanced at, not operated |
 | chrome typography | `text-ui-md` / `-sm` / `-body` / `-section` / `-micro` / `-num` | `text-body-*` — page tiers, ~1/3 too large here |
+| a title in a panel | `text-title-lg` (14px `text-ui-title` in compact) | a heading tier, or a page-tier override on `:root` |
+| a top bar over one column | `WorkspaceBar` first in the column, with `Breadcrumbs` | a hand-built `<header>` with `/` spans |
+| nav groups in a rail | `SidebarGroup` | `SideNav` + `SideNavGroup` — another set of columns |
+| the account at the foot of a rail | `SidebarAccount` as a `MenuTrigger` | an Entity + a Settings Button + a Badge |
+| a view switch in a bar | `TabsList variant="pill"` | underline tabs (page idiom), a hand-built segmented row |
+| rows grouped by state | `DataTable groupBy` + `groups` | a DataTable per group in Collapsibles |
+| a date property | `DatePicker size="xs"` | `<input type="date">` — OS format, wrong size |
+| a person in a row | `Avatar size="2xs"` / `"xs"`, `AvatarGroup` for several | a class on Avatar to shrink it |
+| a project or workspace mark | `Avatar shape="square" tone="…"` | a tinted `<span>` |
+| an inspector on a phone | `Panel narrow="sheet"` | a media-query hook and a second render in a Sheet |
+| a reading tab | `<Density value="comfortable">` | prose in chrome tiers |
 
 ## Menus, selects and popovers adapt on their own
 
@@ -104,9 +195,12 @@ a modal is its own surface rather than part of the control that opened it.
   the nesting reads inverted. Use `treeIndent(depth)`; never hand-write an inset.
 - **No pills in chrome.** The compact scope flattens `--button-radius` to ~5px —
   one of two page-register rules the workspace register deliberately reverses.
+  `TabsList variant="pill"` takes that radius too, so in a bar it is a segment.
 - **Drag with window listeners, not `setPointerCapture`.** Capture throws for an
   inactive pointer id and the throw aborts the handler mid-gesture, silently.
-- **An unmapped `<Icon name>` renders nothing.** No error. Check the contract.
+- **An unmapped `<Icon name>` renders nothing.** A development build warns and
+  names the nearest names, and Lucide or Heroicons spellings resolve, but check
+  with `sable icon <name>` before you write one, through a wrapper too.
 
 ## Verify
 
@@ -136,6 +230,8 @@ and distinguish observed behavior from untested claims.
 ## Read next
 
 - `DESIGN.md → Registers` — doctrine, measured numbers, the two reversals
+- `sable pattern TrackerPage --skeleton` — the records workspace, whole
 - `llms/components/workspace.md`, `panel-group.md`, `panel-section.md`,
-  `tree.md`, `scrub-field.md`, `status-bar.md`, `color-field.md`
+  `sidebar.md`, `data-table.md`, `tree.md`, `scrub-field.md`, `status-bar.md`,
+  `color-field.md`
 - `llms/reference/token-intent.md` — which token to reach for

package/llms/tasks/building-with-sable.md

@@ -46,7 +46,13 @@ for each recognizable element with `sable search "<need>" --json`; inspect the
 matching `component <Name> --props` and `--examples` before implementation.
 Use Sable's composed anatomy and supported variants. A hand-built button, field,
 menu, dialog, table, or card that imitates a shipped component violates the contract.
-That binds behaviour and parts, not layouts. Results marked ◇ (patterns, blocks,
+That binds behaviour and parts, not layouts. Search a part by its plain name and
+its role before writing a class or component for it (`sable search breadcrumb`,
+`sable search "top bar"`); exported parts such as `PropertyRow` and `WorkspaceBar`
+are listed by name, and `sable component <Part>` answers with their entry. When a
+part's look or size disagrees with the design, use its variant or prop, or report
+the missing variant; never rebuild it. `sable icon <name>` says whether an icon
+exists. Results marked ◇ (patterns, blocks,
 and compositions such as MediaTile) are references: use one when its layout fits
 the brief, otherwise compose your own from Sable's parts. The brief's signature
 surfaces, where the product's identity lives, are designed from its direction.
@@ -65,8 +71,10 @@ implement genuinely app-specific structure without creating parallel controls.
 
 ## Finish the working product
 
-Run `sable doctor`, `sable lint <source paths> --json`, and the project's build/type
-checks. Inspect desktop/mobile layouts, operate the primary task and recovery
+Run `sable check <source paths>` (doctor, lint and grade) and the project's
+build/type checks. Answer each Rebuilt parts note in the reuse inventory, and fix
+a colour-modes warning: app colours live in a preset with both modes, and a
+`ThemeSwitcher` under `SableThemeProvider` lets the user review each. Inspect desktop/mobile layouts, operate the primary task and recovery
 path, and check keyboard focus, fonts, reduced motion, and meaningful states.
 Use [reviewing-a-design.md](./reviewing-a-design.md),
 [reviewing-a-journey.md](./reviewing-a-journey.md), and

package/llms/tasks/creating-a-preset.md

@@ -21,6 +21,15 @@ are optional: set `page-inset` and the `region-*` caps (`form`, `feed`, `content
 `wide`, `full`) in `tokens.shared` only when the direction calls for a different
 page proportion, and keep each cap's role.
 
+Overall type size is one token. Sable's scale is built on a 16px base;
+`"type-base": "14"` (or 13) in `tokens.shared` rebuilds every page tier at that
+base, keeping their ratios, and spacing follows because the rhythm is derived
+from body size. Use it when the direction is denser or more technical than the
+bundled presets (a tracker, a console, "like Linear"). Don't rescale the root
+font-size, and don't override tiers one by one to the same end. Retune a single
+tier only when that tier's role changes. Inside a Workspace the chrome already
+uses its own compact `ui-*` tiers.
+
 ```bash
 pnpm exec sable preset --template
 pnpm exec sable preset --check .sable/presets/clay.json --json

package/llms/tasks/getting-started.md

@@ -79,15 +79,22 @@ In a monorepo where Sable belongs to one workspace package, run setup in that
 package with `--root` naming the repository root (for example
 `pnpm --filter web exec sable setup --agent --root ../..`); the entries go
 there and resolve Sable through the package.
+Setup also adds a short managed block to the project's `AGENTS.md` and
+`CLAUDE.md`, the instructions an agent reads on every task, so a UI request
+goes through the skill even when it doesn't mention Sable. Only the text between
+its `<!-- sable:begin -->` and `<!-- sable:end -->` markers is Sable's;
+`--no-instructions` skips it.
 Each entry resolves `skills/sable/SKILL.md` from the installed package, so package
 upgrades also update the workflow. Other agents can read that file directly.
 Use `$sable build <idea>`, `inspire <references>`, `audit <target>`, or
 `polish <target>` in Codex; use `/sable` with the same modes in Claude Code or
 Cursor. `create` is a build alias. These are agent modes, not shell commands.
 
-Upgrade with `pnpm update @sableui/react --latest`, then
-`pnpm exec sable setup --agent --update`. Setup only replaces managed files
-that have not been locally edited; `--dry-run` checks without writing. Keep
+Upgrade with `pnpm exec sable upgrade`: it updates the package, then runs the
+new version's `init`, which refreshes the skill entries and the instructions
+block and checks the wiring. From 0.17 or earlier, which has no `upgrade`, run
+`pnpm update @sableui/react --latest` and then `pnpm exec sable init` once.
+Setup only replaces managed files that have not been locally edited; `--dry-run` checks without writing. Keep
 project preferences in project instructions. Package installation alone does not
 change agent settings. See [building-with-sable.md](./building-with-sable.md),
 [creating-a-preset.md](./creating-a-preset.md), and

package/llms/tasks/using-presets.md

@@ -102,8 +102,7 @@ saved file. Replace, don't add beside:
 ## Upgrade the package and skill
 
 ```bash
-pnpm update @sableui/react --latest
-pnpm exec sable setup --agent --update
+pnpm exec sable upgrade
 pnpm exec sable preset --check .sable/presets/clay.json --json
 pnpm exec sable doctor
 ```