publish-joint-react-docs.yml

# This GitHub Actions workflow builds and deploys the documentation
# for the `@joint/react` package to GitHub Pages.
name: Publish Joint React Docs

# Trigger this workflow on:
on:
  workflow_dispatch:
  push:
    branches:
      - master
    paths:
      - 'packages/joint-react/**'           # Only trigger if files in this folder change
      - '.github/workflows/**'              # (optional) include changes to the workflow itself
  workflow_call:

# Reset permissions and grant them explicitly per job.
permissions: {}

# Prevent concurrent runs of this workflow
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  # Job to build the documentation (Storybook + TypeDoc)
  build-joint-react-docs:
    if: ${{ github.repository == 'clientIO/joint' }}
    runs-on: ubuntu-latest
    permissions:
      contents: read # the built docs leave as an artifact
    defaults:
      run:
        working-directory: ./packages/joint-react
    outputs:
      # Save the docs output path for the next job
      pages_path: ${{ steps.prepare.outputs.pages_path }}

    steps:
      # Checkout the repo contents
      - uses: actions/checkout@v7
        with:
          persist-credentials: false

      # Set up Node.js version for building
      - name: Use Node.js 22.14.0
        uses: actions/setup-node@v7
        with:
          node-version: '22.14.0'

      # Cache Yarn packages to speed up CI
      - name: Cache Yarn
        uses: actions/cache@v6
        with:
          path: |
            .yarn/cache
          key: yarn-cache-${{ hashFiles('yarn.lock') }}

      # Install all dependencies from the monorepo root
      #
      # `PUPPETEER_SKIP_DOWNLOAD` is what keeps this step green. Four packages
      # depend on `puppeteer`, the `node-modules` linker gives each one a copy
      # of its own, and Yarn runs every copy's `postinstall` concurrently - all
      # four into the one shared `~/.cache/puppeteer`. `@puppeteer/browsers`
      # downloads a browser to a fixed archive path, unpacks it and then deletes
      # it, with no locking, so whichever process gets there first deletes the
      # archive the others are still unpacking and they die on `ENOENT`.
      #
      # NOTE: unlike the workflows that test, nothing is installed in their
      # place - this job only builds docs, and launches no browser.
      - name: Install dependencies from root
        env:
          PUPPETEER_SKIP_DOWNLOAD: 'true'
        run: yarn install --immutable
        working-directory: ./

      # Build the core package (dependency of joint-react)
      - name: Build @joint/core package
        run: yarn workspace @joint/core build
        working-directory: ./

      # Create output folders for Storybook and Typedoc
      - name: Ensure docs folders
        id: prepare
        run: |
          mkdir -p docs/learn
          mkdir -p docs/api
          echo "pages_path=$(pwd)/docs" >> $GITHUB_OUTPUT

      # Build Storybook with proper BASE_DOCS_URL for MD linking
      - name: Build Storybook
        env:
          STORYBOOK_BASE_DOCS_URL: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/api
        run: |
          echo "Using BASE_DOCS_URL=$STORYBOOK_BASE_DOCS_URL"
          yarn build-storybook -o docs/learn

      # Generate API reference using TypeDoc
      - name: Build Typedoc
        run: NODE_ENV=production yarn docs:typedoc

      # Upload the built docs as an artifact for GitHub Pages deployment
      - name: Upload GitHub Pages artifact
        uses: actions/upload-pages-artifact@v5
        with:
          path: ./packages/joint-react/docs

  # Deploy the docs to GitHub Pages
  deploy-joint-react-docs:
    needs: build-joint-react-docs
    if: ${{ github.repository == 'clientIO/joint' }}
    runs-on: ubuntu-latest
    permissions:
      pages: write # publish the artifact to GitHub Pages
      id-token: write # OIDC token the Pages deployment is verified with
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    steps:
      # Setup GitHub Pages deployment environment
      - name: Setup GitHub Pages
        uses: actions/configure-pages@v6

      # Deploy the uploaded artifact to GitHub Pages
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v5