@koobiq/components 20.4.2 → 21.0.1

package/schematics/migrations/tree-state-saving-default/data.cjs

@@ -0,0 +1,78 @@
+'use strict';
+
+/**
+ * Data for the `tree-state-saving-default` migration.
+ *
+ * `KbqTreeSelection` and `KbqTree` persist their expanded nodes now, and `useStateSaving` defaults to
+ * `true`. A tree that was never configured to persist anything comes back with the branches the user
+ * left open, which changes four things a consumer can only find out by reading:
+ *
+ * - The key is derived from where the tree sits in the document when no `stateSavingKey` is given, so
+ *   restructuring the markup above it strands what was saved under the previous key.
+ * - Expansion is persisted by the value `FlatTreeControl.getValue` returns, which must therefore be a
+ *   stable, unique string rather than something derived from the node's position or object identity.
+ * - Expansion the application performs itself is not persisted until something else is.
+ * - A `NestedTreeControl` has no `getValue`, so a tree built on one persists nothing.
+ *
+ * Warn-only. The markup whose behaviour changed is exactly the markup that says nothing about the
+ * input, so there is no expression to rewrite — and rewriting it to `[useStateSaving]="false"` would
+ * withhold the feature this release is shipping.
+ */
+/** Import specifiers that mark a file as a tree consumer. */
+const TREE_PACKAGE = '@koobiq/components/tree';
+/** Identifier and element shapes that mark a consumer without an import. */
+const TREE_TYPE = '\\bKbqTreeSelection\\b|\\bKbqTree\\b|\\bkbq-tree-selection\\b|\\bkbq-tree\\b';
+/** The rendered element, which is what the default flip reaches. `<kbq-tree` also opens the selection. */
+const TREE_ELEMENT = '<kbq-tree-selection\\b|<kbq-tree[\\s>]';
+const warnPatterns = [
+    {
+        anchor: TREE_ELEMENT,
+        pattern: TREE_ELEMENT,
+        unless: '\\buseStateSaving\\b',
+        message: 'Trees persist their expanded nodes by default now: useStateSaving defaults to true. Pass ' +
+            '[useStateSaving]="false" to keep the previous behaviour. To keep persistence but pin where ' +
+            'the state is stored, give the tree a stateSavingKey — or an id, which anchors the key ' +
+            'derived from the document just as well. Selection is not persisted; it stays with the form ' +
+            'control the tree is bound to.'
+    },
+    {
+        anchor: 'new\\s+FlatTreeControl\\b',
+        pattern: 'new\\s+FlatTreeControl\\b',
+        unless: '\\[useStateSaving\\]="false"',
+        message: 'Expansion is persisted by the value getValue returns — the third argument of the ' +
+            'FlatTreeControl constructor. Check that it returns a string that is stable across reloads ' +
+            'and unique within the tree: a value derived from the node index, or from the node object, ' +
+            'restores the wrong branches. Where two nodes share a value, the first of them is expanded.'
+    },
+    {
+        anchor: TREE_TYPE,
+        pattern: '\\.\\s*(expandAll|collapseAll|expandDescendants|collapseDescendants)\\s*\\(|\\.\\s*expansionModel\\b',
+        message: 'Expansion the application performs itself is not persisted on its own — only what a user ' +
+            'expands or collapses is. Call saveState() on the tree after expanding programmatically if ' +
+            'that state should be restored on the next visit.'
+    },
+    {
+        anchor: 'new\\s+NestedTreeControl\\b',
+        pattern: 'new\\s+NestedTreeControl\\b',
+        message: 'A tree on a NestedTreeControl persists nothing: the control has no getValue, so there is no ' +
+            'stable identity to store a node under. A warning is logged in dev mode; unset ' +
+            'useStateSaving on that tree to silence it.'
+    }
+];
+/** Printed once, after the per-file reports. */
+const SUMMARY = [
+    '  Nodes that arrive after the tree has initialized are waited for, so a lazily loaded tree is',
+    '  restored as its branches load. Nothing is persisted while a search filter is active, and a tree',
+    '  rendered inside an overlay — the one kbq-tree-select puts in its panel, for instance — does not',
+    '  persist at all, because it has no stable key while it is out of the document.',
+    '  Storage format: entries are written under a "kbq.state." prefix and carry a timestamp, so an',
+    '  entry stranded by a markup change is collected once it outlives KBQ_STATE_SAVING_TTL (90 days by',
+    '  default).',
+    '  Provide KBQ_STATE_STORE to persist somewhere else (KbqSessionStorageStateStore is bundled), and',
+    '  KBQ_STATE_SAVING_KEY_RESOLVER to derive the key from something other than the document position.'
+];
+
+exports.SUMMARY = SUMMARY;
+exports.TREE_PACKAGE = TREE_PACKAGE;
+exports.TREE_TYPE = TREE_TYPE;
+exports.warnPatterns = warnPatterns;

package/schematics/migrations/tree-state-saving-default/index.cjs

@@ -0,0 +1,61 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var utils_messages = require('../../utils/messages.cjs');
+var utils_packageConfig = require('../../utils/package-config.cjs');
+var utils_projectFiles = require('../../utils/project-files.cjs');
+var migrations_treeStateSavingDefault_data = require('./data.cjs');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+const LABEL = '[tree-state-saving-default]';
+const EXTENSIONS = ['.ts', '.html'];
+/** A file is a tree consumer if it imports the package, names the component, or renders one. */
+function referencesTree(content) {
+    return content.includes(migrations_treeStateSavingDefault_data.TREE_PACKAGE) || new RegExp(migrations_treeStateSavingDefault_data.TREE_TYPE).test(content);
+}
+/**
+ * Reports the consequences of the tree persisting its expanded nodes, with `useStateSaving` defaulting
+ * to `true`. Never writes: the markup whose behaviour changed is exactly the markup that does not
+ * mention the input, and rewriting it to opt out would withhold the feature the release is shipping.
+ *
+ * `.html` is visited as well as `.ts`, because the default flip keys off the rendered element while the
+ * node-identity report keys off the tree control the application constructs.
+ */
+function treeStateSavingDefault(options) {
+    return async (tree, context) => {
+        const { project } = options;
+        const projectDefinition = await utils_packageConfig.setupOptions(project, tree);
+        const root = projectDefinition?.root ?? '';
+        const rootDir = root ? tree.getDir(root) : tree.root;
+        let consumers = 0;
+        let reported = 0;
+        utils_projectFiles.visitProjectFiles(rootDir, (filePath, entry) => {
+            if (!EXTENSIONS.some((extension) => filePath.endsWith(extension)))
+                return;
+            const content = entry?.content.toString();
+            if (!content || !referencesTree(content))
+                return;
+            consumers++;
+            for (const { anchor, pattern, unless, message } of migrations_treeStateSavingDefault_data.warnPatterns) {
+                if (!new RegExp(anchor).test(content) || !new RegExp(pattern).test(content))
+                    continue;
+                if (unless && new RegExp(unless).test(content))
+                    continue;
+                reported++;
+                utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${message}`]);
+            }
+        });
+        // Nothing here renders a tree, so the summary would only be noise.
+        if (consumers === 0)
+            return;
+        utils_messages.logMessage(context.logger, [
+            `${LABEL} processed kbq-tree under "${root || '<workspace root>'}", ` +
+                `${consumers} file(s) reference the tree, ${reported} report(s) raised.`,
+            ...migrations_treeStateSavingDefault_data.SUMMARY
+        ]);
+    };
+}
+
+exports.default = treeStateSavingDefault;

package/schematics/migrations/tree-state-saving-default/schema.json

@@ -0,0 +1,15 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-tree-state-saving-default",
+    "title": "Koobiq components tree state saving default migration",
+    "type": "object",
+    "properties": {
+        "project": {
+            "type": "string",
+            "description": "Name of the project to inspect. If omitted, the migration runs over the whole tree.",
+            "$default": {
+                "$source": "projectName"
+            }
+        }
+    }
+}

package/schematics/migrations/username-pipe-injection/README.md

@@ -0,0 +1,59 @@
+# username-pipe-injection
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21`
+(registered for `21.0.0-0`). Reports the call sites that obtained `KbqUsernamePipe` or
+`KbqUsernameCustomPipe` through dependency injection, which stopped resolving in the username review.
+It never writes to the tree.
+
+## Background
+
+Both pipe classes carried two decorators: `@Injectable({ providedIn: 'root' })` on top of `@Pipe`. That
+produced two instantiation paths with two different injectors. Used in a template, a pipe is created
+against the node injector, so a component- or route-level `{ provide: KBQ_PROFILE_MAPPING, … }` applies.
+Obtained with `inject(KbqUsernamePipe)`, it was the **root** singleton, and its own
+`inject(KBQ_PROFILE_MAPPING)` resolved at the root injector — the scoped mapping was invisible. The same
+class therefore produced two different strings for the same profile depending on how you got hold of it,
+and the search guide recommended exactly the path that ignored the override.
+
+`providedIn: 'root'` is gone. In a template nothing changes; through DI the pipes no longer resolve.
+
+| Before                                                  | After                                                                |
+| ------------------------------------------------------- | -------------------------------------------------------------------- |
+| `inject(KbqUsernamePipe).transform(user)`               | `kbqInjectUsernameFormatter()` → `formatUsername(user)`              |
+| `inject(KbqUsernameCustomPipe).transform(user, format)` | `kbqFormatUsernameCustom(user, format, inject(KBQ_PROFILE_MAPPING))` |
+| `constructor(private pipe: KbqUsernamePipe)`            | `private readonly formatUsername = kbqInjectUsernameFormatter()`     |
+| `KbqMappingMissingError`                                | Removed; both pipes fall back to `kbqDefaultProfileMapping`          |
+
+`kbqInjectUsernameFormatter()` must run in an injection context. It resolves `KBQ_PROFILE_MAPPING` where
+_you_ call it, which is what makes the string it returns match the one `kbq-username` renders next to it.
+
+## What it does _not_ do
+
+Nothing is rewritten. `kbqInjectUsernameFormatter()` returns a function rather than an object with a
+`transform` method, and it has to be evaluated in an injection context — neither can be derived from the
+call site.
+
+## Notes with no call site to point at
+
+- The shipped `KBQ_PROFILE_MAPPING` now maps the uppercase keys `F` / `M` / `L` as well, so
+  `{{ user | kbqUsernameCustom }}` with the library's own default format renders the surname instead of a
+  literal capital `L`. Spread `kbqDefaultProfileMapping` to pick the uppercase keys up in a mapping of
+  your own.
+- `kbq-username` renders the name of a profile that carries only some of the name fields. It used to
+  require both `firstName` and `lastName`, so `{ lastName, login }` rendered the login alone and
+  `{ firstName, middleName }` rendered an empty element.
+- `KbqUsernameSecondaryHint` is exported by `KbqUsernameModule`. It was declared, documented and used by
+  the component's own template but missing from the module, so inside a `<kbq-username-custom-view>` the
+  directive silently did not apply and the hint rendered in the primary color.
+- The secondary color no longer hangs off an adjacent-sibling selector, so a login with no name in front
+  of it renders in the secondary color as intended.
+- Initials are taken by code point, so a name starting outside the BMP no longer abbreviates to a lone
+  surrogate.
+- `kbq-title` is not attached in `mode="text"`, which applies no ellipsis for it to detect.
+- The site hint carries a visually hidden label from the new `username.siteLabel` locale key.
+
+## Running it manually
+
+```
+ng generate @koobiq/components:username-pipe-injection --project my-app
+```

package/schematics/migrations/username-pipe-injection/data.cjs

@@ -0,0 +1,78 @@
+'use strict';
+
+/**
+ * Data for the `username-pipe-injection` migration.
+ *
+ * The username review split the pipes' injectable role from their pipe role. Both classes used to carry
+ * `@Injectable({ providedIn: 'root' })` on top of `@Pipe`, which produced a root singleton whose
+ * `inject(KBQ_PROFILE_MAPPING)` resolved at the root injector — so the documented `inject(KbqUsernamePipe)`
+ * pattern silently ignored the component- or route-level mapping the token exists for, and formatted a
+ * profile differently from the `kbq-username` right next to it.
+ *
+ * `providedIn: 'root'` is gone. In a template both pipes work exactly as before; obtained through DI they
+ * no longer resolve at all, which is the one breaking call site.
+ *
+ * Warn-only: the replacement is a different expression (`kbqInjectUsernameFormatter()` returns a
+ * function, not an object with `transform`), and it has to be evaluated in an injection context.
+ */
+/** Import specifier that marks a file as a username consumer. */
+const USERNAME_PACKAGE = '@koobiq/components/username';
+/** Identifier and element shapes that mark a consumer without an import. */
+const USERNAME_TYPE = '\\bKbqUsername\\w*\\b|\\bkbq-username\\b';
+const warnPatterns = [
+    {
+        anchor: USERNAME_TYPE,
+        pattern: 'inject\\(\\s*KbqUsernamePipe\\s*\\)',
+        message: 'KbqUsernamePipe is no longer providedIn: "root", so inject(KbqUsernamePipe) throws a ' +
+            'NullInjectorError. Replace it with kbqInjectUsernameFormatter(), which returns a ' +
+            '(profile, format?) => string bound to the KBQ_PROFILE_MAPPING visible where you call it — ' +
+            'that is the mapping kbq-username renders with, which the root singleton could never see.'
+    },
+    {
+        anchor: USERNAME_TYPE,
+        pattern: 'inject\\(\\s*KbqUsernameCustomPipe\\s*\\)',
+        message: 'KbqUsernameCustomPipe is no longer providedIn: "root", so inject(KbqUsernameCustomPipe) throws ' +
+            'a NullInjectorError. Call kbqFormatUsernameCustom(profile, format, inject(KBQ_PROFILE_MAPPING)) ' +
+            'from your own injection context instead.'
+    },
+    {
+        anchor: USERNAME_TYPE,
+        pattern: ':\\s*KbqUsername(?:Custom)?Pipe\\b',
+        message: 'A KbqUsernamePipe / KbqUsernameCustomPipe constructor parameter or field is resolved through DI ' +
+            'only while the class is providedIn: "root", which it no longer is. Use ' +
+            'kbqInjectUsernameFormatter() or the kbqFormatUsername / kbqFormatUsernameCustom functions; the ' +
+            'pipes themselves keep working in templates.'
+    },
+    {
+        // The only symbol of the package whose name does not start with `KbqUsername`.
+        anchor: USERNAME_PACKAGE,
+        pattern: '\\bKbqMappingMissingError\\b',
+        message: 'KbqMappingMissingError is removed. It could never be thrown — KBQ_PROFILE_MAPPING is created ' +
+            'with a factory, so the optional inject() never returned null — and both pipes now fall back to ' +
+            'the exported kbqDefaultProfileMapping.'
+    }
+];
+/** Printed once per project, after the per-file reports. */
+const SUMMARY = [
+    '  The shipped KBQ_PROFILE_MAPPING now maps the uppercase keys F / M / L as well, so ' +
+        '{{ user | kbqUsernameCustom }} with the library default format renders the surname instead of a ' +
+        'literal capital L. A mapping of your own that only covers f / m / l keeps working; spread ' +
+        'kbqDefaultProfileMapping to pick the uppercase keys up.',
+    '  kbq-username renders the name of a profile that carries only some of the name fields. It used to ' +
+        'require both firstName and lastName, so { lastName, login } rendered the login alone and ' +
+        '{ firstName, middleName } rendered an empty element.',
+    '  KbqUsernameSecondaryHint is exported by KbqUsernameModule. It was declared, documented and used by ' +
+        'the component template, but missing from the module — so inside a <kbq-username-custom-view> the ' +
+        'directive silently did not apply, and the hint rendered in the primary color.',
+    '  The secondary color no longer depends on an adjacent primary sibling, so a login with no name in ' +
+        'front of it renders in the secondary color as intended.',
+    '  Initials are taken by code point, so a name starting outside the BMP no longer abbreviates to a ' +
+        'lone surrogate.',
+    '  The kbq-title directive is not attached in mode="text", which applies no ellipsis for it to detect.',
+    '  The site hint carries a visually hidden label from the new `username.siteLabel` locale key.'
+];
+
+exports.SUMMARY = SUMMARY;
+exports.USERNAME_PACKAGE = USERNAME_PACKAGE;
+exports.USERNAME_TYPE = USERNAME_TYPE;
+exports.warnPatterns = warnPatterns;

package/schematics/migrations/username-pipe-injection/index.cjs

@@ -0,0 +1,59 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var utils_messages = require('../../utils/messages.cjs');
+var utils_packageConfig = require('../../utils/package-config.cjs');
+var utils_projectFiles = require('../../utils/project-files.cjs');
+var migrations_usernamePipeInjection_data = require('./data.cjs');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+const LABEL = '[username-pipe-injection]';
+const EXTENSIONS = ['.ts', '.html'];
+/** A file is a username consumer if it imports the package, names a symbol, or renders the component. */
+function referencesUsername(content) {
+    return content.includes(migrations_usernamePipeInjection_data.USERNAME_PACKAGE) || new RegExp(migrations_usernamePipeInjection_data.USERNAME_TYPE).test(content);
+}
+/**
+ * Reports the call sites that obtained `KbqUsernamePipe` / `KbqUsernameCustomPipe` through DI, which
+ * stopped resolving when the review dropped `@Injectable({ providedIn: 'root' })` from both pipes.
+ * Never writes: the replacement is a different expression and has to run in an injection context.
+ *
+ * `.html` is visited as well as `.ts` so that a project rendering `kbq-username` gets the summary of the
+ * rendering changes even when nothing injects a pipe.
+ */
+function usernamePipeInjection(options) {
+    return async (tree, context) => {
+        const { project } = options;
+        const projectDefinition = await utils_packageConfig.setupOptions(project, tree);
+        const root = projectDefinition?.root ?? '';
+        const rootDir = root ? tree.getDir(root) : tree.root;
+        let consumers = 0;
+        let reported = 0;
+        utils_projectFiles.visitProjectFiles(rootDir, (filePath, entry) => {
+            if (!EXTENSIONS.some((extension) => filePath.endsWith(extension)))
+                return;
+            const content = entry?.content.toString();
+            if (!content || !referencesUsername(content))
+                return;
+            consumers++;
+            for (const { anchor, pattern, message } of migrations_usernamePipeInjection_data.warnPatterns) {
+                if (!new RegExp(anchor).test(content) || !new RegExp(pattern).test(content))
+                    continue;
+                reported++;
+                utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${message}`]);
+            }
+        });
+        // Nothing here renders a username, so the summary would only be noise.
+        if (consumers === 0)
+            return;
+        utils_messages.logMessage(context.logger, [
+            `${LABEL} processed kbq-username under "${root || '<workspace root>'}", ` +
+                `${consumers} file(s) reference the component, ${reported} call site(s) reported.`,
+            ...migrations_usernamePipeInjection_data.SUMMARY
+        ]);
+    };
+}
+
+exports.default = usernamePipeInjection;

package/schematics/migrations/username-pipe-injection/schema.json

@@ -0,0 +1,15 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-username-pipe-injection",
+    "title": "Koobiq components username review migration",
+    "type": "object",
+    "properties": {
+        "project": {
+            "type": "string",
+            "description": "Name of the project to inspect. If omitted, the migration runs over the whole tree.",
+            "$default": {
+                "$source": "projectName"
+            }
+        }
+    }
+}

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

@@ -15,11 +15,14 @@ from three ordered tables in `data.ts`:
   `risk-level` → `badge`, `components-experimental/form-field` → `components/form-field`),
   class renames (`KbqNavbarIc*` → `Kbq*`, `KbqRiskLevel*` → `KbqBadge*`,
   `KbqWarningTooltipTrigger` / `KbqExtendedTooltipTrigger` → `KbqTooltipTrigger`,
-  `KbqDatepickerToggle` → `KbqDatepickerToggleIconComponent`, etc.), token
-  removals (`KBQ_VALIDATION`, `KBQ_SANITY_CHECKS`, `KBQ_SIDEPANEL_WITH_SHADOW`),
-  function renames (`toBoolean(` → `booleanAttribute(`, `isCorrectExtension(` →
+  `KbqDatepickerToggle` → `KbqDatepickerToggleIconComponent`, etc.; when the file
+  imported the new name as well, one import specifier is kept), removals of the
+  symbols that have no replacement (`KBQ_VALIDATION`, `KbqValidationOptions`,
+  `KBQ_SANITY_CHECKS`, `KBQ_SIDEPANEL_WITH_SHADOW`, `KbqCommonModule`, etc.) from
+  imports and lists such as `imports: []` and `providers: []`, function renames (`toBoolean(` → `booleanAttribute(`, `isCorrectExtension(` →
   `FileValidators.isCorrectExtension(`, `formatDataSize(` → `getFormattedSizeParts(`),
-  method renames on instances (`.openPanel(` → `.open(`, `.toggleIsCollapsed(` →
+  method renames on instances (`.openPanel(` → `.open(` in a file that uses the Koobiq autocomplete,
+  `.toggleIsCollapsed(` →
   `.toggle(`, `.focusViaKeyboard(` → `.focus(`), and deprecated type-alias
   renames (`DropdownPositionX` → `KbqDropdownPositionX`, `DropdownPositionY` →
   `KbqDropdownPositionY`).
@@ -29,9 +32,12 @@ from three ordered tables in `data.ts`:
   `<kbq-datepicker-toggle-icon>`, `<kbq-risk-level>` → `<kbq-badge>`,
   `<kbq-navbar-ic>` → `<kbq-navbar>`, `[kbqWarningTooltip]` →
   `kbqTooltipModifier="warning" [kbqTooltip]`, `kbqFormFieldWithoutBorders` →
-  `noBorders`, the deprecated `KbqCodeBlock` input attributes
-  (`[canLoad]` / `canLoad=` → `canDownload`, `[codeFiles]` / `codeFiles=` →
-  `files`), and template-ref exportAs renames
+  `noBorders`, the deprecated `KbqCodeBlock` input attributes on a
+  `<kbq-code-block>` that does not bind the replacement too (`canLoad` →
+  `canDownload`, `codeFiles` → `files`: bindings, static and valueless attributes),
+  the `KbqFilterBarSearch` inputs that survived the tag rename
+  (`emitValueByEnter` → `isEmitValueByEnterEnabled`, `onSearchTimeout` →
+  `emitValueTimeout`, `tooltip` → `tooltipText`), and template-ref exportAs renames
   (`="kbqWarningTooltip"` → `="kbqTooltip"`).
 - **`scssReplacements`** — CSS class selectors renamed at the component level.
 
@@ -40,15 +46,29 @@ from three ordered tables in `data.ts`:
 Some changes require code restructuring and are surfaced as console warnings
 without auto-fixing:
 
-| Pattern                                           | Manual migration                                                                                      |
-| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
-| `(onSaveAsNew)`                                   | Listen to `(onSave)` and branch on `$event.status === 'newFilter'`                                    |
-| `[customValidation]`                              | Use `FormControl` validators (e.g. `FileValidators.isCorrectExtension`)                               |
-| `[errors]` (file-upload)                          | Use `FormControl.errors`                                                                              |
-| `[apps]` (app-switcher)                           | Wrap in single-site `[sites]="[{ id, name, apps }]"` and read with `KbqAppSwitcherSite`               |
-| `scrollableCodeContent` (code-block)              | Use the `scrollTo()` method instead                                                                   |
-| `.canLoad` / `.codeFiles` (code-block, TS access) | Template bindings are auto-migrated; update programmatic access to `.canDownload` / `.files` manually |
-| `required` (KbqFilter)                            | Use `cleanable = false` and `removable = false` (best-effort match — verify it is a KbqFilter config) |
+| Pattern                                           | Manual migration                                                                                       |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `(onSaveAsNew)`                                   | Listen to `(onSave)` and branch on `$event.status === 'newFilter'`                                     |
+| `[customValidation]`                              | Use `FormControl` validators (e.g. `FileValidators.isCorrectExtension`)                                |
+| `[errors]` (file-upload)                          | Use `FormControl.errors`                                                                               |
+| `[apps]` (app-switcher)                           | Wrap in single-site `[sites]="[{ id, name, apps }]"` and read with `KbqAppSwitcherSite`                |
+| `scrollableCodeContent` (code-block)              | Use the `scrollTo()` method instead                                                                    |
+| `.canLoad` / `.codeFiles` (code-block, TS access) | Template bindings are auto-migrated; update programmatic access to `.canDownload` / `.files` manually  |
+| alias next to its replacement (code-block)        | Left untouched: merge `canLoad` + `canDownload` and `codeFiles` + `files` into one binding each        |
+| removed symbol used outside an import or a list   | Left untouched (e.g. `@Inject(KBQ_VALIDATION) x: KbqValidationOptions`): remove the uses by hand       |
+| `required` (KbqFilter)                            | Use `cleanable = false` and `removable = false` (best-effort match — verify it is a KbqFilter config)  |
+| `[initialValue]` (filter-search)                  | Seed the bound `[formControl]` / `[(ngModel)]` — the component has no value input                      |
+| `(onSearch)` (filter-search)                      | Read the query from the bound control instead                                                          |
+| `kbq-filter-search` as an attribute               | `kbq-search-expandable` is element-only — replace the host element by hand                             |
+| `<kbq-filter-search>` timeout default             | `onSearchTimeout` defaulted to `0`, `emitValueTimeout` to `200` — add `[emitValueTimeout]="0"` to keep |
+
+## Behavior changes with no code pattern
+
+Defaults that changed with no markup to rewrite, so there is nothing to match on — verify these by hand:
+
+| Change                                                                                                                                             | What to do                                                                                                                                                                                                                                                             |
+| -------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `kbqTooltip` panes are hoverable now: `ignoreTooltipPointerEvents` defaults to `false` instead of `true` (WCAG 1.4.13 "Content on Hover or Focus") | Add `[ignoreTooltipPointerEvents]="true"` to tooltips that float over other click targets. The built-in overflow hints (`kbq-title`, `kbqEllipsisCenter`, option and timezone hints) already opt out, and so does any tooltip whose `kbqTrigger` is `manual` or `none` |
 
 ## Running it manually