@svadmin/ui 0.88.1 → 0.92.0

package/dist/components/file-upload-reference.js

@@ -0,0 +1,50 @@
+function text(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value : undefined;
+}
+export function uploadReference(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return undefined;
+    const descriptor = (key) => Object.getOwnPropertyDescriptor(value, key);
+    const read = (key) => {
+        const entry = descriptor(key);
+        return entry && 'value' in entry ? text(entry.value) : undefined;
+    };
+    const url = read('url');
+    const uploadId = read('uploadId');
+    if (url === undefined && uploadId === undefined)
+        return undefined;
+    return {
+        ...(url === undefined ? {} : { url }),
+        ...(uploadId === undefined ? {} : { uploadId }),
+    };
+}
+export function uploadReferenceFor(item) {
+    return item.status === 'success' ? uploadReference(item) : undefined;
+}
+/** 兼容历史字符串基线；只读取 plain object 自身数据属性。 */
+export function normalizeUploadReferences(value) {
+    const entries = Array.isArray(value) ? value : value === null || value === undefined ? [] : [value];
+    return entries.flatMap(entry => {
+        if (typeof entry === 'string' && entry.length > 0)
+            return [{ url: entry }];
+        const reference = uploadReference(entry);
+        return reference === undefined ? [] : [reference];
+    });
+}
+export function uploadReferenceKey(reference) {
+    return JSON.stringify([reference.url ?? null, reference.uploadId ?? null]);
+}
+/** 纯文本回显：优先 URL，其次 uploadId，避免把引用渲染成可点击链接。 */
+export function uploadReferenceLabel(reference) {
+    return reference.url ?? reference.uploadId ?? '';
+}
+export function mergeUploadReferences(baseline, uploaded) {
+    const seen = new Set();
+    return [...baseline, ...uploaded].filter(reference => {
+        const key = uploadReferenceKey(reference);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}

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

@@ -0,0 +1,32 @@
+/** FileUpload 的共享队列与回调契约；单独文件便于非 Svelte 单元静态检查。 */
+export type UploadItemStatus = 'queued' | 'uploading' | 'success' | 'error' | 'cancelled';
+export interface UploadItem {
+    id: string;
+    file: File;
+    status: UploadItemStatus;
+    progress: number;
+    url?: string;
+    error?: string;
+    uploadId?: string;
+    cleanupStatus?: 'pending' | 'success' | 'error';
+}
+export interface UploadSession {
+    signal: AbortSignal;
+    idempotencyKey: string;
+    setUploadId: (uploadId: string) => void;
+    onProgress: (progress: number) => void;
+}
+export interface UploadCancellation {
+    uploadId: string;
+    idempotencyKey: string;
+    reason: 'cancel' | 'remove' | 'replace' | 'scope-change' | 'unmount';
+}
+export interface UploadHandler {
+    (file: File, session: UploadSession): Promise<{
+        url?: string;
+        uploadId?: string;
+    } | undefined> | Promise<void>;
+}
+export interface UploadCancelHandler {
+    (file: File, cancellation: UploadCancellation): Promise<void>;
+}

package/dist/components/file-upload-types.js

@@ -0,0 +1 @@
+export {};

package/dist/components/form-contract.upload-type-fixture.svelte

@@ -0,0 +1,108 @@
+<script lang="ts">
+  import type { FieldDefinition } from '@svadmin/core';
+  import AutoForm from './AutoForm.svelte';
+  import FieldRenderer from './FieldRenderer.svelte';
+  import ArrayField from './fields/ArrayField.svelte';
+  import FileUploadField from './FileUploadField.svelte';
+  import type {
+    UploadCancellation, UploadCancelHandler, UploadHandler, UploadSession,
+  } from './file-upload-types.js';
+
+  type Assignable<Value extends Expected, Expected> = Value;
+  type UploadReceipt = { url?: string; uploadId?: string } | undefined;
+  type ReceiptContract = Assignable<Exclude<Awaited<ReturnType<UploadHandler>>, void>, UploadReceipt>;
+
+  const upload: UploadHandler = async (file: File, session: UploadSession) => {
+    const signal: AbortSignal = session.signal;
+    const idempotencyKey: string = session.idempotencyKey;
+    session.setUploadId(`upload-${file.name}`);
+    session.onProgress(0.5);
+    void signal;
+    void idempotencyKey;
+    return { url: `/uploads/${file.name}`, uploadId: `upload-${file.name}` };
+  };
+  const emptyUpload: UploadHandler = async () => {};
+  const cancelUpload: UploadCancelHandler = async (file: File, cancellation: UploadCancellation) => {
+    const uploadId: string = cancellation.uploadId;
+    const idempotencyKey: string = cancellation.idempotencyKey;
+    const reason: UploadCancellation['reason'] = cancellation.reason;
+    void file;
+    void uploadId;
+    void idempotencyKey;
+    void reason;
+  };
+
+  // @ts-expect-error Upload receipts expose only the checked reference identifiers.
+  const invalidReceipt: UploadHandler = async () => ({ localPath: '/tmp/private' });
+  // @ts-expect-error Cancellation reasons come from the checked lifecycle set.
+  const invalidReason: UploadCancellation['reason'] = 'done';
+
+  const field: FieldDefinition = { key: 'attachment', label: 'Attachment', type: 'file' };
+  const nestedArray: FieldDefinition = {
+    key: 'rows',
+    label: 'Rows',
+    type: 'array',
+    subFields: [
+      { key: 'attachment', label: 'Attachment', type: 'file' },
+      { key: 'children', label: 'Children', type: 'array',
+        subFields: [{ key: 'attachment', label: 'Attachment', type: 'file' }] },
+    ],
+  };
+  const value: unknown = null;
+  const onchange = (_next: unknown): void => {};
+  const onUploadStateChange = (state: { busy: boolean; unresolved: boolean }): void => {
+    const busy: boolean = state.busy;
+    const unresolved: boolean = state.unresolved;
+    void busy;
+    void unresolved;
+  };
+
+  const receiptContract: ReceiptContract | undefined = undefined;
+  void emptyUpload;
+  void invalidReceipt;
+  void invalidReason;
+  void receiptContract;
+</script>
+
+{#snippet uploadActions({ isLoading, isDisabled, onSubmit }: {
+  isLoading: boolean; isDisabled: boolean; onSubmit: () => void;
+})}
+  {@const typedLoading: boolean = isLoading}
+  {@const typedDisabled: boolean = isDisabled}
+  <button type="button" disabled={typedDisabled} onclick={onSubmit} data-loading={typedLoading}>
+    Save
+  </button>
+{/snippet}
+
+<AutoForm
+  resourceName="records"
+  upload={upload}
+  cancelUpload={cancelUpload}
+  formActions={uploadActions}
+/>
+<FileUploadField
+  {field}
+  {value}
+  {onchange}
+  upload={upload}
+  cancelUpload={cancelUpload}
+  {onUploadStateChange}
+/>
+<FieldRenderer
+  {field}
+  {value}
+  {onchange}
+  upload={upload}
+  cancelUpload={cancelUpload}
+  fileReferenceMode
+  {onUploadStateChange}
+/>
+<ArrayField
+  field={nestedArray}
+  {value}
+  {onchange}
+  upload={upload}
+  cancelUpload={cancelUpload}
+  fileReferenceMode
+  {onUploadStateChange}
+/>

package/dist/components/form-contract.upload-type-fixture.svelte.d.ts

@@ -0,0 +1,18 @@
+interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
+    new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
+        $$bindings?: Bindings;
+    } & Exports;
+    (internal: unknown, props: {
+        $$events?: Events;
+        $$slots?: Slots;
+    }): Exports & {
+        $set?: any;
+        $on?: any;
+    };
+    z_$$bindings?: Bindings;
+}
+declare const FormContract: $$__sveltets_2_IsomorphicComponent<Record<string, never>, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+type FormContract = InstanceType<typeof FormContract>;
+export default FormContract;

package/dist/components/json-schema-form-state.d.ts

@@ -1,8 +1,16 @@
 /** 嵌套表单的草稿与传输语义；不是替代服务端的 JSON Schema 校验器。 */
 export interface JsonSchemaFormSchema {
+    $schema?: string;
+    $id?: string;
+    $comment?: string;
+    $ref?: string;
+    $defs?: Record<string, JsonSchemaFormSchema>;
     type?: string | string[];
     const?: string | number | boolean | null;
     readOnly?: boolean;
+    writeOnly?: boolean;
+    deprecated?: boolean;
+    examples?: unknown[];
     minimum?: number;
     maximum?: number;
     exclusiveMinimum?: number;
@@ -13,13 +21,24 @@ export interface JsonSchemaFormSchema {
     minItems?: number;
     maxItems?: number;
     additionalProperties?: boolean;
+    pattern?: string;
     title?: string;
     description?: string;
     properties?: Record<string, JsonSchemaFormSchema>;
     items?: JsonSchemaFormSchema;
+    oneOf?: JsonSchemaFormSchema[];
+    discriminator?: {
+        propertyName: string;
+    };
     enum?: Array<string | number | boolean | null>;
     default?: unknown;
     required?: string[];
+    visibleWhen?: {
+        path: readonly string[];
+        equals?: string | number | boolean | null;
+        notEquals?: string | number | boolean | null;
+        exists?: boolean;
+    };
 }
 export declare const SCHEMA_FORM_LIMITS: Readonly<{
     depth: 32;

package/dist/components/list-deletion.svelte.js

@@ -6,6 +6,7 @@ export function createListDeletion(options) {
     let message = $state('');
     let pending = $state(false);
     let activeDelete;
+    let criteriaVersion = 0;
     $effect(() => {
         if (request && !options.permission().isLoading && !options.permission().allowed) {
             open = false;
@@ -38,6 +39,7 @@ export function createListDeletion(options) {
         request = null;
     }
     function cancelBatchOnCriteriaChange() {
+        criteriaVersion += 1;
         if (request?.batch && !pending)
             cancel();
     }
@@ -58,6 +60,7 @@ export function createListDeletion(options) {
             return;
         }
         const scopeIsCurrent = options.captureScope();
+        const confirmedCriteriaVersion = criteriaVersion;
         const token = {};
         activeDelete = token;
         pending = true;
@@ -66,7 +69,9 @@ export function createListDeletion(options) {
         const selectionBeforeDelete = clearBeforeMutation ? selection.captureExplicit() : undefined;
         if (clearBeforeMutation)
             options.clearSelection();
-        const current = () => activeDelete === token && scopeIsCurrent();
+        const current = () => activeDelete === token
+            && scopeIsCurrent()
+            && criteriaVersion === confirmedCriteriaVersion;
         try {
             await options.mutate([...confirmedRequest.ids]);
             if (!current())

package/dist/components/list-state.svelte.d.ts

@@ -1,7 +1,13 @@
 import type { FieldDefinition, Filter, Pagination, Sort, readURLState, writeURLState } from '@svadmin/core';
 import type { SavedListViewState } from './saved-list-views.js';
 type URLState = ReturnType<typeof readURLState>;
-type ListStateSnapshot = Pick<SavedListViewState, 'search' | 'filters' | 'sorters' | 'pagination'>;
+/** AutoTable 可恢复的列表查询快照；不包含列可见性、草稿或远程视图元数据。 */
+export interface ListStateSnapshot {
+    search: string;
+    filters: Filter[];
+    sorters: Sort[];
+    pagination: Pagination;
+}
 interface ListStateOptions {
     fields: () => FieldDefinition[];
     defaultPageSize: () => number;
@@ -9,12 +15,17 @@ interface ListStateOptions {
     externalPagination: () => Pagination | undefined;
     externalSorters: () => Sort[] | undefined;
     initialURLState: URLState;
+    initialListState?: ListStateSnapshot | undefined;
     initialViewState: SavedListViewState | undefined;
     syncWithLocation: () => boolean;
     writeURLState: (state: Parameters<typeof writeURLState>[0]) => void;
     onDirty: () => void;
+    onStateChange?: ((state: ListStateSnapshot) => void) | undefined;
 }
 export declare function cloneListFilter(filter: Filter): Filter;
+export declare function cloneListStateSnapshot(state: ListStateSnapshot): ListStateSnapshot;
+/** 将可恢复的查询快照收敛为持久化视图契约；分页可选字段在写入前补齐。 */
+export declare function captureSavedListViewState(snapshot: ListStateSnapshot, columns: Pick<SavedListViewState, 'columnVisibility' | 'columnOrder'>, fallbackPageSize: number): SavedListViewState;
 export declare function createListState(options: ListStateOptions): {
     pagination: Pagination;
     sorters: Sort[];

package/dist/components/list-state.svelte.js

@@ -11,6 +11,28 @@ export function cloneListFilter(filter) {
     }
     return { operator: filter.operator, value: filter.value.map(cloneListFilter) };
 }
+export function cloneListStateSnapshot(state) {
+    return {
+        search: state.search,
+        filters: state.filters.map(cloneListFilter),
+        sorters: state.sorters.map(sorter => ({ ...sorter })),
+        pagination: { ...state.pagination },
+    };
+}
+/** 将可恢复的查询快照收敛为持久化视图契约；分页可选字段在写入前补齐。 */
+export function captureSavedListViewState(snapshot, columns, fallbackPageSize) {
+    return {
+        search: snapshot.search,
+        filters: snapshot.filters.map(cloneListFilter),
+        sorters: snapshot.sorters.map(sorter => ({ ...sorter })),
+        pagination: {
+            current: snapshot.pagination.current ?? 1,
+            pageSize: snapshot.pagination.pageSize ?? fallbackPageSize,
+        },
+        columnVisibility: { ...columns.columnVisibility },
+        columnOrder: [...columns.columnOrder],
+    };
+}
 function editableValues(filters, fields) {
     const keys = new Set(fields.filter(field => field.filterable).map(field => field.key));
     const counts = new Map();
@@ -28,23 +50,29 @@ function editableValues(filters, fields) {
     return values;
 }
 export function createListState(options) {
-    const url = options.initialURLState;
+    const url = untrack(() => options.syncWithLocation()) ? options.initialURLState : {};
+    const initialListState = options.initialListState
+        ? cloneListStateSnapshot(options.initialListState)
+        : undefined;
     const initialView = options.initialViewState;
-    let pagination = $state(untrack(() => options.externalPagination() ?? {
-        current: url.page ?? initialView?.pagination.current ?? 1,
-        pageSize: url.pageSize ?? initialView?.pagination.pageSize ?? options.defaultPageSize(),
-    }));
+    const initialPagination = initialListState?.pagination ?? initialView?.pagination;
+    let pagination = $state(untrack(() => options.externalPagination() ?? definedOptions({
+        ...initialPagination,
+        current: url.page ?? initialPagination?.current ?? 1,
+        pageSize: url.pageSize ?? initialPagination?.pageSize ?? options.defaultPageSize(),
+    })));
     let sorters = $state(untrack(() => {
         const defaultSort = options.defaultSort();
         return options.externalSorters() ?? (url.sortField
             ? [{ field: url.sortField, order: url.sortOrder ?? 'asc' }]
-            : initialView?.sorters ?? (defaultSort ? [defaultSort] : []));
+            : initialListState?.sorters ?? initialView?.sorters ?? (defaultSort ? [defaultSort] : []));
     }));
-    let filters = $state(url.filters ?? initialView?.filters ?? []);
+    let filters = $state(url.filters ?? initialListState?.filters ?? initialView?.filters ?? []);
     let filterValues = $state(untrack(() => editableValues(filters, options.fields())));
-    let searchText = $state(url.search ?? initialView?.search ?? '');
+    let searchText = $state(url.search ?? initialListState?.search ?? initialView?.search ?? '');
     let appliedSearchText = $state(untrack(() => searchText));
     let searchTimer;
+    let lastNotifiedState = untrack(() => JSON.stringify(captureState()));
     const searchableFields = $derived(options.fields().filter(field => field.searchable));
     const filterableFields = $derived(options.fields().filter(field => field.filterable));
     const activeFilterItems = $derived.by(() => {
@@ -101,6 +129,14 @@ export function createListState(options) {
             filters,
         });
     });
+    $effect(() => {
+        const snapshot = captureState();
+        const serialized = JSON.stringify(snapshot);
+        if (serialized === lastNotifiedState)
+            return;
+        lastNotifiedState = serialized;
+        untrack(() => options.onStateChange?.(snapshot));
+    });
     $effect(() => cancelSearch);
     function cancelSearch() {
         if (searchTimer !== undefined)
@@ -175,20 +211,24 @@ export function createListState(options) {
             search: appliedSearchText,
             filters: filters.map(cloneListFilter),
             sorters: sorters.map(sorter => ({ ...sorter })),
-            pagination: {
+            pagination: definedOptions({
                 current: pagination.current ?? 1,
                 pageSize: pagination.pageSize ?? options.defaultPageSize(),
-            },
+                mode: pagination.mode,
+            }),
         };
     }
     function applyState(state) {
         cancelSearch();
-        searchText = state.search;
-        appliedSearchText = state.search;
-        filters = state.filters;
-        filterValues = editableValues(state.filters, options.fields());
-        pagination = { ...pagination, ...state.pagination };
-        sorters = state.sorters;
+        const snapshot = cloneListStateSnapshot(state);
+        const controlledPagination = options.externalPagination();
+        const controlledSorters = options.externalSorters();
+        searchText = snapshot.search;
+        appliedSearchText = snapshot.search;
+        filters = snapshot.filters;
+        filterValues = editableValues(snapshot.filters, options.fields());
+        pagination = controlledPagination ?? { ...pagination, ...snapshot.pagination };
+        sorters = controlledSorters ?? snapshot.sorters;
     }
     function resetToDefaults() {
         cancelSearch();

package/dist/components/numeric-format.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Minimal, explicit locale contract for the numeric input family.
+ *
+ * Only the locales below are accepted by the public `locale` prop. The default
+ * (no `locale`) keeps the legacy `type="number"` behaviour untouched. Adding a
+ * locale is a product decision and must come with its own parsing/screen-reader
+ * matrix instead of silently widening the contract.
+ */
+export declare const NUMERIC_INPUT_LOCALES: readonly ["en-US", "de-DE", "zh-CN"];
+export type NumericInputLocale = (typeof NUMERIC_INPUT_LOCALES)[number];
+export type NumericParseResult = {
+    ok: true;
+    value: number | null;
+} | {
+    ok: false;
+};
+export declare function isNumericInputLocale(value: string | null | undefined): value is NumericInputLocale;
+export declare function clampNumericPrecision(precision: number | null | undefined): number | undefined;
+/**
+ * Formats a stored value for display. `precision` only rounds the display; the
+ * caller keeps the original stored number. Intl's default rounding is used.
+ */
+export declare function formatNumericValue(locale: NumericInputLocale, value: number | null, precision?: number | null): string;
+/**
+ * Editable text mirrors formatting but omits grouping so that inserting a digit
+ * does not make an otherwise valid number look like a mixed-separator error.
+ */
+export declare function formatNumericEditingText(locale: NumericInputLocale, value: number | null, precision?: number | null): string;
+/**
+ * Parses locale-formatted text into a stored value. Group separators are
+ * display-only and never become part of the number. Invalid or mixed input
+ * returns `{ ok: false }` without echoing the raw text or an error message.
+ */
+export declare function parseNumericInput(locale: NumericInputLocale, text: string): NumericParseResult;
+/** Rounds a stepped value to avoid floating-point drift when precision is set. */
+export declare function roundToNumericPrecision(value: number, precision: number | null | undefined): number;
+/**
+ * Adds one step without rounding to the display precision. Display precision
+ * must not erase an explicit smaller step; decimal scaling only protects the
+ * arithmetic itself. Scaling is used while its integers stay inside
+ * Number.MAX_SAFE_INTEGER; beyond that, direct Number addition is the only
+ * truthful result. Non-finite results keep the original value.
+ */
+export declare function addNumericStep(base: number, step: number, direction?: 1 | -1): number;