@almadar/ui 5.62.0 → 5.63.1

package/dist/hooks/index.js

@@ -2514,6 +2514,152 @@ function usePinchZoom(options = {}) {
     resetZoom
   };
 }
+function localPoint(canvas, clientX, clientY) {
+  if (!canvas) return { x: clientX, y: clientY };
+  const rect = canvas.getBoundingClientRect();
+  return { x: clientX - rect.left, y: clientY - rect.top };
+}
+function useCanvasGestures(options) {
+  const {
+    canvasRef,
+    enabled = true,
+    wheelStep = 1.1,
+    onPointerDown,
+    onPointerMove,
+    onPointerUp,
+    onZoom,
+    onPanDelta,
+    onMultiTouchStart
+  } = options;
+  const pointers = useRef(/* @__PURE__ */ new Map());
+  const pinch = useRef(null);
+  const computePinch = useCallback(() => {
+    const pts = [...pointers.current.values()];
+    const dx = pts[1].x - pts[0].x;
+    const dy = pts[1].y - pts[0].y;
+    return {
+      distance: Math.hypot(dx, dy) || 1,
+      centroid: { x: (pts[0].x + pts[1].x) / 2, y: (pts[0].y + pts[1].y) / 2 }
+    };
+  }, []);
+  const handlePointerDown = useCallback(
+    (e) => {
+      if (!enabled) return;
+      e.currentTarget.setPointerCapture(e.pointerId);
+      pointers.current.set(e.pointerId, localPoint(canvasRef.current, e.clientX, e.clientY));
+      if (pointers.current.size === 2) {
+        onMultiTouchStart?.();
+        pinch.current = computePinch();
+      } else if (pointers.current.size === 1) {
+        onPointerDown?.(e);
+      }
+    },
+    [enabled, canvasRef, onMultiTouchStart, computePinch, onPointerDown]
+  );
+  const handlePointerMove = useCallback(
+    (e) => {
+      if (!enabled) return;
+      if (pointers.current.has(e.pointerId)) {
+        pointers.current.set(e.pointerId, localPoint(canvasRef.current, e.clientX, e.clientY));
+      }
+      if (pointers.current.size >= 2 && pinch.current) {
+        const next = computePinch();
+        const prev = pinch.current;
+        if (next.distance !== prev.distance) {
+          onZoom?.(next.distance / prev.distance, next.centroid.x, next.centroid.y);
+        }
+        onPanDelta?.(next.centroid.x - prev.centroid.x, next.centroid.y - prev.centroid.y);
+        pinch.current = next;
+        return;
+      }
+      onPointerMove?.(e);
+    },
+    [enabled, canvasRef, computePinch, onZoom, onPanDelta, onPointerMove]
+  );
+  const endPointer = useCallback(
+    (e, fireUp) => {
+      const wasMulti = pointers.current.size >= 2;
+      pointers.current.delete(e.pointerId);
+      if (pointers.current.size < 2) pinch.current = null;
+      if (wasMulti && pointers.current.size === 1) return;
+      if (pointers.current.size === 0 && fireUp) onPointerUp?.(e);
+    },
+    [onPointerUp]
+  );
+  const handlePointerUp = useCallback(
+    (e) => {
+      if (!enabled) return;
+      endPointer(e, true);
+    },
+    [enabled, endPointer]
+  );
+  const handlePointerCancel = useCallback(
+    (e) => {
+      if (!enabled) return;
+      endPointer(e, false);
+    },
+    [enabled, endPointer]
+  );
+  const handleWheel = useCallback(
+    (e) => {
+      if (!enabled) return;
+      e.preventDefault();
+      const { x, y } = localPoint(canvasRef.current, e.clientX, e.clientY);
+      onZoom?.(e.deltaY < 0 ? wheelStep : 1 / wheelStep, x, y);
+    },
+    [enabled, canvasRef, wheelStep, onZoom]
+  );
+  return {
+    onPointerDown: handlePointerDown,
+    onPointerMove: handlePointerMove,
+    onPointerUp: handlePointerUp,
+    onPointerCancel: handlePointerCancel,
+    onWheel: handleWheel
+  };
+}
+function useTapReveal(options = {}) {
+  const { onReveal, onDismiss, refs, enabled = true } = options;
+  const [revealed, setRevealed] = useState(false);
+  const onRevealRef = useRef(onReveal);
+  const onDismissRef = useRef(onDismiss);
+  onRevealRef.current = onReveal;
+  onDismissRef.current = onDismiss;
+  const reveal = useCallback(() => {
+    setRevealed((wasRevealed) => {
+      if (!wasRevealed) onRevealRef.current?.();
+      return true;
+    });
+  }, []);
+  const dismiss = useCallback(() => {
+    setRevealed((wasRevealed) => {
+      if (wasRevealed) onDismissRef.current?.();
+      return false;
+    });
+  }, []);
+  const onPointerDown = useCallback(
+    (e) => {
+      if (!enabled || e.pointerType === "mouse") return;
+      if (revealed) dismiss();
+      else reveal();
+    },
+    [enabled, revealed, reveal, dismiss]
+  );
+  useEffect(() => {
+    if (!revealed || typeof document === "undefined") return;
+    const onDocDown = (ev) => {
+      const target = ev.target;
+      if (!(target instanceof Node)) return;
+      const inside = (refs ?? []).some((r) => r.current?.contains(target));
+      if (!inside) dismiss();
+    };
+    const id = setTimeout(() => document.addEventListener("pointerdown", onDocDown), 0);
+    return () => {
+      clearTimeout(id);
+      document.removeEventListener("pointerdown", onDocDown);
+    };
+  }, [revealed, refs, dismiss]);
+  return { revealed, triggerProps: { onPointerDown }, reveal, dismiss };
+}
 var ALMADAR_DND_MIME = "application/x-almadar-dnd";
 function useDraggable({ payload, disabled = false }) {
   const [isDragging, setIsDragging] = useState(false);
@@ -2749,4 +2895,4 @@ function useGitHubBranches(owner, repo, enabled = true) {
   });
 }
 
-export { ALMADAR_DND_MIME, DEFAULT_SLOTS, I18nProvider, clearEntities, createTranslate, getAllEntities, getByType, getEntity, getSingleton, parseQueryBinding, removeEntity, spawnEntity, updateEntity, updateSingleton, useAgentChat, useAuthContext, useCompile, useConnectGitHub, useDeepAgentGeneration, useDisconnectGitHub, useDragReorder, useDraggable, useDropZone, useEmitEvent, useEntities, useEntitiesByType, useEntity as useEntityById, useEventBus, useEventListener, useExtensions, useFileEditor, useFileSystem, useGitHubBranches, useGitHubRepo, useGitHubRepos, useGitHubStatus, useInfiniteScroll, useInput, useLongPress, useOrbitalHistory, usePhysics, usePinchZoom, usePlayer, usePreview, usePullToRefresh, useQuerySingleton, useRenderInterpolation, useSingletonEntity, useSwipeGesture, useTraitListens, useTranslate, useUIEvents, useUISlotManager, useValidation };
+export { ALMADAR_DND_MIME, DEFAULT_SLOTS, I18nProvider, clearEntities, createTranslate, getAllEntities, getByType, getEntity, getSingleton, parseQueryBinding, removeEntity, spawnEntity, updateEntity, updateSingleton, useAgentChat, useAuthContext, useCanvasGestures, useCompile, useConnectGitHub, useDeepAgentGeneration, useDisconnectGitHub, useDragReorder, useDraggable, useDropZone, useEmitEvent, useEntities, useEntitiesByType, useEntity as useEntityById, useEventBus, useEventListener, useExtensions, useFileEditor, useFileSystem, useGitHubBranches, useGitHubRepo, useGitHubRepos, useGitHubStatus, useInfiniteScroll, useInput, useLongPress, useOrbitalHistory, usePhysics, usePinchZoom, usePlayer, usePreview, usePullToRefresh, useQuerySingleton, useRenderInterpolation, useSingletonEntity, useSwipeGesture, useTapReveal, useTraitListens, useTranslate, useUIEvents, useUISlotManager, useValidation };

package/dist/hooks/useCanvasGestures.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Unified pointer/touch gesture detection for canvas surfaces (graph, isometric, etc.).
+ *
+ * It owns the hard part — pointer tracking + two-finger pinch (scale factor + centroid) —
+ * and DELEGATES application to the consumer via callbacks, so each canvas applies pan/zoom
+ * in its own coordinate convention (screen-offset vs world-camera). A single pointer is
+ * passed straight through to the consumer's domain handlers (pan / node-drag / tile-select);
+ * a second pointer takes over as a pinch and cancels any in-flight single-pointer action.
+ *
+ * Pointer Events cover mouse, touch and pen, so this REPLACES mouse handlers — no dual paths.
+ */
+export interface CanvasGestureCallbacks {
+    /** Single-pointer down — start the consumer's pan / drag / select (domain-specific). */
+    onPointerDown?: (e: React.PointerEvent<HTMLCanvasElement>) => void;
+    /** Single-pointer move. */
+    onPointerMove?: (e: React.PointerEvent<HTMLCanvasElement>) => void;
+    /** Single-pointer up. */
+    onPointerUp?: (e: React.PointerEvent<HTMLCanvasElement>) => void;
+    /**
+     * Multiplicative zoom around a canvas-local point. Fired by wheel and by pinch.
+     * Consumer applies `newZoom = clamp(oldZoom * factor)` keeping (centerX,centerY) fixed.
+     */
+    onZoom?: (factor: number, centerX: number, centerY: number) => void;
+    /** Two-finger pan delta in canvas-local px (fired alongside pinch). */
+    onPanDelta?: (dx: number, dy: number) => void;
+    /** A second pointer arrived — cancel any single-pointer pan/drag the consumer started. */
+    onMultiTouchStart?: () => void;
+}
+export interface UseCanvasGesturesOptions extends CanvasGestureCallbacks {
+    /** The canvas being gestured on (for coordinate translation). */
+    canvasRef: React.RefObject<HTMLCanvasElement | null>;
+    /** When false, all gestures are inert. Default true. */
+    enabled?: boolean;
+    /** Wheel zoom step per notch (>1). Default 1.1. */
+    wheelStep?: number;
+}
+export interface CanvasGestureHandlers {
+    onPointerDown: (e: React.PointerEvent<HTMLCanvasElement>) => void;
+    onPointerMove: (e: React.PointerEvent<HTMLCanvasElement>) => void;
+    onPointerUp: (e: React.PointerEvent<HTMLCanvasElement>) => void;
+    onPointerCancel: (e: React.PointerEvent<HTMLCanvasElement>) => void;
+    onWheel: (e: React.WheelEvent<HTMLCanvasElement>) => void;
+}
+export declare function useCanvasGestures(options: UseCanvasGesturesOptions): CanvasGestureHandlers;

package/dist/hooks/useTapReveal.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Hover-only reveals (tooltips, hover-popovers, submenus, `Box.hoverEvent`) have no hover on
+ * touch, so they're invisible/unreachable. This adds the tap-to-reveal fallback: on a touch/pen
+ * tap the surface reveals and fires the SAME event the hover path fires; a tap outside dismisses.
+ * Mouse is left to the component's existing hover handlers (`pointerType === 'mouse'` is ignored),
+ * so this is purely additive — no behavior change on desktop.
+ */
+export interface TapRevealOptions {
+    /** Fired when a tap reveals — reuse to emit the component's existing hover event. */
+    onReveal?: () => void;
+    /** Fired when an outside tap (or a second trigger tap) dismisses. */
+    onDismiss?: () => void;
+    /**
+     * Elements considered "inside" for outside-tap detection. Pass the trigger and the surface
+     * (the surface may be portaled, so it isn't a DOM descendant of the trigger). A tap whose
+     * target is inside none of these dismisses.
+     */
+    refs?: ReadonlyArray<React.RefObject<HTMLElement | null>>;
+    /** When false, taps are ignored (hover-only). Default true. */
+    enabled?: boolean;
+}
+export interface TapRevealResult {
+    /** Whether the surface is currently revealed via a tap. OR this with the hover state. */
+    revealed: boolean;
+    /** Spread on the trigger; toggles reveal on a touch/pen tap (ignores mouse). */
+    triggerProps: {
+        onPointerDown: (e: React.PointerEvent) => void;
+    };
+    reveal: () => void;
+    dismiss: () => void;
+}
+export declare function useTapReveal(options?: TapRevealOptions): TapRevealResult;

package/dist/marketing/index.cjs

@@ -2625,6 +2625,49 @@ function useEventBus() {
     };
   }, [baseBus, scope]);
 }
+function useTapReveal(options = {}) {
+  const { onReveal, onDismiss, refs, enabled = true } = options;
+  const [revealed, setRevealed] = React9.useState(false);
+  const onRevealRef = React9.useRef(onReveal);
+  const onDismissRef = React9.useRef(onDismiss);
+  onRevealRef.current = onReveal;
+  onDismissRef.current = onDismiss;
+  const reveal = React9.useCallback(() => {
+    setRevealed((wasRevealed) => {
+      if (!wasRevealed) onRevealRef.current?.();
+      return true;
+    });
+  }, []);
+  const dismiss = React9.useCallback(() => {
+    setRevealed((wasRevealed) => {
+      if (wasRevealed) onDismissRef.current?.();
+      return false;
+    });
+  }, []);
+  const onPointerDown = React9.useCallback(
+    (e) => {
+      if (!enabled || e.pointerType === "mouse") return;
+      if (revealed) dismiss();
+      else reveal();
+    },
+    [enabled, revealed, reveal, dismiss]
+  );
+  React9.useEffect(() => {
+    if (!revealed || typeof document === "undefined") return;
+    const onDocDown = (ev) => {
+      const target = ev.target;
+      if (!(target instanceof Node)) return;
+      const inside = (refs ?? []).some((r2) => r2.current?.contains(target));
+      if (!inside) dismiss();
+    };
+    const id = setTimeout(() => document.addEventListener("pointerdown", onDocDown), 0);
+    return () => {
+      clearTimeout(id);
+      document.removeEventListener("pointerdown", onDocDown);
+    };
+  }, [revealed, refs, dismiss]);
+  return { revealed, triggerProps: { onPointerDown }, reveal, dismiss };
+}
 
 // components/core/atoms/Box.tsx
 var paddingStyles = {
@@ -2752,10 +2795,12 @@ var Box = React9__default.default.forwardRef(
     action,
     actionPayload,
     hoverEvent,
+    tapReveal = true,
     maxWidth,
     onClick,
     onMouseEnter,
     onMouseLeave,
+    onPointerDown,
     ...rest
   }, ref) => {
     const eventBus = useEventBus();
@@ -2778,6 +2823,19 @@ var Box = React9__default.default.forwardRef(
       }
       onMouseLeave?.(e);
     }, [hoverEvent, eventBus, onMouseLeave]);
+    const { triggerProps } = useTapReveal({
+      enabled: tapReveal && !!hoverEvent,
+      onReveal: React9.useCallback(() => {
+        if (hoverEvent) eventBus.emit(`UI:${hoverEvent}`, { hovered: true });
+      }, [hoverEvent, eventBus]),
+      onDismiss: React9.useCallback(() => {
+        if (hoverEvent) eventBus.emit(`UI:${hoverEvent}`, { hovered: false });
+      }, [hoverEvent, eventBus])
+    });
+    const handlePointerDown = React9.useCallback((e) => {
+      if (hoverEvent && tapReveal) triggerProps.onPointerDown(e);
+      onPointerDown?.(e);
+    }, [hoverEvent, tapReveal, triggerProps, onPointerDown]);
     const isClickable = action || onClick;
     return React9__default.default.createElement(
       Component,
@@ -2805,6 +2863,7 @@ var Box = React9__default.default.forwardRef(
         onClick: isClickable ? handleClick : void 0,
         onMouseEnter: hoverEvent || onMouseEnter ? handleMouseEnter : void 0,
         onMouseLeave: hoverEvent || onMouseLeave ? handleMouseLeave : void 0,
+        onPointerDown: hoverEvent && tapReveal || onPointerDown ? handlePointerDown : void 0,
         style: maxWidth ? { maxWidth, ...rest.style } : rest.style,
         ...rest
       },

package/dist/marketing/index.d.cts

@@ -55,6 +55,8 @@ interface BoxProps extends React.HTMLAttributes<HTMLDivElement> {
     actionPayload?: EventPayload;
     /** Declarative hover event — emits UI:{hoverEvent} with { hovered: true/false } on mouseEnter/mouseLeave */
     hoverEvent?: EventKey;
+    /** When true (default), a touch/pen tap also fires `hoverEvent` (toggling hovered) so hover-only reveals work on touch. */
+    tapReveal?: boolean;
     /** Maximum width (CSS value, e.g., "550px", "80rem") */
     maxWidth?: string;
     /** Children elements */

package/dist/marketing/index.js

@@ -2601,6 +2601,49 @@ function useEventBus() {
     };
   }, [baseBus, scope]);
 }
+function useTapReveal(options = {}) {
+  const { onReveal, onDismiss, refs, enabled = true } = options;
+  const [revealed, setRevealed] = useState(false);
+  const onRevealRef = useRef(onReveal);
+  const onDismissRef = useRef(onDismiss);
+  onRevealRef.current = onReveal;
+  onDismissRef.current = onDismiss;
+  const reveal = useCallback(() => {
+    setRevealed((wasRevealed) => {
+      if (!wasRevealed) onRevealRef.current?.();
+      return true;
+    });
+  }, []);
+  const dismiss = useCallback(() => {
+    setRevealed((wasRevealed) => {
+      if (wasRevealed) onDismissRef.current?.();
+      return false;
+    });
+  }, []);
+  const onPointerDown = useCallback(
+    (e) => {
+      if (!enabled || e.pointerType === "mouse") return;
+      if (revealed) dismiss();
+      else reveal();
+    },
+    [enabled, revealed, reveal, dismiss]
+  );
+  useEffect(() => {
+    if (!revealed || typeof document === "undefined") return;
+    const onDocDown = (ev) => {
+      const target = ev.target;
+      if (!(target instanceof Node)) return;
+      const inside = (refs ?? []).some((r2) => r2.current?.contains(target));
+      if (!inside) dismiss();
+    };
+    const id = setTimeout(() => document.addEventListener("pointerdown", onDocDown), 0);
+    return () => {
+      clearTimeout(id);
+      document.removeEventListener("pointerdown", onDocDown);
+    };
+  }, [revealed, refs, dismiss]);
+  return { revealed, triggerProps: { onPointerDown }, reveal, dismiss };
+}
 
 // components/core/atoms/Box.tsx
 var paddingStyles = {
@@ -2728,10 +2771,12 @@ var Box = React9.forwardRef(
     action,
     actionPayload,
     hoverEvent,
+    tapReveal = true,
     maxWidth,
     onClick,
     onMouseEnter,
     onMouseLeave,
+    onPointerDown,
     ...rest
   }, ref) => {
     const eventBus = useEventBus();
@@ -2754,6 +2799,19 @@ var Box = React9.forwardRef(
       }
       onMouseLeave?.(e);
     }, [hoverEvent, eventBus, onMouseLeave]);
+    const { triggerProps } = useTapReveal({
+      enabled: tapReveal && !!hoverEvent,
+      onReveal: useCallback(() => {
+        if (hoverEvent) eventBus.emit(`UI:${hoverEvent}`, { hovered: true });
+      }, [hoverEvent, eventBus]),
+      onDismiss: useCallback(() => {
+        if (hoverEvent) eventBus.emit(`UI:${hoverEvent}`, { hovered: false });
+      }, [hoverEvent, eventBus])
+    });
+    const handlePointerDown = useCallback((e) => {
+      if (hoverEvent && tapReveal) triggerProps.onPointerDown(e);
+      onPointerDown?.(e);
+    }, [hoverEvent, tapReveal, triggerProps, onPointerDown]);
     const isClickable = action || onClick;
     return React9.createElement(
       Component,
@@ -2781,6 +2839,7 @@ var Box = React9.forwardRef(
         onClick: isClickable ? handleClick : void 0,
         onMouseEnter: hoverEvent || onMouseEnter ? handleMouseEnter : void 0,
         onMouseLeave: hoverEvent || onMouseLeave ? handleMouseLeave : void 0,
+        onPointerDown: hoverEvent && tapReveal || onPointerDown ? handlePointerDown : void 0,
         style: maxWidth ? { maxWidth, ...rest.style } : rest.style,
         ...rest
       },