@koobiq/components 20.4.2 → 21.0.1

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 → data.cjs}

@@ -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.cjs

@@ -0,0 +1,225 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var ts = require('typescript');
+var utils_messages = require('../../utils/messages.cjs');
+var utils_packageConfig = require('../../utils/package-config.cjs');
+var utils_projectFiles = require('../../utils/project-files.cjs');
+var utils_signalMembersMigration = require('../../utils/signal-members-migration.cjs');
+var utils_templateRefAccess = require('../../utils/template-ref-access.cjs');
+var utils_typescript = require('../../utils/typescript.cjs');
+var migrations_filterBarSignals_data = require('./data.cjs');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+require('../../utils/ast.cjs');
+
+const TS_EXT = '.ts';
+const HTML_EXT = '.html';
+/** 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);
+    let result = content;
+    for (const { start, end, text } of sorted) {
+        result = result.slice(0, start) + text + result.slice(end);
+    }
+    return result;
+}
+/** The `KbqFilterBar` / `KbqFilterBarHost` receivers of a file, typed by annotation or `inject()`. */
+function collectFileReceivers(sourceFile) {
+    return {
+        receivers: utils_signalMembersMigration.collectAllReceivers(sourceFile, [migrations_filterBarSignals_data.FILTER_BAR_TYPE, migrations_filterBarSignals_data.FILTER_BAR_HOST_TYPE]),
+        bindings: utils_signalMembersMigration.collectBindings(sourceFile)
+    };
+}
+/**
+ * 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 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 = utils_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 (isSignalMemberAccess(node, sourceFile, scope))
+            utils_signalMembersMigration.classifyAccess(node, sourceFile, migrations_filterBarSignals_data.WRITABLE_MEMBERS, edits);
+        node.forEachChild(visit);
+    };
+    visit(sourceFile);
+    return 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 (isSignalMemberAccess(node, sourceFile, scope) && utils_signalMembersMigration.isWriteTarget(node)) {
+            const name = node.name.text;
+            if (!migrations_filterBarSignals_data.WRITABLE_MEMBERS.has(name))
+                writes.readOnlyWrites.add(name);
+            else if (!utils_signalMembersMigration.isPlainAssignment(node))
+                writes.compoundWrites.add(name);
+        }
+        node.forEachChild(visit);
+    };
+    visit(sourceFile);
+    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 scope = collectFileReceivers(sourceFile);
+    if (scope.receivers.length === 0)
+        return content;
+    const edits = collectAccessEdits(sourceFile, scope);
+    return edits.length > 0 ? applyEdits(content, edits) : content;
+}
+/** 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));
+}
+/** 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 untouched;
+    const parsed = await utils_typescript.parseTemplate(template);
+    if (!parsed.tree)
+        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 } = utils_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 = 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 outcome = await migrateTemplate(result.slice(start, end));
+        mergeWrites(writes, outcome);
+        if (outcome.changed) {
+            result = result.slice(0, start) + outcome.content + result.slice(end);
+        }
+    }
+    return { content: result, ...writes };
+}
+/** Pass C — safe identifier renames. */
+function applyRenames(content) {
+    let result = content;
+    for (const { from, to } of migrations_filterBarSignals_data.tsRenameReplacements) {
+        result = result.replace(new RegExp(from, 'g'), to);
+    }
+    return result;
+}
+function logWarnings(context, filePath, content) {
+    for (const { pattern, message } of migrations_filterBarSignals_data.warnPatterns) {
+        if (new RegExp(pattern).test(content)) {
+            utils_messages.logMessage(context.logger, [`[filter-bar-signals] ${filePath}`, `  ${message}`]);
+        }
+    }
+}
+/** 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');
+}
+function filterBarSignals(options) {
+    return async (tree, context) => {
+        const { project } = options;
+        // `ng update` invokes migrations with no options at all, and migrations.json declares no schema, so the
+        // schema default never reaches us — applying the fix is the intended behaviour there.
+        const fix = options.fix ?? true;
+        const projectDefinition = await utils_packageConfig.setupOptions(project, tree);
+        const root = projectDefinition?.root ?? '';
+        const rootDir = root ? tree.getDir(root) : tree.root;
+        const tsPaths = [];
+        const htmlPaths = [];
+        utils_projectFiles.visitProjectFiles(rootDir, (filePath) => {
+            if (filePath.endsWith(TS_EXT))
+                tsPaths.push(filePath);
+            else if (filePath.endsWith(HTML_EXT))
+                htmlPaths.push(filePath);
+        });
+        let touched = 0;
+        const commit = (filePath, original, updated) => {
+            if (updated === original)
+                return;
+            touched++;
+            if (fix) {
+                tree.overwrite(filePath, updated);
+            }
+            else {
+                utils_messages.logMessage(context.logger, [`[filter-bar-signals] would update ${filePath} (run with --fix to apply)`]);
+            }
+        };
+        for (const filePath of tsPaths) {
+            const original = tree.read(filePath)?.toString();
+            if (!original || !referencesFilterBar(original))
+                continue;
+            logWarnings(context, filePath, original);
+            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, readOnlyWrites, compoundWrites } = await migrateTemplate(original);
+            warnReadOnlyWrites(context, filePath, readOnlyWrites);
+            warnCompoundWrites(context, filePath, compoundWrites);
+            if (changed)
+                commit(filePath, original, content);
+        }
+        utils_messages.logMessage(context.logger, [
+            `[filter-bar-signals] processed tree under "${root || '<workspace root>'}", ` +
+                `${fix ? 'updated' : 'would update'} ${touched} file(s).`
+        ]);
+    };
+}
+
+exports.default = filterBarSignals;

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.cjs

@@ -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;

package/schematics/migrations/filter-bar-state-saving-default/index.cjs

@@ -0,0 +1,62 @@
+'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_filterBarStateSavingDefault_data = require('./data.cjs');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+const LABEL = '[filter-bar-state-saving-default]';
+const EXTENSIONS = ['.ts', '.html'];
+/** A file is a consumer if it imports the package, names the component, or renders one. */
+function referencesConsumer(content) {
+    return migrations_filterBarStateSavingDefault_data.PACKAGES.some((name) => content.includes(name)) || new RegExp(migrations_filterBarStateSavingDefault_data.CONSUMER_TYPE).test(content);
+}
+/**
+ * Reports the consequences of the filter bar persisting the selected filter and the edits made to it,
+ * 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 most reports key off the rendered element rather than off
+ * an import.
+ */
+function filterBarStateSavingDefault(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 || !referencesConsumer(content))
+                return;
+            consumers++;
+            for (const { anchor, pattern, unless, message } of migrations_filterBarStateSavingDefault_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 filter bar, so the summary would only be noise.
+        if (consumers === 0)
+            return;
+        utils_messages.logMessage(context.logger, [
+            `${LABEL} processed kbq-filter-bar under "${root || '<workspace root>'}", ` +
+                `${consumers} file(s) reference it, ${reported} report(s) raised.`,
+            ...migrations_filterBarStateSavingDefault_data.SUMMARY
+        ]);
+    };
+}
+
+exports.default = filterBarStateSavingDefault;

package/schematics/migrations/filter-bar-state-saving-default/schema.json

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

@@ -0,0 +1,67 @@
+# flag-inner-html
+
+Migration schematic invoked automatically by `ng update @koobiq/components@20`
+(registered for `21.0.0-0`). Moves `[innerHTML]` bindings off the `<kbq-flag>` host element onto the
+`svg` input the flag review added, and reports the behavior changes that have no call site to point
+at.
+
+## Background
+
+`KbqFlag` renders `<ng-content />`, so the host element is where projected nodes land. A parent
+binding `[innerHTML]` on `<kbq-flag>` compiles to a write of `hostElement.innerHTML` during the
+parent's update pass — the same element. The two only coexisted because the component's own view
+contributed no DOM: with nothing projected there was nothing for the write to destroy, which is why
+every published example got away with it.
+
+The review gave the string form a slot of its own:
+
+```html
+<!-- before -->
+<kbq-flag decorative [innerHTML]="flag" />
+
+<!-- after -->
+<kbq-flag decorative [svg]="flag" />
+```
+
+The `svg` input renders into a `<span>` inside the component's view, so projected content and string
+content no longer compete for the host element. The value is unchanged — Angular's sanitizer still
+strips an `<svg>` that has not been bypassed, so a flag coming from a package as a string still has to go through
+`DomSanitizer.bypassSecurityTrustHtml`, and only ever for markup known at build time.
+
+## What it rewrites
+
+`[innerHTML]` → `[svg]`, inside `<kbq-flag …>` opening tags only, in `.ts` and `.html` files that
+reference the flag. A binding on any other element — including one on a wrapper projected _into_ a
+flag — is left alone, because there the write targets an element the component does not own.
+
+## What it does not reach
+
+The rewrite is textual, so it only sees a literal `[innerHTML]=` inside a literal `<kbq-flag …>`
+opening tag. Two forms are invisible to it and have to be moved by hand:
+
+- an `innerHTML` write made from TypeScript against a flag element, through `Renderer2.setProperty`
+  or an assignment to a queried element's `innerHTML`;
+- a wrapper component of your own that publishes an `innerHTML`-named input and forwards it. The
+  `<kbq-flag [innerHTML]="…">` inside its template is rewritten, but the input it exposes to its own
+  callers keeps the old name.
+
+## Notes with no call site to point at
+
+- **A flag with no `label` is now `aria-hidden`.** The unlabelled, non-decorative flag reached the
+  accessibility tree as a nameless graphic, which the guide already called out as the one case that
+  must not happen. Give a meaningful flag a `label` — including one whose only name came from the
+  projected image (`alt`, an SVG `<title>`), which the default now hides.
+- **An inline `<svg>` is cropped instead of letterboxed.** `object-fit: cover` is inert on an inline
+  `<svg>` — it is not a replaced element — so a source whose ratio differed from the shape rendered
+  with transparent bands; `square` and `circle` were the visible cases. The same flag passed as an
+  `<img>` always cropped, and the two now match.
+- **`--kbq-flag-empty-background` resolves to an opaque neutral** instead of the translucent disabled
+  state, so the `empty` placeholder no longer takes on the hue of the surface behind it.
+- **The flag tokens are declared at zero specificity.** An override that used to lose to `.kbq-flag`
+  on source order now wins, so a redundant `!important` or an extra selector can be dropped.
+
+## Running it on its own
+
+```bash
+ng g @koobiq/components:flag-inner-html --project <your project>
+```

package/schematics/migrations/flag-inner-html/data.cjs

@@ -0,0 +1,58 @@
+'use strict';
+
+/**
+ * Data for the `flag-inner-html` migration.
+ *
+ * `KbqFlag` renders `<ng-content />`, so the host element is where projected nodes land. A parent
+ * binding `[innerHTML]` on `<kbq-flag>` writes that same element, and the two only coexisted because
+ * the component's own view contributed no DOM. The review gave the string form a slot of its own —
+ * the `svg` input — and the template now creates a node inside the host, so a host-level
+ * `[innerHTML]` write removes it along with anything projected.
+ *
+ * The rename is mechanical, so this migration rewrites it. Everything else in the review is a
+ * behavior change with no call site to point at, and is reported once per project.
+ */
+/** Import specifier that marks a file as a flag consumer. */
+const FLAG_PACKAGE = '@koobiq/components/flag';
+/** Identifier and element shapes that mark a consumer without an import. */
+const FLAG_TYPE = '\\bKbqFlag\\w*\\b|\\bkbq-flag\\b';
+/**
+ * Opening `<kbq-flag …>` tag, including the self-closing form. Closing tags do not match.
+ *
+ * Attribute values are matched as opaque quoted strings, so a `>` inside an attribute expression
+ * (e.g. `[class.a]="x > y"`) does not end the match early and strand a later `[innerHTML]` binding
+ * on the same tag outside it. The third alternative excludes both quote characters so that only one
+ * branch can consume a quote: an unterminated tag would otherwise backtrack exponentially.
+ */
+const FLAG_OPEN_TAG = /<kbq-flag\b(?:"[^"]*"|'[^']*'|[^>"'])*>/g;
+/** The binding this migration moves off the host element. */
+const INNER_HTML_BINDING = /\[innerHTML\]\s*=/g;
+const REWRITE_MESSAGE = '[innerHTML] on <kbq-flag> was rewritten to [svg]. The host element is where projected content ' +
+    'lands, so an innerHTML write replaces it; the svg input renders into a slot of its own. Pass it ' +
+    'the same SafeHtml — Angular still strips an <svg> that has not been bypassed.';
+/** Printed once per project, after the per-file reports. */
+const SUMMARY = [
+    '  The rewrite is textual and only sees a literal [innerHTML]= inside a literal <kbq-flag …> ' +
+        'opening tag. An innerHTML write made from TypeScript against a flag element, and an ' +
+        'innerHTML-named input that a wrapper component of yours forwards to a flag, are both ' +
+        'invisible to it and have to be moved by hand.',
+    '  A flag with no `label` is now aria-hidden. The unlabelled, non-decorative flag reached the ' +
+        'accessibility tree as a nameless graphic, which the guide already called out as the one case ' +
+        'that must not happen. Give a meaningful flag a `label` — including one whose only name came ' +
+        'from the projected image (`alt`, an SVG `<title>`), which the default now hides.',
+    '  An inline <svg> is cropped instead of letterboxed. `object-fit: cover` is inert on an inline ' +
+        '<svg> — it is not a replaced element — so a source whose ratio differed from the shape used to ' +
+        'render with transparent bands; `square` and `circle` are the visible cases. The same flag ' +
+        'passed as an <img> always cropped, and the two now match.',
+    '  --kbq-flag-empty-background resolves to an opaque neutral instead of the translucent disabled ' +
+        'state, so the `empty` placeholder no longer takes on the hue of the surface behind it.',
+    '  The flag tokens are declared at zero specificity. An override that used to lose to .kbq-flag ' +
+        'on source order now wins, so a redundant `!important` or an extra selector can be dropped.'
+];
+
+exports.FLAG_OPEN_TAG = FLAG_OPEN_TAG;
+exports.FLAG_PACKAGE = FLAG_PACKAGE;
+exports.FLAG_TYPE = FLAG_TYPE;
+exports.INNER_HTML_BINDING = INNER_HTML_BINDING;
+exports.REWRITE_MESSAGE = REWRITE_MESSAGE;
+exports.SUMMARY = SUMMARY;