@phreshos/react-ui 0.1.16 → 0.1.18

package/README.md

@@ -25,22 +25,90 @@ applications own composition.
 | Bun | `bun add @phreshos/react-ui` |
 | Yarn | `yarn add @phreshos/react-ui` |
 
-`@phreshos/core`, React, and React DOM are peer dependencies.
+Core is a built-in runtime dependency. React and React DOM remain peer
+dependencies because the application and React UI must share one React
+runtime.
 
 ```tsx
-import { standardAppearance } from "@phreshos/core"
-import { AppearanceProvider, Button, Surface } from "@phreshos/react-ui"
+import { Button, Surface } from "@phreshos/react-ui"
 
-<AppearanceProvider appearance={standardAppearance} theme="light">
-  <Surface>
-    <Button>Continue</Button>
-  </Surface>
-</AppearanceProvider>
+<Surface>
+  <Button>Continue</Button>
+</Surface>
 ```
 
+Without a provider, components use Core's `defaultAppearance` and reactively
+follow the browser color scheme. `AppearanceProvider` independently overrides
+either value for a subtree; omitted values inherit from the nearest provider.
+React UI also exports that same canonical `defaultAppearance` value for callers
+that need it explicitly.
 See [Appearance](https://docs.phreshos.com/system/appearance) for the contract
 interpreted by the provider and components.
 
+```tsx
+import { AppearanceProvider, Button } from "@phreshos/react-ui"
+
+<AppearanceProvider theme="dark">
+  <Button>Dark subtree</Button>
+</AppearanceProvider>
+```
+
+`Button`, `Input`, `Textarea`, `Select`, `Checkbox`, `Switch`, and `Radio`
+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. 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
+higher-contrast text from Appearance's background and foreground once; interaction
+shades keep that choice.
+`size` accepts `xsmall`, `small`, `medium` (default), `large`, or `xlarge`;
+spacing and radius follow Appearance. `disabled` prevents activation and focus;
+`pending` prevents activation while retaining focus.
+
+```tsx
+<Button>Cancel</Button>
+<Button color="primary:base" onPress={save}>Save</Button>
+<Button color="danger:soft" size="small">Delete</Button>
+```
+
+`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 as="button" type="button" color="#345678" radius={18}>Action</Surface>
+<Surface as={Grid} columns={3} gap="medium">Grid content</Surface>
+```
+
+`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.
+
+`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
+`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.
+
+```tsx
+<Button color="primary:base" material={{ opacity: 0.6, backdrop: 0 }}>Save</Button>
+<Input label="Name" radius="large" material={{ grain: "small" }} />
+```
+
 `Panel` composes an outer `Surface`, an optional header, and an inset content
 `Surface`. Both materials retain Surface defaults; the content inset follows
 Appearance spacing. Positioning, modality, and lifecycle belong to the caller.
@@ -56,6 +124,88 @@ import { Panel } from "@phreshos/react-ui"
 Native properties and the forwarded ref target the outer Surface.
 `contentProps` targets the inner Surface; `children` supplies its content.
 
+## Inputs
+
+Every input uses Appearance colors and the same five `size` levels as Button.
+`color` selects the fill independently from material. Input, Textarea, Select,
+and Button use `background:base` when it is omitted; selection indicators use
+`primary:base`. Invalid
+fields use danger instead. Text fields share Surface's glass edge. Interaction shades
+derive from the base color's lightness, and text or selection marks use whichever
+Appearance background or foreground has higher contrast against the base fill.
+That text or mark color stays unchanged across interaction shades.
+These are component-owned derivations, not additional Appearance settings.
+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. 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.
+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.
+
+Motion animates toggle presses, selection marks, switch travel, the Select
+chevron, and Slider thumb feedback. Reduced-motion preferences remove spatial
+feedback and make state transitions immediate. Slider values and native input
+behavior are never delayed by visual animation.
+
+| Component | Value contract | Purpose |
+| --- | --- | --- |
+| `Input` | `value`, `defaultValue`, `onChange(string)` | Single-line text; supports text, email, password, search, URL, and telephone types |
+| `Textarea` | `value`, `defaultValue`, `onChange(string)` | Multiline text; four rows by default, vertically resizable |
+| `Checkbox` | `checked`, `defaultChecked`, `onChange(boolean)` | Independent selection; `indeterminate` represents a mixed state |
+| `Switch` | `checked`, `defaultChecked`, `onChange(boolean)` | An on/off setting |
+| `RadioGroup` / `Radio` | Group `value`, `defaultValue`, `onChange(string)`; Radio `value` | One exclusive choice; vertical by default, optionally horizontal |
+| `Select` | `value: string \| null`, `defaultValue`, `onChange(string \| null)` | One choice from `options: { value, label, disabled? }[]` |
+| `Slider` | `value`, `defaultValue`, `onChange(number)` | One numeric value; `minValue`, `maxValue`, `step`, and `onChangeEnd`; horizontal by default |
+
+Use `label` for visible labels, or `aria-label` / `aria-labelledby` for an
+accessible name without visible text. `description` provides associated help.
+`disabled` prevents interaction and removes the control from keyboard focus.
+`name` participates in native form submission. Controlled values remain owned
+by the caller; omit them and use defaults for internal state and form reset.
+
+Text fields, Checkbox, Switch, and RadioGroup also support `readOnly`: the
+value cannot change, but the control remains focusable. These fields and
+Select support `required`, `invalid`, `errorMessage`, and React Aria's native
+or ARIA validation behavior. A Radio's selection and validation belong to its
+group. Slider represents a bounded number rather than a required text or
+choice field, and has no read-only or validation-error mode. Select has no
+read-only mode; disable it when selection must be unavailable.
+
+`Input`, `Textarea`, and `Select` accept `radius`. Other inputs retain their
+intrinsic indicator shapes. `className` and `style` address the field's root;
+default visual properties remain component-owned. Input and Textarea refs
+target their native text controls; other refs target the root div. Checkbox,
+Switch, and Radio additionally accept `inputRef` for their native input.
+
+```tsx
+import { Input, Textarea, Checkbox, Radio, RadioGroup, Switch, Select, Slider } from "@phreshos/react-ui"
+
+<Input label="Name" name="name" required />
+<Textarea label="Description" name="description" />
+<Checkbox label="Remember this choice" name="remember" />
+<Switch label="Notifications" name="notifications" defaultChecked />
+<RadioGroup label="Layout" name="layout" defaultValue="grid">
+  <Radio label="Grid" value="grid" />
+  <Radio label="List" value="list" />
+</RadioGroup>
+<Select label="Sort" name="sort" options={[
+  { value: "name", label: "Name" },
+  { value: "date", label: "Date" }
+]} />
+<Slider label="Volume" name="volume" defaultValue={50} minValue={0} maxValue={100} step={1} />
+```
+
+React Aria owns focus, keyboard, form, and selection behavior. Select's popup
+uses Surface defaults. Toggle indicators use Motion internally and respect
+reduced-motion preferences. The preview Program demonstrates each input's
+sizes, colors, state, and interaction without overriding its visual defaults.
+
 ## Development
 
 ```sh

package/dist/appearance-provider.d.ts

@@ -1,17 +1,15 @@
 import type { ReactNode } from "react";
-import type { Appearance, Theme, ThemedValue } from "@phreshos/core";
-/** Provides unresolved Appearance and one effective Theme to a React subtree. */
+import { type Appearance, type Theme, type ThemedValue } from "@phreshos/core";
+/** 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 complete unresolved Appearance supplied by the nearest provider. */
+/** Returns the nearest unresolved Appearance, or Core's complete default. */
 export declare function useAppearance(): Appearance;
-/** Returns the effective Theme supplied by the nearest provider. */
+/** 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>;
-/** Internal optional read for primitives that also accept direct values. */
-export declare function useAppearanceIfAvailable(): Appearance | null;
 export interface AppearanceProviderProps {
-    readonly appearance: Appearance;
+    readonly appearance?: Appearance;
     readonly children: ReactNode;
-    readonly theme: Theme;
+    readonly theme?: Theme;
 }

package/dist/appearance-provider.js

@@ -1,34 +1,49 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { createContext, useContext } from "react";
+import { createContext, useContext, useSyncExternalStore } from "react";
+import { defaultAppearance } from "@phreshos/core";
 import DocumentScrollbars from "./document-scrollbars.js";
-const missing = Symbol("AppearanceProvider");
-const AppearanceContext = createContext(missing);
-const ThemeContext = createContext(missing);
-/** Provides unresolved Appearance and one effective Theme to a React subtree. */
+import MotionStyle from "./motion-style.js";
+const AppearanceContext = createContext(defaultAppearance);
+const ThemeContext = createContext(null);
+/** Optionally overrides unresolved Appearance and effective Theme for a React subtree. */
 export function AppearanceProvider({ appearance, children, theme }) {
-    return _jsx(AppearanceContext.Provider, { value: appearance, children: _jsxs(ThemeContext.Provider, { value: theme, children: [_jsx(DocumentScrollbars, { appearance: appearance, theme: theme }), children] }) });
+    const inheritedAppearance = useAppearance();
+    const inheritedTheme = useTheme();
+    const resolvedAppearance = appearance ?? inheritedAppearance;
+    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 complete unresolved Appearance supplied by the nearest provider. */
+/** Returns the nearest unresolved Appearance, or Core's complete default. */
 export function useAppearance() {
-    const appearance = useContext(AppearanceContext);
-    if (appearance === missing)
-        throw new Error("useAppearance() requires an AppearanceProvider");
-    return appearance;
+    return useContext(AppearanceContext);
 }
-/** Returns the effective Theme supplied by the nearest provider. */
+/** Returns the nearest explicit Theme, or reactively follows the browser. */
 export function useTheme() {
     const theme = useContext(ThemeContext);
-    if (theme === missing)
-        throw new Error("useTheme() requires an AppearanceProvider");
-    return theme;
+    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);
 }
-/** Internal optional read for primitives that also accept direct values. */
-export function useAppearanceIfAvailable() {
-    const appearance = useContext(AppearanceContext);
-    return appearance === missing ? null : appearance;
+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

@@ -1,12 +1,18 @@
 import type { CSSProperties, ReactNode } from "react";
 import type { ButtonProps as AriaButtonProps } from "react-aria-components";
-import { type ScaleLevel } from "./scale.js";
-import { type RadiusProps } from "./radius.js";
-type NativeButtonProps = Omit<AriaButtonProps, "children" | "className" | "isDisabled" | "isPending" | "onClick" | "onPress" | "style">;
+import type { ScaleLevel } from "./scale.js";
+import type { RadiusProps } from "./radius.js";
+import { type ControlColor } from "./control.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;
 /** Properties accepted by the shared interactive button. */
-export interface ButtonProps extends NativeButtonProps, RadiusProps {
+export interface ButtonProps extends NativeButtonProps, RadiusProps, MaterialOverrides {
     /** Visible Button content. */
     readonly children?: ReactNode;
+    /** Base color for the material. Omission keeps the Button neutral. */
+    readonly color?: ButtonColor;
     /** Native class name applied without replacing the component contract. */
     readonly className?: string;
     /** Prevents focus and activation. */
@@ -17,7 +23,7 @@ export interface ButtonProps extends NativeButtonProps, RadiusProps {
     readonly onPress?: () => void;
     /** Derives the Button's spacing from Appearance's concrete default. */
     readonly size?: ScaleLevel;
-    /** Additional native styles that do not replace the Button's identity. */
+    /** Native styles applied after Button defaults. */
     readonly style?: CSSProperties;
 }
 /** An Appearance-aware action with normalized pointer and keyboard behavior. */

package/dist/button.js

@@ -1,34 +1,33 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { forwardRef } from "react";
 import { Button as AriaButton } from "react-aria-components";
-import { scale } from "./scale.js";
-import { resolveRadius } from "./radius.js";
-import { useAppearance, useResolveTheme } from "./appearance-provider.js";
+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, disabled = false, pending = false, onPress, radius = "medium", size = "medium", style, type = "button", ...properties }, ref) {
-    const appearance = useAppearance();
-    const spacing = scale(useResolveTheme(appearance.spacing), size);
-    const borderRadius = resolveRadius(radius, appearance);
-    const foreground = useResolveTheme(appearance.foreground);
-    return _jsx(AriaButton, { ...properties, ref: ref, type: type, isDisabled: disabled, isPending: pending, onPress: onPress, style: ({ isFocusVisible, isHovered, isPressed }) => buttonStyle({
-            borderRadius,
+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(SurfaceButton, { native: native, material: material, paint: buttonPaint(theme, !disabled && !pending, state.isHovered, state.isPressed) }), style: ({ isFocusVisible, isHovered, isPressed }) => buttonStyle({
+            theme,
             disabled,
             isFocusVisible,
             isHovered,
             isPressed,
             pending,
             size,
-            spacing,
-            foreground,
             style
         }), children: children });
 });
-function buttonStyle({ borderRadius, disabled, isFocusVisible, isHovered, isPressed, pending, size, spacing, foreground, style }) {
-    const fontSize = buttonFontSizes[size];
-    const height = Math.max(size === "xsmall" ? 24 : 28, 20 + spacing);
+function buttonStyle({ theme, disabled, isFocusVisible, isHovered, isPressed, pending, size, style }) {
+    const fontSize = controlFontSizes[size];
+    const { spacing, foreground } = theme;
+    const height = Math.max(24, 24 + spacing);
+    const interactive = !disabled && !pending;
+    const paint = buttonPaint(theme, interactive, isHovered, isPressed);
     return {
-        ...style,
+        ...visualTransition,
         appearance: "none",
+        boxSizing: "border-box",
         display: "inline-grid",
         gridAutoFlow: "column",
         gridAutoColumns: "max-content",
@@ -37,34 +36,27 @@ function buttonStyle({ borderRadius, disabled, isFocusVisible, isHovered, isPres
         minWidth: 0,
         height,
         paddingBlock: 0,
-        paddingInline: Math.max(8, spacing * 2 / 3),
+        paddingInline: Math.max(8, spacing),
         gap: Math.max(4, spacing / 2),
-        border: "1px solid rgba(255, 255, 255, 0.45)",
-        borderRadius,
-        outline: "none",
-        color: foreground,
-        backgroundColor: `rgba(255, 255, 255, ${isPressed ? 0.42 : isHovered ? 0.5 : 0.3})`,
-        boxShadow: isFocusVisible
-            ? "0 0 0 2px rgba(255, 255, 255, 0.85), inset 0 1px 0 rgba(255, 255, 255, 0.8)"
-            : "inset 0 1px 0 rgba(255, 255, 255, 0.8)",
+        border: "none",
+        borderRadius: theme.radius,
+        outline: isFocusVisible ? `2px solid ${foreground}` : "none",
+        outlineOffset: 2,
+        ...paint,
         opacity: disabled ? 0.46 : pending ? 0.68 : 1,
-        transform: isPressed ? "scale(0.95)" : "scale(1)",
-        transition: "background-color 100ms ease, box-shadow 100ms ease, opacity 100ms ease, transform 100ms ease",
         cursor: disabled ? "not-allowed" : pending ? "progress" : "pointer",
         font: "inherit",
         fontSize,
-        fontWeight: 650,
+        fontWeight: 550,
         lineHeight: 1,
         textAlign: "center",
         textDecoration: "none",
         userSelect: "none",
-        WebkitTapHighlightColor: "transparent"
+        WebkitTapHighlightColor: "transparent",
+        ...style
     };
 }
-const buttonFontSizes = Object.freeze({
-    xsmall: 10,
-    small: 11,
-    medium: 12,
-    large: 13,
-    xlarge: 14
-});
+function buttonPaint(theme, interactive, hovered, pressed) {
+    const paints = theme.colored ? theme.paints.palette : theme.paints.neutral;
+    return interactive && pressed ? paints.pressed : interactive && hovered ? paints.hover : paints.rest;
+}

package/dist/checkbox.d.ts

@@ -0,0 +1,11 @@
+import type { CheckboxFieldProps } from "react-aria-components";
+import type { ControlOverrides, ControlProps, FieldProps } from "./control.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;
+    readonly indeterminate?: boolean;
+    readonly readOnly?: boolean;
+}
+/** An independent boolean field with optional mixed-state presentation. */
+export declare const Checkbox: import("react").ForwardRefExoticComponent<CheckboxProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/checkbox.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef } from "react";
+import { CheckboxField, CheckboxButton } from "react-aria-components";
+import { FieldFeedback, fieldStyle, useControlTheme } from "./control.js";
+import { ToggleIndicator, toggleStyle } from "./toggle-indicator.js";
+/** An independent boolean field with optional mixed-state presentation. */
+export const Checkbox = forwardRef(function Checkbox({ label, description, errorMessage, disabled, required, invalid, readOnly, checked, defaultChecked, indeterminate, size, color, style, material, ...properties }, ref) {
+    const theme = useControlTheme({ size, color });
+    return _jsxs(CheckboxField, { ...properties, ref: ref, isDisabled: disabled, isRequired: required, isInvalid: invalid, isReadOnly: readOnly, isSelected: checked, defaultSelected: defaultChecked, isIndeterminate: indeterminate, style: state => fieldStyle(theme, state.isDisabled, style), children: [_jsx(CheckboxButton, { style: state => toggleStyle(theme, state.isDisabled, state.isReadOnly), children: state => _jsxs(_Fragment, { children: [_jsx(ToggleIndicator, { kind: "checkbox", material: material, theme: theme, selected: state.isSelected, indeterminate: state.isIndeterminate, focused: state.isFocusVisible, invalid: state.isInvalid, hovered: !state.isDisabled && !state.isReadOnly && state.isHovered, pressed: !state.isDisabled && !state.isReadOnly && state.isPressed }), label] }) }), _jsx(FieldFeedback, { theme: theme, description: description, errorMessage: errorMessage })] });
+});

package/dist/color.d.ts

@@ -1,11 +1,23 @@
+import type { AppearanceColor } from "@phreshos/core";
 /** A visual treatment derived from one concrete CSS color. */
 export type ColorLevel = "subtle" | "soft" | "base" | "strong" | "intense";
 /** Every visual treatment derived from one concrete CSS color. */
 export type ColorScale = Readonly<Record<ColorLevel, string>>;
+/** One Appearance color and resting level, or a direct CSS color. */
+export type Color = `${AppearanceColor}:${ColorLevel}` | (string & {});
+export declare const defaultColor = "background:base";
+/** Distinguishes derived color levels from direct CSS colors. */
+export declare function isColorLevel(value: string | undefined): value is ColorLevel;
 /** Derives visual treatments while preserving the concrete value at `base`. */
 export declare function color(value: string): ColorScale;
+/** Resolves the same named treatment for solid paint and contrast calculations. */
+export declare function resolveColorLevel(value: string, level: ColorLevel): string;
 /** Returns the complete visual treatments derived from one concrete color. */
 export declare function useColor(value: string): ColorScale;
+/** Resolves a semantic Appearance color or preserves a direct CSS color. */
+export declare function useResolveColor(value?: Color): string;
+/** Resolves a color to concrete opaque paint for solid interactive states. */
+export declare function useResolveSolidColor(value: Color): string;
 /** Applies material opacity without restricting the source CSS color syntax. */
 export declare function colorOpacity(value: string, opacity: number): string;
 /** Reads perceptual lightness from a resolved CSS color. */
@@ -15,3 +27,24 @@ export declare function orderColors(first: string, second: string): {
     lighter: string;
     darker: string;
 };
+/** Solid controls use opaque, gamut-mapped colors for both paint and contrast. */
+export declare function opaqueColor(value: string): string;
+/** Changes only perceptual lightness; theme names never determine direction. */
+export declare function colorShade(value: string, amount: number): string;
+/** Chooses only from the two Appearance colors, against the actual painted fill. */
+export declare function onColor(fill: string, background: string, foreground: string): string;
+/** Solid controls start at base; interaction shades preserve its text choice. */
+export declare function solidColors(base: string, background: string, foreground: string): {
+    rest: {
+        background: string;
+        color: string;
+    };
+    hover: {
+        background: string;
+        color: string;
+    };
+    pressed: {
+        background: string;
+        color: string;
+    };
+};

package/dist/color.js

@@ -1,22 +1,59 @@
 import { useMemo } from "react";
-import { ColorSpace, parse, sRGB, sRGB_Linear, HSL, HWB, Lab, LCH, OKLab, OKLCH, P3, A98RGB, ProPhoto, REC_2020, XYZ_D50, XYZ_D65 } from "colorjs.io/fn";
+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";
 // 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);
+export const defaultColor = "background:base";
+const treatments = {
+    subtle: { weight: 25, target: "white" },
+    soft: { weight: 60, target: "white" },
+    strong: { weight: 82, target: "black" },
+    intense: { weight: 68, target: "black" }
+};
+/** Distinguishes derived color levels from direct CSS colors. */
+export function isColorLevel(value) {
+    return value === "subtle" || value === "soft" || value === "base" || value === "strong" || value === "intense";
+}
 /** Derives visual treatments while preserving the concrete value at `base`. */
 export function color(value) {
+    const shade = (level) => {
+        const { weight, target } = treatments[level];
+        return `color-mix(in oklch, ${value} ${weight}%, ${target})`;
+    };
     return Object.freeze({
-        subtle: `color-mix(in oklch, ${value} 25%, white)`,
-        soft: `color-mix(in oklch, ${value} 60%, white)`,
+        subtle: shade("subtle"),
+        soft: shade("soft"),
         base: value,
-        strong: `color-mix(in oklch, ${value} 82%, black)`,
-        intense: `color-mix(in oklch, ${value} 68%, black)`
+        strong: shade("strong"),
+        intense: shade("intense")
     });
 }
+/** Resolves the same named treatment for solid paint and contrast calculations. */
+export function resolveColorLevel(value, level) {
+    if (level === "base")
+        return opaqueColor(value);
+    const { weight, target } = treatments[level];
+    return opaqueColor(serialize(mix(opaqueColor(value), target, 1 - weight / 100, { space: "oklch" })));
+}
 /** Returns the complete visual treatments derived from one concrete color. */
 export function useColor(value) {
     return useMemo(() => color(value), [value]);
 }
+/** Resolves a semantic Appearance color or preserves a direct CSS color. */
+export function useResolveColor(value = defaultColor) {
+    const appearance = useAppearance();
+    const semantic = parseSemanticColor(value);
+    const source = useResolveTheme(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"]);
+    return semantic ? resolveColorLevel(source, semantic.level) : opaqueColor(value);
+}
 /** Applies material opacity without restricting the source CSS color syntax. */
 export function colorOpacity(value, opacity) {
     const percentage = Math.round(opacity * 10_000) / 100;
@@ -34,3 +71,45 @@ export function orderColors(first, second) {
         ? { lighter: first, darker: second }
         : { lighter: second, darker: first };
 }
+/** Solid controls use opaque, gamut-mapped colors for both paint and contrast. */
+export function opaqueColor(value) {
+    return serialize(toGamut(to({ ...parse(value), alpha: 1 }, "srgb")), { format: "rgb", precision: 6 });
+}
+/** Changes only perceptual lightness; theme names never determine direction. */
+export function colorShade(value, amount) {
+    const result = to(value, "oklch");
+    const lightness = result.coords[0] ?? 0;
+    result.coords[0] = Math.max(0, Math.min(1, lightness + (lightness > 0.6 ? -amount : amount)));
+    return opaqueColor(serialize(result));
+}
+/** Chooses only from the two Appearance colors, against the actual painted fill. */
+export function onColor(fill, background, foreground) {
+    const first = opaqueColor(background);
+    const second = opaqueColor(foreground);
+    return contrastWCAG21(fill, first) > contrastWCAG21(fill, second) ? first : second;
+}
+/** Solid controls start at base; interaction shades preserve its text choice. */
+export function solidColors(base, background, foreground) {
+    const fill = resolveColorLevel(base, "base");
+    const color = onColor(fill, background, foreground);
+    const paint = (background) => ({ background, color });
+    return {
+        rest: paint(fill),
+        hover: paint(colorShade(fill, 0.045)),
+        pressed: paint(colorShade(fill, 0.085))
+    };
+}
+function parseSemanticColor(value) {
+    const separator = value.indexOf(":");
+    if (separator < 0 || value.indexOf(":", separator + 1) >= 0)
+        return null;
+    const name = value.slice(0, separator);
+    const level = value.slice(separator + 1);
+    if (!isAppearanceColor(name) || !isColorLevel(level))
+        return null;
+    return { name, level };
+}
+function isAppearanceColor(value) {
+    return value === "background" || value === "foreground" || value === "primary" || value === "secondary"
+        || value === "success" || value === "warning" || value === "danger" || value === "info";
+}

package/dist/control-surface.d.ts

@@ -0,0 +1,20 @@
+import type { ComponentPropsWithRef, CSSProperties, ReactNode } from "react";
+import type { MaterialOptions } from "./material-options.js";
+type Paint = Readonly<{
+    background: string;
+    color: string;
+}>;
+/** 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 SurfaceField({ paint, radius, children, material: options }: Readonly<{
+    paint: Paint;
+    radius: CSSProperties["borderRadius"];
+    children: ReactNode;
+    material?: MaterialOptions;
+}>): import("react").JSX.Element;
+export {};

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, ...options, as: "button", color: paint.background, 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 });
+}