@koobiq/components 20.4.2 → 21.0.0

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

@@ -0,0 +1,111 @@
+# navbar-signals-and-aria
+
+Migration schematic invoked automatically by `ng update @koobiq/components`.
+Migrates consumers of `@koobiq/components/navbar` to its signal-based API and reports the accessibility,
+composition and layering changes of the navbar review.
+
+## Why
+
+The review finished the signal migration of the navbar, replaced the inheritance from `KbqTooltipTrigger` on
+`KbqNavbarItem` / `KbqNavbarBrand` with composition, collapsed the two mutually derived orientation booleans of
+`KbqNavbarRectangleElement` into one `orientation`, and moved the disabled state and the accessible names onto
+standard ARIA attributes.
+
+Template _bindings_ keep working — `[expanded]`, `[collapsable]`, `[collapsedText]`, `[kbqPlacement]`,
+`[kbqTrigger]` are unchanged — except `[kbqTooltip]` on items and brands, which becomes `[tooltipText]`. Beyond
+that rename, what breaks is programmatic access and reads through a template reference variable.
+
+| Member                                               | Before                 | After                                             | Auto-fix                         |
+| ---------------------------------------------------- | ---------------------- | ------------------------------------------------- | -------------------------------- |
+| `KbqVerticalNavbar.expanded`                         | `@Input()` accessor    | `ModelSignal<boolean>`                            | ✅ read → call, write → `.set()` |
+| `KbqVerticalNavbar.configuration`                    | untyped field          | `WritableSignal<KbqNavbarLocaleConfiguration>`    | ✅ read → call                   |
+| `KbqVerticalNavbar.openOver`                         | `input()`              | unchanged (call)                                  | ✅ read → call                   |
+| `KbqFocusableComponent.tabIndex`                     | `@Input()` accessor    | `ModelSignal<number>`                             | ✅ read → call, write → `.set()` |
+| `KbqNavbarItem.isCollapsed`                          | getter                 | `Signal<boolean>`                                 | ✅ read → call                   |
+| `KbqNavbarItem.collapsable` / `collapsedText`        | `@Input()` accessors   | `input()` signals                                 | ✅ read → call                   |
+| `KbqNavbarBrand.collapsed` / `collapsedText`         | getter / accessor      | `Signal<boolean>` / `input()`                     | ✅ read → call                   |
+| `KbqNavbarRectangleElement.horizontal` / `vertical`  | boolean accessors      | `isHorizontal()` / `isVertical()` + `orientation` | ✅ read and `= true` write       |
+| `[kbqTooltip]` on an item or a brand                 | inherited input        | `[tooltipText]`                                   | ✅ template rename               |
+| `KbqNavbarItem.disabled` / `KbqNavbarBrand.disabled` | tooltip suppression    | removed                                           | ⚠️ warn                          |
+| `content` / `show()` / `hide()` / `visibleChange`    | inherited from tooltip | owned tooltip (`item.tooltip.*`)                  | ⚠️ warn                          |
+| `KbqNavbarLogo.hovered` / `KbqNavbarTitle.hovered`   | `Subject<boolean>`     | removed                                           | ⚠️ warn                          |
+| `KbqVerticalNavbar.animationDone`                    | `Subject<void>`        | removed                                           | ⚠️ warn                          |
+| `KbqNavbarContainerPositionType`                     | exported type          | removed                                           | ⚠️ warn                          |
+
+## What it does (auto-fix)
+
+The schematic walks every `.ts`, `.html`, `.scss` and `.css` file in the project (skipping `node_modules` and
+`dist`) and, for files that reference the navbar:
+
+- **TypeScript access.** For a receiver whose static type is annotated with one of the navbar classes
+  (method/function params, class fields — including `@ViewChild(KbqVerticalNavbar) x: KbqVerticalNavbar` and
+  constructor parameter-properties — and typed locals):
+    - `navbar.expanded` → `navbar.expanded()` (incl. optional chain `navbar?.expanded`)
+    - `navbar.expanded = true` → `navbar.expanded.set(true)`
+    - `element.horizontal` → `element.isHorizontal()`, and `element.horizontal = true` →
+      `element.orientation = 'horizontal'`
+- **Template reference reads.** For a `#ref="KbqVerticalNavbar"`, `#ref="kbqNavbarItem"` or
+  `#ref="kbqNavbarBrand"` (also the `ref-x="…"` form), reads through that ref are rewritten in the same template,
+  external `.html` and inline `template:` strings alike: `navbar.expanded` → `navbar.expanded()`.
+- **Tooltip content binding.** On `kbq-navbar-item` and `kbq-navbar-brand`, used as an element or as an
+  attribute, `kbqTooltip` becomes `tooltipText` in every form — `kbqTooltip="…"`, `[kbqTooltip]`,
+  `bind-kbqTooltip`, `i18n-kbqTooltip` — in external and inline templates alike. `kbqTooltip` is the tooltip
+  directive's selector, so on a host that already owns a tooltip it matched that directive a second time
+  wherever the tooltip module was imported, which Angular rejects with `NG0309`. On any other element it is
+  left alone.
+
+All rewrites are idempotent — an access already followed by `()`, `.set`, `.update`, `.asReadonly` or
+`.subscribe` is left alone, so running twice does not double the call.
+
+A member backed by `input()` rather than `model()` (`collapsable`, `collapsedText`, `openOver`) cannot be
+written to at all; such an assignment is left in place for the compiler to point at, because the fix is to drive
+it from the binding.
+
+## What it does _not_ do (warn-only)
+
+| Change                                              | Manual migration                                                                                                                                                                                                                       |
+| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `item.disabled` / `brand.disabled`                  | Removed. They never meant "not interactive" — they suppressed the tooltip — while colliding with the real disabled state of the same element. Read `item.navbarFocusableItem.disabled`; control the tooltip with `kbqTooltipDisabled`. |
+| `item.content`, `item.show()`, `item.visibleChange` | `KbqNavbarItem` / `KbqNavbarBrand` own a `KbqTooltipTrigger` instead of extending one: `item.tooltip.content`, `item.tooltip.show()`, `item.tooltip.visibleChange`.                                                                    |
+| `item.updateDropdown()`                             | Private now — the item refreshes its dropdown itself on every orientation or collapse change.                                                                                                                                          |
+| `logo.hovered` / `title.hovered`                    | Removed: nothing subscribed to them and they were never completed. Bind the pointer enter/leave events on the element instead.                                                                                                         |
+| `navbar.animationDone`                              | Removed: nothing has emitted it since the expand/collapse animation was removed, so a subscription never ran. Delete it; to react to a toggle, bind `(expandedChange)` or read `expanded()` in an `effect()`.                          |
+| `KbqNavbarContainerPositionType`                    | Removed — it had no consumer and `KbqNavbarContainer` has no position input.                                                                                                                                                           |
+| `kbq-navbar-item[disabled]` in a stylesheet         | A disabled item renders `aria-disabled="true"` and `.kbq-disabled`, never the `disabled` content attribute, which is meaningless on a custom element.                                                                                  |
+
+## Behaviour changes with no call site to migrate
+
+Printed once per run:
+
+- `Ctrl+/` toggles one vertical navbar — the one holding focus, falling back to the first on the page. It used
+  to toggle every one of them at once, because each toggle bound its own window listener.
+- The horizontal and the vertical navbar are both announced as `role="navigation"` landmarks and accept an
+  `aria-label` input. An item authored as `<kbq-navbar-item>` (not as `<a>`/`<button>`, and not wrapping a
+  button or form field) is announced as `role="button"` and answers to Enter/Space; `<kbq-navbar-divider>` is
+  `role="separator"`.
+- A collapsed item or brand publishes its title as `aria-label`. Set the new `aria-label` input on an icon-only
+  item that has no title of its own — a tooltip alone never named it.
+- An item or brand without a title no longer suppresses its own tooltip: `[tooltipText]` on an icon-only item
+  shows without `[kbqTooltipDisabled]="false"`.
+- `.kbq-navbar` left the CDK overlay layer (1000). The navbar, its toggle and an open-over container read
+  `--kbq-navbar-z-index` / `--kbq-navbar-toggle-z-index` / `--kbq-navbar-vertical-open-over-z-index`
+  (990 / 991 / 989).
+- Hard-coded sizes became tokens: `--kbq-navbar-vertical-size-expanded-width`,
+  `--kbq-navbar-item-vertical-size-height`, `--kbq-navbar-toggle-size-circle`,
+  `--kbq-navbar-brand-vertical-size-title-max-width`.
+- `!important` is gone from the collapsed brand title and the navbar item icon color; both now win on
+  specificity. An override that relied on losing to `!important` may start applying.
+
+## Running it manually
+
+```
+ng generate @koobiq/components:navbar-signals-and-aria --project my-app
+```
+
+Pass `--fix=false` to see what would change without writing files.
+
+## Limitations
+
+Receivers are matched by explicit type annotation only (no cross-package type inference), so aliased or inferred
+receivers (`const n = this.navbar; n.expanded`) are left untouched. After running, **always inspect the diff**
+and act on the warnings before committing.

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

@@ -0,0 +1,198 @@
+'use strict';
+
+/**
+ * Data for the `navbar-signals-and-aria` migration.
+ *
+ * The navbar review turned the remaining `@Input()` accessors into signals, replaced the inheritance from
+ * `KbqTooltipTrigger` on `KbqNavbarItem` / `KbqNavbarBrand` with composition, collapsed the mutually derived
+ * `horizontal` / `vertical` booleans of `KbqNavbarRectangleElement` into a single `orientation`, and moved the
+ * accessibility state onto standard ARIA attributes.
+ *
+ * Template *bindings* (`[expanded]`, `[collapsable]`, `[collapsedText]`, `[kbqPlacement]`, …) keep working, except
+ * `[kbqTooltip]` on items and brands, which is renamed to `[tooltipText]`; what breaks otherwise is programmatic
+ * access and reads through a template reference variable.
+ */
+const RECEIVER_TYPES = [
+    {
+        type: 'KbqVerticalNavbar',
+        exportAs: 'KbqVerticalNavbar',
+        signalMembers: ['expanded', 'configuration', 'openOver', 'tabIndex'],
+        writableMembers: ['expanded', 'tabIndex']
+    },
+    {
+        type: 'KbqNavbar',
+        signalMembers: ['tabIndex'],
+        writableMembers: ['tabIndex']
+    },
+    {
+        type: 'KbqFocusableComponent',
+        signalMembers: ['tabIndex'],
+        writableMembers: ['tabIndex']
+    },
+    {
+        type: 'KbqNavbarItem',
+        exportAs: 'kbqNavbarItem',
+        signalMembers: ['isCollapsed', 'collapsable', 'collapsedText'],
+        writableMembers: []
+    },
+    {
+        type: 'KbqNavbarBrand',
+        exportAs: 'kbqNavbarBrand',
+        signalMembers: ['collapsed', 'collapsedText'],
+        writableMembers: []
+    },
+    // No signal members of their own — listed so a `hovered` access on a receiver typed as one of these (e.g.
+    // `@ViewChild(KbqNavbarLogo) logo: KbqNavbarLogo`) is recognized by `collectManualMembers` and warned about.
+    // Neither directive declares an `exportAs`, so there is no template-reference-variable path to cover.
+    {
+        type: 'KbqNavbarLogo',
+        signalMembers: [],
+        writableMembers: []
+    },
+    {
+        type: 'KbqNavbarTitle',
+        signalMembers: [],
+        writableMembers: []
+    }
+];
+/**
+ * Methods of the signal/model API. A member access followed by one of these is already migrated, so no `()` is
+ * appended. This is what makes the migration idempotent.
+ */
+const SIGNAL_API_METHODS = new Set(['set', 'update', 'asReadonly', 'subscribe']);
+/** Type annotation of the element whose two orientation booleans became one `orientation`. */
+const RECTANGLE_TYPE = 'KbqNavbarRectangleElement';
+/** `x.horizontal = true` → `x.orientation = 'horizontal'`; the same for `vertical`. */
+const ORIENTATION_WRITES = new Map([
+    ['horizontal', 'horizontal'],
+    ['vertical', 'vertical']
+]);
+/** `x.horizontal` → `x.isHorizontal()`; the same for `vertical`. */
+const ORIENTATION_READS = new Map([
+    ['horizontal', 'isHorizontal'],
+    ['vertical', 'isVertical']
+]);
+/** Selectors, as an element or as an attribute, of the navbar hosts that own a tooltip with a content input. */
+const TOOLTIP_TEXT_HOSTS = ['kbq-navbar-item', 'kbq-navbar-brand'];
+/**
+ * The tooltip content input on those hosts. `kbqTooltip` is the tooltip directive's selector, so wherever that
+ * directive is imported a host that already owns a tooltip matched it a second time (NG0309).
+ */
+const TOOLTIP_TEXT_RENAME = { from: 'kbqTooltip', to: 'tooltipText' };
+/**
+ * Members accessed on a navbar receiver that disappeared or changed their meaning. Reported with the file they
+ * were found in; never rewritten, because the replacement depends on what the call site wanted.
+ */
+const MANUAL_MEMBERS = new Map([
+    [
+        'disabled',
+        '`KbqNavbarItem.disabled` / `KbqNavbarBrand.disabled` are gone. They never meant "not interactive" — ' +
+            'they suppressed the tooltip — while sharing a name with the real disabled state of the same ' +
+            'element. Read the interactive state as `item.navbarFocusableItem.disabled`, and control the ' +
+            'tooltip with the `kbqTooltipDisabled` input (`item.tooltipDisabled()`).'
+    ],
+    [
+        'content',
+        '`KbqNavbarItem` / `KbqNavbarBrand` no longer extend `KbqTooltipTrigger`; they own one. Use ' +
+            '`item.tooltip.content` (the `[kbqTooltip]` binding is `[tooltipText]` now; this migration renames it ' +
+            'in templates when run with fixes applied).'
+    ],
+    [
+        'visibleChange',
+        '`KbqNavbarItem` / `KbqNavbarBrand` no longer extend `KbqTooltipTrigger`; they own one. Subscribe to ' +
+            '`item.tooltip.visibleChange` (the `(kbqVisibleChange)` binding is unchanged).'
+    ],
+    [
+        'updateDropdown',
+        '`KbqNavbarItem.updateDropdown()` is private now: the item refreshes its dropdown itself whenever the ' +
+            'ambient navbar changes orientation or collapses. Delete the call.'
+    ],
+    [
+        'hovered',
+        '`KbqNavbarLogo.hovered` / `KbqNavbarTitle.hovered` were removed — nothing ever subscribed to them and ' +
+            'they were never completed. Bind the pointer enter/leave events on the element instead.'
+    ],
+    [
+        'animationDone',
+        '`KbqVerticalNavbar.animationDone` was removed — nothing has emitted it since the expand/collapse animation ' +
+            'was removed, so a subscription to it never ran. Delete the subscription; to react to a toggle, bind ' +
+            '`(expandedChange)` or read `navbar.expanded()` in an `effect()`.'
+    ]
+]);
+/**
+ * Warnings for `.ts` files. Checked against the post-fix content, so an auto-fixed usage does not also produce
+ * a "manual migration required" note. Only evaluated for files that reference the navbar.
+ */
+const tsWarnPatterns = [
+    {
+        pattern: '\\bKbqNavbarContainerPositionType\\b',
+        message: '`KbqNavbarContainerPositionType` was removed: it had no consumer and `KbqNavbarContainer` has no ' +
+            'position input to feed it. Delete the import.'
+    },
+    {
+        pattern: '\\bKbqNavbarItem\\b[\\s\\S]{0,200}?\\.(?:show|hide)\\s*\\(',
+        message: '`show()` / `hide()` came from `KbqTooltipTrigger`, which `KbqNavbarItem` / `KbqNavbarBrand` no ' +
+            'longer extend. Call them on the owned trigger: `item.tooltip.show()`.'
+    },
+    {
+        pattern: '\\bKbqNavbarRectangleElement\\b',
+        message: '`KbqNavbarRectangleElement.horizontal` / `.vertical` are read-only derived signals now ' +
+            '(`isHorizontal()` / `isVertical()`); the orientation is written through `orientation = ' +
+            "'horizontal' | 'vertical'`. `collapsed` is still a boolean accessor, and `collapsedState` is its " +
+            'signal mirror for `computed()` consumers.'
+    },
+    {
+        pattern: '\\bKBQ_VERTICAL_NAVBAR_CONFIGURATION\\b',
+        message: '`KBQ_VERTICAL_NAVBAR_CONFIGURATION` is now `KBQ_NAVBAR_LOCALE_CONFIGURATION`, typed ' +
+            '`InjectionToken<KbqNavbarLocaleConfiguration>`, so a provided value is type-checked. The ' +
+            'strings are read from `KbqVerticalNavbar.localeConfiguration()`, a signal.'
+    }
+];
+/** Stylesheet warnings: the disabled state moved off a content attribute that never meant anything there. */
+const styleWarnPatterns = [
+    {
+        pattern: '(?:kbq-navbar-item|kbq-navbar-brand|kbq-navbar-toggle)[^{,]*\\[disabled\\]',
+        message: 'A disabled navbar item no longer renders the `disabled` content attribute — it is meaningless on ' +
+            'a custom element and ignored by assistive technology. Match `[aria-disabled="true"]` or the ' +
+            '`.kbq-disabled` class instead.'
+    }
+];
+/** Behaviour changes that no usage pattern can point at, printed once per run. */
+const BEHAVIOUR_NOTE = [
+    'Behaviour changes with no call site to migrate:',
+    '- Ctrl+/ now toggles one vertical navbar - the one holding focus, falling back to the first on the page.',
+    '  It used to toggle every one of them at once, because each toggle bound its own window listener.',
+    '- The horizontal and the vertical navbar are both announced as `role="navigation"` landmarks and accept',
+    '  an `aria-label` input. Items authored as `<kbq-navbar-item>` (not as `<a>`/`<button>`, and not wrapping',
+    '  a button or form field) are announced as `role="button"` and answer to Enter/Space;',
+    '  `<kbq-navbar-divider>` is `role="separator"`.',
+    '- A collapsed item or brand publishes its title as `aria-label`; the tooltip alone never named it. Set the',
+    '  new `aria-label` input on an icon-only item that has no title of its own.',
+    '- An item or brand without a title no longer suppresses its own tooltip: `[tooltipText]` on an icon-only',
+    '  item shows without `[kbqTooltipDisabled]="false"`.',
+    '- `.kbq-navbar` left the CDK overlay layer (1000). The navbar, its toggle and an open-over container now',
+    '  read `--kbq-navbar-z-index` / `--kbq-navbar-toggle-z-index` / `--kbq-navbar-vertical-open-over-z-index`',
+    '  (990 / 991 / 989), so overlays render above the navbar instead of fighting it for the same layer.',
+    '- The hard-coded sizes became tokens: `--kbq-navbar-vertical-size-expanded-width`,',
+    '  `--kbq-navbar-item-vertical-size-height`, `--kbq-navbar-toggle-size-circle` and',
+    '  `--kbq-navbar-brand-vertical-size-title-max-width`.',
+    '- `!important` is gone from the collapsed brand title and from the navbar item icon color; both now win',
+    '  on specificity. An override that relied on losing to `!important` may start applying.'
+];
+/** Reported when a template names a navbar but cannot be parsed, so nothing was rewritten in it. */
+const UNPARSEABLE_TEMPLATE_MESSAGE = 'This template references the navbar but could not be parsed, so it was left untouched. Rename ' +
+    '`kbqTooltip` on navbar items and brands to `tooltipText`, and migrate reads through its template ' +
+    'reference variables, by hand.';
+
+exports.BEHAVIOUR_NOTE = BEHAVIOUR_NOTE;
+exports.MANUAL_MEMBERS = MANUAL_MEMBERS;
+exports.ORIENTATION_READS = ORIENTATION_READS;
+exports.ORIENTATION_WRITES = ORIENTATION_WRITES;
+exports.RECEIVER_TYPES = RECEIVER_TYPES;
+exports.RECTANGLE_TYPE = RECTANGLE_TYPE;
+exports.SIGNAL_API_METHODS = SIGNAL_API_METHODS;
+exports.TOOLTIP_TEXT_HOSTS = TOOLTIP_TEXT_HOSTS;
+exports.TOOLTIP_TEXT_RENAME = TOOLTIP_TEXT_RENAME;
+exports.UNPARSEABLE_TEMPLATE_MESSAGE = UNPARSEABLE_TEMPLATE_MESSAGE;
+exports.styleWarnPatterns = styleWarnPatterns;
+exports.tsWarnPatterns = tsWarnPatterns;