@phreshos/react-ui 0.1.31 → 0.1.32

package/dist/appearance.d.ts

@@ -1,6 +1,11 @@
-import { appearanceLimits, type Appearance as SystemAppearance, type AppearanceColor, type AppearanceColors, type AppearanceMaterial, type AppearanceRange, type AppearanceShadow, type AppearanceTransaction, type Easing, type ThemedValue } from "@phreshos/core";
+import { appearanceLimits, type Appearance as SystemAppearance, type AppearanceUpdate as SystemAppearanceUpdate, type AppearanceColor, type AppearanceColors, type AppearanceMaterial, type AppearanceRange, type AppearanceShadow, type AppearanceTransaction, type Easing, type ThemedValue } from "@phreshos/core";
 /** Complete visual input consumed by React UI. */
 export type Appearance = Pick<SystemAppearance, "colors" | "spacing" | "radius" | "shadow" | "material" | "transaction">;
+type AppearanceUpdateFields = Pick<SystemAppearanceUpdate, "colors" | "spacing" | "radius" | "shadow" | "material" | "transaction">;
+/** At least one partial visual field recursively merged with the nearest UIProvider. */
+export type AppearanceUpdate = {
+    [Field in keyof AppearanceUpdateFields]-?: Readonly<Required<Pick<AppearanceUpdateFields, Field>> & Omit<AppearanceUpdateFields, Field>>;
+}[keyof AppearanceUpdateFields];
 export { appearanceLimits, type AppearanceColor, type AppearanceColors, type AppearanceMaterial, type AppearanceRange, type AppearanceShadow, type AppearanceTransaction, type Easing, type ThemedValue };
 /** React UI's default visual input, derived from the System default. */
 export declare const defaultAppearance: Appearance;

package/dist/main.d.ts

@@ -4,9 +4,9 @@
  * Components enter this surface only after their implementation-independent
  * behavior contract has been established by the package's tests.
  */
-export { defaultAppearance, type Appearance, type AppearanceColor, type AppearanceColors, type AppearanceMaterial, type AppearanceShadow, type AppearanceTransaction, type Easing, type ThemedValue } from "./appearance.js";
+export { defaultAppearance, type Appearance, type AppearanceUpdate, type AppearanceColor, type AppearanceColors, type AppearanceMaterial, type AppearanceShadow, type AppearanceTransaction, type Easing, type ThemedValue } from "./appearance.js";
 export { UIProvider, useAppearance, useBrowserPreferences, useDirection, useDocumentDirection, usePreferences, useThemedValue, type UIProviderProps } from "./ui-provider.js";
-export type { Preferences, Theme } from "./preferences.js";
+export type { Preferences, PreferencesUpdate, Theme } from "./preferences.js";
 export type { Direction } from "./direction.js";
 export { Flex, type FlexProps } from "./flex.js";
 export { Grid, type GridProps } from "./grid.js";

package/dist/preferences.d.ts

@@ -1,4 +1,12 @@
 import type { DesktopPreferences } from "@phreshos/core";
 /** Complete environment preferences consumed by React UI. */
 export type Preferences = Pick<DesktopPreferences, "theme" | "animations">;
+/** At least one preference merged with the nearest UIProvider. */
+export type PreferencesUpdate = Readonly<{
+    theme: Preferences["theme"];
+    animations?: Preferences["animations"];
+}> | Readonly<{
+    theme?: Preferences["theme"];
+    animations: Preferences["animations"];
+}>;
 export type Theme = Preferences["theme"];

package/dist/ui-provider.d.ts

@@ -1,15 +1,15 @@
 import type { ReactNode } from "react";
-import type { Appearance } from "./appearance.js";
+import type { AppearanceUpdate } from "./appearance.js";
 import { type Direction } from "./direction.js";
-import type { Preferences } from "./preferences.js";
+import type { PreferencesUpdate } from "./preferences.js";
 export { useAppearance, useBrowserPreferences, usePreferences, useThemedValue } from "./appearance-context.js";
 export { useDirection, useDocumentDirection } from "./direction.js";
 /** Establishes only the explicitly supplied UI values for a React subtree. */
 export declare function UIProvider({ appearance, children, direction, preferences }: UIProviderProps): ReactNode;
 export interface UIProviderProps {
-    readonly appearance?: Appearance;
+    readonly appearance?: AppearanceUpdate;
     readonly children: ReactNode;
     /** Establishes the concrete direction inherited by the provider subtree. */
     readonly direction?: Direction;
-    readonly preferences?: Preferences;
+    readonly preferences?: PreferencesUpdate;
 }

package/dist/ui-provider.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useMemo } from "react";
-import { AppearanceContext, fixedPreferencesSource, PreferencesContext } from "./appearance-context.js";
+import { AppearanceContext, fixedPreferencesSource, PreferencesContext, useAppearance, usePreferences } from "./appearance-context.js";
 import { DirectionContext, fixedDirectionSource } from "./direction.js";
 export { useAppearance, useBrowserPreferences, usePreferences, useThemedValue } from "./appearance-context.js";
 export { useDirection, useDocumentDirection } from "./direction.js";
@@ -8,16 +8,55 @@ const directionBoundaryStyle = { display: "contents" };
 /** Establishes only the explicitly supplied UI values for a React subtree. */
 export function UIProvider({ appearance, children, direction, preferences }) {
     let subtree = children;
-    const preferencesSource = useMemo(() => preferences === undefined ? undefined : fixedPreferencesSource(preferences), [preferences]);
     const directionSource = useMemo(() => direction === undefined ? undefined : fixedDirectionSource(direction), [direction]);
-    if (preferencesSource !== undefined) {
-        subtree = _jsx(PreferencesContext.Provider, { value: preferencesSource, children: subtree });
-    }
-    if (appearance !== undefined) {
-        subtree = _jsx(AppearanceContext.Provider, { value: appearance, children: subtree });
-    }
+    if (preferences !== undefined)
+        subtree = _jsx(PreferencesBoundary, { update: preferences, children: subtree });
+    if (appearance !== undefined)
+        subtree = _jsx(AppearanceBoundary, { update: appearance, children: subtree });
     if (directionSource !== undefined) {
         subtree = _jsx(DirectionContext.Provider, { value: directionSource, children: _jsx("div", { dir: direction, style: directionBoundaryStyle, children: subtree }) });
     }
     return subtree;
 }
+function AppearanceBoundary({ children, update }) {
+    const inherited = useAppearance();
+    const appearance = useMemo(() => mergeAppearance(inherited, update), [inherited, update]);
+    return _jsx(AppearanceContext.Provider, { value: appearance, children: children });
+}
+function PreferencesBoundary({ children, update }) {
+    if (update.theme !== undefined && update.animations !== undefined) {
+        // A complete boundary must not subscribe to the browser merely to obtain
+        // inherited fields that it already supplies itself.
+        return _jsx(CompletePreferencesBoundary, { theme: update.theme, animations: update.animations, children: children });
+    }
+    return _jsx(InheritedPreferencesBoundary, { update: update, children: children });
+}
+function CompletePreferencesBoundary({ animations, children, theme }) {
+    const preferences = useMemo(() => Object.freeze({ theme, animations }), [theme, animations]);
+    const source = useMemo(() => fixedPreferencesSource(preferences), [preferences]);
+    return _jsx(PreferencesContext.Provider, { value: source, children: children });
+}
+function InheritedPreferencesBoundary({ children, update }) {
+    const inherited = usePreferences();
+    const preferences = useMemo(() => Object.freeze({ ...inherited, ...update }), [inherited, update]);
+    const source = useMemo(() => fixedPreferencesSource(preferences), [preferences]);
+    return _jsx(PreferencesContext.Provider, { value: source, children: children });
+}
+function mergeAppearance(appearance, update) {
+    return Object.freeze({
+        colors: mergeThemed(appearance.colors, update.colors),
+        spacing: update.spacing ?? appearance.spacing,
+        radius: update.radius ?? appearance.radius,
+        shadow: mergeThemed(appearance.shadow, update.shadow),
+        material: mergeThemed(appearance.material, update.material),
+        transaction: Object.freeze({ ...appearance.transaction, ...update.transaction }),
+    });
+}
+function mergeThemed(current, update) {
+    if (update === undefined)
+        return current;
+    return Object.freeze({
+        light: Object.freeze({ ...current.light, ...update.light }),
+        dark: Object.freeze({ ...current.dark, ...update.dark })
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/react-ui",
-  "version": "0.1.31",
+  "version": "0.1.32",
   "description": "React components for coherent PhreshOS Program interfaces.",
   "type": "module",
   "sideEffects": false,
@@ -57,7 +57,7 @@
   "dependencies": {
     "@base-ui/react": "^1.7.0",
     "@internationalized/date": "^3.12.3",
-    "@phreshos/core": "^0.1.55",
+    "@phreshos/core": "^0.1.56",
     "colorjs.io": "^0.7.1",
     "motion": "^13.2.0",
     "react-aria": "^3.51.0",