Show coloured progress in a responsive homepage terminal

Author: wolph

docs/_ext/demo.py

@@ -174,5 +174,6 @@ def setup(app: Sphinx) -> dict[str, typing.Any]:
     app.add_css_file('vendor/xterm.css')
     app.add_css_file('livecode/livecode.css')
     app.add_js_file('vendor/xterm.js')
+    app.add_js_file('vendor/addon-fit.js')
     app.add_js_file('livecode/livecode.js')
     return {'parallel_read_safe': True, 'parallel_write_safe': True}

docs/_static/demos/homepage-quickstart.svg

@@ -30,6 +30,7 @@
 
 .demo-controls {
   display: flex;
+  flex-wrap: wrap;
   align-items: center;
   gap: 0.75rem;
   padding: 0.5rem 0.75rem;
@@ -73,3 +74,7 @@
   padding: 0.5rem;
   overflow-x: auto;
 }
+
+.demo-terminal .xterm-viewport {
+  overflow-y: auto;
+}

docs/_static/livecode/livecode.css

@@ -123,6 +123,29 @@ function keepHighlightedHomepageSource(container, editor, controls, source) {
   controls.append(edit);
 }
 
+/**
+ * @param {Terminal} terminal
+ * @param {HTMLElement} host
+ * @returns {() => void}
+ */
+function fitTerminalWidth(terminal, host) {
+  /** @type {FitAddon.FitAddon} */
+  const addon = new FitAddon.FitAddon();
+  terminal.loadAddon(addon);
+  /** @type {() => void} */
+  const fit = () => {
+    /** @type {{cols: number, rows: number} | undefined} */
+    const dimensions = addon.proposeDimensions();
+    if (dimensions && dimensions.cols !== terminal.cols) {
+      terminal.resize(dimensions.cols, terminal.rows);
+    }
+  };
+  /** @type {ResizeObserver} */
+  const observer = new ResizeObserver(fit);
+  observer.observe(host);
+  return fit;
+}
+
 function createPanel(container, source) {
   const editor = document.createElement('textarea');
   editor.className = 'demo-editor';
@@ -143,6 +166,9 @@ function createPanel(container, source) {
 
   const screen = document.createElement('div');
   screen.className = 'demo-terminal';
+  /** @type {HTMLDivElement} */
+  const terminalHost = document.createElement('div');
+  screen.append(terminalHost);
 
   const controls = document.createElement('div');
   controls.className = 'demo-controls';
@@ -153,12 +179,14 @@ function createPanel(container, source) {
 
   const terminal = new Terminal({
     cols: COLUMNS,
-    rows: 12,
+    rows: container.closest('.home-quickstart') ? 3 : 12,
     convertEol: true,
     fontSize: 13,
     theme: {background: '#101418', foreground: '#d6e2ef'},
   });
-  terminal.open(screen);
+  terminal.open(terminalHost);
+  /** @type {() => void} */
+  const fitWidth = fitTerminalWidth(terminal, terminalHost);
 
   const panel = {
     terminal,
@@ -195,6 +223,8 @@ function createPanel(container, source) {
       panel.setStatus('idle');
       return;
     }
+    await new Promise(resolve => requestAnimationFrame(resolve));
+    fitWidth();
     panel.setStatus('ready');
     timeoutHandle = setTimeout(() => {
       terminal.write('\r\n\x1b[33mStopped after 30 seconds.\x1b[0m\r\n');
@@ -204,7 +234,7 @@ function createPanel(container, source) {
     worker.postMessage({
       type: 'run',
       code: editor.value,
-      columns: COLUMNS,
+      columns: terminal.cols,
     });
   });
 
@@ -224,7 +254,7 @@ const NON_RUNNABLE_DEMOS = new Set([
 ]);
 
 document.addEventListener('DOMContentLoaded', () => {
-  if (typeof Terminal === 'undefined') return;
+  if (typeof Terminal === 'undefined' || typeof FitAddon === 'undefined') return;
   for (const container of document.querySelectorAll('.demo-run')) {
     if (NON_RUNNABLE_DEMOS.has(container.dataset.demo)) {
       container.textContent =

docs/_static/livecode/livecode.js

@@ -0,0 +1,19 @@
+Copyright (c) 2019, The xterm.js authors (https://github.com/xtermjs/xterm.js)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

docs/_static/vendor/LICENSE-addon-fit.txt

@@ -3,6 +3,7 @@
 | File | Source | Version | License |
 | --- | --- | --- | --- |
 | `xterm.js`, `xterm.css` | `@xterm/xterm` | 5.5.0 | MIT (`LICENSE-xterm.txt`) |
+| `addon-fit.js`, `addon-fit.js.map` | `@xterm/addon-fit` | 0.10.0 | MIT (`LICENSE-addon-fit.txt`) |
 
 Update (bump the version in both commands and this table):
 
@@ -14,3 +15,13 @@ cp package/css/xterm.css docs/_static/vendor/xterm.css
 cp package/LICENSE docs/_static/vendor/LICENSE-xterm.txt
 rm -rf package xterm-xterm-5.5.0.tgz
 ```
+
+Update the matching terminal sizing addon:
+
+```bash
+npm pack @xterm/addon-fit@0.10.0
+tar -xzf xterm-addon-fit-0.10.0.tgz
+cp package/lib/addon-fit.js package/lib/addon-fit.js.map docs/_static/vendor/
+cp package/LICENSE docs/_static/vendor/LICENSE-addon-fit.txt
+rm -rf package xterm-addon-fit-0.10.0.tgz
+```

docs/_static/vendor/README.md

@@ -57,6 +57,9 @@ def svg_path(self) -> pathlib.Path:
 
 
 DEMOS: tuple[Demo, ...] = (
+    Demo(
+        'homepage/quickstart', 'A percentage and a coloured bar', term_width=60
+    ),
     Demo('howto/colors', 'Fixed and gradient bar colors'),
     Demo('howto/custom-widget', 'The current job phase', term_width=60),
     Demo(

docs/_static/vendor/addon-fit.js

@@ -0,0 +1 @@
+"""Examples for the documentation homepage."""