@phreshos/react-ui 0.1.15 → 0.1.16

package/README.md

@@ -2,8 +2,19 @@
 
 Environment-neutral React components and the visual language of PhreshOS.
 
-React UI interprets Core Appearance and Theme contracts. It does not depend on a
-Client or Server runtime and does not own authoritative application state.
+[Appearance](https://docs.phreshos.com/system/appearance) ·
+[React SDK](https://docs.phreshos.com/sdks/react) ·
+[Source](https://github.com/PhreshOS/react-ui)
+
+## Role
+
+React UI interprets Core Appearance and Theme contracts as reusable visual
+primitives. The Desktop and Programs compose those primitives instead of
+reimplementing material, spacing, color, radius, or interaction behavior.
+
+The package does not depend on a Client or Server runtime and does not own
+authoritative application state. React owns runtime-neutral state adaptation;
+applications own composition.
 
 ## Installation
 
@@ -16,15 +27,9 @@ Client or Server runtime and does not own authoritative application state.
 
 `@phreshos/core`, React, and React DOM are peer dependencies.
 
-## Appearance
-
 ```tsx
 import { standardAppearance } from "@phreshos/core"
-import {
-  AppearanceProvider,
-  Button,
-  Surface,
-} from "@phreshos/react-ui"
+import { AppearanceProvider, Button, Surface } from "@phreshos/react-ui"
 
 <AppearanceProvider appearance={standardAppearance} theme="light">
   <Surface>
@@ -33,26 +38,23 @@ import {
 </AppearanceProvider>
 ```
 
-`AppearanceProvider` provides the unresolved Appearance and one effective
-`"light" | "dark"` Theme. `useAppearance()` reads the unresolved value,
-`useTheme()` reads the effective mode, and `useResolveTheme()` resolves one
-themed property where it is consumed.
+See [Appearance](https://docs.phreshos.com/system/appearance) for the contract
+interpreted by the provider and components.
 
-The provider also applies the shared document scrollbar treatment without
-adding a rendered container.
+`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.
 
-## Components
-
-The package owns the reusable visual primitives used across the desktop and
-official Programs:
+```tsx
+import { Panel } from "@phreshos/react-ui"
 
-- `Surface` and `SurfaceMaterial`
-- `Button`
-- `Flex` and `Grid`
-- spacing, scale, radius, color, and icon utilities
+<Panel header={<h2>Title</h2>} contentProps={{ style: { padding: 16 } }}>
+  Content
+</Panel>
+```
 
-These primitives form one visual language. Desktop and Program Views compose
-them rather than reimplementing their material or layout behavior.
+Native properties and the forwarded ref target the outer Surface.
+`contentProps` targets the inner Surface; `children` supplies its content.
 
 ## Development
 
@@ -62,13 +64,20 @@ bun run verify
 ```
 
 `verify` checks the contracts, tests the components, builds the package, and
-validates its public artifact.
+validates its published shape.
 
-## Repository boundary
+## Related repositories
 
-This repository owns visual interpretation and reusable React components. Core
-owns Appearance contracts, React owns runtime-neutral state adaptation, and
-applications own composition.
+- [`@phreshos/core`](https://github.com/PhreshOS/core) owns Appearance, Theme,
+  and the shared values interpreted here.
+- [`@phreshos/react`](https://github.com/PhreshOS/react) owns runtime-neutral
+  React state adaptation.
+- [PhreshOS System](https://github.com/PhreshOS/system) composes the visual
+  language into the Desktop.
+- [Settings](https://github.com/PhreshOS/settings-program) presents owner-facing
+  Appearance controls.
+
+## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the repository workflow and
 [SECURITY.md](SECURITY.md) for private vulnerability reporting.

package/dist/color.d.ts

@@ -8,3 +8,10 @@ export declare function color(value: string): ColorScale;
 export declare function useColor(value: string): ColorScale;
 /** 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. */
+export declare function colorLightness(value: string): number;
+/** Orders resolved CSS colors by perceptual lightness, never by their role. */
+export declare function orderColors(first: string, second: string): {
+    lighter: string;
+    darker: string;
+};

package/dist/color.js

@@ -1,4 +1,8 @@
 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";
+// 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);
 /** Derives visual treatments while preserving the concrete value at `base`. */
 export function color(value) {
     return Object.freeze({
@@ -18,3 +22,15 @@ export function colorOpacity(value, opacity) {
     const percentage = Math.round(opacity * 10_000) / 100;
     return `color-mix(in srgb, ${value} ${percentage}%, transparent)`;
 }
+/** Reads perceptual lightness from a resolved CSS color. */
+export function colorLightness(value) {
+    // A missing CSS channel (`none`) contributes zero outside interpolation.
+    return OKLCH.from(parse(value))[0] ?? 0;
+}
+/** Orders resolved CSS colors by perceptual lightness, never by their role. */
+export function orderColors(first, second) {
+    const difference = colorLightness(first) - colorLightness(second);
+    return difference > 0 || (difference === 0 && first >= second)
+        ? { lighter: first, darker: second }
+        : { lighter: second, darker: first };
+}

package/dist/main.d.ts

@@ -8,6 +8,7 @@ export { AppearanceProvider, useAppearance, useResolveTheme, useTheme, type Appe
 export { Flex, type FlexProps } from "./flex.js";
 export { Grid, type GridProps } from "./grid.js";
 export { Surface, type SurfaceProps } from "./surface.js";
+export { Panel, type PanelProps } from "./panel.js";
 export { Button, type ButtonProps } from "./button.js";
 export type { LayoutAlignment, LayoutGap, LayoutJustification } from "./layout.js";
 export { resolveRadius, type Radius, type RadiusProps } from "./radius.js";

package/dist/main.js

@@ -8,6 +8,7 @@ export { AppearanceProvider, useAppearance, useResolveTheme, useTheme } from "./
 export { Flex } from "./flex.js";
 export { Grid } from "./grid.js";
 export { Surface } from "./surface.js";
+export { Panel } from "./panel.js";
 export { Button } from "./button.js";
 export { resolveRadius } from "./radius.js";
 export { resolveSpacing } from "./spacing.js";

package/dist/panel.d.ts

@@ -0,0 +1,9 @@
+import { type ReactNode } from "react";
+import { type SurfaceProps } from "./surface.js";
+/** A Surface with an optional header and an inset content Surface. */
+export interface PanelProps extends SurfaceProps {
+    readonly header?: ReactNode;
+    readonly contentProps?: Omit<SurfaceProps, "children">;
+}
+/** Owns the shared shell layout, not positioning, interaction, or lifecycle. */
+export declare const Panel: import("react").ForwardRefExoticComponent<PanelProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/panel.js

@@ -0,0 +1,27 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef } from "react";
+import { useAppearance, useResolveTheme } from "./appearance-provider.js";
+import { scale } from "./scale.js";
+import { Surface } from "./surface.js";
+/** Owns the shared shell layout, not positioning, interaction, or lifecycle. */
+export const Panel = forwardRef(function Panel({ header, children, contentProps, style, ...properties }, ref) {
+    const appearance = useAppearance();
+    const inset = scale(useResolveTheme(appearance.spacing), "small");
+    const hasHeader = header !== undefined && header !== null && header !== false;
+    return _jsxs(Surface, { ...properties, ref: ref, style: {
+            display: "grid",
+            gridTemplateRows: hasHeader ? "auto minmax(0, 1fr)" : "minmax(0, 1fr)",
+            minWidth: 0,
+            minHeight: 0,
+            maxHeight: "inherit",
+            ...style
+        }, children: [header, _jsx(Surface, { ...contentProps, style: {
+                    position: "relative",
+                    minWidth: 0,
+                    minHeight: 0,
+                    margin: inset,
+                    marginTop: hasHeader ? 0 : inset,
+                    overflow: "hidden",
+                    ...contentProps?.style
+                }, children: children })] });
+});

package/dist/surface-material.d.ts

@@ -1,6 +1,7 @@
 interface SurfaceMaterialProps {
     readonly color: string;
     readonly distortion: number;
+    readonly foreground: string;
     readonly grain: number;
     readonly grainAmount: number;
     readonly identity: string;
@@ -8,6 +9,6 @@ interface SurfaceMaterialProps {
     readonly ripples: number;
     readonly waves: number;
 }
-/** The locally owned SVG paint layer inside one Surface. */
-export declare function SurfaceMaterial({ color, distortion, grain, grainAmount, identity, opacity, ripples, waves }: SurfaceMaterialProps): import("react").JSX.Element | null;
+/** The locally owned fill, refraction definition, and glass rim inside one Surface. */
+export declare function SurfaceMaterial({ color, distortion, foreground, grain, grainAmount, identity, opacity, ripples, waves }: SurfaceMaterialProps): import("react").JSX.Element | null;
 export {};

package/dist/surface-material.js

@@ -1,37 +1,63 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Fragment, useMemo } from "react";
+import { Fragment, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { colorLightness, colorOpacity, orderColors } from "./color.js";
 import { scale } from "./scale.js";
-/** The locally owned SVG paint layer inside one Surface. */
-export function SurfaceMaterial({ color, distortion, grain, grainAmount, identity, opacity, ripples, waves }) {
+/** The locally owned fill, refraction definition, and glass rim inside one Surface. */
+export function SurfaceMaterial({ color, distortion, foreground, grain, grainAmount, identity, opacity, ripples, waves }) {
+    const element = useRef(null);
+    const [colors, setColors] = useState(null);
     const seed = useMemo(() => seedFrom(identity), [identity]);
     const hasPaint = opacity > 0;
     const hasGrain = hasPaint && grain > 0 && grainAmount > 0;
     const hasDistortion = distortion > 0 || waves > 0 || ripples > 0;
     const initial = useMemo(() => hasGrain ? grainPaths(seed, grainAmount) : [], [grainAmount, hasGrain, seed]);
+    // Resolve variables, currentColor, and CSS expressions in this Surface's
+    // own scope before comparing colors. Layout effects settle before paint.
+    useLayoutEffect(() => {
+        const material = element.current;
+        const view = material?.ownerDocument.defaultView;
+        if (!material || !view || !hasPaint)
+            return;
+        const computed = view.getComputedStyle(material);
+        const background = computed.fill;
+        const foreground = computed.color;
+        if (colors?.background === background && colors.foreground === foreground)
+            return;
+        setColors({ ...orderColors(background, foreground), background, foreground, lightness: Math.max(0, Math.min(1, colorLightness(background))) });
+    });
     if (!hasPaint && !hasDistortion)
         return null;
-    return _jsxs("svg", { "data-surface-material": "", "data-surface-border": hasPaint ? "" : undefined, "aria-hidden": "true", focusable: "false", style: {
-            position: "absolute",
-            zIndex: -1,
-            inset: 0,
-            display: "block",
-            width: "100%",
-            height: "100%",
-            overflow: "hidden",
-            borderRadius: "inherit",
-            borderColor: edgeColor(color, opacity),
-            borderStyle: hasPaint ? "solid" : "none",
-            borderWidth: hasPaint ? 1 : 0,
-            boxSizing: "border-box",
-            pointerEvents: "none"
-        }, children: [(hasGrain || hasDistortion) && _jsxs("defs", { children: [hasDistortion && _jsx(DistortionFilter, { distortion: distortion, identity: identity, ripples: ripples, seed: seed, waves: waves }), hasGrain && _jsx("pattern", { id: `${identity}-grain`, width: patternSize, height: patternSize, patternUnits: "userSpaceOnUse", children: initial.map((path, tone) => _jsx("path", { "data-surface-grain-tone": tone, d: path, fill: grainTone(color, tone, grain), shapeRendering: "crispEdges" }, tone)) })] }), hasPaint && _jsxs("g", { "data-surface-paint": "", opacity: opacity, children: [_jsx("rect", { "data-surface-base": "", width: "100%", height: "100%", fill: color }), hasGrain && _jsx("rect", { "data-surface-grain": "", width: "100%", height: "100%", fill: `url(#${identity}-grain)`, shapeRendering: "crispEdges" })] })] });
+    return _jsxs(Fragment, { children: [_jsxs("svg", { "data-surface-material": "", "aria-hidden": "true", focusable: "false", style: {
+                    position: "absolute",
+                    zIndex: -1,
+                    inset: 0,
+                    display: "block",
+                    width: "100%",
+                    height: "100%",
+                    overflow: "hidden",
+                    borderRadius: "inherit",
+                    boxShadow: hasPaint && colors ? `inset 0 1px 2px ${colorOpacity(colors.lighter, 0.28)}, 0 8px 24px ${colorOpacity(colors.darker, 0.04)}` : undefined,
+                    pointerEvents: "none"
+                }, children: [(hasGrain || hasDistortion) && _jsxs("defs", { children: [hasDistortion && _jsx(DistortionFilter, { distortion: distortion, identity: identity, ripples: ripples, seed: seed, waves: waves }), hasGrain && _jsx("pattern", { id: `${identity}-grain`, width: patternSize, height: patternSize, patternUnits: "userSpaceOnUse", children: initial.map((path, tone) => _jsx("path", { "data-surface-grain-tone": tone, d: path, fill: grainTone(color, tone, grain), shapeRendering: "crispEdges" }, tone)) })] }), hasPaint && _jsxs("g", { "data-surface-paint": "", opacity: opacity, children: [_jsx("rect", { ref: element, "data-surface-base": "", width: "100%", height: "100%", style: { fill: color, color: foreground } }), hasGrain && _jsx("rect", { "data-surface-grain": "", width: "100%", height: "100%", fill: `url(#${identity}-grain)`, shapeRendering: "crispEdges" })] })] }), hasPaint && _jsx("div", { "data-surface-border": "", "aria-hidden": "true", style: {
+                    position: "absolute",
+                    // The material belongs behind content; its rim belongs above it.
+                    // Opaque children must not erase the Surface's rounded edge.
+                    zIndex: 1,
+                    inset: 0,
+                    padding: 1,
+                    borderRadius: "inherit",
+                    pointerEvents: "none",
+                    opacity: Math.min(1, scale(opacity, "xlarge")) * (colors?.lightness ?? 0),
+                    background: colors ? glassRim(colors.lighter, colors.darker) : undefined,
+                    WebkitMask: "linear-gradient(#000 0 0) content-box, linear-gradient(#000 0 0)",
+                    WebkitMaskComposite: "xor",
+                    mask: "linear-gradient(#000 0 0) content-box, linear-gradient(#000 0 0)",
+                    maskComposite: "exclude"
+                } })] });
 }
-function edgeColor(color, opacity) {
-    const edge = `color-mix(in oklch, ${color} 94%, black)`;
-    const edgeOpacity = Math.min(1, scale(opacity, "large"));
-    if (edgeOpacity === 1)
-        return edge;
-    return `color-mix(in srgb, ${edge} ${Math.round(edgeOpacity * 10_000) / 100}%, transparent)`;
+function glassRim(light, dark) {
+    const edge = `color-mix(in oklch, ${dark} 20%, ${light})`;
+    return `linear-gradient(145deg, ${colorOpacity(light, 0.92)}, ${colorOpacity(light, 0.4)} 35%, ${colorOpacity(edge, 0.18)} 55%, ${colorOpacity(light, 0.6)} 85%, ${colorOpacity(light, 0.3)})`;
 }
 function DistortionFilter({ distortion, identity, ripples, seed, waves }) {
     const fields = [

package/dist/surface.js

@@ -15,7 +15,7 @@ export const Surface = forwardRef(function Surface({ backdrop, brightness, child
     const appearance = useAppearance();
     const background = useResolveTheme(appearance.background);
     const foreground = useResolveTheme(appearance.foreground);
-    const radius = useResolveTheme(appearance.radius);
+    const radius = scale(useResolveTheme(appearance.radius), "medium");
     const surface = useResolveTheme(appearance.surface);
     const identity = `phresh-surface-${useId().replaceAll(":", "")}`;
     const element = useRef(null);
@@ -36,7 +36,7 @@ export const Surface = forwardRef(function Surface({ backdrop, brightness, child
             borderRadius: radius,
             color: foreground,
             ...style
-        }, children: [resolved.refracts && _jsx(BackdropLayer, { name: "refraction", filter: `url("#${identity}-distortion")`, zIndex: -3 }), resolved.frost && _jsx(BackdropLayer, { name: "frost", filter: resolved.frost, zIndex: -2 }), _jsx(SurfaceMaterial, { identity: identity, ...resolved.material }), children] });
+        }, children: [resolved.refracts && _jsx(BackdropLayer, { name: "refraction", filter: `url("#${identity}-distortion")`, zIndex: -3 }), resolved.frost && _jsx(BackdropLayer, { name: "frost", filter: resolved.frost, zIndex: -2 }), _jsx(SurfaceMaterial, { identity: identity, foreground: foreground, ...resolved.material }), children] });
 });
 /** Keeps refraction and native frost in independent compositor passes. */
 function BackdropLayer({ filter, name, zIndex }) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/react-ui",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "React components for coherent PhreshOS Program interfaces.",
   "type": "module",
   "sideEffects": false,
@@ -52,16 +52,17 @@
     "prepack": "node --run test && node --run build"
   },
   "peerDependencies": {
-    "@phreshos/core": "^0.1.37",
+    "@phreshos/core": "^0.1.41",
     "react": "^19.2.0",
     "react-dom": "^19.2.0"
   },
   "dependencies": {
+    "colorjs.io": "^0.7.1",
     "react-aria-components": "^1.20.0"
   },
   "devDependencies": {
     "@base-ui/react": "^1.7.0",
-    "@phreshos/core": "^0.1.37",
+    "@phreshos/core": "^0.1.41",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.0",
     "@testing-library/user-event": "^14.6.1",