bitboss-ui 3.0.0-beta.47 → 3.0.0-beta.49

package/scripts/lib/renamed-item-field.mjs

@@ -0,0 +1,343 @@
+/**
+ * `renamed-item-field` (Q64.2–Q64.5, owner 2026-10-07): the fields of the
+ * item objects the library reads were renamed, so a v2 or early-v3 item keeps
+ * rendering but silently loses its identity — a dropdown row with `key` is a
+ * value-less action row (disabled in a selectable group), a group with `key`
+ * is not selectable, a tab with `key` has no value, a crumb with `text` has no
+ * label. No runtime alias reads the old spelling: this finding, `check --fix`
+ * and the ESLint rule `bitboss-ui/no-renamed-item-field` rewrite it.
+ *
+ * - BbDropdown, BbDropdownButton and `v-bb-dropdown` rows: `key` → `value`,
+ *   `text` → `label`; groups: `key` → `id`.
+ * - BbTabs / BbTabsRoot items: `key` → `value`.
+ * - BbBreadcrumbs items: `key` → `value`, `text` → `label`.
+ *
+ * Reach: object literals inside an `items` array the file spells — inline in
+ * the template, or a `<script setup>` const (`scriptSetupArrayConsts`) bound
+ * by name — including a dropdown's groups, nested arrays and submenus. Never
+ * the rows of a mapped (pipeline) group, which are app data read through
+ * `itemText` / `itemValue`. An object that already spells the new field, or
+ * spreads another object, is reported without a fix (rename it by hand).
+ * Items built elsewhere (a `computed`, an import, a fetch) are out of reach:
+ * typed ones fail `vue-tsc` (the old field is `never`).
+ *
+ * The rows below mirror `src/deprecation/ai-deprecations.json`'s
+ * `surface: 'item'` entries (`renamed-item-field.node.test.mjs` keeps them in
+ * step).
+ */
+import { babelParse, parse } from 'vue/compiler-sfc';
+import { libraryAliases, localBbImports } from './local-components.mjs';
+
+const NODE_ELEMENT = 1;
+const PROP_DIRECTIVE = 7;
+
+/** The version the renames shipped in. */
+export const ITEM_FIELD_SINCE = '3.0.0-beta.49';
+
+const DROPDOWN = {
+	row: { key: 'value', text: 'label' },
+	group: { key: 'id' },
+	nested: true,
+};
+
+/**
+ * component → `{ row, group?, nested? }`: the renames of a row object and of
+ * a group object (old field → new field), and whether rows hold groups,
+ * nested arrays and submenus (the dropdown family).
+ */
+export const ITEM_FIELD_RENAMES = {
+	BbDropdown: DROPDOWN,
+	BbDropdownButton: DROPDOWN,
+	BbTabs: { row: { key: 'value' } },
+	BbTabsRoot: { row: { key: 'value' } },
+	BbBreadcrumbs: { row: { key: 'value', text: 'label' } },
+};
+
+/** The directive whose value holds BbDropdown's items. */
+const DROPDOWN_DIRECTIVE = 'bb-dropdown';
+
+const NOUN = {
+	BbDropdown: { row: 'a BbDropdown row', group: 'a BbDropdown group' },
+	BbDropdownButton: {
+		row: 'a BbDropdownButton row',
+		group: 'a BbDropdownButton group',
+	},
+	BbTabs: { row: 'a BbTabs item' },
+	BbTabsRoot: { row: 'a BbTabsRoot item' },
+	BbBreadcrumbs: { row: 'a BbBreadcrumbs item' },
+};
+
+export const RENAMED_ITEM_FIELD_MESSAGES = {
+	rename: (noun, from, to) =>
+		`\`${from}\` on ${noun} is \`${to}\` since ${ITEM_FIELD_SINCE} — the old field is ignored, so the item ${
+			to === 'value'
+				? 'has no value (no `v-model` value, no slot of its own)'
+				: to === 'id'
+					? 'has no id (not selectable, no `<BbDropdownGroup>` binding, no slots)'
+					: 'has no label'
+		}. Rename it.`,
+	manual: (noun, from, to) =>
+		`\`${from}\` on ${noun} is \`${to}\` since ${ITEM_FIELD_SINCE}, but this object ${
+			to
+				? `already has \`${to}\` or spreads another object`
+				: 'spreads another object'
+		}: rename it by hand.`,
+};
+
+export const RENAMED_ITEM_FIELD_HINT =
+	'rows and crumbs are `{ label, value }`, tabs `{ value, label }`, dropdown groups `{ id, label, items }`';
+
+const pascal = (tag) =>
+	tag.includes('-')
+		? tag.replace(/(?:^|-)([a-z0-9])/g, (_, c) => c.toUpperCase())
+		: tag;
+
+const unwrap = (node) => {
+	let current = node;
+	while (
+		current &&
+		[
+			'TSAsExpression',
+			'TSSatisfiesExpression',
+			'TSNonNullExpression',
+			'TSTypeAssertion',
+			'ParenthesizedExpression',
+		].includes(current.type)
+	)
+		current = current.expression;
+	return current;
+};
+
+const keyName = (property) =>
+	(property.type === 'ObjectProperty' || property.type === 'ObjectMethod') &&
+	!property.computed
+		? property.key.type === 'Identifier'
+			? property.key.name
+			: property.key.type === 'StringLiteral'
+				? property.key.value
+				: undefined
+		: undefined;
+
+const propertyOf = (object, key) =>
+	object.properties.find((p) => keyName(p) === key);
+
+const isFunctionNode = (node) =>
+	node?.type === 'ObjectMethod' ||
+	node?.type === 'ArrowFunctionExpression' ||
+	node?.type === 'FunctionExpression';
+
+const isTrue = (node) => {
+	const value = unwrap(node);
+	return (
+		(value?.type === 'BooleanLiteral' || value?.type === 'Literal') &&
+		value.value === true
+	);
+};
+
+/** Resolves an `items` expression to an ArrayExpression, or null. */
+const arrayOf = (node, arrays) => {
+	const value = unwrap(node);
+	if (value?.type === 'ArrayExpression') return value;
+	if (value?.type === 'Identifier') return arrays?.get(value.name) ?? null;
+	return null;
+};
+
+const parseExpression = (content) => {
+	try {
+		const program = babelParse(`(${content})`, {
+			sourceType: 'module',
+			plugins: ['typescript'],
+		}).program;
+		return program.body[0]?.expression ?? null;
+	} catch {
+		return null;
+	}
+};
+
+/**
+ * Whether a dropdown entry is a group: `group: true`, `selectable` or
+ * `multiple` written, or a function `items` (a pipeline group) — the same
+ * rule as the component's `isGroup`.
+ */
+const isDropdownGroup = (entry) => {
+	if (isTrue(propertyOf(entry, 'group')?.value)) return true;
+	if (propertyOf(entry, 'selectable') || propertyOf(entry, 'multiple'))
+		return true;
+	const items = propertyOf(entry, 'items');
+	return isFunctionNode(items) || isFunctionNode(unwrap(items?.value));
+};
+
+/** A mapped group's rows are app data, read through its mappers. */
+const isMappedGroup = (entry) =>
+	['itemText', 'itemValue', 'itemProps', 'max'].some((name) =>
+		propertyOf(entry, name)
+	);
+
+/**
+ * @param {string} code a whole SFC (ranges are offsets into it) or a snippet
+ * @param {{ templateAst?: any, arrays?: Map<string, any>, library?: Parameters<typeof localBbImports>[1] }} [options]
+ *   `arrays`: the file's script-setup array consts (`scriptSetupArrayConsts`)
+ *   `library`: what counts as the library besides `bitboss-ui` (`isLibrarySource`)
+ * @returns {Array<{ component: string, attr: string, kind: 'renamed-item-field', line: number, message: string, hint: string, from: string, to: string, range?: [number, number], edit?: { range: [number, number], text: string } }>}
+ */
+export function renamedItemFieldFindings(code, options = {}) {
+	if (!/\b(key|text)\b/.test(code)) return [];
+	let descriptor = null;
+	try {
+		({ descriptor } = parse(code, { sourceMap: false }));
+	} catch {
+		descriptor = null;
+	}
+	const ast = options.templateAst ?? descriptor?.template?.ast;
+	if (!ast) return [];
+	// Offsets are only trusted on the file's own template AST.
+	const ranged =
+		!options.templateAst || options.templateAst === descriptor?.template?.ast;
+	const arrays = options.arrays;
+	const aliases = libraryAliases(code);
+	const own = localBbImports(code, options.library);
+	const scriptOffset = descriptor?.scriptSetup?.loc.start.offset ?? 0;
+	const scriptLine = descriptor?.scriptSetup?.loc.start.line ?? 1;
+	const findings = [];
+	const seenObjects = new Set();
+
+	/** One object's renames (a row or a group). */
+	const checkObject = (object, component, level, base, attr) => {
+		if (seenObjects.has(object)) return;
+		seenObjects.add(object);
+		const renames = ITEM_FIELD_RENAMES[component][level] ?? {};
+		const spreads = object.properties.some((p) => p.type === 'SpreadElement');
+		const noun = NOUN[component][level];
+		for (const [from, to] of Object.entries(renames)) {
+			const property = propertyOf(object, from);
+			if (!property || property.type !== 'ObjectProperty') continue;
+			const fixable = !spreads && !propertyOf(object, to);
+			const key = property.key;
+			const keyText =
+				key.type === 'StringLiteral'
+					? code.slice(base.offset + key.start, base.offset + key.end)
+					: null;
+			findings.push({
+				component,
+				attr,
+				kind: 'renamed-item-field',
+				from,
+				to,
+				line: base.line + property.loc.start.line - 1,
+				message: fixable
+					? RENAMED_ITEM_FIELD_MESSAGES.rename(noun, from, to)
+					: RENAMED_ITEM_FIELD_MESSAGES.manual(noun, from, to),
+				hint: RENAMED_ITEM_FIELD_HINT,
+				...(base.offset !== null
+					? {
+							range: [base.offset + property.start, base.offset + property.end],
+							...(fixable
+								? {
+										edit: property.shorthand
+											? {
+													// `{ key }` → `{ value: key }`
+													range: [
+														base.offset + property.start,
+														base.offset + property.end,
+													],
+													text: `${to}: ${from}`,
+												}
+											: {
+													range: [
+														base.offset + key.start,
+														base.offset + key.end,
+													],
+													text: keyText
+														? `${keyText[0]}${to}${keyText[0]}`
+														: to,
+												},
+									}
+								: {}),
+						}
+					: {}),
+			});
+		}
+	};
+
+	/** The rows of one array (and, for the dropdown family, what they hold). */
+	const checkArray = (array, component, base, attr) => {
+		const nested = ITEM_FIELD_RENAMES[component].nested;
+		for (const raw of array.elements) {
+			const entry = unwrap(raw);
+			if (nested && entry?.type === 'ArrayExpression') {
+				checkArray(entry, component, base, attr);
+				continue;
+			}
+			if (entry?.type !== 'ObjectExpression') continue;
+			const items = propertyOf(entry, 'items');
+			const children =
+				items?.type === 'ObjectProperty' ? arrayOf(items.value, arrays) : null;
+			if (nested && isDropdownGroup(entry)) {
+				checkObject(entry, component, 'group', base, attr);
+				if (children && !isMappedGroup(entry))
+					checkArray(children, component, siteOf(children, base), attr);
+				continue;
+			}
+			checkObject(entry, component, 'row', base, attr);
+			// A submenu is a row's `items`: rows again.
+			if (nested && children)
+				checkArray(children, component, siteOf(children, base), attr);
+		}
+	};
+
+	/**
+	 * Where an array's offsets count from: a script const lives in the script
+	 * block, whatever expression reached it.
+	 */
+	const scriptArrays = new Set(arrays ? [...arrays.values()] : []);
+	const scriptBase = {
+		offset: ranged && descriptor?.scriptSetup ? scriptOffset : null,
+		line: scriptLine,
+	};
+	const siteOf = (array, base) => (scriptArrays.has(array) ? scriptBase : base);
+
+	const seenArrays = new Set();
+	const checkValue = (prop, component, attr) => {
+		const expression = parseExpression(prop.exp?.content ?? '');
+		let value = unwrap(expression);
+		// `v-bb-dropdown="{ items: [...], … }"`
+		if (value?.type === 'ObjectExpression') {
+			const items = propertyOf(value, 'items');
+			if (items?.type !== 'ObjectProperty') return;
+			value = unwrap(items.value);
+		}
+		// `(` was prepended to the expression before parsing.
+		const templateBase = {
+			offset: ranged ? prop.exp.loc.start.offset - 1 : null,
+			line: prop.exp.loc.start.line,
+		};
+		const array = arrayOf(value, arrays);
+		if (!array || seenArrays.has(array)) return;
+		seenArrays.add(array);
+		checkArray(array, component, siteOf(array, templateBase), attr);
+	};
+
+	const walk = (node) => {
+		if (!node || typeof node !== 'object') return;
+		if (node.type === NODE_ELEMENT) {
+			const written = pascal(node.tag);
+			const component = own.has(node.tag)
+				? null
+				: (aliases.get(node.tag) ?? aliases.get(written) ?? written);
+			for (const prop of node.props ?? []) {
+				if (prop.type !== PROP_DIRECTIVE) continue;
+				if (prop.name === DROPDOWN_DIRECTIVE) {
+					checkValue(prop, 'BbDropdown', 'v-bb-dropdown');
+					continue;
+				}
+				if (!component || !ITEM_FIELD_RENAMES[component]) continue;
+				if (prop.name !== 'bind' || !prop.arg?.isStatic) continue;
+				if (prop.arg.content !== 'items') continue;
+				checkValue(prop, component, ':items');
+			}
+		}
+		for (const child of node.children ?? []) walk(child);
+	};
+	walk(ast);
+	return findings;
+}

package/scripts/lib/slot-key.mjs

@@ -3,7 +3,7 @@
 // source; scripts/lib/slot-key.node.test.mjs fuzzes the two against each other,
 // so an edit to one without the other fails the suite.
 /**
- * Normalizes an arbitrary item/column key into a template-safe slot name, by
+ * Normalizes an item value or column key into a template-safe slot name, by
  * lodash's `kebabCase` rules (owner ruling Q53.15, 2026-09-24; our own
  * implementation, no lodash dependency): accents are stripped (Latin-1 and
  * Latin Extended-A), the key is split into words (camelCase humps, acronyms,
@@ -15,7 +15,7 @@
  *
  * Shared by every component that exposes dynamic per-item named slots
  * (BbDropdown, BbTable, BbBreadcrumbs, BbTree, BbCalendar / BbDatePicker,
- * BbTabs) so a given key resolves to the same slot name everywhere.
+ * BbTabs) so a given value resolves to the same slot name everywhere.
  * `ColumnName` is the type-level mirror of this rule for ASCII keys — keep the
  * two in sync. Known collisions: `-5` / `5`; `aB` / `a_b` / `a-b` / `a b`.
  */

package/scripts/lib/slot-renames.mjs

@@ -38,7 +38,7 @@ export function renamedSlot(rows, name) {
 		if (!match || match[1].includes(':')) continue;
 		const to = row.new ? row.new.replace('<x>', match[1]) : null;
 		// A self-rename is today's name (`label:<x>` → `<x>:label` for a tab
-		// keyed `label`, Q59).
+		// whose value is `label`, Q59).
 		if (to !== name) return { to, since: row.since, hint: row.hint };
 	}
 	return null;

package/scripts/lib/unimported-components.mjs

@@ -90,8 +90,11 @@ const SKIP = new Set([
 const SCRIPT = /\.(?:[cm]?[jt]s|vue)$/;
 const TEST = /\.(?:test|spec)(?:-d)?\.[cm]?[jt]s$/;
 
-/** Files under the root worth reading (bounded, like `check`'s sweep). */
-function walk(root, depth = 0, out = []) {
+/**
+ * Files under the root worth reading (bounded, like `check`'s sweep): scripts,
+ * `.vue` files and `.d.ts`, never tests. Shared with portal-names.mjs.
+ */
+export function walk(root, depth = 0, out = []) {
 	if (depth > 8 || out.length > 20000) return out;
 	let entries = [];
 	try {