@koobiq/components 20.4.2 → 21.0.0

package/schematics/migrations/toast-stack-and-defaults/data.js

@@ -0,0 +1,79 @@
+'use strict';
+
+/**
+ * Warning data for the toast review.
+ *
+ * `KbqToastComponent` stopped depending on the concrete `KbqToastService` and resolves its stack through
+ * the new `KBQ_TOAST_STACK` token instead, which removed `service` together with the members a subclass
+ * used to reach through it. Everything the template renders became `protected`, `KbqToastService.animation`
+ * was removed with `@angular/animations`, and `showTemplate` / `templates` now carry the template context type
+ * instead of the toast component type.
+ *
+ * None of it can be rewritten mechanically — a subclass has to be rewired by hand — so every pattern below
+ * reports and nothing is auto-fixed.
+ */
+/** Warnings for `.ts` files. */
+const tsWarnPatterns = [
+    {
+        pattern: 'extends\\s+KbqToastComponent\\b',
+        message: 'KbqToastComponent no longer exposes `service`, `elementRef`, `ttl`, `delay`, `isTemplateRef()`, ' +
+            '`themePalette` or `toastStyle`, and everything the template renders is now protected. A subclass ' +
+            'that dismissed itself through `this.service.hide(this.id)` should call `this.close()`, or inject ' +
+            'the stack itself: `private readonly stack = inject(KBQ_TOAST_STACK)`. Use `inject(ElementRef)` for ' +
+            'the host element, and read the remaining lifetime from your own state — the countdown lives in the ' +
+            'service now. Manual migration required.'
+    },
+    {
+        pattern: 'KBQ_TOAST_FACTORY',
+        message: 'A component provided through KBQ_TOAST_FACTORY must extend KbqToastComponent: the service reads ' +
+            'its numeric `id` and now throws when it is missing instead of stacking an unusable toast. The ' +
+            'component also resolves KBQ_TOAST_STACK, which KbqToastService and KbqToastContainerComponent ' +
+            'both provide — nothing has to be wired up by hand.'
+    },
+    {
+        pattern: '\\banimation\\s*\\.\\s*(?:getValue\\s*\\(|value\\b)',
+        message: '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. Drop the read.'
+    },
+    {
+        pattern: '\\.instance\\s*\\.\\s*(?:ttl|delay|toastStyle|themePalette|isTemplateRef|elementRef|service)\\b',
+        message: 'This member was removed from KbqToastComponent, so reads through `KbqToastService.toasts[i].instance` ' +
+            'no longer compile. The lifetime of a toast is owned by the service — pass it as the `duration` ' +
+            'argument of `show()` — and the host element is available as `toasts[i].location.nativeElement`.'
+    },
+    {
+        pattern: '\\bshowTemplate\\s*\\(',
+        message: 'showTemplate() and the `templates` getter return EmbeddedViewRef<KbqToastTemplateContext> now, not ' +
+            'an EmbeddedViewRef of the toast component: the context of a template shown this way carries the ' +
+            'KbqToastData as `$implicit`. Adjust the type argument wherever the returned ref is annotated.'
+    }
+];
+/** Warnings for `.html` files and inline templates. */
+const templateWarnPatterns = [
+    {
+        pattern: '<kbq-toast\\b(?!-)',
+        message: 'Everything KbqToastComponent renders — `style`, `icon`, `role`, `closeButton` and the resolved slot ' +
+            'templates — became protected, so a template reference variable on <kbq-toast> can no longer read ' +
+            'them. `data`, `id`, `hovered`, `focused` and `close()` are still public.'
+    }
+];
+/** Behaviour note printed once per run — the parts no call site can point at. */
+const BEHAVIOUR_NOTE = [
+    'Toast behaviour changed:',
+    '  - The data passed to show() / showTemplate() is no longer written to. `style` used to be defaulted to',
+    '    "contrast" and `icon` to true on the caller\'s object; both defaults are now resolved inside the toast.',
+    '    Anything that read those keys back after show() — or rendered the same object somewhere else, the way',
+    '    kbq-notification-center does — has to apply its own defaults.',
+    '  - Auto-dismissal is paused while a toast is hovered or holds the focus, and the countdown of the whole',
+    '    stack is driven by one heartbeat that 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.',
+    '  - Dismissing a toast with the keyboard hands the focus on 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.'
+];
+
+exports.BEHAVIOUR_NOTE = BEHAVIOUR_NOTE;
+exports.templateWarnPatterns = templateWarnPatterns;
+exports.tsWarnPatterns = tsWarnPatterns;

package/schematics/migrations/toast-stack-and-defaults/index.js

@@ -0,0 +1,53 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var utils_messages = require('../../utils/messages.js');
+var utils_packageConfig = require('../../package-config-BhU2TfC8.js');
+var migrations_toastStackAndDefaults_data = require('./data.js');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+const TS_EXT = '.ts';
+const HTML_EXT = '.html';
+const LABEL = '[toast-stack-and-defaults]';
+function pickWarnPatterns(filePath) {
+    // A .ts file can hold an inline template, so it is checked against both sets.
+    return filePath.endsWith(TS_EXT) ? [...migrations_toastStackAndDefaults_data.tsWarnPatterns, ...migrations_toastStackAndDefaults_data.templateWarnPatterns] : migrations_toastStackAndDefaults_data.templateWarnPatterns;
+}
+function isMigratableFile(filePath) {
+    return filePath.endsWith(TS_EXT) || filePath.endsWith(HTML_EXT);
+}
+function toastStackAndDefaults(options) {
+    return async (tree, context) => {
+        const projectDefinition = await utils_packageConfig.setupOptions(options.project, tree);
+        const root = projectDefinition?.root ?? '';
+        const rootDir = root ? tree.getDir(root) : tree.root;
+        const filePaths = [];
+        utils_packageConfig.visitProjectFiles(rootDir, (filePath) => {
+            if (!isMigratableFile(filePath))
+                return;
+            filePaths.push(filePath);
+        });
+        let reported = 0;
+        for (const filePath of filePaths) {
+            const content = tree.read(filePath)?.toString();
+            if (!content)
+                continue;
+            for (const { pattern, message } of pickWarnPatterns(filePath)) {
+                if (!new RegExp(pattern).test(content))
+                    continue;
+                utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${message}`]);
+                reported++;
+            }
+        }
+        utils_messages.logMessage(context.logger, [
+            `${LABEL} scanned the tree under "${root || '<workspace root>'}", reported ${reported} usage(s). ` +
+                'Nothing was rewritten — every change below needs a decision no schematic can make.',
+            '',
+            ...migrations_toastStackAndDefaults_data.BEHAVIOUR_NOTE
+        ]);
+    };
+}
+
+exports.default = toastStackAndDefaults;

package/schematics/migrations/toast-stack-and-defaults/schema.json

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

package/schematics/migrations/tooltip-pointer-events-and-types/README.md

@@ -0,0 +1,53 @@
+# tooltip-pointer-events-and-types
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21`
+(registered for `21.0.0-0`). Reports the one tooltip change that reaches consumers with no code to
+point at, plus the narrowed types that surface as compile errors and the deprecated open-time tokens.
+It never writes to the tree.
+
+## Background
+
+`ignoreTooltipPointerEvents` used to default to `true`, which made every tooltip pane transparent to
+the pointer. That fails WCAG 1.4.13 _hoverable_: a hint that takes a while to read cannot be reached,
+and a user reading at high magnification, whose pointer often ends up over the pane, loses it. The
+default is now `false`.
+
+The flip is silent. Markup that never mentioned the input compiles unchanged and behaves
+differently — the pane now captures clicks meant for whatever it floats over. That is why this
+migration reports the _absence_ of the input rather than its presence: a file that renders
+`kbqTooltip` and never writes `ignoreTooltipPointerEvents` is exactly the file whose behaviour
+changed.
+
+Already opted out, so nothing to do for them: the built-in overflow hints (`kbq-title`,
+`kbqEllipsisCenter`, the option and timezone hints) and any tooltip whose `kbqTrigger` is `manual` or
+`none` — hovering such a pane neither opens nor closes it, so there is nothing hoverable to protect.
+
+## What it does _not_ do
+
+Nothing is rewritten. The markup whose behaviour changed is the markup that says nothing about the
+input, and there is no way to tell from a template whether a given tooltip floats over a click
+target.
+
+| Pattern                                                    | Manual migration                                                                                                 |
+| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `kbqTooltip` with no `ignoreTooltipPointerEvents`          | Add `[ignoreTooltipPointerEvents]="true"` where a pane overlays a click target                                   |
+| `.scheduler`                                               | Removed; schedule on a scheduler you own                                                                         |
+| `getMouseLeaveListener(delay)`                             | Drop the argument — the listener reads the trigger's own `leaveDelay`                                            |
+| `placementChange`                                          | Handler takes `KbqPopUpPlacementValues`, not `string`                                                            |
+| `.content` / `.header` / `.context` / `.modifier`          | `unknown` and the real enum replaced `any`; a value read out needs a cast                                        |
+| `KBQ_TOOLTIP_OPEN_TIME` / `KBQ_TOOLTIP_OPEN_TIME_PROVIDER` | Deprecated no-ops, removed in 22.0.0: use `KBQ_TOOLTIP_INSTANT_SHOW_WINDOW` and `KbqTooltipDelayTracker.reset()` |
+
+## Notes with no call site to point at
+
+- The pane carries `role="tooltip"` and the trigger points `aria-describedby` at it. A host that
+  added either by hand can drop it.
+- Escape closes a hover tooltip on a non-focusable element, which previously only worked while the
+  trigger itself had focus.
+- `KbqTooltipTrigger` can be imported standalone — `KBQ_TOOLTIP_SCROLL_STRATEGY` has a factory
+  default, so the NgModule is no longer load-bearing.
+
+## Running it manually
+
+```
+ng generate @koobiq/components:tooltip-pointer-events-and-types --project my-app
+```

package/schematics/migrations/tooltip-pointer-events-and-types/data.js

@@ -0,0 +1,89 @@
+'use strict';
+
+/**
+ * Data for the `tooltip-pointer-events-and-types` migration.
+ *
+ * The tooltip review made one change that reaches consumers without any code to point at, and a set
+ * of type narrowings that surface as compile errors:
+ *
+ * - `ignoreTooltipPointerEvents` defaults to `false` instead of `true`. The pane is hoverable now, so
+ *   the pointer can reach it — WCAG 1.4.13 *hoverable* — which also means it captures clicks meant
+ *   for whatever it floats over. Nothing in the markup changes, so nothing can be rewritten and
+ *   nothing warns on its own: the only handle is "this file renders tooltips and never opts out".
+ * - `KbqPopUpTrigger.scheduler` — removed.
+ * - `KbqPopUpTrigger.getMouseLeaveListener()` — took an optional delay, now takes nothing.
+ * - `placementChange` — `EventEmitter<string>` → `EventEmitter<KbqPopUpPlacementValues>`.
+ * - `content`, `header`, `context`, `modifier` — the `any` in their types became `unknown` or the
+ *   real enum.
+ * - `KBQ_TOOLTIP_OPEN_TIME` / `KBQ_TOOLTIP_OPEN_TIME_PROVIDER` — deprecated no-ops, removed in 22.0.0.
+ *
+ * Warn-only. A narrowed type is fixed by giving the call site the right type, which cannot be derived
+ * from the assignment, and the default flip has no call site at all.
+ */
+/** Import specifiers that mark a file as a tooltip consumer. */
+const TOOLTIP_PACKAGE = '@koobiq/components/tooltip';
+/** Identifier and attribute shapes that mark a consumer without an import. */
+const TOOLTIP_TYPE = '\\bKbqTooltipTrigger\\b|\\bkbqTooltip\\b';
+const POP_UP_ANCHOR = '\\bKbqPopUpTrigger\\b|\\bKbqTooltipTrigger\\b|\\bKbqPopoverTrigger\\b';
+const warnPatterns = [
+    {
+        anchor: '\\bkbqTooltip\\b',
+        pattern: '\\bkbqTooltip\\b',
+        unless: '\\bignoreTooltipPointerEvents\\b',
+        message: 'Tooltip panes take pointer events now: ignoreTooltipPointerEvents defaults to false instead of ' +
+            'true, so the pointer can reach the pane (WCAG 1.4.13 "Content on Hover or Focus") and the pane ' +
+            'also captures clicks meant for whatever it floats over. Nothing in this file opts out. Add ' +
+            '[ignoreTooltipPointerEvents]="true" to any tooltip that overlays another click target. The ' +
+            'built-in overflow hints (kbq-title, kbqEllipsisCenter, option and timezone hints) already opt ' +
+            'out, and so does any tooltip whose kbqTrigger is manual or none.'
+    },
+    {
+        anchor: POP_UP_ANCHOR,
+        pattern: '\\.\\s*scheduler\\b',
+        message: 'KbqPopUpTrigger.scheduler was removed. It exposed the RxJS AsyncScheduler the trigger used for ' +
+            'its own delays; schedule your own work on a scheduler you own.'
+    },
+    {
+        anchor: POP_UP_ANCHOR,
+        pattern: 'getMouseLeaveListener\\s*\\(\\s*[^)\\s]',
+        message: 'KbqPopUpTrigger.getMouseLeaveListener() no longer takes a delay — the listener it returns reads ' +
+            "the trigger's own leaveDelay. Drop the argument."
+    },
+    {
+        anchor: POP_UP_ANCHOR,
+        pattern: '\\bplacementChange\\b',
+        message: 'placementChange emits KbqPopUpPlacementValues instead of string. Reading the payload is ' +
+            'unaffected — the values are strings; what breaks is code that emits into the stream or ' +
+            'overrides it with an EventEmitter<string>.'
+    },
+    {
+        anchor: TOOLTIP_TYPE,
+        pattern: '\\.\\s*(?:content|header|context|modifier)\\b',
+        message: 'The `any` left the tooltip inputs: content and header are `string | TemplateRef<unknown>`, ' +
+            'context is `unknown`, and modifier is KbqEnumValues<TooltipModifier>. Assigning still works; a ' +
+            'value read back out needs a cast, and a modifier written as a free-form string has to be one of ' +
+            'the enum members.'
+    },
+    {
+        anchor: '\\bKBQ_TOOLTIP_OPEN_TIME',
+        pattern: '\\bKBQ_TOOLTIP_OPEN_TIME(?:_PROVIDER)?\\b',
+        message: 'KBQ_TOOLTIP_OPEN_TIME and KBQ_TOOLTIP_OPEN_TIME_PROVIDER are deprecated and will be removed in ' +
+            '22.0.0. The tooltip no longer reads them, so providing or writing them has no effect. Set the ' +
+            'instant-show window with KBQ_TOOLTIP_INSTANT_SHOW_WINDOW, and call KbqTooltipDelayTracker.reset() ' +
+            'to make the next tooltip wait its full enter delay.'
+    }
+];
+/** Printed once per project, after the per-file reports. */
+const SUMMARY = [
+    '  The tooltip now carries role="tooltip" and the trigger points aria-describedby at it, so a host ' +
+        'that added either by hand can drop it.',
+    '  Escape closes a hover tooltip on a non-focusable element, which previously only worked while the ' +
+        'trigger itself had focus.',
+    '  KbqTooltipTrigger can be imported standalone: KBQ_TOOLTIP_SCROLL_STRATEGY has a factory default, ' +
+        'so the NgModule is no longer load-bearing.'
+];
+
+exports.SUMMARY = SUMMARY;
+exports.TOOLTIP_PACKAGE = TOOLTIP_PACKAGE;
+exports.TOOLTIP_TYPE = TOOLTIP_TYPE;
+exports.warnPatterns = warnPatterns;

package/schematics/migrations/tooltip-pointer-events-and-types/index.js

@@ -0,0 +1,60 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var utils_messages = require('../../utils/messages.js');
+var utils_packageConfig = require('../../package-config-BhU2TfC8.js');
+var migrations_tooltipPointerEventsAndTypes_data = require('./data.js');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+const LABEL = '[tooltip-pointer-events-and-types]';
+const EXTENSIONS = ['.ts', '.html'];
+/** A file is a tooltip consumer if it imports the package, names the trigger, or renders one. */
+function referencesTooltip(content) {
+    return content.includes(migrations_tooltipPointerEventsAndTypes_data.TOOLTIP_PACKAGE) || new RegExp(migrations_tooltipPointerEventsAndTypes_data.TOOLTIP_TYPE).test(content);
+}
+/**
+ * Reports the tooltip changes a consumer has to act on. Never writes: a narrowed type is fixed by
+ * giving the call site the right type, and the pointer-events default has no call site at all — the
+ * markup that changed behaviour is exactly the markup that did not mention the input.
+ *
+ * `.html` is visited as well as `.ts`, because the pointer-events report keys off the `kbqTooltip`
+ * attribute rather than off an import.
+ */
+function tooltipPointerEventsAndTypes(options) {
+    return async (tree, context) => {
+        const { project } = options;
+        const projectDefinition = await utils_packageConfig.setupOptions(project, tree);
+        const root = projectDefinition?.root ?? '';
+        const rootDir = root ? tree.getDir(root) : tree.root;
+        let consumers = 0;
+        let reported = 0;
+        utils_packageConfig.visitProjectFiles(rootDir, (filePath, entry) => {
+            if (!EXTENSIONS.some((extension) => filePath.endsWith(extension)))
+                return;
+            const content = entry?.content.toString();
+            if (!content || !referencesTooltip(content))
+                return;
+            consumers++;
+            for (const { anchor, pattern, unless, message } of migrations_tooltipPointerEventsAndTypes_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 tooltip, so the summary would only be noise.
+        if (consumers === 0)
+            return;
+        utils_messages.logMessage(context.logger, [
+            `${LABEL} processed kbqTooltip under "${root || '<workspace root>'}", ` +
+                `${consumers} file(s) reference the tooltip, ${reported} call site(s) reported.`,
+            ...migrations_tooltipPointerEventsAndTypes_data.SUMMARY
+        ]);
+    };
+}
+
+exports.default = tooltipPointerEventsAndTypes;

package/schematics/migrations/tooltip-pointer-events-and-types/schema.json

@@ -0,0 +1,15 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-tooltip-pointer-events-and-types",
+    "title": "Koobiq components tooltip 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/top-bar-container-selectors/README.md

@@ -0,0 +1,111 @@
+# top-bar-container-selectors
+
+Migration schematic invoked automatically by `ng update @koobiq/components@20`
+(registered for `21.0.0-0`). Renames the two placement classes of
+`[kbqTopBarContainer]` and the flex-basis token of the `start` container.
+
+## Background
+
+`[kbqTopBarContainer]` applied `kbq-top-bar-container__start` and
+`kbq-top-bar-container__end`. Both are **modifiers** of
+`.kbq-top-bar-container`, but they were spelled with the `__` element
+separator. The library spells modifiers with a single `_` — the component
+itself does so one line away, in `kbq-top-bar_with-shadow`.
+
+The `start` container was `flex: 1 0 var(--kbq-top-bar-container-start-basis)`.
+With `flex-shrink: 0` that basis was never a basis: it was the width the
+container could not fall below, so every caller that put content on the left had
+to invent a value for it. The container is `flex: 1 1 auto` now, and the floor
+is spelled `--kbq-top-bar-container-start-min-width`.
+
+## Behaviour change
+
+The `start` container **shrinks toward** the floor you set instead of being
+pinned at it. Previously an overflowing bar kept the start container at exactly
+its basis and made the end container absorb the whole overflow; now both give
+way, and the start container stops at
+`--kbq-top-bar-container-start-min-width` (default `0`).
+
+`kbq-top-bar` also moved off the CDK overlay layer: it carries
+`z-index: var(--kbq-top-bar-z-index)` (`990`) instead of `1000`. An override
+that raised something above the bar to break that tie is now redundant.
+
+`--kbq-top-bar-position` still defaults to `sticky` and still does nothing on
+its own. Set `--kbq-top-bar-inset-block-start: 0` to make the bar stick to the
+top of its scrolling ancestor.
+
+## What it does
+
+The schematic walks every `.ts`, `.html`, `.scss` and `.css` file in the project
+(skipping `node_modules` and `dist`) and only opens the ones that mention
+`kbq-top-bar`.
+
+| Auto-fix                                                                          | Where               |
+| --------------------------------------------------------------------------------- | ------------------- |
+| `kbq-top-bar-container__start` → `kbq-top-bar-container_start`                    | all four extensions |
+| `kbq-top-bar-container__end` → `kbq-top-bar-container_end`                        | all four extensions |
+| `--kbq-top-bar-container-start-basis` → `--kbq-top-bar-container-start-min-width` | all four extensions |
+
+The replacement is textual on purpose — a class name is as likely to live in a
+template string, a `styles` block or a `classList.add` call as in a
+stylesheet — but it is matched with word/selector-boundary guards, so a
+consumer's own longer identifier that merely starts with one of these strings
+(`kbq-top-bar-container__start-icon`, say) is left alone.
+
+## What it does _not_ do (warn-only)
+
+| Pattern                                 | Manual migration                                                                                                                                                                                                                                            |
+| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.kbq-top-bar-container[placement='…']` | Select the class the directive applies (`.kbq-top-bar-container_start` / `_end`). The attribute selector matches only the static `placement="start"` form; a `[placement]` property binding leaves no attribute behind and the rule silently stops applying |
+
+Warnings are checked against the **post-fix** content, so an auto-fixed usage
+does not also report as needing manual work.
+
+`fix` defaults to `true`. `ng update` invokes migrations with no options at all,
+so the rule applies that default itself rather than relying on the schema.
+
+[Params](schema.ts)
+
+Usage for Angular Cli:
+
+```shell
+ng g @koobiq/components:top-bar-container-selectors --project "<your project>"
+```
+
+Usage for Nx:
+
+```shell
+nx g @koobiq/components:top-bar-container-selectors --project "<your project>"
+```
+
+### Run locally
+
+Build package
+
+```shell
+yarn run build:schematics
+```
+
+Run command (for example, for `koobiq-docs` project)
+
+```shell
+ng g ./dist/components/schematics/collection.json:top-bar-container-selectors --project koobiq-docs
+```
+
+### Result
+
+#### Before
+
+```scss
+.kbq-top-bar-container__start {
+    --kbq-top-bar-container-start-basis: 160px;
+}
+```
+
+#### After
+
+```scss
+.kbq-top-bar-container_start {
+    --kbq-top-bar-container-start-min-width: 160px;
+}
+```

package/schematics/migrations/top-bar-container-selectors/data.js

@@ -0,0 +1,56 @@
+'use strict';
+
+/**
+ * Data for the `top-bar-container-selectors` migration.
+ *
+ * The top-bar review renamed the two placement classes of `[kbqTopBarContainer]` and replaced the
+ * flex-basis token of the `start` container:
+ *
+ * - `kbq-top-bar-container__start` / `__end` are modifiers of `.kbq-top-bar-container`, but were
+ *   written with the `__` element separator. The repo spells modifiers with a single `_`, which the
+ *   component already did one line away in `kbq-top-bar_with-shadow`.
+ * - `--kbq-top-bar-container-start-basis` fed `flex: 1 0 <basis>`. With `flex-shrink: 0` the basis was
+ *   never a basis: it was the width the container could not fall below. The container is
+ *   `flex: 1 1 auto` now and the floor is spelled `--kbq-top-bar-container-start-min-width`.
+ *
+ * Both are plain, library-owned strings, so they are rewritten rather than reported. The rename is
+ * matched with word/selector-boundary guards (see `index.ts`), so a consumer's own longer identifier
+ * that merely starts with one of these strings — `kbq-top-bar-container__start-icon`, say — is left
+ * alone.
+ */
+/** Rewritten in `.ts`, `.html`, `.scss` and `.css`. */
+const renames = [
+    { replace: 'kbq-top-bar-container__start', replaceWith: 'kbq-top-bar-container_start' },
+    { replace: 'kbq-top-bar-container__end', replaceWith: 'kbq-top-bar-container_end' },
+    {
+        replace: '--kbq-top-bar-container-start-basis',
+        replaceWith: '--kbq-top-bar-container-start-min-width'
+    }
+];
+/** Checked against the post-fix content, so an auto-fixed usage is not reported again. */
+const warnPatterns = [
+    {
+        // `(?![\w-])` after `placement` keeps this off `[placementVariant=...]` and `[placement-legacy]`,
+        // which share the prefix but are unrelated attributes.
+        pattern: /\.kbq-top-bar-container\s*\[\s*placement(?![\w-])/,
+        message: 'This rule selects the container by its `placement` attribute. That only matches the static ' +
+            'attribute form (placement="start"); a [placement]="\'start\'" property binding leaves no ' +
+            'attribute behind and the rule silently stops applying. Select the class the directive ' +
+            'applies instead: .kbq-top-bar-container_start / .kbq-top-bar-container_end.'
+    }
+];
+/** Printed once per run, after the per-file reports. */
+const SUMMARY = [
+    '  The start container is `flex: 1 1 auto` with `min-width: var(--kbq-top-bar-container-start-min-width)`',
+    '  instead of `flex: 1 0 <basis>`, so it now shrinks toward the floor you set rather than being pinned',
+    '  at it while the end container absorbs the whole overflow.',
+    '  kbq-top-bar carries `z-index: var(--kbq-top-bar-z-index)` (990) instead of the CDK overlay layer',
+    '  (1000). If your app raised something above the bar to work around that tie — the way a search modal',
+    '  or a floating panel would have had to — that override is now redundant.',
+    '  `--kbq-top-bar-position` still defaults to `sticky` and still does nothing on its own. Set',
+    '  `--kbq-top-bar-inset-block-start: 0` to make the bar stick to the top of its scrolling ancestor.'
+];
+
+exports.SUMMARY = SUMMARY;
+exports.renames = renames;
+exports.warnPatterns = warnPatterns;

package/schematics/migrations/top-bar-container-selectors/index.js

@@ -0,0 +1,84 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var utils_messages = require('../../utils/messages.js');
+var utils_packageConfig = require('../../package-config-BhU2TfC8.js');
+var migrations_topBarContainerSelectors_data = require('./data.js');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+const LABEL = '[top-bar-container-selectors]';
+const EXTENSIONS = ['.ts', '.html', '.scss', '.css'];
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Both renamed strings are library-owned, but a plain textual replacement isn't exact on its own: a
+ * consumer's own longer identifier can still start with one of them (`kbq-top-bar-container__start-icon`,
+ * say). `(?<![\w-])` / `(?![\w-])` keep the match from firing inside such an identifier, the same
+ * word/selector-boundary guard `buildIconTokenPatterns` in `../../utils/icon-migration.ts` uses. Compiled
+ * once here rather than per file, since a single run can visit thousands of them.
+ *
+ * The `[placement]` attribute selector is reported instead — rewriting it means knowing which of the two
+ * placements the rule meant, and the attribute may be there for something other than styling.
+ */
+const renamePatterns = migrations_topBarContainerSelectors_data.renames.map(({ replace, replaceWith }) => ({
+    pattern: new RegExp(`(?<![\\w-])${escapeRegExp(replace)}(?![\\w-])`, 'g'),
+    replace,
+    replaceWith
+}));
+function topBarContainerSelectors(options) {
+    return async (tree, context) => {
+        const { project, fix = true } = options;
+        const projectDefinition = await utils_packageConfig.setupOptions(project, tree);
+        const root = projectDefinition?.root ?? '';
+        const rootDir = root ? tree.getDir(root) : tree.root;
+        let renamed = 0;
+        let reported = 0;
+        utils_packageConfig.visitProjectFiles(rootDir, (filePath, entry) => {
+            if (!EXTENSIONS.some((extension) => filePath.endsWith(extension)))
+                return;
+            const content = entry?.content.toString();
+            if (!content || !content.includes('kbq-top-bar'))
+                return;
+            let updated = content;
+            const applied = [];
+            for (const { pattern, replace, replaceWith } of renamePatterns) {
+                pattern.lastIndex = 0;
+                if (!pattern.test(updated))
+                    continue;
+                applied.push(`${replace} -> ${replaceWith}`);
+                updated = updated.replace(pattern, replaceWith);
+            }
+            if (applied.length) {
+                renamed++;
+                const prefix = fix ? '' : 'would rename ';
+                if (fix)
+                    tree.overwrite(filePath, updated);
+                utils_messages.logMessage(context.logger, [
+                    `${LABEL} ${filePath}`,
+                    ...applied.map((line) => `  ${prefix}${line}`)
+                ]);
+            }
+            // Warnings run against what the file looks like after the renames, so an auto-fixed usage is
+            // not reported as manual work as well.
+            const checked = fix ? updated : content;
+            for (const { pattern, message } of migrations_topBarContainerSelectors_data.warnPatterns) {
+                if (!pattern.test(checked))
+                    continue;
+                reported++;
+                utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${message}`]);
+            }
+        });
+        if (renamed === 0 && reported === 0)
+            return;
+        utils_messages.logMessage(context.logger, [
+            `${LABEL} processed kbq-top-bar under "${root || '<workspace root>'}", ` +
+                `${renamed} file(s) renamed, ${reported} rule(s) reported.`,
+            ...migrations_topBarContainerSelectors_data.SUMMARY
+        ]);
+    };
+}
+
+exports.default = topBarContainerSelectors;

package/schematics/migrations/top-bar-container-selectors/schema.json

@@ -0,0 +1,20 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-top-bar-container-selectors",
+    "title": "Koobiq components top-bar container selectors 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 the renames. When false, prints what would change without writing."
+        }
+    }
+}