bitboss-ui 2.1.113 → 2.1.115

package/dist/ai/BbBreadcrumbs.md

@@ -0,0 +1,536 @@
+# BbBreadcrumbs
+
+## Template & Script
+
+```vue
+<template>
+	<nav
+		:aria-label="resolvedAriaLabel"
+		class="bb-breadcrumbs"
+		ref="navRef"
+		:style="breadcrumbsCssVariables"
+	>
+		<div class="bb-breadcrumbs__container">
+			<div
+				v-if="$slots.prepend"
+				class="bb-breadcrumbs__edge bb-breadcrumbs__edge--prepend"
+			>
+				<slot :disabled="disabled" name="prepend" />
+			</div>
+			<ol class="bb-breadcrumbs__list">
+				<!-- Overflow ellipsis + dropdown (shown when some items are hidden) -->
+				<template v-if="overflowCount > 0">
+					<li class="bb-breadcrumbs__item">
+						<BbDropdown
+							:items="overflowDropdownItems"
+							placement="bottom-start"
+							:boundary="navRef"
+							:padding="0"
+						>
+							<template #activator="{ props: activatorProps }">
+								<slot
+									name="ellipsis"
+									v-bind="{
+										props: activatorProps,
+										disabled,
+										overflowCount,
+										ellipsisWidth: resolvedEllipsisWidth,
+									}"
+								>
+									<span class="bb-breadcrumbs__breadcrumb-container">
+										<button
+											v-bind="activatorProps"
+											:aria-label="resolvedEllipsisAriaLabel"
+											class="bb-breadcrumbs__ellipsis"
+											:disabled="disabled"
+											type="button"
+										>
+											…
+										</button>
+									</span>
+								</slot>
+							</template>
+						</BbDropdown>
+						<span
+							v-if="overflowCount < items.length"
+							aria-hidden="true"
+							class="bb-breadcrumbs__divider"
+						>
+							<slot name="divider">{{ props.divider }}</slot>
+						</span>
+					</li>
+				</template>
+
+				<!-- Visible breadcrumb items (index >= overflowCount) -->
+				<template v-for="(item, index) in items" :key="item.key">
+					<template v-if="index >= overflowCount">
+						<li class="bb-breadcrumbs__item">
+							<span class="bb-breadcrumbs__breadcrumb-container">
+								<slot
+									:disabled="!!(item.disabled || disabled)"
+									:index="index"
+									:item="items[index]"
+									name="item:prepend"
+									:text="item.text"
+								/>
+								<BaseButton
+									v-bind="item"
+									:aria-current="
+										index === items.length - 1 ? 'page' : undefined
+									"
+									class="bb-breadcrumbs__breadcrumb"
+									:disabled="item.disabled || disabled"
+								>
+									<slot
+										:disabled="!!(item.disabled || disabled)"
+										:index="index"
+										:item="items[index]"
+										:name="`${item.key}`"
+										:text="item.text"
+									/>
+								</BaseButton>
+								<slot
+									:disabled="!!(item.disabled || disabled)"
+									:index="index"
+									:item="items[index]"
+									name="item:append"
+									:text="item.text"
+								/>
+							</span>
+							<span
+								v-if="index < items.length - 1"
+								aria-hidden="true"
+								class="bb-breadcrumbs__divider"
+							>
+								<slot name="divider">{{ props.divider }}</slot>
+							</span>
+						</li>
+					</template>
+				</template>
+			</ol>
+			<div
+				v-if="$slots.append"
+				class="bb-breadcrumbs__edge bb-breadcrumbs__edge--append"
+			>
+				<slot :disabled="disabled" name="append" />
+			</div>
+		</div>
+	</nav>
+</template>
+
+<script setup lang="ts">
+import { computed, onBeforeUnmount, ref, watch } from 'vue';
+import { useResizeObserver } from '@vueuse/core';
+import { useLocale } from '@/composables/useLocale';
+import BaseButton from '../BaseButton/BaseButton.vue';
+import BbDropdown from '../BbDropdown/BbDropdown.vue';
+import {
+	estimateBreadcrumbItemWidth,
+	estimateEllipsisWidth,
+} from './estimateBreadcrumbItemWidth';
+import type { BbBreadcrumbsProps, BbBreadcrumbsSlots, Item } from './types';
+export type { BbBreadcrumbsProps, BbBreadcrumbsSlots, Item };
+
+const props = withDefaults(defineProps<BbBreadcrumbsProps>(), {
+	divider: '/',
+	dividerWidth: 5,
+	estimationBias: 1.12,
+	gapWidth: 12,
+	offsetWidth: 0,
+});
+const { t } = useLocale();
+const FLEX_BASIS_OFFSET_WIDTH = 16;
+const SAFETY_MARGIN_WIDTH = 20;
+const COLLAPSE_BUFFER = 1;
+const FONT_WIDTH = 8.5;
+
+defineSlots<BbBreadcrumbsSlots>();
+
+// Template refs
+const navRef = ref<HTMLElement | null>(null);
+
+const overflowCount = ref(0);
+const resolvedGapWidth = computed(() => props.gapWidth);
+const resolvedOffsetWidth = computed(() => Math.max(0, props.offsetWidth));
+const resolvedEstimationBias = computed(() => props.estimationBias);
+const resolvedEllipsisWidth = computed(
+	() => props.ellipsisWidth ?? estimateEllipsisWidth(FONT_WIDTH)
+);
+const resolvedAriaLabel = computed(() => t('breadcrumbs.label').value);
+const resolvedEllipsisAriaLabel = computed(
+	() => t('breadcrumbs.openHiddenLabelCount', overflowCount.value).value
+);
+
+/**
+ * Estimates one breadcrumb item width using weighted character categories.
+ */
+const estimateItemWidth = (item: Item) => {
+	const label = item.text ?? String(item.key);
+	return estimateBreadcrumbItemWidth(label, {
+		estimationBias: resolvedEstimationBias.value,
+		fontWidth: FONT_WIDTH,
+	});
+};
+
+const estimatedRequiredWidth = computed(() => {
+	const n = props.items.length;
+	if (n === 0) {
+		return 0;
+	}
+
+	const dividerW = props.dividerWidth;
+	const gapW = resolvedGapWidth.value;
+	const itemWidths = props.items.map(estimateItemWidth);
+	const itemsWidth = itemWidths.reduce((sum, width) => sum + width, 0);
+	const dividerAndGapWidth = n > 1 ? (n - 1) * (dividerW + 2 * gapW) : 0;
+
+	return (
+		itemsWidth +
+		dividerAndGapWidth +
+		resolvedOffsetWidth.value +
+		SAFETY_MARGIN_WIDTH +
+		FLEX_BASIS_OFFSET_WIDTH
+	);
+});
+
+const breadcrumbsCssVariables = computed(() => ({
+	'--bb-breadcrumbs-flex-basis': `${Math.ceil(estimatedRequiredWidth.value)}px`,
+	// Allow recovery from collapsed states while keeping non-greedy behavior when fully visible.
+	'--bb-breadcrumbs-flex-grow': overflowCount.value > 0 ? '1' : '0',
+}));
+
+/**
+ * Computes the overflow count from estimated content widths.
+ */
+const recompute = (availableWidth: number) => {
+	const n = props.items.length;
+	if (n === 0) {
+		overflowCount.value = 0;
+		return;
+	}
+
+	const effectiveAvailableWidth = Math.max(
+		0,
+		availableWidth -
+			COLLAPSE_BUFFER -
+			resolvedOffsetWidth.value -
+			SAFETY_MARGIN_WIDTH
+	);
+	const dividerW = props.dividerWidth;
+	const ellipsisW = resolvedEllipsisWidth.value;
+	const gapW = resolvedGapWidth.value;
+	const itemWidths = props.items.map(estimateItemWidth);
+	const suffixSums = Array.from({ length: n + 1 }, () => 0);
+	for (let index = n - 1; index >= 0; index--) {
+		suffixSums[index] = suffixSums[index + 1] + itemWidths[index];
+	}
+	const isNearThreshold = (width: number) =>
+		effectiveAvailableWidth - width <= SAFETY_MARGIN_WIDTH / 2;
+
+	// Total width with all items and no ellipsis:
+	// item0 [gap] div0 [gap] item1 ... item_{n-1}   (last divider is display:none)
+	// = sum(items) + (n-1)*(dividerW + 2*GAP)
+	const totalNoOverflow =
+		suffixSums[0] + (n > 1 ? (n - 1) * (dividerW + 2 * gapW) : 0);
+
+	if (totalNoOverflow <= effectiveAvailableWidth) {
+		if (n > 1 && isNearThreshold(totalNoOverflow)) {
+			overflowCount.value = 1;
+			return;
+		}
+
+		overflowCount.value = 0;
+		return;
+	}
+
+	// Find the largest M (items visible from the end) such that
+	// ellipsis + M items fit: ellipsisW + M*(dividerW + 2*GAP) + sum(last M items) <= available
+	// When M=0: only ellipsis shown (the trailing divider is hidden by :last-of-type)
+	for (let M = n - 1; M >= 0; M--) {
+		const lastMSum = suffixSums[n - M];
+		const totalWithEllipsis = ellipsisW + M * (dividerW + 2 * gapW) + lastMSum;
+		if (totalWithEllipsis <= effectiveAvailableWidth) {
+			if (M > 0 && isNearThreshold(totalWithEllipsis)) {
+				overflowCount.value = n - (M - 1);
+				return;
+			}
+
+			overflowCount.value = n - M;
+			return;
+		}
+	}
+
+	// Ellipsis alone doesn't fit — overflow everything anyway
+	overflowCount.value = n;
+};
+
+// Observe this component width so overflow is based on real allocated space.
+const breadcrumbsEl = computed(() => navRef.value);
+const itemsWidthSignature = computed(() =>
+	props.items.map((item) => `${String(item.key)}::${item.text ?? ''}`).join('|')
+);
+let scheduledWidth: number | null = null;
+let scheduledFrameId: number | null = null;
+
+const flushScheduledRecompute = () => {
+	scheduledFrameId = null;
+	if (scheduledWidth == null) {
+		return;
+	}
+
+	const width = scheduledWidth;
+	scheduledWidth = null;
+	recompute(width);
+};
+
+const scheduleRecompute = (availableWidth: number) => {
+	scheduledWidth = availableWidth;
+	if (scheduledFrameId != null) {
+		return;
+	}
+
+	scheduledFrameId = requestAnimationFrame(flushScheduledRecompute);
+};
+
+useResizeObserver(breadcrumbsEl, ([entry]) => {
+	scheduleRecompute(entry.contentRect.width);
+});
+
+// Recompute when items change (text may change width)
+watch(
+	[
+		breadcrumbsEl,
+		itemsWidthSignature,
+		() => props.dividerWidth,
+		() => props.gapWidth,
+		() => props.offsetWidth,
+		() => props.estimationBias,
+		() => props.ellipsisWidth,
+	],
+	([currentBreadcrumbsEl]) => {
+		if (currentBreadcrumbsEl) {
+			scheduleRecompute(currentBreadcrumbsEl.clientWidth);
+		}
+	},
+	{ immediate: true }
+);
+
+onBeforeUnmount(() => {
+	if (scheduledFrameId != null) {
+		cancelAnimationFrame(scheduledFrameId);
+	}
+});
+
+// Map hidden items to BbDropdown item format
+const overflowDropdownItems = computed(() =>
+	props.items.slice(0, overflowCount.value).map((item) => ({
+		...item,
+		key: String(item.key),
+	}))
+);
+</script>
+
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+import type { CommonProps } from '@/types/CommonProps';
+import type { BaseButtonProps } from '../BaseButton/types';
+
+export type Item = Omit<BaseButtonProps, 'block' | 'tag' | 'type'> & {
+	/**
+	 * Click handler of the button.
+	 */
+	onClick?: (...args: any[]) => any;
+	/**
+	 * Key that uniquely identifies the breadcrumb.
+	 */
+	key: string | number;
+};
+
+export type BbBreadcrumbsProps = Pick<CommonProps, 'disabled'> & {
+	/**
+	 * Array of items that describe how the breadcrumbs should behave.
+	 * Compatible with navigating through `a` or `router-link`.
+	 */
+	items: Item[];
+	/**
+	 * Text content of the divider.
+	 */
+	divider?: string;
+	/**
+	 * Width of the divider in pixels.
+	 * @defaultValue `5`
+	 */
+	dividerWidth?: number;
+	/**
+	 * Horizontal gap between breadcrumb elements in pixels.
+	 */
+	gapWidth?: number;
+	/**
+	 * Extra one-off width in pixels added to the total estimate
+	 * (e.g. prepend/append/item slot content).
+	 */
+	offsetWidth?: number;
+	/**
+	 * Multiplier applied to each estimated item width.
+	 * A higher value will result in more over-estimation.
+	 * @defaultValue `1.12`
+	 */
+	estimationBias?: number;
+	/**
+	 * Explicit width used by the estimator for the ellipsis activator.
+	 */
+	ellipsisWidth?: number;
+};
+
+/** Props exposed by the `prepend` and `append` slots. */
+export type BbBreadcrumbsEdgeSlotProps = {
+	/** Whether the breadcrumbs are globally disabled. */
+	disabled?: boolean;
+};
+
+/** Props exposed by `item:prepend`, `item:append`, and named item slots. */
+export type BbBreadcrumbsItemSlotProps = {
+	/** Whether this item is disabled. */
+	disabled: boolean;
+	/** Zero-based index of this item. */
+	index: number;
+	/** The raw item object from the `items` prop. */
+	item: Item;
+	/** The resolved display text for this item. */
+	text?: string;
+};
+
+/** Props exposed by the `ellipsis` slot. */
+export type BbBreadcrumbsEllipsisSlotProps = {
+	/** Spread onto the activator element to wire the dropdown reference. */
+	props: {
+		/** Ref callback to register the activator element. */
+		ref: (reference: unknown) => void;
+	};
+	/** Whether the breadcrumbs are globally disabled. */
+	disabled?: boolean;
+	/** Number of items hidden in the overflow dropdown. */
+	overflowCount: number;
+	/** The calculated pixel width reserved for the ellipsis element. */
+	ellipsisWidth: number;
+};
+
+export type BbBreadcrumbsSlots = {
+	/**
+	 * Content rendered before the breadcrumb list, in a dedicated prepend region.
+	 */
+	prepend?: (props: BbBreadcrumbsEdgeSlotProps) => any;
+	/**
+	 * Content rendered after the breadcrumb list, in a dedicated append region.
+	 */
+	append?: (props: BbBreadcrumbsEdgeSlotProps) => any;
+	/**
+	 * Content rendered before each breadcrumb item's link/button.
+	 */
+	'item:prepend'?: (props: BbBreadcrumbsItemSlotProps) => any;
+	/**
+	 * Content rendered after each breadcrumb item's link/button.
+	 */
+	'item:append'?: (props: BbBreadcrumbsItemSlotProps) => any;
+	/**
+	 * Replaces the default `…` overflow button shown when items overflow.
+	 */
+	ellipsis?: (props: BbBreadcrumbsEllipsisSlotProps) => any;
+	/**
+	 * Replaces the default separator rendered between breadcrumb items.
+	 */
+	divider?: (props: object) => any;
+} & {
+	/**
+	 * Named slot for a specific breadcrumb item, keyed by `item.key`.
+	 * Replaces the default link/button content.
+	 */
+	[key: string]: (props: BbBreadcrumbsItemSlotProps) => any;
+};
+```
+
+## Styles
+
+```css
+.bb-breadcrumbs {
+	flex-basis: var(--bb-breadcrumbs-flex-basis, auto);
+	flex-grow: var(--bb-breadcrumbs-flex-grow, 0);
+	flex-shrink: 1;
+	color: var(--bb-text);
+	max-width: 100%;
+	min-width: 0;
+	position: relative;
+
+	.bb-breadcrumbs__container {
+		align-items: center;
+		column-gap: 12px;
+		display: flex;
+		flex: 1 1 auto;
+		max-width: 100%;
+		min-width: 0;
+	}
+
+	.bb-breadcrumbs__edge {
+		align-items: center;
+		display: inline-flex;
+		flex: 0 0 auto;
+	}
+
+	.bb-breadcrumbs__list {
+		align-items: center;
+		column-gap: 12px;
+		display: flex;
+		flex: 0 1 auto;
+		flex-wrap: nowrap;
+		list-style: none;
+		margin: 0;
+		max-width: 100%;
+		overflow: hidden;
+		padding: 0;
+	}
+
+	.bb-breadcrumbs__item {
+		align-items: center;
+		column-gap: 12px;
+		display: inline-flex;
+	}
+
+	.bb-breadcrumbs__breadcrumb-container {
+		align-items: center;
+		display: inline-flex;
+	}
+
+	.bb-breadcrumbs__breadcrumb {
+		line-height: normal;
+	}
+
+	.bb-breadcrumbs__ellipsis {
+		background: none;
+		border: none;
+		color: inherit;
+		cursor: pointer;
+		font-size: inherit;
+		line-height: normal;
+		min-height: 0;
+		padding: 0;
+	}
+
+	.bb-breadcrumbs__divider {
+		line-height: normal;
+	}
+
+	.bb-breadcrumbs__item:last-of-type .bb-breadcrumbs__divider {
+		display: none;
+	}
+
+	.bb-dropdown {
+		--bb-arrow: 0;
+	}
+}
+```