@koobiq/components 20.4.2 → 21.0.1

package/schematics/migrations/v20-upgrade/{data.js → data.cjs}

@@ -1,14 +1,53 @@
 'use strict';
 
+var utils_listItemPattern = require('../../utils/list-item-pattern.cjs');
+var utils_tagPatterns = require('../../utils/tag-patterns.cjs');
+
 /**
- * Replacement data for the v20.0.0 deprecated API removal migration.
- *
- * Each entry uses a RegExp source string in `from` and a literal `to`. The
- * RegExp is compiled with the `g` flag inside the migration driver.
+ * Replacement data for the v20.0.0 deprecated API removal migration, applied by `replacementMigrationRule`.
  *
  * Three buckets are emitted so the schematic can apply each to the right
  * file kind (.ts, .html / inline-template strings, .scss).
  */
+const CORE = '@koobiq/components/core';
+const FILE_UPLOAD = '@koobiq/components/file-upload';
+/** A named import of `symbol` from `module`. */
+const namedImport = (symbol, module) => `\\bimport\\s*(?:type\\s*)?\\{[^}]*\\b${symbol}\\b[^}]*\\}\\s*from\\s*['"]${module}['"]`;
+/** A mention of the Koobiq autocomplete: one of its symbols, its entry point, its `exportAs` or its input. */
+const KBQ_AUTOCOMPLETE = '(?:\\bKbqAutocomplete|@koobiq/components/autocomplete\\b|\\bkbqAutocomplete)';
+/** An opening `<kbq-divider>` tag up to one of its attributes, captured as `$1`. */
+const DIVIDER_TAG = `(<kbq-divider(?![\\w-])${utils_tagPatterns.TAG_BODY}*?)`;
+/** The `="…"` of an attribute. */
+const ATTRIBUTE_VALUE = `(?:\\s*=\\s*(?:"[^"]*"|'[^']*'))`;
+const REMOVED_SYMBOLS = [
+    { name: 'KbqInputFileLabel', module: FILE_UPLOAD },
+    { name: 'KbqInputFile', module: FILE_UPLOAD },
+    { name: 'KbqFileValidatorFn', module: FILE_UPLOAD },
+    { name: 'KbqValidationOptions', module: CORE },
+    { name: 'KBQ_VALIDATION', module: CORE },
+    { name: 'KBQ_SANITY_CHECKS', module: CORE },
+    { name: 'KBQ_SIDEPANEL_WITH_SHADOW', module: '@koobiq/components/sidepanel' },
+    { name: 'mcSanityChecksFactory', module: CORE },
+    { name: 'KbqCommonModule', module: CORE },
+    // A no-op shim kept after the KbqValidateDirective removal. Its calls go, which can leave an empty
+    // `providers: []` behind.
+    { name: 'kbqDisableLegacyValidationDirectiveProvider', module: CORE, call: true }
+];
+/**
+ * A mention of the symbol outside the elements of `[…]` and `{…}` lists: a type annotation, an `@Inject()` token, a
+ * `provide:`, an aliased import. Deleting it there would leave the code broken.
+ */
+const outsideLists = ({ name, call }) => `(?<![\\[{,]\\s*(?:\\btype\\s+)?)\\b${name}\\b|\\b${name}\\b(?!${call ? '(?:\\s*\\(\\s*\\))?' : ''}\\s*[,\\]}])`;
+/**
+ * Removes the symbol with one of its commas from the named imports and exports and the arrays of a file that names
+ * it nowhere else. A file that also uses it elsewhere is left untouched and reported.
+ */
+const removeFromLists = (symbol) => ({
+    from: utils_listItemPattern.listItemPattern(symbol.call ? `\\b${symbol.name}\\(\\s*\\)` : `\\b${symbol.name}\\b`),
+    to: '',
+    unless: outsideLists(symbol),
+    removeImport: { symbol: symbol.name, from: symbol.module }
+});
 /** TypeScript-source replacements (imports + identifiers + method renames). */
 const tsReplacements = [
     // ─── Package moves ─────────────────────────────────────────────────────
@@ -47,9 +86,14 @@ const tsReplacements = [
     // ─── Identifier renames (TypeScript imports / type references) ────────
     { from: '\\bRdxAccordionItemState\\b', to: 'KbqAccordionItemState' },
     { from: '\\bKbqCodeFile\\b', to: 'KbqCodeBlockFile' },
-    { from: '\\bAnimationCurves\\b', to: 'KbqAnimationCurves' },
+    // The import specifier and the uses of the core one only: Angular Material exports an `AnimationCurves` too.
+    {
+        from: `\\bAnimationCurves\\b(?:(?=[^{}]*\\}\\s*from\\s*['"]${CORE}['"])|` +
+            `(?<=${namedImport('AnimationCurves', CORE)}[\\s\\S]*))`,
+        to: 'KbqAnimationCurves'
+    },
     { from: '\\bMeasurementSystem\\b', to: 'KbqMeasurementSystem' },
-    { from: '\\bSizeUnitsConfig\\b', to: 'KbqSizeUnitsConfig' },
+    { from: '\\bSizeUnitsConfig\\b', to: 'KbqSizeUnitsLocaleConfiguration' },
     { from: '\\bKbqNavbarIcModule\\b', to: 'KbqNavbarModule' },
     { from: '\\bKbqNavbarIcItem\\b', to: 'KbqNavbarItem' },
     { from: '\\bKbqNavbarIcHeader\\b', to: 'KbqNavbarHeader' },
@@ -60,73 +104,14 @@ const tsReplacements = [
     { from: '\\bKbqExtendedTooltipTrigger\\b', to: 'KbqTooltipTrigger' },
     { from: '\\bKbqDatepickerToggle\\b(?!Icon)', to: 'KbqDatepickerToggleIconComponent' },
     { from: '\\bKbqFilterBarSearch\\b', to: 'KbqSearchExpandable' },
-    {
-        from: '\\bKbqInputFileLabel\\b',
-        to: '',
-        removeImport: { symbol: 'KbqInputFileLabel', from: '@koobiq/components/file-upload' }
-    },
-    {
-        from: '\\bKbqInputFile\\b',
-        to: '',
-        removeImport: { symbol: 'KbqInputFile', from: '@koobiq/components/file-upload' }
-    },
-    {
-        from: '\\bKbqFileValidatorFn\\b',
-        to: '',
-        removeImport: { symbol: 'KbqFileValidatorFn', from: '@koobiq/components/file-upload' }
-    },
-    {
-        from: '\\bKbqValidationOptions\\b',
-        to: '',
-        removeImport: { symbol: 'KbqValidationOptions', from: '@koobiq/components/core' }
-    },
     { from: '\\bKbqFormFieldRef\\b', to: 'KbqFormField' },
     // Deprecated dropdown position type aliases → Kbq-prefixed names. The
     // `\b…\b` boundaries make these idempotent: `KbqDropdownPositionX` is not
     // re-matched because the `D` is preceded by a word char (`q`).
     { from: '\\bDropdownPositionX\\b', to: 'KbqDropdownPositionX' },
     { from: '\\bDropdownPositionY\\b', to: 'KbqDropdownPositionY' },
-    // ─── Tokens / function renames ────────────────────────────────────────
-    {
-        from: '\\bKBQ_VALIDATION\\b',
-        to: '',
-        removeImport: { symbol: 'KBQ_VALIDATION', from: '@koobiq/components/core' }
-    },
-    {
-        from: '\\bKBQ_SANITY_CHECKS\\b',
-        to: '',
-        removeImport: { symbol: 'KBQ_SANITY_CHECKS', from: '@koobiq/components/core' }
-    },
-    {
-        from: '\\bKBQ_SIDEPANEL_WITH_SHADOW\\b',
-        to: '',
-        removeImport: { symbol: 'KBQ_SIDEPANEL_WITH_SHADOW', from: '@koobiq/components/sidepanel' }
-    },
-    {
-        from: '\\bmcSanityChecksFactory\\b',
-        to: '',
-        removeImport: { symbol: 'mcSanityChecksFactory', from: '@koobiq/components/core' }
-    },
-    {
-        from: '\\bKbqCommonModule\\b',
-        to: '',
-        removeImport: { symbol: 'KbqCommonModule', from: '@koobiq/components/core' }
-    },
-    {
-        // No-op shim kept after the KbqValidateDirective removal in v20.0.0 is
-        // gone in this release. Strip the call, its trailing comma, and the
-        // import; the array/empty-providers cleanup happens via the extended
-        // `[ , … ]` / `[ … , ]` normalize pass in the driver.
-        from: '\\bkbqDisableLegacyValidationDirectiveProvider\\(\\s*\\),?\\s*',
-        to: '',
-        note: 'kbqDisableLegacyValidationDirectiveProvider was a no-op shim kept after the ' +
-            'KbqValidateDirective removal in v20.0.0; it is removed in this release. ' +
-            'You may also need to remove the (now-empty) `providers: []` key from the affected decorator.',
-        removeImport: {
-            symbol: 'kbqDisableLegacyValidationDirectiveProvider',
-            from: '@koobiq/components/core'
-        }
-    },
+    // ─── Removed symbols / function renames ───────────────────────────────
+    ...REMOVED_SYMBOLS.map(removeFromLists),
     {
         from: '\\btoBoolean\\(',
         to: 'booleanAttribute(',
@@ -145,7 +130,12 @@ const tsReplacements = [
         removeImport: { symbol: 'formatDataSize', from: '@koobiq/components/core' }
     },
     // ─── Method renames on instances ──────────────────────────────────────
-    { from: '\\.openPanel\\(', to: '.open(' },
+    // `KbqAutocompleteTrigger.openPanel()`, in a file that uses the Koobiq autocomplete: the autocomplete trigger of
+    // Angular Material keeps its `openPanel()`.
+    {
+        from: `\\.openPanel\\((?:(?<=${KBQ_AUTOCOMPLETE}[\\s\\S]*)|(?=[\\s\\S]*${KBQ_AUTOCOMPLETE}))`,
+        to: '.open('
+    },
     { from: '\\.toggleIsCollapsed\\(', to: '.toggle(' },
     { from: '\\.focusViaKeyboard\\(', to: '.focus(' },
     // ─── Modal options object key ─────────────────────────────────────────
@@ -192,13 +182,27 @@ const templateReplacements = [
     { from: '="kbqDatepickerToggle"', to: '="kbqDatepickerToggleIcon"' },
     // ─── Attribute renames ────────────────────────────────────────────────
     { from: '\\bkbqFormFieldWithoutBorders\\b', to: 'noBorders' },
+    // ─── KbqFilterBarSearch inputs → KbqSearchExpandable inputs ───────────
+    // The selector rewrite above only renames the tag: without these the inputs
+    // of the removed KbqFilterBarSearch survive as attributes the new component
+    // does not have. Scoped to the attribute forms (`[x]` binding, `x="…"`
+    // static, bare attribute) so the identifiers elsewhere are never touched.
+    // The bare `emitValueByEnter` and the everyday word `tooltip` are additionally anchored to an
+    // opening `<kbq-search-expandable` tag — already renamed by the selector rule above. Template
+    // replacements run over the whole text of every `.ts` file, so an unanchored rule would also
+    // rewrite TypeScript expressions such as `this.emitValueByEnter && …`.
+    { from: '\\[emitValueByEnter\\]', to: '[isEmitValueByEnterEnabled]' },
+    { from: '\\bemitValueByEnter="', to: 'isEmitValueByEnterEnabled="' },
+    { from: '(<kbq-search-expandable\\b[^>]*?\\s)emitValueByEnter(?![\\w-])', to: '$1isEmitValueByEnterEnabled' },
+    { from: '\\[onSearchTimeout\\]', to: '[emitValueTimeout]' },
+    { from: '\\bonSearchTimeout="', to: 'emitValueTimeout="' },
+    { from: '(<kbq-search-expandable\\b[^>]*?\\s)\\[tooltip\\]', to: '$1[tooltipText]' },
+    { from: '(<kbq-search-expandable\\b[^>]*?\\s)tooltip="', to: '$1tooltipText="' },
     // ─── KbqCodeBlock deprecated input renames ────────────────────────────
-    // Scoped strictly to the attribute form (`[x]` binding or `x="…"` static)
-    // so the common words `canDownload` / `files` elsewhere are never touched.
-    { from: '\\[canLoad\\]', to: '[canDownload]' },
-    { from: '\\bcanLoad="', to: 'canDownload="' },
-    { from: '\\[codeFiles\\]', to: '[files]' },
-    { from: '\\bcodeFiles="', to: 'files="' },
+    // `[x]="…"`, `x="…"` and a valueless `x`, only on a `<kbq-code-block>` that does not bind the replacement
+    // as well: the two bindings would end up under one name. Such a tag is reported below.
+    { from: String.raw `${utils_tagPatterns.codeBlockTagWithout('canDownload')}canLoad(?=\]?[\s=/>])`, to: '$1canDownload' },
+    { from: String.raw `${utils_tagPatterns.codeBlockTagWithout('files')}codeFiles(?=\]?[\s=/>])`, to: '$1files' },
     // ─── Tooltip warning trigger → kbqTooltip + modifier ───────────────────
     // Two-step: first add modifier attribute, then rename binding key.
     // The modifier insertion must come before the binding rename otherwise we
@@ -214,8 +218,9 @@ const templateReplacements = [
         to: 'kbqTooltipModifier="extended" [kbqTooltip]'
     },
     // ─── Divider deprecated inset attribute ───────────────────────────────
-    { from: '\\s\\[inset\\]="[^"]*"', to: '' },
-    { from: '\\sinset(\\s|>|/)', to: '$1' }
+    // Only on a `<kbq-divider>`: in code `inset` is any identifier, and other dividers have an input of that name.
+    { from: `${DIVIDER_TAG}\\s\\[inset\\]${ATTRIBUTE_VALUE}`, to: '$1' },
+    { from: `${DIVIDER_TAG}\\sinset${ATTRIBUTE_VALUE}?(?=[\\s/>])`, to: '$1' }
 ];
 /** SCSS replacements (CSS class selectors that were renamed at the runtime level). */
 const scssReplacements = [
@@ -225,6 +230,10 @@ const scssReplacements = [
     { from: '\\.kbq-datepicker-toggle(?!-icon)\\b', to: '.kbq-datepicker-toggle-icon' },
     { from: '\\.kbq-form-field_without-borders\\b', to: '.kbq-form-field_no-borders' }
 ];
+/**
+ * Patterns that we can't safely auto-fix — surface them to the user with file
+ * locations so they can migrate manually, whether or not the fix is applied.
+ */
 const warnPatterns = [
     {
         pattern: '\\(onSaveAsNew\\)',
@@ -261,11 +270,49 @@ const warnPatterns = [
         message: 'KbqCodeBlock.canLoad → canDownload and .codeFiles → files. Template bindings are auto-migrated; ' +
             'update any programmatic (TypeScript) access manually.'
     },
+    {
+        pattern: `${utils_tagPatterns.codeBlockTagWith('canLoad', 'canDownload')}|${utils_tagPatterns.codeBlockTagWith('codeFiles', 'files')}`,
+        message: 'A <kbq-code-block> that binds `canLoad` next to `canDownload`, or `codeFiles` next to `files`, was ' +
+            'left untouched: merge each pair into one `canDownload` / `files` binding. Manual migration required.'
+    },
+    {
+        pattern: '\\[initialValue\\]|\\binitialValue="',
+        message: 'KbqFilterBarSearch.initialValue has no counterpart in kbq-search-expandable: the component ' +
+            'is a form control with no separate value input. Seed the bound [formControl] / [(ngModel)] ' +
+            'with the value instead. Manual migration required.'
+    },
+    {
+        pattern: '\\(onSearch\\)',
+        message: 'KbqFilterBarSearch.onSearch was removed. kbq-search-expandable reports the query through its ' +
+            'form binding — read the bound control (valueChanges) instead. Manual migration required.'
+    },
+    {
+        // Everything but the element form, which the template replacements above rewrite: a leading `<` or
+        // `</` is the tag, a leading `.` the stylesheet class the scss replacements handle.
+        pattern: '(?<![</.\\w-])kbq-filter-search\\b',
+        message: 'KbqFilterBarSearch also matched as an attribute (<div kbq-filter-search>), which ' +
+            'kbq-search-expandable does not: its selector is element-only, so the attribute would silently ' +
+            'match nothing after the upgrade. Replace the host element with <kbq-search-expandable> by hand. ' +
+            'Manual migration required.'
+    },
+    {
+        pattern: '<kbq-filter-search\\b',
+        message: 'KbqFilterBarSearch.onSearchTimeout defaulted to 0 while kbq-search-expandable.emitValueTimeout ' +
+            'defaults to 200: markup that never set the timeout emitted on every keystroke and now waits ' +
+            '200ms. The rename itself is auto-migrated — add [emitValueTimeout]="0" to keep the old timing.'
+    },
     {
         pattern: '\\brequired:\\s*(true|false)',
         message: 'KbqFilter.required is deprecated — use cleanable = false and removable = false instead. ' +
             'NOTE: this warning is best-effort and may match unrelated `required:` keys; verify it is a KbqFilter config.'
-    }
+    },
+    ...REMOVED_SYMBOLS.map((symbol) => ({
+        anchor: `\\b(?:import|export)\\s*(?:type\\s*)?\\{[^}]*\\b${symbol.name}\\b[^}]*\\}\\s*from\\s*['"]${symbol.module}['"]`,
+        pattern: outsideLists(symbol),
+        message: `\`${symbol.name}\` was removed in 20.0.0 with nothing in its place. This file uses it outside an ` +
+            'import or a list, e.g. as a type, an `@Inject()` token or a `provide:`, so it was left untouched: ' +
+            'remove those uses, and the code that depends on them, by hand. Manual migration required.'
+    }))
 ];
 
 exports.scssReplacements = scssReplacements;

package/schematics/migrations/v20-upgrade/index.cjs

@@ -0,0 +1,19 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var utils_replacementDriver = require('../../utils/replacement-driver.cjs');
+var migrations_v20Upgrade_data = require('./data.cjs');
+require('../../utils/list-item-pattern.cjs');
+require('../../utils/messages.cjs');
+require('../../utils/package-config.cjs');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+require('../../utils/project-files.cjs');
+require('../../utils/tag-patterns.cjs');
+
+function v20Upgrade(options) {
+    return utils_replacementDriver.replacementMigrationRule({ label: '[v20-upgrade]', tsReplacements: migrations_v20Upgrade_data.tsReplacements, templateReplacements: migrations_v20Upgrade_data.templateReplacements, scssReplacements: migrations_v20Upgrade_data.scssReplacements, warnPatterns: migrations_v20Upgrade_data.warnPatterns }, options);
+}
+
+exports.default = v20Upgrade;

package/schematics/migrations/v21-upgrade/README.md

@@ -0,0 +1,271 @@
+# v21-upgrade
+
+Migration invoked by `ng update @koobiq/components@21`. It removes the uses of the APIs that were deprecated
+before 21.0.0 and removed in it: renamed members and aliases are rewritten, everything else is reported with the
+replacement to use. It also reports the uses of the state that 21.0.0 turned into signals.
+
+The schematic walks every `.ts`, `.html`, `.scss` and `.css` file of the project (skipping `node_modules` and
+`dist`), and the `styles` of the project's targets in `angular.json`. The tables live in `data/`, one file per
+area, and `data.ts` gathers them:
+
+- **`tsReplacements`** — TypeScript imports, identifiers and member accesses;
+- **`templateReplacements`** — attributes and bindings in templates, external or inline;
+- **`scssReplacements`** — selectors in style sheets;
+- **`styleEntryReplacements`** — the `styles` entries in `angular.json`; an entry they turn into a duplicate is
+  dropped;
+- **`warnPatterns`** — what cannot be rewritten, reported with what to do instead.
+
+## What it changes
+
+**Accordion** — rewrites nothing; reports the `kbq-accordion-trigger__action` class in templates, styles and code:
+move the actions out of the trigger into a `kbq-accordion-header__actions` element next to it.
+
+**Code block and icon button**
+
+- Rewrites `canLoad` → `canDownload` and `codeFiles` → `files` on `<kbq-code-block>`: bindings, static
+  and valueless attributes.
+- Rewrites `small` on an icon button to `size`: `[small]="true"` and `small="true"` → `size="compact"`,
+  `[small]="false"` → `size="normal"`, any other binding → `[size]="(expr) ? 'compact' : 'normal'"`.
+- Rewrites the `kbq-icon-button_small` class to `kbq-icon-button_compact` in styles and code.
+- Reports a code block that binds an alias next to its replacement or binds `canDownload` or `files` twice
+  (what the 20.0.0 migration made of such a pair), an icon button that sets both
+  `small` and `size` or a static `small` other than `"true"`, programmatic `canLoad` / `codeFiles` /
+  `canLoadInput` / `codeFilesInput` / `small`, and `scrollableCodeContent`, which is removed.
+
+**Core** — rewrites:
+
+- `KbqThemeSelector.Default` → `KbqThemeSelector.Light` and `KbqThemeNames.Default` → `KbqThemeNames.Light`, in
+  code and templates;
+- `KbqDefaultThemes` → `KBQ_DEFAULT_THEMES` and `KbqTheme` → `KbqThemeConfig` (an import clause that held both
+  names keeps one);
+- `ThemePalette.Error`, `.Warning` and `.Success` → the `KbqComponentColors` members of the same value, dropping
+  the `ThemePalette` import once nothing else names it;
+- the `mcLine` and `mcListIcon` aliases → `kbq-line` and `kbq-list-icon`, as attributes in templates and as
+  attribute selectors in strings and stylesheets; elsewhere in code the names are the app's own.
+
+Reports:
+
+- `KbqTheme`: `KbqThemeConfig` requires `colorScheme` and has no `selected`;
+- `ThemeService` imported from `@koobiq/components/core`: inject `KbqThemeService` and the member to use for each
+  old one;
+- `getOptionScrollPosition` imported from `@koobiq/components/core`: `KbqOption.focus()` or `kbqFocusAndReveal()`;
+- any other use of `ThemePalette`: `Primary`, `Secondary`, `Info` and `Default` styled nothing, `Empty` becomes an
+  unset `color`, a type or a template field becomes `KbqComponentColors`;
+- a re-export of `ThemePalette` from `@koobiq/components/core`, left as is: `KbqComponentColors` has other members
+  and values;
+- the undocumented exports nothing in the library used, imported from `@koobiq/components/core`: the pop-up
+  position lists, `ARROW_BOTTOM_MARGIN_AND_HALF_HEIGHT`, `SELECT_PANEL_VIEWPORT_PADDING`, `NUMBER_FORMAT_REGEXP`,
+  `isWithin`, `KBQ_SELECT_SCROLL_STRATEGY_PROVIDER`, `KBQ_CHECKABLE_CONTROL_VALUE_ACCESSOR`, `KbqHover`, `CanColor`,
+  `KbqAnimationCurves`, `KbqAnimationDurations`, `KbqRectangleItem`, `countGroupLabelsBeforeOption`, `KbqLineSetter` and
+  `KbqLine`, each with what to do instead;
+- `.lines` in a file that names `KbqListItem` or uses `kbq-list-item`, and `.hasPlaceholder()` in one that names
+  `KbqSelectSearch`: both were removed, query the `kbq-line` elements and read the placeholder yourself;
+- a call of `.handleBodyInteraction()`, and a read of `.isSpecialFormatForRULocale()` or `.roundingOptions`,
+  private members of the number pipes now;
+- in a subclass of a pop-up or of its trigger, `markForCheck()`, `warning` or `closeOnInteraction` on `this`,
+  `super` or `instance`, or overridden: delete a `markForCheck()` after `updateClassMap()` or a visibility change,
+  which re-render the pop-up, and use `changeDetectorRef.markForCheck()` or `instance.detectChanges()` for another
+  field;
+- in a subclass of a pop-up, `elementRef` re-declared as a field, decorated or not, or as a constructor parameter
+  property: override the `KbqPopUp.elementRef` getter over a `viewChild()`;
+- `.isRow` in a file that names `KbqFormElement` or `kbqFormElement`: check the `kbq-form__row` class;
+- deprecated for removal in 22.0.0: the unprefixed date pipes and their `ImpurePipe` twins (in templates and as
+  imported classes), the `mcHighlight` pipe, `isDigit`, `isBoolean`, `KbqMeasureScrollbarService`,
+  `FocusKeyManager.getFocusOrigin()` and `dateInput` of the datepicker locale configuration, each with its
+  replacement.
+
+**Dropdown and select** — rewrites:
+
+- `DropdownPositionX` / `DropdownPositionY` → `KbqDropdownPositionX` / `KbqDropdownPositionY` in a file that names
+  `@koobiq/components/dropdown` (an import clause that held both names keeps one);
+- `KbqSelectPanelWidth` and `KbqTreeSelectPanelWidth` → `KbqPanelWidth`, moving the import from the select or
+  tree-select entry point to `@koobiq/components/core`.
+
+Reports:
+
+- `.triggerWidth` in a file that imports `@koobiq/components/dropdown` or uses `<kbq-dropdown>`, and `triggerWidth`
+  in a `KbqDropdownPanel` implementation or a `KbqDropdown` subclass: delete it, set `KbqDropdownTrigger.widthOrigin`
+  to match another element;
+- `.offsetY` (not a call — that is the `KbqDropdownTrigger` input) in a file that uses `kbq-select`,
+  `kbq-tree-select` or `kbq-timezone-select`, and an `offsetY` field of their subclasses: delete it, the gap is the
+  `--kbq-connected-overlay-gap` CSS variable;
+- `AUTOCOMPLETE_PANEL_HEIGHT` imported from `@koobiq/components/autocomplete`: keep a constant of your own;
+- `DropdownPositionX` / `DropdownPositionY` in a file that does not name the dropdown entry point, and an aliased
+  import or a re-export of `KbqSelectPanelWidth` / `KbqTreeSelectPanelWidth`: rename them by hand;
+- `.clearValue` (except on `this` and on a form field, whose `clearValue()` stays) in a file that uses one of the
+  selects, and `clearValue` in their subclasses: project `<kbq-cleaner />`, or reset the form control from code;
+- the `kbq-dropdown__group-header_small` class in templates, styles and code: use `<kbq-optgroup label="…" />`.
+
+**Filter bar** — rewrites:
+
+- `KbqFilterBarRefresher` → `KbqFilterRefresher` (an import clause that held both names keeps one);
+- `KbqPipeMinWidth`: drops it from the `@koobiq/components/filter-bar` import and from `imports` arrays, and the
+  `kbqPipeMinWidth` attribute from templates.
+
+Reports:
+
+- `.changes` in a file that names `KbqFilterBar`: read `filter()` in an `effect()` or listen to `(filterChange)`;
+- any other `KbqPipeMinWidth` reference (an aliased import, a subclass, a query): remove it;
+- a `required:` key next to `cleanable:`, `removable:` or `type: KbqPipeTypes.…` in the same object literal, in a
+  file that imports `@koobiq/components/filter-bar`: delete it, set `cleanable: false` and `removable: false`;
+- `.required` read on `data` or on a receiver named like a pipe, in a file that imports the filter bar or uses
+  `kbq-pipe` classes: read `cleanable` and `removable` instead.
+
+**Form field** — rewrites nothing: none of the removed APIs has a 1:1 replacement. Reports:
+
+- `KbqPasswordHint`, `PasswordRules`, `regExpPasswordValidator` and `hasPasswordStrengthError` imported from
+  `@koobiq/components/form-field`: put the rules on the control as validators (`PasswordValidators`) and show them
+  with `<kbq-reactive-password-hint [hasError]="…">`;
+- `kbq-password-hint` and `kbq-password-hint__icon` in templates, styles and selectors in code;
+- a check of the `passwordStrength` error in a file that uses the form field or the input: the form field no longer
+  sets it;
+- `.passwordHints`, `.onKeyDown()` on a receiver named like a form field and `.hasPasswordHint`, in a file that
+  names `KbqFormField` or `kbqFormField`;
+- every `canCleanerClearByEsc`: it had no effect, delete it;
+- `.checkRules()` and `.checkRule.next()` / `.subscribe()` / `.pipe()` / `.complete()` in a file that names
+  `KbqInputPassword` or `kbqInputPassword`: call `control.updateValueAndValidity()` instead;
+- `.connectTo()` (except on `this`) in a file that names `KbqStepper`, `kbqStepper` or `<kbq-stepper>`: it was a
+  no-op, delete it.
+
+**Forms controls** — rewrites the `TransitionCheckState` import from `@koobiq/components/checkbox` into the
+`@koobiq/components/core` one, and reports an aliased import, a re-export or a namespace read of it. Reports, in a
+file that names `KbqCheckbox`, `KbqToggleComponent` or their tags:
+
+- a use of `.writeValue`, `.registerOnChange`, `.registerOnTouched` or `.setDisabledState` (except on `this`): set
+  `checked` / `disabled`, listen to `(change)`, or call it on the host `KbqCheckable`;
+- a use of `.onTouched` (except on `this`), checkbox only: forms never called it, delete it;
+- a call of `.onLabelTextChange()` (except on `this`), toggle only: it does nothing now and is deprecated for
+  removal in 22.0.0, delete it;
+- a read of `currentCheckState` without the call in a class that extends `KbqToggleComponent`: it is a signal now.
+
+**Navbar, ellipsis center, description list and loader overlay** — rewrites:
+
+- `minWidth` → `verticalBreakpoint` on `<kbq-dl>`, as a binding or a static attribute, unless the tag sets
+  `verticalBreakpoint` too;
+- `longTitle` on `kbq-navbar-brand` (a binding, a static or a valueless attribute): dropped, the two-line title is
+  detected automatically.
+
+Reports:
+
+- every dropped `longTitle`: a forced `true` or `false` has no replacement;
+- `.longTitle()` and `setInput('longTitle', …)` in a file that names `KbqNavbarBrand` or `kbqNavbarBrand`;
+- `.getTitleWidth()` in a file that names `KbqNavbarItem` or `kbqNavbarItem`, and `.outerElementWidth` in one that
+  names `KbqNavbarTitle`: call `getOuterElementWidth()` on the title;
+- `.resizeStream` in a file that names `KbqEllipsisCenterDirective`: delete it;
+- a `<kbq-dl>` that sets both `minWidth` and `verticalBreakpoint`: `minWidth` took precedence, move its value;
+- a renamed `minWidth` whose value is not a number literal: `minWidth` fell back to 400 on `null`, `''` or `700px`,
+  `verticalBreakpoint` reads them as `NaN` and never switches to the vertical layout;
+- `.minWidth()` and `setInput('minWidth', …)` in a file that names `KbqDlComponent`: use `verticalBreakpoint`.
+- `transparent` and `card` on `<kbq-loader-overlay>`, and their reads and `setInput()` in a file that names
+  `KbqLoaderOverlay`: deprecated for removal in 22.0.0, set `surface` instead.
+
+**Popover**
+
+- Rewrites the unprefixed inputs of `KbqPopoverTrigger` and `KbqPopoverConfirmTrigger` — `[name]=`, `name=` and a
+  bare `name` — on an element that carries `kbqPopover` or `kbqPopoverConfirm`: `hideIfNotInViewPort`,
+  `defaultPaddings`, `container`, `hasBackdrop`, `hasCloseButton`, `closeOnScroll` and `backdropClass` become
+  `kbqPopoverHideIfNotInViewPort`, `kbqPopoverDefaultPaddings`, and so on. The same inputs of other components
+  are left alone.
+- Reports `getKbqPopoverInvalidPositionError`, a read of `KbqPopoverTrigger.hideIfNotInViewPort` (use
+  `popoverHideIfNotInViewPort()`) and a `hostDirectives` entry of `KbqPopoverTrigger` that exposes one of the
+  unprefixed inputs.
+
+**State as signals** — rewrites nothing; reports, each in a file that uses the entry point (an import in code, the
+element in a template):
+
+- `.value`, `.getValue()`, `.next()`, `.subscribe()`, `.pipe()` and `| async` on the flags, `unreadItemsCounter` and
+  `groupedItems` of the notification center, and a subscription to its `changes`, which no longer emits on
+  subscription;
+- the same on `hovered` and `focused` of the toast service and component;
+- the same on `hovered` of a pop-up or its trigger (tooltip, popover, notification center, app switcher), but
+  not on `KbqDropdownItem.hovered`, which stays an event stream;
+- a subscription to, an assignment of or `| async` on `filteredOptions` of the filter bar, `super.ngOnInit()` in a
+  subclass of `KbqPipeSelectComponent`, the date pipe flags read as fields in a subclass, `returnButton()`
+  dereferenced in such a subclass, and a date pipe template that still hides the calendars on Tab with
+  `hideCalendars()`;
+- `hiddenItems` of `KbqSelect` read as a field;
+- `.value.next()`, `.value.getValue()`, `.value.subscribe()` and the like on `KbqSearchExpandable`;
+- `super.ngAfterContentInit()` and `super.ngOnDestroy()` in a subclass of `KbqDatepickerToggleIconComponent`.
+
+**Styles** — rewrites:
+
+- the arguments of `koobiq-theme()`, `koobiq-typography()` and `kbq-core-theme()`, dropped unless they hold
+  parentheses (a map, a function call);
+- `prebuilt-themes/light-theme.css` and `dark-theme.css` → `theme.css` in style sheets, code, templates and the
+  `styles` of `angular.json`, keeping one load where both themes were loaded in the same import block;
+- the unprefixed markdown typography classes (`md-h1`…`md-h6`, `md-body`, `md-body-mono`, `md-caption`,
+  `md-table-cell`, `md-table-header`) → `kbq-md-*` in `class` attributes, `[class.…]` bindings and selectors.
+
+Reports:
+
+- arguments of those mixins that hold parentheses;
+- `kbq-contrast()`, `kbq-palette()`, `kbq-color()` and `kbq-typography-config()`;
+- `kbq-light-theme()` and `kbq-dark-theme()`, deprecated for removal in 22.0.0;
+- deprecated for removal in 22.0.0 too, the `kbq-scrollbar` class, which no library component carries any more (a
+  selector, a `class` attribute or host property, `[class.…]`, an `[ngClass]` key, `classList` and `addClass()`),
+  `kbq-scrollbar-theme()`, and its `--kbq-scrollbar-*` variables the new scrollbar does not share: use
+  `kbqNativeScrollbar` or `<kbq-scrollbar>`;
+- a `@use`, `@import` or `@forward` of `@koobiq/components/core/styles/tokens`: load the design tokens modules
+  directly;
+- a load of the removed modules `core/styles/functions` (its index, `number`, `string`),
+  `typography/typography-utils`, `common/clearfix` and `common/popup`, a call of the removed
+  `kbq-markdown-typography-config()`, the `typography-utils` getters, `popup-params`, `input-placeholder`,
+  `rtl-value()` and `kbq-typography-css-variables`, and, in a file that loads `core/styles/functions`, a timing
+  variable other than `$ease-out-circ`, `$ease-in-out-quad` and `$ease-in-out-circ`;
+- an unprefixed markdown class in any other string, such as `classList.add('md-h1')` or `[ngClass]`.
+
+**Tags** — rewrites nothing; reports, in a file that names `KbqTagInput` or its `exportAs`:
+
+- a read of `.ngControl` (except `this.ngControl` and a `…List.ngControl`): read the control bound to the input;
+- a call of `.triggerValidation()` (except on `this`): a no-op, delete it;
+- a subclass of `KbqTagInput` that mentions either member.
+
+`KbqTagTextControl.ngControl` is not reported: the interface is not exported.
+
+**Toast**
+
+- Rewrites `--kbq-toast-stack-size-margin-top` → `--kbq-toast-stack-size-margin-vertical` and
+  `--kbq-toast-stack-size-margin-right` → `--kbq-toast-stack-size-margin-horizontal` in styles, templates and code.
+- Reports a file that declares both a removed and a new name, and `dispatchScrollEvent` in a file that names
+  `KbqToastContainerComponent` or uses `<kbq-toast-container>`: delete the call.
+
+**Tree** — rewrites the listeners of the outputs deprecated for removal in 22.0.0, which emit the same events as
+their replacements: `(onSelectAll)` → `(selectAllChange)` and `(onCopy)` → `(copyChange)` on
+`<kbq-tree-selection>`, `(onSelectionChange)` → `(selectionChange)` on `<kbq-tree-option>`. Reports:
+
+- `.isUserInput` in a file that names `KbqTreeOptionChange`, and `$event.isUserInput` bound to an output of
+  `<kbq-tree-option>`: it was always `false`, delete the check;
+- `new KbqTreeOptionChange(…)` with a second argument, and a `super(…)` call with one in a subclass: drop it;
+- `.onSelectAll` / `.onCopy` in a file that names `KbqTreeSelection`, and `.onSelectionChange` in a file that
+  names `KbqTreeOption`: use the replacement output;
+- `.mostRecentTreeNode` in a file that imports `@koobiq/components/tree`: deprecated, nothing reads it.
+
+The `isUserInput` of `KbqOptionSelectionChange` and `KbqTreeSelectChange` stays and is not reported, nor are the
+`onSelectAll` and `onCopy` of `kbq-list-selection` and the `onSelectAll` of `kbq-tree-select`, which are not
+deprecated.
+
+**Unused component API** — rewrites nothing; reports what was removed without a deprecation because nothing in the
+library used it:
+
+- imported from their entry point: `normalizeSplitter`, `isInt` and `isDigit` of the input,
+  `KbqTimeRangeTranslateTypeMap` of the time range, `KbqTabBodyOriginState` and `KbqDatepickerIntl`;
+- in a file that names the component: `KbqDropdown.onPanelReached()`, `tagSelectionChanges` and `shouldLabelFloat`
+  of `KbqTagList`, and `KbqTreeNodeOutlet.changeDetectorRef`;
+- in a subclass, through `this` or `super`: the protected `changeDetectorRef` of the accordion, accordion item,
+  password toggle, icons and expandable search, `KbqAccordionTrigger.nativeElement`,
+  `KbqNotificationCenterComponent.dateAdapter`, `KbqFilters.styles`, `setFocusedOption()` and `getItemHeight()` of
+  `KbqTreeSelection`, and
+  `isHorizontalOverflown`, `isVerticalOverflown` and `child` of `KbqTitleDirective`;
+- the `kbq-control_has-validate-directive`, `kbq-form-field_has-validate-directive` and `kbq-no-select` classes in
+  templates, styles and code: nothing sets them.
+
+## Running it manually
+
+```bash
+ng g @koobiq/components:v21-upgrade --project "<your project>"
+```
+
+| Option    | Default | Description                                                    |
+| --------- | ------- | -------------------------------------------------------------- |
+| `project` | —       | Project to migrate; the whole workspace when omitted.          |
+| `fix`     | `true`  | Applies the rewrites; with `false`, only reports what changes. |