@skopon-cool/form-sdk 0.1.0

package/src/catalog/a2uiCustomCatalog.tsx

@@ -0,0 +1,548 @@
+import { z } from 'zod'
+import { Catalog, type ComponentContext } from '@a2ui/web_core/v0_9'
+import {
+  basicCatalog,
+  createBinderlessComponentImplementation,
+  type ReactComponentImplementation,
+} from '@a2ui/react/v0_9'
+import { Checkbox, DatePicker, Radio, Select, Switch, TimePicker, Typography, Upload } from 'antd'
+import dayjs, { type Dayjs } from 'dayjs'
+import type { FormFilePlaceholderIcon, FormMediaSize } from '../types/index'
+import {
+  buildFileAcceptAttribute,
+  formatFileAcceptSummary,
+} from '../adapter/formFileAccept'
+import { buildMediaListClassName, normalizeMediaSize } from '../adapter/formMedia'
+import FilePlaceholderIcon from '../icons/FilePlaceholderIcon'
+import { useA2uiPreviewMode } from './a2uiPreviewContext'
+import {
+  asOptionalString,
+  asStringArray,
+  useSkoponBoundField,
+} from './useSkoponBoundField'
+
+/**
+ * 在 A2UI basicCatalog 基础上扩展/覆盖 skopon 预览组件，
+ * 使 A2uiFormRenderer 与编辑区 BlockPreview 视觉一致。
+ */
+export const SKOPON_CATALOG_ID = 'skopon-form-v0_9'
+
+const SKOPON_COMPONENT_NAMES = new Set([
+  'SkoponMedia',
+  'SkoponSelect',
+  'Image',
+  'Video',
+  'AudioPlayer',
+  'ChoicePicker',
+  'CheckBox',
+  'DateTimeInput',
+  'FileUpload',
+])
+
+function getBasicSchema(name: string): z.ZodTypeAny {
+  const impl = [...basicCatalog.components.values()].find((c) => c.name === name)
+  if (!impl) throw new Error(`Missing basic catalog component: ${name}`)
+  return impl.schema
+}
+
+function readString(value: unknown): string {
+  return typeof value === 'string' ? value : ''
+}
+
+function readOptions(
+  raw: unknown,
+): { label: string; value: string }[] {
+  if (!Array.isArray(raw)) return []
+  return raw
+    .map((item) => {
+      if (!item || typeof item !== 'object') return null
+      const rec = item as Record<string, unknown>
+      const value = String(rec.value ?? rec.label ?? '')
+      const label = String(rec.label ?? rec.value ?? '')
+      return { value, label }
+    })
+    .filter((item): item is { label: string; value: string } => !!item)
+}
+
+interface SkoponMediaPreviewProps {
+  mediaType: 'image' | 'video' | 'audio'
+  urls: string[]
+  mediaSize?: FormMediaSize
+  label?: string
+  help?: string
+  placeholder?: string
+}
+
+function SkoponMediaPreview({
+  mediaType,
+  urls,
+  mediaSize,
+  label,
+  help,
+  placeholder,
+}: SkoponMediaPreviewProps) {
+  const fieldLabel = label?.trim()
+  const helpText = help?.trim()
+  const listClassName = buildMediaListClassName(mediaSize)
+  const emptyLabel =
+    placeholder?.trim() ||
+    (mediaType === 'image'
+      ? '未设置图片 URL'
+      : mediaType === 'video'
+        ? '未设置视频 URL'
+        : '未设置音频 URL')
+
+  return (
+    <div className="form-block-preview">
+      {fieldLabel ? <div className="form-block-preview-label">{fieldLabel}</div> : null}
+      {urls.length === 0 ? (
+        <div className="form-media-preview form-media-preview--empty">{emptyLabel}</div>
+      ) : (
+        <div className={listClassName}>
+          {urls.map((url, index) => {
+            if (mediaType === 'image') {
+              return (
+                <img
+                  key={`media-${index}`}
+                  src={url}
+                  alt={fieldLabel || '图片'}
+                  className="form-media-item"
+                />
+              )
+            }
+            if (mediaType === 'video') {
+              return (
+                <video
+                  key={`media-${index}`}
+                  src={url}
+                  controls
+                  className="form-media-item"
+                />
+              )
+            }
+            return (
+              <audio
+                key={`media-${index}`}
+                src={url}
+                controls
+                className="form-media-item form-media-item--audio"
+              />
+            )
+          })}
+        </div>
+      )}
+      {helpText ? (
+        <Typography.Text type="secondary" className="form-block-preview-help">
+          {helpText}
+        </Typography.Text>
+      ) : null}
+    </div>
+  )
+}
+
+function readMediaPreviewProps(
+  props: Record<string, unknown>,
+  mediaType: 'image' | 'video' | 'audio',
+): SkoponMediaPreviewProps {
+  const urls = Array.isArray(props.urls)
+    ? props.urls.map((u) => String(u).trim()).filter(Boolean)
+    : readString(props.url).trim()
+      ? [readString(props.url).trim()]
+      : []
+  return {
+    mediaType,
+    urls,
+    mediaSize: normalizeMediaSize(props.mediaSize as FormMediaSize | undefined),
+    label: readString(props.label) || readString(props.description),
+    help: readString(props.help),
+    placeholder: readString(props.placeholder),
+  }
+}
+
+const SkoponMediaApi = {
+  name: 'SkoponMedia',
+  schema: z
+    .object({
+      mediaType: z.any().optional(),
+      urls: z.any().optional(),
+      mediaSize: z.any().optional(),
+      label: z.any().optional(),
+      help: z.any().optional(),
+      placeholder: z.any().optional(),
+    })
+    .passthrough(),
+}
+
+const SkoponMediaImpl = createBinderlessComponentImplementation(SkoponMediaApi, ({ context }) => {
+  const props = context.componentModel.properties as Record<string, unknown>
+  const mediaTypeRaw = readString(props.mediaType)
+  const mediaType =
+    mediaTypeRaw === 'video' ? 'video' : mediaTypeRaw === 'audio' ? 'audio' : 'image'
+  return <SkoponMediaPreview {...readMediaPreviewProps(props, mediaType)} />
+})
+
+const ImageImpl = createBinderlessComponentImplementation(
+  { name: 'Image', schema: getBasicSchema('Image') },
+  ({ context }) => (
+    <SkoponMediaPreview {...readMediaPreviewProps(context.componentModel.properties as Record<string, unknown>, 'image')} />
+  ),
+)
+
+const VideoImpl = createBinderlessComponentImplementation(
+  { name: 'Video', schema: getBasicSchema('Video') },
+  ({ context }) => (
+    <SkoponMediaPreview {...readMediaPreviewProps(context.componentModel.properties as Record<string, unknown>, 'video')} />
+  ),
+)
+
+const AudioPlayerImpl = createBinderlessComponentImplementation(
+  { name: 'AudioPlayer', schema: getBasicSchema('AudioPlayer') },
+  ({ context }) => (
+    <SkoponMediaPreview {...readMediaPreviewProps(context.componentModel.properties as Record<string, unknown>, 'audio')} />
+  ),
+)
+
+const SkoponSelectApi = {
+  name: 'SkoponSelect',
+  schema: z
+    .object({
+      label: z.any().optional(),
+      mode: z.any().optional(),
+      placeholder: z.any().optional(),
+      options: z.any().optional(),
+      value: z.any().optional(),
+    })
+    .passthrough(),
+}
+
+function SkoponSelectPreview({ context }: { context: ComponentContext }) {
+  const { interactive } = useA2uiPreviewMode()
+  const { value, setValue } = useSkoponBoundField(context)
+  const props = context.componentModel.properties as Record<string, unknown>
+  const label = readString(props.label)
+  const placeholder = readString(props.placeholder)
+  const options = readOptions(props.options)
+  const isMultiple = readString(props.mode) === 'multiple'
+
+  return (
+    <div className="form-block-preview">
+      {label ? <div className="form-block-preview-label">{label}</div> : null}
+      <Select
+        mode={isMultiple ? 'multiple' : undefined}
+        disabled={!interactive}
+        allowClear
+        className="form-block-preview-control"
+        style={{ width: '100%' }}
+        placeholder={placeholder || (isMultiple ? '请选择多项' : '请选择')}
+        options={options}
+        value={isMultiple ? asStringArray(value) : asOptionalString(value)}
+        onChange={(next) => setValue(isMultiple ? (next ?? []) : (next ?? ''))}
+      />
+    </div>
+  )
+}
+
+const SkoponSelectImpl = createBinderlessComponentImplementation(
+  SkoponSelectApi,
+  SkoponSelectPreview,
+)
+
+function ChoicePickerPreview({ context }: { context: ComponentContext }) {
+  const { interactive } = useA2uiPreviewMode()
+  const { value, setValue } = useSkoponBoundField(context)
+  const props = context.componentModel.properties as Record<string, unknown>
+  const label = readString(props.label)
+  const variant = readString(props.variant) || 'mutuallyExclusive'
+  const pickerType = readString(props.skoponPickerType)
+  const placeholder = readString(props.placeholder)
+  const options = readOptions(props.options)
+  const isMultiple = variant === 'multipleSelection'
+  const effectiveType =
+    pickerType === 'select' ||
+    pickerType === 'multiselect' ||
+    pickerType === 'radio' ||
+    pickerType === 'checkbox'
+      ? pickerType
+      : isMultiple
+        ? 'checkbox'
+        : 'radio'
+
+  return (
+    <div className="form-block-preview">
+      {label ? <div className="form-block-preview-label">{label}</div> : null}
+      {effectiveType === 'select' ? (
+        <Select
+          disabled={!interactive}
+          allowClear
+          className="form-block-preview-control"
+          style={{ width: '100%' }}
+          placeholder={placeholder || '请选择'}
+          options={options}
+          value={asOptionalString(value)}
+          onChange={(next) => setValue(next ?? '')}
+        />
+      ) : effectiveType === 'multiselect' ? (
+        <Select
+          mode="multiple"
+          disabled={!interactive}
+          allowClear
+          className="form-block-preview-control"
+          style={{ width: '100%' }}
+          placeholder={placeholder || '请选择多项'}
+          options={options}
+          value={asStringArray(value)}
+          onChange={(next) => setValue(next ?? [])}
+        />
+      ) : effectiveType === 'checkbox' ? (
+        <Checkbox.Group
+          disabled={!interactive}
+          className="form-block-preview-control"
+          options={options}
+          value={asStringArray(value)}
+          onChange={(next) => setValue(next)}
+        />
+      ) : (
+        <Radio.Group
+          disabled={!interactive}
+          className="form-block-preview-control"
+          options={options}
+          value={asOptionalString(value)}
+          onChange={(e) => setValue(e.target.value)}
+        />
+      )}
+    </div>
+  )
+}
+
+const ChoicePickerImpl = createBinderlessComponentImplementation(
+  {
+    name: 'ChoicePicker',
+    schema: z
+      .object({
+        label: z.any().optional(),
+        variant: z.any().optional(),
+        options: z.any().optional(),
+        value: z.any().optional(),
+        skoponPickerType: z.any().optional(),
+        placeholder: z.any().optional(),
+      })
+      .passthrough(),
+  },
+  ChoicePickerPreview,
+)
+
+function ToggleSwitchPreview({ context }: { context: ComponentContext }) {
+  const { interactive } = useA2uiPreviewMode()
+  const { value, setValue } = useSkoponBoundField(context)
+  const props = context.componentModel.properties as Record<string, unknown>
+  const label = readString(props.label)
+
+  return (
+    <div className="form-block-preview">
+      {label ? <div className="form-block-preview-label">{label}</div> : null}
+      <Switch
+        disabled={!interactive}
+        className="form-block-preview-control"
+        checked={value === true}
+        onChange={(checked) => setValue(checked)}
+      />
+    </div>
+  )
+}
+
+const CheckBoxImpl = createBinderlessComponentImplementation(
+  { name: 'CheckBox', schema: getBasicSchema('CheckBox') },
+  ToggleSwitchPreview,
+)
+
+function toDateTimePickerValue(
+  raw: unknown,
+  enableDate: boolean,
+  enableTime: boolean,
+): Dayjs | undefined {
+  const text = asOptionalString(raw)
+  if (!text) return undefined
+  if (!enableDate && enableTime) {
+    const parsed = dayjs(text, 'HH:mm', true)
+    return parsed.isValid() ? parsed : undefined
+  }
+  const parsed = dayjs(text)
+  return parsed.isValid() ? parsed : undefined
+}
+
+function DateTimeInputPreview({ context }: { context: ComponentContext }) {
+  const { interactive } = useA2uiPreviewMode()
+  const { value, setValue } = useSkoponBoundField(context)
+  const props = context.componentModel.properties as Record<string, unknown>
+  const label = readString(props.label)
+  const placeholder = readString(props.placeholder)
+  const enableDate = props.enableDate === true
+  const enableTime = props.enableTime === true
+  const pickerValue = toDateTimePickerValue(value, enableDate, enableTime)
+
+  const handleChange = (next: Dayjs | null) => {
+    if (!next) {
+      setValue('')
+      return
+    }
+    if (!enableDate && enableTime) {
+      setValue(next.format('HH:mm'))
+      return
+    }
+    if (enableDate && enableTime) {
+      setValue(next.format('YYYY-MM-DDTHH:mm'))
+      return
+    }
+    setValue(next.format('YYYY-MM-DD'))
+  }
+
+  return (
+    <div className="form-block-preview">
+      {label ? <div className="form-block-preview-label">{label}</div> : null}
+      {!enableDate && enableTime ? (
+        <TimePicker
+          disabled={!interactive}
+          className="form-block-preview-control"
+          style={{ width: '100%' }}
+          placeholder={placeholder || '选择时间'}
+          value={pickerValue}
+          onChange={handleChange}
+        />
+      ) : (
+        <DatePicker
+          showTime={enableDate && enableTime}
+          disabled={!interactive}
+          className="form-block-preview-control"
+          style={{ width: '100%' }}
+          placeholder={
+            placeholder ||
+            (enableDate && enableTime ? '选择日期时间' : '选择日期')
+          }
+          value={pickerValue}
+          onChange={handleChange}
+        />
+      )}
+    </div>
+  )
+}
+
+const DateTimeInputImpl = createBinderlessComponentImplementation(
+  {
+    name: 'DateTimeInput',
+    schema: z
+      .object({
+        label: z.any().optional(),
+        enableDate: z.any().optional(),
+        enableTime: z.any().optional(),
+        placeholder: z.any().optional(),
+        value: z.any().optional(),
+        min: z.any().optional(),
+        max: z.any().optional(),
+      })
+      .passthrough(),
+  },
+  DateTimeInputPreview,
+)
+
+const FileUploadApi = {
+  name: 'FileUpload',
+  schema: z
+    .object({
+      label: z.any().optional(),
+      accept: z.any().optional(),
+      fileAcceptTypes: z.any().optional(),
+      filePlaceholderIcon: z.any().optional(),
+      minCount: z.any().optional(),
+      maxCount: z.any().optional(),
+      value: z.any().optional(),
+    })
+    .passthrough(),
+}
+
+function FileUploadPreview({ context }: { context: ComponentContext }) {
+  const { interactive } = useA2uiPreviewMode()
+  const { value, setValue } = useSkoponBoundField(context)
+  const props = context.componentModel.properties as Record<string, unknown>
+  const label = readString(props.label)
+  const accept = readString(props.accept)
+  const fileAcceptTypes = Array.isArray(props.fileAcceptTypes)
+    ? props.fileAcceptTypes.map(String)
+    : undefined
+  const fileAcceptExtensions = accept
+    ? accept.split(',').map((s) => s.trim()).filter(Boolean)
+    : undefined
+  const acceptSummary = formatFileAcceptSummary(fileAcceptTypes, fileAcceptExtensions)
+  const placeholderIcon: FormFilePlaceholderIcon =
+    typeof props.filePlaceholderIcon === 'string' &&
+    ['video', 'audio', 'image', 'file', 'spreadsheet', 'document'].includes(
+      props.filePlaceholderIcon,
+    )
+      ? (props.filePlaceholderIcon as FormFilePlaceholderIcon)
+      : 'document'
+  const maxCount = typeof props.maxCount === 'number' ? props.maxCount : 1
+  const selectedNames = asStringArray(value)
+
+  return (
+    <div className="form-block-preview">
+      {label ? <div className="form-block-preview-label">{label}</div> : null}
+      <Upload.Dragger
+        disabled={!interactive}
+        accept={buildFileAcceptAttribute(fileAcceptTypes, fileAcceptExtensions)}
+        className="form-file-upload-preview"
+        showUploadList={interactive && selectedNames.length > 0}
+        fileList={
+          interactive
+            ? selectedNames.map((name, index) => ({
+                uid: `${index}-${name}`,
+                name,
+                status: 'done' as const,
+              }))
+            : []
+        }
+        beforeUpload={(file) => {
+          if (!interactive) return Upload.LIST_IGNORE
+          const next = [...selectedNames, file.name].slice(0, Math.max(1, maxCount))
+          setValue(next)
+          return false
+        }}
+        onRemove={(file) => {
+          setValue(selectedNames.filter((name) => name !== file.name))
+        }}
+      >
+        <p className="form-file-upload-preview-icon">
+          <FilePlaceholderIcon type={placeholderIcon} size={40} />
+        </p>
+        <p className="form-file-upload-preview-text">点击或拖拽文件到此处上传</p>
+      </Upload.Dragger>
+      <Typography.Text type="secondary" className="form-block-preview-help">
+        允许：{acceptSummary ?? '全部类型'}
+      </Typography.Text>
+    </div>
+  )
+}
+
+const FileUploadImpl = createBinderlessComponentImplementation(
+  FileUploadApi,
+  FileUploadPreview,
+)
+
+/** 构建合并后的 skopon catalog（预览每次重建，避免 HMR 缓存旧组件）。 */
+export function buildSkoponCatalog(): Catalog<ReactComponentImplementation> {
+  const baseComponents = [...basicCatalog.components.values()].filter(
+    (component) => !SKOPON_COMPONENT_NAMES.has(component.name),
+  )
+  const components = [
+    ...baseComponents,
+    SkoponMediaImpl,
+    SkoponSelectImpl,
+    ImageImpl,
+    VideoImpl,
+    AudioPlayerImpl,
+    ChoicePickerImpl,
+    CheckBoxImpl,
+    DateTimeInputImpl,
+    FileUploadImpl,
+  ]
+  const functions = [...basicCatalog.functions.values()]
+  return new Catalog(SKOPON_CATALOG_ID, components, functions, basicCatalog.themeSchema)
+}

package/src/catalog/a2uiPreviewContext.tsx

@@ -0,0 +1,26 @@
+import { createContext, useContext, type ReactNode } from 'react'
+
+export interface A2uiPreviewMode {
+  /** 预览是否允许填写交互（默认 true） */
+  interactive: boolean
+}
+
+const A2uiPreviewModeContext = createContext<A2uiPreviewMode>({ interactive: true })
+
+export function A2uiPreviewModeProvider({
+  interactive,
+  children,
+}: {
+  interactive: boolean
+  children: ReactNode
+}) {
+  return (
+    <A2uiPreviewModeContext.Provider value={{ interactive }}>
+      {children}
+    </A2uiPreviewModeContext.Provider>
+  )
+}
+
+export function useA2uiPreviewMode(): A2uiPreviewMode {
+  return useContext(A2uiPreviewModeContext)
+}

package/src/catalog/useSkoponBoundField.ts

@@ -0,0 +1,57 @@
+import { useCallback, useSyncExternalStore } from 'react'
+import type { ComponentContext } from '@a2ui/web_core/v0_9'
+
+type DynamicBinding = Parameters<ComponentContext['dataContext']['resolveDynamicValue']>[0]
+
+function bindingPath(value: unknown): string | null {
+  if (value && typeof value === 'object' && 'path' in value) {
+    const path = String((value as { path: unknown }).path ?? '').trim()
+    return path || null
+  }
+  return null
+}
+
+/** 将 skopon 预览控件绑定到 A2UI surface dataModel（与 basicCatalog binder 行为一致）。 */
+export function useSkoponBoundField(context: ComponentContext, field = 'value') {
+  const props = context.componentModel.properties as Record<string, unknown>
+  const binding = props[field] as DynamicBinding | undefined
+  const path = bindingPath(binding)
+
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => {
+      if (!path || binding === undefined) return () => {}
+      const sub = context.dataContext.subscribeDynamicValue(binding, () => onStoreChange())
+      return () => sub.unsubscribe()
+    },
+    [context, binding, path],
+  )
+
+  const getSnapshot = useCallback(() => {
+    if (!path || binding === undefined) return undefined
+    return context.dataContext.resolveDynamicValue(binding)
+  }, [context, binding, path])
+
+  const value = path ? useSyncExternalStore(subscribe, getSnapshot, getSnapshot) : undefined
+
+  const setValue = useCallback(
+    (next: unknown) => {
+      if (!path || !binding || typeof binding !== 'object' || !('path' in binding)) return
+      context.dataContext.set(String((binding as { path: string }).path), next)
+    },
+    [context, binding, path],
+  )
+
+  return { value, setValue, hasBinding: !!path }
+}
+
+export function asOptionalString(value: unknown): string | undefined {
+  if (typeof value === 'string') return value || undefined
+  if (typeof value === 'number') return String(value)
+  return undefined
+}
+
+export function asStringArray(value: unknown): string[] {
+  if (Array.isArray(value)) return value.map(String)
+  if (typeof value === 'string' && value) return [value]
+  return []
+}

package/src/client/formClient.ts

@@ -0,0 +1,72 @@
+import type { FormDetailResult, FormSchema } from '../types/index'
+import { mapFormDefinitionFromDto, resolveSurfaceFromFormDefinition } from '../adapter/resolveSurface'
+
+export interface FormDetailDto {
+  form_id: number
+  form_unique_id: string
+  name: string
+  disabled: number
+  form_definition: Record<string, unknown>
+}
+
+export interface FormClientOptions {
+  baseUrl?: string
+  detailPath?: string
+  fetch?: typeof fetch
+  getHeaders?: () => Record<string, string> | Promise<Record<string, string>>
+}
+
+export interface FormClient {
+  fetchDetail: (ref: { formUniqueId?: string; formId?: number }) => Promise<FormDetailResult>
+}
+
+interface ApiEnvelope<T> {
+  success?: boolean
+  data?: T
+  message?: string
+}
+
+async function parseEnvelope<T>(response: Response): Promise<T> {
+  const json = (await response.json()) as ApiEnvelope<T>
+  if (!response.ok || json.success === false) {
+    throw new Error(json.message || `请求失败 (${response.status})`)
+  }
+  return json.data as T
+}
+
+export function createFormClient(options: FormClientOptions = {}): FormClient {
+  const baseUrl = (options.baseUrl ?? '/api/v1').replace(/\/$/, '')
+  const detailPath = options.detailPath ?? '/dev/form/detail'
+  const fetchFn = options.fetch ?? fetch
+
+  async function fetchDetail(ref: {
+    formUniqueId?: string
+    formId?: number
+  }): Promise<FormDetailResult> {
+    const params = new URLSearchParams()
+    if (ref.formId !== undefined) {
+      params.set('form_id', String(ref.formId))
+    } else if (ref.formUniqueId) {
+      params.set('form_unique_id', ref.formUniqueId)
+    } else {
+      throw new Error('form_id 或 form_unique_id 至少传一个')
+    }
+
+    const headers = (await options.getHeaders?.()) ?? {}
+    const response = await fetchFn(`${baseUrl}${detailPath}?${params.toString()}`, {
+      method: 'GET',
+      headers,
+    })
+    const dto = await parseEnvelope<FormDetailDto>(response)
+    const formDefinition = mapFormDefinitionFromDto(dto.form_definition) as FormSchema | undefined
+    return {
+      formUniqueId: dto.form_unique_id,
+      formId: dto.form_id,
+      disabled: dto.disabled === 1,
+      formDefinition,
+      a2ui: resolveSurfaceFromFormDefinition(dto.form_definition) ?? undefined,
+    }
+  }
+
+  return { fetchDetail }
+}