@koobiq/components 20.4.2 → 21.0.1

package/schematics/migrations/time-range-title-for/README.md

@@ -0,0 +1,164 @@
+# time-range-title-for
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21`
+(registered for `21.0.0-0`). Carries a time-range consumer across the two
+changes of this release: the removal of `title.for` from the locale
+configuration, and the component review that made `kbq-time-range` tell
+Angular's forms layer the truth about itself. They ship in the same version, so
+they ship as one schematic.
+
+## Background
+
+The title of `kbq-time-range` used to prepend `title.for` ("за" / "for") to the
+selected period: "за последний час". The period now stands alone ("последний
+час" / "Last hour"), and the duration templates of each locale carry whatever
+word the period needs, so the key was removed.
+
+The same release closed the gap between what the component claimed to the forms
+layer and what it did. The published form-field adapter turned from a set of
+declarations into a real implementation, and the manual `errorState` plumbing
+went away with it.
+
+| Member                                                                                | Before                | After                                       |
+| ------------------------------------------------------------------------------------- | --------------------- | ------------------------------------------- |
+| `KbqTimeRangeEditor.timepickerList`                                                   | view query            | removed                                     |
+| `KbqTimeRangeTitleAsControl.value` / `empty` / `required` / `disabled` / `errorState` | writable, never set   | read-only signals over the host and control |
+| `KbqTimeRangeTitleAsControl.id` / `placeholder` / `focused`                           | writable, `undefined` | read-only signals, `id` generated           |
+| `KbqTimeRangeTitleAsControl.controlType`                                              | writable              | readonly                                    |
+| `KbqTimeRangeTitleAsControl.stateChanges`                                             | never emitted         | removed                                     |
+| `KbqTimeRange.value` / `KbqTimeRange.disabled`                                        | absent                | read-only signals                           |
+| `KbqTimeRange.setDisabledState` / `KbqTimeRangeEditor.setDisabledState`               | absent                | implemented                                 |
+| `KbqTimeRangeTitle.disabled`                                                          | absent                | signal input                                |
+
+The one-line defect behind the review is worth naming. `mapTimeRange` assembled
+its argument as `toDate: this.form.controls.toTime.value` — the _time_ control
+feeding the _date_ slot — and `combineDateAndTime` takes the calendar date from
+its first argument. A user who picked "to: 20 September" got a range ending on
+whatever day the timepicker held. The form's own validator read `toDate`
+correctly, so validation and emission disagreed about what the range was.
+
+## Breaking change
+
+**`title.for` was removed from `KbqTimeRangeLocaleConfiguration`.** A literal
+typed against the configuration — a `kbqTimeRangeLocaleConfigurationProvider()`
+argument, for one — fails to compile on the key with an excess-property error;
+an untyped one silently loses the override.
+
+## Behaviour change
+
+**The title shows the period alone.** A custom title template receives the
+period without a prefix in `formattedDate`. A word you prefixed through
+`title.for` belongs in your `durationTemplate.title` overrides now.
+
+## What it does
+
+The schematic walks every `.ts`, `.html`, `.scss` and `.css` file in the project
+(skipping `node_modules` and `dist`). Stylesheets are visited because the markup
+change is what a descendant selector keyed on the radiogroup notices.
+
+| Auto-fix                                                              | Where |
+| --------------------------------------------------------------------- | ----- |
+| Removes `for` from the `title` section of a time-range locale literal | `.ts` |
+
+A `title` literal is treated as the time-range one when it belongs to a
+`timeRange` section, to a `kbqTimeRangeLocaleConfigurationProvider()` argument,
+or to a literal that also carries `editor` or `durationTemplate`. No type
+resolution is involved — the schematic's virtual tree has no `@koobiq` types to
+resolve against — so an unrelated `title: { for: … }` is never touched. The
+property is deleted together with exactly one adjacent separator, so the literal
+keeps its shape and nothing else in the file is reformatted.
+
+## What it does _not_ do (warn-only)
+
+| Pattern                                                   | Manual migration                                                                 |
+| --------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| A read of `title.for`                                     | Drop it — the title shows the period alone                                       |
+| A `for` key left in a `title` literal or template binding | Remove it, or ignore the report for an unrelated object                          |
+| `.timepickerList`                                         | Provide an `ErrorStateMatcher`; the editor no longer writes `errorState` by hand |
+| `.errorState = …` and friends on the adapter              | Drive the state through the bound form control; read it with a call              |
+| `.stateChanges` on the adapter                            | Read its signals in a `computed()` or an `effect()`                              |
+| `(valueCorrected)`                                        | Still emits, but only for values it actually corrected                           |
+| `.kbq-radio-group .kbq-time-range-editor__range`          | The from/to block is a sibling of the radiogroup now, not a descendant           |
+
+Warnings are checked against the **post-fix** content, so an auto-fixed literal
+does not also report as needing manual work. In dry-run mode (`--fix false`)
+they are reported against the original content instead.
+
+A pattern that names a component member is only evaluated for a file that also
+mentions `kbq-time-range`, so an unrelated `.timepickerList` of your own is not
+reported. The gate is per file rather than per receiver: where a member name is
+common (`.value`, `.disabled`), a report can point at an assignment to an
+unrelated object in a file that happens to use the control. Read the report
+before changing anything — it is a pointer, not a diagnosis. A
+`control().stateChanges` read off a form field is left to `form-field-signals`.
+
+### Notes with no call site to point at
+
+- Ranges emitted before this release ended on the wrong calendar day. Persisted
+  values may need correcting.
+- A disabled control is inert: the trigger leaves the tab order, the popover
+  refuses to open, and the host takes a `kbq-disabled` class.
+- The control becomes `touched` when the popover closes, so a `required` time
+  range shows its error message at the moment the matcher intends instead of
+  never.
+- The popover footer dropped its unnamed `role="group"`, and the from/to
+  prefixes are associated with their four inputs through `aria-labelledby`
+  instead of an inert `aria-label` on a bare `<span>`.
+
+`fix` defaults to `true`. `ng update` invokes migrations with no options at all,
+so the rule applies that default itself rather than relying on the schema.
+
+[Params](schema.ts)
+
+Usage for Angular Cli:
+
+```shell
+ng g @koobiq/components:time-range-title-for --project "<your project>"
+```
+
+Usage for Nx:
+
+```shell
+nx g @koobiq/components:time-range-title-for --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:time-range-title-for --project koobiq-docs
+```
+
+### Result
+
+#### Before
+
+```ts
+import { kbqTimeRangeLocaleConfigurationProvider } from '@koobiq/components/time-range';
+
+export const timeRangeConfiguration = kbqTimeRangeLocaleConfigurationProvider({
+    title: {
+        for: 'за',
+        placeholder: 'Период'
+    }
+});
+```
+
+#### After
+
+```ts
+import { kbqTimeRangeLocaleConfigurationProvider } from '@koobiq/components/time-range';
+
+export const timeRangeConfiguration = kbqTimeRangeLocaleConfigurationProvider({
+    title: {
+        placeholder: 'Период'
+    }
+});
+```

package/schematics/migrations/time-range-title-for/data.cjs

@@ -0,0 +1,139 @@
+'use strict';
+
+/**
+ * Data for the time-range migration.
+ *
+ * Two changes to the same component land in the same release and ship as one schematic:
+ *
+ * - The `title` of `kbq-time-range` used to prepend `title.for` ("за" / "for") to the selected period.
+ *   The period stands alone now ("последний час" / "Last hour") and the duration templates of each
+ *   locale carry whatever word it needs, so the key was removed.
+ * - The component was made to tell Angular's forms layer the truth about itself: the end of a custom
+ *   range was assembled from the *time* control instead of the *date* control, `setDisabledState` was
+ *   implemented on both `KbqTimeRange` and `KbqTimeRangeEditor`, `onTouched` is called when the popover
+ *   closes, `valueCorrected` compares the outcome instead of the shape of the input, the from/to block
+ *   moved out of the radiogroup, and `KbqTimeRangeTitleAsControl` became a real `KbqFormFieldControl`
+ *   instead of a set of declarations nothing ever assigned.
+ *
+ * Only the `for` removal has a mechanical translation. Everything else is reported: what replaces a
+ * write to a member that became a read-only signal is a binding on the host, or nothing at all, and
+ * neither can be derived from the assignment.
+ */
+/** The key removed from the `title` section of the time-range locale configuration. */
+const REMOVED_KEY = 'for';
+/** The section that held the removed key. */
+const TITLE_KEY = 'title';
+/** The time-range section of the locale data (`addLocale()`, `KBQ_LOCALE_DATA`, `[localeOverrides]`). */
+const TIME_RANGE_KEY = 'timeRange';
+/** The provider whose argument is a time-range locale configuration. */
+const PROVIDER_NAME = 'kbqTimeRangeLocaleConfigurationProvider';
+/** Siblings of `title` that only a time-range locale configuration has. */
+const SIBLING_KEYS = ['editor', 'durationTemplate'];
+/** Import specifier that marks a file as a time-range consumer. */
+const TIME_RANGE_PACKAGE = '@koobiq/components/time-range';
+/** Identifier and element shapes that mark a consumer without an import. */
+const TIME_RANGE_TYPE = '\\bKbqTimeRange\\w*\\b|\\bkbq-time-range\\b';
+/** The form-field adapter, whose members became read-only signals. */
+const TITLE_AS_CONTROL_TYPE = '\\bKbqTimeRangeTitleAsControl\\b|\\bkbq-time-range-title-as-control\\b';
+/**
+ * Cheap pre-check gating the AST parse: a `for` member of an object literal (`for:` or `'for':`). A
+ * preceding word character or dot rules out longer identifiers and property reads, which are warn-only.
+ */
+const FOR_MEMBER_PATTERN = /(?:^|[^.\w$])(['"]?)for\1\s*:/;
+/** Whether a file is a time-range consumer at all, by import or by name. */
+const referencesTimeRange = (content) => content.includes(TIME_RANGE_PACKAGE) || new RegExp(TIME_RANGE_TYPE).test(content);
+/**
+ * Warnings for `.ts`, `.html`, `.scss` and `.css` files, inline templates included. Checked against the
+ * post-fix content, so the `for` ones only fire on what the fix left behind. An anchored pattern names a
+ * member of the component, so the file has to be a consumer before a match means anything.
+ */
+const warnPatterns = [
+    {
+        pattern: '\\btitle\\.for\\b',
+        message: 'The `for` key was removed from the title section of the time-range locale configuration: the ' +
+            'title shows the period alone. Drop this read. Manual migration required.'
+    },
+    {
+        pattern: '\\btitle\\s*:\\s*\\{[^{}]*\\bfor\\s*:',
+        message: 'A `for` key in a `title` section the fix did not rewrite: a time-range locale override it could not ' +
+            'recognise, or one bound in a template. Remove the key, or ignore this if the object is not a ' +
+            'time-range locale override.'
+    },
+    {
+        anchor: TIME_RANGE_TYPE,
+        pattern: '\\.\\s*timepickerList\\b',
+        message: 'KbqTimeRangeEditor.timepickerList was removed together with the statusChanges subscription ' +
+            'that wrote errorState onto the first timepicker by hand. It only ever marked the `from` ' +
+            'field, leaving the `to` field - the one an inverted range usually needs - looking valid. ' +
+            'Both pairs take their error state from ErrorStateMatcher now; provide your own matcher ' +
+            'through the ErrorStateMatcher token if you need different timing.'
+    },
+    {
+        anchor: TITLE_AS_CONTROL_TYPE,
+        // `control().stateChanges` read off a form field is reported by `form-field-signals`.
+        pattern: '\\.\\s*(?:errorState|empty|required|disabled|focused|id|placeholder|value|controlType)\\s*=(?!=)|' +
+            '(?<!control\\(\\)\\??)\\.\\s*stateChanges\\b',
+        message: 'A write to a member of a KbqTimeRangeTitleAsControl, or a read of its stateChanges - ignore this ' +
+            'if the receiver is another object, the anchor is the file, not the expression: value, id, ' +
+            'placeholder, focused, empty, required, disabled and errorState are no longer assignable, and ' +
+            'stateChanges was removed. They were declared and never written, so a form field around the ' +
+            'control rendered once against undefined state; they are read-only signals derived from the host ' +
+            'and the bound NgControl now, and controlType is readonly. Drive them through the form control ' +
+            'instead of assigning them, read them with a call - errorState() - and read the signals in a ' +
+            'computed() or an effect() where you subscribed to stateChanges.'
+    },
+    {
+        anchor: TIME_RANGE_TYPE,
+        pattern: '\\bvalueCorrected\\b',
+        message: 'valueCorrected now fires only when the correction produced a different range. It used to ' +
+            'fire on every write of a value with no startDateTime, which the allTime preset legitimately ' +
+            'produces - a host that wrote the payload back looped on it. A handler that counted emissions ' +
+            'or relied on one arriving for allTime sees fewer of them.'
+    },
+    {
+        anchor: TIME_RANGE_TYPE,
+        pattern: '\\bkbq-time-range-editor__(?:range|container)(?![\\w-])',
+        message: 'The editor markup changed: the from/to block is a sibling of the radiogroup rather than a ' +
+            'child of it, because a role="radiogroup" must not own two datepickers and two timepickers. ' +
+            '.kbq-time-range-editor__container is the flex column that holds both, the range radio ' +
+            'carries .kbq-time-range-editor__range-option, and .kbq-time-range-editor__range holds only ' +
+            'the two date/time rows. A selector that descends from the radiogroup no longer matches.'
+    }
+];
+/** Behaviour note printed once per run — the parts no call site can point at. */
+const BEHAVIOUR_NOTE = [
+    'Time-range title behaviour changed:',
+    '  - The title no longer prepends `title.for` to the selected period: it reads "последний час" /',
+    '    "Last hour" rather than "за последний час" / "for last hour". A custom title template receives',
+    '    the period alone in `formattedDate`.',
+    '  - If you prefixed a word through `title.for`, move it into your `durationTemplate.title` overrides.',
+    '',
+    'Time-range forms contract changed:',
+    '  - The end of a custom range is built from the `to` date control instead of the `to` time control.',
+    '    Ranges emitted before this fix ended on whatever calendar day the timepicker held - today, or the',
+    '    day of the previously applied value - rather than the day the user picked. Persisted ranges may',
+    '    need correcting; the form validated the range the user saw while the component emitted a different',
+    '    one, so an inverted range could pass validation and a valid one fail it.',
+    '  - setDisabledState is implemented on KbqTimeRange and KbqTimeRangeEditor. A disabled control drops',
+    '    the trigger out of the tab order, refuses to open the popover and takes a kbq-disabled host class;',
+    '    it used to look and behave enabled while Angular silently discarded the value.',
+    '  - onTouched is called when the popover closes, so the control becomes `touched` after the first',
+    '    interaction. Every ErrorStateMatcher in the library keys error display off that, so a required',
+    '    time range that never showed its message now shows it at the right moment.',
+    '  - The popover footer no longer wraps Apply and Cancel in an unnamed role="group", and the from/to',
+    '    prefixes carry an id that the four inputs point at with aria-labelledby instead of an inert',
+    '    aria-label on a bare <span>.'
+];
+
+exports.BEHAVIOUR_NOTE = BEHAVIOUR_NOTE;
+exports.FOR_MEMBER_PATTERN = FOR_MEMBER_PATTERN;
+exports.PROVIDER_NAME = PROVIDER_NAME;
+exports.REMOVED_KEY = REMOVED_KEY;
+exports.SIBLING_KEYS = SIBLING_KEYS;
+exports.TIME_RANGE_KEY = TIME_RANGE_KEY;
+exports.TIME_RANGE_PACKAGE = TIME_RANGE_PACKAGE;
+exports.TIME_RANGE_TYPE = TIME_RANGE_TYPE;
+exports.TITLE_AS_CONTROL_TYPE = TITLE_AS_CONTROL_TYPE;
+exports.TITLE_KEY = TITLE_KEY;
+exports.referencesTimeRange = referencesTimeRange;
+exports.warnPatterns = warnPatterns;

package/schematics/migrations/time-range-title-for/index.cjs

@@ -0,0 +1,164 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var ts = require('typescript');
+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_timeRangeTitleFor_data = require('./data.cjs');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+const TS_EXT = '.ts';
+const HTML_EXT = '.html';
+const STYLE_EXTENSIONS = ['.scss', '.css'];
+const LABEL = '[time-range-title-for]';
+const createSourceFile = (fileName, content) => ts.createSourceFile(fileName, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+/** Property name of an object-literal member, for the forms a locale literal can use. */
+function propertyName(property) {
+    if (!ts.isPropertyAssignment(property))
+        return null;
+    if (!ts.isIdentifier(property.name) && !ts.isStringLiteralLike(property.name))
+        return null;
+    return property.name.text;
+}
+function calleeName(call) {
+    const callee = call.expression;
+    if (ts.isIdentifier(callee))
+        return callee.text;
+    if (ts.isPropertyAccessExpression(callee))
+        return callee.name.text;
+    return null;
+}
+/**
+ * Whether an object literal is the `title` section of a time-range locale configuration: the `title` of
+ * a `timeRange` section, of a `kbqTimeRangeLocaleConfigurationProvider()` argument, or of a literal that
+ * also carries a time-range-only sibling ({@link SIBLING_KEYS}). No type resolution is involved: the
+ * schematic's virtual tree has no `@koobiq` types to resolve against.
+ */
+function isTimeRangeTitle(node) {
+    const assignment = node.parent;
+    if (propertyName(assignment) !== migrations_timeRangeTitleFor_data.TITLE_KEY)
+        return false;
+    const section = assignment.parent;
+    if (!ts.isObjectLiteralExpression(section))
+        return false;
+    const owner = section.parent;
+    if (propertyName(owner) === migrations_timeRangeTitleFor_data.TIME_RANGE_KEY)
+        return true;
+    if (ts.isCallExpression(owner) && calleeName(owner) === migrations_timeRangeTitleFor_data.PROVIDER_NAME)
+        return true;
+    return section.properties.some((property) => migrations_timeRangeTitleFor_data.SIBLING_KEYS.includes(propertyName(property) ?? ''));
+}
+/** Spans of every removable `for` property across the file. */
+function collectSpans(sourceFile) {
+    const spans = [];
+    const visit = (node) => {
+        if (ts.isObjectLiteralExpression(node) && isTimeRangeTitle(node)) {
+            for (const property of node.properties) {
+                if (propertyName(property) === migrations_timeRangeTitleFor_data.REMOVED_KEY) {
+                    spans.push({ start: property.getStart(sourceFile), end: property.getEnd() });
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    ts.forEachChild(sourceFile, visit);
+    return spans;
+}
+/** A comma and the whitespace — at most one line break — that separates two members. */
+const SEPARATOR_BEFORE = /,[ \t]*\r?\n?[ \t]*$/;
+const SEPARATOR_AFTER = /^,[ \t]*\r?\n?[ \t]*/;
+/**
+ * Deletes the given properties right-to-left, so earlier offsets stay valid, each together with exactly
+ * one adjacent separator — the preceding one when the property has one — so the literal keeps its shape
+ * and nothing around it is reformatted. A sole property leaves an empty literal rather than a stray comma.
+ */
+function removeProperties(content, spans) {
+    let result = content;
+    for (const { start, end } of [...spans].sort((a, b) => b.start - a.start)) {
+        const before = SEPARATOR_BEFORE.exec(result.slice(0, start));
+        const after = before ? null : SEPARATOR_AFTER.exec(result.slice(end));
+        result = result.slice(0, before ? before.index : start) + result.slice(end + (after ? after[0].length : 0));
+    }
+    return result;
+}
+function logWarnings(context, filePath, content) {
+    const consumer = migrations_timeRangeTitleFor_data.referencesTimeRange(content);
+    for (const { anchor, pattern, message } of migrations_timeRangeTitleFor_data.warnPatterns) {
+        // An anchored pattern names a member of the component, so a file that never mentions the
+        // component cannot hold a call site it is about.
+        if (anchor && (!consumer || !new RegExp(anchor).test(content)))
+            continue;
+        if (new RegExp(pattern).test(content)) {
+            utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${message}`]);
+        }
+    }
+}
+function isMigratableFile(filePath) {
+    return (filePath.endsWith(TS_EXT) ||
+        filePath.endsWith(HTML_EXT) ||
+        STYLE_EXTENSIONS.some((extension) => filePath.endsWith(extension)));
+}
+/**
+ * Removes `title.for` from time-range locale configuration literals and reports everything else the
+ * component review breaks: the removed `timepickerList`, the `KbqTimeRangeTitleAsControl` members that
+ * became read-only signals, the narrowed `valueCorrected` and the editor markup that moved the
+ * from/to block out of the radiogroup. Only the `for` removal is written back — what replaces a write
+ * to a derived member is a binding on the host, or nothing at all.
+ *
+ * Stylesheets are visited as well, because the markup change is what a descendant selector keyed on the
+ * radiogroup notices. The two changes ship in one release, so they ship as one schematic.
+ */
+function timeRangeTitleFor(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_projectFiles.visitProjectFiles(rootDir, (filePath) => {
+            if (!isMigratableFile(filePath))
+                return;
+            filePaths.push(filePath);
+        });
+        let touched = 0;
+        for (const filePath of filePaths) {
+            const originalContent = tree.read(filePath)?.toString();
+            if (!originalContent)
+                continue;
+            let content = originalContent;
+            // Parsing every .ts of the project is not free, and a file with no `for` member at all
+            // cannot hold a literal to fix.
+            if (filePath.endsWith(TS_EXT) && migrations_timeRangeTitleFor_data.FOR_MEMBER_PATTERN.test(content)) {
+                content = removeProperties(content, collectSpans(createSourceFile(filePath, content)));
+            }
+            // Warn on what is left over, so an auto-fixed literal does not also produce a "manual
+            // migration required" note. In dry-run mode the fix is not written, so report against the
+            // original content.
+            logWarnings(context, filePath, fix ? content : originalContent);
+            if (content === originalContent)
+                continue;
+            touched++;
+            if (fix) {
+                tree.overwrite(filePath, content);
+            }
+            else {
+                utils_messages.logMessage(context.logger, [`${LABEL} would update ${filePath} (run with --fix to apply)`]);
+            }
+        }
+        utils_messages.logMessage(context.logger, [
+            `${LABEL} processed tree under "${root || '<workspace root>'}", ` +
+                `${fix ? 'updated' : 'would update'} ${touched} file(s).`,
+            '',
+            ...migrations_timeRangeTitleFor_data.BEHAVIOUR_NOTE
+        ]);
+    };
+}
+
+exports.default = timeRangeTitleFor;

package/schematics/migrations/time-range-title-for/schema.json

@@ -0,0 +1,20 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-time-range-title-for",
+    "title": "Koobiq components time-range title.for removal",
+    "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/timepicker-signals/README.md

@@ -0,0 +1,78 @@
+# timepicker-signals
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21` (registered for
+`21.0.0-0`). Migrates `KbqTimepicker` consumers to its signal-based inputs.
+
+## Background
+
+The `KbqFormFieldControl` members of `KbqTimepicker` - `value`, `id`, `placeholder`, `required`,
+`disabled`, `focused`, `empty` and `errorState` - are signals, migrated by `form-field-signals`: reads
+become calls, a write to `disabled` becomes `.set()`, a write to the rest is reported. This schematic
+covers the four inputs the timepicker owns.
+
+`min` and `max` parsed in their setters and reported the parsed result:
+
+```ts
+set min(value: D | null) {
+    this._min = this.getValidDateOrNull(this.dateAdapter.deserialize(value));
+    this.validatorOnChange();
+}
+```
+
+So an unparseable bound value read back as `null`. They report what was bound now; the parsed values
+stay internal and still drive the validators, re-run from `ngOnChanges` when either input changes -
+synchronously with the binding, the way the setters did.
+
+`kbqValidationTooltip` was a setter-only input that subscribed to `incorrectInput` every time it ran, so
+re-binding it stacked another subscription.
+
+## What it rewrites
+
+| Before                      | After                         |
+| --------------------------- | ----------------------------- |
+| `timepicker.format`         | `timepicker.format()`         |
+| `this.timepicker()?.format` | `this.timepicker()?.format()` |
+| `{{ tp.format }}` in a view | `{{ tp.format() }}`           |
+
+On receivers typed `KbqTimepicker` - by annotation, including an aliased import, or by `inject()`,
+`viewChild()` and `contentChild()` - and through `!`, parentheses and `as`. Each name is resolved in its
+own scope, so a nested binding that shadows the receiver, `this` inside a `function` that rebinds it, and
+a parameter that only exists in a type position are left alone. Already-migrated reads are left alone too,
+so the schematic is idempotent.
+
+The template pass follows reference variables bound through the directive's `exportAs`,
+`#tp="kbqTimepicker"`, in external and inline templates. A bare `#tp` on the native `<input>` is the
+element itself, so it is not touched.
+
+## What it does _not_ do
+
+| Pattern                                                | Manual migration                                                                      |
+| ------------------------------------------------------ | ------------------------------------------------------------------------------------- |
+| `.min` / `.max`                                        | `min()` / `max()` - a read without the call is always truthy; expect the bound value  |
+| Any write, incl. `??=`, `+=`, `++`, `delete`           | Bind `[format]`, `[min]`, `[max]` or `[kbqValidationTooltip]`; every form is reported |
+| `query.format` on an uncalled `viewChild()`            | Read it as `query()?.format()`                                                        |
+| `KbqTimepicker` named in a union, array or `QueryList` | Reported with its line; resolve the receiver by hand                                  |
+
+A `@ViewChild(KbqTimepicker)` field holds the instance itself, so its reads are rewritten with a single
+`()` and no double call is suggested.
+
+## Notes with no call site to point at
+
+- **A re-bound `kbqValidationTooltip` no longer stacks subscriptions.** After several re-binds one rejected
+  keystroke used to open every tooltip ever bound. It is an effect with a teardown now, which also gives an
+  unbound tooltip its own trigger and delay back.
+- **A locale change reformats the rendered time even when the placeholder was set by the consumer.**
+  The effect used to return early on a consumer-provided placeholder, which skipped the reformat with
+  it; the two are separate concerns now.
+- **Generated ids come from the CDK `_IdGenerator`** instead of a module-level counter. The shape is
+  unchanged for a default `APP_ID`: the CDK omits the app id when it is `ng`, and the counter still starts
+  at 0, so a real app keeps getting `kbq-timepicker-0`. Only an app that sets `APP_ID` explicitly sees it
+  in the id, right before the counter and with no separator.
+
+## Running it manually
+
+```
+ng generate @koobiq/components:timepicker-signals --project my-app
+```
+
+Pass `--fix=false` to see what it would change without writing.

package/schematics/migrations/timepicker-signals/data.cjs

@@ -0,0 +1,82 @@
+'use strict';
+
+/**
+ * Data for the `timepicker-signals` migration.
+ *
+ * The `KbqFormFieldControl` members of `KbqTimepicker` (`value`, `id`, `placeholder`, `required`, `disabled`,
+ * `focused`, `empty`, `errorState`) are signals too, but `form-field-signals` migrates them. This migration
+ * covers the four inputs the timepicker owns.
+ *
+ * - `timepicker.format` → `timepicker.format()` (value unchanged — auto-fixed)
+ * - `timepicker.min` / `max` → signals whose value changed: the getters returned the parsed date (reported)
+ * - `kbqValidationTooltip` → a read-only input driven by an effect (writes reported)
+ */
+const TARGETS = [
+    {
+        type: 'KbqTimepicker',
+        signalMembers: ['format'],
+        reportedMembers: ['min', 'max'],
+        readOnlyMembers: ['format', 'min', 'max', 'kbqValidationTooltip'],
+        exportAs: ['kbqTimepicker'],
+        elements: [],
+        writeAdvice: 'Bind `[format]`, `[min]`, `[max]` and `[kbqValidationTooltip]` in the template instead.'
+    }
+];
+/** Methods on a signal, whose presence after the member means the read is already migrated. */
+const SIGNAL_API_METHODS = new Set(['set', 'update', 'asReadonly', 'subscribe']);
+/** Import specifier that marks a file as a timepicker consumer. */
+const TIMEPICKER_PACKAGE = '@koobiq/components/timepicker';
+/** Reported for writes to members that are read-only now, whatever form the write takes. */
+const writeMessage = (type, members, advice) => `These ${type} members are read-only signals now, so these writes no longer compile: ` +
+    `${[...members].join(', ')}. That covers compound assignments (\`??=\`, \`+=\`), increments, \`delete\` ` +
+    `and destructuring targets as well as a plain \`=\`. ${advice}`;
+/** Reported for reads of `min` / `max`, which have to become calls and changed what they return. */
+const reportedMessage = (members) => `These KbqTimepicker reads were left untouched: ${[...members].join(', ')}. Add \`()\` - a read ` +
+    'without the call is the signal itself, a function, so `if (timepicker.min)` always passes - and ' +
+    'expect the value that was bound rather than the parsed date: the getters returned ' +
+    '`getValidDateOrNull(dateAdapter.deserialize(bound))`, so an unparseable bound value used to read as ' +
+    '`null` and reads as itself now.';
+/**
+ * Reported for a read through a signal query, which is a signal holding the instance: the read needs two
+ * calls rather than one. Emitted from the AST pass rather than a regex, so a `@ViewChild` field - which holds
+ * the instance itself - is never mistaken for one.
+ */
+const signalQueryMessage = (member, required) => `A signal query holds the instance behind a call of its own, so reading \`${member}\` through it needs ` +
+    `two calls: \`this.query()${required ? '' : '?'}.${member}()\`.` +
+    (required ? '' : ' The query is optional, so keep the `?.`.') +
+    ' Those reads are left untouched - migrate them by hand.';
+/** Reported when a template references the timepicker but cannot be parsed, so nothing in it was inspected. */
+const UNPARSEABLE_TEMPLATE_MESSAGE = 'This template references the timepicker but could not be parsed, so it was left untouched. Migrate ' +
+    'reads through its `#ref="kbqTimepicker"` reference variables by hand. If every template is reported ' +
+    'this way, `@angular/compiler` could not be loaded from this install.';
+/**
+ * Reported when a file names `KbqTimepicker` in a type position the receiver pass cannot scope to a single
+ * identifier - a union, an array, a `QueryList<…>`, a return type - or reads a member in a shape the access
+ * pass cannot reach.
+ */
+const UNRESOLVED_RECEIVER_MESSAGE = 'KbqTimepicker is used here in a way this migration cannot resolve to a single receiver, so any signal ' +
+    'read through it was left untouched. Check these lines by hand:';
+/** Printed once per project, after the per-file reports. */
+const SUMMARY = [
+    '  A re-bound `kbqValidationTooltip` no longer stacks subscriptions. The setter subscribed to ' +
+        '`incorrectInput` every time it ran, so after several re-binds one rejected keystroke opened every ' +
+        'tooltip ever bound. It is an effect with a teardown now, which also gives an unbound tooltip its own ' +
+        'trigger and delay back.',
+    '  A locale change reformats the rendered time even when the placeholder was set by the consumer. The ' +
+        'effect used to return early on a consumer-provided placeholder, which skipped the reformat with ' +
+        'it — the two are separate concerns now.',
+    '  Generated ids come from the CDK `_IdGenerator` instead of a module-level counter. The shape is ' +
+        'unchanged for a default `APP_ID`: the CDK omits the app id when it is `ng`, and the counter still ' +
+        'starts at 0, so a real app keeps getting `kbq-timepicker-0`. Only an app that sets `APP_ID` ' +
+        'explicitly sees it in the id, right before the counter and with no separator.'
+];
+
+exports.SIGNAL_API_METHODS = SIGNAL_API_METHODS;
+exports.SUMMARY = SUMMARY;
+exports.TARGETS = TARGETS;
+exports.TIMEPICKER_PACKAGE = TIMEPICKER_PACKAGE;
+exports.UNPARSEABLE_TEMPLATE_MESSAGE = UNPARSEABLE_TEMPLATE_MESSAGE;
+exports.UNRESOLVED_RECEIVER_MESSAGE = UNRESOLVED_RECEIVER_MESSAGE;
+exports.reportedMessage = reportedMessage;
+exports.signalQueryMessage = signalQueryMessage;
+exports.writeMessage = writeMessage;