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

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,52 +87,89 @@ 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;
+    /**
+     * Hides the column: it renders no header and no cells and contributes no
+     * grid track, but stays DECLARED — its key keeps its slot in `order`, the
+     * header reorder writes the model back complete around it, and it comes
+     * back exactly where it was when the flag clears. This is how a column
+     * panel or a narrow-screen breakpoint hides a column; filtering `columns`
+     * is for a column that does not exist at all (a field this user does not
+     * have). Like `width`, the definition is the single declared truth: a
+     * header's `hideColumn()` sets a per-mount override that `hide:column` reports
+     * and that clears the moment this flag changes to anything but `true`
+     * (write the reported key back as `hidden: true` to persist it).
+     */
+    hidden?: boolean;
+    /**
+     * Pins the column: its cells become `position: sticky` on the given side,
+     * in place — the column keeps its render slot and sticks there as the rest
+     * scrolls under it (spreadsheet freeze panes, not a pinned region). The
+     * offset accumulates the pinned columns before it on the same side, so
+     * pin a contiguous run from the edge: a lone `left` column in the middle
+     * sticks at `left: 0` and slides over everything before it, by design.
+     * The pin travels with the column through `order` and `reorderable`, and
+     * a `hidden` pinned column pins nothing. The structural columns pin
+     * through `fixed-select` / `fixed-actions` on the table.
+     */
+    fixed?: 'left' | 'right';
     /**
      * Freezes the column to a fixed width (numbers are treated as px). When
      * omitted the column syncs its width to the parent table's matching track.
      */
     width?: number | string;
     /**
-     * For a nested table, where this column snaps onto the parent's grid. The
-     * parent's columns form snap points where `select` occupies `[0, 1]`, data
-     * column `k` occupies `[k + 1, k + 2]` and `actions` occupies `[N + 1, N + 2]`.
+     * For a nested table, which parent column this column snaps onto — by the
+     * parent's column KEY, as written (`'client'`, not a position), plus the
+     * reserved names `'select'` and `'actions'` for the parent's structural
+     * columns.
      *
-     * - A single number is a start snap point that takes one parent track, e.g.
-     *   `2` → `[2, 3]`. It may skip ahead (`5` jumps straight to the sixth track),
-     *   and the next column resumes from where it ends.
-     * - A `[start, end]` pair snaps between two points; the width is the sum of
-     *   the fractional parent tracks it covers, so `[3, 4.5]` is the full fourth
-     *   track plus half of the fifth. `end` of `-1` runs to the end of the data
-     *   region.
+     * - A single key takes that parent track: `snap: 'client'`.
+     * - A `[start, end]` pair spans from the start of `start` through the END
+     *   of `end`, inclusive: `['client', 'amount']`, or `['name', 'actions']`
+     *   to run across the parent's actions column too.
+     * - A trailing `.digits` on a key is a fraction of that track — `'amount.5'`
+     *   as an end means "through half of `amount`", as a start "from halfway
+     *   into it". Pairs only; a key that itself ends in `.digits` is written
+     *   in its slot-name spelling (`line_1`).
      *
-     * When omitted the column chains from the previous column's end to the next
-     * whole snap point (a one-to-one inheritance by index).
+     * When omitted the column pairs with the parent column of the SAME key when
+     * there is one, and otherwise flows into the next parent track no other
+     * column claimed. A column whose target the parent does not render (a
+     * `hidden` parent column, a key it lacks) flows the same way; with no free
+     * track left it content-sizes and overflows. The last column runs to the end
+     * of the parent's data region 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.
+     *
+     * Snaps resolve against the parent's RENDERED columns, so they are ignored
+     * (dev builds warn) under a parent that reorders — `reorderable`, or a
+     * non-empty `order` model — where the child falls back to positional
+     * inheritance. Never reorder the snapped child itself.
      */
-    snap?: number | [start: number, end: number];
+    snap?: string | [start: string, end: string];
 };
 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;
-    /**
-     * Displays the actions column.
-     */
-    actions?: boolean;
     /**
      * Label used in the header of the actions column.
      */
@@ -136,31 +180,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 +212,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,45 +241,102 @@ 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;
     /**
-     * Definition for which column should be fixed.
-     * 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.
+     * Pins the actions column (the one the `#actions` slot creates) to the
+     * right edge, `position: sticky`, in place. Data columns pin through
+     * `column.fixed`; this is the same feature for the structural column that
+     * has no definition to carry it. No effect without an `#actions` slot.
      *
-     * @defaultValue `[]`
+     * @defaultValue `false`
      */
-    fixedColumns?: Array<number | {
-        index: number;
-        position: 'left' | 'right';
-    }>;
+    fixedActions?: boolean;
     /**
      * Boolean that sets the headers as sticky to the top of the table.
      */
     fixedHeaders?: boolean;
+    /**
+     * Pins the selection column to the left edge, `position: sticky`, in
+     * place. Data columns pin through `column.fixed`; this is the same feature
+     * for the structural column that has no definition to carry it. No effect
+     * unless the table is `selectable`.
+     *
+     * @defaultValue `false`
+     */
+    fixedSelect?: 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 +345,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 +361,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 +397,23 @@ 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); a `hidden` column keeps its slot
+     * without rendering, and keys that match no declared column render
+     * nothing but are PRESERVED in place on every write. The header drag /
+     * keyboard reorder of `reorderable` writes it back complete (every
+     * declared key present, hidden ones included, duplicates dropped — first
+     * occurrence wins) with exactly the moved column relocated: every other
+     * key 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 +436,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 +479,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 +497,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 +529,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 +576,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 +618,90 @@ 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;
+    /**
+     * A column was hidden from its header (a `#header:<key>` /
+     * `#header:<key>:append` control calling the slot's `hideColumn()`). Fired once;
+     * the table keeps the column hidden for the mount, or until the column's
+     * `hidden` flag changes — write `hidden: true` into the definition to
+     * persist it, `hidden: false` (a column panel) to show it again.
+     */
+    (e: 'hide:column', key: string): 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;
+    /**
+     * Hides this column (fires `hide:column`). One-way by nature — a hidden
+     * column has no header to call it from; showing it again is the
+     * definition's job (`hidden: false`).
+     */
+    hideColumn?: () => 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 +723,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,13 +746,17 @@ 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;
     /**
-     * Content rendered in the actions cell for each row.
+     * Content rendered in the actions cell for each row. Providing this slot
+     * is what CREATES the actions column (there is no prop): the header cell
+     * (labelled by `actions-text`, replaceable through `#header:actions`) and
+     * one cell per row appear with it, and go away with it. Pin it with
+     * `fixed-actions`.
      * @param expanded - Whether this row is currently expanded.
      * @param expandProps - Bind these onto an expand-toggle button to wire up aria attributes and keyboard handling.
      * @param toggleExpanded - Toggles the expanded state for this row.
@@ -616,6 +822,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;
@@ -627,6 +838,8 @@ export type BbTableSlots<Item = any> = {
     sortable?: boolean;
     sortOrder?: 'asc' | 'desc' | null;
     toggleSort?: () => void;
+    /** Header slots only: hides this column (fires `hide:column`). */
+    hideColumn?: () => void;
     /**
      * Optional because this catch-all also types the `head:*` /
      * `header:*` column slots, which have no row and never receive one.