@phreshos/react-ui 0.1.17 → 0.1.19

package/README.md

@@ -54,9 +54,9 @@ import { AppearanceProvider, Button } from "@phreshos/react-ui"
 ```
 
 `Button`, `Input`, `Textarea`, `Select`, `Checkbox`, `Switch`, and `Radio`
-host the shared Material while retaining their native behavior. Color and material
+use the shared Surface implementation while retaining their native behavior. Color and material
 are independent inputs. `color` accepts an Appearance color and resting level such
-as `background:base` or `primary:soft`, or a direct CSS color. Material and neutral
+as `background:base` or `primary:soft`, or a direct CSS color. Surface and neutral
 surface hosts default to `background:base`; a component may select a semantic
 default required by its own behavior, such as `primary:base` for selection.
 Hover and press derive shades of that fill. The resting fill chooses the
@@ -72,40 +72,34 @@ spacing and radius follow Appearance. `disabled` prevents activation and focus;
 <Button color="danger:soft" size="small">Delete</Button>
 ```
 
-`Material` is the raw visual substance: paint, opacity, frost, refraction, and
-grain. It fills the geometry of its nearest positioned container,
-inherits that container's radius, and adds no content, layout, interaction, or
-shadow. The container must establish its own geometry and isolation.
-
-```tsx
-<div style={{ position: "relative", isolation: "isolate", width: 240, height: 120, borderRadius: 18 }}>
-  <Material color="background:soft" material={{ opacity: 0.4 }} />
-</div>
-```
-
-`Surface` is the standard geometric host for a `Material`. It establishes the
-required positioning and isolation on a `div`, resolves radius, renders Material,
-and then renders its content. It never creates or consumes a shadow. Shadow remains
-an independent visual concern. `radius` accepts a size level, a number in pixels,
-or a CSS radius and defaults to `medium`.
+`Surface` is the material-owning element. It renders a `div` by default, while
+`as` selects another React element and preserves that element's native properties
+and ref type. Surface owns its paint, opacity, frost, refraction, grain, edge,
+radius, and clipping requirements. It never creates or consumes a shadow; shadow
+remains an independent visual concern. `radius` accepts a size level, a number in
+pixels, or a CSS radius and defaults to `medium`.
 
 ```tsx
 <Surface color="background:soft" radius="large">Derived values</Surface>
-<Surface color="#345678" radius={18}>Direct values</Surface>
+<Surface as="button" type="button" color="#345678" radius={18}>Action</Surface>
+<Surface as={Grid} columns={3} gap="medium">Grid content</Surface>
 ```
 
-`MaterialOptions` defines `opacity`, `backdrop`, `grain`, `grainAmount`,
-`distortion`, and `saturation`. It contains no color. `MaterialProps` keeps
-`color` beside `material?: MaterialOptions`, so paint selection never becomes a
-physical-material setting. Omitted material values follow `appearance.material`.
-Effect options accept a scale level or a direct number; opacity affects material
-only, never the host's children.
-
-Radius belongs to host geometry, while Surface's border belongs to its geometric
-boundary. Material may determine the border treatment, but it neither owns nor
-renders that border.
+`as` can also select an outside React component. A valid Surface host preserves
+the `style` and `children` it receives on one host element and forwards its ref
+to that same element. This lets layout components carry the material without a
+wrapper. The host retains ownership of its own behavior and layout properties;
+Surface retains ownership of material, edge, radius, and required geometry.
 
-Material-bearing controls expose the same separate `color` and `material` props.
+`MaterialOptions` defines `opacity`, `backdrop`, `grain`, `grainAmount`,
+`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.
+
+Surface-based controls expose the same separate `color` and `material` props.
 For text fields and Select, `material` targets the field or trigger; for Checkbox,
 Switch, and Radio, it targets the indicator. RadioGroup supplies material defaults
 to its options, and a Radio can override them.
@@ -145,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
-radius. Material fill and opacity transition on the painted layers, not on the
+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.
@@ -222,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.d.ts

@@ -3,7 +3,7 @@ import type { ButtonProps as AriaButtonProps } from "react-aria-components";
 import type { ScaleLevel } from "./scale.js";
 import type { RadiusProps } from "./radius.js";
 import { type ControlColor } from "./control.js";
-import type { MaterialOverrides } from "./material.js";
+import type { MaterialOverrides } from "./material-options.js";
 type NativeButtonProps = Omit<AriaButtonProps, "children" | "className" | "color" | "isDisabled" | "isPending" | "onClick" | "onPress" | "style">;
 /** A semantic color from Appearance; omission uses background and foreground. */
 export type ButtonColor = ControlColor;

package/dist/button.js

@@ -2,12 +2,11 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { forwardRef } from "react";
 import { Button as AriaButton } from "react-aria-components";
 import { controlFontSizes, useControlTheme } from "./control.js";
-import { MaterialButton } from "./control-material.js";
-import { visualTransition } from "./motion-style.js";
+import { SurfaceButton } from "./control-surface.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 });
-    return _jsx(AriaButton, { ...properties, ref: ref, type: type, isDisabled: disabled, isPending: pending, onPress: onPress, render: (native, state) => _jsx(MaterialButton, { native: native, material: material, paint: buttonPaint(theme, !disabled && !pending, state.isHovered, state.isPressed) }), style: ({ isFocusVisible, isHovered, isPressed }) => buttonStyle({
+    return _jsx(AriaButton, { ...properties, ref: ref, type: type, isDisabled: disabled, isPending: pending, onPress: onPress, render: (native, state) => _jsx(SurfaceButton, { native: native, material: material, paint: buttonPaint(theme, !disabled && !pending, state.isHovered, state.isPressed) }), style: ({ isFocusVisible, isHovered, isPressed }) => buttonStyle({
             theme,
             disabled,
             isFocusVisible,
@@ -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/checkbox.d.ts

@@ -1,6 +1,6 @@
 import type { CheckboxFieldProps } from "react-aria-components";
 import type { ControlOverrides, ControlProps, FieldProps } from "./control.js";
-import type { MaterialOverrides } from "./material.js";
+import type { MaterialOverrides } from "./material-options.js";
 export interface CheckboxProps extends Omit<CheckboxFieldProps, ControlOverrides | "isReadOnly" | "isSelected" | "defaultSelected" | "isIndeterminate">, ControlProps, FieldProps, MaterialOverrides {
     readonly checked?: boolean;
     readonly defaultChecked?: boolean;

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-material.d.ts → control-surface.d.ts}

@@ -4,14 +4,14 @@ type Paint = Readonly<{
     background: string;
     color: string;
 }>;
-/** A native button hosts Material without changing its native contract. */
-export declare function MaterialButton({ native, paint, material: options }: {
+/** A native button uses Surface without changing its native contract. */
+export declare function SurfaceButton({ native, paint, material: options }: {
     readonly native: ComponentPropsWithRef<"button">;
     readonly paint: Paint;
     readonly material?: MaterialOptions;
 }): import("react").JSX.Element;
 /** Void text controls use a material host while retaining native sizing. */
-export declare function MaterialField({ paint, radius, children, material: options }: Readonly<{
+export declare function SurfaceField({ paint, radius, children, material: options }: Readonly<{
     paint: Paint;
     radius: CSSProperties["borderRadius"];
     children: ReactNode;

package/dist/control-surface.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+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, 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, { 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/input.js

@@ -2,10 +2,10 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { forwardRef } from "react";
 import { Input as AriaInput, TextField } from "react-aria-components";
 import { controlPaint, controlStyle, FieldFeedback, FieldLabel, fieldStyle, useControlTheme } from "./control.js";
-import { MaterialField } from "./control-material.js";
+import { SurfaceField } from "./control-surface.js";
 import FieldStyle, { textControlClass } from "./field-style.js";
 /** A labeled single-line text control. onChange receives the string value. */
 export const Input = forwardRef(function Input({ label, description, errorMessage, disabled, readOnly, required, invalid, size, color, radius, style, className, placeholder, material, ...properties }, ref) {
     const theme = useControlTheme({ size, color, radius });
-    return _jsxs(TextField, { ...properties, className: className, isDisabled: disabled, isReadOnly: readOnly, isRequired: required, isInvalid: invalid, style: fieldStyle(theme, disabled, style), children: [_jsx(FieldStyle, {}), _jsx(FieldLabel, { label: label }), _jsx(AriaInput, { ref: ref, placeholder: placeholder, className: textControlClass, render: (native, state) => _jsx(MaterialField, { material: material, radius: theme.radius, paint: controlPaint(theme, state.isFocused, state.isInvalid, state.isHovered), children: _jsx("input", { ...native, style: { ...native.style, borderRadius: "inherit", background: "transparent" } }) }), style: state => controlStyle(theme, state.isFocused, state.isInvalid, state.isHovered, state.isFocusVisible) }), _jsx(FieldFeedback, { theme: theme, description: description, errorMessage: errorMessage })] });
+    return _jsxs(TextField, { ...properties, className: className, isDisabled: disabled, isReadOnly: readOnly, isRequired: required, isInvalid: invalid, style: fieldStyle(theme, disabled, style), children: [_jsx(FieldStyle, {}), _jsx(FieldLabel, { label: label }), _jsx(AriaInput, { ref: ref, placeholder: placeholder, className: textControlClass, render: (native, state) => _jsx(SurfaceField, { material: material, radius: theme.radius, paint: controlPaint(theme, state.isFocused, state.isInvalid, state.isHovered), children: _jsx("input", { ...native, style: { ...native.style, borderRadius: "inherit", background: "transparent" } }) }), style: state => controlStyle(theme, state.isFocused, state.isInvalid, state.isHovered, state.isFocusVisible) }), _jsx(FieldFeedback, { theme: theme, description: description, errorMessage: errorMessage })] });
 });

package/dist/main.d.ts

@@ -5,11 +5,10 @@
  * 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 { Material, type MaterialOptions, type MaterialOverrides, type MaterialProps } from "./material.js";
-export { Surface, type SurfaceProps } from "./surface.js";
+export { Surface, type MaterialOptions, type SurfaceComponent, type SurfaceHost, type SurfaceHostProps, type SurfaceOwnProps, type SurfaceProps } from "./surface.js";
 export { defaultColor, type Color, type ColorLevel, type ColorScale } from "./color.js";
 export { Panel, type PanelProps } from "./panel.js";
 export { Button, type ButtonColor, type ButtonProps } from "./button.js";

package/dist/main.js

@@ -5,10 +5,9 @@
  * 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 { Material } from "./material.js";
 export { Surface } from "./surface.js";
 export { defaultColor } from "./color.js";
 export { Panel } from "./panel.js";

package/dist/material-options.d.ts

@@ -8,7 +8,11 @@ export interface MaterialOptions {
     readonly distortion?: ScaleLevel | number;
     readonly saturation?: ScaleLevel | number;
 }
-/** Resolves Material values from the current Appearance without knowing any host geometry. */
+/** Grouped material customization exposed by components built on Surface. */
+export interface MaterialOverrides {
+    readonly material?: MaterialOptions;
+}
+/** Resolves material values from the current Appearance without knowing any host geometry. */
 export declare function useMaterialOptions(values?: MaterialOptions): {
     opacity: number;
     backdrop: number;

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. */
+/** 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.d.ts

@@ -6,6 +6,6 @@ interface MaterialPaintProps {
     readonly identity: string;
     readonly opacity: number;
 }
-/** The fill, refraction definition, and grain of one Material. */
+/** The fill, refraction definition, and grain of one Surface. */
 export declare function MaterialPaint({ color, distortion, grain, grainAmount, identity, opacity }: MaterialPaintProps): import("react").JSX.Element | null;
 export {};

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";
-/** The fill, refraction definition, and grain of one Material. */
+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/radio.d.ts

@@ -1,7 +1,7 @@
 import type { ReactNode } from "react";
 import type { RadioGroupProps as AriaRadioGroupProps, RadioFieldProps } from "react-aria-components";
 import type { ControlOverrides, ControlProps, FieldProps } from "./control.js";
-import type { MaterialOverrides } from "./material.js";
+import type { MaterialOverrides } from "./material-options.js";
 export interface RadioGroupProps extends Omit<AriaRadioGroupProps, ControlOverrides | "isReadOnly">, ControlProps, FieldProps, MaterialOverrides {
     readonly children: ReactNode;
     readonly readOnly?: boolean;

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.d.ts

@@ -1,7 +1,7 @@
 import type { SelectProps as AriaSelectProps } from "react-aria-components";
 import type { ControlOverrides, ControlProps, FieldProps } from "./control.js";
 import type { RadiusProps } from "./radius.js";
-import type { MaterialOverrides } from "./material.js";
+import type { MaterialOverrides } from "./material-options.js";
 export interface SelectOption {
     readonly value: string;
     readonly label: string;

package/dist/select.js

@@ -3,19 +3,21 @@ import { forwardRef } from "react";
 import { motion, useReducedMotion } from "motion/react";
 import { Select as AriaSelect, Button, SelectValue, Popover, ListBox, ListBoxItem } from "react-aria-components";
 import { controlPaint, controlStyle, FieldFeedback, FieldLabel, fieldStyle, useControlTheme } from "./control.js";
-import { MaterialButton } from "./control-material.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();
-    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(MaterialButton, { native: native, material: material, paint: controlPaint(theme, state.isOpen || button.isFocused, state.isInvalid, button.isHovered) }), style: button => ({
+    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.d.ts

@@ -1,5 +1,8 @@
-import type { ResolvedMaterial } from "./material.js";
-type EdgeMaterial = Pick<ResolvedMaterial, "color" | "foreground" | "opacity">;
+type EdgeMaterial = Readonly<{
+    color: string;
+    foreground: string;
+    opacity: number;
+}>;
 /** Paints the boundary owned by one Surface from the material it contains. */
 export declare function SurfaceEdge({ material }: Readonly<{
     material: EdgeMaterial;

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,7 +1,23 @@
-import type { ComponentPropsWithRef } from "react";
-import { type MaterialProps } from "./material.js";
+import type { ComponentPropsWithRef, CSSProperties, ElementType, ReactElement, ReactNode } from "react";
+import { type Color } from "./color.js";
+import { type MaterialOverrides } from "./material-options.js";
 import { type RadiusProps } from "./radius.js";
-/** A div that hosts one Material and owns its geometry. */
-export interface SurfaceProps extends Omit<ComponentPropsWithRef<"div">, "color">, MaterialProps, RadiusProps {
+export type { MaterialOptions } from "./material-options.js";
+export interface SurfaceOwnProps extends MaterialOverrides, RadiusProps {
+    readonly color?: Color;
 }
-export declare const Surface: import("react").ForwardRefExoticComponent<Omit<SurfaceProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
+/**
+ * The structural properties a component must preserve when it hosts a Surface.
+ * The component must apply `style` and render `children` on the same host element,
+ * and it must forward its ref to that element.
+ */
+export interface SurfaceHostProps {
+    readonly children?: ReactNode;
+    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;
+export declare const Surface: SurfaceComponent;

package/dist/surface.js

@@ -1,21 +1,63 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { forwardRef } from "react";
-import { useAppearance } from "./appearance-provider.js";
-import { MaterialLayer, useResolvedMaterial } from "./material.js";
-import { visualTransition } from "./motion-style.js";
+import { createElement, forwardRef, useId } from "react";
+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, { useVisualTransition } from "./motion-style.js";
 import { resolveRadius } from "./radius.js";
 import { SurfaceEdge } from "./surface-edge.js";
-export const Surface = forwardRef(function Surface({ color, material: options, radius, children, style, ...properties }, ref) {
+/** One material-owning element. The host is a div unless `as` selects another element. */
+const SurfaceRoot = forwardRef(function Surface({ as: Element = "div", color, material: options, radius, children, style, ...properties }, ref) {
     const appearance = useAppearance();
-    const material = useResolvedMaterial({ color, material: options });
+    const transition = useVisualTransition();
+    const material = useResolvedSurface(color, options);
     const resolvedRadius = resolveRadius(radius ?? "medium", appearance);
-    return _jsxs("div", { ...properties, ref: ref, style: {
-            ...visualTransition,
-            background: "transparent",
-            color: material.foreground,
+    return createElement(Element, {
+        ...properties,
+        ref,
+        style: {
+            ...transition,
             ...style,
+            background: "transparent",
+            color: style?.color ?? material.foreground,
             borderRadius: radius === undefined ? style?.borderRadius ?? resolvedRadius : resolvedRadius,
             position: style?.position ?? "relative",
             isolation: "isolate"
-        }, children: [_jsx(MaterialLayer, { material: material }), _jsx(SurfaceEdge, { material: material }), children] });
+        }
+    }, _jsx(SurfaceLayers, { material: material }), _jsx(SurfaceEdge, { material: material }), children);
 });
+export const Surface = SurfaceRoot;
+function useResolvedSurface(color, options) {
+    const appearance = useAppearance();
+    const material = useMaterialOptions(options);
+    return {
+        ...material,
+        color: useResolveColor(color),
+        foreground: useThemedValue(appearance.colors).foreground
+    };
+}
+const layerStyle = {
+    position: "absolute",
+    inset: 0,
+    borderRadius: "inherit",
+    pointerEvents: "none"
+};
+function SurfaceLayers({ material }) {
+    const { backdrop, saturation, distortion } = material;
+    const frost = [
+        backdrop === 0 ? "" : `blur(${backdrop}px)`,
+        saturation === 1 ? "" : `saturate(${saturation})`
+    ].filter(Boolean).join(" ");
+    const identity = `phresh-material-${useId().replaceAll(":", "")}`;
+    return _jsxs("span", { "data-material": "", "aria-hidden": "true", style: layerStyle, children: [_jsx(MotionStyle, {}), distortion > 0 && _jsx(BackdropLayer, { name: "refraction", filter: `url("#${identity}-distortion")`, zIndex: -3 }), frost && _jsx(BackdropLayer, { name: "frost", filter: frost, zIndex: -2 }), _jsx(MaterialPaint, { identity: identity, distortion: distortion, color: material.color, grain: material.grain, grainAmount: material.grainAmount, opacity: material.opacity })] });
+}
+/** Keep refraction and native frost in independent compositor passes. */
+function BackdropLayer({ filter, name, zIndex }) {
+    return _jsx("span", { "data-material-backdrop": name, "aria-hidden": "true", style: {
+            ...layerStyle,
+            zIndex,
+            backdropFilter: filter,
+            WebkitBackdropFilter: filter
+        } });
+}

package/dist/switch.d.ts

@@ -1,6 +1,6 @@
 import type { SwitchFieldProps } from "react-aria-components";
 import type { ControlOverrides, ControlProps, FieldProps } from "./control.js";
-import type { MaterialOverrides } from "./material.js";
+import type { MaterialOverrides } from "./material-options.js";
 export interface SwitchProps extends Omit<SwitchFieldProps, ControlOverrides | "isReadOnly" | "isSelected" | "defaultSelected">, ControlProps, FieldProps, MaterialOverrides {
     readonly checked?: boolean;
     readonly defaultChecked?: boolean;

package/dist/text-control.d.ts

@@ -1,7 +1,7 @@
 import type { TextFieldProps } from "react-aria-components";
 import type { ControlOverrides, ControlProps, FieldProps } from "./control.js";
 import type { RadiusProps } from "./radius.js";
-import type { MaterialOverrides } from "./material.js";
+import type { MaterialOverrides } from "./material-options.js";
 /** Shared contract for native text-entry controls. */
 export interface TextControlProps extends Omit<TextFieldProps, ControlOverrides | "isReadOnly">, ControlProps, FieldProps, RadiusProps, MaterialOverrides {
     readonly placeholder?: string;

package/dist/textarea.js

@@ -2,12 +2,12 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { forwardRef } from "react";
 import { TextArea as AriaTextarea, TextField } from "react-aria-components";
 import { controlPaint, controlStyle, FieldFeedback, FieldLabel, fieldStyle, useControlTheme } from "./control.js";
-import { MaterialField } from "./control-material.js";
+import { SurfaceField } from "./control-surface.js";
 import FieldStyle, { textControlClass } from "./field-style.js";
 /** A labeled multiline text control, vertically resizable without escaping its width. */
 export const Textarea = forwardRef(function Textarea({ label, description, errorMessage, disabled, readOnly, required, invalid, size, color, radius, style, className, placeholder, rows = 4, material, ...properties }, ref) {
     const theme = useControlTheme({ size, color, radius });
-    return _jsxs(TextField, { ...properties, className: className, isDisabled: disabled, isReadOnly: readOnly, isRequired: required, isInvalid: invalid, style: fieldStyle(theme, disabled, style), children: [_jsx(FieldStyle, {}), _jsx(FieldLabel, { label: label }), _jsx(AriaTextarea, { ref: ref, placeholder: placeholder, rows: rows, className: textControlClass, render: (native, state) => _jsx(MaterialField, { material: material, radius: theme.radius, paint: controlPaint(theme, state.isFocused, state.isInvalid, state.isHovered), children: _jsx("textarea", { ...native, style: { ...native.style, borderRadius: "inherit", background: "transparent" } }) }), style: state => ({
+    return _jsxs(TextField, { ...properties, className: className, isDisabled: disabled, isReadOnly: readOnly, isRequired: required, isInvalid: invalid, style: fieldStyle(theme, disabled, style), children: [_jsx(FieldStyle, {}), _jsx(FieldLabel, { label: label }), _jsx(AriaTextarea, { ref: ref, placeholder: placeholder, rows: rows, className: textControlClass, render: (native, state) => _jsx(SurfaceField, { material: material, radius: theme.radius, paint: controlPaint(theme, state.isFocused, state.isInvalid, state.isHovered), children: _jsx("textarea", { ...native, style: { ...native.style, borderRadius: "inherit", background: "transparent" } }) }), style: state => ({
                     ...controlStyle(theme, state.isFocused, state.isInvalid, state.isHovered, state.isFocusVisible),
                     height: "auto",
                     minHeight: theme.height,

package/dist/toggle-indicator.js

@@ -1,12 +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 { MaterialLayer, useResolvedMaterial } from "./material.js";
-import { SurfaceEdge } from "./surface-edge.js";
-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;
@@ -16,11 +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;
-    const material = useResolvedMaterial({ color: paint.background, material: options });
-    return _jsxs(motion.span, { "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,
-            background: "transparent",
+            ...theme.transition,
             display: "inline-grid",
             placeItems: "center",
             position: "relative",
@@ -32,12 +30,12 @@ export function ToggleIndicator({ kind, selected, indeterminate = false, focused
             border: "none",
             outline: focused ? `2px solid ${theme.foreground}` : "none",
             outlineOffset: 2,
-        }, children: [_jsx(MaterialLayer, { material: material }), _jsx(SurfaceEdge, { material: material }), 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,
-                    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 } })] }) })] });
+        }, 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: 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.17",
+  "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"
   }
 }

package/dist/control-material.js

@@ -1,14 +0,0 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { MaterialLayer, useResolvedMaterial } from "./material.js";
-import { SurfaceEdge } from "./surface-edge.js";
-/** A native button hosts Material without changing its native contract. */
-export function MaterialButton({ native, paint, material: options }) {
-    const { ref, style, children, ...properties } = native;
-    const material = useResolvedMaterial({ color: paint.background, material: options });
-    return _jsxs("button", { ...properties, ref: ref, style: { ...style, background: "transparent", color: paint.color, position: style?.position ?? "relative", isolation: "isolate" }, children: [_jsx(MaterialLayer, { material: material }), _jsx(SurfaceEdge, { material: material }), children] });
-}
-/** Void text controls use a material host while retaining native sizing. */
-export function MaterialField({ paint, radius, children, material: options }) {
-    const material = useResolvedMaterial({ color: paint.background, material: options });
-    return _jsxs("span", { style: { color: paint.color, display: "grid", minWidth: 0, borderRadius: radius, position: "relative", isolation: "isolate" }, children: [_jsx(MaterialLayer, { material: material }), _jsx(SurfaceEdge, { material: material }), children] });
-}

package/dist/material.d.ts

@@ -1,27 +0,0 @@
-import { type MaterialOptions } from "./material-options.js";
-import { type Color } from "./color.js";
-export type { MaterialOptions } from "./material-options.js";
-/** Visual substance without host layout, content, interaction, or shadow. */
-export interface MaterialProps {
-    readonly color?: Color;
-    readonly material?: MaterialOptions;
-}
-export interface MaterialOverrides {
-    readonly material?: MaterialOptions;
-}
-/** Fill the geometry of the nearest positioned host with the resolved material. */
-export declare function Material(options?: MaterialProps): import("react").JSX.Element;
-export declare function useResolvedMaterial({ color, material: options }?: MaterialProps): {
-    color: string;
-    foreground: string;
-    opacity: number;
-    backdrop: number;
-    grain: number;
-    grainAmount: number;
-    distortion: number;
-    saturation: number;
-};
-export type ResolvedMaterial = ReturnType<typeof useResolvedMaterial>;
-export declare function MaterialLayer({ material }: Readonly<{
-    material: ResolvedMaterial;
-}>): import("react").JSX.Element;

package/dist/material.js

@@ -1,45 +0,0 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useId } from "react";
-import { useMaterialOptions } from "./material-options.js";
-import { useAppearance, useResolveTheme } from "./appearance-provider.js";
-import { useResolveColor } from "./color.js";
-import { MaterialPaint } from "./material-paint.js";
-import MotionStyle from "./motion-style.js";
-const layerStyle = {
-    position: "absolute",
-    inset: 0,
-    borderRadius: "inherit",
-    pointerEvents: "none"
-};
-/** Fill the geometry of the nearest positioned host with the resolved material. */
-export function Material(options = {}) {
-    const material = useResolvedMaterial(options);
-    return _jsx(MaterialLayer, { material: material });
-}
-export function useResolvedMaterial({ color, material: options } = {}) {
-    const appearance = useAppearance();
-    const material = useMaterialOptions(options);
-    return {
-        ...material,
-        color: useResolveColor(color),
-        foreground: useResolveTheme(appearance.colors.foreground)
-    };
-}
-export function MaterialLayer({ material }) {
-    const { backdrop, saturation, distortion } = material;
-    const frost = [
-        backdrop === 0 ? "" : `blur(${backdrop}px)`,
-        saturation === 1 ? "" : `saturate(${saturation})`
-    ].filter(Boolean).join(" ");
-    const identity = `phresh-material-${useId().replaceAll(":", "")}`;
-    return _jsxs("span", { "data-material": "", "aria-hidden": "true", style: layerStyle, children: [_jsx(MotionStyle, {}), distortion > 0 && _jsx(BackdropLayer, { name: "refraction", filter: `url("#${identity}-distortion")`, zIndex: -3 }), frost && _jsx(BackdropLayer, { name: "frost", filter: frost, zIndex: -2 }), _jsx(MaterialPaint, { identity: identity, distortion: distortion, color: material.color, grain: material.grain, grainAmount: material.grainAmount, opacity: material.opacity })] });
-}
-/** Keep refraction and native frost in independent compositor passes. */
-function BackdropLayer({ filter, name, zIndex }) {
-    return _jsx("span", { "data-material-backdrop": name, "aria-hidden": "true", style: {
-            ...layerStyle,
-            zIndex,
-            backdropFilter: filter,
-            WebkitBackdropFilter: filter
-        } });
-}