snice 7.8.0 → 7.9.0

package/dist/components/table/snice-table.d.ts

@@ -4,6 +4,7 @@ import '../button/snice-button';
 import '../checkbox/snice-checkbox';
 import '../modal/snice-modal';
 import '../empty-state/snice-empty-state';
+import '../progress/snice-progress';
 import './snice-cell.ts';
 import './snice-cell-text.ts';
 import './snice-cell-number.ts';
@@ -33,7 +34,7 @@ import type { DetailPanelOptions } from './table-master-detail';
 import type { ToolbarOptions } from './table-toolbar';
 import type { TreeDataOptions } from './table-tree-data';
 import type { ColumnGroup } from './table-column-manager';
-import type { SniceTableElement, SelectionMode, ListViewRenderer } from './snice-table.types';
+import type { ColumnFit, SniceTableElement, SelectionMode, ListViewRenderer } from './snice-table.types';
 export declare class SniceTable extends HTMLElement implements SniceTableElement {
     striped: boolean;
     searchable: boolean;
@@ -84,6 +85,15 @@ export declare class SniceTable extends HTMLElement implements SniceTableElement
     editable: boolean;
     editMode: 'cell' | 'row';
     density: 'compact' | 'standard' | 'comfortable';
+    /**
+     * How the columns relate to the frame's width.
+     *
+     * `scroll` keeps every column at or above its `minWidth` and lets the frame
+     * scroll horizontally when they no longer fit. `squish` makes the frame the
+     * hard constraint instead: minimums relax, content ellipsises, and the table
+     * never scrolls sideways. See the `ColumnFit` docs in snice-table.types.ts.
+     */
+    columnFit: ColumnFit;
     headerFilters: boolean;
     quickFilter: boolean;
     rowReorder: boolean;
@@ -122,6 +132,8 @@ export declare class SniceTable extends HTMLElement implements SniceTableElement
     table: HTMLTableElement;
     thead: HTMLTableSectionElement;
     tbody: HTMLTableSectionElement;
+    /** Frame width the columns were last fitted to — see handleFrameResize. */
+    private lastFittedFrameWidth;
     getTableConfig(): any;
     getTableData(): any;
     private unsortedData;
@@ -133,9 +145,22 @@ export declare class SniceTable extends HTMLElement implements SniceTableElement
     private renderedRows;
     private settingSortedData;
     private settingDataImperative;
+    private reorderingRows;
     private renderQueued;
     private pendingHeaderRender;
     private pendingBodyRender;
+    private bodyRenderRetries;
+    private bodyRenderRetryQueued;
+    /**
+     * Requeue a body render whose target had not been committed yet. A frame is
+     * the right granularity — the shadow template commits between frames — and
+     * the paint is dropped again (silently, as before) once the retries run out.
+     *
+     * The retry CHAINS: a template that needs more than one frame to commit is
+     * the whole reason this exists, so a retry that still finds no <tbody> spends
+     * one more of the budget rather than giving the frame back and quitting.
+     */
+    private rearmBodyRender;
     private scheduleRender;
     private debouncedDataRequest;
     styles(): import("snice").CSSResult;
@@ -157,7 +182,14 @@ export declare class SniceTable extends HTMLElement implements SniceTableElement
     handleColumnsAssignment(): void;
     handleGroupByChange(): void;
     private syncGrouping;
-    handleDataAssignment(): void;
+    handleDataAssignment(oldVal?: any[]): void;
+    /**
+     * Drop the failed-load state: the ⚠️ message row's text and the `table--error`
+     * host class always move together, so they are cleared together and from one
+     * place. Idempotent, and deliberately does NOT render — every caller is either
+     * mid-delivery (the data watcher renders) or already renders itself.
+     */
+    private clearLoadError;
     handleDataChange(): void;
     /**
      * Refetch affordance: with rows on screen `loading` only dims the tbody, so
@@ -171,6 +203,28 @@ export declare class SniceTable extends HTMLElement implements SniceTableElement
     handleControlsChange(): void;
     handleControlledSort(): void;
     handleCurrentPageChange(): void;
+    /**
+     * Write a page number the display model just derived (a re-clamp after the
+     * row set shortened), WITHOUT re-entering the render scheduler.
+     *
+     * The three clamp sites all sit inside a display-model computation whose
+     * caller paints immediately afterwards with the clamped page — the ordinary
+     * body path slices with it and then renders the pager, the grouping and tree
+     * models return the clamped slice. Letting the @watch fire here queued a
+     * second, byte-identical body pass per delivery — the measured cost, and what
+     * the regression test pins. Suppressing the write's watcher makes the clamp
+     * cost zero extra passes and makes an oscillating clamp structurally unable
+     * to loop.
+     *
+     * All three sites are reachable only under `paginationMode === 'client'`, so
+     * the watcher's server branch (debouncedDataRequest, whose `loading = true`
+     * re-enters renderBody SYNCHRONOUSLY through the loading watcher — from the
+     * middle of a render) is not reachable from a clamp today. It is the reason
+     * to keep this guard rather than to drop the watcher suppression if a fourth
+     * clamp site ever lands outside that guard.
+     */
+    private clampingPage;
+    private clampCurrentPage;
     handlePageSizeChange(): void;
     handleDensityChange(): void;
     handleListChange(): void;
@@ -184,12 +238,73 @@ export declare class SniceTable extends HTMLElement implements SniceTableElement
     handleColumnReorderChange(): void;
     handleLazyLoadChange(): void;
     handleColumnMenuChange(): void;
+    /**
+     * Switching fit policy re-decides every unsized column's width, so the frame
+     * has to be re-fitted from scratch: the cached width would otherwise make the
+     * resize observer's "did the frame move?" guard swallow the very next pass.
+     */
+    handleColumnFitChange(): void;
     /** Column definitions in their actual painted order. Column state owns
      * visibility/order; pinned columns are partitioned to their physical edges
      * so right-pinned cells do not overlap later unpinned columns. */
     private getVisibleColumnDefinitions;
+    /**
+     * Cells one full-width row spans: every visible data column plus the tool
+     * columns that precede them. Group, aggregate, detail, empty-state, and
+     * virtual-spacer rows all measure themselves against this — a row that spans
+     * MORE than the table has invents columns, and `table-layout: fixed` then
+     * spends the frame's leftover width on the phantoms.
+     */
+    private getTotalColumnSpan;
+    /**
+     * Re-fit the columns nobody sized to the frame they are painted in.
+     *
+     * A column width is a CONTENT width, so the frame's budget has to be reduced
+     * by each column's own padding + border and by the fixed tool columns before
+     * it can be shared out. Both are read off the live header — the previous
+     * render's, on the first pass — rather than guessed, so the fitted table
+     * lands on the frame's width instead of a few pixels past it.
+     *
+     * Widths are written straight onto the header cells: under fixed layout the
+     * first row owns the column grid, so no body repaint is needed and this can
+     * run inside a resize observer without a render cascade.
+     */
+    private syncColumnWidthsToFrame;
+    /**
+     * Sticky geometry plus the visible affordance for a pinned cell.
+     *
+     * Freezing a column is only communicated if the reader can see where the
+     * frozen region ends, so the inner-most pinned column on each side carries
+     * the divider (`--edge`); the header additionally carries a pin marker, which
+     * is the only cue when the table happens to be wide enough not to scroll.
+     */
+    private applyPinnedCell;
+    /** The pin marker a frozen header carries, so pinning reads at any width. */
+    private static pinIndicator;
+    /**
+     * List mode is only "list mode" once a renderer is installed: `list` alone is
+     * a border treatment and still paints normal columnar cells. With a renderer
+     * every row collapses to one full-width cell, so there is no column geometry
+     * left for a header to label.
+     */
+    private usesListRowRenderer;
     renderHeader(): void;
     renderSortableHeader(column: any): string;
+    /**
+     * The single message row a zero-row body shows: loading spinner, load error,
+     * or the empty state (the `empty-state` slot cloned fresh, else the default
+     * placeholder). Returns null when there is data to render. Shared by the
+     * ordinary and virtualized paths — the virtualizer wipes the tbody itself, so
+     * it asks for this row rather than leaving a virtualized empty table blank.
+     */
+    /**
+     * The spinner both loading affordances draw. `snice-progress` paints its
+     * track at 20% alpha, which vanishes against a dark surface — the table pins
+     * `--progress-track-opacity` in its own stylesheet so the ring reads on any
+     * theme; the indicator arc keeps the primary color.
+     */
+    private createLoadingSpinner;
+    private createEmptyBodyRow;
     renderBody(): void;
     /**
      * When the host is taller than its rows, append an inert filler row so the
@@ -197,6 +312,20 @@ export declare class SniceTable extends HTMLElement implements SniceTableElement
      * data row, so column widths, pinning, and alignment track the table
      * engine natively. Removed entirely when content fills (or overflows) the
      * frame, restoring the plain last-row styling.
+     *
+     * INVARIANT — the filler may only consume space the frame ALREADY has; space
+     * that exists only BECAUSE of the filler must be given back. The filler is
+     * table content, and `@observe('resize', '.table-frame')` re-derives it from
+     * the frame's box, so on a host whose height is content-driven (the
+     * documented `:host { height: 100% }` resolving against an auto or
+     * max-content container — a stretched grid/flex item, a plain block parent)
+     * the filler is an input to the very measurement that produced it: the frame
+     * grows, the observer fires, the leftover computes positive again, and the
+     * table inflates by one slack per animation frame without bound. No static
+     * check distinguishes a content-driven frame from a genuinely sized one, so
+     * this measures instead: apply the filler, then confirm the frame kept its
+     * height. Any growth is self-inflicted and is subtracted from the filler;
+     * once nothing honest is left, the frame had no free space to fill at all.
      */
     private updateFillRow;
     private reconcileRows;
@@ -279,6 +408,14 @@ export declare class SniceTable extends HTMLElement implements SniceTableElement
     private selectorDebounceTimeout;
     private handleSelectorChange;
     updateRowSelectionState(): void;
+    /**
+     * The two selection reflections a row carries, written together: `data-selected`
+     * drives the CSS, `aria-selected` is the documented a11y contract ("selected
+     * data rows expose aria-selected"). The keyboard module stamps ARIA only on a
+     * full body render, so the delta paths below have to carry it themselves —
+     * otherwise a screen reader never hears an interaction-driven selection.
+     */
+    private stampRowSelection;
     private updateRowSelectionStateFor;
     updateSelectAllState(): void;
     toggleSort(columnKey: string, multiSort?: boolean): void;
@@ -289,6 +426,20 @@ export declare class SniceTable extends HTMLElement implements SniceTableElement
      */
     private applyLocalSortOrder;
     private sortLocalData;
+    /**
+     * Selection is anchored to the ROW, not to its position. `selectedRows` holds
+     * indices into `data`, so any reorder of that array — a local sort, or a
+     * re-delivery of the same row objects in another order — has to re-resolve
+     * them; otherwise the indices keep pointing at whatever row now occupies the
+     * slot and the user's checkmark silently jumps to a different row (the same
+     * remap the row-reorder/DnD path performs).
+     *
+     * Only a permutation is remapped: same length, same identities, no duplicates.
+     * A genuinely new dataset keeps the documented raw-index semantics untouched,
+     * and rows carrying no identity (duplicate objects) have nothing to anchor to.
+     * Call AFTER rebuildRowIndex() — the remap reads the fresh row-index map.
+     */
+    private remapSelectionAfterReorder;
     private dispatchRowSelectionChanged;
     private dispatchRowClicked;
     private dispatchLoadError;
@@ -316,6 +467,23 @@ export declare class SniceTable extends HTMLElement implements SniceTableElement
      * virtualized); otherwise it is the filtered data. Each descriptor carries
      * the logical index used for `data-index`, selection, and detail lookups.
      */
+    /**
+     * Re-derive the windowed row model and hand it to the virtualizer.
+     *
+     * `virtualRowsSnapshot` is the ONLY state the paint pipeline caches, and
+     * `renderRowRange` paints from it. Any caller that resolves a display index
+     * against a FRESH `getVirtualRows()` and then asks the virtualizer to paint
+     * (scrollToRow, the keyboard ensure-visible hook) must republish that model
+     * first, or it scrolls to an offset computed in one list and paints rows from
+     * another — the requested row never appears. Returns the fresh model so the
+     * caller indexes exactly what will be painted.
+     *
+     * `paint` false leaves the repaint to the caller (scrollToIndex refreshes the
+     * window itself). Those callers must not paint from here: the virtualizer's
+     * afterRender hook re-runs keyboard.refresh(), whose ensure-visible callback
+     * lands back in ensureKeyboardRowRendered — an unbounded recursion.
+     */
+    private syncVirtualRows;
     private getVirtualRows;
     private renderRowRange;
     /** Build a fragment of pinned rows for the given position (top/bottom). */