bitboss-ui 3.0.0-beta.53 → 3.0.0-beta.56

package/README.md

@@ -38,18 +38,20 @@ Full detail: `dist/ai/guides/installation-and-plugin-setup.md`.
 
 ### Composables
 
-| Composable             | Role                                                                  |
-| ---------------------- | --------------------------------------------------------------------- |
-| `useBbConfig`          | `setConfig()` patches the one runtime-editable kit option: `locale`.  |
-| `useBbDropdownContext` | Read a `BbDropdown`'s resolved groups/selections from anywhere by id. |
-| `useBbTableContext`    | Imperative handle onto a `BbTable` by id.                             |
-| `useBbTabsContext`     | Programmatic tab selection for a `BbTabs` by id.                      |
-| `useConfirm`           | Programmatic confirm / modal flows.                                   |
-| `useCountdown`         | Countdown timer state.                                                |
-| `useId`                | SSR-safe unique ids.                                                  |
-| `useMobile`            | Mobile / viewport-oriented behaviour.                                 |
-| `useSafeArea`          | Claim a screen edge for a docked panel so toasts avoid it.            |
-| `useToast`             | Toast notifications API.                                              |
+| Composable              | Role                                                                  |
+| ----------------------- | --------------------------------------------------------------------- |
+| `useBbConfig`           | `setConfig()` patches the one runtime-editable kit option: `locale`.  |
+| `useBbDialogContext`    | Open, close and read a `BbDialog` by id (nearest scope).              |
+| `useBbDropdownContext`  | Read a `BbDropdown`'s resolved groups/selections from anywhere by id. |
+| `useBbOffCanvasContext` | Open, close and read a `BbOffCanvas` by id (nearest scope).           |
+| `useBbTableContext`     | Imperative handle onto a `BbTable` by id.                             |
+| `useBbTabsContext`      | Programmatic tab selection for a `BbTabs` by id.                      |
+| `useConfirm`            | Programmatic confirm / modal flows.                                   |
+| `useCountdown`          | Countdown timer state.                                                |
+| `useId`                 | SSR-safe unique ids.                                                  |
+| `useMobile`             | Mobile / viewport-oriented behaviour.                                 |
+| `useSafeArea`           | Claim a screen edge for a docked panel so toasts avoid it.            |
+| `useToast`              | Toast notifications API.                                              |
 
 ### Utilities
 
@@ -57,7 +59,7 @@ Full detail: `dist/ai/guides/installation-and-plugin-setup.md`.
 
 ### Directives
 
-`vBbTooltip`, `vBbDropdown`, `vBbColor`, `vBbDate`, `vBbTime`, `vBbHoverCard`, `vBbPopover` — plus a
+`vBbTooltip`, `vBbDropdown`, `vBbColor`, `vBbDate`, `vBbTime`, `vBbHoverCard`, `vBbPopover`, `vBbDialog`, `vBbOffCanvas` — plus a
 `Bb*DirectivePlugin` for each, for app-level registration. Prefer the directive
 over the component for simple no-slot cases.
 
@@ -382,7 +384,7 @@ in place — the rule is a codemod, not just a linter:
 | `<BbIcon type="star" />`                  | `<BbIcon icon="star" />`                 | rename                    |
 | `<BbTable :allow-select-all="x" />`       | `<BbTable :disable-select-all="!(x)" />` | polarity inversion        |
 | `<BbSelect allow-writing="not-mobile" />` | `<BbSelect disable-writing="mobile" />`  | rename + value remap      |
-| `<BbToast placement="top-end" />`         | `<BbToast position="top-right" />`       | value map                 |
+| `<BbHost />`                              | `<BbHost />`                             | value map                 |
 | `<BbPopover show-arrow />`                | `<BbPopover />`                          | removed & inert → deleted |
 | `<BbBadge content="5" />`                 | _(unchanged — reported)_                 | needs a slot: manual      |
 
@@ -597,37 +599,28 @@ script, a switch bound to the same ref and your own components are never
 reported. `BbAccordion` wires all of it for you.
 `bitboss-ui check` reports the same as `collapsible-trigger-aria`.
 
-#### `required` inside a BbForm: `no-required-in-form`
-
-A `BbForm` posts `novalidate` (vee-validate owns validation), so `required` on
-a form control inside one shows the asterisk and enforces nothing: an empty
-field submits. `bitboss-ui/no-required-in-form` (error) reports a static
-`required` or a bound `:required` on a library form control inside a
-`<BbForm>` in the same template. Write the requirement where the form
-validates; the asterisk follows:
-
-```vue
-<template>
-	<BbForm :model="draft" @submit="save">
-		<BbTextInput name="email" label="Email" rules="required|email" />
-		<BbTextInput
-			name="vat"
-			label="VAT number"
-			:rules="{ required: isCompany }"
-		/>
-	</BbForm>
-</template>
+#### A rule nobody registered: `no-unregistered-rule`
+
+A string rule is a vee-validate rule name, and vee-validate knows only the
+names your app passes to `defineRule`; it throws "No such validator" when the
+field validates. `bitboss-ui/no-unregistered-rule` (error) reads every rule
+name a library control's `rules` shows (`rules="required|email"`, a bound
+string, `:rules="{ required: isCompany }"`) and looks for its registration
+across the project: a literal `defineRule('email', …)`, a loop over
+`@vee-validate/rules` itself (it reads the installed package), or a loop over
+an object literal in the same file. A registration it cannot read (a name
+from a variable, an object from another file, a shared package) is never a
+silence: the rule is reported as unconfirmed, naming the call. Write the name
+literally, or list it once in `bitboss-ui.check.json`:
+
+```json
+{ "registeredRules": ["tenant_code"] }
 ```
 
-`--fix` rewrites a bare `required` to `rules="required"` when the control has
-no `rules` and the form no `schema`; anything else is reported for you to move
-(with a `schema`, require the key there). A control your own component renders
-inside the form's slot is not seen. `required` beside a `:rules` function is
-reported too, without a fix: the function checks a value only when there is
-one, so register it (`defineRule('vat', isVat)`) and write
-`rules="required|vat"`, or require the key in the schema. Outside a `BbForm`
-`required` stays: a plain `<form>` validates natively.
-`bitboss-ui check` reports the same as `required-in-form`.
+(or `package.json` → `"bitboss-ui": { "registeredRules": [...] }`). A function
+rule needs no registration, and rules beside a form `schema` never run, so
+neither is reported. `bitboss-ui check` reports the same as
+`unregistered-rule`.
 
 #### Rating star colours: `no-star-color`
 

package/bin/bitboss-ui-mcp.mjs

@@ -672,7 +672,7 @@ function seeAlso(entry, contract) {
 	// where "write a MemberSelect around BbSelect" is answered (Q52.6.1).
 	if (/options-items-playbook\.md/.test(contract) && isGeneric(entry))
 		out.push(
-			`Your own ${entry.name} with fixed items (a CustomerSelect): a preset, one call to definePreset (a helper you copy from the guide, not a bitboss-ui export): get_guide({ name: 'preset-components.md' }). Wrapping BbSelect in your own component with its own logic: get_guide({ name: 'options-items-playbook.md', sections: ['Wrapping BbSelect in your own component'] })`
+			`Your own ${entry.name} with fixed items (a CustomerSelect): a preset, one call to definePreset (a helper you copy with: cp node_modules/bitboss-ui/dist/ai/helpers/definePreset.ts src/lib/definePreset.ts; not a bitboss-ui export): get_guide({ name: 'preset-components.md' }). Wrapping BbSelect in your own component with its own logic: get_guide({ name: 'options-items-playbook.md', sections: ['Wrapping BbSelect in your own component'] })`
 		);
 	if (entry.validated)
 		out.push(
@@ -2180,12 +2180,13 @@ function getComposable({ name, sections, maxChars } = {}) {
 	const markdown = readFileSync(join(dir, file), 'utf-8');
 	/*
 	 * A composable that needs a host component says so FIRST, as a field: with
-	 * no `<BbConfirm />`, `await confirm()` never settles. Every blind answerer
+	 * no `<BbHost />`, `await confirm()` resolves `false` after a second and a
+	 * toast never shows. Every blind answerer
 	 * of "await an Are-you-sure dialog" (4 of 4, 2026-09-24) left the host out,
 	 * although the doc's second paragraph states it.
 	 */
 	const host = frontmatter(markdown).summary?.match(
-		/Requires (exactly one <Bb\w+ \/> host[^.]*)\./
+		/Requires (exactly one <Bb\w+ \/>(?: host)?[^.]*)\./
 	)?.[1];
 	const base = {
 		found: true,

package/bin/bitboss-ui.mjs

@@ -86,7 +86,10 @@ import {
 	portalFindings,
 	projectPortalIndex,
 } from '../scripts/lib/portal-names.mjs';
-import { cssClassFindings } from '../scripts/lib/css-class-check.mjs';
+import {
+	cssClassFindings,
+	ownedClassBlocks,
+} from '../scripts/lib/css-class-check.mjs';
 import {
 	cssLocalFindings,
 	libraryTokens,
@@ -98,6 +101,11 @@ import {
 } from '../scripts/lib/hand-imported-styles.mjs';
 import { unknownLocaleFindings } from '../scripts/lib/locale-check.mjs';
 import {
+	readShippedDefinePreset,
+	staleDefinePresetFindings,
+} from '../scripts/lib/define-preset-copy.mjs';
+import {
+	readRegisteredVariants,
 	syncNotice,
 	syncProjectVariantDts,
 } from '../scripts/lib/project-variant-dts.mjs';
@@ -117,12 +125,18 @@ import {
 	MCP_BIN_PATH,
 	MCP_PEERS,
 } from '../scripts/lib/mcp-config.mjs';
+import {
+	addRegistrations,
+	configuredRegisteredRules,
+	ownedBy,
+	packageRuleNames,
+} from '../scripts/lib/rule-registry.mjs';
 import {
 	loadManifest,
-	registeredRuleNames,
 	presetDefinitions,
 	validateMarkdown,
 	validateVueSnippet,
+	VARIANT_INTENT_OPTIONS,
 } from '../scripts/lib/validate-bb-markup.mjs';
 
 const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
@@ -455,29 +469,71 @@ function inSkippedDir(relPath) {
  * `recursive: true` readdir) is what keeps a multi-thousand-file `vendor/`
  * tree from being walked at all.
  */
-function collectCheckFiles(dir, relBase = dir, extensions = CHECK_EXTENSIONS) {
+function collectCheckFiles(
+	dir,
+	relBase = dir,
+	extensions = CHECK_EXTENSIONS,
+	chain = []
+) {
 	let entries;
 	try {
 		entries = readdirSync(dir, { withFileTypes: true });
 	} catch {
 		return [];
 	}
+	// The `.gitignore` chain at this level (git semantics, shared with the
+	// icon scan): build output a project ignores (`.vercel/output`, `.nuxt`,
+	// `coverage`) is never swept.
+	const own = gitignoreKit?.readGitignore(dir);
+	const here = own ? [...chain, { dir, ig: own }] : chain;
+	const ignored = (full, isDir) =>
+		!!gitignoreKit && gitignoreKit.isGitignored(here, full, isDir);
 	const out = [];
 	for (const entry of entries) {
 		const full = join(dir, entry.name);
 		if (entry.isDirectory()) {
 			if (isSkippedSegment(entry.name)) continue;
 			if (isSkippedSubpath(relative(relBase, full))) continue;
-			out.push(...collectCheckFiles(full, relBase, extensions));
+			if (ignored(full, true)) continue;
+			out.push(...collectCheckFiles(full, relBase, extensions, here));
 			continue;
 		}
 		if (!entry.isFile()) continue;
 		if (!extensions.some((ext) => entry.name.endsWith(ext))) continue;
+		if (ignored(full, false)) continue;
 		out.push(full);
 	}
 	return out;
 }
 
+/**
+ * The icon scan's `.gitignore` reader, loaded once by `check` before its
+ * sweep. In the library repo it loads from source (`src/icon-scan.ts`, Node
+ * strips the types): `dist` may be absent (the release runs the node suite
+ * before the build) or stale. In the package, which ships no `src`, it loads
+ * from `dist/icon-scan.js`. Failing to load it is an error, never a sweep
+ * without it: that would report a project's gitignored build output.
+ * Returns the error, or null once loaded.
+ */
+let gitignoreKit = null;
+async function loadGitignoreKit() {
+	const source = join(PACKAGE_ROOT, 'src', 'icon-scan.ts');
+	const file = existsSync(source)
+		? source
+		: join(PACKAGE_ROOT, 'dist', 'icon-scan.js');
+	const where = relative(PACKAGE_ROOT, file);
+	let kit;
+	try {
+		kit = await import(pathToFileURL(file).href);
+	} catch (error) {
+		return `cannot load the .gitignore reader from ${where}: ${error.message}`;
+	}
+	if (!kit.readGitignore || !kit.isGitignored || !kit.ancestorGitignores)
+		return `${where} does not export the .gitignore reader`;
+	gitignoreKit = kit;
+	return null;
+}
+
 /**
  * Resolve the file list for `check`: explicit globs/paths if given, otherwise
  * every `.vue`/`.md` file under `cwd` (excluding `CHECK_SKIP_DIRS`/
@@ -492,7 +548,13 @@ function collectCheckFiles(dir, relBase = dir, extensions = CHECK_EXTENSIONS) {
  * skipped dirs.
  */
 function resolveCheckFiles(cwd, patterns) {
-	if (patterns.length === 0) return collectCheckFiles(cwd).sort();
+	if (patterns.length === 0)
+		return collectCheckFiles(
+			cwd,
+			cwd,
+			CHECK_EXTENSIONS,
+			gitignoreKit?.ancestorGitignores(cwd) ?? []
+		).sort();
 
 	const matched = new Set();
 	for (const pattern of patterns) {
@@ -855,6 +917,11 @@ async function checkCommand(
 	}
 ) {
 	const projectRoot = process.cwd();
+	const kitError = await loadGitignoreKit();
+	if (kitError) {
+		console.error(`[bitboss-ui] check: ${kitError}`);
+		process.exit(1);
+	}
 	if (changedOnly && globs.length) {
 		console.error('[bitboss-ui] check: pass paths or `--changed`, not both.');
 		process.exit(1);
@@ -986,7 +1053,8 @@ async function checkCommand(
 	const projectSources = collectCheckFiles(
 		projectRoot,
 		projectRoot,
-		HAND_IMPORTED_STYLES_EXTENSIONS
+		HAND_IMPORTED_STYLES_EXTENSIONS,
+		gitignoreKit?.ancestorGitignores(projectRoot) ?? []
 	);
 	const texts = new Map();
 	const readText = (path) => {
@@ -1010,8 +1078,15 @@ async function checkCommand(
 				.map((path) => readFileSync(path, 'utf-8')),
 		]);
 	// Q54.2: the rules the project registers with `defineRule`, from the same
-	// whole-project sweep, so a string rule nobody registered is caught.
-	const registeredRules = { names: new Set(), dynamic: false };
+	// whole-project sweep, so a string rule nobody registered is caught. Q67.1:
+	// a call the sweep cannot read is kept by its place, never a silence.
+	const registeredRules = {
+		names: new Set(configuredRegisteredRules(projectRoot)),
+		unreadable: [],
+		stock: packageRuleNames(projectRoot),
+	};
+	const packageRules = registeredRules.stock;
+	const ownedRuleSource = ownedBy(projectRoot);
 	const presets = new Map();
 	const RULE_EXTENSIONS = ['.ts', '.js', '.mjs', '.cjs', '.vue'];
 	for (const path of projectSources.filter((file) =>
@@ -1022,18 +1097,29 @@ async function checkCommand(
 			// Q57.3: the project's `definePreset` wrappers, by name.
 			for (const [name, preset] of presetDefinitions(text))
 				presets.set(name, preset);
-			const found = registeredRuleNames(text);
-			for (const name of found.names) registeredRules.names.add(name);
-			if (found.dynamic) registeredRules.dynamic = true;
+			// A nested app (its own package.json) registers nothing for this one.
+			if (ownedRuleSource(path))
+				addRegistrations(
+					registeredRules,
+					text,
+					relative(projectRoot, path),
+					packageRules
+				);
 		} catch {
-			/* unreadable: fewer names, which only means more caution below */
-			registeredRules.dynamic = true;
+			/* unreadable: its registrations are unknown, said where they would be */
+			if (ownedRuleSource(path))
+				registeredRules.unreadable.push(relative(projectRoot, path));
 		}
 	const validateOptions = {
 		allowComponents: allowedComponents,
 		projectReads,
 		registeredRules,
 		presets,
+		// A variant the build plugin registers is the project's own name.
+		registeredVariants: readRegisteredVariants(
+			projectRoot,
+			Object.values(VARIANT_INTENT_OPTIONS)
+		),
 	};
 
 	const findings = [];
@@ -1165,6 +1251,16 @@ async function checkCommand(
 			readText
 		)
 	);
+	// Q67.9: a project copy of the definePreset recipe older than the one
+	// shipped beside the manifest judged against (`<dist>/ai/helpers/`), or
+	// unstamped. Reads the stamp only: an edited copy is the app's own.
+	findings.push(
+		...staleDefinePresetFindings(
+			styleScan.map((path) => ({ path, relPath: relative(projectRoot, path) })),
+			readText,
+			readShippedDefinePreset(dirname(manifestPath))
+		)
+	);
 	// Q46.5: `.bb-*` selectors in the app's stylesheets (the `.vue` `<style>`
 	// blocks are read by the validator above).
 	for (const path of styleScan) {
@@ -1172,7 +1268,10 @@ async function checkCommand(
 		const relPath = relative(projectRoot, path);
 		const content = readText(path);
 		for (const finding of [
-			...cssClassFindings(content, manifest.cssSurface, { stylesheet: true }),
+			...cssClassFindings(content, manifest.cssSurface, {
+				stylesheet: true,
+				ownedBlocks: ownedClassBlocks(allowedComponents, manifest.cssSurface),
+			}),
 			// Q46.6: custom properties set where nothing reads them.
 			...cssLocalFindings(content, manifest.cssSurface, manifest.localSurface, {
 				stylesheet: true,
@@ -1450,7 +1549,9 @@ Commands:
                         package.json  { "bitboss-ui": { "allowComponents": ["BbRichEditor"] } }
                       or \`bitboss-ui.check.json\` \`{ "allowComponents": [...] }\`.
                       Same option name as the ESLint rules' \`allowComponents\`,
-                      so both gates configure alike.
+                      so both gates configure alike. An allowed or
+                      project-local component owns its \`bb-<kebab>\` class
+                      block, so CSS styling it is never \`unknown-class\`.
 
                       \`--json\` prints \`{ findings: [...], warnings: [...], hints: [...],
                       suppressed, files, manifestVersion, installedVersion }\`
@@ -1515,11 +1616,6 @@ Commands:
                       \`@click="open = !open"\` flips a BbCollapsible's
                       ref, with no \`aria-expanded\`: add
                       \`:aria-expanded="open"\` + \`aria-controls\`),
-                      \`required-in-form\` (\`required\` on a form control
-                      inside a \`BbForm\`: the asterisk shows but the form
-                      posts \`novalidate\`, so nothing enforces it; write
-                      \`rules="required"\` or make it required in the
-                      schema),
                       \`form-v-model\` (\`v-model\`, \`:model-value\` or an
                       \`@update:model-value\` listener on a \`BbForm\`: it
                       takes its object one way, \`:model="draft"\`),
@@ -1534,6 +1630,11 @@ Commands:
                       hover-card portal opened by \`v-bb-popover\`, or the
                       other way round; literal names only, a \`:name\`
                       binding or a non-literal call site is never judged),
+                      \`unknown-dialog\` (\`v-bb-dialog\` /
+                      \`v-bb-off-canvas\` / \`useBbDialogContext()\` /
+                      \`useBbOffCanvasContext()\` names an id no
+                      \`<BbDialog | BbOffCanvas id>\` declares, or one of
+                      the other family; literal ids only),
                       \`positional-provider\` (an \`items\` provider with
                       positional arguments: it receives one object,
                       \`({ query, reason, modelValue, signal })\`),
@@ -1549,12 +1650,18 @@ Commands:
                       \`retired-entrypoint\` (an import from
                       \`bitboss-ui/validated\`, retired: everything is in
                       \`bitboss-ui\`; \`--fix\` rewrites it in .vue files),
-                      \`unregistered-rule\` (a string rule no
-                      \`defineRule\` in the project registers; silent when
-                      the project registers rules in a loop),
+                      \`unregistered-rule\` (a string or object rule no
+                      \`defineRule\` in the project registers; a
+                      registration it cannot read is named, never skipped:
+                      list such names under \`registeredRules\` in
+                      bitboss-ui.check.json),
                       \`invalid-value\` (a static value outside a closed
                       union, e.g. \`placement="bottom-centre"\`; variants
                       and other registry-backed unions are not checked),
+                      \`stale-define-preset\` (a copy of the definePreset
+                      recipe whose \`// bitboss-ui definePreset rev N\` stamp
+                      is older than the shipped one, or missing; update it
+                      with \`cp node_modules/bitboss-ui/dist/ai/helpers/definePreset.ts <file>\`),
                       \`wrapper-drops-props\` (a wrapper whose
                       \`defineProps\` declares a \`Bb*Props\` type, bare,
                       \`Omit\` or \`Pick\`, and never binds or reads some