@elabs-ai/components-ui 4.0.0

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

@@ -0,0 +1,79 @@
+import { describe, expect, it, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { ColorPicker, COLOR_TOKENS } from "./color-picker";
+
+describe("ColorPicker", () => {
+  it("renders a trigger button with default aria-label", () => {
+    render(<ColorPicker defaultValue="chart-1" />);
+    expect(screen.getByRole("button", { name: "Pick color" })).toBeInTheDocument();
+  });
+
+  it("accepts a custom aria-label on the trigger", () => {
+    render(<ColorPicker defaultValue="primary" aria-label="Chart color" />);
+    expect(screen.getByRole("button", { name: "Chart color" })).toBeInTheDocument();
+  });
+
+  it("opens popover on trigger click and shows swatches", async () => {
+    render(<ColorPicker defaultValue="chart-1" />);
+    await userEvent.click(screen.getByRole("button", { name: "Pick color" }));
+    expect(screen.getByRole("radiogroup", { name: "Color swatches" })).toBeInTheDocument();
+    // Each default token should render as a radio
+    expect(screen.getAllByRole("radio").length).toBe(COLOR_TOKENS.length);
+  });
+
+  it("marks the current value as checked", async () => {
+    render(<ColorPicker defaultValue="primary" />);
+    await userEvent.click(screen.getByRole("button", { name: "Pick color" }));
+    expect(screen.getByRole("radio", { name: "primary" })).toHaveAttribute("aria-checked", "true");
+  });
+
+  it("calls onValueChange and closes popover when a swatch is selected", async () => {
+    const onValueChange = vi.fn();
+    render(<ColorPicker defaultValue="chart-1" onValueChange={onValueChange} />);
+    await userEvent.click(screen.getByRole("button", { name: "Pick color" }));
+    await userEvent.click(screen.getByRole("radio", { name: "chart-2" }));
+    expect(onValueChange).toHaveBeenCalledWith("chart-2");
+    // Popover should close — radiogroup no longer visible
+    expect(screen.queryByRole("radiogroup")).not.toBeInTheDocument();
+  });
+
+  it("does not render custom hex section by default", async () => {
+    render(<ColorPicker defaultValue="chart-1" />);
+    await userEvent.click(screen.getByRole("button", { name: "Pick color" }));
+    expect(screen.queryByLabelText("Custom hex color")).not.toBeInTheDocument();
+  });
+
+  it("renders custom hex input when allowCustom=true", async () => {
+    render(<ColorPicker defaultValue="chart-1" allowCustom />);
+    await userEvent.click(screen.getByRole("button", { name: "Pick color" }));
+    expect(screen.getByLabelText("Custom hex color")).toBeInTheDocument();
+  });
+
+  it("applies a valid hex value from the custom input", async () => {
+    const onValueChange = vi.fn();
+    render(<ColorPicker defaultValue="chart-1" allowCustom onValueChange={onValueChange} />);
+    await userEvent.click(screen.getByRole("button", { name: "Pick color" }));
+    const hexInput = screen.getByLabelText("Custom hex color");
+    await userEvent.type(hexInput, "#ff0000");
+    await userEvent.click(screen.getByRole("button", { name: "Apply" }));
+    expect(onValueChange).toHaveBeenCalledWith("#ff0000");
+  });
+
+  it("respects a custom swatches subset", async () => {
+    render(<ColorPicker defaultValue="success" swatches={["success", "warning"]} />);
+    await userEvent.click(screen.getByRole("button", { name: "Pick color" }));
+    expect(screen.getAllByRole("radio").length).toBe(2);
+    expect(screen.getByRole("radio", { name: "success" })).toBeInTheDocument();
+    expect(screen.getByRole("radio", { name: "warning" })).toBeInTheDocument();
+  });
+
+  it("uses only bg-* token classes for swatches (no raw hex in class)", async () => {
+    render(<ColorPicker defaultValue="chart-1" />);
+    await userEvent.click(screen.getByRole("button", { name: "Pick color" }));
+    const radios = screen.getAllByRole("radio");
+    for (const radio of radios) {
+      expect(radio.className).not.toMatch(/#[0-9a-fA-F]/);
+    }
+  });
+});

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

@@ -0,0 +1,341 @@
+// a2ui.exposed: yes
+import {
+  forwardRef,
+  useCallback,
+  useRef,
+  useState,
+  type ButtonHTMLAttributes,
+  type HTMLAttributes,
+  type KeyboardEvent,
+} from "react";
+import { cn } from "../../lib/cn";
+import { Popover, PopoverContent, PopoverTrigger } from "../popover";
+
+// ---------------------------------------------------------------------------
+// Token vocabulary
+// ---------------------------------------------------------------------------
+
+/**
+ * The semantic color token names that ColorPicker understands as "safe" values.
+ * These map 1-to-1 with Tailwind utilities backed by CSS variables so they
+ * remain theme-aware at runtime.
+ */
+export type ColorToken =
+  | "primary"
+  | "secondary"
+  | "destructive"
+  | "success"
+  | "warning"
+  | "info"
+  | "chart-1"
+  | "chart-2"
+  | "chart-3"
+  | "chart-4"
+  | "chart-5"
+  | "chart-6"
+  | "chart-7"
+  | "chart-8"
+  | "chart-9"
+  | "chart-10"
+  | "chart-11"
+  | "chart-12";
+
+/** All recognised token names in display order. */
+export const COLOR_TOKENS: ColorToken[] = [
+  "chart-1",
+  "chart-2",
+  "chart-3",
+  "chart-4",
+  "chart-5",
+  "chart-6",
+  "chart-7",
+  "chart-8",
+  "chart-9",
+  "chart-10",
+  "chart-11",
+  "chart-12",
+  "primary",
+  "secondary",
+  "destructive",
+  "success",
+  "warning",
+  "info",
+];
+
+/**
+ * Map a ColorToken → the Tailwind bg-* utility class that renders it.
+ * These classes must be present as complete strings so Tailwind's JIT scanner
+ * can detect them statically.
+ */
+const TOKEN_BG: Record<ColorToken, string> = {
+  "chart-1": "bg-chart-1",
+  "chart-2": "bg-chart-2",
+  "chart-3": "bg-chart-3",
+  "chart-4": "bg-chart-4",
+  "chart-5": "bg-chart-5",
+  "chart-6": "bg-chart-6",
+  "chart-7": "bg-chart-7",
+  "chart-8": "bg-chart-8",
+  "chart-9": "bg-chart-9",
+  "chart-10": "bg-chart-10",
+  "chart-11": "bg-chart-11",
+  "chart-12": "bg-chart-12",
+  primary: "bg-primary",
+  secondary: "bg-secondary",
+  destructive: "bg-destructive",
+  success: "bg-success",
+  warning: "bg-warning",
+  info: "bg-info",
+};
+
+function isColorToken(v: string): v is ColorToken {
+  return Object.prototype.hasOwnProperty.call(TOKEN_BG, v);
+}
+
+// ---------------------------------------------------------------------------
+// Sub-component: individual swatch button
+// ---------------------------------------------------------------------------
+
+interface SwatchProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "onSelect"> {
+  token: ColorToken;
+  selected: boolean;
+  onSelect: (token: ColorToken) => void;
+}
+
+const Swatch = forwardRef<HTMLButtonElement, SwatchProps>(function Swatch(
+  { token, selected, onSelect, className, ...props },
+  ref,
+) {
+  return (
+    <button
+      ref={ref}
+      type="button"
+      role="radio"
+      aria-checked={selected}
+      aria-label={token}
+      onClick={() => onSelect(token)}
+      className={cn(
+        "size-7 rounded-md border-2 transition-[border-color,box-shadow] duration-fast",
+        TOKEN_BG[token],
+        selected
+          ? "border-foreground ring-2 ring-ring ring-offset-1 ring-offset-background"
+          : "border-transparent hover:border-foreground/40",
+        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
+        className,
+      )}
+      {...props}
+    />
+  );
+});
+
+// ---------------------------------------------------------------------------
+// Trigger swatch preview
+// ---------------------------------------------------------------------------
+
+interface TriggerSwatchProps {
+  value: string;
+  className?: string;
+}
+
+function TriggerSwatch({ value, className }: TriggerSwatchProps) {
+  const bgClass = isColorToken(value) ? TOKEN_BG[value] : undefined;
+  return (
+    <span
+      className={cn("inline-block size-4 rounded-sm border border-border", bgClass, className)}
+      // When a raw hex value is supplied, use inline style — the only safe
+      // place for a non-token color (isolated to this preview span).
+      style={!bgClass ? { backgroundColor: value } : undefined}
+    />
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Main component
+// ---------------------------------------------------------------------------
+
+export interface ColorPickerProps extends Omit<HTMLAttributes<HTMLDivElement>, "onChange"> {
+  /**
+   * Controlled value — a `ColorToken` name (preferred, theme-aware) or a raw
+   * hex string (only when `allowCustom` is true).
+   */
+  value?: ColorToken | string;
+  /** Uncontrolled default value. */
+  defaultValue?: ColorToken | string;
+  /** Called when the selected color changes. */
+  onValueChange?: (value: ColorToken | string) => void;
+  /**
+   * Swatches to display. Defaults to all chart + status tokens.
+   * Accepts any subset of `ColorToken`.
+   */
+  swatches?: ColorToken[];
+  /**
+   * When true, a free-form hex input is shown below the swatches.
+   * NOTE: custom hex values are NOT theme-aware — they will not adapt when
+   * the active theme changes. Prefer token values for all theme-safe UI.
+   */
+  allowCustom?: boolean;
+  /** aria-label for the trigger button. Defaults to "Pick color". */
+  "aria-label"?: string;
+}
+
+/**
+ * ColorPicker — a token-safe swatch picker backed by a Popover.
+ *
+ * The default value type is a `ColorToken` (a semantic CSS variable name),
+ * not a hex string. This ensures the chosen color adapts to the active theme.
+ * Raw hex is available opt-in via `allowCustom` — see the prop docs.
+ *
+ * Swatch group uses `role="radiogroup"` with arrow-key navigation.
+ */
+export const ColorPicker = forwardRef<HTMLDivElement, ColorPickerProps>(function ColorPicker(
+  {
+    value: valueProp,
+    defaultValue,
+    onValueChange,
+    swatches = COLOR_TOKENS,
+    allowCustom = false,
+    "aria-label": ariaLabel = "Pick color",
+    className,
+    ...props
+  },
+  ref,
+) {
+  const isControlled = valueProp !== undefined;
+  const [internalValue, setInternalValue] = useState<ColorToken | string>(
+    defaultValue ?? "chart-1",
+  );
+  const [customHex, setCustomHex] = useState("");
+  const [open, setOpen] = useState(false);
+
+  const current = isControlled ? (valueProp ?? "") : internalValue;
+
+  const commit = useCallback(
+    (next: ColorToken | string) => {
+      if (!isControlled) setInternalValue(next);
+      onValueChange?.(next);
+    },
+    [isControlled, onValueChange],
+  );
+
+  const handleSwatchSelect = useCallback(
+    (token: ColorToken) => {
+      commit(token);
+      setOpen(false);
+    },
+    [commit],
+  );
+
+  const handleCustomSubmit = useCallback(() => {
+    const hex = customHex.trim();
+    if (/^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.test(hex)) {
+      commit(hex);
+      setOpen(false);
+    }
+  }, [customHex, commit]);
+
+  // Arrow-key navigation within the radiogroup
+  const groupRef = useRef<HTMLDivElement>(null);
+  const handleGroupKeyDown = useCallback((e: KeyboardEvent<HTMLDivElement>) => {
+    const buttons = groupRef.current
+      ? Array.from(groupRef.current.querySelectorAll<HTMLButtonElement>("[role=radio]"))
+      : [];
+    if (!buttons.length) return;
+    const focused = document.activeElement as HTMLButtonElement;
+    const idx = buttons.indexOf(focused);
+    if (idx === -1) return;
+
+    if (e.key === "ArrowRight" || e.key === "ArrowDown") {
+      e.preventDefault();
+      buttons[(idx + 1) % buttons.length]?.focus();
+    } else if (e.key === "ArrowLeft" || e.key === "ArrowUp") {
+      e.preventDefault();
+      buttons[(idx - 1 + buttons.length) % buttons.length]?.focus();
+    }
+  }, []);
+
+  return (
+    <div ref={ref} className={cn("inline-flex", className)} {...props}>
+      <Popover open={open} onOpenChange={setOpen}>
+        <PopoverTrigger asChild>
+          <button
+            type="button"
+            aria-label={ariaLabel}
+            aria-haspopup="dialog"
+            aria-expanded={open}
+            className={cn(
+              "inline-flex items-center gap-2 rounded-md border border-input bg-background px-3 py-1.5 text-sm shadow-sm",
+              "transition-[color,box-shadow] duration-fast",
+              "hover:bg-accent hover:text-accent-foreground",
+              "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
+              "disabled:pointer-events-none disabled:opacity-50",
+            )}
+          >
+            <TriggerSwatch value={current} />
+            <span className="text-muted-foreground">{current || "None"}</span>
+          </button>
+        </PopoverTrigger>
+
+        <PopoverContent className="w-auto p-3" align="start">
+          <div
+            ref={groupRef}
+            role="radiogroup"
+            aria-label="Color swatches"
+            className="flex flex-wrap gap-1.5"
+            onKeyDown={handleGroupKeyDown}
+          >
+            {swatches.map((token) => (
+              <Swatch
+                key={token}
+                token={token}
+                selected={current === token}
+                onSelect={handleSwatchSelect}
+              />
+            ))}
+          </div>
+
+          {allowCustom && (
+            <div className="mt-3 border-t border-border pt-3">
+              {/* Custom hex is NOT theme-aware — it will not adapt to theme changes. */}
+              <p className="mb-1.5 text-xs text-muted-foreground">
+                Custom hex <span className="text-warning">(not theme-aware)</span>
+              </p>
+              <div className="flex gap-2">
+                <input
+                  type="text"
+                  value={customHex}
+                  placeholder="#3b82f6"
+                  maxLength={7}
+                  spellCheck={false}
+                  aria-label="Custom hex color"
+                  onChange={(e) => setCustomHex(e.target.value)}
+                  onKeyDown={(e) => {
+                    if (e.key === "Enter") {
+                      e.preventDefault();
+                      handleCustomSubmit();
+                    }
+                  }}
+                  className={cn(
+                    "h-8 w-28 rounded-md border border-input bg-background px-2 text-sm",
+                    "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
+                    "placeholder:text-muted-foreground",
+                  )}
+                />
+                <button
+                  type="button"
+                  onClick={handleCustomSubmit}
+                  className={cn(
+                    "h-8 rounded-md border border-input bg-background px-2 text-sm",
+                    "hover:bg-accent hover:text-accent-foreground",
+                    "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
+                  )}
+                >
+                  Apply
+                </button>
+              </div>
+            </div>
+          )}
+        </PopoverContent>
+      </Popover>
+    </div>
+  );
+});

package/src/components/color-picker/index.ts

@@ -0,0 +1 @@
+export { ColorPicker, COLOR_TOKENS, type ColorPickerProps, type ColorToken } from "./color-picker";

package/src/components/combobox/combobox.stories.tsx

@@ -0,0 +1,154 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, within } from "storybook/test";
+import { Combobox } from "./combobox";
+const meta = {
+  title: "Forms/Combobox",
+  component: Combobox,
+  tags: ["autodocs"],
+  argTypes: {
+    options: {
+      description: "Array of `{ label, value }` options.",
+      control: false,
+      table: { category: "Content" },
+    },
+    value: {
+      description: "Controlled selected value.",
+      control: "text",
+      table: { category: "State" },
+    },
+    placeholder: {
+      description: "Text shown in the trigger when no option is selected.",
+      control: "text",
+      table: { category: "Content" },
+    },
+    searchPlaceholder: {
+      description: "Placeholder inside the search input.",
+      control: "text",
+      table: { category: "Content" },
+    },
+    emptyText: {
+      description: "Message shown when the search yields no results.",
+      control: "text",
+      table: { category: "Content" },
+    },
+    onValueChange: {
+      description: "Called when the selected value changes.",
+      control: false,
+      table: { category: "Behavior" },
+    },
+    className: {
+      description: "Additional CSS classes applied to the trigger button.",
+      control: "text",
+      table: { category: "Appearance" },
+    },
+    disabled: {
+      description: "Disables the trigger and prevents the popover from opening.",
+      control: "boolean",
+      table: { category: "State" },
+    },
+    allowCustomValue: {
+      description:
+        "When true, typed text not present in options becomes a submittable value (#359).",
+      control: "boolean",
+      table: { category: "Behavior" },
+    },
+  },
+} satisfies Meta<typeof Combobox>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+export const Default: Story = {
+  args: {
+    options: [
+      { label: "Production", value: "prod" },
+      { label: "Staging", value: "staging" },
+      { label: "Development", value: "dev" },
+    ],
+    placeholder: "Select environment…",
+  },
+  // Opens the popover, confirms options appear, then picks "Staging".
+  play: async ({ canvas, canvasElement, userEvent }) => {
+    const trigger = canvas.getByRole("combobox");
+    await userEvent.click(trigger);
+    const body = within(canvasElement.ownerDocument.body);
+    const option = await body.findByRole("option", { name: "Staging" });
+    await expect(option).toBeInTheDocument();
+    await userEvent.click(option);
+    await expect(trigger).toHaveTextContent("Staging");
+  },
+};
+
+const ENVIRONMENTS = [
+  { label: "Production", value: "prod" },
+  { label: "Staging", value: "staging" },
+  { label: "Development", value: "dev" },
+];
+
+/** Enabled vs disabled, side by side (#343). */
+export const DisabledState: Story = {
+  name: "Disabled",
+  render: () => (
+    <div className="flex items-center gap-4">
+      <Combobox
+        aria-label="Environment (enabled)"
+        options={ENVIRONMENTS}
+        placeholder="Select environment…"
+      />
+      <Combobox
+        aria-label="Environment (disabled)"
+        options={ENVIRONMENTS}
+        placeholder="Select environment…"
+        disabled
+      />
+    </div>
+  ),
+  // The disabled trigger is a real native `disabled` button — a genuine
+  // pointer click can't even land on it (`pointer-events: none`, asserted by
+  // the browser itself), so there's nothing to open.
+  play: async ({ canvas }) => {
+    const [, disabledTrigger] = canvas.getAllByRole("combobox");
+    await expect(disabledTrigger).toBeDisabled();
+    await expect(canvas.queryByPlaceholderText("Search…")).not.toBeInTheDocument();
+  },
+};
+
+/**
+ * `aria-label` names the control's PURPOSE ("Session switcher"), independent
+ * of the selected value's own text (#347).
+ */
+export const AccessibleName: Story = {
+  args: {
+    options: ENVIRONMENTS,
+    value: "prod",
+    "aria-label": "Environment switcher",
+  },
+  play: async ({ canvas }) => {
+    const trigger = canvas.getByRole("combobox", { name: "Environment switcher" });
+    await expect(trigger).toHaveTextContent("Production");
+  },
+};
+
+/**
+ * `allowCustomValue` accepts free text alongside the suggested options — a
+ * value not in `options` is offered via a "Use…" suggestion, still filtered
+ * live as the user types (#359).
+ */
+export const AllowCustomValue: Story = {
+  name: "Allow custom value",
+  args: {
+    options: ENVIRONMENTS,
+    allowCustomValue: true,
+    placeholder: "Select or type an environment…",
+    "aria-label": "Environment (custom value allowed)",
+  },
+  play: async ({ canvas, canvasElement, userEvent }) => {
+    const trigger = canvas.getByRole("combobox");
+    await userEvent.click(trigger);
+    const body = within(canvasElement.ownerDocument.body);
+    const input = await body.findByPlaceholderText("Search…");
+    await userEvent.type(input, "Canary");
+    const customItem = await body.findByRole("option", { name: /use.*canary/i });
+    await expect(customItem).toBeInTheDocument();
+    await userEvent.click(customItem);
+    await expect(trigger).toHaveTextContent("Canary");
+  },
+};