feat: publish the table as an npm package (#118)

* feat: build the table as an installable npm package

* feat: import the table through its package name, resolved to source

* ci: release through release-please and publish to npm with provenance

* docs: record publishing the table as an npm package

* test: pin the English default labels

* feat: ship English default labels with the table

* feat: route the demo through the package entry and type-check every public type

* feat: prefix every design token with yart

* feat: ship native light-dark() and the forced-colors remap with the table

* feat: typecheck the package under nodenext resolution

* ci: lint the packed tarball with publint and attw

* docs: record the light-dark() floor and the prefixed, layered tokens

* docs: document installing, styling and labeling the npm package

* ci: pack the tarball in a job without publish rights

* ci: require npm 11.5.1 to publish and time-box release-please

* ci: find the first release's changelog heading, which has no brackets

* ci: file dependency bumps under Dependencies and keep tooling changes out of releases

* docs: note that every package export is client code under server components

* fix: keep the forced-colors remap ahead of a host's token overrides

* docs: say which npm releases enforce the Node 24 floor

* test: catch a Sass import in the published declarations

* feat: expose package.json through the exports map

* fix: let a host share its own react-icons 5.x

* test: install the lowest React the peer range admits in the package smoke

* docs: fold the remap and react-icons decisions into their records

* ci: keep dev dependency bumps out of releases and hold the react-icons floor

* fix: run the benchmarks against source when the package entry pulls in styles

* fix: share the build floor, source condition and class names across the build configs

* test: match stylesheet imports in the published declarations by specifier

* docs: complete the README snippet imports and narrow two overstated claims

* docs: point the browser floor at vite.shared.ts

* fix: keep the forced-colors remap ahead of a themed root override

* chore: use US spelling in the stylelint color messages

* docs: tighten the package docs and comments

* docs: make the search example a complete component

* test: typecheck the README examples against the packed tarball

* test: drop toolchain guards that pin prose or duplicate loud failures (#119)

Author: funkadelic

.github/dependabot.yml

@@ -1,25 +1,26 @@
 version: 2
 
 updates:
-  # Package manifest at the repository root. Every entry in it is an exact pin, so the
-  # versioning strategy is set explicitly: "increase" rewrites the pinned version in
-  # place, while the default would be free to widen a pin into a range and quietly
-  # reverse the convention the whole manifest follows.
+  # Package manifest at the repository root. Every dev dependency is an exact pin, which
+  # "increase-if-necessary" rewrites in place. The two ranges are floors for consumers:
+  # the React peer, and react-icons, a caret so a host shares its own copy. A bump inside
+  # the caret moves only the lockfile, so the floor stays where it is.
   - package-ecosystem: npm
     directory: "/"
     schedule:
       interval: weekly
     open-pull-requests-limit: 5
-    versioning-strategy: increase
-    # Generated subjects have to be Conventional Commits, same as hand written ones.
+    versioning-strategy: increase-if-necessary
     # Hold new releases a few days so a hijacked publish is pulled before it is
     # proposed. Security updates bypass this.
     cooldown:
       default-days: 5
       semver-major-days: 14
+    # Generated subjects have to be Conventional Commits, same as hand written ones.
+    # release-please files the deps and deps-dev types under Dependencies.
     commit-message:
-      prefix: "chore(deps)"
-      prefix-development: "chore(deps-dev)"
+      prefix: deps
+      prefix-development: deps-dev
     # Grouped so a routine week is two pull requests to review rather than a dozen.
     # Each group is held to minor and patch only. A grouped major is unreviewable: nine
     # of them arrived as one pull request that could not install, because a single held
@@ -78,8 +79,9 @@ updates:
     open-pull-requests-limit: 5
     cooldown:
       default-days: 5
+    # ci is a hidden changelog type, so an action bump proposes no release.
     commit-message:
-      prefix: "chore(actions)"
+      prefix: ci
     groups:
       github-actions:
         patterns:

.github/workflows/ci.yml

@@ -78,6 +78,11 @@ jobs:
       - name: Build
         run: npm run build
 
+      # Packs the tarball a consumer installs and checks it. Nothing else resolves the
+      # published branch of exports; dev, tests and the demo all read src/.
+      - name: Package checks
+        run: npm run test:package
+
       # The browser download is the most expensive thing here, so it sits behind
       # every cheap gate. The jsdom half of the accessibility gate ran in Test.
       - name: Install Chromium

.github/workflows/npm-publish.yml

@@ -0,0 +1,88 @@
+# Publishes each release to npm through OIDC trusted publishing. Inert until the
+# first version is published by hand and the trusted publisher is set on the package's access page.
+name: npm-publish
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+# Two publishes of one tag would race the registry; the second waits and then fails cleanly.
+concurrency:
+  group: npm-publish-${{ github.event.release.tag_name }}
+  cancel-in-progress: false
+
+jobs:
+  # Installs and builds without publish rights, so dependency code never meets the OIDC token.
+  pack:
+    # release-please cuts full releases only; a hand-cut prerelease is not published.
+    if: ${{ !github.event.release.prerelease }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    outputs:
+      node-version: ${{ steps.node.outputs.node-version }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      # No dependency cache: a poisoned one would end up in the published tarball.
+      - name: Set up Node
+        id: node
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version-file: .nvmrc
+
+      - name: Install
+        run: npm ci
+
+      # prepack builds lib/ before the tarball is made.
+      - name: Pack
+        run: npm pack
+
+      - name: Upload tarball
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: tarball
+          path: "*.tgz"
+          if-no-files-found: error
+          retention-days: 1
+
+  publish:
+    needs: pack
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    # The OIDC token npm exchanges for publish rights, granted to this job alone. It runs no
+    # checkout and no install, only npm itself over the packed tarball.
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Download tarball
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: tarball
+
+      # registry-url writes the .npmrc the OIDC exchange depends on.
+      - name: Set up Node
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: ${{ needs.pack.outputs.node-version }}
+          registry-url: https://registry.npmjs.org
+
+      # Trusted publishing needs npm 11.5.1 or later.
+      - name: Check npm version
+        run: |
+          v="$(npm --version)"
+          if [ "$(printf '%s\n' 11.5.1 "$v" | sort -V | head -n 1)" != 11.5.1 ]; then
+            echo "::error::npm $v is older than 11.5.1, which trusted publishing needs."
+            exit 1
+          fi
+
+      - name: Publish
+        run: npm publish ./*.tgz --provenance --access public

.github/workflows/release-please.yml

@@ -0,0 +1,73 @@
+name: release-please
+
+on:
+  push:
+    branches:
+      - main
+  # Reopens the release PR when a push to main never fired the webhook.
+  workflow_dispatch:
+
+# The App token does the writing, so the workflow token stays read-only.
+permissions:
+  contents: read
+
+concurrency:
+  group: release-please-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  release-please:
+    # Keeps a manual dispatch from running release-please against another ref.
+    if: ${{ github.ref == 'refs/heads/main' }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Generate App token
+        id: app-token
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        with:
+          client-id: ${{ secrets.RELEASE_PLEASE_APP_ID }}
+          private-key: ${{ secrets.RELEASE_PLEASE_APP_PRIVATE_KEY }}
+          permission-contents: write
+          permission-issues: write
+          permission-pull-requests: write
+
+      - name: Release please
+        id: release
+        uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0
+        with:
+          # Branch protection requires Verify, which never runs on a PR the
+          # workflow token opens, so the App authors the release PR.
+          token: ${{ steps.app-token.outputs.token }}
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+      - name: Checkout
+        if: ${{ steps.release.outputs.release_created }}
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Sync the release body from the changelog
+        if: ${{ steps.release.outputs.release_created }}
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          TAG_NAME: ${{ steps.release.outputs.tag_name }}
+          VERSION: ${{ steps.release.outputs.version }}
+        run: |
+          # CHANGELOG.md is the one source of the release notes. The first release has
+          # no compare link, so its heading is "## 0.1.0 (" rather than "## [0.1.0]".
+          # index(), not a regex, because the version carries literal dots.
+          awk -v ver="$VERSION" '
+            index($0, "## [" ver "]") == 1 || index($0, "## " ver " ") == 1 { found = 1; next }
+            found && index($0, "## ") == 1 { exit }
+            found { print }
+          ' CHANGELOG.md > release-notes.md
+
+          # A missing section fails the run rather than blanking a correct body.
+          if ! grep -q '[^[:space:]]' release-notes.md; then
+            echo "::error::No CHANGELOG.md section found for ${VERSION}; release body left as generated."
+            exit 1
+          fi
+
+          gh release edit "$TAG_NAME" --notes-file release-notes.md

.gitignore

@@ -24,6 +24,7 @@ yarn-error.log*
 
 # build output
 /dist
+/lib
 
 # local editor and tooling directories, never committed
 /.claude/

.prettierignore

@@ -9,6 +9,9 @@ src/data/films/films.json
 # Build output.
 dist
 
+# Library build output.
+lib
+
 # Coverage output.
 coverage
 
@@ -20,3 +23,6 @@ package-lock.json
 # every source file twice, and the report beside it is machine written.
 .stryker-tmp
 reports
+
+# Written by release-please, whose formatting drifts on every release.
+CHANGELOG.md

.release-please-manifest.json

@@ -0,0 +1 @@
+{}

.stylelintrc.json

@@ -48,7 +48,7 @@
     "selector-disallowed-list": [
       ["/:dir\\(/"],
       {
-        "message": "The :dir() pseudo-class landed in Chrome 120 against this application's floor of 111, so it ships inert in the very browsers the floor exists to name: select the direction on the attribute, as [dir=\"rtl\"] .navButton svg does"
+        "message": "Direction is selected on the attribute everywhere, so every direction rule reads one way: use [dir=\"rtl\"], as [dir=\"rtl\"] .navButton svg does"
       }
     ]
   },
@@ -59,13 +59,13 @@
         "color-no-hex": [
           true,
           {
-            "message": "Colour in a component stylesheet arrives through var(--color-*) and nowhere else, so a theme switch moves every value at once"
+            "message": "Color in a component stylesheet arrives through var(--yart-color-*) and nowhere else, so a theme switch moves every value at once"
           }
         ],
         "color-named": [
           "never",
           {
-            "message": "Colour in a component stylesheet arrives through var(--color-*) and nowhere else; a keyword is as fixed as a hex and flips with no theme"
+            "message": "Color in a component stylesheet arrives through var(--yart-color-*) and nowhere else; a keyword is as fixed as a hex and flips with no theme"
           }
         ],
         "declaration-property-unit-allowed-list": [
@@ -75,7 +75,7 @@
             "/^(gap|row-gap|column-gap|font-size)$/": ["rem"]
           },
           {
-            "message": "Spacing and type are authored in rem through a token, so the layout follows the reader's browser font-size setting: reach for var(--space-*) or var(--font-size-*)"
+            "message": "Spacing and type are authored in rem through a token, so the layout follows the reader's browser font-size setting: reach for var(--yart-space-*) or var(--yart-font-size-*)"
           }
         ],
         "function-disallowed-list": [
@@ -93,7 +93,7 @@
             "color"
           ],
           {
-            "message": "Colour in a component stylesheet arrives through var(--color-*) and nowhere else; a functional notation is as fixed as a hex and flips with no theme"
+            "message": "Color in a component stylesheet arrives through var(--yart-color-*) and nowhere else; a functional notation is as fixed as a hex and flips with no theme"
           }
         ]
       }