@elabs-ai/components-ui 4.1.0 → 5.0.0

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

@@ -6,9 +6,12 @@
  * select interaction and accessibility are covered by the Storybook stories
  * (run via `pnpm --filter @elabs-ai/components-docs test-storybook` or the MCP story tests).
  */
+import { useState } from "react";
 import { describe, expect, it } from "vitest";
 import { render, screen } from "@testing-library/react";
-import { DateRangePicker } from "./date-range-picker";
+import userEvent from "@testing-library/user-event";
+import { DateRangePicker, type DateRange } from "./date-range-picker";
+import { LocaleProvider } from "../locale-provider";
 
 describe("DateRangePicker", () => {
   it("renders the placeholder on the trigger when no range is set", () => {
@@ -59,4 +62,76 @@ describe("DateRangePicker", () => {
     const button = screen.getByRole("button");
     expect(button.className).toContain("my-custom-class");
   });
+
+  it("does not hard-fix the trigger width — fills its container by default", () => {
+    render(<DateRangePicker />);
+    expect(screen.getByRole("button").className).not.toMatch(/\bw-72\b/);
+  });
+
+  it("spreads extra props (e.g. data-testid) onto the trigger button", () => {
+    render(<DateRangePicker data-testid="range-trigger" />);
+    expect(screen.getByTestId("range-trigger")).toBeInTheDocument();
+  });
+
+  it("formats the range label using the active locale", () => {
+    const from = new Date(2024, 0, 5);
+    const to = new Date(2024, 0, 20);
+    render(
+      <LocaleProvider locale="de-DE">
+        <DateRangePicker value={{ from, to }} />
+      </LocaleProvider>,
+    );
+    // de-DE renders "5. Jan. 2024" style — distinct from the en-US default.
+    expect(screen.getByRole("button").textContent).not.toMatch(/Jan 5, 2024/);
+  });
+
+  // #reviewed 1.7 — clearing a controlled range to `undefined` must not fall
+  // through to a stale uncontrolled `internal` value: once controlled, the
+  // component must stay controlled for its whole lifetime.
+  it("collapses to a single month below the sm breakpoint (phone-width popover)", async () => {
+    const originalWidth = window.innerWidth;
+    Object.defineProperty(window, "innerWidth", {
+      writable: true,
+      configurable: true,
+      value: 375,
+    });
+    try {
+      const user = userEvent.setup();
+      render(<DateRangePicker />);
+      await user.click(screen.getByRole("button"));
+      const grids = await screen.findAllByRole("grid");
+      expect(grids).toHaveLength(1);
+    } finally {
+      Object.defineProperty(window, "innerWidth", {
+        writable: true,
+        configurable: true,
+        value: originalWidth,
+      });
+    }
+  });
+
+  it("shows the placeholder (not a stale value) when a controlled range is cleared to undefined", async () => {
+    function Harness() {
+      const [range, setRange] = useState<DateRange | undefined>({
+        from: new Date(2024, 0, 5),
+        to: new Date(2024, 0, 20),
+      });
+      return (
+        <>
+          <DateRangePicker value={range} onValueChange={setRange} placeholder="Pick a range" />
+          <button type="button" onClick={() => setRange(undefined)}>
+            Clear
+          </button>
+        </>
+      );
+    }
+    const user = userEvent.setup();
+    render(<Harness />);
+    const trigger = screen.getByRole("button", { name: /–/ });
+    expect(trigger.textContent).not.toBe("Pick a range");
+
+    await user.click(screen.getByRole("button", { name: "Clear" }));
+
+    expect(trigger).toHaveTextContent("Pick a range");
+  });
 });

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

@@ -1,14 +1,20 @@
 // a2ui.exposed: yes
 "use client";
 
-import { forwardRef, useState } from "react";
+import { forwardRef, type HTMLAttributes } from "react";
 import { Calendar as CalendarIcon } from "lucide-react";
 import type { DateRange } from "react-day-picker";
 import { cn } from "../../lib/cn";
+import { useControllableState } from "../../lib/use-controllable-state";
+import { useIsMobile } from "../../lib/use-mobile";
 import { Button } from "../button";
 import { Calendar } from "../calendar";
+import { useLocale } from "../locale-provider";
 import { Popover, PopoverContent, PopoverTrigger } from "../popover";
 
+/** Below this width, the calendar collapses to a single month (Tailwind `sm`). */
+const NARROW_BREAKPOINT = 640;
+
 export type { DateRange };
 
 export interface DateRangePreset {
@@ -16,7 +22,10 @@ export interface DateRangePreset {
   getRange: () => DateRange;
 }
 
-export interface DateRangePickerProps {
+export interface DateRangePickerProps extends Omit<
+  HTMLAttributes<HTMLButtonElement>,
+  "onSelect" | "children" | "value" | "defaultValue"
+> {
   value?: DateRange;
   defaultValue?: DateRange;
   onValueChange?: (range?: DateRange) => void;
@@ -26,16 +35,6 @@ export interface DateRangePickerProps {
   className?: string;
 }
 
-const fmt = (date: Date) =>
-  new Intl.DateTimeFormat(undefined, { dateStyle: "medium" }).format(date);
-
-function formatRange(range: DateRange | undefined, placeholder: string): string {
-  if (!range) return placeholder;
-  if (range.from && range.to) return `${fmt(range.from)} – ${fmt(range.to)}`;
-  if (range.from) return `${fmt(range.from)} – …`;
-  return placeholder;
-}
-
 /**
  * Date range picker (Popover + Calendar in range mode).
  * Supports optional preset quick-picks, controlled or uncontrolled.
@@ -50,24 +49,31 @@ export const DateRangePicker = forwardRef<HTMLButtonElement, DateRangePickerProp
       numberOfMonths = 2,
       placeholder = "Pick a date range",
       className,
+      ...props
     },
     ref,
   ) {
-    const [internal, setInternal] = useState<DateRange | undefined>(defaultValue);
-
-    const isControlled = value !== undefined;
-    const range = isControlled ? value : internal;
+    const { formatDate } = useLocale();
+    const [range, setRange] = useControllableState<DateRange | undefined>(
+      value,
+      defaultValue,
+      onValueChange,
+    );
 
-    const setRange = (r?: DateRange) => {
-      if (!isControlled) {
-        setInternal(r);
-      }
-      // Always fire the callback so uncontrolled consumers can observe changes
-      onValueChange?.(r);
+    const fmt = (date: Date) => formatDate(date, { dateStyle: "medium" });
+    const formatRange = (r: DateRange | undefined): string => {
+      if (!r) return placeholder;
+      if (r.from && r.to) return `${fmt(r.from)} – ${fmt(r.to)}`;
+      if (r.from) return `${fmt(r.from)} – …`;
+      return placeholder;
     };
 
     const hasRange = Boolean(range?.from);
-    const label = formatRange(range, placeholder);
+    const label = formatRange(range);
+
+    // Below `sm`, two side-by-side months push the popover off-screen (#reviewed).
+    const isNarrow = useIsMobile(NARROW_BREAKPOINT);
+    const monthsToShow = isNarrow ? 1 : numberOfMonths;
 
     return (
       <Popover>
@@ -76,8 +82,9 @@ export const DateRangePicker = forwardRef<HTMLButtonElement, DateRangePickerProp
             ref={ref}
             variant="outline"
             aria-haspopup="dialog"
+            {...props}
             className={cn(
-              "w-72 justify-start gap-2 text-start font-normal",
+              "w-full justify-start gap-2 text-start font-normal",
               !hasRange && "text-muted-foreground",
               className,
             )}
@@ -86,10 +93,14 @@ export const DateRangePicker = forwardRef<HTMLButtonElement, DateRangePickerProp
             {label}
           </Button>
         </PopoverTrigger>
-        <PopoverContent className="w-auto p-0" align="start">
+        <PopoverContent
+          className="w-auto max-w-[calc(100vw-1rem)] p-0"
+          align="start"
+          collisionPadding={8}
+        >
           {presets && presets.length > 0 ? (
             <div className="flex">
-              <div className="flex flex-col gap-1 border-r border-border p-2">
+              <div className="flex flex-col gap-1 border-e border-border p-2">
                 {presets.map((preset) => (
                   <Button
                     key={preset.label}
@@ -104,7 +115,7 @@ export const DateRangePicker = forwardRef<HTMLButtonElement, DateRangePickerProp
               </div>
               <Calendar
                 mode="range"
-                numberOfMonths={numberOfMonths}
+                numberOfMonths={monthsToShow}
                 selected={range}
                 onSelect={setRange}
                 autoFocus
@@ -113,7 +124,7 @@ export const DateRangePicker = forwardRef<HTMLButtonElement, DateRangePickerProp
           ) : (
             <Calendar
               mode="range"
-              numberOfMonths={numberOfMonths}
+              numberOfMonths={monthsToShow}
               selected={range}
               onSelect={setRange}
               autoFocus

package/src/components/descriptions/descriptions.stories.tsx

@@ -32,6 +32,12 @@ export const Default: Story = {
   render: (args) => <Descriptions {...args}>{items}</Descriptions>,
 };
 
+/** Short labels beside sentence-long values earn a narrower label column. */
+export const NarrowLabels: Story = {
+  args: { columns: 1, layout: "horizontal", labelWidth: "1/5" },
+  render: (args) => <Descriptions {...args}>{items}</Descriptions>,
+};
+
 export const TwoColumns: Story = {
   args: { columns: 2, layout: "horizontal" },
   render: (args) => <Descriptions {...args}>{items}</Descriptions>,

package/src/components/descriptions/descriptions.test.tsx

@@ -39,3 +39,21 @@ describe("Descriptions", () => {
     expect(container.querySelectorAll("dd")).toHaveLength(1);
   });
 });
+
+describe("Descriptions labelWidth", () => {
+  it("defaults the horizontal label column to a third and honours a narrower share", () => {
+    const { rerender } = render(
+      <Descriptions>
+        <DescriptionsItem label="Owner">Sofia</DescriptionsItem>
+      </Descriptions>,
+    );
+    expect(screen.getByText("Owner")).toHaveClass("w-1/3");
+    rerender(
+      <Descriptions labelWidth="1/5">
+        <DescriptionsItem label="Owner">Sofia</DescriptionsItem>
+      </Descriptions>,
+    );
+    expect(screen.getByText("Owner")).toHaveClass("w-1/5");
+    expect(screen.getByText("Owner")).not.toHaveClass("w-1/3");
+  });
+});

package/src/components/descriptions/descriptions.tsx

@@ -3,7 +3,7 @@ import { createContext, forwardRef, use, type HTMLAttributes } from "react";
 import { cva, type VariantProps } from "class-variance-authority";
 import { cn } from "../../lib/cn";
 
-const descriptionsVariants = cva("grid gap-x-6 gap-y-3 text-sm", {
+const descriptionsVariants = cva("grid gap-x-6 gap-y-3 text-body", {
   variants: {
     columns: {
       1: "grid-cols-1",
@@ -18,11 +18,29 @@ const descriptionsVariants = cva("grid gap-x-6 gap-y-3 text-sm", {
 
 type DescriptionsLayout = "horizontal" | "vertical";
 
+/**
+ * The label column's share of a `horizontal` item. Static class names, never
+ * a computed `w-[…]`, so Tailwind can see them. `"1/3"` is the default and
+ * the historical render; `"1/4"`/`"1/5"` suit a record whose labels are
+ * short ("What it did", "Owner") and whose values are sentences.
+ */
+export type DescriptionsLabelWidth = "1/3" | "1/4" | "1/5";
+
+const LABEL_WIDTH_CLASS: Record<DescriptionsLabelWidth, string> = {
+  "1/3": "w-1/3",
+  "1/4": "w-1/4",
+  "1/5": "w-1/5",
+};
+
 interface DescriptionsContextValue {
   layout: DescriptionsLayout;
+  labelWidth: DescriptionsLabelWidth;
 }
 
-const DescriptionsContext = createContext<DescriptionsContextValue>({ layout: "horizontal" });
+const DescriptionsContext = createContext<DescriptionsContextValue>({
+  layout: "horizontal",
+  labelWidth: "1/3",
+});
 
 export interface DescriptionsProps
   extends HTMLAttributes<HTMLDListElement>, VariantProps<typeof descriptionsVariants> {
@@ -36,6 +54,11 @@ export interface DescriptionsProps
    * label above the value. Default `horizontal`.
    */
   layout?: DescriptionsLayout;
+  /**
+   * Width of the label column in the `horizontal` layout, as a share of the
+   * item. Default `"1/3"`. Ignored by `vertical`.
+   */
+  labelWidth?: DescriptionsLabelWidth;
 }
 
 /**
@@ -45,11 +68,11 @@ export interface DescriptionsProps
  * `columns` controls the grid; `layout` controls label placement per item.
  */
 export const Descriptions = forwardRef<HTMLDListElement, DescriptionsProps>(function Descriptions(
-  { columns = 1, layout = "horizontal", className, children, ...props },
+  { columns = 1, layout = "horizontal", labelWidth = "1/3", className, children, ...props },
   ref,
 ) {
   return (
-    <DescriptionsContext value={{ layout }}>
+    <DescriptionsContext value={{ layout, labelWidth }}>
       <dl ref={ref} className={cn(descriptionsVariants({ columns }), className)} {...props}>
         {children}
       </dl>
@@ -72,7 +95,7 @@ export interface DescriptionsItemProps extends HTMLAttributes<HTMLDivElement> {
  */
 export const DescriptionsItem = forwardRef<HTMLDivElement, DescriptionsItemProps>(
   function DescriptionsItem({ label, numeric, className, children, ...props }, ref) {
-    const { layout } = use(DescriptionsContext);
+    const { layout, labelWidth } = use(DescriptionsContext);
     return (
       <div
         ref={ref}
@@ -83,7 +106,12 @@ export const DescriptionsItem = forwardRef<HTMLDivElement, DescriptionsItemProps
         )}
         {...props}
       >
-        <dt className={cn("text-muted-foreground", layout === "horizontal" && "w-1/3 shrink-0")}>
+        <dt
+          className={cn(
+            "text-muted-foreground",
+            layout === "horizontal" && cn(LABEL_WIDTH_CLASS[labelWidth], "shrink-0"),
+          )}
+        >
           {label}
         </dt>
         <dd className={cn("min-w-0 break-words text-foreground", numeric && "tabular-nums")}>

package/src/components/descriptions/index.ts

@@ -1,6 +1,7 @@
 export {
   Descriptions,
   DescriptionsItem,
+  type DescriptionsLabelWidth,
   type DescriptionsProps,
   type DescriptionsItemProps,
 } from "./descriptions";

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

@@ -66,6 +66,7 @@ export const Default: Story = {
  * horizontally. Before the fix the implicit `auto` column blew past `max-w-md`.
  */
 export const OverflowGuard: Story = {
+  name: "Long unbreakable text keeps the dialog width",
   render: () => (
     <Dialog>
       <DialogTrigger asChild>
@@ -392,6 +393,7 @@ export const FocusRingClearance: Story = {
  * `play` so a future regression of THIS story is caught rather than repeated.
  */
 export const FocusRingClearanceDark: Story = {
+  tags: ["!dev"],
   name: "Focus ring clearance — dark",
   globals: { theme: "dark" },
   render: FocusRingClearance.render,
@@ -450,6 +452,7 @@ export const WideWithSections: Story = {
 };
 
 export const WideWithSectionsDark: Story = {
+  tags: ["!dev"],
   name: "Wide with sections — dark",
   decorators: [
     (Story) => (
@@ -463,6 +466,7 @@ export const WideWithSectionsDark: Story = {
 };
 
 export const WideWithSectionsHighDecoration: Story = {
+  tags: ["!dev"],
   name: "Wide with sections — high decoration",
   globals: { decoration: "10" },
   render: () => <WideSettingsDialog prefix="wide-decorated" />,
@@ -685,6 +689,7 @@ function GuardedDialog({ children }: { children?: ReactNode }) {
  * because the component must not own app state (D5).
  */
 export const DirtyGuard: Story = {
+  name: "Unsaved changes confirm before closing",
   render: () => <GuardedDialog />,
   play: async ({ canvas, canvasElement, userEvent }) => {
     const doc = within(canvasElement.ownerDocument.body);

package/src/components/dialog/dialog.test.tsx

@@ -47,11 +47,16 @@ describe("DialogContent size variants", () => {
     expect(content.className).toContain("max-w-3xl");
   });
 
-  it("size='full' renders max-w-[95vw] and h-[90vh]", () => {
+  it("size='full' renders max-w-[95vw] and h-[90dvh] — dvh, not vh (mobile browser chrome)", () => {
     render(<Wrapper size="full" />);
     const content = screen.getByRole("dialog");
     expect(content.className).toContain("max-w-[95vw]");
-    expect(content.className).toContain("h-[90vh]");
+    expect(content.className).toContain("h-[90dvh]");
+    expect(content.className).toContain("max-h-[90dvh]");
+    // `vh` on mobile Safari/Chrome is measured against the viewport with the
+    // browser chrome collapsed, so a plain `vh` value overflows past what is
+    // actually visible while the address bar is shown.
+    expect(content.className).not.toMatch(/(?<!d)vh\]/);
   });
 });
 
@@ -106,7 +111,7 @@ describe("DialogContent height/scroll regime (#341)", () => {
     // later variant utility, so `full` still lets its body own the scroll.
     expect(content.className).toContain("overflow-hidden");
     expect(content.className).not.toContain("overflow-y-auto");
-    expect(content.className).toContain("max-h-[90vh]");
+    expect(content.className).toContain("max-h-[90dvh]");
     expect(content.className).not.toContain("max-h-[calc(100dvh-2rem)]");
   });
 });

package/src/components/dialog/dialog.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import {
   forwardRef,
   useCallback,
@@ -11,6 +13,7 @@ import {
 import * as DialogPrimitive from "@radix-ui/react-dialog";
 import { cva, type VariantProps } from "class-variance-authority";
 import { cn } from "../../lib/cn";
+import { useLocale } from "../locale-provider";
 import { Heading, Text } from "../typography";
 
 /**
@@ -48,14 +51,18 @@ export const dialogContentVariants = cva(
   //      is INERT for every dialog that has no `DialogBody`.
   // `size="full"`'s own `h-/max-h-/overflow-hidden` still wins — cva emits the
   // base first, so tailwind-merge resolves the later variant utilities over it.
-  "fixed left-1/2 top-1/2 z-50 grid grid-cols-[minmax(0,1fr)] w-full -translate-x-1/2 -translate-y-1/2 gap-4 max-h-[calc(100dvh-2rem)] overflow-y-auto overscroll-contain has-[[data-slot=dialog-body]]:overflow-hidden has-[[data-slot=dialog-body]]:grid-rows-[auto_minmax(0,1fr)_auto] rounded-xl bg-card p-6 text-card-foreground shadow-ring-lg 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",
+  "fixed left-1/2 top-1/2 z-50 grid grid-cols-[minmax(0,1fr)] w-full -translate-x-1/2 -translate-y-1/2 gap-4 max-h-[calc(100dvh-2rem)] overflow-y-auto overscroll-contain has-[[data-slot=dialog-body]]:overflow-hidden has-[[data-slot=dialog-body]]:grid-rows-[auto_minmax(0,1fr)_auto] rounded-xl bg-card p-6 text-card-foreground shadow-dialog 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",
   {
     variants: {
       size: {
         sm: "max-w-sm",
         lg: "max-w-lg",
         xl: "max-w-3xl",
-        full: "max-w-[95vw] h-[90vh] max-h-[90vh] overflow-hidden",
+        // `dvh` (dynamic viewport height), not `vh`: on mobile Safari/Chrome
+        // `vh` is measured against the LARGEST viewport (browser chrome
+        // collapsed), so `size="full"` overflows past the visible viewport
+        // while the address bar is showing.
+        full: "max-w-[95vw] h-[90dvh] max-h-[90dvh] overflow-hidden",
       },
     },
     defaultVariants: { size: "lg" },
@@ -76,7 +83,7 @@ export const DialogOverlay = forwardRef<
       ref={ref}
       data-slot="dialog-overlay"
       className={cn(
-        "fixed inset-0 z-50 bg-foreground/50 backdrop-blur-sm",
+        "fixed inset-0 z-50 bg-overlay backdrop-blur-overlay",
         "data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
         className,
       )}
@@ -90,6 +97,7 @@ export const DialogContent = forwardRef<
   ComponentPropsWithoutRef<typeof DialogPrimitive.Content> &
     VariantProps<typeof dialogContentVariants>
 >(function DialogContent({ className, children, size, onOpenAutoFocus, ...props }, ref) {
+  const { t } = useLocale();
   const contentRef = useRef<HTMLDivElement | null>(null);
   const setRefs = useCallback(
     (node: HTMLDivElement | null) => {
@@ -150,7 +158,7 @@ export const DialogContent = forwardRef<
         <DialogPrimitive.Close
           data-slot="dialog-close"
           className="absolute end-4 top-4 rounded-md p-1 text-muted-foreground opacity-70 transition-opacity hover:opacity-100 focus-ring"
-          aria-label="Close"
+          aria-label={t("close")}
         >
           <svg
             width="16"
@@ -213,7 +221,7 @@ export const DialogDescription = forwardRef<
     <DialogPrimitive.Description
       ref={ref}
       data-slot="dialog-description"
-      className={cn("text-sm text-muted-foreground", className)}
+      className={cn("text-body text-muted-foreground", className)}
       {...props}
     />
   );

package/src/components/drawer/drawer.tsx

@@ -25,7 +25,8 @@ const DrawerOverlay = forwardRef<
   return (
     <DrawerPrimitive.Overlay
       ref={ref}
-      className={cn("fixed inset-0 z-50 bg-foreground/50", className)}
+      data-slot="drawer-overlay"
+      className={cn("fixed inset-0 z-50 bg-overlay", className)}
       {...props}
     />
   );
@@ -40,13 +41,14 @@ export const DrawerContent = forwardRef<
       <DrawerOverlay />
       <DrawerPrimitive.Content
         ref={ref}
+        data-slot="drawer-content"
         className={cn(
           "fixed inset-x-0 bottom-0 z-50 mt-24 flex h-auto flex-col overscroll-contain rounded-t-xl border bg-card text-card-foreground",
           className,
         )}
         {...props}
       >
-        <div className="mx-auto mt-4 h-1.5 w-12 rounded-full bg-muted" />
+        <div data-slot="drawer-handle" className="mx-auto mt-4 h-1.5 w-12 rounded-full bg-muted" />
         {children}
       </DrawerPrimitive.Content>
     </DrawerPortal>
@@ -54,19 +56,33 @@ export const DrawerContent = forwardRef<
 });
 
 export function DrawerHeader({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
-  return <div className={cn("grid gap-1.5 p-4 text-center sm:text-start", className)} {...props} />;
+  return (
+    <div
+      data-slot="drawer-header"
+      className={cn("grid gap-1.5 p-4 text-center sm:text-start", className)}
+      {...props}
+    />
+  );
 }
 export function DrawerFooter({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
-  return <div className={cn("mt-auto flex flex-col gap-2 p-4", className)} {...props} />;
+  return (
+    <div
+      data-slot="drawer-footer"
+      className={cn("mt-auto flex flex-col gap-2 p-4", className)}
+      {...props}
+    />
+  );
 }
 export const DrawerTitle = forwardRef<
   ElementRef<typeof DrawerPrimitive.Title>,
   ComponentPropsWithoutRef<typeof DrawerPrimitive.Title>
 >(function DrawerTitle({ className, ...props }, ref) {
   return (
+    // `text-title`, matching `DialogTitle` (#286) — was `text-lg font-semibold`.
     <DrawerPrimitive.Title
       ref={ref}
-      className={cn("text-lg font-semibold", className)}
+      data-slot="drawer-title"
+      className={cn("text-title leading-none", className)}
       {...props}
     />
   );
@@ -78,7 +94,8 @@ export const DrawerDescription = forwardRef<
   return (
     <DrawerPrimitive.Description
       ref={ref}
-      className={cn("text-sm text-muted-foreground", className)}
+      data-slot="drawer-description"
+      className={cn("text-body text-muted-foreground", className)}
       {...props}
     />
   );

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

@@ -156,6 +156,7 @@ export const SubmenuRadioAndCheckbox: Story = {
  * persisting to localStorage across runs.
  */
 export const SubmenuRadioAndCheckboxDark: Story = {
+  tags: ["!dev"],
   name: "Submenu, radio group and checkbox item — dark",
   decorators: [
     (Story) => (
@@ -169,8 +170,44 @@ export const SubmenuRadioAndCheckboxDark: Story = {
 };
 
 export const SubmenuRadioAndCheckboxHighDecoration: Story = {
+  tags: ["!dev"],
   name: "Submenu, radio group and checkbox item — high decoration",
   globals: { decoration: "10" },
   render: SubmenuRadioAndCheckbox.render,
   play: SubmenuRadioAndCheckbox.play,
 };
+
+/**
+ * Locks WCAG 1.4.11 keyboard-focus contrast (#308): a menu item's
+ * `focus:bg-accent` fill alone measures ~1.17–1.40:1 against `--popover` in
+ * both themes — not a visible indicator. 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.getByRole("button", { name: /open menu/i });
+    await userEvent.click(trigger);
+    const body = within(canvasElement.ownerDocument.body);
+    await body.findByRole("menuitem", { name: "Profile" });
+    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);
+    // Close before the axe afterEach scan — an open portal otherwise leaves a
+    // stray focusable node behind an `aria-hidden` sibling from an earlier
+    // story's not-yet-cleaned-up DOM (aria-hidden-focus). Waiting for the menu
+    // to actually leave the DOM (not just sending the keystroke) matters: on a
+    // slower close — observed reproducibly under `STORYBOOK_THEME=dark`, never
+    // under light — the axe scan can otherwise run mid-close-transition, while
+    // the still-focusable menuitem sits inside a portal Radix has already
+    // marked `aria-hidden`.
+    await userEvent.keyboard("{Escape}");
+    await waitFor(() => expect(body.queryByRole("menu")).not.toBeInTheDocument());
+  },
+};