@phreshos/react-ui 0.1.32 → 0.1.33

package/dist/main.d.ts

@@ -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/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.32",
+  "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.56",
+    "@phreshos/core": "^0.1.59",
     "colorjs.io": "^0.7.1",
     "motion": "^13.2.0",
     "react-aria": "^3.51.0",