vue-web-terminal

vue-web-terminal is a Vue-based plugin that provides a web-based command-line interface (CLI) component. It is designed to display various message formats such as plain text, tables, JSON, code/multi-line text, HTML, and ANSI.

Key Capabilities:

• Message Rendering: Supports real-time echoing, appending, and various formats (tables, JSON, etc.).
• User Interaction: Supports user input, command history (using ↑/↓ keys), and cursor movement (using ←/→ keys).
• UI Features: Supports window dragging, pinning, full-screen mode, command input suggestions, and log grouping/collapsing.
• Customization: Provides multiple slots for custom styling, built-in dark/light themes, and a rich JS API to simulate non-human operations.

Important Mental Model: This plugin does not execute commands itself. It acts as the interface layer: it captures the command from the user and presents the results back to the user. The developer is responsible for implementing the actual command execution logic.

The vue-web-terminal component provides the interface for user input but does not execute commands itself. You must implement the execution logic by listening to the @exec-cmd event on the <terminal> component.

When a user enters a command, the @exec-cmd event provides:

• key: A string identifying the command type (e.g., 'fail').
• command: The actual command string entered by the user.
• success: A callback function (SuccessFunc) to display successful output.
• failed: A callback function (FailedFunc) to display error messages.

To display output via the success callback, pass an object with the following structure:

• type: The message type (e.g., 'normal').
• class: A CSS class for styling (e.g., 'success', 'error', 'system', 'info', 'warning').
• tag: A tag for categorization (e.g., 'success').
• content: The content to display.

<script setup lang="ts">
  import {Terminal, SuccessFunc, FailedFunc} from "vue-web-terminal"

  const onExecCmd = (key: string, command: string, success: SuccessFunc, failed: FailedFunc) => {
    if (key === 'fail') {
      failed('Something wrong!!!')
    } else {
      let allClass = ['success', 'error', 'system', 'info', 'warning'];

      let clazz = allClass[Math.floor(Math.random() * allClass.length)];
      success({
        type: 'normal',
        class: clazz,
        tag: 'success',
        content: command
      })
    }
  }
</script>

<template>
  <div id="app">
    <terminal name="my-terminal" @exec-cmd="onExecCmd"></terminal>
  </div>
</template>

Messages in the terminal are structured using the Message type. This allows for rich content types and visual styling.

Message Properties:

• type: The content format ('cmdLine' | 'normal' | 'json' | 'code' | 'table' | 'html' | 'ansi').
• content: The actual data. Can be a string, number, object, MessageContentTable, or an Array.
• class: The visual style ('success' | 'error' | 'info' | 'warning' | 'system').
• tag: An optional identifier for grouping or filtering.
• depth: An optional nesting level.

MessageContentTable Format: For table-style messages, use the following structure:

{ 
  head: string[], 
  rows: string[][] 
}

// Example of a rich table message
const tableMsg: Message = {
  type: 'table',
  content: {
    head: ['ID', 'Name', 'Status'],
    rows: [
      ['1', 'Server-A', 'Running'],
      ['2', 'Server-B', 'Stopped']
    ]
  },
  class: 'info'
};

To make the terminal functional, listen for the @exec-cmd event on the <terminal> component. This event provides the command key, the command string, and two callback functions: success and failed.

• success(options): Use this to display a successful command output. The options object can include type, class, tag, and content.
• failed(message): Use this to display an error message to the user.

Example implementation in a Vue 3 <script setup> component:

<script setup lang="ts">
  import {Terminal, SuccessFunc, FailedFunc} from "vue-web-terminal"

  const onExecCmd = (key: string, command: string, success: SuccessFunc, failed: FailedFunc) => {
    if (key === 'fail') {
      failed('Something wrong!!!')
    } else {
      // Example of cycling through different visual styles
      let allClass = ['success', 'error', 'system', 'info', 'warning'];
      let clazz = allClass[Math.floor(Math.random() * allClass.length)];
      
      success({
        type: 'normal',
        class: clazz,
        tag: 'success',
        content: command
      })
    }
  }
</script>

<template>
  <div id="app">
    <terminal name="my-terminal" @exec-cmd="onExecCmd"></terminal>
  </div>
</template>

<style>
  body, html, #app {
    margin: 0;
    padding: 0;
    width: 100%;
    height: 100%;
  }
</style>

The VueWebTerminal interface provides methods to customize the terminal plugin during or after installation. You can define custom themes, manage local storage settings, and control command history limits.

Key methods:

• configTheme(theme: string, css: string): Define a custom theme by providing a name and a CSS string. This can override default dark or light themes.
• configStoreName(name: string): Set the name of the local storage key used for persisting terminal data.
• configMaxStoredCommandCountPerInstance(count: number): Set the maximum number of command history entries to store per terminal instance.

// Example usage of configuration methods
const terminalPlugin: VueWebTerminal = ...;

terminalPlugin.configTheme('my-custom-theme', '.terminal { background: #000; color: #fff; }');
terminalPlugin.configStoreName('my-app-terminal-storage');
terminalPlugin.configMaxStoredCommandCountPerInstance(100);