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

package/src/workbench/commands/WorkbenchQuickOpen.tsx

@@ -0,0 +1,462 @@
+import {
+  useCallback,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+  type ComponentPropsWithRef,
+  type KeyboardEvent,
+  type ReactNode,
+} from 'react';
+import { useModalFocusTrap } from '../../modal/useModalFocusTrap';
+import { Button } from '../../primitives/button';
+import { EmptyState } from '../../primitives/empty-state';
+import { IconButton } from '../../primitives/icon-button';
+import { TextInput } from '../../primitives/text-input';
+import { cxCodicon } from '../../utils/codicon';
+import { cx } from '../../utils/cx';
+import {
+  DEFAULT_QUICK_OPEN_SEARCH_DEBOUNCE_MS,
+  getNextQuickOpenItemIndex,
+  isQuickOpenItemSelectable,
+  type QuickOpenItem,
+  type QuickOpenProvider,
+  type QuickOpenSelectContext,
+} from './quick-open-model';
+
+interface WorkbenchQuickOpenKeyEvent {
+  key: string;
+  preventDefault: () => void;
+}
+
+interface QuickOpenResult {
+  item: QuickOpenItem;
+  key: string;
+  provider: QuickOpenProvider;
+}
+
+function useControllableQuery({
+  defaultQuery = '',
+  query,
+  onQueryChange,
+}: {
+  defaultQuery?: string | undefined;
+  query?: string | undefined;
+  onQueryChange?: ((query: string) => void) | undefined;
+}) {
+  const [uncontrolledQuery, setUncontrolledQuery] = useState(defaultQuery);
+  const resolvedQuery = query ?? uncontrolledQuery;
+
+  const setQuery = (nextQuery: string) => {
+    if (query === undefined) {
+      setUncontrolledQuery(nextQuery);
+    }
+    onQueryChange?.(nextQuery);
+  };
+
+  return [resolvedQuery, setQuery] as const;
+}
+
+export interface WorkbenchQuickOpenProps extends Omit<
+  ComponentPropsWithRef<'div'>,
+  'children' | 'onSelect' | 'title'
+> {
+  activeItemId?: string | undefined;
+  closeLabel?: string | undefined;
+  debounceMs?: number | undefined;
+  defaultQuery?: string | undefined;
+  emptyLabel?: ReactNode | undefined;
+  onActiveItemChange?: ((itemId: string) => void) | undefined;
+  onClose: () => void;
+  onProviderError?: ((error: unknown, provider: QuickOpenProvider) => void) | undefined;
+  onQueryChange?: ((query: string) => void) | undefined;
+  onSelectItem?: ((item: QuickOpenItem, context: QuickOpenSelectContext) => void) | undefined;
+  open?: boolean | undefined;
+  placeholder?: string | undefined;
+  /** Restrict search to one provider. When omitted, all providers contribute. */
+  providerId?: string | undefined;
+  providers: readonly QuickOpenProvider[];
+  query?: string | undefined;
+  restoreFocusOnClose?: boolean | undefined;
+  title?: ReactNode | undefined;
+}
+
+export function WorkbenchQuickOpen({
+  activeItemId,
+  className,
+  closeLabel = 'Close Quick Open',
+  debounceMs = DEFAULT_QUICK_OPEN_SEARCH_DEBOUNCE_MS,
+  defaultQuery,
+  emptyLabel = 'No matching files',
+  onActiveItemChange,
+  onClose,
+  onProviderError,
+  onQueryChange,
+  onSelectItem,
+  open = true,
+  placeholder = 'Search files by name',
+  providerId,
+  providers,
+  query,
+  restoreFocusOnClose = true,
+  title = 'Quick Open',
+  ...props
+}: WorkbenchQuickOpenProps) {
+  const titleId = useId();
+  const listId = useId();
+  const dialogRef = useRef<HTMLDivElement>(null);
+  const inputRef = useRef<HTMLInputElement>(null);
+  const [uncontrolledActiveResultKey, setUncontrolledActiveResultKey] = useState<string>();
+  const [results, setResults] = useState<QuickOpenResult[]>([]);
+  const [searching, setSearching] = useState(false);
+  const onProviderErrorRef = useRef(onProviderError);
+  const [resolvedQuery, setResolvedQuery] = useControllableQuery({
+    defaultQuery,
+    onQueryChange,
+    query,
+  });
+
+  useEffect(() => {
+    onProviderErrorRef.current = onProviderError;
+  }, [onProviderError]);
+
+  const activeProviders = useMemo(() => {
+    if (providerId) {
+      const provider = providers.find((candidate) => candidate.id === providerId);
+      return provider ? [provider] : [];
+    }
+    return providers;
+  }, [providerId, providers]);
+
+  const items = useMemo(() => results.map(({ item }) => item), [results]);
+  const controlledActiveResult = activeItemId
+    ? results.find(({ item }) => item.id === activeItemId && isQuickOpenItemSelectable(item))
+    : undefined;
+  const uncontrolledActiveResult = results.find(
+    ({ item, key }) => key === uncontrolledActiveResultKey && isQuickOpenItemSelectable(item),
+  );
+  const activeResult =
+    controlledActiveResult ??
+    uncontrolledActiveResult ??
+    results.find(({ item }) => isQuickOpenItemSelectable(item));
+  const resolvedActiveResultKey = activeResult?.key;
+  const activeIndex = activeResult ? results.indexOf(activeResult) : -1;
+
+  const updateActiveItem = useCallback(
+    (result: QuickOpenResult | undefined) => {
+      if (!result) return;
+      if (activeItemId === undefined) {
+        setUncontrolledActiveResultKey(result.key);
+      }
+      onActiveItemChange?.(result.item.id);
+    },
+    [activeItemId, onActiveItemChange],
+  );
+
+  useModalFocusTrap({
+    enabled: open,
+    containerRef: dialogRef,
+    initialFocusRef: inputRef,
+    onClose,
+    restoreFocusOnClose,
+  });
+
+  useEffect(() => {
+    if (!open || activeProviders.length === 0) {
+      setResults([]);
+      setSearching(false);
+      return undefined;
+    }
+
+    const controller = new AbortController();
+    let cancelled = false;
+    const runSearch = async () => {
+      setResults([]);
+      setSearching(true);
+      const providerResults = activeProviders.map<QuickOpenResult[] | undefined>(() => undefined);
+      const publishAvailableResults = () => {
+        setResults(providerResults.flatMap((providerItems) => providerItems ?? []));
+      };
+      const searches = activeProviders.map(async (provider, providerIndex) => {
+        try {
+          const providerItems = await Promise.resolve(
+            provider.search(resolvedQuery, { signal: controller.signal }),
+          );
+          if (cancelled) return;
+
+          providerResults[providerIndex] = providerItems.map((item, itemIndex) => ({
+            item,
+            key: `${providerIndex}:${itemIndex}:${provider.id}:${item.id}`,
+            provider,
+          }));
+          publishAvailableResults();
+        } catch (error) {
+          if (cancelled) return;
+          providerResults[providerIndex] = [];
+          publishAvailableResults();
+          onProviderErrorRef.current?.(error, provider);
+        }
+      });
+
+      await Promise.allSettled(searches);
+      if (!cancelled) setSearching(false);
+    };
+
+    // Empty query (recent / top-level) should paint immediately; debounce typed queries.
+    const delay = resolvedQuery.trim() ? Math.max(0, debounceMs) : 0;
+    if (delay === 0) {
+      void runSearch();
+      return () => {
+        cancelled = true;
+        controller.abort();
+      };
+    }
+
+    const timer = window.setTimeout(() => {
+      void runSearch();
+    }, delay);
+
+    return () => {
+      cancelled = true;
+      controller.abort();
+      window.clearTimeout(timer);
+    };
+  }, [activeProviders, debounceMs, open, resolvedQuery]);
+
+  useEffect(() => {
+    if (!open) return;
+    if (activeItemId !== undefined) return;
+
+    setUncontrolledActiveResultKey((currentResultKey) => {
+      const currentResult = results.find(({ key }) => key === currentResultKey);
+      if (currentResult && isQuickOpenItemSelectable(currentResult.item)) {
+        return currentResultKey;
+      }
+
+      return results.find(({ item }) => isQuickOpenItemSelectable(item))?.key;
+    });
+  }, [activeItemId, open, results]);
+
+  const selectItem = useCallback(
+    (result: QuickOpenResult, index: number) => {
+      if (!isQuickOpenItemSelectable(result.item)) return;
+      onSelectItem?.(result.item, {
+        index,
+        providerId: result.provider.id,
+        query: resolvedQuery,
+      });
+    },
+    [onSelectItem, resolvedQuery],
+  );
+
+  const handleQuickOpenKeyDown = useCallback(
+    (event: WorkbenchQuickOpenKeyEvent) => {
+      if (
+        event.key !== 'ArrowDown' &&
+        event.key !== 'ArrowUp' &&
+        event.key !== 'Home' &&
+        event.key !== 'End' &&
+        event.key !== 'PageDown' &&
+        event.key !== 'PageUp' &&
+        event.key !== 'Enter'
+      ) {
+        return;
+      }
+
+      if (event.key === 'Enter') {
+        if (!activeResult) return;
+        event.preventDefault();
+        selectItem(activeResult, Math.max(activeIndex, 0));
+        return;
+      }
+
+      event.preventDefault();
+
+      const direction =
+        event.key === 'ArrowUp' || event.key === 'End' || event.key === 'PageUp'
+          ? 'previous'
+          : 'next';
+      const stepCount = event.key === 'PageDown' || event.key === 'PageUp' ? 5 : 1;
+      let nextIndex =
+        event.key === 'Home'
+          ? getNextQuickOpenItemIndex({
+              currentIndex: -1,
+              direction: 'next',
+              items,
+            })
+          : event.key === 'End'
+            ? getNextQuickOpenItemIndex({
+                currentIndex: 0,
+                direction: 'previous',
+                items,
+              })
+            : activeIndex;
+
+      if (event.key !== 'Home' && event.key !== 'End') {
+        for (let step = 0; step < stepCount; step += 1) {
+          const steppedIndex = getNextQuickOpenItemIndex({
+            currentIndex: nextIndex,
+            direction,
+            items,
+          });
+
+          if (steppedIndex < 0 || steppedIndex === nextIndex) break;
+          nextIndex = steppedIndex;
+        }
+      }
+
+      if (nextIndex >= 0) {
+        updateActiveItem(results[nextIndex]);
+      }
+    },
+    [activeIndex, activeResult, items, results, selectItem, updateActiveItem],
+  );
+
+  useEffect(() => {
+    if (!open) return undefined;
+
+    const onKeyDown = (event: globalThis.KeyboardEvent) => {
+      if (event.defaultPrevented) return;
+      handleQuickOpenKeyDown(event);
+    };
+
+    window.addEventListener('keydown', onKeyDown);
+    return () => {
+      window.removeEventListener('keydown', onKeyDown);
+    };
+  }, [handleQuickOpenKeyDown, open]);
+
+  const handleKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {
+    handleQuickOpenKeyDown(event);
+  };
+
+  useEffect(() => {
+    if (!resolvedActiveResultKey) return;
+
+    const activeElement = Array.from(
+      dialogRef.current?.querySelectorAll<HTMLElement>('[data-quick-open-id]') ?? [],
+    ).find((element) => element.dataset.quickOpenId === resolvedActiveResultKey);
+
+    activeElement?.scrollIntoView?.({ block: 'nearest' });
+  }, [resolvedActiveResultKey, results]);
+
+  if (!open) return null;
+
+  return (
+    <div className="ui-workbench-command-palette-overlay" onClick={onClose}>
+      <div
+        aria-labelledby={titleId}
+        aria-modal="true"
+        className={cx('ui-workbench-command-palette', className)}
+        data-testid="workbench-quick-open"
+        role="dialog"
+        {...props}
+        ref={dialogRef}
+        onClick={(event) => event.stopPropagation()}
+      >
+        <div className="ui-workbench-command-palette__header">
+          <span id={titleId} className="ui-workbench-command-palette__title">
+            {title}
+          </span>
+          <IconButton
+            className="ui-workbench-command-palette__close"
+            icon="codicon-close"
+            label={closeLabel}
+            onClick={onClose}
+          />
+        </div>
+        <div className="ui-workbench-command-palette__search">
+          <i aria-hidden="true" className="codicon codicon-search" />
+          <TextInput
+            ref={inputRef}
+            aria-activedescendant={
+              activeResult ? `${listId}-${activeResult.key.replace(/[^\w-]/g, '_')}` : undefined
+            }
+            aria-controls={listId}
+            aria-label={placeholder}
+            className="ui-workbench-command-palette__input"
+            controlWidth="full"
+            placeholder={placeholder}
+            type="search"
+            value={resolvedQuery}
+            onValueChange={setResolvedQuery}
+            onKeyDown={handleKeyDown}
+          />
+        </div>
+        <div
+          id={listId}
+          aria-busy={searching || undefined}
+          aria-label="Quick Open results"
+          className={cx('ui-workbench-command-list', 'ui-workbench-scrollbar')}
+          role="listbox"
+        >
+          {results.length === 0 ? (
+            <EmptyState compact icon="codicon-search">
+              {emptyLabel}
+            </EmptyState>
+          ) : (
+            results.map((result, index) => {
+              const { item, key, provider } = result;
+              const active = key === resolvedActiveResultKey;
+              const itemDomId = `${listId}-${key.replace(/[^\w-]/g, '_')}`;
+              const descriptionId = item.description ? `${itemDomId}-description` : undefined;
+
+              return (
+                <Button
+                  key={key}
+                  id={itemDomId}
+                  aria-describedby={descriptionId}
+                  aria-selected={active}
+                  className="ui-workbench-command-item"
+                  data-active={active ? 'true' : undefined}
+                  data-quick-open-id={key}
+                  disabled={item.disabled}
+                  role="option"
+                  onClick={() => selectItem(result, index)}
+                  onMouseEnter={() => updateActiveItem(result)}
+                >
+                  <span className="ui-workbench-command-item__icon">
+                    {item.icon ? <i aria-hidden="true" className={cxCodicon(item.icon)} /> : null}
+                  </span>
+                  <span className="ui-workbench-command-item__content">
+                    <span className="ui-workbench-command-item__label">{item.label}</span>
+                    {item.description ? (
+                      <span id={descriptionId} className="ui-workbench-command-item__description">
+                        {item.description}
+                      </span>
+                    ) : null}
+                  </span>
+                  <span className="ui-workbench-command-item__meta">
+                    {item.detail ? (
+                      <span className="ui-workbench-command-item__category">{item.detail}</span>
+                    ) : null}
+                    <span className="ui-workbench-command-item__category">{provider.label}</span>
+                  </span>
+                </Button>
+              );
+            })
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export type {
+  QuickOpenItem,
+  QuickOpenProvider,
+  QuickOpenSearchContext,
+  QuickOpenSelectContext,
+} from './quick-open-model';
+export {
+  DEFAULT_QUICK_OPEN_SEARCH_DEBOUNCE_MS,
+  getNextQuickOpenItemIndex,
+  isQuickOpenItemSelectable,
+} from './quick-open-model';
+export {
+  WORKSPACE_FILES_QUICK_OPEN_PROVIDER_ID,
+  createWorkspaceFilesQuickOpenProvider,
+  resolveQuickOpenItemPath,
+} from './createWorkspaceFilesQuickOpenProvider';
+export type { CreateWorkspaceFilesQuickOpenProviderOptions } from './createWorkspaceFilesQuickOpenProvider';

package/src/workbench/{command-model.ts → commands/command-model.ts}

@@ -1,6 +1,10 @@
 import type { CommandMenuItem, ResolvedCommandMenuCommandItem } from '@workbench-kit/platform';
 
-import { getWorkbenchStatusLabel, isWorkbenchStatusDisabled, type WorkbenchStatus } from './status';
+import {
+  getWorkbenchStatusLabel,
+  isWorkbenchStatusDisabled,
+  type WorkbenchStatus,
+} from '../shell/status';
 
 export type WorkbenchCommandStatus = WorkbenchStatus;
 

package/src/workbench/commands/command-ui.ts

@@ -0,0 +1,3 @@
+export * from './CommandPalette';
+export * from './ShortcutCommandBridge';
+export * from './WorkbenchQuickOpen';

package/src/workbench/{commands.ts → commands/commands.ts}

@@ -10,9 +10,10 @@ import {
   type CommandValue,
 } from '@workbench-kit/platform';
 
-import type { ContextMenuItem } from '../overlay/ContextMenu';
+import type { ContextMenuItem } from '../../overlay/ContextMenu';
 
 export const WORKBENCH_OPEN_SETTINGS_COMMAND_ID = 'workbench.openSettings';
+export const WORKBENCH_TOGGLE_FOCUS_MODE_COMMAND_ID = 'workbench.toggleFocusMode';
 export const WORKBENCH_TOGGLE_PRIMARY_SIDEBAR_COMMAND_ID = 'workbench.togglePrimarySidebar';
 export const WORKBENCH_EDITOR_SAVE_COMMAND_ID = 'editor.save';
 export const WORKBENCH_EDITOR_DISCARD_CHANGES_COMMAND_ID = 'editor.discardChanges';
@@ -22,6 +23,7 @@ export const WORKBENCH_EDITOR_SPLIT_RIGHT_COMMAND_ID = 'editor.splitRight';
 export const WORKBENCH_EDITOR_SPLIT_DOWN_COMMAND_ID = 'editor.splitDown';
 export const WORKBENCH_EDITOR_CLOSE_COMMAND_ID = 'editor.close';
 export const WORKBENCH_EDITOR_CLOSE_OTHERS_COMMAND_ID = 'editor.closeOthers';
+export const WORKBENCH_EDITOR_CLOSE_TO_RIGHT_COMMAND_ID = 'editor.closeToRight';
 export const WORKBENCH_EDITOR_CLOSE_ALL_COMMAND_ID = 'editor.closeAll';
 export const WORKBENCH_EDITOR_DELETE_COMMAND_ID = 'editor.delete';
 export const WORKBENCH_WORKSPACE_NEW_FILE_COMMAND_ID = 'workspace.newFile';
@@ -54,9 +56,11 @@ export interface WorkbenchShellCommandActivity<TActivityId extends string = stri
 }
 
 export interface WorkbenchShellCommandContext<TActivityId extends string = string> {
+  isFocusModeActive?: boolean | undefined;
   isPrimarySidebarVisible: boolean;
   openSettings: () => void;
   showActivity: (activityId: TActivityId) => void;
+  toggleFocusMode?: (() => void) | undefined;
   togglePrimarySidebar: () => void;
 }
 
@@ -96,6 +100,7 @@ function applyWorkbenchCommandOverrides<TContext>(
 
 export interface WorkbenchShellCommandPresetOptions<TActivityId extends string = string> {
   activities: WorkbenchShellCommandActivity<TActivityId>[];
+  includeFocusModeToggle?: boolean | undefined;
   includeSettings?: boolean | undefined;
   includeSidebarToggle?: boolean | undefined;
   menuSeparatorId?: string | undefined;
@@ -109,6 +114,8 @@ export interface WorkbenchShellCommandPresetOptions<TActivityId extends string =
 export interface WorkbenchEditorCommandContext {
   canCloseAll: boolean;
   canCloseOthers: boolean;
+  /** Optional so existing public command-context object literals remain source-compatible. */
+  canCloseToRight?: boolean | undefined;
   canClosePath: boolean;
   canCopyPath: boolean;
   canDeletePath: boolean;
@@ -119,6 +126,8 @@ export interface WorkbenchEditorCommandContext {
   canTogglePinned: boolean;
   closeAll: () => void;
   closeOthers: () => void;
+  /** Presence advertises support and makes Close to the right visible. */
+  closeToRight?: (() => void) | undefined;
   closePath: () => void;
   copyPath: () => void;
   deletePath: () => void;
@@ -159,6 +168,7 @@ export function getWorkbenchShowActivityCommandId(activityId: string) {
 
 export function createWorkbenchShellCommands<TActivityId extends string>({
   activities,
+  includeFocusModeToggle = true,
   includeSettings = true,
   includeSidebarToggle = true,
   settingsIcon = 'codicon-settings-gear',
@@ -179,6 +189,19 @@ export function createWorkbenchShellCommands<TActivityId extends string>({
 
   const shellCommands: CommandDefinition<WorkbenchShellCommandContext<TActivityId>>[] = [];
 
+  if (includeFocusModeToggle) {
+    shellCommands.push({
+      id: WORKBENCH_TOGGLE_FOCUS_MODE_COMMAND_ID,
+      icon: 'codicon-screen-full',
+      isEnabled: ({ toggleFocusMode }) => toggleFocusMode !== undefined,
+      label: ({ isFocusModeActive }) =>
+        isFocusModeActive ? 'Exit Focus Mode' : 'Enter Focus Mode',
+      run: ({ toggleFocusMode }) => toggleFocusMode?.(),
+      shortcut: 'Ctrl/Cmd+Shift+F11',
+      title: 'Toggle Focus Mode',
+    });
+  }
+
   if (includeSidebarToggle) {
     shellCommands.push({
       id: WORKBENCH_TOGGLE_PRIMARY_SIDEBAR_COMMAND_ID,
@@ -207,6 +230,7 @@ export function createWorkbenchShellCommands<TActivityId extends string>({
 
 export function createWorkbenchShellMenuEntries<TActivityId extends string>({
   activities,
+  includeFocusModeToggle = true,
   includeSettings = true,
   includeSidebarToggle = true,
   menuSeparatorId = 'workbench-shell-separator',
@@ -223,6 +247,15 @@ export function createWorkbenchShellMenuEntries<TActivityId extends string>({
   );
   const shellEntries: CommandMenuEntry<WorkbenchShellCommandContext<TActivityId>>[] = [];
 
+  if (includeFocusModeToggle) {
+    shellEntries.push(
+      commandMenuEntry<WorkbenchShellCommandContext<TActivityId>>(
+        WORKBENCH_TOGGLE_FOCUS_MODE_COMMAND_ID,
+        { surfaces: [WORKBENCH_COMMAND_SURFACE_ACTIVITY_BAR] },
+      ),
+    );
+  }
+
   if (includeSidebarToggle) {
     shellEntries.push(
       commandMenuEntry<WorkbenchShellCommandContext<TActivityId>>(
@@ -314,6 +347,14 @@ export function createWorkbenchEditorCommands({
         label: 'Close others',
         run: ({ closeOthers }) => closeOthers(),
       },
+      {
+        id: WORKBENCH_EDITOR_CLOSE_TO_RIGHT_COMMAND_ID,
+        icon: 'codicon-close-all',
+        isEnabled: ({ canCloseToRight, filePath }) => Boolean(filePath && canCloseToRight),
+        isVisible: ({ closeToRight }) => Boolean(closeToRight),
+        label: 'Close to the right',
+        run: ({ closeToRight }) => closeToRight?.(),
+      },
       {
         id: WORKBENCH_EDITOR_CLOSE_ALL_COMMAND_ID,
         icon: 'codicon-close-all',
@@ -379,6 +420,9 @@ export function createWorkbenchStandaloneEditorTabMenuEntries(): CommandMenuEntr
     commandMenuEntry<WorkbenchEditorCommandContext>(WORKBENCH_EDITOR_CLOSE_OTHERS_COMMAND_ID, {
       surfaces: [WORKBENCH_COMMAND_SURFACE_EDITOR],
     }),
+    commandMenuEntry<WorkbenchEditorCommandContext>(WORKBENCH_EDITOR_CLOSE_TO_RIGHT_COMMAND_ID, {
+      surfaces: [WORKBENCH_COMMAND_SURFACE_EDITOR],
+    }),
     commandMenuEntry<WorkbenchEditorCommandContext>(WORKBENCH_EDITOR_CLOSE_ALL_COMMAND_ID, {
       surfaces: [WORKBENCH_COMMAND_SURFACE_EDITOR],
     }),

package/src/workbench/commands/createWorkspaceFilesQuickOpenProvider.ts

@@ -0,0 +1,86 @@
+import { searchWorkspaceFiles, type WorkspaceFile } from '@workbench-kit/workspace';
+
+import type { QuickOpenItem, QuickOpenProvider } from './quick-open-model';
+
+export const WORKSPACE_FILES_QUICK_OPEN_PROVIDER_ID = 'workspace.files' as const;
+
+export interface CreateWorkspaceFilesQuickOpenProviderOptions {
+  /** Current workspace files, or a getter read on each search. */
+  files: readonly WorkspaceFile[] | (() => readonly WorkspaceFile[]);
+  id?: string | undefined;
+  label?: string | undefined;
+  /**
+   * When the query is empty, these paths appear first (still present in `files`).
+   * Remaining files follow in `searchWorkspaceFiles` order.
+   */
+  recentPaths?: readonly string[] | undefined;
+}
+
+function resolveFiles(
+  files: CreateWorkspaceFilesQuickOpenProviderOptions['files'],
+): readonly WorkspaceFile[] {
+  return typeof files === 'function' ? files() : files;
+}
+
+function toQuickOpenItem(path: string, matchedBy?: string, preview?: string): QuickOpenItem {
+  const segments = path.split('/');
+  const label = segments[segments.length - 1] || path;
+  const parent = segments.length > 1 ? segments.slice(0, -1).join('/') : undefined;
+
+  return {
+    data: { path },
+    description: parent,
+    detail: matchedBy ?? preview,
+    icon: 'codicon-file',
+    id: path,
+    label,
+  };
+}
+
+export function createWorkspaceFilesQuickOpenProvider(
+  options: CreateWorkspaceFilesQuickOpenProviderOptions,
+): QuickOpenProvider {
+  const providerId = options.id ?? WORKSPACE_FILES_QUICK_OPEN_PROVIDER_ID;
+  const providerLabel = options.label ?? 'Files';
+
+  return {
+    id: providerId,
+    label: providerLabel,
+    search(query: string) {
+      const files = [...resolveFiles(options.files)];
+      const results = searchWorkspaceFiles(files, query);
+      const items = results.map((result) =>
+        toQuickOpenItem(result.path, result.matchedBy, result.preview),
+      );
+
+      if (query.trim() || !options.recentPaths?.length) {
+        return items;
+      }
+
+      const recentSet = new Set(options.recentPaths);
+      const byPath = new Map(items.map((item) => [item.id, item]));
+      const recentItems: QuickOpenItem[] = [];
+
+      for (const path of options.recentPaths) {
+        const item = byPath.get(path);
+        if (item) {
+          recentItems.push({ ...item, detail: 'Recent' });
+        }
+      }
+
+      const rest = items.filter((item) => !recentSet.has(item.id));
+      return [...recentItems, ...rest];
+    },
+  };
+}
+
+export function resolveQuickOpenItemPath(item: QuickOpenItem): string | undefined {
+  if (typeof item.data === 'object' && item.data !== null && 'path' in item.data) {
+    const path = (item.data as { path?: unknown }).path;
+    if (typeof path === 'string' && path.length > 0) {
+      return path;
+    }
+  }
+
+  return item.id || undefined;
+}