@svadmin/ui 0.70.0 → 0.73.0

package/dist/components/json-schema-form-state.js

@@ -0,0 +1,168 @@
+export const SCHEMA_FORM_LIMITS = Object.freeze({ depth: 32, nodes: 10_000, characters: 1_048_576 });
+const unsafe = new Set(['__proto__', 'prototype', 'constructor']);
+const record = (value) => value !== null
+    && typeof value === 'object' && !Array.isArray(value)
+    && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+function safeKey(key) {
+    if (unsafe.has(key))
+        throw new Error('Unsafe form field');
+}
+/** wire 模式仅省略对象的 undefined；数组的空洞/undefined 不能偷偷转成 null。 */
+function copy(value, wire) {
+    const active = new Set();
+    let nodes = 0, characters = 0;
+    function visit(current, depth) {
+        if (++nodes > SCHEMA_FORM_LIMITS.nodes || depth > SCHEMA_FORM_LIMITS.depth)
+            throw new Error('Form value exceeds limits');
+        if (current === undefined && !wire)
+            return undefined;
+        if (current === null || typeof current === 'boolean')
+            return current;
+        if (typeof current === 'number' && Number.isFinite(current))
+            return current;
+        if (typeof current === 'string') {
+            characters += current.length;
+            if (characters > SCHEMA_FORM_LIMITS.characters)
+                throw new Error('Form text exceeds limits');
+            return current;
+        }
+        if ((!record(current) && !Array.isArray(current)) || active.has(current))
+            throw new Error('Expected acyclic plain form data');
+        active.add(current);
+        try {
+            if (Reflect.ownKeys(current).some(key => typeof key === 'symbol'))
+                throw new Error('Symbol values are not JSON fields');
+            if (Array.isArray(current)) {
+                if (current.length > SCHEMA_FORM_LIMITS.nodes)
+                    throw new Error('Form array exceeds limits');
+                const result = [];
+                for (let index = 0; index < current.length; index++) {
+                    const descriptor = Object.getOwnPropertyDescriptor(current, String(index));
+                    if (!descriptor || !('value' in descriptor))
+                        throw new Error('Sparse arrays and accessors are not form data');
+                    result.push(visit(descriptor.value, depth + 1));
+                }
+                if (Object.keys(current).some(key => !/^(0|[1-9][0-9]*)$/u.test(key) || Number(key) >= current.length)) {
+                    throw new Error('Array properties are not JSON fields');
+                }
+                return result;
+            }
+            const result = {};
+            for (const key of Object.keys(current)) {
+                safeKey(key);
+                characters += key.length;
+                if (characters > SCHEMA_FORM_LIMITS.characters)
+                    throw new Error('Form text exceeds limits');
+                const descriptor = Object.getOwnPropertyDescriptor(current, key);
+                if (!descriptor || !('value' in descriptor))
+                    throw new Error('Accessors are not form data');
+                if (!wire || descriptor.value !== undefined)
+                    result[key] = visit(descriptor.value, depth + 1);
+            }
+            return result;
+        }
+        finally {
+            active.delete(current);
+        }
+    }
+    return visit(value, 0);
+}
+/** Svelte 代理也通过普通数据属性读取；回调永远收不到活跃草稿的引用。 */
+export function schemaFormSnapshot(value) {
+    if (!record(value))
+        throw new Error('Form root must be an object');
+    return copy(value, true);
+}
+/** 默认值只填“缺失的键”；显式 undefined/null/false/0/空串都表示调用方的决定。 */
+export function initializeSchemaForm(schema, value) {
+    if (!record(value))
+        throw new Error('Form root must be an object');
+    const active = new Set();
+    let nodes = 0;
+    function visit(node, current, present, required, depth) {
+        if (++nodes > SCHEMA_FORM_LIMITS.nodes || depth > SCHEMA_FORM_LIMITS.depth || !record(node) || active.has(node)) {
+            throw new Error('Form schema exceeds supported traversal limits');
+        }
+        active.add(node);
+        try {
+            if (!present) {
+                if (Object.hasOwn(node, 'default'))
+                    current = copy(node.default, false);
+                else if (node.type === 'object' || node.properties)
+                    current = {};
+                else if (node.type === 'array')
+                    current = [];
+                else if (node.type === 'boolean' && required)
+                    current = false;
+            }
+            if (record(current) && (node.type === 'object' || node.properties)) {
+                let result = current;
+                for (const [key, child] of Object.entries(node.properties ?? {})) {
+                    safeKey(key);
+                    const exists = Object.hasOwn(current, key);
+                    const next = visit(child, exists ? current[key] : undefined, exists, node.required?.includes(key) ?? false, depth + 1);
+                    if ((!exists && next !== undefined) || (exists && next !== current[key])) {
+                        if (result === current)
+                            result = { ...current };
+                        result[key] = next;
+                    }
+                }
+                return result;
+            }
+            if (Array.isArray(current) && node.type === 'array' && node.items) {
+                if (current.length > SCHEMA_FORM_LIMITS.nodes)
+                    throw new Error('Form array exceeds limits');
+                const array = current;
+                const items = array.map(item => visit(node.items, item, true, true, depth + 1));
+                return items.some((item, index) => item !== array[index]) ? items : array;
+            }
+            return current;
+        }
+        finally {
+            active.delete(node);
+        }
+    }
+    return visit(schema, value, true, true, 0);
+}
+export function schemaFormArrayItem(schema) {
+    // 新增对象项也初始化其嵌套默认值及必填 false；数字留空，不猜测为 0。
+    const seed = Object.hasOwn(schema, 'default') ? copy(schema.default, false)
+        : schema.type === 'object' || schema.properties ? {}
+            : schema.type === 'array' ? [] : schema.type === 'boolean' ? false : schema.type === 'number' || schema.type === 'integer' ? undefined : '';
+    return initializeSchemaForm({ properties: { item: schema }, required: ['item'] }, { item: seed })['item'];
+}
+export function writeSchemaFormPath(value, path, nextValue) {
+    if (!path.length || path.length > SCHEMA_FORM_LIMITS.depth)
+        throw new Error('Invalid form path');
+    const next = copy(value, false);
+    let target = next;
+    for (const [index, key] of path.entries()) {
+        safeKey(key);
+        if (Array.isArray(target) && (!/^(0|[1-9][0-9]*)$/u.test(key) || Number(key) >= target.length))
+            throw new Error('Invalid array field');
+        if (index === path.length - 1) {
+            Reflect.set(target, key, copy(nextValue, false));
+        }
+        else {
+            let child = Object.hasOwn(target, key) ? Reflect.get(target, key) : undefined;
+            if (!record(child) && !Array.isArray(child)) {
+                child = {};
+                Reflect.set(target, key, child);
+            }
+            target = child;
+        }
+    }
+    return next;
+}
+/** option.value 是索引，不是 String(value)：1 与 "1"、null 与 "null" 必须可区分。 */
+export function schemaFormEnumIndex(choices, value) {
+    const index = choices.findIndex(choice => choice === value);
+    return index === -1 ? '' : String(index);
+}
+export function schemaFormEnumValue(choices, index) {
+    if (index === '')
+        return undefined;
+    if (!/^(0|[1-9][0-9]*)$/u.test(index) || !Object.hasOwn(choices, Number(index)))
+        throw new Error('Invalid form choice');
+    return choices[Number(index)];
+}

package/dist/components/profile/ActivityTimeline.svelte

@@ -12,7 +12,7 @@
   let { activities = [], showAutoRefresh = true }: Props = $props();
   let autoRefresh = $state(false);
   const i18n = useTranslation();
-  const config: Record<string, { icon: Component; tone: string; action: string }> = {
+  const config: Record<ActivityItem['type'], { icon: Component; tone: string; action: string }> = {
     posted: { icon: MessageSquare, tone: 'svadmin-u-375dc44df6e9 svadmin-u-20aaf08a7ed1', action: i18n.t('publicProfile.activityPosted') },
     commented: { icon: MessageSquare, tone: 'svadmin-u-17a9f7af2265 svadmin-u-76747e5e02ff', action: i18n.t('publicProfile.activityCommented') },
     joined: { icon: UserPlus, tone: 'svadmin-u-2ef11f1cb219 svadmin-u-bfa603190748', action: i18n.t('publicProfile.activityJoined') },
@@ -23,5 +23,5 @@
 
 <section class="svadmin-u-3e7ce58d64fa">
   <div class="svadmin-u-60fbb7713999 svadmin-u-8dddea0773ed svadmin-u-1004c0c3954c svadmin-u-020ba687fa12 svadmin-u-64cac80d2e9a svadmin-u-3b9871a0bf93"><SectionHeader title={i18n.t("publicProfile.activity")} />{#if showAutoRefresh}<div class="svadmin-u-60fbb7713999 svadmin-u-3960ffc248d9 svadmin-u-44ee8ba0a421 svadmin-u-421ac2be5045 svadmin-u-ca6bcd4b6f3f svadmin-u-18049387f0af svadmin-u-eb6a3cef9686"><Button size="sm" variant={autoRefresh ? "default" : "ghost"} onclick={() => autoRefresh = true}>{i18n.t("common.on")}</Button><Button size="sm" variant={!autoRefresh ? "default" : "ghost"} onclick={() => autoRefresh = false}>{i18n.t("common.off")}</Button></div>{/if}</div>
-  {#if activities.length === 0}<DataState state="empty" title={i18n.t('publicProfile.noActivity')} />{:else}<Card.Card><Card.CardContent class="svadmin-u-8a539c7fe216"><div class="svadmin-u-fa6acbf81d74 svadmin-u-e783642739e3">{#each activities as activity (activity.id)}{@const item = config[activity.type] ?? config.posted}<div class="svadmin-u-60fbb7713999 svadmin-u-60541e1e26f8 svadmin-u-1004c0c3954c svadmin-u-8e63407b5ceb">{#if activity.avatar}<Avatar src={activity.avatar} alt={activity.user} size="sm" />{:else}<span class={'svadmin-u-60fbb7713999 svadmin-u-d8f5213f0fe0 svadmin-u-012fbd121f37 svadmin-u-3960ffc248d9 svadmin-u-86843cf1e227 svadmin-u-ac204c108886 ' + item.tone}><item.icon class="svadmin-u-f7b5fa971871" /></span>{/if}<div class="svadmin-u-7e0b7cdf1a94 svadmin-u-36e579c0b41c"><p class="svadmin-u-fc7473ca09eb"><strong class="svadmin-u-d4108abe6359">{activity.user}</strong><span class="svadmin-u-bfa603190748"> {item.action} </span>{#if activity.target}<strong class="svadmin-u-d4108abe6359">{activity.target}</strong>{/if}</p>{#if activity.content}<p class="svadmin-u-b6b02c0ebef6 svadmin-u-fc7473ca09eb svadmin-u-bfa603190748">{activity.content}</p>{/if}<p class="svadmin-u-b6b02c0ebef6 svadmin-u-359090c2d529 svadmin-u-bfa603190748">{activity.timestamp}</p></div></div>{/each}</div></Card.CardContent></Card.Card>{/if}
+  {#if activities.length === 0}<DataState state="empty" title={i18n.t('publicProfile.noActivity')} />{:else}<Card.Card><Card.CardContent class="svadmin-u-8a539c7fe216"><div class="svadmin-u-fa6acbf81d74 svadmin-u-e783642739e3">{#each activities as activity (activity.id)}{@const item = config[activity.type] ?? config['posted']}<div class="svadmin-u-60fbb7713999 svadmin-u-60541e1e26f8 svadmin-u-1004c0c3954c svadmin-u-8e63407b5ceb">{#if activity.avatar}<Avatar src={activity.avatar} alt={activity.user} size="sm" />{:else}<span class={'svadmin-u-60fbb7713999 svadmin-u-d8f5213f0fe0 svadmin-u-012fbd121f37 svadmin-u-3960ffc248d9 svadmin-u-86843cf1e227 svadmin-u-ac204c108886 ' + item.tone}><item.icon class="svadmin-u-f7b5fa971871" /></span>{/if}<div class="svadmin-u-7e0b7cdf1a94 svadmin-u-36e579c0b41c"><p class="svadmin-u-fc7473ca09eb"><strong class="svadmin-u-d4108abe6359">{activity.user}</strong><span class="svadmin-u-bfa603190748"> {item.action} </span>{#if activity.target}<strong class="svadmin-u-d4108abe6359">{activity.target}</strong>{/if}</p>{#if activity.content}<p class="svadmin-u-b6b02c0ebef6 svadmin-u-fc7473ca09eb svadmin-u-bfa603190748">{activity.content}</p>{/if}<p class="svadmin-u-b6b02c0ebef6 svadmin-u-359090c2d529 svadmin-u-bfa603190748">{activity.timestamp}</p></div></div>{/each}</div></Card.CardContent></Card.Card>{/if}
 </section>

package/dist/components/record-detail.svelte.d.ts

@@ -0,0 +1,19 @@
+import { type ResourceRendering } from '../rendering/index.js';
+/** Views mount this only when they have an explicit record ID. */
+export declare function useRecordDetail(options: () => {
+    resourceName: string;
+    id: string | number;
+    rendering?: ResourceRendering | undefined;
+}): {
+    query: import("@tanstack/query-core").QueryObserverResult<import("@svadmin/core").GetOneResult<import("@svadmin/core").BaseRecord & {
+        id: string | number;
+    }>, unknown> & {
+        overtime: import("@svadmin/core").OvertimeResult;
+    };
+    readonly rendering: ResourceRendering | undefined;
+    readonly resource: import("@svadmin/core").ResourceDefinition;
+    readonly fields: import("@svadmin/core").FieldDefinition[];
+    readonly canRead: boolean;
+    readonly checkingPermission: boolean;
+    refresh(): Promise<void>;
+};

package/dist/components/record-detail.svelte.js

@@ -0,0 +1,34 @@
+import { bindResourceRendering } from '../rendering/index.js';
+import { captureAdminContext, useOne, useCan, useResourceContract } from '@svadmin/core';
+/** Views mount this only when they have an explicit record ID. */
+export function useRecordDetail(options) {
+    const context = captureAdminContext();
+    const binding = useResourceContract(() => options().resourceName);
+    const rendering = $derived(bindResourceRendering(options().rendering, binding.resource));
+    const resource = $derived(context.getResource(options().resourceName));
+    const permission = useCan(() => ({
+        resource: options().resourceName, action: 'show', id: options().id,
+        queryOptions: { enabled: resource.canShow !== false },
+    }));
+    const canRead = $derived(resource.canShow !== false && permission.allowed === true);
+    const query = useOne(() => {
+        void rendering;
+        return {
+            resource: binding.resource, id: options().id, dataProviderName: binding.dataProviderName,
+            queryOptions: { enabled: canRead },
+        };
+    });
+    return {
+        query,
+        get rendering() { return rendering; },
+        get resource() { return resource; },
+        get fields() { return resource.fields.filter(field => field.showInShow !== false); },
+        get canRead() { return canRead; },
+        get checkingPermission() { return permission.isLoading; },
+        async refresh() {
+            if (!canRead || query.isFetching)
+                return;
+            await query.refetch();
+        },
+    };
+}

package/dist/components/saved-list-views.js

@@ -15,31 +15,31 @@ function isPositiveInteger(value, max) {
 function parseFilter(value, allowedFieldIds, budget, depth = 0) {
     if (depth > 20 || budget.remaining-- <= 0 || !isRecord(value))
         return undefined;
-    if (typeof value.field === 'string') {
-        if (!allowedFieldIds.has(value.field) || typeof value.operator !== 'string' || !CRUD_OPERATORS.has(value.operator) || !('value' in value)) {
+    if (typeof value['field'] === 'string') {
+        if (!allowedFieldIds.has(value['field']) || typeof value['operator'] !== 'string' || !CRUD_OPERATORS.has(value['operator']) || !('value' in value)) {
             return undefined;
         }
         return {
-            field: value.field,
-            operator: value.operator,
-            value: value.value,
+            field: value['field'],
+            operator: value['operator'],
+            value: value['value'],
         };
     }
-    if ((value.operator !== 'and' && value.operator !== 'or') || !Array.isArray(value.value))
+    if ((value['operator'] !== 'and' && value['operator'] !== 'or') || !Array.isArray(value['value']))
         return undefined;
-    const children = value.value.map((entry) => parseFilter(entry, allowedFieldIds, budget, depth + 1));
+    const children = value['value'].map((entry) => parseFilter(entry, allowedFieldIds, budget, depth + 1));
     if (children.some((entry) => entry === undefined))
         return undefined;
-    return { operator: value.operator, value: children };
+    return { operator: value['operator'], value: children };
 }
 function parseSorters(value, allowedFieldIds) {
     const sorters = [];
     for (const sorter of value) {
-        if (!isRecord(sorter) || typeof sorter.field !== 'string' || !allowedFieldIds.has(sorter.field))
+        if (!isRecord(sorter) || typeof sorter['field'] !== 'string' || !allowedFieldIds.has(sorter['field']))
             return undefined;
-        if (sorter.order !== 'asc' && sorter.order !== 'desc')
+        if (sorter['order'] !== 'asc' && sorter['order'] !== 'desc')
             return undefined;
-        sorters.push({ field: sorter.field, order: sorter.order });
+        sorters.push({ field: sorter['field'], order: sorter['order'] });
     }
     return sorters;
 }
@@ -62,30 +62,30 @@ function parseColumnOrder(value, allowedColumnIds) {
 function parseState(value, allowedColumnIds) {
     if (!isRecord(value))
         return undefined;
-    if (typeof value.search !== 'string' || value.search.length > 1_000)
+    if (typeof value['search'] !== 'string' || value['search'].length > 1_000)
         return undefined;
-    if (!Array.isArray(value.filters) || !Array.isArray(value.sorters))
+    if (!Array.isArray(value['filters']) || !Array.isArray(value['sorters']))
         return undefined;
-    if (!isRecord(value.pagination) || !isPositiveInteger(value.pagination.current, 1_000_000) || !isPositiveInteger(value.pagination.pageSize, 1_000)) {
+    if (!isRecord(value['pagination']) || !isPositiveInteger(value['pagination']['current'], 1_000_000) || !isPositiveInteger(value['pagination']['pageSize'], 1_000)) {
         return undefined;
     }
     const allowedFieldIds = new Set([...allowedColumnIds].filter((columnId) => !columnId.startsWith('_')));
     const filterBudget = { remaining: MAX_FILTER_NODES };
-    const filters = value.filters.map((entry) => parseFilter(entry, allowedFieldIds, filterBudget));
+    const filters = value['filters'].map((entry) => parseFilter(entry, allowedFieldIds, filterBudget));
     if (filters.some((entry) => entry === undefined))
         return undefined;
-    const sorters = parseSorters(value.sorters, allowedFieldIds);
-    const columnVisibility = parseColumnVisibility(value.columnVisibility, allowedColumnIds);
-    const columnOrder = parseColumnOrder(value.columnOrder, allowedColumnIds);
+    const sorters = parseSorters(value['sorters'], allowedFieldIds);
+    const columnVisibility = parseColumnVisibility(value['columnVisibility'], allowedColumnIds);
+    const columnOrder = parseColumnOrder(value['columnOrder'], allowedColumnIds);
     if (!sorters || !columnVisibility || !columnOrder)
         return undefined;
     return {
-        search: value.search,
+        search: value['search'],
         filters: filters,
         sorters,
         pagination: {
-            current: value.pagination.current,
-            pageSize: value.pagination.pageSize,
+            current: value['pagination']['current'],
+            pageSize: value['pagination']['pageSize'],
         },
         columnVisibility,
         columnOrder,
@@ -96,22 +96,22 @@ export function readSavedListViews(raw, allowedColumnIds) {
         return [];
     try {
         const parsed = JSON.parse(raw);
-        if (!isRecord(parsed) || parsed.version !== STORAGE_VERSION || !Array.isArray(parsed.views))
+        if (!isRecord(parsed) || parsed['version'] !== STORAGE_VERSION || !Array.isArray(parsed['views']))
             return [];
         const views = [];
         const seenIds = new Set();
-        for (const entry of parsed.views.slice(0, MAX_SAVED_VIEWS)) {
-            if (!isRecord(entry) || typeof entry.id !== 'string' || !entry.id.trim() || entry.id.length > 120)
+        for (const entry of parsed['views'].slice(0, MAX_SAVED_VIEWS)) {
+            if (!isRecord(entry) || typeof entry['id'] !== 'string' || !entry['id'].trim() || entry['id'].length > 120)
                 continue;
-            if (seenIds.has(entry.id))
+            if (seenIds.has(entry['id']))
                 continue;
-            if (typeof entry.name !== 'string' || !entry.name.trim() || entry.name.length > 60)
+            if (typeof entry['name'] !== 'string' || !entry['name'].trim() || entry['name'].length > 60)
                 continue;
-            const state = parseState(entry.state, allowedColumnIds);
+            const state = parseState(entry['state'], allowedColumnIds);
             if (!state)
                 continue;
-            seenIds.add(entry.id);
-            views.push({ id: entry.id, name: entry.name.trim(), state });
+            seenIds.add(entry['id']);
+            views.push({ id: entry['id'], name: entry['name'].trim(), state });
         }
         return views;
     }

package/dist/components/svar-grid-cells.d.ts

@@ -0,0 +1,14 @@
+import type { Snippet } from 'svelte';
+import type { SvarRecordId } from './svar-grid-operations.js';
+export interface SvarCellContent {
+    readonly id: SvarRecordId;
+    readonly field: string;
+    readonly value: unknown;
+    readonly record: Record<string, unknown>;
+}
+export interface SvarCellContext {
+    readonly render: () => Snippet<[SvarCellContent]> | undefined;
+    readonly resolve: (row: unknown, column: unknown) => SvarCellContent | undefined;
+}
+/** 仅可信宿主可提供原生 snippet；不把引擎 api 或 exec 传给内容组件。 */
+export declare const SVAR_CELL_CONTEXT: unique symbol;

package/dist/components/svar-grid-cells.js

@@ -0,0 +1,2 @@
+/** 仅可信宿主可提供原生 snippet；不把引擎 api 或 exec 传给内容组件。 */
+export const SVAR_CELL_CONTEXT = Symbol('svadmin.svar.cell');

package/dist/components/svar-grid-contract.d.ts

@@ -0,0 +1,80 @@
+/** SVAR 2.7 的窄适配契约。应用注入 Grid，未启用的页面无需安装或加载 SVAR。 */
+export interface SvarColumn {
+    readonly key: string;
+    readonly label: string;
+    readonly width?: number;
+    readonly sortable?: boolean;
+    /** 首批内建列过滤只支持文本 contains；其他过滤通过资源 filters 传入。 */
+    readonly filterable?: boolean;
+}
+export interface SvarSort {
+    readonly field: string;
+    readonly order: 'asc' | 'desc';
+}
+export interface SvarTextFilter {
+    readonly field: string;
+    readonly operator: 'contains';
+    readonly value: string;
+}
+export interface SvarRow {
+    id: string;
+    data?: SvarRow[];
+    open?: boolean;
+    [key: string]: unknown;
+}
+export interface SvarEngineColumn {
+    id: string;
+    header: string | (string | {
+        filter: 'text';
+    })[];
+    width?: number;
+    flexgrow?: number;
+    sort: boolean;
+    resize: boolean;
+    treetoggle: boolean;
+}
+export interface SvarGridApi {
+    intercept(action: string, callback: (event: unknown) => false | undefined): void;
+}
+/** 仅使用已核对的上游属性；不暴露任意 editor、template 或事件执行入口。 */
+export interface SvarGridEngineProps {
+    /** 上游声明带事件索引；适配层不直接转发任何事件 prop。 */
+    [event: `on${string}`]: never;
+    columns: SvarEngineColumn[];
+    data?: SvarRow[];
+    tree?: boolean;
+    split?: {
+        left?: number;
+    };
+    sizes?: {
+        rowHeight?: number;
+        headerHeight?: number;
+        columnWidth?: number;
+    };
+    sortMarks?: Record<string, {
+        order: 'asc' | 'desc';
+        index?: number;
+    }>;
+    filterValues?: Record<string, string>;
+    select?: boolean;
+    multiselect?: boolean;
+    reorder?: boolean;
+    draggableRows?: boolean;
+    undo?: boolean;
+    init?: (api: SvarGridApi) => void;
+}
+export declare function svarColumnId(key: string): string;
+export declare function checkedSvarColumns(columns: readonly SvarColumn[]): SvarColumn[];
+export declare function buildSvarColumns(columns: readonly SvarColumn[], tree: boolean): SvarEngineColumn[];
+export declare function projectSvarRows(items: readonly Record<string, unknown>[], columns: readonly SvarColumn[], primaryKey?: string, childrenKey?: string): SvarRow[];
+export declare function nextSvarSort(event: unknown, columns: readonly SvarColumn[], current: readonly SvarSort[]): SvarSort[] | undefined;
+export declare function nextSvarFilter(event: unknown, columns: readonly SvarColumn[], current: readonly SvarTextFilter[]): SvarTextFilter[] | undefined;
+export declare function svarSortMarks(sorters: readonly SvarSort[]): NonNullable<SvarGridEngineProps['sortMarks']>;
+export declare function svarFilterValues(filters: readonly SvarTextFilter[]): Record<string, string>;
+export declare const SVAR_BLOCKED_ACTIONS: readonly ["add-row", "delete-row", "update-row", "update-cell", "copy-row", "move-item", "open-editor", "editor", "undo", "redo", "export-data", "print"];
+export declare function installSvarGuards(api: SvarGridApi, options: {
+    current: () => boolean;
+    server: () => boolean;
+    sort: (event: unknown) => void;
+    filter: (event: unknown) => void;
+}): void;

package/dist/components/svar-grid-contract.js

@@ -0,0 +1,159 @@
+const forbidden = new Set(['__proto__', 'prototype', 'constructor']);
+function fieldName(value) {
+    return typeof value === 'string' && value.length > 0 && !forbidden.has(value);
+}
+export function svarColumnId(key) {
+    return `column:${encodeURIComponent(key)}`;
+}
+export function checkedSvarColumns(columns) {
+    if (!Array.isArray(columns) || columns.length === 0)
+        throw new Error('At least one grid column is required');
+    const ids = new Set();
+    return columns.map(column => {
+        if (!column || !fieldName(column.key) || typeof column.label !== 'string' || ids.has(column.key)) {
+            throw new Error('Invalid or duplicate grid column');
+        }
+        if (column.width !== undefined && (!Number.isFinite(column.width) || column.width < 40 || column.width > 4096)) {
+            throw new Error('Grid column width must be between 40 and 4096');
+        }
+        ids.add(column.key);
+        // 显式投影，拒绝将宿主对象上的 editor/template 等额外属性传入 Grid。
+        return {
+            key: column.key, label: column.label,
+            sortable: column.sortable === true, filterable: column.filterable === true,
+            ...(column.width === undefined ? {} : { width: column.width }),
+        };
+    });
+}
+export function buildSvarColumns(columns, tree) {
+    return columns.map((column, index) => ({
+        id: svarColumnId(column.key),
+        header: column.filterable ? [column.label, { filter: 'text' }] : column.label,
+        ...(column.width === undefined ? { flexgrow: 1 } : { width: column.width }),
+        sort: column.sortable === true, resize: true, treetoggle: tree && index === 0,
+    }));
+}
+function ownValue(record, key) {
+    const descriptor = Object.getOwnPropertyDescriptor(record, key);
+    if (!descriptor)
+        return undefined;
+    if (!('value' in descriptor))
+        throw new Error('Grid records must not contain accessors');
+    return descriptor.value;
+}
+function scalar(value) {
+    if (value == null)
+        return null;
+    if (typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    // 复杂字段需要独立格式化；不隐式调用用户对象的 toString/toJSON。
+    return '—';
+}
+export function projectSvarRows(items, columns, primaryKey = 'id', childrenKey) {
+    if (!Array.isArray(items) || !fieldName(primaryKey) || (childrenKey !== undefined && !fieldName(childrenKey))) {
+        throw new Error('Invalid grid data configuration');
+    }
+    const ids = new Set();
+    const ancestors = new Set();
+    function visit(rows, depth) {
+        if (depth > 64)
+            throw new Error('Grid tree is too deep');
+        return rows.map(record => {
+            if (!record || typeof record !== 'object' || Array.isArray(record) || ancestors.has(record)) {
+                throw new Error('Invalid or cyclic grid record');
+            }
+            const id = ownValue(record, primaryKey);
+            if (!(typeof id === 'string' && id.length > 0) && !(typeof id === 'number' && Number.isFinite(id))) {
+                throw new Error('Every grid record requires a stable string or finite number ID');
+            }
+            // SVAR 内部 ID 使用字符串；防止数字 1 与字符串 "1" 相互覆盖。
+            const key = `${typeof id === 'number' ? 'n' : 's'}:${id}`;
+            if (ids.has(key))
+                throw new Error('Duplicate grid record ID');
+            ids.add(key);
+            const row = { id: key };
+            for (const column of columns)
+                row[svarColumnId(column.key)] = scalar(ownValue(record, column.key));
+            if (childrenKey !== undefined) {
+                const children = ownValue(record, childrenKey);
+                if (children !== undefined && !Array.isArray(children))
+                    throw new Error('Grid children must be an array');
+                if (Array.isArray(children) && children.length) {
+                    ancestors.add(record);
+                    row.data = visit(children, depth + 1);
+                    ancestors.delete(record);
+                    row.open = false;
+                }
+            }
+            return row;
+        });
+    }
+    return visit(items, 0);
+}
+function eventRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}
+export function nextSvarSort(event, columns, current) {
+    const value = eventRecord(event);
+    if (!value || (value['order'] !== undefined && value['order'] !== 'asc' && value['order'] !== 'desc')
+        || (value['add'] !== undefined && typeof value['add'] !== 'boolean'))
+        return undefined;
+    const column = columns.find(column => svarColumnId(column.key) === value['key'] && column.sortable);
+    if (!column)
+        return undefined;
+    const existing = current.find(sort => sort.field === column.key);
+    const order = value['order'] ?? (existing?.order === 'asc' ? 'desc' : 'asc');
+    const next = value['add'] ? current.map(sort => ({ ...sort })) : [];
+    const index = next.findIndex(sort => sort.field === column.key);
+    const sort = { field: column.key, order };
+    if (index < 0)
+        next.push(sort);
+    else
+        next[index] = sort;
+    return next;
+}
+export function nextSvarFilter(event, columns, current) {
+    const value = eventRecord(event);
+    if (!value || (value['value'] != null && typeof value['value'] !== 'string'))
+        return undefined;
+    const column = columns.find(column => svarColumnId(column.key) === value['key'] && column.filterable);
+    if (!column)
+        return undefined;
+    const next = current.filter(filter => filter.field !== column.key).map(filter => ({ ...filter }));
+    if (typeof value['value'] === 'string' && value['value'] !== '') {
+        next.push({ field: column.key, operator: 'contains', value: value['value'] });
+    }
+    return next;
+}
+export function svarSortMarks(sorters) {
+    return Object.fromEntries(sorters.map((sort, index) => [svarColumnId(sort.field), { order: sort.order, index }]));
+}
+export function svarFilterValues(filters) {
+    return Object.fromEntries(filters.map(filter => [svarColumnId(filter.field), filter.value]));
+}
+export const SVAR_BLOCKED_ACTIONS = [
+    'add-row', 'delete-row', 'update-row', 'update-cell', 'copy-row', 'move-item',
+    'open-editor', 'editor', 'undo', 'redo', 'export-data', 'print',
+];
+export function installSvarGuards(api, options) {
+    for (const action of SVAR_BLOCKED_ACTIONS)
+        api.intercept(action, () => false);
+    api.intercept('sort-rows', event => {
+        if (!options.current())
+            return false;
+        if (options.server()) {
+            options.sort(event);
+            return false;
+        }
+    });
+    api.intercept('filter-rows', event => {
+        if (!options.current())
+            return false;
+        if (options.server()) {
+            options.filter(event);
+            return false;
+        }
+    });
+}