@primitiv-ui/react 0.1.38 → 0.1.39

package/dist/Status/types.d.ts

@@ -0,0 +1,19 @@
+import { ComponentProps, ReactNode } from "react";
+/**
+ * Props for {@link Status} — all native `<div>` attributes plus the
+ * `asChild` escape hatch.
+ */
+export type StatusProps = ComponentProps<"div"> & {
+    /**
+     * Renders the child element instead of a native `<div>`, merging
+     * `role="status"` and all other props onto it via {@link Slot}.
+     * Event handlers compose with the child's own handlers (child runs
+     * first). Use this to apply the live-region role to a semantically
+     * appropriate element (e.g. `<output>`).
+     * @default false
+     */
+    asChild?: boolean;
+    /** Content to announce. A live region announces changes that occur
+     * after the region is already present in the DOM. */
+    children?: ReactNode;
+};

package/dist/Status/types.js

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

package/dist/Switch/Switch.d.ts

@@ -0,0 +1,122 @@
+import type { ReactElement } from "react";
+import { SwitchRootProps, SwitchThumbProps } from "./types.js";
+/**
+ * The root of a Switch — a `<label>` that is itself the **visible track** and
+ * wraps a **real, visually-hidden `<input type="checkbox" role="switch">`**
+ * (the focusable, form-participating control) plus the
+ * {@link SwitchThumb | `Switch.Thumb`}. It provides
+ * {@link SwitchContext | `SwitchContext`} to the thumb.
+ *
+ * Because the underlying element is a genuine native checkbox (with the switch
+ * role), it behaves like a real form field: it submits its `value` under `name`
+ * with an enclosing form, resets with it, and gets keyboard activation and
+ * focus for free. Semantically it represents an immediate on/off action.
+ *
+ * Props routing: `className` / `style` style the **track** (the `<label>` you
+ * see — the input is hidden); every other prop (`name`, `value`, `id`,
+ * `aria-*`, `required`, `disabled`, `ref`, ...) spreads onto the input, because
+ * semantically the Root *is* the switch.
+ *
+ * Supports two state modes, statically discriminated at the type level:
+ *
+ * - **Uncontrolled** — pass `defaultChecked` (or omit). The browser owns the
+ *   value, so the switch participates in forms and resets.
+ * - **Controlled** — pass `checked` *and* `onCheckedChange` together.
+ *
+ * **Styling hooks.** `data-state="checked" | "unchecked"` and `data-disabled=""`
+ * on the track (and `data-state` on the thumb). These mirror the input, but
+ * shipped CSS positions the thumb off the input's native `:checked` instead;
+ * `data-state` is a convenience mirror.
+ *
+ * **Keyboard.** Toggles on `Space` (the native checkbox behaviour); `Enter`
+ * does not toggle a checkbox-based control.
+ *
+ * **`onChange` composition.** The consumer's raw `onChange` fires first; if it
+ * calls `event.preventDefault()`, the internal mirror update and
+ * `onCheckedChange` are skipped for that event. See {@link SwitchRootBaseProps}.
+ *
+ * @extends HTMLInputElement
+ *
+ * @example Uncontrolled
+ * ```tsx
+ * <Switch.Root name="notify" value="on" defaultChecked aria-label="Enable notifications">
+ *   <Switch.Thumb />
+ * </Switch.Root>
+ * ```
+ *
+ * @example Controlled
+ * ```tsx
+ * const [enabled, setEnabled] = useState(false);
+ *
+ * <Switch.Root checked={enabled} onCheckedChange={setEnabled} aria-label="...">
+ *   <Switch.Thumb />
+ * </Switch.Root>
+ * ```
+ */
+export declare function SwitchRoot({ className, style, defaultChecked, checked, onCheckedChange, onChange, disabled, children, ref, ...inputRest }: SwitchRootProps): ReactElement;
+export declare namespace SwitchRoot {
+    var displayName: string;
+}
+/**
+ * A decorative `<span aria-hidden="true">` representing the sliding thumb of
+ * the switch. Always mounted — its position is driven entirely by CSS, which
+ * should key off the input's native `:checked` so it stays correct through a
+ * form reset.
+ *
+ * **Styling hook.** Mirrors the root's `data-state="checked" | "unchecked"`.
+ *
+ * **`asChild` prop.** Pass `asChild` to render the consumer's own element as
+ * the thumb, with `aria-hidden` and `data-state` merged in via the
+ * {@link Slot} pattern. See {@link SwitchThumbProps}.
+ *
+ * @extends HTMLSpanElement
+ *
+ * @example
+ * ```tsx
+ * <Switch.Root aria-label="Enable notifications">
+ *   <Switch.Thumb />
+ * </Switch.Root>
+ * ```
+ *
+ * @throws if rendered outside a `Switch.Root`.
+ */
+export declare function SwitchThumb({ children, asChild, ...rest }: SwitchThumbProps): ReactElement;
+export declare namespace SwitchThumb {
+    var displayName: string;
+}
+/** Type of the {@link Switch} compound — the Root callable plus its sub-components. */
+export type TSwitchCompound = typeof SwitchRoot & {
+    /** The root track, owning checked state and context. */
+    Root: typeof SwitchRoot;
+    /** The sliding thumb indicator. */
+    Thumb: typeof SwitchThumb;
+};
+/**
+ * Headless, accessible **Switch** — a compound component built on a **real,
+ * visually-hidden native `<input type="checkbox" role="switch">`**. Unlike a
+ * button dressed up with `role="switch"`, it participates in native forms.
+ * Semantically represents an immediate on/off action (as opposed to a selection
+ * choice). Zero styles ship.
+ *
+ * `Switch` is both callable (an alias of
+ * {@link SwitchRoot | `Switch.Root`}) and carries its sub-components as
+ * static properties.
+ *
+ * - {@link SwitchRoot | `Switch.Root`} — the track: label + hidden input, state owner, context provider.
+ * - {@link SwitchThumb | `Switch.Thumb`} — always-mounted decorative thumb;
+ *   position driven by CSS (the input's native `:checked`).
+ *
+ * @example Minimal usage
+ * ```tsx
+ * import { Switch } from "@primitiv-ui/react";
+ *
+ * <Switch.Root name="notify" value="on" aria-label="Enable notifications">
+ *   <Switch.Thumb />
+ * </Switch.Root>
+ * ```
+ *
+ * @see {@link SwitchRoot} for state modes and form participation.
+ * @see {@link SwitchThumb} for styling the sliding thumb.
+ */
+declare const SwitchCompound: TSwitchCompound;
+export { SwitchCompound as Switch };

package/dist/Switch/Switch.js

@@ -0,0 +1,143 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { Slot } from "../Slot/index.js";
+import { SwitchContext } from "./SwitchContext.js";
+import { useSwitchContext, useSwitchRoot } from "./hooks/index.js";
+function dataStateOf(checked) {
+    return checked ? "checked" : "unchecked";
+}
+/**
+ * The root of a Switch — a `<label>` that is itself the **visible track** and
+ * wraps a **real, visually-hidden `<input type="checkbox" role="switch">`**
+ * (the focusable, form-participating control) plus the
+ * {@link SwitchThumb | `Switch.Thumb`}. It provides
+ * {@link SwitchContext | `SwitchContext`} to the thumb.
+ *
+ * Because the underlying element is a genuine native checkbox (with the switch
+ * role), it behaves like a real form field: it submits its `value` under `name`
+ * with an enclosing form, resets with it, and gets keyboard activation and
+ * focus for free. Semantically it represents an immediate on/off action.
+ *
+ * Props routing: `className` / `style` style the **track** (the `<label>` you
+ * see — the input is hidden); every other prop (`name`, `value`, `id`,
+ * `aria-*`, `required`, `disabled`, `ref`, ...) spreads onto the input, because
+ * semantically the Root *is* the switch.
+ *
+ * Supports two state modes, statically discriminated at the type level:
+ *
+ * - **Uncontrolled** — pass `defaultChecked` (or omit). The browser owns the
+ *   value, so the switch participates in forms and resets.
+ * - **Controlled** — pass `checked` *and* `onCheckedChange` together.
+ *
+ * **Styling hooks.** `data-state="checked" | "unchecked"` and `data-disabled=""`
+ * on the track (and `data-state` on the thumb). These mirror the input, but
+ * shipped CSS positions the thumb off the input's native `:checked` instead;
+ * `data-state` is a convenience mirror.
+ *
+ * **Keyboard.** Toggles on `Space` (the native checkbox behaviour); `Enter`
+ * does not toggle a checkbox-based control.
+ *
+ * **`onChange` composition.** The consumer's raw `onChange` fires first; if it
+ * calls `event.preventDefault()`, the internal mirror update and
+ * `onCheckedChange` are skipped for that event. See {@link SwitchRootBaseProps}.
+ *
+ * @extends HTMLInputElement
+ *
+ * @example Uncontrolled
+ * ```tsx
+ * <Switch.Root name="notify" value="on" defaultChecked aria-label="Enable notifications">
+ *   <Switch.Thumb />
+ * </Switch.Root>
+ * ```
+ *
+ * @example Controlled
+ * ```tsx
+ * const [enabled, setEnabled] = useState(false);
+ *
+ * <Switch.Root checked={enabled} onCheckedChange={setEnabled} aria-label="...">
+ *   <Switch.Thumb />
+ * </Switch.Root>
+ * ```
+ */
+export function SwitchRoot({ className, style, defaultChecked, checked, onCheckedChange, onChange, disabled, children, ref, ...inputRest }) {
+    const { checked: isChecked, handleChange, inputStateProps, } = useSwitchRoot({ defaultChecked, checked, onCheckedChange, onChange });
+    const contextValue = useMemo(() => ({ checked: isChecked, disabled: Boolean(disabled) }), [isChecked, disabled]);
+    return (_jsx(SwitchContext.Provider, { value: contextValue, children: _jsxs("label", { className: className, style: style, "data-state": dataStateOf(isChecked), "data-disabled": disabled ? "" : undefined, children: [_jsx("input", { type: "checkbox", role: "switch", ref: ref, disabled: disabled, ...inputRest, ...inputStateProps, onChange: handleChange }), children] }) }));
+}
+// Runtime-dead: the compound alias below (same object via Object.assign)
+// overwrites this to "Switch" at load, so the value is never observable. The
+// assignment stays because it declares `displayName` on `typeof SwitchRoot`,
+// which TSwitchCompound extends.
+// Stryker disable next-line StringLiteral: overwritten by the compound alias — an equivalent mutant.
+SwitchRoot.displayName = "SwitchRoot";
+/**
+ * A decorative `<span aria-hidden="true">` representing the sliding thumb of
+ * the switch. Always mounted — its position is driven entirely by CSS, which
+ * should key off the input's native `:checked` so it stays correct through a
+ * form reset.
+ *
+ * **Styling hook.** Mirrors the root's `data-state="checked" | "unchecked"`.
+ *
+ * **`asChild` prop.** Pass `asChild` to render the consumer's own element as
+ * the thumb, with `aria-hidden` and `data-state` merged in via the
+ * {@link Slot} pattern. See {@link SwitchThumbProps}.
+ *
+ * @extends HTMLSpanElement
+ *
+ * @example
+ * ```tsx
+ * <Switch.Root aria-label="Enable notifications">
+ *   <Switch.Thumb />
+ * </Switch.Root>
+ * ```
+ *
+ * @throws if rendered outside a `Switch.Root`.
+ */
+export function SwitchThumb({ children, asChild = false, ...rest }) {
+    const { checked } = useSwitchContext();
+    const thumbProps = {
+        ...rest,
+        "aria-hidden": "true",
+        "data-state": dataStateOf(checked),
+    };
+    if (asChild) {
+        return _jsx(Slot, { ...thumbProps, children: children });
+    }
+    return _jsx("span", { ...thumbProps, children: children });
+}
+/** @internal */
+SwitchThumb.displayName = "SwitchThumb";
+/**
+ * Headless, accessible **Switch** — a compound component built on a **real,
+ * visually-hidden native `<input type="checkbox" role="switch">`**. Unlike a
+ * button dressed up with `role="switch"`, it participates in native forms.
+ * Semantically represents an immediate on/off action (as opposed to a selection
+ * choice). Zero styles ship.
+ *
+ * `Switch` is both callable (an alias of
+ * {@link SwitchRoot | `Switch.Root`}) and carries its sub-components as
+ * static properties.
+ *
+ * - {@link SwitchRoot | `Switch.Root`} — the track: label + hidden input, state owner, context provider.
+ * - {@link SwitchThumb | `Switch.Thumb`} — always-mounted decorative thumb;
+ *   position driven by CSS (the input's native `:checked`).
+ *
+ * @example Minimal usage
+ * ```tsx
+ * import { Switch } from "@primitiv-ui/react";
+ *
+ * <Switch.Root name="notify" value="on" aria-label="Enable notifications">
+ *   <Switch.Thumb />
+ * </Switch.Root>
+ * ```
+ *
+ * @see {@link SwitchRoot} for state modes and form participation.
+ * @see {@link SwitchThumb} for styling the sliding thumb.
+ */
+const SwitchCompound = Object.assign(SwitchRoot, {
+    Root: SwitchRoot,
+    Thumb: SwitchThumb,
+});
+SwitchCompound.displayName = "Switch";
+export { SwitchCompound as Switch };

package/dist/Switch/SwitchContext.d.ts

@@ -0,0 +1,12 @@
+import type { Context } from "react";
+/** Value shared from `Switch.Root` to `Switch.Thumb` through context. */
+export type SwitchContextValue = {
+    /** Whether the switch is currently checked (best-effort mirror of the input). */
+    checked: boolean;
+    /** Whether the switch is disabled, for the `data-disabled` hook. */
+    disabled: boolean;
+};
+/** React context carrying the {@link SwitchContextValue} for `Switch.Thumb`. */
+export declare const SwitchContext: Context<SwitchContextValue | null>;
+/** Read the nearest {@link SwitchContextValue}; throws outside `Switch.Root`. */
+export declare const useSwitchContext: () => SwitchContextValue;

package/dist/Switch/SwitchContext.js

@@ -0,0 +1,7 @@
+"use client";
+import { createStrictContext } from "../utils/index.js";
+const switchContextPair = createStrictContext("Switch.Thumb must be rendered inside a <Switch.Root>.");
+/** React context carrying the {@link SwitchContextValue} for `Switch.Thumb`. */
+export const SwitchContext = switchContextPair[0];
+/** Read the nearest {@link SwitchContextValue}; throws outside `Switch.Root`. */
+export const useSwitchContext = switchContextPair[1];

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

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

package/dist/Switch/hooks/index.js

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

package/dist/Switch/hooks/useSwitchContext.d.ts

@@ -0,0 +1 @@
+export { useSwitchContext } from "../SwitchContext.js";

package/dist/Switch/hooks/useSwitchContext.js

@@ -0,0 +1 @@
+export { useSwitchContext } from "../SwitchContext.js";

package/dist/Switch/hooks/useSwitchRoot.d.ts

@@ -0,0 +1,30 @@
+import type { ChangeEvent } from "react";
+import { SwitchChangeHandler } from "../types.js";
+type UseSwitchRootArgs = {
+    defaultChecked?: boolean;
+    checked?: boolean;
+    onCheckedChange?: (checked: boolean) => void;
+    onChange?: SwitchChangeHandler;
+};
+/**
+ * Resolves the controlled / uncontrolled state for a {@link Switch.Root} and
+ * produces the props to spread onto its native `<input type="checkbox"
+ * role="switch">`.
+ *
+ * In uncontrolled mode the input is rendered with `defaultChecked` and no
+ * `checked` prop, so the browser owns the value and the switch participates in
+ * forms and resets. The returned `checked` is a best-effort mirror for the
+ * `data-state` hook, updated from the input's own `change` events.
+ */
+export declare function useSwitchRoot({ defaultChecked, checked: controlledChecked, onCheckedChange, onChange, }: UseSwitchRootArgs): {
+    checked: boolean;
+    handleChange: (event: ChangeEvent<HTMLInputElement>) => void;
+    inputStateProps: {
+        checked: boolean;
+        defaultChecked?: undefined;
+    } | {
+        defaultChecked: boolean;
+        checked?: undefined;
+    };
+};
+export {};

package/dist/Switch/hooks/useSwitchRoot.js

@@ -0,0 +1,33 @@
+"use client";
+import { useState } from "react";
+/**
+ * Resolves the controlled / uncontrolled state for a {@link Switch.Root} and
+ * produces the props to spread onto its native `<input type="checkbox"
+ * role="switch">`.
+ *
+ * In uncontrolled mode the input is rendered with `defaultChecked` and no
+ * `checked` prop, so the browser owns the value and the switch participates in
+ * forms and resets. The returned `checked` is a best-effort mirror for the
+ * `data-state` hook, updated from the input's own `change` events.
+ */
+export function useSwitchRoot({ defaultChecked, checked: controlledChecked, onCheckedChange, onChange, }) {
+    const isControlled = controlledChecked !== undefined;
+    const [mirror, setMirror] = useState(defaultChecked ?? false);
+    const checked = isControlled ? controlledChecked : mirror;
+    const handleChange = (event) => {
+        onChange?.(event);
+        if (event.defaultPrevented)
+            return;
+        const next = event.target.checked;
+        // Stryker disable next-line ConditionalExpression: in controlled mode
+        // `checked` reads controlledChecked, never `mirror`, so setting mirror here
+        // (the mutant's always-run form) has no observable effect — equivalent.
+        if (!isControlled)
+            setMirror(next);
+        onCheckedChange?.(next);
+    };
+    const inputStateProps = isControlled
+        ? { checked: controlledChecked }
+        : { defaultChecked: defaultChecked ?? false };
+    return { checked, handleChange, inputStateProps };
+}

package/dist/Switch/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./Switch.js";
+export * from "./SwitchContext.js";
+export * from "./types.js";

package/dist/Switch/index.js

@@ -0,0 +1,3 @@
+export * from "./Switch.js";
+export * from "./SwitchContext.js";
+export * from "./types.js";

package/dist/Switch/types.d.ts

@@ -0,0 +1,83 @@
+import { ChangeEventHandler, ComponentProps, ReactNode, Ref } from "react";
+/**
+ * Shared base for both {@link SwitchRootProps} variants — the native
+ * `<input type="checkbox">` attributes (minus the ones the component owns:
+ * `type`, `role`, `checked`, and `defaultChecked`), plus `children` and a
+ * typed `ref`.
+ *
+ * Prop routing: `className` / `style` style the **track** (the visible
+ * `<label>`, since the input is visually hidden); every other prop — `name`,
+ * `value`, `id`, `aria-*`, `required`, `disabled`, `ref`, ... — spreads onto the
+ * hidden `<input>`, because semantically the Root *is* the switch.
+ */
+export type SwitchRootBaseProps = Omit<ComponentProps<"input">, "type" | "role" | "checked" | "defaultChecked"> & {
+    /** Content of the switch — typically a single
+     * {@link SwitchThumbProps | `Switch.Thumb`}. */
+    children?: ReactNode;
+    /** Forwarded to the underlying native `HTMLInputElement` (the real,
+     * visually-hidden checkbox), not the visible track. */
+    ref?: Ref<HTMLInputElement>;
+};
+/**
+ * Uncontrolled variant of {@link SwitchRootProps}: the **browser** owns the
+ * checked state, so the switch participates in native form submission and
+ * reset. Pass `defaultChecked` (or omit it); `checked` is forbidden.
+ */
+export type SwitchRootUncontrolledProps = SwitchRootBaseProps & {
+    /** Checked state on first render. Defaults to `false` when omitted.
+     * @default false */
+    defaultChecked?: boolean;
+    /** Forbidden in uncontrolled mode — use `defaultChecked` instead. */
+    checked?: never;
+    /** Called with the new boolean state whenever the switch toggles. Optional
+     * in uncontrolled mode. */
+    onCheckedChange?: (checked: boolean) => void;
+};
+/**
+ * Controlled variant of {@link SwitchRootProps}: the parent owns the checked
+ * value. Pass `checked` and `onCheckedChange` together; `defaultChecked` is
+ * forbidden.
+ */
+export type SwitchRootControlledProps = SwitchRootBaseProps & {
+    /** Forbidden in controlled mode — use `checked` instead. */
+    defaultChecked?: never;
+    /** The controlled checked state. Must be kept in sync by the parent via
+     * `onCheckedChange`. */
+    checked: boolean;
+    /** Called with the new boolean state whenever the user requests a toggle.
+     * Required in controlled mode. */
+    onCheckedChange: (checked: boolean) => void;
+};
+/**
+ * Props for {@link SwitchRoot | `Switch.Root`}.
+ *
+ * Resolves to either {@link SwitchRootUncontrolledProps} or
+ * {@link SwitchRootControlledProps} — only one shape is accepted by TypeScript
+ * at a time.
+ */
+export type SwitchRootProps = SwitchRootUncontrolledProps | SwitchRootControlledProps;
+/**
+ * The Switch's props, named to the `<Component>Props` convention the generated
+ * styled wrapper imports (mirrors {@link ButtonProps}). An alias of the Root's
+ * props, since `Switch` is callable as {@link SwitchRootProps | `Switch.Root`}.
+ */
+export type SwitchProps = SwitchRootProps;
+/**
+ * Props for {@link SwitchThumb | `Switch.Thumb`} — the decorative sliding
+ * indicator inside the track. All `HTMLSpanElement` attributes, plus the
+ * `asChild` escape hatch.
+ */
+export type SwitchThumbProps = ComponentProps<"span"> & {
+    /** Optional thumb content (rarely needed — the thumb is usually styled
+     * purely with CSS). */
+    children?: ReactNode;
+    /**
+     * When `true`, render the consumer's own element as the thumb instead of the
+     * default `<span>`, merging `aria-hidden` and `data-state` onto it via the
+     * {@link Slot} pattern.
+     * @default false
+     */
+    asChild?: boolean;
+};
+/** Internal: the native `onChange` shape the Root composes with its own. */
+export type SwitchChangeHandler = ChangeEventHandler<HTMLInputElement>;

package/dist/Switch/types.js

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