@skopon-cool/form-sdk 0.1.0

package/src/adapter/a2uiAdapter.ts

@@ -0,0 +1,490 @@
+import type {
+  A2uiComponentNode,
+  A2uiSurfaceDoc,
+  FormBlock,
+  FormBlockOption,
+  FormBlockType,
+  FormMediaSize,
+  FormSchema,
+} from '../types/index'
+import { generateId } from './id'
+import { getMediaUrls, normalizeMediaSize } from './formMedia'
+import { syncFormDefinition } from './formSchema'
+
+/**
+ * A2UI surface <-> FormBlock 双向适配器。
+ *
+ * - 内部编辑模型仍是扁平的 FormBlock[]（编辑器、JSON Schema、校验都基于它）。
+ * - 对外/存储/AI 交换使用 A2UI v0.9 surface（basicCatalog + skopon 自定义 catalog）。
+ * - load/save 时在两者之间做无损（尽量）转换。
+ *
+ * 已知有损点（可接受，blocks 仍是存储 source-of-truth）：
+ *   email/tel/url 回读时统一退化为 text（除非可由 validationRegexp 推断）。
+ *   A2UI ChoicePicker 无原生下拉；select/multiselect 使用 SkoponSelect 扩展组件。
+ */
+
+const ROOT_ID = 'root'
+const TITLE_ID = '__title__'
+const DESC_ID = '__desc__'
+const EMAIL_REGEXP = '^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$'
+
+function pathFor(name: string): string {
+  return `/${name}`
+}
+
+function nameFromValue(value: unknown): string {
+  if (value && typeof value === 'object' && 'path' in (value as Record<string, unknown>)) {
+    const path = String((value as { path: unknown }).path ?? '')
+    return path.replace(/^\//, '')
+  }
+  return ''
+}
+
+function asLiteral(value: unknown): string | undefined {
+  if (typeof value === 'string') return value
+  return undefined
+}
+
+
+function mediaBlockNode(block: FormBlock): A2uiComponentNode {
+  const id = block.id || generateId('a2-')
+  const mediaType =
+    block.type === 'video' ? 'video' : block.type === 'audio' ? 'audio' : 'image'
+  return {
+    id,
+    component: 'SkoponMedia',
+    mediaType,
+    urls: getMediaUrls(block),
+    mediaSize: normalizeMediaSize(block.mediaSize),
+    label: block.label ?? '',
+    help: block.help ?? '',
+    placeholder: block.placeholder ?? '',
+  }
+}
+
+function readMediaUrls(node: A2uiComponentNode): string[] {
+  if (Array.isArray(node.urls)) {
+    return node.urls.map((u) => String(u).trim()).filter(Boolean)
+  }
+  const single = asLiteral(node.url)
+  return single?.trim() ? [single.trim()] : []
+}
+
+function readMediaBlock(
+  node: A2uiComponentNode,
+  type: 'image' | 'video' | 'audio',
+  fallbackLabel: string,
+): FormBlock {
+  const id = typeof node.id === 'string' ? node.id : generateId('block-')
+  const urls = readMediaUrls(node)
+  const label = asLiteral(node.label) ?? asLiteral(node.description) ?? fallbackLabel
+  const help = asLiteral(node.help)
+  const placeholder = asLiteral(node.placeholder)
+  const mediaSize = normalizeMediaSize(node.mediaSize as FormMediaSize | undefined)
+  return {
+    id,
+    type,
+    label,
+    ...(help ? { help } : {}),
+    ...(placeholder ? { placeholder } : {}),
+    mediaSize,
+    mediaUrls: urls.length > 0 ? urls : [''],
+  }
+}
+
+function defaultValueForBlock(block: FormBlock): unknown {
+  switch (block.type) {
+    case 'toggle':
+      return typeof block.defaultValue === 'boolean' ? block.defaultValue : false
+    case 'multiselect':
+    case 'checkbox':
+    case 'select':
+    case 'radio':
+      if (Array.isArray(block.defaultValue)) return block.defaultValue
+      if (typeof block.defaultValue === 'string' && block.defaultValue) return [block.defaultValue]
+      return []
+    default:
+      if (typeof block.defaultValue === 'string') return block.defaultValue
+      return ''
+  }
+}
+
+/** 单个 FormBlock -> A2UI 组件节点（input 类附带 dataModel 默认值） */
+function blockToComponent(block: FormBlock): {
+  node: A2uiComponentNode | null
+  dataKey?: string
+  dataValue?: unknown
+} {
+  const id = block.id || generateId('a2-')
+  const label = block.label ?? ''
+  const name = block.name?.trim() || ''
+  const path = name ? pathFor(name) : undefined
+  const options = (block.options ?? []).map((o) => ({ label: o.label, value: o.value }))
+
+  const withData = (node: A2uiComponentNode): {
+    node: A2uiComponentNode
+    dataKey?: string
+    dataValue?: unknown
+  } => (name ? { node, dataKey: name, dataValue: defaultValueForBlock(block) } : { node })
+
+  switch (block.type) {
+    case 'heading':
+      return { node: { id, component: 'Text', text: label, variant: 'h3' } }
+    case 'paragraph':
+      return { node: { id, component: 'Text', text: label, variant: 'body' } }
+
+    case 'text':
+    case 'tel':
+    case 'url':
+      return withData({ id, component: 'TextField', label, variant: 'shortText', value: { path } })
+    case 'email':
+      return withData({
+        id,
+        component: 'TextField',
+        label,
+        variant: 'shortText',
+        validationRegexp: EMAIL_REGEXP,
+        value: { path },
+      })
+    case 'textarea':
+      return withData({ id, component: 'TextField', label, variant: 'longText', value: { path } })
+    case 'number':
+      return withData({ id, component: 'TextField', label, variant: 'number', value: { path } })
+
+    case 'select':
+      return withData({
+        id,
+        component: 'SkoponSelect',
+        label,
+        mode: 'single',
+        placeholder: block.placeholder ?? '',
+        options,
+        value: { path },
+      })
+    case 'radio':
+      return withData({
+        id,
+        component: 'ChoicePicker',
+        label,
+        variant: 'mutuallyExclusive',
+        skoponPickerType: 'radio',
+        options,
+        value: { path },
+      })
+    case 'multiselect':
+      return withData({
+        id,
+        component: 'SkoponSelect',
+        label,
+        mode: 'multiple',
+        placeholder: block.placeholder ?? '',
+        options,
+        value: { path },
+      })
+    case 'checkbox':
+      return withData({
+        id,
+        component: 'ChoicePicker',
+        label,
+        variant: 'multipleSelection',
+        skoponPickerType: 'checkbox',
+        options,
+        value: { path },
+      })
+
+    case 'toggle':
+      return withData({ id, component: 'CheckBox', label, value: { path } })
+
+    case 'datetime':
+      return withData({
+        id,
+        component: 'DateTimeInput',
+        label,
+        enableDate: true,
+        enableTime: true,
+        placeholder: block.placeholder ?? '',
+        value: { path },
+      })
+    case 'time':
+      return withData({
+        id,
+        component: 'DateTimeInput',
+        label,
+        enableTime: true,
+        placeholder: block.placeholder ?? '',
+        value: { path },
+      })
+
+    case 'image':
+    case 'video':
+    case 'audio':
+      return { node: mediaBlockNode(block) }
+
+    case 'file':
+      return withData({
+        id,
+        component: 'FileUpload',
+        label,
+        accept: (block.fileAcceptExtensions ?? []).join(','),
+        fileAcceptTypes: block.fileAcceptTypes ?? [],
+        filePlaceholderIcon: block.filePlaceholderIcon ?? 'document',
+        minCount: block.fileMinCount ?? 0,
+        maxCount: block.fileMaxCount ?? 1,
+        value: { path },
+      })
+
+    default:
+      return { node: null }
+  }
+}
+
+export interface BlocksToA2uiOptions {
+  styleId?: string | null
+  /** 是否写入 title/description 为 Text 组件；预览区由 FormTitleField 展示时可设为 false */
+  includeHeader?: boolean
+}
+
+/** surface 是否仅含空 root Column（无可视内容） */
+export function isA2uiSurfaceEmpty(doc: A2uiSurfaceDoc | null | undefined): boolean {
+  if (!doc || !Array.isArray(doc.components) || doc.components.length === 0) return true
+  const root = doc.components.find((c) => c.id === ROOT_ID)
+  if (!root) return doc.components.length === 0
+  const children = root.children
+  if (!Array.isArray(children) || children.length === 0) return true
+  return false
+}
+
+/** FormBlock[] -> A2UI surface 文档 */
+export function blocksToA2ui(
+  definition: Pick<FormSchema, 'title' | 'description' | 'blocks'>,
+  options?: BlocksToA2uiOptions,
+): A2uiSurfaceDoc {
+  const components: A2uiComponentNode[] = []
+  const childIds: string[] = []
+  const dataModel: Record<string, unknown> = {}
+
+  const includeHeader = options?.includeHeader !== false
+  const title = (definition.title ?? '').trim()
+  const description = (definition.description ?? '').trim()
+  if (includeHeader && title) {
+    components.push({ id: TITLE_ID, component: 'Text', text: title, variant: 'h2' })
+    childIds.push(TITLE_ID)
+  }
+  if (includeHeader && description) {
+    components.push({ id: DESC_ID, component: 'Text', text: description, variant: 'body' })
+    childIds.push(DESC_ID)
+  }
+
+  for (const block of definition.blocks ?? []) {
+    const { node, dataKey, dataValue } = blockToComponent(block)
+    if (!node) continue
+    components.push(node)
+    childIds.push(node.id)
+    if (dataKey) dataModel[dataKey] = dataValue
+  }
+
+  components.unshift({ id: ROOT_ID, component: 'Column', children: childIds })
+
+  const doc: A2uiSurfaceDoc = { root: ROOT_ID, components, dataModel }
+  const styleId = options?.styleId
+  if (styleId !== undefined) {
+    doc.surfaceProperties = { styleId: styleId ?? null }
+  }
+  return doc
+}
+
+function indexComponents(doc: A2uiSurfaceDoc): Map<string, A2uiComponentNode> {
+  const map = new Map<string, A2uiComponentNode>()
+  for (const node of doc.components ?? []) {
+    if (node && typeof node.id === 'string') map.set(node.id, node)
+  }
+  return map
+}
+
+function readOptions(node: A2uiComponentNode): FormBlockOption[] {
+  const raw = node.options
+  if (!Array.isArray(raw)) return []
+  return raw
+    .map((o) => {
+      if (!o || typeof o !== 'object') return null
+      const rec = o as Record<string, unknown>
+      return {
+        value: String(rec.value ?? rec.label ?? ''),
+        label: String(rec.label ?? rec.value ?? ''),
+      } as FormBlockOption
+    })
+    .filter((o): o is FormBlockOption => !!o)
+}
+
+/** 单个 A2UI 组件节点 -> FormBlock（无法识别返回 null） */
+function componentToBlock(node: A2uiComponentNode): FormBlock | null {
+  const id = typeof node.id === 'string' ? node.id : generateId('block-')
+  const component = String(node.component ?? '')
+  const label = asLiteral(node.label) ?? asLiteral(node.text) ?? ''
+  const name = nameFromValue(node.value)
+
+  const base = (type: FormBlockType): FormBlock => ({ id, type, label })
+
+  switch (component) {
+    case 'Text': {
+      const variant = String(node.variant ?? 'body')
+      const isHeading = /^h[1-6]$/i.test(variant) || variant === 'title' || variant === 'subtitle'
+      return { id, type: isHeading ? 'heading' : 'paragraph', label }
+    }
+    case 'TextField': {
+      const variant = String(node.variant ?? 'shortText')
+      let type: FormBlockType = 'text'
+      if (variant === 'longText') type = 'textarea'
+      else if (variant === 'number') type = 'number'
+      else if (asLiteral(node.validationRegexp) === EMAIL_REGEXP) type = 'email'
+      return { ...base(type), name }
+    }
+    case 'CheckBox':
+      return { ...base('toggle'), name }
+    case 'SkoponSelect': {
+      const mode = String(node.mode ?? 'single')
+      const type: FormBlockType = mode === 'multiple' ? 'multiselect' : 'select'
+      const block: FormBlock = {
+        ...base(type),
+        name,
+        options: readOptions(node),
+      }
+      const placeholder = asLiteral(node.placeholder)
+      if (placeholder) block.placeholder = placeholder
+      return block
+    }
+    case 'ChoicePicker': {
+      const pickerType = asLiteral(node.skoponPickerType)
+      if (
+        pickerType === 'select' ||
+        pickerType === 'multiselect' ||
+        pickerType === 'radio' ||
+        pickerType === 'checkbox'
+      ) {
+        const block: FormBlock = {
+          ...base(pickerType),
+          name,
+          options: readOptions(node),
+        }
+        const placeholder = asLiteral(node.placeholder)
+        if (placeholder) block.placeholder = placeholder
+        return block
+      }
+      const variant = String(node.variant ?? 'mutuallyExclusive')
+      const type: FormBlockType = variant === 'multipleSelection' ? 'checkbox' : 'radio'
+      return { ...base(type), name, options: readOptions(node) }
+    }
+    case 'DateTimeInput': {
+      const enableDate = node.enableDate === true
+      const enableTime = node.enableTime === true
+      const type: FormBlockType = !enableDate && enableTime ? 'time' : 'datetime'
+      const block: FormBlock = { ...base(type), name }
+      const placeholder = asLiteral(node.placeholder)
+      if (placeholder) block.placeholder = placeholder
+      return block
+    }
+    case 'SkoponMedia': {
+      const mediaType = String(node.mediaType ?? 'image')
+      const type: FormBlockType =
+        mediaType === 'video' ? 'video' : mediaType === 'audio' ? 'audio' : 'image'
+      return readMediaBlock(node, type, label)
+    }
+    case 'Image':
+      return readMediaBlock(node, 'image', label)
+    case 'Video':
+      return readMediaBlock(node, 'video', label)
+    case 'AudioPlayer':
+      return readMediaBlock(node, 'audio', label)
+    case 'FileUpload': {
+      const accept = asLiteral(node.accept) ?? ''
+      const block: FormBlock = { ...base('file'), name }
+      if (accept) block.fileAcceptExtensions = accept.split(',').map((s) => s.trim()).filter(Boolean)
+      if (Array.isArray(node.fileAcceptTypes)) {
+        block.fileAcceptTypes = node.fileAcceptTypes.map(String)
+      }
+      if (typeof node.filePlaceholderIcon === 'string') {
+        block.filePlaceholderIcon = node.filePlaceholderIcon as FormBlock['filePlaceholderIcon']
+      }
+      if (typeof node.minCount === 'number') block.fileMinCount = node.minCount
+      if (typeof node.maxCount === 'number') block.fileMaxCount = node.maxCount
+      return block
+    }
+    default:
+      return null
+  }
+}
+
+/** 递归收集容器下的叶子组件顺序（扁平化 Column/Row 嵌套） */
+function collectOrder(
+  rootId: string,
+  index: Map<string, A2uiComponentNode>,
+  seen: Set<string>,
+  out: A2uiComponentNode[],
+): void {
+  if (seen.has(rootId)) return
+  seen.add(rootId)
+  const node = index.get(rootId)
+  if (!node) return
+  const component = String(node.component ?? '')
+  if ((component === 'Column' || component === 'Row') && Array.isArray(node.children)) {
+    for (const childId of node.children) {
+      if (typeof childId === 'string') collectOrder(childId, index, seen, out)
+    }
+    return
+  }
+  out.push(node)
+}
+
+/** A2UI surface 文档 -> FormSchema（已 sync 出 jsonSchema） */
+export function a2uiToBlocks(doc: A2uiSurfaceDoc | null | undefined): FormSchema {
+  if (!doc || !Array.isArray(doc.components)) {
+    return syncFormDefinition({ title: '', description: '', blocks: [], jsonSchema: {} })
+  }
+  const index = indexComponents(doc)
+  const ordered: A2uiComponentNode[] = []
+  collectOrder(doc.root ?? ROOT_ID, index, new Set(), ordered)
+
+  let title = ''
+  let description = ''
+  const blocks: FormBlock[] = []
+
+  for (const node of ordered) {
+    if (node.id === TITLE_ID) {
+      title = asLiteral(node.text) ?? title
+      continue
+    }
+    if (node.id === DESC_ID) {
+      description = asLiteral(node.text) ?? description
+      continue
+    }
+    const block = componentToBlock(node)
+    if (block) blocks.push(block)
+  }
+
+  return syncFormDefinition({ title, description, blocks, jsonSchema: {} })
+}
+
+/**
+ * 便携 surface 文档 -> A2UI v0.9 消息列表（供 MessageProcessor 消费）。
+ * 返回宽松类型，调用方按需 `as unknown as A2uiMessage[]`。
+ */
+export function surfaceDocToMessages(
+  doc: A2uiSurfaceDoc,
+  options: { surfaceId: string; catalogId: string },
+): Record<string, unknown>[] {
+  const { surfaceId, catalogId } = options
+  const messages: Record<string, unknown>[] = [
+    { version: 'v0.9', createSurface: { surfaceId, catalogId } },
+    {
+      version: 'v0.9',
+      updateComponents: { surfaceId, components: doc.components },
+    },
+  ]
+  if (doc.dataModel && Object.keys(doc.dataModel).length > 0) {
+    messages.push({
+      version: 'v0.9',
+      updateDataModel: { surfaceId, path: '/', value: doc.dataModel },
+    })
+  }
+  return messages
+}

package/src/adapter/extractSurfaceValues.ts

@@ -0,0 +1,25 @@
+import type { MessageProcessor } from '@a2ui/web_core/v0_9'
+import type { ReactComponentImplementation } from '@a2ui/react/v0_9'
+
+type SkoponProcessor = MessageProcessor<ReactComponentImplementation>
+
+/** 从 MessageProcessor surface 的 dataModel 读取已填字段值。 */
+export function extractSurfaceValues(
+  processor: SkoponProcessor,
+  surfaceId: string,
+  fieldNames: string[],
+): Record<string, unknown> {
+  const surface = processor.model.surfacesMap.get(surfaceId)
+  if (!surface) return {}
+  const values: Record<string, unknown> = {}
+  for (const name of fieldNames) {
+    const trimmed = name.trim()
+    if (!trimmed) continue
+    values[trimmed] = surface.dataModel.get(`/${trimmed}`)
+  }
+  return values
+}
+
+export function collectInputFieldNames(fieldNames?: string[]): string[] {
+  return (fieldNames ?? []).map((name) => name.trim()).filter(Boolean)
+}