@workbench-kit/react 0.0.2-prototype.0.2.4 → 0.0.2-prototype.0.2.40

package/src/modal/useModalFocusTrap.ts

@@ -0,0 +1,142 @@
+import { useEffect, type RefObject } from 'react';
+
+const FOCUSABLE_SELECTOR = [
+  'a[href]',
+  'button:not([disabled])',
+  'textarea:not([disabled])',
+  'input:not([disabled]):not([type="hidden"])',
+  'select:not([disabled])',
+  '[tabindex]:not([tabindex="-1"])',
+].join(',');
+
+function isFocusable(element: HTMLElement): boolean {
+  if (element.hasAttribute('disabled') || element.getAttribute('aria-disabled') === 'true') {
+    return false;
+  }
+  if (element.getAttribute('aria-hidden') === 'true') {
+    return false;
+  }
+  // Explicit tabindex="-1" removes the node from the tab order.
+  // Do not use element.tabIndex >= 0: jsdom reports -1 for native buttons.
+  if (element.getAttribute('tabindex') === '-1') {
+    return false;
+  }
+  const style = window.getComputedStyle(element);
+  return style.display !== 'none' && style.visibility !== 'hidden';
+}
+
+function listFocusable(container: HTMLElement): HTMLElement[] {
+  return Array.from(container.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)).filter(
+    isFocusable,
+  );
+}
+
+export interface UseModalFocusTrapOptions {
+  readonly closeOnEscape?: boolean;
+  readonly containerRef: RefObject<HTMLElement | null>;
+  /** When false, skip trap/restore (for dialogs that stay mounted while closed). Default true. */
+  readonly enabled?: boolean;
+  readonly initialFocusRef?: RefObject<HTMLElement | null>;
+  readonly onClose: () => void;
+  readonly restoreFocusOnClose?: boolean;
+}
+
+/**
+ * Trap Tab focus inside a mounted modal dialog and restore focus on unmount.
+ * Escape dismisses when `closeOnEscape` is true (default).
+ */
+export function useModalFocusTrap({
+  closeOnEscape = true,
+  containerRef,
+  enabled = true,
+  initialFocusRef,
+  onClose,
+  restoreFocusOnClose = true,
+}: UseModalFocusTrapOptions): void {
+  useEffect(() => {
+    if (!enabled) {
+      return;
+    }
+
+    const previousFocus =
+      document.activeElement instanceof HTMLElement ? document.activeElement : null;
+
+    const focusInitial = () => {
+      const container = containerRef.current;
+      if (!container) {
+        return;
+      }
+
+      const preferred = initialFocusRef?.current;
+      if (preferred && container.contains(preferred)) {
+        preferred.focus();
+        return;
+      }
+
+      const focusables = listFocusable(container);
+      if (focusables[0]) {
+        focusables[0].focus();
+        return;
+      }
+
+      if (!container.hasAttribute('tabindex')) {
+        container.tabIndex = -1;
+      }
+      container.focus();
+    };
+
+    const frame = window.requestAnimationFrame(focusInitial);
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape' && closeOnEscape) {
+        event.preventDefault();
+        event.stopPropagation();
+        onClose();
+        return;
+      }
+
+      if (event.key !== 'Tab') {
+        return;
+      }
+
+      const container = containerRef.current;
+      if (!container) {
+        return;
+      }
+
+      const focusables = listFocusable(container);
+      if (focusables.length === 0) {
+        event.preventDefault();
+        container.focus();
+        return;
+      }
+
+      const first = focusables[0]!;
+      const last = focusables[focusables.length - 1]!;
+      const active = document.activeElement;
+
+      if (event.shiftKey) {
+        if (active === first || !container.contains(active)) {
+          event.preventDefault();
+          last.focus();
+        }
+        return;
+      }
+
+      if (active === last || !container.contains(active)) {
+        event.preventDefault();
+        first.focus();
+      }
+    };
+
+    window.addEventListener('keydown', handleKeyDown, true);
+
+    return () => {
+      window.cancelAnimationFrame(frame);
+      window.removeEventListener('keydown', handleKeyDown, true);
+      if (restoreFocusOnClose && previousFocus?.isConnected) {
+        previousFocus.focus();
+      }
+    };
+  }, [closeOnEscape, containerRef, enabled, initialFocusRef, onClose, restoreFocusOnClose]);
+}

package/src/modal/useModalWindowFrame.ts

@@ -9,8 +9,8 @@ import { useModalResize } from './useModalResize';
 
 export interface UseModalWindowFrameOptions {
   defaultMaximized: boolean;
-  defaultHeight?: number | undefined;
-  defaultWidth?: number | undefined;
+  defaultHeight?: number;
+  defaultWidth?: number;
   minHeight: number;
   minWidth: number;
 }

package/src/overlay/ContextMenu.tsx

@@ -1,30 +1,20 @@
-import { useEffect, useRef, type ReactNode } from 'react';
+import './context-menu.css';
+import { useCallback, useEffect, useMemo, useRef, useState, type KeyboardEvent } from 'react';
 import { Button } from '../primitives/button';
 import { cxCodicon } from '../utils/codicon';
 import { cx } from '../utils/cx';
+import type { ContextMenuItem } from './context-menu-item';
 import { useClampedFixedOverlayPosition } from './useClampedFixedOverlayPosition';
 import { useFixedOverlayDismiss } from './useFixedOverlayDismiss';
 
-export type ContextMenuItem =
-  | {
-      type: 'separator';
-      id?: string | undefined;
-    }
-  | {
-      type?: 'item';
-      id?: string | undefined;
-      label: ReactNode;
-      icon?: string | undefined;
-      shortcut?: ReactNode | undefined;
-      disabled?: boolean | undefined;
-      danger?: boolean | undefined;
-      onSelect: () => void;
-    };
+export type { ContextMenuItem } from './context-menu-item';
 
 export interface ContextMenuProps {
   ariaLabel?: string | undefined;
   className?: string | undefined;
   items: ContextMenuItem[];
+  /** Explicit focus target restored only when Escape dismisses the menu. */
+  returnFocusTarget?: HTMLElement | null | undefined;
   x: number;
   y: number;
   onClose: () => void;
@@ -44,20 +34,78 @@ function menuHasShortcuts(items: ContextMenuItem[]): boolean {
   );
 }
 
+function isEnabledMenuItem(
+  item: ContextMenuItem,
+): item is Extract<ContextMenuItem, { onSelect: () => void }> {
+  return item.type !== 'separator' && !item.disabled;
+}
+
+function getEnabledItemIndexes(items: readonly ContextMenuItem[]): number[] {
+  return items.reduce<number[]>((indexes, item, index) => {
+    if (isEnabledMenuItem(item)) {
+      indexes.push(index);
+    }
+    return indexes;
+  }, []);
+}
+
+function stepEnabledIndex(
+  enabledIndexes: readonly number[],
+  currentIndex: number,
+  direction: 1 | -1,
+): number {
+  if (enabledIndexes.length === 0) {
+    return -1;
+  }
+
+  const position = enabledIndexes.indexOf(currentIndex);
+  if (position < 0) {
+    return direction === 1 ? enabledIndexes[0]! : enabledIndexes[enabledIndexes.length - 1]!;
+  }
+
+  const nextPosition = (position + direction + enabledIndexes.length) % enabledIndexes.length;
+  return enabledIndexes[nextPosition]!;
+}
+
+/**
+ * WAI-ARIA menu keyboard model (no nested submenus in this slice):
+ * - ArrowUp/ArrowDown move highlight (skip disabled + separators)
+ * - Home/End jump to first/last enabled item
+ * - Enter/Space activate the highlighted item
+ * - Escape closes via {@link useFixedOverlayDismiss}
+ * - Roving tabindex: only the highlighted enabled item is tabIndex=0
+ */
 export function ContextMenu({
   ariaLabel = 'Context menu',
   className,
   items,
+  returnFocusTarget,
   x,
   y,
   onClose,
 }: ContextMenuProps) {
   const ref = useRef<HTMLDivElement>(null);
+  const [fallbackReturnFocusTarget] = useState<HTMLElement | null>(() => {
+    if (typeof document === 'undefined') {
+      return null;
+    }
+    return document.activeElement instanceof HTMLElement ? document.activeElement : null;
+  });
   const position = useClampedFixedOverlayPosition(ref, { x, y }, items.length);
   const hasIcons = menuHasIcons(items);
   const hasShortcuts = menuHasShortcuts(items);
+  const enabledIndexes = useMemo(() => getEnabledItemIndexes(items), [items]);
+  const [highlightedIndex, setHighlightedIndex] = useState(() => enabledIndexes[0] ?? -1);
 
-  useFixedOverlayDismiss({ containerRef: ref, onClose });
+  const restoreFocusOnEscape = useCallback(() => {
+    const target = returnFocusTarget ?? fallbackReturnFocusTarget;
+    if (target?.isConnected) {
+      target.focus();
+    }
+    return false;
+  }, [fallbackReturnFocusTarget, returnFocusTarget]);
+
+  useFixedOverlayDismiss({ containerRef: ref, onClose, onEscape: restoreFocusOnEscape });
 
   useEffect(() => {
     const handleContextMenu = (event: MouseEvent) => {
@@ -73,8 +121,64 @@ export function ContextMenu({
   }, [onClose]);
 
   useEffect(() => {
-    ref.current?.querySelector<HTMLButtonElement>('.ui-context-menu__item:not(:disabled)')?.focus();
-  }, []);
+    setHighlightedIndex((current) =>
+      enabledIndexes.includes(current) ? current : (enabledIndexes[0] ?? -1),
+    );
+  }, [enabledIndexes]);
+
+  useEffect(() => {
+    if (highlightedIndex < 0) {
+      return;
+    }
+
+    const item = ref.current?.querySelector<HTMLButtonElement>(
+      `[data-menu-index="${highlightedIndex}"]`,
+    );
+    item?.focus();
+  }, [highlightedIndex]);
+
+  const activateIndex = (index: number) => {
+    const item = items[index];
+    if (!item || !isEnabledMenuItem(item)) {
+      return;
+    }
+    item.onSelect();
+    onClose();
+  };
+
+  const handleMenuKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
+    if (event.key === 'ArrowDown') {
+      event.preventDefault();
+      setHighlightedIndex((current) => stepEnabledIndex(enabledIndexes, current, 1));
+      return;
+    }
+
+    if (event.key === 'ArrowUp') {
+      event.preventDefault();
+      setHighlightedIndex((current) => stepEnabledIndex(enabledIndexes, current, -1));
+      return;
+    }
+
+    if (event.key === 'Home') {
+      event.preventDefault();
+      setHighlightedIndex(enabledIndexes[0] ?? -1);
+      return;
+    }
+
+    if (event.key === 'End') {
+      event.preventDefault();
+      setHighlightedIndex(enabledIndexes[enabledIndexes.length - 1] ?? -1);
+      return;
+    }
+
+    if (event.key === 'Enter' || event.key === ' ') {
+      if (highlightedIndex < 0) {
+        return;
+      }
+      event.preventDefault();
+      activateIndex(highlightedIndex);
+    }
+  };
 
   if (items.length === 0) return null;
 
@@ -91,6 +195,7 @@ export function ContextMenu({
         top: position.y,
       }}
       onContextMenu={(event) => event.preventDefault()}
+      onKeyDown={handleMenuKeyDown}
     >
       {items.map((item, index) =>
         item.type === 'separator' ? (
@@ -100,11 +205,18 @@ export function ContextMenu({
             key={itemKey(item, index)}
             className="ui-context-menu__item"
             data-danger={item.danger ? 'true' : undefined}
+            data-highlighted={highlightedIndex === index ? 'true' : undefined}
+            data-menu-index={index}
             disabled={item.disabled}
             role="menuitem"
+            tabIndex={highlightedIndex === index ? 0 : -1}
             onClick={() => {
-              item.onSelect();
-              onClose();
+              activateIndex(index);
+            }}
+            onMouseEnter={() => {
+              if (!item.disabled) {
+                setHighlightedIndex(index);
+              }
             }}
           >
             {hasIcons ? (

package/src/overlay/context-menu-density.css

@@ -0,0 +1,22 @@
+/* Compact density overrides for ContextMenu. Keep before context-menu.css. */
+
+.ui-context-menu__item,
+.ui-context-menu__item.ui-button {
+  --ui-button-min-height: 28px;
+  --ui-button-height: auto;
+  --ui-button-padding: 4px 10px;
+  --ui-button-border-radius: 0;
+  border-radius: 0;
+  min-height: 28px;
+  height: auto;
+  padding: 4px 10px;
+}
+
+.ui-context-menu__separator {
+  margin: 0;
+}
+
+.ui-context-menu__shortcut {
+  font-size: var(--font-size-xs);
+  color: var(--color-text-subtle);
+}

package/src/overlay/context-menu-item.ts

@@ -0,0 +1,17 @@
+import type { ReactNode } from 'react';
+
+export type ContextMenuItem =
+  | {
+      type: 'separator';
+      id?: string | undefined;
+    }
+  | {
+      type?: 'item';
+      id?: string | undefined;
+      label: ReactNode;
+      icon?: string | undefined;
+      shortcut?: ReactNode | undefined;
+      disabled?: boolean | undefined;
+      danger?: boolean | undefined;
+      onSelect: () => void;
+    };

package/src/overlay/context-menu.css

@@ -1,3 +1,5 @@
+@import './context-menu-density.css';
+
 .ui-context-menu {
   position: fixed;
   z-index: var(--ui-context-menu-z-index, 260);
@@ -72,7 +74,8 @@
 }
 
 .ui-context-menu__item:hover,
-.ui-context-menu__item:focus-visible {
+.ui-context-menu__item:focus-visible,
+.ui-context-menu__item[data-highlighted='true'] {
   color: var(--color-text);
   background: var(--color-surface-hover);
   outline: none;
@@ -92,7 +95,8 @@
 }
 
 .ui-context-menu__item[data-danger='true']:hover,
-.ui-context-menu__item[data-danger='true']:focus-visible {
+.ui-context-menu__item[data-danger='true']:focus-visible,
+.ui-context-menu__item[data-danger='true'][data-highlighted='true'] {
   color: #fff;
   background: var(--color-danger);
 }

package/src/overlay/index.ts

@@ -20,12 +20,17 @@ export type {
 export {
   createPointerPassthroughController,
   isPointerOverHitRegion,
+  resolvePointerHitTarget,
 } from './pointerPassthroughRegion';
 export type {
+  PointerHitTestDocument,
   PointerOverHitRegionOptions,
   PointerPassthroughController,
   PointerPassthroughControllerOptions,
   PointerPassthroughPort,
 } from './pointerPassthroughRegion';
 export { usePointerPassthroughRegion } from './usePointerPassthroughRegion';
-export type { UsePointerPassthroughRegionOptions } from './usePointerPassthroughRegion';
+export type {
+  PointerHitTargetResolver,
+  UsePointerPassthroughRegionOptions,
+} from './usePointerPassthroughRegion';

package/src/overlay/measureAnchoredOverlayPanel.ts

@@ -1,3 +1,5 @@
+import { clampNumber } from '../utils/clamp';
+
 export type AnchoredOverlayPlacement = 'side' | 'below' | 'above';
 
 export interface MeasureAnchoredOverlayPanelOptions {
@@ -26,10 +28,6 @@ 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
@@ -65,7 +63,7 @@ export function measureAnchoredOverlayPanel(
 
   if (preferSide) {
     const minVisibleHeight = Math.min(SIDE_MIN_VISIBLE_HEIGHT_PX, maxHeight);
-    const top = clamp(
+    const top = clampNumber(
       triggerRect.top,
       viewportPaddingPx,
       viewportHeight - viewportPaddingPx - minVisibleHeight,
@@ -80,7 +78,7 @@ export function measureAnchoredOverlayPanel(
   }
 
   // Align the panel's right edge toward the trigger's right, then clamp.
-  const left = clamp(
+  const left = clampNumber(
     triggerRect.right - width,
     viewportPaddingPx,
     viewportWidth - viewportPaddingPx - width,

package/src/overlay/pointerPassthroughRegion.ts

@@ -2,6 +2,22 @@ export interface PointerPassthroughPort {
   setPointerPassthrough(enabled: boolean): void | Promise<void>;
 }
 
+export interface PointerHitTestDocument {
+  elementFromPoint(x: number, y: number): Element | null;
+}
+
+/** Resolve the painted element at finite viewport coordinates. */
+export function resolvePointerHitTarget(
+  clientX: number,
+  clientY: number,
+  documentSurface: PointerHitTestDocument = document,
+): Element | null {
+  if (!Number.isFinite(clientX) || !Number.isFinite(clientY)) {
+    return null;
+  }
+  return documentSurface.elementFromPoint(clientX, clientY);
+}
+
 export interface PointerOverHitRegionOptions {
   readonly hitSelectors: readonly string[];
   readonly controlSelectors?: readonly string[];
@@ -51,7 +67,7 @@ export interface PointerPassthroughController {
 /**
  * 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.
+ * Pair with platform `applyWindowResidencyPolicy` on the main side.
  */
 export function createPointerPassthroughController(
   options: PointerPassthroughControllerOptions,

package/src/overlay/usePointerPassthroughRegion.ts

@@ -2,9 +2,12 @@ import { useEffect, useRef, type RefObject } from 'react';
 
 import {
   createPointerPassthroughController,
+  resolvePointerHitTarget,
   type PointerPassthroughPort,
 } from './pointerPassthroughRegion';
 
+export type PointerHitTargetResolver = (clientX: number, clientY: number) => EventTarget | null;
+
 export interface UsePointerPassthroughRegionOptions {
   readonly enabled: boolean;
   readonly port: PointerPassthroughPort;
@@ -14,11 +17,15 @@ export interface UsePointerPassthroughRegionOptions {
   readonly controlSelectors?: readonly string[];
   /** Limit hit-testing to a subtree; defaults to the document. */
   readonly rootRef?: RefObject<HTMLElement | null>;
+  /** Override painted-element resolution; defaults to `document.elementFromPoint`. */
+  readonly resolveHitTarget?: PointerHitTargetResolver;
 }
 
 /**
  * Toggles host pointer passthrough from renderer hit-testing.
- * Uses `requestAnimationFrame` coalescing for pointermove; no product selectors in kit.
+ * Uses `requestAnimationFrame` coalescing and painted-element hit-testing; no
+ * product selectors in kit. Electron can forward move events while ignoring
+ * mouse input, in which case `event.target` is not necessarily under the cursor.
  *
  * Host responsibilities:
  * - Provide selector lists
@@ -26,7 +33,7 @@ export interface UsePointerPassthroughRegionOptions {
  * - Pair with platform residency applicator for the main-process half
  */
 export function usePointerPassthroughRegion(options: UsePointerPassthroughRegionOptions): void {
-  const { enabled, port, hitSelectors, controlSelectors, rootRef } = options;
+  const { enabled, port, hitSelectors, controlSelectors, rootRef, resolveHitTarget } = options;
 
   const portRef = useRef(port);
   portRef.current = port;
@@ -34,6 +41,8 @@ export function usePointerPassthroughRegion(options: UsePointerPassthroughRegion
   hitSelectorsRef.current = hitSelectors;
   const controlSelectorsRef = useRef(controlSelectors);
   controlSelectorsRef.current = controlSelectors;
+  const resolveHitTargetRef = useRef(resolveHitTarget ?? resolvePointerHitTarget);
+  resolveHitTargetRef.current = resolveHitTarget ?? resolvePointerHitTarget;
 
   useEffect(() => {
     const controller = createPointerPassthroughController({
@@ -58,25 +67,45 @@ export function usePointerPassthroughRegion(options: UsePointerPassthroughRegion
     }
 
     let frame = 0;
-    let pendingTarget: EventTarget | null = null;
+    let pendingX = 0;
+    let pendingY = 0;
 
     const flush = () => {
       frame = 0;
-      controller.handlePointerTarget(pendingTarget);
+      // Re-assert on every frame. Host state may also change outside this hook;
+      // the main-process port should make same-value updates a no-op.
+      controller.reset();
+      controller.handlePointerTarget(resolveHitTargetRef.current(pendingX, pendingY));
     };
 
-    const onPointerMove = (event: PointerEvent) => {
-      pendingTarget = event.target;
+    const onPointerMove = (event: PointerEvent | MouseEvent) => {
+      pendingX = event.clientX;
+      pendingY = event.clientY;
       if (frame !== 0) {
         return;
       }
       frame = window.requestAnimationFrame(flush);
     };
 
+    const onMouseLeave = () => {
+      if (frame !== 0) {
+        window.cancelAnimationFrame(frame);
+        frame = 0;
+      }
+      controller.reset();
+      controller.handlePointerTarget(null);
+    };
+
     window.addEventListener('pointermove', onPointerMove, { passive: true });
+    // Some Electron builds forward mousemove rather than pointermove while the
+    // native window ignores input.
+    window.addEventListener('mousemove', onPointerMove, { passive: true });
+    document.documentElement.addEventListener('mouseleave', onMouseLeave);
 
     return () => {
       window.removeEventListener('pointermove', onPointerMove);
+      window.removeEventListener('mousemove', onPointerMove);
+      document.documentElement.removeEventListener('mouseleave', onMouseLeave);
       if (frame !== 0) {
         window.cancelAnimationFrame(frame);
       }

package/src/primitives/absolute-box/AbsoluteBox.tsx

@@ -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/app-icon/AppIcon.tsx

@@ -0,0 +1,33 @@
+import './app-icon.css';
+import type { ComponentPropsWithRef, ReactNode } from 'react';
+
+import { cx } from '../../utils/cx';
+
+export type AppIconSize = 'sm' | 'md' | 'lg';
+
+type AppIconBaseProps = Omit<ComponentPropsWithRef<'span'>, 'children'> & {
+  size?: AppIconSize;
+};
+
+type AppIconImageProps = {
+  /** Accessible image text. Use an empty string when the surrounding surface already names the app. */
+  alt: string;
+  children?: never;
+  src: string;
+};
+
+type AppIconCustomProps = {
+  alt?: never;
+  children: ReactNode;
+  src?: never;
+};
+
+export type AppIconProps = AppIconBaseProps & (AppIconImageProps | AppIconCustomProps);
+
+export function AppIcon({ alt, children, className, size = 'md', src, ...props }: AppIconProps) {
+  return (
+    <span className={cx('ui-app-icon', className)} data-size={size} {...props}>
+      {src === undefined ? children : <img alt={alt} className="ui-app-icon__image" src={src} />}
+    </span>
+  );
+}