@primitiv-ui/react 0.1.0

package/src/ToggleGroup/README.md

@@ -0,0 +1,137 @@
+# ToggleGroup
+
+A headless, accessible compound component that manages a group of pressable
+toggle buttons with roving-tabindex keyboard navigation.
+
+```tsx
+import { ToggleGroup } from "@primitiv-ui/react";
+
+<ToggleGroup.Root type="single" defaultValue="left" aria-label="Alignment">
+  <ToggleGroup.Item value="left">Left</ToggleGroup.Item>
+  <ToggleGroup.Item value="center">Center</ToggleGroup.Item>
+  <ToggleGroup.Item value="right">Right</ToggleGroup.Item>
+</ToggleGroup.Root>;
+```
+
+## Sub-components
+
+| Export              | Element    | Notes                                                        |
+| ------------------- | ---------- | ------------------------------------------------------------ |
+| `ToggleGroup.Root`  | `<div>`    | `role="group"`, context provider, `asChild`                  |
+| `ToggleGroup.Item`  | `<button>` | `aria-pressed`, `data-state`, roving tabindex, `asChild`     |
+
+## Type modes
+
+### `type="single"`
+
+At most one item is pressed at a time. Pressing the active item again
+**deselects** it — unlike a radio group, the value can return to `undefined`.
+
+```tsx
+// Uncontrolled
+<ToggleGroup.Root type="single" defaultValue="center" aria-label="Alignment">
+  …
+</ToggleGroup.Root>
+
+// Controlled — onValueChange receives string | undefined
+const [align, setAlign] = useState<string | undefined>("center");
+<ToggleGroup.Root type="single" value={align} onValueChange={setAlign} aria-label="Alignment">
+  …
+</ToggleGroup.Root>
+```
+
+### `type="multiple"`
+
+Any number of items can be pressed simultaneously. Each item toggles
+independently.
+
+```tsx
+// Uncontrolled
+<ToggleGroup.Root type="multiple" defaultValue={["bold"]} aria-label="Formatting">
+  …
+</ToggleGroup.Root>
+
+// Controlled — onValueChange receives string[]
+const [formats, setFormats] = useState<string[]>([]);
+<ToggleGroup.Root type="multiple" value={formats} onValueChange={setFormats} aria-label="Formatting">
+  …
+</ToggleGroup.Root>
+```
+
+## State modes
+
+Both type modes support **uncontrolled** (`defaultValue`) and **controlled**
+(`value` + `onValueChange`). The shapes are statically discriminated at the
+type level; TypeScript rejects mixing them.
+
+## Pressed state
+
+| `pressed` | `aria-pressed` | `data-state` |
+| --------- | -------------- | ------------ |
+| `true`    | `"true"`       | `"on"`       |
+| `false`   | `"false"`      | `"off"`      |
+
+## Keyboard interaction
+
+| Key             | Behaviour                                          |
+| --------------- | -------------------------------------------------- |
+| `ArrowRight` / `ArrowDown` | Focus next item (wraps)                 |
+| `ArrowLeft` / `ArrowUp`    | Focus previous item (wraps)             |
+| `Home`          | Focus first item                                   |
+| `End`           | Focus last item                                    |
+| `Space`         | Toggle the focused item                            |
+| `Enter`         | Toggle the focused item                            |
+
+Navigation is **decoupled from selection**: arrow keys move focus without
+toggling. Only `Space` / `Enter` (or a click) toggle the focused item.
+Only one item is in the document tab sequence at a time; `Tab` escapes
+the group in a single keystroke.
+
+## Reading direction
+
+Pass `dir` (`"ltr"` / `"rtl"`) to set the arrow-key direction for horizontal
+groups. When `dir` is omitted, it is inherited from the nearest
+[`DirectionProvider`](../DirectionProvider/README.md), falling back to `"ltr"`
+when there is no provider. An explicit `dir` prop always wins over the
+inherited value.
+
+## Disabled
+
+Passing `disabled` on an `Item` forwards the native `disabled` attribute
+(removing it from the tab order and suppressing clicks), sets
+`data-disabled=""` for CSS targeting, and excludes it from arrow-key
+navigation.
+
+```tsx
+<ToggleGroup.Item value="strikethrough" disabled>
+  Strikethrough
+</ToggleGroup.Item>
+```
+
+## `asChild` composition
+
+Both `Root` and `Item` accept `asChild`. When set, the component delegates
+rendering to its single child element and merges its own ARIA attributes,
+data-state, composed event handlers, and ref onto the child.
+
+## Styling hooks
+
+```css
+/* pressed item */
+[data-state="on"] {
+  background: oklch(65% 0.18 250);
+  color: white;
+}
+
+/* group orientation */
+[role="group"][data-orientation="horizontal"] {
+  display: flex;
+  flex-direction: row;
+}
+
+/* disabled */
+[data-disabled] {
+  opacity: 0.4;
+  cursor: not-allowed;
+}
+```

package/src/ToggleGroup/ToggleGroup.tsx

@@ -0,0 +1,298 @@
+import { useEffect, useMemo, useRef } from "react";
+
+import { useDirection } from "../DirectionProvider";
+import { useRovingTabindex } from "../hooks";
+import { Slot, composeEventHandlers, composeRefs } from "../Slot";
+
+import { ToggleGroupContext } from "./ToggleGroupContext";
+import { useToggleGroupRoot, useToggleGroupContext } from "./hooks";
+import { ToggleGroupItemProps, ToggleGroupRootProps } from "./types";
+
+/**
+ * The root of a ToggleGroup — a `<div role="group">` that owns the
+ * pressed values and provides {@link ToggleGroupContext} to descendant
+ * {@link ToggleGroupItem | `ToggleGroup.Item`}s.
+ *
+ * Two type modes, statically discriminated at the type level:
+ *
+ * - **`type="single"`** — at most one item can be pressed at a time.
+ *   Pressing the active item again deselects it (value returns to
+ *   `undefined`). Controlled via `value: string | undefined` +
+ *   `onValueChange: (value: string | undefined) => void`.
+ * - **`type="multiple"`** — any number of items can be pressed
+ *   simultaneously. Controlled via `value: string[]` +
+ *   `onValueChange: (value: string[]) => void`.
+ *
+ * Each type supports **uncontrolled** (pass `defaultValue`, or omit for
+ * nothing pressed on mount) and **controlled** (pass `value` +
+ * `onValueChange`) modes. The two shapes are statically discriminated at
+ * the type level.
+ *
+ * **Keyboard.** Arrow keys move focus between items (roving tabindex)
+ * independently of selection. `Space` / `Enter` toggle the focused item.
+ *
+ * **ARIA.** `role="group"` on the root. Each item carries `aria-pressed`.
+ *
+ * **Styling hooks.** `data-orientation="horizontal" | "vertical"` on the
+ * root. Each item: `data-state="on" | "off"`, `data-disabled=""`.
+ *
+ * **Reading direction.** `dir` (`"ltr"` / `"rtl"`) sets the arrow-key
+ * direction for horizontal groups. When omitted, it is inherited from the
+ * nearest {@link DirectionProvider}, falling back to `"ltr"` when there is
+ * no provider.
+ *
+ * **`asChild` prop.** Pass `asChild` to render any consumer-supplied
+ * element in place of the native `<div>`, with the group's `role`,
+ * `data-orientation`, and ref merged in.
+ *
+ * @example Single mode — text alignment
+ * ```tsx
+ * <ToggleGroup.Root type="single" defaultValue="left" aria-label="Alignment">
+ *   <ToggleGroup.Item value="left">Left</ToggleGroup.Item>
+ *   <ToggleGroup.Item value="center">Center</ToggleGroup.Item>
+ *   <ToggleGroup.Item value="right">Right</ToggleGroup.Item>
+ * </ToggleGroup.Root>
+ * ```
+ *
+ * @example Multiple mode — text formatting
+ * ```tsx
+ * <ToggleGroup.Root type="multiple" aria-label="Formatting">
+ *   <ToggleGroup.Item value="bold">Bold</ToggleGroup.Item>
+ *   <ToggleGroup.Item value="italic">Italic</ToggleGroup.Item>
+ * </ToggleGroup.Root>
+ * ```
+ */
+function ToggleGroupRoot({
+  type,
+  defaultValue,
+  value: controlledValue,
+  onValueChange,
+  orientation = "horizontal",
+  dir,
+  asChild = false,
+  children,
+  ref,
+  ...rest
+}: ToggleGroupRootProps) {
+  const resolvedDir = dir ?? useDirection();
+  const {
+    value,
+    toggle,
+    registerItem,
+    itemValues,
+    disabledValues,
+    focusItem,
+    focusedValue,
+    setFocusedValue,
+  } = useToggleGroupRoot({
+    type,
+    defaultValue,
+    value: controlledValue,
+    onValueChange,
+    orientation,
+    dir: resolvedDir,
+  });
+
+  const contextValue = useMemo(
+    () => ({
+      value,
+      toggle,
+      registerItem,
+      itemValues,
+      disabledValues,
+      focusItem,
+      focusedValue,
+      setFocusedValue,
+      orientation,
+      dir: resolvedDir,
+    }),
+    [
+      value,
+      toggle,
+      registerItem,
+      itemValues,
+      disabledValues,
+      focusItem,
+      focusedValue,
+      setFocusedValue,
+      orientation,
+      resolvedDir,
+    ],
+  );
+
+  const rootProps = {
+    ...rest,
+    ref,
+    role: "group" as const,
+    "data-orientation": orientation,
+  };
+
+  return (
+    <ToggleGroupContext.Provider value={contextValue}>
+      {asChild ? (
+        <Slot {...rootProps}>{children}</Slot>
+      ) : (
+        <div {...rootProps}>{children}</div>
+      )}
+    </ToggleGroupContext.Provider>
+  );
+}
+
+ToggleGroupRoot.displayName = "ToggleGroupRoot";
+
+/**
+ * An individual toggle button inside a ToggleGroup — a native
+ * `<button type="button" aria-pressed>` that participates in the
+ * group's roving tabindex and reports its pressed state.
+ *
+ * **Selection.** Clicking an Item (or pressing `Space` / `Enter` on
+ * the focused Item) toggles it. In `type="single"` mode, pressing an
+ * active item deselects it; in `type="multiple"` mode, items toggle
+ * independently.
+ *
+ * **Roving tabindex.** Arrow keys move focus between enabled items
+ * without changing selection. Only one Item is in the document tab
+ * sequence at a time; `Tab` escapes the group in a single keystroke.
+ *
+ * **Disabled.** Passing `disabled` forwards the native attribute and
+ * excludes the Item from arrow-key navigation. Use `data-disabled` for
+ * CSS targeting without `:disabled` specificity complications.
+ *
+ * **Styling hooks.** `data-state="on" | "off"` mirrors the pressed state.
+ * `data-disabled=""` when disabled.
+ *
+ * **`asChild` prop.** Pass `asChild` to render any consumer element in
+ * place of the native `<button>`, with the Item's `aria-pressed`,
+ * `data-state`, `tabIndex`, and event handlers merged onto it.
+ *
+ * @throws if rendered outside a `ToggleGroup.Root`.
+ */
+function ToggleGroupItem({
+  value,
+  disabled,
+  asChild = false,
+  onClick,
+  onKeyDown,
+  onFocus,
+  children,
+  ref,
+  ...rest
+}: ToggleGroupItemProps) {
+  const {
+    value: groupValue,
+    toggle,
+    registerItem,
+    itemValues,
+    disabledValues,
+    focusItem,
+    focusedValue,
+    setFocusedValue,
+    orientation,
+    dir,
+  } = useToggleGroupContext();
+
+  const isPressed = groupValue.includes(value);
+
+  const enabledValues = useMemo(
+    () => itemValues.filter((v) => !disabledValues.has(v)),
+    [itemValues, disabledValues],
+  );
+
+  // Tabstop: the focused item if known; otherwise fall back to the first
+  // enabled item so the group is reachable via Tab before any interaction.
+  const isTabstop =
+    focusedValue !== undefined
+      ? focusedValue === value
+      : enabledValues[0] === value;
+
+  const localRef = useRef<HTMLButtonElement | null>(null);
+  const setRef = useMemo(() => composeRefs(localRef, ref), [ref]);
+
+  useEffect(() => {
+    registerItem(value, localRef.current, disabled);
+    return () => registerItem(value, null);
+  }, [value, disabled, registerItem]);
+
+  const { handleKeyDown } = useRovingTabindex<string>({
+    orientation,
+    dir,
+    navigable: enabledValues,
+    currentKey: value,
+    includeHomeEnd: true,
+    includeActivate: true,
+    onNavigate: (target, action) => {
+      if (action === "activate") {
+        toggle(target);
+      }
+      focusItem(target);
+    },
+  });
+
+  const itemProps = {
+    ...rest,
+    ref: setRef,
+    "aria-pressed": isPressed,
+    "data-state": isPressed ? ("on" as const) : ("off" as const),
+    "data-disabled": disabled ? "" : undefined,
+    tabIndex: isTabstop ? 0 : -1,
+    disabled,
+    onClick: composeEventHandlers(onClick, () => toggle(value)),
+    onKeyDown: composeEventHandlers(onKeyDown, handleKeyDown),
+    onFocus: composeEventHandlers(onFocus, () => setFocusedValue(value)),
+  };
+
+  return asChild ? (
+    <Slot {...itemProps}>{children}</Slot>
+  ) : (
+    <button type="button" {...itemProps}>
+      {children}
+    </button>
+  );
+}
+
+ToggleGroupItem.displayName = "ToggleGroupItem";
+
+type TToggleGroupCompound = typeof ToggleGroupRoot & {
+  Root: typeof ToggleGroupRoot;
+  Item: typeof ToggleGroupItem;
+};
+
+/**
+ * Headless, accessible **ToggleGroup** — a compound component that
+ * manages a group of pressable toggle buttons with roving tabindex
+ * keyboard navigation.
+ *
+ * Supports `type="single"` (at most one item pressed, pressing again
+ * deselects) and `type="multiple"` (items toggle independently).
+ *
+ * `ToggleGroup` is both callable (an alias of
+ * {@link ToggleGroupRoot | `ToggleGroup.Root`}) and carries its
+ * sub-components as static properties.
+ *
+ * - {@link ToggleGroupRoot | `ToggleGroup.Root`} — state owner, context
+ *   provider, `<div role="group">` wrapper.
+ * - {@link ToggleGroupItem | `ToggleGroup.Item`} — a pressable toggle
+ *   button participating in the roving tabindex.
+ *
+ * @example Single mode — text alignment
+ * ```tsx
+ * import { ToggleGroup } from "@primitiv-ui/react";
+ *
+ * <ToggleGroup.Root type="single" defaultValue="left" aria-label="Alignment">
+ *   <ToggleGroup.Item value="left">Left</ToggleGroup.Item>
+ *   <ToggleGroup.Item value="center">Center</ToggleGroup.Item>
+ *   <ToggleGroup.Item value="right">Right</ToggleGroup.Item>
+ * </ToggleGroup.Root>;
+ * ```
+ *
+ * @see {@link ToggleGroupRoot} for type modes, state, and ARIA.
+ * @see {@link ToggleGroupItem} for selection, roving tabindex, and keyboard navigation.
+ */
+const ToggleGroupCompound: TToggleGroupCompound = Object.assign(ToggleGroupRoot, {
+  Root: ToggleGroupRoot,
+  Item: ToggleGroupItem,
+});
+
+ToggleGroupCompound.displayName = "ToggleGroup";
+
+export { ToggleGroupCompound as ToggleGroup };

package/src/ToggleGroup/ToggleGroupContext.ts

@@ -0,0 +1,9 @@
+import { createStrictContext } from "../utils";
+
+import { ToggleGroupContextValue } from "./types";
+
+export const [ToggleGroupContext, useToggleGroupContext] =
+  createStrictContext<ToggleGroupContextValue>(
+    "ToggleGroup.Item must be rendered inside a ToggleGroup.Root",
+    "ToggleGroupContext",
+  );

package/src/ToggleGroup/__tests__/ToggleGroup.asChild.test.tsx

@@ -0,0 +1,65 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { ToggleGroup } from "../ToggleGroup";
+
+describe("ToggleGroup asChild composition", () => {
+  it("Root asChild renders the consumer's element instead of <div>", () => {
+    render(
+      <ToggleGroup.Root type="single" asChild aria-label="Alignment">
+        <section>
+          <ToggleGroup.Item value="left">Left</ToggleGroup.Item>
+        </section>
+      </ToggleGroup.Root>,
+    );
+    const group = screen.getByRole("group", { name: "Alignment" });
+    expect(group.tagName).toBe("SECTION");
+  });
+
+  it("Root asChild merges role and data-orientation onto the child element", () => {
+    render(
+      <ToggleGroup.Root
+        type="single"
+        orientation="vertical"
+        asChild
+        aria-label="Alignment"
+      >
+        <section>
+          <ToggleGroup.Item value="left">Left</ToggleGroup.Item>
+        </section>
+      </ToggleGroup.Root>,
+    );
+    const group = screen.getByRole("group", { name: "Alignment" });
+    expect(group).toHaveAttribute("data-orientation", "vertical");
+  });
+
+  it("Item asChild renders the consumer's element instead of <button>", () => {
+    render(
+      <ToggleGroup.Root type="single" aria-label="Alignment">
+        <ToggleGroup.Item value="left" asChild>
+          <div>Left</div>
+        </ToggleGroup.Item>
+      </ToggleGroup.Root>,
+    );
+    const item = screen.getByLabelText("Alignment").querySelector("[data-state]");
+    expect(item?.tagName).toBe("DIV");
+    expect(item).toHaveAttribute("aria-pressed", "false");
+    expect(item).toHaveAttribute("data-state", "off");
+  });
+
+  it("Item asChild composes onClick with the toggle handler", async () => {
+    const user = userEvent.setup();
+    const consumerClick = vi.fn();
+    render(
+      <ToggleGroup.Root type="single" aria-label="Alignment">
+        <ToggleGroup.Item value="left" asChild onClick={consumerClick}>
+          <div>Left</div>
+        </ToggleGroup.Item>
+      </ToggleGroup.Root>,
+    );
+    const item = screen.getByLabelText("Alignment").querySelector("[data-state]")!;
+    await user.click(item);
+    expect(consumerClick).toHaveBeenCalledOnce();
+    expect(item).toHaveAttribute("aria-pressed", "true");
+  });
+});

package/src/ToggleGroup/__tests__/ToggleGroup.basic-rendering.test.tsx

@@ -0,0 +1,50 @@
+import { render, screen } from "@testing-library/react";
+
+import { ToggleGroup } from "../ToggleGroup";
+
+describe("ToggleGroup basic rendering", () => {
+  it('Root renders a <div role="group">', () => {
+    render(
+      <ToggleGroup.Root type="single" aria-label="Alignment">
+        <ToggleGroup.Item value="left">Left</ToggleGroup.Item>
+      </ToggleGroup.Root>,
+    );
+    expect(screen.getByRole("group", { name: "Alignment" })).toBeInTheDocument();
+  });
+
+  it('Item renders a <button type="button" aria-pressed>', () => {
+    render(
+      <ToggleGroup.Root type="single" aria-label="Alignment">
+        <ToggleGroup.Item value="left">Left</ToggleGroup.Item>
+      </ToggleGroup.Root>,
+    );
+    const item = screen.getByRole("button", { name: "Left" });
+    expect(item.tagName).toBe("BUTTON");
+    expect(item).toHaveAttribute("type", "button");
+    expect(item).toHaveAttribute("aria-pressed", "false");
+  });
+
+  it('Item defaults data-state to "off" when unpressed', () => {
+    render(
+      <ToggleGroup.Root type="single" aria-label="Alignment">
+        <ToggleGroup.Item value="left">Left</ToggleGroup.Item>
+      </ToggleGroup.Root>,
+    );
+    expect(screen.getByRole("button", { name: "Left" })).toHaveAttribute(
+      "data-state",
+      "off",
+    );
+  });
+
+  it('Root sets data-orientation="horizontal" by default', () => {
+    render(
+      <ToggleGroup.Root type="single" aria-label="Alignment">
+        <ToggleGroup.Item value="left">Left</ToggleGroup.Item>
+      </ToggleGroup.Root>,
+    );
+    expect(screen.getByRole("group", { name: "Alignment" })).toHaveAttribute(
+      "data-orientation",
+      "horizontal",
+    );
+  });
+});

package/src/ToggleGroup/__tests__/ToggleGroup.disabled.test.tsx

@@ -0,0 +1,54 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { ToggleGroup } from "../ToggleGroup";
+
+function Fixture({ disabledItem }: { disabledItem?: string }) {
+  return (
+    <ToggleGroup.Root type="single" aria-label="Alignment">
+      <ToggleGroup.Item value="left" disabled={disabledItem === "left"}>
+        Left
+      </ToggleGroup.Item>
+      <ToggleGroup.Item value="center" disabled={disabledItem === "center"}>
+        Center
+      </ToggleGroup.Item>
+      <ToggleGroup.Item value="right" disabled={disabledItem === "right"}>
+        Right
+      </ToggleGroup.Item>
+    </ToggleGroup.Root>
+  );
+}
+
+describe("ToggleGroup disabled item", () => {
+  it("sets the native disabled attribute on the item", () => {
+    render(<Fixture disabledItem="center" />);
+    expect(screen.getByRole("button", { name: "Center" })).toBeDisabled();
+  });
+
+  it('sets data-disabled="" on the disabled item', () => {
+    render(<Fixture disabledItem="center" />);
+    expect(screen.getByRole("button", { name: "Center" })).toHaveAttribute(
+      "data-disabled",
+      "",
+    );
+  });
+
+  it("does not toggle the disabled item when clicked", async () => {
+    const user = userEvent.setup();
+    render(<Fixture disabledItem="center" />);
+    await user.click(screen.getByRole("button", { name: "Center" }));
+    expect(screen.getByRole("button", { name: "Center" })).toHaveAttribute(
+      "aria-pressed",
+      "false",
+    );
+  });
+
+  it("skips disabled items during arrow key navigation", async () => {
+    const user = userEvent.setup();
+    render(<Fixture disabledItem="center" />);
+    screen.getByRole("button", { name: "Left" }).focus();
+    await user.keyboard("{ArrowRight}");
+    // Center is skipped — focus lands on Right
+    expect(screen.getByRole("button", { name: "Right" })).toHaveFocus();
+  });
+});