@koobiq/components 20.4.2 → 21.0.1

package/schematics/migrations/form-field-signals/index.cjs

@@ -0,0 +1,383 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var ts = require('typescript');
+var utils_messages = require('../../utils/messages.cjs');
+var utils_packageConfig = require('../../utils/package-config.cjs');
+var utils_projectFiles = require('../../utils/project-files.cjs');
+var utils_signalMembersMigration = require('../../utils/signal-members-migration.cjs');
+var utils_templateRefAccess = require('../../utils/template-ref-access.cjs');
+var utils_typescript = require('../../utils/typescript.cjs');
+var migrations_formFieldSignals_data = require('./data.cjs');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+require('../../utils/ast.cjs');
+
+const MIGRATION = 'form-field-signals';
+const TS_EXT = '.ts';
+const HTML_EXT = '.html';
+const STYLE_EXTS = ['.scss', '.css'];
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** Applies text-span edits to `content`, right-to-left, so earlier edits don't shift later offsets. */
+function applyEdits(content, edits) {
+    const sorted = [...edits].sort((a, b) => b.start - a.start || b.end - a.end);
+    let result = content;
+    for (const { start, end, text } of sorted) {
+        result = result.slice(0, start) + text + result.slice(end);
+    }
+    return result;
+}
+/**
+ * Whether a property access reads from a receiver of the target. The shared engine resolves the receiver at
+ * this exact position, so a nested declaration that shadows its name or a `function` that rebinds `this` is
+ * not followed. A signal query (`viewChild(KbqSelect)`) holds the instance behind a call of its own, which
+ * this pass does not reach.
+ */
+function onReceiver(node, sourceFile, scope) {
+    const receiver = utils_signalMembersMigration.resolveReceiver(node.expression, node, sourceFile, scope.receivers, scope.bindings);
+    return !!receiver && !receiver.signalQuery;
+}
+/** Collects edits for every read/write of a migrated member on a known receiver of `target`. */
+function collectAccessEdits(sourceFile, target, scope) {
+    const edits = [];
+    const visit = (node) => {
+        if (ts.isPropertyAccessExpression(node) &&
+            ts.isIdentifier(node.name) &&
+            target.signalMembers.includes(node.name.text) &&
+            onReceiver(node, sourceFile, scope)) {
+            utils_signalMembersMigration.classifyAccess(node, sourceFile, target.writableMembers, edits);
+        }
+        node.forEachChild(visit);
+    };
+    visit(sourceFile);
+    return edits;
+}
+const emptyWarnings = () => ({
+    queryListApi: new Set(),
+    nullability: new Set(),
+    readOnlyInputWrites: new Set(),
+    readOnlyQueryWrites: new Set(),
+    readOnlyStateWrites: new Set(),
+    writableWrites: new Set(),
+    removed: new Set()
+});
+/** Collects the members that the auto-fix can't fully migrate for one target. */
+function collectReceiverWarnings(sourceFile, target, scope) {
+    const warnings = emptyWarnings();
+    const visit = (node) => {
+        if (ts.isPropertyAccessExpression(node) && ts.isIdentifier(node.name)) {
+            const name = node.name.text;
+            const reachesReceiver = onReceiver(node, sourceFile, scope);
+            if (reachesReceiver && migrations_formFieldSignals_data.NULLABILITY_CHANGED_MEMBERS.includes(name)) {
+                warnings.nullability.add(name);
+            }
+            if (reachesReceiver && target.removedMembers?.includes(name)) {
+                warnings.removed.add(name);
+            }
+            // `target.signalMembers` scopes the flat name lists to the members this receiver actually owns.
+            if (reachesReceiver && target.signalMembers.includes(name) && utils_signalMembersMigration.isWriteTarget(node)) {
+                if (target.writableMembers.has(name)) {
+                    if (!utils_signalMembersMigration.isPlainAssignment(node))
+                        warnings.writableWrites.add(name);
+                }
+                else if (migrations_formFieldSignals_data.READ_ONLY_INPUT_MEMBERS.includes(name)) {
+                    warnings.readOnlyInputWrites.add(name);
+                }
+                else if (migrations_formFieldSignals_data.READ_ONLY_QUERY_MEMBERS.includes(name)) {
+                    warnings.readOnlyQueryWrites.add(name);
+                }
+                else if (migrations_formFieldSignals_data.READ_ONLY_STATE_MEMBERS.includes(name)) {
+                    warnings.readOnlyStateWrites.add(name);
+                }
+            }
+            // `formField.hint.changes` — the query member is migrated, the QueryList API below it is not.
+            if (migrations_formFieldSignals_data.QUERY_LIST_ONLY_API.includes(name) &&
+                ts.isPropertyAccessExpression(node.expression) &&
+                ts.isIdentifier(node.expression.name) &&
+                migrations_formFieldSignals_data.QUERY_LIST_MEMBERS.includes(node.expression.name.text) &&
+                onReceiver(node.expression, sourceFile, scope)) {
+                warnings.queryListApi.add(`${node.expression.name.text}.${name}`);
+            }
+        }
+        node.forEachChild(visit);
+    };
+    visit(sourceFile);
+    return warnings;
+}
+/** The members of a file's receivers that can't be auto-fixed, across every target. */
+function collectFileWarnings(filePath, content) {
+    const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const bindings = utils_signalMembersMigration.collectBindings(sourceFile);
+    const merged = emptyWarnings();
+    for (const target of migrations_formFieldSignals_data.TARGETS) {
+        const receivers = utils_signalMembersMigration.collectAllReceivers(sourceFile, target.types);
+        if (receivers.length === 0)
+            continue;
+        const warnings = collectReceiverWarnings(sourceFile, target, { receivers, bindings });
+        warnings.queryListApi.forEach((value) => merged.queryListApi.add(value));
+        warnings.nullability.forEach((value) => merged.nullability.add(value));
+        warnings.readOnlyInputWrites.forEach((value) => merged.readOnlyInputWrites.add(value));
+        warnings.readOnlyQueryWrites.forEach((value) => merged.readOnlyQueryWrites.add(value));
+        warnings.readOnlyStateWrites.forEach((value) => merged.readOnlyStateWrites.add(value));
+        warnings.writableWrites.forEach((value) => merged.writableWrites.add(value));
+        warnings.removed.forEach((value) => merged.removed.add(value));
+    }
+    return merged;
+}
+const emptyTemplateFindings = () => ({
+    readOnlyWrites: new Set(),
+    compoundWrites: new Set(),
+    removed: new Set()
+});
+/** Merges the findings of one template into `into`. */
+function mergeTemplateFindings(into, from) {
+    from.readOnlyWrites.forEach((member) => into.readOnlyWrites.add(member));
+    from.compoundWrites.forEach((member) => into.compoundWrites.add(member));
+    from.removed.forEach((member) => into.removed.add(member));
+}
+/** Adds the members a template reaches through a reference variable to the warnings. */
+function addTemplateFindings(warnings, findings) {
+    for (const name of findings.readOnlyWrites) {
+        if (migrations_formFieldSignals_data.READ_ONLY_INPUT_MEMBERS.includes(name))
+            warnings.readOnlyInputWrites.add(name);
+        else if (migrations_formFieldSignals_data.READ_ONLY_QUERY_MEMBERS.includes(name))
+            warnings.readOnlyQueryWrites.add(name);
+        else if (migrations_formFieldSignals_data.READ_ONLY_STATE_MEMBERS.includes(name))
+            warnings.readOnlyStateWrites.add(name);
+    }
+    findings.compoundWrites.forEach((member) => warnings.writableWrites.add(member));
+    findings.removed.forEach((member) => warnings.removed.add(member));
+    return warnings;
+}
+/** Emits precise, receiver-scoped warnings for the members that can't be auto-fixed. */
+function logReceiverWarnings(context, filePath, merged) {
+    if (merged.queryListApi.size > 0) {
+        utils_messages.logMessage(context.logger, [
+            `[${MIGRATION}] ${filePath}`,
+            `  These KbqFormField members are now a readonly array instead of a QueryList, so the QueryList API is`,
+            `  gone: ${[...merged.queryListApi].join(', ')}. The queries are signals — react to them with`,
+            `  \`computed()\`/\`effect()\` instead of \`.changes\`, and use \`[0]\`/\`.at(-1)\`/the array itself instead`,
+            `  of \`.first\`/\`.last\`/\`.toArray()\`.`
+        ]);
+    }
+    if (merged.nullability.size > 0) {
+        utils_messages.logMessage(context.logger, [
+            `[${MIGRATION}] ${filePath}`,
+            `  \`${[...merged.nullability].join('`, `')}\` now returns \`undefined\` instead of \`null\` when absent.`,
+            `  Strict comparisons against \`null\` no longer match — use a truthiness check or \`== null\`.`
+        ]);
+    }
+    if (merged.readOnlyInputWrites.size > 0) {
+        utils_messages.logMessage(context.logger, [
+            `[${MIGRATION}] ${filePath}`,
+            `  \`${[...merged.readOnlyInputWrites].join('`, `')}\` can no longer be assigned: they are read-only`,
+            `  signal inputs now. Drive them with a template binding (e.g. \`[fillTextOff]="…"\`) instead of an`,
+            `  assignment.`
+        ]);
+    }
+    if (merged.readOnlyQueryWrites.size > 0) {
+        utils_messages.logMessage(context.logger, [
+            `[${MIGRATION}] ${filePath}`,
+            `  \`${[...merged.readOnlyQueryWrites].join('`, `')}\` can no longer be assigned: they are read-only`,
+            `  signal content queries now. Project the content into the form field instead — code that assigned a`,
+            `  query result (usually a test faking the projected content) has to render the real component.`
+        ]);
+    }
+    if (merged.readOnlyStateWrites.size > 0) {
+        utils_messages.logMessage(context.logger, [`[${MIGRATION}] ${filePath}`, `  ${migrations_formFieldSignals_data.READ_ONLY_STATE_MESSAGE}`]);
+    }
+    if (merged.removed.size > 0) {
+        utils_messages.logMessage(context.logger, [`[${MIGRATION}] ${filePath}`, `  ${migrations_formFieldSignals_data.REMOVED_MEMBERS_MESSAGE}`]);
+    }
+    if (merged.writableWrites.size > 0) {
+        utils_messages.logMessage(context.logger, [
+            `[${MIGRATION}] ${filePath}`,
+            `  \`${[...merged.writableWrites].join('`, `')}\` are writable signals now, but only a plain \`=\` is`,
+            `  rewritten to \`.set()\`: a compound assignment, an increment, \`delete\` or a destructuring target`,
+            `  was left as it is. Write it with \`.set()\` or \`.update()\`.`
+        ]);
+    }
+}
+/** Pass A — rewrite value-safe programmatic reads of migrated members in TypeScript code. */
+function migrateTsExpressions(content, fileName) {
+    let result = content;
+    // One target at a time, re-parsing in between, so the edit offsets of each pass stay valid.
+    for (const target of migrations_formFieldSignals_data.TARGETS) {
+        const sourceFile = ts.createSourceFile(fileName, result, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+        const receivers = utils_signalMembersMigration.collectAllReceivers(sourceFile, target.types);
+        if (receivers.length === 0)
+            continue;
+        const edits = collectAccessEdits(sourceFile, target, { receivers, bindings: utils_signalMembersMigration.collectBindings(sourceFile) });
+        if (edits.length > 0)
+            result = applyEdits(result, edits);
+    }
+    return result;
+}
+/** Rewrites renamed attributes inside the opening tag of the elements that own them. */
+function rewriteAttributes(template) {
+    let content = template;
+    for (const { element, from, to } of migrations_formFieldSignals_data.attributeRewrites) {
+        const tagPattern = new RegExp(`<${escapeRegExp(element)}\\b[^>]*>`, 'g');
+        content = content.replace(tagPattern, (tag) => {
+            const attrPattern = new RegExp(`(\\s)${escapeRegExp(from)}(\\s*=)`, 'g');
+            return tag.replace(attrPattern, `$1${to}$2`);
+        });
+    }
+    return content;
+}
+/**
+ * Whether a `#ref` with `value` on an `element` names `target`: bare or naming the `exportAs` on one of its elements,
+ * or naming one of its directive `exportAs` names on any element.
+ */
+function refersTo({ elements, exportAs = [] }, element, value) {
+    if (Object.hasOwn(elements, element) && (!value || value === elements[element]))
+        return true;
+    return !!value && exportAs.includes(value);
+}
+/**
+ * Pass B (core) — parse a template, discover target refs, rewrite their reads, writes and renamed attributes, and
+ * find the removed members they reach.
+ */
+async function migrateTemplate(template) {
+    let content = rewriteAttributes(template);
+    const findings = emptyTemplateFindings();
+    const relevant = migrations_formFieldSignals_data.TARGETS.filter((target) => Object.keys(target.elements).some((element) => template.includes(element)) ||
+        target.exportAs?.some((exportAs) => template.includes(exportAs)));
+    if (relevant.length > 0) {
+        const parsed = await utils_typescript.parseTemplate(content);
+        if (parsed.tree) {
+            const { rootNodes } = parsed.tree;
+            const policies = new Map(relevant.map((target) => [
+                target,
+                {
+                    members: target.signalMembers,
+                    writable: target.writableMembers,
+                    reported: target.removedMembers
+                }
+            ]));
+            const result = utils_templateRefAccess.rewriteRefAccesses(content, rootNodes, (element, value) => {
+                const target = relevant.find((candidate) => refersTo(candidate, element.name, value));
+                return target && policies.get(target);
+            });
+            content = result.content;
+            result.readOnlyWrites.forEach((member) => findings.readOnlyWrites.add(member));
+            result.compoundWrites.forEach((member) => findings.compoundWrites.add(member));
+            result.reported.forEach((member) => findings.removed.add(member));
+        }
+    }
+    return { content, changed: content !== template, ...findings };
+}
+/** Pass B (inline) — rewrite target ref reads and writes inside inline component templates. */
+async function migrateInlineTemplates(content, fileName) {
+    const sourceFile = ts.createSourceFile(fileName, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const ranges = utils_typescript.collectInlineTemplateRanges(sourceFile).sort((a, b) => b.start - a.start);
+    const findings = emptyTemplateFindings();
+    let result = content;
+    for (const { start, end } of ranges) {
+        const outcome = await migrateTemplate(result.slice(start, end));
+        mergeTemplateFindings(findings, outcome);
+        if (outcome.changed) {
+            result = result.slice(0, start) + outcome.content + result.slice(end);
+        }
+    }
+    return { content: result, ...findings };
+}
+/** Pass C — the misspelled `_fiedset-theme.scss` was renamed. */
+function migrateStyles(content) {
+    let result = content;
+    for (const { from, to } of migrations_formFieldSignals_data.styleRewrites) {
+        result = result.split(from).join(to);
+    }
+    return result;
+}
+function logWarnings(context, filePath, content) {
+    for (const { pattern, message } of migrations_formFieldSignals_data.warnPatterns) {
+        if (new RegExp(pattern).test(content)) {
+            utils_messages.logMessage(context.logger, [`[${MIGRATION}] ${filePath}`, `  ${message}`]);
+        }
+    }
+}
+/**
+ * A file is a form-field consumer if it names one of the migrated symbols, imports the package, renders a
+ * control or names the `exportAs` of a directive one: a component that imports only `KbqInputModule` names no type.
+ */
+function referencesFormField(content) {
+    return (migrations_formFieldSignals_data.TARGETS.some((target) => target.exportAs?.some((name) => content.includes(name))) ||
+        /\bKbq(FormField|Hint|Error|ReactivePasswordHint|Cleaner|PasswordToggle|Stepper|Trim|A11yLocaleConfiguration)\b/.test(content) ||
+        /\b(mixinColor|CanColorCtor|KBQ_FORM_FIELD_REF|kbqA11yLocaleConfigurationProvider)\b/.test(content) ||
+        /\bKbq(Select|TreeSelect|TimezoneSelect|TagList|TagInput|Input|InputPassword|Textarea|Timepicker|DatepickerInput|FormFieldControl|ErrorStateTracker|IconErrorStateContext)\b/.test(content) ||
+        /\b(mixinErrorState|CanUpdateErrorState|CanUpdateErrorStateCtor|kbqIconErrorStateContextFactoryProvider)\b/.test(content) ||
+        content.includes('@koobiq/components/form-field') ||
+        content.includes('kbq-form-field') ||
+        content.includes('kbq-cleaner') ||
+        /<kbq-(select|tree-select|timezone-select|tag-list)\b/.test(content));
+}
+function formFieldSignals(options) {
+    return async (tree, context) => {
+        const { project } = options;
+        // `ng update` invokes migrations with no options at all, and migrations.json declares no schema, so the
+        // schema default never reaches us — applying the fix is the intended behaviour there.
+        const fix = options.fix ?? true;
+        const projectDefinition = await utils_packageConfig.setupOptions(project, tree);
+        const root = projectDefinition?.root ?? '';
+        const rootDir = root ? tree.getDir(root) : tree.root;
+        const tsPaths = [];
+        const htmlPaths = [];
+        const stylePaths = [];
+        utils_projectFiles.visitProjectFiles(rootDir, (filePath) => {
+            if (filePath.endsWith(TS_EXT))
+                tsPaths.push(filePath);
+            else if (filePath.endsWith(HTML_EXT))
+                htmlPaths.push(filePath);
+            else if (STYLE_EXTS.some((ext) => filePath.endsWith(ext)))
+                stylePaths.push(filePath);
+        });
+        let touched = 0;
+        const commit = (filePath, original, updated) => {
+            if (updated === original)
+                return;
+            touched++;
+            if (fix) {
+                tree.overwrite(filePath, updated);
+            }
+            else {
+                utils_messages.logMessage(context.logger, [`[${MIGRATION}] would update ${filePath} (run with --fix to apply)`]);
+            }
+        };
+        for (const filePath of tsPaths) {
+            const original = tree.read(filePath)?.toString();
+            if (!original || !referencesFormField(original))
+                continue;
+            logWarnings(context, filePath, original);
+            const warnings = collectFileWarnings(filePath, original);
+            const inline = await migrateInlineTemplates(migrateTsExpressions(original, filePath), filePath);
+            logReceiverWarnings(context, filePath, addTemplateFindings(warnings, inline));
+            commit(filePath, original, inline.content);
+        }
+        for (const filePath of htmlPaths) {
+            const original = tree.read(filePath)?.toString();
+            if (!original)
+                continue;
+            logWarnings(context, filePath, original);
+            const outcome = await migrateTemplate(original);
+            logReceiverWarnings(context, filePath, addTemplateFindings(emptyWarnings(), outcome));
+            if (outcome.changed)
+                commit(filePath, original, outcome.content);
+        }
+        for (const filePath of stylePaths) {
+            const original = tree.read(filePath)?.toString();
+            if (!original)
+                continue;
+            commit(filePath, original, migrateStyles(original));
+        }
+        utils_messages.logMessage(context.logger, [
+            `[${MIGRATION}] processed tree under "${root || '<workspace root>'}", ` +
+                `${fix ? 'updated' : 'would update'} ${touched} file(s).`
+        ]);
+    };
+}
+
+exports.default = formFieldSignals;

package/schematics/migrations/form-field-signals/schema.json

@@ -0,0 +1,20 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-form-field-signals",
+    "title": "Koobiq components form field signals migration",
+    "type": "object",
+    "properties": {
+        "project": {
+            "type": "string",
+            "description": "Name of the project to migrate. If omitted, the migration runs over the whole tree.",
+            "$default": {
+                "$source": "projectName"
+            }
+        },
+        "fix": {
+            "type": "boolean",
+            "default": true,
+            "description": "When true, applies all auto-fix replacements. When false, prints what would change without writing."
+        }
+    }
+}

package/schematics/migrations/icon-semantics-and-api/README.md

@@ -0,0 +1,65 @@
+# icon-semantics-and-api
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21`
+(registered for `21.0.0-0`). Reports the icon call sites the review reaches. It never writes to the
+tree.
+
+## Background
+
+The review gave the three components the semantics they never had, and closed the members that only
+recorded an internal decision.
+
+| Change                                | Before                    | After                                                    |
+| ------------------------------------- | ------------------------- | -------------------------------------------------------- |
+| `<i kbq-icon>`, `<i kbq-icon-item>`   | in the accessibility tree | `aria-hidden="true"` by default                          |
+| `kbq-icon-button` on a non-`<button>` | focusable, no semantics   | `role="button"`, `aria-disabled`; no keyboard activation |
+| `KbqIcon.small`                       | published input           | removed                                                  |
+| `KbqIcon.name`                        | `'KbqIcon'` string        | `appliesMaxHeight` boolean                               |
+| `KbqIconButton.tabindex`              | `any`                     | `number \| null`                                         |
+| `iconName`                            | `string`                  | `string \| undefined`                                    |
+
+`aria-hidden` deserves a note. An icon carries no text, and in nearly every place the library and its
+consumers use one it repeats a label that is already in the button, the link or the row beside it —
+so hidden is the right default and the hand-written `aria-hidden="true"` attributes on icons became
+redundant. An icon that is the only carrier of its meaning has to say so:
+
+```html
+<i kbq-icon="kbq-triangle-exclamation_16" role="img" aria-hidden="false" aria-label="Error"></i>
+```
+
+## What it does _not_ do
+
+Nothing is rewritten. Whether an icon is decorative and what an icon button should be called are both
+decisions the schematic cannot make. `small` on an icon button is rewritten to `size` by `v21-upgrade`,
+which also reports the uses it leaves, so this migration does not report it.
+
+| Pattern                                            | Manual migration                                                    |
+| -------------------------------------------------- | ------------------------------------------------------------------- |
+| `small` on a `[kbq-icon]` or a `[kbq-icon-item]`   | Drop it — nothing ever read it                                      |
+| `(click)` and no `(keydown…)` on a non-button host | Bind `(keydown.enter)` and `(keydown.space)`, or use a `<button>`   |
+| `tabindex` on an icon button, or written in code   | Pass a number (a numeric string is still transformed in a template) |
+| `override name` in a `KbqIcon` subclass            | Override the protected `appliesMaxHeight` instead                   |
+
+## Notes with no call site to point at
+
+- The SVG resolution no longer stops on the first name that does not resolve — which the documented
+  font-icon default guarantees on the very first frame. A stale `<svg>` is removed on the fallback
+  path and the inline `max-height` is cleared as well as set, so an element whose `[kbq-icon]` changes
+  renders the icon it was asked for at the size it was asked for.
+- `autoColor` takes effect when it is turned on after init and lets go of the error color when it is
+  turned off.
+- The `--kbq-icon-*-color` tokens are no longer declared on `.kbq-icon`; they are consumed with their
+  design token as the `var()` fallback, so a container can re-theme the icons inside it. A declaration
+  on `.kbq-icon` sat on the element the value is used on and beat everything inherited. Reading one
+  back with `getComputedStyle` now returns an empty string.
+- `KbqIconRegistry` looks sprite symbols up by id rather than through a `'#' + name` selector that a
+  name starting with a digit made invalid.
+- `kbqIconsDictProvider` maps names to URLs. Its `<`-prefixed inline branch is passed through
+  Angular's HTML sanitizer, which drops `<svg>` wholesale; register inline icons through
+  `KbqIconRegistry.addSvgIconLiteral()` with `bypassSecurityTrustHtml` instead.
+
+## Running it manually
+
+```bash
+ng g @koobiq/components:icon-semantics-and-api --project "<your project>"
+```

package/schematics/migrations/icon-semantics-and-api/data.cjs

@@ -0,0 +1,97 @@
+'use strict';
+
+var utils_tagPatterns = require('../../utils/tag-patterns.cjs');
+
+/**
+ * Data for the `icon-semantics-and-api` migration.
+ *
+ * The icon review gave the three components the semantics they never had and closed the members that
+ * only documented an internal decision:
+ *
+ * - `<i kbq-icon>` renders `aria-hidden="true"` by default. A meaningful icon opts out with
+ *   `aria-hidden="false"` and then supplies its own `role="img"` and `aria-label`.
+ * - `kbq-icon-button` on anything but a native `<button>` gets `role="button"` and `aria-disabled`, and
+ *   warns in dev mode when it has no accessible name. It does not activate itself from the keyboard.
+ * - `KbqIcon.small` is removed — it was published but read by nothing.
+ * - `KbqIcon.name`, the string that stood in for an `instanceof`, is replaced by the protected
+ *   `appliesMaxHeight` flag.
+ * - `KbqIconButton.tabindex` is `number | null` instead of `any`, and `iconName` is `string | undefined`.
+ *
+ * Warn-only. Whether an icon is decorative and what an icon button should be called are both decisions
+ * the schematic cannot make. `small` on an icon button is `v21-upgrade`'s: it rewrites it to `size`.
+ */
+/** Import specifier that marks a file as an icon consumer. */
+const ICON_PACKAGE = '@koobiq/components/icon';
+/** Identifier and attribute shapes that mark a consumer without an import. */
+const ICON_TYPE = String.raw `\bKbqIcon\w*\b|\bkbq-icon(?:-button|-item)?\b`;
+const ICON_OR_ITEM_ATTRIBUTE = String.raw `[\s\[]kbq-icon(?:-item)?(?![\w-])`;
+const ICON_BUTTON_ATTRIBUTE = String.raw `[\s\[]kbq-icon-button(?![\w-])`;
+/** An opening tag that carries `attribute`, read up to the point the rest of the pattern continues from. */
+const tagWith = (attribute) => String.raw `<[a-zA-Z][\w-]*(?=${utils_tagPatterns.TAG_BODY}*${attribute})${utils_tagPatterns.TAG_BODY}*`;
+const warnPatterns = [
+    {
+        // A plain icon or an icon item only: `small` on an icon button is rewritten by `v21-upgrade`.
+        anchor: ICON_OR_ITEM_ATTRIBUTE,
+        pattern: String.raw `${tagWith(ICON_OR_ITEM_ATTRIBUTE)}[\s\[]small[\]\s=/>]`,
+        message: 'KbqIcon.small was removed, and with it the input KbqIconItem inherited. It was published but read ' +
+            'by nothing — not by the host block, not by icon.scss, not by _icon-theme.scss — so dropping the ' +
+            'binding from a [kbq-icon] or a [kbq-icon-item] changes nothing.'
+    },
+    {
+        // A host the browser does not activate from the keyboard on its own: not a <button>, an <input> or an <a>.
+        anchor: ICON_BUTTON_ATTRIBUTE,
+        pattern: String.raw `<(?!(?:button|input|a)(?![\w-]))[a-zA-Z][\w-]*(?=${utils_tagPatterns.TAG_BODY}*${ICON_BUTTON_ATTRIBUTE})` +
+            String.raw `(?=${utils_tagPatterns.TAG_BODY}*\s\(click\))(?!${utils_tagPatterns.TAG_BODY}*\s\(keydown)`,
+        message: 'kbq-icon-button on a host that is not a native <button> is announced as a button now — ' +
+            'role="button" and aria-disabled — but it does not activate itself from Enter or Space, and this ' +
+            'one handles (click) only. Bind (keydown.enter) and (keydown.space) to the same handler, calling ' +
+            'preventDefault() on Space so the page does not scroll, or put the icon button on a <button>.'
+    },
+    {
+        anchor: ICON_BUTTON_ATTRIBUTE,
+        pattern: String.raw `${tagWith(ICON_BUTTON_ATTRIBUTE)}[\s\[]tabindex[\]\s=/>]`,
+        message: 'KbqIconButton.tabindex is number | null instead of any. A template binding still takes a number ' +
+            'or a numeric string, but a value that does not parse as a number renders no tabindex instead of ' +
+            'tabindex="NaN".'
+    },
+    {
+        anchor: String.raw `\bKbqIconButton\b`,
+        pattern: String.raw `\.tabindex\s*=(?!=)`,
+        message: 'KbqIconButton.tabindex is number | null instead of any: code that writes anything else to it no ' +
+            'longer type-checks.'
+    },
+    {
+        anchor: String.raw `\bKbqIcon\w*\b`,
+        // Only the `override` form. `.name` is far too common a property — `file.name`, `error.name`,
+        // `control.name` — and the anchor is any KbqIcon identifier in the file, so matching a bare
+        // member access reported the marker for code that never had anything to do with it.
+        pattern: String.raw `\boverride\s+name\s*(?:=(?!=)|[:;])`,
+        message: 'KbqIcon.name — the protected string that stood in for an instanceof and decided whether the ' +
+            'inline max-height is written — is replaced by the protected `appliesMaxHeight` boolean, which ' +
+            'a subclass overrides. Nothing outside the hierarchy could read it.'
+    }
+];
+/** Printed once per project, after the per-file reports. */
+const SUMMARY = [
+    '  <i kbq-icon> and <i kbq-icon-item> are aria-hidden="true" by default. That is right where the icon ' +
+        'repeats a label that is already there; an icon that carries meaning on its own needs ' +
+        'aria-hidden="false" plus role="img" and an aria-label. kbq-icon-button is not hidden by default.',
+    '  kbq-icon-button warns in dev mode when it has neither aria-label nor aria-labelledby: it renders ' +
+        'a glyph and has no accessible name at all without one (AXE button-name). On a host that is not a ' +
+        'native <button> it adds role="button" and aria-disabled, and leaves Enter and Space to the consumer.',
+    '  The --kbq-icon-*-color tokens are no longer declared on .kbq-icon. They are consumed with their ' +
+        'design token as the var() fallback instead, so a container can finally re-theme the icons inside ' +
+        'it — a declaration on .kbq-icon sat on the element the value is used on and beat everything ' +
+        'inherited. Reading one back with getComputedStyle now returns an empty string.',
+    '  The SVG resolution no longer dies on the first name that does not resolve, which the default ' +
+        'font-icon setup guarantees. A stale <svg> is removed on the fallback path and the inline ' +
+        'max-height is cleared as well as set, so an element whose [kbq-icon] changes renders the icon it ' +
+        'was asked for.',
+    '  KbqIconRegistry looks sprite symbols up by id rather than through a "#" + name selector that a ' +
+        'name starting with a digit made invalid.'
+];
+
+exports.ICON_PACKAGE = ICON_PACKAGE;
+exports.ICON_TYPE = ICON_TYPE;
+exports.SUMMARY = SUMMARY;
+exports.warnPatterns = warnPatterns;

package/schematics/migrations/icon-semantics-and-api/index.cjs

@@ -0,0 +1,65 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var utils_messages = require('../../utils/messages.cjs');
+var utils_packageConfig = require('../../utils/package-config.cjs');
+var utils_projectFiles = require('../../utils/project-files.cjs');
+var migrations_iconSemanticsAndApi_data = require('./data.cjs');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+require('../../utils/tag-patterns.cjs');
+
+const LABEL = '[icon-semantics-and-api]';
+const EXTENSIONS = ['.ts', '.html'];
+// Compiled once rather than per file. None carries the `g` flag, so a shared instance holds no `lastIndex`.
+const ICON_TYPE_REGEX = new RegExp(migrations_iconSemanticsAndApi_data.ICON_TYPE);
+const COMPILED_WARN_PATTERNS = migrations_iconSemanticsAndApi_data.warnPatterns.map(({ anchor, pattern, message }) => ({
+    anchor: new RegExp(anchor),
+    pattern: new RegExp(pattern),
+    message
+}));
+/** A file is an icon consumer if it imports the package, names a component, or renders one. */
+function referencesIcon(content) {
+    return content.includes(migrations_iconSemanticsAndApi_data.ICON_PACKAGE) || ICON_TYPE_REGEX.test(content);
+}
+/**
+ * Reports the icon call sites the review reaches: the removed `KbqIcon.small`, the icon buttons on a host
+ * that is not a native `<button>` that handle a click but no key, the retyped `tabindex` and the replaced
+ * `name` marker. Never writes: whether an icon is decorative and what an icon button is called are both
+ * decisions.
+ */
+function iconSemanticsAndApi(options) {
+    return async (tree, context) => {
+        const { project } = options;
+        const projectDefinition = await utils_packageConfig.setupOptions(project, tree);
+        const root = projectDefinition?.root ?? '';
+        const rootDir = root ? tree.getDir(root) : tree.root;
+        let consumers = 0;
+        let reported = 0;
+        utils_projectFiles.visitProjectFiles(rootDir, (filePath, entry) => {
+            if (!EXTENSIONS.some((extension) => filePath.endsWith(extension)))
+                return;
+            const content = entry.content.toString();
+            if (!content || !referencesIcon(content))
+                return;
+            consumers++;
+            for (const { anchor, pattern, message } of COMPILED_WARN_PATTERNS) {
+                if (!anchor.test(content) || !pattern.test(content))
+                    continue;
+                reported++;
+                utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${message}`]);
+            }
+        });
+        // Nothing here renders an icon, so the summary would only be noise.
+        if (consumers === 0)
+            return;
+        utils_messages.logMessage(context.logger, [
+            `${LABEL} processed icons under "${root || '<workspace root>'}", ` +
+                `${consumers} file(s) reference the component, ${reported} call site(s) reported.`,
+            ...migrations_iconSemanticsAndApi_data.SUMMARY
+        ]);
+    };
+}
+
+exports.default = iconSemanticsAndApi;

package/schematics/migrations/icon-semantics-and-api/schema.json

@@ -0,0 +1,15 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-icon-semantics-and-api",
+    "title": "Koobiq components icon review migration",
+    "type": "object",
+    "properties": {
+        "project": {
+            "type": "string",
+            "description": "Name of the project to inspect. If omitted, the migration runs over the whole tree.",
+            "$default": {
+                "$source": "projectName"
+            }
+        }
+    }
+}