@koobiq/components 20.4.2 → 21.0.0

package/schematics/migrations/dl-standalone-names/README.md

@@ -0,0 +1,49 @@
+# dl-standalone-names
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21` (registered for
+`21.0.0-0`). Moves description list consumers to the names of its standalone components and off its
+NgModule where that is a drop-in change.
+
+## Background
+
+The description list review renamed its standalone components to the names the newer components use,
+and stopped documenting the NgModule that re-exports them:
+
+| Before           | After                     |
+| ---------------- | ------------------------- |
+| `KbqDlComponent` | `KbqDl`                   |
+| `KbqDtComponent` | `KbqDt`                   |
+| `KbqDdComponent` | `KbqDd`                   |
+| `KbqDlModule`    | `KbqDl`, `KbqDt`, `KbqDd` |
+
+The old names are deprecated aliases of the same classes until 22.0.0, and `KbqDlModule` still works,
+so nothing breaks before then.
+
+## What it rewrites
+
+Only what is imported from `@koobiq/components/dl`, read from the TypeScript AST:
+
+- the renamed classes in named, aliased, type-only and namespace imports, and every use of them - as a
+  value, as a type, in a query; an aliased import keeps its local name;
+- a re-export keeps the name it exports: `export { KbqDlComponent } from '@koobiq/components/dl'` becomes
+  `export { KbqDl as KbqDlComponent } from '@koobiq/components/dl'`, so the files that import it from the
+  barrel keep compiling;
+- `KbqDlModule` where it is an element of an array - `imports` and `exports` of a component or an
+  NgModule, a `TestBed` configuration, a shared constant - becomes `KbqDl, KbqDt, KbqDd`, without the ones
+  the array already holds, and the import follows.
+
+## What it does _not_ do
+
+- A `KbqDlModule` that is not an element of an array, such as `importProvidersFrom(KbqDlModule)`, is kept
+  and reported: only an array takes the three components in its place.
+- A file that reaches the old names through a barrel of the project is left alone; the barrel keeps
+  exporting them.
+- Templates are not visited: the selectors did not change.
+
+## Running it manually
+
+```
+ng generate @koobiq/components:dl-standalone-names --project my-app
+```
+
+Pass `--fix=false` to see what would change without writing files.

package/schematics/migrations/dl-standalone-names/data.js

@@ -0,0 +1,44 @@
+'use strict';
+
+/**
+ * Data for the `dl-standalone-names` migration.
+ *
+ * The description list review renamed its standalone components to the names the newer components use
+ * and stopped documenting the NgModule:
+ *
+ * - `KbqDlComponent`, `KbqDtComponent` and `KbqDdComponent` are `KbqDl`, `KbqDt` and `KbqDd`; the old
+ *   names stay as deprecated aliases of the same classes until 22.0.0
+ * - `KbqDlModule` still works, but the documentation imports the three components directly
+ *
+ * Rewrites what is imported from `@koobiq/components/dl`, and `KbqDlModule` where it is an element of an
+ * array - `imports`, `exports`, a `TestBed` configuration - since an array takes the three components
+ * just as well. Anywhere else the module is kept and reported.
+ */
+/** The entry point the migration rewrites the imports of. */
+const DL_PACKAGE = '@koobiq/components/dl';
+/** Each renamed class: its old name, a deprecated alias until 22.0.0, and its new one. */
+const RENAMES = {
+    KbqDlComponent: 'KbqDl',
+    KbqDtComponent: 'KbqDt',
+    KbqDdComponent: 'KbqDd'
+};
+/** The NgModule that re-exports the three components. */
+const DL_MODULE = 'KbqDlModule';
+/** What `KbqDlModule` re-exports, in the order an array lists them in its place. */
+const MODULE_COMPONENTS = ['KbqDl', 'KbqDt', 'KbqDd'];
+/** A `KbqDlModule` the migration leaves alone, because only an array element can take the three components. */
+const keptModuleMessage = (line) => `Line ${line}: KbqDlModule is kept - it is not an element of an array, so it cannot be replaced by ` +
+    'KbqDl, KbqDt and KbqDd in place. It still works, but is no longer documented: import the three ' +
+    'components where they are used.';
+const SUMMARY = [
+    '  KbqDlComponent, KbqDtComponent and KbqDdComponent were renamed to KbqDl, KbqDt and KbqDd. The old names are',
+    '  deprecated aliases of the same classes and will be removed in 22.0.0.',
+    '  KbqDlModule is no longer documented: where it is an element of an array, it is replaced by KbqDl, KbqDt and KbqDd.'
+];
+
+exports.DL_MODULE = DL_MODULE;
+exports.DL_PACKAGE = DL_PACKAGE;
+exports.MODULE_COMPONENTS = MODULE_COMPONENTS;
+exports.RENAMES = RENAMES;
+exports.SUMMARY = SUMMARY;
+exports.keptModuleMessage = keptModuleMessage;

package/schematics/migrations/dl-standalone-names/index.js

@@ -0,0 +1,321 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var ts = require('typescript');
+var utils_messages = require('../../utils/messages.js');
+var utils_packageConfig = require('../../package-config-BhU2TfC8.js');
+var replacementDriver = require('../../replacement-driver-8o5P9eyQ.js');
+var migrations_dlStandaloneNames_data = require('./data.js');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+require('../../list-item-pattern-D95Y1KIk.js');
+
+const LABEL = '[dl-standalone-names]';
+const TS_EXT = '.ts';
+const isEntryPoint = (node) => !!node && ts.isStringLiteral(node) && node.text === migrations_dlStandaloneNames_data.DL_PACKAGE;
+/** Read from the text: `ImportClause.isTypeOnly` is deprecated in favor of a member older TypeScript lacks. */
+const isTypeOnlyImport = (declaration) => /^type\b/.test(declaration.importClause?.getText() ?? '');
+/** The new name of a renamed class. Own keys only: `toString` is no rename. */
+const renameOf = (name) => (Object.hasOwn(migrations_dlStandaloneNames_data.RENAMES, name) ? migrations_dlStandaloneNames_data.RENAMES[name] : undefined);
+/**
+ * Whether an identifier refers to a binding rather than naming a member or a declaration: `KbqDlComponent`
+ * in `x.KbqDlComponent`, `ns.KbqDlComponent` as a type or `{ KbqDlComponent: 1 }` is not the import.
+ */
+function isReference(identifier) {
+    const { parent } = identifier;
+    if (ts.isPropertyAccessExpression(parent) || ts.isQualifiedName(parent)) {
+        return (ts.isPropertyAccessExpression(parent) ? parent.name : parent.right) !== identifier;
+    }
+    if (ts.isPropertyAssignment(parent) ||
+        ts.isPropertyDeclaration(parent) ||
+        ts.isMethodDeclaration(parent) ||
+        ts.isPropertySignature(parent) ||
+        ts.isMethodSignature(parent) ||
+        ts.isGetAccessorDeclaration(parent) ||
+        ts.isSetAccessorDeclaration(parent) ||
+        ts.isEnumMember(parent)) {
+        return parent.name !== identifier;
+    }
+    return true;
+}
+/**
+ * Renames the classes imported from `@koobiq/components/dl` and replaces `KbqDlModule` with the three
+ * components wherever it is an element of an array. Only what is imported from the entry point is touched:
+ * an unrelated `KbqDlComponent`, or one reached through a barrel of the project, is left alone, and a barrel
+ * that re-exports an old name keeps exporting it, now as an alias of the new class.
+ *
+ * Names are edited in place on the AST; imports are added and removed with the helpers the other migrations use.
+ */
+function migrateSource(content, fileName) {
+    const sourceFile = ts.createSourceFile(fileName, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const edits = [];
+    const keptModuleLines = [];
+    const imports = sourceFile.statements.filter((statement) => ts.isImportDeclaration(statement) && isEntryPoint(statement.moduleSpecifier));
+    const reExports = sourceFile.statements.filter((statement) => ts.isExportDeclaration(statement) && isEntryPoint(statement.moduleSpecifier));
+    /** Local name → what it imports, for every named import of the entry point. */
+    const bindings = new Map();
+    const namespaces = new Set();
+    for (const declaration of imports) {
+        const named = declaration.importClause?.namedBindings;
+        if (!named)
+            continue;
+        if (ts.isNamespaceImport(named)) {
+            namespaces.add(named.name.text);
+            continue;
+        }
+        for (const element of named.elements) {
+            bindings.set(element.name.text, {
+                imported: (element.propertyName ?? element.name).text,
+                typeOnly: element.isTypeOnly || isTypeOnlyImport(declaration)
+            });
+        }
+    }
+    if (!bindings.size && !namespaces.size && !reExports.length)
+        return { content, changed: false, keptModuleLines };
+    /** The local name of an import of `name`, an unaliased one first; with `valueOnly`, not a type-only one. */
+    const localOf = (name, valueOnly = false) => {
+        const locals = [...bindings]
+            .filter(([, binding]) => binding.imported === name && !(valueOnly && binding.typeOnly))
+            .map(([local]) => local);
+        return locals.find((local) => local === name) ?? locals[0];
+    };
+    /** Old local name → the local name its references take. */
+    const referenceRenames = new Map();
+    /** The old imports renamed in place: their specifier becomes the new name. */
+    const renamedInPlace = new Set();
+    /** The old imports that go: the new class is imported already, or is about to be. */
+    const droppedOld = new Set();
+    /** The classes to import as values, which nothing imports that way yet. */
+    const missing = new Set();
+    for (const [local, { imported, typeOnly }] of bindings) {
+        const target = renameOf(imported);
+        if (local !== imported || !target)
+            continue;
+        // A value use needs a value import of the new class; a type use takes either.
+        const existing = localOf(target, !typeOnly);
+        if (existing) {
+            referenceRenames.set(local, existing);
+            droppedOld.add(local);
+        }
+        else if (localOf(target) === target) {
+            // Imported type-only under the same name: renaming in place would bind it twice, so it is made a value.
+            referenceRenames.set(local, target);
+            droppedOld.add(local);
+            missing.add(target);
+        }
+        else {
+            referenceRenames.set(local, target);
+            renamedInPlace.add(local);
+        }
+    }
+    /** The local name a replaced `KbqDlModule` refers to a component by, as a value. */
+    const componentLocal = (component) => {
+        const existing = localOf(component, true);
+        if (existing)
+            return existing;
+        const renamedValue = [...renamedInPlace].some((old) => renameOf(old) === component && !bindings.get(old).typeOnly);
+        if (!renamedValue)
+            missing.add(component);
+        return component;
+    };
+    /** The class an element of an array stands for, under its new name. */
+    const elementClass = (element) => {
+        let name;
+        if (ts.isIdentifier(element)) {
+            name = bindings.get(element.text)?.imported;
+        }
+        else if (ts.isPropertyAccessExpression(element) &&
+            ts.isIdentifier(element.expression) &&
+            namespaces.has(element.expression.text)) {
+            name = element.name.text;
+        }
+        return name && (renameOf(name) ?? name);
+    };
+    let moduleReferences = 0;
+    let moduleKept = false;
+    /** The components each array has gained, so that a second `KbqDlModule` in it adds nothing twice. */
+    const added = new Map();
+    const keepModule = (node) => {
+        moduleReferences++;
+        moduleKept = true;
+        keptModuleLines.push(sourceFile.getLineAndCharacterOfPosition(node.getStart()).line + 1);
+    };
+    /** Replaces a `KbqDlModule` element of an array with the components the array does not hold yet. */
+    const replaceModule = (node, componentText) => {
+        const { parent } = node;
+        if (!ts.isArrayLiteralExpression(parent))
+            return keepModule(node);
+        moduleReferences++;
+        const held = added.get(parent) ?? new Set(parent.elements.map(elementClass).filter((name) => !!name));
+        const components = migrations_dlStandaloneNames_data.MODULE_COMPONENTS.filter((component) => !held.has(component));
+        components.forEach((component) => held.add(component));
+        added.set(parent, held);
+        if (components.length) {
+            const lineStart = content.lastIndexOf('\n', node.getStart() - 1) + 1;
+            const indent = content.slice(lineStart, node.getStart());
+            const separator = /^[ \t]*$/.test(indent) ? `,\n${indent}` : ', ';
+            edits.push({
+                start: node.getStart(),
+                end: node.getEnd(),
+                text: components.map(componentText).join(separator)
+            });
+            return;
+        }
+        // Everything it re-exports is in the array already: the element goes, with one of its commas.
+        const elements = parent.elements;
+        const index = elements.indexOf(node);
+        const [start, end] = index < elements.length - 1
+            ? [node.getStart(), elements[index + 1].getStart()]
+            : index > 0
+                ? [elements[index - 1].getEnd(), node.getEnd()]
+                : [node.getStart(), node.getEnd()];
+        edits.push({ start, end, text: '' });
+    };
+    /** Points a specifier at the new class, keeping the name it binds or exports. */
+    const renameSpecifier = (element, name, keepAlias) => {
+        if (element.propertyName) {
+            edits.push({ start: element.propertyName.getStart(), end: element.propertyName.getEnd(), text: name });
+        }
+        else {
+            const text = keepAlias ? `${name} as ${element.name.text}` : name;
+            edits.push({ start: element.name.getStart(), end: element.name.getEnd(), text });
+        }
+    };
+    const visit = (node) => {
+        // Their specifiers are edited below.
+        if (ts.isImportDeclaration(node) || (ts.isExportDeclaration(node) && isEntryPoint(node.moduleSpecifier))) {
+            return;
+        }
+        if (ts.isExportSpecifier(node) && !node.parent.parent.moduleSpecifier) {
+            // A local `export { … }` of the import keeps the name it exports.
+            const source = (node.propertyName ?? node.name).text;
+            const local = referenceRenames.get(source);
+            if (local)
+                renameSpecifier(node, local, true);
+            if (bindings.get(source)?.imported === migrations_dlStandaloneNames_data.DL_MODULE)
+                keepModule(node);
+            return;
+        }
+        if ((ts.isPropertyAccessExpression(node) || ts.isQualifiedName(node)) &&
+            ts.isIdentifier(ts.isPropertyAccessExpression(node) ? node.expression : node.left) &&
+            namespaces.has((ts.isPropertyAccessExpression(node) ? node.expression : node.left).getText())) {
+            const namespace = (ts.isPropertyAccessExpression(node) ? node.expression : node.left).getText();
+            const member = ts.isPropertyAccessExpression(node) ? node.name : node.right;
+            const target = renameOf(member.text);
+            if (target) {
+                edits.push({ start: member.getStart(), end: member.getEnd(), text: target });
+            }
+            else if (member.text === migrations_dlStandaloneNames_data.DL_MODULE && ts.isPropertyAccessExpression(node)) {
+                replaceModule(node, (component) => `${namespace}.${component}`);
+            }
+            return;
+        }
+        if (ts.isIdentifier(node) && isReference(node)) {
+            const local = referenceRenames.get(node.text);
+            if (local) {
+                edits.push({
+                    start: node.getStart(),
+                    end: node.getEnd(),
+                    text: ts.isShorthandPropertyAssignment(node.parent) ? `${node.text}: ${local}` : local
+                });
+            }
+            else if (bindings.get(node.text)?.imported === migrations_dlStandaloneNames_data.DL_MODULE) {
+                if (ts.isShorthandPropertyAssignment(node.parent)) {
+                    keepModule(node);
+                }
+                else {
+                    replaceModule(node, componentLocal);
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    for (const declaration of imports) {
+        const named = declaration.importClause?.namedBindings;
+        if (!named || !ts.isNamedImports(named))
+            continue;
+        for (const element of named.elements) {
+            const target = renameOf((element.propertyName ?? element.name).text);
+            // An unaliased old import is renamed in place or dropped; an aliased one keeps its local name.
+            if (target && (element.propertyName || renamedInPlace.has(element.name.text))) {
+                renameSpecifier(element, target, false);
+            }
+        }
+    }
+    for (const declaration of reExports) {
+        const named = declaration.exportClause;
+        if (!named || !ts.isNamedExports(named))
+            continue;
+        for (const element of named.elements) {
+            const target = renameOf((element.propertyName ?? element.name).text);
+            if (target)
+                renameSpecifier(element, target, true);
+        }
+    }
+    let result = content;
+    for (const { start, end, text } of edits.sort((a, b) => b.start - a.start)) {
+        result = result.slice(0, start) + text + result.slice(end);
+    }
+    // Added before the module goes, so that an import of the module alone gains them in place rather than being
+    // dropped and recreated at the top of the file.
+    for (const component of missing)
+        result = replacementDriver.ensureImport(result, component, migrations_dlStandaloneNames_data.DL_PACKAGE);
+    for (const old of droppedOld)
+        result = replacementDriver.removeImport(result, old, migrations_dlStandaloneNames_data.DL_PACKAGE);
+    // The module import goes once nothing refers to it; an import nothing used is not this migration's business.
+    if (moduleReferences > 0 && !moduleKept)
+        result = replacementDriver.removeImport(result, migrations_dlStandaloneNames_data.DL_MODULE, migrations_dlStandaloneNames_data.DL_PACKAGE);
+    result = replacementDriver.dedupeImportSpecifiers(result, content);
+    return { content: result, changed: result !== content, keptModuleLines };
+}
+/**
+ * Moves the consumers of the description list to the names of its standalone components, and off its no longer
+ * documented NgModule where that is a drop-in change. Only `.ts` files are visited: the selectors did not change,
+ * so no template does.
+ */
+function dlStandaloneNames(options) {
+    return async (tree, context) => {
+        // `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(options.project, tree);
+        const root = projectDefinition?.root ?? '';
+        const rootDir = root ? tree.getDir(root) : tree.root;
+        let consumers = 0;
+        let touched = 0;
+        utils_packageConfig.visitProjectFiles(rootDir, (filePath, entry) => {
+            if (!filePath.endsWith(TS_EXT))
+                return;
+            const original = entry.content.toString();
+            if (!original.includes(migrations_dlStandaloneNames_data.DL_PACKAGE))
+                return;
+            consumers++;
+            const { content, changed, keptModuleLines } = migrateSource(original, filePath);
+            for (const line of keptModuleLines) {
+                utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${migrations_dlStandaloneNames_data.keptModuleMessage(line)}`]);
+            }
+            if (!changed)
+                return;
+            touched++;
+            if (fix) {
+                tree.overwrite(filePath, content);
+            }
+            else {
+                utils_messages.logMessage(context.logger, [`${LABEL} would update ${filePath} (run with --fix to apply)`]);
+            }
+        });
+        // Nothing here uses the description list, so the summary would only be noise.
+        if (consumers === 0)
+            return;
+        utils_messages.logMessage(context.logger, [
+            `${LABEL} processed tree under "${root || '<workspace root>'}", ${consumers} file(s) import ` +
+                `${migrations_dlStandaloneNames_data.DL_PACKAGE}, ${fix ? 'updated' : 'would update'} ${touched} file(s).`,
+            ...migrations_dlStandaloneNames_data.SUMMARY
+        ]);
+    };
+}
+
+exports.default = dlStandaloneNames;
+exports.migrateSource = migrateSource;

package/schematics/migrations/dl-standalone-names/schema.json

@@ -0,0 +1,20 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-dl-standalone-names",
+    "title": "Koobiq components description list standalone names 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 rewrites. When false, prints what would change without writing."
+        }
+    }
+}

package/schematics/migrations/dropdown-demote-overlay/README.md

@@ -0,0 +1,137 @@
+# dropdown-demote-overlay
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21`
+(registered for `21.0.0-0`). Cleans up after the removal of the overlay demotion
+mechanism.
+
+## Background
+
+`KbqDropdownTrigger.demoteOverlay` (default `true`) toggled a
+`.cdk-overlay-container_dropdown` class on the **shared, app-wide**
+`.cdk-overlay-container`, lowering it from `z-index: 1000` to `999` while a
+panel was open. `kbq-select` and `kbq-popover` applied the same class
+unconditionally. The `KBQ_DROPDOWN_HOST` marker token, provided by `KbqNavbar`
+and `KbqTopBar`, flipped the default to `false` so a dropdown inside the chrome
+would not slide behind its own trigger.
+
+All of it was removed: the input, the token, the class, and the stylesheet rule.
+
+## Behaviour change
+
+**Dropdown, select and popover panels now render above `kbq-navbar` and
+`kbq-top-bar` instead of sliding under them while open.** The overlay container
+stays at `z-index: 1000` at all times.
+
+To have panels slide under the bars again, mark the content area below them
+with the `kbqOverlayLayer` directive from `@koobiq/components/core` rather than
+trying to reinstate the demotion — it lowered _every_ overlay, including
+modals, sidepanels and toasts.
+
+## What it does
+
+The schematic walks every `.ts`, `.html`, `.scss` and `.css` file in the project
+(skipping `node_modules` and `dist`).
+
+| Auto-fix                                                                                      | Where                                         |
+| --------------------------------------------------------------------------------------------- | --------------------------------------------- |
+| Removes `demoteOverlay`, `demoteOverlay="…"`, `[demoteOverlay]="…"`, `bind-demoteOverlay="…"` | `.html` and inline `@Component({ template })` |
+| Removes `{ provide: KBQ_DROPDOWN_HOST, … }` entries of a provider array                       | `.ts`                                         |
+| Removes the `KBQ_DROPDOWN_HOST` import specifier it made invalid                              | `.ts`                                         |
+| Drops a `providers: []` array the removal left empty                                          | `.ts`                                         |
+
+Templates are **parsed**, and only nodes the parser reports as attributes are
+removed. An identifier of the same name elsewhere — in an interpolation, a
+binding expression, a `@if` condition or plain text — is left alone.
+
+Template rules are applied to `.ts` files **only inside inline
+`@Component({ template })` literals**, located through the TypeScript AST. A
+`template` property of some other object, or one mentioned in a comment or a
+string, is not a component template and is left alone. A wrapper component that
+declares its own forwarding member (`@Input() demoteOverlay = false;`) keeps
+that declaration untouched — only the binding in its template is removed, and
+the compiler then points at the now-dead member.
+
+Provider entries are found through the AST as well, and are removed **only when
+they are elements of a provider array**. A provider object bound to a name
+(`export const HOST_PROVIDER = { provide: KBQ_DROPDOWN_HOST, … };`) is not an
+element of anything — cutting it out would leave `= ;` behind — so it is warned
+about instead. The entry is deleted together with exactly one adjacent
+separator, so the surrounding array keeps its shape and nothing else in the file
+is reformatted.
+
+## What it does _not_ do (warn-only)
+
+| Pattern                                              | Manual migration                                                                                                                      |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `.demoteOverlay` in `.ts`                            | Delete the read/assignment — there is nothing left to opt out of                                                                      |
+| `.demoteOverlay` in a template                       | Drop the read (e.g. via a `#trigger="kbqDropdownTrigger"` reference)                                                                  |
+| `KBQ_DROPDOWN_HOST` left over                        | A provider declared outside a provider array (`export const HOST_PROVIDER = { … }`), or an `inject()` call — remove it by hand        |
+| `cdk-overlay-container_dropdown` in `.scss` / `.css` | Dead rule — remove it. If it was an override neutralising the demotion, it is now redundant                                           |
+| A template mentioning the input that fails to parse  | Nothing is rewritten in it — editing an unparseable template blind is how a migration corrupts bindings. Remove the attribute by hand |
+
+Warnings are checked against the **post-fix** content, so an auto-fixed usage
+does not also report as needing manual work. In dry-run mode (`--fix false`)
+they are reported against the original content instead.
+
+`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:dropdown-demote-overlay --project "<your project>"
+```
+
+Usage for Nx:
+
+```shell
+nx g @koobiq/components:dropdown-demote-overlay --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:dropdown-demote-overlay --project koobiq-docs
+```
+
+### Result
+
+#### Before
+
+```ts
+import { Component } from '@angular/core';
+import { KBQ_DROPDOWN_HOST } from '@koobiq/components/dropdown';
+
+@Component({
+    selector: 'my-header',
+    providers: [{ provide: KBQ_DROPDOWN_HOST, useExisting: MyHeader }],
+    template: `
+        <button [kbqDropdownTriggerFor]="menu" demoteOverlay="false">Open</button>
+    `
+})
+export class MyHeader {}
+```
+
+#### After
+
+```ts
+import { Component } from '@angular/core';
+
+@Component({
+    selector: 'my-header',
+    template: `
+        <button [kbqDropdownTriggerFor]="menu">Open</button>
+    `
+})
+export class MyHeader {}
+```

package/schematics/migrations/dropdown-demote-overlay/data.js

@@ -0,0 +1,84 @@
+'use strict';
+
+/**
+ * Replacement data for the removal of the overlay-demotion mechanism.
+ *
+ * `KbqDropdownTrigger.demoteOverlay`, the `KBQ_DROPDOWN_HOST` marker token and
+ * the `.cdk-overlay-container_dropdown` stylesheet rule were removed. They used
+ * to lower the whole shared `.cdk-overlay-container` from `z-index: 1000` to
+ * `999` while a dropdown / select / popover panel was open, so the panel slid
+ * under a sticky `kbq-navbar` / `kbq-top-bar`. Panels now always render above
+ * page content.
+ */
+/**
+ * The input removed from templates. Matched against the parsed template AST, so
+ * every binding form (`demoteOverlay`, `demoteOverlay="…"`, `[demoteOverlay]="…"`,
+ * `bind-demoteOverlay="…"`) is covered, while an identifier of the same name in an
+ * interpolation, a binding expression or a text node is never touched.
+ */
+const REMOVED_ATTRIBUTE = 'demoteOverlay';
+/**
+ * The token whose provider entries are removed. Matched against the TypeScript
+ * AST — an object literal with a `provide: KBQ_DROPDOWN_HOST` property — so the
+ * entry's own shape does not matter (a `useFactory` returning an object literal
+ * is removed as cleanly as a `useExisting`), and a provider object declared
+ * outside a provider array is never touched.
+ */
+const PROVIDER_TOKEN = 'KBQ_DROPDOWN_HOST';
+/** The import specifier the provider removal makes invalid. */
+const PROVIDER_IMPORT = { symbol: 'KBQ_DROPDOWN_HOST', from: '@koobiq/components/dropdown' };
+/**
+ * Warnings for `.ts` files. Checked against the post-fix content, so they only
+ * fire on what the auto-fix could not handle.
+ */
+const tsWarnPatterns = [
+    {
+        pattern: '\\.demoteOverlay\\b',
+        message: 'KbqDropdownTrigger.demoteOverlay was removed. Delete the read/assignment — the overlay ' +
+            'container is no longer demoted, so there is nothing to opt out of.'
+    },
+    {
+        pattern: '\\bKBQ_DROPDOWN_HOST\\b',
+        message: 'KBQ_DROPDOWN_HOST was removed from @koobiq/components/dropdown. Remove the provider / ' +
+            'inject() call. Manual migration required — this usage was not in a shape the schematic could rewrite.'
+    }
+];
+/** Warnings for `.html` files and inline templates. */
+const templateWarnPatterns = [
+    {
+        pattern: '\\.demoteOverlay\\b',
+        message: 'KbqDropdownTrigger.demoteOverlay was removed. Drop this read from the template ' +
+            '(e.g. via a #trigger="kbqDropdownTrigger" reference).'
+    }
+];
+/** Warnings for `.scss` / `.css` files. */
+const styleWarnPatterns = [
+    {
+        pattern: 'cdk-overlay-container_dropdown',
+        message: 'The .cdk-overlay-container_dropdown class is no longer applied by @koobiq/components, so ' +
+            'this rule is dead — remove it. If it was an override neutralising the demotion, it is now redundant.'
+    }
+];
+/** Reported when a template mentions the input but cannot be parsed, so nothing was rewritten in it. */
+const UNPARSEABLE_TEMPLATE_MESSAGE = 'This template mentions demoteOverlay but could not be parsed, so it was left untouched. ' +
+    'Remove the attribute by hand.';
+/**
+ * Behaviour note printed once per run. The removal is not purely mechanical:
+ * panels that used to slide under sticky chrome now render on top of it.
+ */
+const BEHAVIOUR_NOTE = [
+    'Layering behaviour changed: kbq-dropdown, kbq-select and popover panels now render ABOVE',
+    'kbq-navbar / kbq-top-bar instead of sliding under them while open. The shared',
+    '.cdk-overlay-container stays at z-index 1000 at all times.',
+    'To have panels slide under the bars again, mark the content area below them with the',
+    'kbqOverlayLayer directive from @koobiq/components/core.'
+];
+
+exports.BEHAVIOUR_NOTE = BEHAVIOUR_NOTE;
+exports.PROVIDER_IMPORT = PROVIDER_IMPORT;
+exports.PROVIDER_TOKEN = PROVIDER_TOKEN;
+exports.REMOVED_ATTRIBUTE = REMOVED_ATTRIBUTE;
+exports.UNPARSEABLE_TEMPLATE_MESSAGE = UNPARSEABLE_TEMPLATE_MESSAGE;
+exports.styleWarnPatterns = styleWarnPatterns;
+exports.templateWarnPatterns = templateWarnPatterns;
+exports.tsWarnPatterns = tsWarnPatterns;