@sableui/react 0.16.0 → 0.18.0

package/llms/components/section-rail.md

@@ -0,0 +1,101 @@
+# SectionRail
+
+**Status:** stable
+
+A slim vertical rail of dots, one per section of a long page, that shows where the reader is and jumps to any section. The current section's bar glides as the page scrolls; a shared tooltip names each dot.
+
+**Keywords:** section rail, scroll spy, scrollspy, dot navigation, page navigation, table of contents, on this page, chapter nav, scroll progress, case study nav
+
+## Usage
+
+Use SectionRail beside a long, single-column read — a case study, an essay, a long landing page — so the reader can see which section they are in and jump to another without leaving the text. It follows the scroll by itself (useActiveSection); pass value when the parent already knows the current section.
+
+### Best practices
+
+- Do: Give every section an id that matches its entry, and keep the list to the page's top-level sections — about ten at most, so the rail stays shorter than the viewport.
+- Do: Place it with layout classes — usually `fixed top-1/2 left-6 z-(--z-nav) -translate-y-1/2` — and hide it below the width where it would overlap the text (`max-lg:hidden`). Offer the same links another way on narrow screens, such as a Collapsible list at the top of the page.
+- Do: Pass `root` when the content scrolls inside an element (a Scroller, an inset AppShell main) rather than the window, and give sections `scroll-mt-*` when a sticky header would cover their tops after a jump.
+- Do: Set `side="right"` when the rail sits on the right edge, so labels open toward the content.
+- Don't: Use it for app navigation between pages; that is SideNav or Sidebar. A SectionRail only moves within one page. → use **SideNav**, **Sidebar**
+- Don't: Use it to show the steps of a task or a flow; that is Stepper, which shows progress through steps rather than position in a read. → use **Stepper**
+- Don't: Use it for a handful of switchable views in one place; that is Tabs. → use **Tabs**
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Rail | yes | The `<nav>` landmark: a rounded muted track holding one link per section. |
+| Dot | yes | A link to `#id`, drawn as a small dot that grows under the pointer or focus. |
+| Marker | yes | One primary bar that sits on the current section's dot and glides to the next. |
+| Label | yes | A shared tooltip that names the hovered or focused dot and travels between dots. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| sections | readonly { id: string; label: string }[] | — | The sections, in document order. `id` is the section element's id (the link goes to `#id`); `label` is the tooltip and the link's accessible name. |
+| value | string | — | The current section's id, when the parent decides it. Leave it unset and the rail follows the scroll itself. |
+| onValueChange | (id: string) => void | — | Called with the new id when the reader scrolls into a section or picks one. |
+| offset | number | 0.35 | Where the reading line sits, as a fraction of the viewport from its top. A section becomes current once its top crosses it. |
+| root | RefObject<HTMLElement \| null> | — | The element that scrolls, when it is not the window. |
+| side | "left" \| "right" | "left" | Which edge of the page the rail sits on. The labels open on the other side, toward the content. |
+| motion | "full" \| "subtle" \| "off" | "full" | How much motion this component uses: `full` inherits the app's policy, `subtle` keeps feedback and drops the marker's glide, `off` stills it. It can only turn motion down — it never overrides a reader's reduce-motion setting. |
+| aria-label | string | "Sections" | The nav landmark's name. Name it for the page ("Case study sections") when it has other navs. |
+
+## Tokens used
+
+`muted`, `muted-foreground`, `foreground`, `primary`, `ring`, `popover`, `popover-foreground`, `border-floating`
+
+## Motion
+
+- **arrival** · Root · _no motion_ — Page chrome arrives with the page; the marker lands on the current section with no transition, because a bar sliding in on load narrates a move nobody made.
+- **response** · Dot · `motion-interactive` — The dot darkens and grows under the pointer or focus, and the label travels between dots as one tooltip (TooltipGroup) rather than closing and reopening at each.
+- **transition** · Marker · `motion-glide` — One bar travels to the new section as the page scrolls, so the change reads as movement down the page. A picked section holds the bar until the reader scrolls by hand, so it goes straight there instead of stepping through every section in between, and stays on the pick even when the page ends before that section can reach the reading line. Expressive: `subtle` moves it at once.
+- **activity** · Root · _no motion_ — Navigation chrome has no working state.
+
+## Accessibility
+
+- Renders a <nav> landmark (default name "Sections") of real links to `#id`, so it works with no script, middle-click and copy-link.
+- Each link is named by its section's label; the current one carries aria-current="location".
+- Activating a link from the keyboard moves focus into the section, as following an anchor does, so the next Tab continues from there.
+- The tooltip opens on focus as well as hover; the dots are 44×32 targets.
+- Under reduced motion the jump is instant and the marker moves without travel.
+
+## Related
+
+- Components: SideNav, Tooltip, Stepper, Tabs, GlidingHighlight
+
+## Examples
+
+### Fixed beside a long read
+
+```tsx
+import { SectionRail } from "@sableui/react"
+
+<SectionRail
+  aria-label="Case study sections"
+  sections={[
+    { id: "overview", label: "Overview" },
+    { id: "problem", label: "The problem" },
+    { id: "process", label: "Process" },
+    { id: "outcome", label: "Outcome" },
+  ]}
+  className="fixed top-1/2 left-6 z-(--z-nav) -translate-y-1/2 max-lg:hidden"
+/>
+```
+
+### On the right edge
+
+```tsx
+import { SectionRail } from "@sableui/react"
+
+<SectionRail
+  side="right"
+  sections={[
+    { id: "intro", label: "Introduction" },
+    { id: "usage", label: "Usage" },
+    { id: "api", label: "API" },
+  ]}
+  className="fixed top-1/2 right-6 z-(--z-nav) -translate-y-1/2 max-lg:hidden"
+/>
+```

package/llms/components/sheet.md

@@ -48,7 +48,7 @@ Use Sheet for secondary workflows that slide in while preserving context from th
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
-| Sheet (Root) | Base UI Drawer.Root props (open, defaultOpen, onOpenChange, onOpenChangeComplete, modal, disablePointerDismissal, actionsRef, handle, snapPoints, snapPoint, defaultSnapPoint, onSnapPointChange, snapToSequentialPoints) — minus swipeDirection | — | Controls open state. Uncontrolled by default. The dismiss swipe direction is not a prop: it follows SheetContent's side. onOpenChange reports reason "swipe" when a swipe closed it. |
+| Sheet (Root) | Base UI Drawer.Root props (open, defaultOpen, onOpenChange, onOpenChangeComplete, modal, disablePointerDismissal, actionsRef, handle, snapPoints, snapPoint, defaultSnapPoint, onSnapPointChange, snapToSequentialPoints) — minus swipeDirection | — | Controls open state. Uncontrolled by default. The dismiss swipe direction is not a prop: it follows SheetContent's side. onOpenChange reports reason "swipe" when a swipe closed it. Records the element focused when the sheet opens, trigger or not, and returns focus there on close. |
 | snapPoints | (number \| string)[] | — | Stops a bottom sheet rests at, smallest first: a fraction of the viewport (0.4), pixels (320), or a px/rem string ("20rem"). The panel is the full stop's height and opens at the first stop; a swipe moves between stops and a swipe below the first closes it. side="bottom" only: other sides ignore them, with a development warning. |
 | snapPoint | number \| string \| null | — | The active stop, controlled. Pair with onSnapPointChange; use defaultSnapPoint to open at a different stop uncontrolled. |
 | onSnapPointChange | (snapPoint: number \| string \| null, eventDetails) => void | — | Fires when a swipe (or your code) moves the sheet to another stop. |
@@ -68,7 +68,7 @@ Use Sheet for secondary workflows that slide in while preserving context from th
 - The panel scrolls its own content (thin scrollbar, contained overscroll) when it outgrows its bound — the full height on left/right, 80vh on top/bottom.
 - Esc and click-outside dismiss by default; on touch, a swipe toward the sheet's own edge dismisses too. A short or slow drag springs back.
 - Swipe is an extra path, never the only one: Esc, click-outside and SheetClose all still work.
-- Focus matches Dialog: the first tabbable on mouse/keyboard open, the panel itself on touch (so the virtual keyboard stays down); focus returns to the trigger on close.
+- Focus matches Dialog: the first tabbable on mouse/keyboard open, the panel itself on touch (so the virtual keyboard stays down). On close, focus returns to the element that held it when the sheet opened: the SheetTrigger, or your own button when it drives a controlled open. It is captured before the content mounts, so an autoFocus field inside cannot displace it; an explicit finalFocus on SheetContent wins.
 - Render a SheetClose inside SheetContent so screen-reader users can escape the popup.
 - Slide animation runs via data-[starting-style]/data-[ending-style] attributes on the motion-duration token; while swiping the panel tracks the finger directly, and a released swipe finishes on the same token (scaled by flick speed), so reduced motion makes it instant.
 - A mouse drag that starts on sheet content selects text rather than dragging the panel; mouse dragging only starts from the padding edge.

package/llms/layout/aspect-box.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-Reserves space via aspect-ratio so async media loads with zero layout shift. Wrap images, video, embeds.
+Reserves space via aspect-ratio so async media loads with zero layout shift. Wrap images, video, embeds. The ratio is a class reading a CSS variable, so className reshapes it at a breakpoint (md:aspect-video).
 
 **Keywords:** aspect box, aspect ratio, media, layout shift
 

package/llms/layout/bleed.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-Escape a width-capped or inset ancestor to span the full CONTENT area (container-query units, so it stops at a fixed Sidebar instead of bleeding under it). Hero bands, profile covers, full-bleed media inside a capped Page.
+Escape a width-capped or inset ancestor to span the full CONTENT area (container-query units, so it stops at a fixed Sidebar instead of bleeding under it). Hero bands, profile covers, full-bleed media inside a capped Page. Width and margins are classes, so a breakpoint can turn the bleed off (lg:mx-0 lg:w-auto).
 
 **Keywords:** bleed, full bleed, media band, layout
 

package/llms/layout/center.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-Horizontally center a block, optionally capping its width (commonly "prose" for a reading column inside a wider layout).
+Horizontally center a block, optionally capping its width (commonly "prose" for a reading column inside a wider layout). Centering and cap are classes, so className overrides them at a breakpoint.
 
 **Keywords:** center, measure, reading width, layout
 

package/llms/layout/columns.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-An explicit N-column track (default 12) for proportioned layouts — pair with Col spans (list-detail, asymmetric editorial layouts). For uniform card grids prefer Grid minItemWidth.
+An explicit N-column track (default 12) for proportioned layouts — pair with Col spans (list-detail, asymmetric editorial layouts). For uniform card grids prefer Grid minItemWidth. display is the grid class, so hidden md:grid works; a gap-* utility replaces both gaps and the column-gap cap.
 
 **Keywords:** columns, 12 column, span, layout
 

package/llms/layout/grid.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-CSS Grid within a region. Two modes: fixed/responsive cols count, or minItemWidth so cells breathe with NO breakpoints (the default choice for card grids). A minItemWidth grid keeps its empty columns (track="fill"), so one result stays one cell wide; track="fit" stretches a fixed set across the row.
+CSS Grid within a region. Two modes: fixed/responsive cols count, or minItemWidth so cells breathe with NO breakpoints (the default choice for card grids). A minItemWidth grid keeps its empty columns (track="fill"), so one result stays one cell wide; track="fit" stretches a fixed set across the row. display is the grid class and the gap a CSS variable, so className utilities win at any breakpoint (hidden md:grid, md:gap-6, lg:grid-cols-3).
 
 **Keywords:** grid, card grid, auto fit, layout
 

package/llms/layout/region.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-The page region: fluid, edge-to-edge with the fluid page inset (--page-inset). Opt-in centered max cap picked by ROLE (prose/form/feed/content/wide/full), never a global page max-width. The root of nearly every route.
+The page region: fluid, edge-to-edge with the fluid page inset (--page-inset). Opt-in centered max cap picked by ROLE (prose/form/feed/content/wide/full), never a global page max-width. The root of nearly every route. The inset and cap are classes (px-(--page-inset), max-w-…), so className overrides them at a breakpoint (max-sm:px-0); only safeArea padding is inline.
 
 **Keywords:** region, page width, container, layout
 

package/llms/layout/row.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-Horizontal flex flow — inline rows of controls, toolbars, action clusters. Defaults to center-aligned, no wrap.
+Horizontal flex flow — inline rows of controls, toolbars, action clusters. Defaults to center-aligned, no wrap. Layout lives in classes (flex flex-row items-* justify-*) and the gap in a CSS variable, never inline style, so className utilities override any prop at a breakpoint (hidden md:flex, max-md:flex-col, md:gap-6).
 
 **Keywords:** row, toolbar, horizontal, layout
 
@@ -38,3 +38,11 @@ import { Button, Row } from "@sableui/react"
 
 <Row gap={2} justify="end"><Button variant="ghost">Cancel</Button><Button>Save changes</Button></Row>
 ```
+
+### Responsive through className
+
+```tsx
+import { Button, Row } from "@sableui/react"
+
+<Row justify="between"><span className="text-title-sm">Acme</span><Row gap={1} className="max-md:hidden"><Button variant="ghost" size="sm">Docs</Button><Button variant="ghost" size="sm">Pricing</Button></Row></Row>
+```

package/llms/layout/spacer.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-Explicit space on the rhythm, or a flexible grow pusher between siblings (e.g. pushing a footer item to the end of a Row).
+Explicit space on the rhythm, or a flexible grow pusher between siblings (e.g. pushing a footer item to the end of a Row). The size is a class reading a CSS variable, so className resizes or hides it at a breakpoint.
 
 **Keywords:** spacer, spacing, grow, layout
 

package/llms/layout/split-pane.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-Responsive two-pane layout: side-by-side at/above a breakpoint, stacked (primary first) below. List-detail, media + metadata.
+Responsive two-pane layout: side-by-side at/above a breakpoint, stacked (primary first) below. List-detail, media + metadata. display is the grid class and the breakpoint rules are layered, so className utilities (hidden lg:grid, gap-8) win.
 
 **Keywords:** split pane, two pane, list detail, responsive
 

package/llms/layout/stack.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-Vertical flow on the 8px rhythm — the default container for stacked content. Gap by role: tight within a group (1.5–2), looser between groups (3–4), generous between sections (6+).
+Vertical flow on the 8px rhythm — the default container for stacked content. Gap by role: tight within a group (1.5–2), looser between groups (3–4), generous between sections (6+). Layout lives in classes (flex flex-col items-* justify-*) and the gap in a CSS variable, never inline style, so className utilities override any prop at a breakpoint (max-lg:hidden, md:flex-row, md:gap-8).
 
 **Keywords:** stack, vertical rhythm, layout, spacing
 

package/llms/tasks/auditing-an-app.md

@@ -58,6 +58,37 @@ names the nearest pair that reads. Report it with that pair as a recommendation.
 A reasoned `design-lint-disable-next-line label-contrast` is the app's recorded
 choice: list it as intentional, not as a defect.
 
+## Adoption: an app wired for Sable that barely uses it
+
+The commonest drift is not a wrong prop. It is an app where an agent never
+loaded this skill: the stylesheet and tokens are wired, and every control is the
+app's own (a `Modal`, a `PrimaryButton`, a `Tabs` written from scratch). Wiring
+checks pass, and lint only sees the raw elements. `sable check` (and `sable
+grade --json` → `adoption`) measures it: how many UI files compose Sable, which
+app-defined components are named for something Sable ships and do the behaviour
+by hand, and what the app's foundation is. `sable doctor` warns when adoption is
+`none` or `low`. It is never a failure: whether working screens move is the
+user's call.
+
+Put the choice to the user before changing anything. Ask, don't migrate silently
+and don't leave it unmentioned. Show the swaps, behaviour first (overlays,
+controls, tabs, menus, anything with focus or keyboard handling), with what each
+one gains ("your Modal has no focus trap or Esc; Sable's Dialog has both").
+Layout and look stay the app's. How strongly to recommend it depends on the
+`foundation` the report names:
+
+| Foundation | What to say |
+|---|---|
+| `ad-hoc`: no system besides Sable | Recommend the move plainly. There is nothing to preserve but one-off components, and every one is a behaviour bug waiting. Offer to do it a screen at a time. |
+| `own`: a folder of the app's own primitives | Offer the swaps and say what each gains. Keep the app's own where the user prefers them; suggest building them on Sable's behaviour (a `Button` wrapper around Sable's `Button`) instead. |
+| `library`: another component library (MUI, Radix, shadcn-style `components/ui`) | Ask whether Sable should replace it or only cover new work. Don't mix two control libraries on one screen. |
+| `sable`: Sable already carries the UI | Mention the few swaps listed when those screens are next touched. |
+
+Use the question tool the host offers when there is one. Record the answer in
+the project's instructions, so the next task doesn't ask again. On a yes, move
+one screen or component at a time with `fix`/`polish`, running `sable check` and
+looking at the rendered states after each.
+
 ## Deliver evidence-backed findings
 
 Save the audit under `design/<surface>/audit/` or the existing review location.

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
 ```