@phreshos/react-ui 0.1.11 → 0.1.13

package/README.md

@@ -27,21 +27,29 @@ collapses Appearance into a second retained object.
 An application using the Client SDK composes the packages explicitly:
 
 ```tsx
-import { useDocumentColorScheme } from "@phreshos/react-ui"
+import { useDesktopPreferences, useSystemAppearance } from "@phreshos/react"
 
 const appearance = useSystemAppearance()
 const { theme } = useDesktopPreferences()
-useDocumentColorScheme(theme)
 
 return <AppearanceProvider appearance={appearance} theme={theme}>
   {children}
 </AppearanceProvider>
 ```
 
-`useDocumentColorScheme(theme)` explicitly synchronizes the document root's
-native `color-scheme` and restores its previous value on unmount. Call it once
-at the application root; reading Theme or Desktop preferences has no document
-side effect.
+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
 
@@ -57,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
 
@@ -73,6 +83,5 @@ Appearance; elevation stays with the surrounding layout.
 - `Flex` and `Grid`: small layout primitives that preserve native props.
 - `AppearanceProvider`, `useAppearance`, `useTheme`, `useResolveTheme`:
   environment-neutral appearance composition.
-- `useDocumentColorScheme`: explicit browser document integration.
 - `useScale`, `useColor`, `resolveSpacing`, `resolveRadius`: explicit visual
   derivation helpers.

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

@@ -5,7 +5,6 @@
  * behavior contract has been established by the package's tests.
  */
 export { AppearanceProvider, useAppearance, useResolveTheme, useTheme, type AppearanceProviderProps } from "./appearance-provider.js";
-export { default as useDocumentColorScheme } from "./document-color-scheme.js";
 export { Flex, type FlexProps } from "./flex.js";
 export { Grid, type GridProps } from "./grid.js";
 export { Surface, type SurfaceProps } from "./surface.js";

package/dist/main.js

@@ -5,7 +5,6 @@
  * behavior contract has been established by the package's tests.
  */
 export { AppearanceProvider, useAppearance, useResolveTheme, useTheme } from "./appearance-provider.js";
-export { default as useDocumentColorScheme } from "./document-color-scheme.js";
 export { Flex } from "./flex.js";
 export { Grid } from "./grid.js";
 export { Surface } from "./surface.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.js

@@ -36,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: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/react-ui",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "React components for coherent PhreshOS Program interfaces.",
   "type": "module",
   "sideEffects": false,
@@ -61,7 +61,7 @@
   },
   "devDependencies": {
     "@base-ui/react": "^1.7.0",
-    "@phreshos/core": "^0.1.22",
+    "@phreshos/core": "^0.1.28",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.0",
     "@testing-library/user-event": "^14.6.1",

package/dist/document-color-scheme.d.ts

@@ -1,3 +0,0 @@
-import type { Theme } from "@phreshos/core";
-/** Keeps the document root's native color scheme aligned with one effective Theme. */
-export default function useDocumentColorScheme(theme: Theme): void;

package/dist/document-color-scheme.js

@@ -1,10 +0,0 @@
-import { useLayoutEffect } from "react";
-/** Keeps the document root's native color scheme aligned with one effective Theme. */
-export default function useDocumentColorScheme(theme) {
-    useLayoutEffect(() => {
-        const root = document.documentElement;
-        const previous = root.style.colorScheme;
-        root.style.colorScheme = theme;
-        return () => { root.style.colorScheme = previous; };
-    }, [theme]);
-}