@koobiq/components 20.4.2 → 21.0.1

package/schematics/migrations/sidepanel-non-modal-behavior/README.md

@@ -0,0 +1,57 @@
+# sidepanel-non-modal-behavior
+
+Migration schematic invoked automatically by `ng update @koobiq/components@20`
+(registered for `21.0.0-0`). Reports what the sidepanel review changed about the panel's effect on the
+page around it. It never writes to the tree.
+
+## Background
+
+The non-modal mode is documented as "without page blocking", but every sidepanel got CDK's
+`BlockScrollStrategy`, which pins the document with `position: fixed`. The strategy follows the
+modality now, and `KbqSidepanelConfig` gained a `scrollStrategy` factory for the cases that want
+something else.
+
+| Change                                           | Before                          | After                                             |
+| ------------------------------------------------ | ------------------------------- | ------------------------------------------------- |
+| Scroll strategy                                  | `block()` for every panel       | `block()` with a backdrop, `reposition()` without |
+| `trapFocusAutoCapture` default                   | `!!hasBackdrop`                 | `true`                                            |
+| Container ARIA                                   | none                            | `role="dialog"`, `aria-modal`, `aria-labelledby`  |
+| Rest of the page while a modal sidepanel is open | reachable by the virtual cursor | `aria-hidden="true"`                              |
+| `FocusTrapFactory` override                      | on `KbqSidepanelModule`         | scoped to `KbqSidepanelContainerComponent`        |
+| `kbq-sidepanel-overlay` on the overlay host      | added, styled by nothing        | not added                                         |
+| Click inside a sidepanel at another edge         | closed this one                 | only the same-position stack closes               |
+
+The `FocusTrapFactory` entry is the one with the widest reach. It was an unscoped override of a
+`providedIn: 'root'` CDK service, so importing the sidepanel module changed the focus-trap
+implementation used by every trapping component in the application — modal, dropdown, popover — not
+just sidepanels. The sidepanel container keeps the override for itself, because
+`ConfigurableFocusTrapFactory` brings the inert strategy that pulls escaping focus back; nothing else
+in the package asked for it.
+
+## What it does _not_ do
+
+Nothing is rewritten. Whether a given non-modal panel wanted the page frozen, and whether an
+application had come to depend on the leaked focus-trap implementation, are decisions the schematic
+cannot make.
+
+| Pattern                                                      | Manual migration                                                                                   |
+| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
+| `{ hasBackdrop: false }`                                     | Pass `scrollStrategy` to keep the page frozen, `trapFocusAutoCapture: false` to keep focus outside |
+| `config.hasBackdrop = …` after open                          | Decide the backdrop when opening; only `disableClose` is re-read                                   |
+| `overlayRef.backdropElement`                                 | `null` for a panel opened without a backdrop — the `!` only silenced the compiler                  |
+| `.kbq-sidepanel-overlay` in a stylesheet                     | Tag the overlay pane with `overlayPanelClass` instead                                              |
+| `host: { class: 'layout-column flex' }` on sidepanel content | Delete it; the package styles the portal host                                                      |
+
+## Notes with no call site to point at
+
+- `KbqSidepanelService` is `providedIn: 'root'`. `KbqSidepanelModule` still provides it, so existing
+  per-module instances are unchanged, and a component-provided service now closes the sidepanels it
+  opened when it is destroyed instead of leaking them.
+- `KbqSidepanelClose` injects `KbqSidepanelRef` non-optionally; the `setTimeout` fallback that looked
+  the ref up by container id is gone.
+
+## Running it manually
+
+```
+ng generate @koobiq/components:sidepanel-non-modal-behavior --project my-app
+```

package/schematics/migrations/sidepanel-non-modal-behavior/data.cjs

@@ -0,0 +1,111 @@
+'use strict';
+
+/**
+ * Data for the `sidepanel-non-modal-behavior` migration.
+ *
+ * The sidepanel review changed what a sidepanel does to the page around it:
+ *
+ * - A sidepanel without a backdrop no longer applies CDK's `BlockScrollStrategy`. The non-modal mode
+ *   is documented as "without page blocking", but every panel got `block()`, which pins the document
+ *   with `position: fixed`.
+ * - `trapFocusAutoCapture` defaults to `true` in both modalities instead of following `hasBackdrop`,
+ *   so a non-modal sidepanel moves focus into itself on open and returns it to the trigger on close.
+ * - The container is a `role="dialog"` with `aria-modal` and a name taken from `kbq-sidepanel-header`,
+ *   and a modal sidepanel hides the rest of the page from assistive technology while it is open.
+ * - `KbqSidepanelModule` no longer swaps `FocusTrapFactory` for `ConfigurableFocusTrapFactory`
+ *   application-wide; the override is scoped to the sidepanel container.
+ * - The overlay host element no longer gets the unstyled `kbq-sidepanel-overlay` class.
+ *
+ * Warn-only. Whether a given non-modal panel wanted the page frozen, and whether an application was
+ * relying on the leaked focus-trap implementation, are decisions this migration cannot make.
+ */
+/** Import specifier that marks a file as a sidepanel consumer. */
+const SIDEPANEL_PACKAGE = '@koobiq/components/sidepanel';
+/**
+ * Identifier and element shapes that mark a consumer without an import.
+ *
+ * The lookbehind keeps the `--kbq-sidepanel-*` design tokens out: a custom property always carries the
+ * leading `--`, and a stylesheet that merely reads one is not a consumer of anything this migration
+ * changed. A selector or an element — `.kbq-sidepanel-overlay`, `<kbq-sidepanel-header>` — is preceded
+ * by something else and still matches.
+ */
+const SIDEPANEL_TYPE = '\\bKbqSidepanel\\w*\\b|(?<!-)\\bkbq-sidepanel\\b';
+const warnPatterns = [
+    {
+        anchor: SIDEPANEL_TYPE,
+        pattern: 'hasBackdrop\\s*:\\s*false',
+        message: 'A sidepanel opened with hasBackdrop: false no longer blocks the page scroll. Every panel used ' +
+            "to get CDK's BlockScrollStrategy, which pins the document with `position: fixed` — the exact " +
+            'opposite of what the non-modal mode documents. Pass scrollStrategy: () => ' +
+            'overlay.scrollStrategies.block() in KbqSidepanelConfig if a particular panel wants the page ' +
+            'frozen. The same panel now captures focus on open and returns it to the trigger on close: ' +
+            'trapFocusAutoCapture defaults to true in both modalities instead of following hasBackdrop, ' +
+            'because CdkTrapFocus only restores focus it captured itself. Pass trapFocusAutoCapture: false to ' +
+            'leave focus where it was. The focus trap itself still follows hasBackdrop — set trapFocus: true ' +
+            'to keep Tab inside a non-modal panel, which also hides the rest of the page from assistive ' +
+            'technology.'
+    },
+    {
+        anchor: SIDEPANEL_TYPE,
+        pattern: '\\.\\s*config\\s*\\.\\s*hasBackdrop\\s*=(?!=)',
+        message: 'Assigning KbqSidepanelRef.config.hasBackdrop on an open sidepanel has never done anything — the ' +
+            'value is read once, when the overlay is built — and the docs that said otherwise are corrected. ' +
+            'disableClose is the one config property that is re-read after open.'
+    },
+    {
+        anchor: SIDEPANEL_TYPE,
+        // Matched as a property access: `sidepanelResult` is an ordinary enough name for a host to own one.
+        pattern: '\\.\\s*sidepanelResult\\b',
+        message: 'KbqSidepanelClose.sidepanelResult is an input signal now, aliased kbq-sidepanel-close as before. ' +
+            'Reading it takes a call — sidepanelResult() — and it can no longer be assigned: bind the value in ' +
+            'the template, <button kbq-sidepanel-close="value"> or [kbqSidepanelClose]="value". The directive ' +
+            'no longer implements OnChanges, and the two spellings are read through one computed, with the ' +
+            'camel-case one winning if a template binds both.'
+    },
+    {
+        anchor: SIDEPANEL_TYPE,
+        pattern: '\\boverlayRef\\s*\\.\\s*backdropElement\\b',
+        message: 'Reaching for KbqSidepanelRef.overlayRef.backdropElement to hide a backdrop throws on any panel ' +
+            'opened with hasBackdrop: false, where the element is null. Decide the backdrop when you open the ' +
+            'sidepanel.'
+    },
+    {
+        anchor: SIDEPANEL_TYPE,
+        // Bounded on both sides so the `--kbq-sidepanel-overlay-background` token does not read as the class:
+        // the token is preceded by `-` and continues with `-background`, the class does neither.
+        pattern: '(?<!-)\\bkbq-sidepanel-overlay\\b(?!-)',
+        message: 'The kbq-sidepanel-overlay class is no longer added to the overlay host element. Nothing in the ' +
+            'library ever styled it. Use overlayPanelClass in KbqSidepanelConfig to tag the overlay pane.'
+    },
+    {
+        anchor: SIDEPANEL_TYPE,
+        pattern: '\\b(?:layout-column\\s+flex|flex\\s+layout-column)\\b|:host\\s*\\{[^}]*display\\s*:\\s*flex',
+        message: 'The package styles the host element of a component-based sidepanel itself now ' +
+            '(.kbq-sidepanel-content-host: a flex column with min-height: 0). If the component you open in a ' +
+            "sidepanel carries `host: { class: 'layout-column flex' }` or a `:host { display: flex; … }` " +
+            'block only to make the body scroll and the footer stick, that workaround can go.'
+    }
+];
+/** Printed once per project, after the per-file reports. */
+const SUMMARY = [
+    '  KbqSidepanelModule no longer provides { provide: FocusTrapFactory, useClass: ' +
+        'ConfigurableFocusTrapFactory }. That was an unscoped override of a providedIn: "root" CDK service, ' +
+        'so importing the sidepanel module changed the focus-trap implementation of every trapping component ' +
+        'in the application — modal, dropdown, popover. The override is scoped to the sidepanel container ' +
+        'now; add the provider to your own application config if you were depending on it.',
+    '  The sidepanel container renders role="dialog", aria-modal for a modal panel and an aria-labelledby ' +
+        'pointing at the kbq-sidepanel-header title, and a modal sidepanel marks the rest of the page ' +
+        'aria-hidden while it is open. Pass ariaLabel or ariaLabelledBy in KbqSidepanelConfig for a panel ' +
+        'with no header, and drop any role or aria-* you were stamping on the container yourself.',
+    '  KbqSidepanelService is providedIn: "root", so KbqSidepanelModule is no longer the only way to get ' +
+        'one. The module still provides it, which keeps the existing per-module instances.',
+    '  A click inside a sidepanel at a different edge no longer closes this one: the outside-click filter ' +
+        'consults the position, so only the panels of the same stack close each other.',
+    '  KbqSidepanelClose injects KbqSidepanelRef non-optionally. The setTimeout fallback that looked the ref ' +
+        'up by container id is gone — the ref reaches template portals through the portal injector.'
+];
+
+exports.SIDEPANEL_PACKAGE = SIDEPANEL_PACKAGE;
+exports.SIDEPANEL_TYPE = SIDEPANEL_TYPE;
+exports.SUMMARY = SUMMARY;
+exports.warnPatterns = warnPatterns;

package/schematics/migrations/sidepanel-non-modal-behavior/index.cjs

@@ -0,0 +1,58 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var utils_messages = require('../../utils/messages.cjs');
+var utils_packageConfig = require('../../utils/package-config.cjs');
+var utils_projectFiles = require('../../utils/project-files.cjs');
+var migrations_sidepanelNonModalBehavior_data = require('./data.cjs');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+const LABEL = '[sidepanel-non-modal-behavior]';
+// Stylesheets are visited too: two of the patterns are about CSS the sidepanel no longer backs.
+const EXTENSIONS = ['.ts', '.html', '.scss', '.css'];
+/** A file is a sidepanel consumer if it imports the package, names the service or renders one of the parts. */
+function referencesSidepanel(content) {
+    return content.includes(migrations_sidepanelNonModalBehavior_data.SIDEPANEL_PACKAGE) || new RegExp(migrations_sidepanelNonModalBehavior_data.SIDEPANEL_TYPE).test(content);
+}
+/**
+ * Reports what the sidepanel review changed about the panel's effect on the page around it: the scroll
+ * block that no longer applies to non-modal panels, the focus that is captured and restored in both
+ * modalities, the dialog semantics on the container, and the application-wide `FocusTrapFactory`
+ * override that is gone. It never writes to the tree.
+ */
+function sidepanelNonModalBehavior(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_projectFiles.visitProjectFiles(rootDir, (filePath, entry) => {
+            if (!EXTENSIONS.some((extension) => filePath.endsWith(extension)))
+                return;
+            const content = entry?.content.toString();
+            if (!content || !referencesSidepanel(content))
+                return;
+            consumers++;
+            for (const { anchor, pattern, message } of migrations_sidepanelNonModalBehavior_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 opens a sidepanel, so the summary would only be noise.
+        if (consumers === 0)
+            return;
+        utils_messages.logMessage(context.logger, [
+            `${LABEL} processed kbq-sidepanel under "${root || '<workspace root>'}", ` +
+                `${consumers} file(s) reference the component, ${reported} call site(s) reported.`,
+            ...migrations_sidepanelNonModalBehavior_data.SUMMARY
+        ]);
+    };
+}
+
+exports.default = sidepanelNonModalBehavior;

package/schematics/migrations/sidepanel-non-modal-behavior/schema.json

@@ -0,0 +1,15 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-sidepanel-non-modal-behavior",
+    "title": "Koobiq components sidepanel 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"
+            }
+        }
+    }
+}

package/schematics/migrations/signal-inputs-subclasses/README.md

@@ -0,0 +1,28 @@
+# signal-inputs-subclasses
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21` (registered for `21.0.0-0`).
+Reports subclasses of the components whose decorator inputs became signal inputs. It never writes to the tree.
+
+## Background
+
+The inputs of `KbqCheckbox`, `KbqToggleComponent`, `KbqRadioGroup`, `KbqRadioButton`, `KbqButtonToggleGroup`,
+`KbqButtonToggle`, `KbqButton`, `KbqButtonGroupRoot`, `KbqSplitButton`, `KbqIcon`, `KbqIconButton`, `KbqIconItem` and
+`KbqSearchExpandable`, and of the pop-up triggers — tooltip, popover, popover confirm, app switcher, notification
+center, password toggle and ellipsis center — and of the tags, file uploads, accordion item, navbar item, notification
+item and sidebar are signal inputs named `<member>Input`, which `ngOnChanges` hands to the unchanged member.
+Reading and writing the members works as before. A member another migration moved to a signal, such as `color`
+(`color-signals`) or the `KbqFormFieldControl` members of the tag list (`form-field-signals`), is migrated there.
+
+| Pattern                                  | Manual migration                                                               |
+| ---------------------------------------- | ------------------------------------------------------------------------------ |
+| A subclass that implements `ngOnChanges` | Call `super.ngOnChanges(changes)`                                              |
+| A subclass that redeclares an `@Input()` | Override the `<member>Input` signal input with its alias, e.g. `iconNameInput` |
+| A panel that redeclares `elementRef`     | Override the protected `elementRef` getter over a `viewChild()`                |
+
+A boolean input accepts `boolean | string | null | undefined` in a template now, rather than anything.
+
+## Running it manually
+
+```bash
+ng g @koobiq/components:signal-inputs-subclasses --project "<your project>"
+```

package/schematics/migrations/signal-inputs-subclasses/data.cjs

@@ -0,0 +1,69 @@
+'use strict';
+
+/**
+ * Data for the `signal-inputs-subclasses` migration.
+ *
+ * The decorator inputs of the checkbox, toggle, radio, button toggle, buttons, icons, search-expandable and the
+ * pop-up triggers are signal inputs named `<member>Input` now, handed to the unchanged member from `ngOnChanges`.
+ * Reads and writes of the members are unchanged; a subclass is not. Warn-only. A member another migration moved to
+ * a signal, such as `color` or the `KbqFormFieldControl` members of the tag list, is migrated there.
+ */
+const COMPONENTS = [
+    'KbqCheckbox',
+    'KbqToggleComponent',
+    'KbqRadioGroup',
+    'KbqRadioButton',
+    'KbqButtonToggleGroup',
+    'KbqButtonToggle',
+    'KbqButton',
+    'KbqButtonGroupRoot',
+    'KbqSplitButton',
+    'KbqIcon',
+    'KbqIconButton',
+    'KbqIconItem',
+    'KbqSearchExpandable',
+    'KbqTooltipTrigger',
+    'KbqPopoverTrigger',
+    'KbqPopoverConfirmTrigger',
+    'KbqAppSwitcherTrigger',
+    'KbqAppSwitcherComponent',
+    'KbqNotificationCenterTrigger',
+    'KbqPasswordToggle',
+    'KbqEllipsisCenterDirective',
+    'KbqTagInput',
+    'KbqTagList',
+    'KbqTag',
+    'KbqSingleFileUploadComponent',
+    'KbqMultipleFileUploadComponent',
+    'KbqAccordionItem',
+    'KbqNavbarFocusableItem',
+    'KbqNavbarItem',
+    'KbqNotificationItemComponent',
+    'KbqSidebar'
+].join('|');
+const PANELS = ['KbqPopUp', 'KbqTooltipComponent', 'KbqPopoverComponent', 'KbqPopoverConfirmComponent'].join('|');
+const warnPatterns = [
+    {
+        anchor: `\\bextends\\s+(?:${COMPONENTS})\\b`,
+        pattern: `\\bextends\\s+(?:${COMPONENTS})\\b`,
+        message: 'A subclass of a Koobiq component whose inputs became signal inputs. The bound value reaches the member ' +
+            'from ngOnChanges now, so an ngOnChanges of the subclass has to call super.ngOnChanges(changes). An input ' +
+            'the subclass redeclared with @Input() is overridden through the `<member>Input` signal input instead, ' +
+            "e.g. `override readonly iconNameInput = input<string | undefined>(undefined, { alias: 'my-icon' })`."
+    },
+    {
+        anchor: `\\bextends\\s+(?:${PANELS})\\b`,
+        pattern: '@ViewChild\\([^)]*\\)\\s*(?:override\\s+)?elementRef\\b',
+        message: 'KbqPopUp.elementRef is a protected getter now, the element the pop-up measures and decorates. A panel ' +
+            'that renders an element of its own overrides the getter over a viewChild() instead of re-declaring the ' +
+            'field with @ViewChild.'
+    }
+];
+const SUMMARY = [
+    'Reads and writes of the members of these components are unchanged. A member another migration moved to a',
+    'signal, such as color or the KbqFormFieldControl members of the tag list, is migrated there. A boolean input',
+    'accepts boolean | string | null | undefined in a template now, rather than anything.'
+];
+
+exports.SUMMARY = SUMMARY;
+exports.warnPatterns = warnPatterns;

package/schematics/migrations/signal-inputs-subclasses/index.cjs

@@ -0,0 +1,18 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var utils_warnOnlyMigration = require('../../utils/warn-only-migration.cjs');
+var migrations_signalInputsSubclasses_data = require('./data.cjs');
+require('../../utils/messages.cjs');
+require('../../utils/package-config.cjs');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+require('../../utils/project-files.cjs');
+
+/** Reports subclasses of the components whose inputs became signal inputs feeding writable members. Never writes. */
+function signalInputsSubclasses(options) {
+    return utils_warnOnlyMigration.warnOnlyRule({ label: '[signal-inputs-subclasses]', warnPatterns: migrations_signalInputsSubclasses_data.warnPatterns, summary: migrations_signalInputsSubclasses_data.SUMMARY }, options);
+}
+
+exports.default = signalInputsSubclasses;

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

@@ -0,0 +1,15 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-signal-inputs-subclasses",
+    "title": "Koobiq components signal inputs subclasses 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/split-button-optional-disabled/README.md

@@ -0,0 +1,47 @@
+# split-button-optional-disabled
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21`
+(registered for `21.0.0-0`). Reports the `KbqSplitButton` members whose type changed in the
+split-button review. It never writes to the tree.
+
+## Background
+
+`disabled` was published as `boolean`, but the backing field is declared without an initializer and
+the setter returns early for `undefined`. A `<kbq-split-button>` with no `[disabled]` binding
+therefore reported `undefined` from a non-nullable type:
+
+```ts
+const flag: boolean = splitButton.disabled; // held undefined
+if (splitButton.disabled === false) { … }   // never ran
+```
+
+The getter now reports `boolean | undefined`, which is what the sibling `KbqButtonGroupRoot` has
+always reported. Nothing about the runtime value changed — the call sites that were quietly wrong
+now fail to compile.
+
+The `buttons` content query moved from `QueryList<KbqButton>` to a signal query in the same review.
+It is `protected`, so only a subclass sees it.
+
+## What it does _not_ do
+
+Nothing is rewritten. Narrowing `boolean | undefined` back to `boolean` is a decision — `?? false`,
+a non-null assertion, or handling the third state — and which one is right depends on what the call
+site does with the value.
+
+| Pattern                           | Manual migration                                                           |
+| --------------------------------- | -------------------------------------------------------------------------- |
+| `.disabled` on a `KbqSplitButton` | `?? false` for the common reading, or handle the unset state explicitly    |
+| `buttons.*` in a subclass         | Read `buttons()` and use array methods; `buttons.changes` no longer exists |
+
+## Notes with no call site to point at
+
+- A `<kbq-split-button>` with no projected button no longer throws outside dev mode. The guard sits
+  behind `isDevMode()`, so production renders an empty control instead of aborting the change
+  detection pass of whoever rendered it. A host that used the throw as a runtime assertion needs its
+  own check.
+
+## Running it manually
+
+```
+ng generate @koobiq/components:split-button-optional-disabled --project my-app
+```

package/schematics/migrations/split-button-optional-disabled/data.cjs

@@ -0,0 +1,53 @@
+'use strict';
+
+/**
+ * Data for the `split-button-optional-disabled` migration.
+ *
+ * `KbqSplitButton.disabled` was declared `boolean` over a field with no initializer, so an unbound
+ * control reported `undefined` through a non-nullable type: `const flag: boolean = sb.disabled` held
+ * `undefined`, and `if (sb.disabled === false)` never ran for a control nobody had disabled. The
+ * getter now reports `boolean | undefined`, matching the sibling `KbqButtonGroupRoot`, so those call
+ * sites finally fail to compile instead of lying at runtime.
+ *
+ * The content query moved from `QueryList<KbqButton>` to a signal query in the same review. It is
+ * `protected`, so only a subclass can see it.
+ *
+ * Warn-only. Narrowing `boolean | undefined` back to `boolean` is a decision — `?? false`, a
+ * non-null assertion, or handling the third state — and which one is right depends on what the call
+ * site does with it.
+ */
+/** Import specifier that marks a file as a split-button consumer. */
+const SPLIT_BUTTON_PACKAGE = '@koobiq/components/split-button';
+/** Identifier shape that marks a consumer without an import (e.g. a re-export or a subclass). */
+const SPLIT_BUTTON_TYPE = '\\bKbqSplitButton\\b';
+const SUBCLASS_ANCHOR = 'extends\\s+KbqSplitButton\\b';
+const warnPatterns = [
+    {
+        anchor: SPLIT_BUTTON_TYPE,
+        pattern: '\\.\\s*disabled\\b',
+        message: 'KbqSplitButton.disabled reports `boolean | undefined` instead of `boolean`. The backing field has ' +
+            'no initializer, so a control with no [disabled] binding always returned `undefined` behind a ' +
+            'non-nullable type — an assignment to a `boolean` held `undefined`, and `=== false` never matched. ' +
+            'Decide per call site: `?? false` for the common reading, or handle the unset state explicitly.'
+    },
+    {
+        anchor: SUBCLASS_ANCHOR,
+        pattern: '\\bbuttons\\s*\\.\\s*(?:changes|first|last|toArray|notifyOnChanges|reset|length|forEach|map|filter)\\b',
+        message: 'KbqSplitButton.buttons is a signal query — `Signal<readonly KbqButton[]>` instead of ' +
+            '`QueryList<KbqButton>`. Read it as `buttons()` and use array methods on the result; ' +
+            '`buttons.changes` is gone, and `buttons.length` is the arity of the signal function, not the ' +
+            'number of buttons.'
+    }
+];
+/** Printed once per project, after the per-file reports. */
+const SUMMARY = [
+    '  A <kbq-split-button> with no projected button no longer throws outside dev mode: the guard is ' +
+        'behind isDevMode(), so production renders an empty control instead of aborting the change ' +
+        'detection pass of whoever rendered it. A host that relied on the throw as a runtime assertion ' +
+        'needs its own check.'
+];
+
+exports.SPLIT_BUTTON_PACKAGE = SPLIT_BUTTON_PACKAGE;
+exports.SPLIT_BUTTON_TYPE = SPLIT_BUTTON_TYPE;
+exports.SUMMARY = SUMMARY;
+exports.warnPatterns = warnPatterns;

package/schematics/migrations/split-button-optional-disabled/index.cjs

@@ -0,0 +1,58 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var utils_messages = require('../../utils/messages.cjs');
+var utils_packageConfig = require('../../utils/package-config.cjs');
+var utils_projectFiles = require('../../utils/project-files.cjs');
+var migrations_splitButtonOptionalDisabled_data = require('./data.cjs');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+const LABEL = '[split-button-optional-disabled]';
+const EXTENSIONS = ['.ts'];
+/** A file is a split-button consumer if it imports the package or names the component. */
+function referencesSplitButton(content) {
+    return content.includes(migrations_splitButtonOptionalDisabled_data.SPLIT_BUTTON_PACKAGE) || new RegExp(migrations_splitButtonOptionalDisabled_data.SPLIT_BUTTON_TYPE).test(content);
+}
+/**
+ * Reports the `KbqSplitButton` members whose type changed. Never writes: narrowing
+ * `boolean | undefined` back to `boolean` is a decision the call site owns.
+ *
+ * Only `.ts` is visited — the component's template surface did not change, and the `disabled`
+ * binding accepts exactly what it did before.
+ */
+function splitButtonOptionalDisabled(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_projectFiles.visitProjectFiles(rootDir, (filePath, entry) => {
+            if (!EXTENSIONS.some((extension) => filePath.endsWith(extension)))
+                return;
+            const content = entry?.content.toString();
+            if (!content || !referencesSplitButton(content))
+                return;
+            consumers++;
+            for (const { anchor, pattern, message } of migrations_splitButtonOptionalDisabled_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 uses the split button, so the summary would only be noise.
+        if (consumers === 0)
+            return;
+        utils_messages.logMessage(context.logger, [
+            `${LABEL} processed kbq-split-button under "${root || '<workspace root>'}", ` +
+                `${consumers} file(s) reference the component, ${reported} call site(s) reported.`,
+            ...migrations_splitButtonOptionalDisabled_data.SUMMARY
+        ]);
+    };
+}
+
+exports.default = splitButtonOptionalDisabled;

package/schematics/migrations/split-button-optional-disabled/schema.json

@@ -0,0 +1,15 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-split-button-optional-disabled",
+    "title": "Koobiq components split-button 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"
+            }
+        }
+    }
+}