@seed-ship/mcp-ui-solid 5.1.0 → 5.3.0

package/docs/recipes/feedback-inline-wiring.md

@@ -0,0 +1,142 @@
+# Recipe — Wire `<FeedbackInline>` to a feedback HTTP endpoint
+
+> **Audience** : consumer apps that ship `<FeedbackInline>` (per-message
+> thumbs-up/down) and want to persist ratings to a backend.
+>
+> mcp-ui's `<FeedbackInline>` is intentionally endpoint-agnostic — it
+> calls `onSubmit(rating, context)` and the consumer owns the HTTP / store
+> wiring. This recipe shows the most common pattern, using the Deposium
+> `POST /api/feedback` endpoint as a concrete example.
+
+## What `<FeedbackInline>` gives you
+
+```tsx
+<FeedbackInline
+  messageHash={msg.hash}
+  context={{ intent: msg.intent, confidenceBand: msg.band }}
+  onSubmit={(rating, context) => persistFeedback(rating, context)}
+/>
+```
+
+The component :
+- Renders two buttons (positive / negative).
+- Flips to "submitted" optimistically on click — UI does NOT revert on network error (best-effort design).
+- Calls `onSubmit('positive' | 'negative', context?)` exactly once.
+
+`rating` already matches the shape Deposium expects. Mapping is direct.
+
+## Endpoint reference (Deposium)
+
+`POST /api/feedback` — no auth required, behind the chat-stream / standard
+middleware chain.
+
+### Request body
+
+```ts
+interface FeedbackRequest {
+  message_hash: string                           // REQUIRED — message ID being rated
+  rating: 'positive' | 'negative' | 'partial'
+  confidence_band?: 'high' | 'medium' | 'low'    // optional, free-form string
+  intent?: string                                // optional, e.g. 'search_query'
+  space_ids?: string[] | string | null
+  comment?: string
+  tenant_id?: string
+}
+```
+
+### Response
+
+| Status | Body |
+|---|---|
+| 200    | `{ ok: true, id: 'fb_<timestamp>_<rand4>' }` |
+| 400    | `{ error: 'rating must be one of: positive, negative, partial' }` |
+
+### Side effects (worth knowing)
+
+- `INSERT` into `logs.feedback` (PostgreSQL) — drives dashboard analytics.
+- `'positive' | 'negative'` ratings also update
+  `logs.intent_classifications.feedback_success`. `'partial'` does **not**
+  propagate (intentional — neither true nor false).
+
+## Wiring (the recipe)
+
+```tsx
+import { FeedbackInline, type FeedbackInlineContext } from '@seed-ship/mcp-ui-solid'
+
+function persistFeedback(
+  messageHash: string,
+  rating: 'positive' | 'negative',
+  ctx?: FeedbackInlineContext
+): Promise<void> {
+  return fetch('/api/feedback', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      message_hash: messageHash,
+      rating, // 'positive' | 'negative' — matches endpoint as-is
+      ...(ctx?.intent && { intent: ctx.intent }),
+      ...(ctx?.confidenceBand && { confidence_band: ctx.confidenceBand }),
+      ...(ctx?.tenantId && { tenant_id: ctx.tenantId }),
+      ...(ctx?.spaceIds && { space_ids: ctx.spaceIds }),
+      ...(ctx?.comment && { comment: ctx.comment }),
+    }),
+  }).then(async (res) => {
+    if (!res.ok) {
+      console.warn('[feedback] persist failed', res.status, await res.text())
+    }
+  }).catch((err) => {
+    // Silent failure — UI is already in the optimistic "submitted" state.
+    console.warn('[feedback] network error', err)
+  })
+}
+
+function MessageRow(props: { msg: ChatMessage }) {
+  return (
+    <div class="message-row">
+      <p>{props.msg.text}</p>
+      <FeedbackInline
+        messageHash={props.msg.hash}
+        context={{
+          intent: props.msg.intent,
+          confidenceBand: props.msg.confidenceBand,
+        }}
+        onSubmit={(rating, ctx) => persistFeedback(props.msg.hash, rating, ctx)}
+      />
+    </div>
+  )
+}
+```
+
+## Variations
+
+### "Partial" rating
+
+`<FeedbackInline>` emits only `'positive'` / `'negative'`. If you need a
+third state (`'partial'`), build a separate UI (e.g. a star rating or a
+3-button row) and call the endpoint directly with `rating: 'partial'`.
+
+### Free-text comment
+
+Add a textarea below `<FeedbackInline>` that opens after the rating click.
+Send a follow-up `POST /api/feedback` with the same `message_hash` and a
+`comment` field — the endpoint accepts multiple records per message.
+
+### Optimistic vs strict semantics
+
+Default behavior is best-effort (UI never reverts). If you need stricter
+semantics — offline retry queue, edit-rating UX — wrap `<FeedbackInline>`
+in your own component and own the state externally instead of relying on
+the component's internal flip.
+
+## Where this code lives
+
+In your consumer app. mcp-ui ships `<FeedbackInline>` and the `onSubmit`
+contract; the HTTP wiring (URL, auth, retry policy, schema mapping) is
+the consumer's responsibility by design — same pattern as
+`pseudo-elicit-spec-adapter`.
+
+## Reference
+
+- mcp-ui component : `<FeedbackInline>` (exported from `@seed-ship/mcp-ui-solid`)
+- mcp-ui types : `FeedbackInlineProps`, `FeedbackInlineContext`
+- Deposium endpoint : `POST /api/feedback` — see deposium_MCPs `src/routes/feedback.ts`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seed-ship/mcp-ui-solid",
-  "version": "5.1.0",
+  "version": "5.3.0",
   "description": "SolidJS components for rendering MCP-generated UI resources",
   "type": "module",
   "main": "./dist/index.cjs",

package/src/components/ElicitationForm.test.tsx

@@ -0,0 +1,197 @@
+/**
+ * Tests for ElicitationForm — v5.3.0
+ *
+ * Coverage focus : the inverse mapping (ChatPromptResponse → spec content)
+ * that this wrapper owns. The forward mapping (spec → ChatPromptConfig) is
+ * already covered by `chat-bus.test.ts elicitationToPromptConfig`.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { render, fireEvent, cleanup } from '@solidjs/testing-library'
+import { ElicitationForm } from './ElicitationForm'
+import type { ElicitationEvent } from '../types/chat-bus'
+
+describe('ElicitationForm — v5.3.0', () => {
+  beforeEach(() => {
+    cleanup()
+  })
+
+  it('boolean property → confirm UI → onAccept gets { propName: true }', () => {
+    const onAccept = vi.fn()
+    const event: ElicitationEvent = {
+      message: 'Proceed?',
+      requestedSchema: {
+        type: 'object',
+        properties: {
+          consent: { type: 'boolean', description: 'I agree' },
+        },
+        required: ['consent'],
+      },
+    }
+
+    const { getByText } = render(() => (
+      <ElicitationForm event={event} onAccept={onAccept} onCancel={() => {}} />
+    ))
+
+    // ChatPrompt renders a Confirm button — find and click it.
+    const confirmBtn = getByText('Confirm') as HTMLElement
+    fireEvent.click(confirmBtn)
+
+    expect(onAccept).toHaveBeenCalledTimes(1)
+    expect(onAccept).toHaveBeenCalledWith({ consent: true })
+  })
+
+  it('single enum property → choice UI → onAccept gets { propName: enumValue }', () => {
+    const onAccept = vi.fn()
+    const event: ElicitationEvent = {
+      message: 'Pick a tier',
+      requestedSchema: {
+        type: 'object',
+        properties: {
+          tier: {
+            type: 'string',
+            enum: ['free', 'pro', 'enterprise'],
+            enumNames: ['Free', 'Pro', 'Enterprise'],
+          },
+        },
+      },
+    }
+
+    const { getByText } = render(() => (
+      <ElicitationForm event={event} onAccept={onAccept} />
+    ))
+
+    fireEvent.click(getByText('Pro') as HTMLElement)
+
+    expect(onAccept).toHaveBeenCalledWith({ tier: 'pro' })
+  })
+
+  it('numeric enum property → onAccept coerces value to number', () => {
+    const onAccept = vi.fn()
+    const event: ElicitationEvent = {
+      message: 'Pick a level',
+      requestedSchema: {
+        type: 'object',
+        properties: {
+          level: { type: 'integer', enum: [1, 2, 3] },
+        },
+      },
+    }
+
+    const { getByText } = render(() => (
+      <ElicitationForm event={event} onAccept={onAccept} />
+    ))
+
+    fireEvent.click(getByText('2') as HTMLElement)
+
+    expect(onAccept).toHaveBeenCalledWith({ level: 2 })
+  })
+
+  it('multi-property schema → form UI → onAccept gets formValues unchanged', () => {
+    const onAccept = vi.fn()
+    const event: ElicitationEvent = {
+      message: 'Tenant scope required',
+      requestedSchema: {
+        type: 'object',
+        properties: {
+          tenant_id: { type: 'string', title: 'Tenant ID' },
+          space_id: { type: 'string', title: 'Space ID', default: 'default' },
+        },
+        required: ['tenant_id', 'space_id'],
+      },
+    }
+
+    const { container, getByText } = render(() => (
+      <ElicitationForm event={event} onAccept={onAccept} />
+    ))
+
+    const tenantInput = container.querySelector('input[name="tenant_id"]') as HTMLInputElement
+    const spaceInput = container.querySelector('input[name="space_id"]') as HTMLInputElement
+    expect(tenantInput).toBeTruthy()
+    expect(spaceInput).toBeTruthy()
+
+    fireEvent.input(tenantInput, { target: { value: 'acme-co' } })
+    fireEvent.input(spaceInput, { target: { value: 'prod' } })
+
+    const submitBtn = getByText('Submit') as HTMLElement
+    fireEvent.click(submitBtn)
+
+    expect(onAccept).toHaveBeenCalledTimes(1)
+    const [content] = onAccept.mock.calls[0]
+    expect(content).toMatchObject({ tenant_id: 'acme-co', space_id: 'prod' })
+  })
+
+  it('X dismiss → onCancel fires, onAccept does NOT', () => {
+    const onAccept = vi.fn()
+    const onCancel = vi.fn()
+    const event: ElicitationEvent = {
+      message: 'Pick a tier',
+      requestedSchema: {
+        type: 'object',
+        properties: {
+          tier: { type: 'string', enum: ['a', 'b'] },
+        },
+      },
+    }
+
+    const { container } = render(() => (
+      <ElicitationForm event={event} onAccept={onAccept} onCancel={onCancel} />
+    ))
+
+    const dismissBtn = container.querySelector('[aria-label="Dismiss"]') as HTMLElement
+    fireEvent.click(dismissBtn)
+
+    expect(onCancel).toHaveBeenCalledTimes(1)
+    expect(onAccept).not.toHaveBeenCalled()
+  })
+
+  it('onDecline takes precedence over onCancel when provided', () => {
+    const onAccept = vi.fn()
+    const onCancel = vi.fn()
+    const onDecline = vi.fn()
+    const event: ElicitationEvent = {
+      message: 'Proceed?',
+      requestedSchema: {
+        type: 'object',
+        properties: { consent: { type: 'boolean' } },
+      },
+    }
+
+    const { getByText } = render(() => (
+      <ElicitationForm
+        event={event}
+        onAccept={onAccept}
+        onCancel={onCancel}
+        onDecline={onDecline}
+        dismissLabel="Decline"
+      />
+    ))
+
+    fireEvent.click(getByText('Decline') as HTMLElement)
+
+    expect(onDecline).toHaveBeenCalledTimes(1)
+    expect(onCancel).not.toHaveBeenCalled()
+    expect(onAccept).not.toHaveBeenCalled()
+  })
+
+  it('confirm cancel button → onCancel fires (dismissed=true via cancel button)', () => {
+    const onAccept = vi.fn()
+    const onCancel = vi.fn()
+    const event: ElicitationEvent = {
+      message: 'Proceed?',
+      requestedSchema: {
+        type: 'object',
+        properties: { consent: { type: 'boolean' } },
+      },
+    }
+
+    const { getByText } = render(() => (
+      <ElicitationForm event={event} onAccept={onAccept} onCancel={onCancel} />
+    ))
+
+    fireEvent.click(getByText('Cancel') as HTMLElement)
+
+    expect(onCancel).toHaveBeenCalledTimes(1)
+    expect(onAccept).not.toHaveBeenCalled()
+  })
+})

package/src/components/ElicitationForm.tsx

@@ -0,0 +1,126 @@
+/**
+ * ElicitationForm — schema-driven renderer for MCP `elicitation/create` requests
+ *
+ * @experimental
+ * @since v5.3.0
+ *
+ * Thin wrapper over `<ChatPrompt>` + `elicitationToPromptConfig()` that
+ * accepts a spec-shaped `ElicitationEvent` (MCP 2025-06-18) and exposes a
+ * spec-shaped `onAccept(content)` callback whose payload is ready to send
+ * back as the `accept` outcome of an `elicitation/create` reply.
+ *
+ * The mapping (boolean → confirm, single enum ≤4 → choice, else → form) is
+ * delegated to the `elicitationToPromptConfig` helper — same rules, same
+ * tests. This component owns the inverse mapping : extracting a spec-shaped
+ * `Record<string, unknown>` from the `ChatPromptResponse`.
+ *
+ * ## Outcome semantics (per MCP spec 2025-06-18)
+ *
+ * | User action                           | Callback fired     | Payload                          |
+ * |---------------------------------------|--------------------|----------------------------------|
+ * | Submit form / pick choice / confirm   | `onAccept(content)`| `{ [propName]: value, ... }`     |
+ * | X icon / Cancel button                | `onCancel()` *or* `onDecline()` if provided | none                |
+ *
+ * mcp-ui's `<ChatPrompt>` does not natively distinguish "decline" (explicit
+ * refusal) from "cancel" (passive close). To surface a decline action,
+ * pass `dismissLabel="Decline"` and route the callback via `onDecline`.
+ *
+ * @example
+ * ```tsx
+ * bus.events.on('onElicitation', ({ elicitation }) => {
+ *   render(() => (
+ *     <ElicitationForm
+ *       event={elicitation}
+ *       onAccept={(content) => sendElicitationReply({ action: 'accept', content })}
+ *       onCancel={() => sendElicitationReply({ action: 'cancel' })}
+ *     />
+ *   ), mountPoint)
+ * })
+ * ```
+ */
+
+import { Component } from 'solid-js'
+import { ChatPrompt } from './ChatPrompt'
+import { elicitationToPromptConfig } from '../services/chat-bus'
+import type {
+  ChatPromptResponse,
+  ElicitationEvent,
+  ElicitationPropertySchema,
+} from '../types/chat-bus'
+
+export interface ElicitationFormProps {
+  /** MCP `elicitation/create` request payload to render. */
+  event: ElicitationEvent
+  /**
+   * Called when user submits a valid response. `content` is keyed by the
+   * elicitation `requestedSchema.properties` names — ready to send back as
+   * the `accept` outcome of an `elicitation/create` reply.
+   */
+  onAccept: (content: Record<string, unknown>) => void
+  /** Called when user dismisses (X icon, confirm-cancel button). */
+  onCancel?: () => void
+  /**
+   * Optional explicit decline action. When provided, takes precedence over
+   * `onCancel` on dismiss. Pair with `dismissLabel="Decline"` to surface as
+   * a decline action in the UI.
+   */
+  onDecline?: () => void
+  /** Label on the dismiss button (default: X icon). */
+  dismissLabel?: string
+}
+
+/**
+ * @experimental
+ * Schema-driven renderer for MCP `elicitation/create` requests.
+ */
+export const ElicitationForm: Component<ElicitationFormProps> = (props) => {
+  const config = () => elicitationToPromptConfig(props.event)
+
+  const handleSubmit = (response: ChatPromptResponse): void => {
+    if (response.dismissed) {
+      ;(props.onDecline ?? props.onCancel)?.()
+      return
+    }
+    props.onAccept(extractContent(response, props.event))
+  }
+
+  return <ChatPrompt config={config()} dismissLabel={props.dismissLabel} onSubmit={handleSubmit} />
+}
+
+function extractContent(
+  response: ChatPromptResponse,
+  event: ElicitationEvent
+): Record<string, unknown> {
+  // Form: response.value is already a Record keyed by property names.
+  if (typeof response.value !== 'string') {
+    return response.value
+  }
+
+  const propEntries = Object.entries(event.requestedSchema.properties)
+
+  // Single-property cases (boolean confirm or single enum choice).
+  if (propEntries.length === 1) {
+    const [name, schema] = propEntries[0]
+    return { [name]: coerceScalar(response.value, schema) }
+  }
+
+  // Multi-property string response — shouldn't happen since the helper
+  // routes multi-prop schemas to 'form'. Fall back gracefully.
+  console.warn(
+    '[MCP-UI] ElicitationForm: received string value for multi-property schema. Falling back to _value.'
+  )
+  return { _value: response.value }
+}
+
+function coerceScalar(value: string, schema: ElicitationPropertySchema): unknown {
+  // Confirm always emits the literal 'confirmed' on accept (cancel path is
+  // trapped earlier by `dismissed: true`). Map to boolean true.
+  if (schema.type === 'boolean') return true
+
+  if (schema.type === 'number' || schema.type === 'integer') {
+    const n = Number(value)
+    return Number.isFinite(n) ? n : value
+  }
+
+  return value
+}

package/src/components/FeedbackInline.test.tsx

@@ -0,0 +1,117 @@
+/**
+ * Tests for FeedbackInline component — v5.2.0
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { render, fireEvent, cleanup } from '@solidjs/testing-library'
+import { FeedbackInline } from './FeedbackInline'
+
+describe('FeedbackInline — v5.2.0', () => {
+  beforeEach(() => {
+    cleanup()
+  })
+
+  it('renders two rating buttons by default', () => {
+    const { container } = render(() => <FeedbackInline onSubmit={() => {}} />)
+    const positive = container.querySelector('[data-feedback-inline-rating="positive"]')
+    const negative = container.querySelector('[data-feedback-inline-rating="negative"]')
+    expect(positive).toBeDefined()
+    expect(negative).toBeDefined()
+  })
+
+  it('click thumb-up calls onSubmit with positive + context and shows ack', () => {
+    const onSubmit = vi.fn()
+    const { container, getByText } = render(() => (
+      <FeedbackInline
+        onSubmit={onSubmit}
+        context={{ intent: 'search', confidenceBand: 'high' }}
+      />
+    ))
+    const positive = container.querySelector(
+      '[data-feedback-inline-rating="positive"]'
+    ) as HTMLElement
+    fireEvent.click(positive)
+
+    expect(onSubmit).toHaveBeenCalledTimes(1)
+    expect(onSubmit).toHaveBeenCalledWith('positive', {
+      intent: 'search',
+      confidenceBand: 'high',
+    })
+    expect(getByText('Merci !')).toBeDefined()
+  })
+
+  it('click thumb-down calls onSubmit with negative and shows negative ack', () => {
+    const onSubmit = vi.fn()
+    const { container, getByText } = render(() => <FeedbackInline onSubmit={onSubmit} />)
+    const negative = container.querySelector(
+      '[data-feedback-inline-rating="negative"]'
+    ) as HTMLElement
+    fireEvent.click(negative)
+
+    expect(onSubmit).toHaveBeenCalledWith('negative', undefined)
+    expect(getByText("Noté, on s'améliore")).toBeDefined()
+  })
+
+  it('second click after rating is a no-op (final state)', () => {
+    const onSubmit = vi.fn()
+    const { container } = render(() => <FeedbackInline onSubmit={onSubmit} />)
+    const positive = container.querySelector(
+      '[data-feedback-inline-rating="positive"]'
+    ) as HTMLElement
+    fireEvent.click(positive)
+    // After first click, buttons are replaced by ack text — there's no button
+    // to click, but verify onSubmit isn't called again via any stale ref
+    expect(onSubmit).toHaveBeenCalledTimes(1)
+    expect(container.querySelector('[data-feedback-inline-rating]')).toBeNull()
+  })
+
+  it('custom positiveAck / negativeAck text is rendered', () => {
+    const { container, getByText, unmount } = render(() => (
+      <FeedbackInline
+        onSubmit={() => {}}
+        positiveAck="Thanks!"
+        negativeAck="Got it, sorry"
+      />
+    ))
+    const positive = container.querySelector(
+      '[data-feedback-inline-rating="positive"]'
+    ) as HTMLElement
+    fireEvent.click(positive)
+    expect(getByText('Thanks!')).toBeDefined()
+    unmount()
+
+    const second = render(() => (
+      <FeedbackInline
+        onSubmit={() => {}}
+        positiveAck="Thanks!"
+        negativeAck="Got it, sorry"
+      />
+    ))
+    const negative = second.container.querySelector(
+      '[data-feedback-inline-rating="negative"]'
+    ) as HTMLElement
+    fireEvent.click(negative)
+    expect(second.getByText('Got it, sorry')).toBeDefined()
+  })
+
+  it('onSubmit promise rejection is swallowed (best-effort, UI still flips)', () => {
+    const onSubmit = vi.fn().mockRejectedValue(new Error('network down'))
+    const { container, getByText } = render(() => <FeedbackInline onSubmit={onSubmit} />)
+    const positive = container.querySelector(
+      '[data-feedback-inline-rating="positive"]'
+    ) as HTMLElement
+    // Should not throw even though onSubmit rejects
+    expect(() => fireEvent.click(positive)).not.toThrow()
+    expect(getByText('Merci !')).toBeDefined()
+  })
+
+  it('works without messageHash or context', () => {
+    const onSubmit = vi.fn()
+    const { container } = render(() => <FeedbackInline onSubmit={onSubmit} />)
+    const positive = container.querySelector(
+      '[data-feedback-inline-rating="positive"]'
+    ) as HTMLElement
+    fireEvent.click(positive)
+    expect(onSubmit).toHaveBeenCalledWith('positive', undefined)
+  })
+})