@instruments/materia-ui 0.1.0

package/dist/data/token-gallery.js

@@ -0,0 +1,518 @@
+/**
+ * Design-token gallery data for `@instruments/materia-ui`.
+ *
+ * The canonical, framework-agnostic description of the design system's visual
+ * tokens - colours, shadows, blurs, radii, the type ramp, and the motion scale.
+ * Each entry pairs a token's Tailwind utility with its semantic key, display
+ * name and resolved value, so a gallery can render the live token and label it
+ * without hardcoding anything.
+ *
+ * This is the single source shared by the package's own Storybook token gallery
+ * (`src/stories/design-tokens.stories.tsx`) and the MateriaUI documentation site
+ * (`apps/materia-ui`). It lives in the public `./data/*` export tree precisely so
+ * the site can import it across the package boundary - deep-importing
+ * `src/stories` would violate the layer doctrine the site demonstrates.
+ *
+ * Only pure data lives here; the Storybook preview components (swatch/shadow/blur
+ * cells) stay beside the story in `design-tokens.stories.helpers.tsx`.
+ *
+ * @module
+ */
+/** Look up a token by its `key`. Throws if the key is missing. */
+export const findByKey = (items, key) => {
+    const found = items.find((item) => item.key === key);
+    if (!found) {
+        throw new Error(`Missing token: ${key}`);
+    }
+    return found;
+};
+/** Core semantic surface + text colours (the everyday palette). */
+export const BASE_COLORS = [
+    { class: "bg-primary", key: "primary", name: "Primary", value: "#111827" },
+    {
+        class: "bg-secondary",
+        key: "secondary",
+        name: "Secondary",
+        value: "#f3f4f6",
+    },
+    { class: "bg-muted", key: "muted", name: "Muted", value: "#f3f4f6" },
+    { class: "bg-accent", key: "accent", name: "Accent", value: "#e5e7eb" },
+    {
+        class: "bg-destructive",
+        key: "destructive",
+        name: "Destructive",
+        value: "#dc2626",
+    },
+    { class: "bg-border", key: "border", name: "Border", value: "#e5e7eb" },
+];
+/** The neutral gray ramp (50 → 950). */
+export const GRAY_COLORS = [
+    { class: "bg-gray-50", key: "gray-50", name: "Gray 50", value: "#f9fafb" },
+    { class: "bg-gray-100", key: "gray-100", name: "Gray 100", value: "#f3f4f6" },
+    { class: "bg-gray-200", key: "gray-200", name: "Gray 200", value: "#e5e7eb" },
+    { class: "bg-gray-300", key: "gray-300", name: "Gray 300", value: "#d1d5db" },
+    { class: "bg-gray-400", key: "gray-400", name: "Gray 400", value: "#9ca3af" },
+    { class: "bg-gray-500", key: "gray-500", name: "Gray 500", value: "#6b7280" },
+    { class: "bg-gray-600", key: "gray-600", name: "Gray 600", value: "#4b5563" },
+    { class: "bg-gray-700", key: "gray-700", name: "Gray 700", value: "#374151" },
+    { class: "bg-gray-800", key: "gray-800", name: "Gray 800", value: "#1f2937" },
+    { class: "bg-gray-900", key: "gray-900", name: "Gray 900", value: "#111827" },
+    { class: "bg-gray-950", key: "gray-950", name: "Gray 950", value: "#030712" },
+];
+/** Status + brand families, each a soft / accent / foreground triad. */
+export const SEMANTIC_COLORS = [
+    {
+        class: "bg-brand-soft",
+        key: "brand-soft",
+        name: "Brand Soft",
+        value: "#fffef5",
+    },
+    {
+        class: "bg-brand-accent",
+        key: "brand-accent",
+        name: "Brand Accent",
+        value: "#facc15",
+    },
+    {
+        class: "bg-brand-foreground",
+        key: "brand-foreground",
+        name: "Brand FG",
+        value: "#1f2937",
+    },
+    {
+        class: "bg-affirmative-soft",
+        key: "affirmative-soft",
+        name: "Affirmative Soft",
+        value: "#f0fdf4",
+    },
+    {
+        class: "bg-affirmative-accent",
+        key: "affirmative-accent",
+        name: "Affirmative Accent",
+        value: "#16a34a",
+    },
+    {
+        class: "bg-affirmative-foreground",
+        key: "affirmative-foreground",
+        name: "Affirmative FG",
+        value: "#14532d",
+    },
+    {
+        class: "bg-warning-soft",
+        key: "warning-soft",
+        name: "Warning Soft",
+        value: "#fffbeb",
+    },
+    {
+        class: "bg-warning-accent",
+        key: "warning-accent",
+        name: "Warning Accent",
+        value: "#fcd34d",
+    },
+    {
+        class: "bg-warning-foreground",
+        key: "warning-foreground",
+        name: "Warning FG",
+        value: "#92400e",
+    },
+    {
+        class: "bg-error-soft",
+        key: "error-soft",
+        name: "Error Soft",
+        value: "#fef2f2",
+    },
+    {
+        class: "bg-error-accent",
+        key: "error-accent",
+        name: "Error Accent",
+        value: "#fca5a5",
+    },
+    {
+        class: "bg-error-foreground",
+        key: "error-foreground",
+        name: "Error FG",
+        value: "#991b1b",
+    },
+];
+/** Translucent black / white overlays across the opacity scale. */
+export const ALPHA_COLORS = [
+    {
+        class: "bg-black/5",
+        key: "black-5",
+        name: "Black 5%",
+        value: "rgba(0,0,0,0.05)",
+    },
+    {
+        class: "bg-black/10",
+        key: "black-10",
+        name: "Black 10%",
+        value: "rgba(0,0,0,0.10)",
+    },
+    {
+        class: "bg-black/20",
+        key: "black-20",
+        name: "Black 20%",
+        value: "rgba(0,0,0,0.20)",
+    },
+    {
+        class: "bg-black/30",
+        key: "black-30",
+        name: "Black 30%",
+        value: "rgba(0,0,0,0.30)",
+    },
+    {
+        class: "bg-black/50",
+        key: "black-50",
+        name: "Black 50%",
+        value: "rgba(0,0,0,0.50)",
+    },
+    {
+        class: "bg-black/70",
+        key: "black-70",
+        name: "Black 70%",
+        value: "rgba(0,0,0,0.70)",
+    },
+    {
+        class: "bg-white/5",
+        key: "white-5",
+        name: "White 5%",
+        value: "rgba(255,255,255,0.05)",
+    },
+    {
+        class: "bg-white/10",
+        key: "white-10",
+        name: "White 10%",
+        value: "rgba(255,255,255,0.10)",
+    },
+    {
+        class: "bg-white/20",
+        key: "white-20",
+        name: "White 20%",
+        value: "rgba(255,255,255,0.20)",
+    },
+    {
+        class: "bg-white/50",
+        key: "white-50",
+        name: "White 50%",
+        value: "rgba(255,255,255,0.50)",
+    },
+    {
+        class: "bg-white/70",
+        key: "white-70",
+        name: "White 70%",
+        value: "rgba(255,255,255,0.70)",
+    },
+];
+/** Box-shadow elevation ladder (gray-900 tinted, layered, with a 1px ring from `sm` up). */
+export const BOX_SHADOWS = [
+    {
+        class: "shadow-2xs",
+        key: "shadow-2xs",
+        name: "2xs",
+        value: "0 1px 1px 0 rgb(17 24 39 / 0.03)",
+    },
+    {
+        class: "shadow-xs",
+        key: "shadow-xs",
+        name: "xs",
+        value: "0 0 4px 0 rgb(17 24 39 / 0.04)",
+    },
+    {
+        class: "shadow-sm",
+        key: "shadow-sm",
+        name: "sm",
+        value: "5 layers to 0 18px 47px, plus 1px ring",
+    },
+    {
+        class: "shadow-md",
+        key: "shadow-md",
+        name: "md",
+        value: "5 layers to 0 17.54px 23.39px, plus 1px ring",
+    },
+    {
+        class: "shadow-lg",
+        key: "shadow-lg",
+        name: "lg",
+        value: "5 layers to 0 25px 50px, plus 1px ring",
+    },
+    {
+        class: "shadow-xl",
+        key: "shadow-xl",
+        name: "xl",
+        value: "5 layers to 0 40px 80px, plus 1px ring",
+    },
+    {
+        class: "shadow-2xl",
+        key: "shadow-2xl",
+        name: "2xl",
+        value: "5 layers to 0 60px 120px, plus 1px ring",
+    },
+    {
+        class: "shadow-3xl",
+        key: "shadow-3xl",
+        name: "3xl",
+        value: "5 layers to 0 80px 160px, plus 1px ring",
+    },
+    {
+        class: "shadow-4xl",
+        key: "shadow-4xl",
+        name: "4xl",
+        value: "5 layers to 0 100px 200px, plus 1px ring",
+    },
+];
+/** Inset (inner) shadow ladder (from Figma). */
+export const INSET_SHADOWS = [
+    {
+        class: "shadow-inner-2xs",
+        key: "shadow-inner-2xs",
+        name: "2xs",
+        value: "inset 0 1px 0 0 rgb(0 0 0 / 0.05)",
+    },
+    {
+        class: "shadow-inner-xs",
+        key: "shadow-inner-xs",
+        name: "xs",
+        value: "inset 0 1px 1px 0 rgb(0 0 0 / 0.05)",
+    },
+    {
+        class: "shadow-inner-sm",
+        key: "shadow-inner-sm",
+        name: "sm",
+        value: "inset 0 2px 4px 0 rgb(0 0 0 / 0.05)",
+    },
+];
+/** Drop-shadow (filter) ladder. */
+export const DROP_SHADOWS = [
+    {
+        class: "drop-shadow-xs",
+        key: "drop-shadow-xs",
+        name: "xs",
+        value: "0 1px 1px rgb(0 0 0 / 0.05)",
+    },
+    {
+        class: "drop-shadow-sm",
+        key: "drop-shadow-sm",
+        name: "sm",
+        value: "0 1px 2px rgb(0 0 0 / 0.15)",
+    },
+    {
+        class: "drop-shadow-md",
+        key: "drop-shadow-md",
+        name: "md",
+        value: "0 3px 3px rgb(0 0 0 / 0.12)",
+    },
+    {
+        class: "drop-shadow-lg",
+        key: "drop-shadow-lg",
+        name: "lg",
+        value: "0 4px 4px rgb(0 0 0 / 0.15)",
+    },
+    {
+        class: "drop-shadow-xl",
+        key: "drop-shadow-xl",
+        name: "xl",
+        value: "0 9px 7px rgb(0 0 0 / 0.1)",
+    },
+    {
+        class: "drop-shadow-2xl",
+        key: "drop-shadow-2xl",
+        name: "2xl",
+        value: "0 25px 25px rgb(0 0 0 / 0.15)",
+    },
+];
+/** Blur (filter) scale. */
+export const BLURS = [
+    { class: "blur-none", key: "blur-none", name: "none", value: "0" },
+    { class: "blur-xs", key: "blur-xs", name: "xs", value: "4px" },
+    { class: "blur-sm", key: "blur-sm", name: "sm", value: "8px" },
+    { class: "blur-md", key: "blur-md", name: "md", value: "12px" },
+    { class: "blur-lg", key: "blur-lg", name: "lg", value: "16px" },
+    { class: "blur-xl", key: "blur-xl", name: "xl", value: "24px" },
+    { class: "blur-2xl", key: "blur-2xl", name: "2xl", value: "40px" },
+    { class: "blur-3xl", key: "blur-3xl", name: "3xl", value: "64px" },
+];
+/** Backdrop-blur scale (from Figma - mirrors the blur scale). */
+export const BACKDROP_BLURS = [
+    {
+        class: "backdrop-blur-none",
+        key: "backdrop-blur-none",
+        name: "none",
+        value: "0",
+    },
+    {
+        class: "backdrop-blur-xs",
+        key: "backdrop-blur-xs",
+        name: "xs",
+        value: "4px",
+    },
+    {
+        class: "backdrop-blur-sm",
+        key: "backdrop-blur-sm",
+        name: "sm",
+        value: "8px",
+    },
+    {
+        class: "backdrop-blur-md",
+        key: "backdrop-blur-md",
+        name: "md",
+        value: "12px",
+    },
+    {
+        class: "backdrop-blur-lg",
+        key: "backdrop-blur-lg",
+        name: "lg",
+        value: "16px",
+    },
+    {
+        class: "backdrop-blur-xl",
+        key: "backdrop-blur-xl",
+        name: "xl",
+        value: "24px",
+    },
+    {
+        class: "backdrop-blur-2xl",
+        key: "backdrop-blur-2xl",
+        name: "2xl",
+        value: "40px",
+    },
+    {
+        class: "backdrop-blur-3xl",
+        key: "backdrop-blur-3xl",
+        name: "3xl",
+        value: "64px",
+    },
+];
+/**
+ * The radius ladder (2xs → 5xl) plus the dedicated `rounded-modal` (36px) and
+ * `rounded-full`. The system's surface-weight story reads 16 inner · 24 card ·
+ * 36 dialog: `rounded-2xl` (16px) for inner elements, `rounded-3xl` (24px) for
+ * cards, and `rounded-modal` (36px) for dialogs.
+ */
+export const RADII = [
+    { class: "rounded-2xs", key: "rounded-2xs", name: "2xs", value: "1px" },
+    { class: "rounded-xs", key: "rounded-xs", name: "xs", value: "4px" },
+    { class: "rounded-sm", key: "rounded-sm", name: "sm", value: "6px" },
+    { class: "rounded-md", key: "rounded-md", name: "md", value: "8px" },
+    { class: "rounded-lg", key: "rounded-lg", name: "lg", value: "10px" },
+    { class: "rounded-xl", key: "rounded-xl", name: "xl", value: "12px" },
+    { class: "rounded-2xl", key: "rounded-2xl", name: "2xl", value: "16px" },
+    { class: "rounded-3xl", key: "rounded-3xl", name: "3xl", value: "24px" },
+    { class: "rounded-4xl", key: "rounded-4xl", name: "4xl", value: "36px" },
+    { class: "rounded-5xl", key: "rounded-5xl", name: "5xl", value: "40px" },
+    {
+        class: "rounded-modal",
+        key: "rounded-modal",
+        name: "modal",
+        value: "36px",
+    },
+    { class: "rounded-full", key: "rounded-full", name: "full", value: "9999px" },
+];
+/** The full type ramp, ordered display-first (title) down to `2xs`. */
+export const TYPE_RAMP = [
+    {
+        class: "text-title",
+        cssVar: "--text-title",
+        key: "title",
+        name: "Title",
+        size: "3.75rem (60px)",
+    },
+    {
+        class: "text-heading-lg",
+        cssVar: "--text-heading-lg",
+        key: "heading-lg",
+        name: "Heading Large",
+        size: "3rem (48px)",
+    },
+    {
+        class: "text-heading",
+        cssVar: "--text-heading",
+        key: "heading",
+        name: "Heading",
+        size: "2.25rem (36px)",
+    },
+    {
+        class: "text-heading-sm",
+        cssVar: "--text-heading-sm",
+        key: "heading-sm",
+        name: "Heading Small",
+        size: "1.875rem (30px)",
+    },
+    {
+        class: "text-subheading-lg",
+        cssVar: "--text-subheading-lg",
+        key: "subheading-lg",
+        name: "Subheading Large",
+        size: "1.5rem (24px)",
+    },
+    {
+        class: "text-subheading",
+        cssVar: "--text-subheading",
+        key: "subheading",
+        name: "Subheading",
+        size: "1.25rem (20px)",
+    },
+    {
+        class: "text-paragraph-lg",
+        cssVar: "--text-paragraph-lg",
+        key: "paragraph-lg",
+        name: "Paragraph Large",
+        size: "1.125rem (18px)",
+    },
+    {
+        class: "text-paragraph",
+        cssVar: "--text-paragraph",
+        key: "paragraph",
+        name: "Paragraph",
+        size: "1rem (16px)",
+    },
+    {
+        class: "text-paragraph-sm",
+        cssVar: "--text-paragraph-sm",
+        key: "paragraph-sm",
+        name: "Paragraph Small",
+        size: "0.875rem (14px)",
+    },
+    {
+        class: "text-caption",
+        cssVar: "--text-caption",
+        key: "caption",
+        name: "Caption",
+        size: "0.75rem (12px)",
+    },
+    {
+        class: "text-2xs",
+        cssVar: "--text-2xs",
+        key: "2xs",
+        name: "2xs",
+        size: "0.6875rem (11px)",
+    },
+];
+/** The duration scale, instant → slow. Mirrors the canonical `durations` in tokens/motion.ts. */
+export const DURATIONS = [
+    { cssVar: "--duration-instant", key: "instant", ms: 0, name: "instant" },
+    { cssVar: "--duration-quick", key: "quick", ms: 120, name: "quick" },
+    { cssVar: "--duration-normal", key: "normal", ms: 220, name: "normal" },
+    { cssVar: "--duration-moderate", key: "moderate", ms: 400, name: "moderate" },
+    { cssVar: "--duration-slow", key: "slow", ms: 1000, name: "slow" },
+];
+/** The three curves. Mirrors the canonical `easings` in tokens/motion.ts. */
+export const EASINGS = [
+    {
+        cssVar: "--ease-out",
+        curve: "cubic-bezier(0.22, 1, 0.36, 1)",
+        key: "out",
+        name: "out",
+    },
+    {
+        cssVar: "--ease-in-out",
+        curve: "cubic-bezier(0.77, 0, 0.175, 1)",
+        key: "in-out",
+        name: "in-out",
+    },
+    {
+        cssVar: "--ease-sheet",
+        curve: "cubic-bezier(0.32, 0.72, 0, 1)",
+        key: "sheet",
+        name: "sheet",
+    },
+];

package/dist/hooks/use-breakpoint.d.ts

@@ -0,0 +1,12 @@
+import type { Breakpoint } from "../tokens/breakpoint.js";
+export { BREAKPOINT_VALUES, BREAKPOINTS, type Breakpoint, } from "../tokens/breakpoint.js";
+/**
+ * Returns true when the viewport is at or above the specified breakpoint.
+ *
+ * @example
+ * ```tsx
+ * const isDesktop = useBreakpoint("lg");
+ * const isTabletUp = useBreakpoint("md");
+ * ```
+ */
+export declare const useBreakpoint: (breakpoint: Exclude<Breakpoint, "base">) => boolean;

package/dist/hooks/use-breakpoint.js

@@ -0,0 +1,17 @@
+"use client";
+import { useMediaQuery } from "usehooks-ts";
+import { BREAKPOINT_VALUES } from "../tokens/breakpoint.js";
+// Re-export for convenience
+export { BREAKPOINT_VALUES, BREAKPOINTS, } from "../tokens/breakpoint.js";
+/**
+ * Returns true when the viewport is at or above the specified breakpoint.
+ *
+ * @example
+ * ```tsx
+ * const isDesktop = useBreakpoint("lg");
+ * const isTabletUp = useBreakpoint("md");
+ * ```
+ */
+export const useBreakpoint = (breakpoint) => useMediaQuery(`(min-width: ${BREAKPOINT_VALUES[breakpoint]}px)`, {
+    initializeWithValue: false,
+});

package/dist/hooks/use-controllable-state.d.ts

@@ -0,0 +1,17 @@
+import type { StateUpdate } from "../utils/resolve-state-update.js";
+interface UseControllableStateOptions<T> {
+    /** Starting value when uncontrolled. Read once, like `useState`'s initial value. */
+    defaultValue: T;
+    /** Called with the resolved value on every set, controlled or not. */
+    onChange?: ((value: T) => void) | undefined;
+    /** Controlled value. `undefined` means uncontrolled; `null` counts as controlled. */
+    value?: T | undefined;
+}
+/**
+ * A value that is controlled when `value` is defined and held internally
+ * otherwise. The setter takes a value or an updater (resolved against the
+ * current value), stores it only when uncontrolled, and always calls
+ * `onChange`, even when the value is unchanged. `T` must not be a function type.
+ */
+export declare const useControllableState: <T>({ defaultValue, onChange, value, }: UseControllableStateOptions<T>) => readonly [T, (update: StateUpdate<T>) => void];
+export {};

package/dist/hooks/use-controllable-state.js

@@ -0,0 +1,22 @@
+"use client";
+import { useCallback, useState } from "react";
+import { resolveStateUpdate } from "../utils/resolve-state-update.js";
+/**
+ * A value that is controlled when `value` is defined and held internally
+ * otherwise. The setter takes a value or an updater (resolved against the
+ * current value), stores it only when uncontrolled, and always calls
+ * `onChange`, even when the value is unchanged. `T` must not be a function type.
+ */
+export const useControllableState = ({ defaultValue, onChange, value, }) => {
+    const [internalValue, setInternalValue] = useState(defaultValue);
+    const isControlled = value !== undefined;
+    const currentValue = isControlled ? value : internalValue;
+    const setValue = useCallback((update) => {
+        const next = resolveStateUpdate(update, currentValue);
+        if (!isControlled) {
+            setInternalValue(next);
+        }
+        onChange?.(next);
+    }, [currentValue, isControlled, onChange]);
+    return [currentValue, setValue];
+};

package/dist/hooks/use-debounced-value.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Debounces a reactive value, updating only after the specified delay
+ * has elapsed since the last change.
+ *
+ * Useful for deferring expensive operations (e.g., search API calls)
+ * until the user stops typing.
+ *
+ * @param value - The source value to debounce
+ * @param delay - Debounce delay in milliseconds
+ * @returns The debounced value, which trails behind the source by `delay` ms
+ */
+export declare const useDebouncedValue: <T>(value: T, delay: number) => T;

package/dist/hooks/use-debounced-value.js

@@ -0,0 +1,25 @@
+"use client";
+import { useEffect, useState } from "react";
+/**
+ * Debounces a reactive value, updating only after the specified delay
+ * has elapsed since the last change.
+ *
+ * Useful for deferring expensive operations (e.g., search API calls)
+ * until the user stops typing.
+ *
+ * @param value - The source value to debounce
+ * @param delay - Debounce delay in milliseconds
+ * @returns The debounced value, which trails behind the source by `delay` ms
+ */
+export const useDebouncedValue = (value, delay) => {
+    const [debouncedValue, setDebouncedValue] = useState(value);
+    useEffect(() => {
+        const timer = setTimeout(() => {
+            setDebouncedValue(value);
+        }, delay);
+        return () => {
+            clearTimeout(timer);
+        };
+    }, [value, delay]);
+    return debouncedValue;
+};

package/dist/hooks/use-drag-scroll.d.ts

@@ -0,0 +1,40 @@
+import type { MouseEvent, PointerEvent } from "react";
+/** Which way a drag moves the scroller. */
+export type DragScrollAxis = "horizontal" | "vertical";
+export interface DragScrollOptions {
+    /**
+     * Pointer travel, in pixels, before a press becomes a drag. Below it, a
+     * press on a button or link inside is an ordinary click.
+     * @default 8
+     */
+    activationDistance?: number;
+    /** Off leaves the scroller to its native gestures alone. @default true */
+    enabled?: boolean;
+    /** Presses starting inside these never drag. */
+    ignoreSelector?: string;
+}
+/**
+ * Click-and-drag scrolling for a scroller used with a mouse. A press can
+ * start on a chip or a link inside: under the activation distance it stays a
+ * click; past it the content follows the pointer and the click the release
+ * would produce is swallowed. Touch keeps its native swipe.
+ *
+ * The pointer is never captured. Capture retargets the release's click at the
+ * scroller, so links and buttons inside would silently stop working. Moves
+ * are tracked on the window instead, which also keeps a drag alive once the
+ * pointer leaves the frame.
+ *
+ * Spread `handlers` on the element inside the scroller that holds the content.
+ * Adapted from @patternmode/scrollframe.
+ *
+ * @example
+ * const { dragging, handlers } = useDragScroll(viewport, "horizontal");
+ * <Box {...handlers}>{chips}</Box>
+ */
+export declare const useDragScroll: (viewport: HTMLElement | null, axis: DragScrollAxis, { activationDistance, enabled, ignoreSelector, }?: DragScrollOptions) => {
+    dragging: boolean;
+    handlers: {
+        onClickCapture: (event: MouseEvent<HTMLElement>) => void;
+        onPointerDownCapture: (event: PointerEvent<HTMLElement>) => void;
+    };
+};