bitboss-ui 3.0.0-beta.0 → 3.0.0-beta.10

package/README.md

@@ -36,46 +36,53 @@ Full detail: `ai/guides/installation-and-plugin-setup.md`.
 
 ### Composables
 
-| Composable                    | Role                                                       |
-| ----------------------------- | ---------------------------------------------------------- |
-| `useBbConfig`                 | Global options for the kit (locale, defaults, etc.).       |
-| `useBroadcastChannelInstance` | Shared `BroadcastChannel` helper for cross-tab messaging.  |
-| `useConfirm`                  | Programmatic confirm / modal flows.                        |
-| `useCountdown`                | Countdown timer state.                                     |
-| `useMobile`                   | Mobile / viewport-oriented behaviour.                      |
-| `useQueue`                    | Simple async task queue.                                   |
-| `useSafeArea`                 | Claim a screen edge for a docked panel so toasts avoid it. |
-| `useToast`                    | Toast notifications API.                                   |
-
-### Base\* components (primitives) _(reference-only - prefer `Bb*` equivalents for consumer code)_
-
-Headless or low-level pieces used inside **Bb\*** wrappers or your own compositions:
-
-- **Actions:** `BbBaseButton`
-- **Text & numbers:** `BaseTextInput`, `BaseTextarea`, `BaseNumberInput`, `BaseTag`
-- **Choice:** `BaseCheckbox`, `BaseCheckboxGroup`, `BaseRadio`, `BaseRadioGroup`, `BaseSwitch`, `BaseSwitchGroup`, `BaseSlider`, `BaseRating`
-- **Choice glyphs (presentational SVGs):** `BbBaseCheckboxIcon`, `BbBaseRadioIcon`, `BbBaseSwitchIcon`
-- **Rich inputs:** `BaseSelect`, `BaseColorInput`, `BaseDatePicker`, `BaseDatePickerInput`
-- **Layout / chrome:** `BaseInputContainer`, `BaseDialog`
+| Composable             | Role                                                                  |
+| ---------------------- | --------------------------------------------------------------------- |
+| `useBbConfig`          | Global options for the kit (locale, defaults, etc.).                  |
+| `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.                                              |
+
+### Utilities
+
+- **`slotKey`** — the normalizer behind every dynamic per-item named slot (`BbDropdown`, `BbTable`, `BbTabs`, `BbTree`, `BbBreadcrumbs`). Import it when building slot names programmatically instead of restating the rule.
+
+### Directives
+
+`vBbTooltip`, `vBbDropdown`, `vBbColor`, `vBbDate`, `vBbTime` — plus a
+`Bb*DirectivePlugin` for each, for app-level registration. Prefer the directive
+over the component for simple no-slot cases.
+
+### Base\* primitives
+
+The styled `Base*` input controls and the input chrome (`BbBaseInputContainer`,
+`CommonInputWrapper` — label, prepend/append, prefix/suffix, clear button,
+spacing) are **internal composition layers and are not exported**. Use the full
+public inputs (`BbTextInput`, `BbSelect`, …); pass `hideLabel` for a
+bare/inline control. The exported primitives are **`BbBaseButton`** and the
+presentational glyphs **`BbBaseCheckboxIcon`**, **`BbBaseRadioIcon`**,
+**`BbBaseSwitchIcon`**.
 
 ### Bb\* components (composed)
 
 Product-ready components with labels, hints, errors, and consistent styling:
 
-- **Forms & actions:** `BbTextInput`, `BbTextarea`, `BbNumberInput`, `BbSelect`, `BbCheckbox`, `BbCheckboxGroup`, `BbRadio`, `BbRadioGroup`, `BbSwitch`, `BbSwitchGroup`, `BbSlider`, `BbRating`, `BbColorInput`, `BbDatePickerInput`, `BbButton`, `BbBadge`, `BbIndicator`, `BbTag`, `BbDropdown`, `BbDropdownButton`
-- **Feedback:** `BbAlert`, `BbProgress`, `BbSpinner`, `BbToast`, `BbTooltip`
-- **Layout & navigation:** `BbAccordion`, `BbCollapsible`, `BbTab`, `BbBreadcrumbs`, `BbPagination`,`BbSmoothHeight`
+- **Forms & actions:** `BbTextInput`, `BbTextarea`, `BbNumberInput`, `BbSelect`, `BbSelectPopover`, `BbCheckbox`, `BbCheckboxGroup`, `BbRadio`, `BbRadioGroup`, `BbSwitch`, `BbSwitchGroup`, `BbSlider`, `BbRating`, `BbColorInput`, `BbColorPalette`, `BbDatePicker`, `BbDatePickerInput`, `BbTimePicker`, `BbTimePickerInput`, `BbButton`, `BbBadge`, `BbBadgeButton`, `BbIndicator`, `BbTag`, `BbDropdown`, `BbDropdownGroup`, `BbDropdownButton`, `BbAsterisk`
+- **Feedback:** `BbAlert`, `BbProgress`, `BbSpinner`, `BbToast`, `BbToastPortal`, `BbTooltip`
+- **Layout & navigation:** `BbAccordion`, `BbCollapsible`, `BbTabs` (+ `BbTabsRoot`, `BbTabsList`, `BbTabsPanes`), `BbBreadcrumbs`, `BbPagination`, `BbSmoothHeight`
 - **Overlays & panels:** `BbDialog`, `BbConfirm`, `BbConfirmPortal`, `BbOffCanvas`, `BbPopover`
 - **Data:** `BbTable`, `BbTree`
 - **Media & files:** `BbAvatar`, `BbDropzone`, `BbIcon`
 
-### Shared input shells _(internal layout primitives - not for direct consumer use)_
-
-- **`CommonInputWrapper`** — the internal input-chrome primitive (label, prepend/append, prefix/suffix, clear button, spacing) that every `Bb*` input composes. Not exported; use the full public inputs (`BbTextInput`, `BbSelect`, …).
-
 ### Exported component types
 
-For most **Base\*** and **Bb\*** components, the package exports matching **props**, **events**, and (where relevant) **slots** types (for example `BbSelectProps`, `BaseSelectEvents`). Use them for typed wrappers and design-system layers; the docs list the full set per component.
+For the public **Bb\*** components, the package exports matching **props**, **events**, and (where relevant) **slots** types (for example `BbSelectProps`, `BbTableEvents`), plus supporting shapes like `BbDropdownItem` and `DropdownGroupItemsGetter`. Use them for typed wrappers and design-system layers; the docs list the full set per component.
 
 ---
 

package/bin/bitboss-ui.mjs

@@ -17,7 +17,17 @@
  *             components.json manifest (unknown props, removed props, bad
  *             v-models, unknown `<template #slot>` names, `href`/`to`/
  *             `method` on a component that doesn't declare them). Exits 1
- *             on findings; supports --json output.
+ *             on findings; supports --json output. Every finding carries the
+ *             source line. `--allow-component <Name>` (or package.json's
+ *             `bitboss-ui.allowComponents`) exempts an app-owned component
+ *             whose name happens to start with `Bb`.
+ *
+ *             SCOPE: `check` knows the INSTALLED v3 API and nothing about v2.
+ *             "was removed from X" is a recorded v2→v3 break; "is not in X's
+ *             API" only says the prop is not a v3 prop of that component —
+ *             it may never have been one anywhere. `printFindingLegend` says
+ *             so in the output, because two migrating fleets each spent real
+ *             time discovering it the hard way.
  *   mcp       Start a stdio MCP server exposing the dist/ai knowledge base
  *             (search_components, get_component, list_recipes, get_recipe,
  *             validate) to MCP-capable agent harnesses.
@@ -445,12 +455,84 @@ function summarizeFileCounts(files) {
 	return exts.map((ext) => `${counts.get(ext)} ${ext}`).join(' + ');
 }
 
+/**
+ * Component names the PROJECT owns despite the `Bb` prefix, read from disk so
+ * CI, the editor and a local run agree without repeating a flag.
+ *
+ * Two sources, merged: `bitboss-ui.check.json`'s `allowComponents`, and
+ * package.json's `bitboss-ui.allowComponents`. The package.json key is the one
+ * to reach for — it sits next to the `eslint.config.js` that already carries
+ * the same list for `no-unknown-attributes`, so the two gates stay in sync.
+ * Unreadable/malformed files are ignored: a broken config must not turn into a
+ * check failure about markup.
+ * @returns {string[]}
+ */
+function configuredAllowComponents(projectRoot) {
+	const out = [];
+	const readList = (path, pick) => {
+		try {
+			if (!existsSync(path)) return;
+			const value = pick(JSON.parse(readFileSync(path, 'utf-8')));
+			if (Array.isArray(value))
+				for (const name of value) if (typeof name === 'string') out.push(name);
+		} catch {
+			/* malformed config — ignore, never fail the check on it */
+		}
+	};
+	readList(
+		join(projectRoot, 'bitboss-ui.check.json'),
+		(cfg) => cfg?.allowComponents
+	);
+	readList(
+		join(projectRoot, 'package.json'),
+		(pkg) => pkg?.['bitboss-ui']?.allowComponents
+	);
+	return out;
+}
+
+/**
+ * CHK-SINCE-V2 — the two unknown-prop message shapes mean OPPOSITE things and
+ * nothing in the output said so. One migrating fleet filed two non-findings
+ * against the library, and the other told the categories apart only by
+ * installing v2 alongside and diffing by hand. Printed once per failing run,
+ * and only for the kinds actually present.
+ *
+ * `check` is honest about its limits here: it validates against the INSTALLED
+ * v3 manifest and holds no record of v2, so "is not in X's API" is a statement
+ * about v3 alone. Deciding whether such a prop ever worked is the reader's job,
+ * and the greps in the migration guide are how it is done.
+ */
+function printFindingLegend(findings) {
+	const kinds = new Set(findings.map((f) => f.kind));
+	const rows = [];
+	if (kinds.has('removed-prop'))
+		rows.push(
+			'  "was removed from X"   a v2→v3 break. X really had this prop; fix the call site.'
+		);
+	if (kinds.has('unknown-prop'))
+		rows.push(
+			'  "is not in X\'s API"    X does not declare this prop in v3 — and `check` cannot\n' +
+				'                         say whether it ever did. It may be a v3 removal that\n' +
+				'                         predates the removal register, or a name that was never\n' +
+				'                         a prop at all and has always fallen through to the DOM\n' +
+				'                         as an inert attribute. Check the v2 source before\n' +
+				'                         "restoring" anything: the second case needs deleting,\n' +
+				'                         not porting.'
+		);
+	if (rows.length === 0) return;
+	console.error('\nReading these findings:');
+	for (const row of rows) console.error(row);
+	console.error(
+		'  `check` reads the installed v3 manifest only; the package carries no v2 API.'
+	);
+}
+
 /**
  * `npx bitboss-ui check [glob…] [--json]` — validate `Bb*` markup (props,
  * v-models, and `<template #slot>` names) in `.vue` and `.md` files against
  * the installed components.json manifest.
  */
-function checkCommand(globs, jsonMode, allowEmpty = false) {
+function checkCommand(globs, { json: jsonMode, allowEmpty, allowComponents }) {
 	const projectRoot = process.cwd();
 
 	const manifestPath = join(PACKAGE_ROOT, 'dist', 'ai', 'components.json');
@@ -481,6 +563,15 @@ function checkCommand(globs, jsonMode, allowEmpty = false) {
 		: new Set();
 	const files = resolveCheckFiles(projectRoot, globs);
 
+	// CHK-ALLOWCOMPONENTS: `Bb` is a naming convention, not proof of ownership.
+	// An app component called `BbRichEditor` is not invalid library markup, and
+	// before this the only way to silence it was to rename the component.
+	const allowedComponents = [
+		...configuredAllowComponents(projectRoot),
+		...allowComponents,
+	];
+	const validateOptions = { allowComponents: allowedComponents };
+
 	const findings = [];
 	/*
 	 * Advisory only — see scripts/lib/hand-roll-hints.mjs. Hints never touch the
@@ -493,8 +584,8 @@ function checkCommand(globs, jsonMode, allowEmpty = false) {
 		const relPath = relative(projectRoot, file);
 		const content = readFileSync(file, 'utf-8');
 		const { findings: fileFindings } = file.endsWith('.md')
-			? validateMarkdown(content, manifest)
-			: validateVueSnippet(content, manifest);
+			? validateMarkdown(content, manifest, validateOptions)
+			: validateVueSnippet(content, manifest, validateOptions);
 		for (const finding of fileFindings) {
 			findings.push({ file: relPath, ...finding });
 		}
@@ -573,14 +664,19 @@ function checkCommand(globs, jsonMode, allowEmpty = false) {
 			finding.fenceInfo != null
 				? `fence#${finding.fenceIndex}${finding.fenceInfo ? ` (${finding.fenceInfo})` : ''} `
 				: '';
+		// CHK-LINE: three identical `full-screen` findings under one filename
+		// were indistinguishable, so every automated fix had to re-parse the
+		// file to place them. The line comes straight off the template AST.
+		const at = finding.line != null ? `line ${finding.line}: ` : '';
 		console.error(
-			`    ✗ ${where ? `[${where.trim()}] ` : ''}${finding.message}`
+			`    ✗ ${at}${where ? `[${where.trim()}] ` : ''}${finding.message}`
 		);
 		if (finding.hint) console.error(`      hint: ${finding.hint}`);
 	}
 	console.error(
 		'\nFix the markup (or the component API) so it stays copy-safe for agents.'
 	);
+	printFindingLegend(findings);
 	printHints();
 	process.exit(1);
 }
@@ -600,7 +696,8 @@ Commands:
                       server for Claude Code (.mcp.json), Cursor (.cursor/mcp.json),
                       VS Code/Copilot (.vscode/mcp.json), and Windsurf (~/.codeium
                       global) — merges, never overwrites other servers.
-  check [glob…] [--json] [--allow-empty]
+  check [glob…] [--json] [--allow-empty] [--allow-component <Name>]
+                      [--no-hints]
                       Validate \`Bb*\` markup in .vue/.md files against the
                       installed components.json manifest (unknown/removed props,
                       bad v-models, unknown \`<template #slot>\` names,
@@ -612,7 +709,27 @@ Commands:
                       Exits 1 on findings, and on an explicit glob that matched
                       nothing (a typo'd CI path validates zero files silently) —
                       pass \`--allow-empty\` when an empty match is expected.
-                      \`--json\` prints \`{ findings: [...], files }\`.
+
+                      \`--allow-component <Name>\` (repeatable) exempts a
+                      component your APP owns whose name starts with \`Bb\` —
+                      the prefix is a convention, not proof of provenance.
+                      Persist the list instead of repeating the flag:
+                        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.
+
+                      \`--json\` prints \`{ findings: [...], hints: [...], files }\`.
+                      Each finding: \`{ file, line, component, attr, kind,
+                      message, hint?, to? }\` (plus \`fenceIndex\`/\`fenceInfo\`
+                      inside a markdown fence; \`line\` is absolute in the file).
+                      \`kind\` is one of: \`removed-prop\` (a v2→v3 break — fix
+                      it), \`unknown-prop\` (not a v3 prop of that component;
+                      may never have been one — see the legend the text output
+                      prints), \`unknown-model\`, \`unknown-slot\`,
+                      \`no-default-slot\`, \`inert-nav-attr\`,
+                      \`missing-partner-prop\`, \`partner-prop\`,
+                      \`validated-only-prop\`.
   mcp                 Start a stdio MCP server exposing the dist/ai knowledge
                       base (search_components, get_component, list_recipes,
                       get_recipe, validate) to MCP-capable agent harnesses.
@@ -658,14 +775,18 @@ switch (command) {
 			{
 				json: { type: 'boolean' },
 				'allow-empty': { type: 'boolean' },
+				'allow-component': { type: 'string', multiple: true },
+				// Accepted and ignored here — read straight off argv inside
+				// checkCommand, but parseArgs is strict, so it must be declared.
+				'no-hints': { type: 'boolean' },
 			},
 			{ allowPositionals: true }
 		);
-		checkCommand(
-			positionals,
-			values.json ?? false,
-			values['allow-empty'] ?? false
-		);
+		checkCommand(positionals, {
+			json: values.json ?? false,
+			allowEmpty: values['allow-empty'] ?? false,
+			allowComponents: values['allow-component'] ?? [],
+		});
 		break;
 	}
 	case 'mcp': {

package/dist/ai/BbBadge.md

@@ -309,9 +309,12 @@ state in the handler. Prefer `secondary` / `outline` for filter chips; reserve
 ```
 
 The clear button inherits the variant's foreground, so it reads on every surface
-— light on a filled `primary`, dark on a `secondary`/`outline`. Set
-`clearable-label` for the button's accessible name (defaults to the localized
-`badge.clearLabel`).
+— light on a filled `primary`, dark on a `secondary`/`outline`. By default its
+accessible name composes the localized verb with the badge's own text — a chip
+reading "Italy" announces "Remove Italy", with no per-chip wiring. Set
+`clearable-label` only when that composition is wrong for the context (it
+replaces the whole name). With a `BbBadgeButton` body the composition is
+skipped and the button falls back to the bare localized `badge.clearLabel`.
 
 Icons combine with `clearable`: a **`prepend:icon`** stays (it leads the label);
 an **`append:icon`** shares the trailing slot with the clear button — the icon
@@ -695,8 +698,10 @@ selectors like `.bb-badge > .bb-badge__content`, which no longer match.
 - An icon-only badge (`icon`) has no visible text; the default slot is rendered
   as a screen-reader-only label — never leave it empty. In button mode that
   label is also the **button's accessible name**, so it is doubly required.
-- The `clearable` button has an accessible name from `clearable-label` (or the
-  localized `badge.clearLabel`).
+- The `clearable` button's accessible name is composed by default: the
+  localized `badge.clearLabel` verb plus the badge body's text ("Remove
+  Italy"). `clearable-label` replaces the whole name; with a `BbBadgeButton`
+  body the composition is skipped (bare verb only).
 - A clickable **and** clearable badge is two tab stops (body, then clear). That
   is intended: two actions, two controls.
 - Keyboard focus on either control rings the whole pill, so the focused target

package/dist/ai/BbSelect.md

@@ -1212,6 +1212,14 @@ Shipped behavior — never reimplement it:
   library default) — `direction="horizontal"` gives a label-beside-field row.
   Only `floating`/`inside` label modes force the vertical layout, since they
   embed the label in the field itself.
+- **A long `placeholder` or a long selected label never widens the control's
+  track.** The trigger is a button, not an `<input>`, so the placeholder is
+  real text rather than a paint-only `::placeholder` — but the field's minimum
+  size is capped so that text cannot become the floor of a grid or flex track.
+  Put a select with a paragraph-length placeholder in
+  `grid-template-columns: repeat(3, 1fr)` and you still get three equal
+  columns, with the text ellipsised inside its field. You do **not** need
+  `min-w-0` on the item or `minmax(0, 1fr)` on the track to get this.
 
 ### Adaptive mobile sheet