@sableui/react 0.7.0 → 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,120 @@
 # 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,
+plus guidance for choosing a page width. Nothing to migrate.
+
+- **A table in a flush card keeps the card's corners.** `Card` now clips to its
+  rounded corners when it holds a `CardContent flush`, as it already did for a
+  `CardList`. The hover fill of an edge-to-edge `Table` or `DataTable` row and a
+  `TableFooter`'s tint no longer poke square corners out past the card's.
+- **Only body rows hover.** `TableRow` lifts on hover inside `TableBody`; header
+  and footer rows stay still, since nothing there responds to a click.
+- **SideNav and Sidebar icons stay level with their labels at any spacing
+  step.** The icon box was sized in spacing steps around an icon sized in type,
+  so a theme with a step other than 4px shrank the box and dropped every icon
+  about 2px below its label. The box is now sized in the icon's own unit and
+  centred with flex.
+- **A donut's number holds the centre.** In `PieChart` and a full-ring
+  `RadialChart`, `centerLabel`'s value sits on the centre and its caption hangs
+  below, instead of the pair splitting the centre between them.
+- **`centerLabel.value` takes a number.** It is written in full up to 9,999 and
+  shortened from 10,000 on (`10.2K`, `102.1K`, `1.2M`), in the chart's
+  `locale`. A string still shows as written, for units.
+- **Presets can set page widths.** `page-inset` and the role caps
+  (`region-form`, `-feed`, `-content`, `-wide`, `-full`) are preset tokens, so a
+  product's widths live in its preset rather than app CSS. They are opt-in:
+  `sable preset --template` and Canvas exports leave them out, so a preset never
+  overrides widths an app already sets. `PAGE_WIDTH_TOKENS` lists them.
+- **Guidance for choosing a page width.** `sable docs building-a-page` has a
+  table of which `max` to use by what the person does on the page, and when to
+  go fluid. The Region docs say `full` is the largest cap (edge to edge is
+  `bleed`) and show a fluid workspace; the old "Fluid dashboard" example was
+  capped and is retitled. `reviewing-a-design` asks for a 1920px capture of a
+  capped or fluid route, where the choice shows, and the skill's brief records
+  each route's width.
+- **A pasted preset gets applied.** Canvas's "Copy for agent" message now asks
+  the agent to apply the preset and build the app, not only save it. The skill
+  treats a preset supplied for an existing app as a restyle, `sable docs
+  using-presets` has an "Apply to an existing app" section, and a passing
+  `sable preset --check` lists the steps that make an app use the preset.
+- **`TrafficTrendBlock` fits a narrow card.** Below 24rem its range toggles
+  move under the title instead of squeezing it.
+
 ## 0.7.0
 
 A dogfooding release. An agent built a music streaming app on Sable with

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/blocks/traffic-sources-block.js

@@ -24,7 +24,7 @@ function TrafficSourcesBlock({ className, framed = true }) {
         index: "source",
         valueKey: "visitors",
         donut: true,
-        centerLabel: { value: total.toLocaleString("en-US"), label: "Visitors" }
+        centerLabel: { value: total, label: "Visitors" }
       }
     ) }),
     /* @__PURE__ */ jsxs(CardFooter, { className: "text-body-sm text-muted-foreground", children: [

package/dist/blocks/traffic-trend-block.js

@@ -27,11 +27,11 @@ var shortDate = (iso) => (/* @__PURE__ */ new Date(`${iso}T00:00:00`)).toLocaleD
 function TrafficTrendBlock({ className, framed = true }) {
   const [range, setRange] = useState("90d");
   const shown = days.slice(-(ranges.find((r) => r.id === range)?.days ?? 90));
-  return /* @__PURE__ */ jsxs(Card, { variant: framed ? "default" : "flat", className: cn("w-full max-w-3xl", className), children: [
-    /* @__PURE__ */ jsxs(CardHeader, { children: [
+  return /* @__PURE__ */ jsxs(Card, { variant: framed ? "default" : "flat", className: cn("@container/trend w-full max-w-3xl", className), children: [
+    /* @__PURE__ */ jsxs(CardHeader, { className: "@max-sm/trend:has-data-[slot=card-action]:grid-cols-1", children: [
       /* @__PURE__ */ jsx(CardTitle, { render: /* @__PURE__ */ jsx("h2", {}), children: "Visitors" }),
       /* @__PURE__ */ jsx(CardDescription, { children: "Desktop and mobile, by day." }),
-      /* @__PURE__ */ jsx(CardAction, { children: /* @__PURE__ */ jsx(ToggleGroup, { value: [range], onValueChange: (v) => v[0] && setRange(String(v[0])), "aria-label": "Time range", children: ranges.map((r) => /* @__PURE__ */ jsx(Toggle, { value: r.id, children: r.label }, r.id)) }) })
+      /* @__PURE__ */ jsx(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", children: /* @__PURE__ */ jsx(ToggleGroup, { value: [range], onValueChange: (v) => v[0] && setRange(String(v[0])), "aria-label": "Time range", children: ranges.map((r) => /* @__PURE__ */ jsx(Toggle, { value: r.id, children: r.label }, r.id)) }) })
     ] }),
     /* @__PURE__ */ jsx(CardContent, { children: /* @__PURE__ */ jsx(
       AreaChart,

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/card/card.js

@@ -44,10 +44,13 @@ function Card({
         "[--card-inner-radius:max(var(--radius-sm),calc(var(--radius-lg)-var(--card-p)-1px))]",
         // Declares its surface so sable-well / sable-surface-interactive inside derive from the card.
         variant === "default" && "border border-border bg-card shadow-sm [--sable-surface-bg:var(--card)]",
-        // A CardList runs its rows to the card's edges, and an interactive
-        // row's hover fill would otherwise poke square-ish corners out past
-        // the card's rounded ones — clip to the card's own curve instead.
-        "has-data-[slot=card-list]:overflow-clip",
+        // A CardList or a flush CardContent (an edge-to-edge Table) runs its
+        // rows to the card's edges, and a row's hover fill or a TableFooter's
+        // tint would otherwise poke square corners out past the card's
+        // rounded ones — clip to the card's own curve instead. Nothing
+        // overflows on purpose here: the table insets its edge cells by
+        // --table-edge-px, so focus rings stay inside, and menus portal out.
+        "has-data-[slot=card-list]:overflow-clip has-[[data-slot=card-content][data-flush]]:overflow-clip",
         INTERACTIVE_BASE,
         INTERACTIVE_HOVER[variant],
         className

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: [