@koobiq/components 20.4.2 → 21.0.0

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

@@ -0,0 +1,93 @@
+# tabs-signals-and-aria
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21` (registered for `21.0.0-0`).
+Reports the subclasses of the tabs classes and the direct calls of their `ngOnChanges`, the members the tabs review
+removed or changed, and states the ARIA and theming changes that have no call site to point at. It never writes to the
+tree.
+
+## Signal inputs and queries
+
+The decorator inputs of `KbqTabGroup`, `KbqTab`, `KbqTabHeader`, `KbqTabNavBar`, `KbqTabLink`, `KbqTabLabelWrapper`
+and `KbqTabBody` are signal inputs named `<member>Input`, handed to the unchanged member from `ngOnChanges`. Their
+decorator queries are signal queries behind getters: `KbqTabGroup.tabs` and the `items` of the header and the nav bar
+stay `QueryList`s. Reading and writing the members works as before — `tab.disabled`, `tabLink.active` and the selection
+of a group stay plain properties.
+
+| Use                                         | What to do                                                            |
+| ------------------------------------------- | --------------------------------------------------------------------- |
+| A subclass with its own `ngOnChanges`       | Mark it `override` and call `super.ngOnChanges(changes)`              |
+| A subclass that redeclared an `@Input()`    | Override the `<member>Input` signal input, e.g. `headerPositionInput` |
+| A subclass that redeclared a query          | Override the getter (`tabs`, `items`, `labelContent`, …)              |
+| `ngOnChanges` called with a `SimpleChanges` | Key it by `<member>Input` (`disabledInput`), or bind the input        |
+
+A boolean input accepts `boolean | string | null | undefined` in a template now, rather than anything.
+
+## Review
+
+The review closed the members that were wired to nothing and gave `KbqTabGroup` the ARIA tabs pattern that
+`KbqTabNavBar`, in the same package, already had.
+
+| Member                          | Before                  | After                                   |
+| ------------------------------- | ----------------------- | --------------------------------------- |
+| `KbqTabGroup.resizeStream`      | public `Subject`        | removed                                 |
+| `(window:resize)` on the group  | host listener           | removed                                 |
+| `KbqTabGroup.disabled`          | published input         | removed                                 |
+| `KbqTabGroup.getTabIndex()`     | `(tab, index)`          | `(tab, tabHeader, index)`, never `null` |
+| `KbqVerticalTabsCssStyler`      | applies a host class    | deprecated no-op                        |
+| `KbqTabLabelWrapper` host       | `[attr.disabled]`       | `[attr.aria-disabled]`                  |
+| `KbqTabLink` host               | `[attr.disabled]`       | `[attr.aria-disabled]` only             |
+| `KbqTabBody.afterLeavingCenter` | `EventEmitter<boolean>` | `EventEmitter<void>`                    |
+
+The header is observed with the CDK `SharedResizeObserver` now, which also catches container resizes that no window
+event reports, so a manual `resizeStream.next(event)` has no counterpart. `KbqTabGroup.disabled` was published,
+documented and appeared in the API table, and no template bound it and no style targeted it: disable the individual
+tabs instead.
+
+| Pattern                    | Manual migration                                                |
+| -------------------------- | --------------------------------------------------------------- |
+| `.resizeStream`            | Nothing to call; the header observes itself                     |
+| `<kbq-tab-group disabled>` | Disable the tabs: `<kbq-tab [disabled]="true">`                 |
+| `.getTabIndex(tab, index)` | Pass the header: `getTabIndex(tab, tabHeader, index)`           |
+| `KbqVerticalTabsCssStyler` | Stop importing it; the class follows the `vertical` binding now |
+| `.kbq-tab-label[disabled]` | Target `.kbq-disabled`, or `[aria-disabled="true"]` in a test   |
+
+## What it cannot reach
+
+`KbqTabGroup.disabled` is matched only where the type name and the property access sit on one line —
+`<kbq-tab-group disabled>`, or a single-statement access. The two-step form, where the reference is typed once and read
+later,
+
+```ts
+@ViewChild(KbqTabGroup) group: KbqTabGroup;
+// ...
+if (this.group.disabled) { … }
+```
+
+is **not** reported: widening it to the whole file would fire on every `.disabled` of a tab in any file that mentions a
+tab group. The removed input did nothing, so a missed call site is dead code rather than a behaviour change.
+
+A stylesheet matching `a[disabled]` inside a nav bar has to move to `.kbq-disabled`; stylesheets are not visited.
+
+## Notes with no call site to point at
+
+- `KbqTabGroup` renders the ARIA tabs pattern: the label strip is a `role="tablist"` (carrying
+  `aria-orientation="vertical"` when `vertical` is set), each label a `role="tab"` with `aria-selected` and
+  `aria-controls`, and each body a `role="tabpanel"` with `aria-labelledby` and a tab stop while it is the active one.
+  Hand-rolled `role` or `aria-*` attributes on those elements are duplicates now.
+- The roving `tabindex` follows the header's focus position rather than the selection, and a disabled tab gets `-1`
+  rather than no attribute at all. A group whose selected tab was disabled had no element with `tabindex="0"`.
+- `KbqTabNavBar` emits `aria-orientation="vertical"` when it is both vertical and a real tablist — that is, when
+  `[tabNavPanel]` is supplied. Without `[tabNavPanel]` the nav bar stays plain navigation.
+- `[vertical]` works as a binding, and `disablePagination` is derived rather than latched, so a header that stops being
+  vertical gets its paginator arrows back.
+- `KbqTabHeader` is `OnPush` like every other component in the package.
+- `KbqPaginatedTabHeader` is exported from the entry point, and the duplicate `ScrollDirection` in
+  `tab-header.component` was deleted in favour of the base one.
+- The four `on-surface` theme branches read the `--kbq-tabs-tab-item-*-on-surface-*` tokens instead of the
+  `on-background` family.
+
+## Running it manually
+
+```bash
+ng g @koobiq/components:tabs-signals-and-aria --project "<your project>"
+```

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

@@ -0,0 +1,139 @@
+'use strict';
+
+/**
+ * Data for the `tabs-signals-and-aria` migration.
+ *
+ * The decorator inputs of the tabs are signal inputs named `<member>Input`, handed to the unchanged member from
+ * `ngOnChanges`, and their decorator queries are signal queries behind getters. Reads and writes of the members are
+ * unchanged; a subclass and a hand-made `SimpleChanges` are not.
+ *
+ * The tabs review closed the members that were wired to nothing and gave `KbqTabGroup` the ARIA tabs pattern its
+ * sibling in the same package already had:
+ *
+ * - `KbqTabGroup.resizeStream` and the `(window:resize)` host listener — removed. The header is observed with the
+ *   CDK `SharedResizeObserver` now, which also catches container resizes no window event reports.
+ * - `KbqTabGroup.disabled` — removed. It was published, documented and read by nothing at all.
+ * - `KbqTabGroup.getTabIndex()` — takes the header as its second argument, and returns `-1` instead of `null` for a
+ *   disabled tab so the strip keeps exactly one tab stop.
+ * - `KbqVerticalTabsCssStyler` — deprecated no-op. The vertical layout class is bound from the components
+ *   themselves, so `[vertical]="false"` now removes it.
+ * - `KbqTabLabelWrapper` and `KbqTabLink` emit `aria-disabled` instead of a bare `disabled` attribute.
+ *
+ * Warn-only. A removed member has no replacement expression, and an attribute selector has to be rewritten by hand.
+ */
+/** Import specifier that marks a file as a tabs consumer. */
+const TABS_PACKAGE = '@koobiq/components/tabs';
+/**
+ * Identifier and element shapes that mark a consumer without an import.
+ *
+ * `KbqTabs?(?![a-z])` rather than `KbqTab\w*`: the greedy form also swallows `KbqTable`, a different component in
+ * the same library. Requiring a non-lowercase character after the optional `s` keeps every real export (`KbqTab`,
+ * `KbqTabGroup`, `KbqTabNavBar`, `KbqTabsModule`) and drops `KbqTable*`.
+ */
+const TABS_TYPE = '\\bKbqTabs?(?![a-z])\\w*\\b|\\bkbq-tab(?:-group|-nav-bar)?\\b|\\bkbqTab(?:NavBar|Link|Label)\\b';
+const CLASSES = [
+    'KbqTabGroup',
+    'KbqTab',
+    'KbqTabHeader',
+    'KbqTabNavBar',
+    'KbqTabLink',
+    'KbqTabLabelWrapper',
+    'KbqTabBody'
+].join('|');
+const SUBCLASS = `\\bextends\\s+(?:${CLASSES})\\b`;
+/** Patterns evaluated for every `.ts` and `.html` file that references the tabs. */
+const warnPatterns = [
+    {
+        anchor: SUBCLASS,
+        pattern: SUBCLASS,
+        message: 'A subclass of a Koobiq tabs class whose inputs became signal inputs. The bound value reaches the member ' +
+            'from ngOnChanges now, which every one of them but KbqTab declares for the first time: an ngOnChanges of ' +
+            'the subclass is marked override and calls super.ngOnChanges(changes). An input the subclass redeclared ' +
+            'with @Input() is overridden through the `<member>Input` signal input instead, e.g. ' +
+            '`override readonly headerPositionInput = input<KbqTabHeaderPosition | undefined>(undefined, ' +
+            "{ alias: 'headerPosition' })`."
+    },
+    {
+        anchor: SUBCLASS,
+        pattern: '@(?:ViewChild|ViewChildren|ContentChild|ContentChildren)\\s*\\(',
+        message: 'A subclass of a Koobiq tabs class that declares a decorator query. KbqTabGroup.tabs, the items, ' +
+            'tabListContainer, tabList, nextPaginator and previousPaginator of KbqTabHeader and KbqTabNavBar, ' +
+            'KbqTabLabelWrapper.labelContent and KbqTab.templateLabel are getters over signal queries now, so a ' +
+            'subclass can no longer redeclare them as fields: override the getter instead. tabs and items stay ' +
+            'QueryLists whose changes emit as before.'
+    },
+    {
+        anchor: `\\b(?:${CLASSES})\\b`,
+        pattern: '(?<!\\bsuper)\\.ngOnChanges\\s*\\(',
+        message: 'A direct call of ngOnChanges in a file that uses a Koobiq tabs class. Their SimpleChanges are keyed by ' +
+            'the `<member>Input` names now (disabledInput, not disabled), and a bound value reaches its member only ' +
+            'through them: set the input with a template binding or ComponentRef.setInput instead. This pattern also ' +
+            'matches ngOnChanges of an unrelated class in the same file — check before changing it.'
+    },
+    {
+        anchor: TABS_TYPE,
+        pattern: '\\bresizeStream\\b',
+        message: 'KbqTabGroup.resizeStream and the (window:resize) host listener were removed. The header is observed with ' +
+            'the CDK SharedResizeObserver now, which also catches container resizes, so a manual ' +
+            'resizeStream.next(event) has no counterpart.'
+    },
+    {
+        anchor: '\\bKbqTabGroup\\b|\\bkbq-tab-group\\b',
+        pattern: '<kbq-tab-group[^>]*\\bdisabled\\b|\\bKbqTabGroup\\b[^\\n]*\\.\\s*disabled\\b',
+        message: 'KbqTabGroup.disabled was removed. It was published and documented but read by nothing — no template ' +
+            'bound it and no style targeted it, so <kbq-tab-group disabled> never did anything. Disable the ' +
+            'individual tabs instead: <kbq-tab [disabled]="true">.'
+    },
+    {
+        anchor: '\\bKbqTabGroup\\b',
+        pattern: '\\.\\s*getTabIndex\\s*\\(',
+        message: 'KbqTabGroup.getTabIndex(tab, index) is getTabIndex(tab, tabHeader, index) and returns -1 rather than ' +
+            'null for a disabled tab. The roving tabindex follows the header focus position now, so a disabled ' +
+            'selected tab can no longer take the whole strip out of the tab order.'
+    },
+    {
+        anchor: '\\bKbqVerticalTabsCssStyler\\b',
+        pattern: '\\bKbqVerticalTabsCssStyler\\b',
+        message: 'KbqVerticalTabsCssStyler is a deprecated no-op and will be removed. The kbq-tab-group_vertical class is ' +
+            'bound from KbqTabGroup and KbqTabNavBar themselves, so [vertical]="false" removes it instead of ' +
+            'leaving it latched on by the attribute selector. Stop importing the directive.'
+    },
+    {
+        anchor: '\\bkbq-tab-label\\b|\\bkbqTabLabelWrapper\\b',
+        pattern: '\\.kbq-tab-label\\[disabled\\]|kbq-tab-label[^\\n]*\\[disabled\\]',
+        message: 'A tab label no longer carries a bare `disabled` attribute — that attribute is defined for form controls ' +
+            'only and no assistive technology reads it off a div. Target .kbq-disabled for styling or ' +
+            '[aria-disabled="true"] in a test.'
+    }
+];
+/** Printed once per project that references the tabs, after the per-file reports. */
+const SUMMARY = [
+    '  Apart from the removals above, reads and writes of the tabs members are unchanged — tab.disabled, ' +
+        'tabLink.active and the selection of a group stay plain properties — and tabs and items are still ' +
+        'QueryLists. A boolean input (disabled, active, vertical, disablePagination) accepts ' +
+        'boolean | string | null | undefined in a template now.',
+    '  KbqTabGroup renders the ARIA tabs pattern now: the label strip is a role="tablist" (with ' +
+        'aria-orientation="vertical" when vertical), each label a role="tab" with aria-selected and ' +
+        'aria-controls, and each body a role="tabpanel" with aria-labelledby and a tab stop while active. ' +
+        'Hand-rolled role or aria-* attributes on those elements are duplicates now.',
+    '  KbqTabNavBar emits aria-orientation="vertical" when it is both vertical and a real tablist, i.e. ' +
+        'when [tabNavPanel] is supplied. Without [tabNavPanel] the nav bar stays plain navigation and ' +
+        'emits no tab semantics at all — supply it whenever the bar switches a region on the same page. ' +
+        'A tab link carries aria-disabled and no longer a bare disabled attribute: a selector such as ' +
+        'a[kbqTabLink][disabled] moves to .kbq-disabled.',
+    '  KbqTabHeader is OnPush like every other component in the package. A host that mutated it outside ' +
+        'Angular and relied on the Default strategy to pick the change up has to mark it for check.',
+    '  KbqTabBody.afterLeavingCenter is an EventEmitter<void>: it never carried a value, so a handler that ' +
+        'declared a boolean parameter drops it.',
+    '  KbqPaginatedTabHeader is exported from the entry point, so `extends KbqPaginatedTabHeader` in the ' +
+        'public signatures is nameable, and the duplicate ScrollDirection in tab-header.component was ' +
+        'deleted in favour of the base one — both resolve through @koobiq/components/tabs.',
+    '  The four on-surface theme branches read the --kbq-tabs-tab-item-*-on-surface-* tokens they always ' +
+        'declared instead of the on-background family. Values that were only overridden on the ' +
+        'on-background tokens no longer reach a group or nav bar with [onSurface].'
+];
+
+exports.SUMMARY = SUMMARY;
+exports.TABS_PACKAGE = TABS_PACKAGE;
+exports.TABS_TYPE = TABS_TYPE;
+exports.warnPatterns = warnPatterns;

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

@@ -0,0 +1,65 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var utils_messages = require('../../utils/messages.js');
+var utils_packageConfig = require('../../package-config-BhU2TfC8.js');
+var migrations_tabsSignalsAndAria_data = require('./data.js');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+const LABEL = '[tabs-signals-and-aria]';
+const EXTENSIONS = ['.ts', '.html'];
+// Compiled once rather than for every file of the project. None carries the `g` flag, so a shared instance holds no
+// `lastIndex`.
+const TABS_TYPE_REGEX = new RegExp(migrations_tabsSignalsAndAria_data.TABS_TYPE);
+const COMPILED_WARN_PATTERNS = migrations_tabsSignalsAndAria_data.warnPatterns.map(({ anchor, pattern, message }) => ({
+    anchor: anchor ? new RegExp(anchor) : null,
+    pattern: new RegExp(pattern),
+    message
+}));
+/** A file is a tabs consumer if it imports the package, names a component, or renders one. */
+function referencesTabs(content) {
+    return content.includes(migrations_tabsSignalsAndAria_data.TABS_PACKAGE) || TABS_TYPE_REGEX.test(content);
+}
+/**
+ * Reports the subclasses of the tabs classes and the direct calls of their `ngOnChanges`, the members the review
+ * removed or changed, and the ARIA and theming changes that have no call site to point at. Never writes.
+ *
+ * `.html` is visited as well as `.ts`, because the removed `disabled` input of the group and the removed
+ * `[attr.disabled]` of a label are both template-side.
+ */
+function tabsSignalsAndAria(options) {
+    return async (tree, context) => {
+        const projectDefinition = await utils_packageConfig.setupOptions(options.project, tree);
+        const root = projectDefinition?.root ?? '';
+        let consumers = 0;
+        let reported = 0;
+        utils_packageConfig.visitProjectFiles(root ? tree.getDir(root) : tree.root, (filePath, entry) => {
+            if (!EXTENSIONS.some((extension) => filePath.endsWith(extension)))
+                return;
+            const content = entry.content.toString();
+            if (!content || !referencesTabs(content))
+                return;
+            consumers++;
+            for (const { anchor, pattern, message } of COMPILED_WARN_PATTERNS) {
+                if (anchor && !anchor.test(content))
+                    continue;
+                if (!pattern.test(content))
+                    continue;
+                reported++;
+                utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${message}`]);
+            }
+        });
+        // Nothing here renders tabs, so the summary would only be noise.
+        if (consumers === 0)
+            return;
+        utils_messages.logMessage(context.logger, [
+            `${LABEL} processed tabs under "${root || '<workspace root>'}", ` +
+                `${consumers} file(s) reference the component, ${reported} call site(s) reported.`,
+            ...migrations_tabsSignalsAndAria_data.SUMMARY
+        ]);
+    };
+}
+
+exports.default = tabsSignalsAndAria;

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

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

@@ -0,0 +1,58 @@
+### Tag list cleaner schematic
+
+This schematic removes the `(click)` handler from every `<kbq-cleaner>` projected into a `<kbq-tag-list>`.
+
+The reset control of a tag list now removes the tags itself and leaves the disabled ones in place. It
+removes them through the same `removed` output as the remove control inside a tag, so the wiring that
+control already needs is all it takes — a handler that cleared the collection is no longer needed.
+
+A handler left in place runs **in addition** to the built-in clearing and cannot suppress it: the host
+listener of `KbqCleaner` runs first. That is why the binding is removed rather than left to the developer.
+
+The expression that was removed is printed for every file, because a handler may have done more than clear
+the tags. Put anything else it did back in another binding. Cleaners outside a tag list are untouched.
+
+A handler is kept, and reported rather than removed, where the built-in clearing would not take its place:
+when no tag in the list reports `removed`, so the clearing reaches nothing, and when the list is written
+`removable="false"`, which now hides the reset control outright. Fix the list first, then drop the handler.
+
+To keep clearing the disabled tags as well, set the predicate on the list instead:
+
+```html
+<!-- clearEverything = () => true; on the class -->
+<kbq-tag-list [clearPredicate]="clearEverything"></kbq-tag-list>
+```
+
+Usage for Angular CLI:
+
+```shell
+ng g @koobiq/components:tag-list-cleaner --project "<your project>"
+```
+
+Run without writing first:
+
+```shell
+ng g @koobiq/components:tag-list-cleaner --project "<your project>" --fix=false
+```
+
+#### Before
+
+<!-- prettier-ignore -->
+```html
+<kbq-tag-list>
+    <kbq-tag [value]="tag" (removed)="removed($event)">{{ tag }}</kbq-tag>
+
+    <kbq-cleaner (click)="clear()" />
+</kbq-tag-list>
+```
+
+#### After
+
+<!-- prettier-ignore -->
+```html
+<kbq-tag-list>
+    <kbq-tag [value]="tag" (removed)="removed($event)">{{ tag }}</kbq-tag>
+
+    <kbq-cleaner />
+</kbq-tag-list>
+```

package/schematics/migrations/tag-list-cleaner/data.js

@@ -0,0 +1,42 @@
+'use strict';
+
+/** The control whose handler this migration removes. */
+const CLEANER_ELEMENT = 'kbq-cleaner';
+/** Only a cleaner projected into a tag list is affected — elsewhere `(click)` still means what it did. */
+const TAG_LIST_ELEMENT = 'kbq-tag-list';
+/** Every spelling of the click binding the Angular parser keeps verbatim in the attribute name. */
+const CLICK_ATTRIBUTES = ['(click)', 'on-click'];
+/** The output the built-in clearing goes through; without it there is nothing to take the handler's place. */
+const REMOVED_ATTRIBUTES = ['(removed)', 'on-removed'];
+/** A list that refuses removal no longer shows a reset control at all. */
+const REMOVABLE_ATTRIBUTES = ['removable', '[removable]', 'bind-removable'];
+const removedHandlerMessage = (filePath, attribute, expression, fix) => [
+    `  ${fix ? 'removed' : 'would remove'} ${attribute}="${expression}" from <${CLEANER_ELEMENT}> — the tag list clears itself now.`,
+    `  If the handler did anything besides clearing the tags, put that part back. File: ${filePath}`
+];
+const keptHandlerMessage = (filePath, attribute, expression, reason) => [
+    `  kept ${attribute}="${expression}" on <${CLEANER_ELEMENT}>: ${reason}`,
+    `  Removing it would leave the control with nothing behind it. Fix the list, then drop the handler by hand. File: ${filePath}`
+];
+const NO_REMOVED_BINDING_REASON = 'no tag in the list reports `removed`, so the built-in clearing reaches nothing';
+const REFUSES_REMOVAL_REASON = `the list is removable="false", so it no longer shows a reset control at all`;
+const UNPARSEABLE_TEMPLATE_MESSAGE = `Template could not be parsed, so it was left untouched. Check its <${CLEANER_ELEMENT}> handlers by hand.`;
+const BEHAVIOUR_NOTE = [
+    `Note: the reset control of a ${TAG_LIST_ELEMENT} now removes the tags itself and leaves the disabled`,
+    'ones in place. It removes them through the same `removed` output as the remove control inside a tag, so',
+    'the wiring that control already needs is all it takes. A handler left on the cleaner runs in addition to',
+    'that, and cannot suppress it. To clear the disabled tags too, bind a predicate that accepts them:',
+    'clearEverything = () => true; on the class, [clearPredicate]="clearEverything" on the list.'
+];
+
+exports.BEHAVIOUR_NOTE = BEHAVIOUR_NOTE;
+exports.CLEANER_ELEMENT = CLEANER_ELEMENT;
+exports.CLICK_ATTRIBUTES = CLICK_ATTRIBUTES;
+exports.NO_REMOVED_BINDING_REASON = NO_REMOVED_BINDING_REASON;
+exports.REFUSES_REMOVAL_REASON = REFUSES_REMOVAL_REASON;
+exports.REMOVABLE_ATTRIBUTES = REMOVABLE_ATTRIBUTES;
+exports.REMOVED_ATTRIBUTES = REMOVED_ATTRIBUTES;
+exports.TAG_LIST_ELEMENT = TAG_LIST_ELEMENT;
+exports.UNPARSEABLE_TEMPLATE_MESSAGE = UNPARSEABLE_TEMPLATE_MESSAGE;
+exports.keptHandlerMessage = keptHandlerMessage;
+exports.removedHandlerMessage = removedHandlerMessage;

package/schematics/migrations/tag-list-cleaner/index.js

@@ -0,0 +1,196 @@
+'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');
+var migrations_tagListCleaner_data = require('./data.js');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+const TS_EXT = '.ts';
+const HTML_EXT = '.html';
+const LABEL = '[tag-list-cleaner]';
+/** Whether any element in the subtree reports `removed`, the output the built-in clearing goes through. */
+function hasRemovedBinding(node) {
+    for (const attr of node.attrs ?? []) {
+        if (typeof attr.name === 'string' && migrations_tagListCleaner_data.REMOVED_ATTRIBUTES.includes(attr.name))
+            return true;
+    }
+    return (node.children ?? []).some((child) => hasRemovedBinding(child));
+}
+/** Whether the list is written as `removable="false"`, which now hides the cleaner outright. */
+function refusesRemoval(element) {
+    return (element.attrs ?? []).some((attr) => typeof attr.name === 'string' &&
+        migrations_tagListCleaner_data.REMOVABLE_ATTRIBUTES.includes(attr.name) &&
+        String(attr.value).trim() === 'false');
+}
+/** Collects the click handler of every cleaner projected into a tag list. */
+class CleanerHandlerCollector {
+    constructor() {
+        this.findings = [];
+        /** One entry per enclosing tag list, carrying why its cleaner's handler may or may not go. */
+        this.tagLists = [];
+    }
+    visitElement(element) {
+        const isTagList = element.name === migrations_tagListCleaner_data.TAG_LIST_ELEMENT;
+        if (isTagList) {
+            this.tagLists.push({
+                keptReason: refusesRemoval(element)
+                    ? migrations_tagListCleaner_data.REFUSES_REMOVAL_REASON
+                    : hasRemovedBinding(element)
+                        ? undefined
+                        : migrations_tagListCleaner_data.NO_REMOVED_BINDING_REASON
+            });
+        }
+        const tagList = this.tagLists.at(-1);
+        if (tagList && element.name === migrations_tagListCleaner_data.CLEANER_ELEMENT) {
+            for (const attr of element.attrs ?? []) {
+                if (typeof attr.name !== 'string' || !migrations_tagListCleaner_data.CLICK_ATTRIBUTES.includes(attr.name))
+                    continue;
+                this.findings.push({
+                    edit: { start: attr.sourceSpan.start.offset, end: attr.sourceSpan.end.offset },
+                    attribute: attr.name,
+                    expression: String(attr.value).trim(),
+                    keptReason: tagList.keptReason
+                });
+            }
+        }
+        this.visitChildren(element);
+        if (isTagList)
+            this.tagLists.pop();
+    }
+    visitBlock(block) {
+        this.visitChildren(block);
+    }
+    visitChildren(node) {
+        for (const child of node.children ?? []) {
+            child.visit(this);
+        }
+    }
+    visitAttribute() { }
+    visitText() { }
+    visitComment() { }
+    visitExpansion() { }
+    visitExpansionCase() { }
+    visitBlockParameter() { }
+    visitLetDeclaration() { }
+}
+/**
+ * Deletes the ranges. A deletion also takes the whitespace that separated the attribute from the previous
+ * one: an inline attribute takes its leading spaces, one written on its own line takes the line break and
+ * the indent as well, so the tag is not left with a blank line.
+ */
+function applyEdits(content, edits) {
+    let result = content;
+    // Right-to-left, so earlier offsets stay valid.
+    for (const { start, end } of [...edits].sort((a, b) => b.start - a.start)) {
+        let from = start;
+        while (from > 0 && (result[from - 1] === ' ' || result[from - 1] === '\t'))
+            from--;
+        if (result[from - 1] === '\n') {
+            from--;
+            if (result[from - 1] === '\r')
+                from--;
+        }
+        result = result.slice(0, from) + result.slice(end);
+    }
+    return result;
+}
+/**
+ * Migrates one template. Returns `null` when it could not be parsed — editing it blind is how a
+ * regex-based migration corrupts binding expressions, so the caller warns instead.
+ */
+async function migrateTemplate(template, onFinding) {
+    if (!template.includes(migrations_tagListCleaner_data.CLEANER_ELEMENT))
+        return template;
+    const parsed = await utils_typescript.parseTemplate(template);
+    if (!parsed.tree)
+        return null;
+    const collector = new CleanerHandlerCollector();
+    utils_ast.visitAll(collector, parsed.tree.rootNodes);
+    collector.findings.forEach(onFinding);
+    return applyEdits(template, collector.findings.filter(({ keptReason }) => !keptReason).map(({ edit }) => edit));
+}
+/** Applies the template migration to every inline `@Component({ template })` literal of a `.ts` source. */
+async function migrateInlineTemplates(content, sourceFile, onFinding, onParseError) {
+    let result = content;
+    // Splice right-to-left so earlier offsets stay valid.
+    for (const { start, end } of utils_typescript.collectInlineTemplateRanges(sourceFile).sort((a, b) => b.start - a.start)) {
+        const migrated = await migrateTemplate(result.slice(start, end), onFinding);
+        if (migrated === null) {
+            onParseError();
+            continue;
+        }
+        result = result.slice(0, start) + migrated + result.slice(end);
+    }
+    return result;
+}
+function tagListCleaner(options) {
+    return async (tree, context) => {
+        const { project } = options;
+        // `ng update` invokes migrations with no options at all, and migrations.json declares no schema,
+        // so the schema default never reaches us — applying the fix is the intended behaviour there.
+        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 filePaths = [];
+        utils_packageConfig.visitProjectFiles(rootDir, (filePath) => {
+            if (!filePath.endsWith(TS_EXT) && !filePath.endsWith(HTML_EXT))
+                return;
+            filePaths.push(filePath);
+        });
+        let touched = 0;
+        for (const filePath of filePaths) {
+            const originalContent = tree.read(filePath)?.toString();
+            // Parsing every `.ts` of the project is not free, and nothing can change in a file that holds
+            // no cleaner at all.
+            if (!originalContent || !originalContent.includes(migrations_tagListCleaner_data.CLEANER_ELEMENT))
+                continue;
+            let content = originalContent;
+            let unparseable = false;
+            const reports = [];
+            const onFinding = ({ attribute, expression, keptReason }) => reports.push(keptReason
+                ? migrations_tagListCleaner_data.keptHandlerMessage(filePath, attribute, expression, keptReason)
+                : migrations_tagListCleaner_data.removedHandlerMessage(filePath, attribute, expression, fix));
+            if (filePath.endsWith(TS_EXT)) {
+                const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+                content = await migrateInlineTemplates(content, sourceFile, onFinding, () => (unparseable = true));
+            }
+            else {
+                const migrated = await migrateTemplate(content, onFinding);
+                if (migrated === null)
+                    unparseable = true;
+                else
+                    content = migrated;
+            }
+            for (const report of reports) {
+                utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, ...report]);
+            }
+            if (unparseable) {
+                utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${migrations_tagListCleaner_data.UNPARSEABLE_TEMPLATE_MESSAGE}`]);
+            }
+            if (content === originalContent)
+                continue;
+            touched++;
+            if (fix) {
+                tree.overwrite(filePath, content);
+            }
+            else {
+                utils_messages.logMessage(context.logger, [`${LABEL} would update ${filePath} (run with --fix to apply)`]);
+            }
+        }
+        utils_messages.logMessage(context.logger, [
+            `${LABEL} processed tree under "${root || '<workspace root>'}", ` +
+                `${fix ? 'updated' : 'would update'} ${touched} file(s).`,
+            '',
+            ...migrations_tagListCleaner_data.BEHAVIOUR_NOTE
+        ]);
+    };
+}
+
+exports.default = tagListCleaner;

package/schematics/migrations/tag-list-cleaner/schema.json

@@ -0,0 +1,20 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-tag-list-cleaner",
+    "title": "Koobiq components tag list cleaner 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, removes the click handler from every kbq-cleaner inside a kbq-tag-list. When false, prints what would change without writing."
+        }
+    }
+}