@primitiv-ui/react 0.1.38 → 0.1.40

package/src/Tree/types.ts

@@ -1,298 +0,0 @@
-import type { ComponentProps, ReactNode } from "react";
-
-/** Mode-independent props shared by every `Tree.Root` variant. */
-export type TreeRootBaseProps = ComponentProps<"div"> & {
-  children: ReactNode;
-};
-
-/** Uncontrolled expansion — initial expanded branches via `defaultExpandedValues`. */
-export type TreeRootUncontrolledExpansionProps = {
-  /** Branch values expanded on first render when uncontrolled. Omit for a
-   * fully-collapsed tree. */
-  defaultExpandedValues?: string[];
-  expandedValues?: never;
-  /** Called with the full set of expanded branch values whenever a branch
-   * is toggled. Optional in uncontrolled mode. */
-  onExpandedChange?: (values: string[]) => void;
-};
-
-/** Controlled expansion — the expanded set is owned by the consumer. */
-export type TreeRootControlledExpansionProps = {
-  defaultExpandedValues?: never;
-  /** The set of expanded branch values, owned by the consumer. Keep in
-   * sync via `onExpandedChange`. */
-  expandedValues: string[];
-  /** Called with the full set of expanded branch values the user requested
-   * on each toggle. Required in controlled mode. */
-  onExpandedChange: (values: string[]) => void;
-};
-
-/** Single-selection mode, uncontrolled — initial value via `defaultSelectedValue`. */
-export type TreeRootSingleUncontrolledSelectionProps = {
-  /** At most one node may be selected; see {@link SelectionMode}.
-   * @default "single" */
-  selectionMode?: "single";
-  /** The value selected on first render when uncontrolled. `null` selects
-   * nothing. */
-  defaultSelectedValue?: string | null;
-  selectedValue?: never;
-  /** Called with the newly-selected value (or `null` when cleared) on each
-   * user selection. Optional in uncontrolled mode. */
-  onSelectedValueChange?: (value: string | null) => void;
-  defaultSelectedValues?: never;
-  selectedValues?: never;
-  onSelectedValuesChange?: never;
-};
-
-/** Single-selection mode, controlled — the selected value is owned by the consumer. */
-export type TreeRootSingleControlledSelectionProps = {
-  /** At most one node may be selected; see {@link SelectionMode}.
-   * @default "single" */
-  selectionMode?: "single";
-  defaultSelectedValue?: never;
-  /** The selected value, owned by the consumer (or `null` for no
-   * selection). Keep it in sync via `onSelectedValueChange`. */
-  selectedValue: string | null;
-  /** Called with the value the user requested to select (or `null` when
-   * cleared). Required in controlled mode. */
-  onSelectedValueChange: (value: string | null) => void;
-  defaultSelectedValues?: never;
-  selectedValues?: never;
-  onSelectedValuesChange?: never;
-};
-
-/** Multiple-selection mode, uncontrolled — initial values via `defaultSelectedValues`. */
-export type TreeRootMultipleUncontrolledSelectionProps = {
-  /** Many nodes may be selected via `Ctrl`/`Cmd`+click and `Shift`+click
-   * ranges; see {@link SelectionMode}. */
-  selectionMode: "multiple";
-  /** The values selected on first render when uncontrolled. */
-  defaultSelectedValues?: string[];
-  selectedValues?: never;
-  /** Called with the full selected set (in selection order) on each
-   * change. Optional in uncontrolled mode. */
-  onSelectedValuesChange?: (values: string[]) => void;
-  defaultSelectedValue?: never;
-  selectedValue?: never;
-  onSelectedValueChange?: never;
-};
-
-/** Multiple-selection mode, controlled — the selected values are owned by the consumer. */
-export type TreeRootMultipleControlledSelectionProps = {
-  /** Many nodes may be selected via `Ctrl`/`Cmd`+click and `Shift`+click
-   * ranges; see {@link SelectionMode}. */
-  selectionMode: "multiple";
-  defaultSelectedValues?: never;
-  /** The selected values, owned by the consumer. Keep in sync via
-   * `onSelectedValuesChange`. */
-  selectedValues: string[];
-  /** Called with the full selected set (in selection order) the user
-   * requested. Required in controlled mode. */
-  onSelectedValuesChange: (values: string[]) => void;
-  defaultSelectedValue?: never;
-  selectedValue?: never;
-  onSelectedValueChange?: never;
-};
-
-/**
- * Props for `Tree.Root`. Combines the shared {@link TreeRootBaseProps} with
- * one expansion arm (controlled / uncontrolled) and one selection arm
- * (single / multiple, controlled / uncontrolled), so the relevant
- * `value` / `defaultValue` / `onChange` shape is enforced per mode.
- */
-export type TreeRootProps = TreeRootBaseProps &
-  (TreeRootUncontrolledExpansionProps | TreeRootControlledExpansionProps) &
-  (
-    | TreeRootSingleUncontrolledSelectionProps
-    | TreeRootSingleControlledSelectionProps
-    | TreeRootMultipleUncontrolledSelectionProps
-    | TreeRootMultipleControlledSelectionProps
-  );
-
-/** Props for `Tree.Item` — a selectable, focusable leaf treeitem. */
-export type TreeItemProps = ComponentProps<"div"> & {
-  /** Stable identifier for this item, unique within the tree. Links the
-   * item to selection / expansion state and to its
-   * {@link TreePathSegment} in a resolved path. */
-  value: string;
-  /**
-   * Optional display label for this item. Stored alongside the value
-   * in the tree's node registry so {@link useTreePath} and
-   * `Tree.SelectionPath` can surface it without an external lookup.
-   * Has no effect on what `Tree.Item` renders.
-   */
-  label?: string;
-  /** Disable selection and remove the item from roving navigation
-   * (`Home`/`End` still skip past it to a non-disabled neighbour).
-   * @default false */
-  disabled?: boolean;
-  /** Render the item as the supplied child element instead of `<div>`,
-   * merging the treeitem behaviour onto it via the {@link Slot} pattern.
-   * The child must accept a `ref`.
-   * @default false */
-  asChild?: boolean;
-  children: ReactNode;
-};
-
-/** Props for `Tree.Branch` — an expandable treeitem with nested children. */
-export type TreeBranchProps = Omit<ComponentProps<"div">, "ref"> & {
-  /** Stable identifier for this branch, unique within the tree. Also seeds
-   * the `parentValue` of its {@link TreeBranchContent}'s children and the
-   * derived `aria-labelledby` control id. */
-  value: string;
-  /**
-   * Optional display label for this branch. Stored alongside the value
-   * in the tree's node registry so {@link useTreePath} and
-   * `Tree.SelectionPath` can surface it without an external lookup.
-   * Has no effect on what `Tree.Branch` renders.
-   */
-  label?: string;
-  /**
-   * Disable selection, expansion-toggling, and roving navigation for
-   * this branch. The branch and its current content remain rendered.
-   * @default false
-   */
-  disabled?: boolean;
-  children: ReactNode;
-};
-
-/** Props for `Tree.BranchControl` — the branch's selectable, toggling control row. */
-export type TreeBranchControlProps = ComponentProps<"div"> & {
-  /** Render the control as the supplied child element instead of `<div>`,
-   * merging its props (including the `aria-labelledby` id) onto the child
-   * via the {@link Slot} pattern. The child must accept a `ref`.
-   * @default false */
-  asChild?: boolean;
-  children: ReactNode;
-};
-
-/** Props for `Tree.BranchContent` — the collapsible group of a branch's child nodes. */
-export type TreeBranchContentProps = ComponentProps<"div"> & {
-  children: ReactNode;
-  /**
-   * Keep the content mounted while the branch is collapsed so CSS can
-   * animate it in and out. When collapsed it is hidden from assistive
-   * technology with `aria-hidden` and carries `data-state="closed"`.
-   * @default false
-   */
-  forceMount?: boolean;
-};
-
-/** Props for `Tree.BranchIndicator` — the expand/collapse affordance. */
-export type TreeBranchIndicatorProps = ComponentProps<"span"> & {
-  /** Render as the supplied child element instead of `<span>`, merging
-   * `aria-hidden` and `data-state` onto it via the {@link Slot} pattern
-   * (e.g. an icon that rotates on `data-state="open"`).
-   * @default false */
-  asChild?: boolean;
-};
-
-/** Arguments passed to the `Tree.SelectionPath` render-prop form. */
-export type TreeSelectionPathRenderProps = {
-  /** One root-to-leaf chain per currently-selected value, in selection order. */
-  paths: TreePathSegment[][];
-};
-
-/**
- * Props for `Tree.SelectionPath` — a breadcrumb of the selected node's
- * root-to-leaf ancestry, with an optional render-prop for custom layout.
- */
-export type TreeSelectionPathProps = Omit<ComponentProps<"div">, "children"> & {
-  /**
-   * Either standard React children (ignored — the subcomponent does its
-   * own rendering) or a render-prop receiving the resolved selection
-   * paths so consumers can lay out custom markup.
-   */
-  children?: ReactNode | ((args: TreeSelectionPathRenderProps) => ReactNode);
-  /**
-   * Node passed to each `Breadcrumb.Separator` in the default rendering.
-   * Defaults to Breadcrumb's built-in `"/"` glyph.
-   */
-  separator?: ReactNode;
-};
-
-/** Per-level context — the nesting depth and enclosing branch value, shared down each subtree. */
-export type TreeLevelContextValue = {
-  /** Zero-based nesting depth — `0` for items directly inside `Tree.Root`. */
-  depth: number;
-  /** The value of the enclosing branch, or `null` at the tree root. */
-  parentValue: string | null;
-};
-
-/** Registry entry for one tree node — its value, element, and structural metadata. */
-export type TreeNodeMeta = {
-  value: string;
-  element: HTMLElement;
-  isBranch: boolean;
-  disabled: boolean;
-  depth: number;
-  parentValue: string | null;
-  label: string | null;
-};
-
-/**
- * One segment of an ancestor chain returned by {@link useTreePath} or
- * `TreeContextValue.getPath`. The array is ordered **root → leaf**, so
- * the last segment is the queried item itself.
- */
-export type TreePathSegment = {
-  value: string;
-  label: string | null;
-  isBranch: boolean;
-  disabled: boolean;
-  depth: number;
-};
-
-/** Whether the tree allows one selected node (`"single"`) or many (`"multiple"`). */
-export type SelectionMode = "single" | "multiple";
-
-/** Keyboard/pointer modifiers that influence a selection gesture. */
-export type TreeSelectModifiers = {
-  meta: boolean;
-  ctrl: boolean;
-  shift: boolean;
-};
-
-/**
- * Context shared from `Tree.Root` to every descendant — selection and
- * expansion state, the node registry, roving-tabindex bookkeeping, and the
- * path resolver.
- */
-export type TreeContextValue = {
-  /** Stable id shared across the tree, used to derive ARIA wiring ids. */
-  rootId: string;
-  selectionMode: SelectionMode;
-  isExpanded: (value: string) => boolean;
-  toggleExpanded: (value: string) => void;
-  isSelected: (value: string) => boolean;
-  select: (value: string, modifiers?: TreeSelectModifiers) => void;
-  registerNode: (value: string, meta: TreeNodeMeta | null) => void;
-  getVisibleOrder: () => string[];
-  isNodeDisabled: (value: string) => boolean;
-  /** Value of the treeitem currently holding the single roving tabstop. */
-  tabStop: string | null;
-  setActiveValue: (value: string) => void;
-  focusItem: (value: string) => void;
-  /**
-   * Returns the root-to-leaf chain of segments for the given value, or
-   * an empty array if the value has never been registered. Walks the
-   * persistent node registry so paths remain resolvable even when an
-   * ancestor branch has collapsed and its descendants unmounted.
-   */
-  getPath: (value: string) => TreePathSegment[];
-  /**
-   * The currently-selected values in selection order. Mirrors
-   * `selectedValues` in multiple mode and `[selectedValue]` (or `[]`)
-   * in single mode.
-   */
-  selectedOrder: readonly string[];
-};
-
-/** Context a branch shares with its own control and content — its value, expanded/disabled state, and control id. */
-export type TreeItemContextValue = {
-  value: string;
-  expanded: boolean;
-  disabled: boolean;
-  /** DOM `id` of the branch's `BranchControl`, for `aria-labelledby`. */
-  controlId: string;
-};

package/src/Tree/utils.ts

@@ -1,101 +0,0 @@
-import { Children, Fragment, isValidElement } from "react";
-import type { ReactElement, ReactNode } from "react";
-
-import { TreeBranchControl, TreeBranchContent } from "./Tree";
-
-/**
- * The property a component sets on itself to declare which `Tree` part it
- * stands in for.
- *
- * `Tree.Branch` finds its control and content by inspecting its children before
- * rendering them, so it sees the component the consumer wrote — not what that
- * component renders. A styled layer wraps every part in its own component to
- * attach classes (that is exactly what `primitiv add tree` copies), and without
- * a marker those wrappers are unrecognisable, making `Tree` the one primitive
- * in the library that cannot be wrapped at all.
- *
- * Set it on the wrapper and it partitions like the part it renders:
- *
- * ```tsx
- * function StyledBranchControl(props: TreeBranchControlProps) {
- *   return <Tree.BranchControl {...props} className="row" />;
- * }
- * StyledBranchControl[TREE_PART] = "branch-control";
- * ```
- */
-export const TREE_PART: "__primitivTreePart" = "__primitivTreePart";
-
-/** The part names {@link TREE_PART} accepts. */
-export type TreePartName = "branch-control" | "branch-content";
-
-/** Read a component's {@link TREE_PART} marker, if it declares one. */
-function treePartOf(type: unknown): TreePartName | undefined {
-  return (type as Record<string, TreePartName | undefined> | null)?.[TREE_PART];
-}
-
-/**
- * Whether `node` is a `Tree.BranchControl` element — either the part itself, or
- * a component that marks itself as standing in for it (see {@link TREE_PART}).
- */
-export function isBranchControlElement(node: ReactNode): node is ReactElement {
-  return (
-    isValidElement(node) &&
-    (node.type === TreeBranchControl || treePartOf(node.type) === "branch-control")
-  );
-}
-
-/**
- * Whether `node` is a `Tree.BranchContent` element — either the part itself, or
- * a component that marks itself as standing in for it (see {@link TREE_PART}).
- */
-export function isBranchContentElement(node: ReactNode): node is ReactElement {
-  return (
-    isValidElement(node) &&
-    (node.type === TreeBranchContent || treePartOf(node.type) === "branch-content")
-  );
-}
-
-/**
- * Splits a `Tree.Branch`'s children into its single `<Tree.BranchControl>`
- * (the clickable row) and its optional `<Tree.BranchContent>` (the nested
- * group). Both are matched however deeply they are wrapped in fragments,
- * since `Children.toArray` does not descend into fragments — so
- * `{open && <BranchContent/>}` is partitioned the same as a bare element.
- */
-export function partitionBranchChildren(children: ReactNode): {
-  control: ReactElement;
-  content: ReactElement | null;
-} {
-  let control: ReactElement | null = null;
-  let content: ReactElement | null = null;
-
-  const visit = (nodes: ReactNode): void => {
-    for (const child of Children.toArray(nodes)) {
-      if (isBranchControlElement(child)) {
-        if (control !== null) {
-          throw new Error(
-            "A Tree.Branch may contain at most one <Tree.BranchControl>.",
-          );
-        }
-        control = child;
-      } else if (isBranchContentElement(child)) {
-        if (content !== null) {
-          throw new Error(
-            "A Tree.Branch may contain at most one <Tree.BranchContent>.",
-          );
-        }
-        content = child;
-      } else if (isValidElement(child) && child.type === Fragment) {
-        visit((child.props as { children?: ReactNode }).children);
-      }
-    }
-  };
-
-  visit(children);
-
-  if (control === null) {
-    throw new Error("A Tree.Branch must contain a <Tree.BranchControl>.");
-  }
-
-  return { control, content };
-}

package/src/VisuallyHidden/README.md

@@ -1,58 +0,0 @@
-# VisuallyHidden
-
-Visually hides its children while keeping them in the accessibility tree,
-implementing the standard
-[screen-reader-only pattern](https://www.w3.org/WAI/WCAG21/Techniques/css/C7).
-
-```tsx
-import { VisuallyHidden } from "@primitiv-ui/react";
-
-<button>
-  <SearchIcon aria-hidden="true" />
-  <VisuallyHidden>Search</VisuallyHidden>
-</button>;
-```
-
-## Props
-
-| Prop        | Type                     | Default | Notes                                              |
-| ----------- | ------------------------ | ------- | -------------------------------------------------- |
-| `asChild`   | `boolean`                | `false` | Render the consumer's element instead of a `<span>` |
-| `style`     | `CSSProperties`          | —       | Merged on top of the clip styles                  |
-| `className` | `string`                 | —       | Applied directly to the rendered element          |
-| `...rest`   | `ComponentProps<"span">` | —       | All other `<span>` props, including `aria-*`       |
-
-## Functional styles
-
-Unlike other `@primitiv-ui/react` components, `VisuallyHidden` ships inline
-styles — the clip rectangle that removes content from the visual layout
-*is* the component's behaviour, not decoration:
-
-```css
-position: absolute;
-width: 1px;
-height: 1px;
-padding: 0;
-margin: -1px;
-overflow: hidden;
-clip: rect(0 0 0 0);
-clip-path: inset(50%);
-white-space: nowrap;
-border-width: 0;
-```
-
-A consumer `style` is merged on top, so any individual property can still
-be overridden.
-
-## asChild
-
-Pass `asChild` to hide the consumer's own element instead of a `<span>` —
-useful when the hidden content needs specific semantics:
-
-```tsx
-<VisuallyHidden asChild>
-  <h2>Section heading</h2>
-</VisuallyHidden>
-```
-
-The clip styles are merged onto the child element via the `Slot` utility.

package/src/VisuallyHidden/VisuallyHidden.tsx

@@ -1,94 +0,0 @@
-import { CSSProperties } from "react";
-import type { ReactElement } from "react";
-import { Slot } from "../Slot/index.ts";
-import { VisuallyHiddenProps } from "./types";
-
-const visuallyHiddenStyle: CSSProperties = {
-  position: "absolute",
-  width: 1,
-  height: 1,
-  padding: 0,
-  margin: -1,
-  overflow: "hidden",
-  clip: "rect(0 0 0 0)",
-  clipPath: "inset(50%)",
-  whiteSpace: "nowrap",
-  borderWidth: 0,
-};
-
-/**
- * Visually hides its children while keeping them in the accessibility tree.
- *
- * Renders a `<span>` carrying the canonical screen-reader-only clip styles
- * (WCAG 2.1 Technique C7): the content is removed from the visual layout but
- * still announced by assistive technology. Use it for text that gives a control
- * or region an accessible name without showing on screen.
- *
- * **Functional styles.** Unlike other `@primitiv-ui/react` components, the
- * clip styles are applied inline because they *are* the component's behaviour,
- * not decoration:
- *
- * ```css
- * position: absolute;
- * width: 1px; height: 1px;
- * padding: 0; margin: -1px;
- * overflow: hidden;
- * clip: rect(0 0 0 0);
- * clip-path: inset(50%);
- * white-space: nowrap;
- * border-width: 0;
- * ```
- *
- * A consumer `style` prop is merged on top, so any individual property can
- * still be overridden.
- *
- * **`asChild` composition.** Renders the consumer's element instead of a
- * `<span>`, merging the clip styles onto the child via the {@link Slot}
- * utility. Useful when the hidden content needs specific semantics (e.g. a
- * heading or landmark). The child must be a single React element.
- *
- * @extends HTMLSpanElement
- *
- * @example Accessible name for an icon-only button
- * ```tsx
- * <button>
- *   <SearchIcon aria-hidden="true" />
- *   <VisuallyHidden>Search</VisuallyHidden>
- * </button>
- * ```
- *
- * @example Region label hidden from sighted users
- * ```tsx
- * <nav aria-labelledby="nav-label">
- *   <VisuallyHidden id="nav-label">Primary navigation</VisuallyHidden>
- *   ...
- * </nav>
- * ```
- *
- * @example asChild — keep semantic markup hidden
- * ```tsx
- * <VisuallyHidden asChild>
- *   <h2>Section heading</h2>
- * </VisuallyHidden>
- * ```
- */
-export function VisuallyHidden({
-  asChild = false,
-  children,
-  style,
-  ...rest
-}: VisuallyHiddenProps): ReactElement {
-  const rootProps = {
-    ...rest,
-    style: { ...visuallyHiddenStyle, ...style },
-  };
-
-  if (asChild) {
-    return <Slot {...rootProps}>{children}</Slot>;
-  }
-
-  return <span {...rootProps}>{children}</span>;
-}
-
-/** @internal */
-VisuallyHidden.displayName = "VisuallyHidden";

package/src/VisuallyHidden/__tests__/VisuallyHidden.test.tsx

@@ -1,73 +0,0 @@
-import { VisuallyHidden } from "../index.ts";
-import { render, screen } from "@testing-library/react";
-
-describe("VisuallyHidden component", () => {
-  it("should render a span containing its children", () => {
-    // Arrange
-    render(<VisuallyHidden>Loading complete</VisuallyHidden>);
-
-    // Assert
-    const hidden = screen.getByText("Loading complete");
-    expect(hidden.tagName).toBe("SPAN");
-  });
-
-  it("should apply the screen-reader-only clip styles", () => {
-    // Arrange
-    render(<VisuallyHidden>Loading complete</VisuallyHidden>);
-
-    // Assert — the full WCAG C7 clip set; every property matters, so each is
-    // asserted (a missing one lets a mutant blank that value undetected).
-    const hidden = screen.getByText("Loading complete");
-    expect(hidden).toHaveStyle({
-      position: "absolute",
-      width: "1px",
-      height: "1px",
-      padding: "0px",
-      margin: "-1px",
-      overflow: "hidden",
-      whiteSpace: "nowrap",
-      borderWidth: "0px",
-    });
-    // jsdom's computed style doesn't surface clip/clip-path, so assert them on
-    // the inline style directly.
-    // jsdom normalises `rect(0 0 0 0)` to `rect(0px)`.
-    expect(hidden.style.clip).toBe("rect(0px)");
-    expect(hidden.style.clipPath).toBe("inset(50%)");
-  });
-
-  it("should merge a consumer style over the clip styles", () => {
-    // Arrange
-    render(
-      <VisuallyHidden style={{ position: "static", display: "block" }}>
-        Loading complete
-      </VisuallyHidden>,
-    );
-
-    // Assert
-    const hidden = screen.getByText("Loading complete");
-    expect(hidden).toHaveStyle({
-      position: "static",
-      display: "block",
-      whiteSpace: "nowrap",
-    });
-  });
-
-  it("should render the consumer element with asChild, keeping the clip styles", () => {
-    // Arrange
-    render(
-      <VisuallyHidden asChild>
-        <label>Search</label>
-      </VisuallyHidden>,
-    );
-
-    // Assert
-    const hidden = screen.getByText("Search");
-    expect(hidden.tagName).toBe("LABEL");
-    expect(hidden).toHaveStyle({ position: "absolute", overflow: "hidden" });
-  });
-
-  it('sets displayName to "VisuallyHidden" for React DevTools and stack traces', () => {
-    // Assert — an empty displayName would render it as an anonymous component.
-    expect(VisuallyHidden.displayName).toBe("VisuallyHidden");
-  });
-});

package/src/VisuallyHidden/index.ts

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

package/src/VisuallyHidden/types.ts

@@ -1,19 +0,0 @@
-import { ComponentProps, ReactNode } from "react";
-
-/**
- * Props for {@link VisuallyHidden} — all native `<span>` attributes plus
- * the `asChild` escape hatch.
- */
-export type VisuallyHiddenProps = ComponentProps<"span"> & {
-  /**
-   * Renders the child element instead of a native `<span>`, merging the
-   * clip styles onto it via {@link Slot}. Useful when the hidden content
-   * needs specific semantics (e.g. a heading or landmark element). The
-   * child must be a single React element. See the `asChild` example on
-   * {@link VisuallyHidden}.
-   * @default false
-   */
-  asChild?: boolean;
-  /** Content to visually hide. Under `asChild`, becomes the single child element whose clip styles are merged. */
-  children?: ReactNode;
-};

package/src/hooks/index.ts

@@ -1,4 +0,0 @@
-export { useControllableState } from "./useControllableState";
-export { useCollection } from "./useCollection";
-export { useRovingTabindex } from "./useRovingTabindex";
-export { useTypeahead } from "./useTypeahead";