@primitiv-ui/react 0.1.0

package/src/Dropdown/types.ts

@@ -0,0 +1,200 @@
+import { ComponentProps, ReactNode, Ref } from "react";
+
+import { CheckedState } from "../Checkbox/types";
+import { Direction } from "../DirectionProvider";
+
+type DropdownRootBaseProps = {
+  children?: ReactNode;
+  /**
+   * Reading direction for the menu. Affects which arrow key opens / closes
+   * a submenu — `ArrowRight` opens in `"ltr"`, `ArrowLeft` opens in
+   * `"rtl"`. Falls back to the inherited {@link DirectionProvider} value,
+   * or to `"ltr"` if no provider is present.
+   */
+  dir?: Direction;
+};
+
+type DropdownRootUncontrolledProps = DropdownRootBaseProps & {
+  defaultOpen?: boolean;
+  open?: never;
+  onOpenChange?: (open: boolean) => void;
+};
+
+type DropdownRootControlledProps = DropdownRootBaseProps & {
+  defaultOpen?: never;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+};
+
+export type DropdownRootProps =
+  | DropdownRootUncontrolledProps
+  | DropdownRootControlledProps;
+
+export type DropdownTriggerProps = Omit<
+  ComponentProps<"button">,
+  "aria-haspopup" | "aria-expanded" | "aria-controls"
+> & {
+  children?: ReactNode;
+  ref?: Ref<HTMLButtonElement>;
+  asChild?: boolean;
+};
+
+export type DropdownContentProps = Omit<
+  ComponentProps<"menu">,
+  "role" | "popover" | "id"
+> & {
+  children?: ReactNode;
+  ref?: Ref<HTMLMenuElement>;
+  asChild?: boolean;
+};
+
+export type DropdownItemProps = Omit<
+  ComponentProps<"li">,
+  "role" | "tabIndex" | "onSelect"
+> & {
+  children?: ReactNode;
+  ref?: Ref<HTMLLIElement>;
+  asChild?: boolean;
+  disabled?: boolean;
+  /**
+   * Fires when the item is activated (click, Enter, or Space). Called
+   * with an event whose `preventDefault()` skips the auto-close that
+   * Dropdown performs after selection.
+   */
+  onSelect?: (event: Event) => void;
+};
+
+export type DropdownSeparatorProps = Omit<ComponentProps<"li">, "role"> & {
+  children?: ReactNode;
+  ref?: Ref<HTMLLIElement>;
+  asChild?: boolean;
+};
+
+export type DropdownItemIndicatorProps = ComponentProps<"span"> & {
+  children?: ReactNode;
+  ref?: Ref<HTMLSpanElement>;
+  asChild?: boolean;
+  /**
+   * Render the indicator even when its parent item is unchecked. The
+   * `data-state` attribute still reflects the live state (`"checked"` /
+   * `"unchecked"` / `"indeterminate"`), so consumers can animate the
+   * indicator in and out instead of mounting / unmounting it.
+   */
+  forceMount?: boolean;
+};
+
+export type DropdownGroupProps = Omit<ComponentProps<"li">, "role"> & {
+  children?: ReactNode;
+  ref?: Ref<HTMLLIElement>;
+  asChild?: boolean;
+};
+
+export type DropdownLabelProps = ComponentProps<"li"> & {
+  children?: ReactNode;
+  ref?: Ref<HTMLLIElement>;
+  asChild?: boolean;
+};
+
+type DropdownCheckboxItemBaseProps = Omit<
+  ComponentProps<"li">,
+  "role" | "tabIndex" | "aria-checked" | "defaultChecked" | "onSelect"
+> & {
+  children?: ReactNode;
+  ref?: Ref<HTMLLIElement>;
+  asChild?: boolean;
+  disabled?: boolean;
+  /**
+   * Fires when activation completes and the close auto-fires. Call
+   * `event.preventDefault()` to keep the menu open after toggling.
+   */
+  onSelect?: (event: Event) => void;
+};
+
+type DropdownCheckboxItemUncontrolledProps = DropdownCheckboxItemBaseProps & {
+  defaultChecked?: CheckedState;
+  checked?: never;
+  onCheckedChange?: (checked: boolean) => void;
+};
+
+type DropdownCheckboxItemControlledProps = DropdownCheckboxItemBaseProps & {
+  defaultChecked?: never;
+  checked: CheckedState;
+  onCheckedChange: (checked: boolean) => void;
+};
+
+export type DropdownCheckboxItemProps =
+  | DropdownCheckboxItemUncontrolledProps
+  | DropdownCheckboxItemControlledProps;
+
+type DropdownRadioGroupBaseProps = Omit<ComponentProps<"li">, "role"> & {
+  children?: ReactNode;
+  ref?: Ref<HTMLLIElement>;
+  asChild?: boolean;
+};
+
+type DropdownRadioGroupUncontrolledProps = DropdownRadioGroupBaseProps & {
+  defaultValue?: string;
+  value?: never;
+  onValueChange?: (value: string) => void;
+};
+
+type DropdownRadioGroupControlledProps = DropdownRadioGroupBaseProps & {
+  defaultValue?: never;
+  value: string;
+  onValueChange: (value: string) => void;
+};
+
+export type DropdownRadioGroupProps =
+  | DropdownRadioGroupUncontrolledProps
+  | DropdownRadioGroupControlledProps;
+
+export type DropdownRadioItemProps = Omit<
+  ComponentProps<"li">,
+  "role" | "tabIndex" | "aria-checked" | "onSelect"
+> & {
+  children?: ReactNode;
+  ref?: Ref<HTMLLIElement>;
+  asChild?: boolean;
+  disabled?: boolean;
+  value: string;
+  onSelect?: (event: Event) => void;
+};
+
+type DropdownSubBaseProps = {
+  children?: ReactNode;
+};
+
+type DropdownSubUncontrolledProps = DropdownSubBaseProps & {
+  defaultOpen?: boolean;
+  open?: never;
+  onOpenChange?: (open: boolean) => void;
+};
+
+type DropdownSubControlledProps = DropdownSubBaseProps & {
+  defaultOpen?: never;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+};
+
+export type DropdownSubProps =
+  | DropdownSubUncontrolledProps
+  | DropdownSubControlledProps;
+
+export type DropdownSubTriggerProps = Omit<
+  ComponentProps<"li">,
+  "role" | "tabIndex" | "aria-haspopup" | "aria-expanded" | "aria-controls"
+> & {
+  children?: ReactNode;
+  ref?: Ref<HTMLLIElement>;
+  asChild?: boolean;
+  disabled?: boolean;
+};
+
+export type DropdownSubContentProps = Omit<
+  ComponentProps<"menu">,
+  "role" | "popover" | "id"
+> & {
+  children?: ReactNode;
+  ref?: Ref<HTMLMenuElement>;
+  asChild?: boolean;
+};

package/src/EmptyState/EmptyState.tsx

@@ -0,0 +1,245 @@
+import { Slot } from "../Slot";
+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.
+ *
+ * **`asChild` composition.** Renders the consumer's element instead of a
+ * `<div>`, merging `role="status"` and all other props in via the
+ * {@link Slot} utility.
+ *
+ * @example
+ * ```tsx
+ * {results.length === 0 && (
+ *   <EmptyState.Root>
+ *     <EmptyState.Title>No results</EmptyState.Title>
+ *     <EmptyState.Description>Try a different search.</EmptyState.Description>
+ *   </EmptyState.Root>
+ * )}
+ * ```
+ */
+function EmptyStateRoot({
+  asChild = false,
+  children,
+  ...rest
+}: EmptyStateRootProps) {
+  const rootProps = { role: "status", ...rest };
+
+  if (asChild) {
+    return <Slot {...rootProps}>{children}</Slot>;
+  }
+
+  return <div {...rootProps}>{children}</div>;
+}
+
+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.
+ *
+ * **`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.
+ *
+ * @example
+ * ```tsx
+ * <EmptyState.Media>
+ *   <InboxIcon />
+ * </EmptyState.Media>
+ * ```
+ */
+function EmptyStateMedia({
+  asChild = false,
+  children,
+  ...rest
+}: EmptyStateMediaProps) {
+  const mediaProps = { "aria-hidden": true, ...rest };
+
+  if (asChild) {
+    return <Slot {...mediaProps}>{children}</Slot>;
+  }
+
+  return <div {...mediaProps}>{children}</div>;
+}
+
+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.
+ *
+ * **`asChild` composition.** Renders the consumer's element instead of a
+ * `<p>`, merging all props in via the {@link Slot} utility.
+ *
+ * @example Promote to a heading
+ * ```tsx
+ * <EmptyState.Title asChild>
+ *   <h2>No results found</h2>
+ * </EmptyState.Title>
+ * ```
+ */
+function EmptyStateTitle({
+  asChild = false,
+  children,
+  ...rest
+}: EmptyStateTitleProps) {
+  if (asChild) {
+    return <Slot {...rest}>{children}</Slot>;
+  }
+
+  return <p {...rest}>{children}</p>;
+}
+
+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`}.
+ *
+ * **`asChild` composition.** Renders the consumer's element instead of a
+ * `<p>`, merging all props in via the {@link Slot} utility.
+ *
+ * @example
+ * ```tsx
+ * <EmptyState.Description>Try adjusting your filters.</EmptyState.Description>
+ * ```
+ */
+function EmptyStateDescription({
+  asChild = false,
+  children,
+  ...rest
+}: EmptyStateDescriptionProps) {
+  if (asChild) {
+    return <Slot {...rest}>{children}</Slot>;
+  }
+
+  return <p {...rest}>{children}</p>;
+}
+
+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.
+ *
+ * **`asChild` composition.** Renders the consumer's element instead of a
+ * `<div>`, merging all props in via the {@link Slot} utility.
+ *
+ * @example
+ * ```tsx
+ * <EmptyState.Actions>
+ *   <button onClick={clearFilters}>Clear filters</button>
+ * </EmptyState.Actions>
+ * ```
+ */
+function EmptyStateActions({
+  asChild = false,
+  children,
+  ...rest
+}: EmptyStateActionsProps) {
+  if (asChild) {
+    return <Slot {...rest}>{children}</Slot>;
+  }
+
+  return <div {...rest}>{children}</div>;
+}
+
+EmptyStateActions.displayName = "EmptyStateActions";
+
+type EmptyStateCompound = typeof EmptyStateRoot & {
+  Root: typeof EmptyStateRoot;
+  Media: typeof EmptyStateMedia;
+  Title: typeof EmptyStateTitle;
+  Description: typeof EmptyStateDescription;
+  Actions: typeof EmptyStateActions;
+};
+
+const EmptyState: EmptyStateCompound = Object.assign(EmptyStateRoot, {
+  Root: EmptyStateRoot,
+  Media: EmptyStateMedia,
+  Title: EmptyStateTitle,
+  Description: EmptyStateDescription,
+  Actions: 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
+ * ```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>
+ * )}
+ * ```
+ */
+EmptyState.displayName = "EmptyState";
+
+export { EmptyState };

package/src/EmptyState/README.md

@@ -0,0 +1,129 @@
+# 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

@@ -0,0 +1,32 @@
+import { EmptyState } from "..";
+import { render, screen } from "@testing-library/react";
+
+describe("EmptyState.Actions component", () => {
+  it("should render a div containing its children", () => {
+    // Arrange
+    render(
+      <EmptyState.Actions>
+        <button>Clear filters</button>
+      </EmptyState.Actions>,
+    );
+
+    // Assert
+    const button = screen.getByRole("button", { name: "Clear filters" });
+    expect(button.parentElement?.tagName).toBe("DIV");
+  });
+
+  it("should render the consumer element with asChild", () => {
+    // Arrange
+    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");
+  });
+});

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

@@ -0,0 +1,30 @@
+import { EmptyState } from "..";
+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
+    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");
+  });
+});

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

@@ -0,0 +1,34 @@
+import { EmptyState } from "..";
+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

@@ -0,0 +1,28 @@
+import { EmptyState } from "..";
+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");
+  });
+});