@cedarjs/tui 0.0.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Cedar
+
+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.

package/README.md

@@ -0,0 +1,7 @@
+# TUI
+
+Terminal User Interface for RedwoodJS. A collection of helpful functions to standardise and simplify terminal output.
+
+## API
+
+**TODO**

package/dist/index.d.ts

@@ -0,0 +1,132 @@
+import stream from 'stream';
+import boxen from 'boxen';
+import chalk from 'chalk';
+import { prompt as enquirerPrompt } from 'enquirer';
+/**
+ * A default set of styling for the TUI, designed for a cohesive look and feel around the Redwood CLI, CRWA and vairous plugins
+ */
+export declare const RedwoodStyling: {
+    error: chalk.Chalk;
+    warning: chalk.Chalk;
+    success: chalk.Chalk;
+    info: chalk.Chalk;
+    header: chalk.Chalk;
+    cmd: chalk.Chalk;
+    redwood: chalk.Chalk;
+    love: chalk.Chalk;
+    green: chalk.Chalk;
+};
+/**
+ * An object used to describe a "reactive" TUI element, that is an element that is updated a number of times per second
+ */
+export declare class ReactiveTUIContent {
+    private outStream?;
+    private mode;
+    private header;
+    private content;
+    private spinner;
+    private boxen;
+    private frameInterval;
+    private spinnerIndex;
+    constructor(options: {
+        mode?: 'text' | 'stream';
+        header?: string;
+        content?: string;
+        spinner?: {
+            enabled?: boolean;
+            characters?: string[];
+        };
+        boxen?: boxen.Options;
+        outStream?: stream.Readable;
+        frameInterval?: number;
+    });
+    update(options: {
+        mode?: 'text' | 'stream';
+        header?: string;
+        content?: string;
+        spinner?: {
+            enabled?: boolean;
+            characters?: string[];
+        };
+        boxen?: boxen.Options;
+        outStream?: stream.Readable;
+        frameInterval?: number;
+    }): void;
+    setOutStream(out: stream.Readable): void;
+    renderToString(): string;
+    getFrameInterval(): number;
+}
+/**
+ * Configuration for the TUI
+ *
+ * Accepts an out and err stream which the TUI will write to.
+ */
+export interface RedwoodTUIConfig {
+    out?: NodeJS.WriteStream;
+    err?: NodeJS.WriteStream;
+}
+/**
+ * TODO: Documentation for this
+ */
+export declare class RedwoodTUI {
+    private manager;
+    private outStream;
+    private errStream;
+    private timerId?;
+    private isReactive;
+    private reactiveContent?;
+    constructor({ out, err }?: RedwoodTUIConfig);
+    /**
+     * Enables rendering of a reactive component to the TUI
+     *
+     * @param reactiveContent A new ReactiveTUIContent object set as the current reactive content
+     */
+    startReactive(reactiveContent?: ReactiveTUIContent): void;
+    /**
+     * Stops any new draws of the current reactive content to the TUI
+     *
+     * @param clear If true, the last drawn content will be cleared
+     */
+    stopReactive(clear?: boolean): void;
+    /**
+     * Renders the current reactive content and draws it to the TUI
+     *
+     * @param force Force a draw even if the TUI is not reactive
+     */
+    private drawReactive;
+    /**
+     * Gets the current reactive TUI content if there is one
+     *
+     * @returns The current reactive content or undefined if there isn't one
+     */
+    getCurrentReactive(): ReactiveTUIContent | undefined;
+    /**
+     * Writes a string to the TUI output stream
+     *
+     * @param text The string to write out
+     */
+    drawText(text: string): void;
+    /**
+     * A wrapper around enquirer.prompt that disables the reactive TUI and prompts
+     *
+     * @param questions A question or array of questions to prompt the user with
+     *
+     * @returns The prompt result
+     */
+    prompt<T = object>(questions: Parameters<typeof enquirerPrompt>[0]): Promise<T>;
+    /**
+     * Display an error message in a box
+     *
+     * @param title Error box title
+     * @param message Error message
+     */
+    displayError(title: string, message: string): void;
+    /**
+     * Display a warning message in a box
+     *
+     * @param title Error box title
+     * @param message Error message
+     */
+    displayWarning(title: string, message: string): void;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,292 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var index_exports = {};
+__export(index_exports, {
+  ReactiveTUIContent: () => ReactiveTUIContent,
+  RedwoodStyling: () => RedwoodStyling,
+  RedwoodTUI: () => RedwoodTUI
+});
+module.exports = __toCommonJS(index_exports);
+var import_stream = __toESM(require("stream"));
+var import_boxen = __toESM(require("boxen"));
+var import_chalk = __toESM(require("chalk"));
+var import_enquirer = require("enquirer");
+var import_stdout_update = require("stdout-update");
+const RedwoodStyling = {
+  error: import_chalk.default.bold.red,
+  warning: import_chalk.default.keyword("orange"),
+  success: import_chalk.default.greenBright,
+  info: import_chalk.default.grey,
+  header: import_chalk.default.bold.underline.hex("#e8e8e8"),
+  cmd: import_chalk.default.hex("#808080"),
+  redwood: import_chalk.default.hex("#ff845e"),
+  love: import_chalk.default.redBright,
+  green: import_chalk.default.green
+};
+class ReactiveTUIContent {
+  outStream;
+  mode;
+  header;
+  content;
+  spinner;
+  boxen;
+  frameInterval;
+  // TODO: Implement a progress bar
+  spinnerIndex = 0;
+  constructor(options) {
+    this.mode = options.mode || "text";
+    this.header = options.header || "";
+    this.content = options.content || "";
+    const defaultSpinner = {
+      enabled: false,
+      characters: ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"].map(
+        (c) => RedwoodStyling.redwood(c)
+      )
+    };
+    this.spinner = { ...defaultSpinner, ...options.spinner };
+    this.boxen = { ...options.boxen };
+    this.frameInterval = options.frameInterval || 80;
+    if (options.outStream) {
+      this.setOutStream(options.outStream);
+    }
+  }
+  update(options) {
+    if (options.mode) {
+      this.mode = options.mode;
+    }
+    if (options.header !== void 0) {
+      this.header = options.header;
+    }
+    if (options.content !== void 0) {
+      this.content = options.content;
+    }
+    if (options.spinner) {
+      this.spinner = { ...this.spinner, ...options.spinner };
+    }
+    if (options.boxen) {
+      this.boxen = { ...this.boxen, ...options.boxen };
+    }
+    if (options.outStream) {
+      this.setOutStream(options.outStream);
+    }
+    if (options.frameInterval) {
+      this.frameInterval = options.frameInterval;
+    }
+  }
+  setOutStream(out) {
+    this.outStream = new import_stream.default.Writable({
+      write: (chunk, _encoding, next) => {
+        if (this.content === "stream") {
+          this.content += chunk.toString("utf-8");
+        }
+        next();
+        return true;
+      }
+    });
+    out.pipe(this.outStream, { end: true });
+  }
+  renderToString() {
+    if (this.mode === "stream") {
+      return "Not implemented yet";
+    }
+    let renderedString = this.content;
+    if (this.header) {
+      renderedString = `${this.header}
+${renderedString}`;
+    }
+    if (this.spinner.enabled) {
+      renderedString = `${this.spinner.characters[this.spinnerIndex]} ${renderedString}`;
+      this.spinnerIndex += 1;
+      if (this.spinnerIndex >= this.spinner.characters.length) {
+        this.spinnerIndex = 0;
+      }
+    }
+    return renderedString;
+  }
+  getFrameInterval() {
+    return this.frameInterval;
+  }
+}
+class RedwoodTUI {
+  manager;
+  outStream;
+  errStream;
+  timerId;
+  isReactive = false;
+  reactiveContent;
+  constructor({ out, err } = {}) {
+    this.outStream = out || process.stdout;
+    this.errStream = err || process.stderr;
+    this.manager = import_stdout_update.UpdateManager.getInstance(this.outStream, this.errStream);
+    process.on("exit", () => {
+      this.stopReactive();
+    });
+  }
+  /**
+   * Enables rendering of a reactive component to the TUI
+   *
+   * @param reactiveContent A new ReactiveTUIContent object set as the current reactive content
+   */
+  startReactive(reactiveContent) {
+    if (this.isReactive) {
+      this.stopReactive();
+    }
+    if (reactiveContent) {
+      this.reactiveContent = reactiveContent;
+    }
+    if (!this.reactiveContent) {
+      throw new Error("TUI has no reactive content");
+    }
+    if (!this.outStream.isTTY) {
+      this.drawReactive(true);
+      return;
+    }
+    if (!this.manager.isHooked) {
+      this.manager.hook();
+      this.isReactive = true;
+      this.timerId = setInterval(() => {
+        this.drawReactive();
+      }, this.reactiveContent.getFrameInterval());
+    }
+  }
+  /**
+   * Stops any new draws of the current reactive content to the TUI
+   *
+   * @param clear If true, the last drawn content will be cleared
+   */
+  stopReactive(clear = false) {
+    if (!this.outStream.isTTY) {
+      this.drawReactive(true);
+      return;
+    }
+    if (this.manager.isHooked) {
+      this.isReactive = false;
+      clearInterval(this.timerId);
+      this.drawReactive(true);
+      if (clear) {
+        this.manager.erase(this.manager.lastLength);
+      }
+      this.manager.unhook();
+    }
+  }
+  /**
+   * Renders the current reactive content and draws it to the TUI
+   *
+   * @param force Force a draw even if the TUI is not reactive
+   */
+  drawReactive(force = false) {
+    if (this.isReactive || force) {
+      const wasHooked = this.manager.isHooked;
+      if (force && !wasHooked) {
+        this.manager.hook();
+      }
+      const content = this.reactiveContent?.renderToString();
+      if (content) {
+        this.manager.update(content.split("\n"));
+      }
+      if (force && !wasHooked) {
+        this.manager.unhook();
+      }
+    }
+  }
+  /**
+   * Gets the current reactive TUI content if there is one
+   *
+   * @returns The current reactive content or undefined if there isn't one
+   */
+  getCurrentReactive() {
+    return this.reactiveContent;
+  }
+  /**
+   * Writes a string to the TUI output stream
+   *
+   * @param text The string to write out
+   */
+  drawText(text) {
+    this.outStream.write(`${text}
+`);
+  }
+  // TODO: Consider a custom prompting implementation for full control of look/feel/functionality etc...
+  /**
+   * A wrapper around enquirer.prompt that disables the reactive TUI and prompts
+   *
+   * @param questions A question or array of questions to prompt the user with
+   *
+   * @returns The prompt result
+   */
+  async prompt(questions) {
+    const wasReactive = this.isReactive;
+    if (wasReactive) {
+      this.stopReactive();
+    }
+    const result = await (0, import_enquirer.prompt)(questions);
+    if (wasReactive) {
+      this.startReactive();
+    }
+    return result;
+  }
+  /**
+   * Display an error message in a box
+   *
+   * @param title Error box title
+   * @param message Error message
+   */
+  displayError(title, message) {
+    this.drawText(
+      (0, import_boxen.default)(message, {
+        padding: 1,
+        borderColor: "red",
+        title: `\u26A0 Error: ${title}`,
+        titleAlignment: "left"
+      })
+    );
+  }
+  /**
+   * Display a warning message in a box
+   *
+   * @param title Error box title
+   * @param message Error message
+   */
+  displayWarning(title, message) {
+    this.drawText(
+      (0, import_boxen.default)(message, {
+        padding: 1,
+        borderColor: "yellow",
+        title: `\u26A0 Warning: ${title}`,
+        titleAlignment: "left"
+      })
+    );
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ReactiveTUIContent,
+  RedwoodStyling,
+  RedwoodTUI
+});

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@cedarjs/tui",
+  "version": "0.0.4",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cedarjs/cedar.git",
+    "directory": "packages/tui"
+  },
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsx ./build.mts && yarn build:types",
+    "build:pack": "yarn pack -o cedar-tui.tgz",
+    "build:types": "tsc --build --verbose",
+    "build:watch": "nodemon --watch src --ext \"js,jsx,ts,tsx\" --ignore dist --exec \"yarn build\"",
+    "prepublishOnly": "NODE_ENV=production yarn build"
+  },
+  "dependencies": {
+    "boxen": "5.1.2",
+    "chalk": "4.1.2",
+    "enquirer": "2.4.1",
+    "stdout-update": "1.6.8"
+  },
+  "devDependencies": {
+    "@cedarjs/framework-tools": "0.0.4",
+    "tsx": "4.19.3",
+    "typescript": "5.6.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "gitHead": "5b4f77f985bd86ee31ee7338312627accf0cb85b"
+}