@svgrid/grid 1.0.2 → 1.1.0

package/dist/scroll-sync.js

@@ -0,0 +1,86 @@
+import "./sv-grid-scrollbar";
+export function createScrollSync(ctx) {
+    function showTooltipFor(el, text) {
+        if (!text)
+            return;
+        if (ctx.tooltipTimer)
+            window.clearTimeout(ctx.tooltipTimer);
+        ctx.tooltipTimer = window.setTimeout(() => {
+            const rect = el.getBoundingClientRect();
+            const vw = window.innerWidth;
+            const vh = window.innerHeight;
+            const below = rect.bottom + 64 < vh;
+            // Clamp x so the 280px-wide tooltip doesn't fall off the viewport.
+            const x = Math.min(Math.max(rect.left + 6, 10), vw - 290);
+            const y = below ? rect.bottom + 6 : rect.top - 6;
+            ctx.tooltip = { text, x, y, below };
+        }, 250);
+    }
+    function hideTooltip() {
+        if (ctx.tooltipTimer) {
+            window.clearTimeout(ctx.tooltipTimer);
+            ctx.tooltipTimer = null;
+        }
+        ctx.tooltip = null;
+    }
+    function flushScheduledScrollSync() {
+        ctx.scrollSyncRaf = null;
+        ctx.scrollVersion += 1;
+        if (ctx.rowVirtualizationEnabled)
+            ctx.virtualizer.setScrollOffset(ctx.domToLogicalRowOffset(ctx.pendingScrollTop));
+        if (ctx.columnVirtualizationEnabled)
+            ctx.columnVirtualizer.setHorizontalOffset(ctx.pendingScrollLeft);
+    }
+    /**
+     * Sync the virtualizer to the user's scroll position once per frame.
+     *
+     * The browser's smooth-scroll animation fires a `scroll` event on
+     * every frame of the ~250 ms ramp after each wheel notch - so a
+     * single wheel notch produces ~16 calls to `onBodyScroll`. Without
+     * batching, each one ran a full virtualizer recalc + Svelte re-render
+     * synchronously, which (a) made the work pile up on heavy demos and
+     * (b) read on screen as "the grid keeps scrolling after the wheel
+     * stopped" because each scroll event ticked the rendered window one
+     * row at a time over a quarter-second.
+     *
+     * Batching to a single rAF flush per frame means each animation
+     * frame produces ONE virtualizer update at the latest known scroll
+     * position. Smooth-scroll still feels smooth (the browser is still
+     * animating `scrollTop`), but the grid's per-frame cost is bounded
+     * and the visible rows match the current `scrollTop` exactly when
+     * the wheel stops - no trailing updates.
+     */
+    function scheduleScrollSync(scrollTop, scrollLeft) {
+        ctx.pendingScrollTop = scrollTop;
+        ctx.pendingScrollLeft = scrollLeft;
+        if (ctx.scrollSyncRaf !== null)
+            return;
+        ctx.scrollSyncRaf = requestAnimationFrame(flushScheduledScrollSync);
+    }
+    function onBodyScroll(event) {
+        const container = event.currentTarget;
+        if (!container)
+            return;
+        if (ctx.columnMenuFor || ctx.operatorMenuFor)
+            ctx.closeMenus();
+        scheduleScrollSync(container.scrollTop, container.scrollLeft);
+        if (ctx.props.onScrollBottomReached) {
+            const { scrollTop, scrollHeight, clientHeight } = container;
+            const atBottom = scrollTop + clientHeight >= scrollHeight - 32;
+            if (atBottom && ctx.scrollBottomArmed) {
+                ctx.scrollBottomArmed = false;
+                ctx.props.onScrollBottomReached({ scrollTop, scrollHeight, clientHeight });
+            }
+            else if (!atBottom && !ctx.scrollBottomArmed) {
+                ctx.scrollBottomArmed = true;
+            }
+        }
+    }
+    return {
+        showTooltipFor,
+        hideTooltip,
+        flushScheduledScrollSync,
+        scheduleScrollSync,
+        onBodyScroll,
+    };
+}

package/dist/selection.d.ts

@@ -0,0 +1,26 @@
+import { type RowData, type TableFeatures } from "./index";
+import "./sv-grid-scrollbar";
+export declare function createSelection<TFeatures extends TableFeatures = TableFeatures, TData extends RowData = RowData>(ctx: any): {
+    isRowSelected: (rowId: string) => boolean;
+    toggleRowSelectionById: (rowId: string) => void;
+    toggleSelectAllRows: () => void;
+    setActiveCell: (rowIndex: number, colIndex: number) => void;
+    scrollActiveCellIntoView: (rowIndex: number, colIndex: number) => void;
+    setSelection: (rowIndex: number, colIndex: number) => void;
+    extendSelection: (rowIndex: number, colIndex: number) => void;
+    isCellInSelectedRange: (rowIndex: number, colIndex: number) => boolean;
+    getCellRangeEdges: (rowIndex: number, colIndex: number) => {
+        top: boolean;
+        bottom: boolean;
+        left: boolean;
+        right: boolean;
+    } | null;
+    isInFillPreview: (rowIndex: number, colIndex: number) => boolean;
+    findColumnById: (columnId: string) => any;
+    onCellPointerDown: (rowIndex: number, colIndex: number, event: PointerEvent) => void;
+    onCellPointerEnter: (rowIndex: number, colIndex: number) => void;
+    endDragSelection: () => void;
+    onWindowPointerMove: (event: PointerEvent) => void;
+    onCellClick: (rowIndex: number, colIndex: number) => void;
+    emitCellDoubleClick: (rowIndex: number, colIndex: number) => void;
+};

package/dist/selection.js

@@ -0,0 +1,387 @@
+// selection handlers extracted from the controller. Imperative event handlers
+// reading/writing controller state via the `ctx` handle; the reactive core
+// ($state/$derived/$effect) stays in the controller.
+import { getGridCellDomId, } from "./index";
+import "./sv-grid-scrollbar";
+import { getColumnBaseValue, isGroupRow, } from "./cell-values";
+export function createSelection(ctx) {
+    function isRowSelected(rowId) {
+        return Boolean(ctx.rowSelectionState[rowId]);
+    }
+    function toggleRowSelectionById(rowId) {
+        ctx.grid.setRowSelection((prev) => ({ ...prev, [rowId]: !prev[rowId] }));
+    }
+    function toggleSelectAllRows() {
+        const selectable = ctx.allRows.filter((row) => !isGroupRow(row));
+        const select = ctx.headerSelectionState !== "all";
+        ctx.grid.setRowSelection((prev) => {
+            const next = { ...prev };
+            for (const row of selectable) {
+                if (select)
+                    next[row.id] = true;
+                else
+                    delete next[row.id];
+            }
+            return next;
+        });
+    }
+    function setActiveCell(rowIndex, colIndex) {
+        ctx.userHasActivatedCell = true;
+        ctx.grid.setActiveCell({
+            rowIndex,
+            colIndex,
+            cellId: getGridCellDomId("svgrid", rowIndex, colIndex),
+        });
+        // Notify consumers (toolbars, ribbons) so they stay synced without
+        // having to listen on the DOM. Fired on EVERY active-cell move -
+        // click, arrow key, Tab, Enter, page-up/down, fill release.
+        if (ctx.props.onActiveCellChange) {
+            const column = ctx.allColumns[colIndex];
+            ctx.props.onActiveCellChange({
+                rowIndex,
+                colIndex,
+                columnId: column?.id ?? "",
+            });
+        }
+    }
+    function scrollActiveCellIntoView(rowIndex, colIndex) {
+        if (!ctx.scrollContainer)
+            return;
+        if (rowIndex < 0 || rowIndex >= ctx.allRows.length)
+            return;
+        if (colIndex < 0 || colIndex >= ctx.allColumns.length)
+            return;
+        if (ctx.rowVirtualizationEnabled) {
+            // Prefer the browser's native `scrollIntoView({ block: 'nearest' })`
+            // when the target row is already mounted. It does Excel-style
+            // minimum-scroll, respects the sticky thead via the
+            // `scroll-padding-top` we set on the scroll container, and runs
+            // on the compositor so it doesn't jump.
+            const root = ctx.scrollContainer;
+            const trEl = root.querySelector(`tr.sv-grid-row [data-svgrid-row="${rowIndex}"]`)?.closest('tr.sv-grid-row');
+            if (trEl) {
+                // `behavior: 'instant'` skips any user-agent smooth-scroll
+                // animation. Without it, fast key-repeat queues multiple
+                // overlapping animated scrolls and the viewport visibly
+                // overshoots / jumps as they collide.
+                trEl.scrollIntoView({
+                    block: 'nearest',
+                    inline: 'nearest',
+                    behavior: 'instant',
+                });
+            }
+            else if (ctx.rowScrollScalingActive) {
+                // Huge-list scroll scaling: the logical row offset does NOT map 1:1
+                // to a DOM scrollTop (the DOM scroll range is capped), so the plain
+                // offset math below would clamp and never reach the target. Map the
+                // logical offset into DOM space and align the row just under the
+                // sticky header. Rows are sub-pixel tall in DOM space here, so exact
+                // minimum-scroll is meaningless; once the row mounts the native
+                // `scrollIntoView` path above fine-tunes on the next navigation.
+                const headerHeight = ctx.theadEl?.offsetHeight
+                    ?? ctx.headerHeight ?? 0;
+                const rowLogicalTop = ctx.virtualizer.getOffsetForIndex(rowIndex);
+                const nextTop = Math.max(ctx.logicalToDomRowOffset(rowLogicalTop) - headerHeight, 0);
+                if (Math.abs(nextTop - root.scrollTop) > 0.5) {
+                    root.scrollTop = nextTop;
+                }
+            }
+            else {
+                // Row outside the rendered virtualizer window. Compute the
+                // scroll-coordinate target manually and set scrollTop. On the
+                // next render the row will mount and subsequent navigations
+                // use the native path above.
+                const currentTop = root.scrollTop;
+                const clientHeight = root.clientHeight;
+                const headerHeight = ctx.theadEl?.offsetHeight
+                    ?? ctx.headerHeight ?? 0;
+                const rowTopScroll = headerHeight + ctx.virtualizer.getOffsetForIndex(rowIndex);
+                const rowHeight = ctx.virtualizer.getSizeForIndex(rowIndex);
+                const rowBottom = rowTopScroll + rowHeight;
+                let nextTop = currentTop;
+                if (rowTopScroll < currentTop + headerHeight) {
+                    nextTop = rowTopScroll - headerHeight;
+                }
+                else if (rowBottom > currentTop + clientHeight) {
+                    nextTop = rowBottom - clientHeight;
+                }
+                nextTop = Math.max(nextTop, 0);
+                if (nextTop !== currentTop) {
+                    root.scrollTop = nextTop;
+                }
+            }
+        }
+        else {
+            // Non-virtualized mode: the cell's <td> is already in the DOM.
+            // Read its actual rect and bring it into view when it overlaps
+            // with the sticky header or is past the visible bottom. Without
+            // this branch, arrow keys move the active cell off-screen and
+            // the scrollbar never follows.
+            const cellEl = ctx.scrollContainer.querySelector(`td[data-svgrid-row="${rowIndex}"][data-svgrid-col="${colIndex}"]`);
+            if (cellEl) {
+                const headerHeight = ctx.theadEl?.offsetHeight ?? 0;
+                const containerRect = ctx.scrollContainer.getBoundingClientRect();
+                const cellRect = cellEl.getBoundingClientRect();
+                const cellTopInView = cellRect.top - containerRect.top;
+                const cellBotInView = cellRect.bottom - containerRect.top;
+                const clientHeight = ctx.scrollContainer.clientHeight;
+                let nextTop = ctx.scrollContainer.scrollTop;
+                if (cellTopInView < ctx.headerHeight) {
+                    nextTop = ctx.scrollContainer.scrollTop + cellTopInView - ctx.headerHeight;
+                }
+                else if (cellBotInView > clientHeight) {
+                    nextTop = ctx.scrollContainer.scrollTop + cellBotInView - clientHeight;
+                }
+                nextTop = Math.max(nextTop, 0);
+                if (nextTop !== ctx.scrollContainer.scrollTop) {
+                    ctx.scrollContainer.scrollTop = nextTop;
+                }
+            }
+        }
+        // Prefer the rendered item (cached size from the layout pass).
+        // Fall back to the column virtualizer's offset helper - that
+        // handles per-column variable widths correctly, unlike the
+        // previous flat `colIndex * fallbackWidth` estimate.
+        const item = ctx.renderedColumnItems.find((entry) => entry.index === colIndex);
+        const fallbackWidth = ctx.props.columnWidth ?? 140;
+        const cellStart = item?.start ?? ctx.columnVirtualizer?.getOffsetForIndex?.(colIndex) ?? (colIndex * fallbackWidth);
+        const cellSize = item?.size ?? ctx.columnVirtualizer?.getSizeForIndex?.(colIndex) ?? fallbackWidth;
+        const cellEnd = cellStart + cellSize;
+        const viewStart = ctx.scrollContainer.scrollLeft;
+        const viewEnd = viewStart + ctx.scrollContainer.clientWidth;
+        if (cellStart < viewStart) {
+            ctx.scrollContainer.scrollLeft = cellStart;
+        }
+        else if (cellEnd > viewEnd) {
+            ctx.scrollContainer.scrollLeft = cellEnd - ctx.scrollContainer.clientWidth;
+        }
+        // No inline scrollVersion bump - the `scroll` event triggers
+        // onBodyScroll which flushes via rAF, doing one batched update.
+    }
+    function setSelection(rowIndex, colIndex) {
+        if (!ctx.enableCellSelectionEffective)
+            return;
+        const point = { rowIndex, colIndex };
+        ctx.selectionRange = { anchor: point, focus: point };
+    }
+    function extendSelection(rowIndex, colIndex) {
+        if (!ctx.enableCellSelectionEffective)
+            return;
+        const anchor = ctx.selectionRange.anchor ?? { rowIndex, colIndex };
+        ctx.selectionRange = { anchor, focus: { rowIndex, colIndex } };
+    }
+    function isCellInSelectedRange(rowIndex, colIndex) {
+        const anchor = ctx.selectionRange.anchor;
+        const focus = ctx.selectionRange.focus;
+        if (!anchor || !focus)
+            return false;
+        const minRow = Math.min(anchor.rowIndex, focus.rowIndex);
+        const maxRow = Math.max(anchor.rowIndex, focus.rowIndex);
+        const minCol = Math.min(anchor.colIndex, focus.colIndex);
+        const maxCol = Math.max(anchor.colIndex, focus.colIndex);
+        return (rowIndex >= minRow &&
+            rowIndex <= maxRow &&
+            colIndex >= minCol &&
+            colIndex <= maxCol);
+    }
+    /**
+     * Returns which sides of the selection rectangle a cell sits on, for the
+     * Excel-style outline. Returns null when the cell is outside the range.
+     */
+    function getCellRangeEdges(rowIndex, colIndex) {
+        const anchor = ctx.selectionRange.anchor;
+        const focus = ctx.selectionRange.focus;
+        if (!anchor || !focus)
+            return null;
+        const minRow = Math.min(anchor.rowIndex, focus.rowIndex);
+        const maxRow = Math.max(anchor.rowIndex, focus.rowIndex);
+        const minCol = Math.min(anchor.colIndex, focus.colIndex);
+        const maxCol = Math.max(anchor.colIndex, focus.colIndex);
+        if (rowIndex < minRow ||
+            rowIndex > maxRow ||
+            colIndex < minCol ||
+            colIndex > maxCol) {
+            return null;
+        }
+        return {
+            top: rowIndex === minRow,
+            bottom: rowIndex === maxRow,
+            left: colIndex === minCol,
+            right: colIndex === maxCol,
+        };
+    }
+    /** Returns true when the given cell is inside the fill-drag preview
+     *  range BUT outside the original source range. Used to paint a
+     *  dashed-outline preview while the user is dragging the handle. */
+    function isInFillPreview(rowIndex, colIndex) {
+        const d = ctx.fillDrag;
+        if (!d)
+            return false;
+        const minR = Math.min(d.sourceMinRow, d.targetRow);
+        const maxR = Math.max(d.sourceMaxRow, d.targetRow);
+        const minC = Math.min(d.sourceMinCol, d.targetCol);
+        const maxC = Math.max(d.sourceMaxCol, d.targetCol);
+        if (rowIndex < minR ||
+            rowIndex > maxR ||
+            colIndex < minC ||
+            colIndex > maxC)
+            return false;
+        const inSource = rowIndex >= d.sourceMinRow &&
+            rowIndex <= d.sourceMaxRow &&
+            colIndex >= d.sourceMinCol &&
+            colIndex <= d.sourceMaxCol;
+        return !inSource;
+    }
+    /** Look up a column by id without depending on `buildApi`'s private
+     *  closure (those helpers don't exist at this scope). */
+    function findColumnById(columnId) {
+        return ctx.allColumns.find((c) => c.id === columnId);
+    }
+    function onCellPointerDown(rowIndex, colIndex, event) {
+        if (event.button !== 0)
+            return;
+        const row = ctx.allRows[rowIndex];
+        const column = ctx.allColumns[colIndex];
+        if (!row || !column || isGroupRow(row))
+            return;
+        const cellValue = ctx.getCellDisplayValue(row.id, column.id, getColumnBaseValue(row, column));
+        const isCheckboxColumn = column.columnDef.editorType === "checkbox" ||
+            typeof cellValue === "boolean";
+        if (isCheckboxColumn)
+            return; // let onCellClick toggle the checkbox
+        const active = ctx.grid.getState().activeCell;
+        ctx.activeAtPointerDown = active
+            ? { rowIndex: active.rowIndex, colIndex: active.colIndex }
+            : null;
+        if (event.shiftKey) {
+            extendSelection(rowIndex, colIndex);
+            setActiveCell(rowIndex, colIndex);
+        }
+        else {
+            setActiveCell(rowIndex, colIndex);
+            setSelection(rowIndex, colIndex);
+            ctx.isDraggingSelection = true;
+        }
+    }
+    function onCellPointerEnter(rowIndex, colIndex) {
+        if (!ctx.isDraggingSelection)
+            return;
+        const row = ctx.allRows[rowIndex];
+        if (!row || isGroupRow(row))
+            return;
+        extendSelection(rowIndex, colIndex);
+        setActiveCell(rowIndex, colIndex);
+    }
+    function endDragSelection() {
+        ctx.isDraggingSelection = false;
+        // Also commit a fill-handle drag if one was in progress - the user
+        // released the mouse, time to apply the pattern.
+        if (ctx.fillDrag)
+            ctx.onFillPointerUp();
+    }
+    function onWindowPointerMove(event) {
+        if (ctx.fillDrag) {
+            ctx.onFillPointerMove(event);
+            return;
+        }
+        if (!ctx.isDraggingSelection)
+            return;
+        // Safety: if no mouse button is held the drag is over (we may have
+        // missed pointerup because the user lifted outside the window).
+        if (event.buttons === 0) {
+            endDragSelection();
+        }
+    }
+    function onCellClick(rowIndex, colIndex) {
+        const row = ctx.allRows[rowIndex];
+        const column = ctx.allColumns[colIndex];
+        if (!row || !column)
+            return;
+        ctx.gridRootEl?.focus({ preventScroll: true });
+        if (isGroupRow(row)) {
+            setActiveCell(rowIndex, colIndex);
+            row.toggleExpanded?.();
+            return;
+        }
+        const baseValue = getColumnBaseValue(row, column);
+        const cellValue = ctx.getCellDisplayValue(row.id, column.id, baseValue);
+        // Emit the public click events for data cells/rows (before any
+        // checkbox-toggle / edit-entry side effects below).
+        ctx.props.onCellClick?.({
+            rowIndex,
+            colIndex,
+            columnId: column.id,
+            value: cellValue,
+            row: row.original,
+        });
+        ctx.props.onRowClick?.({
+            rowIndex,
+            columnId: column.id,
+            row: row.original,
+        });
+        const isCheckboxColumn = column.columnDef.editorType === "checkbox" ||
+            typeof cellValue === "boolean";
+        if (isCheckboxColumn) {
+            ctx.toggleBooleanCell(rowIndex, colIndex);
+            setActiveCell(rowIndex, colIndex);
+            setSelection(rowIndex, colIndex);
+            ctx.editingCell = null;
+            return;
+        }
+        // onCellPointerDown already set active+selection for data cells. Only
+        // decide whether to enter edit mode (click on the previously-active cell).
+        const wasActive = ctx.activeAtPointerDown !== null &&
+            ctx.activeAtPointerDown.rowIndex === rowIndex &&
+            ctx.activeAtPointerDown.colIndex === colIndex;
+        if (wasActive && ctx.editingEnabled) {
+            ctx.onCellDoubleClick(rowIndex, colIndex);
+            return;
+        }
+        ctx.editingCell = null;
+    }
+    /**
+     * Real double-click handler wired to the cell `ondblclick`. Emits the
+     * public double-click events (independent of editability) and then runs
+     * the edit-entry logic. Kept separate from `onCellDoubleClick` so the
+     * single-click-to-edit path in `onCellClick` does NOT emit a dblclick.
+     */
+    function emitCellDoubleClick(rowIndex, colIndex) {
+        const row = ctx.allRows[rowIndex];
+        const column = ctx.allColumns[colIndex];
+        if (row && column && !isGroupRow(row)) {
+            const value = ctx.getCellDisplayValue(row.id, column.id, getColumnBaseValue(row, column));
+            ctx.props.onCellDoubleClick?.({
+                rowIndex,
+                colIndex,
+                columnId: column.id,
+                value,
+                row: row.original,
+            });
+            ctx.props.onRowDoubleClick?.({
+                rowIndex,
+                columnId: column.id,
+                row: row.original,
+            });
+        }
+        ctx.onCellDoubleClick(rowIndex, colIndex);
+    }
+    return {
+        isRowSelected,
+        toggleRowSelectionById,
+        toggleSelectAllRows,
+        setActiveCell,
+        scrollActiveCellIntoView,
+        setSelection,
+        extendSelection,
+        isCellInSelectedRange,
+        getCellRangeEdges,
+        isInFillPreview,
+        findColumnById,
+        onCellPointerDown,
+        onCellPointerEnter,
+        endDragSelection,
+        onWindowPointerMove,
+        onCellClick,
+        emitCellDoubleClick,
+    };
+}

package/dist/spreadsheet.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Spreadsheet-style layout helpers — cell merging + per-cell borders.
+ *
+ * These are *layout-only* augmentations on top of `<SvGrid>`. They don't
+ * change the grid's data model, sorting, or filtering — they just decorate
+ * the rendered body cells. Bind the action to the wrapper around your
+ * SvGrid and pass merge / border specs; the helper observes DOM mutations
+ * and re-applies the layout whenever the grid re-renders.
+ *
+ * Limitations (worth knowing up front):
+ *   - Merges + borders index into the CURRENTLY-DISPLAYED rows (after
+ *     sort / filter), via the `data-svgrid-row` index the grid sets on
+ *     every body cell. If your data sorts or filters, recompute the
+ *     specs against the new display order.
+ *   - Merges use real `colspan` / `rowspan` plus `display:none` on
+ *     covered TDs. Column widths come from the inline styles SvGrid
+ *     emits on each TD; we don't fight those.
+ *   - For long row-merges across a virtualised window, only rows that
+ *     are actually rendered get the rowspan applied. Disable
+ *     virtualisation on grids that need a continuous merge.
+ */
+/** A single edge of a cell border. */
+export type BorderSpec = {
+    /** Thickness in pixels. Default 2. */
+    width?: number;
+    /** CSS border-style. Default 'solid'. */
+    style?: 'solid' | 'dashed' | 'dotted' | 'double';
+    /** CSS color. Falls back to currentColor (i.e. text color). */
+    color?: string;
+};
+/** A merge declaration. The cell at (rowIndex, columnId) is the ORIGIN;
+ *  it spans `colspan` columns to the right + `rowspan` rows downward.
+ *  Covered cells are hidden so the origin visually fills the region. */
+export type MergeSpec = {
+    /** Display-row index — the same value the grid puts on
+     *  `data-svgrid-row`. After sorting/filtering, recompute the spec
+     *  against the new display order. */
+    rowIndex: number;
+    columnId: string;
+    /** Default 1. */
+    rowspan?: number;
+    /** Default 1. */
+    colspan?: number;
+};
+/** Borders for one cell. Edges left unset render as the default
+ *  cell border (i.e. no override). */
+export type CellBorderSpec = {
+    rowIndex: number;
+    columnId: string;
+    top?: BorderSpec;
+    right?: BorderSpec;
+    bottom?: BorderSpec;
+    left?: BorderSpec;
+};
+/** What the Svelte action receives. Pass new values to update; pass
+ *  `null` / empty arrays to clear. */
+export type SpreadsheetActionOptions = {
+    merges?: ReadonlyArray<MergeSpec> | null;
+    borders?: ReadonlyArray<CellBorderSpec> | null;
+    /** Column id order the grid uses, in left-to-right order. Required
+     *  to translate `colspan` into the right set of covered column ids.
+     *  Pass `columns.map((c) => c.id)` from the consumer. */
+    columnOrder: ReadonlyArray<string>;
+};
+/** Svelte action. Attach to the element that hosts your `<SvGrid>` so
+ *  the action can watch its DOM for re-renders.
+ *
+ * ```svelte
+ * <div use:spreadsheetLayout={{ merges, borders, columnOrder }}>
+ *   <SvGrid {data} {columns} ... />
+ * </div>
+ * ```
+ *
+ * The action re-applies the layout whenever the grid's body mutates
+ * (new rows, column reorder, virtualization scroll) and whenever the
+ * options change. */
+export declare function spreadsheetLayout(node: HTMLElement, opts: SpreadsheetActionOptions): {
+    update(next: SpreadsheetActionOptions): void;
+    destroy(): void;
+};