@skopon-cool/form-sdk 0.1.0 → 0.1.3

package/src/components/SkoponA2uiStreamRenderer.test.tsx

@@ -0,0 +1,79 @@
+// @vitest-environment happy-dom
+import { describe, it, expect, vi, afterEach, beforeAll } from 'vitest'
+
+vi.mock('@a2ui/web_core/v0_9/basic_catalog', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@a2ui/web_core/v0_9/basic_catalog')>()
+  return { ...actual, injectBasicCatalogStyles: vi.fn() }
+})
+
+vi.mock('@a2ui/react/styles', () => ({
+  injectStyles: vi.fn(),
+  removeStyles: vi.fn(),
+}))
+
+import { createElement } from 'react'
+import { render, cleanup } from '@testing-library/react'
+import type { A2uiMessage } from '@a2ui/web_core/v0_9'
+import { blocksToA2ui, surfaceDocToMessages } from '../adapter/a2uiAdapter'
+import { SKOPON_CATALOG_ID } from '../catalog/a2uiCustomCatalog'
+import SkoponA2uiStreamRenderer from './SkoponA2uiStreamRenderer'
+
+function buildStreamMessages(surfaceId: string): A2uiMessage[] {
+  const doc = blocksToA2ui(
+    {
+      title: '',
+      description: '',
+      blocks: [{ id: 'b-name', type: 'text', name: 'name', label: '姓名' }],
+    },
+    { includeHeader: false },
+  )
+  return surfaceDocToMessages(doc, { surfaceId, catalogId: SKOPON_CATALOG_ID }) as unknown as A2uiMessage[]
+}
+
+beforeAll(() => {
+  class ResizeObserverMock {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+  }
+  vi.stubGlobal('ResizeObserver', ResizeObserverMock)
+})
+
+describe('SkoponA2uiStreamRenderer component', () => {
+  afterEach(() => {
+    cleanup()
+  })
+
+  it('mounts with empty messages without infinite update loop', () => {
+    expect(() =>
+      render(
+        createElement(SkoponA2uiStreamRenderer, {
+          messages: [],
+          emptyHint: createElement('span', null, 'stream-empty'),
+        }),
+      ),
+    ).not.toThrow()
+  })
+
+  it('reprocesses messages when surfaceId changes', () => {
+    const surfaceA = 'stream-a'
+    const surfaceB = 'stream-b'
+    const messages = buildStreamMessages(surfaceA)
+    const { rerender, getByText, queryByText } = render(
+      createElement(SkoponA2uiStreamRenderer, {
+        messages,
+        surfaceId: surfaceA,
+      }),
+    )
+    expect(getByText('姓名')).toBeTruthy()
+
+    rerender(
+      createElement(SkoponA2uiStreamRenderer, {
+        messages,
+        surfaceId: surfaceB,
+      }),
+    )
+    expect(getByText('姓名')).toBeTruthy()
+    expect(queryByText('stream-empty')).toBeNull()
+  })
+})

package/src/components/SkoponA2uiStreamRenderer.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useMemo, useRef, useState, type ReactNode } from 'react'
+import { useEffect, useRef, useState, type ReactNode } from 'react'
 import { MessageProcessor, type A2uiMessage } from '@a2ui/web_core/v0_9'
 import { injectBasicCatalogStyles } from '@a2ui/web_core/v0_9/basic_catalog'
 import { A2uiSurface, type ReactComponentImplementation } from '@a2ui/react/v0_9'
@@ -14,6 +14,10 @@ export interface SkoponA2uiStreamRendererProps {
   interactive?: boolean
 }
 
+function createProcessor(): MessageProcessor<ReactComponentImplementation> {
+  return new MessageProcessor([buildSkoponCatalog()])
+}
+
 export default function SkoponA2uiStreamRenderer({
   messages,
   surfaceId = 'skopon-form-stream',
@@ -25,20 +29,32 @@ export default function SkoponA2uiStreamRenderer({
     injectBasicCatalogStyles()
   }, [])
 
-  const processorRef = useRef<MessageProcessor<ReactComponentImplementation> | null>(null)
+  const processorRef = useRef<MessageProcessor<ReactComponentImplementation>>(createProcessor())
   const processedCountRef = useRef(0)
+  const mountedRef = useRef(true)
+  const surfaceIdRef = useRef(surfaceId)
+
+  const [processor, setProcessor] = useState(() => processorRef.current)
+  const [surfaces, setSurfaces] = useState(() =>
+    Array.from(processorRef.current.model.surfacesMap.values()),
+  )
 
-  const processor = useMemo(() => {
-    const p = new MessageProcessor([buildSkoponCatalog()])
-    processorRef.current = p
-    processedCountRef.current = 0
-    return p
-  }, [surfaceId])
+  useEffect(() => {
+    mountedRef.current = true
+    return () => {
+      mountedRef.current = false
+    }
+  }, [])
 
-  const [surfaces, setSurfaces] = useState(() => Array.from(processor.model.surfacesMap.values()))
+  useEffect(() => {
+    processorRef.current = processor
+  }, [processor])
 
   useEffect(() => {
-    const sync = () => setSurfaces(Array.from(processor.model.surfacesMap.values()))
+    const sync = () => {
+      if (!mountedRef.current) return
+      setSurfaces(Array.from(processor.model.surfacesMap.values()))
+    }
     const createdSub = processor.onSurfaceCreated(sync)
     const deletedSub = processor.onSurfaceDeleted(sync)
     return () => {
@@ -48,13 +64,78 @@ export default function SkoponA2uiStreamRenderer({
   }, [processor])
 
   useEffect(() => {
-    if (!Array.isArray(messages) || messages.length === 0) return
+    let cancelled = false
+    const surfaceIdChanged = surfaceIdRef.current !== surfaceId
+    surfaceIdRef.current = surfaceId
+
+    if (surfaceIdChanged) {
+      const next = createProcessor()
+      processorRef.current = next
+      processedCountRef.current = 0
+      if (Array.isArray(messages) && messages.length > 0) {
+        next.processMessages(messages)
+        processedCountRef.current = messages.length
+        if (!cancelled) {
+          setProcessor(next)
+          setSurfaces(Array.from(next.model.surfacesMap.values()))
+        }
+      } else if (!cancelled) {
+        setProcessor(next)
+        setSurfaces([])
+      }
+      return () => {
+        cancelled = true
+      }
+    }
+
+    if (!Array.isArray(messages) || messages.length === 0) {
+      if (processedCountRef.current > 0) {
+        const next = createProcessor()
+        processorRef.current = next
+        processedCountRef.current = 0
+        if (!cancelled) {
+          setProcessor(next)
+          setSurfaces([])
+        }
+      }
+      return () => {
+        cancelled = true
+      }
+    }
+
+    const activeProcessor = processorRef.current
+
+    if (messages.length < processedCountRef.current) {
+      const next = createProcessor()
+      processorRef.current = next
+      processedCountRef.current = 0
+      next.processMessages(messages)
+      processedCountRef.current = messages.length
+      if (!cancelled) {
+        setProcessor(next)
+        setSurfaces(Array.from(next.model.surfacesMap.values()))
+      }
+      return () => {
+        cancelled = true
+      }
+    }
+
     const pending = messages.slice(processedCountRef.current)
-    if (pending.length === 0) return
-    processor.processMessages(pending)
+    if (pending.length === 0) {
+      return () => {
+        cancelled = true
+      }
+    }
+    activeProcessor.processMessages(pending)
     processedCountRef.current = messages.length
-    setSurfaces(Array.from(processor.model.surfacesMap.values()))
-  }, [messages, processor])
+    if (!cancelled) {
+      setSurfaces(Array.from(activeProcessor.model.surfacesMap.values()))
+    }
+
+    return () => {
+      cancelled = true
+    }
+  }, [messages, surfaceId])
 
   if (surfaces.length === 0) return <>{emptyHint}</>
 

package/src/components/SkoponFormRenderer.tsx

@@ -49,10 +49,9 @@ const SkoponFormRenderer = forwardRef<SkoponFormRendererRef, SkoponFormRendererP
     const fieldNamesRef = useRef(fieldNames)
     fieldNamesRef.current = fieldNames
 
-    const surfaces = useMemo(() => {
+    const renderResult = useMemo(() => {
       if (isA2uiSurfaceEmpty(doc)) {
-        processorRef.current = null
-        return []
+        return { surfaces: [], processor: null as MessageProcessor<ReactComponentImplementation> | null }
       }
       try {
         const processor = new MessageProcessor([buildSkoponCatalog()])
@@ -61,15 +60,19 @@ const SkoponFormRenderer = forwardRef<SkoponFormRendererRef, SkoponFormRendererP
           catalogId: SKOPON_CATALOG_ID,
         }) as unknown as A2uiMessage[]
         processor.processMessages(messages)
-        processorRef.current = processor
-        return Array.from(processor.model.surfacesMap.values())
+        return {
+          surfaces: Array.from(processor.model.surfacesMap.values()),
+          processor,
+        }
       } catch (error) {
         console.error('[SkoponFormRenderer] 渲染 A2UI surface 失败', error)
-        processorRef.current = null
-        return []
+        return { surfaces: [], processor: null as MessageProcessor<ReactComponentImplementation> | null }
       }
     }, [doc, surfaceId])
 
+    const { surfaces, processor } = renderResult
+    processorRef.current = processor
+
     useImperativeHandle(
       ref,
       () => ({

package/src/index.ts

@@ -41,8 +41,17 @@ export { normalizeFormDefinition, syncFormDefinition } from './adapter/formSchem
 
 export { extractSurfaceValues } from './adapter/extractSurfaceValues'
 
-export { buildCurlStatement } from './submit/buildCurlStatement'
-export { intersectPayloadWithForm, type PayloadFormIntersection } from './submit/intersectPayloadWithForm'
+export { buildCurlStatement, buildAskUserCurlStatement, buildAskUserCurlBodyJson } from './submit/buildCurlStatement'
+export {
+  extractExtraBlockValues,
+  getPayloadInputFieldNames,
+  getPayloadRenderableBlocks,
+  intersectPayloadBlocksWithForm,
+  parsePayloadBlocksJson,
+  payloadHasInputBlocks,
+  type PayloadBlocksDefinition,
+  type PayloadBlocksIntersection,
+} from './submit/intersectPayloadBlocksWithForm'
 export {
   copyTextToClipboard,
   submitFormJson,

package/src/styles/index.css

@@ -132,6 +132,11 @@
   min-width: 0;
 }
 
+.ask-user-form-card-status {
+  display: flex;
+  justify-content: flex-end;
+}
+
 .ask-user-form-actions {
   display: flex;
   justify-content: flex-end;

package/src/submit/buildCurlStatement.ts

@@ -11,3 +11,52 @@ export function buildCurlStatement(payload: unknown, callbackUrl?: string | null
     `  -d '${escapeSingleQuotes(body)}'`,
   ].join('\n')
 }
+
+function formatJsonBodyLine(key: string, value: unknown, trailingComma: boolean): string {
+  return `  ${JSON.stringify(key)}: ${JSON.stringify(value)}${trailingComma ? ',' : ''}`
+}
+
+/** 构建含行注释的 JSON body：extra 段标注「额外字段（未在卡片展示）」 */
+export function buildAskUserCurlBodyJson(
+  cardValues: Record<string, unknown>,
+  extraValues: Record<string, unknown>,
+): string {
+  const lines: string[] = ['{']
+  const cardEntries = Object.entries(cardValues)
+  const extraEntries = Object.entries(extraValues)
+
+  cardEntries.forEach(([key, value], index) => {
+    const hasMore = index < cardEntries.length - 1 || extraEntries.length > 0
+    lines.push(formatJsonBodyLine(key, value, hasMore))
+  })
+
+  if (extraEntries.length > 0) {
+    lines.push('  // 额外字段（未在卡片展示）')
+    extraEntries.forEach(([key, value], index) => {
+      lines.push(formatJsonBodyLine(key, value, index < extraEntries.length - 1))
+    })
+  }
+
+  lines.push('}')
+  return lines.join('\n')
+}
+
+export interface BuildAskUserCurlStatementOptions {
+  cardValues: Record<string, unknown>
+  extraValues?: Record<string, unknown>
+  callbackUrl?: string | null
+}
+
+export function buildAskUserCurlStatement({
+  cardValues,
+  extraValues = {},
+  callbackUrl,
+}: BuildAskUserCurlStatementOptions): string {
+  const url = (callbackUrl ?? '').trim() || '<callback_url>'
+  const body = buildAskUserCurlBodyJson(cardValues, extraValues)
+  return [
+    `curl -X POST '${url}' \\`,
+    `  -H 'Content-Type: application/json' \\`,
+    `  -d '${escapeSingleQuotes(body)}'`,
+  ].join('\n')
+}

package/src/submit/intersectPayloadBlocksWithForm.ts

@@ -0,0 +1,175 @@
+import { normalizeFormDefinition } from '../adapter/formSchema'
+import type { FormBlock, FormSchema } from '../types/index'
+import { isInputBlockType, isLayoutBlockType } from '../types/index'
+
+export type PayloadBlocksDefinition = Pick<FormSchema, 'title' | 'description' | 'blocks'>
+
+export interface PayloadBlocksIntersection {
+  matchedBlocks: FormBlock[]
+  extraBlocks: FormBlock[]
+  /** 按 payload 顺序：layout + matched input（不含 extra input） */
+  renderBlocks: FormBlock[]
+  title: string
+  description: string
+}
+
+function normalizePayloadBlock(block: FormBlock): FormBlock {
+  return normalizeFormDefinition({
+    title: '',
+    description: '',
+    blocks: [block],
+    jsonSchema: {},
+  }).blocks[0]!
+}
+
+function buildRenderBlocks(
+  payloadDef: PayloadBlocksDefinition,
+  matchedBlocks: FormBlock[],
+): FormBlock[] {
+  const matchedByName = new Map<string, FormBlock>()
+  for (const block of matchedBlocks) {
+    const name = block.name?.trim()
+    if (name) matchedByName.set(name, block)
+  }
+
+  const renderBlocks: FormBlock[] = []
+  for (const payloadBlock of payloadDef.blocks) {
+    if (isLayoutBlockType(payloadBlock.type)) {
+      renderBlocks.push(normalizePayloadBlock(payloadBlock))
+      continue
+    }
+    if (!isInputBlockType(payloadBlock.type)) continue
+    const name = payloadBlock.name?.trim()
+    if (!name) continue
+    const matched = matchedByName.get(name)
+    if (matched) renderBlocks.push(matched)
+  }
+  return renderBlocks
+}
+
+/** 交集块以 form 定义为准，仅从 payload 合并运行时 defaultValue。 */
+function mergeBlock(formBlock: FormBlock, payloadBlock: FormBlock): FormBlock {
+  const merged: FormBlock = {
+    ...formBlock,
+    name: formBlock.name?.trim() || payloadBlock.name,
+  }
+  if (payloadBlock.defaultValue !== undefined) {
+    merged.defaultValue = payloadBlock.defaultValue
+  }
+  return normalizeFormDefinition({
+    title: '',
+    description: '',
+    blocks: [merged],
+    jsonSchema: {},
+  }).blocks[0]!
+}
+
+/** 解析 ask_user payload 为 blocksJson 形（title / description / blocks） */
+export function parsePayloadBlocksJson(payload: unknown): PayloadBlocksDefinition | null {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return null
+  const obj = payload as Record<string, unknown>
+  if (!Array.isArray(obj.blocks)) return null
+  return normalizeFormDefinition({
+    title: typeof obj.title === 'string' ? obj.title : '',
+    description: typeof obj.description === 'string' ? obj.description : '',
+    blocks: obj.blocks as FormBlock[],
+    jsonSchema: {},
+  })
+}
+
+/**
+ * payload.blocks 与 vt_forms 按 input 块 name 取交集用于渲染；
+ * payload 中 form 不存在的块归入 extraBlocks（不渲染，提交时写入 curl）。
+ */
+export function intersectPayloadBlocksWithForm(
+  payloadDef: PayloadBlocksDefinition,
+  formDefinition: FormSchema | undefined,
+): PayloadBlocksIntersection {
+  const formByName = new Map<string, FormBlock>()
+  for (const block of formDefinition?.blocks ?? []) {
+    if (isInputBlockType(block.type) && block.name?.trim()) {
+      formByName.set(block.name.trim(), block)
+    }
+  }
+
+  const matchedBlocks: FormBlock[] = []
+  const extraBlocks: FormBlock[] = []
+
+  for (const payloadBlock of payloadDef.blocks) {
+    if (!isInputBlockType(payloadBlock.type)) continue
+    const name = payloadBlock.name?.trim()
+    if (!name) continue
+    const formBlock = formByName.get(name)
+    if (formBlock) {
+      matchedBlocks.push(mergeBlock(formBlock, payloadBlock))
+    } else {
+      extraBlocks.push(
+        normalizeFormDefinition({
+          title: '',
+          description: '',
+          blocks: [payloadBlock],
+          jsonSchema: {},
+        }).blocks[0]!,
+      )
+    }
+  }
+
+  return {
+    matchedBlocks,
+    extraBlocks,
+    renderBlocks: buildRenderBlocks(payloadDef, matchedBlocks),
+    title: payloadDef.title?.trim() || formDefinition?.title?.trim() || '',
+    description: payloadDef.description?.trim() || formDefinition?.description?.trim() || '',
+  }
+}
+
+function blockValueFromDefault(block: FormBlock): unknown {
+  const { type, defaultValue } = block
+  if (defaultValue !== undefined) {
+    if (type === 'toggle') return defaultValue === true || defaultValue === 'true'
+    if (type === 'multiselect' || type === 'checkbox') {
+      if (Array.isArray(defaultValue)) return defaultValue.map(String)
+      if (typeof defaultValue === 'string' && defaultValue) return [defaultValue]
+      return []
+    }
+    return defaultValue
+  }
+  if (type === 'toggle') return false
+  if (type === 'multiselect' || type === 'checkbox') return []
+  if (type === 'number') return null
+  return ''
+}
+
+/** 从 extraBlocks 提取提交值（优先 defaultValue） */
+export function extractExtraBlockValues(extraBlocks: FormBlock[]): Record<string, unknown> {
+  const values: Record<string, unknown> = {}
+  for (const block of extraBlocks) {
+    if (!isInputBlockType(block.type)) continue
+    const name = block.name?.trim()
+    if (!name) continue
+    values[name] = blockValueFromDefault(block)
+  }
+  return values
+}
+
+/** payload 是否含至少一个具 name 的 input 块（可用于卡片 fallback） */
+export function payloadHasInputBlocks(payloadDef: PayloadBlocksDefinition): boolean {
+  return payloadDef.blocks.some(
+    (block) => isInputBlockType(block.type) && Boolean(block.name?.trim()),
+  )
+}
+
+/** 交集为空时 fallback：payload 中可上屏的 blocks（layout + input） */
+export function getPayloadRenderableBlocks(payloadDef: PayloadBlocksDefinition): FormBlock[] {
+  return payloadDef.blocks.filter((block) => {
+    if (isLayoutBlockType(block.type)) return true
+    return isInputBlockType(block.type) && Boolean(block.name?.trim())
+  })
+}
+
+/** payload 中所有 input 块 field name（fallback 提交用） */
+export function getPayloadInputFieldNames(payloadDef: PayloadBlocksDefinition): string[] {
+  return payloadDef.blocks
+    .filter((block) => isInputBlockType(block.type) && block.name?.trim())
+    .map((block) => block.name!.trim())
+}