feat: Upgrade to Bootstrap and Bootswatch 5.3.8

.claude/skills/bslib-upgrade-bootstrap/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: upgrade-bootstrap
+description: >
+  Walk through upgrading Bootstrap and/or Bootswatch dependencies in the bslib
+  R package. Use when the user asks to upgrade Bootstrap, update Bootstrap,
+  bump the Bootstrap version, upgrade Bootswatch, or update vendored web
+  dependencies in bslib. Covers version pinning, running the build pipeline,
+  diagnosing and fixing rejected patches, and verifying the result.
+---
+
+# Upgrade Bootstrap / Bootswatch in bslib
+
+## Architecture
+
+bslib vendors Bootstrap and Bootswatch via npm, then applies a series of patch
+files that add bslib-specific features (semantic color functions, Shiny form
+support, navbar variables, etc.). The build pipeline is:
+
+1. `yarn install` downloads fresh upstream packages into `inst/node_modules/`
+2. `tools/yarn_install.R` moves them to `inst/lib/`, adds vendor prefixes,
+   validates prefixes, downsizes vendor libraries, applies all patches, and
+   generates precompiled CSS
+3. `tools/main.R` runs `yarn_install.R` plus additional asset scripts
+   (fonts, gfont info, variables article, component sass)
+
+Version pins live in `inst/package.json` as npm aliases:
+
+```json
+"bs5": "npm:bootstrap@5.3.8",
+"bsw5": "npm:bootswatch@5.3.8",
+```
+
+Patches live in `tools/patches/` and are applied alphabetically by filename
+via `git apply --reject --whitespace=fix`. Later patches depend on earlier
+ones (especially for shared files like `_variables.scss`).
+
+## Upgrade Workflow
+
+### Step 1: Update version pins
+
+Edit `inst/package.json` to bump the target version(s). Only change the
+versions being upgraded; leave others untouched.
+
+### Step 2: Run the build pipeline
+
+```bash
+Rscript tools/yarn_install.R
+```
+
+This script will stop with an error if any patch fails to apply. When it
+fails, proceed to Step 3 to fix patches, then re-run from scratch.
+
+### Step 3: Fix rejected patches
+
+When patches fail, follow the systematic approach described in
+[references/patch-fixing-guide.md](references/patch-fixing-guide.md).
+
+Key points:
+- Save clean upstream state before any patch application
+- Test all patches sequentially to identify every failure (not just the first)
+- Fix patches in parallel when possible (use subagents)
+- Re-run `yarn_install.R` from scratch to verify the full sequence
+
+### Step 4: Verify the build
+
+After `yarn_install.R` completes successfully, confirm:
+
+1. **`R/versions.R`** shows the new version (auto-generated by the script)
+2. **No `.rej` files** exist in the working tree
+3. **Vendor prefix validation** passed (part of `yarn_install.R`)
+4. **Precompiled CSS** was generated in `inst/css-precompiled/`
+
+### Step 5: Check for new/removed Bootswatch themes
+
+List themes in `inst/lib/bsw5/dist/` and compare with what existed before.
+`bootswatch_themes()` dynamically reads directory names, so new themes are
+picked up automatically. Check `R/bs-theme-preset-bootswatch.R` for any
+hardcoded theme references that might need updating (e.g.,
+`bs3compat_navbar_defaults()` has a hardcoded BS3 theme list).
+
+### Step 6: Check for redundant patches
+
+If all patches applied cleanly, none are redundant. A patch whose changes
+were upstreamed would fail to apply because the old-state lines wouldn't
+match. Only investigate redundancy if a patch was already rejected.
+
+### Step 7: Report upstream changes and patch edits
+
+Produce a changelog report for the user covering both Bootstrap and Bootswatch
+changes between the old and new versions. Research the changelogs (GitHub
+releases, release blog posts, and/or the CHANGELOG.md in the upstream repos)
+and organize changes into three tiers based on likely impact to bslib and
+Shiny apps:
+
+**Critical** — Changes that directly affect bslib's patched files or Shiny
+component rendering. Examples: Sass variable renames/removals, `color-contrast()`
+algorithm changes, form element markup restructuring, navbar API changes,
+dark mode variable changes.
+
+**Notable** — Changes that affect commonly used Bootstrap features in Shiny
+apps but don't directly conflict with bslib patches. Examples: new utility
+classes, component behavior changes, accessibility improvements, new CSS
+custom properties, JavaScript API changes for components used in Shiny.
+
+**Minor** — Bug fixes, docs changes, or changes to features rarely used in
+Shiny contexts. Examples: RTL fixes, print stylesheet changes, Offcanvas
+edge cases, carousel fixes.
+
+After the categorized changelog, include a summary of all patch edits that
+were required during Step 3, listing each modified patch file with a short
+description of what changed and why (e.g., "updated context for new
+`$nav-underline-link-active-color` variable added upstream").
+
+Also include any new/removed Bootswatch themes (from Step 5) and any
+redundant patches identified (from Step 6) in this report.
+
+### Step 8: Run the full asset pipeline (if not already done)
+
+```bash
+Rscript tools/main.R
+```
+
+This runs `yarn_install.R` plus `download_preset_fonts.R`,
+`update_gfont_info.R`, `expand_variables_article_template.R`, and
+`compile_component_sass.R`.
+
+### Step 9: Run tests and checks
+
+```r
+devtools::test()
+devtools::check()
+```
+
+Expect existing snapshot tests to potentially need updating if HTML
+serialization changed (whitespace-only diffs are safe to accept with
+`testthat::snapshot_accept()`). Focus on whether any *new* failures appear
+that are related to the Bootstrap upgrade.
+
+### Step 10: Visual verification
+
+Test Shiny apps and bslib examples with:
+- Default Bootstrap 5 theme
+- Dark Bootswatch themes (Darkly, Cyborg, Slate, Superhero)
+- Light Bootswatch themes (Flatly, Minty, Lux)
+- Shiny form elements (checkbox, radio, selectize, sliders)
+- Navbar styling
+
+## Key Files
+
+| File | Role |
+|------|------|
+| `inst/package.json` | npm version pins |
+| `R/versions.R` | Auto-generated version constants |
+| `tools/yarn_install.R` | Main build script (~760 lines) |
+| `tools/main.R` | Full asset pipeline runner |
+| `tools/patches/*.patch` | ~59 patch files applied to vendored sources |
+| `inst/lib/bs5/` | Vendored Bootstrap 5 SCSS (patched) |
+| `inst/lib/bsw5/` | Vendored Bootswatch 5 SCSS (patched) |
+| `inst/css-precompiled/` | Pre-compiled CSS output |
+| `R/bs-theme-preset-bootswatch.R` | Theme discovery and configuration |
+
+## Common Upstream Changes That Break Patches
+
+- Variable value changes (e.g., `$table-color: $white` to `initial`)
+- New variables added between existing ones (context line shifts)
+- Removed style blocks (e.g., `.nav-item.open` removed)
+- Stylelint comment additions (e.g., `/* stylelint-disable-line */`)
+- Sass declaration reordering for Dart Sass compatibility
+- `color-contrast()` function changes (WCAG compliance updates)

.claude/skills/bslib-upgrade-bootstrap/references/patch-fixing-guide.md

@@ -0,0 +1,156 @@
+# Patch Fixing Guide
+
+When `yarn_install.R` fails because patches don't apply against a new upstream
+version, use this systematic approach to identify and fix all failing patches.
+
+## Overview
+
+The key insight: `yarn_install.R` stops at the **first** failure, but multiple
+patches may be broken. Fix them all before re-running.
+
+## Step 1: Prepare a clean upstream snapshot
+
+Run the build pipeline up to (but not including) patch application, then save
+the clean state. This gives you unpatched upstream files to work against.
+
+```bash
+# After yarn_install.R fails, save the current inst/lib state
+# (which has vendor prefixes applied but no patches yet)
+mkdir -p /tmp/bslib-clean-upstream
+cp -R inst/lib/bs5 /tmp/bslib-clean-upstream/bs5
+cp -R inst/lib/bsw5 /tmp/bslib-clean-upstream/bsw5
+```
+
+If `yarn_install.R` already partially applied patches before failing, you need
+to re-download clean upstream first. Run just the yarn install + vendor prefix
+steps manually, or delete `inst/lib/` and re-run `yarn_install.R` (it will
+fail again at the same patch, but the files before that patch are clean).
+
+## Step 2: Identify all failing patches
+
+Test every patch sequentially against the clean upstream, applying each one
+so later patches see the cumulative state:
+
+```bash
+# From the repo root, with clean upstream in inst/lib/
+for patch in tools/patches/*.patch; do
+  if git apply --check "$patch" 2>/dev/null; then
+    git apply --whitespace=fix "$patch"
+    echo "OK: $(basename $patch)"
+  else
+    echo "FAIL: $(basename $patch)"
+  fi
+done
+```
+
+Collect the full list of failures before fixing anything.
+
+## Step 3: Fix each failing patch
+
+For each failing patch, the process is:
+
+1. **Read the old patch** to understand what changes it intends to make
+2. **Read the clean upstream file** (from `/tmp/bslib-clean-upstream/`)
+3. **Read the current working file** (which may have earlier patches applied)
+4. **Apply the intended changes manually** to the working file
+5. **Generate a new diff** between clean upstream (with prior patches) and
+   the manually patched version
+6. **Write the updated patch file**
+7. **Verify** with `git apply --check`
+
+### Understanding bslib's patch patterns
+
+Many bslib Bootswatch patches follow these patterns:
+
+- **`body-mix()` function**: Replaces hardcoded `$gray-NNN` references with
+  `body-mix(weight%)` calls that derive grays from `$body-bg` and
+  `$body-color`, enabling dynamic theming
+
+- **`$contrast-bg` / `$contrast-fg`**: Variables derived from
+  `color-contrast()` that replace hardcoded `$white` / `$black`, adapting
+  to light/dark mode
+
+- **Semantic color variables**: Moving `$body-bg`, `$body-color`, `$secondary`,
+  `$light`, `$dark` definitions before other variables so they can be
+  referenced throughout
+
+When upstream changes a value (e.g., `$table-color: $white` becomes
+`$table-color: initial`), the patch's old-context no longer matches. Update
+the old-context to match the new upstream, and ensure the new-context still
+applies the intended bslib transformation.
+
+### File path considerations
+
+Patches reference files by their post-downsizing paths. The `yarn_install.R`
+script restructures vendor libraries before applying patches:
+
+- `bs-colorpicker/dist/js/` becomes `bs-colorpicker/js/`
+- `bs-colorpicker/dist/css/` becomes `bs-colorpicker/css/`
+
+Patches must use the **post-downsizing** paths (e.g., `js/` not `dist/js/`).
+
+### Multiple patches touching the same file
+
+Several patches modify `_variables.scss` in sequence. When regenerating these
+patches, each must be diffed against the state **after all preceding patches
+have been applied**, not against the clean upstream.
+
+Order matters. The alphabetical filename order determines application sequence:
+`009-*` before `011-*` before `016-*` before `021-*` before `023-*` before
+`025-*`.
+
+## Step 4: Parallel patch fixing with subagents
+
+When many patches fail, fix them in parallel using subagents. Group patches
+that are independent (touch different files) into separate agents. Patches
+that touch the same files must be handled sequentially or by the same agent.
+
+Typical groupings:
+- Each `006-bootswatch-{theme}-bs5.patch` is independent (different theme dirs)
+- Core BS5 patches (`009`, `011`, `016`, `021`, `023`, `025`) share
+  `_variables.scss` and must be handled together in sequence
+- Cross-cutting patches (`028`, `031`, `032`, `033`, `034`) can often be
+  handled independently
+
+For each agent, provide:
+1. The failing patch file path
+2. The clean upstream file(s) from `/tmp/bslib-clean-upstream/`
+3. The current working copy of the target file(s)
+4. Instructions to read the old patch, apply intended changes to the new
+   upstream, generate a corrected diff, and verify with `git apply --check`
+
+## Step 5: Full verification
+
+After all patches are fixed, run `yarn_install.R` from scratch:
+
+```bash
+Rscript tools/yarn_install.R
+```
+
+This re-downloads fresh upstream, re-applies vendor prefixes, and applies all
+patches in sequence. Every patch must apply cleanly. If any still fail, repeat
+Steps 3-4 for the remaining failures.
+
+## Troubleshooting
+
+### Patch applies with `--check` but fails in yarn_install.R
+
+The script uses `git apply --reject --whitespace=fix`. Check that:
+- The working tree is clean (no leftover modifications from previous attempts)
+- Earlier patches in the sequence haven't changed
+
+### Hunk offsets but still applies
+
+Lines like `Hunk #1 succeeded at 126 (offset 4 lines)` are fine — git found
+the context at a slightly different line number. The patch still applied
+correctly. Only `.rej` files or non-zero exit codes indicate real failures.
+
+### Vendor prefix validation fails
+
+If `yarn_install.R` fails with "Unknown vendor prefixes introduced by
+Bootstrap's autoprefixer", the new Bootstrap version uses CSS properties that
+need prefixing. Either:
+- Add `add_property_prefixes()` calls in `yarn_install.R` for the new
+  properties
+- Add the property names to the `whitelist` vector if prefixes aren't needed
+  for modern browsers

R/versions.R

@@ -1,5 +1,5 @@
 # Generated by tools/yarn_install.R: do not edit by hand
-version_bs5 <- "5.3.1"
+version_bs5 <- "5.3.8"
 version_bs4 <- "4.6.0"
 version_bs3 <- "3.4.1"
 version_accessibility <- "1.0.6"

inst/lib/bs5/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2011-2023 The Bootstrap Authors
+Copyright (c) 2011-2025 The Bootstrap Authors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal