fix(components)!: unresolvable peerDependencies break npm install (#DS-4889)

.github/workflows/build.yml

@@ -9,8 +9,14 @@ permissions:
 jobs:
   build:
     runs-on: ubuntu-latest
+    # `check-npm-resolution` talks to the npm registry, so this job can stall on an outage instead
+    # of failing. Bound it rather than holding a runner for the six-hour default.
+    timeout-minutes: 60
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - uses: ./.github/workflows/actions/setup-node
       - uses: ./.github/workflows/actions/build-packages
+      # Yarn's node-modules linker tolerates peer conflicts that npm rejects, so the built packages
+      # have to be resolved with npm to catch an ERESOLVE before it reaches consumers.
+      - run: yarn run check-npm-resolution
       - uses: ./.github/workflows/actions/build-docs

.github/workflows/linters.yml

@@ -20,3 +20,4 @@ jobs:
           yarn run prettier
           yarn run stylelint --max-warnings=0
           yarn run eslint --max-warnings=0
+          yarn run check-peer-deps

.github/workflows/publish.yml

@@ -16,6 +16,9 @@ jobs:
   publish:
     name: Publish
     runs-on: ubuntu-latest
+    # `check-npm-resolution` gates this job on the npm registry answering; a stall must not hold the
+    # release runner for the six-hour default.
+    timeout-minutes: 60
     if: ${{ github.repository_owner == 'koobiq' }}
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -26,6 +29,9 @@ jobs:
       - name: Build packages
         uses: ./.github/workflows/actions/build-packages
 
+      - name: Check npm can resolve the packages
+        run: yarn run check-npm-resolution
+
       - name: Publish package
         run: |
           rm -rf .npmrc && echo "//registry.npmjs.org/:_authToken=$NPM_TOKEN_KOOBIQ" > ~/.npmrc

docs/guides/installation.en.md

@@ -2,18 +2,49 @@ This guide describes how to set up an Angular project to use `@koobiq/components
 
 ### Installing dependencies
 
-Installation using [Angular CLI](https://angular.dev/cli/add):
+Installation using [Angular CLI](https://angular.dev/cli/add) — recommended, because it installs the
+Angular packages at the version your application is already on:
 
 ```bash
 ng add @koobiq/components
 ```
 
-Manual installation:
+Manual installation. First install the Angular packages, using the same range your `package.json`
+already has for `@angular/core` — `@angular/animations` requires an exactly matching
+`@angular/core`, so a mismatched range fails with `ERESOLVE unable to resolve dependency tree`:
 
 ```bash
-npm install @koobiq/components @koobiq/icons @koobiq/design-tokens @koobiq/angular-luxon-adapter @koobiq/date-adapter @koobiq/date-formatter luxon
+npm install @angular/animations@^20.3.0 @angular/cdk@^20.2.0
 ```
 
+Then install the library and the rest of its dependencies:
+
+```bash
+npm install @koobiq/components overlayscrollbars @koobiq/icons @koobiq/design-tokens @koobiq/angular-luxon-adapter @koobiq/date-adapter @koobiq/date-formatter luxon
+```
+
+`@koobiq/angular-luxon-adapter` (or `@koobiq/angular-moment-adapter`) is only needed if you use the
+date components — [datepicker](/en/components/datepicker), [timepicker](/en/components/timepicker) or
+[filter-bar](/en/components/filter-bar). Install `marked` if you use
+[markdown](/en/components/markdown), `highlight.js` if you use
+[code-block](/en/components/code-block), and `@angular/router` if you use
+[breadcrumbs](/en/components/breadcrumbs).
+
+### Setting up animations
+
+The components use Angular animations, so the application must provide them:
+
+```typescript
+import { provideAnimations } from '@angular/platform-browser/animations';
+
+bootstrapApplication(AppComponent, {
+    providers: [provideAnimations()]
+});
+```
+
+Without this provider, opening a component that animates — dropdown, select, tooltip, toast,
+datepicker — fails with `NG05105: Unexpected synthetic property @state found`.
+
 ### Setting up styles
 
 After installation, you need to include the library styles. Add the following files to the `styles` array in your `angular.json` file:

docs/guides/installation.ru.md

@@ -2,18 +2,50 @@
 
 ### Установка зависимостей
 
-Установка с помощью [Angular CLI](https://angular.dev/cli/add):
+Установка с помощью [Angular CLI](https://angular.dev/cli/add) — рекомендуемый способ, так как
+Angular-пакеты будут установлены той версии, на которой уже находится приложение:
 
 ```bash
 ng add @koobiq/components
 ```
 
-Ручная установка:
+Ручная установка. Сначала установите Angular-пакеты, указав тот же диапазон, который уже стоит
+в `package.json` для `@angular/core`: `@angular/animations` требует точно совпадающий
+`@angular/core`, поэтому несовпадающий диапазон приведёт к ошибке
+`ERESOLVE unable to resolve dependency tree`:
 
 ```bash
-npm install @koobiq/components @koobiq/icons @koobiq/design-tokens @koobiq/angular-luxon-adapter @koobiq/date-adapter @koobiq/date-formatter luxon
+npm install @angular/animations@^20.3.0 @angular/cdk@^20.2.0
 ```
 
+Затем установите библиотеку и остальные её зависимости:
+
+```bash
+npm install @koobiq/components overlayscrollbars @koobiq/icons @koobiq/design-tokens @koobiq/angular-luxon-adapter @koobiq/date-adapter @koobiq/date-formatter luxon
+```
+
+`@koobiq/angular-luxon-adapter` (или `@koobiq/angular-moment-adapter`) нужен только при использовании
+компонентов для работы с датами — [datepicker](/ru/components/datepicker),
+[timepicker](/ru/components/timepicker) или [filter-bar](/ru/components/filter-bar). Установите
+`marked`, если используете [markdown](/ru/components/markdown), `highlight.js`, если используете
+[code-block](/ru/components/code-block), и `@angular/router`, если используете
+[breadcrumbs](/ru/components/breadcrumbs).
+
+### Настройка анимаций
+
+Компоненты используют анимации Angular, поэтому приложение должно их предоставить:
+
+```typescript
+import { provideAnimations } from '@angular/platform-browser/animations';
+
+bootstrapApplication(AppComponent, {
+    providers: [provideAnimations()]
+});
+```
+
+Без этого провайдера открытие компонента с анимацией — dropdown, select, tooltip, toast,
+datepicker — завершится ошибкой `NG05105: Unexpected synthetic property @state found`.
+
 ### Настройка стилей
 
 После установки необходимо подключить стили библиотеки. Добавьте следующие файлы в массив `styles` вашего файла `angular.json`:

package.json

@@ -13,7 +13,7 @@
         "url": "https://github.com/koobiq/angular-components.git"
     },
     "packageManager": "yarn@4.1.1",
-    "requiredAngularVersion": ">=20.0.0",
+    "requiredAngularVersion": "^20.0.0",
     "engines": {
         "node": ">=24.16"
     },
@@ -92,6 +92,7 @@
         "@types/merge2": "^0.3.30",
         "@types/node": "^24.10.4",
         "@types/nunjucks": "^3.2.1",
+        "@types/semver": "^7.7.1",
         "@types/spdx-satisfies": "^0.1.2",
         "angular-eslint": "^20.7.0",
         "autoprefixer": "^10.5.2",
@@ -137,6 +138,7 @@
         "rollup-plugin-terser": "^7.0.2",
         "rollup-plugin-typescript2": "^0.37.0",
         "sass": "^1.93.3",
+        "semver": "^7.8.1",
         "spdx-satisfies": "^5.0.1",
         "style-dictionary": "^3.7.1",
         "stylelint": "^17.14.1",
@@ -296,6 +298,8 @@
         "approve-api": "ts-node --project tools/api-extractor/tsconfig.json tools/api-extractor/api-extractor.ts",
         "check-api": "yarn run approve-api onlyCheck",
         "-----LINTERS-----": "----------------------------------------------------------------------------------------",
+        "check-peer-deps": "ts-node --project tools/check-peer-deps/tsconfig.json tools/check-peer-deps",
+        "check-npm-resolution": "ts-node --project tools/check-npm-resolution/tsconfig.json tools/check-npm-resolution",
         "eslint": "eslint .",
         "eslint:fix": "yarn run eslint --fix",
         "stylelint": "stylelint '**/*.{css,scss}'",

packages/angular-luxon-adapter/package.json

@@ -13,8 +13,12 @@
     ],
     "license": "MIT",
     "peerDependencies": {
-        "@koobiq/luxon-date-adapter": "^3.1.4",
-        "@koobiq/components": "{{VERSION}}"
+        "@angular/common": "{{NG_VERSION}}",
+        "@angular/core": "{{NG_VERSION}}",
+        "@koobiq/luxon-date-adapter": "^3.4.0",
+        "@koobiq/components": "^{{VERSION}}",
+        "luxon": "^3.2.1",
+        "rxjs": "^7.4.0"
     },
     "dependencies": {
         "tslib": "^2.6.2"

packages/angular-moment-adapter/package.json

@@ -13,8 +13,10 @@
     ],
     "license": "MIT",
     "peerDependencies": {
-        "@koobiq/moment-date-adapter": "^3.1.4",
-        "@koobiq/components": "{{VERSION}}"
+        "@angular/core": "{{NG_VERSION}}",
+        "@koobiq/moment-date-adapter": "^3.4.0",
+        "@koobiq/components": "^{{VERSION}}",
+        "rxjs": "^7.4.0"
     },
     "dependencies": {
         "tslib": "^2.6.2"

packages/components-experimental/package.json

@@ -25,7 +25,7 @@
         "@angular/cdk": "{{NG_VERSION}}",
         "@angular/core": "{{NG_VERSION}}",
         "@angular/forms": "{{NG_VERSION}}",
-        "@koobiq/components": "{{VERSION}}"
+        "@koobiq/components": "^{{VERSION}}"
     },
     "dependencies": {
         "tslib": "^2.6.2"

packages/components/package.json

@@ -23,13 +23,38 @@
     "peerDependencies": {
         "@angular/animations": "{{NG_VERSION}}",
         "@angular/cdk": "{{NG_VERSION}}",
+        "@angular/common": "{{NG_VERSION}}",
         "@angular/core": "{{NG_VERSION}}",
         "@angular/forms": "{{NG_VERSION}}",
-        "@koobiq/angular-moment-adapter": "{{VERSION}}",
-        "@koobiq/angular-luxon-adapter": "{{VERSION}}",
+        "@angular/platform-browser": "{{NG_VERSION}}",
+        "@angular/router": "{{NG_VERSION}}",
+        "@koobiq/angular-moment-adapter": "^{{VERSION}}",
+        "@koobiq/angular-luxon-adapter": "^{{VERSION}}",
+        "@koobiq/date-adapter": "^3.4.0",
         "@koobiq/date-formatter": "^3.2.3",
-        "@koobiq/icons": "^11.1.3",
-        "@koobiq/design-tokens": "^3.14.0"
+        "@koobiq/icons": ">=11.1.3 <13.0.0",
+        "@koobiq/design-tokens": "^3.14.0",
+        "highlight.js": "^11.11.1",
+        "marked": "^17.0.0",
+        "overlayscrollbars": "^2.7.3",
+        "rxjs": "^7.4.0"
+    },
+    "peerDependenciesMeta": {
+        "@angular/router": {
+            "optional": true
+        },
+        "@koobiq/angular-moment-adapter": {
+            "optional": true
+        },
+        "@koobiq/angular-luxon-adapter": {
+            "optional": true
+        },
+        "highlight.js": {
+            "optional": true
+        },
+        "marked": {
+            "optional": true
+        }
     },
     "dependencies": {
         "tslib": "^2.6.2"

packages/docs-examples/package.json

@@ -9,12 +9,28 @@
     ],
     "license": "MIT",
     "peerDependencies": {
+        "@angular/animations": "{{NG_VERSION}}",
         "@angular/cdk": "{{NG_VERSION}}",
         "@angular/core": "{{NG_VERSION}}",
         "@angular/common": "{{NG_VERSION}}",
-        "@koobiq/components": "{{VERSION}}",
-        "@koobiq/angular-moment-adapter": "{{VERSION}}",
-        "@koobiq/angular-luxon-adapter": "{{VERSION}}"
+        "@angular/forms": "{{NG_VERSION}}",
+        "@angular/platform-browser": "{{NG_VERSION}}",
+        "@angular/router": "{{NG_VERSION}}",
+        "@koobiq/ag-grid-angular-theme": "^34.5.1",
+        "@koobiq/components": "^{{VERSION}}",
+        "@koobiq/angular-moment-adapter": "^{{VERSION}}",
+        "@koobiq/angular-luxon-adapter": "^{{VERSION}}",
+        "@maskito/angular": "^5.1.0",
+        "@maskito/core": "^5.1.0",
+        "@maskito/kit": "^5.3.1",
+        "ag-grid-angular": "^34.3.1",
+        "ag-grid-community": "^34.3.1",
+        "country-flag-icons": "^1.6.20",
+        "highlight.js": "^11.11.1",
+        "jspdf": "^4.2.1",
+        "jspdf-autotable": "^5.0.8",
+        "luxon": "^3.7.2",
+        "rxjs": "^7.4.0"
     },
     "dependencies": {
         "tslib": "^2.6.2"

packages/schematics/rollup.config.js

@@ -55,14 +55,16 @@ module.exports = [
             clean(),
             replace({
                 preventAssignment: true,
+                'VERSIONS.ANGULAR_ANIMATIONS': version(pkg.dependencies['@angular/animations']),
                 'VERSIONS.ANGULAR_CDK': version(pkg.dependencies['@angular/cdk']),
                 'VERSIONS.KOOBIQ_CDK': version(pkg.version),
                 'VERSIONS.KOOBIQ_ANGULAR_LUXON_ADAPTER': version(pkg.version),
                 'VERSIONS.KOOBIQ_DATE_FORMATTER': version(pkg.dependencies['@koobiq/date-formatter']),
                 'VERSIONS.KOOBIQ_DATE_ADAPTER': version(pkg.dependencies['@koobiq/date-adapter']),
                 'VERSIONS.KOOBIQ_DESIGN_TOKENS': version(pkg.devDependencies['@koobiq/design-tokens']),
                 'VERSIONS.KOOBIQ_ICONS': version(pkg.dependencies['@koobiq/icons']),
-                'VERSIONS.LUXON': version(pkg.devDependencies.luxon)
+                'VERSIONS.LUXON': version(pkg.devDependencies.luxon),
+                'VERSIONS.OVERLAYSCROLLBARS': version(pkg.dependencies.overlayscrollbars)
             }),
             typescript({
                 tsconfig: path.join(__dirname, 'tsconfig.rollup.json')

packages/schematics/src/collection.json

@@ -87,6 +87,11 @@
             "factory": "./migrations/button-supported-colors/index",
             "schema": "./migrations/button-supported-colors/schema.json"
         },
+        "mandatory-peer-dependencies": {
+            "description": "Adds @angular/animations, overlayscrollbars and @koobiq/date-adapter, which became mandatory peers of @koobiq/components, to projects whose package manager does not install new peers on upgrade",
+            "factory": "./migrations/mandatory-peer-dependencies/index",
+            "schema": "./migrations/mandatory-peer-dependencies/schema.json"
+        },
         "button-toggle-signals-and-aria": {
             "description": "Migrates KbqButtonToggleGroup consumers to its signal inputs (vertical/multiple reads become calls) and reports the ARIA, tab-order and keyboard changes of the button-toggle review, including icon-only toggles left without an accessible name",
             "factory": "./migrations/button-toggle-signals-and-aria/index",

packages/schematics/src/migrations.json

@@ -51,6 +51,11 @@
             "description": "Migrates KbqButton and KbqButtonToggle consumers to labels that truncate with an ellipsis by default. Moves an icon sitting at either edge of the default slot into the kbqButtonPrefix/kbqButtonSuffix slot, which is what keeps it beside the truncating label box instead of inside it (icon-only buttons are left alone, and an icon rendered by a single-element @if block is still marked). Reports — without rewriting — stylesheets that override .kbq-button-text (was a flex row, now inline-block), .kbq-button-wrapper (hand-rolled truncation now stacks on the built-in one) and .kbq-button-toggle-wrapper (the label moved into the new .kbq-button-toggle-text box), and notes the silent part: .kbq-button/.kbq-light-button gained max-width: 100%, so a button that used to overflow its container now clamps and clips its label.",
             "factory": "./migrations/button-truncation/index"
         },
+        "mandatory-peer-dependencies": {
+            "version": "20.3.0-0",
+            "description": "Adds the packages that became mandatory peerDependencies of @koobiq/components — @angular/animations (at the range the project uses for @angular/core, because every animations release pins core exactly), overlayscrollbars and @koobiq/date-adapter — and schedules an install. npm adds a newly mandatory peer on upgrade by itself, but Yarn does not and pnpm only does with auto-install-peers, so those projects would otherwise upgrade into 'Cannot find module' at build time. Warns when @koobiq/date-adapter is already present, since an existing entry is left untouched and anything below 3.4.0 lacks the addCalendarUnits()/startOf() the date components call.",
+            "factory": "./migrations/mandatory-peer-dependencies/index"
+        },
         "button-supported-colors": {
             "version": "20.3.0-0",
             "description": "Migrates consumers to the narrowed button color set. `color` on KbqButton, KbqButtonGroupRoot and KbqSplitButton (and `kbqOkType` on KbqModalComponent / ModalOptions) now accepts theme, theme-fade, contrast and contrast-fade only — every other value matched no rule in kbq-button-theme() and rendered the button as a native one. Removes such a color written as a literal from templates, which is appearance-preserving now that each style falls back to its own default color, and warns about the ones it cannot resolve (enum members, programmatic assignment, members still typed KbqComponentColors / ThemePalette). Also flags the silent part: a transparent button with no explicit color now defaults to contrast instead of contrast-fade, so a `.kbq-button_transparent.kbq-contrast-fade` override stops matching.",