@koobiq/components 20.4.2 → 21.0.0

package/schematics/migrations/filter-bar-state-saving-default/index.js

@@ -0,0 +1,61 @@
+'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_filterBarStateSavingDefault_data = require('./data.js');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+const LABEL = '[filter-bar-state-saving-default]';
+const EXTENSIONS = ['.ts', '.html'];
+/** A file is a consumer if it imports the package, names the component, or renders one. */
+function referencesConsumer(content) {
+    return migrations_filterBarStateSavingDefault_data.PACKAGES.some((name) => content.includes(name)) || new RegExp(migrations_filterBarStateSavingDefault_data.CONSUMER_TYPE).test(content);
+}
+/**
+ * Reports the consequences of the filter bar persisting the selected filter and the edits made to it,
+ * with `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 most reports key off the rendered element rather than off
+ * an import.
+ */
+function filterBarStateSavingDefault(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 || !referencesConsumer(content))
+                return;
+            consumers++;
+            for (const { anchor, pattern, unless, message } of migrations_filterBarStateSavingDefault_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 a filter bar, so the summary would only be noise.
+        if (consumers === 0)
+            return;
+        utils_messages.logMessage(context.logger, [
+            `${LABEL} processed kbq-filter-bar under "${root || '<workspace root>'}", ` +
+                `${consumers} file(s) reference it, ${reported} report(s) raised.`,
+            ...migrations_filterBarStateSavingDefault_data.SUMMARY
+        ]);
+    };
+}
+
+exports.default = filterBarStateSavingDefault;

package/schematics/migrations/filter-bar-state-saving-default/schema.json

@@ -0,0 +1,15 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-filter-bar-state-saving-default",
+    "title": "Koobiq filter-bar 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/flag-inner-html/README.md

@@ -0,0 +1,67 @@
+# flag-inner-html
+
+Migration schematic invoked automatically by `ng update @koobiq/components@20`
+(registered for `21.0.0-0`). Moves `[innerHTML]` bindings off the `<kbq-flag>` host element onto the
+`svg` input the flag review added, and reports the behavior changes that have no call site to point
+at.
+
+## Background
+
+`KbqFlag` renders `<ng-content />`, so the host element is where projected nodes land. A parent
+binding `[innerHTML]` on `<kbq-flag>` compiles to a write of `hostElement.innerHTML` during the
+parent's update pass — the same element. The two only coexisted because the component's own view
+contributed no DOM: with nothing projected there was nothing for the write to destroy, which is why
+every published example got away with it.
+
+The review gave the string form a slot of its own:
+
+```html
+<!-- before -->
+<kbq-flag decorative [innerHTML]="flag" />
+
+<!-- after -->
+<kbq-flag decorative [svg]="flag" />
+```
+
+The `svg` input renders into a `<span>` inside the component's view, so projected content and string
+content no longer compete for the host element. The value is unchanged — Angular's sanitizer still
+strips an `<svg>` that has not been bypassed, so a flag coming from a package as a string still has to go through
+`DomSanitizer.bypassSecurityTrustHtml`, and only ever for markup known at build time.
+
+## What it rewrites
+
+`[innerHTML]` → `[svg]`, inside `<kbq-flag …>` opening tags only, in `.ts` and `.html` files that
+reference the flag. A binding on any other element — including one on a wrapper projected _into_ a
+flag — is left alone, because there the write targets an element the component does not own.
+
+## What it does not reach
+
+The rewrite is textual, so it only sees a literal `[innerHTML]=` inside a literal `<kbq-flag …>`
+opening tag. Two forms are invisible to it and have to be moved by hand:
+
+- an `innerHTML` write made from TypeScript against a flag element, through `Renderer2.setProperty`
+  or an assignment to a queried element's `innerHTML`;
+- a wrapper component of your own that publishes an `innerHTML`-named input and forwards it. The
+  `<kbq-flag [innerHTML]="…">` inside its template is rewritten, but the input it exposes to its own
+  callers keeps the old name.
+
+## Notes with no call site to point at
+
+- **A flag with no `label` is now `aria-hidden`.** The unlabelled, non-decorative flag reached the
+  accessibility tree as a nameless graphic, which the guide already called out as the one case that
+  must not happen. Give a meaningful flag a `label` — including one whose only name came from the
+  projected image (`alt`, an SVG `<title>`), which the default now hides.
+- **An inline `<svg>` is cropped instead of letterboxed.** `object-fit: cover` is inert on an inline
+  `<svg>` — it is not a replaced element — so a source whose ratio differed from the shape rendered
+  with transparent bands; `square` and `circle` were the visible cases. The same flag passed as an
+  `<img>` always cropped, and the two now match.
+- **`--kbq-flag-empty-background` resolves to an opaque neutral** instead of the translucent disabled
+  state, so the `empty` placeholder no longer takes on the hue of the surface behind it.
+- **The flag tokens are declared at zero specificity.** An override that used to lose to `.kbq-flag`
+  on source order now wins, so a redundant `!important` or an extra selector can be dropped.
+
+## Running it on its own
+
+```bash
+ng g @koobiq/components:flag-inner-html --project <your project>
+```

package/schematics/migrations/flag-inner-html/data.js

@@ -0,0 +1,58 @@
+'use strict';
+
+/**
+ * Data for the `flag-inner-html` migration.
+ *
+ * `KbqFlag` renders `<ng-content />`, so the host element is where projected nodes land. A parent
+ * binding `[innerHTML]` on `<kbq-flag>` writes that same element, and the two only coexisted because
+ * the component's own view contributed no DOM. The review gave the string form a slot of its own —
+ * the `svg` input — and the template now creates a node inside the host, so a host-level
+ * `[innerHTML]` write removes it along with anything projected.
+ *
+ * The rename is mechanical, so this migration rewrites it. Everything else in the review is a
+ * behavior change with no call site to point at, and is reported once per project.
+ */
+/** Import specifier that marks a file as a flag consumer. */
+const FLAG_PACKAGE = '@koobiq/components/flag';
+/** Identifier and element shapes that mark a consumer without an import. */
+const FLAG_TYPE = '\\bKbqFlag\\w*\\b|\\bkbq-flag\\b';
+/**
+ * Opening `<kbq-flag …>` tag, including the self-closing form. Closing tags do not match.
+ *
+ * Attribute values are matched as opaque quoted strings, so a `>` inside an attribute expression
+ * (e.g. `[class.a]="x > y"`) does not end the match early and strand a later `[innerHTML]` binding
+ * on the same tag outside it. The third alternative excludes both quote characters so that only one
+ * branch can consume a quote: an unterminated tag would otherwise backtrack exponentially.
+ */
+const FLAG_OPEN_TAG = /<kbq-flag\b(?:"[^"]*"|'[^']*'|[^>"'])*>/g;
+/** The binding this migration moves off the host element. */
+const INNER_HTML_BINDING = /\[innerHTML\]\s*=/g;
+const REWRITE_MESSAGE = '[innerHTML] on <kbq-flag> was rewritten to [svg]. The host element is where projected content ' +
+    'lands, so an innerHTML write replaces it; the svg input renders into a slot of its own. Pass it ' +
+    'the same SafeHtml — Angular still strips an <svg> that has not been bypassed.';
+/** Printed once per project, after the per-file reports. */
+const SUMMARY = [
+    '  The rewrite is textual and only sees a literal [innerHTML]= inside a literal <kbq-flag …> ' +
+        'opening tag. An innerHTML write made from TypeScript against a flag element, and an ' +
+        'innerHTML-named input that a wrapper component of yours forwards to a flag, are both ' +
+        'invisible to it and have to be moved by hand.',
+    '  A flag with no `label` is now aria-hidden. The unlabelled, non-decorative flag reached the ' +
+        'accessibility tree as a nameless graphic, which the guide already called out as the one case ' +
+        'that must not happen. Give a meaningful flag a `label` — including one whose only name came ' +
+        'from the projected image (`alt`, an SVG `<title>`), which the default now hides.',
+    '  An inline <svg> is cropped instead of letterboxed. `object-fit: cover` is inert on an inline ' +
+        '<svg> — it is not a replaced element — so a source whose ratio differed from the shape used to ' +
+        'render with transparent bands; `square` and `circle` are the visible cases. The same flag ' +
+        'passed as an <img> always cropped, and the two now match.',
+    '  --kbq-flag-empty-background resolves to an opaque neutral instead of the translucent disabled ' +
+        'state, so the `empty` placeholder no longer takes on the hue of the surface behind it.',
+    '  The flag tokens are declared at zero specificity. An override that used to lose to .kbq-flag ' +
+        'on source order now wins, so a redundant `!important` or an extra selector can be dropped.'
+];
+
+exports.FLAG_OPEN_TAG = FLAG_OPEN_TAG;
+exports.FLAG_PACKAGE = FLAG_PACKAGE;
+exports.FLAG_TYPE = FLAG_TYPE;
+exports.INNER_HTML_BINDING = INNER_HTML_BINDING;
+exports.REWRITE_MESSAGE = REWRITE_MESSAGE;
+exports.SUMMARY = SUMMARY;

package/schematics/migrations/flag-inner-html/index.js

@@ -0,0 +1,61 @@
+'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_flagInnerHtml_data = require('./data.js');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+const LABEL = '[flag-inner-html]';
+const EXTENSIONS = ['.ts', '.html'];
+/** A file is a flag consumer if it imports the package, names the component, or renders one. */
+function referencesFlag(content) {
+    return content.includes(migrations_flagInnerHtml_data.FLAG_PACKAGE) || new RegExp(migrations_flagInnerHtml_data.FLAG_TYPE).test(content);
+}
+/** Renames `[innerHTML]` to `[svg]` inside every `<kbq-flag …>` opening tag, and leaves the rest alone. */
+function rewriteInnerHtmlBindings(content) {
+    return content.replace(migrations_flagInnerHtml_data.FLAG_OPEN_TAG, (tag) => tag.replace(migrations_flagInnerHtml_data.INNER_HTML_BINDING, '[svg]='));
+}
+/**
+ * Moves `[innerHTML]` bindings off the `<kbq-flag>` host element onto the `svg` input the flag review
+ * added, and reports the behavior changes that have no call site to point at.
+ *
+ * `.html` is visited as well as `.ts`, because the binding lives in a template either way.
+ */
+function flagInnerHtml(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 rewritten = 0;
+        utils_packageConfig.visitProjectFiles(rootDir, (filePath, entry) => {
+            if (!EXTENSIONS.some((extension) => filePath.endsWith(extension)))
+                return;
+            const content = entry?.content.toString();
+            if (!content || !referencesFlag(content))
+                return;
+            consumers++;
+            const migrated = rewriteInnerHtmlBindings(content);
+            if (migrated === content)
+                return;
+            rewritten++;
+            tree.overwrite(filePath, migrated);
+            utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${migrations_flagInnerHtml_data.REWRITE_MESSAGE}`]);
+        });
+        // Nothing here renders a flag, so the summary would only be noise.
+        if (consumers === 0)
+            return;
+        utils_messages.logMessage(context.logger, [
+            `${LABEL} processed kbq-flag under "${root || '<workspace root>'}", ` +
+                `${consumers} file(s) reference the component, ${rewritten} file(s) rewritten.`,
+            ...migrations_flagInnerHtml_data.SUMMARY
+        ]);
+    };
+}
+
+exports.default = flagInnerHtml;
+exports.rewriteInnerHtmlBindings = rewriteInnerHtmlBindings;

package/schematics/migrations/flag-inner-html/schema.json

@@ -0,0 +1,15 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-flag-inner-html",
+    "title": "Koobiq components flag 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/form-field-signals/README.md

@@ -0,0 +1,125 @@
+# form-field-signals
+
+Migration schematic invoked automatically by `ng update @koobiq/components`.
+Migrates consumers of the full `@koobiq/components/form-field` review: the signal-based `KbqFormField` /
+`KbqHint` API, the new accessibility semantics of the cleaner and the password toggle, and the removal of the
+deprecated `mixinColor`.
+
+## Why
+
+`KbqFormField` finished its migration to signal queries and `KbqHint` to signal inputs, so every programmatic
+read of those members needs a call. The icon-only cleaner and password toggle became real buttons with a
+localized accessible name, which means the component now owns the `aria-label` a consumer used to set by hand.
+`KbqFormFieldControl` followed: the state of every control is a signal, and `stateChanges` is gone.
+Template _bindings_ (`[fillTextOff]`, `[compact]`, …) keep working — only programmatic reads/writes
+and template-reference reads break.
+
+| Member                                                                                                        | Before                  | After                                    | Auto-fix                         |
+| ------------------------------------------------------------------------------------------------------------- | ----------------------- | ---------------------------------------- | -------------------------------- |
+| `KbqFormField.cleaner` / `passwordToggle`                                                                     | `T \| null`             | `Signal<T \| undefined>`                 | ✅ read → call                   |
+| `KbqFormField.hint` / `prefix` / `suffix`                                                                     | `QueryList<T>`          | `Signal<readonly T[]>`                   | ✅ read → call                   |
+| `KbqFormField.hasCleaner` / `hasHint` / `hasPasswordToggle` / `hasPrefix` / `hasStepper` / `hasSuffix`        | getter                  | `Signal<boolean>`                        | ✅ read → call                   |
+| `KbqHint.fillTextOff` / `compact` (also on `KbqError`, `KbqReactivePasswordHint`)                             | `boolean` input         | `InputSignalWithTransform`               | ✅ read → call                   |
+| `<kbq-cleaner [attr.aria-label]>`                                                                             | plain attribute binding | `[aria-label]` input                     | ✅ rewritten                     |
+| `fiedset-theme` stylesheet                                                                                    | misspelled filename     | `fieldset-theme`                         | ✅ renamed                       |
+| `mixinColor` / `CanColorCtor`                                                                                 | exported from `core`    | removed                                  | ⚠️ warn                          |
+| `KbqA11yLocaleConfiguration`                                                                                  | 8 keys                  | +`clear`, `showPassword`, `hidePassword` | ⚠️ warn                          |
+| `KbqFormFieldRef.control`                                                                                     | `any`                   | `Signal<KbqFormFieldControlRef>`         | ⚠️ warn                          |
+| `value` / `id` / `placeholder` / `focused` / `empty` / `required` / `disabled` / `errorState` of the controls | property or getter      | `Signal`                                 | ✅ read → call, write → `.set()` |
+| `KbqTagInput.id` / `placeholder` / `focused` / `empty`                                                        | input, field or getter  | read-only `Signal`                       | ✅ read → call                   |
+| `KbqInputPassword.elementType`                                                                                | writable `string`       | read-only `Signal<'text' \| 'password'>` | ✅ read → call, ⚠️ write warned  |
+| `KbqFormFieldControl.stateChanges`                                                                            | `Observable<void>`      | removed                                  | ⚠️ warn                          |
+| `KbqFormField.hovered` / `onHoverChanged()`                                                                   | `boolean` / method      | removed                                  | ⚠️ warn                          |
+
+`control`, `stepper` and `connectionContainerRef` were already signals before this release and are deliberately
+left alone — appending `()` to them would be a double call.
+
+## What it does (auto-fix)
+
+The schematic walks every `.ts`, `.html`, `.scss` and `.css` file in the project (skipping `node_modules` and
+`dist`) and, for files that reference the form field:
+
+- **TypeScript reads.** For a receiver whose static type is annotated `KbqFormField`, `KbqHint`, `KbqError` or
+  `KbqReactivePasswordHint` (method/function params, class fields — including
+  `@ContentChild(KbqFormField) x: KbqFormField`, constructor parameter-properties and `inject(KbqFormField)` — and
+  typed locals), a read of a migrated member becomes a call: `formField.hasHint` → `formField.hasHint()` (incl.
+  optional chain `formField?.hint` → `formField?.hint()`). A nested declaration that reuses the receiver's name,
+  and `this.<field>` inside a `function` that rebinds `this`, are left alone.
+- **Control state.** On a receiver typed `KbqSelect`, `KbqTreeSelect`, `KbqTimezoneSelect`, `KbqTagList`,
+  `KbqTimepicker`, `KbqDatepickerInput`, `KbqInput`, `KbqInputPassword`, `KbqTextarea` or `KbqFormFieldControl`,
+  a read of `value`, `id`, `placeholder`, `focused`, `empty`, `required`, `disabled` or `errorState` becomes a
+  call. A plain `=` write becomes `.set()` where the member stays writable — `disabled` on the selects, the tag
+  list, the timepicker and the datepicker input, `value` on the select, the timezone select, the tag list and the
+  native-element controls, `placeholder` on the native-element controls. The tree select, the timepicker and the
+  datepicker input own their `value`, so a write to it is reported. The same reads of `id`, `placeholder`,
+  `focused` and `empty` on a receiver typed `KbqTagInput` become calls too, and so do reads of `elementType` on
+  a receiver typed `KbqInputPassword`, whose writes are reported.
+- **Template references.** For a `#ref` bound to `<kbq-form-field>`, `<kbq-hint>`, `<kbq-error>`,
+  `<kbq-reactive-password-hint>`, `<kbq-select>`, `<kbq-tree-select>`, `<kbq-timezone-select>` or
+  `<kbq-tag-list>`, reads through that ref are rewritten in the same template (external `.html` and inline
+  `template:` strings). The ref has to be bare or name the component's own `exportAs` (`#s="kbqSelect"`): one
+  that names another directive (`#s="ngModel"`) is left alone. The input, the password input, the textarea, the
+  timepicker, the datepicker input and the tag input are directives on a native element, where a bare ref is the
+  element, so only a ref naming their `exportAs` is followed: `#i="kbqInput"`, `kbqInputPassword`,
+  `kbqTextarea`, `kbqTimepicker`, `kbqDatepickerInput`, `kbqTagInput` or `kbqTagInputFor`.
+  Only the ref itself is matched — `form.controls.country.value` stays as it is. 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. In an event binding, a
+  write
+  to a writable member becomes `.set()`: `(click)="s.disabled = true"` → `(click)="s.disabled.set(true)"`;
+  `[(ngModel)]="tags.value"` keeps working on the signal unchanged.
+- **Cleaner accessible name.** `<kbq-cleaner [attr.aria-label]="…">` → `<kbq-cleaner [aria-label]="…">`. The
+  component now writes `aria-label` from a host binding, so an `attr.` binding is silently overwritten by the
+  localized default.
+- **Stylesheet import.** `fiedset-theme` → `fieldset-theme`.
+
+All rewrites are idempotent — running twice does not double the call.
+
+## What it does _not_ do (warn-only)
+
+These changes can't be rewritten safely and are surfaced as warnings (in both `fix` and dry-run mode):
+
+| Change                                                                    | Manual migration                                                                                                                                                                                   |
+| ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `formField.hint.changes` / `.first` / `.last` / `.toArray()` / `.get(i)`  | The content queries are signals over a readonly array. React with `computed()` / `effect()` instead of `.changes`, and index the array instead of the `QueryList` helpers.                         |
+| `formField.cleaner === null`                                              | `cleaner` / `passwordToggle` now return `undefined` when absent. Use a truthiness check or `== null`.                                                                                              |
+| `hint.fillTextOff = …` / `hint.compact = …`                               | Read-only signal inputs now. Drive them with a template binding (`[fillTextOff]="…"`), not an assignment.                                                                                          |
+| `formField.cleaner = …` / `hint` / `prefix` / `suffix` / `passwordToggle` | Read-only signal content queries now. Project the content instead — code that assigned a query result (usually a test faking it) has to render the real component.                                 |
+| `mixinColor(...)` / `CanColorCtor`                                        | Removed, and `CanColor` with them. Extend `KbqColorDirective`, which exposes the same `color` input and `colorClassName` getter, or type a member `Signal<KbqComponentColors \| string>`.          |
+| A custom `KbqA11yLocaleConfiguration`                                     | Add the three new keys — `clear`, `showPassword`, `hidePassword` — used for the accessible names of the cleaner and the password toggle.                                                           |
+| `inject(KBQ_FORM_FIELD_REF)` + `formField.control.<member>`               | `control` is typed now. The read was silently `undefined` and has to become `formField.control().<member>`.                                                                                        |
+| `KbqTrim.trim(...)`                                                       | Typed `(value: unknown) => unknown`. Narrow or cast the result.                                                                                                                                    |
+| `<kbq-error role="…">` / `<kbq-cleaner role="button">`                    | `kbq-error` renders `role="alert"` + `aria-atomic` and `kbq-cleaner` renders `role="button"` themselves. Drop the hand-rolled attributes.                                                          |
+| `implements KbqFormFieldControl`                                          | Expose the state as signals and drop `stateChanges`: the form field derives its state from the signals.                                                                                            |
+| `formField.control().stateChanges`                                        | Removed. Read the state signals in `computed()` / `effect()`, or turn one into a stream with `toObservable()`.                                                                                     |
+| `formField.hovered` / `.onHoverChanged(…)`, also through a `#ref`         | Removed: nothing read them; their pointer listeners ran change detection on every hover. Bind `(mouseenter)` / `(mouseleave)` on `<kbq-form-field>` yourself, or style with `:hover`.              |
+| A write to a read-only control member (`select.placeholder = …`)          | Bind it in the template, or set the value through a form control. Also reported for `+=`, `++`, `delete` and a destructuring target, and through a template ref, in an event or a two-way binding. |
+| `input.value += …` / `++` / `delete` / destructuring on a writable member | Only a plain `=` becomes `.set()`. Write the rest with `.set()` / `.update()`. Also reported for `+=`, `??=`, `++` and the rest through a template ref in an event binding.                        |
+| `password.elementType = …`, also through a `#ref`                         | `KbqInputPassword.elementType` is a read-only signal now. Call `toggleType()` to show or hide the password.                                                                                        |
+| `KbqErrorStateTracker` / `CanUpdateErrorState`                            | The tracker takes no `stateChanges` subject; `errorState` is a `Signal<boolean>`; the interface no longer declares `errorStateMatcher`.                                                            |
+| `mixinErrorState(...)` / `CanUpdateErrorStateCtor`                        | Removed. Track the error state with `KbqErrorStateTracker`.                                                                                                                                        |
+| `KbqIconErrorStateContext`                                                | Its `errorState` is a `Signal<boolean>`, and `stateChanges` was removed.                                                                                                                           |
+
+## Behaviour changes without a code fix
+
+- The form field now writes `aria-describedby` on the control, referencing every rendered hint and — while the
+  control is invalid — the error. Tests that assert on the control's attributes will see the new value.
+- `KbqInput`, `KbqInputPassword` and `KbqSelect` render `aria-invalid`; `KbqSelect` also renders `aria-required`.
+- `.kbq-form-field_no-borders` and `.kbq-form-field_in-overlay` no longer use `!important`: they override the
+  `--kbq-form-field-*` tokens instead. A stylesheet that fought the old `!important` can be simplified.
+- `KbqDatepicker` is no longer provided as a `KbqFormFieldControl`; the form field always finds the
+  `kbqDatepicker` input, which now renders its `id` for the label.
+
+## Running it manually
+
+```
+ng generate @koobiq/components:form-field-signals --project my-app
+```
+
+Pass `--fix=false` to see what would change without writing files.
+
+## Limitations
+
+Receivers are matched by explicit type annotation or an `inject()` initializer (no type inference), so inferred
+receivers (`const f = this.formField; f.hasHint`) and signal queries (`viewChild(KbqSelect)`) are left untouched. After running, **always inspect the diff**
+and act on the warnings before committing.