@sableui/react 0.10.0 → 0.12.0

package/dist/index.js

@@ -42,11 +42,14 @@ export * from "./layout/index.js";
 export * from "./icon/index.js";
 export * from "./motion/index.js";
 export * from "./components/button/index.js";
+export * from "./components/button-group/index.js";
 export * from "./components/card/index.js";
+export * from "./components/caret-menu/index.js";
 export * from "./components/badge/index.js";
 export * from "./components/dialog/index.js";
 export * from "./components/separator/index.js";
 export * from "./components/input/index.js";
+export * from "./components/input-group/index.js";
 export * from "./components/textarea/index.js";
 export * from "./components/number-field/index.js";
 export * from "./components/otp-field/index.js";
@@ -84,6 +87,8 @@ export * from "./components/radio/index.js";
 export * from "./components/select/index.js";
 export * from "./components/popover/index.js";
 export * from "./components/menu/index.js";
+export * from "./components/navigation-menu/index.js";
+export * from "./components/menubar/index.js";
 export * from "./components/sheet/index.js";
 export * from "./components/table/index.js";
 export * from "./components/data-table/index.js";
@@ -161,9 +166,13 @@ import { Density, DensityProvider, useDensity, useAnchoredDensity, useTypeTier }
 import { PresentationProvider, usePresentation } from "./lib/presentation.js";
 import { useScrollActivity } from "./lib/use-scroll-activity.js";
 import { useCopy } from "./lib/use-copy.js";
+import { useSmoothWheel } from "./lib/use-smooth-wheel.js";
+import {
+  useCaretTrigger
+} from "./lib/use-caret-trigger.js";
 import { STATUS_TONES, STATUS_TONE_ICON } from "./lib/status-tone.js";
 import { PALETTE_COLORS, PALETTE_FAMILIES, PALETTE_SCALES, PALETTE_STEPS, PALETTE_TONES, isPaletteColor } from "./lib/palette.js";
-var SABLE_UI_VERSION = "0.10.0";
+var SABLE_UI_VERSION = "0.12.0";
 export {
   ART_TOKENS,
   CHART_SERIES_COUNT,
@@ -214,10 +223,12 @@ export {
   themeManifestById,
   themeManifests,
   useAnchoredDensity,
+  useCaretTrigger,
   useCopy,
   useDensity,
   usePresentation,
   useSableTheme,
   useScrollActivity,
+  useSmoothWheel,
   useTypeTier
 };

package/dist/lib/taxonomy.js

@@ -24,6 +24,8 @@ var COMPONENT_TAXONOMY = {
      options" pattern) — that its list opens in a layer is how it works, not
      what it is. Copying is `useCopy` on a Button, not a component. */
   Button: ["Actions", "either"],
+  ButtonGroup: ["Actions", "either"],
+  Menubar: ["Actions", "either"],
   OverflowMenu: ["Actions", "either"],
   Toolbar: ["Actions", "either"],
   /* ── Forms ────────────────────────────────────────────────────────────────
@@ -38,6 +40,7 @@ var COMPONENT_TAXONOMY = {
   FileDropzone: ["Forms", "page"],
   Form: ["Forms", "either"],
   Input: ["Forms", "either"],
+  InputGroup: ["Forms", "either"],
   Label: ["Forms", "either"],
   NumberField: ["Forms", "either"],
   OtpField: ["Forms", "either"],
@@ -64,6 +67,7 @@ var COMPONENT_TAXONOMY = {
   Toggle: ["Selection", "either"],
   /* ── Overlays ─────────────────────────────────────────────────────────────
      Anything that renders above the page in its own layer. */
+  CaretMenu: ["Overlays", "either"],
   CommandMenu: ["Overlays", "either"],
   ContextCard: ["Overlays", "page"],
   ContextMenu: ["Overlays", "either"],
@@ -81,6 +85,7 @@ var COMPONENT_TAXONOMY = {
      stay together; `Tree` is the hierarchy browser. */
   Breadcrumbs: ["Navigation", "either"],
   BottomNav: ["Navigation", "page"],
+  NavigationMenu: ["Navigation", "page"],
   Pagination: ["Navigation", "either"],
   ShowMore: ["Navigation", "page"],
   SideNav: ["Navigation", "page"],

package/dist/lib/use-caret-trigger.js

@@ -0,0 +1,187 @@
+"use client";
+
+// src/lib/use-caret-trigger.ts
+import { useCallback, useEffect, useRef, useState } from "react";
+function useCaretTrigger({ triggers }) {
+  const [field, setField] = useState(null);
+  const [match, setMatch] = useState(null);
+  const dismissedAt = useRef(null);
+  const composing = useRef(false);
+  const triggersRef = useRef(triggers);
+  triggersRef.current = triggers;
+  const evaluate = useCallback(() => {
+    if (!field || composing.current) return;
+    const next = field.ownerDocument.activeElement === field ? findMatch(field, triggersRef.current) : null;
+    if (!next || next.start !== dismissedAt.current) dismissedAt.current = null;
+    const visible = next && dismissedAt.current === null ? next : null;
+    setMatch((prev) => sameMatch(prev, visible) ? prev : visible);
+  }, [field]);
+  useEffect(() => {
+    if (!field) return;
+    const doc = field.ownerDocument;
+    const onSelection = () => {
+      if (doc.activeElement === field) evaluate();
+    };
+    const onCompositionStart = () => {
+      composing.current = true;
+    };
+    const onCompositionEnd = () => {
+      composing.current = false;
+      setTimeout(evaluate, 0);
+    };
+    const onBlur = () => {
+      dismissedAt.current = null;
+      setMatch(null);
+    };
+    const onInput = (event) => {
+      if (event.target === field) evaluate();
+    };
+    doc.addEventListener("input", onInput);
+    field.addEventListener("focus", evaluate);
+    field.addEventListener("click", evaluate);
+    field.addEventListener("keyup", evaluate);
+    field.addEventListener("compositionstart", onCompositionStart);
+    field.addEventListener("compositionend", onCompositionEnd);
+    field.addEventListener("blur", onBlur);
+    doc.addEventListener("selectionchange", onSelection);
+    return () => {
+      doc.removeEventListener("input", onInput);
+      field.removeEventListener("focus", evaluate);
+      field.removeEventListener("click", evaluate);
+      field.removeEventListener("keyup", evaluate);
+      field.removeEventListener("compositionstart", onCompositionStart);
+      field.removeEventListener("compositionend", onCompositionEnd);
+      field.removeEventListener("blur", onBlur);
+      doc.removeEventListener("selectionchange", onSelection);
+    };
+  }, [field, evaluate]);
+  const dismiss = useCallback(() => {
+    setMatch((current) => {
+      if (current) dismissedAt.current = current.start;
+      return null;
+    });
+  }, []);
+  const replace = useCallback(
+    (text) => {
+      if (!field || !match) return;
+      insertText(field, match.start, match.end, text);
+      dismissedAt.current = match.start;
+      evaluate();
+    },
+    [field, match, evaluate]
+  );
+  const getAnchorRect = useCallback(() => {
+    if (!field || !match) return null;
+    return caretRect(field, match.start);
+  }, [field, match]);
+  return { fieldRef: setField, field, match, getAnchorRect, replace, dismiss };
+}
+var BOUNDARY = /[\s([{"'“‘]/;
+function findMatch(field, triggers) {
+  const { value, selectionStart, selectionEnd } = field;
+  if (selectionStart === null || selectionStart !== selectionEnd) return null;
+  return matchAt(value, selectionStart, triggers);
+}
+function matchAt(value, caret, triggers) {
+  for (let i = caret - 1; i >= 0; i--) {
+    const ch = value[i];
+    if (ch === "\n") return null;
+    const trigger = triggers.find((t) => t.char === ch);
+    if (trigger && opens(value, i, caret, trigger)) {
+      return { trigger, query: value.slice(i + 1, caret), start: i, end: caret };
+    }
+  }
+  return null;
+}
+function opens(value, i, caret, trigger) {
+  const query = value.slice(i + 1, caret);
+  if (!trigger.allowSpaces && /\s/.test(query)) return false;
+  if (query.length > (trigger.maxQueryLength ?? 32)) return false;
+  if (/^\s/.test(query)) return false;
+  const before = i === 0 ? "" : value[i - 1];
+  if (before !== "" && !BOUNDARY.test(before)) return false;
+  if (trigger.atStart && value.slice(0, i).trim() !== "") return false;
+  return true;
+}
+function sameMatch(a, b) {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  return a.trigger === b.trigger && a.query === b.query && a.start === b.start && a.end === b.end;
+}
+function insertText(field, start, end, text) {
+  field.focus();
+  field.setSelectionRange(start, end);
+  const doc = field.ownerDocument;
+  const inserted = text === "" ? typeof doc.execCommand === "function" && doc.execCommand("delete", false) : typeof doc.execCommand === "function" && doc.execCommand("insertText", false, text);
+  if (!inserted || field.value.slice(start, start + text.length) !== text) {
+    const next = field.value.slice(0, start) + text + field.value.slice(end);
+    const proto = field instanceof HTMLTextAreaElement ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype;
+    Object.getOwnPropertyDescriptor(proto, "value")?.set?.call(field, next);
+    field.dispatchEvent(new Event("input", { bubbles: true }));
+  }
+  const caret = start + text.length;
+  field.setSelectionRange(caret, caret);
+}
+var MIRRORED = [
+  "boxSizing",
+  "width",
+  "borderTopWidth",
+  "borderRightWidth",
+  "borderBottomWidth",
+  "borderLeftWidth",
+  "paddingTop",
+  "paddingRight",
+  "paddingBottom",
+  "paddingLeft",
+  "fontFamily",
+  "fontSize",
+  "fontStyle",
+  "fontVariant",
+  "fontWeight",
+  "fontStretch",
+  "fontFeatureSettings",
+  "lineHeight",
+  "letterSpacing",
+  "wordSpacing",
+  "textIndent",
+  "textTransform",
+  "tabSize",
+  "direction"
+];
+function caretRect(field, index) {
+  const doc = field.ownerDocument;
+  const view = doc.defaultView ?? window;
+  const style = view.getComputedStyle(field);
+  const mirror = doc.createElement("div");
+  const s = mirror.style;
+  for (const prop of MIRRORED) s[prop] = style[prop];
+  s.position = "absolute";
+  s.visibility = "hidden";
+  s.top = "0";
+  s.left = "-9999px";
+  s.overflow = "hidden";
+  const multiline = field instanceof HTMLTextAreaElement;
+  s.whiteSpace = multiline ? "pre-wrap" : "pre";
+  s.overflowWrap = multiline ? "break-word" : "normal";
+  mirror.textContent = field.value.slice(0, index);
+  const marker = doc.createElement("span");
+  marker.textContent = field.value.slice(index) || "\u200B";
+  mirror.appendChild(marker);
+  doc.body.appendChild(mirror);
+  const box = field.getBoundingClientRect();
+  const lineHeight = Number.parseFloat(style.lineHeight) || marker.offsetHeight;
+  const rect = new DOMRect(
+    box.left + marker.offsetLeft - field.scrollLeft,
+    box.top + marker.offsetTop - field.scrollTop,
+    1,
+    lineHeight
+  );
+  mirror.remove();
+  return rect;
+}
+export {
+  caretRect,
+  findMatch,
+  matchAt,
+  useCaretTrigger
+};

package/dist/lib/use-copy.js

@@ -11,7 +11,12 @@ function useCopy(text, { timeout = 1500 } = {}) {
   const copy = useCallback(async () => {
     if (typeof navigator === "undefined" || !navigator.clipboard) return false;
     try {
-      await navigator.clipboard.writeText(text);
+      const value = typeof text === "function" ? text() : text;
+      if (typeof value === "string") await navigator.clipboard.writeText(value);
+      else if (typeof ClipboardItem !== "undefined" && navigator.clipboard.write) {
+        const blob = value.then((t) => new Blob([t], { type: "text/plain" }));
+        await navigator.clipboard.write([new ClipboardItem({ "text/plain": blob })]);
+      } else await navigator.clipboard.writeText(await value);
     } catch {
       return false;
     }

package/dist/lib/use-smooth-wheel.js

@@ -0,0 +1,164 @@
+"use client";
+
+// src/lib/use-smooth-wheel.ts
+import { useCallback, useEffect, useRef } from "react";
+import { useMotion } from "../motion/MotionProvider.js";
+var LINE_HEIGHT = 16;
+var PAGE_HEIGHT = 400;
+function toPixels(delta, mode) {
+  if (mode === 1) return delta * LINE_HEIGHT;
+  if (mode === 2) return delta * PAGE_HEIGHT;
+  return delta;
+}
+function isNotch(event) {
+  if (event.deltaMode !== 0) return true;
+  const legacy = event.wheelDeltaY;
+  if (legacy) return event.deltaX === 0 && legacy % 120 === 0;
+  return event.deltaX === 0 && Number.isInteger(event.deltaY) && Math.abs(event.deltaY) >= 50;
+}
+function innerScrolls(target, region, deltaY) {
+  for (let el = target instanceof Element ? target : null; el && el !== region; el = el.parentElement) {
+    if (!(el instanceof HTMLElement) || el.scrollHeight <= el.clientHeight) continue;
+    const overflow = getComputedStyle(el).overflowY;
+    if (overflow !== "auto" && overflow !== "scroll") continue;
+    const max = el.scrollHeight - el.clientHeight;
+    if (deltaY < 0 ? Math.round(el.scrollTop) > 0 : Math.round(el.scrollTop) < max) return true;
+  }
+  return false;
+}
+function cssOwnsMotion(el) {
+  const style = getComputedStyle(el);
+  return style.scrollBehavior === "smooth" || style.scrollSnapType !== "" && style.scrollSnapType !== "none";
+}
+var EASE_PER_FRAME = 0.14;
+var FRAME_MS = 1e3 / 60;
+var SETTLE_PX = 0.5;
+function useSmoothWheel({
+  axis = "vertical",
+  mapVertical = true,
+  smooth = true
+} = {}) {
+  const { enabled: motion } = useMotion();
+  const settings = useRef({ axis, mapVertical, smooth: smooth && motion });
+  settings.current = { axis, mapVertical, smooth: smooth && motion };
+  const horizontal = axis === "horizontal";
+  const active = smooth && motion || horizontal && mapVertical;
+  const nodeRef = useRef(null);
+  const anim = useRef(null);
+  const stop = useCallback(() => {
+    if (anim.current) cancelAnimationFrame(anim.current.frame);
+    anim.current = null;
+  }, []);
+  const step = useCallback((now) => {
+    const el = nodeRef.current;
+    const a = anim.current;
+    if (!el || !a) return;
+    const key = settings.current.axis === "horizontal" ? "scrollLeft" : "scrollTop";
+    const dt = Math.min(64, now - a.last);
+    a.last = now;
+    a.pos += (a.target - a.pos) * (1 - (1 - EASE_PER_FRAME) ** (dt / FRAME_MS));
+    if (Math.abs(a.target - a.pos) < SETTLE_PX) a.pos = a.target;
+    el[key] = a.pos;
+    a.written = el[key];
+    if (a.pos === a.target) anim.current = null;
+    else a.frame = requestAnimationFrame(step);
+  }, []);
+  const onWheel = useCallback(
+    (event) => {
+      const el = nodeRef.current;
+      if (!el || event.ctrlKey) return;
+      const { axis: current, mapVertical: map, smooth: ease } = settings.current;
+      const sideways = current === "horizontal";
+      if (event.shiftKey) return;
+      if (Math.abs(event.deltaX) > Math.abs(event.deltaY) || event.deltaY === 0) return;
+      if (sideways && !map) return;
+      if (innerScrolls(event.target, el, event.deltaY)) return;
+      const notch = ease && isNotch(event) && !cssOwnsMotion(el);
+      if (!sideways && !notch) return;
+      const key = sideways ? "scrollLeft" : "scrollTop";
+      const max = sideways ? el.scrollWidth - el.clientWidth : el.scrollHeight - el.clientHeight;
+      if (max <= 0) return;
+      const delta = toPixels(event.deltaY, event.deltaMode);
+      const from = notch && anim.current ? anim.current.target : el[key];
+      if (delta < 0 && Math.round(from) <= 0 || delta > 0 && Math.round(from) >= max) return;
+      event.preventDefault();
+      const target = Math.max(0, Math.min(max, from + delta));
+      if (!notch) {
+        stop();
+        el[key] = target;
+        return;
+      }
+      if (anim.current) {
+        anim.current.target = target;
+        return;
+      }
+      anim.current = {
+        target,
+        pos: el[key],
+        written: el[key],
+        last: performance.now(),
+        frame: requestAnimationFrame(step)
+      };
+    },
+    [step, stop]
+  );
+  const onScroll = useCallback(() => {
+    const el = nodeRef.current;
+    const a = anim.current;
+    if (!el || !a) return;
+    const key = settings.current.axis === "horizontal" ? "scrollLeft" : "scrollTop";
+    if (Math.abs(el[key] - a.written) > 1) stop();
+  }, [stop]);
+  const activeRef = useRef(active);
+  activeRef.current = active;
+  const attached = useRef(null);
+  const sync = useCallback(() => {
+    const want = activeRef.current ? nodeRef.current : null;
+    if (attached.current === want) return;
+    const was = attached.current;
+    if (was) {
+      was.removeEventListener("wheel", onWheel);
+      was.removeEventListener("scroll", onScroll);
+      was.removeEventListener("pointerdown", stop);
+      stop();
+    }
+    attached.current = want;
+    if (want) {
+      want.addEventListener("wheel", onWheel, { passive: false });
+      want.addEventListener("scroll", onScroll, { passive: true });
+      want.addEventListener("pointerdown", stop, { passive: true });
+    }
+  }, [onWheel, onScroll, stop]);
+  useEffect(sync, [active, sync]);
+  return useCallback(
+    (node) => {
+      nodeRef.current = node;
+      sync();
+    },
+    [sync]
+  );
+}
+function scrollRegionKeyDown(event, orientation) {
+  const el = event.currentTarget;
+  const horizontal = orientation === "horizontal";
+  const page = horizontal ? el.clientWidth : el.clientHeight;
+  const step = Math.max(40, page * 0.2);
+  const back = horizontal ? "ArrowLeft" : "ArrowUp";
+  const forward = horizontal ? "ArrowRight" : "ArrowDown";
+  const axis = horizontal ? "scrollLeft" : "scrollTop";
+  const max = horizontal ? el.scrollWidth - el.clientWidth : el.scrollHeight - el.clientHeight;
+  let next = null;
+  if (event.key === back) next = el[axis] - step;
+  else if (event.key === forward) next = el[axis] + step;
+  else if (event.key === "Home") next = 0;
+  else if (event.key === "End") next = max;
+  else if (event.key === "PageUp") next = el[axis] - page;
+  else if (event.key === "PageDown") next = el[axis] + page;
+  if (next === null) return;
+  event.preventDefault();
+  el[axis] = Math.max(0, Math.min(max, next));
+}
+export {
+  scrollRegionKeyDown,
+  useSmoothWheel
+};

package/dist/patterns/chat-panel.js

@@ -145,7 +145,7 @@ function ChatPanel() {
             onStop: () => void 0,
             stopLabel: "Stop answering",
             onAttach: () => void 0,
-            footer: "Enter to send \xB7 Shift+Enter for a new line",
+            footer: ({ sendOn }) => sendOn === "enter" ? "Enter to send \xB7 Shift+Enter for a new line" : null,
             actions: /* @__PURE__ */ jsxs(
               SettingsMenu,
               {

package/dist/patterns/chat-panel.meta.js

@@ -4,6 +4,7 @@ var chatPanelMeta = {
   summary: "A full-height conversation surface: titled header, scrolling transcript, and a composer pinned to the bottom \u2014 the assembled shape of an AI assistant, a support thread, or a DM.",
   intent: "Reach for this for any conversation that owns its screen \u2014 an assistant, a support inbox thread, a DM. Not for a chat docked beside other work (compose the same three parts inside a Sheet or a PanelGroup instead), and not for a comment thread under an article, which is a FeedPage concern.",
   notes: [
+    "This is the assembled screen with sample data. To wire it to a real streaming source (a hook such as useChat, or your own transport), read `sable docs building-a-chat`: who owns what, the turn lifecycle mapped to props, and every failure state.",
     "The panel is a fixed-height column, not a growing page. `h-[calc(100dvh_-_--spacing(12))]` on the Card (the viewport minus the Page's py-6, in spacing units so density moves both together \u2014 a fixed `3rem` drifts the moment density moves the padding) and `flex-1 min-h-0` on the MessageScroller are what make the transcript scroll instead of the document \u2014 the single most common thing to get wrong here, and it fails by pushing the composer off the bottom of the screen.",
     "The panel is a Card, not a hand-built bordered section: CardHeader (title, description, CardAction), the MessageScroller and a CardFooter all inset by the card's own `--card-p`, so the three regions share one edge at any card density.",
     "`dvh` rather than `vh`: on mobile the URL bar collapses, and a `vh`-sized panel puts the composer under it exactly when someone is trying to type.",

package/dist/styles.css

@@ -1006,6 +1006,31 @@
 	margin-inline: calc(-1 * max(--spacing(1), calc(var(--radius-md) / 3)));
 }
 
+/* ButtonGroup's joins. Keyed to sibling Buttons (`data-variant`), never to
+   :first/:last-child: an open Menu inserts focus-guard spans beside its
+   trigger, and a position rule then read the chevron as "not last" and
+   squared its outer corner for as long as the menu was open. Inner corners
+   square through the per-side radius vars Button reads; bordered buttons
+   overlap by their hairline; filled and ghost ones get a seam in their own
+   ink, except while focused, where the shadow is the focus ring. */
+@utility button-group-join {
+	& > [data-variant] ~ [data-variant] {
+		--button-radius-s: 0px;
+	}
+	& > [data-variant]:has(~ [data-variant]) {
+		--button-radius-e: 0px;
+	}
+	& > [data-variant] ~ [data-variant="outline"] {
+		margin-inline-start: -1px;
+	}
+	& > [data-variant] ~ [data-variant]:not([data-variant="outline"], :focus-visible) {
+		box-shadow: inset 1px 0 0 color-mix(in oklab, currentColor 20%, transparent);
+	}
+	& > :focus-visible {
+		z-index: 1;
+	}
+}
+
 @utility sable-frame {
 	--sable-frame-radius: var(--radius-lg);
 	--sable-frame-padding: --spacing(4);

package/llms/components/app-header.md

@@ -36,7 +36,7 @@ Use AppHeader for compact application chrome at the top of a screen, usually wit
 
 ## Related
 
-- Components: AppShell, PageHeader, BottomNav
+- Components: AppShell, PageHeader, BottomNav, NavigationMenu
 
 ## Examples
 

package/llms/components/button-group.md

@@ -0,0 +1,55 @@
+# ButtonGroup
+
+**Status:** stable
+
+Buttons joined into one control: a split button (an action beside the chevron that opens its menu) or a short run of related actions. The children stay ordinary Buttons; the group squares their inner corners, collapses bordered seams into one hairline, and draws a seam between filled ones.
+
+**Keywords:** split button, button group, segmented actions, dropdown button, joined buttons, toolbar
+
+## Usage
+
+Use ButtonGroup when one action has close alternatives (Copy page, with Open in… behind a chevron) or a few actions belong together as one object (zoom out, reset, zoom in). Use ToggleGroup for a choice that stays selected, and Tabs to switch views.
+
+### Best practices
+
+- Do: Give the children one height: `size="sm"` with `size="icon-sm"`, `md` with `icon`. The group aligns them but cannot reconcile two heights into one edge.
+- Do: For a split button, put the main action first and a Menu whose trigger is the chevron Button second, with an aria-label on the trigger ("More page actions").
+- Do: Name the group with aria-label when the buttons alone do not say what they act on.
+- Don't: Do not round or border the children yourself to make them meet; that is the group's job, and an override breaks under a theme's button shape.
+- Don't: Do not use it for a selection that stays on. That is ToggleGroup, which carries the pressed state.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| role | string | "group" | Group semantics, so a screen reader announces the buttons as one set. Pass `toolbar` when it carries arrow-key navigation of your own. |
+| className | string | — | Layout classes for the group (margins, alignment). The children's look comes from their own variants. |
+| ...props | ComponentPropsWithRef<"div"> | — | All native <div> attributes, including aria-label. |
+
+## Accessibility
+
+- Renders role="group", so assistive tech announces the buttons as one set; name it with aria-label.
+- Each child keeps its own focus stop and label; a focused child is raised above its neighbour so its ring is drawn whole.
+- An icon-only chevron that opens a menu needs its own aria-label, such as "More page actions".
+
+## Related
+
+- Components: Button, Menu, Toggle
+
+## Examples
+
+### Split button with a menu
+
+```tsx
+import { Button, ButtonGroup, Icon, Menu, MenuContent, MenuItem, MenuTrigger } from "@sableui/react"
+
+<ButtonGroup aria-label="Page actions"><Button variant="outline" size="sm" iconStart={<Icon name="copy" />} onClick={copy}>Copy page</Button><Menu><MenuTrigger render={<Button variant="outline" size="icon-sm" aria-label="More page actions" />}><Icon name="chevron-down" /></MenuTrigger><MenuContent align="end"><MenuItem icon={<Icon name="file" />} description="View this page as plain text">View as Markdown</MenuItem></MenuContent></Menu></ButtonGroup>
+```
+
+### Related actions
+
+```tsx
+import { Button, ButtonGroup, Icon } from "@sableui/react"
+
+<ButtonGroup aria-label="Zoom"><Button variant="secondary" size="icon-sm" aria-label="Zoom out"><Icon name="minus" /></Button><Button variant="secondary" size="sm">100%</Button><Button variant="secondary" size="icon-sm" aria-label="Zoom in"><Icon name="plus" /></Button></ButtonGroup>
+```

package/llms/components/button.md

@@ -13,7 +13,7 @@ Use Button when the user commits an action, submits a form, opens UI, or confirm
 ### Best practices
 
 - Do: Use a single primary button in a view or dense panel so the action hierarchy stays obvious.
-- Do: For a copy control, pair an icon Button with `useCopy(text, { timeout? })`. It takes the text when the hook is called and returns `{ copy, copied }`; `copy()` takes no argument, so pass the value the button copies to the hook, not to `copy`.
+- Do: For a copy control, pair an icon Button with `useCopy(text, { timeout? })`. It takes the text when the hook is called and returns `{ copy, copied }`; `copy()` takes no argument, so pass the value the button copies to the hook, not to `copy`. Text that costs something to produce (a file to fetch) goes in as a function, `useCopy(() => fetch(url).then((r) => r.text()))`, called only on click.
 - Do: Write labels as actions, such as "Save changes" or "Delete draft", instead of vague labels like "OK".
 - Do: Use loading with loadingLabel for async work so the action cannot double-fire and the state is announced.
 - Do: Put icons in iconStart / iconEnd rather than as children, so the button applies its optical padding. Start icons say what the action is (plus, share); end icons say where it goes (chevron-right, external).