@instruments/materia-ui 0.1.0

package/dist/components/checkbox-field.d.ts

@@ -0,0 +1 @@
+export { CheckboxField, type CheckboxFieldProps, } from "./checkbox-field/checkbox-field-root.js";

package/dist/components/checkbox-field.js

@@ -0,0 +1 @@
+export { CheckboxField, } from "./checkbox-field/checkbox-field-root.js";

package/dist/components/checkbox.d.ts

@@ -0,0 +1 @@
+export { Checkbox, type CheckboxProps } from "./checkbox/checkbox-root.js";

package/dist/components/checkbox.js

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

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

@@ -0,0 +1,17 @@
+import * as React from "react";
+export interface CodeProps extends React.ComponentProps<"code"> {
+    /**
+     * Render a multi-line block (`<pre><code>`) instead of inline `<code>`. The
+     * block scrolls horizontally rather than wrapping. @default false
+     */
+    block?: boolean;
+}
+/**
+ * Monospace code - inline `<code>` by default (a muted, rounded chip sized to
+ * surrounding text), or a scrollable `<pre><code>` block when `block` is set.
+ * Token-styled and RSC-safe.
+ * @bestPractice Use inline `Code` for identifiers/values in a sentence and `block` for multi-line snippets - `Kbd` is for keyboard keys, not code.
+ * @bestPractice `block` renders `<pre><code>` that scrolls horizontally; add `whitespace-pre-wrap` via `className` only when wrapping beats scrolling (long prose-like messages).
+ * @category typography
+ */
+export declare const Code: ({ block, className, children, ...props }: CodeProps) => React.JSX.Element;

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

@@ -0,0 +1,17 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import * as React from "react";
+/**
+ * Monospace code - inline `<code>` by default (a muted, rounded chip sized to
+ * surrounding text), or a scrollable `<pre><code>` block when `block` is set.
+ * Token-styled and RSC-safe.
+ * @bestPractice Use inline `Code` for identifiers/values in a sentence and `block` for multi-line snippets - `Kbd` is for keyboard keys, not code.
+ * @bestPractice `block` renders `<pre><code>` that scrolls horizontally; add `whitespace-pre-wrap` via `className` only when wrapping beats scrolling (long prose-like messages).
+ * @category typography
+ */
+export const Code = ({ block = false, className, children, ...props }) => {
+    if (block) {
+        return (_jsx("pre", { className: cn("border-border bg-muted text-paragraph-sm overflow-x-auto rounded-lg border p-4 font-mono", className), "data-block": "true", "data-component": "code", children: _jsx("code", { ...props, children: children }) }));
+    }
+    return (_jsx("code", { className: cn("bg-muted text-paragraph-sm rounded-sm px-1 py-0.5 font-mono", className), "data-component": "code", ...props, children: children }));
+};

package/dist/components/code.d.ts

@@ -0,0 +1 @@
+export { Code, type CodeProps } from "./code/code-root.js";

package/dist/components/code.js

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

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

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

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

@@ -0,0 +1,22 @@
+import { defineAnatomy } from "../../tokens/anatomy.js";
+/**
+ * collapsibleAnatomy helper for CollapsibleAnatomy.
+ * Import from "@instruments/materia-ui/components/collapsible-anatomy".
+ */
+export const collapsibleAnatomy = defineAnatomy({
+    children: [
+        {
+            description: "Button to toggle content",
+            label: "CollapsibleTrigger",
+            slot: "collapsible-trigger",
+        },
+        {
+            description: "Collapsible content area",
+            label: "CollapsibleContent",
+            slot: "collapsible-content",
+        },
+    ],
+    description: "Expandable/collapsible content section",
+    label: "Collapsible",
+    slot: "collapsible",
+});

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

@@ -0,0 +1,9 @@
+import { Collapsible as CollapsiblePrimitive } from "@base-ui/react/collapsible";
+/**
+ * Collapsible body; kept mounted and height/opacity-animated through Base UI's
+ * panel height variable so it slides open and closed rather than snapping.
+ * Must render inside Collapsible.
+ */
+export declare const CollapsibleContent: ({ className, ...props }: Omit<CollapsiblePrimitive.Panel.Props, "className"> & {
+    className?: string;
+}) => import("react").JSX.Element;

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

@@ -0,0 +1,10 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Collapsible as CollapsiblePrimitive } from "@base-ui/react/collapsible";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/**
+ * Collapsible body; kept mounted and height/opacity-animated through Base UI's
+ * panel height variable so it slides open and closed rather than snapping.
+ * Must render inside Collapsible.
+ */
+export const CollapsibleContent = ({ className, ...props }) => (_jsx(CollapsiblePrimitive.Panel, { className: cn("transition-panel data-ending-style:transition-panel-close h-(--collapsible-panel-height) overflow-hidden ease-out data-ending-style:h-0 data-ending-style:opacity-0 data-ending-style:ease-out data-starting-style:h-0 data-starting-style:opacity-0 motion-reduce:transition-none", className), "data-component": "collapsible-content", "data-slot": "collapsible-content", keepMounted: true, ...props }));

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

@@ -0,0 +1,11 @@
+import { Collapsible as CollapsiblePrimitive } from "@base-ui/react/collapsible";
+/**
+ * Expand/collapse container that reveals its CollapsibleContent when open.
+ * Controlled via `open`/`onOpenChange` or uncontrolled via `defaultOpen`.
+ *
+ * @bestPractice Use `Collapsible` for a single expand/collapse region; reach for `Accordion` when you have a set of grouped items where selecting one can close the others.
+ * @bestPractice Compose `CollapsibleTrigger` + `CollapsibleContent` inside it - a bare child won't expand.
+ * @bestPractice Drive it uncontrolled with `defaultOpen`; only lift to `open`/`onOpenChange` when external state must sync (e.g. persisting the open panel).
+ * @category data
+ */
+export declare const Collapsible: ({ ...props }: CollapsiblePrimitive.Root.Props) => import("react").JSX.Element;

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

@@ -0,0 +1,13 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Collapsible as CollapsiblePrimitive } from "@base-ui/react/collapsible";
+/**
+ * Expand/collapse container that reveals its CollapsibleContent when open.
+ * Controlled via `open`/`onOpenChange` or uncontrolled via `defaultOpen`.
+ *
+ * @bestPractice Use `Collapsible` for a single expand/collapse region; reach for `Accordion` when you have a set of grouped items where selecting one can close the others.
+ * @bestPractice Compose `CollapsibleTrigger` + `CollapsibleContent` inside it - a bare child won't expand.
+ * @bestPractice Drive it uncontrolled with `defaultOpen`; only lift to `open`/`onOpenChange` when external state must sync (e.g. persisting the open panel).
+ * @category data
+ */
+export const Collapsible = ({ ...props }) => (_jsx(CollapsiblePrimitive.Root, { "data-component": "collapsible", "data-slot": "collapsible", ...props }));

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

@@ -0,0 +1,3 @@
+import { Collapsible as CollapsiblePrimitive } from "@base-ui/react/collapsible";
+/** Button that toggles the collapsible open/closed; use `render` to wrap a custom control. */
+export declare const CollapsibleTrigger: ({ ...props }: CollapsiblePrimitive.Trigger.Props) => import("react").JSX.Element;

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

@@ -0,0 +1,4 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Collapsible as CollapsiblePrimitive } from "@base-ui/react/collapsible";
+/** Button that toggles the collapsible open/closed; use `render` to wrap a custom control. */
+export const CollapsibleTrigger = ({ ...props }) => (_jsx(CollapsiblePrimitive.Trigger, { "data-component": "collapsible-trigger", "data-slot": "collapsible-trigger", ...props }));

package/dist/components/collapsible.d.ts

@@ -0,0 +1,4 @@
+export { CollapsibleContent } from "./collapsible/collapsible-content.js";
+export { Collapsible } from "./collapsible/collapsible-root.js";
+export { CollapsibleTrigger } from "./collapsible/collapsible-trigger.js";
+export { collapsibleAnatomy } from "./collapsible/collapsible-anatomy.js";

package/dist/components/collapsible.js

@@ -0,0 +1,4 @@
+export { CollapsibleContent } from "./collapsible/collapsible-content.js";
+export { Collapsible } from "./collapsible/collapsible-root.js";
+export { CollapsibleTrigger } from "./collapsible/collapsible-trigger.js";
+export { collapsibleAnatomy } from "./collapsible/collapsible-anatomy.js";

package/dist/components/color-wheel/color-wheel-root.d.ts

@@ -0,0 +1,17 @@
+import type { ColorWheelValue } from "../color-wheel/color-wheel-utils.js";
+export type { ColorWheelValue } from "../color-wheel/color-wheel-utils.js";
+export interface ColorWheelProps {
+    /** Fired on every pointer drag of the pad or hue arc with the updated HSL value. */
+    onChange: (value: ColorWheelValue) => void;
+    /** Current HSL selection; the picker is fully controlled and keeps no internal state. */
+    value: ColorWheelValue;
+}
+/**
+ * Concentric saturation/lightness pad + hue arc picker.
+ *
+ * @bestPractice `ColorWheel` is fully controlled - own the `ColorWheelValue` (`{h,s,l}`) and set it from `onChange`; it stores nothing internally, so dropping the update freezes the picker.
+ * @bestPractice Values are HSL (`h` 0–360, `s`/`l` 0–100), not hex - convert at your storage boundary; a hex string won't position the handles.
+ * @bestPractice `onChange` fires on every pointer drag and arrow-key step - throttle persistence/network writes downstream rather than reacting to each intermediate value.
+ * @category color
+ */
+export declare const ColorWheel: ({ value, onChange }: ColorWheelProps) => import("react").JSX.Element;

package/dist/components/color-wheel/color-wheel-root.js

@@ -0,0 +1,205 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { hslToHex } from "@instruments/colorscope/math";
+import { focusRing } from "@instruments/materia-ui/tokens/focus-ring";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { useCallback, useId, useMemo, useRef } from "react";
+import { ARC_PATH, ARC_STROKE_WIDTH, CENTER_X, CENTER_Y, CONTAINER_HEIGHT, CONTAINER_WIDTH, clampValue, getHueHandlePosition, getPadHandlePosition, normalizeHue, PAD_RADIUS, PAD_SIZE, pointerToHue, pointerToPadSL, SVG_VIEWBOX, } from "../color-wheel/color-wheel-utils.js";
+const SaturationPad = ({ handlers, hex, hue, lightness, onKeyDown, padHandle, padLeft, padRef, padTop, saturation, }) => (_jsxs("div", { "aria-label": "Saturation and lightness", "aria-valuemax": 100, "aria-valuemin": 0, "aria-valuenow": Math.round(saturation), "aria-valuetext": `Saturation ${Math.round(saturation)}%, lightness ${Math.round(lightness)}%`, className: cn("absolute touch-none rounded-full border border-black/8", focusRing()), onKeyDown: onKeyDown, onPointerCancel: handlers.handlePointerCancel, onPointerDown: handlers.handlePointerDown, onPointerMove: handlers.handlePointerMove, onPointerUp: handlers.handlePointerUp, ref: padRef, 
+    // A 2D saturation/lightness surface with layered gradient children and a
+    // draggable handle can't be expressed as a void <input type="range">;
+    // role="slider" keeps the a11y semantics on the custom graphic.
+    // oxlint-disable-next-line jsx-a11y/prefer-tag-over-role, react-doctor/prefer-tag-over-role
+    role: "slider", style: {
+        height: PAD_SIZE,
+        left: padLeft,
+        top: padTop,
+        width: PAD_SIZE,
+    }, tabIndex: 0, children: [_jsx("div", { className: "absolute inset-0 rounded-full", style: { backgroundColor: `hsl(${hue} 100% 50%)` } }), _jsx("div", { className: "absolute inset-0 rounded-full bg-linear-to-r/srgb from-white to-transparent" }), _jsx("div", { className: "absolute inset-0 rounded-full bg-linear-to-t/srgb from-black to-transparent" }), _jsx("div", { className: "absolute size-3.5 -translate-1/2 rounded-full border-2 border-white ring-1 ring-black/25", style: {
+                backgroundColor: hex,
+                left: `${padHandle.x}px`,
+                top: `${padHandle.y}px`,
+            } })] }));
+const HueArc = ({ gradientId, handlers, hex, hue, hueHandle, onKeyDown, svgRef, }) => (_jsxs(_Fragment, { children: [_jsxs("svg", { "aria-hidden": "true", className: "absolute inset-0 touch-none", onPointerCancel: handlers.handlePointerCancel, onPointerDown: handlers.handlePointerDown, onPointerMove: handlers.handlePointerMove, onPointerUp: handlers.handlePointerUp, ref: svgRef, style: { pointerEvents: "none" }, viewBox: SVG_VIEWBOX, children: [_jsx("defs", { children: _jsxs("linearGradient", { id: gradientId, x1: "0%", x2: "100%", y1: "0%", y2: "0%", children: [_jsx("stop", { offset: "0%", stopColor: "#ff3b30" }), _jsx("stop", { offset: "16%", stopColor: "#ff9500" }), _jsx("stop", { offset: "33%", stopColor: "#ffcc00" }), _jsx("stop", { offset: "50%", stopColor: "#34c759" }), _jsx("stop", { offset: "66%", stopColor: "#0a84ff" }), _jsx("stop", { offset: "83%", stopColor: "#5856d6" }), _jsx("stop", { offset: "100%", stopColor: "#ff2d55" })] }) }), _jsx("path", { d: ARC_PATH, fill: "none", stroke: `url(#${gradientId})`, strokeLinecap: "round", strokeWidth: ARC_STROKE_WIDTH, style: { pointerEvents: "stroke" } }), _jsx("circle", { cx: hueHandle.x, cy: hueHandle.y, fill: hex, r: "6", stroke: "white", strokeWidth: "2", style: { pointerEvents: "auto" } })] }), _jsx("div", { "aria-label": "Hue", "aria-valuemax": 360, "aria-valuemin": 0, "aria-valuenow": Math.round(hue), "aria-valuetext": `${Math.round(hue)} degrees`, className: cn("absolute size-4 rounded-full", focusRing()), onKeyDown: onKeyDown, 
+            // The hue handle rides a curved gradient arc rendered in SVG; a void
+            // <input type="range"> can't host that graphic, so role="slider" carries
+            // the a11y semantics on this operable overlay.
+            // oxlint-disable-next-line jsx-a11y/prefer-tag-over-role, react-doctor/prefer-tag-over-role
+            role: "slider", style: {
+                left: hueHandle.x,
+                pointerEvents: "none",
+                top: hueHandle.y,
+                transform: "translate(-50%, -50%)",
+            }, tabIndex: 0 })] }));
+/** Keyboard step for the S/L pad; returns the next value, or null to ignore. */
+const nextPadValueFromKey = (value, event) => {
+    const step = event.shiftKey ? 10 : 1;
+    switch (event.key) {
+        case "ArrowLeft": {
+            return { ...value, s: clampValue(value.s - step, 0, 100) };
+        }
+        case "ArrowRight": {
+            return { ...value, s: clampValue(value.s + step, 0, 100) };
+        }
+        case "ArrowUp": {
+            return { ...value, l: clampValue(value.l + step, 3, 97) };
+        }
+        case "ArrowDown": {
+            return { ...value, l: clampValue(value.l - step, 3, 97) };
+        }
+        case "Home": {
+            return { ...value, s: 0 };
+        }
+        case "End": {
+            return { ...value, s: 100 };
+        }
+        default: {
+            return null;
+        }
+    }
+};
+/** Keyboard step for the hue arc; returns the next value, or null to ignore. */
+const nextHueValueFromKey = (value, event) => {
+    const step = event.shiftKey ? 10 : 1;
+    switch (event.key) {
+        case "ArrowLeft":
+        case "ArrowDown": {
+            return { ...value, h: normalizeHue(value.h - step) };
+        }
+        case "ArrowRight":
+        case "ArrowUp": {
+            return { ...value, h: normalizeHue(value.h + step) };
+        }
+        default: {
+            return null;
+        }
+    }
+};
+/** Keyboard operability for the pad + hue arc; reuses the pointer state setter. */
+const useColorWheelKeyboard = (value, onChange) => {
+    const onPadKeyDown = useCallback((event) => {
+        const next = nextPadValueFromKey(value, event);
+        if (next === null) {
+            return;
+        }
+        event.preventDefault();
+        onChange(next);
+    }, [value, onChange]);
+    const onHueKeyDown = useCallback((event) => {
+        const next = nextHueValueFromKey(value, event);
+        if (next === null) {
+            return;
+        }
+        event.preventDefault();
+        onChange(next);
+    }, [value, onChange]);
+    return { onHueKeyDown, onPadKeyDown };
+};
+/** Pointer/drag interaction for the pad + hue arc. Logic is unchanged; it is
+ * grouped here so the component stays focused on rendering. */
+const useColorWheelInteraction = (value, onChange) => {
+    const isPadDraggingRef = useRef(false);
+    const isHueDraggingRef = useRef(false);
+    const padRef = useRef(null);
+    const svgRef = useRef(null);
+    // ── Pad pointer handlers ─────────────────────────────────────────────
+    const handlePadPointer = useCallback((clientX, clientY) => {
+        const pad = padRef.current;
+        if (!pad) {
+            return;
+        }
+        const rect = pad.getBoundingClientRect();
+        const { s, l } = pointerToPadSL(clientX, clientY, rect);
+        onChange({ ...value, l, s });
+    }, [value, onChange]);
+    const onPadPointerDown = useCallback((event) => {
+        event.preventDefault();
+        event.currentTarget.setPointerCapture(event.pointerId);
+        isPadDraggingRef.current = true;
+        handlePadPointer(event.clientX, event.clientY);
+    }, [handlePadPointer]);
+    const onPadPointerMove = useCallback((event) => {
+        if (!(isPadDraggingRef.current || event.buttons === 1)) {
+            return;
+        }
+        handlePadPointer(event.clientX, event.clientY);
+    }, [handlePadPointer]);
+    const onPadPointerUp = useCallback((event) => {
+        if (event.currentTarget.hasPointerCapture(event.pointerId)) {
+            event.currentTarget.releasePointerCapture(event.pointerId);
+        }
+        isPadDraggingRef.current = false;
+    }, []);
+    // ── Hue arc pointer handlers ─────────────────────────────────────────
+    const handleHuePointer = useCallback((clientX, clientY) => {
+        const svg = svgRef.current;
+        if (!svg) {
+            return;
+        }
+        const rect = svg.getBoundingClientRect();
+        const h = pointerToHue(clientX, clientY, rect);
+        onChange({ ...value, h });
+    }, [value, onChange]);
+    const onHuePointerDown = useCallback((event) => {
+        event.preventDefault();
+        event.currentTarget.setPointerCapture(event.pointerId);
+        isHueDraggingRef.current = true;
+        handleHuePointer(event.clientX, event.clientY);
+    }, [handleHuePointer]);
+    const onHuePointerMove = useCallback((event) => {
+        if (!(isHueDraggingRef.current || event.buttons === 1)) {
+            return;
+        }
+        handleHuePointer(event.clientX, event.clientY);
+    }, [handleHuePointer]);
+    const onHuePointerUp = useCallback((event) => {
+        if (event.currentTarget.hasPointerCapture(event.pointerId)) {
+            event.currentTarget.releasePointerCapture(event.pointerId);
+        }
+        isHueDraggingRef.current = false;
+    }, []);
+    const { onHueKeyDown, onPadKeyDown } = useColorWheelKeyboard(value, onChange);
+    const padHandlers = {
+        handlePointerCancel: () => {
+            isPadDraggingRef.current = false;
+        },
+        handlePointerDown: onPadPointerDown,
+        handlePointerMove: onPadPointerMove,
+        handlePointerUp: onPadPointerUp,
+    };
+    const hueHandlers = {
+        handlePointerCancel: () => {
+            isHueDraggingRef.current = false;
+        },
+        handlePointerDown: onHuePointerDown,
+        handlePointerMove: onHuePointerMove,
+        handlePointerUp: onHuePointerUp,
+    };
+    return {
+        hueHandlers,
+        onHueKeyDown,
+        onPadKeyDown,
+        padHandlers,
+        padRef,
+        svgRef,
+    };
+};
+/**
+ * Concentric saturation/lightness pad + hue arc picker.
+ *
+ * @bestPractice `ColorWheel` is fully controlled - own the `ColorWheelValue` (`{h,s,l}`) and set it from `onChange`; it stores nothing internally, so dropping the update freezes the picker.
+ * @bestPractice Values are HSL (`h` 0–360, `s`/`l` 0–100), not hex - convert at your storage boundary; a hex string won't position the handles.
+ * @bestPractice `onChange` fires on every pointer drag and arrow-key step - throttle persistence/network writes downstream rather than reacting to each intermediate value.
+ * @category color
+ */
+export const ColorWheel = ({ value, onChange }) => {
+    const hueGradientId = useId();
+    const { hueHandlers, onHueKeyDown, onPadKeyDown, padHandlers, padRef, svgRef, } = useColorWheelInteraction(value, onChange);
+    const hex = useMemo(() => hslToHex(value.h, value.s, value.l), [value.h, value.s, value.l]);
+    const padHandle = useMemo(() => getPadHandlePosition(value.s, value.l), [value.s, value.l]);
+    const hueHandle = useMemo(() => getHueHandlePosition(value.h), [value.h]);
+    // ── Pad position within the container ────────────────────────────────
+    const padLeft = CENTER_X - PAD_RADIUS;
+    const padTop = CENTER_Y - PAD_RADIUS;
+    return (_jsxs("div", { className: "relative", style: { height: CONTAINER_HEIGHT, width: CONTAINER_WIDTH }, children: [_jsx(SaturationPad, { handlers: padHandlers, hex: hex, hue: value.h, lightness: value.l, onKeyDown: onPadKeyDown, padHandle: padHandle, padLeft: padLeft, padRef: padRef, padTop: padTop, saturation: value.s }), _jsx(HueArc, { gradientId: hueGradientId, handlers: hueHandlers, hex: hex, hue: value.h, hueHandle: hueHandle, onKeyDown: onHueKeyDown, svgRef: svgRef })] }));
+};

package/dist/components/color-wheel/color-wheel-utils.d.ts

@@ -0,0 +1,59 @@
+/** HSL value used by the ColorWheel component. */
+export interface ColorWheelValue {
+    h: number;
+    l: number;
+    s: number;
+}
+/** Diameter of the saturation/lightness circular pad. */
+export declare const PAD_SIZE = 104;
+/** Radius of the pad circle. */
+export declare const PAD_RADIUS: number;
+/** Gap between pad edge and arc centerline. */
+export declare const ARC_GAP = 8;
+/** Radius of the hue arc (concentric with pad). */
+export declare const ARC_RADIUS: number;
+/** Stroke width of the hue arc. */
+export declare const ARC_STROKE_WIDTH = 8;
+/** Arc start angle in degrees (CW from 3 o'clock). */
+export declare const ARC_START_DEG = 10;
+/** Arc end angle in degrees (CW from 3 o'clock). */
+export declare const ARC_END_DEG = 170;
+/** Total container width - fits pad + arc overshoot on each side. */
+export declare const CONTAINER_WIDTH: number;
+/** Center X of both pad and arc within the container. */
+export declare const CENTER_X: number;
+/** Center Y of both pad and arc within the container. */
+export declare const CENTER_Y: number;
+/** Container height - from top to deepest arc point + handle radius. */
+export declare const CONTAINER_HEIGHT: number;
+/** SVG viewBox string for the overlay. */
+export declare const SVG_VIEWBOX = "0 0 130 123";
+/** Pre-computed SVG arc path (sweeps CW from startDeg to endDeg). */
+export declare const ARC_PATH: string;
+export declare const clampValue: (value: number, min: number, max: number) => number;
+export declare const normalizeHue: (hue: number) => number;
+export declare const clampPointToCircle: (x: number, y: number, radius: number) => {
+    x: number;
+    y: number;
+};
+/** Map hue (0-360) to an angle in degrees on the arc (CW from 3 o'clock). */
+export declare const hueToAngle: (hue: number) => number;
+/** Map an angle (degrees, CW from 3 o'clock) back to hue (0-360). */
+export declare const angleToHue: (angleDeg: number) => number;
+/** Get the pixel position of the pad handle from S/L values. */
+export declare const getPadHandlePosition: (saturation: number, lightness: number) => {
+    x: number;
+    y: number;
+};
+/** Get the SVG-space position of the hue handle on the arc. */
+export declare const getHueHandlePosition: (hue: number) => {
+    x: number;
+    y: number;
+};
+/** Convert a pointer event (relative to the pad element) to S/L values. */
+export declare const pointerToPadSL: (clientX: number, clientY: number, padRect: DOMRect) => {
+    l: number;
+    s: number;
+};
+/** Convert a pointer event (relative to the SVG element) to a hue value. */
+export declare const pointerToHue: (clientX: number, clientY: number, svgRect: DOMRect) => number;

package/dist/components/color-wheel/color-wheel-utils.js

@@ -0,0 +1,101 @@
+// ── Geometry constants ─────────────────────────────────────────────────
+/** Diameter of the saturation/lightness circular pad. */
+export const PAD_SIZE = 104;
+/** Radius of the pad circle. */
+export const PAD_RADIUS = PAD_SIZE / 2;
+/** Gap between pad edge and arc centerline. */
+export const ARC_GAP = 8;
+/** Radius of the hue arc (concentric with pad). */
+export const ARC_RADIUS = PAD_RADIUS + ARC_GAP;
+/** Stroke width of the hue arc. */
+export const ARC_STROKE_WIDTH = 8;
+/** Arc start angle in degrees (CW from 3 o'clock). */
+export const ARC_START_DEG = 10;
+/** Arc end angle in degrees (CW from 3 o'clock). */
+export const ARC_END_DEG = 170;
+/** Total container width - fits pad + arc overshoot on each side. */
+export const CONTAINER_WIDTH = 2 * (ARC_RADIUS + ARC_STROKE_WIDTH / 2) + 2;
+/** Center X of both pad and arc within the container. */
+export const CENTER_X = CONTAINER_WIDTH / 2;
+/** Center Y of both pad and arc within the container. */
+export const CENTER_Y = PAD_RADIUS + ARC_STROKE_WIDTH / 2 + 1;
+/** Container height - from top to deepest arc point + handle radius. */
+export const CONTAINER_HEIGHT = CENTER_Y + ARC_RADIUS + ARC_STROKE_WIDTH / 2 + 2;
+/** SVG viewBox string for the overlay. */
+export const SVG_VIEWBOX = `0 0 ${CONTAINER_WIDTH} ${CONTAINER_HEIGHT}`;
+// ── Pre-computed arc path ──────────────────────────────────────────────
+const startRad = (ARC_START_DEG * Math.PI) / 180;
+const endRad = (ARC_END_DEG * Math.PI) / 180;
+const arcStartX = CENTER_X + ARC_RADIUS * Math.cos(startRad);
+const arcStartY = CENTER_Y + ARC_RADIUS * Math.sin(startRad);
+const arcEndX = CENTER_X + ARC_RADIUS * Math.cos(endRad);
+const arcEndY = CENTER_Y + ARC_RADIUS * Math.sin(endRad);
+/** Pre-computed SVG arc path (sweeps CW from startDeg to endDeg). */
+export const ARC_PATH = `M ${arcStartX} ${arcStartY} A ${ARC_RADIUS} ${ARC_RADIUS} 0 0 1 ${arcEndX} ${arcEndY}`;
+// ── Pure helpers ───────────────────────────────────────────────────────
+export const clampValue = (value, min, max) => Math.min(max, Math.max(min, value));
+export const normalizeHue = (hue) => {
+    const normalized = hue % 360;
+    return normalized < 0 ? normalized + 360 : normalized;
+};
+export const clampPointToCircle = (x, y, radius) => {
+    const distance = Math.hypot(x, y);
+    if (distance <= radius || distance === 0) {
+        return { x, y };
+    }
+    const scale = radius / distance;
+    return { x: x * scale, y: y * scale };
+};
+// ── Angle/hue conversion ───────────────────────────────────────────────
+const ARC_SPAN_DEG = ARC_END_DEG - ARC_START_DEG;
+/** Map hue (0-360) to an angle in degrees on the arc (CW from 3 o'clock). */
+export const hueToAngle = (hue) => ARC_START_DEG + (normalizeHue(hue) / 360) * ARC_SPAN_DEG;
+/** Map an angle (degrees, CW from 3 o'clock) back to hue (0-360). */
+export const angleToHue = (angleDeg) => {
+    const clamped = clampValue(angleDeg, ARC_START_DEG, ARC_END_DEG);
+    return ((clamped - ARC_START_DEG) / ARC_SPAN_DEG) * 360;
+};
+// ── Handle positions (for rendering) ───────────────────────────────────
+/** Get the pixel position of the pad handle from S/L values. */
+export const getPadHandlePosition = (saturation, lightness) => {
+    const rawX = (saturation / 100) * PAD_SIZE;
+    const rawY = ((100 - lightness) / 100) * PAD_SIZE;
+    const clamped = clampPointToCircle(rawX - PAD_RADIUS, rawY - PAD_RADIUS, PAD_RADIUS);
+    return {
+        x: clamped.x + PAD_RADIUS,
+        y: clamped.y + PAD_RADIUS,
+    };
+};
+/** Get the SVG-space position of the hue handle on the arc. */
+export const getHueHandlePosition = (hue) => {
+    const angleDeg = hueToAngle(hue);
+    const angleRad = (angleDeg * Math.PI) / 180;
+    return {
+        x: CENTER_X + ARC_RADIUS * Math.cos(angleRad),
+        y: CENTER_Y + ARC_RADIUS * Math.sin(angleRad),
+    };
+};
+// ── Pointer → value conversion ─────────────────────────────────────────
+/** Convert a pointer event (relative to the pad element) to S/L values. */
+export const pointerToPadSL = (clientX, clientY, padRect) => {
+    const localX = clientX - padRect.left - PAD_RADIUS;
+    const localY = clientY - padRect.top - PAD_RADIUS;
+    const clamped = clampPointToCircle(localX, localY, PAD_RADIUS);
+    const xRatio = (clamped.x + PAD_RADIUS) / PAD_SIZE;
+    const yRatio = (clamped.y + PAD_RADIUS) / PAD_SIZE;
+    return {
+        l: clampValue((1 - yRatio) * 100, 3, 97),
+        s: clampValue(xRatio * 100, 0, 100),
+    };
+};
+/** Convert a pointer event (relative to the SVG element) to a hue value. */
+export const pointerToHue = (clientX, clientY, svgRect) => {
+    const localX = clientX - svgRect.left;
+    const localY = clientY - svgRect.top;
+    const dx = localX - CENTER_X;
+    const dy = localY - CENTER_Y;
+    const angleRad = Math.atan2(dy, dx);
+    const angleDeg = (angleRad * 180) / Math.PI;
+    const normalizedDeg = angleDeg < 0 ? angleDeg + 360 : angleDeg;
+    return angleToHue(normalizedDeg);
+};

package/dist/components/color-wheel.d.ts

@@ -0,0 +1,3 @@
+export type { ColorWheelProps, ColorWheelValue, } from "./color-wheel/color-wheel-root.js";
+export { ColorWheel } from "./color-wheel/color-wheel-root.js";
+export { CENTER_X as WHEEL_CENTER_X, CENTER_Y as WHEEL_CENTER_Y, } from "./color-wheel/color-wheel-utils.js";

package/dist/components/color-wheel.js

@@ -0,0 +1,3 @@
+"use client";
+export { ColorWheel } from "./color-wheel/color-wheel-root.js";
+export { CENTER_X as WHEEL_CENTER_X, CENTER_Y as WHEEL_CENTER_Y, } from "./color-wheel/color-wheel-utils.js";

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

@@ -0,0 +1,53 @@
+import type { ResponsiveSize } from "@instruments/materia-ui/tokens/size";
+import type * as React from "react";
+/** Combobox item type definition */
+export interface ComboboxItem {
+    label: string;
+    value: string;
+}
+export interface ComboboxVirtualizationOptions {
+    /** Enable virtualisation for large lists. */
+    enabled?: boolean;
+    /** Estimated row height in pixels. @default 40 */
+    estimateSizePx?: number;
+    /** Max height of the list in pixels. @default 300 */
+    maxHeightPx?: number;
+    /** Number of extra rows to render above/below. @default 8 */
+    overscan?: number;
+}
+export interface ComboboxProps {
+    /** Button class name */
+    buttonClassName?: string;
+    /** Class name for the popover content panel */
+    contentClassName?: string;
+    /** Test id for the trigger button */
+    "data-testid"?: string;
+    /** Whether disabled */
+    disabled?: boolean;
+    /** List of items */
+    items: ComboboxItem[];
+    /** Called with the selected value, or `""` when the selection is toggled off. */
+    onValueChange?: (value: string) => void;
+    /** Placeholder text @default "Select…" */
+    placeholder?: string;
+    /**
+     * Trigger size - a single token or a per-breakpoint object like
+     * `{ base: "sm", md: "xl" }`. Forwarded to the underlying Button. @default "xl"
+     */
+    size?: ResponsiveSize;
+    /** Selected value; provide (with `onValueChange`) for controlled use, omit for uncontrolled. */
+    value?: string;
+    /** Virtualisation settings for large item sets. */
+    virtualization?: ComboboxVirtualizationOptions;
+}
+/**
+ * Searchable select: a button trigger opening a filterable option list in a popover.
+ * Works controlled (`value` + `onValueChange`) or uncontrolled; supports virtualisation for large lists.
+ *
+ * @bestPractice Use `Combobox` when the user filters/searches a long list; use `Select` for a short closed list, or a domain variant like `CountryCombobox` for known sets.
+ * @bestPractice `onValueChange` fires with `""` when the current selection is toggled off - treat empty string as "cleared", not as a real value.
+ * @bestPractice For lists in the hundreds+, pass `virtualization={{ enabled: true }}` so only visible rows mount instead of every option.
+ * @bestPractice Provide `items` as `{ label, value }[]` - the visible text comes from `label` while selection is tracked by `value`.
+ * @category forms
+ */
+export declare const Combobox: ({ items, value, onValueChange, placeholder, buttonClassName, contentClassName, disabled, size, virtualization, "data-testid": dataTestId, }: ComboboxProps) => React.JSX.Element;