@sableui/react 0.7.1 → 0.8.0

package/AGENTS.md

@@ -36,7 +36,7 @@ These are short on purpose. Each links to a foundations doc with the full vocabu
 
    **The same goes for everything below a component. Resolve in this order, and stop at the first that fits:** (1) a **component** → (2) a Sable **utility or recipe** — relative surfaces (`sable-surface*`, `sable-well`, `sable-surface-interactive`), state variants (`sable-selected:`, `sable-highlighted:`…), geometry (`rounded-concentric-*`, `popup-inset`, `rounded-popup-item`, `popup-bleed`), scroll policies, `motion-*` recipes → (3) a **semantic token** → (4) hand-written CSS, last, and reported as a gap. `npx sable search "<what you need>"` searches all of these; `registry.json → utilities` lists the utilities with intent and what each replaces. Mixing ink into a surface by hand (`color-mix(… var(--foreground) …)`) is the tell that you skipped step 2 — that is what the relative-surface utilities compute, in every theme and mode.
 
-   **Never restyle a component with override classes to get a look it lacks.** `className` on a Sable component is for layout (width, margin, flex and grid placement, position); its look — fill, edge, corner, ring, shadow, ink — comes from a variant. Use the one that exists, and if none fits, that is a library gap to report, not a `className`. The common cases: a control floating over content is `<Button variant="floating">`, one on a coloured band `variant="on-color"`; a quiet chip is `<Pill appearance="outline" size="sm">`; a status label is `<Badge appearance="plain" tone="…" dot>`; a destructive menu row is `<MenuItem variant="destructive">` (never `className="text-destructive"`); a list of `Entity` rows in a card is `<CardList>`, and a table that runs edge to edge in a card is `<CardContent flush>`, which insets the outer columns to the card's padding (never `pl-6`/`pr-6` on cells). `sable-lint` flags these (`component-restyle`, `destructive-item-ink`, `table-edge-padding`, `popup-separator-bleed`).
+   **Never restyle a component with override classes to get a look it lacks.** `className` on a Sable component is for layout (width, margin, flex and grid placement, position); its look — fill, edge, corner, ring, shadow, ink — comes from a variant. Use the one that exists, and if none fits, that is a library gap to report, not a `className`. The common cases: a control floating over content is `<Button variant="floating">`, one on a coloured band `variant="on-color"`; a quiet chip is `<Pill appearance="outline" size="sm">`; a status label is `<Badge appearance="plain" tone="…" dot>`; a destructive menu row is `<MenuItem variant="destructive">` (never `className="text-destructive"`); a list of `Entity` rows in a card is `<CardList>`, and a table that runs edge to edge in a card is `<CardContent flush>`, which insets the outer columns to the card's padding (never `pl-6`/`pr-6` on cells). `sable-lint` flags these (`component-restyle`, `destructive-item-ink`, `table-edge-padding`, `popup-separator-bleed`). A component that is *broken*, not just missing a look, is patched in place with `sable patch <Component> --reason … --repro …` while the fix ships: the record is re-checked on every upgrade (`sable docs patching-a-component`).
 1. **Semantic tokens only.** `bg-card`, `text-muted-foreground`, `border-border`, `bg-primary` — never a palette step, never inline hex/`oklch()`. Tone fills take their paired ink (`bg-tone-success` + `text-tone-success-foreground`). → `sable docs token-intent`
 2. **Type is a closed vocabulary.** One paired utility per text node (`text-heading-2`, `text-body-md`, `text-label-lg`, `text-mono-md`); never compose `text-* font-* tracking-*` by hand. Pick by **role**, not size. One `heading-1` per route. Two colors: `foreground` and `muted-foreground` — never opacity on text. → `sable docs typography`
 3. **Space on the 4px scale, by role.** Inset, stack, inline; related things closer than unrelated things. No off-scale `p-[15px]`. Padding, gaps and insets stay on the scale (a step, or `--spacing(n)` inside an arbitrary value) so the density control moves them; fixed `rem`/`px` only for what must not scale, like a hairline. Single-column content in a card is a flex column, not a grid. → `sable docs spacing`
@@ -57,7 +57,7 @@ The machine-readable version of this section is the `consume` block in `registry
 
 1. **Install** from npm: `pnpm add @sableui/react` (or the project's package manager). No registry configuration or token is needed.
 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.
+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.
 
    `styles.css` carries **Sable only** — the default theme, and the layout floor every other theme inherits (`--page-inset`, `--region-*`, `--rhythm-unit` on a bare `:root`). The bundled **alternates are opt-in**, because they are `[data-sable-theme]`-scoped and an app that never sets the attribute ships CSS that can never match: 5.5 KB gzip of permanently-dead weight, which is exactly how a real app's build audit found this. Using one? `@import "@sableui/react/theme/prism.css";`. Offering the whole set through a `<ThemeSelector>`? `@import "@sableui/react/themes.css";`. **Symptom of forgetting:** `data-sable-theme` is set, nothing matches, and the page silently renders as the Sable theme — no error, just the wrong theme.
 4. **Fonts:** load Figtree (sans) + DM Mono (mono) — the theme declares the stacks, the host provides the files. Apply `antialiased` (`-webkit-font-smoothing: antialiased` / `-moz-osx-font-smoothing: grayscale`) **once on the app root**: Sable's type scale was drawn against smoothed text, and without it macOS renders every weight heavier than designed. The package deliberately doesn't set it — a library has no business styling the host's whole page — so it has to happen here.

package/CHANGELOG.md

@@ -1,5 +1,78 @@
 # What's new
 
+## 0.8.0
+
+The same support-workspace app was built twice, on Sable and on shadcn, and this
+release closes every gap the comparison found: two silent layout and form bugs,
+the component defects, row selection, a sanctioned way to patch a component
+while its fix ships, and CSS that only carries the components an app imports.
+
+### Upgrading from 0.7
+
+- **`<Form noValidate>` now means your code owns validation.** `onSubmit` always
+  runs and each Field shows the `error` you set; nothing checks the Fields or
+  the browser first. It used to skip only Sable's extra browser check, while
+  Form still blocked an empty `required` Field. `validationMode`, `errors`,
+  `onFormSubmit` and `actionsRef` do nothing with it. Drop `noValidate` to keep
+  Sable's validation, and word its messages with Field's new `messages`.
+- **A Switch's knob stays white when on.** It took the primary's label ink, so
+  a mid-light brand colour gave a dark knob. It now turns dark only on a track
+  lighter than L 0.9 (a dark mode's near-white primary). Set
+  `--theme-switch-thumb-on` to choose your own.
+- **PageHeader holds 20rem for its title** before actions may share its row, so
+  on a phone the actions sit under the title instead of squeezing it to one
+  word a line.
+
+### Everything in this release
+
+- **Nested `Grid`, `Col` and `SplitPane` no longer inherit their parent's
+  breakpoints.** A breakpoint a nested one left unset read its ancestor's value,
+  so a `cols={2}` Grid inside a 12-column `lg` Columns drew 12 tracks, and a
+  nested `span={6}` Col spanned 9. Each now resets its own.
+- **`Field messages`** words a failed native constraint:
+  `messages={{ valueMissing: "Enter a subject." }}`, instead of the browser's
+  "Please fill out this field."
+- **Text around an expression stays one label.** `All ({count})` rendered as
+  "All ( 12 )" in Button, Pill, Badge, NotificationBadge, Toolbar and pill Tabs:
+  each text child was its own flex item, spaced by the gap. Adjacent text now
+  joins into one.
+- **Toggle spaces an icon from its label**, like Button.
+- **SidebarHeader grows to hold a second row** (a search field under the brand)
+  instead of clipping it at 64px. Give that row `basis-full`.
+- **`BreadcrumbLink` takes `render`**, so a router link navigates in the app
+  instead of reloading the page.
+- **DataTable checkbox selection.** `selectedKeys` and `onSelectedKeysChange`
+  add a checkbox column, each box named by `rowSelectionLabel`, and a
+  select-all box that acts on the rows shown and goes mixed when some are
+  checked. Checked rows take the selected fill; a box never opens the row. The
+  docs show a bulk-action bar with a live status.
+- **`sable patch`** fixes a component in place while the library fix ships.
+  `sable patch Card --reason … --repro …` records why and how to check it, and
+  prints your package manager's patch steps (`pnpm patch`, `yarn patch`, or
+  patch-package). Every build now ships `dist/file-hashes.json`, and `sable
+  doctor` re-checks each patch on upgrade: it fails when Sable changed a
+  patched file, quoting the changelog for that component, until the repro says
+  `--keep` or `--drop`. See `sable docs patching-a-component`.
+- **`sable sources`** writes `@source` lines for just the Sable modules an app
+  imports. The whole-package `@source` ships every component's classes (about
+  32 KB gzipped); an app on Card, Button and DataTable measured 12 KB. `sable
+  doctor` fails when the file goes stale, since an unlisted component renders
+  unstyled.
+- **New lint rule `form-required-error`:** a `required` Field with an `error`
+  inside a validating Form, where that error can never show for an empty field.
+- **Icons:** `tag`, `paperclip`, `chart`, `flag` and `at-sign`.
+- **`CommandMenu` stacked rows:** `stacked` puts `detail` under the label, for
+  results only their detail tells apart.
+- **A one-setting `SettingsMenu`** opens straight to its options under the
+  row's label: one click, not two.
+- **`ChatComposer sendOn="mod-enter"`** for long-form replies: Enter breaks the
+  line, Cmd/Ctrl+Enter sends.
+- **Docs:** `sable learn --template` states its evidence rules (inside the
+  project; different before and after files); MessageScroller names its scroll
+  options (`{ animate }`, not `behavior`); Button explains `useCopy(text)`; and
+  `reviewing-a-design` says to scroll through, or capture with reduced motion,
+  before calling a below-the-fold chart empty.
+
 ## 0.7.1
 
 Fixes from building a customer-support app on 0.7.0 with an app-owned preset,

package/README.md

@@ -72,6 +72,8 @@ export default defineConfig({ resolve: { dedupe: ["react", "react-dom"] } })
 @source "../node_modules/@sableui/react/dist/**/*.{js,mjs}";
 ```
 
+That `@source` generates the classes of every Sable component, about 32 KB of CSS gzipped. Once the app is built, `npx sable sources --write src/sable-sources.css` writes `@source` lines for just the modules it imports (12 KB for an app using Card, Button and DataTable); `@import "./sable-sources.css";` in place of the line above. Re-run it after importing something new: `sable check` fails while the file is stale, since an unlisted component renders unstyled.
+
 **4. Fonts** — the default theme expects **Figtree** (sans) + **DM Mono** (mono). Each alternate preset declares its own families in its manifest (`registry.json → themes.available[].fonts`). Load whichever stacks you plan to use via `<link>` or `@font-face`; the theme manifests declare the stacks but ship no font files.
 
 **5. Providers + color mode / theme selection:**

package/bin/sable.mjs

@@ -37,6 +37,8 @@ import { dirname, join, relative, resolve } from "node:path"
 import { fileURLToPath } from "node:url"
 import { skeletonize } from "../scripts/skeleton.mjs"
 import { claudeStopHook, installAgentSkill, installClaudeStopHook } from "../scripts/agent-setup.mjs"
+import { patchChecks } from "../scripts/patches.mjs"
+import { sourcesCheck } from "../scripts/sources.mjs"
 
 const HERE = dirname(fileURLToPath(import.meta.url))
 const PKG_ROOT = join(HERE, "..")
@@ -89,6 +91,28 @@ const COMMANDS = [
 		],
 		returns: ["preset.template", "preset.check", "preset.css"],
 	},
+	{
+		name: "patch",
+		summary: "Fix a Sable component in place while the library fix ships: record why and how to check it, patch with your package manager, and have doctor re-check it on every upgrade.",
+		arg: { name: "Component", required: false },
+		flags: [
+			{ name: "--reason", value: "text", describe: "What is wrong. Required to record a patch." },
+			{ name: "--repro", value: "text", describe: "How to see it, so a later upgrade can be checked against it. Required to record a patch." },
+			{ name: "--issue", value: "id", describe: "Where it was reported upstream." },
+			{ name: "--file", value: "dist/lib/<module>.js", describe: "Also cover a shared module the component uses, or patch one on its own." },
+			{ name: "--list", value: null, describe: "Each recorded patch and its state against the installed Sable." },
+			{ name: "--keep", value: null, describe: "After an upgrade: the repro still fails on Sable's own files, so keep the patch against this version." },
+			{ name: "--drop", value: null, describe: "The repro passes on Sable's own files: drop the record (and the patch)." },
+		],
+		returns: ["patch.recorded", "patch.list", "patch.kept", "patch.dropped"],
+	},
+	{
+		name: "sources",
+		summary: "Write the @source lines for just the Sable modules this app imports, so Tailwind generates their classes and no others (about 32 KB gzipped for all of Sable, a fraction for a typical app). doctor fails while the file is stale.",
+		arg: null,
+		flags: [{ name: "--write", value: "file.css", describe: "Write the stylesheet there (e.g. src/sable-sources.css) instead of printing it." }],
+		returns: ["sources"],
+	},
 	{
 		name: "setup",
 		summary: "Install package-backed skill entry files for coding agents, preserving local edits.",
@@ -1265,6 +1289,9 @@ function doctorReport() {
 				'@source "<path-to>/@sableui/react/dist/**/*.{js,mjs}";',
 			)
 		else if (hasSable) add("pass", "css:source", "@source covers the package.")
+		// A generated per-module list (sable sources) must cover every module the
+		// app imports, or those components render unstyled.
+		if (hasSable) checks.push(...sourcesCheck(PKG_ROOT, CWD, expandedCss.map(({ path }) => cssByPath.get(path))))
 	}
 
 	/* The theme trap: opting into theme switching without importing theme CSS. */
@@ -1300,6 +1327,11 @@ function doctorReport() {
 			)
 	}
 
+	/* Local patches (sable patch): each one is re-checked against the installed
+	 * Sable, and fails when Sable changed a patched file, so an upgrade tells the
+	 * agent to re-run the repro instead of keeping or losing a fix silently. */
+	checks.push(...patchChecks(PKG_ROOT, CWD, R.version))
+
 	if (pkg && !/resolve\s*:\s*\{[^}]*dedupe|dedupe/.test(readConfigs()))
 		add("info", "dedupe", "Could not confirm React dedupe in a bundler config.", 'resolve.dedupe: ["react","react-dom"] — a second React is an invalid-hook blank page.')
 
@@ -1627,6 +1659,8 @@ const HANDLERS = {
 		ok("target", target, `iOS ${target.platformVersion}${target.status ? ` (${target.status})` : ""}: ${target.designPolicy.principle}\n${target.statusNote ? `${target.statusNote}\n` : ""}${target.designPolicy.rule}\n${(target.designPolicy.layout ?? []).map((l) => `Layout: ${l}\n`).join("")}` + Object.values(target.components).map(c => `${c.source}: ${c.strategy} → ${c.strategy === "contextual" ? "choose by role" : c.components.join(" + ") || "redesign for phone"}`).join("\n"))
 	},
 	preset: () => cmdDesignTool("design-presets.mjs"),
+	patch: () => cmdDesignTool("patches.mjs"),
+	sources: () => cmdDesignTool("sources.mjs"),
 	setup: cmdSetup,
 	check: cmdCheck,
 	provider: cmdProvider,

package/dist/components/breadcrumbs/breadcrumbs.js

@@ -1,4 +1,5 @@
 // src/components/breadcrumbs/breadcrumbs.tsx
+import { useRender } from "@base-ui/react/use-render";
 import { Icon } from "../../icon/index.js";
 import { cn } from "../../lib/cn.js";
 import { jsx } from "react/jsx-runtime";
@@ -28,20 +29,20 @@ function BreadcrumbItem({
 BreadcrumbItem.displayName = "BreadcrumbItem";
 function BreadcrumbLink({
   className,
-  ref,
+  render,
   ...props
 }) {
-  return /* @__PURE__ */ jsx(
-    "a",
-    {
-      ref,
+  return useRender({
+    render: render ?? /* @__PURE__ */ jsx("a", {}),
+    props: {
+      ...props,
       className: cn(
         "rounded-sm text-muted-foreground motion-interactive hover:text-foreground focus-visible:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
         className
-      ),
-      ...props
-    }
-  );
+      )
+    },
+    defaultTagName: "a"
+  });
 }
 BreadcrumbLink.displayName = "BreadcrumbLink";
 function BreadcrumbPage({

package/dist/components/breadcrumbs/breadcrumbs.meta.js

@@ -74,8 +74,8 @@ var breadcrumbsMeta = {
     },
     {
       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",

package/dist/components/button/button.meta.js

@@ -31,6 +31,10 @@ var buttonMeta = {
         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".'

package/dist/components/chat-composer/chat-composer.js

@@ -16,6 +16,7 @@ function ChatComposer({
   onValueChange,
   onSend,
   placeholder = "Send a message\u2026",
+  sendOn = "enter",
   busy = false,
   onStop,
   disabled = false,
@@ -69,11 +70,11 @@ function ChatComposer({
     (event) => {
       if (event.key !== "Enter") return;
       if (event.nativeEvent.isComposing) return;
-      if (event.shiftKey) return;
+      if (sendOn === "mod-enter" ? !(event.metaKey || event.ctrlKey) : event.shiftKey) return;
       event.preventDefault();
       send();
     },
-    [send]
+    [send, sendOn]
   );
   const showStop = busy && Boolean(onStop);
   return /* @__PURE__ */ jsxs(
@@ -103,6 +104,7 @@ function ChatComposer({
             autoResize: true,
             rows: 1,
             "aria-label": label,
+            "aria-keyshortcuts": sendOn === "mod-enter" ? "Meta+Enter Control+Enter" : "Enter",
             "aria-invalid": invalid || void 0,
             disabled,
             placeholder,

package/dist/components/chat-composer/chat-composer.meta.js

@@ -1,7 +1,7 @@
 // src/components/chat-composer/chat-composer.meta.ts
 var chatComposerMeta = {
   name: "ChatComposer",
-  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.',
   status: "stable",
   keywords: [
     "chat input",
@@ -46,7 +46,7 @@ var chatComposerMeta = {
       },
       {
         guidance: "dont",
-        description: "Do not use it as a general multi-line input. That is `Textarea` \u2014 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",
@@ -118,6 +118,12 @@ var chatComposerMeta = {
       default: '"Send a message\u2026"',
       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",

package/dist/components/command-menu/command-menu.js

@@ -201,6 +201,7 @@ function CommandMenuBody({
                   id: item.id ? `${listboxId}-${item.id}` : void 0,
                   icon: item.icon,
                   detail: item.detail,
+                  stacked: item.stacked,
                   hint: item.hint,
                   disabled: item.disabled,
                   onSelect: () => {
@@ -371,6 +372,7 @@ function CommandMenuItem({
   onSelect,
   icon,
   detail,
+  stacked,
   hint,
   id: idProp,
   className,
@@ -408,8 +410,13 @@ function CommandMenuItem({
       ...props,
       children: [
         icon && /* @__PURE__ */ jsx(Icon, { name: icon, className: "text-base text-muted-foreground" }),
-        /* @__PURE__ */ jsx("span", { className: "truncate", children }),
-        detail && /* @__PURE__ */ jsx("span", { className: "min-w-0 flex-1 truncate text-body-sm text-muted-foreground", children: detail }),
+        stacked ? /* @__PURE__ */ jsxs("span", { className: "flex min-w-0 flex-1 flex-col", children: [
+          /* @__PURE__ */ jsx("span", { className: "truncate", children }),
+          detail && /* @__PURE__ */ jsx("span", { className: "truncate text-body-sm text-muted-foreground", children: detail })
+        ] }) : /* @__PURE__ */ jsxs(Fragment, { children: [
+          /* @__PURE__ */ jsx("span", { className: "truncate", children }),
+          detail && /* @__PURE__ */ jsx("span", { className: "min-w-0 flex-1 truncate text-body-sm text-muted-foreground", children: detail })
+        ] }),
         hint && /* @__PURE__ */ jsx("span", { className: "ms-auto flex min-w-0 max-w-1/2 items-center ps-4 text-body-sm text-muted-foreground", children: /* @__PURE__ */ jsx("span", { className: "min-w-0 truncate", children: hint }) })
       ]
     }

package/dist/components/command-menu/command-menu.meta.js

@@ -132,7 +132,7 @@ var commandMenuMeta = {
     {
       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 \u2014 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 \u2014 and it becomes the row's DOM id (namespaced to the palette) and React key, so two rows may share a label."
     },
     {
       name: "query",
@@ -213,8 +213,8 @@ var commandMenuMeta = {
     },
     {
       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 \u2014 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 \u2014 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: [

package/dist/components/data-table/data-table.js

@@ -5,6 +5,7 @@ import { useMemo, useState } from "react";
 import { Icon } from "../../icon/index.js";
 import { cn } from "../../lib/cn.js";
 import { Button } from "../button/button.js";
+import { Checkbox } from "../checkbox/index.js";
 import {
   Table,
   TableBody,
@@ -28,6 +29,10 @@ function DataTable({
   rowKey,
   onRowClick,
   isRowSelected,
+  selectedKeys,
+  onSelectedKeysChange,
+  rowSelectionLabel = () => "Select row",
+  selectAllLabel = (count) => `Select all ${count} shown`,
   defaultSort,
   empty = "No results.",
   caption,
@@ -58,82 +63,130 @@ function DataTable({
       return sort.direction === "asc" ? c : -c;
     });
   }, [data, sort, columns]);
+  const selectable = Boolean(onSelectedKeysChange);
+  const dataIndex = selectable ? new Map(data.map((row, i) => [row, i])) : null;
+  const keyOf = (row) => {
+    const i = dataIndex?.get(row) ?? 0;
+    return rowKey ? rowKey(row, i) : i;
+  };
+  const shownKeys = selectable ? rows.map(keyOf) : [];
+  const checkedCount = selectable ? shownKeys.filter((k) => selectedKeys?.has(k)).length : 0;
+  const allChecked = shownKeys.length > 0 && checkedCount === shownKeys.length;
+  function setChecked(keys, checked) {
+    const next = new Set(selectedKeys);
+    for (const k of keys) {
+      if (checked) next.add(k);
+      else next.delete(k);
+    }
+    onSelectedKeysChange?.(next);
+  }
   return /* @__PURE__ */ jsxs(Table, { className, children: [
     caption ? /* @__PURE__ */ jsx(TableCaption, { children: caption }) : null,
-    /* @__PURE__ */ jsx(TableHeader, { children: /* @__PURE__ */ jsx(TableRow, { children: columns.map((col) => {
-      const active = sort?.key === col.key;
-      return /* @__PURE__ */ jsx(
-        TableHead,
+    /* @__PURE__ */ jsx(TableHeader, { children: /* @__PURE__ */ jsxs(TableRow, { children: [
+      selectable ? /* @__PURE__ */ jsx(TableHead, { className: "w-0", children: /* @__PURE__ */ jsx(
+        Checkbox,
         {
-          "aria-sort": active ? sort.direction === "asc" ? "ascending" : "descending" : void 0,
-          className: cn(col.align && ALIGN[col.align], col.className),
-          children: col.sortable ? (
-            // The negative inline margin cancels Button's padding so
-            // the label stays on the column's text edge; the header's
-            // own type and ink win over Button's action tier. In an
-            // end-aligned column the chevron leads, so the LABEL is
-            // what sits on the numbers' edge.
-            /* @__PURE__ */ jsxs(
-              Button,
-              {
-                variant: "ghost",
-                size: "xs",
-                onClick: () => toggleSort(col.key),
-                className: cn(
-                  "-mx-2 gap-1 text-label-md text-muted-foreground hover:text-foreground",
-                  col.align === "end" && "flex-row-reverse"
-                ),
-                children: [
-                  col.header,
-                  /* @__PURE__ */ jsx(
-                    Icon,
-                    {
-                      name: active && sort.direction === "desc" ? "chevron-down" : "chevron-up",
-                      className: cn("text-xs", !active && "opacity-60")
-                    }
-                  )
-                ]
-              }
-            )
-          ) : col.header
-        },
-        col.key
-      );
-    }) }) }),
+          "aria-label": selectAllLabel(shownKeys.length),
+          checked: allChecked,
+          indeterminate: checkedCount > 0 && !allChecked,
+          disabled: shownKeys.length === 0,
+          onCheckedChange: (checked) => setChecked(shownKeys, checked),
+          className: "align-middle"
+        }
+      ) }) : null,
+      columns.map((col) => {
+        const active = sort?.key === col.key;
+        return /* @__PURE__ */ jsx(
+          TableHead,
+          {
+            "aria-sort": active ? sort.direction === "asc" ? "ascending" : "descending" : void 0,
+            className: cn(col.align && ALIGN[col.align], col.className),
+            children: col.sortable ? (
+              // The negative inline margin cancels Button's padding so
+              // the label stays on the column's text edge; the header's
+              // own type and ink win over Button's action tier. In an
+              // end-aligned column the chevron leads, so the LABEL is
+              // what sits on the numbers' edge.
+              /* @__PURE__ */ jsxs(
+                Button,
+                {
+                  variant: "ghost",
+                  size: "xs",
+                  onClick: () => toggleSort(col.key),
+                  className: cn(
+                    "-mx-2 gap-1 text-label-md text-muted-foreground hover:text-foreground",
+                    col.align === "end" && "flex-row-reverse"
+                  ),
+                  children: [
+                    col.header,
+                    /* @__PURE__ */ jsx(
+                      Icon,
+                      {
+                        name: active && sort.direction === "desc" ? "chevron-down" : "chevron-up",
+                        className: cn("text-xs", !active && "opacity-60")
+                      }
+                    )
+                  ]
+                }
+              )
+            ) : col.header
+          },
+          col.key
+        );
+      })
+    ] }) }),
     /* @__PURE__ */ jsx(TableBody, { children: rows.length === 0 ? /* @__PURE__ */ jsx(TableRow, { children: /* @__PURE__ */ jsx(
       TableCell,
       {
-        colSpan: columns.length,
+        colSpan: columns.length + (selectable ? 1 : 0),
         className: cn(
           "text-center text-muted-foreground",
           typeof empty === "string" && "py-8"
         ),
         children: empty
       }
-    ) }) : rows.map((row, i) => /* @__PURE__ */ jsx(
-      TableRow,
-      {
-        "data-selected": isRowSelected?.(row) ? "" : void 0,
-        onClick: onRowClick ? () => onRowClick(row) : void 0,
-        tabIndex: onRowClick ? 0 : void 0,
-        onKeyDown: onRowClick ? (e) => {
-          if (e.target !== e.currentTarget) return;
-          if (e.key !== "Enter" && e.key !== " ") return;
-          e.preventDefault();
-          onRowClick(row);
-        } : void 0,
-        className: onRowClick ? "cursor-pointer focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring" : void 0,
-        children: columns.map((col) => /* @__PURE__ */ jsx(
-          TableCell,
-          {
-            className: cn(col.align && ALIGN[col.align], col.className),
-            children: col.cell ? col.cell(row) : row[col.key]
-          },
-          col.key
-        ))
-      },
-      rowKey ? rowKey(row, i) : i
-    )) })
+    ) }) : rows.map((row, i) => {
+      const key = selectable ? keyOf(row) : i;
+      const checked = selectable && Boolean(selectedKeys?.has(key));
+      return /* @__PURE__ */ jsxs(
+        TableRow,
+        {
+          "data-selected": checked || isRowSelected?.(row) ? "" : void 0,
+          onClick: onRowClick ? () => onRowClick(row) : void 0,
+          tabIndex: onRowClick ? 0 : void 0,
+          onKeyDown: onRowClick ? (e) => {
+            if (e.target !== e.currentTarget) return;
+            if (e.key !== "Enter" && e.key !== " ") return;
+            e.preventDefault();
+            onRowClick(row);
+          } : void 0,
+          className: onRowClick ? "cursor-pointer focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring" : void 0,
+          children: [
+            selectable ? (
+              // A click on the box checks it; it never opens the row.
+              /* @__PURE__ */ jsx(TableCell, { className: "w-0", onClick: (e) => e.stopPropagation(), children: /* @__PURE__ */ jsx(
+                Checkbox,
+                {
+                  "aria-label": rowSelectionLabel(row),
+                  checked,
+                  onCheckedChange: (next) => setChecked([key], next),
+                  className: "align-middle"
+                }
+              ) })
+            ) : null,
+            columns.map((col) => /* @__PURE__ */ jsx(
+              TableCell,
+              {
+                className: cn(col.align && ALIGN[col.align], col.className),
+                children: col.cell ? col.cell(row) : row[col.key]
+              },
+              col.key
+            ))
+          ]
+        },
+        rowKey ? rowKey(row, i) : i
+      );
+    }) })
   ] });
 }
 DataTable.displayName = "DataTable";

package/dist/components/data-table/data-table.meta.js

@@ -93,7 +93,29 @@ var dataTableMeta = {
     {
       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",
@@ -119,6 +141,10 @@ var dataTableMeta = {
     "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	{/* Mounted from the start, so a screen reader hears each change. */}\n	<span role="status" className="sr-only">{selected.size ? `${selected.size} of ${tickets.length} selected` : ""}</span>\n	{selected.size ? (\n		<Toolbar aria-label="Bulk actions">\n			<span className="text-label-md">{selected.size} of {tickets.length} selected</span>\n			<Button size="sm" variant="secondary" onClick={() => resolve(selected)}>Resolve</Button>\n		</Toolbar>\n	) : null}\n	<DataTable\n		data={tickets}\n		rowKey={(t) => t.id}\n		columns={columns}\n		selectedKeys={selected}\n		onSelectedKeysChange={setSelected}\n		rowSelectionLabel={(t) => `Select ${t.subject}`}\n		selectAllLabel={(n) => `Select all ${n} tickets shown`}\n	/>\n</Stack>'
+    },
     {
       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) }]} />'