Terminal

A terminal that runs the commands added to it. It comes with `help` and `clear`; every other command is added by the page. The `run` function of a command returns the component to show as its output. The terminal places that component among its own children, so the styles of the page reach it, and removes it when the screen is cleared. The terminal has a fixed height of 80 logical pixels and scrolls its lines. Set `height` in CSS to change it. Inside a `pix-window` it grows to fill a maximized window. Enter runs what was typed, the up and down arrows walk through the commands already typed, Tab completes the name of a command and Control + L clears the screen.

Import

Importing the library registers <pix-terminal>.

import '@halleyfante/pix';

Basic

<pix-terminal prompt="$"></pix-terminal>

class GreetingCard extends HTMLElement {
    connectedCallback() {
      this.textContent = 'Hello, ' + this.getAttribute('name') + '!';
    }
  }

customElements.define('about-card', AboutCard);
  customElements.define('greeting-card', GreetingCard);

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

terminal.addCommand({
    name: 'about',
    description: 'Shows who made this',
    run: () => document.createElement('about-card'),
  });

terminal.addCommand({
    name: 'greet',
    description: 'Greets someone by name',
    run: (parameters) => {
      if (parameters.length === 0) {
        throw new Error('usage: greet <name>');
      }

const card = document.createElement('greeting-card');
      card.setAttribute('name', parameters.join(' '));
      return card;
    },
  });
</script>

Inside an application

Attributes

Name	Type	Default	Description
`prompt`	string	'$'	Text shown before each command.

Properties

Name	Type	Description
`commands`	TerminalCommand[]	The commands this terminal can run, in alphabetical order.
`history`	string[]	The commands typed so far, oldest first.

Methods

Method	Description
`PixTerminal.addCommand(command: TerminalCommand): void`	Adds a command to every terminal on the page, including the ones created later.
`addCommand(command: TerminalCommand): void`	Adds a command to this terminal only. It replaces a command of the same name added to every terminal.
`run(text: string): Promise<void>`	Runs a command as if it had been typed. Resolves when the command finishes.
`write(output: TerminalOutput): void`	Shows an element, usually a component, as a new line on the screen.
`clear(): void`	Removes every line from the screen. The typed commands are kept.

Events

Name	Description
`command`	A command was run. `event.detail.text` holds what was typed.