@primitiv-ui/react 0.1.38 → 0.1.39

package/dist/ToggleGroup/ToggleGroup.d.ts

@@ -0,0 +1,144 @@
+import type { ReactElement } from "react";
+import { ToggleGroupItemProps, ToggleGroupRootProps } from "./types.js";
+/**
+ * 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.
+ *
+ * @extends HTMLDivElement
+ *
+ * @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>
+ * ```
+ */
+export declare function ToggleGroupRoot({ type, defaultValue, value: controlledValue, onValueChange, orientation, dir, asChild, children, ref, ...rest }: ToggleGroupRootProps): ReactElement;
+export declare namespace ToggleGroupRoot {
+    var displayName: string;
+}
+/**
+ * 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. The child
+ * must accept a `ref`. Useful for a link or a styled control that needs
+ * toggle-button semantics.
+ *
+ * @throws if rendered outside a `ToggleGroup.Root`.
+ *
+ * @extends HTMLButtonElement
+ *
+ * @example
+ * ```tsx
+ * <ToggleGroup.Item value="bold">Bold</ToggleGroup.Item>
+ * <ToggleGroup.Item value="strike" disabled>Strikethrough</ToggleGroup.Item>
+ * ```
+ */
+export declare function ToggleGroupItem({ value, disabled, asChild, onClick, onKeyDown, onFocus, children, ref, ...rest }: ToggleGroupItemProps): ReactElement;
+export declare namespace ToggleGroupItem {
+    var displayName: string;
+}
+/**
+ * The shape of the exported `ToggleGroup` value — callable as
+ * `ToggleGroup.Root` and carrying `Root` and `Item` as static properties.
+ */
+export 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.
+ */
+declare const ToggleGroupCompound: TToggleGroupCompound;
+export { ToggleGroupCompound as ToggleGroup };

package/dist/ToggleGroup/ToggleGroup.js

@@ -0,0 +1,227 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef } from "react";
+import { useDirection } from "../DirectionProvider/index.js";
+import { useRovingTabindex } from "../hooks/index.js";
+import { Slot, composeEventHandlers, composeRefs } from "../Slot/index.js";
+import { ToggleGroupContext } from "./ToggleGroupContext.js";
+import { useToggleGroupRoot, useToggleGroupContext } from "./hooks/index.js";
+/**
+ * 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.
+ *
+ * @extends HTMLDivElement
+ *
+ * @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>
+ * ```
+ */
+export function ToggleGroupRoot({ type, defaultValue, value: controlledValue, onValueChange, orientation = "horizontal", dir, asChild = false, children, ref, ...rest }) {
+    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",
+        "data-orientation": orientation,
+    };
+    return (_jsx(ToggleGroupContext.Provider, { value: contextValue, children: asChild ? (_jsx(Slot, { ...rootProps, children: children })) : (_jsx("div", { ...rootProps, children: children })) }));
+}
+/** @internal */
+// Stryker disable next-line StringLiteral: overwritten by the compound alias — an equivalent mutant.
+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. The child
+ * must accept a `ref`. Useful for a link or a styled control that needs
+ * toggle-button semantics.
+ *
+ * @throws if rendered outside a `ToggleGroup.Root`.
+ *
+ * @extends HTMLButtonElement
+ *
+ * @example
+ * ```tsx
+ * <ToggleGroup.Item value="bold">Bold</ToggleGroup.Item>
+ * <ToggleGroup.Item value="strike" disabled>Strikethrough</ToggleGroup.Item>
+ * ```
+ */
+export function ToggleGroupItem({ value, disabled, asChild = false, onClick, onKeyDown, onFocus, children, ref, ...rest }) {
+    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(null);
+    const setRef = useMemo(() => composeRefs(localRef, ref), [ref]);
+    useEffect(() => {
+        registerItem(value, localRef.current, disabled);
+        return () => registerItem(value, null);
+    }, [value, disabled, registerItem]);
+    const { handleKeyDown } = useRovingTabindex({
+        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" : "off",
+        "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 ? (_jsx(Slot, { ...itemProps, children: children })) : (_jsx("button", { type: "button", ...itemProps, children: children }));
+}
+/** @internal */
+ToggleGroupItem.displayName = "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 = Object.assign(ToggleGroupRoot, {
+    Root: ToggleGroupRoot,
+    Item: ToggleGroupItem,
+});
+ToggleGroupCompound.displayName = "ToggleGroup";
+export { ToggleGroupCompound as ToggleGroup };

package/dist/ToggleGroup/ToggleGroupContext.d.ts

@@ -0,0 +1,2 @@
+import { ToggleGroupContextValue } from "./types.js";
+export declare const ToggleGroupContext: import("react").Context<ToggleGroupContextValue | null>, useToggleGroupContext: () => ToggleGroupContextValue;

package/dist/ToggleGroup/ToggleGroupContext.js

@@ -0,0 +1,3 @@
+"use client";
+import { createStrictContext } from "../utils/index.js";
+export const [ToggleGroupContext, useToggleGroupContext] = createStrictContext("ToggleGroup.Item must be rendered inside a ToggleGroup.Root", "ToggleGroupContext");

package/dist/ToggleGroup/hooks/index.d.ts

@@ -0,0 +1,2 @@
+export { useToggleGroupRoot } from "./useToggleGroupRoot.js";
+export { useToggleGroupContext } from "./useToggleGroupContext.js";

package/dist/ToggleGroup/hooks/index.js

@@ -0,0 +1,2 @@
+export { useToggleGroupRoot } from "./useToggleGroupRoot.js";
+export { useToggleGroupContext } from "./useToggleGroupContext.js";

package/dist/ToggleGroup/hooks/useToggleGroupContext.d.ts

@@ -0,0 +1 @@
+export { useToggleGroupContext } from "../ToggleGroupContext.js";

package/dist/ToggleGroup/hooks/useToggleGroupContext.js

@@ -0,0 +1 @@
+export { useToggleGroupContext } from "../ToggleGroupContext.js";

package/dist/ToggleGroup/hooks/useToggleGroupRoot.d.ts

@@ -0,0 +1,21 @@
+type UseToggleGroupRootArgs = {
+    type: "single" | "multiple";
+    defaultValue?: string | string[];
+    value?: string | string[] | undefined;
+    onValueChange?: ((v: string | undefined) => void) | ((v: string[]) => void);
+    orientation: "horizontal" | "vertical";
+    dir: "ltr" | "rtl";
+};
+export declare function useToggleGroupRoot({ type, defaultValue, value: rawControlled, onValueChange, orientation, dir, }: UseToggleGroupRootArgs): {
+    value: string[];
+    toggle: (itemValue: string) => void;
+    registerItem: (itemValue: string, element: HTMLButtonElement | null, disabled?: boolean) => void;
+    itemValues: string[];
+    disabledValues: Set<string>;
+    focusItem: (itemValue: string) => void;
+    focusedValue: string | undefined;
+    setFocusedValue: import("react").Dispatch<import("react").SetStateAction<string | undefined>>;
+    orientation: "horizontal" | "vertical";
+    dir: "ltr" | "rtl";
+};
+export {};

package/dist/ToggleGroup/hooks/useToggleGroupRoot.js

@@ -0,0 +1,79 @@
+"use client";
+import { useCallback, useMemo, useState } from "react";
+import { useCollection, useControllableState } from "../../hooks/index.js";
+function toArray(v) {
+    if (v === undefined)
+        return [];
+    if (typeof v === "string")
+        return [v];
+    return v;
+}
+export function useToggleGroupRoot({ type, defaultValue, value: rawControlled, onValueChange, orientation, dir, }) {
+    const isControlled = onValueChange !== undefined;
+    const normalizedControlled = isControlled ? toArray(rawControlled) : undefined;
+    const normalizedDefault = toArray(defaultValue);
+    const [value, setValue] = useControllableState(normalizedControlled, normalizedDefault);
+    const toggle = useCallback((itemValue) => {
+        const isSelected = value.includes(itemValue);
+        if (type === "single") {
+            // Deselecting clears the selection to the empty array. Stryker's
+            // ArrayDeclaration mutant fills this with a phantom value, but since
+            // that value can never equal a registered item's `value` — and single
+            // mode always overwrites the whole array on the next selection — no
+            // item ever reads it as pressed. The mutation is observationally
+            // identical, so it is isolated here to keep the disable off the tested
+            // `[itemValue]` literal below.
+            // Stryker disable next-line ArrayDeclaration
+            const cleared = [];
+            const next = isSelected ? cleared : [itemValue];
+            setValue(next);
+            onValueChange?.(isSelected ? undefined : itemValue);
+        }
+        else {
+            const next = isSelected
+                ? value.filter((v) => v !== itemValue)
+                : [...value, itemValue];
+            setValue(next);
+            onValueChange?.(next);
+        }
+    }, [type, value, setValue, onValueChange]);
+    const { register: registerBase, itemsRef, keys: itemValues, } = useCollection();
+    const registerItem = useCallback((itemValue, element, disabled = false) => {
+        registerBase(itemValue, element ? { element, disabled } : null);
+    }, 
+    // `registerBase` is a stable useCollection callback (its own deps never
+    // change), so emptying this array yields the identical memoised function.
+    // Stryker disable next-line ArrayDeclaration: equivalent — stable dependency.
+    [registerBase]);
+    const disabledValues = useMemo(() => new Set(Array.from(itemsRef.current.entries())
+        .filter(([, meta]) => meta.disabled)
+        .map(([v]) => v)), [itemValues, itemsRef]);
+    const focusItem = useCallback((itemValue) => {
+        // `itemValue` is always sourced from `navigable` (the enabled subset of
+        // `itemValues`), and useCollection's register() writes `itemsRef` and the
+        // `itemValues` state together — so a value that reaches here is guaranteed
+        // to have a live entry in the map.
+        // Stryker disable next-line OptionalChaining: unreachable given that invariant.
+        itemsRef.current.get(itemValue)?.element.focus();
+    }, 
+    // `itemsRef` is a stable RefObject, so emptying this array yields the
+    // identical memoised function.
+    // Stryker disable next-line ArrayDeclaration: equivalent — stable dependency.
+    [itemsRef]);
+    // Tracks which item holds the tabstop. Initialises to the first pressed
+    // value so the selected item is immediately tabbable. Updated via the
+    // onFocus handler in each Item so the tabstop follows actual focus.
+    const [focusedValue, setFocusedValue] = useState(() => value[0]);
+    return {
+        value,
+        toggle,
+        registerItem,
+        itemValues,
+        disabledValues,
+        focusItem,
+        focusedValue,
+        setFocusedValue,
+        orientation,
+        dir,
+    };
+}

package/dist/ToggleGroup/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./ToggleGroup.js";
+export * from "./types.js";

package/dist/ToggleGroup/index.js

@@ -0,0 +1,2 @@
+export * from "./ToggleGroup.js";
+export * from "./types.js";

package/dist/ToggleGroup/types.d.ts

@@ -0,0 +1,141 @@
+import { HTMLAttributes, ButtonHTMLAttributes, ReactNode, Ref } from "react";
+/**
+ * Mode-independent props shared by every `ToggleGroup.Root` variant —
+ * orientation, direction, `asChild`, children, and the ref. Combined with
+ * a mode-specific arm to form {@link ToggleGroupRootProps}.
+ */
+export type ToggleGroupRootBaseProps = Omit<HTMLAttributes<HTMLDivElement>, "dir" | "defaultValue"> & {
+    /** Layout axis for keyboard navigation. `"horizontal"` binds
+     * ArrowLeft/ArrowRight; `"vertical"` binds ArrowUp/ArrowDown. Surfaces as
+     * `data-orientation` on the root for styling; it does not itself apply any
+     * flex/grid layout.
+     * @default "horizontal" */
+    orientation?: "horizontal" | "vertical";
+    /** Reading direction. In `"rtl"` the horizontal arrow keys are mirrored so
+     * focus follows the visual order. Inherited from the nearest
+     * {@link DirectionProvider} when omitted, falling back to `"ltr"`. */
+    dir?: "ltr" | "rtl";
+    /** Render a single consumer-supplied element in place of the native
+     * `<div>`, with the group's `role="group"`, `data-orientation`, and `ref`
+     * merged onto it via the {@link Slot} pattern.
+     * @default false */
+    asChild?: boolean;
+    /** The {@link ToggleGroupItemProps | `ToggleGroup.Item`} elements that make
+     * up the segmented control. */
+    children?: ReactNode;
+    /** Forwarded to the underlying `HTMLDivElement`. */
+    ref?: Ref<HTMLDivElement>;
+};
+/**
+ * Single-selection mode, uncontrolled — at most one item pressed, with the
+ * initial value supplied via `defaultValue`.
+ */
+export type SingleUncontrolledProps = {
+    /** Selects single-selection semantics: at most one item pressed at a time,
+     * and pressing the active item again clears the selection. */
+    type: "single";
+    /** Value of the item pressed on first render. Omit to start with nothing
+     * pressed. */
+    defaultValue?: string;
+    /** Forbidden in uncontrolled mode — use `defaultValue`. */
+    value?: never;
+    /** Forbidden in uncontrolled mode. */
+    onValueChange?: never;
+};
+/**
+ * Single-selection mode, controlled — the pressed value is owned by the
+ * caller via `value` / `onValueChange`.
+ */
+export type SingleControlledProps = {
+    /** Selects single-selection semantics: at most one item pressed at a time,
+     * and pressing the active item again clears the selection. */
+    type: "single";
+    /** The currently pressed item's value, or `undefined` when none is pressed.
+     * Must be kept in sync by the caller via `onValueChange`. */
+    value: string | undefined;
+    /** Called with the requested next value — the pressed item's value, or
+     * `undefined` when the active item is pressed again to deselect it. */
+    onValueChange: (value: string | undefined) => void;
+    /** Forbidden in controlled mode — use `value`. */
+    defaultValue?: never;
+};
+/**
+ * Multiple-selection mode, uncontrolled — items toggle independently, with
+ * the initial set supplied via `defaultValue`.
+ */
+export type MultipleUncontrolledProps = {
+    /** Selects multiple-selection semantics: any number of items can be pressed
+     * simultaneously and each toggles independently. */
+    type: "multiple";
+    /** Values of the items pressed on first render. Omit to start with nothing
+     * pressed. */
+    defaultValue?: string[];
+    /** Forbidden in uncontrolled mode — use `defaultValue`. */
+    value?: never;
+    /** Forbidden in uncontrolled mode. */
+    onValueChange?: never;
+};
+/**
+ * Multiple-selection mode, controlled — the set of pressed values is owned
+ * by the caller via `value` / `onValueChange`.
+ */
+export type MultipleControlledProps = {
+    /** Selects multiple-selection semantics: any number of items can be pressed
+     * simultaneously and each toggles independently. */
+    type: "multiple";
+    /** The full set of currently pressed item values. Must be kept in sync by
+     * the caller via `onValueChange`. */
+    value: string[];
+    /** Called with the complete next array of pressed values whenever the user
+     * toggles any item. */
+    onValueChange: (value: string[]) => void;
+    /** Forbidden in controlled mode — use `value`. */
+    defaultValue?: never;
+};
+/**
+ * Props for `ToggleGroup.Root`. Combines the shared
+ * {@link ToggleGroupRootBaseProps} with one mode-specific arm — single or
+ * multiple, controlled or uncontrolled — so the `value` / `defaultValue` /
+ * `onValueChange` shape is enforced per `type`.
+ */
+export type ToggleGroupRootProps = ToggleGroupRootBaseProps & (SingleUncontrolledProps | SingleControlledProps | MultipleUncontrolledProps | MultipleControlledProps);
+/**
+ * Props for `ToggleGroup.Item` — a pressable toggle button. `value`
+ * identifies the item within the group; `asChild` merges the behaviour
+ * onto a custom child element.
+ */
+export type ToggleGroupItemProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type" | "value"> & {
+    /** Identifies this item within the group. It is this string — not the
+     * visible label — that is compared against the group's pressed
+     * `value` / `defaultValue`; use `children` for the label. */
+    value: string;
+    /** Forwards the native `disabled` attribute and removes the item from the
+     * roving tab order so arrow-key navigation skips it. Also sets
+     * `data-disabled=""` for CSS targeting.
+     * @default false */
+    disabled?: boolean;
+    /** Render a single consumer-supplied element in place of the native
+     * `<button>`, with the item's `aria-pressed`, `data-state`, `tabIndex`, and
+     * event handlers merged onto it via the {@link Slot} pattern.
+     * @default false */
+    asChild?: boolean;
+    /** Forwarded to the underlying `HTMLButtonElement`. */
+    ref?: Ref<HTMLButtonElement>;
+};
+/**
+ * Context shared from `ToggleGroup.Root` to its items — the pressed
+ * values, the toggle action, item registration for roving tabindex, and
+ * the resolved orientation / direction.
+ */
+export type ToggleGroupContextValue = {
+    value: string[];
+    toggle: (itemValue: string) => void;
+    registerItem: (itemValue: string, element: HTMLButtonElement | null, disabled?: boolean) => void;
+    itemValues: string[];
+    disabledValues: Set<string>;
+    focusItem: (itemValue: string) => void;
+    focusedValue: string | undefined;
+    setFocusedValue: (itemValue: string) => void;
+    orientation: "horizontal" | "vertical";
+    dir: "ltr" | "rtl";
+};

package/dist/ToggleGroup/types.js

@@ -0,0 +1 @@
+export {};