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

package/dist/ai/source/BbSelectPopover.md

@@ -164,7 +164,7 @@
 					:query="query"
 			/></template>
 			<template v-if="$slots.option" #option="data"
-				><slot :loading="computedLoading" name="option" v-bind="data"
+				><slot name="option" v-bind="optionSlotProps(data)"
 			/></template>
 			<template #group="data"><slot name="group" v-bind="data" /></template>
 		</ListBox>
@@ -186,8 +186,12 @@
 		"
 		v-bind="mergeProps(offcanvasBindings, sheetEvents, withoutClass($attrs))"
 	>
-		<template v-if="$slots.header" #header>
-			<slot name="header" v-bind="panelSlotProps" />
+		<template v-if="$slots.header" #header="{ titleId: sheetTitleId }">
+			<!-- The sheet's own `titleId`: its dialog is labelled by it. -->
+			<slot
+				name="header"
+				v-bind="{ ...panelSlotProps, titleId: sheetTitleId }"
+			/>
 		</template>
 		<!-- `tabindex="-1"`: the sheet's own opening focus target. Not focusable
 		by Tab — only programmatically, by BbOffCanvas's `focusTarget`. See the
@@ -284,7 +288,11 @@
 	</CommonPopover>
 </template>
 
-<script setup lang="ts" generic="Item = any">
+<script
+	setup
+	lang="ts"
+	generic="Item = any, Known extends BbSelectKnownItems | undefined = undefined"
+>
 import type { Option as BaseOption, GroupedOptions } from '@/types/Option';
 import {
 	computed,
@@ -298,7 +306,11 @@ import {
 	onDeactivated,
 } from 'vue';
 import { isImeComposing } from '@/utilities/functions/isImeComposing';
-import { extractDomContainer } from '@/utilities/functions/extractDomContainer';
+import {
+	domElement,
+	extractDomContainer,
+	type DomHost,
+} from '@/utilities/functions/extractDomContainer';
 import { elementLabel } from '@/utilities/functions/elementLabel';
 import { get } from '@/utilities/functions/get';
 import { hash } from '@/utilities/functions/hash';
@@ -371,7 +383,9 @@ import searchIcon from '@/assets/svgs/search.svg?raw';
 import ListBox from '../ListBox/ListBox.vue';
 import { waitFor } from '@/utilities/functions/waitFor';
 import type {
+	BbSelectKnownItems,
 	BbSelectPopoverEvents,
+	BbSelectPopoverOptionSlotProps,
 	BbSelectPopoverProps,
 	BbSelectPopoverSlots,
 	BbSelectResolvedOption,
@@ -386,7 +400,7 @@ import { removedPropsFor } from '@/deprecation/removedProps';
 import { warnRemovedAttrs } from '@/utilities/functions/warnRemovedAttrs';
 import { hasVnodeListener } from '@/utilities/functions/hasVnodeListener';
 
-const props = withDefaults(defineProps<BbSelectPopoverProps<Item>>(), {
+const props = withDefaults(defineProps<BbSelectPopoverProps<Item, Known>>(), {
 	// `undefined` (declared, not omitted) keeps `adaptive` three-state: it disables
 	// Vue's absent→`false` Boolean cast so `props.adaptive ?? config.adaptive` can
 	// reach the config default, while keeping the Boolean type so the valueless
@@ -421,7 +435,7 @@ const props = withDefaults(defineProps<BbSelectPopoverProps<Item>>(), {
 
 const emit = defineEmits<BbSelectPopoverEvents>();
 
-defineSlots<BbSelectPopoverSlots<Item>>();
+defineSlots<BbSelectPopoverSlots<Item, Known>>();
 
 /**
  * Passthrough (plans/passthrough/BbSelectPopover.md). `root` merges into the `$attrs` spread on the desktop floating element (no node on the phone sheet, where `panel` then `sheet` land on the sheet root); `option` is resolved per option inside the listbox with `part()`.
@@ -432,6 +446,7 @@ const passthrough = usePassthrough({
 	parts: BB_SELECT_POPOVER_PT.parts,
 	states: BB_SELECT_POPOVER_PT.states,
 	active: { open: () => shown.value },
+	facts: (row) => ({ known: isKnown(row) }),
 });
 
 const config = useConfig();
@@ -467,13 +482,13 @@ onBeforeMount(() => {
 /**
  * START ELEMENT REFERENCES
  */
-const activatorEl = ref<HTMLElement>();
+const activatorEl = ref<DomHost>();
 const optionsContainer = ref<any | null>(null);
 const searchInput = ref<HTMLInputElement | null>(null);
 const popoverFocusProxy = ref<HTMLButtonElement | null>(null);
 const activeDescendantId = ref<string>();
 
-const positionAnchorEl = computed<HTMLElement | undefined>(() => {
+const positionAnchorEl = computed<DomHost | undefined>(() => {
 	if (props.anchor) {
 		const el = extractDomContainer(props.anchor);
 		if (el) return el;
@@ -482,7 +497,7 @@ const positionAnchorEl = computed<HTMLElement | undefined>(() => {
 });
 
 const { width: activatorWidth } = useElementSize(
-	positionAnchorEl,
+	() => domElement(positionAnchorEl.value),
 	{ width: 0, height: 0 },
 	{
 		box: 'border-box',
@@ -613,7 +628,7 @@ const computedAriaDescribedby = computed(() => {
 let ignoreNextIntersection = false;
 
 const { resume, pause } = useIntersectionObserver(
-	activatorEl,
+	() => domElement(activatorEl.value),
 	async ([{ intersectionRatio }]) => {
 		if (ignoreNextIntersection) {
 			ignoreNextIntersection = false;
@@ -1623,7 +1638,22 @@ const keepListedWhileOpen = (valueHash: string) => {
 		}
 	}
 };
-if (knownSource) knownSource.userUnpick = markUserUnpicked;
+if (knownSource) {
+	knownSource.userUnpick = markUserUnpicked;
+	knownSource.isKnown = isKnown;
+}
+
+/**
+ * The option slot's props, with the `known` that tells a known row from the
+ * list's own (Q77.7). The scope is typed by whether this popover binds
+ * `known-items` (`Known`), which runtime cannot see: the one cast lives here.
+ */
+const optionSlotProps = <D extends { item: Item }>(data: D) =>
+	({
+		...data,
+		loading: computedLoading.value,
+		known: isKnown(data.item),
+	}) as unknown as BbSelectPopoverOptionSlotProps<Item, Known>;
 watch(modelValueIndexedByHash, (selected) => {
 	// Closed, a value leaving the model leaves its sticky place (R17).
 	if (!shown.value) pruneSticky();
@@ -2316,7 +2346,8 @@ const getGroupData = (option: BaseOption) => {
 /**
  * G5 (owner 2026-10-16): the page decides the order of the groups; a pinned
  * row goes first inside its own group, and a group only pinned rows hold
- * goes first.
+ * goes first. Rows with no group (a nullish `groupBy`, a known row) are
+ * listed before every header (owner 2026-10-26, ATT-15), as in BbDropdown.
  */
 const groupedOptions = computed<GroupedOptions[]>(() => {
 	// Every row the open list puts on top (pins and other outside rows) is
@@ -2358,14 +2389,16 @@ const groupedOptions = computed<GroupedOptions[]>(() => {
 	});
 	return groups
 		.map((group, order) => ({ group, order }))
-		.sort((a, b) =>
-			a.group.firstListed === b.group.firstListed
-				? a.order - b.order
-				: a.group.firstListed === Infinity
-					? -1
-					: b.group.firstListed === Infinity
-						? 1
-						: a.group.firstListed - b.group.firstListed
+		.sort(
+			(a, b) =>
+				Number(b.group.data === null) - Number(a.group.data === null) ||
+				(a.group.firstListed === b.group.firstListed
+					? a.order - b.order
+					: a.group.firstListed === Infinity
+						? -1
+						: b.group.firstListed === Infinity
+							? 1
+							: a.group.firstListed - b.group.firstListed)
 		)
 		.map(({ group: { id, data, options, pinnedOptions } }) => ({
 			id,
@@ -2864,6 +2897,8 @@ const panelSlotProps = computed(() => ({
 	focus: focusPopoverContent,
 	query: query.value,
 	selectedOptions: publicSelectedOptions.value,
+	// The sheet hands its dialog's own id instead (Q76.10 d).
+	titleId: `${id}_title`,
 }));
 
 /**
@@ -3150,6 +3185,41 @@ import type { BbOffCanvasProps } from '../BbOffCanvas/types';
 /** A row naming a value the app already holds (`known-items`): the model value and its text. */
 export type BbSelectKnownItem = { value: unknown; label: string };
 
+/** What `known-items` takes. */
+export type BbSelectKnownItems = Array<BbSelectKnownItem | null | undefined>;
+
+/**
+ * The row an option or chip slot gets, told apart by `known` (Q77.7). On a
+ * select that binds `known-items`, a known row stands in as `item` until the
+ * list brings the real one: `{ value, label }`, whatever the options' shape.
+ * Without `known-items` the row is always the option. `BbSelectSlotRow<Row>`
+ * alone is the bound case: what a helper taking a slot's `{ item, known }`
+ * is typed with.
+ */
+export type BbSelectSlotRow<
+	Item,
+	Known extends BbSelectKnownItems | undefined = BbSelectKnownItems,
+> = [Known] extends [undefined]
+	? {
+			/** Always `false` here: this select binds no `known-items`. */
+			known: false;
+			/** The raw item from the `items` prop. */
+			item: Item;
+		}
+	:
+			| {
+					/** A known row (`known-items`): the list has not brought this value's own row yet. */
+					known: true;
+					/** The known row, `{ value, label }`; read `text` for what it shows. */
+					item: BbSelectKnownItem;
+			  }
+			| {
+					/** The list's own row. */
+					known: false;
+					/** The raw item from the `items` prop. */
+					item: Item;
+			  };
+
 /**
  * A selected option as resolved by the select family and exposed through slot
  * props (`selectedOptions`): the raw source `item` plus its resolved display
@@ -3271,7 +3341,11 @@ export const BB_SELECT_POPOVER_PT = {
 // Two mapped types, never `Partial<Record<…>>`: the lint autofix rewrites one
 // into the other and the SFC resolver reads only the mapped spelling (T23).
 /* eslint-disable @typescript-eslint/consistent-indexed-object-style */
-export type BbSelectPopoverProps<Item> = {
+export type BbSelectPopoverProps<
+	Item,
+	// The type alone is the bound case, as on `BbSelectProps` (Q77.7).
+	Known extends BbSelectKnownItems | undefined = BbSelectKnownItems,
+> = {
 	[K in
 		| `pt:${BbSelectPopoverSurfacePtPart}`
 		| `pt:${BbSelectPopoverPtPart}:${BbSelectPopoverPtState}`]?: PtValue;
@@ -3281,7 +3355,12 @@ export type BbSelectPopoverProps<Item> = {
 	[K in `pt:${BbSelectPopoverOptionPtPart}`]?:
 		| PtValue
 		| ((
-				ctx: PtItemCtx<PtNoInfer<Item>, BbSelectPopoverPtState>
+				ctx: PtItemCtx<
+					PtNoInfer<Item>,
+					BbSelectPopoverPtState,
+					never,
+					BbSelectSlotRow<PtNoInfer<Item>, PtNoInfer<Known>>
+				>
 		  ) => PtItemResult);
 } & {
 	/* eslint-enable @typescript-eslint/consistent-indexed-object-style */
@@ -3293,7 +3372,9 @@ export type BbSelectPopoverProps<Item> = {
 		BbSelectPopoverPtPart,
 		BbSelectPopoverOptionPtPart,
 		BbSelectPopoverPtState,
-		PtNoInfer<Item>
+		PtNoInfer<Item>,
+		never,
+		BbSelectSlotRow<PtNoInfer<Item>, PtNoInfer<Known>>
 	>;
 	/**
 	 * External activator element or component ref.
@@ -3472,11 +3553,11 @@ export type BbSelectPopoverProps<Item> = {
 	/**
 	 * `{ value, label }` rows naming the value the app already holds, whatever
 	 * the options' shape: the activator's `text` with no request until the
-	 * first open (`prefill: true` still loads). Not options; the options'
-	 * accessors never run on them; slots get the row as `item` until the list
+	 * first open (`prefill: true` still loads). Not options: accessors never
+	 * run on them; slots get one as `item`, `known: true`, until the list
 	 * brings its own.
 	 */
-	knownItems?: Array<BbSelectKnownItem | null | undefined>;
+	knownItems?: [Known] extends [undefined] ? BbSelectKnownItems : Known;
 	/**
 	 * Display the loading state styles.
 	 */
@@ -3671,15 +3752,16 @@ export type BbSelectPopoverActivatorSlotProps = {
 };
 
 /** Props exposed by the `option` slot. */
-export type BbSelectPopoverOptionSlotProps<Item> = {
+export type BbSelectPopoverOptionSlotProps<
+	Item,
+	Known extends BbSelectKnownItems | undefined = undefined,
+> = BbSelectSlotRow<Item, Known> & {
 	/** Whether this option is disabled. */
 	disabled: boolean;
 	/** Whether this option currently has keyboard focus. */
 	focused: boolean;
 	/** Zero-based index of this option in the list. */
 	index: number;
-	/** The raw item from the `items` prop. */
-	item: Item;
 	/** Whether items are still being fetched. */
 	loading: boolean;
 	/** Whether this option is currently selected. */
@@ -3721,9 +3803,19 @@ export type BbSelectPopoverPanelSlotProps = {
 	query: string;
 	/** The resolved options that are currently selected. */
 	selectedOptions: BbSelectResolvedOption[];
+	/**
+	 * Bind it as the `id` of a heading in `#header`: on the phone sheet the
+	 * dialog is labelled by it (`aria-labelledby`); on the desktop panel the
+	 * listbox keeps the trigger's name, and the id is there so one markup
+	 * serves both.
+	 */
+	titleId: string;
 };
 
-export type BbSelectPopoverSlots<Item> = {
+export type BbSelectPopoverSlots<
+	Item,
+	Known extends BbSelectKnownItems | undefined = undefined,
+> = {
 	/**
 	 * Replaces the default trigger element that opens the select popover.
 	 */
@@ -3755,9 +3847,12 @@ export type BbSelectPopoverSlots<Item> = {
 	 */
 	empty?: (props: { query: string; focus: () => void; error: unknown }) => any;
 	/**
-	 * Replaces the default rendering of each option row in the dropdown.
+	 * Replaces the default rendering of each option row in the dropdown. With
+	 * `known-items` bound, a row the list has not brought yet is the known
+	 * `{ value, label }` row, `known: true`: check `known` before reading an
+	 * option field off `item`.
 	 */
-	option?: (props: BbSelectPopoverOptionSlotProps<Item>) => any;
+	option?: (props: BbSelectPopoverOptionSlotProps<Item, Known>) => any;
 };
 ```
 

package/dist/ai/source/BbSwitchGroup.md

@@ -477,7 +477,7 @@ const rowListeners = (option: Option) => ({
 	onMouseup: (event: MouseEvent) => emit('mouseup', event),
 });
 
-/** One row's native switch: named by its text when described, described by the group then its own description. */
+/** One row's native switch: named by its text alone, described by the group then its own description. */
 const rowInputAttrs = (
 	option: Option,
 	index: number,
@@ -538,18 +538,39 @@ const rowIconSlotProps = (
 
 ```ts
 import type { BbCheckboxIconSlotProps } from '../BbCheckbox/types';
-import {
-	BB_CHECKBOX_GROUP_PT,
-	type BbCheckboxGroupEvents,
-	type BbCheckboxGroupProps,
+import type {
+	BbCheckboxGroupBaseProps,
+	BbCheckboxGroupEvents,
 } from '../BbCheckboxGroup/types';
+import {
+	GROUP_PT_PARTS,
+	GROUP_PT_STATES,
+	GROUP_ROW_PT_PARTS,
+	GROUP_ROW_PT_STATES,
+	type GroupPtMap,
+	type PtNoInfer,
+} from '@/types/passthrough';
 import type { CommonFieldAsteriskSlotProps } from '../CommonField/types';
 
-/** `BbSwitchGroup` shares `BbCheckboxGroup`'s passthrough vocabulary (its props are the same type). */
-export const BB_SWITCH_GROUP_PT = BB_CHECKBOX_GROUP_PT;
-
-/** Re-export of BbCheckboxGroupProps for the switch-group variant. */
-export type BbSwitchGroupProps<T = any> = BbCheckboxGroupProps<T>;
+/**
+ * `BbSwitchGroup`'s passthrough vocabulary: BbCheckboxGroup's, without the
+ * `variant` indicator (BbTabs' looks are the checkbox group's alone).
+ */
+export const BB_SWITCH_GROUP_PT = {
+	parts: GROUP_PT_PARTS,
+	states: GROUP_PT_STATES,
+	rowParts: GROUP_ROW_PT_PARTS,
+	rowStates: GROUP_ROW_PT_STATES,
+} as const;
+
+/** BbCheckboxGroup's props without its `variant` (and the `indicator` part). */
+export type BbSwitchGroupProps<T = any> = BbCheckboxGroupBaseProps<T> & {
+	/**
+	 * Passthrough, object form: the same keys as the `pt:*` attributes
+	 * without the prefix. See the `pt:<part>` row.
+	 */
+	pt?: GroupPtMap<PtNoInfer<T>>;
+};
 
 /** Re-export for consumers importing events type from BbSwitchGroup. */
 export type BbSwitchGroupEvents = BbCheckboxGroupEvents;
@@ -966,6 +987,19 @@ export type BbSwitchGroupSlots<T> = {
 	}
 }
 
+/* A side hidden with the library's or Tailwind's hiding classes takes its gap
+   with it (ATT-11 e): `hideLabel` / `pt:label="sr-only"` (out of flow) or
+   `pt:icon="hidden"` would leave an empty track AND the gap beside it (the
+   row gap in a `vertical` item, Q76.11 c), and the side still shown sat
+   off-centre. `:where` keeps the rule at the row's
+   one class, so a consumer `gap-*` on `pt:item` still wins. */
+.bb-switch-group__item:where(
+	:has(> .bb-switch-group__label:is(.bb-sr-only, .sr-only)),
+	:has(> .bb-toggle-input + :is(.hidden, .sr-only, .bb-sr-only))
+) {
+	gap: 0;
+}
+
 .bb-switch-group__label {
 	color: var(--bb-text);
 	font-size: var(--bb-label-fs);
@@ -998,6 +1032,32 @@ export type BbSwitchGroupSlots<T> = {
 	user-select: none;
 }
 
+/*
+ * `tiles` (ATT-11 d): the invisible native input covers the WHOLE tile,
+ * padding included, not only the glyph's cell, so a click, a hover tooltip on
+ * the input and a test runner's hit-target check land on it anywhere on the
+ * tile. `grid-area: auto` is load-bearing: an absolutely positioned grid child
+ * is sized against its grid area, so `inset: 0` would still be the glyph
+ * cell. A link or a button inside a tile sits above the input and keeps its
+ * own click. List rows keep the cell overlay.
+ */
+.bb-switch-group__list--tiles > .bb-switch-group__item {
+	position: relative;
+
+	> .bb-toggle-input {
+		border-radius: inherit;
+		grid-area: auto;
+		inset: 0;
+		position: absolute;
+		z-index: 1;
+	}
+
+	:is(a, button) {
+		position: relative;
+		z-index: 2;
+	}
+}
+
 /* ---- Touch targets (Q44.19) -------------------------------------------
  * A row is one label line (`--bb-label-lh`, 18px) and the rows sit
  * `--row-gap` (10px) apart. On a coarse pointer only, each row gets an