@phreshos/react-ui 0.2.0 → 0.2.1

package/dist/foundation/color.d.ts

@@ -54,6 +54,13 @@ export declare function canvasDarkness(colors: AppearanceColors): number;
  * Depth therefore reads the same on a light, mid-tone, or dark canvas.
  */
 export declare function recessColor(base: string): string;
+/**
+ * A paint moved just far enough from the paint it sits on to be told apart: at least `minimum`
+ * perceived difference (OKLab), stepping lighter, or darker only when lighter has no room. Raised
+ * and level things stand out the same way everywhere, whatever happens to be beneath them. A paint
+ * already far enough stays as it is.
+ */
+export declare function separateColor(paint: string, surroundings: string, minimum: number): string;
 /** The lighter Appearance content candidate: the paint of anything lit from above, such as a thumb. */
 export declare function lightColor(colors: AppearanceColors): string;
 export declare function isColorLevel(value: string): value is ColorLevel;

package/dist/foundation/color.js

@@ -252,6 +252,31 @@ export function recessColor(base) {
 }
 /** The constant difference between a recess and the paint it sinks into. */
 const recessContrast = 1.15;
+const separateCache = new Map();
+/**
+ * A paint moved just far enough from the paint it sits on to be told apart: at least `minimum`
+ * perceived difference (OKLab), stepping lighter, or darker only when lighter has no room. Raised
+ * and level things stand out the same way everywhere, whatever happens to be beneath them. A paint
+ * already far enough stays as it is.
+ */
+export function separateColor(paint, surroundings, minimum) {
+    const key = `${paint}|${surroundings}|${minimum}`;
+    const cached = separateCache.get(key);
+    if (cached !== undefined)
+        return cached;
+    const distance = perceivedDistance(paint, surroundings);
+    if (distance === null || distance >= minimum)
+        return remember(separateCache, key, paint);
+    const directions = ["#ffffff", "#000000"];
+    for (const toward of directions) {
+        for (let amount = 0.01; amount <= 0.6; amount += 0.01) {
+            const result = mixColor(paint, toward, Math.round(amount * 1_000) / 1_000);
+            if ((perceivedDistance(result, surroundings) ?? 0) >= minimum)
+                return remember(separateCache, key, result);
+        }
+    }
+    return remember(separateCache, key, paint);
+}
 /** 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;

package/dist/surface/surface.d.ts

@@ -47,6 +47,11 @@ export interface SurfaceInteraction {
     /** Marks a value-holding Surface whose current value is rejected. */
     readonly invalid?: boolean;
 }
+/**
+ * How far a nested Surface keeps from the one it sits on: farther on a dark canvas, where
+ * differences read smaller.
+ */
+export declare function nestingDistance(darkness: number): number;
 /**
  * The single visual primitive. Components express what they are through
  * color, depth, and interaction; paint, grain, frost, edge, shadow, focus,
@@ -81,8 +86,10 @@ export declare function surfaceColor(color: Color, depth: SurfaceDepth, colors:
 /** The color a Surface of this color and depth is painted with at rest, in the active Appearance. */
 export declare function useSurfaceColor(color?: Color, depth?: SurfaceDepth): string;
 /** Resolves every visual value of one Surface. Pure over its inputs. */
-export declare function surfacePaint(visual: Visual, color: Color, depth: SurfaceDepth, options: MaterialMode | MaterialOptions | undefined, shadowOptions: ShadowOverrides["shadow"], interaction: SurfaceInteraction | undefined): {
+export declare function surfacePaint(visual: Visual, color: Color, depth: SurfaceDepth, options: MaterialMode | MaterialOptions | undefined, shadowOptions: ShadowOverrides["shadow"], interaction: SurfaceInteraction | undefined, surroundings?: string | null): {
     fill: string;
+    /** The paint at rest, or `null` for a clear Surface. */
+    rest: string | null;
     text: string;
     ring: string;
     shadow: string;

package/dist/surface/surface.js

@@ -1,12 +1,21 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { createElement, forwardRef, useId, useInsertionEffect } from "react";
-import { canvasDarkness, colorOpacity, contrast, mixColor, readableColor, recessColor, resolveColor } from "../foundation/color.js";
+import { createContext, createElement, forwardRef, useContext, useId, useInsertionEffect } from "react";
+import { canvasDarkness, colorOpacity, contrast, mixColor, readableColor, recessColor, resolveColor, separateColor } from "../foundation/color.js";
 import { resolveRadius } from "../foundation/radius.js";
 import { useVisual } from "../foundation/visual.js";
 import { grainSeed, grainSize, grainTexture } from "./grain.js";
 import { flushPaintRules, paintClass, usePaintClasses } from "./paint-class.js";
 import { resolveMaterialOptions } from "./material-options.js";
 import { resolveShadowOptions, shadowStyle } from "./shadow-options.js";
+/** The resting paint of the nearest painted Surface around, which a nested Surface keeps apart from. */
+const SurroundingPaint = createContext(null);
+/**
+ * How far a nested Surface keeps from the one it sits on: farther on a dark canvas, where
+ * differences read smaller.
+ */
+export function nestingDistance(darkness) {
+    return 0.04 + 0.03 * darkness;
+}
 /**
  * The single visual primitive. Components express what they are through
  * color, depth, and interaction; paint, grain, frost, edge, shadow, focus,
@@ -15,7 +24,8 @@ import { resolveShadowOptions, shadowStyle } from "./shadow-options.js";
 export const SurfaceView = forwardRef(function Surface({ as: Element = "div", color = "background", depth = "raised", material, shadow, radius, interaction, className, children, style, ...properties }, ref) {
     const visual = useVisual();
     const identity = useId();
-    const paint = surfacePaint(visual, color, depth, material, shadow, interaction);
+    const surroundings = useContext(SurroundingPaint);
+    const paint = surfacePaint(visual, color, depth, material, shadow, interaction, surroundings);
     const borderRadius = radius === undefined && style?.borderRadius !== undefined
         ? style.borderRadius
         : resolveRadius(radius ?? "medium", visual.radius);
@@ -38,7 +48,9 @@ export const SurfaceView = forwardRef(function Surface({ as: Element = "div", co
         className: [surfaceClass, paint.grain?.name, painted, dimmedClass(interaction?.disabled ?? false), className].filter(Boolean).join(" "),
         // Without a document (server rendering), the same declarations travel inline.
         style: painted === undefined ? { ...inlineDeclarations(declarations), ...style } : style
-    }, _jsx(SurfaceStyle, {}), paint.grain && _jsx(GrainStyle, { grain: paint.grain }), paint.distortion > 0 && _jsx(Refraction, { identity: identity, distortion: paint.distortion }), children);
+    }, _jsx(SurfaceStyle, {}), paint.grain && _jsx(GrainStyle, { grain: paint.grain }), paint.distortion > 0 && _jsx(Refraction, { identity: identity, distortion: paint.distortion }), 
+    // A clear Surface paints nothing, so what is inside it sits on what is around it.
+    paint.rest === null ? children : _jsx(SurroundingPaint.Provider, { value: paint.rest, children: children }));
 });
 function inlineDeclarations(declarations) {
     const result = {};
@@ -85,7 +97,7 @@ export function useSurfaceColor(color = "background", depth = "raised") {
     return surfaceColor(color, depth, colors);
 }
 /** Resolves every visual value of one Surface. Pure over its inputs. */
-export function surfacePaint(visual, color, depth, options, shadowOptions, interaction) {
+export function surfacePaint(visual, color, depth, options, shadowOptions, interaction, surroundings = null) {
     const { colors } = visual;
     const base = resolveColor(color, colors);
     const active = interaction !== undefined && !interaction.disabled;
@@ -95,12 +107,15 @@ export function surfacePaint(visual, color, depth, options, shadowOptions, inter
     const darkness = canvasDarkness(colors);
     // A recess moves away from its surroundings toward whichever extreme has
     // room, by one constant perceptual difference on any canvas.
-    const rest = depth === "recessed" ? surfaceColor(color, depth, colors) : base;
+    const own = depth === "recessed" ? surfaceColor(color, depth, colors) : base;
     // A clear Surface, with no depth or a transparent color, has no substance of
     // its own: it paints nothing at rest, takes the content color of whatever it
     // sits on, and only reveals interaction as a veil. With no depth, a color
     // other than the neutral one colors its content instead of a fill.
     const clear = depth === "none" || base === "transparent";
+    // A raised or level Surface nested in another keeps apart from it, however deep the nesting goes.
+    // A recess keeps its own constant depth below its color, so a well reads the same wherever it is.
+    const rest = clear || depth === "recessed" || surroundings === null ? own : separateColor(own, surroundings, nestingDistance(darkness));
     const tinted = depth === "none" && base !== "transparent" && base !== colors.default;
     const fill = clear
         ? shift > 0 ? colorOpacity(colors.foreground, shift * clearVeil) : "transparent"
@@ -149,6 +164,8 @@ export function surfacePaint(visual, color, depth, options, shadowOptions, inter
         : shadowStyle(resolveShadowOptions(typeof shadowOptions === "object" ? shadowOptions : {}, shadow));
     return {
         fill,
+        /** The paint at rest, or `null` for a clear Surface. */
+        rest: clear ? null : rest,
         // The label is chosen once for the resting paint: interaction shades stay
         // close to it, and re-deciding per state would flip text on near-ties.
         text: tinted ? base : clear ? "inherit" : readableColor(rest, colors),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/react-ui",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "React components for coherent PhreshOS Program interfaces.",
   "type": "module",
   "sideEffects": false,