@svadmin/ui 0.72.0 → 0.73.0

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

@@ -0,0 +1,174 @@
+import { checkedSvarColumns, buildSvarColumns, svarColumnId, nextSvarSort, nextSvarFilter, SVAR_BLOCKED_ACTIONS } from './svar-grid-contract.js';
+import { svarRecordIndex, svarRecordKey } from './svar-grid-operations.js';
+export function checkedSvarInteractiveColumns(columns) {
+    const checked = checkedSvarColumns(columns);
+    const formats = new Set(['plain', 'number', 'currency', 'percent', 'date', 'datetime', 'boolean']);
+    return checked.map((column, index) => {
+        const source = columns[index];
+        if (!source)
+            throw new Error('Missing column');
+        if (source.editable !== undefined && source.editable !== 'text' && source.editable !== 'number')
+            throw new Error('Invalid editor');
+        if (source.format !== undefined && !formats.has(source.format))
+            throw new Error('Invalid value format');
+        if (source.currency !== undefined && !/^[A-Z]{3}$/u.test(source.currency))
+            throw new Error('Invalid currency');
+        return { ...column,
+            ...(source.editable === undefined ? {} : { editable: source.editable }),
+            ...(source.format === undefined ? {} : { format: source.format }),
+            ...(source.currency === undefined ? {} : { currency: source.currency }),
+        };
+    });
+}
+export function formatSvarValue(value, column, locale) {
+    if (value == null)
+        return '—';
+    const format = column.format ?? 'plain';
+    if (format === 'boolean')
+        return value === true ? (locale.startsWith('zh') ? '是' : 'Yes') : value === false ? (locale.startsWith('zh') ? '否' : 'No') : '—';
+    if (format === 'number' || format === 'currency' || format === 'percent') {
+        if (typeof value !== 'number' || !Number.isFinite(value))
+            return '—';
+        const options = format === 'currency'
+            ? { style: 'currency', currency: column.currency ?? 'USD' }
+            : format === 'percent' ? { style: 'percent', maximumFractionDigits: 2 } : {};
+        return new Intl.NumberFormat(locale, options).format(value);
+    }
+    if (format === 'date' || format === 'datetime') {
+        if (typeof value !== 'string' && typeof value !== 'number')
+            return '—';
+        const date = new Date(value);
+        if (!Number.isFinite(date.getTime()))
+            return '—';
+        return new Intl.DateTimeFormat(locale, format === 'date' ? { dateStyle: 'medium', timeZone: 'UTC' } : { dateStyle: 'medium', timeStyle: 'short', timeZone: 'UTC' }).format(date);
+    }
+    return typeof value === 'string' || typeof value === 'boolean' || (typeof value === 'number' && Number.isFinite(value)) ? String(value) : '—';
+}
+export function buildSvarInteractiveColumns(columns, tree, editable, locale) {
+    return buildSvarColumns(columns, tree).map((column, index) => {
+        const source = columns[index];
+        if (!source)
+            throw new Error('Missing column');
+        return { ...column,
+            ...(source.editable && editable ? { editor: 'text' } : {}),
+            ...(source.format ? { template: (value) => formatSvarValue(value, source, locale) } : {}),
+        };
+    });
+}
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}
+export function resolveSvarCell(event, columns, index, primaryKey) {
+    const ev = record(event);
+    if (!ev || typeof ev['id'] !== 'string')
+        return;
+    const source = index.get(ev['id']);
+    const column = columns.find(item => svarColumnId(item.key) === ev['column'] && item.editable && item.key !== primaryKey && item.key !== 'id');
+    const id = source ? Object.getOwnPropertyDescriptor(source, primaryKey)?.value : undefined;
+    if (!column || (typeof id !== 'string' && typeof id !== 'number'))
+        return;
+    return { id, column };
+}
+export function parseSvarCellEdit(event, columns, index, primaryKey) {
+    const ev = record(event);
+    const cell = resolveSvarCell(event, columns, index, primaryKey);
+    if (!cell || !ev)
+        return;
+    const raw = ev['value'];
+    let value;
+    if (cell.column.editable === 'number') {
+        if (typeof raw !== 'string' && typeof raw !== 'number')
+            throw new Error('Invalid number');
+        if (typeof raw === 'string' && !raw.trim())
+            throw new Error('A number is required');
+        value = Number(raw);
+        if (!Number.isFinite(value))
+            throw new Error('Invalid number');
+    }
+    else {
+        if (typeof raw !== 'string')
+            throw new Error('Text is required');
+        value = raw;
+    }
+    return { id: cell.id, field: cell.column.key, value };
+}
+/** 引擎永远不能自行写业务数据；编辑只生成宿主请求，成功后由查询数据回填。 */
+export function installSvarInteractions(api, options) {
+    const index = () => svarRecordIndex(options.items(), options.primaryKey(), options.childrenKey());
+    for (const action of SVAR_BLOCKED_ACTIONS) {
+        if (!['open-editor', 'editor', 'update-cell'].includes(action))
+            api.intercept(action, () => false);
+    }
+    api.intercept('open-editor', event => {
+        if (!options.current() || !options.editable())
+            return false;
+        try {
+            if (!resolveSvarCell(event, options.columns(), index(), options.primaryKey()))
+                return false;
+        }
+        catch {
+            return false;
+        }
+    });
+    api.intercept('editor', () => { if (!options.current() || !options.editable())
+        return false; });
+    api.intercept('update-cell', event => {
+        if (options.current() && options.editable()) {
+            try {
+                const edit = parseSvarCellEdit(event, options.columns(), index(), options.primaryKey());
+                if (edit)
+                    options.edit(edit);
+            }
+            catch (failure) {
+                options.error(failure instanceof Error ? failure.message : 'Invalid edit');
+            }
+        }
+        return false;
+    });
+    api.intercept('select-row', () => { if (!options.current() || !options.selectable())
+        return false; });
+    api.on('select-row', () => {
+        if (!options.current() || !options.selectable())
+            return;
+        const selected = api.getState().selectedRows;
+        if (!Array.isArray(selected))
+            return;
+        try {
+            const records = index();
+            const ids = selected.flatMap(key => {
+                const source = typeof key === 'string' ? records.get(key) : undefined;
+                const id = source ? Object.getOwnPropertyDescriptor(source, options.primaryKey())?.value : undefined;
+                return typeof id === 'string' || typeof id === 'number' ? [id] : [];
+            });
+            if (ids.length > 100) {
+                options.error('Select at most 100 records');
+                return;
+            }
+            options.selection(ids);
+        }
+        catch {
+            options.selection([]);
+        }
+    });
+    api.intercept('sort-rows', event => {
+        if (!options.current())
+            return false;
+        if (options.server()) {
+            const next = nextSvarSort(event, options.columns(), options.sorters());
+            if (next)
+                options.sort(next);
+            return false;
+        }
+    });
+    api.intercept('filter-rows', event => {
+        if (!options.current())
+            return false;
+        if (options.server()) {
+            const next = nextSvarFilter(event, options.columns(), options.filters());
+            if (next)
+                options.filter(next);
+            return false;
+        }
+    });
+}
+export { svarRecordKey };

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

@@ -0,0 +1,40 @@
+import { type SvarColumn, type SvarRow } from './svar-grid-contract.js';
+import { type SvarRecordId } from './svar-grid-operations.js';
+export interface SvarRange {
+    readonly start: number;
+    readonly end: number;
+}
+export interface SvarWindowPage {
+    readonly data: readonly Record<string, unknown>[];
+    readonly total: number;
+}
+export interface SvarWindowSource {
+    readonly total: number;
+    /** 可信宿主负责数据契约和后端授权，范围使用从零开始、右端不含的索引。 */
+    readonly load: (request: SvarRange & {
+        readonly signal: AbortSignal;
+    }) => Promise<SvarWindowPage>;
+}
+export type SvarChildrenLoader = (request: {
+    readonly id: SvarRecordId;
+    readonly signal: AbortSignal;
+}) => Promise<readonly Record<string, unknown>[]>;
+export declare class SvarLoadCancelled extends Error {
+    constructor();
+}
+/** 单个网格的有界缓存：同键请求去重，AbortSignal 加请求所有者双重隔离。 */
+export declare function createSvarLoadCache<T>(copy: (value: T) => T, maxReady?: number, maxPending?: number): {
+    request: (key: string, load: (signal: AbortSignal) => Promise<T>) => Promise<T>;
+    clear: () => void;
+    invalidate(key: string): void;
+    abortPendingExcept(key: string): void;
+    dispose(): void;
+};
+export declare function snapshotSvarRecords(items: readonly Record<string, unknown>[], primaryKey?: string, childrenKey?: string): Record<string, unknown>[];
+export declare function checkedSvarRange(event: unknown, total: number): SvarRange;
+export declare function snapshotSvarWindow(page: SvarWindowPage, range: SvarRange, primaryKey?: string): SvarWindowPage;
+export declare function svarRowId(record: Record<string, unknown>, primaryKey: string): SvarRecordId;
+/** 合并已加载分支但不修改 Provider 记录；最后全树验证，拒绝跨分支重复 ID。 */
+export declare function mergeSvarBranches(items: readonly Record<string, unknown>[], branches: ReadonlyMap<string, readonly Record<string, unknown>[]>, primaryKey: string, childrenKey: string): Record<string, unknown>[];
+/** 占位子节点永远不能被选中或编辑；真正展开前由适配器拦截并加载。 */
+export declare function projectSvarLazyRows(records: readonly Record<string, unknown>[], columns: readonly SvarColumn[], primaryKey: string, childrenKey: string, hasChildrenKey: string, loaded: ReadonlyMap<string, readonly Record<string, unknown>[]>, opened: ReadonlySet<string>): SvarRow[];

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

@@ -0,0 +1,180 @@
+import { snapshotPlainData, decodeBaseRecord } from '@svadmin/core/schema';
+import { projectSvarRows } from './svar-grid-contract.js';
+import { svarRecordIndex, svarRecordKey } from './svar-grid-operations.js';
+export class SvarLoadCancelled extends Error {
+    constructor() { super('Grid request was superseded'); this.name = 'SvarLoadCancelled'; }
+}
+/** 单个网格的有界缓存：同键请求去重，AbortSignal 加请求所有者双重隔离。 */
+export function createSvarLoadCache(copy, maxReady = 32, maxPending = 8) {
+    const entries = new Map();
+    let disposed = false;
+    function clear() {
+        const pending = [...entries.values()];
+        entries.clear();
+        for (const entry of pending)
+            if (entry.kind === 'pending')
+                entry.controller.abort();
+    }
+    function trim() {
+        let count = [...entries.values()].filter(entry => entry.kind === 'ready').length;
+        for (const [key, entry] of entries) {
+            if (count <= maxReady)
+                break;
+            if (entry.kind === 'ready') {
+                entries.delete(key);
+                count--;
+            }
+        }
+    }
+    function request(key, load) {
+        if (disposed)
+            return Promise.reject(new SvarLoadCancelled());
+        const existing = entries.get(key);
+        if (existing?.kind === 'pending')
+            return existing.promise.then(copy);
+        if (existing?.kind === 'ready') {
+            entries.delete(key);
+            entries.set(key, existing);
+            return Promise.resolve(copy(existing.value));
+        }
+        if ([...entries.values()].filter(entry => entry.kind === 'pending').length >= maxPending) {
+            return Promise.reject(new Error('Too many simultaneous grid requests'));
+        }
+        const owner = {};
+        const controller = new AbortController();
+        const current = () => !disposed && !controller.signal.aborted && entries.get(key)?.owner === owner;
+        const promise = Promise.resolve().then(() => {
+            if (!current())
+                throw new SvarLoadCancelled();
+            return load(controller.signal);
+        }).then(value => {
+            if (!current())
+                throw new SvarLoadCancelled();
+            const cached = copy(value);
+            if (!current())
+                throw new SvarLoadCancelled();
+            entries.set(key, { kind: 'ready', owner, value: cached });
+            trim();
+            return copy(cached);
+        }).catch((failure) => {
+            const active = current();
+            if (entries.get(key)?.owner === owner)
+                entries.delete(key);
+            if (!active)
+                throw new SvarLoadCancelled();
+            throw failure;
+        });
+        entries.set(key, { kind: 'pending', owner, controller, promise });
+        return promise;
+    }
+    return {
+        request, clear,
+        invalidate(key) {
+            const entry = entries.get(key);
+            entries.delete(key);
+            if (entry?.kind === 'pending')
+                entry.controller.abort();
+        },
+        abortPendingExcept(key) {
+            for (const [id, entry] of entries) {
+                if (id !== key && entry.kind === 'pending') {
+                    entries.delete(id);
+                    entry.controller.abort();
+                }
+            }
+        },
+        dispose() { disposed = true; clear(); },
+    };
+}
+export function snapshotSvarRecords(items, primaryKey = 'id', childrenKey) {
+    const cloned = snapshotPlainData(items);
+    if (!Array.isArray(cloned) || cloned.length > 100_000)
+        throw new Error('Invalid grid records');
+    const records = cloned.map(value => decodeBaseRecord(value));
+    if (svarRecordIndex(records, primaryKey, childrenKey).size > 100_000)
+        throw new Error('Too many grid records');
+    return records;
+}
+export function checkedSvarRange(event, total) {
+    if (!Number.isSafeInteger(total) || total < 0 || total > 10_000_000)
+        throw new Error('Invalid total row count');
+    const row = event && typeof event === 'object' ? Object.getOwnPropertyDescriptor(event, 'row')?.value : undefined;
+    const start = row && typeof row === 'object' ? Object.getOwnPropertyDescriptor(row, 'start')?.value : undefined;
+    const end = row && typeof row === 'object' ? Object.getOwnPropertyDescriptor(row, 'end')?.value : undefined;
+    if (typeof start !== 'number' || typeof end !== 'number' || !Number.isSafeInteger(start) || !Number.isSafeInteger(end)
+        || start < 0 || end < start || end - start > 2048)
+        throw new Error('Invalid grid window');
+    return { start: Math.min(start, total), end: Math.min(end, total) };
+}
+export function snapshotSvarWindow(page, range, primaryKey = 'id') {
+    const total = page && typeof page === 'object' ? Object.getOwnPropertyDescriptor(page, 'total')?.value : undefined;
+    const data = page && typeof page === 'object' ? Object.getOwnPropertyDescriptor(page, 'data')?.value : undefined;
+    if (typeof total !== 'number' || !Number.isSafeInteger(total) || total < 0 || total > 10_000_000 || !Array.isArray(data)
+        || data.length !== Math.max(0, Math.min(range.end, total) - range.start))
+        throw new Error('Invalid window response');
+    return { data: snapshotSvarRecords(data, primaryKey), total };
+}
+export function svarRowId(record, primaryKey) {
+    const id = Object.getOwnPropertyDescriptor(record, primaryKey)?.value;
+    if (typeof id !== 'string' && typeof id !== 'number')
+        throw new Error('Invalid record ID');
+    svarRecordKey(id);
+    return id;
+}
+/** 合并已加载分支但不修改 Provider 记录；最后全树验证，拒绝跨分支重复 ID。 */
+export function mergeSvarBranches(items, branches, primaryKey, childrenKey) {
+    if (['__proto__', 'prototype', 'constructor'].includes(childrenKey) || !childrenKey)
+        throw new Error('Invalid children field');
+    const copied = snapshotSvarRecords(items, primaryKey, childrenKey);
+    let count = 0;
+    const ancestors = new Set();
+    function visit(records, depth) {
+        if (depth > 64)
+            throw new Error('Grid tree is too deep');
+        return records.map(record => {
+            if (++count > 100_000)
+                throw new Error('Too many grid records');
+            const key = svarRecordKey(svarRowId(record, primaryKey));
+            if (ancestors.has(key))
+                throw new Error('Cyclic grid branch');
+            const extra = branches.get(key);
+            const native = record[childrenKey];
+            const children = extra === undefined ? (Array.isArray(native) ? native.map(decodeBaseRecord) : undefined)
+                : snapshotSvarRecords(extra, primaryKey, childrenKey);
+            if (children === undefined)
+                return record;
+            ancestors.add(key);
+            const next = { ...record, [childrenKey]: visit(children, depth + 1) };
+            ancestors.delete(key);
+            return next;
+        });
+    }
+    const combined = visit(copied, 0);
+    svarRecordIndex(combined, primaryKey, childrenKey);
+    return combined;
+}
+/** 占位子节点永远不能被选中或编辑；真正展开前由适配器拦截并加载。 */
+export function projectSvarLazyRows(records, columns, primaryKey, childrenKey, hasChildrenKey, loaded, opened) {
+    if (!hasChildrenKey || ['__proto__', 'prototype', 'constructor'].includes(hasChildrenKey))
+        throw new Error('Invalid branch marker field');
+    const index = svarRecordIndex(records, primaryKey, childrenKey);
+    const rows = projectSvarRows(records, columns, primaryKey, childrenKey);
+    function visit(items) {
+        for (const row of items) {
+            if (row.data?.length) {
+                row.open = opened.has(row.id);
+                visit(row.data);
+            }
+            else {
+                const record = index.get(row.id);
+                const marker = record ? Object.getOwnPropertyDescriptor(record, hasChildrenKey)?.value : undefined;
+                if (marker === true && !loaded.has(row.id)) {
+                    row.data = [{ id: `pending:${row.id}` }];
+                    row.open = false;
+                }
+            }
+        }
+    }
+    visit(rows);
+    return rows;
+}

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

@@ -0,0 +1,37 @@
+import type { SvarColumn, SvarRow } from './svar-grid-contract.js';
+export type SvarRecordId = string | number;
+export interface SvarBatchResult {
+    readonly succeeded: SvarRecordId[];
+    readonly failed: {
+        id: SvarRecordId;
+        message: string;
+        uncertain: boolean;
+    }[];
+    readonly skipped: SvarRecordId[];
+    readonly cancelled: boolean;
+}
+export declare function svarRecordKey(id: SvarRecordId): string;
+/** 不解析引擎字符串推测业务 ID，必须从当前已授权记录建立映射。 */
+export declare function svarRecordIndex(items: readonly Record<string, unknown>[], primaryKey?: string, childrenKey?: string): Map<string, Record<string, unknown>>;
+export declare function checkedSvarSelection(ids: readonly SvarRecordId[], max?: number): SvarRecordId[];
+/** 整批预检后逐条重新授权；部分成功不是事务回滚，会话变更后停止派发。 */
+export declare function runSvarBatch(options: {
+    ids: readonly SvarRecordId[];
+    current: () => boolean;
+    authorize: (id: SvarRecordId) => Promise<boolean>;
+    write: (id: SvarRecordId) => Promise<unknown>;
+}): Promise<SvarBatchResult>;
+/** 导出只接受显式投影后的标量值；不调用对象的 toString/toJSON。 */
+export declare function svarCsv(rows: readonly SvarRow[], columns: readonly SvarColumn[]): string;
+export interface SvarExportSnapshot {
+    readonly ids: readonly SvarRecordId[];
+    readonly csv: string;
+}
+/** 在首次 await 之前冻结完整导出内容与所有后代 ID，避免检查与导出对象不一致。 */
+export declare function prepareSvarExport(items: readonly Record<string, unknown>[], columns: readonly SvarColumn[], primaryKey?: string, childrenKey?: string): SvarExportSnapshot;
+/** 只授权已经冻结的快照；禁止只检查树根，或在权限等待结束后读取新数据。 */
+export declare function authorizeSvarExport(snapshot: SvarExportSnapshot, options: {
+    current: () => boolean;
+    authorize: (action: 'list' | 'export', id: SvarRecordId | undefined) => Promise<boolean>;
+}): Promise<string>;
+export declare function downloadSvarCsv(content: string, resourceName: string): void;

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

@@ -0,0 +1,186 @@
+import { checkedSvarColumns, projectSvarRows, svarColumnId } from './svar-grid-contract.js';
+export function svarRecordKey(id) {
+    if ((typeof id !== 'string' || id.length === 0) && (typeof id !== 'number' || !Number.isFinite(id))) {
+        throw new Error('Invalid record ID');
+    }
+    return `${typeof id === 'number' ? 'n' : 's'}:${id}`;
+}
+/** 不解析引擎字符串推测业务 ID，必须从当前已授权记录建立映射。 */
+export function svarRecordIndex(items, primaryKey = 'id', childrenKey) {
+    const index = new Map();
+    const ancestors = new Set();
+    function visit(records, depth) {
+        if (!Array.isArray(records) || depth > 64)
+            throw new Error('Invalid grid tree');
+        for (const record of records) {
+            if (!record || typeof record !== 'object' || Array.isArray(record) || ancestors.has(record))
+                throw new Error('Invalid grid tree');
+            const descriptor = Object.getOwnPropertyDescriptor(record, primaryKey);
+            const id = descriptor && 'value' in descriptor ? descriptor.value : undefined;
+            if (typeof id !== 'string' && typeof id !== 'number')
+                throw new Error('Invalid record ID');
+            const key = svarRecordKey(id);
+            if (index.has(key))
+                throw new Error('Duplicate record ID');
+            index.set(key, record);
+            if (childrenKey) {
+                const childDescriptor = Object.getOwnPropertyDescriptor(record, childrenKey);
+                if (childDescriptor && !('value' in childDescriptor))
+                    throw new Error('Accessors are not allowed');
+                const children = childDescriptor?.value;
+                if (children !== undefined && !Array.isArray(children))
+                    throw new Error('Invalid child records');
+                if (Array.isArray(children)) {
+                    ancestors.add(record);
+                    visit(children, depth + 1);
+                    ancestors.delete(record);
+                }
+            }
+        }
+    }
+    visit(items, 0);
+    return index;
+}
+export function checkedSvarSelection(ids, max = 100) {
+    if (!Array.isArray(ids) || ids.length > max)
+        throw new Error(`Select at most ${max} records`);
+    const seen = new Set();
+    return ids.filter(id => {
+        const key = svarRecordKey(id);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+/** 整批预检后逐条重新授权；部分成功不是事务回滚，会话变更后停止派发。 */
+export async function runSvarBatch(options) {
+    const ids = checkedSvarSelection(options.ids);
+    const succeeded = [];
+    const failed = [];
+    let cancelled = false;
+    for (const id of ids) {
+        if (!options.current())
+            return { succeeded, failed, skipped: ids, cancelled: true };
+        const allowed = await options.authorize(id).catch(() => false);
+        if (!options.current())
+            return { succeeded, failed, skipped: ids, cancelled: true };
+        if (!allowed)
+            return { succeeded, failed: [{ id, message: 'Access denied', uncertain: false }], skipped: ids.filter(value => !Object.is(value, id)), cancelled: false };
+    }
+    for (const id of ids) {
+        if (!options.current()) {
+            cancelled = true;
+            break;
+        }
+        const allowed = await options.authorize(id).catch(() => false);
+        if (!options.current()) {
+            cancelled = true;
+            break;
+        }
+        if (!allowed) {
+            failed.push({ id, message: 'Access denied', uncertain: false });
+            continue;
+        }
+        try {
+            await options.write(id);
+            succeeded.push(id);
+        }
+        catch (error) {
+            const details = error && typeof error === 'object' ? Object.getOwnPropertyDescriptor(error, 'details')?.value : undefined;
+            const known = details && typeof details === 'object' ? Object.getOwnPropertyDescriptor(details, 'writeMayHaveSucceeded')?.value : undefined;
+            failed.push({ id, message: 'Operation failed; refresh before retrying', uncertain: known !== false });
+        }
+        if (!options.current()) {
+            cancelled = true;
+            break;
+        }
+    }
+    const attempted = new Set([...succeeded, ...failed.map(item => item.id)].map(svarRecordKey));
+    return { succeeded, failed, skipped: ids.filter(id => !attempted.has(svarRecordKey(id))), cancelled };
+}
+function hasFormulaPrefix(text) {
+    if (text.startsWith('\t') || text.startsWith('\r') || text.startsWith('\n'))
+        return true;
+    let offset = 0;
+    while (offset < text.length) {
+        const character = text[offset] ?? '';
+        if (text.charCodeAt(offset) <= 31 || /\s/u.test(character))
+            offset++;
+        else
+            break;
+    }
+    const first = text[offset];
+    return first !== undefined && '=+@-'.includes(first);
+}
+/** 导出只接受显式投影后的标量值；不调用对象的 toString/toJSON。 */
+export function svarCsv(rows, columns) {
+    const cell = (value) => {
+        let text = typeof value === 'string' ? value
+            : typeof value === 'number' && Number.isFinite(value) ? String(value)
+                : typeof value === 'boolean' ? String(value) : '';
+        if (typeof value === 'string' && hasFormulaPrefix(text))
+            text = `'${text}`;
+        return `"${text.replaceAll('"', '""')}"`;
+    };
+    const lines = [columns.map(column => cell(column.label)).join(',')];
+    let count = 0;
+    const ancestors = new Set();
+    function visit(records, depth) {
+        if (depth > 64)
+            throw new Error('Export tree is too deep');
+        for (const row of records) {
+            if (++count > 100_000 || ancestors.has(row))
+                throw new Error('Invalid or oversized export');
+            lines.push(columns.map(column => cell(row[svarColumnId(column.key)])).join(','));
+            if (row.data) {
+                ancestors.add(row);
+                visit(row.data, depth + 1);
+                ancestors.delete(row);
+            }
+        }
+    }
+    visit(rows, 0);
+    return `\uFEFF${lines.join('\r\n')}\r\n`;
+}
+/** 在首次 await 之前冻结完整导出内容与所有后代 ID，避免检查与导出对象不一致。 */
+export function prepareSvarExport(items, columns, primaryKey = 'id', childrenKey) {
+    const checked = checkedSvarColumns(columns);
+    const index = svarRecordIndex(items, primaryKey, childrenKey);
+    const ids = [];
+    for (const record of index.values()) {
+        const id = Object.getOwnPropertyDescriptor(record, primaryKey)?.value;
+        if (typeof id !== 'string' && typeof id !== 'number')
+            throw new Error('Invalid record ID');
+        ids.push(id);
+    }
+    const csv = svarCsv(projectSvarRows(items, checked, primaryKey, childrenKey), checked);
+    return Object.freeze({ ids: Object.freeze(ids), csv });
+}
+/** 只授权已经冻结的快照；禁止只检查树根，或在权限等待结束后读取新数据。 */
+export async function authorizeSvarExport(snapshot, options) {
+    async function check(action, id) {
+        if (!options.current())
+            throw new Error('Export scope changed');
+        const allowed = await options.authorize(action, id);
+        if (!options.current() || !allowed)
+            throw new Error('Export access denied');
+    }
+    await check('list');
+    await check('export');
+    for (const id of snapshot.ids)
+        await check('export', id);
+    if (!options.current())
+        throw new Error('Export scope changed');
+    return snapshot.csv;
+}
+export function downloadSvarCsv(content, resourceName) {
+    const url = URL.createObjectURL(new Blob([content], { type: 'text/csv;charset=utf-8' }));
+    const anchor = document.createElement('a');
+    anchor.href = url;
+    anchor.download = `${resourceName.replace(/[^a-zA-Z0-9_-]/gu, '_').slice(0, 80) || 'records'}.csv`;
+    document.body.append(anchor);
+    anchor.click();
+    anchor.remove();
+    setTimeout(() => URL.revokeObjectURL(url), 1000);
+}

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

@@ -0,0 +1,34 @@
+import type { Component } from 'svelte';
+import type { SvarInteractiveApi, SvarInteractiveEngineProps } from './svar-grid-interactions.js';
+export interface SvarManagedApi extends SvarInteractiveApi {
+    exec(action: string, params?: Record<string, unknown>): Promise<unknown>;
+    getState(): {
+        selectedRows?: unknown;
+        scrollTop?: number;
+        flatData?: Record<string, unknown>[];
+        focusCell?: {
+            row?: string | number;
+            column?: string | number;
+        };
+    };
+}
+export interface SvarManagedEngineProps extends Omit<SvarInteractiveEngineProps, 'init' | 'columns'> {
+    columns: (SvarInteractiveEngineProps['columns'][number] & {
+        hidden?: boolean;
+        cell?: Component<{
+            row: unknown;
+            column: unknown;
+        }>;
+    })[];
+    dynamic?: {
+        rowCount?: number;
+    };
+    init?: (api: SvarManagedApi) => void;
+}
+/** 两个公开 Grid 实例组成固定右侧面板，不读取或改写上游 Community 功能开关。 */
+export declare function createSvarPanePair(current: () => boolean): {
+    attach: (side: 0 | 1, api: SvarManagedApi) => void;
+    focus: (side: 0 | 1, row: string | number, column: string) => void;
+    get: (side: 0 | 1) => SvarManagedApi | undefined;
+    dispose(): void;
+};