@phreshos/react-ui 0.1.18 → 0.1.19

package/README.md

@@ -92,9 +92,9 @@ wrapper. The host retains ownership of its own behavior and layout properties;
 Surface retains ownership of material, edge, radius, and required geometry.
 
 `MaterialOptions` defines `opacity`, `backdrop`, `grain`, `grainAmount`,
-`distortion`, and `saturation`. Surface accepts these properties directly because
-it is the material-owning element; it does not accept a nested `material` prop.
-Color remains a separate Surface property. Omitted material values follow
+`distortion`, and `saturation`. Every material-bearing component, including
+Surface, exposes these values through its `material` prop. Color remains a
+separate property. Omitted material values follow
 `appearance.material`. Effect options accept a scale level or a direct number;
 opacity affects Surface paint only, never its content. The material edge is part
 of the same Surface rather than a second public entity.
@@ -139,11 +139,11 @@ Theme names never imply particular colors. No component requires a Client or
 Server SDK.
 
 Fields distinguish hover, pointer focus, keyboard focus, and invalid state.
-Shared CSS transitions use a fixed 120ms ease-out timing for colors and corner
+Shared CSS transitions use `appearance.transaction` for colors and corner
 radius. The material fill and opacity values transition on the painted layers, not on the
 Surface host. Select menus combine a small placement-aware slide with an overlay
 opacity fade for entry and exit, using React Aria's animation lifecycle. Reduced-motion preferences make
-these changes immediate. No Appearance configuration is added for motion yet.
+these changes immediate without changing the Appearance value.
 Blur, distortion, geometry, and Surface host opacity are not transitioned; gradients
 and structurally removed effects change directly rather than adding extra
 layers or keeping disabled effects alive.
@@ -216,6 +216,12 @@ bun run verify
 `verify` checks the contracts, tests the components, builds the package, and
 validates its published shape.
 
+`check` performs static checks, `build` creates distributable output, and `test`
+runs Vitest assertions from `tests/`. Run `build` before testing built artifacts.
+`verify` runs `check`, `build`, and `test` in order. Operational tooling belongs
+in `scripts/`; tests and their fixtures belong in `tests/`. Verification uses
+the committed dependency graph without local package substitutions.
+
 ## Related repositories
 
 - [`@phreshos/core`](https://github.com/PhreshOS/core) owns Appearance, Theme,

package/dist/appearance-context.d.ts

@@ -0,0 +1,18 @@
+import { type Appearance, type Theme, type ThemedValue } from "@phreshos/core";
+export declare const AppearanceContext: import("react").Context<Readonly<{
+    colors: ThemedValue<import("@phreshos/core").AppearanceColors>;
+    spacing: number;
+    radius: number;
+    shadow: ThemedValue<import("@phreshos/core").AppearanceShadow>;
+    material: ThemedValue<import("@phreshos/core").AppearanceMaterial>;
+    transaction: import("@phreshos/core").AppearanceTransaction;
+    signInWallpaper: ThemedValue<string | null>;
+    desktopWallpaper: ThemedValue<string | null>;
+}>>;
+export declare const ThemeContext: import("react").Context<Theme | null>;
+/** Returns the nearest unresolved Appearance, or Core's complete default. */
+export declare function useAppearance(): Appearance;
+/** Returns the nearest explicit Theme, or reactively follows the browser. */
+export declare function useTheme(): Theme;
+/** Selects the active branch of one complete ThemedValue. */
+export declare function useThemedValue<Value>(value: ThemedValue<Value>): Value;

package/dist/appearance-context.js

@@ -0,0 +1,37 @@
+import { createContext, useContext, useSyncExternalStore } from "react";
+import { defaultAppearance } from "@phreshos/core";
+export const AppearanceContext = createContext(defaultAppearance);
+export const ThemeContext = createContext(null);
+/** Returns the nearest unresolved Appearance, or Core's complete default. */
+export function useAppearance() {
+    return useContext(AppearanceContext);
+}
+/** Returns the nearest explicit Theme, or reactively follows the browser. */
+export function useTheme() {
+    const theme = useContext(ThemeContext);
+    const browserTheme = useBrowserTheme();
+    return theme ?? browserTheme;
+}
+/** Selects the active branch of one complete ThemedValue. */
+export function useThemedValue(value) {
+    return value[useTheme()];
+}
+function useBrowserTheme() {
+    return useSyncExternalStore(subscribeBrowserTheme, browserTheme, serverTheme);
+}
+function subscribeBrowserTheme(change) {
+    if (typeof window === "undefined" || typeof window.matchMedia !== "function")
+        return () => undefined;
+    const preference = window.matchMedia(darkThemeQuery);
+    preference.addEventListener("change", change);
+    return () => preference.removeEventListener("change", change);
+}
+function browserTheme() {
+    return typeof window !== "undefined"
+        && typeof window.matchMedia === "function"
+        && window.matchMedia(darkThemeQuery).matches
+        ? "dark"
+        : "light";
+}
+function serverTheme() { return "light"; }
+const darkThemeQuery = "(prefers-color-scheme: dark)";

package/dist/appearance-provider.d.ts

@@ -1,13 +1,8 @@
 import type { ReactNode } from "react";
-import { type Appearance, type Theme, type ThemedValue } from "@phreshos/core";
+import { type Appearance, type Theme } from "@phreshos/core";
+export { useAppearance, useTheme, useThemedValue } from "./appearance-context.js";
 /** Optionally overrides unresolved Appearance and effective Theme for a React subtree. */
 export declare function AppearanceProvider({ appearance, children, theme }: AppearanceProviderProps): import("react").JSX.Element;
-/** Returns the nearest unresolved Appearance, or Core's complete default. */
-export declare function useAppearance(): Appearance;
-/** Returns the nearest explicit Theme, or reactively follows the browser. */
-export declare function useTheme(): Theme;
-/** Resolves one themed value only where it is consumed. */
-export declare function useResolveTheme<Value, DarkValue extends Value = never>(value: ThemedValue<Value, DarkValue>): Exclude<Value, undefined>;
 export interface AppearanceProviderProps {
     readonly appearance?: Appearance;
     readonly children: ReactNode;

package/dist/appearance-provider.js

@@ -1,10 +1,9 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { createContext, useContext, useSyncExternalStore } from "react";
-import { defaultAppearance } from "@phreshos/core";
+import {} from "@phreshos/core";
 import DocumentScrollbars from "./document-scrollbars.js";
 import MotionStyle from "./motion-style.js";
-const AppearanceContext = createContext(defaultAppearance);
-const ThemeContext = createContext(null);
+import { AppearanceContext, ThemeContext, useAppearance, useTheme } from "./appearance-context.js";
+export { useAppearance, useTheme, useThemedValue } from "./appearance-context.js";
 /** Optionally overrides unresolved Appearance and effective Theme for a React subtree. */
 export function AppearanceProvider({ appearance, children, theme }) {
     const inheritedAppearance = useAppearance();
@@ -13,37 +12,3 @@ export function AppearanceProvider({ appearance, children, theme }) {
     const resolvedTheme = theme ?? inheritedTheme;
     return _jsx(AppearanceContext.Provider, { value: resolvedAppearance, children: _jsxs(ThemeContext.Provider, { value: resolvedTheme, children: [_jsx(MotionStyle, {}), _jsx(DocumentScrollbars, { appearance: resolvedAppearance, theme: resolvedTheme }), children] }) });
 }
-/** Returns the nearest unresolved Appearance, or Core's complete default. */
-export function useAppearance() {
-    return useContext(AppearanceContext);
-}
-/** Returns the nearest explicit Theme, or reactively follows the browser. */
-export function useTheme() {
-    const theme = useContext(ThemeContext);
-    const browserTheme = useBrowserTheme();
-    return theme ?? browserTheme;
-}
-/** Resolves one themed value only where it is consumed. */
-export function useResolveTheme(value) {
-    const theme = useTheme();
-    return (theme === "dark" && "dark" in value ? value.dark : value.light);
-}
-function useBrowserTheme() {
-    return useSyncExternalStore(subscribeBrowserTheme, browserTheme, serverTheme);
-}
-function subscribeBrowserTheme(change) {
-    if (typeof window === "undefined" || typeof window.matchMedia !== "function")
-        return () => undefined;
-    const preference = window.matchMedia(darkThemeQuery);
-    preference.addEventListener("change", change);
-    return () => preference.removeEventListener("change", change);
-}
-function browserTheme() {
-    return typeof window !== "undefined"
-        && typeof window.matchMedia === "function"
-        && window.matchMedia(darkThemeQuery).matches
-        ? "dark"
-        : "light";
-}
-function serverTheme() { return "light"; }
-const darkThemeQuery = "(prefers-color-scheme: dark)";

package/dist/button.js

@@ -3,7 +3,6 @@ import { forwardRef } from "react";
 import { Button as AriaButton } from "react-aria-components";
 import { controlFontSizes, useControlTheme } from "./control.js";
 import { SurfaceButton } from "./control-surface.js";
-import { visualTransition } from "./motion-style.js";
 /** An Appearance-aware action with normalized pointer and keyboard behavior. */
 export const Button = forwardRef(function Button({ children, color, disabled = false, pending = false, onPress, radius = "medium", size = "medium", style, material, type = "button", ...properties }, ref) {
     const theme = useControlTheme({ color, radius, size });
@@ -25,7 +24,7 @@ function buttonStyle({ theme, disabled, isFocusVisible, isHovered, isPressed, pe
     const interactive = !disabled && !pending;
     const paint = buttonPaint(theme, interactive, isHovered, isPressed);
     return {
-        ...visualTransition,
+        ...theme.transition,
         appearance: "none",
         boxSizing: "border-box",
         display: "inline-grid",

package/dist/color.js

@@ -1,6 +1,6 @@
 import { useMemo } from "react";
 import { ColorSpace, mix, parse, serialize, to, toGamut, contrastWCAG21, sRGB, sRGB_Linear, HSL, HWB, Lab, LCH, OKLab, OKLCH, P3, A98RGB, ProPhoto, REC_2020, XYZ_D50, XYZ_D65 } from "colorjs.io/fn";
-import { useAppearance, useResolveTheme } from "./appearance-provider.js";
+import { useAppearance, useThemedValue } from "./appearance-provider.js";
 // Register the CSS color spaces, without bundling unrelated color-model APIs.
 for (const space of [sRGB, sRGB_Linear, HSL, HWB, Lab, LCH, OKLab, OKLCH, P3, A98RGB, ProPhoto, REC_2020, XYZ_D50, XYZ_D65])
     ColorSpace.register(space);
@@ -44,14 +44,14 @@ export function useColor(value) {
 export function useResolveColor(value = defaultColor) {
     const appearance = useAppearance();
     const semantic = parseSemanticColor(value);
-    const source = useResolveTheme(appearance.colors[semantic?.name ?? "background"]);
+    const source = useThemedValue(appearance.colors)[semantic?.name ?? "background"];
     return semantic ? color(source)[semantic.level] : value;
 }
 /** Resolves a color to concrete opaque paint for solid interactive states. */
 export function useResolveSolidColor(value) {
     const appearance = useAppearance();
     const semantic = parseSemanticColor(value);
-    const source = useResolveTheme(appearance.colors[semantic?.name ?? "background"]);
+    const source = useThemedValue(appearance.colors)[semantic?.name ?? "background"];
     return semantic ? resolveColorLevel(source, semantic.level) : opaqueColor(value);
 }
 /** Applies material opacity without restricting the source CSS color syntax. */

package/dist/control-surface.js

@@ -3,9 +3,9 @@ import { Surface } from "./surface.js";
 /** A native button uses Surface without changing its native contract. */
 export function SurfaceButton({ native, paint, material: options }) {
     const { ref, style, children, ...properties } = native;
-    return _jsx(Surface, { ...properties, ...options, as: "button", color: paint.background, ref: ref, style: { ...style, color: paint.color }, children: children });
+    return _jsx(Surface, { ...properties, as: "button", color: paint.background, material: options, ref: ref, style: { ...style, color: paint.color }, children: children });
 }
 /** Void text controls use a material host while retaining native sizing. */
 export function SurfaceField({ paint, radius, children, material: options }) {
-    return _jsx(Surface, { ...options, as: "span", color: paint.background, radius: radius, style: { color: paint.color, display: "grid", minWidth: 0 }, children: children });
+    return _jsx(Surface, { as: "span", color: paint.background, material: options, radius: radius, style: { color: paint.color, display: "grid", minWidth: 0 }, children: children });
 }

package/dist/control.d.ts

@@ -25,6 +25,7 @@ export type ControlOverrides = keyof ControlProps | keyof FieldProps | "children
 export declare const controlFontSizes: Readonly<Record<ScaleLevel, number>>;
 type SolidColors = ReturnType<typeof solidColors>;
 export interface ControlTheme {
+    readonly transition: CSSProperties;
     readonly spacing: number;
     readonly foreground: string;
     readonly background: string;

package/dist/control.js

@@ -1,12 +1,12 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo } from "react";
 import { FieldError, Label, Text } from "react-aria-components";
-import { useAppearance, useResolveTheme } from "./appearance-provider.js";
+import { useAppearance, useThemedValue } from "./appearance-provider.js";
 import { resolveRadius } from "./radius.js";
 import { scale } from "./scale.js";
 import { solidColors } from "./color.js";
 import { useResolveSolidColor } from "./color.js";
-import { visualTransition } from "./motion-style.js";
+import { useVisualTransition } from "./motion-style.js";
 export const controlFontSizes = Object.freeze({
     xsmall: 11,
     small: 12,
@@ -16,9 +16,11 @@ export const controlFontSizes = Object.freeze({
 });
 export function useControlTheme({ size = "medium", color, radius = "medium" }) {
     const appearance = useAppearance();
-    const spacing = scale(useResolveTheme(appearance.spacing), size);
-    const foreground = useResolveTheme(appearance.colors.foreground);
-    const background = useResolveTheme(appearance.colors.background);
+    const transition = useVisualTransition();
+    const spacing = scale(appearance.spacing, size);
+    const colors = useThemedValue(appearance.colors);
+    const foreground = colors.foreground;
+    const background = colors.background;
     const tint = useResolveSolidColor(color ?? "primary:base");
     const danger = useResolveSolidColor("danger:base");
     const paints = useMemo(() => ({
@@ -27,6 +29,7 @@ export function useControlTheme({ size = "medium", color, radius = "medium" }) {
         danger: solidColors(danger, background, foreground)
     }), [tint, background, foreground, danger]);
     return {
+        transition,
         spacing,
         foreground,
         background,
@@ -43,7 +46,7 @@ export function useControlTheme({ size = "medium", color, radius = "medium" }) {
 export function fieldStyle(theme, disabled = false, style) {
     return {
         ...style,
-        ...visualTransition,
+        ...theme.transition,
         display: "grid",
         gap: theme.gap,
         minWidth: 0,
@@ -61,7 +64,7 @@ export function controlPaint(theme, focused, invalid, hovered = false) {
 export function controlStyle(theme, focused, invalid, hovered = false, focusVisible = focused) {
     const paint = controlPaint(theme, focused, invalid, hovered);
     return {
-        ...visualTransition,
+        ...theme.transition,
         appearance: "none",
         boxSizing: "border-box",
         width: "100%",

package/dist/document-scrollbars.js

@@ -86,7 +86,7 @@ const documents = new WeakMap();
 /** Applies one Appearance to the complete owning document without rendering. */
 export default function DocumentScrollbars({ appearance, theme }) {
     const identity = useRef(Symbol("AppearanceProvider")).current;
-    const foreground = theme === "dark" ? appearance.colors.foreground.dark : appearance.colors.foreground.light;
+    const foreground = appearance.colors[theme].foreground;
     const padding = 5;
     const thumbSize = 6;
     const size = thumbSize + padding * 2;
@@ -95,7 +95,7 @@ export default function DocumentScrollbars({ appearance, theme }) {
         thumbHover: colorOpacity(foreground, 0.2),
         size: `${size}px`,
         padding: `${padding}px`,
-        radius: `${Math.min(appearance.radius.light, padding + thumbSize / 2)}px`
+        radius: `${Math.min(appearance.radius, padding + thumbSize / 2)}px`
     };
     useInsertionEffect(function () {
         if (typeof document === "undefined")

package/dist/main.d.ts

@@ -5,7 +5,7 @@
  * behavior contract has been established by the package's tests.
  */
 export { defaultAppearance } from "@phreshos/core";
-export { AppearanceProvider, useAppearance, useResolveTheme, useTheme, type AppearanceProviderProps } from "./appearance-provider.js";
+export { AppearanceProvider, useAppearance, useThemedValue, useTheme, type AppearanceProviderProps } from "./appearance-provider.js";
 export { Flex, type FlexProps } from "./flex.js";
 export { Grid, type GridProps } from "./grid.js";
 export { Surface, type MaterialOptions, type SurfaceComponent, type SurfaceHost, type SurfaceHostProps, type SurfaceOwnProps, type SurfaceProps } from "./surface.js";

package/dist/main.js

@@ -5,7 +5,7 @@
  * behavior contract has been established by the package's tests.
  */
 export { defaultAppearance } from "@phreshos/core";
-export { AppearanceProvider, useAppearance, useResolveTheme, useTheme } from "./appearance-provider.js";
+export { AppearanceProvider, useAppearance, useThemedValue, useTheme } from "./appearance-provider.js";
 export { Flex } from "./flex.js";
 export { Grid } from "./grid.js";
 export { Surface } from "./surface.js";

package/dist/material-options.js

@@ -1,10 +1,10 @@
 import { appearanceLimits } from "@phreshos/core";
-import { useAppearance, useResolveTheme } from "./appearance-provider.js";
+import { useAppearance, useThemedValue } from "./appearance-provider.js";
 import { isScaleLevel, scale, scaleMultiplier } from "./scale.js";
 /** Resolves material values from the current Appearance without knowing any host geometry. */
 export function useMaterialOptions(values = {}) {
     const appearance = useAppearance();
-    const defaults = useResolveTheme(appearance.material);
+    const defaults = useThemedValue(appearance.material);
     const limits = appearanceLimits.material;
     return {
         opacity: resolve(values.opacity, defaults.opacity, limits.opacity),

package/dist/material-paint.js

@@ -1,8 +1,9 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo } from "react";
-import { paintTransition } from "./motion-style.js";
+import { usePaintTransition } from "./motion-style.js";
 /** The fill, refraction definition, and grain of one Surface. */
 export function MaterialPaint({ color, distortion, grain, grainAmount, identity, opacity }) {
+    const paintTransition = usePaintTransition();
     const seed = useMemo(() => seedFrom(identity), [identity]);
     const hasPaint = opacity > 0;
     const hasGrain = hasPaint && grain > 0 && grainAmount > 0;

package/dist/motion-style.d.ts

@@ -1,21 +1,13 @@
-/** The same fixed timing for Motion-driven control movements. */
-export declare const controlTransition: {
-    readonly type: "tween";
-    readonly duration: 0.12;
-    readonly ease: "easeOut";
-};
-/** Host opacity and filters are excluded: either can change backdrop sampling. */
-export declare const visualTransition: {
-    transitionProperty: "background-color, color, border-color, border-radius";
-    transitionDuration: "var(--phreshos-ui-motion-duration, 120ms)";
-    transitionTimingFunction: "ease-out";
-};
-/** Radius is inherited from the host; only the painted values transition here. */
-export declare const paintTransition: {
-    transitionProperty: "fill, stroke, opacity";
-    transitionDuration: "var(--phreshos-ui-motion-duration, 120ms)";
-    transitionTimingFunction: "ease-out";
-};
+import type { CSSProperties } from "react";
+import type { Transition } from "motion/react";
+/** CSS timing for values painted directly by React UI. */
+export declare function useVisualTransition(): CSSProperties;
+/** CSS timing for SVG paint owned by a Material. */
+export declare function usePaintTransition(): CSSProperties;
+/** Motion timing for interactive geometry owned by React UI. */
+export declare function useControlTransition(reduced?: boolean): Transition;
+/** Per-overlay variables consumed by the shared entrance keyframes. */
+export declare function useOverlayTransition(): CSSProperties;
 export declare const overlayMotionClass = "phreshos-ui-overlay";
-/** React hoists and deduplicates this stylesheet, including nested providers and portals. */
+/** React hoists and deduplicates this stylesheet, including portals. */
 export default function MotionStyle(): import("react").JSX.Element;

package/dist/motion-style.js

@@ -1,33 +1,72 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-const timing = {
-    transitionDuration: "var(--phreshos-ui-motion-duration, 120ms)",
-    transitionTimingFunction: "ease-out"
-};
-/** The same fixed timing for Motion-driven control movements. */
-export const controlTransition = { type: "tween", duration: 0.12, ease: "easeOut" };
-/** Host opacity and filters are excluded: either can change backdrop sampling. */
-export const visualTransition = {
-    ...timing,
-    transitionProperty: "background-color, color, border-color, border-radius"
-};
-/** Radius is inherited from the host; only the painted values transition here. */
-export const paintTransition = {
-    ...timing,
-    transitionProperty: "fill, stroke, opacity"
-};
+import { defaultAppearance } from "@phreshos/core";
+import { useAppearance } from "./appearance-context.js";
+const visualProperties = "background-color, color, border-color, border-radius";
+const paintProperties = "fill, stroke, opacity";
+/** CSS timing for values painted directly by React UI. */
+export function useVisualTransition() {
+    return { ...useTransitionTiming(), transitionProperty: visualProperties };
+}
+/** CSS timing for SVG paint owned by a Material. */
+export function usePaintTransition() {
+    return { ...useTransitionTiming(), transitionProperty: paintProperties };
+}
+/** Motion timing for interactive geometry owned by React UI. */
+export function useControlTransition(reduced = false) {
+    const { duration, easing } = useAppearance().transaction;
+    return {
+        type: "tween",
+        duration: reduced ? 0 : duration / 1_000,
+        ease: motionEasing(easing)
+    };
+}
+/** Per-overlay variables consumed by the shared entrance keyframes. */
+export function useOverlayTransition() {
+    const { duration, easing } = useAppearance().transaction;
+    return {
+        "--phreshos-ui-motion-duration": `${duration}ms`,
+        "--phreshos-ui-motion-easing": cssEasing(easing)
+    };
+}
 export const overlayMotionClass = "phreshos-ui-overlay";
+function useTransitionTiming() {
+    const { duration, easing } = useAppearance().transaction;
+    return {
+        transitionDuration: `${duration}ms`,
+        transitionTimingFunction: cssEasing(easing)
+    };
+}
+function cssEasing(easing) {
+    return typeof easing === "string" ? easing : `cubic-bezier(${easing.join(", ")})`;
+}
+function motionEasing(easing) {
+    if (typeof easing !== "string")
+        return [...easing];
+    if (easing === "ease")
+        return [0.25, 0.1, 0.25, 1];
+    if (easing === "ease-in")
+        return "easeIn";
+    if (easing === "ease-out")
+        return "easeOut";
+    if (easing === "ease-in-out")
+        return "easeInOut";
+    return easing;
+}
 const stylesheet = `
-:root { --phreshos-ui-motion-duration: 120ms; }
+:root {
+  --phreshos-ui-motion-duration: ${defaultAppearance.transaction.duration}ms;
+  --phreshos-ui-motion-easing: ${cssEasing(defaultAppearance.transaction.easing)};
+}
 
 .phreshos-ui-overlay { --phreshos-ui-overlay-x: 0px; --phreshos-ui-overlay-y: -4px; }
 .phreshos-ui-overlay[data-placement="top"] { --phreshos-ui-overlay-y: 4px; }
 .phreshos-ui-overlay[data-placement="left"] { --phreshos-ui-overlay-x: 4px; --phreshos-ui-overlay-y: 0px; }
 .phreshos-ui-overlay[data-placement="right"] { --phreshos-ui-overlay-x: -4px; --phreshos-ui-overlay-y: 0px; }
 .phreshos-ui-overlay[data-entering] {
-  animation: phreshos-ui-overlay-enter var(--phreshos-ui-motion-duration, 120ms) ease-out both;
+  animation: phreshos-ui-overlay-enter var(--phreshos-ui-motion-duration) var(--phreshos-ui-motion-easing) both;
 }
 .phreshos-ui-overlay[data-exiting] {
-  animation: phreshos-ui-overlay-enter var(--phreshos-ui-motion-duration, 120ms) ease-out reverse both;
+  animation: phreshos-ui-overlay-enter var(--phreshos-ui-motion-duration) var(--phreshos-ui-motion-easing) reverse both;
   pointer-events: none;
 }
 @keyframes phreshos-ui-overlay-enter {
@@ -39,7 +78,7 @@ const stylesheet = `
   .phreshos-ui-overlay[data-entering], .phreshos-ui-overlay[data-exiting] { animation: none; }
 }
 `;
-/** React hoists and deduplicates this stylesheet, including nested providers and portals. */
+/** React hoists and deduplicates this stylesheet, including portals. */
 export default function MotionStyle() {
     return _jsx("style", { href: "phreshos-react-ui-motion", precedence: "phreshos", children: stylesheet });
 }

package/dist/panel.js

@@ -1,12 +1,12 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { forwardRef } from "react";
-import { useAppearance, useResolveTheme } from "./appearance-provider.js";
+import { useAppearance } from "./appearance-provider.js";
 import { scale } from "./scale.js";
 import { Surface } from "./surface.js";
 /** Owns the shared shell layout, not positioning, interaction, or lifecycle. */
 export const Panel = forwardRef(function Panel({ header, children, contentProps, style, ...properties }, ref) {
     const appearance = useAppearance();
-    const inset = scale(useResolveTheme(appearance.spacing), "small");
+    const inset = scale(appearance.spacing, "small");
     const hasHeader = header !== undefined && header !== null && header !== false;
     return _jsxs(Surface, { ...properties, ref: ref, style: {
             display: "grid",

package/dist/radius.d.ts

@@ -1,10 +1,11 @@
 import type { CSSProperties } from "react";
-import type { Appearance, Shapeable } from "@phreshos/core";
+import type { Appearance } from "@phreshos/core";
 import { type ScaleLevel } from "./scale.js";
 /** An Appearance-derived level, pixel value, or explicit CSS corner radius. */
 export type Radius = ScaleLevel | number | (string & {});
 /** Shared semantic corner-radius capability for React UI components. */
-export interface RadiusProps extends Shapeable<Radius> {
+export interface RadiusProps {
+    readonly radius?: Radius;
 }
 /** Resolves a Radius while preserving explicit CSS and pixel values. */
 export declare function resolveRadius(value: Radius | undefined, appearance: Appearance | null): CSSProperties["borderRadius"];

package/dist/radius.js

@@ -5,5 +5,5 @@ export function resolveRadius(value, appearance) {
         return value;
     if (!appearance)
         throw new Error("A semantic radius requires an AppearanceProvider");
-    return scale(appearance.radius.light, value);
+    return scale(appearance.radius, value);
 }

package/dist/select.js

@@ -5,17 +5,19 @@ import { Select as AriaSelect, Button, SelectValue, Popover, ListBox, ListBoxIte
 import { controlPaint, controlStyle, FieldFeedback, FieldLabel, fieldStyle, useControlTheme } from "./control.js";
 import { SurfaceButton } from "./control-surface.js";
 import { Surface } from "./surface.js";
-import { controlTransition, overlayMotionClass, visualTransition } from "./motion-style.js";
+import { overlayMotionClass, useControlTransition, useOverlayTransition } from "./motion-style.js";
 /** Single selection from string-valued options; keyboard navigation and typeahead stay native to React Aria. */
 export const Select = forwardRef(function Select({ label, description, errorMessage, disabled, required, invalid, options, value, defaultValue, onChange, size, color, radius, style, material, ...properties }, ref) {
     const theme = useControlTheme({ size, color, radius });
     const reduced = useReducedMotion();
+    const transition = useControlTransition(Boolean(reduced));
+    const overlayTransition = useOverlayTransition();
     return _jsx(AriaSelect, { ...properties, ref: ref, value: value, defaultValue: defaultValue, onChange: key => onChange?.(key == null ? null : String(key)), disabledKeys: options.filter(option => option.disabled).map(option => option.value), isDisabled: disabled, isRequired: required, isInvalid: invalid, style: fieldStyle(theme, disabled, style), children: state => _jsxs(_Fragment, { children: [_jsx(FieldLabel, { label: label }), _jsxs(Button, { render: (native, button) => _jsx(SurfaceButton, { native: native, material: material, paint: controlPaint(theme, state.isOpen || button.isFocused, state.isInvalid, button.isHovered) }), style: button => ({
                         ...controlStyle(theme, state.isOpen || button.isFocused, state.isInvalid, button.isHovered, button.isFocusVisible),
                         display: "flex", alignItems: "center", justifyContent: "space-between", gap: theme.gap,
                         cursor: disabled ? "not-allowed" : "pointer", textAlign: "start"
-                    }), children: [_jsx(SelectValue, { style: ({ isPlaceholder }) => ({ opacity: isPlaceholder ? 0.6 : 1, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }) }), _jsx(motion.svg, { "aria-hidden": "true", width: "12", height: "12", viewBox: "0 0 12 12", fill: "none", stroke: "currentColor", strokeWidth: "1.5", initial: false, animate: { rotate: state.isOpen ? 180 : 0 }, transition: { ...controlTransition, duration: reduced ? 0 : controlTransition.duration }, style: { flexShrink: 0 }, children: _jsx("path", { d: "m2 4 4 4 4-4" }) })] }), _jsx(Popover, { className: overlayMotionClass, placement: "bottom start", offset: theme.gap, maxHeight: 280 + theme.gap * 2, style: { width: "var(--trigger-width)", maxWidth: "calc(100vw - 16px)" }, children: _jsx(Surface, { style: { padding: theme.gap, display: "flex", flexDirection: "column", maxHeight: "inherit", boxSizing: "border-box" }, children: _jsx(ListBox, { items: options, style: { display: "grid", gap: theme.gap, minHeight: 0, overflow: "auto", outline: "none", fontSize: theme.fontSize, color: theme.foreground }, children: option => _jsx(ListBoxItem, { id: option.value, textValue: option.label, style: item => ({
-                                    ...visualTransition,
+                    }), children: [_jsx(SelectValue, { style: ({ isPlaceholder }) => ({ opacity: isPlaceholder ? 0.6 : 1, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }) }), _jsx(motion.svg, { "aria-hidden": "true", width: "12", height: "12", viewBox: "0 0 12 12", fill: "none", stroke: "currentColor", strokeWidth: "1.5", initial: false, animate: { rotate: state.isOpen ? 180 : 0 }, transition: transition, style: { flexShrink: 0 }, children: _jsx("path", { d: "m2 4 4 4 4-4" }) })] }), _jsx(Popover, { className: overlayMotionClass, placement: "bottom start", offset: theme.gap, maxHeight: 280 + theme.gap * 2, style: { ...overlayTransition, width: "var(--trigger-width)", maxWidth: "calc(100vw - 16px)" }, children: _jsx(Surface, { style: { padding: theme.gap, display: "flex", flexDirection: "column", maxHeight: "inherit", boxSizing: "border-box" }, children: _jsx(ListBox, { items: options, style: { display: "grid", gap: theme.gap, minHeight: 0, overflow: "auto", outline: "none", fontSize: theme.fontSize, color: theme.foreground }, children: option => _jsx(ListBoxItem, { id: option.value, textValue: option.label, style: item => ({
+                                    ...theme.transition,
                                     display: "flex", alignItems: "center", justifyContent: "space-between", gap: theme.gap,
                                     minHeight: theme.height, paddingInline: Math.max(8, theme.spacing), boxSizing: "border-box",
                                     borderRadius: theme.radius,

package/dist/slider.js

@@ -3,7 +3,7 @@ import { forwardRef, useId } from "react";
 import { motion, useReducedMotion } from "motion/react";
 import { Slider as AriaSlider, SliderTrack, SliderThumb, SliderFill, SliderOutput } from "react-aria-components";
 import { FieldLabel, fieldStyle, useControlTheme } from "./control.js";
-import { controlTransition, visualTransition } from "./motion-style.js";
+import { useControlTransition } from "./motion-style.js";
 /** One numeric value with pointer, touch, keyboard, and form support. */
 export const Slider = forwardRef(function Slider({ label, description, name, disabled, size, color, style, orientation = "horizontal", ...properties }, ref) {
     const theme = useControlTheme({ size, color });
@@ -11,17 +11,18 @@ export const Slider = forwardRef(function Slider({ label, description, name, dis
     const vertical = orientation === "vertical";
     const diameter = theme.fontSize + 6;
     const reduced = useReducedMotion();
+    const transition = useControlTransition(Boolean(reduced));
     const rail = Math.max(4, Math.round(diameter / 3));
     return _jsxs(AriaSlider, { ...properties, ref: ref, isDisabled: disabled, orientation: orientation, style: fieldStyle(theme, disabled, style), "aria-describedby": [properties["aria-describedby"], description != null ? descriptionId : null].filter(Boolean).join(" ") || undefined, children: [_jsxs("div", { style: { display: "flex", alignItems: "baseline", justifyContent: "space-between", gap: theme.gap }, children: [_jsx(FieldLabel, { label: label }), _jsx(SliderOutput, { style: { fontVariantNumeric: "tabular-nums", opacity: 0.7 } })] }), _jsxs(SliderTrack, { style: {
                     position: "relative", touchAction: "none",
                     width: vertical ? theme.height : "100%", height: vertical ? 160 : theme.height
                 }, children: [_jsx("div", { "aria-hidden": "true", style: {
-                            ...visualTransition,
+                            ...theme.transition,
                             position: "absolute", borderRadius: rail,
                             ...(vertical ? { width: rail, height: "100%", left: "50%", transform: "translateX(-50%)" } : { height: rail, width: "100%", top: "50%", transform: "translateY(-50%)" }),
                             background: theme.paints.neutral.rest.background
                         } }), _jsx(SliderFill, { style: {
-                            ...visualTransition,
+                            ...theme.transition,
                             position: "absolute", background: theme.paints.palette.rest.background, borderRadius: rail,
                             ...(vertical ? { width: rail, left: "50%", transform: "translateX(-50%)" } : { height: rail, top: "50%", transform: "translateY(-50%)" })
                         } }), _jsx(SliderThumb, { name: name, style: state => ({
@@ -29,7 +30,7 @@ export const Slider = forwardRef(function Slider({ label, description, name, dis
                             ...(vertical ? { left: "50%" } : { top: "50%" }),
                             outline: state.isFocusVisible ? `2px solid ${theme.foreground}` : "none", outlineOffset: 2,
                             cursor: state.isDisabled ? "not-allowed" : state.isDragging ? "grabbing" : "grab"
-                        }), children: state => _jsx(motion.span, { "aria-hidden": "true", initial: false, animate: { scale: reduced || state.isDisabled ? 1 : state.isDragging ? 0.92 : state.isHovered ? 1.08 : 1 }, transition: { ...controlTransition, duration: reduced ? 0 : controlTransition.duration }, style: { ...visualTransition, position: "absolute", inset: 0, borderRadius: "inherit", pointerEvents: "none",
+                        }), children: state => _jsx(motion.span, { "aria-hidden": "true", initial: false, animate: { scale: reduced || state.isDisabled ? 1 : state.isDragging ? 0.92 : state.isHovered ? 1.08 : 1 }, transition: transition, style: { ...theme.transition, position: "absolute", inset: 0, borderRadius: "inherit", pointerEvents: "none",
                                 background: (state.isDragging ? theme.paints.palette.pressed : state.isHovered ? theme.paints.palette.hover : theme.paints.palette.rest).color,
                                 border: `3px solid ${(state.isDragging ? theme.paints.palette.pressed : state.isHovered ? theme.paints.palette.hover : theme.paints.palette.rest).background}`,
                                 boxSizing: "border-box" } }) })] }), description != null && _jsx("span", { id: descriptionId, style: { fontSize: "0.92em", opacity: 0.7 }, children: description })] });

package/dist/spacing.js

@@ -4,5 +4,5 @@ export function resolveSpacing(value, appearance) {
         return value;
     if (!appearance)
         throw new Error("Semantic spacing requires an AppearanceProvider");
-    return scale(appearance.spacing.light, value);
+    return scale(appearance.spacing, value);
 }

package/dist/surface-edge.js

@@ -1,10 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Fragment, useCallback, useLayoutEffect, useRef, useState } from "react";
 import { colorLightness, colorOpacity, orderColors } from "./color.js";
-import { paintTransition } from "./motion-style.js";
+import { usePaintTransition } from "./motion-style.js";
 import { scale } from "./scale.js";
 /** Paints the boundary owned by one Surface from the material it contains. */
 export function SurfaceEdge({ material }) {
+    const paintTransition = usePaintTransition();
     const visible = material.opacity > 0;
     const palette = useRef(null);
     const [colors, setColors] = useState(null);

package/dist/surface.d.ts

@@ -1,9 +1,9 @@
 import type { ComponentPropsWithRef, CSSProperties, ElementType, ReactElement, ReactNode } from "react";
 import { type Color } from "./color.js";
-import { type MaterialOptions } from "./material-options.js";
+import { type MaterialOverrides } from "./material-options.js";
 import { type RadiusProps } from "./radius.js";
 export type { MaterialOptions } from "./material-options.js";
-export interface SurfaceOwnProps extends MaterialOptions, RadiusProps {
+export interface SurfaceOwnProps extends MaterialOverrides, RadiusProps {
     readonly color?: Color;
 }
 /**

package/dist/surface.js

@@ -1,22 +1,23 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { createElement, forwardRef, useId } from "react";
-import { useAppearance, useResolveTheme } from "./appearance-provider.js";
+import { useAppearance, useThemedValue } from "./appearance-provider.js";
 import { useResolveColor } from "./color.js";
 import { useMaterialOptions } from "./material-options.js";
 import { MaterialPaint } from "./material-paint.js";
-import MotionStyle, { visualTransition } from "./motion-style.js";
+import MotionStyle, { useVisualTransition } from "./motion-style.js";
 import { resolveRadius } from "./radius.js";
 import { SurfaceEdge } from "./surface-edge.js";
 /** One material-owning element. The host is a div unless `as` selects another element. */
-const SurfaceRoot = forwardRef(function Surface({ as: Element = "div", color, opacity, backdrop, grain, grainAmount, distortion, saturation, radius, children, style, ...properties }, ref) {
+const SurfaceRoot = forwardRef(function Surface({ as: Element = "div", color, material: options, radius, children, style, ...properties }, ref) {
     const appearance = useAppearance();
-    const material = useResolvedSurface(color, { opacity, backdrop, grain, grainAmount, distortion, saturation });
+    const transition = useVisualTransition();
+    const material = useResolvedSurface(color, options);
     const resolvedRadius = resolveRadius(radius ?? "medium", appearance);
     return createElement(Element, {
         ...properties,
         ref,
         style: {
-            ...visualTransition,
+            ...transition,
             ...style,
             background: "transparent",
             color: style?.color ?? material.foreground,
@@ -33,7 +34,7 @@ function useResolvedSurface(color, options) {
     return {
         ...material,
         color: useResolveColor(color),
-        foreground: useResolveTheme(appearance.colors.foreground)
+        foreground: useThemedValue(appearance.colors).foreground
     };
 }
 const layerStyle = {

package/dist/toggle-indicator.js

@@ -1,11 +1,12 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { motion, useReducedMotion } from "motion/react";
 import { useLocale } from "react-aria-components";
-import { controlTransition, visualTransition } from "./motion-style.js";
+import { useControlTransition } from "./motion-style.js";
 import { Surface } from "./surface.js";
 /** Shared paint only. Selection, focus, validation, and native input behavior belong to React Aria. */
 export function ToggleIndicator({ kind, selected, indeterminate = false, focused, invalid = false, hovered = false, pressed = false, theme, material: options }) {
     const reduced = useReducedMotion();
+    const transition = useControlTransition(Boolean(reduced));
     const { direction } = useLocale();
     const diameter = theme.fontSize + 6;
     const active = selected || indeterminate;
@@ -15,9 +16,9 @@ export function ToggleIndicator({ kind, selected, indeterminate = false, focused
     const switching = kind === "switch";
     const thumbWidth = diameter - 6 + (pressed && !reduced ? 3 : 0);
     const travel = (diameter * 2 - thumbWidth) / 2 - 3;
-    return _jsx(Surface, { as: motion.span, ...options, color: paint.background, "aria-hidden": "true", initial: false, animate: { scale: reduced || switching ? 1 : pressed ? 0.94 : hovered ? 1.03 : 1 }, transition: { ...controlTransition, duration: reduced ? 0 : controlTransition.duration }, style: {
+    return _jsx(Surface, { as: motion.span, material: options, color: paint.background, "aria-hidden": "true", initial: false, animate: { scale: reduced || switching ? 1 : pressed ? 0.94 : hovered ? 1.03 : 1 }, transition: transition, style: {
             color: paint.color,
-            ...visualTransition,
+            ...theme.transition,
             display: "inline-grid",
             placeItems: "center",
             position: "relative",
@@ -29,12 +30,12 @@ export function ToggleIndicator({ kind, selected, indeterminate = false, focused
             border: "none",
             outline: focused ? `2px solid ${theme.foreground}` : "none",
             outlineOffset: 2,
-        }, children: switching ? _jsx(motion.span, { initial: false, animate: { width: thumbWidth, x: (selected ? travel : -travel) * (direction === "rtl" ? -1 : 1) }, transition: { ...controlTransition, duration: reduced ? 0 : controlTransition.duration }, style: {
-                ...visualTransition,
+        }, children: switching ? _jsx(motion.span, { initial: false, animate: { width: thumbWidth, x: (selected ? travel : -travel) * (direction === "rtl" ? -1 : 1) }, transition: transition, style: {
+                ...theme.transition,
                 height: diameter - 6, borderRadius: diameter,
                 background: paint.color
-            } }) : _jsx(motion.span, { initial: false, animate: { opacity: active ? 1 : 0, scale: active ? 1 : 0.7 }, transition: { ...controlTransition, duration: reduced ? 0 : controlTransition.duration }, style: { display: "grid", placeItems: "center" }, children: kind === "radio" ? _jsx("span", { style: { ...visualTransition, width: diameter / 2, height: diameter / 2, borderRadius: "50%", background: "currentColor" } })
-                : _jsxs("svg", { width: diameter - 4, height: diameter - 4, viewBox: "0 0 16 16", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", children: [_jsx(motion.path, { d: "m3 8 3 3 7-7", initial: false, animate: { pathLength: selected && !indeterminate ? 1 : 0, opacity: selected && !indeterminate ? 1 : 0 }, transition: { ...controlTransition, duration: reduced ? 0 : controlTransition.duration } }), _jsx(motion.path, { d: "M4 8h8", initial: false, animate: { pathLength: indeterminate ? 1 : 0, opacity: indeterminate ? 1 : 0 }, transition: { ...controlTransition, duration: reduced ? 0 : controlTransition.duration } })] }) }) });
+            } }) : _jsx(motion.span, { initial: false, animate: { opacity: active ? 1 : 0, scale: active ? 1 : 0.7 }, transition: transition, style: { display: "grid", placeItems: "center" }, children: kind === "radio" ? _jsx("span", { style: { ...theme.transition, width: diameter / 2, height: diameter / 2, borderRadius: "50%", background: "currentColor" } })
+                : _jsxs("svg", { width: diameter - 4, height: diameter - 4, viewBox: "0 0 16 16", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", children: [_jsx(motion.path, { d: "m3 8 3 3 7-7", initial: false, animate: { pathLength: selected && !indeterminate ? 1 : 0, opacity: selected && !indeterminate ? 1 : 0 }, transition: transition }), _jsx(motion.path, { d: "M4 8h8", initial: false, animate: { pathLength: indeterminate ? 1 : 0, opacity: indeterminate ? 1 : 0 }, transition: transition })] }) }) });
 }
 export function toggleStyle(theme, disabled, readOnly) {
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/react-ui",
-  "version": "0.1.18",
+  "version": "0.1.19",
   "description": "React components for coherent PhreshOS Program interfaces.",
   "type": "module",
   "sideEffects": false,
@@ -45,18 +45,17 @@
   "scripts": {
     "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
     "check": "tsc --noEmit && tsc -p tsconfig.test.json",
-    "test": "vitest run --environment jsdom",
+    "test": "vitest run --project default",
     "build": "node --run clean && tsc --noEmit false --outDir dist --rootDir source",
-    "verify:package": "node scripts/verify-package.mjs",
-    "verify": "node --run check && node --run test && node --run build && node --run verify:package",
-    "prepack": "node --run test && node --run build"
+    "verify": "node --run check && node --run build && node --run test",
+    "prepack": "node --run build"
   },
   "peerDependencies": {
     "react": "^19.2.0",
     "react-dom": "^19.2.0"
   },
   "dependencies": {
-    "@phreshos/core": "^0.1.42",
+    "@phreshos/core": "^0.1.43",
     "colorjs.io": "^0.7.1",
     "motion": "^13.2.0",
     "react-aria-components": "^1.20.0"
@@ -72,6 +71,6 @@
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.1"
+    "vitest": "^4.1.10"
   }
 }