bitboss-ui 3.0.0-beta.63 → 3.0.0-beta.64

package/dist/ai/source/BbTooltip.md

@@ -35,6 +35,9 @@
 	`role="none"`: Chromium exposes every `[popover]` element as an unnamed group
 	of its own, around the `role="tooltip"` span (Q62.3, measured in the AX tree,
 	BbTooltip.axTree.test.ts); BbHoverCard's read-only card says the same.
+	`aria-hidden` (ATT-11): the bubble renders next to its activator, so inside a
+	`<label>` its text joined the control's name; its text reaches assistive tech
+	as the description above, and a describedby target is read even when hidden.
 	Mounted on the first open (or at once with `eager`), never before (Q63.5):
 	a closed tooltip is the description node above and the activator's
 	listeners, so a thousand of them cost half the instances and under a third of
@@ -45,6 +48,7 @@
 		ref="popover"
 		v-model="popoverOpen"
 		:anchor="activatorEl"
+		aria-hidden="true"
 		:arrow-padding="arrowPadding"
 		:boundary="boundary"
 		class="bb-tooltip"
@@ -99,17 +103,23 @@ import { removedPropsFor } from '@/deprecation/removedProps';
 import { warnRemovedAttrs } from '@/utilities/functions/warnRemovedAttrs';
 import CommonPopover from '../CommonPopover/CommonPopover.vue';
 import { useElementSize } from '@vueuse/core';
-import { extractDomContainer } from '@/utilities/functions/extractDomContainer';
+import {
+	domElement,
+	extractDomContainer,
+	type DomHost,
+} from '@/utilities/functions/extractDomContainer';
 import {
 	BB_TOOLTIP_PT,
 	type BbTooltipProps,
 	type BbTooltipSlots,
 } from './types';
-import { usePassthrough } from '@/composables/usePassthrough';
+import { usePassthrough, variantPt } from '@/composables/usePassthrough';
 import { transitions } from '@/utilities/misc/transitions';
 export type { BbTooltipProps, BbTooltipSlots };
 
 defineOptions({
+	// An app's own variants as declared `pt:<part>:<name>` props (Q76.7).
+	mixins: [variantPt(BB_TOOLTIP_PT)],
 	inheritAttrs: false,
 });
 
@@ -141,6 +151,7 @@ const passthrough = usePassthrough({
 	parts: BB_TOOLTIP_PT.parts,
 	states: BB_TOOLTIP_PT.states,
 	active: { open: () => open.value },
+	variant: { ...BB_TOOLTIP_PT.variant, current: () => props.variant },
 });
 
 if (process.env.NODE_ENV !== 'production')
@@ -191,7 +202,7 @@ const resolvedDescription = computed(() => {
 		props.text ?? (canReadSlots.value ? slotToText(slots.default?.({})) : '');
 	return raw.replace(/\s+/g, ' ').trim();
 });
-const activatorEl = ref<HTMLElement>();
+const activatorEl = ref<DomHost>();
 const hasExternalActivator = computed(() => props.activator != null);
 const popoverRef = useTemplateRef('popover');
 const popoverDom = computed(() => extractDomContainer(popoverRef.value));
@@ -357,10 +368,19 @@ watch(
 
 // --- Sync external activator prop ---
 
+// A selector is looked up once the tooltip is in the document (the whole render
+// is by `onMounted`), and again whenever the prop changes.
+const isMounted = ref(false);
+onMounted(() => {
+	isMounted.value = true;
+});
+
 watch(
-	() => props.activator,
-	(val) => {
-		if (val) setActivatorRef(val);
+	[() => props.activator, isMounted],
+	([val, mounted]) => {
+		if (typeof val !== 'string') {
+			if (val) setActivatorRef(val);
+		} else if (mounted) setActivatorRef(document.querySelector(val));
 	},
 	{ immediate: true }
 );
@@ -426,9 +446,9 @@ watch(
 const ownTokens = new Set([id, descId]);
 
 /** The element currently carrying our token, so an activator swap can clean it. */
-let describedByHost: HTMLElement | null = null;
+let describedByHost: DomHost | null = null;
 
-const setDescribedBy = (el: HTMLElement, token: string | null) => {
+const setDescribedBy = (el: DomHost, token: string | null) => {
 	const tokens = (el.getAttribute('aria-describedby') ?? '')
 		.split(/\s+/)
 		.filter((entry) => entry && !ownTokens.has(entry));
@@ -498,7 +518,9 @@ const percentWidth = computed(() => {
 // Only `%` widths need the activator measured — skip the ResizeObserver for
 // fixed widths and the (common) no-width case.
 const { width: activatorWidth } = useElementSize(
-	computed(() => (percentWidth.value != null ? activatorEl.value : undefined)),
+	computed(() =>
+		domElement(percentWidth.value != null ? activatorEl.value : undefined)
+	),
 	{ width: 0, height: 0 },
 	{
 		box: 'border-box',
@@ -544,12 +566,14 @@ onDeactivated(forceClose);
 ## Types
 
 ```ts
-import type { TooltipVariantType } from '@/types/TooltipVariant';
-import type { PtMap, PtValue } from '@/types/passthrough';
-import type {
-	ElementOrComponentRef,
-	ElementOrComponentRefOrSelector,
-} from '@/types/CommonProps';
+import {
+	TOOLTIP_VARIANTS,
+	type TooltipVariantBuiltIn,
+	type TooltipVariantRegistry,
+	type TooltipVariantType,
+} from '@/types/TooltipVariant';
+import type { PtMap, PtValue, PtVariantAttrs } from '@/types/passthrough';
+import type { ElementOrComponentRefOrSelector } from '@/types/CommonProps';
 import type { Placement } from '@/types/Placement';
 
 /**
@@ -577,9 +601,12 @@ export type BbTooltipPtState = 'open';
 export const BB_TOOLTIP_PT = {
 	parts: ['root', 'panel'],
 	states: ['open'],
+	// The `variant` is a state on every part (Q76.7), below `open`.
+	variant: { names: TOOLTIP_VARIANTS, option: 'tooltipVariants' },
 } as const satisfies {
 	parts: readonly BbTooltipPtPart[];
 	states: readonly BbTooltipPtState[];
+	variant: { names: readonly TooltipVariantBuiltIn[]; option: string };
 };
 
 // Spelled INLINE with this component's own unions (Vue's SFC type resolver
@@ -588,104 +615,112 @@ export const BB_TOOLTIP_PT = {
 export type BbTooltipProps = {
 	[K in
 		| `pt:${BbTooltipPtPart}`
-		| `pt:${BbTooltipPtPart}:${BbTooltipPtState}`]?: PtValue;
-} & {
-	/**
-	 * Passthrough, object form: the same keys as the `pt:*` attributes
-	 * without the prefix. See the `pt:<part>` row.
-	 */
-	pt?: PtMap<BbTooltipPtPart, BbTooltipPtState>;
-	/**
-	 * Space the arrow will maintain to the edge of the tooltip bubble.
-	 * Useful when the floating element has border radius so it won't appear broken
-	 *
-	 * @defaultValue `10`
-	 */
-	arrowPadding?: number;
-	/**
-	 * Disables the component
-	 */
-	disabled?: boolean;
-	/**
-	 * Renders the tooltip's popover and content at mount instead of on the
-	 * first open. The description screen readers hear exists from mount either
-	 * way.
-	 */
-	eager?: boolean;
-	/**
-	 * Hides the tooltip arrow. A tooltip shows its arrow by default (it's the
-	 * one popover-family surface where an arrow is meaningful — a speech bubble
-	 * pointing at its anchor); set this to drop it.
-	 *
-	 * @defaultValue `false`
-	 */
-	hideArrow?: boolean;
-	/**
-	 * Seed for the tooltip's internal id. It is **prefixed** (`bb_<id>`) and set
-	 * on the inner content element, not on the root — so
-	 * `document.getElementById(theIdYouPassed)` finds nothing. Pass it to make
-	 * the generated id stable (SSR snapshots, tests), not to look the element
-	 * up.
-	 */
-	id?: string;
-	/**
-	 * Minimum empty space to keep from the edge of the page
-	 *
-	 * @defaultValue `10`
-	 */
-	padding?: number;
-	/**
-	 * Position of the overlay in respect to the related activator.
-	 *
-	 * @defaultValue `'top'`
-	 */
-	placement?: Placement;
-	/**
-	 * Text content of the component.
-	 */
-	text?: string;
-	/**
-	 * How long the transition has to last in milliseconds
-	 *
-	 * @defaultValue `250`
-	 */
-	transitionDuration?: number;
-	/**
-	 * External activator element or component ref.
-	 * When provided, the activator slot is not rendered and event listeners
-	 * are attached programmatically to the referenced element.
-	 */
-	activator?: ElementOrComponentRef;
-	/**
-	 * Constrains the tooltip within a bounding element: it stays inside it
-	 * alongside its trigger (sideways for a tooltip above or below); away from
-	 * the trigger it may pass the edge, and it flips at the viewport only.
-	 * Accepts an HTMLElement, a Vue component ref, or a CSS selector string.
-	 */
-	boundary?: ElementOrComponentRefOrSelector;
-	/**
-	 * Visual variant. `'default'` is the inverted (primary) bubble,
-	 * `'destructive'` is the danger-tinted bubble for warnings. Any other
-	 * string is applied as a `bb-tooltip--<name>` class hook.
-	 *
-	 * @defaultValue `'default'`
-	 */
-	variant?: BbTooltipVariant;
-	/**
-	 * Milliseconds a pointer rests on the activator before the tooltip shows
-	 * (`0`: at once). Keyboard focus shows it at once, and so does a pointer
-	 * arriving while another tooltip shows or within 300 ms of one closing.
-	 *
-	 * @defaultValue `100`
-	 */
-	delay?: number;
-	/**
-	 * Caps the bubble's width (it still shrinks to its text): a number is px, a
-	 * percentage is of the activator, any other CSS length passes through.
-	 * Replaces the default `40ch` cap, also `--max-w` on the tooltip root.
-	 */
-	width?: number | string;
-};
+		| `pt:${BbTooltipPtPart}:${BbTooltipPtState}`
+		| `pt:${BbTooltipPtPart}:${TooltipVariantBuiltIn}`]?: PtValue;
+} & /* @vue-ignore */ PtVariantAttrs<
+	BbTooltipPtPart,
+	keyof TooltipVariantRegistry
+> & {
+		/**
+		 * Passthrough, object form: the same keys as the `pt:*` attributes
+		 * without the prefix. See the `pt:<part>` row.
+		 */
+		pt?: PtMap<
+			BbTooltipPtPart,
+			BbTooltipPtState | TooltipVariantBuiltIn | keyof TooltipVariantRegistry
+		>;
+		/**
+		 * Space the arrow will maintain to the edge of the tooltip bubble.
+		 * Useful when the floating element has border radius so it won't appear broken
+		 *
+		 * @defaultValue `10`
+		 */
+		arrowPadding?: number;
+		/**
+		 * Disables the component
+		 */
+		disabled?: boolean;
+		/**
+		 * Renders the tooltip's popover and content at mount instead of on the
+		 * first open. The description screen readers hear exists from mount either
+		 * way.
+		 */
+		eager?: boolean;
+		/**
+		 * Hides the tooltip arrow. A tooltip shows its arrow by default (it's the
+		 * one popover-family surface where an arrow is meaningful — a speech bubble
+		 * pointing at its anchor); set this to drop it.
+		 *
+		 * @defaultValue `false`
+		 */
+		hideArrow?: boolean;
+		/**
+		 * Seed for the tooltip's internal id. It is **prefixed** (`bb_<id>`) and set
+		 * on the inner content element, not on the root — so
+		 * `document.getElementById(theIdYouPassed)` finds nothing. Pass it to make
+		 * the generated id stable (SSR snapshots, tests), not to look the element
+		 * up.
+		 */
+		id?: string;
+		/**
+		 * Minimum empty space to keep from the edge of the page
+		 *
+		 * @defaultValue `10`
+		 */
+		padding?: number;
+		/**
+		 * Position of the overlay in respect to the related activator.
+		 *
+		 * @defaultValue `'top'`
+		 */
+		placement?: Placement;
+		/**
+		 * Text content of the component.
+		 */
+		text?: string;
+		/**
+		 * How long the transition has to last in milliseconds
+		 *
+		 * @defaultValue `250`
+		 */
+		transitionDuration?: number;
+		/**
+		 * External activator: an HTMLElement, a Vue component ref, or a CSS
+		 * selector string (looked up in the document once the tooltip mounts).
+		 * When provided, the activator slot is not rendered and event listeners
+		 * are attached programmatically to the referenced element.
+		 */
+		activator?: ElementOrComponentRefOrSelector;
+		/**
+		 * Constrains the tooltip within a bounding element: it stays inside it
+		 * alongside its trigger (sideways for a tooltip above or below); away from
+		 * the trigger it may pass the edge, and it flips at the viewport only.
+		 * Accepts an HTMLElement, a Vue component ref, or a CSS selector string.
+		 */
+		boundary?: ElementOrComponentRefOrSelector;
+		/**
+		 * Visual variant. `'default'` is the inverted (primary) bubble,
+		 * `'destructive'` is the danger-tinted bubble for warnings. Any other
+		 * string is applied as a `bb-tooltip--<name>` class hook.
+		 *
+		 * @defaultValue `'default'`
+		 */
+		variant?: BbTooltipVariant;
+		/**
+		 * Milliseconds a pointer rests on the activator before the tooltip shows
+		 * (`0`: at once). Keyboard focus shows it at once, and so does a pointer
+		 * arriving while another tooltip shows or within 300 ms of one closing.
+		 *
+		 * @defaultValue `100`
+		 */
+		delay?: number;
+		/**
+		 * Caps the bubble's width (it still shrinks to its text): a number is px, a
+		 * percentage is of the activator, any other CSS length passes through.
+		 * Replaces the default `40ch` cap, also `--max-w` on the tooltip root.
+		 */
+		width?: number | string;
+	};
 
 /** Props exposed by the `activator` slot. */
 export type BbTooltipActivatorSlotProps = {

package/dist/ai/source/CommonPopover.md

@@ -200,11 +200,15 @@ const middleware = computed(() => {
 	];
 });
 
+const openPlacement = ref(props.placement);
+
 const { floatingStyles, placement, middlewareData, update } = useFloating(
 	anchor,
 	wrapper,
 	{
-		placement: props.placement,
+		// Latched at each open (`toggle()`): a change while open applies at the
+		// next open, so an open panel never jumps; flip and shift stay live.
+		placement: openPlacement,
 		middleware,
 		strategy: 'fixed',
 		// Without this, floating-ui computes a position the moment both elements
@@ -262,6 +266,7 @@ const { execute: toggle, cancel: cancelToggle } = useCancelableFunction(
 			signal.addEventListener('abort', eventListener);
 			if (value) {
 				emit('show');
+				openPlacement.value = props.placement;
 				showPopover();
 				update();
 				// Signal-bound: a close (or unmount) that aborts this execution

package/dist/ai/source/FlatListBox.md

@@ -38,15 +38,25 @@
 		<span class="bb-listbox__outer-container scrollbar-border">
 			<span ref="inner" class="bb-listbox__inner-container" tabindex="-1">
 				<slot name="options:prepend"></slot>
-				<span v-if="loading && !hasOptions" class="bb-listbox__loading">
-					<slot name="loading">{{
-						loadingText || t('common.loadingText').value
-					}}</slot>
-				</span>
-				<span v-else-if="!hasOptions && !failedText" class="bb-listbox__empty">
-					<slot name="empty">{{
-						emptyText || t('common.emptyText').value
-					}}</slot>
+				<!-- The empty / loading row is announced: it renders inside a
+				polite region that is always there, so the row appearing is a
+				change a reader speaks (a region that appears with its text is
+				not). What is read is what shows, the slot's or ours. The failed
+				footer is a status of its own; the empty row stays out then. -->
+				<span class="bb-listbox__status" role="status">
+					<span v-if="loading && !hasOptions" class="bb-listbox__loading">
+						<slot name="loading">{{
+							loadingText || t('common.loadingText').value
+						}}</slot>
+					</span>
+					<span
+						v-else-if="!hasOptions && !failedText"
+						class="bb-listbox__empty"
+					>
+						<slot name="empty">{{
+							emptyText || t('common.emptyText').value
+						}}</slot>
+					</span>
 				</span>
 				<!-- eslint-disable vue/attributes-order -- `pt` binds LAST so a consumer listener runs after ours (PASSTHROUGH.md T17) -->
 				<span

package/dist/ai/source/GroupedListBox.md

@@ -34,15 +34,25 @@
 		<span class="bb-listbox__outer-container scrollbar-border">
 			<span ref="inner" class="bb-listbox__inner-container" tabindex="-1">
 				<slot name="options:prepend"></slot>
-				<span v-if="loading && !hasOptions" class="bb-listbox__loading">
-					<slot name="loading">{{
-						loadingText || t('common.loadingText').value
-					}}</slot>
-				</span>
-				<span v-else-if="!hasOptions && !failedText" class="bb-listbox__empty">
-					<slot name="empty">{{
-						emptyText || t('common.emptyText').value
-					}}</slot>
+				<!-- The empty / loading row is announced: it renders inside a
+				polite region that is always there, so the row appearing is a
+				change a reader speaks (a region that appears with its text is
+				not). What is read is what shows, the slot's or ours. The failed
+				footer is a status of its own; the empty row stays out then. -->
+				<span class="bb-listbox__status" role="status">
+					<span v-if="loading && !hasOptions" class="bb-listbox__loading">
+						<slot name="loading">{{
+							loadingText || t('common.loadingText').value
+						}}</slot>
+					</span>
+					<span
+						v-else-if="!hasOptions && !failedText"
+						class="bb-listbox__empty"
+					>
+						<slot name="empty">{{
+							emptyText || t('common.emptyText').value
+						}}</slot>
+					</span>
 				</span>
 				<!-- eslint-disable vue/attributes-order -- `pt` binds LAST so a consumer listener runs after ours (PASSTHROUGH.md T17) -->
 				<span

package/dist/ai/source/OptionsContainer.md

@@ -15,6 +15,9 @@
 				[`${classes.root}--errors`]: hasErrors,
 				[`${classes.root}--warnings`]: showWarning,
 				[`${classes.root}--${resolvedListLayout}`]: true,
+				[`${classes.root}--strip`]: !!variant,
+				[`${classes.root}--${variant}`]: !!variant,
+				[`${classes.root}--no-transition`]: !!variant && !indicatorReady,
 			},
 		]"
 		v-bind="passthrough?.list"
@@ -65,7 +68,7 @@
 						option.description ? descriptionId(index) : undefined
 					"
 					:index="index"
-					:label-id="option.description ? textId(index) : undefined"
+					:label-id="textId(index)"
 					name="input"
 					:option="option"
 					:row-states="rowStates(option, index)"
@@ -212,11 +215,11 @@ const itemRatioStyle = computed(() => {
 
 /**
  * Per-row ids for the option text and its description. The row is a `<label>`
- * wrapping the input, the text AND the description, so the input's native name
- * would be "Text Description". A described row hands these to the `input` slot
- * (`labelId` / `descriptionId`) so the input can be named by its text alone and
- * described by its description; an undescribed row passes neither and keeps
- * native label naming.
+ * wrapping the input, the `icon` slot, the text AND the description, so the
+ * input's native name would be "Icon Text Description". Every row hands the
+ * text's id to the `input` slot (`labelId`), so the input is named by its text
+ * alone (ATT-11: an icon with a name of its own joined it), and a described
+ * row also hands `descriptionId`, so the description describes it.
  */
 const uid = useId().id;
 const textId = (index: number) => `${uid.value}-option-${index}__text`;
@@ -334,6 +337,19 @@ export type OptionsContainerProps<T = any> = {
 	 */
 	listLayout?: ListLayout;
 
+	/**
+	 * A tab-strip look on the list (Q76.11 d): `--strip` plus the variant's
+	 * class hook (`--pill`, `--line`, a registered name), the strip and its
+	 * triggers (choice-strip.css). The owning group renders the indicators.
+	 */
+	variant?: string;
+
+	/**
+	 * With a `variant`: the indicators have been measured and painted, so they
+	 * may transition. Until then the list is `--no-transition`.
+	 */
+	indicatorReady?: boolean;
+
 	/**
 	 * Define if the component should be in an error state.
 	 * It usually attaches a CSS class for styling purposes.
@@ -412,10 +428,10 @@ export type OptionsContainerInputSlotProps<T = any> = {
 	/** The full internal Option object for this row. */
 	option: Option<T>;
 	/**
-	 * Id of the row's text, set only when the option has a description. Pass as
-	 * `aria-labelledby` so the description stays out of the input's name.
+	 * Id of the row's text. Pass as `aria-labelledby` so the `icon` slot and the
+	 * description stay out of the input's name.
 	 */
-	labelId: string | undefined;
+	labelId: string;
 	/**
 	 * Id of the row's description, set only when it has one. Add it to the
 	 * input's `aria-describedby` (see `withItemDescribedby`).