Machine state, sequences and sessions

Terminal <smart-terminal>

Terminal displays a stream of lines, such as an instrument session or an event log, at a high rate.

<smart-terminal> · 9 properties, 6 methods, 2 events · source/modules/smart.terminal.js

Usage in JavaScript

The component is a custom element: its properties are set on the element, its events are DOM CustomEvents with the data in event.detail, and its methods are called on the element. The properties can also be written as attributes in kebab case (precision-digits="1").

const terminal = document.querySelector('smart-terminal');

terminal.filter = '/^ERR/';
terminal.interactive = true;
terminal.addEventListener('command', (event) => console.log(event.detail));
terminal.write('value', 'value');

Properties

Property	Type, default	Description
announce	boolean false	Sets or retrieves whether new lines are announced to assistive technology. Off by default and rate-limited when on. Errors are announced immediately; other lines are announced at most once every few seconds.
ansiColors	boolean false	Sets or retrieves whether ANSI SGR escape codes are rendered as colours. The eight basic foreground colours, bold and reset are supported, which is what bench instruments and serial devices emit. When disabled, the colour codes are removed. Other escape sequences - erase line, cursor moves and visibility, window titles - and control characters such as NUL and BEL are always removed, and a carriage return goes back to the start of the line, so a progress line written over itself reads as its last state.
autoScroll	boolean true	Sets or retrieves whether the view follows the newest line. The view follows only while it is already scrolled to the bottom. Boolean attributes are presence-based, so set the property from script to turn it off.
filter	string	Sets or retrieves a filter, either as plain text matched case-insensitively or as a /regex/. The filter affects the view only: a filtered-out line stays in the buffer, so clearing the filter restores the history. An incomplete regular expression falls back to a substring match while it is being typed. Lines that leave the buffer leave the view by which lines they are, so a filtered view keeps every matching line still in the buffer.
interactive	boolean false	Sets or retrieves whether a command line is shown. Pressing Enter echoes the command as a transcript line and raises the command event. The application appends the response, because the component does not know what is connected.
maxLines	number 500	Sets or retrieves how many lines the ring buffer holds. Lowering it trims the oldest immediately. Never goes below one.
paused	boolean false	Sets or retrieves whether the terminal is frozen. A paused terminal keeps what it holds and drops anything appended, and write returns false so the application knows the line was not taken. While paused the command line sends nothing: the line stays in the box, the box says why, and Enter sends it once the terminal is resumed.
prompt	string >	Sets or retrieves the prompt of the command line, which is also used as the prefix when a command is echoed.
timestampFormat	'none' | 'time' | 'datetime' | 'elapsed' none	Sets or retrieves how each line is stamped. none no timestamp time local time of day datetime local date and time elapsed seconds since the terminal started - what a test log wants, because that is what the report is measured against

Methods

Method	Description
write(text, level?) returns boolean	Appends one line. Returns false when the terminal is paused and the line was dropped. The text is escaped, so device output cannot inject markup. text string The line. level string info, warn, error, success, command or response. Drives the colour. Defaults to info.
writeMany(lines, level?) returns boolean	Appends several lines with one scroll and one announcement. Accepts strings or { text, level } objects. lines string[] | object[] The lines, oldest first. level string Applied to any entry given as a bare string.
clear()	Empties the buffer and the view.
scrollToEnd()	Scrolls to the newest line and resumes following new lines. Intended for a "jump to end" control.
snapshot() returns object[]	Returns the lines in the buffer, oldest first, as a copy that is not changed by later writes.
toText(filtered?) returns string	Returns the buffer as plain text, oldest first, including the timestamps when they are enabled, for export, a report or the clipboard. filtered boolean Only the lines the filter currently admits.

Events

The data of an event is in event.detail. command is a request: the terminal raises it on Enter only while interactive is true, echoes the command line and leaves the response to the application. lineAppended reports a line the terminal has already added, the echo included.

Event	Description and detail
command	This event is triggered when a command is entered on the command line. The component echoes the command; the application appends the response. It is not raised while the terminal is disabled or paused, nor by the Enter that ends an IME composition. Up and Down on the command line bring back the last 50 commands sent. command string What was typed, without the prompt.
lineAppended	This event is triggered when a line is appended. line object The line: { id, text, level, at }. length number How many lines the buffer now holds.

Types

type TerminalTimestampFormat

'none' | 'time' | 'datetime' | 'elapsed'

CSS variables

The component declares 4 CSS variables; the CSS page shows how to set them.

--smart-terminal-height --smart-terminal-background --smart-terminal-color --smart-terminal-font