@koobiq/components 20.4.2 → 21.0.1

package/schematics/migrations/input-number-surface/index.cjs

@@ -0,0 +1,293 @@
+'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 migrations_inputNumberSurface_data = require('./data.cjs');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+const LABEL = '[input-number-surface]';
+const EXTENSIONS = ['.ts', '.html'];
+const TS_EXT = '.ts';
+/** A file is an input consumer if it imports the package or names one of the directives. */
+function referencesInput(content) {
+    return (content.includes(migrations_inputNumberSurface_data.INPUT_PACKAGE) ||
+        new RegExp(migrations_inputNumberSurface_data.INPUT_TYPE).test(content) ||
+        new RegExp(migrations_inputNumberSurface_data.PASSWORD_TYPE).test(content));
+}
+const createSourceFile = (fileName, content) => ts.createSourceFile(fileName, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+/**
+ * Identifiers in the file explicitly typed as `typeName` — through a type annotation, or a
+ * `viewChild(<typeName>)` / `viewChild.required(<typeName>)` initializer.
+ *
+ * Used for two opposite purposes. For `KbqInput` it suppresses a false positive: a member access on one
+ * of these can never be the `KbqFormFieldControl` surface this migration warns about, because `KbqInput`
+ * still owns it. For `KbqNumberInput` it is what scopes the signal-read rewrite, since `min`/`max`/`step`
+ * are far too common to match on the member name alone.
+ *
+ * Only this file's annotations are consulted — there is no cross-package type resolution — so a receiver
+ * whose type is inferred rather than written down is left alone.
+ */
+function collectTypedNames(sourceFile, typeName) {
+    const names = new Set();
+    const isKbqInputTypeNode = (node) => !!node && ts.isTypeReferenceNode(node) && node.typeName.getText(sourceFile) === typeName;
+    const referencesKbqInput = (call) => call.arguments.some((argument) => ts.isIdentifier(argument) && argument.text === typeName);
+    const visit = (node) => {
+        if ((ts.isPropertyDeclaration(node) || ts.isVariableDeclaration(node) || ts.isParameter(node)) &&
+            ts.isIdentifier(node.name) &&
+            isKbqInputTypeNode(node.type)) {
+            names.add(node.name.text);
+        }
+        if (ts.isCallExpression(node) &&
+            /^viewChild(\.required)?$/.test(node.expression.getText(sourceFile)) &&
+            referencesKbqInput(node)) {
+            const owner = node.parent;
+            if ((ts.isPropertyDeclaration(owner) || ts.isVariableDeclaration(owner)) && ts.isIdentifier(owner.name)) {
+                names.add(owner.name.text);
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    ts.forEachChild(sourceFile, visit);
+    return names;
+}
+/** The receiver name (capture group 1) of every `FORM_FIELD_CONTROL_MEMBER_PATTERN` match in `content`. */
+function collectFormFieldControlReceivers(content) {
+    const regex = new RegExp(migrations_inputNumberSurface_data.FORM_FIELD_CONTROL_MEMBER_PATTERN.pattern, 'g');
+    const receivers = [];
+    let match;
+    while ((match = regex.exec(content))) {
+        receivers.push(match[1]);
+    }
+    return receivers;
+}
+/**
+ * Whether `content` reads a removed `KbqFormFieldControl` member off something other than a provably
+ * `KbqInput`-typed reference. `KbqInput` keeps every one of these members, so a match whose receiver
+ * resolves to a `KbqInput`-typed identifier is a false positive, not a call site the rename broke.
+ * `.html` templates fall back to the plain existence check: a template-reference receiver (`#ref="kbqInput"`)
+ * is not resolved here.
+ */
+function reportsFormFieldControlMember(filePath, content) {
+    const receivers = collectFormFieldControlReceivers(content);
+    if (receivers.length === 0)
+        return false;
+    if (!filePath.endsWith(TS_EXT))
+        return true;
+    const kbqInputTypedNames = collectTypedNames(createSourceFile(filePath, content), 'KbqInput');
+    return receivers.some((receiver) => !kbqInputTypedNames.has(receiver));
+}
+/** Applies text-span edits to `content`, right-to-left, so earlier edits don't shift later offsets. */
+function applyEdits(content, edits) {
+    return [...edits]
+        .sort((a, b) => b.start - a.start || b.end - a.end)
+        .reduce((result, { start, end, text }) => result.slice(0, start) + text + result.slice(end), content);
+}
+/**
+ * Trailing identifier of a receiver expression: `input` for `input`, `numberInput` for
+ * `this.numberInput`. Anything else (a call, an index read) has no stable name and is skipped.
+ */
+function receiverName(expression) {
+    if (ts.isIdentifier(expression))
+        return expression.text;
+    if (ts.isPropertyAccessExpression(expression) && ts.isIdentifier(expression.name))
+        return expression.name.text;
+    return null;
+}
+/**
+ * Rewrites `numberInput.min` to `numberInput.min()` on every receiver this file annotates as a
+ * `KbqNumberInput`. A write (`numberInput.min = 5`) is left alone and reported instead: the members are
+ * read-only `input()`s, so there is no `.set()` to rewrite to, and the binding is the replacement.
+ *
+ * Returns the rewritten content plus the distinct member names written to, for the caller to report.
+ */
+function migrateSignalReads(content, filePath) {
+    const written = new Set();
+    if (!migrations_inputNumberSurface_data.SIGNAL_MEMBERS.some((member) => content.includes(member)))
+        return { content, written };
+    const sourceFile = createSourceFile(filePath, content);
+    const receivers = collectTypedNames(sourceFile, migrations_inputNumberSurface_data.NUMBER_INPUT_TYPE);
+    if (receivers.size === 0)
+        return { content, written };
+    const edits = [];
+    const visit = (node) => {
+        if (ts.isPropertyAccessExpression(node) &&
+            ts.isIdentifier(node.name) &&
+            migrations_inputNumberSurface_data.SIGNAL_MEMBERS.includes(node.name.text)) {
+            const name = receiverName(node.expression);
+            if (name && receivers.has(name)) {
+                const parent = node.parent;
+                const isWrite = ts.isBinaryExpression(parent) &&
+                    parent.left === node &&
+                    parent.operatorToken.kind === ts.SyntaxKind.EqualsToken;
+                // Already a call — `min()` — so the rewrite stays idempotent across repeated runs.
+                const isCalled = ts.isCallExpression(parent) && parent.expression === node;
+                if (isWrite)
+                    written.add(node.name.text);
+                else if (!isCalled)
+                    edits.push({ start: node.getEnd(), end: node.getEnd(), text: '()' });
+            }
+        }
+        node.forEachChild(visit);
+    };
+    visit(sourceFile);
+    return { content: edits.length > 0 ? applyEdits(content, edits) : content, written };
+}
+/**
+ * Template reference variables bound to the number input by `exportAs` — `#ref="kbqNumberInput"` and the
+ * `kbqNumericalInput` alias. Matched textually: the templates this runs over are the consumer's, and a
+ * full template parse would still not tell us the directive's type.
+ */
+function collectTemplateRefs(template) {
+    const pattern = new RegExp(`#([A-Za-z_$][\\w$]*)\\s*=\\s*["'](?:${migrations_inputNumberSurface_data.NUMBER_INPUT_EXPORT_AS.join('|')})["']`, 'g');
+    return [...template.matchAll(pattern)].map((match) => match[1]);
+}
+/**
+ * Names this file imports from `@koobiq/components/input` that were renamed. A name can only be bound
+ * once per module, so a name imported from koobiq here cannot also be the `@angular/forms` export of the
+ * same spelling — which is what makes a whole-file rename of it safe.
+ */
+function collectRenamedImports(sourceFile) {
+    const imported = new Set();
+    for (const statement of sourceFile.statements) {
+        if (!ts.isImportDeclaration(statement) ||
+            !ts.isStringLiteralLike(statement.moduleSpecifier) ||
+            statement.moduleSpecifier.text !== migrations_inputNumberSurface_data.INPUT_PACKAGE) {
+            continue;
+        }
+        const bindings = statement.importClause?.namedBindings;
+        if (!bindings || !ts.isNamedImports(bindings))
+            continue;
+        for (const element of bindings.elements) {
+            // `import { MinValidator as Lower }` binds a different local name; the import itself is
+            // rewritten by the propertyName branch, and the alias keeps working untouched.
+            imported.add((element.propertyName ?? element.name).text);
+        }
+    }
+    return migrations_inputNumberSurface_data.RENAMED_EXPORTS.filter(([from]) => imported.has(from));
+}
+/** Rewrites the removed export names to their prefixed replacements, scoped to this file's imports. */
+function migrateRenamedExports(content, filePath) {
+    if (!migrations_inputNumberSurface_data.RENAMED_EXPORTS.some(([from]) => content.includes(from)))
+        return content;
+    const renames = collectRenamedImports(createSourceFile(filePath, content));
+    if (renames.length === 0)
+        return content;
+    // Longest first, so `MIN_VALIDATOR` is never matched as part of a longer identifier by a shorter
+    // pattern; `\b` on both ends keeps `KbqMinValidator` itself from matching `MinValidator`.
+    return [...renames]
+        .sort(([a], [b]) => b.length - a.length)
+        .reduce((result, [from, to]) => result.replace(new RegExp(`(?<![\\w$])${from}(?![\\w$])`, 'g'), to), content);
+}
+/**
+ * Renames the dropped kebab-case `big-step` to `bigStep`, within the same `<input>` tag as the
+ * directive so an unrelated element's attribute of that name is untouched. Both binding forms, and
+ * both attribute orders — the directive may sit before or after the attribute.
+ */
+function migrateBigStepAttribute(template) {
+    if (!template.includes('big-step'))
+        return template;
+    return template.replace(/<input\b[^>]*>/g, (tag) => /\bkbqNumberInput\b/.test(tag) ? tag.replace(/(\[?)big-step(\]?)\s*=/g, '$1bigStep$2=') : tag);
+}
+/** Rewrites `ref.min` to `ref.min()` for template refs bound to the number input, and renames `big-step`. */
+function migrateTemplate(template) {
+    let content = migrateBigStepAttribute(template);
+    const refs = collectTemplateRefs(content);
+    const members = migrations_inputNumberSurface_data.SIGNAL_MEMBERS.join('|');
+    for (const ref of refs) {
+        // `(?!\s*\()` skips anything already invoked, so a second run is a no-op.
+        content = content.replace(new RegExp(`\\b(${ref})\\.(${members})\\b(?!\\s*\\()`, 'g'), '$1.$2()');
+    }
+    return { content, changed: content !== template };
+}
+/**
+ * Rewrites reads of the `KbqNumberInput` members that became `input()` signals — `min`, `max`, `step`,
+ * `bigStep` — on a receiver this file annotates as a `KbqNumberInput`, and on a template reference bound
+ * through the directive's `exportAs`.
+ *
+ * Reports the rest: the members that disappeared with the unimplemented `KbqFormFieldControl` surface,
+ * the validator classes that gained a `Kbq` prefix, the `EventEmitter` → `Subject` change, and the two
+ * behaviors that changed without a call site to point at — the `type="number"` reset and the removed
+ * `valueAsNumber` prototype patch. A removed member that was always `undefined` has no replacement
+ * expression, so none of that half can be written.
+ *
+ * `.html` is visited as well as `.ts`, because `type="number"` is markup.
+ */
+function inputNumberSurface(options) {
+    return async (tree, context) => {
+        const { project } = options;
+        // `migrations.json` registers this without a schema, so the schema default never reaches us;
+        // applying the fix is the intended behavior of `ng update`.
+        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;
+        let consumers = 0;
+        let reported = 0;
+        let touched = 0;
+        const pending = [];
+        utils_projectFiles.visitProjectFiles(rootDir, (filePath, entry) => {
+            if (!EXTENSIONS.some((extension) => filePath.endsWith(extension)))
+                return;
+            const content = entry?.content.toString();
+            if (!content || !referencesInput(content))
+                return;
+            consumers++;
+            for (const { anchor, pattern, message } of migrations_inputNumberSurface_data.warnPatterns) {
+                if (!new RegExp(anchor).test(content) || !new RegExp(pattern).test(content))
+                    continue;
+                reported++;
+                utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${message}`]);
+            }
+            if (new RegExp(migrations_inputNumberSurface_data.FORM_FIELD_CONTROL_MEMBER_PATTERN.anchor).test(content) &&
+                reportsFormFieldControlMember(filePath, content)) {
+                reported++;
+                utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${migrations_inputNumberSurface_data.FORM_FIELD_CONTROL_MEMBER_PATTERN.message}`]);
+            }
+            const isTs = filePath.endsWith(TS_EXT);
+            // A `.ts` file carries both programmatic reads and any inline template; an `.html` file only
+            // the latter. Both passes run on a `.ts` file, so `#ref="kbqNumberInput"` in an inline
+            // template is reached too.
+            const { content: afterReads, written } = isTs
+                ? migrateSignalReads(content, filePath)
+                : { content, written: new Set() };
+            const afterRenames = isTs ? migrateRenamedExports(afterReads, filePath) : afterReads;
+            const { content: updated } = migrateTemplate(afterRenames);
+            if (written.size > 0) {
+                reported++;
+                utils_messages.logMessage(context.logger, [
+                    `${LABEL} ${filePath}`,
+                    `  ${[...written].join(', ')} on KbqNumberInput ${written.size === 1 ? 'is' : 'are'} a ` +
+                        'read-only input() and cannot be assigned. Bind the value in the template instead ' +
+                        '([min]="…"); a programmatic write has no .set() to migrate to.'
+                ]);
+            }
+            if (updated === content)
+                return;
+            touched++;
+            if (fix)
+                pending.push({ filePath, content: updated });
+            else
+                utils_messages.logMessage(context.logger, [`${LABEL} would update ${filePath} (run with --fix to apply)`]);
+        });
+        // Written after the walk: overwriting during `visit` re-enters the visitor on some Tree backends.
+        for (const { filePath, content } of pending) {
+            tree.overwrite(filePath, content);
+        }
+        // Nothing here uses the input, so the summary would only be noise.
+        if (consumers === 0)
+            return;
+        utils_messages.logMessage(context.logger, [
+            `${LABEL} processed kbqInput under "${root || '<workspace root>'}", ` +
+                `${consumers} file(s) reference the package, ${reported} call site(s) reported, ` +
+                `${fix ? 'updated' : 'would update'} ${touched} file(s).`,
+            ...migrations_inputNumberSurface_data.SUMMARY
+        ]);
+    };
+}
+
+exports.default = inputNumberSurface;

package/schematics/migrations/input-number-surface/schema.json

@@ -0,0 +1,20 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-input-number-surface",
+    "title": "Koobiq components input 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"
+            }
+        },
+        "fix": {
+            "type": "boolean",
+            "default": true,
+            "description": "When true, applies the signal-read replacements. When false, prints what would change without writing."
+        }
+    }
+}

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

@@ -0,0 +1,20 @@
+# input-signals
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21` (registered for `21.0.0-0`).
+Reports programmatic writes to the signal inputs of `KbqNumberInput` and `KbqInput`. It never writes to the tree.
+
+## Background
+
+`KbqNumberInput.value`, `KbqNumberInput.disabled` and `KbqInput.type` are signal inputs read through a getter. A read
+is unchanged; a write no longer compiles.
+
+| Write                                               | Manual migration                                       |
+| --------------------------------------------------- | ------------------------------------------------------ |
+| `numberInput.value = …`, `numberInput.disabled = …` | Bind `[value]` / `[disabled]`, or use the form control |
+| `input.type = …`                                    | Bind `[type]`                                          |
+
+## Running it manually
+
+```bash
+ng g @koobiq/components:input-signals --project "<your project>"
+```

package/schematics/migrations/input-signals/data.cjs

@@ -0,0 +1,30 @@
+'use strict';
+
+/**
+ * Data for the `input-signals` migration.
+ *
+ * `KbqNumberInput.value` / `.disabled` and `KbqInput.type` are signal inputs read through a getter now. Reads are
+ * unchanged; a programmatic write no longer compiles. Warn-only: the write belongs in a binding or a form control.
+ */
+const warnPatterns = [
+    {
+        anchor: '\\bKbqNumberInput\\b|\\bkbqNumberInput\\b',
+        pattern: '\\.\\s*(?:value|disabled)\\s*=[^=]',
+        message: 'KbqNumberInput.value and .disabled are signal inputs read through a getter now, so a programmatic ' +
+            'write no longer compiles. Bind [value] / [disabled], or write through the form control. This ' +
+            'pattern also matches a write to an unrelated object in the same file — check before changing it.'
+    },
+    {
+        anchor: '\\bKbqInput\\b',
+        pattern: '\\.\\s*type\\s*=[^=]',
+        message: 'KbqInput.type is a signal input read through a getter now, so a programmatic write no longer ' +
+            'compiles. Bind [type] instead. This pattern also matches a write to an unrelated object in the ' +
+            'same file — check before changing it.'
+    }
+];
+const SUMMARY = [
+    'KbqNumberInput.value / .disabled and KbqInput.type are read as before; only programmatic writes are gone.'
+];
+
+exports.SUMMARY = SUMMARY;
+exports.warnPatterns = warnPatterns;

package/schematics/migrations/input-signals/index.cjs

@@ -0,0 +1,18 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var utils_warnOnlyMigration = require('../../utils/warn-only-migration.cjs');
+var migrations_inputSignals_data = require('./data.cjs');
+require('../../utils/messages.cjs');
+require('../../utils/package-config.cjs');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+require('../../utils/project-files.cjs');
+
+/** Reports programmatic writes to the signal inputs of `KbqNumberInput` and `KbqInput`. Never writes. */
+function inputSignals(options) {
+    return utils_warnOnlyMigration.warnOnlyRule({ label: '[input-signals]', warnPatterns: migrations_inputSignals_data.warnPatterns, summary: migrations_inputSignals_data.SUMMARY }, options);
+}
+
+exports.default = inputSignals;

package/schematics/migrations/input-signals/schema.json

@@ -0,0 +1,15 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-input-signals",
+    "title": "Koobiq components input signals 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"
+            }
+        }
+    }
+}

package/schematics/migrations/link-deprecated-path/README.md

@@ -0,0 +1,144 @@
+# link-deprecated-path
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21` (registered for
+`21.0.0-0`). Rewrites `@koobiq/components/link` imports to `@koobiq/components/link/deprecated`.
+
+## Background
+
+`@koobiq/components/link` now resolves to the `KbqLink` component with the `[kbqLink]` selector. It
+renders the underlined text itself, between the `kbqLinkPrefix` and `kbqLinkSuffix` slots, adds the
+external icon through the `external` input, takes its size from the `size` input and its underline
+from the `underline` input, covers the gaps between the lines of a wrapped link by itself, makes a link on any element but an `<a>` a pseudo link with the `button` role
+and Enter and Space, and stops the click on a disabled link. The previous directive - `KbqLink` and
+`KbqLinkModule` with the `[kbq-link]` selector, whose markup needed the `kbq-link__text` wrapper and
+the `kbq-link_external` and `kbq-text-with-dot` classes - moved to
+`@koobiq/components/link/deprecated` and will be removed in a future major version.
+
+Nothing about the directive changed: its inputs, the `[kbq-link]` selector, the `kbqLink` export
+name and the classes its markup relies on behave exactly as before at the new path. Rewriting the
+import is the whole migration - adopting the component is a separate, manual step.
+
+## Behaviour change
+
+An unmigrated import keeps compiling, and that is why the migration exists: both entry points
+export `KbqLink` and `KbqLinkModule`. Without the rewrite the import brings in the component, whose
+selector is `[kbqLink]`, so the `kbq-link` attribute in the templates matches nothing and the links
+lose their styles.
+
+## What it does
+
+The schematic walks every `.ts` file under the project root - the whole workspace when `--project`
+is omitted, which is how `ng update` invokes it - skipping `node_modules` and `dist`, and rewrites
+the module specifier `@koobiq/components/link` to `@koobiq/components/link/deprecated`.
+
+The match is quote-anchored (`(['"])@koobiq/components/link\1`), so only the exact, bare specifier
+is taken, in the quote style it was written in:
+
+| Specifier                                    | Result                                                                                 |
+| -------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `'@koobiq/components/link'`                  | rewritten, still single-quoted                                                         |
+| `"@koobiq/components/link"`                  | rewritten, still double-quoted                                                         |
+| `'@koobiq/components/link/deprecated'`       | untouched - the migration is idempotent                                                |
+| `'@koobiq/components/link-x'` (hypothetical) | untouched - the closing quote is required, so a longer specifier is not a prefix match |
+
+It is a textual replacement rather than an AST rewrite, so an `import`, an `export … from`, a
+dynamic `import()` and a specifier handed to something like `jest.mock()` are all covered by the
+same pass.
+
+## What it does _not_ do (manual)
+
+| Pattern                          | Manual migration                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A specifier outside a `.ts` file | Only `.ts` files are visited - the same string in a JSON config or a documentation snippet stays as written                                                                                                                                                                                                                                                                                                                                                 |
+| Templates                        | Left as written; they keep working against the directive at its new path                                                                                                                                                                                                                                                                                                                                                                                    |
+| Moving off `/deprecated`         | Nothing is migrated _to_ the component: rename `kbq-link` to `kbqLink`, `big` / `compact` to `size` and `noUnderline` to `underline="none"`, drop `multiline`, drop `pseudo` from a host that is not an `<a>` and the `kbq-link__text` wrapper, mark a leading icon with `kbqLinkPrefix` and a trailing one with `kbqLinkSuffix`, replace `kbq-link_external` and its north-east icon with `external`, and the `kbq-text-with-dot` dot with `kbqLinkSuffix` |
+
+`fix` defaults to `true`. `ng update` invokes migrations with no options at all, and
+`migrations.json` declares no schema, so the rule applies that default itself. With `--fix false`
+every file that would change is logged instead of written, followed by the same count either way.
+
+[Params](schema.ts)
+
+Usage for Angular Cli:
+
+```shell
+ng g @koobiq/components:link-deprecated-path --project "<your project>"
+```
+
+Usage for Nx:
+
+```shell
+nx g @koobiq/components:link-deprecated-path --project "<your project>"
+```
+
+### Run locally
+
+Build package
+
+```shell
+yarn run build:schematics
+```
+
+Run command (for example, for `koobiq-docs` project)
+
+```shell
+ng g ./dist/components/schematics/collection.json:link-deprecated-path --project koobiq-docs
+```
+
+### Result
+
+#### Before
+
+```ts
+import { Component } from '@angular/core';
+import { KbqIconModule } from '@koobiq/components/icon';
+import { KbqLinkModule } from '@koobiq/components/link';
+
+@Component({
+    selector: 'my-page',
+    imports: [KbqLinkModule, KbqIconModule],
+    template: `
+        <a class="kbq-link_external" href="https://koobiq.io" target="_blank" kbq-link>
+            <span class="kbq-link__text">Koobiq</span>
+            <i kbq-icon="kbq-north-east_16"></i>
+        </a>
+    `
+})
+export class MyPage {}
+```
+
+#### After
+
+```ts
+import { Component } from '@angular/core';
+import { KbqIconModule } from '@koobiq/components/icon';
+import { KbqLinkModule } from '@koobiq/components/link/deprecated';
+
+@Component({
+    selector: 'my-page',
+    imports: [KbqLinkModule, KbqIconModule],
+    template: `
+        <a class="kbq-link_external" href="https://koobiq.io" target="_blank" kbq-link>
+            <span class="kbq-link__text">Koobiq</span>
+            <i kbq-icon="kbq-north-east_16"></i>
+        </a>
+    `
+})
+export class MyPage {}
+```
+
+#### With the component
+
+```ts
+import { Component } from '@angular/core';
+import { KbqLinkModule } from '@koobiq/components/link';
+
+@Component({
+    selector: 'my-page',
+    imports: [KbqLinkModule],
+    template: `
+        <a href="https://koobiq.io" target="_blank" kbqLink external>Koobiq</a>
+    `
+})
+export class MyPage {}
+```

package/schematics/migrations/link-deprecated-path/index.cjs

@@ -0,0 +1,20 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var utils_deprecatedPathMigration = require('../../utils/deprecated-path-migration.cjs');
+require('../../utils/messages.cjs');
+require('../../utils/package-config.cjs');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+require('../../utils/project-files.cjs');
+
+/**
+ * `@koobiq/components/link` now resolves to the `KbqLink` component, which renders the text, the slots
+ * and the external icon itself - the directive it used to export (`KbqLink`, `KbqLinkModule`) moved to
+ * `@koobiq/components/link/deprecated`. This rewrites the import specifier only; the API itself is
+ * unchanged at its new path.
+ */
+var index = utils_deprecatedPathMigration.deprecatedPathMigration('link');
+
+exports.default = index;

package/schematics/migrations/link-deprecated-path/schema.json

@@ -0,0 +1,20 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-link-deprecated-path",
+    "title": "Koobiq components link deprecated-path rewrite",
+    "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/link-signals/README.md

@@ -0,0 +1,71 @@
+# link-signals
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21` (registered for
+`21.0.0-0`). Migrates `KbqLink` consumers to its finished signal-based API and reports the members
+the review closed.
+
+## Background
+
+The three inputs the automated signal migration skipped were all accessors, and each did something
+beyond storing a value:
+
+```ts
+set disabled(value: boolean) { this.disabledSignal.set(value); }
+get tabIndex(): number { return this.disabled ? -1 : this._tabIndex; }
+set print(value: any) { this.printMode = value !== null; this._print = value; this.updatePrintUrl(); }
+```
+
+`disabledSignal` stays a public `WritableSignal<boolean>`: `kbqTooltip` accepts a link through
+`forDisabledComponent` and reads it, and that contract is typed on the tooltip side. It is a
+`linkedSignal` over the input now, so binding `[disabled]` still drives it and a direct write still
+wins.
+
+## What it rewrites
+
+| Before          | After             |
+| --------------- | ----------------- |
+| `link.disabled` | `link.disabled()` |
+
+On receivers explicitly typed `KbqLink`. Already-migrated reads are left alone, so the schematic is
+idempotent. There is no template-reference pass: `kbq-link` is an attribute on an anchor, so a
+`#ref="kbqLink"` read is not tied to an element name the schematic can match.
+
+## What it does _not_ do
+
+| Pattern                                         | Manual migration                                                                   |
+| ----------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `.tabIndex`                                     | `tabIndex()`, and expect what was bound — not `-1` for a disabled link             |
+| `link.print = …`                                | Bind `[print]`; it was a setter with no getter, so there is no read to fix         |
+| `.icons` / `.nativeElement`                     | Now `private`; call `getHostElement()` for the host                                |
+| `.hasIcon` / `.printMode` / `.printUrl`         | Now `protected`; the `kbq-link_print` class and `print` attribute are the contract |
+| `.icon` / `.destroyRef` / `.ngAfterContentInit` | Gone; `icons` answers what `icon` did, and the hook is not implemented             |
+| `viewChild(KbqLink)`                            | The query returns the instance, so a read through it is a double call              |
+
+`tabIndex` is warned about rather than rewritten because appending `()` would compile and hand back
+a different number for a disabled link. A write of any kind — `=`, `||=`, `++` — is reported rather
+than rewritten: every member is an `input()`, so there is no writable half, and appending `()` would
+turn a read-only error into a syntax error.
+
+## Notes with no call site to point at
+
+- **`[print]="undefined"` no longer marks the link as printable.** The old setter tested
+  `value !== null`, so an explicit `undefined` passed it: the link got `kbq-link_print` and printed
+  its `href`. The input tests `!= null`, which covers both. An unbound link behaves exactly as
+  before — no class, and the href still lands in the `print` attribute. `print` accepts
+  `string | null` instead of `any`.
+- **Reading `disabled` reports the bound input.** The effective state — what the host bindings
+  render — is `disabledSignal()`. The two only differ if something writes `disabledSignal` directly,
+  which is what `kbqTooltip` does through `forDisabledComponent`. This one is reported next to every
+  file the rewrite touched rather than once per project, because the rewrite it applies is correct
+  but not value-identical.
+- **A disabled link carries `aria-disabled` instead of `disabled`.** `disabled` is not valid on an
+  `<a>` or a `<span>` and told assistive tech nothing. `kbq-disabled` and `tabindex="-1"` are
+  unchanged; a selector on `a[kbq-link][disabled]` needs `.kbq-disabled` or `[aria-disabled]`.
+
+## Running it manually
+
+```
+ng generate @koobiq/components:link-signals --project my-app
+```
+
+Pass `--fix=false` to see what it would change without writing.