@koobiq/components 20.4.1 → 21.0.0

package/schematics/migrations/tag-slots/README.md

@@ -0,0 +1,41 @@
+### Tag slots schematic
+
+This schematic migrates legacy implicit icons in `KbqTag` to the explicit `kbqTagPrefix` slot. The old tag
+template projected every element with `kbq-icon` before the label regardless of its source position, so every
+matching element receives `kbqTagPrefix`; the migration never guesses a suffix from source order. Elements
+with only `kbq-icon-button` or `kbq-icon-item` were not part of that legacy slot and remain unchanged.
+
+`kbqTagRemove`, `kbqTagEditSubmit`, and icons already marked with `kbqTagPrefix` or `kbqTagSuffix` are left
+unchanged.
+
+Usage for Angular CLI:
+
+```shell
+ng g @koobiq/components:tag-slots --project "<your project>"
+```
+
+Run without writing first:
+
+```shell
+ng g @koobiq/components:tag-slots --project "<your project>" --fix=false
+```
+
+#### Before
+
+```html
+<kbq-tag>
+    Tag
+    <i kbq-icon="kbq-circle-info_16"></i>
+    <i kbqTagRemove kbq-icon="kbq-xmark-s_16"></i>
+</kbq-tag>
+```
+
+#### After
+
+```html
+<kbq-tag>
+    Tag
+    <i kbqTagPrefix kbq-icon="kbq-circle-info_16"></i>
+    <i kbqTagRemove kbq-icon="kbq-xmark-s_16"></i>
+</kbq-tag>
+```

package/schematics/migrations/tag-slots/index.js

@@ -0,0 +1,190 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var ts = require('typescript');
+var utils_ast = require('../../utils/ast.js');
+var utils_messages = require('../../utils/messages.js');
+var utils_packageConfig = require('../../package-config-BhU2TfC8.js');
+var utils_typescript = require('../../utils/typescript.js');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+const TS_EXT = '.ts';
+const HTML_EXT = '.html';
+const PREFIX_ATTR = 'kbqTagPrefix';
+const TAG_ELEMENTS = new Set(['kbq-tag', 'kbq-basic-tag']);
+const TAG_ATTRS = ['kbq-tag', 'kbq-basic-tag'];
+const LEGACY_ICON_ATTR = 'kbq-icon';
+const SPECIAL_ICON_ATTRS = [PREFIX_ATTR, 'kbqTagSuffix', 'kbqTagRemove', 'kbqTagEditSubmit'];
+const attrName = (attr) => attr.name.replace(/[[\]()]/g, '');
+const hasAttr = (node, name) => !!node.attrs?.some((attr) => attrName(attr) === name);
+const isElement = (node) => Array.isArray(node.attrs);
+const isBlock = (node) => !isElement(node) && Array.isArray(node.children);
+const isTagHost = (node) => isElement(node) && ((!!node.name && TAG_ELEMENTS.has(node.name)) || TAG_ATTRS.some((name) => hasAttr(node, name)));
+const isIcon = (node) => isElement(node) && hasAttr(node, LEGACY_ICON_ATTR);
+const isSpecialIcon = (node) => SPECIAL_ICON_ATTRS.some((name) => hasAttr(node, name));
+function applyEdits(content, edits) {
+    let result = content;
+    for (const { start, end, text } of [...edits].sort((a, b) => b.start - a.start || b.end - a.end)) {
+        result = result.slice(0, start) + text + result.slice(end);
+    }
+    return result;
+}
+/** Offset just after the element name, or immediately before its first existing attribute. */
+function attributeInsertOffset(element) {
+    const firstAttr = element.attrs?.find((attr) => attr.keySpan?.start.offset !== undefined);
+    if (firstAttr)
+        return firstAttr.keySpan.start.offset;
+    const start = element.startSourceSpan?.start.offset;
+    return start === undefined ? undefined : start + 1 + (element.name?.length ?? 0);
+}
+/**
+ * Finds icons that participated in the old implicit leading slot.
+ *
+ * Control-flow blocks and `ng-container` are transparent for this purpose. Regular consumer wrappers are
+ * not traversed because their nested icons did not match the tag's direct projection selector either.
+ */
+function collectLegacyIcons(children = [], result = []) {
+    for (const child of children) {
+        if (isBlock(child) || child.name === 'ng-container') {
+            collectLegacyIcons(child.children, result);
+        }
+        else if (isIcon(child) && !isSpecialIcon(child) && !hasAttr(child, 'ngProjectAs')) {
+            result.push(child);
+        }
+    }
+    return result;
+}
+class TagHostCollector {
+    constructor() {
+        this.hosts = [];
+    }
+    visitElement(element) {
+        if (isTagHost(element))
+            this.hosts.push(element);
+        this.visitChildren(element);
+    }
+    visitChildren(node) {
+        for (const child of node.children ?? []) {
+            child.visit(this);
+        }
+    }
+    visitBlock(block) {
+        this.visitChildren(block);
+    }
+    visitAttribute() { }
+    visitText() { }
+    visitComment() { }
+    visitExpansion() { }
+    visitExpansionCase() { }
+    visitBlockParameter() { }
+    visitLetDeclaration() { }
+}
+async function migrateTemplate(template) {
+    if (![...TAG_ELEMENTS, ...TAG_ATTRS].some((selector) => template.includes(selector))) {
+        return { content: template, changed: false };
+    }
+    const parsed = await utils_typescript.parseTemplate(template);
+    if (!parsed.tree)
+        return { content: template, changed: false };
+    const collector = new TagHostCollector();
+    utils_ast.visitAll(collector, parsed.tree.rootNodes);
+    const edits = [];
+    for (const host of collector.hosts) {
+        for (const icon of collectLegacyIcons(host.children)) {
+            const offset = attributeInsertOffset(icon);
+            if (offset !== undefined)
+                edits.push({ start: offset, end: offset, text: `${PREFIX_ATTR} ` });
+        }
+    }
+    return { content: applyEdits(template, edits), changed: edits.length > 0 };
+}
+/** Interior ranges of static inline `@Component({ template: '…' })` string literals. */
+function collectInlineTemplateRanges(sourceFile) {
+    const ranges = [];
+    utils_typescript.forEachClass(sourceFile, (node) => {
+        const decorator = ts
+            .getDecorators(node)
+            ?.find((current) => ts.isCallExpression(current.expression) &&
+            ts.isIdentifier(current.expression.expression) &&
+            current.expression.expression.text === 'Component');
+        if (!decorator || !ts.isCallExpression(decorator.expression))
+            return;
+        const [metadata] = decorator.expression.arguments;
+        if (!metadata || !ts.isObjectLiteralExpression(metadata))
+            return;
+        for (const property of metadata.properties) {
+            if (ts.isPropertyAssignment(property) &&
+                (ts.isIdentifier(property.name) || ts.isStringLiteralLike(property.name)) &&
+                property.name.text === 'template' &&
+                ts.isStringLiteralLike(property.initializer) &&
+                property.initializer.text) {
+                ranges.push({
+                    start: property.initializer.getStart(sourceFile) + 1,
+                    end: property.initializer.getEnd() - 1
+                });
+            }
+        }
+    });
+    return ranges;
+}
+async function migrateInlineTemplates(content, fileName) {
+    const sourceFile = ts.createSourceFile(fileName, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const ranges = collectInlineTemplateRanges(sourceFile).sort((a, b) => b.start - a.start);
+    let result = content;
+    for (const { start, end } of ranges) {
+        const migrated = await migrateTemplate(result.slice(start, end));
+        if (migrated.changed)
+            result = result.slice(0, start) + migrated.content + result.slice(end);
+    }
+    return result;
+}
+function tagSlots(options) {
+    return async (tree, context) => {
+        const { project } = options;
+        const fix = options.fix ?? true;
+        const projectDefinition = await utils_packageConfig.setupOptions(project, tree);
+        const root = projectDefinition?.root ?? '';
+        const rootDir = root ? tree.getDir(root) : tree.root;
+        const tsPaths = [];
+        const htmlPaths = [];
+        utils_packageConfig.visitProjectFiles(rootDir, (filePath) => {
+            if (filePath.endsWith(TS_EXT))
+                tsPaths.push(filePath);
+            else if (filePath.endsWith(HTML_EXT))
+                htmlPaths.push(filePath);
+        });
+        let touched = 0;
+        const commit = (filePath, original, updated) => {
+            if (updated === original)
+                return;
+            touched++;
+            if (fix) {
+                tree.overwrite(filePath, updated);
+            }
+            else {
+                utils_messages.logMessage(context.logger, [`[tag-slots] would update ${filePath} (run with --fix to apply)`]);
+            }
+        };
+        for (const filePath of tsPaths) {
+            const original = tree.read(filePath)?.toString();
+            if (original)
+                commit(filePath, original, await migrateInlineTemplates(original, filePath));
+        }
+        for (const filePath of htmlPaths) {
+            const original = tree.read(filePath)?.toString();
+            if (!original)
+                continue;
+            const migrated = await migrateTemplate(original);
+            if (migrated.changed)
+                commit(filePath, original, migrated.content);
+        }
+        utils_messages.logMessage(context.logger, [
+            `[tag-slots] processed tree under "${root || '<workspace root>'}", ` +
+                `${fix ? 'updated' : 'would update'} ${touched} file(s).`
+        ]);
+    };
+}
+
+exports.default = tagSlots;

package/schematics/migrations/tag-slots/schema.json

@@ -0,0 +1,20 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-tag-slots",
+    "title": "Koobiq components tag slots 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, marks legacy kbq-icon content in tags with kbqTagPrefix. When false, prints what would change without writing."
+        }
+    }
+}

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

@@ -0,0 +1,85 @@
+# tags-signals
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21` (registered for
+`21.0.0-0`). Migrates `KbqTag`, `KbqTagList` and `KbqTagInput` consumers to their signal-based members.
+
+## What deliberately did not move
+
+What stays an accessor stays for a reason the code enforces, not for want of a transform - a backing
+input carries `booleanAttribute`, and a `computed` or `linkedSignal` over it reads back as a signal.
+
+- `KbqTag.disabled` is read by the focus key manager as a value (`item.disabled`), and a signal - a
+  function - would always be truthy and skip every tag.
+- `disabled`, `tabindex` and `value` on the tag, `draggable`, `tabIndex` on the tag list and `disabled`
+  on the tag input keep their setters; `KbqTag.value` falls back to the projected text content.
+
+**Their read and write syntax is unchanged**, and the schematic does not touch them.
+
+The form-field state did move, but not here. `value`, `id`, `placeholder`, `focused`, `empty`,
+`required`, `disabled` and `errorState` of `KbqTagList` are signals, migrated by `form-field-signals`:
+reads become calls, a write to `disabled` or `value` becomes `.set()`, a write to the rest is reported.
+`id`, `placeholder`, `focused` and `empty` of `KbqTagInput` are read-only signals, migrated there
+too: reads become calls, a write is reported.
+
+## What it rewrites
+
+| Before                         | After                    |
+| ------------------------------ | ------------------------ |
+| `tagInput.addOnBlur`           | `tagInput.addOnBlur()`   |
+| `tagInput.separators`          | `tagInput.separators()`  |
+| `tag.selected`                 | `tag.selected()`         |
+| `tag.editable`                 | `tag.editable()`         |
+| `tag.selectable`               | `tag.selectable()`       |
+| `tag.removable`                | `tag.removable()`        |
+| `list.removable`               | `list.removable()`       |
+| `this.tag()?.selected`         | `this.tag()?.selected()` |
+| `{{ tag.selected }}` in a view | `{{ tag.selected() }}`   |
+
+The member sets are per class. `KbqTagList` has a `selected` of its own - an array of tags - that did
+not move, so `list.selected` is left alone even though `tag.selected` is rewritten.
+
+On receivers typed `KbqTag`, `KbqTagList` or `KbqTagInput` - by annotation, including an aliased import,
+or by `inject()`, `viewChild()` and `contentChild()` - and through `!`, parentheses and `as`. Each name is
+resolved in its own scope, so a nested binding that shadows the receiver, and `this` inside a `function`
+that rebinds it, are left alone. Already-migrated reads are left alone too, so the schematic is
+idempotent.
+
+The template pass follows reference variables in external and inline templates. A ref that names an
+`exportAs` - `kbqTag`, `kbqTagList`, `kbqTagInput`, `kbqTagInputFor` - holds that instance. A bare ref
+holds the component on `<kbq-tag>`, `<kbq-basic-tag>`, `<kbq-tag-list>` and on an element their
+attribute selector matches; on the native `<input>` a bare ref is the element itself, so it is not
+touched.
+
+## What it does _not_ do
+
+| Pattern                                              | Manual migration                                           |
+| ---------------------------------------------------- | ---------------------------------------------------------- |
+| `tag.selected = …`                                   | Call `select()`, `deselect()` or `toggleSelected()`        |
+| `.separatorKeyCodes = …` / `.tagList = …`            | Bind `[kbqTagInputSeparatorKeyCodes]` / `[kbqTagInputFor]` |
+| Any other write, incl. `\|\|=`, `+=`, `++`, `delete` | Bind the attribute; every write form is reported           |
+| `query.selected` on an uncalled `viewChild()`        | Read it as `query()?.selected()`                           |
+| A class named in a union, an array or `QueryList`    | Reported with its line; resolve the receiver by hand       |
+
+A `@ViewChild(KbqTag)` field holds the instance itself, so its reads are rewritten with a single `()`
+and no double call is suggested.
+
+## Notes with no call site to point at
+
+- **A change of the `[selected]` binding still emits `selectionChange`**, the way the old setter did. The
+  tag list listens to it, so `selected` is read-only rather than a `linkedSignal`: resetting through one
+  would skip the event.
+- **`distinct` is a `booleanAttribute` input.** A valueless `distinct` attribute used to pass the
+  empty string, which is falsy, so duplicate tags were still accepted.
+- **Generated ids come from the CDK `_IdGenerator`** instead of a module-level counter. The shape is
+  unchanged for a default `APP_ID`: the CDK omits the app id when it is `ng`, and the counter still
+  starts at 0, so a real app keeps getting `kbq-tag-list-0` and `kbq-tag-list-input-0`. Only an app
+  that sets `APP_ID` explicitly sees it in the id, right before the counter and with no separator. The
+  tag list reports the id of its input when it has one, so both surface through the form field.
+
+## Running it manually
+
+```
+ng generate @koobiq/components:tags-signals --project my-app
+```
+
+Pass `--fix=false` to see what it would change without writing.

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

@@ -0,0 +1,103 @@
+'use strict';
+
+/**
+ * Data for the `tags-signals` migration.
+ *
+ * What stays an accessor stays for a reason the code enforces, not for want of a transform - a backing input
+ * carries `booleanAttribute`, and a `computed` or `linkedSignal` over it reads back as a signal:
+ *
+ * - `KbqTag.disabled` is read by the focus key manager as a value, and a signal would always be truthy;
+ * - `disabled`, `draggable`, `tabindex` and `tabIndex` keep their setters; `KbqTag.value` falls back to the
+ *   projected text content, which is DOM state.
+ *
+ * The `KbqFormFieldControl` members of `KbqTagList` and `id`, `placeholder`, `focused` and `empty` of
+ * `KbqTagInput` are signals too; this migration leaves them to `form-field-signals`.
+ *
+ * Everything else moved:
+ *
+ * - `KbqTagInput`: `addOnBlur` and `separators` read as calls; `separatorKeyCodes` and `tagList` are read-only
+ * - `KbqTag`: `selected`, `editable`, `selectable` and `removable` read as calls and are read-only
+ * - `KbqTagList`: `removable` reads as a call and is read-only
+ */
+const TARGETS = [
+    {
+        type: 'KbqTagInput',
+        signalMembers: ['addOnBlur', 'separators'],
+        readOnlyMembers: ['addOnBlur', 'separators', 'separatorKeyCodes', 'tagList'],
+        exportAs: ['kbqTagInput', 'kbqTagInputFor'],
+        elements: [],
+        writeAdvice: 'Bind `[kbqTagInputAddOnBlur]`, `[kbqTagInputSeparatorKeyCodes]` and `[kbqTagInputFor]` instead. ' +
+            '`separatorKeyCodes` and `tagList` were setters with no getter, so in exchange they can be read now.'
+    },
+    {
+        type: 'KbqTag',
+        signalMembers: ['selected', 'editable', 'selectable', 'removable'],
+        readOnlyMembers: ['selected', 'editable', 'selectable', 'removable'],
+        exportAs: ['kbqTag'],
+        elements: ['kbq-tag', 'kbq-basic-tag'],
+        writeAdvice: 'Bind `[selected]`, `[editable]`, `[selectable]` and `[removable]` instead. To change the selection ' +
+            'from code, call `select()`, `deselect()` or `toggleSelected()`: like the old `selected` setter, ' +
+            'they emit `selectionChange`, which the tag list listens to.'
+    },
+    {
+        type: 'KbqTagList',
+        signalMembers: ['removable'],
+        readOnlyMembers: ['removable'],
+        exportAs: ['kbqTagList'],
+        elements: ['kbq-tag-list'],
+        writeAdvice: 'Bind `[removable]` instead.'
+    }
+];
+/** Methods on a signal, whose presence after the member means the read is already migrated. */
+const SIGNAL_API_METHODS = new Set(['set', 'update', 'asReadonly', 'subscribe']);
+/** Import specifier that marks a file as a tags consumer. */
+const TAGS_PACKAGE = '@koobiq/components/tags';
+/** Reported for writes to members that are read-only now, whatever form the write takes. */
+const writeMessage = (type, members, advice) => `These ${type} members are read-only signals now, so these writes no longer compile: ` +
+    `${[...members].join(', ')}. That covers compound assignments (\`||=\`, \`+=\`), increments, \`delete\` ` +
+    `and destructuring targets as well as a plain \`=\`. ${advice}`;
+/**
+ * Reported for a read through a signal query, which is a signal holding the instance: the read needs two
+ * calls rather than one. Emitted from the AST pass rather than a regex, so a `@ViewChild` field - which holds
+ * the instance itself - is never mistaken for one.
+ */
+const signalQueryMessage = (member, required) => `A signal query holds the instance behind a call of its own, so reading \`${member}\` through it needs ` +
+    `two calls: \`this.query()${required ? '' : '?'}.${member}()\`.` +
+    (required ? '' : ' The query is optional, so keep the `?.`.') +
+    ' Those reads are left untouched - migrate them by hand.';
+/** Reported when a template references a tag, a tag list or a tag input but cannot be parsed. */
+const UNPARSEABLE_TEMPLATE_MESSAGE = 'This template references a tag, a tag list or a tag input but could not be parsed, so it was left ' +
+    'untouched. Migrate reads through its template reference variables by hand. If every template is ' +
+    'reported this way, `@angular/compiler` could not be loaded from this install.';
+/**
+ * Reported when a file names one of the classes in a type position the receiver pass cannot scope to a single
+ * identifier - a union, an array, a `QueryList<…>`, a return type - or reads a member in a shape the access
+ * pass cannot reach.
+ */
+const UNRESOLVED_RECEIVER_MESSAGE = 'KbqTag, KbqTagList or KbqTagInput 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:';
+/** Printed once per project, after the per-file reports. */
+const SUMMARY = [
+    '  `distinct` is a `booleanAttribute` input. A valueless `distinct` attribute used to pass the empty ' +
+        'string, which is falsy, so duplicate tags were still accepted; it prevents them now.',
+    '  Generated ids come from the CDK `_IdGenerator` instead of a module-level counter. The shape is ' +
+        'unchanged for a default `APP_ID`: the CDK omits the app id when it is `ng`, and the counter still ' +
+        'starts at 0, so a real app keeps getting `kbq-tag-list-0` and `kbq-tag-list-input-0`. Only an app ' +
+        'that sets `APP_ID` explicitly sees it in the id, right before the counter and with no separator. ' +
+        'The tag list reports the id of its input when it has one, so both surface through the form field.',
+    '  A change of the `[selected]` binding still emits `selectionChange`, the way the old setter did.',
+    '  `disabled`, `tabindex` and `value` on the tag, `draggable`, `tabIndex` on the tag list and `disabled` ' +
+        'on the tag input keep their accessors, so their reads and writes are unchanged.',
+    '  The form-field state is signals and is left to `form-field-signals`: `value`, `id`, `placeholder`, ' +
+        '`focused`, `empty`, `required`, `disabled` and `errorState` of the tag list, and `id`, ' +
+        '`placeholder`, `focused` and `empty` of the tag input.'
+];
+
+exports.SIGNAL_API_METHODS = SIGNAL_API_METHODS;
+exports.SUMMARY = SUMMARY;
+exports.TAGS_PACKAGE = TAGS_PACKAGE;
+exports.TARGETS = TARGETS;
+exports.UNPARSEABLE_TEMPLATE_MESSAGE = UNPARSEABLE_TEMPLATE_MESSAGE;
+exports.UNRESOLVED_RECEIVER_MESSAGE = UNRESOLVED_RECEIVER_MESSAGE;
+exports.signalQueryMessage = signalQueryMessage;
+exports.writeMessage = writeMessage;