@koobiq/components 20.4.2 → 21.0.0

package/schematics/migrations/link-signals/index.js

@@ -0,0 +1,415 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var ts = require('typescript');
+var utils_messages = require('../../utils/messages.js');
+var utils_packageConfig = require('../../package-config-BhU2TfC8.js');
+var migrations_linkSignals_data = require('./data.js');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+const LABEL = '[link-signals]';
+const TS_EXT = '.ts';
+/** Factories whose single argument gives the type of the declaration they set up. */
+const TYPING_FACTORIES = new Set(['inject', 'viewChild', 'contentChild']);
+/** 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;
+}
+/** 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;
+}
+/**
+ * Nodes that open a new binding scope. `ts.isFunctionLike` rather than a hand-rolled list of declarations,
+ * so a parameter of a `FunctionTypeNode` or a `MethodSignature` is bounded by its type instead of falling
+ * back to the whole file. Blocks and loops are included because `let`/`const` are block-scoped.
+ */
+const opensScope = (node) => ts.isFunctionLike(node) ||
+    ts.isBlock(node) ||
+    ts.isCaseBlock(node) ||
+    ts.isModuleBlock(node) ||
+    ts.isForStatement(node) ||
+    ts.isForInStatement(node) ||
+    ts.isForOfStatement(node) ||
+    ts.isCatchClause(node) ||
+    ts.isClassLike(node) ||
+    ts.isSourceFile(node);
+/** Nodes that rebind `this`, so `this.link` inside them is a different object. Arrows don't. */
+const rebindsThis = (node) => ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isClassLike(node);
+/** Whether `node` sits inside `scope` without crossing a `barrier` node on the way up. */
+function reachesScope(node, scope, barrier) {
+    let current = node.parent;
+    while (current && current !== scope) {
+        if (barrier(current))
+            return false;
+        current = current.parent;
+    }
+    return current === scope;
+}
+/** Whether a type annotation names one of `typeNames` directly (not through a union or type argument). */
+function isTypeReference(type, typeNames) {
+    return (!!type &&
+        ts.isTypeReferenceNode(type) &&
+        ts.isIdentifier(type.typeName) &&
+        typeNames.includes(type.typeName.text));
+}
+const FIELD_MODIFIERS = new Set([
+    ts.SyntaxKind.PrivateKeyword,
+    ts.SyntaxKind.PublicKeyword,
+    ts.SyntaxKind.ProtectedKeyword,
+    ts.SyntaxKind.ReadonlyKeyword
+]);
+/** Every value declaration that introduces a plain identifier, with the scope it is visible in. */
+function collectBindings(sourceFile) {
+    const bindings = [];
+    const add = (name, declaration, scope) => bindings.push({ name, declaration, scope: scope ?? sourceFile });
+    const visit = (node) => {
+        if (ts.isParameter(node) && ts.isIdentifier(node.name)) {
+            add(node.name.text, node, findAncestor(node, ts.isFunctionLike));
+        }
+        else if ((ts.isVariableDeclaration(node) || ts.isBindingElement(node)) && ts.isIdentifier(node.name)) {
+            add(node.name.text, node, findAncestor(node, opensScope));
+        }
+        else if ((ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node)) && node.name) {
+            add(node.name.text, node, findAncestor(node, opensScope));
+        }
+        else if ((ts.isImportSpecifier(node) || ts.isImportClause(node)) && node.name) {
+            add(node.name.text, node, sourceFile);
+        }
+        node.forEachChild(visit);
+    };
+    visit(sourceFile);
+    return bindings;
+}
+/** The declaration `name` binds to at `pos`: the innermost enclosing scope that declares it. */
+function resolveBinding(bindings, name, pos) {
+    let best;
+    let bestWidth = Number.POSITIVE_INFINITY;
+    for (const binding of bindings) {
+        if (binding.name !== name)
+            continue;
+        const start = binding.scope.getStart();
+        const end = binding.scope.getEnd();
+        if (pos < start || pos > end)
+            continue;
+        const width = end - start;
+        if (width < bestWidth) {
+            best = binding;
+            bestWidth = width;
+        }
+    }
+    return best?.declaration;
+}
+/** Local names `KbqLink` is bound to in this file, including aliased imports. */
+function localTypeNames(sourceFile) {
+    const names = new Set([migrations_linkSignals_data.LINK_TYPE]);
+    const visit = (node) => {
+        if (ts.isImportSpecifier(node) && (node.propertyName?.text ?? node.name.text) === migrations_linkSignals_data.LINK_TYPE) {
+            names.add(node.name.text);
+        }
+        node.forEachChild(visit);
+    };
+    visit(sourceFile);
+    return [...names];
+}
+/**
+ * The link-ness of an initializer, for the shapes a modern Angular consumer writes: `inject(KbqLink)`,
+ * `viewChild(KbqLink)`, `viewChild.required(…)`, `contentChild(…)`.
+ */
+function initializerTypeOf(initializer, typeNames) {
+    const none = { link: false, signalQuery: false, required: false };
+    if (!initializer || !ts.isCallExpression(initializer))
+        return none;
+    const callee = initializer.expression;
+    const qualified = ts.isPropertyAccessExpression(callee) && ts.isIdentifier(callee.expression);
+    const name = ts.isIdentifier(callee) ? callee.text : qualified ? callee.expression.text : undefined;
+    if (!name || !TYPING_FACTORIES.has(name))
+        return none;
+    const [arg] = initializer.arguments;
+    if (!arg || !ts.isIdentifier(arg) || !typeNames.includes(arg.text))
+        return none;
+    // `viewChild.required(...)` is `Signal<KbqLink>`; the bare form adds `| undefined`.
+    const required = qualified && callee.name.text === 'required';
+    return { link: true, signalQuery: name !== 'inject', required };
+}
+/**
+ * Collects the link receivers: method/function params, class fields (incl. `@ViewChild(KbqLink) x: KbqLink`,
+ * constructor parameter-properties and the `inject()` / `viewChild()` initializer forms) and typed locals.
+ */
+function collectReceivers(sourceFile, typeNames) {
+    const receivers = [];
+    const add = (text, declaration, scope, signalQuery = false, required = false) => receivers.push({ text, declaration, scope: scope ?? sourceFile, signalQuery, required });
+    const visit = (node) => {
+        if (ts.isParameter(node) && ts.isIdentifier(node.name) && isTypeReference(node.type, typeNames)) {
+            add(node.name.text, node, findAncestor(node, ts.isFunctionLike));
+            // 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}`, node, owner);
+            }
+        }
+        else if (ts.isPropertyDeclaration(node) && ts.isIdentifier(node.name)) {
+            const owner = findAncestor(node, ts.isClassDeclaration);
+            const { link, signalQuery, required } = initializerTypeOf(node.initializer, typeNames);
+            if (owner && (isTypeReference(node.type, typeNames) || link)) {
+                add(`this.${node.name.text}`, node, owner, signalQuery, required);
+            }
+        }
+        else if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name)) {
+            const { link, signalQuery, required } = initializerTypeOf(node.initializer, typeNames);
+            if (isTypeReference(node.type, typeNames) || link) {
+                add(node.name.text, node, findAncestor(node, opensScope), signalQuery, required);
+            }
+        }
+        node.forEachChild(visit);
+    };
+    visit(sourceFile);
+    return receivers;
+}
+/** Strips the wrappers that do not change which object an access reads from. */
+function unwrapReceiver(node) {
+    let current = node;
+    while (ts.isNonNullExpression(current) ||
+        ts.isParenthesizedExpression(current) ||
+        ts.isAsExpression(current) ||
+        ts.isTypeAssertionExpression(current)) {
+        current = current.expression;
+    }
+    return current;
+}
+/** The receiver a property access resolves to at this exact position, if any. */
+function resolveReceiver(expression, at, sourceFile, receivers, bindings) {
+    const inner = unwrapReceiver(expression);
+    // A receiver is `this.<name>` or a bare identifier, so its own text is a single token: `this . link`
+    // and `this /* x */ . link` already spell `this.link`, because the trivia between the token and the
+    // member lies outside both of their spans.
+    const text = ts.isPropertyAccessExpression(inner)
+        ? `${unwrapReceiver(inner.expression).getText(sourceFile)}.${inner.name.text}`
+        : inner.getText(sourceFile);
+    return receivers.find((receiver) => {
+        if (receiver.text !== text)
+            return false;
+        // For `this.link`, a nested `function` or class changes what `this` is; an arrow does not.
+        // For a bare `link`, a nested redeclaration of the same name shadows the receiver.
+        if (receiver.text.startsWith('this.'))
+            return reachesScope(at, receiver.scope, rebindsThis);
+        return (reachesScope(at, receiver.scope, () => false) &&
+            resolveBinding(bindings, receiver.text, at.getStart(sourceFile)) === receiver.declaration);
+    });
+}
+/** Binary operators that make their left operand a write target rather than a read. */
+const ASSIGNMENT_OPERATORS = new Set([
+    ts.SyntaxKind.EqualsToken,
+    ts.SyntaxKind.PlusEqualsToken,
+    ts.SyntaxKind.MinusEqualsToken,
+    ts.SyntaxKind.AsteriskEqualsToken,
+    ts.SyntaxKind.AsteriskAsteriskEqualsToken,
+    ts.SyntaxKind.SlashEqualsToken,
+    ts.SyntaxKind.PercentEqualsToken,
+    ts.SyntaxKind.LessThanLessThanEqualsToken,
+    ts.SyntaxKind.GreaterThanGreaterThanEqualsToken,
+    ts.SyntaxKind.GreaterThanGreaterThanGreaterThanEqualsToken,
+    ts.SyntaxKind.AmpersandEqualsToken,
+    ts.SyntaxKind.BarEqualsToken,
+    ts.SyntaxKind.CaretEqualsToken,
+    ts.SyntaxKind.BarBarEqualsToken,
+    ts.SyntaxKind.AmpersandAmpersandEqualsToken,
+    ts.SyntaxKind.QuestionQuestionEqualsToken
+]);
+/** Unary operators that write their operand back. Every other prefix operator is a plain read. */
+const INCREMENT_OPERATORS = new Set([ts.SyntaxKind.PlusPlusToken, ts.SyntaxKind.MinusMinusToken]);
+/** Whether `node` sits on the left of a destructuring assignment, where it is written rather than read. */
+function isDestructuringTarget(node) {
+    let current = node;
+    while (ts.isPropertyAssignment(current.parent) ||
+        ts.isShorthandPropertyAssignment(current.parent) ||
+        ts.isSpreadAssignment(current.parent) ||
+        ts.isSpreadElement(current.parent) ||
+        ts.isObjectLiteralExpression(current.parent) ||
+        ts.isArrayLiteralExpression(current.parent)) {
+        current = current.parent;
+    }
+    return (ts.isBinaryExpression(current.parent) &&
+        current.parent.left === current &&
+        ASSIGNMENT_OPERATORS.has(current.parent.operatorToken.kind));
+}
+/**
+ * Classifies a matched property access and appends the resulting edit, if any. Only a plain read is
+ * rewritten: every `KbqLink` signal member is an `input()`, so a write has no mechanical translation, and
+ * appending `()` to it would produce unparseable TypeScript instead of the read-only error to fix by hand.
+ */
+function classifyAccess(node, edits, rewritable) {
+    const parent = node.parent;
+    // Already migrated: `x.disabled()` (call) or the signal API on it.
+    if (ts.isCallExpression(parent) && parent.expression === node)
+        return 'migrated';
+    if (ts.isPropertyAccessExpression(parent) && parent.expression === node && migrations_linkSignals_data.SIGNAL_API_METHODS.has(parent.name.text))
+        return 'migrated';
+    // Write target: `x.disabled = RHS` and every compound form (`+=`, `??=`, `||=`, …).
+    if (ts.isBinaryExpression(parent) && parent.left === node && ASSIGNMENT_OPERATORS.has(parent.operatorToken.kind))
+        return 'write';
+    // `x.disabled++` / `--x.disabled` and `delete x.disabled` are writes too. Only the increment operators
+    // count: a `PrefixUnaryExpression` is also how `!x.disabled` and `-x.tabIndex` are spelled, and those
+    // are reads.
+    if (ts.isPostfixUnaryExpression(parent) && parent.operand === node)
+        return 'write';
+    if (ts.isPrefixUnaryExpression(parent) && parent.operand === node && INCREMENT_OPERATORS.has(parent.operator))
+        return 'write';
+    if (ts.isDeleteExpression(parent))
+        return 'write';
+    if (isDestructuringTarget(node))
+        return 'write';
+    // Read (incl. optional chain `x?.disabled`): append `()`.
+    if (rewritable)
+        edits.push({ start: node.getEnd(), end: node.getEnd(), text: '()' });
+    return 'read';
+}
+/** Collects the edits and the findings for every access on a known link receiver. */
+function collectAccesses(sourceFile, receivers, bindings) {
+    const edits = [];
+    const writes = new Set();
+    const hidden = new Set();
+    const valueChanged = new Set();
+    const signalQueryReads = [];
+    const visit = (node) => {
+        if (ts.isPropertyAccessExpression(node) && ts.isIdentifier(node.name)) {
+            const member = node.name.text;
+            const receiver = migrations_linkSignals_data.KNOWN_MEMBERS.includes(member)
+                ? resolveReceiver(node.expression, node, sourceFile, receivers, bindings)
+                : undefined;
+            if (receiver) {
+                // A hidden member has no reachable spelling left, so classification would have nothing to
+                // offer: report it whether it is read or written.
+                if (migrations_linkSignals_data.HIDDEN_MEMBERS.includes(member)) {
+                    hidden.add(member);
+                }
+                else if (receiver.signalQuery) {
+                    // A signal query holds the directive behind a call of its own, so the read is
+                    // `query().disabled()`. Appending one `()` would be wrong in both halves.
+                    signalQueryReads.push({ member, required: receiver.required });
+                }
+                else if (classifyAccess(node, edits, migrations_linkSignals_data.SIGNAL_MEMBERS.includes(member)) === 'write') {
+                    writes.add(member);
+                }
+                else if (migrations_linkSignals_data.VALUE_CHANGED_MEMBERS.includes(member)) {
+                    valueChanged.add(member);
+                }
+            }
+        }
+        node.forEachChild(visit);
+    };
+    visit(sourceFile);
+    return { edits, writes, hidden, valueChanged, signalQueryReads };
+}
+/** Rewrites the value-safe programmatic reads in one TypeScript file and reports the rest. */
+function migrateTsExpressions(content, fileName) {
+    const sourceFile = ts.createSourceFile(fileName, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const typeNames = localTypeNames(sourceFile);
+    const receivers = collectReceivers(sourceFile, typeNames);
+    const empty = {
+        edits: [],
+        writes: new Set(),
+        hidden: new Set(),
+        valueChanged: new Set(),
+        signalQueryReads: []
+    };
+    if (receivers.length === 0)
+        return { ...empty, content };
+    const bindings = collectBindings(sourceFile);
+    const findings = collectAccesses(sourceFile, receivers, bindings);
+    return { ...findings, content: findings.edits.length > 0 ? applyEdits(content, findings.edits) : content };
+}
+/** Emits the per-file report for everything the rewrite could not do on its own. */
+function report(context, filePath, findings) {
+    const lines = [];
+    const subset = (members) => members.filter((member) => findings.hidden.has(member));
+    const protectedMembers = subset(migrations_linkSignals_data.PROTECTED_MEMBERS);
+    const privateMembers = subset(migrations_linkSignals_data.PRIVATE_MEMBERS);
+    const removedMembers = subset(migrations_linkSignals_data.REMOVED_MEMBERS);
+    if (protectedMembers.length > 0)
+        lines.push(`  ${migrations_linkSignals_data.protectedMessage(protectedMembers)}`);
+    if (privateMembers.length > 0)
+        lines.push(`  ${migrations_linkSignals_data.privateMessage(privateMembers)}`);
+    if (removedMembers.length > 0)
+        lines.push(`  ${migrations_linkSignals_data.removedMessage(removedMembers)}`);
+    if (findings.valueChanged.size > 0)
+        lines.push(`  ${migrations_linkSignals_data.valueChangedMessage(findings.valueChanged)}`);
+    if (findings.writes.size > 0)
+        lines.push(`  ${migrations_linkSignals_data.writeMessage(findings.writes)}`);
+    // The rewrite this file just got is correct but not value-identical, so the caveat belongs next to the
+    // file it was applied to rather than in a summary printed once, after every edit has landed.
+    if (findings.edits.length > 0)
+        lines.push(migrations_linkSignals_data.DISABLED_CAVEAT);
+    for (const { member, required } of findings.signalQueryReads) {
+        lines.push(`  ${migrations_linkSignals_data.signalQueryMessage(member, required)}`);
+    }
+    if (lines.length === 0)
+        return;
+    utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, ...lines]);
+}
+/**
+ * A `.ts` file is a link consumer if it names any of the exported symbols or imports the package. There is
+ * no element to look for: `kbq-link` is an attribute on an anchor.
+ */
+function referencesLink(content) {
+    return /\bKbqLink\w*\b/.test(content) || content.includes(migrations_linkSignals_data.LINK_PACKAGE);
+}
+function linkSignals(options) {
+    return async (tree, context) => {
+        const { project } = options;
+        // `ng update` runs a migration with no options at all, and `migrations.json` declares no schema, so
+        // the schema default never reaches the rule: without this the migration would only ever report.
+        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 = [];
+        utils_packageConfig.visitProjectFiles(rootDir, (filePath) => {
+            if (filePath.endsWith(TS_EXT))
+                tsPaths.push(filePath);
+        });
+        let touched = 0;
+        let consumers = 0;
+        for (const filePath of tsPaths) {
+            const original = tree.read(filePath)?.toString();
+            if (!original || !referencesLink(original))
+                continue;
+            consumers++;
+            const findings = migrateTsExpressions(original, filePath);
+            report(context, filePath, findings);
+            if (findings.content === original)
+                continue;
+            touched++;
+            if (fix) {
+                tree.overwrite(filePath, findings.content);
+            }
+            else {
+                utils_messages.logMessage(context.logger, [`${LABEL} would update ${filePath}`]);
+            }
+        }
+        // Nothing here uses the link, so the summary would only be noise.
+        if (consumers === 0)
+            return;
+        utils_messages.logMessage(context.logger, [
+            `${LABEL} processed tree under "${root || '<workspace root>'}", ` +
+                `${fix ? 'updated' : 'would update'} ${touched} file(s).`,
+            ...migrations_linkSignals_data.SUMMARY
+        ]);
+    };
+}
+
+exports.default = linkSignals;

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

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

@@ -0,0 +1,22 @@
+# list-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 `KbqListSelection` and `KbqListOption`. It never writes to the
+tree.
+
+## Background
+
+The inputs of the list are signal inputs read through a getter. A read is unchanged; a write no longer compiles.
+
+| Member                                                                                         | Write                            |
+| ---------------------------------------------------------------------------------------------- | -------------------------------- |
+| `KbqListSelection`: `autoSelect`, `noUnselectLast`, `multiple`, `tabIndex`, `selectAllHandler` | Bind it                          |
+| `KbqListSelection.disabled`                                                                    | Bind it, or use the form control |
+| `KbqListOption`: `value`, `disabled`, `draggable`, `showCheckbox`                              | Bind it                          |
+| `KbqListOption.selected`, `KbqListSelection.multipleMode`                                      | Still writable                   |
+
+## Running it manually
+
+```bash
+ng g @koobiq/components:list-signals --project "<your project>"
+```

package/schematics/migrations/list-signals/data.js

@@ -0,0 +1,35 @@
+'use strict';
+
+/**
+ * Data for the `list-signals` migration.
+ *
+ * The inputs of `KbqListSelection` and `KbqListOption` are signal inputs read through a getter now. Reads are
+ * unchanged; a programmatic write no longer compiles, except `KbqListOption.selected`, which stays writable.
+ * Warn-only: the write belongs in a binding or a form control.
+ */
+const LIST_ANCHOR = '\\bKbqList(?:Selection|Option)\\b';
+const warnPatterns = [
+    {
+        anchor: LIST_ANCHOR,
+        pattern: '\\.\\s*(?:autoSelect|noUnselectLast|multiple|tabIndex|selectAllHandler)\\s*=[^=]',
+        message: 'KbqListSelection.autoSelect, .noUnselectLast, .multiple, .tabIndex and .selectAllHandler are signal ' +
+            'inputs read through a getter now, so a programmatic write no longer compiles. Bind them in the ' +
+            'template; multipleMode stays writable. This pattern also matches a write to an unrelated object in ' +
+            'the same file — check before changing it.'
+    },
+    {
+        anchor: LIST_ANCHOR,
+        pattern: '\\.\\s*(?:value|disabled|draggable|showCheckbox)\\s*=[^=]',
+        message: 'The value, disabled, draggable and showCheckbox of KbqListOption, and the disabled and draggable of ' +
+            'KbqListSelection, are signal inputs read through a getter now, so a programmatic write no longer ' +
+            'compiles. Bind them in the template, or disable the list through its form control. ' +
+            'KbqListOption.selected stays writable. This pattern also matches a write to an unrelated object in ' +
+            'the same file — check before changing it.'
+    }
+];
+const SUMMARY = [
+    'KbqListSelection and KbqListOption are read as before; only programmatic writes to their inputs are gone.'
+];
+
+exports.SUMMARY = SUMMARY;
+exports.warnPatterns = warnPatterns;

package/schematics/migrations/list-signals/index.js

@@ -0,0 +1,17 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var warnOnlyMigration = require('../../warn-only-migration-BISJBODk.js');
+var migrations_listSignals_data = require('./data.js');
+require('../../utils/messages.js');
+require('../../package-config-BhU2TfC8.js');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+/** Reports programmatic writes to the signal inputs of `KbqListSelection` and `KbqListOption`. Never writes. */
+function listSignals(options) {
+    return warnOnlyMigration.warnOnlyRule({ label: '[list-signals]', warnPatterns: migrations_listSignals_data.warnPatterns, summary: migrations_listSignals_data.SUMMARY }, options);
+}
+
+exports.default = listSignals;

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

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

@@ -0,0 +1,105 @@
+# list-tree-multiple-input
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21` (registered for `21.0.0-0`).
+
+## Background
+
+`multiple` on `kbq-list-selection` and `kbq-tree-selection` used to be a static host attribute read once in
+the constructor:
+
+```ts
+const multiple = inject(new HostAttributeToken('multiple'), { optional: true });
+
+if (multiple === MultipleMode.CHECKBOX || multiple === MultipleMode.KEYBOARD) {
+    this.multipleMode = multiple;
+} else if (multiple !== null) {
+    this.multipleMode = MultipleMode.CHECKBOX; // every other value
+}
+```
+
+So the attribute could not be bound, the mode was frozen for the lifetime of the component, and **every**
+value other than `checkbox` and `keyboard` fell through to multiple selection with checkboxes —
+`multiple="false"` meant _multiple_.
+
+It is now a real input with a closed set of values, resolved by `resolveMultipleMode` in
+`@koobiq/components/core`, and the mode can be changed at any time.
+
+## Behaviour change
+
+| value                                                  | before       | after            |
+| ------------------------------------------------------ | ------------ | ---------------- |
+| `multiple="checkbox"`, `multiple="keyboard"`           | that mode    | unchanged        |
+| `multiple`, `multiple=""`, `multiple="true"`           | checkbox     | unchanged        |
+| no attribute                                           | single       | unchanged        |
+| `multiple="false"`, `multiple="single"`, anything else | **checkbox** | single selection |
+
+Single selection is the default, so the way to ask for it is to leave the attribute off entirely.
+`multiple="single"` is not an accepted spelling.
+
+## What it does
+
+| case                                                           | rewrite                     | preserves behaviour?      |
+| -------------------------------------------------------------- | --------------------------- | ------------------------- |
+| `multiple="false"`, `multiple="single"`                        | attribute removed           | **no** — reported as such |
+| any other unrecognized value (`"multiple"`, `"yes"`, `"1"`, …) | → `multiple="checkbox"`     | yes                       |
+| `[multiple]="'yes'"` (quoted literal)                          | → `[multiple]="'checkbox'"` | yes                       |
+
+Both external `.html` files and inline `@Component({ template })` literals are covered. The two spellings
+that are deleted are the ones whose author meant single selection but got multiple; every rewrite is logged
+with the value it replaced, and the deletions are called out as a behaviour change so they can be reviewed
+in the diff.
+
+## What it does _not_ do (warn-only)
+
+| case                                              | why                                                                                                                            |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `[multiple]="expr"`                               | a runtime expression cannot be resolved at migration time                                                                      |
+| `[multiple]="true \| false \| null \| undefined"` | unambiguous under the new API and impossible before it, so it is left alone silently                                           |
+| `multipleMode = …`                                | now an accessor: it rebuilds the `SelectionModel`, and inside a `kbq-tree-select` it throws, because the select owns the model |
+| `selectionModel.changed.subscribe(…)`             | a mode change replaces the model instance, stranding the subscription; use the `(selectionChange)` output                      |
+
+[Params](schema.ts)
+
+Usage for Angular Cli:
+
+```shell
+ng g @koobiq/components:list-tree-multiple-input --project "<your project>"
+```
+
+Usage for Nx:
+
+```shell
+nx g @koobiq/components:list-tree-multiple-input --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:list-tree-multiple-input --project koobiq-docs
+```
+
+### Result
+
+#### Before
+
+```html
+<kbq-list-selection multiple="false">…</kbq-list-selection>
+<kbq-list-selection multiple="single">…</kbq-list-selection>
+<kbq-tree-selection multiple="multiple">…</kbq-tree-selection>
+```
+
+#### After
+
+```html
+<kbq-list-selection>…</kbq-list-selection>
+<kbq-list-selection>…</kbq-list-selection>
+<kbq-tree-selection multiple="checkbox">…</kbq-tree-selection>
+```