bitboss-ui 3.0.0-beta.65 → 3.0.0-beta.67

package/dist/ai/source/BbTabsList.md

@@ -6,7 +6,8 @@
 
 ```vue
 <template>
-	<div
+	<component
+		:is="linkMode ? 'nav' : 'div'"
 		class="bb-tabs-list"
 		:class="{
 			[`bb-tabs-list--${direction}`]: true,
@@ -15,7 +16,7 @@
 			'bb-tabs-list--compact': compact,
 			'bb-tabs-list--disabled': disabled,
 		}"
-		v-bind="omitName(passthrough.rootAttrs)"
+		v-bind="rootBindings()"
 	>
 		<span class="bb-tabs-list__prepend">
 			<slot name="wrapper:prepend" v-bind="scrollStatus"></slot>
@@ -23,10 +24,10 @@
 		<!-- eslint-disable vue/attributes-order -- `pt` binds LAST so a consumer attribute wins (PASSTHROUGH.md T17) -->
 		<ul
 			ref="tablist"
-			:aria-orientation="direction"
+			:aria-orientation="linkMode ? undefined : direction"
 			class="bb-tabs-list__list"
 			:class="{ 'bb-tabs-list__list--no-transition': !highlightReady }"
-			role="tablist"
+			:role="linkMode ? undefined : 'tablist'"
 			:style="{
 				'--width': `${highlightWidth}px`,
 				'--height': `${highlightHeight}px`,
@@ -49,29 +50,27 @@
 				role="presentation"
 				v-bind="passthrough.indicator"
 			></li>
-			<li v-for="tab in mappedItems" :key="tab.tabId" role="presentation">
+			<li
+				v-for="tab in mappedItems"
+				:key="tab.tabId"
+				:role="linkMode ? undefined : 'presentation'"
+			>
 				<!-- eslint-disable vue/attributes-order -- `pt` binds LAST so a consumer listener runs after ours (PASSTHROUGH.md T17) -->
 				<BbBaseButton
 					:id="tab.tabId"
-					:aria-controls="
-						tab.active || eager || tab.eager ? tab.panelId : undefined
-					"
-					:aria-selected="tab.ariaSelected"
 					class="bb-tabs-list__item"
 					:class="{ 'bb-tabs-list__item--active': tab.active }"
-					:disabled="tab.disabled"
-					role="tab"
-					:tabindex="tab.tabindex"
-					@click="tab.onClick"
-					@keydown="tab.onKeydown"
 					v-bind="
-						passthrough.part(
-							'item',
-							{
-								active: tab.active,
-								disabled: tab.disabled || undefined,
-							},
-							tab.item
+						mergeProps(
+							linkMode ? linkBindings(tab) : tabBindings(tab),
+							passthrough.part(
+								'item',
+								{
+									active: tab.active,
+									disabled: tab.disabled || undefined,
+								},
+								tab.item
+							)
 						)
 					"
 				>
@@ -90,14 +89,16 @@
 		<span class="bb-tabs-list__append">
 			<slot name="wrapper:append" v-bind="scrollStatus"></slot>
 		</span>
-	</div>
+	</component>
 </template>
 
 <script setup lang="ts">
+import type { FallthroughAttrs } from '@/types/fallthrough';
 import { removedPropsFor } from '@/deprecation/removedProps';
 import { warnRemovedAttrs } from '@/utilities/functions/warnRemovedAttrs';
 import {
 	computed,
+	mergeProps,
 	nextTick,
 	onMounted,
 	onUnmounted,
@@ -110,7 +111,7 @@ import { useLogger } from '@/composables/useLogger';
 import { usePassthrough, variantPt } from '@/composables/usePassthrough';
 import BbBaseButton from '../BbBaseButton/BbBaseButton.vue';
 import { omitName, pickName } from './tablistName';
-import { useInternalTabsContext } from '@/composables/useBbTabsContext';
+import { useInternalTabsContext } from '@/composables/useBbTabs';
 import {
 	BB_TABS_LIST_HOST_PARTS,
 	BB_TABS_LIST_PT,
@@ -138,7 +139,9 @@ defineOptions({
  * `wrapper:prepend`/`wrapper:append` slots, and keeping the active trigger in
  * view.
  */
-const props = defineProps<BbTabsListProps>();
+const props = defineProps<
+	BbTabsListProps & /* @vue-ignore */ FallthroughAttrs<'div', BbTabsListProps>
+>();
 
 // Widened with a string index so `BbTabs` can forward its whole slot bag
 // dynamically; the exported `BbTabsListSlots` stays the precise contract.
@@ -171,10 +174,45 @@ const {
 	compact,
 	disabled,
 	// Mirrors BbTabsPanels' mount rule: `aria-controls` names only a panel that
-	// is in the DOM (a lazy tab's panel is not until it is selected).
+	// is in the DOM (a lazy tab's panel is not until it is selected, and none
+	// is without panel content, Q82.6).
 	eager,
+	hasPanels,
+	linkMode,
 } = context;
 
+type MappedTab = (typeof mappedItems.value)[number];
+
+/** A tab of the tablist: roving tabindex, its panel, arrow keys. */
+const tabBindings = (tab: MappedTab) => ({
+	'aria-controls':
+		hasPanels() && (tab.active || eager.value || tab.eager)
+			? tab.panelId
+			: undefined,
+	'aria-selected': tab.ariaSelected,
+	disabled: tab.disabled,
+	role: 'tab',
+	tabindex: tab.tabindex,
+	onClick: tab.onClick,
+	onKeydown: tab.onKeydown,
+});
+
+/**
+ * A link of link mode (Q6.1): its own destination, native keyboard, and
+ * `aria-current="page"` from `model-value` alone (`undefined` also clears a
+ * router's own guess). An item with nowhere to go is a disabled link.
+ */
+const linkBindings = (tab: MappedTab) => {
+	const link = context.linkProps(tab.item);
+	const lost = link.href == null && link.to == null;
+	return {
+		...link,
+		'aria-current': tab.active ? ('page' as const) : undefined,
+		disabled: tab.disabled || lost,
+		...(lost ? { tag: 'a', role: 'link', 'aria-disabled': 'true' } : {}),
+	};
+};
+
 /**
  * Passthrough (plans/passthrough/BbTabs.md). A global / scoped `BbTabs` entry
  * for `wrapper` (as `root`) / `list` / `item` / `indicator` lands here under
@@ -201,8 +239,18 @@ const passthrough = usePassthrough<BbTabsListPtPart, BbTabsListPtState>({
 /** The strip's look: this list's own `variant`, else the root's. */
 const variant = computed(() => props.variant ?? context.variant.value);
 
-/** The list's own `pt`, after the strip's name (a `pt:list` attribute wins). */
-const listBindings = () => ({ ...pickName(attrs), ...passthrough.list });
+/**
+ * The strip's name: on the tablist, or on the `<nav>` in link mode (Q6.1).
+ * The list's own `pt` after it (a `pt:list` attribute wins).
+ */
+const listBindings = () => ({
+	...(linkMode.value ? {} : pickName(attrs)),
+	...passthrough.list,
+});
+const rootBindings = () => ({
+	...(linkMode.value ? pickName(attrs) : {}),
+	...omitName(passthrough.rootAttrs),
+});
 
 const tablist = ref<HTMLElement>();
 // `measure` re-derives `arrivedState` from the current geometry: vueuse only
@@ -423,14 +471,15 @@ useResizeObserver(tablist, () => {
 
 ```ts
 import type {
+	PtCompoundProps,
 	PtItemCtx,
-	PtItemMap,
+	PtScopedItemMap,
 	PtItemResult,
-	PtMap,
 	PtNoInfer,
 	PtValue,
 	PtVariantAttrs,
 } from '@/types/passthrough';
+import type { BbBaseButtonProps } from '@/components/BbBaseButton/types';
 import {
 	TABS_VARIANTS,
 	type TabsVariantBuiltIn,
@@ -522,23 +571,26 @@ export type BbTabsItem<K extends string = string> = BbTabsInertiaOptions & {
 	 */
 	eager?: boolean;
 	/**
-	 * Base URL this tab navigates to. The trigger always renders as a
-	 * `<button role="tab">` — never a link, so there is nothing to middle-click,
-	 * hover-preview or "copy link address" from.
-	 *
-	 * Read only in an Inertia context with `navigation` on. The component sets
-	 * `queryKey` on this URL (so `href` may not carry the tab parameter itself)
-	 * and then either rewrites the address bar client-side
-	 * (`history.pushState`/`replaceState`) or, with `server`, performs a real
-	 * `router.visit()` to it. Ignored under Vue Router/Nuxt, where the
-	 * destination is always the current route with the query patched, and
-	 * ignored entirely without `navigation`.
+	 * The page this tab links to. Any item with `href` or `to` makes the strip
+	 * a set of links (link mode): a `<nav>` of real `<a>`s with
+	 * `aria-current="page"` on the `model-value` one, instead of a tablist, so
+	 * every item needs one (an item without renders disabled). Under Inertia an
+	 * `href` is an Inertia visit carrying the strip's and the item's Inertia
+	 * options, and also takes Inertia's `{ url, method }`; elsewhere it is a
+	 * full page load (use `to` with Vue Router / Nuxt). `navigation` does not
+	 * apply to links.
+	 */
+	href?: BbBaseButtonProps['href'];
+	/**
+	 * The route this tab links to under Vue Router / Nuxt (a `RouterLink` /
+	 * `NuxtLink`). Like `href`, it puts the strip in link mode.
 	 */
-	href?: string;
+	to?: BbBaseButtonProps['to'];
 	/**
 	 * Identifies the tab: what `v-model` holds while it is the active one, the
 	 * name of its slots (`#<value>` for its panel, `#<value>:label` for its
-	 * trigger, through `slotKey`) and, with `navigation`, the URL slug.
+	 * trigger, through `slotKey`) and, with `navigation`, the URL slug. In
+	 * link mode, the `model-value` that marks it the current page.
 	 */
 	value: K;
 	/** Tabs have no `key` (that is `value`). Guards against the old shape. */
@@ -551,6 +603,8 @@ export type BbTabsItem<K extends string = string> = BbTabsInertiaOptions & {
 	 * When true and in an Inertia context, triggers a real server-side Inertia
 	 * visit (via `router.visit`) instead of a client-only `history.pushState`.
 	 * All other Inertia options and lifecycle hooks are forwarded to that visit.
+	 * The visit sets `queryKey` on the current URL, so the other query keys
+	 * (the page's filters) ride along.
 	 */
 	server?: boolean;
 };
@@ -564,9 +618,10 @@ export type BbTabsItem<K extends string = string> = BbTabsInertiaOptions & {
  * @part root - The tabs' outer element, around the strip and the panels.
  * @part wrapper - The strip's outer element: the `wrapper:prepend` slot, the
  *   triggers, the `wrapper:append` slot. `BbTabsList`'s root in a split layout.
- * @part list - The `role="tablist"` row the triggers sit in — it scrolls when
+ * @part list - The `role="tablist"` row the triggers sit in (a plain list of
+ *   links in link mode) — it scrolls when
  *   they overflow, and the indicator slides inside it.
- * @part item - One tab trigger — a broadcast resolved per tab with its own
+ * @part item - One tab trigger (a link in link mode) — a broadcast resolved per tab with its own
  *   `active` / `disabled`. Also takes a per-item function, called with the
  *   tab's descriptor.
  * @part indicator - The marker sliding under the active trigger: the pill,
@@ -599,6 +654,10 @@ export type BbTabsPtState = 'active' | 'disabled';
 export const BB_TABS_PT = {
 	parts: ['root', 'wrapper', 'list', 'item', 'indicator', 'panels', 'panel'],
 	states: ['disabled', 'active'],
+	/** On every part: what the resolver's `active` map turns on. */
+	wide: ['disabled'],
+	/** Per node: the selected tab's `item` and its `panel`. */
+	node: { item: ['active'], panel: ['active'] },
 	// The `variant` is a state on the strip's parts (Q76.7), below the real ones.
 	variant: {
 		names: TABS_VARIANTS,
@@ -608,6 +667,8 @@ export const BB_TABS_PT = {
 } as const satisfies {
 	parts: readonly BbTabsPtPart[];
 	states: readonly BbTabsPtState[];
+	wide: readonly BbTabsPtState[];
+	node: Partial<Record<BbTabsPtPart, readonly BbTabsPtState[]>>;
 	variant: {
 		names: readonly TabsVariantBuiltIn[];
 		option: string;
@@ -627,8 +688,9 @@ export type BbTabsStripPtPart = 'wrapper' | 'list' | 'item' | 'indicator';
  *
  * @part root - The strip's outer element: the `wrapper:prepend` slot, the
  *   triggers, the `wrapper:append` slot (`BbTabs`'s `wrapper`).
- * @part list - The `role="tablist"` row the triggers sit in.
- * @part item - One tab trigger, per tab with its own `active` / `disabled`.
+ * @part list - The `role="tablist"` row the triggers sit in (a plain list of
+ *   links in link mode).
+ * @part item - One tab trigger (a link in link mode), per tab with its own `active` / `disabled`.
  *   Also takes a per-item function, called with the tab's descriptor.
  * @part indicator - The marker sliding under the active trigger.
  */
@@ -641,11 +703,17 @@ export type BbTabsListPtState = BbTabsPtState;
 export const BB_TABS_LIST_PT = {
 	parts: ['root', 'list', 'item', 'indicator'],
 	states: ['disabled', 'active'],
+	/** On every part: what the resolver's `active` map turns on. */
+	wide: ['disabled'],
+	/** Per node: the selected tab. */
+	node: { item: ['active'] },
 	// The strip's `variant` is a state on every part (Q76.7).
 	variant: { names: TABS_VARIANTS, option: 'tabsVariants' },
 } as const satisfies {
 	parts: readonly BbTabsListPtPart[];
 	states: readonly BbTabsListPtState[];
+	wide: readonly BbTabsListPtState[];
+	node: Partial<Record<BbTabsListPtPart, readonly BbTabsListPtState[]>>;
 	variant: { names: readonly TabsVariantBuiltIn[]; option: string };
 };
 /** Where each `BbTabsList` part reads a `BbTabs` global / scope entry. */
@@ -673,9 +741,15 @@ export type BbTabsPanelsPtState = BbTabsPtState;
 export const BB_TABS_PANELS_PT = {
 	parts: ['root', 'panel'],
 	states: ['disabled', 'active'],
+	/** On every part: what the resolver's `active` map turns on. */
+	wide: ['disabled'],
+	/** Per node: the selected tab's panel. */
+	node: { panel: ['active'] },
 } as const satisfies {
 	parts: readonly BbTabsPanelsPtPart[];
 	states: readonly BbTabsPanelsPtState[];
+	wide: readonly BbTabsPanelsPtState[];
+	node: Partial<Record<BbTabsPanelsPtPart, readonly BbTabsPanelsPtState[]>>;
 };
 /** Where each `BbTabsPanels` part reads a `BbTabs` global / scope entry. */
 export const BB_TABS_PANELS_HOST_PARTS = {
@@ -683,16 +757,35 @@ export const BB_TABS_PANELS_HOST_PARTS = {
 	panel: 'panel',
 } as const satisfies Record<BbTabsPanelsPtPart, BbTabsPtPart>;
 
+/** Every `part` / `part:state` key of `BbTabs` — only the pairs that land (the variant keys aside). */
+export type BbTabsPtKey =
+	| BbTabsPtPart
+	| `${BbTabsPtPart}:disabled`
+	| 'item:active'
+	| 'panel:active';
+/** Every `part` / `part:state` key of `BbTabsList` — only the pairs that land (the variant keys aside). */
+export type BbTabsListPtKey =
+	| BbTabsListPtPart
+	| `${BbTabsListPtPart}:disabled`
+	| 'item:active';
+/** Every `part` / `part:state` key of `BbTabsPanels` — only the pairs that land. */
+export type BbTabsPanelsPtKey =
+	| BbTabsPanelsPtPart
+	| `${BbTabsPanelsPtPart}:disabled`
+	| 'panel:active';
+
 // Spelled INLINE with this component's own unions (PASSTHROUGH.md T20).
 // eslint-disable-next-line @typescript-eslint/consistent-indexed-object-style
 export type BbTabsProps<K extends string = string> = {
 	[K2 in
 		| `pt:${BbTabsSurfacePtPart}`
-		| `pt:${BbTabsPtPart}:${BbTabsPtState}`
+		| `pt:${BbTabsPtPart}:disabled`
+		| 'pt:item:active'
+		| 'pt:panel:active'
 		| `pt:${BbTabsStripPtPart}:${TabsVariantBuiltIn}`]?: PtValue;
-} & /* @vue-ignore */ PtVariantAttrs<
-	BbTabsStripPtPart,
-	keyof TabsVariantRegistry
+} & /* @vue-ignore */ PtCompoundProps<
+	typeof BB_TABS_PT,
+	PtVariantAttrs<BbTabsStripPtPart, keyof TabsVariantRegistry>
 > & {
 		// `item` also takes a per-item function, called with the tab descriptor.
 		// A literal function type, not `PtItemFn` (PASSTHROUGH.md T23).
@@ -710,8 +803,8 @@ export type BbTabsProps<K extends string = string> = {
 		 * without the prefix. See the `pt:<part>` row.
 		 */
 		/* eslint-disable @typescript-eslint/consistent-indexed-object-style -- mapped, never Record (T23) */
-		pt?: PtItemMap<
-			BbTabsPtPart,
+		pt?: PtScopedItemMap<
+			BbTabsPtKey,
 			'item',
 			BbTabsPtState,
 			BbTabsItem<PtNoInfer<K>>,
@@ -749,7 +842,7 @@ export type BbTabsRootProps<K extends string = string> =
 		 */
 		eager?: boolean;
 		/**
-		 * The root's `id`, and the key `useBbTabsContext(id)` pairs by. Generated
+		 * The root's `id`, and the key `useBbTabs(id)` pairs by. Generated
 		 * when omitted.
 		 */
 		id?: string;
@@ -781,17 +874,20 @@ export type BbTabsRootProps<K extends string = string> =
 		 * Arrow keys (and Home / End) only move focus; Enter or Space opens the
 		 * tab (APG manual activation, Radix `activationMode="manual"`). Unset:
 		 * on when the strip or an item has `server` (else every arrow press is
-		 * a visit), off elsewhere; `href` alone does not turn it on.
+		 * a visit), off elsewhere. Links (link mode) have no activation.
 		 *
 		 * @defaultValue `undefined` (on when `server` is set on the strip or an item)
 		 */
 		manualActivation?: boolean;
 		/**
-		 * The active tab's `value`. Used by v-model.
+		 * The active tab's `value`. Used by v-model. In link mode (items with
+		 * `href` / `to`) the page's current one, painted with
+		 * `aria-current="page"` and never emitted back.
 		 */
 		modelValue?: null | BbTabsItem<K>['value'];
 		/**
-		 * Synchronizes the current tab with the URL query parameter.
+		 * Synchronizes the current tab with the URL query parameter. Ignored in
+		 * link mode (items with `href` / `to`): a link goes to its own page.
 		 *
 		 * Pair it with `replace` unless a tab is genuinely a separate destination —
 		 * see the `replace` prop.
@@ -836,11 +932,12 @@ export type BbTabsRootProps<K extends string = string> =
 export type BbTabsListProps = {
 	[K2 in
 		| `pt:${BbTabsListSurfacePtPart}`
-		| `pt:${BbTabsListPtPart}:${BbTabsListPtState}`
+		| `pt:${BbTabsListPtPart}:disabled`
+		| 'pt:item:active'
 		| `pt:${BbTabsListPtPart}:${TabsVariantBuiltIn}`]?: PtValue;
-} & /* @vue-ignore */ PtVariantAttrs<
-	BbTabsListPtPart,
-	keyof TabsVariantRegistry
+} & /* @vue-ignore */ PtCompoundProps<
+	typeof BB_TABS_LIST_PT,
+	PtVariantAttrs<BbTabsListPtPart, keyof TabsVariantRegistry>
 > & {
 		// `item` also takes a per-item function, called with the tab descriptor.
 		// A literal function type, not `PtItemFn` (PASSTHROUGH.md T23).
@@ -858,8 +955,8 @@ export type BbTabsListProps = {
 		 * without the prefix. See the `pt:<part>` row.
 		 */
 		/* eslint-disable @typescript-eslint/consistent-indexed-object-style -- mapped, never Record (T23) */
-		pt?: PtItemMap<
-			BbTabsListPtPart,
+		pt?: PtScopedItemMap<
+			BbTabsListPtKey,
 			'item',
 			BbTabsListPtState,
 			BbTabsItem,
@@ -886,14 +983,16 @@ export type BbTabsListProps = {
 export type BbTabsPanelsProps = {
 	[K2 in
 		| `pt:${BbTabsPanelsPtPart}`
-		| `pt:${BbTabsPanelsPtPart}:${BbTabsPanelsPtState}`]?: PtValue;
-} & {
-	/**
-	 * Passthrough, object form: the same keys as the `pt:*` attributes
-	 * without the prefix. See the `pt:<part>` row.
-	 */
-	pt?: PtMap<BbTabsPanelsPtPart, BbTabsPanelsPtState>;
-};
+		| `pt:${BbTabsPanelsPtPart}:disabled`
+		| 'pt:panel:active']?: PtValue;
+} & /* @vue-ignore */ PtCompoundProps<typeof BB_TABS_PANELS_PT> & {
+		/**
+		 * Passthrough, object form: the same keys as the `pt:*` attributes
+		 * without the prefix. See the `pt:<part>` row.
+		 */
+		// eslint-disable-next-line @typescript-eslint/consistent-indexed-object-style
+		pt?: { [K2 in BbTabsPanelsPtKey]?: PtValue };
+	};
 
 export type BbTabsRootEvents<K extends string = string> = BbTabsEvents<K>;
 
@@ -958,7 +1057,7 @@ export type BbTabsListSlots<K extends string = string> = {
  * Slots rendered by the tab panels — one per tab, keyed by the normalized
  * `slotKey(value)`.
  *
- * @dynamicSlot `<value>` {BbTabsSlotProps<K>} - One tab's content panel, by the tab's `value` through `slotKey`; no fallback (an empty panel).
+ * @dynamicSlot `<value>` {BbTabsSlotProps<K>} - One tab's content panel, by the tab's `value` through `slotKey`; no fallback (an empty panel). With no panel slot at all, no panel renders and no tab has `aria-controls`.
  */
 export type BbTabsPanelsSlots<K extends string = string> = Record<
 	string,
@@ -966,7 +1065,7 @@ export type BbTabsPanelsSlots<K extends string = string> = Record<
 >;
 
 /**
- * @dynamicSlot `<value>` {BbTabsSlotProps<K>} - One tab's content panel, by the tab's `value` through `slotKey`; no fallback (an empty panel).
+ * @dynamicSlot `<value>` {BbTabsSlotProps<K>} - One tab's content panel, by the tab's `value` through `slotKey`; no fallback (an empty panel). With no panel slot at all, no panel renders and no tab has `aria-controls`.
  * @dynamicSlot `<value>:label` {BbTabsSlotProps<K>} - One tab trigger's label, by the tab's `value` through `slotKey`; beats `label`, which beats the item's `label` text.
  */
 export type BbTabsSlots<K extends string = string> = BbTabsListSlots<K> &