@koobiq/components 20.4.2 → 21.0.0

package/schematics/migrations/app-switcher-signals/README.md

@@ -0,0 +1,88 @@
+# app-switcher-signals
+
+Migration schematic invoked automatically by `ng update @koobiq/components`.
+Migrates consumers of `KbqAppSwitcherTrigger` to its `model()`-based API and reports the members the
+app-switcher review removed.
+
+## Why
+
+`selectedApp` and `selectedSite` moved from a plain `@Input()` (plus a matching `output()`) to `model()`, and
+several members that never did anything were dropped. Template _bindings_ keep working — `[selectedApp]`,
+`[(selectedSite)]` and `(selectedAppChange)` are unchanged — so only programmatic access and reads through a
+`#ref="kbqAppSwitcher"` template reference variable break.
+
+| Member                                 | Before                       | After                                         | Auto-fix                         |
+| -------------------------------------- | ---------------------------- | --------------------------------------------- | -------------------------------- |
+| `selectedApp`                          | `@Input()` property          | `ModelSignal<KbqAppSwitcherApp \| undefined>` | ✅ read → call, write → `.set()` |
+| `selectedAppChange`                    | `output()`                   | implicit output of the `selectedApp` model    | ✅ `.subscribe` renamed          |
+| `selectedSite`                         | `get`/`set` accessor input   | `ModelSignal`, **value changed**              | ⚠️ warn                          |
+| `selectedSiteChange`                   | `output()`                   | implicit output, **value changed**            | ⚠️ warn                          |
+| `header` / `footer`                    | properties                   | removed                                       | ⚠️ warn                          |
+| `isTrapFocus` / `updateTrapFocus()`    | `KbqAppSwitcherComponent`    | removed                                       | ⚠️ warn                          |
+| `activeSite` / `activeApp` (protected) | `KbqAppSwitcherComponent`    | removed: the flyout template context          | ⚠️ warn                          |
+| `getIcon()`                            | `KbqAppSwitcherDropdownApp`  | removed                                       | ⚠️ warn                          |
+| `collapsed`, `app`, `site`, `toggle`   | properties / optional inputs | model / `input.required`                      | ⚠️ warn                          |
+
+## What it does (auto-fix)
+
+The schematic walks every `.ts` and `.html` file in the project (skipping `node_modules` and `dist`) and, for
+files that reference the app-switcher:
+
+- **TypeScript access.** For a receiver whose static type is annotated `KbqAppSwitcherTrigger` (method/function
+  params, class fields — including `@ViewChild(KbqAppSwitcherTrigger) x: KbqAppSwitcherTrigger` and constructor
+  parameter-properties — and typed locals):
+    - `trigger.selectedApp` → `trigger.selectedApp()` (incl. optional chain `trigger?.selectedApp`)
+    - `trigger.selectedApp = app` → `trigger.selectedApp.set(app)`
+    - `trigger.selectedAppChange.subscribe(fn)` → `trigger.selectedApp.subscribe(fn)` — `ModelSignal` implements
+      `OutputRef`, so the callback signature is identical
+- **Template reference reads.** For a `#ref="kbqAppSwitcher"` (or `ref-x="kbqAppSwitcher"`), reads of
+  `selectedApp` through that ref are rewritten in the same template (external `.html` and inline `template:`
+  strings): `switcher.selectedApp` → `switcher.selectedApp()`.
+
+All rewrites are idempotent — an access already followed by `()`, `.set`, `.update`, `.asReadonly` or
+`.subscribe` is left alone, so running twice does not double the call.
+
+Note that `selectedApp()` is typed `KbqAppSwitcherApp | undefined`. Where the old property was read as
+non-nullable (`trigger.selectedApp.name` → `trigger.selectedApp().name`), the compiler will now ask for a `!` or
+a `?.` — that narrowing is yours to place.
+
+## What it does _not_ do (warn-only)
+
+| Change                                               | Manual migration                                                                                                                                                                                                                                                                          |
+| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `trigger.selectedSite` read                          | **Value changed.** The old getter returned the site with its applications already grouped; the model returns the value that was passed in. Use `trigger.selectedSite()` for the raw site, `trigger.parsedSelectedSite()` for the grouped one.                                             |
+| `trigger.selectedSite = site` write                  | `trigger.selectedSite.set(site)`.                                                                                                                                                                                                                                                         |
+| `trigger.selectedSiteChange`                         | Now the implicit output of the model: `trigger.selectedSite.subscribe(…)`. It emits the raw site, not the grouped one.                                                                                                                                                                    |
+| `trigger.selectedAppChange.emit(app)`                | No longer an emitter — `trigger.selectedApp.set(app)`.                                                                                                                                                                                                                                    |
+| `trigger.header` / `trigger.footer`                  | Removed. The popup never rendered either, so the value was pushed into the overlay and dropped — delete the usage.                                                                                                                                                                        |
+| `popup.isTrapFocus` / `popup.updateTrapFocus(…)`     | Removed from `KbqAppSwitcherComponent`. The template never bound `[cdkTrapFocus]`, so neither did anything.                                                                                                                                                                               |
+| `row.getIcon(icon)`                                  | Removed from `KbqAppSwitcherDropdownApp`. Inline markup is sanitized by `KbqAppSwitcherIconSanitizer` and rendered by the component itself.                                                                                                                                               |
+| `KbqAppSwitcherListItem.collapsed`                   | Now a `model()`: read `collapsed()`, write `collapsed.set(v)`.                                                                                                                                                                                                                            |
+| `app` / `site` inputs of the internal row components | Now `input.required` signals and must be bound.                                                                                                                                                                                                                                           |
+| Inline `icon` SVG markup                             | Sanitized against a strict SVG allow-list before rendering: `<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`). |
+
+## Behaviour changes with no call site to migrate
+
+Printed once per run:
+
+- `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. Provide them explicitly where they are actually needed.
+- `defaultGroupBy` 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.
+
+## Running it manually
+
+```
+ng generate @koobiq/components:app-switcher-signals --project my-app
+```
+
+Pass `--fix=false` to see what would change without writing files.
+
+## Limitations
+
+Receivers are matched by explicit `KbqAppSwitcherTrigger` type annotation only (no cross-package type
+inference), so aliased or inferred receivers (`const t = this.trigger; t.selectedApp`) are left untouched.
+`selectedSite` is intentionally **not** auto-rewritten because its value semantics changed. After running,
+**always inspect the diff** and act on the warnings before committing.

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

@@ -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.js

@@ -0,0 +1,365 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var ts = require('typescript');
+var utils_ast = require('../../utils/ast.js');
+var utils_messages = require('../../utils/messages.js');
+var utils_packageConfig = require('../../package-config-BhU2TfC8.js');
+var utils_typescript = require('../../utils/typescript.js');
+var migrations_appSwitcherSignals_data = require('./data.js');
+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_packageConfig.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

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
 var utils_angularParsing = require('../../utils/angular-parsing.js');
-var utils_packageConfig = require('../../utils/package-config.js');
+var utils_packageConfig = require('../../package-config-BhU2TfC8.js');
 var utils_typescript = require('../../utils/typescript.js');
 require('typescript');
 require('../../utils/ast.js');