Document Components 3 with PrimeReact 11.2 and guard 3.x releases on main

.github/workflows/publish.yml

@@ -58,6 +58,30 @@ jobs:
             - name: Checkout code
               uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
+            # Older majors are released from their support branch (see release.md). A version from
+            # an older major dispatched here would create its GitHub release on main.
+            - name: Refuse a dispatched version from an older major
+              if: github.event_name == 'workflow_dispatch'
+              env:
+                  VERSION: ${{ github.event.inputs.version }}
+              run: |
+                  set -euo pipefail
+                  [[ "$VERSION" == "0.0.0" ]] && exit 0
+                  if [[ ! "$VERSION" =~ ^([0-9]+)\.[0-9]+\.[0-9]+$ ]]; then
+                    echo "::error::'$VERSION' is not a version."
+                    exit 1
+                  fi
+                  requested_major="${BASH_REMATCH[1]}"
+                  current_major=$(node -p "require('./Source/package.json').version.split('.')[0]")
+                  if [[ ! "$current_major" =~ ^[0-9]+$ ]]; then
+                    echo "::error::Could not read the current major from Source/package.json."
+                    exit 1
+                  fi
+                  if (( 10#$requested_major < 10#$current_major )); then
+                    echo "::error::$VERSION belongs to an older major; dispatch publish.yml on its support branch instead."
+                    exit 1
+                  fi
+
             - name: Release
               id: release
               uses: cratis/release-action@f5fc6db6adbb4db6e6c4548cd7addfc924426e69 # v1

Documentation/troubleshooting.md

@@ -44,6 +44,10 @@ The public adapters implement the declared presentation slots rather than replac
 
 Use the [UI foundation capability matrix](ui-foundation.md#capability-matrix) to check the server-rendering boundary for the component profile. For a custom portal container, resolve `document` inside `overlayEnvironment.getContainer` and return `null` when it is unavailable, as shown in [Choose an overlay container](Common/cratis-components-provider.md#choose-an-overlay-container).
 
+## Components 3 fails to build after updating PrimeReact to 11.2
+
+`@cratis/components` 3.x imports `@primereact/styles/password`, which PrimeReact 11.2.0 renamed to `inputpassword`. Components 3.6.1 and earlier declare PrimeReact `^11.0.0`, so the install succeeds and then a bundler that follows package `exports`, such as Vite, fails with `"styles" is not exported by ... @primereact/styles/password`. Later 3.x maintenance releases limit PrimeReact to versions below 11.2.0, so the package manager reports the mismatch instead. Keep `primereact` and every `@primereact/*` package at 11.1.x while you stay on Components 3, or move to Components 4, which does not depend on PrimeReact; see [Migrating from 3 to 4](Migration/3-to-4.md). The PrimeReact 11 renderer adapter for Components 4 is tested against 11.2.0.
+
 ## See also
 
 For generated proxies, command authorization, command validation, and Arc request behavior, use [Arc troubleshooting](/arc/troubleshooting/).

release.md

@@ -59,6 +59,41 @@ A brand-new npm package must receive a one-time authenticated bootstrap publicat
 publishing can be configured; do not begin a multi-package release until all package records and
 trusted publishers are ready.
 
+## Components 3 maintenance releases
+
+Components 3 is in maintenance support and is released from the `support/3.x` branch, never from
+`main`. Land a fix there through a pull request, then dispatch the support branch's `publish.yml`
+with the exact 3.x version:
+
+```bash
+gh workflow run publish.yml --ref support/3.x -f version=3.x.y
+```
+
+In the GitHub form, choose **Use workflow from: support/3.x**. Dispatching on `main` runs the
+4.x publish workflow, which refuses a version from an older major.
+
+The support branch's workflow:
+
+- refuses to run anywhere but `support/3.x`, or for a version that is not a new 3.x version;
+- builds, lints, and tests before publishing, in a job that cannot write to the repository;
+- publishes `@cratis/components` and `@cratis/eslint-plugin-components` under the `v3-lts`
+  dist-tag. `publish-version` refuses to publish without a non-`latest` tag, so npm `latest` stays
+  on the current major. Applications depending on `^3.x` still receive the release through their
+  range;
+- skips packages already on the registry at that version, so re-running a failed run continues
+  where it stopped;
+- verifies that both packages reached the registry under `v3-lts` and that `latest` did not move;
+  and
+- then pushes a plain `v3.x.y` git tag. It creates no GitHub release, so GitHub never marks a 3.x
+  release as the repository's latest release. The release action on `main` versions from the
+  highest release, so 3.x tags do not affect it.
+
+If both packages show the version under `v3-lts` but the tag was never pushed, push it at the
+dispatched commit: `git tag v3.x.y <commit> && git push origin v3.x.y`. If a publish ever moves
+`latest` to 3.x, restore it with an npm account that can manage the package:
+`npm dist-tag add @cratis/components@<current 4.x version> latest`, and the same for
+`@cratis/eslint-plugin-components`.
+
 ## Release evidence and verification
 
 `.github/workflows/javascript-build.yml` generates retained archives, SHA-256/SHA-512 manifests,