@phreshos/react-ui 0.1.32 → 0.1.34

package/dist/color.d.ts

@@ -14,6 +14,8 @@ export declare function color(value: string): ColorScale;
 export declare function resolveColorLevel(value: string, level: ColorLevel): string;
 /** Returns the complete visual treatments derived from one concrete color. */
 export declare function useColor(value: string): ColorScale;
+/** Returns the readable Appearance content color for one semantic or CSS fill. */
+export declare function useContrastingColor(value: Color): string;
 /** Resolves a semantic color from an already selected Appearance branch. */
 export declare function resolveColor(value: Color | undefined, colors: AppearanceColors): string;
 /** Resolves opaque control paint from an already selected Appearance branch. */

package/dist/color.js

@@ -1,4 +1,5 @@
 import { useMemo } from "react";
+import { useResolvedAppearance } from "./appearance-context.js";
 import ColorSpace from "colorjs.io/src/ColorSpace.js";
 import { mix } from "colorjs.io/src/interpolation.js";
 import parse from "colorjs.io/src/parse.js";
@@ -61,6 +62,11 @@ export function resolveColorLevel(value, level) {
 export function useColor(value) {
     return useMemo(() => color(value), [value]);
 }
+/** Returns the readable Appearance content color for one semantic or CSS fill. */
+export function useContrastingColor(value) {
+    const { colors } = useResolvedAppearance();
+    return useMemo(() => contrastingColor(value, colors), [value, colors]);
+}
 /** Resolves a semantic color from an already selected Appearance branch. */
 export function resolveColor(value, colors) {
     const resolved = value ?? defaultColor;

package/dist/main.d.ts

@@ -13,7 +13,8 @@ export { Grid, type GridProps } from "./grid.js";
 export { Surface, type MaterialMode, type MaterialOptions, type ShadowOptions, type SurfaceComponent, type SurfaceHost, type SurfaceHostProps, type SurfaceOwnProps, type SurfaceProps } from "./surface.js";
 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 { Window, type WindowProps, type WindowContentProps, type WindowHeaderProps, type WindowIdentityProps, type WindowCenterProps, type WindowActionsProps, type WindowActionProps, type WindowControlProps, type WindowMaximizeProps, type WindowCloseProps, type WindowMoveCaptureProps } 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";
@@ -50,5 +51,5 @@ export type { ControlColor } from "./control.js";
 export type { LayoutAlignment, LayoutGap, LayoutJustification } from "./layout.js";
 export { resolveRadius, type Radius, type RadiusProps } from "./radius.js";
 export { resolveSpacing, type Spacing } from "./spacing.js";
-export { useColor } from "./color.js";
+export { useColor, useContrastingColor } from "./color.js";
 export { useScale, type NumericScale, type ScaleLevel } from "./scale.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";
@@ -46,5 +47,5 @@ export { AlertDialog } from "./alert-dialog.js";
 export { Tooltip } from "./tooltip.js";
 export { resolveRadius } from "./radius.js";
 export { resolveSpacing } from "./spacing.js";
-export { useColor } from "./color.js";
+export { useColor, useContrastingColor } from "./color.js";
 export { useScale } from "./scale.js";

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,14 @@ 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;
+    /** Whether the represented window is currently maximized. */
+    readonly maximized?: boolean;
+    /** Toggles the represented window between maximized and restored states. */
+    readonly onMaximize?: () => void;
+    /** Receives a synchronous or asynchronous move handoff failure. */
+    readonly onMoveError?: (error: unknown) => void;
 }
 export interface WindowIdentityProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
     readonly icon?: string;
@@ -24,6 +33,7 @@ export interface WindowMaximizeProps extends WindowControlProps {
     readonly maximized?: boolean;
 }
 export type WindowCloseProps = WindowControlProps;
+export type WindowMoveCaptureProps = HTMLAttributes<HTMLDivElement>;
 /** One Surface with a ready-to-use header-and-content composition. */
 export declare const Window: import("react").ForwardRefExoticComponent<Omit<WindowProps, "ref"> & import("react").RefAttributes<HTMLDivElement>> & {
     Header: import("react").ForwardRefExoticComponent<WindowHeaderProps & import("react").RefAttributes<HTMLDivElement>> & {
@@ -36,4 +46,5 @@ export declare const Window: import("react").ForwardRefExoticComponent<Omit<Wind
         Close: import("react").ForwardRefExoticComponent<WindowControlProps & import("react").RefAttributes<HTMLButtonElement>>;
     };
     Content: import("react").ForwardRefExoticComponent<WindowContentProps & import("react").RefAttributes<HTMLDivElement>>;
+    MoveCapture: import("react").ForwardRefExoticComponent<WindowMoveCaptureProps & import("react").RefAttributes<HTMLDivElement>>;
 };

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, maximized = false, onDoubleClick, onLostPointerCapture, onMaximize, 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);
@@ -40,10 +41,21 @@ const HeaderRoot = forwardRef(function HeaderRoot({ active = true, children, col
         active,
         foreground,
         iconRadius: scale(resolved.appearance.radius, "xsmall"),
+        maximized,
+        onMaximize,
         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); }, onDoubleClick: event => {
+                onDoubleClick?.(event);
+                if (!event.defaultPrevented)
+                    onMaximize?.();
+            }, style: {
                 boxSizing: "border-box",
                 display: "flex",
                 alignItems: "center",
@@ -53,8 +65,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 }) });
@@ -112,8 +124,10 @@ const WindowAction = forwardRef(function WindowAction({ ...properties }, ref) {
 const WindowMinimize = forwardRef(function WindowMinimize({ "aria-label": label = "Minimize", preventFocusOnPress = true, ...properties }, ref) {
     return _jsx(WindowAction, { ...properties, ref: ref, "aria-label": label, preventFocusOnPress: preventFocusOnPress, children: _jsx(ControlIcon, { children: _jsx("path", { d: "M1.5 7.5h7" }) }) });
 });
-const WindowMaximize = forwardRef(function WindowMaximize({ "aria-label": label, maximized = false, ...properties }, ref) {
-    return _jsx(WindowAction, { ...properties, ref: ref, "aria-label": label ?? (maximized ? "Restore" : "Maximize"), children: _jsx(ControlIcon, { children: maximized
+const WindowMaximize = forwardRef(function WindowMaximize({ "aria-label": label, maximized, onPress, ...properties }, ref) {
+    const header = useHeader();
+    const selected = maximized ?? header.maximized;
+    return _jsx(WindowAction, { ...properties, ref: ref, onPress: onPress ?? header.onMaximize, "aria-label": label ?? (selected ? "Restore" : "Maximize"), children: _jsx(ControlIcon, { children: selected
                 ? _jsx("path", { d: "M1 4h5v5H1zM4 1h5v5H6.5", strokeWidth: "1.3", strokeLinejoin: "round" })
                 : _jsx("path", { d: "M1.5 1.5h7v7h-7z", strokeWidth: "1.3", strokeLinejoin: "round" }) }) });
 });
@@ -132,8 +146,20 @@ const Header = Object.assign(HeaderRoot, {
     Maximize: WindowMaximize,
     Close: WindowClose
 });
+/** The active full-viewport side of a Window move handoff. */
+const WindowMoveCapture = forwardRef(function WindowMoveCapture({ style, ...properties }, ref) {
+    return _jsx("div", { ...properties, ref: ref, style: {
+            position: "fixed",
+            inset: 0,
+            touchAction: "none",
+            userSelect: "none",
+            cursor: "grab",
+            ...style
+        } });
+});
 /** One Surface with a ready-to-use header-and-content composition. */
 export const Window = Object.assign(WindowRoot, {
     Header,
-    Content: WindowContent
+    Content: WindowContent,
+    MoveCapture: WindowMoveCapture
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/react-ui",
-  "version": "0.1.32",
+  "version": "0.1.34",
   "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.56",
+    "@phreshos/core": "^0.1.59",
     "colorjs.io": "^0.7.1",
     "motion": "^13.2.0",
     "react-aria": "^3.51.0",