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

package/src/layout/sidebar/SideBarTree.tsx

@@ -0,0 +1,301 @@
+import {
+  useCallback,
+  useMemo,
+  useState,
+  type KeyboardEvent,
+  type MouseEvent,
+  type ReactNode,
+} from 'react';
+import { cxCodicon } from '../../utils/codicon';
+import { cx } from '../../utils/cx';
+import { SideBarList, SideBarListItem } from './SideBarViewFrame';
+
+/**
+ * Controlled sidebar tree for library / provider category rows.
+ *
+ * Branch vs leaf: items with `children` (even empty) render as expandable branches;
+ * items without `children` are leaves. Hosts own expand/selection sets.
+ *
+ * Keyboard (default on): ArrowUp/Down move focus+selection (single mode) or focus
+ * (multi mode); ArrowRight expands / moves into first child; ArrowLeft collapses /
+ * moves to parent; Enter/Space activates selection. Virtualization and DnD are
+ * out of scope for v1.
+ */
+export interface SideBarTreeItem {
+  readonly id: string;
+  readonly label: ReactNode;
+  readonly children?: readonly SideBarTreeItem[];
+  readonly disabled?: boolean;
+  readonly icon?: ReactNode;
+}
+
+export type SideBarTreeSelectionMode = 'single' | 'multi';
+
+export interface SideBarTreeProps {
+  readonly items: readonly SideBarTreeItem[];
+  readonly expandedIds: ReadonlySet<string>;
+  readonly selectedIds: ReadonlySet<string>;
+  readonly onExpandedIdsChange: (next: Set<string>) => void;
+  readonly onSelectedIdsChange: (next: Set<string>) => void;
+  readonly selectionMode?: SideBarTreeSelectionMode;
+  /** When false, arrow / activation keys are not handled. Default true. */
+  readonly keyboardNavigation?: boolean;
+  readonly 'aria-label'?: string;
+  readonly className?: string;
+}
+
+export interface SideBarTreeVisibleNode {
+  readonly depth: number;
+  readonly item: SideBarTreeItem;
+  readonly parentId: string | null;
+  readonly hasChildren: boolean;
+}
+
+export function isSideBarTreeBranch(item: SideBarTreeItem): boolean {
+  return item.children !== undefined;
+}
+
+export function flattenVisibleSideBarTreeItems(
+  items: readonly SideBarTreeItem[],
+  expandedIds: ReadonlySet<string>,
+  depth = 0,
+  parentId: string | null = null,
+): SideBarTreeVisibleNode[] {
+  const rows: SideBarTreeVisibleNode[] = [];
+
+  for (const item of items) {
+    const hasChildren = isSideBarTreeBranch(item);
+    rows.push({ depth, item, parentId, hasChildren });
+
+    if (hasChildren && expandedIds.has(item.id) && item.children) {
+      rows.push(...flattenVisibleSideBarTreeItems(item.children, expandedIds, depth + 1, item.id));
+    }
+  }
+
+  return rows;
+}
+
+export function toggleSideBarTreeId(ids: ReadonlySet<string>, id: string): Set<string> {
+  const next = new Set(ids);
+  if (next.has(id)) {
+    next.delete(id);
+  } else {
+    next.add(id);
+  }
+  return next;
+}
+
+export function selectSideBarTreeIds(
+  current: ReadonlySet<string>,
+  id: string,
+  mode: SideBarTreeSelectionMode,
+  additive: boolean,
+): Set<string> {
+  if (mode === 'single' || !additive) {
+    return new Set([id]);
+  }
+  return toggleSideBarTreeId(current, id);
+}
+
+export function SideBarTree({
+  items,
+  expandedIds,
+  selectedIds,
+  onExpandedIdsChange,
+  onSelectedIdsChange,
+  selectionMode = 'single',
+  keyboardNavigation = true,
+  'aria-label': ariaLabel = 'Sidebar tree',
+  className,
+}: SideBarTreeProps) {
+  const visibleNodes = useMemo(
+    () => flattenVisibleSideBarTreeItems(items, expandedIds),
+    [expandedIds, items],
+  );
+
+  const [focusedId, setFocusedId] = useState<string | null>(null);
+
+  const focusIndex = useMemo(() => {
+    if (focusedId == null) {
+      return visibleNodes.length > 0 ? 0 : -1;
+    }
+    const index = visibleNodes.findIndex((node) => node.item.id === focusedId);
+    return index >= 0 ? index : visibleNodes.length > 0 ? 0 : -1;
+  }, [focusedId, visibleNodes]);
+
+  const toggleExpanded = useCallback(
+    (id: string) => {
+      onExpandedIdsChange(toggleSideBarTreeId(expandedIds, id));
+    },
+    [expandedIds, onExpandedIdsChange],
+  );
+
+  const selectItem = useCallback(
+    (id: string, additive: boolean) => {
+      onSelectedIdsChange(selectSideBarTreeIds(selectedIds, id, selectionMode, additive));
+      setFocusedId(id);
+    },
+    [onSelectedIdsChange, selectedIds, selectionMode],
+  );
+
+  const handleItemClick = useCallback(
+    (event: MouseEvent<HTMLButtonElement>, node: SideBarTreeVisibleNode) => {
+      if (node.item.disabled) {
+        return;
+      }
+
+      const additive = selectionMode === 'multi' && (event.metaKey || event.ctrlKey);
+      selectItem(node.item.id, additive);
+
+      if (node.hasChildren && !additive) {
+        toggleExpanded(node.item.id);
+      }
+    },
+    [selectItem, selectionMode, toggleExpanded],
+  );
+
+  const handleKeyDown = useCallback(
+    (event: KeyboardEvent<HTMLUListElement>) => {
+      if (!keyboardNavigation || visibleNodes.length === 0 || focusIndex < 0) {
+        return;
+      }
+
+      const current = visibleNodes[focusIndex];
+      if (!current) {
+        return;
+      }
+
+      if (event.key === 'ArrowDown') {
+        event.preventDefault();
+        const next = visibleNodes[Math.min(visibleNodes.length - 1, focusIndex + 1)];
+        if (!next || next.item.disabled) {
+          return;
+        }
+        setFocusedId(next.item.id);
+        if (selectionMode === 'single') {
+          onSelectedIdsChange(new Set([next.item.id]));
+        }
+        return;
+      }
+
+      if (event.key === 'ArrowUp') {
+        event.preventDefault();
+        const next = visibleNodes[Math.max(0, focusIndex - 1)];
+        if (!next || next.item.disabled) {
+          return;
+        }
+        setFocusedId(next.item.id);
+        if (selectionMode === 'single') {
+          onSelectedIdsChange(new Set([next.item.id]));
+        }
+        return;
+      }
+
+      if (event.key === 'ArrowRight') {
+        event.preventDefault();
+        if (!current.hasChildren || current.item.disabled) {
+          return;
+        }
+        if (!expandedIds.has(current.item.id)) {
+          toggleExpanded(current.item.id);
+          return;
+        }
+        const firstChild = current.item.children?.[0];
+        if (firstChild && !firstChild.disabled) {
+          setFocusedId(firstChild.id);
+          if (selectionMode === 'single') {
+            onSelectedIdsChange(new Set([firstChild.id]));
+          }
+        }
+        return;
+      }
+
+      if (event.key === 'ArrowLeft') {
+        event.preventDefault();
+        if (current.hasChildren && expandedIds.has(current.item.id)) {
+          toggleExpanded(current.item.id);
+          return;
+        }
+        if (current.parentId) {
+          setFocusedId(current.parentId);
+          if (selectionMode === 'single') {
+            onSelectedIdsChange(new Set([current.parentId]));
+          }
+        }
+        return;
+      }
+
+      if (event.key === 'Enter' || event.key === ' ') {
+        event.preventDefault();
+        if (current.item.disabled) {
+          return;
+        }
+        selectItem(current.item.id, selectionMode === 'multi' && (event.metaKey || event.ctrlKey));
+        if (current.hasChildren && selectionMode === 'single') {
+          toggleExpanded(current.item.id);
+        }
+      }
+    },
+    [
+      expandedIds,
+      focusIndex,
+      keyboardNavigation,
+      onSelectedIdsChange,
+      selectItem,
+      selectionMode,
+      toggleExpanded,
+      visibleNodes,
+    ],
+  );
+
+  return (
+    <SideBarList
+      aria-label={ariaLabel}
+      className={cx('ui-sidebar-tree', className)}
+      fill
+      role="tree"
+      onKeyDown={handleKeyDown}
+    >
+      {visibleNodes.map((node, index) => {
+        const { item, depth, hasChildren } = node;
+        const expanded = hasChildren && expandedIds.has(item.id);
+        const selected = selectedIds.has(item.id);
+        const focused = focusIndex === index;
+
+        return (
+          <SideBarListItem
+            key={item.id}
+            depth={depth}
+            disabled={item.disabled}
+            selected={selected}
+            tabIndex={focused ? 0 : -1}
+            wrapperProps={{
+              role: 'treeitem',
+              'aria-level': depth + 1,
+              'aria-selected': selected,
+              ...(hasChildren ? { 'aria-expanded': expanded } : {}),
+            }}
+            onClick={(event) => handleItemClick(event, node)}
+            onFocus={() => setFocusedId(item.id)}
+          >
+            <span className="workbench-tree-prefix">
+              {hasChildren ? (
+                <i
+                  aria-hidden="true"
+                  className={cxCodicon(
+                    expanded ? 'chevron-down' : 'chevron-right',
+                    'workbench-tree-chevron',
+                  )}
+                />
+              ) : (
+                <span className="workbench-tree-spacer" />
+              )}
+              {item.icon}
+            </span>
+            <span className="workbench-tree-label">{item.label}</span>
+          </SideBarListItem>
+        );
+      })}
+    </SideBarList>
+  );
+}

package/src/layout/sidebar/SidebarActionIconBar.tsx

@@ -12,14 +12,14 @@ import { IconButton } from '../../primitives/icon-button';
 
 import { cx } from '../../utils/cx';
 
-import { type ActivityBarOrientation } from '../../workbench/activityBarOrder';
+import { type ActivityBarOrientation } from '../../workbench/shell/activityBarOrder';
 
 import {
   mergeWorkbenchSidebarViewPlacementDropZoneProps,
   useWorkbenchSidebarViewPlacementDropZone,
-} from '../../workbench/useWorkbenchSidebarViewPlacementDropZone';
+} from '../../workbench/shell/useWorkbenchSidebarViewPlacementDropZone';
 
-import { useWorkbenchSidebarActionBarDnd } from '../../workbench/useWorkbenchSidebarActionBarDnd';
+import { useWorkbenchSidebarActionBarDnd } from '../../workbench/shell/useWorkbenchSidebarActionBarDnd';
 
 import { SidebarToolbar } from './SidebarToolbar';
 

package/src/layout/sidebar/WorkbenchSidebarActions.tsx

@@ -8,7 +8,7 @@ import {
   isWorkbenchStatusBusy,
   isWorkbenchStatusDisabled,
   type WorkbenchStatus,
-} from '../../workbench/status';
+} from '../../workbench/shell/status';
 import {
   SideBarList,
   SideBarListItem,

package/src/layout/sidebar/index.ts

@@ -17,6 +17,19 @@ export type {
   SideBarScrollSpacerProps,
   SideBarViewFrameProps,
 } from './SideBarViewFrame';
+export {
+  SideBarTree,
+  flattenVisibleSideBarTreeItems,
+  isSideBarTreeBranch,
+  selectSideBarTreeIds,
+  toggleSideBarTreeId,
+} from './SideBarTree';
+export type {
+  SideBarTreeItem,
+  SideBarTreeProps,
+  SideBarTreeSelectionMode,
+  SideBarTreeVisibleNode,
+} from './SideBarTree';
 export { SidebarActionIconBar } from './SidebarActionIconBar';
 export { SidebarSlotChrome } from './SidebarSlotChrome';
 export type { SidebarSlotChromeProps } from './SidebarSlotChrome';

package/src/modal/Modal.tsx

@@ -1,18 +1,22 @@
 import {
+  useCallback,
   useId,
+  useRef,
   type CSSProperties,
   type FormEventHandler,
   type MouseEvent,
   type ReactNode,
+  type RefObject,
 } from 'react';
 import { cx } from '../utils/cx';
 import { ModalResizeHandles } from './ModalResizeHandles';
 import { ModalTitlebar } from './ModalTitlebar';
+import { useModalFocusTrap } from './useModalFocusTrap';
 import { useModalWindowFrame } from './useModalWindowFrame';
 import {
   resolveWorkbenchWindowChromeDataAttributes,
   type WorkbenchWindowChromeMode,
-} from '../workbench/workbenchPlatformChrome';
+} from '../workbench/chrome/workbenchPlatformChrome';
 
 export type { ModalBounds, ModalPosition, ModalSize } from './modalTypes';
 
@@ -20,44 +24,50 @@ export type ModalBodyLayout = 'block' | 'stack';
 export type ModalBodyPadding = 'none' | 'md' | 'lg';
 
 export interface ModalProps {
-  chrome?: WorkbenchWindowChromeMode | undefined;
+  chrome?: WorkbenchWindowChromeMode;
   title: ReactNode;
-  titleSuffix?: ReactNode | undefined;
+  titleSuffix?: ReactNode;
   children: ReactNode;
-  footer?: ReactNode | undefined;
-  className?: string | undefined;
-  bodyClassName?: string | undefined;
-  bodyLayout?: ModalBodyLayout | undefined;
-  bodyPadding?: ModalBodyPadding | undefined;
-  bodyScroll?: 'auto' | 'hidden' | undefined;
-  closeLabel?: string | undefined;
-  defaultHeight?: number | undefined;
-  defaultMaximized?: boolean | undefined;
-  defaultWidth?: number | undefined;
-  labelledBy?: string | undefined;
-  maximizeLabel?: string | undefined;
-  minHeight?: number | undefined;
-  minWidth?: number | undefined;
+  footer?: ReactNode;
+  className?: string;
+  bodyClassName?: string;
+  bodyLayout?: ModalBodyLayout;
+  bodyPadding?: ModalBodyPadding;
+  bodyScroll?: 'auto' | 'hidden';
+  /** When true (default), Escape calls `onClose`. */
+  closeOnEscape?: boolean;
+  closeLabel?: string;
+  defaultHeight?: number;
+  defaultMaximized?: boolean;
+  defaultWidth?: number;
+  /** Optional element to focus when the modal mounts (must be inside the dialog). */
+  initialFocusRef?: RefObject<HTMLElement | null>;
+  labelledBy?: string;
+  maximizeLabel?: string;
+  minHeight?: number;
+  minWidth?: number;
   onClose: () => void;
-  onSubmit?: FormEventHandler<HTMLFormElement> | undefined;
-  restoreLabel?: string | undefined;
+  onSubmit?: FormEventHandler<HTMLFormElement>;
+  /** When true (default), restore focus to the previously focused element on unmount. */
+  restoreFocusOnClose?: boolean;
+  restoreLabel?: string;
 }
 
 interface ModalFrameProps {
-  bodyClassName?: string | undefined;
+  bodyClassName?: string;
   bodyLayout: ModalBodyLayout;
   bodyPadding: ModalBodyPadding;
   bodyScroll: 'auto' | 'hidden';
   children: ReactNode;
   dataAttrs: Record<string, string | undefined>;
-  footer?: ReactNode | undefined;
+  footer?: ReactNode;
   frameRef: (node: HTMLDivElement | HTMLFormElement | null) => void;
   modalClassName: string;
   resolvedLabelledBy: string;
-  resizeHandles?: ReactNode | undefined;
-  style?: CSSProperties | undefined;
+  resizeHandles?: ReactNode;
+  style?: CSSProperties;
   titlebar: ReactNode;
-  onSubmit?: FormEventHandler<HTMLFormElement> | undefined;
+  onSubmit?: FormEventHandler<HTMLFormElement>;
 }
 
 function ModalFrame({
@@ -133,22 +143,26 @@ export function Modal({
   bodyLayout = 'block',
   bodyPadding = 'none',
   bodyScroll = 'hidden',
+  closeOnEscape = true,
   closeLabel,
   defaultHeight,
   defaultMaximized = false,
   defaultWidth,
+  initialFocusRef,
   labelledBy,
   maximizeLabel,
   minHeight = 200,
   minWidth = 320,
   onClose,
   onSubmit,
+  restoreFocusOnClose = true,
   restoreLabel,
 }: ModalProps) {
   const modalClassName = cx('ui-modal', className);
   const chromeAttributes = resolveWorkbenchWindowChromeDataAttributes(chrome);
   const generatedLabelId = useId();
   const resolvedLabelledBy = labelledBy ?? generatedLabelId;
+  const dialogRef = useRef<HTMLElement | null>(null);
 
   const {
     assignFrameRef,
@@ -167,6 +181,22 @@ export function Modal({
     minWidth,
   });
 
+  const setFrameRef = useCallback(
+    (node: HTMLDivElement | HTMLFormElement | null) => {
+      dialogRef.current = node;
+      assignFrameRef(node);
+    },
+    [assignFrameRef],
+  );
+
+  useModalFocusTrap({
+    closeOnEscape,
+    containerRef: dialogRef,
+    initialFocusRef,
+    onClose,
+    restoreFocusOnClose,
+  });
+
   const isPositioned = bounds !== null || maximized;
 
   return (
@@ -183,7 +213,7 @@ export function Modal({
           ...(chromeAttributes ?? {}),
         }}
         footer={footer}
-        frameRef={assignFrameRef}
+        frameRef={setFrameRef}
         modalClassName={modalClassName}
         resolvedLabelledBy={resolvedLabelledBy}
         resizeHandles={maximized ? null : <ModalResizeHandles onResizeStart={handleResizeStart} />}

package/src/modal/ModalTitlebar.tsx

@@ -1,28 +1,28 @@
 import type { PointerEvent as ReactPointerEvent, ReactNode } from 'react';
 
-import { useWorkbenchHostPlatform } from '../workbench/WorkbenchPlatformContext';
+import { useWorkbenchHostPlatform } from '../workbench/chrome/WorkbenchPlatformContext';
 import {
   shouldUseDarwinPlatformChrome,
   WorkbenchWindowChromeControls,
-} from '../workbench/WorkbenchWindowChromeControls';
+} from '../workbench/shell/WorkbenchWindowChromeControls';
 import {
   resolveWorkbenchWindowChromeDataAttributes,
   type WorkbenchWindowChromeMode,
-} from '../workbench/workbenchPlatformChrome';
+} from '../workbench/chrome/workbenchPlatformChrome';
 
 export interface ModalTitlebarProps {
-  chrome?: WorkbenchWindowChromeMode | undefined;
-  closeLabel?: string | undefined;
+  chrome?: WorkbenchWindowChromeMode;
+  closeLabel?: string;
   labelledBy: string;
   maximized: boolean;
-  maximizeLabel?: string | undefined;
+  maximizeLabel?: string;
   onClose: () => void;
   onDoubleClick: () => void;
   onPointerDown: (event: ReactPointerEvent<HTMLDivElement>) => void;
   onToggleMaximized: () => void;
-  restoreLabel?: string | undefined;
+  restoreLabel?: string;
   title: ReactNode;
-  titleSuffix?: ReactNode | undefined;
+  titleSuffix?: ReactNode;
 }
 
 export function ModalTitlebar({

package/src/modal/modalPosition.ts

@@ -1,3 +1,4 @@
+import { clampNumber } from '../utils/clamp';
 import type { ModalBounds, ModalPosition, ModalSize } from './modalTypes';
 import type { ModalContainerBounds } from './modalContainer';
 import { readWindowViewportBounds } from './modalContainer';
@@ -17,9 +18,9 @@ export function clampModalDragPosition(
   }
 
   const maxX = Math.max(0, viewport.width - size.width);
-  const x = clamp(nextPosition.x, 0, maxX);
+  const x = clampNumber(nextPosition.x, 0, maxX);
   const maxY = size.height >= viewport.height ? 0 : Math.max(0, viewport.height - size.height);
-  const y = clamp(nextPosition.y, 0, maxY);
+  const y = clampNumber(nextPosition.y, 0, maxY);
 
   return { x, y };
 }
@@ -30,7 +31,3 @@ export function clampModalBoundsPosition(
 ): ModalBounds {
   return { ...bounds, ...clampModalDragPosition(bounds, bounds, viewport) };
 }
-
-function clamp(value: number, min: number, max: number): number {
-  return Math.min(Math.max(value, min), max);
-}