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

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,4 +1,4 @@
-import { useEffect, useRef, type ReactNode } from 'react';
+import { useEffect, useMemo, useRef, useState, type KeyboardEvent, type ReactNode } from 'react';
 import { Button } from '../primitives/button';
 import { cxCodicon } from '../utils/codicon';
 import { cx } from '../utils/cx';
@@ -44,6 +44,47 @@ 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,
@@ -56,6 +97,8 @@ export function ContextMenu({
   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 });
 
@@ -73,8 +116,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 +190,7 @@ export function ContextMenu({
         top: position.y,
       }}
       onContextMenu={(event) => event.preventDefault()}
+      onKeyDown={handleMenuKeyDown}
     >
       {items.map((item, index) =>
         item.type === 'separator' ? (
@@ -100,11 +200,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.css

@@ -72,7 +72,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 +93,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/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/usePointerPassthroughRegion.ts

@@ -80,6 +80,8 @@ export function usePointerPassthroughRegion(options: UsePointerPassthroughRegion
       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/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/button/Button.tsx

@@ -6,10 +6,10 @@ import { cx } from '../../utils/cx';
 type ButtonVariant = 'default' | 'primary' | 'danger';
 
 export interface ButtonProps extends ComponentPropsWithRef<'button'> {
-  block?: boolean | undefined;
-  compact?: boolean | undefined;
-  icon?: string | undefined;
-  secondary?: boolean | undefined;
+  block?: boolean;
+  compact?: boolean;
+  icon?: string;
+  secondary?: boolean;
   variant?: ButtonVariant;
 }
 

package/src/primitives/catalog-browse-card/CatalogBrowseCard.tsx

@@ -11,9 +11,9 @@ export interface CatalogBrowseCardProps extends Omit<
   'children' | 'title'
 > {
   description?: ReactNode;
-  icon?: string | undefined;
-  imageAlt?: string | undefined;
-  imageUrl?: string | null | undefined;
+  icon?: string;
+  imageAlt?: string;
+  imageUrl?: string | null;
   label: ReactNode;
   /**
    * Custom media content for the icon/cover region. When set, replaces the
@@ -23,15 +23,15 @@ export interface CatalogBrowseCardProps extends Omit<
   /** Overlay content inside the media region (badges, status chips, etc.). */
   mediaOverlay?: ReactNode;
   meta?: ReactNode;
-  selected?: boolean | undefined;
+  selected?: boolean;
   /**
    * Secondary actions outside the primary hit target (for example Assign).
    * When set, the root becomes a non-button container and click/drag handlers
    * apply to the main control only.
    */
   trailing?: ReactNode;
-  tooltip?: string | undefined;
-  variant?: CatalogBrowseCardVariant | undefined;
+  tooltip?: string;
+  variant?: CatalogBrowseCardVariant;
 }
 
 export function CatalogBrowseCard({

package/src/primitives/catalog-browse-pane/CatalogBrowsePane.tsx

@@ -33,12 +33,12 @@ export type CatalogBrowseViewMode = 'grid' | 'list';
  * Hosts with richer cards should pass `renderGridItem` / `renderListItem`.
  */
 export interface CatalogBrowseItem {
-  readonly description?: string | null | undefined;
+  readonly description?: string | null;
   readonly id: string;
-  readonly imageAlt?: string | undefined;
-  readonly imageUrl?: string | null | undefined;
+  readonly imageAlt?: string;
+  readonly imageUrl?: string | null;
   readonly label: string;
-  readonly meta?: string | null | undefined;
+  readonly meta?: string | null;
 }
 
 export interface CatalogBrowseItemRenderState {
@@ -48,17 +48,17 @@ export interface CatalogBrowseItemRenderState {
 export interface CatalogBrowsePaneProps extends Omit<ComponentPropsWithRef<'div'>, 'children'> {
   readonly clearSearchLabel: string;
   readonly emptyMessage: string;
-  readonly errorMessage?: string | null | undefined;
+  readonly errorMessage?: string | null;
   /** Slot between search and sort/view controls (facet trigger, chips, etc.). */
   readonly facetStrip?: ReactNode;
-  readonly gridAriaLabel?: string | undefined;
+  readonly gridAriaLabel?: string;
   /** Visual label for the grid view-mode segment (string or icon node). */
   readonly gridLabel?: ReactNode;
   readonly hasMore: boolean;
   readonly isLoading: boolean;
   readonly isLoadingMore: boolean;
   readonly items: ReadonlyArray<CatalogBrowseItem>;
-  readonly listAriaLabel?: string | undefined;
+  readonly listAriaLabel?: string;
   /** Visual label for the list view-mode segment (string or icon node). */
   readonly listLabel?: ReactNode;
   readonly loadingMessage: string;
@@ -66,11 +66,11 @@ export interface CatalogBrowsePaneProps extends Omit<ComponentPropsWithRef<'div'
     ((itemId: string, itemLabel: string, event: ReactMouseEvent<HTMLElement>) => void) | undefined;
   readonly onLoadMore: () => void;
   readonly onOpenItem: (itemId: string) => void;
-  readonly onRefresh?: (() => void) | null | undefined;
+  readonly onRefresh?: (() => void) | null;
   readonly onSearchQueryChange: (query: string) => void;
-  readonly onSortChange?: ((sort: string) => void) | undefined;
+  readonly onSortChange?: (sort: string) => void;
   readonly onViewModeChange: (viewMode: CatalogBrowseViewMode) => void;
-  readonly refreshLabel?: string | null | undefined;
+  readonly refreshLabel?: string | null;
   readonly renderGridItem?:
     ((item: CatalogBrowseItem, state: CatalogBrowseItemRenderState) => ReactNode) | undefined;
   readonly renderListItem?:
@@ -78,14 +78,14 @@ export interface CatalogBrowsePaneProps extends Omit<ComponentPropsWithRef<'div'
   readonly searchAriaLabel: string;
   readonly searchPlaceholder: string;
   readonly searchQuery: string;
-  readonly selectedItemId?: string | null | undefined;
-  readonly sort?: string | undefined;
-  readonly sortAriaLabel?: string | undefined;
-  readonly sortOptions?: ReadonlyArray<{ label: string; value: string }> | undefined;
+  readonly selectedItemId?: string | null;
+  readonly sort?: string;
+  readonly sortAriaLabel?: string;
+  readonly sortOptions?: ReadonlyArray<{ label: string; value: string }>;
   /** Extra trailing controls after built-in sort / view mode (before refresh). */
   readonly toolbarTrailing?: ReactNode;
   readonly viewMode: CatalogBrowseViewMode;
-  readonly viewModeAriaLabel?: string | undefined;
+  readonly viewModeAriaLabel?: string;
 }
 
 export function CatalogBrowsePane({

package/src/primitives/catalog-filter-overlay/CatalogFilterOverlay.tsx

@@ -13,10 +13,10 @@ export interface CatalogFilterOverlayProps extends Omit<
    * When true, Clear stays mounted and sized but is not actionable.
    * Keeps the title row height stable across selection changes.
    */
-  readonly clearDisabled?: boolean | undefined;
+  readonly clearDisabled?: boolean;
   readonly clearLabel: string;
   readonly onClear: () => void;
-  readonly ref?: Ref<HTMLDivElement> | undefined;
+  readonly ref?: Ref<HTMLDivElement>;
   readonly title: ReactNode;
   readonly titleId: string;
 }

package/src/primitives/checkbox/Checkbox.tsx

@@ -3,7 +3,7 @@ import type { ChangeEvent, ComponentPropsWithRef, ReactNode } from 'react';
 import { cx } from '../../utils/cx';
 
 export interface CheckboxProps extends Omit<ComponentPropsWithRef<'input'>, 'type'> {
-  label?: ReactNode | undefined;
+  label?: ReactNode;
   onCheckedChange?: (checked: boolean, event: ChangeEvent<HTMLInputElement>) => void;
 }
 

package/src/primitives/chip/Chip.tsx

@@ -4,9 +4,9 @@ import { Button } from '../button';
 import { cx } from '../../utils/cx';
 
 export interface ChipProps extends Omit<ComponentPropsWithRef<'button'>, 'children'> {
-  count?: number | undefined;
+  count?: number;
   label: ReactNode;
-  onDismiss?: (() => void) | undefined;
+  onDismiss?: () => void;
 }
 
 /**

package/src/primitives/codicon/Codicon.tsx

@@ -4,7 +4,7 @@ import { cxCodicon } from '../../utils/codicon';
 export interface CodiconProps extends Omit<ComponentPropsWithRef<'i'>, 'children'> {
   icon: string;
   /** When set, exposes the icon to assistive tech instead of aria-hidden. */
-  label?: string | undefined;
+  label?: string;
 }
 
 /** VS Code codicon glyph (`codicon` font). Requires `@vscode/codicons` CSS in the app entry. Prefer `WorkbenchIcon` for new code. */

package/src/primitives/file-icon/FileIcon.tsx

@@ -6,7 +6,7 @@ export const UI_FILE_ICON_CLASS = 'ui-file-icon';
 
 export interface FileIconProps extends Omit<ComponentPropsWithRef<'i'>, 'children'> {
   icon: string;
-  kind?: FileIconKind | undefined;
+  kind?: FileIconKind;
 }
 
 export function FileIcon({ className, icon, kind, ...props }: FileIconProps) {

package/src/primitives/icon-button/IconButton.tsx

@@ -7,7 +7,7 @@ import { cx } from '../../utils/cx';
 type IconButtonVariant = 'default' | 'danger';
 
 export interface IconButtonProps extends Omit<ComponentPropsWithRef<'button'>, 'children'> {
-  compact?: boolean | undefined;
+  compact?: boolean;
   icon: WorkbenchIconInput;
   label: string;
   variant?: IconButtonVariant;

package/src/primitives/index.ts

@@ -110,6 +110,11 @@ export type {
   LibraryDetailLayoutMode,
   LibraryDetailLayoutProps,
 } from './library-detail-layout/LibraryDetailLayout';
+export { resolveLibraryDetailHeroCoverMedia } from './library-detail-layout/resolve-hero-cover-media.js';
+export type {
+  ResolveLibraryDetailHeroCoverMediaInput,
+  ResolvedLibraryDetailHeroCoverMedia,
+} from './library-detail-layout/resolve-hero-cover-media.js';
 export { ScrollAreaInfiniteSentinel } from './scroll-area-infinite-load/ScrollAreaInfiniteSentinel';
 export type { ScrollAreaInfiniteSentinelProps } from './scroll-area-infinite-load/ScrollAreaInfiniteSentinel';
 export { useScrollAreaInfiniteLoad } from './scroll-area-infinite-load/useScrollAreaInfiniteLoad';