@sableui/react 0.11.0 → 0.13.0

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

@@ -0,0 +1,221 @@
+"use client";
+
+// src/components/caret-menu/caret-menu.tsx
+import {
+  Children,
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useRef,
+  useState
+} from "react";
+import { createPortal } from "react-dom";
+import { cn } from "../../lib/cn.js";
+import { useAnchoredDensity, useTypeTier } from "../../lib/density.js";
+import { HighlightGlide } from "../../lib/highlight-glide.js";
+import { applyPortalThemeScope, resolvePortalThemeScope } from "../../lib/portal-theme-scope.js";
+import { useIsomorphicLayoutEffect } from "../../lib/use-isomorphic-layout-effect.js";
+import { MENU_ITEM, useItemContent } from "../menu/menu.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+var EDGE = 8;
+var GAP = 4;
+var CaretMenuContext = createContext(null);
+function CaretMenu({ trigger, label, status, children, className }) {
+  const { field, match } = trigger;
+  const listId = useId();
+  const anchoredDensity = useAnchoredDensity();
+  const tier = useTypeTier();
+  const popupRef = useRef(null);
+  const listRef = useRef(null);
+  const [activeId, setActiveId] = useState(null);
+  const [count, setCount] = useState(0);
+  const triggerRef = useRef(trigger);
+  triggerRef.current = trigger;
+  const hasItems = Children.toArray(children).length > 0;
+  const open = match !== null && field !== null && (hasItems || status != null);
+  useIsomorphicLayoutEffect(() => {
+    const options = open ? optionsIn(listRef.current) : [];
+    setCount(options.length);
+    if (!options.some((o) => o.id === activeId)) setActiveId(options[0]?.id ?? null);
+  });
+  useEffect(() => {
+    if (!field) return;
+    const isInput = field instanceof HTMLInputElement;
+    if (isInput) field.setAttribute("role", "combobox");
+    field.setAttribute("aria-autocomplete", "list");
+    return () => {
+      if (isInput) {
+        field.removeAttribute("role");
+        field.removeAttribute("aria-expanded");
+      }
+      field.removeAttribute("aria-autocomplete");
+    };
+  }, [field]);
+  useEffect(() => {
+    if (!field) return;
+    if (field instanceof HTMLInputElement) field.setAttribute("aria-expanded", String(open));
+    if (!open) return;
+    field.setAttribute("aria-controls", listId);
+    if (activeId) field.setAttribute("aria-activedescendant", activeId);
+    else field.removeAttribute("aria-activedescendant");
+    return () => {
+      field.removeAttribute("aria-activedescendant");
+      field.removeAttribute("aria-controls");
+    };
+  }, [field, open, listId, activeId]);
+  const activeRef = useRef(activeId);
+  activeRef.current = activeId;
+  useEffect(() => {
+    if (!field || !open) return;
+    const onKeyDown = (event) => {
+      if (event.isComposing) return;
+      const options = optionsIn(listRef.current);
+      const index = options.findIndex((o) => o.id === activeRef.current);
+      if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+        if (!options.length) return;
+        event.preventDefault();
+        const step = event.key === "ArrowDown" ? 1 : -1;
+        const next = options[(index + step + options.length) % options.length];
+        setActiveId(next.id);
+        next.scrollIntoView?.({ block: "nearest" });
+      } else if ((event.key === "Enter" || event.key === "Tab") && !event.shiftKey && !event.metaKey && !event.ctrlKey && !event.altKey) {
+        if (index < 0) return;
+        event.preventDefault();
+        options[index].click();
+      } else if (event.key === "Escape") {
+        event.preventDefault();
+        event.stopPropagation();
+        triggerRef.current.dismiss();
+      }
+    };
+    const target = field;
+    target.addEventListener("keydown", onKeyDown);
+    return () => target.removeEventListener("keydown", onKeyDown);
+  }, [field, open]);
+  const place = useCallback(() => {
+    const popup = popupRef.current;
+    const anchor = triggerRef.current.getAnchorRect();
+    if (!popup || !anchor) return;
+    const view = popup.ownerDocument.defaultView ?? window;
+    const natural = popup.scrollHeight;
+    const below = view.innerHeight - (anchor.bottom + GAP) - EDGE;
+    const above = anchor.top - GAP - EDGE;
+    const flip = natural > below && above > below;
+    const room = Math.max(0, flip ? above : below);
+    popup.style.maxHeight = `${room}px`;
+    const height = Math.min(natural, room);
+    popup.style.top = `${flip ? anchor.top - GAP - height : anchor.bottom + GAP}px`;
+    popup.style.setProperty("--transform-origin", flip ? "left bottom" : "left top");
+    const option = optionsIn(listRef.current)[0];
+    const inset = Number.parseFloat(view.getComputedStyle(popup).paddingLeft) + (option ? Number.parseFloat(view.getComputedStyle(option).paddingLeft) : 0);
+    const width = popup.offsetWidth;
+    const left = Math.min(anchor.left - inset, view.innerWidth - EDGE - width);
+    popup.style.left = `${Math.max(EDGE, left)}px`;
+  }, []);
+  useIsomorphicLayoutEffect(() => {
+    if (open) place();
+  });
+  useEffect(() => {
+    if (!open || !field) return;
+    const view = field.ownerDocument.defaultView ?? window;
+    const onScroll = (event) => {
+      if (popupRef.current?.contains(event.target)) return;
+      place();
+    };
+    view.addEventListener("resize", place);
+    view.addEventListener("scroll", onScroll, true);
+    return () => {
+      view.removeEventListener("resize", place);
+      view.removeEventListener("scroll", onScroll, true);
+    };
+  }, [open, field, place]);
+  const [entered, setEntered] = useState(false);
+  useEffect(() => {
+    if (!open) {
+      setEntered(false);
+      return;
+    }
+    const frame = requestAnimationFrame(() => setEntered(true));
+    return () => cancelAnimationFrame(frame);
+  }, [open]);
+  const setScope = useCallback(
+    (node) => {
+      if (node && field) applyPortalThemeScope(node, resolvePortalThemeScope(field));
+    },
+    [field]
+  );
+  const announcement = !open ? "" : status != null && typeof status !== "boolean" ? status : `${count} ${count === 1 ? "suggestion" : "suggestions"}`;
+  return /* @__PURE__ */ jsxs(CaretMenuContext.Provider, { value: { activeId, setActive: setActiveId }, children: [
+    /* @__PURE__ */ jsx("span", { role: "status", "aria-live": "polite", className: "sr-only", children: announcement }),
+    open && field ? createPortal(
+      /* @__PURE__ */ jsx("div", { ref: setScope, "data-slot": "caret-menu-portal", children: /* @__PURE__ */ jsxs(
+        "div",
+        {
+          ref: popupRef,
+          ...anchoredDensity,
+          "data-slot": "caret-menu",
+          "data-starting-style": entered ? void 0 : "",
+          className: cn(
+            "fixed z-(--z-overlay) min-w-48 max-w-[min(24rem,calc(100vw-1rem))] rounded-md border border-border-floating bg-popover popup-inset text-popover-foreground shadow-md outline-none",
+            "overflow-y-auto overscroll-contain scrollbar-quiet motion-pop",
+            className
+          ),
+          children: [
+            /* @__PURE__ */ jsx(HighlightGlide, {}),
+            /* @__PURE__ */ jsx("div", { ref: listRef, id: listId, role: "listbox", "aria-label": label, children }),
+            status != null ? /* @__PURE__ */ jsx("div", { "data-slot": "caret-menu-status", className: cn("px-(--item-px) py-1.5 text-muted-foreground", tier.secondary), children: status }) : null
+          ]
+        }
+      ) }),
+      field.ownerDocument.body
+    ) : null
+  ] });
+}
+function optionsIn(list) {
+  if (!list) return [];
+  return [...list.querySelectorAll('[role="option"]:not([aria-disabled="true"])')];
+}
+function CaretMenuItem({
+  onSelect,
+  disabled = false,
+  icon,
+  description,
+  className,
+  children,
+  id,
+  ...props
+}) {
+  const context = useContext(CaretMenuContext);
+  const tier = useTypeTier();
+  const ownId = useId();
+  const optionId = id ?? ownId;
+  const active = context?.activeId === optionId;
+  const content = useItemContent(children, { icon, description });
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      ...props,
+      id: optionId,
+      role: "option",
+      "aria-selected": active,
+      "aria-disabled": disabled || void 0,
+      "data-highlighted": active ? "" : void 0,
+      "data-disabled": disabled ? "" : void 0,
+      className: cn(MENU_ITEM, tier.body, className),
+      onMouseDown: (event) => event.preventDefault(),
+      onMouseMove: () => {
+        if (!disabled && !active) context?.setActive(optionId);
+      },
+      onClick: () => {
+        if (!disabled) onSelect();
+      },
+      children: content
+    }
+  );
+}
+export {
+  CaretMenu,
+  CaretMenuItem
+};

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

@@ -0,0 +1,119 @@
+// src/components/caret-menu/caret-menu.meta.ts
+var caretMenuMeta = {
+  name: "CaretMenu",
+  summary: "Suggestions at the caret of a text field, for @mentions and /slash commands. `useCaretTrigger` watches a Textarea, Input or ChatComposer (through `fieldRef`) for a trigger character and reports the query; CaretMenu draws the list beside the trigger and drives it from the field's keys, so focus never leaves the field. The value stays plain text: a mention is inserted as `@Sam Rivera`, a command runs and clears its `/query`.",
+  status: "beta",
+  keywords: [
+    "mention",
+    "mentions",
+    "at mention",
+    "slash command",
+    "slash commands",
+    "autocomplete",
+    "typeahead",
+    "suggestions",
+    "emoji picker",
+    "hashtag",
+    "trigger"
+  ],
+  usage: {
+    description: "Use CaretMenu with `useCaretTrigger` when typing a character in running text should offer choices: `@` for people, `/` for commands, `#` for channels, `:` for emoji. The app owns the items (filter or fetch them from `trigger.match.query`) and what choosing one does; Sable owns detecting the trigger, placing the list at the caret, the keys and the accessibility. Use Combobox when the whole field is a search for one value, and CommandMenu for a global palette.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Attach the hook's `fieldRef` to the field: `ref` on Textarea or Input, `fieldRef` on ChatComposer. On ChatComposer, Enter picks the highlighted suggestion instead of sending, because CaretMenu takes the Enter first."
+      },
+      {
+        guidance: "do",
+        description: 'Insert a mention with a trailing space, `trigger.replace(`@${person.name} `)`, so the reader keeps typing; run a slash command and then `trigger.replace("")` to clear `/query` from the field.'
+      },
+      {
+        guidance: "do",
+        description: "For `@` names with spaces set `allowSpaces: true` on that trigger; for `/` commands set `atStart: true` so `and/or` mid-sentence stays text."
+      },
+      {
+        guidance: "do",
+        description: 'Fetch remote suggestions from `trigger.match?.query` yourself, debounced, and pass `status` while loading or when nothing matches ("Searching\u2026", "No one matches"). The status row is also what the list announces.'
+      },
+      {
+        guidance: "dont",
+        description: "Do not expect chips inside the field. A textarea holds text, so a mention is text. Rendering tokens in the field needs a rich-text editor, which Sable does not own (`sable docs extending-a-component`)."
+      },
+      {
+        guidance: "dont",
+        description: "Do not move focus into the list or wrap the field in a Popover. Focus stays in the field; the list is pointed at with aria-activedescendant."
+      }
+    ],
+    anatomy: [
+      { name: "useCaretTrigger", required: true, description: "The hook on the field: trigger detection, the query, the caret anchor, replace() and dismiss()." },
+      { name: "CaretMenu", required: true, description: "The list at the caret, its keys, and its announcements." },
+      { name: "CaretMenuItem", required: true, description: "One suggestion row, with optional icon and description." }
+    ]
+  },
+  related: {
+    components: ["ChatComposer", "Textarea", "Input", "Combobox", "CommandMenu", "Menu"]
+  },
+  props: [
+    {
+      name: "trigger",
+      type: "UseCaretTriggerResult",
+      description: "The result of `useCaretTrigger({ triggers })`, whose `fieldRef` is attached to the field. Each trigger is `{ char, atStart?, allowSpaces?, maxQueryLength? }`; the result carries `match` (`{ trigger, query, start, end }` or null), `replace(text)`, `dismiss()` and `getAnchorRect()`."
+    },
+    {
+      name: "label",
+      type: "string",
+      description: `The list's accessible name, e.g. "People" or "Commands".`
+    },
+    {
+      name: "status",
+      type: "ReactNode",
+      description: "A row under the items for what the list is doing: loading, nothing found, an error. Announced politely in place of the suggestion count. With no items and no status the list stays shut."
+    },
+    {
+      name: "children",
+      type: "ReactNode",
+      description: "CaretMenuItems, already filtered for the query."
+    },
+    {
+      name: "className",
+      type: "string",
+      description: "Layout classes for the popup, such as a width."
+    }
+  ],
+  subcomponents: [
+    {
+      name: "CaretMenuItem",
+      type: "div props + onSelect: () => void + disabled?: boolean + icon?: ReactNode + description?: ReactNode",
+      description: "One suggestion, styled as a Menu row. `onSelect` runs on Enter, Tab or click; `icon` and `description` work as on MenuItem. A disabled row shows but the arrow keys skip it."
+    }
+  ],
+  tokensUsed: ["popover", "popover-foreground", "border-floating", "accent", "accent-foreground", "muted-foreground"],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "motion-pop",
+      part: "root",
+      why: "Scales in from the caret's side, so the list reads as coming from the character just typed. It leaves instantly: it answers a keystroke and should be gone by the next one."
+    }
+  ],
+  a11y: [
+    'Focus stays in the field. The field carries aria-autocomplete="list", aria-controls (the listbox) and aria-activedescendant (the highlighted option), so a screen reader follows the arrow keys without focus moving.',
+    'An <input> becomes role="combobox" with aria-expanded. A <textarea> keeps its textbox role (combobox would drop multiline), and since a textbox cannot carry aria-expanded, opening is announced through a polite status, mounted from the start: "3 suggestions", or the `status` text.',
+    "\u2191/\u2193 move the highlight and wrap; Enter or Tab choose it; Escape closes the list without reaching an enclosing Dialog or Sheet. Shift+Enter is left alone, so a line break still breaks the line.",
+    "Rows keep focus in the field on pointer down, so a click does not blur it and close the list first.",
+    "Triggers follow a word boundary (`ana@example.com` and `and/or` stay text), wait for IME composition to end, and stay closed after Escape until the caret leaves that trigger."
+  ],
+  examples: [
+    {
+      label: "Mentions and slash commands in a ChatComposer",
+      code: 'const trigger = useCaretTrigger({ triggers: [{ char: "@", allowSpaces: true }, { char: "/", atStart: true }] })\nconst q = trigger.match?.query.toLowerCase() ?? ""\nconst commands = trigger.match?.trigger.char === "/"\n\n<ChatComposer fieldRef={trigger.fieldRef} onSend={send} />\n<CaretMenu trigger={trigger} label={commands ? "Commands" : "People"} status={!commands && people.length === 0 ? "No one matches" : undefined}>\n	{commands\n		? slashCommands.filter((c) => c.name.startsWith(q)).map((c) => (\n			<CaretMenuItem key={c.name} description={c.hint} onSelect={() => { c.run(); trigger.replace("") }}>/{c.name}</CaretMenuItem>\n		))\n		: people.filter((p) => p.name.toLowerCase().includes(q)).map((p) => (\n			<CaretMenuItem key={p.id} icon={<Avatar size="sm" src={p.avatar} fallback={p.initials} />} onSelect={() => trigger.replace(`@${p.name} `)}>{p.name}</CaretMenuItem>\n		))}\n</CaretMenu>'
+    },
+    {
+      label: "On a Textarea, with remote results",
+      code: 'const trigger = useCaretTrigger({ triggers: [{ char: "#" }] })\n// Fetch from trigger.match?.query yourself, debounced; pass the state as status.\n<Textarea ref={trigger.fieldRef} aria-label="Note" />\n<CaretMenu trigger={trigger} label="Channels" status={loading ? "Searching\u2026" : channels.length === 0 ? "No channels match" : undefined}>\n	{channels.map((c) => <CaretMenuItem key={c.id} onSelect={() => trigger.replace(`#${c.name} `)}>#{c.name}</CaretMenuItem>)}\n</CaretMenu>'
+    }
+  ]
+};
+export {
+  caretMenuMeta
+};

package/dist/components/caret-menu/index.js

@@ -0,0 +1,8 @@
+// src/components/caret-menu/index.ts
+import { CaretMenu, CaretMenuItem } from "./caret-menu.js";
+import { caretMenuMeta } from "./caret-menu.meta.js";
+export {
+  CaretMenu,
+  CaretMenuItem,
+  caretMenuMeta
+};

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

@@ -1,7 +1,7 @@
 "use client";
 
 // src/components/chat-composer/chat-composer.tsx
-import { useCallback, useRef, useState } from "react";
+import { useCallback, useRef, useState, useSyncExternalStore } from "react";
 import { Icon } from "../../icon/index.js";
 import { cn } from "../../lib/cn.js";
 import { useTypeTier } from "../../lib/density.js";
@@ -15,6 +15,7 @@ function ChatComposer({
   defaultValue = "",
   onValueChange,
   onSend,
+  allowEmpty = false,
   placeholder = "Send a message\u2026",
   sendOn = "enter",
   busy = false,
@@ -53,7 +54,10 @@ function ChatComposer({
     },
     [isControlled, onValueChange]
   );
-  const canSend = text.trim().length > 0 && !busy && !disabled;
+  const coarse = useCoarsePointer();
+  const mode = coarse ? "mod-enter" : sendOn;
+  const footerContent = typeof footer === "function" ? footer({ sendOn: mode }) : footer;
+  const canSend = (allowEmpty || text.trim().length > 0) && !busy && !disabled;
   const send = useCallback(() => {
     if (!canSend) return;
     onSend?.(text.trim());
@@ -70,11 +74,12 @@ function ChatComposer({
     (event) => {
       if (event.key !== "Enter") return;
       if (event.nativeEvent.isComposing) return;
-      if (sendOn === "mod-enter" ? !(event.metaKey || event.ctrlKey) : event.shiftKey) return;
+      if (event.defaultPrevented) return;
+      if (mode === "mod-enter" ? !(event.metaKey || event.ctrlKey) : event.shiftKey) return;
       event.preventDefault();
       send();
     },
-    [send, sendOn]
+    [send, mode]
   );
   const showStop = busy && Boolean(onStop);
   return /* @__PURE__ */ jsxs(
@@ -104,7 +109,7 @@ function ChatComposer({
             autoResize: true,
             rows: 1,
             "aria-label": label,
-            "aria-keyshortcuts": sendOn === "mod-enter" ? "Meta+Enter Control+Enter" : "Enter",
+            "aria-keyshortcuts": mode === "mod-enter" ? "Meta+Enter Control+Enter" : "Enter",
             "aria-invalid": invalid || void 0,
             disabled,
             placeholder,
@@ -145,7 +150,10 @@ function ChatComposer({
               variant: "secondary",
               size: "icon-sm",
               "aria-label": stopLabel,
-              onClick: onStop,
+              onClick: () => {
+                onStop?.();
+                if (!coarse) field.current?.focus();
+              },
               children: /* @__PURE__ */ jsx(Icon, { name: "stop", variant: "solid", className: "text-[0.75em]" })
             }
           ) : (
@@ -164,13 +172,28 @@ function ChatComposer({
             )
           )
         ] }),
-        footer ? /* @__PURE__ */ jsx("p", { className: cn("px-[calc((var(--control-sm)-1.125rem)/2)] text-muted-foreground", tier.secondary), children: footer }) : null,
+        footerContent ? /* @__PURE__ */ jsx("p", { className: cn("px-[calc((var(--control-sm)-1.125rem)/2)] text-muted-foreground", tier.secondary), children: footerContent }) : null,
         children
       ]
     }
   );
 }
 ChatComposer.displayName = "ChatComposer";
+var COARSE = "(pointer: coarse)";
+function subscribeCoarse(onChange) {
+  if (typeof window === "undefined" || !window.matchMedia) return () => {
+  };
+  const query = window.matchMedia(COARSE);
+  query.addEventListener("change", onChange);
+  return () => query.removeEventListener("change", onChange);
+}
+function useCoarsePointer() {
+  return useSyncExternalStore(
+    subscribeCoarse,
+    () => typeof window !== "undefined" && Boolean(window.matchMedia?.(COARSE).matches),
+    () => false
+  );
+}
 export {
   ChatComposer
 };

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
+};