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

package/llms.txt

@@ -7,7 +7,7 @@ Note: the `dist/` paths below resolve inside the installed npm package (`node_mo
 ## AI Knowledge Base
 
 - [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 ~250 KB.
-- [Complete knowledge base](https://llms-bitboss-ui.bitboss.it/dist/llms-full.txt): Everything concatenated (~6.1 MB). Bulk ingestion only — too large to prompt with.
+- [Complete knowledge base](https://llms-bitboss-ui.bitboss.it/dist/llms-full.txt): Everything concatenated (~6.3 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 API files](dist/ai/manifest/index.json): Machine-readable API, one JSON file per component (`manifest/components/<Name>.json`: every prop, event, slot, v-model and pt part, one per line, plus the public types it uses; a row marked `common: true` is whole in `manifest/common.json`) — open the index, then the one component. The same data in one ~1.2 MB file for tools is [components.json](dist/ai/components.json); its `types` array lists the public TYPE exports with a `usage` tier (`api` = the ones you reach for) and, on the `api` ones, a `usedBy` array naming the component and prop or event each is the type OF — `BbTableColumn` is `usedBy` `BbTable.columns`, a value you pass, not a tag you write. This file is props and events, not paint.
@@ -22,6 +22,7 @@ Note: the `dist/` paths below resolve inside the installed npm package (`node_mo
 - [Options and Items Playbook](dist/ai/guides/options-items-playbook.md): How item-driven components turn raw domain items into options — mapping, value identity, model seeding, and the supported ways to disable choices.
 - [Inline Edit Playbook](dist/ai/guides/inline-edit-playbook.md): Who owns the edit? Choosing between draft-map, autosave, and write-back persistence for inline-editing tables — commit rules per control kind, optimistic overlays with rollback, and the dirty-ring / chevron-to-spinner feedback grammar.
 - [Icons Policy](dist/ai/guides/icons-policy.md): Provider-first icon usage (`lucide:*` via `@iconify-json/*` packages), `local:*` for brand art, how the plugin resolves names, and a catalog of every surface that accepts an icon.
+- [Adoption checklist — finish a migration on the library](dist/ai/guides/migration/adoption-checklist.md): The walk every migration ends with, from bitboss-ui v2 or any other library — each hand-rolled pattern the library ships (radio cards, segmented controls, tabs, sortable headers, nested tables, steppers, notice boxes, app sheets, app dialogs and confirms), how to find it (an rg command, or `npx bitboss-ui check --idioms`), and the replacement in its shortest syntax; then the adaptive phase and the production rebuild.
 - [App Layout](dist/ai/guides/app-layout.md): App-side chrome around every page — collapsible left nav sidebar and a fat footer, owning the page's one <main> landmark and the CSS hooks (.layout--sidebar-expanded, --sidebar-max-w) that size the nav.
 - [Design Language](dist/ai/guides/design-language.md): Token vocabulary, variants, sizing, dark mode, and how to style around the components when building on-system UIs.
 - [Design Tokens](dist/ai/guides/design-tokens.md): The token architecture of bitboss-ui — tiers, naming rules, the emphasis ladder, and the theming contract.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "bitboss-ui",
-	"version": "3.0.0-beta.63",
+	"version": "3.0.0-beta.65",
 	"description": "Vue 3 component library by BitBoss: forms, selects, layout, overlays, and more.",
 	"license": "MIT",
 	"type": "module",
@@ -92,7 +92,7 @@
 		"prepack": "npm run build && npm run check:pack && npm pkg delete scripts.prepare",
 		"preview": "vite preview",
 		"storybook": "storybook dev -p 6006",
-		"test": "node scripts/ensure-manifest.mjs && vitest run && node scripts/check-guide-types.mjs && npm run check:test-types && node scripts/check-fixture-types.mjs && node scripts/check-recipes.mjs && node scripts/check-examples.mjs && node scripts/recipes.mjs --check && node scripts/check-doc-drift.mjs && node scripts/check-doc-ts.mjs && node scripts/run-ai-evals.mjs && node scripts/check-mcp.mjs && node scripts/check-search-coverage.mjs && node scripts/check-tokens.mjs && node scripts/check-pins.mjs && node scripts/check-deprecation-register.mjs && node scripts/check-inertia-link-props.mjs && node --experimental-strip-types scripts/check-api-consistency.ts --strict && node --experimental-strip-types scripts/check-default-docs.ts && node --experimental-strip-types scripts/generate-component-docs.ts --strict && node scripts/check-doc-links.mjs && node scripts/generate-css-migration.mjs --check",
+		"test": "node scripts/ensure-manifest.mjs && vitest run && node scripts/check-guide-types.mjs && npm run check:test-types && node scripts/check-fixture-types.mjs && node scripts/check-recipes.mjs && node scripts/check-examples.mjs && node scripts/recipes.mjs --check && node scripts/check-doc-drift.mjs && node scripts/check-doc-ts.mjs && node scripts/run-ai-evals.mjs && node scripts/check-mcp.mjs && node scripts/check-search-coverage.mjs && node scripts/check-tokens.mjs && node scripts/check-pins.mjs && node scripts/check-deprecation-register.mjs && node scripts/check-inertia-link-props.mjs && node --experimental-strip-types scripts/check-api-consistency.ts --strict && node --experimental-strip-types scripts/check-default-docs.ts && node --experimental-strip-types scripts/generate-component-docs.ts --strict && node scripts/check-doc-links.mjs && node scripts/generate-css-migration.mjs --check && node scripts/generate-adoption-checklist.mjs --check",
 		"test:fixtures": "npm run build && node scripts/check-nuxt-types.mjs && node scripts/run-ssr-fixture.mjs && node scripts/invalidate-fixture-caches.mjs && FIXTURE_TARGET=dist node scripts/run-e2es.mjs fixtures/inertia/e2e && FIXTURE_TARGET=dist node scripts/run-e2es.mjs fixtures/vue/e2e && npm run test:nuxt && npm run test:nuxt:prod && node scripts/test-add.mjs",
 		"test:fixtures:src": "npm run test:inertia && npm run test:vue && npm run test:nuxt",
 		"test:inertia": "node scripts/invalidate-fixture-caches.mjs && node scripts/run-e2es.mjs fixtures/inertia/e2e",
@@ -106,7 +106,7 @@
 		"test:engines": "node scripts/ensure-manifest.mjs && node scripts/run-engines.mjs",
 		"test:ci:node": "node scripts/ensure-manifest.mjs && vitest run --project node --project types --project ssr",
 		"test:ci:browser": "node scripts/ensure-manifest.mjs && node scripts/run-browser-chunked.mjs 12",
-		"test:ci:gates": "node scripts/check-guide-types.mjs && npm run check:test-types && node scripts/check-fixture-types.mjs && node scripts/check-recipes.mjs && node scripts/check-examples.mjs && node scripts/recipes.mjs --check && node scripts/check-doc-drift.mjs && node scripts/check-doc-ts.mjs && node scripts/run-ai-evals.mjs && node scripts/check-pins.mjs && node scripts/check-deprecation-register.mjs && node scripts/check-inertia-link-props.mjs && node --experimental-strip-types scripts/check-default-docs.ts && node scripts/check-doc-links.mjs && node scripts/generate-css-migration.mjs --check && npm run check:helpers-lint",
+		"test:ci:gates": "node scripts/check-guide-types.mjs && npm run check:test-types && node scripts/check-fixture-types.mjs && node scripts/check-recipes.mjs && node scripts/check-examples.mjs && node scripts/recipes.mjs --check && node scripts/check-doc-drift.mjs && node scripts/check-doc-ts.mjs && node scripts/run-ai-evals.mjs && node scripts/check-pins.mjs && node scripts/check-deprecation-register.mjs && node scripts/check-inertia-link-props.mjs && node --experimental-strip-types scripts/check-default-docs.ts && node scripts/check-doc-links.mjs && node scripts/generate-css-migration.mjs --check && node scripts/generate-adoption-checklist.mjs --check && npm run check:helpers-lint",
 		"test:ci": "npm run test:ci:node && npm run test:ci:browser && npm run test:ci:gates",
 		"postpack": "npm pkg set \"scripts.prepare=node scripts/hooks-install.mjs\"",
 		"test:ssr": "npm run build && node scripts/run-ssr-fixture.mjs",
@@ -129,7 +129,7 @@
 	},
 	"peerDependencies": {
 		"@iconify/collections": ">=1.0.0",
-		"@inertiajs/vue3": ">=1.0.0",
+		"@inertiajs/vue3": ">=2.0.0",
 		"@modelcontextprotocol/sdk": ">=1.29.0",
 		"@nuxt/kit": ">=4.0.0",
 		"vee-validate": ">=4.10.0 <5",
@@ -196,6 +196,7 @@
 		"gray-matter": "^4.0.3",
 		"heroicons": "^2.2.0",
 		"husky": "^9.1.7",
+		"inertia2-vue3": "npm:@inertiajs/vue3@^2.3.10",
 		"joi": "^18.2.9",
 		"lightningcss": "^1.32.0",
 		"lint-staged": "^17.0.4",

package/scripts/lib/adoption-checklist.json

@@ -0,0 +1,312 @@
+{
+	"$comment": "The adoption checklist (Q76.0): ONE source for the guide (ai/guides/migration/adoption-checklist.md, the block between the adoption-rows markers, written by scripts/generate-adoption-checklist.mjs) and for `bitboss-ui check --idioms` (scripts/lib/idiom-scan.mjs). Each probe is a regex run per line, in both JavaScript and ripgrep syntax (no lookarounds; `.` stands for a quote so the shell command needs none). `inFile` must also match somewhere in the file, `notInFile` must not, and `notInLine` must not match the hit's own line. `ext` lists the file extensions the row reads.",
+	"rows": [
+		{
+			"id": "radio-group",
+			"pattern": "A hand-built single choice: radio cards, a pill row, anything carrying `role=\"radiogroup\"` / `role=\"radio\"`, or raw `<input type=\"radio\">`",
+			"ext": ["vue"],
+			"probes": [
+				{
+					"find": "role=.radio(group)?[^a-z]|type=.radio."
+				}
+			],
+			"use": "BbRadioGroup",
+			"example": "<BbRadioGroup v-model=\"plan\" legend=\"Plan\" :items=\"plans\" />",
+			"note": "Cards: `list-layout=\"vertical-stretch\" item-layout=\"label-fill\"`. A segmented strip: `variant=\"pill\"` (or `\"line\"`), BbTabs' look. Other pill looks: `pt:` on `item` / `label`, with `pt:icon=\"hidden\"`. One look across the app = one `definePreset`."
+		},
+		{
+			"id": "checkbox",
+			"pattern": "A hand-built checkbox or check square: `role=\"checkbox\"` on your own markup, or a raw `<input type=\"checkbox\">`",
+			"ext": ["vue"],
+			"probes": [
+				{
+					"find": "role=.checkbox.|type=.checkbox."
+				}
+			],
+			"use": "BbCheckbox / BbCheckboxGroup",
+			"example": "<BbCheckboxGroup v-model=\"ids\" legend=\"Columns\" :items=\"columns\" />",
+			"note": "A row of single checkboxes is a group. Selectable table rows are `BbTable selectable`."
+		},
+		{
+			"id": "tabs",
+			"pattern": "Hand-built tabs: `role=\"tablist\"` / `role=\"tab\"` on your own markup",
+			"ext": ["vue"],
+			"probes": [
+				{
+					"find": "role=.tab(list)?[^a-z]"
+				}
+			],
+			"use": "BbTabs",
+			"example": "<BbTabs v-model=\"view\" :items=\"views\" />",
+			"note": "`pill` is the default look; `line` for page sections; `navigation` puts the tab in the URL."
+		},
+		{
+			"id": "toggle-group",
+			"pattern": "A segmented control or tag group: a `v-for` of buttons that carry `aria-pressed`, or an app component named like one (`SegmentedControl`, `TagGroup`, `ChipGroup`, `ToggleGroup`, `RadioCards`)",
+			"ext": ["vue"],
+			"probes": [
+				{
+					"find": "aria-pressed",
+					"inFile": "v-for"
+				},
+				{
+					"find": "<(Segmented[A-Za-z]*|Tags?Group|ChipGroup|ToggleGroup|RadioCards?[A-Za-z]*)[\\s/>]"
+				}
+			],
+			"use": "BbTabs (switch views) / BbRadioGroup (pick a value) / BbCheckboxGroup (pick several)",
+			"example": "<BbTabs v-model=\"view\" :items=\"views\" />",
+			"note": "Decide by the job, not the look: switching what the page shows is BbTabs (`pill`); choosing a value a form or a filter submits is BbRadioGroup `variant=\"pill\"` (several values: BbCheckboxGroup `variant=\"pill\"`). See \"Switch views or pick a value\" above. On/off toggles that are not one choice are `BbButton` with `v-model` (it owns `aria-pressed`; `group` fuses them)."
+		},
+		{
+			"id": "sort-header",
+			"pattern": "Hand-built sortable headers: your own `aria-sort`, sort arrows and click handlers on `<th>`",
+			"ext": ["vue"],
+			"probes": [
+				{
+					"find": "aria-sort"
+				}
+			],
+			"use": "BbTable `sortable` columns + `v-model:sort`",
+			"example": "<BbTable v-model:sort=\"sort\" :columns=\"[{ key: 'name', label: 'Name', sortable: true }]\" :items=\"rows\" />",
+			"note": "`v-model:sort` is an ordered array of `[key, dir]`; a server that sorts by one column keeps the last entry."
+		},
+		{
+			"id": "table",
+			"pattern": "A raw `<table>`, including a hand-made nested or expanding one (child rows, a chevron in the first cell)",
+			"ext": ["vue"],
+			"probes": [
+				{
+					"find": "<table[\\s>]"
+				}
+			],
+			"use": "BbTable (nested: `#expand` + a nested `BbTable inherit-column-widths`)",
+			"example": "<BbTable :columns=\"columns\" :items=\"rows\" />",
+			"note": "Rows that open: `v-model:expanded-items` and the `#expand` slot. An email or print template that needs a raw table stays one."
+		},
+		{
+			"id": "option-check",
+			"pattern": "A custom check glyph in select options: a check icon or check square in `#option`, or a class that hides the library's own check (`[&>svg]:hidden`)",
+			"ext": ["vue", "ts"],
+			"probes": [
+				{
+					"find": "\\[&>svg\\]:hidden"
+				},
+				{
+					"find": "<CheckSquare[\\s/>]"
+				},
+				{
+					"find": "icon=.[a-z-]*:?(square-)?check",
+					"inFile": "#option"
+				}
+			],
+			"use": "BbSelect / BbSelectPopover / BbDropdown (the selected row draws its own check)",
+			"example": "<BbSelect v-model=\"ids\" label=\"Owners\" :items=\"users\" multiple />",
+			"note": "Keep `#option` for the row's content; the selection mark is the component's."
+		},
+		{
+			"id": "stepper",
+			"pattern": "A hand-built stepper: minus / plus buttons around a number, with your own increment and decrement code",
+			"ext": ["vue"],
+			"probes": [
+				{
+					"find": "(increment|decrement|stepUp|stepDown)\\s*\\(",
+					"inFile": "<button",
+					"notInFile": "<BbNumberInput"
+				}
+			],
+			"use": "BbNumberInput (its slots get `{ increase, decrease }`)",
+			"example": "<BbNumberInput v-model=\"qty\" label=\"Quantity\" :min=\"0\"><template #append=\"{ increase }\"><BbButton icon=\"lucide:plus\" variant=\"ghost\" @click=\"increase\">More</BbButton></template></BbNumberInput>",
+			"note": "Arrow keys, clamping to `min` / `max`, `step` and locale formatting come with the field."
+		},
+		{
+			"id": "notice",
+			"pattern": "A hand-built notice box: a styled `<div role=\"status\">` / `role=\"alert\"`",
+			"ext": ["vue"],
+			"probes": [
+				{
+					"find": "<(div|p|section|aside)\\b[^>]*role=.(status|alert)."
+				}
+			],
+			"use": "BbAlert",
+			"example": "<BbAlert title=\"Saved as a draft\" />",
+			"note": "`variant=\"destructive\"` for errors (it announces as an alert). An empty-state box (\"nothing here yet\") has no component: keep it, built on tokens."
+		},
+		{
+			"id": "clickable-card",
+			"pattern": "A whole card or tile wrapped in a link (`<a>`, `<Link>`, `<RouterLink>` carrying the card's border and padding)",
+			"ext": ["vue"],
+			"probes": [
+				{
+					"find": "<(a|Link|RouterLink|router-link)\\b[^>]*class=.[^\"]*\\b(rounded|border|shadow)[^\"]*\\bp-[0-9]"
+				}
+			],
+			"use": "BbBaseButton as an overlay link (BbBaseButton § A clickable card)",
+			"example": "<div class=\"relative rounded-(--bb-radius) border p-4\">…<BbBaseButton class=\"absolute inset-0\" :href=\"url\"><span class=\"sr-only\">Open report</span></BbBaseButton></div>",
+			"note": "There is no card or KPI-tile component: keep the box, adopt the link (navigation, prefetch, one focus ring, selectable text)."
+		},
+		{
+			"id": "app-sheet",
+			"pattern": "An app-made sheet or mobile overlay: a `useBottomSheet` / `BottomSheet` / `ActionSheet` of your own, a `BbOffCanvas` mounted with `v-if` instead of `v-model`, or a side switched by hand on `isMobile`",
+			"ext": ["vue", "ts", "js"],
+			"probes": [
+				{
+					"find": "use(Bottom|Action)Sheet\\b|<(Bottom|Action)Sheet[\\s/>]"
+				},
+				{
+					"find": "<BbOffCanvas\\b[^>]*\\bv-if="
+				},
+				{
+					"find": ":side=.[A-Za-z.]*[Mm]obile\\b"
+				}
+			],
+			"use": "Adaptive overlays (BbDialog, BbDropdown, BbSelect, BbPopover open as sheets on a phone) / BbOffCanvas with a per-breakpoint `side`",
+			"example": "<BbOffCanvas v-model=\"open\" :side=\"{ default: 'bottom', md: 'right' }\" draggable title=\"Filters\" />",
+			"note": "Delete the app's sheet, its drag code and its `isMobile` branches: `draggable` gives drag-to-dismiss and the handle, and the panel lifts above the keyboard by itself."
+		},
+		{
+			"id": "app-dialog",
+			"pattern": "App-made dialogs and confirms: a raw `<dialog>`, `role=\"dialog\"` on your own markup, `window.confirm()`, or an app `ConfirmDialog` / `ConfirmModal`",
+			"ext": ["vue", "ts", "js"],
+			"probes": [
+				{
+					"find": "<dialog[\\s>]|role=.(alert)?dialog."
+				},
+				{
+					"find": "window\\.confirm\\("
+				},
+				{
+					"find": "<Confirm(Dialog|Modal)[\\s/>]"
+				}
+			],
+			"use": "BbDialog (`v-bb-dialog`) / `confirm()`",
+			"example": "const ok = await confirm({ title: 'Delete invoice?', variant: 'destructive' });",
+			"note": "Open a dialog by id from its trigger: `<BbButton v-bb-dialog=\"'edit-user'\">Edit</BbButton>` + `<BbDialog id=\"edit-user\" title=\"Edit user\">`; `confirm()` comes from `useConfirm()`."
+		},
+		{
+			"id": "destructive-confirm",
+			"pattern": "A delete confirm without the destructive look: a `confirm()` in a file that deletes or removes, with no `variant: 'destructive'`",
+			"ext": ["vue", "ts", "js"],
+			"probes": [
+				{
+					"find": "confirm\\(\\{",
+					"inFile": "[Dd]elete|[Rr]emove|[Ee]limina|[Cc]ancella",
+					"notInFile": "variant:\\s*.destructive."
+				}
+			],
+			"use": "`confirm({ variant: 'destructive' })`",
+			"example": "const ok = await confirm({ title: 'Delete invoice?', variant: 'destructive' });",
+			"note": "The Yes button takes the variant too. A row menu's delete item takes `variant: 'destructive'` on the item."
+		},
+		{
+			"id": "media-query",
+			"pattern": "Your own mobile check: a `useIsMobile`, `window.matchMedia(…)` or an `innerWidth` comparison deciding layout",
+			"ext": ["vue", "ts", "js"],
+			"probes": [
+				{
+					"find": "\\buseIsMobile\\b|window\\.matchMedia\\(|innerWidth\\s*[<>]"
+				}
+			],
+			"use": "`useMobile()` from bitboss-ui",
+			"example": "const { isMobile } = useMobile();",
+			"note": "It is the same breakpoint the adaptive overlays switch at (`mobileMaxWidth`), so the app and the library never disagree."
+		},
+		{
+			"id": "pagination",
+			"pattern": "A hand-built pager: page-number buttons, an app `Pagination` / `Pager` component, a `nav` labelled \"pagination\"",
+			"ext": ["vue"],
+			"probes": [
+				{
+					"find": "aria-label=.[Pp]agina(tion|zione)."
+				},
+				{
+					"find": "<(Pagination|Pager|XPagination)[\\s/>]"
+				}
+			],
+			"use": "BbPagination",
+			"example": "<BbPagination v-model=\"page\" :total-pages=\"pages\" />",
+			"note": "`navigation` builds a link per page; inside a BbTable the table's pager reads the table."
+		},
+		{
+			"id": "disclosure",
+			"pattern": "A hand-built disclosure or collapsible card: a raw `<details>` / `<summary>`",
+			"ext": ["vue"],
+			"probes": [
+				{
+					"find": "<details[\\s>]"
+				}
+			],
+			"use": "BbAccordion (BbCollapsible when you bring the trigger)",
+			"example": "<BbAccordion v-model=\"open\" title=\"Can I change plans?\" />",
+			"note": "`heading-level` sets the header's heading; the chevron and the ARIA come with it."
+		},
+		{
+			"id": "form-control",
+			"pattern": "Raw form controls: `<input>` (text, number, date, time), `<textarea>`, `<select>`",
+			"ext": ["vue"],
+			"probes": [
+				{
+					"find": "<(textarea|select)[\\s>]"
+				},
+				{
+					"find": "<input\\b",
+					"notInLine": "type=.(hidden|radio|checkbox|file)."
+				}
+			],
+			"use": "BbTextInput / BbNumberInput / BbDatePickerInput / BbTimePickerInput / BbTextarea / BbSelect",
+			"example": "<BbTextInput v-model=\"name\" label=\"Name\" />",
+			"note": "The field brings the label, the hint, errors, `required` and the BbForm wiring."
+		},
+		{
+			"id": "raw-button",
+			"pattern": "A raw `<button>`: an icon button, a remove ✕, an add-row button, a pill you click",
+			"ext": ["vue"],
+			"probes": [
+				{
+					"find": "<button[\\s>]"
+				}
+			],
+			"use": "BbButton (a styled action) / BbBaseButton (your own look)",
+			"example": "<BbButton variant=\"ghost\" prepend:icon=\"lucide:plus\">Add row</BbButton>",
+			"note": "BbBaseButton keeps your markup and adds the cursor, the focus ring, `disabled` and links (`href`, Inertia visits). A raw button also loses the pointer cursor under Tailwind 4 without the library reset."
+		},
+		{
+			"id": "progress",
+			"pattern": "A hand-built progress bar: a raw `<progress>` or `role=\"progressbar\"`",
+			"ext": ["vue"],
+			"probes": [
+				{
+					"find": "<progress[\\s>]|role=.progressbar."
+				}
+			],
+			"use": "BbProgress",
+			"example": "<BbProgress label=\"Upload\" :model-value=\"40\" />",
+			"note": "A decorative bar with the numbers in text beside it can stay `aria-hidden` markup."
+		},
+		{
+			"id": "avatar",
+			"pattern": "An app avatar: an `InitialsAvatar` / `Avatar` component of your own, or initials computed for a round plate",
+			"ext": ["vue"],
+			"probes": [
+				{
+					"find": "<(Initials|User)?Avatar[\\s/>]|getInitials\\("
+				}
+			],
+			"use": "BbAvatar",
+			"example": "<BbAvatar size=\"40\" alt=\"Grace Hopper\">GH</BbAvatar>",
+			"note": "Circle only. The image, its load error and the icon fallback come with it."
+		},
+		{
+			"id": "adaptive-false",
+			"pattern": "`adaptive: false` (plugin) or `:adaptive=\"false\"` (one component): the temporary crutch from the migration",
+			"ext": ["vue", "ts", "js", "mjs"],
+			"probes": [
+				{
+					"find": "adaptive:\\s*false|:adaptive=.false."
+				}
+			],
+			"use": "Remove it in the adaptive phase (below)",
+			"example": "bitbossUi({ iconDir: 'resources/icons' })",
+			"note": "Keep it only on a surface that must never become a sheet, and say why in a comment."
+		}
+	]
+}

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

@@ -106,6 +106,19 @@ export interface NoUnknownAttributesOptions {
 	allowAttributes?: string[];
 	/** Component names to skip entirely. */
 	allowComponents?: string[];
+	/**
+	 * The app's own variant names per build-plugin option
+	 * (`{ dropdownItemVariants: ['warning'] }`), so a `:pt` key like
+	 * `'item:warning'` is a state, not a typo. Read from the project's Vite
+	 * config when left out.
+	 */
+	registeredVariants?: Record<string, string[]>;
+	/**
+	 * Whether the app turns Vue's Options API off: then an app's own variant
+	 * is no `pt:<part>:<name>` attribute (mixins do not merge). Read from the
+	 * project's config when left out.
+	 */
+	optionsApiOff?: boolean;
 }
 
 declare const plugin: ESLint.Plugin & {

package/scripts/lib/eslint-plugin.mjs

@@ -104,10 +104,39 @@ import {
 	NAV_ATTRS,
 	unknownComponentFinding,
 	PARTNER_PROP_PAIRS,
+	REGISTERED_VARIANT_OPTIONS,
 	toCamel,
 	keyedSlotLookup,
 	scriptSetupArrayConsts,
 } from './validate-bb-markup.mjs';
+import {
+	readOptionsApiOff,
+	readRegisteredVariants,
+} from './project-variant-dts.mjs';
+
+/**
+ * The project's registered variant names per plugin option (Q76.7), read from
+ * its Vite config once per project root: a `:pt` key naming an app's own
+ * variant is a real state, not a typo.
+ */
+const registeredVariantsByRoot = new Map();
+const registeredVariantsFor = (root) => {
+	if (!root) return {};
+	let found = registeredVariantsByRoot.get(root);
+	if (!found) {
+		found = readRegisteredVariants(root, REGISTERED_VARIANT_OPTIONS);
+		registeredVariantsByRoot.set(root, found);
+	}
+	return found;
+};
+/** Whether the project's build config turns the Options API off (no mixin props), per root. */
+const optionsApiOffByRoot = new Map();
+const optionsApiOffFor = (root) => {
+	if (!root) return false;
+	if (!optionsApiOffByRoot.has(root))
+		optionsApiOffByRoot.set(root, readOptionsApiOff(root));
+	return optionsApiOffByRoot.get(root);
+};
 import {
 	REACTIVE_V_MODEL_MESSAGE,
 	reactiveConstNames,
@@ -147,7 +176,11 @@ import {
 	ruleNamesIn,
 	unregisteredRuleMessage,
 } from './rule-registry.mjs';
-import { matchNameStyle, planAttributeFix } from './migrate-fix.mjs';
+import {
+	attrRemovalRange,
+	matchNameStyle,
+	planAttributeFix,
+} from './migrate-fix.mjs';
 import {
 	UNIMPORTED_MESSAGE,
 	projectResolution,
@@ -338,6 +371,15 @@ const noUnknownAttributes = {
 					allowAttributes: { type: 'array', items: { type: 'string' } },
 					allowComponents: { type: 'array', items: { type: 'string' } },
 					libraryImports: LIBRARY_IMPORTS_SCHEMA,
+					// The app's variant names per plugin option; read from the
+					// project's Vite config when left out.
+					registeredVariants: {
+						type: 'object',
+						additionalProperties: { type: 'array', items: { type: 'string' } },
+					},
+					// Whether the app turns Vue's Options API off; read from the
+					// project's config when left out.
+					optionsApiOff: { type: 'boolean' },
 				},
 				additionalProperties: false,
 			},
@@ -366,6 +408,15 @@ const noUnknownAttributes = {
 
 		const allowAttrs = new Set(options.allowAttributes ?? []);
 		const allowComps = allowedComponentsFor(context, options);
+		const filename = context.filename ?? context.getFilename?.();
+		let registered;
+		const registeredVariants = () =>
+			(registered ??=
+				options.registeredVariants ??
+				registeredVariantsFor(filename ? projectRootFor(filename) : null));
+		const optionsApiOff = () =>
+			options.optionsApiOff ??
+			optionsApiOffFor(filename ? projectRootFor(filename) : null);
 
 		/**
 		 * Which bitboss-ui entrypoint each local name came from. Unlike a
@@ -416,13 +467,10 @@ const noUnknownAttributes = {
 
 			return (fixer) => {
 				switch (plan.action) {
-					case 'remove': {
-						// Drop the attribute and one leading space so no gap remains.
-						let [from] = attr.range;
-						const [, end] = attr.range;
-						if (from > 0 && /\s/.test(sourceCode.text[from - 1])) from -= 1;
-						return fixer.removeRange([from, end]);
-					}
+					case 'remove':
+						return fixer.removeRange(
+							attrRemovalRange(sourceCode.text, attr.range)
+						);
 					case 'rename': {
 						const styled = matchNameStyle(plan.to, originalName);
 						const nameNode =
@@ -437,6 +485,11 @@ const noUnknownAttributes = {
 						const styled = matchNameStyle(plan.to, originalName);
 						return fixer.replaceText(attr, `:${styled}="${plan.expr}"`);
 					}
+					case 'setBare':
+						return fixer.replaceText(
+							attr,
+							matchNameStyle(plan.to, originalName)
+						);
 					default:
 						return null;
 				}
@@ -475,6 +528,8 @@ const noUnknownAttributes = {
 					// Q54.4: every form control is form-aware wherever it comes from.
 					const checker = createComponentChecker(surface, {
 						includeValidated: true,
+						registeredVariants: registeredVariants(),
+						optionsApiOff: optionsApiOff(),
 					});
 					for (const attr of node.startTag.attributes) {
 						// `v-model` / `:model-value` / `@update:model-value` on BbForm
@@ -526,7 +581,10 @@ const noUnknownAttributes = {
 													? prop.key.value
 													: null;
 										if (key === null) continue;
-										const ptFinding = checker.checkPtKey(key);
+										const ptFinding = checker.checkPtKey(
+											key,
+											registeredVariants()
+										);
 										if (!ptFinding) continue;
 										// A renamed part (Q51.16) is rewritten in the key's
 										// own spelling: bare stays bare when it can, a
@@ -1509,7 +1567,10 @@ const noReverseFalse = {
 								},
 								{
 									desc: 'Remove it (control on the left, the v3 default)',
-									fix: (fixer) => fixer.remove(attr),
+									fix: (fixer) =>
+										fixer.removeRange(
+											attrRemovalRange(sourceCode.text, attr.range)
+										),
 								},
 							],
 						});
@@ -1546,7 +1607,10 @@ const noReverseFalse = {
 							},
 							{
 								desc: 'Control on the left: remove the prop (it is the default)',
-								fix: (fixer) => fixer.remove(attr),
+								fix: (fixer) =>
+									fixer.removeRange(
+										attrRemovalRange(sourceCode.text, attr.range)
+									),
 							},
 						],
 					});

package/scripts/lib/helpers-add.mjs

@@ -152,6 +152,21 @@ export function loadContext({ cwd, packageRoot, command }) {
 	};
 }
 
+/** An installed package's package.json, walking up from `root`; null if none. */
+function readInstalledJson(root, name) {
+	for (let dir = root; ; dir = dirname(dir)) {
+		const path = join(dir, 'node_modules', name, 'package.json');
+		if (existsSync(path)) {
+			try {
+				return JSON.parse(readFileSync(path, 'utf-8'));
+			} catch {
+				return null;
+			}
+		}
+		if (dirname(dir) === dir) return null;
+	}
+}
+
 /** The first `node_modules/bitboss-ui` walking up from `root` (directory walk-up, like Node's resolution). */
 function findInstalled(root) {
 	let dir = root;
@@ -749,10 +764,19 @@ function missingPackages(ctx, names) {
 	const missing = (set) => [...set].filter((p) => !ctx.declared.has(p)).sort();
 	const run = missing(runtime);
 	const dev = missing(types);
+	// `@inertiajs/core` types must be the core the app's `@inertiajs/vue3`
+	// runs on: a bare `-D @inertiajs/core` installs the newest one, and two
+	// cores' Visit types do not match (strict apps fail to type-check).
+	const spec = (p) => {
+		const pinned =
+			p === '@inertiajs/core' &&
+			readInstalledJson(ctx.root, '@inertiajs/vue3')?.dependencies?.[p];
+		return pinned ? `${p}@${pinned}` : p;
+	};
 	const verb = { npm: 'i', pnpm: 'add', yarn: 'add', bun: 'add' }[ctx.pm];
 	const install = [
-		...(run.length ? [`${ctx.pm} ${verb} ${run.join(' ')}`] : []),
-		...(dev.length ? [`${ctx.pm} ${verb} -D ${dev.join(' ')}`] : []),
+		...(run.length ? [`${ctx.pm} ${verb} ${run.map(spec).join(' ')}`] : []),
+		...(dev.length ? [`${ctx.pm} ${verb} -D ${dev.map(spec).join(' ')}`] : []),
 	];
 	return { missing: [...run, ...dev], install };
 }