@sableui/react 0.11.0 → 0.12.0

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 (sendOn="mod-enter" swaps them for long-form replies), 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; on touch, Return always breaks the line), and send becomes stop while a reply streams. allowEmpty sends attachments without text.',
   status: "stable",
   keywords: [
     "chat input",
@@ -16,6 +16,10 @@ var chatComposerMeta = {
   usage: {
     description: "Pairs with MessageScroller to make a working chat. A single surface rather than an input with buttons parked beside it: attachments above, text in the middle, affordances along the bottom. Works controlled or uncontrolled \u2014 uncontrolled is the default because it is what the common case wants, and what lets a hook-free page shell ship a composer that actually types.",
     bestPractices: [
+      {
+        guidance: "do",
+        description: "Wiring it to a streaming source? `sable docs building-a-chat` maps a turn lifecycle (submitted, streaming, done, stopped, error) onto `busy`, `onStop` and `disabled`, and says where each failure goes."
+      },
       {
         guidance: "do",
         description: "Pass `busy` while a reply streams, and `onStop` alongside it. Interrupting a long generation is the most common thing a reader wants during one, and the control belongs where their cursor already is."
@@ -28,6 +32,10 @@ var chatComposerMeta = {
         guidance: "do",
         description: "Render pending uploads as `<Attachment>` chips in `attachments`, so the file and the message it belongs to stay in one box."
       },
+      {
+        guidance: "do",
+        description: 'Pass `allowEmpty={files.length > 0}` when a file can go without a caption. Send enables on the attachment alone and `onSend` receives `""`. Tie it to the pending files: a constant `allowEmpty` leaves send enabled with nothing to send.'
+      },
       {
         guidance: "do",
         description: "Put model pickers and tool toggles in `leading`, beside the attach button \u2014 they are composer state, not message content, and belong on the chrome row rather than in the field."
@@ -38,7 +46,7 @@ var chatComposerMeta = {
       },
       {
         guidance: "dont",
-        description: "Do not add your own Enter-to-send handler on top. The built-in one already guards against firing mid-IME-composition, which is the line hand-rolled chat inputs miss."
+        description: "Do not add your own Enter-to-send handler on top. The built-in one already guards against firing mid-IME-composition, and on a touch device lets Return break the line (a soft keyboard has no Shift+Return), which are the lines hand-rolled chat inputs miss."
       },
       {
         guidance: "do",
@@ -110,7 +118,13 @@ var chatComposerMeta = {
     {
       name: "onSend",
       type: "(value: string) => void",
-      description: "Called with the trimmed message. An uncontrolled composer clears itself afterwards; a controlled one is the caller's to clear."
+      description: 'Called with the trimmed message. An uncontrolled composer clears itself afterwards; a controlled one is the caller\'s to clear. With `allowEmpty` the message can be `""`.'
+    },
+    {
+      name: "allowEmpty",
+      type: "boolean",
+      default: "false",
+      description: 'Let the reader send with no text, because the app has something else to send (pending attachments). Pass it only while that is true, `allowEmpty={files.length > 0}`; `onSend` then receives `""`.'
     },
     {
       name: "placeholder",
@@ -122,7 +136,7 @@ var chatComposerMeta = {
       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").'
+      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"). On a touch device (pointer: coarse) enter behaves as mod-enter: a soft keyboard has no Shift+Return, so Return breaks the line and the send button sends.'
     },
     {
       name: "busy",
@@ -187,13 +201,13 @@ var chatComposerMeta = {
     },
     {
       name: "footer",
-      type: "ReactNode",
-      description: "Helper text or counter below the controls."
+      type: 'ReactNode | ((state: { sendOn: "enter" | "mod-enter" }) => ReactNode)',
+      description: 'Helper text or counter below the controls. For a keyboard hint pass a function: it receives the send key in effect (touch turns `enter` into `mod-enter`), and returning null removes the row, e.g. `footer={({ sendOn }) => sendOn === "enter" ? "Enter to send" : null}`.'
     },
     {
       name: "fieldRef",
       type: "Ref<HTMLTextAreaElement>",
-      description: "Ref to the underlying textarea \u2014 for focusing after a send, or on mount."
+      description: "Ref to the underlying textarea \u2014 for focusing after a send, or on mount, and the extension point for anything that listens to the field. Pass `useCaretTrigger`'s `fieldRef` here for mentions and slash commands (CaretMenu). An Enter another listener already handled (`preventDefault()`) does not send."
     },
     {
       name: "...form props",
@@ -220,7 +234,8 @@ var chatComposerMeta = {
     "A real `<form>`, so the send button is a submit button and the whole thing behaves as one control to assistive tech and to password managers alike.",
     "Enter never submits while an IME composition is open (`isComposing`), so a CJK reader confirming a candidate word does not mail a fragment of their first sentence.",
     "The focus ring is drawn on the surface via `focus-within`, not on the textarea, so the visible focus indicator matches the box a sighted user perceives as the input.",
-    "Send is disabled \u2014 not merely styled down \u2014 until there is non-whitespace to send, so the affordance and the behaviour agree for keyboard users.",
+    "Send is disabled \u2014 not merely styled down \u2014 until there is non-whitespace to send (or `allowEmpty` says an attachment is enough), so the affordance and the behaviour agree for keyboard users.",
+    "On a touch device Return breaks the line and the send button sends; `aria-keyshortcuts` reports the shortcut actually in effect (\u2318/Ctrl+Enter there, Enter on desktop).",
     "Icon-only attach, send and stop buttons all carry accessible labels, each overridable for localisation."
   ],
   examples: [
@@ -236,6 +251,10 @@ var chatComposerMeta = {
       label: "Controlled, with pending attachments",
       code: '<ChatComposer\n	value={draft}\n	onValueChange={setDraft}\n	onSend={(text) => { post(text, files); setDraft("") }}\n	onAttach={pickFile}\n	attachments={files.map((f) => (<Attachment key={f.id} variant="media" name={f.name} thumbnail={f.url} actions={<Button variant="floating" size="icon-xs" aria-label="Remove" onClick={() => drop(f.id)}><Icon name="xmark" /></Button>} />))}\n	footer={`${draft.length} / 4000`}\n	invalid={draft.length > 4000}\n/>'
     },
+    {
+      label: "Attachments sent without text",
+      code: "<ChatComposer\n	onSend={(text) => post(text, files)}\n	allowEmpty={files.length > 0}\n	onAttach={pickFile}\n	attachments={files.map((f) => <Attachment key={f.id} name={f.name} meta={f.size} />)}\n/>"
+    },
     {
       label: "A working chat, end to end",
       code: '<div className="flex h-128 flex-col gap-3">\n	<MessageScroller className="flex-1 min-h-0">\n		{messages.map((m) => (<Message key={m.id} messageId={m.id} align={m.mine ? "end" : "start"}><Bubble variant={m.mine ? "primary" : "muted"} align={m.mine ? "end" : "start"}>{m.body}</Bubble></Message>))}\n		{streaming ? <Marker icon="spinner" spin shimmer>Thinking\u2026</Marker> : null}\n	</MessageScroller>\n	<ChatComposer onSend={send} busy={streaming} onStop={stop} />\n</div>'

package/dist/components/combobox/combobox.meta.js

@@ -22,6 +22,10 @@ var comboboxMeta = {
         guidance: "do",
         description: "Use ComboboxEmpty with helpful copy for zero matches."
       },
+      {
+        guidance: "do",
+        description: "For results from a server, pass `filter={null}` so Base UI shows the items as the server returned them, fetch from `onInputValueChange`, and make ComboboxEmpty say which state it is in (searching, no results, type to search). Object items take `itemToStringLabel`."
+      },
       {
         guidance: "do",
         description: "Wrap in Field when the combobox is part of a form."
@@ -109,6 +113,24 @@ var comboboxMeta = {
       default: "false",
       description: "Select several items instead of one. `value` / `defaultValue` / `onValueChange` become arrays, choosing an item toggles its membership, and the popup stays open between picks. Pair it with ComboboxChips in place of ComboboxInput; every other part is unchanged."
     },
+    {
+      name: "filter",
+      type: "null | ((item, query, itemToString?) => boolean)",
+      default: "Base UI's locale-aware contains",
+      description: "How items match the query. `null` turns matching off, for items a server already filtered: pair it with `onInputValueChange` to fetch."
+    },
+    {
+      name: "onInputValueChange",
+      type: "(inputValue: string, eventDetails) => void",
+      default: "\u2014",
+      description: "Fires as the reader types. The place to fetch results for a server-backed combobox."
+    },
+    {
+      name: "itemToStringLabel",
+      type: "(item) => string",
+      default: "item.label for { value, label } items",
+      description: "The text an object item shows in the input once chosen, and is matched by. Needed for object items without a `label` field."
+    },
     {
       name: "virtualized",
       type: "boolean",
@@ -202,6 +224,10 @@ var comboboxMeta = {
       label: "Multiple selection",
       code: '<Combobox multiple items={tags} value={value} onValueChange={setValue}><ComboboxChips placeholder="Add tags\u2026" /><ComboboxContent><ComboboxEmpty>No matching tags.</ComboboxEmpty><ComboboxList>{(item) => (<ComboboxItem key={item} value={item}>{item}</ComboboxItem>)}</ComboboxList></ComboboxContent></Combobox>'
     },
+    {
+      label: "Async search (server results)",
+      code: '<Combobox items={results} filter={null} itemToStringLabel={(person) => person.name} value={person} onValueChange={setPerson} onInputValueChange={setQuery}><ComboboxInput placeholder="Search people\u2026" /><ComboboxContent><ComboboxEmpty>{searching ? "Searching\u2026" : query ? "No one matches." : "Type a name to search."}</ComboboxEmpty><ComboboxList>{(item) => (<ComboboxItem key={item.id} value={item}>{item.name}</ComboboxItem>)}</ComboboxList></ComboboxContent></Combobox>'
+    },
     {
       label: "Virtualized (long list)",
       code: '<Combobox virtualized items={districts} value={district} onValueChange={setDistrict}><ComboboxInput placeholder="Search districts\u2026" /><ComboboxContent scroll={false}><ComboboxEmpty>No district matches.</ComboboxEmpty><ComboboxVirtualList itemHeight={32}>{(item) => item.label}</ComboboxVirtualList></ComboboxContent></Combobox>'

package/dist/components/input-group/index.js

@@ -0,0 +1,7 @@
+// src/components/input-group/index.ts
+import { InputGroup } from "./input-group.js";
+import { inputGroupMeta } from "./input-group.meta.js";
+export {
+  InputGroup,
+  inputGroupMeta
+};

package/dist/components/input-group/input-group.js

@@ -0,0 +1,66 @@
+// src/components/input-group/input-group.tsx
+import {
+  Children,
+  cloneElement
+} from "react";
+import { cn } from "../../lib/cn.js";
+import { useDensity, useTypeTier } from "../../lib/density.js";
+import { MOBILE_FIELD_TIER } from "../../lib/field-shell.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+function InputGroup({
+  leading,
+  trailing,
+  children,
+  className,
+  id,
+  required,
+  disabled,
+  "aria-describedby": describedBy,
+  "aria-invalid": invalid,
+  ...props
+}) {
+  const tier = useTypeTier();
+  const density = useDensity();
+  const input = Children.only(children);
+  const control = cloneElement(input, {
+    ...id != null ? { id } : null,
+    ...required != null ? { required } : null,
+    ...disabled ? { disabled: true } : null,
+    ...describedBy ? { "aria-describedby": describedBy } : null,
+    ...invalid ? { "aria-invalid": invalid } : null
+  });
+  const addon = cn(
+    "flex shrink-0 items-center gap-1.5 text-muted-foreground whitespace-nowrap",
+    tier.body,
+    density === "comfortable" && MOBILE_FIELD_TIER
+  );
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      "data-slot": "input-group",
+      className: cn(
+        "flex h-(--control-md) w-full items-center",
+        // The field shell, moved from the input to the group: focus is the
+        // ring on the whole field, and so are the error and disabled states.
+        "rounded-sm border border-input bg-card motion-interactive focus-within:ring-2 focus-within:ring-ring",
+        "has-[>input[aria-invalid=true]]:border-destructive has-[>input[aria-invalid=true]]:ring-destructive/30",
+        "has-[>input:disabled]:cursor-not-allowed has-[>input:disabled]:opacity-50",
+        // The Input keeps its type, padding and behaviour; the box is the group's.
+        "[&>input]:h-full [&>input]:min-w-0 [&>input]:flex-1 [&>input]:rounded-none [&>input]:border-0 [&>input]:bg-transparent [&>input]:focus-visible:ring-0 [&>input]:disabled:opacity-100",
+        leading != null && "[&>input]:ps-1.5",
+        trailing != null && "[&>input]:pe-1.5",
+        className
+      ),
+      ...props,
+      children: [
+        leading != null ? /* @__PURE__ */ jsx("span", { "data-slot": "input-group-leading", className: cn(addon, "ps-3 has-[>[data-variant]]:ps-1"), children: leading }) : null,
+        control,
+        trailing != null ? /* @__PURE__ */ jsx("span", { "data-slot": "input-group-trailing", className: cn(addon, "pe-3 has-[>[data-variant]]:pe-1"), children: trailing }) : null
+      ]
+    }
+  );
+}
+InputGroup.displayName = "InputGroup";
+export {
+  InputGroup
+};

package/dist/components/input-group/input-group.meta.js

@@ -0,0 +1,106 @@
+// src/components/input-group/input-group.meta.ts
+var inputGroupMeta = {
+  name: "InputGroup",
+  summary: `An Input with addons inside the same field: a prefix or suffix ("https://", ".com", "$"), an icon, or a borderless Button such as copy or reveal. One shell, one focus ring, one error state; a Field's label and error wiring reaches the Input inside.`,
+  keywords: [
+    "input group",
+    "input addon",
+    "prefix",
+    "suffix",
+    "adornment",
+    "url input",
+    "currency input",
+    "password reveal",
+    "copy field",
+    "icon in input"
+  ],
+  usage: {
+    description: "Use InputGroup when something belongs inside the field with the text: a unit, a fixed prefix, an icon, or a small action on the value itself (copy, reveal, clear). Use Field's `trailing` for an action beside the field (Apply next to a promo code), SearchInput for search, and NumberField for numbers with steppers.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: 'Keep text addons short and fixed ("https://", "kg", "USD"). They are part of the field, not its label.'
+      },
+      {
+        guidance: "do",
+        description: 'For a button addon, use a borderless Button (`variant="ghost"`, `size="icon-sm"`) with an aria-label. The addon tightens around it, so it sits as far from the edge as from the top and bottom.'
+      },
+      {
+        guidance: "do",
+        description: 'Wrap the group in Field for a label and errors: `<Field label="Website"><InputGroup leading="https://"><Input /></InputGroup></Field>`.'
+      },
+      {
+        guidance: "dont",
+        description: `Do not put the value's meaning only in an addon. A screen reader hears the label and the text, so "Price (USD)" belongs in the label too.`
+      },
+      {
+        guidance: "dont",
+        description: "Do not restyle an Input to fake an addon; the group owns the border, the fill and the ring."
+      }
+    ]
+  },
+  related: {
+    components: ["Input", "Field", "SearchInput", "NumberField", "Button"]
+  },
+  status: "stable",
+  props: [
+    {
+      name: "leading",
+      type: "ReactNode",
+      default: "\u2014",
+      description: 'Inside the field, before the text: a prefix ("https://", "$"), an icon, or a borderless Button.'
+    },
+    {
+      name: "trailing",
+      type: "ReactNode",
+      default: "\u2014",
+      description: 'Inside the field, after the text: a suffix (".com", "kg"), an icon, or a borderless Button (copy, reveal, clear).'
+    },
+    {
+      name: "children",
+      type: "ReactElement",
+      default: "\u2014",
+      description: "The single `<Input />`. It keeps its own props and type; the group takes over its border, fill and focus ring."
+    },
+    {
+      name: "id / required / disabled / aria-describedby / aria-invalid",
+      type: "control props",
+      default: "\u2014",
+      description: "Forwarded to the Input, not set on the group. This is how a Field's wiring reaches the text box when the group is its child."
+    },
+    {
+      name: "className",
+      type: "string",
+      default: "\u2014",
+      description: "Layout classes for the group (width, margins)."
+    }
+  ],
+  tokensUsed: ["input", "card", "ring", "destructive", "muted-foreground", "foreground"],
+  a11y: [
+    "The Input stays the focusable control; the group draws the focus ring around the whole field while it is focused.",
+    "Inside a Field, the label, description and error are wired to the Input itself, not the group.",
+    "Text addons are plain text beside the input, read in order; put a unit or currency in the label as well so it is not only visual.",
+    "A button addon is a real Button with its own focus stop and needs an aria-label."
+  ],
+  examples: [
+    {
+      label: "Prefix and suffix",
+      code: '<Field label="Website"><InputGroup leading="https://" trailing=".com"><Input placeholder="example" /></InputGroup></Field>'
+    },
+    {
+      label: "Leading icon",
+      code: '<Field label="Email"><InputGroup leading={<Icon name="mail" />}><Input type="email" placeholder="you@example.com" /></InputGroup></Field>'
+    },
+    {
+      label: "Copy button",
+      code: '<Field label="API key"><InputGroup trailing={<Button variant="ghost" size="icon-sm" aria-label="Copy key" onClick={copy}><Icon name={copied ? "check" : "copy"} /></Button>}><Input readOnly value={key} /></InputGroup></Field>'
+    },
+    {
+      label: "Password with reveal",
+      code: '<Field label="Password"><InputGroup trailing={<Button variant="ghost" size="icon-sm" aria-label={shown ? "Hide password" : "Show password"} aria-pressed={shown} onClick={() => setShown(!shown)}><Icon name={shown ? "eye-off" : "eye"} /></Button>}><Input type={shown ? "text" : "password"} autoComplete="current-password" /></InputGroup></Field>'
+    }
+  ]
+};
+export {
+  inputGroupMeta
+};

package/dist/components/menu/index.js

@@ -5,6 +5,7 @@ import {
   MenuPortal,
   MenuContent,
   MenuItem,
+  MenuLinkItem,
   MenuSeparator,
   MenuGroup,
   MenuGroupLabel,
@@ -22,6 +23,7 @@ export {
   MenuGroup,
   MenuGroupLabel,
   MenuItem,
+  MenuLinkItem,
   MenuPortal,
   MenuRadioGroup,
   MenuRadioItem,

package/dist/components/menu/menu.js

@@ -6,7 +6,7 @@ import { cn } from "../../lib/cn.js";
 import { withPortalThemeScope } from "../../lib/portal-theme-scope.js";
 import { useAnchoredDensity, useTypeTier } from "../../lib/density.js";
 import { HighlightGlide } from "../../lib/highlight-glide.js";
-import { jsx, jsxs } from "react/jsx-runtime";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 var Menu = Base.Root;
 var MenuTrigger = Base.Trigger;
 var MenuPortal = withPortalThemeScope(Base.Portal);
@@ -40,6 +40,28 @@ function MenuContent({
     }
   ) }) });
 }
+var MENU_ITEM = "flex cursor-default select-none items-center gap-(--item-gap) rounded-popup-item px-(--item-px) py-1.5 outline-none motion-interactive data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:shrink-0";
+function useItemContent(children, { icon, description }) {
+  const tier = useTypeTier();
+  if (!description) return icon ? /* @__PURE__ */ jsxs(Fragment, { children: [
+    icon,
+    children
+  ] }) : children;
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    icon ? /* @__PURE__ */ jsx(
+      "span",
+      {
+        "data-slot": "menu-item-icon",
+        className: "flex size-(--control-sm) shrink-0 items-center justify-center rounded-sm border border-border-strong bg-popover text-muted-foreground",
+        children: icon
+      }
+    ) : null,
+    /* @__PURE__ */ jsxs("span", { className: "flex min-w-0 flex-col", children: [
+      /* @__PURE__ */ jsx("span", { children }),
+      /* @__PURE__ */ jsx("span", { "data-slot": "menu-item-description", className: cn("text-muted-foreground", tier.secondary), children: description })
+    ] })
+  ] });
+}
 var MENU_ITEM_DESTRUCTIVE = (
   // The ink is pulled a quarter toward --foreground (as Badge's soft tones
   // are), from --destructive-text rather than the fill: dark fills sit low
@@ -48,17 +70,34 @@ var MENU_ITEM_DESTRUCTIVE = (
   // 5.4:1, Prism dark, on the 10% red wash).
   "text-[color-mix(in_oklch,var(--destructive-text)_75%,var(--foreground))] data-[highlighted]:bg-destructive/10 data-[highlighted]:text-[color-mix(in_oklch,var(--destructive-text)_75%,var(--foreground))]"
 );
-function MenuItem({ className, variant = "default", ...props }) {
+function MenuItem({ className, variant = "default", icon, description, children, ...props }) {
   const tier = useTypeTier();
+  const content = useItemContent(children, { icon, description });
   return /* @__PURE__ */ jsx(
     Base.Item,
     {
-      className: cn(
-        `flex cursor-default select-none items-center gap-(--item-gap) rounded-popup-item px-(--item-px) py-1.5 ${tier.body} outline-none motion-interactive data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:shrink-0`,
-        variant === "destructive" && MENU_ITEM_DESTRUCTIVE,
-        className
-      ),
-      ...props
+      className: cn(MENU_ITEM, tier.body, variant === "destructive" && MENU_ITEM_DESTRUCTIVE, className),
+      ...props,
+      children: content
+    }
+  );
+}
+function MenuLinkItem({ className, icon, description, children, target, ...props }) {
+  const tier = useTypeTier();
+  const external = target === "_blank";
+  const label = external ? /* @__PURE__ */ jsxs("span", { className: "inline-flex items-center gap-1", children: [
+    children,
+    /* @__PURE__ */ jsx(Icon, { name: "arrow-up-right", className: "text-[0.875em] text-muted-foreground" })
+  ] }) : children;
+  const content = useItemContent(label, { icon, description });
+  return /* @__PURE__ */ jsx(
+    Base.LinkItem,
+    {
+      className: cn(MENU_ITEM, tier.body, className),
+      target,
+      rel: external ? "noopener noreferrer" : void 0,
+      ...props,
+      children: content
     }
   );
 }
@@ -151,6 +190,7 @@ function MenuCheckboxItem({
   );
 }
 export {
+  MENU_ITEM,
   MENU_ITEM_DESTRUCTIVE,
   Menu,
   MenuCheckboxItem,
@@ -158,11 +198,13 @@ export {
   MenuGroup,
   MenuGroupLabel,
   MenuItem,
+  MenuLinkItem,
   MenuPortal,
   MenuRadioGroup,
   MenuRadioItem,
   MenuSeparator,
   MenuSubmenu,
   MenuSubmenuTrigger,
-  MenuTrigger
+  MenuTrigger,
+  useItemContent
 };

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

@@ -93,8 +93,13 @@ var menuMeta = {
     },
     {
       name: "MenuItem",
-      type: 'Base UI Menu.Item props + className (disabled, closeOnClick, onClick) + variant?: "default" | "destructive"',
-      description: 'An interactive row. Highlights via data-[highlighted]; dims via data-[disabled]. variant="destructive" for a delete or irreversible action: it keeps the destructive ink when highlighted (never className="text-destructive", which the highlight repaints).'
+      type: 'Base UI Menu.Item props + className (disabled, closeOnClick, onClick) + variant?: "default" | "destructive" + icon?: ReactNode + description?: ReactNode',
+      description: 'An interactive row. Highlights via data-[highlighted]; dims via data-[disabled]. variant="destructive" for a delete or irreversible action: it keeps the destructive ink when highlighted (never className="text-destructive", which the highlight repaints). `icon` leads the row; `description` adds a quieter second line saying what the action does, and the icon then sits in a small tile spanning both lines.'
+    },
+    {
+      name: "MenuLinkItem",
+      type: "Base UI Menu.LinkItem props (href, target, closeOnClick) + className + icon?: ReactNode + description?: ReactNode",
+      description: 'A row that navigates: a real <a>, so it opens in a new tab, middle-clicks and copies as a link. With target="_blank" it adds rel="noopener noreferrer" and a trailing \u2197. Takes icon and description like MenuItem.'
     },
     {
       name: "MenuSeparator",
@@ -165,6 +170,10 @@ var menuMeta = {
       label: "Nested, with a single-choice submenu",
       code: '<Menu>\n	<MenuTrigger render={<Button variant="secondary">View</Button>} />\n	<MenuContent>\n		<MenuItem>Reload</MenuItem>\n		<MenuSubmenu>\n			<MenuSubmenuTrigger value={density}>Density</MenuSubmenuTrigger>\n			<MenuContent side="inline-end" align="start" sideOffset={4}>\n				<MenuRadioGroup value={density} onValueChange={setDensity}>\n					<MenuRadioItem value="Comfortable">Comfortable</MenuRadioItem>\n					<MenuRadioItem value="Compact">Compact</MenuRadioItem>\n				</MenuRadioGroup>\n			</MenuContent>\n		</MenuSubmenu>\n	</MenuContent>\n</Menu>'
     },
+    {
+      label: "Rows with icons and descriptions, and links",
+      code: '<Menu>\n	<MenuTrigger render={<Button variant="outline" size="sm">Share</Button>} />\n	<MenuContent align="end">\n		<MenuItem icon={<Icon name="copy" />} description="Copy page as Markdown for LLMs" onClick={copy}>Copy page</MenuItem>\n		<MenuLinkItem icon={<Icon name="file" />} description="View this page as plain text" href={markdownUrl} target="_blank">View as Markdown</MenuLinkItem>\n	</MenuContent>\n</Menu>'
+    },
     {
       label: "Toggling rows",
       code: '<Menu>\n	<MenuTrigger render={<Button variant="secondary">Columns</Button>} />\n	<MenuContent>\n		<MenuCheckboxItem checked={cols.status} onCheckedChange={(v) => setCol("status", v)}>Status</MenuCheckboxItem>\n		<MenuCheckboxItem checked={cols.updated} onCheckedChange={(v) => setCol("updated", v)}>Updated</MenuCheckboxItem>\n	</MenuContent>\n</Menu>'

package/dist/components/menubar/index.js

@@ -0,0 +1,8 @@
+// src/components/menubar/index.ts
+import { Menubar, MenubarTrigger } from "./menubar.js";
+import { menubarMeta } from "./menubar.meta.js";
+export {
+  Menubar,
+  MenubarTrigger,
+  menubarMeta
+};

package/dist/components/menubar/menubar.js

@@ -0,0 +1,42 @@
+// src/components/menubar/menubar.tsx
+import { Menubar as Base } from "@base-ui/react/menubar";
+import { cn } from "../../lib/cn.js";
+import { useTypeTier } from "../../lib/density.js";
+import { trimLabel } from "../../lib/trim-label.js";
+import { buttonVariants } from "../button/button.variants.js";
+import { MenuTrigger } from "../menu/index.js";
+import { jsx } from "react/jsx-runtime";
+function Menubar({ className, ...props }) {
+  return /* @__PURE__ */ jsx(
+    Base,
+    {
+      className: cn(
+        "inline-flex items-center gap-0.5 data-[orientation=vertical]:flex-col data-[orientation=vertical]:items-stretch",
+        className
+      ),
+      ...props
+    }
+  );
+}
+Menubar.displayName = "Menubar";
+function MenubarTrigger({ className, children, ...props }) {
+  const tier = useTypeTier();
+  return /* @__PURE__ */ jsx(
+    MenuTrigger,
+    {
+      className: cn(
+        buttonVariants({ variant: "ghost", size: "sm" }),
+        tier.control,
+        "sable-open:bg-accent sable-open:text-accent-foreground",
+        className
+      ),
+      ...props,
+      children: trimLabel(children)
+    }
+  );
+}
+MenubarTrigger.displayName = "MenubarTrigger";
+export {
+  Menubar,
+  MenubarTrigger
+};

package/dist/components/menubar/menubar.meta.js

@@ -0,0 +1,99 @@
+// src/components/menubar/menubar.meta.ts
+var menubarMeta = {
+  name: "Menubar",
+  summary: "An application's row of menus \u2014 File, Edit, View \u2014 over Base UI's Menubar. Each menu is an ordinary Sable Menu with a MenubarTrigger as its title; the bar joins them into one tab stop with \u2190/\u2192 between titles, and once one menu is open, pointing at a neighbour opens it.",
+  status: "stable",
+  keywords: ["menubar", "menu bar", "app menu", "file menu", "edit menu", "application menu", "desktop menu"],
+  usage: {
+    description: "Use Menubar for a tool or editor whose commands are too many for a toolbar and belong under named menus (File, Edit, View, Help). Use Toolbar for a row of direct actions, a single Menu or OverflowMenu for one set of options, and NavigationMenu-style links for site navigation.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Compose each menu from the Menu parts: `<Menu><MenubarTrigger>File</MenubarTrigger><MenuContent>\u2026</MenuContent></Menu>`. Rows, groups, submenus, checkbox and radio items are the same parts a lone Menu uses."
+      },
+      {
+        guidance: "do",
+        description: `Name the bar with aria-label ("Editor") so it is announced as the application's menus, not a list of buttons.`
+      },
+      {
+        guidance: "do",
+        description: "Keep titles to one short word each. A reader scans a menubar left to right; a phrase in the bar is a toolbar button."
+      },
+      {
+        guidance: "dont",
+        description: "Do not use MenubarTrigger outside a Menubar, or a plain MenuTrigger inside one. The bar's arrow keys and hover-to-switch work on the triggers it owns; a Button trigger in the bar looks like a menu title and behaves like a stray button."
+      },
+      {
+        guidance: "dont",
+        description: "Do not use a menubar for site navigation. Its items are commands in menus (role=menuitem), not links between pages."
+      }
+    ],
+    anatomy: [
+      { name: "Menubar", required: true, description: "The bar: role=menubar, one tab stop, arrow keys between titles." },
+      { name: "Menu", required: true, description: "One per title; the ordinary Menu root." },
+      { name: "MenubarTrigger", required: true, description: "The title in the bar that opens its menu." },
+      { name: "MenuContent", required: true, description: "The menu's popup, with MenuItem / MenuSubmenu / MenuCheckboxItem rows inside." }
+    ]
+  },
+  related: {
+    components: ["Menu", "Toolbar", "OverflowMenu", "ContextMenu"]
+  },
+  props: [
+    {
+      name: "orientation",
+      type: '"horizontal" | "vertical"',
+      default: '"horizontal"',
+      description: "The bar's axis. Arrow keys follow it: \u2190/\u2192 along a horizontal bar, \u2191/\u2193 down a vertical one."
+    },
+    {
+      name: "loopFocus",
+      type: "boolean",
+      default: "true",
+      description: "Wrap from the last title back to the first with the arrow keys."
+    },
+    {
+      name: "modal",
+      type: "boolean",
+      default: "true",
+      description: "While a menu is open, block pointer interaction outside it and lock page scroll, like a lone Menu."
+    },
+    {
+      name: "disabled",
+      type: "boolean",
+      default: "false",
+      description: "Disable every menu in the bar."
+    },
+    {
+      name: "className",
+      type: "string",
+      description: "Layout classes for the bar. Titles take their look from MenubarTrigger."
+    }
+  ],
+  subcomponents: [
+    {
+      name: "MenubarTrigger",
+      type: "Base UI Menu.Trigger props + className",
+      description: "A menu's title in the bar. A small ghost Button in the control type tier, held in the accent wash while its menu is open (`sable-open:`), so the reader sees which title the popup belongs to."
+    }
+  ],
+  tokensUsed: ["accent", "accent-foreground", "foreground", "ring"],
+  a11y: [
+    'Base UI renders role="menubar" with aria-orientation; each title is a menuitem with aria-haspopup and aria-expanded.',
+    "The bar is one tab stop. \u2190/\u2192 move between titles (\u2191/\u2193 when vertical), \u2193 or Enter opens a menu and moves into it, and Esc closes it and returns focus to its title.",
+    "With one menu open, pointing at another title opens that menu instead, so a reader can sweep across the bar, as in a desktop application.",
+    "Name the bar with aria-label; titles are their own text."
+  ],
+  examples: [
+    {
+      label: "Editor menus",
+      code: '<Menubar aria-label="Editor">\n	<Menu>\n		<MenubarTrigger>File</MenubarTrigger>\n		<MenuContent>\n			<MenuItem>New</MenuItem>\n			<MenuItem>Open\u2026</MenuItem>\n			<MenuSeparator />\n			<MenuItem>Save</MenuItem>\n		</MenuContent>\n	</Menu>\n	<Menu>\n		<MenubarTrigger>Edit</MenubarTrigger>\n		<MenuContent>\n			<MenuItem>Undo</MenuItem>\n			<MenuItem>Redo</MenuItem>\n		</MenuContent>\n	</Menu>\n</Menubar>'
+    },
+    {
+      label: "With a submenu and toggling rows",
+      code: '<Menubar aria-label="Editor">\n	<Menu>\n		<MenubarTrigger>View</MenubarTrigger>\n		<MenuContent>\n			<MenuCheckboxItem checked={ruler} onCheckedChange={setRuler}>Show ruler</MenuCheckboxItem>\n			<MenuSubmenu>\n				<MenuSubmenuTrigger value={zoom}>Zoom</MenuSubmenuTrigger>\n				<MenuContent side="inline-end" align="start" sideOffset={4}>\n					<MenuRadioGroup value={zoom} onValueChange={setZoom}>\n						<MenuRadioItem value="100%">100%</MenuRadioItem>\n						<MenuRadioItem value="Fit">Fit</MenuRadioItem>\n					</MenuRadioGroup>\n				</MenuContent>\n			</MenuSubmenu>\n		</MenuContent>\n	</Menu>\n</Menubar>'
+    }
+  ]
+};
+export {
+  menubarMeta
+};

package/dist/components/message-scroller/message-scroller.meta.js

@@ -20,6 +20,10 @@ var messageScrollerMeta = {
   usage: {
     description: "The scroll region a conversation lives in. It owns the scrolling and nothing else \u2014 not your messages, not your AI state, not your transport or persistence \u2014 so you bring the content renderer and it handles the behaviors that make streaming chat feel right: pinning to the newest message, releasing when the reader scrolls up, keeping the view still when older history loads above, jumping to a specific message, restoring a saved read position, and reporting what is actually on screen.",
     bestPractices: [
+      {
+        guidance: "do",
+        description: "Building a whole chat? `sable docs building-a-chat` covers what the scroller does during a stream, what the app owns, and the failure states around it."
+      },
       {
         guidance: "do",
         description: "Bound it the way you would bound any scroll box \u2014 `flex-1 min-h-0` inside a flex column, or `max-h-96`. `className` lands on the element that actually scrolls, so the obvious bound is the correct one (same contract as Scroller)."