@phreshos/react-ui 0.1.10 → 0.1.11

package/README.md

@@ -27,14 +27,22 @@ collapses Appearance into a second retained object.
 An application using the Client SDK composes the packages explicitly:
 
 ```tsx
+import { useDocumentColorScheme } from "@phreshos/react-ui"
+
 const appearance = useSystemAppearance()
-const theme = useSystemTheme()
+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.
+
 ## Levels
 
 `useScale(value)` and `useColor(value)` derive semantic UI levels from one
@@ -65,5 +73,6 @@ 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/document-color-scheme.d.ts

@@ -0,0 +1,3 @@
+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

@@ -0,0 +1,10 @@
+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]);
+}

package/dist/main.d.ts

@@ -5,9 +5,10 @@
  * 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 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/main.js

@@ -5,6 +5,7 @@
  * 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.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)
@@ -61,7 +60,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 +82,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.11",
   "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",