@primitiv-ui/react 0.1.38 → 0.1.39

package/README.md

@@ -7,13 +7,35 @@ Zero styles ship with this package — style them with whatever system you use
 
 ## Installation
 
-The package is part of the Primitiv monorepo. Within the workspace, import
-directly:
+```sh
+npm i @primitiv-ui/react
+```
 
 ```tsx
 import { Tabs } from "@primitiv-ui/react";
 ```
 
+The npm package ships compiled JavaScript with type declarations, so it works
+with any bundler and any `tsconfig` — including the defaults from
+`npm create vite` and `create-next-app` — and loads in plain Node for SSR and
+tests. (JSR serves the TypeScript source.)
+
+### Next.js App Router and Server Components
+
+Every component module is marked `"use client"`, so you can import from
+`@primitiv-ui/react` directly in a Server Component — the client boundary forms
+at the component itself.
+
+One limit comes from React, not Primitiv: a Server Component cannot reach into
+a client component's properties, so the compound form (`Tabs.Root`) only works
+inside a `"use client"` file. In a Server Component, use the flat exports every
+compound also provides:
+
+```tsx
+// app/page.tsx — a Server Component
+import { TabsRoot, TabsList, TabsTrigger, TabsContent } from "@primitiv-ui/react";
+```
+
 ## Components
 
 | Component                                | Description                                                                                                                                                                                                                                                                             |

package/dist/AccessibleIcon/AccessibleIcon.d.ts

@@ -0,0 +1,51 @@
+import { ReactElement } from "react";
+import { AccessibleIconProps } from "./types.js";
+/**
+ * Gives an icon-only control an accessible name without adding a visible label.
+ *
+ * Wraps a single decorative icon element and performs two mutations via
+ * `cloneElement`:
+ *
+ * - Sets `aria-hidden="true"` on the icon, removing the purely decorative
+ *   graphic from the accessibility tree.
+ * - Sets `focusable="false"` on the icon, so legacy browsers (IE/Edge
+ *   classic) do not place the `<svg>` in the tab order.
+ *
+ * The {@link AccessibleIconProps.label | `label`} string is rendered
+ * alongside the icon inside a {@link VisuallyHidden} span — invisible on
+ * screen but announced by assistive technology. When `AccessibleIcon` is
+ * placed inside an interactive element (`<button>`, `<a>`, etc.), the
+ * hidden label becomes that element's accessible name. A screen reader
+ * will announce, for example, "Close dialog, button" rather than nothing.
+ *
+ * **Runtime validation.** `children` must be exactly **one** React
+ * element. Passing zero, multiple, or a plain string throws a React
+ * `Children.only` error. Wrap the glyph in a single `<svg>` or component
+ * if your icon library returns a fragment.
+ *
+ * **Renders no host element.** `AccessibleIcon` returns a React fragment
+ * (`<>...</>`), so it adds no DOM node of its own. The icon element and the
+ * {@link VisuallyHidden} span are the only nodes emitted.
+ *
+ * @example Icon-only button
+ * ```tsx
+ * <button>
+ *   <AccessibleIcon label="Close dialog">
+ *     <CloseIcon />
+ *   </AccessibleIcon>
+ * </button>
+ * ```
+ *
+ * @example Icon-only link
+ * ```tsx
+ * <a href="/home">
+ *   <AccessibleIcon label="Go to home page">
+ *     <HomeIcon />
+ *   </AccessibleIcon>
+ * </a>
+ * ```
+ */
+export declare function AccessibleIcon({ label, children, }: AccessibleIconProps): ReactElement;
+export declare namespace AccessibleIcon {
+    var displayName: string;
+}

package/dist/AccessibleIcon/AccessibleIcon.js

@@ -0,0 +1,55 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Children, cloneElement } from "react";
+import { VisuallyHidden } from "../VisuallyHidden/index.js";
+/**
+ * Gives an icon-only control an accessible name without adding a visible label.
+ *
+ * Wraps a single decorative icon element and performs two mutations via
+ * `cloneElement`:
+ *
+ * - Sets `aria-hidden="true"` on the icon, removing the purely decorative
+ *   graphic from the accessibility tree.
+ * - Sets `focusable="false"` on the icon, so legacy browsers (IE/Edge
+ *   classic) do not place the `<svg>` in the tab order.
+ *
+ * The {@link AccessibleIconProps.label | `label`} string is rendered
+ * alongside the icon inside a {@link VisuallyHidden} span — invisible on
+ * screen but announced by assistive technology. When `AccessibleIcon` is
+ * placed inside an interactive element (`<button>`, `<a>`, etc.), the
+ * hidden label becomes that element's accessible name. A screen reader
+ * will announce, for example, "Close dialog, button" rather than nothing.
+ *
+ * **Runtime validation.** `children` must be exactly **one** React
+ * element. Passing zero, multiple, or a plain string throws a React
+ * `Children.only` error. Wrap the glyph in a single `<svg>` or component
+ * if your icon library returns a fragment.
+ *
+ * **Renders no host element.** `AccessibleIcon` returns a React fragment
+ * (`<>...</>`), so it adds no DOM node of its own. The icon element and the
+ * {@link VisuallyHidden} span are the only nodes emitted.
+ *
+ * @example Icon-only button
+ * ```tsx
+ * <button>
+ *   <AccessibleIcon label="Close dialog">
+ *     <CloseIcon />
+ *   </AccessibleIcon>
+ * </button>
+ * ```
+ *
+ * @example Icon-only link
+ * ```tsx
+ * <a href="/home">
+ *   <AccessibleIcon label="Go to home page">
+ *     <HomeIcon />
+ *   </AccessibleIcon>
+ * </a>
+ * ```
+ */
+export function AccessibleIcon({ label, children, }) {
+    const icon = Children.only(children);
+    return (_jsxs(_Fragment, { children: [cloneElement(icon, { "aria-hidden": "true", focusable: "false" }), _jsx(VisuallyHidden, { children: label })] }));
+}
+/** @internal */
+AccessibleIcon.displayName = "AccessibleIcon";

package/dist/AccessibleIcon/index.d.ts

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

package/dist/AccessibleIcon/index.js

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

package/dist/AccessibleIcon/types.d.ts

@@ -0,0 +1,24 @@
+import { ReactElement } from "react";
+/**
+ * Props for {@link AccessibleIcon} — a single icon element plus the
+ * visually-hidden `label` announced as its accessible name.
+ *
+ * `AccessibleIconProps` does not extend any HTML element props: the
+ * component renders a React fragment with no host element of its own.
+ */
+export type AccessibleIconProps = {
+    /**
+     * Text announced by assistive technology as the accessible name of the
+     * surrounding interactive control. Keep it concise and action-oriented
+     * (e.g. `"Close dialog"`, `"Go to home page"`). This string is rendered
+     * inside a {@link VisuallyHidden} span — it is never visible on screen.
+     */
+    label: string;
+    /**
+     * Exactly one React element representing the icon (typically an `<svg>`
+     * or a component that renders one). The element is cloned with
+     * `aria-hidden="true"` and `focusable="false"` applied. Passing zero,
+     * multiple, or a non-element child throws a React `Children.only` error.
+     */
+    children: ReactElement;
+};

package/dist/AccessibleIcon/types.js

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

package/dist/Accordion/Accordion.d.ts

@@ -0,0 +1,287 @@
+import type { ReactElement } from "react";
+import type { AccordionRootProps, AccordionItemProps, AccordionTriggerProps, AccordionHeaderProps, AccordionContentProps, AccordionTriggerIconProps } from "./types.js";
+/**
+ * The root of an Accordion widget — owns the expanded-items state, provides
+ * context to descendants, and renders a plain `<div>`.
+ *
+ * Supports two state modes, statically discriminated at the type level:
+ *
+ * - **Uncontrolled** — pass {@link AccordionRootUncontrolledProps.defaultValue | `defaultValue`}
+ *   (or omit it to start with all items collapsed). The component owns and
+ *   updates the expanded set internally.
+ * - **Controlled** — pass {@link AccordionRootControlledProps.value | `value`} *and*
+ *   {@link AccordionRootControlledProps.onValueChange | `onValueChange`} together.
+ *   The parent owns the expanded set; the component defers every state change
+ *   back through the callback.
+ *
+ * In both modes, `multiple` controls whether more than one item can be open
+ * simultaneously. By default only one item can be expanded at a time — opening
+ * a new item collapses the previous one.
+ *
+ * **Styling hooks.** `data-orientation="vertical" | "horizontal"` is set on
+ * the rendered container. No `aria-orientation` is emitted because it is not
+ * valid on a `<div>` according to the WAI-ARIA spec.
+ *
+ * **Reading direction.** `dir` (`"ltr"` / `"rtl"`) sets the arrow-key
+ * direction for horizontal accordions and the container's `dir` attribute.
+ * When omitted, it is inherited from the nearest {@link DirectionProvider},
+ * falling back to `"ltr"` when there is no provider.
+ *
+ * @extends HTMLDivElement
+ *
+ * @example Uncontrolled — single open item
+ * ```tsx
+ * <Accordion.Root defaultValue="item-1">
+ *   <Accordion.Item value="item-1">...</Accordion.Item>
+ *   <Accordion.Item value="item-2">...</Accordion.Item>
+ * </Accordion.Root>
+ * ```
+ *
+ * @example Controlled — multiple open items
+ * ```tsx
+ * const [expanded, setExpanded] = useState<string[]>([]);
+ *
+ * <Accordion.Root multiple value={expanded} onValueChange={setExpanded}>
+ *   <Accordion.Item value="shipping">...</Accordion.Item>
+ *   <Accordion.Item value="returns">...</Accordion.Item>
+ * </Accordion.Root>
+ * ```
+ */
+export declare function AccordionRoot({ children, multiple, defaultValue, value: controlledValue, onValueChange, orientation, dir, ...rest }: AccordionRootProps): ReactElement;
+export declare namespace AccordionRoot {
+    var displayName: string;
+}
+/**
+ * A single collapsible section within an accordion. Wraps one
+ * `Accordion.Header` + `Accordion.Content` pair and tracks their shared
+ * expanded / collapsed state via context.
+ *
+ * The {@link AccordionItemProps.value | `value`} prop is the stable identifier
+ * used to match this item against the root's expanded set. If omitted, a
+ * stable auto-generated ID is used via `useId()` — useful for fully anonymous
+ * items where the consumer doesn't need to drive state from outside.
+ *
+ * @extends HTMLDivElement
+ *
+ * @example
+ * ```tsx
+ * <Accordion.Item value="shipping">
+ *   <Accordion.Header>
+ *     <Accordion.Trigger>Shipping</Accordion.Trigger>
+ *   </Accordion.Header>
+ *   <Accordion.Content>Free on orders over £50.</Accordion.Content>
+ * </Accordion.Item>
+ * ```
+ */
+export declare function AccordionItem({ children, value, ...rest }: AccordionItemProps): ReactElement;
+export declare namespace AccordionItem {
+    var displayName: string;
+}
+/**
+ * Renders the heading element that wraps an `Accordion.Trigger`. Defaults to
+ * `<h3>` but the level is configurable via the
+ * {@link AccordionHeaderProps.level | `level`} prop so the heading hierarchy
+ * of the surrounding page is preserved.
+ *
+ * The WAI-ARIA Accordion pattern requires each trigger to be wrapped in a
+ * heading at the appropriate level for its position in the document outline.
+ *
+ * @extends HTMLHeadingElement
+ *
+ * @example
+ * ```tsx
+ * <Accordion.Header level={2}>
+ *   <Accordion.Trigger>Shipping policy</Accordion.Trigger>
+ * </Accordion.Header>
+ * ```
+ */
+export declare function AccordionHeader({ children, level, ...rest }: AccordionHeaderProps): ReactElement;
+export declare namespace AccordionHeader {
+    var displayName: string;
+}
+/**
+ * The button that toggles an accordion item open or closed. Renders
+ * `<button type="button">` by default and wires up all required ARIA
+ * attributes, click handling, and keyboard navigation automatically.
+ *
+ * **Disabled behaviour.** When `disabled` is `true` the trigger is rendered
+ * with `aria-disabled="true"` and `data-disabled="true"` instead of the
+ * native HTML `disabled` attribute. This keeps the button focusable so
+ * keyboard users can discover it, while preventing activation.  Disabled
+ * triggers are excluded from arrow-key navigation.
+ *
+ * **`asChild` prop.** Pass `asChild` to render an arbitrary child element
+ * instead of the default `<button>`. All accordion ARIA attributes, event
+ * handlers, and the internal ref are merged onto the child following the
+ * Composition pattern:
+ * - Event handlers compose — the child's handler runs first, then the trigger's.
+ * - `style` is shallow-merged (child wins on collisions).
+ * - `className` strings are concatenated.
+ * - Refs from both sides are composed via `composeRefs`.
+ *
+ * When `asChild` is `true` and `disabled` is `true`, `role="button"` is
+ * automatically injected so that `aria-disabled` is semantically valid on
+ * non-button elements (e.g. `<a>`, `<div>`). Without a button role the
+ * `aria-disabled` attribute has no defined meaning in the ARIA spec.
+ *
+ * **Keyboard support** (WAI-ARIA Accordion pattern):
+ *
+ * | Key               | Behaviour                                    |
+ * | ----------------- | -------------------------------------------- |
+ * | `Enter` / `Space` | Toggle the focused item                      |
+ * | `ArrowDown`       | Move focus to next trigger (vertical)        |
+ * | `ArrowUp`         | Move focus to previous trigger (vertical)    |
+ * | `ArrowRight`      | Move focus to next trigger (horizontal)      |
+ * | `ArrowLeft`       | Move focus to previous trigger (horizontal)  |
+ * | `Home`            | Move focus to first enabled trigger          |
+ * | `End`             | Move focus to last enabled trigger           |
+ *
+ * Movement **wraps** at the ends. For horizontal orientation with
+ * `dir="rtl"`, `ArrowLeft` moves forward and `ArrowRight` moves backward.
+ *
+ * **Ref forwarding.** A `ref` prop (React 19 ref-as-prop style) is forwarded
+ * to the underlying DOM element — useful for imperative focus management.
+ *
+ * **Styling hooks.**
+ * - `data-state="open" | "closed"` on the rendered element.
+ * - `data-disabled="true" | "false"`.
+ *
+ * @extends HTMLButtonElement
+ *
+ * @example Basic
+ * ```tsx
+ * <Accordion.Trigger>Shipping policy</Accordion.Trigger>
+ * ```
+ *
+ * @example Disabled
+ * ```tsx
+ * <Accordion.Trigger disabled>Unavailable section</Accordion.Trigger>
+ * ```
+ *
+ * @example asChild — render a link with accordion semantics
+ * ```tsx
+ * <Accordion.Trigger asChild>
+ *   <a href="#shipping">Shipping policy</a>
+ * </Accordion.Trigger>
+ * ```
+ */
+export declare function AccordionTrigger<T extends HTMLElement = HTMLButtonElement>({ ref, children, onClick, disabled, asChild, ...rest }: AccordionTriggerProps<T>): ReactElement;
+export declare namespace AccordionTrigger {
+    var displayName: string;
+}
+/**
+ * The panel that is revealed when the associated `Accordion.Trigger` is
+ * activated. Renders a `<div role="region" aria-labelledby="...">` whose
+ * visibility is controlled by the `hidden` attribute.
+ *
+ * **`forceMount` prop.** By default the panel is removed from visibility with
+ * `hidden` when closed. Pass `forceMount` to keep the panel in the DOM at all
+ * times. In `forceMount` mode the `hidden` attribute is never set, so
+ * CSS transitions on open / close work correctly — consumers can use
+ * `[data-state="closed"] { display: none; }` (or equivalent animation
+ * classes) to control visibility themselves.
+ *
+ * When `forceMount` is `true` and the panel is closed, `aria-hidden="true"` is
+ * set automatically so assistive technology ignores the off-screen content.
+ * It is removed when the panel opens. Consumers can override this by passing
+ * `aria-hidden` explicitly (it appears after the automatic value in the spread).
+ *
+ * **`role="region"` escape hatch.** Each panel renders with `role="region"` by
+ * default, creating an ARIA landmark. Accordions with many items can produce
+ * landmark overload in screen readers. Opt out by passing `role={undefined}`:
+ * ```tsx
+ * <Accordion.Content role={undefined}>...</Accordion.Content>
+ * ```
+ *
+ * **Styling hooks.**
+ * - `data-state="open" | "closed"` on the rendered element.
+ *
+ * @extends HTMLDivElement
+ *
+ * @example Default (hidden attribute)
+ * ```tsx
+ * <Accordion.Content>Free shipping on orders over £50.</Accordion.Content>
+ * ```
+ *
+ * @example With forceMount for CSS animations
+ * ```tsx
+ * <Accordion.Content forceMount className="panel">
+ *   Content that animates in and out.
+ * </Accordion.Content>
+ * ```
+ */
+export declare function AccordionContent({ children, forceMount, ...rest }: AccordionContentProps): ReactElement;
+export declare namespace AccordionContent {
+    var displayName: string;
+}
+/**
+ * A wrapper that hides its icon child from the accessibility tree and
+ * provides a `data-state` hook for open/close animations. Accepts any
+ * renderable React content as a child — an inline `<svg>`, a component
+ * from a third-party icon library (lucide-react, react-icons, etc.), or
+ * any custom icon component.
+ *
+ * Renders a `<span>` with `aria-hidden="true"` around the child so the
+ * icon is hidden from assistive technology regardless of whether the child
+ * component forwards unknown props. Any additional props (`className`,
+ * `data-*`, `ref`, etc.) are forwarded to that `<span>`.
+ *
+ * **Styling hooks.**
+ * - `data-state="open" | "closed"` on the rendered `<span>`.
+ * - `aria-hidden="true"` on the rendered `<span>`.
+ *
+ * @extends HTMLSpanElement
+ *
+ * @example Inline SVG
+ * ```tsx
+ * <Accordion.Trigger>
+ *   Shipping policy
+ *   <Accordion.TriggerIcon>
+ *     <svg ...><path d="..." /></svg>
+ *   </Accordion.TriggerIcon>
+ * </Accordion.Trigger>
+ * ```
+ *
+ * @example Third-party icon component
+ * ```tsx
+ * import { ChevronDown } from "lucide-react";
+ *
+ * <Accordion.Trigger>
+ *   Shipping policy
+ *   <Accordion.TriggerIcon>
+ *     <ChevronDown />
+ *   </Accordion.TriggerIcon>
+ * </Accordion.Trigger>
+ * ```
+ */
+export declare function AccordionTriggerIcon({ children, ...rest }: AccordionTriggerIconProps): ReactElement;
+export declare namespace AccordionTriggerIcon {
+    var displayName: string;
+}
+/** @internal */
+type AccordionCompound = typeof AccordionRoot & {
+    Root: typeof AccordionRoot;
+    Item: typeof AccordionItem;
+    Header: typeof AccordionHeader;
+    Trigger: typeof AccordionTrigger;
+    Content: typeof AccordionContent;
+    TriggerIcon: typeof AccordionTriggerIcon;
+};
+/**
+ * Headless, accessible **Accordion** — a compound component for a vertically
+ * (or horizontally) stacked set of collapsible sections, following the
+ * [WAI-ARIA Accordion pattern](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/)
+ * with zero styles.
+ *
+ * `Accordion` is both callable (an alias of {@link AccordionRoot | `Accordion.Root`})
+ * and carries its sub-components as static properties:
+ *
+ * - {@link AccordionRoot | `Accordion.Root`} — state owner and context provider.
+ * - {@link AccordionItem | `Accordion.Item`} — one collapsible section.
+ * - {@link AccordionHeader | `Accordion.Header`} — heading wrapper for the trigger.
+ * - {@link AccordionTrigger | `Accordion.Trigger`} — button that toggles the section.
+ * - {@link AccordionContent | `Accordion.Content`} — the collapsible panel.
+ * - {@link AccordionTriggerIcon | `Accordion.TriggerIcon`} — decorative state indicator.
+ */
+declare const AccordionCompound: AccordionCompound;
+export { AccordionCompound as Accordion };