@elabs-ai/components-ui 4.1.0 → 5.0.0

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 { Button, type ButtonProps } from "../button";
 import {
   DropdownMenu,
   DropdownMenuContent,
   DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuSeparator,
   DropdownMenuTrigger,
 } from "../dropdown-menu";
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "../tooltip";
@@ -46,6 +59,12 @@ export interface ThemeSwitcherProps extends Omit<HTMLAttributes<HTMLButtonElemen
   effect?: ThemeTransitionEffect;
   /** Control size. Default "default". */
   size?: ButtonSize;
+  /**
+   * The trigger button's variant. Default: `"outline"` for the dropdown forms and `"ghost"` for
+   * the two-theme toggle (today's behaviour). Pass `"ghost"` when the switcher sits in a row of
+   * borderless icon buttons — an app top bar — so it reads as one of them.
+   */
+  variant?: ButtonProps["variant"];
   /**
    * Controlled preference (#366). When set, the switcher derives its "current"
    * state — including "system" — from this prop instead of its own internal,
@@ -100,6 +119,7 @@ export const ThemeSwitcher = forwardRef<HTMLButtonElement, ThemeSwitcherProps>(
       showSystem = true,
       effect = "polygon",
       size = "default",
+      variant,
       preference,
       onPreferenceChange,
       className,
@@ -129,16 +149,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 +242,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={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) ----
@@ -204,9 +335,9 @@ export const ThemeSwitcher = forwardRef<HTMLButtonElement, ThemeSwitcherProps>(
           <DropdownMenuTrigger asChild>
             <Button
               ref={ref}
-              variant="outline"
+              variant={variant ?? "outline"}
               size={ICON_SIZE[size]}
-              aria-label="Theme"
+              aria-label={t("ui.themeSwitcher.theme")}
               className={className}
               {...props}
             >
@@ -218,14 +349,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>
@@ -266,7 +397,7 @@ export const ThemeSwitcher = forwardRef<HTMLButtonElement, ThemeSwitcherProps>(
           <TooltipTrigger asChild>
             <Button
               ref={ref}
-              variant="ghost"
+              variant={variant ?? "ghost"}
               size={ICON_SIZE[size]}
               aria-label={`Theme: ${roleLabel(current)}. Activate to switch to ${roleLabel(next)}.`}
               onClick={apply}

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/token-spotlight/index.ts

@@ -0,0 +1,11 @@
+export {
+  TokenSpotlight,
+  DEFAULT_TOKEN_SPOTLIGHT_LABELS,
+  TOKEN_SPOTLIGHT_SCAN_LIMIT,
+  resolveTokenDisplayValue,
+  resolveTokenMatchValue,
+  scanForConsumers,
+  type TokenSpotlightLabels,
+  type TokenSpotlightProps,
+  type TokenSpotlightToken,
+} from "./token-spotlight";

package/src/components/token-spotlight/token-spotlight.css

@@ -0,0 +1,32 @@
+/*
+ * TokenSpotlight — the outline pulse a hovered/focused chip draws on every element that
+ * consumes its token (RM-103, wave-4 ruling 20). Tokens only (`--ring`, `--t-fast`,
+ * `--ease-standard`); no HTML sink, no inline style — `data-token-consumer` is the only
+ * hook, added/removed by the component itself (precedent: `ambient-field.css`).
+ */
+@layer base {
+  [data-token-consumer] {
+    outline: 2px solid var(--ring);
+    outline-offset: 2px;
+    animation: brand-ui-token-consumer-pulse var(--t-fast) var(--ease-standard);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    :root:not([data-motion-pref="full"]) [data-token-consumer] {
+      animation: none;
+    }
+  }
+
+  [data-motion-pref="reduced"] [data-token-consumer] {
+    animation: none;
+  }
+
+  @keyframes brand-ui-token-consumer-pulse {
+    from {
+      outline-color: transparent;
+    }
+    to {
+      outline-color: var(--ring);
+    }
+  }
+}

package/src/components/token-spotlight/token-spotlight.stories.tsx

@@ -0,0 +1,161 @@
+import type { ComponentProps } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, userEvent, waitFor, within } from "storybook/test";
+import { TokenSpotlight, type TokenSpotlightToken } from "./token-spotlight";
+
+const TOKENS: TokenSpotlightToken[] = [
+  { token: "--primary", label: "Primary" },
+  { token: "--background", label: "Background" },
+  { token: "--border", label: "Border" },
+];
+
+/** A couple of real consumers so hovering a chip has something to find and outline. */
+function Demo(props: ComponentProps<typeof TokenSpotlight>) {
+  return (
+    <div className="flex flex-col gap-6 p-6">
+      <TokenSpotlight {...props} />
+      <div className="flex gap-4">
+        <button type="button" className="rounded-md bg-primary px-4 py-2 text-primary-foreground">
+          Uses --primary
+        </button>
+        <div className="rounded-md border border-border p-4 text-foreground">Uses --border</div>
+      </div>
+    </div>
+  );
+}
+
+const meta = {
+  title: "Display/TokenSpotlight",
+  component: TokenSpotlight,
+  parameters: { layout: "padded" },
+  tags: ["autodocs"],
+  args: { tokens: TOKENS },
+  render: (args) => <Demo {...args} />,
+} satisfies Meta<typeof TokenSpotlight>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+/** Hovering a chip sets `data-token-spotlight` on `<html>` and marks its consumers; moving off
+ * clears both. */
+export const HoverHighlightsConsumers: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const chip = canvas.getByText("--primary");
+    await userEvent.hover(chip);
+    await waitFor(() =>
+      expect(document.documentElement).toHaveAttribute("data-token-spotlight", "primary"),
+    );
+    const consumer = canvas.getByText("Uses --primary");
+    await waitFor(() => expect(consumer).toHaveAttribute("data-token-consumer", "primary"));
+    await userEvent.unhover(chip);
+    await waitFor(() =>
+      expect(document.documentElement).not.toHaveAttribute("data-token-spotlight"),
+    );
+    await expect(consumer).not.toHaveAttribute("data-token-consumer");
+  },
+};
+
+/** Keyboard focus on a chip does the same as hover — the spotlight is never mouse-only. */
+export const KeyboardFocus: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const chip = canvas.getByText("--primary").closest("button");
+    if (!chip) throw new Error("chip button not found");
+    chip.focus();
+    await waitFor(() =>
+      expect(document.documentElement).toHaveAttribute("data-token-spotlight", "primary"),
+    );
+    chip.blur();
+    await waitFor(() =>
+      expect(document.documentElement).not.toHaveAttribute("data-token-spotlight"),
+    );
+  },
+};
+
+/** Under reduced motion the outline still appears — CSS `animation: none` (`token-spotlight.css`)
+ * just removes the pulse. Asserted on the computed style directly (`animationName`), never on
+ * `document.getAnimations()`: an unrelated `transition-colors` on the outlined element is a real
+ * `CSSTransition` that legitimately runs for a few ms right after the attribute flips, and is not
+ * the pulse this story is about. */
+export const ReducedMotion: Story = {
+  globals: { motionPref: "reduced" },
+  render: (args) => (
+    <div data-motion-pref="reduced">
+      <Demo {...args} />
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const chip = canvas.getByText("--primary");
+    await userEvent.hover(chip);
+    const consumer = canvas.getByText("Uses --primary");
+    await waitFor(() => expect(consumer).toHaveAttribute("data-token-consumer", "primary"));
+    await waitFor(() => expect(getComputedStyle(consumer).animationName).toBe("none"));
+  },
+};
+
+/** Only elements that visibly PAINT the token are marked: a border counts only on a side with a
+ * width (every element carries `border-color: var(--border)` at width 0 from the base layer), and
+ * the text colour counts only on an element with its own text — not on a wrapper that merely
+ * inherits it. SVG shapes are reported as their `<svg>`. */
+export const OnlyRealConsumers: Story = {
+  args: {
+    tokens: [
+      { token: "--border", label: "Border" },
+      { token: "--foreground", label: "Foreground" },
+    ],
+  },
+  render: (args) => (
+    <div className="flex flex-col gap-6 p-6">
+      <TokenSpotlight {...args} />
+      <div className="flex gap-4">
+        <div className="rounded-md border border-border p-4">Bordered</div>
+        <div className="rounded-md p-4">No border</div>
+        <div data-testid="inherits-only" className="text-foreground">
+          <span className="text-foreground">Own text</span>
+        </div>
+      </div>
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const borderChip = canvas.getByText("--border");
+    await userEvent.hover(borderChip);
+    const bordered = canvas.getByText("Bordered");
+    await waitFor(() => expect(bordered).toHaveAttribute("data-token-consumer", "border"));
+    await expect(canvas.getByText("No border")).not.toHaveAttribute("data-token-consumer");
+    await userEvent.unhover(borderChip);
+    await waitFor(() => expect(bordered).not.toHaveAttribute("data-token-consumer"));
+
+    await userEvent.hover(canvas.getByText("--foreground"));
+    await waitFor(() =>
+      expect(canvas.getByText("Own text")).toHaveAttribute("data-token-consumer", "foreground"),
+    );
+    await expect(canvas.getByTestId("inherits-only")).not.toHaveAttribute("data-token-consumer");
+  },
+};
+
+/** Each chip shows the token’s resolved value in a readable form: colours as a rounded
+ * `oklch(L C H)` whatever colour space the CSS build emitted (never `lab()`), lengths such as
+ * `--radius` as px (never a raw `calc()`). Values are re-read when `data-theme` or
+ * `data-decoration` changes on `<html>`. */
+export const ResolvedValues: Story = {
+  args: {
+    tokens: [
+      { token: "--background", label: "Background" },
+      { token: "--primary", label: "Primary" },
+      { token: "--radius", label: "Radius" },
+    ],
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const valueOf = (token: string) =>
+      canvas.getByText(token).closest("button")?.querySelector(":scope > span:nth-of-type(2)")
+        ?.textContent ?? "";
+    await waitFor(() => expect(valueOf("--background")).toMatch(/^oklch\([\d.]+ [\d.]+ \d+\)$/));
+    await expect(valueOf("--primary")).toMatch(/^oklch\([\d.]+ [\d.]+ \d+\)$/);
+    await expect(valueOf("--radius")).toMatch(/^[\d.]+px$/);
+  },
+};