@elabs-ai/components-ui 4.1.0 → 4.2.0

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

@@ -7,6 +7,7 @@ import {
   BUILT_IN_THEME_DEFINITIONS,
   defineTheme,
   ThemeProvider,
+  useTheme,
 } from "@elabs-ai/components-tokens";
 
 import { ThemeSwitcher } from "./theme-switcher";
@@ -251,3 +252,184 @@ describe("ThemeSwitcher — consumer themes (ADR 0029)", () => {
     );
   });
 });
+
+describe("ThemeSwitcher — theme families (ADR 0036)", () => {
+  const oceanLight = defineTheme({
+    value: "ocean-light",
+    label: "Ocean light",
+    dark: false,
+    family: "ocean",
+    familyLabel: "Ocean",
+  });
+  const oceanDark = defineTheme({
+    value: "ocean-dark",
+    label: "Ocean dark",
+    dark: true,
+    family: "ocean",
+  });
+  const dusk = defineTheme({
+    value: "dusk",
+    label: "Dusk",
+    dark: true,
+    family: "dusk",
+    familyLabel: "Dusk",
+  });
+  const midnight = defineTheme({ value: "midnight", label: "Midnight", dark: true });
+  const daylight = defineTheme({ value: "daylight", label: "Daylight", dark: false });
+  const REGISTRY = [...BUILT_IN_THEME_DEFINITIONS, oceanLight, oceanDark, dusk];
+
+  async function openMenu() {
+    await userEvent.click(screen.getByRole("button", { name: "Theme" }));
+    return screen.findByRole("menu");
+  }
+
+  it("BACKWARD COMPAT: the default provider still renders the cycle toggle", () => {
+    setup(<ThemeSwitcher />);
+    expect(screen.getByRole("button", { name: /theme:/i })).toBeInTheDocument();
+  });
+
+  it("BACKWARD COMPAT: built-ins plus one undeclared theme stays a flat dropdown", async () => {
+    render(
+      <ThemeProvider themes={[...BUILT_IN_THEME_DEFINITIONS, midnight]}>
+        <ThemeSwitcher />
+      </ThemeProvider>,
+    );
+    const menu = await openMenu();
+    expect(within(menu).queryAllByRole("menuitemradio")).toHaveLength(0);
+    expect(within(menu).getByText("Midnight")).toBeInTheDocument();
+  });
+
+  it("BACKWARD COMPAT: an undeclared two-theme pair stays a light/dark toggle", () => {
+    render(
+      <ThemeProvider themes={[daylight, midnight]} defaultTheme="daylight">
+        <ThemeSwitcher showSystem={false} />
+      </ThemeProvider>,
+    );
+    expect(screen.getByRole("button", { name: /theme:/i })).toHaveAccessibleName(
+      "Theme: Daylight. Activate to switch to Midnight.",
+    );
+  });
+
+  it("offers families and a separate mode group once two families are declared", async () => {
+    render(
+      <ThemeProvider themes={REGISTRY} defaultTheme="light">
+        <ThemeSwitcher />
+      </ThemeProvider>,
+    );
+    const menu = await openMenu();
+    const radios = within(menu).getAllByRole("menuitemradio");
+    expect(radios.map((r) => r.textContent)).toEqual([
+      "Default",
+      "Ocean",
+      "Dusk",
+      "Light",
+      "Dark",
+      "System",
+    ]);
+    expect(within(menu).getByRole("menuitemradio", { name: "Default" })).toBeChecked();
+    expect(within(menu).getByRole("menuitemradio", { name: "Light" })).toBeChecked();
+  });
+
+  it("switching family keeps the chosen mode", async () => {
+    render(
+      <ThemeProvider themes={REGISTRY} defaultTheme="dark">
+        <ThemeSwitcher />
+      </ThemeProvider>,
+    );
+    await openMenu();
+    await userEvent.click(screen.getByRole("menuitemradio", { name: "Ocean" }));
+    expect(document.documentElement.getAttribute("data-theme")).toBe("ocean-dark");
+  });
+
+  it("switching mode stays within the family", async () => {
+    render(
+      <ThemeProvider themes={REGISTRY} defaultTheme="ocean-light">
+        <ThemeSwitcher />
+      </ThemeProvider>,
+    );
+    await openMenu();
+    await userEvent.click(screen.getByRole("menuitemradio", { name: "Dark" }));
+    expect(document.documentElement.getAttribute("data-theme")).toBe("ocean-dark");
+  });
+
+  it("hides the mode group for a single-mode family", async () => {
+    render(
+      <ThemeProvider themes={REGISTRY} defaultTheme="dusk">
+        <ThemeSwitcher />
+      </ThemeProvider>,
+    );
+    const menu = await openMenu();
+    expect(within(menu).queryByRole("menuitemradio", { name: "Light" })).not.toBeInTheDocument();
+    expect(within(menu).queryByText("Mode")).not.toBeInTheDocument();
+  });
+
+  it("remembers dark across a light-only family", async () => {
+    const sand = defineTheme({ value: "sand", label: "Sand", dark: false, family: "sand" });
+    render(
+      <ThemeProvider themes={[...REGISTRY, sand]} defaultTheme="dark">
+        <ThemeSwitcher />
+      </ThemeProvider>,
+    );
+    await openMenu();
+    await userEvent.click(screen.getByRole("menuitemradio", { name: "sand" }));
+    expect(document.documentElement.getAttribute("data-theme")).toBe("sand");
+    await openMenu();
+    await userEvent.click(screen.getByRole("menuitemradio", { name: "Ocean" }));
+    expect(document.documentElement.getAttribute("data-theme")).toBe("ocean-dark");
+  });
+
+  it("checks the right family when a second same-scheme variant is active", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const oceanDeep = defineTheme({
+      value: "ocean-deep",
+      label: "Ocean deep",
+      dark: true,
+      family: "ocean",
+    });
+    render(
+      <ThemeProvider themes={[...REGISTRY, oceanDeep]} defaultTheme="ocean-deep">
+        <ThemeSwitcher />
+      </ThemeProvider>,
+    );
+    const menu = await openMenu();
+    expect(within(menu).getByRole("menuitemradio", { name: "Ocean" })).toBeChecked();
+    expect(within(menu).getByRole("menuitemradio", { name: "Default" })).not.toBeChecked();
+    warn.mockRestore();
+  });
+
+  it("forgets a remembered mode once another control changes the theme", async () => {
+    function ExternalLight() {
+      const { setTheme } = useTheme();
+      return (
+        <button type="button" onClick={() => setTheme("light")}>
+          External light
+        </button>
+      );
+    }
+    render(
+      <ThemeProvider themes={REGISTRY} defaultTheme="light">
+        <ThemeSwitcher />
+        <ExternalLight />
+      </ThemeProvider>,
+    );
+    await openMenu();
+    await userEvent.click(screen.getByRole("menuitemradio", { name: "Dark" }));
+    expect(document.documentElement.getAttribute("data-theme")).toBe("dark");
+    await userEvent.click(screen.getByRole("button", { name: "External light" }));
+    expect(document.documentElement.getAttribute("data-theme")).toBe("light");
+    await openMenu();
+    await userEvent.click(screen.getByRole("menuitemradio", { name: "Ocean" }));
+    expect(document.documentElement.getAttribute("data-theme")).toBe("ocean-light");
+  });
+
+  it("forced dropdown mode keeps the flat list even with families", async () => {
+    render(
+      <ThemeProvider themes={REGISTRY}>
+        <ThemeSwitcher mode="dropdown" />
+      </ThemeProvider>,
+    );
+    const menu = await openMenu();
+    expect(within(menu).queryAllByRole("menuitemradio")).toHaveLength(0);
+    expect(within(menu).getByText("Ocean dark")).toBeInTheDocument();
+  });
+});

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

@@ -1,14 +1,27 @@
 "use client";
 
-import { forwardRef, useCallback, useEffect, useState, type HTMLAttributes } from "react";
+import { forwardRef, useCallback, useEffect, useRef, useState, type HTMLAttributes } from "react";
 import { Check, Monitor, Moon, Sun } from "lucide-react";
-import { useTheme, type ThemeDefinition, type ThemeName } from "@elabs-ai/components-tokens";
+import {
+  groupThemeFamilies,
+  resolveThemeVariant,
+  themeFamilyIdOf,
+  themeSchemeOf,
+  useTheme,
+  type ThemeDefinition,
+  type ThemeName,
+  type ThemeScheme,
+} from "@elabs-ai/components-tokens";
 
 import { Button } from "../button";
 import {
   DropdownMenu,
   DropdownMenuContent,
   DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuSeparator,
   DropdownMenuTrigger,
 } from "../dropdown-menu";
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "../tooltip";
@@ -129,16 +142,43 @@ export const ThemeSwitcher = forwardRef<HTMLButtonElement, ThemeSwitcherProps>(
     const labelOf = (name: ThemeName) => offered.find((d) => d.value === name)?.label ?? name;
     const isDark = (name: ThemeName) => offered.find((d) => d.value === name)?.dark ?? false;
 
-    // `?? theme` (the active theme), never a "light"/"dark" literal: with an open
-    // registry those names may not exist at all in this app.
-    const lightTheme: ThemeName = pickByDarkness(offered, false) ?? theme;
-    const darkTheme: ThemeName = pickByDarkness(offered, true) ?? theme;
-
     // The concrete theme to DISPLAY as current: the controlled preference when
     // it names one, otherwise the theme actually applied via the provider.
     const resolvedTheme: ThemeName =
       isControlled && preference !== undefined && preference !== "system" ? preference : theme;
 
+    // ADR 0036 — the family layout is OPT-IN: only when the offered list (not the
+    // provider's `families`, so the `themes` prop still narrows) holds two or
+    // more DECLARED families. An undeclared `[daylight, midnight]` pair keeps
+    // today's toggle byte-for-byte.
+    const families = groupThemeFamilies(offered);
+    const useFamilies = mode === "auto" && families.filter((f) => f.declared).length >= 2;
+    // Match by the active definition's declared family, not the retained
+    // light/dark slots: a second same-scheme variant is still reachable via
+    // `setTheme` but is not in either slot.
+    const activeDefinition = offered.find((d) => d.value === resolvedTheme);
+    const activeFamily = useFamilies
+      ? ((activeDefinition && families.find((f) => f.id === themeFamilyIdOf(activeDefinition))) ??
+        families[0])
+      : undefined;
+    // "System" is scoped to the active family in the family layout.
+    const scope: readonly ThemeDefinition[] = activeFamily
+      ? [activeFamily.light, activeFamily.dark].filter((d): d is ThemeDefinition => d !== undefined)
+      : offered;
+
+    // `?? theme` (the active theme), never a "light"/"dark" literal: with an open
+    // registry those names may not exist at all in this app.
+    const lightTheme: ThemeName = pickByDarkness(scope, false) ?? theme;
+    const darkTheme: ThemeName = pickByDarkness(scope, true) ?? theme;
+
+    // The scheme the user last chose, so dark → a light-only family → a
+    // two-scheme family lands on dark again (mirrors the provider's `setFamily`).
+    // Remembered together with the theme it produced: once something else changes
+    // the theme (another control calling `setTheme`), the memory no longer applies.
+    const intendedSchemeRef = useRef<{ scheme: ThemeScheme; theme: ThemeName } | undefined>(
+      undefined,
+    );
+
     // Hydrate the "system" choice from localStorage and apply it on mount —
     // uncontrolled mode only. Controlled mode's "system" state comes from the
     // `preference` prop and never touches this component's own storage key.
@@ -195,6 +235,90 @@ export const ThemeSwitcher = forwardRef<HTMLButtonElement, ThemeSwitcherProps>(
     }, [switchTheme, darkTheme, lightTheme, isControlled, onPreferenceChange]);
 
     const TriggerIcon = isSystem ? Monitor : isDark(resolvedTheme) ? Moon : Sun;
+
+    // ---- Family layout (≥2 declared families): family group + scheme group ----
+    if (activeFamily) {
+      const activeScheme = activeDefinition;
+      const remembered = intendedSchemeRef.current;
+      const intended =
+        remembered && remembered.theme === resolvedTheme
+          ? remembered.scheme
+          : activeScheme
+            ? themeSchemeOf(activeScheme)
+            : "light";
+      const pickFamily = (familyId: string) => {
+        // System re-resolves against the OS immediately on a family change
+        // instead of waiting for the next `change` event.
+        const scheme: ThemeScheme = isSystem ? (prefersDark() ? "dark" : "light") : intended;
+        const next = resolveThemeVariant(families, familyId, scheme);
+        if (next === undefined) return;
+        intendedSchemeRef.current = { scheme: intended, theme: next };
+        if (isSystem) switchTheme(next);
+        else pickTheme(next);
+      };
+      const pickScheme = (value: string) => {
+        if (value === "system") {
+          pickSystem();
+          return;
+        }
+        const scheme = value as ThemeScheme;
+        const next = activeFamily[scheme]?.value;
+        if (next === undefined) return;
+        intendedSchemeRef.current = { scheme, theme: next };
+        pickTheme(next);
+      };
+      const schemeValue = isSystem ? "system" : activeScheme ? themeSchemeOf(activeScheme) : "";
+
+      return (
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <Button
+              ref={ref}
+              variant="outline"
+              size={ICON_SIZE[size]}
+              aria-label={t("ui.themeSwitcher.theme")}
+              className={className}
+              {...props}
+            >
+              <TriggerIcon />
+            </Button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end">
+            <DropdownMenuLabel>{t("ui.themeSwitcher.theme")}</DropdownMenuLabel>
+            <DropdownMenuRadioGroup value={activeFamily.id} onValueChange={pickFamily}>
+              {families.map((f) => (
+                <DropdownMenuRadioItem key={f.id} value={f.id}>
+                  {f.label}
+                </DropdownMenuRadioItem>
+              ))}
+            </DropdownMenuRadioGroup>
+            {activeFamily.schemes.length === 2 ? (
+              <>
+                <DropdownMenuSeparator />
+                <DropdownMenuLabel>{t("ui.themeSwitcher.mode")}</DropdownMenuLabel>
+                <DropdownMenuRadioGroup value={schemeValue} onValueChange={pickScheme}>
+                  <DropdownMenuRadioItem value="light">
+                    <Sun aria-hidden="true" />
+                    {t("ui.themeSwitcher.light")}
+                  </DropdownMenuRadioItem>
+                  <DropdownMenuRadioItem value="dark">
+                    <Moon aria-hidden="true" />
+                    {t("ui.themeSwitcher.dark")}
+                  </DropdownMenuRadioItem>
+                  {showSystem ? (
+                    <DropdownMenuRadioItem value="system">
+                      <Monitor aria-hidden="true" />
+                      {t("ui.themeSwitcher.system")}
+                    </DropdownMenuRadioItem>
+                  ) : null}
+                </DropdownMenuRadioGroup>
+              </>
+            ) : null}
+          </DropdownMenuContent>
+        </DropdownMenu>
+      );
+    }
+
     const useDropdown = mode === "dropdown" || (mode === "auto" && safeThemes.length > 2);
 
     // ---- Dropdown mode (>2 themes) ----
@@ -206,7 +330,7 @@ export const ThemeSwitcher = forwardRef<HTMLButtonElement, ThemeSwitcherProps>(
               ref={ref}
               variant="outline"
               size={ICON_SIZE[size]}
-              aria-label="Theme"
+              aria-label={t("ui.themeSwitcher.theme")}
               className={className}
               {...props}
             >
@@ -218,14 +342,14 @@ export const ThemeSwitcher = forwardRef<HTMLButtonElement, ThemeSwitcherProps>(
               <DropdownMenuItem onSelect={() => pickSystem()}>
                 <Monitor />
                 <span>{t("ui.themeSwitcher.system")}</span>
-                {isSystem ? <Check className="ml-auto" /> : null}
+                {isSystem ? <Check className="ms-auto" /> : null}
               </DropdownMenuItem>
             ) : null}
             {offered.map((d) => (
               <DropdownMenuItem key={d.value} onSelect={() => pickTheme(d.value)}>
                 {d.dark ? <Moon /> : <Sun />}
                 <span>{d.label}</span>
-                {!isSystem && resolvedTheme === d.value ? <Check className="ml-auto" /> : null}
+                {!isSystem && resolvedTheme === d.value ? <Check className="ms-auto" /> : null}
               </DropdownMenuItem>
             ))}
           </DropdownMenuContent>

package/src/components/timeline/timeline.tsx

@@ -15,9 +15,6 @@
  *     parts. Keeps the editor-facing `done|active|pending` API unchanged by
  *     mapping in via `fromTimelineStatus` at the boundary.
  *
- * Fork-prevention: a Timeline re-implementation outside this folder fails
- * `pnpm timeline-fork:check` (scripts/check-timeline-fork.mjs).
- *
  * Deliberately NOT on this rail (a different grammar, not an oversight —
  * RM-014, #133): `RevisionTimeline` (@elabs-ai/components-ui). Its rail is a
  * multi-lane commit DAG whose node colour is LANE IDENTITY (the chart ramp),

package/src/components/toggle/toggle.tsx

@@ -21,7 +21,7 @@ export const toggleVariants = cva(
   // asChild wrapper overwrites data-state="on" with "closed" — aria-pressed
   // (Toggle) and aria-checked (ToggleGroupItem) are set by the toggle primitive
   // alone and survive the merge. (#214)
-  "inline-flex items-center justify-center gap-2 rounded-md text-sm font-medium transition-colors duration-fast ease-standard hover:bg-muted hover:text-muted-foreground focus-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:pointer-events-none disabled:opacity-50 data-[state=on]:bg-accent data-[state=on]:text-accent-foreground data-[state=on]:font-semibold aria-pressed:bg-accent aria-pressed:text-accent-foreground aria-pressed:font-semibold aria-checked:bg-accent aria-checked:text-accent-foreground aria-checked:font-semibold [&_svg]:size-4 [&_svg]:shrink-0",
+  "inline-flex items-center justify-center gap-2 rounded-control text-body font-control transition-colors duration-fast ease-standard hover:bg-muted hover:text-muted-foreground focus-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:pointer-events-none disabled:opacity-50 data-[state=on]:bg-accent data-[state=on]:text-accent-foreground data-[state=on]:font-semibold aria-pressed:bg-accent aria-pressed:text-accent-foreground aria-pressed:font-semibold aria-checked:bg-accent aria-checked:text-accent-foreground aria-checked:font-semibold [&_svg]:size-4 [&_svg]:shrink-0",
   {
     variants: {
       variant: {
@@ -44,7 +44,11 @@ export const toggleVariants = cva(
         segmented:
           "border-0 bg-transparent text-muted-foreground hover:bg-transparent hover:text-foreground aria-checked:bg-surface-elevated aria-checked:text-foreground aria-checked:font-medium aria-checked:shadow-sm aria-pressed:bg-surface-elevated aria-pressed:text-foreground aria-pressed:font-medium aria-pressed:shadow-sm data-[state=on]:bg-surface-elevated data-[state=on]:text-foreground data-[state=on]:font-medium data-[state=on]:shadow-sm",
       },
-      size: { default: "h-9 px-2.5 min-w-9", sm: "h-8 px-2 min-w-8", lg: "h-10 px-3 min-w-10" },
+      size: {
+        default: "h-control px-2.5 min-w-control",
+        sm: "h-control-sm px-2 min-w-control-sm",
+        lg: "h-control-lg px-3 min-w-control-lg",
+      },
     },
     defaultVariants: { variant: "default", size: "default" },
   },
@@ -57,6 +61,7 @@ export const Toggle = forwardRef<
   return (
     <TogglePrimitive.Root
       ref={ref}
+      data-slot="toggle"
       className={cn(toggleVariants({ variant, size }), className)}
       {...props}
     />

package/src/components/toggle-group/toggle-group.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import {
   createContext,
   forwardRef,

package/src/components/tooltip/tooltip.tsx

@@ -14,9 +14,10 @@ export const TooltipContent = forwardRef<
     <TooltipPrimitive.Portal>
       <TooltipPrimitive.Content
         ref={ref}
+        data-slot="tooltip-content"
         sideOffset={sideOffset}
         className={cn(
-          "z-50 overflow-hidden rounded-md bg-foreground px-2.5 py-1.5 text-xs text-background shadow-md",
+          "z-50 overflow-hidden rounded-md bg-foreground px-2.5 py-1.5 text-meta text-background shadow-md",
           "data-[state=delayed-open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=delayed-open]:fade-in-0 data-[state=delayed-open]:zoom-in-95",
           className,
         )}

package/src/components/top-nav/top-nav.tsx

@@ -17,7 +17,7 @@ export const TopNav = forwardRef<HTMLElement, TopNavProps>(function TopNav(
     <header
       ref={ref}
       className={cn(
-        "sticky top-0 z-30 flex h-14 items-center gap-4 border-b bg-surface-elevated/80 px-4 backdrop-blur",
+        "sticky top-0 z-30 flex h-header items-center gap-4 border-b bg-surface-elevated/80 px-4 backdrop-blur",
         className,
       )}
       {...props}

package/src/components/transfer/transfer.tsx

@@ -18,6 +18,7 @@ import { Card, CardContent, CardHeader, CardTitle } from "../card";
 import { Checkbox } from "../checkbox";
 import { Input } from "../input";
 import { ScrollArea } from "../scroll-area";
+import { useLocale } from "../locale-provider";
 
 // ─── Public types ─────────────────────────────────────────────────────────────
 
@@ -87,6 +88,7 @@ function TransferPanel({
   titleId,
   rowIdBase,
 }: PanelProps) {
+  const { t } = useLocale();
   // When a search is active, filter visible items; move operations affect VISIBLE enabled items.
   const visibleItems = useMemo(() => {
     if (!searchQuery) return items;
@@ -109,10 +111,12 @@ function TransferPanel({
           <Checkbox
             checked={someChecked ? "indeterminate" : allChecked}
             onCheckedChange={(v) => onCheckAll(v === true)}
-            aria-label={`Select all in ${typeof title === "string" ? title : "panel"}`}
+            aria-label={t("ui.transfer.selectAllIn", {
+              title: typeof title === "string" ? title : t("ui.transfer.panelFallback"),
+            })}
             disabled={enabledVisible.length === 0}
           />
-          <CardTitle id={titleId} className="text-sm">
+          <CardTitle id={titleId} className="text-body">
             {title}
           </CardTitle>
         </div>
@@ -124,15 +128,17 @@ function TransferPanel({
       {showSearch && (
         <div className="px-3 pb-2">
           <label htmlFor={searchInputId} className="sr-only">
-            Search {typeof title === "string" ? title : "items"}
+            {t("ui.transfer.searchIn", {
+              title: typeof title === "string" ? title : t("ui.transfer.itemsFallback"),
+            })}
           </label>
           <Input
             id={searchInputId}
             type="search"
-            placeholder="Search…"
+            placeholder={t("ui.transfer.searchPlaceholder")}
             value={searchQuery}
             onChange={(e) => onSearchChange(e.target.value)}
-            className="h-7 text-xs"
+            className="h-7 text-meta"
           />
         </div>
       )}
@@ -140,8 +146,8 @@ function TransferPanel({
       <CardContent className="flex-1 overflow-hidden p-0">
         <ScrollArea className="h-full min-h-[200px]">
           {visibleItems.length === 0 ? (
-            <p className="flex h-[200px] items-center justify-center text-sm text-muted-foreground">
-              No items
+            <p className="flex h-[200px] items-center justify-center text-body text-muted-foreground">
+              {t("ui.transfer.empty")}
             </p>
           ) : (
             <ul role="list" className="flex flex-col py-1">
@@ -156,7 +162,7 @@ function TransferPanel({
                   <li
                     key={item.value}
                     className={cn(
-                      "flex select-none items-center gap-2 px-3 py-1.5 text-sm",
+                      "flex select-none items-center gap-2 px-3 py-1.5 text-body",
                       "hover:bg-accent hover:text-accent-foreground",
                       item.disabled && "opacity-50 hover:bg-transparent hover:text-foreground",
                     )}
@@ -198,13 +204,18 @@ export const Transfer = forwardRef<HTMLDivElement, TransferProps>(function Trans
     defaultTargetKeys,
     onChange,
     showSearch = false,
-    titles = ["Source", "Target"],
+    titles,
     renderItem = (item) => item.label,
     className,
     ...props
   },
   ref,
 ) {
+  const { t } = useLocale();
+  const resolvedTitles: [ReactNode, ReactNode] = titles ?? [
+    t("ui.transfer.defaultSourceTitle"),
+    t("ui.transfer.defaultTargetTitle"),
+  ];
   const isControlled = controlledTargetKeys !== undefined;
 
   // Uncontrolled internal state
@@ -273,13 +284,13 @@ export const Transfer = forwardRef<HTMLDivElement, TransferProps>(function Trans
     );
     if (toMove.size === 0) return;
     applyMove([...targetKeys, ...toMove]);
-    setAnnouncement(`${toMove.size} item${toMove.size === 1 ? "" : "s"} moved to the target list.`);
+    setAnnouncement(t("ui.transfer.movedToTarget", { count: toMove.size }));
     setSourceChecked((prev) => {
       const next = new Set(prev);
       toMove.forEach((v) => next.delete(v));
       return next;
     });
-  }, [sourceChecked, dataSource, targetKeys, targetSet, applyMove]);
+  }, [sourceChecked, dataSource, targetKeys, targetSet, applyMove, t]);
 
   /** Move ALL visible enabled source items → target */
   const handleMoveAllRight = useCallback(() => {
@@ -290,11 +301,9 @@ export const Transfer = forwardRef<HTMLDivElement, TransferProps>(function Trans
     if (toAdd.length === 0) return;
     const next = [...new Set([...targetKeys, ...toAdd])];
     applyMove(next);
-    setAnnouncement(
-      `${toAdd.length} item${toAdd.length === 1 ? "" : "s"} moved to the target list.`,
-    );
+    setAnnouncement(t("ui.transfer.movedToTarget", { count: toAdd.length }));
     setSourceChecked(new Set());
-  }, [visibleSourceEnabled, targetKeys, applyMove]);
+  }, [visibleSourceEnabled, targetKeys, applyMove, t]);
 
   /** Move target-panel checked items → source */
   const handleMoveCheckedLeft = useCallback(() => {
@@ -306,26 +315,22 @@ export const Transfer = forwardRef<HTMLDivElement, TransferProps>(function Trans
     );
     if (toRemove.size === 0) return;
     applyMove(targetKeys.filter((k) => !toRemove.has(k)));
-    setAnnouncement(
-      `${toRemove.size} item${toRemove.size === 1 ? "" : "s"} moved to the source list.`,
-    );
+    setAnnouncement(t("ui.transfer.movedToSource", { count: toRemove.size }));
     setTargetChecked((prev) => {
       const next = new Set(prev);
       toRemove.forEach((v) => next.delete(v));
       return next;
     });
-  }, [targetChecked, dataSource, targetKeys, targetSet, applyMove]);
+  }, [targetChecked, dataSource, targetKeys, targetSet, applyMove, t]);
 
   /** Move ALL visible enabled target items → source */
   const handleMoveAllLeft = useCallback(() => {
     const toRemove = new Set(visibleTargetEnabled.map((it) => it.value));
     if (toRemove.size === 0) return;
     applyMove(targetKeys.filter((k) => !toRemove.has(k)));
-    setAnnouncement(
-      `${toRemove.size} item${toRemove.size === 1 ? "" : "s"} moved to the source list.`,
-    );
+    setAnnouncement(t("ui.transfer.movedToSource", { count: toRemove.size }));
     setTargetChecked(new Set());
-  }, [visibleTargetEnabled, targetKeys, applyMove]);
+  }, [visibleTargetEnabled, targetKeys, applyMove, t]);
 
   // ── Per-panel check handlers ──────────────────────────────────────────────
 
@@ -402,7 +407,7 @@ export const Transfer = forwardRef<HTMLDivElement, TransferProps>(function Trans
 
       {/* ── Source panel ─────────────────────────────── */}
       <TransferPanel
-        title={titles[0]}
+        title={resolvedTitles[0]}
         items={sourceItems}
         checked={sourceChecked}
         onCheckItem={handleSourceCheckItem}
@@ -420,12 +425,12 @@ export const Transfer = forwardRef<HTMLDivElement, TransferProps>(function Trans
       <div
         className="flex flex-col items-center justify-center gap-1"
         role="group"
-        aria-label="Move controls"
+        aria-label={t("ui.transfer.moveControls")}
       >
         <Button
           variant="outline"
           size="icon-sm"
-          aria-label="Move selected right"
+          aria-label={t("ui.transfer.moveSelectedRight")}
           disabled={!canMoveCheckedRight}
           onClick={handleMoveCheckedRight}
         >
@@ -434,7 +439,7 @@ export const Transfer = forwardRef<HTMLDivElement, TransferProps>(function Trans
         <Button
           variant="outline"
           size="icon-sm"
-          aria-label="Move all right"
+          aria-label={t("ui.transfer.moveAllRight")}
           disabled={!canMoveAllRight}
           onClick={handleMoveAllRight}
         >
@@ -443,7 +448,7 @@ export const Transfer = forwardRef<HTMLDivElement, TransferProps>(function Trans
         <Button
           variant="outline"
           size="icon-sm"
-          aria-label="Move selected left"
+          aria-label={t("ui.transfer.moveSelectedLeft")}
           disabled={!canMoveCheckedLeft}
           onClick={handleMoveCheckedLeft}
           className="mt-2"
@@ -453,7 +458,7 @@ export const Transfer = forwardRef<HTMLDivElement, TransferProps>(function Trans
         <Button
           variant="outline"
           size="icon-sm"
-          aria-label="Move all left"
+          aria-label={t("ui.transfer.moveAllLeft")}
           disabled={!canMoveAllLeft}
           onClick={handleMoveAllLeft}
         >
@@ -463,7 +468,7 @@ export const Transfer = forwardRef<HTMLDivElement, TransferProps>(function Trans
 
       {/* ── Target panel ─────────────────────────────── */}
       <TransferPanel
-        title={titles[1]}
+        title={resolvedTitles[1]}
         items={targetItems}
         checked={targetChecked}
         onCheckItem={handleTargetCheckItem}