diff --git a/.github/workflows/javascript-build.yml b/.github/workflows/javascript-build.yml index b8638c4b..cb4e4845 100644 --- a/.github/workflows/javascript-build.yml +++ b/.github/workflows/javascript-build.yml @@ -81,17 +81,17 @@ jobs: steps: - name: Checkout code - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - name: Setup node - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 + uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 with: - node-version: 23.x + node-version: 24.x registry-url: 'https://registry.npmjs.org' - - uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4 + - uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 id: yarn-cache with: path: | @@ -149,17 +149,17 @@ jobs: steps: - name: Checkout code - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - name: Setup node - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 + uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 with: - node-version: 23.x + node-version: 24.x registry-url: 'https://registry.npmjs.org' - - uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4 + - uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 id: yarn-cache with: path: | @@ -198,17 +198,17 @@ jobs: steps: - name: Checkout code - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - name: Setup node - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 + uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 with: - node-version: 23.x + node-version: 24.x registry-url: 'https://registry.npmjs.org' - - uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4 + - uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 id: yarn-cache with: path: | @@ -258,17 +258,17 @@ jobs: steps: - name: Checkout code - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - name: Setup node - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 + uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 with: - node-version: 23.x + node-version: 24.x registry-url: 'https://registry.npmjs.org' - - uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4 + - uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 id: yarn-cache with: path: | @@ -336,17 +336,17 @@ jobs: steps: - name: Checkout code - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - name: Setup node - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 + uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 with: - node-version: 23.x + node-version: 24.x registry-url: 'https://registry.npmjs.org' - - uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4 + - uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 id: yarn-cache with: path: | @@ -366,7 +366,7 @@ jobs: --output "${{ runner.temp }}/components-v4-release-evidence" - name: Upload release evidence - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 with: name: components-v4-release-evidence-${{ github.sha }} path: | @@ -398,17 +398,17 @@ jobs: steps: - name: Checkout code - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - name: Setup node - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 + uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 with: - node-version: 23.x + node-version: 24.x registry-url: 'https://registry.npmjs.org' - - uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4 + - uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 id: yarn-cache with: path: | @@ -448,17 +448,17 @@ jobs: steps: - name: Checkout code - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - name: Setup node - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 + uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 with: - node-version: 23.x + node-version: 24.x registry-url: 'https://registry.npmjs.org' - - uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4 + - uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 id: yarn-cache with: path: | @@ -484,7 +484,7 @@ jobs: - name: Upload verify-public-types report if: always() - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 with: name: verify-public-types-report-ts${{ matrix.typescript }} path: ${{ runner.temp }}/verify-public-types-report.json @@ -502,17 +502,17 @@ jobs: steps: - name: Checkout code - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - name: Setup node - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 + uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 with: - node-version: 23.x + node-version: 24.x registry-url: 'https://registry.npmjs.org' - - uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4 + - uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 id: yarn-cache with: path: | @@ -536,7 +536,7 @@ jobs: - name: Upload verify-package-graph report if: always() - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 with: name: verify-package-graph-report path: ${{ runner.temp }}/verify-package-graph-report.json @@ -552,17 +552,17 @@ jobs: steps: - name: Checkout code - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - name: Setup node - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 + uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 with: - node-version: 23.x + node-version: 24.x registry-url: 'https://registry.npmjs.org' - - uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4 + - uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 id: yarn-cache with: path: | @@ -594,17 +594,17 @@ jobs: steps: - name: Checkout code - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - name: Setup node - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 + uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 with: - node-version: 23.x + node-version: 24.x registry-url: 'https://registry.npmjs.org' - - uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4 + - uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 id: yarn-cache with: path: | @@ -637,17 +637,17 @@ jobs: steps: - name: Checkout code - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - name: Setup node - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 + uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 with: - node-version: 23.x + node-version: 24.x registry-url: 'https://registry.npmjs.org' - - uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4 + - uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 id: yarn-cache with: path: | @@ -679,14 +679,14 @@ jobs: steps: - name: Checkout code - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - name: Setup node - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 + uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 with: - node-version: 23.x + node-version: 24.x registry-url: 'https://registry.npmjs.org' - name: Yarn install @@ -754,14 +754,14 @@ jobs: steps: - name: Checkout code - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - name: Setup node - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 + uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 with: - node-version: 23.x + node-version: 24.x registry-url: 'https://registry.npmjs.org' - name: Enable Corepack @@ -836,7 +836,7 @@ jobs: yarn node verify-peers.mjs verify-renderer-adapters: - name: Renderer adapter (${{ matrix.adapter }}, ${{ matrix.boundary }}, ${{ matrix.manager }}) + name: Renderer adapter (${{ matrix.adapter }}, ${{ matrix.boundary }}, ${{ matrix.manager }}, Node ${{ matrix.node }}) runs-on: ubuntu-latest timeout-minutes: 25 strategy: @@ -845,17 +845,36 @@ jobs: adapter: [mui, primereact11, primereact10] boundary: [minimum, current] manager: [npm, pnpm, yarn-pnp] + node: [24.x] + # The oldest Node.js the published packages declare in engines. npm with + # engine-strict refuses to install a package whose engines exclude the running + # Node.js, so these legs prove both the declared range and that the adapter works. + include: + - adapter: mui + boundary: current + manager: npm + node: 22.x + - adapter: primereact11 + boundary: current + manager: npm + node: 22.x + - adapter: primereact10 + boundary: current + manager: npm + node: 22.x + env: + npm_config_engine_strict: ${{ matrix.node == '22.x' }} steps: - name: Checkout code - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - name: Setup node - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 + uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 with: - node-version: 23.x + node-version: ${{ matrix.node }} registry-url: 'https://registry.npmjs.org' - name: Enable Corepack diff --git a/.github/workflows/markdown-verification.yml b/.github/workflows/markdown-verification.yml index 8a165dd6..23a8aa27 100644 --- a/.github/workflows/markdown-verification.yml +++ b/.github/workflows/markdown-verification.yml @@ -48,14 +48,14 @@ jobs: timeout-minutes: 15 steps: - name: Checkout code - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - name: Setup node - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 + uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 with: - node-version: 23.x + node-version: 24.x # Run the same entry point contributors use locally so linting, # authoring validation, and local-link checks cannot drift apart. diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index c2cdb99b..15a7dbd3 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -56,7 +56,7 @@ jobs: steps: - name: Checkout code - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - name: Release id: release @@ -76,19 +76,19 @@ jobs: steps: - name: Checkout code - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - name: Setup node - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 + uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 with: - node-version: 23.x + node-version: 24.x registry-url: 'https://registry.npmjs.org' - name: Configure npm for OIDC-based publishing run: | - # setup-node writes a placeholder _authToken (XXXXX-XXXXX-XXXXX-XXXXX) into - # .npmrc and exports NODE_AUTH_TOKEN with the same placeholder. npm uses this - # token as-is for registry auth → 404. Remove it so npm falls back to OIDC. + # setup-node writes _authToken=${NODE_AUTH_TOKEN} into .npmrc. npm would use + # that entry instead of OIDC trusted publishing, so delete it and make sure + # NODE_AUTH_TOKEN is empty. sed -i '/_authToken/d' "$NPM_CONFIG_USERCONFIG" echo "NODE_AUTH_TOKEN=" >> "$GITHUB_ENV" echo "--- .npmrc after stripping placeholder ---" @@ -107,15 +107,16 @@ jobs: } " - - uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4 + - uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 id: yarn-cache with: path: | .yarn/cache **/node_modules **/.eslintcache - **/yarn.lock - key: ${{ runner.os }}-yarn-${{ hashFiles('**/package.json') }} + # The same key as the build, which the lockfile is part of. Never cache yarn.lock + # itself: a restore would replace the checked-out lockfile with a stale one. + key: ${{ runner.os }}-yarn-v2-${{ hashFiles('yarn.lock', '**/package.json', '.yarnrc.yml', '.yarn/releases/yarn-4.17.1.cjs') }} - name: Yarn install run: yarn install --immutable @@ -181,14 +182,14 @@ jobs: fi - name: Trigger Documentation Build - uses: peter-evans/repository-dispatch@ff45666b9427631e3450c54a1bcbee4d9ff4d7c0 # v3 + uses: peter-evans/repository-dispatch@28959ce8df70de7be546dd1250a005dd32156697 # v4.0.1 with: token: ${{ secrets.PAT_DOCUMENTATION }} repository: cratis/documentation event-type: build-docs - name: Trigger Dependency Updates on Sample Repository - uses: peter-evans/repository-dispatch@ff45666b9427631e3450c54a1bcbee4d9ff4d7c0 # v3 + uses: peter-evans/repository-dispatch@28959ce8df70de7be546dd1250a005dd32156697 # v4.0.1 with: token: ${{ secrets.PAT_DOCUMENTATION }} repository: cratis/samples diff --git a/Adapters/Mui/README.md b/Adapters/Mui/README.md index 3d293aba..a1cd7672 100644 --- a/Adapters/Mui/README.md +++ b/Adapters/Mui/README.md @@ -19,7 +19,7 @@ npm install @cratis/components.mui@^4 @cratis/components@^4 \ @mui/material@^9 @emotion/react@^11 @emotion/styled@^11 react@^19 react-dom@^19 ``` -Node-based build, test, and server-rendering environments require Node.js 23 or newer. +Node-based build, test, and server-rendering environments require Node.js 22 or newer. Select the adapter on the application Components provider: diff --git a/Adapters/Mui/package.json b/Adapters/Mui/package.json index 953f53ad..98087cee 100644 --- a/Adapters/Mui/package.json +++ b/Adapters/Mui/package.json @@ -13,7 +13,7 @@ "access": "public" }, "engines": { - "node": ">=23.0.0" + "node": ">=22.0.0" }, "files": [ "dist", diff --git a/Adapters/PrimeReact/README.md b/Adapters/PrimeReact/README.md index 2680b6ea..0fcb4186 100644 --- a/Adapters/PrimeReact/README.md +++ b/Adapters/PrimeReact/README.md @@ -22,7 +22,7 @@ npm install @cratis/components.primereact@^4 @cratis/components@^4 \ @primeuix/themes@^3 react@^19 react-dom@^19 ``` -Node-based build, test, and server-rendering environments require Node.js 23 or newer. +Node-based build, test, and server-rendering environments require Node.js 22 or newer. The adapter uses PrimeReact 11 styled components. It covers Button, IconButton, TextInput, TextArea, Checkbox, Radio, Switch, ProgressBar, and Surface. The five atomic interaction slots are diff --git a/Adapters/PrimeReact/package.json b/Adapters/PrimeReact/package.json index 7aaff1dd..07006cde 100644 --- a/Adapters/PrimeReact/package.json +++ b/Adapters/PrimeReact/package.json @@ -13,7 +13,7 @@ "access": "public" }, "engines": { - "node": ">=23.0.0" + "node": ">=22.0.0" }, "files": [ "dist", diff --git a/Adapters/PrimeReact10/README.md b/Adapters/PrimeReact10/README.md index f79a63c6..881f3b73 100644 --- a/Adapters/PrimeReact10/README.md +++ b/Adapters/PrimeReact10/README.md @@ -23,7 +23,7 @@ npm install @cratis/components.primereact10@^4 @cratis/components@^4 \ primereact@^10.9.9 react@^19 react-dom@^19 ``` -Node-based build, test, and server-rendering environments require Node.js 23 or newer. +Node-based build, test, and server-rendering environments require Node.js 22 or newer. The adapter covers Button, IconButton, TextInput, TextArea, Checkbox, Radio, Switch, ProgressBar, and Surface. The five atomic interaction slots are not part of this profile and continue through the diff --git a/Adapters/PrimeReact10/package.json b/Adapters/PrimeReact10/package.json index 0d73e7af..4a188124 100644 --- a/Adapters/PrimeReact10/package.json +++ b/Adapters/PrimeReact10/package.json @@ -13,7 +13,7 @@ "access": "public" }, "engines": { - "node": ">=23.0.0" + "node": ">=22.0.0" }, "files": [ "dist", diff --git a/Conformance/README.md b/Conformance/README.md index 7cc86531..9734116d 100644 --- a/Conformance/README.md +++ b/Conformance/README.md @@ -17,7 +17,7 @@ mechanism. ## Requirements -- Node.js 23 or newer. +- Node.js 22 or newer. - `@cratis/components` at the same version as this package (the source manifest declares `>=4 <5`; the release step pins the published peer to the exact release version). - React and ReactDOM 19. diff --git a/Conformance/package.json b/Conformance/package.json index 8a5131e7..0dfc0cd2 100644 --- a/Conformance/package.json +++ b/Conformance/package.json @@ -13,7 +13,7 @@ "access": "public" }, "engines": { - "node": ">=23.0.0" + "node": ">=22.0.0" }, "files": [ "dist", diff --git a/Documentation/decisions/0004-stable-presentation-renderer-profile.md b/Documentation/decisions/0004-stable-presentation-renderer-profile.md index 54deb8c7..5e6a1274 100644 --- a/Documentation/decisions/0004-stable-presentation-renderer-profile.md +++ b/Documentation/decisions/0004-stable-presentation-renderer-profile.md @@ -84,6 +84,8 @@ named profile and version so existing adapters never acquire an unimplemented re version. Renderer ABI major `1` remains separate from npm versioning, and every adapter retains the honest `@cratis/components >=4 <5` peer range. +> **2026-09-29 — peer range replaced.** The published peer range is now governed by [ADR 0006, Published adapters pin their Components release](0006-exact-adapter-peer-pin.md), decided on [#233](https://github.com/Cratis/Components/issues/233): each published adapter and Conformance release peers on exactly its own `@cratis/components` release. The `>=4 <5` range above remains what the adapter source manifests declare. The rest of this decision is unchanged. + ## Intentionally unstable The following surfaces keep their `unstable_` prefix and carry no promise from this decision: diff --git a/Documentation/decisions/0006-exact-adapter-peer-pin.md b/Documentation/decisions/0006-exact-adapter-peer-pin.md new file mode 100644 index 00000000..6be7b5b7 --- /dev/null +++ b/Documentation/decisions/0006-exact-adapter-peer-pin.md @@ -0,0 +1,53 @@ +--- +id: '0006' +title: Published adapters pin their Components release +description: Each published adapter and Conformance release peers on exactly the @cratis/components release it ships with. +status: accepted +stage: implemented +class: contract +reversibility: costly +decided: 2026-09-25 +decider: woksin +applies-to: + - 'Adapters/**/*' + - 'Conformance/**/*' + - 'scripts/prepare-release-version.mjs' +sidebar: + badge: { text: Accepted, variant: tip } +--- + +**Status:** Accepted + +**Provenance:** woksin made this decision on [#233](https://github.com/Cratis/Components/issues/233) on 2026-09-25. This record was written on 2026-09-29 to replace the peer range stated in [Stable presentation renderer profile](0004-stable-presentation-renderer-profile.md), which records the rest of the renderer contract and remains in force. + +## Context + +[Stable presentation renderer profile](0004-stable-presentation-renderer-profile.md) states that every adapter retains a `@cratis/components >=4 <5` peer range. That range is what the adapter source manifests declare. The release pipeline has always published something else: `scripts/prepare-release-version.mjs` stamps every workspace peer with the release version, so each published adapter and Conformance release requires exactly the `@cratis/components` release it ships with. All 4.x releases are lockstep. #233 reported the contradiction and asked for one answer. + +## Decision + +Each published adapter (`@cratis/components.primereact`, `@cratis/components.primereact10`, `@cratis/components.mui`) and `@cratis/components.conformance` declares a peer on exactly the `@cratis/components` version it is released with. Applications install and upgrade an adapter and `@cratis/components` together, at the same version. The source manifests keep `>=4 <5` as the bound the renderer ABI major allows. This replaces the peer range sentence in the semver policy of [ADR 0004](0004-stable-presentation-renderer-profile.md); the rest of that record is unchanged. + +## Options considered + +- Publish the `>=4 <5` range. Rejected for now: it lets an application install an adapter and a core release that were never released and tested together, while the renderer ABI is still new. +- Pin the exact release. Chosen: every installable pair has been through the same release's conformance run. +- Pin a caret range such as `^4.21.0`. Rejected: it has the same untested-pair problem as the full range for every later minor release. + +## Default if unanswered + +The documented range and the published pin would keep contradicting each other. Readers of ADR 0004 would expect `>=4 <5` and get peer-dependency errors on every Components upgrade that leaves the adapter behind. + +## Timeline and scope + +In force from 4.x onward. Revisit, with a new record, once the renderer ABI has stayed stable across several releases; widening then means stopping `prepare-release-version.mjs` from rewriting the adapter peers. The renderer ABI, the stable profile and the adapter certification rules in ADR 0004 are out of scope. + +## Verification + +**Done when:** Every published adapter and Conformance release declares a peer on exactly its own `@cratis/components` version, and the adapter and Conformance READMEs say so. + +**Verify by:** `npm view @cratis/components.mui@ peerDependencies` (and the same for the other adapters and Conformance) shows `"@cratis/components": ""`. + +## Consequences + +Every installable adapter and core pair was released and tested together. Applications upgrade the adapter and `@cratis/components` in lockstep on every release, including patch releases, and a peer-dependency error tells them when they have not. Widening the range later is a compatible change; narrowing it again would not be. diff --git a/Documentation/decisions/index.md b/Documentation/decisions/index.md index 626c4f88..009e6b4e 100644 --- a/Documentation/decisions/index.md +++ b/Documentation/decisions/index.md @@ -16,5 +16,6 @@ boundaries. | [0003 — Repository-owned kernel boundary](0003-kernel-boundary.md) | Accepted | Implemented | 2026-08-27 | woksin | | [0004 — Stable presentation renderer profile](0004-stable-presentation-renderer-profile.md) | Accepted | Implemented | 2026-08-28 | woksin | | [0005 — Generic primitive admission](0005-generic-primitive-admission.md) | Accepted | None | 2026-09-28 | woksin (delegated) | +| [0006 — Published adapters pin their Components release](0006-exact-adapter-peer-pin.md) | Accepted | Implemented | 2026-09-25 | woksin | Read [UI foundation](../ui-foundation.md) for the current architecture and capability matrix. diff --git a/Documentation/decisions/toc.yml b/Documentation/decisions/toc.yml index 867913ef..e6303971 100644 --- a/Documentation/decisions/toc.yml +++ b/Documentation/decisions/toc.yml @@ -10,3 +10,5 @@ href: 0004-stable-presentation-renderer-profile.md - name: Generic primitive admission href: 0005-generic-primitive-admission.md +- name: Published adapters pin their Components release + href: 0006-exact-adapter-peer-pin.md diff --git a/Source/MIGRATION.md b/Source/MIGRATION.md index f19a83f6..7c35942d 100644 --- a/Source/MIGRATION.md +++ b/Source/MIGRATION.md @@ -45,9 +45,9 @@ Keep a Prime package only when your application still imports it directly. Migra Applications using Canvas or PivotViewer must install `pixi.js@^8.20.0`, now an optional peer rather than a nested Components dependency. Align any existing direct Pixi dependency to the same compatible resolution so public `PIXI.Container` and pointer-event types come from one package instance. Applications using only non-Pixi subpaths do not need it. -The package declares an Arc peer range of `>=20.3.1 <23`. Conformance and all three renderer -adapters declare the final `@cratis/components >=4 <5` peer range, so each remains bounded to the -Components major whose renderer ABI and stable presentation profile it implements. +The package declares an Arc peer range of `>=20.3.1 <23`. Each published release of Conformance +and the three renderer adapters requires exactly the `@cratis/components` version it is released +with, so install and upgrade an adapter and `@cratis/components` together, at the same version. ## Import from explicit subpaths