@svadmin/ui 0.72.0 → 0.74.0

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;
+        }
+    });
+}

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

@@ -0,0 +1,54 @@
+import type { SvarColumn, SvarEngineColumn, SvarGridApi, SvarGridEngineProps, SvarSort, SvarTextFilter } from './svar-grid-contract.js';
+import { svarRecordKey, type SvarRecordId } from './svar-grid-operations.js';
+export type SvarValueFormat = 'plain' | 'number' | 'currency' | 'percent' | 'date' | 'datetime' | 'boolean';
+export interface SvarInteractiveColumn extends SvarColumn {
+    readonly editable?: 'text' | 'number';
+    readonly format?: SvarValueFormat;
+    readonly currency?: string;
+}
+export interface SvarCellEdit {
+    readonly id: SvarRecordId;
+    readonly field: string;
+    readonly value: string | number;
+}
+export interface SvarInteractiveApi extends SvarGridApi {
+    on(action: string, callback: (event: unknown) => void): void;
+    getState(): {
+        selectedRows?: unknown;
+    };
+}
+export interface SvarInteractiveEngineProps extends Omit<SvarGridEngineProps, 'init' | 'columns'> {
+    columns: (SvarEngineColumn & {
+        editor?: 'text';
+        template?: (value: unknown) => string;
+    })[];
+    selectedRows?: (string | number)[];
+    init?: (api: SvarInteractiveApi) => void;
+}
+export declare function checkedSvarInteractiveColumns(columns: readonly SvarInteractiveColumn[]): SvarInteractiveColumn[];
+export declare function formatSvarValue(value: unknown, column: SvarInteractiveColumn, locale: string): string;
+export declare function buildSvarInteractiveColumns(columns: readonly SvarInteractiveColumn[], tree: boolean, editable: boolean, locale: string): SvarInteractiveEngineProps['columns'];
+export declare function resolveSvarCell(event: unknown, columns: readonly SvarInteractiveColumn[], index: Map<string, Record<string, unknown>>, primaryKey: string): {
+    id: SvarRecordId;
+    column: SvarInteractiveColumn;
+} | undefined;
+export declare function parseSvarCellEdit(event: unknown, columns: readonly SvarInteractiveColumn[], index: Map<string, Record<string, unknown>>, primaryKey: string): SvarCellEdit | undefined;
+/** 引擎永远不能自行写业务数据；编辑只生成宿主请求，成功后由查询数据回填。 */
+export declare function installSvarInteractions(api: SvarInteractiveApi, options: {
+    current: () => boolean;
+    columns: () => readonly SvarInteractiveColumn[];
+    items: () => readonly Record<string, unknown>[];
+    primaryKey: () => string;
+    childrenKey: () => string | undefined;
+    server: () => boolean;
+    sorters: () => readonly SvarSort[];
+    filters: () => readonly SvarTextFilter[];
+    sort: (sorters: SvarSort[]) => void;
+    filter: (filters: SvarTextFilter[]) => void;
+    editable: () => boolean;
+    edit: (edit: SvarCellEdit) => void;
+    selectable: () => boolean;
+    selection: (ids: SvarRecordId[]) => void;
+    error: (message: string) => void;
+}): void;
+export { svarRecordKey };

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[];