bitboss-ui 3.0.0-beta.2 → 3.0.0-beta.21

package/dist/ai/source/BbDialog.md

@@ -24,6 +24,9 @@
 		<template v-if="$slots.title" #title="slotProps">
 			<slot name="title" v-bind="slotProps" />
 		</template>
+		<template v-if="$slots.description" #description="slotProps">
+			<slot name="description" v-bind="slotProps" />
+		</template>
 		<template v-if="$slots.footer" #footer>
 			<slot name="footer" />
 		</template>
@@ -31,8 +34,11 @@
 	<dialog
 		v-else
 		ref="dialog"
+		:aria-describedby="
+			hasRenderedAtLeastOnce && hasDescription() ? descriptionId : undefined
+		"
 		:aria-labelledby="
-			hasRenderedAtLeastOnce && (renderHeader || $slots.header)
+			hasRenderedAtLeastOnce && (hasTitle() || $slots.header)
 				? titleId
 				: undefined
 		"
@@ -57,11 +63,20 @@
 		@pointerdown="onBackdropPointerDown"
 	>
 		<template v-if="hasRenderedAtLeastOnce">
-			<div v-if="renderHeader || $slots.header" class="bb-dialog__header">
+			<div v-if="renderHeader() || $slots.header" class="bb-dialog__header">
 				<slot :close="close" name="header" :title="title" :title-id="titleId">
-					<span :id="titleId" class="bb-dialog__title">
+					<span v-if="hasTitle()" :id="titleId" class="bb-dialog__title">
 						<slot name="title" :text="title">{{ title }}</slot>
 					</span>
+					<p
+						v-if="hasDescription()"
+						:id="descriptionId"
+						class="bb-dialog__description"
+					>
+						<slot name="description" :text="description">{{
+							description
+						}}</slot>
+					</p>
 					<CloseButton
 						v-if="!hideClose"
 						:aria-label="t('dialog.closeLabel').value"
@@ -72,7 +87,7 @@
 			<div class="bb-dialog__body scrollbar-border">
 				<div class="bb-dialog__body-content">
 					<CloseButton
-						v-if="!renderHeader && !$slots.header && !hideClose"
+						v-if="!renderHeader() && !$slots.header && !hideClose"
 						:aria-label="t('dialog.closeLabel').value"
 						@click="onCloseButtonClick"
 					/>
@@ -106,13 +121,14 @@ import {
 } from '@/utils/overlayEscapeStack';
 import { useId } from '@/composables/useId';
 import { useLocale } from '@/composables/useLocale';
+import { useLogger } from '@/composables/useLogger';
 import { useMobile } from '@/composables/useMobile';
 import { useBreakpoint } from '@/composables/useBreakpoint';
 import { useUntil } from '@/composables/useUntil';
 import { removedPropsFor } from '@/deprecation/removedProps';
 import { warnRemovedAttrs } from '@/utilities/functions/warnRemovedAttrs';
 import { wait } from '@/utilities/functions/wait';
-import { config } from 'virtual:bitboss-ui/config';
+import { useConfig } from '@/composables/useConfig';
 import type { BbDialogProps, BbDialogEvents, BbDialogSlots } from './types';
 import type { BbOffCanvasProps } from '../BbOffCanvas/types';
 import CloseButton from '../CloseIcon/CloseButton.vue';
@@ -142,7 +158,9 @@ const props = withDefaults(defineProps<BbDialogProps>(), {
 
 const emit = defineEmits<BbDialogEvents>();
 
-defineSlots<BbDialogSlots>();
+const slots = defineSlots<BbDialogSlots>();
+
+const config = useConfig();
 
 if (process.env.NODE_ENV !== 'production')
 	warnRemovedAttrs('BbDialog', removedPropsFor('BbDialog'));
@@ -173,6 +191,7 @@ watch([() => props.adaptive, isMobile], () => {
 //     drawer's extent mean different things, so the drawer defaults to 'auto';
 //  3. `offCanvasProps`, so the consumer overrides any of the above.
 const canvasBindings = computed<Partial<BbOffCanvasProps>>(() => ({
+	description: props.description,
 	disabled: props.disabled,
 	eager: props.eager,
 	focusTarget: props.focusTarget,
@@ -190,7 +209,40 @@ const canvasBindings = computed<Partial<BbOffCanvasProps>>(() => ({
 
 const dialog = ref<HTMLDialogElement | null>(null);
 const titleId = `title_${useId().id.value}`;
-const renderHeader = computed(() => !!props.title);
+/*
+ * `aria-describedby` points HERE and nowhere else.
+ *
+ * BbConfirm has described its dialog by its message for a while, and its
+ * comment says exactly why that is safe there and was not safe on BbDialog:
+ * a confirm's text is short and static, where BbDialog's body is arbitrary
+ * markup and pointing at it would read entire forms aloud. A dedicated
+ * `description` is the confirm case — one short static line — so the wiring
+ * that v3 dropped along with the prop can come back with it, aimed at the
+ * element that is actually a description.
+ */
+const descriptionId = `desc_${useId().id.value}`;
+const hasDescription = () => !!props.description || !!slots.description;
+/*
+ * A `#title` slot is a title — it renders the default header exactly as the
+ * `title` prop does. It was keyed on `!!props.title` alone, so a dialog that
+ * only slotted its title rendered NO header at all and the declared slot was
+ * silently inert (v2 rendered it: the slot replaced the title text, and the
+ * header was not gated on the prop). `#header` stays separate below: it
+ * REPLACES the header rather than filling it, and owns its own close control.
+ *
+ * A function, not a computed, now that it reads a slot: `$slots` is not a
+ * reactive dependency, so a computed would latch its first value and miss a
+ * `#title` that appears later (a consumer's `<template v-if="…" #title>`).
+ * Evaluated per render it tracks the slot correctly — the same reason
+ * BbOffCanvas's twin is a function.
+ */
+const hasTitle = () => !!props.title || !!slots.title;
+/*
+ * A description raises the header on its own — a describing line with no title
+ * is a legitimate shape, and gating the header on the title alone would drop
+ * it silently.
+ */
+const renderHeader = () => hasTitle() || hasDescription();
 const hasRenderedAtLeastOnce: Ref<boolean> = useUntil(
 	() => model.value || props.eager,
 	{
@@ -426,6 +478,29 @@ const toggleDialog = async (value: boolean) => {
 	}
 };
 
+/*
+ * Q18.13 — `aria-labelledby` is bound to `titleId` as soon as a `#header` slot
+ * exists, but the slot content is the author's: nothing guarantees they put
+ * that id on their heading. A name pointing at a missing element is WORSE than
+ * no name — assistive tech announces the surface unnamed and the author has no
+ * signal. Binding conditionally is not possible (the attribute is computed
+ * before the slot renders), so warn once, in dev, after the header is in the
+ * DOM.
+ */
+const warnIfHeaderNameIsDangling = () => {
+	if (process.env.NODE_ENV === 'production') return;
+	// `props.title`, not `renderHeader` (which now also counts `#title`): a
+	// `#header` slot replaces the whole header, so the dangling-id risk is the
+	// same whatever else was passed. Keyed exactly like BbOffCanvas's twin.
+	if (!slots.header || props.title) return;
+	nextTick(() => {
+		if (!dialog.value || document.getElementById(titleId)) return;
+		useLogger().warn(
+			`BbDialog: the #header slot does not contain an element with id="${titleId}", so aria-labelledby points at nothing and the dialog announces as unnamed. Bind the slot's \`titleId\` to your heading: <template #header="{ titleId }"><h2 :id="titleId">…</h2></template>.`
+		);
+	});
+};
+
 watch(model, (value) => {
 	// Latch the surface at the moment we open, then freeze it: a resize across
 	// the mobile breakpoint mid-session must not swap dialog <-> drawer.
@@ -435,6 +510,7 @@ watch(model, (value) => {
 });
 onMounted(() => {
 	if (model.value && surface.value === 'dialog') toggleDialog(true);
+	warnIfHeaderNameIsDangling();
 });
 onBeforeUnmount(() => {
 	clearTimeout(denyCloseTimer);
@@ -507,6 +583,18 @@ export type { Sizes };
  * Props controlling the BbDialog appearance, accessibility, and closing behaviour.
  */
 export type BbDialogProps = {
+	/**
+	 * One short line under the title, in the header — the shadcn
+	 * `DialogDescription` shape: same block as the title, lower hierarchy,
+	 * muted.
+	 *
+	 * It is also what `aria-describedby` points at. That wiring was dropped in
+	 * v3 along with the old `description` prop, on the reasoning that pointing
+	 * it at arbitrary body content would read whole forms aloud — true, and the
+	 * reason it aims at THIS element only. Keep it to a sentence; anything
+	 * longer belongs in the body.
+	 */
+	description?: string;
 	/**
 	 * Disable EVERY user-initiated dismissal: backdrop click, Escape AND the
 	 * header close (×) button (denied attempts play the deny nudge). Use it
@@ -540,7 +628,7 @@ export type BbDialogProps = {
 	/**
 	 * Overrides merged over the offcanvas (mobile) surface's props. The drawer
 	 * defaults to a bottom, draggable, content-sized sheet
-	 * (`direction: 'bottom'`, `draggable: true`, `size: 'auto'`); use this to
+	 * (`side: 'bottom'`, `draggable: true`, `size: 'auto'`); use this to
 	 * override those, set other drawer-only options (`stackGap`), or override
 	 * shared props whose meaning differs on the drawer (`stack`). Ignored on the
 	 * desktop dialog surface.
@@ -615,12 +703,24 @@ export type BbDialogHeaderSlotProps = {
 };
 
 /** Props exposed by the `title` slot. */
+/** Props exposed by the `description` slot. */
+export type BbDialogDescriptionSlotProps = {
+	/** The `description` prop value. */
+	text: BbDialogProps['description'];
+};
+
 export type BbDialogTitleSlotProps = {
 	/** The `title` prop value. */
 	text: BbDialogProps['title'];
 };
 
 export type BbDialogSlots = {
+	/**
+	 * Replaces the description text under the title. Renders the header even
+	 * when `title` and `description` are unset — a slotted description is a
+	 * description, the same rule `#title` follows.
+	 */
+	description?: (props: BbDialogDescriptionSlotProps) => any;
 	/** Primary body content of the dialog, rendered in the scrollable body area. */
 	default?: (props: BbDialogDefaultSlotProps) => any;
 	/** Content rendered in the dialog footer, below the body area. Typically used for action buttons. */
@@ -640,7 +740,11 @@ export type BbDialogSlots = {
 	 * width, or it renders squeezed against the left edge.
 	 */
 	header?: (props: BbDialogHeaderSlotProps) => any;
-	/** Replaces the default title text inside the header. Remains linked to the dialog through `aria-labelledby`. */
+	/**
+	 * Replaces the default title text inside the header. Remains linked to the
+	 * dialog through `aria-labelledby`. Providing this slot renders the header
+	 * even when `title` is unset — a slotted title is a title.
+	 */
 	title?: (props: BbDialogTitleSlotProps) => any;
 };
 
@@ -657,6 +761,13 @@ export type { BbDialogSlots as BaseDialogSlots };
 ```css
 /* @inherit --transition-duration --max-width — set inline from props; @inherit --scrollbar-width — set on body by the scroll lock */
 .bb-dialog {
+	/* Axis split of --bb-panel-p: --px (inline) / --py (block),
+	   each branching off it. Set the pair only when the axes differ; setting
+	   --bb-panel-p alone keeps them equal. Local on this root class (not
+	   :root) so scoped --bb-panel-p overrides keep reaching the slots; for
+	   per-part asymmetry, scope --py to the part class. */
+	--px: var(--bb-panel-p);
+	--py: var(--bb-panel-p);
 	--page-padding: 20px;
 	--transition-timing-function: var(--bb-ease);
 
@@ -751,26 +862,71 @@ export type { BbDialogSlots as BaseDialogSlots };
 	}
 
 	.bb-dialog__header {
+		/* Shared by the close control and by the space the title reserves for it,
+		 * so the two can never drift apart. */
+		--close-size: 28px;
+
 		align-items: center;
 		column-gap: 12px;
 		display: flex;
 		flex-shrink: 0;
 		justify-content: space-between;
-		padding: var(--bb-panel-p) var(--bb-panel-p) calc(var(--bb-panel-p) / 2)
-			var(--bb-panel-p);
+		padding: var(--py) var(--px) calc(var(--py) / 2) var(--px);
 
 		.bb-dialog__title {
 			font-size: var(--dialog-title-fs, calc(var(--bb-fs) + 2px));
 			font-weight: 500;
 			line-height: var(--dialog-title-fs, calc(var(--bb-fs) + 2px));
+			/* Long titles wrap rather than truncate — a dialog title is usually
+			 * naming the record you are about to act on, so hiding the end of it
+			 * is worse than a second line. `anywhere` because the thing that
+			 * overflows is typically one unbroken id with nowhere to break. */
+			min-width: 0;
+			overflow-wrap: anywhere;
+
+			/* The close control is out of flow (below), so `column-gap` has
+			 * nothing to push against and the title would run under it. Reserve
+			 * the space here instead — only when there is actually a control to
+			 * clear, so `hideClose` keeps the full width. */
+			&:has(~ .bb-close-button) {
+				padding-right: calc(var(--close-size) + 4px);
+			}
 		}
 
+		/* Absolute on purpose: pinned to the panel corner, so a title that wraps
+		 * to two lines does not drag the × down with it, and the control never
+		 * adds its 28px to the header's height (the title's line box sets that).
+		 * The negative offsets align the ICON's edges with the padding box —
+		 * the button's own `--p` sits outside it. */
 		> .bb-close-button {
-			--size: 28px;
+			--size: var(--close-size);
 			--p: 7px;
 			position: absolute;
-			right: calc(var(--bb-panel-p) - var(--p));
-			top: calc(var(--bb-panel-p) - var(--p));
+			right: calc(var(--px) - var(--p));
+			top: calc(var(--py) - var(--p));
+		}
+
+		/* Only when a description is present. A header without one keeps its
+		   original single-row, vertically-centred layout exactly — this must not
+		   move any dialog that does not opt in. */
+		&:has(.bb-dialog__description) {
+			align-items: flex-start;
+			flex-direction: column;
+			row-gap: 2px;
+		}
+
+		.bb-dialog__description {
+			color: var(--bb-text-muted);
+			font-size: var(--bb-fs);
+			font-weight: 400;
+			line-height: 20px;
+			margin: 0;
+			/* Clears the absolutely-positioned close button the same way the title
+			   does. The × sits at the top-right, and a one-line title is short
+			   enough that the description's first line can still run under it. */
+			&:has(~ .bb-close-button) {
+				padding-right: calc(var(--close-size) + 4px);
+			}
 		}
 	}
 
@@ -781,20 +937,20 @@ export type { BbDialogSlots as BaseDialogSlots };
 
 		&:first-child {
 			.bb-dialog__body-content {
-				padding-top: var(--bb-panel-p);
+				padding-top: var(--py);
 
 				> .bb-close-button {
 					--size: 28px;
 					--p: 7px;
 					position: absolute;
-					right: calc(var(--bb-panel-p) - var(--p));
-					top: calc(var(--bb-panel-p) - var(--p));
+					right: calc(var(--px) - var(--p));
+					top: calc(var(--py) - var(--p));
 				}
 			}
 		}
 
 		&-content {
-			padding: 0px var(--bb-panel-p) var(--dialog-gap, var(--bb-panel-p));
+			padding: 0px var(--px) var(--dialog-gap, var(--py));
 		}
 
 		/* Hide any nested dialogs that are not open so that scale transition works without affecting fixed positioning */
@@ -805,7 +961,7 @@ export type { BbDialogSlots as BaseDialogSlots };
 
 	.bb-dialog__footer {
 		border-top: 1px solid var(--bb-border);
-		padding: var(--dialog-gap, var(--bb-panel-p)) var(--bb-panel-p);
+		padding: var(--dialog-gap, var(--py)) var(--px);
 		pointer-events: auto;
 
 		&:empty {