@koobiq/components 20.4.1 → 21.0.0

package/schematics/migrations/divider-signals-and-aria/README.md

@@ -0,0 +1,47 @@
+# divider-signals-and-aria
+
+Migration schematic invoked automatically by `ng update @koobiq/components`.
+Reports what the divider review changed for a consumer: the two inputs that became signals, and the
+separator semantics the component now renders itself. It never writes to the tree.
+
+It reads `.ts` and `.html`. In TypeScript it resolves the receiver's declared type before reporting
+anything, so only a member access on something annotated `KbqDivider` counts — `vertical` and
+`paddings` are ordinary property names, and a file that renders a divider is very likely to contain
+unrelated ones. Declarations of other types are tracked too, so an inner one shadowing a divider
+receiver is seen to shadow it. The trade is that the type has to be written down: a receiver whose
+type is only inferred is not recognised.
+
+## Background
+
+| Member / behaviour  | Before        | After                                        |
+| ------------------- | ------------- | -------------------------------------------- |
+| `vertical`          | accessor pair | `InputSignalWithTransform<boolean, unknown>` |
+| `paddings`          | accessor pair | `InputSignalWithTransform<boolean, unknown>` |
+| `decorative`        | —             | new input, renders `role="presentation"`     |
+| separator semantics | none          | `role="separator"` + `aria-orientation`      |
+
+Both inputs kept their names, so `[vertical]` and `[paddings]` bindings are unchanged; only TypeScript
+that reads or writes them through a component reference is affected.
+
+## What it does _not_ do
+
+Nothing is rewritten. A read of a signal input becomes a call, a write becomes a template binding, and
+whether a duplicated `role` should be deleted or replaced by `decorative` depends on what the divider
+is for.
+
+| Pattern                              | Manual migration                                                      |
+| ------------------------------------ | --------------------------------------------------------------------- |
+| `.vertical = …` / `.paddings = …`    | Bind `[vertical]` / `[paddings]` — a signal input takes no assignment |
+| `.vertical` / `.paddings`            | Read them as calls                                                    |
+| `<kbq-divider role="…">`             | Drop it; the component renders `role="separator"`                     |
+| `<kbq-divider aria-orientation="…">` | Drop it; it follows `vertical`                                        |
+| `<kbq-divider aria-hidden="true">`   | Still honoured; `decorative` says the same thing through the input    |
+
+A comparison (`d.vertical === true`) is reported as a read, not a write. It keeps compiling after the
+migration and quietly compares against the signal itself, so it is the case most worth looking at.
+
+## Running it manually
+
+```
+ng generate @koobiq/components:divider-signals-and-aria --project my-app
+```

package/schematics/migrations/divider-signals-and-aria/data.js

@@ -0,0 +1,62 @@
+'use strict';
+
+/**
+ * Data for the `divider-signals-and-aria` migration.
+ *
+ * The divider review changed two things a consumer can notice:
+ *
+ * - `vertical` and `paddings` are signal inputs instead of accessor pairs, so a read is a call and a
+ *   write is a template binding. Both kept their names, so no template needs migrating.
+ * - The host carries `role="separator"` and, when vertical, `aria-orientation="vertical"`, with a
+ *   `decorative` input that swaps to `role="presentation"`. Hand-rolled attributes are duplicates.
+ *
+ * Warn-only. A read that becomes a call and a hand-rolled attribute that becomes a duplicate are both
+ * decisions about the call site, not rewrites that can be derived from it.
+ */
+/** Import specifier that marks a file as a divider consumer. */
+const DIVIDER_PACKAGE = '@koobiq/components/divider';
+/** The class a receiver has to be annotated with for its member access to be a divider's. */
+const DIVIDER_TYPE_NAME = 'KbqDivider';
+/** Identifier and element shapes that mark a file worth parsing at all. */
+const DIVIDER_TYPE = '\\bKbqDivider\\w*\\b|\\bkbq-divider\\b';
+/** The inputs that stopped being accessor pairs. */
+const SIGNAL_INPUTS = ['vertical', 'paddings'];
+const WRITE_MESSAGE = 'KbqDivider.vertical and KbqDivider.paddings are signal inputs and take no assignment. Bind ' +
+    '[vertical] / [paddings] in the template instead; both kept their names, so the binding itself ' +
+    'is unchanged.';
+const READ_MESSAGE = 'KbqDivider.vertical and KbqDivider.paddings are signal-backed: read them as calls, ' +
+    'divider.vertical() and divider.paddings().';
+/**
+ * Template warnings. The element name carries the scope here, so unlike the member access on the
+ * TypeScript side these need no receiver to resolve — the attribute is on `<kbq-divider>` or it is not.
+ */
+const templateWarnPatterns = [
+    {
+        pattern: '<kbq-divider[^>]*\\b(?:role|aria-orientation)\\s*=',
+        message: 'kbq-divider renders role="separator" itself, plus aria-orientation="vertical" when vertical, ' +
+            'so a hand-rolled role or aria-orientation on the element is a duplicate. Drop it, or set ' +
+            '`decorative` for a divider that only repeats a boundary the layout already conveys.'
+    },
+    {
+        pattern: '<kbq-divider[^>]*\\baria-hidden\\s*=',
+        message: 'A hand-rolled aria-hidden on kbq-divider still works and is left alone, but `decorative` says ' +
+            'the same thing through the component: it renders role="presentation" instead of "separator".'
+    }
+];
+/** Printed once per project, after the per-file reports. */
+const SUMMARY = [
+    '  Both inputs kept their names, so [vertical] and [paddings] bindings are unchanged - only ' +
+        'TypeScript that reads or writes them through a component reference is affected.',
+    '  The host renders role="separator", and aria-orientation="vertical" when vertical, so a ' +
+        'hand-rolled one on the element is a duplicate. A divider that only repeats a boundary the ' +
+        'layout already conveys should set decorative instead.'
+];
+
+exports.DIVIDER_PACKAGE = DIVIDER_PACKAGE;
+exports.DIVIDER_TYPE = DIVIDER_TYPE;
+exports.DIVIDER_TYPE_NAME = DIVIDER_TYPE_NAME;
+exports.READ_MESSAGE = READ_MESSAGE;
+exports.SIGNAL_INPUTS = SIGNAL_INPUTS;
+exports.SUMMARY = SUMMARY;
+exports.WRITE_MESSAGE = WRITE_MESSAGE;
+exports.templateWarnPatterns = templateWarnPatterns;

package/schematics/migrations/divider-signals-and-aria/index.js

@@ -0,0 +1,211 @@
+'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 migrations_dividerSignalsAndAria_data = require('./data.js');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+const LABEL = '[divider-signals-and-aria]';
+const TS_EXT = '.ts';
+const HTML_EXT = '.html';
+/** A file is worth parsing if it imports the package, names the component, or renders one. */
+function referencesDivider(content) {
+    return content.includes(migrations_dividerSignalsAndAria_data.DIVIDER_PACKAGE) || new RegExp(migrations_dividerSignalsAndAria_data.DIVIDER_TYPE).test(content);
+}
+const isFunctionLike = (node) => ts.isFunctionDeclaration(node) ||
+    ts.isMethodDeclaration(node) ||
+    ts.isConstructorDeclaration(node) ||
+    ts.isArrowFunction(node) ||
+    ts.isFunctionExpression(node) ||
+    ts.isGetAccessorDeclaration(node) ||
+    ts.isSetAccessorDeclaration(node);
+/** Nodes that confine a `let`/`const` declared inside them. */
+const isBlockScopeContainer = (node) => ts.isBlock(node) ||
+    ts.isSourceFile(node) ||
+    ts.isModuleBlock(node) ||
+    ts.isCaseBlock(node) ||
+    ts.isForStatement(node) ||
+    ts.isForInStatement(node) ||
+    ts.isForOfStatement(node);
+const FIELD_MODIFIERS = new Set([
+    ts.SyntaxKind.PrivateKeyword,
+    ts.SyntaxKind.PublicKeyword,
+    ts.SyntaxKind.ProtectedKeyword,
+    ts.SyntaxKind.ReadonlyKeyword
+]);
+/** Walks up from `node` to the nearest ancestor matching `predicate`. */
+function findAncestor(node, predicate) {
+    let current = node.parent;
+    while (current) {
+        if (predicate(current))
+            return current;
+        current = current.parent;
+    }
+    return undefined;
+}
+/** Whether a type annotation names `KbqDivider`. Explicit annotations only — no cross-package resolution. */
+const isDividerType = (type) => !!type &&
+    ts.isTypeReferenceNode(type) &&
+    ts.isIdentifier(type.typeName) &&
+    type.typeName.text === migrations_dividerSignalsAndAria_data.DIVIDER_TYPE_NAME;
+/**
+ * Scope a local is visible in: a `let`/`const` is confined to its nearest block, a `var` to the whole
+ * function. Giving a block-scoped local the whole function would let an access elsewhere match it even
+ * where the name refers to a different, shadowing declaration.
+ */
+function variableScope(node, sourceFile) {
+    const blockScoped = !!(node.parent.flags & ts.NodeFlags.BlockScoped);
+    return findAncestor(node, blockScoped ? isBlockScopeContainer : isFunctionLike) ?? sourceFile;
+}
+/**
+ * Collects the receivers annotated `KbqDivider` — method/function params, class fields (including
+ * `@ViewChild(KbqDivider) x!: KbqDivider` and constructor parameter-properties) and typed locals.
+ *
+ * `vertical` and `paddings` are ordinary property names that plenty of unrelated objects carry, so the
+ * receiver is what makes an access the divider's. Params and locals of any other type are collected as
+ * well, so that a nested declaration reusing the name is seen to shadow the divider one.
+ */
+function collectReceivers(sourceFile) {
+    const receivers = [];
+    const add = (text, scope, isDivider) => receivers.push({ text, start: scope.getStart(sourceFile), end: scope.getEnd(), isDivider });
+    const visit = (node) => {
+        if (ts.isParameter(node) && ts.isIdentifier(node.name)) {
+            const isDivider = isDividerType(node.type);
+            add(node.name.text, findAncestor(node, isFunctionLike) ?? sourceFile, isDivider);
+            // A constructor parameter-property is also a class field, reachable as `this.<name>`.
+            if (isDivider && node.modifiers?.some((modifier) => FIELD_MODIFIERS.has(modifier.kind))) {
+                const owner = findAncestor(node, ts.isClassDeclaration);
+                if (owner)
+                    add(`this.${node.name.text}`, owner, true);
+            }
+        }
+        else if (ts.isPropertyDeclaration(node) && ts.isIdentifier(node.name)) {
+            const owner = isDividerType(node.type) && findAncestor(node, ts.isClassDeclaration);
+            if (owner)
+                add(`this.${node.name.text}`, owner, true);
+        }
+        else if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name)) {
+            add(node.name.text, variableScope(node, sourceFile), isDividerType(node.type));
+        }
+        node.forEachChild(visit);
+    };
+    visit(sourceFile);
+    return receivers;
+}
+/**
+ * Whether a property access resolves to a divider receiver. The innermost enclosing declaration wins: a
+ * nested param or local shadows an outer one of the same name.
+ */
+function isDividerAccess(node, sourceFile, receivers) {
+    const receiverText = node.expression.getText(sourceFile);
+    const start = node.getStart(sourceFile);
+    const end = node.getEnd();
+    let innermost;
+    for (const receiver of receivers) {
+        if (receiver.text !== receiverText || start < receiver.start || end > receiver.end)
+            continue;
+        if (!innermost || receiver.start > innermost.start)
+            innermost = receiver;
+    }
+    return !!innermost?.isDivider;
+}
+/**
+ * Whether the access is the target of an assignment — plain (`=`) or compound (`+=`, `||=`, `??=`, ...).
+ * Asking the AST rather than the operator's spelling is what keeps a comparison (`===`) on the read side,
+ * where it belongs: it stays legal after the migration and silently compares against the signal itself.
+ */
+function isAssignmentTarget(node) {
+    const parent = node.parent;
+    if (ts.isBinaryExpression(parent) && parent.left === node) {
+        // The assignment operators are contiguous in `SyntaxKind` and the comparisons sit well below
+        // them, so the range covers `=` through `??=` without catching `==` / `===` / `>=`.
+        const operator = parent.operatorToken.kind;
+        return operator >= ts.SyntaxKind.FirstAssignment && operator <= ts.SyntaxKind.LastAssignment;
+    }
+    return ((ts.isPostfixUnaryExpression(parent) || ts.isPrefixUnaryExpression(parent)) &&
+        (parent.operator === ts.SyntaxKind.PlusPlusToken || parent.operator === ts.SyntaxKind.MinusMinusToken));
+}
+/** The already-migrated shape — `divider.vertical()` needs no report. */
+const isCallee = (node) => ts.isCallExpression(node.parent) && node.parent.expression === node;
+/** Reports the member accesses that resolve to a `KbqDivider`, split into writes and reads. */
+function reportMemberAccess(context, filePath, content) {
+    const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true);
+    const receivers = collectReceivers(sourceFile);
+    let writes = false;
+    let reads = false;
+    const visit = (node) => {
+        if (ts.isPropertyAccessExpression(node) &&
+            migrations_dividerSignalsAndAria_data.SIGNAL_INPUTS.includes(node.name.text) &&
+            !isCallee(node) &&
+            isDividerAccess(node, sourceFile, receivers)) {
+            if (isAssignmentTarget(node))
+                writes = true;
+            else
+                reads = true;
+        }
+        node.forEachChild(visit);
+    };
+    visit(sourceFile);
+    let reported = 0;
+    for (const message of [writes ? migrations_dividerSignalsAndAria_data.WRITE_MESSAGE : undefined, reads ? migrations_dividerSignalsAndAria_data.READ_MESSAGE : undefined]) {
+        if (!message)
+            continue;
+        reported++;
+        utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${message}`]);
+    }
+    return reported;
+}
+/** Reports every pattern that matches, one line per pattern. */
+function reportPatterns(context, filePath, content, patterns) {
+    let reported = 0;
+    for (const { pattern, message } of patterns) {
+        if (!new RegExp(pattern).test(content))
+            continue;
+        reported++;
+        utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${message}`]);
+    }
+    return reported;
+}
+/**
+ * Reports the `KbqDivider` inputs that became signals, the hand-rolled separator attributes the component
+ * now renders itself. Never writes: a read becomes a call, a write becomes a binding, and whether a
+ * duplicate attribute should be deleted or replaced by `decorative` is a decision.
+ */
+function dividerSignalsAndAria(options) {
+    return async (tree, context) => {
+        const { project } = options;
+        const projectDefinition = await utils_packageConfig.setupOptions(project, tree);
+        const root = projectDefinition?.root ?? '';
+        const rootDir = root ? tree.getDir(root) : tree.root;
+        let consumers = 0;
+        let reported = 0;
+        utils_packageConfig.visitProjectFiles(rootDir, (filePath, entry) => {
+            const isTs = filePath.endsWith(TS_EXT);
+            const isHtml = filePath.endsWith(HTML_EXT);
+            if (!isTs && !isHtml)
+                return;
+            const content = entry?.content.toString();
+            if (!content || !referencesDivider(content))
+                return;
+            consumers++;
+            // An inline template lives in the `.ts` file, so the element patterns apply to both.
+            reported += reportPatterns(context, filePath, content, migrations_dividerSignalsAndAria_data.templateWarnPatterns);
+            if (isTs)
+                reported += reportMemberAccess(context, filePath, content);
+        });
+        // Nothing here renders a divider, so the summary would only be noise.
+        if (consumers === 0)
+            return;
+        utils_messages.logMessage(context.logger, [
+            `${LABEL} processed kbq-divider under "${root || '<workspace root>'}", ` +
+                `${consumers} file(s) reference the component, ${reported} report(s) emitted.`,
+            ...migrations_dividerSignalsAndAria_data.SUMMARY
+        ]);
+    };
+}
+
+exports.default = dividerSignalsAndAria;

package/schematics/migrations/divider-signals-and-aria/schema.json

@@ -0,0 +1,15 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-divider-signals-and-aria",
+    "title": "Koobiq components divider review migration",
+    "type": "object",
+    "properties": {
+        "project": {
+            "type": "string",
+            "description": "Name of the project to inspect. If omitted, the migration runs over the whole tree.",
+            "$default": {
+                "$source": "projectName"
+            }
+        }
+    }
+}

package/schematics/migrations/dl-attribute-coercion/README.md

@@ -0,0 +1,59 @@
+# dl-attribute-coercion
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21` (registered for
+`21.0.0-0`). Reports the `<kbq-dl>` attributes and bindings whose coercion changed. It never writes to
+the tree.
+
+## Background
+
+`KbqDlComponent` was already fully signal-based, so the review had nothing to migrate. What it found
+were the four inputs that never got a coercion transform, next to siblings that had one:
+
+```ts
+readonly verticalBreakpoint = input(400, { transform: numberAttribute });
+readonly dtMinWidth = input<number | undefined>();        // no transform
+readonly wide = input(false);                              // no transform
+```
+
+So `<kbq-dl wide>` passed the empty string — falsy — and the attribute did nothing, while
+`<kbq-dl resizable>` right next to it worked.
+
+`vertical` is tri-state: `null` means "decide from `verticalBreakpoint`". `booleanAttribute` would
+have folded that into `false`, so it uses a transform that preserves `null`.
+
+## What it does _not_ do
+
+Nothing is rewritten. Whether markup relied on a valueless `wide` being ignored is a decision the
+call site owns, and so is what a non-numeric width was meant to say.
+
+| Pattern                                      | Manual migration                                                       |
+| -------------------------------------------- | ---------------------------------------------------------------------- |
+| `<kbq-dl wide>` / `<kbq-dl wide="">`         | Remove it if the markup was relying on it being ignored                |
+| `<kbq-dl vertical>` / `<kbq-dl vertical="">` | Rewrite as `[vertical]="false"` — see below                            |
+| `wide="false"` / `vertical="false"`          | Meant true, means false now — drop the attribute to keep it true       |
+| `<kbq-dl dtMinWidth>` and the other widths   | A value that is not a finite number reports `undefined`, not `0`       |
+| `<kbq-dl dtWidth>`                           | Same, but its empty state is `null`; it also skipped the min clamp     |
+| `[wide]` / `[vertical]` / `[dtMinWidth]` …   | The bound value goes through the transform — check what it resolves to |
+
+`<kbq-dl vertical>` is the one that looks inert and is not. The untransformed input held `''`, which
+is not `null`, so the breakpoint branch never ran and the list stayed pinned horizontal. Deleting the
+attribute hands that decision back to `verticalBreakpoint`; `[vertical]="false"` preserves the
+behavior.
+
+A numeric literal is not reported: `Math.max` applies `ToNumber` to its arguments, so
+`<kbq-dl dtMinWidth="120">` produced `120` on either side of the change.
+
+## Notes with no call site to point at
+
+- `dtWidth` is an aliased input plus a `linkedSignal` and an explicit `dtWidthChange` output rather
+  than a `model()`, because `model()` takes no `transform`. `[(dtWidth)]` is unchanged; only code that
+  typed the member as `ModelSignal<number | null>` has to say `WritableSignal<number | null>`.
+- `dtMinWidth` and `ddMinWidth` report `number | undefined`, which is what an unbound
+  description list always held. A value that is not a finite number reads as `undefined` rather than
+  as `NaN`, so `?? fallback` at a call site fires.
+
+## Running it manually
+
+```
+ng generate @koobiq/components:dl-attribute-coercion --project my-app
+```

package/schematics/migrations/dl-attribute-coercion/data.js

@@ -0,0 +1,85 @@
+'use strict';
+
+/**
+ * Data for the `dl-attribute-coercion` migration.
+ *
+ * `KbqDlComponent` was already fully signal-based; the review found the four inputs that never got a
+ * coercion transform, so a static attribute reached them as a string and a binding reached them raw.
+ *
+ * - `<kbq-dl wide>` and `<kbq-dl wide="">` passed the empty string, which is falsy - the attribute did
+ *   nothing, and it means true now
+ * - `<kbq-dl wide="false">` passed a non-empty string, which is truthy - it meant true, and means false now
+ * - `vertical` is tri-state, so it keeps `null` through a transform that preserves it rather than
+ *   `booleanAttribute`, which would fold "decide from the breakpoint" into false
+ * - `dtMinWidth` and `ddMinWidth` reached the layout arithmetic as strings; a value that is
+ *   not a finite number now reads as `undefined` rather than reaching it at all
+ *
+ * Warn-only: every one of these is a template change, and which markup relied on the old reading is a
+ * decision the call site owns.
+ */
+/** Import specifier that marks a file as a description list consumer. */
+const DL_PACKAGE = '@koobiq/components/dl';
+/** Element selector of the description list. */
+const DL_ELEMENT = 'kbq-dl';
+/** Boolean-ish inputs that gained a coercion transform. */
+const BOOLEAN_ATTRIBUTES = ['wide', 'vertical'];
+/** Numeric inputs that gained a coercion transform. */
+const NUMERIC_ATTRIBUTES = ['dtMinWidth', 'ddMinWidth', 'dtWidth'];
+/** `dtWidth` is the one numeric input whose "no width" state is `null` rather than `undefined`. */
+const NULL_FALLBACK_ATTRIBUTES = ['dtWidth'];
+/**
+ * A static `wide` / `vertical` that used to be ignored, because the empty string is falsy. The advice
+ * differs per attribute: `wide` really was inert, while `vertical` pinned the horizontal layout by not
+ * being `null`, so deleting it hands the decision back to `verticalBreakpoint`.
+ */
+const falsyBooleanMessage = (attribute, line) => `Line ${line}: a valueless (or empty) \`${attribute}\` on <kbq-dl> used to pass the empty string, ` +
+    'which is falsy, so it did nothing. It is coerced now and the attribute means true. ' +
+    (attribute === 'vertical'
+        ? 'Write `[vertical]="false"` to keep the previous behavior: an unrecognised `vertical` was not ' +
+            '`null`, so the list stayed pinned horizontal and never switched at `verticalBreakpoint` - ' +
+            'deleting the attribute hands that decision back to the breakpoint.'
+        : 'Remove it if the markup was relying on it being ignored.');
+/** A static `wide="false"` / `vertical="false"`: a non-empty string, so it used to be truthy. */
+const truthyBooleanMessage = (attribute, value, line) => `Line ${line}: \`${attribute}="${value}"\` on <kbq-dl> used to pass a non-empty string, which is ` +
+    `truthy, so it meant *true*. It is coerced now, and \`booleanAttribute("${value}")\` is ` +
+    `${value === 'false' ? 'false' : 'true'}. This is the form whose meaning inverts.`;
+/** A static numeric attribute that is not a finite number: it used to reach the arithmetic as a string. */
+const numericAttributeMessage = (attribute, line) => {
+    const fallback = NULL_FALLBACK_ATTRIBUTES.includes(attribute) ? '`null`' : '`undefined`';
+    return (`Line ${line}: \`${attribute}\` on <kbq-dl> holds a value that is not a finite number. It used to ` +
+        `reach the layout arithmetic as a string, where \`Math.max(0, "")\` made it 0; it reports ${fallback} ` +
+        'now, and the layout falls back to the measured term width. A numeric literal behaves as before.' +
+        (NULL_FALLBACK_ATTRIBUTES.includes(attribute)
+            ? ' `dtWidth` also skipped the clamp against `dtMinWidth` entirely while it held a string, ' +
+                'so a column could render narrower than its own minimum.'
+            : ''));
+};
+/** A binding: the transform changes what the bound value means, with no compile error to point at it. */
+const boundAttributeMessage = (attributes, line) => `Line ${line}: ${[...attributes].map((name) => `\`[${name}]\``).join(', ')} on <kbq-dl> now runs the ` +
+    'bound value through a coercion. `[vertical]="undefined"` used to leave the input `undefined`, which ' +
+    'is not `null`, so the list stayed pinned horizontal; it is `null` now and the breakpoint decides. ' +
+    'On `wide`, every falsy non-boolean inverts: `0` and `""` were falsy and are `true` now. A numeric ' +
+    'binding that resolves to a non-number reads as `undefined` instead of reaching the arithmetic.';
+/** Reported when a template renders the element but cannot be parsed, so nothing in it was inspected. */
+const UNPARSEABLE_TEMPLATE_MESSAGE = 'This template renders <kbq-dl> but could not be parsed, so none of its attributes were inspected. ' +
+    'Check them by hand. If every template is reported this way, `@angular/compiler` could not be loaded ' +
+    'from this install.';
+/** Printed once per project, after the per-file reports. */
+const SUMMARY = [
+    '  `vertical` keeps `null` as its default - the state that lets the list decide from ' +
+        '`verticalBreakpoint` - so it is coerced with a transform that preserves null rather than with ' +
+        '`booleanAttribute`, which would have folded it into false.',
+    '  `dtMinWidth` and `ddMinWidth` report `number | undefined`. A value that is not a ' +
+        'finite number reads as `undefined` rather than as `NaN`, so `?? fallback` at a call site fires.'
+];
+
+exports.BOOLEAN_ATTRIBUTES = BOOLEAN_ATTRIBUTES;
+exports.DL_ELEMENT = DL_ELEMENT;
+exports.DL_PACKAGE = DL_PACKAGE;
+exports.NUMERIC_ATTRIBUTES = NUMERIC_ATTRIBUTES;
+exports.SUMMARY = SUMMARY;
+exports.UNPARSEABLE_TEMPLATE_MESSAGE = UNPARSEABLE_TEMPLATE_MESSAGE;
+exports.boundAttributeMessage = boundAttributeMessage;
+exports.falsyBooleanMessage = falsyBooleanMessage;
+exports.numericAttributeMessage = numericAttributeMessage;
+exports.truthyBooleanMessage = truthyBooleanMessage;

package/schematics/migrations/dl-attribute-coercion/index.js

@@ -0,0 +1,161 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var ts = require('typescript');
+var utils_ast = require('../../utils/ast.js');
+var utils_messages = require('../../utils/messages.js');
+var utils_packageConfig = require('../../package-config-BhU2TfC8.js');
+var utils_typescript = require('../../utils/typescript.js');
+var migrations_dlAttributeCoercion_data = require('./data.js');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+const LABEL = '[dl-attribute-coercion]';
+const TS_EXT = '.ts';
+const HTML_EXT = '.html';
+/** A file is a description list consumer if it renders the element or imports the package. */
+function referencesDl(content) {
+    return content.includes(`<${migrations_dlAttributeCoercion_data.DL_ELEMENT}`) || content.includes(migrations_dlAttributeCoercion_data.DL_PACKAGE);
+}
+/**
+ * The four attribute-name syntaxes that carry an Angular expression rather than a literal, with the
+ * bound name captured: `[x]`, `bind-x`, `[(x)]` and `bindon-x`.
+ *
+ * The HTML parser reports the name exactly as written, so the two-way forms have to be matched in
+ * full - stripping a leading `[` and a trailing `]` off `[(dtWidth)]` leaves `(dtWidth)`, which
+ * matches no input and was silently skipped.
+ */
+const BINDING_SYNTAX = /^(?:\[\(([^()\]]+)\)\]|\[([^\[\]]+)\]|bindon-(.+)|bind-(.+))$/;
+/**
+ * Walks a template's HTML AST collecting what changed meaning on every `<kbq-dl>`.
+ *
+ * An AST rather than a regular expression over the markup: the previous pattern matched the attribute
+ * names anywhere inside the opening tag, so `class="my-list vertical"` and `title="Very wide list"`
+ * were reported, `<kbq-dl-other wide>` matched on the unanchored element name, and an attribute value
+ * containing `>` cut the tag short and hid everything after it.
+ */
+class DlCollector {
+    constructor() {
+        this.findings = [];
+    }
+    visitElement(element) {
+        if (element.name === migrations_dlAttributeCoercion_data.DL_ELEMENT)
+            this.inspect(element);
+        this.visitChildren(element);
+    }
+    visitBlock(block) {
+        this.visitChildren(block);
+    }
+    visitChildren(node) {
+        utils_ast.visitAll(this, node.children ?? []);
+    }
+    visitAttribute() { }
+    visitText() { }
+    visitComment() { }
+    visitExpansion() { }
+    visitExpansionCase() { }
+    visitBlockParameter() { }
+    visitLetDeclaration() { }
+    inspect(element) {
+        const line = (element.startSourceSpan?.start.line ?? 0) + 1;
+        const bound = new Set();
+        for (const attr of element.attrs ?? []) {
+            if (typeof attr.name !== 'string')
+                continue;
+            const binding = BINDING_SYNTAX.exec(attr.name);
+            const name = binding ? (binding[1] ?? binding[2] ?? binding[3] ?? binding[4]) : attr.name;
+            const isBinding = binding !== null;
+            const value = typeof attr.value === 'string' ? attr.value : '';
+            if (!migrations_dlAttributeCoercion_data.BOOLEAN_ATTRIBUTES.includes(name) && !migrations_dlAttributeCoercion_data.NUMERIC_ATTRIBUTES.includes(name))
+                continue;
+            if (isBinding) {
+                bound.add(name);
+                continue;
+            }
+            if (migrations_dlAttributeCoercion_data.BOOLEAN_ATTRIBUTES.includes(name)) {
+                // The empty string covers both `wide` and `wide=""`: they are the same value, and the
+                // previous pattern reported the first while excluding the second.
+                this.findings.push(value === '' ? migrations_dlAttributeCoercion_data.falsyBooleanMessage(name, line) : migrations_dlAttributeCoercion_data.truthyBooleanMessage(name, value, line));
+                continue;
+            }
+            // A numeric literal reached the arithmetic as a string and coerced there, so it behaves
+            // exactly as before; only a value that is not a finite number changed meaning.
+            if (!Number.isFinite(Number(value === '' ? NaN : value))) {
+                this.findings.push(migrations_dlAttributeCoercion_data.numericAttributeMessage(name, line));
+            }
+        }
+        if (bound.size > 0)
+            this.findings.push(migrations_dlAttributeCoercion_data.boundAttributeMessage(bound, line));
+    }
+}
+/** Collects the findings of one template, or reports that it could not be parsed. */
+async function inspectTemplate(template) {
+    if (!template.includes(`<${migrations_dlAttributeCoercion_data.DL_ELEMENT}`))
+        return { findings: [], unparseable: false };
+    const parsed = await utils_typescript.parseTemplate(template);
+    if (!parsed.tree)
+        return { findings: [], unparseable: true };
+    const collector = new DlCollector();
+    utils_ast.visitAll(collector, parsed.tree.rootNodes);
+    return { findings: collector.findings, unparseable: false };
+}
+/** The same, over every inline template in a `.ts` file. */
+async function inspectInlineTemplates(content, fileName) {
+    const sourceFile = ts.createSourceFile(fileName, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const findings = [];
+    let unparseable = false;
+    for (const { start, end } of utils_typescript.collectInlineTemplateRanges(sourceFile)) {
+        const inspected = await inspectTemplate(content.slice(start, end));
+        findings.push(...inspected.findings);
+        unparseable ||= inspected.unparseable;
+    }
+    return { findings, unparseable };
+}
+/**
+ * Reports the `<kbq-dl>` attributes whose coercion changed. Never writes: whether markup relied on a
+ * valueless `wide` being ignored is a decision the call site owns, and so is what a non-numeric width
+ * was meant to say.
+ *
+ * Both `.ts` and `.html` are visited, because the element is written in templates of either kind.
+ */
+function dlAttributeCoercion(options) {
+    return async (tree, context) => {
+        const { project } = options;
+        const projectDefinition = await utils_packageConfig.setupOptions(project, tree);
+        const root = projectDefinition?.root ?? '';
+        const rootDir = root ? tree.getDir(root) : tree.root;
+        const paths = [];
+        utils_packageConfig.visitProjectFiles(rootDir, (filePath) => {
+            if (filePath.endsWith(TS_EXT) || filePath.endsWith(HTML_EXT))
+                paths.push(filePath);
+        });
+        let consumers = 0;
+        let reported = 0;
+        for (const filePath of paths) {
+            const content = tree.read(filePath)?.toString();
+            if (!content || !referencesDl(content))
+                continue;
+            consumers++;
+            const { findings, unparseable } = filePath.endsWith(HTML_EXT)
+                ? await inspectTemplate(content)
+                : await inspectInlineTemplates(content, filePath);
+            if (unparseable)
+                utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${migrations_dlAttributeCoercion_data.UNPARSEABLE_TEMPLATE_MESSAGE}`]);
+            for (const finding of findings) {
+                reported++;
+                utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${finding}`]);
+            }
+        }
+        // Nothing here uses the description list, so the summary would only be noise.
+        if (consumers === 0)
+            return;
+        utils_messages.logMessage(context.logger, [
+            `${LABEL} processed kbq-dl under "${root || '<workspace root>'}", ` +
+                `${consumers} file(s) reference the component, ${reported} attribute(s) reported.`,
+            ...migrations_dlAttributeCoercion_data.SUMMARY
+        ]);
+    };
+}
+
+exports.default = dlAttributeCoercion;

package/schematics/migrations/dl-attribute-coercion/schema.json

@@ -0,0 +1,15 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-dl-attribute-coercion",
+    "title": "Koobiq components description list review migration",
+    "type": "object",
+    "properties": {
+        "project": {
+            "type": "string",
+            "description": "Name of the project to inspect. If omitted, the migration runs over the whole tree.",
+            "$default": {
+                "$source": "projectName"
+            }
+        }
+    }
+}