@koobiq/components 20.4.2 → 21.0.1

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

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

@@ -0,0 +1,129 @@
+# button-state-and-styles
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21`
+(registered for `21.0.0-0`). Migrates consumers of the v21.0.0 button review.
+
+## Background
+
+The review of `[kbq-button]` changed three unrelated things at once, which is why
+one schematic covers all of them:
+
+1. **Host attributes.** `disabled` and `aria-disabled` are now chosen by host
+   tag instead of being applied to both; `tabindex` is omitted when it would be
+   redundant; an `<a kbq-button>` without `href` is announced as a button.
+2. **Button group ownership.** `KbqButtonGroupRoot` used to overwrite every
+   nested button's `kbqStyle` and `color` on each update. It now treats a button
+   that sets them itself as the owner, and its `disabled` became additive.
+3. **Styles.** Four physical border-radius mixins were replaced by logical ones,
+   the `.kbq-progress` utility moved into `kbq-core()`, and two custom properties
+   that nothing read were dropped.
+
+## What it does
+
+The schematic walks every `.ts`, `.html`, `.scss` and `.css` file in the project
+(skipping `node_modules` and `dist`).
+
+| Auto-fix                                                                    | Where            |
+| --------------------------------------------------------------------------- | ---------------- |
+| `@include border-right-radius(…)` → `@include border-inline-end-radius(…)`  | `.scss` / `.css` |
+| `@include border-left-radius(…)` → `@include border-inline-start-radius(…)` | `.scss` / `.css` |
+| `@include border-top-radius(…)` → `@include border-block-start-radius(…)`   | `.scss` / `.css` |
+| `@include border-bottom-radius(…)` → `@include border-block-end-radius(…)`  | `.scss` / `.css` |
+
+This is the only mandatory mechanical change in the release: the four mixins were
+removed from `core/styles/common/_groups-mixins.scss` and
+`core/styles/common/_groups.scss` (the latter re-exported through
+`core/styles/common/_index.scss`), so an unmigrated stylesheet no longer compiles.
+
+The rewrite is anchored on `@include`, because these identifiers only ever appear
+as Sass mixin calls. A CSS declaration (`border-top-left-radius`), a custom
+property (`--border-top-radius`) or a comment mentioning the old name is never
+touched.
+
+> **The replacement is not a pure rename.** `border-inline-end-radius` follows
+> `dir`, so under `dir="rtl"` it rounds the corners `border-right-radius` did
+> not. That is the intent — the library moved its own group styling the same way
+> — but a physically-designed RTL layout will change.
+
+## Group ownership findings
+
+Templates are **parsed**, and a button is reported only when it sits inside a
+group (`kbqButtonGroupRoot`, `<kbq-button-group>` or `[kbq-button-group]`) **and**
+declares a `kbqStyle`, `color` or `disabled` of its own — in any binding form
+(`color="…"`, `[color]="…"`, `bind-color="…"`). A standalone button is
+unaffected by the ownership rule, so reporting it would be noise.
+
+```html
+<div kbqButtonGroupRoot [kbqStyle]="groupStyle">
+    <button kbq-button [kbqStyle]="ownStyle">Reported — the group no longer wins</button>
+    <button kbq-button>Not reported — still inherits from the group</button>
+</div>
+```
+
+Nesting is tracked through the traversal, so a button inside an `@if` block, or a
+group nested in another group, is found once. Findings carry a line number; for
+an inline `@Component({ template })` it is offset to point into the `.ts` file.
+
+Template rules are applied to `.ts` files **only inside inline
+`@Component({ template })` literals**, located through the TypeScript AST — a
+`template` property of some other object is not a component template.
+
+## What it warns about
+
+Nothing below is auto-fixed: each needs a decision, and rewriting it blind would
+be wrong more often than right.
+
+**`.ts`**
+
+| Trigger                                     | Why                                                                                                                                     |
+| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `KbqButtonGroupRoot`                        | `disabled` is now `boolean \| undefined` and additive — re-enabling the group no longer enables a button disabled through its own input |
+| `KbqButtonCssStyler`                        | `nativeElement` became `readonly`; `icons` is typed `Signal<readonly KbqIcon[]>` instead of `readonly any[]`                            |
+| `getAttribute('disabled')` / `hasAttribute` | `<a kbq-button>` no longer renders `disabled`; `<button kbq-button>` no longer renders `aria-disabled`                                  |
+| `KBQ_LOCALE_DATA` / `.addLocale(`           | locale data gained an `a11y` section; custom data without it falls back to the ru-RU accessible names                                   |
+
+**`.scss` / `.css`**
+
+| Trigger                                        | Why                                                                                                     |
+| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `--kbq-button-icon-size-vertical-padding`      | removed — nothing read it even before 21.0.0, so the override was already inert                         |
+| `--kbq-button-icon-size-content-padding`       | same                                                                                                    |
+| `[disabled]` in a file mentioning `kbq-button` | `a[kbq-button][disabled]` never matches now — use `.kbq-disabled` or `[aria-disabled="true"]`           |
+| `@use '…/core/styles/common[/animation]'`      | the import no longer emits `.kbq-progress` or its keyframes; they moved into the `kbq-progress()` mixin |
+
+A template that mentions a group but fails to parse is reported rather than
+guessed at, because a regex cannot tell which buttons are inside the group.
+
+## Behaviour note
+
+Printed once per run, since none of it needs a code change but all of it is
+visible in tests and screenshots:
+
+- `<a kbq-button [disabled]>` drops `disabled`, keeps `aria-disabled="true"`, `tabindex="-1"` and `.kbq-disabled`
+- `<button kbq-button [disabled]>` drops `aria-disabled`, keeps the native `disabled`
+- `<button kbq-button>` no longer renders `tabindex="0"` (anchors still do)
+- `<a kbq-button>` without `href` is announced as `role="button"`
+- every `[kbqDropdownTriggerFor]` renders `aria-expanded`
+- the built-in icon-only buttons render a localized `aria-label`
+- icon gaps and group corner radii follow `dir`
+- `.kbq-progress` is emitted by `kbq-core()` only
+
+## Usage
+
+```bash
+# automatically, as part of the update
+ng update @koobiq/components@21
+
+# or manually
+ng g @koobiq/components:button-state-and-styles --project "<your project>"
+
+# dry run — report without writing
+ng g @koobiq/components:button-state-and-styles --project "<your project>" --fix false
+```
+
+## Options
+
+| Option      | Default | Description                                                    |
+| ----------- | ------- | -------------------------------------------------------------- |
+| `--project` | —       | Project to migrate. Omitted, the migration runs over the tree. |
+| `--fix`     | `true`  | When `false`, prints what would change without writing.        |

package/schematics/migrations/button-state-and-styles/data.cjs

@@ -0,0 +1,136 @@
+'use strict';
+
+/**
+ * Replacement data for the v21.0.0 button review.
+ *
+ * Three unrelated clusters landed together and are migrated by one schematic
+ * because they all originate from the same release:
+ *
+ * 1. Host attributes of `[kbq-button]` — `disabled` / `aria-disabled` are now
+ *    chosen by host tag, `tabindex` is omitted when redundant, and an `<a>`
+ *    without `href` is announced as a button.
+ * 2. `KbqButtonGroupRoot` no longer overwrites a `kbqStyle` / `color` the button
+ *    sets itself, and its `disabled` became additive.
+ * 3. Styles — four physical border-radius mixins were replaced by logical ones,
+ *    the `.kbq-progress` utility moved into `kbq-core()`, and two dead custom
+ *    properties were dropped.
+ */
+/**
+ * Physical border-radius mixins removed from `core/styles/common/_groups-mixins.scss`
+ * and `core/styles/common/_groups.scss` (the latter re-exported through
+ * `core/styles/common/_index.scss`), mapped to the logical mixins that replaced them.
+ *
+ * The replacement is not a rename: `border-inline-end-radius` follows `dir`, so
+ * under `dir="rtl"` it rounds the corners the old `border-right-radius` did not.
+ * That is the point of the change — the library moved its own group styling the
+ * same way — but it is a behaviour change for a physically-designed RTL layout.
+ */
+const REMOVED_MIXINS = {
+    'border-right-radius': 'border-inline-end-radius',
+    'border-left-radius': 'border-inline-start-radius',
+    'border-top-radius': 'border-block-start-radius',
+    'border-bottom-radius': 'border-block-end-radius'
+};
+/**
+ * Matches a mixin call, optionally namespaced (`@include groups-mixins.border-right-radius(0)`).
+ *
+ * Anchored on `@include` on purpose: these identifiers only ever appear as Sass
+ * mixin calls, so a CSS declaration, a custom property name or a comment that
+ * happens to contain the same text is never rewritten.
+ */
+const MIXIN_INCLUDE_PATTERN = /(@include\s+(?:[\w$-]+\.)?)(border-(?:right|left|top|bottom)-radius)\b/g;
+/** Attribute / element names identifying a button group in a template. */
+const GROUP_ATTRIBUTES = ['kbqButtonGroupRoot', 'kbq-button-group'];
+const GROUP_ELEMENT = 'kbq-button-group';
+/** The button attribute marking a host as `KbqButton`. */
+const BUTTON_ATTRIBUTE = 'kbq-button';
+/**
+ * Inputs a nested button may now own. A group used to overwrite these on every
+ * update; it now leaves them alone once the button sets them itself.
+ */
+const OWNED_INPUTS = ['kbqStyle', 'color', 'disabled'];
+/** Reported for a nested button that declares one of {@link OWNED_INPUTS}. */
+const groupOverrideMessage = (inputs) => `This button sets ${inputs.map((input) => `\`${input}\``).join(' / ')} inside a button group. ` +
+    'Until 21.0.0 the group overwrote that value on every update; it now treats the button as the owner ' +
+    'and leaves it alone. Drop the binding if you wanted the group value, or keep it if you wanted the override.';
+/** Warnings for `.ts` files. */
+const tsWarnPatterns = [
+    {
+        pattern: '\\bKbqButtonGroupRoot\\b',
+        message: 'KbqButtonGroupRoot changed: `disabled` now reads `boolean | undefined` (it stays undefined while ' +
+            'the input is unbound) and is additive — re-enabling the group no longer enables a button disabled ' +
+            'through its own input. Style and color are no longer propagated to a button that sets them itself.'
+    },
+    {
+        pattern: '\\bKbqButtonCssStyler\\b',
+        message: 'KbqButtonCssStyler.nativeElement is now readonly and `icons` is typed Signal<readonly KbqIcon[]> ' +
+            'instead of readonly any[]. Assignments and untyped member access no longer compile.'
+    },
+    {
+        pattern: '(get|has)Attribute\\(\\s*[\'"]disabled[\'"]',
+        message: 'The disabled attribute moved: `<a kbq-button>` no longer renders `disabled` (it renders ' +
+            'aria-disabled="true", tabindex="-1" and .kbq-disabled), and `<button kbq-button>` no longer renders ' +
+            'aria-disabled (only the native disabled attribute). Assertions and queries need updating.'
+    },
+    {
+        pattern: '\\bKBQ_LOCALE_DATA\\b|\\.addLocale\\(',
+        message: 'Locale data gained an `a11y` section holding the accessible names of the built-in icon-only buttons ' +
+            '(modal / popover / sidepanel close, calendar navigation, inline-edit save and cancel, and others). ' +
+            'Custom locale data without it falls back to the ru-RU strings — add the section, or provide ' +
+            'kbqA11yLocaleConfigurationProvider(...).'
+    }
+];
+/** Warnings for `.scss` / `.css` files. */
+const styleWarnPatterns = [
+    {
+        pattern: '--kbq-button-icon-size-(vertical-padding|content-padding)\\b',
+        message: 'The --kbq-button-icon-size-vertical-padding and --kbq-button-icon-size-content-padding custom ' +
+            'properties were removed. Nothing read them even before 21.0.0, so an override was already inert — ' +
+            'delete it. Icon buttons use --kbq-button-icon-size-horizontal-padding and ' +
+            '--kbq-button-size-content-padding.'
+    },
+    {
+        pattern: '^(?=[\\s\\S]*kbq-button)(?=[\\s\\S]*\\[disabled\\])',
+        message: 'This stylesheet mentions kbq-button and a [disabled] selector. A disabled `<a kbq-button>` no ' +
+            'longer carries the disabled attribute, so `a[kbq-button][disabled]` never matches now — use ' +
+            '.kbq-disabled or [aria-disabled="true"]. Selectors targeting `<button kbq-button>` still work.'
+    },
+    {
+        pattern: '@use\\s+[\'"][^\'"]*core/styles/common(/animation)?[\'"]',
+        message: 'Importing core/styles/common/animation no longer emits the `.kbq-progress` rule or its keyframes — ' +
+            'they moved into the `kbq-progress()` mixin, emitted once by `kbq-core()`. If you relied on the ' +
+            'import to ship that CSS, include the prebuilt theme (which calls kbq-core()) or add ' +
+            '`@include animation.kbq-progress();` yourself.'
+    }
+];
+/** Reported when a template mentions a button group but cannot be parsed, so nothing was inspected in it. */
+const UNPARSEABLE_TEMPLATE_MESSAGE = 'This template mentions a button group but could not be parsed, so it was not inspected. ' +
+    'Check by hand whether a nested button sets its own kbqStyle / color / disabled.';
+/**
+ * Behaviour note printed once per run. Nothing here needs a code change, but all
+ * of it is observable in tests, stylesheets and screenshots.
+ */
+const BEHAVIOUR_NOTE = [
+    'Rendered attributes changed for [kbq-button]:',
+    '  - <a kbq-button [disabled]>  drops `disabled`, keeps aria-disabled="true" + tabindex="-1" + .kbq-disabled',
+    '  - <button kbq-button [disabled]>  drops `aria-disabled`, keeps the native `disabled`',
+    '  - <button kbq-button>  no longer renders tabindex="0" (anchors still do)',
+    '  - <a kbq-button> without href is announced as role="button"',
+    '  - every [kbqDropdownTriggerFor] now renders aria-expanded',
+    '  - the built-in icon-only buttons now render a localized aria-label',
+    'Icon gaps and group corner radii follow `dir` now, so an RTL layout mirrors instead of staying physical.',
+    'The .kbq-progress utility is emitted by kbq-core() only — it is no longer part of button.css / toggle.css.',
+    'Snapshot and DOM-query tests covering any of the above need updating.'
+];
+
+exports.BEHAVIOUR_NOTE = BEHAVIOUR_NOTE;
+exports.BUTTON_ATTRIBUTE = BUTTON_ATTRIBUTE;
+exports.GROUP_ATTRIBUTES = GROUP_ATTRIBUTES;
+exports.GROUP_ELEMENT = GROUP_ELEMENT;
+exports.MIXIN_INCLUDE_PATTERN = MIXIN_INCLUDE_PATTERN;
+exports.OWNED_INPUTS = OWNED_INPUTS;
+exports.REMOVED_MIXINS = REMOVED_MIXINS;
+exports.UNPARSEABLE_TEMPLATE_MESSAGE = UNPARSEABLE_TEMPLATE_MESSAGE;
+exports.groupOverrideMessage = groupOverrideMessage;
+exports.styleWarnPatterns = styleWarnPatterns;
+exports.tsWarnPatterns = tsWarnPatterns;

package/schematics/migrations/button-state-and-styles/index.cjs

@@ -0,0 +1,221 @@
+'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_buttonStateAndStyles_data = require('./data.cjs');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+const TS_EXT = '.ts';
+const HTML_EXT = '.html';
+const SCSS_EXT = '.scss';
+const CSS_EXT = '.css';
+const LABEL = '[button-state-and-styles]';
+/** `kbqStyle`, `[kbqStyle]` and `bind-kbqStyle` all name the same input. */
+function attributeName(name) {
+    return utils_ast.getSimpleAttributeName(name).replace(/^bind-/, '');
+}
+function hasAttribute(element, name) {
+    return (element.attrs ?? []).some((attr) => typeof attr.name === 'string' && attributeName(attr.name) === name);
+}
+function isGroup(element) {
+    return element.name === migrations_buttonStateAndStyles_data.GROUP_ELEMENT || migrations_buttonStateAndStyles_data.GROUP_ATTRIBUTES.some((name) => hasAttribute(element, name));
+}
+/** The owned inputs a `[kbq-button]` element declares, in template order. */
+function ownedInputs(element) {
+    if (!hasAttribute(element, migrations_buttonStateAndStyles_data.BUTTON_ATTRIBUTE))
+        return [];
+    return migrations_buttonStateAndStyles_data.OWNED_INPUTS.filter((input) => hasAttribute(element, input));
+}
+/**
+ * Collects nested buttons that declare a `kbqStyle` / `color` / `disabled` of
+ * their own.
+ *
+ * Only buttons *inside* a group are reported: the ownership rule exists solely
+ * to decide who wins between a group and its child, so a standalone button is
+ * unaffected and reporting it would be noise. Nesting is tracked through the
+ * traversal rather than by matching the whole subtree at once, so a group nested
+ * in another group still reports its children once.
+ */
+class GroupOverrideCollector {
+    constructor() {
+        this.overrides = [];
+        this.groupDepth = 0;
+    }
+    visitElement(element) {
+        const entered = isGroup(element);
+        if (entered)
+            this.groupDepth++;
+        if (this.groupDepth > 0) {
+            const inputs = ownedInputs(element);
+            if (inputs.length) {
+                this.overrides.push({ line: element.sourceSpan.start.line + 1, inputs });
+            }
+        }
+        this.visitChildren(element);
+        if (entered)
+            this.groupDepth--;
+    }
+    visitBlock(block) {
+        this.visitChildren(block);
+    }
+    visitChildren(node) {
+        for (const child of node.children ?? []) {
+            child.visit(this);
+        }
+    }
+    visitAttribute() { }
+    visitText() { }
+    visitComment() { }
+    visitExpansion() { }
+    visitExpansionCase() { }
+    visitBlockParameter() { }
+    visitLetDeclaration() { }
+}
+/**
+ * Reports nested buttons owning a group-propagated input.
+ *
+ * Returns `null` when the template could not be parsed — guessing at the
+ * structure with a regex would report buttons that are not in a group at all.
+ */
+async function inspectTemplate(template) {
+    // Parsing every template of the project is not free, and a template with no
+    // group in it cannot produce a finding.
+    if (!migrations_buttonStateAndStyles_data.GROUP_ATTRIBUTES.some((name) => template.includes(name)))
+        return [];
+    const parsed = await utils_typescript.parseTemplate(template);
+    if (!parsed.tree)
+        return null;
+    const collector = new GroupOverrideCollector();
+    utils_ast.visitAll(collector, parsed.tree.rootNodes);
+    return collector.overrides;
+}
+/**
+ * Applies the template inspection to every inline `@Component({ template })`
+ * literal of a `.ts` source. Line numbers are reported relative to the template,
+ * which is what a reader of an inline template needs.
+ */
+async function inspectInlineTemplates(content, sourceFile, onParseError) {
+    const overrides = [];
+    for (const { start, end } of utils_typescript.collectInlineTemplateRanges(sourceFile)) {
+        const found = await inspectTemplate(content.slice(start, end));
+        if (found === null) {
+            onParseError();
+            continue;
+        }
+        // Offset by where the literal starts, so the number points into the file.
+        const lineOffset = content.slice(0, start).split('\n').length - 1;
+        overrides.push(...found.map(({ line, inputs }) => ({ line: line + lineOffset, inputs })));
+    }
+    return overrides;
+}
+const createSourceFile = (fileName, content) => ts.createSourceFile(fileName, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+/**
+ * Rewrites `@include border-<side>-radius(…)` to its logical counterpart.
+ *
+ * The mixins were removed outright, so an unmigrated stylesheet fails to compile
+ * — this is the one change in the release that is both mechanical and mandatory.
+ */
+function migrateMixinIncludes(content) {
+    return content.replace(migrations_buttonStateAndStyles_data.MIXIN_INCLUDE_PATTERN, (full, prefix, name) => {
+        const replacement = migrations_buttonStateAndStyles_data.REMOVED_MIXINS[name];
+        return replacement ? `${prefix}${replacement}` : full;
+    });
+}
+function logWarnings(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 logGroupOverrides(context, filePath, overrides) {
+    for (const { line, inputs } of overrides) {
+        utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}:${line}`, `  ${migrations_buttonStateAndStyles_data.groupOverrideMessage(inputs)}`]);
+    }
+}
+function pickWarnPatterns(filePath) {
+    if (filePath.endsWith(TS_EXT))
+        return migrations_buttonStateAndStyles_data.tsWarnPatterns;
+    if (filePath.endsWith(HTML_EXT))
+        return [];
+    return migrations_buttonStateAndStyles_data.styleWarnPatterns;
+}
+function isMigratableFile(filePath) {
+    return (filePath.endsWith(TS_EXT) ||
+        filePath.endsWith(HTML_EXT) ||
+        filePath.endsWith(SCSS_EXT) ||
+        filePath.endsWith(CSS_EXT));
+}
+function buttonStateAndStyles(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 filePaths = [];
+        utils_projectFiles.visitProjectFiles(rootDir, (filePath) => {
+            if (!isMigratableFile(filePath))
+                return;
+            filePaths.push(filePath);
+        });
+        let touched = 0;
+        for (const filePath of filePaths) {
+            const originalContent = tree.read(filePath)?.toString();
+            if (!originalContent)
+                continue;
+            let content = originalContent;
+            let unparseable = false;
+            const reportParseError = () => (unparseable = true);
+            let overrides = [];
+            if (filePath.endsWith(TS_EXT)) {
+                overrides = await inspectInlineTemplates(content, createSourceFile(filePath, content), reportParseError);
+            }
+            else if (filePath.endsWith(HTML_EXT)) {
+                const found = await inspectTemplate(content);
+                if (found === null)
+                    reportParseError();
+                else
+                    overrides = found;
+            }
+            else {
+                content = migrateMixinIncludes(content);
+            }
+            // Warn on what is left over, so an auto-fixed usage does not also produce
+            // a "manual migration required" note. In dry-run mode the fix is not
+            // written, so report against the original content.
+            logWarnings(context, filePath, fix ? content : originalContent, pickWarnPatterns(filePath));
+            logGroupOverrides(context, filePath, overrides);
+            if (unparseable) {
+                utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${migrations_buttonStateAndStyles_data.UNPARSEABLE_TEMPLATE_MESSAGE}`]);
+            }
+            if (content === originalContent)
+                continue;
+            touched++;
+            if (fix) {
+                tree.overwrite(filePath, content);
+            }
+            else {
+                utils_messages.logMessage(context.logger, [`${LABEL} would update ${filePath} (run with --fix to apply)`]);
+            }
+        }
+        utils_messages.logMessage(context.logger, [
+            `${LABEL} processed tree under "${root || '<workspace root>'}", ` +
+                `${fix ? 'updated' : 'would update'} ${touched} file(s).`,
+            '',
+            ...migrations_buttonStateAndStyles_data.BEHAVIOUR_NOTE
+        ]);
+    };
+}
+
+exports.default = buttonStateAndStyles;

package/schematics/migrations/button-state-and-styles/schema.json

@@ -0,0 +1,20 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-button-state-and-styles",
+    "title": "Koobiq components button state and styles upgrade",
+    "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-supported-colors/README.md

@@ -0,0 +1,73 @@
+### Button Supported Colors schematics
+
+This schematic migrates consumers to the narrowed button color set. It includes:
+
+- Removing a `color` written as a literal outside the supported set from `[kbq-button]`, `kbq-button-group`,
+  `[kbqButtonGroupRoot]` and `kbq-split-button` hosts
+- Reporting the `color` bindings it cannot resolve, and the members still typed `KbqComponentColors` /
+  `ThemePalette`
+- Reporting stylesheets that target the old default color of a transparent button
+- A note about the behaviour changes that have no textual signature to search for
+
+#### Why
+
+`color` used to accept any `KbqComponentColors` / `ThemePalette` value, but `kbq-button-theme()` only ever
+styled the pairs the design system defines:
+
+| `kbqStyle`    | supported colors              |
+| ------------- | ----------------------------- |
+| `filled`      | `contrast`, `contrast-fade`   |
+| `outline`     | `theme-fade`, `contrast-fade` |
+| `transparent` | `theme`, `contrast`           |
+
+Every other combination matched no rule at all, so the button fell through to the user-agent appearance — a
+grey OS button. The most visible case was `transparent` with no explicit color: the shared default was
+`contrast-fade`, which is not one of the two colors the transparent block styled.
+
+Each style now carries its own default color, every style gained an unqualified fallback rule, and `color` was
+narrowed to the four colors a button supports.
+
+#### What is fixed
+
+A `color` written as a literal — `color="error"`, `[color]="'error'"`, `bind-color="'error'"` — and holding one
+of `error`, `warning`, `success`, `empty`, `primary`, `secondary`, `info` is removed.
+
+This is appearance-preserving. The button already rendered in its style's default color: an unsupported color
+matched no theme rule, and the fallback rule added by this release resolves to exactly the tokens the style's
+default color branch resolves to. Removing the binding only drops a value that never had an effect, and fixes
+the type error.
+
+#### What is reported, not fixed
+
+| Case                                                 | Why                                                                                                                                      |
+| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `[color]="colors.Error"`                             | the expression is not resolved, so the member name alone does not prove which enum it comes from — deleting it blind could change colors |
+| `button.color = KbqComponentColors.Error`            | same, on the programmatic path                                                                                                           |
+| `kbqOkType`                                          | narrowed from `string` to `KbqButtonColor` on `KbqModalComponent` and `ModalOptions`                                                     |
+| a member typed `KbqComponentColors` / `ThemePalette` | the wide type no longer assigns to a button `color` binding                                                                              |
+| `.kbq-button_transparent.kbq-contrast-fade`          | no longer matches — a transparent button defaults to `contrast` now                                                                      |
+
+Watch for values built inside `Array.from` / `map` callbacks: without a return-type annotation an enum member
+widens to the whole enum and stops assigning even when every value is supported. Annotate the callback:
+
+```ts
+Array.from({ length: 3 }, (_, i): ExampleAction => ({ color: KbqComponentColors.ContrastFade, ... }))
+```
+
+#### Behaviour changes with no textual signature
+
+- A transparent button with no explicit color renders in `contrast` instead of `contrast-fade`. It used to
+  match no theme rule and rendered as a native button, so this is the fix — but a stylesheet or a `color`
+  getter read that expected `contrast-fade` needs updating.
+- A style paired with a color the design system does not define now renders in the style default instead of
+  unstyled.
+- `KbqButtonGroupRoot` no longer propagates a color it was never given, so each nested button follows the
+  default color of its own style. A color bound on the group still wins over that default.
+
+#### Usage
+
+```bash
+ng generate @koobiq/components/schematics:button-supported-colors
+```
+
+Pass `--fix=false` to print what would change without writing.