bitboss-ui 3.0.0-beta.12 → 3.0.0-beta.14

package/dist/ai/changelog.json

@@ -1,7 +1,7 @@
 {
 	"schemaVersion": 1,
 	"library": "bitboss-ui",
-	"version": "3.0.0-beta.12",
+	"version": "3.0.0-beta.14",
 	"upgrade": "v2-to-v3",
 	"guide": "ai/guides/migration/v2-to-v3.md",
 	"summary": {

package/dist/ai/components.json

@@ -1,8 +1,8 @@
 {
 	"schemaVersion": 1,
 	"library": "bitboss-ui",
-	"version": "3.0.0-beta.12",
-	"generatedAt": "2026-08-28T12:47:31.708Z",
+	"version": "3.0.0-beta.14",
+	"generatedAt": "2026-08-28T14:01:44.030Z",
 	"composables": [
 		{
 			"name": "useBbConfig",

package/dist/ai/source/BbTable.md

@@ -471,42 +471,17 @@
 							:selected="isSelected(row.item)"
 							:virtual-index="row.virtualIndex"
 						/>
-						<div
+						<!-- Behind a component boundary for the same reason the data row
+							is: the table re-renders its body on every window move, and this
+							row holds the CONSUMER's `#expand` slot — usually a whole nested
+							table. See the note at the top of `BbTableExpandRow`. -->
+						<BbTableExpandRow
 							v-else
-							:id="`expanded_${row.item.valueHash}`"
-							:ref="measureVirtualRow"
-							:aria-rowindex="
-								hasProvidedAccessibilityData && row.item.rowIndex
-									? row.item.rowIndex + 1
-									: undefined
-							"
-							class="bb-table-expand__row"
-							:class="{
-								'bb-table-expand__row--highlighted': row.item.highlighted,
-							}"
-							:data-index="row.virtualIndex"
-							role="row"
-						>
-							<div
-								:aria-colspan="replacementContentSpan"
-								class="bb-table-expand__cell"
-								role="cell"
-							>
-								<!-- @vue-ignore -->
-								<slot
-									:expand-props="row.item.expandProps"
-									:expanded="row.item.expanded"
-									:highlighted="row.item.highlighted"
-									:item="row.item.item"
-									name="expand"
-									:selected="isSelected(row.item)"
-									:toggle-expanded="row.item.toggleExpanded"
-									:toggle-highlighted="row.item.toggleHighlighted"
-									:toggle-selected="row.item.toggleSelected"
-									:value="row.item.value"
-								></slot>
-							</div>
-						</div>
+							:context="dataRowContext"
+							:item="row.item"
+							:selected="isSelected(row.item)"
+							:virtual-index="row.virtualIndex"
+						/>
 					</template>
 				</slot>
 
@@ -605,6 +580,7 @@ import {
 } from '@/utilities/functions/parsePaginationNumber';
 import BaseCheckbox from '../BbBaseCheckbox/BbBaseCheckbox.vue';
 import BbTableDataRow from './BbTableDataRow';
+import BbTableExpandRow from './BbTableExpandRow';
 import type { DataRowContext } from './BbTableDataRow';
 import type { Option as BaseOption } from '@/types/Option';
 import type { Classes } from '@/types/Classes';
@@ -881,6 +857,18 @@ const orderedColumns = computed(() => {
 		: ordered;
 });
 
+/**
+ * The RENDERED column keys, in order — as distinct from `declaredKeys`, which
+ * is the same list in the order the consumer wrote it. Six places derived this
+ * independently (the roving header index, the two header-focus helpers, the
+ * resize handle's neighbour lookup, the drag's placement math and
+ * `columnOrderKey`); they now share one cached derivation and, more to the
+ * point, one name for the thing.
+ */
+const orderedColumnKeys = computed(() =>
+	orderedColumns.value.map((column) => String(column.key))
+);
+
 /**
  * The next model for "move `key` to render index `toIndex`", or `null` when
  * that changes nothing (the boundary key, a no-op drop): callers then emit
@@ -928,7 +916,7 @@ const announceColumnMove = (key: string, from: number) => {
  */
 const activeHeaderKey = ref<string | null>(null);
 const rovingHeaderKey = computed(() => {
-	const keys = orderedColumns.value.map((column) => String(column.key));
+	const keys = orderedColumnKeys.value;
 	const active = activeHeaderKey.value;
 	return active !== null && keys.includes(active) ? active : (keys[0] ?? null);
 });
@@ -964,7 +952,7 @@ const headerCellFor = (key: string) =>
 	) ?? null;
 
 const focusHeaderAt = (index: number) => {
-	const keys = orderedColumns.value.map((column) => String(column.key));
+	const keys = orderedColumnKeys.value;
 	const key = keys[Math.max(0, Math.min(keys.length - 1, index))];
 	if (!key) return;
 	activeHeaderKey.value = key;
@@ -1012,7 +1000,7 @@ const onHeaderKeydown = async (event: KeyboardEvent, key: string) => {
 		return;
 	}
 	if (event.ctrlKey || event.metaKey) return;
-	const rendered = orderedColumns.value.map((column) => String(column.key));
+	const rendered = orderedColumnKeys.value;
 	const from = rendered.indexOf(key);
 	if (from < 0) return;
 	let to: number;
@@ -1162,39 +1150,53 @@ const resizedKeys = computed(
 );
 
 /**
- * Cells that clip with an ellipsis instead of spilling: the user-resized
- * columns, and — under `virtual` — every column sized from the first batch
- * (`virtualWidths`): its floor came from the rows that happened to be there,
- * so a later, longer value must not overflow the cell. A declared `width`
- * keeps wrapping; that is the way to get prose in a virtual table.
- */
-const clippedCellKeys = computed(() => {
-	const keys = new Set(resizedKeys.value);
-	if (virtualActive.value) {
-		for (const column of orderedColumns.value) {
-			const key = String(column.key);
-			if (column.width == null && key in virtualWidths.value) keys.add(key);
-		}
-	}
-	return keys;
-});
-
-/**
- * Cells that are single-line from the FIRST render of a `virtual` table:
- * every undeclared column, frozen yet or not. The first batch is what the
- * freeze measures, and a cell that may still wrap ("INV-10213" breaks at
- * the hyphen, a phone at its spaces) floors its `auto` track at the wrapped
- * width — the clip that follows then cuts the same value by a character.
- * `nowrap` alone keeps the cell flooring the track (an `overflow: hidden`
- * would zero its automatic minimum); the clip is layered on once frozen.
+ * The width-driven state classes a column's DATA CELLS carry, as one ready
+ * string per column key. Columns in their default state are absent from the
+ * map rather than mapped to `''`.
+ *
+ * This replaces three Sets the row used to interrogate separately, once per
+ * CELL: three membership tests and a three-key object literal on the order of
+ * 250 times per body render, to answer a question that is per COLUMN and moves
+ * only when a resize commits, the first-batch freeze lands, or the columns are
+ * reordered.
+ *
+ * Holding the rules together is the other half of it, because they overlap by
+ * construction and reading any one of them told you only a third of what a
+ * cell would do:
+ *
+ * - `--resized` is a user override. A squeezed track cannot wrap a single
+ *   word, so such a cell clips with an ellipsis rather than spilling into its
+ *   neighbour. Only those: every other cell keeps wrapping and keeps flooring
+ *   its `auto` track exactly as before.
+ * - `--nowrap` is every undeclared column of a `virtual` table, from its FIRST
+ *   render, frozen yet or not. The first batch is what the freeze measures,
+ *   and a cell that may still wrap ("INV-10213" breaks at the hyphen, a phone
+ *   at its spaces) floors its `auto` track at the WRAPPED width — the clip
+ *   that follows then cuts the same value by a character. `nowrap` alone keeps
+ *   the cell flooring the track; an `overflow: hidden` would zero its
+ *   automatic minimum.
+ * - `--clip` is layered onto such a column once it IS frozen: its floor came
+ *   from whichever rows happened to be there, so a later, longer value must
+ *   not overflow the cell. A declared `width` keeps wrapping — that is how a
+ *   virtual table gets prose.
  */
-const nowrapCellKeys = computed(() => {
-	const keys = new Set<string>();
-	if (!virtualActive.value) return keys;
+const cellStateClasses = computed(() => {
+	const byKey = new Map<string, string>();
+	const resized = resizedKeys.value;
+	const virtual = virtualActive.value;
+	const frozen = virtualWidths.value;
 	for (const column of orderedColumns.value) {
-		if (column.width == null) keys.add(String(column.key));
+		const key = String(column.key);
+		const undeclared = virtual && column.width == null;
+		const state: string[] = [];
+		if (undeclared) state.push('bb-table-data__cell--nowrap');
+		if (resized.has(key)) state.push('bb-table-data__cell--resized');
+		if (resized.has(key) || (undeclared && key in frozen)) {
+			state.push('bb-table-data__cell--clip');
+		}
+		if (state.length) byKey.set(key, state.join(' '));
 	}
-	return keys;
+	return byKey;
 });
 
 /** True when any user override is live (feeds the `bb-table--fixed` hook). */
@@ -1372,7 +1374,7 @@ const onResizerPointerDown = (event: PointerEvent, key: string) => {
 		// see above
 	}
 	document.documentElement.classList.add(RESIZING_ROOT_CLASS);
-	const rendered = orderedColumns.value.map((column) => String(column.key));
+	const rendered = orderedColumnKeys.value;
 	const nextKey = rendered[rendered.indexOf(key) + 1];
 	const nextCell = nextKey ? headerCellFor(nextKey) : null;
 	resize = {
@@ -1559,7 +1561,7 @@ const placeDraggedColumn = (rawX: number) => {
 		...cells.filter((c) => !isStuck(c)),
 	];
 	const others = ordered.filter((cell) => cell.dataset.columnKey !== drag!.key);
-	const rendered = orderedColumns.value.map((column) => String(column.key));
+	const rendered = orderedColumnKeys.value;
 	const from = rendered.indexOf(drag.key);
 	if (from < 0) return;
 
@@ -2954,9 +2956,7 @@ const trackKeys = computed(() =>
  * `columnTracks`' keys are positions, so they read `0 1 2 3` before and after a
  * reorder; this changes whenever the columns move.
  */
-const columnOrderKey = computed(() =>
-	orderedColumns.value.map((column) => String(column.key)).join(' ')
-);
+const columnOrderKey = computed(() => orderedColumnKeys.value.join(' '));
 
 watch(
 	[trackKeys, columnOrderKey],
@@ -3685,25 +3685,39 @@ const flatRows = computed<FlatRow[]>(() => {
 
 /**
  * Wraps a flat row for rendering, with the projection behind a getter (see
- * `BodyRow.item`). Deliberately NOT memoized on the entry: these wrappers are
- * rebuilt on every window move, and a per-entry cache would hand a row a fresh
- * item each time. `mappedItemAt` owns the memo, and it outlives the wrappers.
+ * `BodyRow.item`).
+ *
+ * The getter resolves ONCE per entry. `mappedItemAt` still owns the memo — the
+ * identity a row's slots depend on comes from there, not from here, and the
+ * entries are rebuilt on every window move — but the body reads this getter
+ * three times for every rendered row (`:item`, `isSelected(row.item)` and
+ * `isSelectToggleBlocked(row.item)`), so without the local hold each of those
+ * paid a computed read and a `Map` lookup for a value it had already resolved
+ * a line earlier. Counted on the playground during a drag: 107 resolutions per
+ * scroll step for ~33 rendered rows.
+ *
+ * It cannot go stale. Everything that invalidates the memo also invalidates
+ * `bodyRows` — which reads `mappedMemo` for exactly that reason — and a new
+ * `bodyRows` is a new set of these wrappers.
  */
 const bodyEntry = (
 	row: FlatRow,
 	kind: BodyRow['kind'],
 	key: string,
 	height: number
-): BodyRow => ({
-	kind,
-	index: row.index,
-	key,
-	virtualIndex: row.virtualIndex,
-	height,
-	get item() {
-		return mappedItemAt(row);
-	},
-});
+): BodyRow => {
+	let item: MappedItem | undefined;
+	return {
+		kind,
+		index: row.index,
+		key,
+		virtualIndex: row.virtualIndex,
+		height,
+		get item() {
+			return (item ??= mappedItemAt(row));
+		},
+	};
+};
 
 /**
  * The vertical scroller: the container once its height is bounded (it is
@@ -3800,8 +3814,10 @@ const onBodyFocusOut = (event: FocusEvent) => {
 };
 
 /**
- * What the body reads: the window and the total size, published by
- * `flushVirtual` — NOT the wrapper's reactive handle. A scroll-driven change
+ * The list's total height, published by `flushVirtual` — NOT read off the
+ * wrapper's reactive handle. (The window itself is `virtualSlots`, below; a
+ * `virtualItems` ref used to be published alongside this one and nothing ever
+ * read it.) A scroll-driven change
  * (`sync`) is published at once; a measurement-driven one (a mounted row
  * measured taller or shorter than its estimate, which is the browser's
  * ResizeObserver callback) is published on the next frame. The offsets and
@@ -3811,7 +3827,6 @@ const onBodyFocusOut = (event: FocusEvent) => {
  * same delivery loop, which the browser reports as "ResizeObserver loop
  * completed with undelivered notifications".
  */
-const virtualItems = shallowRef<VirtualItem[]>([]);
 const virtualTotal = ref(0);
 let virtualFlushFrame = 0;
 
@@ -3925,6 +3940,11 @@ const noteVirtualScroll = (offset: number) => {
 const virtualRowMean = ref(0);
 /** Entry count of the last cache we summed — see `syncVirtualMean`. */
 let virtualMeanCacheSize = -1;
+/**
+ * Whether the estimate has settled. See the latch in `syncVirtualMean`: it is
+ * released only by a new row list, where the reset below clears it.
+ */
+let virtualEstimateLatched = false;
 const syncVirtualMean = () => {
 	const cache = (
 		virtualizerHandle as { itemSizeCache?: Map<string, number> } | null
@@ -3959,7 +3979,29 @@ const syncVirtualMean = () => {
 				mode = size;
 			}
 		}
-		if (mode > 0) virtualRowMean.value = mode;
+		// LATCHED once enough rows have been measured to choose well, and then
+		// left alone until the row list itself changes.
+		//
+		// The estimate stands in for every row NOT yet measured, so moving it
+		// resizes the scrollport by (rows still unmeasured × the delta). Measuring
+		// a row does not do that — the virtualizer swaps that one row's estimate
+		// for its real height and adjusts the total by the difference, which is
+		// smooth and invisible. Only re-estimating the whole tail at once can jump,
+		// and on a list whose rows fall into two clusters (most short, some
+		// wrapping) a freely-moving mode does exactly that: the two tallies trade
+		// places as measurement proceeds, and each swap moved the scrollport
+		// between 161,000px and 671,000px — the thumb skipping backwards while the
+		// reader scrolled forwards. Hysteresis was not enough; a 50/50 split
+		// crosses any margin repeatedly.
+		//
+		// Twenty rows is about one full window, so the sample is a real one rather
+		// than the first five rows of a sorted list. Being wrong afterwards costs
+		// only correction passes nobody sees; being unstable costs the reader
+		// their place, which is the one thing a scrollbar exists to keep.
+		if (mode > 0 && !virtualEstimateLatched) {
+			virtualRowMean.value = mode;
+			if (count >= 20) virtualEstimateLatched = true;
+		}
 	}
 	// The spacers tile their skeleton on this cadence.
 	syncPlaceholderRowHeight();
@@ -4009,7 +4051,6 @@ const flushVirtual = (scrolled = false) => {
 	}
 	if (!virtualizerHandle) return;
 	const items = virtualActive.value ? virtualizerHandle.getVirtualItems() : [];
-	virtualItems.value = items;
 	virtualTotal.value = virtualizerHandle.getTotalSize();
 	const slots: VirtualSlot[] = [];
 	let span: { start: number; end: number } | null = null;
@@ -4027,14 +4068,19 @@ const flushVirtual = (scrolled = false) => {
 		).range;
 		const first = range ? range.startIndex : items[0].index;
 		const last = range ? range.endIndex : items[items.length - 1].index;
+		// The item IS its measurement — `getVirtualItems` pushes the entries of
+		// `measurementsCache` themselves, it does not copy them — so looking the
+		// same index up again bought a second read and a `continue` branch that
+		// could not be taken. Still copied into our own shape rather than
+		// forwarded: a slot is what the body renders against and what the next
+		// flush compares itself to, and it should not be an object the
+		// virtualizer owns.
 		for (const item of items) {
-			const measurement = measurements?.[item.index];
-			if (!measurement) continue;
 			slots.push({
 				index: item.index,
-				start: measurement.start,
-				end: measurement.end,
-				size: measurement.size,
+				start: item.start,
+				end: item.end,
+				size: item.size,
 			});
 		}
 		// The scroll range the WINDOW covers — the visible range plus its
@@ -4083,30 +4129,61 @@ const scheduleVirtualFlush = () => {
 	});
 };
 
+/**
+ * The three virtualizer callbacks that must keep ONE IDENTITY for the table's
+ * life. They read their inputs when they are called, so a closure per options
+ * evaluation bought nothing — and cost a great deal.
+ *
+ * `getItemKey` is the memo key of tanstack's `getMeasurementOptions`
+ * (`virtual-core`: the deps are `[count, paddingStart, scrollMargin,
+ * getItemKey, enabled, …]`, compared by IDENTITY). A new function there clears
+ * `pendingMeasuredCacheIndexes` and invalidates `getMeasurements`, which then
+ * rebuilds EVERY measurement from index 0 — one object, one `getItemKey` and
+ * one `estimateSize` call per row in the whole list, not per row on screen.
+ *
+ * Built inside the options computed, they were re-created whenever anything
+ * that computed reads changed — and one of those is `pinnedVirtualIndex`,
+ * which is written on every `focusin`/`focusout` in the body. So tabbing
+ * between two buttons in two rows, or arrowing down the keyboard grammar, paid
+ * a full-list measurement rebuild: measured on the playground at 50,000 rows,
+ * 94,076 `getItemKey` calls across twenty focus moves. Hoisted, focus moves
+ * the range and nothing else.
+ *
+ * `rangeExtractor` deliberately STAYS in the computed: it is the memo key of
+ * `getVirtualIndexes`, so the pinned row would never be added to the range if
+ * its identity did not move with `pinnedVirtualIndex`. That memo is over one
+ * window, not over the list.
+ */
+const virtualOnChange = (
+	instance: { getScrollOffset: () => number },
+	sync: boolean
+) => {
+	if (sync) {
+		noteVirtualScroll(instance.getScrollOffset());
+		flushVirtual(true);
+	} else {
+		scheduleVirtualFlush();
+	}
+};
+
+const virtualItemKey = (index: number) => flatRows.value[index]?.key ?? index;
+
+const virtualEstimateSize = (index: number) =>
+	(flatRows.value[index]?.kind === 'expand' ? 3 : 1) *
+	(virtualRowMean.value || virtualRowEstimate.value);
+
 const rowVirtualizer = useVirtualizer(
 	computed(() => {
 		const scroller = virtualScroller.value;
 		const isWindow = scroller === window;
 		const pinned = pinnedVirtualIndex.value;
 		return {
-			onChange: (
-				instance: { getScrollOffset: () => number },
-				sync: boolean
-			) => {
-				if (sync) {
-					noteVirtualScroll(instance.getScrollOffset());
-					flushVirtual(true);
-				} else {
-					scheduleVirtualFlush();
-				}
-			},
+			onChange: virtualOnChange,
 			count: virtualActive.value ? flatRows.value.length : 0,
 			enabled: virtualActive.value,
 			getScrollElement: () => scroller as any,
-			estimateSize: (index: number) =>
-				(flatRows.value[index]?.kind === 'expand' ? 3 : 1) *
-				(virtualRowMean.value || virtualRowEstimate.value),
-			getItemKey: (index: number) => flatRows.value[index]?.key ?? index,
+			estimateSize: virtualEstimateSize,
+			getItemKey: virtualItemKey,
 			overscan: VIRTUAL_OVERSCAN,
 			scrollMargin: virtualScrollMargin.value,
 			// Before the scroller is known (first render, SSR): a window's worth
@@ -4185,7 +4262,6 @@ const bodyRows = computed<BodyRow[]>(() => {
 	const out: BodyRow[] = [];
 	const margin = virtualScrollMargin.value;
 	const fast = virtualFast.value;
-	const real = new Set<string>();
 	let cursor = margin;
 	let last: FlatRow | undefined;
 	for (const slot of slots) {
@@ -4201,13 +4277,10 @@ const bodyRows = computed<BodyRow[]>(() => {
 			out.push(bodyEntry(row, 'placeholder', `p:${row.key}`, slot.size));
 		} else {
 			out.push(bodyEntry(row, row.kind, row.key, 0));
-			real.add(row.key);
 		}
 		cursor = slot.end;
 		last = row;
 	}
-	// Bookkeeping, not state: remember what has been rendered real.
-	for (const key of real) virtualRealKeys.add(key);
 	const tail = virtualTotal.value - (cursor - margin);
 	if (tail > 0.5 && last) {
 		out.push(bodyEntry(last, 'spacer', 's:end', tail));
@@ -4215,6 +4288,39 @@ const bodyRows = computed<BodyRow[]>(() => {
 	return out;
 });
 
+/**
+ * "Rows you have already seen stay real" — recorded AFTER the patch, not
+ * inside `bodyRows`.
+ *
+ * It used to be a `virtualRealKeys.add` at the end of that computed, and a
+ * computed that writes to the world outside it is one whose result depends on
+ * how many times it has run. Vue re-evaluates a computed whenever a dependency
+ * moves and somebody asks for the value, which is NOT the same event as "the
+ * body rendered this": an evaluation whose output never reached the DOM still
+ * promoted its rows out of the skeleton, and the next fast scroll then mounted
+ * a full row — sixteen cells and the consumer's slots — for a reader who is
+ * nowhere near it. Post-flush the set says exactly what it claims: the keys of
+ * rows that are, or have been, on screen.
+ *
+ * Both real kinds are recorded, as they were before. Only `row` is ever
+ * consulted (an expand row is never drawn as a placeholder), but keeping
+ * `expand` in makes the set answer the question its name asks.
+ *
+ * This watcher forces no extra work: the pin pass below already subscribes to
+ * `bodyRows` post-flush, so the value is computed for that tick regardless.
+ */
+watch(
+	bodyRows,
+	(rows) => {
+		if (!virtualActive.value) return;
+		for (const row of rows) {
+			if (row.kind === 'row' || row.kind === 'expand')
+				virtualRealKeys.add(row.key);
+		}
+	},
+	{ flush: 'post' }
+);
+
 /**
  * Column widths of a `virtual` table, measured once from the first rendered
  * batch (key → px). A windowed body sizes its `auto` tracks from the rows it
@@ -4347,6 +4453,7 @@ watch(
 			// re-summed even if the size cache happens to hold the same count.
 			virtualRealKeys = new Set();
 			virtualMeanCacheSize = -1;
+			virtualEstimateLatched = false;
 			// New rows (a refetch, a filter) render on this tick, not the next frame.
 			flushVirtual();
 		});
@@ -4645,11 +4752,10 @@ const dataRowContext = computed<DataRowContext>(() => ({
 	keyboardNavigation: !!props.keyboardNavigation,
 	contentInert: contentInert.value,
 	hasRowIndex: hasProvidedAccessibilityData.value,
+	columnSpan: replacementContentSpan.value,
 	inputName: randomName,
 	tdClass: props.tdClass,
-	resizedKeys: resizedKeys.value,
-	clippedKeys: clippedCellKeys.value,
-	nowrapKeys: nowrapCellKeys.value,
+	cellClasses: cellStateClasses.value,
 	sortOrders: sortOrders.value,
 	// A plain table has no virtualizer: the ref is still passed, and is a no-op.
 	measureRow: measureVirtualRow,