@koobiq/components 20.4.2 → 21.0.0

package/schematics/migrations/filter-bar-signals/README.md

@@ -23,18 +23,26 @@ The schematic walks every `.ts` and `.html` file in the project (skipping
 
 - **TypeScript reads/writes.** For a receiver whose static type is annotated
   `KbqFilterBar` / `KbqFilterBarHost` (method/function params, class fields —
-  including `@ViewChild(KbqFilterBar) x: KbqFilterBar` and constructor
-  parameter-properties — and typed locals), a read of a signal member becomes a
-  call and a `filter` write becomes `.set(...)`:
+  including `@ViewChild(KbqFilterBar) x: KbqFilterBar`, constructor
+  parameter-properties and `inject(KbqFilterBar)` — and typed locals), a read of
+  a signal member becomes a call and a plain `filter = …` write becomes
+  `.set(...)`:
     - `filterBar.filter` → `filterBar.filter()` (incl. optional chain `filterBar.filter?.name` → `filterBar.filter()?.name`)
     - `filterBar.filter = next` → `filterBar.filter.set(next)`
     - `this.filterBar.isChanged` → `this.filterBar.isChanged()`
-- **Template reference reads.** For a `#ref` bound to `<kbq-filter-bar>`, reads
+- **Template references.** For a bare `#ref` on `<kbq-filter-bar>`, reads
   of signal members through that ref are rewritten in the same template
   (external `.html` and inline `template:` strings): `ref.isChanged` →
-  `ref.isChanged()`.
-- **Rename.** `KbqFilterBarRefresher` → `KbqFilterRefresher` (the old name is
-  still re-exported as an alias, so this is optional cleanup).
+  `ref.isChanged()`, and in an event binding `ref.filter = saved` →
+  `ref.filter.set(saved)`. `KbqFilterBar` has no `exportAs`, so a ref with a
+  value (`#ref="ngModel"`) names another directive and is left alone, and so
+  is a property chain that only ends in the ref's name
+  (`page.filterBar.filter`). Only the expressions of the view that declares
+  the ref are looked at — prose, comments and plain attributes are not — and a
+  ref whose name a `@for`, `let-`, `*ngFor` or `@let` variable or another
+  `#ref` shares is left alone.
+- **Rename.** `KbqFilterBarRefresher` → `KbqFilterRefresher` (the old name
+  stayed an alias until 21.0.0).
 
 All rewrites are idempotent — running twice does not double the call.
 
@@ -43,12 +51,14 @@ All rewrites are idempotent — running twice does not double the call.
 Some changes require code restructuring and are surfaced as warnings without
 auto-fixing:
 
-| Pattern                          | Manual migration                                                                                   |
-| -------------------------------- | -------------------------------------------------------------------------------------------------- |
-| `.changes` (KbqFilterBar)        | Deprecated no-op; read `filterBar.filter()` inside an `effect(...)`, or listen to `(filterChange)` |
-| `.preparePopover()` (KbqFilters) | Removed; use `openSaveAsNewFilterPopover()` / `openChangeFilterNamePopover()`                      |
-| `viewChild(KbqFilterBar)` query  | Returns the instance, so reads are a double call: `this.filterBar().filter()` — verify manually    |
-| `KBQ_FILTER_BAR_PIPES`           | Now typed `Map<KbqPipeType, Type<KbqBasePipe>>`; wrap direct providers in `new Map([...])`         |
+| Pattern                          | Manual migration                                                                                                 |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `.changes` (KbqFilterBar)        | Deprecated no-op; read `filterBar.filter()` inside an `effect(...)`, or listen to `(filterChange)`               |
+| `.preparePopover()` (KbqFilters) | Removed; use `openSaveAsNewFilterPopover()` / `openChangeFilterNamePopover()`                                    |
+| `viewChild(KbqFilterBar)` query  | Returns the instance, so reads are a double call: `this.filterBar().filter()` — verify manually                  |
+| `KBQ_FILTER_BAR_PIPES`           | Now typed `Map<KbqPipeType, Type<KbqBasePipe>>`; wrap direct providers in `new Map([...])`                       |
+| `filterBar.pipeTemplates = …`    | Read-only input, also when written through a template ref; bind `[pipeTemplates]` instead                        |
+| `filterBar.filter ??= …`         | Only a plain `=` becomes `.set()`, in code or through a template ref; write the rest with `.set()` / `.update()` |
 
 ## Running it manually
 
@@ -60,7 +70,8 @@ Pass `--fix=false` to see what would change without writing files.
 
 ## Limitations
 
-Receivers are matched by explicit `KbqFilterBar` type annotation only (no
-cross-package type inference), so aliased/inferred receivers
+Receivers are matched by an explicit `KbqFilterBar` type annotation or an
+`inject()` initializer (no type inference), so inferred receivers
 (`const fb = this.filterBar; fb.filter`) are left untouched and covered by the
-warnings above. After running, **always inspect the diff** before committing.
+warnings above. A nested declaration that reuses the receiver's name, and
+`this.<field>` inside a `function` that rebinds `this`, are left alone too. After running, **always inspect the diff** before committing.

package/schematics/migrations/filter-bar-signals/data.js

@@ -31,8 +31,7 @@ const FILTER_BAR_HOST_TYPE = 'KbqFilterBarHost';
 const FILTER_BAR_ELEMENT = 'kbq-filter-bar';
 /**
  * Safe, idempotent identifier renames applied to `.ts` files. The `\b…\b` boundaries make each rule
- * idempotent. `KbqFilterBarRefresher` is still re-exported as an alias of `KbqFilterRefresher`, so this
- * is optional cleanup that can never break a consumer build.
+ * idempotent. The `KbqFilterBarRefresher` alias was removed in 21.0.0.
  */
 const tsRenameReplacements = [{ from: '\\bKbqFilterBarRefresher\\b', to: 'KbqFilterRefresher' }];
 /**

package/schematics/migrations/filter-bar-signals/index.js

@@ -3,19 +3,18 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
 var ts = require('typescript');
-var utils_ast = require('../../utils/ast.js');
 var utils_messages = require('../../utils/messages.js');
-var utils_packageConfig = require('../../utils/package-config.js');
+var utils_packageConfig = require('../../package-config-BhU2TfC8.js');
+var signalMembersMigration = require('../../signal-members-migration-BoAJKutT.js');
+var templateRefAccess = require('../../template-ref-access-DLNoxmmG.js');
 var utils_typescript = require('../../utils/typescript.js');
 var migrations_filterBarSignals_data = require('./data.js');
 require('@angular-devkit/schematics');
 require('@schematics/angular/utility');
+require('../../utils/ast.js');
 
 const TS_EXT = '.ts';
 const HTML_EXT = '.html';
-function escapeRegExp(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
 /** Applies text-span edits to `content`, right-to-left, so earlier edits don't shift later offsets. */
 function applyEdits(content, edits) {
     const sorted = [...edits].sort((a, b) => b.start - a.start || b.end - a.end);
@@ -25,221 +24,103 @@ function applyEdits(content, edits) {
     }
     return result;
 }
-const isFunctionLike = (node) => ts.isFunctionDeclaration(node) ||
-    ts.isMethodDeclaration(node) ||
-    ts.isConstructorDeclaration(node) ||
-    ts.isArrowFunction(node) ||
-    ts.isFunctionExpression(node) ||
-    ts.isGetAccessorDeclaration(node) ||
-    ts.isSetAccessorDeclaration(node);
-/** Walks up from `node` to the nearest ancestor matching `predicate`. */
-function findAncestor(node, predicate) {
-    let current = node.parent;
-    while (current) {
-        if (predicate(current))
-            return current;
-        current = current.parent;
-    }
-    return undefined;
-}
-/** Whether a type annotation refers to the filter bar (`KbqFilterBar` / `KbqFilterBarHost`). */
-function isFilterBarType(type) {
-    return (!!type &&
-        ts.isTypeReferenceNode(type) &&
-        ts.isIdentifier(type.typeName) &&
-        (type.typeName.text === migrations_filterBarSignals_data.FILTER_BAR_TYPE || type.typeName.text === migrations_filterBarSignals_data.FILTER_BAR_HOST_TYPE));
+/** The `KbqFilterBar` / `KbqFilterBarHost` receivers of a file, typed by annotation or `inject()`. */
+function collectFileReceivers(sourceFile) {
+    return {
+        receivers: signalMembersMigration.collectAllReceivers(sourceFile, [migrations_filterBarSignals_data.FILTER_BAR_TYPE, migrations_filterBarSignals_data.FILTER_BAR_HOST_TYPE]),
+        bindings: signalMembersMigration.collectBindings(sourceFile)
+    };
 }
-const FIELD_MODIFIERS = new Set([
-    ts.SyntaxKind.PrivateKeyword,
-    ts.SyntaxKind.PublicKeyword,
-    ts.SyntaxKind.ProtectedKeyword,
-    ts.SyntaxKind.ReadonlyKeyword
-]);
 /**
- * Collects the receivers whose static type is a filter bar, by explicit annotation only (no cross-package
- * type resolution): method/function params, class fields (incl. `@ViewChild(KbqFilterBar) x: KbqFilterBar`
- * and constructor parameter-properties) and typed locals.
+ * Whether `node` accesses a signal member on a filter-bar receiver. The shared engine resolves the receiver at
+ * this exact position, so a nested declaration that shadows its name or a `function` that rebinds `this` is
+ * not followed. A signal query holds the instance behind a call of its own, which this pass does not reach.
  */
-function collectReceivers(sourceFile) {
-    const receivers = [];
-    const add = (text, scope) => receivers.push({ text, start: scope.getStart(sourceFile), end: scope.getEnd() });
+function isSignalMemberAccess(node, sourceFile, scope) {
+    if (!ts.isPropertyAccessExpression(node) ||
+        !ts.isIdentifier(node.name) ||
+        !migrations_filterBarSignals_data.SIGNAL_MEMBERS.includes(node.name.text)) {
+        return false;
+    }
+    const receiver = signalMembersMigration.resolveReceiver(node.expression, node, sourceFile, scope.receivers, scope.bindings);
+    return !!receiver && !receiver.signalQuery;
+}
+/** Collects edits for every read/write of a signal member on a known filter-bar receiver. */
+function collectAccessEdits(sourceFile, scope) {
+    const edits = [];
     const visit = (node) => {
-        if (ts.isParameter(node) && ts.isIdentifier(node.name) && isFilterBarType(node.type)) {
-            add(node.name.text, findAncestor(node, isFunctionLike) ?? sourceFile);
-            // A constructor parameter-property is also a class field, reachable as `this.<name>`.
-            if (node.modifiers?.some((modifier) => FIELD_MODIFIERS.has(modifier.kind))) {
-                const owner = findAncestor(node, ts.isClassDeclaration);
-                if (owner)
-                    add(`this.${node.name.text}`, owner);
-            }
-        }
-        else if (ts.isPropertyDeclaration(node) && ts.isIdentifier(node.name) && isFilterBarType(node.type)) {
-            const owner = findAncestor(node, ts.isClassDeclaration);
-            if (owner)
-                add(`this.${node.name.text}`, owner);
-        }
-        else if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && isFilterBarType(node.type)) {
-            add(node.name.text, findAncestor(node, isFunctionLike) ?? sourceFile);
-        }
+        if (isSignalMemberAccess(node, sourceFile, scope))
+            signalMembersMigration.classifyAccess(node, sourceFile, migrations_filterBarSignals_data.WRITABLE_MEMBERS, edits);
         node.forEachChild(visit);
     };
     visit(sourceFile);
-    return receivers;
-}
-/** Classifies a matched property access and appends the resulting edit(s). */
-function classifyAccess(node, sourceFile, edits) {
-    const parent = node.parent;
-    // Already migrated: `x.filter()` (call) or `x.filter.set(...)` — leave alone (idempotent).
-    if (ts.isCallExpression(parent) && parent.expression === node)
-        return;
-    if (ts.isPropertyAccessExpression(parent) && parent.expression === node && parent.name.text === 'set')
-        return;
-    // Write target: `x.filter = RHS` → `x.filter.set(RHS)` (writable members only).
-    if (ts.isBinaryExpression(parent) &&
-        parent.left === node &&
-        parent.operatorToken.kind === ts.SyntaxKind.EqualsToken) {
-        if (migrations_filterBarSignals_data.WRITABLE_MEMBERS.has(node.name.text)) {
-            const rhs = parent.right;
-            // Replace ` = ` with `.set(` and close after the right-hand side; keeping the RHS span intact
-            // lets any nested read edits inside it still apply.
-            edits.push({ start: node.getEnd(), end: rhs.getStart(sourceFile), text: '.set(' });
-            edits.push({ start: rhs.getEnd(), end: rhs.getEnd(), text: ')' });
-        }
-        return;
-    }
-    // Read (incl. optional chain `x?.filter`): append `()`.
-    edits.push({ start: node.getEnd(), end: node.getEnd(), text: '()' });
+    return edits;
 }
-/** Collects edits for every read/write of a signal member on a known filter-bar receiver. */
-function collectAccessEdits(sourceFile, receivers) {
-    const edits = [];
+/** Signal members written on a filter-bar receiver in a form the rewrite leaves for the consumer. */
+function collectWrites(sourceFile, scope) {
+    const writes = { readOnlyWrites: new Set(), compoundWrites: new Set() };
     const visit = (node) => {
-        if (ts.isPropertyAccessExpression(node) &&
-            ts.isIdentifier(node.name) &&
-            migrations_filterBarSignals_data.SIGNAL_MEMBERS.includes(node.name.text)) {
-            const receiverText = node.expression.getText(sourceFile);
-            const start = node.getStart(sourceFile);
-            const end = node.getEnd();
-            const inScope = receivers.some((r) => r.text === receiverText && start >= r.start && end <= r.end);
-            if (inScope)
-                classifyAccess(node, sourceFile, edits);
+        if (isSignalMemberAccess(node, sourceFile, scope) && signalMembersMigration.isWriteTarget(node)) {
+            const name = node.name.text;
+            if (!migrations_filterBarSignals_data.WRITABLE_MEMBERS.has(name))
+                writes.readOnlyWrites.add(name);
+            else if (!signalMembersMigration.isPlainAssignment(node))
+                writes.compoundWrites.add(name);
         }
         node.forEachChild(visit);
     };
     visit(sourceFile);
-    return edits;
+    return writes;
 }
 /** Pass A — rewrite programmatic reads/writes of filter-bar signal members in TypeScript code. */
 function migrateTsExpressions(content, fileName) {
     const sourceFile = ts.createSourceFile(fileName, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
-    const receivers = collectReceivers(sourceFile);
-    if (receivers.length === 0)
+    const scope = collectFileReceivers(sourceFile);
+    if (scope.receivers.length === 0)
         return content;
-    const edits = collectAccessEdits(sourceFile, receivers);
+    const edits = collectAccessEdits(sourceFile, scope);
     return edits.length > 0 ? applyEdits(content, edits) : content;
 }
-/** Collects template reference variable names bound to a `<kbq-filter-bar>` element. */
-class FilterBarRefCollector {
-    constructor() {
-        this.refs = new Set();
-    }
-    visitElement(element) {
-        if (element.name === migrations_filterBarSignals_data.FILTER_BAR_ELEMENT) {
-            for (const attr of element.attrs ?? []) {
-                if (typeof attr.name !== 'string')
-                    continue;
-                if (attr.name.startsWith('#'))
-                    this.refs.add(attr.name.slice(1));
-                else if (attr.name.startsWith('ref-'))
-                    this.refs.add(attr.name.slice(4));
-            }
-        }
-        this.visitChildren(element);
-    }
-    visitBlock(block) {
-        this.visitChildren(block);
-    }
-    visitChildren(node) {
-        for (const child of node.children ?? []) {
-            child.visit(this);
-        }
-    }
-    visitAttribute() { }
-    visitText() { }
-    visitComment() { }
-    visitExpansion() { }
-    visitExpansionCase() { }
-    visitBlockParameter() { }
-    visitLetDeclaration() { }
-}
-/** Rewrites `ref.member` reads to `ref.member()` for the given refs, scoped to those exact identifiers. */
-function rewriteRefReads(template, refs) {
-    const members = migrations_filterBarSignals_data.SIGNAL_MEMBERS.join('|');
-    let content = template;
-    let changed = false;
-    for (const ref of refs) {
-        // `\bref\.(member)\b(?!\s*\()` — skip anything already invoked, so the rewrite is idempotent.
-        const pattern = new RegExp(`\\b(${escapeRegExp(ref)})\\.(${members})\\b(?!\\s*\\()`, 'g');
-        const next = content.replace(pattern, '$1.$2()');
-        if (next !== content) {
-            content = next;
-            changed = true;
-        }
-    }
-    return { content, changed };
+/** Merges the writes in `from` into `into`. */
+function mergeWrites(into, from) {
+    from.readOnlyWrites.forEach((member) => into.readOnlyWrites.add(member));
+    from.compoundWrites.forEach((member) => into.compoundWrites.add(member));
 }
-/** Pass B (core) — parse a template, discover filter-bar refs, rewrite their signal reads. */
+/** What a reference variable on `<kbq-filter-bar>` reaches. */
+const REF_POLICY = { members: migrations_filterBarSignals_data.SIGNAL_MEMBERS, writable: migrations_filterBarSignals_data.WRITABLE_MEMBERS };
+/** Pass B (core) — parse a template, discover filter-bar refs, rewrite their signal reads and `filter` writes. */
 async function migrateTemplate(template) {
+    const untouched = {
+        content: template,
+        changed: false,
+        readOnlyWrites: new Set(),
+        compoundWrites: new Set()
+    };
     if (!template.includes(migrations_filterBarSignals_data.FILTER_BAR_ELEMENT))
-        return { content: template, changed: false };
+        return untouched;
     const parsed = await utils_typescript.parseTemplate(template);
     if (!parsed.tree)
-        return { content: template, changed: false };
-    const collector = new FilterBarRefCollector();
-    utils_ast.visitAll(collector, parsed.tree.rootNodes);
-    if (collector.refs.size === 0)
-        return { content: template, changed: false };
-    return rewriteRefReads(template, [...collector.refs]);
-}
-/** Interior `[start, end]` ranges of inline `@Component({ template: '…' })` string literals. */
-function collectInlineTemplateRanges(sourceFile) {
-    const ranges = [];
-    utils_typescript.forEachClass(sourceFile, (node) => {
-        const decorator = ts
-            .getDecorators(node)
-            ?.find((dec) => ts.isCallExpression(dec.expression) &&
-            ts.isIdentifier(dec.expression.expression) &&
-            dec.expression.expression.text === 'Component');
-        if (!decorator || !ts.isCallExpression(decorator.expression))
-            return;
-        const [arg] = decorator.expression.arguments;
-        if (!arg || !ts.isObjectLiteralExpression(arg))
-            return;
-        for (const prop of arg.properties) {
-            if (ts.isPropertyAssignment(prop) &&
-                (ts.isIdentifier(prop.name) || ts.isStringLiteralLike(prop.name)) &&
-                prop.name.text === 'template' &&
-                ts.isStringLiteralLike(prop.initializer) &&
-                prop.initializer.text) {
-                // +1 / -1 to exclude the opening/closing quote characters.
-                ranges.push({ start: prop.initializer.getStart(sourceFile) + 1, end: prop.initializer.getEnd() - 1 });
-            }
-        }
-    });
-    return ranges;
+        return untouched;
+    const { rootNodes } = parsed.tree;
+    // `KbqFilterBar` has no `exportAs`, so only a bare `#ref` is the filter bar; `#ref="ngModel"` names another
+    // directive.
+    const { content, readOnlyWrites, compoundWrites } = templateRefAccess.rewriteRefAccesses(template, rootNodes, (element, value) => element.name === migrations_filterBarSignals_data.FILTER_BAR_ELEMENT && !value ? REF_POLICY : undefined);
+    return { content, changed: content !== template, readOnlyWrites, compoundWrites };
 }
 /** Pass B (inline) — rewrite filter-bar ref reads inside inline component templates. */
 async function migrateInlineTemplates(content, fileName) {
     const sourceFile = ts.createSourceFile(fileName, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
-    const ranges = collectInlineTemplateRanges(sourceFile).sort((a, b) => b.start - a.start);
+    const ranges = utils_typescript.collectInlineTemplateRanges(sourceFile).sort((a, b) => b.start - a.start);
+    const writes = { readOnlyWrites: new Set(), compoundWrites: new Set() };
     let result = content;
     for (const { start, end } of ranges) {
-        const { content: rewritten, changed } = await migrateTemplate(result.slice(start, end));
-        if (changed) {
-            result = result.slice(0, start) + rewritten + result.slice(end);
+        const outcome = await migrateTemplate(result.slice(start, end));
+        mergeWrites(writes, outcome);
+        if (outcome.changed) {
+            result = result.slice(0, start) + outcome.content + result.slice(end);
         }
     }
-    return result;
+    return { content: result, ...writes };
 }
 /** Pass C — safe identifier renames. */
 function applyRenames(content) {
@@ -256,6 +137,27 @@ function logWarnings(context, filePath, content) {
         }
     }
 }
+/** Reports writes to signal members that are read-only now, made in code or through a template reference. */
+function warnReadOnlyWrites(context, filePath, members) {
+    if (members.size === 0)
+        return;
+    utils_messages.logMessage(context.logger, [
+        `[filter-bar-signals] ${filePath}`,
+        `  \`${[...members].join('`, `')}\` can no longer be assigned: they are read-only signals now. Bind`,
+        `  \`[pipeTemplates]\` in the template instead; the \`is*\` state follows \`filter\`.`
+    ]);
+}
+/** Reports writes to `filter` that have no `.set()` form, made in code or through a template reference. */
+function warnCompoundWrites(context, filePath, members) {
+    if (members.size === 0)
+        return;
+    utils_messages.logMessage(context.logger, [
+        `[filter-bar-signals] ${filePath}`,
+        `  \`${[...members].join('`, `')}\` is a writable signal now, but only a plain \`=\` is rewritten to`,
+        `  \`.set()\`: a compound assignment, an increment, \`delete\` or a destructuring target was left as it`,
+        `  is. Write it with \`.set()\` or \`.update()\`.`
+    ]);
+}
 /** A `.ts` file is a filter-bar consumer if it names the type or imports the package. */
 function referencesFilterBar(content) {
     return /\bKbqFilterBar\b/.test(content) || content.includes('@koobiq/components/filter-bar');
@@ -271,9 +173,7 @@ function filterBarSignals(options) {
         const rootDir = root ? tree.getDir(root) : tree.root;
         const tsPaths = [];
         const htmlPaths = [];
-        rootDir.visit((filePath) => {
-            if (filePath.includes('node_modules') || filePath.includes('/dist/'))
-                return;
+        utils_packageConfig.visitProjectFiles(rootDir, (filePath) => {
             if (filePath.endsWith(TS_EXT))
                 tsPaths.push(filePath);
             else if (filePath.endsWith(HTML_EXT))
@@ -296,16 +196,21 @@ function filterBarSignals(options) {
             if (!original || !referencesFilterBar(original))
                 continue;
             logWarnings(context, filePath, original);
-            let content = migrateTsExpressions(original, filePath);
-            content = await migrateInlineTemplates(content, filePath);
-            content = applyRenames(content);
-            commit(filePath, original, content);
+            const sourceFile = ts.createSourceFile(filePath, original, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+            const writes = collectWrites(sourceFile, collectFileReceivers(sourceFile));
+            const inline = await migrateInlineTemplates(migrateTsExpressions(original, filePath), filePath);
+            mergeWrites(writes, inline);
+            warnReadOnlyWrites(context, filePath, writes.readOnlyWrites);
+            warnCompoundWrites(context, filePath, writes.compoundWrites);
+            commit(filePath, original, applyRenames(inline.content));
         }
         for (const filePath of htmlPaths) {
             const original = tree.read(filePath)?.toString();
             if (!original)
                 continue;
-            const { content, changed } = await migrateTemplate(original);
+            const { content, changed, readOnlyWrites, compoundWrites } = await migrateTemplate(original);
+            warnReadOnlyWrites(context, filePath, readOnlyWrites);
+            warnCompoundWrites(context, filePath, compoundWrites);
             if (changed)
                 commit(filePath, original, content);
         }

package/schematics/migrations/filter-bar-state-saving-default/README.md

@@ -0,0 +1,53 @@
+# filter-bar-state-saving-default
+
+Migration schematic invoked automatically by `ng update @koobiq/components@20`
+(registered for `21.0.0-0`). Reports the consequences of `kbq-filter-bar` remembering which filter is
+selected and the edits made to it, with `useStateSaving` defaulting to `true`. It never writes to the
+tree.
+
+## Background
+
+The filter bar gained the same state saving the accordion, the tree, the tab group, the sidebar and the
+content panel already have, applied through the `KbqStateSaving` host directive, and it is on by default.
+With no `stateSavingKey` the key is derived from where the bar sits in the document — the chain of tag
+names up to `<body>`, cut short by the first author-written `id`, which becomes the anchor.
+
+One thing is different here. The components that shipped before it leave a controlled input alone: a
+sidebar with a bound `opened` persists nothing at all. The filter bar restores over the value a
+`[filter]` binding supplied at initialization, because `filter` is a `model()` — the restore writes
+through it, `filterChange` fires, and the application loads data for the restored filter exactly as it
+would for one the user had just picked. Only a change made after that wins.
+
+## What is stored
+
+The filter's `name`, whether it carried unsaved changes, and one entry per pipe: its `id` (or its `name`
+when it has none) and its value. Nothing else. A pipe built from a template keeps that template's
+`compareWith` and date bounds, and those do not survive being written to storage — so the rest of each
+pipe is rebuilt from `filters` and `pipeTemplates` while restoring, and a pipe whose template is gone is
+left out.
+
+`KbqFilter` has no id, so a filter is identified by its `name`: renaming a saved filter loses what was
+stored for it, and a name no longer in the list restores nothing. A list that arrives from a server is
+waited for — the restore applies as soon as the named filter appears, and is abandoned as soon as
+anything else changes the filter.
+
+## What it reports
+
+| Pattern                                      | Reported unless               |
+| -------------------------------------------- | ----------------------------- |
+| `<kbq-filter-bar>` / `[kbq-filter-bar]`      | `useStateSaving` is mentioned |
+| `[filter]` / `[(filter)]` on the bar         | `useStateSaving` is mentioned |
+| `<kbq-filters>` inside the bar               | `useStateSaving` is mentioned |
+| `compareWith` in a consumer file             | always                        |
+| `saveFilterState()` / `restoreFilterState()` | always                        |
+
+The last one is a reassurance rather than a warning: those two are unchanged, and are unrelated to
+`clearSavedState()` / `hasSavedState`.
+
+## Running it manually
+
+```bash
+ng generate @koobiq/components:filter-bar-state-saving-default --project my-app
+```
+
+Omit `--project` to inspect the whole workspace.

package/schematics/migrations/filter-bar-state-saving-default/data.js

@@ -0,0 +1,87 @@
+'use strict';
+
+/**
+ * Data for the `filter-bar-state-saving-default` migration.
+ *
+ * `KbqFilterBar` remembers which filter is selected and the edits made to it now, and `useStateSaving`
+ * defaults to `true`. Unlike the components that shipped before it, the bar restores over the value a
+ * `[filter]` binding supplied at initialization — it writes through the `filter` model, so `filterChange`
+ * fires and the application loads data for the restored filter. That is the part a consumer has to act
+ * on, and it is exactly the markup that says nothing about the input.
+ *
+ * Warn-only. Rewriting the markup to `[useStateSaving]="false"` would withhold the feature this release
+ * is shipping.
+ */
+/** Import specifiers that mark a file as a consumer of the filter bar. */
+const PACKAGES = ['@koobiq/components/filter-bar'];
+/** Identifier and element shapes that mark a consumer without an import. */
+const CONSUMER_TYPE = '\\bKbqFilterBar\\b|\\bkbq-filter-bar\\b';
+const FILTER_BAR = '<kbq-filter-bar\\b|\\[kbq-filter-bar\\]';
+/**
+ * Anything that makes a file a consumer, for the reports that key off a call site rather than off the
+ * rendered element — pipe templates are routinely declared in a `.ts` whose markup lives elsewhere.
+ */
+const CONSUMER = `${CONSUMER_TYPE}|\\bKbqPipeTemplate\\b|@koobiq/components/filter-bar`;
+const warnPatterns = [
+    {
+        anchor: FILTER_BAR,
+        pattern: FILTER_BAR,
+        unless: '\\buseStateSaving\\b',
+        message: 'Filter bars remember the selected filter and the edits made to it by default now: ' +
+            'useStateSaving defaults to true. Pass [useStateSaving]="false" to keep the previous ' +
+            'behaviour. What is stored is the filter name, whether it carried unsaved changes, and one ' +
+            'entry per pipe — its id (or name) and its value.'
+    },
+    {
+        anchor: FILTER_BAR,
+        pattern: '\\[\\(?filter\\)?\\]',
+        unless: '\\buseStateSaving\\b',
+        message: 'A restored filter overrides the value this [filter] binding supplies at initialization, and ' +
+            'writes through the model, so filterChange fires and the application fetches for it as it ' +
+            'would for one the user had picked. Only a later change wins — this is the one place the bar ' +
+            'differs from the components that persist a controlled input by leaving it alone.'
+    },
+    {
+        anchor: FILTER_BAR,
+        pattern: '<kbq-filters\\b',
+        unless: '\\buseStateSaving\\b',
+        message: 'A filter is identified by its name, the only identity KbqFilter has. Renaming a saved filter ' +
+            'therefore loses what was stored for it, and a name that is no longer in the filters list ' +
+            'restores nothing. Applications that load their filters from a server are waited for: the ' +
+            'restore applies as soon as the named filter appears.'
+    },
+    {
+        anchor: CONSUMER,
+        pattern: '\\bcompareWith\\b',
+        message: 'Restored pipe values come back as new objects, never the option instances in the templates. ' +
+            'This compareWith is what matches them again — keep it in step with what is stored, which is ' +
+            'the value alone.'
+    },
+    {
+        // Programmatic access names the class, which the markup-only anchor does not cover.
+        anchor: CONSUMER,
+        pattern: '\\.\\s*(saveFilterState|restoreFilterState)\\s*\\(',
+        message: 'saveFilterState()/restoreFilterState() are unchanged: they snapshot the filter in memory ' +
+            'within one session. Persistence is separate — clearSavedState() and hasSavedState are the ' +
+            'members that reach it, and the bar writes on every change by itself.'
+    }
+];
+/** Printed once, after the per-file reports. */
+const SUMMARY = [
+    '  A filter bar rendered inside an overlay does not persist: it is not in the document when it',
+    '  initializes and so has no stable key. The key otherwise comes from stateSavingKey, or is derived',
+    '  from the position in the document when none is given.',
+    '  Pipes are stored as a projection — id and value — and everything else is rebuilt from filters and',
+    '  pipeTemplates, because a pipe built from a template keeps that template compareWith and date',
+    '  bounds, which do not survive being written to storage. A pipe whose template is gone is left out.',
+    '  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.CONSUMER_TYPE = CONSUMER_TYPE;
+exports.PACKAGES = PACKAGES;
+exports.SUMMARY = SUMMARY;
+exports.warnPatterns = warnPatterns;