@arcblock/terminal 3.1.8 → 3.1.10

package/LICENSE

@@ -1,4 +1,4 @@
-Copyright 2018-2022 ArcBlock
+Copyright 2018-2025 ArcBlock
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

package/README.md

@@ -1,19 +1,144 @@
 ![@arcblock/terminal](https://www.arcblock.io/.netlify/functions/badge/?text=terminal)
 
-> Terminal Player is a react wrapper for `xterm` allowing you to easily render a terminal in the browser.
+> Terminal Player is a React component for playing back terminal recordings in the browser, built on top of `xterm.js`. Perfect for creating interactive terminal demos, tutorials, and documentation.
 
-## Usage
+## Features
+
+- 🎬 **Playback Controls**: Play, pause, seek, and loop terminal recordings
+- 🎨 **Customizable Themes**: Full terminal color theme support
+- 📱 **Responsive Design**: Automatically adapts to container size
+- ⚡ **Performance**: Optimized for smooth playback of long recordings
+- 🔧 **Easy Integration**: Simple React component API
+- 📹 **asciinema Compatible**: Works with standard `.cast` recording format
+
+## Installation
 
 ```shell
 yarn add @arcblock/terminal
 ```
 
-Then:
+## Quick Start
+
+### Basic Usage
 
 ```javascript
-import Terminal from '@arcblock/terminal';
+import { Player } from '@arcblock/terminal';
+import recordingData from './my-recording.json';
 
 export default function Demo() {
-  return <Player frames={records} options={config} />;
+  return <Player frames={recordingData.records} options={recordingData.config} autoPlay={true} loop={true} />;
+}
+```
+
+### Player Props
+
+| Prop         | Type       | Default      | Description                      |
+| ------------ | ---------- | ------------ | -------------------------------- |
+| `frames`     | `Array`    | **required** | Array of terminal frames to play |
+| `options`    | `Object`   | **required** | Player configuration and theme   |
+| `autoPlay`   | `Boolean`  | `false`      | Auto-start playback when mounted |
+| `loop`       | `Boolean`  | `false`      | Loop playback infinitely         |
+| `onStart`    | `Function` | -            | Callback when playback starts    |
+| `onPause`    | `Function` | -            | Callback when playback pauses    |
+| `onComplete` | `Function` | -            | Callback when playback completes |
+
+## Recording Terminal Sessions
+
+### 1. Install asciinema
+
+```bash
+# macOS
+brew install asciinema
+
+# Ubuntu/Debian
+sudo apt install asciinema
+
+# pip
+pipx install asciinema
+```
+
+### 2. Record Your Session
+
+```bash
+# Start recording
+asciinema rec my-demo.cast
+
+# ... perform your terminal commands ...
+
+# Stop recording (Ctrl+D or type 'exit')
+```
+
+### 3. Convert to Player Format
+
+Visit our **online converter** to transform your `.cast` file:
+
+**👉 [https://arcblock.github.io/ux/?path=/story/data-display-terminal-player--recording-guide](https://arcblock.github.io/ux/?path=/story/data-display-terminal-player--recording-guide)**
+
+- Drag & drop your `.cast` file
+- Instant conversion and live preview
+- Download the converted JSON file
+- No command-line tools required!
+
+## Advanced Configuration
+
+### Custom Theme
+
+```javascript
+const customOptions = {
+  ...recordingData.config,
+  theme: {
+    background: '#1e1e1e',
+    foreground: '#d4d4d4',
+    cursor: '#ffffff',
+    // ... more colors
+  },
+};
+
+<Player frames={frames} options={customOptions} />;
+```
+
+### Playback Options
+
+```javascript
+const playbackOptions = {
+  ...recordingData.config,
+  frameDelay: 'auto', // or number in ms
+  maxIdleTime: 2000, // max delay between frames
+  repeat: true, // loop playback
+  autoplay: true, // start automatically
+};
+```
+
+## Examples
+
+Check out our **Storybook demos**:
+
+- [Basic Player](https://arcblock.github.io/ux/?path=/story/data-display-terminal-player--player)
+- [Auto Play](https://arcblock.github.io/ux/?path=/story/data-display-terminal-player--auto-play)
+- [Loop Mode](https://arcblock.github.io/ux/?path=/story/data-display-terminal-player--loop)
+- [Recording Guide](https://arcblock.github.io/ux/?path=/story/data-display-terminal-player--recording-guide)
+
+## Data Format
+
+The Player expects data in this format:
+
+```json
+{
+  "config": {
+    "cols": 80,
+    "rows": 24,
+    "frameDelay": "auto",
+    "theme": {
+      /* terminal colors */
+    }
+  },
+  "records": [
+    { "delay": 100, "content": "Hello World!\n" },
+    { "delay": 500, "content": "Next command...\n" }
+  ]
 }
 ```
+
+## License
+
+Apache 2.0

package/lib/Player.js

@@ -1,17 +1,17 @@
 import { jsxs as f, jsx as n } from "react/jsx-runtime";
-import { useRef as v, useState as O, useReducer as W, useEffect as x } from "react";
-import l from "prop-types";
-import H from "@arcblock/react-hooks/lib/useInterval";
-import { useSize as I } from "ahooks";
+import { useRef as b, useState as A, useReducer as O, useEffect as x } from "react";
+import o from "prop-types";
+import { useSize as W, useInterval as H } from "ahooks";
 import y from "lodash/isUndefined";
 import h from "lodash/noop";
-import A from "./Terminal.js";
-import "./player.css";
-import { defaultOptions as U, formatFrames as L, defaultState as X, isFrameAt as b, findFrameAt as F, getPlayerClass as _, getFrameClass as $, formatTime as G } from "./util.js";
-function K({ ...P }) {
-  const a = Object.assign({}, P);
-  y(a.onComplete) && (a.onComplete = h), y(a.onStart) && (a.onStart = h), y(a.onStop) && (a.onStop = h), y(a.onPause) && (a.onPause = h), y(a.onTick) && (a.onTick = h), y(a.onJump) && (a.onJump = h);
-  const t = Object.assign({}, U, a.options), { frames: u, totalDuration: m } = L(a.frames, t), C = {
+import I from "./Terminal.js";
+import { PlayerRoot as L } from "./styles.js";
+import { defaultOptions as _, formatFrames as U, defaultState as Y, isFrameAt as N, findFrameAt as F, getPlayerClass as X, getFrameClass as $, formatTime as G } from "./util.js";
+const K = 8;
+function Q({ ...P }) {
+  const i = Object.assign({}, P);
+  y(i.onComplete) && (i.onComplete = h), y(i.onStart) && (i.onStart = h), y(i.onStop) && (i.onStop = h), y(i.onPause) && (i.onPause = h), y(i.onTick) && (i.onTick = h), y(i.onJump) && (i.onJump = h);
+  const t = Object.assign({}, _, i.options), { frames: u, totalDuration: m } = U(i.frames, t), R = {
     cols: t.cols,
     rows: t.rows,
     cursorStyle: t.cursorStyle,
@@ -20,101 +20,81 @@ function K({ ...P }) {
     lineHeight: t.lineHeight,
     letterSpacing: t.letterSpacing,
     allowTransparency: !0,
-    scrollback: 0
-    // theme: options.theme,
-  }, R = (i, e) => {
+    scrollback: 0,
+    theme: t.theme || {}
+  }, C = (a, e) => {
     switch (e.type) {
       case "jump":
-        return { ...i, isPlaying: !1, ...e.payload };
+        return { ...a, isPlaying: !1, ...e.payload };
       case "start":
-        return { ...i, isStarted: !0, lastTickTime: Date.now() };
+        return { ...a, isStarted: !0, lastTickTime: Date.now() };
       case "play":
-        return {
-          ...i,
-          isPlaying: !0,
-          lastTickTime: Date.now(),
-          ...e.payload
-        };
+        return { ...a, isPlaying: !0, lastTickTime: Date.now(), ...e.payload };
       case "pause":
-        return { ...i, isPlaying: !1, ...e.payload };
+        return { ...a, isPlaying: !1, ...e.payload };
       case "tickStart":
-        return {
-          ...i,
-          isRendering: !0,
-          lastTickTime: Date.now(),
-          ...e.payload
-        };
+        return { ...a, isRendering: !0, lastTickTime: Date.now(), ...e.payload };
       case "tickEnd":
-        return {
-          ...i,
-          isRendering: !1,
-          lastTickTime: Date.now(),
-          ...e.payload
-        };
+        return { ...a, isRendering: !1, lastTickTime: Date.now(), ...e.payload };
       case "reset":
-        return {
-          ...i,
-          currentFrame: 0,
-          currentTime: 0,
-          ...e.payload
-        };
+        return { ...a, currentFrame: 0, currentTime: 0, ...e.payload };
       default:
-        return { ...i, lastTickTime: Date.now(), ...e.payload };
+        return { ...a, lastTickTime: Date.now(), ...e.payload };
     }
-  }, o = v(null), k = v(null), d = v(null), [B, D] = O(0), M = I(document.body), [r, c] = W(R, X), j = M?.width || 0;
+  }, c = b(null), k = b(null), d = b(null), [B, D] = A(0), M = W(document.body), [r, l] = O(C, Y), j = M?.width || 0;
   x(() => {
-    if (o.current)
+    if (c.current)
       try {
-        const i = 8.03305785123967, e = d.current.getBoundingClientRect();
+        const a = 8.03305785123967, e = d.current.getBoundingClientRect();
         let s = e.x < 0 ? e.width + e.x : e.width;
         if (d.current.parentNode) {
-          const N = d.current.parentNode.getBoundingClientRect();
-          e.width > N.width && (s = N.width);
+          const v = d.current.parentNode.getBoundingClientRect();
+          e.width > v.width && (s = v.width);
         }
         t.controls && (s -= 12);
-        const T = Math.ceil(s / i), E = Math.min(Math.max(T, 40), t.cols);
-        o.current.resize(E, t.rows);
+        const T = Math.ceil(s / a), J = Math.min(Math.max(T, 40), t.cols);
+        c.current.resize(J, t.rows);
       } catch {
       }
   }, [j, B]);
-  const S = (i, e) => {
-    const s = u[i];
-    s.content && (r.requireReset && o.current.reset(), o.current.write(s.content, () => {
+  const w = (a, e) => {
+    const s = u[a];
+    s && s.content && (r.requireReset && c.current.reset(), c.current.write(s.content, () => {
       typeof e == "function" && e();
     }));
-  }, p = (i) => {
-    typeof a[i] == "function" && a[i]({ state: r, frames: u, options: t });
-  }, w = (i) => {
-    o.current.reset();
-    const e = F(u, i);
+  }, p = (a) => {
+    typeof i[a] == "function" && i[a]({ state: r, frames: u, options: t });
+  }, S = (a) => {
+    c.current.reset();
+    const e = F(u, a);
     for (let s = 0; s < e; s++)
-      S(s);
-  }, z = (i) => {
-    if (!k.current || !o.current || !r.isStarted)
+      w(s);
+  }, E = (a) => {
+    if (!k.current || !c.current || !r.isStarted)
       return !1;
-    const e = k.current.getBoundingClientRect().width, s = i.nativeEvent.offsetX, T = Math.floor(m * s / e);
-    return c({ type: "jump", payload: { currentTime: T } }), w(T), p("onJump"), !1;
-  }, g = () => (r.isStarted === !1 && (c({ type: "start" }), o.current.reset()), c({ type: "play" }), p("onStart"), !1), q = () => (c({ type: "pause" }), p("onPause"), !1), J = () => (r.currentFrame === u.length - 1 && r.currentTime === m && (c({ type: "reset" }), o.current.reset()), p("onPlay"), g());
+    const e = k.current.getBoundingClientRect().width, s = a.nativeEvent.offsetX, T = Math.floor(m * s / e);
+    return l({ type: "jump", payload: { currentTime: T } }), S(T), p("onJump"), !1;
+  }, g = () => (r.isStarted === !1 && (l({ type: "start" }), c.current.reset()), l({ type: "play" }), p("onStart"), !1), z = () => (l({ type: "pause" }), p("onPause"), !1), q = () => (r.currentFrame === u.length - 1 && r.currentTime === m && (l({ type: "reset" }), c.current.reset()), p("onPlay"), g());
   return x(() => {
-    if (o.current) {
+    if (c.current) {
       if (d.current)
         try {
           D(d.current.getBoundingClientRect().width);
         } catch {
         }
-      t.autoplay ? g() : w(Math.min(Math.abs(t.thumbnailTime), m));
+      t.autoplay ? g() : S(Math.min(Math.abs(t.thumbnailTime), m));
     }
   }, []), H(
     () => {
       if (r.isRendering)
         return !1;
-      const i = Date.now() - r.lastTickTime, e = {};
-      r.currentTime < m && (e.currentTime = r.currentTime + i), r.currentTime > m && (e.currentTime = m);
-      const s = b(u, e.currentTime, r.currentFrame);
-      return r.currentFrame !== -1 && s ? c({ type: "tick", payload: e }) : r.currentFrame === u.length - 1 ? (p("onComplete"), t.repeat ? c({ type: "reset", payload: e }) : (e.currentTime = 0, e.currentFrame = 0, e.requireReset = !0, e.isStarted = !1, c({ type: "pause", payload: e }))) : (b(e.currentTime, r.currentFrame + 1) ? e.currentFrame = r.currentFrame + 1 : e.currentFrame = F(u, e.currentTime), c({ type: "tickStart", payload: e }), S(e.currentFrame, () => (r.requireReset && (e.requireReset = !1), c({ type: "tickEnd", payload: e }), p("onTick"))));
+      const a = Date.now() - r.lastTickTime, e = {};
+      r.currentTime < m && (e.currentTime = r.currentTime + a), r.currentTime > m && (e.currentTime = m);
+      const s = N(u, e.currentTime, r.currentFrame);
+      return r.currentFrame !== -1 && s ? l({ type: "tick", payload: e }) : r.currentFrame === u.length - 1 ? (p("onComplete"), t.repeat ? l({ type: "reset", payload: e }) : (e.currentTime = 0, e.currentFrame = 0, e.requireReset = !0, e.isStarted = !1, l({ type: "pause", payload: e }))) : (e?.currentTime != null && r?.currentFrame != null && N(e.currentTime, r.currentFrame + 1) ? e.currentFrame = r.currentFrame + 1 : e.currentFrame = F(u, e.currentTime), l({ type: "tickStart", payload: e }), w(e.currentFrame, () => (r.requireReset && (e.requireReset = !1), l({ type: "tickEnd", payload: e }), p("onTick"))));
     },
-    r.isPlaying ? 8 : null
-  ), t.controls && (t.frameBox.title = null, t.frameBox.type = null, t.frameBox.style = {}, t.theme.background === "transparent" ? t.frameBox.style.background = "black" : t.frameBox.style.background = t.theme.background, t.frameBox.style.padding = "10px", t.frameBox.style.paddingBottom = "40px"), /* @__PURE__ */ f("div", { className: _(t, r), ref: d, children: [
+    r.isPlaying ? K : null
+  ), t.controls && (t.frameBox.title = null, t.frameBox.type = null, t.frameBox.style = {}, t.theme?.background === "transparent" ? t.frameBox.style.background = "black" : t.theme?.background && (t.frameBox.style.background = t.theme.background), t.frameBox.style.padding = "10px", t.frameBox.style.paddingBottom = "40px"), /* @__PURE__ */ f(L, { className: X(t, r), ref: d, children: [
     /* @__PURE__ */ n("div", { className: "cover", onClick: g }),
     /* @__PURE__ */ n("div", { className: "start", onClick: g, children: /* @__PURE__ */ f("svg", { style: { enableBackground: "new 0 0 30 30" }, viewBox: "0 0 30 30", children: [
       /* @__PURE__ */ n("polygon", { points: "6.583,3.186 5,4.004 5,15 26,15 26.483,14.128 " }),
@@ -132,27 +112,36 @@ function K({ ...P }) {
         ] }),
         /* @__PURE__ */ n("div", { className: "title", children: t.frameBox.title || "" })
       ] }),
-      /* @__PURE__ */ n("div", { className: "terminal-body", children: /* @__PURE__ */ n(A, { ref: o, options: C }) })
+      /* @__PURE__ */ n("div", { className: "terminal-body", children: /* @__PURE__ */ n(I, { ref: c, options: R }) })
     ] }) }),
     /* @__PURE__ */ f("div", { className: "controller", children: [
-      r.isPlaying && /* @__PURE__ */ n("div", { className: "pause", onClick: q, title: "Pause", children: /* @__PURE__ */ n("span", { className: "icon" }) }),
-      !r.isPlaying && r.isStarted && /* @__PURE__ */ n("div", { className: "play", onClick: J, title: "Play", children: /* @__PURE__ */ n("span", { className: "icon" }) }),
+      r.isPlaying && /* @__PURE__ */ n("div", { className: "pause", onClick: z, title: "Pause", children: /* @__PURE__ */ n("span", { className: "icon" }) }),
+      !r.isPlaying && r.isStarted && /* @__PURE__ */ n("div", { className: "play", onClick: q, title: "Play", children: /* @__PURE__ */ n("span", { className: "icon" }) }),
       !r.isPlaying && !r.isStarted && /* @__PURE__ */ n("div", { className: "play", onClick: g, title: "Start", children: /* @__PURE__ */ n("span", { className: "icon" }) }),
       /* @__PURE__ */ n("div", { className: "timer", children: G(r.currentTime) }),
-      /* @__PURE__ */ n("div", { className: "progressbar-wrapper", children: /* @__PURE__ */ n("div", { className: "progressbar", ref: k, onClick: z, children: /* @__PURE__ */ n("div", { className: "progress", style: { width: `${r.currentTime / m * 100}%` } }) }) })
+      /* @__PURE__ */ n("div", { className: "progressbar-wrapper", children: /* @__PURE__ */ n("div", { className: "progressbar", ref: k, onClick: E, children: /* @__PURE__ */ n("div", { className: "progress", style: { width: `${r.currentTime / m * 100}%` } }) }) })
     ] })
   ] });
 }
-K.propTypes = {
-  frames: l.array.isRequired,
-  options: l.object.isRequired,
-  onComplete: l.func,
-  onStart: l.func,
-  onStop: l.func,
-  onPause: l.func,
-  onTick: l.func,
-  onJump: l.func
+Q.propTypes = {
+  frames: o.array.isRequired,
+  options: o.shape({
+    autoplay: o.bool,
+    repeat: o.bool,
+    controls: o.bool,
+    frameBox: o.object,
+    theme: o.object,
+    cols: o.number,
+    rows: o.number
+  }).isRequired,
+  onComplete: o.func,
+  onStart: o.func,
+  onStop: o.func,
+  onPause: o.func,
+  onTick: o.func,
+  onJump: o.func
 };
 export {
-  K as default
+  K as PLAYER_FRAME_DELAY,
+  Q as default
 };

package/lib/Terminal.js

@@ -6,8 +6,8 @@ import { WebLinksAddon as a } from "xterm-addon-web-links";
 import { FitAddon as d } from "xterm-addon-fit";
 import p from "lodash/debounce";
 import s from "lodash/noop";
-import "./xterm.css";
-class f extends m.Component {
+import { TerminalRoot as f } from "./styles.js";
+class x extends m.Component {
   xterm = null;
   container = null;
   componentDidMount() {
@@ -61,13 +61,19 @@ class f extends m.Component {
   }
   render() {
     const { className: t = "", style: e = {} } = this.props, r = ["react-xterm", t].filter(Boolean).join(" ");
-    return (
-      // eslint-disable-next-line no-return-assign
-      /* @__PURE__ */ n("div", { ref: (o) => this.container = o, className: r, style: e })
+    return /* @__PURE__ */ n(
+      f,
+      {
+        ref: (o) => {
+          this.container = o;
+        },
+        className: r,
+        style: e
+      }
     );
   }
 }
-f.propTypes = {
+x.propTypes = {
   onData: i.func,
   onRender: i.func,
   options: i.object,
@@ -76,5 +82,5 @@ f.propTypes = {
   style: i.object
 };
 export {
-  f as default
+  x as default
 };