@skopon-cool/form-sdk 0.1.1 → 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,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Skopon form rendering SDK (A2UI + form_definition) with submit helpers",
   "type": "module",
   "sideEffects": [
@@ -29,31 +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",
-    "jsdom": "^29.1.1",
-    "@testing-library/react": "^16.3.2"
+    "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,71 @@ 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(
       {

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 ''

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

@@ -20,6 +20,7 @@ import {
 } from 'antd'
 import dayjs, { type Dayjs } from 'dayjs'
 import type { FormFilePlaceholderIcon, FormMediaSize } from '../types/index'
+import { coerceToggleValue } from '../adapter/formSchema'
 import {
   buildFileAcceptAttribute,
   formatFileAcceptSummary,
@@ -30,6 +31,7 @@ import { useA2uiPreviewMode } from './a2uiPreviewContext'
 import {
   asOptionalString,
   asStringArray,
+  readBoundFieldValue,
   useSkoponBoundField,
 } from './useSkoponBoundField'
 
@@ -359,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>
@@ -495,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}
@@ -517,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">
@@ -532,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>
   )
@@ -567,13 +588,15 @@ function TextFieldPreview({ context }: { context: ComponentContext }) {
       />
     )
   } 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={stringValue ? Number(stringValue) : undefined}
+        value={numericValue}
         onChange={(next) => setValue(next == null ? '' : String(next))}
       />
     )

package/src/catalog/textFieldPreview.test.tsx

@@ -1,4 +1,4 @@
-// @vitest-environment jsdom
+// @vitest-environment happy-dom
 import { describe, it, expect, vi, afterEach, beforeAll } from 'vitest'
 
 vi.mock('@a2ui/web_core/v0_9/basic_catalog', async (importOriginal) => {

package/src/catalog/useSkoponBoundField.test.ts

@@ -0,0 +1,62 @@
+/**
+ * @vitest-environment node
+ */
+import { describe, it, expect } from 'vitest'
+import type { ComponentContext } from '@a2ui/web_core/v0_9'
+import { asStringArray, readBoundFieldValue } from './useSkoponBoundField'
+
+function createMockContext(initial: unknown = []): {
+  context: ComponentContext
+  getStore: () => unknown
+} {
+  const store = new Map<string, unknown>([['/files', initial]])
+  const binding = { path: '/files' }
+  const context = {
+    componentModel: {
+      properties: { value: binding },
+    },
+    dataContext: {
+      resolveDynamicValue: (b: typeof binding) => store.get(b.path),
+      set: (path: string, value: unknown) => {
+        store.set(path, value)
+      },
+      subscribeDynamicValue: () => ({ unsubscribe: () => {} }),
+    },
+  } as unknown as ComponentContext
+  return {
+    context,
+    getStore: () => store.get('/files'),
+  }
+}
+
+describe('readBoundFieldValue', () => {
+  it('reads current bound value from dataContext', () => {
+    const { context } = createMockContext(['a.pdf'])
+    expect(asStringArray(readBoundFieldValue(context))).toEqual(['a.pdf'])
+  })
+
+  it('supports sequential appends without stale reads', () => {
+    const { context, getStore } = createMockContext([])
+    const append = (fileName: string) => {
+      const current = asStringArray(readBoundFieldValue(context))
+      context.dataContext.set('/files', [...current, fileName])
+    }
+    append('first.pdf')
+    append('second.pdf')
+    expect(getStore()).toEqual(['first.pdf', 'second.pdf'])
+  })
+})
+
+describe('file upload remove by uid index', () => {
+  it('removes only the file at the uid index when names duplicate', () => {
+    const currentNames = ['dup.txt', 'dup.txt', 'other.txt']
+    const uid = '1-dup.txt'
+    const indexMatch = /^(\d+)-/.exec(uid)
+    const index = indexMatch ? Number(indexMatch[1]) : -1
+    const next =
+      index >= 0 && index < currentNames.length
+        ? currentNames.filter((_, i) => i !== index)
+        : currentNames.filter((name) => name !== 'dup.txt')
+    expect(next).toEqual(['dup.txt', 'other.txt'])
+  })
+})

package/src/catalog/useSkoponBoundField.ts

@@ -11,6 +11,15 @@ function bindingPath(value: unknown): string | null {
   return null
 }
 
+/** 从 A2UI 组件 context 读取当前绑定字段值（不订阅更新，适合事件回调内读最新值）。 */
+export function readBoundFieldValue(context: ComponentContext, field = 'value'): unknown {
+  const props = context.componentModel.properties as Record<string, unknown>
+  const binding = props[field] as DynamicBinding | undefined
+  const path = bindingPath(binding)
+  if (!path || binding === undefined) return undefined
+  return context.dataContext.resolveDynamicValue(binding)
+}
+
 /** 将 skopon 预览控件绑定到 A2UI surface dataModel（与 basicCatalog binder 行为一致）。 */
 export function useSkoponBoundField(context: ComponentContext, field = 'value') {
   const props = context.componentModel.properties as Record<string, unknown>
@@ -31,7 +40,7 @@ export function useSkoponBoundField(context: ComponentContext, field = 'value')
     return context.dataContext.resolveDynamicValue(binding)
   }, [context, binding, path])
 
-  const value = path ? useSyncExternalStore(subscribe, getSnapshot, getSnapshot) : undefined
+  const value = useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
 
   const setValue = useCallback(
     (next: unknown) => {

package/src/client/formClient.test.ts

@@ -0,0 +1,83 @@
+/**
+ * @vitest-environment node
+ */
+import { describe, it, expect, vi } from 'vitest'
+import { createFormClient } from './formClient'
+
+function mockResponse(
+  init: Partial<Response> & { json?: () => Promise<unknown>; text?: () => Promise<string> },
+): Response {
+  return {
+    ok: init.ok ?? true,
+    status: init.status ?? 200,
+    headers: { get: () => 'application/json' },
+    json: init.json ?? (async () => ({})),
+    text: init.text ?? (async () => ''),
+  } as Response
+}
+
+describe('createFormClient', () => {
+  it('fetchDetail returns mapped form definition on success', async () => {
+    const fetchMock = vi.fn(async () =>
+      mockResponse({
+        json: async () => ({
+          success: true,
+          data: {
+            form_id: 1,
+            form_unique_id: 'form-abc',
+            name: 'Test',
+            disabled: 0,
+            form_definition: {
+              title: 'T',
+              blocks: [{ id: 'b1', type: 'text', name: 'x', label: 'X' }],
+            },
+          },
+        }),
+      }),
+    ) as unknown as typeof fetch
+
+    const client = createFormClient({ fetch: fetchMock, baseUrl: '/api/v1', detailPath: '/dev/form/detail' })
+    const result = await client.fetchDetail({ formUniqueId: 'form-abc' })
+    expect(result.formUniqueId).toBe('form-abc')
+    expect(result.formId).toBe(1)
+    expect(result.disabled).toBe(false)
+    expect(result.formDefinition?.blocks).toHaveLength(1)
+  })
+
+  it('throws on non-JSON response', async () => {
+    const fetchMock = vi.fn(async () =>
+      mockResponse({
+        json: async () => {
+          throw new SyntaxError('Unexpected token')
+        },
+      }),
+    ) as unknown as typeof fetch
+
+    const client = createFormClient({ fetch: fetchMock })
+    await expect(client.fetchDetail({ formUniqueId: 'x' })).rejects.toThrow('响应非 JSON')
+  })
+
+  it('throws when envelope data is missing', async () => {
+    const fetchMock = vi.fn(async () =>
+      mockResponse({
+        json: async () => ({ success: true, data: null }),
+      }),
+    ) as unknown as typeof fetch
+
+    const client = createFormClient({ fetch: fetchMock })
+    await expect(client.fetchDetail({ formUniqueId: 'x' })).rejects.toThrow('响应缺少 data')
+  })
+
+  it('throws when API returns success false', async () => {
+    const fetchMock = vi.fn(async () =>
+      mockResponse({
+        ok: false,
+        status: 404,
+        json: async () => ({ success: false, message: '表单不存在' }),
+      }),
+    ) as unknown as typeof fetch
+
+    const client = createFormClient({ fetch: fetchMock })
+    await expect(client.fetchDetail({ formUniqueId: 'missing' })).rejects.toThrow('表单不存在')
+  })
+})

package/src/client/formClient.ts

@@ -27,11 +27,19 @@ interface ApiEnvelope<T> {
 }
 
 async function parseEnvelope<T>(response: Response): Promise<T> {
-  const json = (await response.json()) as ApiEnvelope<T>
+  let json: ApiEnvelope<T>
+  try {
+    json = (await response.json()) as ApiEnvelope<T>
+  } catch {
+    throw new Error(`响应非 JSON (${response.status})`)
+  }
   if (!response.ok || json.success === false) {
     throw new Error(json.message || `请求失败 (${response.status})`)
   }
-  return json.data as T
+  if (json.data === undefined || json.data === null) {
+    throw new Error(json.message || `响应缺少 data (${response.status})`)
+  }
+  return json.data
 }
 
 export function createFormClient(options: FormClientOptions = {}): FormClient {