@elabs-ai/components-ui 4.1.0 → 5.0.0

package/src/components/command-chip/command-chip.tsx

@@ -0,0 +1,168 @@
+"use client";
+
+import { forwardRef, useRef, useState, type HTMLAttributes } from "react";
+import { Check, ChevronDown, Copy } from "lucide-react";
+import { cn } from "../../lib/cn";
+import { useControllableState } from "../../lib/use-controllable-state";
+import { useCopyToClipboard } from "../../lib/use-copy-to-clipboard";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuLabel,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuTrigger,
+} from "../dropdown-menu";
+
+/** One install target: the host a visitor runs the command in, and the exact command. */
+export interface CommandChipHost {
+  /** Stable id, reported to `onValueChange`. */
+  id: string;
+  /** Host name shown in the menu and on the trigger. */
+  label: string;
+  /** The exact text shown in the chip and written to the clipboard. */
+  command: string;
+}
+
+/** Every string the chip renders — pass your own to localize it. */
+export interface CommandChipLabels {
+  /** Accessible name of the copy button. */
+  copy: string;
+  /** Announced (and shown to sighted users as the check icon) after a successful copy. */
+  copied: string;
+  /** Announced when the clipboard is unavailable and the command is selected instead. */
+  selectFallback: string;
+  /** Accessible name prefix of the host trigger (the current host follows it). */
+  chooseHost: string;
+  /** Heading of the host menu. */
+  menuLabel: string;
+}
+
+export const DEFAULT_COMMAND_CHIP_LABELS: CommandChipLabels = {
+  copy: "Copy command",
+  copied: "Copied",
+  selectFallback: "Command selected — press Ctrl+C or ⌘C to copy",
+  chooseHost: "Install for",
+  menuLabel: "Install for",
+};
+
+export interface CommandChipProps extends Omit<HTMLAttributes<HTMLDivElement>, "onCopy"> {
+  /** The hosts to choose between; the first is the default selection. */
+  hosts: CommandChipHost[];
+  /** Selected host id (controlled). */
+  value?: string;
+  /** Initially selected host id (uncontrolled). Default: the first host. */
+  defaultValue?: string;
+  /** Fires when the visitor picks another host. */
+  onValueChange?: (id: string) => void;
+  /** Fires after a copy attempt with the command and whether the clipboard accepted it. */
+  onCopyCommand?: (command: string, copied: boolean) => void;
+  /** Override any rendered string. */
+  labels?: Partial<CommandChipLabels>;
+}
+
+/**
+ * A one-line install command in a monospace chip: pick the host (Claude Code, Cursor, …) from a
+ * menu, copy the exact command. When the page has no clipboard access (insecure origin, denied
+ * permission) the command text is selected instead so the visitor can copy it by hand; either
+ * outcome is announced through an always-mounted live region.
+ */
+export const CommandChip = forwardRef<HTMLDivElement, CommandChipProps>(function CommandChip(
+  {
+    hosts,
+    value,
+    defaultValue,
+    onValueChange,
+    onCopyCommand,
+    labels: labelsProp,
+    className,
+    ...props
+  },
+  ref,
+) {
+  const labels = { ...DEFAULT_COMMAND_CHIP_LABELS, ...labelsProp };
+  const [selectedId, setSelectedId] = useControllableState(
+    value,
+    defaultValue ?? hosts[0]?.id ?? "",
+    onValueChange,
+  );
+  const host = hosts.find((h) => h.id === selectedId) ?? hosts[0];
+  const { copied, copy } = useCopyToClipboard();
+  const commandRef = useRef<HTMLElement>(null);
+  const [selectedManually, setSelectedManually] = useState(false);
+
+  if (!host) return null;
+
+  const onCopy = () => {
+    void copy(host.command).then((ok) => {
+      setSelectedManually(!ok);
+      if (!ok && commandRef.current && typeof window !== "undefined") {
+        // No clipboard here: select the command so a manual copy takes one keystroke.
+        const selection = window.getSelection();
+        selection?.selectAllChildren(commandRef.current);
+      }
+      onCopyCommand?.(host.command, ok);
+    });
+  };
+
+  return (
+    <div
+      ref={ref}
+      data-slot="command-chip"
+      data-copied={copied ? "" : undefined}
+      className={cn(
+        "inline-flex max-w-full min-w-0 items-center gap-1 rounded-md border border-input bg-card p-1 shadow-xs",
+        className,
+      )}
+      {...props}
+    >
+      {hosts.length > 1 ? (
+        <DropdownMenu>
+          <DropdownMenuTrigger
+            data-slot="command-chip-host"
+            aria-label={`${labels.chooseHost}: ${host.label}`}
+            className="inline-flex shrink-0 items-center gap-1 rounded-sm px-2 py-1 text-meta text-muted-foreground hover:bg-accent hover:text-accent-foreground focus-ring"
+          >
+            {host.label}
+            <ChevronDown aria-hidden="true" className="size-3.5" />
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="start">
+            <DropdownMenuLabel>{labels.menuLabel}</DropdownMenuLabel>
+            <DropdownMenuRadioGroup value={host.id} onValueChange={setSelectedId}>
+              {hosts.map((h) => (
+                <DropdownMenuRadioItem key={h.id} value={h.id}>
+                  {h.label}
+                </DropdownMenuRadioItem>
+              ))}
+            </DropdownMenuRadioGroup>
+          </DropdownMenuContent>
+        </DropdownMenu>
+      ) : null}
+      <code
+        ref={commandRef}
+        data-slot="command-chip-command"
+        className="min-w-0 flex-1 truncate px-2 font-mono text-code text-foreground"
+        title={host.command}
+      >
+        {host.command}
+      </code>
+      <button
+        type="button"
+        data-slot="command-chip-copy"
+        aria-label={labels.copy}
+        onClick={onCopy}
+        className="inline-flex size-7 shrink-0 items-center justify-center rounded-sm text-muted-foreground hover:bg-accent hover:text-accent-foreground focus-ring"
+      >
+        {copied ? (
+          <Check aria-hidden="true" className="size-4" />
+        ) : (
+          <Copy aria-hidden="true" className="size-4" />
+        )}
+      </button>
+      {/* Always mounted so the announcement is not missed (ARIA22); only its text changes. */}
+      <span role="status" aria-live="polite" className="sr-only" data-slot="command-chip-status">
+        {copied ? labels.copied : selectedManually ? labels.selectFallback : ""}
+      </span>
+    </div>
+  );
+});

package/src/components/command-chip/index.ts

@@ -0,0 +1,7 @@
+export {
+  CommandChip,
+  DEFAULT_COMMAND_CHIP_LABELS,
+  type CommandChipHost,
+  type CommandChipLabels,
+  type CommandChipProps,
+} from "./command-chip";

package/src/components/command-trigger/command-trigger.tsx

@@ -49,7 +49,7 @@ export const CommandTrigger = forwardRef<HTMLButtonElement, CommandTriggerProps>
         aria-label={label}
         className={cn(
           "inline-flex h-8 items-center gap-2 rounded-md border border-input bg-background px-2 text-body text-muted-foreground",
-          "hover:bg-accent hover:text-accent-foreground focus-ring",
+          "hover:bg-accent hover:text-accent-foreground focus-ring focus-visible:border-input-focus",
           "sm:w-56 sm:justify-between sm:ps-2 sm:pe-1.5",
           className,
         )}

package/src/components/confirm-dialog/confirm-dialog.stories.tsx

@@ -163,6 +163,7 @@ export const NeutralTone: Story = {
  * dark sweep and the workaround is retired.
  */
 export const DestructiveDark: Story = {
+  tags: ["!dev"],
   name: "Destructive — dark",
   decorators: [
     (Story) => (
@@ -176,6 +177,7 @@ export const DestructiveDark: Story = {
 };
 
 export const DestructiveHighDecoration: Story = {
+  tags: ["!dev"],
   name: "Destructive — high decoration",
   globals: { decoration: "10" },
   render: () => <DestructiveConfirm />,

package/src/components/context-menu/context-menu.stories.tsx

@@ -68,3 +68,29 @@ export const Default: Story = {
     await userEvent.keyboard("{Escape}");
   },
 };
+
+/**
+ * Locks WCAG 1.4.11 keyboard-focus contrast (#308): a menu item's
+ * `focus:bg-accent` fill alone is not a visible indicator (~1.17–1.40:1
+ * against `--popover`). Moving focus with the keyboard must additionally
+ * paint a compound ring (`focus-ring-inset`): a real `boxShadow` layer, or a
+ * non-zero, non-`none` `outline`.
+ */
+export const KeyboardFocusIndicator: Story = {
+  name: "Keyboard focus",
+  render: Default.render,
+  play: async ({ canvas, canvasElement, userEvent }) => {
+    const trigger = canvas.getByText("Right-click here");
+    await userEvent.pointer({ target: trigger, keys: "[MouseRight]" });
+    const body = within(canvasElement.ownerDocument.body);
+    await body.findByRole("menu");
+    await userEvent.keyboard("{ArrowDown}");
+    const focused = canvasElement.ownerDocument.activeElement as HTMLElement;
+    await expect(focused).toHaveAttribute("role", "menuitem");
+    const style = getComputedStyle(focused);
+    const hasRing = style.boxShadow !== "none";
+    const hasOutline = style.outlineStyle !== "none" && parseFloat(style.outlineWidth) > 0;
+    await expect(hasRing || hasOutline).toBe(true);
+    await userEvent.keyboard("{Escape}");
+  },
+};

package/src/components/context-menu/context-menu.tsx

@@ -21,8 +21,9 @@ export const ContextMenuSubTrigger = forwardRef<
   return (
     <ContextMenuPrimitive.SubTrigger
       ref={ref}
+      data-slot="context-menu-sub-trigger"
       className={cn(
-        "flex cursor-default select-none items-center rounded-sm px-2 py-1.5 text-sm outline-none transition-colors duration-fast focus:bg-accent data-[state=open]:bg-accent",
+        "flex cursor-default select-none items-center rounded-sm px-2 py-1.5 text-body outline-none transition-colors duration-fast focus:bg-accent focus:text-accent-foreground focus-ring-inset data-[state=open]:bg-accent",
         inset && "ps-8",
         className,
       )}
@@ -41,8 +42,9 @@ export const ContextMenuSubContent = forwardRef<
   return (
     <ContextMenuPrimitive.SubContent
       ref={ref}
+      data-slot="context-menu-sub-content"
       className={cn(
-        "z-50 min-w-[8rem] overflow-hidden rounded-md bg-popover p-1 text-popover-foreground shadow-ring-md data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 data-[state=closed]:zoom-out-95 data-[side=bottom]:slide-in-from-top-2 data-[side=top]:slide-in-from-bottom-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2",
+        "z-50 min-w-[8rem] overflow-hidden rounded-md bg-popover p-1 text-popover-foreground shadow-popover data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 data-[state=closed]:zoom-out-95 data-[side=bottom]:slide-in-from-top-2 data-[side=top]:slide-in-from-bottom-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2",
         className,
       )}
       {...props}
@@ -58,8 +60,9 @@ export const ContextMenuContent = forwardRef<
     <ContextMenuPrimitive.Portal>
       <ContextMenuPrimitive.Content
         ref={ref}
+        data-slot="context-menu-content"
         className={cn(
-          "z-50 min-w-[8rem] overflow-hidden rounded-md bg-popover p-1 text-popover-foreground shadow-ring-md data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 data-[state=closed]:zoom-out-95 data-[side=bottom]:slide-in-from-top-2 data-[side=top]:slide-in-from-bottom-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2",
+          "z-50 min-w-[12rem] overflow-hidden rounded-md bg-popover p-1 text-popover-foreground shadow-popover data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 data-[state=closed]:zoom-out-95 data-[side=bottom]:slide-in-from-top-2 data-[side=top]:slide-in-from-bottom-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2",
           className,
         )}
         {...props}
@@ -75,8 +78,9 @@ export const ContextMenuItem = forwardRef<
   return (
     <ContextMenuPrimitive.Item
       ref={ref}
+      data-slot="context-menu-item"
       className={cn(
-        "relative flex cursor-default select-none items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-none transition-colors duration-fast focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:size-4",
+        "relative flex cursor-default select-none items-center gap-2 rounded-sm px-2 py-1.5 text-body outline-none transition-colors duration-fast focus:bg-accent focus:text-accent-foreground focus-ring-inset data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:size-4",
         inset && "ps-8",
         className,
       )}
@@ -92,9 +96,10 @@ export const ContextMenuCheckboxItem = forwardRef<
   return (
     <ContextMenuPrimitive.CheckboxItem
       ref={ref}
+      data-slot="context-menu-checkbox-item"
       checked={checked}
       className={cn(
-        "relative flex cursor-default select-none items-center rounded-sm py-1.5 ps-8 pe-2 text-sm outline-none transition-colors duration-fast focus:bg-accent",
+        "relative flex cursor-default select-none items-center rounded-sm py-1.5 ps-8 pe-2 text-body outline-none transition-colors duration-fast focus:bg-accent focus:text-accent-foreground focus-ring-inset",
         className,
       )}
       {...props}
@@ -116,8 +121,9 @@ export const ContextMenuRadioItem = forwardRef<
   return (
     <ContextMenuPrimitive.RadioItem
       ref={ref}
+      data-slot="context-menu-radio-item"
       className={cn(
-        "relative flex cursor-default select-none items-center rounded-sm py-1.5 ps-8 pe-2 text-sm outline-none transition-colors duration-fast focus:bg-accent",
+        "relative flex cursor-default select-none items-center rounded-sm py-1.5 ps-8 pe-2 text-body outline-none transition-colors duration-fast focus:bg-accent focus:text-accent-foreground focus-ring-inset",
         className,
       )}
       {...props}
@@ -139,8 +145,9 @@ export const ContextMenuLabel = forwardRef<
   return (
     <ContextMenuPrimitive.Label
       ref={ref}
+      data-slot="context-menu-label"
       className={cn(
-        "px-2 py-1.5 text-xs font-semibold text-muted-foreground",
+        "px-2 py-1.5 text-meta font-semibold text-muted-foreground",
         inset && "ps-8",
         className,
       )}
@@ -156,6 +163,7 @@ export const ContextMenuSeparator = forwardRef<
   return (
     <ContextMenuPrimitive.Separator
       ref={ref}
+      data-slot="context-menu-separator"
       className={cn("-mx-1 my-1 h-px bg-border", className)}
       {...props}
     />
@@ -165,7 +173,8 @@ export const ContextMenuSeparator = forwardRef<
 export function ContextMenuShortcut({ className, ...props }: HTMLAttributes<HTMLSpanElement>) {
   return (
     <span
-      className={cn("ms-auto text-xs tracking-widest text-muted-foreground", className)}
+      data-slot="context-menu-shortcut"
+      className={cn("ms-auto text-meta tracking-widest text-muted-foreground", className)}
       {...props}
     />
   );

package/src/components/context-rail/context-rail.tsx

@@ -155,14 +155,16 @@ const COUNT_BADGE_BASE =
 // (measured before the strip gained its own padding). `CONTEXT_RAIL_HEADER`'s
 // `px-2` now buys that margin back, so this is belt and braces rather than the
 // only guard — keep it: a host restyling the rail through `className` can put
-// the item back on the edge. The vertical `-top-1` overhang is kept: nothing
-// clips it.
+// the item back on the edge. The vertical `-top-1` overhang is kept — but the
+// expanded row switcher is an `overflow-x-auto` scroller, which clips on BOTH
+// axes, so that row carries `py-1` to keep the overhang inside its own box
+// (measured: without it the count was cut in half at the top).
 const COUNT_BADGE_POSITION = "end-0 -top-1 h-4 min-w-4 px-0.5";
 
 // The rail's own header band. Two jobs, and both are geometry the rail cannot
 // leave to its children:
 //
-// 1. EXPANDED it is `h-14` — the same 56px an app shell's top bar carries
+// 1. EXPANDED it is `h-header` (56px by default) — the same height an app shell's top bar carries
 //    (`AppShell`, and both shipped shell blocks) — and it holds the section
 //    heading AND the switcher in ONE row. Before this, the switcher row (32px,
 //    flush at y=0) and a separately-bordered heading (53px) stacked to 85px, so
@@ -177,7 +179,7 @@ const COUNT_BADGE_POSITION = "end-0 -top-1 h-4 min-w-4 px-0.5";
 //    centres the FIRST icon in the same 56px band as the top bar's controls, so
 //    the two rails' first rows agree.
 const CONTEXT_RAIL_HEADER =
-  "flex h-14 shrink-0 items-center gap-2 border-b border-border-strong px-2 group-data-[collapsible=icon]:h-auto group-data-[collapsible=icon]:flex-col group-data-[collapsible=icon]:items-stretch group-data-[collapsible=icon]:border-b-0 group-data-[collapsible=icon]:px-2 group-data-[collapsible=icon]:pt-3 group-data-[collapsible=icon]:pb-2";
+  "flex h-header shrink-0 items-center gap-2 border-b border-border-strong px-2 group-data-[collapsible=icon]:h-auto group-data-[collapsible=icon]:flex-col group-data-[collapsible=icon]:items-stretch group-data-[collapsible=icon]:border-b-0 group-data-[collapsible=icon]:px-2 group-data-[collapsible=icon]:pt-3 group-data-[collapsible=icon]:pb-2";
 
 function ContextRailSwitcher({
   sections,
@@ -216,7 +218,7 @@ function ContextRailSwitcher({
         // narrow strip) it is the whole column again, with no cap and no
         // scroller.
         orientation === "row"
-          ? "w-auto max-w-1/2 shrink-0 flex-row overflow-x-auto [&>li]:shrink-0 group-data-[collapsible=icon]:w-full group-data-[collapsible=icon]:max-w-none group-data-[collapsible=icon]:flex-col group-data-[collapsible=icon]:overflow-x-visible"
+          ? "w-auto max-w-1/2 shrink-0 flex-row overflow-x-auto py-1 [&>li]:shrink-0 group-data-[collapsible=icon]:w-full group-data-[collapsible=icon]:max-w-none group-data-[collapsible=icon]:flex-col group-data-[collapsible=icon]:overflow-x-visible"
           : "flex-col"
       }
     >
@@ -241,6 +243,11 @@ function ContextRailSwitcher({
               aria-current={isActive ? "true" : undefined}
               disabled={section.disabled}
               onClick={() => handleClick(section)}
+              // No leading accent bar: in a nav LIST it marks the row, but on a
+              // 32px icon button in this switcher it read as a stray vertical
+              // line beside the glyph. The accent fill is the active cue here
+              // (a shape, so it survives greyscale), and `aria-current` names it.
+              className="data-[active=true]:before:hidden"
             >
               <span
                 aria-hidden="true"
@@ -491,10 +498,10 @@ const ContextRailNarrow = forwardRef<HTMLDivElement, ContextRailNarrowProps>(
                     above; this is the visible heading the body sits under. */}
                 <h2
                   data-slot="context-rail-heading"
-                  // `h-14`, matching the wide branch's header band and the app
+                  // `h-header`, matching the wide branch's header band and the app
                   // shell's top bar — the sheet is the same rail at a narrower
                   // width, so its header keeps the same height.
-                  className="flex h-14 shrink-0 items-center truncate border-b border-border-strong px-4 text-title"
+                  className="flex h-header shrink-0 items-center truncate border-b border-border-strong px-4 text-title"
                 >
                   {activeSection.label}
                 </h2>
@@ -658,7 +665,18 @@ export const ContextRail = forwardRef<HTMLDivElement, ContextRailProps>(function
       ) : (
         // `variant` is hardcoded, not a public prop (#382) — see the doc
         // comment on `ContextRailProps` above.
-        <Sidebar side="right" collapsible="icon" variant="sidebar">
+        // No edge line (the variant draws it under the same group selector, so the
+        // override uses that selector too). The rail's `bg-sidebar` chrome fill is
+        // already the boundary against the canvas (`surface-elevation` keeps
+        // the two apart in every theme), and beside an inset content card the
+        // card's own elevation is — so the line only ever drew a stray hairline.
+        <Sidebar
+          side="right"
+          collapsible="icon"
+          variant="sidebar"
+          // eslint-disable-next-line conventions/logical-props -- must cancel Sidebar's own physical `group-data-[side=right]:border-l` under the same selector; a logical override loses the cascade
+          className="group-data-[side=right]:border-l-0"
+        >
           <ContextRailWide
             ref={ref}
             sections={sections}

package/src/components/copyable-value/copyable-value.stories.tsx

@@ -1,11 +1,21 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
 import { expect, userEvent, within } from "storybook/test";
+import { Toaster } from "../sonner";
 import { CopyableValue } from "./copyable-value";
 
 const meta = {
   title: "Display/CopyableValue",
   component: CopyableValue,
   tags: ["autodocs"],
+  // The copy toast needs a host; apps mount one `<Toaster />` at their root.
+  decorators: [
+    (Story) => (
+      <>
+        <Story />
+        <Toaster />
+      </>
+    ),
+  ],
   parameters: {
     docs: {
       description: {

package/src/components/copyable-value/copyable-value.test.tsx

@@ -11,7 +11,10 @@
 import { describe, expect, it, vi } from "vitest";
 import { render, screen, fireEvent, waitFor } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
-import { CopyableValue } from "./copyable-value";
+import { toast } from "../sonner";
+import { CopyableValue, COPYABLE_VALUE_TOAST_MS } from "./copyable-value";
+
+vi.mock("../sonner", () => ({ toast: vi.fn() }));
 
 /** Install a clipboard stub for one test; returns the writeText spy. */
 function stubClipboard(impl: () => Promise<void> = () => Promise.resolve()) {
@@ -38,6 +41,30 @@ describe("CopyableValue", () => {
     });
   });
 
+  it("shows a one-second toast once the copy succeeds", async () => {
+    vi.mocked(toast).mockClear();
+    stubClipboard();
+    render(<CopyableValue value="42">42</CopyableValue>);
+
+    fireEvent.click(screen.getByRole("button"));
+    await waitFor(() => {
+      expect(toast).toHaveBeenCalledWith("Copied", { duration: COPYABLE_VALUE_TOAST_MS });
+    });
+    expect(COPYABLE_VALUE_TOAST_MS).toBe(1000);
+  });
+
+  it("shows no toast when the copy fails", async () => {
+    vi.mocked(toast).mockClear();
+    stubClipboard(() => Promise.reject(new Error("denied")));
+    render(<CopyableValue value="42">42</CopyableValue>);
+
+    fireEvent.click(screen.getByRole("button"));
+    await waitFor(() => {
+      expect(screen.getByRole("status")).toHaveTextContent("");
+    });
+    expect(toast).not.toHaveBeenCalled();
+  });
+
   it("falls back to the exact value as its own display", () => {
     render(<CopyableValue value="1234" />);
     expect(screen.getByRole("button")).toHaveTextContent("1234");

package/src/components/copyable-value/copyable-value.tsx

@@ -19,6 +19,10 @@ import { forwardRef, type ButtonHTMLAttributes, type ReactNode } from "react";
 import { cn } from "../../lib/cn";
 import { useCopyToClipboard } from "../../lib/use-copy-to-clipboard";
 import { useLocale } from "../locale-provider";
+import { toast } from "../sonner";
+
+/** ms the copy-confirmation toast stays on screen. */
+export const COPYABLE_VALUE_TOAST_MS = 1000;
 
 export interface CopyableValueProps extends Omit<
   ButtonHTMLAttributes<HTMLButtonElement>,
@@ -79,7 +83,14 @@ export const CopyableValue = forwardRef<HTMLButtonElement, CopyableValueProps>(
           onClick={(event) => {
             onClick?.(event);
             if (!event.defaultPrevented) {
-              void copy(value);
+              // The toast is the visible confirmation; it needs an app-mounted
+              // `<Toaster />` and is a silent no-op without one, which is why
+              // the live region below stays as the always-present fallback.
+              void copy(value).then((ok) => {
+                if (ok) {
+                  toast(t("ui.copyableValue.copied"), { duration: COPYABLE_VALUE_TOAST_MS });
+                }
+              });
             }
           }}
         >

package/src/components/date-picker/date-picker.stories.tsx

@@ -5,6 +5,15 @@ const meta = {
   title: "Forms/DatePicker",
   component: DatePicker,
   tags: ["autodocs"],
+  // The trigger fills its container by default (no hard-fixed width) — cap
+  // the docs canvas to a realistic form-field width.
+  decorators: [
+    (Story) => (
+      <div className="w-full max-w-xs">
+        <Story />
+      </div>
+    ),
+  ],
   argTypes: {
     value: {
       description: "Controlled selected date.",

package/src/components/date-picker/date-picker.test.tsx

@@ -0,0 +1,52 @@
+import { createRef } from "react";
+import { describe, expect, it, vi } from "vitest";
+import { render, screen, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { DatePicker } from "./date-picker";
+import { LocaleProvider } from "../locale-provider";
+
+describe("DatePicker", () => {
+  it("forwards the ref to the trigger button", () => {
+    const ref = createRef<HTMLButtonElement>();
+    render(<DatePicker ref={ref} />);
+    expect(ref.current).toBeInstanceOf(HTMLButtonElement);
+    expect(ref.current).toBe(screen.getByRole("button"));
+  });
+
+  it("does not hard-fix the trigger width — fills its container by default", () => {
+    render(<DatePicker />);
+    expect(screen.getByRole("button").className).not.toMatch(/\bw-56\b/);
+  });
+
+  // #reviewed 1.7 — same `value ?? internal` / ternary-setter bug as Combobox:
+  // an uncontrolled DatePicker with an onValueChange listener never updated
+  // its own displayed date.
+  it("updates its own displayed date when uncontrolled even with an onValueChange listener", async () => {
+    const onValueChange = vi.fn();
+    const user = userEvent.setup();
+    render(<DatePicker onValueChange={onValueChange} placeholder="Pick a date" />);
+    const trigger = screen.getByRole("button", { name: /pick a date/i });
+    await user.click(trigger);
+    const grid = await screen.findByRole("grid");
+    const dayButtons = within(grid)
+      .getAllByRole("button")
+      .filter((b) => !/previous|next/i.test(b.getAttribute("aria-label") ?? ""));
+    const firstEnabled = dayButtons.find((b) => !(b as HTMLButtonElement).disabled)!;
+    await user.click(firstEnabled);
+    expect(onValueChange).toHaveBeenCalled();
+    expect(trigger).not.toHaveTextContent("Pick a date");
+  });
+
+  it("formats the displayed date using the active locale", () => {
+    const date = new Date(2024, 0, 15); // Jan 15, 2024
+    render(
+      <LocaleProvider locale="de-DE">
+        <DatePicker value={date} />
+      </LocaleProvider>,
+    );
+    // de-DE "medium" dateStyle renders like "15. Jan. 2024" — distinct from
+    // the en-US default ("Jan 15, 2024").
+    expect(screen.getByRole("button")).toHaveTextContent("2024");
+    expect(screen.getByRole("button").textContent).not.toMatch(/Jan 15, 2024/);
+  });
+});

package/src/components/date-picker/date-picker.tsx

@@ -1,8 +1,12 @@
-import { useState } from "react";
+"use client";
+
+import { forwardRef } from "react";
 import { Calendar as CalendarIcon } from "lucide-react";
 import { cn } from "../../lib/cn";
+import { useControllableState } from "../../lib/use-controllable-state";
 import { Button } from "../button";
 import { Calendar } from "../calendar";
+import { useLocale } from "../locale-provider";
 import { Popover, PopoverContent, PopoverTrigger } from "../popover";
 
 export interface DatePickerProps {
@@ -13,26 +17,22 @@ export interface DatePickerProps {
 }
 
 /** Single-date picker (Popover + Calendar). Controlled or uncontrolled. */
-export function DatePicker({
-  value,
-  onValueChange,
-  placeholder = "Pick a date",
-  className,
-}: DatePickerProps) {
-  const [internal, setInternal] = useState<Date | undefined>(undefined);
-  const date = value ?? internal;
-  const setDate = (d?: Date) => (onValueChange ? onValueChange(d) : setInternal(d));
-  const label = date
-    ? new Intl.DateTimeFormat(undefined, { dateStyle: "medium" }).format(date)
-    : placeholder;
+export const DatePicker = forwardRef<HTMLButtonElement, DatePickerProps>(function DatePicker(
+  { value, onValueChange, placeholder = "Pick a date", className },
+  ref,
+) {
+  const { formatDate } = useLocale();
+  const [date, setDate] = useControllableState<Date | undefined>(value, undefined, onValueChange);
+  const label = date ? formatDate(date, { dateStyle: "medium" }) : placeholder;
 
   return (
     <Popover>
       <PopoverTrigger asChild>
         <Button
+          ref={ref}
           variant="outline"
           className={cn(
-            "w-56 justify-start gap-2 text-start font-normal",
+            "w-full justify-start gap-2 text-start font-normal",
             !date && "text-muted-foreground",
             className,
           )}
@@ -46,4 +46,4 @@ export function DatePicker({
       </PopoverContent>
     </Popover>
   );
-}
+});

package/src/components/date-range-picker/date-range-picker.stories.tsx

@@ -12,6 +12,15 @@ const meta = {
   parameters: {
     layout: "centered",
   },
+  // The trigger fills its container by default (no hard-fixed width) — cap
+  // the docs canvas to a realistic form-field width.
+  decorators: [
+    (Story) => (
+      <div className="w-80">
+        <Story />
+      </div>
+    ),
+  ],
   argTypes: {
     value: {
       description: "Controlled date range `{ from, to }`.",