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

package/src/modal/useModalResize.ts

@@ -0,0 +1,122 @@
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  type Dispatch,
+  type PointerEvent as ReactPointerEvent,
+  type SetStateAction,
+} from 'react';
+import { applyModalResize } from './modalSize';
+import type { ModalContainerBounds } from './modalContainer';
+import type { ModalBounds, ModalResizeEdge } from './modalTypes';
+
+interface ModalResizeState {
+  edge: ModalResizeEdge;
+  pointerId: number;
+  startClientX: number;
+  startClientY: number;
+  startBounds: ModalBounds;
+}
+
+interface UseModalResizeOptions {
+  bounds: ModalBounds | null;
+  maximized: boolean;
+  minHeight: number;
+  minWidth: number;
+  setBounds: Dispatch<SetStateAction<ModalBounds | null>>;
+  viewport: ModalContainerBounds;
+}
+
+export function useModalResize({
+  bounds,
+  maximized,
+  minHeight,
+  minWidth,
+  setBounds,
+  viewport,
+}: UseModalResizeOptions) {
+  const resizeStateRef = useRef<ModalResizeState | null>(null);
+  const [resizing, setResizing] = useState(false);
+  const sizeConstraints = { minHeight, minWidth };
+
+  const stopResizing = useCallback(() => {
+    resizeStateRef.current = null;
+    setResizing(false);
+  }, []);
+
+  const handleResizeStart = useCallback(
+    (edge: ModalResizeEdge, event: ReactPointerEvent<HTMLDivElement>) => {
+      if (maximized || !bounds) {
+        return;
+      }
+
+      resizeStateRef.current = {
+        edge,
+        pointerId: event.pointerId,
+        startBounds: bounds,
+        startClientX: event.clientX,
+        startClientY: event.clientY,
+      };
+
+      if (typeof event.currentTarget.setPointerCapture === 'function') {
+        event.currentTarget.setPointerCapture(event.pointerId);
+      }
+      setResizing(true);
+    },
+    [bounds, maximized],
+  );
+
+  useEffect(() => {
+    if (!resizing) {
+      return undefined;
+    }
+
+    const previousUserSelect = document.body.style.userSelect;
+    document.body.style.userSelect = 'none';
+
+    const handlePointerMove = (event: PointerEvent) => {
+      const resizeState = resizeStateRef.current;
+      if (!resizeState || event.pointerId !== resizeState.pointerId) {
+        return;
+      }
+
+      event.preventDefault();
+      const nextBounds = applyModalResize(
+        resizeState.startBounds,
+        resizeState.edge,
+        event.clientX - resizeState.startClientX,
+        event.clientY - resizeState.startClientY,
+        sizeConstraints,
+        viewport,
+      );
+
+      setBounds(nextBounds);
+    };
+
+    const handlePointerUp = (event: PointerEvent) => {
+      const resizeState = resizeStateRef.current;
+      if (resizeState && event.pointerId !== resizeState.pointerId) {
+        return;
+      }
+
+      stopResizing();
+    };
+
+    window.addEventListener('pointermove', handlePointerMove, { passive: false });
+    window.addEventListener('pointerup', handlePointerUp);
+    window.addEventListener('pointercancel', handlePointerUp);
+
+    return () => {
+      document.body.style.userSelect = previousUserSelect;
+      window.removeEventListener('pointermove', handlePointerMove);
+      window.removeEventListener('pointerup', handlePointerUp);
+      window.removeEventListener('pointercancel', handlePointerUp);
+    };
+  }, [minHeight, minWidth, resizing, setBounds, stopResizing, viewport]);
+
+  return {
+    handleResizeStart,
+    stopResizing,
+  };
+}

package/src/modal/useModalWindowFrame.ts

@@ -0,0 +1,122 @@
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { readModalContainerBounds, resolveModalContainer } from './modalContainer';
+import { clampModalBoundsPosition } from './modalPosition';
+import { clampModalBounds, readCssModalDimension } from './modalSize';
+import type { ModalBounds } from './modalTypes';
+import { useModalContainerViewport } from './useModalContainerViewport';
+import { useModalDrag } from './useModalDrag';
+import { useModalResize } from './useModalResize';
+
+export interface UseModalWindowFrameOptions {
+  defaultMaximized: boolean;
+  defaultHeight?: number | undefined;
+  defaultWidth?: number | undefined;
+  minHeight: number;
+  minWidth: number;
+}
+
+export function useModalWindowFrame({
+  defaultHeight,
+  defaultMaximized,
+  defaultWidth,
+  minHeight,
+  minWidth,
+}: UseModalWindowFrameOptions) {
+  const frameRef = useRef<HTMLDivElement | HTMLFormElement | null>(null);
+  const restoredBoundsRef = useRef<ModalBounds | null>(null);
+  const [bounds, setBounds] = useState<ModalBounds | null>(null);
+  const [maximized, setMaximized] = useState(defaultMaximized);
+  const [frameVersion, setFrameVersion] = useState(0);
+
+  const assignFrameRef = useCallback((node: HTMLDivElement | HTMLFormElement | null) => {
+    frameRef.current = node;
+    setFrameVersion((current) => current + 1);
+  }, []);
+
+  const viewport = useModalContainerViewport(frameRef, frameVersion);
+  const isContained = resolveModalContainer(frameRef.current) !== null;
+
+  const { handleTitlebarPointerDown, stopDragging } = useModalDrag({
+    bounds,
+    maximized,
+    setBounds,
+    viewport,
+  });
+
+  const { handleResizeStart, stopResizing } = useModalResize({
+    bounds,
+    maximized,
+    minHeight,
+    minWidth,
+    setBounds,
+    viewport,
+  });
+
+  const resolveDefaultBounds = useCallback((): ModalBounds => {
+    const element = frameRef.current;
+    const width =
+      defaultWidth ?? (element ? readCssModalDimension(element, '--ui-modal-width', 640) : 640);
+    const height =
+      defaultHeight ?? (element ? readCssModalDimension(element, '--ui-modal-height', 480) : 480);
+    const container = resolveModalContainer(element);
+    const containerBounds = readModalContainerBounds(container);
+
+    const x = Math.max(0, (containerBounds.width - width) / 2);
+    const y = Math.max(0, (containerBounds.height - height) / 2);
+
+    return clampModalBounds({ x, y, width, height }, { minHeight, minWidth }, containerBounds);
+  }, [defaultHeight, defaultWidth, minHeight, minWidth]);
+
+  useLayoutEffect(() => {
+    if (bounds || maximized) {
+      return;
+    }
+
+    setBounds(resolveDefaultBounds());
+  }, [bounds, maximized, resolveDefaultBounds, frameVersion, viewport.height, viewport.width]);
+
+  useEffect(() => {
+    if (maximized) {
+      return undefined;
+    }
+
+    setBounds((current) => (current ? clampModalBoundsPosition(current, viewport) : current));
+  }, [maximized, viewport.height, viewport.width]);
+
+  const handleToggleMaximized = useCallback(() => {
+    if (maximized) {
+      setMaximized(false);
+      setBounds(restoredBoundsRef.current ?? resolveDefaultBounds());
+      restoredBoundsRef.current = null;
+    } else {
+      if (bounds) {
+        restoredBoundsRef.current = bounds;
+      }
+      setMaximized(true);
+    }
+
+    stopDragging();
+    stopResizing();
+  }, [bounds, maximized, resolveDefaultBounds, stopDragging, stopResizing]);
+
+  const windowStyle =
+    bounds && !maximized
+      ? {
+          height: `${bounds.height}px`,
+          left: `${bounds.x}px`,
+          top: `${bounds.y}px`,
+          width: `${bounds.width}px`,
+        }
+      : undefined;
+
+  return {
+    assignFrameRef,
+    bounds,
+    handleResizeStart,
+    handleTitlebarPointerDown,
+    handleToggleMaximized,
+    isContained,
+    maximized,
+    windowStyle,
+  };
+}

package/src/overlay/ContextMenu.tsx

@@ -1,6 +1,9 @@
-import { useEffect, useRef, useState, type ReactNode } from 'react';
+import { useEffect, useRef, type ReactNode } from 'react';
+import { Button } from '../primitives/button';
 import { cxCodicon } from '../utils/codicon';
 import { cx } from '../utils/cx';
+import { useClampedFixedOverlayPosition } from './useClampedFixedOverlayPosition';
+import { useFixedOverlayDismiss } from './useFixedOverlayDismiss';
 
 export type ContextMenuItem =
   | {
@@ -31,6 +34,16 @@ function itemKey(item: ContextMenuItem, index: number): string {
   return item.id ?? `${item.type ?? 'item'}-${index}`;
 }
 
+function menuHasIcons(items: ContextMenuItem[]): boolean {
+  return items.some((item) => item.type !== 'separator' && Boolean(item.icon));
+}
+
+function menuHasShortcuts(items: ContextMenuItem[]): boolean {
+  return items.some(
+    (item) => item.type !== 'separator' && item.shortcut != null && item.shortcut !== '',
+  );
+}
+
 export function ContextMenu({
   ariaLabel = 'Context menu',
   className,
@@ -40,40 +53,13 @@ export function ContextMenu({
   onClose,
 }: ContextMenuProps) {
   const ref = useRef<HTMLDivElement>(null);
-  const [position, setPosition] = useState({ x, y });
-
-  useEffect(() => {
-    setPosition({ x, y });
-  }, [x, y]);
-
-  useEffect(() => {
-    const menu = ref.current;
-    if (!menu || typeof window === 'undefined') return;
-
-    const frame = window.requestAnimationFrame(() => {
-      const rect = menu.getBoundingClientRect();
-      setPosition({
-        x: Math.max(4, Math.min(x, window.innerWidth - rect.width - 4)),
-        y: Math.max(4, Math.min(y, window.innerHeight - rect.height - 4)),
-      });
-    });
+  const position = useClampedFixedOverlayPosition(ref, { x, y }, items.length);
+  const hasIcons = menuHasIcons(items);
+  const hasShortcuts = menuHasShortcuts(items);
 
-    return () => window.cancelAnimationFrame(frame);
-  }, [items.length, x, y]);
+  useFixedOverlayDismiss({ containerRef: ref, onClose });
 
   useEffect(() => {
-    const handleKeyDown = (event: KeyboardEvent) => {
-      if (event.key === 'Escape') {
-        event.preventDefault();
-        onClose();
-      }
-    };
-
-    const handlePointerDown = (event: PointerEvent) => {
-      if (ref.current?.contains(event.target as Node)) return;
-      onClose();
-    };
-
     const handleContextMenu = (event: MouseEvent) => {
       if (ref.current?.contains(event.target as Node)) {
         event.preventDefault();
@@ -82,19 +68,8 @@ export function ContextMenu({
       onClose();
     };
 
-    window.addEventListener('keydown', handleKeyDown);
-    window.addEventListener('pointerdown', handlePointerDown, true);
     window.addEventListener('contextmenu', handleContextMenu, true);
-    window.addEventListener('resize', onClose);
-    window.addEventListener('scroll', onClose, true);
-
-    return () => {
-      window.removeEventListener('keydown', handleKeyDown);
-      window.removeEventListener('pointerdown', handlePointerDown, true);
-      window.removeEventListener('contextmenu', handleContextMenu, true);
-      window.removeEventListener('resize', onClose);
-      window.removeEventListener('scroll', onClose, true);
-    };
+    return () => window.removeEventListener('contextmenu', handleContextMenu, true);
   }, [onClose]);
 
   useEffect(() => {
@@ -108,6 +83,8 @@ export function ContextMenu({
       ref={ref}
       aria-label={ariaLabel}
       className={cx('ui-context-menu', className)}
+      data-has-icons={hasIcons ? 'true' : 'false'}
+      data-has-shortcuts={hasShortcuts ? 'true' : 'false'}
       role="menu"
       style={{
         left: position.x,
@@ -119,26 +96,27 @@ export function ContextMenu({
         item.type === 'separator' ? (
           <div key={itemKey(item, index)} className="ui-context-menu__separator" role="separator" />
         ) : (
-          <button
+          <Button
             key={itemKey(item, index)}
             className="ui-context-menu__item"
             data-danger={item.danger ? 'true' : undefined}
             disabled={item.disabled}
             role="menuitem"
-            type="button"
             onClick={() => {
               item.onSelect();
               onClose();
             }}
           >
-            <span className="ui-context-menu__icon">
-              {item.icon ? <i className={cxCodicon(item.icon)} /> : null}
-            </span>
+            {hasIcons ? (
+              <span className="ui-context-menu__icon" aria-hidden="true">
+                {item.icon ? <i className={cxCodicon(item.icon)} /> : null}
+              </span>
+            ) : null}
             <span className="ui-context-menu__label">{item.label}</span>
             {item.shortcut ? (
               <span className="ui-context-menu__shortcut">{item.shortcut}</span>
             ) : null}
-          </button>
+          </Button>
         ),
       )}
     </div>

package/src/overlay/clampFixedOverlayPosition.ts

@@ -0,0 +1,22 @@
+const OVERLAY_VIEWPORT_PADDING = 4;
+
+export function clampFixedOverlayPosition(
+  x: number,
+  y: number,
+  rect: Pick<DOMRect, 'width' | 'height'>,
+): { x: number; y: number } {
+  if (typeof window === 'undefined') {
+    return { x, y };
+  }
+
+  return {
+    x: Math.max(
+      OVERLAY_VIEWPORT_PADDING,
+      Math.min(x, window.innerWidth - rect.width - OVERLAY_VIEWPORT_PADDING),
+    ),
+    y: Math.max(
+      OVERLAY_VIEWPORT_PADDING,
+      Math.min(y, window.innerHeight - rect.height - OVERLAY_VIEWPORT_PADDING),
+    ),
+  };
+}

package/src/overlay/context-menu.css

@@ -0,0 +1,127 @@
+.ui-context-menu {
+  position: fixed;
+  z-index: var(--ui-context-menu-z-index, 260);
+  /* Hug content so short labels do not leave a wide empty hover strip. */
+  width: max-content;
+  min-width: 128px;
+  max-width: 300px;
+  /* Flush items to the frame so hover fills edge-to-edge. */
+  padding: 0;
+  color: var(--color-text);
+  background: var(--color-surface);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-sm);
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.35);
+  overflow: hidden;
+}
+
+.ui-context-menu__item {
+  --ui-button-width: 100%;
+  --ui-button-min-height: var(--workbench-context-menu-item-height);
+  --ui-button-height: auto;
+  --ui-button-display: grid;
+  /* Default: label only. Icon/shortcut columns are opt-in via data attrs. */
+  --ui-button-grid-template-columns: minmax(0, 1fr);
+  --ui-button-align-items: center;
+  --ui-button-justify-content: stretch;
+  --ui-button-gap: 7px;
+  --ui-button-padding: 0 10px;
+  --ui-button-border: 0;
+  --ui-button-border-radius: 0;
+  --ui-button-color: var(--color-text-muted);
+  --ui-button-background: transparent;
+  --ui-button-font-family: inherit;
+  --ui-button-font-size: var(--font-size-sm);
+  --ui-button-font-weight: 400;
+  --ui-button-text-align: left;
+  --ui-button-hover-color: var(--color-text);
+  --ui-button-hover-background: var(--color-surface-hover);
+  --ui-button-disabled-color: var(--color-text-subtle);
+  --ui-button-disabled-background: transparent;
+  box-sizing: border-box;
+  width: 100%;
+  min-height: var(--workbench-context-menu-item-height);
+  display: grid;
+  grid-template-columns: minmax(0, 1fr);
+  align-items: center;
+  gap: 7px;
+  padding: 0 10px;
+  border: 0;
+  border-radius: 0;
+  color: var(--color-text-muted);
+  background: transparent;
+  font-family: inherit;
+  font-size: var(--font-size-sm);
+  text-align: left;
+  cursor: pointer;
+}
+
+.ui-context-menu[data-has-shortcuts='true'] .ui-context-menu__item {
+  --ui-button-grid-template-columns: minmax(0, 1fr) auto;
+  grid-template-columns: minmax(0, 1fr) auto;
+}
+
+.ui-context-menu[data-has-icons='true'] .ui-context-menu__item {
+  --ui-button-grid-template-columns: 20px minmax(0, 1fr);
+  grid-template-columns: 20px minmax(0, 1fr);
+}
+
+.ui-context-menu[data-has-icons='true'][data-has-shortcuts='true'] .ui-context-menu__item {
+  --ui-button-grid-template-columns: 20px minmax(0, 1fr) auto;
+  grid-template-columns: 20px minmax(0, 1fr) auto;
+}
+
+.ui-context-menu__item:hover,
+.ui-context-menu__item:focus-visible {
+  color: var(--color-text);
+  background: var(--color-surface-hover);
+  outline: none;
+}
+
+.ui-context-menu__item:disabled {
+  color: var(--color-text-subtle);
+  background: transparent;
+  cursor: default;
+}
+
+.ui-context-menu__item[data-danger='true'] {
+  --ui-button-color: var(--color-danger);
+  --ui-button-hover-color: #fff;
+  --ui-button-hover-background: var(--color-danger);
+  color: var(--color-danger);
+}
+
+.ui-context-menu__item[data-danger='true']:hover,
+.ui-context-menu__item[data-danger='true']:focus-visible {
+  color: #fff;
+  background: var(--color-danger);
+}
+
+.ui-context-menu__icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  color: inherit;
+}
+
+.ui-context-menu__icon .codicon {
+  font-size: 14px;
+}
+
+.ui-context-menu__label {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.ui-context-menu__shortcut {
+  color: var(--color-text-subtle);
+  font-size: 11px;
+}
+
+.ui-context-menu__separator {
+  height: 1px;
+  margin: 4px 0;
+  background: var(--color-border);
+}

package/src/overlay/index.ts

@@ -0,0 +1,31 @@
+export { ContextMenu } from './ContextMenu';
+export type { ContextMenuItem, ContextMenuProps } from './ContextMenu';
+export { measureAnchoredOverlayPanel } from './measureAnchoredOverlayPanel';
+export type {
+  AnchoredOverlayPanelRect,
+  AnchoredOverlayPlacement,
+  MeasureAnchoredOverlayPanelOptions,
+} from './measureAnchoredOverlayPanel';
+export { useAnchoredOverlayPanel } from './useAnchoredOverlayPanel';
+export type {
+  UseAnchoredOverlayPanelOptions,
+  UseAnchoredOverlayPanelResult,
+} from './useAnchoredOverlayPanel';
+export { useContextMenuState } from './useContextMenuState';
+export type {
+  ContextMenuPointerEvent,
+  ContextMenuPointerState,
+  UseContextMenuStateResult,
+} from './useContextMenuState';
+export {
+  createPointerPassthroughController,
+  isPointerOverHitRegion,
+} from './pointerPassthroughRegion';
+export type {
+  PointerOverHitRegionOptions,
+  PointerPassthroughController,
+  PointerPassthroughControllerOptions,
+  PointerPassthroughPort,
+} from './pointerPassthroughRegion';
+export { usePointerPassthroughRegion } from './usePointerPassthroughRegion';
+export type { UsePointerPassthroughRegionOptions } from './usePointerPassthroughRegion';

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';