@koobiq/components 20.4.2 → 21.0.0

package/schematics/migrations/progress-spinner-signals/schema.json

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

@@ -0,0 +1,32 @@
+# query-list-signals
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21` (registered for `21.0.0-0`).
+Reports subclasses that redeclare the query members turned into getters, and writes to those members. It never writes
+to the tree.
+
+## Background
+
+The remaining decorator queries are signal queries. The members over them are getters that keep their types, so a
+read and a subscription to `changes` work as before. Before the content is initialized a `QueryList` is empty rather
+than `undefined`.
+
+| Member                                                                                                  | Type         |
+| ------------------------------------------------------------------------------------------------------- | ------------ |
+| `options` of `KbqSelect`, `KbqAutocomplete` and `KbqListSelection`                                      | `QueryList`  |
+| `tags` of `KbqSelect`, `KbqTreeSelect` (protected) and `KbqTagList`                                     | `QueryList`  |
+| `KbqRadioGroup.radios`, `KbqTreeSelection.unorderedOptions`                                             | `QueryList`  |
+| `focusableItems` of `KbqNavbar` and `KbqVerticalNavbar`, `KbqAppSwitcherComponent.allItems` (protected) | `QueryList`  |
+| `textElement` of `KbqTag` and `KbqDropdownItem`                                                         | `ElementRef` |
+| `KbqCodeBlock.tabLinkTemplate` (protected)                                                              | Signal       |
+
+| Use                                   | What to do                                       |
+| ------------------------------------- | ------------------------------------------------ |
+| A subclass that redeclared the member | Remove the redeclaration, or override the getter |
+| A write to the member                 | Render the items in the template instead         |
+| A subclass reading `tabLinkTemplate`  | Call it: `this.tabLinkTemplate()`                |
+
+## Running it manually
+
+```bash
+ng g @koobiq/components:query-list-signals --project "<your project>"
+```

package/schematics/migrations/query-list-signals/data.js

@@ -0,0 +1,70 @@
+'use strict';
+
+/**
+ * Data for the `query-list-signals` migration.
+ *
+ * The remaining decorator queries are signal queries now. The public members over them are getters that keep their
+ * types — a `QueryList` whose `changes` emit as before, or an `ElementRef` — so reads are unchanged. A subclass that
+ * redeclares one of them, and a write to one, no longer compile. `KbqCodeBlock.tabLinkTemplate`, which is protected,
+ * is a signal. Warn-only.
+ */
+const OWNERS = [
+    'KbqSelect',
+    'KbqTimezoneSelect',
+    'KbqTreeSelect',
+    'KbqAutocomplete',
+    'KbqListSelection',
+    'KbqFocusableComponent',
+    'KbqNavbar',
+    'KbqVerticalNavbar',
+    'KbqRadioGroup',
+    'KbqTagList',
+    'KbqTag',
+    'KbqDropdownItem',
+    'KbqTreeSelection',
+    'KbqAppSwitcherComponent',
+    'KbqCodeBlock'
+].join('|');
+const MEMBERS = [
+    'options',
+    'tags',
+    'focusableItems',
+    'radios',
+    'unorderedOptions',
+    'allItems',
+    'textElement',
+    'tabLinkTemplate'
+].join('|');
+const SUBCLASS = `\\bextends\\s+(?:${OWNERS})\\b`;
+const warnPatterns = [
+    {
+        anchor: SUBCLASS,
+        pattern: `@(?:ViewChild|ViewChildren|ContentChild|ContentChildren)\\s*\\(|\\b(?:override|declare)\\s+(?:readonly\\s+)?(?:${MEMBERS})\\s*[!?]?\\s*:`,
+        message: 'A subclass of a Koobiq component whose query members are getters over signal queries now: options of ' +
+            'KbqSelect, KbqAutocomplete and KbqListSelection, tags of KbqSelect, KbqTreeSelect and KbqTagList, ' +
+            'focusableItems of KbqNavbar and KbqVerticalNavbar, KbqRadioGroup.radios, ' +
+            'KbqTreeSelection.unorderedOptions, KbqAppSwitcherComponent.allItems and textElement of KbqTag and ' +
+            'KbqDropdownItem. A subclass can no longer redeclare them as fields: remove the redeclaration, or override ' +
+            'the getter. This pattern also matches a query of the subclass itself — check before changing it.'
+    },
+    {
+        anchor: `\\b(?:${OWNERS})\\b`,
+        pattern: '\\.\\s*(?:options|tags|focusableItems|radios|unorderedOptions|textElement)\\s*=[^=]',
+        message: 'The query members of KbqSelect, KbqAutocomplete, KbqListSelection, the navbar, ' +
+            'KbqRadioGroup, KbqTagList, KbqTag, KbqDropdownItem and KbqTreeSelection are read-only getters now, so a ' +
+            'write no longer compiles. Render the items in the template instead. This pattern also matches a write ' +
+            'to an unrelated object in the same file — check before changing it.'
+    },
+    {
+        anchor: '\\bextends\\s+KbqCodeBlock\\b',
+        pattern: '\\btabLinkTemplate\\b(?!\\s*\\()',
+        message: 'KbqCodeBlock.tabLinkTemplate is a protected signal now: a subclass reads it as this.tabLinkTemplate().'
+    }
+];
+const SUMMARY = [
+    'Reading these members and subscribing to the changes of a QueryList work as before. Before the content is',
+    'initialized a QueryList is empty rather than undefined.'
+];
+
+exports.SUMMARY = SUMMARY;
+exports.warnPatterns = warnPatterns;

package/schematics/migrations/query-list-signals/index.js

@@ -0,0 +1,17 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var warnOnlyMigration = require('../../warn-only-migration-BISJBODk.js');
+var migrations_queryListSignals_data = require('./data.js');
+require('../../utils/messages.js');
+require('../../package-config-BhU2TfC8.js');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+/** Reports subclasses that redeclare the query members now behind getters, and writes to them. Never writes. */
+function queryListSignals(options) {
+    return warnOnlyMigration.warnOnlyRule({ label: '[query-list-signals]', warnPatterns: migrations_queryListSignals_data.warnPatterns, summary: migrations_queryListSignals_data.SUMMARY }, options);
+}
+
+exports.default = queryListSignals;

package/schematics/migrations/query-list-signals/schema.json

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

@@ -0,0 +1,82 @@
+# radio-signals-and-aria
+
+Migration schematic invoked automatically by `ng update @koobiq/components@20`
+(registered for `21.0.0-0`). Moves the radio's one-way inputs to the signal API and reports what has
+no mechanical translation.
+
+## Background
+
+`name` is the load-bearing contract in the radio: the app-global `UniqueSelectionDispatcher` fans a
+notification out to every listener in the application, and the name comparison inside each listener is
+the only isolation there is. A button used outside a group never assigned one, so `undefined ===
+undefined` made every group-less radio in the application one selection group — checking one
+un-checked the others, in unrelated routes, overlays and dialogs. In the other direction, `ngOnInit`
+overwrote an explicitly bound `[name]` with the group's, so the documented input did nothing.
+
+## What it rewrites
+
+A read of one of these becomes a call. The rewrite is **scoped by receiver type**, which matters here
+more than in any other component of the campaign: `name`, `labelPosition` and `required` exist on both
+classes, and only the group's became signals.
+
+| Type             | Members                             |
+| ---------------- | ----------------------------------- |
+| `KbqRadioGroup`  | `name`, `labelPosition`, `required` |
+| `KbqRadioButton` | `id`, `inputId`                     |
+
+So `group.required` becomes `group.required()`, while `button.required` is left exactly as it was.
+
+## What stays an accessor input, and why
+
+| Member                                                                    | Why                                                                                                                                                                             |
+| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `KbqRadioGroup.value`                                                     | `writeValue` writes it, and has to resolve the checked button synchronously before the first render; a `model()` would also publish a `valueChange` output duplicating `change` |
+| `KbqRadioGroup.selected`                                                  | the buttons write their selection back onto the group                                                                                                                           |
+| `KbqRadioGroup.disabled`                                                  | `setDisabledState` writes it, and it coerces with `booleanAttribute` — a `model()` carries no `transform`                                                                       |
+| `KbqRadioButton.checked`                                                  | two-way state the component and the form both write, with a `booleanAttribute` transform                                                                                        |
+| `KbqRadioButton.value`                                                    | writing it re-resolves the checked state against the group                                                                                                                      |
+| `disabled`, `required`, `labelPosition`, `name`, `tabIndex` on the button | each folds in the group's value — a button inside a disabled group is disabled — so the read is derived, not stored                                                             |
+
+Reads and writes of those are unchanged.
+
+## What it only reports
+
+| Pattern                           | Manual migration                                                                                                |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `[isFocused]` / `.isFocused`      | Read the `cdk-*-focused` classes, or call `focus(origin)`                                                       |
+| `.radioGroup`                     | Guard the access — the button may not be in a group                                                             |
+| `.id = …`                         | Bind `[id]` instead; `id` is read-only now                                                                      |
+| `--kbq-radio-size-*-top`          | Delete the override; no rule read it                                                                            |
+| `hostDirectives: [KbqRadioGroup]` | Render a `<kbq-radio-group>` element; a component cannot be a host directive                                    |
+| `extends KbqRadioGroup`           | Decorate the subclass with `@Component` and repeat `<ng-content />` and the `kbq-error` slot, or wrap the group |
+
+`KbqRadioButton.isFocused` was removed outright: a published input that nothing read. `radioGroup` is
+typed `KbqRadioGroup | null` — it was always injected with `{ optional: true }` and the non-null
+assertion only hid it.
+
+## Notes with no call site to point at
+
+- Two `<kbq-radio-button>`s used outside a group are independent now. Markup that relied on the old
+  mutual exclusion has to say so: put them in a group, or give them the same explicit `[name]`.
+- `[name]` on a button inside a group is honoured, so a button bound to its own name forms its own
+  selection group instead of silently inheriting the group's.
+- `<kbq-radio-group>` is a `radiogroup`, which takes no name from its content. Name it with a plain
+  `aria-label` / `aria-labelledby` attribute on the element — a detached label sibling leaves the
+  group unnamed for assistive technology.
+- A `kbq-hint` projected into a button is exposed through `aria-describedby` instead of being folded
+  into the button's accessible name.
+- `KbqRadioGroup` is a component: a `kbq-error` put inside it is rendered under the options only
+  while the group is in the error state, and the group references it from its `aria-describedby`.
+- `[color]` on the group colors every button in it, `[required]` reaches the group as
+  `aria-required`, and an error color as `aria-invalid`.
+- The native input carries its option value, so a group inside a plain `<form>` submits that value
+  instead of the literal `"on"`. Only string-like values round-trip, and a group meant for native
+  submission still needs an explicit `[name]`.
+
+## Running it manually
+
+```
+ng generate @koobiq/components:radio-signals-and-aria --project my-app
+```
+
+Pass `--fix=false` to see what would change without writing.

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

@@ -0,0 +1,163 @@
+'use strict';
+
+/**
+ * Data for the `radio-signals-and-aria` migration.
+ *
+ * The review closed the `name` contract, gave the group something to say about itself, and moved the
+ * one-way inputs to the signal API.
+ *
+ * Only the members listed in `MEMBERS_BY_TYPE` became signals, and the split matters: `name`,
+ * `labelPosition` and `required` exist on **both** `KbqRadioGroup` and `KbqRadioButton`, and only the
+ * group's are signals. The button's stay accessors, because each folds in the group's value — a button
+ * inside a disabled group is disabled, one inside a required group is required. That is why the rewrite
+ * is scoped by receiver type rather than by member name: `group.required` becomes `group.required()`,
+ * `button.required` is left alone.
+ *
+ * `value`, `selected` and `disabled` on the group stay accessor inputs. `writeValue` and
+ * `setDisabledState` write them from outside the template, `disabled` coerces with `booleanAttribute`
+ * and a `model()` carries no `transform`, and `writeValue` has to resolve the checked button
+ * synchronously before the first render. Reads and writes of those three are unchanged.
+ *
+ * Nothing here is writable: every migrated member is a read-only `input()` or a `computed()`, so a
+ * programmatic write has no mechanical translation and is reported instead.
+ */
+/** Identifier shape that marks a file as a radio consumer without an import. */
+const RADIO_ANCHOR = '\\bKbqRadio\\w*\\b|\\bkbq-radio\\b';
+/** Import specifier that marks a file as a radio consumer. */
+const RADIO_PACKAGE = '@koobiq/components/radio';
+/** Which members each type owns. A receiver resolves to one type, so the rewrite is scoped by it. */
+const MEMBERS_BY_TYPE = {
+    KbqRadioGroup: ['name', 'labelPosition', 'required'],
+    KbqRadioButton: ['id', 'inputId']
+};
+/** `exportAs` names a template reference can be bound to. */
+const EXPORT_AS_TO_TYPE = {
+    kbqRadioGroup: 'KbqRadioGroup',
+    kbqRadioButton: 'KbqRadioButton'
+};
+/** Element selectors whose bare `#ref` points at one of the migrated types. */
+const ELEMENT_TO_TYPE = {
+    'kbq-radio-group': 'KbqRadioGroup',
+    'kbq-radio-button': 'KbqRadioButton'
+};
+/** None: every migrated member is a read-only `input()` or a `computed()`. */
+const WRITABLE_MEMBERS = new Set();
+/** The two custom properties the review removed. Also reported in stylesheets, which the engine skips. */
+const REMOVED_TOKENS_PATTERN = '--kbq-radio-size-(?:big|normal)-top\\b';
+const REMOVED_TOKENS_MESSAGE = 'The --kbq-radio-size-big-top and --kbq-radio-size-normal-top custom properties were removed. ' +
+    'Neither was referenced by any rule in the package, so overriding them never changed anything; ' +
+    'the vertical offset follows the line height through kbq-css-half-difference().';
+const warnPatterns = [
+    {
+        anchor: RADIO_ANCHOR,
+        pattern: '\\bisFocused\\b',
+        message: 'KbqRadioButton.isFocused was removed. It was a published input that nothing in the component ' +
+            'read — no host binding, no template reference — so binding it never had an effect. Focus state ' +
+            'is carried by the FocusMonitor classes on the host (cdk-keyboard-focused / cdk-program-focused); ' +
+            'read those, or call focus(origin).'
+    },
+    {
+        anchor: RADIO_ANCHOR,
+        pattern: '\\.\\s*radioGroup\\b',
+        message: 'KbqRadioButton.radioGroup is typed KbqRadioGroup | null. It was always injected with ' +
+            '{ optional: true } and the non-null assertion only hid it, so a button used outside a group ' +
+            'already returned null behind a non-nullable type. Guard the access instead of asserting it. ' +
+            'Note that the group members reached through it are signals now: radioGroup?.name() rather ' +
+            'than radioGroup.name.'
+    },
+    {
+        anchor: RADIO_ANCHOR,
+        pattern: '\\.\\s*id\\s*=[^=]',
+        message: 'KbqRadioButton.id is a read-only input() now, so a programmatic write no longer compiles. Bind ' +
+            '[id] in the template instead. Binding it to null or an empty string keeps the generated id, so ' +
+            'a read always yields the id the element actually carries. This pattern also matches a plain ' +
+            'element.id assignment in a file that happens to name the radio — check before changing it.'
+    },
+    {
+        anchor: RADIO_ANCHOR,
+        pattern: REMOVED_TOKENS_PATTERN,
+        message: REMOVED_TOKENS_MESSAGE
+    },
+    {
+        anchor: RADIO_ANCHOR,
+        pattern: 'hostDirectives[^\\]]*\\bKbqRadioGroup\\b|\\bdirective\\s*:\\s*KbqRadioGroup\\b',
+        message: 'KbqRadioGroup is a component now, so it can no longer be applied through hostDirectives: a ' +
+            'component cannot be a host directive. Render a <kbq-radio-group> element in the template instead.'
+    },
+    {
+        anchor: RADIO_ANCHOR,
+        pattern: '\\bextends\\s+KbqRadioGroup\\b',
+        message: 'KbqRadioGroup is a component now. A subclass decorated with @Directive fails at runtime with NG0903 ' +
+            '(directives cannot inherit components), so decorate it with @Component instead. Its template ' +
+            "replaces the group's, so repeat <ng-content /> in it and, to keep the validation error, the " +
+            'kbq-error slot. Wrapping the group rather than extending it avoids both.'
+    }
+];
+const UNPARSEABLE_TEMPLATE_MESSAGE = 'This template renders a radio but could not be parsed, so it was left untouched. Migrate reads ' +
+    'through its template reference variables by hand.';
+const UNRESOLVED_RECEIVER_MESSAGE = 'A radio type 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:';
+const SUMMARY = [
+    '  KbqRadioGroup.name, .labelPosition and .required are signal inputs now, so a read is a call. A read ' +
+        'left un-called is silent in a template: {{ group.name }} prints the function source, and ' +
+        '@if (group.required) is always true. The same three members on KbqRadioButton are unchanged — each ' +
+        "folds in the group's value, so they stay accessors — which is why this rewrite is scoped by type.",
+    '  KbqRadioButton.id and .inputId are signals too. id is read-only now: bind [id] rather than assigning ' +
+        'to it, and bind null or an empty string to keep the generated one.',
+    '  KbqRadioGroup.value, .selected and .disabled are deliberately unchanged. ControlValueAccessor writes ' +
+        'the first and last, the buttons write selected, and writeValue has to resolve the checked button ' +
+        'before the first render — none of which a read-only input() or a transform-less model() supports.',
+    '  A <kbq-radio-button> used outside a <kbq-radio-group> is independent now. It used to resolve its ' +
+        'name to undefined, and the application-global UniqueSelectionDispatcher isolates its listeners by ' +
+        'name alone, so checking one un-checked every other group-less radio in the application. Markup ' +
+        'that relied on that mutual exclusion has to say so: put the buttons in a group, or give them the ' +
+        'same explicit [name].',
+    '  [name] on a <kbq-radio-button> inside a group is honoured. ngOnInit used to overwrite it with the ' +
+        "group's name unconditionally, so a bound name was discarded; a button bound to its own name now " +
+        'forms its own selection group.',
+    '  <kbq-radio-group> is a radiogroup, which takes no name from its content. Name it with a plain ' +
+        'aria-label / aria-labelledby attribute on the element — a detached label sibling leaves the group ' +
+        'unnamed for assistive technology.',
+    '  A kbq-hint projected into a button is exposed through aria-describedby instead of being folded into ' +
+        "the button's accessible name, so an option is announced by its own text.",
+    '  KbqRadioGroup accepts [color]: one binding colors every button in the group, so the error palette ' +
+        'no longer has to be repeated per option. The error color is also mirrored as aria-invalid, and ' +
+        '[required] as aria-required, on the group element.',
+    '  KbqRadioGroup is a component now. A kbq-error put inside the group is rendered under the options only ' +
+        'while the group is in the error state, a kbq-hint put directly inside it is moved under the options ' +
+        'after the error, and both are referenced from its aria-describedby. A component cannot be a host ' +
+        'directive, and a @Directive cannot extend it.',
+    "  KbqRadioButton.focus() takes a FocusOrigin and routes through the FocusMonitor, so focus('keyboard') " +
+        'leaves the visible ring the theme paints off .cdk-keyboard-focused. KbqRadioGroup has a focus() of ' +
+        'its own that forwards to the checked option, or to the first enabled one.',
+    '  The native input carries its option value now, so a group inside a plain <form> submits that value ' +
+        'instead of the literal "on". Only string-like values round-trip, and a group meant for native ' +
+        'submission still needs an explicit [name] — the generated one changes between application loads.'
+];
+const config = {
+    label: '[radio-signals-and-aria]',
+    package: RADIO_PACKAGE,
+    membersByType: MEMBERS_BY_TYPE,
+    exportAsToType: EXPORT_AS_TO_TYPE,
+    elementToType: ELEMENT_TO_TYPE,
+    writableMembers: WRITABLE_MEMBERS,
+    warnPatterns,
+    messages: {
+        unparseableTemplate: UNPARSEABLE_TEMPLATE_MESSAGE,
+        unresolvedReceiver: UNRESOLVED_RECEIVER_MESSAGE,
+        summary: SUMMARY
+    }
+};
+
+exports.ELEMENT_TO_TYPE = ELEMENT_TO_TYPE;
+exports.EXPORT_AS_TO_TYPE = EXPORT_AS_TO_TYPE;
+exports.MEMBERS_BY_TYPE = MEMBERS_BY_TYPE;
+exports.RADIO_PACKAGE = RADIO_PACKAGE;
+exports.REMOVED_TOKENS_MESSAGE = REMOVED_TOKENS_MESSAGE;
+exports.REMOVED_TOKENS_PATTERN = REMOVED_TOKENS_PATTERN;
+exports.SUMMARY = SUMMARY;
+exports.UNPARSEABLE_TEMPLATE_MESSAGE = UNPARSEABLE_TEMPLATE_MESSAGE;
+exports.UNRESOLVED_RECEIVER_MESSAGE = UNRESOLVED_RECEIVER_MESSAGE;
+exports.WRITABLE_MEMBERS = WRITABLE_MEMBERS;
+exports.config = config;
+exports.warnPatterns = warnPatterns;

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

@@ -0,0 +1,39 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var schematics = require('@angular-devkit/schematics');
+var utils_messages = require('../../utils/messages.js');
+var utils_packageConfig = require('../../package-config-BhU2TfC8.js');
+var signalMembersMigration = require('../../signal-members-migration-BoAJKutT.js');
+var migrations_radioSignalsAndAria_data = require('./data.js');
+require('@schematics/angular/utility');
+require('typescript');
+require('../../utils/ast.js');
+require('../../utils/typescript.js');
+
+const STYLE_EXTENSIONS = ['.scss', '.css'];
+/**
+ * The two removed custom properties are a stylesheet concern, and the shared engine visits only `.ts`
+ * and `.html`. Reports an override of either; never writes, because the declaration has no replacement.
+ */
+function removedTokensRule(options) {
+    return async (tree, context) => {
+        const projectDefinition = await utils_packageConfig.setupOptions(options.project, tree);
+        const root = projectDefinition?.root ?? '';
+        const rootDir = root ? tree.getDir(root) : tree.root;
+        utils_packageConfig.visitProjectFiles(rootDir, (filePath, entry) => {
+            if (!STYLE_EXTENSIONS.some((extension) => filePath.endsWith(extension)))
+                return;
+            const content = entry?.content.toString();
+            if (!content || !new RegExp(migrations_radioSignalsAndAria_data.REMOVED_TOKENS_PATTERN).test(content))
+                return;
+            utils_messages.logMessage(context.logger, [`${migrations_radioSignalsAndAria_data.config.label} ${filePath}`, `  ${migrations_radioSignalsAndAria_data.REMOVED_TOKENS_MESSAGE}`]);
+        });
+    };
+}
+function radioSignalsAndAria(options) {
+    return schematics.chain([removedTokensRule(options), signalMembersMigration.signalMembersRule(migrations_radioSignalsAndAria_data.config, options)]);
+}
+
+exports.default = radioSignalsAndAria;

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

@@ -0,0 +1,20 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-radio-signals-and-aria",
+    "title": "Koobiq components radio signals and aria 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/read-state-dwell-handlers/README.md

@@ -0,0 +1,125 @@
+# read-state-dwell-handlers
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21`
+(registered for `21.0.0-0`). Renames the `KbqReadStateDirective` dwell handlers and reports the two
+changes a rename cannot cover.
+
+## Background
+
+`KbqReadStateDirective` marks its host as read once the user has dwelled on it long enough. It used
+to measure the pointer only, so its two handlers were named after the events that called them. It now
+measures a keyboard dwell as well, so they are named after what they measure:
+
+| Before                | After          |
+| --------------------- | -------------- |
+| `mouseenterHandler()` | `startDwell()` |
+| `mouseleaveHandler()` | `endDwell()`   |
+
+Both new names take an optional channel argument that defaults to the pointer, so a renamed call keeps
+compiling and keeps meaning exactly what it did.
+
+## What it does
+
+The schematic walks every `.ts` file under the project root — the whole workspace when `--project` is
+omitted, which is how `ng update` invokes it — skipping `node_modules` and `dist`, and visits only the
+files that name `KbqReadStateDirective`. The directive has no selector: a consumer reaches it through
+`hostDirectives` and `inject()`, so it is always named.
+
+Within such a file the rename is applied to receivers whose static type is the directive, discovered
+by explicit annotation (parameters, class fields, constructor parameter-properties, typed locals) or
+by an `inject(KbqReadStateDirective, …)` / `inject<KbqReadStateDirective>(…)` initializer — the shape
+a host normally writes, which usually carries no annotation. A method of the same name on an
+unrelated receiver is left alone, and a call that already uses the new name is untouched, so the
+migration is idempotent.
+
+## What it does _not_ do (manual)
+
+| Pattern                                   | Manual migration                                                                                                                                                           |
+| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `readState.timestamp`                     | Reported. It is a read-only getter now, and `number \| undefined`: it reports the start of the earliest dwell still in progress, and is `undefined` while the host is idle |
+| `hostDirectives: [KbqReadStateDirective]` | Reported once per file. Nothing to change — it is the behaviour note below                                                                                                 |
+
+### Behaviour change
+
+The pointer and the keyboard channel are tracked independently and the dwell ends only once both have
+left the host. Two consequences no call site can point at:
+
+- A host that keeps focus for longer than `timeToRead` is marked read without a pointer ever touching
+  it.
+- A pointer leaving no longer ends a dwell that focus is still holding open, so the host is reported
+  read later than it used to be when both were in play.
+
+`fix` defaults to `true`. `ng update` invokes migrations with no options at all, and `migrations.json`
+declares no schema, so the rule applies that default itself. With `--fix false` every file that would
+change is logged instead of written, followed by the same count either way. The reports are printed
+in both modes.
+
+[Params](schema.ts)
+
+Usage for Angular Cli:
+
+```shell
+ng g @koobiq/components:read-state-dwell-handlers --project "<your project>"
+```
+
+Usage for Nx:
+
+```shell
+nx g @koobiq/components:read-state-dwell-handlers --project "<your project>"
+```
+
+### Run locally
+
+Build package
+
+```shell
+yarn run build:schematics
+```
+
+Run command (for example, for `koobiq-docs` project)
+
+```shell
+ng g ./dist/components/schematics/collection.json:read-state-dwell-handlers --project koobiq-docs
+```
+
+### Result
+
+#### Before
+
+```ts
+import { Component, inject } from '@angular/core';
+import { KbqReadStateDirective } from '@koobiq/components/core';
+
+@Component({
+    selector: 'my-card',
+    template: '...',
+    hostDirectives: [KbqReadStateDirective]
+})
+export class MyCard {
+    protected readonly readState = inject(KbqReadStateDirective, { host: true });
+
+    reveal() {
+        this.readState.mouseenterHandler();
+    }
+}
+```
+
+#### After
+
+```ts
+import { Component, inject } from '@angular/core';
+import { KbqReadStateDirective } from '@koobiq/components/core';
+
+@Component({
+    selector: 'my-card',
+    template: '...',
+    hostDirectives: [KbqReadStateDirective]
+})
+export class MyCard {
+    protected readonly readState = inject(KbqReadStateDirective, { host: true });
+
+    reveal() {
+        this.readState.startDwell();
+    }
+}
+```

package/schematics/migrations/read-state-dwell-handlers/data.js

@@ -0,0 +1,45 @@
+'use strict';
+
+/**
+ * Data for the `read-state-dwell-handlers` migration.
+ *
+ * `KbqReadStateDirective` no longer tracks the pointer only, so its handlers are named after what they
+ * measure rather than after the event that used to call them. Both new names keep working with no
+ * argument — the pointer channel is their default — so the rename is a safe, value-preserving rewrite.
+ *
+ * - `readState.mouseenterHandler()` → `readState.startDwell()`
+ * - `readState.mouseleaveHandler()` → `readState.endDwell()`
+ * - `readState.timestamp` → still there, but read-only and `number | undefined` (warn)
+ */
+/** TypeScript type annotation, and `inject()` argument, that marks a receiver as the directive. */
+const DIRECTIVE_TYPE = 'KbqReadStateDirective';
+/** Renamed methods, old name → new name. Both are callable with no argument, as before. */
+const RENAMES = new Map([
+    ['mouseenterHandler', 'startDwell'],
+    ['mouseleaveHandler', 'endDwell']
+]);
+/** Members that changed shape rather than name, so they are reported instead of rewritten. */
+const WARN_MEMBERS = ['timestamp'];
+/** Message emitted for a receiver-scoped read of one of {@link WARN_MEMBERS}. */
+const TIMESTAMP_MESSAGE = 'KbqReadStateDirective.timestamp is a read-only getter now, and `number | undefined` rather than `number`: it ' +
+    'reports the start of the earliest dwell still in progress and is `undefined` while the host is neither ' +
+    'hovered nor focused. Writing to it is no longer possible — call startDwell()/endDwell() instead.';
+/**
+ * File-scoped patterns for the change no call site can point at. Only evaluated for files that name
+ * the directive.
+ */
+const warnPatterns = [
+    {
+        pattern: 'hostDirectives[^\\]]*\\bKbqReadStateDirective\\b',
+        message: 'KbqReadStateDirective now measures a keyboard dwell (`focusin`/`focusout`) alongside the pointer one, ' +
+            'and reports the host as read once both channels have left it. A host that keeps focus for longer than ' +
+            '`timeToRead` is therefore marked read without a pointer ever touching it, and a pointer leaving no ' +
+            'longer ends a dwell that focus is still holding open.'
+    }
+];
+
+exports.DIRECTIVE_TYPE = DIRECTIVE_TYPE;
+exports.RENAMES = RENAMES;
+exports.TIMESTAMP_MESSAGE = TIMESTAMP_MESSAGE;
+exports.WARN_MEMBERS = WARN_MEMBERS;
+exports.warnPatterns = warnPatterns;