@skopon-cool/form-sdk 0.1.0

package/src/components/AskUserFormCard.tsx

@@ -0,0 +1,155 @@
+import { useEffect, useMemo, useRef, useState } from 'react'
+import { Button, Spin, Tooltip } from 'antd'
+import type { FormDetailResult, FormSchema, SubmitMode } from '../types/index'
+import { buildAskUserSurface } from '../adapter/resolveSurface'
+import { buildCurlStatement } from '../submit/buildCurlStatement'
+import { intersectPayloadWithForm } from '../submit/intersectPayloadWithForm'
+import { copyTextToClipboard, submitFormJson } from '../submit/submitFormJson'
+import SkoponFormRenderer, { type SkoponFormRendererRef } from './SkoponFormRenderer'
+import CurlSubmitBlock from './CurlSubmitBlock'
+
+export interface AskUserFormCardProps {
+  payload: unknown
+  formUniqueId: string
+  callbackUrl?: string | null
+  submitMode?: SubmitMode
+  fetchFormDetail: (ref: { formUniqueId: string }) => Promise<FormDetailResult>
+  onNotify?: (type: 'success' | 'error', message: string) => void
+}
+
+export default function AskUserFormCard({
+  payload,
+  formUniqueId,
+  callbackUrl,
+  submitMode = 'curl',
+  fetchFormDetail,
+  onNotify,
+}: AskUserFormCardProps) {
+  const [formDef, setFormDef] = useState<FormSchema | null>(null)
+  const [formDisabled, setFormDisabled] = useState(false)
+  const [loading, setLoading] = useState(true)
+  const rendererRef = useRef<SkoponFormRendererRef>(null)
+
+  useEffect(() => {
+    let cancelled = false
+    setLoading(true)
+    setFormDisabled(false)
+    fetchFormDetail({ formUniqueId })
+      .then((detail) => {
+        if (cancelled) return
+        setFormDisabled(Boolean(detail.disabled))
+        setFormDef(detail.disabled ? null : detail.formDefinition ?? null)
+      })
+      .catch(() => {
+        if (!cancelled) {
+          setFormDisabled(false)
+          setFormDef(null)
+        }
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false)
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [formUniqueId, fetchFormDetail])
+
+  const { matchedBlocks, remainderPayload } = useMemo(
+    () => intersectPayloadWithForm(payload, formDef ?? undefined),
+    [payload, formDef],
+  )
+
+  const fieldNames = useMemo(
+    () =>
+      matchedBlocks
+        .map((block) => block.name?.trim())
+        .filter((name): name is string => Boolean(name)),
+    [matchedBlocks],
+  )
+
+  const surfaceDoc = useMemo(() => {
+    if (!formDef || matchedBlocks.length === 0) return null
+    return buildAskUserSurface(formDef, matchedBlocks)
+  }, [formDef, matchedBlocks])
+
+  if (loading) {
+    return (
+      <div className="ask-user-form-card">
+        <Spin size="small" />
+      </div>
+    )
+  }
+
+  if (matchedBlocks.length === 0) {
+    return (
+      <CurlSubmitBlock
+        payload={payload}
+        callbackUrl={callbackUrl}
+        unpublishedFormId={formDisabled ? formUniqueId : undefined}
+        onNotify={onNotify}
+      />
+    )
+  }
+
+  const hasRemainder = Object.keys(remainderPayload).length > 0
+
+  async function handleSubmit() {
+    const values = rendererRef.current?.getValues(fieldNames) ?? {}
+    if (submitMode === 'post') {
+      const url = (callbackUrl ?? '').trim()
+      if (!url) {
+        onNotify?.('error', 'callback_url 为空，无法提交')
+        return
+      }
+      try {
+        const result = await submitFormJson(url, values)
+        if (result.ok) {
+          onNotify?.('success', '提交成功')
+        } else {
+          onNotify?.('error', `提交失败 (${result.status})`)
+        }
+      } catch (error) {
+        const detail = error instanceof Error ? error.message : '提交失败'
+        onNotify?.('error', detail)
+      }
+      return
+    }
+
+    try {
+      await copyTextToClipboard(buildCurlStatement(values, callbackUrl))
+      onNotify?.('success', '已复制 curl 到剪贴板')
+    } catch {
+      onNotify?.('error', '复制失败')
+    }
+  }
+
+  return (
+    <div className="ask-user-form-card">
+      <SkoponFormRenderer
+        ref={rendererRef}
+        doc={surfaceDoc}
+        surfaceId={`ask-user-${formUniqueId}`}
+        fieldNames={fieldNames}
+        interactive
+      />
+
+      <div className="ask-user-form-actions">
+        <Tooltip title={submitMode === 'curl' ? '点击复制 curl' : '提交 JSON 到 callback_url'}>
+          <Button type="primary" size="small" onClick={() => void handleSubmit()}>
+            提交
+          </Button>
+        </Tooltip>
+      </div>
+
+      {hasRemainder ? (
+        <CurlSubmitBlock
+          payload={remainderPayload}
+          callbackUrl={callbackUrl}
+          title="以下字段不在表单中，请使用 curl 提交"
+          incompleteFormId={formUniqueId}
+          onNotify={onNotify}
+        />
+      ) : null}
+    </div>
+  )
+}

package/src/components/CurlSubmitBlock.tsx

@@ -0,0 +1,60 @@
+import { useMemo } from 'react'
+import { Button, Tag, Tooltip, Typography } from 'antd'
+import { buildCurlStatement } from '../submit/buildCurlStatement'
+import { copyTextToClipboard } from '../submit/submitFormJson'
+
+export interface CurlSubmitBlockProps {
+  payload: unknown
+  callbackUrl?: string | null
+  title?: string
+  unpublishedFormId?: string | null
+  incompleteFormId?: string | null
+  onNotify?: (type: 'success' | 'error', message: string) => void
+}
+
+export default function CurlSubmitBlock({
+  payload,
+  callbackUrl,
+  title,
+  unpublishedFormId,
+  incompleteFormId,
+  onNotify,
+}: CurlSubmitBlockProps) {
+  const curl = useMemo(
+    () => buildCurlStatement(payload, callbackUrl),
+    [payload, callbackUrl],
+  )
+
+  async function handleCopy() {
+    try {
+      await copyTextToClipboard(curl)
+      onNotify?.('success', '已复制到剪贴板')
+    } catch {
+      onNotify?.('error', '复制失败')
+    }
+  }
+
+  return (
+    <div className="ask-user-curl-card">
+      <div className="ask-user-curl-card-header">
+        <div className="ask-user-curl-card-header-title">
+          <Typography.Text type="secondary">{title ?? 'curl 命令'}</Typography.Text>
+          {unpublishedFormId ? (
+            <Tooltip title={unpublishedFormId}>
+              <Tag className="ask-user-curl-unpublished-tag">卡片 ID 未发布</Tag>
+            </Tooltip>
+          ) : null}
+          {incompleteFormId ? (
+            <Tooltip title={incompleteFormId}>
+              <Tag className="ask-user-curl-incomplete-tag">卡片 ID 待补足</Tag>
+            </Tooltip>
+          ) : null}
+        </div>
+        <Button size="small" type="text" onClick={() => void handleCopy()}>
+          复制
+        </Button>
+      </div>
+      <pre className="skopon-form-curl-json">{curl}</pre>
+    </div>
+  )
+}

package/src/components/SkoponA2uiStreamRenderer.tsx

@@ -0,0 +1,70 @@
+import { useEffect, useMemo, 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'
+import { injectStyles } from '@a2ui/react/styles'
+import { buildSkoponCatalog } from '../catalog/a2uiCustomCatalog'
+import { A2uiPreviewModeProvider } from '../catalog/a2uiPreviewContext'
+
+export interface SkoponA2uiStreamRendererProps {
+  /** 增量追加的 A2UI v0.9 消息 */
+  messages: A2uiMessage[]
+  surfaceId?: string
+  emptyHint?: ReactNode
+  interactive?: boolean
+}
+
+export default function SkoponA2uiStreamRenderer({
+  messages,
+  surfaceId = 'skopon-form-stream',
+  emptyHint = null,
+  interactive = true,
+}: SkoponA2uiStreamRendererProps) {
+  useEffect(() => {
+    injectStyles()
+    injectBasicCatalogStyles()
+  }, [])
+
+  const processorRef = useRef<MessageProcessor<ReactComponentImplementation> | null>(null)
+  const processedCountRef = useRef(0)
+
+  const processor = useMemo(() => {
+    const p = new MessageProcessor([buildSkoponCatalog()])
+    processorRef.current = p
+    processedCountRef.current = 0
+    return p
+  }, [surfaceId])
+
+  const [surfaces, setSurfaces] = useState(() => Array.from(processor.model.surfacesMap.values()))
+
+  useEffect(() => {
+    const sync = () => setSurfaces(Array.from(processor.model.surfacesMap.values()))
+    const createdSub = processor.onSurfaceCreated(sync)
+    const deletedSub = processor.onSurfaceDeleted(sync)
+    return () => {
+      createdSub.unsubscribe()
+      deletedSub.unsubscribe()
+    }
+  }, [processor])
+
+  useEffect(() => {
+    if (!Array.isArray(messages) || messages.length === 0) return
+    const pending = messages.slice(processedCountRef.current)
+    if (pending.length === 0) return
+    processor.processMessages(pending)
+    processedCountRef.current = messages.length
+    setSurfaces(Array.from(processor.model.surfacesMap.values()))
+  }, [messages, processor])
+
+  if (surfaces.length === 0) return <>{emptyHint}</>
+
+  return (
+    <A2uiPreviewModeProvider interactive={interactive}>
+      <div className="a2ui-surface a2ui-container">
+        {surfaces.map((surface) => (
+          <A2uiSurface key={surface.id} surface={surface} />
+        ))}
+      </div>
+    </A2uiPreviewModeProvider>
+  )
+}

package/src/components/SkoponFormRenderer.tsx

@@ -0,0 +1,100 @@
+import {
+  forwardRef,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  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'
+import { injectStyles } from '@a2ui/react/styles'
+import type { A2uiSurfaceDoc } from '../types/index'
+import { extractSurfaceValues } from '../adapter/extractSurfaceValues'
+import { isA2uiSurfaceEmpty, surfaceDocToMessages } from '../adapter/a2uiAdapter'
+import { SKOPON_CATALOG_ID, buildSkoponCatalog } from '../catalog/a2uiCustomCatalog'
+import { A2uiPreviewModeProvider } from '../catalog/a2uiPreviewContext'
+
+export interface SkoponFormRendererRef {
+  getValues: (fieldNames?: string[]) => Record<string, unknown>
+}
+
+export interface SkoponFormRendererProps {
+  doc: A2uiSurfaceDoc | null | undefined
+  surfaceId?: string
+  emptyHint?: ReactNode
+  interactive?: boolean
+  /** 默认用于 getValues() 的字段名列表 */
+  fieldNames?: string[]
+}
+
+const SkoponFormRenderer = forwardRef<SkoponFormRendererRef, SkoponFormRendererProps>(
+  function SkoponFormRenderer(
+    {
+      doc,
+      surfaceId = 'skopon-form',
+      emptyHint = null,
+      interactive = true,
+      fieldNames = [],
+    },
+    ref,
+  ) {
+    useEffect(() => {
+      injectStyles()
+      injectBasicCatalogStyles()
+    }, [])
+
+    const processorRef = useRef<MessageProcessor<ReactComponentImplementation> | null>(null)
+    const fieldNamesRef = useRef(fieldNames)
+    fieldNamesRef.current = fieldNames
+
+    const surfaces = useMemo(() => {
+      if (isA2uiSurfaceEmpty(doc)) {
+        processorRef.current = null
+        return []
+      }
+      try {
+        const processor = new MessageProcessor([buildSkoponCatalog()])
+        const messages = surfaceDocToMessages(doc!, {
+          surfaceId,
+          catalogId: SKOPON_CATALOG_ID,
+        }) as unknown as A2uiMessage[]
+        processor.processMessages(messages)
+        processorRef.current = processor
+        return Array.from(processor.model.surfacesMap.values())
+      } catch (error) {
+        console.error('[SkoponFormRenderer] 渲染 A2UI surface 失败', error)
+        processorRef.current = null
+        return []
+      }
+    }, [doc, surfaceId])
+
+    useImperativeHandle(
+      ref,
+      () => ({
+        getValues(names) {
+          const processor = processorRef.current
+          if (!processor) return {}
+          const resolvedNames = (names ?? fieldNamesRef.current).map((n) => n.trim()).filter(Boolean)
+          return extractSurfaceValues(processor, surfaceId, resolvedNames)
+        },
+      }),
+      [surfaceId],
+    )
+
+    if (surfaces.length === 0) return <>{emptyHint}</>
+
+    return (
+      <A2uiPreviewModeProvider interactive={interactive}>
+        <div className="a2ui-surface a2ui-container">
+          {surfaces.map((surface) => (
+            <A2uiSurface key={surface.id} surface={surface} />
+          ))}
+        </div>
+      </A2uiPreviewModeProvider>
+    )
+  },
+)
+
+export default SkoponFormRenderer

package/src/icons/FilePlaceholderIcon.tsx

@@ -0,0 +1,40 @@
+import {
+  FileExcelOutlined,
+  FileOutlined,
+  FileTextOutlined,
+  PictureOutlined,
+  SoundOutlined,
+  VideoCameraOutlined,
+} from '@ant-design/icons'
+import type { FormFilePlaceholderIcon } from '../types/index'
+
+const PLACEHOLDER_ICON_COMPONENTS = {
+  video: VideoCameraOutlined,
+  audio: SoundOutlined,
+  image: PictureOutlined,
+  file: FileOutlined,
+  spreadsheet: FileExcelOutlined,
+  document: FileTextOutlined,
+} satisfies Record<FormFilePlaceholderIcon, typeof FileOutlined>
+
+interface FilePlaceholderIconProps {
+  type: FormFilePlaceholderIcon
+  size?: number
+  className?: string
+}
+
+/** 文件上传占位图标（@ant-design/icons，与 admin 编辑区语义对齐）。 */
+export default function FilePlaceholderIcon({
+  type,
+  size = 40,
+  className,
+}: FilePlaceholderIconProps) {
+  const Icon = PLACEHOLDER_ICON_COMPONENTS[type] ?? FileOutlined
+  return (
+    <Icon
+      className={className ?? 'skopon-form-file-placeholder-icon'}
+      style={{ fontSize: size, color: 'var(--color-primary, #1677ff)' }}
+      aria-hidden
+    />
+  )
+}

package/src/index.ts

@@ -0,0 +1,67 @@
+export type {
+  A2uiBinding,
+  A2uiComponentName,
+  A2uiComponentNode,
+  A2uiSurfaceDoc,
+  FormBlock,
+  FormBlockOption,
+  FormBlockType,
+  FormDefinitionPayload,
+  FormDetailResult,
+  FormFilePlaceholderIcon,
+  FormJsonSchema,
+  FormMediaSize,
+  FormSchema,
+  SubmitMode,
+} from './types/index'
+
+export {
+  A2UI_PROTOCOL_VERSION,
+  FORM_MEDIA_SIZES,
+  isInputBlockType,
+  isLayoutBlockType,
+  isMediaBlockType,
+} from './types/index'
+
+export {
+  a2uiToBlocks,
+  blocksToA2ui,
+  isA2uiSurfaceEmpty,
+  surfaceDocToMessages,
+  type BlocksToA2uiOptions,
+} from './adapter/a2uiAdapter'
+
+export {
+  buildAskUserSurface,
+  mapFormDefinitionFromDto,
+  resolveSurfaceFromFormDefinition,
+} from './adapter/resolveSurface'
+
+export { normalizeFormDefinition, syncFormDefinition } from './adapter/formSchema'
+
+export { extractSurfaceValues } from './adapter/extractSurfaceValues'
+
+export { buildCurlStatement } from './submit/buildCurlStatement'
+export { intersectPayloadWithForm, type PayloadFormIntersection } from './submit/intersectPayloadWithForm'
+export {
+  copyTextToClipboard,
+  submitFormJson,
+  type SubmitFormJsonOptions,
+  type SubmitFormJsonResult,
+} from './submit/submitFormJson'
+
+export { createFormClient, type FormClient, type FormClientOptions } from './client/formClient'
+
+export { default as SkoponFormRenderer } from './components/SkoponFormRenderer'
+export type { SkoponFormRendererProps, SkoponFormRendererRef } from './components/SkoponFormRenderer'
+
+export { default as SkoponA2uiStreamRenderer } from './components/SkoponA2uiStreamRenderer'
+export type { SkoponA2uiStreamRendererProps } from './components/SkoponA2uiStreamRenderer'
+
+export { default as AskUserFormCard } from './components/AskUserFormCard'
+export type { AskUserFormCardProps } from './components/AskUserFormCard'
+
+export { default as CurlSubmitBlock } from './components/CurlSubmitBlock'
+export type { CurlSubmitBlockProps } from './components/CurlSubmitBlock'
+
+import './styles/index.css'