@koobiq/components 20.4.2 → 21.0.1

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

@@ -0,0 +1,20 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-timepicker-signals",
+    "title": "Koobiq components timepicker signals migration",
+    "type": "object",
+    "properties": {
+        "project": {
+            "type": "string",
+            "description": "Name of the project to migrate. If omitted, the migration runs over the whole tree.",
+            "$default": {
+                "$source": "projectName"
+            }
+        },
+        "fix": {
+            "type": "boolean",
+            "default": true,
+            "description": "When true, applies all auto-fix replacements. When false, prints what would change without writing."
+        }
+    }
+}

package/schematics/migrations/timezone-grouping-utils/README.md

@@ -0,0 +1,73 @@
+# timezone-grouping-utils
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21`
+(registered for `21.0.0-0`). Reports the timezone call sites that the review's split of
+`getZonesGroupedByCountry` breaks, and the members whose type or behavior changed under them. It never
+writes to the tree.
+
+## Background
+
+The package ships no timezone data — every consumer feeds its own rows through two exported utilities, and
+both were wrong.
+
+| Member                                              | Before                                         | After                                         |
+| --------------------------------------------------- | ---------------------------------------------- | --------------------------------------------- |
+| `getZonesGroupedByCountry(data, label?, priority?)` | one privileged country plus one "Other" bucket | `getZonesGroupedByCountry(data)`, per country |
+| —                                                   | —                                              | `promoteCountry`, `collapseOtherCountries`    |
+| host country                                        | read from `Intl` inside the grouping           | `kbqResolveHostCountry(data)`                 |
+| `timezonesSortComparator`                           | returned the first zone's offset               | returns the difference, ties on `city`        |
+| `KbqTimezoneGroup.countryCode`                      | `string`                                       | `string \| null`                              |
+| `KbqTimezoneZone.offset`                            | required, rendered verbatim                    | optional, resolved from `id` when absent      |
+| `kbq-timezone-select` `multiple`, `multiline`       | accepted, half-rendered                        | throws                                        |
+
+`timezonesSortComparator` deserves a note. Its body returned `parseOffset(first.offset)` rather than a
+difference, so `cmp(+05:00, +02:00)` and `cmp(+02:00, +05:00)` were both positive: it is not a valid
+comparator, and the order a list came out in was whatever the engine's sort algorithm made of it. Any zone
+at `00:00:00` compared equal to everything, and an unparsable offset was `NaN`, which V8 reads as `0`.
+
+`getZonesGroupedByCountry` never grouped by country either. It read
+`Intl.DateTimeFormat().resolvedOptions().timeZone` at call time and produced at most two groups — the host
+machine's country and one bucket holding everything else with its `countryName` overwritten. The same input
+rendered differently on a developer's laptop, on CI and on an SSR server versus the browser that hydrated it.
+
+## What it does _not_ do
+
+Nothing is rewritten. Restoring the old rendering takes a composition of two or three helpers, and which one
+a call site meant — promote the country, collapse the rest, or both — cannot be read off the call.
+
+| Pattern                                            | Manual migration                                                                                                |
+| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `getZonesGroupedByCountry(zones, label, country)`  | `collapseOtherCountries(getZonesGroupedByCountry(zones), country, label)`                                       |
+| `getZonesGroupedByCountry(zones, label)`           | `collapseOtherCountries(getZonesGroupedByCountry(zones), kbqResolveHostCountry(zones), label)`                  |
+| `getZonesGroupedByCountry(zones)`                  | `promoteCountry(getZonesGroupedByCountry(zones), kbqResolveHostCountry(zones))` for a real per-country grouping |
+| `group.countryCode`                                | Nullable — an aggregate bucket belongs to no country                                                            |
+| `zone.offset`                                      | `resolveZoneOffset(zone)`; omit the field to have it derived from the IANA `id`                                 |
+| `multiple` or `multiline` on `kbq-timezone-select` | Use `kbq-select`                                                                                                |
+
+## Notes with no call site to point at
+
+- The option tooltip carries the same filtered city list the option renders. It used to carry the
+  unfiltered one while the show/hide decision was measured on the filtered box, so a search opened a hint
+  listing exactly the cities it had just removed.
+- `UtcOffsetPipe` and `CitiesByFilterPipe` are exported, and `KbqTimezoneModule` re-exports
+  `KbqOptionModule`, so the documented usage with `kbq-optgroup` works from the module alone.
+- `filterCitiesBySearchString` rejoins on `', '` instead of `','`, so a filtered list no longer begins with
+  a stray space. Its offset guard recognizes an offset that is still being typed — `+`, `+03:`, `0330` — and
+  leaves the city list whole for it, as before. A lone hyphen-minus is the one sign it now searches for,
+  because it is also how `Baden-Baden` is found.
+- Typeahead matches the city. `getLabel()` used to return the whole line, which opens with `UTC`, so typing
+  a city's first letters never moved past the first option, and a zone west of UTC — written with U+2212 —
+  could not be reached by typing at all.
+- The overlay pane carries `kbq-select-overlay`, as it does for `kbq-select`: the forked template did not
+  bind `cdkConnectedOverlayPanelClass`, so a style keyed on `.cdk-overlay-pane.kbq-select-overlay` missed
+  the timezone panel.
+- `KbqTimezoneOption` provides `KBQ_TITLE_TEXT_REF` and marks its city label, so a `[kbq-title]` inside an
+  option measures the label rather than the whole two-column row.
+- The search placeholder follows the active locale instead of latching to whichever one was applied first.
+  A placeholder the consumer binds still wins.
+
+## Running it manually
+
+```
+ng generate @koobiq/components:timezone-grouping-utils --project my-app
+```

package/schematics/migrations/timezone-grouping-utils/data.cjs

@@ -0,0 +1,101 @@
+'use strict';
+
+/**
+ * Data for the `timezone-grouping-utils` migration.
+ *
+ * The timezone review split the two exported utilities that every consumer routes its data through:
+ *
+ * - `getZonesGroupedByCountry(data, otherCountriesLabel?, priorityCountry?)` → `getZonesGroupedByCountry(data)`.
+ *   It groups by country now instead of producing "the host's country plus one Other bucket", and it no
+ *   longer reads `Intl`. The old behaviour is `collapseOtherCountries(getZonesGroupedByCountry(data),
+ *   priorityCountry ?? kbqResolveHostCountry(data), otherCountriesLabel)`.
+ * - `timezonesSortComparator` returns the difference of the two offsets instead of the first zone's offset,
+ *   and ties break on `city` rather than on `countryName`, which was always equal inside a group.
+ * - `KbqTimezoneGroup.countryCode` is `string | null` — the aggregate bucket belongs to no country.
+ * - `KbqTimezoneZone.offset` is optional; omitted, it is resolved from the IANA `id` at render time.
+ * - `kbq-timezone-select` rejects `multiple` and `multiline` instead of half-rendering them.
+ *
+ * Warn-only. The replacement for a dropped argument is a composition whose shape depends on what the call
+ * site meant by it, and neither the promotion nor the aggregate label can be derived from the call.
+ */
+/** Import specifier that marks a file as a timezone consumer. */
+const TIMEZONE_PACKAGE = '@koobiq/components/timezone';
+/** Identifier and element shapes that mark a consumer without an import. */
+const TIMEZONE_TYPE = '\\bKbqTimezone\\w*\\b|\\bkbq-timezone-(?:select|option)\\b|\\bgetZonesGroupedByCountry\\b|\\btimezonesSortComparator\\b';
+const warnPatterns = [
+    {
+        anchor: TIMEZONE_TYPE,
+        pattern: '\\bgetZonesGroupedByCountry\\s*\\([^)]*,',
+        message: 'getZonesGroupedByCountry now takes only the zones: the otherCountriesLabel and priorityCountry ' +
+            'parameters are gone, and the function groups by country instead of producing the host country ' +
+            'plus one "Other" bucket. Compose the old behaviour explicitly — ' +
+            'collapseOtherCountries(getZonesGroupedByCountry(zones), priorityCountry, otherCountriesLabel) — ' +
+            'and use kbqResolveHostCountry(zones) where the country used to be read from Intl.'
+    },
+    {
+        anchor: TIMEZONE_TYPE,
+        // Any call with no comma before its first closing parenthesis, so an argument that is itself a call —
+        // `getZonesGroupedByCountry(this.getZones())` — is reported too: it compiles unchanged, which is exactly
+        // why it must not go unmentioned.
+        pattern: '\\bgetZonesGroupedByCountry\\s*\\((?![^)]*,)',
+        message: 'getZonesGroupedByCountry no longer reads the host time zone and no longer collapses anything: ' +
+            'it returns one group per country, ordered by country name. A single-argument call used to mean ' +
+            '"the host country first, everything else under \'Other\'" — write that as ' +
+            "collapseOtherCountries(getZonesGroupedByCountry(zones), kbqResolveHostCountry(zones), 'Other'), " +
+            'or keep the per-country grouping and pass it through promoteCountry.'
+    },
+    {
+        anchor: TIMEZONE_TYPE,
+        pattern: '\\btimezonesSortComparator\\b',
+        message: 'timezonesSortComparator returns the difference of the two offsets now — it used to return the ' +
+            "first zone's offset, which is not a valid comparator, so a list of more than a couple of zones " +
+            "came out in an order the engine's sort happened to produce. Ties break on city instead of on " +
+            'countryName, and a zone whose offset cannot be resolved sorts last instead of as UTC.'
+    },
+    {
+        anchor: TIMEZONE_TYPE,
+        pattern: '\\.\\s*countryCode\\b',
+        message: 'KbqTimezoneGroup.countryCode is `string | null`. The bucket collapseOtherCountries produces ' +
+            'spans several countries and says so with null, instead of borrowing the code of an arbitrary ' +
+            'member the way the old aggregate group did.'
+    },
+    {
+        anchor: TIMEZONE_TYPE,
+        pattern: '\\.\\s*offset\\b',
+        message: 'KbqTimezoneZone.offset is optional. Omit it and the offset is resolved from the IANA id every ' +
+            'time the option renders, so a zone that observes DST is labelled correctly on both sides of the ' +
+            'change; a string supplied there is still rendered verbatim and never recomputed. Read it with ' +
+            'resolveZoneOffset(zone) rather than directly.'
+    },
+    {
+        anchor: TIMEZONE_TYPE,
+        pattern: '<kbq-timezone-select\\b[^>]*\\bmulti(?:ple|line)\\b|\\.\\s*multiple\\s*=(?!=)',
+        message: 'kbq-timezone-select rejects multiple selection with an error instead of accepting it and ' +
+            'rendering a trigger that shows one of the selected values — through multiple and through ' +
+            'multiline alike, since multiline turns on multiple selection as well. An assignment to multiple ' +
+            'no longer compiles: it is a signal input now, set through the template. Use kbq-select for ' +
+            'multiple selection.'
+    }
+];
+/** Printed once per project, after the per-file reports. */
+const SUMMARY = [
+    '  The two grouping helpers are pure: getZonesGroupedByCountry, promoteCountry and ' +
+        'collapseOtherCountries produce the same output on any machine, and kbqResolveHostCountry is the ' +
+        'one place that reads Intl. That is what makes a server-rendered list match the one the browser ' +
+        'computes on hydration.',
+    '  The option tooltip carries the same filtered city list the option renders, so a search no longer ' +
+        'opens a hint listing the cities it has just filtered out.',
+    '  UtcOffsetPipe and CitiesByFilterPipe are exported, and KbqTimezoneModule re-exports KbqOptionModule, ' +
+        'so the documented usage with kbq-optgroup works from the module alone.',
+    '  filterCitiesBySearchString rejoins on ", " instead of ",", so a filtered list no longer starts with ' +
+        'a stray space. Its offset guard recognizes an offset still being typed (+, +03:, 0330) and keeps ' +
+        'the city list whole for it, but a lone hyphen-minus is searched for, so Baden-Baden can be found.',
+    '  Typing letters in the select moves to the option whose city starts with them. Typeahead used to ' +
+        'match the whole line, which opens with UTC, so it never reached past the first option.',
+    '  The overlay pane carries kbq-select-overlay, as it does for kbq-select.'
+];
+
+exports.SUMMARY = SUMMARY;
+exports.TIMEZONE_PACKAGE = TIMEZONE_PACKAGE;
+exports.TIMEZONE_TYPE = TIMEZONE_TYPE;
+exports.warnPatterns = warnPatterns;

package/schematics/migrations/timezone-grouping-utils/index.cjs

@@ -0,0 +1,65 @@
+'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_timezoneGroupingUtils_data = require('./data.cjs');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+const LABEL = '[timezone-grouping-utils]';
+const EXTENSIONS = ['.ts', '.html'];
+// Compiled once rather than per file. None carries the `g` flag, so a shared instance holds no `lastIndex`.
+const TIMEZONE_TYPE_REGEX = new RegExp(migrations_timezoneGroupingUtils_data.TIMEZONE_TYPE);
+const COMPILED_WARN_PATTERNS = migrations_timezoneGroupingUtils_data.warnPatterns.map(({ anchor, pattern, message }) => ({
+    anchor: new RegExp(anchor),
+    pattern: new RegExp(pattern),
+    message
+}));
+/** A file is a timezone consumer if it imports the package, names a member, or renders one of its elements. */
+function referencesTimezone(content) {
+    return content.includes(migrations_timezoneGroupingUtils_data.TIMEZONE_PACKAGE) || TIMEZONE_TYPE_REGEX.test(content);
+}
+/**
+ * Reports the timezone call sites the review's split of `getZonesGroupedByCountry` breaks, plus the members
+ * whose type or behaviour changed under them. Never writes: what replaces a dropped argument is a
+ * composition of two or three helpers, and which one the call site meant cannot be read off the call.
+ *
+ * `.html` is visited as well as `.ts`, because `[multiple]` is a template binding that used to be accepted.
+ */
+function timezoneGroupingUtils(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 || !referencesTimezone(content))
+                return;
+            consumers++;
+            for (const { anchor, pattern, message } of COMPILED_WARN_PATTERNS) {
+                if (!anchor.test(content) || !pattern.test(content))
+                    continue;
+                reported++;
+                utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${message}`]);
+            }
+        });
+        // Nothing here renders or builds a timezone list, so the summary would only be noise.
+        if (consumers === 0)
+            return;
+        utils_messages.logMessage(context.logger, [
+            `${LABEL} processed the timezone utilities under "${root || '<workspace root>'}", ` +
+                `${consumers} file(s) reference the package, ${reported} call site(s) reported.`,
+            ...migrations_timezoneGroupingUtils_data.SUMMARY
+        ]);
+    };
+}
+
+exports.default = timezoneGroupingUtils;

package/schematics/migrations/timezone-grouping-utils/schema.json

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

@@ -0,0 +1,49 @@
+# title-encapsulation
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21`
+(registered for `21.0.0-0`). Reports the members of `KbqTitleDirective` that stopped being public in
+the title review. It never writes to the tree.
+
+## Background
+
+`kbq-title` measures its host and opens a tooltip when the text is truncated. The review kept that
+surface — the `kbq-title` input and the tooltip it opens — and closed everything else, because the
+rest was the measurement machinery:
+
+| Member                                                                                                 | Before           | After                   |
+| ------------------------------------------------------------------------------------------------------ | ---------------- | ----------------------- |
+| `resizeStream`                                                                                         | `Subject<Event>` | removed                 |
+| `hasOnlyText`                                                                                          | public getter    | `private`               |
+| `ngOnDestroy`                                                                                          | declared         | removed, no `OnDestroy` |
+| `child`, `parent`, `isHorizontalOverflown`, `isVerticalOverflown`, `handleElementEnter`, `hideTooltip` | public           | `protected`             |
+
+`resizeStream` is the only one that changes how the directive works rather than only what it exposes. It was
+fed by a `(window:resize)` host listener, so one directive instance meant one listener — a dropdown
+with hundreds of options meant hundreds. The directive now injects the CDK `SharedResizeObserver`,
+which adds no per-instance listener and, unlike `window:resize`, also reacts to container-only
+resizes. A consumer that pushed into `resizeStream` to force a re-measure can drop the call.
+
+## What it does _not_ do
+
+Nothing is rewritten. Every member is either gone or hidden, so there is no expression to migrate a
+call site to — what a consumer should do instead depends on why it reached in.
+
+| Pattern                                                                         | Manual migration                                                  |
+| ------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| `.resizeStream`                                                                 | Drop the call; the shared `ResizeObserver` re-measures on its own |
+| `.hasOnlyText`                                                                  | Read the rendered DOM directly if it is genuinely needed          |
+| `.child` / `.parent` / `.is*Overflown` / `.handleElementEnter` / `.hideTooltip` | Use the `kbq-title` input; these are measurement internals        |
+| `super.ngOnDestroy()` in a subclass                                             | Remove it — the base tears down through `takeUntilDestroyed`      |
+
+## Notes with no call site to point at
+
+- The tooltip now opens on keyboard focus, which the class JSDoc and the published guide already
+  described. A host that compensated for its absence can drop the workaround.
+- `titleContent` is typed `TemplateRef<unknown>` instead of `TemplateRef<any>`. A `TemplateRef<Ctx>`
+  still assigns to it; a value read back out needs a cast.
+
+## Running it manually
+
+```
+ng generate @koobiq/components:title-encapsulation --project my-app
+```

package/schematics/migrations/title-encapsulation/data.cjs

@@ -0,0 +1,69 @@
+'use strict';
+
+/**
+ * Data for the `title-encapsulation` migration.
+ *
+ * The title review narrowed what `KbqTitleDirective` publishes. Nothing was renamed, so no call site
+ * has a mechanical replacement — the members are either gone or no longer reachable from outside:
+ *
+ * - `resizeStream` — a public `Subject<Event>` fed by a `(window:resize)` host listener. The directive
+ *   now injects the CDK `SharedResizeObserver` and re-measures on container resizes by itself, so
+ *   there is nothing left to push into.
+ * - `hasOnlyText` — public getter → `private`.
+ * - `ngOnDestroy` — no longer declared; teardown runs through `takeUntilDestroyed`, and the directive
+ *   no longer implements `OnDestroy`.
+ * - `child`, `parent`, `isHorizontalOverflown`, `isVerticalOverflown`, `handleElementEnter`,
+ *   `hideTooltip` — public → `protected`. `child` additionally returns `HTMLElement | undefined`.
+ *
+ * Warn-only. A consumer that reached for any of these was reaching into the measurement internals,
+ * and what it should do instead depends on why — there is no expression to rewrite it to.
+ */
+/** Import specifier that marks a file as a title consumer. */
+const TITLE_PACKAGE = '@koobiq/components/title';
+/** Identifier shape that marks a consumer without an import (e.g. a re-export or a subclass). */
+const TITLE_TYPE = '\\bKbqTitleDirective\\b';
+const SUBCLASS_ANCHOR = 'extends\\s+KbqTitleDirective\\b';
+const warnPatterns = [
+    {
+        anchor: TITLE_TYPE,
+        pattern: '\\.\\s*resizeStream\\b',
+        message: 'KbqTitleDirective.resizeStream was removed. It was a Subject fed by a (window:resize) host ' +
+            'listener; the directive now injects the CDK SharedResizeObserver and re-measures on container ' +
+            'resizes on its own, so a manual `resizeStream.next(event)` has no counterpart and is no longer ' +
+            'needed. Drop the call.'
+    },
+    {
+        anchor: TITLE_TYPE,
+        pattern: '\\.\\s*hasOnlyText\\b',
+        message: 'KbqTitleDirective.hasOnlyText is private. It reported whether the host holds a single text node, ' +
+            'which is a detail of the overflow measurement — read the rendered DOM directly if a consumer ' +
+            'genuinely needs it.'
+    },
+    {
+        anchor: TITLE_TYPE,
+        pattern: '\\.\\s*(?:child|parent|isHorizontalOverflown|isVerticalOverflown|handleElementEnter|hideTooltip)\\b',
+        message: 'KbqTitleDirective.child / parent / isHorizontalOverflown / isVerticalOverflown / ' +
+            'handleElementEnter / hideTooltip are protected. They are the measurement internals; the ' +
+            'supported surface is the `kbq-title` input and the tooltip the directive opens by itself. ' +
+            '`child` additionally returns `HTMLElement | undefined` now.'
+    },
+    {
+        anchor: SUBCLASS_ANCHOR,
+        pattern: 'super\\s*\\.\\s*ngOnDestroy\\s*\\(',
+        message: 'KbqTitleDirective no longer declares ngOnDestroy — it tears down through takeUntilDestroyed and ' +
+            'no longer implements OnDestroy, so `super.ngOnDestroy()` from a subclass no longer resolves. ' +
+            'Remove the call; the base teardown runs on its own.'
+    }
+];
+/** Printed once per project, after the per-file reports. */
+const SUMMARY = [
+    '  The tooltip now opens on keyboard focus as the guide always claimed, so a host that compensated ' +
+        'for its absence — its own focus listener calling show(), or a duplicate hint — can be removed.',
+    '  `titleContent` is typed TemplateRef<unknown> instead of TemplateRef<any>; a TemplateRef<SomeCtx> ' +
+        'still assigns, but a value read back out needs a cast.'
+];
+
+exports.SUMMARY = SUMMARY;
+exports.TITLE_PACKAGE = TITLE_PACKAGE;
+exports.TITLE_TYPE = TITLE_TYPE;
+exports.warnPatterns = warnPatterns;

package/schematics/migrations/title-encapsulation/index.cjs

@@ -0,0 +1,58 @@
+'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_titleEncapsulation_data = require('./data.cjs');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+const LABEL = '[title-encapsulation]';
+const EXTENSIONS = ['.ts'];
+/** A file is a title consumer if it imports the package or names the directive. */
+function referencesTitle(content) {
+    return content.includes(migrations_titleEncapsulation_data.TITLE_PACKAGE) || new RegExp(migrations_titleEncapsulation_data.TITLE_TYPE).test(content);
+}
+/**
+ * Reports the members of `KbqTitleDirective` that stopped being public. Never writes: every one of
+ * them was removed or hidden outright, so there is no expression to rewrite a call site to.
+ *
+ * Only `.ts` is visited. The directive's template surface — the `kbq-title` attribute — did not
+ * change, so no markup needs migrating.
+ */
+function titleEncapsulation(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 || !referencesTitle(content))
+                return;
+            consumers++;
+            for (const { anchor, pattern, message } of migrations_titleEncapsulation_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 uses kbq-title, so the summary would only be noise.
+        if (consumers === 0)
+            return;
+        utils_messages.logMessage(context.logger, [
+            `${LABEL} processed kbq-title under "${root || '<workspace root>'}", ` +
+                `${consumers} file(s) reference the directive, ${reported} call site(s) reported.`,
+            ...migrations_titleEncapsulation_data.SUMMARY
+        ]);
+    };
+}
+
+exports.default = titleEncapsulation;

package/schematics/migrations/title-encapsulation/schema.json

@@ -0,0 +1,15 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-title-encapsulation",
+    "title": "Koobiq components title 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/toast-stack-and-defaults/README.md

@@ -0,0 +1,102 @@
+# toast-stack-and-defaults
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21`
+(registered for `21.0.0-0`). Reports the breaking parts of the toast review.
+
+This schematic is report-only: it never writes a file. Every change below needs
+a decision a schematic cannot make for you.
+
+## Background
+
+`KbqToastComponent` used to hold `readonly service = inject(KbqToastService)`
+and reach the whole service through it. It now resolves only the narrow
+`KbqToastStack` contract it actually consumes, through the new
+`KBQ_TOAST_STACK` token, which both `KbqToastService` and
+`KbqToastContainerComponent` provide.
+
+## Breaking changes
+
+**`KbqToastComponent.service` is gone**, and so are the members that only
+existed for the old rendering path: `elementRef`, `ttl`, `delay`,
+`isTemplateRef()`, `themePalette` and `toastStyle`. Everything the template
+renders — `style`, `icon`, `role`, `closeButton` and the resolved slot templates
+— became `protected`. `data`, `id`, `hovered`, `focused` and `close()` are
+still public.
+
+A subclass registered through `KBQ_TOAST_FACTORY` is the documented extension
+point, so it is the code most likely to break:
+
+```ts
+// Before
+class MyToast extends KbqToastComponent {
+    ok() {
+        this.service.hide(this.id);
+    }
+}
+
+// After
+class MyToast extends KbqToastComponent {
+    ok() {
+        this.close();
+    }
+}
+```
+
+Anything the stack contract does not cover is reached by injecting it directly:
+
+```ts
+class MyToast extends KbqToastComponent {
+    private readonly stack = inject(KBQ_TOAST_STACK);
+    private readonly host = inject<ElementRef<HTMLElement>>(ElementRef);
+}
+```
+
+The countdown moved into the service, so there is no per-instance `ttl` or
+`delay` to read or write any more — pass the lifetime as the `duration`
+argument of `show()`.
+
+**`KbqToastService.animation` was removed** with `@angular/animations`: a toast
+plays its exit animation before it is taken out, and the overlay detaches once
+the last exit has ended.
+
+**`showTemplate()` and `templates` return
+`EmbeddedViewRef<KbqToastTemplateContext>`**, whose `$implicit` is the
+`KbqToastData` — not the toast component. Only annotations of the returned ref
+need adjusting; the value has always been the embedded view.
+
+**A `KBQ_TOAST_FACTORY` component that does not extend `KbqToastComponent`** is
+rejected: `show()` reads the numeric `id` the service keys its stack by, and
+throws when it is missing instead of stacking a toast it can never dismiss.
+
+## Behaviour changes
+
+**The data you pass in is no longer written to.** `show()` used to default
+`style` to `contrast` and `icon` to `true` by assigning them onto the caller's
+object; both defaults are resolved inside the toast now. Anything that read
+those keys back after `show()` — or rendered the same object somewhere else,
+which is what `kbq-notification-center` does — has to apply its own defaults.
+
+**Auto-dismissal pauses while a toast is hovered or holds the focus.** The
+whole stack shares one heartbeat, which stops while the stack is empty. A toast
+shown through `showTemplate()` carries no such listeners and is not paused.
+
+**Every toast is a live region:** `role="alert"` for the error and warning
+styles, `role="status"` otherwise. The stack itself is a labelled
+`role="region"` whose name comes from the new `toastRegion` key of the `a11y`
+section of the locale data.
+
+**Focus is handed on only for a keyboard dismissal** — to the next toast, or
+back to the element that held it when the toast appeared. A mouse dismissal
+leaves the focus where the browser put it.
+
+## Running the migration
+
+```bash
+ng update @koobiq/components@21
+```
+
+Or manually:
+
+```bash
+ng g @koobiq/components:toast-stack-and-defaults --project "<your project>"
+```