@phreshos/react-ui 0.1.1 → 0.1.3

package/README.md

@@ -82,6 +82,29 @@ const spacing = useScale(theme.spacing)
 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:
+
+```tsx
+<Surface className="grid rounded-xl shadow-lg">
+  ...
+</Surface>
+
+<Surface color="strong" grain="large">...</Surface>
+<Surface color="#101114" grain={0.2} animation={8} backdrop={4} opacity={0.9}>...</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
+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.
+
 The Theme stores unrestricted CSS background, foreground, and accent sources.
 Core derives the fixed `subtle`, `soft`, `base`, `strong`, and `intense`
 treatments from any supplied color, preserving the value exactly at `base`.
@@ -156,8 +179,9 @@ Pending Buttons remain focusable but cannot activate. Disabled Buttons leave
 the focus order entirely. The native element defaults to `type="button"`, so
 placing it inside a form never triggers an accidental submission.
 
-`ThemeProvider` accepts a plain `ThemeProperties` snapshot, so the library
-remains usable without either environment SDK. A Program can adapt its
+`ThemeProvider` accepts a plain `ThemeProperties` snapshot, such as Core's
+`standardTheme`, so the library remains usable without either environment SDK.
+A Program can adapt its
 observable Host value at the application boundary:
 
 ```tsx

package/dist/main.d.ts

@@ -7,6 +7,7 @@
 export { ThemeProvider, useTheme, type ThemeProviderProps } from "./theme-provider.js";
 export { Flex, type FlexProps } from "./flex.js";
 export { Grid, type GridProps } from "./grid.js";
+export { Surface, type SurfaceColor, type SurfaceProps } from "./surface.js";
 export { GlassSurface, type GlassSurfaceProps } from "./glass-surface.js";
 export { Button, type ButtonProps } from "./button.js";
 export type { LayoutAlignment, LayoutGap, LayoutJustification } from "./layout.js";

package/dist/main.js

@@ -7,6 +7,7 @@
 export { ThemeProvider, useTheme } from "./theme-provider.js";
 export { Flex } from "./flex.js";
 export { Grid } from "./grid.js";
+export { Surface } from "./surface.js";
 export { GlassSurface } from "./glass-surface.js";
 export { Button } from "./button.js";
 export { resolveRadius } from "./radius.js";

package/dist/surface-material.d.ts

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

package/dist/surface-material.js

@@ -0,0 +1,133 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useId, 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(":", "")}`;
+    const seed = useMemo(() => seedFrom(identity), [identity]);
+    const initial = useMemo(() => grainPaths(seed, 0), [seed]);
+    const svg = useRef(null);
+    const paths = useRef([]);
+    useEffect(() => {
+        paths.current.forEach((path, tone) => path?.setAttribute("d", initial[tone] ?? ""));
+        if (animation === 0 || !svg.current)
+            return;
+        const paint = (frame) => {
+            const values = grainPaths(seed, frame);
+            paths.current.forEach((path, tone) => path?.setAttribute("d", values[tone] ?? ""));
+        };
+        return animate(svg.current, animation, paint);
+    }, [animation, initial, seed]);
+    return _jsxs("svg", { ref: 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",
+            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" })] });
+}
+class AnimationClock {
+    #entries = new Set();
+    #view;
+    #request;
+    constructor(view) {
+        this.#view = view;
+    }
+    subscribe(rate, paint) {
+        const entry = { rate, paint, frame: -1 };
+        this.#entries.add(entry);
+        this.#start();
+        return () => {
+            this.#entries.delete(entry);
+            if (this.#entries.size === 0)
+                this.#stop();
+        };
+    }
+    #start() {
+        if (this.#request !== undefined)
+            return;
+        this.#request = this.#view.requestAnimationFrame(this.#tick);
+    }
+    #stop() {
+        if (this.#request === undefined)
+            return;
+        this.#view.cancelAnimationFrame(this.#request);
+        this.#request = undefined;
+    }
+    #tick = (time) => {
+        this.#entries.forEach(entry => {
+            const frame = Math.floor(time / 1000 * entry.rate);
+            if (frame === entry.frame)
+                return;
+            entry.frame = frame;
+            entry.paint(frame);
+        });
+        this.#request = this.#entries.size === 0
+            ? undefined
+            : this.#view.requestAnimationFrame(this.#tick);
+    };
+}
+const clocks = new WeakMap();
+function animate(element, rate, paint) {
+    const view = element.ownerDocument.defaultView;
+    if (!view)
+        return;
+    let clock = clocks.get(view);
+    if (!clock) {
+        clock = new AnimationClock(view);
+        clocks.set(view, clock);
+    }
+    return clock.subscribe(rate, paint);
+}
+function grainPaths(seed, frame) {
+    const tones = Array.from({ length: toneCount }, () => []);
+    const frameX = frame * 19.17;
+    const frameY = frame * 7.31;
+    for (let y = 0; y < patternSize; y += 1) {
+        for (let x = 0; x < patternSize; x += 1) {
+            const pointX = x + seed * 41;
+            const pointY = y + seed * 17;
+            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);
+            const tone = Math.min(toneCount - 1, Math.floor(value * toneCount));
+            tones[tone]?.push(`M${x} ${y}h1v1h-1z`);
+        }
+    }
+    return tones.map(tone => tone.join(""));
+}
+function shaderHash(x, y) {
+    let red = fract(x * 0.1031);
+    let green = fract(y * 0.1031);
+    let blue = fract(x * 0.1031);
+    const product = red * (green + 33.33) + green * (blue + 33.33) + blue * (red + 33.33);
+    red += product;
+    green += product;
+    blue += product;
+    return fract((red + green) * blue);
+}
+function seedFrom(value) {
+    let seed = 2166136261;
+    for (const character of value) {
+        seed ^= character.codePointAt(0) ?? 0;
+        seed = Math.imul(seed, 16777619);
+    }
+    return (seed >>> 0) % 997 + 1;
+}
+function fract(value) {
+    return value - Math.floor(value);
+}
+function clamp(value, minimum, maximum) {
+    return Math.min(maximum, Math.max(minimum, value));
+}
+const patternSize = 64;
+const toneCount = 16;

package/dist/surface.d.ts

@@ -0,0 +1,30 @@
+import type { ComponentPropsWithoutRef } from "react";
+import { type ColorLevel, type ScaleLevel } from "@phreshos/core";
+/** A Theme-derived treatment or direct CSS color. */
+export type SurfaceColor = ColorLevel | (string & {});
+/** Native div properties plus controls for the locally owned material. */
+export type SurfaceProps = Omit<ComponentPropsWithoutRef<"div">, "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 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;
+}>;
+/** Contains content above one independent pure-SVG Surface material. */
+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 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;
+}> & import("react").RefAttributes<HTMLDivElement>>;

package/dist/surface.js

@@ -0,0 +1,68 @@
+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 { 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 theme = useTheme();
+    const element = useRef(null);
+    const ref = 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)`
+    };
+    useLayoutEffect(() => {
+        const surface = element.current;
+        if (surface)
+            return prepareSurfaceLayout(surface);
+    });
+    return _jsxs("div", { ...properties, ref: ref, style: {
+            borderRadius: theme.radius,
+            color: theme.foreground,
+            ...blur,
+            ...style
+        }, children: [_jsx(SurfaceMaterial, { animation: resolvedAnimation, color: resolvedColor, grain: resolvedGrain, opacity: resolvedOpacity }), children] });
+});
+function resolveColor(value, base) {
+    if (value === undefined)
+        return base;
+    return isColorLevel(value) ? deriveColor(base)[value] : value;
+}
+function isColorLevel(value) {
+    return value === "subtle" || value === "soft" || value === "base" || value === "strong" || value === "intense";
+}
+function resolveScale(value, base, range) {
+    const resolved = isScaleLevel(value) ? scale(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);
+    const position = element.style.position;
+    const isolation = element.style.isolation;
+    const ownsPosition = computed?.position === "static";
+    const ownsIsolation = computed?.isolation !== "isolate";
+    if (ownsPosition)
+        element.style.position = "relative";
+    if (ownsIsolation)
+        element.style.isolation = "isolate";
+    return () => {
+        if (ownsPosition && element.style.position === "relative")
+            element.style.position = position;
+        if (ownsIsolation && element.style.isolation === "isolate")
+            element.style.isolation = isolation;
+    };
+}

package/dist/theme-provider.d.ts

@@ -3,23 +3,9 @@ import type { ThemeProperties } from "@phreshos/core";
 /** Provides the nearest Theme value to one React subtree. */
 export declare function ThemeProvider({ children, theme }: ThemeProviderProps): import("react").JSX.Element;
 /** Returns the complete snapshot supplied by the nearest ThemeProvider. */
-export declare function useTheme(): Readonly<{
-    background: string;
-    foreground: string;
-    accent: string;
-    spacing: number;
-    radius: number;
-    glass: import("@phreshos/core").ThemeGlass;
-}>;
+export declare function useTheme(): ThemeProperties;
 /** Internal optional read used by primitives with both raw and themed values. */
-export declare function useThemeIfAvailable(): Readonly<{
-    background: string;
-    foreground: string;
-    accent: string;
-    spacing: number;
-    radius: number;
-    glass: import("@phreshos/core").ThemeGlass;
-}> | null;
+export declare function useThemeIfAvailable(): ThemeProperties | null;
 /** Properties accepted by ThemeProvider. */
 export interface ThemeProviderProps {
     /** Content that receives this Theme instead of any outer Theme. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/react-ui",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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.4",
+    "@phreshos/core": "^0.1.7",
     "react": "^19.2.0",
     "react-dom": "^19.2.0"
   },
@@ -61,7 +61,7 @@
   },
   "devDependencies": {
     "@base-ui/react": "^1.7.0",
-    "@phreshos/core": "^0.1.4",
+    "@phreshos/core": "^0.1.7",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.0",
     "@testing-library/user-event": "^14.6.1",