@instruments/materia-ui 0.1.0

package/dist/compositions/editorial-card/editorial-card-media.d.ts

@@ -0,0 +1,19 @@
+import type { ReactNode } from "react";
+import type { EditorialCardImageProps } from "./editorial-card-ticker.js";
+export interface EditorialCardMediaProps {
+    /** Alt text for the image */
+    alt?: string;
+    /** Optional class name for the container */
+    className?: string;
+    /** Image URL */
+    imageSrc?: string;
+    /** Custom image renderer (e.g., for next/image). Defaults to standard img element. */
+    renderImage?: (props: EditorialCardImageProps) => ReactNode;
+    /** Video URL (takes precedence over imageSrc) */
+    videoSrc?: string;
+}
+/**
+ * Media variant for EditorialCard - displays a single image or video
+ * with rounded corners and padding.
+ */
+export declare const EditorialCardMedia: ({ imageSrc, videoSrc, alt, className, renderImage, }: EditorialCardMediaProps) => import("react").JSX.Element;

package/dist/compositions/editorial-card/editorial-card-media.js

@@ -0,0 +1,22 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Center } from "@instruments/materia-ui/components/center";
+import { MediaFrame } from "@instruments/materia-ui/components/media-frame";
+import { cn } from "@instruments/materia-ui/utils/cn";
+const defaultRenderImage = ({ src, alt, className, draggable, }) => (_jsx("img", { alt: alt, className: className, draggable: draggable, height: 192, src: src, width: 320 }));
+/**
+ * Media variant for EditorialCard - displays a single image or video
+ * with rounded corners and padding.
+ */
+export const EditorialCardMedia = ({ imageSrc, videoSrc, alt = "", className, renderImage = defaultRenderImage, }) => (_jsx(Center, { className: cn("h-48 overflow-hidden px-4 pt-4", className), "data-slot": "editorial-card-media", children: _jsxs(MediaFrame, { className: "size-full rounded-2xl", children: [videoSrc !== undefined && videoSrc !== null && videoSrc !== "" && (_jsx("video", { "aria-hidden": "true", autoPlay: true, className: "size-full object-cover", loop: true, muted: true, playsInline: true, src: videoSrc, tabIndex: -1 })), (videoSrc === undefined || videoSrc === null || videoSrc === "") &&
+                imageSrc !== undefined &&
+                imageSrc !== null &&
+                imageSrc !== "" &&
+                renderImage({
+                    alt,
+                    className: "object-cover",
+                    draggable: false,
+                    fill: true,
+                    sizes: "(max-width: 768px) 100vw, 320px",
+                    src: imageSrc,
+                })] }) }));

package/dist/compositions/editorial-card/editorial-card-root.d.ts

@@ -0,0 +1,57 @@
+import type { ReactNode } from "react";
+import type { EditorialCardImageProps } from "./editorial-card-ticker.js";
+export type EditorialCardVariant = "ticker" | "stack" | "media";
+export interface EditorialCardProps {
+    /** Alt text for media variant */
+    alt?: string;
+    /** Optional class name */
+    className?: string;
+    /** Optional link URL - wraps card in anchor if provided */
+    href?: string;
+    /** Single image URL for media variant */
+    imageSrc?: string;
+    /** Array of image URLs for ticker and stack variants */
+    images?: string[];
+    /**
+     * Custom image renderer for framework-specific image components (e.g., next/image).
+     * Defaults to standard img element.
+     *
+     * @example
+     * ```tsx
+     * // Using Next.js Image
+     * import Image from "next/image";
+     *
+     * <EditorialCard
+     *   renderImage={({ src, alt, className, width, height }) => (
+     *     <Image
+     *       src={src}
+     *       alt={alt}
+     *       className={className}
+     *       width={width}
+     *       height={height}
+     *     />
+     *   )}
+     * />
+     * ```
+     */
+    renderImage?: (props: EditorialCardImageProps) => ReactNode;
+    /** Optional subtitle text (appears above title) */
+    subtitle?: string;
+    /** Velocity for ticker animation (pixels per second) */
+    tickerVelocity?: number;
+    /** Main title text */
+    title: string;
+    /** Visual variant of the card */
+    variant: EditorialCardVariant;
+    /** Video URL for media variant (takes precedence over imageSrc) */
+    videoSrc?: string;
+}
+/**
+ * Renders an editorial content card in one of several layout variants, composing imagery, title, and subtitle into a single linkable promotional tile.
+ *
+ * @bestPractice Match the media prop to `variant`: `ticker`/`stack` consume `images[]` (stack uses the first three), while `media` uses `imageSrc`/`videoSrc` - passing the wrong one renders empty media.
+ * @bestPractice Pass `renderImage` (wrapping `next/image`) in Next.js - the default is a plain `<img>` and skips Next optimisation; give `media` images a meaningful `alt`.
+ * @bestPractice Set `href` to make the whole card a single link (it wraps in an `<a>`); don't nest additional links/buttons inside - use `EditorialCard` for promo tiles, plain `Card` for neutral content.
+ * @category catalogue
+ */
+export declare const EditorialCard: ({ variant, title, subtitle, href, images, imageSrc, videoSrc, alt, tickerVelocity, className, renderImage, }: EditorialCardProps) => import("react").JSX.Element;

package/dist/compositions/editorial-card/editorial-card-root.js

@@ -0,0 +1,84 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { EditorialCardContent } from "./editorial-card-content.js";
+import { EditorialCardMedia } from "./editorial-card-media.js";
+import { EditorialCardStack } from "./editorial-card-stack.js";
+import { EditorialCardTicker } from "./editorial-card-ticker.js";
+/**
+ * EditorialCard displays featured content in various visual styles.
+ *
+ * @param props - The editorial card props
+ * @param props.variant - Visual variant: "ticker" (scrolling grid), "stack" (overlapping cards), or "media" (single image/video)
+ * @param props.title - Main title text displayed below the media
+ * @param props.subtitle - Optional subtitle displayed above the title
+ * @param props.href - Optional link URL - wraps card in anchor if provided
+ * @param props.images - Array of image URLs for ticker (all) and stack (first 3) variants
+ * @param props.imageSrc - Single image URL for media variant
+ * @param props.videoSrc - Video URL for media variant (takes precedence over imageSrc)
+ * @param props.alt - Alt text for media variant image
+ * @param props.tickerVelocity - Speed of ticker animation in pixels per second (default: 20)
+ * @param props.className - Additional CSS classes
+ *
+ * @example
+ * ```tsx
+ * // Ticker variant with scrolling thumbnails
+ * <EditorialCard
+ *   variant="ticker"
+ *   title="Hüron Residences"
+ *   subtitle="Curated for your project"
+ *   images={[...imageUrls]}
+ * />
+ *
+ * // Stack variant with overlapping cards
+ * <EditorialCard
+ *   variant="stack"
+ *   title="LEED rated japandi curtains"
+ *   subtitle="Pick up where you left off"
+ *   images={[img1, img2, img3]}
+ * />
+ *
+ * // Media variant with single image
+ * <EditorialCard
+ *   variant="media"
+ *   title="Handcrafted Tiles"
+ *   subtitle="Featured collection"
+ *   imageSrc="/path/to/image.jpg"
+ * />
+ * ```
+ */
+const EMPTY_IMAGES = [];
+const EditorialCardMediaSwitch = ({ variant, images, imageSrc, videoSrc, alt, tickerVelocity, renderImage, }) => {
+    switch (variant) {
+        case "ticker": {
+            return (_jsx(EditorialCardTicker, { images: images, ...(renderImage === undefined ? {} : { renderImage }), ...(tickerVelocity === undefined
+                    ? {}
+                    : { velocity: tickerVelocity }) }));
+        }
+        case "stack": {
+            return (_jsx(EditorialCardStack, { images: images, ...(renderImage === undefined ? {} : { renderImage }) }));
+        }
+        case "media": {
+            return (_jsx(EditorialCardMedia, { ...(alt === undefined ? {} : { alt }), ...(imageSrc === undefined ? {} : { imageSrc }), ...(renderImage === undefined ? {} : { renderImage }), ...(videoSrc === undefined ? {} : { videoSrc }) }));
+        }
+        default: {
+            return null;
+        }
+    }
+};
+/**
+ * Renders an editorial content card in one of several layout variants, composing imagery, title, and subtitle into a single linkable promotional tile.
+ *
+ * @bestPractice Match the media prop to `variant`: `ticker`/`stack` consume `images[]` (stack uses the first three), while `media` uses `imageSrc`/`videoSrc` - passing the wrong one renders empty media.
+ * @bestPractice Pass `renderImage` (wrapping `next/image`) in Next.js - the default is a plain `<img>` and skips Next optimisation; give `media` images a meaningful `alt`.
+ * @bestPractice Set `href` to make the whole card a single link (it wraps in an `<a>`); don't nest additional links/buttons inside - use `EditorialCard` for promo tiles, plain `Card` for neutral content.
+ * @category catalogue
+ */
+export const EditorialCard = ({ variant, title, subtitle, href, images = EMPTY_IMAGES, imageSrc, videoSrc, alt, tickerVelocity, className, renderImage, }) => {
+    const content = (_jsxs(_Fragment, { children: [_jsx(EditorialCardMediaSwitch, { ...(alt === undefined ? {} : { alt }), ...(imageSrc === undefined ? {} : { imageSrc }), images: images, ...(renderImage === undefined ? {} : { renderImage }), ...(tickerVelocity === undefined ? {} : { tickerVelocity }), variant: variant, ...(videoSrc === undefined ? {} : { videoSrc }) }), _jsx(EditorialCardContent, { title: title, ...(subtitle === undefined ? {} : { subtitle }) })] }));
+    const baseClassName = cn("bg-card flex h-80 flex-1 flex-col overflow-hidden rounded-3xl", className);
+    if (href !== undefined && href !== null && href !== "") {
+        return (_jsx("a", { className: cn(baseClassName, "cursor-pointer no-underline"), "data-component": "editorial-card", href: href, children: content }));
+    }
+    return (_jsx("div", { className: baseClassName, "data-component": "editorial-card", children: content }));
+};

package/dist/compositions/editorial-card/editorial-card-stack.d.ts

@@ -0,0 +1,21 @@
+import type { ReactNode } from "react";
+import type { EditorialCardImageProps } from "./editorial-card-ticker.js";
+export interface EditorialCardStackProps {
+    /** Optional class name for the container */
+    className?: string;
+    /** Array of image URLs (uses first 3) */
+    images: string[];
+    /** Custom image renderer (e.g., for next/image). Defaults to standard img element. */
+    renderImage?: (props: EditorialCardImageProps) => ReactNode;
+}
+/**
+ * Stack variant for EditorialCard - three overlapping material cards with
+ * slight rotations that spread apart on hover.
+ *
+ * Built on {@link SwatchFan} (spread variant) rather than hand-rolled
+ * transforms. The Figma constants (90px card, 109px wrapper, 83px overlap,
+ * 3.5px border, 21/17 radii, ±8° rotation, 12px hover nudge) are pinned via
+ * SwatchFan's layout override props so the output is pixel-identical to the
+ * original composition.
+ */
+export declare const EditorialCardStack: ({ images, className, renderImage, }: EditorialCardStackProps) => import("react").JSX.Element;

package/dist/compositions/editorial-card/editorial-card-stack.js

@@ -0,0 +1,57 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Center } from "@instruments/materia-ui/components/center";
+import { SwatchFan } from "@instruments/materia-ui/compositions/swatch-fan";
+import { cn } from "@instruments/materia-ui/utils/cn";
+const defaultRenderImage = ({ src, alt, className, draggable, width, height, fill, }) => (_jsx("img", { alt: alt, className: cn(fill === true ? "absolute inset-0 size-full" : "", className), draggable: draggable, height: height ?? 1, src: src, width: width ?? 1 }));
+// =============================================================================
+// Exact Figma specifications (preserved pixel-for-pixel from the original
+// hand-rolled stack). SwatchFan's own computed defaults differ, so these are
+// pinned via SwatchFan's layout override props below.
+// =============================================================================
+// Inner image size in px
+const CARD_INNER = 90;
+// Border width in px
+const CARD_BORDER = 3.5;
+// Bordered outer card size. Swatch tile numeric sizes are border-box, so passing
+// the outer size yields a 90px inner image inside a 3.5px border (97px total),
+// matching the Figma card. SwatchFan's fan geometry is built on this outer size.
+// = 97
+const CARD_OUTER = CARD_INNER + CARD_BORDER * 2;
+// Outer border radius in px
+const OUTER_RADIUS = 21;
+// Inner image border radius in px (the Swatch tile's standard tier rounds images to
+// 14px; force the Figma 17px so the inner corners match the original exactly)
+const INNER_RADIUS_CLASS = "rounded-editorial-stack!";
+// Square wrapper for the rotated side cards (from Figma)
+const WRAPPER_SIZE = 109;
+// Heavy horizontal overlap between adjacent cards (from Figma)
+const OVERLAP = 83;
+// Side-card rotation in degrees
+const ROTATION = 8;
+// Outward nudge (px) applied to the side cards on hover; no extra rotation
+const HOVER_SHIFT = 12;
+const HOVER_ROTATE = 0;
+/**
+ * Stack variant for EditorialCard - three overlapping material cards with
+ * slight rotations that spread apart on hover.
+ *
+ * Built on {@link SwatchFan} (spread variant) rather than hand-rolled
+ * transforms. The Figma constants (90px card, 109px wrapper, 83px overlap,
+ * 3.5px border, 21/17 radii, ±8° rotation, 12px hover nudge) are pinned via
+ * SwatchFan's layout override props so the output is pixel-identical to the
+ * original composition.
+ */
+export const EditorialCardStack = ({ images, className, renderImage = defaultRenderImage, }) => {
+    const items = images.slice(0, 3).map((src, index) => ({
+        id: `${index}-${src}`,
+        src,
+    }));
+    // Delegate to the consumer's renderer but pin the inner-image radius so the
+    // corners match the Figma spec (the Swatch tile would otherwise round to 14px).
+    const renderStackImage = (props) => renderImage({
+        ...props,
+        className: cn(props.className, INNER_RADIUS_CLASS),
+    });
+    return (_jsx(Center, { className: cn("relative h-48", className), "data-slot": "editorial-card-stack", children: _jsx(SwatchFan, { cardBorderWidth: CARD_BORDER, cardRadius: OUTER_RADIUS, hoverRotate: HOVER_ROTATE, hoverShift: HOVER_SHIFT, items: items, overlap: OVERLAP, renderImage: renderStackImage, rotationDeg: ROTATION, size: CARD_OUTER, variant: "spread", wrapperSize: WRAPPER_SIZE }) }));
+};

package/dist/compositions/editorial-card/editorial-card-ticker.d.ts

@@ -0,0 +1,31 @@
+import type { ReactNode } from "react";
+/** Props passed to the renderImage function */
+export interface EditorialCardImageProps {
+    alt: string;
+    className: string;
+    draggable: boolean;
+    /** Use fill mode (for next/image to fill parent container) */
+    fill?: boolean;
+    /** Height in pixels (for next/image with fixed dimensions) */
+    height?: number;
+    /** Sizes attribute for responsive images (required with fill for next/image) */
+    sizes?: string;
+    src: string;
+    /** Width in pixels (for next/image with fixed dimensions) */
+    width?: number;
+}
+export interface EditorialCardTickerProps {
+    /** Optional class name for the container */
+    className?: string;
+    /** Array of image URLs to display in the ticker grid */
+    images: string[];
+    /** Custom image renderer (e.g., for next/image). Defaults to standard img element. */
+    renderImage?: (props: EditorialCardImageProps) => ReactNode;
+    /** Velocity for the ticker animation (pixels per second) */
+    velocity?: number;
+}
+/**
+ * Ticker variant for EditorialCard - displays a 2-row grid of continuously
+ * scrolling thumbnails using the local plain-`motion` Marquee.
+ */
+export declare const EditorialCardTicker: ({ images, className, velocity, renderImage, }: EditorialCardTickerProps) => import("react").JSX.Element;

package/dist/compositions/editorial-card/editorial-card-ticker.js

@@ -0,0 +1,81 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Flex } from "@instruments/materia-ui/components/flex";
+import { MediaFrame } from "@instruments/materia-ui/components/media-frame";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { useAnimationFrame, useMotionValue, useReducedMotion, } from "motion/react";
+import * as m from "motion/react-m";
+import { useLayoutEffect, useRef } from "react";
+/**
+ * Infinite horizontal marquee on plain `motion` - the local
+ * replacement for motion-plus `Ticker`.
+ *
+ * Renders the item set twice and advances a single translateX motion value each
+ * frame, wrapping by the measured width of one set (plus the inter-set gap) so
+ * the second copy slides into the first's place with no visible seam. Positive
+ * `velocity` scrolls one way, negative the other; magnitude is pixels/second.
+ */
+const Marquee = ({ items, gap, velocity, }) => {
+    const x = useMotionValue(0);
+    const setRef = useRef(null);
+    const wrapWidthRef = useRef(0);
+    useLayoutEffect(() => {
+        const element = setRef.current;
+        if (!element) {
+            return () => {
+                // No element mounted yet - nothing to observe or clean up.
+            };
+        }
+        const measure = () => {
+            // Wrap distance is one set's width plus the gap separating the two sets,
+            // so copy B lands exactly where copy A began.
+            wrapWidthRef.current = element.getBoundingClientRect().width + gap;
+        };
+        measure();
+        const observer = new ResizeObserver(measure);
+        observer.observe(element);
+        return () => {
+            observer.disconnect();
+        };
+    }, [gap]);
+    const reduceMotion = useReducedMotion();
+    useAnimationFrame((_time, delta) => {
+        const wrapWidth = wrapWidthRef.current;
+        if (wrapWidth === 0 || reduceMotion === true) {
+            return;
+        }
+        let next = (x.get() - velocity * (delta / 1000)) % wrapWidth;
+        // Normalise into (-wrapWidth, 0] so both scroll directions stay seamless.
+        if (next > 0) {
+            next -= wrapWidth;
+        }
+        x.set(next);
+    });
+    return (_jsx("div", { className: "overflow-hidden", children: _jsxs(m.div, { className: "flex w-max", style: { gap, x }, children: [_jsx(Flex, { className: "w-max shrink-0", ref: setRef, style: { gap }, children: items }), _jsx(Flex, { "aria-hidden": true, className: "w-max shrink-0", style: { gap }, children: items })] }) }));
+};
+const defaultRenderImage = ({ src, alt, className, draggable, }) => (_jsx("img", { alt: alt, className: className, draggable: draggable, height: 96, src: src, width: 96 }));
+/**
+ * Ticker variant for EditorialCard - displays a 2-row grid of continuously
+ * scrolling thumbnails using the local plain-`motion` Marquee.
+ */
+export const EditorialCardTicker = ({ images, className, velocity = 20, renderImage = defaultRenderImage, }) => {
+    // Split images into two rows
+    const midpoint = Math.ceil(images.length / 2);
+    const topRowImages = images.slice(0, midpoint);
+    const bottomRowImages = images.slice(midpoint);
+    const createTickerItems = (imageUrls) => imageUrls.map((src) => {
+        // renderImage is a consumer-supplied render prop (defaults to <img>,
+        // consumers pass next/image). It is called here, not wrapped in a
+        // component, so the consumer's own image element is what React keeps.
+        const image = renderImage({
+            alt: "",
+            className: "object-cover",
+            draggable: false,
+            fill: true,
+            sizes: "96px",
+            src,
+        });
+        return (_jsx(MediaFrame, { className: "size-24 shrink-0 rounded-2xl", children: image }, src));
+    });
+    return (_jsxs(Flex, { className: cn("h-48 overflow-hidden", className), "data-slot": "editorial-card-ticker", direction: "column", gap: "2xs", justify: "flex-end", children: [_jsx(Marquee, { gap: 4, items: createTickerItems(topRowImages), velocity: -velocity }), _jsx(Marquee, { gap: 4, items: createTickerItems(bottomRowImages), velocity: velocity })] }));
+};

package/dist/compositions/editorial-card.d.ts

@@ -0,0 +1,5 @@
+export { EditorialCardContent, type EditorialCardContentProps, } from "./editorial-card/editorial-card-content.js";
+export { EditorialCardMedia, type EditorialCardMediaProps, } from "./editorial-card/editorial-card-media.js";
+export { EditorialCard, type EditorialCardProps, type EditorialCardVariant, } from "./editorial-card/editorial-card-root.js";
+export { EditorialCardStack, type EditorialCardStackProps, } from "./editorial-card/editorial-card-stack.js";
+export { type EditorialCardImageProps, EditorialCardTicker, type EditorialCardTickerProps, } from "./editorial-card/editorial-card-ticker.js";

package/dist/compositions/editorial-card.js

@@ -0,0 +1,5 @@
+export { EditorialCardContent, } from "./editorial-card/editorial-card-content.js";
+export { EditorialCardMedia, } from "./editorial-card/editorial-card-media.js";
+export { EditorialCard, } from "./editorial-card/editorial-card-root.js";
+export { EditorialCardStack, } from "./editorial-card/editorial-card-stack.js";
+export { EditorialCardTicker, } from "./editorial-card/editorial-card-ticker.js";

package/dist/compositions/empty-state/empty-state-root.d.ts

@@ -0,0 +1,46 @@
+import type { LucideIcon } from "lucide-react";
+import type * as React from "react";
+import type { EmptyMediaProps } from "../../components/empty/empty-media.js";
+import type { EmptyProps } from "../../components/empty/empty-root.js";
+import type { HeadingLevel } from "../../tokens/heading-level.js";
+export interface EmptyStateProps extends Omit<EmptyProps, "children" | "title"> {
+    /** Actions rendered in `EmptyActions`. Wrap `next/link` via `<Button render={<Link />}>`. */
+    actions?: React.ReactNode;
+    /** Supporting copy rendered in `EmptyDescription`. */
+    description?: React.ReactNode;
+    /** Icon shown above the title, via `EmptyMedia`. Ignored when `media` is set. */
+    icon?: LucideIcon;
+    /** Render the icon bare, without the rounded `IconBox` surface. */
+    iconPlain?: boolean;
+    /** Icon box surface tone (also tints the bare icon when `iconPlain`). */
+    iconTone?: EmptyMediaProps["tone"];
+    /**
+     * Heading level passed to `EmptyTitle`, for the document outline.
+     * @default "3"
+     */
+    level?: HeadingLevel;
+    /** Custom media (illustration / `SwatchFan`). Takes precedence over `icon`. */
+    media?: React.ReactNode;
+    /** Heading text. */
+    title: React.ReactNode;
+}
+/**
+ * Generic empty state, composed on `Empty`. Replaces the per-feature
+ * "nothing here" implementations with one flat-props preset: an icon (or custom
+ * media), a title, optional description, and optional actions.
+ *
+ * @example
+ * ```tsx
+ * <EmptyState
+ *   icon={SearchX}
+ *   title="No results found"
+ *   description="Try adjusting your filters."
+ *   actions={<Button onClick={reset}>Clear filters</Button>}
+ * />
+ * ```
+ *
+ * @bestPractice Use `EmptyState` for "no data / nothing here"; a failure the user can retry is an `ErrorState` (which also composes `Empty`), so don't hand-roll a retry empty.
+ * @bestPractice Set `level` to keep the document outline gapless where you place it - a full-page empty near an `h2` wants `level="3"`, but a nested one may need `"4"`.
+ * @category states
+ */
+export declare const EmptyState: ({ actions, description, icon, iconPlain, iconTone, level, media, title, ...emptyProps }: EmptyStateProps) => React.JSX.Element;

package/dist/compositions/empty-state/empty-state-root.js

@@ -0,0 +1,40 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { EmptyActions } from "../../components/empty/empty-actions.js";
+import { EmptyDescription } from "../../components/empty/empty-description.js";
+import { EmptyHeader } from "../../components/empty/empty-header.js";
+import { EmptyMedia } from "../../components/empty/empty-media.js";
+import { Empty } from "../../components/empty/empty-root.js";
+import { EmptyTitle } from "../../components/empty/empty-title.js";
+/**
+ * Generic empty state, composed on `Empty`. Replaces the per-feature
+ * "nothing here" implementations with one flat-props preset: an icon (or custom
+ * media), a title, optional description, and optional actions.
+ *
+ * @example
+ * ```tsx
+ * <EmptyState
+ *   icon={SearchX}
+ *   title="No results found"
+ *   description="Try adjusting your filters."
+ *   actions={<Button onClick={reset}>Clear filters</Button>}
+ * />
+ * ```
+ *
+ * @bestPractice Use `EmptyState` for "no data / nothing here"; a failure the user can retry is an `ErrorState` (which also composes `Empty`), so don't hand-roll a retry empty.
+ * @bestPractice Set `level` to keep the document outline gapless where you place it - a full-page empty near an `h2` wants `level="3"`, but a nested one may need `"4"`.
+ * @category states
+ */
+export const EmptyState = ({ actions, description, icon, iconPlain, iconTone, level = "3", media, title, ...emptyProps }) => {
+    const hasDescription = description !== undefined && description !== null;
+    const hasActions = actions !== undefined && actions !== null;
+    const hasMedia = media !== undefined && media !== null;
+    let mediaNode = null;
+    if (hasMedia) {
+        mediaNode = _jsx(EmptyMedia, { children: media });
+    }
+    else if (icon) {
+        mediaNode = (_jsx(EmptyMedia, { icon: icon, ...(iconPlain === undefined ? {} : { plain: iconPlain }), ...(iconTone === undefined ? {} : { tone: iconTone }) }));
+    }
+    return (_jsxs(Empty, { "data-component": "empty-state", ...emptyProps, children: [_jsxs(EmptyHeader, { children: [mediaNode, _jsx(EmptyTitle, { level: level, children: title }), hasDescription ? (_jsx(EmptyDescription, { children: description })) : null] }), hasActions ? _jsx(EmptyActions, { children: actions }) : null] }));
+};

package/dist/compositions/empty-state.d.ts

@@ -0,0 +1 @@
+export { EmptyState, type EmptyStateProps, } from "./empty-state/empty-state-root.js";

package/dist/compositions/empty-state.js

@@ -0,0 +1 @@
+export { EmptyState, } from "./empty-state/empty-state-root.js";

package/dist/compositions/error-state/error-state-root.d.ts

@@ -0,0 +1,39 @@
+import type { LucideIcon } from "lucide-react";
+import type * as React from "react";
+import type { EmptyProps } from "../../components/empty/empty-root.js";
+import type { Tone } from "../../tokens/tone.js";
+/** ErrorState tone - the canon subset it maps onto an IconBox surface tone. */
+export type ErrorStateTone = Extract<Tone, "danger" | "info" | "neutral" | "warning">;
+export interface ErrorStateProps extends Omit<EmptyProps, "children" | "title"> {
+    /** Additional actions rendered alongside the retry button. */
+    actions?: React.ReactNode;
+    /** Icon shown above the title. Defaults based on `tone`. */
+    icon?: LucideIcon;
+    /** Supporting copy describing what went wrong. */
+    message?: React.ReactNode;
+    /** Called when the retry button is pressed. Omit to render no retry button. */
+    retry?: () => void;
+    /** Retry button label. Defaults to "Try again". */
+    retryLabel?: string;
+    /** Test id applied to the retry button, for Playwright targeting. */
+    retryTestId?: string;
+    /** Semantic tone driving the icon colour. Defaults to "danger". */
+    tone?: ErrorStateTone;
+    /** Heading text. Defaults to "Something went wrong". */
+    title?: React.ReactNode;
+}
+/**
+ * Generic error state, composed on `Empty`. Replaces the five per-feature
+ * "something went wrong" implementations with one primitive: an icon, a
+ * title, an optional message, and an optional retry action.
+ *
+ * @example
+ * ```tsx
+ * <ErrorState message={error.message} retry={() => refetch()} />
+ * ```
+ *
+ * @bestPractice `ErrorState` renders a failure UI (icon / title / message / retry) but does not catch errors - wrap the throwing subtree in an `ErrorBoundary` and render this in its `fallback`.
+ * @bestPractice Pass `retry` to show the retry button (omit it to hide); it's built on `Empty`, so `layout` / `minHeight` props pass straight through.
+ * @category states
+ */
+export declare const ErrorState: ({ actions, icon, message, retry, retryLabel, retryTestId, tone, title, ...props }: ErrorStateProps) => React.JSX.Element;

package/dist/compositions/error-state/error-state-root.js

@@ -0,0 +1,30 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { CircleAlert } from "lucide-react";
+import { Button } from "../../components/button.js";
+import { EmptyActions } from "../../components/empty/empty-actions.js";
+import { EmptyDescription } from "../../components/empty/empty-description.js";
+import { EmptyHeader } from "../../components/empty/empty-header.js";
+import { EmptyMedia } from "../../components/empty/empty-media.js";
+import { Empty } from "../../components/empty/empty-root.js";
+import { EmptyTitle } from "../../components/empty/empty-title.js";
+/**
+ * Generic error state, composed on `Empty`. Replaces the five per-feature
+ * "something went wrong" implementations with one primitive: an icon, a
+ * title, an optional message, and an optional retry action.
+ *
+ * @example
+ * ```tsx
+ * <ErrorState message={error.message} retry={() => refetch()} />
+ * ```
+ *
+ * @bestPractice `ErrorState` renders a failure UI (icon / title / message / retry) but does not catch errors - wrap the throwing subtree in an `ErrorBoundary` and render this in its `fallback`.
+ * @bestPractice Pass `retry` to show the retry button (omit it to hide); it's built on `Empty`, so `layout` / `minHeight` props pass straight through.
+ * @category states
+ */
+export const ErrorState = ({ actions, icon = CircleAlert, message, retry, retryLabel = "Try again", retryTestId, tone = "danger", title = "Something went wrong", ...props }) => {
+    const hasMessage = message !== undefined && message !== null;
+    const hasRetry = retry !== undefined;
+    const hasActions = hasRetry || (actions !== undefined && actions !== null);
+    return (_jsxs(Empty, { ...props, children: [_jsxs(EmptyHeader, { children: [_jsx(EmptyMedia, { icon: icon, plain: true, tone: tone }), _jsx(EmptyTitle, { children: title }), hasMessage ? _jsx(EmptyDescription, { children: message }) : null] }), hasActions ? (_jsxs(EmptyActions, { children: [hasRetry ? (_jsx(Button, { onClick: retry, ...(retryTestId === undefined ? {} : { testId: retryTestId }), tone: "neutral", emphasis: "soft", children: retryLabel })) : null, actions] })) : null] }));
+};

package/dist/compositions/error-state.d.ts

@@ -0,0 +1 @@
+export { ErrorState, type ErrorStateProps, type ErrorStateTone, } from "./error-state/error-state-root.js";

package/dist/compositions/error-state.js

@@ -0,0 +1 @@
+export { ErrorState, } from "./error-state/error-state-root.js";

package/dist/compositions/file-upload/file-upload-dropzone.d.ts

@@ -0,0 +1,52 @@
+import type { LucideIcon } from "lucide-react";
+import type { DragEvent, ReactNode, Ref } from "react";
+interface FileUploadDropzoneProps {
+    /** Children to render inside (overrides default content) */
+    children?: ReactNode;
+    /** Additional class names */
+    className?: string;
+    /** Secondary description text */
+    description?: string;
+    /** Whether the dropzone is disabled */
+    disabled?: boolean;
+    /** Icon to display (default: CloudUpload) */
+    icon?: LucideIcon;
+    /** Whether files are currently being dragged over */
+    dragging?: boolean;
+    /** Click handler to open file dialog */
+    onClick?: () => void;
+    /** Drag event handlers from useFileUpload */
+    onDragEnter?: (e: DragEvent<HTMLElement>) => void;
+    onDragLeave?: (e: DragEvent<HTMLElement>) => void;
+    onDragOver?: (e: DragEvent<HTMLElement>) => void;
+    onDrop?: (e: DragEvent<HTMLElement>) => void;
+    /** Ref for the dropzone element */
+    ref?: Ref<HTMLButtonElement>;
+    /** Primary text */
+    title?: string;
+}
+/**
+ * FileUploadDropzone - A drag-and-drop zone for file uploads.
+ * Use with the useFileUpload hook for full functionality.
+ *
+ * @example
+ * ```tsx
+ * const [{ isDragging }, actions] = useFileUpload();
+ *
+ * <FileUploadDropzone
+ *   dragging={isDragging}
+ *   onDragEnter={actions.handleDragEnter}
+ *   onDragLeave={actions.handleDragLeave}
+ *   onDragOver={actions.handleDragOver}
+ *   onDrop={actions.handleDrop}
+ *   onClick={actions.openFileDialog}
+ * />
+ * ```
+ *
+ * @bestPractice `FileUploadDropzone` is presentational - wire it to the `useFileUpload` hook for the actual file input, drag state, and file list; it stores nothing itself.
+ * @bestPractice Forward the hook's `handleDragEnter/Leave/Over/Drop` and drag state into `dragging` so the drag styling matches the real drop-target state.
+ * @bestPractice Keep `title`/`description` (accepted types, size limit) accurate - they are the zone's only affordance copy; override the whole body via `children` when needed.
+ * @category inputs
+ */
+export declare const FileUploadDropzone: ({ ref, dragging, disabled, icon, title, description, onDragEnter, onDragLeave, onDragOver, onDrop, onClick, className, children, }: FileUploadDropzoneProps) => import("react").JSX.Element;
+export {};