@phreshos/react-ui 0.1.35 → 0.1.37

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,20 +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", initial: false, 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,6 @@
+/** 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;

package/dist/surface/paint-class.js

@@ -0,0 +1,36 @@
+/**
+ * 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";

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,73 @@
+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;
+/** 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;
+};

package/dist/surface/surface.js

@@ -0,0 +1,230 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createElement, forwardRef, useId, useInsertionEffect } from "react";
+import { canvasDarkness, colorOpacity, contrast, mixColor, readableColor, recessColor, resolveColor } from "../foundation/color.js";
+import { resolveRadius } from "../foundation/radius.js";
+import { useVisual } from "../foundation/visual.js";
+import { grainImage, grainSeed, grainSize } from "./grain.js";
+import { flushPaintRules, paintClass, paintClassesAvailable } from "./paint-class.js";
+import { resolveMaterialOptions } from "./material-options.js";
+import { resolveShadowOptions, shadowStyle } from "./shadow-options.js";
+/**
+ * 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 const SurfaceView = forwardRef(function Surface({ as: Element = "div", color = "background", depth = "raised", material, shadow, radius, interaction, className, children, style, ...properties }, ref) {
+    const visual = useVisual();
+    const identity = useId();
+    const paint = surfacePaint(visual, color, depth, material, shadow, interaction);
+    const borderRadius = radius === undefined && style?.borderRadius !== undefined
+        ? style.borderRadius
+        : resolveRadius(radius ?? "medium", visual.radius);
+    const declarations = [
+        ...Object.entries(paint.variables).map(([name, value]) => `${name}: ${value}`),
+        "transition-property: box-shadow, color, outline-color, opacity",
+        `transition-duration: ${visual.duration}ms`,
+        `transition-timing-function: ${visual.easing}`,
+        `box-shadow: ${paint.shadow}`,
+        `color: ${paint.text}`,
+        `outline: 3px solid ${interaction?.focusVisible ? paint.ring : "transparent"}`,
+        "outline-offset: 1px",
+        `border-radius: ${typeof borderRadius === "number" ? `${borderRadius}px` : borderRadius}`
+    ].join("; ");
+    const painted = paintClassesAvailable ? paintClass(declarations) : undefined;
+    useInsertionEffect(flushPaintRules);
+    return createElement(Element, {
+        ...properties,
+        ref,
+        className: [surfaceClass, painted, dimmedClass(interaction?.disabled ?? false), className].filter(Boolean).join(" "),
+        // Without a document (server rendering), the same declarations travel inline.
+        style: painted === undefined ? { ...inlineDeclarations(declarations), ...style } : style
+    }, _jsx(SurfaceStyle, {}), paint.distortion > 0 && _jsx(Refraction, { identity: identity, distortion: paint.distortion }), children);
+});
+function inlineDeclarations(declarations) {
+    const result = {};
+    for (const declaration of declarations.split("; ")) {
+        const separator = declaration.indexOf(": ");
+        const name = declaration.slice(0, separator);
+        result[name.startsWith("--") ? name : name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase())] = declaration.slice(separator + 2);
+    }
+    return result;
+}
+/** One material- and depth-owning element. The host is a div unless `as` selects another. */
+export const Surface = SurfaceView;
+/**
+ * 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 function dimmedClass(disabled, className) {
+    return [disabled ? dimmed : undefined, className].filter(Boolean).join(" ") || undefined;
+}
+const disabledOpacity = 0.46;
+const dimmed = "phreshos-dimmed";
+const surfaceClass = "phreshos-surface";
+const materialLevel = Object.freeze({ none: 0, basic: 1, extended: 2, full: 3 });
+/** Resolves every visual value of one Surface. Pure over its inputs. */
+export function surfacePaint(visual, color, depth, options, shadowOptions, interaction) {
+    const { colors } = visual;
+    const base = resolveColor(color, colors);
+    const active = interaction !== undefined && !interaction.disabled;
+    const shift = active ? interaction.pressed ? 0.1 : interaction.hovered ? 0.05 : 0 : 0;
+    // Recessed paint sinks slightly below its surroundings; interaction then
+    // moves the same base toward the content color so every state stays related.
+    const darkness = canvasDarkness(colors);
+    // A recess moves away from its surroundings toward whichever extreme has
+    // room, by one constant perceptual difference on any canvas.
+    const rest = depth === "recessed" ? recessColor(base) : base;
+    // A transparent Surface has no substance of its own: it takes the content
+    // color of whatever it sits on and only reveals interaction as a veil.
+    const clear = base === "transparent";
+    const fill = clear
+        ? shift > 0 ? colorOpacity(colors.foreground, shift * 1.3) : "transparent"
+        : mixColor(rest, colors.foreground, shift);
+    const mode = clear ? "none" : typeof options === "object" ? "full" : options ?? "basic";
+    const level = materialLevel[mode];
+    const material = resolveMaterialOptions(typeof options === "object" ? options : {}, visual.material);
+    const opacity = level >= materialLevel.extended ? material.opacity : 1;
+    const translucent = opacity < 1;
+    const frost = level >= materialLevel.full && translucent
+        ? [material.backdrop > 0 ? `blur(${material.backdrop}px)` : "", material.saturation !== 1 ? `saturate(${material.saturation})` : ""].filter(Boolean).join(" ")
+        : "";
+    const grain = level >= materialLevel.basic && material.grain > 0 && material.grainAmount > 0
+        ? grainImage(grainSeed, material.grainAmount, level === materialLevel.basic ? material.grain * material.opacity : material.grain)
+        : "none";
+    const ringBase = interaction?.invalid
+        ? colors.danger
+        : !clear && (contrast(base, colors.background) ?? 1) >= 1.6 ? base : colors.primary;
+    const edged = level >= materialLevel.basic;
+    const lit = edgeLight(depth, darkness);
+    const light = mixColor(fill, "#ffffff", 0.7);
+    // Light rises from the middle of the top and bottom edges and spreads along
+    // them, fading as it goes, so it leans toward the sides without reaching
+    // them; the same slight spill falls inward from both middles. A hairline
+    // outside separates the Surface from whatever it sits on. Neither edge
+    // dominates, so no Surface reads as a bevel. Depth changes only how much
+    // light the rim receives.
+    const rim = edged
+        ? `linear-gradient(to right, transparent, ${colorOpacity(light, lit.side)} 18%, ${colorOpacity(light, lit.edge)} 50%, ${colorOpacity(light, lit.side)} 82%, transparent)`
+        : "none";
+    const spill = (edge) => edged && lit.spill > 0
+        ? `radial-gradient(50% 6px at 50% ${edge === "top" ? "0" : "100%"}, ${colorOpacity(light, lit.spill)}, transparent)`
+        : "none";
+    // A recessed Surface holds a value, so focus and validity also claim its hairline.
+    const claimed = interaction?.invalid || (depth === "recessed" && interaction?.focusVisible);
+    const hairline = !edged
+        ? null
+        : claimed
+            ? `0 0 0 1px ${ringBase}`
+            : `0 0 0 0.5px ${colorOpacity("#000000", lit.hairline)}`;
+    const shadow = visual.shadow;
+    const outer = clear || depth !== "raised" || shadowOptions === false || (active && interaction.pressed)
+        ? null
+        : shadowStyle(resolveShadowOptions(typeof shadowOptions === "object" ? shadowOptions : {}, shadow));
+    return {
+        fill,
+        // The label is chosen once for the resting paint: interaction shades stay
+        // close to it, and re-deciding per state would flip text on near-ties.
+        text: clear ? "inherit" : readableColor(rest, colors),
+        ring: colorOpacity(ringBase, 0.34),
+        shadow: [hairline, outer === "none" ? null : outer].filter(Boolean).join(", ") || "none",
+        distortion: level >= materialLevel.full && translucent ? material.distortion : 0,
+        variables: {
+            "--phreshos-surface-paint": translucent ? colorOpacity(fill, opacity) : fill,
+            "--phreshos-surface-grain": grain,
+            "--phreshos-surface-frost": frost || "none",
+            "--phreshos-surface-rim": rim,
+            "--phreshos-surface-spill-top": spill("top"),
+            "--phreshos-surface-spill-bottom": spill("bottom"),
+            "--phreshos-surface-duration": `${visual.duration}ms`,
+            "--phreshos-surface-easing": visual.easing
+        }
+    };
+}
+/** How much light each part of the rim receives, interpolated along the canvas darkness. */
+function edgeLight(depth, darkness) {
+    const { light, dark } = edgeLightEnds[depth];
+    return {
+        edge: round(mix(light.edge, dark.edge, darkness)),
+        side: round(mix(light.side, dark.side, darkness)),
+        spill: round(mix(light.spill, dark.spill, darkness)),
+        hairline: round(mix(light.hairline, dark.hairline, darkness))
+    };
+}
+function round(value) {
+    return Math.round(value * 1_000) / 1_000;
+}
+function mix(from, to, amount) {
+    return from + (to - from) * amount;
+}
+const edgeLightEnds = Object.freeze({
+    raised: {
+        light: { edge: 0.55, side: 0.22, spill: 0.15, hairline: 0.16 },
+        dark: { edge: 0.18, side: 0.08, spill: 0.035, hairline: 0.55 }
+    },
+    flat: {
+        light: { edge: 0.3, side: 0.14, spill: 0, hairline: 0.12 },
+        dark: { edge: 0.1, side: 0.05, spill: 0, hairline: 0.45 }
+    },
+    recessed: {
+        light: { edge: 0.45, side: 0.12, spill: 0, hairline: 0.12 },
+        dark: { edge: 0.12, side: 0.04, spill: 0, hairline: 0.45 }
+    }
+});
+/** A separate compositor pass for refraction, present only when it is visible. */
+function Refraction({ identity, distortion }) {
+    const filter = `phreshos-refraction-${identity.replaceAll(":", "")}`;
+    return _jsx("span", { "aria-hidden": "true", "data-surface-refraction": "", style: {
+            position: "absolute",
+            inset: 0,
+            zIndex: -2,
+            borderRadius: "inherit",
+            pointerEvents: "none",
+            backdropFilter: `url("#${filter}")`,
+            WebkitBackdropFilter: `url("#${filter}")`
+        }, children: _jsx("svg", { width: "0", height: "0", focusable: "false", style: { position: "absolute" }, children: _jsxs("filter", { id: filter, x: "-20%", y: "-20%", width: "140%", height: "140%", colorInterpolationFilters: "sRGB", children: [_jsx("feTurbulence", { type: "fractalNoise", baseFrequency: "0.008 0.008", numOctaves: 2, seed: 92, result: "noise" }), _jsx("feGaussianBlur", { in: "noise", stdDeviation: 2, result: "soft" }), _jsx("feDisplacementMap", { in: "SourceGraphic", in2: "soft", scale: distortion, xChannelSelector: "R", yChannelSelector: "G" })] }) }) });
+}
+/*
+ * Paint and edge live on pseudo-elements driven by per-Surface custom
+ * properties, so a Surface is one DOM element regardless of its Material.
+ * Position and isolation use zero specificity so any consumer class or style
+ * can replace them.
+ */
+const stylesheet = `
+:where(.${dimmed}:not(.${dimmed} .${dimmed})) {
+  opacity: ${disabledOpacity};
+}
+:where(.${surfaceClass}) {
+  position: relative;
+  isolation: isolate;
+}
+.${surfaceClass}::before,
+.${surfaceClass}::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  border-radius: inherit;
+  pointer-events: none;
+}
+.${surfaceClass}::before {
+  z-index: -1;
+  background-color: var(--phreshos-surface-paint);
+  background-image: var(--phreshos-surface-spill-top), var(--phreshos-surface-spill-bottom), var(--phreshos-surface-grain);
+  background-size: auto, auto, ${grainSize}px ${grainSize}px;
+  -webkit-backdrop-filter: var(--phreshos-surface-frost);
+  backdrop-filter: var(--phreshos-surface-frost);
+  transition: background-color var(--phreshos-surface-duration) var(--phreshos-surface-easing);
+}
+.${surfaceClass}::after {
+  z-index: 1;
+  padding: 0.5px;
+  background: var(--phreshos-surface-rim);
+  -webkit-mask: linear-gradient(#000 0 0) content-box, linear-gradient(#000 0 0);
+  -webkit-mask-composite: xor;
+  mask: linear-gradient(#000 0 0) content-box exclude, linear-gradient(#000 0 0);
+}
+`;
+/** React hoists and deduplicates this stylesheet, including inside portals. */
+function SurfaceStyle() {
+    return _jsx("style", { href: "phreshos-react-ui-surface", precedence: "phreshos", children: stylesheet });
+}

package/dist/switch.d.ts

@@ -1,11 +1,10 @@
 import type { SwitchFieldProps } from "react-aria-components";
-import type { ControlOverrides, ControlProps, FieldProps } from "./control.js";
-import type { MaterialOverrides } from "./material-options.js";
-import type { ShadowOverrides } from "./shadow-options.js";
-export interface SwitchProps extends Omit<SwitchFieldProps, ControlOverrides | "isReadOnly" | "isSelected" | "defaultSelected">, ControlProps, FieldProps, MaterialOverrides, ShadowOverrides {
+import { type ControlOverrides, type ControlProps, type FieldProps } from "./control/control.js";
+import type { MaterialOverrides } from "./surface/material-options.js";
+export interface SwitchProps extends Omit<SwitchFieldProps, ControlOverrides | "isSelected" | "defaultSelected">, ControlProps, FieldProps, MaterialOverrides {
     readonly checked?: boolean;
     readonly defaultChecked?: boolean;
     readonly readOnly?: boolean;
 }
-/** An on/off setting. onChange receives the next boolean value. */
+/** An on/off setting. `onChange` receives the next boolean value. */
 export declare const Switch: import("react").ForwardRefExoticComponent<SwitchProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/switch.js

@@ -1,12 +1,21 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { forwardRef } from "react";
-import { SwitchField, SwitchButton } from "react-aria-components";
-import { FieldFeedback, fieldStyle, useControlTheme } from "./control.js";
-import { ToggleIndicator, toggleStyle } from "./toggle-indicator.js";
-import { resolveDirection, useDirection } from "./direction.js";
-/** An on/off setting. onChange receives the next boolean value. */
-export const Switch = forwardRef(function Switch({ label, description, errorMessage, disabled, required, invalid, readOnly, checked, defaultChecked, size, color, style, material, shadow, ...properties }, ref) {
-    const theme = useControlTheme({ size, color });
+import { SwitchButton, SwitchField } from "react-aria-components";
+import { useControlMetrics } from "./control/control.js";
+import { FieldFeedback, fieldStyle } from "./control/field.js";
+import { ToggleIndicator, toggleRowStyle } from "./control/toggle.js";
+import { resolveDirection, useDirection } from "./foundation/direction.js";
+import { dimmedClass } from "./surface/surface.js";
+/** An on/off setting. `onChange` receives the next boolean value. */
+export const Switch = forwardRef(function Switch({ label, description, errorMessage, disabled, required, invalid, readOnly, className, checked, defaultChecked, size, color = "primary", style, material, ...properties }, ref) {
+    const metrics = useControlMetrics(size);
     const direction = resolveDirection(properties.dir, useDirection());
-    return _jsxs(SwitchField, { ...properties, ref: ref, isDisabled: disabled, isRequired: required, isInvalid: invalid, isReadOnly: readOnly, isSelected: checked, defaultSelected: defaultChecked, style: state => fieldStyle(theme, state.isDisabled, style), children: [_jsx(SwitchButton, { style: state => toggleStyle(theme, state.isDisabled, state.isReadOnly), children: state => _jsxs(_Fragment, { children: [_jsx(ToggleIndicator, { kind: "switch", direction: direction, material: material, shadow: shadow, theme: theme, selected: state.isSelected, focused: state.isFocusVisible, invalid: state.isInvalid, hovered: !state.isDisabled && !state.isReadOnly && state.isHovered, pressed: !state.isDisabled && !state.isReadOnly && state.isPressed }), label] }) }), _jsx(FieldFeedback, { theme: theme, description: description, errorMessage: errorMessage })] });
+    return _jsxs(SwitchField, { ...properties, ref: ref, isDisabled: disabled, isRequired: required, isInvalid: invalid, isReadOnly: readOnly, isSelected: checked, defaultSelected: defaultChecked, className: state => dimmedClass(state.isDisabled, className ?? state.defaultClassName) ?? "", style: fieldStyle(metrics, style), children: [_jsx(SwitchButton, { style: state => toggleRowStyle(metrics, state.isDisabled, state.isReadOnly), children: state => _jsxs(_Fragment, { children: [_jsx(ToggleIndicator, { kind: "switch", direction: direction, color: color, material: material, metrics: metrics, state: {
+                                selected: state.isSelected,
+                                hovered: !state.isReadOnly && state.isHovered,
+                                pressed: !state.isReadOnly && state.isPressed,
+                                focusVisible: state.isFocusVisible,
+                                invalid: state.isInvalid,
+                                disabled: state.isDisabled
+                            } }), label] }) }), _jsx(FieldFeedback, { metrics: metrics, description: description, errorMessage: errorMessage })] });
 });