@koobiq/components 20.4.2 → 21.0.0

package/schematics/migrations/tree-select-signals/README.md

@@ -0,0 +1,61 @@
+# tree-select-signals
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21`
+(registered for `21.0.0-0`). Reports the `KbqTreeSelect` members that became signal-backed, protected
+or disappeared in the tree-select review. It never writes to the tree.
+
+## Background
+
+The review typed the surface and dropped the members that only existed to feed the template:
+
+| Member                                                                                          | Before            | After                       |
+| ----------------------------------------------------------------------------------------------- | ----------------- | --------------------------- |
+| `valueChange`                                                                                   | declared output   | removed                     |
+| `getPanelClasses()`, `getPanelTheme()`, `isRtl()`, `transformOrigin`                            | public            | removed                     |
+| `hiddenItemsText`, `hiddenItemsTextFormatter`                                                   | accessor / method | signal inputs               |
+| `hasBackdrop`, `searchMinOptionsThreshold`                                                      | accessor / input  | signals                     |
+| `hiddenItems`, `colorForState`                                                                  | plain members     | `WritableSignal` / `Signal` |
+| `options`, `tags`, `overlayDir`, `triggerRect`, `panelDoneAnimatingStream`, `changeDetectorRef` | public            | `protected`                 |
+| `KbqTreeSelectChange`                                                                           | `value: any`      | generic, typed `value`      |
+
+`valueChange` deserves a note. It was declared and documented as the other half of a two-way binding
+on a `value` input that does not exist, and nothing ever emitted it — so `(valueChange)` never fired.
+Removing it changes nothing at runtime: Angular treats an unmatched `(x)` as a DOM event listener,
+which stays just as silent. Listen to `(selectionChange)`.
+
+## What it does _not_ do
+
+Nothing is rewritten. A read of a signal member becomes a call, a write becomes a template binding,
+and a removed member has no replacement expression at all.
+
+| Pattern                                                                     | Manual migration                                                      |
+| --------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| `valueChange`                                                               | Listen to `(selectionChange)`                                         |
+| `.getPanelClasses()` / `.getPanelTheme()` / `.isRtl()` / `.transformOrigin` | Bind `[panelClass]` if the panel needs styling                        |
+| `.hiddenItemsText = …` and friends                                          | Bind the input — a signal member takes no assignment                  |
+| `.hiddenItemsText` and friends                                              | Read them as calls                                                    |
+| `.options` / `.tags` / `.overlayDir` / …                                    | Protected; use the open/close API, the inputs and `(selectionChange)` |
+| `sortComparator`                                                            | Its third argument is the tree's data nodes in panel order            |
+
+## Notes with no call site to point at
+
+- `KbqTreeSelectChange` is generic and its `value` is no longer `any`. A handler that relied on the
+  implicit widening needs the type argument.
+- The embedded tree is set up through `KbqTreeSelection.initializeForEmbedding()` instead of a
+  second manual `ngAfterContentInit()`. The old path left duplicate subscriptions on query lists that
+  are never re-created, so every options change was handled several times — on the search-filtering
+  hot path.
+- The dead `{ provide: KbqTree, useExisting: KbqTreeSelect }` provider is gone. `KbqTreeSelect` never
+  satisfied `KbqTree` structurally, so anything injecting `KbqTree` from inside a tree-select was
+  getting an object that only looked right.
+- A `multiple` value is ordered by the panel, collapsed branches included, instead of the order it
+  was written in. `[sortComparator]` gets two selected data nodes and every data node of the tree in
+  panel order; `() => 0` keeps the write order.
+- The component renders a host `id` and carries combobox ARIA, so the form field label's `[attr.for]`
+  resolves instead of dangling.
+
+## Running it manually
+
+```
+ng generate @koobiq/components:tree-select-signals --project my-app
+```

package/schematics/migrations/tree-select-signals/data.js

@@ -0,0 +1,106 @@
+'use strict';
+
+/**
+ * Data for the `tree-select-signals` migration.
+ *
+ * The tree-select review typed the surface and removed the members that only existed to serve the
+ * template:
+ *
+ * - `getPanelClasses()`, `getPanelTheme()`, `isRtl()`, `transformOrigin` — removed. The panel classes
+ *   are a `protected` computed (`panelClasses`) the template reads directly.
+ * - `valueChange` — removed. It was declared and documented as the other half of a two-way binding on
+ *   a `value` input that does not exist, and nothing ever emitted it.
+ * - `hiddenItemsText`, `hiddenItemsTextFormatter` — accessor pair / method → signal inputs.
+ * - `hiddenItems` → `WritableSignal<number>`, `colorForState` → `Signal<KbqComponentColors>`.
+ * - `hasBackdrop` — accessor pair → signal input.
+ * - `options`, `tags`, `overlayDir`, `triggerRect`, `panelDoneAnimatingStream`, `changeDetectorRef` —
+ *   public → `protected`.
+ * - `KbqTreeSelectChange` is generic and its `value` is no longer `any`.
+ *
+ * Warn-only. A read of a signal member becomes a call, a write becomes the binding, and a removed
+ * member has no replacement expression at all.
+ */
+/** Import specifier that marks a file as a tree-select consumer. */
+const TREE_SELECT_PACKAGE = '@koobiq/components/tree-select';
+/** Identifier and attribute shapes that mark a consumer without an import. */
+const TREE_SELECT_TYPE = '\\bKbqTreeSelect\\w*\\b|\\bkbq-tree-select\\b';
+const warnPatterns = [
+    {
+        anchor: TREE_SELECT_TYPE,
+        pattern: '\\bvalueChange\\b',
+        message: 'KbqTreeSelect.valueChange was removed. It was declared as the other half of a two-way binding ' +
+            'on a `value` input that does not exist, and nothing ever emitted it — a `(valueChange)` binding ' +
+            'never fired, and Angular treats it as a DOM event listener now, so it stays silent either way. ' +
+            'Listen to (selectionChange) instead.'
+    },
+    {
+        anchor: TREE_SELECT_TYPE,
+        pattern: '\\.\\s*(?:getPanelClasses|getPanelTheme|isRtl|transformOrigin)\\b',
+        message: 'KbqTreeSelect.getPanelClasses() / getPanelTheme() / isRtl() / transformOrigin were removed. They ' +
+            'existed to feed the template, which now reads a protected `panelClasses` computed; a host that ' +
+            'needs the panel styled differently should bind [panelClass].'
+    },
+    {
+        anchor: TREE_SELECT_TYPE,
+        pattern: '\\.\\s*(?:hiddenItemsText|hiddenItemsTextFormatter|hiddenItems|colorForState)\\s*=(?!=)',
+        message: 'hiddenItemsText and hiddenItemsTextFormatter are signal inputs, hiddenItems is a WritableSignal ' +
+            'and colorForState is a computed — none of them takes an assignment. Bind the inputs in the ' +
+            'template; hiddenItems is written by the measurement, not by the host.'
+    },
+    {
+        anchor: TREE_SELECT_TYPE,
+        pattern: '\\.\\s*(?:hiddenItemsText|hiddenItemsTextFormatter|hiddenItems|colorForState)\\b(?!\\s*[=(])',
+        message: 'hiddenItemsText, hiddenItemsTextFormatter, hiddenItems and colorForState are signal-backed: read ' +
+            'them as calls. `hiddenItemsTextFormatter()(template, count)` for the formatter, which is an ' +
+            'input holding the function rather than a method.'
+    },
+    {
+        anchor: TREE_SELECT_TYPE,
+        pattern: '\\.\\s*(?:options|tags|overlayDir|triggerRect|panelDoneAnimatingStream|changeDetectorRef)\\b',
+        message: 'KbqTreeSelect.options / tags / overlayDir / triggerRect / panelDoneAnimatingStream / ' +
+            'changeDetectorRef are protected. They were the panel and trigger plumbing; the supported ' +
+            'surface is the open/close API, the inputs and (selectionChange).'
+    },
+    {
+        anchor: TREE_SELECT_TYPE,
+        pattern: '\\.\\s*(?:hasBackdrop|searchMinOptionsThreshold)\\b(?!\\s*[=(])',
+        message: 'KbqTreeSelect.hasBackdrop and .searchMinOptionsThreshold are signals now: read them as calls, ' +
+            '`hasBackdrop()` and `searchMinOptionsThreshold()`. searchMinOptionsThreshold() still reports the ' +
+            'resolved number.'
+    },
+    {
+        anchor: TREE_SELECT_TYPE,
+        pattern: '\\.\\s*(?:multiple|autoSelect|tabIndex|selectAllHandler|hasBackdrop|searchMinOptionsThreshold)\\s*=(?!=)',
+        message: 'multiple, autoSelect, tabIndex, selectAllHandler, hasBackdrop and searchMinOptionsThreshold of ' +
+            'KbqTreeSelect are signal inputs, so an assignment no longer compiles. Bind them in the template. This ' +
+            'pattern also matches a write to an unrelated object in the same file — check before changing it.'
+    },
+    {
+        anchor: TREE_SELECT_TYPE,
+        pattern: '\\bsortComparator\\b',
+        message: 'The sortComparator of KbqTreeSelect gets the selected data nodes, as it always did, and its third ' +
+            'argument is every data node of the tree in panel order (treeControl.dataNodes) instead of the ' +
+            'rendered KbqTreeOption[]. A comparator that looks its arguments up among the options, or types ' +
+            'them as KbqTreeOption, has to take your node type. Without a comparator a multiple value is ' +
+            'ordered by the panel now; `() => 0` keeps the order the values were written in.'
+    }
+];
+/** Printed once per project, after the per-file reports. */
+const SUMMARY = [
+    '  KbqTreeSelectChange is generic — KbqTreeSelectChange<T> — and its `value` is no longer `any`. A ' +
+        'handler that relied on the implicit widening needs the type argument.',
+    '  The embedded tree is set up through KbqTreeSelection.initializeForEmbedding() instead of a ' +
+        'second manual ngAfterContentInit(). The old path left duplicate subscriptions on query lists ' +
+        'that are never re-created, so every options change was handled several times on the ' +
+        'search-filtering hot path.',
+    '  The dead { provide: KbqTree, useExisting: KbqTreeSelect } provider is gone: KbqTreeSelect never ' +
+        'satisfied KbqTree structurally, so anything injecting KbqTree from inside a tree-select was ' +
+        'getting an object that only looked right.',
+    '  The component renders a host id and carries combobox ARIA, so the [attr.for] on the form field ' +
+        'label resolves instead of dangling, and hand-rolled role or aria-* attributes are duplicates.'
+];
+
+exports.SUMMARY = SUMMARY;
+exports.TREE_SELECT_PACKAGE = TREE_SELECT_PACKAGE;
+exports.TREE_SELECT_TYPE = TREE_SELECT_TYPE;
+exports.warnPatterns = warnPatterns;

package/schematics/migrations/tree-select-signals/index.js

@@ -0,0 +1,58 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var utils_messages = require('../../utils/messages.js');
+var utils_packageConfig = require('../../package-config-BhU2TfC8.js');
+var migrations_treeSelectSignals_data = require('./data.js');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+const LABEL = '[tree-select-signals]';
+const EXTENSIONS = ['.ts', '.html'];
+/** A file is a tree-select consumer if it imports the package, names the component, or renders one. */
+function referencesTreeSelect(content) {
+    return content.includes(migrations_treeSelectSignals_data.TREE_SELECT_PACKAGE) || new RegExp(migrations_treeSelectSignals_data.TREE_SELECT_TYPE).test(content);
+}
+/**
+ * Reports the `KbqTreeSelect` members that became signal-backed, protected, or disappeared. Never
+ * writes: a read becomes a call, a write becomes a binding, and a removed member has no replacement
+ * expression at all.
+ *
+ * `.html` is visited as well as `.ts`, because `(valueChange)` is a template binding that Angular
+ * now silently treats as a DOM event listener.
+ */
+function treeSelectSignals(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_packageConfig.visitProjectFiles(rootDir, (filePath, entry) => {
+            if (!EXTENSIONS.some((extension) => filePath.endsWith(extension)))
+                return;
+            const content = entry?.content.toString();
+            if (!content || !referencesTreeSelect(content))
+                return;
+            consumers++;
+            for (const { anchor, pattern, message } of migrations_treeSelectSignals_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 tree-select, so the summary would only be noise.
+        if (consumers === 0)
+            return;
+        utils_messages.logMessage(context.logger, [
+            `${LABEL} processed kbq-tree-select under "${root || '<workspace root>'}", ` +
+                `${consumers} file(s) reference the component, ${reported} call site(s) reported.`,
+            ...migrations_treeSelectSignals_data.SUMMARY
+        ]);
+    };
+}
+
+exports.default = treeSelectSignals;

package/schematics/migrations/tree-select-signals/schema.json

@@ -0,0 +1,15 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-tree-select-signals",
+    "title": "Koobiq components tree-select 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/tree-signals/README.md

@@ -0,0 +1,82 @@
+# tree-signals
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21`
+(registered for `21.0.0-0`). Reports the public members of `@koobiq/components/tree` that
+became read-only when the tree moved to signals, and the node type the tree takes. It never writes to the tree.
+
+## Background
+
+The tree moved its inputs and its query members to signals. Members that used to be writable
+are now getters — over a `computed()`, over an `InputSignal`, or over an `asObservable()` view of a
+`Subject`. Assigning to a getter-only property throws `TypeError: Cannot set property … which has
+only a getter` in strict mode, and an ES module is always strict, so an unmigrated write does not
+merely stop compiling: it throws at runtime in any build that skips type checking.
+
+| Member                                                        | Was                            | Is                                             |
+| ------------------------------------------------------------- | ------------------------------ | ---------------------------------------------- |
+| `KbqTreeNodeToggle.disabled`                                  | `@Input()` accessor pair       | getter over a `computed()`                     |
+| `KbqTreeBase.nodeDefs`                                        | `QueryList<KbqTreeNodeDef<T>>` | `Signal<readonly KbqTreeNodeDef<T>[]>`         |
+| `KbqTreeNodePadding.indent`                                   | accessor pair                  | `InputSignal<number \| string>`                |
+| `KbqTreeNodePadding.indentUnits`                              | writable field                 | getter derived from `indent`                   |
+| `KbqTreeNodeToggleBaseDirective.recursive`                    | accessor pair                  | `InputSignalWithTransform<boolean, …>`         |
+| `KbqTreeOption.onFocus` / `onBlur`                            | `Subject<KbqTreeOptionEvent>`  | `Observable<KbqTreeOptionEvent>`               |
+| `KbqTreeBase.treeControl`                                     | field                          | getter over an `InputSignal`                   |
+| `KbqTreeBase.dataSource`                                      | accessor pair                  | getter; the input switches it from an `effect` |
+| `KbqTreeSelection.disabled` / `tabIndex` / `selectAllHandler` | accessor pairs                 | getters over signal inputs                     |
+| `KbqTreeOption.disabled` / `showCheckbox`                     | accessor pairs                 | getters over signal inputs                     |
+
+`KbqTree` and `KbqTreeSelection` inherit `treeControl` and `dataSource`. Every input keeps its alias,
+so template bindings keep working. `KbqTreeSelection.multiple` is not listed: it has never had a
+setter, and `multipleMode` stays writable.
+
+Two of them are silent rather than loud:
+
+- `KbqTreeBase` is exported and is the documented extension point for a custom tree. A subclass
+  reading `this.nodeDefs.length` now gets `0` — the arity of the signal function — instead of the
+  number of node definitions, and `this.nodeDefs.changes.subscribe(…)` throws.
+- `KbqTreeNodeToggle` kept `disabled` as the input alias (the input is declared as `disabledInput`),
+  so every template binding keeps working. Only imperative writes break, and the class itself
+  performed one before the review: the filter state is now OR-ed in by the computed instead.
+
+## Node type
+
+`KbqTreeSelection`, `KbqTreeOption` and `KbqTreeSelect` take the type of the data node, `T`, `any` by
+default, and `selectionModel` is `SelectionModel<T>`. A template infers `T` of `kbq-tree-selection` from
+`[treeControl]`, `[dataSource]`, `[trackBy]` and `[selectAllHandler]`, so with `strictTemplates`
+bindings that name different node types no longer compile. Only the compiler sees such a mismatch, so
+the summary names it rather than a pattern: give the bindings the same node type. A query names it as
+`viewChild.required<KbqTreeSelection<Node>>(KbqTreeSelection)`.
+
+## What it does
+
+Walks every `.ts` and `.html` file under the project root — the whole workspace when `--project` is
+omitted, which is how `ng update` invokes it — skipping `node_modules` and `dist`, and logs the
+files that hold a call site one of the narrowings breaks:
+
+| Reported                                                 | Manual migration                                                                   |
+| -------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `<toggle>.disabled = …`                                  | Bind the `disabled` attribute; it still reaches the toggle through `disabledInput` |
+| `<toggle>.recursive`                                     | Read `recursive()`; bind `kbqTreeNodeToggleRecursive`                              |
+| `nodeDefs.changes` / `.length` / `.toArray()` / …        | Read `nodeDefs()`; replace the subscription with an `effect`                       |
+| `<padding>.indent` / `.indentUnits`                      | Read `indent()`; bind `kbqTreeNodePaddingIndent`                                   |
+| `<option>.onFocus.next(…)` / `onBlur.next(…)`            | Subscribe instead — the option emits on both streams itself                        |
+| `<tree>.treeControl / dataSource = …`                    | Bind it, on `kbq-tree` and `kbq-tree-selection` alike                              |
+| `<selection>.disabled / tabIndex / selectAllHandler = …` | Bind it; disable the tree through its form control                                 |
+| `<option>.disabled / showCheckbox = …`                   | Bind it, or disable the node through the tree control's `isDisabled`               |
+
+Each pattern is scoped to files that also name its owner, so a `.disabled =` write in a file that
+never mentions a tree toggle stays quiet. A project that renders a tree at all also gets a summary
+of every member, because not every narrowing breaks the build: `nodeDefs.length` still compiles and
+returns `0`, and a read of `indent` or `recursive` passed on loosely gets a signal instead of its
+value — through a receiver no pattern recognizes, with no diagnostic at all.
+
+## What it does _not_ do (manual)
+
+Nothing is rewritten. What replaces a write is a template binding or a different member, neither of
+which can be derived from the assignment, and a read cannot be mechanically suffixed with `()`
+either: `nodeDefs` returns a plain array rather than a `QueryList`, and `indentUnits` is derived
+from `indent` rather than stored. The report is the migration.
+
+Receivers are matched by the identifiers in the file rather than by resolved types, so a member
+reached through an `any`-typed or structurally-typed receiver in a file that names no tree type is
+not reported.

package/schematics/migrations/tree-signals/data.js

@@ -0,0 +1,123 @@
+'use strict';
+
+/**
+ * Data for the `tree-signals` migration.
+ *
+ * These public members of `@koobiq/components/tree` became read-only when the tree moved to signals:
+ *
+ * - `KbqTreeNodeToggle.disabled`        — accessor pair → getter over a `computed()` (the input is
+ *   declared as `disabledInput` and still aliased `disabled`, so templates are unaffected)
+ * - `KbqTreeBase.nodeDefs`              — `QueryList<KbqTreeNodeDef<T>>` → `Signal<readonly KbqTreeNodeDef<T>[]>`
+ * - `KbqTreeNodePadding.indent`         — accessor pair → `InputSignal<number | string>`
+ * - `KbqTreeNodePadding.indentUnits`    — writable field → getter derived from `indent`
+ * - `KbqTreeNodeToggleBaseDirective.recursive` — accessor pair → `InputSignalWithTransform`
+ * - `KbqTreeOption.onFocus` / `onBlur`  — `Subject` → `Observable` via `asObservable()`
+ * - `KbqTreeBase.treeControl` / `dataSource` (of `KbqTree` and `KbqTreeSelection`), `KbqTreeSelection.disabled` /
+ *   `tabIndex` / `selectAllHandler`, `KbqTreeOption.disabled` / `showCheckbox` — field or accessor pair → getter
+ *   over a signal input that keeps the alias, so templates are unaffected
+ *
+ * `KbqTreeSelection`, `KbqTreeOption` and `KbqTreeSelect` also took the type of the data node, `T`. A template
+ * infers it from the bindings of the tree, so bindings that name different node types stop compiling under
+ * `strictTemplates`; only the compiler sees that, so the summary names it.
+ *
+ * Nothing is rewritten. What replaces a write is a template binding or a different member, and
+ * neither can be derived from the assignment; a read of a signal-backed member has to be checked
+ * against its new value rather than mechanically suffixed with `()`.
+ */
+/** Import specifier that marks a file as a tree consumer. */
+const TREE_PACKAGE = '@koobiq/components/tree';
+/** Identifier shape that marks a file as a tree consumer without an import (e.g. a re-export). */
+const TREE_TYPE = '\\bKbqTree\\w*\\b';
+const TOGGLE_ANCHOR = '\\bKbqTreeNodeToggle\\w*\\b';
+/**
+ * Reported with the file they were found in, in every mode — the migration only ever warns.
+ * Scoped by `anchor` so a plain `.disabled =` in a file that never mentions a toggle stays quiet.
+ */
+const warnPatterns = [
+    {
+        anchor: TOGGLE_ANCHOR,
+        pattern: '\\.disabled\\s*=(?!=)',
+        message: 'KbqTreeNodeToggle.disabled is a read-only getter over a computed (the `disabled` input OR-ed with ' +
+            'the filter state), so an assignment throws `TypeError: Cannot set property disabled`. Bind the ' +
+            '`disabled` attribute instead — it still reaches the toggle, through the `disabledInput` input.'
+    },
+    {
+        anchor: TOGGLE_ANCHOR,
+        pattern: '\\.recursive\\b',
+        message: 'KbqTreeNodeToggleBaseDirective.recursive is an InputSignalWithTransform: read it as `recursive()`, ' +
+            'and set it through the `kbqTreeNodeToggleRecursive` binding — assigning to it throws.'
+    },
+    {
+        anchor: TREE_TYPE,
+        pattern: '\\bnodeDefs\\s*\\.\\s*(?:changes|first|last|toArray|notifyOnChanges|reset|length)\\b',
+        message: 'KbqTreeBase.nodeDefs is a Signal<readonly KbqTreeNodeDef<T>[]> instead of a QueryList. ' +
+            '`nodeDefs.changes` no longer exists, and `nodeDefs.length` is the arity of the signal function — ' +
+            'always 0. Read the array as `nodeDefs()` and use `toSignal`/`effect` where you subscribed.'
+    },
+    {
+        anchor: '\\bKbqTreeNodePadding\\b',
+        pattern: '\\.indent(?:Units)?\\b',
+        message: 'KbqTreeNodePadding.indent is an InputSignal — read it as `indent()` and set it through the ' +
+            '`kbqTreeNodePaddingIndent` binding — and `indentUnits` is a read-only getter derived from it. ' +
+            'Assigning to either throws.'
+    },
+    {
+        anchor: '\\bKbqTreeOption\\b',
+        pattern: '\\.(?:onFocus|onBlur)\\s*\\.\\s*(?:next|complete|error)\\b',
+        message: 'KbqTreeOption.onFocus and onBlur are Observables now (`asObservable()`), so `.next()` is gone at ' +
+            'runtime as well as in the types. Subscribe to them; the option emits on them itself.'
+    },
+    {
+        // KbqTree and KbqTreeSelection inherit both from KbqTreeBase; KbqTreeSelect, KbqTreeOption and the rest do not.
+        anchor: '\\bKbqTree(?:Base|Selection)?\\b',
+        pattern: '\\.\\s*(?:treeControl|dataSource)\\s*=[^=]',
+        message: 'treeControl and dataSource of KbqTreeBase, so of KbqTree and KbqTreeSelection, are signal inputs ' +
+            'read through a getter now, so a programmatic write no longer compiles. Bind them. This pattern also ' +
+            'matches a write to an unrelated object in the same file — check before changing it.'
+    },
+    {
+        // `multiple` is left out: it has never had a setter, `multipleMode` is what a write changes.
+        anchor: '\\bKbqTreeSelection\\b',
+        pattern: '\\.\\s*(?:disabled|tabIndex|selectAllHandler)\\s*=[^=]',
+        message: 'disabled, tabIndex and selectAllHandler of KbqTreeSelection are signal inputs read through a getter ' +
+            'now, so a programmatic write no longer compiles. Bind them, and disable the tree through its form ' +
+            'control. autoSelect, noUnselectLast, typeAhead, selectAll and multipleMode stay writable. This ' +
+            'pattern also matches a write to an unrelated object in the same file — check before changing it.'
+    },
+    {
+        anchor: '\\bKbqTreeOption\\b',
+        pattern: '\\.\\s*(?:disabled|showCheckbox)\\s*=[^=]',
+        message: 'KbqTreeOption.disabled and .showCheckbox are signal inputs read through a getter now, so a ' +
+            'programmatic write no longer compiles. Bind them, or disable the node through the isDisabled ' +
+            'predicate of the tree control. This pattern also matches a write to an unrelated object in the ' +
+            'same file — check before changing it.'
+    }
+];
+/**
+ * Printed once for every project that renders a tree, because not every narrowing breaks the build:
+ * `nodeDefs.length` still compiles and returns 0, and a read of `indent` or `recursive` passed on
+ * loosely gets a signal instead of its value — through a receiver no pattern recognizes, with no
+ * diagnostic at all.
+ */
+const SUMMARY = [
+    '',
+    'These members of @koobiq/components/tree became read-only and cannot be assigned:',
+    '  - KbqTreeNodeToggle.disabled (bind `disabled`; the input is declared as `disabledInput`)',
+    '  - KbqTreeBase.nodeDefs (Signal<readonly KbqTreeNodeDef<T>[]>, no longer a QueryList)',
+    '  - KbqTreeNodePadding.indent (InputSignal) and KbqTreeNodePadding.indentUnits (getter)',
+    '  - KbqTreeNodeToggleBaseDirective.recursive (InputSignalWithTransform)',
+    '  - KbqTreeOption.onFocus and KbqTreeOption.onBlur (Observable, not Subject)',
+    '  - KbqTree and KbqTreeSelection treeControl, dataSource; KbqTreeSelection disabled, tabIndex,',
+    '    selectAllHandler; KbqTreeOption disabled, showCheckbox (signal inputs read through a getter; bind them)',
+    '',
+    'KbqTreeSelection, KbqTreeOption and KbqTreeSelect take the type of the data node, T (`any` by default):',
+    '  - a template infers T of kbq-tree-selection from [treeControl], [dataSource], [trackBy] and',
+    '    [selectAllHandler]; with strictTemplates, bindings that name different node types no longer compile.',
+    '    Give them the same node type.',
+    '  - a query names T: viewChild.required<KbqTreeSelection<Node>>(KbqTreeSelection).'
+];
+
+exports.SUMMARY = SUMMARY;
+exports.TREE_PACKAGE = TREE_PACKAGE;
+exports.TREE_TYPE = TREE_TYPE;
+exports.warnPatterns = warnPatterns;

package/schematics/migrations/tree-signals/index.js

@@ -0,0 +1,54 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var utils_messages = require('../../utils/messages.js');
+var utils_packageConfig = require('../../package-config-BhU2TfC8.js');
+var migrations_treeSignals_data = require('./data.js');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+const LABEL = '[tree-signals]';
+const EXTENSIONS = ['.ts', '.html'];
+/** A file is a tree consumer if it imports the package, names one of its types, or renders one. */
+function referencesTree(content) {
+    return content.includes(migrations_treeSignals_data.TREE_PACKAGE) || new RegExp(migrations_treeSignals_data.TREE_TYPE).test(content) || content.includes('kbq-tree');
+}
+/**
+ * Reports the members of `@koobiq/components/tree` that became read-only, with the files that
+ * write or read them. Never writes: see `data.ts` for why none of them can be rewritten mechanically.
+ */
+function treeSignals(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_packageConfig.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, message } of migrations_treeSignals_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 tree, so the summary would only be noise.
+        if (consumers === 0)
+            return;
+        utils_messages.logMessage(context.logger, [
+            `${LABEL} processed tree under "${root || '<workspace root>'}", ` +
+                `${consumers} file(s) reference the tree, ${reported} call site(s) reported.`,
+            ...migrations_treeSignals_data.SUMMARY
+        ]);
+    };
+}
+
+exports.default = treeSignals;

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

@@ -0,0 +1,15 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-tree-signals",
+    "title": "Koobiq components tree 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/tree-state-saving-default/README.md

@@ -0,0 +1,66 @@
+# tree-state-saving-default
+
+Migration schematic invoked automatically by `ng update @koobiq/components@20`
+(registered for `21.0.0-0`). Reports the consequences of the tree persisting its expanded nodes, with
+`useStateSaving` defaulting to `true`. It never writes to the tree.
+
+## Background
+
+`KbqTreeSelection` and `KbqTree` gained the same state saving the accordion has, applied through the
+`KbqStateSaving` host directive, and it is on by default. A tree with no `stateSavingKey` derives its key
+from where it sits in the document — the chain of tag names up to `<body>`, cut short by the first
+author-written `id`, which becomes the anchor. So a tree inside `<section id="catalog">` persists under
+`#catalog/kbq-tree-selection`, and everything above that `id` can be restructured without moving the key.
+
+Only expansion is persisted. Selection belongs to the form control the tree is bound to, and restoring it
+from storage would overwrite the value the application supplied.
+
+## What it reports
+
+- **The default flip.** A file that renders `kbq-tree-selection` or `kbq-tree` and never writes
+  `useStateSaving`.
+- **How a node is identified.** Expansion is persisted by the value `getValue` returns — the third
+  argument of the `FlatTreeControl` constructor. It must be a string, stable across reloads, and unique
+  within the tree; a node object is re-created whenever the data is replaced, so it cannot serve as the
+  key. Where two nodes share a value, the first of them is expanded.
+- **Programmatic expansion.** `expandAll()`, `collapseAll()`, `expandDescendants()`,
+  `collapseDescendants()` and direct writes to `expansionModel` are not persisted on their own — only
+  what a user expands or collapses is. Call `saveState()` afterwards to record them.
+- **`NestedTreeControl`.** It has no `getValue`, so a tree built on one persists nothing and logs a
+  dev-mode warning.
+
+Each check is evaluated against the whole file, matching the other warn-only migrations in this
+collection. A file holding two trees where only one opts out is not reported — inspect it by hand.
+
+## What it does _not_ do
+
+It does not insert `[useStateSaving]="false"`. The markup whose behaviour changed is exactly the markup
+that says nothing about the input, so opting every tree out would be a rewrite of every consumer template
+that also withholds the feature this release is shipping. Opting out stays a decision the application
+makes.
+
+## Behaviour worth knowing without a report
+
+- **Nodes that arrive late are waited for.** A value whose node is not loaded yet is applied as soon as
+  it appears, so a lazily loaded tree is restored as its branches load. Until then the value is kept, so
+  persisting a change made in the meantime does not drop the branches still loading.
+- **Nothing is persisted while a filter is active.** `filterNodes()` rewrites the expansion set to every
+  expandable node that matched and puts the real one back afterwards, so what is expanded during a search
+  is a view of the results rather than a state.
+- **A tree inside an overlay does not persist.** `kbq-tree-select` renders one into its panel, where the
+  tree is not in the document when it initializes and so has no stable key.
+- **Trees sharing one `treeControl` share one expansion model** while persisting under a key each: the
+  last one to initialize decides what is restored.
+
+## Storage format
+
+Entries are written under a `kbq.state.` prefix and carry a `savedAt` timestamp, so an entry stranded by a
+markup change is collected once it outlives `KBQ_STATE_SAVING_TTL` (90 days by default). Reading an entry
+refreshes it, so state that is visited but never changed does not expire under an active user.
+
+## Related tokens
+
+- `KBQ_STATE_STORE` — where state is persisted. `KbqSessionStorageStateStore` is bundled for state that
+  should live no longer than the tab session.
+- `KBQ_STATE_SAVING_KEY_RESOLVER` — how the key is derived when no `stateSavingKey` is given.
+- `KBQ_STATE_SAVING_TTL` — how long an entry survives without being written or read.