@koobiq/components 20.4.2 → 21.0.0

package/schematics/migrations/code-block-signals/schema.json

@@ -0,0 +1,20 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-code-block-signals",
+    "title": "Koobiq components code block signals migration",
+    "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/color-signals/README.md

@@ -0,0 +1,46 @@
+# color-signals
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21` (registered for
+`21.0.0-0`). Migrates consumers of the signal-based color of `KbqColorDirective`.
+
+## Background
+
+`KbqColorDirective` was an accessor input that added the `kbq-<color>` class to the host from its setter.
+`color` is a writable signal now, linked to the `color` input and to the default color of the component, and
+the class is rendered by a host binding. Every component built on the directive inherits it:
+
+`KbqButton`, `KbqButtonGroupRoot`, `KbqSplitButton`, `KbqCheckbox`, `KbqPseudoCheckbox`, `KbqToggleComponent`,
+`KbqRadioGroup`, `KbqRadioButton`, `KbqIcon`, `KbqIconButton`, `KbqIconItem`, `KbqFormField`, `KbqHint`,
+`KbqError`, `KbqReactivePasswordHint`, `KbqCleaner`, `KbqProgressBar`, `KbqProgressSpinner`, `KbqTag`.
+
+## What it rewrites
+
+On a receiver typed by one of these components, and through a template reference bound to one:
+
+| Before                                        | After                                        |
+| --------------------------------------------- | -------------------------------------------- |
+| `icon.color === KbqComponentColors.Error`     | `icon.color() === KbqComponentColors.Error`  |
+| `button.color = KbqComponentColors.Theme`     | `button.color.set(KbqComponentColors.Theme)` |
+| `{{ b.color }}` with `<button kbq-button #b>` | `{{ b.color() }}`                            |
+
+Template bindings such as `[color]="..."` are unchanged.
+
+## What it reports
+
+| Pattern                           | Action                                                                                                                                           |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| A subclass of a colored component | The `color` accessor can no longer be overridden. Use `setDefaultColor()` for a default, `this.color()` to read, a `linkedSignal` to derive one. |
+| `CanColor`                        | Removed. Type the member `Signal<KbqComponentColors \| string>`, or use `KbqColorDirective`.                                                     |
+
+## Behavior changes with no call site
+
+- An unset or falsy `[color]` renders the default color class of the component, `kbq-empty` where it has none,
+  instead of no color class.
+- `KbqColorDirective` is generic: `KbqButton`, `KbqButtonGroupRoot` and `KbqSplitButton` narrow their color to
+  `KbqButtonColor`.
+
+## Running it by hand
+
+```bash
+ng g @koobiq/components:color-signals --project "<your project>"
+```

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

@@ -0,0 +1,131 @@
+'use strict';
+
+/**
+ * Data for the `color-signals` migration.
+ *
+ * `KbqColorDirective.color` is a writable signal now, and so is the `color` of every component built on
+ * it. A read becomes a call and a write becomes `.set()`, on a receiver typed by one of those components.
+ */
+/** Every component and directive whose `color` comes from `KbqColorDirective`. */
+const COLORED_TYPES = [
+    'KbqColorDirective',
+    'KbqButton',
+    'KbqButtonGroupRoot',
+    'KbqSplitButton',
+    'KbqCheckbox',
+    'KbqPseudoCheckbox',
+    'KbqToggleComponent',
+    'KbqRadioGroup',
+    'KbqRadioButton',
+    'KbqIcon',
+    'KbqIconButton',
+    'KbqIconItem',
+    'KbqFormField',
+    'KbqHint',
+    'KbqError',
+    'KbqReactivePasswordHint',
+    'KbqCleaner',
+    'KbqProgressBar',
+    'KbqProgressSpinner',
+    'KbqTag'
+];
+/** Identifier shape that marks a file as naming one of the colored types. */
+const COLORED_ANCHOR = `\\b(?:${COLORED_TYPES.join('|')})\\b`;
+/** Import specifier prefix that marks a file as a Koobiq consumer. */
+const KOOBIQ_PACKAGE = '@koobiq/components/';
+const MEMBERS_BY_TYPE = Object.fromEntries(COLORED_TYPES.map((type) => [type, ['color']]));
+/** `exportAs` names a template reference can be bound to. */
+const EXPORT_AS_TO_TYPE = {
+    kbqCheckbox: 'KbqCheckbox',
+    kbqToggle: 'KbqToggleComponent',
+    kbqRadioGroup: 'KbqRadioGroup',
+    kbqRadioButton: 'KbqRadioButton',
+    kbqFormField: 'KbqFormField',
+    kbqHint: 'KbqHint',
+    kbqError: 'KbqError',
+    kbqReactivePasswordHint: 'KbqReactivePasswordHint',
+    kbqCleaner: 'KbqCleaner',
+    kbqTag: 'KbqTag'
+};
+/** Element selectors whose bare `#ref` points at one of the colored components. */
+const ELEMENT_TO_TYPE = {
+    'kbq-checkbox': 'KbqCheckbox',
+    'kbq-pseudo-checkbox': 'KbqPseudoCheckbox',
+    'kbq-toggle': 'KbqToggleComponent',
+    'kbq-radio-button': 'KbqRadioButton',
+    'kbq-split-button': 'KbqSplitButton',
+    'kbq-form-field': 'KbqFormField',
+    'kbq-hint': 'KbqHint',
+    'kbq-error': 'KbqError',
+    'kbq-reactive-password-hint': 'KbqReactivePasswordHint',
+    'kbq-cleaner': 'KbqCleaner',
+    'kbq-progress-bar': 'KbqProgressBar',
+    'kbq-progress-spinner': 'KbqProgressSpinner',
+    'kbq-tag': 'KbqTag',
+    'kbq-basic-tag': 'KbqTag'
+};
+/** Attribute selectors whose bare `#ref` points at one of the colored components. */
+const ATTRIBUTE_TO_TYPE = {
+    'kbq-button': 'KbqButton',
+    'kbq-split-button': 'KbqSplitButton',
+    'kbq-icon': 'KbqIcon',
+    'kbq-icon-button': 'KbqIconButton',
+    'kbq-icon-item': 'KbqIconItem',
+    'kbq-tag': 'KbqTag',
+    'kbq-basic-tag': 'KbqTag'
+};
+const WRITABLE_MEMBERS = new Set(['color']);
+const warnPatterns = [
+    {
+        anchor: COLORED_ANCHOR,
+        pattern: `\\bextends\\s+${COLORED_ANCHOR}`,
+        message: 'A subclass of a colored component: `color` is a writable signal inherited from KbqColorDirective, ' +
+            'and the accessor can no longer be overridden. Replace `this.color = x` in the constructor with ' +
+            '`this.setDefaultColor(x)`, read `this.color()`, and to derive the color override the `color` field ' +
+            'with a linkedSignal over `colorInput()` and `defaultColor()`. `_color` was removed and ' +
+            '`defaultColor` is a Signal.'
+    },
+    {
+        anchor: '\\bCanColor\\b',
+        pattern: '\\bCanColor\\b',
+        message: '`CanColor` was removed. Type the member `Signal<KbqComponentColors | string>`, or use `KbqColorDirective`.'
+    }
+];
+const UNPARSEABLE_TEMPLATE_MESSAGE = 'This template renders a colored component but could not be parsed, so it was left untouched. ' +
+    'Migrate reads of `color` through its template reference variables by hand.';
+const UNRESOLVED_RECEIVER_MESSAGE = 'A colored component is used here in a way this migration cannot resolve to a single receiver, so ' +
+    'any read of `color` through it was left untouched. Check these lines by hand:';
+const SUMMARY = [
+    '  `color` of every component built on KbqColorDirective is a writable signal: a read is a call ' +
+        '(icon.color()), a write is .set(). A read left un-called is silent in a template: ' +
+        '{{ icon.color }} prints the function source.',
+    '  An unset or falsy [color] renders the default color class of the component, kbq-empty where it ' +
+        'has none, instead of no color class.'
+];
+const config = {
+    label: '[color-signals]',
+    package: KOOBIQ_PACKAGE,
+    membersByType: MEMBERS_BY_TYPE,
+    exportAsToType: EXPORT_AS_TO_TYPE,
+    elementToType: ELEMENT_TO_TYPE,
+    attributeToType: ATTRIBUTE_TO_TYPE,
+    writableMembers: WRITABLE_MEMBERS,
+    warnPatterns,
+    messages: {
+        unparseableTemplate: UNPARSEABLE_TEMPLATE_MESSAGE,
+        unresolvedReceiver: UNRESOLVED_RECEIVER_MESSAGE,
+        summary: SUMMARY
+    }
+};
+
+exports.ATTRIBUTE_TO_TYPE = ATTRIBUTE_TO_TYPE;
+exports.ELEMENT_TO_TYPE = ELEMENT_TO_TYPE;
+exports.EXPORT_AS_TO_TYPE = EXPORT_AS_TO_TYPE;
+exports.KOOBIQ_PACKAGE = KOOBIQ_PACKAGE;
+exports.MEMBERS_BY_TYPE = MEMBERS_BY_TYPE;
+exports.SUMMARY = SUMMARY;
+exports.UNPARSEABLE_TEMPLATE_MESSAGE = UNPARSEABLE_TEMPLATE_MESSAGE;
+exports.UNRESOLVED_RECEIVER_MESSAGE = UNRESOLVED_RECEIVER_MESSAGE;
+exports.WRITABLE_MEMBERS = WRITABLE_MEMBERS;
+exports.config = config;
+exports.warnPatterns = warnPatterns;

package/schematics/migrations/color-signals/index.js

@@ -0,0 +1,19 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var signalMembersMigration = require('../../signal-members-migration-BoAJKutT.js');
+var migrations_colorSignals_data = require('./data.js');
+require('typescript');
+require('../../utils/ast.js');
+require('../../utils/messages.js');
+require('../../package-config-BhU2TfC8.js');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+require('../../utils/typescript.js');
+
+function colorSignals(options) {
+    return signalMembersMigration.signalMembersRule(migrations_colorSignals_data.config, options);
+}
+
+exports.default = colorSignals;

package/schematics/migrations/color-signals/schema.json

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

@@ -0,0 +1,20 @@
+# core-mixins-removal
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21` (registered for `21.0.0-0`).
+Reports the uses of the removed `mixinDisabled` and `mixinTabIndex`. It never writes to the tree.
+
+## Background
+
+Both mixins were deprecated, unused inside the library, and logged a dev-mode warning on every instance. They are
+removed from `@koobiq/components/core` with their types.
+
+| Removed                                           | Manual migration                                                                 |
+| ------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `mixinDisabled`, `CanDisable`, `CanDisableCtor`   | `readonly disabled = input(false, { transform: booleanAttribute })` on the class |
+| `mixinTabIndex`, `HasTabIndex`, `HasTabIndexCtor` | A `tabIndex` input on the class, rendered as -1 while it is disabled             |
+
+## Running it manually
+
+```bash
+ng g @koobiq/components:core-mixins-removal --project "<your project>"
+```

package/schematics/migrations/core-mixins-removal/data.js

@@ -0,0 +1,27 @@
+'use strict';
+
+/**
+ * Data for the `core-mixins-removal` migration.
+ *
+ * `mixinDisabled` and `mixinTabIndex` were deprecated, unused inside the library, and logged a dev-mode warning
+ * on every instance. They are removed from `@koobiq/components/core` with their types. Warn-only: a class built on
+ * them declares the members itself.
+ */
+const warnPatterns = [
+    {
+        pattern: '\\b(?:mixinDisabled|CanDisableCtor|CanDisable)\\b',
+        message: 'mixinDisabled, CanDisable and CanDisableCtor were removed from @koobiq/components/core. Declare ' +
+            '`readonly disabled = input(false, { transform: booleanAttribute })` on the class instead.'
+    },
+    {
+        pattern: '\\b(?:mixinTabIndex|HasTabIndexCtor|HasTabIndex)\\b',
+        message: 'mixinTabIndex, HasTabIndex and HasTabIndexCtor were removed from @koobiq/components/core. Declare a ' +
+            '`tabIndex` input on the class, and render -1 while it is disabled.'
+    }
+];
+const SUMMARY = [
+    'The deprecated mixins of @koobiq/components/core are removed: declare their members on the class.'
+];
+
+exports.SUMMARY = SUMMARY;
+exports.warnPatterns = warnPatterns;

package/schematics/migrations/core-mixins-removal/index.js

@@ -0,0 +1,17 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var warnOnlyMigration = require('../../warn-only-migration-BISJBODk.js');
+var migrations_coreMixinsRemoval_data = require('./data.js');
+require('../../utils/messages.js');
+require('../../package-config-BhU2TfC8.js');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+/** Reports the uses of the removed `mixinDisabled` and `mixinTabIndex`. Never writes. */
+function coreMixinsRemoval(options) {
+    return warnOnlyMigration.warnOnlyRule({ label: '[core-mixins-removal]', warnPatterns: migrations_coreMixinsRemoval_data.warnPatterns, summary: migrations_coreMixinsRemoval_data.SUMMARY }, options);
+}
+
+exports.default = coreMixinsRemoval;

package/schematics/migrations/core-mixins-removal/schema.json

@@ -0,0 +1,15 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-core-mixins-removal",
+    "title": "Koobiq components core mixins removal 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/css-selectors/README.md

@@ -9,11 +9,11 @@ This schematic provides migration for css-selectors of typography. It includes:
 Usage for Angular Cli:
 
 ```shell
-ng g @koobiq/components:css-selectors --fix=true --project <your project>
+ng g @koobiq/components:css-selectors --fix=true --project "<your project>"
 ```
 
 Usage for Nx:
 
 ```shell
-nx g @koobiq/components:css-selectors --fix=true --project <your project>
+nx g @koobiq/components:css-selectors --fix=true --project "<your project>"
 ```

package/schematics/migrations/css-selectors/index.js

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
 var path = require('path');
-var utils_packageConfig = require('../../utils/package-config.js');
+var utils_packageConfig = require('../../package-config-BhU2TfC8.js');
 var migrations_cssSelectors_data = require('./data.js');
 require('@angular-devkit/schematics');
 require('@schematics/angular/utility');

package/schematics/migrations/datepicker-signals/README.md

@@ -0,0 +1,24 @@
+# datepicker-signals
+
+Migration schematic invoked automatically by `ng update @koobiq/components@21` (registered for `21.0.0-0`).
+Reports subclasses of the datepicker classes and direct calls of their `ngOnChanges`. It never writes to the tree.
+
+## Background
+
+The decorator inputs of `KbqDatepicker`, `KbqDatepickerInput`, `KbqDatepickerToggleIconComponent`, `KbqCalendar`,
+`KbqCalendarHeader` and `KbqMonthView` are signal inputs named `<member>Input`, handed to the unchanged member from
+`ngOnChanges`. Reading and writing the members works as before, except the `KbqFormFieldControl` members of
+`KbqDatepickerInput` - `value`, `id`, `placeholder`, `focused`, `empty`, `required`, `disabled` and `errorState` - which
+are signals, migrated by `form-field-signals`.
+
+| Use                                         | What to do                                                            |
+| ------------------------------------------- | --------------------------------------------------------------------- |
+| A subclass with its own `ngOnChanges`       | Mark it `override` and call `super.ngOnChanges(changes)`              |
+| A subclass that redeclared an `@Input()`    | Override the `<member>Input` signal input, e.g. `minInput`            |
+| `ngOnChanges` called with a `SimpleChanges` | Key it by `<member>Input` (`minDateInput`), or bind the input instead |
+
+## Running it manually
+
+```bash
+ng g @koobiq/components:datepicker-signals --project "<your project>"
+```

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

@@ -0,0 +1,49 @@
+'use strict';
+
+/**
+ * Data for the `datepicker-signals` migration.
+ *
+ * The decorator inputs of the datepicker, its input, toggle and calendar are signal inputs named `<member>Input` now,
+ * handed to the unchanged member from `ngOnChanges`. Reads and writes of the members are unchanged; a subclass and a
+ * hand-made `SimpleChanges` are not. Warn-only. The `KbqFormFieldControl` members of the datepicker input are
+ * signals, migrated by `form-field-signals`.
+ */
+const CLASSES = [
+    'KbqDatepicker',
+    'KbqDatepickerInput',
+    'KbqDatepickerToggleIconComponent',
+    'KbqCalendar',
+    'KbqCalendarHeader',
+    'KbqMonthView'
+].join('|');
+const warnPatterns = [
+    {
+        anchor: `\\bextends\\s+(?:${CLASSES})\\b`,
+        pattern: `\\bextends\\s+(?:${CLASSES})\\b`,
+        message: 'A subclass of a Koobiq datepicker class whose inputs became signal inputs. The bound value reaches the ' +
+            'member from ngOnChanges now, which KbqDatepicker, KbqDatepickerInput, KbqCalendarHeader and KbqMonthView ' +
+            'declare for the first time: an ngOnChanges of the subclass is marked override and calls ' +
+            'super.ngOnChanges(changes). An input the subclass redeclared with @Input() is overridden through the ' +
+            '`<member>Input` signal input instead, e.g. ' +
+            "`override readonly minInput = input<Date | null | undefined>(undefined, { alias: 'min' })`."
+    },
+    {
+        anchor: `\\b(?:${CLASSES})\\b`,
+        pattern: '(?<!\\bsuper)\\.ngOnChanges\\s*\\(',
+        message: 'A direct call of ngOnChanges in a file that uses a Koobiq datepicker class. The SimpleChanges of ' +
+            'KbqDatepicker, KbqDatepickerInput, KbqDatepickerToggleIconComponent, KbqCalendar, KbqCalendarHeader and ' +
+            'KbqMonthView are keyed by the `<member>Input` names now (minDateInput, not minDate), and a bound value ' +
+            'reaches its member only through them: set the input with a template binding or ComponentRef.setInput ' +
+            'instead. This pattern also matches ngOnChanges of an unrelated class in the same file — check before ' +
+            'changing it.'
+    }
+];
+const SUMMARY = [
+    'Reads and writes of the datepicker members are unchanged, except the KbqFormFieldControl members of the',
+    'datepicker input (value, id, placeholder, focused, empty, required, disabled, errorState): they are signals,',
+    'migrated by form-field-signals.',
+    'A boolean input (hasBackdrop, disabled, opened) accepts boolean | string | null | undefined in a template now.'
+];
+
+exports.SUMMARY = SUMMARY;
+exports.warnPatterns = warnPatterns;

package/schematics/migrations/datepicker-signals/index.js

@@ -0,0 +1,17 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var warnOnlyMigration = require('../../warn-only-migration-BISJBODk.js');
+var migrations_datepickerSignals_data = require('./data.js');
+require('../../utils/messages.js');
+require('../../package-config-BhU2TfC8.js');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+/** Reports subclasses of the datepicker classes and direct calls of their `ngOnChanges`. Never writes. */
+function datepickerSignals(options) {
+    return warnOnlyMigration.warnOnlyRule({ label: '[datepicker-signals]', warnPatterns: migrations_datepickerSignals_data.warnPatterns, summary: migrations_datepickerSignals_data.SUMMARY }, options);
+}
+
+exports.default = datepickerSignals;

package/schematics/migrations/datepicker-signals/schema.json

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

@@ -36,11 +36,11 @@ Two intentional behavior changes from earlier versions of this schematic:
 Usage for Angular Cli:
 
 ```shell
-ng g @koobiq/components:deprecated-icons --fix=true --project <your project>
+ng g @koobiq/components:deprecated-icons --fix=true --project "<your project>"
 ```
 
 Usage for Nx:
 
 ```shell
-nx g @koobiq/components:deprecated-icons --fix=true --project <your project>
+nx g @koobiq/components:deprecated-icons --fix=true --project "<your project>"
 ```

package/schematics/migrations/deprecated-icons/index.js

@@ -6,7 +6,7 @@ var path = require('path');
 var utils_angularParsing = require('../../utils/angular-parsing.js');
 var utils_iconMigration = require('../../utils/icon-migration.js');
 var utils_messages = require('../../utils/messages.js');
-var utils_packageConfig = require('../../utils/package-config.js');
+var utils_packageConfig = require('../../package-config-BhU2TfC8.js');
 var migrations_deprecatedIcons_data = require('./data.js');
 require('typescript');
 require('../../utils/ast.js');

package/schematics/migrations/design-tokens-v4/README.md

@@ -0,0 +1,75 @@
+### Design Tokens v4 schematics
+
+This schematic moves a project to `@koobiq/design-tokens` 4, which `@koobiq/components` now requires.
+
+The bump is not optional — `@koobiq/components` declares `@koobiq/design-tokens@^4.1.0` as a peer
+dependency now. v4 removed the component tokens except for code-block, scrollbar and skeleton, which it
+ships as opt-in files; a project needs nothing extra for those three, since `@koobiq/components`' own
+`prebuilt-themes/theme.css` already bakes their values in.
+
+The entry is rewritten wherever the project declared it, `dependencies` or `devDependencies`, and
+added to `dependencies` when it declared it nowhere: a project can reach the tokens through the
+library's peer dependency alone, with npm having installed them and nothing in `package.json` saying
+so. An install is scheduled afterwards.
+
+The rest of the upgrade is in a project's own stylesheets, and `@koobiq/design-tokens` ships a codemod
+for it, so this schematic points at that instead of reimplementing the same rewrite:
+
+```bash
+npx koobiq-tokens-codemod src
+```
+
+It is warn-only about the two manual steps: running the codemod, and looking at the code blocks and
+scrollbars — the only two places v4 changes pixels without being asked.
+
+[Params](schema.ts)
+
+Usage for Angular Cli:
+
+```shell
+ng g @koobiq/components:design-tokens-v4 --project "<your project>"
+```
+
+Usage for Nx:
+
+```shell
+nx g @koobiq/components:design-tokens-v4 --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:design-tokens-v4 --project koobiq-docs
+```
+
+### Result
+
+#### Before
+
+```json
+{
+    "dependencies": {
+        "@koobiq/components": "^21.0.0",
+        "@koobiq/design-tokens": "^3.14.0"
+    }
+}
+```
+
+#### After
+
+```json
+{
+    "dependencies": {
+        "@koobiq/components": "^21.0.0",
+        "@koobiq/design-tokens": "^4.1.0"
+    }
+}
+```

package/schematics/migrations/design-tokens-v4/index.js

@@ -0,0 +1,59 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var tasks = require('@angular-devkit/schematics/tasks');
+var utils_messages = require('../../utils/messages.js');
+var utils_packageConfig = require('../../package-config-BhU2TfC8.js');
+require('@angular-devkit/schematics');
+require('@schematics/angular/utility');
+
+const PACKAGE = '@koobiq/design-tokens';
+/** Writes `version` over the entry the project already has, wherever it declared it. */
+function setPackageVersion(tree, pkg, version) {
+    if (!tree.exists('package.json'))
+        return false;
+    const json = JSON.parse(tree.read('package.json').toString('utf-8'));
+    const section = ['dependencies', 'devDependencies'].find((name) => json[name]?.[pkg]);
+    if (!section)
+        return false;
+    json[section][pkg] = version;
+    tree.overwrite('package.json', JSON.stringify(json, null, 2));
+    return true;
+}
+/**
+ * `@koobiq/components` requires `@koobiq/design-tokens` 4 now.
+ *
+ * The bump is not optional: v4 moved several things around. The rest of the upgrade is a
+ * consumer's own stylesheets, which `@koobiq/design-tokens` ships a codemod for; pointing at it
+ * beats a second, worse implementation of the same rewrite here. Code-block, scrollbar and
+ * skeleton need nothing from the consumer — their v4 tokens are baked into
+ * `@koobiq/components`' own `prebuilt-themes/theme.css`, which every project already loads.
+ */
+function migrate() {
+    return (tree, context) => {
+        const declared = utils_packageConfig.getPackageVersionFromPackageJson(tree, PACKAGE, true);
+        if (declared) {
+            setPackageVersion(tree, PACKAGE, "^4.1.0");
+        }
+        else {
+            // A project can reach the tokens through the library's peer dependency alone, in which
+            // case npm has installed them and nothing says so in package.json.
+            utils_packageConfig.addPackageToPackageJson(tree, PACKAGE, "^4.1.0");
+        }
+        context.addTask(new tasks.NodePackageInstallTask());
+        utils_messages.logMessage(context.logger, [
+            `\`${PACKAGE}\` was set to "${"^4.1.0"}". Two things need doing by hand:`,
+            '',
+            '1. Run `npx koobiq-tokens-codemod src` over your own styles and templates. It rewrites',
+            '   the import paths that moved (`web/new/**` → `web/css/**`), the tokens with a',
+            '   one-for-one replacement, and the removed overlay tokens (as color-mix()). For the',
+            '   old `--kbq-palette-*` scale it suggests the nearest `--kbq-plt-*`; `--fix-palette`',
+            '   and `--palette-to-color` turn the suggestion into a rewrite.',
+            '2. Look at your code blocks and scrollbars. Those are the only two places v4 changes',
+            '   pixels without being asked.'
+        ]);
+    };
+}
+
+exports.default = migrate;

package/schematics/migrations/design-tokens-v4/schema.json

@@ -0,0 +1,15 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "koobiq-components-design-tokens-v4",
+    "title": "koobiq-components design-tokens-v4 schematic",
+    "type": "object",
+    "properties": {
+        "project": {
+            "type": "string",
+            "description": "Name of the project",
+            "$default": {
+                "$source": "projectName"
+            }
+        }
+    }
+}