@primitiv-ui/react 0.1.38 → 0.1.40

package/dist/EmptyState/EmptyState.d.ts

@@ -0,0 +1,246 @@
+import type { ReactElement } from "react";
+import { EmptyStateActionsProps, EmptyStateDescriptionProps, EmptyStateMediaProps, EmptyStateRootProps, EmptyStateTitleProps } from "./types.js";
+/**
+ * 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 declare function EmptyStateRoot({ asChild, children, ...rest }: EmptyStateRootProps): ReactElement;
+export declare namespace EmptyStateRoot {
+    var displayName: string;
+}
+/**
+ * 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 declare function EmptyStateMedia({ asChild, children, ...rest }: EmptyStateMediaProps): ReactElement;
+export declare namespace EmptyStateMedia {
+    var displayName: string;
+}
+/**
+ * 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 declare function EmptyStateTitle({ asChild, children, ...rest }: EmptyStateTitleProps): ReactElement;
+export declare namespace EmptyStateTitle {
+    var displayName: string;
+}
+/**
+ * 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 declare function EmptyStateDescription({ asChild, children, ...rest }: EmptyStateDescriptionProps): ReactElement;
+export declare namespace EmptyStateDescription {
+    var displayName: string;
+}
+/**
+ * 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 declare function EmptyStateActions({ asChild, children, ...rest }: EmptyStateActionsProps): ReactElement;
+export declare namespace EmptyStateActions {
+    var displayName: string;
+}
+/** 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.
+ */
+declare const EmptyState: EmptyStateCompound;
+export { EmptyState };

package/dist/EmptyState/EmptyState.js

@@ -0,0 +1,268 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Slot } from "../Slot/index.js";
+/**
+ * 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 }) {
+    const rootProps = { role: "status", ...rest };
+    if (asChild) {
+        return _jsx(Slot, { ...rootProps, children: children });
+    }
+    return _jsx("div", { ...rootProps, children: children });
+}
+// 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 }) {
+    const mediaProps = { "aria-hidden": true, ...rest };
+    if (asChild) {
+        return _jsx(Slot, { ...mediaProps, children: children });
+    }
+    return _jsx("div", { ...mediaProps, children: children });
+}
+/** @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 }) {
+    if (asChild) {
+        return _jsx(Slot, { ...rest, children: children });
+    }
+    return _jsx("p", { ...rest, children: children });
+}
+/** @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 }) {
+    if (asChild) {
+        return _jsx(Slot, { ...rest, children: children });
+    }
+    return _jsx("p", { ...rest, children: children });
+}
+/** @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 }) {
+    if (asChild) {
+        return _jsx(Slot, { ...rest, children: children });
+    }
+    return _jsx("div", { ...rest, children: children });
+}
+/** @internal */
+EmptyStateActions.displayName = "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 = Object.assign(EmptyStateRoot, {
+    Root: EmptyStateRoot,
+    Media: EmptyStateMedia,
+    Title: EmptyStateTitle,
+    Description: EmptyStateDescription,
+    Actions: EmptyStateActions,
+});
+/** @internal */
+EmptyState.displayName = "EmptyState";
+export { EmptyState };

package/dist/EmptyState/index.d.ts

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

package/dist/EmptyState/index.js

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

package/dist/EmptyState/types.d.ts

@@ -0,0 +1,59 @@
+import { ComponentProps } from "react";
+/** Mixin adding the `asChild` opt-in to a sub-component's props. */
+export type WithAsChild = {
+    /**
+     * When `true`, renders the consumer's own element instead of the
+     * sub-component's default host element, merging all props (aria-*, data-*,
+     * event handlers) onto it via the `Slot` utility. The child must be a single
+     * React element. For `EmptyState.Root` and `EmptyState.Media`, the implicit
+     * `role="status"` / `aria-hidden="true"` are also forwarded through `Slot`.
+     * @default false
+     */
+    asChild?: boolean;
+};
+/**
+ * Props for {@link EmptyStateRoot | `EmptyState.Root`} — all native `<div>`
+ * attributes plus the `asChild` escape hatch.
+ *
+ * The root renders `role="status"` by default, creating a polite ARIA live
+ * region. Override with `role={undefined}` for a static empty state that has
+ * nothing to announce on appearance.
+ */
+export type EmptyStateRootProps = ComponentProps<"div"> & WithAsChild;
+/**
+ * Props for {@link EmptyStateMedia | `EmptyState.Media`} — all native `<div>`
+ * attributes plus the `asChild` escape hatch.
+ *
+ * The media wrapper renders `aria-hidden="true"` by default, hiding decorative
+ * artwork from assistive technology. Pass `aria-hidden={false}` and provide an
+ * accessible name when the artwork is genuinely informative.
+ */
+export type EmptyStateMediaProps = ComponentProps<"div"> & WithAsChild;
+/**
+ * Props for {@link EmptyStateTitle | `EmptyState.Title`} — all native `<p>`
+ * attributes plus the `asChild` escape hatch.
+ *
+ * Renders a `<p>` by default. Use `asChild` to substitute a heading element
+ * (`<h2>`, `<h3>`, etc.) when the empty state stands in for a titled section
+ * and needs to participate in the document's heading hierarchy.
+ */
+export type EmptyStateTitleProps = ComponentProps<"p"> & WithAsChild;
+/**
+ * Props for {@link EmptyStateDescription | `EmptyState.Description`} — all
+ * native `<p>` attributes plus the `asChild` escape hatch.
+ *
+ * Renders a `<p>` for secondary supporting copy that explains the situation or
+ * suggests a next step. Actionable controls belong in
+ * {@link EmptyStateActionsProps | `EmptyState.Actions`} rather than here.
+ */
+export type EmptyStateDescriptionProps = ComponentProps<"p"> & WithAsChild;
+/**
+ * Props for {@link EmptyStateActions | `EmptyState.Actions`} — all native
+ * `<div>` attributes plus the `asChild` escape hatch.
+ *
+ * Renders a plain `<div>` with no ARIA role of its own, so buttons and links
+ * placed inside it retain their native semantics. The element is a child of the
+ * `role="status"` live region, so its text content is included in the
+ * announcement.
+ */
+export type EmptyStateActionsProps = ComponentProps<"div"> & WithAsChild;

package/dist/EmptyState/types.js

@@ -0,0 +1 @@
+export {};