@svadmin/ui 0.72.0 → 0.74.0

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

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

@@ -0,0 +1,66 @@
+function own(event, key) {
+    return event && typeof event === 'object' ? Object.getOwnPropertyDescriptor(event, key)?.value : undefined;
+}
+function mirroredEvent(action, event) {
+    if (action === 'scroll-to') {
+        const top = own(event, 'top');
+        return typeof top === 'number' && Number.isFinite(top) && top >= 0 ? { top } : undefined;
+    }
+    if (action === 'open-row' || action === 'close-row') {
+        const id = own(event, 'id');
+        return typeof id === 'string' ? { id, nested: own(event, 'nested') === true } : undefined;
+    }
+    const key = own(event, 'key');
+    if (typeof key !== 'string')
+        return undefined;
+    if (action === 'sort-rows') {
+        // 上游首次排序可能省略 order，其公开语义为升序。
+        const order = own(event, 'order') ?? 'asc';
+        if (order !== 'asc' && order !== 'desc')
+            return undefined;
+        return { key, order, add: own(event, 'add') === true };
+    }
+    const value = own(event, 'value');
+    return typeof value === 'string' || value == null ? { key, value: value ?? '' } : undefined;
+}
+/** 两个公开 Grid 实例组成固定右侧面板，不读取或改写上游 Community 功能开关。 */
+export function createSvarPanePair(current) {
+    const panes = new Map();
+    let disposed = false;
+    let synchronizing = 0;
+    function attach(side, api) {
+        panes.set(side, api);
+        for (const action of ['scroll-to', 'sort-rows', 'filter-rows', 'open-row', 'close-row']) {
+            api.on(action, event => {
+                const peer = panes.get(side === 0 ? 1 : 0);
+                if (disposed || synchronizing || panes.get(side) !== api || !peer || !current())
+                    return;
+                const next = mirroredEvent(action, event);
+                if (!next)
+                    return;
+                if (action === 'scroll-to' && peer.getState().scrollTop === next['top'])
+                    return;
+                synchronizing++;
+                try {
+                    void Promise.resolve(peer.exec(action, next)).catch(() => { }).finally(() => { synchronizing--; });
+                }
+                catch {
+                    synchronizing--;
+                }
+            });
+        }
+        if (side === 1) {
+            const top = panes.get(0)?.getState().scrollTop;
+            if (typeof top === 'number' && top > 0)
+                void api.exec('scroll-to', { top }).catch(() => { });
+        }
+    }
+    function focus(side, row, column) {
+        if (disposed || !current())
+            return;
+        const api = panes.get(side);
+        if (api)
+            void api.exec('focus-cell', { row, column, eventSource: 'svadmin-pinned-navigation' }).catch(() => { });
+    }
+    return { attach, focus, get: (side) => panes.get(side), dispose() { disposed = true; panes.clear(); } };
+}

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

@@ -0,0 +1,18 @@
+import { type SvarRange, type SvarWindowPage } from './svar-grid-loading.js';
+export interface SvarLazyTree {
+    /** Resource field containing the parent record ID. */
+    readonly parentField: string;
+    readonly rootValue?: string | number | null;
+    readonly hasChildrenKey?: string;
+    /** A branch is rejected rather than silently truncated above this bound. Default: 10,000. */
+    readonly maxChildren?: number;
+}
+export type SvarResourcePageReader = (pagination: {
+    current: number;
+    pageSize: number;
+}) => Promise<SvarWindowPage>;
+/** Translate a zero-based exclusive grid window to the existing one-based Provider pagination. */
+export declare function loadSvarResourceWindow(range: SvarRange, pageSize: number, read: SvarResourcePageReader, signal: AbortSignal, primaryKey?: string): Promise<SvarWindowPage>;
+/** Load all children in bounded pages. Partial branches must never masquerade as complete trees. */
+export declare function loadSvarResourceChildren(pageSize: number, maxChildren: number, read: SvarResourcePageReader, signal: AbortSignal, primaryKey?: string, childrenKey?: string): Promise<readonly Record<string, unknown>[]>;
+export declare function appendSvarResourcePage(rows: readonly Record<string, unknown>[], page: SvarWindowPage, expectedTotal: number, primaryKey?: string): readonly Record<string, unknown>[];

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

@@ -0,0 +1,68 @@
+import { snapshotSvarRecords, snapshotSvarWindow, SvarLoadCancelled } from './svar-grid-loading.js';
+function checkSignal(signal) {
+    if (signal.aborted)
+        throw new SvarLoadCancelled();
+}
+function checkPageSize(pageSize) {
+    if (!Number.isSafeInteger(pageSize) || pageSize < 1 || pageSize > 1000)
+        throw new Error('Invalid resource page size');
+}
+function checkPage(page, start, size, primaryKey) {
+    return snapshotSvarWindow(page, { start, end: start + size }, primaryKey);
+}
+/** Translate a zero-based exclusive grid window to the existing one-based Provider pagination. */
+export async function loadSvarResourceWindow(range, pageSize, read, signal, primaryKey = 'id') {
+    checkPageSize(pageSize);
+    checkSignal(signal);
+    if (!Number.isSafeInteger(range.start) || !Number.isSafeInteger(range.end) || range.start < 0
+        || range.end < range.start || range.end > 10_000_000 || range.end - range.start > 2048)
+        throw new Error('Invalid resource window');
+    const first = Math.floor(range.start / pageSize);
+    const last = Math.max(first, Math.ceil(range.end / pageSize) - 1);
+    let total;
+    const rows = [];
+    for (let pageIndex = first; pageIndex <= last; pageIndex++) {
+        checkSignal(signal);
+        const page = checkPage(await read({ current: pageIndex + 1, pageSize }), pageIndex * pageSize, pageSize, primaryKey);
+        checkSignal(signal);
+        if (total !== undefined && total !== page.total)
+            throw new Error('Resource changed during window loading; refresh');
+        total = page.total;
+        rows.push(...page.data);
+        if ((pageIndex + 1) * pageSize >= total)
+            break;
+    }
+    const data = rows.slice(range.start - first * pageSize, range.end - first * pageSize);
+    return snapshotSvarWindow({ data, total: total ?? 0 }, range, primaryKey);
+}
+/** Load all children in bounded pages. Partial branches must never masquerade as complete trees. */
+export async function loadSvarResourceChildren(pageSize, maxChildren, read, signal, primaryKey = 'id', childrenKey = 'children') {
+    checkPageSize(pageSize);
+    checkSignal(signal);
+    if (!Number.isSafeInteger(maxChildren) || maxChildren < 1 || maxChildren > 100_000)
+        throw new Error('Invalid child limit');
+    let total;
+    const rows = [];
+    for (let pageIndex = 0;; pageIndex++) {
+        checkSignal(signal);
+        const page = checkPage(await read({ current: pageIndex + 1, pageSize }), pageIndex * pageSize, pageSize, primaryKey);
+        checkSignal(signal);
+        if (page.total > maxChildren)
+            throw new Error('Branch exceeds the configured child limit');
+        if (total !== undefined && total !== page.total)
+            throw new Error('Branch changed during loading; retry');
+        total = page.total;
+        rows.push(...page.data);
+        if (rows.length >= total)
+            return snapshotSvarRecords(rows, primaryKey, childrenKey);
+    }
+}
+export function appendSvarResourcePage(rows, page, expectedTotal, primaryKey = 'id') {
+    if (!Number.isSafeInteger(expectedTotal) || expectedTotal < 0 || expectedTotal > 10_000_000)
+        throw new Error('Invalid expected total');
+    if (page.total !== expectedTotal)
+        throw new Error('Resource changed during infinite loading; refresh');
+    if (rows.length + page.data.length > expectedTotal || (!page.data.length && rows.length < expectedTotal))
+        throw new Error('Invalid next resource page');
+    return snapshotSvarRecords([...rows, ...page.data], primaryKey);
+}

package/dist/components/svar-grid-resource-session.svelte.d.ts

@@ -0,0 +1,29 @@
+import { SvelteMap } from 'svelte/reactivity';
+import type { Filter, Sort } from '@svadmin/core';
+import type { SvarResourceReadRequest } from './SvarResourceRead.svelte';
+import { type SvarWindowPage } from './svar-grid-loading.js';
+import type { SvarRecordId } from './svar-grid-operations.js';
+/** Query workers remain descendants of the host AdminContext and QueryClientProvider. */
+export declare function createSvarResourceReads<Scope extends object>(options: {
+    scope: () => Scope;
+    current: (scope: Scope) => boolean;
+    authorize: (scope: Scope, parentId?: SvarRecordId) => Promise<boolean>;
+    resourceName: () => string;
+    dataScopeKey: () => string | number;
+    primaryKey: () => string;
+    childrenKey: () => string | undefined;
+}): {
+    requests: SvelteMap<number, SvarResourceReadRequest>;
+    read: (input: {
+        scope: Scope;
+        signal: AbortSignal;
+        pagination: {
+            current: number;
+            pageSize: number;
+        };
+        filters: Filter[];
+        sorters: Sort[];
+        parentId?: SvarRecordId;
+    }) => Promise<SvarWindowPage>;
+    cancelAll: () => void;
+};