@primitiv-ui/react 0.1.38 → 0.1.39

package/dist/DirectionProvider/DirectionProvider.js

@@ -0,0 +1,59 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { DirectionContext } from "./DirectionContext.js";
+/**
+ * Broadcasts a reading direction to every descendant so direction-aware
+ * components can inherit it through context instead of each being passed
+ * an explicit `dir` prop.
+ *
+ * Renders **no DOM host element** — only a React context provider.
+ * Direction is never inferred from the DOM; the consumer still owns
+ * setting `dir` on their `<html>` (or another ancestor element) for
+ * CSS purposes. This component only propagates the {@link Direction}
+ * value to `@primitiv-ui/react` components.
+ *
+ * **Override precedence.** A descendant component's own `dir` prop
+ * always wins over the inherited value; components fall back to
+ * {@link useDirection} only when their `dir` prop is omitted:
+ *
+ * ```tsx
+ * <DirectionProvider dir="rtl">
+ *   {/* inherits rtl *\/}
+ *   <Tabs.Root defaultValue="a">...</Tabs.Root>
+ *   {/* explicit ltr overrides the provider *\/}
+ *   <Tabs.Root dir="ltr" defaultValue="a">...</Tabs.Root>
+ * </DirectionProvider>
+ * ```
+ *
+ * **Nesting.** Providers nest — an inner `DirectionProvider` overrides an
+ * outer one for its subtree.
+ *
+ * **`useDirection` hook.** Direction-aware sub-components read the
+ * inherited value via {@link useDirection}, which falls back to `"ltr"`
+ * when no provider is present.
+ *
+ * @example Declare direction once near the app root
+ * ```tsx
+ * import { DirectionProvider } from "@primitiv-ui/react";
+ *
+ * <DirectionProvider dir="rtl">
+ *   <Tabs.Root defaultValue="overview">...</Tabs.Root>
+ *   <Slider.Root defaultValue={[50]} aria-label="Volume" />
+ * </DirectionProvider>
+ * ```
+ *
+ * @example Nested providers — inner overrides outer for its subtree
+ * ```tsx
+ * <DirectionProvider dir="rtl">
+ *   <Tabs.Root defaultValue="a">...</Tabs.Root>
+ *   <DirectionProvider dir="ltr">
+ *     <Tabs.Root defaultValue="b">...</Tabs.Root>
+ *   </DirectionProvider>
+ * </DirectionProvider>
+ * ```
+ */
+export function DirectionProvider({ dir, children, }) {
+    return (_jsx(DirectionContext.Provider, { value: dir, children: children }));
+}
+/** @internal */
+DirectionProvider.displayName = "DirectionProvider";

package/dist/DirectionProvider/index.d.ts

@@ -0,0 +1,3 @@
+export { useDirection } from "./DirectionContext.js";
+export { DirectionProvider } from "./DirectionProvider.js";
+export type { Direction, DirectionProviderProps } from "./types.js";

package/dist/DirectionProvider/index.js

@@ -0,0 +1,2 @@
+export { useDirection } from "./DirectionContext.js";
+export { DirectionProvider } from "./DirectionProvider.js";

package/dist/DirectionProvider/types.d.ts

@@ -0,0 +1,34 @@
+import { ReactNode } from "react";
+/**
+ * A reading direction value — left-to-right or right-to-left.
+ *
+ * Used as the {@link DirectionProviderProps.dir | `dir`} prop on
+ * {@link DirectionProvider} and as the `dir` prop accepted by every
+ * direction-aware component (e.g. `Tabs.Root`, `Slider.Root`).
+ * {@link useDirection} returns this type.
+ */
+export type Direction = "ltr" | "rtl";
+/**
+ * Props for {@link DirectionProvider} — the reading direction broadcast to
+ * all descendant components.
+ *
+ * `DirectionProvider` accepts no native HTML element props: it renders no
+ * DOM host element and is a pure React context provider.
+ */
+export type DirectionProviderProps = {
+    /**
+     * The reading direction to broadcast to every descendant.
+     * See {@link Direction}.
+     *
+     * Direction-aware components (e.g. `Tabs.Root`, `Slider.Root`) read
+     * this value via {@link useDirection} when their own `dir` prop is
+     * omitted. An explicit `dir` prop on a descendant always takes
+     * precedence over the inherited value.
+     */
+    dir: Direction;
+    /**
+     * The subtree whose direction-aware components will inherit `dir`.
+     * Any React content is accepted; there is no DOM wrapper.
+     */
+    children?: ReactNode;
+};

package/dist/DirectionProvider/types.js

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

package/dist/Divider/Divider.d.ts

@@ -0,0 +1,59 @@
+import type { ReactElement } from "react";
+import { DividerProps } from "./types.js";
+/**
+ * A headless `<span role="separator">` that marks a visual and semantic
+ * boundary between content sections.
+ *
+ * Renders a native `<span>` with `role="separator"` and the matching
+ * `aria-orientation` attribute. Screen readers announce it as a separator,
+ * which is appropriate when the divider conveys genuine structural meaning
+ * (e.g. separating navigation groups or distinct content areas).
+ *
+ * **Decorative use.** When the divider is purely visual and carries no
+ * semantic meaning, pass `aria-hidden="true"` to remove it from the
+ * accessibility tree entirely:
+ *
+ * ```tsx
+ * <Divider aria-hidden="true" />
+ * ```
+ *
+ * **Styling hooks.** No styles ship with the component. Because Divider
+ * emits no `data-*` attributes, target the rendered element via the
+ * `aria-orientation` attribute selector or a `className`:
+ *
+ * ```css
+ * [role="separator"][aria-orientation="horizontal"] { height: 1px; width: 100%; background: currentColor; }
+ * [role="separator"][aria-orientation="vertical"]   { width: 1px; height: 100%; background: currentColor; }
+ * ```
+ *
+ * ```tsx
+ * <Divider className="my-divider" />
+ * <Divider orientation="vertical" className="my-divider--vertical" />
+ * ```
+ *
+ * @extends HTMLSpanElement
+ *
+ * @example Horizontal (default)
+ * ```tsx
+ * <Divider />
+ * ```
+ *
+ * @example Vertical
+ * ```tsx
+ * <Divider orientation="vertical" />
+ * ```
+ *
+ * @example Decorative — hidden from screen readers
+ * ```tsx
+ * <Divider aria-hidden="true" />
+ * ```
+ *
+ * @example With a className
+ * ```tsx
+ * <Divider className="my-section-rule" />
+ * ```
+ */
+export declare function Divider({ orientation, className, ...rest }: DividerProps): ReactElement;
+export declare namespace Divider {
+    var displayName: string;
+}

package/dist/Divider/Divider.js

@@ -0,0 +1,60 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * A headless `<span role="separator">` that marks a visual and semantic
+ * boundary between content sections.
+ *
+ * Renders a native `<span>` with `role="separator"` and the matching
+ * `aria-orientation` attribute. Screen readers announce it as a separator,
+ * which is appropriate when the divider conveys genuine structural meaning
+ * (e.g. separating navigation groups or distinct content areas).
+ *
+ * **Decorative use.** When the divider is purely visual and carries no
+ * semantic meaning, pass `aria-hidden="true"` to remove it from the
+ * accessibility tree entirely:
+ *
+ * ```tsx
+ * <Divider aria-hidden="true" />
+ * ```
+ *
+ * **Styling hooks.** No styles ship with the component. Because Divider
+ * emits no `data-*` attributes, target the rendered element via the
+ * `aria-orientation` attribute selector or a `className`:
+ *
+ * ```css
+ * [role="separator"][aria-orientation="horizontal"] { height: 1px; width: 100%; background: currentColor; }
+ * [role="separator"][aria-orientation="vertical"]   { width: 1px; height: 100%; background: currentColor; }
+ * ```
+ *
+ * ```tsx
+ * <Divider className="my-divider" />
+ * <Divider orientation="vertical" className="my-divider--vertical" />
+ * ```
+ *
+ * @extends HTMLSpanElement
+ *
+ * @example Horizontal (default)
+ * ```tsx
+ * <Divider />
+ * ```
+ *
+ * @example Vertical
+ * ```tsx
+ * <Divider orientation="vertical" />
+ * ```
+ *
+ * @example Decorative — hidden from screen readers
+ * ```tsx
+ * <Divider aria-hidden="true" />
+ * ```
+ *
+ * @example With a className
+ * ```tsx
+ * <Divider className="my-section-rule" />
+ * ```
+ */
+export function Divider({ orientation = "horizontal", className = "", ...rest }) {
+    return (_jsx("span", { role: "separator", "aria-orientation": orientation, className: className, ...rest }));
+}
+/** @internal */
+Divider.displayName = "Divider";

package/dist/Divider/index.d.ts

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

package/dist/Divider/index.js

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

package/dist/Divider/types.d.ts

@@ -0,0 +1,16 @@
+import { ComponentProps } from "react";
+/**
+ * Props for {@link Divider} — all native `<span>` attributes plus an
+ * `orientation` that controls both the visual axis and the `aria-orientation`
+ * value announced to assistive technology.
+ */
+export type DividerProps = ComponentProps<"span"> & {
+    /**
+     * Axis the separator runs along. Sets `aria-orientation` on the rendered
+     * `<span role="separator">` so screen readers announce the correct
+     * orientation. Use `"horizontal"` for row-dividing rules and
+     * `"vertical"` for column-dividing rules.
+     * @default "horizontal"
+     */
+    orientation?: "horizontal" | "vertical";
+};

package/dist/Divider/types.js

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

package/dist/Drawer/Drawer.d.ts

@@ -0,0 +1,268 @@
+import type { ReactElement } from "react";
+import type { DrawerCloseProps, DrawerContentProps, DrawerDescriptionProps, DrawerOverlayProps, DrawerPortalProps, DrawerRootProps, DrawerTitleProps, DrawerTriggerProps } from "./types.js";
+/**
+ * The root of a Drawer — owns open state, registers the dialog's id,
+ * title id, and description id, and exposes an imperative handle for
+ * opening / closing from outside the React subtree.
+ *
+ * A Drawer *is* a {@link Modal | Modal} that slides in from a screen edge, so
+ * `Drawer.Root` delegates its entire behaviour to `Modal.Root`: the two
+ * state modes (uncontrolled `defaultOpen` vs. controlled `open` +
+ * `onOpenChange`, statically discriminated at the type level) and the
+ * imperative open/close API are identical.
+ *
+ * @example Uncontrolled
+ * ```tsx
+ * <Drawer.Root defaultOpen>
+ *   <Drawer.Content>...</Drawer.Content>
+ * </Drawer.Root>
+ * ```
+ *
+ * @example Controlled
+ * ```tsx
+ * const [open, setOpen] = useState(false);
+ *
+ * <Drawer.Root open={open} onOpenChange={setOpen}>
+ *   <Drawer.Trigger>Open</Drawer.Trigger>
+ *   <Drawer.Portal>
+ *     <Drawer.Overlay />
+ *     <Drawer.Content side="right">...</Drawer.Content>
+ *   </Drawer.Portal>
+ * </Drawer.Root>
+ * ```
+ */
+export declare function DrawerRoot(props: DrawerRootProps): ReactElement;
+export declare namespace DrawerRoot {
+    var displayName: string;
+}
+/**
+ * A button that toggles the drawer open. Renders a
+ * `<button type="button">` with full ARIA wiring inherited from
+ * `Modal.Trigger`:
+ *
+ * - `aria-haspopup="dialog"`
+ * - `aria-expanded` tracks open state
+ * - `aria-controls` points at the `Drawer.Content` dialog's id
+ *
+ * **`asChild` prop.** Pass `asChild` to render any consumer-supplied
+ * element (e.g. a router `<Link>`) with the trigger's ARIA attributes,
+ * composed event handlers, and ref merged in.
+ *
+ * @extends HTMLButtonElement
+ *
+ * @example
+ * ```tsx
+ * <Drawer.Trigger>Open menu</Drawer.Trigger>
+ *
+ * <Drawer.Trigger asChild>
+ *   <Link to="/cart">Cart</Link>
+ * </Drawer.Trigger>
+ * ```
+ */
+export declare function DrawerTrigger(props: DrawerTriggerProps): ReactElement;
+export declare namespace DrawerTrigger {
+    var displayName: string;
+}
+/**
+ * Renders its children through `React.createPortal` so the drawer is
+ * detached from wherever `Drawer.Root` lives in the React tree and becomes
+ * a direct child of `container` (default `document.body`).
+ *
+ * By default the portal only renders while the drawer is open. Pass
+ * `forceMount` to keep the subtree in the DOM after `open` flips false —
+ * useful for the CSS slide-out animation driven by `data-state="closed"`.
+ *
+ * @example
+ * ```tsx
+ * <Drawer.Portal container={document.getElementById("drawer-root")!}>
+ *   <Drawer.Overlay />
+ *   <Drawer.Content>...</Drawer.Content>
+ * </Drawer.Portal>
+ * ```
+ */
+export declare function DrawerPortal(props: DrawerPortalProps): ReactElement;
+export declare namespace DrawerPortal {
+    var displayName: string;
+}
+/**
+ * A decorative, animation-friendly backdrop rendered as a **sibling** of
+ * `Drawer.Content`. Like `Modal.Overlay` it is **not** the click-outside
+ * event surface — opening the native `<dialog>` via `showModal()` promotes
+ * it to the top layer with a browser-painted `::backdrop` above this
+ * overlay, so click-outside-to-close is wired on the dialog itself via
+ * `onPointerDownOutside`.
+ *
+ * - `aria-hidden="true"` (the backdrop is decorative).
+ * - `data-state="open" | "closed"` follows the drawer's open state.
+ *
+ * **`asChild` prop.** Pass `asChild` to render a consumer-supplied element
+ * (e.g. a motion wrapper) with the overlay's ARIA and data-state merged in.
+ *
+ * **`forceMount` prop.** Pass `forceMount` to keep the overlay in the DOM
+ * while `open` is false so a CSS fade-out can play.
+ *
+ * @extends HTMLDivElement
+ *
+ * @example
+ * ```tsx
+ * <Drawer.Overlay />
+ * ```
+ */
+export declare function DrawerOverlay(props: DrawerOverlayProps): ReactElement;
+export declare namespace DrawerOverlay {
+    var displayName: string;
+}
+/**
+ * The native `<dialog>` element — the sliding panel. Behaviour is
+ * `Modal.Content`'s: React drives `showModal()` / `close()` in response to
+ * open state, so the browser owns the inert background, the top layer, and
+ * the `Esc` key, while the same JS `Tab`-wrap focus trap (last ⇄ first)
+ * applies — inherited from `Modal.Content`. `aria-labelledby` /
+ * `aria-describedby` are wired automatically from `Drawer.Title` /
+ * `Drawer.Description`, and the `onEscapeKeyDown` / `onPointerDownOutside`
+ * escape hatches pass straight through.
+ *
+ * **The one drawer-specific addition —
+ * {@link DrawerContentProps.side | `side`}.** Which edge the panel slides in
+ * from (`"top" | "right" | "bottom" | "left"`, default `"right"`). It is
+ * emitted verbatim as `data-side` on the dialog for the styled layer to
+ * position and animate against; it changes no behaviour, focus, or ARIA.
+ *
+ * **`asChild` is intentionally not supported** (as with `Modal.Content`) —
+ * the native dialog is what provides the inert background and top layer (and
+ * hosts the inherited Tab-wrap focus trap).
+ *
+ * **Styling hooks.** `data-state="open" | "closed"` and
+ * `data-side="top|right|bottom|left"` on the dialog.
+ *
+ * @extends HTMLDialogElement
+ *
+ * @example Right-hand drawer (default)
+ * ```tsx
+ * <Drawer.Content>...</Drawer.Content>
+ * ```
+ *
+ * @example Bottom sheet
+ * ```tsx
+ * <Drawer.Content side="bottom">...</Drawer.Content>
+ * ```
+ */
+export declare function DrawerContent({ side, ...rest }: DrawerContentProps): ReactElement;
+export declare namespace DrawerContent {
+    var displayName: string;
+}
+/**
+ * The drawer's accessible name. Renders an `<h2>` by default and
+ * auto-registers its generated id so `Drawer.Content` can wire it up as
+ * `aria-labelledby` (via `Modal.Title`).
+ *
+ * Pass `asChild` to render the consumer's own heading element; the id is
+ * still registered.
+ *
+ * @extends HTMLHeadingElement
+ *
+ * @example
+ * ```tsx
+ * <Drawer.Title>Filters</Drawer.Title>
+ * ```
+ */
+export declare function DrawerTitle(props: DrawerTitleProps): ReactElement;
+export declare namespace DrawerTitle {
+    var displayName: string;
+}
+/**
+ * The drawer's accessible description. Renders a `<p>` by default and
+ * auto-registers its generated id so `Drawer.Content` can wire it up as
+ * `aria-describedby` (via `Modal.Description`).
+ *
+ * Pass `asChild` to render any consumer-supplied element; the id is still
+ * registered.
+ *
+ * @extends HTMLParagraphElement
+ *
+ * @example
+ * ```tsx
+ * <Drawer.Description>Narrow the results below.</Drawer.Description>
+ * ```
+ */
+export declare function DrawerDescription(props: DrawerDescriptionProps): ReactElement;
+export declare namespace DrawerDescription {
+    var displayName: string;
+}
+/**
+ * A button that closes the drawer. Renders a `<button type="button">`
+ * whose `onClick` is composed with the close action (via `Modal.Close`) —
+ * consumer handlers run first and can `event.preventDefault()` to veto.
+ *
+ * **`asChild` prop.** Pass `asChild` to render any element (e.g. an
+ * icon-only button of your own) with the close behaviour merged in.
+ *
+ * @extends HTMLButtonElement
+ *
+ * @example
+ * ```tsx
+ * <Drawer.Close>Done</Drawer.Close>
+ *
+ * <Drawer.Close asChild>
+ *   <IconButton aria-label="Close" icon={<XIcon />} />
+ * </Drawer.Close>
+ * ```
+ */
+export declare function DrawerClose(props: DrawerCloseProps): ReactElement;
+export declare namespace DrawerClose {
+    var displayName: string;
+}
+/** @internal */
+type DrawerCompound = typeof DrawerRoot & {
+    Root: typeof DrawerRoot;
+    Trigger: typeof DrawerTrigger;
+    Portal: typeof DrawerPortal;
+    Overlay: typeof DrawerOverlay;
+    Content: typeof DrawerContent;
+    Title: typeof DrawerTitle;
+    Description: typeof DrawerDescription;
+    Close: typeof DrawerClose;
+};
+/**
+ * Headless, accessible **Drawer** — a Modal dialog that slides in from a
+ * screen edge. It reuses {@link Modal | Modal}'s native-`<dialog>` machinery
+ * wholesale (focus trap, inert background, top layer, `Esc`, click-outside,
+ * controlled / uncontrolled state, the imperative API), adding a single
+ * presentational axis: {@link DrawerContentProps.side | `side`} on
+ * `Drawer.Content`, emitted as `data-side` for the styled layer to slide the
+ * panel from `top` / `right` / `bottom` / `left`.
+ *
+ * `Drawer` is both callable (an alias of {@link DrawerRoot | `Drawer.Root`})
+ * and carries its sub-components as static properties.
+ *
+ * - {@link DrawerRoot | `Drawer.Root`} — state owner, context provider, imperative API holder.
+ * - {@link DrawerTrigger | `Drawer.Trigger`} — `<button>` that opens the drawer.
+ * - {@link DrawerPortal | `Drawer.Portal`} — `createPortal` wrapper with `container` + `forceMount`.
+ * - {@link DrawerOverlay | `Drawer.Overlay`} — click-outside backdrop sibling of the dialog.
+ * - {@link DrawerContent | `Drawer.Content`} — native `<dialog>` with the `side` axis and auto-ARIA.
+ * - {@link DrawerTitle | `Drawer.Title`} — accessible name; auto-wires `aria-labelledby`.
+ * - {@link DrawerDescription | `Drawer.Description`} — auto-wires `aria-describedby`.
+ * - {@link DrawerClose | `Drawer.Close`} — `<button>` that closes the drawer.
+ *
+ * @example Minimal usage
+ * ```tsx
+ * import { Drawer } from "@primitiv-ui/react";
+ *
+ * <Drawer.Root>
+ *   <Drawer.Trigger>Open</Drawer.Trigger>
+ *   <Drawer.Portal>
+ *     <Drawer.Overlay />
+ *     <Drawer.Content side="right">
+ *       <Drawer.Title>Filters</Drawer.Title>
+ *       <Drawer.Description>Narrow the results below.</Drawer.Description>
+ *       <Drawer.Close>Done</Drawer.Close>
+ *     </Drawer.Content>
+ *   </Drawer.Portal>
+ * </Drawer.Root>;
+ * ```
+ *
+ * @see {@link Modal} for the shared dialog behaviour, state modes, and imperative API.
+ * @see {@link DrawerContent} for the `side` axis and the styling hooks.
+ */
+declare const DrawerCompound: DrawerCompound;
+export { DrawerCompound as Drawer };