@svadmin/ui 0.88.1 → 0.92.0

package/dist/components/enterprise/schema-form-references.js

@@ -0,0 +1,316 @@
+import { SCHEMA_FORM_LIMITS } from '../json-schema-form-state.js';
+const unsafe = new Set(['__proto__', 'prototype', 'constructor']);
+const internalRef = /^#\/\$defs\/([^/]+)$/u;
+const externalRef = /^([^#]+)(?:#(.*))?$/u;
+const MAX_REFERENCES = 256;
+const MAX_DEFINITIONS = 256;
+const typeBoxSymbols = new Set([
+    Symbol.for('TypeBox.Kind'), Symbol.for('TypeBox.Optional'), Symbol.for('TypeBox.Readonly'),
+]);
+const typeBoxMetadata = new Set(['~kind', '~optional', '~readonly']);
+const pointer = (key) => '/' + key.replaceAll('~', '~0').replaceAll('/', '~1');
+/** 只接受由数据属性组成的普通对象，不执行 getter。 */
+function dataRecord(value, schemaNode = false) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        return false;
+    return Reflect.ownKeys(value).every(key => {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (typeof key === 'symbol') {
+            return schemaNode && typeBoxSymbols.has(key)
+                && descriptor !== undefined && 'value' in descriptor
+                && typeof descriptor.value === 'string';
+        }
+        if (schemaNode && descriptor?.enumerable === false) {
+            return typeBoxMetadata.has(key) && 'value' in descriptor;
+        }
+        return descriptor !== undefined && 'value' in descriptor;
+    });
+}
+function own(record, key) {
+    const descriptor = Object.getOwnPropertyDescriptor(record, key);
+    return descriptor !== undefined && 'value' in descriptor ? descriptor.value : undefined;
+}
+function decodePointerSegment(segment) {
+    if (!segment)
+        return undefined;
+    let result = '';
+    for (let index = 0; index < segment.length; index++) {
+        const character = segment[index];
+        if (character !== '~') {
+            result += character;
+            continue;
+        }
+        const escape = segment[++index];
+        if (escape === '0')
+            result += '~';
+        else if (escape === '1')
+            result += '/';
+        else
+            return undefined;
+    }
+    return result;
+}
+function validDocumentUri(uri) {
+    if (uri.length === 0 || uri.includes('#'))
+        return false;
+    for (const character of uri) {
+        const code = character.codePointAt(0) ?? 0;
+        if (code <= 0x20 || code === 0x7f)
+            return false;
+    }
+    return true;
+}
+function referenceTarget(reference, localDefinitions, documents) {
+    const local = internalRef.exec(reference);
+    if (local) {
+        const name = decodePointerSegment(local[1] ?? '');
+        if (name === undefined || unsafe.has(name) || !localDefinitions || !Object.hasOwn(localDefinitions, name))
+            return undefined;
+        return { target: own(localDefinitions, name), definitions: localDefinitions, root: false };
+    }
+    const match = externalRef.exec(reference);
+    if (!match)
+        return undefined;
+    const uri = match[1] ?? '';
+    if (!validDocumentUri(uri) || !Object.hasOwn(documents, uri))
+        return undefined;
+    const document = own(documents, uri);
+    if (!dataRecord(document, true))
+        return undefined;
+    const fragment = match[2];
+    if (fragment !== undefined && fragment !== '' && !fragment.startsWith('/$defs/'))
+        return undefined;
+    let definitions;
+    const candidates = own(document, '$defs');
+    if (candidates !== undefined) {
+        if (!dataRecord(candidates) || Object.keys(candidates).length > MAX_DEFINITIONS)
+            return undefined;
+        definitions = candidates;
+    }
+    if (fragment === undefined || fragment === '')
+        return { target: document, definitions, root: true };
+    const name = decodePointerSegment(fragment.slice('/$defs/'.length));
+    if (name === undefined || unsafe.has(name) || !definitions || !Object.hasOwn(definitions, name))
+        return undefined;
+    return { target: own(definitions, name), definitions, root: false };
+}
+/**
+ * 解析受控的本地外部引用子集。
+ * 外部引用必须命中宿主传入的精确 URI 映射，只允许根文档或 `/$defs/<name>`；
+ * 不执行网络、fetch/XHR、动态 import、storage 或环境读取。
+ */
+export function resolveSchemaFormReferences(schema, referenceDocuments = {}) {
+    const issues = [];
+    const active = new Set();
+    const activeData = new Set();
+    let localDefinitions;
+    let expansions = 0;
+    let nodes = 0;
+    const issue = (path, code) => {
+        if (issues.length < 128)
+            issues.push({ path, code });
+    };
+    if (!dataRecord(referenceDocuments)) {
+        issue('', 'ref-invalid');
+        referenceDocuments = {};
+    }
+    function copyData(raw, path, depth) {
+        if (++nodes > SCHEMA_FORM_LIMITS.nodes || depth > SCHEMA_FORM_LIMITS.depth) {
+            issue(path, 'invalid-schema');
+            return undefined;
+        }
+        if (raw === undefined || raw === null || typeof raw === 'boolean' || typeof raw === 'string')
+            return raw;
+        if (typeof raw === 'number') {
+            if (Number.isFinite(raw))
+                return raw;
+            issue(path, 'invalid-schema');
+            return undefined;
+        }
+        if (typeof raw !== 'object' || activeData.has(raw)) {
+            issue(path, 'invalid-schema');
+            return undefined;
+        }
+        activeData.add(raw);
+        try {
+            if (Array.isArray(raw)) {
+                if (Reflect.ownKeys(raw).some(key => typeof key === 'symbol') || raw.length > SCHEMA_FORM_LIMITS.nodes) {
+                    issue(path, 'invalid-schema');
+                    return undefined;
+                }
+                for (let index = 0; index < raw.length; index++) {
+                    const descriptor = Object.getOwnPropertyDescriptor(raw, String(index));
+                    if (!descriptor || !('value' in descriptor)) {
+                        issue(path + '/' + index, 'invalid-schema');
+                        return undefined;
+                    }
+                }
+                if (Object.keys(raw).some(key => !/^(0|[1-9]\d*)$/u.test(key) || Number(key) >= raw.length)) {
+                    issue(path, 'invalid-schema');
+                    return undefined;
+                }
+                const result = [];
+                for (let index = 0; index < raw.length; index++) {
+                    result.push(copyData(own(raw, String(index)), path + '/' + index, depth + 1));
+                }
+                return result;
+            }
+            if (!dataRecord(raw)) {
+                issue(path, 'invalid-schema');
+                return undefined;
+            }
+            const result = {};
+            for (const key of Object.keys(raw)) {
+                if (unsafe.has(key)) {
+                    issue(path + pointer(key), 'invalid-schema');
+                    continue;
+                }
+                const source = own(raw, key);
+                const value = copyData(source, path + pointer(key), depth + 1);
+                if (value !== undefined || source === undefined) {
+                    Object.defineProperty(result, key, { value, enumerable: true, configurable: true, writable: true });
+                }
+            }
+            return result;
+        }
+        finally {
+            activeData.delete(raw);
+        }
+    }
+    function collectDefinitions(raw, path) {
+        const candidates = own(raw, '$defs');
+        if (candidates === undefined)
+            return undefined;
+        if (!dataRecord(candidates) || Object.keys(candidates).length > MAX_DEFINITIONS) {
+            issue(path + '/$defs', 'invalid-schema');
+            return undefined;
+        }
+        const collected = Object.create(null);
+        for (const key of Object.keys(candidates)) {
+            if (unsafe.has(key)) {
+                issue(path + '/$defs' + pointer(key), 'invalid-schema');
+                continue;
+            }
+            collected[key] = own(candidates, key);
+        }
+        return collected;
+    }
+    function expand(raw, path, depth, refDepth, root, definitions = localDefinitions) {
+        if (++nodes > SCHEMA_FORM_LIMITS.nodes || depth > SCHEMA_FORM_LIMITS.depth) {
+            issue(path, 'invalid-schema');
+            return undefined;
+        }
+        if (!dataRecord(raw, true) || active.has(raw)) {
+            issue(path, 'invalid-schema');
+            return undefined;
+        }
+        active.add(raw);
+        try {
+            if (Object.hasOwn(raw, '$ref')) {
+                const schemaKeys = Object.getOwnPropertyNames(raw).filter(key => !(['~kind', '~optional', '~readonly'].includes(key)
+                    && Object.getOwnPropertyDescriptor(raw, key)?.enumerable === false));
+                if (schemaKeys.length !== 1) {
+                    issue(path, 'unsupported-schema');
+                    return undefined;
+                }
+                const reference = own(raw, '$ref');
+                if (typeof reference !== 'string') {
+                    issue(path, 'ref-invalid');
+                    return undefined;
+                }
+                const resolved = referenceTarget(reference, definitions, referenceDocuments);
+                if (!resolved) {
+                    issue(path, 'ref-invalid');
+                    return undefined;
+                }
+                if (++expansions > MAX_REFERENCES || refDepth + 1 > SCHEMA_FORM_LIMITS.depth) {
+                    issue(path, 'ref-limit');
+                    return undefined;
+                }
+                const target = resolved.target;
+                if (target !== null && typeof target === 'object' && active.has(target)) {
+                    issue(path, 'ref-cycle');
+                    return undefined;
+                }
+                return expand(target, path, depth, refDepth + 1, resolved.root, resolved.definitions);
+            }
+            const currentDefinitions = root ? collectDefinitions(raw, path) : definitions;
+            if (root)
+                localDefinitions = currentDefinitions;
+            const result = {};
+            for (const key of Object.keys(raw)) {
+                if (root && key === '$defs')
+                    continue;
+                if (key === 'properties') {
+                    const properties = own(raw, key);
+                    if (!dataRecord(properties) || Object.keys(properties).length > MAX_DEFINITIONS) {
+                        issue(path + '/properties', 'invalid-schema');
+                        continue;
+                    }
+                    const expanded = {};
+                    for (const name of Object.keys(properties)) {
+                        if (unsafe.has(name)) {
+                            issue(path + '/properties' + pointer(name), 'invalid-schema');
+                            continue;
+                        }
+                        const child = expand(own(properties, name), path + pointer(name), depth + 1, 0, false, currentDefinitions);
+                        if (child !== undefined)
+                            Object.defineProperty(expanded, name, { value: child, enumerable: true, configurable: true, writable: true });
+                    }
+                    Object.defineProperty(result, key, { value: expanded, enumerable: true, configurable: true, writable: true });
+                    continue;
+                }
+                if (key === 'items') {
+                    const item = expand(own(raw, key), path + '/items', depth + 1, 0, false, currentDefinitions);
+                    if (item !== undefined)
+                        Object.defineProperty(result, key, { value: item, enumerable: true, configurable: true, writable: true });
+                    continue;
+                }
+                if (key === 'oneOf') {
+                    const branches = own(raw, key);
+                    if (!Array.isArray(branches) || branches.length === 0 || branches.length > MAX_DEFINITIONS
+                        || Reflect.ownKeys(branches).some(branchKey => typeof branchKey === 'symbol')
+                        || Object.keys(branches).some(branchKey => !/^(0|[1-9]\d*)$/u.test(branchKey) || Number(branchKey) >= branches.length)) {
+                        issue(path + '/oneOf', 'oneOf-invalid');
+                        continue;
+                    }
+                    const expanded = [];
+                    for (let index = 0; index < branches.length; index++) {
+                        const descriptor = Object.getOwnPropertyDescriptor(branches, String(index));
+                        if (!descriptor || !('value' in descriptor)) {
+                            issue(path + '/oneOf/' + index, 'oneOf-invalid');
+                            continue;
+                        }
+                        const branch = expand(descriptor.value, path + '/oneOf/' + index, depth + 1, 0, false, currentDefinitions);
+                        if (branch !== undefined)
+                            expanded.push(branch);
+                    }
+                    if (expanded.length === branches.length)
+                        Object.defineProperty(result, key, { value: expanded, enumerable: true, configurable: true, writable: true });
+                    continue;
+                }
+                const source = own(raw, key);
+                const value = copyData(source, path + pointer(key), 0);
+                if (value !== undefined || source === undefined)
+                    Object.defineProperty(result, key, { value, enumerable: true, configurable: true, writable: true });
+            }
+            return result;
+        }
+        finally {
+            active.delete(raw);
+        }
+    }
+    let resolved;
+    try {
+        const next = expand(schema, '', 0, 0, true);
+        if (next !== undefined && dataRecord(next))
+            resolved = next;
+    }
+    catch {
+        issue('', 'invalid-schema');
+    }
+    return { schema: issues.length ? undefined : resolved, issues };
+}

package/dist/components/fields/ArrayField.svelte

@@ -2,20 +2,95 @@
   import type { FieldDefinition } from '@svadmin/core';
   import { useTranslation } from '@svadmin/core/i18n';
   import { Button } from '../ui/button/index.js';
-  import { Plus, Trash2 } from '@lucide/svelte';
+  import { ArrowDown, ArrowUp, Plus, Trash2 } from '@lucide/svelte';
   import TooltipButton from '../TooltipButton.svelte';
   import FieldRenderer from '../FieldRenderer.svelte';
+  import type { UploadCancelHandler, UploadHandler } from '../file-upload-types.js';
+  import { arrayFieldRowKey as editedRowKey, arrayFieldOrderKey as outputOrderKey } from './array-field-metadata.js';
 
   const i18n = useTranslation();
 
-  let { field, value, onchange } = $props<{
+  interface Props {
     field: FieldDefinition;
     value: unknown;
     onchange: (val: unknown) => void;
-  }>();
+    disabled?: boolean;
+    labelledby?: string;
+    describedby?: string;
+    invalid?: boolean;
+    nativeSubmit?: boolean;
+    upload?: UploadHandler;
+    cancelUpload?: UploadCancelHandler;
+    onUploadStateChange?: (state: { busy: boolean; unresolved: boolean }) => void;
+    fileReferenceMode?: boolean;
+    fileScopeKey?: string | number | object;
+  }
+
+  let {
+    field, value, onchange, disabled = false, labelledby, describedby, invalid = false,
+    nativeSubmit = true, upload, cancelUpload, onUploadStateChange, fileReferenceMode = false,
+    fileScopeKey,
+  }: Props = $props();
 
-  const arrayVal = $derived(Array.isArray(value) ? value : []);
+  const instanceId = $props.id();
+  const headingId = `${instanceId}-heading`;
+  const arrayVal = $derived<Record<string, unknown>[]>(Array.isArray(value) ? value : []);
   const subFields = $derived(field.subFields || []);
+  let previousItems: Record<string, unknown>[] = [];
+  let previousKeys: number[] = [];
+  const pendingEdits = new Set<number>();
+  let pendingItems: Record<string, unknown>[] = [];
+  let pendingKeys: number[] = [];
+  const childUploadStates = new Map<string, { busy: boolean; unresolved: boolean }>();
+  let outputSequence = 0;
+  let nextKey = 0;
+  function rememberOutput(items: Record<string, unknown>[], keys: number[]) {
+    Object.defineProperty(items, outputOrderKey, { value: ++outputSequence });
+    pendingItems = [...items];
+    pendingKeys = [...keys];
+  }
+  const rows = $derived.by(() => {
+    const acceptedOutput = Reflect.get(arrayVal, outputOrderKey) === outputSequence
+      && pendingItems.length === arrayVal.length
+      && arrayVal.every((item, index) => Object.is(item, pendingItems[index]));
+    if (acceptedOutput) {
+      const nextRows = arrayVal.map((item, index) => ({ item, key: pendingKeys[index] ?? ++nextKey }));
+      previousItems = [...arrayVal];
+      previousKeys = nextRows.map(row => row.key);
+      pendingItems = [];
+      pendingKeys = [];
+      pendingEdits.clear();
+      return nextRows;
+    }
+    const used = new Set<number>();
+    // 先保留显式编辑行，避免同一对象出现在多行时被未编辑的行抢走身份。
+    const matches = arrayVal.map(item => {
+      const key: unknown = Reflect.get(item, editedRowKey);
+      if (typeof key !== 'number' || !pendingEdits.has(key)) return -1;
+      const index = previousKeys.indexOf(key);
+      if (index < 0 || used.has(index)) return -1;
+      used.add(index);
+      return index;
+    });
+    arrayVal.forEach((item, position) => {
+      if (matches[position] !== -1) return;
+      const index = previousItems.findIndex((previous, i) => previous === item && !used.has(i));
+      if (index >= 0) used.add(index);
+      matches[position] = index;
+    });
+    const nextRows = arrayVal.map((item, index) => {
+      const match = matches[index] ?? -1;
+      const key = match >= 0 ? previousKeys[match] : undefined;
+      if (key !== undefined) pendingEdits.delete(key);
+      return { item, key: key ?? ++nextKey };
+    });
+    previousItems = [...arrayVal];
+    previousKeys = nextRows.map(row => row.key);
+    pendingItems = [];
+    pendingKeys = [];
+    pendingEdits.clear();
+    return nextRows;
+  });
 
   function getDefaultForType(type: string): unknown {
     switch (type) {
@@ -29,42 +104,121 @@
   }
 
   function handleAdd() {
+    if (disabled) return;
     const newItem: Record<string, unknown> = {};
     for (const f of subFields) {
       newItem[f.key] = f.defaultValue ?? getDefaultForType(f.type);
     }
-    onchange([...arrayVal, newItem]);
+    const next = [...arrayVal, newItem];
+    rememberOutput(next, [...rows.map(row => row.key), ++nextKey]);
+    onchange(next);
+  }
+
+  function reportChildUploadState(
+    key: string,
+    state: { busy: boolean; unresolved: boolean },
+  ): void {
+    if (!state.busy && !state.unresolved) childUploadStates.delete(key);
+    else childUploadStates.set(key, state);
+    const states = [...childUploadStates.values()];
+    onUploadStateChange?.({
+      busy: states.some(value => value.busy),
+      unresolved: states.some(value => value.unresolved),
+    });
   }
 
   function handleRemove(index: number) {
-    onchange(arrayVal.filter((_, i) => i !== index));
+    if (disabled) return;
+    const next = arrayVal.filter((_, i) => i !== index);
+    rememberOutput(next, rows.filter((_, i) => i !== index).map(row => row.key));
+    onchange(next);
+  }
+
+  function handleMove(index: number, direction: -1 | 1) {
+    if (disabled || index < 0 || index >= arrayVal.length) return;
+    const target = index + direction;
+    if (target < 0 || target >= arrayVal.length) return;
+    const next = [...arrayVal];
+    const moved = next.splice(index, 1);
+    next.splice(target, 0, ...moved);
+    const nextKeys = rows.map(row => row.key);
+    const movedKey = nextKeys.splice(index, 1);
+    nextKeys.splice(target, 0, ...movedKey);
+    rememberOutput(next, nextKeys);
+    onchange(next);
   }
 
   function handleChange(index: number, key: string, val: unknown) {
+    if (disabled) return;
     const next = [...arrayVal];
-    next[index] = { ...next[index], [key]: val };
+    const edited = { ...next[index], [key]: val };
+    const rowKey = rows[index]?.key;
+    if (rowKey !== undefined) {
+      Object.defineProperty(edited, editedRowKey, { value: rowKey });
+      pendingEdits.add(rowKey);
+    }
+    next[index] = edited;
+    rememberOutput(next, rows.map(row => row.key));
     onchange(next);
   }
 </script>
 
-<div class="svadmin-u-3e7ce58d64fa svadmin-u-5f22e64f2282 svadmin-u-ca6bcd4b6f3f svadmin-u-a29b7a649c77 svadmin-u-8e63407b5ceb">
+<div
+  role="group"
+  aria-labelledby={labelledby ?? headingId}
+  aria-describedby={describedby}
+  aria-disabled={disabled || undefined}
+  data-invalid={invalid || undefined}
+  class="svadmin-u-3e7ce58d64fa svadmin-u-5f22e64f2282 svadmin-u-ca6bcd4b6f3f svadmin-u-a29b7a649c77 svadmin-u-8e63407b5ceb"
+>
   <div class="svadmin-u-60fbb7713999 svadmin-u-3960ffc248d9 svadmin-u-8ef2268efbbc">
-    <div class="svadmin-u-fc7473ca09eb svadmin-u-2689f3958069 svadmin-u-d4108abe6359">
+    <div id={headingId} class="svadmin-u-fc7473ca09eb svadmin-u-2689f3958069 svadmin-u-d4108abe6359">
       {field.label}
       {#if field.required}
         <span class="svadmin-u-811148b13d1e">*</span>
       {/if}
     </div>
-    <Button variant="outline" size="sm" type="button" onclick={handleAdd}>
+    <Button
+      variant="outline"
+      size="sm"
+      type="button"
+      disabled={disabled}
+      {...(describedby === undefined ? {} : { 'aria-describedby': describedby })}
+      {...(invalid ? { 'aria-invalid': true } : {})}
+      onclick={handleAdd}
+    >
       <Plus class="svadmin-u-7fc7f732bf7e svadmin-u-bf600f8e029c svadmin-u-618162408e7a" /> {i18n.t('common.add') || 'Add'}
     </Button>
   </div>
   
   <div class="svadmin-u-3e7ce58d64fa svadmin-u-f46b61a9b310">
-    {#each arrayVal as item, i (i)}
-      <div class="svadmin-u-d89972fe17d6 svadmin-u-421ac2be5045 svadmin-u-ca6bcd4b6f3f svadmin-u-cd0ad9a56558 svadmin-u-8e63407b5ceb svadmin-u-30c1d058f0db svadmin-u-438b2237b8d6">
-        <div class="svadmin-u-da4dbfbc4fdc svadmin-u-7b2d63937d23 svadmin-u-9a2db8f949b6">
-          <TooltipButton tooltip={i18n.t('common.remove') || 'Remove'} variant="ghost" size="icon" class="svadmin-u-ed8a5df7b2fb svadmin-u-2bbcfc3b5179 svadmin-u-bfa603190748 svadmin-u-51e95020d6f2 svadmin-u-ceb69a6b0e5f" onclick={() => handleRemove(i)}>
+    {#each rows as row, i (row.key)}
+      {@const item = row.item}
+      <div role="group" aria-label={`${field.label} ${i + 1}`} class="svadmin-u-d89972fe17d6 svadmin-u-421ac2be5045 svadmin-u-ca6bcd4b6f3f svadmin-u-cd0ad9a56558 svadmin-u-8e63407b5ceb svadmin-u-30c1d058f0db svadmin-u-438b2237b8d6">
+        <div style="display: flex; justify-content: flex-end; gap: 4px;">
+          <TooltipButton
+            disabled={disabled || i === 0}
+            tooltip={i18n.t('common.moveUp') || 'Move up'}
+            variant="ghost"
+            size="icon"
+            aria-label={i18n.t('common.moveUp') || 'Move up'}
+            class="svadmin-u-ed8a5df7b2fb svadmin-u-2bbcfc3b5179"
+            onclick={() => handleMove(i, -1)}
+          >
+            <ArrowUp class="svadmin-u-11e59c6d5f6b svadmin-u-dc7972ebf3f3" />
+          </TooltipButton>
+          <TooltipButton
+            disabled={disabled || i === arrayVal.length - 1}
+            tooltip={i18n.t('common.moveDown') || 'Move down'}
+            variant="ghost"
+            size="icon"
+            aria-label={i18n.t('common.moveDown') || 'Move down'}
+            class="svadmin-u-ed8a5df7b2fb svadmin-u-2bbcfc3b5179"
+            onclick={() => handleMove(i, 1)}
+          >
+            <ArrowDown class="svadmin-u-11e59c6d5f6b svadmin-u-dc7972ebf3f3" />
+          </TooltipButton>
+          <TooltipButton disabled={disabled} tooltip={i18n.t('common.remove') || 'Remove'} variant="ghost" size="icon" class="svadmin-u-ed8a5df7b2fb svadmin-u-2bbcfc3b5179 svadmin-u-bfa603190748 svadmin-u-51e95020d6f2 svadmin-u-ceb69a6b0e5f" onclick={() => handleRemove(i)}>
             <Trash2 class="svadmin-u-11e59c6d5f6b svadmin-u-dc7972ebf3f3" />
           </TooltipButton>
         </div>
@@ -73,6 +227,16 @@
             <FieldRenderer
               field={subField}
               value={item[subField.key]}
+              disabled={disabled}
+              {nativeSubmit}
+              {fileReferenceMode}
+              {...(fileScopeKey === undefined ? {} : { fileScopeKey })}
+              {...(upload === undefined ? {} : { upload })}
+              {...(cancelUpload === undefined ? {} : { cancelUpload })}
+              {...(onUploadStateChange === undefined
+                ? {}
+                : { onUploadStateChange: (state: { busy: boolean; unresolved: boolean }) =>
+                  reportChildUploadState(`${row.key}:${subField.key}`, state) })}
               onchange={(val) => handleChange(i, subField.key, val)}
             />
           {/each}

package/dist/components/fields/ArrayField.svelte.d.ts

@@ -1,9 +1,23 @@
 import type { FieldDefinition } from '@svadmin/core';
-type $$ComponentProps = {
+import type { UploadCancelHandler, UploadHandler } from '../file-upload-types.js';
+interface Props {
     field: FieldDefinition;
     value: unknown;
     onchange: (val: unknown) => void;
-};
-declare const ArrayField: import("svelte").Component<$$ComponentProps, {}, "">;
+    disabled?: boolean;
+    labelledby?: string;
+    describedby?: string;
+    invalid?: boolean;
+    nativeSubmit?: boolean;
+    upload?: UploadHandler;
+    cancelUpload?: UploadCancelHandler;
+    onUploadStateChange?: (state: {
+        busy: boolean;
+        unresolved: boolean;
+    }) => void;
+    fileReferenceMode?: boolean;
+    fileScopeKey?: string | number | object;
+}
+declare const ArrayField: import("svelte").Component<Props, {}, "">;
 type ArrayField = ReturnType<typeof ArrayField>;
 export default ArrayField;

package/dist/components/fields/array-field-metadata.d.ts

@@ -0,0 +1,4 @@
+export declare const arrayFieldRowKey: unique symbol;
+export declare const arrayFieldOrderKey: unique symbol;
+/** 仅剥离 UI 行身份；保留其他描述符，让 Core 继续拒绝非法业务数据。 */
+export declare function withoutArrayFieldMetadata(value: unknown): unknown;

package/dist/components/fields/array-field-metadata.js

@@ -0,0 +1,36 @@
+export const arrayFieldRowKey = Symbol('array-field-row');
+export const arrayFieldOrderKey = Symbol('array-field-order');
+/** 仅剥离 UI 行身份；保留其他描述符，让 Core 继续拒绝非法业务数据。 */
+export function withoutArrayFieldMetadata(value) {
+    const copies = new Map();
+    function copy(input) {
+        if (typeof input !== 'object' || input === null)
+            return input;
+        const prototype = Object.getPrototypeOf(input);
+        if (!Array.isArray(input) && prototype !== Object.prototype && prototype !== null)
+            return input;
+        const previous = copies.get(input);
+        if (previous)
+            return previous;
+        const output = Array.isArray(input) ? [] : Object.create(prototype);
+        copies.set(input, output);
+        for (const key of Reflect.ownKeys(input)) {
+            if (key === arrayFieldRowKey || key === arrayFieldOrderKey)
+                continue;
+            const descriptor = Object.getOwnPropertyDescriptor(input, key);
+            if (!descriptor)
+                continue;
+            if ('value' in descriptor)
+                descriptor.value = copy(descriptor.value);
+            Object.defineProperty(output, key, descriptor);
+        }
+        return output;
+    }
+    try {
+        return copy(value);
+    }
+    catch {
+        // 由 Core 归一化拒绝，不能把无法读取的数据替换成可提交的空值。
+        return value;
+    }
+}

package/dist/components/file-upload-reference.d.ts

@@ -0,0 +1,11 @@
+import type { UploadItem } from './file-upload-types.js';
+/** 上传成功后写入表单的 JSON 引用；保留服务端返回的全部标识。 */
+export type UploadReference = Pick<UploadItem, 'url' | 'uploadId'>;
+export declare function uploadReference(value: unknown): UploadReference | undefined;
+export declare function uploadReferenceFor(item: Pick<UploadItem, 'status' | 'url' | 'uploadId'>): UploadReference | undefined;
+/** 兼容历史字符串基线；只读取 plain object 自身数据属性。 */
+export declare function normalizeUploadReferences(value: unknown): UploadReference[];
+export declare function uploadReferenceKey(reference: UploadReference): string;
+/** 纯文本回显：优先 URL，其次 uploadId，避免把引用渲染成可点击链接。 */
+export declare function uploadReferenceLabel(reference: UploadReference): string;
+export declare function mergeUploadReferences(baseline: UploadReference[], uploaded: UploadReference[]): UploadReference[];