@workbench-kit/react 0.0.1-prototype.0

package/src/workbench/settings/WorkbenchSettingsModal.tsx

@@ -0,0 +1,188 @@
+import { useId, useState, type FormEventHandler, type ReactNode } from 'react';
+import { Modal } from '../../modal/Modal';
+import type { ModalProps } from '../../modal/Modal';
+import { TextInput } from '../../primitives/TextInput';
+import { cx } from '../../utils/cx';
+import { WorkbenchSettingsNav } from './WorkbenchSettingsNav';
+import type { WorkbenchSettingsCategory, WorkbenchSettingsScope } from './types';
+
+export interface WorkbenchSettingsModalProps extends Pick<
+  ModalProps,
+  'className' | 'closeLabel' | 'footer' | 'labelledBy' | 'onClose' | 'title' | 'titleSuffix'
+> {
+  categories: WorkbenchSettingsCategory[];
+  activeCategoryId?: string;
+  activeScopeId?: string;
+  bodyClassName?: string;
+  defaultActiveCategoryId?: string;
+  defaultActiveScopeId?: string;
+  defaultSearchValue?: string;
+  emptyContent?: ReactNode;
+  onActiveCategoryIdChange?: (categoryId: string) => void;
+  onScopeChange?: (scopeId: string) => void;
+  onSearchValueChange?: (value: string) => void;
+  onSubmit?: FormEventHandler<HTMLFormElement>;
+  renderCategory?: (category: WorkbenchSettingsCategory) => ReactNode;
+  scopes?: WorkbenchSettingsScope[];
+  searchPlaceholder?: string;
+  searchValue?: string;
+  showSearch?: boolean;
+}
+
+function firstEnabledCategory(categories: WorkbenchSettingsCategory[]) {
+  return categories.find((category) => !category.disabled) ?? categories[0];
+}
+
+function resolveCategoryId(
+  categories: WorkbenchSettingsCategory[],
+  preferredCategoryId: string | undefined,
+) {
+  const preferredCategory = categories.find(
+    (category) => category.id === preferredCategoryId && !category.disabled,
+  );
+
+  return preferredCategory?.id ?? firstEnabledCategory(categories)?.id ?? '';
+}
+
+function firstEnabledScope(scopes: WorkbenchSettingsScope[] | undefined) {
+  return scopes?.find((scope) => !scope.disabled) ?? scopes?.[0];
+}
+
+export function WorkbenchSettingsModal({
+  activeCategoryId,
+  activeScopeId,
+  bodyClassName,
+  categories,
+  className,
+  closeLabel = 'Close settings',
+  defaultActiveCategoryId,
+  defaultActiveScopeId,
+  defaultSearchValue = '',
+  emptyContent = null,
+  footer,
+  labelledBy,
+  onActiveCategoryIdChange,
+  onClose,
+  onScopeChange,
+  onSearchValueChange,
+  onSubmit,
+  renderCategory,
+  scopes,
+  searchPlaceholder = 'Search settings',
+  searchValue,
+  showSearch = true,
+  title,
+  titleSuffix,
+}: WorkbenchSettingsModalProps) {
+  const generatedId = useId().replace(/:/g, '');
+  const titleId = labelledBy ?? `${generatedId}-settings-title`;
+  const [uncontrolledCategoryId, setUncontrolledCategoryId] = useState(
+    () => defaultActiveCategoryId ?? firstEnabledCategory(categories)?.id ?? '',
+  );
+  const [uncontrolledScopeId, setUncontrolledScopeId] = useState(
+    () => defaultActiveScopeId ?? firstEnabledScope(scopes)?.id ?? '',
+  );
+  const [uncontrolledSearchValue, setUncontrolledSearchValue] = useState(defaultSearchValue);
+  const selectedCategoryId = resolveCategoryId(
+    categories,
+    activeCategoryId ?? uncontrolledCategoryId,
+  );
+  const selectedCategory = categories.find((category) => category.id === selectedCategoryId);
+  const selectedScopeId =
+    activeScopeId ?? uncontrolledScopeId ?? firstEnabledScope(scopes)?.id ?? '';
+  const resolvedSearchValue = searchValue ?? uncontrolledSearchValue;
+
+  const handleSelectCategory = (categoryId: string) => {
+    const category = categories.find((candidate) => candidate.id === categoryId);
+    if (!category || category.disabled) return;
+
+    if (activeCategoryId === undefined) {
+      setUncontrolledCategoryId(categoryId);
+    }
+
+    onActiveCategoryIdChange?.(categoryId);
+  };
+
+  const handleSelectScope = (scopeId: string) => {
+    const scope = scopes?.find((candidate) => candidate.id === scopeId);
+    if (!scope || scope.disabled) return;
+
+    if (activeScopeId === undefined) {
+      setUncontrolledScopeId(scopeId);
+    }
+
+    onScopeChange?.(scopeId);
+  };
+
+  const handleSearchChange = (value: string) => {
+    if (searchValue === undefined) {
+      setUncontrolledSearchValue(value);
+    }
+
+    onSearchValueChange?.(value);
+  };
+
+  return (
+    <Modal
+      className={cx('workbench-settings-modal', className)}
+      bodyClassName={cx('workbench-settings-modal__body', bodyClassName)}
+      closeLabel={closeLabel}
+      footer={footer}
+      labelledBy={titleId}
+      title={title}
+      titleSuffix={titleSuffix}
+      onClose={onClose}
+      onSubmit={onSubmit}
+    >
+      {showSearch ? (
+        <div className="workbench-settings-search">
+          <TextInput
+            aria-label={searchPlaceholder}
+            controlWidth="full"
+            placeholder={searchPlaceholder}
+            value={resolvedSearchValue}
+            onChange={(event) => handleSearchChange(event.currentTarget.value)}
+          />
+        </div>
+      ) : null}
+
+      {scopes?.length ? (
+        <div className="workbench-settings-tabs" aria-label="Settings scope">
+          {scopes.map((scope) => {
+            const isActive = scope.id === selectedScopeId;
+
+            return (
+              <button
+                key={scope.id}
+                type="button"
+                className={cx(
+                  'workbench-settings-tab',
+                  isActive && 'workbench-settings-tab--active',
+                )}
+                disabled={scope.disabled}
+                title={scope.title}
+                onClick={() => handleSelectScope(scope.id)}
+              >
+                {scope.label}
+              </button>
+            );
+          })}
+        </div>
+      ) : null}
+
+      <div className="workbench-settings-layout">
+        <WorkbenchSettingsNav
+          activeCategoryId={selectedCategoryId}
+          categories={categories}
+          onSelectCategory={handleSelectCategory}
+        />
+
+        <main className="workbench-settings-content">
+          {selectedCategory
+            ? (renderCategory?.(selectedCategory) ?? selectedCategory.content ?? emptyContent)
+            : emptyContent}
+        </main>
+      </div>
+    </Modal>
+  );
+}

package/src/workbench/settings/WorkbenchSettingsNav.tsx

@@ -0,0 +1,41 @@
+import { cx } from '../../utils/cx';
+import type { WorkbenchSettingsCategory } from './types';
+
+export interface WorkbenchSettingsNavProps {
+  activeCategoryId: string;
+  categories: WorkbenchSettingsCategory[];
+  ariaLabel?: string;
+  onSelectCategory: (categoryId: string) => void;
+}
+
+export function WorkbenchSettingsNav({
+  activeCategoryId,
+  ariaLabel = 'Settings categories',
+  categories,
+  onSelectCategory,
+}: WorkbenchSettingsNavProps) {
+  return (
+    <aside className="workbench-settings-sidebar" aria-label={ariaLabel}>
+      {categories.map((category) => {
+        const isActive = category.id === activeCategoryId;
+
+        return (
+          <button
+            key={category.id}
+            type="button"
+            className={cx(
+              'workbench-settings-nav-item',
+              isActive && 'workbench-settings-nav-item--active',
+            )}
+            aria-current={isActive ? 'page' : undefined}
+            disabled={category.disabled}
+            title={category.title}
+            onClick={() => onSelectCategory(category.id)}
+          >
+            {category.label}
+          </button>
+        );
+      })}
+    </aside>
+  );
+}

package/src/workbench/settings/WorkbenchSettingsSection.tsx

@@ -0,0 +1,30 @@
+import type { ReactNode } from 'react';
+import { cx } from '../../utils/cx';
+
+export interface WorkbenchSettingsSectionProps {
+  children: ReactNode;
+  id: string;
+  title: ReactNode;
+  className?: string;
+  description?: ReactNode;
+}
+
+export function WorkbenchSettingsSection({
+  children,
+  className,
+  description,
+  id,
+  title,
+}: WorkbenchSettingsSectionProps) {
+  return (
+    <section className={cx('workbench-settings-section', className)} aria-labelledby={id}>
+      <h2 id={id} className="workbench-settings-section__title">
+        {title}
+      </h2>
+      {description ? (
+        <p className="workbench-settings-section__description">{description}</p>
+      ) : null}
+      {children}
+    </section>
+  );
+}

package/src/workbench/settings/index.ts

@@ -0,0 +1,7 @@
+export { WorkbenchSettingsModal } from './WorkbenchSettingsModal';
+export type { WorkbenchSettingsModalProps } from './WorkbenchSettingsModal';
+export { WorkbenchSettingsNav } from './WorkbenchSettingsNav';
+export type { WorkbenchSettingsNavProps } from './WorkbenchSettingsNav';
+export { WorkbenchSettingsSection } from './WorkbenchSettingsSection';
+export type { WorkbenchSettingsSectionProps } from './WorkbenchSettingsSection';
+export type { WorkbenchSettingsCategory, WorkbenchSettingsScope } from './types';

package/src/workbench/settings/types.ts

@@ -0,0 +1,16 @@
+import type { ReactNode } from 'react';
+
+export interface WorkbenchSettingsCategory {
+  id: string;
+  label: string;
+  content?: ReactNode;
+  disabled?: boolean;
+  title?: string;
+}
+
+export interface WorkbenchSettingsScope {
+  id: string;
+  label: string;
+  disabled?: boolean;
+  title?: string;
+}

package/src/workbench/shellState.ts

@@ -0,0 +1,203 @@
+import { useReducer } from 'react';
+
+export interface WorkbenchShellInitialState<
+  TActivityId extends string = string,
+  TTheme extends string = string,
+> {
+  activeActivityId: TActivityId;
+  isPrimarySidebarVisible?: boolean;
+  isSettingsOpen?: boolean;
+  primarySidebarSizePercent?: number;
+  settingsCategoryId?: string;
+  settingsScopeId?: string;
+  settingsSearchValue?: string;
+  theme: TTheme;
+}
+
+export interface WorkbenchShellState<
+  TActivityId extends string = string,
+  TTheme extends string = string,
+> {
+  activeActivityId: TActivityId;
+  isPrimarySidebarVisible: boolean;
+  isSettingsOpen: boolean;
+  primarySidebarSizePercent: number;
+  settingsCategoryId: string;
+  settingsScopeId: string;
+  settingsSearchValue: string;
+  theme: TTheme;
+}
+
+export type WorkbenchShellAction<
+  TActivityId extends string = string,
+  TTheme extends string = string,
+> =
+  | { activityId: TActivityId; type: 'activate-activity' }
+  | { activityId: TActivityId; type: 'show-activity' }
+  | { isOpen: boolean; type: 'set-settings-open' }
+  | { percent: number; type: 'set-primary-sidebar-size' }
+  | { settingsCategoryId: string; type: 'set-settings-category' }
+  | { settingsScopeId: string; type: 'set-settings-scope' }
+  | { settingsSearchValue: string; type: 'set-settings-search' }
+  | { theme: TTheme; type: 'set-theme' }
+  | { type: 'close-settings' }
+  | { type: 'open-settings' }
+  | { type: 'toggle-primary-sidebar' }
+  | { isVisible: boolean; type: 'set-primary-sidebar-visible' };
+
+export interface UseWorkbenchShellStateResult<
+  TActivityId extends string = string,
+  TTheme extends string = string,
+> {
+  activateActivity: (activityId: TActivityId) => void;
+  closeSettings: () => void;
+  dispatch: (action: WorkbenchShellAction<TActivityId, TTheme>) => void;
+  openSettings: () => void;
+  setPrimarySidebarSizePercent: (percent: number) => void;
+  setPrimarySidebarVisible: (isVisible: boolean) => void;
+  setSettingsCategoryId: (settingsCategoryId: string) => void;
+  setSettingsOpen: (isOpen: boolean) => void;
+  setSettingsScopeId: (settingsScopeId: string) => void;
+  setSettingsSearchValue: (settingsSearchValue: string) => void;
+  setTheme: (theme: TTheme) => void;
+  showActivity: (activityId: TActivityId) => void;
+  state: WorkbenchShellState<TActivityId, TTheme>;
+  togglePrimarySidebar: () => void;
+}
+
+const DEFAULT_PRIMARY_SIDEBAR_SIZE_PERCENT = 24;
+const MIN_PRIMARY_SIDEBAR_SIZE_PERCENT = 10;
+const MAX_PRIMARY_SIDEBAR_SIZE_PERCENT = 90;
+
+function clampPrimarySidebarSizePercent(percent: number, fallback: number) {
+  if (!Number.isFinite(percent)) return fallback;
+  return Math.min(
+    MAX_PRIMARY_SIDEBAR_SIZE_PERCENT,
+    Math.max(MIN_PRIMARY_SIDEBAR_SIZE_PERCENT, percent),
+  );
+}
+
+export function initializeWorkbenchShellState<TActivityId extends string, TTheme extends string>({
+  activeActivityId,
+  isPrimarySidebarVisible = true,
+  isSettingsOpen = false,
+  primarySidebarSizePercent = DEFAULT_PRIMARY_SIDEBAR_SIZE_PERCENT,
+  settingsCategoryId = '',
+  settingsScopeId = '',
+  settingsSearchValue = '',
+  theme,
+}: WorkbenchShellInitialState<TActivityId, TTheme>): WorkbenchShellState<TActivityId, TTheme> {
+  return {
+    activeActivityId,
+    isPrimarySidebarVisible,
+    isSettingsOpen,
+    primarySidebarSizePercent: clampPrimarySidebarSizePercent(
+      primarySidebarSizePercent,
+      DEFAULT_PRIMARY_SIDEBAR_SIZE_PERCENT,
+    ),
+    settingsCategoryId,
+    settingsScopeId,
+    settingsSearchValue,
+    theme,
+  };
+}
+
+export function workbenchShellStateReducer<TActivityId extends string, TTheme extends string>(
+  state: WorkbenchShellState<TActivityId, TTheme>,
+  action: WorkbenchShellAction<TActivityId, TTheme>,
+): WorkbenchShellState<TActivityId, TTheme> {
+  if (action.type === 'activate-activity') {
+    const shouldHideSidebar =
+      action.activityId === state.activeActivityId && state.isPrimarySidebarVisible;
+
+    return {
+      ...state,
+      activeActivityId: action.activityId,
+      isPrimarySidebarVisible: !shouldHideSidebar,
+    };
+  }
+
+  if (action.type === 'show-activity') {
+    return {
+      ...state,
+      activeActivityId: action.activityId,
+      isPrimarySidebarVisible: true,
+    };
+  }
+
+  if (action.type === 'set-primary-sidebar-visible') {
+    return { ...state, isPrimarySidebarVisible: action.isVisible };
+  }
+
+  if (action.type === 'toggle-primary-sidebar') {
+    return { ...state, isPrimarySidebarVisible: !state.isPrimarySidebarVisible };
+  }
+
+  if (action.type === 'set-primary-sidebar-size') {
+    return {
+      ...state,
+      primarySidebarSizePercent: clampPrimarySidebarSizePercent(
+        action.percent,
+        state.primarySidebarSizePercent,
+      ),
+    };
+  }
+
+  if (action.type === 'set-theme') {
+    return { ...state, theme: action.theme };
+  }
+
+  if (action.type === 'open-settings') {
+    return { ...state, isSettingsOpen: true };
+  }
+
+  if (action.type === 'close-settings') {
+    return { ...state, isSettingsOpen: false };
+  }
+
+  if (action.type === 'set-settings-open') {
+    return { ...state, isSettingsOpen: action.isOpen };
+  }
+
+  if (action.type === 'set-settings-category') {
+    return { ...state, settingsCategoryId: action.settingsCategoryId };
+  }
+
+  if (action.type === 'set-settings-scope') {
+    return { ...state, settingsScopeId: action.settingsScopeId };
+  }
+
+  return { ...state, settingsSearchValue: action.settingsSearchValue };
+}
+
+export function useWorkbenchShellState<TActivityId extends string, TTheme extends string>(
+  initialState: WorkbenchShellInitialState<TActivityId, TTheme>,
+): UseWorkbenchShellStateResult<TActivityId, TTheme> {
+  const [state, dispatch] = useReducer(
+    workbenchShellStateReducer<TActivityId, TTheme>,
+    initialState,
+    initializeWorkbenchShellState,
+  );
+
+  return {
+    activateActivity: (activityId) => dispatch({ activityId, type: 'activate-activity' }),
+    closeSettings: () => dispatch({ type: 'close-settings' }),
+    dispatch,
+    openSettings: () => dispatch({ type: 'open-settings' }),
+    setPrimarySidebarSizePercent: (percent) =>
+      dispatch({ percent, type: 'set-primary-sidebar-size' }),
+    setPrimarySidebarVisible: (isVisible) =>
+      dispatch({ isVisible, type: 'set-primary-sidebar-visible' }),
+    setSettingsCategoryId: (settingsCategoryId) =>
+      dispatch({ settingsCategoryId, type: 'set-settings-category' }),
+    setSettingsOpen: (isOpen) => dispatch({ isOpen, type: 'set-settings-open' }),
+    setSettingsScopeId: (settingsScopeId) =>
+      dispatch({ settingsScopeId, type: 'set-settings-scope' }),
+    setSettingsSearchValue: (settingsSearchValue) =>
+      dispatch({ settingsSearchValue, type: 'set-settings-search' }),
+    setTheme: (theme) => dispatch({ theme, type: 'set-theme' }),
+    showActivity: (activityId) => dispatch({ activityId, type: 'show-activity' }),
+    state,
+    togglePrimarySidebar: () => dispatch({ type: 'toggle-primary-sidebar' }),
+  };
+}

package/src/workbench/standalone.ts

@@ -0,0 +1,94 @@
+import type { CommandRegistry } from '@workbench-kit/core';
+import type {
+  SaveResult,
+  WorkspacePatchApplyResult,
+  WorkspacePatchEvent,
+} from '@workbench-kit/contracts';
+import type { ReactNode } from 'react';
+import type { StatusBarSectionModel } from './StatusBar';
+import type { WorkbenchShellCommandContext } from './commands';
+import type { WorkspaceFile } from './workspace';
+
+export type WorkbenchTheme = 'light' | 'dark' | (string & {});
+
+export interface WorkbenchActivityDescriptor<TActivityId extends string = string> {
+  id: TActivityId;
+  label: string;
+  icon?: string;
+  iconNode?: ReactNode;
+}
+
+export interface WorkbenchActivityChangeEvent<TActivityId extends string = string> {
+  nextActivityId: TActivityId;
+}
+
+export interface WorkbenchWorkspaceController {
+  openFile: (path: string) => void | Promise<void>;
+  saveFile: (path: string, content: string, previousUpdatedAt?: string) => Promise<SaveResult>;
+  deleteFiles: (paths: string[]) => void | Promise<void>;
+  moveFiles?: (paths: string[], targetParentPath: string | undefined) => void | Promise<void>;
+  rename?: (path: string, nextName: string) => void | Promise<void>;
+}
+
+export interface WorkbenchChatController {
+  onChatSubmit: (message: string, context?: Record<string, unknown>) => void | Promise<void>;
+  onCancelChat: () => void;
+}
+
+export interface WorkbenchPatchController {
+  onPatchApply: (patch: WorkspacePatchEvent) => Promise<WorkspacePatchApplyResult> | void;
+}
+
+export interface WorkbenchSaveController {
+  onSaveResult?: (result: SaveResult) => void | Promise<void>;
+  onCommitPatchResult?: (
+    patch: WorkspacePatchEvent,
+    result: WorkspacePatchApplyResult,
+    source: 'chat' | 'command',
+  ) => void | Promise<void>;
+}
+
+export interface WorkbenchStatusController {
+  onStatusMessage?: (message: string) => void;
+  onError?: (error: Error) => void;
+}
+
+export interface WorkbenchShellContract<TActivityId extends string = string> {
+  activities: WorkbenchActivityDescriptor<TActivityId>[];
+  commandRegistry: CommandRegistry<WorkbenchShellCommandContext<TActivityId>>;
+  initialActivityId?: TActivityId;
+  initialTheme?: WorkbenchTheme;
+  statusSections: StatusBarSectionModel[];
+  statusCompact?: boolean;
+}
+
+export interface WorkbenchStandaloneEntryState<TActivityId extends string = string> {
+  activeActivityId: TActivityId;
+  isPrimarySidebarVisible: boolean;
+  primarySidebarSizePercent: number;
+  primarySidebarMinPercent?: number;
+  primarySidebarMaxPercent?: number;
+  theme: WorkbenchTheme;
+  isSettingsOpen?: boolean;
+  settingsCategoryId?: string;
+  settingsScopeId?: string;
+  settingsSearchValue?: string;
+  selectedFilePath?: string;
+  openFilePaths?: readonly string[];
+}
+
+export interface WorkbenchStandaloneBootstrap<TActivityId extends string = string> {
+  contract: WorkbenchShellContract<TActivityId>;
+  initialFiles: readonly WorkspaceFile[];
+  workspace: WorkbenchWorkspaceController;
+  chat: WorkbenchChatController;
+  patch: WorkbenchPatchController;
+  save: WorkbenchSaveController;
+  status: WorkbenchStatusController;
+  initialState?: Partial<WorkbenchStandaloneEntryState<TActivityId>>;
+}
+
+export type WorkbenchStandaloneBootstrapEvent<TActivityId extends string = string> =
+  | { type: 'activity-change'; payload: WorkbenchActivityChangeEvent<TActivityId> }
+  | { type: 'status-message'; message: string }
+  | { type: 'error'; error: Error };