@koobiq/components 20.4.1 → 21.0.0

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

@@ -0,0 +1,215 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var ts = require('typescript');
+var utils_messages = require('../../utils/messages.js');
+var utils_packageConfig = require('../../package-config-BhU2TfC8.js');
+var migrations_readStateDwellHandlers_data = require('./data.js');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+const TS_EXT = '.ts';
+const LABEL = '[read-state-dwell-handlers]';
+/** Hand-written TypeScript: neither a declaration file nor a template type-check file. */
+const isMigratableTs = (filePath) => filePath.endsWith(TS_EXT) && !filePath.endsWith('.d.ts') && !filePath.endsWith('.ngtypecheck.ts');
+/** Applies text-span edits to `content`, right-to-left, so earlier edits don't shift later offsets. */
+function applyEdits(content, edits) {
+    const sorted = [...edits].sort((a, b) => b.start - a.start || b.end - a.end);
+    let result = content;
+    for (const { start, end, text } of sorted) {
+        result = result.slice(0, start) + text + result.slice(end);
+    }
+    return result;
+}
+const isFunctionLike = (node) => ts.isFunctionDeclaration(node) ||
+    ts.isMethodDeclaration(node) ||
+    ts.isConstructorDeclaration(node) ||
+    ts.isArrowFunction(node) ||
+    ts.isFunctionExpression(node) ||
+    ts.isGetAccessorDeclaration(node) ||
+    ts.isSetAccessorDeclaration(node);
+/**
+ * Where a `let`/`const` binding stops being visible.
+ *
+ * A local has to be scoped to its own block rather than to the enclosing function: two siblings can
+ * declare the same name, and only one of them may be the directive. Scoping to the function would
+ * rewrite calls on the other one.
+ */
+const isBlockLike = (node) => ts.isBlock(node) || ts.isCaseClause(node) || ts.isDefaultClause(node) || ts.isModuleBlock(node);
+/** Walks up from `node` to the nearest ancestor matching `predicate`. */
+function findAncestor(node, predicate) {
+    let current = node.parent;
+    while (current) {
+        if (predicate(current))
+            return current;
+        current = current.parent;
+    }
+    return undefined;
+}
+/** Whether a type annotation refers to the directive. */
+function isDirectiveType(type) {
+    return (!!type &&
+        ts.isTypeReferenceNode(type) &&
+        ts.isIdentifier(type.typeName) &&
+        type.typeName.text === migrations_readStateDwellHandlers_data.DIRECTIVE_TYPE);
+}
+/**
+ * Whether an initializer is `inject(KbqReadStateDirective, …)` or `inject<KbqReadStateDirective>(…)`.
+ * The directive has no selector, so a host reaches it through `inject()` and usually leaves the field
+ * without a type annotation.
+ */
+function isDirectiveInject(initializer) {
+    if (!initializer || !ts.isCallExpression(initializer))
+        return false;
+    if (!ts.isIdentifier(initializer.expression) || initializer.expression.text !== 'inject')
+        return false;
+    const [first] = initializer.arguments;
+    return ((!!first && ts.isIdentifier(first) && first.text === migrations_readStateDwellHandlers_data.DIRECTIVE_TYPE) ||
+        (initializer.typeArguments ?? []).some(isDirectiveType));
+}
+const FIELD_MODIFIERS = new Set([
+    ts.SyntaxKind.PrivateKeyword,
+    ts.SyntaxKind.PublicKeyword,
+    ts.SyntaxKind.ProtectedKeyword,
+    ts.SyntaxKind.ReadonlyKeyword
+]);
+/**
+ * Collects the receivers whose static type is the directive, by explicit annotation or by an
+ * `inject()` initializer (no cross-package type resolution): method/function params, class fields
+ * (incl. constructor parameter-properties) and typed locals.
+ */
+function collectReceivers(sourceFile) {
+    const receivers = [];
+    const add = (text, scope) => receivers.push({ text, start: scope.getStart(sourceFile), end: scope.getEnd() });
+    const visit = (node) => {
+        if (ts.isParameter(node) && ts.isIdentifier(node.name) && isDirectiveType(node.type)) {
+            add(node.name.text, findAncestor(node, isFunctionLike) ?? sourceFile);
+            // A constructor parameter-property is also a class field, reachable as `this.<name>`.
+            if (node.modifiers?.some((modifier) => FIELD_MODIFIERS.has(modifier.kind))) {
+                const owner = findAncestor(node, ts.isClassDeclaration);
+                if (owner)
+                    add(`this.${node.name.text}`, owner);
+            }
+        }
+        else if (ts.isPropertyDeclaration(node) &&
+            ts.isIdentifier(node.name) &&
+            (isDirectiveType(node.type) || isDirectiveInject(node.initializer))) {
+            const owner = findAncestor(node, ts.isClassDeclaration);
+            if (owner)
+                add(`this.${node.name.text}`, owner);
+        }
+        else if (ts.isVariableDeclaration(node) &&
+            ts.isIdentifier(node.name) &&
+            (isDirectiveType(node.type) || isDirectiveInject(node.initializer))) {
+            add(node.name.text, findAncestor(node, isBlockLike) ?? sourceFile);
+        }
+        node.forEachChild(visit);
+    };
+    visit(sourceFile);
+    return receivers;
+}
+/** Whether a property access on a receiver is within one of the receiver's scopes. */
+function inReceiverScope(node, sourceFile, receivers) {
+    const receiverText = node.expression.getText(sourceFile);
+    const start = node.getStart(sourceFile);
+    const end = node.getEnd();
+    return receivers.some((r) => r.text === receiverText && start >= r.start && end <= r.end);
+}
+/** Walks every property access made on a known directive receiver. */
+function forEachReceiverAccess(sourceFile, receivers, visitor) {
+    const visit = (node) => {
+        if (ts.isPropertyAccessExpression(node) &&
+            ts.isIdentifier(node.name) &&
+            inReceiverScope(node, sourceFile, receivers)) {
+            visitor(node, node.name.text);
+        }
+        node.forEachChild(visit);
+    };
+    visit(sourceFile);
+}
+function parse(content, fileName) {
+    return ts.createSourceFile(fileName, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+}
+/** Rewrites the renamed handlers on every receiver typed as the directive. */
+function migrateTs(content, fileName) {
+    const sourceFile = parse(content, fileName);
+    const receivers = collectReceivers(sourceFile);
+    if (receivers.length === 0)
+        return content;
+    const edits = [];
+    forEachReceiverAccess(sourceFile, receivers, (node, name) => {
+        const renamed = migrations_readStateDwellHandlers_data.RENAMES.get(name);
+        if (renamed) {
+            edits.push({ start: node.name.getStart(sourceFile), end: node.name.getEnd(), text: renamed });
+        }
+    });
+    return edits.length > 0 ? applyEdits(content, edits) : content;
+}
+/** Reports the members that changed shape rather than name. */
+function warnReceiverMembers(context, filePath, content) {
+    const sourceFile = parse(content, filePath);
+    const receivers = collectReceivers(sourceFile);
+    if (receivers.length === 0)
+        return;
+    let found = false;
+    forEachReceiverAccess(sourceFile, receivers, (_node, name) => {
+        if (migrations_readStateDwellHandlers_data.WARN_MEMBERS.includes(name))
+            found = true;
+    });
+    if (found) {
+        utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${migrations_readStateDwellHandlers_data.TIMESTAMP_MESSAGE}`]);
+    }
+}
+function logWarnings(context, filePath, content) {
+    for (const { pattern, message } of migrations_readStateDwellHandlers_data.warnPatterns) {
+        if (new RegExp(pattern).test(content)) {
+            utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${message}`]);
+        }
+    }
+}
+function readStateDwellHandlers(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) => {
+            // Declarations carry no call sites and `.ngtypecheck.ts` is regenerated on every build, so
+            // neither can hold a call worth rewriting — and an edit to either would be noise at best.
+            if (isMigratableTs(filePath))
+                filePaths.push(filePath);
+        });
+        let touched = 0;
+        for (const filePath of filePaths) {
+            const original = tree.read(filePath)?.toString();
+            // The directive has no selector — it is reachable through `hostDirectives` and `inject()`
+            // only, so a consumer always names it.
+            if (!original || !original.includes(migrations_readStateDwellHandlers_data.DIRECTIVE_TYPE))
+                continue;
+            logWarnings(context, filePath, original);
+            warnReceiverMembers(context, filePath, original);
+            const content = migrateTs(original, filePath);
+            if (content === original)
+                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).`
+        ]);
+    };
+}
+
+exports.default = readStateDwellHandlers;

package/schematics/migrations/read-state-dwell-handlers/schema.json

@@ -0,0 +1,20 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-read-state-dwell-handlers",
+    "title": "Koobiq components read-state dwell handler rename",
+    "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/scrollbar-deprecated-path/README.md

@@ -0,0 +1,128 @@
+# scrollbar-deprecated-path
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21`
+(registered for `21.0.0-0`). Rewrites `@koobiq/components/scrollbar` imports to
+`@koobiq/components/scrollbar/deprecated`.
+
+## Background
+
+`@koobiq/components/scrollbar` now resolves to a new, dependency-free scrollbar built on
+`CdkScrollable`. The previous implementation — the `overlayscrollbars`-based `KbqScrollbar`
+component together with `KbqScrollbarDirective` — moved to
+`@koobiq/components/scrollbar/deprecated` and will be removed in 22.0.0.
+
+Nothing about that implementation changed: `initializationTarget`, `options`, `events`, `defer`,
+`scrollbarInstance`, the `onInitialize` / `onUpdate` / `onDestroy` / `onScroll` outputs and the
+`kbq-scrollbar` element selector all behave exactly as before at the new path. Rewriting the
+import is the whole migration — adopting the new scrollbar is a separate, manual step.
+
+## Behaviour change
+
+The two entry points share only two exported names, so most unmigrated imports break loudly:
+`KbqScrollbarModule`, `KbqScrollbarDirective`, `KBQ_SCROLLBAR_CONFIG`,
+`KBQ_SCROLLBAR_OPTIONS_DEFAULT_CONFIG`, `KBQ_SCROLLBAR_OPTIONS_DEFAULT_CONFIG_PROVIDER`,
+`KbqScrollbarEvents`, `KbqScrollbarEventListenerArgs` and `KbqScrollbarTarget` live at the
+`/deprecated` path only, so the build stops with `TS2305: … has no exported member`.
+
+`KbqScrollbar` and `KbqScrollbarOptions` are the silent pair — both names exist at both paths:
+
+- `KbqScrollbar` keeps the `kbq-scrollbar` selector and `exportAs: 'kbqScrollbar'`, so a template
+  that only renders `<kbq-scrollbar>` keeps compiling and keeps rendering — with the new
+  component, which has a different set of inputs. The `[kbq-scrollbar]` attribute form of the
+  selector is gone as well, so a host marked that way quietly matches nothing.
+- `KbqScrollbarOptions` is now `{ mode: KbqScrollbarMode }` instead of the `overlayscrollbars`
+  `PartialOptions`.
+
+## 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/scrollbar` to `@koobiq/components/scrollbar/deprecated`.
+
+The match is quote-anchored (`(['"])@koobiq/components/scrollbar\1`), so only the exact, bare
+specifier is taken, in the quote style it was written in:
+
+| Specifier                                         | Result                                                                                 |
+| ------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `'@koobiq/components/scrollbar'`                  | rewritten, still single-quoted                                                         |
+| `"@koobiq/components/scrollbar"`                  | rewritten, still double-quoted                                                         |
+| `'@koobiq/components/scrollbar/deprecated'`       | untouched — the migration is idempotent                                                |
+| `'@koobiq/components/scrollbar-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                                                                                        |
+| `overlayscrollbars` in `package.json` | The `/deprecated` entry point still imports it. Adding it as a dependency is the `mandatory-peer-dependencies` migration's job                                                                     |
+| Moving off `/deprecated`              | Nothing is migrated _to_ the new scrollbar: `options` / `events` / `defer` are replaced by `kbqScrollbarMode`, and the `overlayscrollbars` instance by the `scrollTo*` methods and `scrollChanges` |
+
+`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:scrollbar-deprecated-path --project "<your project>"
+```
+
+Usage for Nx:
+
+```shell
+nx g @koobiq/components:scrollbar-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:scrollbar-deprecated-path --project koobiq-docs
+```
+
+### Result
+
+#### Before
+
+```ts
+import { Component } from '@angular/core';
+import { KbqScrollbarModule } from '@koobiq/components/scrollbar';
+
+@Component({
+    selector: 'my-page',
+    imports: [KbqScrollbarModule],
+    template: `
+        <kbq-scrollbar [options]="{ scrollbars: { autoHide: 'never' } }">...</kbq-scrollbar>
+    `
+})
+export class MyPage {}
+```
+
+#### After
+
+```ts
+import { Component } from '@angular/core';
+import { KbqScrollbarModule } from '@koobiq/components/scrollbar/deprecated';
+
+@Component({
+    selector: 'my-page',
+    imports: [KbqScrollbarModule],
+    template: `
+        <kbq-scrollbar [options]="{ scrollbars: { autoHide: 'never' } }">...</kbq-scrollbar>
+    `
+})
+export class MyPage {}
+```

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

@@ -0,0 +1,20 @@
+'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/scrollbar` now resolves to the new, dependency-free directive —
+ * the `overlayscrollbars`-based component/directive it used to export moved to
+ * `@koobiq/components/scrollbar/deprecated`. This rewrites the import specifier only;
+ * the API itself (`options`/`events`/`defer`/`scrollbarInstance`, the `kbq-scrollbar`
+ * element selector) is unchanged at its new path.
+ */
+var index = utils_deprecatedPathMigration.deprecatedPathMigration('scrollbar');
+
+exports.default = index;

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

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

@@ -0,0 +1,61 @@
+# select-signal-inputs
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21`
+(registered for `21.0.0-0`). Reports the `KbqSelect` members that became signal inputs or stopped
+being public in the select review. It never writes to the tree. `KbqTimezoneSelect` extends `KbqSelect`,
+so a file that names only the timezone select is reported as well.
+
+## Background
+
+The trigger-label surface moved to signal inputs, and the overlay plumbing was closed:
+
+| Member                                                    | Before                             | After                                   |
+| --------------------------------------------------------- | ---------------------------------- | --------------------------------------- |
+| `hiddenItemsText`                                         | accessor pair                      | `InputSignal<string \| undefined>`      |
+| `hiddenItemsTextFormatter`                                | overridable method                 | input holding the function              |
+| `overlayDir`                                              | public                             | `protected`                             |
+| `triggerRect`                                             | public                             | `protected`                             |
+| `onRemoveMatcherItem`                                     | `$event: any`                      | `$event: Event`                         |
+| `selectEvents`                                            | exported from `core/select/events` | removed together with the module        |
+| `hasBackdrop`, `compareWith`, `searchMinOptionsThreshold` | inputs                             | signals                                 |
+| `multiple`, `tabIndex`, `selectAllHandler`                | inputs                             | signal inputs, still read as properties |
+
+The template surface is untouched — every input kept its alias, so `[hiddenItemsText]` and
+`[hiddenItemsTextFormatter]` bind exactly as before. Only programmatic access changed.
+
+`selectEvents` was one constant whose value equalled its own name, read by nothing.
+
+## What it does _not_ do
+
+Nothing is rewritten. A read of a signal input becomes a call, a write becomes a template binding,
+and which of the two a call site wants cannot be derived from the expression.
+
+| Pattern                                                        | Manual migration                                                             |
+| -------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `.hiddenItemsText = …`                                         | Bind `[hiddenItemsText]` — an `input()` has no `.set()`                      |
+| `.hiddenItemsText`                                             | Read it as `hiddenItemsText()`; it reports `string \| undefined`             |
+| `.hiddenItemsTextFormatter`                                    | `hiddenItemsTextFormatter()(template, count)`; an override becomes a binding |
+| `.overlayDir` / `.triggerRect`                                 | Protected; use the open/close API and the panel inputs                       |
+| `selectEvents`                                                 | Delete the import                                                            |
+| `.hasBackdrop` / `.compareWith` / `.searchMinOptionsThreshold` | Read them as calls: `compareWith()(a, b)`                                    |
+| `.multiple = …` and the other signal inputs                    | Bind them in the template                                                    |
+
+## Notes with no call site to point at
+
+- Multiple mode orders the selection by the panel. `sortValues()` was documented as sorting by panel
+  order, but its default comparator was `a.value - b.value`: `NaN` on string values, which a sort
+  treats as "equal" and so leaves the arrival order in place, and plain numeric order otherwise. The
+  default is the option's index in the panel now, with an unrendered value — a `KbqVirtualOption`
+  under virtual scroll, or `showPreselectedValues` — sorting last. It is visible in the emitted form
+  value, the trigger tags, and the option highlighted on open. `[sortComparator]` still wins:
+  `(a, b) => a.value - b.value` restores the old numeric order, `() => 0` the old arrival order.
+- The locale subscription created in the constructor had no teardown, and a root-provided singleton
+  held every created-then-destroyed select for the lifetime of the app. That is fixed.
+- The select carries combobox/listbox/option ARIA now, and the tag-remove control is keyboard
+  operable, so hand-rolled `role` or `aria-*` attributes on the host are duplicates.
+
+## Running it manually
+
+```
+ng generate @koobiq/components:select-signal-inputs --project my-app
+```

package/schematics/migrations/select-signal-inputs/data.js

@@ -0,0 +1,99 @@
+'use strict';
+
+/**
+ * Data for the `select-signal-inputs` migration.
+ *
+ * The select review moved the trigger-label surface to signal inputs and closed the overlay
+ * internals:
+ *
+ * - `hiddenItemsText` — accessor pair → `InputSignal<string | undefined>`.
+ * - `hiddenItemsTextFormatter` — a method a subclass could override → an input holding the function.
+ * - `overlayDir`, `triggerRect` — public → `protected`.
+ * - `onRemoveMatcherItem(option, $event)` — the event parameter is `Event` instead of `any`.
+ * - `selectEvents`, and the whole `core/select/events.ts` it lived in, are gone. The module held one
+ *   constant whose value equalled its own name and nothing read it.
+ *
+ * The template surface is untouched: every input keeps its alias, so `[hiddenItemsText]` and
+ * `[hiddenItemsTextFormatter]` bind exactly as before. Only programmatic access changed.
+ *
+ * Warn-only. A read of a signal input becomes a call, a write becomes the binding, and which of the
+ * two a call site wants cannot be derived from the expression.
+ */
+/** Import specifiers that mark a file as a select consumer. */
+const SELECT_PACKAGE = '@koobiq/components/select';
+/**
+ * Identifier and attribute shapes that mark a consumer without an import: the select and the timezone select,
+ * which extends it and inherits every member reported here. `selectEvents` is in the list because it was exported
+ * from `@koobiq/components/core`, so a file importing it need not name the select at all — and that file is
+ * exactly the one whose import no longer resolves.
+ */
+const SELECT_TYPE = '\\bKbq(?:Timezone)?Select\\w*\\b|\\bkbq-(?:timezone-)?select\\b|\\bselectEvents\\b';
+const warnPatterns = [
+    {
+        anchor: SELECT_TYPE,
+        pattern: '\\.\\s*hiddenItemsText\\s*=(?!=)',
+        message: 'KbqSelect.hiddenItemsText is an InputSignal — an input() has no .set(), so the assignment no ' +
+            'longer compiles. Bind [hiddenItemsText] in the template instead. The alias is unchanged, so an ' +
+            'existing binding needs nothing.'
+    },
+    {
+        anchor: SELECT_TYPE,
+        pattern: '\\.\\s*hiddenItemsText\\b(?!\\s*[=(])',
+        message: 'KbqSelect.hiddenItemsText is an InputSignal: read it as `hiddenItemsText()`. Note it reports ' +
+            '`string | undefined` — the locale default is applied where the label is built, not in the input.'
+    },
+    {
+        anchor: SELECT_TYPE,
+        pattern: '\\.\\s*hiddenItemsTextFormatter\\b',
+        message: 'KbqSelect.hiddenItemsTextFormatter is an input holding the function, not a method. Call it as ' +
+            '`hiddenItemsTextFormatter()(template, count)`, and replace an override in a subclass with a ' +
+            '[hiddenItemsTextFormatter] binding.'
+    },
+    {
+        anchor: SELECT_TYPE,
+        pattern: '\\.\\s*(?:overlayDir|triggerRect)\\b',
+        message: 'KbqSelect.overlayDir and KbqSelect.triggerRect are protected. They are the overlay plumbing; ' +
+            'the supported surface is the open/close API and the panel inputs.'
+    },
+    {
+        anchor: '\\bselectEvents\\b|core/select/events',
+        pattern: '\\bselectEvents\\b|core/select/events',
+        message: 'selectEvents and the core/select/events module were removed. The module exported one constant ' +
+            "whose value equalled its own name ('selectEvents') and nothing read it — delete the import."
+    },
+    {
+        anchor: SELECT_TYPE,
+        pattern: '\\.\\s*(?:hasBackdrop|compareWith|searchMinOptionsThreshold)\\b(?!\\s*[=(])',
+        message: 'KbqSelect.hasBackdrop, .compareWith and .searchMinOptionsThreshold are signals now: read them as ' +
+            'calls, e.g. `compareWith()(a, b)`. searchMinOptionsThreshold() still reports the resolved number.'
+    },
+    {
+        anchor: SELECT_TYPE,
+        pattern: '\\.\\s*(?:hasBackdrop|compareWith|searchMinOptionsThreshold|multiple|tabIndex|selectAllHandler)\\s*=(?!=)',
+        message: 'hasBackdrop, compareWith, searchMinOptionsThreshold, multiple, tabIndex and selectAllHandler of ' +
+            'KbqSelect are signal inputs, so an assignment no longer compiles. Bind them in the template; ' +
+            'multiple, tabIndex and selectAllHandler are still read as properties. This pattern also matches a ' +
+            'write to an unrelated object in the same file — check before changing it.'
+    }
+];
+/** Printed once per project, after the per-file reports. */
+const SUMMARY = [
+    '  Multiple mode orders the selection by the panel now. sortValues() was documented as sorting by ' +
+        'panel order, but its default comparator was `a.value - b.value` — NaN on string values, which a ' +
+        'sort treats as "equal" and so leaves the arrival order in place, and plain numeric order ' +
+        'otherwise. The default is the option index in the panel now, and a value with no rendered option ' +
+        '(a KbqVirtualOption under virtual scroll, or showPreselectedValues) sorts last. The order is ' +
+        'visible in the emitted form value, the trigger tags and the option highlighted on open. A host ' +
+        'that re-sorted the emitted value into panel order itself can drop that; to keep another order, ' +
+        'bind [sortComparator] — `(a, b) => a.value - b.value` restores the old numeric order, `() => 0` ' +
+        'the old arrival order.',
+    '  KbqSelect no longer leaks: the locale subscription created in the constructor had no teardown, and ' +
+        'a root-provided singleton held every created-then-destroyed select for the lifetime of the app.',
+    '  The select finally carries combobox/listbox/option ARIA and a keyboard-operable tag-remove ' +
+        'control, so hand-rolled role or aria-* attributes on the host are now duplicates.'
+];
+
+exports.SELECT_PACKAGE = SELECT_PACKAGE;
+exports.SELECT_TYPE = SELECT_TYPE;
+exports.SUMMARY = SUMMARY;
+exports.warnPatterns = warnPatterns;

package/schematics/migrations/select-signal-inputs/index.js

@@ -0,0 +1,57 @@
+'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_selectSignalInputs_data = require('./data.js');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+const LABEL = '[select-signal-inputs]';
+const EXTENSIONS = ['.ts'];
+/** A file is a select consumer if it imports the package or names the component. */
+function referencesSelect(content) {
+    return content.includes(migrations_selectSignalInputs_data.SELECT_PACKAGE) || new RegExp(migrations_selectSignalInputs_data.SELECT_TYPE).test(content);
+}
+/**
+ * Reports the `KbqSelect` members that became signal inputs or stopped being public. Never writes:
+ * a read of a signal input becomes a call and a write becomes a binding, and which of the two a call
+ * site wants cannot be derived from the expression.
+ *
+ * Only `.ts` is visited — every input kept its alias, so no template needs migrating.
+ */
+function selectSignalInputs(options) {
+    return async (tree, context) => {
+        const { project } = options;
+        const projectDefinition = await utils_packageConfig.setupOptions(project, tree);
+        const root = projectDefinition?.root ?? '';
+        const rootDir = root ? tree.getDir(root) : tree.root;
+        let consumers = 0;
+        let reported = 0;
+        utils_packageConfig.visitProjectFiles(rootDir, (filePath, entry) => {
+            if (!EXTENSIONS.some((extension) => filePath.endsWith(extension)))
+                return;
+            const content = entry?.content.toString();
+            if (!content || !referencesSelect(content))
+                return;
+            consumers++;
+            for (const { anchor, pattern, message } of migrations_selectSignalInputs_data.warnPatterns) {
+                if (!new RegExp(anchor).test(content) || !new RegExp(pattern).test(content))
+                    continue;
+                reported++;
+                utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${message}`]);
+            }
+        });
+        // Nothing here renders a select, so the summary would only be noise.
+        if (consumers === 0)
+            return;
+        utils_messages.logMessage(context.logger, [
+            `${LABEL} processed kbq-select under "${root || '<workspace root>'}", ` +
+                `${consumers} file(s) reference the select, ${reported} call site(s) reported.`,
+            ...migrations_selectSignalInputs_data.SUMMARY
+        ]);
+    };
+}
+
+exports.default = selectSignalInputs;

package/schematics/migrations/select-signal-inputs/schema.json

@@ -0,0 +1,15 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-select-signal-inputs",
+    "title": "Koobiq components select review 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"
+            }
+        }
+    }
+}