@koobiq/components 20.4.2 → 21.0.1

package/schematics/migrations/app-switcher-signals/data.cjs

@@ -0,0 +1,136 @@
+'use strict';
+
+/**
+ * Data for the `app-switcher-signals` migration.
+ *
+ * `KbqAppSwitcherTrigger` moved `selectedApp` / `selectedSite` from a plain `@Input()` (plus a matching
+ * `output()`) to `model()`, and the review that came with it removed several members that never did anything.
+ *
+ * Only `selectedApp` is a value-preserving property → signal change, so only it is auto-fixed. `selectedSite`
+ * also changed *what it returns* — the old getter handed back the site with its applications already grouped,
+ * the model returns the value that was passed in — so a mechanical `()` would silently change the value and it
+ * is surfaced as a warning instead.
+ *
+ * Template *bindings* (`[selectedApp]`, `[(selectedSite)]`, `(selectedAppChange)`) keep working; only
+ * programmatic access and reads through a `#ref="kbqAppSwitcher"` break.
+ */
+/** TypeScript type annotation that marks a receiver as the app-switcher trigger. */
+const TRIGGER_TYPE = 'KbqAppSwitcherTrigger';
+/** `exportAs` of the trigger: a `#ref="kbqAppSwitcher"` in a template points at one. */
+const TRIGGER_EXPORT_AS = 'kbqAppSwitcher';
+/** Members whose value is unchanged: a read becomes a call, a write becomes `.set(…)`. Auto-fixed. */
+const SIGNAL_MEMBERS = ['selectedApp'];
+/** Of those, the ones backed by `model()`, so a write can be rewritten rather than left to the compiler. */
+const WRITABLE_MEMBERS = new Set(['selectedApp']);
+/**
+ * Methods of the signal/model API. A member access followed by one of these is already migrated — or is the
+ * result of the rename below — so no `()` is appended. This is what makes the migration idempotent.
+ */
+const SIGNAL_API_METHODS = new Set(['set', 'update', 'asReadonly', 'subscribe']);
+/**
+ * Outputs folded into their model. `ModelSignal` implements `OutputRef`, so `.subscribe(fn)` keeps the exact
+ * same signature and the access can simply be renamed; `.emit(v)` has no equivalent and is warned about.
+ */
+const OUTPUT_TO_MODEL = new Map([['selectedAppChange', 'selectedApp']]);
+/**
+ * Members accessed on a trigger that changed their value semantics or disappeared. Reported with the file they
+ * were found in; never rewritten.
+ */
+const MANUAL_MEMBERS = new Map([
+    [
+        'selectedSite',
+        '`selectedSite` is now a `model()`, and its value changed: the old getter returned the site with its ' +
+            'applications already grouped, the model returns the value that was passed in. Read ' +
+            '`trigger.selectedSite()` for the raw site or `trigger.parsedSelectedSite()` for the grouped one, ' +
+            'and write with `trigger.selectedSite.set(…)`.'
+    ],
+    [
+        'selectedSiteChange',
+        '`selectedSiteChange` is now the implicit output of the `selectedSite` model: subscribe with ' +
+            '`trigger.selectedSite.subscribe(…)`. It emits the raw site, not the grouped one the old output ' +
+            'carried. Replace `.emit(v)` with `trigger.selectedSite.set(v)`.'
+    ],
+    [
+        'selectedAppChange',
+        '`selectedAppChange` is now the implicit output of the `selectedApp` model: subscribe with ' +
+            '`trigger.selectedApp.subscribe(…)` and replace `.emit(v)` with `trigger.selectedApp.set(v)`.'
+    ],
+    [
+        'header',
+        '`KbqAppSwitcherTrigger.header` was removed — the popup never rendered a header, so the value was ' +
+            'pushed into the overlay and dropped. Delete the usage.'
+    ],
+    [
+        'footer',
+        '`KbqAppSwitcherTrigger.footer` was removed — the popup never rendered a footer, so the value was ' +
+            'pushed into the overlay and dropped. Delete the usage.'
+    ]
+]);
+/**
+ * Warnings for `.ts` files. Checked against the post-fix content, so an auto-fixed usage does not also produce
+ * a "manual migration required" note. Only evaluated for files that reference the app-switcher, which is what
+ * keeps the looser patterns (`getIcon(`, `icon:`) scoped.
+ */
+const tsWarnPatterns = [
+    {
+        pattern: '\\b(?:isTrapFocus|updateTrapFocus)\\b',
+        message: '`KbqAppSwitcherComponent.isTrapFocus` / `updateTrapFocus()` were removed: the template never ' +
+            'bound `[cdkTrapFocus]`, so neither did anything. Delete the usage.'
+    },
+    {
+        // Protected, so only a subclass reaches them.
+        pattern: '\\b(?:this|super)\\.active(?:Site|App)\\b',
+        message: '`KbqAppSwitcherComponent.activeSite` / `activeApp` were removed: each flyout reads its site and app ' +
+            'from the context of its `kbqDropdownContent` template, which `kbqDropdownTriggerData` fills. Read ' +
+            'them there.'
+    },
+    {
+        pattern: '\\bgetIcon\\s*\\(',
+        message: '`KbqAppSwitcherDropdownApp.getIcon()` was removed. Inline `icon` markup is now sanitized by ' +
+            '`KbqAppSwitcherIconSanitizer` and rendered by the component itself — drop the call.'
+    },
+    {
+        pattern: '\\bKbqAppSwitcherListItem\\b',
+        message: '`KbqAppSwitcherListItem.collapsed` is now a `model()`: read it as `collapsed()` and write it as ' +
+            '`collapsed.set(v)`. Its `app` input became `input.required`, so it must be bound.'
+    },
+    {
+        pattern: '\\bKbqAppSwitcherDropdown(?:App|Site)\\b',
+        message: 'The `app` / `site` inputs of `KbqAppSwitcherDropdownApp` / `KbqAppSwitcherDropdownSite` are now ' +
+            '`input.required` signals and must be bound.'
+    },
+    {
+        pattern: '\\bicon\\s*:',
+        message: 'Inline `icon` SVG markup is now sanitized against a strict SVG allow-list before it is rendered: ' +
+            '`<script>`, `<style>`, `<foreignObject>`, HTML elements, every `on*` handler and any external ' +
+            'reference are removed, and markup that changes shape when re-parsed is dropped entirely (the row ' +
+            'then falls back to `iconSrc`). Check icons that rely on any of those.'
+    }
+];
+/**
+ * Behaviour changes that no usage pattern can point at, printed once per run.
+ */
+const BEHAVIOUR_NOTE = [
+    'Behaviour changes with no call site to migrate:',
+    '- KbqAppSwitcherModule no longer provides FocusTrapFactory / FOCUS_TRAP_INERT_STRATEGY. The app-switcher',
+    '  never rendered a focus trap, and those providers are injector-wide: they disabled the CDK inert',
+    '  strategy for every other focus trap in the same scope. If your app relied on that, provide them',
+    '  explicitly where they are actually needed.',
+    '- defaultGroupBy now identifies a synthetic group by its type name instead of an empty `id`.',
+    '- The popup hides itself when it scrolls out of an ancestor marked `kbq-hide-nested-popup`. The guard',
+    '  that used to suppress this never passed, so the behaviour is effectively new.'
+];
+/** Reported when a template names the trigger but cannot be parsed, so nothing was rewritten in it. */
+const UNPARSEABLE_TEMPLATE_MESSAGE = 'This template references the app-switcher but could not be parsed, so it was left untouched. ' +
+    'Migrate reads through its template reference variable by hand.';
+
+exports.BEHAVIOUR_NOTE = BEHAVIOUR_NOTE;
+exports.MANUAL_MEMBERS = MANUAL_MEMBERS;
+exports.OUTPUT_TO_MODEL = OUTPUT_TO_MODEL;
+exports.SIGNAL_API_METHODS = SIGNAL_API_METHODS;
+exports.SIGNAL_MEMBERS = SIGNAL_MEMBERS;
+exports.TRIGGER_EXPORT_AS = TRIGGER_EXPORT_AS;
+exports.TRIGGER_TYPE = TRIGGER_TYPE;
+exports.UNPARSEABLE_TEMPLATE_MESSAGE = UNPARSEABLE_TEMPLATE_MESSAGE;
+exports.WRITABLE_MEMBERS = WRITABLE_MEMBERS;
+exports.tsWarnPatterns = tsWarnPatterns;

package/schematics/migrations/app-switcher-signals/index.cjs

@@ -0,0 +1,366 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var ts = require('typescript');
+var utils_ast = require('../../utils/ast.cjs');
+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_typescript = require('../../utils/typescript.cjs');
+var migrations_appSwitcherSignals_data = require('./data.cjs');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+const TS_EXT = '.ts';
+const HTML_EXT = '.html';
+const LABEL = '[app-switcher-signals]';
+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;
+}
+const isFunctionLike = (node) => ts.isFunctionDeclaration(node) ||
+    ts.isMethodDeclaration(node) ||
+    ts.isConstructorDeclaration(node) ||
+    ts.isArrowFunction(node) ||
+    ts.isFunctionExpression(node) ||
+    ts.isGetAccessorDeclaration(node) ||
+    ts.isSetAccessorDeclaration(node);
+/** Walks up from `node` to the nearest ancestor matching `predicate`. */
+function findAncestor(node, predicate) {
+    let current = node.parent;
+    while (current) {
+        if (predicate(current))
+            return current;
+        current = current.parent;
+    }
+    return undefined;
+}
+/** Whether a type annotation refers to the trigger (`KbqAppSwitcherTrigger`). */
+function isTriggerType(type) {
+    return (!!type && ts.isTypeReferenceNode(type) && ts.isIdentifier(type.typeName) && type.typeName.text === migrations_appSwitcherSignals_data.TRIGGER_TYPE);
+}
+const FIELD_MODIFIERS = new Set([
+    ts.SyntaxKind.PrivateKeyword,
+    ts.SyntaxKind.PublicKeyword,
+    ts.SyntaxKind.ProtectedKeyword,
+    ts.SyntaxKind.ReadonlyKeyword
+]);
+/**
+ * Collects the receivers whose static type is the trigger, by explicit annotation only (no cross-package type
+ * resolution): method/function params, class fields (incl. `@ViewChild(KbqAppSwitcherTrigger) x:
+ * KbqAppSwitcherTrigger` and constructor parameter-properties) and typed locals.
+ */
+function collectReceivers(sourceFile) {
+    const receivers = [];
+    const add = (text, scope) => receivers.push({ text, start: scope.getStart(sourceFile), end: scope.getEnd() });
+    const visit = (node) => {
+        if (ts.isParameter(node) && ts.isIdentifier(node.name) && isTriggerType(node.type)) {
+            add(node.name.text, findAncestor(node, isFunctionLike) ?? sourceFile);
+            // A constructor parameter-property is also a class field, reachable as `this.<name>`.
+            if (node.modifiers?.some((modifier) => FIELD_MODIFIERS.has(modifier.kind))) {
+                const owner = findAncestor(node, ts.isClassDeclaration);
+                if (owner)
+                    add(`this.${node.name.text}`, owner);
+            }
+        }
+        else if (ts.isPropertyDeclaration(node) && ts.isIdentifier(node.name) && isTriggerType(node.type)) {
+            const owner = findAncestor(node, ts.isClassDeclaration);
+            if (owner)
+                add(`this.${node.name.text}`, owner);
+        }
+        else if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && isTriggerType(node.type)) {
+            add(node.name.text, findAncestor(node, isFunctionLike) ?? sourceFile);
+        }
+        node.forEachChild(visit);
+    };
+    visit(sourceFile);
+    return receivers;
+}
+/** Whether a property access on a receiver is within one of the receiver's scopes. */
+function inReceiverScope(node, sourceFile, receivers) {
+    const receiverText = node.expression.getText(sourceFile);
+    const start = node.getStart(sourceFile);
+    const end = node.getEnd();
+    return receivers.some((r) => r.text === receiverText && start >= r.start && end <= r.end);
+}
+/** The signal/model method a member access is immediately followed by, if any (`x.selectedApp.set`). */
+function followedByMethod(node) {
+    const parent = node.parent;
+    return ts.isPropertyAccessExpression(parent) && parent.expression === node ? parent.name.text : undefined;
+}
+/** Classifies a matched property access of a value-safe signal member and appends the resulting edit(s). */
+function classifySignalAccess(node, sourceFile, edits) {
+    const parent = node.parent;
+    // Already migrated: `x.selectedApp()` (call) or `x.selectedApp.set(…)` / `.subscribe(…)` — leave alone.
+    if (ts.isCallExpression(parent) && parent.expression === node)
+        return;
+    const method = followedByMethod(node);
+    if (method && migrations_appSwitcherSignals_data.SIGNAL_API_METHODS.has(method))
+        return;
+    // Write target: `x.selectedApp = RHS` → `x.selectedApp.set(RHS)`.
+    if (ts.isBinaryExpression(parent) &&
+        parent.left === node &&
+        parent.operatorToken.kind === ts.SyntaxKind.EqualsToken) {
+        if (migrations_appSwitcherSignals_data.WRITABLE_MEMBERS.has(node.name.text)) {
+            const rhs = parent.right;
+            edits.push({ start: node.getEnd(), end: rhs.getStart(sourceFile), text: '.set(' });
+            edits.push({ start: rhs.getEnd(), end: rhs.getEnd(), text: ')' });
+        }
+        return;
+    }
+    // Read (incl. optional chain `x?.selectedApp`): append `()`.
+    edits.push({ start: node.getEnd(), end: node.getEnd(), text: '()' });
+}
+/**
+ * Renames an output that became the implicit output of a model, but only where the two are interchangeable:
+ * `x.selectedAppChange.subscribe(fn)` → `x.selectedApp.subscribe(fn)`, because `ModelSignal` implements
+ * `OutputRef`. Anything else (notably `.emit(v)`) is left for the warning.
+ */
+function classifyOutputAccess(node, edits) {
+    const model = migrations_appSwitcherSignals_data.OUTPUT_TO_MODEL.get(node.name.text);
+    if (!model || followedByMethod(node) !== 'subscribe')
+        return;
+    edits.push({ start: node.name.getStart(node.getSourceFile()), end: node.name.getEnd(), text: model });
+}
+/** Collects edits for every access of a migratable member on a known trigger receiver. */
+function collectAccessEdits(sourceFile, receivers) {
+    const edits = [];
+    const visit = (node) => {
+        if (ts.isPropertyAccessExpression(node) &&
+            ts.isIdentifier(node.name) &&
+            inReceiverScope(node, sourceFile, receivers)) {
+            if (migrations_appSwitcherSignals_data.SIGNAL_MEMBERS.includes(node.name.text))
+                classifySignalAccess(node, sourceFile, edits);
+            else
+                classifyOutputAccess(node, edits);
+        }
+        node.forEachChild(visit);
+    };
+    visit(sourceFile);
+    return edits;
+}
+/** Pass A — rewrite value-safe programmatic accesses of trigger signal members in TypeScript code. */
+function migrateTsExpressions(content, fileName) {
+    const sourceFile = ts.createSourceFile(fileName, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const receivers = collectReceivers(sourceFile);
+    if (receivers.length === 0)
+        return content;
+    const edits = collectAccessEdits(sourceFile, receivers);
+    return edits.length > 0 ? applyEdits(content, edits) : content;
+}
+/** Members needing manual migration, found on a trigger receiver in TypeScript code. */
+function collectManualMembers(content, fileName) {
+    const sourceFile = ts.createSourceFile(fileName, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const receivers = collectReceivers(sourceFile);
+    const found = new Set();
+    if (receivers.length === 0)
+        return found;
+    const visit = (node) => {
+        if (ts.isPropertyAccessExpression(node) &&
+            ts.isIdentifier(node.name) &&
+            migrations_appSwitcherSignals_data.MANUAL_MEMBERS.has(node.name.text) &&
+            inReceiverScope(node, sourceFile, receivers)) {
+            found.add(node.name.text);
+        }
+        node.forEachChild(visit);
+    };
+    visit(sourceFile);
+    return found;
+}
+/** Collects template reference variable names exported as the trigger (`#ref="kbqAppSwitcher"`). */
+class TriggerRefCollector {
+    constructor() {
+        this.refs = new Set();
+    }
+    visitElement(element) {
+        for (const attr of element.attrs ?? []) {
+            if (typeof attr.name !== 'string' || attr.value !== migrations_appSwitcherSignals_data.TRIGGER_EXPORT_AS)
+                continue;
+            if (attr.name.startsWith('#'))
+                this.refs.add(attr.name.slice(1));
+            else if (attr.name.startsWith('ref-'))
+                this.refs.add(attr.name.slice(4));
+        }
+        this.visitChildren(element);
+    }
+    visitBlock(block) {
+        this.visitChildren(block);
+    }
+    visitChildren(node) {
+        for (const child of node.children ?? []) {
+            child.visit(this);
+        }
+    }
+    visitAttribute() { }
+    visitText() { }
+    visitComment() { }
+    visitExpansion() { }
+    visitExpansionCase() { }
+    visitBlockParameter() { }
+    visitLetDeclaration() { }
+}
+/**
+ * Matches `<ref>.<member>` where the access is neither already a call nor a signal-API call. `\b` after the
+ * member keeps `selectedApp` from matching inside `selectedAppChange`.
+ */
+function memberAccessPattern(ref, members) {
+    const methods = [...migrations_appSwitcherSignals_data.SIGNAL_API_METHODS].join('|');
+    return new RegExp(`\\b(${escapeRegExp(ref)})\\.(${members.join('|')})\\b(?!\\s*\\()(?!\\s*\\.\\s*(?:${methods})\\b)`, 'g');
+}
+/** Rewrites `ref.selectedApp` reads to `ref.selectedApp()` for the given refs. */
+function rewriteRefReads(template, refs) {
+    let content = template;
+    let changed = false;
+    for (const ref of refs) {
+        const next = content.replace(memberAccessPattern(ref, migrations_appSwitcherSignals_data.SIGNAL_MEMBERS), '$1.$2()');
+        if (next !== content) {
+            content = next;
+            changed = true;
+        }
+    }
+    return { content, changed };
+}
+/** Members needing manual migration, read through a trigger reference variable in a template. */
+function collectRefManualMembers(template, refs) {
+    const members = [...migrations_appSwitcherSignals_data.MANUAL_MEMBERS.keys()];
+    const found = new Set();
+    for (const ref of refs) {
+        // `\bref\.(member)\b` — a template can only read these, so no call/method exclusions are needed.
+        const pattern = new RegExp(`\\b${escapeRegExp(ref)}\\.(${members.join('|')})\\b`, 'g');
+        for (const match of template.matchAll(pattern)) {
+            found.add(match[1]);
+        }
+    }
+    return found;
+}
+const untouched = (template) => ({
+    content: template,
+    changed: false,
+    manual: new Set(),
+    unparseable: false
+});
+/** Pass B (core) — parse a template, discover trigger refs, rewrite their value-safe reads. */
+async function migrateTemplate(template) {
+    if (!template.includes(migrations_appSwitcherSignals_data.TRIGGER_EXPORT_AS))
+        return untouched(template);
+    const parsed = await utils_typescript.parseTemplate(template);
+    if (!parsed.tree)
+        return { ...untouched(template), unparseable: true };
+    const collector = new TriggerRefCollector();
+    utils_ast.visitAll(collector, parsed.tree.rootNodes);
+    if (collector.refs.size === 0)
+        return untouched(template);
+    const refs = [...collector.refs];
+    return { ...rewriteRefReads(template, refs), manual: collectRefManualMembers(template, refs), unparseable: false };
+}
+/** Pass B (inline) — rewrite trigger ref reads inside inline component templates. */
+async function migrateInlineTemplates(content, fileName) {
+    const sourceFile = ts.createSourceFile(fileName, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const manual = new Set();
+    let result = content;
+    let unparseable = false;
+    // Splice right-to-left so earlier offsets stay valid.
+    for (const { start, end } of utils_typescript.collectInlineTemplateRanges(sourceFile).sort((a, b) => b.start - a.start)) {
+        const migrated = await migrateTemplate(result.slice(start, end));
+        migrated.manual.forEach((member) => manual.add(member));
+        unparseable ||= migrated.unparseable;
+        if (migrated.changed) {
+            result = result.slice(0, start) + migrated.content + result.slice(end);
+        }
+    }
+    return { content: result, manual, unparseable };
+}
+function logPatternWarnings(context, filePath, content) {
+    for (const { pattern, message } of migrations_appSwitcherSignals_data.tsWarnPatterns) {
+        if (new RegExp(pattern).test(content)) {
+            utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${message}`]);
+        }
+    }
+}
+function logManualMembers(context, filePath, members) {
+    for (const member of members) {
+        utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${migrations_appSwitcherSignals_data.MANUAL_MEMBERS.get(member)}`]);
+    }
+}
+/** A `.ts` file is an app-switcher consumer if it names one of its symbols or imports the package. */
+function referencesAppSwitcher(content) {
+    return /\bKbqAppSwitcher\w*\b/.test(content) || content.includes('@koobiq/components/app-switcher');
+}
+function appSwitcherSignals(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 = [];
+        utils_projectFiles.visitProjectFiles(rootDir, (filePath) => {
+            if (filePath.endsWith(TS_EXT))
+                tsPaths.push(filePath);
+            else if (filePath.endsWith(HTML_EXT))
+                htmlPaths.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, [`${LABEL} would update ${filePath} (run with --fix to apply)`]);
+            }
+        };
+        for (const filePath of tsPaths) {
+            const original = tree.read(filePath)?.toString();
+            if (!original || !referencesAppSwitcher(original))
+                continue;
+            const withExpressions = migrateTsExpressions(original, filePath);
+            const inline = await migrateInlineTemplates(withExpressions, filePath);
+            const content = inline.content;
+            // Warn on what is left over, so an auto-fixed usage does not also produce a "manual migration
+            // required" note. In dry-run mode the fix is not written, so report against the original.
+            const reported = fix ? content : original;
+            logPatternWarnings(context, filePath, reported);
+            logManualMembers(context, filePath, collectManualMembers(reported, filePath));
+            logManualMembers(context, filePath, inline.manual);
+            if (inline.unparseable) {
+                utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${migrations_appSwitcherSignals_data.UNPARSEABLE_TEMPLATE_MESSAGE}`]);
+            }
+            commit(filePath, original, content);
+        }
+        for (const filePath of htmlPaths) {
+            const original = tree.read(filePath)?.toString();
+            if (!original)
+                continue;
+            const migrated = await migrateTemplate(original);
+            logManualMembers(context, filePath, migrated.manual);
+            if (migrated.unparseable) {
+                utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${migrations_appSwitcherSignals_data.UNPARSEABLE_TEMPLATE_MESSAGE}`]);
+            }
+            if (migrated.changed)
+                commit(filePath, original, migrated.content);
+        }
+        utils_messages.logMessage(context.logger, [
+            `${LABEL} processed tree under "${root || '<workspace root>'}", ` +
+                `${fix ? 'updated' : 'would update'} ${touched} file(s).`,
+            '',
+            ...migrations_appSwitcherSignals_data.BEHAVIOUR_NOTE
+        ]);
+    };
+}
+
+exports.default = appSwitcherSignals;

package/schematics/migrations/app-switcher-signals/schema.json

@@ -0,0 +1,20 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-app-switcher-signals",
+    "title": "Koobiq components app-switcher 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/autocomplete-panel-width-auto/README.md

@@ -16,13 +16,13 @@ lay out differently without any error.
 Usage for Angular Cli:
 
 ```shell
-ng g @koobiq/components:autocomplete-panel-width-auto --project <your project>
+ng g @koobiq/components:autocomplete-panel-width-auto --project "<your project>"
 ```
 
 Usage for Nx:
 
 ```shell
-nx g @koobiq/components:autocomplete-panel-width-auto --project <your project>
+nx g @koobiq/components:autocomplete-panel-width-auto --project "<your project>"
 ```
 
 ### Run locally

package/schematics/migrations/autocomplete-panel-width-auto/{index.js → index.cjs}

@@ -2,14 +2,15 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-var utils_angularParsing = require('../../utils/angular-parsing.js');
-var utils_packageConfig = require('../../utils/package-config.js');
-var utils_typescript = require('../../utils/typescript.js');
+var utils_angularParsing = require('../../utils/angular-parsing.cjs');
+var utils_packageConfig = require('../../utils/package-config.cjs');
+var utils_typescript = require('../../utils/typescript.cjs');
 require('typescript');
-require('../../utils/ast.js');
+require('../../utils/ast.cjs');
 require('@angular-devkit/schematics');
 require('@schematics/angular/utility');
-require('../../utils/messages.js');
+require('../../utils/messages.cjs');
+require('../../utils/project-files.cjs');
 
 const migrationData = {
     elementName: 'kbq-autocomplete',

package/schematics/migrations/autocomplete-signals/README.md

@@ -0,0 +1,92 @@
+# autocomplete-signals
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21` (registered for
+`21.0.0-0`). Migrates `KbqAutocomplete` and `KbqAutocompleteTrigger` consumers to the finished
+signal-based API.
+
+## Background
+
+Four accessor inputs and one write-target input survived the automated signal migration. `classList`
+was the odd one: declared `@Input('class')`, its setter accumulated class names into an object that
+the panel template binds, and cleared the host's `className` as a side effect. It is an internal
+`computed` now, fed by a `class` signal input — `class="..."` on `<kbq-autocomplete>` keeps working
+exactly as before.
+
+`isOpen` was asymmetric: `set isOpen(v)` stored a flag, `get isOpen()` returned that flag **and**
+`showPanel`. Writing `true` and reading it back returned `false` whenever the panel had no options.
+It is a `computed` now — `attached() && showPanel()` — with `attached` as the writable half the
+trigger owns.
+
+## What it rewrites
+
+| Before                               | After                                    |
+| ------------------------------------ | ---------------------------------------- |
+| `autocomplete.autoActiveFirstOption` | `autocomplete.autoActiveFirstOption()`   |
+| `autocomplete.openOnFocus`           | `autocomplete.openOnFocus()`             |
+| `autocomplete.showPanel` / `.isOpen` | `autocomplete.showPanel()` / `.isOpen()` |
+| `autocomplete.showPanel = v`         | `autocomplete.showPanel.set(v)`          |
+| `autocomplete.displayWith(value)`    | `autocomplete.displayWith()(value)`      |
+| `trigger.autocompleteDisabled`       | `trigger.autocompleteDisabled()`         |
+
+On receivers explicitly typed `KbqAutocomplete` or `KbqAutocompleteTrigger`, and through template
+reference variables — `#auto` on `<kbq-autocomplete>`, `#auto="kbqAutocomplete"` and
+`#t="kbqAutocompleteTrigger"` — in external and inline templates. Each reference only gets the members
+its own type owns, so `autocompleteDisabled` is rewritten on a trigger reference and nowhere else.
+Already-migrated reads are left alone, so the schematic is idempotent.
+
+`displayWith` is the one member whose value is a function, so the read and the invocation are separate
+calls: an existing `displayWith(value)` is a pre-migration invocation, not a migrated read.
+
+## What it does _not_ do
+
+| Pattern                                 | Manual migration                                                         |
+| --------------------------------------- | ------------------------------------------------------------------------ |
+| `.classList`                            | Set `class` on `<kbq-autocomplete>`; the classes still land on the panel |
+| `.isOpen = …`                           | `attached.set(…)` — but this is the trigger's own state                  |
+| `.displayWith = …` / `.openOnFocus = …` | These are `input()`s now; bind them in the template                      |
+| `viewChild(KbqAutocomplete)`            | The query is a signal too, so a read through it is a double call         |
+
+`@ViewChild(KbqAutocomplete) a: KbqAutocomplete` is a plain annotated field, so it is rewritten like
+any other receiver — `this.a.isOpen()`, a single call. Only the signal-query form needs the double
+call.
+
+## What it cannot see
+
+Receivers are found by explicit type annotation, with no cross-package type resolution. A non-null
+assertion, parentheses and an aliased import are seen through; a type named in a position that does
+not resolve to a single identifier — a union, an array, a `QueryList<…>`, a cast, a return type — is
+reported with its line number rather than rewritten, and so is `a['isOpen']` or
+`const { isOpen } = a`.
+
+Templates report rather than rewrite when they cannot be parsed, and skip a reference whose name a
+`@for` variable, an `@let` or another `#ref` also introduces. A reference is rewritten only inside the
+embedded view that declares it.
+
+## Notes with no call site to point at
+
+- **`autoActiveFirstOption`, `openOnFocus` and `kbqAutocompleteDisabled` are `booleanAttribute`
+  inputs.** For `autoActiveFirstOption` and `kbqAutocompleteDisabled` that matches the
+  `coerceBooleanProperty` they already used, so nothing changes. `openOnFocus` had no coercion at all:
+  a valueless attribute or `0` used to read as false and now means `true`, and `'false'` used to read
+  as true and now means `false`.
+- **Binding `[autoActiveFirstOption]` overrides `KBQ_AUTOCOMPLETE_DEFAULT_OPTIONS`,** even when the
+  bound value is `undefined` — as it did before, because the old setter coerced every binding write.
+  The token default only applies to an input nobody bound, so leave it unbound to let the token decide.
+- **Generated panel ids come from the CDK `_IdGenerator`.** With the default `APP_ID` the shape is
+  unchanged (`kbq-autocomplete-0`, `kbq-autocomplete-1`, …); an app or test that sets a custom `APP_ID`
+  now gets it embedded, e.g. `kbq-autocomplete-a1` under TestBed. The id is the panel element's `id`.
+
+- **Classes from the `class` attribute replace each other on the panel instead of accumulating.** The
+  old setter merged every value it was given into an object it never cleared, so a `[class]` binding
+  that changed from `"a"` to `"b"` left the panel with both.
+
+`options` stays a `QueryList` content query: `ActiveDescendantKeyManager` and the panel-closing
+stream both rely on its `changes` semantics.
+
+## Running it manually
+
+```
+ng generate @koobiq/components:autocomplete-signals --project my-app
+```
+
+Pass `--fix=false` to see what it would change without writing.