@phreshos/react-ui 0.2.0 → 0.2.2

package/dist/dialog.js

@@ -11,7 +11,7 @@ import { scale } from "./foundation/scale.js";
 import { containerPadding } from "./foundation/spacing.js";
 import { useVisual } from "./foundation/visual.js";
 import { floatingShadow } from "./surface/shadow-options.js";
-import { Surface } from "./surface/surface.js";
+import { FloatingLayer, Surface } from "./surface/surface.js";
 export function DialogRoot({ children, ...state }) {
     return _jsx(AriaDialogTrigger, { ...ariaOpenState(state), children: children });
 }
@@ -63,24 +63,24 @@ export const DialogContent = forwardRef(function DialogContent({ children, class
                     maxWidth: maxWidth ?? `calc(100vw - ${inset * 2}px)`,
                     maxHeight: `calc(100vh - ${inset * 2}px)`,
                     outline: "none"
-                }, children: _jsx(Surface, { className: className, color: color, material: material, 
-                    // Dialog content is composed by its consumer, so no owned rounded shape
-                    // sits at a known inset; it keeps the plain Appearance radius like Popover.
-                    radius: radius, shadow: shadow ?? floatingShadow(visual.shadow), style: {
-                        boxSizing: "border-box",
-                        width: "100%",
-                        maxHeight: "inherit",
-                        padding,
-                        overflow: "hidden",
-                        ...surfaceStyle
-                    }, children: _jsx(AriaDialog, { ...properties, ref: ref, style: {
-                            display: "grid",
-                            gap: inset,
-                            minWidth: 0,
-                            minHeight: 0,
+                }, children: _jsx(FloatingLayer, { children: _jsx(Surface, { className: className, color: color, material: material, 
+                        // Dialog content is composed by its consumer, so no owned rounded shape
+                        // sits at a known inset; it keeps the plain Appearance radius like Popover.
+                        radius: radius, shadow: shadow ?? floatingShadow(visual.shadow), style: {
+                            boxSizing: "border-box",
+                            width: "100%",
                             maxHeight: "inherit",
-                            outline: "none"
-                        }, children: children }) }) })] });
+                            padding,
+                            overflow: "hidden",
+                            ...surfaceStyle
+                        }, children: _jsx(AriaDialog, { ...properties, ref: ref, style: {
+                                display: "grid",
+                                gap: inset,
+                                minWidth: 0,
+                                minHeight: 0,
+                                maxHeight: "inherit",
+                                outline: "none"
+                            }, children: children }) }) }) })] });
 });
 export const DialogHeader = forwardRef(function DialogHeader({ style, ...properties }, ref) {
     const gap = scale(useVisual().spacing, "small");

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/panel.js

@@ -6,7 +6,7 @@ import { resolveRadius } from "./foundation/radius.js";
 import { scale } from "./foundation/scale.js";
 import { useVisual } from "./foundation/visual.js";
 import { paintClass, usePaintClasses } from "./surface/paint-class.js";
-import { Surface } from "./surface/surface.js";
+import { FloatingLayer, Surface } from "./surface/surface.js";
 import { containerPadding } from "./foundation/spacing.js";
 const PanelContext = createContext({ color: undefined, hasHeader: false, radius: undefined });
 export const PanelHeader = forwardRef(function PanelHeader({ style, ...properties }, ref) {
@@ -29,14 +29,14 @@ export const PanelRoot = forwardRef(function Panel({ children, style, ...propert
     const hasHeader = Children.toArray(children).some(child => isValidElement(child) && child.type === PanelHeader);
     // The shell and its content share one radius: the Appearance radius.
     const radius = resolveRadius(properties.radius ?? "medium", useVisual().radius);
-    return _jsx(PanelContext.Provider, { value: { color: properties.color, hasHeader, radius }, children: _jsx(Surface, { material: "full", ...properties, ref: ref, radius: radius, style: {
-                display: "grid",
-                gridTemplateRows: hasHeader ? "auto minmax(0, 1fr)" : "minmax(0, 1fr)",
-                minWidth: 0,
-                minHeight: 0,
-                maxHeight: "inherit",
-                ...style
-            }, children: children }) });
+    return _jsx(PanelContext.Provider, { value: { color: properties.color, hasHeader, radius }, children: _jsx(FloatingLayer, { children: _jsx(Surface, { material: "full", ...properties, ref: ref, radius: radius, style: {
+                    display: "grid",
+                    gridTemplateRows: hasHeader ? "auto minmax(0, 1fr)" : "minmax(0, 1fr)",
+                    minWidth: 0,
+                    minHeight: 0,
+                    maxHeight: "inherit",
+                    ...style
+                }, children: children }) }) });
 });
 export const PanelContent = forwardRef(function PanelContent({ className, style, ...properties }, ref) {
     const { spacing } = useVisual();

package/dist/popover.js

@@ -10,7 +10,7 @@ import { resolveDirectionalPlacement } from "./foundation/overlay-placement.js";
 import { scale } from "./foundation/scale.js";
 import { useVisual } from "./foundation/visual.js";
 import { floatingShadow } from "./surface/shadow-options.js";
-import { Surface } from "./surface/surface.js";
+import { FloatingLayer, Surface } from "./surface/surface.js";
 export function PopoverRoot({ children, ...state }) {
     return _jsx(AriaDialogTrigger, { ...ariaOpenState(state), children: children });
 }
@@ -22,13 +22,13 @@ const PositionedContent = forwardRef(function PositionedContent({ children, clas
     const inset = scale(visual.spacing, "small");
     const transition = overlayTransition(visual);
     const direction = resolveDirection(dir, useDirection());
-    return _jsxs(_Fragment, { children: [_jsx(MotionStyle, {}), _jsx(AriaPopover, { ...attributes, isNonModal: nonModal, ref: ref, dir: direction, offset: offset ?? inset, placement: resolveDirectionalPlacement(placement, direction), UNSTABLE_portalContainer: portalContainer, className: overlayMotionClass, style: transition, children: _jsx(Surface, { dir: direction, className: className, color: color, material: material, shadow: shadow ?? floatingShadow(visual.shadow), radius: radius, style: {
-                        boxSizing: "border-box",
-                        maxWidth: `calc(100vw - ${inset * 2}px)`,
-                        maxHeight: `calc(100vh - ${inset * 2}px)`,
-                        outline: "none",
-                        ...style
-                    }, children: children }) })] });
+    return _jsxs(_Fragment, { children: [_jsx(MotionStyle, {}), _jsx(AriaPopover, { ...attributes, isNonModal: nonModal, ref: ref, dir: direction, offset: offset ?? inset, placement: resolveDirectionalPlacement(placement, direction), UNSTABLE_portalContainer: portalContainer, className: overlayMotionClass, style: transition, children: _jsx(FloatingLayer, { children: _jsx(Surface, { dir: direction, className: className, color: color, material: material, shadow: shadow ?? floatingShadow(visual.shadow), radius: radius, style: {
+                            boxSizing: "border-box",
+                            maxWidth: `calc(100vw - ${inset * 2}px)`,
+                            maxHeight: `calc(100vh - ${inset * 2}px)`,
+                            outline: "none",
+                            ...style
+                        }, children: children }) }) })] });
 });
 export const PopoverContent = forwardRef(function PopoverContent(properties, ref) {
     return _jsx(PositionedContent, { ...properties, ref: ref });

package/dist/surface/surface.d.ts

@@ -47,6 +47,18 @@ export interface SurfaceInteraction {
     /** Marks a value-holding Surface whose current value is rejected. */
     readonly invalid?: boolean;
 }
+/**
+ * A layer that floats above everything, such as a popover, a dialog, or a panel: it is not inside the
+ * Surface it was opened from, so what it holds has nothing around it to keep apart from.
+ */
+export declare function FloatingLayer({ children }: Readonly<{
+    children: ReactNode;
+}>): import("react").JSX.Element;
+/**
+ * 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 +93,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,28 @@
 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);
+/**
+ * A layer that floats above everything, such as a popover, a dialog, or a panel: it is not inside the
+ * Surface it was opened from, so what it holds has nothing around it to keep apart from.
+ */
+export function FloatingLayer({ children }) {
+    return _jsx(SurroundingPaint.Provider, { value: null, children: children });
+}
+/**
+ * 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 +31,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 +55,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 +104,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 +114,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 +171,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/dist/tooltip.js

@@ -11,7 +11,7 @@ import { scale } from "./foundation/scale.js";
 import { useVisual } from "./foundation/visual.js";
 import { timing } from "./foundation/timing.js";
 import { floatingShadow } from "./surface/shadow-options.js";
-import { Surface } from "./surface/surface.js";
+import { FloatingLayer, Surface } from "./surface/surface.js";
 export function TooltipRoot({ children, delay, closeDelay, trigger, disabled, closeOnPress, ...state }) {
     // A pointer resting on a trigger for four changes in place is asking what it is.
     const rest = timing("change", { tempo: useVisual().appearance.tempo }).duration * 4;
@@ -25,16 +25,16 @@ export const TooltipContent = forwardRef(function TooltipContent({ children, cla
     const inset = scale(visual.spacing, "small");
     const transition = overlayTransition(visual);
     const direction = resolveDirection(dir, useDirection());
-    return _jsxs(_Fragment, { children: [_jsx(MotionStyle, {}), _jsx(AriaTooltip, { ...attributes, ref: ref, dir: direction, offset: offset ?? inset, placement: resolveDirectionalPlacement(placement, direction), UNSTABLE_portalContainer: portalContainer, className: overlayMotionClass, style: transition, children: _jsx(Surface, { dir: direction, className: className, color: color ?? "foreground", material: material, radius: radius, shadow: shadow ?? floatingShadow(visual.shadow), style: {
-                        boxSizing: "border-box",
-                        maxWidth: "28em",
-                        paddingBlock: inset,
-                        paddingInline: inset * 1.5,
-                        outline: "none",
-                        fontSize: controlFontSizes.small,
-                        lineHeight: controlLineHeight,
-                        ...style
-                    }, children: children }) })] });
+    return _jsxs(_Fragment, { children: [_jsx(MotionStyle, {}), _jsx(AriaTooltip, { ...attributes, ref: ref, dir: direction, offset: offset ?? inset, placement: resolveDirectionalPlacement(placement, direction), UNSTABLE_portalContainer: portalContainer, className: overlayMotionClass, style: transition, children: _jsx(FloatingLayer, { children: _jsx(Surface, { dir: direction, className: className, color: color ?? "foreground", material: material, radius: radius, shadow: shadow ?? floatingShadow(visual.shadow), style: {
+                            boxSizing: "border-box",
+                            maxWidth: "28em",
+                            paddingBlock: inset,
+                            paddingInline: inset * 1.5,
+                            outline: "none",
+                            fontSize: controlFontSizes.small,
+                            lineHeight: controlLineHeight,
+                            ...style
+                        }, children: children }) }) })] });
 });
 /** A description shown from the focus and hover state of its trigger. */
 export const Tooltip = Object.assign(TooltipRoot, {

package/package.json

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