Terminosaurus

The TermElement widget is the foundational building block for all other widgets in Terminosaurus. It manages the rectangular geometry of a widget, including positioning, bounding box computation, and border rendering.

To create a custom widget, you inherit from TermElement and implement the renderContent method to define what appears inside the box.

In React environments, TermElement is exposed via the <term:div/> component and is typically used to define the high-level application layout.

Terminosaurus distinguishes itself from other terminal UI libraries through its framework-agnostic core, comprehensive support for Flexbox layout, relative/absolute positioning, focus management, scrolling, text alignment, text wrapping, and extensive CSS property support.

Key comparisons:

• Ink: Supports React and Flexbox, but lacks relative/absolute positioning, scrolling, text alignment/wrapping, and full CSS property support.
• Blessed: Lacks framework-agnostic API, Flexbox, positioning, focus management, scrolling, and text alignment/wrapping. React support is limited via unmaintained third-party adapters.

The TermScreen class serves as the primary render target for a Terminosaurus application. It functions similarly to the window object in a web browser, acting as the environment where your application lives.

Crucially, a TermScreen is not a node within the element tree; it is the container/target that exists outside the tree itself.

Terminosaurus provides a React renderer that allows you to build terminal UIs using familiar JSX syntax. By importing render from terminosaurus/react, you can mount a React component tree to the terminal. You can use custom elements (e.g., <term:div>) within your components to represent terminal UI elements and handle events like onClick using standard React patterns.

import {
    useState
} from 'react'
import {
    render,
} from 'terminosaurus/react';

function App() {
    const [counter, setCounter] = useState(0);

    const increaseCounter = () => {
        setCounter(counter + 1);
    };

    return (
        <term:div onClick={increaseCounter}>
            Counter: {counter}
        </term:div>
    );
}

render({}, <App/>);

To start a terminal application, use the run function imported from terminosaurus. This is the preferred way to initialize your app because it automatically handles the asynchronous loading of required WASM modules and waits for the application to complete before returning. The run function provides a screen object in its callback, which contains the rootNode used for appending elements.

import {run} from 'terminosaurus';

run(screen => {
  // Your application logic goes here
});

You can attach event handlers to Terminosaurus React components by using the on prefix followed by the event name (e.g., onClick). This allows you to integrate standard React state management with terminal interactions.

import {useState} from 'react';
import {render} from 'terminosaurus/react';

function Counter() {
  const [count, setCount] = useState(0);

  return (
    <term:div onClick={() => setCount(count + 1)}>
      Clicked {count} times
    </term:div>
  );
}

render(
  <Counter/>
);

You can use the core Terminosaurus API directly to build interfaces. This involves using run to initialize the terminal environment and interacting with elements like TermText and TermElement. You can manually append elements to the screen.rootNode and attach event listeners using addEventListener on element event properties (e.g., onClick).

import {
    TermElement,
    TermText,
    run,
} from 'terminosaurus';

run({}, async screen => {
    const text = new TermText();
    text.appendTo(screen.rootNode);

    let counter = 0;

    const increaseCounter = () => {
        counter += 1;
        text.setText(`Counter: ${counter}`);
    };

    text.onClick.addEventListener(() => {
        increaseCounter();
    });

    increaseCounter();
});