@koobiq/components 20.4.2 → 21.0.0

package/schematics/migrations/accordion-state-saving-default/README.md

@@ -0,0 +1,60 @@
+# accordion-state-saving-default
+
+Migration schematic invoked automatically by `ng update @koobiq/components@20`
+(registered for `21.0.0-0`). Reports the consequences of `KbqAccordion.useStateSaving` defaulting to
+`true`. It never writes to the tree.
+
+## Background
+
+`useStateSaving` shipped in 20.2.0 defaulting to `false`, and persisting anything also required a
+`stateSavingKey`: the fallback was the accordion's own id, which carries a global instantiation
+counter and therefore changes as soon as anything else on the page is created ahead of it. That is why
+the previous release warned about a missing key.
+
+Both are gone. An accordion with no `stateSavingKey` derives its key from where it sits in the
+document — the chain of tag names up to `<body>`, cut short by the first author-written `id`, which
+becomes the anchor. So `<kbq-accordion>` inside `<section id="settings">` persists under
+`#settings/kbq-accordion`, and everything above that `id` can be restructured without moving the key.
+
+With a usable key available for free, persistence is on by default.
+
+## What it reports
+
+- **The default flip.** A file that renders `kbq-accordion` and never writes `useStateSaving`.
+- **`defaultValue` demoted.** It applies to the first visit only; from the second one on, the sections
+  the user left open win.
+- **Positional item values.** `KbqAccordionItem.value` falls back to the item's position inside its
+  accordion instead of its id, because the position is what survives a reload. Only reported for a file
+  whose items carry no `value` at all.
+- **The inputs moved onto a host directive.** `useStateSaving` and `stateSavingKey` belong to
+  `KbqStateSaving`, which the accordion applies through `hostDirectives`. Templates are unaffected —
+  `<kbq-accordion useStateSaving>` binds them exactly as before — but they are no longer members of
+  `KbqAccordion`, so `accordion.useStateSaving()` does not compile. Reported for programmatic access only.
+
+Each check is evaluated against the whole file, matching the other warn-only migrations in this
+collection. A file holding two accordions where only one opts out is not reported — inspect it by hand.
+
+## What it does _not_ do
+
+It does not insert `[useStateSaving]="false"`. The markup whose behaviour changed is exactly the markup
+that says nothing about the input, so opting every accordion out would be a rewrite of every consumer
+template that also withholds the feature this release is shipping. Opting out stays a decision the
+application makes.
+
+## Storage format
+
+Entries are written under a `kbq.state.` prefix and carry a `savedAt` timestamp, so an entry stranded
+by a markup change is collected once it outlives `KBQ_STATE_SAVING_TTL` (90 days by default). Reading
+an entry refreshes it, so state that is visited but never changed does not expire under an active user.
+
+An entry written by 20.2.0 under the bare, unprefixed key is still read, so an upgrade does not reset
+what users had. It is never rewritten or removed: an unprefixed key is not necessarily ours, and an
+application storing its own `settings` must not lose it to a component keyed `stateSavingKey="settings"`.
+The first save moves the state under the prefix and takes over from there.
+
+## Related tokens
+
+- `KBQ_STATE_STORE` — where state is persisted. `KbqSessionStorageStateStore` is bundled for state that
+  should live no longer than the tab session.
+- `KBQ_STATE_SAVING_KEY_RESOLVER` — how the key is derived when no `stateSavingKey` is given.
+- `KBQ_STATE_SAVING_TTL` — how long an entry survives without being written or read.

package/schematics/migrations/accordion-state-saving-default/data.js

@@ -0,0 +1,75 @@
+'use strict';
+
+/**
+ * Data for the `accordion-state-saving-default` migration.
+ *
+ * `KbqAccordion.useStateSaving` defaults to `true`. An accordion that was never configured to persist
+ * anything now remembers which sections the user left open, which changes three things a consumer can
+ * only find out by reading:
+ *
+ * - `defaultValue` applies to the first visit only. From the second one on, the persisted state wins.
+ * - The storage key is derived from where the accordion sits in the document when no `stateSavingKey`
+ *   is given, so restructuring the markup above it strands what was saved under the previous key.
+ * - An item with no `value` persists its position inside the accordion, not the id it used to report.
+ *
+ * Warn-only. The markup whose behaviour changed is exactly the markup that says nothing about the
+ * input, so there is no expression to rewrite — and rewriting it to `[useStateSaving]="false"` would
+ * withhold the feature this release is shipping.
+ */
+/** Import specifiers that mark a file as an accordion consumer. */
+const ACCORDION_PACKAGE = '@koobiq/components/accordion';
+/** Identifier and element shapes that mark a consumer without an import. */
+const ACCORDION_TYPE = '\\bKbqAccordion\\b|<kbq-accordion\\b|\\bkbq-accordion\\b';
+const ACCORDION_ANCHOR = '<kbq-accordion\\b|\\bkbq-accordion\\b';
+const warnPatterns = [
+    {
+        anchor: ACCORDION_ANCHOR,
+        pattern: ACCORDION_ANCHOR,
+        unless: '\\buseStateSaving\\b',
+        message: 'Accordions persist their expanded sections by default now: useStateSaving defaults to true ' +
+            'instead of false. Pass [useStateSaving]="false" to keep the previous behaviour. To keep it ' +
+            'but pin where the state is stored, give the accordion a stateSavingKey — or an id, which ' +
+            'anchors the key derived from the document just as well.'
+    },
+    {
+        anchor: ACCORDION_ANCHOR,
+        pattern: '\\bdefaultValue\\b',
+        unless: '\\[useStateSaving\\]="false"',
+        message: 'defaultValue now applies to the first visit only — from the second one on, the sections the ' +
+            'user left open win. Pass [useStateSaving]="false" if the application owns the initial state.'
+    },
+    {
+        // Programmatic access names the class, which the markup-only anchor does not cover.
+        anchor: ACCORDION_TYPE,
+        pattern: '\\.\\s*(useStateSaving|stateSavingKey)\\b',
+        message: 'useStateSaving and stateSavingKey moved onto the KbqStateSaving host directive, so they are no ' +
+            'longer members of KbqAccordion. The markup is unchanged — <kbq-accordion useStateSaving> still ' +
+            'binds them — but reading them off the component, including through a template reference ' +
+            'variable, no longer compiles. Inject KbqStateSaving to reach them, or read the accordion ' +
+            'through KbqStateSavingService.'
+    },
+    {
+        anchor: '<kbq-accordion-item\\b|\\bkbq-accordion-item\\b',
+        pattern: '<kbq-accordion-item\\b|\\bkbq-accordion-item\\b',
+        unless: '\\[value\\]|\\svalue="|\\[useStateSaving\\]="false"',
+        message: 'Accordion items with no value are persisted by position now, and KbqAccordionItem.value ' +
+            'reports that position instead of the item id — the id carries a global instantiation ' +
+            'counter, which shifts as soon as anything else on the page is created ahead of the ' +
+            'accordion. Give each item an explicit value if valueChange payloads are compared anywhere.'
+    }
+];
+/** Printed once, after the per-file reports. */
+const SUMMARY = [
+    '  Storage format: entries are written under a "kbq.state." prefix and carry a timestamp, so an',
+    '  entry stranded by a markup change is collected once it outlives KBQ_STATE_SAVING_TTL (90 days by',
+    '  default). An entry written by 20.2.0 under the bare key is still read, but never rewritten or',
+    '  removed — the first save moves the state under the prefix and the original is left for the',
+    '  application to clean up.',
+    '  Provide KBQ_STATE_STORE to persist somewhere else (KbqSessionStorageStateStore is bundled), and',
+    '  KBQ_STATE_SAVING_KEY_RESOLVER to derive the key from something other than the document position.'
+];
+
+exports.ACCORDION_PACKAGE = ACCORDION_PACKAGE;
+exports.ACCORDION_TYPE = ACCORDION_TYPE;
+exports.SUMMARY = SUMMARY;
+exports.warnPatterns = warnPatterns;

package/schematics/migrations/accordion-state-saving-default/index.js

@@ -0,0 +1,60 @@
+'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_accordionStateSavingDefault_data = require('./data.js');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+const LABEL = '[accordion-state-saving-default]';
+const EXTENSIONS = ['.ts', '.html'];
+/** A file is an accordion consumer if it imports the package, names the component, or renders one. */
+function referencesAccordion(content) {
+    return content.includes(migrations_accordionStateSavingDefault_data.ACCORDION_PACKAGE) || new RegExp(migrations_accordionStateSavingDefault_data.ACCORDION_TYPE).test(content);
+}
+/**
+ * Reports the consequences of `KbqAccordion.useStateSaving` defaulting to `true`. Never writes: the
+ * markup whose behaviour changed is exactly the markup that does not mention the input, and rewriting
+ * it to opt out would withhold the feature the release is shipping.
+ *
+ * `.html` is visited as well as `.ts`, because every report keys off the rendered element rather than
+ * off an import.
+ */
+function accordionStateSavingDefault(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 || !referencesAccordion(content))
+                return;
+            consumers++;
+            for (const { anchor, pattern, unless, message } of migrations_accordionStateSavingDefault_data.warnPatterns) {
+                if (!new RegExp(anchor).test(content) || !new RegExp(pattern).test(content))
+                    continue;
+                if (unless && new RegExp(unless).test(content))
+                    continue;
+                reported++;
+                utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${message}`]);
+            }
+        });
+        // Nothing here renders an accordion, so the summary would only be noise.
+        if (consumers === 0)
+            return;
+        utils_messages.logMessage(context.logger, [
+            `${LABEL} processed kbq-accordion under "${root || '<workspace root>'}", ` +
+                `${consumers} file(s) reference the accordion, ${reported} report(s) raised.`,
+            ...migrations_accordionStateSavingDefault_data.SUMMARY
+        ]);
+    };
+}
+
+exports.default = accordionStateSavingDefault;

package/schematics/migrations/accordion-state-saving-default/schema.json

@@ -0,0 +1,15 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-accordion-state-saving-default",
+    "title": "Koobiq components accordion state saving default 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/actions-panel-overlay-container/README.md

@@ -0,0 +1,35 @@
+# actions-panel-overlay-container
+
+Migration schematic invoked automatically by `ng update @koobiq/components@20`
+(registered for `20.3.0-0`). Reports the call sites that `KbqActionsPanelConfig.overlayContainer`
+gives a new meaning to. It never writes to the tree.
+
+## Background
+
+`overlayContainer` was documented as the element the panel is displayed in, but it only anchored the
+positioning: CDK resolves the overlay host from the single `OverlayContainer` its `Dialog` was
+injected with, so the overlay itself stayed in the application-wide container. Every panel on a page
+therefore shared one container, and anything that relocated that container — a
+`FullscreenOverlayContainer`, for one — took all of them along with it.
+
+The panel now gets a `Dialog` of its own from a child environment injector, backed by an
+`OverlayContainer` scoped to the element, and renders inside it.
+
+## What changes for a call site
+
+- The panel is inside the element rather than floating above the page. An element with
+  `overflow: hidden` clips it; an element that scrolls its own content scrolls it out of view,
+  because the overlay is positioned against the content rather than against the visible area.
+- The element is mutated while the panel is open: it gains one child node holding the overlay, and a
+  `static` element is promoted to `position: relative`. That shifts `:empty`, `:last-child`,
+  `:nth-last-child()` and `childElementCount`.
+- `maxWidth` used to be ignored whenever `overlayContainer` was set — the panel was capped at the
+  container's measured width. It is applied as given now.
+- A panel opened with the option no longer uses a globally provided `OverlayContainer`. Both
+  settings answer "where is the panel rendered", and the per-panel one wins.
+
+## Why warn-only
+
+None of it can be rewritten automatically. Whether a panel that now sits inside a bordered, clipping
+or scrolling element is still where the product wants it is a layout question, not a syntactic one,
+and the fix ranges from doing nothing to moving the option to a different element.

package/schematics/migrations/actions-panel-overlay-container/data.js

@@ -0,0 +1,47 @@
+'use strict';
+
+/**
+ * Data for the `actions-panel-overlay-container` migration.
+ *
+ * `KbqActionsPanelConfig.overlayContainer` used to be an anchor for the positioning only: the overlay
+ * itself stayed in the application-wide CDK container. It now names the element the panel is rendered
+ * into, which changes three things at once for a call site that already passes it.
+ *
+ * Warn-only. None of it can be rewritten automatically: whether a panel that now sits inside a clipping or
+ * scrolling element is still where the product wants it is a layout question, not a syntactic one.
+ */
+/** Import specifier that marks a file as an actions panel consumer. */
+const ACTIONS_PANEL_PACKAGE = '@koobiq/components/actions-panel';
+/** Identifier shapes that mark a consumer without an import. */
+const ACTIONS_PANEL_TYPE = '\\bKbqActionsPanel\\w*\\b';
+const warnPatterns = [
+    {
+        anchor: ACTIONS_PANEL_TYPE,
+        pattern: '\\boverlayContainer\\s*:',
+        message: 'The panel passed `overlayContainer` is now rendered inside that element instead of `document.body`, ' +
+            'so it no longer floats above the page: an element with `overflow: hidden` clips it, and one that ' +
+            'scrolls its own content scrolls it out of view. The element is also mutated while the panel is open ' +
+            '(one extra child node, and `position: static` promoted to `relative`), which shifts `:empty`, ' +
+            '`:last-child`, `:nth-last-child()` and `childElementCount`. Check the layout, and move the option to ' +
+            'an element outside the scrolled area if the panel has to stay on a visible edge.'
+    },
+    {
+        anchor: ACTIONS_PANEL_TYPE,
+        pattern: '\\bmaxWidth\\s*:',
+        message: '`maxWidth` used to be ignored whenever `overlayContainer` was set — the panel was capped at the ' +
+            "container's measured width. It is now applied as given, so a value that was dead code before starts " +
+            'taking effect. Drop it to keep the previous width.'
+    }
+];
+/** Printed once per project, after the per-file reports. */
+const SUMMARY = [
+    '  A panel opened with `overlayContainer` no longer uses a globally provided `OverlayContainer`: the ' +
+        'two settings both answer "where is the panel rendered", and the per-panel one wins. An application ' +
+        'that swaps the container globally (`FullscreenOverlayContainer`, `kbqShadowDomOverlayProvider`) ' +
+        'keeps it for every panel opened without the option.'
+];
+
+exports.ACTIONS_PANEL_PACKAGE = ACTIONS_PANEL_PACKAGE;
+exports.ACTIONS_PANEL_TYPE = ACTIONS_PANEL_TYPE;
+exports.SUMMARY = SUMMARY;
+exports.warnPatterns = warnPatterns;

package/schematics/migrations/actions-panel-overlay-container/index.js

@@ -0,0 +1,54 @@
+'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_actionsPanelOverlayContainer_data = require('./data.js');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+const LABEL = '[actions-panel-overlay-container]';
+const EXTENSIONS = ['.ts', '.html'];
+/** A file is an actions panel consumer if it imports the package or names one of its types. */
+function referencesActionsPanel(content) {
+    return content.includes(migrations_actionsPanelOverlayContainer_data.ACTIONS_PANEL_PACKAGE) || new RegExp(migrations_actionsPanelOverlayContainer_data.ACTIONS_PANEL_TYPE).test(content);
+}
+/**
+ * Reports the call sites the `overlayContainer` change gives a new meaning to. Never writes: whether a
+ * panel that now renders inside the element is still where the product wants it is a layout question.
+ */
+function actionsPanelOverlayContainer(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 || !referencesActionsPanel(content))
+                return;
+            consumers++;
+            for (const { anchor, pattern, message } of migrations_actionsPanelOverlayContainer_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 an actions panel, so the summary would only be noise.
+        if (consumers === 0)
+            return;
+        utils_messages.logMessage(context.logger, [
+            `${LABEL} processed KbqActionsPanel under "${root || '<workspace root>'}", ` +
+                `${consumers} file(s) reference the actions panel, ${reported} call site(s) reported.`,
+            ...migrations_actionsPanelOverlayContainer_data.SUMMARY
+        ]);
+    };
+}
+
+exports.default = actionsPanelOverlayContainer;

package/schematics/migrations/actions-panel-overlay-container/schema.json

@@ -0,0 +1,15 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-actions-panel-overlay-container",
+    "title": "Koobiq components actions panel overlayContainer 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/alert-signals/README.md

@@ -22,13 +22,17 @@ The schematic walks every `.ts` and `.html` file in the project (skipping `node_
 files that reference the alert:
 
 - **TypeScript reads.** For a receiver whose static type is annotated `KbqAlert` (method/function params, class
-  fields — including `@ViewChild(KbqAlert) x: KbqAlert` and constructor parameter-properties — and typed locals),
-  a read of a value-safe signal member becomes a call:
+  fields — including `@ViewChild(KbqAlert) x: KbqAlert`, constructor parameter-properties and `inject(KbqAlert)` —
+  and typed locals), a read of a value-safe signal member becomes a call. A nested declaration that reuses the
+  receiver's name, and `this.<field>` inside a `function` that rebinds `this`, are left alone:
     - `alert.compact` → `alert.compact()` (incl. optional chain `alert?.compact` → `alert.compact()`)
     - `alert.alertStyle` → `alert.alertStyle()`
-- **Template reference reads.** For a `#ref` bound to `<kbq-alert>`, reads of `compact`/`alertStyle` through that
-  ref are rewritten in the same template (external `.html` and inline `template:` strings): `ref.compact` →
-  `ref.compact()`.
+- **Template reference reads.** For a bare `#ref` or `#ref="kbqAlert"` on `<kbq-alert>`, reads of
+  `compact`/`alertStyle` through that ref are rewritten in the same template (external `.html` and inline
+  `template:` strings): `ref.compact` → `ref.compact()`. A ref naming another directive (`#ref="ngModel"`) is
+  left alone, and so is a property chain that only ends in the ref's name (`state.alert.compact`). Only the
+  expressions of the view that declares the ref are looked at — prose, comments and plain attributes are not —
+  and a ref whose name a `@for`, `let-`, `*ngFor` or `@let` variable or another `#ref` shares is left alone.
 
 All rewrites are idempotent — running twice does not double the call. `compact`/`alertStyle` keep the same value,
 so appending `()` is safe.
@@ -41,6 +45,7 @@ These changes can't be rewritten safely and are surfaced as warnings (in both `f
 | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `alert.alertColor` read                                                                  | Now a read-only `InputSignal`: read as `alert.alertColor()`. **Value changed** — the getter used to return the CSS class `kbq-alert_<color>`, it now returns the raw color (`error`). Update any code that expected the class string. |
 | `alert.alertColor = …` write                                                             | The input is read-only. Drive it with the `[alertColor]` binding (or a signal in your own component), not an assignment.                                                                                                              |
+| `alert.compact = …` / `alertStyle` write, in code or through a template ref              | The inputs are read-only. Bind `[compact]` / `[alertStyle]` instead of assigning them. Also reported for `\|\|=`, `+=`, `++`, `delete` and a destructuring target.                                                                    |
 | `alert.icon` / `iconItem` / `button` / `title` / `control` / `closeButton` / `isColored` | Now `protected` — inaccessible from outside. Refactor to avoid reading component internals.                                                                                                                                           |
 | `[alertColor]` / `[alertStyle]` with a custom string                                     | The inputs are narrowed to the enum literals (`'error' \| 'warning' \| 'success' \| 'info'`, `'default' \| 'colored'`). Replace typos/custom strings with a valid value.                                                              |
 | `<kbq-alert compact>` (bare attribute)                                                   | Now applies the `booleanAttribute` transform, so the bare attribute really enables compact (it used to be a silent no-op). Verify this is intended.                                                                                   |
@@ -58,7 +63,8 @@ Pass `--fix=false` to see what would change without writing files.
 
 ## Limitations
 
-Receivers are matched by explicit `KbqAlert` type annotation only (no cross-package type inference), so
-aliased/inferred receivers (`const a = this.alert; a.compact`) are left untouched. `alertColor` is intentionally
+Receivers are matched by an explicit `KbqAlert` type annotation or an `inject()` initializer (no type inference),
+so inferred receivers (`const a = this.alert; a.compact`) and signal queries (`viewChild(KbqAlert)`) are left
+untouched. `alertColor` is intentionally
 **not** auto-rewritten because its value semantics changed. After running, **always inspect the diff** and act on
 the warnings before committing.

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

@@ -27,6 +27,8 @@ const WRITABLE_MEMBERS = new Set();
 const ALERT_TYPE = 'KbqAlert';
 /** Element selector whose template reference variables (`#ref`) point at an alert. */
 const ALERT_ELEMENT = 'kbq-alert';
+/** The only `#ref` value on `<kbq-alert>` that names the alert; `#ref="ngModel"` names another directive. */
+const ALERT_EXPORT_AS = 'kbqAlert';
 /**
  * `alertColor` became a read-only `InputSignal` AND changed its value: the getter used to return the CSS class
  * `kbq-alert_<color>`, it now returns the raw color (e.g. `error`). Because a mechanical `()` append would
@@ -62,6 +64,7 @@ const warnPatterns = [
 ];
 
 exports.ALERT_ELEMENT = ALERT_ELEMENT;
+exports.ALERT_EXPORT_AS = ALERT_EXPORT_AS;
 exports.ALERT_TYPE = ALERT_TYPE;
 exports.PROTECTED_MEMBERS = PROTECTED_MEMBERS;
 exports.SIGNAL_MEMBERS = SIGNAL_MEMBERS;