bitboss-ui 3.0.0-beta.2 → 3.0.0-beta.20

package/dist/components/BbTable/types.d.ts

@@ -25,6 +25,13 @@ export type ItemKey<Item = any> = NestedPaths<Item> | (string & {});
  * inferred per column, so the conditional has literal types to distribute over.
  */
 export type ReservedColumnKey = 'actions' | 'select';
+/**
+ * Suffixes of the header affix slots (`header:prepend` / `header:append` and
+ * their per-column `header:<key>:prepend/append` variants). A column key that
+ * normalizes to one of these shadows the table-wide slot name; the table-wide
+ * interpretation wins and dev builds warn.
+ */
+export type HeaderAffixSuffix = 'prepend' | 'append';
 /**
  * Skeleton placeholder style for the loading state.
  * Matches the expected content type for a better loading experience.
@@ -80,17 +87,17 @@ export type BbTableColumn<Item = any> = BaseColumn<Item> & {
      */
     sorted?: 'asc' | 'desc';
     /**
-     * Classes this column contributes to the whole row's `<tr>`. Every column's
+     * Classes this column contributes to the whole row element. Every column's
      * `rowClass` is accumulated with the table-level `rowClass` prop and applied
      * together. Can also be a function of the cell's content for dynamic values.
      */
     rowClass?: ColumnClasses<Item>;
     /**
-     * Defines the classes to be passed to the `<td>` elements. Can also be a function for dynamic values.
+     * Defines the classes to be passed to this column's data cells. Can also be a function for dynamic values.
      */
     tdClass?: ColumnClasses<Item>;
     /**
-     * Defines the classes to be passed to the `<th>`.
+     * Defines the classes to be passed to this column's header cell.
      */
     thClass?: Classes;
     /**
@@ -112,7 +119,11 @@ export type BbTableColumn<Item = any> = BaseColumn<Item> & {
      *   region.
      *
      * When omitted the column chains from the previous column's end to the next
-     * whole snap point (a one-to-one inheritance by index).
+     * whole snap point (a one-to-one inheritance by index). The last column
+     * always runs to the end of the parent's data region (as if `[start, -1]`)
+     * unless it declares a `width` or an explicit pair, so a table with fewer
+     * columns than its parent widens its last content cell across the parent's
+     * trailing tracks rather than its actions cell.
      */
     snap?: number | [start: number, end: number];
 };
@@ -120,6 +131,8 @@ export type BbTableProps<Item = any> = {
     /**
      * Function that accepts the columns and the current item as
      * arguments and returns a label to be used for accessibility purposes.
+     * The cells arrive in RENDER order (they follow `order`, so the
+     * label reads like the row) — look a cell up by `key`, never by position.
      */
     accessibleLabel?: (columns: MappedCell[], item: any) => string;
     /**
@@ -136,31 +149,6 @@ export type BbTableProps<Item = any> = {
      * @defaultValue `'left'`
      */
     align?: 'left' | 'center' | 'right';
-    /**
-     * Stable id for this table's width context. When omitted a unique id is
-     * generated. Nested tables use the nearest ancestor id to inherit widths.
-     */
-    id?: string;
-    /**
-     * Opt a nested table into inheriting its column widths from an ancestor
-     * table's matching tracks (accounting for `select`/`actions` columns). This
-     * also forces `table-layout: fixed`, so it is **off by default** — a nested
-     * table renders independently unless you ask for alignment.
-     * - `false` (the default): do not inherit; size independently.
-     * - `true`: inherit from the nearest ancestor table.
-     * - a table id (string): inherit from the specific ancestor in the chain with
-     *   that id rather than the immediate parent. Use this when an intermediate
-     *   table has a different column count, so the extra columns would otherwise
-     *   misalign against it.
-     */
-    inheritColumnWidths?: boolean | string;
-    /**
-     * Hides the "Select all" checkbox that selectable multi-row tables
-     * display by default.
-     *
-     * @defaultValue `false`
-     */
-    disableSelectAll?: boolean;
     /**
      * Caption that describes the content of the table. Used for accessibility purposes.
      */
@@ -193,6 +181,18 @@ export type BbTableProps<Item = any> = {
      * Disables the component
      */
     disabled?: boolean;
+    /**
+     * Hides the "Select all" checkbox that selectable multi-row tables
+     * display by default.
+     *
+     * @defaultValue `false`
+     */
+    disableSelectAll?: boolean;
+    /**
+     * Boolean that defines whether to display or hide the caption.
+     * By default is true and the caption is hidden.
+     */
+    displayCaption?: boolean;
     /**
      * After every load (initial, `dependencies` refetch or a change of the
      * `items` array) prunes the row-keyed models of values whose row is no
@@ -210,12 +210,17 @@ export type BbTableProps<Item = any> = {
      */
     enforceCoherence?: boolean;
     /**
-     * Boolean that defines whether to display or hide the caption.
-     * By default is true and the caption is hidden.
+     * Used by `v-model:expandedItems`. Array of the currently expanded items —
+     * toggled by the row expand control and by external writes (mirrors the
+     * `highlighted`/`sort` v-model surfaces). Drives the `#expand` slot rows and
+     * their `aria-expanded`/`aria-controls` wiring.
+     *
+     * @defaultValue `[]`
      */
-    displayCaption?: boolean;
+    expandedItems?: any[];
     /**
-     * Defines the table layout as fixed
+     * Splits the width equally among the columns that declare no `width`
+     * (each undeclared column becomes a `minmax(0, 1fr)` track)
      * making each column take up the same amount of space.
      */
     fixed?: boolean;
@@ -224,6 +229,11 @@ export type BbTableProps<Item = any> = {
      * It can be an array of index of the column to fix on the left side of the table or
      * an array of objects indicating the index and the position `left` or `right` where to affix the columns.
      *
+     * Indices are POSITIONS in the rendered column list (a selection column is
+     * index 0), like a spreadsheet's freeze panes — not per-column pins. With
+     * `order` the pinned slot holds and whichever column lands in it is
+     * pinned; dragging a column out of a pinned slot unpins it.
+     *
      * @defaultValue `[]`
      */
     fixedColumns?: Array<number | {
@@ -234,21 +244,66 @@ export type BbTableProps<Item = any> = {
      * Boolean that sets the headers as sticky to the top of the table.
      */
     fixedHeaders?: boolean;
+    /**
+     * Defines the classes to be passed to the header row.
+     */
+    headerRowClass?: Classes;
     /**
      * Used by `v-model:highlighted`. A parallel, UI-intent state to selection —
      * typically "the row whose details are open". A single item value (or
      * `null`) — highlight is single by design.
-     * Purely mechanical: highlighted rows only get the
-     * `bb-table-data__row--highlighted` class (and `aria-current`) — no styling
-     * is shipped, targeting the class is up to the consumer.
+     *
+     * **Opt-in, and `undefined` is the opt-out.** Leave it unbound and the whole
+     * mechanic is off: clicking a row emits `click:row` and nothing else — no
+     * class, no `aria-current`, no internal state. Bind it and clicking a row
+     * toggles it. The value itself is the switch: `undefined` means "never
+     * initialised", `null` means "initialised and currently empty", so bind
+     * `ref(null)` rather than `ref()` — a bound-but-`undefined` model warns in
+     * dev and stays off. A value seeded through
+     * `useBbTableContext(id, { highlighted })` counts as bound the same way.
+     *
+     * A highlighted row gets `aria-current="true"` and the
+     * `bb-table-data__row--highlighted` class, which the shipped stylesheet
+     * paints with a neutral fill plus a brand accent bar; override the whole
+     * look with `rowClass`.
      */
     highlighted?: any;
+    /**
+     * Stable id for this table's width context. When omitted a unique id is
+     * generated. Nested tables use the nearest ancestor id to inherit widths.
+     */
+    id?: string;
+    /**
+     * Opt a nested table into inheriting its column widths from an ancestor
+     * table's matching tracks (accounting for `select`/`actions` columns). This
+     * also makes the parent's tracks authoritative, so it is **off by default** — a nested
+     * table renders independently unless you ask for alignment.
+     * - `false` (the default): do not inherit; size independently.
+     * - `true`: inherit from the nearest ancestor table.
+     * - a table id (string): inherit from the specific ancestor in the chain with
+     *   that id rather than the immediate parent. Use this when an intermediate
+     *   table has a different column count, so the extra columns would otherwise
+     *   misalign against it.
+     */
+    inheritColumnWidths?: boolean | string;
+    /**
+     * Keeps the table interactive while it is loading. The header and the rows are
+     * `inert` while loading by default — a refetch is about to replace the rows,
+     * so editing, selecting or sorting them races the incoming data. This escape
+     * hatch exists for tables that must stay usable during background refreshes
+     * (e.g. a poll that must not interrupt an open editor).
+     *
+     * The loading announcement is never inert, so the busy state is always
+     * conveyed.
+     */
+    interactiveWhileLoading?: boolean;
     /**
      * Rows to render, or a fetcher that returns them.
      *
      * @defaultValue `[]`
      */
     items: Item[] | ((prefill: boolean, modelValue?: any) => Item[] | Promise<Item[]>);
+    itemValue?: ItemAccessor<Item>;
     /**
      * Opt-in keyboard navigation with a roving tabindex: the body is one tab
      * stop, ArrowUp/ArrowDown move the focused row (Home/End jump), and
@@ -257,7 +312,6 @@ export type BbTableProps<Item = any> = {
      * not highlight until committed. Focused rows show the standard focus ring.
      */
     keyboardNavigation?: boolean;
-    itemValue?: ItemAccessor<Item>;
     /**
      * Text content of the `<legend>` a `selectable` table renders (it becomes
      * a `<fieldset>`, and the legend is that fieldset's accessible name).
@@ -274,17 +328,6 @@ export type BbTableProps<Item = any> = {
      * a refetch should not blank a table the user is reading.
      */
     loading?: boolean;
-    /**
-     * Keeps the table interactive while it is loading. The header and the rows are
-     * `inert` while loading by default — a refetch is about to replace the rows,
-     * so editing, selecting or sorting them races the incoming data. This escape
-     * hatch exists for tables that must stay usable during background refreshes
-     * (e.g. a poll that must not interrupt an open editor).
-     *
-     * The loading announcement is never inert, so the busy state is always
-     * conveyed.
-     */
-    interactiveWhileLoading?: boolean;
     /**
      * Screen-reader announcement for the loading row's `aria-live` status.
      * Visually hidden — the skeleton (or the `#loading` slot) is the visible
@@ -321,6 +364,24 @@ export type BbTableProps<Item = any> = {
      * @defaultValue the localized `common.noDataText` ("No data to display")
      */
     noDataText?: string;
+    /**
+     * Used by `v-model:order`. Ordered array of column keys — the render
+     * order of the data columns. Keys listed here render first, in this order;
+     * declared columns it omits follow, in declaration order (so a column added
+     * to `columns` later renders last); keys that match no declared column render
+     * nothing but are PRESERVED in place on every write — a column you hide by
+     * removing it from `columns` (a column panel) keeps its slot and comes back
+     * where it was. The header drag / keyboard reorder of `reorderable`
+     * writes it back complete (every declared key present, duplicates dropped —
+     * first occurrence wins) with exactly the moved column relocated: every other
+     * key, hidden ones included, keeps its relative order, and a drop that
+     * changes nothing emits nothing. Works uncontrolled when unbound, exactly
+     * like `sort`. The `select` and `actions` columns are structural and never
+     * part of it.
+     *
+     * @defaultValue `[]`
+     */
+    order?: string[];
     /**
      * Current page number starting from 1, used for accessibility purposes.
      * Also flows into the shared table context, so a `BbPagination` paired
@@ -343,14 +404,42 @@ export type BbTableProps<Item = any> = {
      */
     readonly?: boolean;
     /**
-     * Defines the classes to be passed to each data `<tr>`. Can also be a
+     * Lets the user reorder the data columns: drag a header cell (AG Grid style —
+     * the column moves live under the pointer and a chip with its label follows)
+     * or, from the keyboard, use each header's reorder handle (ArrowLeft /
+     * ArrowRight move the column one slot, Home / End to the ends). Every move
+     * writes `v-model:order`. Not needed by an external control (a column
+     * panel) that only writes `order`. The `select` / `actions` columns and
+     * a custom `#thead` are never draggable.
+     *
+     * @defaultValue `false`
+     */
+    reorderable?: boolean;
+    /**
+     * Lets the user resize the data columns of a root table: drag the handle on
+     * a header's trailing edge (the column follows live, the width commits on
+     * release), or press Alt + ArrowLeft / ArrowRight on the focused header;
+     * double-click the handle to go back to the declared width. Each commit
+     * fires `resize:column(key, width)` once. `column.width` stays the single declared
+     * truth: a resized width is an override the table keeps until that
+     * column's `width` changes — write the reported width back into your
+     * column definition to persist it. Ignored on a table that inherits its
+     * widths from a parent.
+     *
+     * @defaultValue `false`
+     */
+    resizable?: boolean;
+    /**
+     * Defines the classes to be passed to each data row. Can also be a
      * function of the row's item for dynamic values.
      */
     rowClass?: RowClasses<Item>;
     /**
-     * Defines the classes to be passed to the header `<tr>`.
+     * Defines whether the table is selectable.
+     * Can be a global boolean that affects all rows or a function
+     * that accepts an item and returns a boolean that only affects that item.
      */
-    headerRowClass?: Classes;
+    selectable?: boolean | ((item: Item) => boolean);
     /**
      * Defines whether the "Select all" checkbox is checked.
      *
@@ -358,11 +447,13 @@ export type BbTableProps<Item = any> = {
      */
     selectAll?: boolean;
     /**
-     * Defines whether the table is selectable.
-     * Can be a global boolean that affects all rows or a function
-     * that accepts an item and returns a boolean that only affects that item.
+     * Text of the label used by the "Select all" boolean.
      */
-    selectable?: boolean | ((item: Item) => boolean);
+    selectAllLabel?: string;
+    /**
+     * Text of the header used for the radio inputs when the table is not `multiple`.
+     */
+    selectText?: string;
     /**
      * Used by `v-model:sort`. Ordered array of `[columnKey, direction]`
      * entries, one per actively sorted column. Bidirectional: the header
@@ -374,28 +465,11 @@ export type BbTableProps<Item = any> = {
      */
     sort?: BbTableSortEntry[];
     /**
-     * Used by `v-model:expandedItems`. Array of the currently expanded items —
-     * toggled by the row expand control and by external writes (mirrors the
-     * `highlighted`/`sort` v-model surfaces). Drives the `#expand` slot rows and
-     * their `aria-expanded`/`aria-controls` wiring.
-     *
-     * @defaultValue `[]`
-     */
-    expandedItems?: any[];
-    /**
-     * Text of the label used by the "Select all" boolean.
-     */
-    selectAllLabel?: string;
-    /**
-     * Text of the header used for the radio inputs when the table is not `multiple`.
-     */
-    selectText?: string;
-    /**
-     * Defines the classes to be passed to the `<td>` elements. Can also be a function for dynamic values.
+     * Defines the classes to be passed to every data cell. Can also be a function for dynamic values.
      */
     tdClass?: ColumnClasses<Item>;
     /**
-     * Defines the classes to be passed to the `<th>`.
+     * Defines the classes to be passed to every header cell.
      */
     thClass?: Classes;
     /**
@@ -423,6 +497,22 @@ export type BbTableProps<Item = any> = {
      * @defaultValue `[]`
      */
     unselectedItems?: any[];
+    /**
+     * Windows the body: only the rows in (and just around) the vertical
+     * scrollport are mounted, so a client-side dataset of any size scrolls at
+     * a constant cost. The table itself is the scroller as soon as you bound
+     * its height (`max-height` / `height`, or a flex item with
+     * `min-height: 0`); left unbounded, the nearest scrolling ancestor or the
+     * page scrolls it. The header sticks to that scroller. Column widths are
+     * measured once from the first rendered batch and then hold — later rows
+     * never widen them. Expand rows and nested tables stay fully rendered
+     * inside their row (a nested table is never windowed); the row that owns
+     * focus stays mounted even when scrolled out of view. Ignored by a table
+     * that inherits its widths from a parent, and under a `#tbody` slot.
+     *
+     * @defaultValue `false`
+     */
+    virtual?: boolean;
 };
 /**
  * We allow table data classes to be a function so it can depend on the item.
@@ -454,12 +544,22 @@ export type MappedItem = Option & {
     onRowContextMenu: (event: MouseEvent) => void;
     onRowDblClick: (event: MouseEvent) => void;
     rowIndex: number | undefined;
+    /**
+     * The row's slot scope, built ONCE per row in the projection rather than
+     * per cell per render (a 16-column row used to allocate ~100 closures and
+     * objects on every render; a virtualized table mounts a dozen rows per
+     * scroll step).
+     */
+    expandProps: Record<string, unknown>;
+    toggleExpanded: () => void;
+    toggleHighlighted: () => void;
+    toggleSelected: () => void;
 };
 /**
  * Projection that represents a header
  */
 export type MappedHeader = {
-    align: HTMLTableCellElement['align'];
+    align: string;
     classes?: Classes;
     key: string;
     label: string;
@@ -486,34 +586,76 @@ export type ExpandControllerProps = {
     onKeydown: (event: KeyboardEvent) => void;
 };
 export type BbTableEvents = {
-    (e: 'click:row', event: MouseEvent, item: any, selected: boolean): void;
-    (e: 'contextmenu:row', event: MouseEvent, item: any, selected: boolean): void;
-    (e: 'dblclick:row', event: MouseEvent, item: any, selected: boolean): void;
+    (e: 'click:row', event: MouseEvent, item: any): void;
+    (e: 'contextmenu:row', event: MouseEvent, item: any): void;
+    (e: 'dblclick:row', event: MouseEvent, item: any): void;
     (e: 'update:highlighted', value: any): void;
     (e: 'update:modelValue', value: any): void;
     (e: 'update:selectAll', value: boolean): void;
     (e: 'update:sort', value: BbTableSortEntry[]): void;
+    (e: 'update:order', value: string[]): void;
+    /**
+     * A column was resized by the user (`resizable`): the new width in
+     * px, or `null` when the handle was double-clicked to reset the column to
+     * its declared width.
+     */
+    (e: 'resize:column', key: string, width: number | null): void;
     (e: 'update:expandedItems', value: any[]): void;
     (e: 'update:unselectedItems', value: any[]): void;
     (e: 'item:selected', value: any): void;
     (e: 'item:unselected', value: any): void;
 };
+/**
+ * Props exposed by the table-wide `header:prepend` / `header:append` slots and
+ * their per-column `header:<key>:prepend` / `header:<key>:append` variants —
+ * the `header:<key>` payload plus the column key.
+ */
+export type BbTableHeaderAffixSlotProps<Item = any> = {
+    /** Merged header classes for this column. */
+    classes?: Classes;
+    /**
+     * The raw key of the column being rendered — branch on it in the
+     * table-wide slots.
+     */
+    columnKey: string;
+    /** The current table items. */
+    items?: Item[];
+    /** The column's label. */
+    label?: string;
+    /** Whether this column is sortable. */
+    sortable?: boolean;
+    /** This column's current sort direction, or `null` when unsorted. */
+    sortOrder?: 'asc' | 'desc' | null;
+    /** Cycles this column's sort: unsorted → asc → desc → unsorted. */
+    toggleSort?: () => void;
+};
 export type BbTableSlots<Item = any> = {
     /**
-     * Replaces the entire `<thead>` element. Use when you need full control over the header markup.
+     * Replaces the content of the header row group (`.bb-table__head`). Use when
+     * you need full control over the header markup. The table is a CSS grid,
+     * not a `<table>`: provide role-complete rows — `<div role="row">` holding
+     * one `<div role="columnheader">` per column — and never a `<tr>`/`<th>`.
+     * Rows are subgrid rows, so each cell lands on the matching column track.
      */
     thead?: (props: object) => any;
     /**
-     * Replaces the entire `<tbody>` element. Use when you need full control over the body markup.
+     * Replaces the content of the body row group (`.bb-table__body`). Use when
+     * you need full control over the body markup. Provide role-complete rows —
+     * `<div role="row">` holding one `<div role="cell">` per column — never a
+     * `<tr>`/`<td>`. A full-width cell spans with `grid-column: 1 / -1`.
      */
     tbody?: (props: object) => any;
     /**
-     * Replaces the entire `<tfoot>` element. Use when you need full control over the footer markup.
+     * Fills the footer row group (`.bb-table__foot`). Use when you need a
+     * footer. Provide role-complete rows — `<div role="row">` holding
+     * `<div role="cell">` elements — never a `<tr>`/`<td>`.
      */
     tfoot?: (props: {
         /**
-         * Total rendered column count — the value to give a full-width footer row's
-         * `colspan` (accounts for the selection/expand columns), so you never hand-count it.
+         * Total rendered column count (accounts for the selection/actions
+         * columns), so you never hand-count it. A footer cell spanning the
+         * whole table uses `grid-column: 1 / -1`; one spanning a subset uses
+         * `grid-column: span N` with `N` up to this value.
          */
         columnCount: number;
     }) => any;
@@ -535,6 +677,20 @@ export type BbTableSlots<Item = any> = {
     'header:actions'?: (props: {
         text: string;
     }) => any;
+    /**
+     * Content rendered before every data column's header cell content — the
+     * label + sort control, or the column's own `header:<key>` replacement.
+     * A column's `header:<key>:prepend` slot wins over this one for that
+     * column; they never stack. Branch on `columnKey` for per-column output.
+     */
+    'header:prepend'?: (props: BbTableHeaderAffixSlotProps<Item>) => any;
+    /**
+     * Content rendered after every data column's header cell content — the
+     * label + sort control, or the column's own `header:<key>` replacement.
+     * A column's `header:<key>:append` slot wins over this one for that
+     * column; they never stack. Branch on `columnKey` for per-column output.
+     */
+    'header:append'?: (props: BbTableHeaderAffixSlotProps<Item>) => any;
     /**
      * Content shown while table rows are loading (replaces the skeleton rows).
      * @param items - The current (possibly stale) list of items, useful to match the previous row count.
@@ -544,9 +700,9 @@ export type BbTableSlots<Item = any> = {
     }) => any;
     /**
      * Content shown when the items list is empty and not loading. It fills the
-     * table's own full-width empty-state cell (the colspan already accounts for
-     * the selection/actions columns), so provide the *content* — a message, an
-     * illustration, a "clear filters" button — never a `<tr>`/`<td>` of your own.
+     * table's own full-width empty-state cell (it already spans the
+     * selection/actions columns), so provide the *content* — a message, an
+     * illustration, a "clear filters" button — never a row/cell of your own.
      */
     'no-data'?: (props: object) => any;
     /**
@@ -616,6 +772,11 @@ export type BbTableSlots<Item = any> = {
     }) => any;
 } & Record<string, (props: {
     classes?: Classes[];
+    /**
+     * Present only in the `header:<key>:prepend/append` affix slots — the
+     * raw key of the column being rendered.
+     */
+    columnKey?: string;
     content?: any;
     expanded?: boolean;
     expandProps?: ExpandControllerProps;

package/dist/components/BbTable/utils.d.ts

@@ -5,10 +5,93 @@ export type FixedColumnConfig = number | {
     position: 'left' | 'right';
 };
 /**
- * Applies sticky positioning to fixed table columns.
- * Call after DOM updates (e.g. in watch with flush: 'post') to read layout.
+ * Splits the grid root's *resolved* `grid-template-columns` (one
+ * `getComputedStyle` read) into its px tokens, verbatim. Returns `null` when
+ * any token is not a px length: a table hidden by `display: none` reports its
+ * SPECIFIED template (`max-content auto …`) instead of used values, and the
+ * caller must keep its last good measurement rather than publish keywords.
+ *
+ * Read the root only — a subgrid box reports the literal `subgrid [] [] …`.
  */
-export declare const applyFixedTableColumns: (table: HTMLTableElement, fixedColumns: FixedColumnConfig[]) => void;
+export declare const readResolvedTracks: (root: Element) => string[] | null;
+/**
+ * Applies sticky positioning to fixed table columns — a RECONCILE pass, not a
+ * set-only one: every cell of every processed row ends up with exactly the
+ * inline `position`/`left`/`right` its slot calls for, and nothing else.
+ *
+ * `root` is the grid root (`.bb-table__table`). Offsets are prefix sums of the
+ * resolved track list, so they hold to the subpixel regardless of what sized
+ * the track (frozen width, inherited parent track, content). Call after DOM
+ * updates (e.g. in a `flush: 'post'` watch) and after every re-measure so the
+ * offsets follow the tracks.
+ *
+ * Pins are POSITIONAL (indices into the rendered track list, `select`
+ * included): the pinned slot holds and whichever column lands in it is
+ * pinned. Cells are keyed by column, so a reorder MOVES the cell element —
+ * inline styles travel with it. A column leaving a pinned slot would keep
+ * `position: sticky; left: 0px` and, once the container scrolls, paint over
+ * the column that took the slot (and shrink a right-pinned slot's `left`
+ * would linger too), which is why every non-pinned cell is cleared and every
+ * pinned cell has its opposite side cleared. The same clearing is what makes
+ * shrinking `fixedColumns` (or emptying it) unpin. Clearing an absent inline
+ * property is mutation-free, so the pass is idempotent and cheap.
+ */
+export declare const applyFixedTableColumns: (root: HTMLElement, fixedColumns: FixedColumnConfig[], 
+/**
+ * The resolved tracks when the caller already holds them (the measure path
+ * just read them; a `virtual` window change moves no track): skips the
+ * `getComputedStyle` read, which forces style on every call.
+ */
+resolvedTracks?: string[] | null, 
+/**
+ * Skip rows whose inline styles were already written for this exact track
+ * list and pin config — the caller opting in to the row stamp below. Only
+ * safe when the CELL ORDER cannot have changed since the last pass, which
+ * is the caller's knowledge, not ours: a reorder can leave the track list
+ * and the config byte-identical while every cell has moved to a different
+ * track. `virtual`'s window-move pass is exactly that case (the rows
+ * change, the columns do not).
+ */
+memoize?: boolean) => void;
+/**
+ * Completes an `order` model against the declared column keys: the
+ * model's keys first (duplicates dropped, first occurrence wins), then every
+ * declared key the model omits, in declaration order. Unknown keys (columns
+ * the consumer currently hides) are kept in place.
+ */
+export declare const completeColumnOrder: (model: readonly string[], declared: readonly string[]) => string[];
+/**
+ * Declared columns in render order — the completed model restricted to the
+ * declared keys. A key declared twice keeps both columns (parity with the
+ * unordered render), adjacent, in declaration order.
+ */
+export declare const orderColumns: <C extends {
+    key: string;
+}>(columns: readonly C[], model: readonly string[]) => C[];
+/**
+ * The write-back. Moves `key` to render index `toIndex` among the declared
+ * columns and returns the complete model to emit: the completed model with
+ * exactly ONE entry relocated — what dragging that entry in a panel listing
+ * the complete order (hidden columns included) would produce.
+ *
+ * Invariants (each pinned by a unit test):
+ *  1. completeness — a permutation of `completeColumnOrder(model, declared)`,
+ *     no duplicates;
+ *  2. single relocation — `result` without `key` equals the completed model
+ *     without `key`: every other key, hidden ones included, keeps its
+ *     relative order (this IS the "hidden columns keep their slot" guarantee);
+ *  3. render index — among the declared keys, `key` sits at
+ *     `clamp(toIndex, 0, N - 1)`;
+ *  4. adjacency — `key` lands right AFTER (moving right) / right BEFORE
+ *     (moving left) the visible column it displaces, so a hidden key is never
+ *     caught between the mover and its new neighbour;
+ *  5. stability — an unknown or hidden `key`, or `toIndex` equal to the
+ *     current index, returns the completed model unchanged (callers compare
+ *     against the completed model and emit nothing).
+ */
+export declare const moveColumnKey: (model: readonly string[], declared: readonly string[], key: string, toIndex: number) => string[];
+/** Sequence equality for the commit guard. */
+export declare const sameColumnOrder: (a: readonly string[], b: readonly string[]) => boolean;
 /**
  * Converts a column key (e.g. "address.nested.value") to a slot-safe name (e.g. "address_nested_value").
  * Thin alias over the shared {@link slotKey} normalizer used across every
@@ -20,7 +103,7 @@ export declare const columnKeyToSlotName: (key: string) => string;
  */
 export declare const mergeHeaderClasses: (base: Classes, global?: Classes, column?: Classes) => Classes;
 /**
- * Accumulates every row-class source for a row's `<tr>`: the table-level
+ * Accumulates every row-class source for a data row: the table-level
  * `rowClass` prop (item function or static), then each column's `rowClass`
  * (resolved with that column's cell content, like `tdClass`), in column order.
  */