@sableui/react 0.10.0 → 0.12.0

package/AGENTS.md

@@ -51,10 +51,14 @@ These are short on purpose. Each links to a foundations doc with the full vocabu
 
 Pick a theme as a starting point, then override tokens on top of it. Every token a theme sets can be reset by the app on `:root` (or any subtree) after the theme CSS loads — radius, density, type scale, motion scale, accent — and components follow, because they only read tokens. The docs site's **Customize** panel does exactly this live and exports the result as CSS; paste it after your Sable imports. Retrieve the overridable set with `npx sable token --list`. When you retune a filled role (`--primary`, `--sidebar-primary`, `--highlight`, `--destructive`, `--success`, `--tone-warning`, `--tone-info`), check the label on it: `sable lint` measures the pair against the installed theme and suggests one that reads. If the pair is a deliberate brand choice, keep it with `/* design-lint-disable-next-line label-contrast -- <reason> */`. Status colours have a second token for the colour drawn on a surface — `--destructive-text`, `--success-text`, `--tone-warning-text`, `--tone-info-text` — which `text-`, `border-` and `ring-<status>` read; only `bg-<status>` reads the fill. Retune both.
 
+When a component doesn't do something you need — be a link, carry a control, take a key, offer @mentions or /commands — read `sable docs extending-a-component` before restyling or copying it: `render`, slots, controlled state and refs, `useCaretTrigger` + `CaretMenu`, and how to tell a library gap from app-owned work.
+
 ## Wire it up
 
 The machine-readable version of this section is the `consume` block in `registry.json`.
 
+**Start with `sable init`.** After `pnpm add @sableui/react`, run `pnpm exec sable init` (`npx sable init` once the package is installed — never before, when `npx sable` would fetch an unrelated package) from the app root. It runs steps 2–5 and 7 below: installs missing packages with the project's package manager, puts the CSS imports in order, adds dedupe and the Tailwind plugin to a Vite config (or a PostCSS config for Next.js), loads the fonts, mounts `IconProvider` in a Vite starter's entry, installs the agent skill, and finishes with `sable doctor`. What it cannot change safely it prints as a snippet with the file it belongs in; apply those, then run `sable doctor` again. `--dry-run` previews every change. In an app that is already wired, `sable doctor --fix` applies the same fixes to whatever doctor flags. The numbered steps are the manual route and what `init` checks against.
+
 1. **Install** from npm: `pnpm add @sableui/react` (or the project's package manager). No registry configuration or token is needed. Sable depends on no router, data or form library, and keeps whatever the project already uses: links, menus and nav items take any router's link through `render` (`render={<Link to="/inbox" />}` is TanStack Router's or React Router's `Link` alike). For a blank-slate app, the suggested stack is Vite + TypeScript with TanStack Router, TanStack Query, TanStack Form for forms with validation logic, and TanStack Table once a table outgrows `DataTable` (`sable docs tables-with-tanstack`).
 2. **Dedupe React** in the bundler (`resolve.dedupe: ["react","react-dom"]`) — Base UI must not resolve a second React, or you get an "invalid hook call" blank page.
 3. **CSS, in order:** `@import "tailwindcss";` → `@import "@sableui/react/styles.css";` → `@source "<node_modules>/@sableui/react/dist/**/*.{js,mjs}";` so Tailwind scans the package's classes. That ships every component's classes (about 32 KB gzipped); before shipping, `sable sources --write src/sable-sources.css` lists just the modules the app imports, imported in place of that `@source`, and `sable check` fails when it goes stale.
@@ -73,7 +77,8 @@ The machine-readable version of this section is the `consume` block in `registry
    npx sable pattern SettingsPage --skeleton     # composition tree, fixtures stripped
    npx sable block --list                        # section-sized blocks: cards, forms, lists
    npx sable component DataTable --props
-   npx sable search "empty state"                # across components, patterns, layout, tokens, docs
+   npx sable search "empty state"                # across components, examples, patterns, blocks, layout, tokens, docs
+   npx sable component Form --example "Server errors"   # one example a search hit names, imports included
    npx sable docs converting-an-app              # the task walkthroughs
    npx sable manifest --json                     # the whole command surface, machine-readable
    ```
@@ -150,9 +155,10 @@ package with `--root` naming the repository root (for example
 there and resolve Sable through the package.
 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.
+Use `$sable build <idea>`, `inspire <references>`, `audit <target>`,
+`polish <target>`, or `fix <target>` in Codex; use `/sable` with the same modes in
+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

package/CHANGELOG.md

@@ -1,5 +1,189 @@
 # What's new
 
+## 0.12.0
+
+Getting to a working first component, finding the right example, moving over from shadcn, and the components that move called for: Menubar, NavigationMenu, InputGroup, ButtonGroup, CaretMenu and bottom-sheet snap points.
+
+- **New: `sable init` wires an app in one step.** Run it after `pnpm add
+  @sableui/react`. It installs what is missing with your package manager
+  (React, Tailwind and its build plugin), puts the CSS imports in order, adds
+  React dedupe and the Tailwind plugin to a Vite config (a
+  `postcss.config.mjs` for Next.js), loads Figtree and DM Mono, and wraps a
+  Vite starter's `<App />` in `IconProvider`. Then it installs the agent
+  skill and runs `sable doctor`. What it can't change safely, such as a
+  Next.js layout or an unfamiliar config, it prints as the snippet and the
+  file it belongs in. `--dry-run` shows every change first.
+- **New: `sable doctor --fix`** applies the same fixes to whatever doctor
+  flags in an app that's already set up, then checks again. A fix that
+  didn't take is reported as unverified, not done. Doctor also gains two
+  warnings: Tailwind missing from the Vite or Next.js build (`css:build`),
+  and the theme's fonts never loaded (`fonts`).
+- **`sable search` finds examples.** Every component example is searchable
+  by what it shows: `sable search "multiple selection"` or `"server errors"`.
+  A hit names its own retrieve command, `sable component Combobox --example
+  "Multiple selection"`, which prints that one example with its imports.
+  Examples are capped per component and per list, so a component name still
+  lands on the component.
+- **New: a migration guide from shadcn/ui and Radix.** `sable docs
+  migrating-from-shadcn` maps what changes everywhere (`asChild` becomes
+  `render`, values become arrays, menu rows take `onClick`,
+  `data-[state=open]:` becomes `sable-open:`), the tokens, lucide icons, and
+  every shadcn component to its Sable counterpart, or what to compose where
+  there isn't one. `converting-an-app` points to it.
+- **New lint rule: `shadcn-leftover`.** Flags imports still coming from the
+  old stack (`@radix-ui/*`, `@/components/ui`, `lucide-react`, `sonner`,
+  `vaul`, `cmdk`, `input-otp`, `next-themes`) and any `asChild` prop, which a
+  Sable trigger silently ignores. A deliberate keeper takes a reasoned disable.
+- **The agent skill has a `fix` mode.** `$sable fix <target>` (or `/sable
+  fix`) repairs one scoped defect on a short path: it reads only the
+  contracts the change touches, then runs `sable check` on the changed files
+  and looks at the affected state. It escalates to `polish`, and its full
+  finish checklist, when the change grows. Run `sable setup --agent --update`
+  to refresh installed entries.
+- **ChatComposer can send attachments without text.** Pass
+  `allowEmpty={files.length > 0}` and send enables on the files alone;
+  `onSend` receives `""`. Tie it to the pending files: a constant
+  `allowEmpty` leaves send enabled with nothing to send.
+- **ChatComposer: on a phone or tablet, Return starts a new line.** A soft
+  keyboard has no Shift+Return, so on a touch device (`pointer: coarse`) the
+  default `sendOn="enter"` now behaves as `mod-enter`: Return breaks the
+  line, the send button sends, and ⌘/Ctrl+Enter still sends from a hardware
+  keyboard. `aria-keyshortcuts` reports whichever is in effect. `footer` now
+  also takes a function of the send key in effect, so a keyboard hint can
+  stay true: `footer={({ sendOn }) => sendOn === "enter" ? "Enter to send" :
+  null}` (null removes the row). *Migration:* a fixed "Enter to send" footer
+  is wrong on touch; switch it to the function form, as ChatPanel has.
+- **Combobox documents server-backed search.** A new "Async search" example
+  and the props it uses (`filter={null}`, `onInputValueChange`,
+  `itemToStringLabel`) show how to show results a server already filtered.
+- **New: `Menubar`.** An application's row of menus (File, Edit, View) over
+  Base UI's Menubar. Each menu is an ordinary `Menu` with a `MenubarTrigger`
+  as its title. The bar is one tab stop with ←/→ between titles, and once a
+  menu is open, pointing at a neighbour opens it.
+- **New: `NavigationMenu`.** A site header's primary nav: a bar of links and
+  triggers, where a trigger opens a panel of links on hover, click or Enter.
+  One shared panel moves along the bar and resizes to each trigger's
+  content. Links take your router's link through `render` and mark the
+  current page with `active`; panel rows take a `description`. Below `md`,
+  hand the same destinations to a Sheet with a SideNav, as the docs show.
+- **Pagination can render real links.** `pageLink={(page) => <Link
+  to={`?page=${page}`} />}` makes every page control a link that crawlers
+  follow and readers can open in a new tab. The current page keeps
+  `aria-current`; the arrows at the ends stay disabled buttons.
+  `onPageChange` is optional with `pageLink`.
+- **New: `InputGroup`.** An Input with addons inside the same field: a
+  prefix or suffix ("https://", ".com"), an icon, or a borderless Button
+  such as copy or reveal. One shell, one focus ring, one error state; inside
+  a Field, the label, description and error reach the Input.
+- **OverflowMenu documents responsive actions.** Secondary actions inline
+  when the container is wide, folded into the menu when it's narrow, the
+  primary action always inline. `sable search "responsive action menu"`
+  finds it.
+- **Sheet: snap points for bottom sheets.** `<Sheet snapPoints={[0.4, 1]}>`
+  gives a bottom sheet stops between closed and fully open; a swipe moves
+  between them, and `snapPoint` / `onSnapPointChange` control the active
+  one (new `SheetSnapPoint` type). With stops the sheet shows a drag handle,
+  and the part below the screen becomes padding, so content scrolls and
+  `SheetFooter` stays visible. Other sides ignore stops and a development
+  build says so. Every bottom sheet now also rides above the on-screen
+  keyboard (measured from `visualViewport`).
+- **New: `CaretMenu` and `useCaretTrigger`, mentions and slash commands on
+  any text field.** The hook watches a Textarea, Input or ChatComposer
+  (`fieldRef`) for a trigger character at the caret (`@`, `/` at the start,
+  `#`) and reports the query. CaretMenu shows suggestions there, driven by
+  ↑/↓, Enter, Tab and Escape while focus stays in the field. The app
+  supplies the items and what choosing one does: `trigger.replace("@Sam
+  Rivera ")` inserts a mention as text, and a command runs and `replace("")`
+  clears it. The value stays a plain string; chips inside the field need a
+  rich-text editor, which Sable doesn't ship.
+- **ChatComposer: an Enter someone else handled doesn't send.** A listener
+  on `fieldRef` that handles Enter and calls `preventDefault()` owns it. It's
+  how CaretMenu picks a suggestion instead of sending, and how an app adds
+  key behaviour of its own.
+- **ChatComposer keeps focus after Stop.** Stop turns back into send in
+  place, and with an empty field that send is disabled, which dropped focus
+  to the page. Focus now moves to the field, except on touch, where it would
+  raise the keyboard unasked.
+- **Scroller eases the mouse wheel.** New `smoothWheel` (on by default): a
+  notch eases toward its target instead of jumping, on either axis, the
+  inertia a library like Lenis adds but scoped to the region. Only a mouse
+  wheel is eased: trackpads and touch keep their own momentum, keys and
+  scrollbar drags stay native, it releases at the ends so the page scrolls
+  on, a nested area that can still scroll (a code block, a textarea) keeps
+  the wheel, a region that smooths or snaps in CSS is left to the browser,
+  and anything else that moves the region (`scrollIntoView`, a scrollbar
+  drag) stops it at once. Reduced motion turns it off. New
+  `useSmoothWheel()` gives a scroll container of your own the same thing.
+- **New guide: `sable docs building-a-chat`.** Wires Sable's chat parts to
+  any streaming source: which part owns what and what stays with the app, a
+  turn's lifecycle mapped onto `busy`, `onStop`, `streaming` and `disabled`,
+  where each failure goes, announcing a turn once rather than per token, and
+  rendering model output without injecting HTML.
+- **New guide: `sable docs extending-a-component`.** What to do when a
+  component doesn't do what you need: compose with `render`, fill a slot,
+  hold the state and reach the element, add behaviour on top (mentions as
+  the worked example), change the look through tokens and presets rather
+  than overrides, patch a defect, and tell a library gap from app work.
+- **The shadcn migration guide now maps every component.** Menubar,
+  NavigationMenu, InputGroup, ButtonGroup, link Pagination and drawer snap
+  points all have counterparts.
+- **Fix: a horizontal Scroller no longer widens its container.** Its outer
+  box kept the default `min-width: auto`, so inside a grid or flex column a
+  strip of cards grew to its full length and never scrolled. It now shrinks
+  to the column and scrolls with its edge fade. The Scrolling page's own
+  example was showing exactly this, and also lacked `orientation="horizontal"`.
+- **`useCopy` takes a function.** `useCopy(() => fetch(url).then((r) =>
+  r.text()))` produces the text only on click; a pending promise goes to the
+  clipboard as a ClipboardItem so Safari still counts it as part of the click.
+  New `CopySource` type.
+- **New: `ButtonGroup`.** Buttons joined into one control, such as a split
+  button (an action beside the chevron that opens its menu) or a short run of
+  related actions. The children stay ordinary Buttons with their own variants
+  and sizes. The group squares their inner corners, collapses bordered seams
+  into one hairline and draws a seam between filled ones. Button now reads a
+  per-side radius (`--button-radius-s` / `--button-radius-e`, falling back to
+  `--button-radius`) and renders `data-variant`, which is how the group
+  does it without overriding a class.
+- **Menu rows can carry an icon and a description.** `MenuItem` takes `icon`
+  and `description`, a quieter second line saying what the action does; with
+  a description the icon sits in a small tile spanning both lines.
+- **New: `MenuLinkItem`.** A menu row that navigates: a real `<a>`, so it opens
+  in a new tab, middle-clicks and copies as a link. With `target="_blank"`
+  it adds `rel="noopener noreferrer"` and a trailing ↗.
+- **Icon contract: `arrow-up-right`.** Added for links that leave the app.
+  An app with its own icon set should map it; Reicon's set already does.
+- **sableui.com: a Copy page button on every page.** Each page with a
+  Markdown version has a split button in its header. Copy page copies the
+  page as Markdown, fetched only when you click. The menu behind the chevron
+  opens the Markdown file, starts a ChatGPT or Claude chat that reads the
+  page (Claude tries the desktop app first and falls back to claude.ai), and
+  copies the setup command (`pnpm add @sableui/react && pnpm exec
+  sable init`). The Markdown files are the same ones the site publishes at
+  `/<page>.md`; both now come from one table
+  (`apps/docs/src/markdown-twins.json`).
+- **New: `Sidebar surface="page"`.** The rail paints the page's own surface
+  and ink, with no border, instead of the theme's `--sidebar-*` set. Use it
+  when a full-width header sits above the rail: a tinted or dark rail
+  (Verdant, Meridian) starting under a page-coloured bar reads as pasted on.
+  The default, `surface="rail"`, is unchanged and still right for a
+  full-height rail. Overriding `bg-background text-foreground` on a Sidebar
+  never worked, because the rail re-points those tokens at its own;
+  use the prop instead. sableui.com's docs rail now uses it.
+
+## 0.11.0
+
+- **New: `PropertyGroup`, a collapsible group inside a PanelSection.** The
+  row names the group, summarises its value while closed (a word, a few
+  swatches, or both), and opens with +/− to the rows beneath. It's sized for
+  a tool panel, where an Accordion is page furniture. Groups open
+  independently and stack with a hairline between them.
+- **sableui.com's Customize panel: the Color section is rebuilt on it.**
+  It now reads Brand color, then Primary action (with colour dots), then
+  three groups: Color palette (the families and Pull to brand), Tones (tones
+  and status) and Neutrals. Each group summarises itself with its own
+  swatches, and Tones and Neutrals are chosen from a list that previews what
+  each option would paint. The section has its own Reset.
+
 ## 0.10.0
 
 A palette generated from the theme, numbered extra tones, and sample content that isn't a marketplace.

package/DESIGN.md

@@ -469,7 +469,7 @@ Reference via `z-(--z-overlay)`, never a raw `z-[9999]`. Base UI overlays portal
 
 **Vertical gets a bar; horizontal gets a carousel.** A vertical list needs position feedback — how far through a long transcript am I — and a thin bar is the only thing that gives it. A horizontal strip does not: what a reader needs there is "there is more this way", which an **edge fade says better than a 4px rail**, and which the rail obscures by adding chrome under the content. So `Scroller` draws a bar on its vertical axis and none on its horizontal one, where its alpha-masked edges already do the work. Reach for the same split in anything strip-shaped: media rows, chip rows, tab overflow.
 
-**A horizontal region must be operable without a horizontal input.** Hiding the bar removed the last non-drag affordance on that axis, and most mice have no horizontal wheel — so `Scroller` maps a vertical wheel to sideways movement, and is focusable with arrow / Home / End / PageUp / PageDown handling. Both are on by default; the wheel mapping is `wheelScroll`, the name is `label`. The four things that make a naive wheel mapping feel broken, all handled in `useWheelToHorizontal`: it **releases at both ends** so it never traps a reader scrolling the page, it **ignores trackpad `deltaX` gestures** (`|deltaX| > |deltaY|` means the browser is already doing it, and handling `deltaY` too double-scrolls a diagonal swipe), it **ignores `shift+wheel`** (already native), and it **normalises `deltaMode`** (mice report *lines*, so the raw value moves ~3px per notch). Keyboard focus is declared rather than inherited: Chrome 128+ and Firefox make scroll regions focusable on their own, Safari does not.
+**A horizontal region must be operable without a horizontal input.** Hiding the bar removed the last non-drag affordance on that axis, and most mice have no horizontal wheel — so `Scroller` maps a vertical wheel to sideways movement, and is focusable with arrow / Home / End / PageUp / PageDown handling. Both are on by default; the wheel mapping is `wheelScroll`, the name is `label`. The four things that make a naive wheel mapping feel broken, all handled in `useSmoothWheel` (lib/use-smooth-wheel.ts): it **releases at both ends** so it never traps a reader scrolling the page, it **ignores trackpad `deltaX` gestures** (`|deltaX| > |deltaY|` means the browser is already doing it, and handling `deltaY` too double-scrolls a diagonal swipe), it **ignores `shift+wheel`** (already native), and it **normalises `deltaMode`** (mice report *lines*, so the raw value moves ~3px per notch). The same hook eases a mouse wheel on either axis (`smoothWheel`, on by default): only notches, never trackpads or touch, it gives way to a nested area that can still scroll, it leaves regions that smooth or snap in CSS to the browser, and anything else that moves the region stops the ease. Keyboard focus is declared rather than inherited: Chrome 128+ and Firefox make scroll regions focusable on their own, Safari does not.
 
 **Reveal is driven by scrolling, not by hover.** Hover is a decent proxy and a bad one for the cases that matter: a touch drag hovers nothing, and neither does a programmatic scroll — a chat auto-following a streamed reply, a jump-to-message, a restored read position — which are exactly the moments a reader needs to see where they now are. `useScrollActivity` sets `data-scrolling` on the element for ~600ms after each scroll event and `scrollbar-quiet` keys off it. Hover and `:focus-within` remain in the CSS as the no-JS baseline, so the bare utility still behaves for a consumer who never reaches for the hook. The fade honours `--motion-scale`, so reduced motion collapses it to an instant swap.
 

package/README.md

@@ -62,6 +62,17 @@ retrieval is the default. These tools do not update model weights. See
 
 > **Agents:** the machine-readable version of these steps is the `consume` block in [`registry.json`](./registry.json).
 
+**Quick start** — install, then let `sable init` do steps 2–5:
+
+```bash
+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.
+
+The steps below are what `init` does, for doing it by hand or checking its work.
+
 **1. Install:**
 
 ```bash
@@ -138,8 +149,11 @@ npx sable pattern --list                     # the eight canonical page shells
 npx sable pattern DashboardPage --skeleton   # its composition tree — 127 lines of source, 45 of structure
 npx sable block PricingCardBlock --code      # a section-sized block's source, imports included
 npx sable component Button --props
-npx sable search "date range"                # one ranked set across components, patterns, layout, tokens, docs
+npx sable search "date range"                # one ranked set across components, examples, patterns, layout, tokens, docs
+npx sable component Calendar --example Range # just the example a search hit names
+npx sable init                               # wire a new app: packages, CSS, fonts, IconProvider, agent skill, then doctor
 npx sable doctor                             # is this project wired correctly? exits 1 if not
+npx sable doctor --fix                       # apply the fixes doctor can make safely; print the rest
 npx sable docs designing-a-surface           # brief, direction, composition, interaction, adaptation
 npx sable docs developing-taste             # references, rendered directions, scoped judgment
 npx sable atlas --search "editorial culture" --contrast --limit 3 --json  # a project's own atlas, if it has one