@primitiv-ui/react 0.1.38 → 0.1.39

package/src/Accordion/README.md

@@ -1,202 +0,0 @@
-# Accordion
-
-A compound component implementing the
-[WAI-ARIA Accordion pattern](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/).
-
-```tsx
-import { Accordion } from "@primitiv-ui/react";
-
-<Accordion.Root defaultValue="shipping">
-  <Accordion.Item value="shipping">
-    <Accordion.Header>
-      <Accordion.Trigger>Shipping policy</Accordion.Trigger>
-    </Accordion.Header>
-    <Accordion.Content>Free on orders over £50.</Accordion.Content>
-  </Accordion.Item>
-  <Accordion.Item value="returns">
-    <Accordion.Header>
-      <Accordion.Trigger>Returns</Accordion.Trigger>
-    </Accordion.Header>
-    <Accordion.Content>30-day returns accepted.</Accordion.Content>
-  </Accordion.Item>
-</Accordion.Root>;
-```
-
-## Sub-components
-
-| Export                  | Role           | Notes                                                                   |
-| ----------------------- | -------------- | ----------------------------------------------------------------------- |
-| `Accordion.Root`        | State owner    | Uncontrolled (`defaultValue`) or controlled (`value` + `onValueChange`) |
-| `Accordion.Item`        | Item wrapper   | Owns the trigger–panel pair; optional `value` prop                      |
-| `Accordion.Header`      | Heading        | Configurable level (`h1`–`h6`); defaults to `h3`                        |
-| `Accordion.Trigger`     | Toggle button  | Supports `asChild`, ref forwarding, and `disabled`                      |
-| `Accordion.Content`     | `region` panel | Supports `forceMount` for CSS animation                                 |
-| `Accordion.TriggerIcon` | Icon wrapper   | Injects `aria-hidden` and `data-state` onto a decorative icon           |
-
-## Keyboard interaction
-
-| Key               | Behaviour                                         |
-| ----------------- | ------------------------------------------------- |
-| `Enter` / `Space` | Toggle the focused item                           |
-| `ArrowDown`       | Move focus to next trigger (vertical orientation) |
-| `ArrowUp`         | Move focus to previous trigger (vertical)         |
-| `ArrowRight`      | Move focus to next trigger (horizontal)           |
-| `ArrowLeft`       | Move focus to previous trigger (horizontal)       |
-| `Home`            | Jump to first enabled trigger                     |
-| `End`             | Jump to last enabled trigger                      |
-
-Focus movement **wraps** at the ends. Disabled triggers are excluded from
-arrow-key navigation but remain focusable via `Tab`.
-
-## State modes
-
-- **Uncontrolled** — pass `defaultValue` (or omit to start with all items collapsed).
-- **Controlled** — pass `value` (a `string[]`) and `onValueChange` together.
-
-## Multiple mode
-
-By default only one item can be open at a time — opening a second item
-collapses the first. Pass `multiple` to allow any number of items open
-simultaneously:
-
-```tsx
-<Accordion.Root multiple defaultValue="shipping">
-  ...
-</Accordion.Root>
-```
-
-## Disabled items
-
-Disabled triggers are rendered with `aria-disabled="true"` (not the native
-`disabled` attribute) so they remain focusable for keyboard discovery:
-
-```tsx
-<Accordion.Trigger disabled>Unavailable section</Accordion.Trigger>
-```
-
-## `forceMount` for animations
-
-By default the content panel is hidden with the `hidden` attribute. Pass
-`forceMount` to keep the panel in the DOM and control visibility via CSS:
-
-```tsx
-<Accordion.Content forceMount className="panel">
-  Content that animates in and out.
-</Accordion.Content>
-```
-
-```css
-.panel[data-state="closed"] {
-  display: none; /* or use an animation */
-}
-```
-
-When `forceMount` is active and the panel is closed, `aria-hidden="true"` is
-applied automatically so assistive technology skips the off-screen content.
-It is removed when the panel opens. Consumers can override this by passing
-`aria-hidden` explicitly.
-
-## `role="region"` escape hatch
-
-Each `Accordion.Content` renders with `role="region"`, creating an ARIA
-landmark. This is appropriate for panels whose content benefits from
-landmark navigation, but accordions with many items can produce landmark
-overload in screen readers (JAWS/NVDA expose all landmarks in their landmark
-list).
-
-Opt out on individual panels by passing `role={undefined}`:
-
-```tsx
-<Accordion.Content role={undefined}>
-  Simple prose that doesn't need landmark navigation.
-</Accordion.Content>
-```
-
-## `asChild` composition
-
-`Accordion.Trigger` accepts an `asChild` prop to render any child element
-with full accordion semantics. All ARIA attributes, event handlers, and
-the internal ref are merged onto the child (child handler runs first, then
-the trigger's):
-
-```tsx
-<Accordion.Trigger asChild>
-  <a href="#shipping">Shipping policy</a>
-</Accordion.Trigger>
-```
-
-`Enter` and `Space` are handled in `onKeyDown` so non-button elements (e.g.
-`<a>`) toggle correctly without relying on native click behaviour.
-
-When `asChild` is combined with `disabled`, `role="button"` is injected
-automatically so that `aria-disabled` is semantically valid on non-button
-elements. Without a button role, `aria-disabled` has no defined meaning:
-
-```tsx
-<Accordion.Trigger asChild disabled>
-  <a href="#shipping">Temporarily unavailable</a>
-  {/* rendered with role="button" aria-disabled="true" */}
-</Accordion.Trigger>
-```
-
-## Trigger icon
-
-Wrap a decorative icon in `Accordion.TriggerIcon` to hide it from assistive
-technology and expose a `data-state` hook for rotation animations. The child
-can be any renderable React content — an inline `<svg>`, a component from
-a third-party icon library (lucide-react, react-icons, etc.), or a custom
-icon component. `aria-hidden` and `data-state` are placed on a wrapping
-`<span>`, so they work regardless of whether the icon component forwards
-unknown props.
-
-```tsx
-import { ChevronDown } from "lucide-react";
-
-<Accordion.Trigger>
-  Shipping policy
-  <Accordion.TriggerIcon>
-    <ChevronDown />
-  </Accordion.TriggerIcon>
-</Accordion.Trigger>;
-```
-
-## Reading direction (RTL)
-
-Pass `dir="rtl"` on `Accordion.Root` combined with `orientation="horizontal"`
-to invert the arrow-key direction so `ArrowLeft` moves forward and
-`ArrowRight` moves backward, matching right-to-left reading order:
-
-```tsx
-<Accordion.Root orientation="horizontal" dir="rtl">
-  ...
-</Accordion.Root>
-```
-
-When `dir` is omitted, it is inherited from the nearest
-[`DirectionProvider`](../DirectionProvider/README.md), falling back to `"ltr"`
-when there is no provider. An explicit `dir` prop always wins over the
-inherited value.
-
-## Styling hooks
-
-```css
-/* Trigger open/closed */
-[data-state="open"] .chevron {
-  transform: rotate(180deg);
-}
-
-/* Content panel */
-[role="region"][data-state="closed"] {
-  display: none;
-}
-
-/* Disabled trigger */
-[aria-disabled="true"] {
-  opacity: 0.5;
-  cursor: not-allowed;
-}
-```
-
-`data-state` (`"open"` | `"closed"`), `data-disabled` (`"true"` | `"false"`),
-and `data-orientation` (`"vertical"` | `"horizontal"`) are available on
-relevant rendered elements.

package/src/Accordion/__tests__/Accordion.asChild.test.tsx

@@ -1,283 +0,0 @@
-import { createRef } from "react";
-import { render, screen } from "@testing-library/react";
-import userEvent from "@testing-library/user-event";
-
-import { Accordion } from "../Accordion";
-
-describe("Accordion asChild tests", () => {
-  it("should render the child element instead of a <button> when asChild is true", () => {
-    // Arrange
-    render(
-      <Accordion.Root>
-        <Accordion.Item>
-          <Accordion.Header>
-            <Accordion.Trigger asChild>
-              <a href="#section-1">Section 1</a>
-            </Accordion.Trigger>
-          </Accordion.Header>
-          <Accordion.Content>Content</Accordion.Content>
-        </Accordion.Item>
-      </Accordion.Root>,
-    );
-
-    // Assert — an anchor is rendered, not a button
-    const trigger = screen.getByRole("link", { name: "Section 1" });
-    expect(trigger.tagName).toBe("A");
-    expect(trigger).toHaveAttribute("href", "#section-1");
-  });
-
-  it("should merge ARIA attributes (aria-expanded, aria-controls, id) onto the child element when asChild is true", () => {
-    // Arrange
-    render(
-      <Accordion.Root>
-        <Accordion.Item>
-          <Accordion.Header>
-            <Accordion.Trigger asChild>
-              <a href="#section-1">Section 1</a>
-            </Accordion.Trigger>
-          </Accordion.Header>
-          <Accordion.Content>Content</Accordion.Content>
-        </Accordion.Item>
-      </Accordion.Root>,
-    );
-
-    const trigger = screen.getByRole("link", { name: "Section 1" });
-
-    // Assert
-    expect(trigger).toHaveAttribute("aria-expanded", "false");
-    expect(trigger).toHaveAttribute("aria-controls");
-    expect(trigger).toHaveAttribute("id");
-  });
-
-  it("should compose child onClick with accordion toggle when asChild is true", async () => {
-    // Arrange
-    const user = userEvent.setup();
-    const childClick = vi.fn();
-    render(
-      <Accordion.Root>
-        <Accordion.Item>
-          <Accordion.Header>
-            <Accordion.Trigger asChild>
-              <button type="button" onClick={childClick}>
-                Section 1
-              </button>
-            </Accordion.Trigger>
-          </Accordion.Header>
-          <Accordion.Content>Content 1</Accordion.Content>
-        </Accordion.Item>
-      </Accordion.Root>,
-    );
-    const trigger = screen.getByRole("button", { name: "Section 1" });
-
-    // Act
-    await user.click(trigger);
-
-    // Assert — child handler fires and panel toggles
-    expect(childClick).toHaveBeenCalledTimes(1);
-    expect(trigger).toHaveAttribute("aria-expanded", "true");
-  });
-
-  it("should forward ref to the child DOM element when asChild is true", () => {
-    // Arrange
-    const ref = createRef<HTMLAnchorElement>();
-    render(
-      <Accordion.Root>
-        <Accordion.Item>
-          <Accordion.Header>
-            <Accordion.Trigger asChild ref={ref}>
-              <a href="#section-1">Section 1</a>
-            </Accordion.Trigger>
-          </Accordion.Header>
-          <Accordion.Content>Content</Accordion.Content>
-        </Accordion.Item>
-      </Accordion.Root>,
-    );
-
-    // Assert
-    expect(ref.current).not.toBeNull();
-    expect(ref.current?.tagName).toBe("A");
-  });
-
-  it("should forward ref to the underlying button element when asChild is false", () => {
-    // Arrange
-    const ref = createRef<HTMLButtonElement>();
-    render(
-      <Accordion.Root>
-        <Accordion.Item>
-          <Accordion.Header>
-            <Accordion.Trigger ref={ref}>Section 1</Accordion.Trigger>
-          </Accordion.Header>
-          <Accordion.Content>Content</Accordion.Content>
-        </Accordion.Item>
-      </Accordion.Root>,
-    );
-
-    // Assert
-    expect(ref.current).not.toBeNull();
-    expect(ref.current?.tagName).toBe("BUTTON");
-  });
-
-  it("should toggle the accordion when Enter is pressed on an asChild anchor element", async () => {
-    // Arrange
-    const user = userEvent.setup();
-    render(
-      <Accordion.Root>
-        <Accordion.Item>
-          <Accordion.Header>
-            <Accordion.Trigger asChild>
-              <a href="#section-1">Section 1</a>
-            </Accordion.Trigger>
-          </Accordion.Header>
-          <Accordion.Content>Content 1</Accordion.Content>
-        </Accordion.Item>
-      </Accordion.Root>,
-    );
-    const trigger = screen.getByRole("link", { name: "Section 1" });
-
-    // Act
-    trigger.focus();
-    await user.keyboard("[Enter]");
-
-    // Assert
-    expect(trigger).toHaveAttribute("aria-expanded", "true");
-  });
-
-  it("should toggle the accordion when Space is pressed on an asChild anchor element", async () => {
-    // Arrange
-    const user = userEvent.setup();
-    render(
-      <Accordion.Root>
-        <Accordion.Item>
-          <Accordion.Header>
-            <Accordion.Trigger asChild>
-              <a href="#section-1">Section 1</a>
-            </Accordion.Trigger>
-          </Accordion.Header>
-          <Accordion.Content>Content 1</Accordion.Content>
-        </Accordion.Item>
-      </Accordion.Root>,
-    );
-    const trigger = screen.getByRole("link", { name: "Section 1" });
-
-    // Act
-    trigger.focus();
-    await user.keyboard(" ");
-
-    // Assert
-    expect(trigger).toHaveAttribute("aria-expanded", "true");
-  });
-
-  it("should not toggle the accordion when Enter is pressed on a disabled asChild anchor element", async () => {
-    // Arrange
-    const user = userEvent.setup();
-    render(
-      <Accordion.Root>
-        <Accordion.Item>
-          <Accordion.Header>
-            <Accordion.Trigger asChild disabled>
-              <a href="#section-1">Section 1</a>
-            </Accordion.Trigger>
-          </Accordion.Header>
-          <Accordion.Content>Content 1</Accordion.Content>
-        </Accordion.Item>
-      </Accordion.Root>,
-    );
-    // disabled asChild gets role="button" injected, so query by button role
-    const trigger = screen.getByRole("button", { name: "Section 1" });
-
-    // Act
-    trigger.focus();
-    await user.keyboard("[Enter]");
-
-    // Assert
-    expect(trigger).toHaveAttribute("aria-expanded", "false");
-  });
-
-  it("should apply role='button' when asChild is true and disabled is true", () => {
-    // Arrange
-    render(
-      <Accordion.Root>
-        <Accordion.Item>
-          <Accordion.Header>
-            <Accordion.Trigger asChild disabled>
-              <a href="#section-1">Section 1</a>
-            </Accordion.Trigger>
-          </Accordion.Header>
-          <Accordion.Content>Content</Accordion.Content>
-        </Accordion.Item>
-      </Accordion.Root>,
-    );
-
-    // Assert — role="button" injected so aria-disabled is semantically valid on a non-button
-    const trigger = screen.getByRole("button", { name: "Section 1" });
-    expect(trigger.tagName).toBe("A");
-    expect(trigger).toHaveAttribute("aria-disabled", "true");
-  });
-
-  it("should NOT apply role='button' when asChild is true and disabled is false", () => {
-    // Arrange
-    render(
-      <Accordion.Root>
-        <Accordion.Item>
-          <Accordion.Header>
-            <Accordion.Trigger asChild>
-              <a href="#section-1">Section 1</a>
-            </Accordion.Trigger>
-          </Accordion.Header>
-          <Accordion.Content>Content</Accordion.Content>
-        </Accordion.Item>
-      </Accordion.Root>,
-    );
-
-    const trigger = screen.getByRole("link", { name: "Section 1" });
-
-    // Assert — no role="button" injected on enabled asChild elements
-    expect(trigger).not.toHaveAttribute("role", "button");
-  });
-
-  // A plain <div> (no native button semantics, no role) fires no synthetic
-  // click on Enter/Space, so these isolate the Trigger's own keydown handler —
-  // a native <button> or anchor would toggle via click even if the handler did
-  // nothing, masking mutations in it.
-  it("toggles on Enter for a non-native asChild element", async () => {
-    const user = userEvent.setup();
-    render(
-      <Accordion.Root>
-        <Accordion.Item value="a">
-          <Accordion.Header>
-            <Accordion.Trigger asChild>
-              <div tabIndex={0} data-testid="trigger">
-                Toggle
-              </div>
-            </Accordion.Trigger>
-          </Accordion.Header>
-          <Accordion.Content data-testid="content">Content</Accordion.Content>
-        </Accordion.Item>
-      </Accordion.Root>,
-    );
-    screen.getByTestId("trigger").focus();
-    await user.keyboard("{Enter}");
-    expect(screen.getByTestId("content")).toBeVisible();
-  });
-
-  it("toggles on Space for a non-native asChild element", async () => {
-    const user = userEvent.setup();
-    render(
-      <Accordion.Root>
-        <Accordion.Item value="a">
-          <Accordion.Header>
-            <Accordion.Trigger asChild>
-              <div tabIndex={0} data-testid="trigger">
-                Toggle
-              </div>
-            </Accordion.Trigger>
-          </Accordion.Header>
-          <Accordion.Content data-testid="content">Content</Accordion.Content>
-        </Accordion.Item>
-      </Accordion.Root>,
-    );
-    screen.getByTestId("trigger").focus();
-    await user.keyboard(" ");
-    expect(screen.getByTestId("content")).toBeVisible();
-  });
-});