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

package/dist/utilities/misc/listboxMetrics.d.ts

@@ -30,12 +30,12 @@
  * needs no viewport clause of its own.)
  */
 /** Height of one option row, in px. */
-export declare const listboxOptionHeight: (touch: boolean, compact: boolean) => 24 | 44 | 28 | 36;
+export declare const listboxOptionHeight: (touch: boolean, compact: boolean) => 36 | 44 | 24 | 28;
 /** Height of a group heading row, in px (grouped box only). */
-export declare const listboxHeaderHeight: (touch: boolean, compact: boolean) => 32 | 24 | 36;
+export declare const listboxHeaderHeight: (touch: boolean, compact: boolean) => 32 | 36 | 24;
 /**
  * Option label size, as a CSS length. `undefined` means "leave the stylesheet's
  * own value alone" — the desktop size stays declared in CSS, next to the rest of
  * the option styling, and only the touch override travels through the var.
  */
-export declare const listboxOptionFontSize: (touch: boolean) => "1rem" | undefined;
+export declare const listboxOptionFontSize: (touch: boolean) => "16px" | undefined;

package/dist/utilities/misc/listboxMetrics.js

@@ -1,4 +1,4 @@
 //#region src/utilities/misc/listboxMetrics.ts
-var e = (e, t) => e ? t ? 36 : 44 : t ? 24 : 28, t = (e, t) => e ? t ? 32 : 36 : t ? 24 : 32, n = (e) => e ? "1rem" : void 0;
+var e = (e, t) => e ? t ? 36 : 44 : t ? 24 : 28, t = (e, t) => e ? t ? 32 : 36 : t ? 24 : 32, n = "16px", r = (e) => e ? n : void 0;
 //#endregion
-export { t as listboxHeaderHeight, n as listboxOptionFontSize, e as listboxOptionHeight };
+export { t as listboxHeaderHeight, r as listboxOptionFontSize, e as listboxOptionHeight };

package/dist/utilities/misc/ssrStateInjectionKey.d.ts

@@ -0,0 +1,42 @@
+import { InjectionKey } from 'vue';
+/**
+ * How the library moves a value it resolved during SSR across to the client.
+ *
+ * Deliberately two methods and no framework: the library cannot import from
+ * `#app`, `@inertiajs/*` or any other host, so the host provides the bucket and
+ * the library only reads and writes it. `bitboss-ui/nuxt`'s runtime plugin
+ * ships one backed by `nuxtApp.payload`; anything else (plain Vue SSR, Inertia
+ * SSR) can provide its own with the same two methods, or provide nothing —
+ * "nothing" is a supported, mismatch-free configuration, not a degraded one.
+ *
+ * Contract:
+ *   - `set` is called on the SERVER only, during `onServerPrefetch`, before the
+ *     component renders.
+ *   - `get` is called on the CLIENT only, during setup of the same component,
+ *     before its first (hydration) render.
+ *   - keys are opaque strings, unique per component instance.
+ *   - values must survive the host's payload serializer. Under Nuxt that is
+ *     devalue: plain objects, arrays, dates, maps, sets — not functions or
+ *     class instances. See `useItemsGetter`'s dev guard.
+ */
+export type SsrStateAdapter = {
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, value: T): void;
+};
+/**
+ * Provide an `SsrStateAdapter` under this key — at the app level
+ * (`app.provide(...)`), so every component reaches the same bucket.
+ *
+ * Same shape as `ICONS_INJECTION_KEY`, including the `Symbol.for`: under Nuxt
+ * the runtime plugin is loaded raw while the components come from Vite's
+ * pre-bundled copy, so the library is instantiated TWICE on the client and a
+ * plain `Symbol()` would be two different keys — the provide would land under
+ * one and every `inject` would miss under the other. That failure is quiet and
+ * looks exactly like "the host installed no adapter", which is a supported
+ * state, so nothing would have thrown; the ids simply drifted.
+ *
+ * No default value on purpose. Absent injection is meaningful (see
+ * `useSsrState`) — a no-op adapter would be indistinguishable from a real one,
+ * and the whole point is that the library must be able to tell.
+ */
+export declare const SSR_STATE_INJECTION_KEY: InjectionKey<SsrStateAdapter>;

package/dist/utilities/misc/ssrStateInjectionKey.js

@@ -0,0 +1,4 @@
+//#region src/utilities/misc/ssrStateInjectionKey.ts
+var e = Symbol.for("bitboss-ui:ssr-state");
+//#endregion
+export { e as SSR_STATE_INJECTION_KEY };

package/dist/validated/BbForm.vue_vue_type_script_setup_true_lang.js

@@ -1,42 +1,60 @@
 import { useBbFormContextHost as e } from "../composables/useBbFormContext.js";
-import { createElementBlock as t, defineComponent as n, mergeProps as r, openBlock as i, renderSlot as a, unref as o, useTemplateRef as s } from "vue";
-import { useForm as c } from "vee-validate";
+import { createElementBlock as t, defineComponent as n, getCurrentInstance as r, mergeProps as i, openBlock as a, renderSlot as o, unref as s, useTemplateRef as c } from "vue";
+import { useForm as l } from "vee-validate";
 //#region src/validated/BbForm.vue?vue&type=script&setup=true&lang.ts
-var l = /*@__PURE__*/ n({
+var u = /*@__PURE__*/ n({
 	__name: "BbForm",
 	props: { id: {} },
 	emits: ["submit"],
-	setup(n, { expose: l, emit: u }) {
-		let d = n, f = u, { handleSubmit: p, isSubmitting: m, submitCount: h, resetForm: g, meta: _, values: v, errors: y, validate: b } = c(), x = p((e) => f("submit", e)), S = s("formEl");
+	setup(n, { expose: u }) {
+		let d = n, { handleSubmit: f, isSubmitting: p, submitCount: m, resetForm: h, meta: g, values: _, errors: v, validate: y } = l(), b = r(), x = !1, S = (e) => {
+			let t = b?.appContext.config.errorHandler;
+			t ? t(e, b?.proxy ?? null, "component event handler") : console.error(e);
+		}, C = (e) => typeof e?.then == "function", w = (e) => {
+			let t = b?.vnode.props, n = (e) => Array.isArray(e) ? e : typeof e == "function" ? [e] : [], r = n(t?.onSubmit);
+			if (!x) {
+				let e = n(t?.onSubmitOnce);
+				e.length && (x = !0, r.push(...e));
+			}
+			if (!r.length) return;
+			let i = [];
+			for (let t of r) try {
+				let n = t(e);
+				C(n) && i.push(Promise.resolve(n).catch(S));
+			} catch (e) {
+				S(e);
+			}
+			return i.length ? Promise.all(i) : void 0;
+		}, T = f((e) => w(e)), E = c("formEl");
 		return e(() => d.id, {
 			state: () => ({
-				valid: _.value.valid,
-				dirty: _.value.dirty,
-				touched: _.value.touched,
-				pending: _.value.pending,
-				submitting: m.value,
-				submitCount: h.value,
-				values: { ...v },
-				errors: { ...y.value }
+				valid: g.value.valid,
+				dirty: g.value.dirty,
+				touched: g.value.touched,
+				pending: g.value.pending,
+				submitting: p.value,
+				submitCount: m.value,
+				values: { ..._ },
+				errors: { ...v.value }
 			}),
 			actions: {
-				submit: () => void x(),
-				reset: () => g(),
-				validate: async () => (await b()).valid
+				submit: () => void T(),
+				reset: () => h(),
+				validate: async () => (await y()).valid
 			}
-		}), l({ $el: S }), (e, n) => (i(), t("form", {
+		}), u({ $el: E }), (e, n) => (a(), t("form", {
 			ref_key: "formEl",
-			ref: S,
+			ref: E,
 			novalidate: "",
-			onSubmit: n[0] ||= (...e) => o(x) && o(x)(...e)
-		}, [a(e.$slots, "default", r({
-			isSubmitting: o(m),
-			resetForm: o(g),
-			submitCount: o(h),
-			validate: o(b),
-			values: o(v)
-		}, o(_)))], 544));
+			onSubmit: n[0] ||= (...e) => s(T) && s(T)(...e)
+		}, [o(e.$slots, "default", i({
+			isSubmitting: s(p),
+			resetForm: s(h),
+			submitCount: s(m),
+			validate: s(y),
+			values: s(_)
+		}, s(g)))], 544));
 	}
 });
 //#endregion
-export { l as default };
+export { u as default };

package/dist/validated/BbSelect.vue.d.ts

@@ -32,6 +32,8 @@ declare const __VLS_export: <T>(__VLS_props: NonNullable<Awaited<typeof __VLS_se
         option?: (props: any) => any;
     } & {
         group?: (props: any) => any;
+    } & {
+        chip?: (props: any) => any;
     };
     emit: ((evt: "update:modelValue", value: any) => void) & ((evt: "inactive") => void);
 }>) => import('vue').VNode & {

package/dist/validated/BbSelect.vue_vue_type_script_setup_true_lang.js

@@ -101,6 +101,7 @@ var h = /*@__PURE__*/ o({
 			"no-data": m((e) => [d(n.$slots, "no-data", l(s(e)))]),
 			option: m((e) => [d(n.$slots, "option", l(s(e)))]),
 			group: m((e) => [d(n.$slots, "group", l(s(e)))]),
+			chip: m((e) => [d(n.$slots, "chip", l(s(e)))]),
 			_: 3
 		}, 16, ["errors"]));
 	}

package/dist/validated/useValidatedField.js

@@ -1,49 +1,51 @@
-import { isEqual as e } from "../utilities/functions/isEqual.js";
-import { deburr as t } from "../utilities/functions/deburr.js";
-import { config as n } from "virtual:bitboss-ui/config";
+import { useConfig as e } from "../composables/useConfig.js";
+import { isEqual as t } from "../utilities/functions/isEqual.js";
+import { deburr as n } from "../utilities/functions/deburr.js";
 import { computed as r, onBeforeMount as i, watch as a } from "vue";
 import { useField as o } from "vee-validate";
 //#region src/validated/useValidatedField.ts
-var s = (e) => t(e).replace(/\s+/g, "").toLowerCase(), c = /* @__PURE__ */ new Set([
+var s = (e) => n(e).replace(/\s+/g, "").toLowerCase(), c = /* @__PURE__ */ new Set([
 	"vid",
 	"rules",
 	"validateOn",
 	"errors"
 ]), l = (e) => typeof e == "string" ? e.split("|").some((e) => e.trim().split(":")[0] === "required") : e && typeof e == "object" && !Array.isArray(e) ? !!e.required : !1;
-function u(t, u, d) {
-	let f = r(() => d.identifierFallback()), p = r(() => t.vid ? t.vid : f.value ? s(f.value) : void 0), m = () => t.validateOn ?? [];
+function u(n, u, d) {
+	let f = r(() => d.identifierFallback()), p = r(() => n.vid ? n.vid : f.value ? s(f.value) : void 0), m = () => n.validateOn ?? [];
 	i(() => {
 		if (!p.value) throw Error(`[bitboss-ui/validated] ${d.componentName}: give the field a "label"/"legend" (its name is derived from it) or an explicit "vid".`);
 	});
-	let h = r(() => t.rules), { value: g, errors: _, validate: v, setValue: y, handleChange: b, handleBlur: x } = o(r(() => p.value ?? ""), h, {
-		initialValue: t.modelValue,
+	let h = e(), g = r(() => n.rules), { value: _, errors: v, validate: y, setValue: b, handleChange: x, handleBlur: S } = o(r(() => p.value ?? ""), g, {
+		initialValue: n.modelValue,
 		validateOnValueUpdate: m().includes("update:modelValue"),
 		label: () => f.value
 	});
-	return a(() => t.modelValue, (t, n) => {
-		e(t, n) || (g.value = t);
-	}), {
-		value: g,
-		errors: _,
-		validate: v,
-		setValue: y,
-		handleChange: b,
-		handleBlur: x,
+	return a(() => n.modelValue, (e, n) => {
+		t(e, n) || (_.value = e);
+	}), a(_, (e) => {
+		t(e, n.modelValue) || u("update:modelValue", e);
+	}, { flush: "post" }), {
+		value: _,
+		errors: v,
+		validate: y,
+		setValue: b,
+		handleChange: x,
+		handleBlur: S,
 		computedErrors: r(() => {
-			let e = [..._.value];
-			return t.errors && e.push(...[].concat(t.errors)), e;
+			let e = [...v.value];
+			return n.errors && e.push(...[].concat(n.errors)), e;
 		}),
-		showAsterisk: r(() => n.requiredAsterisk && (!!t.required || l(t.rules))),
+		showAsterisk: r(() => h.requiredAsterisk && (!!n.required || l(n.rules))),
 		passthrough: r(() => {
 			let e = {};
-			for (let n in t) c.has(n) || (e[n] = t[n]);
+			for (let t in n) c.has(t) || (e[t] = n[t]);
 			return e;
 		}),
 		setModelValue: (e) => {
-			y(e, m().includes("update:modelValue") || _.value.length > 0), u("update:modelValue", e);
+			b(e, m().includes("update:modelValue") || v.value.length > 0), u("update:modelValue", e);
 		},
 		validateIfNeeded: (e) => {
-			m().includes(e) && v();
+			m().includes(e) && y();
 		}
 	};
 }

package/dist/vite.js

@@ -552,14 +552,18 @@ function tt(t) {
 	return {
 		name: "bitboss-ui:icon-registry",
 		config(e) {
-			let t = e.optimizeDeps?.include ?? [], n = e.optimizeDeps?.exclude ?? [], r = P(e.root ?? process.cwd()) ? [...L, He] : L, i = p.found.map(({ pack: e }) => `dayjs/locale/${e}`);
+			let t = e.optimizeDeps?.include ?? [], n = e.optimizeDeps?.exclude ?? [], r = P(e.root ?? process.cwd()) ? [...L, He] : L, i = p.found.map(({ pack: e }) => `dayjs/locale/${e}`), a = (e.build?.assetsDir ?? "assets").replace(/\/+$/, ""), o = e.build?.rollupOptions?.output, s = (Array.isArray(o) ? o[0] : o)?.chunkFileNames;
 			return {
 				optimizeDeps: {
 					include: [...r, ...i].filter((e) => !t.includes(e)),
 					exclude: R.filter((e) => !n.includes(e))
 				},
 				build: { rollupOptions: { output: { chunkFileNames(e) {
-					return e.facadeModuleId?.startsWith($) ? `assets/icons/${e.facadeModuleId.slice(17).replace("/", "_")}-[hash].js` : "assets/[name]-[hash].js";
+					if (e.facadeModuleId?.startsWith($)) {
+						let t = e.facadeModuleId.slice(17);
+						return `${a}/icons/${t.replace("/", "_")}-[hash].js`;
+					}
+					return typeof s == "function" ? s(e) : s ?? `${a}/[name]-[hash].js`;
 				} } } }
 			};
 		},

package/llms.txt

@@ -2,12 +2,12 @@
 
 > Vue 3 component library by BitBoss: forms, selects, layout, overlays, and more.
 
-Note: the `dist/` paths below resolve inside the installed npm package (`node_modules/bitboss-ui/`) and, when this file is fetched over HTTP, against https://cdn.jsdelivr.net/npm/bitboss-ui@beta. `dist/` is generated and not committed, so when browsing the repository the sources are `ai/` (guides, recipes, composables) and `src/components/<Name>/<Name>.guide.md` (per-component guides).
+Note: the `dist/` paths below resolve inside the installed npm package (`node_modules/bitboss-ui/`) and, when this file is fetched over HTTP, against https://llms-bitboss-ui.bitboss.it. `dist/` is generated and not committed, so when browsing the repository the sources are `ai/` (guides, recipes, composables) and `src/components/<Name>/<Name>.guide.md` (per-component guides).
 
 ## AI Knowledge Base
 
-- [Core knowledge base](https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/llms-medium.txt): **Fetch this if you can only fetch one file** — hard rules, setup, component picker, design language, and the full component catalogue in ~70 KB.
-- [Complete knowledge base](https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/llms-full.txt): Everything concatenated (~2 MB). Bulk ingestion only — too large to prompt with.
+- [Core knowledge base](https://llms-bitboss-ui.bitboss.it/dist/llms-medium.txt): **Fetch this if you can only fetch one file** — hard rules, setup, component picker, design language, and the full component catalogue in ~70 KB.
+- [Complete knowledge base](https://llms-bitboss-ui.bitboss.it/dist/llms-full.txt): Everything concatenated (~2 MB). Bulk ingestion only — too large to prompt with.
 - [AI Router](dist/ai/guides/ai-router.md): **Start here** — tiny hop map for any coding agent (which file to open next).
 - [Component index](dist/ai/index.md): Full component catalogue with agent rules, grouped by category. Each entry links a typed contract (props/events/slots/v-model).
 - [Component manifest](dist/ai/components.json): Machine-readable API surface of every component, for programmatic validation.
@@ -34,17 +34,17 @@ Note: the `dist/` paths below resolve inside the installed npm package (`node_mo
 - [Migration v2→v3: BbCheckbox / BbRadio / BbSwitch](dist/ai/guides/migration/components/bb-checkbox.md): reverse polarity inverted (explicit values flip, default layout unchanged), checked narrowed to boolean, color removed, BbRadio's name no longer required.
 - [Migration v2→v3: BbCheckboxGroup / BbRadioGroup / BbSwitchGroup](dist/ai/guides/migration/components/bb-checkbox-group.md): labelPosition renamed legendPosition, per-item disabled is now inert (use selectable), color and the option affix slots removed, BbRadioGroup's name no longer required, and the shared bb-cr-container CSS block split into one per group.
 - [Migration v2→v3: BbChip (removed)](dist/ai/guides/migration/components/bb-chip.md): BbChip is gone — BbBadge with clearable is the replacement; non-clearable chips were badges all along.
-- [Migration v2→v3: BbCollapsible](dist/ai/guides/migration/components/bb-collapsible.md): The tag prop is removed; the root is always a div.
+- [Migration v2→v3: BbCollapsible](dist/ai/guides/migration/components/bb-collapsible.md): The tag prop is removed; the root is always a span.
 - [Migration v2→v3: BbColorInput](dist/ai/guides/migration/components/bb-color-input.md): picker renamed to eyeDropper.
 - [Migration v2→v3: BbColorPalette](dist/ai/guides/migration/components/bb-color-palette.md): flip inverted to disableFlip, showArrow removed, picker renamed eyeDropper, update:open dropped, model updates never emit null.
 - [Migration v2→v3: BbDatePickerInput](dist/ai/guides/migration/components/bb-date-picker-input.md): allowWriting inverted to disableWriting and hidePopover renamed to disableCalendar, both with a changed token set; the width prop is removed; adaptive mobile sheet by default; non-floating output carries the local offset instead of UTC `Z` (new `utc` prop restores v2 output).
-- [Migration v2→v3: BbDialog](dist/ai/guides/migration/components/bb-dialog.md): showClose inverted to hideClose, several presentation props and the #close/#description slots removed, default widths changed, adaptive bottom sheet on mobile by default, --bb-dialog-* tokens replaced by --bb-panel-p plus locals.
+- [Migration v2→v3: BbDialog](dist/ai/guides/migration/components/bb-dialog.md): showClose inverted to hideClose, #close removed (description restored in beta.19), default widths changed, adaptive bottom sheet on mobile by default, --bb-dialog-* tokens replaced by --bb-panel-p plus locals.
 - [Migration v2→v3: BbDropdown](dist/ai/guides/migration/components/bb-dropdown.md): Items now expect text as the label and can carry variants/submenus; arrowPadding removed; adaptive mobile sheet on by default.
 - [Migration v2→v3: BbDropdownButton](dist/ai/guides/migration/components/bb-dropdown-button.md): autoLoading renamed to disableAutoLoading, disabledWhileLoading and theme removed.
 - [Migration v2→v3: BbDropzone](dist/ai/guides/migration/components/bb-dropzone.md): modelValue is typed, accept no longer throws and takes bare tokens, and the hidden native-submit input only renders when name is set.
 - [Migration v2→v3: BbIcon](dist/ai/guides/migration/components/bb-icon.md): The required prop is renamed type→icon, color is removed, and the xxl size key becomes 2xl.
 - [Migration v2→v3: BbIntersection](dist/ai/guides/migration/components/bb-intersection.md): Removed with no replacement — it wrapped IntersectionObserver and carried no styling; use @vueuse/core's useIntersectionObserver.
-- [Migration v2→v3: BbOffCanvas](dist/ai/guides/migration/components/bb-offcanvas.md): direction→side; showClose→hideClose; description and the #close/#description slots removed; size defaults change; adaptive drawer configs unify on offCanvasProps.
+- [Migration v2→v3: BbOffCanvas](dist/ai/guides/migration/components/bb-offcanvas.md): direction→side; showClose→hideClose; #close removed (description restored in beta.19); size defaults change; adaptive drawer configs unify on offCanvasProps.
 - [Migration v2→v3: BbPagination](dist/ai/guides/migration/components/bb-pagination.md): querykey renamed to queryKey; the loading prop is removed.
 - [Migration v2→v3: BbPopover](dist/ai/guides/migration/components/bb-popover.md): Built-in close button, restoreFocus, theme, and the arrow are gone; close affordances move into your content.
 - [Migration v2→v3: BbRating](dist/ai/guides/migration/components/bb-rating.md): color removed; name no longer required; the star state modifier renamed --highlighted to --filled/--empty; --bb-rating-size demoted to a local --size; input-position finally works.
@@ -53,7 +53,7 @@ Note: the `dist/` paths below resolve inside the installed npm package (`node_mo
 - [Migration v2→v3: BbSlider](dist/ai/guides/migration/components/bb-slider.md): thumbTranslate inverted to disableThumbTranslate; string model values and color removed.
 - [Migration v2→v3: BbSmoothHeight](dist/ai/guides/migration/components/bb-smooth-height.md): The `tag` prop is narrowed to `div | span`, and the inner measuring element now mirrors it instead of always being a `<div>`.
 - [Migration v2→v3: BbSpinner](dist/ai/guides/migration/components/bb-spinner.md): The color prop is removed; spinners follow currentColor.
-- [Migration v2→v3: BbTable](dist/ai/guides/migration/components/bb-table.md): allowSelectAll inverted to disableSelectAll; loading no longer blanks populated tables and now inerts rows; #loading is first-load-only; #no-data fills a full-width table cell instead of replacing the row; columns gained sortable + rowClass, which collide with same-named consumer fields.
+- [Migration v2→v3: BbTable](dist/ai/guides/migration/components/bb-table.md): The table renders as a CSS grid of divs with ARIA roles, not a <table> — every element selector (table/thead/tbody/tr/th/td) under .bb-table matches nothing, #thead/#tbody/#tfoot take role-complete div rows, --fill/--natural-width are gone, column widths drift within documented bounds, copy-to-spreadsheet and print header repetition degrade; allowSelectAll inverted to disableSelectAll; loading no longer blanks populated tables and now inerts rows; #loading is first-load-only; #no-data fills a full-width cell instead of replacing the row; row events drop the selected argument; columns gained sortable + rowClass, which collide with same-named consumer fields.
 - [Migration v2→v3: BbTabs (was BbTab)](dist/ai/guides/migration/components/bb-tabs.md): Component renamed; querykey→queryKey; animations default on; label slots renamed and all dynamic names/URL slugs normalized; the entire .bb-tab BEM tree renamed to .bb-tabs / .bb-tabs-list / .bb-tabs-panes.
 - [Migration v2→v3: BbTag](dist/ai/guides/migration/components/bb-tag.md): modelValue is strictly string[] now, multiple is removed, and duplicates are rejected case-insensitively by default.
 - [Migration v2→v3: BbTextInput](dist/ai/guides/migration/components/bb-text-input.md): The type prop narrows to the text-like input types — number/date values must move to their dedicated components; a bare `floating` attribute was never a prop, the spelling is label-mode="floating".
@@ -63,6 +63,7 @@ Note: the `dist/` paths below resolve inside the installed npm package (`node_mo
 - [Migration v2→v3: confirm() / useConfirm](dist/ai/guides/migration/components/use-confirm.md): yesText/onYes/noText/onNo collapse into yes/no configs, actions becomes an array-or-false, theme→variant, timeout→duration, autoClose flips to default-true, labels are localized, footer buttons default md.
 - [Migration v2→v3: useBroadcastChannelInstance](dist/ai/guides/migration/components/use-broadcast-channel-instance.md): Removed — cross-tab messaging is not a UI concern; use useBroadcastChannel from @vueuse/core.
 - [Page Shell](dist/ai/guides/page-shell.md): App-side page layout — topbar, content, and a right details sidebar driven by a stack-based context (push a record to peek it, pop to go back). The implementation ships in the per-platform Layout Scaffold recipe; this guide covers when and how to use it.
+- [ssr-prefill](dist/ai/guides/ssr-prefill.md): Guide for ssr-prefill usage and decision-making context.
 - [Validated Forms (vee-validate)](dist/ai/guides/validated-forms.md): The `bitboss-ui/validated` entrypoint — form controls pre-wired to vee-validate. Global rules give an effort-free `rules="required|email"` string syntax; BbForm hosts the form; requiredAsterisk marks required fields.
 
 ## Recipes (Page-Level Assemblies)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "bitboss-ui",
-	"version": "3.0.0-beta.2",
+	"version": "3.0.0-beta.20",
 	"description": "Vue 3 component library by BitBoss: forms, selects, layout, overlays, and more.",
 	"license": "MIT",
 	"type": "module",
@@ -11,7 +11,7 @@
 	"publishConfig": {
 		"tag": "alpha"
 	},
-	"homepage": "https://ui-components-docs.vercel.app/",
+	"homepage": "https://ui-components.bitboss.it/",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/bitboss-hub/bitboss-ui.git"

package/scripts/lib/eslint-plugin.d.ts

@@ -27,7 +27,24 @@ export type BitbossUiRuleName =
 	| 'require-partner-prop'
 	| 'no-unknown-slots'
 	| 'no-active-class-on-root-link'
-	| 'no-navigation-attr-fallthrough';
+	| 'no-navigation-attr-fallthrough'
+	| 'no-reverse-false';
+
+/** Options accepted by `bitboss-ui/no-reverse-false`. */
+export interface NoReverseFalseOptions {
+	/** Component names to skip entirely. */
+	allowComponents?: string[];
+	/**
+	 * Promote the v2-intent rewrite (`:reverse="false"` → `reverse`) from an
+	 * editor suggestion to a real `--fix`, for a bulk v2→v3 sweep.
+	 *
+	 * Off by default, and deliberately so: the two readings of
+	 * `:reverse="false"` produce OPPOSITE layouts, so an unrequested fix would
+	 * silently flip every row in a v3-native codebase that wrote the redundant
+	 * prop. Turn it on only for files you know came from v2.
+	 */
+	assumeV2?: boolean;
+}
 
 /** Options accepted by `bitboss-ui/no-unknown-attributes`. */
 export interface NoUnknownAttributesOptions {
@@ -54,6 +71,7 @@ export const requirePartnerProp: Rule.RuleModule;
 export const noUnknownSlots: Rule.RuleModule;
 export const noActiveClassOnRootLink: Rule.RuleModule;
 export const noNavigationAttrFallthrough: Rule.RuleModule;
+export const noReverseFalse: Rule.RuleModule;
 
 /**
  * Resolves the optional `@typescript-eslint/parser` peer, or `null` when it is

package/scripts/lib/eslint-plugin.mjs

@@ -924,6 +924,149 @@ const noNavigationAttrFallthrough = {
 	},
 };
 
+/*
+ * The three v3 controls whose `reverse` prop kept its NAME but inverted its
+ * MEANING between v2 and v3. Hardcoded on purpose: this is a fact about one
+ * historical migration, not a property the manifest can express — the manifest
+ * records that `reverse` exists and defaults to `false`, which is true in both
+ * versions and says nothing about which layout that produces.
+ *
+ * Verified against both branches rather than assumed:
+ *   v2 `BbSwitch.vue` withDefaults `reverse: true`, passed RAW to the base
+ *   container. v3 defaults the public prop `false` and passes `!props.reverse`
+ *   down. Both defaults therefore reach the base as `true` — the default
+ *   layout never moved — but every EXPLICIT value flips.
+ */
+const INVERTED_REVERSE_COMPONENTS = new Set([
+	'BbCheckbox',
+	'BbRadio',
+	'BbSwitch',
+]);
+
+/** @type {import('eslint').Rule.RuleModule} */
+const noReverseFalse = {
+	meta: {
+		type: 'problem',
+		hasSuggestions: true,
+		fixable: 'code',
+		docs: {
+			description:
+				'Flag `:reverse="false"` on BbCheckbox/BbRadio/BbSwitch — the v2 spelling for a right-hand control. `reverse` kept its name and inverted its meaning in v3, so the v2 spelling is now a no-op that renders the OPPOSITE layout, and nothing else catches it: it is valid TypeScript, a declared prop, and its own default.',
+			recommended: true,
+		},
+		schema: [
+			{
+				type: 'object',
+				properties: {
+					manifestPath: { type: 'string' },
+					failClosed: { type: 'boolean' },
+					allowComponents: { type: 'array', items: { type: 'string' } },
+					// Opt-in for a bulk v2→v3 sweep: turn the "control on the right"
+					// rewrite into a real `--fix`. Off by default because the two
+					// readings produce OPPOSITE layouts, and a v3-native codebase
+					// that wrote the redundant `:reverse="false"` would silently have
+					// its rows flipped by a fix it never asked for.
+					assumeV2: { type: 'boolean' },
+				},
+				additionalProperties: false,
+			},
+		],
+		messages: {
+			reverseFalse:
+				'`:reverse="false"` on {{component}} is the v2 spelling for a right-hand control, and in v3 it is a no-op that renders the control on the LEFT. v3 inverted the prop\'s meaning while keeping its name: pass bare `reverse` for the v2 layout, or delete the prop (it is already the default). See ai/guides/migration/components/bb-checkbox.md.',
+			reverseStringFalse:
+				'`reverse="false"` on {{component}} is a STRING, which is truthy — so it does the opposite of what it reads like and behaves as `reverse`. Write bare `reverse` if that is what you want, or delete the prop.',
+		},
+	},
+
+	create(context) {
+		const options = context.options[0] ?? {};
+		const manifest = getManifest(options.manifestPath, options);
+		const sourceCode = context.sourceCode ?? context.getSourceCode();
+		const services = sourceCode.parserServices;
+		if (!manifest || !services?.defineTemplateBodyVisitor) return {};
+
+		const allowComps = new Set(options.allowComponents ?? []);
+
+		return services.defineTemplateBodyVisitor({
+			VElement(node) {
+				const name = toPascalTag(node.rawName);
+				if (!INVERTED_REVERSE_COMPONENTS.has(name) || allowComps.has(name)) {
+					return;
+				}
+				// Stay honest against the installed manifest: if this build of the
+				// library no longer declares `reverse` on the component, the rule has
+				// nothing to say and `no-unknown-attributes` owns the diagnostic.
+				const surface = manifest.get(name);
+				if (!surface) return;
+				const checker = createComponentChecker(surface);
+				if (!checker.isKnownProp('reverse')) return;
+
+				for (const attr of node.startTag.attributes) {
+					// `reverse="false"` — a plain attribute, so the value is the STRING
+					// "false", which Vue leaves truthy. Reads as off, behaves as on.
+					if (!attr.directive) {
+						const attrName = attr.key.rawName ?? attr.key.name;
+						if (toCamel(attrName) !== 'reverse') continue;
+						if (attr.value?.value !== 'false') continue;
+						context.report({
+							node: attr,
+							messageId: 'reverseStringFalse',
+							data: { component: name },
+							suggest: [
+								{
+									desc: 'Use bare `reverse` (same result, says what it does)',
+									fix: (fixer) => fixer.replaceText(attr, 'reverse'),
+								},
+								{
+									desc: 'Remove it (control on the left, the v3 default)',
+									fix: (fixer) => fixer.remove(attr),
+								},
+							],
+						});
+						continue;
+					}
+
+					if (attr.key.name.name !== 'bind') continue;
+					const arg = attr.key.argument;
+					// `v-bind="obj"` and `:[expr]` are unbounded — nothing to assert.
+					if (!arg || arg.type !== 'VIdentifier') continue;
+					if (toCamel(arg.rawName ?? arg.name) !== 'reverse') continue;
+					const expr =
+						attr.value?.type === 'VExpressionContainer'
+							? attr.value.expression
+							: null;
+					// ONLY a literal `false`. A dynamic `:reverse="isRtl"` that happens
+					// to evaluate false is legitimate v3 code, and the template AST is
+					// the one place that distinction survives — which is exactly why
+					// this is a lint rule and not a runtime warning.
+					if (!expr || expr.type !== 'Literal' || expr.value !== false) {
+						continue;
+					}
+
+					const toBare = (fixer) => fixer.replaceText(attr, 'reverse');
+					context.report({
+						node: attr,
+						messageId: 'reverseFalse',
+						data: { component: name },
+						...(options.assumeV2 ? { fix: toBare } : {}),
+						suggest: [
+							{
+								desc: 'Control on the right (what this meant in v2): `reverse`',
+								fix: toBare,
+							},
+							{
+								desc: 'Control on the left: remove the prop (it is the default)',
+								fix: (fixer) => fixer.remove(attr),
+							},
+						],
+					});
+				}
+			},
+		});
+	},
+};
+
 const plugin = {
 	meta: { name: 'bitboss-ui', version: '1.0.0' },
 	rules: {
@@ -933,6 +1076,7 @@ const plugin = {
 		'no-unknown-slots': noUnknownSlots,
 		'no-active-class-on-root-link': noActiveClassOnRootLink,
 		'no-navigation-attr-fallthrough': noNavigationAttrFallthrough,
+		'no-reverse-false': noReverseFalse,
 	},
 };
 
@@ -991,6 +1135,7 @@ plugin.configs = {
 				'bitboss-ui/no-unknown-slots': 'error',
 				'bitboss-ui/no-active-class-on-root-link': 'error',
 				'bitboss-ui/no-navigation-attr-fallthrough': 'error',
+				'bitboss-ui/no-reverse-false': 'error',
 			},
 		},
 	],
@@ -1004,5 +1149,6 @@ export {
 	noUnknownSlots,
 	noActiveClassOnRootLink,
 	noNavigationAttrFallthrough,
+	noReverseFalse,
 	resolveOptionalTsParser,
 };