@elabs-ai/components-ui 4.0.0

package/src/components/scroll-area/index.ts

@@ -0,0 +1 @@
+export { ScrollArea, ScrollBar } from "./scroll-area";

package/src/components/scroll-area/scroll-area.stories.tsx

@@ -0,0 +1,45 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { ScrollArea } from "./scroll-area";
+const meta = {
+  title: "Display/ScrollArea",
+  component: ScrollArea,
+  tags: ["autodocs"],
+  argTypes: {
+    type: {
+      description: "Controls scrollbar visibility: `auto` (default), `always`, `scroll`, `hover`.",
+      control: { type: "select" },
+      options: ["auto", "always", "scroll", "hover"],
+      table: { category: "Behavior" },
+    },
+    scrollHideDelay: {
+      description:
+        "Duration (ms) before the scrollbar hides (applicable to `scroll` and `hover` types).",
+      control: "number",
+      table: { category: "Behavior" },
+    },
+    dir: {
+      description: "Reading direction — affects scrollbar placement.",
+      control: { type: "radio" },
+      options: ["ltr", "rtl"],
+      table: { category: "Behavior" },
+    },
+    className: {
+      description: "Extra Tailwind classes merged via cn() on the root.",
+      control: "text",
+      table: { category: "Appearance" },
+    },
+  },
+} satisfies Meta<typeof ScrollArea>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+export const Default: Story = {
+  render: () => (
+    <ScrollArea className="h-40 w-56 rounded-md border p-3">
+      <div className="space-y-2 text-body">
+        {Array.from({ length: 20 }).map((_, i) => (
+          <p key={i}>Row {i + 1}</p>
+        ))}
+      </div>
+    </ScrollArea>
+  ),
+};

package/src/components/scroll-area/scroll-area.tsx

@@ -0,0 +1,43 @@
+import { forwardRef, type ComponentPropsWithoutRef, type ElementRef } from "react";
+import * as ScrollAreaPrimitive from "@radix-ui/react-scroll-area";
+import { cn } from "../../lib/cn";
+
+export const ScrollArea = forwardRef<
+  ElementRef<typeof ScrollAreaPrimitive.Root>,
+  ComponentPropsWithoutRef<typeof ScrollAreaPrimitive.Root>
+>(function ScrollArea({ className, children, ...props }, ref) {
+  return (
+    <ScrollAreaPrimitive.Root
+      ref={ref}
+      className={cn("relative overflow-hidden", className)}
+      {...props}
+    >
+      <ScrollAreaPrimitive.Viewport className="size-full rounded-[inherit]">
+        {children}
+      </ScrollAreaPrimitive.Viewport>
+      <ScrollBar />
+      <ScrollAreaPrimitive.Corner />
+    </ScrollAreaPrimitive.Root>
+  );
+});
+
+export const ScrollBar = forwardRef<
+  ElementRef<typeof ScrollAreaPrimitive.ScrollAreaScrollbar>,
+  ComponentPropsWithoutRef<typeof ScrollAreaPrimitive.ScrollAreaScrollbar>
+>(function ScrollBar({ className, orientation = "vertical", ...props }, ref) {
+  return (
+    <ScrollAreaPrimitive.ScrollAreaScrollbar
+      ref={ref}
+      orientation={orientation}
+      className={cn(
+        "flex touch-none select-none transition-colors",
+        orientation === "vertical" && "h-full w-2.5 border-s border-s-transparent p-px",
+        orientation === "horizontal" && "h-2.5 flex-col border-t border-t-transparent p-px",
+        className,
+      )}
+      {...props}
+    >
+      <ScrollAreaPrimitive.ScrollAreaThumb className="relative flex-1 rounded-full bg-border" />
+    </ScrollAreaPrimitive.ScrollAreaScrollbar>
+  );
+});

package/src/components/section-header/index.ts

@@ -0,0 +1 @@
+export { SectionHeader, type SectionHeaderProps } from "./section-header";

package/src/components/section-header/section-header.stories.tsx

@@ -0,0 +1,20 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Button } from "../button";
+import { SectionHeader } from "./section-header";
+
+const meta = {
+  title: "Layout/SectionHeader",
+  component: SectionHeader,
+  tags: ["autodocs"],
+} satisfies Meta<typeof SectionHeader>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    eyebrow: "Workspace",
+    title: "Projects",
+    description: "Everything your team is working on.",
+    actions: <Button size="sm">New project</Button>,
+  },
+};

package/src/components/section-header/section-header.tsx

@@ -0,0 +1,36 @@
+import { type ReactNode } from "react";
+import { cn } from "../../lib/cn";
+
+export interface SectionHeaderProps {
+  title: ReactNode;
+  description?: ReactNode;
+  /** Right-aligned actions (buttons, menus). */
+  actions?: ReactNode;
+  /** Optional element rendered above the title (eyebrow / breadcrumbs). */
+  eyebrow?: ReactNode;
+  className?: string;
+}
+
+/** A consistent page/section heading row with optional actions. */
+export function SectionHeader({
+  title,
+  description,
+  actions,
+  eyebrow,
+  className,
+}: SectionHeaderProps) {
+  return (
+    <div className={cn("flex flex-wrap items-end justify-between gap-4", className)}>
+      <div className="space-y-1">
+        {eyebrow ? (
+          <div className="text-xs font-medium uppercase tracking-wide text-muted-foreground">
+            {eyebrow}
+          </div>
+        ) : null}
+        <h2 className="text-title text-foreground">{title}</h2>
+        {description ? <p className="text-sm text-muted-foreground">{description}</p> : null}
+      </div>
+      {actions ? <div className="flex items-center gap-2">{actions}</div> : null}
+    </div>
+  );
+}

package/src/components/segmented-field/index.ts

@@ -0,0 +1,5 @@
+export {
+  SegmentedField,
+  type SegmentedFieldOption,
+  type SegmentedFieldProps,
+} from "./segmented-field";

package/src/components/segmented-field/segmented-field.stories.tsx

@@ -0,0 +1,121 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect } from "storybook/test";
+import { useState } from "react";
+import { SegmentedField } from "./segmented-field";
+
+const PRIORITY_OPTIONS = [
+  { value: "low", label: "Low" },
+  { value: "medium", label: "Medium" },
+  { value: "high", label: "High" },
+];
+
+const meta = {
+  title: "Forms/SegmentedField",
+  component: SegmentedField,
+  tags: ["autodocs"],
+  args: {
+    label: "Priority",
+    options: PRIORITY_OPTIONS,
+    defaultValue: "medium",
+  },
+  argTypes: {
+    label: {
+      description: "Visible label describing the field.",
+      control: "text",
+      table: { category: "Content" },
+    },
+    options: {
+      description: "Segment options ({ value, label, disabled? }[]).",
+      control: false,
+      table: { category: "Content" },
+    },
+    value: {
+      description: "Controlled selected value.",
+      control: false,
+      table: { category: "State" },
+    },
+    defaultValue: {
+      description: "Uncontrolled initial selected value.",
+      control: false,
+      table: { category: "State" },
+    },
+    size: {
+      description: "Size applied to every segment.",
+      control: { type: "radio" },
+      options: ["default", "sm", "lg"],
+      table: { category: "Appearance" },
+    },
+    disabled: {
+      description: "Disables every segment.",
+      control: "boolean",
+      table: { category: "State" },
+    },
+    onValueChange: {
+      description: 'Called when the selected value changes. Never called with "".',
+      control: false,
+      table: { category: "Behavior" },
+    },
+    className: {
+      description: "Additional CSS classes applied to the root element.",
+      control: "text",
+      table: { category: "Appearance" },
+    },
+  },
+} satisfies Meta<typeof SegmentedField>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+export const Controlled: Story = {
+  render: () => {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    const [value, setValue] = useState("medium");
+    return (
+      <div className="flex flex-col gap-2">
+        <SegmentedField
+          label="Priority"
+          options={PRIORITY_OPTIONS}
+          value={value}
+          onValueChange={setValue}
+        />
+        <p className="text-body text-muted-foreground">Value: {value}</p>
+      </div>
+    );
+  },
+};
+
+/**
+ * Locks the whole reason this component exists: re-clicking the already
+ * active segment is a no-op — the value never becomes "" or undefined.
+ */
+export const ClickingActiveSegmentIsANoOp: Story = {
+  args: { defaultValue: "medium" },
+  play: async ({ canvas, userEvent }) => {
+    const mediumSegment = canvas.getByRole("radio", { name: "Medium" });
+    await expect(mediumSegment).toHaveAttribute("aria-checked", "true");
+    await userEvent.click(mediumSegment);
+    // Still checked — the empty-emission was swallowed, not applied.
+    await expect(mediumSegment).toHaveAttribute("aria-checked", "true");
+    await expect(canvas.getByRole("radio", { name: "Low" })).toHaveAttribute(
+      "aria-checked",
+      "false",
+    );
+  },
+};
+
+export const WithDisabledOption: Story = {
+  args: {
+    label: "Rollout stage",
+    options: [
+      { value: "dev", label: "Dev" },
+      { value: "staging", label: "Staging" },
+      { value: "prod", label: "Prod", disabled: true },
+    ],
+    defaultValue: "dev",
+  },
+};
+
+export const Disabled: Story = {
+  args: { defaultValue: "medium", disabled: true },
+};

package/src/components/segmented-field/segmented-field.test.tsx

@@ -0,0 +1,163 @@
+import { describe, expect, it, vi } from "vitest";
+import { act, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { SegmentedField } from "./segmented-field";
+
+const OPTIONS = [
+  { value: "low", label: "Low" },
+  { value: "medium", label: "Medium" },
+  { value: "high", label: "High" },
+];
+
+describe("SegmentedField", () => {
+  it("renders the label and every segment", () => {
+    render(<SegmentedField label="Priority" options={OPTIONS} defaultValue="low" />);
+    expect(screen.getByText("Priority")).toBeInTheDocument();
+    expect(screen.getByRole("radio", { name: "Low" })).toBeInTheDocument();
+    expect(screen.getByRole("radio", { name: "Medium" })).toBeInTheDocument();
+    expect(screen.getByRole("radio", { name: "High" })).toBeInTheDocument();
+  });
+
+  it("always reports exactly one selected value (uncontrolled)", async () => {
+    const onValueChange = vi.fn();
+    render(
+      <SegmentedField
+        label="Priority"
+        options={OPTIONS}
+        defaultValue="low"
+        onValueChange={onValueChange}
+      />,
+    );
+    await userEvent.click(screen.getByRole("radio", { name: "High" }));
+    expect(onValueChange).toHaveBeenCalledWith("high");
+    expect(screen.getByRole("radio", { name: "High" })).toHaveAttribute("aria-checked", "true");
+  });
+
+  it("clicking the already-active segment is a no-op (never emits '')", async () => {
+    const onValueChange = vi.fn();
+    render(
+      <SegmentedField
+        label="Priority"
+        options={OPTIONS}
+        value="medium"
+        onValueChange={onValueChange}
+      />,
+    );
+    const mediumSegment = screen.getByRole("radio", { name: "Medium" });
+    await userEvent.click(mediumSegment);
+    expect(onValueChange).not.toHaveBeenCalled();
+    expect(mediumSegment).toHaveAttribute("aria-checked", "true");
+  });
+
+  it("never calls onValueChange with an empty string", async () => {
+    const onValueChange = vi.fn();
+    render(
+      <SegmentedField
+        label="Priority"
+        options={OPTIONS}
+        defaultValue="low"
+        onValueChange={onValueChange}
+      />,
+    );
+    await userEvent.click(screen.getByRole("radio", { name: "Low" }));
+    await userEvent.click(screen.getByRole("radio", { name: "Low" }));
+    for (const call of onValueChange.mock.calls) {
+      expect(call[0]).not.toBe("");
+    }
+  });
+
+  it("moves selection with arrow-key navigation (selection follows focus)", async () => {
+    const onValueChange = vi.fn();
+    render(
+      <SegmentedField
+        label="Priority"
+        options={OPTIONS}
+        defaultValue="low"
+        onValueChange={onValueChange}
+      />,
+    );
+    const lowSegment = screen.getByRole("radio", { name: "Low" });
+    act(() => {
+      lowSegment.focus();
+    });
+    await userEvent.keyboard("{ArrowRight}");
+    expect(onValueChange).toHaveBeenCalledWith("medium");
+    expect(screen.getByRole("radio", { name: "Medium" })).toHaveAttribute("aria-checked", "true");
+  });
+
+  it("clicking the label focuses the SELECTED segment without changing the value", async () => {
+    const onValueChange = vi.fn();
+    render(
+      <SegmentedField
+        label="Priority"
+        options={OPTIONS}
+        defaultValue="medium"
+        onValueChange={onValueChange}
+      />,
+    );
+    await userEvent.click(screen.getByText("Priority"));
+    // A `<label>` moves focus into its field — it never mutates it.
+    expect(screen.getByRole("radio", { name: "Medium" })).toHaveFocus();
+    expect(onValueChange).not.toHaveBeenCalled();
+    expect(screen.getByRole("radio", { name: "Medium" })).toHaveAttribute("aria-checked", "true");
+  });
+
+  it("tabbing into a group with nothing selected does not auto-select", async () => {
+    const onValueChange = vi.fn();
+    render(
+      <>
+        <button>before</button>
+        <SegmentedField label="Priority" options={OPTIONS} onValueChange={onValueChange} />
+      </>,
+    );
+    screen.getByRole("button", { name: "before" }).focus();
+    await userEvent.tab();
+    expect(onValueChange).not.toHaveBeenCalled();
+    expect(screen.queryByRole("radio", { checked: true })).not.toBeInTheDocument();
+  });
+
+  it("stays controlled for Radix even when nothing is selected yet", async () => {
+    const warn = vi.spyOn(console, "error").mockImplementation(() => {});
+    render(<SegmentedField label="Priority" options={OPTIONS} />);
+    await userEvent.click(screen.getByRole("radio", { name: "High" }));
+    // A `value` that starts `undefined` and becomes a string is a mode flip;
+    // Radix reports it on console.error.
+    expect(warn.mock.calls.flat().join(" ")).not.toMatch(/uncontrolled to controlled/i);
+    warn.mockRestore();
+  });
+
+  it("disables every segment when disabled is set", () => {
+    render(<SegmentedField label="Priority" options={OPTIONS} defaultValue="low" disabled />);
+    expect(screen.getByRole("radio", { name: "Low" })).toBeDisabled();
+    expect(screen.getByRole("radio", { name: "Medium" })).toBeDisabled();
+  });
+
+  it("disables just the option marked disabled", () => {
+    render(
+      <SegmentedField
+        label="Stage"
+        options={[
+          { value: "dev", label: "Dev" },
+          { value: "prod", label: "Prod", disabled: true },
+        ]}
+        defaultValue="dev"
+      />,
+    );
+    expect(screen.getByRole("radio", { name: "Prod" })).toBeDisabled();
+    expect(screen.getByRole("radio", { name: "Dev" })).not.toBeDisabled();
+  });
+
+  it("supports the controlled mode via value/onValueChange", async () => {
+    const onValueChange = vi.fn();
+    render(
+      <SegmentedField
+        label="Priority"
+        options={OPTIONS}
+        value="low"
+        onValueChange={onValueChange}
+      />,
+    );
+    await userEvent.click(screen.getByRole("radio", { name: "High" }));
+    expect(onValueChange).toHaveBeenCalledWith("high");
+  });
+});

package/src/components/segmented-field/segmented-field.tsx

@@ -0,0 +1,235 @@
+"use client";
+
+import {
+  forwardRef,
+  useCallback,
+  useId,
+  useRef,
+  useState,
+  type FocusEvent as ReactFocusEvent,
+  type HTMLAttributes,
+  type KeyboardEvent as ReactKeyboardEvent,
+  type PointerEvent as ReactPointerEvent,
+  type ReactNode,
+} from "react";
+import { cn } from "../../lib/cn";
+import { Label } from "../label";
+import { ToggleGroup, ToggleGroupItem } from "../toggle-group";
+
+/** Keys whose focus move must also move the selection (WAI-ARIA radiogroup). */
+const NAV_KEYS = new Set(["ArrowLeft", "ArrowRight", "ArrowUp", "ArrowDown", "Home", "End"]);
+
+export interface SegmentedFieldOption {
+  /** The option's value, reported to `onValueChange`. */
+  value: string;
+  /** Visible content for the segment. */
+  label: ReactNode;
+  /** Disables just this segment. */
+  disabled?: boolean;
+}
+
+export interface SegmentedFieldProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  "onChange" | "defaultValue"
+> {
+  /** Visible label describing the field. */
+  label: ReactNode;
+  /**
+   * Segment options. Omit and render `ToggleGroupItem` children directly for
+   * the compound-component escape hatch (component-api.md) when a plain
+   * `{ value, label }` shape isn't expressive enough.
+   */
+  options?: SegmentedFieldOption[];
+  /** Controlled selected value. */
+  value?: string;
+  /** Uncontrolled initial selected value. */
+  defaultValue?: string;
+  /**
+   * Called when the selected value changes. Never called with `""` —
+   * re-clicking the active segment (Radix `ToggleGroup`'s `type="single"`
+   * empty-emission on re-click) is swallowed as a no-op instead of clearing
+   * the field.
+   */
+  onValueChange?: (value: string) => void;
+  /** Size applied to every segment. Defaults to "sm", matching the compact segmented look. */
+  size?: "default" | "sm" | "lg";
+  /** Disables every segment. */
+  disabled?: boolean;
+  /** `ToggleGroupItem` children — the compound escape hatch (used instead of `options`). */
+  children?: ReactNode;
+}
+
+/**
+ * SegmentedField — a labelled segmented control with STICKY selection.
+ *
+ * Composes the existing `Label` + `ToggleGroup`/`ToggleGroupItem`
+ * (`variant="segmented"`) — no new visual style. The whole reason this
+ * component exists: Radix's `ToggleGroup` in `type="single"` mode emits `""`
+ * when the already-active segment is re-clicked, silently clearing a field
+ * that must always hold exactly one value. `SegmentedField` swallows that
+ * emission so re-clicking the active segment is a true no-op.
+ *
+ * Per the WAI-ARIA radiogroup pattern (each segment renders `role="radio"`
+ * for `type="single"`), ARROW-KEY navigation also SELECTS the newly focused
+ * segment (selection follows focus), matching native radio-button behavior —
+ * Radix's roving-tabindex only moves focus, so this component adds that
+ * activation on top of it.
+ *
+ * Selection follows focus ONLY for arrow/Home/End keys, never for arbitrary
+ * focus. A bare `onFocus` commit would make three non-navigation paths mutate
+ * the field: clicking the `<Label>` (which moves focus into the group),
+ * tabbing into a group with nothing selected yet, and any programmatic
+ * `.focus()` a consumer performs. The keyboard intent is recorded on the
+ * wrapper in the CAPTURE phase (it must land before Radix's own roving-focus
+ * keydown handler runs) and is cleared by the focus it explains, by a pointer
+ * press, by any non-navigation key, or by focus leaving the field — so it can
+ * never leak into a later, unrelated focus.
+ */
+export const SegmentedField = forwardRef<HTMLDivElement, SegmentedFieldProps>(
+  function SegmentedField(
+    {
+      label,
+      options,
+      value: valueProp,
+      defaultValue,
+      onValueChange,
+      size = "sm",
+      disabled,
+      id,
+      className,
+      children,
+      ...props
+    },
+    ref,
+  ) {
+    const generatedId = useId();
+    const labelId = `${id ?? generatedId}-label`;
+    const groupRef = useRef<HTMLDivElement>(null);
+
+    const isControlled = valueProp !== undefined;
+    const [internalValue, setInternalValue] = useState(defaultValue);
+    const currentValue = isControlled ? valueProp : internalValue;
+
+    // Synced every render (mirrors the ref-during-render idiom in
+    // NumberInput) so a same-event double-dispatch (focus-follows-selection
+    // AND the click's own onPressedChange) commits at most once.
+    const lastCommittedRef = useRef(currentValue);
+    lastCommittedRef.current = currentValue;
+
+    const commit = useCallback(
+      (next: string) => {
+        // Radix emits "" when the active segment is re-clicked — swallow it.
+        if (next === "" || next === lastCommittedRef.current) return;
+        lastCommittedRef.current = next;
+        if (!isControlled) setInternalValue(next);
+        onValueChange?.(next);
+      },
+      [isControlled, onValueChange],
+    );
+
+    // Armed by an arrow/Home/End key, DISARMED by anything else — a pointer
+    // press, any other key, or focus leaving the field. It is deliberately not
+    // a timer: `@radix-ui/react-roving-focus` moves focus in a
+    // `setTimeout(() => focusFirst(...))`, so a microtask/`setTimeout` reset
+    // queued from the capture phase would always fire first and the arm would
+    // be gone before the focus it exists to classify.
+    const keyboardNavRef = useRef(false);
+
+    const handleKeyDownCapture = useCallback(
+      (event: ReactKeyboardEvent<HTMLDivElement>) => {
+        keyboardNavRef.current = NAV_KEYS.has(event.key);
+        props.onKeyDownCapture?.(event);
+      },
+      [props],
+    );
+
+    const handlePointerDownCapture = useCallback(
+      (event: ReactPointerEvent<HTMLDivElement>) => {
+        keyboardNavRef.current = false;
+        props.onPointerDownCapture?.(event);
+      },
+      [props],
+    );
+
+    const handleBlurCapture = useCallback(
+      (event: ReactFocusEvent<HTMLDivElement>) => {
+        // Focus moving between segments keeps the arm; leaving the field drops
+        // it, so a stale arm can never fire on a later tab-in.
+        if (!event.currentTarget.contains(event.relatedTarget as Node | null)) {
+          keyboardNavRef.current = false;
+        }
+        props.onBlurCapture?.(event);
+      },
+      [props],
+    );
+
+    const handleItemFocus = useCallback(
+      (next: string) => {
+        if (!keyboardNavRef.current) return;
+        keyboardNavRef.current = false;
+        commit(next);
+      },
+      [commit],
+    );
+
+    // Match a native `<label>`: move focus into the field without changing it.
+    // Focusing the SELECTED segment (not blindly the first) keeps the visible
+    // selection and the focus ring in agreement.
+    const handleLabelClick = useCallback(() => {
+      const group = groupRef.current;
+      if (!group) return;
+      const selected = group.querySelector<HTMLButtonElement>(
+        '[aria-checked="true"]:not(:disabled),[data-state="on"]:not(:disabled)',
+      );
+      (selected ?? group.querySelector<HTMLButtonElement>("button:not(:disabled)"))?.focus();
+    }, []);
+
+    return (
+      <div
+        ref={ref}
+        data-slot="segmented-field"
+        className={cn("flex flex-col items-start gap-1.5", className)}
+        {...props}
+        // After the spread: these three are load-bearing (they classify a
+        // focus as arrow-navigation or not) and each re-invokes the consumer's
+        // handler, so composing beats being silently replaced.
+        onKeyDownCapture={handleKeyDownCapture}
+        onPointerDownCapture={handlePointerDownCapture}
+        onBlurCapture={handleBlurCapture}
+      >
+        <Label id={labelId} data-slot="segmented-field-label" onClick={handleLabelClick}>
+          {label}
+        </Label>
+        <ToggleGroup
+          ref={groupRef}
+          type="single"
+          variant="segmented"
+          size={size}
+          // Always a string, never `undefined` — an unselected field would
+          // otherwise start UNcontrolled and flip to controlled on the first
+          // selection (React/Radix warn, and the mode flip is exactly what
+          // component-api.md forbids). `""` is Radix's "nothing selected".
+          value={currentValue ?? ""}
+          onValueChange={commit}
+          disabled={disabled}
+          aria-labelledby={labelId}
+          data-slot="segmented-field-options"
+        >
+          {options
+            ? options.map((option) => (
+                <ToggleGroupItem
+                  key={option.value}
+                  data-slot="segmented-field-segment"
+                  value={option.value}
+                  disabled={option.disabled}
+                  onFocus={() => handleItemFocus(option.value)}
+                >
+                  {option.label}
+                </ToggleGroupItem>
+              ))
+            : children}
+        </ToggleGroup>
+      </div>
+    );
+  },
+);