bitboss-ui 2.1.127 → 2.1.129

package/dist/ai/BbTable.md

@@ -6,10 +6,13 @@
 <template>
 	<component
 		:is="containerTag"
+		ref="containerRef"
 		:aria-busy="loading"
 		:aria-rowcount="hasProvidedAccessibilityData ? props.totalItems : undefined"
 		:class="containerClass"
+		:data-bb-table-id="tableId"
 		:inert="disabled"
+		:style="containerStyle"
 	>
 		<legend v-if="selectable" class="sr-only">{{ legend }}</legend>
 		<table ref="tableRef">
@@ -24,6 +27,13 @@
 					caption
 				}}
 			</caption>
+			<colgroup>
+				<col
+					v-for="track in columnTracks"
+					:key="track.key"
+					:style="{ width: track.width }"
+				/>
+			</colgroup>
 			<thead>
 				<!-- @vue-ignore -->
 				<slot name="thead">
@@ -74,11 +84,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 -->
@@ -297,10 +314,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
@@ -373,7 +397,16 @@
 	lang="ts"
 	generic="Item = any, T extends ItemKey<Item> = string & {}"
 >
-import { computed, reactive, ref, toRef, watch } from 'vue';
+import {
+	computed,
+	nextTick,
+	onBeforeUnmount,
+	onMounted,
+	reactive,
+	ref,
+	toRef,
+	watch,
+} from 'vue';
 import { clamp } from '@/utilities/functions/clamp';
 import { hash } from '@/utilities/functions/hash';
 import { isNil } from '@/utilities/functions/isNil';
@@ -385,6 +418,7 @@ import { usePrefill } from '@/composables/usePrefill';
 import { useIndexById } from '@/composables/useIndexById';
 import { useBaseOptions } from '@/composables/useBaseOptions';
 import { useHashedWatcher } from '@/composables/useHashedWatcher';
+import { useTableWidthContext } from '@/composables/useTableWidthContext';
 import { useLocale } from '@/composables/useLocale';
 import BaseCheckbox from '../BaseCheckbox/BaseCheckbox.vue';
 import BaseRadio from '../BaseRadio/BaseRadio.vue';
@@ -437,6 +471,7 @@ const props = withDefaults(defineProps<InternalProps<T>>(), {
 	max: Infinity,
 	multiple: true,
 	modelValue: () => [],
+	inheritColumnWidths: true,
 	unselectedItems: () => [],
 });
 
@@ -476,6 +511,709 @@ if (props.multiple && !Array.isArray(props.modelValue)) {
 const { t } = useLocale();
 
 const tableRef = ref<HTMLTableElement>();
+const containerRef = ref<HTMLElement>();
+
+const {
+	id: tableId,
+	parentId,
+	parentNode,
+	cssVars,
+	parentVar,
+	setTracks,
+} = useTableWidthContext({
+	id: () => props.id,
+	container: () => containerRef.value,
+	inheritFrom: () =>
+		typeof props.inheritColumnWidths === 'string'
+			? props.inheritColumnWidths
+			: undefined,
+});
+
+const inheritColumnWidths = computed(() => props.inheritColumnWidths !== false);
+
+/**
+ * Assigned column widths (frozen or inherited) are only authoritative under
+ * `table-layout: fixed`; in auto layout they behave like a minimum. So a table
+ * that drives widths — explicitly `fixed`, inheriting from a parent, or with a
+ * frozen column — uses fixed layout even when `fixed` was not set.
+ */
+const fixedLayout = computed(
+	() =>
+		props.fixed ||
+		props.columns.some((column) => column.width != null) ||
+		(inheritColumnWidths.value && !!parentId.value)
+);
+
+/**
+ * A nested table inheriting its parent's widths must size itself to the sum of
+ * those columns rather than stretching to fill its container — otherwise fixed
+ * layout would distribute the slack and the columns would no longer match the
+ * 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.
+ */
+/** 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) => {
+	if (typeof width === 'number') return `${width}px`;
+	const trimmed = width.trim();
+	return /^-?\d*\.?\d+$/.test(trimmed) ? `${trimmed}px` : trimmed;
+};
+
+/** Number of data columns the parent renders (numeric track keys). */
+const parentDataColumns = computed(() => {
+	const tracks = parentNode.value?.tracks;
+	return tracks
+		? Object.keys(tracks).filter((key) => /^\d+$/.test(key)).length
+		: 0;
+});
+
+/**
+ * The parent's rendered columns in order — `select` (if any), data columns
+ * `0…N-1`, then `actions` (if any) — form a gridline coordinate, one cell per
+ * column. Cell `c` is the range `[c, c + 1]`. So a no-select parent starts its
+ * data at cell 0, while a selectable parent starts it at cell 1.
+ */
+const parentColumnKeys = computed(() => {
+	const tracks = parentNode.value?.tracks ?? {};
+	const keys: string[] = [];
+	if ('select' in tracks) keys.push('select');
+	for (let k = 0; k < parentDataColumns.value; k++) keys.push(String(k));
+	if ('actions' in tracks) keys.push('actions');
+	return keys;
+});
+
+/** Gridline cells where the parent's data region begins/ends and the table ends. */
+const firstDataCell = computed(() =>
+	'select' in (parentNode.value?.tracks ?? {}) ? 1 : 0
+);
+const dataEndCell = computed(
+	() => firstDataCell.value + parentDataColumns.value
+);
+const tableEndCell = computed(() => parentColumnKeys.value.length);
+
+/** Parent track custom property for the integer cell `[cell, cell + 1]`. */
+const cellTrackVar = (cell: number) => {
+	const key = parentColumnKeys.value[cell];
+	return key ? parentVar(key, '0px') : '0px';
+};
+
+/** CSS length summing the parent tracks across the gridline range `[a, b]`. */
+const gridRangeWidth = (a: number, b: number): string | null => {
+	if (!parentId.value || b - a <= 1e-6) return null;
+	const parts: string[] = [];
+	for (let cell = Math.floor(a); cell < Math.ceil(b - 1e-6); cell++) {
+		const fraction = Math.min(b, cell + 1) - Math.max(a, cell);
+		if (fraction <= 1e-6) continue;
+		const track = cellTrackVar(cell);
+		parts.push(
+			fraction >= 1 - 1e-6 ? track : `${Number(fraction.toFixed(4))} * ${track}`
+		);
+	}
+	if (!parts.length) return null;
+	// A bare `var()` can stand alone, but a single fractional term still needs a
+	// `calc()` wrapper for the multiplication to be valid CSS.
+	if (parts.length === 1 && !parts[0].includes('*')) return parts[0];
+	return `calc(${parts.join(' + ')})`;
+};
+
+/**
+ * Resolved parent snap interval for each data column.
+ * - A number snaps to that start point; the column then runs up to the next
+ *   column's snap point (or one whole track if the next is unset). So a single
+ *   snap that skips ahead widens this column to cover the gap — `snap: 4` on the
+ *   second column makes the first effectively `[start, 4]`.
+ * - A `[start, end]` pair is taken verbatim (`end` of `-1` runs to the end of
+ *   the data region).
+ * - Omitted, the column chains from the previous column's end.
+ */
+const columnIntervals = computed(() => {
+	const cols = props.columns;
+	// Explicit start points; a later column's snap sets the previous column's end.
+	const starts = cols.map((column) =>
+		typeof column.snap === 'number'
+			? column.snap
+			: Array.isArray(column.snap)
+				? column.snap[0]
+				: null
+	);
+	let cursor = firstDataCell.value;
+	return cols.map((column, i) => {
+		const start = starts[i] ?? cursor;
+		let end: number;
+		if (Array.isArray(column.snap)) {
+			end = column.snap[1] === -1 ? dataEndCell.value : column.snap[1];
+		} else {
+			const next = starts[i + 1];
+			end = next != null && next > start ? next : Math.floor(start) + 1;
+		}
+		cursor = end;
+		return { start, end };
+	});
+});
+
+/**
+ * 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];
+	// 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];
+	// 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);
+
+/**
+ * Measured intrinsic content widths of the structural columns. In a fixed table
+ * these pin `select`/`actions` to their content so the remaining space is shared
+ * among the data columns; `null` falls back to the regular auto behavior.
+ */
+const structuralFit = reactive<{
+	select: string | null;
+	actions: string | null;
+}>({ select: null, actions: null });
+
+/**
+ * Rendered columns in DOM order, each with the track key it publishes/inherits
+ * and the width to apply via `<colgroup>`. A frozen column width wins; otherwise
+ * an unfrozen column syncs to the parent's matching track (or `auto` at root).
+ * The first/last column additionally absorbs the structural edge offset.
+ */
+const columnTracks = computed(() => {
+	const sync = (key: string) =>
+		inheritColumnWidths.value ? parentVar(key) : 'auto';
+	// In fixed layout `auto` columns share width equally, so pin the structural
+	// columns to their measured content width and let the data columns share.
+	const structural = (key: 'select' | 'actions') =>
+		fixedLayout.value && structuralFit[key]
+			? (structuralFit[key] as string)
+			: sync(key);
+	const tracks: { key: string; width: string }[] = [];
+
+	if (props.selectable) {
+		tracks.push({ key: 'select', width: structural('select') });
+	}
+
+	const lastIndex = props.columns.length - 1;
+	props.columns.forEach((column, index) => {
+		const key = String(index);
+		const frozen = column.width != null ? toLength(column.width) : null;
+		const interval = columnIntervals.value[index];
+
+		// 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' });
+			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) {
+			offsets.push('var(--bb-table-offset-internal-start)');
+		}
+		if (index === lastIndex && offsetEndActive.value) {
+			offsets.push('var(--bb-table-offset-internal-end)');
+		}
+
+		// When folding an offset, use a calc-safe length base (no `auto`) so the
+		// column width = offset(s) + the column's own span.
+		const width = offsets.length
+			? `calc(${[...offsets, span ?? '0px'].join(' + ')})`
+			: (span ?? 'auto');
+
+		tracks.push({ key, width });
+	});
+
+	if (props.actions) {
+		tracks.push({ key: 'actions', width: structural('actions') });
+	}
+
+	return tracks;
+});
+
+/**
+ * Standalone edge-offset custom properties consumed by the first/last cell
+ * padding and the first/last column width. Set only when an offset is active;
+ * otherwise the CSS default of `0px` makes both calcs collapse to their base.
+ */
+const structuralOffset = computed<Record<string, string>>(() => {
+	const style: Record<string, string> = {};
+	if (offsetStartValue.value) {
+		style['--bb-table-offset-start'] = offsetStartValue.value;
+	}
+	if (offsetEndValue.value) {
+		style['--bb-table-offset-end'] = offsetEndValue.value;
+	}
+	return style;
+});
+
+const containerStyle = computed(() => {
+	const vars: Record<string, string> = {
+		...cssVars.value,
+		...structuralOffset.value,
+	};
+
+	if (naturalTotalWidth.value) {
+		vars['--bb-table-natural-width'] = naturalTotalWidth.value;
+	}
+
+	if (fillValue.value > 0) {
+		vars['--bb-table-fill'] = `${fillValue.value}px`;
+	}
+
+	return vars;
+});
+
+/** Reads the header cells in render order: [select?, ...data, actions?]. */
+const headerCells = () =>
+	Array.from(
+		tableRef.value?.querySelectorAll<HTMLElement>(
+			':scope > thead > tr.bb-table-header-row > th'
+		) ?? []
+	);
+
+/** Measures the rendered columns and publishes them as this table's tracks. */
+const measureTracks = () => {
+	const keys = columnTracks.value.map((track) => track.key);
+	const tracks: Record<string, string> = {};
+	headerCells().forEach((cell, index) => {
+		const key = keys[index];
+		if (key != null) tracks[key] = `${cell.getBoundingClientRect().width}px`;
+	});
+	setTracks(tracks);
+};
+
+/**
+ * Measures the intrinsic content width of the structural columns across header
+ * and body. Fixed layout sizes columns from the header row only, so the body is
+ * required here: the actions header is `sr-only`, while the real control lives
+ * in the body. The measured child width is independent of the column width, so
+ * pinning the column to it converges instead of oscillating.
+ */
+const measureStructuralFit = () => {
+	const table = tableRef.value;
+	if (!table) return;
+
+	const fit = (selector: string) => {
+		let max = 0;
+		table.querySelectorAll<HTMLElement>(selector).forEach((cell) => {
+			// 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) => {
+				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);
+			max = Math.max(max, content + padding);
+		});
+		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(
+				':scope > thead > tr > th.bb-table-header--select, :scope > tbody > tr > td.bb-table-data__cell--select'
+			)
+		: null;
+	structuralFit.actions = props.actions
+		? fit(
+				':scope > thead > tr > th.bb-table-header--actions, :scope > tbody > tr > td.bb-table__cell--actions'
+			)
+		: null;
+};
+
+const measure = () => {
+	measureStructuralFit();
+	measureTracks();
+};
+
+/**
+ * Proportional `<col>` widths derived from an auto-layout probe, one entry per
+ * data column (`null` for frozen columns — they keep their declared width).
+ *
+ * For each auto column the formula is:
+ *   width = max(minimum, available × (minimum / minimumTotal))
+ *
+ * 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.
+ *
+ * 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).
+ */
+const probeColWidths = ref<(string | null)[]>([]);
+
+/**
+ * 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);
+
+const runNaturalWidthProbe = () => {
+	const container = containerRef.value;
+	if (!container || !fixedLayout.value) 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 dataOffset = props.selectable ? 1 : 0;
+
+	// ── Real-table measurements ────────────────────────────────────────────
+	// Structural column widths come from measureStructuralFit (already run).
+	const selectWidth = structuralFit.select
+		? parseFloat(structuralFit.select)
+		: 0;
+	const actionsWidth = structuralFit.actions
+		? parseFloat(structuralFit.actions)
+		: 0;
+
+	// Live rendered widths from the fixed-layout table. `frozenTotal` (declared
+	// widths) feeds the stable min-width floor; `nonFlexTotal` (frozen + inherited)
+	// is what the flex columns share the remainder of. The inherited part is only
+	// used for that `available` figure — never fed back into min-width, since those
+	// widths stretch with the table and would otherwise lock min-width above
+	// max-content and force a spurious uniform stretch on every column.
+	const realThs = headerCells();
+	let frozenTotal = 0;
+	let nonFlexTotal = 0;
+	props.columns.forEach((col, i) => {
+		const width = realThs[dataOffset + i]?.getBoundingClientRect().width ?? 0;
+		if (col.width != null) frozenTotal += width;
+		if (!isFlexColumn(i)) nonFlexTotal += width;
+	});
+
+	// ── 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',
+		'top:-9999px',
+		'left:-9999px',
+		'visibility:hidden',
+		'pointer-events:none',
+		`width:${containerWidth}px`,
+		`height:${container.offsetHeight}px`,
+		'overflow:visible',
+	].join(';');
+
+	const clone = container.cloneNode(true) as HTMLElement;
+	clone.classList.remove('bb-table--fixed');
+
+	// 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) {
+			const probeCol = probeColEls[dataOffset + i];
+			if (probeCol) probeCol.style.width = '';
+		}
+	});
+
+	const innerTable = clone.querySelector<HTMLElement>('table');
+	if (innerTable) {
+		innerTable.style.width = 'min-content';
+		innerTable.style.minWidth = '0';
+	}
+
+	probe.appendChild(clone);
+	document.body.appendChild(probe);
+
+	const headerRow = probe.querySelector<HTMLElement>(
+		'table thead tr.bb-table-header-row'
+	);
+	const ths = headerRow
+		? Array.from(headerRow.querySelectorAll<HTMLElement>(':scope > th'))
+		: [];
+
+	// 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;
+	});
+
+	document.body.removeChild(probe);
+
+	// ── Proportional <col> widths ──────────────────────────────────────────
+	// 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));
+	});
+
+	// 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 + minContentTotal + selectWidth + actionsWidth;
+	naturalTotalWidth.value =
+		naturalTotal > 0 ? `${Math.ceil(naturalTotal)}px` : null;
+};
+
+let naturalWidthDebounceTimer: ReturnType<typeof setTimeout> | null = null;
+let mutationObserver: MutationObserver | undefined;
+
+/** Invalidates the cached natural width and schedules a fresh probe. */
+const scheduleNaturalWidthProbe = () => {
+	if (naturalWidthDebounceTimer !== null)
+		clearTimeout(naturalWidthDebounceTimer);
+	naturalWidthDebounceTimer = setTimeout(() => {
+		naturalWidthDebounceTimer = null;
+		runNaturalWidthProbe();
+	}, 200);
+};
+
+let resizeObserver: ResizeObserver | undefined;
+/** Observes the container element specifically for size changes so the
+ *  proportional <col> widths are recomputed whenever the container grows or
+ *  shrinks — separately from the header-cell observer that drives measureTracks. */
+let containerResizeObserver: ResizeObserver | undefined;
+
+const observeColumns = () => {
+	if (!resizeObserver) return;
+	resizeObserver.disconnect();
+	headerCells().forEach((cell) => resizeObserver?.observe(cell));
+	measure();
+};
+
+onMounted(() => {
+	resizeObserver = new ResizeObserver(() => measure());
+	observeColumns();
+
+	// Initial probe runs after the first render so all cells have content.
+	nextTick(runNaturalWidthProbe);
+
+	// Invalidate the cache whenever rows or cell content change.
+	if (tableRef.value) {
+		mutationObserver = new MutationObserver(scheduleNaturalWidthProbe);
+		mutationObserver.observe(tableRef.value, {
+			childList: true,
+			subtree: true,
+			characterData: true,
+		});
+	}
+
+	// Re-probe whenever the container itself is resized so that proportional
+	// <col> widths stay accurate as the available space changes.
+	if (containerRef.value) {
+		containerResizeObserver = new ResizeObserver(scheduleNaturalWidthProbe);
+		containerResizeObserver.observe(containerRef.value);
+	}
+});
+
+onBeforeUnmount(() => {
+	resizeObserver?.disconnect();
+	containerResizeObserver?.disconnect();
+	mutationObserver?.disconnect();
+	if (naturalWidthDebounceTimer !== null)
+		clearTimeout(naturalWidthDebounceTimer);
+});
+
+watch(columnTracks, () => nextTick(observeColumns), { flush: 'post' });
 
 /** Builds accessible label for selection controls from row content. */
 const getAccessibleLabel = (columns: MappedCell[]) =>
@@ -493,11 +1231,13 @@ const containerClass = computed(() => ({
 	'bb-table': true,
 	[`bb-table--align-${props.align}`]: true,
 	'bb-table--compact': props.compact,
-	'bb-table--fixed': props.fixed,
+	'bb-table--fixed': fixedLayout.value,
+	'bb-table--inherit-widths': sizeToColumns.value,
 	'bb-table--fixed-header': props.fixedHeaders,
 	'bb-table--loading': loading.value,
 	'bb-table--empty': !options.value.length,
 	'bb-table--selectable': !!props.selectable,
+	'scrollbar-border': true,
 }));
 
 const replacementContentSpan = computed(
@@ -611,6 +1351,7 @@ const mappedHeaders = computed(() =>
 				? 'ascending'
 				: 'descending'
 			: undefined;
+
 		return {
 			align,
 			key: column.key,
@@ -919,6 +1660,30 @@ export type BbTableColumn<Item = any> = BaseColumn<Item> & {
 	 * Defines the classes to be passed to the `<th>`.
 	 */
 	thClass?: Classes;
+
+	/**
+	 * 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]`.
+	 *
+	 * - 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.
+	 *
+	 * When omitted the column chains from the previous column's end to the next
+	 * whole snap point (a one-to-one inheritance by index).
+	 */
+	snap?: number | [start: number, end: number];
 };
 
 export type BbTableProps<Item = any> = {
@@ -943,6 +1708,24 @@ export type BbTableProps<Item = any> = {
 	 */
 	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;
+
+	/**
+	 * 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 | string;
+
 	/**
 	 * Boolean that defines whether to display a "Select all" checkbox.
 	 */
@@ -1291,10 +2074,32 @@ export type BbTableSlots<Item = any> = {
 	--padding-x: 16px;
 	--padding-y: 8px;
 	--actions-spacing: 8px;
+	/* Raw structural edge offset measured by the component (the parent's
+	   select/actions track width). Default 0 keeps every calc at its base. */
+	--bb-table-offset-start: 0px;
+	--bb-table-offset-end: 0px;
+	/* Routing of that offset. By default it is "internal": added to the
+	   first/last cell padding and folded into the first/last column width.
+	   Swap internal↔external (set internal to 0 and external to the raw offset)
+	   to pad the whole table instead of the edge cells. */
+	--bb-table-offset-internal-start: var(--bb-table-offset-start);
+	--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);
 
 	position: relative;
 
@@ -1367,6 +2172,40 @@ export type BbTableSlots<Item = any> = {
 		min-width: 100%;
 	}
 
+	/* A nested table inheriting its parent's widths sizes to the sum of its
+	   columns instead of filling its container, so fixed layout cannot stretch
+	   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;
+			/* 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%;
+		}
+	}
+
+	/* Declared after the base `table { min-width: 100% }` rule so it wins the
+	   cascade at equal specificity. The probe publishes the natural content width
+	   of all columns; the table fills its container freely but never compresses
+	   below that floor — the container's `overflow-x: auto` then shows a
+	   scrollbar instead of squishing content. */
+	&--fixed {
+		table {
+			min-width: var(--bb-table-natural-width, 0px);
+		}
+	}
+
 	.bb-table-caption {
 	}
 
@@ -1416,11 +2255,41 @@ 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 *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) + max(0px, var(--bb-table-offset-internal-start))
+		);
+	}
+
+	thead tr > th.bb-table-header--edge-end,
+	tbody tr > td.bb-table-data__cell--edge-end {
+		padding-inline-end: calc(
+			var(--padding-x) + max(0px, var(--bb-table-offset-internal-end))
+		);
+	}
+
 	&.bb-table--loading {
 		.bb-table-loading__row {
 			.bb-table-loading__cell {