bitboss-ui 2.1.127 → 2.1.128

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">
@@ -373,7 +383,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 +404,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 +457,7 @@ const props = withDefaults(defineProps<InternalProps<T>>(), {
 	max: Infinity,
 	multiple: true,
 	modelValue: () => [],
+	inheritColumnWidths: true,
 	unselectedItems: () => [],
 });
 
@@ -476,6 +497,524 @@ 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,
+});
+
+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.
+ */
+const sizeToColumns = computed(
+	() => inheritColumnWidths.value && !!parentId.value
+);
+
+/** 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 };
+	});
+});
+
+// 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);
+});
+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);
+});
+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;
+		// 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);
+
+		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;
+	}
+
+	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) => {
+			let content = 0;
+			cell.querySelectorAll<HTMLElement>(':scope > *').forEach((child) => {
+				content = Math.max(content, child.getBoundingClientRect().width);
+			});
+			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;
+	};
+
+	structuralFit.select = props.selectable
+		? fit('.bb-table-header--select, .bb-table-data__cell--select')
+		: null;
+	structuralFit.actions = props.actions
+		? fit('.bb-table-header--actions, .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(natural, available × (natural / autoTotal))
+ *
+ * where `available` = containerWidth − frozenColumnWidths − structuralColumnWidths
+ * and `autoTotal` = sum of auto-column natural widths.
+ *
+ * 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).
+ *
+ * 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)[]>([]);
+
+/**
+ * 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.
+ */
+const naturalTotalWidth = ref<string | null>(null);
+
+const runNaturalWidthProbe = () => {
+	const container = containerRef.value;
+	if (!container || !fixedLayout.value) return;
+	if (!props.columns.some((col) => col.width != null)) 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;
+
+	// 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.
+	const realThs = headerCells();
+	let frozenTotal = 0;
+	props.columns.forEach((col, i) => {
+		if (col.width != null) {
+			frozenTotal +=
+				realThs[dataOffset + i]?.getBoundingClientRect().width ?? 0;
+		}
+	});
+
+	// ── 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.
+	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');
+
+	// 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.
+	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 = 'max-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'))
+		: [];
+
+	// Only auto columns — frozen columns use their declared widths from above.
+	const autoNaturals = 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 ──────────────────────────────────────────
+	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`;
+	});
+
+	// 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.
+	const naturalTotal =
+		frozenTotal + autoNaturalTotal + 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,7 +1032,8 @@ 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,
@@ -611,6 +1151,7 @@ const mappedHeaders = computed(() =>
 				? 'ascending'
 				: 'descending'
 			: undefined;
+
 		return {
 			align,
 			key: column.key,
@@ -919,6 +1460,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 +1508,18 @@ 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;
+
+	/**
+	 * When `true` (the default) unfrozen columns inherit their width from the
+	 * parent table's matching track, accounting for `select`/`actions` columns.
+	 */
+	inheritColumnWidths?: boolean;
+
 	/**
 	 * Boolean that defines whether to display a "Select all" checkbox.
 	 */
@@ -1291,10 +1868,24 @@ 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;
 	border-collapse: separate;
 	border-spacing: 0;
 	display: grid;
 	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 +1958,28 @@ 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 {
+		table {
+			min-width: 0;
+			width: max-content;
+		}
+	}
+
+	/* 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 {
 	}
 
@@ -1421,6 +2034,26 @@ export type BbTableSlots<Item = any> = {
 		}
 	}
 
+	/* 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) {
+		padding-inline-start: calc(
+			var(--padding-x) + 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) {
+		padding-inline-end: calc(
+			var(--padding-x) + var(--bb-table-offset-internal-end)
+		);
+	}
+
 	&.bb-table--loading {
 		.bb-table-loading__row {
 			.bb-table-loading__cell {