bitboss-ui 2.1.128 → 2.1.130

package/dist/ai/BbTable.md

@@ -31,7 +31,11 @@
 				<col
 					v-for="track in columnTracks"
 					:key="track.key"
-					:style="{ width: track.width }"
+					:style="{
+						width: track.width,
+						minWidth: track.locked ? track.width : undefined,
+						maxWidth: track.locked ? track.width : undefined,
+					}"
 				/>
 			</colgroup>
 			<thead>
@@ -84,11 +88,18 @@
 							</slot>
 						</th>
 						<th
-							v-for="header in mappedHeaders"
+							v-for="(header, index) in mappedHeaders"
 							:key="header.key"
 							:aria-sort="header.sortDirection"
 							class="bb-table-header"
-							:class="header.classes"
+							:class="[
+								header.classes,
+								{
+									'bb-table-header--edge-start': index === 0,
+									'bb-table-header--edge-end':
+										index === mappedHeaders.length - 1,
+								},
+							]"
 							scope="col"
 						>
 							<!-- @vue-ignore -->
@@ -307,10 +318,17 @@
 								</slot>
 							</td>
 							<td
-								v-for="col in item.cols"
+								v-for="(col, colIndex) in item.cols"
 								:key="col.key"
 								class="bb-table-data__cell"
-								:class="col.classes"
+								:class="[
+									col.classes,
+									{
+										'bb-table-data__cell--edge-start': colIndex === 0,
+										'bb-table-data__cell--edge-end':
+											colIndex === item.cols.length - 1,
+									},
+								]"
 							>
 								<!-- @vue-ignore -->
 								<slot
@@ -509,6 +527,10 @@ const {
 } = useTableWidthContext({
 	id: () => props.id,
 	container: () => containerRef.value,
+	inheritFrom: () =>
+		typeof props.inheritColumnWidths === 'string'
+			? props.inheritColumnWidths
+			: undefined,
 });
 
 const inheritColumnWidths = computed(() => props.inheritColumnWidths !== false);
@@ -533,10 +555,13 @@ const fixedLayout = computed(
  * parent. Tables with the same column count already sum to the full width, so
  * this is a no-op for them and only narrows tables with fewer columns.
  */
-const sizeToColumns = computed(
+/** True for a nested table that inherits its column widths from a parent. */
+const isInheriting = computed(
 	() => inheritColumnWidths.value && !!parentId.value
 );
 
+const sizeToColumns = isInheriting;
+
 /** Numbers and bare numeric strings (e.g. `400`, `'400'`) default to px; values
  * that already carry a unit/keyword (`'50%'`, `'10rem'`, `'auto'`) pass through. */
 const toLength = (width: number | string) => {
@@ -545,6 +570,29 @@ const toLength = (width: number | string) => {
 	return /^-?\d*\.?\d+$/.test(trimmed) ? `${trimmed}px` : trimmed;
 };
 
+/**
+ * Resolves a CSS length to px in the context of `host`.
+ * Returns `null` when the value cannot be resolved reliably.
+ */
+const resolveLengthToPx = (
+	width: number | string,
+	host: HTMLElement
+): number | null => {
+	const length = toLength(width);
+	if (/^-?\d*\.?\d+px$/.test(length)) return parseFloat(length);
+
+	const probe = document.createElement('div');
+	probe.style.position = 'absolute';
+	probe.style.visibility = 'hidden';
+	probe.style.pointerEvents = 'none';
+	probe.style.width = length;
+	host.appendChild(probe);
+	const px = probe.getBoundingClientRect().width;
+	host.removeChild(probe);
+
+	return Number.isFinite(px) && px > 0 ? px : null;
+};
+
 /** Number of data columns the parent renders (numeric track keys). */
 const parentDataColumns = computed(() => {
 	const tracks = parentNode.value?.tracks;
@@ -637,25 +685,95 @@ const columnIntervals = computed(() => {
 	});
 });
 
+/**
+ * A column whose interval begins at or beyond the parent's last data cell has no
+ * matching parent column to inherit from — the table has more columns than its
+ * parent. Such columns are sized to their own measured content and scroll within
+ * the expand row instead of inheriting a track.
+ */
+const isOverflowColumn = (interval: { start: number }) =>
+	isInheriting.value && interval.start >= dataEndCell.value;
+
+/** True when any column overflows the parent (more columns than the parent). */
+const overflowsParent = computed(() =>
+	columnIntervals.value.some(isOverflowColumn)
+);
+
+/**
+ * A "flex" column shares a root table's leftover space (min-content floor)
+ * proportionally via the probe. Only root tables flex this way; an inheriting
+ * table instead snaps its in-range columns to the parent, content-sizes its
+ * overflow columns, and lets a single fill column take up any slack.
+ */
+const isFlexColumn = (index: number) =>
+	props.columns[index]?.width == null && !isInheriting.value;
+
+/**
+ * The last column of an inheriting table whose width is left undefined — neither
+ * a `width` nor a `snap` (a `snap` *is* a width definition: the track range it
+ * spans). That column absorbs the leftover space so the table fills its parent
+ * when a frozen/snapped column narrower than the parent's would otherwise leave a
+ * gap. `-1` for a root table, or when every column defines its own width.
+ */
+const fillColumnIndex = computed(() => {
+	if (!isInheriting.value) return -1;
+	for (let i = props.columns.length - 1; i >= 0; i--) {
+		const column = props.columns[i];
+		if (column.width == null && column.snap == null) return i;
+	}
+	return -1;
+});
+
 // Parent columns left of the first column (e.g. a select this table doesn't
 // render, or columns skipped by the first snap) and those right of the last are
 // folded into the edge columns as the structural offset, keeping the table
 // aligned to the parent. `offsetStartValue` becomes the first column's padding.
 const offsetStartValue = computed(() => {
 	const first = columnIntervals.value[0];
-	if (!inheritColumnWidths.value || !first) return null;
-	// Skip the parent's select cell only when this table renders its own.
-	const lead = props.selectable && firstDataCell.value === 1 ? 1 : 0;
-	return gridRangeWidth(lead, first.start);
+	// No parent to align to (a root table) means no offset at all — without this
+	// the structural reclaim below would still fold a negative `-ownSelect` in.
+	if (!inheritColumnWidths.value || !parentId.value || !first) return null;
+	// The fill runs from the parent's left edge to this table's first data
+	// column — the parent's select cell, if any, plus any skipped data columns.
+	const head = gridRangeWidth(0, first.start);
+	// This table's own select column sits flush at the left edge and takes its
+	// measured width, so reclaim it from the fill (mirror of the actions side):
+	// the first data column then lines the *next* column up flush with the
+	// parent. When the parent has a select cell it is part of `head`, so only the
+	// surplus over it is reclaimed; when the parent has none the whole select
+	// width comes out of the first column, which shrinks to make room for it.
+	const ownSelect = props.selectable ? structuralFit.select : null;
+	if (!ownSelect) return head;
+	return `calc(${head ?? '0px'} - ${ownSelect})`;
 });
 const offsetEndValue = computed(() => {
 	const intervals = columnIntervals.value;
 	const last = intervals[intervals.length - 1];
-	if (!inheritColumnWidths.value || !last) return null;
-	const hasActions = 'actions' in (parentNode.value?.tracks ?? {});
-	const end =
-		props.actions && hasActions ? tableEndCell.value - 1 : tableEndCell.value;
-	return gridRangeWidth(last.end, end);
+	// No parent to align to (a root table) means no offset at all — without this
+	// the structural reclaim below would still fold a negative `-ownActions` in.
+	if (!inheritColumnWidths.value || !parentId.value || !last) return null;
+	// With more columns than the parent, the table runs past the parent's right
+	// edge: there is no trailing parent region to fold, and the last column is a
+	// content-sized overflow column, so there is no end fill.
+	if (overflowsParent.value) return null;
+	// When the last column is the (auto) fill column it already absorbs the whole
+	// trailing region via fixed layout, so folding the offset in too would double
+	// it — and skew its right-aligned content inward.
+	if (fillColumnIndex.value === props.columns.length - 1) return null;
+	// The fill runs from the last data column's end all the way to the parent's
+	// right edge — any unmapped data columns plus the parent's actions cell, if
+	// it has one.
+	const tail = gridRangeWidth(last.end, tableEndCell.value);
+	// This table's own actions column sits flush against that right edge and
+	// takes its measured content width, so reclaim it from the fill: the table
+	// then ends exactly at the parent's edge instead of overflowing by the
+	// actions width. When the parent has an actions cell it is part of `tail`, so
+	// only the surplus over it is effectively reclaimed; when the parent has none
+	// the whole actions width comes out of the data fill. The result may be
+	// negative — the last data column then shrinks to make room for the actions.
+	const ownActions = props.actions ? structuralFit.actions : null;
+	if (!ownActions) return tail;
+	return `calc(${tail ?? '0px'} - ${ownActions})`;
 });
 const offsetStartActive = computed(() => offsetStartValue.value !== null);
 const offsetEndActive = computed(() => offsetEndValue.value !== null);
@@ -685,28 +803,43 @@ const columnTracks = computed(() => {
 		fixedLayout.value && structuralFit[key]
 			? (structuralFit[key] as string)
 			: sync(key);
-	const tracks: { key: string; width: string }[] = [];
+	const tracks: { key: string; width: string; locked?: boolean }[] = [];
 
 	if (props.selectable) {
-		tracks.push({ key: 'select', width: structural('select') });
+		tracks.push({ key: 'select', width: structural('select'), locked: false });
 	}
 
 	const lastIndex = props.columns.length - 1;
 	props.columns.forEach((column, index) => {
 		const key = String(index);
 		const frozen = column.width != null ? toLength(column.width) : null;
-		// For auto columns in fixed layout, use the proportional width derived
-		// from the offscreen probe so each column is pinned to a precise value
-		// rather than relying on equal-share distribution (which ignores natural
-		// content widths and can under-allocate to wider auto columns).
-		const probeWidth =
-			frozen == null && fixedLayout.value
-				? (probeColWidths.value[index] ?? null)
-				: null;
-		// The column's own width is the gridline range it spans of the parent.
 		const interval = columnIntervals.value[index];
-		const span =
-			frozen ?? probeWidth ?? gridRangeWidth(interval.start, interval.end);
+
+		// The fill column is left `auto` so fixed layout (the inheriting table has
+		// a definite `width: 100%`) hands it the leftover space — its own inherited
+		// track plus the folded edge region plus any deficit. Skipped when the
+		// table overflows: there is no leftover then, and it must content-size.
+		if (index === fillColumnIndex.value && !overflowsParent.value) {
+			tracks.push({ key, width: 'auto', locked: false });
+			return;
+		}
+
+		let span: string | null;
+		if (frozen != null) {
+			span = frozen;
+		} else if (isFlexColumn(index)) {
+			// Root table auto column: a precise share of the leftover space from the
+			// proportional probe rather than fixed layout's equal split. `auto` is
+			// the fallback before the probe runs.
+			span = (fixedLayout.value && probeColWidths.value[index]) || null;
+		} else if (isOverflowColumn(interval)) {
+			// Inheriting table, past the parent's last column: no track to snap to,
+			// so size to its own content and let the table overflow (and scroll).
+			span = columnMinWidths.value[index] ?? null;
+		} else {
+			// In range: snap to the parent's matching column.
+			span = gridRangeWidth(interval.start, interval.end);
+		}
 
 		const offsets: string[] = [];
 		if (index === 0 && offsetStartActive.value) {
@@ -722,11 +855,11 @@ const columnTracks = computed(() => {
 			? `calc(${[...offsets, span ?? '0px'].join(' + ')})`
 			: (span ?? 'auto');
 
-		tracks.push({ key, width });
+		tracks.push({ key, width, locked: frozen != null });
 	});
 
 	if (props.actions) {
-		tracks.push({ key: 'actions', width: structural('actions') });
+		tracks.push({ key: 'actions', width: structural('actions'), locked: false });
 	}
 
 	return tracks;
@@ -758,6 +891,10 @@ const containerStyle = computed(() => {
 		vars['--bb-table-natural-width'] = naturalTotalWidth.value;
 	}
 
+	if (fillValue.value > 0) {
+		vars['--bb-table-fill'] = `${fillValue.value}px`;
+	}
+
 	return vars;
 });
 
@@ -794,10 +931,19 @@ const measureStructuralFit = () => {
 	const fit = (selector: string) => {
 		let max = 0;
 		table.querySelectorAll<HTMLElement>(selector).forEach((cell) => {
-			let content = 0;
+			// Combined horizontal extent of the children, not the widest one: an
+			// actions cell holds several side-by-side controls whose total width is
+			// what the column must fit. Measured from edges so it stays correct even
+			// when the cell is narrower than its content (controls overflow on
+			// `nowrap`), which keeps the pin-to-content convergence stable.
+			let left = Infinity;
+			let right = -Infinity;
 			cell.querySelectorAll<HTMLElement>(':scope > *').forEach((child) => {
-				content = Math.max(content, child.getBoundingClientRect().width);
+				const rect = child.getBoundingClientRect();
+				left = Math.min(left, rect.left);
+				right = Math.max(right, rect.right);
 			});
+			const content = right > left ? right - left : 0;
 			const style = getComputedStyle(cell);
 			const padding =
 				parseFloat(style.paddingLeft) + parseFloat(style.paddingRight);
@@ -806,11 +952,18 @@ const measureStructuralFit = () => {
 		return max > 0 ? `${Math.ceil(max)}px` : null;
 	};
 
+	// Scoped to this table's own header/body rows: an unscoped descendant query
+	// would also match the structural cells of a nested table living in an expand
+	// row, letting a child's actions/select width hijack this table's column.
 	structuralFit.select = props.selectable
-		? fit('.bb-table-header--select, .bb-table-data__cell--select')
+		? fit(
+				':scope > thead > tr > th.bb-table-header--select, :scope > tbody > tr > td.bb-table-data__cell--select'
+			)
 		: null;
 	structuralFit.actions = props.actions
-		? fit('.bb-table-header--actions, .bb-table__cell--actions')
+		? fit(
+				':scope > thead > tr > th.bb-table-header--actions, :scope > tbody > tr > td.bb-table__cell--actions'
+			)
 		: null;
 };
 
@@ -824,14 +977,17 @@ const measure = () => {
  * data column (`null` for frozen columns — they keep their declared width).
  *
  * For each auto column the formula is:
- *   width = max(natural, available × (natural / autoTotal))
+ *   width = max(minimum, available × (minimum / minimumTotal))
  *
- * where `available` = containerWidth − frozenColumnWidths − structuralColumnWidths
- * and `autoTotal` = sum of auto-column natural widths.
+ * where `minimum` is the column's `min-content` width (what it shrinks to in a
+ * very narrow container, i.e. the floor below which content would be clipped),
+ * `available` = containerWidth − frozenColumnWidths − structuralColumnWidths
+ * and `minimumTotal` = sum of the auto columns' minimums.
  *
- * This gives proportional growth when the container is wide (auto columns scale
- * relative to each other) and a hard natural-width floor when it is narrow (the
- * table-level `min-width` then triggers horizontal overflow instead of squishing).
+ * So when the container has room (`available ≥ minimumTotal`) the slack is shared
+ * out proportionally to each column's minimum, scaling them up together; when it
+ * does not, every column drops to its minimum and the table-level `min-width`
+ * lets it overflow (the container scrolls) rather than squashing content further.
  *
  * Re-measured after any DOM mutation (debounced 200 ms) and after any container
  * resize (via a dedicated ResizeObserver on the container element).
@@ -839,19 +995,54 @@ const measure = () => {
 const probeColWidths = ref<(string | null)[]>([]);
 
 /**
- * Total natural minimum width of the table (all columns, including structural).
- * Published as `--bb-table-natural-width` and used as `min-width` on the
- * `<table>` element so fixed-layout compression never squeezes content below its
- * natural size.
+ * Each unfrozen column's measured `min-content` width (`null` for frozen). Used
+ * to content-size the overflow columns of an inheriting table — those past the
+ * parent's last column, with no track to snap to.
+ */
+const columnMinWidths = ref<(string | null)[]>([]);
+
+/**
+ * Leftover px the inheriting fill column adds so the table reaches its parent's
+ * width. Published as `--bb-table-fill`; `0` when the table already fills or
+ * overflows. Derived self-correctingly from the live total (see the probe).
+ */
+const fillValue = ref(0);
+
+/**
+ * Total minimum width of the table (all columns at their `min-content`, plus the
+ * structural columns). Published as `--bb-table-natural-width` and used as
+ * `min-width` on the `<table>` so the table scrolls horizontally only once the
+ * container is narrower than this true minimum.
  */
 const naturalTotalWidth = ref<string | null>(null);
 
+/**
+ * Width budget for probe distribution. Prefer the immediate parent's visible
+ * width (the scroll viewport) over this table's own offset width so a
+ * max-content growth loop in ancestors cannot recursively inflate probe output.
+ */
+const probeViewportWidth = (container: HTMLElement): number => {
+	const parentWidth = container.parentElement?.clientWidth ?? 0;
+	const selfWidth = container.clientWidth || container.getBoundingClientRect().width;
+	const fallback = container.offsetWidth;
+	const width = parentWidth || selfWidth || fallback;
+	return Number.isFinite(width) && width > 0 ? width : 0;
+};
+
 const runNaturalWidthProbe = () => {
 	const container = containerRef.value;
 	if (!container || !fixedLayout.value) return;
-	if (!props.columns.some((col) => col.width != null)) return;
+	// Runs for a frozen-column table (to share space), or any inheriting table
+	// (to content-size overflow columns and drive the fill column's slack).
+	if (
+		!props.columns.some((col) => col.width != null) &&
+		!overflowsParent.value &&
+		fillColumnIndex.value < 0
+	)
+		return;
 
-	const containerWidth = container.offsetWidth;
+	const containerWidth = probeViewportWidth(container);
+	if (containerWidth <= 0) return;
 	const dataOffset = props.selectable ? 1 : 0;
 
 	// ── Real-table measurements ────────────────────────────────────────────
@@ -863,22 +1054,30 @@ const runNaturalWidthProbe = () => {
 		? parseFloat(structuralFit.actions)
 		: 0;
 
-	// Frozen column widths from the live fixed-layout table — getBoundingClientRect
-	// returns the exact px value the browser computed from the declared CSS length,
-	// so no unit parsing is needed and viewport-relative units work correctly.
+	// Live rendered widths from the fixed-layout table. Frozen columns use their
+	// declared width (resolved to px) so an explicit width like `200` remains a
+	// true floor in the probe math even when the live render is under pressure.
+	// `frozenTotal` (declared widths) feeds the stable min-width floor;
+	// `nonFlexTotal` (frozen + inherited) is what the flex columns share.
 	const realThs = headerCells();
 	let frozenTotal = 0;
+	let nonFlexTotal = 0;
 	props.columns.forEach((col, i) => {
-		if (col.width != null) {
-			frozenTotal +=
-				realThs[dataOffset + i]?.getBoundingClientRect().width ?? 0;
-		}
+		const renderedWidth =
+			realThs[dataOffset + i]?.getBoundingClientRect().width ?? 0;
+		const declaredFrozenWidth =
+			col.width != null ? resolveLengthToPx(col.width, container) : null;
+		const width = declaredFrozenWidth ?? renderedWidth;
+
+		if (col.width != null) frozenTotal += width;
+		if (!isFlexColumn(i)) nonFlexTotal += width;
 	});
 
-	// ── Offscreen probe for natural (max-content) auto-column widths ───────
-	// The clone's inner table is forced to `width: max-content` and all <col>
-	// hints are stripped so each <th> reports its true content-driven width,
-	// independent of the container size or previous probe cycles.
+	// ── Offscreen probe for the auto columns' minimum (min-content) widths ──
+	// The clone's inner table is forced to `width: min-content` and the auto <col>
+	// hints are stripped so each <th> reports the narrowest width it can take
+	// before content would be clipped, independent of the container size or
+	// previous probe cycles.
 	const probe = document.createElement('div');
 	probe.style.cssText = [
 		'position:absolute',
@@ -894,11 +1093,16 @@ const runNaturalWidthProbe = () => {
 	const clone = container.cloneNode(true) as HTMLElement;
 	clone.classList.remove('bb-table--fixed');
 
-	// Frozen <col> hints are kept intact so auto columns are probed in the
-	// correct spatial context (a 400 px frozen column still occupies 400 px,
-	// giving neighbouring auto columns the right available space to size against).
-	// Only auto column hints are cleared so previous probe cycles cannot inflate
-	// their measured natural widths.
+	// Expand rows are full-width (colspan) and hold nested tables; under the
+	// auto-layout probe their content would back-pressure this table's own
+	// columns, so drop them and measure this table's columns in isolation.
+	clone
+		.querySelectorAll('.bb-table-expand__row')
+		.forEach((row) => row.remove());
+
+	// Auto <col> hints are cleared so a previous cycle's computed width cannot
+	// act as a minimum and inflate the measurement; frozen hints are left intact
+	// since their declared width is a genuine floor for that column.
 	const probeColEls = Array.from(clone.querySelectorAll<HTMLElement>('col'));
 	props.columns.forEach((col, i) => {
 		if (col.width == null) {
@@ -909,7 +1113,7 @@ const runNaturalWidthProbe = () => {
 
 	const innerTable = clone.querySelector<HTMLElement>('table');
 	if (innerTable) {
-		innerTable.style.width = 'max-content';
+		innerTable.style.width = 'min-content';
 		innerTable.style.minWidth = '0';
 	}
 
@@ -923,8 +1127,10 @@ const runNaturalWidthProbe = () => {
 		? Array.from(headerRow.querySelectorAll<HTMLElement>(':scope > th'))
 		: [];
 
-	// Only auto columns — frozen columns use their declared widths from above.
-	const autoNaturals = props.columns.map((col, i) => {
+	// Min-content of every unfrozen column (0 for frozen). Independent of the live
+	// table's width, so it is a stable basis for both the flex share and the
+	// min-width floor — unlike the rendered inherited widths.
+	const minContents = props.columns.map((col, i) => {
 		if (col.width != null) return 0;
 		const th = ths[dataOffset + i];
 		return th ? th.getBoundingClientRect().width : 0;
@@ -933,24 +1139,62 @@ const runNaturalWidthProbe = () => {
 	document.body.removeChild(probe);
 
 	// ── Proportional <col> widths ──────────────────────────────────────────
-	const autoNaturalTotal = autoNaturals.reduce((s, w) => s + w, 0);
-	const available = containerWidth - frozenTotal - selectWidth - actionsWidth;
-
-	// Scale each auto column proportionally to available space, but never
-	// below its natural content width so content is never squished.
-	probeColWidths.value = props.columns.map((col, i) => {
-		if (col.width != null) return null;
-		const natural = autoNaturals[i];
-		if (autoNaturalTotal <= 0) return `${Math.ceil(natural)}px`;
-		const share = available > 0 ? available * (natural / autoNaturalTotal) : 0;
-		return `${Math.ceil(Math.max(natural, share))}px`;
+	// Only the flex columns share `available`; the inherited columns are already
+	// laid out and excluded via `nonFlexTotal`.
+	const flexMinTotal = props.columns.reduce(
+		(s, _, i) => s + (isFlexColumn(i) ? minContents[i] : 0),
+		0
+	);
+	const available = containerWidth - nonFlexTotal - selectWidth - actionsWidth;
+
+	// Share the available space proportionally to each flex column's minimum, but
+	// never drop below that minimum — when space runs out the table overflows
+	// (and the container scrolls) instead of clipping content.
+	//
+	// Widths are kept sub-pixel (not rounded up): the raw shares sum to exactly
+	// `available`, whereas ceiling each column would over-allocate by up to a
+	// pixel apiece and, under `table-layout: fixed`, push the table a few px past
+	// the container and trip the horizontal scrollbar. `toFixed` only trims the
+	// float tail, well below the 1px a scrollbar needs.
+	const px = (n: number) => `${Number(n.toFixed(3))}px`;
+	probeColWidths.value = props.columns.map((_, i) => {
+		if (!isFlexColumn(i)) return null;
+		const minimum = minContents[i];
+		if (flexMinTotal <= 0) return px(minimum);
+		const share = available > 0 ? available * (minimum / flexMinTotal) : 0;
+		return px(Math.max(minimum, share));
 	});
 
-	// Table min-width = real frozen widths + natural auto widths + structural.
-	// Using real frozen widths (not probe) ensures declared px/rem/% lengths
-	// are respected rather than the probe's stripped-hint approximation.
+	// Min-content per unfrozen column, for content-sizing an inheriting table's
+	// overflow columns (no parent track to snap to).
+	columnMinWidths.value = minContents.map((w) => (w > 0 ? px(w) : null));
+
+	// Leftover the inheriting fill column must absorb to reach the parent's width.
+	// `parentTotal` is the parent table's full width (the expand cell this table
+	// sits in); the container itself shrink-wraps to the table, so it can't be the
+	// reference. Self-correcting: the live total already includes last cycle's
+	// fill, so adding it back recovers the intrinsic total and the result is the
+	// same once the table fills (0 when it already fills or overflows).
+	if (fillColumnIndex.value >= 0) {
+		const parentTotal = Object.values(parentNode.value?.tracks ?? {}).reduce(
+			(s, w) => s + (parseFloat(w) || 0),
+			0
+		);
+		const liveTotal = realThs.reduce(
+			(s, th) => s + th.getBoundingClientRect().width,
+			0
+		);
+		fillValue.value = Math.max(0, parentTotal - liveTotal + fillValue.value);
+	} else {
+		fillValue.value = 0;
+	}
+
+	// Table min-width = frozen (declared) widths + every unfrozen column's
+	// min-content + structural. Built only from values that do not depend on the
+	// table's own width, so it can never exceed max-content and force a stretch.
+	const minContentTotal = minContents.reduce((s, w) => s + w, 0);
 	const naturalTotal =
-		frozenTotal + autoNaturalTotal + selectWidth + actionsWidth;
+		frozenTotal + minContentTotal + selectWidth + actionsWidth;
 	naturalTotalWidth.value =
 		naturalTotal > 0 ? `${Math.ceil(naturalTotal)}px` : null;
 };
@@ -1038,6 +1282,7 @@ const containerClass = computed(() => ({
 	'bb-table--loading': loading.value,
 	'bb-table--empty': !options.value.length,
 	'bb-table--selectable': !!props.selectable,
+	'scrollbar-border': true,
 }));
 
 const replacementContentSpan = computed(
@@ -1515,10 +1760,16 @@ export type BbTableProps<Item = any> = {
 	id?: string;
 
 	/**
-	 * When `true` (the default) unfrozen columns inherit their width from the
-	 * parent table's matching track, accounting for `select`/`actions` columns.
+	 * Controls whether unfrozen columns inherit their width from an ancestor
+	 * table's matching track, accounting for `select`/`actions` columns.
+	 * - `true` (the default): inherit from the nearest ancestor table.
+	 * - `false`: do not inherit.
+	 * - 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;
+	inheritColumnWidths?: boolean | string;
 
 	/**
 	 * Boolean that defines whether to display a "Select all" checkbox.
@@ -1880,9 +2131,17 @@ export type BbTableSlots<Item = any> = {
 	--bb-table-offset-internal-end: var(--bb-table-offset-end);
 	--bb-table-offset-external-start: 0px;
 	--bb-table-offset-external-end: 0px;
+	/* Slack the fill column adds to reach the parent's width. Reset per table so a
+	   nested table never inherits an ancestor's value through the cascade. */
+	--bb-table-fill: 0px;
 	border-collapse: separate;
 	border-spacing: 0;
 	display: grid;
+	/* Override the UA `min-inline-size: min-content` that a <fieldset> container
+	   (rendered for selectable tables) carries — without this the container can't
+	   shrink below the table's content width, so it overflows its parent and
+	   pushes the page instead of scrolling inside its own `overflow-x: auto`. */
+	min-width: 0;
 	overflow-x: auto;
 	padding-inline-end: var(--bb-table-offset-external-end);
 	padding-inline-start: var(--bb-table-offset-external-start);
@@ -1912,10 +2171,22 @@ export type BbTableSlots<Item = any> = {
 			width: 100%;
 
 			thead {
+				th {
+					box-sizing: border-box;
+					min-width: 0;
+				}
+
 				.bb-table-header--actions {
 					width: auto;
 				}
 			}
+
+			tbody {
+				td {
+					box-sizing: border-box;
+					min-width: 0;
+				}
+			}
 		}
 	}
 
@@ -1963,9 +2234,21 @@ export type BbTableSlots<Item = any> = {
 	   them out of alignment. Declared after `--fixed` and the base table rule so
 	   it overrides their width/min-width at equal specificity. */
 	&--inherit-widths {
+		/* Never grow past the parent's expand cell: a child with more columns
+		   than the parent overflows the cell, so cap the container here and let its
+		   own `overflow-x: auto` scroll the surplus columns inside the expand row
+		   rather than stretching the ancestor. */
+		max-width: 100%;
+		min-width: 0;
+
 		table {
 			min-width: 0;
-			width: max-content;
+			/* A *definite* width (not `max-content`) so `table-layout: fixed` stays
+			   content-independent: inherited columns keep their colgroup widths and
+			   align with the parent instead of growing to fit content. The fill
+			   column is `auto`, so fixed layout hands it the leftover; when columns
+			   overflow, the table grows past 100% and scrolls. */
+			width: 100%;
 		}
 	}
 
@@ -2029,28 +2312,38 @@ export type BbTableSlots<Item = any> = {
 			}
 
 			td.bb-table-expand__cell {
+				/* Collapse to the content's height instead of inheriting the data-row
+				   cell height, so an expand row with no slot content takes no space. */
+				height: auto;
 				padding: 0;
+
+				&:empty {
+					display: none;
+				}
 			}
 		}
 	}
 
-	/* Apply the structural edge offsets to the first/last cell of every data
-	   row. The full-width expand and loading cells are excluded. */
-	thead tr > th:first-child,
-	tbody
-		tr
-		> td:first-child:not(.bb-table-expand__cell):not(.bb-table-loading__cell) {
+	/* Apply the structural edge offsets to the first/last *data* column. They
+	   must land on the data cells, not the absolute first/last child: a select
+	   or actions column would otherwise absorb the fill and leave the data
+	   columns misaligned with the parent (and bloat the actions cell).
+
+	   The offset is clamped at 0 here: a positive fill widens the cell and is
+	   reserved as extra edge padding, but a *negative* offset (a select/actions
+	   column reclaimed from this column's width) must not eat into the normal
+	   `--padding-x` — that only shrinks the column width, not its inner padding. */
+	thead tr > th.bb-table-header--edge-start,
+	tbody tr > td.bb-table-data__cell--edge-start {
 		padding-inline-start: calc(
-			var(--padding-x) + var(--bb-table-offset-internal-start)
+			var(--padding-x) + max(0px, var(--bb-table-offset-internal-start))
 		);
 	}
 
-	thead tr > th:last-child,
-	tbody
-		tr
-		> td:last-child:not(.bb-table-expand__cell):not(.bb-table-loading__cell) {
+	thead tr > th.bb-table-header--edge-end,
+	tbody tr > td.bb-table-data__cell--edge-end {
 		padding-inline-end: calc(
-			var(--padding-x) + var(--bb-table-offset-internal-end)
+			var(--padding-x) + max(0px, var(--bb-table-offset-internal-end))
 		);
 	}