Forward-ported the deferred decisions and refreshed dependencies on '2.x'.

.ahoy.yml

@@ -43,6 +43,9 @@ commands:
       #;< SERVICE_SEARCH
       export VORTEX_HOST_SOLR_PORT=$(docker compose port search 8983 2>/dev/null | cut -d : -f 2)
       #;> SERVICE_SEARCH
+      #;< STORYBOOK
+      export VORTEX_HOST_STORYBOOK_PORT=$(docker compose port cli ${VORTEX_STORYBOOK_PORT:-6006} 2>/dev/null | cut -d : -f 2)
+      #;> STORYBOOK
       export VORTEX_HOST_SELENIUM_VNC_PORT=$(docker compose port browser 7900 2>/dev/null | cut -d : -f 2)
       export VORTEX_HOST_HAS_SEQUELACE=$(uname -a | grep -i -q darwin && mdfind -name 'Sequel Ace' 2>/dev/null | grep -q "Ace" && echo 1 || true)
       ahoy cli ./vendor/bin/vortex-info "$@"
@@ -233,6 +236,22 @@ commands:
     cmd: |
       ahoy cli "pkill -9 -f grunt" || true
       ahoy cli "cd ${WEBROOT}/themes/custom/${DRUPAL_THEME} && npm run watch"
+
+  #;< STORYBOOK
+  storybook:
+    usage: Start Storybook for component development. Stories are regenerated as their Twig templates change.
+    cmd: |
+      export VORTEX_HOST_STORYBOOK_PORT=$(docker compose port cli ${VORTEX_STORYBOOK_PORT:-6006} 2>/dev/null | cut -d : -f 2)
+      ahoy cli ./vendor/bin/vortex-storybook dev "$@"
+
+  storybook-build:
+    usage: Build the Storybook component library served at /storybook.
+    cmd: ahoy cli ./vendor/bin/vortex-storybook build
+
+  storybook-stories:
+    usage: Generate Storybook stories from Twig templates. Run with "--watch" to regenerate them as they change.
+    cmd: ahoy cli ./vendor/bin/vortex-storybook stories "$@"
+  #;> STORYBOOK
   #;> DRUPAL_THEME
 
   lint:

.circleci/config.yml

@@ -45,7 +45,7 @@ aliases:
       # dockerized stack against the remote Docker engine (see setup_remote_docker).
       # https://circleci.com/developer/images/image/cimg/php
       - image: cimg/php:8.4
-        environment:
+        environment: &runner_environment
           # Set runner timezone via UI to ensure that executed operations use correct timestamps.
           # https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
           TZ: UTC
@@ -232,6 +232,11 @@ jobs:
   # Audit job runs in its own workflow, independently of the commit workflow.
   audit:
     <<: *runner_config
+    docker:
+      # The '-node' variant of the convenience image adds Node.js for the npm
+      # audit.
+      - image: cimg/php:8.4-node
+        environment: *runner_environment
     steps:
       - checkout
       - *load_variables_from_dotenv
@@ -251,8 +256,32 @@ jobs:
 
       - run:
           name: Audit Composer packages
+          when: always
           command: composer audit --locked || [ "${VORTEX_CI_COMPOSER_AUDIT_IGNORE_FAILURE:-0}" -eq 1 ]
 
+      #;< TOOL_NPM
+      # The threshold is passed here rather than in 'package-audit.jsonc', because
+      # audit-ci passes every advisory when no threshold is set.
+      - run:
+          name: Audit npm packages
+          when: always
+          command: |
+            config=()
+            [ -f package-audit.jsonc ] && config=(--config package-audit.jsonc)
+            npx --yes audit-ci@7.1.0 --high --extra-args=--package-lock-only "${config[@]}" || [ "${VORTEX_CI_NPM_AUDIT_IGNORE_FAILURE:-0}" -eq 1 ]
+      #;> TOOL_NPM
+
+      #;< DRUPAL_THEME
+      - run:
+          name: Audit npm packages of the theme
+          when: always
+          command: |
+            dir="${WEBROOT}/themes/custom/${DRUPAL_THEME}"
+            config=()
+            [ -f "${dir}/package-audit.jsonc" ] && config=(--config "${dir}/package-audit.jsonc")
+            npx --yes audit-ci@7.1.0 --high --extra-args=--package-lock-only --directory "${dir}" "${config[@]}" || [ "${VORTEX_CI_NPM_AUDIT_IGNORE_FAILURE:-0}" -eq 1 ]
+      #;> DRUPAL_THEME
+
       #;< CI_GITLEAKS
       # The remote Docker engine has no access to the checkout, so the files
       # are copied into the container.
@@ -386,16 +415,21 @@ jobs:
             #;< DB_FETCH_SOURCE_CONTAINER_REGISTRY
             [ "${CIRCLE_NODE_TOTAL:-1}" -gt 1 ] && [ "${CIRCLE_NODE_INDEX:-0}" -ne 0 ] && export VORTEX_EXPORT_DB_CONTAINER_REGISTRY_PUSH_PROCEED=0
             #;> DB_FETCH_SOURCE_CONTAINER_REGISTRY
-            docker compose exec cli mkdir -p .data && docker compose --progress quiet cp -L .data/db.sql cli:/app/.data/db.sql || true
+            # The 'container_registry' source fetches an image without a dump file.
+            if [ -f .data/db.sql ]; then
+              docker compose exec cli mkdir -p .data
+              docker compose --progress quiet cp -L .data/db.sql cli:/app/.data/db.sql
+            fi
             docker compose exec $(env | cut -f1 -d= | sed 's/^/-e /') -T cli bash -c "VORTEX_PROVISION_POST_OPERATIONS_SKIP=1 ./vendor/bin/vortex-provision"
             #;< DB_FETCH_SOURCE_CONTAINER_REGISTRY
-            grep -q ^VORTEX_DB_IMAGE .env && rm .data/db.sql || true
+            # Database-in-image storage caches the exported image archive instead of the dump.
+            [ -n "${VORTEX_DB_IMAGE:-}" ] && rm -f .data/db.sql || true
             #;> DB_FETCH_SOURCE_CONTAINER_REGISTRY
             ./vendor/bin/vortex-export-db db.sql
             #;< DB_FETCH_SOURCE_CONTAINER_REGISTRY
             if [ -n "${VORTEX_DB_IMAGE:-}" ]; then ./vendor/bin/vortex-push-db-image; fi
             #;> DB_FETCH_SOURCE_CONTAINER_REGISTRY
-            docker compose exec -T cli test -f /app/.data/db.sql && docker compose --progress quiet cp -L cli:/app/.data/db.sql .data/db.sql || true
+            [ -z "${VORTEX_DB_IMAGE:-}" ] && docker compose exec -T cli test -f /app/.data/db.sql && docker compose --progress quiet cp -L cli:/app/.data/db.sql .data/db.sql || true
           no_output_timeout: 30m
 
       # Save the clean DB dump to the cache before the slow dev-dependency

.circleci/vortex-test-common.yml

@@ -36,7 +36,7 @@ aliases:
       # dockerized stack against the remote Docker engine (see setup_remote_docker).
       # https://circleci.com/developer/images/image/cimg/php
       - image: cimg/php:8.4
-        environment:
+        environment: &runner_environment
           # Set runner timezone via UI to ensure that executed operations use correct timestamps.
           # https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
           TZ: UTC
@@ -233,16 +233,21 @@ jobs:
             #;< DB_FETCH_SOURCE_CONTAINER_REGISTRY
             [ "${CIRCLE_NODE_TOTAL:-1}" -gt 1 ] && [ "${CIRCLE_NODE_INDEX:-0}" -ne 0 ] && export VORTEX_EXPORT_DB_CONTAINER_REGISTRY_PUSH_PROCEED=0
             #;> DB_FETCH_SOURCE_CONTAINER_REGISTRY
-            docker compose exec cli mkdir -p .data && docker compose --progress quiet cp -L .data/db.sql cli:/app/.data/db.sql || true
+            # The 'container_registry' source fetches an image without a dump file.
+            if [ -f .data/db.sql ]; then
+              docker compose exec cli mkdir -p .data
+              docker compose --progress quiet cp -L .data/db.sql cli:/app/.data/db.sql
+            fi
             docker compose exec $(env | cut -f1 -d= | sed 's/^/-e /') -T cli bash -c "VORTEX_PROVISION_POST_OPERATIONS_SKIP=1 ./vendor/bin/vortex-provision"
             #;< DB_FETCH_SOURCE_CONTAINER_REGISTRY
-            grep -q ^VORTEX_DB_IMAGE .env && rm .data/db.sql || true
+            # Database-in-image storage caches the exported image archive instead of the dump.
+            [ -n "${VORTEX_DB_IMAGE:-}" ] && rm -f .data/db.sql || true
             #;> DB_FETCH_SOURCE_CONTAINER_REGISTRY
             ./vendor/bin/vortex-export-db db.sql
             #;< DB_FETCH_SOURCE_CONTAINER_REGISTRY
             if [ -n "${VORTEX_DB_IMAGE:-}" ]; then ./vendor/bin/vortex-push-db-image; fi
             #;> DB_FETCH_SOURCE_CONTAINER_REGISTRY
-            docker compose exec -T cli test -f /app/.data/db.sql && docker compose --progress quiet cp -L cli:/app/.data/db.sql .data/db.sql || true
+            [ -z "${VORTEX_DB_IMAGE:-}" ] && docker compose exec -T cli test -f /app/.data/db.sql && docker compose --progress quiet cp -L cli:/app/.data/db.sql .data/db.sql || true
           no_output_timeout: 30m
 
       # Save the clean DB dump to the cache before the slow dev-dependency
@@ -466,12 +471,15 @@ jobs:
           name: Export DB after fetch
           command: |
             [ ! -f /tmp/fetch-db-success ] && echo "==> Database fetch semaphore file is missing. DB export will not proceed." && exit 0
-            docker compose exec cli mkdir -p .data && docker compose cp -L .data/db.sql cli:/app/.data/db.sql || true
+            if [ -f .data/db.sql ]; then
+              docker compose exec cli mkdir -p .data
+              docker compose cp -L .data/db.sql cli:/app/.data/db.sql
+            fi
             docker compose exec $(env | cut -f1 -d= | sed 's/^/-e /') -T cli bash -c "VORTEX_PROVISION_POST_OPERATIONS_SKIP=1 ./vendor/bin/vortex-provision"
-            grep -q ^VORTEX_DB_IMAGE .env && rm .data/db.sql || true
+            [ -n "${VORTEX_DB_IMAGE:-}" ] && rm -f .data/db.sql || true
             ./vendor/bin/vortex-export-db db.sql
             if [ -n "${VORTEX_DB_IMAGE:-}" ]; then ./vendor/bin/vortex-push-db-image; fi
-            docker compose exec -T cli test -f /app/.data/db.sql && docker compose cp -L cli:/app/.data/db.sql .data/db.sql || true
+            [ -z "${VORTEX_DB_IMAGE:-}" ] && docker compose exec -T cli test -f /app/.data/db.sql && docker compose cp -L cli:/app/.data/db.sql .data/db.sql || true
           no_output_timeout: 30m
 
   vortex-dev-didi-build-fi:
@@ -526,12 +534,15 @@ jobs:
           name: Export DB after fetch
           command: |
             [ ! -f /tmp/fetch-db-success ] && echo "==> Database fetch semaphore file is missing. DB export will not proceed." && exit 0
-            docker compose exec cli mkdir -p .data && docker compose cp -L .data/db.sql cli:/app/.data/db.sql || true
+            if [ -f .data/db.sql ]; then
+              docker compose exec cli mkdir -p .data
+              docker compose cp -L .data/db.sql cli:/app/.data/db.sql
+            fi
             docker compose exec $(env | cut -f1 -d= | sed 's/^/-e /') -T cli bash -c "VORTEX_PROVISION_POST_OPERATIONS_SKIP=1 ./vendor/bin/vortex-provision"
-            grep -q ^VORTEX_DB_IMAGE .env && rm .data/db.sql || true
+            [ -n "${VORTEX_DB_IMAGE:-}" ] && rm -f .data/db.sql || true
             ./vendor/bin/vortex-export-db db.sql
             if [ -n "${VORTEX_DB_IMAGE:-}" ]; then ./vendor/bin/vortex-push-db-image; fi
-            docker compose exec -T cli test -f /app/.data/db.sql && docker compose cp -L cli:/app/.data/db.sql .data/db.sql || true
+            [ -z "${VORTEX_DB_IMAGE:-}" ] && docker compose exec -T cli test -f /app/.data/db.sql && docker compose cp -L cli:/app/.data/db.sql .data/db.sql || true
           no_output_timeout: 30m
 
   vortex-dev-didi-build-ii:

.docker/config/README.md

@@ -1,3 +1,4 @@
-This directory contains additional configuration for each container service.
+This directory contains additional configuration for each container
+service.
 
 Place your custom configuration in the directory named after the service.

.docker/config/nginx/maintenance.conf

@@ -0,0 +1,29 @@
+# Maintenance page.
+#
+# Answers every request with HTTP status 503 and the static maintenance page
+# while VORTEX_WEBSERVER_MAINTENANCE_MODE is set to 1, so no request reaches
+# PHP.
+#
+# The image entrypoint replaces the placeholder below with the variable's
+# value when the container starts, so a changed value needs a new container.
+
+set $vortex_maintenance "${VORTEX_WEBSERVER_MAINTENANCE_MODE:-0}";
+
+# nginx runs these directives again for the internal redirect to the error
+# page, so the page URI is exempt.
+if ($uri = /__maintenance.html) {
+  set $vortex_maintenance 0;
+}
+
+if ($vortex_maintenance = 1) {
+  return 503;
+}
+
+# A URI error page makes nginx serve the page as GET, so POST and other
+# methods get the page instead of a 405 response.
+error_page 503 /__maintenance.html;
+
+location = /__maintenance.html {
+  internal;
+  alias /etc/nginx/html/maintenance.html;
+}

.docker/config/nginx/maintenance.html

@@ -0,0 +1,60 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Down for maintenance | YOURSITE</title>
+  <style>
+    :root {
+      color-scheme: light dark;
+      --background: #f6f7f9;
+      --text: #1d2127;
+      --muted: #5a6270;
+    }
+
+    @media (prefers-color-scheme: dark) {
+      :root {
+        --background: #15181d;
+        --text: #eceef1;
+        --muted: #a3abb8;
+      }
+    }
+
+    body {
+      box-sizing: border-box;
+      display: grid;
+      place-items: center;
+      min-height: 100vh;
+      margin: 0;
+      padding: 1.5rem;
+      background: var(--background);
+      color: var(--text);
+      font-family: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+      line-height: 1.5;
+      text-align: center;
+    }
+
+    main {
+      max-width: 36rem;
+    }
+
+    h1 {
+      margin: 0 0 1rem;
+      font-size: clamp(1.75rem, 5vw, 2.5rem);
+      line-height: 1.2;
+    }
+
+    p {
+      margin: 0;
+      color: var(--muted);
+      font-size: 1.125rem;
+    }
+  </style>
+</head>
+<body>
+  <main>
+    <h1>We'll be back soon</h1>
+    <p>YOURSITE is down for maintenance. Please check back shortly.</p>
+  </main>
+</body>
+</html>

.docker/config/nginx/storybook.conf

@@ -0,0 +1,32 @@
+# Storybook component library.
+#
+# Serves the static Storybook application and keeps the Drupal story render
+# route reachable underneath the same path prefix.
+
+# The Storybook module renders every story through Drupal.
+location ^~ /storybook/stories/ {
+  try_files $uri @drupal;
+}
+
+# A relative Location keeps the scheme and host the client used behind a
+# TLS-terminating proxy.
+location = /storybook {
+  absolute_redirect off;
+  return 301 /storybook/;
+}
+
+# Storybook builds the static application into the theme's 'storybook-static'
+# directory. Its entry files keep their names across builds, so browsers
+# revalidate them to pick up a rebuilt library.
+location ^~ /storybook/ {
+  alias /app/web/themes/custom/your_site_theme/storybook-static/;
+  index index.html;
+  expires -1;
+}
+
+# The Storybook development server runs on its own origin and loads theme
+# fonts from this one.
+location ~* ^/themes/custom/.+\.(woff2?|ttf|otf|eot)$ {
+  add_header Access-Control-Allow-Origin '*' always;
+  try_files $uri @drupal;
+}

.docker/nginx-drupal.dockerfile

@@ -19,6 +19,13 @@ RUN apk add --no-cache tzdata
 
 COPY ./.docker/config/nginx/redirects-map.conf /etc/nginx/redirects-map.conf
 
+COPY ./.docker/config/nginx/maintenance.conf /etc/nginx/conf.d/drupal/server_prepend-maintenance.conf
+COPY ./.docker/config/nginx/maintenance.html /etc/nginx/html/maintenance.html
+
+#;< STORYBOOK
+COPY ./.docker/config/nginx/storybook.conf /etc/nginx/conf.d/drupal/location_append-storybook.conf
+#;> STORYBOOK
+
 RUN fix-permissions /etc/nginx
 
 COPY --from=cli /app /app

.docker/scripts/README.md

@@ -1,2 +1,2 @@
-This directory contains custom scripts to run in container services during
-image build or container runtime.
+This directory contains custom scripts that container services run during
+the image build or at container runtime.

.dockerignore

@@ -48,6 +48,12 @@ web/themes/**/node_modules
 # Theme build assets are compiled during the image build.
 web/themes/**/build
 
+#;< STORYBOOK
+# Storybook stories and application are compiled during provisioning.
+web/themes/**/*.stories.json
+web/themes/**/storybook-static
+#;> STORYBOOK
+
 # Caches, data, logs and temporary artifacts.
 **/.artifacts
 **/.data

.env

@@ -69,6 +69,11 @@ DRUPAL_MAINTENANCE_THEME=your_site_theme
 VORTEX_FRONTEND_BUILD_SKIP=0
 #;> DRUPAL_THEME
 
+#;< STORYBOOK
+# Skip building the Storybook component library during provisioning.
+DRUPAL_STORYBOOK_SKIP=0
+#;> STORYBOOK
+
 #;< MODULE_STAGE_FILE_PROXY
 # Stage file proxy origin.
 #;< MODULE_SHIELD

.github/PULL_REQUEST_TEMPLATE.dist.md

@@ -3,7 +3,7 @@
 - [ ] Subject includes ticket number as `[#123] Verb in past tense.`
 - [ ] Ticket number `#123` added to description
 - [ ] Added context in `Changed` section
-- [ ] Self-reviewed code and commented in commented complex areas.
+- [ ] Self-reviewed the code and commented complex areas.
 - [ ] Added tests for fix/feature.
 - [ ] Relevant tests run and passed locally.