@koobiq/components 20.4.2 → 21.0.1

package/schematics/migrations/list-tree-multiple-input/README.md

@@ -0,0 +1,105 @@
+# list-tree-multiple-input
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21` (registered for `21.0.0-0`).
+
+## Background
+
+`multiple` on `kbq-list-selection` and `kbq-tree-selection` used to be a static host attribute read once in
+the constructor:
+
+```ts
+const multiple = inject(new HostAttributeToken('multiple'), { optional: true });
+
+if (multiple === MultipleMode.CHECKBOX || multiple === MultipleMode.KEYBOARD) {
+    this.multipleMode = multiple;
+} else if (multiple !== null) {
+    this.multipleMode = MultipleMode.CHECKBOX; // every other value
+}
+```
+
+So the attribute could not be bound, the mode was frozen for the lifetime of the component, and **every**
+value other than `checkbox` and `keyboard` fell through to multiple selection with checkboxes —
+`multiple="false"` meant _multiple_.
+
+It is now a real input with a closed set of values, resolved by `resolveMultipleMode` in
+`@koobiq/components/core`, and the mode can be changed at any time.
+
+## Behaviour change
+
+| value                                                  | before       | after            |
+| ------------------------------------------------------ | ------------ | ---------------- |
+| `multiple="checkbox"`, `multiple="keyboard"`           | that mode    | unchanged        |
+| `multiple`, `multiple=""`, `multiple="true"`           | checkbox     | unchanged        |
+| no attribute                                           | single       | unchanged        |
+| `multiple="false"`, `multiple="single"`, anything else | **checkbox** | single selection |
+
+Single selection is the default, so the way to ask for it is to leave the attribute off entirely.
+`multiple="single"` is not an accepted spelling.
+
+## What it does
+
+| case                                                           | rewrite                     | preserves behaviour?      |
+| -------------------------------------------------------------- | --------------------------- | ------------------------- |
+| `multiple="false"`, `multiple="single"`                        | attribute removed           | **no** — reported as such |
+| any other unrecognized value (`"multiple"`, `"yes"`, `"1"`, …) | → `multiple="checkbox"`     | yes                       |
+| `[multiple]="'yes'"` (quoted literal)                          | → `[multiple]="'checkbox'"` | yes                       |
+
+Both external `.html` files and inline `@Component({ template })` literals are covered. The two spellings
+that are deleted are the ones whose author meant single selection but got multiple; every rewrite is logged
+with the value it replaced, and the deletions are called out as a behaviour change so they can be reviewed
+in the diff.
+
+## What it does _not_ do (warn-only)
+
+| case                                              | why                                                                                                                            |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `[multiple]="expr"`                               | a runtime expression cannot be resolved at migration time                                                                      |
+| `[multiple]="true \| false \| null \| undefined"` | unambiguous under the new API and impossible before it, so it is left alone silently                                           |
+| `multipleMode = …`                                | now an accessor: it rebuilds the `SelectionModel`, and inside a `kbq-tree-select` it throws, because the select owns the model |
+| `selectionModel.changed.subscribe(…)`             | a mode change replaces the model instance, stranding the subscription; use the `(selectionChange)` output                      |
+
+[Params](schema.ts)
+
+Usage for Angular Cli:
+
+```shell
+ng g @koobiq/components:list-tree-multiple-input --project "<your project>"
+```
+
+Usage for Nx:
+
+```shell
+nx g @koobiq/components:list-tree-multiple-input --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:list-tree-multiple-input --project koobiq-docs
+```
+
+### Result
+
+#### Before
+
+```html
+<kbq-list-selection multiple="false">…</kbq-list-selection>
+<kbq-list-selection multiple="single">…</kbq-list-selection>
+<kbq-tree-selection multiple="multiple">…</kbq-tree-selection>
+```
+
+#### After
+
+```html
+<kbq-list-selection>…</kbq-list-selection>
+<kbq-list-selection>…</kbq-list-selection>
+<kbq-tree-selection multiple="checkbox">…</kbq-tree-selection>
+```

package/schematics/migrations/list-tree-multiple-input/data.cjs

@@ -0,0 +1,74 @@
+'use strict';
+
+/** The input this migration rewrites. Matched against the parsed template AST, not against raw text. */
+const MULTIPLE_ATTRIBUTE = 'multiple';
+/** The two components whose `multiple` changed meaning. `kbq-tree-select` has its own, unrelated input. */
+const TARGET_ELEMENTS = ['kbq-list-selection', 'kbq-tree-selection'];
+/**
+ * The mode the migration writes when it has to preserve multiple selection.
+ *
+ * Spelled out rather than imported from `@koobiq/components`: a schematic describes a past state of the
+ * API, so it must keep working after the enum it migrates away from has moved on.
+ */
+const CHECKBOX_MODE = 'checkbox';
+/** Values whose meaning did not change, so a template using one is already correct. */
+const UNCHANGED_VALUES = ['', 'true', CHECKBOX_MODE, 'keyboard'];
+/**
+ * Values that asked for single selection in the author's head but enabled multiple selection in the
+ * browser. The attribute is deleted rather than rewritten: single selection is what an absent `multiple`
+ * already means, and `multiple="single"` is no longer an accepted spelling.
+ */
+const SINGLE_INTENT_VALUES = ['false', 'single'];
+/**
+ * Expression literals a binding may hold that are unambiguous under the new API. They cannot appear in
+ * code written before this release — `multiple` was not an input then — so they are left alone silently.
+ */
+const SAFE_BINDING_LITERALS = ['true', 'false', 'null', 'undefined'];
+const removedAttributeMessage = (filePath, value) => [
+    `  removed ${MULTIPLE_ATTRIBUTE}="${value}" — single selection is the default, so the attribute is gone.`,
+    '  BEHAVIOUR CHANGE: this element used to allow multiple selection with checkboxes. If that is what you',
+    `  wanted, put ${MULTIPLE_ATTRIBUTE}="${CHECKBOX_MODE}" back. File: ${filePath}`
+];
+const rewrittenAttributeMessage = (filePath, value) => [
+    `  ${MULTIPLE_ATTRIBUTE}="${value}" → ${MULTIPLE_ATTRIBUTE}="${CHECKBOX_MODE}", which preserves the`,
+    `  behaviour: every unrecognized value used to enable multiple selection. File: ${filePath}`
+];
+const dynamicBindingMessage = (filePath, value) => [
+    `  [${MULTIPLE_ATTRIBUTE}]="${value}" is a runtime expression and cannot be resolved here. Make sure it`,
+    `  evaluates to "${CHECKBOX_MODE}", "keyboard", a boolean or null. File: ${filePath}`
+];
+const UNPARSEABLE_TEMPLATE_MESSAGE = 'Template could not be parsed, so it was left untouched. Check its `multiple` attributes by hand.';
+const tsWarnPatterns = [
+    {
+        pattern: '\\.multipleMode\\s*=',
+        message: 'KbqListSelection.multipleMode / KbqTreeSelection.multipleMode is now an accessor. Assigning to it ' +
+            'rebuilds the SelectionModel instead of only relabelling the mode, and on a kbq-tree-selection ' +
+            'rendered inside a kbq-tree-select it throws, because the select owns the model. Bind `multiple` ' +
+            'on the select instead.'
+    },
+    {
+        pattern: 'selectionModel\\s*\\.\\s*changed',
+        message: 'Changing the mode replaces the SelectionModel instance, so a subscription taken on ' +
+            'selectionModel.changed is left behind on the discarded one. Subscribe to the ' +
+            '(selectionChange) output instead.'
+    }
+];
+const BEHAVIOUR_NOTE = [
+    'Note: `multiple` on kbq-list-selection and kbq-tree-selection is now a real input with a closed set of',
+    'values. `checkbox`, `keyboard`, a bare attribute and `true` enable multiple selection; an absent',
+    'attribute, `false` and `null` mean single selection. Every other value now falls back to single',
+    'selection and is reported in dev mode, where it used to enable multiple selection with checkboxes.'
+];
+
+exports.BEHAVIOUR_NOTE = BEHAVIOUR_NOTE;
+exports.CHECKBOX_MODE = CHECKBOX_MODE;
+exports.MULTIPLE_ATTRIBUTE = MULTIPLE_ATTRIBUTE;
+exports.SAFE_BINDING_LITERALS = SAFE_BINDING_LITERALS;
+exports.SINGLE_INTENT_VALUES = SINGLE_INTENT_VALUES;
+exports.TARGET_ELEMENTS = TARGET_ELEMENTS;
+exports.UNCHANGED_VALUES = UNCHANGED_VALUES;
+exports.UNPARSEABLE_TEMPLATE_MESSAGE = UNPARSEABLE_TEMPLATE_MESSAGE;
+exports.dynamicBindingMessage = dynamicBindingMessage;
+exports.removedAttributeMessage = removedAttributeMessage;
+exports.rewrittenAttributeMessage = rewrittenAttributeMessage;
+exports.tsWarnPatterns = tsWarnPatterns;

package/schematics/migrations/list-tree-multiple-input/index.cjs

@@ -0,0 +1,222 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var ts = require('typescript');
+var utils_ast = require('../../utils/ast.cjs');
+var utils_messages = require('../../utils/messages.cjs');
+var utils_packageConfig = require('../../utils/package-config.cjs');
+var utils_projectFiles = require('../../utils/project-files.cjs');
+var utils_typescript = require('../../utils/typescript.cjs');
+var migrations_listTreeMultipleInput_data = require('./data.cjs');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+const TS_EXT = '.ts';
+const HTML_EXT = '.html';
+const LABEL = '[list-tree-multiple-input]';
+/** `multiple`, `[multiple]` and `bind-multiple` all name the same input. */
+function attributeName(name) {
+    return utils_ast.getSimpleAttributeName(name).replace(/^bind-/, '');
+}
+/**
+ * The value an attribute carries, when it is knowable without running the app.
+ *
+ * A plain attribute holds its value verbatim. A binding holds an expression, which is only resolvable
+ * here when it is a quoted string literal; anything else is a genuine runtime value.
+ */
+function resolveValue(attr) {
+    const raw = typeof attr.value === 'string' ? attr.value : '';
+    const binding = attributeName(attr.name) !== attr.name;
+    if (!binding)
+        return { value: raw, binding };
+    const quoted = /^\s*'([^']*)'\s*$/.exec(raw) ?? /^\s*"([^"]*)"\s*$/.exec(raw);
+    return quoted ? { value: quoted[1], binding } : null;
+}
+/** Renders the attribute back, keeping the binding syntax the author used. */
+function render(binding, value) {
+    return binding ? `[${migrations_listTreeMultipleInput_data.MULTIPLE_ATTRIBUTE}]="'${value}'"` : `${migrations_listTreeMultipleInput_data.MULTIPLE_ATTRIBUTE}="${value}"`;
+}
+function decide(attr) {
+    const span = { start: attr.sourceSpan.start.offset, end: attr.sourceSpan.end.offset };
+    const resolved = resolveValue(attr);
+    if (!resolved) {
+        // An unresolvable expression. The literals below are unambiguous under the new API and cannot
+        // predate it, so reporting them would be noise.
+        if (migrations_listTreeMultipleInput_data.SAFE_BINDING_LITERALS.includes(String(attr.value).trim()))
+            return null;
+        return { edit: null, report: (filePath) => migrations_listTreeMultipleInput_data.dynamicBindingMessage(filePath, String(attr.value).trim()) };
+    }
+    const { value, binding } = resolved;
+    if (migrations_listTreeMultipleInput_data.UNCHANGED_VALUES.includes(value))
+        return null;
+    if (migrations_listTreeMultipleInput_data.SINGLE_INTENT_VALUES.includes(value)) {
+        return { edit: { ...span, text: '' }, report: (filePath) => migrations_listTreeMultipleInput_data.removedAttributeMessage(filePath, value) };
+    }
+    return {
+        edit: { ...span, text: render(binding, migrations_listTreeMultipleInput_data.CHECKBOX_MODE) },
+        report: (filePath) => migrations_listTreeMultipleInput_data.rewrittenAttributeMessage(filePath, value)
+    };
+}
+/** Collects a finding for every `multiple` attribute on a target element. */
+class MultipleAttributeCollector {
+    constructor() {
+        this.findings = [];
+    }
+    visitElement(element) {
+        if (migrations_listTreeMultipleInput_data.TARGET_ELEMENTS.includes(element.name)) {
+            for (const attr of element.attrs ?? []) {
+                if (typeof attr.name !== 'string' || attributeName(attr.name) !== migrations_listTreeMultipleInput_data.MULTIPLE_ATTRIBUTE)
+                    continue;
+                const finding = decide(attr);
+                if (finding)
+                    this.findings.push(finding);
+            }
+        }
+        this.visitChildren(element);
+    }
+    visitBlock(block) {
+        this.visitChildren(block);
+    }
+    visitChildren(node) {
+        for (const child of node.children ?? []) {
+            child.visit(this);
+        }
+    }
+    visitAttribute() { }
+    visitText() { }
+    visitComment() { }
+    visitExpansion() { }
+    visitExpansionCase() { }
+    visitBlockParameter() { }
+    visitLetDeclaration() { }
+}
+/**
+ * Applies the edits. A deletion also takes the whitespace that separated the attribute from the previous
+ * one: an inline attribute takes its leading spaces, one written on its own line takes the line break and
+ * the indent as well, so the tag is not left with a blank line.
+ */
+function applyEdits(content, edits) {
+    let result = content;
+    // Right-to-left, so earlier offsets stay valid.
+    for (const { start, end, text } of [...edits].sort((a, b) => b.start - a.start)) {
+        let from = start;
+        if (text === '') {
+            while (from > 0 && (result[from - 1] === ' ' || result[from - 1] === '\t'))
+                from--;
+            if (result[from - 1] === '\n') {
+                from--;
+                if (result[from - 1] === '\r')
+                    from--;
+            }
+        }
+        result = result.slice(0, from) + text + result.slice(end);
+    }
+    return result;
+}
+/**
+ * Migrates every `multiple` attribute of a template. Returns `null` when the template could not be
+ * parsed — editing it blind is how a regex-based migration corrupts binding expressions, so the caller
+ * warns instead.
+ */
+async function migrateTemplate(template, onFinding) {
+    if (!template.includes(migrations_listTreeMultipleInput_data.MULTIPLE_ATTRIBUTE))
+        return template;
+    const parsed = await utils_typescript.parseTemplate(template);
+    if (!parsed.tree)
+        return null;
+    const collector = new MultipleAttributeCollector();
+    utils_ast.visitAll(collector, parsed.tree.rootNodes);
+    collector.findings.forEach(onFinding);
+    return applyEdits(template, collector.findings.map(({ edit }) => edit).filter((edit) => edit !== null));
+}
+/** Applies the template migration to every inline `@Component({ template })` literal of a `.ts` source. */
+async function migrateInlineTemplates(content, sourceFile, onFinding, onParseError) {
+    let result = content;
+    // Splice right-to-left so earlier offsets stay valid.
+    for (const { start, end } of utils_typescript.collectInlineTemplateRanges(sourceFile).sort((a, b) => b.start - a.start)) {
+        const migrated = await migrateTemplate(result.slice(start, end), onFinding);
+        if (migrated === null) {
+            onParseError();
+            continue;
+        }
+        result = result.slice(0, start) + migrated + result.slice(end);
+    }
+    return result;
+}
+function logWarnings(context, filePath, content, patterns) {
+    for (const { pattern, message } of patterns) {
+        if (new RegExp(pattern).test(content)) {
+            utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${message}`]);
+        }
+    }
+}
+function listTreeMultipleInput(options) {
+    return async (tree, context) => {
+        const { project } = options;
+        // `ng update` invokes migrations with no options at all, and migrations.json declares no schema,
+        // so the schema default never reaches us — applying the fix is the intended behaviour there.
+        const fix = options.fix ?? true;
+        const projectDefinition = await utils_packageConfig.setupOptions(project, tree);
+        const root = projectDefinition?.root ?? '';
+        const rootDir = root ? tree.getDir(root) : tree.root;
+        const filePaths = [];
+        utils_projectFiles.visitProjectFiles(rootDir, (filePath) => {
+            if (!filePath.endsWith(TS_EXT) && !filePath.endsWith(HTML_EXT))
+                return;
+            filePaths.push(filePath);
+        });
+        let touched = 0;
+        for (const filePath of filePaths) {
+            const originalContent = tree.read(filePath)?.toString();
+            if (!originalContent)
+                continue;
+            let content = originalContent;
+            let unparseable = false;
+            const reports = [];
+            const onFinding = (finding) => reports.push(finding.report(filePath));
+            // Parsing every `.ts` of the project is not free, and nothing can change in a file that
+            // mentions neither of the two elements.
+            const mentionsTarget = migrations_listTreeMultipleInput_data.TARGET_ELEMENTS.some((element) => content.includes(element));
+            if (filePath.endsWith(TS_EXT) && mentionsTarget) {
+                const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+                content = await migrateInlineTemplates(content, sourceFile, onFinding, () => (unparseable = true));
+            }
+            else if (filePath.endsWith(HTML_EXT) && mentionsTarget) {
+                const migrated = await migrateTemplate(content, onFinding);
+                if (migrated === null)
+                    unparseable = true;
+                else
+                    content = migrated;
+            }
+            for (const report of reports) {
+                utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, ...report]);
+            }
+            // Warn on what is left over, so an auto-fixed usage does not also produce a "manual migration
+            // required" note. In dry-run mode the fix is not written, so report against the original.
+            if (filePath.endsWith(TS_EXT)) {
+                logWarnings(context, filePath, fix ? content : originalContent, migrations_listTreeMultipleInput_data.tsWarnPatterns);
+            }
+            if (unparseable) {
+                utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${migrations_listTreeMultipleInput_data.UNPARSEABLE_TEMPLATE_MESSAGE}`]);
+            }
+            if (content === originalContent)
+                continue;
+            touched++;
+            if (fix) {
+                tree.overwrite(filePath, content);
+            }
+            else {
+                utils_messages.logMessage(context.logger, [`${LABEL} would update ${filePath} (run with --fix to apply)`]);
+            }
+        }
+        utils_messages.logMessage(context.logger, [
+            `${LABEL} processed tree under "${root || '<workspace root>'}", ` +
+                `${fix ? 'updated' : 'would update'} ${touched} file(s).`,
+            '',
+            ...migrations_listTreeMultipleInput_data.BEHAVIOUR_NOTE
+        ]);
+    };
+}
+
+exports.default = listTreeMultipleInput;

package/schematics/migrations/list-tree-multiple-input/schema.json

@@ -0,0 +1,20 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-list-tree-multiple-input",
+    "title": "Koobiq components list and tree multiple input",
+    "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/loader-overlay-signals/README.md

@@ -0,0 +1,62 @@
+# loader-overlay-signals
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21` (registered for
+`21.0.0-0`). Migrates `KbqLoaderOverlay` consumers to its finished signal-based API and reports the
+members the review closed.
+
+## Background
+
+`text` and `caption` were the two inputs the automated signal migration skipped — it saw them read
+inside `@if` blocks and would not risk the narrowing. They are `input()` now, and honest about being
+optional:
+
+```ts
+@Input() text: string; // no initializer — an unbound overlay reported undefined
+```
+
+They report `string | undefined`, which is what they always held.
+
+Everything the template uses to decide between a projected slot and an input — `isExternalIndicator`,
+`isExternalText`, `isExternalCaption`, `isEmpty`, `spinnerSize` and the three content queries — left
+the public surface in the same review.
+
+## What it rewrites
+
+| Before            | After               |
+| ----------------- | ------------------- |
+| `overlay.text`    | `overlay.text()`    |
+| `overlay.caption` | `overlay.caption()` |
+
+Both on receivers explicitly typed `KbqLoaderOverlay` and through template reference variables on
+`<kbq-loader-overlay>`, in external and inline templates. Already-migrated reads are left alone, so
+the schematic is idempotent.
+
+`size`, `transparent` and `card` were already signals in 20.2.0 and are not touched.
+
+## What it does _not_ do
+
+| Pattern                                                     | Manual migration                                          |
+| ----------------------------------------------------------- | --------------------------------------------------------- |
+| `overlay.text = …`                                          | Bind `[text]` in the template — the input is read-only    |
+| `.isEmpty` / `.isExternal*` / `.spinnerSize`                | Now `protected`; what the overlay renders is the contract |
+| `.externalIndicator` / `.externalText` / `.externalCaption` | Now `private` signal queries                              |
+| `viewChild(KbqLoaderOverlay)`                               | The query is a signal too, so a read needs two calls      |
+
+## Notes with no call site to point at
+
+- `text` and `caption` report `string | undefined`. The call sites that were already wrong now fail
+  to compile.
+- **`transparent` is a `booleanAttribute` input, and it flips in both directions.**
+  `<kbq-loader-overlay transparent>` used to pass the empty string, which is falsy, so the valueless
+  attribute rendered the _filled_ background — the opposite of how it reads; `[transparent]="0"` and
+  `NaN` read as false the same way, and all of them mean `true` now. Conversely
+  `[transparent]="'false'"` was a non-empty string, so it used to mean `true`. This is the one change
+  with no compile error behind it, so every file carrying the valueless attribute is reported.
+
+## Running it manually
+
+```
+ng generate @koobiq/components:loader-overlay-signals --project my-app
+```
+
+Pass `--fix=false` to see what it would change without writing.

package/schematics/migrations/loader-overlay-signals/data.cjs

@@ -0,0 +1,101 @@
+'use strict';
+
+/**
+ * Data for the `loader-overlay-signals` migration.
+ *
+ * `text` and `caption` were the two inputs the automated signal migration skipped, because they are read
+ * inside `@if` blocks and it would not risk the narrowing. They are `input()` now, and honest about being
+ * optional: both were declared `string` over a field with no initializer, so an overlay that bound neither
+ * reported `undefined` from a non-nullable type.
+ *
+ * - `overlay.text` / `overlay.caption` → calls (value unchanged — auto-fixed)
+ * - the template helpers and the content queries → `protected` / `private` (warn)
+ *
+ * `size`, `transparent` and `card` were already signals in 20.2.0 and need no rewrite; `transparent` only
+ * gained a `booleanAttribute` transform, which is reported rather than rewritten.
+ */
+/** Members of `KbqLoaderOverlay` whose value is unchanged; a read must become a call. Auto-fixed. */
+const SIGNAL_MEMBERS = ['text', 'caption'];
+/** Signal-API methods reachable on a signal; a read followed by one is already migrated. */
+const SIGNAL_API_METHODS = new Set(['set', 'update', 'asReadonly', 'subscribe']);
+/** Reported for a programmatic write, which has no mechanical translation: every member is an `input()`. */
+const writeMessage = (members) => `These are \`input()\`s now, so a programmatic write no longer compiles: ${[...members].join(', ')}. ` +
+    'Bind them in the template instead. The write is left untouched so the error points at your call site.';
+/** TypeScript type annotation that marks a receiver as a loader overlay. */
+const OVERLAY_TYPE = 'KbqLoaderOverlay';
+/** Element selector whose template reference variables (`#ref`) point at a loader overlay. */
+const OVERLAY_ELEMENT = 'kbq-loader-overlay';
+/** Import specifier that marks a file as a loader overlay consumer. */
+const OVERLAY_PACKAGE = '@koobiq/components/loader-overlay';
+/** Template helpers that became `protected`: a subclass still sees them, nothing outside does. */
+const PROTECTED_MEMBERS = [
+    'isExternalIndicator',
+    'isExternalText',
+    'isExternalCaption',
+    'isEmpty',
+    'spinnerSize'
+];
+/** Content queries that became `private`: not even a subclass can name them. */
+const PRIVATE_MEMBERS = ['externalIndicator', 'externalText', 'externalCaption'];
+/** Every member a consumer can no longer read, whichever visibility it landed on. */
+const HIDDEN_MEMBERS = [...PROTECTED_MEMBERS, ...PRIVATE_MEMBERS];
+const protectedMessage = (members) => `These KbqLoaderOverlay members are \`protected\` now: ${[...members].join(', ')}. They are the ` +
+    'template helpers behind the projection slots: what the overlay renders is the contract, not how it ' +
+    'decides. Read the DOM, or track the projected content yourself.';
+const privateMessage = (members) => `These KbqLoaderOverlay content queries are \`private\` now, so a subclass cannot name them either: ` +
+    `${[...members].join(', ')}. Project the content and read the DOM, or track it yourself.`;
+/**
+ * Reported for a read through a signal query, which is a signal holding the component: the read needs two
+ * calls rather than one. Emitted from the AST pass rather than a regex, so it follows the same receiver
+ * resolution as the rewrite - the decorator form is a plain annotated field that the rewrite handles, and
+ * telling the reader it needs two calls there would break working code.
+ *
+ * `viewChild()` without `.required` is typed `Signal<KbqLoaderOverlay | undefined>`, so the safe spelling
+ * differs between the two forms.
+ */
+const signalQueryMessage = (member, required) => `A signal query holds the component behind a call of its own, so reading \`${member}\` through it needs ` +
+    `two calls: \`this.overlay()${required ? '' : '?'}.${member}()\`.` +
+    (required ? '' : ' The query is optional, so keep the `?.`.') +
+    ' Those reads are left untouched - migrate them by hand.';
+/** Reported when a template renders the overlay but cannot be parsed, so nothing in it was inspected. */
+const UNPARSEABLE_TEMPLATE_MESSAGE = 'This template renders <kbq-loader-overlay> but could not be parsed, so it was left untouched. Migrate ' +
+    'reads through its template reference variables by hand. If every template is reported this way, ' +
+    '`@angular/compiler` could not be loaded from this install.';
+/**
+ * Reported when a file names `KbqLoaderOverlay` in a type position the receiver pass cannot scope to a
+ * single identifier - a union, an array, a `QueryList<…>`, a cast, a return type - or reads a member in a
+ * shape the access pass cannot reach.
+ */
+const UNRESOLVED_RECEIVER_MESSAGE = 'KbqLoaderOverlay is used here in a way this migration cannot resolve to a single receiver, so any ' +
+    'signal read through it was left untouched. Check these lines by hand:';
+/** Reported per file for the one change that produces no compile error anywhere. */
+const TRANSPARENT_ATTRIBUTE_MESSAGE = '`<kbq-loader-overlay transparent>` renders the transparent background now. The valueless attribute used ' +
+    'to pass the empty string, which is falsy, so it rendered the *filled* background - the opposite of what ' +
+    'it reads as. Nothing here fails to compile: check what this markup was relying on.';
+/** Printed once per project, after the per-file reports. */
+const SUMMARY = [
+    '  `text` and `caption` report `string | undefined` instead of `string`. Both were declared non-nullable ' +
+        'over a field with no initializer, so an overlay that bound neither always handed back `undefined` — ' +
+        'the call sites that were already wrong now fail to compile.',
+    '  `transparent` is a `booleanAttribute` input, and it flips in both directions. A valueless attribute, ' +
+        '`0` and `NaN` used to read as false, so <kbq-loader-overlay transparent> rendered the *filled* ' +
+        'background - the opposite of what it reads as - and they all mean true now. Conversely ' +
+        '[transparent]="\'false\'" was a non-empty string, so it used to mean true, and now means false.'
+];
+
+exports.HIDDEN_MEMBERS = HIDDEN_MEMBERS;
+exports.OVERLAY_ELEMENT = OVERLAY_ELEMENT;
+exports.OVERLAY_PACKAGE = OVERLAY_PACKAGE;
+exports.OVERLAY_TYPE = OVERLAY_TYPE;
+exports.PRIVATE_MEMBERS = PRIVATE_MEMBERS;
+exports.PROTECTED_MEMBERS = PROTECTED_MEMBERS;
+exports.SIGNAL_API_METHODS = SIGNAL_API_METHODS;
+exports.SIGNAL_MEMBERS = SIGNAL_MEMBERS;
+exports.SUMMARY = SUMMARY;
+exports.TRANSPARENT_ATTRIBUTE_MESSAGE = TRANSPARENT_ATTRIBUTE_MESSAGE;
+exports.UNPARSEABLE_TEMPLATE_MESSAGE = UNPARSEABLE_TEMPLATE_MESSAGE;
+exports.UNRESOLVED_RECEIVER_MESSAGE = UNRESOLVED_RECEIVER_MESSAGE;
+exports.privateMessage = privateMessage;
+exports.protectedMessage = protectedMessage;
+exports.signalQueryMessage = signalQueryMessage;
+exports.writeMessage = writeMessage;