Improve workflow with better error handling and documentation

Co-authored-by: tyeth <6692083+tyeth@users.noreply.github.com>

Author: Copilot

.github/workflows/README-deploy-preview.md

@@ -0,0 +1,101 @@
+# GitHub Pages Preview Deployments
+
+This workflow (`deploy-preview.yml`) automatically builds and deploys preview versions of the examples application to GitHub Pages for every branch push and pull request.
+
+## How it works
+
+### Triggering Events
+- **Pull Requests**: Triggers on `opened`, `synchronize`, and `reopened` events
+- **Branch Pushes**: Triggers on pushes to any branch except `main` (which has its own deployment workflow)
+
+### Deployment Paths
+
+The workflow deploys to the `gh-pages` branch using the following path structure:
+
+- **Pull Requests**: `pr/<pr-number>-<short-sha>/`
+  - Example: `pr/42-abc1234/`
+  
+- **Branches**: `branch/<safe-branch-name>-<short-sha>/`
+  - Example: `branch/feature_new-ui-a7b8c9d/`
+
+### Base URL Configuration
+
+The workflow automatically:
+1. Fetches the GitHub Pages URL using the `gh` CLI
+2. Falls back to `https://<owner>.github.io/<repo>` if Pages isn't configured
+3. Builds the examples app with the correct base href using Parcel's `--public-url` option
+4. All asset paths are absolute URLs pointing to the correct subdirectory
+
+### Features
+
+- ✅ **Automatic PR Comments**: Posts a comment on PRs with the preview URL
+- ✅ **Branch Sanitization**: Safely handles branch names with special characters
+- ✅ **Incremental Deployments**: Each commit creates a new deployment with a unique SHA
+- ✅ **Job Summaries**: Provides deployment URL in GitHub Actions summary
+- ✅ **gh-pages Auto-Init**: Creates the gh-pages branch if it doesn't exist
+
+## Usage
+
+### For Pull Requests
+1. Open a pull request
+2. Wait for the workflow to complete
+3. Click the preview URL in the automated comment
+4. Each new commit will update the deployment (with a new SHA in the path)
+
+### For Branch Pushes
+1. Push commits to any branch (except `main`)
+2. Check the workflow run for the deployment URL in the summary
+3. Access your preview at: `https://<owner>.github.io/<repo>/branch/<branch-name>-<sha>/`
+
+## Permissions Required
+
+The workflow needs the following permissions:
+- `contents: write` - To push to the gh-pages branch
+- `pull-requests: write` - To comment on pull requests
+- `pages: read` - To fetch the GitHub Pages URL
+
+## Build Process
+
+1. Install root dependencies and build the library
+2. Install example app dependencies
+3. Clean previous builds
+4. Generate API documentation
+5. Build example app with Parcel using custom `--public-url`
+6. Deploy to gh-pages branch in the appropriate subdirectory
+
+## Customization
+
+### Changing the Deployment Path Format
+
+Edit the "Determine deployment path" step in `.github/workflows/deploy-preview.yml`:
+
+```yaml
+- name: Determine deployment path
+  id: deployment-path
+  run: |
+    # Modify DEPLOY_DIR and BASE_HREF variables here
+```
+
+### Changing Build Configuration
+
+The build uses Parcel with the following options:
+- `--no-optimize`: Faster builds, easier debugging
+- `--public-url`: Dynamic base URL for assets
+
+To modify, edit the "Build example with base href" step.
+
+## Troubleshooting
+
+### Preview URL returns 404
+- Ensure GitHub Pages is enabled for the repository
+- Check that the gh-pages branch exists
+- Verify the deployment path in the workflow logs
+
+### Assets not loading
+- Check the browser console for failed requests
+- Verify the base href is correct in the deployed HTML
+- Ensure all asset paths are absolute URLs
+
+### Workflow fails to push
+- Check repository permissions
+- Verify the `GITHUB_TOKEN` has write access to contents

.github/workflows/deploy-preview.yml

@@ -4,6 +4,7 @@ on:
   push:
     branches:
       - '**'  # All branches
+      - '!main'  # Exclude main branch (handled by pages.yml)
   pull_request:
     types: [opened, synchronize, reopened]
 
@@ -100,16 +101,20 @@ jobs:
       - name: Setup gh-pages branch
         if: steps.checkout-gh-pages.outputs.exists == 'false'
         run: |
-          # Create orphan gh-pages branch
-          git checkout --orphan gh-pages
-          git rm -rf .
-          echo "# GitHub Pages" > README.md
+          # Create a temporary directory for gh-pages initialization
+          mkdir -p /tmp/gh-pages-init
+          cd /tmp/gh-pages-init
+          git init
+          git checkout -b gh-pages
+          echo "# GitHub Pages - Preview Deployments" > README.md
+          echo "" >> README.md
+          echo "This branch contains preview deployments for pull requests and branches." >> README.md
           git add README.md
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
           git commit -m "Initialize gh-pages branch"
-          git push origin gh-pages
-          cd ..
+          git remote add origin https://x-access-token:${{ github.token }}@github.com/${{ github.repository }}.git
+          git push -u origin gh-pages
 
       - name: Checkout existing gh-pages
         if: steps.checkout-gh-pages.outputs.exists == 'true'
@@ -155,17 +160,31 @@ jobs:
         with:
           script: |
             const deployUrl = '${{ steps.deployment-path.outputs.base_href }}';
+            const deployDir = '${{ steps.deployment-path.outputs.deploy_dir }}';
             const comment = `### 🚀 Preview Deployment Ready!
             
             Your changes have been deployed to GitHub Pages:
             
-            **Preview URL:** ${deployUrl}
+            **Preview URL:** [${deployUrl}](${deployUrl})
             
-            This preview will be available until the PR is closed or new commits are pushed.`;
+            **Deployment Path:** \`${deployDir}\`
+            
+            This preview will be updated with each new commit to this PR.`;
             
             github.rest.issues.createComment({
               owner: context.repo.owner,
               repo: context.repo.repo,
               issue_number: context.issue.number,
               body: comment
             });
+
+      - name: Output deployment summary
+        run: |
+          echo "## Deployment Summary" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Deployment URL:** [${{ steps.deployment-path.outputs.base_href }}](${{ steps.deployment-path.outputs.base_href }})" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Deployment Directory:** \`${{ steps.deployment-path.outputs.deploy_dir }}\`" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Event Type:** ${{ github.event_name }}" >> $GITHUB_STEP_SUMMARY
+