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

package/dist/ai/source/BbDropdownGroup.md

@@ -333,11 +333,14 @@ export type InternalGroup = DropdownEntryBase & {
 	 * predictable size regardless of row content. A `number` is pixels; a `string`
 	 * is any CSS length (`'50vh'`, `'20rem'`). `'none'` (or `0`) removes the cap.
 	 *
-	 * `searchable` groups default to `280` (≈ 10 rows of 28px), since a searched
-	 * list is usually long; set your own value to tweak, or `'none'` to uncap.
-	 * Non-searchable groups are uncapped unless you set this.
+	 * `searchable` groups default to `280` (≈ 10 rows of 28px) **on the flyout**,
+	 * since a searched list is usually long; set your own value to tweak, or
+	 * `'none'` to uncap. The adaptive sheet ignores the cap so the OffCanvas
+	 * body stays the only scroller (nested group overflow trapped swipes that
+	 * started on a row). Non-searchable flyout groups are uncapped unless you
+	 * set this.
 	 *
-	 * @defaultValue `280` for `searchable` groups, otherwise unset
+	 * @defaultValue `280` for `searchable` flyout groups, otherwise unset
 	 */
 	maxHeight?: number | string;
 	/**
@@ -506,6 +509,17 @@ export type BbDropdownProps = {
 	 * @defaultValue `config.adaptive` (`true`)
 	 */
 	adaptive?: boolean;
+	/**
+	 * Apply the compact density variant — the same ladder `BbSelect` uses, on
+	 * both surfaces: flyout rows go 28px → 24px, sheet rows 44px → 36px. The
+	 * label size does not change; density here is height, as it is for a select.
+	 *
+	 * A menu row is a touch target in a way a select option is not quite — a
+	 * mis-tap fires the neighbouring COMMAND rather than picking the wrong value
+	 * — so the compact sheet stops at 36px and never follows the flyout down to
+	 * 24px. That is the same floor the select's sheet holds.
+	 */
+	compact?: boolean;
 	/**
 	 * Element the panel positions itself against, when it should differ from the
 	 * activator — e.g. a wrapper that the activator is only a part of, so the menu
@@ -585,7 +599,8 @@ export type BbDropdownProps = {
 	padding?: number;
 	/**
 	 * Position of the dropdown relative to the activator.
-	 * Use `'cursor'` to anchor at the mouse/touch coordinates (hides arrow).
+	 * Use `'cursor'` to anchor at the mouse/touch coordinates.
+	 * (No arrow is drawn either way — arrows are tooltip-only in v3.)
 	 *
 	 * @defaultValue `'bottom'`
 	 */
@@ -786,7 +801,9 @@ export type BbDropdownGroupEvents = {
 ## Styles
 
 ```css
-/* @inherit --transition-duration — set inline by the adaptive surface */
+/* @inherit --transition-duration — set inline by the adaptive surface;
+   @inherit --py — the adaptive sheet's rules target BbOffCanvas elements, which
+   declare it on the panel */
 .bb-dropdown {
 	overflow: visible;
 
@@ -999,7 +1016,11 @@ export type BbDropdownGroupEvents = {
 		 * is inert there and `max-height` alone caps it. */
 		flex: 1 1 auto;
 		flex-direction: column;
-		font-size: calc(var(--bb-fs) - 1px);
+		/* `--bb-fs`, matching the select's option label. These two menus sit at
+		   the same 28px row height on the same screen and their labels were a
+		   pixel apart (13 against 14) — the desktop twin of the sheet drift, and
+		   the kind of difference nobody can name but everybody sees. */
+		font-size: var(--bb-fs);
 		gap: 1px;
 		line-height: 1.2;
 		max-height: var(--max-h, none);
@@ -1092,9 +1113,11 @@ export type BbDropdownGroupEvents = {
 			/* Keep natural row height under a capped, scrolling container. */
 			flex-shrink: 0;
 			height: 28px;
-			/* Let the row sit inside a fixed `--w` panel instead of expanding it. */
+			/* Let the row sit inside a fixed `--w` panel instead of expanding it.
+			 * Also the containing block for the absolute selection check. */
 			min-width: 0;
 			padding: 2px 6px;
+			position: relative;
 			text-align: left;
 			width: 100%;
 
@@ -1132,8 +1155,7 @@ export type BbDropdownGroupEvents = {
 			}
 
 			.item__prepend-icon,
-			.item__append-icon,
-			.item__check {
+			.item__append-icon {
 				--size: 16px;
 				flex-shrink: 0;
 				font-size: 15px;
@@ -1179,21 +1201,42 @@ export type BbDropdownGroupEvents = {
 
 				.item__prepend-icon,
 				.item__append-icon,
-				.item__check,
 				.item__chevron {
 					margin-top: 2px;
 				}
+
+				/* Absolute check: pin to the title line, not the row mid-point. */
+				.item__check {
+					margin-top: 0;
+					top: 6px;
+					transform: none;
+				}
 			}
 
-			.item__check,
 			.item__chevron {
 				--size: 16px;
 				color: var(--bb-text-muted);
+				flex-shrink: 0;
+				font-size: 19px;
 				margin-inline-start: auto;
 			}
 
+			/*
+			 * Selection check is out of flow. Selectable groups always mount the
+			 * glyph (stroke animates in when selected); leaving it in flex would
+			 * reserve ~24px on EVERY row and make ellipsis truncate as if an
+			 * append icon were present. Absolute + pad-only-when-selected lets
+			 * unselected labels use the full row.
+			 */
 			.item__check {
+				--size: 16px;
 				color: var(--bb-text);
+				font-size: 15px;
+				inset-inline-end: 6px;
+				pointer-events: none;
+				position: absolute;
+				top: 50%;
+				transform: translateY(-50%);
 
 				path {
 					stroke-dasharray: 30;
@@ -1204,16 +1247,14 @@ export type BbDropdownGroupEvents = {
 			}
 
 			&.bb-dropdown__item--selected {
+				/* Keep the label clear of the absolute check. */
+				padding-inline-end: calc(6px + 16px + 4px);
+
 				.item__check path {
 					stroke-dashoffset: 0;
 				}
 			}
 
-			.item__chevron {
-				flex-shrink: 0;
-				font-size: 19px;
-			}
-
 			&.bb-dropdown__item--variant-destructive {
 				color: var(--bb-danger);
 
@@ -1251,6 +1292,24 @@ export type BbDropdownGroupEvents = {
 	}
 }
 
+/* ---- Compact density --------------------------------------------------
+ * The same ladder `BbSelect` walks, so a dense toolbar can hold a select and a
+ * menu that agree: the flyout drops 28px → 24px here, and the SHEET drops
+ * 44px → 36px through `--sheet-row-h` (AdaptiveDropdown reads
+ * `listboxOptionHeight`, the helper the listbox reads, so neither can drift).
+ * The label does not shrink — density is height, exactly as it is for a select
+ * — and the sheet never follows the flyout to 24px, because a menu row is a
+ * touch target whose mis-tap fires the neighbouring COMMAND. */
+.bb-dropdown.bb-dropdown--compact {
+	.bb-dropdown__item {
+		height: 24px;
+	}
+
+	.bb-dropdown__placeholder {
+		min-height: 24px;
+	}
+}
+
 /* ---- Adaptive drill-down sheet ----------------------------------------
  * The mobile surface (`AdaptiveDropdown`) reuses the `.bb-dropdown` classes
  * above by carrying `.bb-dropdown` on the off-canvas root; these rules only
@@ -1260,7 +1319,104 @@ export type BbDropdownGroupEvents = {
 	/* Shrink the off-canvas chrome so the sheet reads as compact as the desktop
 	   panel rather than a full dialog. */
 	--dialog-gap: 8px;
-	--dialog-title-fs: calc(var(--bb-fs) - 1px);
+	/* The title tracks the row label rather than the off-canvas default. It was
+	   pulled DOWN to `--bb-fs - 1` (13px) once, which put it under the rows it
+	   heads; the default (`--bb-fs + 2`) fixed that until the rows moved to 18px
+	   and passed it again. Tied to the same constant, a title can no longer end
+	   up smaller than the list beneath it whatever that constant becomes. */
+	--dialog-title-fs: var(--sheet-option-fs, 1rem);
+
+	/* Root sheet title via `offCanvasProps.title` (no drill nav / custom
+	   `#header`): centre it and tighten the title→divider air like BbSelect.
+	   `:not(:has(.bb-dropdown__nav))` keeps consumer `#header` content and the
+	   drill nav on their own layouts. */
+	.bb-offcanvas__header:not(:has(.bb-dropdown__nav)) {
+		border-bottom: var(--bb-border-w) solid var(--bb-border);
+		padding-bottom: calc(var(--py) - 6px);
+
+		> .bb-offcanvas__title {
+			flex: 1 1 auto;
+			text-align: center;
+		}
+	}
+
+	/* Drill nav owns the title→body air. Drop the OffCanvas header's own bottom
+	   pad so it does not stack under the nav and push chips / search below
+	   BbSelect's. */
+	.bb-offcanvas__header:has(.bb-dropdown__nav--drill) {
+		padding-bottom: 0;
+	}
+
+	/* Body used to start flush under the header. Match BbSelect's step down
+	   from the title rule. Specificity beats OffCanvas's nested shorthand.
+	   Skip headerless sheets (`--no-header`): OffCanvas already supplies the
+	   top inset (and the handle clearance) that this would otherwise crush to
+	   0.5rem — the filters root with no title / drill nav / `#header`. */
+	&.bb-offcanvas:not(.bb-offcanvas--no-header)
+		.bb-offcanvas__body
+		.bb-offcanvas__body-content {
+		padding-top: 0.5rem;
+	}
+
+	/* Flat multi-group sheets: space a following section after the previous
+	   group's items/search. */
+	.bb-dropdown__group-items + .bb-dropdown__group-title,
+	.bb-dropdown__group-search + .bb-dropdown__group-title,
+	.bb-dropdown__divider + .bb-dropdown__group-title {
+		margin-top: 0.5rem;
+	}
+
+	/* Group headers on the sheet read as BbSelect's sheet label — centred title
+	   weight/size, not the flyout's faint left-aligned section caption. No
+	   hairline here: the select sheet label's rule lives on the OffCanvas
+	   header, and repeating it under every group stacked like extra chrome.
+	   Nested drills with `hideLabel` skip this entirely; the drill nav title is
+	   already that label. */
+	.bb-dropdown__group-title {
+		align-items: center;
+		border-bottom: 0;
+		color: var(--bb-text);
+		column-gap: 6px;
+		display: flex;
+		font-size: var(--dialog-title-fs, var(--sheet-option-fs, 1rem));
+		font-weight: 500;
+		justify-content: center;
+		letter-spacing: normal;
+		/* Match select's title→body air (`padding-bottom: calc(var(--py) - 6px)`
+		   on the OffCanvas header) so the label sits above the soft search the
+		   same way City sits above its field. */
+		padding: 0.25rem 0 calc(var(--py, var(--bb-panel-p)) - 6px);
+
+		.group-title__content {
+			flex: 1 1 auto;
+			line-height: normal;
+			overflow-x: clip;
+			overflow-y: visible;
+			text-align: center;
+		}
+
+		.group-title__prepend-icon,
+		.group-title__append-icon {
+			--size: 1.25rem;
+			font-size: var(--size);
+		}
+	}
+
+	/* Headerless sheet: the first group title IS the sheet label (Flat filters'
+	   "Status" beside BbSelect's "City"). Body already clears the handle via
+	   `--no-header` padding (`calc(var(--py) + 12px)`); the items-container's
+	   4px (meant for air under a nav divider) and the title's own 0.25rem top
+	   pad were stacking on top and dropping the label ~8px below City.
+	   Measured: City title @29px, Flat Status @33–37px before this. */
+	&.bb-offcanvas--no-header .bb-dropdown__items-container {
+		padding-top: 0;
+	}
+
+	&.bb-offcanvas--no-header
+		.bb-dropdown__items-container
+		> .bb-dropdown__group-title:first-child {
+		padding-top: 0;
+	}
 
 	/* Clip the sideways level slide so it never spills a horizontal scrollbar. */
 	.bb-dropdown__adaptive-body {
@@ -1290,55 +1446,132 @@ export type BbDropdownGroupEvents = {
 	 * construction, so this selector needs no viewport clause of its own. The
 	 * JS half lives in `useTouchRowLadder`, for the virtualized option lists
 	 * whose row heights feed a virtualizer instead of a stylesheet. */
+	/* Belt for an explicit `maxHeight` leaking onto the sheet: never nest a
+	   second scrollport inside the OffCanvas body. */
+	.bb-dropdown__group-items--capped {
+		display: contents;
+		max-height: none;
+		overflow: visible;
+	}
+
 	.bb-dropdown__items-container {
-		font-size: calc(var(--bb-fs) + 1px);
+		/* Published by AdaptiveDropdown from `listboxMetrics`, the same helpers the
+		   select's sheet reads. The fallbacks are the shipped touch values, so the
+		   stylesheet still reads on its own. */
+		font-size: var(--sheet-option-fs, 1rem);
 		max-height: none;
 		min-width: 0;
 		overflow-y: visible;
-		padding: 0;
+		/* Horizontal inset is the OffCanvas body's `--px`. Do not re-pad here
+		   (or on the rows) to fake alignment with search/chips. */
+		padding: 4px 0 0;
 		width: 100%;
 
 		.bb-dropdown__item {
-			height: 44px;
-			padding: 2px 10px;
+			height: var(--sheet-row-h, 44px);
+			/* Flyout rows are `2px 6px`. +4px start so the label shares the
+			   search field's text edge (`padding-inline: 0.75rem` on the fill). */
+			padding-left: calc(6px + 4px);
+			/* iOS treats a <button> as a tap target and will not hand the pan to
+			   the sheet body unless the control itself opts into vertical panning.
+			   Without this, dismiss/scroll work on the handle and miss on rows. */
+			touch-action: pan-y;
 
 			&.bb-dropdown__item--description {
-				min-height: 44px;
+				min-height: var(--sheet-row-h, 44px);
 			}
 
+			.item__content {
+				line-height: normal;
+				overflow-x: clip;
+				overflow-y: visible;
+			}
+
+			/* One step under the row label, the same step the listbox puts between
+			   an option and its group header — so the two sheets' secondary text
+			   agrees as well as their primary. */
 			.item__description {
-				font-size: calc(var(--bb-fs) - 1px);
+				font-size: calc(var(--sheet-option-fs, 1rem) - 2px);
 				line-height: 18px;
 			}
 		}
 
 		.bb-dropdown__placeholder {
-			min-height: 44px;
-			padding: 2px 10px;
+			min-height: var(--sheet-row-h, 44px);
+			padding-left: calc(6px + 4px);
 		}
 
-		.bb-dropdown__group-title {
-			font-size: calc(var(--bb-fs) - 1px);
-			padding: 8px 10px 4px;
+		/* Icons scale with the label they sit beside. The desktop sizes (16px
+		   glyphs against a 13px label) were tuned for a 28px row; left alone in a
+		   44px row with an 18px label they read as undersized — the chevron that
+		   says "this opens another level" ended up the smallest thing in the row.
+		   One step up, so the glyph keeps roughly the proportion to its label that
+		   it has on the desktop panel. BbIcon reads `--size`; keep `font-size` on
+		   the same token so the glyph box and the type size cannot drift. */
+		.item__prepend-icon,
+		.item__append-icon,
+		.item__check,
+		.item__chevron {
+			--size: 1.25rem;
+			font-size: var(--size);
 		}
+
+		/* Group titles are restyled as select-sheet labels on `--adaptive`
+		   (see block above); do not re-apply the flyout caption metrics here. */
 	}
 
+	/* Soft filled search — mirrors BbSelectPopover's sheet field: no underline
+	   rule, faint `--bb-muted` wash, and the same inset as sheet chips / row
+	   padding so the fill lines up. */
 	.bb-dropdown__group-search {
-		padding: 8px 10px;
+		background-color: var(--bb-muted);
+		border-bottom: 0;
+		border-radius: var(--bb-radius);
+		/* Undo the flyout's full-bleed negative margins. No extra inline inset —
+		   the OffCanvas body already pads `--px`. */
+		margin: 0 0 0.25rem;
+		padding: 0.625rem 0.75rem;
+		position: relative;
+		top: auto;
+		transition: background-color var(--bb-transition-fast) ease;
+		/* Flyout search is sticky `z-index: 1`; that same stacking painted over
+		   the sheet's grab handle once the body scrolled. */
+		z-index: auto;
+
+		/* One emphasis stop above the resting --bb-muted (6%) fill. */
+		&:focus-within {
+			background-color: color-mix(in oklab, var(--bb-text) 8%, var(--bb-panel));
+		}
+
+		/* Lens on the trailing edge, same side as BbSelect's sheet search. */
+		.bb-dropdown__search-icon {
+			order: 1;
+		}
+
+		.bb-dropdown__search-input {
+			font-size: var(--bb-input-fs);
+			order: 0;
+		}
+
+		/* Busy strip sits on the field's bottom edge (no border to overlay). */
+		.bb-dropdown__group-loading {
+			border-radius: 0 0 var(--bb-radius) var(--bb-radius);
+			bottom: 0;
+		}
 	}
 
 	/* Removable selection chips for the current multi-select level — sit above the
 	   menu (and its search), mirroring BbSelect's sheet. */
 	.bb-dropdown__sheet-selection {
 		flex-shrink: 0;
-		padding: 0 4px 8px;
+		padding: 0 0 0.5rem;
 		text-align: left;
 	}
 
 	.bb-dropdown__sheet-chips {
 		display: flex;
 		flex-wrap: wrap;
-		gap: 8px;
+		gap: 0.5rem;
 	}
 
 	/* Touch target: the xl badge is a ~24px pill — fine inline on desktop, too
@@ -1347,9 +1580,9 @@ export type BbDropdownGroupEvents = {
 	   padding and a bigger clear glyph; the badge API stays untouched. Mirrors
 	   BbSelectPopover's sheet chips. */
 	.bb-dropdown__sheet-chip {
-		--min-size: 34px;
-		--padding-inline: 12px;
-		--clear-size: 20px;
+		--min-size: 2.125rem;
+		--padding-inline: 0.75rem;
+		--clear-size: 1.25rem;
 	}
 
 	.bb-dropdown__nav {
@@ -1357,42 +1590,69 @@ export type BbDropdownGroupEvents = {
 		column-gap: 6px;
 		display: flex;
 		width: 100%;
-	}
 
-	.bb-dropdown__nav-back {
-		align-items: center;
-		background: transparent;
-		border: none;
-		border-radius: var(--bb-radius-sm);
-		color: var(--bb-text);
-		cursor: pointer;
-		display: inline-flex;
-		flex-shrink: 0;
-		/* Touch target: this is the sheet's only way back up a level. */
-		height: 40px;
-		justify-content: center;
-		margin-inline-start: -8px;
-		width: 40px;
+		/* Drilled in: a navigation bar. The TITLE LINE sets the bar height — same
+		   as BbSelect's OffCanvas title — so City and Status share one baseline.
+		   The back control is a BbButton ghost sm, absolutely pinned to the
+		   OffCanvas header with equal inset from the sheet's top and left. */
+		&--drill {
+			/* Title line sets the bar height — same as BbSelect's OffCanvas title.
+			   Sit in the header's `--px`; do not pull out and re-pad to fake a
+			   full-bleed bar. Bottom pad matches BbSelect's
+			   `calc(var(--py) - 6px)`. No `position: relative` — the back button's
+			   containing block is the header. */
+			display: block;
+			padding-bottom: calc(var(--py, var(--bb-panel-p)) - 6px);
+
+			/* Equal inset from the sheet edges. Header is `position: relative`
+			   in OffCanvas. Size/chrome come from BbButton ghost sm.
+			   Use `--bb-panel-p`, not `--px`: BbButton redefines `--px` as its
+			   own padding token, which collapsed the inset to 10px. */
+			.bb-dropdown__nav-back {
+				left: var(--bb-panel-p);
+				position: absolute;
+				top: var(--bb-panel-p);
+
+				/* Same chevron_right asset the submenu rows use, pointed back. */
+				.bb-button__icon {
+					transform: rotate(180deg);
+				}
+			}
 
-		&:hover {
-			background-color: color-mix(in oklab, var(--bb-text) 8%, transparent);
+			/* Spacer kept in the DOM for the drill a11y tests; layout is now the
+			   title's equal inline gutters below. */
+			.bb-dropdown__nav-gutter {
+				display: none;
+			}
 		}
+	}
 
-		.bb-dropdown__nav-back-icon {
-			--size: 16px;
-			/* Reuse `chevron_right` pointed the other way (no left asset exists). */
-			transform: rotate(180deg);
-		}
+	/* Pure spacer, mirroring the back button's box (root / non-drill layouts). */
+	.bb-dropdown__nav-gutter {
+		height: 24px;
+		width: 24px;
 	}
 
-	.bb-dropdown__nav-title {
+	.bb-offcanvas__title.bb-dropdown__nav-title {
 		flex: auto;
 		font-weight: 500;
+		/* Same 1em line box as BbSelect's sheet title so the cap sits on the
+		   same baseline. Descenders ("Tags") paint into the drill nav's bottom
+		   pad — `overflow-y: visible`; ellipsis still clips on X only. */
 		min-width: 0;
-		overflow: hidden;
+		overflow-x: clip;
+		overflow-y: visible;
 		text-overflow: ellipsis;
 		white-space: nowrap;
 	}
+
+	.bb-dropdown__nav--drill .bb-dropdown__nav-title {
+		/* Equal side gutters matching BbButton sm icon-only (24px) so the label
+		   centres. */
+		display: block;
+		padding-inline: 24px;
+		text-align: center;
+	}
 }
 
 /* Level slide: drilling in enters from the right and the old level exits left;
@@ -1428,4 +1688,15 @@ export type BbDropdownGroupEvents = {
 	opacity: 0;
 	transform: translateX(28px);
 }
+
+/*
+ * Q14.3 — see `reservesCheckSpace` in BbDropdown.vue for why this is scoped to
+ * an auto-width panel. `:has(.item__check)` targets exactly the rows a
+ * selectable group mounts a check on, so a non-selectable group in the same
+ * menu is untouched. The value matches the `--selected` rule's clearance; when
+ * both apply they agree, so nothing shifts on selection.
+ */
+.bb-dropdown__panel--reserve-check .bb-dropdown__item:has(.item__check) {
+	padding-inline-end: calc(6px + 16px + 4px);
+}
 ```

package/dist/ai/source/BbForm.md

@@ -27,7 +27,7 @@
 </template>
 
 <script setup lang="ts">
-import { useTemplateRef } from 'vue';
+import { getCurrentInstance, useTemplateRef } from 'vue';
 import { useForm } from 'vee-validate';
 import { useBbFormContextHost } from '@/composables/useBbFormContext';
 
@@ -41,7 +41,10 @@ const props = defineProps<{
 	id?: string;
 }>();
 
-const emit = defineEmits<{
+// Declared for the public typing and the manifest. The handler is INVOKED
+// directly (see `runSubmitListeners`) rather than through the returned `emit`,
+// so the returned function is deliberately unused.
+defineEmits<{
 	/** Fired only when every field passes; carries the collected form values. */
 	submit: [values: Record<string, unknown>];
 }>();
@@ -57,9 +60,94 @@ const {
 	validate,
 } = useForm();
 
-// Validates all fields on native submit; emits `submit` with the values only
-// when the form is valid (and preventDefault's the native navigation).
-const onSubmit = handleSubmit((formValues) => emit('submit', formValues));
+/*
+ * Validates all fields on native submit, then runs the consumer's `@submit`
+ * with the values — only when the form is valid (and preventDefault's the
+ * native navigation).
+ *
+ * Q18.3 — why this calls the listener instead of `emit('submit', …)`.
+ * vee-validate decides "is a submit still in flight?" from what the handler
+ * RETURNS: return a thenable and `isSubmitting` stays true until it settles;
+ * return nothing and it clears immediately. Vue's `emit` always returns
+ * undefined, so `isSubmitting` used to drop as soon as VALIDATION resolved —
+ * measured over 10 ticks, `[true,false,false,…]` against `[true,true,true,…]`
+ * for a handler whose promise is returned. Every guide and the manifest tell
+ * you to bind a button's `loading` to it, so the spinner flashed for one frame
+ * and the user could double-submit a save that was still running.
+ *
+ * `vnode.props.onSubmit` rather than `useAttrs()`: `submit` is a DECLARED
+ * emit, so Vue strips it from `$attrs`. The raw prop is still on the vnode.
+ *
+ * The shape is preserved in both directions — an array of listeners (two
+ * `@submit` handlers) is called in order, and a sync handler returns undefined
+ * exactly as before, so nothing about existing behaviour changes except that
+ * an async handler is now awaited.
+ */
+const instance = getCurrentInstance();
+
+type SubmitListener = (values: Record<string, unknown>) => unknown;
+
+/** `@submit.once` compiles to a SEPARATE `onSubmitOnce` prop — Vue's own emit
+ *  reads both and guards the once-handler with a fired flag. Mirror that, or a
+ *  `.once` listener would silently never run. */
+let onceFired = false;
+
+/**
+ * Route a listener failure the way `emit` did.
+ *
+ * Vue wraps event handlers in `callWithAsyncErrorHandling`, which sends both
+ * sync throws and promise rejections to `app.config.errorHandler`. Calling the
+ * prop directly skips that, so a project with a global reporter (Sentry, a
+ * toast-on-error boundary) would stop seeing submit failures. Report through
+ * the same channel, then let the submit settle — a rejected save must still
+ * clear `isSubmitting`, or the button spins forever.
+ */
+const reportListenerError = (error: unknown) => {
+	const handler = instance?.appContext.config.errorHandler;
+	if (handler)
+		handler(error, instance?.proxy ?? null, 'component event handler');
+	else console.error(error);
+};
+
+const isThenable = (value: unknown): value is PromiseLike<unknown> =>
+	typeof (value as PromiseLike<unknown>)?.then === 'function';
+
+const runSubmitListeners = (formValues: Record<string, unknown>) => {
+	const props = instance?.vnode.props as Record<string, unknown> | undefined;
+	const collect = (value: unknown): SubmitListener[] =>
+		Array.isArray(value)
+			? (value as SubmitListener[])
+			: typeof value === 'function'
+				? [value as SubmitListener]
+				: [];
+
+	const listeners = collect(props?.onSubmit);
+	if (!onceFired) {
+		const once = collect(props?.onSubmitOnce);
+		if (once.length) {
+			onceFired = true;
+			listeners.push(...once);
+		}
+	}
+	if (!listeners.length) return undefined;
+
+	const pending: Array<PromiseLike<unknown>> = [];
+	for (const listener of listeners) {
+		try {
+			const result = listener(formValues);
+			if (isThenable(result)) {
+				pending.push(Promise.resolve(result).catch(reportListenerError));
+			}
+		} catch (error) {
+			reportListenerError(error);
+		}
+	}
+	// Await only what is actually awaitable, so a sync handler keeps the exact
+	// timing it has today rather than being pushed a microtask later.
+	return pending.length ? Promise.all(pending) : undefined;
+};
+
+const onSubmit = handleSubmit((formValues) => runSubmitListeners(formValues));
 
 /**
  * The rendered `<form>`, exposed as `$el` the way `BbButton` does it.