@primitiv-ui/react 0.1.37 → 0.1.39

package/dist/SegmentedControl/types.d.ts

@@ -0,0 +1,121 @@
+import { ComponentProps, ReactNode, Ref } from "react";
+/**
+ * Layout axis of the control. `"horizontal"` (default) binds the
+ * Arrow Left/Right pair; `"vertical"` binds Arrow Up/Down. Also
+ * reflected as `aria-orientation` and `data-orientation` on the root.
+ */
+export type SegmentedControlOrientation = "horizontal" | "vertical";
+/** Reading direction — swaps the horizontal arrow pair when `"rtl"`. */
+export type SegmentedControlReadingDirection = "ltr" | "rtl";
+/**
+ * Shared base for both {@link SegmentedControlRootProps} variants — the
+ * native `<div>` attributes (minus the component-owned `role` and the
+ * narrowed `dir`) plus the `asChild` escape hatch, orientation, reading
+ * direction, group-level `disabled`, and a typed `ref`.
+ */
+export type SegmentedControlRootBaseProps = Omit<ComponentProps<"div">, "role" | "dir" | "defaultValue"> & {
+    /** The control's segments — {@link SegmentedControlItemProps | `SegmentedControl.Item`}
+     * elements. */
+    children?: ReactNode;
+    /** Forwarded to the underlying `HTMLDivElement`. */
+    ref?: Ref<HTMLDivElement>;
+    /**
+     * When `true`, Root delegates rendering to a single consumer-supplied
+     * element via the {@link Slot} pattern instead of the default `<div>`;
+     * `role="radiogroup"`, `aria-orientation`, `data-orientation`,
+     * `data-disabled`, `dir`, and remaining props are merged onto it.
+     * @default false
+     */
+    asChild?: boolean;
+    /**
+     * Which arrow-key pair moves focus and selection through the segments,
+     * and the visual axis. `"horizontal"` binds Arrow Left/Right;
+     * `"vertical"` binds Arrow Up/Down. Reflected as `aria-orientation` and
+     * `data-orientation` on the root.
+     * @default "horizontal"
+     */
+    orientation?: SegmentedControlOrientation;
+    /**
+     * Reading direction. In `"rtl"` the horizontal arrow pair is swapped so
+     * Arrow Left moves forward. When omitted, it is inherited from the
+     * nearest {@link DirectionProvider}, falling back to `"ltr"`.
+     */
+    dir?: SegmentedControlReadingDirection;
+    /**
+     * Disables the entire control — every segment is non-interactive and
+     * excluded from arrow-key navigation, and `data-disabled=""` is set on
+     * the root. Individual segments can also be disabled via the Item's own
+     * `disabled` prop.
+     * @default false
+     */
+    disabled?: boolean;
+};
+/**
+ * Uncontrolled variant of {@link SegmentedControlRootProps}: the component
+ * owns the selected value. Pass `defaultValue` (or omit it); `onValueChange`
+ * is optional and `value` is forbidden.
+ */
+export type SegmentedControlRootUncontrolledProps = SegmentedControlRootBaseProps & {
+    /** Value of the segment selected on first render. Omit for nothing
+     * selected on mount. */
+    defaultValue?: string;
+    /** Forbidden in uncontrolled mode — use `defaultValue` instead. */
+    value?: never;
+    /** Called with the new value whenever the selection changes. Optional
+     * in uncontrolled mode. */
+    onValueChange?: (value: string) => void;
+};
+/**
+ * Controlled variant of {@link SegmentedControlRootProps}: the parent owns
+ * the selected value. Pass `value` and `onValueChange` together;
+ * `defaultValue` is forbidden.
+ */
+export type SegmentedControlRootControlledProps = SegmentedControlRootBaseProps & {
+    /** Forbidden in controlled mode — use `value` instead. */
+    defaultValue?: never;
+    /** The currently selected value. Must be kept in sync by the parent
+     * via `onValueChange`. */
+    value: string;
+    /** Called with the new value whenever the selection changes. Required
+     * in controlled mode. */
+    onValueChange: (value: string) => void;
+};
+/**
+ * Props for {@link SegmentedControlRoot | `SegmentedControl.Root`}. A
+ * discriminated union of {@link SegmentedControlRootUncontrolledProps} and
+ * {@link SegmentedControlRootControlledProps}, so TypeScript accepts exactly
+ * one state mode.
+ */
+export type SegmentedControlRootProps = SegmentedControlRootUncontrolledProps | SegmentedControlRootControlledProps;
+/**
+ * Props for {@link SegmentedControlItem | `SegmentedControl.Item`} — the
+ * segment button. `value` identifies the option; all native `<button>`
+ * attributes (minus the component-owned `type`, `role`, `aria-checked`, and
+ * `value`) plus the `asChild` escape hatch and a typed `ref` pass through.
+ */
+export type SegmentedControlItemProps = Omit<ComponentProps<"button">, "type" | "role" | "aria-checked" | "value"> & {
+    /** Uniquely identifies this segment within the control and is reported to
+     * `onValueChange` / matched against Root's `value` when selected. Required. */
+    value: string;
+    /** The segment's visible content — typically its text label. */
+    children?: ReactNode;
+    /** Forwarded to the underlying `HTMLButtonElement`. */
+    ref?: Ref<HTMLButtonElement>;
+    /**
+     * Disables just this segment: forwards the native `disabled` attribute,
+     * removes it from arrow-key navigation and the roving-tabindex home base,
+     * and sets `data-disabled=""`. The whole control can also be disabled via
+     * Root's `disabled` prop.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * When `true`, renders the single child element via the {@link Slot}
+     * pattern instead of the default `<button>`; ARIA, `data-state`,
+     * `data-disabled`, `tabIndex`, `onClick`, `onKeyDown`, `disabled`, and
+     * `ref` are merged onto it. A non-focusable child must be made focusable
+     * by the consumer.
+     * @default false
+     */
+    asChild?: boolean;
+};

package/dist/SegmentedControl/types.js

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

package/dist/Select/Select.d.ts

@@ -0,0 +1,390 @@
+import type { ReactElement } from "react";
+import { SelectContentProps, SelectGroupProps, SelectItemIndicatorProps, SelectItemProps, SelectPlaceholderProps, SelectRootProps, SelectSeparatorProps, SelectTriggerProps, SelectValueProps } from "./types.js";
+/**
+ * The root of a Select — owns the selection (and, in rich mode, the open)
+ * state and provides it to the sub-components.
+ *
+ * **Two render paths, one API** — chosen by {@link SelectRootBaseProps.native | `native`}:
+ *
+ * - `native={false}` (**default**) — the rich Popover-API listbox, composed
+ *   from {@link SelectTrigger}, {@link SelectValue}, {@link SelectContent},
+ *   {@link SelectItem} and {@link SelectItemIndicator}. Items carry arbitrary
+ *   content; a visually-hidden `<select name>` is rendered for form
+ *   submission.
+ * - `native={true}` — a thin wrapper over a real `<select>` (implicit
+ *   `role="combobox"`); the browser owns the popup, keyboard, mobile UX and
+ *   form submission. {@link SelectItem} becomes an `<option>` (string/number
+ *   children only), {@link SelectGroup} an `<optgroup>`.
+ *
+ * **Controlled vs uncontrolled.** Two selection modes are statically
+ * discriminated at the type level so only one shape is accepted by
+ * TypeScript at a time:
+ *
+ * - **Uncontrolled** — pass {@link SelectRootUncontrolledProps.defaultValue | `defaultValue`}
+ *   (or omit it). The browser owns the selection. `onValueChange` is optional.
+ * - **Controlled** — pass {@link SelectRootControlledProps.value | `value`}
+ *   and {@link SelectRootControlledProps.onValueChange | `onValueChange`} together.
+ *   Every transition defers back through `onValueChange`, which receives the
+ *   new selection as a plain string. The consumer's own `onChange` (the raw
+ *   `ChangeEvent`) still fires alongside it.
+ *
+ * **Placeholder integration.** When a {@link SelectPlaceholder | `Select.Placeholder`}
+ * appears among the direct children and neither `value` nor `defaultValue`
+ * is set, Root infers `defaultValue=""` so the placeholder — not the first
+ * selectable option — is the initial selection. Pair with `required` to
+ * make the browser's native form validation catch an unchosen value at
+ * submission.
+ *
+ * **Field integration.** When rendered inside a `<Field.Root>`, Select
+ * 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.
+ *
+ * **`asChild` composition.** Pass `asChild` to delegate rendering to a
+ * single consumer-supplied element (e.g. a styled `<select>` wrapper).
+ * Root's `onChange`, `data-disabled`, `value` / `defaultValue`, and other
+ * native attributes are merged onto the child via the {@link Slot} pattern.
+ * Placeholder-detection walks direct children only in this mode, so
+ * `asChild` + placeholder requires the consumer to set `defaultValue=""`
+ * explicitly.
+ *
+ * **Styling hooks.**
+ * - `data-disabled=""` — present on the `<select>` when `disabled` is set,
+ *   so CSS can target `[data-disabled]` without relying on `:disabled`.
+ *
+ * Root renders no single semantic element of its own in the default (rich)
+ * path — it is a context boundary that also emits a visually-hidden form
+ * `<select>`. Under `native` it renders the real `<select>`.
+ *
+ * @example Rich (default)
+ * ```tsx
+ * <Select.Root value={framework} onValueChange={setFramework}>
+ *   <Select.Trigger>
+ *     <Select.Value placeholder="Pick a framework..." />
+ *   </Select.Trigger>
+ *   <Select.Content>
+ *     <Select.Item value="react">
+ *       <ReactIcon />
+ *       React
+ *       <Select.ItemIndicator>✓</Select.ItemIndicator>
+ *     </Select.Item>
+ *     <Select.Item value="vue">
+ *       <VueIcon />
+ *       Vue
+ *       <Select.ItemIndicator>✓</Select.ItemIndicator>
+ *     </Select.Item>
+ *   </Select.Content>
+ * </Select.Root>
+ * ```
+ *
+ * @example Native
+ * ```tsx
+ * <Select.Root native defaultValue="apple" aria-label="Pick a fruit">
+ *   <Select.Placeholder>Choose...</Select.Placeholder>
+ *   <Select.Group label="Fruits">
+ *     <Select.Item value="apple">Apple</Select.Item>
+ *     <Select.Item value="banana">Banana</Select.Item>
+ *   </Select.Group>
+ * </Select.Root>
+ * ```
+ *
+ * @example Field integration
+ * ```tsx
+ * <Field.Root invalid={!!errors.framework}>
+ *   <Field.Label>Framework</Field.Label>
+ *   <Select.Root name="framework" value={value} onValueChange={onChange}>
+ *     <Select.Trigger>
+ *       <Select.Value placeholder="Choose..." />
+ *     </Select.Trigger>
+ *     <Select.Content>
+ *       <Select.Item value="react">React</Select.Item>
+ *     </Select.Content>
+ *   </Select.Root>
+ *   <Field.ErrorText>{errors.framework?.message}</Field.ErrorText>
+ * </Field.Root>
+ * ```
+ */
+export declare function SelectRoot({ children, native, asChild, onChange, onValueChange, value, defaultValue, defaultOpen, open, onOpenChange, ...consumer }: SelectRootProps): ReactElement;
+export declare namespace SelectRoot {
+    var displayName: string;
+}
+/**
+ * An individual choice inside a Select.
+ *
+ * In `native` mode (the case handled in this cycle) it renders a native
+ * `<option>` element with an implicit `role="option"`. Because an
+ * `<option>` can only hold text, `Select.Item` keeps **only the
+ * string/number parts** of its children — joined as the option's visible
+ * text — and **drops every element child** (icons, indicators). This is
+ * the inverse of the string-vs-element split used elsewhere in the
+ * library, and it means an icon-only item with no text renders an empty,
+ * unlabelled `<option>` under `native`.
+ *
+ * Pass `disabled` to make a single choice unreachable from the dropdown
+ * while still visible.
+ *
+ * @extends HTMLOptionElement
+ *
+ * @example Native
+ * ```tsx
+ * <Select.Root native>
+ *   <Select.Item value="apple">Apple</Select.Item>
+ *   <Select.Item value="durian" disabled>Durian (sold out)</Select.Item>
+ * </Select.Root>
+ * ```
+ */
+export declare function SelectItem({ children, value, disabled, onClick, ...rest }: SelectItemProps): ReactElement;
+export declare namespace SelectItem {
+    var displayName: string;
+}
+/**
+ * The rich-mode trigger button that opens the listbox. Exposes the
+ * WAI-ARIA listbox-combobox contract: `aria-haspopup="listbox"`,
+ * `aria-expanded` reflecting the open state, and `aria-controls` pointing
+ * at the {@link SelectContent | `Select.Content`} id. Place a
+ * {@link SelectValue | `Select.Value`} inside it to show the current
+ * selection.
+ *
+ * Renders a `<button type="button">` by default; pass `asChild` to compose
+ * the ARIA attributes and click handler onto a consumer element via the
+ * {@link Slot} pattern.
+ *
+ * @extends HTMLButtonElement
+ *
+ * @example
+ * ```tsx
+ * <Select.Trigger>
+ *   <Select.Value placeholder="Pick a framework..." />
+ * </Select.Trigger>
+ * ```
+ */
+export declare function SelectTrigger({ children, onClick, asChild, ...rest }: SelectTriggerProps): ReactElement;
+export declare namespace SelectTrigger {
+    var displayName: string;
+}
+/**
+ * The rich-mode display of the current selection, placed inside a
+ * {@link SelectTrigger | `Select.Trigger`}. Shows the `placeholder` when
+ * nothing is selected; mirroring the selected item's content is layered on
+ * in a later cycle.
+ *
+ * Renders a `<span>`.
+ *
+ * **Styling hooks.**
+ * - `data-placeholder=""` — present while nothing is selected (the
+ *   `placeholder` is what's rendered), absent as soon as an item's content is
+ *   mirrored. This is the hook the styled layer uses to render the muted
+ *   placeholder colour versus the filled one.
+ *
+ * @extends HTMLSpanElement
+ *
+ * @example
+ * ```tsx
+ * <Select.Value placeholder="Select a framework..." />
+ * ```
+ */
+export declare function SelectValue({ placeholder, ...rest }: SelectValueProps): ReactElement;
+export declare namespace SelectValue {
+    var displayName: string;
+}
+/**
+ * The selection mark rendered inside a rich {@link SelectItem} — typically a
+ * checkmark. Reads its item's selected state from context and renders only
+ * when that item is selected (pass `forceMount` to keep it mounted for
+ * CSS/animation), exposing `data-state` (`"checked"` / `"unchecked"`).
+ *
+ * `Select.Value` deliberately excludes the indicator when mirroring the
+ * selection into the trigger.
+ *
+ * Renders a `<span>` by default; pass `asChild` to compose onto any element
+ * (commonly an SVG icon) via the {@link Slot} pattern.
+ *
+ * @extends HTMLSpanElement
+ *
+ * @example
+ * ```tsx
+ * <Select.Item value="react">
+ *   <ReactIcon />
+ *   React
+ *   <Select.ItemIndicator>✓</Select.ItemIndicator>
+ * </Select.Item>
+ * ```
+ */
+export declare function SelectItemIndicator({ children, asChild, forceMount, ...rest }: SelectItemIndicatorProps): ReactElement | null;
+export declare namespace SelectItemIndicator {
+    var displayName: string;
+}
+/**
+ * The rich-mode listbox panel, rendered with the native
+ * [Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API)
+ * (`popover="auto"`) — no portal, no floating-ui. The browser manages the
+ * top layer and light-dismiss (outside click / Escape). Opens and closes in
+ * sync with the trigger; on open, focus moves into the listbox, and Escape
+ * closes it and returns focus to the trigger.
+ *
+ * Renders a `<div role="listbox">` by default; pass `asChild` to compose the
+ * listbox props onto a consumer element via the {@link Slot} pattern.
+ *
+ * @extends HTMLDivElement
+ *
+ * @example
+ * ```tsx
+ * <Select.Content>
+ *   <Select.Item value="react">React</Select.Item>
+ *   <Select.Item value="vue">Vue</Select.Item>
+ * </Select.Content>
+ * ```
+ */
+export declare function SelectContent({ children, onKeyDown, asChild, ...rest }: SelectContentProps): ReactElement;
+export declare namespace SelectContent {
+    var displayName: string;
+}
+/**
+ * Visually groups related options. In `native` mode it renders an
+ * `<optgroup>` (the browser shows {@link SelectGroupProps.label | `label`}
+ * as a non-selectable heading); in rich mode it renders a
+ * `<div role="group">` with `aria-label={label}`. Either way the `label` is
+ * the group's accessible name.
+ *
+ * @example
+ * ```tsx
+ * <Select.Group label="Fruits">
+ *   <Select.Item value="apple">Apple</Select.Item>
+ *   <Select.Item value="banana">Banana</Select.Item>
+ * </Select.Group>
+ * ```
+ */
+export declare function SelectGroup({ children, label, ...rest }: SelectGroupProps): ReactElement;
+export declare namespace SelectGroup {
+    var displayName: string;
+}
+/**
+ * A visual divider between groups of options in rich mode — typically
+ * placed between two {@link SelectGroup | `Select.Group`} elements (or any
+ * two {@link SelectItem | `Select.Item`}s). Renders a `<div role="separator">`
+ * by default; pass `asChild` to render any element with separator semantics.
+ * Non-interactive — {@link SelectContent | `Select.Content`}'s keyboard
+ * navigation only ever targets `[role="option"]`, so it is skipped by arrow
+ * key traversal without any extra wiring.
+ *
+ * @extends HTMLDivElement
+ *
+ * @example
+ * ```tsx
+ * <Select.Item value="apple">Apple</Select.Item>
+ * <Select.Separator />
+ * <Select.Item value="banana">Banana</Select.Item>
+ * ```
+ */
+export declare function SelectSeparator({ asChild, children, ...rest }: SelectSeparatorProps): ReactElement;
+export declare namespace SelectSeparator {
+    var displayName: string;
+}
+/**
+ * A non-selectable hint shown as the initial selection of a Select.
+ * Renders a native `<option value="" disabled hidden>` so the browser
+ * displays it in the closed control before the user picks anything but
+ * makes it unreachable from the dropdown afterwards.
+ *
+ * Always render it as the **first** child of
+ * {@link SelectRoot | `Select.Root`}, above any
+ * {@link SelectItem | `Select.Item`} or
+ * {@link SelectGroup | `Select.Group`}.
+ *
+ * When `Select.Placeholder` is present among Root's direct children and
+ * neither `value` nor `defaultValue` is set, Root automatically infers
+ * `defaultValue=""` so the placeholder — not the first selectable option
+ * — is the initial selection. Pair `required` on Root to make the
+ * browser's native form validation catch an unchosen value at submission.
+ *
+ * `value=""`, `disabled`, and `hidden` are fixed by the component and
+ * cannot be overridden. See {@link SelectPlaceholderProps}.
+ *
+ * @extends HTMLOptionElement
+ *
+ * @example
+ * ```tsx
+ * <Select.Root native required aria-label="Pick a fruit">
+ *   <Select.Placeholder>Choose a fruit...</Select.Placeholder>
+ *   <Select.Item value="apple">Apple</Select.Item>
+ *   <Select.Item value="banana">Banana</Select.Item>
+ * </Select.Root>
+ * ```
+ */
+export declare function SelectPlaceholder({ children, ...rest }: SelectPlaceholderProps): ReactElement;
+export declare namespace SelectPlaceholder {
+    var displayName: string;
+}
+/** Type of the {@link Select} compound: the root callable plus its attached sub-components. */
+export type TSelectCompound = typeof SelectRoot & {
+    Root: typeof SelectRoot;
+    Trigger: typeof SelectTrigger;
+    Value: typeof SelectValue;
+    Content: typeof SelectContent;
+    Item: typeof SelectItem;
+    ItemIndicator: typeof SelectItemIndicator;
+    Group: typeof SelectGroup;
+    Separator: typeof SelectSeparator;
+    Placeholder: typeof SelectPlaceholder;
+};
+/**
+ * Headless, accessible single-select **Select** — a compound with two render
+ * paths behind one API, chosen by {@link SelectRootBaseProps.native | `native`}:
+ * a rich Popover-API listbox (default) or a native `<select>` wrapper. Zero
+ * styles ship.
+ *
+ * `Select` is both callable (an alias of {@link SelectRoot | `Select.Root`})
+ * and carries its sub-components as static properties. Prefer the namespaced
+ * form in application code:
+ *
+ * - {@link SelectRoot | `Select.Root`} — state owner + context boundary.
+ * - {@link SelectTrigger | `Select.Trigger`} — rich mode: the listbox button.
+ * - {@link SelectValue | `Select.Value`} — rich mode: mirrors the selection.
+ * - {@link SelectContent | `Select.Content`} — rich mode: the popover listbox.
+ * - {@link SelectItem | `Select.Item`} — an option (rich `<div>` / native `<option>`).
+ * - {@link SelectItemIndicator | `Select.ItemIndicator`} — rich mode: the selected mark.
+ * - {@link SelectGroup | `Select.Group`} — a group (rich `role="group"` / native `<optgroup>`).
+ * - {@link SelectSeparator | `Select.Separator`} — rich mode: a divider between groups/items.
+ * - {@link SelectPlaceholder | `Select.Placeholder`} — native mode: the initial hint.
+ *
+ * @example Rich (default)
+ * ```tsx
+ * import { Select } from "@primitiv-ui/react";
+ *
+ * <Select.Root value={framework} onValueChange={setFramework}>
+ *   <Select.Trigger>
+ *     <Select.Value placeholder="Pick a framework..." />
+ *   </Select.Trigger>
+ *   <Select.Content>
+ *     <Select.Item value="react">
+ *       React
+ *       <Select.ItemIndicator>✓</Select.ItemIndicator>
+ *     </Select.Item>
+ *     <Select.Item value="vue">
+ *       Vue
+ *       <Select.ItemIndicator>✓</Select.ItemIndicator>
+ *     </Select.Item>
+ *   </Select.Content>
+ * </Select.Root>
+ * ```
+ *
+ * @example Native
+ * ```tsx
+ * <Select.Root native defaultValue="apple" aria-label="Pick a fruit">
+ *   <Select.Placeholder>Choose...</Select.Placeholder>
+ *   <Select.Group label="Fruits">
+ *     <Select.Item value="apple">Apple</Select.Item>
+ *     <Select.Item value="banana">Banana</Select.Item>
+ *   </Select.Group>
+ * </Select.Root>
+ * ```
+ *
+ * @see {@link SelectRoot} for the mode + state contract and Field integration.
+ * @see {@link SelectValue} for how the selection mirrors into the trigger.
+ * @see {@link SelectContent} for the listbox keyboard contract.
+ * @see {@link SelectPlaceholder} for the native placeholder + `defaultValue` interaction.
+ */
+declare const SelectCompound: TSelectCompound;
+export { SelectCompound as Select };