@sableui/react 0.7.0 → 0.8.0

package/registry.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://sable.design/registry.schema.json",
   "name": "@sableui/react",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Themeable React components, semantic tokens, layout patterns, presets, and package-owned agent skills. Default theme: Sable.",
   "engine": {
     "behavior": "@base-ui/react",
@@ -1585,6 +1585,10 @@
       {
         "id": "lookalike-media-frame",
         "fails-on": "A cover or media frame built by hand — an `aspect-*` ratio + `overflow-hidden` wrapped around an <img>, <video>, <picture> or GradientArt. That is `AspectBox`: `ratio` as a number reserves the box before the media arrives (no layout shift while a cover loads or a shader starts), it clips and positions what it holds (`relative w-full overflow-hidden`), and it is the one frame the media components share, so a change to how frames behave reaches every cover. Put the radius on it as a className. For a cover with its title beneath (an album, an episode, a product), `MediaTile` composes this frame with fallback art for a missing or broken image and an action revealed on hover. Not flagged: a ratio box with no media in it (a pad, a canvas well), a frame without overflow clipping, an <img> sized by its own aspect class, or a round fixed-size frame (lookalike-avatar's)."
+      },
+      {
+        "id": "form-required-error",
+        "fails-on": "A `required` Field with an `error` prop, inside a `Form` that validates for you. On submit Form checks every Field first, so an empty required one stops the submit with the browser's message (\"Please fill out this field.\") and your onSubmit, which would set `error`, never runs. Either let your code own validation, `<Form noValidate>` (onSubmit always runs and the Field shows your `error`), or let Form validate and word the message on the Field: `messages={{ valueMissing: \"Enter a subject.\" }}`."
       }
     ],
     "escapeHatch": {
@@ -1678,7 +1682,12 @@
       "volume-low",
       "volume-off",
       "queue",
-      "music"
+      "music",
+      "tag",
+      "paperclip",
+      "chart",
+      "flag",
+      "at-sign"
     ]
   },
   "layoutPrimitives": {
@@ -1706,7 +1715,19 @@
           "bestPractices": [
             {
               "guidance": "do",
-              "description": "Choose the max value by content role, such as prose, form, feed, content, wide, or full."
+              "description": "Choose the max value by what the person does on the page: read (prose), fill in a form (form), scroll one stream (feed), review one record or settings (content), scan and compare rows or cards (wide)."
+            },
+            {
+              "guidance": "do",
+              "description": "Omit max (fluid) for work across panes, a board, an editor or a map, where a flexible part uses the extra width; cap text inside it with --measure-prose."
+            },
+            {
+              "guidance": "do",
+              "description": "Give sibling routes in one nav the same width so the header does not jump between them."
+            },
+            {
+              "guidance": "do",
+              "description": "Review a capped or fluid route at 1920px and 2560px: a cap is a ceiling, so below the cap plus app chrome every choice looks the same."
             },
             {
               "guidance": "do",
@@ -1715,6 +1736,14 @@
             {
               "guidance": "dont",
               "description": "Do not use Region as a global wrapper that forces every page into the same max width."
+            },
+            {
+              "guidance": "dont",
+              "description": "Do not go fluid when the extra width only widens the gaps between fixed columns; cap it."
+            },
+            {
+              "guidance": "dont",
+              "description": "Do not read full as edge to edge: it is the largest cap and keeps the page inset. Use bleed for edge to edge."
             }
           ]
         },
@@ -1741,7 +1770,7 @@
           {
             "name": "max",
             "type": "\"prose\" | \"form\" | \"feed\" | \"content\" | \"wide\" | \"full\" | CSS length",
-            "description": "Opt-in centered max-width cap, purpose-named: prose 65ch (long-form reading) · form 480px (auth, narrow single-column forms) · feed 640px (single-column timeline) · content 896px (settings/admin panes) · wide 1280px (dashboards, tables, card grids) · full 1536px (full-bleed ceiling). Omit for fully fluid."
+            "description": "Opt-in centered max-width cap, purpose-named: prose 65ch (long-form reading) · form 480px (auth, narrow single-column forms) · feed 640px (single-column timeline) · content 896px (settings/admin panes) · wide 1280px (dashboards, tables, card grids) · full 1536px (the largest cap; keeps the inset, so not edge to edge — that is bleed). Omit for fluid: work views whose panes, board or canvas use the extra width. A cap is a ceiling: it applies only once the viewport minus app chrome exceeds it, so judge it at 1920px and up."
           },
           {
             "name": "bleed",
@@ -1764,9 +1793,14 @@
             "imports": "import { PageHeader, Region } from \"@sableui/react\""
           },
           {
-            "label": "Fluid dashboard region",
+            "label": "Dashboard region (capped at wide)",
             "code": "<Region max=\"wide\"><Grid minItemWidth=\"16rem\"><Card><CardHeader><CardTitle>Revenue</CardTitle></CardHeader></Card><Card><CardHeader><CardTitle>Collects</CardTitle></CardHeader></Card></Grid></Region>",
             "imports": "import { Card, CardHeader, CardTitle, Grid, Region } from \"@sableui/react\""
+          },
+          {
+            "label": "Fluid workspace: the queue's table takes the extra width",
+            "code": "<Region as=\"main\"><Columns count={{ base: 1, lg: 12 }}><Col span={{ base: 1, lg: 3 }}><SideNav aria-label=\"Views\"><SideNavItem label=\"Open\" active /><SideNavItem label=\"Pending\" /></SideNav></Col><Col span={{ base: 1, lg: 9 }}><Card><CardContent flush><DataTable columns={columns} data={tickets} /></CardContent></Card></Col></Columns></Region>",
+            "imports": "import { Card, CardContent, Col, Columns, DataTable, Region, SideNav, SideNavItem } from \"@sableui/react\""
           }
         ]
       },
@@ -4457,8 +4491,8 @@
         },
         {
           "name": "BreadcrumbLink",
-          "type": "ComponentPropsWithRef<'a'>",
-          "description": "An interactive ancestor crumb (<a>). Muted by default, brightens to foreground on hover/focus."
+          "type": "ComponentPropsWithRef<'a'> & { render?: useRender.RenderProp }",
+          "description": "An interactive ancestor crumb (<a>). Muted by default, brightens to foreground on hover/focus. render composes another element with the crumb's styling, e.g. a router link: render={<Link to=\"/library\" />}, so navigating stays in the app."
         },
         {
           "name": "BreadcrumbPage",
@@ -4783,6 +4817,10 @@
             "guidance": "do",
             "description": "Use a single primary button in a view or dense panel so the action hierarchy stays obvious."
           },
+          {
+            "guidance": "do",
+            "description": "For a copy control, pair an icon Button with `useCopy(text, { timeout? })`. It takes the text when the hook is called and returns `{ copy, copied }`; `copy()` takes no argument, so pass the value the button copies to the hook, not to `copy`."
+          },
           {
             "guidance": "do",
             "description": "Write labels as actions, such as \"Save changes\" or \"Delete draft\", instead of vague labels like \"OK\"."
@@ -5622,7 +5660,7 @@
       "group": "Chat & AI",
       "register": "either",
       "path": "components/chat-composer",
-      "summary": "The input half of a conversation: one surface holding attachments, an auto-growing field, and its controls. Enter sends, Shift+Enter breaks the line, and send becomes stop while a reply streams.",
+      "summary": "The input half of a conversation: one surface holding attachments, an auto-growing field, and its controls. Enter sends, Shift+Enter breaks the line (sendOn=\"mod-enter\" swaps them for long-form replies), and send becomes stop while a reply streams.",
       "keywords": [
         "chat input",
         "composer",
@@ -5666,7 +5704,7 @@
           },
           {
             "guidance": "dont",
-            "description": "Do not use it as a general multi-line input. That is `Textarea` — this one submits on Enter, which is wrong for any field inside a larger form."
+            "description": "Do not use it as a general multi-line input inside a larger form. That is `Textarea`. A standalone reply box that sends multi-paragraph messages (email, support replies) is this one with sendOn=\"mod-enter\"."
           },
           {
             "guidance": "dont",
@@ -5740,6 +5778,12 @@
           "default": "\"Send a message…\"",
           "description": "Placeholder for the field."
         },
+        {
+          "name": "sendOn",
+          "type": "\"enter\" | \"mod-enter\"",
+          "default": "\"enter\"",
+          "description": "Which key sends. enter for chat (Shift+Enter breaks the line). mod-enter for long-form replies such as an email or a support answer: Enter breaks the line and Cmd/Ctrl+Enter sends, so a paragraph break never mails a draft. Say so in footer (\"Cmd+Enter to send\")."
+        },
         {
           "name": "busy",
           "type": "boolean",
@@ -6994,7 +7038,7 @@
         {
           "name": "items",
           "type": "CommandItem[]",
-          "description": "Data-driven commands ({ group, label, onSelect, id?, icon?, detail?, hint?, disabled? }). Ignored when children are provided. id is optional identity: filter is handed these same objects, so it is how a caller that ranks over its own richer model maps the array back onto it — and it becomes the row's DOM id (namespaced to the palette) and React key, so two rows may share a label."
+          "description": "Data-driven commands ({ group, label, onSelect, id?, icon?, detail?, stacked?, hint?, disabled? }). stacked puts detail on its own line under the label, for results only their detail tells apart (two tickets with one subject); beside a long label an inline detail truncates first. Ignored when children are provided. id is optional identity: filter is handed these same objects, so it is how a caller that ranks over its own richer model maps the array back onto it — and it becomes the row's DOM id (namespaced to the palette) and React key, so two rows may share a label."
         },
         {
           "name": "query",
@@ -7075,8 +7119,8 @@
         },
         {
           "name": "CommandMenuItem",
-          "type": "{ onSelect?: () => void; icon?: string; detail?: ReactNode; hint?: ReactNode; disabled?: boolean; id?: string; children }",
-          "description": "A selectable row. Self-filters by its text (unless the root was given a filter), runs onSelect, then closes the palette. detail is secondary text after the label; hint is the end-aligned trailing slot — a shortcut, a count, or a disabled row's reason. A disabled row stays listed, stays announced, and stays reachable by arrow key so its reason can be read, but is inert to Enter and to a click."
+          "type": "{ onSelect?: () => void; icon?: string; detail?: ReactNode; stacked?: boolean; hint?: ReactNode; disabled?: boolean; id?: string; children }",
+          "description": "A selectable row. Self-filters by its text (unless the root was given a filter), runs onSelect, then closes the palette. detail is secondary text after the label, or under it with stacked; hint is the end-aligned trailing slot — a shortcut, a count, or a disabled row's reason. A disabled row stays listed, stays announced, and stays reachable by arrow key so its reason can be read, but is inert to Enter and to a click."
         }
       ],
       "tokensUsed": [
@@ -7495,7 +7539,29 @@
         {
           "name": "isRowSelected",
           "type": "(row) => boolean",
-          "description": "Mark a row visually selected (data-selected). Derive it from a stable id (row.id === selectedId), not the row index, so selection survives re-sorts."
+          "description": "Mark a row visually selected (data-selected), e.g. the one open in a detail pane. Derive it from a stable id (row.id === selectedId), not the row index, so selection survives re-sorts. For checking several rows, use selectedKeys."
+        },
+        {
+          "name": "selectedKeys",
+          "type": "ReadonlySet<string | number>",
+          "description": "The checked rows, by rowKey, for bulk actions. With onSelectedKeysChange it adds a checkbox column (each box named by rowSelectionLabel) and a select-all box in the header that acts on the rows shown and goes mixed when some are checked. Checked rows get the selected fill. Controlled: when the rows shown change (a filter, another view), set the keys to keep, usually none. Needs rowKey."
+        },
+        {
+          "name": "onSelectedKeysChange",
+          "type": "(keys: Set<string | number>) => void",
+          "description": "Called with the new set of checked keys. Its presence turns selection on. A click on a box never fires onRowClick."
+        },
+        {
+          "name": "rowSelectionLabel",
+          "type": "(row) => string",
+          "default": "() => \"Select row\"",
+          "description": "A row checkbox's accessible name. Name the row, e.g. (t) => `Select ${t.subject}`, so a screen reader can tell the boxes apart."
+        },
+        {
+          "name": "selectAllLabel",
+          "type": "(count: number) => string",
+          "default": "(count) => `Select all ${count} shown`",
+          "description": "The select-all checkbox's accessible name; say what it acts on (\"Select all 7 tickets shown\")."
         },
         {
           "name": "defaultSort",
@@ -7525,6 +7591,11 @@
         "Inherits the Table's scrollable frame and semantic <table>/<th>/<td> structure."
       ],
       "examples": [
+        {
+          "label": "Checkbox selection with a bulk-action bar",
+          "code": "const [selected, setSelected] = useState<Set<string | number>>(new Set())\n\n<Stack gap={2}>\n\t{/* Mounted from the start, so a screen reader hears each change. */}\n\t<span role=\"status\" className=\"sr-only\">{selected.size ? `${selected.size} of ${tickets.length} selected` : \"\"}</span>\n\t{selected.size ? (\n\t\t<Toolbar aria-label=\"Bulk actions\">\n\t\t\t<span className=\"text-label-md\">{selected.size} of {tickets.length} selected</span>\n\t\t\t<Button size=\"sm\" variant=\"secondary\" onClick={() => resolve(selected)}>Resolve</Button>\n\t\t</Toolbar>\n\t) : null}\n\t<DataTable\n\t\tdata={tickets}\n\t\trowKey={(t) => t.id}\n\t\tcolumns={columns}\n\t\tselectedKeys={selected}\n\t\tonSelectedKeysChange={setSelected}\n\t\trowSelectionLabel={(t) => `Select ${t.subject}`}\n\t\tselectAllLabel={(n) => `Select all ${n} tickets shown`}\n\t/>\n</Stack>",
+          "imports": "import { Button, DataTable, Stack, Toolbar } from \"@sableui/react\""
+        },
         {
           "label": "Sortable columns",
           "code": "<DataTable data={users} columns={[{ key: \"name\", header: \"Name\", sortable: true }, { key: \"role\", header: \"Role\" }, { key: \"joined\", header: \"Joined\", sortable: true, sortValue: (u) => u.joinedAt, cell: (u) => formatDate(u.joinedAt) }]} />",
@@ -9498,7 +9569,7 @@
         {
           "name": "Form",
           "type": "{ validationMode?: \"onSubmit\" | \"onBlur\" | \"onChange\"; errors?: Record<string, string | string[]>; onFormSubmit?: (values, details) => void; actionsRef?: RefObject<Form.Actions> } + ComponentPropsWithRef<\"form\">",
-          "description": "A <form> laid out as a vertical column with comfortable field spacing (override with className, e.g. gap-4). On submit it validates every Field (native constraints plus Field validate), shows each message under its field, focuses the first invalid control, and only then calls onSubmit. validationMode defaults to \"onSubmit\" (then live re-validation on change). errors shows external (e.g. server) messages keyed by Field name and clears one when its field is edited. onFormSubmit receives the named Field values and prevents the native submit. A control outside any Field is still checked by the browser before onSubmit runs; pass noValidate to skip that."
+          "description": "A <form> laid out as a vertical column with comfortable field spacing (override with className, e.g. gap-4). On submit it validates every Field (native constraints plus Field validate), shows each message under its field, focuses the first invalid control, and only then calls onSubmit. validationMode defaults to \"onSubmit\" (then live re-validation on change). errors shows external (e.g. server) messages keyed by Field name and clears one when its field is edited. onFormSubmit receives the named Field values and prevents the native submit. A control outside any Field is still checked by the browser before onSubmit runs. Validating in your own code (react-hook-form, a schema, state)? Pass noValidate: onSubmit always runs and each Field shows the error you set; without it an empty required Field stops the submit before your handler can set that error."
         },
         {
           "name": "validationMode",
@@ -9516,6 +9587,12 @@
           "type": "(values: Record<string, unknown>, details) => void",
           "description": "Called with the named Field values after validation passes; prevents the native submit."
         },
+        {
+          "name": "noValidate",
+          "type": "boolean",
+          "default": "false",
+          "description": "Your code owns validation: nothing is checked before onSubmit (neither the Fields nor the browser), so it always runs and each Field shows the error you pass. required Fields keep their asterisk and aria-required. validationMode, errors, onFormSubmit and actionsRef do nothing with it."
+        },
         {
           "name": "actionsRef",
           "type": "RefObject<{ validate(name?: string): void }>",
@@ -9525,8 +9602,8 @@
       "subcomponents": [
         {
           "name": "Field",
-          "type": "{ label?: ReactNode; description?: ReactNode; error?: ReactNode; required?: boolean; disabled?: boolean; name?: string; validate?: (value, formValues) => string | string[] | null | Promise<…>; validationMode?: \"onSubmit\" | \"onBlur\" | \"onChange\"; validationDebounceTime?: number; orientation?: \"vertical\" | \"horizontal\"; className?: string; children: ReactElement }",
-          "description": "Wraps a single control element (e.g. <Input />) on Base UI Field and wires label (htmlFor + aria-labelledby), helper text and error (aria-describedby), aria-invalid, and required onto it automatically. Base UI-backed controls (Input, Textarea, Select, Combobox, NumberField, Checkbox, Switch, Slider, OtpField…) register through context; the child is also cloned so plain elements keep the same wiring. error renders a destructive message and takes precedence; without it the slot shows Base UI's validation message when the field fails (native constraint, validate, or Form errors). required adds the native attribute plus a visual asterisk (defaults to false). disabled disables the control and dims the label. name keys the field in Form errors / onFormSubmit. validationMode overrides the Form's. orientation defaults to \"vertical\" (label → control); \"horizontal\" places control then label inline for a single checkbox / switch / radio — the control centres on the label's first line (it stays there when the label wraps) and description/error sit in the label's column. The root, label, description, error and control carry data-invalid / data-valid, data-touched, data-dirty, data-filled, data-focused and data-disabled for state styling."
+          "type": "{ label?: ReactNode; description?: ReactNode; error?: ReactNode; required?: boolean; messages?: Partial<Record<\"valueMissing\" | \"typeMismatch\" | \"patternMismatch\" | \"tooShort\" | \"tooLong\" | \"rangeUnderflow\" | \"rangeOverflow\" | \"stepMismatch\" | \"badInput\", ReactNode>>; disabled?: boolean; name?: string; validate?: (value, formValues) => string | string[] | null | Promise<…>; validationMode?: \"onSubmit\" | \"onBlur\" | \"onChange\"; validationDebounceTime?: number; orientation?: \"vertical\" | \"horizontal\"; className?: string; children: ReactElement }",
+          "description": "Wraps a single control element (e.g. <Input />) on Base UI Field and wires label (htmlFor + aria-labelledby), helper text and error (aria-describedby), aria-invalid, and required onto it automatically. Base UI-backed controls (Input, Textarea, Select, Combobox, NumberField, Checkbox, Switch, Slider, OtpField…) register through context; the child is also cloned so plain elements keep the same wiring. error renders a destructive message and takes precedence; without it the slot shows the field's messages entry for the native constraint that failed (messages={{ valueMissing: \"Enter a subject.\" }}), else Base UI's validation message (the browser's wording for a native constraint, validate, or Form errors). required adds the native attribute plus a visual asterisk (defaults to false). disabled disables the control and dims the label. name keys the field in Form errors / onFormSubmit. validationMode overrides the Form's. orientation defaults to \"vertical\" (label → control); \"horizontal\" places control then label inline for a single checkbox / switch / radio — the control centres on the label's first line (it stays there when the label wraps) and description/error sit in the label's column. The root, label, description, error and control carry data-invalid / data-valid, data-touched, data-dirty, data-filled, data-focused and data-disabled for state styling."
         }
       ],
       "tokensUsed": [
@@ -9550,6 +9627,16 @@
           "code": "<Field label=\"Password\" error=\"Must be at least 8 characters.\"><Input type=\"password\" /></Field>",
           "imports": "import { Field, Input } from \"@sableui/react\""
         },
+        {
+          "label": "Your own wording for a missing value",
+          "code": "<Form onSubmit={handleSubmit}><Field label=\"Subject\" required messages={{ valueMissing: \"Enter a subject.\" }}><Input name=\"subject\" /></Field><Button type=\"submit\">Send</Button></Form>",
+          "imports": "import { Button, Field, Form, Input } from \"@sableui/react\""
+        },
+        {
+          "label": "Validation in your own code",
+          "code": "<Form noValidate onSubmit={handleSubmit}><Field label=\"Subject\" required error={errors.subject}><Input name=\"subject\" /></Field><Button type=\"submit\">Send</Button></Form>",
+          "imports": "import { Button, Field, Form, Input } from \"@sableui/react\""
+        },
         {
           "label": "Validated on submit",
           "code": "<Form onSubmit={handleSubmit}><Field label=\"Handle\" required validate={(value) => String(value).length < 3 ? \"At least 3 characters.\" : null}><Input name=\"handle\" /></Field><Button type=\"submit\">Claim</Button></Form>",
@@ -11711,7 +11798,7 @@
         {
           "name": "ref",
           "type": "Ref<MessageScrollerHandle>",
-          "description": "Imperative commands, not the DOM node: `scrollToBottom(opts)`, `scrollToTop(opts)`, `scrollToMessage(id, opts)` (returns false when the message is not rendered), `isFollowing()`, and `element` for the scrolling node itself."
+          "description": "Imperative commands, not the DOM node: `scrollToBottom(opts)`, `scrollToTop(opts)`, `scrollToMessage(id, opts)` (returns false when the message is not rendered), `isFollowing()`, and `element` for the scrolling node itself. `opts` is `ScrollCommandOptions`: `{ animate?: boolean }` (default true, and off whenever motion is), not the DOM's `behavior`."
         },
         {
           "name": "autoFollow",
@@ -12860,7 +12947,7 @@
         {
           "name": "actions",
           "type": "ReactNode",
-          "description": "Trailing actions aligned to the title row's end. They drop under the title when the row runs out of room, and the title wraps rather than truncating. A ghost or link Button at either end of the group bleeds by its own padding, so its label meets the content edge (the end on the title row, the start once wrapped); filled buttons keep their edge on the line. Direct children only."
+          "description": "Trailing actions aligned to the title row's end. They drop under the title when the title would have less than 20rem beside them (on a phone, nearly always), and the title wraps rather than truncating. A ghost or link Button at either end of the group bleeds by its own padding, so its label meets the content edge (the end on the title row, the start once wrapped); filled buttons keep their edge on the line. Direct children only."
         },
         {
           "name": "titleAs",
@@ -13561,8 +13648,8 @@
         },
         {
           "name": "centerLabel",
-          "type": "{ value: string; label?: string }",
-          "description": "A value and caption in the hole of a donut."
+          "type": "{ value: string | number; label?: string }",
+          "description": "A value and caption in the hole of a donut. The value holds the centre and the caption hangs below it. A number is formatted for you: in full up to 9,999, compact from 10,000 (10.2K, 102.1K, 1.2M); pass a string for units."
         },
         {
           "name": "separator",
@@ -13675,7 +13762,7 @@
       "examples": [
         {
           "label": "Donut with a total",
-          "code": "const sources = [\n\t{ source: \"Search\", visitors: 275 },\n\t{ source: \"Direct\", visitors: 200 },\n\t{ source: \"Social\", visitors: 187 },\n\t{ source: \"Email\", visitors: 90 },\n]\n\n<PieChart\n\tlabel=\"Visitors by source\"\n\tdata={sources}\n\tindex=\"source\"\n\tvalueKey=\"visitors\"\n\tdonut\n\tcenterLabel={{ value: \"752\", label: \"Visitors\" }}\n/>",
+          "code": "const sources = [\n\t{ source: \"Search\", visitors: 275 },\n\t{ source: \"Direct\", visitors: 200 },\n\t{ source: \"Social\", visitors: 187 },\n\t{ source: \"Email\", visitors: 90 },\n]\n\n<PieChart\n\tlabel=\"Visitors by source\"\n\tdata={sources}\n\tindex=\"source\"\n\tvalueKey=\"visitors\"\n\tdonut\n\tcenterLabel={{ value: 752, label: \"Visitors\" }}\n/>",
           "imports": "import { PieChart } from \"@sableui/react\""
         },
         {
@@ -14439,8 +14526,8 @@
         },
         {
           "name": "centerLabel",
-          "type": "{ value: string; label?: string }",
-          "description": "A value and caption in the middle."
+          "type": "{ value: string | number; label?: string }",
+          "description": "A value and caption in the middle. On a full ring the value holds the centre and the caption hangs below it. A number is formatted for you: in full up to 9,999, compact from 10,000 (10.2K); pass a string for units (\"7.2 GB\", \"72%\")."
         },
         {
           "name": "legend",
@@ -15942,7 +16029,7 @@
       "group": "Overlays",
       "register": "either",
       "path": "components/settings-menu",
-      "summary": "A compact trigger that states the current settings, over a menu of rows that change them. Each row shows its own value and opens a submenu.",
+      "summary": "A compact trigger that states the current settings, over a menu of rows that change them. Each row shows its own value and opens a submenu; with one setting, the menu opens straight to its options under the row's label.",
       "keywords": [
         "settings",
         "model picker",
@@ -16467,6 +16554,11 @@
         }
       ],
       "subcomponents": [
+        {
+          "name": "SidebarHeader",
+          "type": "div props",
+          "description": "The top of the rail, at least 64px tall. It holds SidebarBrand and may take a second row under it, such as a search field or a notifications button: give that row basis-full and the header grows to hold it instead of clipping."
+        },
         {
           "name": "SidebarBrand",
           "type": "{ mark: ReactNode; label: ReactNode; render?: useRender.RenderProp } + div props",
@@ -17858,7 +17950,7 @@
       "group": "Selection",
       "register": "either",
       "path": "components/switch",
-      "summary": "Binary on/off toggle for immediate-effect settings. Track fills with the primary tone when checked; the thumb slides on a spring-eased transform (mirrored in RTL).",
+      "summary": "Binary on/off toggle for immediate-effect settings. Track fills with the primary tone when checked; the thumb slides on a spring-eased transform (mirrored in RTL). The thumb is white in both states, like every physical toggle, and turns dark only on a near-white track (a dark mode's light primary). Themes can set --theme-switch-thumb-on.",
       "keywords": [
         "switch",
         "toggle setting",
@@ -17941,7 +18033,6 @@
       "tokensUsed": [
         "input",
         "primary",
-        "primary-foreground",
         "ring"
       ],
       "motion": [
@@ -21174,7 +21265,7 @@
           "Hovering or arrowing through the slices pulls each out and announces it."
         ],
         "imports": "import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, cn, PieChart } from \"@sableui/react\"",
-        "code": "const sources = [\n\t{ source: \"Search\", visitors: 4280 },\n\t{ source: \"Direct\", visitors: 2910 },\n\t{ source: \"Social\", visitors: 1840 },\n\t{ source: \"Email\", visitors: 960 },\n]\n\nconst total = sources.reduce((sum, s) => sum + s.visitors, 0)\n\nexport interface TrafficSourcesBlockProps {\n\tclassName?: string\n\t/** false drops the card's surface and border — for a muted section that already frames it. */\n\tframed?: boolean\n}\n\nexport function TrafficSourcesBlock({ className, framed = true }: TrafficSourcesBlockProps) {\n\treturn (\n\t\t<Card variant={framed ? \"default\" : \"flat\"} className={cn(\"w-full max-w-sm\", className)}>\n\t\t\t<CardHeader>\n\t\t\t\t<CardTitle render={<h2 />}>Traffic sources</CardTitle>\n\t\t\t\t<CardDescription>Where this month's visitors came from.</CardDescription>\n\t\t\t</CardHeader>\n\t\t\t<CardContent>\n\t\t\t\t<PieChart\n\t\t\t\t\tlabel=\"Visitors by source, this month\"\n\t\t\t\t\tdata={sources}\n\t\t\t\t\tindex=\"source\"\n\t\t\t\t\tvalueKey=\"visitors\"\n\t\t\t\t\tdonut\n\t\t\t\t\tcenterLabel={{ value: total.toLocaleString(\"en-US\"), label: \"Visitors\" }}\n\t\t\t\t/>\n\t\t\t</CardContent>\n\t\t\t<CardFooter className=\"text-body-sm text-muted-foreground\">\n\t\t\t\tSearch brings {Math.round((sources[0].visitors / total) * 100)}% of visitors.\n\t\t\t</CardFooter>\n\t\t</Card>\n\t)\n}"
+        "code": "const sources = [\n\t{ source: \"Search\", visitors: 4280 },\n\t{ source: \"Direct\", visitors: 2910 },\n\t{ source: \"Social\", visitors: 1840 },\n\t{ source: \"Email\", visitors: 960 },\n]\n\nconst total = sources.reduce((sum, s) => sum + s.visitors, 0)\n\nexport interface TrafficSourcesBlockProps {\n\tclassName?: string\n\t/** false drops the card's surface and border — for a muted section that already frames it. */\n\tframed?: boolean\n}\n\nexport function TrafficSourcesBlock({ className, framed = true }: TrafficSourcesBlockProps) {\n\treturn (\n\t\t<Card variant={framed ? \"default\" : \"flat\"} className={cn(\"w-full max-w-sm\", className)}>\n\t\t\t<CardHeader>\n\t\t\t\t<CardTitle render={<h2 />}>Traffic sources</CardTitle>\n\t\t\t\t<CardDescription>Where this month's visitors came from.</CardDescription>\n\t\t\t</CardHeader>\n\t\t\t<CardContent>\n\t\t\t\t<PieChart\n\t\t\t\t\tlabel=\"Visitors by source, this month\"\n\t\t\t\t\tdata={sources}\n\t\t\t\t\tindex=\"source\"\n\t\t\t\t\tvalueKey=\"visitors\"\n\t\t\t\t\tdonut\n\t\t\t\t\tcenterLabel={{ value: total, label: \"Visitors\" }}\n\t\t\t\t/>\n\t\t\t</CardContent>\n\t\t\t<CardFooter className=\"text-body-sm text-muted-foreground\">\n\t\t\t\tSearch brings {Math.round((sources[0].visitors / total) * 100)}% of visitors.\n\t\t\t</CardFooter>\n\t\t</Card>\n\t)\n}"
       },
       {
         "name": "TrafficTrendBlock",
@@ -21197,7 +21288,7 @@
           "The range control is a labelled ToggleGroup; the chart is one tab stop with arrow-key navigation."
         ],
         "imports": "import { useState } from \"react\"\nimport { AreaChart, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, cn, Icon, Toggle, ToggleGroup } from \"@sableui/react\"",
-        "code": "/** 90 days of visitors — replace with your own rows ({ date, desktop, mobile }). */\nconst days = Array.from({ length: 90 }, (_, i) => {\n\tconst wave = Math.sin(i / 6) * 60 + Math.sin(i / 2.3) * 25\n\treturn {\n\t\tdate: new Date(2026, 6, 1 + i).toISOString().slice(0, 10),\n\t\tdesktop: Math.round(240 + wave + (i % 7) * 9),\n\t\tmobile: Math.round(160 + wave * 0.7 + ((i * 3) % 11) * 6),\n\t}\n})\n\nconst series = [\n\t{ key: \"desktop\", label: \"Desktop\" },\n\t{ key: \"mobile\", label: \"Mobile\" },\n]\n\nconst ranges = [\n\t{ id: \"90d\", label: \"3 months\", days: 90 },\n\t{ id: \"30d\", label: \"30 days\", days: 30 },\n\t{ id: \"7d\", label: \"7 days\", days: 7 },\n]\n\nconst shortDate = (iso: string) => new Date(`${iso}T00:00:00`).toLocaleDateString(\"en-US\", { month: \"short\", day: \"numeric\" })\n\nexport interface TrafficTrendBlockProps {\n\tclassName?: string\n\t/** false drops the card's surface and border — for a muted section that already frames it. */\n\tframed?: boolean\n}\n\nexport function TrafficTrendBlock({ className, framed = true }: TrafficTrendBlockProps) {\n\tconst [range, setRange] = useState(\"90d\")\n\tconst shown = days.slice(-(ranges.find((r) => r.id === range)?.days ?? 90))\n\treturn (\n\t\t<Card variant={framed ? \"default\" : \"flat\"} className={cn(\"w-full max-w-3xl\", className)}>\n\t\t\t<CardHeader>\n\t\t\t\t<CardTitle render={<h2 />}>Visitors</CardTitle>\n\t\t\t\t<CardDescription>Desktop and mobile, by day.</CardDescription>\n\t\t\t\t<CardAction>\n\t\t\t\t\t<ToggleGroup value={[range]} onValueChange={(v: unknown[]) => v[0] && setRange(String(v[0]))} aria-label=\"Time range\">\n\t\t\t\t\t\t{ranges.map((r) => (\n\t\t\t\t\t\t\t<Toggle key={r.id} value={r.id}>\n\t\t\t\t\t\t\t\t{r.label}\n\t\t\t\t\t\t\t</Toggle>\n\t\t\t\t\t\t))}\n\t\t\t\t\t</ToggleGroup>\n\t\t\t\t</CardAction>\n\t\t\t</CardHeader>\n\t\t\t<CardContent>\n\t\t\t\t<AreaChart\n\t\t\t\t\tlabel={`Visitors per day, last ${ranges.find((r) => r.id === range)?.label}`}\n\t\t\t\t\tdata={shown}\n\t\t\t\t\tindex=\"date\"\n\t\t\t\t\tseries={series}\n\t\t\t\t\tindexFormatter={shortDate}\n\t\t\t\t\ttooltip={{ labelFormatter: (d) => new Date(`${d}T00:00:00`).toLocaleDateString(\"en-US\", { weekday: \"short\", month: \"short\", day: \"numeric\" }) }}\n\t\t\t\t\tstacked\n\t\t\t\t\tgradient\n\t\t\t\t\tclassName=\"h-64\"\n\t\t\t\t/>\n\t\t\t</CardContent>\n\t\t\t<CardFooter className=\"gap-1.5 text-body-sm\">\n\t\t\t\t<Icon name=\"arrow-up\" className=\"text-success\" />\n\t\t\t\t<span>\n\t\t\t\t\tUp 5.2% on the previous period <span className=\"text-muted-foreground\">· desktop leads every week</span>\n\t\t\t\t</span>\n\t\t\t</CardFooter>\n\t\t</Card>\n\t)\n}"
+        "code": "/** 90 days of visitors — replace with your own rows ({ date, desktop, mobile }). */\nconst days = Array.from({ length: 90 }, (_, i) => {\n\tconst wave = Math.sin(i / 6) * 60 + Math.sin(i / 2.3) * 25\n\treturn {\n\t\tdate: new Date(2026, 6, 1 + i).toISOString().slice(0, 10),\n\t\tdesktop: Math.round(240 + wave + (i % 7) * 9),\n\t\tmobile: Math.round(160 + wave * 0.7 + ((i * 3) % 11) * 6),\n\t}\n})\n\nconst series = [\n\t{ key: \"desktop\", label: \"Desktop\" },\n\t{ key: \"mobile\", label: \"Mobile\" },\n]\n\nconst ranges = [\n\t{ id: \"90d\", label: \"3 months\", days: 90 },\n\t{ id: \"30d\", label: \"30 days\", days: 30 },\n\t{ id: \"7d\", label: \"7 days\", days: 7 },\n]\n\nconst shortDate = (iso: string) => new Date(`${iso}T00:00:00`).toLocaleDateString(\"en-US\", { month: \"short\", day: \"numeric\" })\n\nexport interface TrafficTrendBlockProps {\n\tclassName?: string\n\t/** false drops the card's surface and border — for a muted section that already frames it. */\n\tframed?: boolean\n}\n\nexport function TrafficTrendBlock({ className, framed = true }: TrafficTrendBlockProps) {\n\tconst [range, setRange] = useState(\"90d\")\n\tconst shown = days.slice(-(ranges.find((r) => r.id === range)?.days ?? 90))\n\treturn (\n\t\t<Card variant={framed ? \"default\" : \"flat\"} className={cn(\"@container/trend w-full max-w-3xl\", className)}>\n\t\t\t<CardHeader className=\"@max-sm/trend:has-data-[slot=card-action]:grid-cols-1\">\n\t\t\t\t<CardTitle render={<h2 />}>Visitors</CardTitle>\n\t\t\t\t<CardDescription>Desktop and mobile, by day.</CardDescription>\n\t\t\t\t{/* Beside the title on a wide card; under it on a narrow one, where three\n\t\t\t\t    ranges would squeeze the title and description into a sliver. */}\n\t\t\t\t<CardAction className=\"@max-sm/trend:col-start-1 @max-sm/trend:row-span-1 @max-sm/trend:row-start-auto @max-sm/trend:mt-2 @max-sm/trend:justify-self-start\">\n\t\t\t\t\t<ToggleGroup value={[range]} onValueChange={(v: unknown[]) => v[0] && setRange(String(v[0]))} aria-label=\"Time range\">\n\t\t\t\t\t\t{ranges.map((r) => (\n\t\t\t\t\t\t\t<Toggle key={r.id} value={r.id}>\n\t\t\t\t\t\t\t\t{r.label}\n\t\t\t\t\t\t\t</Toggle>\n\t\t\t\t\t\t))}\n\t\t\t\t\t</ToggleGroup>\n\t\t\t\t</CardAction>\n\t\t\t</CardHeader>\n\t\t\t<CardContent>\n\t\t\t\t<AreaChart\n\t\t\t\t\tlabel={`Visitors per day, last ${ranges.find((r) => r.id === range)?.label}`}\n\t\t\t\t\tdata={shown}\n\t\t\t\t\tindex=\"date\"\n\t\t\t\t\tseries={series}\n\t\t\t\t\tindexFormatter={shortDate}\n\t\t\t\t\ttooltip={{ labelFormatter: (d) => new Date(`${d}T00:00:00`).toLocaleDateString(\"en-US\", { weekday: \"short\", month: \"short\", day: \"numeric\" }) }}\n\t\t\t\t\tstacked\n\t\t\t\t\tgradient\n\t\t\t\t\tclassName=\"h-64\"\n\t\t\t\t/>\n\t\t\t</CardContent>\n\t\t\t<CardFooter className=\"gap-1.5 text-body-sm\">\n\t\t\t\t<Icon name=\"arrow-up\" className=\"text-success\" />\n\t\t\t\t<span>\n\t\t\t\t\tUp 5.2% on the previous period <span className=\"text-muted-foreground\">· desktop leads every week</span>\n\t\t\t\t</span>\n\t\t\t</CardFooter>\n\t\t</Card>\n\t)\n}"
       },
       {
         "name": "UploadListBlock",
@@ -23748,6 +23839,9 @@
         "render",
         "showLabel"
       ],
+      "BreadcrumbLink": [
+        "render"
+      ],
       "BreadcrumbSeparator": [
         "children"
       ],
@@ -23917,6 +24011,7 @@
         "onValueChange",
         "placeholder",
         "sendLabel",
+        "sendOn",
         "stopLabel",
         "value"
       ],
@@ -24188,7 +24283,8 @@
         "disabled",
         "hint",
         "icon",
-        "onSelect"
+        "onSelect",
+        "stacked"
       ],
       "CommandMenuPanel": [
         "children",
@@ -24326,7 +24422,11 @@
         "empty",
         "isRowSelected",
         "onRowClick",
-        "rowKey"
+        "onSelectedKeysChange",
+        "rowKey",
+        "rowSelectionLabel",
+        "selectAllLabel",
+        "selectedKeys"
       ],
       "DatePicker": [
         "className",
@@ -24511,6 +24611,7 @@
         "disabled",
         "error",
         "label",
+        "messages",
         "name",
         "orientation",
         "required",
@@ -24567,6 +24668,7 @@
       "Form": [
         "actionsRef",
         "errors",
+        "noValidate",
         "onFormSubmit",
         "validationMode"
       ],

package/scripts/design-memory.mjs

@@ -95,7 +95,12 @@ const template = {
 	avoidWhen: "",
 	change: { before: "", after: "" },
 	provenance: { kind: "build-review", source: "", date: "", reviewer: "", sableVersion: "" },
-	evidence: [{ kind: "before", path: "", observation: "" }, { kind: "after", path: "", observation: "" }],
+	// The paths say their own rules, which recording enforces: a dogfood run met
+	// both only as ERR_LESSON_INVALID after filling the template in.
+	evidence: [
+		{ kind: "before", path: "<a non-empty file inside this project, relative to its root, e.g. design/evidence/before.png>", observation: "" },
+		{ kind: "after", path: "<a different file from the before one, also inside the project>", observation: "" },
+	],
 }
 
 function main() {
@@ -118,7 +123,7 @@ function main() {
 	const actions = ["--list", "--search", "--show", "--record", "--template", "--check"].filter((flag) => flags.has(flag))
 	if (actions.length > 1) return fail("ERR_BAD_FLAG", "Choose one of --list, --search, --show, --record, --template, --check.")
 	if (flags.has("--help")) {
-		process.stdout.write("sable learn — retrieve precedents and record project-owned lessons\n\n  --list | --search <words> | --show <id> | --template | --record <lesson.json> | --check\n  --json   structured { type, data } output\n\nRun from the project root. Evidence paths are relative to that root. Records are provisional reviewer observations, never automatic proof of taste.\n")
+		process.stdout.write("sable learn — retrieve precedents and record project-owned lessons\n\n  --list | --search <words> | --show <id> | --template | --record <lesson.json> | --check\n  --json   structured { type, data } output\n\nRun from the project root. Evidence paths are relative to that root, must stay inside it, and before and after must be different files. Records are provisional reviewer observations, never automatic proof of taste.\n")
 		return
 	}
 	if (flags.has("--template")) {

package/scripts/design-presets.mjs

@@ -55,7 +55,7 @@ try {
 			const target = match[1].includes(".dark") ? groups.dark : groups.light
 			for (const declaration of match[2].matchAll(/--([\w-]+)\s*:\s*([^;]+);/g)) target[declaration[1]] = declaration[2].trim()
 		}
-		const { PRESET_TOKEN_NAMES } = await import("../dist/presets/index.js")
+		const { PAGE_WIDTH_TOKENS, PRESET_TOKEN_NAMES } = await import("../dist/presets/index.js")
 		function tokens(mode) {
 			const values = { ...groups.light, ...(mode === "dark" ? groups.dark : {}) }
 			function resolveValue(value, chain = []) {
@@ -65,7 +65,9 @@ try {
 					return resolveValue(values[name], [...chain, name])
 				})
 			}
-			return Object.fromEntries(PRESET_TOKEN_NAMES.filter(name => values[name]).map(name => [name, resolveValue(values[name])]))
+			// Page widths are opt-in: copying the defaults would override any widths
+			// an app already sets in its own CSS, since preset CSS loads after it.
+			return Object.fromEntries(PRESET_TOKEN_NAMES.filter(name => values[name] && !PAGE_WIDTH_TOKENS.includes(name)).map(name => [name, resolveValue(values[name])]))
 		}
 		const preset = parsePreset({ schemaVersion: 1, id: "my-preset", label: "My preset", revision: 1, sableVersion: manifest.version, defaultMode: "dark", fonts: { sans: groups.light["font-sans"], mono: groups.light["font-mono"] }, direction: "Content-first composition with a clear primary action. Replace this guidance with the direction for your product.", tokens: { shared: {}, light: tokens("light"), dark: tokens("dark") } })
 		emit("preset.template", preset, JSON.stringify(preset, null, 2))
@@ -95,10 +97,19 @@ try {
 			}
 			const accepted = labels.accepted.map(f => `\n  accepted: ${pair(f)} — ${f.reason}`).join("")
 			const unmeasured = labels.unmeasured.length ? `, ${labels.unmeasured.length} unmeasured (${labels.unmeasured.join(", ")})` : ""
+			// A passing check is the start of applying a preset, not the end: say what
+			// makes the app use it, so a check does not read as "done".
+			const fonts = [...new Set(Object.values(preset.fonts).filter(Boolean).map(stack => stack.split(",")[0].trim().replace(/^["']|["']$/g, "")))]
+			const next = [
+				`sable preset --css ${file} > <stylesheet>, imported after Sable's`,
+				`load fonts: ${fonts.join(", ")}`,
+				`SableThemeProvider defaultThemeId="${preset.id}" defaultPreference="${preset.defaultMode}" with the preset in customThemes`,
+				"build the app, run sable check, review both modes (sable docs using-presets)",
+			]
 			emit(
 				"preset.check",
-				{ valid: true, id: preset.id, revision: preset.revision, authoredWith: preset.sableVersion, installed, warnings, labelContrast: { measured: labels.measured, accepted: labels.accepted, unmeasured: labels.unmeasured } },
-				`Valid preset ${preset.id}, revision ${preset.revision}. Labels on filled roles: ${labels.measured} pairs measured${unmeasured}.${accepted}${warningText}\nReview rendered contrast and brief fit separately.`,
+				{ valid: true, id: preset.id, revision: preset.revision, authoredWith: preset.sableVersion, installed, warnings, labelContrast: { measured: labels.measured, accepted: labels.accepted, unmeasured: labels.unmeasured }, fonts, next },
+				`Valid preset ${preset.id}, revision ${preset.revision}. Labels on filled roles: ${labels.measured} pairs measured${unmeasured}.${accepted}${warningText}\nReview rendered contrast and brief fit separately.\nTo apply it to an app:\n${next.map(step => `  - ${step}`).join("\n")}`,
 			)
 		} else {
 			const css = presetCss(preset)

package/scripts/lint-rules.mjs

@@ -1038,6 +1038,37 @@ export function makeRules({ semanticTokens, motionTokens, labelContrast = null,
 				return ctx?.isStylesheet && statusText ? statusText(text) : []
 			},
 		},
+		{
+			id: "form-required-error",
+			/* CONSUMER-scoped. A support app set `error` on a required Field and
+			 * never saw it: Form validates every Field before it calls onSubmit, so
+			 * an empty one stopped the submit with the browser's wording and the
+			 * handler that sets `error` never ran. */
+			scope: "consumer",
+			since: "0.8.0",
+			file: true,
+			code: true,
+			why:
+				"A `required` Field with an `error` prop, inside a `Form` that validates for you. On submit Form checks every Field first, so an empty required one stops the submit with the browser's message (\"Please fill out this field.\") and your onSubmit, which would set `error`, never runs. Either let your code own validation, `<Form noValidate>` (onSubmit always runs and the Field shows your `error`), or let Form validate and word the message on the Field: `messages={{ valueMissing: \"Enter a subject.\" }}`.",
+			scan(text) {
+				const src = maskMarkupTemplates(text)
+				const out = []
+				// A boolean prop is on when written bare or as anything but `={false}`.
+				const flag = (attrs, name) => {
+					const m = new RegExp(`(?:^|\\s)${name}(?![\\w-])(\\s*=\\s*\\{\\s*false\\s*\\})?`).exec(attrs)
+					return Boolean(m) && !m[1]
+				}
+				for (const form of openingTags(src, /^Form$/)) {
+					if (flag(form.attrs, "noValidate")) continue
+					const { inner } = elementContent(src, form)
+					for (const field of openingTags(inner, /^Field$/)) {
+						if (!flag(field.attrs, "required") || !/(?:^|\s)error\s*=/.test(field.attrs)) continue
+						out.push({ index: form.end + 1 + field.index, match: "required Field with error inside a validating Form → <Form noValidate> or messages={{ valueMissing }}" })
+					}
+				}
+				return out
+			},
+		},
 		{
 			id: "hand-derived-surface",
 			/* CONSUMER-scoped. Mixing ink into a surface by hand is what the
@@ -1229,7 +1260,7 @@ export function makeRules({ semanticTokens, motionTokens, labelContrast = null,
 			file: true,
 			code: true,
 			why:
-				"A look-changing class on a Sable component (border*, bg-*, rounded*, ring-*, shadow-* on Button, Pill or Badge). Their appearance is set by variants — Button `variant` (floating for a control over content), Pill `appearance`/`size`, Badge `appearance`/`tone` — and an override fights the variant's own hover, selected and focus states. Use a real variant, or add one to the component. Layout classes (width, margin, flex, position) are fine.",
+				"A look-changing class on a Sable component (border*, bg-*, rounded*, ring-*, shadow-* on Button, Pill or Badge). Their appearance is set by variants — Button `variant` (floating for a control over content), Pill `appearance`/`size`, Badge `appearance`/`tone` — and an override fights the variant's own hover, selected and focus states. Use a real variant, or add one to the component. Layout classes (width, margin, flex, position) are fine. If the component is defective rather than missing a look, patch it with `sable patch <Component>` (recorded, and re-checked on every upgrade) instead of restyling it.",
 			scan(text) {
 				const out = []
 				for (const m of openingTags(text, /^(?:Button|Pill|Badge)$/)) {