@koobiq/components 20.4.2 → 21.0.0

package/schematics/migrations/empty-state-error-color/README.md

@@ -0,0 +1,84 @@
+# empty-state-error-color
+
+Migration schematic invoked automatically by `ng update @koobiq/components@20`
+(registered for `21.0.0-0`). Reports the members the empty-state review removed or turned into
+signals, and the four theme custom properties it renamed. It never writes to the tree.
+
+## Background
+
+`errorColor` used to reach the illustration imperatively. `KbqEmptyState.ngAfterContentInit()` read
+the input once and called `KbqEmptyStateIcon.setErrorColor()`, which assigned `color = 'error'` on the
+injected `kbq-icon-item`. Three things followed from that one call:
+
+- it never came back — flipping `[errorColor]` to `false` left a red icon above black text;
+- it never arrived late — flipping to `true` after init did nothing;
+- it only happened for one of the two supported markup shapes, because the directive resolved the
+  icon through `inject(KbqIconItem)`, which sees an icon on its own host element and not one wrapped
+  by it.
+
+The tint is driven by the input now, in both shapes, so `setErrorColor()` has no caller and is gone.
+
+| Member                               | Before                   | After                                 |
+| ------------------------------------ | ------------------------ | ------------------------------------- |
+| `KbqEmptyStateIcon.setErrorColor()`  | public, called at init   | removed                               |
+| `KbqEmptyState.icon`                 | public `@ContentChild`   | `protected` `contentChild()`          |
+| `KbqEmptyState.ngAfterContentInit()` | public lifecycle hook    | removed                               |
+| `KbqEmptyState.size`                 | `@Input()`, writable     | `input()`, read as `size()`           |
+| `--kbq-empty-state-title`            | theme token              | `--kbq-empty-state-title-color`       |
+| `--kbq-empty-state-color`            | theme token (text color) | `--kbq-empty-state-text-color`        |
+| `--kbq-empty-state-error-title`      | theme token              | `--kbq-empty-state-error-title-color` |
+| `--kbq-empty-state-error-color`      | theme token (text color) | `--kbq-empty-state-error-text-color`  |
+
+The old names are removed, not deprecated. Nothing chains to them, so an override of one is ignored
+and a `var()` read of one resolves to nothing — in both cases without an error.
+
+## `size` and the file-upload subclass
+
+`size` was the last decorator left on the component. It stayed one because
+`KbqFileUploadEmptyState` — a public class in `@koobiq/components/file-upload` — extends
+`KbqEmptyState` and assigned `this.size = 'big'` straight after `super()`, which an `input()` cannot
+take.
+
+That subclass redeclares the input with its own default instead:
+
+```ts
+override readonly size = input<KbqDefaultSizes>('big');
+```
+
+So `<kbq-file-upload-empty-state>` still renders at `big` without a binding, and a `[size]` binding
+still overrides it. Nothing changes for anyone rendering that component.
+
+## What it does _not_ do
+
+Nothing is rewritten. A call to a removed method has no replacement expression, renaming a token
+override is a theming decision, and `size` is far too common a property name to rewrite blind —
+`file.size`, `blob.size` and `map.size` all appear in files that also render an empty state.
+
+The `size` report is therefore matched on the receiver, not the member: only a read like
+`emptyState.size` or `myEmptyState?.size` is flagged. A read through a variable named something else
+is not reported at all, and the summary says so rather than letting you assume it was covered.
+
+| Pattern                                           | Manual migration                                         |
+| ------------------------------------------------- | -------------------------------------------------------- |
+| `.setErrorColor()`                                | Bind `[errorColor]` on `<kbq-empty-state>` and delete it |
+| `--kbq-empty-state-title` / `-color` / `-error-*` | Rename to the `-color`-suffixed names                    |
+| `emptyState.size`                                 | `emptyState.size()`                                      |
+| `emptyState.size = 'big'`                         | Bind `[size]="'big'"` — an `input()` has no setter       |
+
+## Notes with no call site to point at
+
+- The title is rendered with heading typography — `subheading` at `size="normal"`, `headline` at
+  `size="big"` — but every usage in the library wrote it as a `div`. Write a real heading of the level
+  the page calls for, `<h2 kbq-empty-state-title>`; the component zeroes the user-agent margin, so
+  nothing moves.
+- An empty state inserted into a page that has already been read needs `role="status"` on
+  `<kbq-empty-state>`, or `role="alert"` for the error variant. The component adds no `role` of its own.
+- `empty-state.scss` loads its own token layer instead of relying on a second `styleUrls` entry, so
+  anything reusing the stylesheet across a package boundary now gets the custom properties together
+  with the rules that read them.
+
+## Running it manually
+
+```
+ng generate @koobiq/components:empty-state-error-color --project my-app
+```

package/schematics/migrations/empty-state-error-color/data.js

@@ -0,0 +1,85 @@
+'use strict';
+
+/**
+ * Data for the `empty-state-error-color` migration.
+ *
+ * The empty-state review closed the one imperative hook the component had and renamed its four theme
+ * custom properties:
+ *
+ * - `KbqEmptyStateIcon.setErrorColor()` — removed. It existed so that `KbqEmptyState` could tint the
+ *   icon once from `ngAfterContentInit`, which made the tint irreversible, late for anything toggled
+ *   after init, and silently absent whenever the icon was wrapped rather than carrying the slot
+ *   attribute. The illustration follows `[errorColor]` on its own now.
+ * - `--kbq-empty-state-title`, `--kbq-empty-state-color`, `--kbq-empty-state-error-title`,
+ *   `--kbq-empty-state-error-color` — renamed to `-title-color`, `-text-color`, `-error-title-color`
+ *   and `-error-text-color`. The old names are removed outright — nothing chains to them, so an
+ *   override or a `var()` read of one stops having any effect.
+ * - `KbqEmptyState.size` — `@Input()` to `input()`. It was the last decorator on the component, held
+ *   back because `KbqFileUploadEmptyState` assigned it from its constructor; that subclass redeclares
+ *   the input with its own `big` default now, so nothing writes to it.
+ *
+ * Warn-only. A call to a removed method has no replacement expression, a token override is a theming
+ * decision the schematic cannot make, and `size` is too common a property name to rewrite blind.
+ */
+/** Import specifier that marks a file as an empty-state consumer. */
+const EMPTY_STATE_PACKAGE = '@koobiq/components/empty-state';
+/**
+ * Identifier, element and custom-property shapes that mark a consumer without an import.
+ *
+ * Every `warnPatterns` entry below only applies to a file that also matches this, so it is checked
+ * once, ahead of the per-pattern checks, rather than repeated as a per-pattern anchor.
+ */
+const EMPTY_STATE_TYPE = '\\bKbqEmptyState\\w*\\b|\\bkbq-empty-state\\b';
+const warnPatterns = [
+    {
+        pattern: '\\bsetErrorColor\\b',
+        message: 'KbqEmptyStateIcon.setErrorColor() was removed. It tinted the icon once from ' +
+            'ngAfterContentInit, so the tint never went away, never arrived for an [errorColor] flipped ' +
+            'after init, and never happened at all when the icon was wrapped by the slot instead of ' +
+            'carrying it. The illustration follows [errorColor] on <kbq-empty-state> now, in both markup ' +
+            'shapes — bind the input and delete the call.'
+    },
+    {
+        // Matches either shape the old name can appear in: a declaration (an override) or a
+        // `var(--kbq-empty-state-...)` read.
+        pattern: '--kbq-empty-state-(?:title|color|error-title|error-color)\\s*:' +
+            '|\\bvar\\(\\s*--kbq-empty-state-(?:title|color|error-title|error-color)\\s*[,)]',
+        message: 'The four empty-state theme tokens were renamed: --kbq-empty-state-title becomes ' +
+            '--kbq-empty-state-title-color, --kbq-empty-state-color becomes --kbq-empty-state-text-color ' +
+            '(it is the text color, not the component color), --kbq-empty-state-error-title becomes ' +
+            '--kbq-empty-state-error-title-color and --kbq-empty-state-error-color becomes ' +
+            '--kbq-empty-state-error-text-color. The old names are gone, not deprecated: an override of one ' +
+            'is ignored and a var() read of one resolves to nothing, in both cases silently. Rename it.'
+    },
+    {
+        // `size` is far too common a property name to match bare, or to rewrite: `file.size`,
+        // `blob.size`, `map.size` and `event.size` all live in files that also render an empty
+        // state. Matched only on a receiver that names one, which covers the @ViewChild, viewChild()
+        // and `#ref="kbqEmptyState"` shapes; `(?!\s*\()` keeps an already-migrated call quiet. Reads
+        // through a differently named variable are left to the summary.
+        pattern: '\\b\\w*[eE]mptyState\\w*\\s*(?:\\?\\.|\\.)\\s*size\\b(?!\\s*\\()',
+        message: 'KbqEmptyState.size is an input() now, so reading it is a call: emptyState.size(). Writing ' +
+            'to it is gone — bind [size] instead. KbqFileUploadEmptyState redeclares the same input to ' +
+            'keep defaulting to "big", so its rendered size is unchanged. A template binding [size]="..." ' +
+            'needs no edit.'
+    }
+];
+/** Printed once per project, after the per-file reports. */
+const SUMMARY = [
+    '  The title is rendered with heading typography but was written as a <div> in every usage in the ' +
+        'library. Write it as a real heading of the level the page calls for — <h2 kbq-empty-state-title> ' +
+        '— the component zeroes the browser margin, so nothing moves.',
+    '  An empty state inserted into a page that has already been read needs role="status" (role="alert" ' +
+        'for the error variant) on <kbq-empty-state>; the component adds no role of its own.',
+    '  empty-state.scss loads its own token layer now instead of relying on a second styleUrls entry, ' +
+        'so anything reusing the stylesheet gets the custom properties with the rules. A workaround that ' +
+        're-declared --kbq-empty-state-size-* tokens to compensate can be dropped.',
+    '  KbqEmptyState.size is an input(). Reads through a variable this schematic cannot recognise as an ' +
+        'empty state are not reported, because "size" is too common a property to match on its own — ' +
+        'check any code that reads .size off a KbqEmptyState or a subclass of it.'
+];
+
+exports.EMPTY_STATE_PACKAGE = EMPTY_STATE_PACKAGE;
+exports.EMPTY_STATE_TYPE = EMPTY_STATE_TYPE;
+exports.SUMMARY = SUMMARY;
+exports.warnPatterns = warnPatterns;

package/schematics/migrations/empty-state-error-color/index.js

@@ -0,0 +1,71 @@
+'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_emptyStateErrorColor_data = require('./data.js');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+const LABEL = '[empty-state-error-color]';
+const EXTENSIONS = ['.ts', '.html', '.scss', '.css'];
+const anchorRegExp = new RegExp(migrations_emptyStateErrorColor_data.EMPTY_STATE_TYPE);
+const compiledWarnPatterns = migrations_emptyStateErrorColor_data.warnPatterns.map(({ pattern, message }) => ({ regExp: new RegExp(pattern), message }));
+/**
+ * Decodes a file's content, but only once it is known to be an empty-state consumer — importing the
+ * package, naming the component, or theming it. Every `warnPatterns` entry only applies to a file
+ * that passes this check, so it is the single gate for all of them.
+ *
+ * Checks the raw buffer for the import specifier first, since that is the common case for `.ts` and
+ * `.html` consumers and needs no decoding to test; only the fallback name/selector check requires the
+ * decoded string, and once decoded it is reused rather than decoded again for the patterns below.
+ */
+function readIfEmptyStateConsumer(buffer) {
+    if (buffer.includes(migrations_emptyStateErrorColor_data.EMPTY_STATE_PACKAGE))
+        return buffer.toString();
+    const content = buffer.toString();
+    return anchorRegExp.test(content) ? content : undefined;
+}
+/**
+ * Reports the removed `KbqEmptyStateIcon.setErrorColor()` and the four renamed theme custom
+ * properties. Never writes: a removed method has no replacement expression, and the old token names
+ * are still read as fallbacks, so renaming them is a decision rather than a fix.
+ *
+ * Stylesheets are visited as well as `.ts` and `.html`, because the tokens are a theming contract
+ * consumers override from their own SCSS.
+ */
+function emptyStateErrorColor(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.length ? readIfEmptyStateConsumer(entry.content) : undefined;
+            if (!content)
+                return;
+            consumers++;
+            for (const { regExp, message } of compiledWarnPatterns) {
+                if (!regExp.test(content))
+                    continue;
+                reported++;
+                utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${message}`]);
+            }
+        });
+        // Nothing here renders an empty state, so the summary would only be noise.
+        if (consumers === 0)
+            return;
+        utils_messages.logMessage(context.logger, [
+            `${LABEL} processed kbq-empty-state under "${root || '<workspace root>'}", ` +
+                `${consumers} file(s) reference the component, ${reported} call site(s) reported.`,
+            ...migrations_emptyStateErrorColor_data.SUMMARY
+        ]);
+    };
+}
+
+exports.default = emptyStateErrorColor;

package/schematics/migrations/empty-state-error-color/schema.json

@@ -0,0 +1,15 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-empty-state-error-color",
+    "title": "Koobiq components empty-state 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/empty-state-size-attr/README.md

@@ -10,13 +10,13 @@ This schematic provides migration for `KbqEmptyState` new `size` attribute. It i
 Usage for Angular Cli:
 
 ```shell
-ng g @koobiq/components:empty-state-size-attr --project <your project>
+ng g @koobiq/components:empty-state-size-attr --project "<your project>"
 ```
 
 Usage for Nx:
 
 ```shell
-nx g @koobiq/components:empty-state-size-attr --project <your project>
+nx g @koobiq/components:empty-state-size-attr --project "<your project>"
 ```
 
 ### Run locally

package/schematics/migrations/empty-state-size-attr/index.js

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
 var utils_angularParsing = require('../../utils/angular-parsing.js');
-var utils_packageConfig = require('../../utils/package-config.js');
+var utils_packageConfig = require('../../package-config-BhU2TfC8.js');
 var utils_typescript = require('../../utils/typescript.js');
 require('typescript');
 require('../../utils/ast.js');

package/schematics/migrations/file-upload-cva-and-primitives/README.md

@@ -0,0 +1,70 @@
+# file-upload-cva-and-primitives
+
+Migration schematic invoked automatically by `ng update @koobiq/components@20`
+(registered for `21.0.0-0`). Reports the file-upload behavior the component review changed. It never
+writes to the tree.
+
+## Background
+
+The review repaired the two contracts the component is judged on — the form contract and the file-list
+primitive.
+
+| Member                              | Before                                      | After                                            |
+| ----------------------------------- | ------------------------------------------- | ------------------------------------------------ |
+| `writeValue()`                      | wrote through the `file` / `files` setter   | writes the list directly                         |
+| `KbqFileList.remove(item)`          | returned the kept items, removed every copy | returns the removed item, removes the first copy |
+| `KbqFileList.removeAt(index)`       | rewrote the list and emitted for any index  | ignores an index outside the list                |
+| `hasFocus`                          | public, always `false`                      | removed                                          |
+| single uploader's hidden input      | `multiple`                                  | single-selection                                 |
+| `[multiple]` on the single uploader | forwarded to that input                     | not an input at all                              |
+| `[file]` / `[files]` setter         | wrote the list and notified the form        | writes the list only                             |
+| `KbqInputFileMultipleLabel`         | exported interface                          | removed                                          |
+
+`writeValue()` deserves a note. It assigned through the `file`/`files` setters, and those setters call
+`cvaOnChange` — the view→model half of the `ControlValueAccessor`. Angular's model→view callback
+therefore re-entered the view→model pipeline: every `setValue`/`patchValue` marked the control
+**dirty** and emitted `valueChanges` twice, and because `FormControl.reset()` calls `markAsPristine()`
+_before_ `setValue()`, a reset uploader came back dirty. The same method also emitted the public
+`(fileChange)`/`(filesChange)` output, so a background `patchValue` was indistinguishable from a user
+picking a file.
+
+## What it does _not_ do
+
+Nothing is rewritten. `remove()` keeps its signature while returning the opposite array, and whether an
+output handler was meant to run for a programmatic write is a decision, not a rename.
+
+| Pattern                             | Manual migration                                                               |
+| ----------------------------------- | ------------------------------------------------------------------------------ |
+| `.remove(item)`                     | The return value is the removed item now; use `removeAt(index)` for a position |
+| `.hasFocus`                         | Track focus with `cdkMonitorSubtreeFocus` or `(focusin)`/`(focusout)`          |
+| `(fileChange)` / `(filesChange)`    | Subscribe to the control if the handler was meant to see programmatic writes   |
+| `KbqInputFileMultipleLabel`         | Use `KbqMultipleFileUploadLocaleConfiguration` from `@koobiq/components/core`  |
+| `[file]` / `[files]` beside a form  | Drop the binding — the form owns the value; without a form nothing changes     |
+| `<kbq-single-file-upload multiple>` | Drop the attribute, or switch to `<kbq-multiple-file-upload>`                  |
+
+## Notes with no call site to point at
+
+- A programmatic value no longer marks the control dirty, and `valueChanges` fires once instead of
+  twice. Error display keyed off `dirty` shows fewer errors than before, not more.
+- The control is marked touched when focus leaves the uploader, so the default `ErrorStateMatcher`
+  shows a `required` error to a user who tabbed through without attaching anything.
+- The single uploader renders a single-selection file input, so the system dialog no longer offers a
+  multi-selection the component would throw away. Files a drop hands over past the first are reported
+  through the new `(rejected)` output, as are duplicates the multiple uploader skips.
+- `accept` is documented as what it is: the native attribute, which only filters the system dialog.
+  Rejection still needs a validator — `FileValidators.isCorrectExtension` takes the same array.
+- The locale gains a `fileUpload.a11y` section holding the live-region announcements. A hand-written
+  `KbqLocaleData` registered through `KBQ_LOCALE_DATA` has to add those three keys.
+- 22 `--kbq-file-upload-*` custom properties that no rule read were removed, including both
+  `*-states-focused-focus-outline-color` tokens. Setting one never had an effect.
+- `removeAt()` ignores an index outside the list. It used to rewrite `list` with a fresh array for a
+  `splice` that removed nothing — waking every `list()` consumer for a no-op — and emit `itemRemoved`
+  carrying `undefined` in a tuple typed `[T, number]`.
+- A drop that hands over no files no longer reaches the list. An empty directory unwraps to zero
+  files, and under `addStrategy="replace"` that used to clear a selection the user had already built.
+
+## Running it manually
+
+```
+ng generate @koobiq/components:file-upload-cva-and-primitives --project my-app
+```

package/schematics/migrations/file-upload-cva-and-primitives/data.js

@@ -0,0 +1,97 @@
+'use strict';
+
+/**
+ * Data for the `file-upload-cva-and-primitives` migration.
+ *
+ * The file-upload review repaired the two contracts the component is judged on — the form contract
+ * and the file-list primitive — and both changes are behavioral, so nothing here is rewritten:
+ *
+ * - `writeValue()` no longer routes through the `file`/`files` setters, so a programmatic value stops
+ *   marking the control dirty, stops emitting `valueChanges` twice, and no longer fires
+ *   `(fileChange)`/`(filesChange)`.
+ * - `KbqFileList.remove()` now does what its JSDoc always said: removes the first occurrence, returns
+ *   the removed item, and emits `itemRemoved`. It used to return the items it kept and remove every
+ *   occurrence silently.
+ * - The single uploader's hidden input is no longer `multiple`, so the system dialog cannot select
+ *   files the component would discard; whatever a drop hands over past the first file is reported
+ *   through the new `(rejected)` output.
+ * - `KbqMultipleFileUploadComponent.hasFocus` is removed — it was public and read by nothing.
+ * - `KbqInputFileMultipleLabel` is removed. Its replacement lives in another entry point, so the
+ *   rename cannot be applied without also moving the import.
+ *
+ * Warn-only: which value a call site wanted from `remove()` and whether a consumer relied on the
+ * output firing for a programmatic write are decisions, not renames.
+ */
+/** Import specifier that marks a file as a file-upload consumer. */
+const FILE_UPLOAD_PACKAGE = '@koobiq/components/file-upload';
+/** Identifier and element shapes that mark a consumer without an import. */
+const FILE_UPLOAD_TYPE = '\\bKbq\\w*File(?:Upload|List|Loader|Multiple)\\w*\\b|\\bkbq-(?:single-|multiple-)?file-upload\\b';
+const warnPatterns = [
+    {
+        pattern: '\\.\\s*remove\\s*\\(',
+        message: 'KbqFileList.remove() follows its documented contract now: it removes the first occurrence, ' +
+            'returns the removed item and emits itemRemoved. It used to return the items it kept, drop ' +
+            'every occurrence and emit nothing, so a call site reading the return value gets the ' +
+            'opposite array from before. Use removeAt(index) when you mean a position.'
+    },
+    {
+        pattern: '\\.\\s*hasFocus\\b',
+        message: 'KbqMultipleFileUploadComponent.hasFocus was removed. It was public, always false and read ' +
+            'by nothing; track focus with cdkMonitorSubtreeFocus or a (focusin)/(focusout) pair.'
+    },
+    {
+        pattern: '\\((?:fileChange|filesChange)\\)|\\.\\s*(?:fileChange|filesChange)\\s*\\.\\s*subscribe',
+        message: 'writeValue() no longer emits (fileChange)/(filesChange). The outputs report a user picking ' +
+            'or removing a file; a setValue/patchValue/reset from the host no longer looks like one. A ' +
+            'handler that started an upload from there also ran on every programmatic write — subscribe ' +
+            'to the control instead if that was the intent.'
+    },
+    {
+        pattern: '\\bKbqInputFileMultipleLabel\\b',
+        message: 'KbqInputFileMultipleLabel was removed. Use KbqMultipleFileUploadLocaleConfiguration from ' +
+            '@koobiq/components/core — note the entry point, the import moves with the rename. The index ' +
+            'signature only widened the config so an unknown key could be passed along with the labels, ' +
+            'and nothing reads one.'
+    },
+    {
+        pattern: '\\[\\s*(?:file|files)\\s*\\]|\\[\\(\\s*(?:file|files)\\s*\\)\\]',
+        message: 'Writing [file]/[files] no longer notifies the form. The setter is the model→view half, like ' +
+            'writeValue(): it fills the list and stops there. This only matters when the same component ' +
+            'also carries formControl, formControlName or ngModel — two sources of truth for one value; ' +
+            'drop the binding and let the form own it. Without a form the binding is unchanged, and ' +
+            '[(file)]/[(files)] still report what the user does.'
+    },
+    {
+        pattern: '<\\s*kbq-single-file-upload\\b[^>]*\\bmultiple\\b',
+        message: 'kbq-single-file-upload no longer forwards `multiple` to its hidden input. It used to put the ' +
+            'system dialog back into multi-select on a component that keeps one file and discarded the ' +
+            'rest; remove the attribute, or use kbq-multiple-file-upload if several files were intended.'
+    }
+];
+/** Printed once per project, after the per-file reports. */
+const SUMMARY = [
+    '  A programmatic value no longer marks the control dirty. `control.setValue(...)` emits valueChanges ' +
+        'once instead of twice, and a control reset right after `markAsPristine()` stays pristine — error ' +
+        'display keyed off `dirty` shows fewer errors than before, not more.',
+    '  The control is marked touched when focus leaves the uploader, so the default ErrorStateMatcher ' +
+        'shows a `required` error to a user who tabbed through without attaching anything.',
+    '  The single uploader renders a single-selection file input. The system dialog no longer offers a ' +
+        'multi-selection the component would throw away; files a drop hands over past the first are ' +
+        'reported through the new (rejected) output, as are duplicates skipped by the multiple uploader.',
+    '  `accept` is documented as what it is — the native attribute, which only filters the system dialog. ' +
+        'Rejection still needs a validator; FileValidators.isCorrectExtension takes the same array.',
+    '  The locale gains a `fileUpload.a11y` section with the live-region announcements. A hand-written ' +
+        'KbqLocaleData registered through KBQ_LOCALE_DATA has to add those three keys.',
+    '  22 --kbq-file-upload-* custom properties that no rule read were removed, including both ' +
+        '*-states-focused-focus-outline-color tokens. Setting one never had an effect.',
+    '  KbqFileList.removeAt(index) ignores an index outside the list. It used to rewrite the list with a ' +
+        'fresh array anyway — waking every list() consumer for a no-op — and emit itemRemoved carrying ' +
+        'undefined in a tuple typed [T, number].',
+    '  A drop that hands over no files (an empty directory unwraps to zero) no longer reaches the list. ' +
+        'Under addStrategy="replace" it used to clear a selection the user had already built.'
+];
+
+exports.FILE_UPLOAD_PACKAGE = FILE_UPLOAD_PACKAGE;
+exports.FILE_UPLOAD_TYPE = FILE_UPLOAD_TYPE;
+exports.SUMMARY = SUMMARY;
+exports.warnPatterns = warnPatterns;

package/schematics/migrations/file-upload-cva-and-primitives/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_fileUploadCvaAndPrimitives_data = require('./data.js');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+const LABEL = '[file-upload-cva-and-primitives]';
+const EXTENSIONS = ['.ts', '.html'];
+/** A file is a file-upload consumer if it imports the package, names a type, or renders an uploader. */
+function referencesFileUpload(content) {
+    return content.includes(migrations_fileUploadCvaAndPrimitives_data.FILE_UPLOAD_PACKAGE) || new RegExp(migrations_fileUploadCvaAndPrimitives_data.FILE_UPLOAD_TYPE).test(content);
+}
+/**
+ * Reports the file-upload behavior the review changed. Never writes: `remove()` keeps its signature
+ * while returning the opposite array, and whether an output handler wanted to run for a programmatic
+ * write is a decision rather than a rename.
+ *
+ * `.html` is visited as well as `.ts`, because `(fileChange)`/`(filesChange)` are template bindings.
+ */
+function fileUploadCvaAndPrimitives(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 || !referencesFileUpload(content))
+                return;
+            consumers++;
+            // `referencesFileUpload` above is the only scoping rule. A per-pattern anchor used to
+            // re-test the type regex here, which silently skipped a file that reaches the component
+            // through the import path alone — `KbqDropzoneData` names no type the regex matches.
+            for (const { pattern, message } of migrations_fileUploadCvaAndPrimitives_data.warnPatterns) {
+                if (!new RegExp(pattern).test(content))
+                    continue;
+                reported++;
+                utils_messages.logMessage(context.logger, [`${LABEL} ${filePath}`, `  ${message}`]);
+            }
+        });
+        // Nothing here renders a file-upload, so the summary would only be noise.
+        if (consumers === 0)
+            return;
+        utils_messages.logMessage(context.logger, [
+            `${LABEL} processed kbq-file-upload under "${root || '<workspace root>'}", ` +
+                `${consumers} file(s) reference the component, ${reported} call site(s) reported.`,
+            ...migrations_fileUploadCvaAndPrimitives_data.SUMMARY
+        ]);
+    };
+}
+
+exports.default = fileUploadCvaAndPrimitives;

package/schematics/migrations/file-upload-cva-and-primitives/schema.json

@@ -0,0 +1,15 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-file-upload-cva-and-primitives",
+    "title": "Koobiq components file-upload 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/file-upload-deprecated-outputs/README.md

@@ -0,0 +1,90 @@
+# file-upload-deprecated-outputs
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21`
+(registered for `21.0.0-0`). Renames the deprecated file-upload outputs to
+their replacements.
+
+## Background
+
+`KbqMultipleFileUploadComponent.fileQueueChanged` and
+`KbqSingleFileUploadComponent.fileQueueChange` (#DS-5229) were deprecated in
+favor of `filesChange` / `fileChange`. Removal was originally planned for the
+next major release, but was moved up to 21.0.0. Both outputs fired at exactly
+the same call sites, with the same payload, as their replacement — this is a
+pure rename, not a behaviour change.
+
+## What it does
+
+The schematic walks every `.ts` and `.html` file in the project (skipping
+`node_modules`, `dist`, `coverage`, `.angular` and `out-tsc`) and renames the
+identifier wherever it appears:
+
+| Before             | After         |
+| ------------------ | ------------- |
+| `fileQueueChanged` | `filesChange` |
+| `fileQueueChange`  | `fileChange`  |
+
+Both names are unambiguous — they don't collide with any other Angular or
+TypeScript identifier — so the rename applies everywhere the text occurs:
+
+- A template binding, in an external `.html` file or an inline
+  `@Component({ template })` string: `(fileQueueChanged)="…"` →
+  `(filesChange)="…"`.
+- Programmatic TypeScript access: `comp.fileQueueChanged.subscribe(...)` →
+  `comp.filesChange.subscribe(...)`.
+
+The rewrite is idempotent — running it twice does not change an
+already-migrated file.
+
+## Running it
+
+```shell
+ng g @koobiq/components:file-upload-deprecated-outputs --project "<your project>"
+```
+
+Pass `--fix=false` to see what would change without writing files. `fix`
+defaults to `true`.
+
+[Params](schema.ts)
+
+### 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:file-upload-deprecated-outputs --project koobiq-docs
+```
+
+### Result
+
+#### Before
+
+```ts
+@Component({
+    selector: 'my-uploads',
+    template: `
+        <kbq-file-upload (fileQueueChange)="onFileChange($event)"></kbq-file-upload>
+        <kbq-file-upload multiple (fileQueueChanged)="onFilesChange($event)"></kbq-file-upload>
+    `
+})
+export class MyUploads {}
+```
+
+#### After
+
+```ts
+@Component({
+    selector: 'my-uploads',
+    template: `
+        <kbq-file-upload (fileChange)="onFileChange($event)"></kbq-file-upload>
+        <kbq-file-upload multiple (filesChange)="onFilesChange($event)"></kbq-file-upload>
+    `
+})
+export class MyUploads {}
+```

package/schematics/migrations/file-upload-deprecated-outputs/data.js

@@ -0,0 +1,20 @@
+'use strict';
+
+/**
+ * Replacement data for the removal of the deprecated file-upload outputs
+ *
+ * `KbqMultipleFileUploadComponent.fileQueueChanged` and
+ * `KbqSingleFileUploadComponent.fileQueueChange` were deprecated in favor of
+ * `filesChange` / `fileChange` and are removed in this release. Both names
+ * are unambiguous — they don't collide with any other Angular or TypeScript
+ * identifier — so a plain `\b…\b` word-boundary rename is safe everywhere
+ * the identifier can appear: an `(fileQueueChanged)="…"` template binding
+ * (external `.html` or inline `template:` string), or a programmatic
+ * `.fileQueueChanged` property access / `.subscribe(...)` call in `.ts`.
+ */
+const replacements = [
+    { from: '\\bfileQueueChanged\\b', to: 'filesChange' },
+    { from: '\\bfileQueueChange\\b', to: 'fileChange' }
+];
+
+exports.replacements = replacements;