@instruments/materia-ui 0.1.0

package/dist/components/sheet/sheet-anatomy.d.ts

@@ -0,0 +1,5 @@
+/**
+ * sheetAnatomy helper for SheetAnatomy.
+ * Import from "@instruments/materia-ui/components/sheet-anatomy".
+ */
+export declare const sheetAnatomy: import("../../tokens/anatomy.js").ComponentAnatomy;

package/dist/components/sheet/sheet-anatomy.js

@@ -0,0 +1,49 @@
+import { defineAnatomy } from "../../tokens/anatomy.js";
+/**
+ * sheetAnatomy helper for SheetAnatomy.
+ * Import from "@instruments/materia-ui/components/sheet-anatomy".
+ */
+export const sheetAnatomy = defineAnatomy({
+    children: [
+        {
+            description: "Element that opens sheet",
+            label: "SheetTrigger",
+            slot: "sheet-trigger",
+        },
+        {
+            children: [
+                {
+                    description: "Top section with title/description",
+                    label: "SheetHeader",
+                    slot: "sheet-header",
+                },
+                {
+                    description: "Sheet heading",
+                    label: "SheetTitle",
+                    slot: "sheet-title",
+                },
+                {
+                    description: "Sheet description text",
+                    label: "SheetDescription",
+                    slot: "sheet-description",
+                },
+                {
+                    description: "Bottom section for actions",
+                    label: "SheetFooter",
+                    slot: "sheet-footer",
+                },
+                {
+                    description: "Close button",
+                    label: "SheetClose",
+                    slot: "sheet-close",
+                },
+            ],
+            description: "Sheet panel container",
+            label: "SheetContent",
+            slot: "sheet-content",
+        },
+    ],
+    description: "Slide-out panel from screen edge",
+    label: "Sheet",
+    slot: "sheet",
+});

package/dist/components/sheet/sheet-close.d.ts

@@ -0,0 +1,5 @@
+/**
+ * SheetClose closes the sheet when triggered.
+ * Import from "@instruments/materia-ui/components/sheet".
+ */
+export declare const SheetClose: (props: Omit<import("@base-ui/react").DialogCloseProps, "ref"> & import("react").RefAttributes<HTMLButtonElement>) => import("react").ReactElement;

package/dist/components/sheet/sheet-close.js

@@ -0,0 +1,10 @@
+import { Dialog as DialogPrimitive } from "@base-ui/react/dialog";
+import { makeOverlayClose } from "../overlay-primitives.js";
+/**
+ * SheetClose closes the sheet when triggered.
+ * Import from "@instruments/materia-ui/components/sheet".
+ */
+export const SheetClose = makeOverlayClose(DialogPrimitive.Close, {
+    component: "sheet-close",
+    slot: "sheet-close",
+});

package/dist/components/sheet/sheet-content.d.ts

@@ -0,0 +1,14 @@
+import { Dialog as DialogPrimitive } from "@base-ui/react/dialog";
+import type { ComponentProps } from "react";
+type SheetSide = "top" | "right" | "bottom" | "left";
+type SheetContentProps = Omit<ComponentProps<typeof DialogPrimitive.Popup>, "className"> & {
+    className?: string;
+    /** Side from which sheet slides in. */
+    side?: SheetSide;
+};
+/**
+ * Main content area of the sheet. Slides in from the specified side.
+ * Import from "@instruments/materia-ui/components/sheet".
+ */
+export declare const SheetContent: ({ className, children, side, ...props }: SheetContentProps) => import("react").JSX.Element;
+export {};

package/dist/components/sheet/sheet-content.js

@@ -0,0 +1,16 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Dialog as DialogPrimitive } from "@base-ui/react/dialog";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { XIcon } from "lucide-react";
+import { Button } from "../button.js";
+import { SheetOverlay } from "../sheet/sheet-overlay.js";
+import { SheetPortal } from "../sheet/sheet-portal.js";
+/**
+ * Main content area of the sheet. Slides in from the specified side.
+ * Import from "@instruments/materia-ui/components/sheet".
+ */
+export const SheetContent = ({ className, children, side = "right", ...props }) => (_jsxs(SheetPortal, { children: [_jsx(SheetOverlay, {}), _jsxs(DialogPrimitive.Popup, { className: cn("bg-background data-closed:animate-out data-open:animate-in data-closed:duration-normal data-open:duration-moderate fixed z-50 flex flex-col gap-4 rounded-3xl border px-4 shadow-lg transition ease-in-out dark:shadow-none", side === "right" &&
+                "data-closed:slide-out-to-right data-open:slide-in-from-right inset-y-3 right-3 w-3/4 sm:max-w-sm", side === "left" &&
+                "data-closed:slide-out-to-left data-open:slide-in-from-left inset-y-3 left-3 w-3/4 sm:max-w-sm", side === "top" &&
+                "data-closed:slide-out-to-top data-open:slide-in-from-top inset-x-3 top-3 h-auto", side === "bottom" &&
+                "data-closed:slide-out-to-bottom data-open:slide-in-from-bottom inset-x-3 bottom-3 h-auto", className), "data-component": "sheet-content", "data-slot": "sheet-content", ...props, children: [children, _jsx(DialogPrimitive.Close, { render: _jsx(Button, { "aria-label": "Close", className: "absolute top-4 right-4", "data-component": "sheet-close", "data-slot": "sheet-close", emphasis: "soft", icon: XIcon, size: "icon-sm", tone: "neutral" }) })] })] }));

package/dist/components/sheet/sheet-description.d.ts

@@ -0,0 +1,7 @@
+/**
+ * SheetDescription renders supporting text for the sheet.
+ * Import from "@instruments/materia-ui/components/sheet".
+ */
+export declare const SheetDescription: ({ className: incoming, ...props }: Omit<Omit<import("@base-ui/react").DialogDescriptionProps, "ref"> & import("react").RefAttributes<HTMLParagraphElement>, "className"> & {
+    className?: string;
+}) => import("react").ReactElement;

package/dist/components/sheet/sheet-description.js

@@ -0,0 +1,11 @@
+import { Dialog as DialogPrimitive } from "@base-ui/react/dialog";
+import { OVERLAY_DESCRIPTION } from "../../tokens/overlay-styles.js";
+import { makeOverlayDescription } from "../overlay-primitives.js";
+/**
+ * SheetDescription renders supporting text for the sheet.
+ * Import from "@instruments/materia-ui/components/sheet".
+ */
+export const SheetDescription = makeOverlayDescription(DialogPrimitive.Description, {
+    className: OVERLAY_DESCRIPTION,
+    slot: "sheet-description",
+});

package/dist/components/sheet/sheet-footer.d.ts

@@ -0,0 +1,6 @@
+import type * as React from "react";
+/**
+ * SheetFooter section for actions.
+ * Import from "@instruments/materia-ui/components/sheet".
+ */
+export declare const SheetFooter: ({ className, ...props }: React.ComponentProps<"div">) => React.JSX.Element;

package/dist/components/sheet/sheet-footer.js

@@ -0,0 +1,8 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { Flex } from "../flex.js";
+/**
+ * SheetFooter section for actions.
+ * Import from "@instruments/materia-ui/components/sheet".
+ */
+export const SheetFooter = ({ className, ...props }) => (_jsx(Flex, { className: cn("mt-auto py-4", className), direction: "column", gap: "xs", "data-component": "sheet-footer", "data-slot": "sheet-footer", ...props }));

package/dist/components/sheet/sheet-header.d.ts

@@ -0,0 +1,6 @@
+import type * as React from "react";
+/**
+ * SheetHeader section (title/description area).
+ * Import from "@instruments/materia-ui/components/sheet".
+ */
+export declare const SheetHeader: ({ className, ...props }: React.ComponentProps<"div">) => React.JSX.Element;

package/dist/components/sheet/sheet-header.js

@@ -0,0 +1,8 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { Flex } from "../flex.js";
+/**
+ * SheetHeader section (title/description area).
+ * Import from "@instruments/materia-ui/components/sheet".
+ */
+export const SheetHeader = ({ className, ...props }) => (_jsx(Flex, { className: cn("gap-1.5 py-4", className), direction: "column", "data-component": "sheet-header", "data-slot": "sheet-header", ...props }));

package/dist/components/sheet/sheet-overlay.d.ts

@@ -0,0 +1,9 @@
+import { Dialog as DialogPrimitive } from "@base-ui/react/dialog";
+import type { ComponentProps } from "react";
+/**
+ * SheetOverlay renders the scrim behind the sheet.
+ * Import from "@instruments/materia-ui/components/sheet".
+ */
+export declare const SheetOverlay: ({ className, ...props }: Omit<ComponentProps<typeof DialogPrimitive.Backdrop>, "className"> & {
+    className?: string;
+}) => import("react").JSX.Element;

package/dist/components/sheet/sheet-overlay.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Dialog as DialogPrimitive } from "@base-ui/react/dialog";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { OVERLAY_SCRIM_GLASS } from "../../tokens/overlay-styles.js";
+/**
+ * SheetOverlay renders the scrim behind the sheet.
+ * Import from "@instruments/materia-ui/components/sheet".
+ */
+export const SheetOverlay = ({ className, ...props }) => (_jsx(DialogPrimitive.Backdrop, { className: cn(OVERLAY_SCRIM_GLASS, className), "data-component": "sheet-overlay", "data-slot": "sheet-overlay", ...props }));

package/dist/components/sheet/sheet-portal.d.ts

@@ -0,0 +1,5 @@
+/**
+ * SheetPortal renders sheet content into a portal.
+ * Import from "@instruments/materia-ui/components/sheet".
+ */
+export declare const SheetPortal: (props: Omit<import("@base-ui/react").DialogPortalProps, "ref"> & import("react").RefAttributes<HTMLDivElement>) => import("react").ReactElement;

package/dist/components/sheet/sheet-portal.js

@@ -0,0 +1,10 @@
+import { Dialog as DialogPrimitive } from "@base-ui/react/dialog";
+import { makeOverlayPortal } from "../overlay-primitives.js";
+/**
+ * SheetPortal renders sheet content into a portal.
+ * Import from "@instruments/materia-ui/components/sheet".
+ */
+export const SheetPortal = makeOverlayPortal(DialogPrimitive.Portal, {
+    component: "sheet-portal",
+    slot: "sheet-portal",
+});

package/dist/components/sheet/sheet-root.d.ts

@@ -0,0 +1,10 @@
+import { Dialog as DialogPrimitive } from "@base-ui/react/dialog";
+/**
+ * Root component for a sheet (side panel). Manages open/closed state and accessibility.
+ * Import from "@instruments/materia-ui/components/sheet".
+ *
+ * @bestPractice Use `Sheet` for a simple edge panel holding a focused form / settings; a drag-to-dismiss bottom sheet is a `Drawer`, and nested panels are a `Sidepanel`.
+ * @bestPractice Set the entry edge via `SheetContent` `side`; always render a `SheetTitle` (wrap in `sr-only` if hidden) so the panel is announced.
+ * @category overlays
+ */
+export declare const Sheet: (props: DialogPrimitive.Root.Props<unknown>) => import("react").ReactElement;

package/dist/components/sheet/sheet-root.js

@@ -0,0 +1,14 @@
+import { Dialog as DialogPrimitive } from "@base-ui/react/dialog";
+import { makeOverlayRoot } from "../overlay-primitives.js";
+/**
+ * Root component for a sheet (side panel). Manages open/closed state and accessibility.
+ * Import from "@instruments/materia-ui/components/sheet".
+ *
+ * @bestPractice Use `Sheet` for a simple edge panel holding a focused form / settings; a drag-to-dismiss bottom sheet is a `Drawer`, and nested panels are a `Sidepanel`.
+ * @bestPractice Set the entry edge via `SheetContent` `side`; always render a `SheetTitle` (wrap in `sr-only` if hidden) so the panel is announced.
+ * @category overlays
+ */
+export const Sheet = makeOverlayRoot(DialogPrimitive.Root, {
+    component: "sheet",
+    slot: "sheet",
+});

package/dist/components/sheet/sheet-title.d.ts

@@ -0,0 +1,7 @@
+/**
+ * SheetTitle renders the heading for the sheet.
+ * Import from "@instruments/materia-ui/components/sheet".
+ */
+export declare const SheetTitle: ({ className: incoming, ...props }: Omit<Omit<import("@base-ui/react").DialogTitleProps, "ref"> & import("react").RefAttributes<HTMLHeadingElement>, "className"> & {
+    className?: string;
+}) => import("react").ReactElement;

package/dist/components/sheet/sheet-title.js

@@ -0,0 +1,11 @@
+import { Dialog as DialogPrimitive } from "@base-ui/react/dialog";
+import { OVERLAY_TITLE } from "../../tokens/overlay-styles.js";
+import { makeOverlayTitle } from "../overlay-primitives.js";
+/**
+ * SheetTitle renders the heading for the sheet.
+ * Import from "@instruments/materia-ui/components/sheet".
+ */
+export const SheetTitle = makeOverlayTitle(DialogPrimitive.Title, {
+    className: OVERLAY_TITLE,
+    slot: "sheet-title",
+});

package/dist/components/sheet/sheet-trigger.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Button that opens the sheet when clicked.
+ * Import from "@instruments/materia-ui/components/sheet".
+ */
+export declare const SheetTrigger: (props: import("@base-ui/react").DialogTriggerProps<unknown> & import("react").RefAttributes<HTMLElement>) => import("react").ReactElement;

package/dist/components/sheet/sheet-trigger.js

@@ -0,0 +1,10 @@
+import { Dialog as DialogPrimitive } from "@base-ui/react/dialog";
+import { makeOverlayTrigger } from "../overlay-primitives.js";
+/**
+ * Button that opens the sheet when clicked.
+ * Import from "@instruments/materia-ui/components/sheet".
+ */
+export const SheetTrigger = makeOverlayTrigger(DialogPrimitive.Trigger, {
+    component: "sheet-trigger",
+    slot: "sheet-trigger",
+});

package/dist/components/sheet.d.ts

@@ -0,0 +1,16 @@
+export { SheetClose } from "./sheet/sheet-close.js";
+export { SheetContent } from "./sheet/sheet-content.js";
+export { SheetDescription } from "./sheet/sheet-description.js";
+export { SheetFooter } from "./sheet/sheet-footer.js";
+export { SheetHeader } from "./sheet/sheet-header.js";
+export { SheetOverlay } from "./sheet/sheet-overlay.js";
+export { SheetPortal } from "./sheet/sheet-portal.js";
+/**
+ * Sheet (side panel) primitives built on Base UI Dialog.
+ *
+ * Import from "@instruments/materia-ui/components/sheet".
+ */
+export { Sheet } from "./sheet/sheet-root.js";
+export { SheetTitle } from "./sheet/sheet-title.js";
+export { SheetTrigger } from "./sheet/sheet-trigger.js";
+export { sheetAnatomy } from "./sheet/sheet-anatomy.js";

package/dist/components/sheet.js

@@ -0,0 +1,17 @@
+"use client";
+export { SheetClose } from "./sheet/sheet-close.js";
+export { SheetContent } from "./sheet/sheet-content.js";
+export { SheetDescription } from "./sheet/sheet-description.js";
+export { SheetFooter } from "./sheet/sheet-footer.js";
+export { SheetHeader } from "./sheet/sheet-header.js";
+export { SheetOverlay } from "./sheet/sheet-overlay.js";
+export { SheetPortal } from "./sheet/sheet-portal.js";
+/**
+ * Sheet (side panel) primitives built on Base UI Dialog.
+ *
+ * Import from "@instruments/materia-ui/components/sheet".
+ */
+export { Sheet } from "./sheet/sheet-root.js";
+export { SheetTitle } from "./sheet/sheet-title.js";
+export { SheetTrigger } from "./sheet/sheet-trigger.js";
+export { sheetAnatomy } from "./sheet/sheet-anatomy.js";

package/dist/components/shimmer/shimmer-root.d.ts

@@ -0,0 +1,67 @@
+import type { MotionValue } from "motion/react";
+/** Shimmer colour variant configurations */
+export type ShimmerVariant = "light" | "dark" | "inverted" | "metallic";
+/** Text elements the shimmer can render as. */
+export type ShimmerTag = "div" | "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "p" | "span";
+export interface ShimmerProps {
+    /** HTML element to render as. Defaults to "span" */
+    as?: ShimmerTag;
+    /** Text content to apply shimmer effect to */
+    children: string;
+    /** Additional CSS classes */
+    className?: string;
+    /** Animation duration in seconds. Defaults to 1.2 (2.4 for `"metallic"`) */
+    duration?: number;
+    /**
+     * External 0-100 driver for the band's position: 100 is the band off one
+     * edge, 0 off the other. When given, the Shimmer doesn't animate itself
+     * (`duration`, `repeat` and `repeatDelay` are ignored), so several lines can
+     * share one sweep. Reduced motion still wins.
+     */
+    progress?: MotionValue<number>;
+    /** Number of times to repeat the animation. Defaults to Infinity */
+    repeat?: number;
+    /** Delay between repeats in seconds. Defaults to 0 (3.6 for `"metallic"`) */
+    repeatDelay?: number;
+    /** Spread of shimmer gradient in pixels per character. Defaults to 2.5. Ignored by `"metallic"`. */
+    spread?: number;
+    /** Colour variant. Defaults to "light" */
+    variant?: ShimmerVariant;
+}
+/**
+ * Animated shimmer effect for text. Creates a gradient sweep animation.
+ *
+ * Variants:
+ * - `"light"` (default): muted foreground → muted highlight (dark text on light bg)
+ * - `"dark"`: gray-400 → foreground (darker sweep on light bg)
+ * - `"inverted"`: white text on dark backgrounds
+ * - `"metallic"`: chrome text for dark surfaces, with a slow champagne-to-steel sheen and a pause between sweeps
+ *
+ * @example
+ * ```tsx
+ * // Infinite shimmer (default)
+ * <Shimmer>Loading...</Shimmer>
+ *
+ * // Limited repeats for thinking indicators
+ * <Shimmer repeat={2} repeatDelay={0.25}>Analyzing data</Shimmer>
+ *
+ * // Inverted variant for dark backgrounds
+ * <Shimmer variant="inverted">Processing</Shimmer>
+ *
+ * // Metallic chrome text on a dark surface
+ * <Shimmer variant="metallic">Premium</Shimmer>
+ *
+ * // Several lines sharing one sweep, driven from outside
+ * const progress = useMotionValue(100);
+ * <Shimmer progress={progress} variant="metallic">First line</Shimmer>
+ * <Shimmer progress={progress} variant="metallic">Second line</Shimmer>
+ * ```
+ *
+ * @bestPractice Reach for `Shimmer` for in-progress *text* (a "Thinking…"/"Analyzing" sweep); `Shine` is an occasional attention flick on a surface, and `Skeleton` is a layout-shaped content placeholder.
+ * @bestPractice `children` must be a plain string - the sweep is a `bg-clip-text` gradient sized from character count, so element children won't clip correctly.
+ * @bestPractice Under reduced motion every variant renders its static base with no sweep. For finite "thinking" states set `repeat` (e.g. `repeat={2}`) rather than leaving the default infinite loop running.
+ * @bestPractice `variant="metallic"` is built for dark surfaces only - on a light background the chrome ramp loses contrast. Its own `duration` and `repeatDelay` defaults apply only when you pass neither.
+ * @bestPractice To sweep several lines in step, pass them one shared `progress` motion value (0-100) and drive it yourself; a Shimmer given `progress` never animates on its own.
+ * @category motion
+ */
+export declare const Shimmer: ({ children, as: Component, className, duration, progress, spread, repeat, repeatDelay, variant, }: ShimmerProps) => import("react").JSX.Element;

package/dist/components/shimmer/shimmer-root.js

@@ -0,0 +1,148 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { useMotionTemplate, useMotionValue, useReducedMotion, } from "motion/react";
+import * as m from "motion/react-m";
+import { useMemo } from "react";
+/** Colour tokens for each flat variant using semantic design tokens */
+const SHIMMER_COLORS = {
+    dark: {
+        // No semantic equivalent for gray-400, using raw token
+        base: "var(--color-gray-400)",
+        highlight: "var(--color-foreground)",
+    },
+    inverted: {
+        // White text on dark backgrounds
+        base: "rgba(255, 255, 255, 0.85)",
+        highlight: "rgba(255, 255, 255, 1)",
+    },
+    light: {
+        base: "var(--color-muted-foreground)",
+        highlight: "var(--color-muted)",
+    },
+};
+/**
+ * Metallic base: a vertical chrome ramp that never reads darker than gray-400,
+ * so the text stays legible on dark surfaces even at rest.
+ */
+const METALLIC_BASE = "linear-gradient(in oklab 180deg, oklab(78% -0.004 -0.020) 0%, oklab(91% -0.003 -0.014) 45%, oklab(64% -0.004 -0.020) 55%, oklab(82% -0.004 -0.020) 78%, oklab(92% -0.003 -0.014) 100%)";
+/**
+ * Metallic sheen: a band 28% of the text's width at 105° (champagne edge,
+ * white-silver peak, steel-blue edge). Painted on a layer 250% of the text's
+ * width, so the band sits at 44.4% to 55.6% of that layer.
+ */
+const METALLIC_SHEEN = "linear-gradient(in oklab 105deg, oklab(0% 0 0 / 0%) 44.4%, oklab(88% 0.012 0.070 / 75%) 47.6%, oklab(99% -0.002 -0.008 / 95%) 50%, oklab(82% -0.012 -0.060 / 70%) 52.4%, oklab(0% 0 0 / 0%) 55.6%)";
+/** Sweep timing used when the caller passes nothing, per variant family. */
+const FLAT_TIMING = { duration: 1.2, repeatDelay: 0 };
+const METALLIC_TIMING = { duration: 2.4, repeatDelay: 3.6 };
+/** Motion components for the text elements the shimmer can render as. */
+const MOTION_TAGS = {
+    div: m.div,
+    h1: m.h1,
+    h2: m.h2,
+    h3: m.h3,
+    h4: m.h4,
+    h5: m.h5,
+    h6: m.h6,
+    p: m.p,
+    span: m.span,
+};
+/** Background layers for a variant: base only when at rest, base + band when sweeping. */
+const getShimmerPaint = ({ spreadPx, sweeping, variant, }) => {
+    if (variant === "metallic") {
+        return sweeping
+            ? {
+                backgroundImage: `${METALLIC_SHEEN}, ${METALLIC_BASE}`,
+                backgroundRepeat: "no-repeat, no-repeat",
+                backgroundSize: "250% 100%, 100% 100%",
+            }
+            : {
+                backgroundImage: METALLIC_BASE,
+                backgroundRepeat: "no-repeat",
+                backgroundSize: "100% 100%",
+            };
+    }
+    const colors = SHIMMER_COLORS[variant];
+    const base = `linear-gradient(${colors.base}, ${colors.base})`;
+    return sweeping
+        ? {
+            backgroundImage: `linear-gradient(90deg, transparent calc(50% - ${spreadPx}px), ${colors.highlight} 50%, transparent calc(50% + ${spreadPx}px)), ${base}`,
+            backgroundRepeat: "no-repeat, padding-box",
+        }
+        : { backgroundImage: base, backgroundRepeat: "no-repeat" };
+};
+/** Band position at the start and end of a self-driven sweep. */
+const SWEEP_FROM = { backgroundPosition: "100% center" };
+const SWEEP_TO = { backgroundPosition: "0% center" };
+/** Sweep timing: the caller's values, else the variant family's defaults. */
+const getSweepTransition = ({ duration, repeat, repeatDelay, variant, }) => {
+    const timing = variant === "metallic" ? METALLIC_TIMING : FLAT_TIMING;
+    return {
+        duration: duration ?? timing.duration,
+        ease: "linear",
+        // Motion's repeat = additional plays after initial, so repeat - 1
+        repeat: repeat === Number.POSITIVE_INFINITY ? repeat : Math.max(0, repeat - 1),
+        repeatDelay: repeatDelay ?? timing.repeatDelay,
+    };
+};
+/**
+ * Animated shimmer effect for text. Creates a gradient sweep animation.
+ *
+ * Variants:
+ * - `"light"` (default): muted foreground → muted highlight (dark text on light bg)
+ * - `"dark"`: gray-400 → foreground (darker sweep on light bg)
+ * - `"inverted"`: white text on dark backgrounds
+ * - `"metallic"`: chrome text for dark surfaces, with a slow champagne-to-steel sheen and a pause between sweeps
+ *
+ * @example
+ * ```tsx
+ * // Infinite shimmer (default)
+ * <Shimmer>Loading...</Shimmer>
+ *
+ * // Limited repeats for thinking indicators
+ * <Shimmer repeat={2} repeatDelay={0.25}>Analyzing data</Shimmer>
+ *
+ * // Inverted variant for dark backgrounds
+ * <Shimmer variant="inverted">Processing</Shimmer>
+ *
+ * // Metallic chrome text on a dark surface
+ * <Shimmer variant="metallic">Premium</Shimmer>
+ *
+ * // Several lines sharing one sweep, driven from outside
+ * const progress = useMotionValue(100);
+ * <Shimmer progress={progress} variant="metallic">First line</Shimmer>
+ * <Shimmer progress={progress} variant="metallic">Second line</Shimmer>
+ * ```
+ *
+ * @bestPractice Reach for `Shimmer` for in-progress *text* (a "Thinking…"/"Analyzing" sweep); `Shine` is an occasional attention flick on a surface, and `Skeleton` is a layout-shaped content placeholder.
+ * @bestPractice `children` must be a plain string - the sweep is a `bg-clip-text` gradient sized from character count, so element children won't clip correctly.
+ * @bestPractice Under reduced motion every variant renders its static base with no sweep. For finite "thinking" states set `repeat` (e.g. `repeat={2}`) rather than leaving the default infinite loop running.
+ * @bestPractice `variant="metallic"` is built for dark surfaces only - on a light background the chrome ramp loses contrast. Its own `duration` and `repeatDelay` defaults apply only when you pass neither.
+ * @bestPractice To sweep several lines in step, pass them one shared `progress` motion value (0-100) and drive it yourself; a Shimmer given `progress` never animates on its own.
+ * @category motion
+ */
+export const Shimmer = ({ children, as: Component = "span", className, duration, progress, spread = 2.5, repeat = Number.POSITIVE_INFINITY, repeatDelay, variant = "light", }) => {
+    const MotionDiv = MOTION_TAGS[Component];
+    const sweeping = useReducedMotion() !== true;
+    const isDriven = progress !== undefined;
+    // useMotionTemplate needs a source on every render; this one idles at "band
+    // off the first edge" and is only read when no external driver is given.
+    const idleProgress = useMotionValue(100);
+    const backgroundPosition = useMotionTemplate `${progress ?? idleProgress}% center`;
+    const dynamicSpread = useMemo(() => (children?.length ?? 0) * spread, [children, spread]);
+    const shimmerStyle = getShimmerPaint({
+        spreadPx: dynamicSpread,
+        sweeping,
+        variant,
+    });
+    if (sweeping && isDriven) {
+        shimmerStyle.backgroundPosition = backgroundPosition;
+    }
+    const selfAnimates = sweeping && !isDriven;
+    return (_jsx(MotionDiv, { animate: selfAnimates ? SWEEP_TO : false, className: cn("inline-block bg-clip-text text-transparent", sweeping && variant !== "metallic" && "bg-size-shimmer", className), initial: selfAnimates ? SWEEP_FROM : false, style: shimmerStyle, transition: getSweepTransition({
+            duration,
+            repeat,
+            repeatDelay,
+            variant,
+        }), children: children }));
+};

package/dist/components/shimmer.d.ts

@@ -0,0 +1,2 @@
+export type { ShimmerProps, ShimmerVariant } from "./shimmer/shimmer-root.js";
+export { Shimmer } from "./shimmer/shimmer-root.js";

package/dist/components/shimmer.js

@@ -0,0 +1 @@
+export { Shimmer } from "./shimmer/shimmer-root.js";

package/dist/components/shine/shine-root.d.ts

@@ -0,0 +1,50 @@
+import type { ReactNode } from "react";
+export interface ShineProps {
+    /** Drives fade in/out of the shine */
+    visible?: boolean | undefined;
+    /** Border radius of the sweep container (defaults to fully round) */
+    radius?: number | string | undefined;
+    /** Positional overrides forwarded to the sweep container */
+    className?: string | undefined;
+    /**
+     * When provided, Shine wraps `children` in a relative container.
+     * When omitted, Shine assumes the nearest ancestor is already `position: relative`.
+     */
+    children?: ReactNode | undefined;
+    /**
+     * Run a single diagonal pass, then hide. Use for entrance cues.
+     * When false (default), the sweep loops with a rest interval.
+     */
+    playOnce?: boolean | undefined;
+    /** Fires after a `playOnce` sweep finishes (and the overlay has faded out). */
+    onPlayComplete?: (() => void) | undefined;
+    /** Override the default one-pass / loop sweep duration in seconds. */
+    duration?: number | undefined;
+}
+/**
+ * A subtle diagonal specular sweep for drawing attention to interactive
+ * surfaces. Unlike a skeleton shimmer, Shine runs as an occasional flick
+ * with rest between passes - one quick highlight every few seconds - so it
+ * reads as "this surface is alive" rather than "content is loading".
+ *
+ * Pass `playOnce` for a single entrance sweep (then it fades out).
+ *
+ * Two usage shapes:
+ *   1. Wrapper - pass `children` and Shine wraps them in a relative box.
+ *   2. Overlay - render without children inside an existing relative parent.
+ *
+ * Uses `mix-blend-mode: soft-light` so the highlight harmonizes with the
+ * underlying colour instead of painting pure white.
+ *
+ * Honours `prefers-reduced-motion` - renders nothing when motion is reduced
+ * (a static band would read as a permanent artefact, not a cue). When
+ * `visible` flips to `false`, the sweep fades out then unmounts so its rAF
+ * loop stops.
+ *
+ * @bestPractice Use `Shine` for a periodic "this surface is alive" flick on an interactive element - not for loading; a continuous text sweep is `Shimmer` and a content placeholder is `Skeleton`.
+ * @bestPractice Use `playOnce` for entrance choreography that should not loop.
+ * @bestPractice Either pass `children` (Shine wraps them in a relative box) or render it bare inside an existing `position: relative` parent - otherwise the sweep has nothing to overlay.
+ * @bestPractice Needs `ReducedMotionProvider`; under reduced motion it renders nothing (a static band would look like a permanent artefact), so don't rely on it as persistent decoration.
+ * @category motion
+ */
+export declare const Shine: ({ visible, radius, className, children, playOnce, onPlayComplete, duration, }: ShineProps) => import("react").JSX.Element;