@workbench-kit/react 0.0.2-prototype.0.1.2 → 0.0.2-prototype.0.2.10

package/src/overlay/measureAnchoredOverlayPanel.ts

@@ -0,0 +1,107 @@
+export type AnchoredOverlayPlacement = 'side' | 'below' | 'above';
+
+export interface MeasureAnchoredOverlayPanelOptions {
+  readonly panelWidthPx?: number;
+  readonly viewportPaddingPx?: number;
+  readonly anchorGapPx?: number;
+  readonly maxHeightRatio?: number;
+  readonly sidePreferTriggerLeftRatio?: number;
+}
+
+export interface AnchoredOverlayPanelRect {
+  readonly top: number;
+  readonly left: number;
+  readonly width: number;
+  readonly maxHeight: number;
+  readonly placement: AnchoredOverlayPlacement;
+}
+
+const DEFAULT_PANEL_WIDTH_PX = 360;
+const DEFAULT_VIEWPORT_PADDING_PX = 8;
+const DEFAULT_ANCHOR_GAP_PX = 6;
+const DEFAULT_MAX_HEIGHT_RATIO = 0.72;
+const DEFAULT_SIDE_PREFER_TRIGGER_LEFT_RATIO = 0.42;
+/** Assumed minimum panel height when clamping side placement into the viewport. */
+const SIDE_MIN_VISIBLE_HEIGHT_PX = 240;
+/** Prefer below when at least this many pixels are available under the trigger. */
+const BELOW_MIN_SPACE_PX = 12;
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max);
+}
+
+/**
+ * Measure a panel-sized overlay anchored to a trigger element.
+ * Prefers a side flyout when the trigger sits in the left portion of the
+ * viewport and there is room; otherwise places below or above.
+ */
+export function measureAnchoredOverlayPanel(
+  trigger: HTMLElement,
+  options: MeasureAnchoredOverlayPanelOptions = {},
+): AnchoredOverlayPanelRect {
+  const panelWidthPx = options.panelWidthPx ?? DEFAULT_PANEL_WIDTH_PX;
+  const viewportPaddingPx = options.viewportPaddingPx ?? DEFAULT_VIEWPORT_PADDING_PX;
+  const anchorGapPx = options.anchorGapPx ?? DEFAULT_ANCHOR_GAP_PX;
+  const maxHeightRatio = options.maxHeightRatio ?? DEFAULT_MAX_HEIGHT_RATIO;
+  const sidePreferTriggerLeftRatio =
+    options.sidePreferTriggerLeftRatio ?? DEFAULT_SIDE_PREFER_TRIGGER_LEFT_RATIO;
+
+  const viewportWidth = window.innerWidth;
+  const viewportHeight = window.innerHeight;
+  const triggerRect = trigger.getBoundingClientRect();
+
+  const maxHeight = Math.min(
+    viewportHeight * maxHeightRatio,
+    viewportHeight - viewportPaddingPx * 2,
+  );
+  const width = Math.min(panelWidthPx, viewportWidth - viewportPaddingPx * 2);
+
+  const spaceRight = Math.max(0, viewportWidth - triggerRect.right - viewportPaddingPx);
+  const spaceBelow = Math.max(0, viewportHeight - triggerRect.bottom - viewportPaddingPx);
+  const spaceAbove = Math.max(0, triggerRect.top - viewportPaddingPx);
+
+  const preferSide =
+    triggerRect.left < sidePreferTriggerLeftRatio * viewportWidth && spaceRight >= width;
+
+  if (preferSide) {
+    const minVisibleHeight = Math.min(SIDE_MIN_VISIBLE_HEIGHT_PX, maxHeight);
+    const top = clamp(
+      triggerRect.top,
+      viewportPaddingPx,
+      viewportHeight - viewportPaddingPx - minVisibleHeight,
+    );
+    return {
+      placement: 'side',
+      top,
+      left: triggerRect.right + anchorGapPx,
+      width,
+      maxHeight,
+    };
+  }
+
+  // Align the panel's right edge toward the trigger's right, then clamp.
+  const left = clamp(
+    triggerRect.right - width,
+    viewportPaddingPx,
+    viewportWidth - viewportPaddingPx - width,
+  );
+
+  if (spaceBelow >= BELOW_MIN_SPACE_PX || spaceBelow >= spaceAbove) {
+    return {
+      placement: 'below',
+      top: triggerRect.bottom + anchorGapPx,
+      left,
+      width,
+      maxHeight,
+    };
+  }
+
+  const aboveHeight = Math.min(maxHeight, spaceAbove);
+  return {
+    placement: 'above',
+    top: triggerRect.top - anchorGapPx - aboveHeight,
+    left,
+    width,
+    maxHeight,
+  };
+}

package/src/overlay/overlay.css

@@ -0,0 +1,2 @@
+/* Overlay surfaces */
+@import './context-menu.css';

package/src/overlay/pointerPassthroughRegion.ts

@@ -0,0 +1,83 @@
+export interface PointerPassthroughPort {
+  setPointerPassthrough(enabled: boolean): void | Promise<void>;
+}
+
+export interface PointerOverHitRegionOptions {
+  readonly hitSelectors: readonly string[];
+  readonly controlSelectors?: readonly string[];
+  readonly root?: HTMLElement | null;
+}
+
+/**
+ * Returns true when `target` matches any host-provided hit/control selector
+ * (and, when `root` is set, lies inside that root).
+ */
+export function isPointerOverHitRegion(
+  target: EventTarget | null,
+  options: PointerOverHitRegionOptions,
+): boolean {
+  if (!(target instanceof Element)) {
+    return false;
+  }
+
+  const root = options.root ?? null;
+  if (root !== null && !root.contains(target)) {
+    return false;
+  }
+
+  const selectors = [...options.hitSelectors, ...(options.controlSelectors ?? [])];
+  for (const selector of selectors) {
+    if (selector.length === 0) {
+      continue;
+    }
+    if (target.closest(selector) !== null) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export interface PointerPassthroughControllerOptions extends PointerOverHitRegionOptions {
+  readonly enabled: boolean;
+  readonly port: PointerPassthroughPort;
+}
+
+export interface PointerPassthroughController {
+  handlePointerTarget(target: EventTarget | null): void;
+  /** Force the next decision to notify the port even if unchanged. */
+  reset(): void;
+}
+
+/**
+ * Pure controller for overlay click-through: when the pointer is outside
+ * host-provided selectors, ask the port to enable passthrough.
+ * Pair with platform `applyWindowResidency(..., 'click-through')` on the main side.
+ */
+export function createPointerPassthroughController(
+  options: PointerPassthroughControllerOptions,
+): PointerPassthroughController {
+  let lastPassthrough: boolean | null = null;
+
+  return {
+    reset() {
+      lastPassthrough = null;
+    },
+    handlePointerTarget(target: EventTarget | null) {
+      if (!options.enabled) {
+        if (lastPassthrough !== false) {
+          lastPassthrough = false;
+          void options.port.setPointerPassthrough(false);
+        }
+        return;
+      }
+
+      const overHit = isPointerOverHitRegion(target, options);
+      const passthrough = !overHit;
+      if (passthrough === lastPassthrough) {
+        return;
+      }
+      lastPassthrough = passthrough;
+      void options.port.setPointerPassthrough(passthrough);
+    },
+  };
+}

package/src/overlay/useAnchoredOverlayPanel.ts

@@ -0,0 +1,222 @@
+import {
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type CSSProperties,
+  type RefCallback,
+  type RefObject,
+} from 'react';
+
+import {
+  isSearchableMultiSelectPortalTarget,
+  resolvePortalContainer,
+} from '../primitives/searchable-multi-select/overlay';
+import {
+  measureAnchoredOverlayPanel,
+  type MeasureAnchoredOverlayPanelOptions,
+} from './measureAnchoredOverlayPanel';
+
+export interface UseAnchoredOverlayPanelOptions {
+  readonly open: boolean;
+  readonly onOpenChange: (open: boolean) => void;
+  readonly triggerRef: RefObject<HTMLElement | null>;
+  readonly panelRef?: RefObject<HTMLElement | null>;
+  readonly measureOptions?: MeasureAnchoredOverlayPanelOptions;
+  /** Extra "inside" predicates (e.g. host markers). */
+  readonly isInsideExtra?: (target: EventTarget | null) => boolean;
+}
+
+export interface UseAnchoredOverlayPanelResult {
+  readonly style: CSSProperties | null;
+  readonly portalRoot: HTMLElement;
+  readonly panelProps: {
+    /** Always a callback ref so it composes with host `panelRef` and panel shells. */
+    ref: RefCallback<HTMLElement>;
+    tabIndex: number;
+    style: CSSProperties | null;
+  };
+}
+
+function assignRef<T>(
+  ref: RefObject<T | null> | RefCallback<T> | null | undefined,
+  value: T | null,
+): void {
+  if (typeof ref === 'function') {
+    ref(value);
+    return;
+  }
+  if (ref) {
+    (ref as { current: T | null }).current = value;
+  }
+}
+
+function isInsideCatalogFilterOverlay(target: EventTarget | null): boolean {
+  if (!(target instanceof Element)) {
+    return false;
+  }
+  return target.closest('[data-ui-catalog-filter-overlay]') !== null;
+}
+
+/**
+ * Host-neutral anchored overlay panel helper: trigger-relative placement,
+ * viewport clamping, dismiss lifecycle, remeasure on resize/scroll, and portal root.
+ *
+ * Pair with `CatalogFilterOverlay` (or a similar panel shell). Unlike
+ * `useFixedOverlayDismiss`, scroll and resize remeasure instead of closing.
+ */
+export function useAnchoredOverlayPanel({
+  open,
+  onOpenChange,
+  triggerRef,
+  panelRef: externalPanelRef,
+  measureOptions,
+  isInsideExtra,
+}: UseAnchoredOverlayPanelOptions): UseAnchoredOverlayPanelResult {
+  const internalPanelRef = useRef<HTMLElement | null>(null);
+  const [style, setStyle] = useState<CSSProperties | null>(null);
+  const didFocusOnOpenRef = useRef(false);
+
+  const setPanelNode = useCallback<RefCallback<HTMLElement>>(
+    (node) => {
+      internalPanelRef.current = node;
+      assignRef(externalPanelRef, node);
+    },
+    [externalPanelRef],
+  );
+
+  const remeasure = useCallback(() => {
+    const trigger = triggerRef.current;
+    if (!open || !trigger) {
+      setStyle(null);
+      return;
+    }
+
+    const rect = measureAnchoredOverlayPanel(trigger, measureOptions);
+    setStyle({
+      position: 'fixed',
+      top: rect.top,
+      left: rect.left,
+      width: rect.width,
+      maxHeight: rect.maxHeight,
+    });
+  }, [measureOptions, open, triggerRef]);
+
+  useLayoutEffect(() => {
+    remeasure();
+  }, [remeasure]);
+
+  useEffect(() => {
+    if (!open) {
+      didFocusOnOpenRef.current = false;
+      return;
+    }
+
+    const handleResize = () => {
+      remeasure();
+    };
+    const handleScroll = () => {
+      remeasure();
+    };
+
+    window.addEventListener('resize', handleResize);
+    window.addEventListener('scroll', handleScroll, true);
+
+    return () => {
+      window.removeEventListener('resize', handleResize);
+      window.removeEventListener('scroll', handleScroll, true);
+    };
+  }, [open, remeasure]);
+
+  useEffect(() => {
+    if (!open) {
+      return;
+    }
+
+    const isInside = (target: EventTarget | null): boolean => {
+      const trigger = triggerRef.current;
+      const panel = internalPanelRef.current;
+      if (trigger && target instanceof Node && trigger.contains(target)) {
+        return true;
+      }
+      if (panel && target instanceof Node && panel.contains(target)) {
+        return true;
+      }
+      if (isInsideCatalogFilterOverlay(target)) {
+        return true;
+      }
+      if (isSearchableMultiSelectPortalTarget(target)) {
+        return true;
+      }
+      if (isInsideExtra?.(target)) {
+        return true;
+      }
+      return false;
+    };
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== 'Escape') {
+        return;
+      }
+      if (event.defaultPrevented) {
+        return;
+      }
+      event.preventDefault();
+      onOpenChange(false);
+    };
+
+    const handlePointerDown = (event: PointerEvent) => {
+      if (event.defaultPrevented) {
+        return;
+      }
+      if (isInside(event.target)) {
+        return;
+      }
+      onOpenChange(false);
+    };
+
+    window.addEventListener('keydown', handleKeyDown);
+    window.addEventListener('pointerdown', handlePointerDown, true);
+
+    return () => {
+      window.removeEventListener('keydown', handleKeyDown);
+      window.removeEventListener('pointerdown', handlePointerDown, true);
+    };
+  }, [isInsideExtra, onOpenChange, open, triggerRef]);
+
+  useEffect(() => {
+    if (!open) {
+      return;
+    }
+    if (didFocusOnOpenRef.current) {
+      return;
+    }
+
+    const panel = internalPanelRef.current;
+    if (!panel) {
+      return;
+    }
+
+    const active = document.activeElement;
+    if (active instanceof Node && panel.contains(active)) {
+      didFocusOnOpenRef.current = true;
+      return;
+    }
+
+    panel.focus();
+    didFocusOnOpenRef.current = true;
+  }, [open, style]);
+
+  const portalRoot = resolvePortalContainer(triggerRef.current);
+
+  return {
+    style,
+    portalRoot,
+    panelProps: {
+      ref: setPanelNode,
+      tabIndex: -1,
+      style,
+    },
+  };
+}

package/src/overlay/useClampedFixedOverlayPosition.ts

@@ -0,0 +1,27 @@
+import { useEffect, useState, type RefObject } from 'react';
+import { clampFixedOverlayPosition } from './clampFixedOverlayPosition';
+
+export function useClampedFixedOverlayPosition(
+  containerRef: RefObject<HTMLElement | null>,
+  anchor: { x: number; y: number },
+  repositionKey: unknown,
+): { x: number; y: number } {
+  const [position, setPosition] = useState(anchor);
+
+  useEffect(() => {
+    setPosition(anchor);
+  }, [anchor.x, anchor.y]);
+
+  useEffect(() => {
+    const element = containerRef.current;
+    if (!element || typeof window === 'undefined') return;
+
+    const frame = window.requestAnimationFrame(() => {
+      setPosition(clampFixedOverlayPosition(anchor.x, anchor.y, element.getBoundingClientRect()));
+    });
+
+    return () => window.cancelAnimationFrame(frame);
+  }, [anchor.x, anchor.y, containerRef, repositionKey]);
+
+  return position;
+}

package/src/overlay/useContextMenuState.ts

@@ -0,0 +1,59 @@
+import { useCallback, useState } from 'react';
+
+export interface ContextMenuPointerState<T> {
+  readonly target: T;
+  readonly x: number;
+  readonly y: number;
+}
+
+/** Minimal pointer event shape accepted by `open` (React or DOM). */
+export interface ContextMenuPointerEvent {
+  readonly clientX: number;
+  readonly clientY: number;
+  preventDefault(): void;
+  stopPropagation(): void;
+}
+
+export interface UseContextMenuStateResult<T> {
+  readonly close: () => void;
+  readonly open: (event: ContextMenuPointerEvent, target: T) => void;
+  readonly openAt: (position: { readonly x: number; readonly y: number }, target: T) => void;
+  readonly state: ContextMenuPointerState<T> | null;
+}
+
+/**
+ * Host-owned context-menu pointer state (target + viewport coordinates).
+ * Does not build menu items or change selection — callers own those policies.
+ */
+export function useContextMenuState<T>(): UseContextMenuStateResult<T> {
+  const [state, setState] = useState<ContextMenuPointerState<T> | null>(null);
+
+  const close = useCallback(() => {
+    setState(null);
+  }, []);
+
+  const openAt = useCallback((position: { readonly x: number; readonly y: number }, target: T) => {
+    setState({
+      target,
+      x: position.x,
+      y: position.y,
+    });
+  }, []);
+
+  const open = useCallback((event: ContextMenuPointerEvent, target: T) => {
+    event.preventDefault();
+    event.stopPropagation();
+    setState({
+      target,
+      x: event.clientX,
+      y: event.clientY,
+    });
+  }, []);
+
+  return {
+    close,
+    open,
+    openAt,
+    state,
+  };
+}

package/src/overlay/useFixedOverlayDismiss.ts

@@ -0,0 +1,49 @@
+import { useEffect, type RefObject } from 'react';
+
+import { isSearchableMultiSelectPortalTarget } from '../primitives/searchable-multi-select/overlay';
+
+export interface FixedOverlayDismissOptions {
+  containerRef: RefObject<HTMLElement | null>;
+  onClose: () => void;
+  /** Return true when Escape was handled by nested UI (skip closing the root overlay). */
+  onEscape?: (() => boolean) | undefined;
+  /** When true, outside pointer events do not close the root overlay. */
+  ignoreOutsidePointer?: boolean | undefined;
+}
+
+export function useFixedOverlayDismiss({
+  containerRef,
+  onClose,
+  onEscape,
+  ignoreOutsidePointer = false,
+}: FixedOverlayDismissOptions): void {
+  useEffect(() => {
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== 'Escape') return;
+      if (onEscape?.()) return;
+
+      event.preventDefault();
+      onClose();
+    };
+
+    const handlePointerDown = (event: PointerEvent) => {
+      if (ignoreOutsidePointer) return;
+      if (containerRef.current?.contains(event.target as Node)) return;
+      // Portaled SMS listbox is not a DOM child of the overlay root.
+      if (isSearchableMultiSelectPortalTarget(event.target)) return;
+      onClose();
+    };
+
+    window.addEventListener('keydown', handleKeyDown);
+    window.addEventListener('pointerdown', handlePointerDown, true);
+    window.addEventListener('resize', onClose);
+    window.addEventListener('scroll', onClose, true);
+
+    return () => {
+      window.removeEventListener('keydown', handleKeyDown);
+      window.removeEventListener('pointerdown', handlePointerDown, true);
+      window.removeEventListener('resize', onClose);
+      window.removeEventListener('scroll', onClose, true);
+    };
+  }, [containerRef, ignoreOutsidePointer, onClose, onEscape]);
+}

package/src/overlay/usePointerPassthroughRegion.ts

@@ -0,0 +1,87 @@
+import { useEffect, useRef, type RefObject } from 'react';
+
+import {
+  createPointerPassthroughController,
+  type PointerPassthroughPort,
+} from './pointerPassthroughRegion';
+
+export interface UsePointerPassthroughRegionOptions {
+  readonly enabled: boolean;
+  readonly port: PointerPassthroughPort;
+  /** Host-provided CSS selectors for interactive hit regions. */
+  readonly hitSelectors: readonly string[];
+  /** Optional extra control chrome selectors (also treated as hit). */
+  readonly controlSelectors?: readonly string[];
+  /** Limit hit-testing to a subtree; defaults to the document. */
+  readonly rootRef?: RefObject<HTMLElement | null>;
+}
+
+/**
+ * Toggles host pointer passthrough from renderer hit-testing.
+ * Uses `requestAnimationFrame` coalescing for pointermove; no product selectors in kit.
+ *
+ * Host responsibilities:
+ * - Provide selector lists
+ * - Implement `port.setPointerPassthrough` (usually IPC → ignore-mouse-events)
+ * - Pair with platform residency applicator for the main-process half
+ */
+export function usePointerPassthroughRegion(options: UsePointerPassthroughRegionOptions): void {
+  const { enabled, port, hitSelectors, controlSelectors, rootRef } = options;
+
+  const portRef = useRef(port);
+  portRef.current = port;
+  const hitSelectorsRef = useRef(hitSelectors);
+  hitSelectorsRef.current = hitSelectors;
+  const controlSelectorsRef = useRef(controlSelectors);
+  controlSelectorsRef.current = controlSelectors;
+
+  useEffect(() => {
+    const controller = createPointerPassthroughController({
+      enabled,
+      port: {
+        setPointerPassthrough: (value) => portRef.current.setPointerPassthrough(value),
+      },
+      get hitSelectors() {
+        return hitSelectorsRef.current;
+      },
+      get controlSelectors() {
+        return controlSelectorsRef.current;
+      },
+      get root() {
+        return rootRef?.current ?? null;
+      },
+    });
+
+    if (!enabled) {
+      controller.handlePointerTarget(null);
+      return;
+    }
+
+    let frame = 0;
+    let pendingTarget: EventTarget | null = null;
+
+    const flush = () => {
+      frame = 0;
+      controller.handlePointerTarget(pendingTarget);
+    };
+
+    const onPointerMove = (event: PointerEvent) => {
+      pendingTarget = event.target;
+      if (frame !== 0) {
+        return;
+      }
+      frame = window.requestAnimationFrame(flush);
+    };
+
+    window.addEventListener('pointermove', onPointerMove, { passive: true });
+
+    return () => {
+      window.removeEventListener('pointermove', onPointerMove);
+      if (frame !== 0) {
+        window.cancelAnimationFrame(frame);
+      }
+      // Do not leave the host window stuck in click-through after unmount.
+      void portRef.current.setPointerPassthrough(false);
+    };
+  }, [enabled, rootRef]);
+}

package/src/primitives/{AbsoluteBox.tsx → absolute-box/AbsoluteBox.tsx}

@@ -1,5 +1,5 @@
 import type { CSSProperties, ReactNode } from 'react';
-import { cx } from '../utils/cx';
+import { cx } from '../../utils/cx';
 
 export interface WorkbenchRect {
   x: number;
@@ -9,12 +9,12 @@ export interface WorkbenchRect {
 }
 
 export interface AbsoluteBoxProps {
-  background?: string | undefined;
+  background?: string;
   children?: ReactNode;
-  className?: string | undefined;
-  overflow?: CSSProperties['overflow'] | undefined;
+  className?: string;
+  overflow?: CSSProperties['overflow'];
   rect: WorkbenchRect;
-  style?: CSSProperties | undefined;
+  style?: CSSProperties;
 }
 
 export function AbsoluteBox({

package/src/primitives/absolute-box/index.ts

@@ -0,0 +1 @@
+export * from './AbsoluteBox';

package/src/primitives/{Badge.tsx → badge/Badge.tsx}

@@ -1,9 +1,11 @@
-import type { ComponentPropsWithRef } from 'react';
-import { cx } from '../utils/cx';
+import './badge.css';
+import type { ComponentPropsWithRef, ReactNode } from 'react';
+import { cx } from '../../utils/cx';
 
 type BadgeVariant = 'accent' | 'muted' | 'danger';
 
 export interface BadgeProps extends ComponentPropsWithRef<'span'> {
+  children?: ReactNode;
   variant?: BadgeVariant;
 }
 

package/src/primitives/badge/badge.css

@@ -0,0 +1,20 @@
+.ui-badge {
+  padding: 1px 6px;
+  border-radius: var(--radius-sm);
+  font-size: 10px;
+  font-weight: 600;
+  line-height: 16px;
+  color: #fff;
+  background: var(--color-accent);
+}
+
+.ui-badge[data-variant='muted'] {
+  color: var(--color-text-muted);
+  background: var(--color-surface);
+  border: 1px solid var(--color-border);
+}
+
+.ui-badge[data-variant='danger'] {
+  color: #fff;
+  background: var(--color-danger);
+}