@skopon-cool/form-sdk 0.1.0 → 0.1.3

package/dist/submit/buildCurlStatement.d.ts

@@ -1,2 +1,10 @@
 export declare function buildCurlStatement(payload: unknown, callbackUrl?: string | null): string;
+/** 构建含行注释的 JSON body：extra 段标注「额外字段（未在卡片展示）」 */
+export declare function buildAskUserCurlBodyJson(cardValues: Record<string, unknown>, extraValues: Record<string, unknown>): string;
+export interface BuildAskUserCurlStatementOptions {
+    cardValues: Record<string, unknown>;
+    extraValues?: Record<string, unknown>;
+    callbackUrl?: string | null;
+}
+export declare function buildAskUserCurlStatement({ cardValues, extraValues, callbackUrl, }: BuildAskUserCurlStatementOptions): string;
 //# sourceMappingURL=buildCurlStatement.d.ts.map

package/dist/submit/buildCurlStatement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"buildCurlStatement.d.ts","sourceRoot":"","sources":["../../src/submit/buildCurlStatement.ts"],"names":[],"mappings":"AAIA,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAQxF"}
+{"version":3,"file":"buildCurlStatement.d.ts","sourceRoot":"","sources":["../../src/submit/buildCurlStatement.ts"],"names":[],"mappings":"AAIA,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAQxF;AAMD,gDAAgD;AAChD,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnC,MAAM,CAmBR;AAED,MAAM,WAAW,gCAAgC;IAC/C,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACrC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAC5B;AAED,wBAAgB,yBAAyB,CAAC,EACxC,UAAU,EACV,WAAgB,EAChB,WAAW,GACZ,EAAE,gCAAgC,GAAG,MAAM,CAQ3C"}

package/dist/submit/intersectPayloadBlocksWithForm.d.ts

@@ -0,0 +1,26 @@
+import type { FormBlock, FormSchema } 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;
+}
+/** 解析 ask_user payload 为 blocksJson 形（title / description / blocks） */
+export declare function parsePayloadBlocksJson(payload: unknown): PayloadBlocksDefinition | null;
+/**
+ * payload.blocks 与 vt_forms 按 input 块 name 取交集用于渲染；
+ * payload 中 form 不存在的块归入 extraBlocks（不渲染，提交时写入 curl）。
+ */
+export declare function intersectPayloadBlocksWithForm(payloadDef: PayloadBlocksDefinition, formDefinition: FormSchema | undefined): PayloadBlocksIntersection;
+/** 从 extraBlocks 提取提交值（优先 defaultValue） */
+export declare function extractExtraBlockValues(extraBlocks: FormBlock[]): Record<string, unknown>;
+/** payload 是否含至少一个具 name 的 input 块（可用于卡片 fallback） */
+export declare function payloadHasInputBlocks(payloadDef: PayloadBlocksDefinition): boolean;
+/** 交集为空时 fallback：payload 中可上屏的 blocks（layout + input） */
+export declare function getPayloadRenderableBlocks(payloadDef: PayloadBlocksDefinition): FormBlock[];
+/** payload 中所有 input 块 field name（fallback 提交用） */
+export declare function getPayloadInputFieldNames(payloadDef: PayloadBlocksDefinition): string[];
+//# sourceMappingURL=intersectPayloadBlocksWithForm.d.ts.map

package/dist/submit/intersectPayloadBlocksWithForm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intersectPayloadBlocksWithForm.d.ts","sourceRoot":"","sources":["../../src/submit/intersectPayloadBlocksWithForm.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAG3D,MAAM,MAAM,uBAAuB,GAAG,IAAI,CAAC,UAAU,EAAE,OAAO,GAAG,aAAa,GAAG,QAAQ,CAAC,CAAA;AAE1F,MAAM,WAAW,yBAAyB;IACxC,aAAa,EAAE,SAAS,EAAE,CAAA;IAC1B,WAAW,EAAE,SAAS,EAAE,CAAA;IACxB,0DAA0D;IAC1D,YAAY,EAAE,SAAS,EAAE,CAAA;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;CACpB;AAqDD,uEAAuE;AACvE,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,uBAAuB,GAAG,IAAI,CAUvF;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAC5C,UAAU,EAAE,uBAAuB,EACnC,cAAc,EAAE,UAAU,GAAG,SAAS,GACrC,yBAAyB,CAqC3B;AAmBD,2CAA2C;AAC3C,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,SAAS,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASzF;AAED,sDAAsD;AACtD,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,uBAAuB,GAAG,OAAO,CAIlF;AAED,0DAA0D;AAC1D,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,uBAAuB,GAAG,SAAS,EAAE,CAK3F;AAED,mDAAmD;AACnD,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,uBAAuB,GAAG,MAAM,EAAE,CAIvF"}

package/dist/submit/submitFormJson.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"submitFormJson.d.ts","sourceRoot":"","sources":["../../src/submit/submitFormJson.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACjC;AAED,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,OAAO,CAAA;IACX,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,OAAO,CAAA;CACf;AAED,wBAAsB,cAAc,CAClC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,oBAAoB,CAAC,CA8B/B;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAErE"}
+{"version":3,"file":"submitFormJson.d.ts","sourceRoot":"","sources":["../../src/submit/submitFormJson.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACjC;AAED,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,OAAO,CAAA;IACX,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,OAAO,CAAA;CACf;AAED,wBAAsB,cAAc,CAClC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,oBAAoB,CAAC,CA8B/B;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAqBrE"}

package/package.json

@@ -3,9 +3,13 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "Skopon form rendering SDK (A2UI + form_definition) with submit helpers",
   "type": "module",
+  "sideEffects": [
+    "*.css",
+    "dist/form-sdk.css"
+  ],
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -25,29 +29,36 @@
     "test": "vitest run",
     "test:watch": "vitest"
   },
+  "dependencies": {
+    "dayjs": "^1.11.13",
+    "zod": "^3.24.0"
+  },
   "peerDependencies": {
-    "@ant-design/icons": "^6.0.0",
     "@a2ui/react": "^0.10.1",
     "@a2ui/web_core": "^0.10.2",
+    "@ant-design/icons": "^6.0.0",
     "antd": "^6.4.3",
-    "dayjs": "^1.11.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@ant-design/icons": "^6.2.3",
     "@a2ui/react": "^0.10.1",
     "@a2ui/web_core": "^0.10.2",
+    "@ant-design/icons": "^6.2.3",
+    "@testing-library/react": "^16.3.2",
     "@types/react": "^19.1.2",
     "@types/react-dom": "^19.1.2",
     "@vitejs/plugin-react": "^4.5.2",
     "antd": "^6.4.3",
     "dayjs": "^1.11.13",
+    "happy-dom": "^17.6.3",
+    "jsdom": "^29.1.1",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "typescript": "~5.8.3",
     "vite": "^6.3.5",
     "vite-plugin-dts": "^4.5.4",
-    "vitest": "^3.2.4"
+    "vitest": "^3.2.4",
+    "zod": "^3.24.0"
   }
 }

package/src/adapter/a2uiAdapter.test.ts

@@ -1,3 +1,6 @@
+/**
+ * @vitest-environment node
+ */
 import { describe, it, expect } from 'vitest'
 import type { FormSchema } from '../types/index'
 import { a2uiToBlocks, blocksToA2ui, isA2uiSurfaceEmpty, surfaceDocToMessages } from './a2uiAdapter'
@@ -120,6 +123,94 @@ describe('a2uiAdapter blocks <-> surface', () => {
     expect(back.blocks.find((b) => b.name === 'tags')?.type).toBe('multiselect')
   })
 
+  it('blocksToA2ui stores single-select and radio defaults as strings in dataModel', () => {
+    const doc = blocksToA2ui(
+      {
+        title: '',
+        description: '',
+        blocks: [
+          {
+            id: 'b-city',
+            type: 'select',
+            name: 'city',
+            label: '城市',
+            defaultValue: 'bj',
+            options: [{ label: '北京', value: 'bj' }],
+          },
+          {
+            id: 'b-gender',
+            type: 'radio',
+            name: 'gender',
+            label: '性别',
+            defaultValue: 'm',
+            options: [
+              { label: '男', value: 'm' },
+              { label: '女', value: 'f' },
+            ],
+          },
+          {
+            id: 'b-tags',
+            type: 'multiselect',
+            name: 'tags',
+            label: '标签',
+            defaultValue: ['a', 'b'],
+            options: [
+              { label: 'A', value: 'a' },
+              { label: 'B', value: 'b' },
+            ],
+          },
+        ],
+      },
+      { includeHeader: false },
+    )
+    expect(doc.dataModel?.city).toBe('bj')
+    expect(doc.dataModel?.gender).toBe('m')
+    expect(doc.dataModel?.tags).toEqual(['a', 'b'])
+  })
+
+  it('blocksToA2ui stores toggle string default "true" as true in dataModel', () => {
+    const doc = blocksToA2ui(
+      {
+        title: '',
+        description: '',
+        blocks: [
+          {
+            id: 'b-sub',
+            type: 'toggle',
+            name: 'subscribe',
+            label: '订阅',
+            defaultValue: 'true',
+          },
+        ],
+      },
+      { includeHeader: false },
+    )
+    expect(doc.dataModel?.subscribe).toBe(true)
+  })
+
+  it('round-trips textarea placeholder through blocksToA2ui', () => {
+    const doc = blocksToA2ui(
+      {
+        title: '',
+        description: '',
+        blocks: [
+          {
+            id: 'b-bio',
+            type: 'textarea',
+            name: 'bio',
+            label: '简介',
+            placeholder: '请填写简介',
+          },
+        ],
+      },
+      { includeHeader: false },
+    )
+    const bioNode = doc.components.find((c) => c.id === 'b-bio')
+    expect(bioNode?.placeholder).toBe('请填写简介')
+    const back = a2uiToBlocks(doc)
+    expect(back.blocks.find((b) => b.name === 'bio')?.placeholder).toBe('请填写简介')
+  })
+
   it('surfaceDocToMessages emits createSurface + updateComponents + updateDataModel', () => {
     const doc = blocksToA2ui(makeDefinition())
     const messages = surfaceDocToMessages(doc, { surfaceId: 's1', catalogId: 'c1' })

package/src/adapter/a2uiAdapter.ts

@@ -8,6 +8,7 @@ import type {
   FormSchema,
 } from '../types/index'
 import { generateId } from './id'
+import { coerceToggleValue } from './formSchema'
 import { getMediaUrls, normalizeMediaSize } from './formMedia'
 import { syncFormDefinition } from './formSchema'
 
@@ -95,14 +96,17 @@ function readMediaBlock(
 function defaultValueForBlock(block: FormBlock): unknown {
   switch (block.type) {
     case 'toggle':
-      return typeof block.defaultValue === 'boolean' ? block.defaultValue : false
+      return coerceToggleValue(block.defaultValue)
     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 []
+    case 'select':
+    case 'radio':
+      if (Array.isArray(block.defaultValue)) return block.defaultValue[0] ?? ''
+      if (typeof block.defaultValue === 'string') return block.defaultValue
+      return ''
     default:
       if (typeof block.defaultValue === 'string') return block.defaultValue
       return ''
@@ -136,7 +140,14 @@ function blockToComponent(block: FormBlock): {
     case 'text':
     case 'tel':
     case 'url':
-      return withData({ id, component: 'TextField', label, variant: 'shortText', value: { path } })
+      return withData({
+        id,
+        component: 'TextField',
+        label,
+        variant: 'shortText',
+        ...(block.placeholder ? { placeholder: block.placeholder } : {}),
+        value: { path },
+      })
     case 'email':
       return withData({
         id,
@@ -144,12 +155,27 @@ function blockToComponent(block: FormBlock): {
         label,
         variant: 'shortText',
         validationRegexp: EMAIL_REGEXP,
+        ...(block.placeholder ? { placeholder: block.placeholder } : {}),
         value: { path },
       })
     case 'textarea':
-      return withData({ id, component: 'TextField', label, variant: 'longText', value: { path } })
+      return withData({
+        id,
+        component: 'TextField',
+        label,
+        variant: 'longText',
+        ...(block.placeholder ? { placeholder: block.placeholder } : {}),
+        value: { path },
+      })
     case 'number':
-      return withData({ id, component: 'TextField', label, variant: 'number', value: { path } })
+      return withData({
+        id,
+        component: 'TextField',
+        label,
+        variant: 'number',
+        ...(block.placeholder ? { placeholder: block.placeholder } : {}),
+        value: { path },
+      })
 
     case 'select':
       return withData({
@@ -337,7 +363,10 @@ function componentToBlock(node: A2uiComponentNode): FormBlock | null {
       if (variant === 'longText') type = 'textarea'
       else if (variant === 'number') type = 'number'
       else if (asLiteral(node.validationRegexp) === EMAIL_REGEXP) type = 'email'
-      return { ...base(type), name }
+      const block: FormBlock = { ...base(type), name }
+      const placeholder = asLiteral(node.placeholder)
+      if (placeholder) block.placeholder = placeholder
+      return block
     }
     case 'CheckBox':
       return { ...base('toggle'), name }

package/src/adapter/formFileAccept.test.ts

@@ -0,0 +1,53 @@
+/**
+ * @vitest-environment node
+ */
+import { describe, it, expect } from 'vitest'
+import {
+  buildFileAcceptAttribute,
+  filterFileAcceptExtensionsForTypes,
+  formatFileAcceptSummary,
+} from './formFileAccept'
+import { normalizeFormDefinition } from './formSchema'
+
+describe('filterFileAcceptExtensionsForTypes without types', () => {
+  it('keeps whitelisted extensions when fileAcceptTypes is empty', () => {
+    expect(filterFileAcceptExtensionsForTypes(undefined, ['.pdf', '.docx'])).toEqual([
+      '.pdf',
+      '.docx',
+    ])
+  })
+
+  it('drops unknown extensions when fileAcceptTypes is empty', () => {
+    expect(filterFileAcceptExtensionsForTypes([], ['.pdf', '.exe'])).toEqual(['.pdf'])
+  })
+})
+
+describe('buildFileAcceptAttribute without types', () => {
+  it('preserves extension-only accept attribute', () => {
+    expect(buildFileAcceptAttribute(undefined, ['.pdf', '.docx'])).toBe('.pdf,.docx')
+  })
+
+  it('formatFileAcceptSummary shows extension labels without types', () => {
+    expect(formatFileAcceptSummary(undefined, ['.pdf'])).toBe('.pdf')
+  })
+})
+
+describe('normalizeFormDefinition file extensions without types', () => {
+  it('retains whitelisted extensions on file blocks', () => {
+    const def = normalizeFormDefinition({
+      title: '',
+      description: '',
+      blocks: [
+        {
+          id: 'b1',
+          type: 'file',
+          name: 'attach',
+          label: '附件',
+          fileAcceptExtensions: ['.pdf', '.docx'],
+        },
+      ],
+      jsonSchema: {},
+    })
+    expect(def.blocks[0]?.fileAcceptExtensions).toEqual(['.pdf', '.docx'])
+  })
+})

package/src/adapter/formFileAccept.ts

@@ -103,6 +103,10 @@ const FILE_EXTENSION_LABELS = Object.fromEntries(
 
 const FILE_TYPE_VALUE_SET = new Set(FORM_FILE_TYPE_OPTIONS.map((item) => item.value))
 
+const KNOWN_FILE_EXTENSION_SET = new Set(
+  FORM_FILE_EXTENSION_OPTIONS.map((item) => item.value),
+)
+
 function resolveFileAcceptTypeValue(value: string): string | null {
   const trimmed = value.trim()
   if (!trimmed) return null
@@ -164,10 +168,15 @@ export function filterFileAcceptExtensionsForTypes(
   types?: string[],
   extensions?: string[],
 ): string[] {
+  const normalizedExtensions = normalizeFileAcceptExtensions(extensions)
+  const normalizedTypes = normalizeFileAcceptTypes(types)
+  if (normalizedTypes.length === 0) {
+    return normalizedExtensions.filter((item) => KNOWN_FILE_EXTENSION_SET.has(item))
+  }
   const allowed = new Set(
-    getFileExtensionOptionsForTypes(types).map((item) => item.value),
+    getFileExtensionOptionsForTypes(normalizedTypes).map((item) => item.value),
   )
-  return normalizeFileAcceptExtensions(extensions).filter((item) => allowed.has(item))
+  return normalizedExtensions.filter((item) => allowed.has(item))
 }
 
 export function buildFileAcceptAttribute(

package/src/adapter/formSchema.test.ts

@@ -0,0 +1,35 @@
+/**
+ * @vitest-environment node
+ */
+import { describe, it, expect } from 'vitest'
+import { coerceToggleValue, normalizeFormDefinition } from './formSchema'
+
+describe('coerceToggleValue', () => {
+  it('accepts boolean and string true', () => {
+    expect(coerceToggleValue(true)).toBe(true)
+    expect(coerceToggleValue('true')).toBe(true)
+    expect(coerceToggleValue(false)).toBe(false)
+    expect(coerceToggleValue('false')).toBe(false)
+    expect(coerceToggleValue(undefined)).toBe(false)
+  })
+})
+
+describe('normalizeFormDefinition toggle default', () => {
+  it('normalizes string "true" default to boolean true', () => {
+    const def = normalizeFormDefinition({
+      title: '',
+      description: '',
+      blocks: [
+        {
+          id: 'b1',
+          type: 'toggle',
+          name: 'subscribe',
+          label: '订阅',
+          defaultValue: 'true',
+        },
+      ],
+      jsonSchema: {},
+    })
+    expect(def.blocks[0]?.defaultValue).toBe(true)
+  })
+})

package/src/adapter/formSchema.ts

@@ -13,6 +13,10 @@ import {
 
 const DEFAULT_MEDIA_URL_MAX = 10
 
+export function coerceToggleValue(raw: unknown): boolean {
+  return raw === true || raw === 'true'
+}
+
 function normalizeFileUploadCount(raw: unknown, fallback = 1): number {
   const num = typeof raw === 'number' ? raw : Number(raw)
   if (!Number.isFinite(num)) return fallback
@@ -24,7 +28,7 @@ function normalizeDefaultValue(
   raw: FormBlock['defaultValue'],
 ): FormBlock['defaultValue'] {
   if (raw === undefined) return undefined
-  if (type === 'toggle') return raw === true
+  if (type === 'toggle') return coerceToggleValue(raw)
   if (type === 'multiselect' || type === 'checkbox') {
     if (Array.isArray(raw)) return raw.map(String)
     if (typeof raw === 'string' && raw) return [raw]

package/src/catalog/a2uiCustomCatalog.tsx

@@ -1,13 +1,26 @@
 import { z } from 'zod'
+import type { ReactNode } from 'react'
 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 {
+  Checkbox,
+  DatePicker,
+  Input,
+  InputNumber,
+  Radio,
+  Select,
+  Switch,
+  TimePicker,
+  Typography,
+  Upload,
+} from 'antd'
 import dayjs, { type Dayjs } from 'dayjs'
 import type { FormFilePlaceholderIcon, FormMediaSize } from '../types/index'
+import { coerceToggleValue } from '../adapter/formSchema'
 import {
   buildFileAcceptAttribute,
   formatFileAcceptSummary,
@@ -18,6 +31,7 @@ import { useA2uiPreviewMode } from './a2uiPreviewContext'
 import {
   asOptionalString,
   asStringArray,
+  readBoundFieldValue,
   useSkoponBoundField,
 } from './useSkoponBoundField'
 
@@ -37,8 +51,12 @@ const SKOPON_COMPONENT_NAMES = new Set([
   'CheckBox',
   'DateTimeInput',
   'FileUpload',
+  'TextField',
+  'Text',
 ])
 
+const NON_MARKDOWN_TEXT_VARIANTS = new Set(['h1', 'h2', 'h3', 'h4', 'h5', 'caption'])
+
 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}`)
@@ -343,7 +361,7 @@ function ToggleSwitchPreview({ context }: { context: ComponentContext }) {
       <Switch
         disabled={!interactive}
         className="form-block-preview-control"
-        checked={value === true}
+        checked={coerceToggleValue(value)}
         onChange={(checked) => setValue(checked)}
       />
     </div>
@@ -479,14 +497,18 @@ function FileUploadPreview({ context }: { context: ComponentContext }) {
     )
       ? (props.filePlaceholderIcon as FormFilePlaceholderIcon)
       : 'document'
+  const minCount = typeof props.minCount === 'number' ? Math.max(0, props.minCount) : 0
   const maxCount = typeof props.maxCount === 'number' ? props.maxCount : 1
+  const hasMaxLimit = maxCount > 0
   const selectedNames = asStringArray(value)
+  const atMaxLimit = hasMaxLimit && selectedNames.length >= maxCount
+  const belowMinCount = selectedNames.length < minCount
 
   return (
     <div className="form-block-preview">
       {label ? <div className="form-block-preview-label">{label}</div> : null}
       <Upload.Dragger
-        disabled={!interactive}
+        disabled={!interactive || atMaxLimit}
         accept={buildFileAcceptAttribute(fileAcceptTypes, fileAcceptExtensions)}
         className="form-file-upload-preview"
         showUploadList={interactive && selectedNames.length > 0}
@@ -501,12 +523,24 @@ function FileUploadPreview({ context }: { context: ComponentContext }) {
         }
         beforeUpload={(file) => {
           if (!interactive) return Upload.LIST_IGNORE
-          const next = [...selectedNames, file.name].slice(0, Math.max(1, maxCount))
+          const currentNames = asStringArray(readBoundFieldValue(context))
+          if (hasMaxLimit && currentNames.length >= maxCount) return Upload.LIST_IGNORE
+          const next = hasMaxLimit
+            ? [...currentNames, file.name].slice(0, maxCount)
+            : [...currentNames, file.name]
           setValue(next)
           return false
         }}
         onRemove={(file) => {
-          setValue(selectedNames.filter((name) => name !== file.name))
+          const currentNames = asStringArray(readBoundFieldValue(context))
+          const indexMatch = /^(\d+)-/.exec(file.uid ?? '')
+          const index = indexMatch ? Number(indexMatch[1]) : -1
+          const next =
+            index >= 0 && index < currentNames.length
+              ? currentNames.filter((_, i) => i !== index)
+              : currentNames.filter((name) => name !== file.name)
+          if (next.length < minCount) return false
+          setValue(next)
         }}
       >
         <p className="form-file-upload-preview-icon">
@@ -516,6 +550,9 @@ function FileUploadPreview({ context }: { context: ComponentContext }) {
       </Upload.Dragger>
       <Typography.Text type="secondary" className="form-block-preview-help">
         允许：{acceptSummary ?? '全部类型'}
+        {minCount > 0 ? `；至少 ${minCount} 个文件` : ''}
+        {hasMaxLimit ? `；最多 ${maxCount} 个文件` : ''}
+        {belowMinCount && interactive ? `（当前 ${selectedNames.length} 个，未达下限）` : ''}
       </Typography.Text>
     </div>
   )
@@ -526,6 +563,116 @@ const FileUploadImpl = createBinderlessComponentImplementation(
   FileUploadPreview,
 )
 
+function TextFieldPreview({ 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 variant = readString(props.variant) || 'shortText'
+  const stringValue = asOptionalString(value) ?? ''
+  const disabled = !interactive
+
+  const controlClassName = 'form-block-preview-control'
+
+  let control: ReactNode
+  if (variant === 'longText') {
+    control = (
+      <Input.TextArea
+        disabled={disabled}
+        className={controlClassName}
+        placeholder={placeholder || '长文本回答...'}
+        autoSize={{ minRows: 2, maxRows: 6 }}
+        value={stringValue}
+        onChange={(e) => setValue(e.target.value)}
+      />
+    )
+  } else if (variant === 'number') {
+    const numericValue =
+      stringValue && Number.isFinite(Number(stringValue)) ? Number(stringValue) : undefined
+    control = (
+      <InputNumber
+        disabled={disabled}
+        className={controlClassName}
+        style={{ width: '100%' }}
+        placeholder={placeholder || '数字'}
+        value={numericValue}
+        onChange={(next) => setValue(next == null ? '' : String(next))}
+      />
+    )
+  } else if (variant === 'obscured') {
+    control = (
+      <Input.Password
+        disabled={disabled}
+        className={controlClassName}
+        placeholder={placeholder}
+        value={stringValue}
+        onChange={(e) => setValue(e.target.value)}
+      />
+    )
+  } else {
+    control = (
+      <Input
+        disabled={disabled}
+        className={controlClassName}
+        placeholder={placeholder}
+        value={stringValue}
+        onChange={(e) => setValue(e.target.value)}
+      />
+    )
+  }
+
+  return (
+    <div className="form-block-preview">
+      {label ? <div className="form-block-preview-label">{label}</div> : null}
+      {control}
+    </div>
+  )
+}
+
+const TextFieldImpl = createBinderlessComponentImplementation(
+  {
+    name: 'TextField',
+    schema: z
+      .object({
+        label: z.any().optional(),
+        variant: z.any().optional(),
+        placeholder: z.any().optional(),
+        validationRegexp: z.any().optional(),
+        value: z.any().optional(),
+      })
+      .passthrough(),
+  },
+  TextFieldPreview,
+)
+
+function TextPreview({ context }: { context: ComponentContext }) {
+  const props = context.componentModel.properties as Record<string, unknown>
+  const text = readString(props.text)
+  const variant = readString(props.variant) || 'body'
+
+  if (NON_MARKDOWN_TEXT_VARIANTS.has(variant)) {
+    if (variant === 'caption') {
+      return (
+        <Typography.Text type="secondary" className="form-block-preview-paragraph">
+          <em>{text}</em>
+        </Typography.Text>
+      )
+    }
+    const Tag = variant as 'h1' | 'h2' | 'h3' | 'h4' | 'h5'
+    return <Tag className="form-block-preview-heading">{text}</Tag>
+  }
+
+  return (
+    <Typography.Paragraph className="form-block-preview-paragraph">{text}</Typography.Paragraph>
+  )
+}
+
+const TextImpl = createBinderlessComponentImplementation(
+  { name: 'Text', schema: getBasicSchema('Text') },
+  TextPreview,
+)
+
 /** 构建合并后的 skopon catalog（预览每次重建，避免 HMR 缓存旧组件）。 */
 export function buildSkoponCatalog(): Catalog<ReactComponentImplementation> {
   const baseComponents = [...basicCatalog.components.values()].filter(
@@ -542,6 +689,8 @@ export function buildSkoponCatalog(): Catalog<ReactComponentImplementation> {
     CheckBoxImpl,
     DateTimeInputImpl,
     FileUploadImpl,
+    TextFieldImpl,
+    TextImpl,
   ]
   const functions = [...basicCatalog.functions.values()]
   return new Catalog(SKOPON_CATALOG_ID, components, functions, basicCatalog.themeSchema)