@elabs-ai/components-ui 4.0.0

package/src/components/timeline/timeline.tsx

@@ -0,0 +1,188 @@
+/**
+ * Timeline — THE rail/node/connector spine (#190, research 10 §B.2): an
+ * ordered list of steps with a vertical connector and a status-colored node
+ * per step. Moved from `@elabs-ai/components-editor` (which re-exports it for back-compat —
+ * the ADR-0012 own/re-export model); the branded target for the editor's
+ * `:::timeline` markdown directive, and reusable anywhere a process/sequence
+ * needs showing. Token-driven, theme-safe, motion-free (animation belongs to
+ * composing consumers, e.g. the `@elabs-ai/components-ai` agent grammar).
+ *
+ * One rail, two front doors:
+ *   - compound `TimelineRoot` + `TimelineItem` — for composing consumers that
+ *     interleave rich children per node. The node takes the CANONICAL 7-state
+ *     `Status` (status-badge, #189) — closed enum, no freeform strings.
+ *   - array `Timeline items={TimelineEntry[]}` — a thin map over the compound
+ *     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).
+ */
+import { forwardRef, type HTMLAttributes, type LiHTMLAttributes, type ReactNode } from "react";
+import { cn } from "../../lib/cn";
+import {
+  fromTimelineStatus,
+  STATUS_LABELS,
+  type Status,
+  type TimelineStatus,
+} from "../status-badge";
+
+/**
+ * Node visual per canonical status. This is a DUPLICATE of the status→role
+ * mapping `status-badge.tsx` owns (`STATUS_ROLE`) — it exists because the rail
+ * node is a filled dot, not a badge pill, so it can't share `statusBadgeVariants`
+ * directly. A duplicate is only safe when it is TESTED against the source of
+ * truth: `timeline.test.tsx` asserts every chromatic status here resolves to
+ * the same role as `STATUS_ROLE`/`statusBadgeVariants` (#392 — `running` had
+ * silently drifted to `--primary` here while the canonical map said `--info`,
+ * because nothing checked the two agreed). Semantic tokens only.
+ *
+ * Every status ALSO carries a non-colour signature (#387, WCAG 1.4.1) — a
+ * 12px dot can't host a legible glyph, so the cue is geometric. It took an
+ * empirical (rendered) pass to find a signature that actually PAINTS
+ * distinctly, not merely one that differs as a class string:
+ *   - `denied`/`skipped` (hollow-ish `bg-muted`, `border-border`) get
+ *     `border-dashed`/`border-dotted` — this WORKS because border and fill
+ *     are different colours there, so the gaps in the dash/dot pattern show
+ *     the (lighter) fill through the (darker) border.
+ *   - `running`/`complete`/`awaiting-approval`/`failed` are all `bg-<status>
+ *     border-<status>` — the vivid MARK rung, where border and fill are the
+ *     SAME token. A `border-style` on a same-colour border is invisible (no
+ *     colour boundary for the dash gaps to reveal), so this quartet is
+ *     differentiated by `ring-*` WIDTH instead — the ring sits outside the
+ *     dot, contrasting against the PAGE, not the fill, which is why
+ *     `running`'s existing halo was legible in the first place. Widths
+ *     `0 / 1 / 2 / 4` give four unmistakably different silhouettes:
+ *     `complete` none (calm/settled, matches `StatusBadge`'s quiet
+ *     treatment for `complete`) → `awaiting-approval` `ring-1` (a nudge) →
+ *     `running` `ring-2` (active) → `failed` `ring-4` (the widest, most
+ *     emphatic — the state that most needs to grab the eye).
+ * `denied`/`skipped` were byte-identical before this; the ring-width
+ * progression replaces an earlier border-style-only attempt that turned out
+ * to be visually void on the vivid quartet — verified in `timeline.test.tsx`
+ * (structural) and by rendered zoomed + greyscale screenshots (see #387
+ * rendered proof) — don't reintroduce border-style there without re-checking
+ * a render, it will look correct in code and disappear on screen.
+ */
+export const NODE_STYLE: Record<Status, string> = {
+  pending: "border-border bg-background",
+  running: "border-info bg-info ring-2 ring-info/25",
+  complete: "border-success bg-success",
+  "awaiting-approval": "border-warning bg-warning ring-1 ring-warning/40",
+  denied: "border-border bg-muted border-dashed",
+  failed: "border-destructive bg-destructive ring-4 ring-destructive/20",
+  skipped: "border-border bg-muted border-dotted",
+};
+
+/** Statuses whose title reads de-emphasized (not-yet/never-run steps). */
+const MUTED_TITLE_STATUSES: ReadonlySet<Status> = new Set(["pending", "skipped", "denied"]);
+
+export type TimelineRootProps = HTMLAttributes<HTMLOListElement>;
+
+/** The `<ol>` that owns the rail geometry; compose `TimelineItem`s inside. */
+export const TimelineRoot = forwardRef<HTMLOListElement, TimelineRootProps>(function TimelineRoot(
+  { className, ...props },
+  ref,
+) {
+  return <ol ref={ref} className={cn("relative", className)} {...props} />;
+});
+
+export interface TimelineItemProps extends LiHTMLAttributes<HTMLLIElement> {
+  /** The canonical execution status (closed 7-state enum, status-badge #189). */
+  status?: Status;
+  /** Right-aligned meta (e.g. a date) on the title row. */
+  timestamp?: ReactNode;
+  /** Secondary line under the title. */
+  description?: ReactNode;
+  /**
+   * Rich block content under the title/description, indented with the rail —
+   * the slot composing consumers (e.g. `@elabs-ai/components-ai`'s `AgentStep`, #192)
+   * interleave per node. Block-level, so it must NOT ride the inline title
+   * slot (`children`).
+   */
+  detail?: ReactNode;
+}
+
+/**
+ * One `<li>`: status node + connector + the title row; `children` is the
+ * title slot. The connector hides itself on the last item via CSS
+ * (`group-last`), so streaming/compound consumers never track "is last".
+ */
+export const TimelineItem = forwardRef<HTMLLIElement, TimelineItemProps>(function TimelineItem(
+  { status = "pending", timestamp, description, detail, className, children, ...props },
+  ref,
+) {
+  return (
+    <li
+      ref={ref}
+      data-status={status}
+      className={cn("group/timeline-item relative pb-5 ps-7 last:pb-0", className)}
+      {...props}
+    >
+      <span
+        aria-hidden="true"
+        className="absolute start-[5px] top-2.5 h-full w-px bg-border group-last/timeline-item:hidden"
+      />
+      <span
+        aria-hidden="true"
+        className={cn("absolute start-0 top-1 size-3 rounded-full border-2", NODE_STYLE[status])}
+      />
+      <div className="flex items-baseline justify-between gap-3">
+        <span
+          className={cn(
+            "text-body font-medium",
+            MUTED_TITLE_STATUSES.has(status) ? "text-muted-foreground" : "text-foreground",
+          )}
+        >
+          {/* The dot is `aria-hidden` and `data-status` isn't AT-visible (#387) —
+              this is the step's only announced status; kept inline so it reads
+              naturally as "<Status>: <title>" instead of a second live region. */}
+          <span className="sr-only">{STATUS_LABELS[status]}: </span>
+          {children}
+        </span>
+        {timestamp ? (
+          <span className="shrink-0 text-meta text-muted-foreground">{timestamp}</span>
+        ) : null}
+      </div>
+      {description ? <p className="mt-0.5 text-body text-muted-foreground">{description}</p> : null}
+      {detail ? <div className="mt-2 space-y-2">{detail}</div> : null}
+    </li>
+  );
+});
+
+/**
+ * One step of the array-API `Timeline` (the editor's original item shape —
+ * re-exported by `@elabs-ai/components-editor` as `TimelineItem` for back-compat).
+ */
+export interface TimelineEntry {
+  title: ReactNode;
+  description?: ReactNode;
+  /** The editor's 3-state vocabulary; mapped in via `fromTimelineStatus`. */
+  status?: TimelineStatus;
+  timestamp?: ReactNode;
+}
+
+export interface TimelineProps extends HTMLAttributes<HTMLOListElement> {
+  items: TimelineEntry[];
+}
+
+/** Array convenience over the compound parts (data in, list out). */
+export const Timeline = forwardRef<HTMLOListElement, TimelineProps>(function Timeline(
+  { items, className, ...props },
+  ref,
+) {
+  return (
+    <TimelineRoot ref={ref} className={className} {...props}>
+      {items.map((item, i) => (
+        <TimelineItem
+          key={i}
+          status={fromTimelineStatus(item.status ?? "pending")}
+          timestamp={item.timestamp}
+          description={item.description}
+        >
+          {item.title}
+        </TimelineItem>
+      ))}
+    </TimelineRoot>
+  );
+});

package/src/components/toggle/index.ts

@@ -0,0 +1 @@
+export { Toggle, toggleVariants } from "./toggle";

package/src/components/toggle/toggle.stories.tsx

@@ -0,0 +1,116 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect } from "storybook/test";
+import { Bold } from "lucide-react";
+import { Toggle } from "./toggle";
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "../tooltip";
+const meta = {
+  title: "Forms/Toggle",
+  component: Toggle,
+  tags: ["autodocs"],
+  argTypes: {
+    variant: {
+      description: "Visual style of the toggle.",
+      control: { type: "select" },
+      options: ["default", "outline", "segmented"],
+      table: { category: "Appearance" },
+    },
+    size: {
+      description: "Size of the toggle button.",
+      control: { type: "radio" },
+      options: ["default", "sm", "lg"],
+      table: { category: "Appearance" },
+    },
+    pressed: {
+      description: "Controlled pressed state.",
+      control: "boolean",
+      table: { category: "State" },
+    },
+    defaultPressed: {
+      description: "Uncontrolled initial pressed state.",
+      control: "boolean",
+      table: { category: "State" },
+    },
+    disabled: {
+      description: "Disables the toggle.",
+      control: "boolean",
+      table: { category: "State" },
+    },
+    onPressedChange: {
+      description: "Called when the pressed state changes.",
+      control: false,
+      table: { category: "Behavior" },
+    },
+    "aria-label": {
+      description: "Accessible label (required for icon-only toggles).",
+      control: "text",
+      table: { category: "Appearance" },
+    },
+    children: {
+      description: "Toggle content — icon and/or text.",
+      control: false,
+      table: { category: "Content" },
+    },
+    className: {
+      description: "Additional CSS classes applied to the root element.",
+      control: "text",
+      table: { category: "Appearance" },
+    },
+  },
+} satisfies Meta<typeof Toggle>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+export const Default: Story = {
+  args: { "aria-label": "Bold", children: <Bold /> },
+  // Clicks the toggle and confirms the pressed state flips.
+  play: async ({ canvas, userEvent }) => {
+    const btn = canvas.getByRole("button", { name: /bold/i });
+    await expect(btn).toHaveAttribute("aria-pressed", "false");
+    await userEvent.click(btn);
+    await expect(btn).toHaveAttribute("aria-pressed", "true");
+  },
+};
+export const Pressed: Story = {
+  args: { "aria-label": "Bold", children: <Bold />, pressed: true },
+};
+export const Outline: Story = { args: { variant: "outline", children: "Bold" } };
+export const OutlinePressed: Story = {
+  args: { variant: "outline", children: "Bold", pressed: true },
+};
+// `segmented` was selectable in the controls panel (`argTypes.variant.options`)
+// but never actually rendered by any story (#388), so it never reached the
+// blocking interaction + axe job. This is the mode-switch look — no border, an
+// elevated `bg-surface-elevated` active segment — normally composed inside a
+// `ToggleGroup variant="segmented"` track (see Forms/ToggleGroup → Segmented);
+// rendered standalone here purely to exercise the variant itself.
+export const Segmented: Story = {
+  args: { variant: "segmented", "aria-label": "Bold", children: <Bold /> },
+};
+export const Disabled: Story = {
+  args: { "aria-label": "Bold", children: <Bold />, disabled: true },
+};
+
+// Regression story for #214: a pressed Toggle wrapped in TooltipTrigger asChild.
+// The tooltip's data-state="closed" overwrites the toggle's data-state="on", but
+// the active style must still render because it is also keyed on aria-pressed.
+export const TooltipWrappedPressed: Story = {
+  render: () => (
+    <TooltipProvider>
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <Toggle aria-label="Bold" pressed>
+            <Bold />
+          </Toggle>
+        </TooltipTrigger>
+        <TooltipContent>Bold</TooltipContent>
+      </Tooltip>
+    </TooltipProvider>
+  ),
+  play: async ({ canvas }) => {
+    const btn = canvas.getByRole("button", { name: /bold/i });
+    // aria-pressed must survive the TooltipTrigger asChild merge.
+    await expect(btn).toHaveAttribute("aria-pressed", "true");
+    // aria-keyed class tokens must be present so the active style renders.
+    await expect(btn.className).toContain("aria-pressed:bg-accent");
+    await expect(btn.className).toContain("aria-pressed:border-primary");
+  },
+};

package/src/components/toggle/toggle.test.tsx

@@ -0,0 +1,119 @@
+import { describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { Toggle } from "./toggle";
+import { ToggleGroup, ToggleGroupItem } from "../toggle-group";
+
+describe("Toggle", () => {
+  it("toggles pressed state", async () => {
+    render(<Toggle aria-label="t">B</Toggle>);
+    const t = screen.getByRole("button", { name: "t" });
+    await userEvent.click(t);
+    expect(t).toHaveAttribute("data-state", "on");
+  });
+
+  // Regression guard for #214: when a TooltipTrigger asChild wrapper merges
+  // onto the toggle element it overwrites data-state="on" → "closed". The
+  // active styles must survive via aria-pressed / aria-checked keying.
+  it("carries aria-pressed=true and aria-keyed active classes when pressed, regardless of data-state", () => {
+    render(
+      <Toggle aria-label="bold" pressed>
+        B
+      </Toggle>,
+    );
+    const btn = screen.getByRole("button", { name: "bold" });
+
+    // aria-pressed must be "true" — set by the Radix Toggle primitive alone,
+    // not clobbered by a TooltipTrigger wrapper.
+    expect(btn).toHaveAttribute("aria-pressed", "true");
+
+    // The className must contain the aria-pressed-keyed active utilities so
+    // the style applies even when data-state is overwritten to "closed".
+    expect(btn.className).toContain("aria-pressed:bg-accent");
+    expect(btn.className).toContain("aria-pressed:text-accent-foreground");
+    expect(btn.className).toContain("aria-pressed:font-semibold");
+    expect(btn.className).toContain("aria-pressed:border-primary");
+  });
+
+  it("carries aria-pressed=true and aria-keyed active classes on outline variant when pressed", () => {
+    render(
+      <Toggle aria-label="bold" variant="outline" pressed>
+        B
+      </Toggle>,
+    );
+    const btn = screen.getByRole("button", { name: "bold" });
+
+    expect(btn).toHaveAttribute("aria-pressed", "true");
+    expect(btn.className).toContain("aria-pressed:bg-accent");
+    expect(btn.className).toContain("aria-pressed:text-accent-foreground");
+    expect(btn.className).toContain("aria-pressed:font-semibold");
+    expect(btn.className).toContain("aria-pressed:border-primary");
+  });
+
+  // Simulate the exact TooltipTrigger collision: data-state is clobbered to
+  // "closed" after mount; the aria-pressed attribute (set by the toggle
+  // primitive) must remain "true" and the class tokens must still be present.
+  it("active style survives data-state being overwritten to closed (TooltipTrigger collision)", () => {
+    render(
+      <Toggle aria-label="bold" pressed>
+        B
+      </Toggle>,
+    );
+    const btn = screen.getByRole("button", { name: "bold" });
+
+    // Simulate what TooltipTrigger asChild does: clobber data-state.
+    btn.setAttribute("data-state", "closed");
+
+    // aria-pressed is NOT affected by the data-state clobber.
+    expect(btn).toHaveAttribute("aria-pressed", "true");
+
+    // The aria-keyed class tokens must still be present in className — they
+    // will activate in the browser via CSS [aria-pressed="true"] selectors.
+    expect(btn.className).toContain("aria-pressed:bg-accent");
+    expect(btn.className).toContain("aria-pressed:border-primary");
+
+    // data-state is now "closed" (confirming the collision scenario).
+    expect(btn).toHaveAttribute("data-state", "closed");
+  });
+});
+
+describe("ToggleGroup / ToggleGroupItem (#214 regression)", () => {
+  it("selected ToggleGroupItem carries aria-checked=true and aria-keyed active classes", () => {
+    render(
+      <ToggleGroup type="single" value="a">
+        <ToggleGroupItem value="a" aria-label="item-a">
+          A
+        </ToggleGroupItem>
+      </ToggleGroup>,
+    );
+    const item = screen.getByRole("radio", { name: "item-a" });
+
+    // ToggleGroupItem sets aria-checked, not aria-pressed.
+    expect(item).toHaveAttribute("aria-checked", "true");
+
+    // aria-checked-keyed active class tokens must be present.
+    expect(item.className).toContain("aria-checked:bg-accent");
+    expect(item.className).toContain("aria-checked:text-accent-foreground");
+    expect(item.className).toContain("aria-checked:font-semibold");
+    expect(item.className).toContain("aria-checked:border-primary");
+  });
+
+  it("active style on ToggleGroupItem survives data-state being overwritten to closed", () => {
+    render(
+      <ToggleGroup type="single" value="a">
+        <ToggleGroupItem value="a" aria-label="item-a">
+          A
+        </ToggleGroupItem>
+      </ToggleGroup>,
+    );
+    const item = screen.getByRole("radio", { name: "item-a" });
+
+    // Simulate TooltipTrigger asChild clobbering data-state.
+    item.setAttribute("data-state", "closed");
+
+    expect(item).toHaveAttribute("aria-checked", "true");
+    expect(item.className).toContain("aria-checked:bg-accent");
+    expect(item.className).toContain("aria-checked:border-primary");
+    expect(item).toHaveAttribute("data-state", "closed");
+  });
+});

package/src/components/toggle/toggle.tsx

@@ -0,0 +1,64 @@
+import { forwardRef, type ComponentPropsWithoutRef, type ElementRef } from "react";
+import * as TogglePrimitive from "@radix-ui/react-toggle";
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "../../lib/cn";
+
+export const toggleVariants = cva(
+  // Pressed (data-[state=on]) reads as a clearly-distinct, AA-safe state: an
+  // accent fill + bolded label (accent/accent-foreground is a guaranteed AA
+  // pair) plus a solid `primary` border as a ≥3:1 non-text boundary cue. We
+  // deliberately do NOT use `bg-primary`/`text-primary-foreground`: under the
+  // pre-debrand green palette that pair measured only 3.61:1 in `light`, which
+  // fails AA for text labels (#148). The retuned palette flipped
+  // `--primary-foreground` to near-black on a light primary and clears AA
+  // comfortably, so the CONTRAST argument is spent — the shape stands on design
+  // grounds instead: a pressed toggle is a secondary state and an accent fill is
+  // the right weight for it. The border carries the strength; the focus ring is
+  // untouched.
+  //
+  // Active styles are keyed on BOTH data-[state=on]: AND aria-pressed:/aria-checked:
+  // (belt-and-suspenders, mirroring the `segmented` variant). A TooltipTrigger
+  // 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-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:pointer-events-none disabled:opacity-50 data-[state=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: {
+        // `border border-transparent` reserves the 1px so the pressed
+        // `border-primary` does not shift layout.
+        default:
+          "border border-transparent bg-transparent data-[state=on]:border-primary aria-pressed:border-primary aria-checked:border-primary",
+        outline:
+          "border border-input bg-transparent shadow-sm hover:bg-accent hover:text-accent-foreground data-[state=on]:border-primary aria-pressed:border-primary aria-checked:border-primary",
+        // Segmented mode switch: the SAME elevation grammar as TabsTrigger —
+        // raised elevated segment on a recessed `bg-muted` track (the track
+        // comes from ToggleGroup `variant="segmented"`). No `border-primary`
+        // here: within a group the active boundary is the fill/elevation
+        // change (1.4.11 redundant boundary), and no weight shift on press
+        // (labels would jiggle the segment widths).
+        // Keyed off aria-checked/aria-pressed, NOT data-[state=on]: a
+        // TooltipTrigger asChild wrapper overwrites the toggle's data-state
+        // with the tooltip's ("closed"), silently killing the active style —
+        // the aria attributes are set by the toggle primitive alone.
+        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" },
+    },
+    defaultVariants: { variant: "default", size: "default" },
+  },
+);
+
+export const Toggle = forwardRef<
+  ElementRef<typeof TogglePrimitive.Root>,
+  ComponentPropsWithoutRef<typeof TogglePrimitive.Root> & VariantProps<typeof toggleVariants>
+>(function Toggle({ className, variant, size, ...props }, ref) {
+  return (
+    <TogglePrimitive.Root
+      ref={ref}
+      className={cn(toggleVariants({ variant, size }), className)}
+      {...props}
+    />
+  );
+});

package/src/components/toggle-group/index.ts

@@ -0,0 +1 @@
+export { ToggleGroup, ToggleGroupItem } from "./toggle-group";

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

@@ -0,0 +1,110 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect } from "storybook/test";
+import { Bold, BookOpen, Italic, PencilLine, Underline } from "lucide-react";
+import { ToggleGroup, ToggleGroupItem } from "./toggle-group";
+const meta = {
+  title: "Forms/ToggleGroup",
+  component: ToggleGroup,
+  tags: ["autodocs"],
+  argTypes: {
+    type: {
+      description: '`"single"` — at most one item active. `"multiple"` — any number active.',
+      control: { type: "radio" },
+      options: ["single", "multiple"],
+      table: { category: "Behavior" },
+    },
+    variant: {
+      description: "Visual style applied to all items in the group.",
+      control: { type: "select" },
+      options: ["default", "outline", "segmented"],
+      table: { category: "Appearance" },
+    },
+    size: {
+      description: "Size applied to all items.",
+      control: { type: "radio" },
+      options: ["default", "sm", "lg"],
+      table: { category: "Appearance" },
+    },
+    value: {
+      description: "Controlled active value(s).",
+      control: false,
+      table: { category: "State" },
+    },
+    defaultValue: {
+      description: "Uncontrolled initial active value(s).",
+      control: false,
+      table: { category: "State" },
+    },
+    disabled: {
+      description: "Disables all items.",
+      control: "boolean",
+      table: { category: "State" },
+    },
+    onValueChange: {
+      description: "Called when the active value(s) change.",
+      control: false,
+      table: { category: "Behavior" },
+    },
+    children: {
+      description: "ToggleGroupItem elements.",
+      control: false,
+      table: { category: "Content" },
+    },
+    className: {
+      description: "Additional CSS classes applied to the root element.",
+      control: "text",
+      table: { category: "Appearance" },
+    },
+  },
+} satisfies Meta<typeof ToggleGroup>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+export const Default: Story = {
+  render: () => (
+    <ToggleGroup type="multiple" variant="outline">
+      <ToggleGroupItem value="bold" aria-label="Bold">
+        <Bold />
+      </ToggleGroupItem>
+      <ToggleGroupItem value="italic" aria-label="Italic">
+        <Italic />
+      </ToggleGroupItem>
+      <ToggleGroupItem value="underline" aria-label="Underline">
+        <Underline />
+      </ToggleGroupItem>
+    </ToggleGroup>
+  ),
+  // Clicks "Bold" to activate it, then clicks again to deactivate.
+  play: async ({ canvas, userEvent }) => {
+    const boldBtn = canvas.getByRole("button", { name: /bold/i });
+    await expect(boldBtn).toHaveAttribute("aria-pressed", "false");
+    await userEvent.click(boldBtn);
+    await expect(boldBtn).toHaveAttribute("aria-pressed", "true");
+    await userEvent.click(boldBtn);
+    await expect(boldBtn).toHaveAttribute("aria-pressed", "false");
+  },
+};
+
+/**
+ * Segmented mode switch — a single-select group on a recessed `bg-muted`
+ * track with a raised elevated active segment: the same elevation grammar
+ * as Tabs. Use it for exclusive view/mode controls (Read ↔ Write, editor
+ * source/split/wysiwyg) instead of the bordered toggle variants.
+ */
+export const Segmented: Story = {
+  render: () => (
+    <ToggleGroup
+      type="single"
+      variant="segmented"
+      size="sm"
+      defaultValue="read"
+      aria-label="Document mode"
+    >
+      <ToggleGroupItem value="read" aria-label="Read">
+        <BookOpen /> Read
+      </ToggleGroupItem>
+      <ToggleGroupItem value="write" aria-label="Write">
+        <PencilLine /> Write
+      </ToggleGroupItem>
+    </ToggleGroup>
+  ),
+};

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

@@ -0,0 +1,59 @@
+import {
+  createContext,
+  forwardRef,
+  useContext,
+  type ComponentPropsWithoutRef,
+  type ElementRef,
+} from "react";
+import * as ToggleGroupPrimitive from "@radix-ui/react-toggle-group";
+import { type VariantProps } from "class-variance-authority";
+import { cn } from "../../lib/cn";
+import { toggleVariants } from "../toggle";
+
+type ToggleVariantProps = VariantProps<typeof toggleVariants>;
+const ToggleGroupContext = createContext<ToggleVariantProps>({
+  size: "default",
+  variant: "default",
+});
+
+export const ToggleGroup = forwardRef<
+  ElementRef<typeof ToggleGroupPrimitive.Root>,
+  ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Root> & ToggleVariantProps
+>(function ToggleGroup({ className, variant, size, children, ...props }, ref) {
+  return (
+    <ToggleGroupPrimitive.Root
+      ref={ref}
+      className={cn(
+        "flex items-center gap-1",
+        // Segmented groups carry the TabsList track (recessed muted fill);
+        // the raised active segment comes from the item variant.
+        variant === "segmented" && "gap-0 rounded-lg bg-muted p-1 text-muted-foreground",
+        className,
+      )}
+      {...props}
+    >
+      <ToggleGroupContext.Provider value={{ variant, size }}>
+        {children}
+      </ToggleGroupContext.Provider>
+    </ToggleGroupPrimitive.Root>
+  );
+});
+
+export const ToggleGroupItem = forwardRef<
+  ElementRef<typeof ToggleGroupPrimitive.Item>,
+  ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Item> & ToggleVariantProps
+>(function ToggleGroupItem({ className, children, variant, size, ...props }, ref) {
+  const ctx = useContext(ToggleGroupContext);
+  return (
+    <ToggleGroupPrimitive.Item
+      ref={ref}
+      className={cn(
+        toggleVariants({ variant: ctx.variant ?? variant, size: ctx.size ?? size }),
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </ToggleGroupPrimitive.Item>
+  );
+});