webui: add tooling to update the Bootstrap assets

src/webui/bootstrap/.gitignore

@@ -0,0 +1,2 @@
+node_modules
+package-lock.json

src/webui/bootstrap/README.md

@@ -0,0 +1,32 @@
+# WebUI Bootstrap assets
+
+The WebUI loads [Bootstrap](https://getbootstrap.com/) 5 from
+`src/webui/www/webui`:
+
+| File | Source |
+| --- | --- |
+| `js/extern/bootstrap.bundle.min.js` (+ `.map`) | copied unmodified from the `bootstrap` npm package (includes Popper) |
+| `css/extern/main.min.css` (+ `.map`) | compiled from `scss/main.scss`, which imports only the Bootstrap parts the WebUI needs and adds the WebUI colors |
+| `css/extern/hmBootstrap.css` | hand-written; reverts Bootstrap defaults that conflict with the existing WebUI styles |
+
+This directory holds the tooling to regenerate the first two. It is not
+installed into the firmware image (only `src/webui/www` and
+`src/webui/rega/www` are).
+
+## Updating Bootstrap
+
+1. Set the new versions in `package.json` (exact versions, no ranges).
+   Use the Sass version the Bootstrap release itself is built with (see its
+   `package.json`); newer Dart Sass releases emit many deprecation warnings
+   for Bootstrap 5.3.
+2. Run `./update.sh` (needs Node.js with npm and access to the npm registry).
+   It installs the packages into `node_modules`, copies the bundle and
+   recompiles `main.min.css` and its source map.
+3. Check `scss/main.scss` against the release notes of the new version, for
+   example new Sass maps that the WebUI colors have to extend.
+4. Review the diff of the generated files and check the WebUI pages that use
+   Bootstrap (for example the DutyCycle and CarrierSense bars).
+
+`node_modules` and `package-lock.json` are not committed. With the versions
+in `package.json` unchanged, `./update.sh` reproduces the committed files
+byte for byte.

src/webui/bootstrap/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "webui-bootstrap",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Bootstrap assets of the WebUI (see README.md and update.sh)",
+  "author": "ptweety",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@popperjs/core": "2.11.8",
+    "bootstrap": "5.3.8"
+  },
+  "devDependencies": {
+    "sass": "1.78.0"
+  }
+}

src/webui/bootstrap/update.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+#
+# Regenerates the Bootstrap assets of the WebUI from the versions pinned in
+# package.json:
+#
+#   www/webui/js/extern/bootstrap.bundle.min.js(.map)  copied from bootstrap
+#   www/webui/css/extern/main.min.css(.map)            compiled from
+#                                                      www/webui/scss/main.scss
+#
+# Requires Node.js with npm and network access to the npm registry.
+
+set -o errexit
+set -o nounset
+set -o pipefail
+
+tooling=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
+webui="${tooling}/../www/webui"
+temporary=$(mktemp -d)
+trap 'rm -rf "$temporary"' EXIT
+
+cd "$tooling"
+npm install --no-audit --no-fund
+
+cp node_modules/bootstrap/dist/js/bootstrap.bundle.min.js \
+   node_modules/bootstrap/dist/js/bootstrap.bundle.min.js.map \
+   "${webui}/js/extern/"
+
+# main.scss imports Bootstrap from ../node_modules, and the source map refers
+# to the sources relative to css/extern. Compile in a copy of the webui layout
+# with node_modules next to scss/ so that both stay unchanged.
+mkdir -p "${temporary}/webui/scss" "${temporary}/webui/css/extern"
+cp "${webui}/scss/main.scss" "${temporary}/webui/scss/"
+ln -s "${tooling}/node_modules" "${temporary}/webui/node_modules"
+(cd "${temporary}/webui" && \
+  "${tooling}/node_modules/.bin/sass" --style=compressed \
+    scss/main.scss css/extern/main.min.css)
+cp "${temporary}/webui/css/extern/main.min.css" \
+   "${temporary}/webui/css/extern/main.min.css.map" \
+   "${webui}/css/extern/"
+
+echo "bootstrap $(node -p 'require("./node_modules/bootstrap/package.json").version')," \
+     "sass $(node_modules/.bin/sass --version)"

src/webui/www/webui/scss/main.scss

@@ -1,8 +1,8 @@
 // webui-main.scss
 
-// compile it on the command line as follows::after
-// cd /www/webui
-// ./node_modules/.bin/sass --style=compressed scss/main.scss css/extern/main.min.css
+// Compiled into css/extern/main.min.css by src/webui/bootstrap/update.sh
+// in the OpenCCU-Base repository (see src/webui/bootstrap/README.md).
+//
 
 // 0. Include any default variable overrides here (though functions won't be available)