@skopon-cool/form-sdk 0.1.0

package/src/adapter/formFileAccept.ts

@@ -0,0 +1,198 @@
+export interface FormFileAcceptOption {
+  value: string
+  label: string
+}
+
+/** UI 选项 value；Office 类为分组 key，生成 accept 时展开为多个 MIME */
+export const FORM_FILE_TYPE_OPTIONS: FormFileAcceptOption[] = [
+  { value: 'image/*', label: '图片' },
+  { value: 'video/*', label: '视频' },
+  { value: 'audio/*', label: '音频' },
+  { value: 'application/pdf', label: 'PDF' },
+  { value: 'office/word', label: 'Word' },
+  { value: 'office/excel', label: 'Excel' },
+  { value: 'office/ppt', label: 'PPT' },
+  { value: 'text/plain', label: '纯文本' },
+  { value: 'application/zip', label: 'ZIP 压缩包' },
+  { value: 'application/x-rar-compressed', label: 'RAR 压缩包' },
+]
+
+export const FORM_FILE_TYPE_MIME_MAP: Record<string, string[]> = {
+  'image/*': ['image/*'],
+  'video/*': ['video/*'],
+  'audio/*': ['audio/*'],
+  'application/pdf': ['application/pdf'],
+  'office/word': [
+    'application/msword',
+    'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  ],
+  'office/excel': [
+    'application/vnd.ms-excel',
+    'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  ],
+  'office/ppt': [
+    'application/vnd.ms-powerpoint',
+    'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+  ],
+  'text/plain': ['text/plain'],
+  'application/zip': ['application/zip'],
+  'application/x-rar-compressed': ['application/x-rar-compressed'],
+}
+
+export const FORM_FILE_TYPE_EXTENSION_MAP: Record<string, string[]> = {
+  'image/*': ['.jpg', '.jpeg', '.png', '.gif', '.webp', '.svg'],
+  'video/*': ['.mp4', '.mov', '.avi', '.webm'],
+  'audio/*': ['.mp3', '.wav', '.ogg', '.m4a'],
+  'application/pdf': ['.pdf'],
+  'office/word': ['.doc', '.docx'],
+  'office/excel': ['.xls', '.xlsx'],
+  'office/ppt': ['.ppt', '.pptx'],
+  'text/plain': ['.txt'],
+  'application/zip': ['.zip', '.7z'],
+  'application/x-rar-compressed': ['.rar'],
+}
+
+/** 旧版按 MIME 存储的数据，归一化为分组 key */
+const LEGACY_FILE_ACCEPT_TYPE_TO_GROUP: Record<string, string> = {
+  'application/msword': 'office/word',
+  'application/vnd.openxmlformats-officedocument.wordprocessingml.document':
+    'office/word',
+  'application/vnd.ms-excel': 'office/excel',
+  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet':
+    'office/excel',
+  'application/vnd.ms-powerpoint': 'office/ppt',
+  'application/vnd.openxmlformats-officedocument.presentationml.presentation':
+    'office/ppt',
+}
+
+export const FORM_FILE_EXTENSION_OPTIONS: FormFileAcceptOption[] = [
+  { value: '.jpg', label: '.jpg' },
+  { value: '.jpeg', label: '.jpeg' },
+  { value: '.png', label: '.png' },
+  { value: '.gif', label: '.gif' },
+  { value: '.webp', label: '.webp' },
+  { value: '.svg', label: '.svg' },
+  { value: '.mp4', label: '.mp4' },
+  { value: '.mov', label: '.mov' },
+  { value: '.avi', label: '.avi' },
+  { value: '.webm', label: '.webm' },
+  { value: '.mp3', label: '.mp3' },
+  { value: '.wav', label: '.wav' },
+  { value: '.ogg', label: '.ogg' },
+  { value: '.m4a', label: '.m4a' },
+  { value: '.pdf', label: '.pdf' },
+  { value: '.doc', label: '.doc' },
+  { value: '.docx', label: '.docx' },
+  { value: '.xls', label: '.xls' },
+  { value: '.xlsx', label: '.xlsx' },
+  { value: '.ppt', label: '.ppt' },
+  { value: '.pptx', label: '.pptx' },
+  { value: '.txt', label: '.txt' },
+  { value: '.zip', label: '.zip' },
+  { value: '.rar', label: '.rar' },
+  { value: '.7z', label: '.7z' },
+]
+
+const FILE_TYPE_LABELS = Object.fromEntries(
+  FORM_FILE_TYPE_OPTIONS.map((item) => [item.value, item.label]),
+)
+
+const FILE_EXTENSION_LABELS = Object.fromEntries(
+  FORM_FILE_EXTENSION_OPTIONS.map((item) => [item.value, item.label]),
+)
+
+const FILE_TYPE_VALUE_SET = new Set(FORM_FILE_TYPE_OPTIONS.map((item) => item.value))
+
+function resolveFileAcceptTypeValue(value: string): string | null {
+  const trimmed = value.trim()
+  if (!trimmed) return null
+  if (FILE_TYPE_VALUE_SET.has(trimmed)) return trimmed
+  return LEGACY_FILE_ACCEPT_TYPE_TO_GROUP[trimmed] ?? null
+}
+
+export function normalizeFileAcceptExtensions(extensions?: string[]): string[] {
+  if (!Array.isArray(extensions)) return []
+  return extensions
+    .map((item) => {
+      const trimmed = item.trim().toLowerCase()
+      if (!trimmed) return ''
+      return trimmed.startsWith('.') ? trimmed : `.${trimmed}`
+    })
+    .filter(Boolean)
+}
+
+export function normalizeFileAcceptTypes(types?: string[]): string[] {
+  if (!Array.isArray(types)) return []
+  const result: string[] = []
+  const seen = new Set<string>()
+  for (const item of types) {
+    const resolved = resolveFileAcceptTypeValue(item)
+    if (resolved && !seen.has(resolved)) {
+      seen.add(resolved)
+      result.push(resolved)
+    }
+  }
+  return result
+}
+
+export function expandFileAcceptTypesToMime(types?: string[]): string[] {
+  const normalizedTypes = normalizeFileAcceptTypes(types)
+  const mimes: string[] = []
+  for (const type of normalizedTypes) {
+    mimes.push(...(FORM_FILE_TYPE_MIME_MAP[type] ?? [type]))
+  }
+  return mimes
+}
+
+export function getFileExtensionOptionsForTypes(
+  types?: string[],
+): FormFileAcceptOption[] {
+  const normalizedTypes = normalizeFileAcceptTypes(types)
+  if (normalizedTypes.length === 0) return []
+
+  const extensionSet = new Set<string>()
+  for (const type of normalizedTypes) {
+    for (const extension of FORM_FILE_TYPE_EXTENSION_MAP[type] ?? []) {
+      extensionSet.add(extension)
+    }
+  }
+
+  return FORM_FILE_EXTENSION_OPTIONS.filter((item) => extensionSet.has(item.value))
+}
+
+export function filterFileAcceptExtensionsForTypes(
+  types?: string[],
+  extensions?: string[],
+): string[] {
+  const allowed = new Set(
+    getFileExtensionOptionsForTypes(types).map((item) => item.value),
+  )
+  return normalizeFileAcceptExtensions(extensions).filter((item) => allowed.has(item))
+}
+
+export function buildFileAcceptAttribute(
+  types?: string[],
+  extensions?: string[],
+): string | undefined {
+  const mimeTypes = expandFileAcceptTypesToMime(types)
+  const normalizedExtensions = filterFileAcceptExtensionsForTypes(types, extensions)
+  const parts = [...mimeTypes, ...normalizedExtensions]
+  return parts.length > 0 ? parts.join(',') : undefined
+}
+
+export function formatFileAcceptSummary(
+  types?: string[],
+  extensions?: string[],
+): string | null {
+  const normalizedTypes = normalizeFileAcceptTypes(types)
+  const normalizedExtensions = filterFileAcceptExtensionsForTypes(
+    normalizedTypes,
+    extensions,
+  )
+  const labels = [
+    ...normalizedTypes.map((item) => FILE_TYPE_LABELS[item] ?? item),
+    ...normalizedExtensions.map((item) => FILE_EXTENSION_LABELS[item] ?? item),
+  ]
+  if (labels.length === 0) return null
+  return labels.join('、')
+}

package/src/adapter/formFilePlaceholderIcon.ts

@@ -0,0 +1,33 @@
+import type { FormFilePlaceholderIcon } from '../types/index'
+
+export const FORM_FILE_PLACEHOLDER_ICON_VALUES: FormFilePlaceholderIcon[] = [
+  'video',
+  'audio',
+  'image',
+  'file',
+  'spreadsheet',
+  'document',
+]
+
+export const FORM_FILE_PLACEHOLDER_ICON_LABELS: Record<
+  FormFilePlaceholderIcon,
+  string
+> = {
+  video: '视频',
+  audio: '音频',
+  image: '图片',
+  file: '文件',
+  spreadsheet: '表格',
+  document: '文档',
+}
+
+const PLACEHOLDER_ICON_VALUE_SET = new Set<string>(FORM_FILE_PLACEHOLDER_ICON_VALUES)
+
+export function normalizeFilePlaceholderIcon(
+  value?: string,
+): FormFilePlaceholderIcon {
+  if (value && PLACEHOLDER_ICON_VALUE_SET.has(value)) {
+    return value as FormFilePlaceholderIcon
+  }
+  return 'file'
+}

package/src/adapter/formMedia.ts

@@ -0,0 +1,50 @@
+import type { FormBlock, FormMediaSize } from '../types/index'
+import { FORM_MEDIA_SIZES } from '../types/index'
+
+export function normalizeMediaSize(raw: unknown): FormMediaSize {
+  if (
+    typeof raw === 'string' &&
+    FORM_MEDIA_SIZES.includes(raw as FormMediaSize)
+  ) {
+    return raw as FormMediaSize
+  }
+  return 'medium'
+}
+
+export function normalizeMediaUrls(
+  raw: Pick<FormBlock, 'mediaUrls' | 'mediaUrl'>,
+  maxCount: number,
+): string[] {
+  const limit = Math.max(1, maxCount)
+  let urls: string[] = []
+
+  if (Array.isArray(raw.mediaUrls)) {
+    urls = raw.mediaUrls.map((item) => String(item).trim())
+  } else if (raw.mediaUrl?.trim()) {
+    urls = [raw.mediaUrl.trim()]
+  }
+
+  if (urls.length === 0) {
+    return ['']
+  }
+
+  return urls.slice(0, limit)
+}
+
+export function getMediaUrls(block: Pick<FormBlock, 'mediaUrls' | 'mediaUrl'>): string[] {
+  if (Array.isArray(block.mediaUrls)) {
+    return block.mediaUrls.map((item) => item.trim()).filter(Boolean)
+  }
+  if (block.mediaUrl?.trim()) {
+    return [block.mediaUrl.trim()]
+  }
+  return []
+}
+
+export function getMediaSizeClass(size: FormMediaSize | undefined): string {
+  return `form-media-size-${normalizeMediaSize(size)}`
+}
+
+export function buildMediaListClassName(size: FormMediaSize | undefined): string {
+  return `form-media-preview form-media-list ${getMediaSizeClass(size)}`
+}

package/src/adapter/formSchema.ts

@@ -0,0 +1,139 @@
+import type { FormBlock, FormBlockType, FormSchema } from '../types/index'
+import { isInputBlockType, isMediaBlockType } from '../types/index'
+import { generateId } from './id'
+import {
+  filterFileAcceptExtensionsForTypes,
+  normalizeFileAcceptTypes,
+} from './formFileAccept'
+import { normalizeFilePlaceholderIcon } from './formFilePlaceholderIcon'
+import {
+  normalizeMediaSize,
+  normalizeMediaUrls,
+} from './formMedia'
+
+const DEFAULT_MEDIA_URL_MAX = 10
+
+function normalizeFileUploadCount(raw: unknown, fallback = 1): number {
+  const num = typeof raw === 'number' ? raw : Number(raw)
+  if (!Number.isFinite(num)) return fallback
+  return Math.max(0, Math.floor(num))
+}
+
+function normalizeDefaultValue(
+  type: FormBlockType,
+  raw: FormBlock['defaultValue'],
+): FormBlock['defaultValue'] {
+  if (raw === undefined) return undefined
+  if (type === 'toggle') return raw === true
+  if (type === 'multiselect' || type === 'checkbox') {
+    if (Array.isArray(raw)) return raw.map(String)
+    if (typeof raw === 'string' && raw) return [raw]
+    return []
+  }
+  if (typeof raw === 'boolean') return raw ? 'true' : 'false'
+  if (Array.isArray(raw)) return raw.map(String)
+  return String(raw)
+}
+
+function normalizeBlock(raw: FormBlock): FormBlock {
+  const fileAcceptTypes = normalizeFileAcceptTypes(raw.fileAcceptTypes)
+  const type = raw.type
+  return {
+    id: raw.id?.trim() || generateId('block-'),
+    type,
+    name: raw.name?.trim() || undefined,
+    label: raw.label ?? '',
+    placeholder: raw.placeholder ?? '',
+    help: raw.help ?? '',
+    required: raw.required === true,
+    mediaUrls: isMediaBlockType(type)
+      ? normalizeMediaUrls(raw, DEFAULT_MEDIA_URL_MAX)
+      : undefined,
+    mediaSize: isMediaBlockType(type) ? normalizeMediaSize(raw.mediaSize) : undefined,
+    fileAcceptTypes,
+    fileAcceptExtensions: filterFileAcceptExtensionsForTypes(
+      fileAcceptTypes,
+      raw.fileAcceptExtensions,
+    ),
+    filePlaceholderIcon: normalizeFilePlaceholderIcon(raw.filePlaceholderIcon),
+    fileMinCount: type === 'file' ? normalizeFileUploadCount(raw.fileMinCount, 1) : undefined,
+    fileMaxCount: type === 'file' ? normalizeFileUploadCount(raw.fileMaxCount, 1) : undefined,
+    defaultValue: normalizeDefaultValue(type, raw.defaultValue),
+    options: Array.isArray(raw.options)
+      ? raw.options.map((opt, index) => ({
+          value: opt.value?.trim() || `option_${index + 1}`,
+          label: opt.label?.trim() || `选项 ${index + 1}`,
+        }))
+      : undefined,
+  }
+}
+
+export function syncFormDefinition(definition: FormSchema): FormSchema {
+  return {
+    title: definition.title ?? '',
+    description: definition.description ?? '',
+    blocks: definition.blocks,
+    jsonSchema: definition.jsonSchema ?? {},
+  }
+}
+
+export function normalizeFormDefinition(raw: FormSchema | undefined): FormSchema {
+  if (!raw || !Array.isArray(raw.blocks)) {
+    return syncFormDefinition({ title: '', description: '', blocks: [], jsonSchema: {} })
+  }
+  const blocks = raw.blocks.map(normalizeBlock)
+  return syncFormDefinition({
+    title: typeof raw.title === 'string' ? raw.title : '',
+    description: typeof raw.description === 'string' ? raw.description : '',
+    blocks,
+    jsonSchema: {},
+  })
+}
+
+export function createEmptyFormDefinition(): FormSchema {
+  return syncFormDefinition({ title: '', description: '', blocks: [], jsonSchema: {} })
+}
+
+export function createEmptyBlock(type: FormBlockType): FormBlock {
+  const block: FormBlock = {
+    id: generateId('block-'),
+    type,
+    label: type,
+  }
+
+  if (isInputBlockType(type)) {
+    block.label = ''
+    block.name = generateId('field_')
+    block.placeholder = ''
+    block.required = false
+  }
+
+  if (isMediaBlockType(type)) {
+    block.label = ''
+    block.placeholder = ''
+    block.help = ''
+    block.mediaUrls = ['']
+    block.mediaSize = 'medium'
+  }
+
+  if (isOptionsBlockType(type)) {
+    block.options = [
+      { value: 'option_1', label: '选项 1' },
+      { value: 'option_2', label: '选项 2' },
+    ]
+  }
+
+  if (type === 'file') {
+    block.fileAcceptTypes = []
+    block.fileAcceptExtensions = []
+    block.filePlaceholderIcon = 'file'
+    block.fileMinCount = 1
+    block.fileMaxCount = 1
+  }
+
+  return block
+}
+
+function isOptionsBlockType(type: FormBlockType): boolean {
+  return type === 'select' || type === 'multiselect' || type === 'radio' || type === 'checkbox'
+}

package/src/adapter/id.ts

@@ -0,0 +1,24 @@
+/** 生成 UUID v4；内网 HTTP 等非 Secure Context 下 randomUUID 不可用，回退 getRandomValues / Math.random。 */
+export function randomUuid(): string {
+  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+    return crypto.randomUUID()
+  }
+  if (typeof crypto !== 'undefined' && typeof crypto.getRandomValues === 'function') {
+    const bytes = new Uint8Array(16)
+    crypto.getRandomValues(bytes)
+    bytes[6] = (bytes[6]! & 0x0f) | 0x40
+    bytes[8] = (bytes[8]! & 0x3f) | 0x80
+    const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('')
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`
+  }
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+    const r = (Math.random() * 16) | 0
+    const v = c === 'x' ? r : (r & 0x3) | 0x8
+    return v.toString(16)
+  })
+}
+
+export function generateId(prefix: string): string {
+  const suffix = randomUuid().replace(/-/g, '').slice(0, 8)
+  return `${prefix}${suffix}`
+}

package/src/adapter/resolveSurface.ts

@@ -0,0 +1,66 @@
+import type { A2uiSurfaceDoc, FormBlock, FormDefinitionPayload, FormSchema } from '../types/index'
+import { a2uiToBlocks, blocksToA2ui, isA2uiSurfaceEmpty, type BlocksToA2uiOptions } from './a2uiAdapter'
+import { normalizeFormDefinition } from './formSchema'
+
+function isA2uiSurfaceDoc(raw: unknown): raw is A2uiSurfaceDoc {
+  return (
+    !!raw &&
+    typeof raw === 'object' &&
+    !Array.isArray(raw) &&
+    Array.isArray((raw as Record<string, unknown>).components)
+  )
+}
+
+export function resolveSurfaceFromFormDefinition(
+  raw: FormDefinitionPayload | FormSchema | undefined,
+  options?: BlocksToA2uiOptions,
+): A2uiSurfaceDoc | null {
+  if (!raw || typeof raw !== 'object') return null
+  const payload = raw as FormDefinitionPayload
+  const a2ui = isA2uiSurfaceDoc(payload.a2ui) ? payload.a2ui : undefined
+  if (a2ui && !isA2uiSurfaceEmpty(a2ui)) return a2ui
+
+  const blocks = Array.isArray(payload.blocks) ? payload.blocks : []
+  if (blocks.length === 0) return null
+
+  const normalized = normalizeFormDefinition({
+    title: typeof payload.title === 'string' ? payload.title : '',
+    description: typeof payload.description === 'string' ? payload.description : '',
+    blocks,
+    jsonSchema: {},
+  })
+  const doc = blocksToA2ui(normalized, options)
+  return isA2uiSurfaceEmpty(doc) ? null : doc
+}
+
+export function buildAskUserSurface(
+  formDef: Pick<FormSchema, 'title' | 'description'>,
+  matchedBlocks: FormBlock[],
+  options?: BlocksToA2uiOptions,
+): A2uiSurfaceDoc {
+  return blocksToA2ui(
+    {
+      title: formDef.title,
+      description: formDef.description,
+      blocks: matchedBlocks,
+    },
+    options,
+  )
+}
+
+export function mapFormDefinitionFromDto(raw: unknown): FormSchema | undefined {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    return undefined
+  }
+  const obj = raw as Record<string, unknown>
+  const hasBlocks = Array.isArray(obj.blocks) && obj.blocks.length > 0
+  if (!hasBlocks && isA2uiSurfaceDoc(obj.a2ui)) {
+    return a2uiToBlocks(obj.a2ui)
+  }
+  return normalizeFormDefinition({
+    title: typeof obj.title === 'string' ? obj.title : '',
+    description: typeof obj.description === 'string' ? obj.description : '',
+    blocks: Array.isArray(obj.blocks) ? (obj.blocks as FormSchema['blocks']) : [],
+    jsonSchema: {},
+  })
+}