@koobiq/components 20.4.2 → 21.0.0

package/schematics/migrations/autocomplete-signals/schema.json

@@ -0,0 +1,20 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-autocomplete-signals",
+    "title": "Koobiq components autocomplete signals migration",
+    "type": "object",
+    "properties": {
+        "project": {
+            "type": "string",
+            "description": "Name of the project to migrate. If omitted, the migration runs over the whole tree.",
+            "$default": {
+                "$source": "projectName"
+            }
+        },
+        "fix": {
+            "type": "boolean",
+            "default": true,
+            "description": "When true, applies all auto-fix replacements. When false, prints what would change without writing."
+        }
+    }
+}

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

@@ -0,0 +1,77 @@
+# badge-signals
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21` (registered for
+`21.0.0-0`). Migrates `KbqBadge` consumers to its finished signal-based API and reports the members
+the badge review closed.
+
+## Background
+
+`badgeColor` was the last accessor input on the badge, and it was an odd one: the setter took a
+color, the getter returned a CSS class.
+
+```ts
+badge.badgeColor = KbqBadgeColors.Error;
+badge.badgeColor; // 'kbq-badge_error' — not what was written
+```
+
+It is an `input()` now and reports what was written. The `kbq-badge_<color>` class is still applied
+to the host, from an internal computed, so styles are unaffected.
+
+`compact` and `outline` gained `booleanAttribute` in the same review, and the `KbqBadgeCssStyler`
+directive — an implementation detail of `<kbq-badge>` that nothing outside the component ever drove
+— closed its members.
+
+## What it rewrites
+
+| Before          | After             |
+| --------------- | ----------------- |
+| `badge.compact` | `badge.compact()` |
+| `badge.outline` | `badge.outline()` |
+
+Both on receivers explicitly typed `KbqBadge` and through template reference variables on
+`<kbq-badge>`, in external and inline templates. Already-migrated reads are left alone, so the
+schematic is idempotent.
+
+## What it does _not_ do
+
+| Pattern                | Manual migration                                                                           |
+| ---------------------- | ------------------------------------------------------------------------------------------ |
+| `.badgeColor`          | `badgeColor()` — and expect the raw color, not `kbq-badge_<color>`                         |
+| `badge.badgeColor = …` | Bind `[badgeColor]` in the template — the input is read-only                               |
+| `.iconItem`            | Removed; the badge never read this content query either                                    |
+| `KbqBadgeCssStyler.*`  | Now `private`; the icon spacing classes it applies are the contract                        |
+| `viewChild(KbqBadge)`  | The query is a signal too, so a read through it is a double call: `this.badge().compact()` |
+
+`@ViewChild(KbqBadge) badge: KbqBadge` is a plain annotated field, so it is rewritten like any other
+receiver — `this.badge.compact()`, a single call. Only the signal-query form needs the double call.
+
+`badgeColor` is warned about rather than rewritten because appending `()` would compile and hand
+back a different string.
+
+## What it cannot see
+
+Receivers are found by explicit type annotation, with no cross-package type resolution. A non-null
+assertion, parentheses and an aliased import (`import { KbqBadge as Badge }`) are seen through; a
+`KbqBadge` named in a type position that does not resolve to a single identifier — a union, an array,
+a `QueryList<KbqBadge>`, a cast, a return type — is reported with its line number rather than
+rewritten, and so is a read the access pass structurally cannot reach: `badge['compact']` and
+`const { compact } = badge`.
+
+Templates report rather than rewrite when they cannot be parsed, and skip a reference variable whose
+name a `@for` variable, an `@let` or another `#ref` also introduces. A reference is rewritten only
+inside the embedded view that declares it, so a read outside an `@if`, `@for` or `<ng-template>` is
+left alone.
+
+## Notes with no call site to point at
+
+- `compact` and `outline` are `booleanAttribute` inputs. `<kbq-badge compact>` used to pass the
+  empty string, which is falsy, so the badge rendered at its default size; it now renders compact.
+  Conversely `[compact]="'false'"` — a non-empty string, previously truthy — now means `false`.
+
+## Running it manually
+
+```
+ng generate @koobiq/components:badge-signals --project my-app
+```
+
+Pass `--fix=false` to see what it would change without writing.

package/schematics/migrations/badge-signals/data.js

@@ -0,0 +1,109 @@
+'use strict';
+
+/**
+ * Data for the `badge-signals` migration.
+ *
+ * `KbqBadge` moved its remaining accessor input to a signal and closed the internals of the
+ * `KbqBadgeCssStyler` directive that sits on the same host.
+ *
+ * - `badge.compact`    → `badge.compact()`  (value unchanged — auto-fixed)
+ * - `badge.outline`    → `badge.outline()`  (value unchanged — auto-fixed)
+ * - `badge.badgeColor` → read-only signal; it now reports the raw color, not `kbq-badge_<color>` (warn)
+ * - `badge.iconItem`   → removed; it was a content query nothing ever read (warn)
+ * - `KbqBadgeCssStyler.icons` / `nativeElement` / `updateClassModifierForIcons` → `private`, and
+ *   `isIconButton` is gone entirely — nothing in the badge ever read it (warn)
+ *
+ * Template *bindings* (`[compact]`, `[outline]`, `[badgeColor]`) keep working — only programmatic reads and
+ * template-reference reads break. `compact` and `outline` also gained `booleanAttribute`, which is a behavior
+ * change with no call site to point at: it is reported once per project.
+ */
+/** Members of `KbqBadge` whose value is unchanged; a read must become a call. Auto-fixed. */
+const SIGNAL_MEMBERS = ['compact', 'outline'];
+/**
+ * Signal members that are writable via `.set(...)`. Every `KbqBadge` signal 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 badge. */
+const BADGE_TYPE = 'KbqBadge';
+/** TypeScript type annotation that marks a receiver as the badge's CSS styler directive. */
+const STYLER_TYPE = 'KbqBadgeCssStyler';
+/** Element selector whose template reference variables (`#ref`) point at a badge. */
+const BADGE_ELEMENT = 'kbq-badge';
+/** Import specifier that marks a file as a badge consumer. */
+const BADGE_PACKAGE = '@koobiq/components/badge';
+/**
+ * `badgeColor` became a read-only `InputSignal` AND changed its value: the getter used to return the CSS class
+ * `kbq-badge_<color>`, it now reports the raw color (e.g. `error`). A mechanical `()` append would compile and
+ * silently hand back a different string, so this is warned on rather than auto-fixed.
+ */
+const VALUE_CHANGED_MEMBERS = ['badgeColor'];
+/** `KbqBadge` members that left the public surface. */
+const PROTECTED_MEMBERS = ['iconItem'];
+/** `KbqBadgeCssStyler` members a consumer can no longer reach: private, or removed outright. */
+const STYLER_PRIVATE_MEMBERS = [
+    'icons',
+    'isIconButton',
+    'nativeElement',
+    'updateClassModifierForIcons'
+];
+/**
+ * File-scoped patterns that can't be auto-fixed reliably — surfaced with file locations (in both `fix` and
+ * dry-run mode). Only evaluated for files that reference the badge, so the patterns stay scoped.
+ */
+const warnPatterns = [
+    {
+        anchor: '\\bKbqBadge\\b',
+        // The signal-query form only. The decorator form (`@ViewChild(KbqBadge) badge: KbqBadge`) is an
+        // annotated field the receiver pass resolves on its own, and rewrites to a single call. Whitespace
+        // rather than `[^\\n;]` between the parts, so a prettier-wrapped call is still matched.
+        pattern: '\\b(?:viewChild|contentChild)(?:\\s*\\.\\s*required)?\\s*(?:<[^<>()]*>)?\\s*\\(\\s*KbqBadge\\b',
+        message: 'A `viewChild(KbqBadge)` / `contentChild(KbqBadge)` query is itself a signal, so a badge signal ' +
+            'read through it is a double call: `this.badge().compact()`. The receiver pass cannot see through ' +
+            'the query, so these reads are left untouched. Migrate them by hand.'
+    },
+    {
+        anchor: '\\bKbqBadgeCssStyler\\b',
+        // Match a member access rather than the type name: importing the directive for a module's
+        // `declarations` is not a call site, and warning on it is pure noise.
+        pattern: `\\.\\s*(?:${STYLER_PRIVATE_MEMBERS.join('|')})\\b`,
+        message: 'KbqBadgeCssStyler is an implementation detail of <kbq-badge> and no longer exposes any member: ' +
+            `${STYLER_PRIVATE_MEMBERS.join(', ')} are private, except isIconButton which is gone entirely - ` +
+            'the badge never bound a class to it, so it only forced an ancestor change-detection pass that ' +
+            'rendered nothing. It is still exported and still declared by KbqBadgeModule, so a module import ' +
+            'keeps working. The icon spacing classes it applies are the contract.'
+    }
+];
+/** Reported when a template renders the badge but cannot be parsed, so nothing in it was inspected. */
+const UNPARSEABLE_TEMPLATE_MESSAGE = 'This template renders <kbq-badge> but could not be parsed, so it was left untouched. Migrate reads ' +
+    'through its template reference variables by hand.';
+/**
+ * Reported when a file names `KbqBadge` in a type position the receiver pass cannot scope to a single
+ * identifier - a union, an array, a `QueryList<KbqBadge>`, a cast or a return type. Those reads are left
+ * alone, and staying silent about them would read as "nothing to do here".
+ */
+const UNRESOLVED_RECEIVER_MESSAGE = 'KbqBadge is named here in a type position this migration cannot resolve to a single receiver, so any ' +
+    'signal read through it was left untouched. Check these lines by hand:';
+/** Printed once per project, after the per-file reports. */
+const SUMMARY = [
+    '  `compact` and `outline` are `booleanAttribute` inputs now. A valueless attribute finally means true: ' +
+        '<kbq-badge compact> used to pass the empty string, which is falsy, so the badge rendered at its ' +
+        'default size. Markup that carried the attribute expecting nothing to happen now renders compact, and ' +
+        '[compact]="\'false\'" — a non-empty string, previously truthy — now means false.',
+    '  `badgeColor` reports the raw color instead of the `kbq-badge_<color>` class. The class is still on the ' +
+        'host element, so styles and screenshots are unaffected; only a programmatic read sees the change.'
+];
+
+exports.BADGE_ELEMENT = BADGE_ELEMENT;
+exports.BADGE_PACKAGE = BADGE_PACKAGE;
+exports.BADGE_TYPE = BADGE_TYPE;
+exports.PROTECTED_MEMBERS = PROTECTED_MEMBERS;
+exports.SIGNAL_MEMBERS = SIGNAL_MEMBERS;
+exports.STYLER_PRIVATE_MEMBERS = STYLER_PRIVATE_MEMBERS;
+exports.STYLER_TYPE = STYLER_TYPE;
+exports.SUMMARY = SUMMARY;
+exports.UNPARSEABLE_TEMPLATE_MESSAGE = UNPARSEABLE_TEMPLATE_MESSAGE;
+exports.UNRESOLVED_RECEIVER_MESSAGE = UNRESOLVED_RECEIVER_MESSAGE;
+exports.VALUE_CHANGED_MEMBERS = VALUE_CHANGED_MEMBERS;
+exports.WRITABLE_MEMBERS = WRITABLE_MEMBERS;
+exports.warnPatterns = warnPatterns;