@koobiq/components 20.4.2 → 21.0.1

package/schematics/migrations/button-toggle-signals-and-aria/index.cjs

@@ -0,0 +1,497 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var ts = require('typescript');
+var utils_ast = require('../../utils/ast.cjs');
+var utils_messages = require('../../utils/messages.cjs');
+var utils_packageConfig = require('../../utils/package-config.cjs');
+var utils_projectFiles = require('../../utils/project-files.cjs');
+var utils_typescript = require('../../utils/typescript.cjs');
+var migrations_buttonToggleSignalsAndAria_data = require('./data.cjs');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+const TS_EXT = '.ts';
+const HTML_EXT = '.html';
+const STYLE_EXTS = ['.scss', '.css', '.less'];
+const LABEL = '[button-toggle-signals-and-aria]';
+const emptyFindings = () => ({ manual: new Set(), writes: new Set(), notes: new Set() });
+function mergeFindings(target, source) {
+    source.manual.forEach((value) => target.manual.add(value));
+    source.writes.forEach((value) => target.writes.add(value));
+    source.notes.forEach((value) => target.notes.add(value));
+}
+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;
+}
+/** Local names the button-toggle types are reachable by in this file, `import { X as Y }` included. */
+function collectTypeAliases(sourceFile) {
+    const aliases = new Map([
+        [migrations_buttonToggleSignalsAndAria_data.GROUP_TYPE, migrations_buttonToggleSignalsAndAria_data.GROUP_TYPE],
+        [migrations_buttonToggleSignalsAndAria_data.TOGGLE_TYPE, migrations_buttonToggleSignalsAndAria_data.TOGGLE_TYPE]
+    ]);
+    for (const statement of sourceFile.statements) {
+        if (!ts.isImportDeclaration(statement))
+            continue;
+        const bindings = statement.importClause?.namedBindings;
+        if (!bindings || !ts.isNamedImports(bindings))
+            continue;
+        for (const element of bindings.elements) {
+            const imported = (element.propertyName ?? element.name).text;
+            if (imported === migrations_buttonToggleSignalsAndAria_data.GROUP_TYPE || imported === migrations_buttonToggleSignalsAndAria_data.TOGGLE_TYPE)
+                aliases.set(element.name.text, imported);
+        }
+    }
+    return aliases;
+}
+/** The button-toggle type a type annotation refers to, if any. */
+function toggleTypeOf(type, aliases) {
+    if (!type || !ts.isTypeReferenceNode(type) || !ts.isIdentifier(type.typeName))
+        return undefined;
+    return aliases.get(type.typeName.text);
+}
+const FIELD_MODIFIERS = new Set([
+    ts.SyntaxKind.PrivateKeyword,
+    ts.SyntaxKind.PublicKeyword,
+    ts.SyntaxKind.ProtectedKeyword,
+    ts.SyntaxKind.ReadonlyKeyword
+]);
+/** Factories that hand back a signal, so the declaration is read through a call: `this.group()`. */
+const QUERY_FACTORIES = new Set(['viewChild', 'contentChild']);
+/** Factories that hand back the instance itself. */
+const INSTANCE_FACTORIES = new Set(['inject']);
+/**
+ * The button-toggle an initialiser holds, for the shapes that carry no type annotation to read —
+ * `viewChild(X)`, `viewChild.required(X)`, `contentChild(X)` and `inject(X)`, which is how a modern
+ * Angular consumer reaches a group.
+ */
+function initializerTypeOf(initializer, aliases) {
+    if (!initializer || !ts.isCallExpression(initializer))
+        return undefined;
+    const callee = initializer.expression;
+    let factory;
+    if (ts.isIdentifier(callee)) {
+        factory = callee.text;
+    }
+    else if (ts.isPropertyAccessExpression(callee) && ts.isIdentifier(callee.expression)) {
+        // `viewChild.required(X)` — the `.required` variant of the same factory.
+        factory = callee.name.text === 'required' ? callee.expression.text : undefined;
+    }
+    const [argument] = initializer.arguments;
+    const typeName = factory && argument && ts.isIdentifier(argument) ? aliases.get(argument.text) : undefined;
+    if (!factory || !typeName)
+        return undefined;
+    if (QUERY_FACTORIES.has(factory))
+        return { typeName, isCall: true };
+    if (INSTANCE_FACTORIES.has(factory))
+        return { typeName, isCall: false };
+    return undefined;
+}
+/**
+ * Collects every declaration a receiver can resolve to — not only the ones typed as a button-toggle.
+ * An unrelated declaration of the same name has to be collected as well: it is what makes a nested
+ * `const group = { vertical: 'north' }` shadow an outer group instead of being rewritten as one.
+ *
+ * Types are read from an explicit annotation or from a signal-query / `inject()` initialiser; there is
+ * no cross-file type resolution, so a receiver whose type lives elsewhere resolves to nothing.
+ */
+function collectDeclarations(sourceFile, aliases) {
+    const declarations = [];
+    const add = (text, typeName, scope) => declarations.push({ text, typeName, start: scope.getStart(sourceFile), end: scope.getEnd() });
+    /** A declaration reached by its own name, plus the call form when it holds a signal. */
+    const addWithInitializer = (name, node, scope) => {
+        const annotated = toggleTypeOf(node.type, aliases);
+        const initialized = annotated ? undefined : initializerTypeOf(node.initializer, aliases);
+        add(name, annotated ?? (initialized?.isCall ? undefined : initialized?.typeName), scope);
+        if (initialized?.isCall)
+            add(`${name}()`, initialized.typeName, scope);
+    };
+    const visit = (node) => {
+        if (ts.isParameter(node) && ts.isIdentifier(node.name)) {
+            const typeName = toggleTypeOf(node.type, aliases);
+            add(node.name.text, typeName, 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}`, typeName, owner);
+            }
+        }
+        else if (ts.isPropertyDeclaration(node) && ts.isIdentifier(node.name)) {
+            const owner = findAncestor(node, ts.isClassDeclaration);
+            if (owner)
+                addWithInitializer(`this.${node.name.text}`, node, owner);
+        }
+        else if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name)) {
+            addWithInitializer(node.name.text, node, findAncestor(node, isFunctionLike) ?? sourceFile);
+        }
+        node.forEachChild(visit);
+    };
+    visit(sourceFile);
+    return declarations;
+}
+/**
+ * The declaration a receiver resolves to: the innermost scope that still contains the access, which is
+ * the one with the latest start. Matching the name alone is not enough — an unrelated local of the same
+ * name has to win over an outer group, or the rewrite lands on code that is not a button-toggle at all.
+ */
+function resolveDeclaration(node, sourceFile, declarations) {
+    const text = node.expression.getText(sourceFile);
+    const start = node.getStart(sourceFile);
+    const end = node.getEnd();
+    let resolved;
+    for (const declaration of declarations) {
+        if (declaration.text !== text || start < declaration.start || end > declaration.end)
+            continue;
+        if (!resolved || declaration.start > resolved.start)
+            resolved = declaration;
+    }
+    return resolved;
+}
+/** The signal method a member access is immediately followed by, if any (`x.multiple.set`). */
+function followedByMethod(node) {
+    const parent = node.parent;
+    return ts.isPropertyAccessExpression(parent) && parent.expression === node ? parent.name.text : undefined;
+}
+/** Whether a property access is the left-hand side of an assignment. */
+const isAssignmentTarget = (node) => ts.isBinaryExpression(node.parent) &&
+    node.parent.left === node &&
+    node.parent.operatorToken.kind === ts.SyntaxKind.EqualsToken;
+/** Whether a member access is already a call, i.e. reads a signal the way the new API expects. */
+const isCalled = (node) => ts.isCallExpression(node.parent) && node.parent.expression === node;
+/**
+ * Whether a member of a removed-or-narrowed receiver has to be reported. Most of them break on any
+ * access, having become `private`/`protected` or gone altogether; the ones that only turned into a
+ * read-only getter still read exactly as they did, so only an assignment is worth a line.
+ */
+const isBreakingManualAccess = (member, node) => migrations_buttonToggleSignalsAndAria_data.MANUAL_MEMBERS.has(member) && (!migrations_buttonToggleSignalsAndAria_data.WRITE_ONLY_MANUAL_MEMBERS.has(member) || isAssignmentTarget(node));
+/**
+ * Classifies a matched property access of a group signal member: a read becomes a call, a write is left to
+ * the compiler and reported — an `input()` is read-only and has no `.set()` to rewrite to.
+ */
+function classifySignalAccess(node, edits, findings) {
+    // Already migrated: `x.multiple()` — leave alone.
+    if (ts.isCallExpression(node.parent) && node.parent.expression === node)
+        return;
+    const method = followedByMethod(node);
+    if (method && migrations_buttonToggleSignalsAndAria_data.SIGNAL_API_METHODS.has(method))
+        return;
+    if (isAssignmentTarget(node)) {
+        findings.writes.add(node.name.text);
+        return;
+    }
+    // Read (incl. optional chain `x?.multiple`): append `()`.
+    edits.push({ start: node.getEnd(), end: node.getEnd(), text: '()' });
+}
+/** Pass A — rewrite reads of the group's signal inputs and collect what cannot be rewritten. */
+function migrateTs(content, fileName) {
+    const sourceFile = ts.createSourceFile(fileName, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const aliases = collectTypeAliases(sourceFile);
+    const declarations = collectDeclarations(sourceFile, aliases);
+    const findings = emptyFindings();
+    const edits = [];
+    // A receiver typed elsewhere resolves to nothing here, so a signal read on it is neither rewritten
+    // nor reported by name. Worth one line per file, but only where a group is actually in play.
+    const namesGroup = content.includes(migrations_buttonToggleSignalsAndAria_data.GROUP_TYPE);
+    const visit = (node) => {
+        if (ts.isPropertyAccessExpression(node) && ts.isIdentifier(node.name)) {
+            const declaration = resolveDeclaration(node, sourceFile, declarations);
+            const member = node.name.text;
+            if (declaration?.typeName) {
+                if (declaration.typeName === migrations_buttonToggleSignalsAndAria_data.GROUP_TYPE && migrations_buttonToggleSignalsAndAria_data.SIGNAL_MEMBERS.includes(member)) {
+                    classifySignalAccess(node, edits, findings);
+                }
+                else if (isBreakingManualAccess(member, node)) {
+                    findings.manual.add(member);
+                }
+            }
+            else if (!declaration && namesGroup && migrations_buttonToggleSignalsAndAria_data.SIGNAL_MEMBERS.includes(member) && !isCalled(node)) {
+                findings.notes.add(migrations_buttonToggleSignalsAndAria_data.UNRESOLVED_SIGNAL_READ_MESSAGE);
+            }
+        }
+        node.forEachChild(visit);
+    };
+    visit(sourceFile);
+    return { content: edits.length > 0 ? applyEdits(content, edits) : content, findings };
+}
+/** An attribute name as written, with binding syntax stripped: `[attr.aria-label]` → `aria-label`. */
+const attrName = (attr) => attr.name.replace(/[[\]()]/g, '').replace(/^attr\./, '');
+const hasAttr = (node, names) => !!node.attrs?.some((attr) => names.includes(attrName(attr)));
+const isElement = (node) => Array.isArray(node.attrs);
+const isText = (node) => !isElement(node) && Array.isArray(node.tokens);
+/** Whether the subtree holds any text — a bare text node, an interpolation, or text inside an element. */
+function hasTextContent(node) {
+    for (const child of node.children ?? []) {
+        if (isText(child)) {
+            if ((child.value ?? '').trim() !== '')
+                return true;
+        }
+        else if (hasTextContent(child)) {
+            return true;
+        }
+    }
+    return false;
+}
+/** Whether the subtree holds an icon, which is the content that carries no accessible name. */
+function hasIcon(node) {
+    for (const child of node.children ?? []) {
+        if (isElement(child) && hasAttr(child, migrations_buttonToggleSignalsAndAria_data.ICON_ATTRS))
+            return true;
+        if (hasIcon(child))
+            return true;
+    }
+    return false;
+}
+/** Collects group reference variables and icon-only toggles that carry no accessible name. */
+class TemplateCollector {
+    constructor() {
+        this.refs = new Set();
+        this.unnamedToggleLines = [];
+    }
+    visitElement(element) {
+        for (const attr of element.attrs ?? []) {
+            if (typeof attr.name !== 'string' || attr.value !== migrations_buttonToggleSignalsAndAria_data.GROUP_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));
+        }
+        if (element.name === migrations_buttonToggleSignalsAndAria_data.TOGGLE_ELEMENT && hasIcon(element) && !hasTextContent(element)) {
+            // A `title` here does not count: it stays on the host, while the name is computed for the
+            // inner button. `KbqButtonToggle` does not accept it either.
+            if (!hasAttr(element, migrations_buttonToggleSignalsAndAria_data.NAME_ATTRS)) {
+                this.unnamedToggleLines.push((element.startSourceSpan?.start.line ?? 0) + 1);
+            }
+        }
+        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. A template can
+ * only read these, so an assignment never needs excluding.
+ *
+ * The dot is matched with the whitespace around it — Angular's expression grammar allows `group . multiple`
+ * and a binding wrapped over two lines — and that whitespace is captured so the rewrite keeps the layout.
+ */
+function memberAccessPattern(ref) {
+    const methods = [...migrations_buttonToggleSignalsAndAria_data.SIGNAL_API_METHODS].join('|');
+    return new RegExp(`\\b(${escapeRegExp(ref)})(\\s*\\.\\s*)(${migrations_buttonToggleSignalsAndAria_data.SIGNAL_MEMBERS.join('|')})\\b(?!\\s*\\()(?!\\s*\\.\\s*(?:${methods})\\b)`, 'g');
+}
+/** Rewrites `ref.multiple` reads to `ref.multiple()` 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), '$1$2$3()');
+        if (next !== content) {
+            content = next;
+            changed = true;
+        }
+    }
+    return { content, changed };
+}
+/**
+ * Manual members read through a group reference variable in a template. A template cannot assign, so the
+ * members that only broke for writers — the ones that became read-only getters — are left out.
+ */
+function collectRefManualMembers(template, refs) {
+    const members = [...migrations_buttonToggleSignalsAndAria_data.MANUAL_MEMBERS.keys()].filter((member) => !migrations_buttonToggleSignalsAndAria_data.WRITE_ONLY_MANUAL_MEMBERS.has(member));
+    const found = new Set();
+    for (const ref of refs) {
+        const pattern = new RegExp(`\\b${escapeRegExp(ref)}\\s*\\.\\s*(${members.join('|')})\\b`, 'g');
+        for (const match of template.matchAll(pattern)) {
+            found.add(match[1]);
+        }
+    }
+    return found;
+}
+const untouched = (template) => ({
+    content: template,
+    changed: false,
+    findings: emptyFindings(),
+    unparseable: false
+});
+/** Pass B — rewrite group ref reads and report icon-only toggles with no accessible name. */
+async function migrateTemplate(template) {
+    if (!template.includes(migrations_buttonToggleSignalsAndAria_data.TOGGLE_ELEMENT))
+        return untouched(template);
+    const parsed = await utils_typescript.parseTemplate(template);
+    if (!parsed.tree)
+        return { ...untouched(template), unparseable: true };
+    const collector = new TemplateCollector();
+    utils_ast.visitAll(collector, parsed.tree.rootNodes);
+    const refs = [...collector.refs];
+    const findings = emptyFindings();
+    for (const line of collector.unnamedToggleLines) {
+        findings.notes.add(migrations_buttonToggleSignalsAndAria_data.UNNAMED_ICON_TOGGLE_MESSAGE.replace('%s', String(line)));
+    }
+    if (refs.length === 0)
+        return { ...untouched(template), findings };
+    collectRefManualMembers(template, refs).forEach((member) => findings.manual.add(member));
+    return { ...rewriteRefReads(template, refs), findings, unparseable: false };
+}
+/** Pass B (inline) — the same, inside inline component templates. */
+async function migrateInlineTemplates(content, fileName) {
+    const sourceFile = ts.createSourceFile(fileName, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const findings = emptyFindings();
+    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));
+        mergeFindings(findings, migrated.findings);
+        unparseable ||= migrated.unparseable;
+        if (migrated.changed) {
+            result = result.slice(0, start) + migrated.content + result.slice(end);
+        }
+    }
+    return { content: result, findings, unparseable };
+}
+function logPatterns(context, filePath, content, patterns) {
+    for (const { pattern, message } of patterns) {
+        if (new RegExp(pattern).test(content)) {
+            utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${message}`]);
+        }
+    }
+}
+function logFindings(context, filePath, findings) {
+    for (const member of findings.manual) {
+        utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${migrations_buttonToggleSignalsAndAria_data.MANUAL_MEMBERS.get(member)}`]);
+    }
+    for (const member of findings.writes) {
+        utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${migrations_buttonToggleSignalsAndAria_data.WRITE_MESSAGES.get(member)}`]);
+    }
+    for (const note of findings.notes) {
+        utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${note}`]);
+    }
+}
+/** A `.ts` file is a button-toggle consumer if it names one of its symbols or imports the package. */
+function referencesButtonToggle(content) {
+    return (/\bKbqButtonToggle\w*\b/.test(content) ||
+        content.includes('@koobiq/components/button-toggle') ||
+        content.includes(migrations_buttonToggleSignalsAndAria_data.TOGGLE_ELEMENT));
+}
+function buttonToggleSignalsAndAria(options) {
+    return async (tree, context) => {
+        const { project } = options;
+        // `ng update` invokes migrations with no options at all, and migrations.json declares no schema, so the
+        // schema default never reaches us — applying the fix is the intended behaviour there.
+        const fix = options.fix ?? true;
+        const projectDefinition = await utils_packageConfig.setupOptions(project, tree);
+        const root = projectDefinition?.root ?? '';
+        const rootDir = root ? tree.getDir(root) : tree.root;
+        const tsPaths = [];
+        const htmlPaths = [];
+        const stylePaths = [];
+        utils_projectFiles.visitProjectFiles(rootDir, (filePath) => {
+            if (filePath.endsWith(TS_EXT))
+                tsPaths.push(filePath);
+            else if (filePath.endsWith(HTML_EXT))
+                htmlPaths.push(filePath);
+            else if (STYLE_EXTS.some((ext) => filePath.endsWith(ext)))
+                stylePaths.push(filePath);
+        });
+        let touched = 0;
+        const commit = (filePath, original, updated) => {
+            if (updated === original)
+                return;
+            touched++;
+            if (fix) {
+                tree.overwrite(filePath, updated);
+            }
+            else {
+                utils_messages.logMessage(context.logger, [`${LABEL} would update ${filePath} (run with --fix to apply)`]);
+            }
+        };
+        for (const filePath of tsPaths) {
+            const original = tree.read(filePath)?.toString();
+            if (!original || !referencesButtonToggle(original))
+                continue;
+            const expressions = migrateTs(original, filePath);
+            const inline = await migrateInlineTemplates(expressions.content, filePath);
+            const content = inline.content;
+            // The pattern warnings are checked against the post-fix content, so an auto-fixed read does not
+            // also produce a note. In dry-run mode the fix is not written, so report against the original.
+            const reported = fix ? content : original;
+            const findings = emptyFindings();
+            // Both passes only ever collect what they could not rewrite, so there is nothing to re-check.
+            mergeFindings(findings, expressions.findings);
+            mergeFindings(findings, inline.findings);
+            logPatterns(context, filePath, reported, migrations_buttonToggleSignalsAndAria_data.tsWarnPatterns);
+            logFindings(context, filePath, findings);
+            if (inline.unparseable) {
+                utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${migrations_buttonToggleSignalsAndAria_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);
+            logFindings(context, filePath, migrated.findings);
+            if (migrated.unparseable) {
+                utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${migrations_buttonToggleSignalsAndAria_data.UNPARSEABLE_TEMPLATE_MESSAGE}`]);
+            }
+            if (migrated.changed)
+                commit(filePath, original, migrated.content);
+        }
+        for (const filePath of stylePaths) {
+            const original = tree.read(filePath)?.toString();
+            if (!original || !original.includes(migrations_buttonToggleSignalsAndAria_data.TOGGLE_ELEMENT))
+                continue;
+            logPatterns(context, filePath, original, migrations_buttonToggleSignalsAndAria_data.styleWarnPatterns);
+        }
+        utils_messages.logMessage(context.logger, [
+            `${LABEL} processed tree under "${root || '<workspace root>'}", ` +
+                `${fix ? 'updated' : 'would update'} ${touched} file(s).`,
+            '',
+            ...migrations_buttonToggleSignalsAndAria_data.BEHAVIOUR_NOTE
+        ]);
+    };
+}
+
+exports.default = buttonToggleSignalsAndAria;

package/schematics/migrations/button-toggle-signals-and-aria/schema.json

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

@@ -0,0 +1,110 @@
+### Button Truncation schematics
+
+This schematic migrates `KbqButton` and `KbqButtonToggle` consumers to labels that truncate with an ellipsis
+by default. It includes:
+
+- Moving an icon that sits at either edge of the default slot into the `kbqButtonPrefix` / `kbqButtonSuffix`
+  slot
+- Reporting stylesheets whose overrides the new layout affects
+- A note about the one change that has no textual signature to search for
+
+An icon left in the default slot shares one box with the label, and that box has to become a flex row to
+centre the icon exactly — which is precisely what stops `text-overflow: ellipsis` from being painted. The
+marker slots lay the icon out _beside_ the truncating box, so the label keeps its ellipsis and the icon keeps
+its centring. Icon-only buttons are left alone: they have no label to truncate.
+
+The change is silent — every template still compiles and still renders — so what is not migrated only lays
+out differently.
+
+#### What is reported, not fixed
+
+| Selector                     | Why                                                                                                                                                                                  |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `.kbq-button-text`           | was `display: flex`, now `display: inline-block` (a flex box never paints `text-overflow`). Content projected as your own row needs `display: flex; align-items: center` re-declared |
+| `.kbq-button-wrapper`        | hand-rolled truncation overrides now stack on top of the built-in one                                                                                                                |
+| `.kbq-button-toggle-wrapper` | the projected label moved one level deeper, into `.kbq-button-toggle-text`                                                                                                           |
+
+`.kbq-button` and `.kbq-light-button` also gained `max-width: 100%`, so a button whose label is wider than its
+container no longer overflows — it clamps and clips. Nothing in the code identifies those places, so review
+screens with narrow buttons, dense toolbars and table cells visually. To upgrade first and adopt truncation
+screen by screen, neutralise it in your global styles:
+
+```css
+.kbq-button,
+.kbq-light-button {
+    max-width: none;
+}
+```
+
+[Params](schema.ts)
+
+Usage for Angular Cli:
+
+```shell
+ng g @koobiq/components:button-truncation --project "<your project>"
+```
+
+Usage for Nx:
+
+```shell
+nx g @koobiq/components:button-truncation --project "<your project>"
+```
+
+Run it without writing anything first — stylesheet findings are printed either way:
+
+```shell
+ng g @koobiq/components:button-truncation --project "<your project>" --fix=false
+```
+
+### 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:button-truncation --project koobiq-docs
+```
+
+### Result
+
+#### Before
+
+```html
+<button kbq-button>
+    <i kbq-icon="kbq-plus_16"></i>
+    Очень длинный текст кнопки
+    <i kbq-icon="kbq-chevron-down-s_16"></i>
+</button>
+
+<kbq-button-toggle [value]="1">
+    @if (showIcon()) {
+    <i kbq-icon="kbq-briefcase_16"></i>
+    } Курьером
+</kbq-button-toggle>
+
+<!-- icon-only: nothing to truncate, left untouched -->
+<button kbq-button aria-label="Add"><i kbq-icon="kbq-plus_16"></i></button>
+```
+
+#### After
+
+```html
+<button kbq-button>
+    <i kbqButtonPrefix kbq-icon="kbq-plus_16"></i>
+    Очень длинный текст кнопки
+    <i kbqButtonSuffix kbq-icon="kbq-chevron-down-s_16"></i>
+</button>
+
+<kbq-button-toggle [value]="1">
+    @if (showIcon()) {
+    <i kbqButtonPrefix kbq-icon="kbq-briefcase_16"></i>
+    } Курьером
+</kbq-button-toggle>
+
+<button kbq-button aria-label="Add"><i kbq-icon="kbq-plus_16"></i></button>
+```