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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workbench-kit/react",
-  "version": "0.0.2-prototype.0.2.10",
+  "version": "0.0.2-prototype.0.2.11",
   "private": false,
   "type": "module",
   "exports": {
@@ -58,15 +58,15 @@
     "@vscode/codicons": "^0.0.45",
     "remark-gfm": "^4.0.1",
     "rehype-sanitize": "^6.0.0",
-    "@workbench-kit/contracts": "0.0.2-prototype.0.2.10",
-    "@workbench-kit/adapters": "0.0.2-prototype.0.2.10",
-    "@workbench-kit/jdw": "0.0.2-prototype.0.2.10",
-    "@workbench-kit/monaco": "0.0.2-prototype.0.2.10",
-    "@workbench-kit/services": "0.0.2-prototype.0.2.10",
-    "@workbench-kit/runtime": "0.0.2-prototype.0.2.10",
-    "@workbench-kit/tokens": "0.0.2-prototype.0.2.10",
-    "@workbench-kit/workspace": "0.0.2-prototype.0.2.10",
-    "@workbench-kit/platform": "0.0.2-prototype.0.2.10"
+    "@workbench-kit/adapters": "0.0.2-prototype.0.2.11",
+    "@workbench-kit/monaco": "0.0.2-prototype.0.2.11",
+    "@workbench-kit/contracts": "0.0.2-prototype.0.2.11",
+    "@workbench-kit/platform": "0.0.2-prototype.0.2.11",
+    "@workbench-kit/runtime": "0.0.2-prototype.0.2.11",
+    "@workbench-kit/services": "0.0.2-prototype.0.2.11",
+    "@workbench-kit/tokens": "0.0.2-prototype.0.2.11",
+    "@workbench-kit/workspace": "0.0.2-prototype.0.2.11",
+    "@workbench-kit/jdw": "0.0.2-prototype.0.2.11"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/index.ts

@@ -276,6 +276,7 @@ export {
   SideBarHeaderControl,
   SideBarList,
   SideBarListItem,
+  SideBarTree,
   SideBarViewFrame,
   SideBarRow,
   SidebarActionIconBar,
@@ -286,12 +287,20 @@ export {
   WorkbenchSidebarSection,
   WorkbenchSidebarSectionHeader,
   WorkbenchSidebarSectionStack,
+  flattenVisibleSideBarTreeItems,
+  isSideBarTreeBranch,
+  selectSideBarTreeIds,
+  toggleSideBarTreeId,
   useSidebarSectionBaseDepth,
 } from './layout/sidebar';
 export type {
   SideBarHeaderControlProps,
   SideBarListItemProps,
   SideBarListProps,
+  SideBarTreeItem,
+  SideBarTreeProps,
+  SideBarTreeSelectionMode,
+  SideBarTreeVisibleNode,
   SideBarViewFrameProps,
   SideBarRowProps,
   SidebarActionIconBarProps,
@@ -643,8 +652,13 @@ export type {
 } from './primitives';
 export { CatalogFilterOverlay } from './primitives';
 export type { CatalogFilterOverlayProps } from './primitives';
-export { LibraryDetailLayout } from './primitives';
-export type { LibraryDetailLayoutMode, LibraryDetailLayoutProps } from './primitives';
+export { LibraryDetailLayout, resolveLibraryDetailHeroCoverMedia } from './primitives';
+export type {
+  LibraryDetailLayoutMode,
+  LibraryDetailLayoutProps,
+  ResolveLibraryDetailHeroCoverMediaInput,
+  ResolvedLibraryDetailHeroCoverMedia,
+} from './primitives';
 export { WorkbenchMediaPlaceholder } from './primitives';
 export type { WorkbenchMediaPlaceholderProps } from './primitives';
 export { WorkbenchMediaSlot } from './primitives';

package/src/layout/index.ts

@@ -56,6 +56,7 @@ export {
   SideBarListItem,
   SideBarRow,
   SideBarScrollSpacer,
+  SideBarTree,
   SideBarViewFrame,
   SideBarViewTabStrip,
   SideBarViewTitleMenu,
@@ -68,7 +69,11 @@ export {
   WorkbenchSidebarSection,
   WorkbenchSidebarSectionHeader,
   WorkbenchSidebarSectionStack,
+  flattenVisibleSideBarTreeItems,
+  isSideBarTreeBranch,
+  selectSideBarTreeIds,
   sideBarTreeDepthStyle,
+  toggleSideBarTreeId,
   useSidebarSectionBaseDepth,
 } from './sidebar';
 export type {
@@ -77,6 +82,10 @@ export type {
   SideBarListProps,
   SideBarRowProps,
   SideBarScrollSpacerProps,
+  SideBarTreeItem,
+  SideBarTreeProps,
+  SideBarTreeSelectionMode,
+  SideBarTreeVisibleNode,
   SideBarViewFrameProps,
   SideBarViewTabDescriptor,
   SideBarViewTabStripProps,

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