@lavalogic/scoria 0.35.0 → 0.37.0

package/dist/Components/Table/Types/Context/SelectionState.svelte.d.ts

@@ -0,0 +1,260 @@
+import { SvelteMap } from 'svelte/reactivity';
+import type { ColumnDef } from '../Columns/Definitions/ColumnDef.svelte.js';
+import type { Primitive } from './TableInitOptions.js';
+/**
+ * Dependency surface that `SelectionState` reads from the surrounding
+ * `TableContext`. Every dependency is passed as a thunk so the sub-context
+ * never holds a direct reference to the parent; reactivity threads through
+ * `$derived` and `$effect` exactly as before the extraction.
+ *
+ * Splits cleanly into three groups:
+ *
+ *   1. Data-shape thunks (`getSortedData`, `getCurrentPageData`,
+ *      `getColumnDefs`) - used by `selectAllInCurrentPage`,
+ *      `allSelectedInCurrentPage`, `onHighlightAll`, and the per-row
+ *      key-cache walk in `updateSelectedItems`.
+ *
+ *   2. Pagination-window thunks (`getPageStartIndex`,
+ *      `getPageEndIndexExclusive`) - the page-window bounds. Returning
+ *      `undefined` from either thunk collapses to the full sortedData
+ *      range so this sub-context does not depend on the repo shape.
+ *
+ *   3. Identifier extraction (`getSelectionExtractor`) - the
+ *      caller-supplied `TableInitOptions.selectionExtractor`.
+ */
+export interface SelectionStateDeps<T extends object, RowIdType extends Primitive> {
+    /** Snapshot of the sorted, filtered row array (pre-pagination). */
+    getSortedData: () => ReadonlyArray<T>;
+    /** Snapshot of the row array currently displayed on the page. */
+    getCurrentPageData: () => ReadonlyArray<T>;
+    /** Live column-def array (used to locate the `RowSelectionDef` and
+     *  its optional `isSelectable` guard). */
+    getColumnDefs: () => ReadonlyArray<ColumnDef<T>>;
+    /** Page window start (inclusive). `undefined` means "no pagination"
+     *  - the sub-context flattens to `0`. */
+    getPageStartIndex: () => number | undefined;
+    /** Page window end (exclusive). `undefined` means "no pagination"
+     *  - the sub-context flattens to `sortedData.length`. */
+    getPageEndIndexExclusive: () => number | undefined;
+    /** The caller-supplied row-identifier extractor. */
+    getSelectionExtractor: () => (item: T) => RowIdType | Promise<RowIdType>;
+    /** Master gate from the discovered row-selection column. When
+     *  false, `selectionContains` short-circuits to `true` (legacy
+     *  behaviour - non-selectable tables treat every row as
+     *  "selected" for downstream code that branches on the selection
+     *  map). */
+    getIsSelectable: () => boolean;
+    /** Logger gate; mirrors the parent `TableContext.debug` field. */
+    getDebug: () => boolean;
+}
+/**
+ * Phase 6.5 god-object decomposition - sub-context that owns every
+ * selection + highlighting + key-cache concern previously held directly
+ * on `TableContext`:
+ *
+ * - `selectedItems` (the `SvelteMap<RowIdType, T>` of currently
+ *   selected rows, keyed by extractor id);
+ * - `invalidValues` (the parallel `SvelteMap` of rows currently
+ *   failing their per-cell validation);
+ * - `highlightedItems` (the visual-highlight `SvelteMap`, used for
+ *   the copy-to-clipboard "highlighted rows" flow);
+ * - `_keyCache` (a `WeakMap<T, RowIdType>` that memoises the
+ *   `selectionExtractor` result for each row reference;
+ *   `handleItemMutation` clears the entry when the parent's
+ *   `onEditCell` callback may have mutated the id field in place);
+ * - the pending-flush buffer (`_pendingSelectionChanges`) and its
+ *   debounced flush - preserves SvelteMap per-key reactivity and
+ *   avoids the per-toggle reactive cascade caught during Phase-5
+ *   Group 2;
+ * - `toggleSelected` / `setSelected` / `resetSelectedItems` /
+ *   `setSelectionMap` (consumer-facing writers);
+ * - `selectionContains` / `addInvalidValue` / `removeInvalidValue`;
+ * - `selectAllInCurrentPage`, `updateSelectedItems`,
+ *   `allSelectedInCurrentPage`;
+ * - `toggleHighlightedRow` / `resetHighlightedRows` /
+ *   `onHighlightAll` / `allHighlighted` / `hasHighlightedItems`;
+ * - `cachedKey(item)` (sync/async key memoisation);
+ * - `handleItemMutation` (the key-cache + selection-rebind half of
+ *   the pre-extraction `onEditCell`; the user-supplied edit callback
+ *   stays on `TableContext`).
+ *
+ * Effect lifecycle: the parent owns every `$effect`. The two effects
+ * that previously read these state slots (the post-pagination rebind
+ * and the `_allHighlighted` derivation) continue to live on
+ * `TableContext`, but they now call into this sub-context through
+ * `updateSelectedItems()` / `setAllHighlighted(...)` /
+ * `computeAllHighlightedInRange(...)` rather than mutating the state
+ * slots directly.
+ *
+ * `TableContext` retains delegating getters / setters / methods for
+ * every legacy surface so existing consumers need no migration.
+ */
+export declare class SelectionState<T extends object, RowIdType extends Primitive> {
+    private readonly _deps;
+    /** Selected rows keyed by id. Map entries are mutated in place so
+     *  the per-key reactivity tracking of `SvelteMap` survives every
+     *  toggle. Replacing the slot with a cloned map would invalidate
+     *  every `.has()` / `.get()` subscriber across all visible rows
+     *  (regression caught during Phase-5 Group 2). */
+    private _selectedItems;
+    /** Parallel `SvelteMap` of rows currently failing per-cell
+     *  validation. Public-mutable for source compatibility. */
+    private _invalidValues;
+    /** Visual-highlight `SvelteMap`, distinct from selection. */
+    private readonly _highlightedItems;
+    /**
+     * Memoises the `selectionExtractor` result for each row reference.
+     * Cleared by `handleItemMutation` immediately before the parent's
+     * `onEditCell` callback may mutate the id field in place.
+     *
+     * `WeakMap` so rows that get garbage-collected do not hold the
+     * cache entry forever; rows replaced by remote-paged refresh see
+     * their entry collected automatically.
+     */
+    private readonly _keyCache;
+    /**
+     * Pending selection changes - buffered and flushed as a single
+     * `SvelteMap` mutation pass to avoid per-toggle reactive cascades.
+     * Values: `null` = pending delete, `T` = pending insert.
+     */
+    private readonly _pendingSelectionChanges;
+    private _flushScheduled;
+    /** Tracks the async `allSelectedBySelectableMethod` result so the
+     *  `$derived` can return a synchronous value while a promise
+     *  resolves in the background. */
+    private _allSelectedAsync;
+    /** Last computed value of `_areAllHighlightedInRange` for the
+     *  current page. Mutated by the parent's `$effect` through
+     *  `setAllHighlighted` (the effect lives in `TableContext`
+     *  because it needs the parent's pagination-repo reads). */
+    private _allHighlighted;
+    /**
+     * @param deps thunks the sub-context reads from the parent.
+     *             Constructor-only - no implicit setup so the parent
+     *             remains in control of effect ownership and lifecycle.
+     */
+    constructor(deps: SelectionStateDeps<T, RowIdType>);
+    /** Currently-selected rows, keyed by `selectionExtractor(item)`. */
+    get selectedItems(): SvelteMap<RowIdType, T>;
+    /** Currently-invalid rows. */
+    get invalidValues(): SvelteMap<RowIdType, T>;
+    set invalidValues(v: SvelteMap<RowIdType, T>);
+    /** Currently-highlighted rows. */
+    get highlightedItems(): SvelteMap<RowIdType, T>;
+    /** `true` iff any row is currently highlighted. */
+    readonly hasHighlightedItems: boolean;
+    /**
+     * `true` iff every visible row on the current page is highlighted.
+     * Set by the parent's `$effect` through `setAllHighlighted` (the
+     * effect reads `paginationRepo.pageStartIndex` /
+     * `paginationRepo.pageEndIndexExclusive` and delegates the range
+     * computation to `computeAllHighlightedInRange`).
+     */
+    get allHighlighted(): boolean;
+    /** Setter for `_allHighlighted` driven by the parent's effect. */
+    setAllHighlighted(v: boolean): void;
+    /**
+     * Resolves the row identifier through the caller-supplied
+     * extractor, memoising the result in `_keyCache` so subsequent
+     * lookups on the same `T` reference avoid the extractor cost.
+     *
+     * Async extractors are supported: the returned promise is awaited
+     * by every call site through the `instanceof Promise` branch.
+     *
+     * Public so the parent's `originalRowIndices` / `getHighlightedRowData`
+     * flows can reach the cached key without piercing the boundary.
+     */
+    cachedKey(item: T): RowIdType | Promise<RowIdType>;
+    /**
+     * Invoked by the parent's `onEditCell`. Splits cleanly:
+     *
+     *   1. Resolves the row's old key (sync or async) and snapshots
+     *      its selection state.
+     *   2. If the row was selected, drops it from the selection map
+     *      so the post-edit insert (step 4) does not duplicate.
+     *   3. Invalidates the key-cache entry for the row reference -
+     *      the callback may mutate the id field in place.
+     *   4. Awaits the supplied callback (the user's
+     *      `TableInitOptions.onEditCell`).
+     *   5. Re-inserts the row under its new extractor result if it
+     *      was previously selected AND `isSelectable` is currently
+     *      true.
+     *
+     * The parent's `onEditCell` becomes a thin wrapper that passes
+     * the user-supplied callback in as the `runUserEditCallback`
+     * thunk.
+     */
+    readonly handleItemMutation: (item: T, runUserEditCallback: () => Promise<void> | void) => Promise<void>;
+    private _flushPendingSelectionChanges;
+    private _schedulePendingFlush;
+    /** Whether the row's selection key is currently in the selected
+     *  map. Returns `true` unconditionally when the table has no
+     *  selection column (legacy semantics). */
+    readonly selectionContains: (item: T) => boolean | Promise<boolean>;
+    /** Marks a row as invalid for downstream invalid-rows tracking. */
+    readonly addInvalidValue: (item: T) => void | Promise<void>;
+    /** Clears the invalid-state marker for a row. */
+    readonly removeInvalidValue: (item: T) => void | Promise<void>;
+    /**
+     * Toggles the selected state of a row. Both the selected map and
+     * the pending-flush buffer are consulted so a same-microtask
+     * double-toggle reflects the user's last action rather than the
+     * persisted state.
+     */
+    readonly toggleSelected: (item: T) => void | Promise<void>;
+    /** Sets the selected state of a row to the supplied value. */
+    readonly setSelected: (item: T, selected: boolean) => void | Promise<void>;
+    /** Replaces the entire selected-items map. */
+    readonly setSelectionMap: (set: SvelteMap<RowIdType, T>) => void;
+    /** Clears every selected row. */
+    readonly resetSelectedItems: () => void;
+    /**
+     * Resolve the page-window pair `[start, end)` from the dependency
+     * thunks, applying the `undefined` -> "no pagination" fallback.
+     * Exposed publicly so the parent's `_hasInvalidSelectedItems`
+     * effect can reach the same window without duplicating the
+     * fallback logic.
+     */
+    getPageWindow(): {
+        pageStartIndex: number;
+        pageEndIndexExclusive: number;
+    };
+    private allSelectedBySelectableMethod;
+    /**
+     * `true` iff every row on the current page is currently in the
+     * selection map (or covered by the `RowSelectionDef.isSelectable`
+     * gate). The async result is parked in `_allSelectedAsync` so a
+     * synchronous read remains possible.
+     */
+    readonly allSelectedInCurrentPage: boolean;
+    /**
+     * Toggles the selection state of every row on the current page.
+     * If every row is already selected, every row is deselected;
+     * otherwise every row that passes the optional `RowSelectionDef`
+     * `isSelectable` guard is added to the selection map.
+     */
+    readonly selectAllInCurrentPage: () => Promise<void>;
+    /**
+     * Rebinds every currently selected key to its row object on the
+     * current page. Called by the post-pagination effect so a paged
+     * remote refresh does not leave the selection map pointing at the
+     * old item references.
+     */
+    readonly updateSelectedItems: () => Promise<void>;
+    /** Toggles whether a row is highlighted (visually marked, not selected). */
+    readonly toggleHighlightedRow: (item: T) => void | Promise<void>;
+    /** Clears every highlighted row. */
+    readonly resetHighlightedRows: () => void;
+    /**
+     * If every row on the current page is highlighted, clears the
+     * highlight; otherwise highlights every row on the current page.
+     */
+    readonly onHighlightAll: () => void | Promise<void>;
+    /**
+     * Compute whether every row in `[pageStartIndex, pageEndIndexExclusive)`
+     * is currently highlighted. Called by the parent's `_allHighlighted`
+     * `$effect` so the effect retains its `paginationRepo` reads
+     * directly while the row-walk logic lives here.
+     */
+    computeAllHighlightedInRange(pageStartIndex: number, pageEndIndexExclusive: number): boolean | Promise<boolean>;
+}