@sableui/react 0.8.1 → 0.9.0

package/AGENTS.md

@@ -32,7 +32,7 @@ library gap to report, not a reason for a native control.
 
 These are short on purpose. Each links to a foundations doc with the full vocabulary, the reasoning, and before/after examples; `sable-lint` catches most violations.
 
-0. **Compose from Sable components; never rebuild one.** Before writing any interactive or recognisable element — a button, a field, a toggle, tabs, a menu, a badge, a card, a search box, a dialog — run `npx sable search "<what you need>"` and use what it returns. A raw `<button>`, `<input>` or `<div>` dressed in a component's classes is a reinvention, and it is a bug even when every class is a semantic token: it misses the component's states, density, focus and keyboard contract, and drifts the moment the component changes. A link that looks like a button is `<Button render={<a href=… />}>`. If nothing fits, compose from the nearest component's parts; if it genuinely does not exist, say so in your summary — that is a library gap to report, not a license to invent. The rules below are for styling what you compose *around* components, not for re-creating them. `sable-lint` flags the common cases (`hand-rolled-control`, `lookalike-control`), and the bigger assemblies built from utilities and tokens: a raw `grid` of mapped items is `<Grid cols minItemWidth>` (`lookalike-grid`), a link or button wearing a card's radius, surface and padding is `<Card render={<Link … />}>` (`lookalike-card`), a round fixed-size box holding a picture, GradientArt or initials is `<Avatar>` (`lookalike-avatar`), and an `aspect-*` + `overflow-hidden` frame around media is `<AspectBox ratio>` (`lookalike-media-frame`). `sable check` also lists every app-owned surface (a card fill, a bordered padded box, a media frame, a fixed-size circle) for your reuse inventory: each one composes the component named beside it, or the inventory says why the app owns it.
+0. **Compose from Sable components; never rebuild one.** Before writing any interactive or recognisable element — a button, a field, a toggle, tabs, a menu, a badge, a card, a search field, a dialog — run `npx sable search "<what you need>"` and use what it returns. This binds behaviour and parts, not layouts: results marked ◇ (patterns, blocks, compositions such as MediaTile) are references, used when their layout fits the brief. When one does not fit, compose your own from Sable's parts and behaviour. A storefront's search panel can look like nothing else in the catalog, as long as its field, list keyboard model and rows are Sable's. A raw `<button>`, `<input>` or `<div>` dressed in a component's classes is a reinvention, and it is a bug even when every class is a semantic token: it misses the component's states, density, focus and keyboard contract, and drifts the moment the component changes. A link that looks like a button is `<Button render={<a href=… />}>`. If nothing fits, compose from the nearest component's parts; if it genuinely does not exist, say so in your summary — that is a library gap to report, not a license to invent. The rules below are for styling what you compose *around* components, not for re-creating them. `sable-lint` flags the common cases (`hand-rolled-control`, `lookalike-control`), and the bigger assemblies built from utilities and tokens: a raw `grid` of mapped items is `<Grid cols minItemWidth>` (`lookalike-grid`), a link or button wearing a card's radius, surface and padding is `<Card render={<Link … />}>` (`lookalike-card`), a round fixed-size box holding a picture, GradientArt or initials is `<Avatar>` (`lookalike-avatar`), and an `aspect-*` + `overflow-hidden` frame around media is `<AspectBox ratio>` (`lookalike-media-frame`). `sable check` also lists every app-owned surface (a card fill, a bordered padded box, a media frame, a fixed-size circle) for your reuse inventory: each one composes the component named beside it, or the inventory says why the app owns it.
 
    **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.
 
@@ -55,7 +55,7 @@ Pick a theme as a starting point, then override tokens on top of it. Every token
 
 The machine-readable version of this section is the `consume` block in `registry.json`.
 
-1. **Install** from npm: `pnpm add @sableui/react` (or the project's package manager). No registry configuration or token is needed.
+1. **Install** from npm: `pnpm add @sableui/react` (or the project's package manager). No registry configuration or token is needed. Sable depends on no router, data or form library, and keeps whatever the project already uses: links, menus and nav items take any router's link through `render` (`render={<Link to="/inbox" />}` is TanStack Router's or React Router's `Link` alike). For a blank-slate app, the suggested stack is Vite + TypeScript with TanStack Router, TanStack Query, TanStack Form for forms with validation logic, and TanStack Table once a table outgrows `DataTable` (`sable docs tables-with-tanstack`).
 2. **Dedupe React** in the bundler (`resolve.dedupe: ["react","react-dom"]`) — Base UI must not resolve a second React, or you get an "invalid hook call" blank page.
 3. **CSS, in order:** `@import "tailwindcss";` → `@import "@sableui/react/styles.css";` → `@source "<node_modules>/@sableui/react/dist/**/*.{js,mjs}";` so Tailwind scans the package's classes. That ships every component's classes (about 32 KB gzipped); before shipping, `sable sources --write src/sable-sources.css` lists just the modules the app imports, imported in place of that `@source`, and `sable check` fails when it goes stale.
 

package/CHANGELOG.md

@@ -1,5 +1,102 @@
 # What's new
 
+## 0.9.0
+
+A storefront built on 0.8.2 (and the same brief on shadcn) found the seams
+below: focus lost after async actions, controls clipped in accordions, and
+slots a shop needs that the parts did not have. It also built its own search
+panel, and it was good. This release makes that the expected outcome rather
+than a rule bent.
+
+### Apps on Sable shouldn't all look alike
+
+- **Behaviour is fixed; layout is yours.** The skill and `AGENTS.md` now sort
+  the catalog three ways. Behaviour (controls, fields, overlays, anything with
+  focus or keys) is always used. Parts (Card, Entity, AspectBox, Badge) are
+  composed freely. References (patterns, blocks, and compositions such as
+  MediaTile) are used when their layout fits the brief; otherwise the agent
+  composes its own from parts, and that is not a gap.
+- **Signature surfaces.** The brief names the one to three surfaces where a
+  product's identity lives (a shop's product card and search). The agent
+  designs those from the brief's direction, and takes Sable's defaults
+  everywhere else.
+- **`sable search` and `sable component` mark references** with ◇ and name
+  the parts to compose your own from (`reference` and `parts` in JSON).
+- **`sable check`'s surface list reads as notes.** "→ Sable has Card"
+  replaces "→ consider Card", and the reuse inventory records "used it" or
+  "kept ours, because…" with neither treated as a failure. A new note flags
+  arrow keys handled by hand: list keyboard navigation is behaviour CommandMenu,
+  Combobox, Menu and Toolbar already own.
+
+### Upgrading from 0.8
+
+- **Button `loading` no longer sets `disabled`.** A busy native button gets
+  `aria-disabled` and refuses presses itself, so it keeps focus. Disabling the
+  focused button sent focus to `<body>`, and a sheet the action opened had
+  nowhere to return it. A test asserting `toBeDisabled()` on a loading button
+  checks `aria-disabled="true"` now.
+- **A horizontal Field is a few pixels taller.** Its row is padded to a
+  Switch's height, so the control no longer overflows the Field's box.
+
+### Fixes
+
+- **Focus moves to the first invalid field after your own validation.** Form
+  focused it only for its own checks. Errors your handler sets on Fields now get
+  the same, once `onSubmit` (or the promise it returns) is done, with or
+  without `noValidate`.
+- **Controls in an AccordionPanel are no longer clipped.** The first checkbox
+  or switch lost its top edge, and focus rings their left edge.
+  `motion-disclosure` clips with a small margin, and horizontal Fields contain
+  their control.
+- **Toasts keep clear of an open Sheet.** A toast on the sheet's edge covered
+  its footer (Check out) or its close button. With room, the stack moves beside
+  the sheet; on a narrow screen, a bottom stack moves to the top.
+- **Field forwards `data-*`, `id` and other props to its root.**
+- **`sable grade` accepts native input attributes** (`inputMode`,
+  `enterKeyHint`, `autoCapitalize`, `autoCorrect`, `pattern`, `list`, `accept`,
+  `capture`). It flagged the ones the form contract asks for.
+- **`sable check` warns when `sable sources` trims nothing.** With the
+  whole-package `@source` still beside the generated file, Tailwind scans all
+  of Sable anyway.
+
+### New
+
+- **Button `onClick` can return a promise.** The button shows `loading` until
+  it settles and ignores presses meanwhile, from the first click on. A `busy`
+  flag in state took effect a render late, so three fast clicks added three
+  items.
+- **Field `trailing`.** Vertically, it sits beside the control: a promo code's
+  Apply button. Horizontally, it sits at the end of the label's line: a facet
+  count.
+- **RadioCard `trailing`,** end-aligned on the title's line: a delivery
+  option's price.
+- **MediaTile `meta`, `srcSet` and `sizes`.** `meta` holds the lines under the
+  subtitle (price, sale price, finishes, a Badge), so a product tile is a
+  MediaTile.
+- **CommandMenu items take `leading`** (a thumbnail or Avatar in place of
+  `icon`), and the field has a clear button once there is a query.
+- **`Fieldset variant="plain"`:** the group and its legend without the card.
+  It names a radio group inside a form that is already framed.
+- **Stepper compacts on a phone.** A horizontal stepper narrower than 28rem
+  keeps every disc and only the current step's title; the other titles stay
+  for screen readers.
+- **`SkipLink`,** AppShell's skip link on its own, for layouts that are not an
+  AppShell.
+
+## 0.8.2
+
+- **A suggested stack for blank-slate apps.** Sable still depends on no router,
+  data or form library, and an app keeps the ones it has. Starting from
+  nothing, the skill, `AGENTS.md`, `sable docs getting-started` and the install
+  recipe (`registry.json` → `consume.stack`) now suggest Vite + TypeScript with
+  TanStack Router, TanStack Query, TanStack Form for forms with validation
+  logic, and TanStack Table once a table outgrows `DataTable`.
+- **`sable docs tables-with-tanstack`:** when to move from `DataTable` to
+  TanStack Table (server-side data, column visibility or resizing, grouping,
+  virtualised rows), and how to render it with Sable's `Table` parts,
+  `Checkbox`, `Button` and `Pagination`, with server data through TanStack
+  Query and bulk-action selection. `DataTable` stays dependency-free.
+
 ## 0.8.1
 
 - **`sable check` shows doctor's notes.** Warnings and notes from `sable doctor`

package/bin/sable.mjs

@@ -608,7 +608,7 @@ function cmdSearch() {
 	const pool = []
 	if (!type || type === "component")
 		for (const c of COMPONENTS)
-			pool.push({ kind: "component", name: c.name, summary: c.summary, status: c.status, group: c.group, _s: score({ name: c.name, keywords: c.keywords, text: `${c.summary} ${c.usage?.description ?? ""}` }) })
+			pool.push({ kind: "component", name: c.name, summary: c.summary, status: c.status, group: c.group, ...(c.composition ? { reference: true, parts: c.composition } : {}), _s: score({ name: c.name, keywords: c.keywords, text: `${c.summary} ${c.usage?.description ?? ""}` }) })
 	if (!type || type === "provider")
 		for (const p of PROVIDERS)
 			pool.push({ kind: "provider", name: p.name, summary: p.summary, _s: score({ name: p.name, keywords: ["provider", ...(p.companions ?? [])], text: `${p.summary} ${p.placement ?? ""}` }) })
@@ -646,15 +646,26 @@ function cmdSearch() {
 			"Try a single word — search is term-wise, not phrase-wise",
 		])
 
-	const results = hits.map(({ _s, ...h }) => ({ ...h, retrieve: `sable ${h.kind === "doc" ? "docs" : h.kind} ${h.name}` }))
+	// Patterns, blocks and composition components are designed arrangements,
+	// not behaviour: references to use when their layout fits the brief. Marked
+	// so an agent does not take the nearest one as the required answer.
+	const results = hits.map(({ _s, ...h }) => ({
+		...h,
+		...(h.kind === "pattern" || h.kind === "block" ? { reference: true } : {}),
+		retrieve: `sable ${h.kind === "doc" ? "docs" : h.kind} ${h.name}`,
+	}))
+	const anyReference = results.some((h) => h.reference)
 	ok("search", { query, count: results.length, results }, () =>
-		results
-			.map((h) =>
+		[
+			...results.map((h) =>
 				DENSE
-					? `${h.kind}/${h.name}`
-					: `${h.kind.padEnd(9)} ${h.name.padEnd(24)} ${firstSentence(h.summary ?? "")}`,
-			)
-			.join("\n"),
+					? `${h.kind}/${h.name}${h.reference ? " (reference)" : ""}`
+					: `${h.kind.padEnd(9)} ${`${h.name}${h.reference ? " ◇" : ""}`.padEnd(24)} ${firstSentence(h.summary ?? "")}`,
+			),
+			...(anyReference && !DENSE
+				? ["", "◇ a reference layout: use it when it fits the brief, or compose your own from Sable's parts. Either is fine. Behaviour components (controls, overlays, fields) are always used, never rebuilt."]
+				: []),
+		].join("\n"),
 	)
 }
 
@@ -726,6 +737,7 @@ function cmdComponent() {
 		register: c.register,
 		import: importLine(c.name),
 		summary: c.summary,
+		...(c.composition ? { composition: c.composition } : {}),
 	}
 	if (level !== "brief") {
 		data.props = c.props ?? []
@@ -744,6 +756,9 @@ function cmdComponent() {
 		[
 			`${c.name}  [${c.status}]  ${c.group}  register:${c.register}`,
 			c.summary,
+			c.composition
+				? `Reference layout: use it when it fits the brief, or compose your own from ${c.composition}.`
+				: "",
 			`\n${data.import}`,
 			level === "brief" ? "" : renderProps(c),
 			level !== "full" || DENSE ? "" : renderUsage(c),
@@ -1442,7 +1457,7 @@ const MANUAL_REVIEW = [
 	{ step: "Walk the journey", how: "sable docs reviewing-a-journey — operate the primary task and its recovery path end to end; loading, empty, error and success states; keyboard and touch." },
 	{ step: "Review the motion", how: "sable docs reviewing-motion — observe playback and interruption for anything that moves." },
 	{ step: "Check reduced motion", how: "Turn on prefers-reduced-motion (or MotionProvider \"reduced\"): state still changes, nothing essential depends on animation, nothing keeps moving." },
-	{ step: "Write the reuse inventory", how: "List the Sable components, parts, utilities and token groups used, and every app-owned UI or CSS addition with the catalog search that justified it. Start from the app-owned surfaces sable check lists (sable grade --json → inventory): each composes the component named beside it, or the inventory says why the app owns it." },
+	{ step: "Write the reuse inventory", how: "List the Sable components, parts, utilities and token groups used, and every app-owned UI or CSS addition with the catalog search that justified it. Start from the app-owned surfaces sable check lists (sable grade --json → inventory) and note, for each, whether you used the Sable part named beside it or kept your own. Either is fine for layout and look. Behaviour (controls, overlays, keyboard handling) comes from Sable." },
 	{ step: "Record what you learned", how: "sable docs learning-from-builds — keep conditional lessons with evidence (sable learn --record); never record human approval you did not get." },
 ]
 
@@ -1557,8 +1572,8 @@ function cmdCheck() {
 		if (!list.length) return ""
 		return [
 			"",
-			`App-owned surfaces for the reuse inventory (review, not failures) — ${list.length}:`,
-			...list.slice(0, MAX_DETAILS).map((s) => `      ${s.file}:${s.line}  <${s.tag}> ${s.kind} (${s.classes}) → ${s.consider}`),
+			`App-owned surfaces, for the reuse inventory — ${list.length}. Notes, not failures: use the Sable part named if it fits your design, or keep yours.`,
+			...list.slice(0, MAX_DETAILS).map((s) => `      ${s.file}:${s.line}  <${s.tag}> ${s.kind} (${s.classes}) → Sable has ${s.consider}`),
 			...(list.length > MAX_DETAILS ? [`      … ${list.length - MAX_DETAILS} more: sable grade ${paths.join(" ")} --json → inventory.surfaces`] : []),
 			"",
 		].join("\n")

package/dist/blocks/index.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { B as BlockMeta } from '../meta-CcE_SeFu.js';
+import { B as BlockMeta } from '../meta-DVG8ceze.js';
 
 interface ApiKeysBlockProps {
     className?: string;

package/dist/components/app-shell/app-shell.js

@@ -1,7 +1,7 @@
 // src/components/app-shell/app-shell.tsx
 import { cn } from "../../lib/cn.js";
-import { buttonVariants } from "../button/button.variants.js";
 import { AppShellDock } from "./app-shell-dock.js";
+import { SkipLink } from "./skip-link.js";
 import { jsx, jsxs } from "react/jsx-runtime";
 function AppShell({
   banners,
@@ -26,17 +26,7 @@ function AppShell({
       ),
       ...rest,
       children: [
-        /* @__PURE__ */ jsx(
-          "a",
-          {
-            href: "#main-content",
-            className: cn(
-              buttonVariants({ variant: "primary", size: "sm" }),
-              "text-label-md sr-only focus:not-sr-only focus:fixed focus:start-2 focus:top-2 focus:z-(--z-skip-link)"
-            ),
-            children: "Skip to content"
-          }
-        ),
+        /* @__PURE__ */ jsx(SkipLink, {}),
         banners ? /* @__PURE__ */ jsx("div", { className: "relative z-(--z-nav)", children: banners }) : null,
         header,
         /* @__PURE__ */ jsxs("div", { className: "flex min-h-0 flex-1", children: [

package/dist/components/app-shell/app-shell.meta.js

@@ -115,6 +115,13 @@ var appShellMeta = {
       description: "Floating overlays \u2014 a message launcher, FAB, or modal mount points."
     }
   ],
+  subcomponents: [
+    {
+      name: "SkipLink",
+      type: 'ComponentProps<"a">',
+      description: 'AppShell\'s skip link on its own, for a layout that is not an AppShell (a storefront with a top header). Put it first in the body and give the page\'s <main> the matching id: `<SkipLink />` then `<main id="main-content" tabIndex={-1}>`. `href` defaults to #main-content, the label to "Skip to content".'
+    }
+  ],
   a11y: [
     "Renders a skip link to #main-content as the first focusable element.",
     'Wraps content in a <main id="main-content"> landmark.',
@@ -148,6 +155,21 @@ var appShellMeta = {
     <PageHeader title="Home" description="Latest posts from artists you follow." />
   </Region>
 </AppShell>`
+    },
+    {
+      label: "SkipLink in a layout of your own",
+      code: `<>
+  <SkipLink />
+  <header className="flex items-center justify-between px-(--page-inset) py-4">
+    <Link to="/">Alder & Lune</Link>
+    <Button variant="ghost" size="icon" aria-label="Search"><Icon name="search" /></Button>
+  </header>
+  <main id="main-content" tabIndex={-1}>
+    <Region max="wide">
+      <PageHeader title="Lighting" />
+    </Region>
+  </main>
+</>`
     },
     {
       label: "Minimal (sidebar + content only)",

package/dist/components/app-shell/index.js

@@ -1,7 +1,9 @@
 // src/components/app-shell/index.ts
 import { AppShell } from "./app-shell.js";
+import { SkipLink } from "./skip-link.js";
 import { appShellMeta } from "./app-shell.meta.js";
 export {
   AppShell,
+  SkipLink,
   appShellMeta
 };

package/dist/components/app-shell/skip-link.js

@@ -0,0 +1,28 @@
+// src/components/app-shell/skip-link.tsx
+import { cn } from "../../lib/cn.js";
+import { buttonVariants } from "../button/button.variants.js";
+import { jsx } from "react/jsx-runtime";
+function SkipLink({
+  href = "#main-content",
+  children = "Skip to content",
+  className,
+  ...props
+}) {
+  return /* @__PURE__ */ jsx(
+    "a",
+    {
+      href,
+      className: cn(
+        buttonVariants({ variant: "primary", size: "sm" }),
+        "text-label-md sr-only focus:not-sr-only focus:fixed focus:start-2 focus:top-2 focus:z-(--z-skip-link)",
+        className
+      ),
+      ...props,
+      children
+    }
+  );
+}
+SkipLink.displayName = "SkipLink";
+export {
+  SkipLink
+};

package/dist/components/button/button.js

@@ -1,5 +1,9 @@
 // src/components/button/button.tsx
-import { useContext } from "react";
+import {
+  useContext,
+  useRef,
+  useState
+} from "react";
 import { useRender } from "@base-ui/react/use-render";
 import { cn } from "../../lib/cn.js";
 import { useTypeTier } from "../../lib/density.js";
@@ -31,19 +35,38 @@ function Button({
   bleed,
   disabled,
   children,
+  onClick,
   ...props
 }) {
   const tier = useTypeTier();
   const isNativeButton = render === void 0;
+  const [pending, setPending] = useState(false);
+  const pendingRef = useRef(false);
+  const busy = loading || pending;
+  const handleClick = (event) => {
+    if (busy || pendingRef.current || !isNativeButton && disabled) {
+      event.preventDefault();
+      return;
+    }
+    const result = onClick?.(event);
+    if (typeof result?.then === "function") {
+      pendingRef.current = true;
+      setPending(true);
+      result.finally(() => {
+        pendingRef.current = false;
+        setPending(false);
+      });
+    }
+  };
   const stacked = useContext(StackedActionsContext) && !String(size ?? "md").startsWith("icon");
   const resolvedSize = stacked ? "cta" : size ?? "md";
   const hasLabel = children != null && children !== false;
   const spinner = /* @__PURE__ */ jsx(Spinner, { className: "size-(--button-icon)", thickness: 2 });
-  const start = loading ? spinner : iconStart;
+  const start = busy ? spinner : iconStart;
   const iconOnly = String(resolvedSize).startsWith("icon");
-  const inner = loading && iconOnly ? spinner : /* @__PURE__ */ jsxs(Fragment, { children: [
+  const inner = busy && iconOnly ? spinner : /* @__PURE__ */ jsxs(Fragment, { children: [
     start,
-    trimLabel(loading ? loadingLabel ?? children : children),
+    trimLabel(busy ? loadingLabel ?? children : children),
     iconEnd
   ] });
   const content = badge != null ? /* @__PURE__ */ jsxs("span", { "data-slot": "button-badge-anchor", className: "relative inline-flex items-center gap-(--control-gap)", children: [
@@ -67,16 +90,20 @@ function Button({
         tier.action,
         optical,
         resolvedBleed && resolvedBleed !== "auto" && resolvedBleed !== "none" ? BLEED_CLASS[resolvedBleed] : null,
-        // Busy is not disabled. Loading sets `disabled` so the action cannot
+        // Busy is not disabled. Loading refuses presses so the action cannot
         // double-fire, but fading it to 50% made a working button read as an
         // unavailable one. It keeps full colour; the spinner says "working".
-        loading ? "cursor-progress disabled:opacity-100 aria-disabled:opacity-100" : null,
+        busy ? "cursor-progress disabled:opacity-100 aria-disabled:opacity-100" : null,
         className
       ),
       children: content,
+      onClick: handleClick,
       ...resolvedBleed ? { "data-bleed": resolvedBleed } : null,
-      ...loading ? { "aria-busy": true } : null,
-      ...isNativeButton ? { disabled: disabled || loading } : loading || disabled ? { "aria-disabled": true } : null
+      ...busy ? { "aria-busy": true } : null,
+      // A busy native button stays focusable: aria-disabled, with presses
+      // refused in handleClick. `disabled` would move focus to <body>.
+      ...isNativeButton && disabled ? { disabled: true } : null,
+      ...busy || !isNativeButton && disabled ? { "aria-disabled": true } : null
     },
     defaultTagName: "button"
   });

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

@@ -126,7 +126,12 @@ var buttonMeta = {
       name: "loading",
       type: "boolean",
       default: "false",
-      description: "Disable the button and show a leading Spinner while an action is in flight. Sets aria-busy; a native button is disabled, a render element (e.g. an <a>) gets aria-disabled."
+      description: "Show a leading Spinner while an action is in flight and refuse presses. Sets aria-busy and aria-disabled, never the native disabled: disabling the focused button sent focus to <body>, so a sheet the action opened had nowhere to return it."
+    },
+    {
+      name: "onClick",
+      type: "(event: MouseEvent<HTMLButtonElement>) => unknown",
+      description: "May return a promise: the button shows `loading` until it settles and ignores further presses meanwhile, from the first click on. Prefer it to a `busy` flag in state, which takes effect a render late (three fast clicks ran three times)."
     },
     {
       name: "badge",

package/dist/components/card/card.meta.js

@@ -81,7 +81,7 @@ var cardMeta = {
       name: "variant",
       type: '"default" | "flat"',
       default: '"default"',
-      description: '"default" raises with bg-card + border + soft shadow; "flat" is transparent.'
+      description: '"default" raises with bg-card + border + soft shadow; "flat" is transparent, for a card inside a section that already frames it. A flat card made a link or button shows its shape only on hover (the muted fill), so over a photo with square bottom corners it reads as a cropped image at rest: give a linked media card the default variant.'
     },
     {
       name: "density",

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

@@ -20,6 +20,8 @@ import {
   DialogDescription,
   DialogTitle
 } from "../dialog/dialog.js";
+import { mergeRefs } from "../../lib/refs.js";
+import { Button } from "../button/index.js";
 import { Scroller } from "../scroller/scroller.js";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 function defaultFilter(items, query) {
@@ -55,6 +57,8 @@ function CommandMenuBody({
 }) {
   const [activeId, setActiveId] = useState(null);
   const listRef = useRef(null);
+  const inputRef = useRef(null);
+  const mergedInputRef = useMemo(() => mergeRefs(inputRef, inputProps?.ref), [inputProps?.ref]);
   const listboxId = useId();
   const tier = useTypeTier();
   const grouped = useMemo(() => {
@@ -163,6 +167,7 @@ function CommandMenuBody({
           autoFocus: !inline,
           type: "text",
           ...inputProps,
+          ref: mergedInputRef,
           "data-command-menu-input": inline ? void 0 : "",
           role: "combobox",
           "aria-expanded": true,
@@ -179,7 +184,25 @@ function CommandMenuBody({
             inputProps?.className
           )
         }
-      )
+      ),
+      query ? (
+        // Empties the query and hands focus back to the field, which owns
+        // the keyboard (the list is driven from it).
+        /* @__PURE__ */ jsx(
+          Button,
+          {
+            variant: "ghost",
+            size: "icon-xs",
+            "aria-label": "Clear search",
+            className: "-my-1 text-muted-foreground hover:text-foreground",
+            onClick: () => {
+              setQuery("");
+              inputRef.current?.focus();
+            },
+            children: /* @__PURE__ */ jsx(Icon, { name: "xmark" })
+          }
+        )
+      ) : null
     ] }),
     /* @__PURE__ */ jsx("div", { role: "status", "aria-live": "polite", className: "sr-only", children: resultCount === 0 ? "No results" : `${resultCount} result${resultCount === 1 ? "" : "s"}` }),
     /* @__PURE__ */ jsxs(
@@ -200,6 +223,7 @@ function CommandMenuBody({
                 {
                   id: item.id ? `${listboxId}-${item.id}` : void 0,
                   icon: item.icon,
+                  leading: item.leading,
                   detail: item.detail,
                   stacked: item.stacked,
                   hint: item.hint,
@@ -371,6 +395,7 @@ function CommandMenuGroup({
 function CommandMenuItem({
   onSelect,
   icon,
+  leading,
   detail,
   stacked,
   hint,
@@ -409,7 +434,7 @@ function CommandMenuItem({
       ),
       ...props,
       children: [
-        icon && /* @__PURE__ */ jsx(Icon, { name: icon, className: "text-base text-muted-foreground" }),
+        leading != null ? /* @__PURE__ */ jsx("span", { "aria-hidden": "true", className: "flex shrink-0 items-center", children: leading }) : icon && /* @__PURE__ */ jsx(Icon, { name: icon, className: "text-base text-muted-foreground" }),
         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 })

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

@@ -31,6 +31,10 @@ var dataTableMeta = {
         guidance: "do",
         description: "Pair server-side datasets with Pagination and pass already-sorted/paged rows."
       },
+      {
+        guidance: "do",
+        description: "Move to TanStack Table, rendered with Sable's Table parts, once the table needs server-side sorting or filtering, column visibility or resizing, grouping, or virtualised rows. DataTable stays dependency-free and does not grow into a data grid; `sable docs tables-with-tanstack` maps one onto the other."
+      },
       {
         guidance: "dont",
         description: "Make every row clickable and also fill it with competing buttons. Choose a clear row interaction model."

package/dist/components/date-tile/date-tile.meta.js

@@ -32,6 +32,7 @@ var dateTileMeta = {
     components: ["Entity", "Card", "RelativeTime", "Calendar"]
   },
   status: "stable",
+  composition: "a <time> element with the type tiers, on a surface utility",
   props: [
     {
       name: "date",

package/dist/components/feedback/feedback.meta.js

@@ -3,6 +3,7 @@ var feedbackMeta = {
   name: "Feedback",
   summary: "A compact feedback popover. Composes Popover + Textarea + Button + Toggle into a rating row plus a message field; submitting reports the rating + message and closes the popover.",
   status: "stable",
+  composition: "Popover, Textarea, ToggleGroup, Button",
   keywords: [
     "feedback",
     "sentiment",

package/dist/components/fieldset/fieldset.js

@@ -1,18 +1,23 @@
 // src/components/fieldset/fieldset.tsx
 import { Fieldset as Base } from "@base-ui/react/fieldset";
+import { createContext, useContext } from "react";
 import { cn } from "../../lib/cn.js";
 import { jsx } from "react/jsx-runtime";
-function Fieldset({ className, ...props }) {
-  return /* @__PURE__ */ jsx(
+var VariantContext = createContext("card");
+function Fieldset({ className, variant = "card", ...props }) {
+  return /* @__PURE__ */ jsx(VariantContext.Provider, { value: variant, children: /* @__PURE__ */ jsx(
     Base.Root,
     {
+      "data-variant": variant,
       className: cn(
         // min-w-0: a native <fieldset> defaults to min-inline-size: min-content
-        // and would refuse to shrink below its widest control. overflow-hidden
-        // keeps the footer's wash inside the rounded corners.
-        // Publishes its surface like Card, so wells, stepper discs and
-        // interactive rows inside derive from the card, not the page.
-        "min-w-0 overflow-hidden rounded-lg border border-border bg-card text-card-foreground shadow-sm [--sable-surface-bg:var(--card)]",
+        // and would refuse to shrink below its widest control.
+        variant === "plain" ? "flex min-w-0 flex-col gap-2" : (
+          // overflow-hidden keeps the footer's wash inside the rounded corners.
+          // Publishes its surface like Card, so wells, stepper discs and
+          // interactive rows inside derive from the card, not the page.
+          "min-w-0 overflow-hidden rounded-lg border border-border bg-card text-card-foreground shadow-sm [--sable-surface-bg:var(--card)]"
+        ),
         // No opacity of its own: a disabled fieldset disables every control
         // in it, and each already dims to 50% — dimming here as well stacked
         // to ~30%, against 50% everywhere else in the system.
@@ -20,14 +25,15 @@ function Fieldset({ className, ...props }) {
       ),
       ...props
     }
-  );
+  ) });
 }
 Fieldset.displayName = "Fieldset";
 function FieldsetLegend({ className, ...props }) {
+  const plain = useContext(VariantContext) === "plain";
   return /* @__PURE__ */ jsx(
     Base.Legend,
     {
-      className: cn("px-6 pt-6 text-title-lg text-foreground", className),
+      className: cn(plain ? "text-label-lg text-foreground" : "px-6 pt-6 text-title-lg text-foreground", className),
       ...props
     }
   );
@@ -37,11 +43,12 @@ function FieldsetDescription({
   className,
   ...props
 }) {
+  const plain = useContext(VariantContext) === "plain";
   return /* @__PURE__ */ jsx(
     "p",
     {
       "data-slot": "fieldset-description",
-      className: cn("px-6 text-body-sm text-muted-foreground", className),
+      className: cn(plain ? "text-body-sm text-muted-foreground" : "px-6 text-body-sm text-muted-foreground", className),
       ...props
     }
   );
@@ -51,19 +58,21 @@ function FieldsetContent({
   className,
   ...props
 }) {
-  return /* @__PURE__ */ jsx("div", { className: cn("space-y-4 px-6 py-4 last:pb-6", className), ...props });
+  const plain = useContext(VariantContext) === "plain";
+  return /* @__PURE__ */ jsx("div", { className: cn(plain ? "space-y-4" : "space-y-4 px-6 py-4 last:pb-6", className), ...props });
 }
 FieldsetContent.displayName = "FieldsetContent";
 function FieldsetFooter({
   className,
   ...props
 }) {
+  const plain = useContext(VariantContext) === "plain";
   return /* @__PURE__ */ jsx(
     "div",
     {
       className: cn(
-        "flex justify-end gap-2 border-t border-border bg-muted/30 px-6 py-4",
-        "[[data-slot=fieldset-description]+&]:mt-6",
+        plain ? "flex justify-end gap-2 pt-2" : "flex justify-end gap-2 border-t border-border bg-muted/30 px-6 py-4",
+        !plain && "[[data-slot=fieldset-description]+&]:mt-6",
         className
       ),
       ...props