@phreshos/react-ui 0.1.26 → 0.1.28

package/README.md

@@ -8,8 +8,8 @@ Environment-neutral React components and the visual language of PhreshOS.
 
 ## Role
 
-React UI interprets Core Appearance and Theme contracts as reusable visual
-primitives. The Desktop and Programs compose those primitives instead of
+React UI owns reusable visual contracts that accept the corresponding PhreshOS
+System values directly. The Desktop and Programs compose those primitives instead of
 reimplementing material, spacing, color, radius, or interaction behavior.
 
 The package does not depend on a Client or Server runtime and does not own
@@ -25,9 +25,8 @@ applications own composition.
 | Bun | `bun add @phreshos/react-ui` |
 | Yarn | `yarn add @phreshos/react-ui` |
 
-Core is a built-in runtime dependency. React and React DOM remain peer
-dependencies because the application and React UI must share one React
-runtime.
+React and React DOM are peer dependencies because the application and React UI
+must share one React runtime.
 
 ```tsx
 import { Button, Surface } from "@phreshos/react-ui"
@@ -37,21 +36,23 @@ import { Button, Surface } from "@phreshos/react-ui"
 </Surface>
 ```
 
-Without a provider, components use Core's `defaultAppearance` and reactively
+Without a provider, components use React UI's `defaultAppearance` and reactively
 follow the browser's complete visual preferences. `UIProvider` supplies the
-Appearance, Preferences, and direction shared by a React UI subtree. Omitted
-Appearance and Preferences values inherit from the nearest provider.
-React UI also exports that same canonical `defaultAppearance` value for callers
-that need it explicitly.
-See [Appearance](https://docs.phreshos.com/system/appearance) for the contract
-interpreted by the provider and components.
+Appearance, Preferences, and direction explicitly established for a React UI
+subtree. Each omitted property inherits independently from the nearest provider
+or follows its own default resolution. A provider with no properties introduces
+no boundary or behavior.
+React UI also exports `defaultAppearance` for callers that need the value
+explicitly. A complete System Appearance can be passed directly; React UI uses
+the visual fields it owns and ignores additional System fields such as
+wallpapers.
 
 React UI is neutral between left-to-right and right-to-left interfaces.
-`UIProvider` creates a direction boundary that participates in native DOM
-inheritance without creating a layout box. Its direction follows `<html dir>`
-unless `direction` supplies an explicit override. React UI reads that same
-resolved value only for JavaScript behavior and portals that cannot rely on
-native inheritance.
+An explicit `UIProvider` direction creates a boundary that participates in
+native DOM inheritance without creating a layout box. When direction is
+omitted, the provider leaves DOM inheritance unchanged. React UI reads the
+nearest explicit direction—or `<html dir>` when there is none—only for
+JavaScript behavior and portals that cannot rely on native inheritance.
 
 ```tsx
 import { UIProvider, Select } from "@phreshos/react-ui"
@@ -277,8 +278,7 @@ the committed dependency graph without local package substitutions.
 
 ## Related repositories
 
-- [`@phreshos/core`](https://github.com/PhreshOS/core) owns Appearance, Theme,
-  and the shared values interpreted here.
+- [`@phreshos/core`](https://github.com/PhreshOS/core) owns the System contracts.
 - [`@phreshos/react`](https://github.com/PhreshOS/react) owns runtime-neutral
   React state adaptation.
 - [PhreshOS System](https://github.com/PhreshOS/system) composes the visual

package/dist/appearance-context.d.ts

@@ -1,19 +1,8 @@
-import { type Appearance, type DesktopPreferences as Preferences, type ThemedValue } from "@phreshos/core";
-export declare const AppearanceContext: import("react").Context<Readonly<{
-    colors: ThemedValue<import("@phreshos/core").AppearanceColors>;
-    spacing: number;
-    radius: number;
-    shadow: ThemedValue<import("@phreshos/core").AppearanceShadow>;
-    material: ThemedValue<import("@phreshos/core").AppearanceMaterial>;
-    transaction: import("@phreshos/core").AppearanceTransaction;
-    signInWallpaper: ThemedValue<string | null>;
-    desktopWallpaper: ThemedValue<string | null>;
-}>>;
-export declare const PreferencesContext: import("react").Context<Readonly<{
-    theme: import("@phreshos/core").Theme;
-    animations: boolean;
-}> | null>;
-/** Returns the nearest unresolved Appearance, or Core's complete default. */
+import { type Appearance, type ThemedValue } from "./appearance.js";
+import type { Preferences } from "./preferences.js";
+export declare const AppearanceContext: import("react").Context<Appearance>;
+export declare const PreferencesContext: import("react").Context<Preferences | null>;
+/** Returns the nearest unresolved appearance, or React UI's default. */
 export declare function useAppearance(): Appearance;
 /** Returns the nearest complete Preferences, or reactively follows the browser. */
 export declare function usePreferences(): Preferences;

package/dist/appearance-context.js

@@ -1,8 +1,8 @@
 import { createContext, useContext, useMemo, useSyncExternalStore } from "react";
-import { defaultAppearance } from "@phreshos/core";
+import { defaultAppearance } from "./appearance.js";
 export const AppearanceContext = createContext(defaultAppearance);
 export const PreferencesContext = createContext(null);
-/** Returns the nearest unresolved Appearance, or Core's complete default. */
+/** Returns the nearest unresolved appearance, or React UI's default. */
 export function useAppearance() {
     return useContext(AppearanceContext);
 }

package/dist/appearance.d.ts

@@ -0,0 +1,6 @@
+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";
+/** Complete visual input consumed by React UI. */
+export type Appearance = Pick<SystemAppearance, "colors" | "spacing" | "radius" | "shadow" | "material" | "transaction">;
+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/appearance.js

@@ -0,0 +1,11 @@
+import { appearanceLimits, defaultAppearance as systemDefaultAppearance } from "@phreshos/core";
+export { appearanceLimits };
+/** React UI's default visual input, derived from the System default. */
+export const defaultAppearance = Object.freeze({
+    colors: systemDefaultAppearance.colors,
+    spacing: systemDefaultAppearance.spacing,
+    radius: systemDefaultAppearance.radius,
+    shadow: systemDefaultAppearance.shadow,
+    material: systemDefaultAppearance.material,
+    transaction: systemDefaultAppearance.transaction
+});

package/dist/color.d.ts

@@ -1,4 +1,4 @@
-import type { AppearanceColor } from "@phreshos/core";
+import type { AppearanceColor } from "./appearance.js";
 /** A visual treatment derived from one concrete CSS color. */
 export type ColorLevel = "subtle" | "soft" | "base" | "strong" | "intense";
 /** Every visual treatment derived from one concrete CSS color. */

package/dist/layout.d.ts

@@ -1,5 +1,5 @@
 import type { CSSProperties } from "react";
-import type { Appearance } from "@phreshos/core";
+import type { Appearance } from "./appearance.js";
 import { type Spacing } from "./spacing.js";
 /** Cross-axis alignment shared by layout containers. */
 export type LayoutAlignment = "start" | "center" | "end" | "stretch" | "baseline";

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 } from "@phreshos/core";
+export { defaultAppearance, type Appearance, 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 { DesktopPreferences as Preferences } from "@phreshos/core";
+export type { Preferences, 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/main.js

@@ -4,7 +4,7 @@
  * Components enter this surface only after their implementation-independent
  * behavior contract has been established by the package's tests.
  */
-export { defaultAppearance } from "@phreshos/core";
+export { defaultAppearance } from "./appearance.js";
 export { UIProvider, useAppearance, useBrowserPreferences, useDirection, useDocumentDirection, usePreferences, useThemedValue } from "./ui-provider.js";
 export { Flex } from "./flex.js";
 export { Grid } from "./grid.js";

package/dist/material-options.js

@@ -1,4 +1,4 @@
-import { appearanceLimits } from "@phreshos/core";
+import { appearanceLimits } from "./appearance.js";
 import { useAppearance, useThemedValue } from "./ui-provider.js";
 import { isScaleLevel, scale, scaleMultiplier } from "./scale.js";
 /** Resolves material values from the current Appearance without knowing any host geometry. */

package/dist/motion-style.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { defaultAppearance } from "@phreshos/core";
+import { defaultAppearance } from "./appearance.js";
 import { useAppearance, usePreferences } from "./appearance-context.js";
 const visualProperties = "background-color, color, border-color, border-radius, box-shadow";
 const paintProperties = "fill, stroke, opacity";

package/dist/preferences.d.ts

@@ -0,0 +1,4 @@
+import type { DesktopPreferences } from "@phreshos/core";
+/** Complete environment preferences consumed by React UI. */
+export type Preferences = Pick<DesktopPreferences, "theme" | "animations">;
+export type Theme = Preferences["theme"];

package/dist/radius.d.ts

@@ -1,5 +1,5 @@
 import type { CSSProperties } from "react";
-import type { Appearance } from "@phreshos/core";
+import type { Appearance } from "./appearance.js";
 import { type ScaleLevel } from "./scale.js";
 /** An Appearance-derived level, fully rounded shape, pixel value, or explicit CSS corner radius. */
 export type Radius = ScaleLevel | "full" | number | (string & {});

package/dist/shadow-options.js

@@ -1,4 +1,4 @@
-import { appearanceLimits } from "@phreshos/core";
+import { appearanceLimits } from "./appearance.js";
 import { useAppearance, useThemedValue } from "./ui-provider.js";
 import { isScaleLevel, scale } from "./scale.js";
 /** Resolves shadow values from the active Appearance branch. */

package/dist/spacing.d.ts

@@ -1,5 +1,5 @@
 import type { CSSProperties } from "react";
-import type { Appearance } from "@phreshos/core";
+import type { Appearance } from "./appearance.js";
 import { type ScaleLevel } from "./scale.js";
 /** An Appearance-derived level, pixel value, or explicit CSS spacing value. */
 export type Spacing = ScaleLevel | number | (string & {});

package/dist/surface.js

@@ -49,7 +49,10 @@ const layerStyle = {
     pointerEvents: "none"
 };
 function SurfaceLayers({ material }) {
-    const { backdrop, saturation, distortion } = material;
+    const filtersVisible = material.opacity < 1;
+    const backdrop = filtersVisible ? material.backdrop : 0;
+    const saturation = filtersVisible ? material.saturation : 1;
+    const distortion = filtersVisible ? material.distortion : 0;
     const frost = [
         backdrop === 0 ? "" : `blur(${backdrop}px)`,
         saturation === 1 ? "" : `saturate(${saturation})`

package/dist/ui-provider.d.ts

@@ -1,10 +1,11 @@
 import type { ReactNode } from "react";
-import { type Appearance, type DesktopPreferences as Preferences } from "@phreshos/core";
+import type { Appearance } from "./appearance.js";
 import { type Direction } from "./direction.js";
+import type { Preferences } from "./preferences.js";
 export { useAppearance, useBrowserPreferences, usePreferences, useThemedValue } from "./appearance-context.js";
 export { useDirection, useDocumentDirection } from "./direction.js";
-/** Supplies the complete shared environment of a React UI subtree. */
-export declare function UIProvider({ appearance, children, direction, preferences }: UIProviderProps): import("react").JSX.Element;
+/** 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 children: ReactNode;

package/dist/ui-provider.js

@@ -1,18 +1,20 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import {} from "@phreshos/core";
-import MotionStyle from "./motion-style.js";
-import { AppearanceContext, PreferencesContext, useAppearance, usePreferences } from "./appearance-context.js";
-import { DirectionContext, useDocumentDirection } from "./direction.js";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { AppearanceContext, PreferencesContext } from "./appearance-context.js";
+import { DirectionContext } from "./direction.js";
 export { useAppearance, useBrowserPreferences, usePreferences, useThemedValue } from "./appearance-context.js";
 export { useDirection, useDocumentDirection } from "./direction.js";
 const directionBoundaryStyle = { display: "contents" };
-/** Supplies the complete shared environment of a React UI subtree. */
+/** Establishes only the explicitly supplied UI values for a React subtree. */
 export function UIProvider({ appearance, children, direction, preferences }) {
-    const inheritedAppearance = useAppearance();
-    const inheritedPreferences = usePreferences();
-    const documentDirection = useDocumentDirection();
-    const resolvedAppearance = appearance ?? inheritedAppearance;
-    const resolvedDirection = direction ?? documentDirection;
-    const resolvedPreferences = preferences ?? inheritedPreferences;
-    return _jsx(DirectionContext.Provider, { value: resolvedDirection, children: _jsx("div", { dir: resolvedDirection, style: directionBoundaryStyle, children: _jsx(AppearanceContext.Provider, { value: resolvedAppearance, children: _jsxs(PreferencesContext.Provider, { value: resolvedPreferences, children: [_jsx(MotionStyle, {}), children] }) }) }) });
+    let subtree = children;
+    if (preferences !== undefined) {
+        subtree = _jsx(PreferencesContext.Provider, { value: preferences, children: subtree });
+    }
+    if (appearance !== undefined) {
+        subtree = _jsx(AppearanceContext.Provider, { value: appearance, children: subtree });
+    }
+    if (direction !== undefined) {
+        subtree = _jsx(DirectionContext.Provider, { value: direction, children: _jsx("div", { dir: direction, style: directionBoundaryStyle, children: subtree }) });
+    }
+    return subtree;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/react-ui",
-  "version": "0.1.26",
+  "version": "0.1.28",
   "description": "React components for coherent PhreshOS Program interfaces.",
   "type": "module",
   "sideEffects": false,
@@ -56,7 +56,7 @@
   },
   "dependencies": {
     "@base-ui/react": "^1.7.0",
-    "@phreshos/core": "^0.1.52",
+    "@phreshos/core": "^0.1.53",
     "colorjs.io": "^0.7.1",
     "motion": "^13.2.0",
     "react-aria-components": "^1.20.0"