deno_tui

Tui uses a reactive system to automatically update the UI when data changes.

• Signal: A wrapper for a value that notifies listeners when it changes. Use .value to read or write the data.
• Computed: A reactive value that derives its state from other signals. When the underlying signals change, the Computed value updates automatically.

When accessing a signal's value outside of a reactive context (like inside a standard event callback), use the .peek() method on the component's property to get the current value without creating a dependency.

const number = new Signal(0);

const button = new Button({
  parent: tui,
  label: {
    text: new Computed(() => number.value.toString()),
  },
  // ...
});

// Updating the signal triggers UI updates
button.state.when("active", () => {
  ++number.value;
});

The reactivity system is built on the relationship between Dependency and Dependant interfaces:

• Dependency: An element (like a root Signal) that provides data. It uses the depend(dependant: Dependant) method to register a consumer. It maintains a Set<Dependant> of all elements relying on it.
• Dependant: An element that relies on one or more Dependency objects. It must implement dispose() to clear its dependencies and update(cause: Dependency | Dependant) to handle state changes triggered by its dependencies or other dependants.

export interface Dependency {
  depend(dependant: Dependant): void;
  dependants?: Set<Dependant>;
}

export interface Dependant {
  dependencies: Set<Dependency>;
  dispose(): void;
  update(cause: Dependency | Dependant): void;
}

The Component class uses a reactive signal system to manage its properties. This allows for dynamic updates to the UI without manual re-renders.

Properties that can be controlled via Signal or SignalOfObject include:

• visible: Controls visibility. When set to false, the component and all its children are hidden. When set to true, the component is redrawn.
• rectangle: Controls the component's dimensions and position. Supports deepObserve: true to watch for changes in specific rectangle properties.
• zIndex: Controls the drawing order.
• view: Controls the associated View.
• state: A Signal<ComponentState> (where ComponentState is a key of Theme) that determines which theme style is applied via the style computed signal.

The Signal class provides two primary ways to react to changes:

1. General Subscriptions (subscribe): A callback is executed every time the signal's value changes.
2. Conditional Subscriptions (when): A callback is executed only when the signal's value matches a specific conditionValue.

Example

const status = new Signal('idle');

// Runs on every change
status.subscribe((val) => {
  console.log(`Status changed to: ${val}`);
});

// Runs only when status becomes 'loading'
status.when('loading', () => {
  console.log('System is now loading...');
});

status.value = 'loading';
status.value = 'idle';

Components in Tui emit events and have a state machine that you can hook into.

• State Listeners: Use component.state.when(stateName, callback) to execute logic when a component enters a specific state (e.g., "active").
• Event Listeners: Use component.on(eventName, callback) to listen for user interactions like "mousePress".

In mouse events, the callback provides an object containing drag (boolean), movementX, and movementY.

button.state.when("active", (state) => {
  ++number.value;
});

button.on("mousePress", ({ drag, movementX, movementY }) => {
  if (!drag) return;
  const rectangle = button.rectangle.peek();
  rectangle.column += movementX;
  rectangle.row += movementY;
});

The Component class maintains an Interaction object that tracks the most recent user interaction. This is useful for implementing 'idle' timeouts or focus logic.

• lastInteraction.time: The timestamp (via Date.now()) of the last interaction.
• lastInteraction.method: The type of interaction, either `

You can restrict the characters allowed in a TextBox by providing a validator option containing a RegExp.

new TextBox({
  ...,
  validator: /\d+/,
});

To support characters like emojis that consist of multiple codepoints, set multiCodePointSupport to true in the TextBoxOptions.

new TextBox({
  ...,
  placeholder: "🧡",
  multiCodePointSupport: true,
});

A Theme is an object used to define how text is styled across different component states. Each state is represented by a Style function, which takes a string and returns a string (typically containing ANSI escape codes for terminal styling).

Required properties in a Theme include:

• base: The default style.
• focused: The style applied when a component has focus.
• active: The style applied when a component is actively being interacted with.
• disabled: The style applied when a component is disabled.

import type { Theme, Style } from './theme.ts';

const myTheme: Theme = {
  base: (text) => `\x1b[37m${text}\x1b[0m`,      // White
  focused: (text) => `\x1b[34m${text}\x1b[0m`,   // Blue
  active: (text) => `\x1b[32m${text}\x1b[0m`,    // Green
  disabled: (text) => `\x1b[90m${text}\x1b[0m`, // Grey
};