@everygrid/grid 0.4.7

package/dist/src/core/Everygrid.d.ts

@@ -0,0 +1,568 @@
+import { GridHandle, GridEvents, RowKey, CellChange, RowChange } from './GridHandle';
+import { I18n } from '../i18n/I18n';
+import { default as React } from 'react';
+import { GridColumn, GridLoadProgress, GridOptions, GridPaginationConfig, GridVirtualScrollConfig, IEverygrid, KeyTree, ReloadOptions } from './types';
+export declare class Everygrid<T extends Record<string, unknown> = Record<string, unknown>> implements IEverygrid<T> {
+    static readonly POPUP_OVERLAY_CLASS = "everygrid-popup-overlay";
+    static readonly POPUP_CONTENT_CLASS = "everygrid-popup-content";
+    static readonly POPUP_CLOSE_CLASS = "everygrid-popup-close";
+    static readonly POPUP_CLOSE_HTML = "&times;";
+    private static instances;
+    private static _initializedTargets;
+    private static _configCache;
+    private static _targetRegistry;
+    private static _mounting;
+    static I18n: typeof I18n;
+    static options: GridOptions;
+    readonly options: GridOptions<T>;
+    hiddenFieldsMap: Map<string, Set<string>>;
+    displayColsMap: Map<string, Set<string>>;
+    exportState: Map<string, {
+        done: number;
+        total: number;
+    }>;
+    private _exportControllers;
+    pinnedColumns: Set<string>;
+    commaSeparatedFields: Set<string>;
+    linkFields: Set<string>;
+    isExcelViewMode: boolean;
+    sortConfig: Map<string, {
+        field: string;
+        direction: 'asc' | 'desc' | null;
+    }>;
+    columnWidths: Map<string, Map<string, number>>;
+    activeEditFields: Map<string, Set<string>>;
+    private _searchKeysCache;
+    activePopup: React.ReactElement | null;
+    activePopupData: {
+        data: unknown;
+    } | null;
+    activePopupTitle: string | null;
+    activePopupSubtitle: string | null;
+    /** Hover text for the subtitle strip (e.g. the full URL behind a file name). */
+    activePopupSubtitleTitle: string | null;
+    activePopupRow: unknown | null;
+    activePopupRowKey: string | null;
+    currentPage: Map<string, number>;
+    private originalDataMap;
+    private _editedKeys;
+    private _inserted;
+    private _deletedRows;
+    checkedValues: Map<string, Set<unknown>>;
+    private syncTimeoutId;
+    private roots;
+    private subscribers;
+    private domObserver;
+    _destroyed: boolean;
+    filterText: string;
+    private _wasmEngines;
+    private _wasmEngineReady;
+    private _wasmDataLoaded;
+    _wasmPageCache: Map<string, {
+        rows: unknown[];
+        total: number;
+    }>;
+    get wasmReady(): boolean;
+    /** Loading/indexing progress for one of this instance's targets. Mirrors the flags the toolbar
+     *  uses for its progress pill, but as plain data so a host (tab bar, shell) can render it too. */
+    loadProgress(containerId: string): GridLoadProgress;
+    /** Loading/indexing progress for a mounted target, or null if nothing is mounted under that id.
+     *  Lets a tab bar or shell show a grid's load progress while that grid's own view is hidden —
+     *  a keep-alive tab keeps streaming in the background, so its progress outlives its visibility. */
+    static getLoadProgress(id: string): GridLoadProgress | null;
+    private _serverTotal;
+    private _serverFetching;
+    _streamTotal: Map<string, number>;
+    _dataLimited: Map<string, {
+        shown: number;
+        total: number | null;
+    }>;
+    _streamRows: Map<string, Record<string, unknown>[]>;
+    _streamUrl: Map<string, string>;
+    _processing: Map<string, boolean>;
+    private _processingTimer;
+    private _filterSeq;
+    private _blockCache;
+    private _blockPending;
+    private _blockRenderScheduled;
+    private _loadChain;
+    private _loadSeq;
+    _wasmRawTotal: Map<string, number>;
+    _indexingAllRows: Map<string, Record<string, unknown>[]>;
+    _indexingStage: Map<string, 'indexing' | 'ready'>;
+    _indexingProgress: Map<string, number>;
+    _wasStreaming: Set<string>;
+    _loading: Set<string>;
+    /** Headers an origin may use to advertise the decoded size of a compressed body. */
+    private static readonly UNCOMPRESSED_LENGTH_HEADERS;
+    private static readonly LARGE_PAYLOAD_BYTES;
+    _dataSource: Map<string, string | (() => Promise<Record<string, unknown>[]>)>;
+    _reloading: Map<string, 'button' | 'silent'>;
+    private _reloadRun;
+    private _reloadNext;
+    private _discarding;
+    constructor(options: GridOptions<T>);
+    /** Unmounts every grid and forgets all loaded config — the next loadConfig re-fetches. */
+    /**
+     * Re-fetches a mounted grid's data from the source it was created with, in place.
+     *
+     * The instance method needs a handle the host usually does not keep; this is the same call for
+     * callers that only know the target id — what the toolbar's reload button does, by another name.
+     * Use it when the fetcher's own inputs have changed (a different row count, a new date range) and
+     * the grid should pick that up without being torn down and remounted.
+     */
+    static reload(id: string, opts?: ReloadOptions): Promise<void>;
+    /**
+     * A handle onto a mounted grid's data — `Everygrid.get('users').row(3).cell('score').set(90)`.
+     * Null when nothing is mounted under that id. See GridHandle.
+     */
+    /** The instance behind a target id (tests and tooling; the handle is the API). */
+    static instances_get<D extends Record<string, unknown> = Record<string, unknown>>(id: string): Everygrid<D>;
+    static get<D extends Record<string, unknown> = Record<string, unknown>>(id: string): GridHandle<D> | null;
+    static resetAutoInit(): void;
+    /**
+     * Resolves a config/data URL against the browser's base URI.
+     * Absolute paths ('/…') get the base path prefix, so the library works under a sub-path deploy.
+     */
+    private static _resolveUrl;
+    /**
+     * Loads config files and registers their targets — no DOM work, no engines, no data fetching.
+     * Mount the ones this screen actually shows with `mount()`.
+     *
+     * Cached per entry URL, so calling it from every screen costs one network round trip for the
+     * lifetime of the page. Config edits are picked up on reload, or explicitly via
+     * `invalidateConfig()` / `{reload: true}`.
+     *
+     * @param entryConfigUrl Path to the static entry config file (default: /everygrid.config.json)
+     * @param opts Options.
+     * @param opts.reload Bypass the cache and re-fetch
+     * @returns The target ids that are now registered (across every config file listed)
+     */
+    static loadConfig(entryConfigUrl?: string, opts?: {
+        reload?: boolean;
+    }): Promise<string[]>;
+    /** Drops cached config so the next loadConfig re-fetches. Already-mounted grids keep their config. */
+    static invalidateConfig(entryConfigUrl?: string): void;
+    private static _fetchConfig;
+    /**
+     * Mounts a grid into the element with the same id. Self-sufficient: it loads the root config
+     * (`/everygrid.config.json`, cached — one fetch app-wide) on demand, so a screen can just call
+     * `mount('a-grid', { fetcher })` with no separate `loadConfig()` bootstrap. If the config carries
+     * a target for this id, its settings apply; if not, the grid renders with defaults — config is
+     * for customization, not a requirement. The element must be in the DOM (nothing is allocated for a
+     * target this screen doesn't show).
+     *
+     * Idempotent: mounting an already-mounted target returns the live instance.
+     *
+     * @param targetId Element id; any id renders (a matching config target just customizes it)
+     * @param opts Mount options.
+     * @param opts.fetcher Data source for this target — a URL (streamed) or an async function
+     */
+    static mount<D extends Record<string, unknown> = Record<string, unknown>>(targetId: string, opts?: {
+        fetcher?: string | (() => Promise<Record<string, unknown>[]>);
+    }): Promise<Everygrid<D> | null>;
+    private static _doMount;
+    /**
+     * Preload one or more entry config files (each an `everygrid.config.json` listing its `configs`).
+     * Usually unnecessary — `createGrid` / `mount` read the root config on demand — but call it to
+     * point at a non-root path (a sub-app), or to load several entries up front. Cached per URL.
+     * Returns every registered target id. Also exported as a standalone `loadEverygridConfig`.
+     */
+    static loadEverygridConfig(entryConfigUrls?: string | string[]): Promise<string[]>;
+    /**
+     * Create a grid in the element with `id` — the ergonomic form of `mount`. Loads the root config on
+     * demand, applies a matching config target or renders with defaults, and returns the instance
+     * (null if the element isn't in the DOM). `fetcher` is a URL (streamed) or a `() => Promise<rows>`.
+     * Also exported as a standalone `createGrid`.
+     */
+    static createGrid<D extends Record<string, unknown> = Record<string, unknown>>(id: string, fetcher?: string | (() => Promise<Record<string, unknown>[]>)): Promise<Everygrid<D> | null>;
+    /**
+     * Tears a mounted grid down completely — React root, WASM engine, worker thread, timers — and
+     * makes the target mountable again. Call this when the screen owning the grid goes away.
+     *
+     * @returns true if a grid was mounted and is now gone
+     */
+    static unmount(targetId: string): boolean;
+    /**
+     * Loads config and mounts every target already present in the DOM.
+     *
+     * @deprecated Prefer `loadConfig()` + `mount()`. Targets whose element doesn't exist yet are
+     * skipped rather than waited for, so a screen that renders its container later must mount it
+     * itself.
+     * @param apiFetchers Map of data fetch functions or absolute URL strings keyed by target id
+     * @param entryConfigUrl Path to the static entry config file (default: /everygrid.config.json)
+     */
+    static autoInit(apiFetchers?: Record<string, string | (() => Promise<Record<string, unknown>[]>)>, entryConfigUrl?: string): Promise<void>;
+    /**
+     * Fetches a target's data from `url` and loads it in — streaming straight into WASM when
+     * the payload is large, otherwise parsing it as one JSON document.
+     *
+     * Shared by autoInit's first load and by reloadData(), so both take the identical path.
+     */
+    private _loadFromUrl;
+    /** Installs freshly loaded rows as the target's data and hands them to its WASM engine. */
+    private _setRows;
+    /**
+     * The single way rows reach an engine. Queues behind any load already running for the same
+     * target, and skips itself if a newer load was requested while it waited — by then its rows
+     * are stale and writing them would just undo the newer ones.
+     */
+    private _loadIntoEngine;
+    /**
+     * Patches edited rows into every ready engine in place, then refreshes the visible page.
+     *
+     * The alternative, `_loadIntoEngine`, is a full `setData`: it re-uploads and re-indexes the
+     * entire dataset to change one cell, and its progress callback puts the indexing bar on
+     * screen for every keystroke-sized edit. Rows are addressed by their position in
+     * `options.data`, which is the engine's raw row order.
+     */
+    private _syncRowsToEngines;
+    /**
+     * Runs one engine operation on every ready engine of this instance, then re-applies the filter
+     * so the page on screen reflects it. All row mutations — edit, insert, remove — go through here.
+     */
+    private _forEachReadyEngine;
+    /** The ids this instance renders into. */
+    private _targetIds;
+    /** Re-renders this instance's targets that are in the DOM. */
+    private _rerenderTargets;
+    /** Re-renders one target if it is in the DOM. */
+    private _rerender;
+    /** After a change to the change set: repaint the grid and tell listeners. */
+    private _afterChange;
+    /** Resolves with the target's engine once it exists, or null if it never shows up. */
+    private _awaitEngine;
+    /**
+     * Re-fetches a grid's data from the source it was created with and rebuilds its WASM
+     * index. No-op for grids whose data was passed in directly (nothing to re-fetch).
+     *
+     * `silent` marks a reload the host asked for rather than one the reader clicked, so the toolbar's
+     * reload button stays as it is. The data still loads with the usual loading UI — the button's
+     * spinner reports that *that button* is working, and spinning it for something the reader did not
+     * press reads as the grid reloading itself.
+     *
+     * `discard` says the incoming rows replace the old ones rather than refreshing them — a different
+     * query, not the same one again. Holding the previous rows on screen through that is showing an
+     * answer to a question nobody asked any more, so the body drops to the loading skeleton the way a
+     * first load does. Leave it off for a plain refresh, where the rows on screen stay valid until
+     * the new ones land.
+     */
+    reloadData(containerId: string, opts?: ReloadOptions): Promise<void>;
+    /** Resolves once the browser has painted — or at once in a hidden tab, where it never will. */
+    private static _afterPaint;
+    private _runReload;
+    /**
+     * Size in bytes of the body as the reader will actually deliver it, or 0 when unknown.
+     *
+     * `Content-Length` counts bytes *on the wire*, but `res.body` yields bytes *after* the
+     * browser has undone any `Content-Encoding`. For a compressed response the two differ by
+     * the compression ratio, so comparing read bytes against Content-Length would report
+     * nonsense (an 11x-compressed 1GB file would "finish" at 9%). When the body is encoded we
+     * only have a real total if the origin advertises the decoded size out of band, via either
+     * header below — `x-amz-meta-uncompressed-length` is what S3 returns for user metadata,
+     * and it must also be listed in the bucket's CORS ExposeHeaders to be readable here.
+     */
+    private static _decodedLength;
+    /**
+     * Streams a JSON array from a ReadableStream directly into the WASM engine.
+     *
+     * The raw fetch bytes are transferred to the worker (zero-copy) without ever being
+     * parsed on the main thread — the worker runs the brace-depth scan and feeds complete
+     * objects into WASM. This keeps the main thread free during multi-GB loads (no
+     * blank-screen freeze) and avoids holding the whole dataset as JS objects on the heap.
+     */
+    private static _streamJsonToWasm;
+    /**
+     * Pulls a just-streamed dataset back out of WASM and installs it as `options.data`.
+     *
+     * Streaming is chosen whenever the response length is unmeasurable, and a compressed CDN
+     * response (`Content-Encoding` with no comparable length header) always is — so small payloads
+     * routinely take the streaming path in production while taking the buffered one locally. Those
+     * targets would otherwise be left with an empty `options.data`, and everything keyed off it —
+     * updateData, the modification marker, resetCell — would silently no-op. Only done while the
+     * payload really is small; a genuinely large stream keeps WASM as its only copy.
+     */
+    private static _materializeStreamedRows;
+    /**
+     * Re-renders all grid instances that are currently in the DOM.
+     * Grids visible in the viewport are rendered immediately.
+     * Grids outside the viewport are rendered lazily via IntersectionObserver.
+     * Grids not attached to the DOM are skipped entirely.
+     */
+    static refreshAll(): void;
+    /**
+     * Re-render every mounted grid immediately — no viewport gating and no data re-fetch. Use this
+     * for changes that only affect rendering, like a locale switch (headers, labels, toolbar strings):
+     * `refreshAll` would miss grids scrolled out of view and needlessly reload data.
+     */
+    static rerenderAll(): void;
+    /**
+     * Switch the UI locale and refresh every mounted grid so headers, labels and toolbar strings
+     * update — the one call a host app needs on a language change. (Facade over `I18n.setLocale` +
+     * `rerenderAll`; use `I18n.setLocale` directly only if you want to set the locale without redraw.)
+     */
+    static setLocale(locale: 'ko' | 'en'): void;
+    private static readonly LOCALE_MESSAGE;
+    /**
+     * For grids embedded in an iframe / separate window, where the host app's global `setLocale`
+     * can't reach them: listen for a locale pushed by the parent (via {@link sendLocale}) and apply it.
+     * Call once inside the embedded page. Returns a function that removes the listener.
+     *
+     * @param opts.origin only accept messages from this origin (recommended for security). Omit to
+     *   accept any origin.
+     * @param opts.source only accept messages sent from this window (e.g. `window.parent`). Use it
+     *   when several places could post a locale and only one is authoritative — messages from any
+     *   other window are ignored, so it settles the "which sender wins" ambiguity. Omit to accept
+     *   from any window.
+     */
+    static listenForLocale(opts?: {
+        origin?: string;
+        source?: Window | null;
+    }): () => void;
+    /**
+     * Push the current locale to an embedded grid window (an iframe's `contentWindow`) whose page
+     * called {@link listenForLocale}. The parent/host side of the same handshake.
+     *
+     * @param target the embedded window to deliver to (e.g. an iframe's `contentWindow`).
+     * @param locale the locale to apply in the target — `'ko'` or `'en'`.
+     * @param targetOrigin restrict delivery to this origin (recommended); defaults to any (`'*'`).
+     */
+    static sendLocale(target: Window, locale: 'ko' | 'en', targetOrigin?: string): void;
+    closePopup(): void;
+    private _kindsCache;
+    private _dataVersion;
+    /** Marks the loaded data as changed in place (an edit, a reset, a commit). */
+    private _touchData;
+    private _columnKinds;
+    isColumnNumeric(field: string): boolean;
+    /** True when every non-empty value in the sampled rows is a boolean. */
+    isColumnBoolean(field: string): boolean;
+    isColumnDate(field: string): boolean;
+    isColumnObject(field: string): boolean;
+    getGridTitle(containerId: string): string | undefined;
+    resetColumnWidths(container: HTMLElement): void;
+    /** Whether the target shows its toolbar (search + actions); `toolbar: [{id, active: false}]` hides it. */
+    hasToolbar(containerId: string): boolean;
+    /** Whether the toolbar offers the "config" button (`toolbar: [{id, showConfig: true}]`). */
+    showsConfig(containerId: string): boolean;
+    /**
+     * The grid's effective configuration in the config-file shape, reduced to this one grid: its
+     * target entry with every per-grid option folded in, plus root-only options. Data, callbacks
+     * and fetchers are left out.
+     */
+    getTargetConfig(containerId: string): Record<string, unknown>;
+    /** Opens the grid's effective configuration in the popup viewer (the toolbar's "config" button). */
+    showConfig(container: HTMLElement): void;
+    getRowActions(containerId: string): {
+        insertRow: boolean;
+        deleteRow: boolean;
+    };
+    /** The live reference for a row the grid handed out (a WASM copy is matched by content). */
+    private _liveRef;
+    isRowInserted(row: T): boolean;
+    /**
+     * The rows inserted since load, in insertion order. A fresh array each call: the table
+     * components are memoised on their props, and the live list keeps its identity across an
+     * insert, so handing it out directly could leave a memoised table one row behind.
+     */
+    getInsertedRows(): T[];
+    /**
+     * Cheap on purpose — every rendered row asks. A deleted row is registered in _editedKeys, so
+     * the engine's copy of it maps to the live reference by content in one step; nothing scans the
+     * data.
+     */
+    isRowDeleted(row: T): boolean;
+    /**
+     * Adds a new row to the insert grid and returns it. Every data field starts empty unless
+     * `values` supplies it. The loaded data and its indices are untouched: the row joins the data
+     * (at the end) only on commit, and revert simply drops it.
+     */
+    insertRow(containerId: string, values?: Partial<T>, at?: number): T;
+    /**
+     * Marks a row deleted. It stays on screen struck through and can be restored; commit removes
+     * it. Deleting a row that was only just inserted simply drops it.
+     */
+    deleteRow(containerId: string, rowData: T): void;
+    /** Undoes a delete. */
+    restoreRow(containerId: string, rowData: T): void;
+    /** Physically removes rows from the data and the engine, and forgets everything about them. */
+    private _dropRows;
+    private _insertRowsToEngines;
+    private _removeRowsFromEngines;
+    /** The field whose value a checked row is remembered by (`checkbox.mapping`), if configured. */
+    getCheckboxMapping(containerId: string): string | undefined;
+    getCheckedValues(containerId: string): unknown[];
+    /** The rows currently checked, in data order. */
+    getCheckedRows(containerId: string): T[];
+    /**
+     * Checks or unchecks rows by their mapping values — the one path every checkbox change takes,
+     * from the UI or the API, so the `check` event sees all of them.
+     */
+    setChecked(containerId: string, values: unknown[], checked: boolean): void;
+    clearChecked(containerId: string): void;
+    private _listeners;
+    /** Subscribe to `cellChange` / `change`; returns the unsubscribe function. */
+    on<K extends keyof GridEvents<T>>(event: K, handler: GridEvents<T>[K]): () => void;
+    private _emit;
+    /** Fires `change` with the current change set; every edit, revert and commit ends here. */
+    private _emitChange;
+    /**
+     * The row's key per the `rowKey` config, else its index. Null when the key field is empty —
+     * an inserted row whose key has not been filled in yet — rather than the string "null".
+     */
+    _keyOf(containerId: string, row: T, index: number): RowKey | null;
+    _indexOfKey(containerId: string, key: RowKey): number;
+    /** Data index of a row handed out by the grid — a WASM copy is matched by content. */
+    _indexOfRow(row: T): number;
+    _originalOf(row: T): T;
+    _cellChanges(row: T): CellChange[];
+    /**
+     * Every row that differs from the loaded data: inserted, deleted, or edited so that it still
+     * differs from its original. Inserted rows carry their current values and no cell list; deleted
+     * rows their original and no cell list.
+     */
+    _changedRows(containerId: string): RowChange<T>[];
+    /**
+     * Accepts the current state as the new baseline: deleted rows are removed for good, inserted row
+     * become ordinary rows, and no row is modified any more.
+     */
+    commit(containerId: string): void;
+    /**
+     * Walks only the rows that have been edited, not the whole dataset. This runs on every render,
+     * including the synchronous one per scroll event, and over a million rows the full scan cost
+     * ~300ms a frame — the main thread fell that far behind the compositor, which is what the blank
+     * band during a scroll actually was. _editedKeys is maintained by every path that mutates a row.
+     */
+    checkHasChanges(): boolean;
+    /** Server-side paging: calls serverFetcher, loads the result into WASM, and re-renders */
+    fetchServerPage(containerId: string): Promise<void>;
+    /** Applies the current filter/sort state to the WASM engine, fetches the current page, caches result, then re-renders */
+    applyWasmFilter(containerId: string, suppressProcessing?: boolean): Promise<void>;
+    /**
+     * Fetches only the requested page from WASM, reusing the already-computed filtered/sorted
+     * result (no re-filter, no re-sort). Use this for page navigation when the filter and sort
+     * are unchanged — it slices the cached result in O(pageSize) instead of rescanning every row.
+     */
+    fetchWasmPage(containerId: string): Promise<void>;
+    /** @deprecated Replaced by applyWasmFilter */
+    applyWasmState(containerId: string): void;
+    /** For rendering: reads and returns the current page data directly from the WASM engine or JS stream rows */
+    getDisplayItems(containerId: string, items: T[]): T[];
+    /** @deprecated Cache invalidation is no longer needed since data is read directly from WASM. Kept for backward compatibility. */
+    invalidateSortCache(_containerId?: string): void;
+    /** Sets the text filter and re-renders the grid */
+    setFilter(text: string, container?: HTMLElement): void;
+    /** Total row count after filter is applied (used for pagination calculation) */
+    getFilteredTotal(containerId: string): number;
+    /** Parse filter text supporting && (AND) and || (OR) operators */
+    /**
+     * Lower-cased searchable text for a cell value, mirroring the WASM engine: nested objects/arrays
+     * are matched by their JSON serialization (lib.rs FieldVal::Json), not "[object Object]". Keeping
+     * this in sync is what makes the JS re-filter (used for the 'filtered' Excel export) select the
+     * same rows the visible WASM-filtered grid shows.
+     */
+    private static _searchText;
+    private _parseFilterExpr;
+    /** Filter/sort JS stream rows without WASM */
+    private _applyStreamFilter;
+    getPagination(containerId: string): GridPaginationConfig | undefined;
+    /**
+     * Rows this device can safely hold, for `dataLimit: 'auto'`. Derived from reported RAM
+     * (`navigator.deviceMemory`, Chromium only) and whether the device looks mobile. Conservative on
+     * purpose — a grid that loads beats one that shows everything and crashes the tab.
+     */
+    private static _deviceRowBudget;
+    getDataLimit(containerId: string): number | undefined;
+    /**
+     * Applies the row cap to an in-memory array. Returns the (possibly sliced) rows and records the
+     * cap so the banner can report it. A no-op when there is no cap or the data is within it.
+     */
+    private _capRows;
+    getVirtualScroll(containerId: string): GridVirtualScrollConfig | undefined;
+    /** Resolved block size for a virtualised target — the unit every engine fetch is aligned to. */
+    private _blockSize;
+    /**
+     * Rows for [start, end) of the current filtered result. Synchronous: whatever is cached comes
+     * back immediately, missing blocks come back as `undefined` holes and are fetched in the
+     * background. Callers render a placeholder for the holes; the fetch re-renders when it lands.
+     */
+    getRowsInRange(containerId: string, start: number, end: number): (T | undefined)[];
+    /** Fetches one block from the engine into the cache, then coalesces a re-render. */
+    private _fetchBlock;
+    /**
+     * Blocks land one by one but a fast scroll requests several at once, so renders are coalesced
+     * into a single pass instead of one per arriving block.
+     *
+     * A timeout rather than requestAnimationFrame: rAF does not run in a background tab or an
+     * occluded window, and this render is what makes arrived rows visible at all — not just a
+     * smoothing step. Waiting on a frame left the Excel preview showing its cold-start stand-in
+     * long after the real rows had been cached.
+     */
+    private _scheduleVirtualRender;
+    getEditableFields(containerId: string): string[];
+    getCurrentWidths(containerId: string): Map<string, number>;
+    getDataFields(containerId: string): string[];
+    getSearchKeys(containerId: string, fallbackSample?: unknown[]): KeyTree;
+    /** Aborts an in-flight worker export for this grid; the export's finally clears state + re-renders. */
+    cancelExport(containerId: string): void;
+    exportExcel(containerId: string, scope?: 'filtered' | 'all'): Promise<void>;
+    /**
+     * Localized display name for a field: `columnI18n[locale][containerId][field]`, falling back to
+     * the `common` bucket and then the raw field key. Locale comes from the global `I18n`, so a
+     * `setLocale` + re-render is all it takes to relabel. Queries never use this — they stay in field
+     * keys — so nothing downstream (WASM/matcher/highlight) needs to know about labels.
+     */
+    columnLabel(field: string, containerId: string): string;
+    private buildBaseColumns;
+    /** Mobile column keys from config (`mobileColumns`), or undefined when none is set for this grid. */
+    getMobileColumns(containerId: string): string[] | undefined;
+    getColumns(containerId: string, items: T[], isMobile?: boolean): GridColumn[];
+    /** The row-actions column (delete / restore per row), when the config asks for it. Insert lives in the toolbar. */
+    private _actionsColumn;
+    subscribe(callback: () => void): () => void;
+    notify(): void;
+    renderGrid(container: HTMLElement, _updatePinned?: boolean): void;
+    isCellModified(rowData: T, field: string): boolean;
+    syncRowHeights(container: HTMLElement): void;
+    showPopup(data: unknown, rowData?: unknown, title?: string, subtitle?: string, subtitleTitle?: string): void;
+    showTextPopup(text: string, rowData?: unknown, title?: string): void;
+    showEditPopup(rowData: Record<string, unknown>, field: string, data: unknown): void;
+    updateData(rowData: Record<string, unknown>, field: string, value: unknown): void;
+    /** The id this instance renders into — one instance serves one target under createGrid/mount. */
+    private _firstTargetId;
+    reset(container: HTMLElement): void;
+    /** Cancels every change of the target: edits undone, inserted rows dropped, deleted rows back. */
+    cancelAll(containerId: string): void;
+    resetCell(rowData: Record<string, unknown>, field: string, container: HTMLElement): void;
+    /** Puts one cell's loaded value back. */
+    cancelCell(containerId: string, rowData: Record<string, unknown>, field: string): void;
+    updateColumnWidth(containerId: string, field: string, width: number): void;
+    resetSort(container: HTMLElement): void;
+    toggleExcelViewMode(container: HTMLElement): void;
+    setCurrentPage(containerId: string, page: number, _container: HTMLElement): void;
+    getCurrentPage(containerId: string): number;
+    getTotalPages(containerId: string): number;
+    showColumnSelector(allFields: string[], container: HTMLElement): void;
+    showRowDetail(row: T, container: HTMLElement): void;
+    /** Opens the read-only list of every change since load (the toolbar's "diff" button). */
+    showDiff(container: HTMLElement): void;
+    showMobileColumnSelector(allFields: string[], container: HTMLElement): void;
+    showHiddenColumnSelector(container: HTMLElement): void;
+    /**
+     * A fresh load is a new baseline: edits against the previous rows have nothing to compare to.
+     *
+     * Nothing is copied here. originalDataMap used to hold a deep copy of every row (and a second
+     * full copy sat in a parallel array), which for a million rows meant two JSON round trips of
+     * the whole dataset at load and three times the memory. A row's original is now captured on its
+     * first edit — see the edit path — so the map only ever holds the rows that have changed.
+     */
+    private initOriginalDataMap;
+    /** The dataset as it was before any edits, built for onDataChange from the per-row snapshots. */
+    private _originalData;
+    private isDate;
+    private observeDOM;
+    private checkAndInit;
+    private init;
+    private getRoot;
+    destroy(): void;
+}

package/dist/src/core/ExcelView.d.ts

@@ -0,0 +1,28 @@
+import { default as XLSX } from 'xlsx-js-style';
+export declare const ExcelView: {
+    createExcelTable: (data: unknown[], limit?: number, isExcel?: boolean) => HTMLTableElement;
+    downloadExcel: (data: unknown[], gridId?: string) => void;
+    unionHeader: (flatRows: Record<string, unknown>[]) => string[];
+    buildXlsxBuffer: (flatRows: Record<string, unknown>[], header: string[]) => Uint8Array;
+    buildMultiSheetXlsx: (sheets: {
+        name: string;
+        rows: Record<string, unknown>[];
+        front?: string[];
+    }[]) => Uint8Array;
+    triggerDownload: (bytes: Uint8Array, fileName: string, mime: string) => void;
+    downloadTableAsExcel: (table: HTMLTableElement, gridId?: string) => void;
+    trimSheet: (ws: XLSX.WorkSheet | undefined) => void;
+    styleSheet: (ws: XLSX.WorkSheet | undefined) => void;
+    sanitizeSheetName: (name: string, used: Set<string>) => string;
+    arrayPaths: (rows: Record<string, unknown>[]) => string[][];
+    getAtPath: (obj: unknown, path: string[]) => unknown;
+    decomposeToRows: (value: unknown, keyPrefix: string, out: Record<string, unknown>[], scalarAsKey?: boolean) => void;
+    detectKeyField: (record: unknown) => string | undefined;
+    orderHeader: (header: string[], front: string[]) => string[];
+    sheetFromRows: (rows: Record<string, unknown>[], dense?: boolean, front?: string[]) => XLSX.WorkSheet | null;
+    appendChildSheets: (wb: XLSX.WorkBook, records: Record<string, unknown>[], paths: string[][], keyField: string | undefined, used: Set<string>, dense?: boolean) => void;
+    downloadRelationalExcel: (rows: unknown[], gridId?: string, keyField?: string) => void;
+    flattenObjectForExcel: (obj: unknown, prefix?: string, deep?: boolean) => Record<string, unknown>;
+    formatObject: (obj: unknown, indent?: number) => string;
+    getExcelRows: (data: unknown[]) => Record<string, unknown>[];
+};