@koobiq/components 20.4.2 → 21.0.1

package/schematics/migrations/button-truncation/data.cjs

@@ -0,0 +1,88 @@
+'use strict';
+
+/**
+ * Data for the `button-truncation` migration.
+ *
+ * `KbqButton` and `KbqButtonToggle` now truncate their label with an ellipsis by default. Three things
+ * changed that no compiler can catch:
+ *
+ * 1. `.kbq-button` / `.kbq-light-button` gained `max-width: 100%`, so a button that used to overflow its
+ *    container now clamps to it and clips the label. Nothing in a template or a stylesheet identifies the
+ *    affected places — this is reported once, as a note.
+ * 2. `.kbq-button-text` went from `display: flex` to `display: inline-block` (only a block container paints
+ *    `text-overflow`). Content projected into the default slot that relied on being a flex row lays out
+ *    differently, and hand-rolled truncation overrides now stack on top of the built-in one.
+ * 3. `kbq-button-toggle` gained a `.kbq-button-toggle-text` box between `.kbq-button-toggle-wrapper` and the
+ *    projected content, so selectors aimed at the wrapper reach a different element.
+ *
+ * Only the markup is auto-fixed: an icon at either edge of a button's default slot is moved into the
+ * `kbqButtonPrefix`/`kbqButtonSuffix` slot, which is what keeps it laid out *beside* the truncating box
+ * instead of inside it. Stylesheets are reported, never rewritten — the right fix depends on why the
+ * override exists.
+ */
+/** Attribute that marks a Koobiq button host, e.g. `<button kbq-button>` or `<a kbq-button>`. */
+const BUTTON_ATTR = 'kbq-button';
+/** Element whose default slot has the same prefix/suffix contract as a button. */
+const TOGGLE_ELEMENT = 'kbq-button-toggle';
+/**
+ * Attributes that make an element a `KbqIcon`. `[kbq-icon-button]` and `[kbq-icon-item]` are subclasses,
+ * so they count towards the same content query the component uses to decide its icon layout.
+ */
+const ICON_ATTRS = ['kbq-icon', 'kbq-icon-button', 'kbq-icon-item'];
+/** Marker directives that project content out of the truncating label box. */
+const PREFIX_ATTR = 'kbqButtonPrefix';
+const SUFFIX_ATTR = 'kbqButtonSuffix';
+/**
+ * Stylesheet overrides that are affected by the layout change. Reported with file locations in both `fix`
+ * and dry-run mode: whether an override has to be dropped, retargeted or kept depends on why it was written,
+ * and guessing wrong silently changes a layout.
+ */
+const stylePatterns = [
+    {
+        selector: '.kbq-button-text',
+        pattern: '\\.kbq-button-text\\b',
+        message: '`.kbq-button-text` is no longer a flex container — it is `display: inline-block`, because ' +
+            '`text-overflow: ellipsis` is never painted on a flex box. If you project your own row of elements ' +
+            'into the default slot, re-declare `display: flex; align-items: center` on it (see how ' +
+            '`kbq-filter-bar` does it). If this rule was hand-rolled truncation, delete it: the label now ' +
+            'truncates on its own.'
+    },
+    {
+        selector: '.kbq-button-wrapper',
+        pattern: '\\.kbq-button-wrapper\\b',
+        message: '`.kbq-button-wrapper` no longer needs a truncation override — `.kbq-button-text` inside it clips ' +
+            'and paints the ellipsis, and the button host carries `max-width: 100%`. An override that sets ' +
+            '`overflow`/`text-overflow`/`display` here now stacks on top of the built-in behaviour; delete it ' +
+            'unless it does something else.'
+    },
+    {
+        selector: '.kbq-button-toggle-wrapper',
+        pattern: '\\.kbq-button-toggle-wrapper\\b',
+        message: '`kbq-button-toggle` gained a `.kbq-button-toggle-text` box: the wrapper is now only the flex row ' +
+            'that lays out the slots, and the projected label sits one level deeper. Retarget selectors that ' +
+            'meant the label (including `display: block` overrides added to get an ellipsis — that now works ' +
+            'out of the box) at `.kbq-button-toggle-text`.'
+    }
+];
+/** Printed once per run: the one change that has no textual signature to search for. */
+const MAX_WIDTH_NOTE = [
+    '`.kbq-button` and `.kbq-light-button` now carry `max-width: 100%`.',
+    'A button whose label is wider than its container no longer overflows — it clamps and truncates.',
+    'Nothing identifies those places in code, so review screens with narrow buttons, dense toolbars and',
+    'table cells visually (screenshot tests will show it immediately).',
+    'To upgrade first and adopt truncation screen by screen, neutralise it in your global styles:',
+    '    .kbq-button, .kbq-light-button { max-width: none; }'
+];
+/** Printed once per run when a template could not be migrated automatically. */
+const MANUAL_TEMPLATE_NOTE = 'Icons that are not a direct first/last child of the button (wrapped in your own element, or produced by ' +
+    'a block with more than one element) keep sharing the label box and give the ellipsis up. Mark them with ' +
+    `\`${PREFIX_ATTR}\`/\`${SUFFIX_ATTR}\` by hand if the label should truncate.`;
+
+exports.BUTTON_ATTR = BUTTON_ATTR;
+exports.ICON_ATTRS = ICON_ATTRS;
+exports.MANUAL_TEMPLATE_NOTE = MANUAL_TEMPLATE_NOTE;
+exports.MAX_WIDTH_NOTE = MAX_WIDTH_NOTE;
+exports.PREFIX_ATTR = PREFIX_ATTR;
+exports.SUFFIX_ATTR = SUFFIX_ATTR;
+exports.TOGGLE_ELEMENT = TOGGLE_ELEMENT;
+exports.stylePatterns = stylePatterns;

package/schematics/migrations/button-truncation/index.cjs

@@ -0,0 +1,270 @@
+'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_buttonTruncation_data = require('./data.cjs');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+const TS_EXT = '.ts';
+const HTML_EXT = '.html';
+const STYLE_EXTS = ['.scss', '.css', '.less'];
+function applyEdits(content, edits) {
+    const sorted = [...edits].sort((a, b) => b.start - a.start || b.end - a.end);
+    let result = content;
+    for (const { start, end, text } of sorted) {
+        result = result.slice(0, start) + text + result.slice(end);
+    }
+    return result;
+}
+/** An attribute name as written, with the binding brackets stripped: `[disabled]` → `disabled`. */
+const attrName = (attr) => attr.name.replace(/[[\]()]/g, '');
+const hasAttr = (node, name) => !!node.attrs?.some((attr) => attrName(attr) === name);
+/**
+ * Node kinds are told apart by the field each one carries, not by the start span: a block (`@if`, `@for`)
+ * has a name and a start span just like an element does, and would otherwise be mistaken for one.
+ */
+const isElement = (node) => Array.isArray(node.attrs);
+const isBlock = (node) => !isElement(node) && Array.isArray(node.children);
+const isText = (node) => !isElement(node) && Array.isArray(node.tokens);
+/** A node that projects nothing: a comment, or text that is only the template's own indentation. */
+const isInsignificant = (node) => {
+    if (isElement(node) || isBlock(node))
+        return false;
+    // a comment has a `value` but no tokens, unlike a text node
+    return isText(node) ? (node.value ?? '').trim() === '' : typeof node.value === 'string';
+};
+const isIcon = (node) => isElement(node) && migrations_buttonTruncation_data.ICON_ATTRS.some((name) => hasAttr(node, name));
+const isButtonHost = (node) => isElement(node) && (hasAttr(node, migrations_buttonTruncation_data.BUTTON_ATTR) || node.name === migrations_buttonTruncation_data.TOGGLE_ELEMENT);
+/**
+ * The nodes a button actually projects, with a single-element block unwrapped to the element it renders.
+ *
+ * `@if (showIcon()) { <i kbq-icon></i> }` is the ordinary way to make an icon conditional, and the block's
+ * position among the children still tells which side of the label it is on — so it can be marked. A block
+ * holding more than one element cannot: which of them ends up at the edge is a runtime question.
+ */
+function projectedNodes(host) {
+    const nodes = [];
+    let ambiguous = false;
+    for (const child of host.children ?? []) {
+        if (isInsignificant(child))
+            continue;
+        if (isBlock(child)) {
+            const inner = (child.children ?? []).filter((node) => !isInsignificant(node));
+            if (inner.length === 1 && isElement(inner[0])) {
+                nodes.push(inner[0]);
+            }
+            else if (inner.length > 0) {
+                nodes.push(child);
+                ambiguous = true;
+            }
+            continue;
+        }
+        nodes.push(child);
+    }
+    return { nodes, ambiguous };
+}
+/** Offset just after the tag name, i.e. where a new attribute is inserted. */
+function attributeInsertOffset(element) {
+    const firstAttr = element.attrs?.find((attr) => attr.keySpan?.start.offset !== undefined);
+    if (firstAttr)
+        return firstAttr.keySpan.start.offset;
+    const start = element.startSourceSpan?.start.offset;
+    return start === undefined ? undefined : start + 1 + (element.name?.length ?? 0);
+}
+/** Collects every button host in a template, blocks included. */
+class ButtonHostCollector {
+    constructor() {
+        this.hosts = [];
+    }
+    visitElement(el) {
+        if (isButtonHost(el))
+            this.hosts.push(el);
+        this.visitChildren(el);
+    }
+    visitChildren(el) {
+        for (const child of el.children ?? []) {
+            child.visit(this);
+        }
+    }
+    visitBlock(block) {
+        this.visitChildren(block);
+    }
+    visitAttribute() { }
+    visitText() { }
+    visitComment() { }
+    visitExpansion() { }
+    visitExpansionCase() { }
+    visitBlockParameter() { }
+    visitLetDeclaration() { }
+}
+/**
+ * Marks the outermost icons of every button in a template with the slot they belong to.
+ *
+ * Only an icon that sits next to a label is marked: a button whose whole content is icons has nothing to
+ * truncate, and the markers would only add noise.
+ */
+async function migrateTemplate(template) {
+    if (!template.includes(migrations_buttonTruncation_data.BUTTON_ATTR) && !template.includes(migrations_buttonTruncation_data.TOGGLE_ELEMENT)) {
+        return { content: template, changed: false, manual: false };
+    }
+    const parsed = await utils_typescript.parseTemplate(template);
+    if (!parsed.tree)
+        return { content: template, changed: false, manual: false };
+    const collector = new ButtonHostCollector();
+    utils_ast.visitAll(collector, parsed.tree.rootNodes);
+    const edits = [];
+    let manual = false;
+    for (const host of collector.hosts) {
+        const { nodes, ambiguous } = projectedNodes(host);
+        manual ||= ambiguous;
+        // nothing beside the icons, so nothing to keep them out of
+        if (nodes.length < 2 || nodes.every(isIcon))
+            continue;
+        for (const [node, marker] of [
+            [nodes[0], migrations_buttonTruncation_data.PREFIX_ATTR],
+            [nodes[nodes.length - 1], migrations_buttonTruncation_data.SUFFIX_ATTR]
+        ]) {
+            if (!isIcon(node) || hasAttr(node, migrations_buttonTruncation_data.PREFIX_ATTR) || hasAttr(node, migrations_buttonTruncation_data.SUFFIX_ATTR))
+                continue;
+            const offset = attributeInsertOffset(node);
+            if (offset === undefined)
+                continue;
+            edits.push({ start: offset, end: offset, text: `${marker} ` });
+        }
+    }
+    return { content: applyEdits(template, edits), changed: edits.length > 0, manual };
+}
+/** Interior `[start, end]` ranges of inline `@Component({ template: '…' })` string literals. */
+function collectInlineTemplateRanges(sourceFile) {
+    const ranges = [];
+    utils_typescript.forEachClass(sourceFile, (node) => {
+        const decorator = ts
+            .getDecorators(node)
+            ?.find((dec) => ts.isCallExpression(dec.expression) &&
+            ts.isIdentifier(dec.expression.expression) &&
+            dec.expression.expression.text === 'Component');
+        if (!decorator || !ts.isCallExpression(decorator.expression))
+            return;
+        const [arg] = decorator.expression.arguments;
+        if (!arg || !ts.isObjectLiteralExpression(arg))
+            return;
+        for (const prop of arg.properties) {
+            if (ts.isPropertyAssignment(prop) &&
+                (ts.isIdentifier(prop.name) || ts.isStringLiteralLike(prop.name)) &&
+                prop.name.text === 'template' &&
+                ts.isStringLiteralLike(prop.initializer) &&
+                prop.initializer.text) {
+                // +1 / -1 to exclude the opening/closing quote characters.
+                ranges.push({ start: prop.initializer.getStart(sourceFile) + 1, end: prop.initializer.getEnd() - 1 });
+            }
+        }
+    });
+    return ranges;
+}
+async function migrateInlineTemplates(content, fileName) {
+    const sourceFile = ts.createSourceFile(fileName, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const ranges = collectInlineTemplateRanges(sourceFile).sort((a, b) => b.start - a.start);
+    let result = content;
+    let manual = false;
+    for (const { start, end } of ranges) {
+        const migrated = await migrateTemplate(result.slice(start, end));
+        manual ||= migrated.manual;
+        if (migrated.changed) {
+            result = result.slice(0, start) + migrated.content + result.slice(end);
+        }
+    }
+    return { content: result, manual };
+}
+/** Reports stylesheet overrides that the layout change affects. Never rewrites them. */
+function warnStyles(context, filePath, content) {
+    let found = false;
+    for (const { selector, pattern, message } of migrations_buttonTruncation_data.stylePatterns) {
+        if (new RegExp(pattern).test(content)) {
+            found = true;
+            utils_messages.logMessage(context.logger, [`[button-truncation] ${filePath} overrides ${selector}`, `  ${message}`]);
+        }
+    }
+    return found;
+}
+function buttonTruncation(options) {
+    return async (tree, context) => {
+        const { project } = options;
+        // `ng update` invokes migrations with no options at all, and migrations.json declares no schema, so the
+        // schema default never reaches us — applying the fix is the intended behaviour there.
+        const fix = options.fix ?? true;
+        const projectDefinition = await utils_packageConfig.setupOptions(project, tree);
+        const root = projectDefinition?.root ?? '';
+        const rootDir = root ? tree.getDir(root) : tree.root;
+        const tsPaths = [];
+        const htmlPaths = [];
+        const stylePaths = [];
+        utils_projectFiles.visitProjectFiles(rootDir, (filePath) => {
+            if (filePath.endsWith(TS_EXT))
+                tsPaths.push(filePath);
+            else if (filePath.endsWith(HTML_EXT))
+                htmlPaths.push(filePath);
+            else if (STYLE_EXTS.some((ext) => filePath.endsWith(ext)))
+                stylePaths.push(filePath);
+        });
+        let touched = 0;
+        let manual = false;
+        let styleFindings = 0;
+        const commit = (filePath, original, updated) => {
+            if (updated === original)
+                return;
+            touched++;
+            if (fix) {
+                tree.overwrite(filePath, updated);
+            }
+            else {
+                utils_messages.logMessage(context.logger, [
+                    `[button-truncation] would update ${filePath} (run with --fix to apply)`
+                ]);
+            }
+        };
+        for (const filePath of tsPaths) {
+            const original = tree.read(filePath)?.toString();
+            if (!original)
+                continue;
+            const migrated = await migrateInlineTemplates(original, filePath);
+            manual ||= migrated.manual;
+            // a `styles: [...]` block lives in the same file, so stylesheets are looked for here too
+            if (warnStyles(context, filePath, original))
+                styleFindings++;
+            commit(filePath, original, migrated.content);
+        }
+        for (const filePath of htmlPaths) {
+            const original = tree.read(filePath)?.toString();
+            if (!original)
+                continue;
+            const migrated = await migrateTemplate(original);
+            manual ||= migrated.manual;
+            if (migrated.changed)
+                commit(filePath, original, migrated.content);
+        }
+        for (const filePath of stylePaths) {
+            const original = tree.read(filePath)?.toString();
+            if (!original)
+                continue;
+            if (warnStyles(context, filePath, original))
+                styleFindings++;
+        }
+        if (manual)
+            utils_messages.logMessage(context.logger, [`[button-truncation] ${migrations_buttonTruncation_data.MANUAL_TEMPLATE_NOTE}`]);
+        utils_messages.logMessage(context.logger, migrations_buttonTruncation_data.MAX_WIDTH_NOTE.map((line) => `[button-truncation] ${line}`));
+        utils_messages.logMessage(context.logger, [
+            `[button-truncation] processed tree under "${root || '<workspace root>'}", ` +
+                `${fix ? 'updated' : 'would update'} ${touched} file(s), ` +
+                `${styleFindings} stylesheet(s) need a manual review.`
+        ]);
+    };
+}
+
+exports.default = buttonTruncation;

package/schematics/migrations/button-truncation/schema.json

@@ -0,0 +1,20 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-button-truncation",
+    "title": "Koobiq components button truncation 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, moves edge icons into the kbqButtonPrefix/kbqButtonSuffix slots. When false, prints what would change without writing. Stylesheet findings are always reported, never rewritten."
+        }
+    }
+}

package/schematics/migrations/checkbox-signals/README.md

@@ -0,0 +1,76 @@
+# checkbox-signals
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21` (registered for
+`21.0.0-0`). Migrates `KbqCheckbox` consumers to its signal-based one-way inputs and reports the
+members the review closed.
+
+## Background
+
+`id` and `clickAction` were the two inputs the automated signal migration skipped, because
+application code writes to them. Both are `input()` now, and `id` is generated by the CDK
+`_IdGenerator` instead of a module-level counter.
+
+## What stays an accessor input
+
+`checked`, `disabled`, `indeterminate` and `tabIndex` are two-way state: the component writes them on
+click and the `ControlValueAccessor` writes them through the `KbqCheckable` host directive. A
+`model()` cannot carry the `booleanAttribute` / `numberAttribute` transform they need, so they stay
+accessor inputs over `KbqCheckable`'s signals — the shape the reviewed `KbqButtonToggle` settled on.
+**Reads and writes of those four are unchanged in TypeScript**, and the schematic does not touch them.
+A template binding is coerced now, though: `booleanAttribute` maps `0`, `''` and `NaN` to `true`, and
+the accepted template type widens to `unknown`, so `[checked]="items.length"` on an empty list reads as
+checked and a binding that used to fail `strictTemplates` is accepted.
+
+## What it rewrites
+
+| Before                   | After                      |
+| ------------------------ | -------------------------- |
+| `checkbox.id`            | `checkbox.id()`            |
+| `checkbox.clickAction`   | `checkbox.clickAction()`   |
+| `checkbox.big`           | `checkbox.big()`           |
+| `checkbox.required`      | `checkbox.required()`      |
+| `checkbox.value`         | `checkbox.value()`         |
+| `checkbox.name`          | `checkbox.name()`          |
+| `checkbox.labelPosition` | `checkbox.labelPosition()` |
+
+Both on receivers explicitly typed `KbqCheckbox` and through template reference variables on
+`<kbq-checkbox>`, in external and inline templates. Already-migrated reads are left alone, so the
+schematic is idempotent.
+
+## What it does _not_ do
+
+| Pattern                                                        | Manual migration                                           |
+| -------------------------------------------------------------- | ---------------------------------------------------------- |
+| `checkbox.id = …` / `checkbox.clickAction = …`                 | Bind `[id]` / `[clickAction]` — the inputs are read-only   |
+| `.inputId` / `.inputElement` / `.getAriaChecked`               | Now `protected`; use `focus()` and `toggle()`              |
+| `.onInputClick` / `.onInteractionEvent` / `.onLabelTextChange` | Now `protected` template handlers                          |
+| `viewChild(KbqCheckbox)`                                       | The query returns the instance, so a read is a double call |
+
+`[clickAction]="undefined"` explicitly **overrides** `KBQ_CHECKBOX_CLICK_ACTION` rather than falling
+back to it — leave the input unbound to use the token. That was true of the decorator input too, but
+it is easy to reach for when converting a field write into a binding.
+
+## Notes with no call site to point at
+
+- **Generated ids come from the CDK `_IdGenerator`.** The shape is unchanged for a default `APP_ID` -
+  the CDK omits the app id unless it was overridden - but the counter is 0-based and shared per prefix,
+  so the first checkbox is `kbq-checkbox-0` where it used to be `kbq-checkbox-1`. An assertion on an
+  exact id needs updating; one matching the shape does not.
+- **`<kbq-checkbox [id]="null">` falls back to the generated id on the host too.** It used to leave
+  the host without an id while the hidden input still pointed its `for` at the generated one.
+- **`checked`, `big` and `indeterminate` are `booleanAttribute` inputs.** `<kbq-checkbox checked>`
+  used to pass the empty string, which is falsy, so the valueless attribute did nothing.
+- **`required` defaults to `false`** instead of `undefined` behind a `boolean` type, and **`value`
+  reports `string | undefined`** instead of `string` over an `undefined!` default.
+
+- **An enabled `<kbq-checkbox>` no longer carries `disabled="false"` on its host.** The host binding
+  rendered the boolean verbatim, so every enabled checkbox shipped the attribute — enough for a
+  consumer stylesheet or test selector written as `kbq-checkbox[disabled]` to match all of them.
+
+## Running it manually
+
+```
+ng generate @koobiq/components:checkbox-signals --project my-app
+```
+
+Pass `--fix=false` to see what it would change without writing.

package/schematics/migrations/checkbox-signals/data.cjs

@@ -0,0 +1,114 @@
+'use strict';
+
+/**
+ * Data for the `checkbox-signals` migration.
+ *
+ * The one-way inputs became signals; `id` and `clickAction` are the two the automated migration skipped,
+ * because application code writes to them.
+ *
+ * - `checkbox.id` / `clickAction` / `big` / `required` / `value` / `name` / `labelPosition` → calls (auto-fixed)
+ * - the template plumbing (`inputId`, `inputElement`, `getAriaChecked`, the click handlers) → `protected` (warn)
+ *
+ * `checked`, `disabled`, `indeterminate` and `tabIndex` stay accessor inputs over the signals of the
+ * `KbqCheckable` host directive: they are two-way state that the component and the `ControlValueAccessor`
+ * both write, and a `model()` cannot carry the `booleanAttribute` / `numberAttribute` transform they need.
+ * That is the shape the reviewed `KbqButtonToggle` settled on. Reads and writes of those four are unchanged.
+ */
+/** Members of `KbqCheckbox` whose value is unchanged; a read must become a call. Auto-fixed. */
+const SIGNAL_MEMBERS = [
+    'id',
+    'clickAction',
+    'big',
+    'required',
+    'value',
+    'name',
+    'labelPosition'
+];
+/** 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']);
+/** `exportAs` name a template reference has to carry to be the checkbox rather than some other directive. */
+const CHECKBOX_EXPORT_AS = 'kbqCheckbox';
+/** TypeScript type annotation that marks a receiver as a checkbox. */
+const CHECKBOX_TYPE = 'KbqCheckbox';
+/** Element selector whose template reference variables (`#ref`) point at a checkbox. */
+const CHECKBOX_ELEMENT = 'kbq-checkbox';
+/** Import specifier that marks a file as a checkbox consumer. */
+const CHECKBOX_PACKAGE = '@koobiq/components/checkbox';
+/** Members that moved out of the public surface and can no longer be reached from outside the component. */
+const PROTECTED_MEMBERS = [
+    'inputId',
+    'inputElement',
+    'getAriaChecked',
+    'onInputClick',
+    'onInteractionEvent',
+    'onLabelTextChange'
+];
+/**
+ * Reported for a programmatic write. Emitted from the AST pass rather than a regex: the old pattern was
+ * anchored only on `KbqCheckbox` appearing somewhere in the file, so `el.id = 'x'` on an `HTMLElement`
+ * warned, and a genuine write at the very end of a file did not.
+ */
+const writeMessage = (members) => `These are read-only signal inputs now, so a programmatic write no longer compiles: ` +
+    `${[...members].join(', ')}. Bind them in the template instead. Note that binding ` +
+    '`[clickAction]="undefined"` explicitly overrides the KBQ_CHECKBOX_CLICK_ACTION token rather than ' +
+    'falling back to it - leave the input unbound to use the token.';
+/**
+ * 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, so the decorator form - which the rewrite handles
+ * correctly on its own - is never told it needs two calls.
+ *
+ * `viewChild()` without `.required` is typed `Signal<KbqCheckbox | 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.checkbox()${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 checkbox but cannot be parsed, so nothing in it was inspected. */
+const UNPARSEABLE_TEMPLATE_MESSAGE = 'This template renders <kbq-checkbox> but could not be parsed, so it was left untouched. Migrate reads ' +
+    'through its template reference variables by hand.';
+/**
+ * Reported when a file names `KbqCheckbox` 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 = 'KbqCheckbox 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 for the members that left the public surface, in both the TypeScript and the template pass. */
+const protectedMessage = (members) => `These KbqCheckbox members are \`protected\` now and can't be read from outside the component: ` +
+    `${[...members].join(', ')}. They are the wiring between the label, the visually hidden native input ` +
+    'and the click algorithm. Use `focus()` and `toggle()`, or drive the checkbox through its inputs.';
+/** Printed once per project, after the per-file reports. */
+const SUMMARY = [
+    '  Generated ids come from the CDK `_IdGenerator`. The shape is unchanged for a default `APP_ID` - the ' +
+        'CDK omits the app id unless it was overridden - but the counter is 0-based and shared per prefix, ' +
+        'so the first checkbox is `kbq-checkbox-0` where it used to be `kbq-checkbox-1`. An assertion on an ' +
+        'exact id needs updating; one matching the shape does not.',
+    '  `<kbq-checkbox [id]="null">` now falls back to the generated id on the host as well. It used to leave ' +
+        'the host without an id while the hidden input still pointed its `for` at the generated one.',
+    '  `checked`, `big` and `indeterminate` are `booleanAttribute` inputs, and `required` defaults to `false` ' +
+        'instead of `undefined` behind a `boolean` type. `<kbq-checkbox checked>` used to pass the empty ' +
+        'string, which is falsy, so the valueless attribute did nothing; it checks the box now. The same ' +
+        'coercion runs on a bound value, so `[checked]="items.length"` with an empty list, `[checked]="0"` ' +
+        'and `NaN` now read as true - and the template type is `unknown`, so a binding that used to be a ' +
+        'compile error under strictTemplates is accepted and reads as true.',
+    '  `value` reports `string | undefined` instead of `string`. It was declared non-nullable over an ' +
+        '`undefined!` default, so an unbound checkbox always handed back `undefined`.',
+    '  An enabled <kbq-checkbox> no longer carries `disabled="false"` on its host. The host binding ' +
+        'rendered the boolean verbatim, so every enabled checkbox shipped the attribute — enough for a ' +
+        'consumer stylesheet or test selector written as `kbq-checkbox[disabled]` to match all of them.'
+];
+
+exports.CHECKBOX_ELEMENT = CHECKBOX_ELEMENT;
+exports.CHECKBOX_EXPORT_AS = CHECKBOX_EXPORT_AS;
+exports.CHECKBOX_PACKAGE = CHECKBOX_PACKAGE;
+exports.CHECKBOX_TYPE = CHECKBOX_TYPE;
+exports.PROTECTED_MEMBERS = PROTECTED_MEMBERS;
+exports.SIGNAL_API_METHODS = SIGNAL_API_METHODS;
+exports.SIGNAL_MEMBERS = SIGNAL_MEMBERS;
+exports.SUMMARY = SUMMARY;
+exports.UNPARSEABLE_TEMPLATE_MESSAGE = UNPARSEABLE_TEMPLATE_MESSAGE;
+exports.UNRESOLVED_RECEIVER_MESSAGE = UNRESOLVED_RECEIVER_MESSAGE;
+exports.protectedMessage = protectedMessage;
+exports.signalQueryMessage = signalQueryMessage;
+exports.writeMessage = writeMessage;