@seed-ship/mcp-ui-solid 6.19.1 → 6.20.0

package/src/hooks/index.ts

@@ -4,9 +4,10 @@
  * SolidJS hooks for managing UI resource state and streaming
  */
 
-export { useStreamingUI } from './useStreamingUI'
+export { useStreamingUI, DEFAULT_STREAMING_UI_MESSAGES } from './useStreamingUI'
 export type {
   UseStreamingUIOptions,
+  StreamingUIMessages,
   StreamingUIState,
   StreamProgress,
   StreamError,

package/src/hooks/useStreamingUI.ts

@@ -24,6 +24,7 @@
 import { createSignal, onCleanup } from 'solid-js'
 import type { UIComponent } from '../types'
 import { createLogger } from '../utils/logger'
+import { formatMCPUIString } from '../utils/format-string'
 
 const logger = createLogger('useStreamingUI')
 
@@ -34,6 +35,50 @@ const isServer = typeof window === 'undefined'
 // Types
 // ============================================================================
 
+/**
+ * Every string `useStreamingUI` puts into `progress().message` and
+ * `error()` — both are rendered by `<StreamingUIRenderer>`.
+ *
+ * @since v6.20.0 — `StreamingUIRenderer` feeds these from `MCPUIStrings`
+ * (`stream*` keys); a host calling the hook directly passes `messages`.
+ */
+export interface StreamingUIMessages {
+  /** Initial progress message. */
+  initializing: string
+  /** Progress message while the request is sent. */
+  connecting: string
+  /** Progress message on `component-start`. Template — `{type}`. */
+  loadingComponent: string
+  /** Progress message on `complete`. */
+  dashboardLoaded: string
+  /** Progress message after an error. Template — `{message}`. */
+  errorProgress: string
+  /** `StreamError.error` when the fetch / read fails. */
+  connectionFailed: string
+  /** `StreamError.message` when the server answers non-OK without a message. */
+  requestFailed: string
+  /** `StreamError.message` when the response has no body. */
+  emptyResponse: string
+  /** `StreamError.message` when streaming starts during SSR. */
+  serverSide: string
+  /** `StreamError.message` when the failure carries no message. */
+  unknownError: string
+}
+
+/** English defaults of {@link StreamingUIMessages}. */
+export const DEFAULT_STREAMING_UI_MESSAGES: StreamingUIMessages = {
+  initializing: 'Initializing...',
+  connecting: 'Connecting to server...',
+  loadingComponent: 'Loading {type} component...',
+  dashboardLoaded: 'Dashboard loaded',
+  errorProgress: 'Error: {message}',
+  connectionFailed: 'Stream connection failed',
+  requestFailed: 'Stream request failed',
+  emptyResponse: 'Response body is null',
+  serverSide: 'Streaming UI cannot start on server-side',
+  unknownError: 'Unknown error',
+}
+
 export interface UseStreamingUIOptions {
   query: string
   spaceIds?: string[]
@@ -47,6 +92,12 @@ export interface UseStreamingUIOptions {
   onComplete?: (metadata: CompleteMetadata) => void
   onError?: (error: StreamError) => void
   onComponentReceived?: (component: UIComponent) => void
+  /**
+   * Localized progress / error messages (v6.20.0). Each key is read when
+   * the message is produced, so an object with getters stays reactive.
+   * Omitted keys fall back to {@link DEFAULT_STREAMING_UI_MESSAGES}.
+   */
+  messages?: Partial<StreamingUIMessages>
 }
 
 export interface StreamingUIState {
@@ -124,6 +175,9 @@ interface ComponentEvent {
 // ============================================================================
 
 export function useStreamingUI(options: UseStreamingUIOptions) {
+  const msg = (key: keyof StreamingUIMessages): string =>
+    options.messages?.[key] ?? DEFAULT_STREAMING_UI_MESSAGES[key]
+
   // State
   const [components, setComponents] = createSignal<UIComponent[]>([])
   const [isLoading, setIsLoading] = createSignal(false)
@@ -132,7 +186,7 @@ export function useStreamingUI(options: UseStreamingUIOptions) {
   const [progress, setProgress] = createSignal<StreamProgress>({
     receivedCount: 0,
     totalCount: null,
-    message: 'Initializing...',
+    message: msg('initializing'),
     timestamp: new Date().toISOString(),
   })
   const [metadata, setMetadata] = createSignal<CompleteMetadata | null>(null)
@@ -194,7 +248,7 @@ export function useStreamingUI(options: UseStreamingUIOptions) {
 
     setProgress((prev) => ({
       ...prev,
-      message: `Loading ${data.type} component...`,
+      message: formatMCPUIString(msg('loadingComponent'), { type: data.type }),
       timestamp: new Date().toISOString(),
     }))
   }
@@ -242,7 +296,7 @@ export function useStreamingUI(options: UseStreamingUIOptions) {
 
     setProgress((prev) => ({
       ...prev,
-      message: 'Dashboard loaded',
+      message: msg('dashboardLoaded'),
       timestamp: new Date().toISOString(),
     }))
 
@@ -264,7 +318,7 @@ export function useStreamingUI(options: UseStreamingUIOptions) {
 
     setProgress((prev) => ({
       ...prev,
-      message: `Error: ${data.message}`,
+      message: formatMCPUIString(msg('errorProgress'), { message: data.message }),
       timestamp: new Date().toISOString(),
     }))
 
@@ -325,7 +379,7 @@ export function useStreamingUI(options: UseStreamingUIOptions) {
       logger.warn('startStreaming called on server-side - skipping')
       setError({
         error: 'ssr',
-        message: 'Streaming UI cannot start on server-side',
+        message: msg('serverSide'),
         recoverable: false,
       })
       setIsLoading(false)
@@ -343,7 +397,7 @@ export function useStreamingUI(options: UseStreamingUIOptions) {
     setProgress({
       receivedCount: 0,
       totalCount: null,
-      message: 'Connecting to server...',
+      message: msg('connecting'),
       timestamp: new Date().toISOString(),
     })
 
@@ -372,11 +426,11 @@ export function useStreamingUI(options: UseStreamingUIOptions) {
       .then(async (response) => {
         if (!response.ok) {
           const errorData = await response.json()
-          throw new Error(errorData.message || 'Stream request failed')
+          throw new Error(errorData.message || msg('requestFailed'))
         }
 
         if (!response.body) {
-          throw new Error('Response body is null')
+          throw new Error(msg('emptyResponse'))
         }
 
         const reader = response.body.getReader()
@@ -423,8 +477,8 @@ export function useStreamingUI(options: UseStreamingUIOptions) {
         })
 
         handleErrorEvent({
-          error: 'Stream connection failed',
-          message: err instanceof Error ? err.message : 'Unknown error',
+          error: msg('connectionFailed'),
+          message: err instanceof Error ? err.message : msg('unknownError'),
           recoverable: true,
         })
       })

package/src/index.ts

@@ -134,6 +134,8 @@ export {
   MCPUIStringsContext,
   useMCPUIStrings,
   DEFAULT_MCPUI_STRINGS,
+  formatMCPUIString,
+  resolveMCPUILocale,
 } from './context/MCPUIStringsContext'
 export type {
   MCPUIStrings,
@@ -177,6 +179,7 @@ export type { AutocompleteFormFieldProps, AutocompleteFormFieldParams } from './
 // Hooks
 export {
   useStreamingUI,
+  DEFAULT_STREAMING_UI_MESSAGES,
   useAction,
   useToolAction,
   useConditionalField,
@@ -195,6 +198,7 @@ export {
 
 export type {
   UseStreamingUIOptions,
+  StreamingUIMessages,
   StreamingUIState,
   StreamProgress,
   StreamError,
@@ -338,6 +342,25 @@ export {
   validateAgainstSource,
 } from './services'
 
+// i18n of the pure helpers (v6.20.0) — English baselines a host spreads and
+// overrides when it renders in another language. The helpers themselves take
+// the table as a trailing optional parameter, so nothing else changes.
+export {
+  validateFieldValue,
+  validateFormData,
+  DEFAULT_VALIDATION_MESSAGES,
+} from './services/validation'
+export type { FormValidationMessages } from './services/validation'
+export {
+  graphToDegradedTable,
+  mapToDegradedTable,
+  chartToDegradedTable,
+  DEGRADED_PROJECTION_LABELS,
+} from './utils/degraded-projections'
+export type { DegradedProjectionLabels } from './utils/degraded-projections'
+export { chartToDataTable, CHART_DATA_TABLE_LABELS } from './components/chart-data-table'
+export type { ChartDataTableLabels } from './components/chart-data-table'
+
 // Clarification → Prompt helper (v4.3.9)
 export { clarificationToPromptConfig } from './services/chat-bus'
 

package/src/services/validation.ts

@@ -42,6 +42,9 @@ import type {
   ValidationOptions,
   ComponentType,
 } from '../types';
+// Runtime-free template helper: `src/validation.ts` (the SSR-safe subpath)
+// re-exports this module, so it must stay free of any solid-js import.
+import { formatMCPUIString } from '../utils/format-string';
 
 /**
  * All known ComponentType values — used to distinguish known-but-unvalidated
@@ -919,20 +922,85 @@ export function validateLayout(layout: UILayout, options?: ValidationOptions): V
   };
 }
 
+/**
+ * The end-user form-validation wording.
+ *
+ * `validateFieldValue` / `validateFormData` are pure and SSR-safe (they are
+ * re-exported from the `@seed-ship/mcp-ui-solid/validation` subpath), so
+ * they cannot read `MCPUIStrings`. The wording is injected instead: both
+ * take an optional trailing `messages` partial, and `FormRenderer` feeds it
+ * from `useMCPUIStrings()` (keys `fieldRequired`, `fieldMinLength`, …).
+ *
+ * The STRUCTURAL validators (`validateComponent`, `validateLayout`, …) keep
+ * their English `ValidationError.message`: those are payload diagnostics
+ * addressed to whoever produced the payload, not end-user chrome.
+ *
+ * @since v6.20.0
+ */
+export interface FormValidationMessages {
+  /** Template \u2014 `{field}`. */
+  required: string;
+  /** Template \u2014 `{field}`. */
+  mustBeChecked: string;
+  /** Template \u2014 `{min}`. */
+  minLength: string;
+  /** Template \u2014 `{max}`. */
+  maxLength: string;
+  /** Value does not match `field.pattern`. */
+  invalidPattern: string;
+  /** Value is not a valid email address. */
+  invalidEmail: string;
+  /** Value is not a number. */
+  invalidNumber: string;
+  /** Template \u2014 `{min}`. */
+  minValue: string;
+  /** Template \u2014 `{max}`. */
+  maxValue: string;
+  /** Template \u2014 `{min}`. */
+  minDate: string;
+  /** Template \u2014 `{max}`. */
+  maxDate: string;
+  /** Value is not one of `field.options`. */
+  invalidOption: string;
+  /** Template \u2014 `{format}`. `field.valueFormatHint` still wins. */
+  invalidFormat: string;
+}
+
+/** English defaults for {@link FormValidationMessages}. */
+export const DEFAULT_VALIDATION_MESSAGES: FormValidationMessages = {
+  required: '{field} is required',
+  mustBeChecked: '{field} must be checked',
+  minLength: 'Minimum {min} characters required',
+  maxLength: 'Maximum {max} characters allowed',
+  invalidPattern: 'Invalid format',
+  invalidEmail: 'Invalid email address',
+  invalidNumber: 'Must be a valid number',
+  minValue: 'Minimum value is {min}',
+  maxValue: 'Maximum value is {max}',
+  minDate: 'Date must be after {min}',
+  maxDate: 'Date must be before {max}',
+  invalidOption: 'Please select a valid option',
+  invalidFormat: 'Invalid format (expected: {format})',
+};
+
 /**
  * Validate a single form field value against field rules
  */
 export function validateFieldValue(
   value: any,
-  field: FormFieldParams
+  field: FormFieldParams,
+  messages?: Partial<FormValidationMessages>
 ): { valid: boolean; error?: string } {
+  const m: FormValidationMessages = { ...DEFAULT_VALIDATION_MESSAGES, ...messages };
+  const fieldName = field.label || field.name;
+
   // Required check
   if (field.required) {
     if (value === undefined || value === null || value === '') {
-      return { valid: false, error: `${field.label || field.name} is required` };
+      return { valid: false, error: formatMCPUIString(m.required, { field: fieldName }) };
     }
     if (field.type === 'checkbox' && value !== true) {
-      return { valid: false, error: `${field.label || field.name} must be checked` };
+      return { valid: false, error: formatMCPUIString(m.mustBeChecked, { field: fieldName }) };
     }
   }
 
@@ -947,42 +1015,48 @@ export function validateFieldValue(
     case 'textarea':
     case 'password':
       if (field.minLength && String(value).length < field.minLength) {
-        return { valid: false, error: `Minimum ${field.minLength} characters required` };
+        return {
+          valid: false,
+          error: formatMCPUIString(m.minLength, { min: field.minLength }),
+        };
       }
       if (field.maxLength && String(value).length > field.maxLength) {
-        return { valid: false, error: `Maximum ${field.maxLength} characters allowed` };
+        return {
+          valid: false,
+          error: formatMCPUIString(m.maxLength, { max: field.maxLength }),
+        };
       }
       if (field.pattern && !new RegExp(field.pattern).test(String(value))) {
-        return { valid: false, error: 'Invalid format' };
+        return { valid: false, error: m.invalidPattern };
       }
       break;
 
     case 'email':
       if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(String(value))) {
-        return { valid: false, error: 'Invalid email address' };
+        return { valid: false, error: m.invalidEmail };
       }
       break;
 
     case 'number': {
       const numValue = Number(value);
       if (isNaN(numValue)) {
-        return { valid: false, error: 'Must be a valid number' };
+        return { valid: false, error: m.invalidNumber };
       }
       if (field.min !== undefined && numValue < field.min) {
-        return { valid: false, error: `Minimum value is ${field.min}` };
+        return { valid: false, error: formatMCPUIString(m.minValue, { min: field.min }) };
       }
       if (field.max !== undefined && numValue > field.max) {
-        return { valid: false, error: `Maximum value is ${field.max}` };
+        return { valid: false, error: formatMCPUIString(m.maxValue, { max: field.max }) };
       }
       break;
     }
 
     case 'date':
       if (field.minDate && value < field.minDate) {
-        return { valid: false, error: `Date must be after ${field.minDate}` };
+        return { valid: false, error: formatMCPUIString(m.minDate, { min: field.minDate }) };
       }
       if (field.maxDate && value > field.maxDate) {
-        return { valid: false, error: `Date must be before ${field.maxDate}` };
+        return { valid: false, error: formatMCPUIString(m.maxDate, { max: field.maxDate }) };
       }
       break;
 
@@ -992,7 +1066,7 @@ export function validateFieldValue(
       if (field.options && field.options.length > 0) {
         const validValues = field.options.map((opt) => opt.value);
         if (!validValues.includes(String(value))) {
-          return { valid: false, error: 'Please select a valid option' };
+          return { valid: false, error: m.invalidOption };
         }
       }
       break;
@@ -1005,7 +1079,9 @@ export function validateFieldValue(
       if (!new RegExp(field.valueFormat).test(v)) {
         return {
           valid: false,
-          error: field.valueFormatHint || `Invalid format (expected: ${field.valueFormat})`,
+          error:
+            field.valueFormatHint ||
+            formatMCPUIString(m.invalidFormat, { format: field.valueFormat }),
         };
       }
     }
@@ -1019,12 +1095,13 @@ export function validateFieldValue(
  */
 export function validateFormData(
   data: Record<string, any>,
-  fields: FormFieldParams[]
+  fields: FormFieldParams[],
+  messages?: Partial<FormValidationMessages>
 ): { valid: boolean; errors: Record<string, string> } {
   const errors: Record<string, string> = {};
 
   for (const field of fields) {
-    const result = validateFieldValue(data[field.name], field);
+    const result = validateFieldValue(data[field.name], field, messages);
     if (!result.valid && result.error) {
       errors[field.name] = result.error;
     }

package/src/utils/degraded-projections.ts

@@ -11,6 +11,63 @@
  * map/graph.
  */
 
+import { formatMCPUIString } from './format-string';
+
+/**
+ * Column headers and series names of the degraded tables.
+ *
+ * The projections are pure helpers with no access to `MCPUIStrings`, so the
+ * wording is injected: each function takes an optional trailing `labels`
+ * partial, and the renderers feed it from `useMCPUIStrings()`. Left out, the
+ * English defaults below apply — the pre-v6.20.0 behaviour.
+ *
+ * @since v6.20.0
+ */
+export interface DegradedProjectionLabels {
+  /** Graph edge table — source column. */
+  source: string;
+  /** Graph edge table — target column. */
+  target: string;
+  /** Graph edge / node table — label column. */
+  label: string;
+  /** Graph node table — node id column. */
+  node: string;
+  /** Map table — feature type column. */
+  type: string;
+  /** Map table — latitude column. */
+  lat: string;
+  /** Map table — longitude column. */
+  lng: string;
+  /** Map table — property summary column. */
+  info: string;
+  /** Map table — `Type` cell of a marker row (v6.20.0, 6th pass). */
+  marker: string;
+  /** Map table — `Type` cell of a GeoJSON feature without a geometry type (v6.20.0). */
+  feature: string;
+  /** Chart table — fallback dataset name. Template — `{n}`. */
+  series: string;
+}
+
+/** English defaults for {@link DegradedProjectionLabels}. */
+export const DEGRADED_PROJECTION_LABELS: DegradedProjectionLabels = {
+  source: 'Source',
+  target: 'Target',
+  label: 'Label',
+  node: 'Node',
+  type: 'Type',
+  lat: 'Lat',
+  lng: 'Lng',
+  info: 'Info',
+  marker: 'marker',
+  feature: 'feature',
+  series: 'Series {n}',
+};
+
+const withLabels = (labels?: Partial<DegradedProjectionLabels>): DegradedProjectionLabels => ({
+  ...DEGRADED_PROJECTION_LABELS,
+  ...labels,
+});
+
 export interface DegradedTable {
   columns: string[];
   rows: Array<Array<string | number>>;
@@ -41,11 +98,12 @@ function cell(value: unknown): string {
 export function graphToDegradedTable(params: {
   nodes?: Array<{ id: string; label?: string }>;
   edges?: Array<{ source: string; target: string; label?: string; weight?: number }>;
-}): DegradedTable {
+}, labels?: Partial<DegradedProjectionLabels>): DegradedTable {
+  const l = withLabels(labels);
   const edges = params.edges ?? [];
   if (edges.length > 0) {
     return {
-      columns: ['Source', 'Target', 'Label'],
+      columns: [l.source, l.target, l.label],
       rows: edges.slice(0, MAX_PROJECTED_ROWS).map((e) => {
         const label = [e.weight != null ? String(e.weight) : '', e.label ?? '']
           .filter(Boolean)
@@ -56,7 +114,7 @@ export function graphToDegradedTable(params: {
   }
   const nodes = params.nodes ?? [];
   return {
-    columns: ['Node', 'Label'],
+    columns: [l.node, l.label],
     rows: nodes.slice(0, MAX_PROJECTED_ROWS).map((n) => [cell(n.id), cell(n.label ?? n.id)]),
   };
 }
@@ -91,13 +149,14 @@ export function mapToDegradedTable(params: {
     popup?: string;
   }>;
   geojson?: unknown;
-}): DegradedTable {
+}, labels?: Partial<DegradedProjectionLabels>): DegradedTable {
+  const l = withLabels(labels);
   const rows: Array<Array<string | number>> = [];
 
   for (const m of params.markers ?? []) {
     const lat = Array.isArray(m.position) ? m.position[0] : m.position?.lat;
     const lng = Array.isArray(m.position) ? m.position[1] : m.position?.lng;
-    rows.push(['marker', cell(lat), cell(lng), cell(m.tooltip ?? m.popup ?? '')]);
+    rows.push([l.marker, cell(lat), cell(lng), cell(m.tooltip ?? m.popup ?? '')]);
   }
 
   const fc = params.geojson as { features?: GeoJSONLikeFeature[] } | undefined;
@@ -110,7 +169,7 @@ export function mapToDegradedTable(params: {
       .map((k) => `${k}=${cell(props[k])}`)
       .join(', ');
     rows.push([
-      cell(f.geometry?.type ?? 'feature'),
+      cell(f.geometry?.type ?? l.feature),
       ll ? cell(ll[1]) : '',
       ll ? cell(ll[0]) : '',
       propSummary,
@@ -118,7 +177,7 @@ export function mapToDegradedTable(params: {
   }
 
   return {
-    columns: ['Type', 'Lat', 'Lng', 'Info'],
+    columns: [l.type, l.lat, l.lng, l.info],
     rows: rows.slice(0, MAX_PROJECTED_ROWS),
   };
 }
@@ -135,15 +194,19 @@ export function chartToDegradedTable(params: {
     labels?: Array<string | number>;
     datasets?: Array<{ label?: string; data?: unknown[] }>;
   };
-}): DegradedTable {
+}, labels?: Partial<DegradedProjectionLabels>): DegradedTable {
+  const l = withLabels(labels);
   const datasets = params.data?.datasets ?? [];
-  const labels = params.data?.labels ?? [];
-  const rowCount = Math.max(labels.length, ...datasets.map((d) => d.data?.length ?? 0), 0);
+  const dataLabels = params.data?.labels ?? [];
+  const rowCount = Math.max(dataLabels.length, ...datasets.map((d) => d.data?.length ?? 0), 0);
 
-  const columns = ['', ...datasets.map((d, i) => d.label ?? `Series ${i + 1}`)];
+  const columns = [
+    '',
+    ...datasets.map((d, i) => d.label ?? formatMCPUIString(l.series, { n: i + 1 })),
+  ];
   const rows: Array<Array<string | number>> = [];
   for (let r = 0; r < Math.min(rowCount, MAX_PROJECTED_ROWS); r++) {
-    rows.push([cell(labels[r] ?? r + 1), ...datasets.map((d) => cell(d.data?.[r]))]);
+    rows.push([cell(dataLabels[r] ?? r + 1), ...datasets.map((d) => cell(d.data?.[r]))]);
   }
   return { columns, rows };
 }

package/src/utils/format-string.ts

@@ -0,0 +1,33 @@
+/**
+ * `formatMCPUIString` — the chrome-string template helper, runtime-free.
+ *
+ * @since v6.20.0 (extracted from `MCPUIStringsContext` so the pure adapters
+ * under `src/adapters` can interpolate their own message templates without
+ * importing `solid-js`). `MCPUIStringsContext` re-exports it, so every
+ * existing import path — including the root barrel — keeps working.
+ *
+ * This module imports nothing. It must stay that way: `src/adapters/*` is
+ * published as a dedicated subpath that never pulls in the renderer.
+ */
+
+/**
+ * Substitutes `{name}` placeholders in a chrome string template.
+ *
+ * Only the keys present in `vars` are replaced; an unknown placeholder is
+ * left verbatim so a mistyped or locale-specific template degrades to
+ * visible text rather than to `undefined`.
+ *
+ * @example
+ * ```ts
+ * formatMCPUIString('Sort by {column}', { column: 'Revenue' }) // 'Sort by Revenue'
+ * formatMCPUIString('Export CSV ({count} rows)', { count: 42 }) // 'Export CSV (42 rows)'
+ * ```
+ */
+export function formatMCPUIString(
+  template: string,
+  vars: Record<string, string | number>
+): string {
+  return template.replace(/\{(\w+)\}/g, (match, name: string) =>
+    Object.prototype.hasOwnProperty.call(vars, name) ? String(vars[name]) : match
+  )
+}

package/src/validation.ts

@@ -21,7 +21,12 @@ export {
   validateIframeDomain,
   sanitizeString,
   DEFAULT_RESOURCE_LIMITS,
+  // v6.20.0 — end-user form validation with injectable wording.
+  validateFieldValue,
+  validateFormData,
+  DEFAULT_VALIDATION_MESSAGES,
 } from './services/validation'
+export type { FormValidationMessages } from './services/validation'
 
 // Re-export types only (no runtime code)
 export type {