@seed-ship/mcp-ui-solid 5.0.0 → 5.2.0

package/src/services/chat-bus.test.ts

@@ -3,8 +3,8 @@
  */
 
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
-import { createEventEmitter, createCommandHandler, createChatBus, clarificationToPromptConfig } from './chat-bus'
-import type { ChatEvents, ChatCommands, ClarificationEvent } from '../types/chat-bus'
+import { createEventEmitter, createCommandHandler, createChatBus, clarificationToPromptConfig, elicitationToPromptConfig } from './chat-bus'
+import type { ChatEvents, ChatCommands, ClarificationEvent, ElicitationEvent } from '../types/chat-bus'
 
 describe('createEventEmitter', () => {
   it('emits events to subscribed listeners', () => {
@@ -384,3 +384,155 @@ describe('clarificationToPromptConfig', () => {
     expect(opts[0]).not.toHaveProperty('metadata')
   })
 })
+
+describe('elicitationToPromptConfig — v5.2.0', () => {
+  it('single boolean property maps to confirm prompt', () => {
+    const event: ElicitationEvent = {
+      message: 'Proceed with the deployment?',
+      requestedSchema: {
+        type: 'object',
+        properties: { confirmed: { type: 'boolean', description: 'Ship it?' } },
+        required: ['confirmed'],
+      },
+    }
+    const config = elicitationToPromptConfig(event)
+    expect(config.type).toBe('confirm')
+    expect(config.title).toBe('Proceed with the deployment?')
+    expect((config.config as any).message).toBe('Ship it?')
+  })
+
+  it('single enum string property (≤4 values) maps to choice prompt', () => {
+    const event: ElicitationEvent = {
+      message: 'Select severity',
+      requestedSchema: {
+        type: 'object',
+        properties: {
+          level: {
+            type: 'string',
+            enum: ['low', 'medium', 'high'],
+            enumNames: ['Low', 'Medium', 'High'],
+          },
+        },
+      },
+    }
+    const config = elicitationToPromptConfig(event)
+    expect(config.type).toBe('choice')
+    const opts = (config.config as any).options
+    expect(opts).toEqual([
+      { value: 'low', label: 'Low' },
+      { value: 'medium', label: 'Medium' },
+      { value: 'high', label: 'High' },
+    ])
+  })
+
+  it('enum with >4 values maps to form with select field (not choice)', () => {
+    const event: ElicitationEvent = {
+      message: 'Pick a country',
+      requestedSchema: {
+        type: 'object',
+        properties: {
+          country: {
+            type: 'string',
+            enum: ['FR', 'DE', 'IT', 'ES', 'PT'],
+          },
+        },
+      },
+    }
+    const config = elicitationToPromptConfig(event)
+    expect(config.type).toBe('form')
+    const fields = (config.config as any).fields
+    expect(fields[0].type).toBe('select')
+    expect(fields[0].options).toHaveLength(5)
+  })
+
+  it('multi-property object maps to form with one field per property', () => {
+    const event: ElicitationEvent = {
+      message: 'Fill in contact info',
+      requestedSchema: {
+        type: 'object',
+        properties: {
+          name: { type: 'string', title: 'Full name' },
+          age: { type: 'integer' },
+          newsletter: { type: 'boolean', description: 'Opt-in' },
+        },
+        required: ['name'],
+      },
+    }
+    const config = elicitationToPromptConfig(event)
+    expect(config.type).toBe('form')
+    const fields = (config.config as any).fields
+    expect(fields).toHaveLength(3)
+    expect(fields.map((f: any) => f.name)).toEqual(['name', 'age', 'newsletter'])
+    expect(fields[0]).toMatchObject({ type: 'text', label: 'Full name', required: true })
+    expect(fields[1]).toMatchObject({ type: 'number', required: false })
+    expect(fields[2]).toMatchObject({ type: 'checkbox', helpText: 'Opt-in' })
+  })
+
+  it('string format email maps to email field', () => {
+    const event: ElicitationEvent = {
+      message: 'Contact',
+      requestedSchema: {
+        type: 'object',
+        properties: {
+          email: { type: 'string', format: 'email' },
+          reply: { type: 'string' }, // force form (not single-property shortcut)
+        },
+      },
+    }
+    const config = elicitationToPromptConfig(event)
+    const fields = (config.config as any).fields
+    expect(fields[0]).toMatchObject({ name: 'email', type: 'email' })
+  })
+
+  it('string format date / date-time maps to date field', () => {
+    const event: ElicitationEvent = {
+      message: 'Schedule',
+      requestedSchema: {
+        type: 'object',
+        properties: {
+          start: { type: 'string', format: 'date' },
+          end: { type: 'string', format: 'date-time' },
+        },
+      },
+    }
+    const config = elicitationToPromptConfig(event)
+    const fields = (config.config as any).fields
+    expect(fields[0].type).toBe('date')
+    expect(fields[1].type).toBe('date')
+  })
+
+  it('default value maps to placeholder', () => {
+    const event: ElicitationEvent = {
+      message: 'Settings',
+      requestedSchema: {
+        type: 'object',
+        properties: {
+          retries: { type: 'integer', default: 3 },
+          timeout: { type: 'integer' }, // second property to force form
+        },
+      },
+    }
+    const config = elicitationToPromptConfig(event)
+    const fields = (config.config as any).fields
+    expect(fields[0]).toMatchObject({ placeholder: '3' })
+  })
+
+  it('unknown schema type falls through to text with console.warn', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const event = {
+      message: 'Edge case',
+      requestedSchema: {
+        type: 'object',
+        properties: {
+          weird: { type: 'array' }, // not a primitive
+          other: { type: 'string' },
+        },
+      },
+    } as unknown as ElicitationEvent
+    const config = elicitationToPromptConfig(event)
+    const fields = (config.config as any).fields
+    expect(fields[0].type).toBe('text')
+    expect(warnSpy).toHaveBeenCalled()
+    warnSpy.mockRestore()
+  })
+})

package/src/services/chat-bus.ts

@@ -14,7 +14,10 @@ import type {
   EventSubscribeOptions,
   ScratchpadSection,
   ClarificationEvent,
+  ElicitationEvent,
+  ElicitationPropertySchema,
   ChatPromptConfig,
+  FormPromptConfig,
 } from '../types/chat-bus'
 
 // ─── Event Emitter ───────────────────────────────────────────
@@ -245,6 +248,118 @@ export function mergeScratchpadSections(
  *   bus.commands.exec('showChatPrompt', clarificationToPromptConfig(clarification))
  * })
  */
+// ─── Elicitation → Prompt Helper (v5.2.0) ───────────────────
+
+/**
+ * Convert an MCP `elicitation/create` payload into a `ChatPromptConfig`.
+ *
+ * Mapping rules :
+ * - Single `boolean` property → `type: 'confirm'`
+ * - Single property with `enum` of ≤4 values → `type: 'choice'` (one option per enum value)
+ * - Anything else → `type: 'form'` with one field per schema property
+ *
+ * JSON Schema primitive types map to mcp-ui form field types :
+ *
+ * | JSON Schema | mcp-ui FormFieldType |
+ * |---|---|
+ * | `type: 'string'` | `'text'` |
+ * | `type: 'string', format: 'email'` | `'email'` |
+ * | `type: 'string', format: 'date'` or `'date-time'` | `'date'` |
+ * | `type: 'string', enum: [...]` | `'select'` |
+ * | `type: 'number' \| 'integer'` | `'number'` |
+ * | `type: 'boolean'` | `'checkbox'` |
+ *
+ * Unknown shapes fall through to plain text with a `helpText` warning.
+ *
+ * @experimental
+ * @since v5.2.0
+ *
+ * @example
+ * bus.events.on('onElicitation', ({ elicitation }) => {
+ *   bus.commands.exec('showChatPrompt', elicitationToPromptConfig(elicitation))
+ * })
+ */
+export function elicitationToPromptConfig(event: ElicitationEvent): ChatPromptConfig {
+  const propEntries = Object.entries(event.requestedSchema.properties)
+
+  // Shortcut 1 : single boolean → confirm
+  if (propEntries.length === 1 && propEntries[0][1].type === 'boolean') {
+    return {
+      type: 'confirm',
+      title: event.message,
+      config: {
+        message: propEntries[0][1].description,
+      },
+    }
+  }
+
+  // Shortcut 2 : single enum property with ≤4 values → choice
+  if (propEntries.length === 1) {
+    const [, schema] = propEntries[0]
+    if (schema.enum && schema.enum.length > 0 && schema.enum.length <= 4) {
+      return {
+        type: 'choice',
+        title: event.message,
+        config: {
+          options: schema.enum.map((val, idx) => ({
+            value: String(val),
+            label: schema.enumNames?.[idx] ?? String(val),
+          })),
+          layout: 'vertical',
+        },
+      }
+    }
+  }
+
+  // Default : full form
+  const required = new Set(event.requestedSchema.required ?? [])
+  const fields: FormPromptConfig['fields'] = propEntries.map(([name, schema]) => ({
+    name,
+    label: schema.title ?? name,
+    ...schemaToFieldType(schema),
+    required: required.has(name),
+    helpText: schema.description,
+    ...(schema.default !== undefined ? { placeholder: String(schema.default) } : {}),
+  }))
+
+  return {
+    type: 'form',
+    title: event.message,
+    config: { fields },
+  }
+}
+
+function schemaToFieldType(
+  schema: ElicitationPropertySchema
+):
+  | { type: FormPromptConfig['fields'][number]['type']; options?: Array<{ label: string; value: string }> }
+  | { type: FormPromptConfig['fields'][number]['type']; helpText?: string } {
+  // Enum → select
+  if (schema.enum && schema.enum.length > 0) {
+    return {
+      type: 'select',
+      options: schema.enum.map((val, idx) => ({
+        label: schema.enumNames?.[idx] ?? String(val),
+        value: String(val),
+      })),
+    }
+  }
+
+  if (schema.type === 'boolean') return { type: 'checkbox' }
+  if (schema.type === 'number' || schema.type === 'integer') return { type: 'number' }
+  if (schema.type === 'string') {
+    if (schema.format === 'email') return { type: 'email' }
+    if (schema.format === 'date' || schema.format === 'date-time') return { type: 'date' }
+    return { type: 'text' }
+  }
+
+  // Unknown primitive — fall back to text with a warning
+  console.warn(
+    `[MCP-UI] elicitationToPromptConfig: unsupported schema type "${(schema as { type?: string }).type}", falling back to text.`
+  )
+  return { type: 'text' }
+}
+
 export function clarificationToPromptConfig(
   event: ClarificationEvent
 ): ChatPromptConfig {

package/src/services/chat-prompt-controller.test.ts

@@ -0,0 +1,144 @@
+/**
+ * Tests for createChatPromptController — v5.2.0
+ */
+
+import { describe, it, expect } from 'vitest'
+import { createRoot } from 'solid-js'
+import {
+  createChatPromptController,
+  PromptReplacedError,
+} from './chat-prompt-controller'
+import type { ChatPromptConfig, ChatPromptResponse } from '../types/chat-bus'
+
+const choiceConfig = (title = 'Pick one'): ChatPromptConfig => ({
+  type: 'choice',
+  title,
+  config: { options: [{ value: 'a', label: 'A' }, { value: 'b', label: 'B' }] },
+})
+
+const confirmConfig = (title = 'Confirm?'): ChatPromptConfig => ({
+  type: 'confirm',
+  title,
+  config: { message: 'Sure?' },
+})
+
+const choiceResponse = (value: string): ChatPromptResponse => ({
+  type: 'choice',
+  value,
+  label: value,
+})
+
+describe('createChatPromptController — v5.2.0', () => {
+  it('sequential prompts both resolve', async () => {
+    await createRoot(async (dispose) => {
+      const ctrl = createChatPromptController()
+
+      const p1 = ctrl.handle(choiceConfig('First'))
+      expect(ctrl.activePrompt()?.title).toBe('First')
+      ctrl.resolveActive(choiceResponse('a'))
+      expect(ctrl.activePrompt()).toBeNull()
+      const r1 = await p1
+      expect(r1.value).toBe('a')
+
+      const p2 = ctrl.handle(choiceConfig('Second'))
+      expect(ctrl.activePrompt()?.title).toBe('Second')
+      ctrl.resolveActive(choiceResponse('b'))
+      const r2 = await p2
+      expect(r2.value).toBe('b')
+
+      dispose()
+    })
+  })
+
+  it('re-entrant call rejects previous Promise with PromptReplacedError', async () => {
+    await createRoot(async (dispose) => {
+      const ctrl = createChatPromptController()
+
+      const p1 = ctrl.handle(choiceConfig('First'))
+      // Don't resolve — fire a second one
+      const p2 = ctrl.handle(choiceConfig('Second'))
+
+      await expect(p1).rejects.toBeInstanceOf(PromptReplacedError)
+
+      // The second prompt is now active and can still resolve
+      expect(ctrl.activePrompt()?.title).toBe('Second')
+      ctrl.resolveActive(choiceResponse('b'))
+      await expect(p2).resolves.toMatchObject({ value: 'b' })
+
+      dispose()
+    })
+  })
+
+  it('AbortSignal already aborted on entry rejects with DOMException AbortError', async () => {
+    await createRoot(async (dispose) => {
+      const ctrl = createChatPromptController()
+      const ac = new AbortController()
+      ac.abort()
+
+      const p = ctrl.handle(choiceConfig('Never shown'), ac.signal)
+      expect(ctrl.activePrompt()).toBeNull() // UI never installed
+
+      await expect(p).rejects.toMatchObject({ name: 'AbortError' })
+      dispose()
+    })
+  })
+
+  it('AbortSignal aborted during prompt rejects + clears activePrompt', async () => {
+    await createRoot(async (dispose) => {
+      const ctrl = createChatPromptController()
+      const ac = new AbortController()
+
+      const p = ctrl.handle(choiceConfig('Pending'), ac.signal)
+      expect(ctrl.activePrompt()?.title).toBe('Pending')
+
+      ac.abort()
+      await expect(p).rejects.toMatchObject({ name: 'AbortError' })
+      expect(ctrl.activePrompt()).toBeNull()
+
+      dispose()
+    })
+  })
+
+  it('abort() method rejects pending Promise with AbortError', async () => {
+    await createRoot(async (dispose) => {
+      const ctrl = createChatPromptController()
+
+      const p = ctrl.handle(choiceConfig('Will abort'))
+      ctrl.abort('Navigated away')
+
+      await expect(p).rejects.toMatchObject({ name: 'AbortError' })
+      expect(ctrl.activePrompt()).toBeNull()
+
+      dispose()
+    })
+  })
+
+  it('dismissActive resolves with dismissed: true and preserves the prompt type', async () => {
+    await createRoot(async (dispose) => {
+      const ctrl = createChatPromptController()
+      const p = ctrl.handle(confirmConfig('Really?'))
+
+      ctrl.dismissActive()
+      const r = await p
+      expect(r).toMatchObject({ type: 'confirm', dismissed: true })
+      expect(ctrl.activePrompt()).toBeNull()
+
+      dispose()
+    })
+  })
+
+  it('resolve/dismiss after abort is a no-op (double-settle protection)', async () => {
+    await createRoot(async (dispose) => {
+      const ctrl = createChatPromptController()
+      const p = ctrl.handle(choiceConfig('x'))
+
+      ctrl.abort()
+      // These should not throw or re-settle
+      ctrl.resolveActive(choiceResponse('ignored'))
+      ctrl.dismissActive()
+
+      await expect(p).rejects.toMatchObject({ name: 'AbortError' })
+      dispose()
+    })
+  })
+})

package/src/services/chat-prompt-controller.ts

@@ -0,0 +1,214 @@
+/**
+ * createChatPromptController — centralised lifecycle for `showChatPrompt`
+ *
+ * @experimental
+ * @since v5.2.0
+ *
+ * The controller owns the resolver closure, AbortSignal wiring, and
+ * re-entrance policy in one primitive. Consumers go from ~20 LOC of manual
+ * wiring per app to :
+ *
+ * ```ts
+ * const ctrl = createChatPromptController()
+ * bus.commands.handle('showChatPrompt', ctrl.handle)
+ * // ...
+ * <Show when={ctrl.activePrompt()}>
+ *   {(cfg) => (
+ *     <ChatPrompt
+ *       config={cfg()}
+ *       onSubmit={ctrl.resolveActive}
+ *       onDismiss={ctrl.dismissActive}
+ *     />
+ *   )}
+ * </Show>
+ * ```
+ *
+ * ## Re-entrance policy
+ *
+ * If a new `showChatPrompt` arrives while a previous Promise is still
+ * pending, the previous Promise rejects **synchronously** with a
+ * `PromptReplacedError` before the new prompt is installed. Callers that
+ * care can branch on `err instanceof PromptReplacedError` or `err.name ===
+ * 'PromptReplacedError'`.
+ *
+ * ## Abort semantics
+ *
+ * `handle(config, signal?)` honours `AbortSignal` :
+ *
+ * - If `signal.aborted === true` on entry → returns a rejected Promise with
+ *   `new DOMException('Prompt aborted', 'AbortError')`, does NOT set
+ *   `activePrompt`.
+ * - Otherwise registers a once-only listener that rejects with the same
+ *   `DOMException` on abort, clearing the active state.
+ *
+ * `AbortError` is the Web Platform convention (matches `fetch()`,
+ * `Response.body.cancel()`, etc.) — callers can branch on `err.name ===
+ * 'AbortError'` without importing any mcp-ui type.
+ */
+
+import { createSignal, type Accessor } from 'solid-js'
+import type { ChatPromptConfig, ChatPromptResponse } from '../types/chat-bus'
+
+// ─── Error class ─────────────────────────────────────────────
+
+/**
+ * Thrown when an active `showChatPrompt` Promise is rejected because a new
+ * prompt arrived before the previous one resolved. Consumers can use
+ * `instanceof PromptReplacedError` or `err.name === 'PromptReplacedError'` to
+ * branch (retry, bail, log).
+ *
+ * @experimental
+ * @since v5.2.0
+ */
+export class PromptReplacedError extends Error {
+  readonly name = 'PromptReplacedError' as const
+  constructor(message = 'Prompt replaced by a newer one') {
+    super(message)
+  }
+}
+
+// ─── Controller shape ────────────────────────────────────────
+
+export interface ChatPromptController {
+  /**
+   * Register as the bus handler :
+   * `bus.commands.handle('showChatPrompt', ctrl.handle)`
+   */
+  handle: (config: ChatPromptConfig, signal?: AbortSignal) => Promise<ChatPromptResponse>
+
+  /**
+   * Reactive accessor for the currently active prompt config (null when no
+   * prompt is pending). Use in JSX to drive `<ChatPrompt>` rendering.
+   */
+  activePrompt: Accessor<ChatPromptConfig | null>
+
+  /** Call this from `<ChatPrompt>`'s `onSubmit` prop. */
+  resolveActive: (response: ChatPromptResponse) => void
+
+  /** Call this from `<ChatPrompt>`'s `onDismiss` prop. */
+  dismissActive: () => void
+
+  /**
+   * Cancel the active prompt programmatically (e.g. on route change). Rejects
+   * the pending Promise with the supplied reason or an `AbortError`.
+   */
+  abort: (reason?: string) => void
+}
+
+// ─── Factory ─────────────────────────────────────────────────
+
+/**
+ * Create a stateful controller that owns the active prompt Promise, the
+ * AbortSignal listener, and the re-entrance policy. See module JSDoc for
+ * full usage.
+ *
+ * @experimental
+ * @since v5.2.0
+ */
+export function createChatPromptController(): ChatPromptController {
+  const [activePrompt, setActivePrompt] = createSignal<ChatPromptConfig | null>(null)
+
+  interface PendingEntry {
+    type: ChatPromptConfig['type']
+    resolve: (r: ChatPromptResponse) => void
+    reject: (err: unknown) => void
+    signal?: AbortSignal
+    onAbort?: () => void
+  }
+
+  let pending: PendingEntry | null = null
+
+  function cleanupAbort(entry: PendingEntry): void {
+    if (entry.signal && entry.onAbort) {
+      entry.signal.removeEventListener('abort', entry.onAbort)
+    }
+  }
+
+  function clearPending(): void {
+    if (pending) {
+      cleanupAbort(pending)
+      pending = null
+    }
+    setActivePrompt(null)
+  }
+
+  function handle(
+    config: ChatPromptConfig,
+    signal?: AbortSignal
+  ): Promise<ChatPromptResponse> {
+    // Re-entrance : synchronously reject the previous Promise before
+    // installing the new prompt. The caller's .catch sees the rejection
+    // on the microtask boundary regardless.
+    if (pending) {
+      const previous = pending
+      pending = null
+      cleanupAbort(previous)
+      previous.reject(new PromptReplacedError())
+    }
+
+    // Abort already tripped on entry : return a rejected Promise without
+    // ever showing the UI.
+    if (signal?.aborted) {
+      setActivePrompt(null)
+      return Promise.reject(new DOMException('Prompt aborted', 'AbortError'))
+    }
+
+    return new Promise<ChatPromptResponse>((resolve, reject) => {
+      const entry: PendingEntry = { type: config.type, resolve, reject, signal }
+
+      if (signal) {
+        entry.onAbort = () => {
+          // If this entry is still active, reject + clear. If a newer prompt
+          // has since replaced it, the cleanup already ran — no-op.
+          if (pending === entry) {
+            pending = null
+            cleanupAbort(entry)
+            setActivePrompt(null)
+            reject(new DOMException('Prompt aborted', 'AbortError'))
+          }
+        }
+        signal.addEventListener('abort', entry.onAbort, { once: true })
+      }
+
+      pending = entry
+      setActivePrompt(config)
+    })
+  }
+
+  function resolveActive(response: ChatPromptResponse): void {
+    if (!pending) return
+    const entry = pending
+    pending = null
+    cleanupAbort(entry)
+    setActivePrompt(null)
+    entry.resolve(response)
+  }
+
+  function dismissActive(): void {
+    if (!pending) return
+    const entry = pending
+    pending = null
+    cleanupAbort(entry)
+    setActivePrompt(null)
+    // Surface as a resolved Promise with dismissed: true — matches existing
+    // ChatPrompt onDismiss contract from v4.x.
+    entry.resolve({ type: entry.type, value: '', label: '', dismissed: true })
+  }
+
+  function abort(reason = 'Prompt aborted'): void {
+    if (!pending) return
+    const entry = pending
+    pending = null
+    cleanupAbort(entry)
+    setActivePrompt(null)
+    entry.reject(new DOMException(reason, 'AbortError'))
+  }
+
+  return {
+    handle,
+    activePrompt,
+    resolveActive,
+    dismissActive,
+    abort,
+  }
+}