@primitiv-ui/react 0.1.38 → 0.1.39

package/src/AccessibleIcon/AccessibleIcon.tsx

@@ -1,67 +0,0 @@
-import { Children, cloneElement, ReactElement } from "react";
-import { VisuallyHidden } from "../VisuallyHidden/index.ts";
-import { AccessibleIconProps } from "./types";
-
-type DecorativeIconProps = { "aria-hidden": string; focusable: string };
-
-/**
- * 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,
-}: AccessibleIconProps): ReactElement {
-  const icon = Children.only(children) as ReactElement<DecorativeIconProps>;
-
-  return (
-    <>
-      {cloneElement(icon, { "aria-hidden": "true", focusable: "false" })}
-      <VisuallyHidden>{label}</VisuallyHidden>
-    </>
-  );
-}
-
-/** @internal */
-AccessibleIcon.displayName = "AccessibleIcon";

package/src/AccessibleIcon/README.md

@@ -1,42 +0,0 @@
-# AccessibleIcon
-
-Gives an icon-only control an accessible name, following the
-[icon accessibility guidance](https://www.sarasoueidan.com/blog/accessible-icon-buttons/).
-
-```tsx
-import { AccessibleIcon } from "@primitiv-ui/react";
-
-<button>
-  <AccessibleIcon label="Close dialog">
-    <CloseIcon />
-  </AccessibleIcon>
-</button>;
-```
-
-## Props
-
-| Prop       | Type           | Default | Notes                                                          |
-| ---------- | -------------- | ------- | -------------------------------------------------------------- |
-| `label`    | `string`       | —       | Text announced as the icon's accessible name (**required**)    |
-| `children` | `ReactElement` | —       | A single icon element, e.g. an `<svg>` (**required**)          |
-
-## What it does
-
-`AccessibleIcon` takes a single icon element and:
-
-- clones it with `aria-hidden="true"`, removing the purely decorative
-  graphic from the accessibility tree;
-- clones it with `focusable="false"`, so legacy browsers do not place
-  the `<svg>` in the tab order;
-- renders the `label` text alongside it inside a `VisuallyHidden` span.
-
-Place it inside an interactive element (a `<button>`, an `<a>`, etc.) —
-the visually hidden label becomes that element's accessible name, so a
-screen reader announces "Close dialog, button" rather than nothing.
-
-The icon stays the only thing visible on screen.
-
-## Single child only
-
-`children` must be exactly one element. Passing zero, multiple, or a
-plain string throws — wrap the glyph in a single `<svg>` or component.

package/src/AccessibleIcon/__tests__/AccessibleIcon.test.tsx

@@ -1,52 +0,0 @@
-import { AccessibleIcon } from "../index.ts";
-import { render, screen } from "@testing-library/react";
-
-describe("AccessibleIcon component", () => {
-  it("should mark the icon child as aria-hidden", () => {
-    // Arrange
-    render(
-      <AccessibleIcon label="Search">
-        <svg data-testid="icon" />
-      </AccessibleIcon>,
-    );
-
-    // Assert
-    expect(screen.getByTestId("icon")).toHaveAttribute(
-      "aria-hidden",
-      "true",
-    );
-  });
-
-  it("should mark the icon child as non-focusable", () => {
-    // Arrange
-    render(
-      <AccessibleIcon label="Search">
-        <svg data-testid="icon" />
-      </AccessibleIcon>,
-    );
-
-    // Assert
-    expect(screen.getByTestId("icon")).toHaveAttribute(
-      "focusable",
-      "false",
-    );
-  });
-
-  it("should render the label in a visually hidden span", () => {
-    // Arrange
-    render(
-      <AccessibleIcon label="Search">
-        <svg data-testid="icon" />
-      </AccessibleIcon>,
-    );
-
-    // Assert
-    const label = screen.getByText("Search");
-    expect(label).toHaveStyle({ position: "absolute", overflow: "hidden" });
-  });
-
-  it('sets displayName to "AccessibleIcon" for React DevTools and stack traces', () => {
-    // Assert — an empty displayName would render it as an anonymous component.
-    expect(AccessibleIcon.displayName).toBe("AccessibleIcon");
-  });
-});

package/src/AccessibleIcon/index.ts

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

package/src/AccessibleIcon/types.ts

@@ -1,25 +0,0 @@
-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/src/Accordion/Accordion.tsx

@@ -1,455 +0,0 @@
-import { Ref, useEffect } from "react";
-import type { ReactElement } from "react";
-
-import { useDirection } from "../DirectionProvider/index.ts";
-import { Slot } from "../Slot/index.ts";
-
-import type {
-  AccordionRootProps,
-  AccordionItemProps,
-  AccordionTriggerProps,
-  AccordionHeaderProps,
-  AccordionContentProps,
-  AccordionTriggerIconProps,
-} from "./types";
-
-import type { HeadingTag } from "../types";
-
-import { AccordionContext, AccordionItemContext } from "./AccordionContext";
-import {
-  useAccordionContext,
-  useAccordionHeaderContext,
-  useAccordionItem,
-  useAccordionItemContext,
-  useAccordionRoot,
-} from "./hooks/index.ts";
-import { useAccordionTrigger } from "./hooks/useAccordionTrigger";
-
-/**
- * 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 function AccordionRoot({
-  children,
-  multiple = false,
-  defaultValue,
-  value: controlledValue,
-  onValueChange,
-  orientation = "vertical",
-  dir,
-  ...rest
-}: AccordionRootProps): ReactElement {
-  const resolvedDir = dir ?? useDirection();
-  const { contextValue } = useAccordionRoot(
-    controlledValue,
-    defaultValue,
-    multiple,
-    onValueChange,
-    orientation,
-    resolvedDir,
-  );
-
-  return (
-    <AccordionContext.Provider value={contextValue}>
-      <div data-orientation={orientation} dir={resolvedDir} {...rest}>
-        {children}
-      </div>
-    </AccordionContext.Provider>
-  );
-}
-
-/** @internal */
-// Stryker disable next-line StringLiteral: overwritten by the compound alias — an equivalent mutant.
-AccordionRoot.displayName = "AccordionRoot";
-
-/**
- * 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 function AccordionItem({
-  children,
-  value,
-  ...rest
-}: AccordionItemProps): ReactElement {
-  const { contextValue } = useAccordionItem(value);
-
-  return (
-    <AccordionItemContext.Provider value={contextValue}>
-      <div {...rest}>{children}</div>
-    </AccordionItemContext.Provider>
-  );
-}
-
-/** @internal */
-AccordionItem.displayName = "AccordionItem";
-
-/**
- * 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 function AccordionHeader({
-  children,
-  level = 3,
-  ...rest
-}: AccordionHeaderProps): ReactElement {
-  useAccordionHeaderContext();
-  const HeadingTag: HeadingTag = `h${level}`;
-
-  return <HeadingTag {...rest}>{children}</HeadingTag>;
-}
-
-/** @internal */
-AccordionHeader.displayName = "AccordionHeader";
-
-/**
- * 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 function AccordionTrigger<T extends HTMLElement = HTMLButtonElement>({
-  ref,
-  children,
-  onClick,
-  disabled = false,
-  asChild = false,
-  ...rest
-}: AccordionTriggerProps<T>): ReactElement {
-  // Cast the external ref to match the internal button ref's element type —
-  // RefObject<T> is invariant in React's types, but at runtime the callback
-  // receives whatever DOM element is actually rendered (button or asChild).
-  const { triggerProps } = useAccordionTrigger({
-    ref: ref as Ref<HTMLButtonElement>,
-    onClick,
-    disabled,
-    asChild,
-    ...rest,
-  });
-
-  if (asChild) {
-    return <Slot {...triggerProps}>{children}</Slot>;
-  }
-
-  return (
-    <button type="button" {...triggerProps}>
-      {children}
-    </button>
-  );
-}
-
-/** @internal */
-AccordionTrigger.displayName = "AccordionTrigger";
-
-/**
- * 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 function AccordionContent({
-  children,
-  forceMount = false,
-  ...rest
-}: AccordionContentProps): ReactElement {
-  const { panelId, buttonId, itemId, isExpanded } = useAccordionItemContext();
-  const { registerPanel, unregisterPanel } = useAccordionContext();
-
-  useEffect(
-    () => {
-      registerPanel(itemId);
-      return () => unregisterPanel(itemId);
-    },
-    // `registerPanel`/`unregisterPanel` are stable, and `itemId` is effectively
-    // immutable: changing an item's value produces a phantom-key validation
-    // throw (the collection keeps unmounted keys), so it is never a supported
-    // runtime transition. Emptying the deps is therefore equivalent.
-    // Stryker disable next-line ArrayDeclaration: equivalent — stable/immutable dependencies.
-    [itemId, registerPanel, unregisterPanel],
-  );
-
-  return (
-    <div
-      id={panelId}
-      aria-labelledby={buttonId}
-      role="region"
-      hidden={forceMount ? undefined : !isExpanded}
-      aria-hidden={forceMount && !isExpanded ? true : undefined}
-      data-state={isExpanded ? "open" : "closed"}
-      {...rest}
-    >
-      {children}
-    </div>
-  );
-}
-
-/** @internal */
-AccordionContent.displayName = "AccordionContent";
-
-/**
- * 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 function AccordionTriggerIcon({
-  children,
-  ...rest
-}: AccordionTriggerIconProps): ReactElement {
-  const { isExpanded } = useAccordionItemContext();
-
-  return (
-    <span
-      {...rest}
-      aria-hidden="true"
-      data-state={isExpanded ? "open" : "closed"}
-    >
-      {children}
-    </span>
-  );
-}
-
-/** @internal */
-AccordionTriggerIcon.displayName = "AccordionTriggerIcon";
-
-/** @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.
- */
-const AccordionCompound: AccordionCompound = Object.assign(AccordionRoot, {
-  Root: AccordionRoot,
-  Item: AccordionItem,
-  Header: AccordionHeader,
-  Trigger: AccordionTrigger,
-  Content: AccordionContent,
-  TriggerIcon: AccordionTriggerIcon,
-});
-
-AccordionCompound.displayName = "Accordion";
-
-export { AccordionCompound as Accordion };

package/src/Accordion/AccordionContext.ts

@@ -1,12 +0,0 @@
-import { createStrictContext } from "../utils/index.ts";
-import { AccordionContextValue, AccordionItemContextValue } from "./types";
-
-export const [AccordionContext, useAccordionContext] =
-  createStrictContext<AccordionContextValue>(
-    "AccordionItem must be used within AccordionRoot",
-  );
-
-export const [AccordionItemContext, useAccordionItemContext] =
-  createStrictContext<AccordionItemContextValue>(
-    "Component must be used within AccordionItem",
-  );