@phreshos/react-ui 0.1.35 → 0.1.37

package/dist/foundation/color.js

@@ -0,0 +1,247 @@
+import { useMemo } from "react";
+import ColorSpace from "colorjs.io/src/ColorSpace.js";
+import contrastAPCA from "colorjs.io/src/contrast/APCA.js";
+import { mix } from "colorjs.io/src/interpolation.js";
+import parse from "colorjs.io/src/parse.js";
+import serialize from "colorjs.io/src/serialize.js";
+import to from "colorjs.io/src/to.js";
+import toGamut from "colorjs.io/src/toGamut.js";
+import sRGB from "colorjs.io/src/spaces/srgb.js";
+import sRGB_Linear from "colorjs.io/src/spaces/srgb-linear.js";
+import HSL from "colorjs.io/src/spaces/hsl.js";
+import HWB from "colorjs.io/src/spaces/hwb.js";
+import Lab from "colorjs.io/src/spaces/lab.js";
+import LCH from "colorjs.io/src/spaces/lch.js";
+import OKLab from "colorjs.io/src/spaces/oklab.js";
+import OKLCH from "colorjs.io/src/spaces/oklch.js";
+import P3 from "colorjs.io/src/spaces/p3.js";
+import A98RGB from "colorjs.io/src/spaces/a98rgb.js";
+import ProPhoto from "colorjs.io/src/spaces/prophoto.js";
+import REC_2020 from "colorjs.io/src/spaces/rec2020.js";
+import XYZ_D50 from "colorjs.io/src/spaces/xyz-d50.js";
+import XYZ_D65 from "colorjs.io/src/spaces/xyz-d65.js";
+import { useVisual } from "./visual.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);
+/**
+ * Levels move a color toward the canvas (`subtle`, `soft`) or toward the
+ * content color (`strong`, `intense`). Direction therefore follows the colors
+ * themselves, so every level keeps its meaning in any Theme.
+ */
+const levels = {
+    subtle: { toward: "background", amount: 0.84 },
+    soft: { toward: "background", amount: 0.62 },
+    strong: { toward: "foreground", amount: 0.22 },
+    intense: { toward: "foreground", amount: 0.42 }
+};
+/*
+ * Every derivation below is pure and repeats constantly across components and
+ * renders. Results are cached by their inputs so a theme change or a hover
+ * costs a lookup instead of a color-space conversion.
+ */
+const concreteCache = new Map();
+const luminanceCache = new Map();
+const mixCache = new Map();
+const resolvedCache = new WeakMap();
+const readableCache = new WeakMap();
+const cacheLimit = 2_048;
+function remember(cache, key, value) {
+    if (cache.size >= cacheLimit)
+        cache.delete(cache.keys().next().value);
+    cache.set(key, value);
+    return value;
+}
+/** Returns an opaque sRGB serialization, or `null` when the value is not a concrete CSS color. */
+export function concreteColor(value) {
+    const cached = concreteCache.get(value);
+    if (cached !== undefined)
+        return cached;
+    let result;
+    try {
+        result = serialize(toGamut(to({ ...parse(value), alpha: 1 }, "srgb")), { format: "hex" });
+    }
+    catch {
+        result = null;
+    }
+    return remember(concreteCache, value, result);
+}
+/** WCAG relative luminance of a concrete color, or `null` when it cannot be evaluated. */
+export function luminance(value) {
+    const cached = luminanceCache.get(value);
+    if (cached !== undefined)
+        return cached;
+    const concrete = concreteColor(value);
+    let result = null;
+    if (concrete !== null) {
+        const [red, green, blue] = to(parse(concrete), "srgb-linear").coords.map(channel => channel ?? 0);
+        result = 0.2126 * red + 0.7152 * green + 0.0722 * blue;
+    }
+    return remember(luminanceCache, value, result);
+}
+/** WCAG contrast ratio between two colors, or `null` when either cannot be evaluated. */
+export function contrast(first, second) {
+    const a = luminance(first);
+    const b = luminance(second);
+    if (a === null || b === null)
+        return null;
+    return (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);
+}
+/**
+ * Mixes `amount` of `target` into `base` in OKLab, concretely when possible.
+ * OKLab keeps the hue while moving toward a near-neutral canvas or text color;
+ * OKLCH would rotate the hue toward the neutral's meaningless angle.
+ */
+export function mixColor(base, target, amount) {
+    if (amount <= 0)
+        return base;
+    const key = `${base}|${target}|${amount}`;
+    const cached = mixCache.get(key);
+    if (cached !== undefined)
+        return cached;
+    const first = concreteColor(base);
+    const second = concreteColor(target);
+    const result = first !== null && second !== null
+        ? concreteColor(serialize(mix(first, second, amount, { space: "oklab" })))
+        : `color-mix(in oklab, ${base}, ${target} ${Math.round(amount * 10_000) / 100}%)`;
+    return remember(mixCache, key, result);
+}
+/** Applies transparency without restricting the source CSS color syntax. */
+export function colorOpacity(value, opacity) {
+    return `color-mix(in srgb, ${value} ${Math.round(opacity * 10_000) / 100}%, transparent)`;
+}
+/** Resolves one Color against the active Appearance colors. */
+export function resolveColor(value, colors) {
+    let cache = resolvedCache.get(colors);
+    if (cache === undefined)
+        resolvedCache.set(colors, cache = new Map());
+    const cached = cache.get(value);
+    if (cached !== undefined)
+        return cached;
+    const separator = value.indexOf(":");
+    const name = separator < 0 ? value : value.slice(0, separator);
+    const level = separator < 0 ? "base" : value.slice(separator + 1);
+    const source = Object.hasOwn(colors, name) ? colors[name] : undefined;
+    const result = source === undefined || !isColorLevel(level)
+        ? value
+        : level === "base" ? source : colorLevel(source, level, colors);
+    cache.set(value, result);
+    return result;
+}
+/** Derives one level from a concrete base color. */
+export function colorLevel(base, level, colors) {
+    if (level === "base")
+        return base;
+    const { toward, amount } = levels[level];
+    return mixColor(base, colors[toward], amount);
+}
+/** Every level derived from one base color. */
+export function colorScale(base, colors) {
+    return Object.freeze({
+        subtle: colorLevel(base, "subtle", colors),
+        soft: colorLevel(base, "soft", colors),
+        base,
+        strong: colorLevel(base, "strong", colors),
+        intense: colorLevel(base, "intense", colors)
+    });
+}
+/**
+ * Perceived lightness contrast (APCA Lc magnitude) of `text` drawn on `fill`,
+ * or `null` when either cannot be evaluated. Unlike the WCAG 2 ratio, it is
+ * polarity-aware: the WCAG ratio overrates dark text on saturated mid-tone
+ * fills such as blue or green, where light text actually reads better.
+ */
+export function readability(fill, text) {
+    const background = concreteColor(fill);
+    const foreground = concreteColor(text);
+    if (background === null || foreground === null)
+        return null;
+    return Math.abs(contrastAPCA(background, foreground));
+}
+/**
+ * APCA grades readability in steps of 15 Lc. Contrasts closer than one step
+ * read alike, so they are not a reason to leave the Appearance text color.
+ */
+const readabilityStep = 15;
+/**
+ * Returns the Appearance text color, `foreground`, unless `background` reads
+ * clearly better on the fill: better by at least one APCA step.
+ */
+export function readableColor(fill, colors) {
+    let cache = readableCache.get(colors);
+    if (cache === undefined)
+        readableCache.set(colors, cache = new Map());
+    const cached = cache.get(fill);
+    if (cached !== undefined)
+        return cached;
+    const onBackground = readability(fill, colors.background);
+    const onForeground = readability(fill, colors.foreground);
+    const result = onBackground === null || onForeground === null
+        ? colors.foreground
+        : onBackground >= onForeground + readabilityStep ? colors.background : colors.foreground;
+    cache.set(fill, result);
+    return result;
+}
+/** Whether the canvas is darker than its content, derived from the colors themselves. */
+export function darkCanvas(colors) {
+    const background = luminance(colors.background);
+    const foreground = luminance(colors.foreground);
+    return background !== null && foreground !== null && background < foreground;
+}
+const darknessCache = new WeakMap();
+/**
+ * How dark the canvas is, from 0 (a light canvas) to 1 (a dark canvas), read
+ * from the perceptual lightness of the background itself. Treatments that
+ * depend on the canvas interpolate along it instead of switching at a threshold,
+ * so a mid-tone canvas receives a mid-tone treatment.
+ */
+export function canvasDarkness(colors) {
+    const cached = darknessCache.get(colors);
+    if (cached !== undefined)
+        return cached;
+    const concrete = concreteColor(colors.background);
+    const lightness = concrete === null ? (darkCanvas(colors) ? 0 : 1) : to(parse(concrete), "oklch").coords[0] ?? 1;
+    const progress = Math.min(1, Math.max(0, (0.82 - lightness) / (0.82 - 0.28)));
+    // Smoothstep keeps both ends settled and the middle continuous.
+    const result = progress * progress * (3 - 2 * progress);
+    darknessCache.set(colors, result);
+    return result;
+}
+const recessCache = new Map();
+/**
+ * The paint of a recess in `base`: the same color moved just far enough toward
+ * whichever extreme has more room to reach one constant perceptual difference.
+ * Depth therefore reads the same on a light, mid-tone, or dark canvas.
+ */
+export function recessColor(base) {
+    const cached = recessCache.get(base);
+    if (cached !== undefined)
+        return cached;
+    const toward = (contrast(base, "#ffffff") ?? 1) > (contrast(base, "#000000") ?? 1) ? "#ffffff" : "#000000";
+    let result = base;
+    for (let amount = 0.005; amount <= 0.25; amount += 0.005) {
+        result = mixColor(base, toward, Math.round(amount * 1_000) / 1_000);
+        if ((contrast(base, result) ?? recessContrast) >= recessContrast)
+            break;
+    }
+    return remember(recessCache, base, result);
+}
+/** The constant difference between a recess and the paint it sinks into. */
+const recessContrast = 1.085;
+/** The lighter Appearance content candidate: the paint of anything lit from above, such as a thumb. */
+export function lightColor(colors) {
+    return darkCanvas(colors) ? colors.foreground : colors.default;
+}
+export function isColorLevel(value) {
+    return value === "subtle" || value === "soft" || value === "base" || value === "strong" || value === "intense";
+}
+/** Every level derived from one color in the active Appearance. */
+export function useColor(value) {
+    const { colors } = useVisual();
+    return useMemo(() => colorScale(resolveColor(value, colors), colors), [value, colors]);
+}
+/** The readable content color for one fill in the active Appearance. */
+export function useContrastingColor(value) {
+    const { colors } = useVisual();
+    return useMemo(() => readableColor(resolveColor(value, colors), colors), [value, colors]);
+}

package/dist/{layout.d.ts → foundation/layout.d.ts}

@@ -1,6 +1,5 @@
 import type { CSSProperties } from "react";
-import type { Appearance } from "./appearance.js";
-import { type Spacing } from "./spacing.js";
+import type { Spacing } from "./spacing.js";
 /** Cross-axis alignment shared by layout containers. */
 export type LayoutAlignment = "start" | "center" | "end" | "stretch" | "baseline";
 /** Main-axis distribution shared by layout containers. */
@@ -9,6 +8,9 @@ export type LayoutJustification = "start" | "center" | "end" | "between" | "arou
 export type LayoutGap = Spacing;
 export declare function alignment(value: LayoutAlignment | undefined): CSSProperties["alignItems"] | undefined;
 export declare function justification(value: LayoutJustification | undefined): CSSProperties["justifyContent"] | undefined;
-/** Resolves semantic spacing while preserving explicit CSS gap values. */
-export declare function resolveGap(value: LayoutGap | undefined, appearance: Appearance | null): CSSProperties["gap"];
 export declare function tracks(value: number | string | undefined, property: "columns" | "rows"): string | undefined;
+/**
+ * The height of a shell header row, shared by Window and Panel: a 16px icon
+ * or line of title plus the Appearance spacing above and below.
+ */
+export declare function headerHeight(spacing: number): number;

package/dist/{layout.js → foundation/layout.js}

@@ -1,4 +1,3 @@
-import { resolveSpacing } from "./spacing.js";
 const alignments = {
     start: "flex-start",
     center: "center",
@@ -20,10 +19,6 @@ export function alignment(value) {
 export function justification(value) {
     return value === undefined ? undefined : justifications[value];
 }
-/** Resolves semantic spacing while preserving explicit CSS gap values. */
-export function resolveGap(value, appearance) {
-    return resolveSpacing(value, appearance);
-}
 export function tracks(value, property) {
     if (value === undefined || typeof value === "string")
         return value;
@@ -32,3 +27,10 @@ export function tracks(value, property) {
     }
     return `repeat(${value}, minmax(0, 1fr))`;
 }
+/**
+ * The height of a shell header row, shared by Window and Panel: a 16px icon
+ * or line of title plus the Appearance spacing above and below.
+ */
+export function headerHeight(spacing) {
+    return 16 + spacing * 2;
+}

package/dist/foundation/motion-style.d.ts

@@ -0,0 +1,9 @@
+import type { CSSProperties } from "react";
+import type { Visual } from "./visual.js";
+/** Per-overlay variables consumed by the shared entrance keyframes. */
+export declare function overlayTransition(visual: Visual): CSSProperties;
+export declare const overlayMotionClass = "phreshos-ui-overlay";
+export declare const backdropMotionClass = "phreshos-ui-backdrop";
+/** React hoists and deduplicates this stylesheet, including inside portals. */
+export default function MotionStyle(): import("react").JSX.Element;
+export declare const textControlClass = "phreshos-ui-text-control";

package/dist/foundation/motion-style.js

@@ -0,0 +1,50 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/** Per-overlay variables consumed by the shared entrance keyframes. */
+export function overlayTransition(visual) {
+    return {
+        "--phreshos-ui-motion-duration": `${visual.duration}ms`,
+        "--phreshos-ui-motion-easing": visual.easing
+    };
+}
+export const overlayMotionClass = "phreshos-ui-overlay";
+export const backdropMotionClass = "phreshos-ui-backdrop";
+const stylesheet = `
+.phreshos-ui-overlay[data-entering] {
+  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) var(--phreshos-ui-motion-easing) reverse both;
+  pointer-events: none;
+}
+.phreshos-ui-backdrop[data-entering] {
+  animation: phreshos-ui-backdrop-enter var(--phreshos-ui-motion-duration) var(--phreshos-ui-motion-easing) both;
+}
+.phreshos-ui-backdrop[data-exiting] {
+  animation: phreshos-ui-backdrop-enter var(--phreshos-ui-motion-duration) var(--phreshos-ui-motion-easing) reverse both;
+  pointer-events: none;
+}
+@keyframes phreshos-ui-overlay-enter {
+  from { opacity: 0; scale: 1.05; }
+  to { opacity: 1; scale: 1; }
+}
+@keyframes phreshos-ui-backdrop-enter {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+.phreshos-ui-text-control::placeholder {
+  color: inherit;
+  opacity: 0.55;
+}
+@keyframes phreshos-ui-spin {
+  to { rotate: 360deg; }
+}
+@keyframes phreshos-ui-sweep {
+  from { inset-inline-start: -40%; }
+  to { inset-inline-start: 100%; }
+}
+`;
+/** React hoists and deduplicates this stylesheet, including inside portals. */
+export default function MotionStyle() {
+    return _jsx("style", { href: "phreshos-react-ui-motion", precedence: "phreshos", children: stylesheet });
+}
+export const textControlClass = "phreshos-ui-text-control";

package/dist/foundation/preferences.d.ts

@@ -0,0 +1,15 @@
+/** A visual Theme selects one branch of every themed Appearance value. */
+export type Theme = "light" | "dark";
+/** Complete environment preferences consumed by React UI. */
+export type Preferences = Readonly<{
+    theme: Theme;
+    animations: boolean;
+}>;
+/** At least one preference merged with the nearest UIProvider. */
+export type PreferencesUpdate = Readonly<{
+    theme: Theme;
+    animations?: boolean;
+}> | Readonly<{
+    theme?: Theme;
+    animations: boolean;
+}>;

package/dist/{ui-provider.d.ts → foundation/provider.d.ts}

@@ -1,11 +1,7 @@
 import type { ReactNode } from "react";
-import type { AppearanceUpdate } from "./appearance.js";
+import { type AppearanceUpdate } from "./appearance.js";
 import { type Direction } from "./direction.js";
 import type { PreferencesUpdate } from "./preferences.js";
-export { useAppearance, useBrowserPreferences, usePreferences, useThemedValue } from "./appearance-context.js";
-export { useDirection, useDocumentDirection } from "./direction.js";
-/** Establishes only the explicitly supplied UI values for a React subtree. */
-export declare function UIProvider({ appearance, children, direction, preferences }: UIProviderProps): ReactNode;
 export interface UIProviderProps {
     readonly appearance?: AppearanceUpdate;
     readonly children: ReactNode;
@@ -13,3 +9,5 @@ export interface UIProviderProps {
     readonly direction?: Direction;
     readonly preferences?: PreferencesUpdate;
 }
+/** Establishes only the explicitly supplied UI values for a React subtree. */
+export declare function UIProvider({ appearance, children, direction, preferences }: UIProviderProps): import("react").JSX.Element;

package/dist/{ui-provider.js → foundation/provider.js}

@@ -1,9 +1,9 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+import { LucideProvider } from "lucide-react";
 import { useMemo } from "react";
-import { AppearanceContext, fixedPreferencesSource, PreferencesContext, useAppearance, usePreferences } from "./appearance-context.js";
+import { mergeAppearance } from "./appearance.js";
 import { DirectionContext, fixedDirectionSource } from "./direction.js";
-export { useAppearance, useBrowserPreferences, usePreferences, useThemedValue } from "./appearance-context.js";
-export { useDirection, useDocumentDirection } from "./direction.js";
+import { AppearanceContext, fixedPreferencesSource, PreferencesContext, useAppearance, usePreferences } from "./visual.js";
 const directionBoundaryStyle = { display: "contents" };
 /** Establishes only the explicitly supplied UI values for a React subtree. */
 export function UIProvider({ appearance, children, direction, preferences }) {
@@ -16,8 +16,14 @@ export function UIProvider({ appearance, children, direction, preferences }) {
     if (directionSource !== undefined) {
         subtree = _jsx(DirectionContext.Provider, { value: directionSource, children: _jsx("div", { dir: direction, style: directionBoundaryStyle, children: subtree }) });
     }
-    return subtree;
+    // Icons are not a supplied value: every provider gives its subtree the same
+    // icon treatment. An icon follows its text size and color, with a constant
+    // 1.5px stroke; a `size` or `strokeWidth` on the icon still wins.
+    return _jsx(LucideProvider, { size: iconSize, strokeWidth: 1.5, nonScalingStroke: true, children: subtree });
 }
+// Lucide types its default size as a number, but passes it to the SVG size
+// attributes, which take any CSS length.
+const iconSize = "1em";
 function AppearanceBoundary({ children, update }) {
     const inherited = useAppearance();
     const appearance = useMemo(() => mergeAppearance(inherited, update), [inherited, update]);
@@ -32,31 +38,13 @@ function PreferencesBoundary({ children, update }) {
     return _jsx(InheritedPreferencesBoundary, { update: update, children: children });
 }
 function CompletePreferencesBoundary({ animations, children, theme }) {
-    const preferences = useMemo(() => Object.freeze({ theme, animations }), [theme, animations]);
-    const source = useMemo(() => fixedPreferencesSource(preferences), [preferences]);
+    const source = useMemo(() => fixedPreferencesSource(Object.freeze({ theme, animations })), [theme, animations]);
     return _jsx(PreferencesContext.Provider, { value: source, children: children });
 }
 function InheritedPreferencesBoundary({ children, update }) {
     const inherited = usePreferences();
-    const preferences = useMemo(() => Object.freeze({ ...inherited, ...update }), [inherited, update]);
-    const source = useMemo(() => fixedPreferencesSource(preferences), [preferences]);
+    const theme = update.theme ?? inherited.theme;
+    const animations = update.animations ?? inherited.animations;
+    const source = useMemo(() => fixedPreferencesSource(Object.freeze({ theme, animations })), [theme, animations]);
     return _jsx(PreferencesContext.Provider, { value: source, children: children });
 }
-function mergeAppearance(appearance, update) {
-    return Object.freeze({
-        colors: mergeThemed(appearance.colors, update.colors),
-        spacing: update.spacing ?? appearance.spacing,
-        radius: update.radius ?? appearance.radius,
-        shadow: mergeThemed(appearance.shadow, update.shadow),
-        material: mergeThemed(appearance.material, update.material),
-        transaction: Object.freeze({ ...appearance.transaction, ...update.transaction }),
-    });
-}
-function mergeThemed(current, update) {
-    if (update === undefined)
-        return current;
-    return Object.freeze({
-        light: Object.freeze({ ...current.light, ...update.light }),
-        dark: Object.freeze({ ...current.dark, ...update.dark })
-    });
-}

package/dist/{radius.d.ts → foundation/radius.d.ts}

@@ -1,5 +1,4 @@
 import type { CSSProperties } from "react";
-import type { Appearance } from "./appearance.js";
 import { type ScaleLevel } from "./scale.js";
 /** An Appearance-derived level, fully rounded shape, pixel value, or explicit CSS corner radius. */
 export type Radius = ScaleLevel | "full" | number | (string & {});
@@ -7,5 +6,9 @@ export type Radius = ScaleLevel | "full" | number | (string & {});
 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"];
+/**
+ * Resolves a Radius against a base radius: a level scales the base, `full`
+ * rounds completely, and pixels and CSS pass through. Only the base is needed,
+ * so it can come from an Appearance or from anywhere else.
+ */
+export declare function resolveRadius(value: Radius | undefined, radius: number): CSSProperties["borderRadius"];

package/dist/foundation/radius.js

@@ -0,0 +1,11 @@
+import { isScaleLevel, scale } from "./scale.js";
+/**
+ * Resolves a Radius against a base radius: a level scales the base, `full`
+ * rounds completely, and pixels and CSS pass through. Only the base is needed,
+ * so it can come from an Appearance or from anywhere else.
+ */
+export function resolveRadius(value, radius) {
+    if (value === "full")
+        return "9999px";
+    return isScaleLevel(value) ? scale(radius, value) : value;
+}

package/dist/foundation/spacing.d.ts

@@ -0,0 +1,11 @@
+import type { CSSProperties } from "react";
+import { type ScaleLevel } from "./scale.js";
+/** An Appearance-derived level, pixel value, or explicit CSS spacing value. */
+export type Spacing = ScaleLevel | number | (string & {});
+/**
+ * Resolves a spacing value against a base spacing: a level scales the base,
+ * while pixels and CSS pass through. Only the base is needed, so it can come
+ * from an Appearance or from anywhere else.
+ */
+export declare function resolveSpacing(value: ScaleLevel, spacing: number): number;
+export declare function resolveSpacing(value: Spacing | undefined, spacing: number): CSSProperties["gap"];

package/dist/foundation/spacing.js

@@ -0,0 +1,4 @@
+import { isScaleLevel, scale } from "./scale.js";
+export function resolveSpacing(value, spacing) {
+    return isScaleLevel(value) ? scale(spacing, value) : value;
+}

package/dist/foundation/visual.d.ts

@@ -0,0 +1,42 @@
+import { type Appearance, type AppearanceColors, type AppearanceMaterial, type AppearanceShadow, type Easing, type ThemedValue } from "./appearance.js";
+import type { Preferences } from "./preferences.js";
+/**
+ * One Appearance resolved for one set of Preferences. Every component reads
+ * this single object instead of deriving its own view of Appearance, so equal
+ * inputs share one identity across the whole tree.
+ */
+export interface Visual {
+    readonly appearance: Appearance;
+    readonly preferences: Preferences;
+    readonly colors: AppearanceColors;
+    readonly material: AppearanceMaterial;
+    readonly shadow: AppearanceShadow;
+    readonly spacing: number;
+    readonly radius: number;
+    /** Duration in milliseconds, already zero when animations are disabled. */
+    readonly duration: number;
+    /** CSS timing function for the Appearance transaction. */
+    readonly easing: string;
+}
+/** Resolves and memoizes one Visual per Appearance, Theme, and animation preference. */
+export declare function resolveVisual(appearance: Appearance, preferences: Preferences): Visual;
+export declare const AppearanceContext: import("react").Context<Appearance>;
+export interface PreferencesSource {
+    readonly getSnapshot: () => Preferences;
+    readonly getServerSnapshot: () => Preferences;
+    readonly subscribe: (change: () => void) => () => void;
+}
+/** Returns the nearest Appearance, or React UI's default. */
+export declare function useAppearance(): Appearance;
+/** Returns the nearest complete Preferences, or reactively follows the browser. */
+export declare function usePreferences(): Preferences;
+/** Returns the shared resolved Visual for the nearest Appearance and Preferences. */
+export declare function useVisual(): Visual;
+/** Selects the active branch of one themed value. */
+export declare function useThemedValue<Value>(value: ThemedValue<Value>): Value;
+/** Reactively reads the browser's complete visual preferences. */
+export declare function useBrowserPreferences(): Preferences;
+/** Creates a stable source for one explicitly supplied Preferences value. */
+export declare function fixedPreferencesSource(preferences: Preferences): PreferencesSource;
+export declare function cssEasing(easing: Easing): string;
+export declare const PreferencesContext: import("react").Context<PreferencesSource>;

package/dist/{appearance-context.js → foundation/visual.js}

@@ -1,7 +1,32 @@
-import { createContext, useContext, useMemo, useSyncExternalStore } from "react";
+import { createContext, useContext, useSyncExternalStore } from "react";
 import { defaultAppearance } from "./appearance.js";
+const visuals = new WeakMap();
+/** Resolves and memoizes one Visual per Appearance, Theme, and animation preference. */
+export function resolveVisual(appearance, preferences) {
+    let resolved = visuals.get(appearance);
+    if (resolved === undefined)
+        visuals.set(appearance, resolved = new Map());
+    const key = `${preferences.theme}:${preferences.animations}`;
+    const cached = resolved.get(key);
+    if (cached !== undefined)
+        return cached;
+    const duration = preferences.animations ? appearance.transaction.duration : 0;
+    const visual = Object.freeze({
+        appearance,
+        preferences,
+        colors: appearance.colors[preferences.theme],
+        material: appearance.material[preferences.theme],
+        shadow: appearance.shadow[preferences.theme],
+        spacing: appearance.spacing,
+        radius: appearance.radius,
+        duration,
+        easing: cssEasing(appearance.transaction.easing)
+    });
+    resolved.set(key, visual);
+    return visual;
+}
 export const AppearanceContext = createContext(defaultAppearance);
-/** Returns the nearest unresolved appearance, or React UI's default. */
+/** Returns the nearest Appearance, or React UI's default. */
 export function useAppearance() {
     return useContext(AppearanceContext);
 }
@@ -10,35 +35,29 @@ export function usePreferences() {
     const source = useContext(PreferencesContext);
     return useSyncExternalStore(source.subscribe, source.getSnapshot, source.getServerSnapshot);
 }
-/** Reactively reads the browser's complete visual preferences. */
-export function useBrowserPreferences() {
-    return useSyncExternalStore(browserPreferencesSource.subscribe, browserPreferencesSource.getSnapshot, browserPreferencesSource.getServerSnapshot);
+/** Returns the shared resolved Visual for the nearest Appearance and Preferences. */
+export function useVisual() {
+    return resolveVisual(useAppearance(), usePreferences());
 }
-/** Selects the active branch of one complete ThemedValue. */
+/** Selects the active branch of one themed value. */
 export function useThemedValue(value) {
     return value[usePreferences().theme];
 }
-/** Resolves one coherent Appearance snapshot for internal component derivation. */
-export function useResolvedAppearance() {
-    const appearance = useAppearance();
-    const preferences = usePreferences();
-    return useMemo(() => ({
-        appearance,
-        preferences,
-        colors: appearance.colors[preferences.theme],
-        material: appearance.material[preferences.theme],
-        shadow: appearance.shadow[preferences.theme],
-        transaction: appearance.transaction
-    }), [appearance, preferences]);
+/** Reactively reads the browser's complete visual preferences. */
+export function useBrowserPreferences() {
+    return useSyncExternalStore(browserPreferencesSource.subscribe, browserPreferencesSource.getSnapshot, browserPreferencesSource.getServerSnapshot);
 }
-/** Creates a stable source for a complete explicitly supplied Preferences value. */
+/** Creates a stable source for one explicitly supplied Preferences value. */
 export function fixedPreferencesSource(preferences) {
     return {
         getSnapshot: () => preferences,
         getServerSnapshot: () => preferences,
-        subscribe: emptySubscription
+        subscribe: () => () => undefined
     };
 }
+export function cssEasing(easing) {
+    return typeof easing === "string" ? easing : `cubic-bezier(${easing.join(", ")})`;
+}
 const defaultPreferences = Object.freeze({ theme: "light", animations: true });
 const subscribers = new Set();
 let darkPreference;
@@ -47,8 +66,8 @@ let browserSnapshot = defaultPreferences;
 function readBrowserPreferences() {
     if (typeof window === "undefined" || typeof window.matchMedia !== "function")
         return defaultPreferences;
-    darkPreference ??= window.matchMedia(darkThemeQuery);
-    reducedMotionPreference ??= window.matchMedia(reducedMotionQuery);
+    darkPreference ??= window.matchMedia("(prefers-color-scheme: dark)");
+    reducedMotionPreference ??= window.matchMedia("(prefers-reduced-motion: reduce)");
     const theme = darkPreference.matches ? "dark" : "light";
     const animations = !reducedMotionPreference.matches;
     if (browserSnapshot.theme !== theme || browserSnapshot.animations !== animations) {
@@ -78,14 +97,9 @@ function publishBrowserPreferences() {
     for (const subscriber of subscribers)
         subscriber();
 }
-function emptySubscription() {
-    return () => undefined;
-}
 const browserPreferencesSource = {
     getSnapshot: readBrowserPreferences,
     getServerSnapshot: () => defaultPreferences,
     subscribe: subscribeBrowserPreferences
 };
 export const PreferencesContext = createContext(browserPreferencesSource);
-const darkThemeQuery = "(prefers-color-scheme: dark)";
-const reducedMotionQuery = "(prefers-reduced-motion: reduce)";