rift-ds 1.9.0 → 1.11.0

package/README.md

@@ -13,7 +13,7 @@ An open source React design system built for AI products and coding agents: comp
 
 ## Why Rift DS
 
-- **<!-- component-count -->152<!-- /component-count --> components.** Buttons, forms and tables through to charts, navigation and overlays, each typed and documented with live examples. React is the only required peer dependency.
+- **<!-- component-count -->155<!-- /component-count --> components.** Buttons, forms and tables through to charts, navigation and overlays, each typed and documented with live examples. Every one forwards a ref and your own attributes to its element, state you can own works controlled or uncontrolled (a modal opens when your app says so, by design), and every word a component writes has a prop you can localise. The build checks the first two on every component, and the words wherever they sit in markup. React and React DOM are the only required peer dependencies.
 - **AI patterns, the whole chat and templates, ready to use.** Composer, streaming chat thread, tool calls, reasoning and thread panel are in the box, the complete AI chat ships assembled as one widget that one command scaffolds, and the docs site has complete template screens built from them.
 - **Fully themeable.** The shipped themes are complete looks to start from, each in light and dark. One `data-brand` attribute applies a theme, and a few CSS overrides make your own.
 - **Ready for coding agents.** One command installs the agent skills, and a public MCP endpoint serves every component's props, so your agent builds with the library as it actually is. No key, no account.
@@ -94,13 +94,13 @@ import 'rift-ds/tokens/presets/presets.css';
 
 ## Components
 
-<!-- component-count -->152<!-- /component-count --> components, including a chat set for AI products (Chat thread, Composer, Tool call, Reasoning, Thread panel) and Shader field, a WebGL2 ambient background whose light sources read your colour tokens at runtime, so it re-themes with everything else. Details and live examples are on the [docs site](https://rift-ds.com/components).
+<!-- component-count -->155<!-- /component-count --> components, including a chat set for AI products (Chat thread, Composer, Tool call, Reasoning, Thread panel) and Shader field, a WebGL2 ambient background whose light sources read your colour tokens at runtime, so it re-themes with everything else. Details and live examples are on the [docs site](https://rift-ds.com/components).
 
 <details>
 <summary>The full list</summary>
 
 <!-- component-list:start -->
-Accordion · Agent plan · Agent rail · Agent status · AI button · Alert · Alert dialog · Anchor nav · Animated number · App layout · App sidebar · Area chart · Artifact card · Artifact panel · Attachment drop zone · Attachment group · Attachment tile · Attachment viewer · Avatar · Avatar group · Badge · Banner · Bar chart · Bottom nav · Breadcrumb · Button · Button group · Card · Card stack · Carousel · Chat header · Chat marker · Chat message · Chat thread · Checkbox · Chip · Circular button · Code block · Code diff · Colour picker · Combo chart · Combobox · Command palette · Composer · Contact card · Context menu · Contribution graph · Data table · Date input · Date picker · Dialog · Divider · Document chip · Drawer · Dropdown · Dropdown menu · Empty state · Entity card · Event calendar · Field · Figure · File input · Filter bar · Funnel chart · Gantt chart · Gauge · Globe · Hover card · Image compare · Input · Inspector colour picker · Inspector dropdown · Inspector input · Inspector section · Inspector segments · Inspector slider · Inspector toggle switch · Instructions · Interrupt card · Kbd · Legend tile · Lightbox · Line chart · Link list · Map callout · Map legend · Mention · Message actions · Message card · Meter · Model picker · Nav · Nav list · Notification centre · Number input · Pagination · Panel · Pie chart · Pin input · Pixel avatar · Popover · Progress bar · Prompt suggestions · Prose · Quote · Radar chart · Radial chart · Radio button · Rating · Reasoning · Rich dropdown · Scatter chart · Section title · Segmented control · Selection card · Shader field · Sidebar panel · Skeleton · Slider · Source chip · Source trail · Sparkline · Spinner · Split button · Split pane · Stacked bar chart · Stat · Status dot · Stepper · Streaming text · Swatch · Table · Tabs · Tag input · Textarea · Thread panel · Thread tabs · Time picker · Timeline · Toast · Toggle group · Toggle switch · Tool call · Toolbar · Tooltip · Top app bar · Tree view · Treemap · Usage card · Waveform · Widget · World map
+Accordion · Agent plan · Agent rail · Agent status · AI button · Alert · Alert dialog · Anchor nav · Animated number · App layout · App sidebar · Area chart · Artifact card · Artifact panel · Attachment drop zone · Attachment group · Attachment tile · Attachment viewer · Avatar · Avatar group · Badge · Banner · Bar chart · Bento tile · Bento tile art · Bottom nav · Breadcrumb · Button · Button group · Card · Card stack · Carousel · Chat header · Chat marker · Chat message · Chat thread · Checkbox · Chip · Circular button · Code block · Code diff · Colour picker · Combo chart · Combobox · Command palette · Composer · Contact card · Context menu · Contribution graph · Data table · Date input · Date picker · Dialog · Divider · Document chip · Drawer · Dropdown · Dropdown menu · Empty state · Entity card · Event calendar · Field · Figure · File input · Filter bar · Funnel chart · Gantt chart · Gauge · Globe · Hover card · Image compare · Input · Inspector colour picker · Inspector dropdown · Inspector input · Inspector section · Inspector segments · Inspector slider · Inspector toggle switch · Instructions · Interrupt card · Kbd · Legend tile · Lightbox · Line chart · Link list · Map callout · Map legend · Mention · Message actions · Message card · Meter · Model picker · Nav · Nav list · Notification centre · Number input · Pagination · Panel · Pie chart · Pin input · Pixel avatar · Popover · Progress bar · Prompt suggestions · Prose · Question card · Quote · Radar chart · Radial chart · Radio button · Rating · Reasoning · Rich dropdown · Scatter chart · Section title · Segmented control · Selection card · Shader field · Sidebar panel · Skeleton · Slider · Source chip · Source trail · Sparkline · Spinner · Split button · Split pane · Stacked bar chart · Stat · Status dot · Stepper · Streaming text · Swatch · Table · Tabs · Tag input · Textarea · Thread panel · Thread tabs · Time picker · Timeline · Toast · Toggle group · Toggle switch · Tool call · Toolbar · Tooltip · Top app bar · Tree view · Treemap · Usage card · Waveform · Widget · World map
 <!-- component-list:end -->
 
 </details>

package/behaviors/useFocusScope.d.ts

@@ -2,11 +2,15 @@
  * Focus containment for modal overlays: initial focus, Tab wrapping, focus
  * restore, and background isolation.
  *
- * Restore is guarded by `document.contains` — the element that opened a
- * dialog can be gone by the time it closes (a row the dialog itself deleted),
- * and restoring into a detached node silently drops focus to `<body>`. It
- * also runs when the component unmounts while open, which the per-component
- * implementations this replaces never handled.
+ * Restore is guarded twice. The element that opened a dialog can be gone by
+ * the time it closes (a row the dialog itself deleted), and it can still be in
+ * the document but hidden: a button inside a popover that closed underneath
+ * the dialog sits in a `display: none` panel, and `.focus()` on it silently
+ * drops focus to `<body>`. A detached element is skipped; a hidden one hands
+ * focus to the first visible control of its nearest visible ancestor, which
+ * for a closed popover is its trigger. It also runs when the component
+ * unmounts while open, which the per-component implementations this replaced
+ * never handled.
  *
  * Background isolation uses `inert`, not `aria-hidden`: a JS focus trap only
  * fences the Tab key, while a screen reader's virtual cursor walks the page
@@ -17,7 +21,9 @@
  * inert set is recomputed only when a scope activates or deactivates, so a
  * portal that mounts *while* a modal is open (a toast, say) is not inerted
  * until the stack next changes — under `aria-modal` that content is outside
- * the dialog's world anyway.
+ * the dialog's world anyway. Live regions are never inerted: a toast region
+ * (`aria-live`, a direct child of the body) must keep announcing, and keep
+ * its actions pressable, while a modal is open.
  */
 type FocusScopeOptions = {
     /** Whether the scope is active — the overlay's open state. */

package/behaviors/useFocusScope.js

@@ -8,6 +8,7 @@ const applyInert = () => {
   for (const child of Array.from(document.body.children)) {
     if (!(child instanceof HTMLElement)) continue;
     if (child.tagName === "SCRIPT" || child.tagName === "STYLE") continue;
+    if (child.hasAttribute("aria-live")) continue;
     const shouldBeInert = top !== void 0 && !child.contains(top.panel);
     if (shouldBeInert && !child.inert) {
       child.inert = true;
@@ -22,6 +23,15 @@ const applyInert = () => {
     inerted.clear();
   }
 };
+const isVisible = (el) => el.getClientRects().length > 0;
+const restoreTarget = (previous) => {
+  if (!document.contains(previous)) return null;
+  if (isVisible(previous)) return previous;
+  for (let el = previous.parentElement; el && el !== document.body; el = el.parentElement) {
+    if (isVisible(el)) return getFocusable(el)[0] ?? null;
+  }
+  return null;
+};
 function useFocusScope(ref, options) {
   const optionsRef = useRef(options);
   useEffect(() => {
@@ -71,8 +81,8 @@ function useFocusScope(ref, options) {
         inertScopes.splice(index, 1);
         applyInert();
       }
-      if (optionsRef.current.restoreFocus !== false && previousFocus && document.contains(previousFocus)) {
-        previousFocus.focus();
+      if (optionsRef.current.restoreFocus !== false && previousFocus) {
+        restoreTarget(previousFocus)?.focus();
       }
     };
   }, [active, ref]);

package/behaviors/useLayer.d.ts

@@ -1,19 +1,33 @@
 /**
  * The dismissal layer stack — the single owner of the document-level Escape
- * and outside-press listeners for every overlay in the library.
+ * and outside-press listeners for every overlay in the library, modal and
+ * non-modal alike.
  *
  * Before this existed, each open overlay registered its own document keydown,
- * so Escape over a stacked Dialog-in-Drawer closed both at once. The stack
- * routes each interaction to the **topmost** open layer only: Escape
- * dismisses it (or is swallowed when it is not Escape-dismissible — a lower
- * layer must never close through a blocking one), and an outside press
- * dismisses it only when the press lands outside every element the layer
- * claims. Layers below are untouched; one press, one layer.
+ * so Escape over a stacked Dialog-in-Drawer closed both at once, and a
+ * popover or menu open inside a Dialog closed together with it. The stack
+ * routes each interaction by stack order:
+ *
+ * - **Escape** goes to the topmost open layer only: it dismisses it, or is
+ *   swallowed when that layer is not Escape-dismissible (a lower layer must
+ *   never close through a blocking one). One press, one layer. An Escape a
+ *   component has already handled (`event.preventDefault()`, say an input
+ *   clearing its own text) is left alone.
+ * - **An outside press** walks down from the top: every layer the press
+ *   lands outside of, and that opts into light dismiss, closes; the walk
+ *   stops at the first layer that contains the press or does not
+ *   light-dismiss (a modal, which owns its backdrop). So a press on a
+ *   Dialog's body closes the menus open above it and leaves the Dialog.
+ * - **Backdrop clicks** stay with the modal that draws the backdrop, but a
+ *   press that began while another layer was on top was that layer's press:
+ *   `ownsPress()` tells the modal so, and it keeps itself open. Without it, a
+ *   press on the backdrop closed the open menu at pointerdown and then the
+ *   Dialog on click, two layers for one press.
  *
  * Exactly two document listeners exist while any layer is open, and none
- * while the stack is empty. Registration order is stack order — overlays
- * portal into `document.body` in the order they open, so stack order and
- * paint order agree without reading z-index.
+ * while the stack is empty. Registration order is stack order: overlays open
+ * in the order they are stacked, so stack order and paint order agree
+ * without reading z-index.
  */
 type LayerOptions = {
     /** The overlay's open state — the layer registers while true. */
@@ -23,21 +37,31 @@ type LayerOptions = {
     /** Whether Escape dismisses this layer. Default true. */
     dismissOnEscape?: boolean;
     /**
-     * Whether a pointerdown outside `getElements()` dismisses this layer.
-     * Default false — modal components keep their own backdrop click handler,
-     * which is part of their DOM and needs no document listener.
+     * Whether a pointerdown outside `getElements()` dismisses this layer (light
+     * dismiss: popovers, menus, listboxes). Default false — modal components
+     * keep their own backdrop click handler, which is part of their DOM, and
+     * gate it on `ownsPress()`.
      */
     dismissOnOutsidePress?: boolean;
     /**
      * The elements that count as "inside" for outside-press checks — typically
-     * the panel and its trigger. Only read when `dismissOnOutsidePress` is on.
+     * the panel and its trigger. Read when `dismissOnOutsidePress` is on, and
+     * also to stop the outside-press walk at a layer that contains the press.
      */
     getElements?: () => (HTMLElement | null | undefined)[];
 };
+export type LayerHandle = {
+    /**
+     * Whether the current press belongs to this layer: it was the topmost
+     * layer when the press began (or, outside a press, is topmost now). Gate a
+     * backdrop click on it.
+     */
+    ownsPress: () => boolean;
+};
 /**
  * Register an overlay on the dismissal stack while `open` is true. Options
  * are read at event time, so a `dismissOnEscape` toggle takes effect without
  * re-registering (which would wrongly move the layer to the top).
  */
-export declare function useLayer(options: LayerOptions): void;
+export declare function useLayer(options: LayerOptions): LayerHandle;
 export {};

package/behaviors/useLayer.js

@@ -1,39 +1,43 @@
 "use client";
-import { useRef, useEffect } from "react";
+import { useRef, useEffect, useCallback } from "react";
 const layers = [];
 let listenersInstalled = false;
+let pressOwner = null;
+const contains = (layer, target) => (layer.optionsRef.current.getElements?.() ?? []).some((el) => el?.contains(target));
 const handleKeyDown = (event) => {
-  if (event.key !== "Escape") return;
+  if (event.key !== "Escape" || event.defaultPrevented) return;
   const top = layers[layers.length - 1];
   if (!top) return;
   const options = top.optionsRef.current;
-  if (options.dismissOnEscape === false) return;
   event.preventDefault();
+  if (options.dismissOnEscape === false) return;
   options.onDismiss?.();
 };
 const handlePointerDown = (event) => {
-  const top = layers[layers.length - 1];
-  if (!top) return;
-  const options = top.optionsRef.current;
-  if (!options.dismissOnOutsidePress) return;
+  pressOwner = layers[layers.length - 1] ?? null;
   const target = event.target instanceof Node ? event.target : null;
   if (!target) return;
-  const inside = (options.getElements?.() ?? []).some((el) => el?.contains(target));
-  if (!inside) options.onDismiss?.();
+  for (const layer of [...layers].reverse()) {
+    const options = layer.optionsRef.current;
+    if (!options.dismissOnOutsidePress || contains(layer, target)) break;
+    options.onDismiss?.();
+  }
 };
 const syncListeners = () => {
   if (layers.length > 0 && !listenersInstalled) {
     document.addEventListener("keydown", handleKeyDown);
-    document.addEventListener("pointerdown", handlePointerDown);
+    document.addEventListener("pointerdown", handlePointerDown, true);
     listenersInstalled = true;
   } else if (layers.length === 0 && listenersInstalled) {
     document.removeEventListener("keydown", handleKeyDown);
-    document.removeEventListener("pointerdown", handlePointerDown);
+    document.removeEventListener("pointerdown", handlePointerDown, true);
     listenersInstalled = false;
+    pressOwner = null;
   }
 };
 function useLayer(options) {
   const optionsRef = useRef(options);
+  const layerRef = useRef(null);
   useEffect(() => {
     optionsRef.current = options;
   });
@@ -41,14 +45,22 @@ function useLayer(options) {
   useEffect(() => {
     if (!open) return;
     const layer = { optionsRef };
+    layerRef.current = layer;
     layers.push(layer);
     syncListeners();
     return () => {
       const index = layers.indexOf(layer);
       if (index !== -1) layers.splice(index, 1);
+      layerRef.current = null;
       syncListeners();
     };
   }, [open]);
+  const ownsPress = useCallback(() => {
+    const layer = layerRef.current;
+    if (!layer) return false;
+    return pressOwner ? pressOwner === layer : layers[layers.length - 1] === layer;
+  }, []);
+  return { ownsPress };
 }
 export {
   useLayer

package/bin/templates/chat/app/api/chat/route.ts

@@ -23,6 +23,9 @@ const handler = createChatHandler({
   models: CHAT_MODELS,
   defaultModel: DEFAULT_CHAT_MODEL,
   // tools: [], // Deterministic lookups the model may call; a tool can answer with a card.
+  // A reply can end in a question with answers to pick, drawn as a card the
+  // visitor taps. Asking ends the exchange; the answer arrives as the next message.
+  askUser: true,
   guardrails,
 });
 

package/chat/AssistantTurn.d.ts

@@ -1,5 +1,22 @@
+import { CodeBlockProps } from '../components/CodeBlock/CodeBlock';
+import { PromptSuggestionsProps } from '../components/PromptSuggestions/PromptSuggestions';
+import { QuestionCardLabels } from '../components/QuestionCard/QuestionCard';
 import { ChatTurn, LiveResponse } from './types';
-export declare function AssistantTurn({ turn, live }: {
+/** The words an assistant turn's parts write, set from ChatWidget's label props. Every key left out keeps the part's English. */
+export interface AssistantTurnLabels {
+    /** The fenced-code CodeBlocks in a reply; `codeLabel` is given the fence's language. */
+    codeBlock?: Pick<CodeBlockProps, 'copyLabel' | 'copyText' | 'copiedLabel'> & {
+        codeLabel?: (language: string | undefined) => string;
+    };
+    /** The reasoning disclosure's summary once thinking is over, given the seconds it took when known. */
+    reasoning?: (durationSeconds: number | undefined) => string;
+    /** The question card a reply ends in. */
+    questionCard?: Partial<QuestionCardLabels>;
+    /** The follow-up row's hidden "(chosen)" text. */
+    promptSuggestions?: Pick<PromptSuggestionsProps, 'chosenLabel'>;
+}
+export declare function AssistantTurn({ turn, live, labels, }: {
     turn?: ChatTurn;
     live?: LiveResponse;
+    labels?: AssistantTurnLabels;
 }): import("react").JSX.Element;

package/chat/AssistantTurn.js

@@ -1,5 +1,6 @@
 "use client";
 import { jsx, jsxs, Fragment } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
 import ReactMarkdown from "react-markdown";
 import remarkGfm from "remark-gfm";
 import { AgentStatus } from "../components/AgentStatus/AgentStatus.js";
@@ -12,6 +13,8 @@ import { DOCK_QUERY } from "./queries.js";
 import { FollowupSuggestions } from "./FollowupSuggestions.js";
 import { ResponseActions } from "./ResponseActions.js";
 import { TurnCard } from "./TurnContent.js";
+import { TurnQuestion } from "./TurnQuestion.js";
+const CodeBlockLabelsContext = createContext(void 0);
 function MarkdownLink({ href, children }) {
   const { view, setOpen, renderLink, isInternalHref } = useChatWidget();
   if (!href || !isInternalHref(href)) return /* @__PURE__ */ jsx(Fragment, { children });
@@ -25,26 +28,39 @@ function MarkdownLink({ href, children }) {
 }
 const hastText = (node) => node.type === "text" ? node.value ?? "" : (node.children ?? []).map(hastText).join("");
 function MarkdownPre({ node, children, ...props }) {
+  const { codeLabel, ...labels } = useContext(CodeBlockLabelsContext) ?? {};
   const code = node?.children?.find(
     (child) => child.type === "element" && child.tagName === "code"
   );
   if (!code) return /* @__PURE__ */ jsx("pre", { ...props, children });
   const classes = code.properties?.className;
   const language = (Array.isArray(classes) ? classes : []).map(String).find((name) => name.startsWith("language-"))?.slice("language-".length);
-  return /* @__PURE__ */ jsx(CodeBlock, { code: hastText(code).replace(/\n$/, ""), language });
+  return /* @__PURE__ */ jsx(
+    CodeBlock,
+    {
+      ...labels,
+      codeLabel: codeLabel?.(language),
+      code: hastText(code).replace(/\n$/, ""),
+      language
+    }
+  );
 }
 const markdownComponents = {
   a: MarkdownLink,
   pre: MarkdownPre,
   table: ({ children, ...props }) => /* @__PURE__ */ jsx("table", { tabIndex: 0, ...props, children })
 };
-function AssistantTurn({ turn, live }) {
+function AssistantTurn({
+  turn,
+  live,
+  labels
+}) {
   const thinking = live?.phase === "thinking";
   const tracePoints = live ? live.tracePoints : turn?.tracePoints ?? [];
   const durationSeconds = live ? live.durationSeconds : turn?.durationSeconds;
   const text = live ? live.text : turn?.text ?? "";
   const { turns, live: liveTurn, freshFollowupsId } = useChatWidget();
-  const followupsPending = !!turn && turn.text !== "" && !!turn.exchangeId && !turn.followups && !liveTurn && turns[turns.length - 1]?.id === turn.id;
+  const followupsPending = !!turn && turn.text !== "" && !!turn.exchangeId && !turn.followups && !turn.question && !liveTurn && turns[turns.length - 1]?.id === turn.id;
   return /* @__PURE__ */ jsx(
     ChatMessage,
     {
@@ -56,7 +72,9 @@ function AssistantTurn({ turn, live }) {
         {
           turnId: turn.id,
           suggestions: turn.followups,
-          entrance: turn.id === freshFollowupsId
+          chosen: turn.followupChosen,
+          entrance: turn.id === freshFollowupsId,
+          chosenLabel: labels?.promptSuggestions?.chosenLabel
         }
       ) : followupsPending && turn ? /* @__PURE__ */ jsx(FollowupSuggestions, { turnId: turn.id, suggestions: [], pending: true }) : void 0,
       children: /* @__PURE__ */ jsxs("div", { className: "ds-chat-widget__response", children: [
@@ -66,13 +84,15 @@ function AssistantTurn({ turn, live }) {
             streaming: thinking,
             summaryOnly: tracePoints.length === 0,
             duration: durationSeconds,
+            label: labels?.reasoning && !thinking ? labels.reasoning(durationSeconds) : void 0,
             summary: thinking && live ? /* @__PURE__ */ jsx(AgentStatus, { state: "working", label: live.statusLabel }) : void 0,
             children: tracePoints.length > 0 && /* @__PURE__ */ jsx("ul", { children: tracePoints.map((point, index) => /* @__PURE__ */ jsx("li", { children: point }, `${index}-${point.slice(0, 24)}`)) })
           }
         ),
         turn?.content,
         turn?.card && /* @__PURE__ */ jsx(TurnCard, { card: turn.card }),
-        text !== "" && /* @__PURE__ */ jsx(Prose, { children: /* @__PURE__ */ jsx(ReactMarkdown, { remarkPlugins: [remarkGfm], components: markdownComponents, children: text }) })
+        text !== "" && /* @__PURE__ */ jsx(CodeBlockLabelsContext.Provider, { value: labels?.codeBlock, children: /* @__PURE__ */ jsx(Prose, { children: /* @__PURE__ */ jsx(ReactMarkdown, { remarkPlugins: [remarkGfm], components: markdownComponents, children: text }) }) }),
+        turn?.question && /* @__PURE__ */ jsx(TurnQuestion, { turn, labels: labels?.questionCard })
       ] })
     }
   );

package/chat/ChatAgentPane.d.ts

@@ -1,17 +1,35 @@
-import { AgentRailProfile, AgentRailTab } from '../components/AgentRail/AgentRail';
+import { AgentRailProfile, AgentRailProps, AgentRailTab } from '../components/AgentRail/AgentRail';
 export interface ChatAgentPaneProps {
     /** The agent this pane belongs to: the portrait block at the top. */
     profile: AgentRailProfile;
     /** The panes, in display order: activity, approvals, automations, personalisation, or whatever the agent has. */
     tabs: AgentRailTab[];
-    /** The tab on stage, when the host owns the state; otherwise the pane keeps its own. */
-    activeTab?: string;
+    /** The tab on stage, when the host owns the state; otherwise the pane keeps its own, seeded from `defaultValue`. */
+    value?: string;
+    /** The tab on stage first when the pane keeps its own state. Defaults to the first tab. */
+    defaultValue?: string;
     /** Fires with the chosen tab's id. */
+    onValueChange?: (id: string) => void;
+    /**
+     * Legacy name for `value`.
+     *
+     * @deprecated Use `value` instead.
+     */
+    activeTab?: string;
+    /**
+     * Legacy change callback; fires alongside `onValueChange`.
+     *
+     * @deprecated Use `onValueChange` instead.
+     */
     onTabChange?: (id: string) => void;
     /** The widget seated the pane as a bottom sheet, where it fills the width instead of holding its own column. */
     overlay: boolean;
     /** Fires from the pane's own close button, a cross in its top trailing corner. Omit for a pane with no close of its own. */
     onClose?: () => void;
+    /** Accessible name of the pane's own close button. Defaults to "Close the agent panel". */
+    closeLabel?: string;
+    /** The words the AgentRail writes, merged over its English defaults: the tab strip's name ("Agent views"). */
+    agentRailLabels?: Pick<AgentRailProps, 'tabsLabel'>;
 }
 /**
  * The built-in agent pane: an AgentRail the widget seats on the
@@ -21,4 +39,4 @@ export interface ChatAgentPaneProps {
  * pane carries a close of its own in its top corner, where a panel's way
  * out is looked for.
  */
-export declare function ChatAgentPane({ profile, tabs, activeTab, onTabChange, overlay, onClose }: ChatAgentPaneProps): import("react").JSX.Element;
+export declare function ChatAgentPane({ profile, tabs, value, defaultValue, onValueChange, activeTab, onTabChange, overlay, onClose, closeLabel, agentRailLabels, }: ChatAgentPaneProps): import("react").JSX.Element;

package/chat/ChatAgentPane.js

@@ -3,21 +3,35 @@ import { jsx } from "react/jsx-runtime";
 import { useState } from "react";
 import { AgentRail } from "../components/AgentRail/AgentRail.js";
 import "./ChatAgentPane.css";
-function ChatAgentPane({ profile, tabs, activeTab, onTabChange, overlay, onClose }) {
-  const [ownTab, setOwnTab] = useState(tabs[0]?.id ?? "");
-  const current = activeTab ?? ownTab;
+function ChatAgentPane({
+  profile,
+  tabs,
+  value,
+  defaultValue,
+  onValueChange,
+  activeTab,
+  onTabChange,
+  overlay,
+  onClose,
+  closeLabel = "Close the agent panel",
+  agentRailLabels
+}) {
+  const [ownTab, setOwnTab] = useState(defaultValue ?? tabs[0]?.id ?? "");
+  const current = value ?? activeTab ?? ownTab;
   return /* @__PURE__ */ jsx(
     AgentRail,
     {
+      ...agentRailLabels,
       className: overlay ? "ds-chat-agent-pane--sheet" : void 0,
       profile,
       tabs,
-      activeTab: current,
+      value: current,
       onCollapse: onClose,
       collapseVariant: "close",
-      collapseLabel: "Close the agent panel",
-      onTabChange: (id) => {
+      collapseLabel: closeLabel,
+      onValueChange: (id) => {
         setOwnTab(id);
+        onValueChange?.(id);
         onTabChange?.(id);
       }
     }

package/chat/ChatArtifactPane.d.ts

@@ -1,3 +1,4 @@
+import { ArtifactPanelProps } from '../components/ArtifactPanel/ArtifactPanel';
 import { ChatArtifact } from './types';
 export interface ChatArtifactPaneProps {
     /** The artifact on stage, or null for the empty state: the panel opened before the conversation has made anything. */
@@ -8,6 +9,20 @@ export interface ChatArtifactPaneProps {
     onExpandedChange?: (expanded: boolean) => void;
     /** Fires from the pane's close button; omit where another control closes the seat. */
     onClose?: () => void;
+    /** The panel's title while nothing is on stage. Defaults to "Artifacts". */
+    emptyPanelTitle?: string;
+    /** The empty state's heading. Defaults to "Nothing here yet". */
+    emptyTitle?: string;
+    /** The empty state's description. Defaults to "What the chat makes for you, like a dashboard or a page, opens in this panel." */
+    emptyDescription?: string;
+    /**
+     * The words the ArtifactPanel writes, merged over its English defaults:
+     * the view switch's segments and name ("Preview", "Code", "Artifact
+     * view"), the expand toggle and close button's names ("Expand the
+     * artifact", "Collapse the artifact", "Close the artifact"), and the code
+     * view's copy button and region (`codeBlockLabels`).
+     */
+    artifactPanelLabels?: Pick<ArtifactPanelProps, 'previewLabel' | 'codeLabel' | 'viewLabel' | 'expandLabel' | 'collapseLabel' | 'closeLabel' | 'codeBlockLabels'>;
 }
 /**
  * The built-in artifact pane: an ArtifactPanel drawn from a `ChatArtifact`.
@@ -15,4 +30,4 @@ export interface ChatArtifactPaneProps {
  * otherwise the artifact's document, URL or source decides the preview. The
  * widget owns the seat (beside the conversation, or a sheet over it).
  */
-export declare function ChatArtifactPane({ artifact, expanded, onExpandedChange, onClose }: ChatArtifactPaneProps): import("react").JSX.Element;
+export declare function ChatArtifactPane({ artifact, expanded, onExpandedChange, onClose, emptyPanelTitle, emptyTitle, emptyDescription, artifactPanelLabels, }: ChatArtifactPaneProps): import("react").JSX.Element;

package/chat/ChatArtifactPane.js

@@ -4,18 +4,19 @@ import { ArtifactPanel } from "../components/ArtifactPanel/ArtifactPanel.js";
 import { EmptyState } from "../components/EmptyState/EmptyState.js";
 import { useChatWidget } from "./context.js";
 const FRAMEABLE_URL = /^(?:https?:\/\/|\/(?!\/))/i;
-function ChatArtifactPane({ artifact, expanded, onExpandedChange, onClose }) {
+function ChatArtifactPane({
+  artifact,
+  expanded,
+  onExpandedChange,
+  onClose,
+  emptyPanelTitle = "Artifacts",
+  emptyTitle = "Nothing here yet",
+  emptyDescription = "What the chat makes for you, like a dashboard or a page, opens in this panel.",
+  artifactPanelLabels
+}) {
   const { artifactRenderers } = useChatWidget();
   if (!artifact) {
-    return /* @__PURE__ */ jsx(ArtifactPanel, { title: "Artifacts", icon: "space_dashboard", onClose, children: /* @__PURE__ */ jsx("div", { className: "ds-chat-widget__artifact-empty", children: /* @__PURE__ */ jsx(
-      EmptyState,
-      {
-        size: "compact",
-        icon: "draft",
-        title: "Nothing here yet",
-        description: "What the chat makes for you, like a dashboard or a page, opens in this panel."
-      }
-    ) }) });
+    return /* @__PURE__ */ jsx(ArtifactPanel, { ...artifactPanelLabels, title: emptyPanelTitle, icon: "space_dashboard", onClose, children: /* @__PURE__ */ jsx("div", { className: "ds-chat-widget__artifact-empty", children: /* @__PURE__ */ jsx(EmptyState, { size: "compact", icon: "draft", title: emptyTitle, description: emptyDescription }) }) });
   }
   const custom = Object.hasOwn(artifactRenderers, artifact.kind);
   const render = artifactRenderers[artifact.kind];
@@ -23,6 +24,7 @@ function ChatArtifactPane({ artifact, expanded, onExpandedChange, onClose }) {
   return /* @__PURE__ */ jsx(
     ArtifactPanel,
     {
+      ...artifactPanelLabels,
       title: artifact.title,
       meta: artifact.meta,
       icon: artifact.icon,

package/chat/ChatLauncher.d.ts

@@ -1,5 +1,5 @@
 import { ReactNode } from 'react';
-import { AiButtonSummary } from '../components/AiButton/AiButton';
+import { AiButtonProps, AiButtonSummary } from '../components/AiButton/AiButton';
 import { ChatWidgetProps } from './ChatWidget';
 /** The id the panel carries, for a host control's `aria-controls`. */
 export declare const CHAT_PANEL_ID = "ds-chat-panel";
@@ -11,8 +11,10 @@ export interface ChatLauncherProps {
     /**
      * A TLDR panel the button summons on hover: a pre-written summary and
      * prompt chips. A tapped chip opens the chat and sends the chip's
-     * `prompt`. Hover-capable devices only: the launcher never renders it on
-     * touch, and never in server HTML.
+     * `prompt`. The launcher hands it to the closed button's AiButton, which
+     * opens the panel on pointer hover; it does no device or hydration gating
+     * of its own, so a host that wants the panel on hover-capable devices only,
+     * or kept out of server HTML, passes `summary` only there.
      */
     summary?: AiButtonSummary & {
         chips?: {
@@ -21,7 +23,10 @@ export interface ChatLauncherProps {
             prompt: string;
         }[];
     };
-    /** Render nothing at all: for routes that carry no chrome. */
+    /**
+     * Render nothing at all: for routes that carry no chrome.
+     * Note: not the native `hidden` attribute, which keeps an element mounted and only hides it; the launcher unmounts its button and panel, and spreads no native attributes.
+     */
     hidden?: boolean;
     /** The panel's DOM id, for a host control's `aria-controls`. */
     panelId?: string;
@@ -33,6 +38,8 @@ export interface ChatLauncherProps {
     hostAttribute?: string | false;
     /** Accessible name for the panel. */
     panelLabel?: string;
+    /** The words of the floating button's summary panel, over AiButton's English defaults: the panel's name, given the summary's title ("Summary: <title>"), its dismiss button ("Dismiss summary") and its chips' group ("Suggested prompts"). */
+    aiButtonLabels?: Pick<AiButtonProps, 'summaryRegionLabel' | 'dismissLabel' | 'suggestionsLabel'>;
     /** Everything the widget takes. The launcher sets the responsive ones itself. */
     widget?: Omit<ChatWidgetProps, 'fullscreenEnabled' | 'placementEnabled' | 'compact' | 'phone'>;
     /** Rendered inside the panel after the widget: for a host's extra chrome. */
@@ -61,4 +68,4 @@ export interface ChatLauncherProps {
  * touch the host's body). The panel's geometry reads `--ds-chat-width`,
  * `--ds-chat-inset` and `--ds-chat-float-height`, defaulted on `:root`.
  */
-export declare function ChatLauncher({ label, icon, summary, hidden, panelId, hostAttribute, panelLabel, widget, children, }: ChatLauncherProps): import("react").JSX.Element | null;
+export declare function ChatLauncher({ label, icon, summary, hidden, panelId, hostAttribute, panelLabel, aiButtonLabels, widget, children, }: ChatLauncherProps): import("react").JSX.Element | null;

package/chat/ChatLauncher.js

@@ -42,6 +42,7 @@ function ChatLauncher({
   panelId = CHAT_PANEL_ID,
   hostAttribute = "data-chat",
   panelLabel = "Chat",
+  aiButtonLabels,
   widget,
   children
 }) {
@@ -223,6 +224,7 @@ function ChatLauncher({
     return /* @__PURE__ */ jsx("div", { className: "ds-chat-launcher__fab", children: /* @__PURE__ */ jsx(
       AiButton,
       {
+        ...aiButtonLabels,
         label,
         icon,
         "aria-expanded": false,
@@ -244,7 +246,7 @@ function ChatLauncher({
   }
   const handleKeyDown = (event) => {
     if (event.key === "Escape") {
-      setOpen(false);
+      if (!event.defaultPrevented) setOpen(false);
       return;
     }
     if (modal && event.key === "Tab" && panelRef.current) {

package/chat/ChatProvider.d.ts

@@ -18,11 +18,12 @@ export interface ChatProviderProps {
     defaultPlacement?: ChatPlacement;
     /**
      * Where follow-up questions come from after an answer commits: a source
-     * function, an endpoint for the built-in fetcher, or `false` for none.
-     * Defaults to the fetcher against `/api/chat/followups`.
+     * function, an endpoint for the built-in fetcher, or `false` for none:
+     * with `false` no chips show under an answer at all, not even the written
+     * `fallbackFollowups`. Defaults to the fetcher against `/api/chat/followups`.
      */
     followups?: FollowupsSource | string | false;
-    /** The written questions offered when the source returns none. */
+    /** The written questions offered when the source returns none or fails. Unused when `followups` is `false`. */
     fallbackFollowups?: readonly string[];
     /**
      * Where a thumbs verdict goes: a sink function, an endpoint for the
@@ -41,7 +42,7 @@ export interface ChatProviderProps {
     isInternalHref?: (href: string) => boolean;
     /** Seeds the thread lifecycle behind the `threads` and `tabs` slots. */
     threads?: ThreadsOptions;
-    /** Replacement copy for the hook's placeholder replies. */
+    /** Replacement copy for the words the hook writes itself, merged over the English defaults: the status line of a reply that has not started ("Thinking") and the placeholder replies for an empty, stopped or failed turn. */
     placeholders?: Partial<ChatPlaceholderCopy>;
     children: ReactNode;
 }