RHOAIENG-24181: chore(jupyter/utils/addons): tree-shake the PatternFly CSS used to add spinner to JupyterLab-based workbenches (#1024)

* fixup, node 22 compatibility

* fixup, remove linter for tsconfig.json, it is making unreasonable demands

Author: jiridanek

.github/workflows/code-quality.yaml

@@ -82,11 +82,13 @@ jobs:
       - name: Validate JSON files (just syntax)
         id: validate-json-files
         run: |
+          set -Eeuxo pipefail
+
           type json_verify || sudo apt-get -y install yajl-tools
           shopt -s globstar
           ret_code=0
           echo "-- Checking a regular '*.json' files"
-          for f in **/*.json; do echo "Checking: '${f}"; echo -n "  > "; cat $f | json_verify || ret_code=1; done
+          for f in **/*.json; do echo "Checking: '${f}"; echo -n "  > "; [[ "$(basename "$f")" == "tsconfig.json" ]] && echo "Skipping ${f}" && continue; cat $f | json_verify || ret_code=1; done
           echo "-- Checking a 'Pipfile.lock' files"
           for f in **/Pipfile.lock; do echo "Checking: '${f}"; echo -n "  > "; cat $f | json_verify || ret_code=1; done
           echo "-- Checking a '*.ipynb' Jupyter notebook files"

jupyter/utils/addons/.dockerignore

@@ -0,0 +1,11 @@
+# Dependencies
+node_modules/
+.pnpm-store/
+
+# Logs
+logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+yarn-debug.log*
+yarn-error.log*

jupyter/utils/addons/.gitignore

@@ -0,0 +1,11 @@
+# Dependencies
+node_modules/
+.pnpm-store/
+
+# Logs
+logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+yarn-debug.log*
+yarn-error.log*

jupyter/utils/addons/README.md

@@ -0,0 +1,65 @@
+# Jupyter Addons
+
+This package contains addons for JupyterLab workbenches.
+
+## Features / Bugs solved here
+
+(second level bullet points indicate features/bugs that appeared due to the first level bullet point solution)
+
+* [RHOAIENG-11156](https://issues.redhat.com/browse/RHOAIENG-11156) - Better feedback for JupyterLab-based workbenches initial load (improve time to first contentful paint)
+  * [RHOAIENG-20553](https://issues.redhat.com/browse/RHOAIENG-20553) - CSS is broken when loading the TensorBoard extension
+
+## Usage
+
+The project uses PurgeCSS to tree-shake the PatternFly CSS file, removing unused styles.
+The bundled output is generated in the `dist/` directory.
+
+Code generation (generated code in `dist/` is committed to the repository)
+
+```bash
+pnpm install
+pnpm build
+```
+
+Image build (in a Dockerfile)
+
+```Dockerfile
+ARG JUPYTER_REUSABLE_UTILS=jupyter/utils
+WORKDIR /opt/app-root/bin
+COPY ${JUPYTER_REUSABLE_UTILS} utils/
+RUN # Apply JupyterLab addons \
+    /opt/app-root/bin/utils/addons/apply.sh
+```
+
+## Development
+
+### Example
+
+Interactive demo of the spinner functionality:
+
+1. Build the project: `pnpm build` or `pnpm build:dev`
+2. Open `dist/index.html` in a browser
+3. Clicking button simulates JupyterLab finished loading (spinner disappears)
+
+### Build Process
+
+The project uses webpack to bundle the JavaScript files and tree-shake the CSS:
+
+- `pnpm build`: Creates a production build with minification
+- `pnpm build:dev`: Creates a development build with source maps
+- `pnpm build:clean`: Cleans the output directory and cache before building
+- `pnpm clean`: Removes the dist directory and build cache
+- `pnpm start`: Starts the webpack development server and opens `dist/index.html` (test page) in a browser
+- `pnpm watch`: Watches for file changes and rebuilds automatically
+- `pnpm test`: Runs the test-build.sh script to report tree-shaking effectiveness
+
+## Files
+
+- `apply.sh`: Script to apply the addons to a JupyterLab during Dockerfile build
+- `partial-head.html`, `partial-body.html`: HTML content to be injected into the head section of JupyterLab
+- `cleanup-webpack-plugin.mts`: Custom webpack plugin for asset cleanup (removes unnecessary files)
+- `webpack.config.ts`: Webpack configuration with enhanced tree-shaking
+- `dist/pf.css`: Tree-shaken PatternFly CSS file with only the necessary styles
+- `src/index.ejs`: Template for the example page built into `dist/index.html`
+- `dist/index.html`: Example HTML file demonstrating usage of the output
+- `test-build.sh`: Script to verify the tree-shaking effectiveness

jupyter/utils/addons/apply.sh

@@ -5,13 +5,12 @@
 
 script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
-pf_url="https://unpkg.com/@patternfly/[email protected]/patternfly-no-globals.css"
-
 static_dir="/opt/app-root/share/jupyter/lab/static"
 index_file="$static_dir/index.html"
 
 head_file="$script_dir/partial-head.html"
 body_file="$script_dir/partial-body.html"
+css_file="$script_dir/dist/pf.css"
 
 if [ ! -f "$index_file" ]; then
   echo "File '$index_file' not found"
@@ -28,7 +27,17 @@ if [ ! -f "$body_file" ]; then
   exit 1
 fi
 
-curl -o "$static_dir/pf.css" "$pf_url"
+if [ ! -f "$css_file" ]; then
+  echo "Tree-shaken CSS file not found. Building it now..."
+  cd "$script_dir" && pnpm build
+  if [ ! -f "$css_file" ]; then
+    echo "Failed to build CSS file"
+    exit 1
+  fi
+fi
+
+# Copy the tree-shaken CSS file to the static directory
+cp "$css_file" "$static_dir/pf.css"
 
 head_content=$(tr -d '\n' <"$head_file" | sed 's/@/\\@/g')
 body_content=$(tr -d '\n' <"$body_file" | sed 's/@/\\@/g')

jupyter/utils/addons/cleanup-webpack-plugin.ts

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: LicenseRef-Not-Copyrightable
+import webpack from 'webpack';
+import type { Compilation, Compiler, WebpackPluginInstance } from 'webpack';
+
+interface CleanupPluginOptions {
+    patterns: RegExp[];
+}
+
+class WebpackCleanupPlugin implements WebpackPluginInstance {
+    private options: CleanupPluginOptions;
+
+    constructor(options: CleanupPluginOptions) {
+        this.options = {
+            patterns: options.patterns || [],
+        };
+    }
+
+    apply(compiler: Compiler) {
+        compiler.hooks.thisCompilation.tap('WebpackCleanupPlugin', (compilation: Compilation) => {
+            // Process assets to remove files based on filename patterns
+            compilation.hooks.processAssets.tap(
+                {
+                    name: 'WebpackCleanupPlugin',
+                    stage: webpack.Compilation.PROCESS_ASSETS_STAGE_ADDITIONS,
+                },
+                (assets: Compilation['assets']) => {
+                    // Remove files based on filename patterns
+                    for (const filename in assets) {
+                        if (this.options.patterns.some(pattern => pattern.test(filename))) {
+                            compilation.deleteAsset(filename);
+                        }
+                    }
+                },
+            );
+        });
+    }
+}
+
+export default WebpackCleanupPlugin;

jupyter/utils/addons/dist/index.html

@@ -0,0 +1,10 @@
+<!doctype html><html lang="en"><head><meta charset="utf-8"/><title>Example spinner page</title><link rel="stylesheet" href="./pf.css"/><style>:where(html,body){height:100%}#loading-container{width:100%;height:100%;display:flex;align-items:center;justify-content:center}</style></head><body><p>Check the following</p><ol><li>the spinner is shown</li><li>the spinner is not too thin at the beginning of animation (missing CSS manifested this way)</li><li>if you scroll down as much as possible, the spinner is centered vertically and horizontally</li><li>the spinner is not shown after the button is clicked</li></ol><button>Finish loading</button><script>function htmlToNode(html) {
+        const template = document.createElement('template');
+        template.innerHTML = html;
+        return template.content.firstChild;
+    }
+    document.querySelector('button').addEventListener('click', function () {
+        document.querySelector('button').replaceWith(
+            htmlToNode(`<div class="lm-Widget jp-LabShell" id="main">Jupyter is here.</div>`)
+        );
+    });</script><div id="loading-container"><svg class="pf-v6-c-spinner" role="progressbar" viewBox="0 0 100 100" aria-label="Loading..."><circle class="pf-v6-c-spinner__path" cx="50" cy="50" r="45" fill="none"/></svg></div><script>function checkForTargetElement(){const e=document.querySelector(".lm-Widget.jp-LabShell#main"),t=document.getElementById("loading-container");e&&t?t.remove():requestAnimationFrame(checkForTargetElement)}requestAnimationFrame(checkForTargetElement)</script></body></html>

jupyter/utils/addons/dist/pf.css

@@ -0,0 +1,75 @@
+@charset "UTF-8";
+
+:root {
+  --pf-t--color--blue--50: #0066cc;
+  --pf-t--global--icon--size--400: 3.5rem;
+  --pf-t--global--color--brand--200: var(--pf-t--color--blue--50);
+  --pf-t--global--icon--size--2xl: var(--pf-t--global--icon--size--400);
+  --pf-t--global--color--brand--default: var(--pf-t--global--color--brand--200);
+  --pf-t--global--icon--color--brand--default: var(--pf-t--global--color--brand--default);
+}
+
+:root {
+}
+
+.pf-v6-c-spinner {
+  --pf-v6-c-spinner--diameter: var(--pf-t--global--icon--size--2xl);
+  --pf-v6-c-spinner--Width: var(--pf-v6-c-spinner--diameter);
+  --pf-v6-c-spinner--Height: var(--pf-v6-c-spinner--diameter);
+  --pf-v6-c-spinner--Color: var(--pf-t--global--icon--color--brand--default);
+  --pf-v6-c-spinner--AnimationDuration: 1.4s;
+  --pf-v6-c-spinner--AnimationTimingFunction: linear;
+  --pf-v6-c-spinner--StrokeWidth: 10;
+  --pf-v6-c-spinner__path--StrokeWidth: var(--pf-v6-c-spinner--StrokeWidth);
+  --pf-v6-c-spinner__path--AnimationTimingFunction: ease-in-out;
+  --pf-v6-c-spinner--m-sm--diameter: var(--pf-t--global--icon--size--md);
+  --pf-v6-c-spinner--m-md--diameter: var(--pf-t--global--icon--size--lg);
+  --pf-v6-c-spinner--m-lg--diameter: var(--pf-t--global--icon--size--xl);
+  --pf-v6-c-spinner--m-xl--diameter: var(--pf-t--global--icon--size--2xl);
+  --pf-v6-c-spinner--m-inline--diameter: 1em;
+}
+
+.pf-v6-c-spinner {
+  width: var(--pf-v6-c-spinner--Width);
+  height: var(--pf-v6-c-spinner--Height);
+  overflow: hidden;
+  animation: pf-v6-c-spinner-animation-rotate calc(var(--pf-v6-c-spinner--AnimationDuration) * 2) var(--pf-v6-c-spinner--AnimationTimingFunction) infinite;
+}
+
+.pf-v6-c-spinner__path {
+  width: 100%;
+  height: 100%;
+  stroke: var(--pf-v6-c-spinner--Color);
+  stroke-dasharray: 283;
+  stroke-dashoffset: 280;
+  stroke-linecap: round;
+  stroke-width: var(--pf-v6-c-spinner--StrokeWidth);
+  transform-origin: 50% 50%;
+  animation: pf-v6-c-spinner-animation-dash var(--pf-v6-c-spinner--AnimationDuration) var(--pf-v6-c-spinner__path--AnimationTimingFunction) infinite;
+}
+
+@keyframes pf-v6-c-spinner-animation-rotate {
+  0% {
+    transform: rotate(0deg);
+  }
+  100% {
+    transform: rotate(360deg);
+  }
+}
+@keyframes pf-v6-c-spinner-animation-dash {
+  0% {
+    stroke-dashoffset: 280;
+    transform: rotate(0);
+  }
+  15% {
+    stroke-width: calc(var(--pf-v6-c-spinner__path--StrokeWidth) - 4);
+  }
+  40% {
+    stroke-dasharray: 220;
+    stroke-dashoffset: 150;
+  }
+  100% {
+    stroke-dashoffset: 280;
+    transform: rotate(720deg);
+  }
+}

jupyter/utils/addons/package.json5

@@ -0,0 +1,41 @@
+// https://pnpm.io/package_json
+{
+  type: "module",
+  private: true,
+  name: 'jupyter-utils-addons',
+  version: '1.0.0',
+  description: 'Addons for JupyterLab workbenches',
+  license: 'Apache-2.0',
+  scripts: {
+    test: './test-build.sh',
+    build: 'webpack --mode production',
+    'build:dev': 'webpack --mode development',
+    start: 'webpack serve --open',
+    watch: 'webpack --watch',
+    clean: 'rm -rf dist .cache',
+    'build:clean': 'pnpm clean && pnpm build',
+  },
+  dependencies: {
+    '@patternfly/patternfly': '6.0.0',
+  },
+  devDependencies: {
+    // webpack to minify css file
+    webpack: '^5.99.6',
+    'webpack-cli': '^6.0.1',
+    'webpack-dev-server': '^5.2.1',
+
+    // plugins for webpack
+    'css-loader': '^7.1.2',
+    'html-loader': '^5.1.0',
+    'html-webpack-plugin': '^5.6.3',
+    'mini-css-extract-plugin': '^2.9.2',
+    'purgecss-webpack-plugin': '^7.0.2',
+
+    // https://webpack.js.org/configuration/configuration-languages/#typescript,
+    'ts-node': '^10.9.2',
+    typescript: '^5.8.3',
+    '@types/node': '^22.14.1',
+    '@types/webpack': '^5.28.5'
+  },
+  // "packageManager": "[email protected]" // forces install of a precise version, so annoying
+}