@primitiv-ui/react 0.1.37 → 0.1.39

package/dist/Collapsible/hooks/useCollapsibleTrigger.js

@@ -0,0 +1,39 @@
+"use client";
+import { useRef } from "react";
+import { composeRefs } from "../../Slot/index.js";
+import { useCollapsibleContext } from "../CollapsibleContext.js";
+export function useCollapsibleTrigger({ ref, onClick, onKeyDown, 
+// No default: the `CollapsibleTrigger` component always supplies a resolved
+// `asChild` boolean, so a default here would be unreachable (dead) code.
+asChild, ...rest }) {
+    const { open, disabled, toggle, triggerId, contentId } = useCollapsibleContext();
+    const triggerRef = useRef(null);
+    const composedRef = ref ? composeRefs(triggerRef, ref) : triggerRef;
+    function handleClick(e) {
+        if (disabled)
+            return;
+        toggle();
+        onClick?.(e);
+    }
+    function handleKeyDown(e) {
+        onKeyDown?.(e);
+        if ((e.key === "Enter" || e.key === " ") && !disabled) {
+            e.preventDefault();
+            toggle();
+        }
+    }
+    const triggerProps = {
+        ref: composedRef,
+        id: triggerId,
+        "aria-expanded": open,
+        "aria-controls": contentId,
+        "aria-disabled": disabled || undefined,
+        "data-disabled": disabled,
+        "data-state": open ? "open" : "closed",
+        ...(asChild && disabled ? { role: "button" } : {}),
+        onClick: handleClick,
+        onKeyDown: handleKeyDown,
+        ...rest,
+    };
+    return { triggerProps };
+}

package/dist/Collapsible/index.d.ts

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

package/dist/Collapsible/index.js

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

package/dist/Collapsible/types.d.ts

@@ -0,0 +1,134 @@
+import { ComponentProps, ReactNode, Ref } from "react";
+/**
+ * Shared base for both {@link CollapsibleRootProps} variants — the native
+ * `<div>` attributes (minus the conflicting `onChange`) plus the `disabled`
+ * flag common to both state modes.
+ */
+export type CollapsibleRootBaseProps = Omit<ComponentProps<"div">, "onChange"> & {
+    /**
+     * When `true`, disables the widget: the {@link CollapsibleTriggerProps |
+     * Trigger} renders `aria-disabled="true"` (staying focusable) and both
+     * click and keyboard activation are short-circuited. Mirrored as
+     * `data-disabled` onto Root, Trigger, and Content.
+     * @default false
+     */
+    disabled?: boolean;
+};
+/**
+ * Uncontrolled variant of {@link CollapsibleRootProps}: the component owns
+ * the open state. Pass `defaultOpen` (or omit it); `open` is forbidden.
+ */
+export type CollapsibleRootUncontrolledProps = CollapsibleRootBaseProps & {
+    /**
+     * Initial open state on first render. The component owns the value
+     * thereafter.
+     * @default false
+     */
+    defaultOpen?: boolean;
+    /** Forbidden in uncontrolled mode — use `defaultOpen` instead. */
+    open?: never;
+    /** Called with the new open state on every toggle. Optional in
+     * uncontrolled mode (Collapsible fires it in both modes). */
+    onOpenChange?: (open: boolean) => void;
+};
+/**
+ * Controlled variant of {@link CollapsibleRootProps}: the parent owns the
+ * open value. Pass `open` and `onOpenChange` together; `defaultOpen` is
+ * forbidden.
+ */
+export type CollapsibleRootControlledProps = CollapsibleRootBaseProps & {
+    /** The controlled open state. Must be kept in sync by the parent via
+     * `onOpenChange`. */
+    open: boolean;
+    /** Called with the requested open state on every toggle. Required in
+     * controlled mode. */
+    onOpenChange: (open: boolean) => void;
+    /** Forbidden in controlled mode — use `open` instead. */
+    defaultOpen?: never;
+};
+/**
+ * Props for {@link CollapsibleRoot | `Collapsible.Root`}.
+ *
+ * Resolves to either {@link CollapsibleRootUncontrolledProps} or
+ * {@link CollapsibleRootControlledProps} — only one shape is accepted by
+ * TypeScript at a time.
+ */
+export type CollapsibleRootProps = CollapsibleRootUncontrolledProps | CollapsibleRootControlledProps;
+/**
+ * Props for {@link CollapsibleTrigger | `Collapsible.Trigger`}, the button
+ * that toggles the panel.
+ *
+ * Generic over the rendered element type so `asChild` consumers can type
+ * the forwarded `ref` (e.g. `Collapsible.Trigger<HTMLAnchorElement>`).
+ */
+export type CollapsibleTriggerProps<T extends HTMLElement = HTMLButtonElement> = Omit<ComponentProps<"button">, "ref"> & {
+    /** Trigger content (label, and optionally a
+     * {@link CollapsibleTriggerIconProps | TriggerIcon}). */
+    children: ReactNode;
+    /**
+     * Render a single consumer-supplied child element instead of the default
+     * `<button>`, merging the Trigger's ARIA, handlers, and ref onto it via
+     * the {@link Slot} pattern. When `asChild` and the Root is `disabled`,
+     * `role="button"` is injected so `aria-disabled` is semantically valid.
+     * @default false
+     */
+    asChild?: boolean;
+    /** Forwarded to the rendered element. Defaults to `HTMLButtonElement`;
+     * when using `asChild`, specify the child's element type (e.g.
+     * `HTMLAnchorElement`). Composed with the library's internal ref. */
+    ref?: Ref<T>;
+};
+/**
+ * Props for {@link CollapsibleContent | `Collapsible.Content`}, the panel
+ * revealed when open.
+ */
+export type CollapsibleContentProps = ComponentProps<"div"> & {
+    /** Panel content. */
+    children: ReactNode;
+    /**
+     * Keep the panel mounted (and in the DOM) even when closed, so open/close
+     * transitions can be CSS-driven. When closed under `forceMount`, the panel
+     * gets `aria-hidden="true"` instead of the `hidden` attribute. Consumers
+     * may override `aria-hidden` explicitly.
+     * @default false
+     */
+    forceMount?: boolean;
+    /**
+     * Show a **clamped preview** of the panel while closed instead of hiding it
+     * entirely — the "collapsed height" / read-more pattern. A `number` is taken
+     * as pixels; a string is used verbatim as a CSS length (e.g. `"4rem"`,
+     * `"20cqi"`). When set:
+     *
+     * - the panel is always mounted and never gets the `hidden` attribute or
+     *   `aria-hidden` (the preview is real, readable content), so `forceMount` is
+     *   implied;
+     * - the value is emitted as the `--primitiv-collapsible-collapsed-height`
+     *   custom property on the panel, which the styling layer clamps the closed
+     *   height to (e.g. `max-block-size`) and anchors a bottom fade-shadow to,
+     *   keyed off `data-state="closed"`.
+     *
+     * Leave unset for the default fully-hidden / grid-collapse behaviour.
+     */
+    collapsedHeight?: number | string;
+};
+/**
+ * Props for {@link CollapsibleTriggerIcon | `Collapsible.TriggerIcon`}, the
+ * `aria-hidden` icon wrapper carrying an open/closed `data-state` hook.
+ */
+export type CollapsibleTriggerIconProps = ComponentProps<"span"> & {
+    /** The icon to render (inline SVG or an icon component). */
+    children: ReactNode;
+};
+/** Value shared through Collapsible context to all sub-components. */
+export type CollapsibleContextValue = {
+    /** Whether the panel is currently open. */
+    open: boolean;
+    /** Whether the widget is disabled. */
+    disabled: boolean;
+    /** Toggle the open state. */
+    toggle: () => void;
+    /** Generated id linking trigger to content. */
+    triggerId: string;
+    /** Generated id of the content panel. */
+    contentId: string;
+};

package/dist/Collapsible/types.js

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

package/dist/Combobox/Combobox.d.ts

@@ -0,0 +1,149 @@
+import { type ReactElement } from "react";
+import type { ComboboxContentProps, ComboboxEmptyProps, ComboboxInputProps, ComboboxItemProps, ComboboxRootProps } from "./types.js";
+/**
+ * The root of a Combobox — owns the open state, the selected value, the live
+ * query and the virtual-focus cursor, and provides {@link ComboboxContextValue}
+ * to its parts.
+ *
+ * **Filtering is consumer-owned.** There is deliberately no `filter` prop: the
+ * root reports keystrokes through
+ * {@link ComboboxRootProps.onQueryChange | `onQueryChange`} and you render the
+ * options you want. That keeps async loading, fuzzy matching and sorting where
+ * the data lives.
+ *
+ * **Query versus value.** While the popup is open the input holds whatever the
+ * user typed; committing a choice or pressing Escape resets the text from the
+ * selected value, so the field never sits showing a half-typed query that is
+ * not the value.
+ *
+ * **Virtual focus, not a roving tabstop.** DOM focus never leaves the input.
+ * The cursor is published as `aria-activedescendant` on the input and
+ * `data-highlighted` on the item, which is what lets the input keep focus while
+ * driving the list.
+ *
+ * @extends HTMLDivElement
+ */
+export declare function ComboboxRoot({ asChild, defaultOpen, open: openProp, onOpenChange, defaultValue, value: valueProp, onQueryChange, onValueChange, children, ...rest }: ComboboxRootProps): ReactElement;
+export declare namespace ComboboxRoot {
+    var displayName: string;
+}
+/**
+ * The editable text field. Carries `role="combobox"`, `aria-expanded`,
+ * `aria-controls`, `aria-autocomplete="list"` and — once the user asks for a
+ * cursor — `aria-activedescendant`, per the ARIA 1.2 combobox pattern.
+ *
+ * Owns the whole keyboard model: ArrowDown/ArrowUp move the cursor (seeding the
+ * first/last item when there is none), Home/End jump to the ends, Enter commits
+ * the cursor item, and Escape closes and restores the committed label.
+ *
+ * @extends HTMLInputElement
+ */
+export declare function ComboboxInput({ asChild, onChange, onKeyDown, ...rest }: ComboboxInputProps): ReactElement;
+export declare namespace ComboboxInput {
+    var displayName: string;
+}
+/**
+ * The popup listbox. **Unmounted while closed**, so a closed combobox has no
+ * list in the accessibility tree at all — not a hidden one.
+ *
+ * Rendered as a `popover="auto"` element and promoted with `showPopover()` on
+ * open, which buys two things no amount of CSS can: the **top layer**, so nothing
+ * on the page can paint over the panel, and the browser's own **light dismiss**,
+ * so clicking outside closes it. There is deliberately no hand-rolled
+ * pointerdown-outside listener — the browser already does that detection, and it
+ * reports the result back as a `toggle` event, which is the only way React hears
+ * about a close it did not initiate. Same construction as `Select.Content`.
+ *
+ * A light dismiss runs the full {@link ComboboxContextValue.dismiss | `dismiss`},
+ * not just a close, so clicking away and pressing Escape leave the field in the
+ * same state rather than one of them stranding a half-typed query on screen.
+ *
+ * @extends HTMLDivElement
+ */
+export declare function ComboboxContent({ asChild, children, ref, ...rest }: ComboboxContentProps): ReactElement | null;
+export declare namespace ComboboxContent {
+    var displayName: string;
+}
+/**
+ * One selectable option in the popup listbox. Renders `role="option"` with
+ * `aria-selected`, plus `data-highlighted` while the cursor sits on it.
+ *
+ * Registers itself with the root so the arrow keys know the DOM order and Enter
+ * resolves the same label a click would.
+ *
+ * @extends HTMLDivElement
+ */
+export declare function ComboboxItem({ asChild, value: itemValue, children, onClick, ref, ...rest }: ComboboxItemProps): ReactElement;
+export declare namespace ComboboxItem {
+    var displayName: string;
+}
+/**
+ * The no-results message shown inside the popup while the filtered list is
+ * empty. `role="presentation"`, so it is never announced as an option and the
+ * cursor has nothing to land on — the panel simply keeps its height while the
+ * user carries on typing. Rendering it is your call, since filtering is
+ * consumer-owned.
+ *
+ * @extends HTMLDivElement
+ */
+export declare function ComboboxEmpty({ asChild, children, ...rest }: ComboboxEmptyProps): ReactElement;
+export declare namespace ComboboxEmpty {
+    var displayName: string;
+}
+/**
+ * The shape of the exported `Combobox` value — callable as
+ * {@link ComboboxRoot | `Combobox.Root`} and carrying its sub-components as
+ * static properties.
+ */
+export type TComboboxCompound = typeof ComboboxRoot & {
+    Root: typeof ComboboxRoot;
+    Input: typeof ComboboxInput;
+    Content: typeof ComboboxContent;
+    Item: typeof ComboboxItem;
+    Empty: typeof ComboboxEmpty;
+};
+/**
+ * Headless, accessible **Combobox** — an editable text field with a filtered
+ * popup listbox, implementing the
+ * {@link https://www.w3.org/WAI/ARIA/apg/patterns/combobox/ | WAI-ARIA APG combobox pattern}.
+ *
+ * `Combobox` is both callable (an alias of {@link ComboboxRoot | `Combobox.Root`})
+ * and carries its sub-components as static properties.
+ *
+ * - {@link ComboboxRoot | `Combobox.Root`} — state owner and context provider.
+ * - {@link ComboboxInput | `Combobox.Input`} — the editable field and the whole
+ *   keyboard model.
+ * - {@link ComboboxContent | `Combobox.Content`} — the popup listbox.
+ * - {@link ComboboxItem | `Combobox.Item`} — one selectable option.
+ * - {@link ComboboxEmpty | `Combobox.Empty`} — the no-results message.
+ *
+ * v1 is **single-select with consumer-owned filtering**. Multi-select, async
+ * option loading and virtualization are deliberately out of scope.
+ *
+ * @example Filtering is yours to do
+ * ```tsx
+ * import { Combobox } from "@primitiv-ui/react";
+ *
+ * const [query, setQuery] = useState("");
+ * const matches = FRAMEWORKS.filter((f) =>
+ *   f.label.toLowerCase().includes(query.toLowerCase()),
+ * );
+ *
+ * <Combobox.Root onQueryChange={setQuery} onValueChange={setFramework}>
+ *   <Combobox.Input aria-label="Framework" />
+ *   <Combobox.Content aria-label="Frameworks">
+ *     {matches.map((f) => (
+ *       <Combobox.Item key={f.value} value={f.value}>
+ *         {f.label}
+ *       </Combobox.Item>
+ *     ))}
+ *     {matches.length === 0 && <Combobox.Empty>No matches</Combobox.Empty>}
+ *   </Combobox.Content>
+ * </Combobox.Root>;
+ * ```
+ *
+ * @see {@link ComboboxRoot} for the state model and the query/value split.
+ * @see {@link ComboboxInput} for the keyboard model and ARIA wiring.
+ */
+declare const ComboboxCompound: TComboboxCompound;
+export { ComboboxCompound as Combobox };