@phreshos/react-ui 0.1.4 → 0.1.5

package/README.md

@@ -83,9 +83,10 @@ Explicit values such as `4rem` are used directly — passing them through a
 Theme hook would perform no additional work.
 
 `Surface` keeps a native `<div>` as its public container and gives every
-instance one locally owned pure-SVG material. The material uses a deterministic
-64×64 micro-pattern derived from the former shader grain; it creates no canvas,
-WebGL context, or shared texture:
+instance one locally owned pure-SVG material plus only the backdrop layers its
+settings enable. The material uses a deterministic 64×64 micro-pattern derived
+from the former shader grain; it creates no canvas, WebGL context, or shared
+texture:
 
 ```tsx
 <Surface className="grid rounded-xl shadow-lg">
@@ -94,16 +95,25 @@ WebGL context, or shared texture:
 
 <Surface color="strong" grain="large">...</Surface>
 <Surface color="#101114" grain={0.2} animation={8} backdrop={4} opacity={0.9}>...</Surface>
+<Surface distortion={70} waves={8} ripples={4} saturation={1.4} brightness={1.04}>...</Surface>
 ```
 
 `color` resolves from `Theme.background`; its semantic levels derive from that
 same source and a direct color remains an explicit local override. `grain`,
-`animation`, `backdrop`, and `opacity` resolve from `Theme.surface`, accept
+`grainAmount`, `animation`, `backdrop`, `opacity`, `distortion`, `waves`,
+`ripples`, `saturation`, and `brightness` resolve from `Theme.surface`, accept
 their semantic levels or direct values, and remain bounded by Core's Theme
-limits. Radius and foreground remain ordinary Theme styles. Backdrop belongs
-to the outer div and emits no filter property when its resolved value is zero.
-Animation defaults to zero; only explicitly animated Surfaces join the internal
-document clock, while every texture and seed remains local to its own Surface.
+limits. Radius and foreground remain ordinary Theme styles. Grain intensity
+controls tonal distance while grain amount controls retained cell density.
+When either is zero, Surface creates no grain pattern or paths. Refraction and
+native frost use independent backdrop layers so blur does not soften the
+displaced image. Enabled organic, wave, and ripple fields are combined
+mathematically before one displacement pass; each zero-valued field is absent,
+and the filter and refraction layer are absent when all three are zero.
+Backdrop blur emits no CSS function at zero. Neutral saturation and brightness
+at one are also omitted. Animation defaults to zero; only a Surface with
+visible grain and a positive rate joins the internal document clock, while
+every texture and seed remains local to its own Surface.
 
 The Theme stores unrestricted CSS background, foreground, and accent sources.
 Core derives the fixed `subtle`, `soft`, `base`, `strong`, and `intense`

package/dist/surface-material.d.ts

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

package/dist/surface-material.js

@@ -1,22 +1,26 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useId, useMemo, useRef } from "react";
+import { Fragment, useEffect, useMemo, useRef } from "react";
 /** The locally owned SVG paint layer inside one Surface. */
-export function SurfaceMaterial({ animation, color, grain, opacity }) {
-    const identity = `phresh-surface-${useId().replaceAll(":", "")}`;
+export function SurfaceMaterial({ animation, color, distortion, grain, grainAmount, identity, opacity, ripples, waves }) {
     const seed = useMemo(() => seedFrom(identity), [identity]);
-    const initial = useMemo(() => grainPaths(seed, 0), [seed]);
+    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, 0, grainAmount) : [], [grainAmount, hasGrain, seed]);
     const svg = useRef(null);
     const paths = useRef([]);
     useEffect(() => {
         paths.current.forEach((path, tone) => path?.setAttribute("d", initial[tone] ?? ""));
-        if (animation === 0 || !svg.current)
+        if (animation === 0 || !hasGrain || !svg.current)
             return;
         const paint = (frame) => {
-            const values = grainPaths(seed, frame);
+            const values = grainPaths(seed, frame, grainAmount);
             paths.current.forEach((path, tone) => path?.setAttribute("d", values[tone] ?? ""));
         };
         return animate(svg.current, animation, paint);
-    }, [animation, initial, seed]);
+    }, [animation, grainAmount, hasGrain, initial, seed]);
+    if (!hasPaint && !hasDistortion)
+        return null;
     return _jsxs("svg", { ref: svg, "data-surface-material": "", "aria-hidden": "true", focusable: "false", style: {
             position: "absolute",
             zIndex: -1,
@@ -26,14 +30,33 @@ export function SurfaceMaterial({ animation, color, grain, opacity }) {
             height: "100%",
             overflow: "hidden",
             borderRadius: "inherit",
-            border: "1px solid rgba(15, 17, 21, 0.08)",
             boxSizing: "border-box",
             opacity,
             pointerEvents: "none"
-        }, children: [_jsx("defs", { children: _jsx("pattern", { id: identity, width: patternSize, height: patternSize, patternUnits: "userSpaceOnUse", children: initial.map((path, tone) => {
-                        const channel = Math.round(tone / (toneCount - 1) * 255);
-                        return _jsx("path", { ref: node => { paths.current[tone] = node; }, "data-surface-grain-tone": tone, d: path, fill: `rgb(${channel}, ${channel}, ${channel})`, shapeRendering: "crispEdges" }, tone);
-                    }) }) }), _jsx("rect", { "data-surface-base": "", width: "100%", height: "100%", fill: color }), _jsx("rect", { "data-surface-grain": "", width: "100%", height: "100%", fill: `url(#${identity})`, opacity: grain, shapeRendering: "crispEdges" })] });
+        }, 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", { ref: node => { paths.current[tone] = node; }, "data-surface-grain-tone": tone, d: path, fill: grainTone(color, tone, grain), shapeRendering: "crispEdges" }, tone)) })] }), hasPaint && _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" })] });
+}
+function DistortionFilter({ distortion, identity, ripples, seed, waves }) {
+    const fields = [
+        distortion > 0 && { name: "organic", strength: distortion, x: "R" },
+        waves > 0 && { name: "waves", strength: waves, x: "R" },
+        ripples > 0 && { name: "ripples", strength: ripples, x: "B" }
+    ].filter((field) => Boolean(field));
+    const scale = fields.reduce((total, field) => total + field.strength, 0);
+    const weighted = fields.map(field => `${identity}-${field.name}-weighted`);
+    const map = `${identity}-distortion-map`;
+    return _jsxs("filter", { id: `${identity}-distortion`, "data-surface-distortion": "", x: "-20%", y: "-20%", width: "140%", height: "140%", colorInterpolationFilters: "sRGB", children: [distortion > 0 && _jsxs(Fragment, { children: [_jsx("feTurbulence", { "data-surface-distortion-noise": "", "data-surface-distortion-field": "organic", type: "fractalNoise", baseFrequency: "0.008 0.008", numOctaves: 2, seed: 92, result: `${identity}-organic-noise` }), _jsx("feGaussianBlur", { in: `${identity}-organic-noise`, stdDeviation: 2, result: `${identity}-organic-noise-blurred` })] }), waves > 0 && _jsx(Fragment, { children: _jsx("feTurbulence", { "data-surface-distortion-field": "waves", type: "turbulence", baseFrequency: "0.006 0.045", numOctaves: 1, seed: seed + 17, result: `${identity}-waves-noise` }) }), ripples > 0 && _jsx(Fragment, { children: _jsx("feTurbulence", { "data-surface-distortion-field": "ripples", type: "turbulence", baseFrequency: "0.055", numOctaves: 2, seed: seed + 31, result: `${identity}-ripples-noise` }) }), fields.map(field => _jsx("feColorMatrix", { "data-surface-distortion-weight": field.name, in: `${identity}-${field.name}-noise${field.name === "organic" ? "-blurred" : ""}`, type: "matrix", values: weightMatrix(field.x, field.strength / scale), result: `${identity}-${field.name}-weighted` }, field.name)), weighted.slice(1).map((field, index) => _jsx("feComposite", { "data-surface-distortion-combine": "", in: index === 0 ? weighted[0] : `${identity}-distortion-sum-${index}`, in2: field, operator: "arithmetic", k2: 1, k3: 1, result: index === weighted.length - 2 ? map : `${identity}-distortion-sum-${index + 1}` }, field)), _jsx("feDisplacementMap", { "data-surface-distortion-stage": "combined", in: "SourceGraphic", in2: weighted.length === 1 ? weighted[0] : map, scale: scale, xChannelSelector: "R", yChannelSelector: "G" })] });
+}
+function weightMatrix(x, weight) {
+    const red = x === "R" ? `${weight} 0 0 0 0` : `0 0 ${weight} 0 0`;
+    return `${red}
+          0 ${weight} 0 0 0
+          0 0 0 0 0
+          0 0 0 1 0`;
+}
+function grainTone(color, tone, intensity) {
+    const channel = Math.round(tone / (toneCount - 1) * 255);
+    const percentage = Math.round(intensity * 10_000) / 100;
+    return `color-mix(in srgb, ${color} ${100 - percentage}%, rgb(${channel} ${channel} ${channel}) ${percentage}%)`;
 }
 class AnimationClock {
     #entries = new Set();
@@ -88,7 +111,7 @@ function animate(element, rate, paint) {
     }
     return clock.subscribe(rate, paint);
 }
-function grainPaths(seed, frame) {
+function grainPaths(seed, frame, amount) {
     const tones = Array.from({ length: toneCount }, () => []);
     const frameX = frame * 19.17;
     const frameY = frame * 7.31;
@@ -96,6 +119,9 @@ function grainPaths(seed, frame) {
         for (let x = 0; x < patternSize; x += 1) {
             const pointX = x + seed * 41;
             const pointY = y + seed * 17;
+            const presence = shaderHash(pointX + frameX + 71.9, pointY + frameY + 13.7);
+            if (presence > amount)
+                continue;
             const fine = shaderHash(Math.floor(pointX * 1.18) + frameX, Math.floor(pointY * 1.18) + frameY);
             const clustered = shaderHash(Math.floor(pointX * 0.47) + frameX + 31.7, Math.floor(pointY * 0.47) + frameY + 31.7);
             const value = clamp(fine * 0.8 + clustered * 0.2, 0, 1);

package/dist/surface.d.ts

@@ -8,23 +8,47 @@ export type SurfaceProps = Omit<ComponentPropsWithoutRef<"div">, "color" | "opac
     color?: SurfaceColor;
     /** Theme-derived level or direct grain intensity from zero to one. */
     grain?: ScaleLevel | number;
+    /** Theme-derived level or direct retained grain amount from zero to one. */
+    grainAmount?: ScaleLevel | number;
     /** Theme-derived level or direct grain changes per second from zero to 16. */
     animation?: ScaleLevel | number;
     /** Theme-derived level or direct backdrop blur from zero to 24 CSS pixels. */
     backdrop?: ScaleLevel | number;
     /** Theme-derived level or direct material opacity from zero to one. */
     opacity?: ScaleLevel | number;
+    /** Theme-derived level or direct organic displacement from zero to 140 pixels. */
+    distortion?: ScaleLevel | number;
+    /** Theme-derived level or direct directional displacement from zero to 40 pixels. */
+    waves?: ScaleLevel | number;
+    /** Theme-derived level or direct ripple displacement from zero to 40 pixels. */
+    ripples?: ScaleLevel | number;
+    /** Theme-derived level or direct backdrop saturation multiplier. */
+    saturation?: ScaleLevel | number;
+    /** Theme-derived level or direct backdrop brightness multiplier. */
+    brightness?: ScaleLevel | number;
 }>;
-/** Contains content above one independent pure-SVG Surface material. */
+/** Contains content above locally owned Surface material layers. */
 export declare const Surface: import("react").ForwardRefExoticComponent<Omit<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, "color" | "opacity"> & Readonly<{
     /** Theme-derived treatment or direct CSS material color. */
     color?: SurfaceColor;
     /** Theme-derived level or direct grain intensity from zero to one. */
     grain?: ScaleLevel | number;
+    /** Theme-derived level or direct retained grain amount from zero to one. */
+    grainAmount?: ScaleLevel | number;
     /** Theme-derived level or direct grain changes per second from zero to 16. */
     animation?: ScaleLevel | number;
     /** Theme-derived level or direct backdrop blur from zero to 24 CSS pixels. */
     backdrop?: ScaleLevel | number;
     /** Theme-derived level or direct material opacity from zero to one. */
     opacity?: ScaleLevel | number;
+    /** Theme-derived level or direct organic displacement from zero to 140 pixels. */
+    distortion?: ScaleLevel | number;
+    /** Theme-derived level or direct directional displacement from zero to 40 pixels. */
+    waves?: ScaleLevel | number;
+    /** Theme-derived level or direct ripple displacement from zero to 40 pixels. */
+    ripples?: ScaleLevel | number;
+    /** Theme-derived level or direct backdrop saturation multiplier. */
+    saturation?: ScaleLevel | number;
+    /** Theme-derived level or direct backdrop brightness multiplier. */
+    brightness?: ScaleLevel | number;
 }> & import("react").RefAttributes<HTMLDivElement>>;

package/dist/surface.js

@@ -1,40 +1,87 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { forwardRef, useCallback, useLayoutEffect, useRef } from "react";
-import { color as deriveColor, isScaleLevel, scale, themeLimits } from "@phreshos/core";
+import { forwardRef, useCallback, useId, useLayoutEffect, useRef } from "react";
+import { color as deriveColor, isScaleLevel, scale, scaleMultiplier, themeLimits } from "@phreshos/core";
 import { SurfaceMaterial } from "./surface-material.js";
 import { useTheme } from "./theme-provider.js";
-/** Contains content above one independent pure-SVG Surface material. */
-export const Surface = forwardRef(function Surface({ animation, backdrop, children, color, grain, opacity, style, ...properties }, forwardedRef) {
+const layerStyle = {
+    position: "absolute",
+    inset: 0,
+    borderRadius: "inherit",
+    pointerEvents: "none"
+};
+const borderOpacity = 0.3;
+/** Contains content above locally owned Surface material layers. */
+export const Surface = forwardRef(function Surface({ animation, backdrop, brightness, children, color, distortion, grain, grainAmount, opacity, ripples, saturation, style, waves, ...properties }, forwardedRef) {
     const theme = useTheme();
+    const identity = `phresh-surface-${useId().replaceAll(":", "")}`;
     const element = useRef(null);
-    const ref = useCallback((node) => {
+    const capture = useCallback((node) => {
         element.current = node;
         if (typeof forwardedRef === "function")
             forwardedRef(node);
         else if (forwardedRef)
             forwardedRef.current = node;
     }, [forwardedRef]);
-    const resolvedColor = resolveColor(color, theme.background);
-    const resolvedGrain = resolveScale(grain, theme.surface.grain, themeLimits.surface.grain);
-    const resolvedAnimation = resolveScale(animation, theme.surface.animation, themeLimits.surface.animation);
-    const resolvedBackdrop = resolveScale(backdrop, theme.surface.backdrop, themeLimits.surface.backdrop);
-    const resolvedOpacity = resolveScale(opacity, theme.surface.opacity, themeLimits.surface.opacity);
-    const blur = resolvedBackdrop === 0 ? {} : {
-        backdropFilter: `blur(${resolvedBackdrop}px)`,
-        WebkitBackdropFilter: `blur(${resolvedBackdrop}px)`
-    };
+    const resolved = resolveSurface({ animation, backdrop, brightness, color, distortion, grain, grainAmount, opacity, ripples, saturation, waves }, theme);
     useLayoutEffect(() => {
         const surface = element.current;
         if (surface)
             return prepareSurfaceLayout(surface);
     });
-    return _jsxs("div", { ...properties, ref: ref, style: {
+    return _jsxs("div", { ...properties, ref: capture, style: {
             borderRadius: theme.radius,
             color: theme.foreground,
-            ...blur,
             ...style
-        }, children: [_jsx(SurfaceMaterial, { animation: resolvedAnimation, color: resolvedColor, grain: resolvedGrain, opacity: resolvedOpacity }), 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(SurfaceBorder, { color: resolved.material.color }), _jsx(SurfaceMaterial, { identity: identity, ...resolved.material }), children] });
 });
+/** Draws one continuous edge from the same color as the Surface material. */
+function SurfaceBorder({ color }) {
+    const highlight = `color-mix(in oklch, ${color} 88%, white)`;
+    const shade = `color-mix(in oklch, ${color} 94%, black)`;
+    return _jsx("div", { "data-surface-border": "", "aria-hidden": "true", style: {
+            ...layerStyle,
+            zIndex: 0,
+            borderStyle: "solid",
+            borderWidth: 1,
+            borderColor: `${highlight} ${shade} ${shade} ${highlight}`,
+            boxSizing: "border-box",
+            opacity: borderOpacity
+        } });
+}
+/** Keeps refraction and native frost in independent compositor passes. */
+function BackdropLayer({ filter, name, zIndex }) {
+    return _jsx("div", { "data-surface-backdrop": name, "aria-hidden": "true", style: {
+            ...layerStyle,
+            zIndex,
+            backdropFilter: filter,
+            WebkitBackdropFilter: filter
+        } });
+}
+function resolveSurface(values, theme) {
+    const material = {
+        animation: resolveScale(values.animation, theme.surface.animation, themeLimits.surface.animation),
+        color: resolveColor(values.color, theme.background),
+        distortion: resolveScale(values.distortion, theme.surface.distortion, themeLimits.surface.distortion),
+        grain: resolveScale(values.grain, theme.surface.grain, themeLimits.surface.grain),
+        grainAmount: resolveScale(values.grainAmount, theme.surface.grainAmount, themeLimits.surface.grainAmount),
+        opacity: resolveScale(values.opacity, theme.surface.opacity, themeLimits.surface.opacity),
+        ripples: resolveScale(values.ripples, theme.surface.ripples, themeLimits.surface.ripples),
+        waves: resolveScale(values.waves, theme.surface.waves, themeLimits.surface.waves)
+    };
+    const backdrop = resolveScale(values.backdrop, theme.surface.backdrop, themeLimits.surface.backdrop);
+    const saturation = resolveMultiplier(values.saturation, theme.surface.saturation, themeLimits.surface.saturation);
+    const brightness = resolveMultiplier(values.brightness, theme.surface.brightness, themeLimits.surface.brightness);
+    const frost = [
+        backdrop === 0 ? "" : `blur(${backdrop}px)`,
+        saturation === 1 ? "" : `saturate(${saturation})`,
+        brightness === 1 ? "" : `brightness(${brightness})`
+    ].filter(Boolean).join(" ");
+    return {
+        material,
+        frost,
+        refracts: material.distortion > 0 || material.waves > 0 || material.ripples > 0
+    };
+}
 function resolveColor(value, base) {
     if (value === undefined)
         return base;
@@ -48,6 +95,11 @@ function resolveScale(value, base, range) {
     const finite = Number.isFinite(resolved) ? resolved : base;
     return Math.min(range.maximum, Math.max(range.minimum, finite));
 }
+function resolveMultiplier(value, base, range) {
+    const resolved = isScaleLevel(value) ? scaleMultiplier(base, value) : value ?? base;
+    const finite = Number.isFinite(resolved) ? resolved : base;
+    return Math.min(range.maximum, Math.max(range.minimum, finite));
+}
 function prepareSurfaceLayout(element) {
     const view = element.ownerDocument.defaultView;
     const computed = view?.getComputedStyle(element);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/react-ui",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "React components for coherent PhreshOS Program interfaces.",
   "type": "module",
   "sideEffects": false,
@@ -52,7 +52,7 @@
     "prepack": "node --run test && node --run build"
   },
   "peerDependencies": {
-    "@phreshos/core": "^0.1.8",
+    "@phreshos/core": "^0.1.9",
     "react": "^19.2.0",
     "react-dom": "^19.2.0"
   },
@@ -61,7 +61,7 @@
   },
   "devDependencies": {
     "@base-ui/react": "^1.7.0",
-    "@phreshos/core": "^0.1.8",
+    "@phreshos/core": "^0.1.9",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.0",
     "@testing-library/user-event": "^14.6.1",