@elabs-ai/components-ui 4.0.0 → 4.2.0

package/src/components/tabs/tabs.test.tsx

@@ -76,6 +76,73 @@ describe("Tabs", () => {
   // scroll-into-view/320px-container behavior is layout-dependent and is
   // covered by the `OverflowScrollable` Storybook interaction test instead
   // (jsdom doesn't lay out real scroll geometry).
+  it("creates one shared observer pair per list, not one per trigger (#387)", () => {
+    const originalMutationObserver = globalThis.MutationObserver;
+    const originalResizeObserver = globalThis.ResizeObserver;
+    let mutationObserverCount = 0;
+    let resizeObserverCount = 0;
+
+    class CountingMutationObserver extends originalMutationObserver {
+      constructor(...args: ConstructorParameters<typeof MutationObserver>) {
+        super(...args);
+        mutationObserverCount += 1;
+      }
+    }
+    class CountingResizeObserver extends originalResizeObserver {
+      constructor(...args: ConstructorParameters<typeof ResizeObserver>) {
+        super(...args);
+        resizeObserverCount += 1;
+      }
+    }
+    globalThis.MutationObserver = CountingMutationObserver as typeof MutationObserver;
+    globalThis.ResizeObserver = CountingResizeObserver as typeof ResizeObserver;
+
+    try {
+      render(
+        <Tabs defaultValue="a">
+          <TabsList>
+            <TabsTrigger value="a">A</TabsTrigger>
+            <TabsTrigger value="b">B</TabsTrigger>
+            <TabsTrigger value="c">C</TabsTrigger>
+            <TabsTrigger value="d">D</TabsTrigger>
+          </TabsList>
+          <TabsContent value="a">Panel A</TabsContent>
+        </Tabs>,
+      );
+      // 4 triggers in the strip. Before the fix, each trigger owned its own
+      // MutationObserver AND ResizeObserver (4 of each here — the review's
+      // "20 callbacks per resize" was measured on a 20-tab strip).
+      const fourTriggerMutationCount = mutationObserverCount;
+      const fourTriggerResizeCount = resizeObserverCount;
+      expect(fourTriggerResizeCount).toBeGreaterThan(0);
+
+      mutationObserverCount = 0;
+      resizeObserverCount = 0;
+      render(
+        <Tabs defaultValue="a">
+          <TabsList>
+            <TabsTrigger value="a">A</TabsTrigger>
+            <TabsTrigger value="b">B</TabsTrigger>
+            <TabsTrigger value="c">C</TabsTrigger>
+            <TabsTrigger value="d">D</TabsTrigger>
+            <TabsTrigger value="e">E</TabsTrigger>
+            <TabsTrigger value="f">F</TabsTrigger>
+            <TabsTrigger value="g">G</TabsTrigger>
+            <TabsTrigger value="h">H</TabsTrigger>
+          </TabsList>
+          <TabsContent value="a">Panel A</TabsContent>
+        </Tabs>,
+      );
+      // The list owns a FIXED number of observers regardless of trigger
+      // count — doubling the trigger count must not double it.
+      expect(mutationObserverCount).toBe(fourTriggerMutationCount);
+      expect(resizeObserverCount).toBe(fourTriggerResizeCount);
+    } finally {
+      globalThis.MutationObserver = originalMutationObserver;
+      globalThis.ResizeObserver = originalResizeObserver;
+    }
+  });
+
   it("renders TabsList as a bounded scroll container with safe centering", () => {
     render(
       <Tabs defaultValue="a">

package/src/components/tabs/tabs.tsx

@@ -1,5 +1,9 @@
+"use client";
+
 import {
+  createContext,
   forwardRef,
+  use,
   useEffect,
   useMemo,
   useRef,
@@ -7,6 +11,7 @@ import {
   type ElementRef,
 } from "react";
 import * as TabsPrimitive from "@radix-ui/react-tabs";
+import { cva, type VariantProps } from "class-variance-authority";
 import { useReducedMotion } from "@elabs-ai/components-tokens";
 import { cn } from "../../lib/cn";
 import { mergeRefs } from "../../lib/merge-refs";
@@ -68,85 +73,184 @@ function scrollTriggerIntoStrip(trigger: HTMLElement, behavior: ScrollBehavior)
  * start-alignment on overflow while staying visually identical when the
  * strip fits (see #344).
  */
-export const TabsList = forwardRef<
-  ElementRef<typeof TabsPrimitive.List>,
-  ComponentPropsWithoutRef<typeof TabsPrimitive.List>
->(function TabsList({ className, ...props }, ref) {
-  return (
-    <TabsPrimitive.List
-      ref={ref}
-      className={cn(
-        "inline-flex h-9 max-w-full items-center justify-center-safe overflow-x-auto rounded-lg bg-muted p-1 text-muted-foreground",
-        className,
-      )}
-      {...props}
-    />
-  );
-});
+export const tabsListVariants = cva(
+  "max-w-full items-center overflow-x-auto text-muted-foreground",
+  {
+    variants: {
+      variant: {
+        // Recessed pill track with a raised active segment.
+        segmented: "inline-flex h-9 justify-center-safe rounded-lg bg-muted p-1",
+        // Line tabs: a transparent start-aligned row over a 1px rule; the active
+        // tab's 2px underline sits on top of it (see `tabsTriggerVariants`).
+        underline: "flex w-full justify-start border-b border-rule",
+      },
+    },
+    defaultVariants: { variant: "segmented" },
+  },
+);
+
+export const tabsTriggerVariants = cva(
+  "inline-flex items-center justify-center whitespace-nowrap text-body font-control transition-colors duration-fast disabled:pointer-events-none disabled:opacity-50",
+  {
+    variants: {
+      variant: {
+        segmented: cn(
+          "rounded-control px-3 py-1",
+          // `ring-offset-1`, not `-2`: the compound indicator's reach is
+          // `ring-offset` + 2px ring + 1px contour, and `TabsList` is an
+          // `overflow-x-auto` strip with `p-1` (4px). At offset 2 the reach is 5px
+          // and the scroll box clips the contour on three sides (#67 fix round 2,
+          // measured on `patterns-templates-object-detail-hub--default` tab stop
+          // 9); at offset 1 it is exactly 4px and the loop closes.
+          "focus-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
+          "data-[state=active]:bg-surface-elevated data-[state=active]:text-foreground data-[state=active]:shadow-sm",
+        ),
+        underline: cn(
+          // The underline is a bottom BORDER inside the fixed height, transparent
+          // at rest, so activation never shifts layout. No negative margin to
+          // overlap the list's rule: the list scrolls (`overflow-x-auto`), which
+          // would clip anything hanging past its padding box. The strip has no
+          // padding for an outer ring either, so the indicator is drawn inset.
+          "h-12 rounded-none border-b-2 border-transparent px-4 hover:text-foreground",
+          "focus-ring-inset",
+          "data-[state=active]:border-primary data-[state=active]:text-foreground",
+        ),
+      },
+    },
+    defaultVariants: { variant: "segmented" },
+  },
+);
+
+export type TabsVariant = NonNullable<VariantProps<typeof tabsListVariants>["variant"]>;
+
+// The list owns the variant; its triggers read it, so a strip never mixes two.
+const TabsVariantContext = createContext<TabsVariant>("segmented");
+
+export interface TabsListProps
+  extends
+    ComponentPropsWithoutRef<typeof TabsPrimitive.List>,
+    VariantProps<typeof tabsListVariants> {}
+
+export const TabsList = forwardRef<ElementRef<typeof TabsPrimitive.List>, TabsListProps>(
+  function TabsList({ className, variant, ...props }, ref) {
+    const resolved = variant ?? "segmented";
+    const innerRef = useRef<HTMLDivElement | null>(null);
+    const mergedRef = useMemo(() => mergeRefs(ref, innerRef), [ref]);
+    // Honours the in-app tri-state motion preference on `ThemeProvider` as well
+    // as the OS setting, and degrades to OS-only outside a provider.
+    const reducedMotion = useReducedMotion();
+
+    // Keep the tab that BECOMES active inside the strip's visible bounds.
+    //
+    // ONE set of observers per LIST, not one per trigger (#387 perf finding:
+    // N triggers used to mean N independent `MutationObserver`s (each
+    // watching only its own node) plus N independent `ResizeObserver`s (each
+    // ALSO watching this same shared strip) — a resize of a 20-tab strip fired
+    // 20 redundant callbacks. Watching the list's subtree in one callback
+    // gets the same behaviour for the cost of one.
+    //
+    // Watching attributes rather than reacting to a render is still
+    // load-bearing: Radix flips `data-state` on the trigger it renders, and
+    // only ITS OWN context consumer re-renders — this component does not, so
+    // a render-driven effect would never observe an activation at all
+    // (measured: 8 effect runs for 8 triggers at mount, zero on any later
+    // activation). A MutationObserver fires on a genuine inactive → active
+    // TRANSITION and never at mount, which is what stops a freshly-mounted
+    // Tabs from scrolling anything (#344 shipped a version that scrolled the
+    // page 900px on every mount).
+    useEffect(() => {
+      const node = innerRef.current;
+      if (!node) return;
+
+      const scrollActiveIntoView = () => {
+        const active = node.querySelector<HTMLElement>(
+          '[data-slot="tabs-trigger"][data-state="active"]',
+        );
+        if (active) scrollTriggerIntoStrip(active, reducedMotion ? "auto" : "smooth");
+      };
+
+      const activationObserver = new MutationObserver((mutations) => {
+        for (const mutation of mutations) {
+          const el = mutation.target as HTMLElement;
+          if (el.getAttribute("data-state") === "active") {
+            scrollTriggerIntoStrip(el, reducedMotion ? "auto" : "smooth");
+            break;
+          }
+        }
+      });
+      activationObserver.observe(node, {
+        subtree: true,
+        attributes: true,
+        attributeFilter: ["data-state"],
+      });
+
+      // A relayout AFTER the scroll invalidates the target it was computed
+      // from: a webfont swapping in on a cold load (measured — a
+      // mono-everything theme's wider mono face left the last tab 45px
+      // outside the strip), or the strip itself being resized. One
+      // `ResizeObserver` instance covers both — it watches the strip AND
+      // every trigger inside it, not a second instance per trigger.
+      let resizeObserver: ResizeObserver | undefined;
+      if (typeof ResizeObserver === "function") {
+        resizeObserver = new ResizeObserver(scrollActiveIntoView);
+        resizeObserver.observe(node);
+        for (const trigger of node.querySelectorAll<HTMLElement>('[data-slot="tabs-trigger"]')) {
+          resizeObserver.observe(trigger);
+        }
+      }
+
+      // A dynamic tab list can add/remove triggers later — keep the single
+      // `ResizeObserver`'s target set in sync instead of spinning up a new
+      // observer per trigger mount.
+      const childListObserver = new MutationObserver((mutations) => {
+        if (!resizeObserver) return;
+        for (const mutation of mutations) {
+          mutation.addedNodes.forEach((added) => {
+            if (added instanceof HTMLElement && added.matches('[data-slot="tabs-trigger"]')) {
+              resizeObserver!.observe(added);
+            }
+          });
+          mutation.removedNodes.forEach((removed) => {
+            if (removed instanceof HTMLElement && removed.matches('[data-slot="tabs-trigger"]')) {
+              resizeObserver!.unobserve(removed);
+            }
+          });
+        }
+      });
+      childListObserver.observe(node, { childList: true, subtree: true });
+
+      return () => {
+        activationObserver.disconnect();
+        resizeObserver?.disconnect();
+        childListObserver.disconnect();
+      };
+    }, [reducedMotion]);
+
+    return (
+      <TabsVariantContext.Provider value={resolved}>
+        <TabsPrimitive.List
+          ref={mergedRef}
+          data-slot="tabs-list"
+          data-variant={resolved}
+          className={cn(tabsListVariants({ variant: resolved }), className)}
+          {...props}
+        />
+      </TabsVariantContext.Provider>
+    );
+  },
+);
 
 export const TabsTrigger = forwardRef<
   ElementRef<typeof TabsPrimitive.Trigger>,
   ComponentPropsWithoutRef<typeof TabsPrimitive.Trigger>
 >(function TabsTrigger({ className, ...props }, ref) {
-  const innerRef = useRef<HTMLButtonElement>(null);
-  const mergedRef = useMemo(() => mergeRefs(ref, innerRef), [ref]);
-  // Honours the in-app tri-state motion preference on `ThemeProvider` as well
-  // as the OS setting, and degrades to OS-only outside a provider.
-  const reducedMotion = useReducedMotion();
-
-  // Keep the tab that BECOMES active inside the strip's visible bounds.
-  //
-  // Watching the attribute rather than reacting to a render is load-bearing on
-  // both counts:
-  //  - Radix flips `data-state` on the trigger it renders INSIDE this wrapper,
-  //    and only its own context consumer re-renders — this component does not.
-  //    A render-driven effect therefore never observes an activation at all
-  //    (measured: 8 effect runs for 8 triggers at mount, zero on any later
-  //    activation), so the scroll only ever ran when the CONSUMER's own state
-  //    changed.
-  //  - A MutationObserver fires on a genuine inactive → active TRANSITION and
-  //    never at mount, which is what stops a freshly-mounted Tabs from
-  //    scrolling anything (#344 shipped a version that scrolled the page 900px
-  //    on every mount).
-  useEffect(() => {
-    const node = innerRef.current;
-    if (!node) return;
-
-    const scrollIfActive = () => {
-      if (node.getAttribute("data-state") !== "active") return;
-      scrollTriggerIntoStrip(node, reducedMotion ? "auto" : "smooth");
-    };
-
-    const observer = new MutationObserver(scrollIfActive);
-    observer.observe(node, { attributes: true, attributeFilter: ["data-state"] });
-
-    // A relayout AFTER the scroll invalidates the target it was computed from:
-    // a webfont swapping in on a cold load (measured — a mono-everything theme's
-    // wider mono face left the last tab 45px outside the strip), or the strip
-    // being resized. Re-measure whenever the tab or the strip changes size;
-    // the delta check makes every unaffected pass a no-op.
-    const resizeObserver =
-      typeof ResizeObserver === "function" ? new ResizeObserver(scrollIfActive) : undefined;
-    resizeObserver?.observe(node);
-    const strip = node.closest<HTMLElement>('[role="tablist"]');
-    if (strip) resizeObserver?.observe(strip);
-
-    return () => {
-      observer.disconnect();
-      resizeObserver?.disconnect();
-    };
-  }, [reducedMotion]);
+  const variant = use(TabsVariantContext);
 
   return (
     <TabsPrimitive.Trigger
-      ref={mergedRef}
-      className={cn(
-        "inline-flex items-center justify-center whitespace-nowrap rounded-md px-3 py-1 text-sm font-medium transition-colors duration-fast",
-        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
-        "disabled:pointer-events-none disabled:opacity-50",
-        "data-[state=active]:bg-surface-elevated data-[state=active]:text-foreground data-[state=active]:shadow-sm",
-        className,
-      )}
+      ref={ref}
+      data-slot="tabs-trigger"
+      className={cn(tabsTriggerVariants({ variant }), className)}
       {...props}
     />
   );
@@ -160,7 +264,7 @@ export const TabsContent = forwardRef<
     <TabsPrimitive.Content
       ref={ref}
       className={cn(
-        "mt-2 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
+        "mt-2 focus-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
         "data-[state=active]:animate-in data-[state=active]:fade-in-0 data-[state=active]:slide-in-from-bottom-1 data-[state=active]:[--tw-ease:var(--ease-entrance)]",
         className,
       )}

package/src/components/tag-input/tag-input.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 // a2ui.exposed: yes
 import {
   forwardRef,
@@ -208,7 +210,7 @@ export const TagInput = forwardRef<HTMLDivElement, TagInputProps>(function TagIn
               }}
               className={cn(
                 "rounded-full p-0.5 transition-colors",
-                "hover:bg-secondary-foreground/20 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+                "hover:bg-secondary-foreground/20 focus-ring",
                 "disabled:pointer-events-none disabled:opacity-50",
               )}
             >
@@ -229,7 +231,7 @@ export const TagInput = forwardRef<HTMLDivElement, TagInputProps>(function TagIn
           aria-invalid={error ? "true" : undefined}
           data-slot="input-group-control"
           className={cn(
-            "min-w-[6rem] flex-1 bg-transparent text-sm outline-none",
+            "min-w-[6rem] flex-1 bg-transparent text-body outline-none",
             "placeholder:text-muted-foreground",
             "disabled:cursor-not-allowed disabled:opacity-50",
           )}
@@ -240,7 +242,8 @@ export const TagInput = forwardRef<HTMLDivElement, TagInputProps>(function TagIn
         />
       </InputGroup>
       {error && (
-        <p role="alert" className="text-xs text-destructive">
+        // #124: running text (the validation message) — ink rung.
+        <p role="alert" className="text-meta text-destructive-text">
           {error}
         </p>
       )}

package/src/components/team-switcher/team-switcher.tsx

@@ -12,6 +12,7 @@ import {
   DropdownMenuTrigger,
 } from "../dropdown-menu";
 import { SidebarMenu, SidebarMenuButton, SidebarMenuItem, useSidebar } from "../sidebar";
+import { useLocale } from "../locale-provider";
 import { cn } from "../../lib/cn";
 
 export type TeamSwitcherTeam = {
@@ -37,6 +38,7 @@ export interface TeamSwitcherProps {
  */
 export function TeamSwitcher({ teams, logoClassName, className }: TeamSwitcherProps) {
   const { isMobile } = useSidebar();
+  const { t } = useLocale();
   const [activeTeam, setActiveTeam] = React.useState(teams[0]);
   if (!activeTeam) return null;
   const Logo = activeTeam.logo;
@@ -48,21 +50,44 @@ export function TeamSwitcher({ teams, logoClassName, className }: TeamSwitcherPr
           <DropdownMenuTrigger asChild>
             <SidebarMenuButton
               size="lg"
+              // The name is written out rather than left to the button's own
+              // contents, because the contents cannot carry it in every state:
+              // collapsed to the 48px rail the trigger is one glyph, and the
+              // label beside it is either gone or clipped out of view by the
+              // button's `overflow-hidden` — either way axe reads a nameless
+              // button (`button-name`, critical). The string is exactly the
+              // visible label, in reading order, so WCAG 2.5.3 (label in name)
+              // holds expanded, where that label IS on screen. Verified by
+              // deleting this line and watching three dashboard stories fail
+              // `button-name` (critical).
+              aria-label={`${activeTeam.name} ${activeTeam.plan}`}
               className="data-[state=open]:bg-sidebar-accent data-[state=open]:text-sidebar-accent-foreground"
             >
+              {/* Collapsed, this row is ONE ICON in a 48px rail and has to sit
+                  on the same centre line as every nav entry above and below it.
+                  Measured before this fix: the 32px plate did not fit the
+                  button's 16px content box, so it overflowed (clipped by the
+                  button's own `overflow-hidden`) and its glyph landed 8px to the
+                  trailing side of every other icon in the rail. So the plate
+                  becomes the glyph's own 16px box — no fill, no radius, nothing
+                  to overflow — and the label and chevron stand down: at 48px
+                  there is no room to read them, and they are what crowds the
+                  plate. Expanded, all three come back unchanged. */}
               <div
                 className={cn(
-                  "flex aspect-square size-8 items-center justify-center rounded-lg",
+                  "flex aspect-square size-8 shrink-0 items-center justify-center rounded-lg",
                   logoClassName ?? "bg-sidebar-accent text-sidebar-accent-foreground",
+                  "group-data-[collapsible=icon]:size-4 group-data-[collapsible=icon]:rounded-none group-data-[collapsible=icon]:bg-transparent group-data-[collapsible=icon]:text-sidebar-foreground",
                 )}
               >
                 <Logo className="size-4" />
               </div>
-              <div className="grid flex-1 text-start text-sm leading-tight">
+              <div className="grid flex-1 text-start text-body leading-tight group-data-[collapsible=icon]:hidden">
                 <span className="truncate font-semibold">{activeTeam.name}</span>
-                <span className="truncate text-xs">{activeTeam.plan}</span>
+                <span className="truncate text-meta">{activeTeam.plan}</span>
               </div>
-              <ChevronsUpDown className="ms-auto" />
+              {/* Decorative, so it simply goes. */}
+              <ChevronsUpDown className="ms-auto group-data-[collapsible=icon]:hidden" />
             </SidebarMenuButton>
           </DropdownMenuTrigger>
           <DropdownMenuContent
@@ -71,7 +96,9 @@ export function TeamSwitcher({ teams, logoClassName, className }: TeamSwitcherPr
             side={isMobile ? "bottom" : "right"}
             sideOffset={4}
           >
-            <DropdownMenuLabel className="text-xs text-muted-foreground">Teams</DropdownMenuLabel>
+            <DropdownMenuLabel className="text-meta text-muted-foreground">
+              {t("ui.teamSwitcher.label")}
+            </DropdownMenuLabel>
             {teams.map((team, index) => (
               <DropdownMenuItem
                 key={team.name}
@@ -90,7 +117,9 @@ export function TeamSwitcher({ teams, logoClassName, className }: TeamSwitcherPr
               <div className="flex size-6 items-center justify-center rounded-md border bg-transparent">
                 <Plus className="size-4" />
               </div>
-              <div className="font-medium text-muted-foreground">Add team</div>
+              <div className="font-medium text-muted-foreground">
+                {t("ui.teamSwitcher.addTeam")}
+              </div>
             </DropdownMenuItem>
           </DropdownMenuContent>
         </DropdownMenu>

package/src/components/textarea/textarea.tsx

@@ -11,9 +11,9 @@ export const Textarea = forwardRef<HTMLTextAreaElement, TextareaProps>(function
     <textarea
       ref={ref}
       className={cn(
-        "flex min-h-20 w-full rounded-md border border-input bg-background px-3 py-2 text-sm shadow-sm transition-[color,background-color,border-color,box-shadow] duration-fast ease-standard",
+        "flex min-h-20 w-full rounded-control border border-input bg-input-background px-3 py-2 text-body shadow-input transition-[color,background-color,border-color,box-shadow] duration-fast ease-standard",
         "placeholder:text-muted-foreground",
-        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
+        "focus-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
         "disabled:cursor-not-allowed disabled:opacity-50 disabled:border-border",
         "aria-[invalid=true]:border-destructive aria-[invalid=true]:ring-destructive",
         className,

package/src/components/theme-switcher/theme-switcher.stories.tsx

@@ -144,3 +144,79 @@ export const RestrictedProvider: Story = {
     await waitFor(() => expect(body.queryByRole("menu")).not.toBeInTheDocument());
   },
 };
+
+/**
+ * Theme families (ADR 0036). Once two or more families declare `family`, the
+ * switcher offers a **Theme** group and — for a family with both schemes — a
+ * separate **Mode** group (Light / Dark / System). `ocean-*` are the
+ * downloadable family in repo-root `themes/ocean/`, whose CSS this Storybook
+ * imports.
+ */
+const oceanThemes = [
+  defineTheme({
+    value: "ocean-light",
+    label: "Ocean Light",
+    dark: false,
+    family: "ocean",
+    familyLabel: "Ocean",
+  }),
+  defineTheme({ value: "ocean-dark", label: "Ocean Dark", dark: true, family: "ocean" }),
+];
+const FAMILY_REGISTRY = [...BUILT_IN_THEME_DEFINITIONS, ...oceanThemes];
+
+export const WithThemeFamilies: Story = {
+  decorators: [
+    (Story) => (
+      <ThemeProvider themes={FAMILY_REGISTRY} defaultTheme="light" storageKey={null}>
+        <div className="flex min-h-32 items-center justify-center">
+          <Story />
+        </div>
+      </ThemeProvider>
+    ),
+  ],
+  play: async ({ canvas, canvasElement, userEvent }) => {
+    const root = canvasElement.ownerDocument.documentElement;
+    const body = within(canvasElement.ownerDocument.body);
+    await userEvent.click(canvas.getByRole("button", { name: "Theme" }));
+    await userEvent.click(await body.findByRole("menuitemradio", { name: "Ocean" }));
+    await waitFor(() => expect(root).toHaveAttribute("data-theme", "ocean-light"));
+    // The closing menu keeps the canvas aria-hidden until it unmounts; reopen only after.
+    await waitFor(() => expect(body.queryByRole("menu")).not.toBeInTheDocument());
+    await userEvent.click(await canvas.findByRole("button", { name: "Theme" }));
+    await userEvent.click(await body.findByRole("menuitemradio", { name: "Dark" }));
+    await waitFor(() => expect(root).toHaveAttribute("data-theme", "ocean-dark"));
+    await waitFor(() => expect(body.queryByRole("menu")).not.toBeInTheDocument());
+  },
+};
+
+/**
+ * A family that ships only one scheme shows no Mode group. `Dusk` borrows the
+ * reference `dark` block as its only variant.
+ */
+const duskTheme = defineTheme({
+  value: "dark",
+  label: "Dusk",
+  dark: true,
+  family: "dusk",
+  familyLabel: "Dusk (dark only)",
+});
+
+export const SingleModeFamily: Story = {
+  decorators: [
+    (Story) => (
+      <ThemeProvider themes={[...oceanThemes, duskTheme]} defaultTheme="dark" storageKey={null}>
+        <div className="flex min-h-32 items-center justify-center">
+          <Story />
+        </div>
+      </ThemeProvider>
+    ),
+  ],
+  play: async ({ canvas, canvasElement, userEvent }) => {
+    const body = within(canvasElement.ownerDocument.body);
+    await userEvent.click(canvas.getByRole("button", { name: "Theme" }));
+    await expect(await body.findByRole("menuitemradio", { name: /Dusk/ })).toBeChecked();
+    await expect(body.queryByRole("menuitemradio", { name: "Light" })).not.toBeInTheDocument();
+    await userEvent.keyboard("{Escape}");
+    await waitFor(() => expect(body.queryByRole("menu")).not.toBeInTheDocument());
+  },
+};