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

package/dist/ai/source/BbOffCanvas.md

@@ -8,8 +8,13 @@
 <template>
 	<dialog
 		ref="dialog"
+		:aria-describedby="
+			hasRenderedAtLeastOnce && hasDescription() ? descriptionId : undefined
+		"
 		:aria-labelledby="
-			hasRenderedAtLeastOnce && renderHeader() ? titleId : undefined
+			hasRenderedAtLeastOnce && (hasTitle() || $slots.header)
+				? titleId
+				: undefined
 		"
 		class="bb-offcanvas"
 		:class="
@@ -20,6 +25,7 @@
 					'bb-offcanvas--fullscreen': isFullscreen,
 					'bb-offcanvas--deny-close': denyClose,
 					'bb-offcanvas--dragging': isDragging,
+					'bb-offcanvas--swipe-exit': swipeExiting,
 					'bb-offcanvas--instant-stack': instantStack,
 					'bb-offcanvas--covered': isCovered,
 					'bb-offcanvas--has-handle': draggable,
@@ -39,7 +45,7 @@
 		@cancel="cancelableClose"
 		@click.self="onBackdropClick"
 		@pointercancel="resetBackdropPointerState"
-		@pointerdown="onPanelPointerDown"
+		@pointerdown="onBackdropPointerDown"
 	>
 		<template v-if="hasRenderedAtLeastOnce">
 			<div
@@ -49,9 +55,18 @@
 			></div>
 			<div v-if="renderHeader()" class="bb-offcanvas__header">
 				<slot :close="close" name="header" :title="title" :title-id="titleId">
-					<span :id="titleId" class="bb-offcanvas__title">
+					<span v-if="hasTitle()" :id="titleId" class="bb-offcanvas__title">
 						<slot name="title" :text="title">{{ title }}</slot>
 					</span>
+					<p
+						v-if="hasDescription()"
+						:id="descriptionId"
+						class="bb-offcanvas__description"
+					>
+						<slot name="description" :text="description">{{
+							description
+						}}</slot>
+					</p>
 					<CloseButton
 						v-if="!hideClose"
 						:aria-label="t('offCanvas.closeLabel').value"
@@ -62,6 +77,34 @@
 			<div ref="body" class="bb-offcanvas__body scrollbar-border">
 				<div class="bb-offcanvas__body-content">
 					<slot :close="close"></slot>
+
+					<!--
+						Q18.12 — the headerless close.
+						Without it a panel with no `title` and no `#header` had NO close
+						control at all: for an adaptive BbDialog that meant a floating ×
+						on desktop and none on the phone, from one template. The
+						positioning CSS for this button already shipped
+						(`index.css` `.bb-offcanvas__body-content > .bb-close-button`) —
+						it was dead, waiting for the element.
+
+						The guard is the dialog's, so delegating the close stays
+						possible the same two ways: `hide-close` drops it entirely, and
+						a `#header` slot means you are rendering your own control.
+
+						AFTER the slot, unlike BbDialog, and that is load-bearing.
+						`showModal()` focuses the first focusable element in the dialog,
+						so rendering the × first made it steal the opening focus — it
+						broke BbColorPalette, whose contract is that opening the sheet
+						focuses the palette. The button is `position: absolute`, so DOM
+						order does not move it visually; it only decides who the browser
+						focuses and where the × sits in the tab order (last, after the
+						content it closes).
+					-->
+					<CloseButton
+						v-if="!renderHeader() && !hideClose"
+						:aria-label="t('offCanvas.closeLabel').value"
+						@click="onCloseButtonClick"
+					/>
 				</div>
 			</div>
 
@@ -82,6 +125,7 @@ import {
 	watch,
 	type Ref,
 } from 'vue';
+import { useSwipe } from '@vueuse/core';
 import { parseSize } from '@/utilities/functions/parseSize';
 import {
 	pushEscapeEntry,
@@ -90,6 +134,7 @@ 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 { viewportWidth, viewportHeight } from '@/composables/useViewportWidth';
 import { useBreakpoint } from '@/composables/useBreakpoint';
@@ -99,7 +144,7 @@ import { warnRemovedAttrs } from '@/utilities/functions/warnRemovedAttrs';
 import { wait } from '@/utilities/functions/wait';
 import { transitions } from '@/utilities/misc/transitions';
 import { overlaySurfaceIsolation } from '@/utils/overlaySurfaceIsolation';
-import { config } from 'virtual:bitboss-ui/config';
+import { useConfig } from '@/composables/useConfig';
 import CloseButton from '../CloseIcon/CloseButton.vue';
 import { useOffCanvasStack } from './useOffCanvasStack';
 import { registerTopLayerHost } from '@/composables/useTopLayer';
@@ -109,7 +154,6 @@ import type {
 	BbOffCanvasSlots,
 	Sizes,
 } from './types';
-export type { BbOffCanvasProps, BbOffCanvasEvents, BbOffCanvasSlots, Sizes };
 
 /**
  * Used by v-model to open / close the panel. A panel with no `v-model`
@@ -118,7 +162,6 @@ export type { BbOffCanvasProps, BbOffCanvasEvents, BbOffCanvasSlots, Sizes };
  * @defaultValue `false`
  */
 const model = defineModel<boolean>({ default: false });
-
 const props = withDefaults(defineProps<BbOffCanvasProps>(), {
 	side: 'left',
 	size: 'sm',
@@ -126,10 +169,10 @@ const props = withDefaults(defineProps<BbOffCanvasProps>(), {
 	draggable: false,
 	stackGap: 60,
 });
-
 const emit = defineEmits<BbOffCanvasEvents>();
-
 const slots = defineSlots<BbOffCanvasSlots>();
+const config = useConfig();
+export type { BbOffCanvasProps, BbOffCanvasEvents, BbOffCanvasSlots, Sizes };
 
 if (process.env.NODE_ENV !== 'production')
 	warnRemovedAttrs('BbOffCanvas', removedPropsFor('BbOffCanvas'));
@@ -139,7 +182,15 @@ const { t } = useLocale();
 // computed would latch its first value and miss a slot that appears later (e.g.
 // BbDropdown's adaptive sheet only provides `#header` once you drill into a
 // submenu). Evaluated per render, it tracks the slot's presence correctly.
-const renderHeader = () => !!props.title || !!slots.header;
+// `#title` counts as a title, exactly like the prop — the twin of BbDialog's
+// `renderHeader`. Without it a panel that only slotted its title rendered no
+// header, so the declared slot was silently inert (and an adaptive BbDialog
+// forwards `#title` straight through to here).
+const hasTitle = () => !!props.title || !!slots.title;
+// A description raises the header on its own — a describing line with no title
+// is a legitimate shape — but it is NOT a name, so `aria-labelledby` keys off
+// `hasTitle()` while the header keys off both.
+const renderHeader = () => hasTitle() || !!slots.header || hasDescription();
 const shouldPreventClose = computed(
 	() => !!(props.disabled || props.persistent)
 );
@@ -154,6 +205,11 @@ const hasRenderedAtLeastOnce: Ref<boolean> = useUntil(
 );
 
 const titleId = `title_${useId().id.value}`;
+// Twin of BbDialog's: `aria-describedby` points at the dedicated description
+// and nothing else, which is what makes the wiring safe here (see the note on
+// BbDialog's `descriptionId`).
+const descriptionId = `desc_${useId().id.value}`;
+const hasDescription = () => !!props.description || !!slots.description;
 const openedTimes = ref(0);
 const isVisible = ref(false);
 
@@ -291,19 +347,41 @@ const toggleDialog = async (value: boolean) => {
 		releaseTopLayer?.();
 		releaseTopLayer = null;
 		isVisible.value = false;
+		swipeDismissPending = false;
+		swipeExiting.value = false;
 		clearDragVisual();
 		emit('hidden');
 	}
 };
 
+/*
+ * Q18.13 — see the twin in BbDialog. `aria-labelledby` points at `titleId` as
+ * soon as a `#header` slot exists, but the heading inside it is the author's,
+ * so a forgotten id leaves the panel announcing as unnamed with no signal.
+ * Warn once, in dev, after the header is in the DOM.
+ */
+const warnIfHeaderNameIsDangling = () => {
+	if (process.env.NODE_ENV === 'production') return;
+	if (!slots.header || props.title) return;
+	nextTick(() => {
+		if (!dialog.value || document.getElementById(titleId)) return;
+		useLogger().warn(
+			`BbOffCanvas: the #header slot does not contain an element with id="${titleId}", so aria-labelledby points at nothing and the panel announces as unnamed. Bind the slot's \`titleId\` to your heading: <template #header="{ titleId }"><h2 :id="titleId">…</h2></template>.`
+		);
+	});
+};
+
 watch(model, toggleDialog);
 onMounted(() => {
 	if (model.value) toggleDialog(true);
+	warnIfHeaderNameIsDangling();
 });
 onBeforeUnmount(() => {
 	clearTimeout(denyCloseTimer);
 	removeEscapeListener();
-	teardownGestureListeners();
+	body.value?.removeEventListener('scroll', onBodyScroll);
+	bodyResizeObserver?.disconnect();
+	bodyResizeObserver = null;
 	leaveStack();
 	releaseTopLayer?.();
 	releaseTopLayer = null;
@@ -526,50 +604,108 @@ watch(
 );
 
 // ---------------------------------------------------------------------------
-// Pointer drag — drag-to-dismiss with velocity, rubber-band and scroll handoff.
+// Swipe-to-dismiss — VueUse `useSwipe` (fixed px threshold, not panel height).
 // ---------------------------------------------------------------------------
 const body = ref<HTMLElement | null>(null);
 const isDragging = ref(false);
+/** Fades `::backdrop` in parallel with the swipe-exit `transform` (Vaul overlay). */
+const swipeExiting = ref(false);
 
-/** Pointer travel before a gesture is classified as a drag (vs. a tap/scroll). */
-const DRAG_SLOP = 6;
-/** Fraction of the panel that must be dragged away to dismiss on release. */
-const DISMISS_DISTANCE_RATIO = 0.25;
-/** Release velocity (px/ms, toward close) that dismisses regardless of distance. */
-const DISMISS_VELOCITY = 0.5;
+/**
+ * Absolute travel toward the exit edge before the sheet dismisses.
+ * Height-ratio thresholds made tall filter sheets feel sticky and short ones
+ * nearly impossible; VueUse's default 50px reads the same on both.
+ */
+const SWIPE_THRESHOLD = 50;
+/**
+ * Start following the finger well below the dismiss threshold. `useSwipe`'s
+ * threshold also gates `onSwipe`, so a 50px track delay left the first 50px to
+ * native pan — on a row `<button>` that pan never reached the sheet body.
+ */
+const SWIPE_TRACK_PX = 8;
+/**
+ * Vaul sheet motion — 500ms / `cubic-bezier(0.32, 0.72, 0, 1)` (iOS sheet curve).
+ * Used for spring-back AND swipe-dismiss; both stay on the drag `transform`
+ * layer (never a CSS keyframe swap — that samples identity and flashes).
+ * @see https://emilkowal.ski/ui/building-a-drawer-component
+ */
+const SWIPE_EXIT_MS = 500;
+const SWIPE_EXIT_EASE = 'cubic-bezier(0.32, 0.72, 0, 1)';
+
+/** True while a swipe-dismiss transform is finishing — blocks clear mid-exit. */
+let swipeDismissPending = false;
+
+let bodyResizeObserver: ResizeObserver | null = null;
+/** Candidate gesture (touch on the panel, not the backdrop). */
+let swipeCandidate = false;
+/** Started inside the scrollable body — may need to hand off to scroll. */
+let swipeStartedInBody = false;
+/** Sheet is following the finger (dismiss-axis past threshold). */
+let swipeClaimed = false;
+/**
+ * Vaul `shouldDrag`: decided at touchstart, not per-move. Live `scrollTop`
+ * during the first 50px lets native pan and dismiss fight (tall auto sheets
+ * only overflow by a few px, so the edge flickers). Once this gesture is
+ * scrolling, it stays scrolling.
+ */
+let swipeLockedToScroll = false;
 
-type DragGesture = {
-	pointerId: number;
-	startX: number;
-	startY: number;
-	size: number;
-	startedInBody: boolean;
-	decided: boolean;
-	active: boolean;
-	samples: Array<{ t: number; pos: number }>;
+/**
+ * Allow vertical panning on the body so a tall sheet can scroll. Dismiss vs
+ * scroll is latched in `useSwipe` (`scrollLocksThisGesture`); directional
+ * `pan-up` / `pan-down` at the edge blocked scrolling filter sheets on mobile.
+ * `pan-y` lives in CSS; this only clears the inline `none` written during drag.
+ */
+const syncBodyDismissTouchAction = () => {
+	body.value?.style.removeProperty('touch-action');
 };
-let gesture: DragGesture | null = null;
 
-const axisDelta = (event: PointerEvent, g: DragGesture) =>
-	dragAxis.value === 'x' ? event.clientX - g.startX : event.clientY - g.startY;
+const onBodyScroll = () => syncBodyDismissTouchAction();
+
+watch(
+	body,
+	(el, prev) => {
+		prev?.removeEventListener('scroll', onBodyScroll);
+		bodyResizeObserver?.disconnect();
+		bodyResizeObserver = null;
+		if (!el) return;
+		el.addEventListener('scroll', onBodyScroll, { passive: true });
+		if (typeof ResizeObserver !== 'undefined') {
+			bodyResizeObserver = new ResizeObserver(() =>
+				syncBodyDismissTouchAction()
+			);
+			bodyResizeObserver.observe(el);
+		}
+		syncBodyDismissTouchAction();
+	},
+	{ flush: 'post' }
+);
 
-const axisPos = (event: PointerEvent) =>
-	dragAxis.value === 'x' ? event.clientX : event.clientY;
+watch([() => props.draggable, () => props.side, isVisible] as const, () =>
+	syncBodyDismissTouchAction()
+);
 
 /**
- * The drag is driven imperatively (direct style writes, no per-frame Vue render)
- * to stay smooth, and the transition is toggled inline so restoring it and the
- * resting offset happen in the same synchronous tick — no race with Vue's flush.
+ * Travel toward the exit edge in px. `useSwipe`'s lengthX/Y are
+ * `start − end`, so a finger moving down yields a negative lengthY.
  */
+const closeAmountFromSwipe = () => {
+	if (dragAxis.value === 'y') {
+		return closeSign.value === 1 ? -lengthY.value : lengthY.value;
+	}
+	return closeSign.value === 1 ? -lengthX.value : lengthX.value;
+};
+
 const beginDragVisual = () => {
 	if (dialog.value) dialog.value.style.transition = 'none';
+	if (body.value && dragAxis.value === 'y') {
+		body.value.style.touchAction = 'none';
+	}
 };
 
 const applyDragVisual = (closeAmount: number) => {
 	const el = dialog.value;
 	if (!el) return;
-	// Follow the pointer toward the exit edge with a direct compositor translate
-	// (no CSS var, no calc). Over-opening does nothing — no elastic stretch.
 	const px = closeAmount > 0 ? closeAmount * closeSign.value : 0;
 	el.style.transform =
 		dragAxis.value === 'x'
@@ -577,159 +713,185 @@ const applyDragVisual = (closeAmount: number) => {
 			: `translate3d(0, ${px}px, 0)`;
 };
 
-/** Restore the transition; on spring-back also animate the transform to rest. */
+/** Fully off-screen on the drag layer — same units as Vaul's `slideTo*` `to`. */
+const applyDismissTransform = () => {
+	const el = dialog.value;
+	if (!el) return;
+	el.style.transform =
+		props.side === 'bottom'
+			? 'translate3d(0, 100%, 0)'
+			: props.side === 'top'
+				? 'translate3d(0, -100%, 0)'
+				: props.side === 'left'
+					? 'translate3d(-100%, 0, 0)'
+					: 'translate3d(100%, 0, 0)';
+};
+
+/**
+ * Vaul `resetDrawer`: spring to rest on the same inline `transform` that drag
+ * wrote — never clear to identity then re-enable transition (one-frame flash).
+ */
 const endDragVisual = (springBack: boolean) => {
 	const el = dialog.value;
 	if (!el) return;
-	el.style.transition = ''; // restore the CSS transition synchronously
-	// Spring back animates the transform to rest. On dismiss we keep it so the
-	// exit `translate` continues seamlessly from where the finger let go.
-	if (springBack) el.style.transform = '';
+	if (springBack) {
+		el.style.transition = `transform ${SWIPE_EXIT_MS}ms ${SWIPE_EXIT_EASE}`;
+		el.style.transform = 'translate3d(0, 0, 0)';
+		window.setTimeout(() => {
+			if (!el.isConnected || swipeDismissPending) return;
+			el.style.removeProperty('transform');
+			el.style.removeProperty('transition');
+			syncBodyDismissTouchAction();
+		}, SWIPE_EXIT_MS);
+		return;
+	}
+	el.style.transition = '';
+	syncBodyDismissTouchAction();
 };
 
-/** Hard reset with no animation, once the panel is fully hidden. */
 const clearDragVisual = () => {
 	const el = dialog.value;
 	if (!el) return;
+	// Leave the frozen off-screen `transform` until `toggleDialog` has waited
+	// out the backdrop fade and is about to `dialog.close()`. Clearing earlier
+	// restores the stylesheet `transform` transition while `--open` can still
+	// be at rest — that is the on-screen flash.
+	if (swipeDismissPending) return;
 	el.style.removeProperty('transition');
 	el.style.removeProperty('transform');
 };
 
-/** Whether the scrollable body should absorb the gesture as a scroll instead. */
-const bodyAbsorbsScroll = (closeAmount: number) => {
-	if (dragAxis.value !== 'y' || !body.value) return false;
-	if (closeAmount <= 0) return true; // over-opening: let content scroll
-	return closeSign.value === 1
-		? body.value.scrollTop > 0 // bottom drawer: scroll up before dismissing
-		: body.value.scrollTop + body.value.clientHeight <
-				body.value.scrollHeight - 1; // top drawer: scroll down first
-};
-
-const teardownGestureListeners = () => {
-	window.removeEventListener('pointermove', onPanelPointerMove);
-	window.removeEventListener('pointerup', onPanelPointerUp);
-	window.removeEventListener('pointercancel', onPanelPointerCancel);
+/**
+ * Vaul dismiss: drawer and overlay move together on one clock, both on their
+ * own properties (drawer = inline `transform`, overlay = `::backdrop` opacity).
+ * `close()` is called only after the drawer is off-screen; `toggleDialog` then
+ * waits `transitionDuration` so the already-fading backdrop can finish before
+ * `dialog.close()` tears it down. Styles stay frozen until that wait ends.
+ */
+const finishDismissFromDrag = async () => {
+	const el = dialog.value;
+	if (!el) {
+		close();
+		return;
+	}
+	swipeDismissPending = true;
+	swipeExiting.value = true;
+	el.style.transition = `transform ${SWIPE_EXIT_MS}ms ${SWIPE_EXIT_EASE}`;
+	applyDismissTransform();
+	await wait(SWIPE_EXIT_MS);
+	if (!model.value) {
+		swipeDismissPending = false;
+		swipeExiting.value = false;
+		el.style.removeProperty('transform');
+		el.style.removeProperty('transition');
+		syncBodyDismissTouchAction();
+		return;
+	}
+	// Freeze the off-screen pose. Keep `transition: none` so `close()` cannot
+	// run a CSS `translate` close on the same element. Backdrop keeps fading
+	// via `--swipe-exit` / `--open` removal — those live on `::backdrop`.
+	el.style.transition = 'none';
+	applyDismissTransform();
+	close();
 };
 
-const abandonGesture = () => {
-	teardownGestureListeners();
-	gesture = null;
+/** Whether the scrollable body should absorb the gesture as a scroll instead. */
+const isVerticallyScrollable = (el: HTMLElement) => {
+	const { overflowY } = getComputedStyle(el);
+	if (overflowY !== 'auto' && overflowY !== 'scroll') return false;
+	return el.scrollHeight > el.clientHeight + 1;
 };
 
-const onPanelPointerDown = (event: PointerEvent) => {
-	// Preserve backdrop-intent tracking used by the outside-click close.
-	onBackdropPointerDown(event);
-	// Drag-to-dismiss is opt-in via `draggable`.
-	if (!props.draggable) return;
-	// The dialog element itself is the backdrop — handled by click, not drag.
-	if (event.target === event.currentTarget) return;
-	if (event.button !== 0 || !dialog.value) return;
-	if (gesture) abandonGesture();
-
-	const rect = dialog.value.getBoundingClientRect();
-	gesture = {
-		pointerId: event.pointerId,
-		startX: event.clientX,
-		startY: event.clientY,
-		size: dragAxis.value === 'x' ? rect.width : rect.height,
-		startedInBody: !!(event.target as HTMLElement).closest?.(
-			'.bb-offcanvas__body'
-		),
-		decided: false,
-		active: false,
-		samples: [{ t: performance.now(), pos: axisPos(event) }],
-	};
-	window.addEventListener('pointermove', onPanelPointerMove, {
-		passive: false,
-	});
-	window.addEventListener('pointerup', onPanelPointerUp);
-	window.addEventListener('pointercancel', onPanelPointerCancel);
-};
+const isAtDismissEdge = (el: HTMLElement) =>
+	closeSign.value === 1
+		? el.scrollTop <= 1
+		: el.scrollTop + el.clientHeight >= el.scrollHeight - 1;
 
-const onPanelPointerMove = (event: PointerEvent) => {
-	if (!gesture || event.pointerId !== gesture.pointerId) return;
-	const along = axisDelta(event, gesture);
-	const cross =
-		dragAxis.value === 'x'
-			? event.clientY - gesture.startY
-			: event.clientX - gesture.startX;
-
-	if (!gesture.decided) {
-		if (Math.abs(along) < DRAG_SLOP && Math.abs(cross) < DRAG_SLOP) return;
-		gesture.decided = true;
-		const closeAmount = along * closeSign.value;
-		const dominantAlongAxis = Math.abs(along) >= Math.abs(cross);
-		// Cross-axis swipe, or one the body can scroll: hand off to native scroll.
-		if (
-			!dominantAlongAxis ||
-			(gesture.startedInBody && bodyAbsorbsScroll(closeAmount))
-		) {
-			abandonGesture();
-			return;
+/**
+ * True when a scrollable ancestor under the finger is not at its dismiss edge.
+ * Latched at start so a 1px overflow on a `fit-content` (then capped) sheet
+ * cannot flip mid-gesture as native pan moves `scrollTop`.
+ */
+const scrollLocksThisGesture = (target: Element) => {
+	const root = dialog.value;
+	if (!root) return false;
+	let el: Element | null = target;
+	while (el && el !== root) {
+		if (el instanceof HTMLElement && isVerticallyScrollable(el)) {
+			if (!isAtDismissEdge(el)) return true;
 		}
-		gesture.active = true;
-		isDragging.value = true;
-		beginDragVisual();
+		el = el.parentElement;
 	}
-	if (!gesture.active) return;
-
-	event.preventDefault();
-	gesture.samples.push({ t: performance.now(), pos: axisPos(event) });
-	if (gesture.samples.length > 6) gesture.samples.shift();
-
-	// Write synchronously (no rAF hop): the panel stays glued to the pointer with
-	// no added latency. Multiple moves per frame just overwrite the inline
-	// `transform`; the browser still paints once, at the frame boundary.
-	applyDragVisual(along * closeSign.value);
+	return false;
 };
 
-/** Close-direction velocity (px/ms) from the most recent ~50ms of samples. */
-const releaseVelocity = (samples: DragGesture['samples']) => {
-	if (samples.length < 2) return 0;
-	const last = samples[samples.length - 1];
-	let start = samples[0];
-	for (let i = samples.length - 2; i >= 0; i--) {
-		start = samples[i];
-		if (last.t - samples[i].t >= 50) break;
-	}
-	const dt = last.t - start.t;
-	return dt > 0 ? ((last.pos - start.pos) / dt) * closeSign.value : 0;
+const resetSwipeState = () => {
+	swipeCandidate = false;
+	swipeStartedInBody = false;
+	swipeClaimed = false;
+	swipeLockedToScroll = false;
+	isDragging.value = false;
 };
 
-const onPanelPointerUp = (event: PointerEvent) => {
-	if (!gesture || event.pointerId !== gesture.pointerId) return;
-	const { active, size, samples } = gesture;
-	const closeAmount = axisDelta(event, gesture) * closeSign.value;
-	teardownGestureListeners();
-	gesture = null;
-	if (!active) return;
-
-	isDragging.value = false; // restore the transition for settle / exit
-	const dismiss =
-		closeAmount > size * DISMISS_DISTANCE_RATIO ||
-		(releaseVelocity(samples) > DISMISS_VELOCITY && closeAmount > DRAG_SLOP);
-
-	if (dismiss && !shouldPreventClose.value) {
-		// Restore the transition but keep the offset so the exit continues from
-		// where the finger let go; it is reset once the panel is fully hidden.
-		endDragVisual(false);
-		close();
-		return;
-	}
-	endDragVisual(true); // spring back to fully open
-	if (dismiss) triggerDenyCloseFeedback(300);
-};
+const { lengthX, lengthY } = useSwipe(dialog, {
+	threshold: SWIPE_TRACK_PX,
+	// Non-passive so we can preventDefault once the sheet is following the
+	// finger — otherwise Chrome cancels the gesture for native pan.
+	passive: false,
+	onSwipeStart: (event) => {
+		resetSwipeState();
+		if (!props.draggable || !isVisible.value) return;
+		// The dialog element itself is the backdrop — click closes, not swipe.
+		if (event.target === dialog.value) return;
+		const target = event.target;
+		if (!(target instanceof Element)) return;
+		swipeCandidate = true;
+		swipeStartedInBody = !!target.closest('.bb-offcanvas__body');
+		swipeLockedToScroll = swipeStartedInBody && scrollLocksThisGesture(target);
+	},
+	onSwipe: (event) => {
+		if (!swipeCandidate || !props.draggable || swipeLockedToScroll) return;
+		const closeAmount = closeAmountFromSwipe();
+
+		if (!swipeClaimed) {
+			// Finger moving into content: this gesture stays a scroll even if they
+			// later reverse toward the dismiss edge.
+			if (swipeStartedInBody && closeAmount < -SWIPE_TRACK_PX) {
+				swipeLockedToScroll = true;
+				return;
+			}
+			// Require the dismiss-axis itself to clear the track slop. A mostly
+			// horizontal flick on a short sheet must not latch the panel just
+			// because |dx| exceeded the track threshold.
+			if (closeAmount < SWIPE_TRACK_PX) return;
+			swipeClaimed = true;
+			isDragging.value = true;
+			beginDragVisual();
+		}
 
-const onPanelPointerCancel = (event: PointerEvent) => {
-	if (!gesture || event.pointerId !== gesture.pointerId) return;
-	const wasActive = gesture.active;
-	teardownGestureListeners();
-	gesture = null;
-	if (wasActive) {
-		isDragging.value = false;
+		// Once the sheet is following the finger, this gesture stays a drag
+		// until lift — even after reversing to rest. `touch-action` is sampled
+		// at touchstart (`pan-y`), so dropping preventDefault here would let
+		// native scroll start mid-drag (sheet at 0, list jumping).
+		event.preventDefault();
+		applyDragVisual(closeAmount);
+	},
+	onSwipeEnd: () => {
+		if (!swipeClaimed) {
+			resetSwipeState();
+			return;
+		}
+		const closeAmount = closeAmountFromSwipe();
+		resetSwipeState();
+		// Fixed px threshold — same on a tall filters sheet and a short menu.
+		if (closeAmount >= SWIPE_THRESHOLD && !shouldPreventClose.value) {
+			void finishDismissFromDrag();
+			return;
+		}
 		endDragVisual(true);
-	}
-};
+		if (closeAmount >= SWIPE_THRESHOLD) triggerDenyCloseFeedback(300);
+	},
+});
 </script>
 
 <style lang="postcss">
@@ -747,6 +909,18 @@ export type { Sizes };
 type OffCanvasSize = NonNullable<Size<Sizes>['size']> | 'auto';
 
 export type BbOffCanvasProps = {
+	/**
+	 * 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,
 	 * drag-to-dismiss AND the header close (×) button (denied attempts play the
@@ -769,10 +943,10 @@ export type BbOffCanvasProps = {
 	 */
 	fullscreen?: boolean | 'mobile';
 	/**
-	 * Enable drag-to-dismiss. The panel can be dragged from anywhere toward its
-	 * edge to close, and a grab handle is shown on the inner edge as the
-	 * affordance. When `false`, the panel is static (dismiss via the close button,
-	 * backdrop, or Escape only).
+	 * Enable drag-to-dismiss via VueUse `useSwipe` (fixed ~50px threshold toward
+	 * the exit edge, including from the scrollable body once it is at its scroll
+	 * edge). A grab handle on the inner edge is the visual cue. When `false`, the
+	 * panel is static (dismiss via the close button, backdrop, or Escape only).
 	 * @defaultValue `false`
 	 */
 	draggable?: boolean;
@@ -849,18 +1023,32 @@ export type BbOffCanvasHeaderSlotProps = {
 };
 
 /** Props exposed by the `title` slot. */
+/** Props exposed by the `description` slot. */
+export type BbOffCanvasDescriptionSlotProps = {
+	/** The `description` prop value. */
+	text: BbOffCanvasProps['description'];
+};
+
 export type BbOffCanvasTitleSlotProps = {
 	/** The `title` prop value. */
 	text: BbOffCanvasProps['title'];
 };
 
 export type BbOffCanvasSlots = {
+	/**
+	 * 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: BbOffCanvasDescriptionSlotProps) => any;
 	/**
 	 * Replaces the entire off-canvas header section (title + close button). Maintains accessibility wiring via the provided props.
 	 */
 	header?: (props: BbOffCanvasHeaderSlotProps) => any;
 	/**
-	 * Replaces the default title text inside the header. Remains linked to the panel through `aria-labelledby`.
+	 * Replaces the default title text inside the header. Remains linked to the
+	 * panel through `aria-labelledby`. Providing this slot renders the header even
+	 * when `title` is unset — a slotted title is a title.
 	 */
 	title?: (props: BbOffCanvasTitleSlotProps) => any;
 	/**
@@ -892,6 +1080,13 @@ export type BbOffCanvasSlots = {
 	/* Duration for the stack shift + pad. Zeroed while a peer resizes so parents
 	   track the live size instead of lagging behind a 250ms animation. */
 	--stack-transition-duration: var(--transition-duration);
+	/* 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);
 	--transition-timing-function: var(--bb-ease);
 	background-color: var(--bb-panel);
 	border: 1px solid var(--bb-border);
@@ -1067,6 +1262,11 @@ export type BbOffCanvasSlots = {
 		transform-origin: center bottom;
 	}
 
+	&.bb-offcanvas--top .bb-offcanvas__body,
+	&.bb-offcanvas--bottom .bb-offcanvas__body {
+		touch-action: pan-y;
+	}
+
 	&.bb-offcanvas--fullscreen {
 		border-radius: 0;
 		height: 100%;
@@ -1127,7 +1327,20 @@ export type BbOffCanvasSlots = {
 			background-color var(--transition-duration) var(--bb-ease);
 	}
 
-	/* Grab handle: reliable drag surface on touch, centred on the inner edge. */
+	/* Vaul overlay: fade the dim with the swipe-exit, not after it. `--open`
+	   stays on for the 500ms so `dialog.close()` does not tear the backdrop
+	   down mid-fade; this only overrides opacity. */
+	&.bb-offcanvas--open.bb-offcanvas--swipe-exit::backdrop {
+		opacity: 0;
+		transition:
+			opacity 500ms cubic-bezier(0.32, 0.72, 0, 1),
+			background-color 500ms cubic-bezier(0.32, 0.72, 0, 1);
+	}
+
+	/* Grab handle: reliable drag surface on touch, centred on the inner edge.
+	   z-index above the body: a sheet search (flyout leftover `z-index: 1`, or
+	   `position: relative`) would otherwise paint over the 4px pill once the
+	   headerless body scrolls its padding-top away. */
 	.bb-offcanvas__handle {
 		background-color: var(--bb-border);
 		border-radius: 999px;
@@ -1135,7 +1348,7 @@ export type BbOffCanvasSlots = {
 		flex-shrink: 0;
 		position: absolute;
 		touch-action: none;
-		z-index: 1;
+		z-index: 2;
 	}
 
 	&.bb-offcanvas--bottom .bb-offcanvas__handle,
@@ -1171,24 +1384,27 @@ export type BbOffCanvasSlots = {
 	   `:first-child` because an absolutely-positioned drag handle can precede the
 	   body in the DOM, which would defeat `:first-child`. */
 	&.bb-offcanvas--no-header .bb-offcanvas__body-content {
-		padding-top: var(--bb-panel-p);
+		padding-top: var(--py);
 	}
 
 	/* Make room for the handle so it does not overlap header content. */
 	&.bb-offcanvas--has-handle.bb-offcanvas--bottom .bb-offcanvas__header,
 	&.bb-offcanvas--has-handle.bb-offcanvas--bottom.bb-offcanvas--no-header
 		.bb-offcanvas__body-content {
-		padding-top: calc(var(--bb-panel-p) + 12px);
+		padding-top: calc(var(--py) + 12px);
 	}
 
 	.bb-offcanvas__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);
 		position: relative;
 		/* Header is a dependable drag surface even when content scrolls. */
 		touch-action: none;
@@ -1197,38 +1413,102 @@ export type BbOffCanvasSlots = {
 			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 — the title usually names the
+			 * record you are acting on, so hiding the end of it is worse than a
+			 * second line. `anywhere` because what overflows is typically one
+			 * unbroken id with nowhere to break. Matters more here than on the
+			 * dialog: an adaptive sheet is as narrow as the phone. */
+			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);
+			}
+		}
+		/* 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-offcanvas__description) {
+			align-items: flex-start;
+			flex-direction: column;
+			row-gap: 2px;
 		}
 
+		.bb-offcanvas__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);
+			}
+		}
+
+		/* 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));
 		}
 	}
 
 	.bb-offcanvas__body {
 		flex: 1 1 auto;
+		/* Keep descendant z-index (sticky/relative search) inside this scrollport
+		   so it cannot cover the absolutely-positioned grab handle. */
+		isolation: isolate;
+		/* Cap to the panel, not to the content — default `min-height: auto` lets a
+		   tall sheet (filter dropdown) grow the flex item past `max-height: 100%`
+		   and then nothing scrolls. */
+		min-height: 0;
 		overflow: auto;
+		overscroll-behavior: contain;
 		position: relative;
 
-		&:first-child {
-			.bb-offcanvas__body-content {
-				padding-top: var(--bb-panel-p);
-
-				> .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));
-				}
-			}
-		}
-
 		.bb-offcanvas__body-content {
-			padding: 0px var(--bb-panel-p) var(--dialog-gap, var(--bb-panel-p));
+			padding: 0px var(--px) var(--dialog-gap, var(--py));
+
+			/*
+			 * The headerless close control, pinned to the panel corner.
+			 *
+			 * NOT keyed on `.bb-offcanvas__body:first-child`, which is what this
+			 * rule used to sit under. A DRAGGABLE sheet renders
+			 * `.bb-offcanvas__handle` before the body, so `:first-child` never
+			 * matched there, the button fell back to `position: static`, and it
+			 * painted in normal flow AFTER the content — i.e. at the bottom of the
+			 * sheet. Every adaptive `BbSelectPopover` hit this: its sheet is
+			 * `draggable: true` and titleless, so it takes exactly this path.
+			 * Measured before the fix: `position: static`, 228px below the body top.
+			 *
+			 * The same `:first-child` fragility was already fixed a few rules up
+			 * for the no-header padding, with the reason spelled out
+			 * ("an absolutely-positioned drag handle can precede the body"); this
+			 * rule simply did not get the same treatment. No condition is needed
+			 * at all — the element only renders when there is no header
+			 * (`v-if="!renderHeader() && !hideClose"`), which is what the comment
+			 * beside it in the SFC already claimed this selector did.
+			 */
+			> .bb-close-button {
+				--size: 28px;
+				--p: 7px;
+				position: absolute;
+				right: calc(var(--px) - var(--p));
+				top: calc(var(--py) - var(--p));
+			}
 		}
 
 		/* Keep nested overlays out of flow while closed, mirroring dialog behavior. */
@@ -1240,7 +1520,7 @@ export type BbOffCanvasSlots = {
 
 	.bb-offcanvas__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 {