@primitiv-ui/react 0.1.37 → 0.1.39

package/dist/Tabs/types.d.ts

@@ -0,0 +1,139 @@
+import { ComponentProps, Ref } from "react";
+/** Layout axis of the tab list. `"horizontal"` arranges triggers in a row and
+ * binds ArrowLeft/ArrowRight; `"vertical"` stacks them and binds
+ * ArrowUp/ArrowDown. */
+export type TabsOrientation = "horizontal" | "vertical";
+/** Reading direction of the tab list. In `"rtl"` the horizontal arrow keys are
+ * mirrored so navigation follows the visual order. */
+export type TabsReadingDirection = "ltr" | "rtl";
+/** When a focused trigger becomes active. `"automatic"` activates a tab as soon
+ * as it receives focus via the arrow keys; `"manual"` requires Enter/Space. */
+export type TabsActivationMode = "automatic" | "manual";
+/**
+ * Payload delivered to the {@link BaseTabsRootProps.onChange | `onChange`} callback
+ * on every user-driven tab activation.
+ *
+ * - `index` — zero-based position of the activated trigger in registration order.
+ * - `name`  — the programmatic **value** string passed to `Tabs.Trigger` (e.g.
+ *   `"settings"`), **not** the human-readable label text rendered inside the
+ *   trigger. Use the `children` of the trigger for the visible label.
+ */
+export type TabMetadata = {
+    index: number;
+    name: string;
+};
+/** Props common to both controlled and uncontrolled `Tabs.Root` usage. */
+export type BaseTabsRootProps = {
+    /** Fired on every user-driven activation with the activated tab's metadata. */
+    onChange?: ({ index, name }: TabMetadata) => void;
+};
+/** Uncontrolled `Tabs.Root` props: the component owns the active tab, seeded by
+ * an optional `defaultValue`. Mutually exclusive with the controlled props. */
+export type UncontrolledTabsRootProps = {
+    /** Value of the tab active on first render. */
+    defaultValue?: string;
+    value?: never;
+    onValueChange?: never;
+};
+/** Controlled `Tabs.Root` props: the caller owns the active tab via `value` and
+ * is notified of activation requests through `onValueChange`. */
+export type ControlledTabsRootProps = {
+    /** Value of the currently active tab. */
+    value: string;
+    /** Called with the requested value when the user activates a tab. */
+    onValueChange: (value: string) => void;
+    defaultValue?: never;
+};
+/** Props for `Tabs.Root` — the state owner and context provider. Extends the
+ * native `<div>` props (minus `onChange`) and resolves to either the
+ * controlled or uncontrolled prop shape.
+ *
+ * `ref` is omitted from the inherited `<div>` props deliberately: `Tabs.Root`
+ * is a `forwardRef` component whose ref is the {@link TabsImperativeApi}
+ * imperative handle, **not** the underlying `HTMLDivElement`. The component
+ * type re-adds the correct `ref` via `RefAttributes<TabsImperativeApi>`. Were
+ * the `HTMLDivElement` `ref` left in, a styled wrapper that spreads these props
+ * straight back into `Tabs.Root` (`<Tabs.Root {...props} />`) would fail to
+ * type-check on incompatible `ref` types (D58). */
+export type TabsRootProps = Omit<ComponentProps<"div">, "onChange" | "ref" | "dir" | "defaultValue"> & {
+    /** Layout axis; see {@link TabsOrientation}.
+     * @default "horizontal" */
+    orientation?: TabsOrientation;
+    /** Reading direction; see {@link TabsReadingDirection}. Inherited from the
+     * nearest `DirectionProvider` when omitted, falling back to `"ltr"`. */
+    dir?: TabsReadingDirection;
+    /** When a focused trigger becomes active; see {@link TabsActivationMode}.
+     * @default "automatic" */
+    activationMode?: TabsActivationMode;
+    /** When `true`, a panel's children are not rendered until that tab is first
+     * activated. Once mounted they remain in the DOM across subsequent tab
+     * switches (lazy mount, not unmount-on-hide). Useful for panels that own
+     * expensive initialisation — e.g. a scroll-snap carousel whose initial
+     * scroll position must be set while the panel is visible. */
+    lazyMount?: boolean;
+} & BaseTabsRootProps & (UncontrolledTabsRootProps | ControlledTabsRootProps);
+/** The value shared by `Tabs.Root` with its descendants through context:
+ * resolved configuration, the active tab and its setter, and the registry of
+ * triggers used for roving focus and keyboard navigation. */
+export type TabsContextValue = {
+    orientation: TabsOrientation;
+    dir: TabsReadingDirection;
+    activationMode: TabsActivationMode;
+    activeValue: string | undefined;
+    isControlled: boolean;
+    setActiveValue: (next: string) => void;
+    onValueChange?: (value: string) => void;
+    onChange?: ({ index, name }: TabMetadata) => void;
+    tabsId: string;
+    lazyMount: boolean;
+    registerTrigger: (value: string, element: HTMLButtonElement | null, disabled?: boolean) => void;
+    triggerValues: string[];
+    disabledTriggerValues: Set<string>;
+    focusTrigger: (value: string) => void;
+};
+/** Props for `Tabs.List` — the `role="tablist"` container. Requires exactly one
+ * accessible name source: either an inline `label` or an `ariaLabelledBy` id
+ * referencing existing label text. */
+export type TabsListProps = Omit<ComponentProps<"div">, "label" | "aria-labelledby"> & ({
+    /** Accessible name for the tablist, announced as `aria-label`. Pick a
+     * short, human-readable description of the set (e.g. `"Account
+     * sections"`, not `"Tabs"`). Mutually exclusive with `ariaLabelledBy`. */
+    label: string;
+    ariaLabelledBy?: never;
+} | {
+    label?: never;
+    /** Id of an existing element to use as the tablist's accessible name,
+     * set as `aria-labelledby`. Mutually exclusive with `label`. */
+    ariaLabelledBy: string;
+});
+/** Props for `Tabs.Trigger` — an individual `role="tab"` button. Identified by
+ * its required `value`, which links it to the `Tabs.Content` of the same value.
+ * The element type defaults to `HTMLButtonElement` and can be overridden via
+ * `asChild` and the `ref` type parameter. */
+export type TabsTriggerProps<T extends HTMLElement = HTMLButtonElement> = Omit<ComponentProps<"button">, "ref" | "value"> & {
+    /** Removes the trigger from the roving tab order and marks it
+     * `aria-disabled`/`data-disabled`; arrow-key navigation skips it.
+     * @default false */
+    disabled?: boolean;
+    /** Identifies this trigger, linking it to the `Tabs.Content` of the same
+     * value. Not the visible label — use `children` for that. */
+    value: string;
+    /** Render the child element instead of the default `<button>`. All tab
+     * ARIA attributes and event handlers are merged onto the child. The child
+     * must accept a `ref`. Useful for routing links that need tab semantics. */
+    asChild?: boolean;
+    /** Ref to the rendered element. Defaults to `HTMLButtonElement`; when using
+     * `asChild`, specify the child's element type (e.g. `HTMLAnchorElement`). */
+    ref?: Ref<T>;
+};
+/** Props for `Tabs.Content` — a `role="tabpanel"`. Its required `value` links
+ * it to the `Tabs.Trigger` of the same value. */
+export type TabsContentProps = ComponentProps<"div"> & {
+    /** Value of the trigger this panel belongs to. */
+    value: string;
+};
+/** Imperative handle exposed on the `Tabs.Root` ref for programmatic control. */
+export type TabsImperativeApi = {
+    /** Activate the tab with the given value. */
+    setActiveTab: (value: string) => void;
+};

package/dist/Tabs/types.js

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

package/dist/Tabs/utils.d.ts

@@ -0,0 +1,4 @@
+export declare function getTriggerAndPanelIds(tabsId: string, value: string): {
+    triggerId: string;
+    panelId: string;
+};

package/dist/Tabs/utils.js

@@ -0,0 +1,8 @@
+"use client";
+import { deriveId } from "../utils/index.js";
+export function getTriggerAndPanelIds(tabsId, value) {
+    return {
+        triggerId: deriveId(tabsId, "trigger", value),
+        panelId: deriveId(tabsId, "panel", value),
+    };
+}

package/dist/Textarea/Textarea.d.ts

@@ -0,0 +1,81 @@
+import type { ReactElement } from "react";
+import { TextareaProps } from "./types.js";
+/**
+ * A headless, accessible multi-line text input.
+ *
+ * Renders a native `<textarea>` and passes every standard textarea
+ * attribute straight through to the DOM — `value` / `defaultValue`,
+ * `rows`, `cols`, `placeholder`, `readOnly`, `required`, `name`,
+ * `maxLength`, and so on. No styles ship with the component.
+ *
+ * **Labelling.** A `<textarea>` has no implicit accessible name. Pair it
+ * with a `<label>` (`htmlFor` → the textarea's `id`), or pass `aria-label`
+ * / `aria-labelledby` for the control to be announced correctly.
+ *
+ * **Field integration.** When rendered inside a `<Field.Root>`, Textarea
+ * opts into `FieldContext` and inherits `id`, `aria-describedby`,
+ * `aria-invalid`, `disabled`, and `required` from the field. Any prop
+ * the consumer passes wins; `aria-describedby` is composed (consumer
+ * ids first, then field-supplied description / error ids). Outside a
+ * `<Field.Root>`, behaviour is unchanged.
+ *
+ * **Ref forwarding.** Pass a `ref` prop to access the underlying
+ * `HTMLTextAreaElement` directly:
+ *
+ * ```tsx
+ * const ref = useRef<HTMLTextAreaElement>(null);
+ * <Textarea ref={ref} aria-label="Bio" />
+ * ```
+ *
+ * **Disabled.** Sets native `disabled` (removing the field from the tab
+ * order and blocking input) plus `data-disabled=""` so CSS can target
+ * `[data-disabled]` without relying on the `:disabled` pseudo-class:
+ *
+ * ```css
+ * textarea[data-disabled] { opacity: 0.5; cursor: not-allowed; }
+ * ```
+ *
+ * **Styling hooks.**
+ * - `data-disabled=""` — present when `disabled` is `true`; omitted otherwise.
+ *   Target with `[data-disabled]` rather than the `:disabled` pseudo-class so
+ *   styles work identically in both native and `asChild` modes.
+ *
+ * **`asChild` composition.** Renders the consumer's element instead of
+ * `<textarea>`, merging all props (aria-*, data-*, event handlers, ref)
+ * via the {@link Slot} utility. Use it to wrap an autosizing textarea
+ * implementation while keeping this component's prop contract. Event handlers
+ * compose with the child's own handlers (child runs first).
+ *
+ * @extends HTMLTextAreaElement
+ *
+ * @example Basic usage
+ * ```tsx
+ * <label htmlFor="bio">Bio</label>
+ * <Textarea id="bio" rows={4} placeholder="Tell us about yourself" />
+ * ```
+ *
+ * @example Inside a Field — id and aria wired automatically
+ * ```tsx
+ * <Field.Root invalid={!!errors.bio}>
+ *   <Field.Label>Bio</Field.Label>
+ *   <Textarea rows={4} {...register("bio")} />
+ *   <Field.ErrorText>{errors.bio?.message}</Field.ErrorText>
+ * </Field.Root>
+ * ```
+ *
+ * @example Disabled
+ * ```tsx
+ * <Textarea aria-label="Bio" disabled />
+ * ```
+ *
+ * @example asChild — wrap an autosizing textarea
+ * ```tsx
+ * <Textarea asChild aria-label="Bio">
+ *   <AutosizeTextarea />
+ * </Textarea>
+ * ```
+ */
+export declare function Textarea({ asChild, children, ref, ...consumer }: TextareaProps): ReactElement;
+export declare namespace Textarea {
+    var displayName: string;
+}

package/dist/Textarea/Textarea.js

@@ -0,0 +1,93 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useFieldProps } from "../Field/hooks/index.js";
+import { Slot } from "../Slot/index.js";
+/**
+ * A headless, accessible multi-line text input.
+ *
+ * Renders a native `<textarea>` and passes every standard textarea
+ * attribute straight through to the DOM — `value` / `defaultValue`,
+ * `rows`, `cols`, `placeholder`, `readOnly`, `required`, `name`,
+ * `maxLength`, and so on. No styles ship with the component.
+ *
+ * **Labelling.** A `<textarea>` has no implicit accessible name. Pair it
+ * with a `<label>` (`htmlFor` → the textarea's `id`), or pass `aria-label`
+ * / `aria-labelledby` for the control to be announced correctly.
+ *
+ * **Field integration.** When rendered inside a `<Field.Root>`, Textarea
+ * opts into `FieldContext` and inherits `id`, `aria-describedby`,
+ * `aria-invalid`, `disabled`, and `required` from the field. Any prop
+ * the consumer passes wins; `aria-describedby` is composed (consumer
+ * ids first, then field-supplied description / error ids). Outside a
+ * `<Field.Root>`, behaviour is unchanged.
+ *
+ * **Ref forwarding.** Pass a `ref` prop to access the underlying
+ * `HTMLTextAreaElement` directly:
+ *
+ * ```tsx
+ * const ref = useRef<HTMLTextAreaElement>(null);
+ * <Textarea ref={ref} aria-label="Bio" />
+ * ```
+ *
+ * **Disabled.** Sets native `disabled` (removing the field from the tab
+ * order and blocking input) plus `data-disabled=""` so CSS can target
+ * `[data-disabled]` without relying on the `:disabled` pseudo-class:
+ *
+ * ```css
+ * textarea[data-disabled] { opacity: 0.5; cursor: not-allowed; }
+ * ```
+ *
+ * **Styling hooks.**
+ * - `data-disabled=""` — present when `disabled` is `true`; omitted otherwise.
+ *   Target with `[data-disabled]` rather than the `:disabled` pseudo-class so
+ *   styles work identically in both native and `asChild` modes.
+ *
+ * **`asChild` composition.** Renders the consumer's element instead of
+ * `<textarea>`, merging all props (aria-*, data-*, event handlers, ref)
+ * via the {@link Slot} utility. Use it to wrap an autosizing textarea
+ * implementation while keeping this component's prop contract. Event handlers
+ * compose with the child's own handlers (child runs first).
+ *
+ * @extends HTMLTextAreaElement
+ *
+ * @example Basic usage
+ * ```tsx
+ * <label htmlFor="bio">Bio</label>
+ * <Textarea id="bio" rows={4} placeholder="Tell us about yourself" />
+ * ```
+ *
+ * @example Inside a Field — id and aria wired automatically
+ * ```tsx
+ * <Field.Root invalid={!!errors.bio}>
+ *   <Field.Label>Bio</Field.Label>
+ *   <Textarea rows={4} {...register("bio")} />
+ *   <Field.ErrorText>{errors.bio?.message}</Field.ErrorText>
+ * </Field.Root>
+ * ```
+ *
+ * @example Disabled
+ * ```tsx
+ * <Textarea aria-label="Bio" disabled />
+ * ```
+ *
+ * @example asChild — wrap an autosizing textarea
+ * ```tsx
+ * <Textarea asChild aria-label="Bio">
+ *   <AutosizeTextarea />
+ * </Textarea>
+ * ```
+ */
+export function Textarea({ asChild = false, children, ref, ...consumer }) {
+    const merged = useFieldProps(consumer);
+    const rootProps = {
+        ...merged,
+        ref,
+        "data-disabled": merged.disabled ? "" : undefined,
+    };
+    if (asChild) {
+        return _jsx(Slot, { ...rootProps, children: children });
+    }
+    return _jsx("textarea", { ...rootProps });
+}
+/** @internal */
+Textarea.displayName = "Textarea";

package/dist/Textarea/index.d.ts

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

package/dist/Textarea/index.js

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

package/dist/Textarea/types.d.ts

@@ -0,0 +1,27 @@
+import { ComponentProps, ReactNode, Ref } from "react";
+/**
+ * Props for {@link Textarea} — all native `<textarea>` attributes (with `ref`
+ * typed as `Ref<HTMLTextAreaElement>`) plus the `asChild` escape hatch.
+ */
+export type TextareaProps = Omit<ComponentProps<"textarea">, "ref"> & {
+    /**
+     * Renders the child element instead of a native `<textarea>`, merging all
+     * props — aria-*, data-*, event handlers, ref — onto it via {@link Slot}.
+     * Event handlers compose (child runs first). Use this to wrap a third-party
+     * autosizing textarea while keeping this component's prop contract.
+     * @default false
+     */
+    asChild?: boolean;
+    /**
+     * Forwarded to the underlying `HTMLTextAreaElement`. Under `asChild`, merged
+     * onto the rendered child via {@link Slot}.
+     */
+    ref?: Ref<HTMLTextAreaElement>;
+    /**
+     * Child content. Under `asChild`, must be a single React element that
+     * {@link Slot} merges props onto. Not used when rendering a native
+     * `<textarea>` (the element's content is controlled by `value` /
+     * `defaultValue`, not children).
+     */
+    children?: ReactNode;
+};

package/dist/Textarea/types.js

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

package/dist/Toggle/Toggle.d.ts

@@ -0,0 +1,82 @@
+import type { ReactElement } from "react";
+import { ToggleProps } from "./types.js";
+/**
+ * A stateful toggle button implementing the
+ * [WAI-ARIA Button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/)
+ * with the `aria-pressed` attribute. Renders a native
+ * `<button type="button">` by default.
+ *
+ * **Controlled vs uncontrolled.** Two state modes, statically discriminated at
+ * the type level so TypeScript rejects mixing them:
+ *
+ * - **Uncontrolled** — pass
+ *   {@link ToggleProps.defaultPressed | `defaultPressed`} (or omit entirely
+ *   for unpressed on mount). The component owns the pressed value internally.
+ * - **Controlled** — pass {@link ToggleProps.pressed | `pressed`} *and*
+ *   {@link ToggleProps.onPressedChange | `onPressedChange`} together. The
+ *   parent owns the value; every click defers back through the callback.
+ *
+ * **Keyboard support.** Keyboard activation is provided natively by the
+ * underlying `<button>` element — no custom `keydown` listeners are needed:
+ *
+ * | Key     | Behaviour                              |
+ * | ------- | -------------------------------------- |
+ * | `Space` | Toggles the button (native `<button>`) |
+ * | `Enter` | Toggles the button (native `<button>`) |
+ *
+ * **Styling hooks.**
+ * - `data-state="on" | "off"` — mirrors the pressed state; use
+ *   `[data-state="on"]` to style the active appearance.
+ * - `data-disabled=""` — set when `disabled` is `true`; lets CSS target
+ *   `[data-disabled]` without relying on the `:disabled` pseudo-class.
+ *
+ * **`asChild` composition.** Pass `asChild` to render any consumer-supplied
+ * element instead of the default `<button>`. The toggle's `aria-pressed`,
+ * `data-state`, composed `onClick`, and `ref` are merged onto the child via
+ * {@link Slot}. The native `<button>` is dropped; the consumer is responsible
+ * for making the element focusable (e.g. `tabIndex={0}`, `role="button"`).
+ *
+ * **Ref forwarding.** Pass a `ref` prop to access the underlying
+ * `HTMLButtonElement` directly (or the `asChild` element when `asChild` is
+ * set):
+ *
+ * ```tsx
+ * const ref = useRef<HTMLButtonElement>(null);
+ * <Toggle ref={ref} aria-label="Bold">B</Toggle>
+ * ```
+ *
+ * **Disabled.** Sets the native `disabled` attribute (removing the button
+ * from the tab order and suppressing clicks) **and** sets `data-disabled=""`
+ * so CSS can target `[data-disabled]` without relying on `:disabled`.
+ *
+ * @extends HTMLButtonElement
+ *
+ * @example Uncontrolled
+ * ```tsx
+ * <Toggle aria-label="Bold" defaultPressed>B</Toggle>
+ * ```
+ *
+ * @example Controlled
+ * ```tsx
+ * const [bold, setBold] = useState(false);
+ *
+ * <Toggle pressed={bold} onPressedChange={setBold} aria-label="Bold">B</Toggle>
+ * ```
+ *
+ * @example Disabled
+ * ```tsx
+ * <Toggle disabled aria-label="Bold (unavailable)">B</Toggle>
+ * ```
+ *
+ * @example asChild — render a custom element with toggle semantics
+ * ```tsx
+ * <Toggle asChild aria-label="Bold">
+ *   <div role="button" tabIndex={0}>B</div>
+ * </Toggle>
+ * ```
+ */
+declare function Toggle({ defaultPressed, pressed: controlledPressed, onPressedChange, disabled, asChild, onClick, children, ref, ...rest }: ToggleProps): ReactElement;
+declare namespace Toggle {
+    var displayName: string;
+}
+export { Toggle };

package/dist/Toggle/Toggle.js

@@ -0,0 +1,102 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useControllableState } from "../hooks/index.js";
+import { Slot, composeEventHandlers } from "../Slot/index.js";
+/**
+ * A stateful toggle button implementing the
+ * [WAI-ARIA Button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/)
+ * with the `aria-pressed` attribute. Renders a native
+ * `<button type="button">` by default.
+ *
+ * **Controlled vs uncontrolled.** Two state modes, statically discriminated at
+ * the type level so TypeScript rejects mixing them:
+ *
+ * - **Uncontrolled** — pass
+ *   {@link ToggleProps.defaultPressed | `defaultPressed`} (or omit entirely
+ *   for unpressed on mount). The component owns the pressed value internally.
+ * - **Controlled** — pass {@link ToggleProps.pressed | `pressed`} *and*
+ *   {@link ToggleProps.onPressedChange | `onPressedChange`} together. The
+ *   parent owns the value; every click defers back through the callback.
+ *
+ * **Keyboard support.** Keyboard activation is provided natively by the
+ * underlying `<button>` element — no custom `keydown` listeners are needed:
+ *
+ * | Key     | Behaviour                              |
+ * | ------- | -------------------------------------- |
+ * | `Space` | Toggles the button (native `<button>`) |
+ * | `Enter` | Toggles the button (native `<button>`) |
+ *
+ * **Styling hooks.**
+ * - `data-state="on" | "off"` — mirrors the pressed state; use
+ *   `[data-state="on"]` to style the active appearance.
+ * - `data-disabled=""` — set when `disabled` is `true`; lets CSS target
+ *   `[data-disabled]` without relying on the `:disabled` pseudo-class.
+ *
+ * **`asChild` composition.** Pass `asChild` to render any consumer-supplied
+ * element instead of the default `<button>`. The toggle's `aria-pressed`,
+ * `data-state`, composed `onClick`, and `ref` are merged onto the child via
+ * {@link Slot}. The native `<button>` is dropped; the consumer is responsible
+ * for making the element focusable (e.g. `tabIndex={0}`, `role="button"`).
+ *
+ * **Ref forwarding.** Pass a `ref` prop to access the underlying
+ * `HTMLButtonElement` directly (or the `asChild` element when `asChild` is
+ * set):
+ *
+ * ```tsx
+ * const ref = useRef<HTMLButtonElement>(null);
+ * <Toggle ref={ref} aria-label="Bold">B</Toggle>
+ * ```
+ *
+ * **Disabled.** Sets the native `disabled` attribute (removing the button
+ * from the tab order and suppressing clicks) **and** sets `data-disabled=""`
+ * so CSS can target `[data-disabled]` without relying on `:disabled`.
+ *
+ * @extends HTMLButtonElement
+ *
+ * @example Uncontrolled
+ * ```tsx
+ * <Toggle aria-label="Bold" defaultPressed>B</Toggle>
+ * ```
+ *
+ * @example Controlled
+ * ```tsx
+ * const [bold, setBold] = useState(false);
+ *
+ * <Toggle pressed={bold} onPressedChange={setBold} aria-label="Bold">B</Toggle>
+ * ```
+ *
+ * @example Disabled
+ * ```tsx
+ * <Toggle disabled aria-label="Bold (unavailable)">B</Toggle>
+ * ```
+ *
+ * @example asChild — render a custom element with toggle semantics
+ * ```tsx
+ * <Toggle asChild aria-label="Bold">
+ *   <div role="button" tabIndex={0}>B</div>
+ * </Toggle>
+ * ```
+ */
+function Toggle({ defaultPressed, pressed: controlledPressed, onPressedChange, disabled, asChild = false, onClick, children, ref, ...rest }) {
+    const [pressed, setPressed] = useControllableState(controlledPressed, defaultPressed ?? false);
+    const toggle = () => {
+        const next = !pressed;
+        setPressed(next);
+        onPressedChange?.(next);
+    };
+    const toggleProps = {
+        ...rest,
+        ref,
+        "aria-pressed": pressed,
+        "data-state": pressed ? "on" : "off",
+        "data-disabled": disabled ? "" : undefined,
+        disabled,
+        onClick: composeEventHandlers(onClick, toggle),
+    };
+    if (asChild)
+        return _jsx(Slot, { ...toggleProps, children: children });
+    return (_jsx("button", { type: "button", ...toggleProps, children: children }));
+}
+/** @internal */
+Toggle.displayName = "Toggle";
+export { Toggle };

package/dist/Toggle/index.d.ts

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

package/dist/Toggle/index.js

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

package/dist/Toggle/types.d.ts

@@ -0,0 +1,72 @@
+import { ButtonHTMLAttributes, ReactNode, Ref } from "react";
+/**
+ * Uncontrolled {@link Toggle} props: seed the initial pressed state with
+ * `defaultPressed`; `pressed` and `onPressedChange` are disallowed in this
+ * mode. The component owns the pressed value internally.
+ */
+export type UncontrolledToggleProps = {
+    /**
+     * The pressed state on first render. Omit to start unpressed.
+     * Mutually exclusive with {@link ControlledToggleProps.pressed | `pressed`}.
+     * @default false
+     */
+    defaultPressed?: boolean;
+    pressed?: never;
+    onPressedChange?: never;
+};
+/**
+ * Controlled {@link Toggle} props: drive the pressed state with `pressed` and
+ * respond to toggle requests via `onPressedChange`; `defaultPressed` is
+ * disallowed in this mode. The parent owns the value.
+ */
+export type ControlledToggleProps = {
+    /**
+     * The current pressed state, owned by the caller. Every click fires
+     * {@link ControlledToggleProps.onPressedChange | `onPressedChange`} with the
+     * next value — the component does not update state itself.
+     */
+    pressed: boolean;
+    /**
+     * Called with the next pressed value when the user clicks the toggle.
+     * The caller is responsible for updating the `pressed` prop accordingly.
+     */
+    onPressedChange: (pressed: boolean) => void;
+    defaultPressed?: never;
+};
+/**
+ * Props common to both controlled and uncontrolled {@link Toggle} modes:
+ * `disabled`, `asChild`, `children`, `ref`, and all native `<button>`
+ * attributes except `type` (which is fixed to `"button"` by the component).
+ */
+export type ToggleBaseProps = {
+    /**
+     * When `true`, sets the native `disabled` attribute (removing the button
+     * from the tab order and suppressing clicks) and adds `data-disabled=""`
+     * so CSS can target `[data-disabled]` without relying on `:disabled`.
+     */
+    disabled?: boolean;
+    /**
+     * Renders the child element instead of the default `<button>`, merging
+     * `aria-pressed`, `data-state`, the composed `onClick`, and `ref` onto
+     * it via {@link Slot}. The child must be focusable (e.g. carry
+     * `tabIndex={0}` and `role="button"`).
+     * @default false
+     */
+    asChild?: boolean;
+    /** Toggle content — text, icons, or any React node. */
+    children?: ReactNode;
+    /**
+     * Forwarded to the underlying `HTMLButtonElement`, or — under
+     * `asChild` — merged onto the rendered child element.
+     */
+    ref?: Ref<HTMLButtonElement>;
+} & Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type">;
+/**
+ * Props for the {@link Toggle} button — {@link ToggleBaseProps} combined with
+ * the controlled/uncontrolled discriminated union
+ * ({@link ControlledToggleProps} | {@link UncontrolledToggleProps}).
+ *
+ * TypeScript statically rejects mixing controlled and uncontrolled props
+ * (e.g. passing both `pressed` and `defaultPressed`).
+ */
+export type ToggleProps = ToggleBaseProps & (UncontrolledToggleProps | ControlledToggleProps);

package/dist/Toggle/types.js

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