@phreshos/react-ui 0.1.7 → 0.1.8

package/README.md

@@ -68,11 +68,11 @@ Theme's concrete default spacing:
 <Grid gap="large">...</Grid>
 ```
 
-Structures that own native spacing pass the explicit Theme value to the
-general React SDK hook instead:
+Structures that own native spacing pass the explicit Theme value to React UI's
+general derivation hook:
 
 ```tsx
-import { useScale } from "@phreshos/react"
+import { useScale } from "@phreshos/react-ui"
 
 const spacing = useScale(theme.spacing)
 
@@ -94,13 +94,13 @@ texture:
 </Surface>
 
 <Surface color="strong" grain="large">...</Surface>
-<Surface color="#101114" grain={0.2} grainAnimation={8} backdrop={4} opacity={0.9}>...</Surface>
+<Surface color="#101114" grain={0.2} 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`,
-`grainAmount`, `grainAnimation`, `backdrop`, `opacity`, `distortion`, `waves`,
+`grainAmount`, `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. Grain intensity
@@ -118,14 +118,14 @@ 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`
+React UI derives the fixed `subtle`, `soft`, `base`, `strong`, and `intense`
 treatments from any supplied color, preserving the value exactly at `base`.
-`useColor(value)` in the React SDK memoizes that calculation without
-implicitly choosing a Theme property. CSS performs the nearby mixing in
-OKLCH, so React UI does not own or persist a parallel palette of its own:
+`useColor(value)` memoizes that calculation without implicitly choosing a
+Theme property. CSS performs the nearby mixing in OKLCH, and the System retains
+only the concrete Theme color:
 
 ```tsx
-import { useColor } from "@phreshos/react"
+import { useColor } from "@phreshos/react-ui"
 
 const colors = useColor(theme.accent)
 
@@ -143,10 +143,10 @@ overrides:
 ```
 
 Structures whose native element owns the shape derive from the explicit
-radius value through the same general React SDK hook:
+radius value through the same React UI hook:
 
 ```tsx
-import { useScale } from "@phreshos/react"
+import { useScale } from "@phreshos/react-ui"
 
 const radius = useScale(theme.radius)
 

package/dist/button.d.ts

@@ -1,6 +1,6 @@
 import type { CSSProperties, ReactNode } from "react";
 import type { ButtonProps as AriaButtonProps } from "react-aria-components";
-import { type ScaleLevel } from "@phreshos/core";
+import { type ScaleLevel } from "./scale.js";
 import { type RadiusProps } from "./radius.js";
 type NativeButtonProps = Omit<AriaButtonProps, "children" | "className" | "isDisabled" | "isPending" | "onClick" | "onPress" | "style">;
 /** Properties accepted by the shared interactive button. */

package/dist/button.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { forwardRef } from "react";
 import { Button as AriaButton } from "react-aria-components";
-import { scale } from "@phreshos/core";
+import { scale } from "./scale.js";
 import { resolveRadius } from "./radius.js";
 import { useTheme } from "./theme-provider.js";
 /** A Theme-aware action with normalized pointer and keyboard behavior. */

package/dist/color.d.ts

@@ -1,2 +1,10 @@
+/** A visual treatment derived from one concrete CSS color. */
+export type ColorLevel = "subtle" | "soft" | "base" | "strong" | "intense";
+/** Every visual treatment derived from one concrete CSS color. */
+export type ColorScale = Readonly<Record<ColorLevel, string>>;
+/** Derives visual treatments while preserving the concrete value at `base`. */
+export declare function color(value: string): ColorScale;
+/** Returns the complete visual treatments derived from one concrete color. */
+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;

package/dist/color.js

@@ -1,3 +1,18 @@
+import { useMemo } from "react";
+/** Derives visual treatments while preserving the concrete value at `base`. */
+export function color(value) {
+    return Object.freeze({
+        subtle: `color-mix(in oklch, ${value} 25%, white)`,
+        soft: `color-mix(in oklch, ${value} 60%, white)`,
+        base: value,
+        strong: `color-mix(in oklch, ${value} 82%, black)`,
+        intense: `color-mix(in oklch, ${value} 68%, black)`
+    });
+}
+/** Returns the complete visual treatments derived from one concrete color. */
+export function useColor(value) {
+    return useMemo(() => color(value), [value]);
+}
 /** Applies material opacity without restricting the source CSS color syntax. */
 export function colorOpacity(value, opacity) {
     const percentage = Math.round(opacity * 10_000) / 100;

package/dist/main.d.ts

@@ -12,3 +12,5 @@ export { Button, type ButtonProps } from "./button.js";
 export type { LayoutAlignment, LayoutGap, LayoutJustification } from "./layout.js";
 export { resolveRadius, type Radius, type RadiusProps } from "./radius.js";
 export { resolveSpacing, type Spacing } from "./spacing.js";
+export { useColor, type ColorLevel, type ColorScale } from "./color.js";
+export { useScale, type NumericScale, type ScaleLevel } from "./scale.js";

package/dist/main.js

@@ -11,3 +11,5 @@ export { Surface } from "./surface.js";
 export { Button } from "./button.js";
 export { resolveRadius } from "./radius.js";
 export { resolveSpacing } from "./spacing.js";
+export { useColor } from "./color.js";
+export { useScale } from "./scale.js";

package/dist/radius.d.ts

@@ -1,6 +1,6 @@
 import type { CSSProperties } from "react";
 import type { Shapeable, ThemeProperties } from "@phreshos/core";
-import { type ScaleLevel } from "@phreshos/core";
+import { type ScaleLevel } from "./scale.js";
 /** A Theme-derived level, pixel value, or explicit CSS corner radius. */
 export type Radius = ScaleLevel | number | (string & {});
 /** Shared semantic corner-radius capability for React UI components. */

package/dist/radius.js

@@ -1,4 +1,4 @@
-import { isScaleLevel, scale } from "@phreshos/core";
+import { isScaleLevel, scale } from "./scale.js";
 /** Resolves a Radius while preserving explicit CSS and pixel values. */
 export function resolveRadius(value, theme) {
     if (!isScaleLevel(value))

package/dist/scale.d.ts

@@ -0,0 +1,14 @@
+/** A visual level derived around one concrete Theme value. */
+export type ScaleLevel = "xsmall" | "small" | "medium" | "large" | "xlarge";
+/** Every visual level derived around one concrete Theme value. */
+export type NumericScale = Readonly<Record<ScaleLevel, number>>;
+/** Returns whether a value names a React UI visual level. */
+export declare function isScaleLevel(value: unknown): value is ScaleLevel;
+/** Derives one visual level from one concrete value. */
+export declare function scale(value: number, level: ScaleLevel): number;
+/** Derives every visual level from one concrete value. */
+export declare function numericScale(value: number): NumericScale;
+/** Derives a multiplier while preserving its neutral value of one. */
+export declare function scaleMultiplier(value: number, level: ScaleLevel): number;
+/** Returns every visual level derived from one concrete Theme value. */
+export declare function useScale(value: number): NumericScale;

package/dist/scale.js

@@ -0,0 +1,34 @@
+import { useMemo } from "react";
+const factors = Object.freeze({
+    xsmall: 0.25,
+    small: 0.5,
+    medium: 1,
+    large: 1.5,
+    xlarge: 2
+});
+/** Returns whether a value names a React UI visual level. */
+export function isScaleLevel(value) {
+    return value === "xsmall" || value === "small" || value === "medium" || value === "large" || value === "xlarge";
+}
+/** Derives one visual level from one concrete value. */
+export function scale(value, level) {
+    return value * factors[level];
+}
+/** Derives every visual level from one concrete value. */
+export function numericScale(value) {
+    return Object.freeze({
+        xsmall: scale(value, "xsmall"),
+        small: scale(value, "small"),
+        medium: scale(value, "medium"),
+        large: scale(value, "large"),
+        xlarge: scale(value, "xlarge")
+    });
+}
+/** Derives a multiplier while preserving its neutral value of one. */
+export function scaleMultiplier(value, level) {
+    return 1 + (value - 1) * factors[level];
+}
+/** Returns every visual level derived from one concrete Theme value. */
+export function useScale(value) {
+    return useMemo(() => numericScale(value), [value]);
+}

package/dist/spacing.d.ts

@@ -1,6 +1,6 @@
 import type { CSSProperties } from "react";
 import type { ThemeProperties } from "@phreshos/core";
-import { type ScaleLevel } from "@phreshos/core";
+import { type ScaleLevel } from "./scale.js";
 /** A Theme-derived level, pixel value, or explicit CSS spacing value. */
 export type Spacing = ScaleLevel | number | (string & {});
 /** Resolves spacing while preserving explicit CSS and pixel values. */

package/dist/spacing.js

@@ -1,4 +1,4 @@
-import { isScaleLevel, scale } from "@phreshos/core";
+import { isScaleLevel, scale } from "./scale.js";
 export function resolveSpacing(value, theme) {
     if (!isScaleLevel(value))
         return value;

package/dist/surface-material.d.ts

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

package/dist/surface-material.js

@@ -1,27 +1,15 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Fragment, useEffect, useMemo, useRef } from "react";
+import { Fragment, useMemo } from "react";
 /** The locally owned SVG paint layer inside one Surface. */
-export function SurfaceMaterial({ color, distortion, grain, grainAmount, grainAnimation, identity, opacity, ripples, waves }) {
+export function SurfaceMaterial({ color, distortion, grain, grainAmount, identity, opacity, ripples, waves }) {
     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, 0, grainAmount) : [], [grainAmount, hasGrain, seed]);
-    const svg = useRef(null);
-    const paths = useRef([]);
-    useEffect(() => {
-        paths.current.forEach((path, tone) => path?.setAttribute("d", initial[tone] ?? ""));
-        if (grainAnimation === 0 || !hasGrain || !svg.current)
-            return;
-        const paint = (frame) => {
-            const values = grainPaths(seed, frame, grainAmount);
-            paths.current.forEach((path, tone) => path?.setAttribute("d", values[tone] ?? ""));
-        };
-        return animate(svg.current, grainAnimation, paint);
-    }, [grainAnimation, grainAmount, hasGrain, initial, seed]);
+    const initial = useMemo(() => hasGrain ? grainPaths(seed, grainAmount) : [], [grainAmount, hasGrain, seed]);
     if (!hasPaint && !hasDistortion)
         return null;
-    return _jsxs("svg", { ref: svg, "data-surface-material": "", "aria-hidden": "true", focusable: "false", style: {
+    return _jsxs("svg", { "data-surface-material": "", "aria-hidden": "true", focusable: "false", style: {
             position: "absolute",
             zIndex: -1,
             inset: 0,
@@ -33,7 +21,7 @@ export function SurfaceMaterial({ color, distortion, grain, grainAmount, grainAn
             boxSizing: "border-box",
             opacity,
             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", { 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" })] });
+        }, 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 && _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 = [
@@ -58,72 +46,17 @@ function grainTone(color, tone, intensity) {
     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();
-    #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, amount) {
+function grainPaths(seed, amount) {
     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 presence = shaderHash(pointX + frameX + 71.9, pointY + frameY + 13.7);
+            const presence = shaderHash(pointX + 71.9, pointY + 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 fine = shaderHash(Math.floor(pointX * 1.18), Math.floor(pointY * 1.18));
+            const clustered = shaderHash(Math.floor(pointX * 0.47) + 31.7, Math.floor(pointY * 0.47) + 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`);

package/dist/surface.d.ts

@@ -1,5 +1,6 @@
 import type { ComponentPropsWithoutRef } from "react";
-import { type ColorLevel, type ScaleLevel } from "@phreshos/core";
+import { type ColorLevel } from "./color.js";
+import { type ScaleLevel } from "./scale.js";
 /** A Theme-derived treatment or direct CSS color. */
 export type SurfaceColor = ColorLevel | (string & {});
 /** Native div properties plus controls for the locally owned material. */
@@ -10,8 +11,6 @@ export type SurfaceProps = Omit<ComponentPropsWithoutRef<"div">, "color" | "opac
     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. */
-    grainAnimation?: 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. */
@@ -35,8 +34,6 @@ export declare const Surface: import("react").ForwardRefExoticComponent<Omit<Omi
     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. */
-    grainAnimation?: 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. */

package/dist/surface.js

@@ -1,6 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { forwardRef, useCallback, useId, useLayoutEffect, useRef } from "react";
-import { color as deriveColor, isScaleLevel, scale, scaleMultiplier, themeLimits } from "@phreshos/core";
+import { themeLimits } from "@phreshos/core";
+import { color as deriveColor } from "./color.js";
+import { isScaleLevel, scale, scaleMultiplier } from "./scale.js";
 import { SurfaceMaterial } from "./surface-material.js";
 import { useTheme } from "./theme-provider.js";
 const layerStyle = {
@@ -10,7 +12,7 @@ const layerStyle = {
     pointerEvents: "none"
 };
 /** Contains content above locally owned Surface material layers. */
-export const Surface = forwardRef(function Surface({ backdrop, brightness, children, color, distortion, grain, grainAmount, grainAnimation, opacity, ripples, saturation, style, waves, ...properties }, forwardedRef) {
+export const Surface = forwardRef(function Surface({ 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);
@@ -21,7 +23,7 @@ export const Surface = forwardRef(function Surface({ backdrop, brightness, child
         else if (forwardedRef)
             forwardedRef.current = node;
     }, [forwardedRef]);
-    const resolved = resolveSurface({ backdrop, brightness, color, distortion, grain, grainAmount, grainAnimation, opacity, ripples, saturation, waves }, theme);
+    const resolved = resolveSurface({ backdrop, brightness, color, distortion, grain, grainAmount, opacity, ripples, saturation, waves }, theme);
     useLayoutEffect(() => {
         const surface = element.current;
         if (surface)
@@ -55,7 +57,6 @@ function BackdropLayer({ filter, name, zIndex }) {
 }
 function resolveSurface(values, theme) {
     const material = {
-        grainAnimation: resolveScale(values.grainAnimation, theme.surface.grainAnimation, themeLimits.surface.grainAnimation),
         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),

package/package.json

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