@sableui/react 0.17.0 → 0.19.0

package/AGENTS.md

@@ -153,6 +153,11 @@ 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>`,
@@ -160,9 +165,11 @@ Use `$sable build <idea>`, `inspire <references>`, `audit <target>`,
 Claude Code or Cursor. `create` is a build alias. `fix` takes the short path for
 one scoped defect and escalates to `polish` when the change grows. 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](./llms/tasks/building-with-sable.md),
 [creating-a-preset.md](./llms/tasks/creating-a-preset.md), and

package/CHANGELOG.md

@@ -1,5 +1,240 @@
 # What's new
 
+## 0.19.0
+
+A compact work tracker, built on Sable by an agent, rebuilt about thirty parts
+Sable already ships. Every gap behind those rebuilds is fixed here: a lookup
+that couldn't find parts, checks that couldn't see the app's own CSS, and
+components that had no variant for a dense layout.
+
+- **`--type-base` rebuilds the type scale at another base size.** Set
+  `--type-base: 14` (a unitless px number; the default is 16) on `:root`, a
+  `[data-sable-theme]` scope or in a preset's `tokens.shared`, and every page
+  tier scales by `base / 16`, including each theme's own tier values and any
+  per-tier override. Spacing follows, because the baseline step is derived from
+  body size. The workspace `ui-*` tiers stay absolute px, and compact still only
+  ever shrinks text. Don't change the root font-size to get a denser UI: it
+  scales every rem in the app, not just the type.
+- **New `text-ui-title`** (14px / 600 / 20px leading, tokens
+  `--type-ui-title-*`). Inside a compact scope `text-title-lg` maps to it. It
+  used to collapse to 12px, the same size as the description under it.
+- **A comfortable scope inside a compact one gets page type back.**
+  `<Density value="comfortable">` around a reading view (an overview, notes,
+  docs) in a Workspace used to reset the control sizes but not the text, which
+  stayed at 11px.
+- **Tables follow density.** TableHead's height, TableCell's padding and the
+  table's text tier read density tokens. In a compact Workspace that is a 28px
+  head, 32px rows and `text-ui-body`, with no consumer CSS.
+- **Compact on a touch screen uses the comfortable control ladder.** Under
+  `pointer: coarse` the 24/28/32 ladder, measured from mouse-driven editors,
+  becomes 28/32/40.
+- **Workspace's body is its only stretching row.** The grid always assumed a
+  toolbar, so a Workspace without one put the body in the auto track and
+  clipped the status bar. The root is now a flex column, which holds for every
+  combination of slots. Migration: drop any `grid-template-rows` override on
+  the Workspace root.
+- **Workspace and Panel on small screens.** Workspace takes `bottomNav`, a row
+  shown below `lg`. Panel takes `narrow="sheet" | "hidden"` with `open`,
+  `onOpenChange`, `side` and `below`: below the breakpoint an inspector becomes
+  a Sheet and its content renders once. A Sidebar moved into that sheet fills
+  it. New `useMediaQuery` and
+  `useBelowBreakpoint` hooks are exported. A WorkspaceBar can also sit at the
+  top of one column, so the inspector runs the full height beside it, as in
+  Linear.
+- **DataTable groups rows.** `groupBy`, `groups` (each with an icon, an action
+  and `defaultExpanded`), `collapsible` and controlled `expandedGroups` give
+  one table with one header and a header row per group that carries a toggle,
+  a count and an add action. Sorting applies within each group, and select-all
+  acts on the visible rows.
+- **The Sidebar rail is one grid, at either density.** New `SidebarGroup`
+  labels a run of items, so a rail no longer has to borrow SideNav for its
+  groups. New `SidebarAccount` is the account row: the avatar in the icon slot,
+  the label and one detail line on the label column, and an up-down chevron.
+  Make it the account Menu's trigger and put Settings, appearance and sign-out
+  in the menu. Inside a compact scope such as a Workspace, the whole rail takes
+  32px rows and 20px icons, and the header matches the chrome bar's height.
+  Before this, a tool's footer mixed a ghost Button, an Entity patched with
+  `[--entity-py:0]` and a Badge, and the rail's icons and labels landed on four
+  columns. DashboardPage uses the new parts.
+- **Underline tabs in a WorkspaceBar sit on the bar's hairline.** They used to
+  draw a second, shorter rule that stopped after the last tab, with the mark
+  floating above the bar's edge. Tabs guidance now steers a view switch in tool
+  chrome to `variant="pill"`.
+- **`MenuSubmenuTrigger` takes `icon`**, as MenuItem does, so a submenu row
+  lines up with the icon rows around it.
+- New icon `chevron-up-down` (Lucide's `chevrons-up-down` resolves to it).
+- **Avatar:** `2xs` (20px) and `xs` (24px), `shape="square"` for a workspace,
+  project or org mark, and a palette `tone` for the initials fallback.
+- **DatePicker:** `size="xs"` for a property row, and `formatOptions`
+  (`Intl.DateTimeFormatOptions`) for the trigger text.
+- **CollapsibleIndicator needs no setup.** It no longer needs the
+  `group/collapsible` class on its trigger. New `direction="end"` gives a side
+  caret that turns down on open, mirrored in RTL.
+- **Icons:** new `users`, `archive`, `kanban`, `sliders`, `help` and `sidebar`.
+  About 90 Lucide and Heroicons names now resolve to Sable's (`settings` →
+  `gear`, `menu` → `bars`, `check-circle` → `circle-check`). A development
+  build warns once for a name the set can't draw, and names the nearest ones.
+- **A toast clears an open side sheet on a phone.** It used to move to the
+  top, over the sheet's close button. It now sits below the sheet's header
+  inset, tunable with `--sable-sheet-top-inset`.
+- **Workspace surfaces derive in oklab.** The canvas, panel, field, hairline
+  and shell-ground mixes used `color-mix(in oklch, …)`. On hex colours Chrome
+  resolves that to a colour with no hue, painted as 0°: a brown cast on a cool
+  graphite preset's canvas. Bundled themes write oklch and never showed it, but
+  presets and apps write hex. The heatmap's empty cell moves to oklab too.
+- **`--nav-height` is defined** (56px). AppShell's bottom padding read it with
+  no fallback, so the padding was dropped.
+- **Agent tooling finds parts.** `sable component PropertyRow` (or `Panel`,
+  `WorkspaceBar`, `CollapsibleTrigger`) answers with the parent component;
+  it used to be ERR_UNKNOWN_COMPONENT. Search indexes parts, and an exact name
+  ranks first. New `sable icon [name]` lists the drawable names and resolves
+  aliases.
+- **`sable check` sees rebuilt parts.** A new "Rebuilt parts" block reads class
+  names in the app's markup and the app's own CSS. It flags a breadcrumb, top
+  bar, property row, status dot or avatar stack built by hand; fixed bar and row
+  heights; selectors reaching into Sable's components; and a chevron rotated on
+  `aria-expanded`. Icon names passed through an app's own wrapper are checked
+  too. These are notes, and the skill asks the agent to answer each one.
+- **`sable check` warns on one-mode colour.** Colour tokens set for light with
+  no dark value now produce a warning, and an app with no ThemeSwitcher gets a
+  note. The skill now ships both modes, as a preset with a ThemeSwitcher under
+  SableThemeProvider, unless the brief rules one out.
+- **New pattern: `TrackerPage`.** A records workspace in the tool register,
+  the reference shape for an issue tracker, a support queue or a pipeline. It
+  has a Sidebar rail of grouped views ending in an account menu (with
+  appearance), Breadcrumbs and pill Tabs in WorkspaceBars, a filter row, one
+  grouped DataTable, a docked inspector of PanelSection property rows with a
+  pinned comment form, and a comfortable reading tab. Below lg the rail and the
+  inspector become sheets and BottomNav takes the last row. `sable pattern
+  TrackerPage --skeleton` has the tree. Pattern metadata takes `keywords` now,
+  so "issue tracker", "like Linear" or "support queue" lands on the shell first.
+- **Guidance for a records workspace.** `building-a-tool` now covers the
+  shape of an issue tracker, a support queue or a pipeline: the shell, the
+  decisions that keep it one system (one rail grid, the account as a row and a
+  menu, one grouped table, an inspector that renders once, page-sized reading
+  tabs, pill tabs in chrome, both modes, `type-base` for "compact") and a
+  "you want / use / not" table built from what a real build rebuilt. The skill
+  routes a tool, tracker or "like Linear" brief there; `building-a-page` points
+  trackers to it; `creating-a-preset` explains `type-base`.
+- **`sable check` notes compositions another part does better:** SideNav
+  inside a Sidebar, an Entity or Badge in the rail's footer, a DataTable per
+  group inside Collapsibles, underline tabs in a WorkspaceBar, and a native
+  date input. Notes, never failures. On the build that prompted this release
+  they flag four drifts, each at its line.
+- **The skill searches before it builds.** It looks up a part by its plain name
+  and role before writing any class or component for it. A style or layout
+  disagreement means using the variant or prop, or reporting the missing
+  variant, never rebuilding the part.
+- Migration: run `sable sources --write` after upgrading. Panel now imports
+  Sheet, so the generated sources file is stale until it is rewritten, and
+  doctor says so.
+
+## 0.18.0
+
+A year at a glance: the contribution graph, built so a phone, a keyboard and a
+screen reader can all read it.
+
+- **New: `ActivityHeatmap`.** A calendar heatmap: one value per day as a grid
+  of weeks by weekdays — the GitHub contribution graph, for any daily measure.
+  Pass days as `"YYYY-MM-DD"` with a value (or a date-to-value map); levels
+  come by quartile, as GitHub's do, unless a day brings its own. `categories`
+  colour days by source instead of intensity, and `mergeActivity` tags each day
+  with its source or `both`. The grid is a real `role="grid"` table with one
+  tab stop: arrows step a day or a week, each cell is named with its date and
+  value, and the tooltip shows on hover, focus and tap. It fills the width down
+  to `size`; narrower, the weeks scroll sideways and open on the latest, while
+  the weekday labels stay outside the scroller. Days are read as calendar days,
+  never instants, so no time zone shifts one. Prompted by a consumer site that
+  hand-built one from 371 buttons and broke on phones.
+- **New: `@sableui/react/adapters/github`.** `fromGitHubGraphQL` and
+  `fromGitHubContributionsApi` turn GitHub's contribution data into heatmap
+  days. Pure transforms: fetch on your server and pass the result in.
+- **New: `activityLevels` and `activityGrid`.** The level scale and the week
+  grid behind the heatmap, exported for a custom legend, a summary stat or
+  another layout.
+- **`ChartTooltipContent` with no rows** draws just its label, so a caller's
+  own content sits on the standard tooltip card.
+- **Layout primitives take `className` over their own layout.** Row, Stack,
+  Grid, Columns, Col, Center, Region, Page, Bleed, AspectBox, Spacer, SplitPane
+  and GridOverlay set `display`, direction, alignment, gap, inset, cap, ratio and
+  size inline, and an inline declaration beats every utility, so
+  `<Row className="max-lg:hidden">` or `hidden md:flex` silently did nothing.
+  The grid and split rules in `styles.css` were unlayered too, so `hidden` lost
+  to them whatever its specificity. Layout now lives in classes merged through
+  `cn()`, with prop values passed as CSS variables those classes read, and the
+  layout rules sit in `@layer components`. A utility in `className` wins at any
+  breakpoint (`max-md:flex-col`, `md:gap-6`, `lg:grid-cols-3`); the props work
+  as before. Migration: a `className` that used to be ignored on a primitive now
+  applies, and a test reading `style.gap` or `style.maxWidth` reads
+  `--sable-row-gap`, `--sable-region-max` and the like instead.
+- **`PageHeader size="lg"`.** A display-size page title for an editorial page
+  (a personal site, a marketing page, an article index): `text-display-lg` over
+  a `text-body-lg` lede capped at the prose measure. `md`, the default, is
+  unchanged. Keep `lg` off app routes: display type stays out of product chrome.
+- **`SectionHeader size="lg"`.** The major-section tier, `text-heading-2` over a
+  `text-body-md` description, for an editorial page's sections under a
+  `PageHeader size="lg"`. It stops at heading-2 because heading-1 is the page
+  title's, one per route. Actions stay centred on the title's first line at
+  every size.
+- **`SearchInput` takes `size`** (`md` | `sm` | `xs`), on the same ladder as
+  Input, Select and Combobox. `sm` is the toolbar field on `--control-sm`, `xs`
+  the inset tool-panel field; the magnifier, padding and clear button scale with
+  it and stay centred. Before, it was fixed at 40px and matched nothing in a
+  toolbar.
+- **`Pill size="lg"`.** A 32px chip on `--control-sm`, the toolbar height Button
+  `sm` and SearchInput `sm` share, so a filter row beside a search field is one
+  height in either density.
+- **`MediaImage` and `MediaTile` take a crop focus.** `position` sets where the
+  image sits in its frame and takes any CSS `object-position` value
+  (`"35% 50%"`, `"top"`), beside `fit`. MediaTile forwards it to its cover.
+- **Dialogs return focus to whatever opened them.** `Dialog`, `AlertDialog` and
+  `Sheet` record the element focused when `open` turns true and send focus back
+  to it on close, with or without a trigger. Before, a dialog opened from your
+  own button lost focus to the page whenever a field inside autofocused,
+  CommandMenu's included. An explicit `finalFocus` still wins.
+- **`DialogContent keepMounted`.** Keeps a closed dialog's content mounted and
+  hidden, so a half-written draft survives Esc or a stray click and is still
+  there on reopen. Opt in for drafts the user may come back to.
+- **Eight more icon names.** `briefcase`, `layers`, `microphone`, `video`,
+  `broadcast`, `newspaper`, `palette` and `gamepad` join the contract, mapped
+  in the Reicon set, for a portfolio that imported reicon-react directly for
+  its work, audio, video, live, press, design and games sections.
+- **Setup writes the skill into the instructions every task reads.** A skill
+  loads only when a request names it, so "add a pricing page" in a wired app
+  could skip it: the agent saw Tailwind and a stylesheet, wrote its own Button
+  and Modal, and put Sable's tokens on them. `sable setup --agent` (and `sable
+  init`) now also writes a short managed block into `AGENTS.md` and
+  `CLAUDE.md` that sends every UI request through the skill. Only the text
+  between its `<!-- sable:begin -->` and `<!-- sable:end -->` markers is
+  Sable's; `--no-instructions` skips it. **Migration:** from 0.17, run
+  `pnpm update @sableui/react --latest` then `pnpm exec sable init` once; after
+  that, `sable upgrade` does both.
+- **New: `sable upgrade`.** One command to update: installs the latest
+  `@sableui/react` with the project's package manager, then runs the new
+  version's `init`, so the skill entries, the instructions block and the
+  checks are the new release's. Safe on an app that already works.
+- **"Move this app onto Sable" is a request the skill understands.** It checks
+  the app, shows the swaps once, asks, and moves them a screen at a time; it
+  never starts a new build. `init` says so when an app's UI barely uses Sable,
+  and its next step for a ready app is now a plain request, not mode syntax.
+- **Adoption, in `sable check`, `sable grade` and `sable doctor`.** How much of
+  the UI composes Sable, which app-built components do by hand what a Sable
+  component already does (a `Modal` → Dialog, a `SearchBar` → SearchInput,
+  behaviour first), and what the app already stands on: nothing, its own
+  primitives, or another library. Never a failure. `check` lists the swaps and,
+  when adoption is low, makes "ask the user about moving onto Sable" the first
+  review step; `doctor` warns. The skill and `sable docs auditing-an-app` say
+  how to put the choice to the user, more firmly when the app has no
+  foundation of its own.
+- **The skill triggers on any UI work in a Sable app.** Its description now
+  says so, even when the request doesn't mention Sable.
+- **`sable init --hook`.** Adds the Claude Code Stop hook that runs `sable
+  check` before a task can end. Run in a terminal, init asks; `--no-hook`
+  doesn't.
+- **`CodeBlock wrap`.** Wraps long lines instead of scrolling them, for prose
+  in a code face: a prompt to paste into an agent, a log line. Code keeps
+  scrolling.
+
 ## 0.17.0
 
 Knowing where you are: a rail that follows a long read, and an approval

package/README.md

@@ -69,7 +69,7 @@ pnpm add @sableui/react
 pnpm exec sable init        # or: npx sable init — once the package is installed
 ```
 
-`init` reads your package manager from the lockfile and your framework from the project. It installs what is missing (React, Tailwind and its build plugin), puts the CSS imports below in order, adds React dedupe and the Tailwind plugin to a Vite config, loads the fonts, mounts `IconProvider` in a Vite starter's entry, installs the agent skill (`sable setup --agent`), then runs `sable doctor`. Anything it cannot change safely — an unfamiliar config, a Next.js layout — it prints as the exact snippet and the file it belongs in. Vite and Next.js (App Router) get every step; other setups get the packages and the stylesheet. `--dry-run` shows every change first; `--no-agent` skips the skill. Already set up? `sable doctor --fix` applies the same fixes to whatever doctor flags.
+`init` reads your package manager from the lockfile and your framework from the project. It installs what is missing (React, Tailwind and its build plugin), puts the CSS imports below in order, adds React dedupe and the Tailwind plugin to a Vite config, loads the fonts, mounts `IconProvider` in a Vite starter's entry, installs the agent skill and its block in `AGENTS.md` / `CLAUDE.md` (`sable setup --agent`), offers the Claude Code Stop hook when you run it in a terminal, then runs `sable doctor`. Anything it cannot change safely — an unfamiliar config, a Next.js layout — it prints as the exact snippet and the file it belongs in. Vite and Next.js (App Router) get every step; other setups get the packages and the stylesheet. `--dry-run` shows every change first; `--no-agent` skips the skill. Already set up? `sable doctor --fix` applies the same fixes to whatever doctor flags.
 
 The steps below are what `init` does, for doing it by hand or checking its work.
 
@@ -213,6 +213,11 @@ 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
@@ -225,9 +230,11 @@ server: `claude mcp add --transport http sable https://www.sableui.com/api/mcp`
 and `docs`, give the CLI's answers from the published package, at the version
 the agent passes or the latest. Once Sable is installed, the CLI is the default.
 
-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](./llms/tasks/building-with-sable.md),
 [creating-a-preset.md](./llms/tasks/creating-a-preset.md), and