Simple retro styled React-hooks-based terminal shell.
- Smooth printing
- Command history
- Loader
- Ability lock command input
- Typescript and React
- Hooks-based with event queues under the hood
- Zero additional dependencies
The best way to use crt-terminal is to install it from npm and include it into your app.
yarn add @gton-capital/crt-terminal
npm install @gton-capital/crt-terminal
Then you need to import Terminal
, useEventQueue
(or implement your own EventQueue) and line/words helpers (or corresponding enum with IDs).
Important! For better experience Terminal
should be wrapped into a fixed size container.
import React from 'react';
import { Terminal, useEventQueue, textLine, textWord } from '@gton-capital/crt-terminal';
const bannerText = `
Hello world!
And not only world
`;
export default function App() {
const eventQueue = useEventQueue();
const { print } = eventQueue.handlers;
return (
<div style={{ width: '1000px', height: '600px' }}>
<Terminal
queue={eventQueue}
banner={[textLine({ words: [textWord({ characters: bannerText })] })]}
onCommand={(command) =>
print([
textLine({
words: [
textWord({ characters: 'You entered command: ' }),
commandWord({ characters: command, prompt: '>' }),
],
}),
])
}
/>
</div>
);
}
queue: QueueInterface
-state
andapi
ofuseEventQueue
(command: string) => void
- function to be called every time new command is submitted
-
prompt?: string
- prompt symbol before command input -
cursorSymbol?: string
- function to be called every time new command is submitted -
maxHistoryCommands?: number
- max number of commands to be memorized in commands history -
banner?: PrintableItem
- message to be printed afterTerminal
is mounted -
loader?: Partial<LoaderConfig>
- loader config, consist of:slides: string[]
- array of consecutive loader statesloaderSpeed: number
- interval between state changes
-
printer?: Partial<PrinterConfig>
- printer config, consist of:printerSpeed: number
- interval between state changescharactersPerTick: number
- characters to print on each tick
-
effects?
enabling or disabling following effects:scanner?: boolean
- scanner linepixels?: boolean
- "pixels" effectscreenEffects?: boolean
- screen shakingtextEffects?: boolean
- text glow pulsing
The main part of public interface through which component communicates with outer world. useEventQueue
exports event creators in handlers
field of return object, namely:
print: (payload: PrintableItem) => void
- prints a message on terminal "screen". Important! Print is async operation, so your next message will be printed as soon as the previous one is finishedclear: () => void
- clears terminal "screen" with respect to printing queuefocus: () => void
- focuses terminal inputlock: (payload: boolean) => void
- locks/unlocks terminal input preventing any user attempt to enter a commandloading: (payload: boolean) => void
- starts/ends loader. Important! Loading start locks input automatically, if it is not locked yet. Loading end unlocks input automatically, if it was locked by loader
You can use these handlers everywhere to fully control behavior of tour terminal.
If you don't like event creators, you can use enqueue
from api
field of return object. In this case you also need to import enums PrinterEvents
and TerminalEvents
. Important! To avoid possible bugs, you should pass newly created object into enqueue
method
As one can notice print
handler prints a PrintableItem
. PrintableItem
or sentence is an array of Lines
. Line is essentially a new div
on the screen, each line has field words
with array of Words
. There are two types of lines:
TextLine
(larger x-padding, no y-padding)CommandLine
(smaller x-padding, y-padding).
Important! Each Lines
and Words
have common optional fields:
dataAttribute
-data-crt-terminal
attributeclassName
id
Word is essentially a new span
inside line. Word can be multilined, but aware of span intereactions whe one of them is multilined. Each word has characters
filed with content of a word. There are quite few types of words:
AnchorWord
-<a>
element with optionalhref
andonClick
fieldsTextWord
-<span>
elementButtonWord
-<button>
element with optionalonClick
fieldCommandWord
-<span>
element with requiredprompt
field
There are two ways of creating Lines
and Words
:
- Using helper functions
textWord
,buttonWord
,commandWord
,anchorWord
,commandLine
,textLine
- Using object literals, in this cases you need to import
WordTypes
,LineTypes
enums
Every element inside terminal has special fixed style you can safely refer to. You can also add your own className
for lines and words.
Command history saves entered commands, but no more then maxHistoryCommands
. You can get previous/next saved command by pressing Arrow Up
/ Arrow Down
It is a turborepo-based monorepo set up for testing and developing. Library itself is inside packages/crt-terminal, demo app is inside apps/web; to start locally just yarn dev
in root folder.
MIT Licensed. Copyright (c) Dmitriy Lipin 2022.