@koobiq/components 20.4.2 → 21.0.1

package/schematics/migrations/progress-bar-percentage-and-aria/data.cjs

@@ -0,0 +1,76 @@
+'use strict';
+
+/**
+ * Data for the `progress-bar-percentage-and-aria` migration.
+ *
+ * The progress-bar review closed the one member that was never part of the component's contract and
+ * gave the bar the semantics it had none of:
+ *
+ * - `percentage` — public getter over the clamped `value` → `protected` computed. It existed to feed
+ *   the template; the rendered width is the observable half of it.
+ * - The host renders `role="progressbar"` with mode-aware `aria-valuenow` / `aria-valuemin` /
+ *   `aria-valuemax`, an `aria-label` that falls back to the new `progressBar` a11y locale key, and
+ *   `aria-labelledby` / `aria-describedby` pointing at the projected text and caption.
+ * - `KbqProgressBarText` and `KbqProgressBarCaption` render an `id` — generated, or the one bound —
+ *   so the bar can reference them.
+ * - The inner track no longer repeats the host `id`.
+ *
+ * Warn-only. `percentage` has no drop-in replacement expression, and a hand-rolled `role` or `aria-*`
+ * on `<kbq-progress-bar>` is a decision about which of the two attributes survives.
+ */
+/** Import specifier that marks a file as a progress-bar consumer. */
+const PROGRESS_BAR_PACKAGE = '@koobiq/components/progress-bar';
+/** Identifier and element shapes that mark a consumer without an import. */
+const PROGRESS_BAR_TYPE = '\\bKbqProgressBar\\w*\\b|\\bkbq-progress-bar\\b';
+const warnPatterns = [
+    {
+        anchor: PROGRESS_BAR_TYPE,
+        pattern: '\\.\\s*percentage\\b',
+        message: 'KbqProgressBar.percentage is protected and signal-backed. It only ever existed to feed the ' +
+            'template, and the clamp it performs is observable through the rendered width and through ' +
+            'aria-valuenow. Clamp the value at the call site — Math.max(0, Math.min(100, value)) — or ' +
+            'read the aria-valuenow attribute of the host.'
+    },
+    {
+        anchor: PROGRESS_BAR_TYPE,
+        pattern: '<kbq-progress-bar[^>]*\\s(?:role|aria-valuenow|aria-valuemin|aria-valuemax|aria-labelledby)\\s*=',
+        message: 'The bar renders role="progressbar" with aria-valuenow/valuemin/valuemax of its own (all three ' +
+            'omitted in indeterminate mode, which is how an unknown duration is expressed), plus ' +
+            'aria-labelledby for a projected [kbq-progress-bar-text]. A hand-rolled attribute on the same ' +
+            'element is a duplicate now — drop it.'
+    },
+    {
+        anchor: PROGRESS_BAR_TYPE,
+        pattern: '<kbq-progress-bar[^>]*\\saria-label\\s*=',
+        message: 'aria-label is an input on KbqProgressBar now, not a plain attribute. A static aria-label still ' +
+            'binds and still wins over the projected [kbq-progress-bar-text]; an [attr.aria-label] binding ' +
+            'has to become [aria-label], because the host writes that attribute itself.'
+    },
+    {
+        anchor: '\\bkbq-progress-bar-(?:text|caption)\\b',
+        pattern: '\\bkbq-progress-bar-(?:text|caption)\\b[^>]*\\sid\\s*=',
+        message: 'kbq-progress-bar-text and kbq-progress-bar-caption render an id — the one bound, or a generated ' +
+            'one — so the bar can reference them from aria-labelledby / aria-describedby. An existing id ' +
+            'attribute is preserved; nothing to change unless the element also had [attr.id].'
+    }
+];
+/** Printed once per project, after the per-file reports. */
+const SUMMARY = [
+    '  Under prefers-reduced-motion: reduce an indeterminate bar used to render as a full, finished ' +
+        'determinate bar: the fill was sized only inside the keyframes, so suppressing the animation left ' +
+        'it at width: auto. It is a quarter-width fill with an opacity pulse now, and the determinate ' +
+        'width transition is suppressed under the same preference.',
+    '  [color] covers theme (default), contrast, contrast-fade and error. Every other value used to ' +
+        'render both the track and the fill transparent; an unsupported — or falsy — value falls back to ' +
+        'the default palette now. The error and contrast bars an application already had become visible.',
+    '  The a11y locale gained a progressBar key, used as the accessible name of a bar that carries ' +
+        'neither aria-label nor a projected [kbq-progress-bar-text]. An application overriding the a11y ' +
+        'section through kbqA11yLocaleConfigurationProvider can override it too.',
+    '  The inner track no longer repeats the host id, so a single bar renders exactly one element ' +
+        'carrying that id and an aria-describedby or <label for> aimed at it is no longer ambiguous.'
+];
+
+exports.PROGRESS_BAR_PACKAGE = PROGRESS_BAR_PACKAGE;
+exports.PROGRESS_BAR_TYPE = PROGRESS_BAR_TYPE;
+exports.SUMMARY = SUMMARY;
+exports.warnPatterns = warnPatterns;

package/schematics/migrations/progress-bar-percentage-and-aria/index.cjs

@@ -0,0 +1,59 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var utils_messages = require('../../utils/messages.cjs');
+var utils_packageConfig = require('../../utils/package-config.cjs');
+var utils_projectFiles = require('../../utils/project-files.cjs');
+var migrations_progressBarPercentageAndAria_data = require('./data.cjs');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+const LABEL = '[progress-bar-percentage-and-aria]';
+const EXTENSIONS = ['.ts', '.html'];
+/** A file is a progress-bar consumer if it imports the package, names the component, or renders one. */
+function referencesProgressBar(content) {
+    return content.includes(migrations_progressBarPercentageAndAria_data.PROGRESS_BAR_PACKAGE) || new RegExp(migrations_progressBarPercentageAndAria_data.PROGRESS_BAR_TYPE).test(content);
+}
+/**
+ * Reports the progress-bar review changes a consumer has to act on: the `percentage` getter that became
+ * a protected computed, and the ARIA the host now renders itself. Never writes — `percentage` has no
+ * replacement expression, and which of two competing `aria-*` attributes survives is a decision.
+ *
+ * `.html` is visited as well as `.ts`, because the attributes that collide with the new host bindings
+ * are template markup.
+ */
+function progressBarPercentageAndAria(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_projectFiles.visitProjectFiles(rootDir, (filePath, entry) => {
+            if (!EXTENSIONS.some((extension) => filePath.endsWith(extension)))
+                return;
+            const content = entry?.content.toString();
+            if (!content || !referencesProgressBar(content))
+                return;
+            consumers++;
+            for (const { anchor, pattern, message } of migrations_progressBarPercentageAndAria_data.warnPatterns) {
+                if (!new RegExp(anchor).test(content) || !new RegExp(pattern).test(content))
+                    continue;
+                reported++;
+                utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${message}`]);
+            }
+        });
+        // Nothing here renders a progress bar, so the summary would only be noise.
+        if (consumers === 0)
+            return;
+        utils_messages.logMessage(context.logger, [
+            `${LABEL} processed kbq-progress-bar under "${root || '<workspace root>'}", ` +
+                `${consumers} file(s) reference the component, ${reported} call site(s) reported.`,
+            ...migrations_progressBarPercentageAndAria_data.SUMMARY
+        ]);
+    };
+}
+
+exports.default = progressBarPercentageAndAria;

package/schematics/migrations/progress-bar-percentage-and-aria/schema.json

@@ -0,0 +1,15 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-progress-bar-percentage-and-aria",
+    "title": "Koobiq components progress-bar 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/progress-spinner-signals/README.md

@@ -0,0 +1,72 @@
+# progress-spinner-signals
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21` (registered for
+`21.0.0-0`). Migrates `KbqProgressSpinner` consumers to its finished signal-based API and reports
+the members the review closed.
+
+## Background
+
+`size` was the last accessor input on the spinner, and the reason the automated signal migration
+skipped it: its setter did two things at once, storing the size and computing the SVG circle radius.
+
+```ts
+set size(value: ProgressSpinnerSize | string) {
+    this._size = value;
+    this.svgCircleRadius = value === 'big' ? '47%' : '42.5%';
+}
+```
+
+The radius is a `computed` now and `size` is a plain `input()`. `id`, `value` and `mode` were
+signals since 20.0.0, and no migration has ever covered them, so their reads are rewritten here too.
+
+## What it rewrites
+
+| Before          | After             |
+| --------------- | ----------------- |
+| `spinner.size`  | `spinner.size()`  |
+| `spinner.id`    | `spinner.id()`    |
+| `spinner.value` | `spinner.value()` |
+| `spinner.mode`  | `spinner.mode()`  |
+
+On receivers explicitly typed `KbqProgressSpinner`, on the `inject(KbqProgressSpinner)` and
+`viewChild(KbqProgressSpinner)` forms a modern consumer writes, and through template reference
+variables on `<kbq-progress-spinner>`, in external and inline templates. Already-migrated reads are
+left alone, so the schematic is idempotent.
+
+## What it cannot see
+
+Receivers are found by explicit type annotation or by an `inject()` / `viewChild()` initializer. A
+non-null assertion, parentheses and an aliased import are seen through; a type named in a position
+that does not resolve to a single identifier — a union, an array, a cast, a return type — is reported
+with its line number rather than rewritten, and so is `spinner['size']` or `const { size } = spinner`.
+
+Templates report rather than rewrite when they cannot be parsed, and skip a reference whose name a
+`@for` variable, an `@let` or another `#ref` also introduces. A reference is rewritten only inside the
+embedded view that declares it, and only when it is bound to the spinner rather than to some other
+directive through `exportAs`.
+
+## What it does _not_ do
+
+| Pattern                              | Manual migration                                                        |
+| ------------------------------------ | ----------------------------------------------------------------------- |
+| `spinner.size = …`                   | Bind `[size]` in the template — the input is read-only                  |
+| `.percentage` / `.dashOffsetPercent` | Now `protected`; derive what you need from the `value` you already bind |
+| `.svgCircleRadius`                   | Now `protected`; it is the SVG geometry, not a contract                 |
+| `viewChild(KbqProgressSpinner)`      | The query is a signal too, so a read through it is a double call        |
+
+## Notes with no call site to point at
+
+- `size` is typed `ProgressSpinnerSize` (`'compact' | 'big'`) instead of accepting an arbitrary
+  string, resolving a TODO that predates the review. Any other value used to fall through to the
+  compact radius silently; it is a template type error now.
+- `value` is a `numberAttribute` input with a `0` fallback. `value="40"` used to pass the string
+  `"40"`, which the percentage arithmetic coerced by accident. Anything that is not a number reads as
+  `0` rather than reaching the `stroke-dashoffset` percentage as `NaN`, which is not a length at all.
+
+## Running it manually
+
+```
+ng generate @koobiq/components:progress-spinner-signals --project my-app
+```
+
+Pass `--fix=false` to see what it would change without writing.

package/schematics/migrations/progress-spinner-signals/data.cjs

@@ -0,0 +1,83 @@
+'use strict';
+
+/**
+ * Data for the `progress-spinner-signals` migration.
+ *
+ * `size` was the last accessor input on the spinner. Its setter also computed the SVG circle radius, which is
+ * why the automated signal migration skipped it; the radius is a `computed` now and the input is a plain
+ * `input()`.
+ *
+ * - `spinner.size` → `spinner.size()` (value unchanged — auto-fixed)
+ * - `spinner.id` / `value` / `mode` → the same (auto-fixed)
+ * - `spinner.svgCircleRadius` / `percentage` / `dashOffsetPercent` → `protected` (warn)
+ *
+ * `id`, `value` and `mode` became `input()` in 20.0.0, not 20.2.0, and no migration ever covered them.
+ * This schematic is registered for `21.0.0-0`, so it runs for a v20 → v21 upgrade and is the only place
+ * those reads are ever rewritten.
+ */
+/** Members of `KbqProgressSpinner` whose value is unchanged; a read must become a call. Auto-fixed. */
+const SIGNAL_MEMBERS = ['size', 'id', 'value', 'mode'];
+/**
+ * Signal members that are writable via `.set(...)`. Every one of them is `input()` (read-only), so this is
+ * empty — a programmatic write is left untouched and becomes a compile error the consumer fixes by hand.
+ */
+const WRITABLE_MEMBERS = new Set();
+/** TypeScript type annotation that marks a receiver as a progress spinner. */
+const SPINNER_TYPE = 'KbqProgressSpinner';
+/** Element selector whose template reference variables (`#ref`) point at a progress spinner. */
+const SPINNER_ELEMENT = 'kbq-progress-spinner';
+/** Import specifier that marks a file as a progress spinner consumer. */
+const SPINNER_PACKAGE = '@koobiq/components/progress-spinner';
+/** Members that moved from `public` to `protected` and can no longer be read from outside the component. */
+const PROTECTED_MEMBERS = ['svgCircleRadius', 'percentage', 'dashOffsetPercent'];
+const SPINNER_ANCHOR = '\\bKbqProgressSpinner\\w*\\b';
+const warnPatterns = [
+    {
+        anchor: SPINNER_ANCHOR,
+        // The signal-query form only. `@ViewChild(KbqProgressSpinner) s: KbqProgressSpinner` is a plain
+        // annotated field that the receiver pass resolves and rewrites to a single call, so telling the
+        // reader it needs a double call there would break working code. Whitespace rather than `[^\n;]`,
+        // so a prettier-wrapped call is matched too.
+        pattern: '\\b(?:viewChild|contentChild)(?:\\s*\\.\\s*required)?\\s*(?:<[^<>()]*>)?\\s*\\(\\s*KbqProgressSpinner\\b',
+        message: 'A `viewChild(KbqProgressSpinner)` / `contentChild(KbqProgressSpinner)` query is itself a signal, ' +
+            'so reading a spinner signal through it is a double call: `this.spinner().size()`. Those reads are ' +
+            'resolved and rewritten where the query is assigned to a field; check any other shape by hand.'
+    }
+];
+/** Reported when a template renders the spinner but cannot be parsed, so nothing in it was inspected. */
+const UNPARSEABLE_TEMPLATE_MESSAGE = 'This template renders <kbq-progress-spinner> but could not be parsed, so it was left untouched. ' +
+    'Migrate reads through its template reference variables by hand.';
+/**
+ * Reported when a file names the spinner 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. Those reads are left alone, and staying silent reads as "nothing to do".
+ */
+const UNRESOLVED_RECEIVER_MESSAGE = 'KbqProgressSpinner 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:';
+/** Appended to the protected-members report, in both the TypeScript and the template pass. */
+const PROTECTED_HINT = 'They are internals of the spinner: the radius, the clamped fraction and the stroke offset are derived ' +
+    'from `size` and `value`, so bind those instead of reading the derived values.';
+/** Printed once per project, after the per-file reports. */
+const SUMMARY = [
+    "  `size` no longer accepts an arbitrary string: it is typed `ProgressSpinnerSize` ('compact' | 'big'), " +
+        'resolving a TODO that predates the component review. Any other value used to fall through to the ' +
+        'compact radius silently; it is a template type error now.',
+    '  `value` is a `numberAttribute` input with a 0 fallback. `value="40"` used to pass the string "40", ' +
+        'which the percentage arithmetic coerced by accident; it is a number now, and anything that is not a ' +
+        'number reads as 0 rather than reaching the stroke offset as NaN.',
+    '  `id`, `value` and `mode` became signal inputs back in 20.0.0 and no migration has covered them until ' +
+        'now, so their reads are rewritten here too. A read left un-called is silent: `spinner.value > 50` is ' +
+        'always false and `{{ spinner.value }}` prints the function source.'
+];
+
+exports.PROTECTED_HINT = PROTECTED_HINT;
+exports.PROTECTED_MEMBERS = PROTECTED_MEMBERS;
+exports.SIGNAL_MEMBERS = SIGNAL_MEMBERS;
+exports.SPINNER_ELEMENT = SPINNER_ELEMENT;
+exports.SPINNER_PACKAGE = SPINNER_PACKAGE;
+exports.SPINNER_TYPE = SPINNER_TYPE;
+exports.SUMMARY = SUMMARY;
+exports.UNPARSEABLE_TEMPLATE_MESSAGE = UNPARSEABLE_TEMPLATE_MESSAGE;
+exports.UNRESOLVED_RECEIVER_MESSAGE = UNRESOLVED_RECEIVER_MESSAGE;
+exports.WRITABLE_MEMBERS = WRITABLE_MEMBERS;
+exports.warnPatterns = warnPatterns;