@phreshos/react-ui 0.1.36 → 0.1.38

package/dist/slider.js

@@ -1,25 +1,33 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-// Base UI accepts direction directly; React Aria derives these keys from locale.
+// Base UI accepts an explicit direction; React Aria derives slider geometry
+// from the locale, which cannot follow a React UI direction boundary.
 import { Slider as BaseSlider } from "@base-ui/react/slider";
 import { DirectionProvider as BaseDirectionProvider } from "@base-ui/react/direction-provider";
 import { forwardRef, useEffect, useId, useRef, useState } from "react";
-import { controlFontWeight, controlOpacity, fieldStyle, useControlTheme } from "./control.js";
-import { resolveDirection, useDirection } from "./direction.js";
-/** One numeric value with pointer, touch, keyboard, and form support. */
-export const Slider = forwardRef(function Slider({ label, description, name, form, disabled, size, color, style, orientation = "horizontal", value, defaultValue, minValue = 0, maxValue = 100, step = 1, formatOptions, onChange, onChangeEnd, ...properties }, ref) {
-    const theme = useControlTheme({ size, color });
+import { controlFontWeight, controlOpacity, transition, useControlMetrics } from "./control/control.js";
+import { fieldStyle } from "./control/field.js";
+import { lightColor } from "./foundation/color.js";
+import { resolveDirection, useDirection } from "./foundation/direction.js";
+import { SurfaceView, dimmedClass } from "./surface/surface.js";
+/**
+ * One numeric value, drawn as a long Switch: a recessed bed, a raised fill in
+ * the owner's color up to the thumb, and the Switch thumb dragged along it.
+ */
+export const Slider = forwardRef(function Slider({ label, description, name, form, disabled, size, color = "primary", style, className, orientation = "horizontal", value, defaultValue, minValue = 0, maxValue = 100, step = 1, formatOptions, onChange, onChangeEnd, material, ...properties }, ref) {
+    const metrics = useControlMetrics(size);
+    const { colors } = metrics.visual;
     const direction = resolveDirection(properties.dir, useDirection());
     const descriptionId = useId();
     const input = useRef(null);
     const initialValue = useRef(defaultValue ?? minValue);
     const [uncontrolledValue, setUncontrolledValue] = useState(initialValue.current);
-    const [hovered, setHovered] = useState(false);
     const vertical = orientation === "vertical";
-    const diameter = theme.indicatorSize;
-    const rail = Math.max(4, Math.round(diameter / 3));
+    // The Switch's proportions: its bed height, and a thumb inset by the same gap.
+    const bed = metrics.indicator;
+    const inset = 3;
+    const thumb = bed - inset * 2;
     const describedBy = [properties["aria-describedby"], description != null ? descriptionId : null].filter(Boolean).join(" ") || undefined;
     const controlled = value !== undefined;
-    const resolvedValue = controlled ? value : uncontrolledValue;
     useEffect(() => {
         const formElement = input.current?.form;
         if (controlled || formElement == null)
@@ -28,44 +36,37 @@ export const Slider = forwardRef(function Slider({ label, description, name, for
         formElement.addEventListener("reset", reset);
         return () => formElement.removeEventListener("reset", reset);
     }, [controlled]);
-    const root = _jsxs(BaseSlider.Root, { ...properties, ref: ref, value: resolvedValue, min: minValue, max: maxValue, step: step, name: name, form: form, disabled: disabled, orientation: orientation, format: formatOptions, onValueChange: next => {
-            if (!controlled)
-                setUncontrolledValue(next);
-            onChange?.(next);
-        }, onValueCommitted: next => onChangeEnd?.(next), style: fieldStyle(theme, disabled, style), children: [_jsxs("div", { style: { display: "flex", alignItems: "baseline", justifyContent: "space-between", gap: theme.gap }, children: [label != null && _jsx(BaseSlider.Label, { style: { fontWeight: controlFontWeight }, children: label }), _jsx(BaseSlider.Value, { style: { fontVariantNumeric: "tabular-nums", opacity: controlOpacity.secondary } })] }), _jsx(BaseSlider.Control, { style: {
-                    position: "relative",
-                    display: "flex",
-                    alignItems: "center",
-                    justifyContent: "center",
-                    touchAction: "none",
-                    userSelect: "none",
-                    width: vertical ? theme.height : "100%",
-                    height: vertical ? theme.height * 4 : theme.height
-                }, children: _jsxs(BaseSlider.Track, { style: {
-                        position: "relative",
-                        width: vertical ? rail : "100%",
-                        height: vertical ? "100%" : rail,
-                        borderRadius: rail,
-                        background: theme.paints.subtle.rest.background
-                    }, children: [_jsx(BaseSlider.Indicator, { style: {
-                                ...theme.transition,
-                                borderRadius: rail,
-                                background: theme.paints.palette.rest.background
-                            } }), _jsx(BaseSlider.Thumb, { inputRef: input, "aria-label": properties["aria-label"], "aria-labelledby": properties["aria-labelledby"], "aria-describedby": describedBy, onPointerEnter: () => setHovered(true), onPointerLeave: () => setHovered(false), style: state => {
-                                const paint = state.dragging ? theme.paints.palette.pressed : hovered ? theme.paints.palette.hover : theme.paints.palette.rest;
-                                return {
-                                    ...theme.transition,
-                                    width: diameter,
-                                    height: diameter,
-                                    borderRadius: "50%",
-                                    boxSizing: "border-box",
-                                    background: paint.color,
-                                    border: `${Math.max(1, diameter / 6)}px solid ${paint.background}`,
-                                    outline: state.focused ? `1px solid ${theme.focusColor}` : "none",
-                                    outlineOffset: 1,
-                                    cursor: state.disabled ? "not-allowed" : state.dragging ? "grabbing" : "grab",
-                                    transform: `scale(${state.dragging ? 0.92 : hovered ? 1.08 : 1})`
-                                };
-                            } })] }) }), description != null && _jsx("span", { id: descriptionId, style: { fontSize: "0.92em", opacity: controlOpacity.secondary }, children: description })] });
-    return _jsx(BaseDirectionProvider, { direction: direction, children: root });
+    return _jsx(BaseDirectionProvider, { direction: direction, children: _jsxs(BaseSlider.Root, { ...properties, ref: ref, className: dimmedClass(disabled ?? false, className), value: controlled ? value : uncontrolledValue, min: minValue, max: maxValue, step: step, name: name, form: form, disabled: disabled, orientation: orientation, format: formatOptions, onValueChange: next => {
+                if (!controlled)
+                    setUncontrolledValue(next);
+                onChange?.(next);
+            }, onValueCommitted: next => onChangeEnd?.(next), style: fieldStyle(metrics, style), children: [_jsxs("div", { style: { display: "flex", alignItems: "baseline", justifyContent: "space-between", gap: metrics.gap }, children: [label != null && _jsx(BaseSlider.Label, { style: { fontWeight: controlFontWeight }, children: label }), _jsx(BaseSlider.Value, { style: { fontVariantNumeric: "tabular-nums", opacity: controlOpacity.secondary } })] }), _jsx(SurfaceView, { as: "div", color: "background", depth: "recessed", material: material, radius: "full", style: {
+                        display: "flex",
+                        boxSizing: "border-box",
+                        // The thumb center travels between the bed ends minus half a thumb,
+                        // so the thumb keeps the Switch inset at both ends.
+                        paddingBlock: vertical ? inset + thumb / 2 : inset,
+                        paddingInline: vertical ? inset : inset + thumb / 2,
+                        width: vertical ? bed : "100%",
+                        height: vertical ? metrics.height * 4 : bed
+                    }, children: _jsx(BaseSlider.Control, { style: { position: "relative", flex: 1, touchAction: "none", userSelect: "none" }, children: _jsxs(BaseSlider.Track, { style: { position: "relative", width: "100%", height: "100%" }, children: [_jsx(BaseSlider.Indicator, { render: (fill, _state) => _jsx(SurfaceView, { ...fill, ref: fill.ref, as: "div", color: color, material: material, shadow: false, radius: "full", style: {
+                                            ...fill.style,
+                                            position: "absolute",
+                                            boxSizing: "content-box",
+                                            // The fill starts at the bed's end and wraps the thumb with the
+                                            // bed's inset, like an enabled Switch.
+                                            ...(vertical
+                                                ? { insetInlineStart: -inset, width: bed, marginBottom: -(inset + thumb / 2), paddingTop: thumb + inset * 2 }
+                                                : { top: -inset, height: bed, marginInlineStart: -(inset + thumb / 2), paddingInlineEnd: thumb + inset * 2 })
+                                        } }) }), _jsx(BaseSlider.Thumb, { inputRef: input, "aria-label": properties["aria-label"], "aria-labelledby": properties["aria-labelledby"], "aria-describedby": describedBy, render: (native, state) => _jsx(SurfaceView, { ...native, ref: native.ref, as: "div", 
+                                        // A thumb is lit from above in every Theme.
+                                        color: lightColor(colors), radius: "full", interaction: { hovered: false, pressed: state.dragging, focusVisible: state.focused, disabled: state.disabled }, style: {
+                                            ...native.style,
+                                            ...transition(metrics.visual, "scale, outline-color, box-shadow"),
+                                            zIndex: 2,
+                                            width: thumb,
+                                            height: thumb,
+                                            cursor: state.disabled ? "not-allowed" : state.dragging ? "grabbing" : "grab",
+                                            scale: state.dragging ? "0.92" : "1"
+                                        } }) })] }) }) }), description != null && _jsx("span", { id: descriptionId, style: { fontSize: "0.92em", opacity: controlOpacity.secondary }, children: description })] }) });
 });

package/dist/spinner.d.ts

@@ -1,20 +1,17 @@
 import type { CSSProperties } from "react";
 import type { ProgressBarProps as AriaProgressBarProps } from "react-aria-components";
-import type { ControlColor } from "./control.js";
-import { type ScaleLevel } from "./scale.js";
+import { type Color } from "./foundation/color.js";
+import { type ScaleLevel } from "./foundation/scale.js";
 type NativeSpinnerProps = Omit<AriaProgressBarProps, "aria-hidden" | "aria-label" | "aria-labelledby" | "children" | "className" | "formatOptions" | "isIndeterminate" | "maxValue" | "minValue" | "slot" | "style" | "value" | "valueLabel">;
 interface SpinnerVisualProps extends NativeSpinnerProps {
-    /** Native class name applied without replacing the component contract. */
     readonly className?: string;
-    /** Color of the moving indicator. */
-    readonly color?: ControlColor;
-    /** Derives the indicator diameter from Appearance. */
+    /** Color of the moving arc. `currentColor` follows the surrounding content. */
+    readonly color?: Color;
     readonly size?: ScaleLevel;
-    /** Native styles applied after Spinner defaults. */
     readonly style?: CSSProperties;
 }
 type NamedSpinnerProps = Readonly<{
-    /** Accessible operation name announced with indeterminate progress semantics. */
+    /** Accessible name announced with indeterminate progress semantics. */
     label: string;
     decorative?: false;
 }>;

package/dist/spinner.js

@@ -1,18 +1,17 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { forwardRef } from "react";
 import { ProgressBar as AriaProgressBar } from "react-aria-components";
-import { motion } from "motion/react";
-import { useAppearance } from "./appearance-context.js";
-import { colorOpacity } from "./color.js";
-import { useControlTheme } from "./control.js";
-import { scale } from "./scale.js";
+import { useControlMetrics } from "./control/control.js";
+import { colorOpacity, resolveColor } from "./foundation/color.js";
+import MotionStyle from "./foundation/motion-style.js";
+import { scale } from "./foundation/scale.js";
 /** Compact indeterminate progress, either named or explicitly decorative. */
-export const Spinner = forwardRef(function Spinner({ className, color = "default:base", decorative = false, label, size = "medium", style, ...properties }, ref) {
-    const appearance = useAppearance();
-    const theme = useControlTheme({ color, size });
-    // Spinner is a standalone status, so its scale must remain visibly distinct
-    // instead of inheriting the compact indicator size used inside controls.
-    const diameter = appearance.spacing + scale(appearance.spacing, size);
+export const Spinner = forwardRef(function Spinner({ className, color = "primary", decorative = false, label, size = "medium", style, ...properties }, ref) {
+    const metrics = useControlMetrics(size);
+    const { colors } = metrics.visual;
+    // A standalone status stays visibly distinct from the compact control indicator.
+    const diameter = metrics.visual.spacing + scale(metrics.visual.spacing, size);
+    const arc = color === "currentColor" ? "currentColor" : resolveColor(color, colors);
     const rootStyle = {
         display: "inline-grid",
         placeItems: "center",
@@ -23,22 +22,8 @@ export const Spinner = forwardRef(function Spinner({ className, color = "default
         verticalAlign: "middle",
         ...style
     };
-    const indicator = _jsx(SpinnerIndicator, { contextualColor: color === "currentColor", theme: theme });
+    const indicator = _jsxs(_Fragment, { children: [_jsx(MotionStyle, {}), _jsxs("svg", { "data-spinner-indicator": "", "aria-hidden": "true", focusable: "false", viewBox: "0 0 24 24", width: "100%", height: "100%", fill: "none", style: { display: "block", animation: metrics.visual.duration > 0 ? `phreshos-ui-spin ${Math.max(600, metrics.visual.appearance.transaction.duration * 5)}ms linear infinite` : undefined }, children: [_jsx("circle", { "data-spinner-track": "", cx: "12", cy: "12", r: "9", stroke: colorOpacity(arc, 0.2), strokeWidth: "3" }), _jsx("circle", { "data-spinner-fill": "", cx: "12", cy: "12", r: "9", pathLength: "100", stroke: arc, strokeWidth: "3", strokeLinecap: "round", strokeDasharray: "30 70" })] })] });
     if (decorative)
         return _jsx("div", { ...properties, ref: ref, "aria-hidden": "true", className: className, style: rootStyle, children: indicator });
     return _jsx(AriaProgressBar, { ...properties, ref: ref, "aria-label": label, className: className, isIndeterminate: true, style: rootStyle, children: indicator });
 });
-function SpinnerIndicator({ contextualColor, theme }) {
-    const duration = typeof theme.motionTransition.duration === "number"
-        ? Math.max(0.6, theme.motionTransition.duration * 4)
-        : 0.8;
-    // currentColor belongs to the surrounding surface, whose canvas is not the
-    // Appearance canvas. Alpha preserves contrast against that actual owner.
-    const track = contextualColor
-        ? colorOpacity("currentColor", 0.25)
-        : theme.paints.subtle.rest.background;
-    const fill = contextualColor ? "currentColor" : theme.paints.palette.rest.background;
-    return _jsxs(motion.svg, { "data-spinner-indicator": "", "aria-hidden": "true", focusable: "false", viewBox: "0 0 24 24", width: "100%", height: "100%", fill: "none", 
-        // A repeating animation must start on mount; initial={false} renders its final keyframe instead.
-        initial: { rotate: 0 }, animate: { rotate: theme.animations ? [0, 360] : 0 }, transition: theme.animations ? { duration, repeat: Infinity, ease: "linear" } : { duration: 0 }, style: { display: "block", transformOrigin: "center" }, children: [_jsx("circle", { "data-spinner-track": "", cx: "12", cy: "12", r: "9", stroke: track, strokeWidth: "3" }), _jsx("circle", { "data-spinner-fill": "", cx: "12", cy: "12", r: "9", pathLength: "100", stroke: fill, strokeWidth: "3", strokeLinecap: "round", strokeDasharray: "68 32" })] });
-}

package/dist/surface/grain.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Returns the tiled grain texture for one seed, density, and opacity. The
+ * opacity is baked into the image so grain can share one layer with the paint
+ * without also fading that layer's backdrop.
+ */
+export declare function grainImage(seed: number, amount: number, opacity: number): string;
+/**
+ * One texture serves every Surface. Each Surface tiles it from its own origin,
+ * so neighbours never align, and equal paints can share one generated class.
+ */
+export declare const grainSeed = 47;
+export declare const grainSize = 64;

package/dist/surface/grain.js

@@ -0,0 +1,65 @@
+/**
+ * Returns the tiled grain texture for one seed, density, and opacity. The
+ * opacity is baked into the image so grain can share one layer with the paint
+ * without also fading that layer's backdrop.
+ */
+export function grainImage(seed, amount, opacity) {
+    const key = `${seed}:${amount}:${Math.round(opacity * 1_000)}`;
+    const cached = resources.get(key);
+    if (cached !== undefined)
+        return cached;
+    const paths = grainPaths(seed, amount)
+        .map((path, tone) => path ? `<path d="${path}" fill="rgb(${channel(tone)} ${channel(tone)} ${channel(tone)})"/>` : "")
+        .join("");
+    const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${patternSize}" height="${patternSize}" viewBox="0 0 ${patternSize} ${patternSize}"><g opacity="${opacity}">${paths}</g></svg>`;
+    const resource = `url("data:image/svg+xml,${encodeURIComponent(svg)}")`;
+    // The same few textures repeat across every Surface; the bound keeps live
+    // grain controls from growing the cache without limit.
+    if (resources.size >= resourceLimit)
+        resources.delete(resources.keys().next().value);
+    resources.set(key, resource);
+    return resource;
+}
+/**
+ * One texture serves every Surface. Each Surface tiles it from its own origin,
+ * so neighbours never align, and equal paints can share one generated class.
+ */
+export const grainSeed = 47;
+export const grainSize = 64;
+/** `amount` is the monotonic density of visible grain pixels. */
+function grainPaths(seed, amount) {
+    const tones = Array.from({ length: toneCount }, () => []);
+    for (let y = 0; y < patternSize; y += 1) {
+        for (let x = 0; x < patternSize; x += 1) {
+            const pointX = x + seed * 41;
+            const pointY = y + seed * 17;
+            if (hash(pointX + 71.9, pointY + 13.7) > amount)
+                continue;
+            const fine = hash(Math.floor(pointX * 1.18), Math.floor(pointY * 1.18));
+            const clustered = hash(Math.floor(pointX * 0.47) + 31.7, Math.floor(pointY * 0.47) + 31.7);
+            const value = Math.min(1, Math.max(0, fine * 0.8 + clustered * 0.2));
+            tones[Math.min(toneCount - 1, Math.floor(value * toneCount))]?.push(`M${x} ${y}h1v1h-1z`);
+        }
+    }
+    return tones.map(tone => tone.join(""));
+}
+function channel(tone) {
+    return Math.round(tone / (toneCount - 1) * 255);
+}
+function hash(x, y) {
+    let red = fract(x * 0.1031);
+    let green = fract(y * 0.1031);
+    let blue = fract(x * 0.1031);
+    const product = red * (green + 33.33) + green * (blue + 33.33) + blue * (red + 33.33);
+    red += product;
+    green += product;
+    blue += product;
+    return fract((red + green) * blue);
+}
+function fract(value) {
+    return value - Math.floor(value);
+}
+const patternSize = grainSize;
+const toneCount = 16;
+const resourceLimit = 64;
+const resources = new Map();

package/dist/{material-options.d.ts → surface/material-options.d.ts}

@@ -1,4 +1,4 @@
-import { type ScaleLevel } from "./scale.js";
+import { type ScaleLevel } from "../foundation/scale.js";
 /** Optional values of visual substance, expressed directly or relative to Appearance. */
 export interface MaterialOptions {
     readonly opacity?: ScaleLevel | number;
@@ -31,4 +31,3 @@ export declare function resolveMaterialOptions(values: MaterialOptions, defaults
     distortion: number;
     saturation: number;
 };
-export type ResolvedMaterial = ReturnType<typeof resolveMaterialOptions>;

package/dist/{material-options.js → surface/material-options.js}

@@ -1,5 +1,5 @@
-import { appearanceLimits } from "./appearance.js";
-import { isScaleLevel, scale, scaleMultiplier } from "./scale.js";
+import { appearanceLimits } from "../foundation/appearance.js";
+import { isScaleLevel, scale, scaleMultiplier } from "../foundation/scale.js";
 /** Resolves overrides against an already selected material branch. */
 export function resolveMaterialOptions(values, defaults) {
     const limits = appearanceLimits.material;

package/dist/surface/paint-class.d.ts

@@ -0,0 +1,13 @@
+/** Returns the class for one declaration block, registering it on first use. */
+export declare function paintClass(declarations: string): string;
+/** Inserts every registered rule not yet in the document. Runs before layout effects. */
+export declare function flushPaintRules(): void;
+/** Whether generated rules can reach a document in this environment. */
+export declare const paintClassesAvailable: boolean;
+/**
+ * Whether this render may use paint classes. Server rendering sends paints
+ * inline, so hydration renders inline too and matches the server HTML; React
+ * then renders again with classes. Without this, the server's inline paint
+ * would stay on the element, because hydration does not patch attributes.
+ */
+export declare function usePaintClasses(): boolean;

package/dist/surface/paint-class.js

@@ -0,0 +1,47 @@
+import { useSyncExternalStore } from "react";
+/**
+ * Every distinct Surface paint becomes one shared class. Surfaces repeat the
+ * same few paints across a whole interface, so changing Theme or hovering a
+ * control swaps one class name instead of rewriting a dozen inline properties
+ * on every element, which dominated the cost of large Theme changes.
+ *
+ * Rules use zero specificity, so any consumer class or inline style still wins.
+ */
+const classes = new Map();
+const pending = [];
+let sheet = null;
+/** Returns the class for one declaration block, registering it on first use. */
+export function paintClass(declarations) {
+    const cached = classes.get(declarations);
+    if (cached !== undefined)
+        return cached;
+    const name = `phreshos-paint-${classes.size.toString(36)}`;
+    classes.set(declarations, name);
+    pending.push(`:where(.${name}) { ${declarations} }`);
+    return name;
+}
+/** Inserts every registered rule not yet in the document. Runs before layout effects. */
+export function flushPaintRules() {
+    if (pending.length === 0 || typeof document === "undefined")
+        return;
+    if (sheet === null) {
+        const element = document.createElement("style");
+        element.setAttribute("data-phreshos-paint", "");
+        document.head.append(element);
+        sheet = element.sheet;
+    }
+    for (const rule of pending.splice(0))
+        sheet?.insertRule(rule, sheet.cssRules.length);
+}
+/** Whether generated rules can reach a document in this environment. */
+export const paintClassesAvailable = typeof document !== "undefined";
+const unchanging = () => () => undefined;
+/**
+ * Whether this render may use paint classes. Server rendering sends paints
+ * inline, so hydration renders inline too and matches the server HTML; React
+ * then renders again with classes. Without this, the server's inline paint
+ * would stay on the element, because hydration does not patch attributes.
+ */
+export function usePaintClasses() {
+    return useSyncExternalStore(unchanging, () => paintClassesAvailable, () => false);
+}

package/dist/{shadow-options.d.ts → surface/shadow-options.d.ts}

@@ -1,4 +1,4 @@
-import { type ScaleLevel } from "./scale.js";
+import { type ScaleLevel } from "../foundation/scale.js";
 /** Optional outer-shadow values expressed directly or relative to Appearance. */
 export interface ShadowOptions {
     readonly x?: ScaleLevel | number;
@@ -29,3 +29,15 @@ export declare function resolveShadowOptions(values: ShadowOptions, defaults: Re
 export type ResolvedShadow = ReturnType<typeof resolveShadowOptions>;
 /** Serializes one resolved neutral-black outer shadow. */
 export declare function shadowStyle({ x, y, blur, spread, opacity }: ResolvedShadow): string;
+/**
+ * The outer shadow of something floating above the interface, such as an
+ * overlay: the same Appearance shadow, only wider and slightly denser. It keeps
+ * the Appearance offset, so a directionless Appearance stays directionless.
+ */
+export declare function floatingShadow(shadow: Readonly<{
+    x: number;
+    y: number;
+    blur: number;
+    spread: number;
+    opacity: number;
+}>): ShadowOptions;

package/dist/{shadow-options.js → surface/shadow-options.js}

@@ -1,5 +1,5 @@
-import { appearanceLimits } from "./appearance.js";
-import { isScaleLevel, scale } from "./scale.js";
+import { appearanceLimits } from "../foundation/appearance.js";
+import { isScaleLevel, scale } from "../foundation/scale.js";
 /** Resolves overrides against an already selected shadow branch. */
 export function resolveShadowOptions(values, defaults) {
     const limits = appearanceLimits.shadow;
@@ -20,3 +20,18 @@ function resolve(value, base, range) {
     const finite = Number.isFinite(resolved) ? resolved : base;
     return Math.min(range.maximum, Math.max(range.minimum, finite));
 }
+/**
+ * The outer shadow of something floating above the interface, such as an
+ * overlay: the same Appearance shadow, only wider and slightly denser. It keeps
+ * the Appearance offset, so a directionless Appearance stays directionless.
+ */
+export function floatingShadow(shadow) {
+    const limits = appearanceLimits.shadow;
+    return {
+        x: shadow.x,
+        y: shadow.y,
+        blur: Math.min(limits.blur.maximum, Math.max(24, shadow.blur * 3)),
+        spread: shadow.spread,
+        opacity: Math.min(limits.opacity.maximum, shadow.opacity * 1.6)
+    };
+}

package/dist/surface/surface.d.ts

@@ -0,0 +1,80 @@
+import type { ComponentPropsWithRef, CSSProperties, ElementType, ReactElement, ReactNode } from "react";
+import { type Color } from "../foundation/color.js";
+import type { Direction } from "../foundation/direction.js";
+import { type RadiusProps } from "../foundation/radius.js";
+import { type Visual } from "../foundation/visual.js";
+import { type MaterialMode, type MaterialOptions, type MaterialOverrides } from "./material-options.js";
+import { type ShadowOverrides } from "./shadow-options.js";
+export type { MaterialMode, MaterialOptions } from "./material-options.js";
+export type { ShadowOptions } from "./shadow-options.js";
+/**
+ * Where a Surface sits relative to its surroundings. Every depth is the same
+ * Material; only the direction of light changes.
+ *   raised   — something you act on: an outer shadow and a lit top edge.
+ *   flat     — a region level with its surroundings: only a boundary.
+ *   recessed — something that holds content: a slightly deeper paint and an
+ *              inner shadow instead of an outer one.
+ */
+export type SurfaceDepth = "raised" | "flat" | "recessed";
+export interface SurfaceOwnProps extends MaterialOverrides, ShadowOverrides, RadiusProps {
+    readonly color?: Color;
+    readonly depth?: SurfaceDepth;
+}
+/**
+ * The structural properties a component must preserve when it hosts a Surface.
+ * It applies `className` and `style` and renders `children` on one element,
+ * and forwards its ref to that element.
+ */
+export interface SurfaceHostProps {
+    readonly children?: ReactNode;
+    readonly className?: string;
+    readonly dir?: Direction;
+    readonly style?: CSSProperties;
+}
+export type SurfaceHost = ElementType<SurfaceHostProps>;
+export type SurfaceProps<As extends SurfaceHost = "div"> = SurfaceOwnProps & Readonly<{
+    as?: As;
+}> & Omit<ComponentPropsWithRef<As>, keyof SurfaceOwnProps | "as" | "color">;
+export type SurfaceComponent = <As extends SurfaceHost = "div">(properties: SurfaceProps<As>) => ReactElement | null;
+/** Interaction state supplied by the components that own a Surface. */
+export interface SurfaceInteraction {
+    readonly hovered?: boolean;
+    readonly pressed?: boolean;
+    readonly focusVisible?: boolean;
+    readonly disabled?: boolean;
+    /** Marks a value-holding Surface whose current value is rejected. */
+    readonly invalid?: boolean;
+}
+/**
+ * The single visual primitive. Components express what they are through
+ * color, depth, and interaction; paint, grain, frost, edge, shadow, focus,
+ * and the text color are all derived here from Appearance.
+ */
+export declare const SurfaceView: import("react").ForwardRefExoticComponent<SurfaceOwnProps & Readonly<{
+    as?: ElementType;
+    interaction?: SurfaceInteraction;
+}> & Omit<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, keyof SurfaceOwnProps | "as"> & import("react").RefAttributes<Element>>;
+/** One material- and depth-owning element. The host is a div unless `as` selects another. */
+export declare const Surface: SurfaceComponent;
+/**
+ * Marks an element that is disabled. Disabling fades only the outermost
+ * disabled element: parts inside it, such as a field's well or a disabled
+ * calendar's days, are disabled with it and do not fade a second time.
+ */
+export declare function dimmedClass(disabled: boolean, className?: string): string | undefined;
+/** How far hover and press move a paint toward the text color. */
+export declare const interactionShift: Readonly<{
+    hovered: 0.05;
+    pressed: 0.1;
+}>;
+/** A clear Surface has no paint to move, so it shows the same shift as a slightly stronger veil. */
+export declare const clearVeil = 1.3;
+/** Resolves every visual value of one Surface. Pure over its inputs. */
+export declare function surfacePaint(visual: Visual, color: Color, depth: SurfaceDepth, options: MaterialMode | MaterialOptions | undefined, shadowOptions: ShadowOverrides["shadow"], interaction: SurfaceInteraction | undefined): {
+    fill: string;
+    text: string;
+    ring: string;
+    shadow: string;
+    distortion: number;
+    variables: CSSProperties;
+};