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

package/src/workbench/commands/CommandList.tsx

@@ -0,0 +1,167 @@
+import { useEffect, useId, useRef, type ComponentPropsWithRef, type ReactNode } from 'react';
+import { Button } from '../../primitives/button';
+import { EmptyState } from '../../primitives/empty-state';
+import { cxCodicon } from '../../utils/codicon';
+import { cx } from '../../utils/cx';
+import {
+  getWorkbenchCommandExecutionLabel,
+  getWorkbenchCommandStatusLabel,
+  isWorkbenchCommandRunnable,
+  type WorkbenchCommandDescriptor,
+  type WorkbenchCommandRunContext,
+  type WorkbenchCommandRunSource,
+} from './command-model';
+import { isWorkbenchStatusBusy } from '../shell/status';
+
+function commandIcon(command: WorkbenchCommandDescriptor) {
+  if (!command.icon) return null;
+  return <i aria-hidden="true" className={cxCodicon(command.icon)} />;
+}
+
+function commandStatus(command: WorkbenchCommandDescriptor) {
+  const status = command.status ?? (command.disabled ? 'disabled' : 'idle');
+
+  return (
+    <span
+      aria-label={getWorkbenchCommandStatusLabel(status)}
+      className="ui-workbench-command-item__status"
+      title={getWorkbenchCommandStatusLabel(status)}
+    >
+      <span aria-hidden="true" className="ui-workbench-command-item__status-dot" />
+    </span>
+  );
+}
+
+function commandExecution(command: WorkbenchCommandDescriptor) {
+  if (!command.execution) return null;
+
+  return (
+    <span className="ui-workbench-command-item__chip">
+      {getWorkbenchCommandExecutionLabel(command.execution)}
+    </span>
+  );
+}
+
+export interface WorkbenchCommandListProps extends Omit<
+  ComponentPropsWithRef<'div'>,
+  'children' | 'onSelect'
+> {
+  activeCommandId?: string | undefined;
+  commands: readonly WorkbenchCommandDescriptor[];
+  emptyLabel?: ReactNode | undefined;
+  onActiveCommandChange?: ((commandId: string) => void) | undefined;
+  onRunCommand?:
+    | ((command: WorkbenchCommandDescriptor, context: WorkbenchCommandRunContext) => void)
+    | undefined;
+  query?: string | undefined;
+  source?: WorkbenchCommandRunSource | undefined;
+}
+
+export function WorkbenchCommandList({
+  activeCommandId,
+  className,
+  commands,
+  emptyLabel = 'No commands available',
+  id,
+  onActiveCommandChange,
+  onRunCommand,
+  query = '',
+  source = 'list',
+  ...props
+}: WorkbenchCommandListProps) {
+  const generatedId = useId();
+  const listId = id ?? generatedId;
+  const listRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (!activeCommandId) return;
+
+    const activeElement = Array.from(
+      listRef.current?.querySelectorAll<HTMLElement>('[data-command-id]') ?? [],
+    ).find((element) => element.dataset.commandId === activeCommandId);
+
+    activeElement?.scrollIntoView?.({ block: 'nearest' });
+  }, [activeCommandId, commands]);
+
+  if (commands.length === 0) {
+    return (
+      <div
+        id={id}
+        className={cx('ui-workbench-command-list', 'ui-workbench-scrollbar', className)}
+        {...props}
+      >
+        <EmptyState compact icon="codicon-search">
+          {emptyLabel}
+        </EmptyState>
+      </div>
+    );
+  }
+
+  return (
+    <div
+      id={id}
+      aria-label={props['aria-label'] ?? 'Commands'}
+      className={cx('ui-workbench-command-list', 'ui-workbench-scrollbar', className)}
+      role="listbox"
+      {...props}
+      ref={listRef}
+    >
+      {commands.map((command, index) => {
+        const active = command.id === activeCommandId;
+        const disabled = !isWorkbenchCommandRunnable(command);
+        const itemId = `${listId}-${command.id}`;
+        const descriptionId = command.description ? `${itemId}-description` : undefined;
+        const disabledReasonId = command.disabledReason ? `${itemId}-disabled` : undefined;
+
+        return (
+          <Button
+            key={command.id}
+            id={itemId}
+            aria-busy={command.status && isWorkbenchStatusBusy(command.status) ? true : undefined}
+            aria-describedby={
+              [descriptionId, disabledReasonId].filter(Boolean).join(' ') || undefined
+            }
+            aria-selected={active}
+            className="ui-workbench-command-item"
+            data-active={active ? 'true' : undefined}
+            data-command-id={command.id}
+            data-danger={command.danger ? 'true' : undefined}
+            data-status={command.status ?? (command.disabled ? 'disabled' : 'idle')}
+            disabled={disabled}
+            role="option"
+            onClick={() => onRunCommand?.(command, { index, query, source })}
+            onMouseDown={(event) => {
+              if (source === 'suggest') event.preventDefault();
+            }}
+            onMouseEnter={() => onActiveCommandChange?.(command.id)}
+          >
+            <span className="ui-workbench-command-item__icon">{commandIcon(command)}</span>
+            <span className="ui-workbench-command-item__content">
+              <span className="ui-workbench-command-item__label">{command.label}</span>
+              {command.description ? (
+                <span id={descriptionId} className="ui-workbench-command-item__description">
+                  {command.description}
+                </span>
+              ) : null}
+              {command.disabledReason ? (
+                <span id={disabledReasonId} className="ui-visually-hidden">
+                  {command.disabledReason}
+                </span>
+              ) : null}
+            </span>
+            <span className="ui-workbench-command-item__meta">
+              {command.category ? (
+                <span className="ui-workbench-command-item__category">{command.category}</span>
+              ) : null}
+              {commandExecution(command)}
+              {command.shortcut ? (
+                <kbd className="ui-workbench-command-item__shortcut">{command.shortcut}</kbd>
+              ) : null}
+              {commandStatus(command)}
+            </span>
+          </Button>
+        );
+      })}
+    </div>
+  );
+}

package/src/workbench/commands/CommandPalette.tsx

@@ -0,0 +1,391 @@
+import {
+  useEffect,
+  useId,
+  useCallback,
+  useMemo,
+  useRef,
+  useState,
+  type ComponentPropsWithRef,
+  type KeyboardEvent,
+  type ReactNode,
+} from 'react';
+import { useModalFocusTrap } from '../../modal/useModalFocusTrap';
+import { IconButton } from '../../primitives/icon-button';
+import { TextInput } from '../../primitives/text-input';
+import { cx } from '../../utils/cx';
+import {
+  filterWorkbenchCommands,
+  getNextWorkbenchCommandIndex,
+  isWorkbenchCommandRunnable,
+  normalizeWorkbenchCommandQuery,
+  type WorkbenchCommandDescriptor,
+  type WorkbenchCommandRunContext,
+} from './command-model';
+import { WorkbenchCommandList } from './CommandList';
+export { WorkbenchCommandList } from './CommandList';
+export type { WorkbenchCommandListProps } from './CommandList';
+export { WorkbenchCommandGroupShell } from './CommandGroupShell';
+export type { WorkbenchCommandGroupShellProps } from './CommandGroupShell';
+
+export {
+  commandMenuItemsToWorkbenchCommandDescriptors,
+  commandMenuItemToWorkbenchCommandDescriptor,
+  filterWorkbenchCommands,
+  getNextWorkbenchCommandIndex,
+  getWorkbenchCommandExecutionLabel,
+  getWorkbenchCommandStatusLabel,
+  groupWorkbenchCommands,
+  isWorkbenchCommandRunnable,
+  normalizeWorkbenchCommandQuery,
+} from './command-model';
+export {
+  getWorkbenchCommandExecutionPolicyLabel,
+  isWorkbenchCommandExecutionPolicy,
+  resolveWorkbenchCommandExecutionPolicy,
+} from './command-execution-policy';
+export type { ResolveWorkbenchCommandExecutionPolicyInput } from './command-execution-policy';
+export type {
+  WorkbenchCommandDescriptor,
+  WorkbenchCommandDescriptorOverrides,
+  WorkbenchCommandExecution,
+  WorkbenchCommandExecutionPolicy,
+  WorkbenchCommandFeedback,
+  WorkbenchCommandFilterInput,
+  WorkbenchCommandGroup,
+  WorkbenchCommandGroupBy,
+  WorkbenchCommandGroupingInput,
+  WorkbenchCommandNavigationInput,
+  WorkbenchCommandOutput,
+  WorkbenchCommandRunContext,
+  WorkbenchCommandRunSource,
+  WorkbenchCommandSideEffect,
+  WorkbenchCommandStatus,
+} from './command-model';
+
+interface WorkbenchCommandPaletteKeyEvent {
+  key: string;
+  preventDefault: () => void;
+}
+
+function useControllableCommandQuery({
+  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 WorkbenchCommandPaletteProps extends Omit<
+  ComponentPropsWithRef<'div'>,
+  'children' | 'onSelect' | 'title'
+> {
+  activeCommandId?: string | undefined;
+  closeLabel?: string | undefined;
+  commands: readonly WorkbenchCommandDescriptor[];
+  defaultQuery?: string | undefined;
+  emptyLabel?: ReactNode | undefined;
+  onActiveCommandChange?: ((commandId: string) => void) | undefined;
+  onClose: () => void;
+  onQueryChange?: ((query: string) => void) | undefined;
+  onRunCommand?:
+    | ((command: WorkbenchCommandDescriptor, context: WorkbenchCommandRunContext) => void)
+    | undefined;
+  open?: boolean | undefined;
+  placeholder?: string | undefined;
+  query?: string | undefined;
+  restoreFocusOnClose?: boolean | undefined;
+  title?: ReactNode | undefined;
+}
+
+export function WorkbenchCommandPalette({
+  activeCommandId,
+  className,
+  closeLabel = 'Close command palette',
+  commands,
+  defaultQuery,
+  emptyLabel = 'No commands match your search',
+  onActiveCommandChange,
+  onClose,
+  onQueryChange,
+  onRunCommand,
+  open = true,
+  placeholder = 'Search commands',
+  query,
+  restoreFocusOnClose = true,
+  title = 'Command Palette',
+  ...props
+}: WorkbenchCommandPaletteProps) {
+  const titleId = useId();
+  const listId = useId();
+  const dialogRef = useRef<HTMLDivElement>(null);
+  const inputRef = useRef<HTMLInputElement>(null);
+  const [uncontrolledActiveCommandId, setUncontrolledActiveCommandId] = useState<string>();
+  const [resolvedQuery, setResolvedQuery] = useControllableCommandQuery({
+    defaultQuery,
+    onQueryChange,
+    query,
+  });
+  const commandQuery = normalizeWorkbenchCommandQuery(resolvedQuery);
+  const filteredCommands = useMemo(
+    () => filterWorkbenchCommands({ commands, query: commandQuery }),
+    [commandQuery, commands],
+  );
+  const fallbackActiveCommand = filteredCommands.find((command) =>
+    isWorkbenchCommandRunnable(command),
+  );
+  const resolvedActiveCommandId =
+    activeCommandId ?? uncontrolledActiveCommandId ?? fallbackActiveCommand?.id;
+  const activeIndex = filteredCommands.findIndex(
+    (command) => command.id === resolvedActiveCommandId,
+  );
+  const activeCommand = activeIndex >= 0 ? filteredCommands[activeIndex] : fallbackActiveCommand;
+
+  const updateActiveCommand = useCallback(
+    (commandId: string | undefined) => {
+      if (!commandId) return;
+      if (activeCommandId === undefined) {
+        setUncontrolledActiveCommandId(commandId);
+      }
+      onActiveCommandChange?.(commandId);
+    },
+    [activeCommandId, onActiveCommandChange],
+  );
+
+  useModalFocusTrap({
+    enabled: open,
+    containerRef: dialogRef,
+    initialFocusRef: inputRef,
+    onClose,
+    restoreFocusOnClose,
+  });
+
+  const runCommand = useCallback(
+    (command: WorkbenchCommandDescriptor, context: WorkbenchCommandRunContext) => {
+      if (!isWorkbenchCommandRunnable(command)) return;
+      onRunCommand?.(command, context);
+    },
+    [onRunCommand],
+  );
+
+  useEffect(() => {
+    if (!open) return;
+    if (activeCommandId !== undefined) return;
+
+    setUncontrolledActiveCommandId((currentCommandId) => {
+      const nextCommandId = fallbackActiveCommand?.id;
+
+      return currentCommandId === nextCommandId ? currentCommandId : nextCommandId;
+    });
+  }, [activeCommandId, fallbackActiveCommand?.id, open]);
+
+  const handlePaletteKeyDown = useCallback(
+    (event: WorkbenchCommandPaletteKeyEvent) => {
+      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 (!activeCommand) return;
+        event.preventDefault();
+        runCommand(activeCommand, {
+          index: filteredCommands.findIndex((command) => command.id === activeCommand.id),
+          query: commandQuery,
+          source: 'palette',
+        });
+        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'
+          ? getNextWorkbenchCommandIndex({
+              commands: filteredCommands,
+              currentIndex: -1,
+              direction: 'next',
+            })
+          : event.key === 'End'
+            ? getNextWorkbenchCommandIndex({
+                commands: filteredCommands,
+                currentIndex: 0,
+                direction: 'previous',
+              })
+            : activeIndex;
+
+      if (event.key !== 'Home' && event.key !== 'End') {
+        for (let step = 0; step < stepCount; step += 1) {
+          const steppedIndex = getNextWorkbenchCommandIndex({
+            commands: filteredCommands,
+            currentIndex: nextIndex,
+            direction,
+          });
+
+          if (steppedIndex < 0 || steppedIndex === nextIndex) break;
+          nextIndex = steppedIndex;
+        }
+      }
+
+      if (nextIndex >= 0) {
+        updateActiveCommand(filteredCommands[nextIndex]?.id);
+      }
+    },
+    [activeCommand, activeIndex, commandQuery, filteredCommands, runCommand, updateActiveCommand],
+  );
+
+  useEffect(() => {
+    if (!open) return undefined;
+
+    const onKeyDown = (event: globalThis.KeyboardEvent) => {
+      if (event.defaultPrevented) return;
+
+      handlePaletteKeyDown(event);
+    };
+
+    window.addEventListener('keydown', onKeyDown);
+    return () => {
+      window.removeEventListener('keydown', onKeyDown);
+    };
+  }, [handlePaletteKeyDown, open]);
+
+  const handleKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {
+    handlePaletteKeyDown(event);
+  };
+
+  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)}
+        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={activeCommand ? `${listId}-${activeCommand.id}` : 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>
+        <WorkbenchCommandList
+          id={listId}
+          activeCommandId={activeCommand?.id}
+          aria-label="Command palette results"
+          commands={filteredCommands}
+          emptyLabel={emptyLabel}
+          query={resolvedQuery}
+          source="palette"
+          onActiveCommandChange={updateActiveCommand}
+          onRunCommand={runCommand}
+        />
+      </div>
+    </div>
+  );
+}
+
+export interface WorkbenchCommandSuggestProps extends Omit<
+  ComponentPropsWithRef<'div'>,
+  'children' | 'onSelect'
+> {
+  activeCommandId?: string | undefined;
+  commands: readonly WorkbenchCommandDescriptor[];
+  emptyLabel?: ReactNode | undefined;
+  onActiveCommandChange?: ((commandId: string) => void) | undefined;
+  onRunCommand?:
+    | ((command: WorkbenchCommandDescriptor, context: WorkbenchCommandRunContext) => void)
+    | undefined;
+  query?: string | undefined;
+  visible?: boolean | undefined;
+}
+
+export function WorkbenchCommandSuggest({
+  activeCommandId,
+  className,
+  commands,
+  emptyLabel = 'No suggested commands',
+  onActiveCommandChange,
+  onRunCommand,
+  query = '',
+  visible = true,
+  ...props
+}: WorkbenchCommandSuggestProps) {
+  const filteredCommands = useMemo(
+    () => filterWorkbenchCommands({ commands, limit: 8, query }),
+    [commands, query],
+  );
+  const fallbackActiveCommand = filteredCommands.find((command) =>
+    isWorkbenchCommandRunnable(command),
+  );
+
+  if (!visible) return null;
+
+  return (
+    <div className={cx('ui-workbench-command-suggest', className)} {...props}>
+      <div className="ui-workbench-command-suggest__header">
+        <span>Commands</span>
+        {query ? <span className="ui-workbench-command-suggest__query">/{query}</span> : null}
+      </div>
+      <WorkbenchCommandList
+        activeCommandId={activeCommandId ?? fallbackActiveCommand?.id}
+        aria-label="Suggested commands"
+        commands={filteredCommands}
+        emptyLabel={emptyLabel}
+        query={query}
+        source="suggest"
+        onActiveCommandChange={onActiveCommandChange}
+        onRunCommand={onRunCommand}
+      />
+    </div>
+  );
+}

package/src/workbench/{ConfirmationFlow.tsx → commands/ConfirmationFlow.tsx}

@@ -1,21 +1,19 @@
 import { useState, type FormEvent, type ReactNode } from 'react';
-import { Modal } from '../modal/Modal';
-import { Button } from '../primitives/Button';
-import { cx } from '../utils/cx';
+import '../shell/confirmation-flow.css';
+import { Modal } from '../../modal/Modal';
+import { Button } from '../../primitives/button';
+import { cx } from '../../utils/cx';
 import {
   getWorkbenchStatusLabel,
   isWorkbenchStatusBusy,
   isWorkbenchStatusDisabled,
   type WorkbenchStatus,
-} from './status';
+} from '../shell/status';
 
 export type WorkbenchConfirmationVariant = 'default' | 'danger';
 
 export type WorkbenchConfirmationSideEffect =
-  | 'external-write'
-  | 'none'
-  | 'workspace-write'
-  | (string & {});
+  'external-write' | 'none' | 'workspace-write' | (string & {});
 
 export type WorkbenchConfirmationReason = 'cancel' | 'close' | 'confirm';
 

package/src/workbench/{ShortcutCommandBridge.tsx → commands/ShortcutCommandBridge.tsx}

@@ -49,10 +49,7 @@ export interface WorkbenchShortcutCommandRunInput<
 }
 
 export type WorkbenchShortcutCommandMissReason =
-  | 'disabled'
-  | 'missing'
-  | 'missing-handler'
-  | 'no-match';
+  'disabled' | 'missing' | 'missing-handler' | 'no-match';
 
 export type WorkbenchShortcutCommandRunResult =
   | {

package/src/workbench/commands/command-execution-policy.ts

@@ -0,0 +1,61 @@
+import type { WorkbenchCommandDescriptor, WorkbenchCommandExecutionPolicy } from './command-model';
+
+export interface ResolveWorkbenchCommandExecutionPolicyInput {
+  /** Fallback for non-mutating commands without an explicit policy. */
+  defaultPolicy?: WorkbenchCommandExecutionPolicy | undefined;
+  /** Fallback for mutating commands without an explicit policy. */
+  mutatingDefaultPolicy?: WorkbenchCommandExecutionPolicy | undefined;
+  /** Host overrides keyed by command id. */
+  policyByCommandId?: Readonly<Record<string, WorkbenchCommandExecutionPolicy>> | undefined;
+}
+
+const policyLabels: Record<WorkbenchCommandExecutionPolicy, string> = {
+  'auto-allow': 'Auto allow',
+  'approval-required': 'Approval required',
+  'auto-deny': 'Auto deny',
+};
+
+export function isWorkbenchCommandExecutionPolicy(
+  value: unknown,
+): value is WorkbenchCommandExecutionPolicy {
+  return value === 'auto-allow' || value === 'approval-required' || value === 'auto-deny';
+}
+
+export function getWorkbenchCommandExecutionPolicyLabel(policy: WorkbenchCommandExecutionPolicy) {
+  return policyLabels[policy];
+}
+
+function isMutatingWorkbenchCommand(descriptor: WorkbenchCommandDescriptor) {
+  if (descriptor.danger) {
+    return true;
+  }
+
+  if (descriptor.sideEffect && descriptor.sideEffect !== 'none') {
+    return true;
+  }
+
+  if (descriptor.metadata?.requiresApproval === true) {
+    return true;
+  }
+
+  return false;
+}
+
+export function resolveWorkbenchCommandExecutionPolicy(
+  descriptor: WorkbenchCommandDescriptor,
+  input: ResolveWorkbenchCommandExecutionPolicyInput = {},
+): WorkbenchCommandExecutionPolicy {
+  if (descriptor.executionPolicy) {
+    return descriptor.executionPolicy;
+  }
+
+  const hostPolicy = input.policyByCommandId?.[descriptor.id];
+  if (hostPolicy) {
+    return hostPolicy;
+  }
+
+  const mutatingDefault = input.mutatingDefaultPolicy ?? 'approval-required';
+  const nonMutatingDefault = input.defaultPolicy ?? 'auto-allow';
+
+  return isMutatingWorkbenchCommand(descriptor) ? mutatingDefault : nonMutatingDefault;
+}