@primitiv-ui/react 0.1.37 → 0.1.39

package/src/EmptyState/EmptyState.tsx

@@ -1,329 +0,0 @@
-import type { ReactElement } from "react";
-
-import { Slot } from "../Slot/index.ts";
-import {
-  EmptyStateActionsProps,
-  EmptyStateDescriptionProps,
-  EmptyStateMediaProps,
-  EmptyStateRootProps,
-  EmptyStateTitleProps,
-} from "./types";
-
-/**
- * The root of an Empty State — renders a `<div role="status">` wrapping the
- * placeholder shown when a collection, search, or view has no content.
- *
- * The `status` role makes the root a polite live region (implicit
- * `aria-live="polite"`, `aria-atomic="true"`). Render the `EmptyState`
- * conditionally — in place of the absent content — so that when it appears
- * after a filter or search returns nothing, assistive technology announces
- * it once the user is idle, without interrupting them.
- *
- * Opt out of the live region by passing `role={undefined}` for an empty
- * state that is part of the initial, static page.
- *
- * **Styling hooks.** `EmptyState.Root` emits no `data-*` attributes — it is a
- * static layout component. Target it via `className` or element selectors.
- *
- * **`asChild` composition.** Renders the consumer's element instead of a
- * `<div>`, merging `role="status"` and all other props in via the
- * {@link Slot} utility.
- *
- * @extends HTMLDivElement
- *
- * @example Conditional empty state (live region)
- * ```tsx
- * {results.length === 0 && (
- *   <EmptyState.Root>
- *     <EmptyState.Title>No results</EmptyState.Title>
- *     <EmptyState.Description>Try a different search.</EmptyState.Description>
- *   </EmptyState.Root>
- * )}
- * ```
- *
- * @example Static empty state (opt out of live region)
- * ```tsx
- * <EmptyState.Root role={undefined}>
- *   <EmptyState.Title>No projects yet</EmptyState.Title>
- * </EmptyState.Root>
- * ```
- *
- * @example asChild — render a `<section>` instead of a `<div>`
- * ```tsx
- * <EmptyState.Root asChild>
- *   <section aria-label="Empty inbox">
- *     <EmptyState.Title>Your inbox is empty</EmptyState.Title>
- *   </section>
- * </EmptyState.Root>
- * ```
- */
-export function EmptyStateRoot({
-  asChild = false,
-  children,
-  ...rest
-}: EmptyStateRootProps): ReactElement {
-  const rootProps = { role: "status", ...rest };
-
-  if (asChild) {
-    return <Slot {...rootProps}>{children}</Slot>;
-  }
-
-  return <div {...rootProps}>{children}</div>;
-}
-
-// Runtime-dead: the compound alias below (same object via Object.assign)
-// overwrites this to "EmptyState" at load, so the value is never observable.
-// The assignment stays because it declares `displayName` on
-// `typeof EmptyStateRoot`, which EmptyStateCompound extends.
-// Stryker disable next-line StringLiteral: overwritten by the compound alias — an equivalent mutant.
-EmptyStateRoot.displayName = "EmptyStateRoot";
-
-/**
- * The illustration slot of an Empty State — renders a `<div aria-hidden="true">`
- * wrapping a decorative icon or illustration.
- *
- * Empty-state artwork is decorative: the {@link EmptyStateTitle | `Title`} and
- * {@link EmptyStateDescription | `Description`} carry the meaning. `Media` is
- * therefore hidden from assistive technology by default, so screen-reader
- * users are not read a redundant or meaningless image. If the artwork is
- * genuinely informative, pass `aria-hidden={false}` and give it an accessible
- * name yourself.
- *
- * **Styling hooks.** `EmptyState.Media` emits no `data-*` attributes. Target it
- * via `className` or the `[aria-hidden]` attribute selector.
- *
- * **`asChild` composition.** Renders the consumer's element instead of a
- * `<div>`, merging `aria-hidden="true"` and all other props in via the
- * {@link Slot} utility.
- *
- * @extends HTMLDivElement
- *
- * @example Decorative icon (default)
- * ```tsx
- * <EmptyState.Media>
- *   <InboxIcon />
- * </EmptyState.Media>
- * ```
- *
- * @example Informative artwork — opt back in to accessibility tree
- * ```tsx
- * <EmptyState.Media aria-hidden={false}>
- *   <img src="/chart.svg" alt="Sales trending to zero" />
- * </EmptyState.Media>
- * ```
- */
-export function EmptyStateMedia({
-  asChild = false,
-  children,
-  ...rest
-}: EmptyStateMediaProps): ReactElement {
-  const mediaProps = { "aria-hidden": true, ...rest };
-
-  if (asChild) {
-    return <Slot {...mediaProps}>{children}</Slot>;
-  }
-
-  return <div {...mediaProps}>{children}</div>;
-}
-
-/** @internal */
-EmptyStateMedia.displayName = "EmptyStateMedia";
-
-/**
- * The headline of an Empty State — renders a `<p>` with the short summary of
- * why the view is empty (e.g. "No results found").
- *
- * A `<p>` is the safe default: a headless primitive cannot know the correct
- * heading level for the surrounding document outline. When the empty state
- * stands in for a titled section, promote the title to a real heading with
- * `asChild` so it joins the page's heading hierarchy.
- *
- * **Styling hooks.** `EmptyState.Title` emits no `data-*` attributes. Target
- * it via `className` or the `p` element selector.
- *
- * **`asChild` composition.** Renders the consumer's element instead of a
- * `<p>`, merging all props in via the {@link Slot} utility.
- *
- * @extends HTMLParagraphElement
- *
- * @example Default paragraph headline
- * ```tsx
- * <EmptyState.Title>No results found</EmptyState.Title>
- * ```
- *
- * @example Promote to a heading
- * ```tsx
- * <EmptyState.Title asChild>
- *   <h2>No results found</h2>
- * </EmptyState.Title>
- * ```
- */
-export function EmptyStateTitle({
-  asChild = false,
-  children,
-  ...rest
-}: EmptyStateTitleProps): ReactElement {
-  if (asChild) {
-    return <Slot {...rest}>{children}</Slot>;
-  }
-
-  return <p {...rest}>{children}</p>;
-}
-
-/** @internal */
-EmptyStateTitle.displayName = "EmptyStateTitle";
-
-/**
- * The supporting copy of an Empty State — renders a `<p>` with the secondary
- * text that explains the situation or suggests a next step (e.g. "Try
- * adjusting your filters").
- *
- * Keep it to guidance the user can act on; the actionable controls themselves
- * belong in {@link EmptyStateActions | `Actions`}.
- *
- * **Styling hooks.** `EmptyState.Description` emits no `data-*` attributes.
- * Target it via `className` or the `p` element selector.
- *
- * **`asChild` composition.** Renders the consumer's element instead of a
- * `<p>`, merging all props in via the {@link Slot} utility.
- *
- * @extends HTMLParagraphElement
- *
- * @example
- * ```tsx
- * <EmptyState.Description>Try adjusting your filters.</EmptyState.Description>
- * ```
- */
-export function EmptyStateDescription({
-  asChild = false,
-  children,
-  ...rest
-}: EmptyStateDescriptionProps): ReactElement {
-  if (asChild) {
-    return <Slot {...rest}>{children}</Slot>;
-  }
-
-  return <p {...rest}>{children}</p>;
-}
-
-/** @internal */
-EmptyStateDescription.displayName = "EmptyStateDescription";
-
-/**
- * The recovery-action slot of an Empty State — renders a `<div>` grouping the
- * controls that let the user move on from the empty state (e.g. a "Clear
- * filters" button or a "Create your first project" link).
- *
- * It is a plain grouping element with no role of its own, so the buttons and
- * links inside keep their native semantics. As a child of
- * {@link EmptyStateRoot | `Root`}'s live region, the control labels are
- * included when the empty state is announced.
- *
- * **Styling hooks.** `EmptyState.Actions` emits no `data-*` attributes. Target
- * it via `className` or the `div` element selector.
- *
- * **`asChild` composition.** Renders the consumer's element instead of a
- * `<div>`, merging all props in via the {@link Slot} utility.
- *
- * @extends HTMLDivElement
- *
- * @example
- * ```tsx
- * <EmptyState.Actions>
- *   <button onClick={clearFilters}>Clear filters</button>
- * </EmptyState.Actions>
- * ```
- */
-export function EmptyStateActions({
-  asChild = false,
-  children,
-  ...rest
-}: EmptyStateActionsProps): ReactElement {
-  if (asChild) {
-    return <Slot {...rest}>{children}</Slot>;
-  }
-
-  return <div {...rest}>{children}</div>;
-}
-
-/** @internal */
-EmptyStateActions.displayName = "EmptyStateActions";
-
-/** Type of the {@link EmptyState} compound — the Root callable plus its sub-components. */
-export type EmptyStateCompound = typeof EmptyStateRoot & {
-  /** The `<div role="status">` live region wrapping the placeholder. */
-  Root: typeof EmptyStateRoot;
-  /** The decorative icon/illustration slot. */
-  Media: typeof EmptyStateMedia;
-  /** The headline. */
-  Title: typeof EmptyStateTitle;
-  /** The supporting copy. */
-  Description: typeof EmptyStateDescription;
-  /** The recovery-action slot. */
-  Actions: typeof EmptyStateActions;
-};
-
-/**
- * Headless, accessible **Empty State** — a stateless compound component for
- * the placeholder shown when a collection, search, or view has no content.
- *
- * `EmptyState` is both callable (an alias of {@link EmptyStateRoot |
- * `EmptyState.Root`}) and carries its sub-components as static properties.
- * Prefer the namespaced form in application code:
- *
- * - {@link EmptyStateRoot | `EmptyState.Root`} — `<div role="status">`, the
- *   polite live region wrapping the placeholder.
- * - {@link EmptyStateMedia | `EmptyState.Media`} — `<div aria-hidden="true">`,
- *   the decorative icon/illustration slot.
- * - {@link EmptyStateTitle | `EmptyState.Title`} — `<p>`, the headline.
- * - {@link EmptyStateDescription | `EmptyState.Description`} — `<p>`, the
- *   supporting copy.
- * - {@link EmptyStateActions | `EmptyState.Actions`} — `<div>`, the
- *   recovery-action slot.
- *
- * All sub-components are stateless and optional — compose only the parts a
- * given empty state needs.
- *
- * @example Full composition
- * ```tsx
- * import { EmptyState } from "@primitiv-ui/react";
- *
- * {results.length === 0 && (
- *   <EmptyState.Root>
- *     <EmptyState.Media>
- *       <SearchIcon />
- *     </EmptyState.Media>
- *     <EmptyState.Title>No results found</EmptyState.Title>
- *     <EmptyState.Description>Try adjusting your filters.</EmptyState.Description>
- *     <EmptyState.Actions>
- *       <button onClick={clearFilters}>Clear filters</button>
- *     </EmptyState.Actions>
- *   </EmptyState.Root>
- * )}
- * ```
- *
- * @example Minimal — title only
- * ```tsx
- * <EmptyState.Root>
- *   <EmptyState.Title>No messages</EmptyState.Title>
- * </EmptyState.Root>
- * ```
- *
- * @see {@link EmptyStateRoot} for the live-region opt-out and `asChild` details.
- * @see {@link EmptyStateMedia} for the `aria-hidden` default and opt-back-in pattern.
- * @see {@link EmptyStateTitle} for the `<p>` default and heading promotion via `asChild`.
- * @see {@link EmptyStateDescription} for secondary copy placement guidance.
- * @see {@link EmptyStateActions} for grouping recovery controls.
- */
-const EmptyState: EmptyStateCompound = Object.assign(EmptyStateRoot, {
-  Root: EmptyStateRoot,
-  Media: EmptyStateMedia,
-  Title: EmptyStateTitle,
-  Description: EmptyStateDescription,
-  Actions: EmptyStateActions,
-});
-
-/** @internal */
-EmptyState.displayName = "EmptyState";
-
-export { EmptyState };

package/src/EmptyState/README.md

@@ -1,129 +0,0 @@
-# EmptyState
-
-A stateless compound component for the placeholder shown when a
-collection, search, or view has no content. Renders a polite
-[`status`](https://www.w3.org/TR/wai-aria-1.2/#status) live region so a
-conditionally-mounted empty state is announced. Zero styles ship.
-
-```tsx
-import { EmptyState } from "@primitiv-ui/react";
-
-{
-  results.length === 0 && (
-    <EmptyState.Root>
-      <EmptyState.Media>
-        <SearchIcon />
-      </EmptyState.Media>
-      <EmptyState.Title>No results found</EmptyState.Title>
-      <EmptyState.Description>
-        Try adjusting your filters.
-      </EmptyState.Description>
-      <EmptyState.Actions>
-        <button onClick={clearFilters}>Clear filters</button>
-      </EmptyState.Actions>
-    </EmptyState.Root>
-  );
-}
-```
-
-## Sub-components
-
-All sub-components are stateless and optional — compose only the parts a
-given empty state needs.
-
-| Export                   | Renders                  | Notes                                                              |
-| ------------------------ | ------------------------ | ------------------------------------------------------------------ |
-| `EmptyState.Root`        | `<div role="status">`    | Polite live region wrapping the placeholder.                       |
-| `EmptyState.Media`       | `<div aria-hidden>`      | Decorative icon/illustration slot — see [Media](#media).           |
-| `EmptyState.Title`       | `<p>`                    | The headline — see [Title heading level](#title-heading-level).    |
-| `EmptyState.Description` | `<p>`                    | Secondary supporting copy.                                         |
-| `EmptyState.Actions`     | `<div>`                  | Groups recovery controls (buttons/links).                          |
-
-`EmptyState` is also callable directly as an alias of `EmptyState.Root`.
-
-## Props
-
-Every sub-component accepts `asChild` plus all native props for the
-element it renders:
-
-| Prop      | Type      | Default | Notes                                                |
-| --------- | --------- | ------- | ---------------------------------------------------- |
-| `asChild` | `boolean` | `false` | Render the consumer's own element instead — see below |
-| `...rest` | native    | —       | All props for the rendered element, including `aria-*` |
-
-## Announce on appearance
-
-`EmptyState.Root` renders `role="status"` — a polite live region with
-implicit `aria-live="polite"` and `aria-atomic="true"`. Render the empty
-state **conditionally**, in place of the absent content, so that when a
-search or filter returns nothing the message is announced once the user
-is idle:
-
-```tsx
-{
-  results.length === 0 && <EmptyState.Root>No results found</EmptyState.Root>;
-}
-```
-
-For an empty state that is part of the initial, static page — and so has
-nothing to announce — opt out of the live region:
-
-```tsx
-<EmptyState.Root role={undefined}>...</EmptyState.Root>
-```
-
-## Media
-
-Empty-state artwork is decorative: the `Title` and `Description` carry
-the meaning. `EmptyState.Media` is therefore `aria-hidden` by default so
-screen-reader users are not read a redundant image. If the artwork is
-genuinely informative, opt back in and give it an accessible name:
-
-```tsx
-<EmptyState.Media aria-hidden={false}>
-  <img src="/chart.svg" alt="Sales trending to zero" />
-</EmptyState.Media>
-```
-
-## Title heading level
-
-`EmptyState.Title` renders a `<p>` — a headless primitive cannot know
-the correct heading level for the surrounding document outline. When the
-empty state stands in for a titled section, promote the title to a real
-heading with `asChild` so it joins the page's heading hierarchy:
-
-```tsx
-<EmptyState.Title asChild>
-  <h2>No results found</h2>
-</EmptyState.Title>
-```
-
-## asChild
-
-Pass `asChild` to any sub-component to render the consumer's own element
-instead of the default, merging in the sub-component's props (and, for
-`Root` and `Media`, its `role` / `aria-hidden`) via the `Slot` utility:
-
-```tsx
-<EmptyState.Root asChild>
-  <section>...</section>
-</EmptyState.Root>
-```
-
-## Styling hooks
-
-`EmptyState` emits no `data-*` attributes — it is a static layout
-component. Style it with whatever system you use, targeting the rendered
-elements directly or via your own `className`s:
-
-```tsx
-<EmptyState.Root className="empty-state">
-  <EmptyState.Title className="empty-state__title">
-    No results found
-  </EmptyState.Title>
-</EmptyState.Root>
-```
-
----
-
-[Back to @primitiv-ui/react](../../README.md)

package/src/EmptyState/__tests__/EmptyState.Actions.test.tsx

@@ -1,37 +0,0 @@
-import { EmptyState } from "../index.ts";
-import { render, screen } from "@testing-library/react";
-
-describe("EmptyState.Actions component", () => {
-  it("should render a div containing its children", () => {
-    // Arrange
-    const { container } = render(
-      <EmptyState.Actions>
-        <button>Clear filters</button>
-      </EmptyState.Actions>,
-    );
-
-    // Assert
-    const button = screen.getByRole("button", { name: "Clear filters" });
-    expect(button.parentElement?.tagName).toBe("DIV");
-    // The wrapping <div> is Actions' own render root (default is not asChild),
-    // not the test container.
-    expect((container.firstChild as HTMLElement).tagName).toBe("DIV");
-  });
-
-  it("should render the consumer element with asChild", () => {
-    // Arrange
-    const { container } = render(
-      <EmptyState.Actions asChild>
-        <nav>
-          <button>Clear filters</button>
-        </nav>
-      </EmptyState.Actions>,
-    );
-
-    // Assert
-    const button = screen.getByRole("button", { name: "Clear filters" });
-    expect(button.parentElement?.tagName).toBe("NAV");
-    // Slot renders the <nav> in place — no default <div> wrapper around it.
-    expect(container.querySelector("div")).toBeNull();
-  });
-});

package/src/EmptyState/__tests__/EmptyState.Description.test.tsx

@@ -1,32 +0,0 @@
-import { EmptyState } from "../index.ts";
-import { render, screen } from "@testing-library/react";
-
-describe("EmptyState.Description component", () => {
-  it("should render a paragraph containing its children", () => {
-    // Arrange
-    render(
-      <EmptyState.Description>
-        Try adjusting your filters.
-      </EmptyState.Description>,
-    );
-
-    // Assert
-    const description = screen.getByText("Try adjusting your filters.");
-    expect(description.tagName).toBe("P");
-  });
-
-  it("should render the consumer element with asChild", () => {
-    // Arrange
-    const { container } = render(
-      <EmptyState.Description asChild>
-        <span>Try adjusting your filters.</span>
-      </EmptyState.Description>,
-    );
-
-    // Assert
-    const description = screen.getByText("Try adjusting your filters.");
-    expect(description.tagName).toBe("SPAN");
-    // Slot renders the child in place — no default <p> wrapper around it.
-    expect(container.querySelector("p")).toBeNull();
-  });
-});

package/src/EmptyState/__tests__/EmptyState.Media.test.tsx

@@ -1,34 +0,0 @@
-import { EmptyState } from "../index.ts";
-import { render } from "@testing-library/react";
-
-describe("EmptyState.Media component", () => {
-  it("should render a div hidden from assistive technology", () => {
-    // Arrange
-    const { container } = render(
-      <EmptyState.Media>
-        <svg />
-      </EmptyState.Media>,
-    );
-
-    // Assert
-    const media = container.firstChild as HTMLElement;
-    expect(media.tagName).toBe("DIV");
-    expect(media).toHaveAttribute("aria-hidden", "true");
-  });
-
-  it("should render the consumer element with asChild, keeping it hidden", () => {
-    // Arrange
-    const { container } = render(
-      <EmptyState.Media asChild>
-        <span>
-          <svg />
-        </span>
-      </EmptyState.Media>,
-    );
-
-    // Assert
-    const media = container.firstChild as HTMLElement;
-    expect(media.tagName).toBe("SPAN");
-    expect(media).toHaveAttribute("aria-hidden", "true");
-  });
-});

package/src/EmptyState/__tests__/EmptyState.Root.test.tsx

@@ -1,38 +0,0 @@
-import { EmptyState } from "../index.ts";
-import { render, screen } from "@testing-library/react";
-
-describe("EmptyState.Root component", () => {
-  it("should render a div with role status containing its children", () => {
-    // Arrange
-    render(<EmptyState.Root>No projects yet</EmptyState.Root>);
-
-    // Assert
-    const root = screen.getByRole("status");
-    expect(root.tagName).toBe("DIV");
-    expect(root).toHaveTextContent("No projects yet");
-  });
-
-  it("should render the consumer element with asChild, keeping role status", () => {
-    // Arrange
-    render(
-      <EmptyState.Root asChild>
-        <section>No projects yet</section>
-      </EmptyState.Root>,
-    );
-
-    // Assert
-    const root = screen.getByRole("status");
-    expect(root.tagName).toBe("SECTION");
-    expect(root).toHaveTextContent("No projects yet");
-  });
-
-  it("sets a displayName on the compound and each sub-component", () => {
-    // Assert — empty displayNames would render each as anonymous in DevTools.
-    // Root aliases the compound (Object.assign), so its name is "EmptyState".
-    expect(EmptyState.displayName).toBe("EmptyState");
-    expect(EmptyState.Media.displayName).toBe("EmptyStateMedia");
-    expect(EmptyState.Title.displayName).toBe("EmptyStateTitle");
-    expect(EmptyState.Description.displayName).toBe("EmptyStateDescription");
-    expect(EmptyState.Actions.displayName).toBe("EmptyStateActions");
-  });
-});

package/src/EmptyState/__tests__/EmptyState.Title.test.tsx

@@ -1,28 +0,0 @@
-import { EmptyState } from "../index.ts";
-import { render, screen } from "@testing-library/react";
-
-describe("EmptyState.Title component", () => {
-  it("should render a paragraph containing its children", () => {
-    // Arrange
-    render(<EmptyState.Title>No results found</EmptyState.Title>);
-
-    // Assert
-    const title = screen.getByText("No results found");
-    expect(title.tagName).toBe("P");
-  });
-
-  it("should render the consumer element with asChild", () => {
-    // Arrange
-    const { container } = render(
-      <EmptyState.Title asChild>
-        <h2>No results found</h2>
-      </EmptyState.Title>,
-    );
-
-    // Assert
-    const title = screen.getByRole("heading", { name: "No results found" });
-    expect(title.tagName).toBe("H2");
-    // Slot renders the child in place — no default <p> wrapper around it.
-    expect(container.querySelector("p")).toBeNull();
-  });
-});

package/src/EmptyState/index.ts

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