@phreshos/react-ui 0.1.10 → 0.1.12

package/README.md

@@ -27,14 +27,30 @@ collapses Appearance into a second retained object.
 An application using the Client SDK composes the packages explicitly:
 
 ```tsx
+import { useDesktopPreferences, useSystemAppearance } from "@phreshos/react"
+
 const appearance = useSystemAppearance()
-const theme = useSystemTheme()
+const { theme } = useDesktopPreferences()
 
 return <AppearanceProvider appearance={appearance} theme={theme}>
   {children}
 </AppearanceProvider>
 ```
 
+Document color-scheme negotiation belongs to the System iframe and the Client
+HTML document, not to a visual component or React hook.
+
+`AppearanceProvider` also owns the native scrollbars in its document. It adds
+no rendered container: one document stylesheet styles a six-pixel rounded
+thumb from Appearance foreground and radius, leaves the track transparent, and
+gives its container five pixels of transparent padding. With a precise
+pointer, the thumb is transparent outside its scrollable area, uses foreground
+at 10% inside it, and rises to 20% directly under the pointer. Touch documents
+retain the 10% thumb. The standardized scrollbar API has no thumb-hover state,
+so its fallback stops at 10%. Standard and WebKit rules are mutually exclusive
+so the standard thin width cannot override the padded geometry. WebKit hover
+also invalidates the scrollbar style to ensure Safari repaints each state.
+
 ## Levels
 
 `useScale(value)` and `useColor(value)` derive semantic UI levels from one
@@ -49,14 +65,16 @@ radii require Appearance because their concrete source is `spacing` or
 ## Surface
 
 `Surface` is the shared visual material. It accepts native `div` properties
-plus local overrides for color, grain, grain amount, backdrop blur, opacity,
+plus local overrides for grain, grain amount, backdrop blur, opacity,
 distortion, waves, ripples, saturation, and brightness. Omitted controls derive
 from the resolved Appearance. A zero-valued optional effect is omitted from the
 rendered material so disabled work costs nothing.
 
-Each Surface owns its SVG material and border. Backdrop refraction and frost
-remain separate compositor layers. Radius and foreground resolve from
-Appearance; elevation stays with the surrounding layout.
+Each Surface returns one plain geometry and content container. Its existing SVG
+material paints both the fill and its material-derived border; no separate
+border element is rendered. Backdrop refraction and frost remain separate
+compositor layers. Radius and foreground resolve from Appearance; elevation
+stays with the surrounding layout.
 
 ## Components
 

package/dist/appearance-provider.js

@@ -1,11 +1,12 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { createContext, useContext } from "react";
+import DocumentScrollbars from "./document-scrollbars.js";
 const missing = Symbol("AppearanceProvider");
 const AppearanceContext = createContext(missing);
 const ThemeContext = createContext(missing);
 /** Provides unresolved Appearance and one effective Theme to a React subtree. */
 export function AppearanceProvider({ appearance, children, theme }) {
-    return _jsx(AppearanceContext.Provider, { value: appearance, children: _jsx(ThemeContext.Provider, { value: theme, children: children }) });
+    return _jsx(AppearanceContext.Provider, { value: appearance, children: _jsxs(ThemeContext.Provider, { value: theme, children: [_jsx(DocumentScrollbars, { appearance: appearance, theme: theme }), children] }) });
 }
 /** Returns the complete unresolved Appearance supplied by the nearest provider. */
 export function useAppearance() {

package/dist/document-scrollbars.d.ts

@@ -0,0 +1,6 @@
+import type { Appearance, Theme } from "@phreshos/core";
+/** Applies one Appearance to the complete owning document without rendering. */
+export default function DocumentScrollbars({ appearance, theme }: Readonly<{
+    appearance: Appearance;
+    theme: Theme;
+}>): null;

package/dist/document-scrollbars.js

@@ -0,0 +1,164 @@
+import { useInsertionEffect, useRef } from "react";
+import { colorOpacity } from "./color.js";
+const properties = {
+    thumb: "--phreshos-scrollbar-thumb",
+    thumbHover: "--phreshos-scrollbar-thumb-hover",
+    size: "--phreshos-scrollbar-size",
+    padding: "--phreshos-scrollbar-padding",
+    radius: "--phreshos-scrollbar-radius"
+};
+const stylesheet = `
+@supports not selector(::-webkit-scrollbar) {
+  * {
+    scrollbar-color: var(${properties.thumb}) transparent;
+    scrollbar-width: thin;
+  }
+
+  @media (hover: hover) and (pointer: fine) {
+    * {
+      scrollbar-color: transparent transparent;
+    }
+
+    *:hover {
+      scrollbar-color: var(${properties.thumb}) transparent;
+    }
+  }
+
+  @media (forced-colors: active) {
+    *,
+    *:hover {
+      scrollbar-color: auto;
+    }
+  }
+}
+
+@supports selector(::-webkit-scrollbar) {
+  *::-webkit-scrollbar {
+    width: var(${properties.size});
+    height: var(${properties.size});
+    background: transparent;
+  }
+
+  *::-webkit-scrollbar-track,
+  *::-webkit-scrollbar-corner {
+    background: transparent;
+  }
+
+  *::-webkit-scrollbar-button {
+    display: none;
+  }
+
+  *::-webkit-scrollbar-thumb {
+    border: var(${properties.padding}) solid transparent;
+    border-radius: var(${properties.radius});
+    background-color: var(${properties.thumb});
+    background-clip: padding-box;
+  }
+
+  @media (hover: hover) and (pointer: fine) {
+    *:hover {
+      --phreshos-scrollbar-repaint: ;
+    }
+
+    *::-webkit-scrollbar-thumb {
+      background-color: transparent;
+    }
+
+    *:hover::-webkit-scrollbar-thumb {
+      background-color: var(${properties.thumb});
+    }
+
+    *::-webkit-scrollbar-thumb:hover {
+      background-color: var(${properties.thumbHover});
+    }
+  }
+
+  @media (forced-colors: active) {
+    *::-webkit-scrollbar-thumb,
+    *:hover::-webkit-scrollbar-thumb,
+    *::-webkit-scrollbar-thumb:hover {
+      background-color: ButtonText;
+    }
+  }
+}
+`;
+const documents = new WeakMap();
+/** Applies one Appearance to the complete owning document without rendering. */
+export default function DocumentScrollbars({ appearance, theme }) {
+    const identity = useRef(Symbol("AppearanceProvider")).current;
+    const foreground = theme === "dark" ? appearance.foreground.dark : appearance.foreground.light;
+    const padding = 5;
+    const thumbSize = 6;
+    const size = thumbSize + padding * 2;
+    const values = {
+        thumb: colorOpacity(foreground, 0.1),
+        thumbHover: colorOpacity(foreground, 0.2),
+        size: `${size}px`,
+        padding: `${padding}px`,
+        radius: `${Math.min(appearance.radius.light, padding + thumbSize / 2)}px`
+    };
+    useInsertionEffect(function () {
+        if (typeof document === "undefined")
+            return;
+        return register(document, identity, values);
+    }, []);
+    useInsertionEffect(function () {
+        if (typeof document !== "undefined")
+            update(document, identity, values);
+    }, [values.thumb, values.thumbHover, values.size, values.padding, values.radius]);
+    return null;
+}
+function register(owner, identity, values) {
+    const state = documents.get(owner) ?? create(owner);
+    state.providers.set(identity, values);
+    apply(state);
+    return function () {
+        state.providers.delete(identity);
+        if (state.providers.size) {
+            apply(state);
+            return;
+        }
+        state.style.remove();
+        restore(state);
+        documents.delete(owner);
+    };
+}
+function update(owner, identity, values) {
+    const state = documents.get(owner);
+    if (!state?.providers.has(identity))
+        return;
+    state.providers.set(identity, values);
+    apply(state);
+}
+function create(owner) {
+    const root = owner.documentElement;
+    const style = owner.createElement("style");
+    const original = new Map(Object.values(properties).map(property => [property, {
+            value: root.style.getPropertyValue(property),
+            priority: root.style.getPropertyPriority(property)
+        }]));
+    style.dataset.phreshosScrollbars = "";
+    style.textContent = stylesheet;
+    owner.head.append(style);
+    const state = { root, style, original, providers: new Map() };
+    documents.set(owner, state);
+    return state;
+}
+function apply(state) {
+    const values = [...state.providers.values()].at(-1);
+    if (!values)
+        return;
+    state.root.style.setProperty(properties.thumb, values.thumb);
+    state.root.style.setProperty(properties.thumbHover, values.thumbHover);
+    state.root.style.setProperty(properties.size, values.size);
+    state.root.style.setProperty(properties.padding, values.padding);
+    state.root.style.setProperty(properties.radius, values.radius);
+}
+function restore(state) {
+    for (const [property, original] of state.original) {
+        if (original.value)
+            state.root.style.setProperty(property, original.value, original.priority);
+        else
+            state.root.style.removeProperty(property);
+    }
+}

package/dist/main.d.ts

@@ -7,7 +7,7 @@
 export { AppearanceProvider, useAppearance, useResolveTheme, useTheme, type AppearanceProviderProps } from "./appearance-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 { Surface, type SurfaceProps } from "./surface.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/surface-material.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Fragment, useMemo } from "react";
+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 }) {
     const seed = useMemo(() => seedFrom(identity), [identity]);
@@ -9,7 +10,7 @@ export function SurfaceMaterial({ color, distortion, grain, grainAmount, identit
     const initial = useMemo(() => hasGrain ? grainPaths(seed, grainAmount) : [], [grainAmount, hasGrain, seed]);
     if (!hasPaint && !hasDistortion)
         return null;
-    return _jsxs("svg", { "data-surface-material": "", "aria-hidden": "true", focusable: "false", style: {
+    return _jsxs("svg", { "data-surface-material": "", "data-surface-border": hasPaint ? "" : undefined, "aria-hidden": "true", focusable: "false", style: {
             position: "absolute",
             zIndex: -1,
             inset: 0,
@@ -18,10 +19,19 @@ export function SurfaceMaterial({ color, distortion, grain, grainAmount, identit
             height: "100%",
             overflow: "hidden",
             borderRadius: "inherit",
+            borderColor: edgeColor(color, opacity),
+            borderStyle: hasPaint ? "solid" : "none",
+            borderWidth: hasPaint ? 1 : 0,
             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", { "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 && _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" })] })] });
+}
+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 DistortionFilter({ distortion, identity, ripples, seed, waves }) {
     const fields = [

package/dist/surface.d.ts

@@ -1,12 +1,7 @@
 import type { ComponentPropsWithoutRef } from "react";
-import { type ColorLevel } from "./color.js";
 import { type ScaleLevel } from "./scale.js";
-/** An Appearance-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<{
-    /** Appearance-derived treatment or direct CSS material color. */
-    color?: SurfaceColor;
+export type SurfaceProps = Omit<ComponentPropsWithoutRef<"div">, "opacity"> & Readonly<{
     /** Appearance-derived level or direct grain intensity from zero to one. */
     grain?: ScaleLevel | number;
     /** Appearance-derived level or direct retained grain amount from zero to one. */
@@ -27,9 +22,7 @@ export type SurfaceProps = Omit<ComponentPropsWithoutRef<"div">, "color" | "opac
     brightness?: ScaleLevel | number;
 }>;
 /** 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">, "opacity" | "color"> & Readonly<{
-    /** Appearance-derived treatment or direct CSS material color. */
-    color?: SurfaceColor;
+export declare const Surface: import("react").ForwardRefExoticComponent<Omit<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, "opacity"> & Readonly<{
     /** Appearance-derived level or direct grain intensity from zero to one. */
     grain?: ScaleLevel | number;
     /** Appearance-derived level or direct retained grain amount from zero to one. */

package/dist/surface.js

@@ -1,7 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { forwardRef, useCallback, useId, useLayoutEffect, useRef } from "react";
 import { appearanceLimits } from "@phreshos/core";
-import { color as deriveColor } from "./color.js";
 import { isScaleLevel, scale, scaleMultiplier } from "./scale.js";
 import { SurfaceMaterial } from "./surface-material.js";
 import { useAppearance, useResolveTheme } from "./appearance-provider.js";
@@ -12,7 +11,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, opacity, ripples, saturation, style, waves, ...properties }, forwardedRef) {
+export const Surface = forwardRef(function Surface({ backdrop, brightness, children, distortion, grain, grainAmount, opacity, ripples, saturation, style, waves, ...properties }, forwardedRef) {
     const appearance = useAppearance();
     const background = useResolveTheme(appearance.background);
     const foreground = useResolveTheme(appearance.foreground);
@@ -27,7 +26,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, opacity, ripples, saturation, waves }, background, surface);
+    const resolved = resolveSurface({ backdrop, brightness, distortion, grain, grainAmount, opacity, ripples, saturation, waves }, background, surface);
     useLayoutEffect(() => {
         const surface = element.current;
         if (surface)
@@ -37,19 +36,8 @@ 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(SurfaceBorder, { color: resolved.material.color, opacity: resolveScale("large", resolved.material.opacity, appearanceLimits.surface.opacity) }), _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, ...resolved.material }), children] });
 });
-/** Draws one uniform inset edge from the same color as the Surface material. */
-function SurfaceBorder({ color, opacity }) {
-    const edge = `color-mix(in oklch, ${color} 94%, black)`;
-    return _jsx("div", { "data-surface-border": "", "aria-hidden": "true", style: {
-            ...layerStyle,
-            zIndex: 0,
-            boxSizing: "border-box",
-            boxShadow: `inset 0 0 0 1px ${edge}`,
-            opacity
-        } });
-}
 /** 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: {
@@ -61,7 +49,7 @@ function BackdropLayer({ filter, name, zIndex }) {
 }
 function resolveSurface(values, background, surface) {
     const material = {
-        color: resolveColor(values.color, background),
+        color: background,
         distortion: resolveScale(values.distortion, surface.distortion, appearanceLimits.surface.distortion),
         grain: resolveScale(values.grain, surface.grain, appearanceLimits.surface.grain),
         grainAmount: resolveScale(values.grainAmount, surface.grainAmount, appearanceLimits.surface.grainAmount),
@@ -83,14 +71,6 @@ function resolveSurface(values, background, surface) {
         refracts: material.distortion > 0 || material.waves > 0 || material.ripples > 0
     };
 }
-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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/react-ui",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "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.19",
+    "@phreshos/core": "^0.1.22",
     "react": "^19.2.0",
     "react-dom": "^19.2.0"
   },
@@ -61,7 +61,7 @@
   },
   "devDependencies": {
     "@base-ui/react": "^1.7.0",
-    "@phreshos/core": "^0.1.19",
+    "@phreshos/core": "^0.1.22",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.0",
     "@testing-library/user-event": "^14.6.1",