@workbench-kit/shell-react 0.0.2-prototype.0.2.10

package/README.md

@@ -0,0 +1,98 @@
+# `@workbench-kit/shell-react`
+
+React shell and host assembly for Workbench Kit: `WorkbenchProvider`,
+`WorkbenchShell`, editor area wiring, layout/appearance persistence helpers, and
+settings/profile/help composition.
+
+Published on npm with the **`prototype`** dist tag.
+
+## Install
+
+```powershell
+pnpm add @workbench-kit/shell-react@prototype @workbench-kit/react@prototype @workbench-kit/tokens@prototype
+```
+
+Peer: React 19.
+
+## Quick start
+
+```tsx
+import { WorkbenchProvider, WorkbenchShell } from '@workbench-kit/shell-react';
+
+export function App() {
+  return (
+    <WorkbenchProvider>
+      <WorkbenchShell title="Workbench" primarySidebar={<aside />} />
+    </WorkbenchProvider>
+  );
+}
+```
+
+Prefer this package when the host needs provider + shell orchestration. For
+layout-only chrome without host services, start from
+`@workbench-kit/react/workbench/shell` — see
+[Getting Started](../../docs/guides/getting-started.md).
+
+## Field Remap embed (slim subpath)
+
+Hosts that only need the Field Remap mapper UI can import the slim subpath instead
+of the full shell barrel (avoids pulling workbench shell / extension-host surfaces
+into the consumer import graph):
+
+```ts
+import {
+  FieldRemapPanel,
+  FieldRemapFlowMapper,
+  createJsonataValueTransform,
+} from '@workbench-kit/shell-react/field-remap';
+import '@workbench-kit/shell-react/field-remap/view.css';
+
+// Uncontrolled demo:
+// <FieldRemapPanel sample="nested-ab" />
+
+// Controlled (host-persisted edges):
+// <FieldRemapPanel edges={edges} onEdgesChange={setEdges} sources={…} targets={…} sourceSample={…} />
+```
+
+`FieldRemapFlowMapper` side-imports the same CSS; the explicit CSS export remains
+for Flow-only embeds and custom bundler setups. The full barrel
+`import { FieldRemapPanel } from '@workbench-kit/shell-react'` stays supported.
+
+### Flow host chrome hooks
+
+`FieldRemapFlowMapper` (and `FieldRemapPanel` pass-through) accept optional chrome
+hooks so hosts avoid CSS/DOM workarounds:
+
+| Prop                                                            | Behavior                                                              |
+| --------------------------------------------------------------- | --------------------------------------------------------------------- |
+| `showMinimap`                                                   | Default `true`. When `false`, MiniMap is not mounted.                 |
+| `onPaneContextMenu` / `onNodeContextMenu` / `onEdgeContextMenu` | Native event + selection payload; host owns menu UI.                  |
+| `flowActionsRef`                                                | `{ fitView(options?) }` using the same defaults as Controls fit-view. |
+| `labels` / `t`                                                  | Override edge-list / Convert palette chrome (e.g. “Field maps”).      |
+| `ioChrome` (Panel)                                              | `'browse' \| 'edit' \| 'none'` — prefer browse for inspect-only I/O.  |
+
+```tsx
+const flowActionsRef = useRef<FieldRemapFlowActions | null>(null);
+
+<FieldRemapFlowMapper
+  sources={sources}
+  targets={targets}
+  edges={edges}
+  transforms={registry}
+  onEdgesChange={setEdges}
+  showMinimap={false}
+  labels={{ bindingsTitle: 'Field maps' }}
+  flowActionsRef={flowActionsRef}
+  onPaneContextMenu={(event, { selection }) => {
+    event.preventDefault();
+    // host ContextMenu…
+  }}
+/>;
+```
+
+## Related docs
+
+- [Component Map](../../docs/guides/component-map.md)
+- [Sample Screens](../../docs/guides/sample-screens.md)
+- [Consumer Capabilities](../../docs/workbench/consumer-capabilities.md)
+- Sample host: [`examples/workbench-sample`](../../examples/workbench-sample/README.md)

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@workbench-kit/shell-react",
+  "version": "0.0.2-prototype.0.2.10",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./field-remap": "./src/field-remap/index.ts",
+    "./field-remap/view.css": "./src/field-remap/view.css"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.stories.ts",
+    "!src/**/*.stories.tsx"
+  ],
+  "dependencies": {
+    "@radix-ui/react-select": "^2.3.4",
+    "@radix-ui/react-slot": "^1.3.0",
+    "@xyflow/react": "^12.11.2",
+    "jsonata": "^2.2.0",
+    "react-table-mapping": "^1.0.3",
+    "@workbench-kit/platform": "0.0.2-prototype.0.2.10",
+    "@workbench-kit/tokens": "0.0.2-prototype.0.2.10",
+    "@workbench-kit/workbench-config": "0.0.2-prototype.0.2.10",
+    "@workbench-kit/react": "0.0.2-prototype.0.2.10",
+    "@workbench-kit/field-remap": "0.0.2-prototype.0.2.10",
+    "@workbench-kit/workbench-core": "0.0.2-prototype.0.2.10",
+    "@workbench-kit/workspace": "0.0.2-prototype.0.2.10"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "description": "React shell and host assembly for Workbench Kit.",
+  "publishConfig": {
+    "access": "public",
+    "tag": "prototype",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NewChoBo/workbench-kit.git",
+    "directory": "packages/shell-react"
+  },
+  "scripts": {
+    "test": "vitest run --config vitest.config.ts src",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/src/chat/ai-mock-proposals.ts

@@ -0,0 +1,39 @@
+import type { WorkbenchChatCommandProposalInput } from './use-chat-command-proposals.js';
+
+const MOCK_AI_COMMAND_PROPOSALS: readonly WorkbenchChatCommandProposalInput[] = [
+  {
+    commandId: 'workbench.showActivity.explorer',
+    description: 'Focus the Explorer activity in the primary sidebar.',
+    id: 'mock-proposal-show-explorer',
+    label: 'Show Explorer',
+  },
+  {
+    commandId: 'workbench.togglePrimarySidebar',
+    description: 'Toggle the primary sidebar visibility.',
+    id: 'mock-proposal-toggle-sidebar',
+    label: 'Toggle Primary Sidebar',
+  },
+];
+
+export function createMockAiChatCommandProposals(
+  userMessage: string,
+): readonly WorkbenchChatCommandProposalInput[] {
+  const normalized = userMessage.trim().toLocaleLowerCase();
+  if (!normalized || normalized === 'help') {
+    return [];
+  }
+
+  return MOCK_AI_COMMAND_PROPOSALS;
+}
+
+export function createMockAiChatResponseContent(userMessage: string) {
+  const proposals = createMockAiChatCommandProposals(userMessage);
+  if (!proposals.length) {
+    return `Received: ${userMessage}`;
+  }
+
+  return [
+    `I can help with "${userMessage.trim()}".`,
+    'Review the suggested commands below. Safe commands run automatically; workspace changes require approval.',
+  ].join('\n\n');
+}

package/src/chat/command-input.ts

@@ -0,0 +1,52 @@
+export type WorkbenchChatCommandInputParseResult =
+  | { type: 'none' }
+  | { type: 'unknown'; token: string }
+  | { commandId: string; message: string; type: 'invalid-arguments' }
+  | { args: readonly unknown[]; commandId: string; type: 'run' };
+
+export function parseWorkbenchChatCommandInput(
+  input: string,
+  isValidCommandId: (id: string) => boolean,
+): WorkbenchChatCommandInputParseResult {
+  const trimmed = input.trim();
+  if (!trimmed.startsWith('/')) {
+    return { type: 'none' };
+  }
+
+  const [rawToken] = trimmed.slice(1).split(/\s+/, 1);
+  if (!rawToken) {
+    return { token: '', type: 'unknown' };
+  }
+
+  if (!isValidCommandId(rawToken)) {
+    return { token: rawToken, type: 'unknown' };
+  }
+
+  const argumentText = getSlashCommandArgumentText(trimmed, rawToken);
+  if (!argumentText) {
+    return {
+      args: [],
+      commandId: rawToken,
+      type: 'run',
+    };
+  }
+
+  try {
+    return {
+      args: [JSON.parse(argumentText) as unknown],
+      commandId: rawToken,
+      type: 'run',
+    };
+  } catch {
+    return {
+      commandId: rawToken,
+      message:
+        'Command arguments must be valid JSON. Use /command.id {"key":"value"} or /command.id "value".',
+      type: 'invalid-arguments',
+    };
+  }
+}
+
+function getSlashCommandArgumentText(trimmedInput: string, commandId: string) {
+  return trimmedInput.slice(1 + commandId.length).trim();
+}

package/src/chat/command-policy.ts

@@ -0,0 +1,54 @@
+import type {
+  ResolveWorkbenchCommandExecutionPolicyInput,
+  WorkbenchCommandExecutionPolicy,
+} from '@workbench-kit/react/workbench';
+import type { WorkbenchStorageReader } from '@workbench-kit/workbench-core';
+
+import { readPersistedLocalPreferences } from '../management/preference-settings-storage.js';
+
+export const WORKBENCH_AI_CHAT_COMMAND_DEFAULT_POLICY_KEY = 'workbench.chat.aiCommandDefaultPolicy';
+
+function isWorkbenchCommandExecutionPolicy(
+  value: unknown,
+): value is WorkbenchCommandExecutionPolicy {
+  return value === 'auto-allow' || value === 'approval-required' || value === 'auto-deny';
+}
+
+export function readWorkbenchAiChatCommandPolicyInput(
+  storageKey?: string,
+  storage?: WorkbenchStorageReader,
+): ResolveWorkbenchCommandExecutionPolicyInput {
+  const preferences = readPersistedLocalPreferences(storageKey, storage);
+  const configuredDefault = preferences[WORKBENCH_AI_CHAT_COMMAND_DEFAULT_POLICY_KEY];
+
+  return {
+    defaultPolicy: isWorkbenchCommandExecutionPolicy(configuredDefault)
+      ? configuredDefault
+      : undefined,
+    mutatingDefaultPolicy: 'approval-required',
+  };
+}
+
+export function createWorkbenchAiChatCommandPolicyById(
+  entries: Readonly<Record<string, WorkbenchCommandExecutionPolicy>>,
+): ResolveWorkbenchCommandExecutionPolicyInput {
+  return {
+    policyByCommandId: entries,
+  };
+}
+
+export function mergeWorkbenchAiChatCommandPolicyInput(
+  ...inputs: readonly ResolveWorkbenchCommandExecutionPolicyInput[]
+): ResolveWorkbenchCommandExecutionPolicyInput {
+  return inputs.reduce<ResolveWorkbenchCommandExecutionPolicyInput>(
+    (merged, input) => ({
+      defaultPolicy: input.defaultPolicy ?? merged.defaultPolicy,
+      mutatingDefaultPolicy: input.mutatingDefaultPolicy ?? merged.mutatingDefaultPolicy,
+      policyByCommandId: {
+        ...merged.policyByCommandId,
+        ...input.policyByCommandId,
+      },
+    }),
+    {},
+  );
+}

package/src/chat/command-surface.tsx

@@ -0,0 +1,155 @@
+import { useCallback, useMemo, useRef, type KeyboardEvent } from 'react';
+import {
+  WorkbenchCommandSuggest,
+  isWorkbenchCommandRunnable,
+  useSlashCommandSuggest,
+  type WorkbenchCommandDescriptor,
+} from '@workbench-kit/react/workbench';
+
+import { parseWorkbenchChatCommandInput } from './command-input.js';
+import { useWorkbench } from '../shell/provider.js';
+import { useWorkbenchCommandDescriptors } from '../commands/use-command-descriptors.js';
+
+export interface WorkbenchChatCommandRunResult {
+  commandId: string;
+  label?: string | undefined;
+  message?: string | undefined;
+  status: 'error' | 'success';
+}
+
+export interface WorkbenchChatCommandSurfaceOptions {
+  additionalCommands?: readonly WorkbenchCommandDescriptor[] | undefined;
+  onCommandResult?: ((result: WorkbenchChatCommandRunResult) => void) | undefined;
+  onValueChange: (value: string) => void;
+  value: string;
+}
+
+export function useWorkbenchChatCommandSurface({
+  additionalCommands,
+  onCommandResult,
+  onValueChange,
+  value,
+}: WorkbenchChatCommandSurfaceOptions) {
+  const { executeCommand } = useWorkbench();
+  const composerRef = useRef<HTMLTextAreaElement>(null);
+  const commands = useWorkbenchCommandDescriptors(additionalCommands);
+  const commandIds = useMemo(() => new Set(commands.map((command) => command.id)), [commands]);
+  const suggest = useSlashCommandSuggest({ commands, value });
+
+  const runCommand = useCallback(
+    async (commandId: string, args: readonly unknown[] = []) => {
+      const command = commands.find((candidate) => candidate.id === commandId);
+      if (command && !isWorkbenchCommandRunnable(command)) {
+        onCommandResult?.({
+          commandId,
+          label: command.label,
+          message: command.disabledReason ?? 'Command is currently unavailable.',
+          status: 'error',
+        });
+        return;
+      }
+
+      onValueChange('');
+
+      try {
+        await executeCommand(commandId, ...args);
+        onCommandResult?.({
+          commandId,
+          label: command?.label,
+          status: 'success',
+        });
+      } catch (error) {
+        onCommandResult?.({
+          commandId,
+          label: command?.label,
+          message: getCommandErrorMessage(error),
+          status: 'error',
+        });
+      }
+    },
+    [commands, executeCommand, onCommandResult, onValueChange],
+  );
+
+  const runInputAsCommand = useCallback(
+    (message: string) => {
+      const parsed = parseWorkbenchChatCommandInput(message, (commandId) =>
+        commandIds.has(commandId),
+      );
+      if (parsed.type === 'none') {
+        return false;
+      }
+
+      if (parsed.type === 'unknown') {
+        onValueChange('');
+        onCommandResult?.({
+          commandId: parsed.token || '/',
+          message: parsed.token ? `Unknown command: ${parsed.token}` : 'Type a command after /.',
+          status: 'error',
+        });
+        return true;
+      }
+
+      if (parsed.type === 'invalid-arguments') {
+        onValueChange('');
+        onCommandResult?.({
+          commandId: parsed.commandId,
+          message: parsed.message,
+          status: 'error',
+        });
+        return true;
+      }
+
+      void runCommand(parsed.commandId, parsed.args);
+      return true;
+    },
+    [commandIds, onCommandResult, onValueChange, runCommand],
+  );
+
+  const handleKeyDown = useCallback(
+    (event: KeyboardEvent<HTMLTextAreaElement>) => {
+      suggest.handleKeyDown(event, (commandId) => {
+        void runCommand(commandId);
+      });
+    },
+    [runCommand, suggest],
+  );
+
+  const openCommandSuggest = useCallback(() => {
+    if (!value.trimStart().startsWith('/')) {
+      onValueChange('/');
+    }
+
+    window.requestAnimationFrame(() => {
+      composerRef.current?.focus();
+    });
+  }, [onValueChange, value]);
+
+  const commandSuggestPopover = (
+    <WorkbenchCommandSuggest
+      activeCommandId={suggest.activeCommandId}
+      commands={suggest.suggestedCommands}
+      query={suggest.commandQuery}
+      visible={suggest.isOpen}
+      onActiveCommandChange={suggest.setActiveCommandByKey}
+      onRunCommand={(command) => {
+        void runCommand(command.id);
+      }}
+    />
+  );
+
+  return {
+    commandSuggestPopover,
+    composerRef,
+    onCommandClick: openCommandSuggest,
+    onKeyDown: handleKeyDown,
+    runInputAsCommand,
+  };
+}
+
+function getCommandErrorMessage(error: unknown) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  return String(error);
+}

package/src/chat/use-chat-command-proposals.ts

@@ -0,0 +1,194 @@
+import { useCallback, useRef, type Dispatch, type SetStateAction } from 'react';
+import {
+  isWorkbenchCommandRunnable,
+  resolveWorkbenchCommandExecutionPolicy,
+  type ResolveWorkbenchCommandExecutionPolicyInput,
+  type WorkbenchCommandDescriptor,
+} from '@workbench-kit/react/workbench';
+import type { ChatCommandProposal, ChatMessage } from '@workbench-kit/react/workbench/chat';
+
+import { type WorkbenchChatCommandRunResult } from './command-surface.js';
+import { useWorkbench } from '../shell/provider.js';
+
+export interface WorkbenchChatCommandProposalInput {
+  args?: readonly unknown[] | undefined;
+  commandId: string;
+  description?: string | undefined;
+  id?: string | undefined;
+  label?: string | undefined;
+}
+
+export interface UseWorkbenchChatCommandProposalsOptions {
+  commands: readonly WorkbenchCommandDescriptor[];
+  onCommandResult?: ((result: WorkbenchChatCommandRunResult) => void) | undefined;
+  policyInput?: ResolveWorkbenchCommandExecutionPolicyInput | undefined;
+}
+
+function getCommandErrorMessage(error: unknown) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  return String(error);
+}
+
+function createProposalId(commandId: string) {
+  return `proposal-${commandId}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+}
+
+export function useWorkbenchChatCommandProposals({
+  commands,
+  onCommandResult,
+  policyInput,
+}: UseWorkbenchChatCommandProposalsOptions) {
+  const { executeCommand } = useWorkbench();
+  const runningProposalIds = useRef(new Set<string>());
+
+  const resolveDescriptor = useCallback(
+    (commandId: string, label?: string) =>
+      commands.find((command) => command.id === commandId) ?? {
+        id: commandId,
+        label: label ?? commandId,
+      },
+    [commands],
+  );
+
+  const enrichProposal = useCallback(
+    (proposal: WorkbenchChatCommandProposalInput): ChatCommandProposal => {
+      const descriptor = resolveDescriptor(proposal.commandId, proposal.label);
+      const policy = resolveWorkbenchCommandExecutionPolicy(descriptor, policyInput);
+
+      return {
+        args: proposal.args,
+        commandId: proposal.commandId,
+        description: proposal.description ?? descriptor.description,
+        id: proposal.id ?? createProposalId(proposal.commandId),
+        label: proposal.label ?? descriptor.label,
+        policy,
+        status: policy === 'auto-deny' ? 'blocked' : 'pending',
+      };
+    },
+    [policyInput, resolveDescriptor],
+  );
+
+  const enrichMessageProposals = useCallback(
+    (proposals: readonly WorkbenchChatCommandProposalInput[]) =>
+      proposals.map((proposal) => enrichProposal(proposal)),
+    [enrichProposal],
+  );
+
+  const updateProposalStatus = useCallback(
+    (
+      setMessages: Dispatch<SetStateAction<ChatMessage[]>>,
+      messageId: string,
+      proposalId: string,
+      status: ChatCommandProposal['status'],
+    ) => {
+      setMessages((currentMessages) =>
+        currentMessages.map((message) => {
+          if (message.id !== messageId || !message.commandProposals) {
+            return message;
+          }
+
+          return {
+            ...message,
+            commandProposals: message.commandProposals.map((proposal) =>
+              proposal.id === proposalId ? { ...proposal, status } : proposal,
+            ),
+          };
+        }),
+      );
+    },
+    [],
+  );
+
+  const runProposal = useCallback(
+    async (
+      setMessages: Dispatch<SetStateAction<ChatMessage[]>>,
+      messageId: string,
+      proposal: ChatCommandProposal,
+    ) => {
+      if (runningProposalIds.current.has(proposal.id)) {
+        return;
+      }
+
+      const descriptor = resolveDescriptor(proposal.commandId, proposal.label);
+      if (!isWorkbenchCommandRunnable(descriptor)) {
+        updateProposalStatus(setMessages, messageId, proposal.id, 'failed');
+        onCommandResult?.({
+          commandId: proposal.commandId,
+          label: proposal.label,
+          message: descriptor.disabledReason ?? 'Command is currently unavailable.',
+          status: 'error',
+        });
+        return;
+      }
+
+      runningProposalIds.current.add(proposal.id);
+      updateProposalStatus(setMessages, messageId, proposal.id, 'running');
+
+      try {
+        await executeCommand(proposal.commandId, ...(proposal.args ?? []));
+        updateProposalStatus(setMessages, messageId, proposal.id, 'executed');
+        onCommandResult?.({
+          commandId: proposal.commandId,
+          label: proposal.label,
+          status: 'success',
+        });
+      } catch (error) {
+        updateProposalStatus(setMessages, messageId, proposal.id, 'failed');
+        onCommandResult?.({
+          commandId: proposal.commandId,
+          label: proposal.label,
+          message: getCommandErrorMessage(error),
+          status: 'error',
+        });
+      } finally {
+        runningProposalIds.current.delete(proposal.id);
+      }
+    },
+    [executeCommand, onCommandResult, resolveDescriptor, updateProposalStatus],
+  );
+
+  const processAutoPolicies = useCallback(
+    (
+      setMessages: Dispatch<SetStateAction<ChatMessage[]>>,
+      messageId: string,
+      proposals: readonly ChatCommandProposal[],
+    ) => {
+      proposals.forEach((proposal) => {
+        if (proposal.policy === 'auto-allow' && proposal.status === 'pending') {
+          void runProposal(setMessages, messageId, proposal);
+        }
+      });
+    },
+    [runProposal],
+  );
+
+  const createProposalHandlers = useCallback(
+    (setMessages: Dispatch<SetStateAction<ChatMessage[]>>) => ({
+      onProposalAllow: (messageId: string, proposal: ChatCommandProposal) => {
+        if (proposal.status !== 'pending' || proposal.policy !== 'approval-required') {
+          return;
+        }
+
+        updateProposalStatus(setMessages, messageId, proposal.id, 'allowed');
+        void runProposal(setMessages, messageId, proposal);
+      },
+      onProposalDeny: (messageId: string, proposal: ChatCommandProposal) => {
+        if (proposal.status !== 'pending') {
+          return;
+        }
+
+        updateProposalStatus(setMessages, messageId, proposal.id, 'denied');
+      },
+    }),
+    [runProposal, updateProposalStatus],
+  );
+
+  return {
+    createProposalHandlers,
+    enrichMessageProposals,
+    processAutoPolicies,
+  };
+}

package/src/chat/view-data.ts

@@ -0,0 +1,20 @@
+export const BUILTIN_CHAT_VIEW_RENDER_KIND = 'workbench-kit.builtin.chat.view' as const;
+
+export type BuiltinChatViewMode = 'aiChat' | 'chatting';
+
+export interface BuiltinChatViewRenderData {
+  readonly kind: typeof BUILTIN_CHAT_VIEW_RENDER_KIND;
+  readonly mode: BuiltinChatViewMode;
+}
+
+export function isBuiltinChatViewRenderData(value: unknown): value is BuiltinChatViewRenderData {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+
+  const candidate = value as Partial<BuiltinChatViewRenderData>;
+  return (
+    candidate.kind === BUILTIN_CHAT_VIEW_RENDER_KIND &&
+    (candidate.mode === 'chatting' || candidate.mode === 'aiChat')
+  );
+}