@primitiv-ui/react 0.1.38 → 0.1.39

package/dist/Carousel/types.js

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

package/dist/Checkbox/Checkbox.d.ts

@@ -0,0 +1,120 @@
+import type { ReactElement } from "react";
+import { CheckboxIndicatorProps, CheckboxRootProps } from "./types.js";
+/**
+ * The root of a Checkbox — a `<label>` that is itself the **visible, styled
+ * box** and wraps a **real, visually-hidden `<input type="checkbox">`** (the
+ * focusable, form-participating control) plus the decorative
+ * {@link CheckboxIndicator | `Checkbox.Indicator`} mark. It provides
+ * {@link CheckboxContext | `CheckboxContext`} to the indicator.
+ *
+ * Because the underlying element is a genuine native checkbox, it behaves like
+ * one: it submits its `value` under `name` with an enclosing form, resets with
+ * the form, and gets keyboard activation and focus for free. The tri-state
+ * `"indeterminate"` is the platform's own: it is applied via the input's
+ * `.indeterminate` DOM property, so the browser exposes `aria-checked="mixed"`
+ * and the `:indeterminate` pseudo-class for styling.
+ *
+ * Props routing: `className` / `style` style the **box** (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 checkbox.
+ *
+ * Supports two state modes, statically discriminated at the type level:
+ *
+ * - **Uncontrolled** — pass
+ *   {@link CheckboxRootProps.defaultChecked | `defaultChecked`} (or omit). It
+ *   may be `"indeterminate"` for a mixed-on-mount checkbox.
+ * - **Controlled** — pass
+ *   {@link CheckboxRootProps.checked | `checked`} *and*
+ *   {@link CheckboxRootProps.onCheckedChange | `onCheckedChange`} together.
+ *   Clicking a mixed checkbox resolves it to `true`.
+ *
+ * **Styling hooks.** `data-state="checked" | "unchecked" | "indeterminate"`
+ * and `data-disabled=""` on the box (and `data-state` on the indicator). These
+ * mirror the input, but shipped CSS keys the mark off the input's native
+ * `:checked` / `:indeterminate` instead; `data-state` is a convenience mirror.
+ *
+ * @extends HTMLInputElement
+ *
+ * @example Uncontrolled
+ * ```tsx
+ * <Checkbox.Root name="terms" value="accepted" defaultChecked aria-label="Accept terms">
+ *   <Checkbox.Indicator />
+ * </Checkbox.Root>
+ * ```
+ *
+ * @example Controlled tri-state
+ * ```tsx
+ * const [checked, setChecked] = useState<CheckedState>("indeterminate");
+ *
+ * <Checkbox.Root checked={checked} onCheckedChange={setChecked} aria-label="...">
+ *   <Checkbox.Indicator />
+ * </Checkbox.Root>
+ * ```
+ */
+export declare function CheckboxRoot(props: CheckboxRootProps): ReactElement;
+export declare namespace CheckboxRoot {
+    var displayName: string;
+}
+/**
+ * The decorative mark — a `<span>` that is **always mounted**, sitting inside
+ * the {@link CheckboxRoot | `Checkbox.Root`} box. Its visibility and shape (a
+ * tick when checked, a bar when indeterminate) are a pure CSS concern, revealed
+ * off the input's native `:checked` / `:indeterminate` state. The checkbox's
+ * accessible state is conveyed by the native input, so the mark is purely
+ * visual.
+ *
+ * **Styling hook.** Mirrors the root's
+ * `data-state="checked" | "unchecked" | "indeterminate"`.
+ *
+ * **`asChild` prop.** Pass `asChild` to render the consumer's own element
+ * (typically an `<svg>` tick) as the indicator itself, with `data-state`
+ * merged onto that element rather than a wrapper.
+ *
+ * @extends HTMLSpanElement
+ *
+ * @example Icon as the indicator via `asChild`
+ * ```tsx
+ * <Checkbox.Indicator asChild>
+ *   <svg viewBox="0 0 10 10"><path d="M1 5l3 3 5-7" /></svg>
+ * </Checkbox.Indicator>
+ * ```
+ *
+ * @throws if rendered outside a `Checkbox.Root`.
+ */
+export declare function CheckboxIndicator({ children, asChild, ...rest }: CheckboxIndicatorProps): ReactElement;
+export declare namespace CheckboxIndicator {
+    var displayName: string;
+}
+/** Type of the {@link Checkbox} compound: the root callable plus its attached sub-components. */
+export type TCheckboxCompound = typeof CheckboxRoot & {
+    Root: typeof CheckboxRoot;
+    Indicator: typeof CheckboxIndicator;
+};
+/**
+ * Headless, accessible **Checkbox** — a compound component built on a **real,
+ * visually-hidden native `<input type="checkbox">`**, including the platform's
+ * own tri-state (`indeterminate` → `aria-checked="mixed"`). Unlike a button
+ * dressed up with `role="checkbox"`, it participates in native forms. Zero
+ * styles ship.
+ *
+ * `Checkbox` is both callable (an alias of
+ * {@link CheckboxRoot | `Checkbox.Root`}) and carries its sub-components as
+ * static properties.
+ *
+ * - {@link CheckboxRoot | `Checkbox.Root`} — the styled box: label + hidden input, state owner, context provider.
+ * - {@link CheckboxIndicator | `Checkbox.Indicator`} — the decorative mark.
+ *
+ * @example Minimal usage
+ * ```tsx
+ * import { Checkbox } from "@primitiv-ui/react";
+ *
+ * <Checkbox.Root name="terms" value="accepted" aria-label="Accept terms">
+ *   <Checkbox.Indicator />
+ * </Checkbox.Root>;
+ * ```
+ *
+ * @see {@link CheckboxRoot} for state modes and tri-state semantics.
+ */
+declare const CheckboxCompound: TCheckboxCompound;
+export { CheckboxCompound as Checkbox };

package/dist/Checkbox/Checkbox.js

@@ -0,0 +1,155 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef } from "react";
+import { Slot, composeRefs } from "../Slot/index.js";
+import { CheckboxContext } from "./CheckboxContext.js";
+import { useCheckboxContext, useCheckboxInput } from "./hooks/index.js";
+function dataStateOf(checked) {
+    if (checked === "indeterminate")
+        return "indeterminate";
+    return checked ? "checked" : "unchecked";
+}
+/**
+ * The root of a Checkbox — a `<label>` that is itself the **visible, styled
+ * box** and wraps a **real, visually-hidden `<input type="checkbox">`** (the
+ * focusable, form-participating control) plus the decorative
+ * {@link CheckboxIndicator | `Checkbox.Indicator`} mark. It provides
+ * {@link CheckboxContext | `CheckboxContext`} to the indicator.
+ *
+ * Because the underlying element is a genuine native checkbox, it behaves like
+ * one: it submits its `value` under `name` with an enclosing form, resets with
+ * the form, and gets keyboard activation and focus for free. The tri-state
+ * `"indeterminate"` is the platform's own: it is applied via the input's
+ * `.indeterminate` DOM property, so the browser exposes `aria-checked="mixed"`
+ * and the `:indeterminate` pseudo-class for styling.
+ *
+ * Props routing: `className` / `style` style the **box** (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 checkbox.
+ *
+ * Supports two state modes, statically discriminated at the type level:
+ *
+ * - **Uncontrolled** — pass
+ *   {@link CheckboxRootProps.defaultChecked | `defaultChecked`} (or omit). It
+ *   may be `"indeterminate"` for a mixed-on-mount checkbox.
+ * - **Controlled** — pass
+ *   {@link CheckboxRootProps.checked | `checked`} *and*
+ *   {@link CheckboxRootProps.onCheckedChange | `onCheckedChange`} together.
+ *   Clicking a mixed checkbox resolves it to `true`.
+ *
+ * **Styling hooks.** `data-state="checked" | "unchecked" | "indeterminate"`
+ * and `data-disabled=""` on the box (and `data-state` on the indicator). These
+ * mirror the input, but shipped CSS keys the mark off the input's native
+ * `:checked` / `:indeterminate` instead; `data-state` is a convenience mirror.
+ *
+ * @extends HTMLInputElement
+ *
+ * @example Uncontrolled
+ * ```tsx
+ * <Checkbox.Root name="terms" value="accepted" defaultChecked aria-label="Accept terms">
+ *   <Checkbox.Indicator />
+ * </Checkbox.Root>
+ * ```
+ *
+ * @example Controlled tri-state
+ * ```tsx
+ * const [checked, setChecked] = useState<CheckedState>("indeterminate");
+ *
+ * <Checkbox.Root checked={checked} onCheckedChange={setChecked} aria-label="...">
+ *   <Checkbox.Indicator />
+ * </Checkbox.Root>
+ * ```
+ */
+export function CheckboxRoot(props) {
+    const { className, style, children, defaultChecked, checked, onCheckedChange, onChange, disabled, ref, ...inputRest } = props;
+    const { checked: value, handleChange, inputStateProps, } = useCheckboxInput({ defaultChecked, checked, onCheckedChange, onChange });
+    // `indeterminate` is a DOM property with no JSX attribute, so it is applied
+    // imperatively whenever the resolved tri-state value changes. The input is
+    // rendered unconditionally, so the ref is always set here.
+    const inputRef = useRef(null);
+    useEffect(() => {
+        inputRef.current.indeterminate = value === "indeterminate";
+    }, [value]);
+    const composedRef = ref ? composeRefs(inputRef, ref) : inputRef;
+    const contextValue = useMemo(() => ({ checked: value, disabled: Boolean(disabled) }), [value, disabled]);
+    return (_jsx(CheckboxContext.Provider, { value: contextValue, children: _jsxs("label", { className: className, style: style, "data-state": dataStateOf(value), "data-disabled": disabled ? "" : undefined, children: [_jsx("input", { type: "checkbox", ref: composedRef, disabled: disabled, ...inputRest, ...inputStateProps, onChange: handleChange }), children] }) }));
+}
+// Runtime-dead: the compound alias below (same object via Object.assign)
+// overwrites this to "Checkbox" at load, so the value is never observable. The
+// assignment stays because it declares `displayName` on `typeof CheckboxRoot`,
+// which TCheckboxCompound extends.
+// Stryker disable next-line StringLiteral: overwritten by the compound alias — an equivalent mutant.
+CheckboxRoot.displayName = "CheckboxRoot";
+/**
+ * The decorative mark — a `<span>` that is **always mounted**, sitting inside
+ * the {@link CheckboxRoot | `Checkbox.Root`} box. Its visibility and shape (a
+ * tick when checked, a bar when indeterminate) are a pure CSS concern, revealed
+ * off the input's native `:checked` / `:indeterminate` state. The checkbox's
+ * accessible state is conveyed by the native input, so the mark is purely
+ * visual.
+ *
+ * **Styling hook.** Mirrors the root's
+ * `data-state="checked" | "unchecked" | "indeterminate"`.
+ *
+ * **`asChild` prop.** Pass `asChild` to render the consumer's own element
+ * (typically an `<svg>` tick) as the indicator itself, with `data-state`
+ * merged onto that element rather than a wrapper.
+ *
+ * @extends HTMLSpanElement
+ *
+ * @example Icon as the indicator via `asChild`
+ * ```tsx
+ * <Checkbox.Indicator asChild>
+ *   <svg viewBox="0 0 10 10"><path d="M1 5l3 3 5-7" /></svg>
+ * </Checkbox.Indicator>
+ * ```
+ *
+ * @throws if rendered outside a `Checkbox.Root`.
+ */
+export function CheckboxIndicator({ children, asChild = false, ...rest }) {
+    const { checked } = useCheckboxContext();
+    const indicatorProps = {
+        ...rest,
+        "aria-hidden": "true",
+        "data-state": dataStateOf(checked),
+    };
+    if (asChild) {
+        return _jsx(Slot, { ...indicatorProps, children: children });
+    }
+    return _jsx("span", { ...indicatorProps, children: children });
+}
+/** @internal */
+CheckboxIndicator.displayName = "CheckboxIndicator";
+/**
+ * Headless, accessible **Checkbox** — a compound component built on a **real,
+ * visually-hidden native `<input type="checkbox">`**, including the platform's
+ * own tri-state (`indeterminate` → `aria-checked="mixed"`). Unlike a button
+ * dressed up with `role="checkbox"`, it participates in native forms. Zero
+ * styles ship.
+ *
+ * `Checkbox` is both callable (an alias of
+ * {@link CheckboxRoot | `Checkbox.Root`}) and carries its sub-components as
+ * static properties.
+ *
+ * - {@link CheckboxRoot | `Checkbox.Root`} — the styled box: label + hidden input, state owner, context provider.
+ * - {@link CheckboxIndicator | `Checkbox.Indicator`} — the decorative mark.
+ *
+ * @example Minimal usage
+ * ```tsx
+ * import { Checkbox } from "@primitiv-ui/react";
+ *
+ * <Checkbox.Root name="terms" value="accepted" aria-label="Accept terms">
+ *   <Checkbox.Indicator />
+ * </Checkbox.Root>;
+ * ```
+ *
+ * @see {@link CheckboxRoot} for state modes and tri-state semantics.
+ */
+const CheckboxCompound = Object.assign(CheckboxRoot, {
+    Root: CheckboxRoot,
+    Indicator: CheckboxIndicator,
+});
+/** @internal */
+CheckboxCompound.displayName = "Checkbox";
+export { CheckboxCompound as Checkbox };

package/dist/Checkbox/CheckboxContext.d.ts

@@ -0,0 +1,13 @@
+import { CheckedState } from "./types.js";
+export type CheckboxContextValue = {
+    /**
+     * Best-effort mirror of the input's tri-state value, for the `data-state`
+     * hook on the indicator. The shipped CSS reveals the mark off the input's
+     * native `:checked` / `:indeterminate` instead, so it stays correct through
+     * a form reset; `data-state` is a convenience mirror.
+     */
+    checked: CheckedState;
+    /** Whether the checkbox is disabled, for the `data-disabled` hook. */
+    disabled: boolean;
+};
+export declare const CheckboxContext: import("react").Context<CheckboxContextValue | null>, useCheckboxContext: () => CheckboxContextValue;

package/dist/Checkbox/CheckboxContext.js

@@ -0,0 +1,3 @@
+"use client";
+import { createStrictContext } from "../utils/index.js";
+export const [CheckboxContext, useCheckboxContext] = createStrictContext("Checkbox sub-components must be rendered inside a <Checkbox.Root>.");

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

@@ -0,0 +1,3 @@
+export { useCheckboxRoot } from "./useCheckboxRoot.js";
+export { useCheckboxInput } from "./useCheckboxInput.js";
+export { useCheckboxContext } from "./useCheckboxContext.js";

package/dist/Checkbox/hooks/index.js

@@ -0,0 +1,3 @@
+export { useCheckboxRoot } from "./useCheckboxRoot.js";
+export { useCheckboxInput } from "./useCheckboxInput.js";
+export { useCheckboxContext } from "./useCheckboxContext.js";

package/dist/Checkbox/hooks/useCheckboxContext.d.ts

@@ -0,0 +1 @@
+export { useCheckboxContext } from "../CheckboxContext.js";

package/dist/Checkbox/hooks/useCheckboxContext.js

@@ -0,0 +1 @@
+export { useCheckboxContext } from "../CheckboxContext.js";

package/dist/Checkbox/hooks/useCheckboxInput.d.ts

@@ -0,0 +1,33 @@
+import type { ChangeEvent } from "react";
+import { CheckboxChangeHandler, CheckedState } from "../types.js";
+type UseCheckboxInputArgs = {
+    defaultChecked?: CheckedState;
+    checked?: CheckedState;
+    onCheckedChange?: (checked: boolean) => void;
+    onChange?: CheckboxChangeHandler;
+};
+/**
+ * Resolves the controlled / uncontrolled tri-state for a {@link Checkbox.Root}
+ * and produces the props to spread onto its native `<input type="checkbox">`.
+ *
+ * Distinct from {@link useCheckboxRoot}, which drives the *button*-based
+ * `menuitemcheckbox` items in Dropdown / ContextMenu via a `toggle()` callback.
+ * This hook instead lets the native input own the toggling: the boolean half of
+ * the state maps to the input's `checked` / `defaultChecked`, and the
+ * `"indeterminate"` value is applied by the component via the input's
+ * `.indeterminate` DOM property. A native checkbox only toggles between booleans
+ * by user action — clicking a mixed checkbox resolves it to `true` — so
+ * `onCheckedChange` is always called with a boolean.
+ */
+export declare function useCheckboxInput({ defaultChecked, checked: controlledChecked, onCheckedChange, onChange, }: UseCheckboxInputArgs): {
+    checked: CheckedState;
+    handleChange: (event: ChangeEvent<HTMLInputElement>) => void;
+    inputStateProps: {
+        checked: boolean;
+        defaultChecked?: undefined;
+    } | {
+        defaultChecked: boolean;
+        checked?: undefined;
+    };
+};
+export {};

package/dist/Checkbox/hooks/useCheckboxInput.js

@@ -0,0 +1,37 @@
+"use client";
+import { useState } from "react";
+/**
+ * Resolves the controlled / uncontrolled tri-state for a {@link Checkbox.Root}
+ * and produces the props to spread onto its native `<input type="checkbox">`.
+ *
+ * Distinct from {@link useCheckboxRoot}, which drives the *button*-based
+ * `menuitemcheckbox` items in Dropdown / ContextMenu via a `toggle()` callback.
+ * This hook instead lets the native input own the toggling: the boolean half of
+ * the state maps to the input's `checked` / `defaultChecked`, and the
+ * `"indeterminate"` value is applied by the component via the input's
+ * `.indeterminate` DOM property. A native checkbox only toggles between booleans
+ * by user action — clicking a mixed checkbox resolves it to `true` — so
+ * `onCheckedChange` is always called with a boolean.
+ */
+export function useCheckboxInput({ 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
+        // `inputStateProps` 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 === true }
+        : { defaultChecked: defaultChecked === true };
+    return { checked, handleChange, inputStateProps };
+}

package/dist/Checkbox/hooks/useCheckboxRoot.d.ts

@@ -0,0 +1,11 @@
+import { CheckedState } from "../types.js";
+type UseCheckboxRootArgs = {
+    defaultChecked?: CheckedState;
+    checked?: CheckedState;
+    onCheckedChange?: (checked: boolean) => void;
+};
+export declare function useCheckboxRoot({ defaultChecked, checked: controlledChecked, onCheckedChange, }: UseCheckboxRootArgs): {
+    checked: CheckedState;
+    toggle: () => void;
+};
+export {};

package/dist/Checkbox/hooks/useCheckboxRoot.js

@@ -0,0 +1,14 @@
+"use client";
+import { useCallback } from "react";
+import { useControllableState } from "../../hooks/index.js";
+export function useCheckboxRoot({ defaultChecked, checked: controlledChecked, onCheckedChange, }) {
+    const [checked, setChecked] = useControllableState(controlledChecked, defaultChecked ?? false);
+    const toggle = useCallback(() => {
+        // Indeterminate resolves to checked per the WAI-ARIA tri-state
+        // convention; boolean flips.
+        const next = checked === "indeterminate" ? true : !checked;
+        setChecked(next);
+        onCheckedChange?.(next);
+    }, [checked, setChecked, onCheckedChange]);
+    return { checked, toggle };
+}

package/dist/Checkbox/index.d.ts

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

package/dist/Checkbox/index.js

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

package/dist/Checkbox/types.d.ts

@@ -0,0 +1,74 @@
+import { ChangeEventHandler, ComponentProps, ReactNode, Ref } from "react";
+/** The checked value of a checkbox — `true`, `false`, or `"indeterminate"` (the tri-state). */
+export type CheckedState = boolean | "indeterminate";
+/**
+ * Props for {@link Checkbox.Indicator} — the decorative mark. All `<span>`
+ * attributes plus the `asChild` escape hatch. The indicator is always mounted;
+ * its visibility is a CSS concern, revealed off the input's native `:checked` /
+ * `:indeterminate` state.
+ */
+export type CheckboxIndicatorProps = ComponentProps<"span"> & {
+    /** Custom mark content. Omit to let the shipped CSS draw the tick/bar off the
+     * input's native `:checked` / `:indeterminate` state; provide your own (an
+     * icon, glyph, or nested element) to override it. */
+    children?: ReactNode;
+    /**
+     * When `true`, render `children` as the indicator element itself
+     * (via the {@link Slot} pattern) instead of wrapping them in a `<span>`.
+     * `data-state` and `aria-hidden` are merged onto that element.
+     * @default false
+     */
+    asChild?: boolean;
+};
+/**
+ * Shared base for both {@link CheckboxRootProps} variants — the native
+ * `<input type="checkbox">` attributes (minus the ones the component owns) plus
+ * the `onCheckedChange` convenience callback. `className` / `style` here style
+ * the **box** (the visible control), not the hidden input; everything else
+ * spreads onto the input, because semantically the Root *is* the checkbox.
+ */
+export type CheckboxRootBaseProps = Omit<ComponentProps<"input">, "type" | "checked" | "defaultChecked"> & {
+    /** Fired with the new boolean checked value on every user toggle. */
+    onCheckedChange?: (checked: boolean) => void;
+    children?: ReactNode;
+    /** Forwarded to the underlying native `<input type="checkbox">`. */
+    ref?: Ref<HTMLInputElement>;
+};
+/**
+ * Uncontrolled variant of {@link CheckboxRootProps}: the component owns the
+ * checked value. Pass `defaultChecked` (or omit it); `checked` is forbidden.
+ * `defaultChecked` may be `"indeterminate"` for a mixed-on-mount checkbox.
+ */
+export type CheckboxRootUncontrolledProps = CheckboxRootBaseProps & {
+    /** Checked value on first render; the component owns it thereafter. May be
+     * `"indeterminate"` for a mixed-on-mount checkbox. Omit for an initially
+     * unchecked box. */
+    defaultChecked?: CheckedState;
+    /** Forbidden in uncontrolled mode — use `defaultChecked` instead. */
+    checked?: never;
+};
+/**
+ * Controlled variant of {@link CheckboxRootProps}: the parent owns the checked
+ * value. Pass `checked` and `onCheckedChange` together; `defaultChecked` is
+ * forbidden.
+ */
+export type CheckboxRootControlledProps = CheckboxRootBaseProps & {
+    /** Forbidden in controlled mode — use `checked` instead. */
+    defaultChecked?: never;
+    /** The current checked value, owned by the parent. May be `"indeterminate"`
+     * for the tri-state; clicking a mixed checkbox resolves it to `true`. Keep it
+     * in sync via `onCheckedChange`. */
+    checked: CheckedState;
+    /** Called with the new boolean checked value on every user toggle. Required
+     * in controlled mode so the parent can keep `checked` in sync. */
+    onCheckedChange: (checked: boolean) => void;
+};
+/**
+ * Props for {@link Checkbox.Root}. A discriminated union of
+ * {@link CheckboxRootUncontrolledProps} and
+ * {@link CheckboxRootControlledProps}, so TypeScript accepts exactly one
+ * state mode.
+ */
+export type CheckboxRootProps = CheckboxRootUncontrolledProps | CheckboxRootControlledProps;
+/** Internal: the native `onChange` shape the Root composes with its own. */
+export type CheckboxChangeHandler = ChangeEventHandler<HTMLInputElement>;

package/dist/Checkbox/types.js

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

package/dist/CheckboxCard/CheckboxCard.d.ts

@@ -0,0 +1,132 @@
+import type { ReactElement } from "react";
+import { CheckboxCardIndicatorProps, CheckboxCardRootProps } from "./types.js";
+/**
+ * The root of a CheckboxCard — a native `<button role="checkbox">` whose
+ * entire card surface is the interactive area. Owns the tri-state checked
+ * value and provides {@link CheckboxCardContext | `CheckboxCardContext`} to
+ * descendant {@link CheckboxCardIndicator | `CheckboxCard.Indicator`}s.
+ *
+ * Supports two state modes, statically discriminated at the type level:
+ *
+ * - **Uncontrolled** — pass
+ *   {@link CheckboxCardRootProps.defaultChecked | `defaultChecked`} (or omit
+ *   for unchecked-on-mount). The component owns the value internally.
+ * - **Controlled** — pass
+ *   {@link CheckboxCardRootProps.checked | `checked`} *and*
+ *   {@link CheckboxCardRootProps.onCheckedChange | `onCheckedChange`}
+ *   together. The parent owns the value.
+ *
+ * Both `checked` and `defaultChecked` accept `boolean | "indeterminate"`.
+ * Clicking an indeterminate card resolves it to `true` per the WAI-ARIA
+ * tri-state convention, then flips boolean on subsequent clicks.
+ *
+ * **ARIA.** `role="checkbox"` and `aria-checked` are set automatically;
+ * `aria-checked="mixed"` represents the indeterminate state.
+ *
+ * **Styling hooks.** `data-state="checked" | "unchecked" | "indeterminate"`
+ * on the root, plus `data-disabled=""` when disabled.
+ *
+ * **`asChild` prop.** Pass `asChild` to render any consumer-supplied element
+ * with the checkbox's ARIA attributes, `data-state`, composed `onClick`, and
+ * `ref` merged in via the {@link Slot} pattern. See
+ * {@link CheckboxCardRootBaseProps}.
+ *
+ * @extends HTMLButtonElement
+ *
+ * @example Uncontrolled
+ * ```tsx
+ * <CheckboxCard.Root defaultChecked aria-label="Enable feature">
+ *   <CheckboxCard.Indicator>
+ *     <CheckIcon />
+ *   </CheckboxCard.Indicator>
+ *   <h3>Feature name</h3>
+ *   <p>Feature description</p>
+ * </CheckboxCard.Root>
+ * ```
+ *
+ * @example Controlled
+ * ```tsx
+ * const [enabled, setEnabled] = useState<CheckedState>(false);
+ *
+ * <CheckboxCard.Root checked={enabled} onCheckedChange={setEnabled} aria-label="...">
+ *   <CheckboxCard.Indicator />
+ *   Feature name
+ * </CheckboxCard.Root>
+ * ```
+ */
+export declare function CheckboxCardRoot(props: CheckboxCardRootProps): ReactElement;
+export declare namespace CheckboxCardRoot {
+    var displayName: string;
+}
+/**
+ * A decorative `<span aria-hidden="true">` that renders its children only
+ * while the parent {@link CheckboxCardRoot | `CheckboxCard.Root`} is
+ * **checked** or **indeterminate** — never when unchecked. The checkbox's
+ * accessible state is already conveyed by `aria-checked` on the root, so
+ * the indicator is purely visual.
+ *
+ * **Styling hook.** Mirrors the root's
+ * `data-state="checked" | "unchecked" | "indeterminate"`.
+ *
+ * **`asChild` prop.** Pass `asChild` to render the consumer's own element
+ * (typically an `<svg>` tick icon) as the indicator itself.
+ *
+ * **`forceMount` prop.** Pass `forceMount` to keep the indicator in the DOM
+ * while unchecked so a CSS exit animation can play against
+ * `data-state="unchecked"`. See {@link CheckboxCardIndicatorProps}.
+ *
+ * @extends HTMLSpanElement
+ *
+ * @example
+ * ```tsx
+ * <CheckboxCard.Indicator>
+ *   <CheckIcon />
+ * </CheckboxCard.Indicator>
+ * ```
+ *
+ * @throws if rendered outside a `CheckboxCard.Root`.
+ */
+export declare function CheckboxCardIndicator({ children, forceMount, asChild, ...rest }: CheckboxCardIndicatorProps): ReactElement | null;
+export declare namespace CheckboxCardIndicator {
+    var displayName: string;
+}
+/** Type of the {@link CheckboxCard} compound: the callable `CheckboxCard.Root`
+ * component augmented with its sub-components as static properties. */
+export type TCheckboxCardCompound = typeof CheckboxCardRoot & {
+    Root: typeof CheckboxCardRoot;
+    Indicator: typeof CheckboxCardIndicator;
+};
+/**
+ * Headless, accessible **CheckboxCard** — a card/tile-shaped checkbox
+ * implementing the
+ * [WAI-ARIA Checkbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/)
+ * including the tri-state ("mixed") variant. The entire card surface is the
+ * interactive element. Zero styles ship.
+ *
+ * `CheckboxCard` is both callable (an alias of
+ * {@link CheckboxCardRoot | `CheckboxCard.Root`}) and carries its
+ * sub-components as static properties.
+ *
+ * - {@link CheckboxCardRoot | `CheckboxCard.Root`} — state owner, context
+ *   provider, toggle button.
+ * - {@link CheckboxCardIndicator | `CheckboxCard.Indicator`} — decorative
+ *   tick, conditional on checked state.
+ *
+ * @example Minimal usage
+ * ```tsx
+ * import { CheckboxCard } from "@primitiv-ui/react";
+ *
+ * <CheckboxCard.Root aria-label="Enable feature">
+ *   <CheckboxCard.Indicator>
+ *     <CheckIcon />
+ *   </CheckboxCard.Indicator>
+ *   <h3>Feature name</h3>
+ *   <p>Enable this to unlock advanced capabilities.</p>
+ * </CheckboxCard.Root>
+ * ```
+ *
+ * @see {@link CheckboxCardRoot} for state modes and tri-state semantics.
+ * @see {@link CheckboxCardIndicator} for the mount gate and animation hooks.
+ */
+declare const CheckboxCardCompound: TCheckboxCardCompound;
+export { CheckboxCardCompound as CheckboxCard };