@phreshos/react-ui 0.1.31 → 0.1.33

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";
@@ -14,6 +14,7 @@ export { Surface, type MaterialMode, type MaterialOptions, type ShadowOptions, t
 export { defaultColor, type Color, type ColorLevel, type ColorScale } from "./color.js";
 export { Panel, type PanelProps, type PanelHeaderProps, type PanelContentProps } from "./panel.js";
 export { Window, type WindowProps, type WindowContentProps, type WindowHeaderProps, type WindowIdentityProps, type WindowCenterProps, type WindowActionsProps, type WindowActionProps, type WindowControlProps, type WindowMaximizeProps, type WindowCloseProps } from "./window.js";
+export { default as useWindowMoveHandle, type WindowMoveHandle } from "./use-window-move-handle.js";
 export { Button, type ButtonColor, type ButtonProps } from "./button.js";
 export { Input, type InputProps } from "./input.js";
 export { Textarea, type TextareaProps } from "./textarea.js";

package/dist/main.js

@@ -13,6 +13,7 @@ export { defaultColor } from "./color.js";
 // Context-dependent parts are public only through their owning component family.
 export { Panel } from "./panel.js";
 export { Window } from "./window.js";
+export { default as useWindowMoveHandle } from "./use-window-move-handle.js";
 export { Button } from "./button.js";
 export { Input } from "./input.js";
 export { Textarea } from "./textarea.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/dist/use-window-move-handle.d.ts

@@ -0,0 +1,11 @@
+import type { BeginWindowMoveGesture } from "@phreshos/core";
+import { type PointerEventHandler } from "react";
+export interface WindowMoveHandle {
+    onPointerDown: PointerEventHandler<HTMLElement>;
+    onPointerMove: PointerEventHandler<HTMLElement>;
+    onPointerUp: PointerEventHandler<HTMLElement>;
+    onPointerCancel: PointerEventHandler<HTMLElement>;
+    onLostPointerCapture: PointerEventHandler<HTMLElement>;
+}
+/** Turns one DOM element into a move handle for any compatible host gesture. */
+export default function useWindowMoveHandle(beginMoveGesture?: BeginWindowMoveGesture, onError?: (error: unknown) => void): WindowMoveHandle;

package/dist/use-window-move-handle.js

@@ -0,0 +1,114 @@
+import { useEffect, useMemo, useRef } from "react";
+/** Turns one DOM element into a move handle for any compatible host gesture. */
+export default function useWindowMoveHandle(beginMoveGesture, onError) {
+    const active = useRef(null);
+    const beginHandler = useRef(beginMoveGesture);
+    const errorHandler = useRef(onError);
+    beginHandler.current = beginMoveGesture;
+    errorHandler.current = onError;
+    useEffect(() => () => {
+        active.current?.gesture?.cancel();
+        active.current = null;
+    }, []);
+    return useMemo(() => {
+        const point = (event) => ({ x: event.clientX, y: event.clientY });
+        const matching = (event) => active.current?.pointer === event.pointerId;
+        const releaseCapture = (move) => {
+            if (move.element.hasPointerCapture(move.pointer))
+                move.element.releasePointerCapture(move.pointer);
+        };
+        const fail = (error) => {
+            if (errorHandler.current)
+                errorHandler.current(error);
+            else if (typeof globalThis.reportError === "function")
+                globalThis.reportError(error);
+            else
+                setTimeout(() => { throw error; });
+        };
+        const cancel = (event) => {
+            if (!matching(event))
+                return;
+            const move = active.current;
+            active.current = null;
+            move?.gesture?.cancel();
+            if (move)
+                releaseCapture(move);
+        };
+        return {
+            onPointerDown(event) {
+                if (!beginHandler.current || !event.isPrimary || event.button !== 0 || active.current)
+                    return;
+                active.current = {
+                    pointer: event.pointerId,
+                    element: event.currentTarget,
+                    origin: point(event),
+                    gesture: null,
+                    handedOff: false
+                };
+                event.currentTarget.setPointerCapture(event.pointerId);
+            },
+            onPointerMove(event) {
+                const move = active.current;
+                const begin = beginHandler.current;
+                if (!begin || !matching(event) || !move || move.gesture)
+                    return;
+                const current = point(event);
+                if (Math.hypot(current.x - move.origin.x, current.y - move.origin.y) < 4)
+                    return;
+                try {
+                    // Capture proves that an intentional drag began. Releasing it lets
+                    // the ready host receive the continuous pointer stream without transport.
+                    const gesture = begin({ origin: move.origin, point: current });
+                    move.gesture = gesture;
+                    // A failed handoff is reported through `ready`; its corresponding
+                    // completion may reject as the same failure and must not escape alone.
+                    void gesture.finished.catch(() => undefined);
+                    void gesture.ready.then(() => {
+                        if (active.current !== move) {
+                            gesture.cancel();
+                            return gesture.finished;
+                        }
+                        move.handedOff = true;
+                        releaseCapture(move);
+                        return gesture.finished;
+                    }).then(() => {
+                        if (active.current === move)
+                            active.current = null;
+                    }, error => {
+                        if (active.current === move) {
+                            active.current = null;
+                            releaseCapture(move);
+                        }
+                        fail(error);
+                    });
+                }
+                catch (error) {
+                    active.current = null;
+                    releaseCapture(move);
+                    fail(error);
+                }
+            },
+            onPointerUp(event) {
+                if (!matching(event))
+                    return;
+                const move = active.current;
+                active.current = null;
+                move?.gesture?.cancel();
+                if (move)
+                    releaseCapture(move);
+            },
+            onPointerCancel: cancel,
+            onLostPointerCapture(event) {
+                if (!matching(event))
+                    return;
+                // Losing capture after handoff is expected because the host now owns
+                // the pointer. Before handoff it means the local candidate was abandoned.
+                const move = active.current;
+                if (move && !move.handedOff) {
+                    active.current = null;
+                    move.gesture?.cancel();
+                }
+            }
+        };
+    }, []);
+}

package/dist/window.d.ts

@@ -1,4 +1,5 @@
 import type { HTMLAttributes, ReactNode } from "react";
+import type { BeginWindowMoveGesture } from "@phreshos/core";
 import { type ButtonProps } from "./button.js";
 import { type Color } from "./color.js";
 import { type SurfaceProps } from "./surface.js";
@@ -11,6 +12,10 @@ export interface WindowHeaderProps extends Omit<HTMLAttributes<HTMLDivElement>,
     readonly active?: boolean;
     /** Base color inherited by header-owned text and icons. */
     readonly color?: Color;
+    /** Hands an intentional header drag to its host after the pointer threshold. */
+    readonly beginMoveGesture?: BeginWindowMoveGesture;
+    /** Receives a synchronous or asynchronous move handoff failure. */
+    readonly onMoveError?: (error: unknown) => void;
 }
 export interface WindowIdentityProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
     readonly icon?: string;

package/dist/window.js

@@ -6,6 +6,7 @@ import { resolveColor } from "./color.js";
 import { transitionTiming } from "./motion-style.js";
 import { scale } from "./scale.js";
 import { Surface } from "./surface.js";
+import useWindowMoveHandle from "./use-window-move-handle.js";
 const HeaderContext = createContext(null);
 function useHeader() {
     const value = useContext(HeaderContext);
@@ -32,7 +33,7 @@ const WindowContent = forwardRef(function WindowContent({ style, ...properties }
         } });
 });
 /** The composable top region of a window; its enclosing Surface owns the material. */
-const HeaderRoot = forwardRef(function HeaderRoot({ active = true, children, color, onPointerDown, style, ...properties }, ref) {
+const HeaderRoot = forwardRef(function HeaderRoot({ active = true, beginMoveGesture, children, color, onLostPointerCapture, onMoveError, onPointerCancel, onPointerDown, onPointerMove, onPointerUp, style, ...properties }, ref) {
     const resolved = useResolvedAppearance();
     const spacing = resolved.appearance.spacing;
     const foreground = style?.color ?? resolveColor(color ?? "foreground:base", resolved.colors);
@@ -43,7 +44,12 @@ const HeaderRoot = forwardRef(function HeaderRoot({ active = true, children, col
         spacing,
         transition: transitionTiming(resolved.transaction, resolved.preferences.animations)
     };
-    return _jsx(HeaderContext.Provider, { value: state, children: _jsx("div", { ...properties, ref: ref, onPointerDown: onPointerDown, style: {
+    const move = useWindowMoveHandle(beginMoveGesture, onMoveError);
+    return _jsx(HeaderContext.Provider, { value: state, children: _jsx("div", { ...properties, ref: ref, onPointerDown: event => {
+                onPointerDown?.(event);
+                if (!event.defaultPrevented)
+                    move.onPointerDown(event);
+            }, onPointerMove: event => { onPointerMove?.(event); move.onPointerMove(event); }, onPointerUp: event => { onPointerUp?.(event); move.onPointerUp(event); }, onPointerCancel: event => { onPointerCancel?.(event); move.onPointerCancel(event); }, onLostPointerCapture: event => { onLostPointerCapture?.(event); move.onLostPointerCapture(event); }, style: {
                 boxSizing: "border-box",
                 display: "flex",
                 alignItems: "center",
@@ -53,8 +59,8 @@ const HeaderRoot = forwardRef(function HeaderRoot({ active = true, children, col
                 paddingInline: spacing,
                 flexShrink: 0,
                 userSelect: "none",
-                touchAction: onPointerDown ? "none" : undefined,
-                cursor: onPointerDown ? "grab" : undefined,
+                touchAction: beginMoveGesture ? "none" : undefined,
+                cursor: beginMoveGesture ? "grab" : undefined,
                 color: foreground,
                 ...style
             }, children: children }) });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/react-ui",
-  "version": "0.1.31",
+  "version": "0.1.33",
   "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.59",
     "colorjs.io": "^0.7.1",
     "motion": "^13.2.0",
     "react-aria": "^3.51.0",