@primitiv-ui/react 0.1.38 → 0.1.40

package/dist/Select/types.d.ts

@@ -0,0 +1,246 @@
+import { ChangeEventHandler, ComponentProps, HTMLAttributes, ReactNode, Ref } from "react";
+/**
+ * Shared base for both {@link SelectRootProps} variants — the native
+ * `<select>` attributes (minus the state-owning and multiple-selection
+ * ones), the `asChild` escape hatch, and the raw `onChange` passthrough.
+ */
+export type SelectRootBaseProps = Omit<ComponentProps<"select">, "value" | "defaultValue" | "multiple" | "onChange"> & {
+    /** Content of the select — typically {@link SelectOption}, {@link SelectGroup},
+     * and optionally a leading {@link SelectPlaceholder}. */
+    children?: ReactNode;
+    /** Forwarded to the underlying `HTMLSelectElement`. */
+    ref?: Ref<HTMLSelectElement>;
+    /**
+     * Native `change` handler. Fires alongside `onValueChange` whenever the
+     * user picks a different option. Use this when you want the raw
+     * `ChangeEvent` (e.g. to inspect `event.target.validity`).
+     */
+    onChange?: ChangeEventHandler<HTMLSelectElement>;
+    /**
+     * When `true`, Root delegates to a single consumer-supplied element
+     * (expected to render a `<select>`) and merges its own props onto it
+     * via the {@link Slot} pattern. Placeholder-detection inside Root
+     * walks direct children only in this mode, so the `asChild` +
+     * placeholder combination requires the consumer to set
+     * `defaultValue=""` explicitly.
+     * @default false
+     */
+    asChild?: boolean;
+    /**
+     * Selects the render path:
+     *
+     * - `false` (the default) — the **rich** render path: a fully-styleable
+     *   Popover-API listbox built from {@link SelectTrigger | `Select.Trigger`},
+     *   {@link SelectValue | `Select.Value`},
+     *   {@link SelectContent | `Select.Content`} and
+     *   {@link SelectItem | `Select.Item`}. Icons and other rich content on an
+     *   item render as authored.
+     * - `true` — the **native** render path: a thin wrapper over a real
+     *   `<select>` / `<option>` / `<optgroup>`, for flat, OS-native cases
+     *   (mobile wheel pickers, maximum-compatibility forms). Under `native`,
+     *   {@link SelectItem | `Select.Item`} renders an `<option>` from its
+     *   string/number children only — element children (icons, indicators)
+     *   are dropped.
+     *
+     * Both modes share the same `value` / `onValueChange` / `disabled` / form
+     * `name` API.
+     * @default false
+     */
+    native?: boolean;
+    /**
+     * Rich mode only — whether the listbox popover is open on first render.
+     * Ignored under `native` (the browser owns the popup). Uncontrolled: pass
+     * this (or omit for closed) and let the component manage the state.
+     * @default false
+     */
+    defaultOpen?: boolean;
+    /**
+     * Rich mode only — the controlled open state of the listbox popover. Pass
+     * together with {@link SelectRootBaseProps.onOpenChange | `onOpenChange`}
+     * to own the state from the parent.
+     */
+    open?: boolean;
+    /**
+     * Rich mode only — called with the next open state whenever the listbox
+     * opens or closes (trigger click, selection, Escape, light-dismiss).
+     */
+    onOpenChange?: (open: boolean) => void;
+};
+/**
+ * Uncontrolled variant of {@link SelectRootProps}: the browser owns the
+ * selection. Pass `defaultValue` (or omit it); `onValueChange` is optional
+ * and `value` is forbidden.
+ */
+export type SelectRootUncontrolledProps = SelectRootBaseProps & {
+    /** Value of the option selected on first render. When omitted and a
+     * {@link SelectPlaceholder} is present among Root's direct children,
+     * Root infers `""` automatically so the placeholder is the initial
+     * selection. */
+    defaultValue?: string;
+    /** Forbidden in uncontrolled mode — use `defaultValue` instead. */
+    value?: never;
+    /** Called with the new option value whenever the user changes the
+     * selection. Optional in uncontrolled mode. */
+    onValueChange?: (value: string) => void;
+};
+/**
+ * Controlled variant of {@link SelectRootProps}: the parent owns the
+ * selection. Pass `value` and `onValueChange` together; `defaultValue` is
+ * forbidden.
+ */
+export type SelectRootControlledProps = SelectRootBaseProps & {
+    /** Forbidden in controlled mode — use `value` instead. */
+    defaultValue?: never;
+    /** The currently selected option value. Must be kept in sync by the
+     * parent via `onValueChange`. */
+    value: string;
+    /** Called with the new option value whenever the user changes the
+     * selection. Required in controlled mode. */
+    onValueChange: (value: string) => void;
+};
+/**
+ * Props for {@link SelectRoot | `Select.Root`}.
+ *
+ * Resolves to either {@link SelectRootUncontrolledProps} or
+ * {@link SelectRootControlledProps} — only one shape is accepted by
+ * TypeScript at a time. Native `multiple`-selection mode is not supported
+ * in v1.
+ */
+export type SelectRootProps = SelectRootUncontrolledProps | SelectRootControlledProps;
+/**
+ * Props for {@link SelectItem | `Select.Item`}.
+ *
+ * `Select.Item` renders different elements per mode — an `<option>` under
+ * `native`, a `<div role="option">` in rich mode — so it extends the
+ * element-agnostic `HTMLAttributes<HTMLElement>` rather than an
+ * option-specific type.
+ */
+export type SelectItemProps = HTMLAttributes<HTMLElement> & {
+    /** The value this item represents; committed as the Select's value when
+     * chosen, and matched against the current value for the selected state. */
+    value: string;
+    /** Marks the item unselectable while still visible. */
+    disabled?: boolean;
+    /** The item content. In `native` mode only its string/number parts are
+     * kept as the `<option>` text (element children are dropped); in rich mode
+     * arbitrary content (icons, indicators) renders as authored. */
+    children?: ReactNode;
+};
+/**
+ * Props for {@link SelectGroup | `Select.Group`} — all
+ * `OptgroupHTMLAttributes` on the underlying `<optgroup>` element (with
+ * `label` narrowed to a required `string`), plus a typed `ref`.
+ */
+export type SelectGroupProps = HTMLAttributes<HTMLElement> & {
+    /**
+     * The group heading. In `native` mode it is the `<optgroup>`'s `label`
+     * attribute; in rich mode it becomes the `<div role="group">`'s
+     * `aria-label`. Either way it is the group's accessible name. Required —
+     * a group without one is inaccessible.
+     */
+    label: string;
+    /** The {@link SelectItem} elements belonging to this group. */
+    children?: ReactNode;
+};
+/**
+ * Props for {@link SelectPlaceholder | `Select.Placeholder`}.
+ *
+ * `value`, `disabled`, and `hidden` are owned by the component —
+ * the placeholder always renders with `value=""`, `disabled`, and `hidden`
+ * — so they are excluded from this type and cannot be set by the consumer.
+ */
+export type SelectPlaceholderProps = Omit<ComponentProps<"option">, "value" | "disabled" | "hidden"> & {
+    /** The placeholder hint text shown in the closed select before the user
+     * makes a selection (e.g. `"Choose a fruit..."`). */
+    children?: ReactNode;
+    /** Forwarded to the underlying `HTMLOptionElement`. */
+    ref?: Ref<HTMLOptionElement>;
+};
+/**
+ * Props for {@link SelectTrigger | `Select.Trigger`} — the rich-mode button
+ * that opens the listbox. Extends the native `<button>` attributes.
+ */
+export type SelectTriggerProps = ComponentProps<"button"> & {
+    /** Trigger content — typically a {@link SelectValue | `Select.Value`}. */
+    children?: ReactNode;
+    /**
+     * Render the composed child element instead of a `<button>`, merging the
+     * trigger's ARIA attributes and click handler via the {@link Slot}
+     * pattern.
+     * @default false
+     */
+    asChild?: boolean;
+    /** Forwarded to the underlying `HTMLButtonElement`. */
+    ref?: Ref<HTMLButtonElement>;
+};
+/**
+ * Props for {@link SelectValue | `Select.Value`} — the rich-mode element,
+ * placed inside {@link SelectTrigger | `Select.Trigger`}, that displays the
+ * current selection (mirrored from the selected item in a later cycle) or a
+ * placeholder when nothing is selected. Extends `<span>` attributes minus
+ * `children`, which the component owns.
+ */
+export type SelectValueProps = Omit<ComponentProps<"span">, "children"> & {
+    /** Shown when no value is selected (e.g. `"Select a framework..."`). */
+    placeholder?: ReactNode;
+    /** Forwarded to the underlying `HTMLSpanElement`. */
+    ref?: Ref<HTMLSpanElement>;
+};
+/**
+ * Props for {@link SelectItemIndicator | `Select.ItemIndicator`} — the
+ * selection mark inside a rich {@link SelectItem | `Select.Item`}. Extends
+ * the native `<span>` attributes.
+ */
+export type SelectItemIndicatorProps = ComponentProps<"span"> & {
+    /** The mark to render (e.g. a checkmark glyph or icon). */
+    children?: ReactNode;
+    /**
+     * Render the composed child element instead of a `<span>` via the
+     * {@link Slot} pattern.
+     * @default false
+     */
+    asChild?: boolean;
+    /**
+     * Keep the indicator mounted even when the item is not selected (it still
+     * exposes `data-state="unchecked"`), useful for CSS enter/exit animation.
+     * @default false
+     */
+    forceMount?: boolean;
+    /** Forwarded to the underlying `HTMLSpanElement`. */
+    ref?: Ref<HTMLSpanElement>;
+};
+/**
+ * Props for {@link SelectContent | `Select.Content`} — the rich-mode
+ * Popover-API listbox panel. Extends the native `<div>` attributes.
+ */
+export type SelectContentProps = ComponentProps<"div"> & {
+    /** Listbox content — {@link SelectItem | `Select.Item`} /
+     * {@link SelectGroup | `Select.Group`} elements. */
+    children?: ReactNode;
+    /**
+     * Render the composed child element instead of a `<div>`, merging the
+     * listbox props via the {@link Slot} pattern.
+     * @default false
+     */
+    asChild?: boolean;
+    /** Forwarded to the underlying `HTMLDivElement`. */
+    ref?: Ref<HTMLDivElement>;
+};
+/**
+ * Props for {@link SelectSeparator | `Select.Separator`} — a non-interactive
+ * divider between groups of options in rich mode. Extends the native `<div>`
+ * attributes and adds `asChild`.
+ */
+export type SelectSeparatorProps = Omit<ComponentProps<"div">, "role"> & {
+    /** Optional content; separators are usually empty, and only render (via
+     * the {@link Slot} pattern) when `asChild` composes onto a custom element. */
+    children?: ReactNode;
+    /** Forwarded to the underlying `HTMLDivElement`. */
+    ref?: Ref<HTMLDivElement>;
+    /**
+     * Render the composed child element (with separator semantics) instead of
+     * the default `<div role="separator">`.
+     * @default false
+     */
+    asChild?: boolean;
+};

package/dist/Select/types.js

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

package/dist/SkipNav/SkipNav.d.ts

@@ -0,0 +1,137 @@
+import type { ReactElement } from "react";
+import { SkipNavContentProps, SkipNavLinkProps } from "./types.js";
+/**
+ * The skip link — an `<a>` that jumps keyboard and screen-reader users past
+ * repeated navigation straight to the main content.
+ *
+ * Place it as the very first focusable element on the page (typically the
+ * first child of `<body>`). It is a plain in-page anchor: its `href` is a
+ * URL fragment pointing at the `id` of the matching {@link SkipNavContent |
+ * `SkipNav.Content`}, so following it moves focus there with no JavaScript.
+ *
+ * **`contentId`.** The `href` is derived as `#${contentId}` and defaults to
+ * a shared id (`"primitiv-skip-nav"`), so an unconfigured
+ * `SkipNav.Link` / `SkipNav.Content` pair works out of the box. Override
+ * `contentId` on the link only if you also set a matching `id` on
+ * {@link SkipNavContent | `SkipNav.Content`}.
+ *
+ * **Visibility.** No styles ship with the component. The conventional
+ * pattern keeps the link visually hidden until it receives focus — position
+ * it off-screen by default and restore it on `:focus`. Do **not** use
+ * `display: none` or `visibility: hidden`, as those remove it from the tab
+ * order entirely:
+ *
+ * ```css
+ * a[href="#primitiv-skip-nav"] { position: absolute; left: -9999px; }
+ * a[href="#primitiv-skip-nav"]:focus { left: 0; top: 0; }
+ * ```
+ *
+ * Alternatively, pass a `className` and target that class in your
+ * stylesheet.
+ *
+ * @extends HTMLAnchorElement
+ *
+ * @example Default — shared content id
+ * ```tsx
+ * <SkipNav.Link>Skip to main content</SkipNav.Link>
+ * ```
+ *
+ * @example Custom content id (must match the `id` on `SkipNav.Content`)
+ * ```tsx
+ * <SkipNav.Link contentId="main">Skip to main content</SkipNav.Link>
+ * ```
+ */
+declare function SkipNavLink({ children, contentId, ...rest }: SkipNavLinkProps): ReactElement;
+declare namespace SkipNavLink {
+    var displayName: string;
+}
+/**
+ * The skip target — a `<div tabIndex={-1}>` placed at the start of the main
+ * content that {@link SkipNavLink | `SkipNav.Link`} jumps to.
+ *
+ * `tabIndex={-1}` makes the element a valid programmatic focus destination:
+ * when the link is followed the browser scrolls to this element *and* moves
+ * focus into it, so the next <kbd>Tab</kbd> press continues from within the
+ * main content rather than cycling back to the top of the page. No
+ * JavaScript runs; it is pure anchor navigation.
+ *
+ * **`id`.** Defaults to the same shared id (`"primitiv-skip-nav"`) as
+ * {@link SkipNavLink | `SkipNav.Link`}'s `contentId`. Pass a custom `id`
+ * via the native `id` prop only if you set a matching `contentId` on the
+ * link — the spread props override the default, so the two always stay in
+ * sync.
+ *
+ * @extends HTMLDivElement
+ *
+ * @example Default — wraps the main page content
+ * ```tsx
+ * <SkipNav.Content>
+ *   <main>...</main>
+ * </SkipNav.Content>
+ * ```
+ *
+ * @example Custom id (must match `contentId` on `SkipNav.Link`)
+ * ```tsx
+ * <SkipNav.Content id="main">
+ *   <main>...</main>
+ * </SkipNav.Content>
+ * ```
+ */
+declare function SkipNavContent({ children, ...rest }: SkipNavContentProps): ReactElement;
+declare namespace SkipNavContent {
+    var displayName: string;
+}
+/**
+ * Headless, accessible **Skip Nav** — a "skip to main content" link and its
+ * focus target, letting keyboard and screen-reader users bypass repeated
+ * navigation. Implements the
+ * [WCAG 2.4.1 Bypass Blocks](https://www.w3.org/WAI/WCAG22/Understanding/bypass-blocks.html)
+ * technique with no JavaScript — pure in-page anchor navigation.
+ *
+ * `SkipNav` is a stateless pair of sub-components used as siblings (not
+ * nested). Render the link first; place the content wrapper at the start of
+ * the main content area:
+ *
+ * - {@link SkipNavLink | `SkipNav.Link`} — the `<a>` skip link; must be
+ *   the first focusable element on the page.
+ * - {@link SkipNavContent | `SkipNav.Content`} — the `<div tabIndex={-1}>`
+ *   target; wrap it around (or immediately before) your main content.
+ *
+ * The two sub-components are connected by a shared content id
+ * (`"primitiv-skip-nav"`) with no configuration required. Override both
+ * sides when you need a custom id.
+ *
+ * @example Minimal usage
+ * ```tsx
+ * import { SkipNav } from "@primitiv-ui/react";
+ *
+ * export function App() {
+ *   return (
+ *     <>
+ *       <SkipNav.Link>Skip to main content</SkipNav.Link>
+ *       <header>...site navigation...</header>
+ *       <SkipNav.Content>
+ *         <main>...</main>
+ *       </SkipNav.Content>
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @example Custom id — both sides must match
+ * ```tsx
+ * <SkipNav.Link contentId="main">Skip to main content</SkipNav.Link>
+ * <SkipNav.Content id="main">
+ *   <main>...</main>
+ * </SkipNav.Content>
+ * ```
+ *
+ * @see {@link SkipNavLink} for the `contentId` contract and the
+ *   visually-hidden-until-focused CSS pattern.
+ * @see {@link SkipNavContent} for the `tabIndex={-1}` focus-target behaviour.
+ */
+declare const SkipNav: {
+    Link: typeof SkipNavLink;
+    Content: typeof SkipNavContent;
+};
+export { SkipNav };

package/dist/SkipNav/SkipNav.js

@@ -0,0 +1,138 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+const DEFAULT_CONTENT_ID = "primitiv-skip-nav";
+/**
+ * The skip link — an `<a>` that jumps keyboard and screen-reader users past
+ * repeated navigation straight to the main content.
+ *
+ * Place it as the very first focusable element on the page (typically the
+ * first child of `<body>`). It is a plain in-page anchor: its `href` is a
+ * URL fragment pointing at the `id` of the matching {@link SkipNavContent |
+ * `SkipNav.Content`}, so following it moves focus there with no JavaScript.
+ *
+ * **`contentId`.** The `href` is derived as `#${contentId}` and defaults to
+ * a shared id (`"primitiv-skip-nav"`), so an unconfigured
+ * `SkipNav.Link` / `SkipNav.Content` pair works out of the box. Override
+ * `contentId` on the link only if you also set a matching `id` on
+ * {@link SkipNavContent | `SkipNav.Content`}.
+ *
+ * **Visibility.** No styles ship with the component. The conventional
+ * pattern keeps the link visually hidden until it receives focus — position
+ * it off-screen by default and restore it on `:focus`. Do **not** use
+ * `display: none` or `visibility: hidden`, as those remove it from the tab
+ * order entirely:
+ *
+ * ```css
+ * a[href="#primitiv-skip-nav"] { position: absolute; left: -9999px; }
+ * a[href="#primitiv-skip-nav"]:focus { left: 0; top: 0; }
+ * ```
+ *
+ * Alternatively, pass a `className` and target that class in your
+ * stylesheet.
+ *
+ * @extends HTMLAnchorElement
+ *
+ * @example Default — shared content id
+ * ```tsx
+ * <SkipNav.Link>Skip to main content</SkipNav.Link>
+ * ```
+ *
+ * @example Custom content id (must match the `id` on `SkipNav.Content`)
+ * ```tsx
+ * <SkipNav.Link contentId="main">Skip to main content</SkipNav.Link>
+ * ```
+ */
+function SkipNavLink({ children, contentId = DEFAULT_CONTENT_ID, ...rest }) {
+    return (_jsx("a", { href: `#${contentId}`, ...rest, children: children }));
+}
+SkipNavLink.displayName = "SkipNavLink";
+/**
+ * The skip target — a `<div tabIndex={-1}>` placed at the start of the main
+ * content that {@link SkipNavLink | `SkipNav.Link`} jumps to.
+ *
+ * `tabIndex={-1}` makes the element a valid programmatic focus destination:
+ * when the link is followed the browser scrolls to this element *and* moves
+ * focus into it, so the next <kbd>Tab</kbd> press continues from within the
+ * main content rather than cycling back to the top of the page. No
+ * JavaScript runs; it is pure anchor navigation.
+ *
+ * **`id`.** Defaults to the same shared id (`"primitiv-skip-nav"`) as
+ * {@link SkipNavLink | `SkipNav.Link`}'s `contentId`. Pass a custom `id`
+ * via the native `id` prop only if you set a matching `contentId` on the
+ * link — the spread props override the default, so the two always stay in
+ * sync.
+ *
+ * @extends HTMLDivElement
+ *
+ * @example Default — wraps the main page content
+ * ```tsx
+ * <SkipNav.Content>
+ *   <main>...</main>
+ * </SkipNav.Content>
+ * ```
+ *
+ * @example Custom id (must match `contentId` on `SkipNav.Link`)
+ * ```tsx
+ * <SkipNav.Content id="main">
+ *   <main>...</main>
+ * </SkipNav.Content>
+ * ```
+ */
+function SkipNavContent({ children, ...rest }) {
+    return (_jsx("div", { id: DEFAULT_CONTENT_ID, tabIndex: -1, ...rest, children: children }));
+}
+SkipNavContent.displayName = "SkipNavContent";
+/**
+ * Headless, accessible **Skip Nav** — a "skip to main content" link and its
+ * focus target, letting keyboard and screen-reader users bypass repeated
+ * navigation. Implements the
+ * [WCAG 2.4.1 Bypass Blocks](https://www.w3.org/WAI/WCAG22/Understanding/bypass-blocks.html)
+ * technique with no JavaScript — pure in-page anchor navigation.
+ *
+ * `SkipNav` is a stateless pair of sub-components used as siblings (not
+ * nested). Render the link first; place the content wrapper at the start of
+ * the main content area:
+ *
+ * - {@link SkipNavLink | `SkipNav.Link`} — the `<a>` skip link; must be
+ *   the first focusable element on the page.
+ * - {@link SkipNavContent | `SkipNav.Content`} — the `<div tabIndex={-1}>`
+ *   target; wrap it around (or immediately before) your main content.
+ *
+ * The two sub-components are connected by a shared content id
+ * (`"primitiv-skip-nav"`) with no configuration required. Override both
+ * sides when you need a custom id.
+ *
+ * @example Minimal usage
+ * ```tsx
+ * import { SkipNav } from "@primitiv-ui/react";
+ *
+ * export function App() {
+ *   return (
+ *     <>
+ *       <SkipNav.Link>Skip to main content</SkipNav.Link>
+ *       <header>...site navigation...</header>
+ *       <SkipNav.Content>
+ *         <main>...</main>
+ *       </SkipNav.Content>
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @example Custom id — both sides must match
+ * ```tsx
+ * <SkipNav.Link contentId="main">Skip to main content</SkipNav.Link>
+ * <SkipNav.Content id="main">
+ *   <main>...</main>
+ * </SkipNav.Content>
+ * ```
+ *
+ * @see {@link SkipNavLink} for the `contentId` contract and the
+ *   visually-hidden-until-focused CSS pattern.
+ * @see {@link SkipNavContent} for the `tabIndex={-1}` focus-target behaviour.
+ */
+const SkipNav = {
+    Link: SkipNavLink,
+    Content: SkipNavContent,
+};
+export { SkipNav };

package/dist/SkipNav/index.d.ts

@@ -0,0 +1 @@
+export * from "./SkipNav.js";

package/dist/SkipNav/index.js

@@ -0,0 +1 @@
+export * from "./SkipNav.js";

package/dist/SkipNav/types.d.ts

@@ -0,0 +1,32 @@
+import type { AnchorHTMLAttributes, HTMLAttributes, ReactNode } from "react";
+/**
+ * Props for {@link SkipNavLink | `SkipNav.Link`} — `children`, an optional
+ * `contentId`, plus all native `<a>` attributes.
+ */
+export type SkipNavLinkProps = {
+    /** The visible link text (e.g. `"Skip to main content"`). */
+    children?: ReactNode;
+    /**
+     * Id of the matching {@link SkipNavContent | `SkipNav.Content`} target.
+     * The link's `href` is derived as `#${contentId}`. Defaults to the shared
+     * id (`"primitiv-skip-nav"`), so an unconfigured
+     * `SkipNav.Link` / `SkipNav.Content` pair works out of the box. Override
+     * only when you also set a matching native `id` prop on `SkipNav.Content`.
+     * @default "primitiv-skip-nav"
+     */
+    contentId?: string;
+} & AnchorHTMLAttributes<HTMLAnchorElement>;
+/**
+ * Props for {@link SkipNavContent | `SkipNav.Content`} — `children` plus
+ * all native `<div>` attributes.
+ *
+ * The component always renders with `tabIndex={-1}` (making it a valid
+ * programmatic focus target) and sets `id` to `"primitiv-skip-nav"` by
+ * default. Pass a native `id` prop to override the default; when you do,
+ * set the same value as `contentId` on {@link SkipNavLink | `SkipNav.Link`}
+ * so the anchor's `href` resolves correctly.
+ */
+export type SkipNavContentProps = {
+    /** The main page content that follows the skip target. */
+    children?: ReactNode;
+} & HTMLAttributes<HTMLDivElement>;

package/dist/SkipNav/types.js

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