@koobiq/components 20.4.2 → 21.0.0

package/schematics/migrations/button-supported-colors/data.js

@@ -0,0 +1,106 @@
+'use strict';
+
+/**
+ * Replacement data for the narrowed button color set.
+ *
+ * A button used to accept any `KbqComponentColors` / `ThemePalette` value, but
+ * `kbq-button-theme()` only ever styled the pairs the design system defines. A style
+ * paired with anything else matched no theme rule at all and fell through to the
+ * user-agent button appearance — most visibly `transparent` with no explicit color,
+ * because the shared default (`contrast-fade`) was not one of the two colors the
+ * transparent block styled.
+ *
+ * Two things changed:
+ *
+ * 1. Each style now carries its own default color. `transparent` resolves to
+ *    `contrast` rather than `contrast-fade`: it paints neither fill nor border, so
+ *    the color only picks the foreground and the design system has no faded
+ *    transparent variant.
+ * 2. Every style gained an unqualified fallback rule, so a pair the design system
+ *    does not define renders in the style's default color instead of unstyled — and
+ *    `color` was narrowed to the four colors a button actually supports.
+ */
+/** The colors `color` still accepts, on a button, a button group and a split button. */
+const SUPPORTED_COLORS = ['theme', 'theme-fade', 'contrast', 'contrast-fade'];
+/**
+ * Color values a button no longer accepts, as written in a template.
+ *
+ * `KbqComponentColors.Default` is deliberately absent: it is `'contrast'`, so it
+ * still compiles. `ThemePalette.Default` is `'secondary'` and does not — but the two
+ * are indistinguishable by member name, so that one is left to the warning below.
+ */
+const UNSUPPORTED_COLORS = ['error', 'warning', 'success', 'empty', 'primary', 'secondary', 'info'];
+/**
+ * Enum member names that resolve to an unsupported color. Used only to warn: the
+ * receiver is not resolved, so rewriting on a name alone could delete a binding that
+ * reads from something else entirely.
+ */
+const UNSUPPORTED_MEMBERS = ['Error', 'Warning', 'Success', 'Empty', 'Primary', 'Secondary', 'Info'];
+/** Attribute / element names identifying a host whose `color` input is now narrowed. */
+const COLOR_HOST_ATTRIBUTES = ['kbq-button', 'kbq-button-group', 'kbqButtonGroupRoot', 'kbq-split-button'];
+const COLOR_HOST_ELEMENTS = ['kbq-button-group', 'kbq-split-button'];
+/** The input this migration rewrites. */
+const COLOR_ATTRIBUTE = 'color';
+const removedColorMessage = (value) => `removed \`color="${value}"\`: a button supports ${SUPPORTED_COLORS.join(', ')} only. The button already ` +
+    `rendered in its style's default color here — an unsupported color matched no theme rule — so dropping the ` +
+    `binding keeps the appearance and fixes the type error.`;
+const unsupportedMemberMessage = (member) => `\`color\` is bound to \`${member}\`, which is not one of ${SUPPORTED_COLORS.join(', ')}. Remove the binding ` +
+    `to keep the style's default color, or pick a supported one. Not rewritten automatically: the expression is ` +
+    `not resolved, so the member name alone does not prove which enum it comes from.`;
+/** Warnings for `.ts` sources. */
+const tsWarnPatterns = [
+    {
+        pattern: '\\.color\\s*=\\s*(?:KbqComponentColors|ThemePalette)\\.(?:' + UNSUPPORTED_MEMBERS.join('|') + ')',
+        message: 'assigns an unsupported color programmatically. `KbqButton.color`, `KbqButtonGroupRoot.color` and ' +
+            '`KbqSplitButton.color` now accept ' +
+            SUPPORTED_COLORS.join(', ') +
+            ' only; anything else never had a theme rule and now renders in the style default.'
+    },
+    {
+        pattern: 'kbqOkType',
+        message: '`kbqOkType` on `KbqModalComponent` / `ModalOptions` was narrowed from `string` to `KbqButtonColor`: ' +
+            'it colors the predefined OK button, so it takes ' +
+            SUPPORTED_COLORS.join(', ') +
+            ' only.'
+    },
+    {
+        pattern: ':\\s*(?:KbqComponentColors|ThemePalette)\\b',
+        message: 'declares a member typed `KbqComponentColors` / `ThemePalette`. If it feeds a button `color` binding, ' +
+            'narrow it to `KbqButtonColor` — the wide type no longer assigns. Watch for values built inside ' +
+            '`Array.from`/`map` callbacks too: without a return-type annotation an enum member widens to the whole ' +
+            'enum and stops assigning even when every value is supported.'
+    }
+];
+/** Warnings for stylesheets. */
+const styleWarnPatterns = [
+    {
+        pattern: '\\.kbq-button_transparent[^{,]*\\.kbq-contrast-fade|\\.kbq-contrast-fade[^{,]*\\.kbq-button_transparent',
+        message: 'targets `.kbq-button_transparent.kbq-contrast-fade`, which no longer matches: a transparent button ' +
+            'defaults to `contrast` now. Retarget it at `.kbq-contrast`, or drop it if it was a workaround for the ' +
+            'transparent button rendering unstyled.'
+    }
+];
+const UNPARSEABLE_TEMPLATE_MESSAGE = 'template could not be parsed, so its `color` bindings were left untouched — check them by hand.';
+const BEHAVIOUR_NOTE = [
+    'Behaviour changes that are not auto-fixable:',
+    '  - A transparent button with no explicit color now renders in `contrast` instead of `contrast-fade`.',
+    '    It used to match no theme rule at all 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 (e.g. filled + theme) 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.'
+];
+
+exports.BEHAVIOUR_NOTE = BEHAVIOUR_NOTE;
+exports.COLOR_ATTRIBUTE = COLOR_ATTRIBUTE;
+exports.COLOR_HOST_ATTRIBUTES = COLOR_HOST_ATTRIBUTES;
+exports.COLOR_HOST_ELEMENTS = COLOR_HOST_ELEMENTS;
+exports.SUPPORTED_COLORS = SUPPORTED_COLORS;
+exports.UNPARSEABLE_TEMPLATE_MESSAGE = UNPARSEABLE_TEMPLATE_MESSAGE;
+exports.UNSUPPORTED_COLORS = UNSUPPORTED_COLORS;
+exports.UNSUPPORTED_MEMBERS = UNSUPPORTED_MEMBERS;
+exports.removedColorMessage = removedColorMessage;
+exports.styleWarnPatterns = styleWarnPatterns;
+exports.tsWarnPatterns = tsWarnPatterns;
+exports.unsupportedMemberMessage = unsupportedMemberMessage;

package/schematics/migrations/button-supported-colors/index.js

@@ -0,0 +1,260 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var ts = require('typescript');
+var utils_ast = require('../../utils/ast.js');
+var utils_messages = require('../../utils/messages.js');
+var utils_packageConfig = require('../../package-config-BhU2TfC8.js');
+var utils_typescript = require('../../utils/typescript.js');
+var migrations_buttonSupportedColors_data = require('./data.js');
+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-supported-colors]';
+/** `color`, `[color]` and `bind-color` 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);
+}
+/** Whether the element is one whose `color` input this release narrowed. */
+function isColorHost(element) {
+    return (migrations_buttonSupportedColors_data.COLOR_HOST_ELEMENTS.includes(element.name) || migrations_buttonSupportedColors_data.COLOR_HOST_ATTRIBUTES.some((name) => hasAttribute(element, name)));
+}
+/**
+ * The color a binding resolves to, when that can be read off the source alone.
+ *
+ * Covers the two unambiguous forms: a plain attribute (`color="error"`) and a bound
+ * string literal (`[color]="'error'"`). Anything else — an enum member, a field, a
+ * ternary — returns `null` and is warned about instead of rewritten.
+ */
+function literalColor(attr) {
+    const raw = typeof attr.value === 'string' ? attr.value.trim() : '';
+    if (!raw)
+        return null;
+    // A plain attribute carries the value verbatim; only a binding is an expression.
+    if (attributeName(attr.name) === attr.name)
+        return raw;
+    const quoted = /^'([^']*)'$|^"([^"]*)"$/.exec(raw);
+    return quoted ? (quoted[1] ?? quoted[2]) : null;
+}
+/** The trailing enum member of a property access, e.g. `colors.Error` → `Error`. */
+function memberName(attr) {
+    const raw = typeof attr.value === 'string' ? attr.value.trim() : '';
+    const match = /^[\w$.]*\.(\w+)$/.exec(raw);
+    return match && migrations_buttonSupportedColors_data.UNSUPPORTED_MEMBERS.includes(match[1]) ? raw : null;
+}
+/**
+ * Collects `color` bindings on button hosts: the removable ones by span, the ones
+ * that only look unsupported by line.
+ */
+class ColorCollector {
+    constructor() {
+        this.removals = [];
+        this.warnings = [];
+    }
+    visitElement(element) {
+        if (isColorHost(element)) {
+            for (const attr of element.attrs ?? []) {
+                if (typeof attr.name !== 'string' || attributeName(attr.name) !== migrations_buttonSupportedColors_data.COLOR_ATTRIBUTE)
+                    continue;
+                const value = literalColor(attr);
+                if (value !== null) {
+                    if (migrations_buttonSupportedColors_data.UNSUPPORTED_COLORS.includes(value)) {
+                        this.removals.push({
+                            start: attr.sourceSpan.start.offset,
+                            end: attr.sourceSpan.end.offset,
+                            value
+                        });
+                    }
+                    continue;
+                }
+                const expression = memberName(attr);
+                if (expression) {
+                    this.warnings.push({ line: attr.sourceSpan.start.line + 1, expression });
+                }
+            }
+        }
+        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() { }
+}
+/**
+ * Deletes the given spans, each together with the whitespace that separated it from
+ * the previous attribute: an inline attribute takes its leading spaces, one written
+ * on its own line takes the line break and the indent as well, so the tag is not left
+ * with a blank line.
+ */
+function removeSpans(content, spans) {
+    let result = content;
+    // Right-to-left, so earlier offsets stay valid.
+    for (const { start, end } of [...spans].sort((a, b) => b.start - a.start)) {
+        let from = start;
+        while (from > 0 && (result[from - 1] === ' ' || result[from - 1] === '\t'))
+            from--;
+        if (result[from - 1] === '\n') {
+            from--;
+            if (result[from - 1] === '\r')
+                from--;
+        }
+        result = result.slice(0, from) + result.slice(end);
+    }
+    return result;
+}
+/**
+ * Drops unsupported `color` values from every button host in a template. Returns
+ * `null` when the template could not be parsed — editing it blind is how a
+ * regex-based migration corrupts binding expressions, so the caller warns instead.
+ */
+async function migrateTemplate(template) {
+    // Parsing every template of the project is not free, and a template with no
+    // colored host in it cannot produce a finding.
+    if (!template.includes(migrations_buttonSupportedColors_data.COLOR_ATTRIBUTE))
+        return { content: template, removed: [], warnings: [] };
+    const parsed = await utils_typescript.parseTemplate(template);
+    if (!parsed.tree)
+        return null;
+    const collector = new ColorCollector();
+    utils_ast.visitAll(collector, parsed.tree.rootNodes);
+    return {
+        content: removeSpans(template, collector.removals),
+        removed: collector.removals,
+        warnings: collector.warnings
+    };
+}
+/**
+ * Applies the template migration to every inline `@Component({ template })` literal
+ * of a `.ts` source. Line numbers are reported relative to the file, which is what a
+ * reader of an inline template needs.
+ */
+async function migrateInlineTemplates(content, sourceFile, onParseError) {
+    let result = content;
+    const removed = [];
+    const warnings = [];
+    // Right-to-left, so the ranges of the literals still to be processed 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));
+        if (migrated === null) {
+            onParseError();
+            continue;
+        }
+        const lineOffset = result.slice(0, start).split('\n').length - 1;
+        removed.push(...migrated.removed);
+        warnings.push(...migrated.warnings.map(({ line, expression }) => ({ line: line + lineOffset, expression })));
+        result = result.slice(0, start) + migrated.content + result.slice(end);
+    }
+    return { content: result, removed, warnings };
+}
+const createSourceFile = (fileName, content) => ts.createSourceFile(fileName, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+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 pickWarnPatterns(filePath) {
+    if (filePath.endsWith(TS_EXT))
+        return migrations_buttonSupportedColors_data.tsWarnPatterns;
+    if (filePath.endsWith(HTML_EXT))
+        return [];
+    return migrations_buttonSupportedColors_data.styleWarnPatterns;
+}
+function isMigratableFile(filePath) {
+    return (filePath.endsWith(TS_EXT) ||
+        filePath.endsWith(HTML_EXT) ||
+        filePath.endsWith(SCSS_EXT) ||
+        filePath.endsWith(CSS_EXT));
+}
+function buttonSupportedColors(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_packageConfig.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 result = { content, removed: [], warnings: [] };
+            if (filePath.endsWith(TS_EXT)) {
+                result = await migrateInlineTemplates(content, createSourceFile(filePath, content), reportParseError);
+            }
+            else if (filePath.endsWith(HTML_EXT)) {
+                const migrated = await migrateTemplate(content);
+                if (migrated === null)
+                    reportParseError();
+                else
+                    result = migrated;
+            }
+            content = result.content;
+            for (const { value } of result.removed) {
+                utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${migrations_buttonSupportedColors_data.removedColorMessage(value)}`]);
+            }
+            for (const { line, expression } of result.warnings) {
+                utils_messages.logMessage(context.logger, [
+                    `${LABEL} ${filePath}:${line}`,
+                    `  ${migrations_buttonSupportedColors_data.unsupportedMemberMessage(expression)}`
+                ]);
+            }
+            // 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));
+            if (unparseable) {
+                utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${migrations_buttonSupportedColors_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_buttonSupportedColors_data.BEHAVIOUR_NOTE
+        ]);
+    };
+}
+
+exports.default = buttonSupportedColors;

package/schematics/migrations/button-supported-colors/schema.json

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

@@ -0,0 +1,137 @@
+# button-toggle-signals-and-aria
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21`
+(registered for `21.0.0-0`). Migrates consumers of the v21.0.0 button-toggle
+review.
+
+## Background
+
+The review of `kbq-button-toggle` changed two unrelated things, which is why one
+schematic covers both:
+
+1. **ARIA, tab order and the keyboard.** The control always behaved like a radio
+   group in single selection and like a set of toggle buttons with `multiple`,
+   and none of it reached assistive tech: selection was readable from the
+   `.kbq-selected` class alone. A single-selection group is now a `radiogroup` of
+   `role="radio"` buttons with `aria-checked`, walked with the arrow keys and
+   entered through a single tab stop; a `multiple` group is a `group` of toggle
+   buttons with `aria-pressed`, each still its own tab stop.
+2. **Signal inputs.** `vertical` and `multiple` moved from `@Input()`
+   getter/setter pairs to `input()`.
+
+Only the second breaks compilation. The first changes rendered markup and
+behaviour, which no rewrite can carry over, so it is reported instead.
+
+## What it does
+
+The schematic walks every `.ts`, `.html`, `.scss`, `.css` and `.less` file in the
+project (skipping `node_modules` and `dist`). A `.ts` file is inspected only if it
+names a `KbqButtonToggle*` symbol, imports `@koobiq/components/button-toggle` or
+mentions `kbq-button-toggle`; a stylesheet only if it mentions
+`kbq-button-toggle`.
+
+| Auto-fix                | Where                                            |
+| ----------------------- | ------------------------------------------------ |
+| `group.vertical` → `()` | `.ts` on a `KbqButtonToggleGroup`-typed receiver |
+| `group.multiple` → `()` | `.ts` on a `KbqButtonToggleGroup`-typed receiver |
+| `ref.vertical` → `()`   | templates, through `#ref="kbqButtonToggleGroup"` |
+| `ref.multiple` → `()`   | templates, through `#ref="kbqButtonToggleGroup"` |
+
+Receivers are resolved **within the file**, with no cross-file type resolution.
+Covered: method and function parameters, class fields, constructor
+parameter-properties and locals — by explicit type annotation, by an import under
+an alias (`KbqButtonToggleGroup as Group`), or by a `viewChild()` /
+`viewChild.required()` / `contentChild()` / `inject()` initialiser, where the
+signal form is reached through its call (`this.group().multiple`). Not covered:
+a receiver whose type comes from another file (`const g = this.group; g.multiple`,
+an imported const) — those are reported instead of being rewritten.
+
+Resolution is lexical: every declaration of a name is collected, not only the
+button-toggle-typed ones, and the innermost scope containing the access wins. A
+nested `const group = { vertical: 'north' }` therefore shadows an outer
+`KbqButtonToggleGroup` of the same name and is left alone, which matters most in
+spec files, where a `describe` often reuses short names.
+
+Template reference variables are matched through the `exportAs`, in external
+`.html` files and in inline `@Component({ template })` strings alike, with
+whitespace around the dot tolerated (`group . multiple`, or a binding wrapped
+over two lines) and preserved by the rewrite.
+
+Every rewrite is idempotent: an access that is already a call, or is followed by
+`.set` / `.update` / `.asReadonly` / `.subscribe`, is left alone.
+
+## What it reports
+
+**Assignments to `vertical` / `multiple`.** An `input()` is read-only and has no
+`.set()`, so there is nothing to rewrite to — bind the input in the template and
+drive the bound value instead.
+
+**Members that were removed or narrowed**, found on a typed receiver:
+
+| Member                                 | Why                                                                                        |
+| -------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `KbqButtonToggle.mcButton`             | removed — a dead view query with a legacy prefix; use `focus()` / `focusViaKeyboard()`     |
+| `KbqButtonToggle.buttonToggleGroup`    | `protected`, and typed `KbqButtonToggleGroup \| null` — it was non-null while being `null` |
+| `KbqButtonToggle.icons`                | private — read the resulting `iconType` instead                                            |
+| `KbqButtonToggle.iconType`             | read-only getter — reported on assignment only, a read still reads the same                |
+| `KbqButtonToggle.type`                 | read-only getter that follows `multiple` at runtime — reported on assignment only          |
+| `KbqButtonToggleGroup.selected`        | typed `KbqButtonToggle \| KbqButtonToggle[] \| null` instead of `any`                      |
+| `KbqButtonToggleGroup.emitChangeEvent` | takes the toggle the change came from: `emitChangeEvent(toggle)`                           |
+
+**Reads it could not resolve.** A `vertical` / `multiple` read on a receiver that
+is not declared in the file — an imported const, an alias assigned from somewhere
+else — is reported once per file, since a single-file pass cannot tell whether it
+is a group.
+
+**Icon-only toggles with no accessible name.** The template is parsed and every
+`<kbq-button-toggle>` whose content holds an icon and no text at all is reported
+with its line number, unless it carries `aria-label` or `aria-labelledby` (bound
+or static, `[attr.]`-prefixed or not). A `title` does not count: it stays on
+`<kbq-button-toggle>`, while the accessible name is computed for the inner
+`<button>`, and the attribute never reaches it. An icon glyph is `aria-hidden`, so
+such a button is announced as unlabelled — an AXE `button-name` failure — and the
+component now logs a dev-mode warning about it. `aria-label` and `aria-labelledby`
+are inputs of the toggle and are forwarded to the inner button, so the fix is one
+attribute; the schematic cannot invent the text.
+
+**Patterns worth a second look**, in files that already reference the
+button-toggle: anything mentioning `tabindex` (the tab order of a single-selection
+group is one stop now), a leftover `mcButton`, and manual `markForCheck()` calls
+(inert now that a toggle derives its state from signals).
+
+**Stylesheets** that copied the old theme selector `& > .kbq-icon-button`, a class
+`KbqButton` never emitted — it is `.kbq-button-icon` now — or that override the
+keyboard-focus `border-color`, which the theme owns alone since the structural
+stylesheet stopped declaring it.
+
+## What it cannot see
+
+Printed once per run, because no call site points at it:
+
+- the rendered `role` / `aria-checked` / `aria-pressed` and the group's
+  `aria-orientation`, which snapshot and DOM-query tests will notice;
+- arrow keys moving focus and selection together and `Home`/`End` jumping to the
+  ends, with the keydown `preventDefault`-ed;
+- naming the group with a plain `aria-label` / `aria-labelledby` attribute, which
+  it had no role to be announced against before;
+- `disabled` on a standalone toggle finally returning a `boolean` instead of the
+  `null` group it could not find;
+- `tabIndex` defaulting to `null` instead of `undefined`;
+- the group implementing `OnDestroy`, so tearing down a whole selected group no
+  longer emits `valueChange` after destruction;
+- `onTouched` / `registerOnTouched` taking `() => void`, and
+  `KBQ_BUTTON_TOGGLE_GROUP_VALUE_ACCESSOR` being typed `Provider`.
+
+## Usage
+
+```bash
+ng update @koobiq/components@21
+```
+
+Or manually, for a project that is already on 21.0.0:
+
+```bash
+ng g @koobiq/components:button-toggle-signals-and-aria --project "<your project>"
+```
+
+Add `--fix=false` to print what would change without writing anything.