bitboss-ui 2.1.113 → 2.1.115

package/dist/ai/BbTable.md

@@ -0,0 +1,1624 @@
+# BbTable
+
+## Template & Script
+
+```vue
+<template>
+	<component
+		:is="containerTag"
+		:aria-busy="loading"
+		:aria-rowcount="hasProvidedAccessibilityData ? props.totalItems : undefined"
+		:class="containerClass"
+		:inert="disabled"
+	>
+		<legend v-if="selectable" class="sr-only">{{ legend }}</legend>
+		<table ref="tableRef">
+			<caption
+				v-if="caption"
+				:class="{
+					'bb-table-caption': true,
+					'sr-only': !displayCaption,
+				}"
+			>
+				{{
+					caption
+				}}
+			</caption>
+			<thead>
+				<!-- @vue-ignore -->
+				<slot name="thead">
+					<tr
+						:aria-rowindex="hasProvidedAccessibilityData ? 1 : undefined"
+						class="bb-table-header-row"
+					>
+						<th
+							v-if="selectable"
+							class="bb-table-header bb-table-header--select"
+							:class="thClass"
+							scope="col"
+						>
+							<!-- @vue-ignore -->
+							<slot
+								:multiple="multiple"
+								:name="'header:select'"
+								:select-all="!!selectAll"
+								:text="selectText || t('table.selectText').value"
+							>
+								<span class="bb-table-header__content">
+									<label
+										v-if="allowSelectAll && multiple"
+										class="bb-table-check__label"
+										:class="{
+											'bb-table-check__label--disabled': disabled,
+										}"
+									>
+										<BaseCheckbox
+											:key="indeterminate.toString()"
+											v-model="selectAll"
+											class="bb-table-check"
+											:disabled="disabled"
+											:indeterminate="indeterminate"
+											:name="`select_all_${name || ''}`"
+											:readonly="readonly"
+										/>
+										<span class="bb-table-check__label-text sr-only"
+											>{{ selectAllLabel || t('table.selectAllLabel').value }}
+										</span>
+									</label>
+									<span
+										v-else-if="!multiple"
+										class="bb-table-radio__label-text sr-only"
+										>{{ selectText || t('table.selectText').value }}</span
+									>
+								</span>
+							</slot>
+						</th>
+						<th
+							v-for="header in mappedHeaders"
+							:key="header.key"
+							:aria-sort="header.sortDirection"
+							class="bb-table-header"
+							:class="header.classes"
+							scope="col"
+						>
+							<!-- @vue-ignore -->
+							<slot
+								:classes="header.classes"
+								:items="internalItems"
+								:label="header.label"
+								:name="header.slotName"
+								><span class="bb-table-header__content">{{
+									header.label
+								}}</span></slot
+							>
+						</th>
+						<th
+							v-if="actions"
+							class="bb-table-header bb-table-header--actions"
+							:class="thClass"
+							scope="col"
+						>
+							<!-- @vue-ignore -->
+							<slot name="header:actions" :text="actionsText">
+								<span class="bb-table-header__content sr-only">
+									{{ actionsText }}
+								</span>
+							</slot>
+						</th>
+					</tr>
+				</slot>
+			</thead>
+			<tbody>
+				<slot v-if="loading" :items="internalItems" name="loading">
+					<template v-for="(_, rowIndex) in skeletonLength" :key="rowIndex">
+						<tr
+							:aria-rowindex="
+								hasProvidedAccessibilityData ? rowIndex + 2 : undefined
+							"
+							class="bb-table-skeleton__row"
+						>
+							<td
+								v-if="selectable"
+								class="bb-table-skeleton__cell bb-table-skeleton__cell--select"
+							>
+								<div class="bb-table-skeleton__placeholder" />
+							</td>
+							<td
+								v-for="(col, colIndex) in props.columns"
+								:key="col.key"
+								:class="[
+									'bb-table-skeleton__cell',
+									`bb-table-skeleton__cell--${col.skeleton ?? 'text'}`,
+								]"
+							>
+								<!-- text: 2 lines with dynamic widths -->
+								<template v-if="!col.skeleton || col.skeleton === 'text'">
+									<div class="bb-table-skeleton__cell-content">
+										<div
+											class="bb-table-skeleton__line"
+											:style="{
+												width: `${skeletonLineWidths[(rowIndex + colIndex) % 4]}%`,
+											}"
+										/>
+										<div
+											class="bb-table-skeleton__line"
+											:style="{
+												width: `${skeletonLineWidths[(rowIndex + colIndex + 2) % 4]}%`,
+											}"
+										/>
+									</div>
+								</template>
+								<!-- avatar: circle only -->
+								<div
+									v-else-if="col.skeleton === 'avatar'"
+									class="bb-table-skeleton__avatar"
+								/>
+								<!-- avatar-text: avatar + 2 lines -->
+								<div
+									v-else-if="col.skeleton === 'avatar-text'"
+									class="bb-table-skeleton__avatar-text"
+								>
+									<div class="bb-table-skeleton__avatar" />
+									<div class="bb-table-skeleton__cell-content">
+										<div
+											class="bb-table-skeleton__line"
+											:style="{
+												width: `${skeletonLineWidths[(rowIndex + colIndex) % 4]}%`,
+											}"
+										/>
+										<div
+											class="bb-table-skeleton__line"
+											:style="{
+												width: `${skeletonLineWidths[(rowIndex + colIndex + 2) % 4]}%`,
+											}"
+										/>
+									</div>
+								</div>
+								<!-- image: rounded rect -->
+								<div
+									v-else-if="col.skeleton === 'image'"
+									class="bb-table-skeleton__image"
+								/>
+								<!-- badge: small pill -->
+								<div
+									v-else-if="col.skeleton === 'badge'"
+									class="bb-table-skeleton__badge"
+								/>
+							</td>
+							<td
+								v-if="actions"
+								class="bb-table-skeleton__cell bb-table-skeleton__cell--actions"
+							>
+								<div class="bb-table-skeleton__placeholder" />
+							</td>
+						</tr>
+					</template>
+					<tr
+						:aria-rowindex="
+							hasProvidedAccessibilityData ? skeletonLength + 2 : undefined
+						"
+						class="bb-table-loading__row bb-table-loading__row--sr-only"
+					>
+						<td
+							:colspan="replacementContentSpan"
+							class="bb-table-loading__cell"
+							aria-live="polite"
+							role="status"
+						>
+							<span class="bb-table-loading__text sr-only">{{
+								loadingText
+							}}</span>
+						</td>
+					</tr>
+				</slot>
+				<slot v-else-if="!options.length" :name="'no-data'">
+					<tr
+						:aria-rowindex="hasProvidedAccessibilityData ? 2 : undefined"
+						class="bb-table-no-data__row"
+					>
+						<td
+							class="bb-table-no-data__cell"
+							:colspan="replacementContentSpan"
+						>
+							<span class="bb-table-no-data__text">{{
+								noDataText || t('table.noDataText').value
+							}}</span>
+						</td>
+					</tr>
+				</slot>
+				<slot v-else name="tbody">
+					<template v-for="item in mappedItems" :key="item.valueHash">
+						<tr
+							:aria-rowindex="
+								hasProvidedAccessibilityData && item.rowIndex
+									? item.rowIndex
+									: undefined
+							"
+							class="bb-table-data__row"
+							@click="item.onRowClick"
+							@contextmenu="item.onRowContextMenu"
+							@dblclick="item.onRowDblClick"
+						>
+							<td
+								v-if="selectable"
+								class="bb-table-data__cell bb-table-data__cell--select"
+								:class="tdClass"
+							>
+								<!-- @vue-ignore -->
+								<slot
+									:checked="isSelected(item)"
+									:disabled="!!item.disabled"
+									:input-name="randomName"
+									:item="item.item"
+									:name="'select'"
+									:readonly="!!readonly"
+									:value="item.value"
+								>
+									<!-- We use temp names for these inputs because we don't submit them -->
+									<label
+										v-if="multiple"
+										class="bb-table-check__label"
+										:class="{
+											'bb-table-check__label--disabled': item.disabled,
+										}"
+									>
+										<BaseCheckbox
+											:checked="isSelected(item)"
+											class="bb-table-check"
+											:disabled="item.disabled"
+											:readonly="readonly"
+											@change="() => onInputChange(item)"
+										/>
+										<span class="bb-table-check__label-text sr-only">{{
+											item.accessibleLabel
+										}}</span>
+									</label>
+
+									<label
+										v-else
+										class="bb-table-radio__label"
+										:class="{
+											'bb-table-radio__label--disabled': item.disabled,
+										}"
+									>
+										<BaseRadio
+											:checked="item.selected"
+											class="bb-table-radio"
+											:disabled="item.disabled"
+											:name="randomName"
+											:readonly="readonly"
+											:value="item.value"
+											@change="() => onInputChange(item)"
+										/>
+										<span class="bb-table-radio__label-text sr-only">{{
+											item.accessibleLabel
+										}}</span>
+									</label>
+								</slot>
+							</td>
+							<td
+								v-for="col in item.cols"
+								:key="col.key"
+								class="bb-table-data__cell"
+								:class="col.classes"
+							>
+								<!-- @vue-ignore -->
+								<slot
+									:classes="col.classes"
+									:content="col.content"
+									:expanded="item.expanded"
+									:item="item.item"
+									:name="col.slotName"
+									:expand-props="getExpandControllerProps(item)"
+									:toggle-expanded="() => toggleExpandedFor(item.valueHash)"
+									:value="item.value"
+									>{{ col.content }}</slot
+								>
+							</td>
+							<td
+								v-if="actions"
+								class="bb-table__cell bb-table__cell--actions"
+								:class="tdClass"
+							>
+								<!-- @vue-ignore -->
+								<slot
+									:expanded="item.expanded"
+									:item="item.item"
+									:name="'actions'"
+									:expand-props="getExpandControllerProps(item)"
+									:toggle-expanded="() => toggleExpandedFor(item.valueHash)"
+									:value="item.value"
+								></slot>
+							</td>
+						</tr>
+						<tr
+							v-if="item.expanded"
+							:aria-rowindex="
+								hasProvidedAccessibilityData && item.rowIndex
+									? item.rowIndex + 1
+									: undefined
+							"
+							:id="`expanded_${item.valueHash}`"
+							class="bb-table-expand__row"
+						>
+							<td
+								:colspan="replacementContentSpan"
+								class="bb-table-expand__cell"
+							>
+								<!-- @vue-ignore -->
+								<slot
+									:expanded="item.expanded"
+									:item="item.item"
+									:name="'expand'"
+									:expand-props="getExpandControllerProps(item)"
+									:toggle-expanded="() => toggleExpandedFor(item.valueHash)"
+									:value="item.value"
+								></slot>
+							</td>
+						</tr>
+					</template>
+				</slot>
+			</tbody>
+			<tfoot>
+				<!-- @vue-ignore -->
+				<slot name="tfoot"></slot>
+			</tfoot>
+		</table>
+		<input v-for="input in hiddenInputs" :key="input.value" v-bind="input" />
+	</component>
+</template>
+
+<script
+	setup
+	lang="ts"
+	generic="Item = any, T extends ItemKey<Item> = string & {}"
+>
+import { computed, reactive, ref, toRef, watch } from 'vue';
+import { clamp } from '@/utilities/functions/clamp';
+import { hash } from '@/utilities/functions/hash';
+import { isNil } from '@/utilities/functions/isNil';
+import { when } from '@/utilities/functions/when';
+import { useId } from '@/composables/useId';
+import { useItemValue } from '@/composables/useItemValue';
+import { useItemsGetter } from '@/composables/useItemsGetter';
+import { usePrefill } from '@/composables/usePrefill';
+import { useIndexById } from '@/composables/useIndexById';
+import { useBaseOptions } from '@/composables/useBaseOptions';
+import { useHashedWatcher } from '@/composables/useHashedWatcher';
+import { useLocale } from '@/composables/useLocale';
+import BaseCheckbox from '../BaseCheckbox/BaseCheckbox.vue';
+import BaseRadio from '../BaseRadio/BaseRadio.vue';
+import type { Option as BaseOption } from '@/types/Option';
+import type { Classes } from '@/types/Classes';
+import type { ColumnName } from '@/types/ColumnName';
+import type { PrefixWith } from '@/types/PrefixWith';
+import type {
+	BbTableColumn,
+	BbTableEvents,
+	BbTableProps,
+	BbTableSlots,
+	ExpandControllerProps,
+	ItemKey,
+	MappedCell,
+	MappedHeader,
+	MappedItem,
+} from './types';
+import {
+	applyFixedTableColumns,
+	columnKeyToSlotName,
+	mergeCellClasses,
+	mergeHeaderClasses,
+} from './utils';
+import { useLogger } from '@/composables/useLogger';
+import { isEmpty } from '@/utilities/functions/empty';
+
+const { getItemValue } = useItemValue();
+
+/** Temporary name for selection inputs; hidden inputs handle real submission. */
+const randomName = useId().id.value;
+
+type InternalColumn<K extends string> = Omit<BbTableColumn<Item>, 'key'> & {
+	key: K;
+};
+
+type InternalProps<K extends string> = Omit<BbTableProps<Item>, 'columns'> & {
+	columns: InternalColumn<K>[];
+};
+
+const props = withDefaults(defineProps<InternalProps<T>>(), {
+	align: 'left',
+	actionsText: 'Azioni',
+	allowSelectAll: true,
+	columns: () => [],
+	dependencies: () => [],
+	depsDebounceTime: 0,
+	fixedColumns: () => [],
+	items: () => [],
+	max: Infinity,
+	multiple: true,
+	modelValue: () => [],
+	unselectedItems: () => [],
+});
+
+const emit = defineEmits<BbTableEvents>();
+
+type InferredBodySlots = ColumnName<T>;
+type InferredHeaderSlots = PrefixWith<ColumnName<T>, 'header:'>;
+
+defineSlots<
+	BbTableSlots<Item> & {
+		[K in InferredBodySlots]?: (props: {
+			classes?: Classes;
+			content?: any;
+			expanded?: boolean;
+			expandProps?: ExpandControllerProps;
+			toggleExpanded?: () => void;
+			item: Item;
+			value?: any;
+		}) => any;
+	} & {
+		[K in InferredHeaderSlots]?: (props: {
+			classes?: Classes;
+			content?: any;
+			items?: Item[];
+			label?: string;
+		}) => any;
+	}
+>();
+
+if (props.multiple && !Array.isArray(props.modelValue)) {
+	const logger = useLogger();
+	logger.throw(
+		'BbTable is set for multiple selection but modelValue is not an array.'
+	);
+}
+
+const { t } = useLocale();
+
+const tableRef = ref<HTMLTableElement>();
+
+/** Builds accessible label for selection controls from row content. */
+const getAccessibleLabel = (columns: MappedCell[]) =>
+	[t('table.select').value, ...columns.map((col) => col.content)].join(' ');
+
+const containerTag = computed(() => (props.selectable ? 'fieldset' : 'div'));
+
+const loading = computed(() => props.loading || innerLoading.value);
+
+const hasProvidedAccessibilityData = computed(
+	() => !isNil(props.page) && !isNil(props.perPage) && !isNil(props.totalItems)
+);
+
+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-header': props.fixedHeaders,
+	'bb-table--loading': loading.value,
+	'bb-table--empty': !options.value.length,
+	'bb-table--selectable': !!props.selectable,
+}));
+
+const replacementContentSpan = computed(
+	() =>
+		props.columns.length + Number(!!props.selectable) + Number(!!props.actions)
+);
+
+const slotNamesByKey = computed(() =>
+	Object.fromEntries(
+		props.columns.map((col) => [col.key, columnKeyToSlotName(col.key)])
+	)
+);
+const {
+	getter,
+	items: internalItems,
+	loading: innerLoading,
+} = useItemsGetter({
+	items: toRef(props, 'items'),
+});
+
+const { hasPrefilled } = usePrefill({
+	trigger: true,
+	fn: async (isPrefill) => {
+		await getter(isPrefill, props.modelValue);
+	},
+});
+
+const { data: modelValueIndexedByHash } = useIndexById({
+	items: toRef(props, 'modelValue'),
+});
+
+const { options } = useBaseOptions({
+	disabled: toRef(props, 'disabled'),
+	items: internalItems,
+	itemText: undefined,
+	itemValue: props.itemValue,
+	max: props.max,
+	selectable: true,
+	selectedIndexedByHash: modelValueIndexedByHash,
+});
+
+const onOptionSelected = async (option: BaseOption) => {
+	if (props.multiple) {
+		emit('update:modelValue', props.modelValue.concat(option.value));
+	} else {
+		emit('update:modelValue', option.value);
+	}
+};
+
+const onOptionUnselected = async (option: BaseOption) => {
+	if (props.multiple) {
+		const copy = { ...modelValueIndexedByHash.value };
+		delete copy[option.valueHash];
+		emit('update:modelValue', Object.values(copy));
+	} else {
+		emit('update:modelValue', null);
+	}
+};
+
+useHashedWatcher(
+	() => [props.dependencies, props.items],
+	async () => {
+		if (!hasPrefilled.value) {
+			return;
+		}
+		await getter(false, props.modelValue);
+	},
+	{
+		debounce: props.depsDebounceTime,
+	}
+);
+
+const mapColumnToCell = (
+	column: BbTableColumn<Item>,
+	item: BaseOption
+): MappedCell => {
+	const slotName = slotNamesByKey.value[column.key];
+	const align = column.align ?? 'left';
+	let content = getItemValue(item.item, column.key);
+
+	if (column.formatter && (!isNil(content) || column.formatOnNull !== false)) {
+		content = column.formatter(content, column.key, item.item);
+	}
+	if (column.placeholder && isNil(content)) {
+		content = column.placeholder;
+	}
+
+	return {
+		align,
+		classes: mergeCellClasses(
+			[`bb-table-data__cell--${align}`],
+			props.tdClass,
+			column.tdClass,
+			content,
+			column.key,
+			item.item
+		),
+		content,
+		key: column.key,
+		label: column.label,
+		slotName,
+	};
+};
+
+const mappedHeaders = computed(() =>
+	props.columns.map((column: BbTableColumn<Item>): MappedHeader => {
+		const align = column.align ?? 'left';
+		const slotName = `header:${slotNamesByKey.value[column.key]}`;
+		const sortDirection = column.sorted
+			? column.sorted === 'asc'
+				? 'ascending'
+				: 'descending'
+			: undefined;
+		return {
+			align,
+			key: column.key,
+			label: column.label,
+			slotName,
+			classes: mergeHeaderClasses(
+				[`bb-table-header--${align}`],
+				props.thClass,
+				column.thClass
+			),
+			sortDirection,
+		};
+	})
+);
+
+const mappedItems = computed<MappedItem[]>(() => {
+	let expandedRows = 0;
+	return options.value.map((item: BaseOption, index: number): MappedItem => {
+		const disabled =
+			!props.selectable ||
+			(typeof props.selectable === 'function' &&
+				!props.selectable(item.item)) ||
+			!!item.disabled;
+
+		// How many rows have passed
+		const indexPageOffset = (props.page ?? 0 - 1) * (props.perPage ?? 0);
+		const headRowOffset = 1;
+		const increment = index + 1;
+		const rowIndex = indexPageOffset + headRowOffset + increment + expandedRows;
+
+		// Create a projection of the columns and run all formatter logic so
+		// we just display content in the template
+		const cols: MappedCell[] = props.columns.map((column) =>
+			mapColumnToCell(column, item)
+		);
+		const expanded = expandedItemsIndexedByHash.value[item.valueHash] ?? false;
+		if (expanded) {
+			expandedRows++;
+		}
+		const res = {
+			accessibleLabel: getAccessibleLabel(cols),
+			cols,
+			expanded,
+			onRowClick: (event: MouseEvent) =>
+				emit('click:row', event, item, !!item.selected),
+			onRowContextMenu: (event: MouseEvent) =>
+				emit('contextmenu:row', event, item, !!item.selected),
+			onRowDblClick: (event: MouseEvent) =>
+				emit('dblclick:row', event, item, !!item.selected),
+			item: item.item,
+			text: item.text,
+			rowIndex,
+			valueHash: item.valueHash,
+			value: item.value,
+			selected: item.selected,
+			disabled,
+		};
+		return res;
+	});
+});
+
+const selectAll = defineModel<boolean>('selectAll', {
+	required: false,
+	default: false,
+});
+
+const expandedItems = defineModel<any[]>('expandedItems', {
+	required: false,
+	default: () => [],
+});
+
+const { data: expandedItemsIndexedByHash } = useIndexById({
+	items: expandedItems,
+});
+
+const onExpandControllerKeydown = (event: KeyboardEvent, valueHash: string) => {
+	if (!(event.target instanceof HTMLElement)) return;
+	if (event.target instanceof HTMLButtonElement) return;
+	if (event.key !== 'Enter' && event.key !== ' ') return;
+	event.preventDefault();
+	toggleExpandedFor(valueHash);
+};
+
+const getExpandControllerProps = (item: MappedItem) => ({
+	'aria-controls': isNil(expandedItemsIndexedByHash.value[item.valueHash])
+		? undefined
+		: `expanded_${item.valueHash}`,
+	'aria-expanded': item.expanded ? 'true' : 'false',
+	onClick: (event: MouseEvent) => {
+		event.stopPropagation();
+		toggleExpandedFor(item.valueHash);
+	},
+	onKeydown: (event: KeyboardEvent) =>
+		onExpandControllerKeydown(event, item.valueHash),
+});
+
+const toggleExpandedFor = (valueHash: string) => {
+	const linkedOption = options.value.find((o) => o.valueHash === valueHash);
+	if (!linkedOption) return;
+	if (valueHash in expandedItemsIndexedByHash.value) {
+		expandedItems.value = expandedItems.value.filter(
+			(o) => hash(o) !== valueHash
+		);
+	} else {
+		expandedItems.value = [...expandedItems.value, linkedOption.value];
+	}
+};
+
+watch(selectAll, () => {
+	unselectedItems.clear();
+	emit('update:unselectedItems', []);
+	emit('update:modelValue', []);
+});
+
+const indeterminate = computed(() => {
+	if (props.multiple && props.modelValue.length > 0 && !props.selectAll) {
+		return true;
+	}
+	if (selectAll.value && unselectedItems.size > 0) {
+		return true;
+	}
+	return false;
+});
+
+const unselectedItems = reactive(new Set<string>());
+watch(
+	() => props.unselectedItems,
+	() => {
+		unselectedItems.clear();
+		props.unselectedItems.forEach((i) => {
+			unselectedItems.add(hash(i));
+		});
+	}
+);
+
+const onInputChange = (item: BaseOption) => {
+	if (isSelected(item)) {
+		onOptionUnselected(item);
+		emit('item:unselected', item.value);
+		unselectedItems.add(item.valueHash);
+		emit('update:unselectedItems', [...props.unselectedItems, item.value]);
+		return;
+	}
+	if (!selectAll.value) {
+		onOptionSelected(item);
+	}
+	emit('item:selected', item.value);
+	unselectedItems.delete(item.valueHash);
+	emit(
+		'update:unselectedItems',
+		props.unselectedItems.filter((i) => hash(i) !== hash(item.value))
+	);
+};
+
+const isSelected = (item: BaseOption): boolean => {
+	if (unselectedItems.has(item.valueHash)) return false;
+	return item.selected || selectAll.value;
+};
+
+/**
+ * When using this component for submission we add a bunch of hidden inputs
+ * so the submitted inputs is on par with v-model
+ */
+
+/**
+ * This is used to keep the value compatible to common html expected values.
+ * Convert to string everything that's not but do not double encode strings
+ */
+const makeInputValue = when(
+	(item: unknown) => typeof item !== 'string',
+	JSON.stringify
+);
+const hiddenInputs = computed(() =>
+	[].concat(props.modelValue ?? []).map((current: unknown) => ({
+		disabled: props.disabled,
+		name: props.name,
+		type: 'hidden' as const,
+		value: makeInputValue(current),
+	}))
+);
+
+/** Varied line widths for skeleton (percent) to avoid a mechanical look */
+const skeletonLineWidths = [70, 45, 85, 55];
+
+const skeletonLength = computed(() =>
+	clamp(options.value.length || props.columns.length || 1, 4, 10)
+);
+
+watch(
+	() => [mappedItems.value, props.fixedColumns],
+	() => {
+		if (tableRef.value && props.fixedColumns?.length) {
+			applyFixedTableColumns(tableRef.value, props.fixedColumns);
+		}
+	},
+	{ flush: 'post' }
+);
+</script>
+
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+import type { Classes } from '@/types/Classes';
+import type { Option } from '@/types/Option';
+import type { InputHTMLAttributes } from 'vue';
+
+/**
+ * Recursively builds dot-notation paths from a type's keys.
+ * Depth-limited to 3 levels to avoid compiler performance issues.
+ */
+type NestedPaths<T, Depth extends unknown[] = []> = Depth['length'] extends 3
+	? never
+	: 0 extends 1 & T
+		? string
+		: T extends object
+			? T extends any[] | Date | Function | RegExp | Map<any, any> | Set<any>
+				? never
+				: {
+						[K in Extract<keyof T, string>]:
+							| K
+							| `${K}.${NestedPaths<NonNullable<T[K]>, [...Depth, unknown]>}`;
+					}[Extract<keyof T, string>]
+			: never;
+
+/**
+ * Suggested keys for a column derived from an Item type.
+ * Provides autocomplete for nested dot-notation paths (up to 3 levels)
+ * while still allowing arbitrary string keys for virtual columns.
+ */
+export type ItemKey<Item = any> = NestedPaths<Item> | (string & {});
+
+/**
+ * Skeleton placeholder style for the loading state.
+ * Matches the expected content type for a better loading experience.
+ */
+export type SkeletonType =
+	| 'text'
+	| 'avatar'
+	| 'avatar-text'
+	| 'image'
+	| 'badge';
+
+export type BaseColumn<Item = any> = {
+	/**
+	 * When set to false the formatter will not run on nullish values.
+	 * By default is true so you can create virtual columns with keys that do not
+	 * reference a prop in the `item` and still extract data from the other
+	 * arguments in the formatting function.
+	 */
+	formatOnNull?: boolean;
+
+	/**
+	 * Formatting function used to generate enhanced content.
+	 * @param content The content generated by the extraction of `Item[key]`
+	 * @param key Key of the column taken from the column definition.
+	 * @param item Item of the row.
+	 */
+	formatter?: (content: any, key: string, item: Item) => any;
+
+	/**
+	 * Key identifying the column.
+	 */
+	key: ItemKey<Item>;
+
+	/**
+	 * Text used in the header for this column.
+	 */
+	label: string;
+
+	/**
+	 * Placeholder used when the pipeline returns null content.
+	 */
+	placeholder?: string;
+};
+
+/**
+ * Column definition for BbTable. Controls data extraction, formatting, alignment, and styling.
+ */
+export type BbTableColumn<Item = any> = BaseColumn<Item> & {
+	/**
+	 * Text alignment of the column.
+	 */
+	align?: 'left' | 'right' | 'center';
+
+	/**
+	 * Skeleton placeholder style shown during loading. Defaults to `'text'`.
+	 */
+	skeleton?: SkeletonType;
+
+	/**
+	 * Defines the sorting direction of the column.
+	 */
+	sorted?: 'asc' | 'desc';
+
+	/**
+	 * Defines the classes to be passed to the `<td>` elements. Can also be a function for dynamic values.
+	 */
+	tdClass?: ColumnClasses<Item>;
+
+	/**
+	 * Defines the classes to be passed to the `<th>`.
+	 */
+	thClass?: Classes;
+};
+
+export type BbTableProps<Item = any> = {
+	/**
+	 * Function that accepts the columns and the current item as
+	 * arguments and returns a label to be used for accessibility purposes.
+	 */
+	accessibleLabel?: (columns: MappedCell[], item: any) => string;
+
+	/**
+	 * Displays the actions column.
+	 */
+	actions?: boolean;
+
+	/**
+	 * Label used in the header of the actions column.
+	 */
+	actionsText?: string;
+
+	/**
+	 * Text alignment of the columns.
+	 */
+	align?: 'left' | 'center' | 'right';
+
+	/**
+	 * Boolean that defines whether to display a "Select all" checkbox.
+	 */
+	allowSelectAll?: boolean;
+
+	/**
+	 * Caption that describes the content of the table. Used for accessibility purposes.
+	 */
+	caption?: string;
+
+	/**
+	 * Array of definitions of how the columns should be rendered.
+	 *
+	 */
+	columns: BbTableColumn<Item>[];
+
+	/**
+	 * Adds a CSS class that applies a compact style to the component.
+	 */
+	compact?: boolean;
+
+	/**
+	 * Defines an array of dependencies that will trigger actions in the component upon change.
+	 */
+	dependencies?: any[];
+
+	/**
+	 * Timeout used to debounce response to changes to dependencies.
+	 */
+	depsDebounceTime?: number;
+
+	/**
+	 * Disables the component
+	 */
+	disabled?: boolean;
+
+	/**
+	 * Boolean that defines whether to display or hide the caption.
+	 * By default is true and the caption is hidden.
+	 */
+	displayCaption?: boolean;
+
+	/**
+	 * Defines the table layout as fixed
+	 * making each column take up the same amount of space.
+	 */
+	fixed?: boolean;
+
+	/**
+	 * Definition for which column should be fixed.
+	 * It can be an array of index of the column to fix on the left side of the table or
+	 * an array of objects indicating the index and the position `left` or `right` where to affix the columns.
+	 */
+	fixedColumns?: (number | { index: number; position: 'left' | 'right' })[];
+
+	/**
+	 * Boolean that sets the headers as sticky to the top of the table.
+	 */
+	fixedHeaders?: boolean;
+
+	items:
+		| Item[]
+		| ((prefill: boolean, modelValue?: any[]) => Promise<Item[]>)
+		| ((prefill: boolean, modelValue?: any[]) => Item[]);
+
+	itemValue?: string | ((item: Item) => any);
+
+	/**
+	 * Text content of the legend.
+	 */
+	legend?: string;
+
+	/**
+	 * Sets the component in a loading state, usually triggering some visual styles.
+	 */
+	loading?: boolean;
+
+	/**
+	 * String displayed while items are being loaded.
+	 */
+	loadingText?: string;
+
+	/**
+	 * Maximum number of items that can be selected.
+	 */
+	max?: number;
+
+	/**
+	 * Used by v-model. Can be any serializable type.
+	 */
+	modelValue?: any;
+
+	/**
+	 * Allows the selection of multiple items.
+	 */
+	multiple?: boolean;
+
+	/**
+	 * Defines the name of the input.
+	 */
+	name?: InputHTMLAttributes['name'];
+
+	/**
+	 * String displayed when there are no items to display.
+	 */
+	noDataText?: string;
+
+	/**
+	 * Current page number starting from 1, used for accessibility purposes.
+	 */
+	page?: number;
+
+	/**
+	 * Number of items per page, used for accessibility purposes.
+	 */
+	perPage?: number;
+
+	/**
+	 * Sets the input in a readonly state.
+	 */
+	readonly?: boolean;
+
+	/**
+	 * Defines whether the "Select all" checkbox is checked.
+	 */
+	selectAll?: boolean;
+
+	/**
+	 * Defines whether the table is selectable.
+	 * Can be a global boolean that affects all rows or a function
+	 * that accepts an item and returns a boolean that only affects that item.
+	 */
+	selectable?: boolean | ((item: Item) => boolean);
+
+	/**
+	 * Text of the label used by the "Select all" boolean.
+	 */
+	selectAllLabel?: string;
+
+	/**
+	 * Text of the header used for the radio inputs when the table is not `multiple`.
+	 */
+	selectText?: string;
+
+	/**
+	 * Defines the classes to be passed to the `<td>` elements. Can also be a function for dynamic values.
+	 */
+	tdClass?: ColumnClasses<Item>;
+
+	/**
+	 * Defines the classes to be passed to the `<th>`.
+	 */
+	thClass?: Classes;
+
+	/**
+	 * Total number of items there is.
+	 */
+	totalItems?: number;
+
+	/**
+	 * Items that are not selected.
+	 */
+	unselectedItems?: any[];
+};
+
+/**
+ * We allow table data classes to be a function so it can depend on the item
+ */
+export type ColumnClasses<Item = any> =
+	| Classes
+	| ((content: any, key: string, item: Item) => Classes);
+
+/**
+ * Projection that represents a row of cells with flags
+ * linked to the state of the item
+ */
+export type MappedItem = Option & {
+	accessibleLabel: string;
+	cols: MappedCell[];
+	expanded: boolean;
+	onRowClick: (event: MouseEvent) => void;
+	onRowContextMenu: (event: MouseEvent) => void;
+	onRowDblClick: (event: MouseEvent) => void;
+	rowIndex: number | undefined;
+};
+
+/**
+ * Projection that represents a header
+ */
+export type MappedHeader = {
+	align: HTMLTableCellElement['align'];
+	classes?: Classes;
+	key: string;
+	label: string;
+	slotName: string;
+	sortDirection?: 'ascending' | 'descending';
+};
+
+/**
+ * Projection that represents a cell of data for display.
+ */
+export type MappedCell = {
+	align: string;
+	classes: Classes;
+	content: any;
+	key: string;
+	label: string;
+	slotName: string;
+};
+
+export type ExpandControllerProps = {
+	'aria-controls'?: string;
+	'aria-expanded': 'true' | 'false';
+	onClick: () => void;
+	onKeydown: (event: KeyboardEvent) => void;
+};
+
+export type BbTableEvents = {
+	(e: 'click:row', event: MouseEvent, item: any, selected: boolean): void;
+	(e: 'contextmenu:row', event: MouseEvent, item: any, selected: boolean): void;
+	(e: 'dblclick:row', event: MouseEvent, item: any, selected: boolean): void;
+	(e: 'update:modelValue', value: any): void;
+	(e: 'update:selectAll', value: boolean): void;
+	(e: 'update:expandedItems', value: any[]): void;
+	(e: 'update:unselectedItems', value: any[]): void;
+	(e: 'item:selected', value: any): void;
+	(e: 'item:unselected', value: any): void;
+};
+
+export type BbTableSlots<Item = any> = {
+	/**
+	 * Replaces the entire `<thead>` element. Use when you need full control over the header markup.
+	 */
+	thead?: (props: object) => any;
+	/**
+	 * Replaces the entire `<tbody>` element. Use when you need full control over the body markup.
+	 */
+	tbody?: (props: object) => any;
+	/**
+	 * Replaces the entire `<tfoot>` element. Use when you need full control over the footer markup.
+	 */
+	tfoot?: (props: object) => any;
+	/**
+	 * Replaces the default selection header cell content (checkbox or radio label).
+	 * @param multiple - Whether the table allows multiple selection.
+	 * @param selectAll - Whether the "select all" checkbox is currently checked.
+	 * @param text - The accessible label text for the select-all control.
+	 */
+	'header:select'?: (props: {
+		multiple: boolean;
+		selectAll: boolean;
+		text: string;
+	}) => any;
+	/**
+	 * Replaces the default actions header cell content.
+	 * @param text - The accessible label text for the actions column header.
+	 */
+	'header:actions'?: (props: { text: string }) => any;
+	/**
+	 * Content shown while table rows are loading (replaces the skeleton rows).
+	 * @param items - The current (possibly stale) list of items, useful to match the previous row count.
+	 */
+	loading?: (props: { items: Item[] }) => any;
+	/**
+	 * Content shown when the items list is empty and not loading.
+	 */
+	'no-data'?: (props: object) => any;
+	/**
+	 * Content rendered in the actions cell for each row.
+	 * @param expanded - Whether this row is currently expanded.
+	 * @param expandProps - Bind these onto an expand-toggle button to wire up aria attributes and keyboard handling.
+	 * @param toggleExpanded - Toggles the expanded state for this row.
+	 * @param item - The raw item for this row.
+	 * @param value - The resolved value for this row.
+	 */
+	actions?: (props: {
+		expanded?: boolean;
+		expandProps?: ExpandControllerProps;
+		toggleExpanded?: () => void;
+		item: Item;
+		value: any;
+	}) => any;
+	/**
+	 * Full-width expandable content row rendered below each main row when expanded.
+	 * @param expanded - Whether this row is currently expanded.
+	 * @param expandProps - Bind these onto an expand-toggle button to wire up aria attributes and keyboard handling.
+	 * @param toggleExpanded - Toggles the expanded state for this row.
+	 * @param item - The raw item for this row.
+	 * @param value - The resolved value for this row.
+	 */
+	expand?: (props: {
+		expanded: boolean;
+		expandProps?: ExpandControllerProps;
+		toggleExpanded: () => void;
+		item: Item;
+		value: any;
+	}) => any;
+	/**
+	 * Replaces the default checkbox/radio in the selection cell for each row.
+	 * @param item - The raw item for this row.
+	 * @param value - The resolved value for this row.
+	 * @param checked - Whether this row is currently selected.
+	 * @param disabled - Whether this row's selection control is disabled.
+	 * @param inputName - The `name` attribute for the selection input.
+	 * @param readonly - Whether the selection control is read-only.
+	 */
+	select?: (props: {
+		item: Item;
+		value: any;
+		checked: boolean;
+		disabled: boolean;
+		inputName: string;
+		readonly: boolean;
+	}) => any;
+} & {
+	/**
+	 * Named slot for a specific column cell (`col-key`) or column header (`header:col-key`).
+	 * @param classes - CSS classes computed for the cell.
+	 * @param content - The formatted cell content.
+	 * @param expanded - Whether this row is currently expanded (body slots only).
+	 * @param expandProps - Bind these onto an expand-toggle button (body slots only).
+	 * @param toggleExpanded - Toggles the expanded state for this row (body slots only).
+	 * @param item - The raw item for this row (body slots only).
+	 * @param value - The resolved row value (body slots only).
+	 * @param items - The full items list (header slots only).
+	 * @param label - The column label (header slots only).
+	 */
+	[key: string]: (props: {
+		classes?: Classes[];
+		content?: any;
+		expanded?: boolean;
+		expandProps?: ExpandControllerProps;
+		toggleExpanded?: () => void;
+		item: Item;
+		value?: any;
+		items?: Item[];
+		label?: string;
+	}) => any;
+};
+```
+
+## Styles
+
+```css
+.bb-table {
+	--padding-x: 16px;
+	--padding-y: 8px;
+	--actions-spacing: 8px;
+	border-collapse: separate;
+	border-spacing: 0;
+	display: grid;
+	overflow-x: auto;
+
+	position: relative;
+
+	&--align {
+		&-left {
+			text-align: left;
+		}
+		&-center {
+			text-align: center;
+		}
+		&-right {
+			text-align: right;
+		}
+	}
+
+	&--compact {
+		--padding-x: 8px;
+		--padding-y: 4px;
+	}
+
+	&--fixed {
+		table {
+			table-layout: fixed;
+			width: 100%;
+
+			thead {
+				.bb-table-header--actions {
+					width: auto;
+				}
+			}
+		}
+	}
+
+	&--fixed-header {
+		table {
+			thead {
+				th {
+					position: sticky;
+					top: 0;
+					z-index: 1;
+				}
+				th[style*='sticky'] {
+					position: sticky;
+					top: 0;
+					z-index: 2;
+				}
+			}
+		}
+	}
+
+	&--loading {
+	}
+
+	&--empty {
+	}
+
+	&--selectable {
+		tr {
+			> .bb-table-data__cell--select {
+				text-align: center;
+				width: 0px;
+			}
+		}
+	}
+
+	legend {
+	}
+
+	table {
+		min-width: 100%;
+	}
+
+	.bb-table-caption {
+	}
+
+	&-header-row {
+	}
+
+	&-header {
+		border-bottom: 1px solid var(--bb-border);
+		color: color-mix(in srgb, var(--bb-text), transparent 40%);
+		font-size: 14px;
+		font-weight: 500;
+		padding: var(--padding-y) var(--padding-x);
+
+		&--center {
+			text-align: center;
+		}
+
+		&--right {
+			text-align: right;
+		}
+
+		&--select {
+		}
+
+		&--actions {
+			width: 0;
+
+			.bb-table-header__content {
+			}
+		}
+
+		&__content {
+		}
+	}
+
+	tbody {
+		tr {
+			&:not(:last-child) {
+				border-bottom: 1px solid var(--bb-border);
+			}
+			td {
+				color: var(--bb-text);
+				font-size: 14px;
+				font-weight: 400;
+				height: var(--bb-table-cell-h);
+				padding: var(--padding-y) var(--padding-x);
+			}
+
+			td.bb-table-expand__cell {
+				padding: 0;
+			}
+		}
+	}
+
+	&.bb-table--loading {
+		.bb-table-loading__row {
+			.bb-table-loading__cell {
+				padding: 0 var(--padding-x) !important;
+				vertical-align: top;
+			}
+		}
+
+		.bb-table-loading__row--sr-only {
+			.bb-table-loading__cell {
+				padding: 0 !important;
+				border: none;
+				height: 0;
+				overflow: hidden;
+			}
+		}
+	}
+
+	&-skeleton {
+		&__row {
+		}
+
+		&__cell {
+			height: var(--bb-table-cell-h);
+			overflow: hidden;
+			padding: var(--padding-y) var(--padding-x);
+			vertical-align: middle;
+
+			&--select,
+			&--actions {
+				text-align: center;
+				width: 0;
+			}
+		}
+
+		&__cell-content {
+			display: flex;
+			flex-direction: column;
+			gap: 6px;
+			justify-content: center;
+			max-height: calc(var(--bb-table-cell-h) - var(--padding-y) * 2);
+			min-width: 96px;
+		}
+
+		&__line {
+			background: linear-gradient(
+				90deg,
+				var(--bb-border) 0%,
+				var(--bb-border) 35%,
+				color-mix(in srgb, var(--bb-border) 60%, white) 50%,
+				var(--bb-border) 65%,
+				var(--bb-border) 100%
+			);
+			background-size: 200% 100%;
+			border-radius: 6px;
+			flex-shrink: 0;
+			height: 10px;
+			animation: bb-table-skeleton-shimmer 1.8s ease-in-out infinite;
+		}
+
+		@media (prefers-reduced-motion: reduce) {
+			&__line {
+				animation: none;
+				background: var(--bb-border);
+			}
+		}
+
+		&__placeholder {
+			background-color: var(--bb-border);
+			border-radius: 6px;
+			flex-shrink: 0;
+			height: 22px;
+			margin: 0 auto;
+			min-width: 22px;
+			width: 22px;
+		}
+
+		&__avatar {
+			aspect-ratio: 1;
+			background-color: var(--bb-border);
+			border-radius: 50%;
+			flex-shrink: 0;
+			height: calc(var(--bb-table-cell-h) - var(--padding-y) * 2);
+			min-width: calc(var(--bb-table-cell-h) - var(--padding-y) * 2);
+			width: calc(var(--bb-table-cell-h) - var(--padding-y) * 2);
+		}
+
+		&__avatar-text {
+			align-items: center;
+			display: flex;
+			gap: 12px;
+			max-height: calc(var(--bb-table-cell-h) - var(--padding-y) * 2);
+			min-width: 140px;
+		}
+
+		&__avatar-text .bb-table-skeleton__avatar {
+			width: calc(var(--bb-table-cell-h) - var(--padding-y) * 2);
+		}
+
+		&__avatar-text .bb-table-skeleton__cell-content {
+			flex: 1;
+			min-width: 0;
+		}
+
+		&__image {
+			aspect-ratio: 4 / 3;
+			background-color: var(--bb-border);
+			border-radius: 8px;
+			height: calc(var(--bb-table-cell-h) - var(--padding-y) * 2);
+			min-width: 64px;
+			width: auto;
+		}
+
+		&__badge {
+			background-color: var(--bb-border);
+			border-radius: 999px;
+			flex-shrink: 0;
+			height: 26px;
+			min-width: 72px;
+			width: 88px;
+		}
+	}
+
+	@keyframes bb-table-skeleton-shimmer {
+		0% {
+			background-position: 200% 0;
+		}
+		100% {
+			background-position: -200% 0;
+		}
+	}
+
+	&-no-data {
+		&__row {
+		}
+		&__cell {
+		}
+		&__text {
+		}
+	}
+
+	&-data {
+		&__row {
+		}
+		&__cell {
+			&--center {
+				text-align: center;
+			}
+
+			&--right {
+				text-align: right;
+			}
+
+			&--select {
+			}
+		}
+	}
+
+	&-data-row {
+	}
+
+	&__cell {
+		&--select {
+		}
+
+		&--actions {
+			white-space: nowrap;
+			> *:not(:first-child) {
+				margin-left: var(--actions-spacing);
+			}
+		}
+	}
+
+	&-check,
+	&-radio {
+		&__label {
+			cursor: pointer;
+			display: inline-block;
+			transform: translateY(2px);
+			user-select: none;
+
+			&.bb-table {
+				&-check,
+				&-radio {
+					&__label--disabled {
+						cursor: default;
+						visibility: hidden;
+					}
+				}
+			}
+
+			&.bb-table-radio__label--disabled {
+				cursor: default;
+			}
+
+			&-text {
+			}
+		}
+	}
+}
+```