@phreshos/react 0.1.7 → 0.1.9

package/README.md

@@ -19,8 +19,8 @@ It provides two kinds of adapter:
 - `CurrentProvider` resolves exactly the current values named by its required
   `provide` prop, then exposes them synchronously through `useProgram()`,
   `useProcess()`, and `useParent()`.
-- `HostProvider` subscribes before reading exactly the host values named by its
-  required `provide` prop. `useHostTheme()`, `useDesktopSize()`, and
+- `SystemProvider` subscribes before reading exactly the system values named by its
+  required `provide` prop. `useSystemAppearance()`, `useSystemTheme()`, `useDesktopSize()`, and
   `usePointerPosition()` expose those values synchronously after resolution.
 - `useSubscribe()` and `useObserve()` own persistent ordinary-event
   registrations for one mounted React consumer.
@@ -31,9 +31,6 @@ It provides two kinds of adapter:
 - `useObserveAsks()` adapts an Endpoint traffic surface's question observation,
   while `useObserveAnswers()` adapts a Server traffic surface's answer
   observation.
-- `useScale(value)` and `useColor(value)` memoize the complete derived scale
-  around the explicit number or CSS color supplied by the component. They do
-  not read a Theme or choose a source value implicitly.
 
 Window needs no React resolution: `current.window` is already a synchronous,
 silent capability object. `CurrentProvider` therefore has no `window` selection
@@ -75,47 +72,41 @@ mount its `useWindowState()` child only while `clientExists` is true. Calling
 the Window hook while the Client is absent lets the existing Window reads
 reject normally.
 
-```tsx
-const theme = useHostTheme()
-const spacing = useScale(theme.spacing)
-const radius = useScale(theme.radius)
-const accent = useColor(theme.accent)
-```
-
 The ordinary-event and traffic hooks retain the latest value returned by their projector.
 `useSubscribe()` may omit that callback; its default projector is
 `message => message`, so the hook retains the latest message unchanged.
 
 ```tsx
-import { host } from "@phreshos/client"
+import { system } from "@phreshos/client"
 import { useSubscribe } from "@phreshos/react"
 
-const desktop = useSubscribe(host.desktop, "resize")
+const desktop = useSubscribe(system.desktop, "resize")
 ```
 
-Host reads are asynchronous while subscriptions are live-only. `HostProvider`
+System reads are asynchronous while subscriptions are live-only. `SystemProvider`
 subscribes before requesting each selected snapshot and prevents an older read
 from overwriting a newer event:
 
 ```tsx
-import { HostProvider, useDesktopSize, useHostTheme } from "@phreshos/react"
+import { SystemProvider, useDesktopSize, useSystemAppearance, useSystemTheme } from "@phreshos/react"
 
 function Content() {
-  const theme = useHostTheme()
+  const theme = useSystemTheme()
+  const appearance = useSystemAppearance()
   const desktop = useDesktopSize()
 
-  return <p style={{ color: theme.foreground }}>{desktop.width} × {desktop.height}</p>
+  return <p style={{ color: appearance.foreground[theme] }}>{desktop.width} × {desktop.height}</p>
 }
 
 function App() {
-  return <HostProvider provide={["theme", "desktopSize"]} fallback={<p>Loading…</p>}>
+  return <SystemProvider provide={["appearance", "theme", "desktopSize"]} fallback={<p>Loading…</p>}>
     <Content />
-  </HostProvider>
+  </SystemProvider>
 }
 ```
 
 The selection is required and non-empty. Nothing is read or subscribed merely
-because either SDK was imported, and an unselected host value never enters the
+because either SDK was imported, and an unselected system value never enters the
 Client. `pointerPosition` is permission-guarded: selecting it does not request
 permission, and resolution fails unless the Program already holds `pointer`.
 The provider renders its fallback until every selected value resolves.
@@ -147,7 +138,7 @@ export default function App() {
 }
 ```
 
-Using a current or host hook outside its provider, or without selecting its
+Using a current or system hook outside its provider, or without selecting its
 value, throws a configuration error. Neither provider supplies an implicit
 "everything" selection, so adding a future capability cannot make it enter an
 existing application.

package/dist/live-snapshot.js

@@ -14,7 +14,7 @@ export default class LiveSnapshot {
     }
     snapshot = () => {
         if (this.value === unavailable)
-            throw new Error("The requested host value is not ready");
+            throw new Error("The requested system value is not ready");
         return this.value;
     };
     subscribe = (listener) => {

package/dist/main.d.ts

@@ -1,9 +1,7 @@
 export { default as CurrentProvider, useParent, useProcess, useProgram, type CurrentProvision, type CurrentProvisionName, type CurrentProviderProperties } from "./current-provider.js";
-export { default as HostProvider, usePointerPosition, useDesktopSize, useHostTheme, type HostProvision, type HostProvisionName, type HostProviderProperties } from "./host-provider.js";
+export { default as SystemProvider, usePointerPosition, useDesktopSize, useSystemAppearance, useSystemTheme, type SystemProvision, type SystemProvisionName, type SystemProviderProperties } from "./system-provider.js";
 export { default as useSubscribe } from "./use-subscribe.js";
 export { default as useObserve } from "./use-observe.js";
-export { default as useScale } from "./use-scale.js";
-export { default as useColor } from "./use-color.js";
 export { default as useProgramState, type ProgramState } from "./use-program-state.js";
 export { default as useProcessState, type ProcessState } from "./use-process-state.js";
 export { default as useServiceState, type ServiceState } from "./use-service-state.js";

package/dist/main.js

@@ -1,9 +1,7 @@
 export { default as CurrentProvider, useParent, useProcess, useProgram } from "./current-provider.js";
-export { default as HostProvider, usePointerPosition, useDesktopSize, useHostTheme } from "./host-provider.js";
+export { default as SystemProvider, usePointerPosition, useDesktopSize, useSystemAppearance, useSystemTheme } from "./system-provider.js";
 export { default as useSubscribe } from "./use-subscribe.js";
 export { default as useObserve } from "./use-observe.js";
-export { default as useScale } from "./use-scale.js";
-export { default as useColor } from "./use-color.js";
 export { default as useProgramState } from "./use-program-state.js";
 export { default as useProcessState } from "./use-process-state.js";
 export { default as useServiceState } from "./use-service-state.js";

package/dist/system-provider.d.ts

@@ -0,0 +1,30 @@
+import { type ReactNode } from "react";
+import { type Appearance, type DesktopSize, type PointerPosition, type Theme } from "@phreshos/client";
+declare const provisionNames: readonly ["appearance", "theme", "desktopSize", "pointerPosition"];
+/** Requests and follows only the system values explicitly selected by the program. */
+export default function SystemProvider(properties: SystemProviderProperties): import("react").FunctionComponentElement<SelectedSystemProviderProperties>;
+/** Returns the complete unresolved Appearance and follows authoritative updates. */
+export declare function useSystemAppearance(): Appearance;
+/** Returns the effective local Desktop Theme and follows future changes. */
+export declare function useSystemTheme(): Theme;
+/** Returns the selected desktop size and follows future resize events. */
+export declare function useDesktopSize(): DesktopSize;
+/** Returns the selected Pointer position and follows future move events. */
+export declare function usePointerPosition(): PointerPosition | null;
+/** Values that SystemProvider can request and follow. */
+export type SystemProvisionName = typeof provisionNames[number];
+/** Required non-empty selection of system values. */
+export type SystemProvision = readonly [SystemProvisionName, ...SystemProvisionName[]];
+/** Properties accepted by SystemProvider. */
+export interface SystemProviderProperties {
+    /** Content rendered after every selected system value has resolved. */
+    readonly children: ReactNode;
+    /** Content rendered while selected system values resolve. */
+    readonly fallback: ReactNode;
+    /** Exact system values requested and followed for mounted descendants. */
+    readonly provide: SystemProvision;
+}
+type SelectedSystemProviderProperties = SystemProviderProperties & Readonly<{
+    selection: readonly SystemProvisionName[];
+}>;
+export {};

package/dist/{host-provider.js → system-provider.js}

@@ -1,16 +1,16 @@
 import { createContext, createElement, useContext, useEffect, useMemo, useState, useSyncExternalStore } from "react";
-import { host } from "@phreshos/client";
+import { system } from "@phreshos/client";
 import LiveSnapshot from "./live-snapshot.js";
-const provisionNames = ["theme", "desktopSize", "pointerPosition"];
-const HostContext = createContext(null);
-/** Requests and follows only the host values explicitly selected by the program. */
-export default function HostProvider(properties) {
+const provisionNames = ["appearance", "theme", "desktopSize", "pointerPosition"];
+const SystemContext = createContext(null);
+/** Requests and follows only the system values explicitly selected by the program. */
+export default function SystemProvider(properties) {
     const normalized = normalizeProvision(properties.provide);
     const selectionKey = normalized.join("\0");
     const selection = useMemo(() => normalized, [selectionKey]);
-    return createElement(SelectedHostProvider, { ...properties, key: selectionKey, selection });
+    return createElement(SelectedSystemProvider, { ...properties, key: selectionKey, selection });
 }
-function SelectedHostProvider({ children, fallback, selection }) {
+function SelectedSystemProvider({ children, fallback, selection }) {
     const stores = useMemo(() => createStores(selection), [selection]);
     const [resolution, setResolution] = useState({ status: "pending" });
     useEffect(() => {
@@ -35,10 +35,14 @@ function SelectedHostProvider({ children, fallback, selection }) {
         return fallback;
     if (resolution.status === "error")
         throw resolution.error;
-    return createElement(HostContext.Provider, { value: { provided: new Set(selection), stores } }, children);
+    return createElement(SystemContext.Provider, { value: { provided: new Set(selection), stores } }, children);
 }
-/** Returns the selected Theme snapshot and follows future change events. */
-export function useHostTheme() {
+/** Returns the complete unresolved Appearance and follows authoritative updates. */
+export function useSystemAppearance() {
+    return useProvided("appearance");
+}
+/** Returns the effective local Desktop Theme and follows future changes. */
+export function useSystemTheme() {
     return useProvided("theme");
 }
 /** Returns the selected desktop size and follows future resize events. */
@@ -50,11 +54,11 @@ export function usePointerPosition() {
     return useProvided("pointerPosition");
 }
 function useProvided(name) {
-    const context = useContext(HostContext);
+    const context = useContext(SystemContext);
     if (!context)
-        throw new Error(`${hookNames[name]} must be used inside HostProvider`);
+        throw new Error(`${hookNames[name]} must be used inside SystemProvider`);
     if (!context.provided.has(name))
-        throw new Error(`${hookNames[name]} requires "${name}" in HostProvider's provide prop`);
+        throw new Error(`${hookNames[name]} requires "${name}" in SystemProvider's provide prop`);
     const store = context.stores[name];
     return useSyncExternalStore(store.subscribe, store.snapshot, store.snapshot);
 }
@@ -62,14 +66,17 @@ function createStores(selection) {
     const stores = {};
     for (const name of selection) {
         switch (name) {
+            case "appearance":
+                stores.appearance = new LiveSnapshot(() => system.appearance.snapshot(), subscriber => system.appearance.subscribe("change", subscriber));
+                break;
             case "theme":
-                stores.theme = new LiveSnapshot(() => host.theme.snapshot(), subscriber => host.theme.subscribe("change", subscriber));
+                stores.theme = new LiveSnapshot(() => system.theme.snapshot(), subscriber => system.theme.subscribe("change", subscriber));
                 break;
             case "desktopSize":
-                stores.desktopSize = new LiveSnapshot(() => host.desktop.size(), subscriber => host.desktop.subscribe("resize", subscriber));
+                stores.desktopSize = new LiveSnapshot(() => system.desktop.size(), subscriber => system.desktop.subscribe("resize", subscriber));
                 break;
             case "pointerPosition":
-                stores.pointerPosition = new LiveSnapshot(() => host.pointer.position(), subscriber => host.pointer.subscribe("move", subscriber));
+                stores.pointerPosition = new LiveSnapshot(() => system.pointer.position(), subscriber => system.pointer.subscribe("move", subscriber));
                 break;
         }
     }
@@ -77,19 +84,20 @@ function createStores(selection) {
 }
 function normalizeProvision(provide) {
     if (!Array.isArray(provide) || provide.length === 0)
-        throw new Error("HostProvider's provide prop must select at least one host value");
+        throw new Error("SystemProvider's provide prop must select at least one system value");
     const selected = new Set();
     for (const name of provide) {
         if (!provisionNames.includes(name))
-            throw new Error(`HostProvider cannot provide "${String(name)}"`);
+            throw new Error(`SystemProvider cannot provide "${String(name)}"`);
         if (selected.has(name))
-            throw new Error(`HostProvider's provide prop selects "${name}" more than once`);
+            throw new Error(`SystemProvider's provide prop selects "${name}" more than once`);
         selected.add(name);
     }
     return [...selected];
 }
 const hookNames = {
-    theme: "useHostTheme",
+    appearance: "useSystemAppearance",
+    theme: "useSystemTheme",
     desktopSize: "useDesktopSize",
     pointerPosition: "usePointerPosition"
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/react",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "React adapters for the Client SDK.",
   "type": "module",
   "main": "dist/main.js",
@@ -47,13 +47,13 @@
     "prepack": "node --run test && node --run build"
   },
   "peerDependencies": {
-    "@phreshos/client": "^0.1.13",
-    "@phreshos/core": "^0.1.9",
+    "@phreshos/client": "^0.1.20",
+    "@phreshos/core": "^0.1.17",
     "react": "^19.2.0"
   },
   "devDependencies": {
-    "@phreshos/client": "^0.1.13",
-    "@phreshos/core": "^0.1.9",
+    "@phreshos/client": "^0.1.20",
+    "@phreshos/core": "^0.1.17",
     "@testing-library/react": "^16.3.0",
     "@types/react": "^19.2.18",
     "@types/react-dom": "^19.2.4",

package/dist/host-provider.d.ts

@@ -1,28 +0,0 @@
-import { type ReactNode } from "react";
-import { type DesktopSize, type PointerPosition, type ThemeProperties } from "@phreshos/client";
-declare const provisionNames: readonly ["theme", "desktopSize", "pointerPosition"];
-/** Requests and follows only the host values explicitly selected by the program. */
-export default function HostProvider(properties: HostProviderProperties): import("react").FunctionComponentElement<SelectedHostProviderProperties>;
-/** Returns the selected Theme snapshot and follows future change events. */
-export declare function useHostTheme(): Readonly<ThemeProperties>;
-/** Returns the selected desktop size and follows future resize events. */
-export declare function useDesktopSize(): DesktopSize;
-/** Returns the selected Pointer position and follows future move events. */
-export declare function usePointerPosition(): PointerPosition | null;
-/** Values that HostProvider can request and follow. */
-export type HostProvisionName = typeof provisionNames[number];
-/** Required non-empty selection of host values. */
-export type HostProvision = readonly [HostProvisionName, ...HostProvisionName[]];
-/** Properties accepted by HostProvider. */
-export interface HostProviderProperties {
-    /** Content rendered after every selected host value has resolved. */
-    readonly children: ReactNode;
-    /** Content rendered while selected host values resolve. */
-    readonly fallback: ReactNode;
-    /** Exact host values requested and followed for mounted descendants. */
-    readonly provide: HostProvision;
-}
-type SelectedHostProviderProperties = HostProviderProperties & Readonly<{
-    selection: readonly HostProvisionName[];
-}>;
-export {};

package/dist/use-color.d.ts

@@ -1,3 +0,0 @@
-import { type ColorScale } from "@phreshos/core";
-/** Returns the complete color scale derived from one explicit CSS color. */
-export default function useColor(value: string): ColorScale;

package/dist/use-color.js

@@ -1,6 +0,0 @@
-import { useMemo } from "react";
-import { color } from "@phreshos/core";
-/** Returns the complete color scale derived from one explicit CSS color. */
-export default function useColor(value) {
-    return useMemo(() => color(value), [value]);
-}

package/dist/use-scale.d.ts

@@ -1,3 +0,0 @@
-import { type NumericScale } from "@phreshos/core";
-/** Returns the complete visual scale derived from one explicit numeric value. */
-export default function useScale(value: number): NumericScale;

package/dist/use-scale.js

@@ -1,6 +0,0 @@
-import { useMemo } from "react";
-import { numericScale } from "@phreshos/core";
-/** Returns the complete visual scale derived from one explicit numeric value. */
-export default function useScale(value) {
-    return useMemo(() => numericScale(value), [value]);
-}