@koobiq/components 20.4.2 → 21.0.0

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

@@ -0,0 +1,15 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-input-signals",
+    "title": "Koobiq components input 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/link-deprecated-path/README.md

@@ -0,0 +1,144 @@
+# link-deprecated-path
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21` (registered for
+`21.0.0-0`). Rewrites `@koobiq/components/link` imports to `@koobiq/components/link/deprecated`.
+
+## Background
+
+`@koobiq/components/link` now resolves to the `KbqLink` component with the `[kbqLink]` selector. It
+renders the underlined text itself, between the `kbqLinkPrefix` and `kbqLinkSuffix` slots, adds the
+external icon through the `external` input, takes its size from the `size` input and its underline
+from the `underline` input, covers the gaps between the lines of a wrapped link by itself, makes a link on any element but an `<a>` a pseudo link with the `button` role
+and Enter and Space, and stops the click on a disabled link. The previous directive - `KbqLink` and
+`KbqLinkModule` with the `[kbq-link]` selector, whose markup needed the `kbq-link__text` wrapper and
+the `kbq-link_external` and `kbq-text-with-dot` classes - moved to
+`@koobiq/components/link/deprecated` and will be removed in a future major version.
+
+Nothing about the directive changed: its inputs, the `[kbq-link]` selector, the `kbqLink` export
+name and the classes its markup relies on behave exactly as before at the new path. Rewriting the
+import is the whole migration - adopting the component is a separate, manual step.
+
+## Behaviour change
+
+An unmigrated import keeps compiling, and that is why the migration exists: both entry points
+export `KbqLink` and `KbqLinkModule`. Without the rewrite the import brings in the component, whose
+selector is `[kbqLink]`, so the `kbq-link` attribute in the templates matches nothing and the links
+lose their styles.
+
+## 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 rewrites
+the module specifier `@koobiq/components/link` to `@koobiq/components/link/deprecated`.
+
+The match is quote-anchored (`(['"])@koobiq/components/link\1`), so only the exact, bare specifier
+is taken, in the quote style it was written in:
+
+| Specifier                                    | Result                                                                                 |
+| -------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `'@koobiq/components/link'`                  | rewritten, still single-quoted                                                         |
+| `"@koobiq/components/link"`                  | rewritten, still double-quoted                                                         |
+| `'@koobiq/components/link/deprecated'`       | untouched - the migration is idempotent                                                |
+| `'@koobiq/components/link-x'` (hypothetical) | untouched - the closing quote is required, so a longer specifier is not a prefix match |
+
+It is a textual replacement rather than an AST rewrite, so an `import`, an `export … from`, a
+dynamic `import()` and a specifier handed to something like `jest.mock()` are all covered by the
+same pass.
+
+## What it does _not_ do (manual)
+
+| Pattern                          | Manual migration                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A specifier outside a `.ts` file | Only `.ts` files are visited - the same string in a JSON config or a documentation snippet stays as written                                                                                                                                                                                                                                                                                                                                                 |
+| Templates                        | Left as written; they keep working against the directive at its new path                                                                                                                                                                                                                                                                                                                                                                                    |
+| Moving off `/deprecated`         | Nothing is migrated _to_ the component: rename `kbq-link` to `kbqLink`, `big` / `compact` to `size` and `noUnderline` to `underline="none"`, drop `multiline`, drop `pseudo` from a host that is not an `<a>` and the `kbq-link__text` wrapper, mark a leading icon with `kbqLinkPrefix` and a trailing one with `kbqLinkSuffix`, replace `kbq-link_external` and its north-east icon with `external`, and the `kbq-text-with-dot` dot with `kbqLinkSuffix` |
+
+`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.
+
+[Params](schema.ts)
+
+Usage for Angular Cli:
+
+```shell
+ng g @koobiq/components:link-deprecated-path --project "<your project>"
+```
+
+Usage for Nx:
+
+```shell
+nx g @koobiq/components:link-deprecated-path --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:link-deprecated-path --project koobiq-docs
+```
+
+### Result
+
+#### Before
+
+```ts
+import { Component } from '@angular/core';
+import { KbqIconModule } from '@koobiq/components/icon';
+import { KbqLinkModule } from '@koobiq/components/link';
+
+@Component({
+    selector: 'my-page',
+    imports: [KbqLinkModule, KbqIconModule],
+    template: `
+        <a class="kbq-link_external" href="https://koobiq.io" target="_blank" kbq-link>
+            <span class="kbq-link__text">Koobiq</span>
+            <i kbq-icon="kbq-north-east_16"></i>
+        </a>
+    `
+})
+export class MyPage {}
+```
+
+#### After
+
+```ts
+import { Component } from '@angular/core';
+import { KbqIconModule } from '@koobiq/components/icon';
+import { KbqLinkModule } from '@koobiq/components/link/deprecated';
+
+@Component({
+    selector: 'my-page',
+    imports: [KbqLinkModule, KbqIconModule],
+    template: `
+        <a class="kbq-link_external" href="https://koobiq.io" target="_blank" kbq-link>
+            <span class="kbq-link__text">Koobiq</span>
+            <i kbq-icon="kbq-north-east_16"></i>
+        </a>
+    `
+})
+export class MyPage {}
+```
+
+#### With the component
+
+```ts
+import { Component } from '@angular/core';
+import { KbqLinkModule } from '@koobiq/components/link';
+
+@Component({
+    selector: 'my-page',
+    imports: [KbqLinkModule],
+    template: `
+        <a href="https://koobiq.io" target="_blank" kbqLink external>Koobiq</a>
+    `
+})
+export class MyPage {}
+```

package/schematics/migrations/link-deprecated-path/index.js

@@ -0,0 +1,19 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var utils_deprecatedPathMigration = require('../../utils/deprecated-path-migration.js');
+require('../../utils/messages.js');
+require('../../package-config-BhU2TfC8.js');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+/**
+ * `@koobiq/components/link` now resolves to the `KbqLink` component, which renders the text, the slots
+ * and the external icon itself - the directive it used to export (`KbqLink`, `KbqLinkModule`) moved to
+ * `@koobiq/components/link/deprecated`. This rewrites the import specifier only; the API itself is
+ * unchanged at its new path.
+ */
+var index = utils_deprecatedPathMigration.deprecatedPathMigration('link');
+
+exports.default = index;

package/schematics/migrations/link-deprecated-path/schema.json

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

@@ -0,0 +1,71 @@
+# link-signals
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21` (registered for
+`21.0.0-0`). Migrates `KbqLink` consumers to its finished signal-based API and reports the members
+the review closed.
+
+## Background
+
+The three inputs the automated signal migration skipped were all accessors, and each did something
+beyond storing a value:
+
+```ts
+set disabled(value: boolean) { this.disabledSignal.set(value); }
+get tabIndex(): number { return this.disabled ? -1 : this._tabIndex; }
+set print(value: any) { this.printMode = value !== null; this._print = value; this.updatePrintUrl(); }
+```
+
+`disabledSignal` stays a public `WritableSignal<boolean>`: `kbqTooltip` accepts a link through
+`forDisabledComponent` and reads it, and that contract is typed on the tooltip side. It is a
+`linkedSignal` over the input now, so binding `[disabled]` still drives it and a direct write still
+wins.
+
+## What it rewrites
+
+| Before          | After             |
+| --------------- | ----------------- |
+| `link.disabled` | `link.disabled()` |
+
+On receivers explicitly typed `KbqLink`. Already-migrated reads are left alone, so the schematic is
+idempotent. There is no template-reference pass: `kbq-link` is an attribute on an anchor, so a
+`#ref="kbqLink"` read is not tied to an element name the schematic can match.
+
+## What it does _not_ do
+
+| Pattern                                         | Manual migration                                                                   |
+| ----------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `.tabIndex`                                     | `tabIndex()`, and expect what was bound — not `-1` for a disabled link             |
+| `link.print = …`                                | Bind `[print]`; it was a setter with no getter, so there is no read to fix         |
+| `.icons` / `.nativeElement`                     | Now `private`; call `getHostElement()` for the host                                |
+| `.hasIcon` / `.printMode` / `.printUrl`         | Now `protected`; the `kbq-link_print` class and `print` attribute are the contract |
+| `.icon` / `.destroyRef` / `.ngAfterContentInit` | Gone; `icons` answers what `icon` did, and the hook is not implemented             |
+| `viewChild(KbqLink)`                            | The query returns the instance, so a read through it is a double call              |
+
+`tabIndex` is warned about rather than rewritten because appending `()` would compile and hand back
+a different number for a disabled link. A write of any kind — `=`, `||=`, `++` — is reported rather
+than rewritten: every member is an `input()`, so there is no writable half, and appending `()` would
+turn a read-only error into a syntax error.
+
+## Notes with no call site to point at
+
+- **`[print]="undefined"` no longer marks the link as printable.** The old setter tested
+  `value !== null`, so an explicit `undefined` passed it: the link got `kbq-link_print` and printed
+  its `href`. The input tests `!= null`, which covers both. An unbound link behaves exactly as
+  before — no class, and the href still lands in the `print` attribute. `print` accepts
+  `string | null` instead of `any`.
+- **Reading `disabled` reports the bound input.** The effective state — what the host bindings
+  render — is `disabledSignal()`. The two only differ if something writes `disabledSignal` directly,
+  which is what `kbqTooltip` does through `forDisabledComponent`. This one is reported next to every
+  file the rewrite touched rather than once per project, because the rewrite it applies is correct
+  but not value-identical.
+- **A disabled link carries `aria-disabled` instead of `disabled`.** `disabled` is not valid on an
+  `<a>` or a `<span>` and told assistive tech nothing. `kbq-disabled` and `tabindex="-1"` are
+  unchanged; a selector on `a[kbq-link][disabled]` needs `.kbq-disabled` or `[aria-disabled]`.
+
+## Running it manually
+
+```
+ng generate @koobiq/components:link-signals --project my-app
+```
+
+Pass `--fix=false` to see what it would change without writing.

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

@@ -0,0 +1,116 @@
+'use strict';
+
+/**
+ * Data for the `link-signals` migration.
+ *
+ * The three inputs the automated signal migration skipped were all accessors, and each of them did
+ * something beyond storing a value.
+ *
+ * - `link.disabled` → `link.disabled()` (auto-fixed, with a caveat about what it reports)
+ * - `link.tabIndex` → a signal whose value changed: the getter folded in the disabled state (warn)
+ * - `link.print` → was write-only (a setter with no getter), so it has no read to rewrite (warn on writes)
+ * - the icon and print bookkeeping → `protected`, `private` or gone (warn)
+ *
+ * `disabledSignal` stays a public `WritableSignal<boolean>`: `kbqTooltip` accepts a link through
+ * `forDisabledComponent` and reads it, and that contract is typed on the tooltip side.
+ */
+/** Members of `KbqLink` a read of which must become a call. Auto-fixed. */
+const SIGNAL_MEMBERS = ['disabled'];
+/** Signal-API methods reachable on a signal; a read followed by one is already migrated. */
+const SIGNAL_API_METHODS = new Set(['set', 'update', 'asReadonly', 'subscribe']);
+/** TypeScript type annotation that marks a receiver as a link. */
+const LINK_TYPE = 'KbqLink';
+/** Import specifier that marks a file as a link consumer. */
+const LINK_PACKAGE = '@koobiq/components/link';
+/**
+ * `tabIndex` became a read-only `InputSignal` AND changed its value: the getter returned `-1` for a
+ * disabled link, it now reports what was bound. The host attribute still goes to `-1` while the link is
+ * disabled, so nothing about focus behavior changed — only a programmatic read sees the difference, and a
+ * mechanical `()` append would silently change it.
+ */
+const VALUE_CHANGED_MEMBERS = ['tabIndex'];
+/** The write-only input: a setter with no getter, so there is no read to rewrite. */
+const WRITE_ONLY_MEMBERS = ['print'];
+/** Icon and print bookkeeping that became `protected`: a subclass still sees it, nothing outside does. */
+const PROTECTED_MEMBERS = ['hasIcon', 'printMode', 'printUrl'];
+/** Members that became `private`, so not even a subclass can name them. */
+const PRIVATE_MEMBERS = ['icons', 'nativeElement'];
+/** Members that are gone from the class altogether, including the lifecycle hook a subclass could call. */
+const REMOVED_MEMBERS = ['icon', 'destroyRef', 'ngAfterContentInit'];
+/** Every member a consumer can no longer read, whichever visibility it landed on. */
+const HIDDEN_MEMBERS = [...PROTECTED_MEMBERS, ...PRIVATE_MEMBERS, ...REMOVED_MEMBERS];
+/** Every member the access pass looks at, whatever it ends up doing with it. */
+const KNOWN_MEMBERS = [
+    ...SIGNAL_MEMBERS,
+    ...VALUE_CHANGED_MEMBERS,
+    ...WRITE_ONLY_MEMBERS,
+    ...HIDDEN_MEMBERS
+];
+const protectedMessage = (members) => `These KbqLink members are \`protected\` now: ${[...members].join(', ')}. They are the print and icon ` +
+    'bookkeeping: the classes and the `print` attribute the directive puts on the anchor are the contract, ' +
+    'not the state behind them.';
+const privateMessage = (members) => `These KbqLink members are \`private\` now, so a subclass cannot name them either: ` +
+    `${[...members].join(', ')}. \`nativeElement\` has a public accessor - call \`getHostElement()\`; the ` +
+    'icon query is internal, and the icon spacing classes are what it produces.';
+const removedMessage = (members) => `These KbqLink members are gone: ${[...members].join(', ')}. \`icon\` is dropped - \`icons\` already ` +
+    'answered the one question it was asked - `destroyRef` is not held any more, so inject `DestroyRef` ' +
+    'yourself if a subclass needs it, and `ngAfterContentInit` is not implemented, so an override calling ' +
+    '`super.ngAfterContentInit()` no longer compiles: the icon classes follow the content query on their own.';
+/** Reported for a programmatic write: every member is an `input()`, so the write no longer compiles. */
+const writeMessage = (members) => `These are \`input()\`s now, so a programmatic write no longer compiles: ${[...members].join(', ')}. ` +
+    'Bind them in the template instead. `print` was a write-only input - a setter with no getter - and ' +
+    '`tabIndex` had a setter too. The write is left untouched so the error points at your call site.';
+const valueChangedMessage = (members) => `${[...members].join(', ')} is a read-only InputSignal - read it as \`link.tabIndex()\`. Its value also ` +
+    'changed: the getter used to fold in the disabled state and report -1 for a disabled link, it now ' +
+    'reports what was bound. The host attribute still goes to -1 while the link is disabled. Migrate by hand.';
+/**
+ * Emitted next to the files the rewrite touched, because the call it writes is correct but does not report
+ * quite the same value. The old getter mirrored `disabledSignal`, which `kbqTooltip` writes directly through
+ * `forDisabledComponent`; the input reports only what was bound.
+ */
+const DISABLED_CAVEAT = '  `disabled` reads here were rewritten to `disabled()`. That reports the bound input, while the old ' +
+    'getter mirrored `disabledSignal` - the effective state the host bindings render. The two differ only ' +
+    'if something writes `disabledSignal` directly, which is what `kbqTooltip` does through ' +
+    '`forDisabledComponent`: read `disabledSignal()` at those call sites.';
+/**
+ * Reported for a read through a signal query, which is a signal holding the directive: the read needs two
+ * calls rather than one. Emitted from the AST pass rather than a regex, so it follows the same receiver
+ * resolution as the rewrite - the decorator form is a plain annotated field that the rewrite handles.
+ *
+ * `viewChild()` without `.required` is typed `Signal<KbqLink | undefined>`, so the safe spelling differs
+ * between the two forms.
+ */
+const signalQueryMessage = (member, required) => `A signal query holds the directive behind a call of its own, so reading \`${member}\` through it needs ` +
+    `a double call: \`this.link()${required ? '' : '?'}.${member}()\`.` +
+    (required ? '' : ' The query is optional, so keep the `?.`.') +
+    ' Those reads are left untouched - migrate them by hand.';
+/** Printed once per project, after the per-file reports. */
+const SUMMARY = [
+    '  `print` accepts `string | null` instead of `any`, and `[print]="undefined"` no longer marks the link ' +
+        'as printable. The old setter tested `value !== null`, so an explicit `undefined` passed it and added ' +
+        '`kbq-link_print` while printing the href; the input tests `!= null`, which covers both. An unbound ' +
+        'link behaves exactly as before: no class, and the href still lands in the `print` attribute.',
+    '  A disabled link carries `aria-disabled` instead of the `disabled` attribute, which is not valid HTML ' +
+        'on an anchor and told assistive tech nothing. If you styled `a[kbq-link][disabled]`, match ' +
+        '`.kbq-disabled` or `[aria-disabled]` instead.'
+];
+
+exports.DISABLED_CAVEAT = DISABLED_CAVEAT;
+exports.HIDDEN_MEMBERS = HIDDEN_MEMBERS;
+exports.KNOWN_MEMBERS = KNOWN_MEMBERS;
+exports.LINK_PACKAGE = LINK_PACKAGE;
+exports.LINK_TYPE = LINK_TYPE;
+exports.PRIVATE_MEMBERS = PRIVATE_MEMBERS;
+exports.PROTECTED_MEMBERS = PROTECTED_MEMBERS;
+exports.REMOVED_MEMBERS = REMOVED_MEMBERS;
+exports.SIGNAL_API_METHODS = SIGNAL_API_METHODS;
+exports.SIGNAL_MEMBERS = SIGNAL_MEMBERS;
+exports.SUMMARY = SUMMARY;
+exports.VALUE_CHANGED_MEMBERS = VALUE_CHANGED_MEMBERS;
+exports.WRITE_ONLY_MEMBERS = WRITE_ONLY_MEMBERS;
+exports.privateMessage = privateMessage;
+exports.protectedMessage = protectedMessage;
+exports.removedMessage = removedMessage;
+exports.signalQueryMessage = signalQueryMessage;
+exports.valueChangedMessage = valueChangedMessage;
+exports.writeMessage = writeMessage;