DynamicCLI

A tool for building "dynamic" CLI.

Example

import { DynamicCLI } from './DynamicCLI'

new DynamicCLI()
  .createPage('Page1', 'A Page', () => ['This', 'Is', 'A', 'Page'])
  .createPage('Page2', 'Another Page', () => ['This', 'Is', 'Another', 'Page'])

Installation

You can simply copy DynamicCLI.ts into your project or use JSR to install.

[!Note] DynamicCLI need @types/wcwidth and wcwidth as its dependencies.

Contents

• DynamicCLI
  • Getters
  • stop()
  • setSize()
  • setLayout()
  • setStyle()
  • createPage()
  • deletePage()
  • setInput()
  • simulateInput()
  • switchPage()
  • listen()
  • removeListener()
  • removeAllListeners()
  • render()
• Style
• Component
• TextColor
• BackgroundColor

DynamicCLI

import { DynamicCLI } from './DynamicCLI'

new DynamicCLI(<options>) // Create a CLI

• options <undefined | object> | Options for the CLI.
  • render <boolean> | Should the CLI render stuff onto the console. Default: true
  • renderInterval <number> | The interval(ms) between each render. Default: 25
  • pagePrefix_notSelected <string> | The prefix for the page, when the line is not selected. Default: " <lineNumber> | "
  • pagePrefix_selected <string> | The prefix for the page, when the line is selected. Default: "${style.background_selected} ${style.text_selected}<lineNumber>${TextColor.reset}${style.background} | "
  • allowInput <boolean> | Should the CLI take input from stdin. Default: true
  • allowSwitchPage <boolean> | Whether the user is allowed to switch pages. Default: true

Getters

• .options <DynamicCliOptions> | Get the options for the CLI.
• .size <{ width: number, height: number }> | Get the size of the CLI.
• .pages <string[]> | Get IDs of all the pages.
• .input <string> | Get user input.
• .currentPage <undefined | string> | Get the ID of current page.
• .cursorY <undefined | number> | The y position of the cursor.

stop()

.stop() // Stop the CLI

return <void>

setSize()

.setSize(<width>, <height>) // Set the size of the CLI

• width <undefined | number> | The width.
• height <undefined | number> | The height.

return <DynamicCLI>

setLayout()

.setLayout(<layout>) // Set the layout of the CLI

• layout <any[]> | An contains components.

return <DynamicCLI>

setStyle()

.setStyle(<style>) // Set the style of the CLI

• style <object> | A style object

return <DynamicCLI>

- Default Style -

{
  background: BackgroundColor.reset,

  selectBackground: BackgroundColor.white,
  selectFont: TextColor.gray,
  notSelectBackground: BackgroundColor.gray,
  notSelectFont: TextColor.white
}

return <DynamicCLI>

createPage()

.createPage(<id>, <name>, <callback>) // Create a page

• id <string> | The ID of the page.
• name <string> | The name of the page.
• callback <function> | The render function of the page, the function must return <string[]>.

return <DynamicCLI>

deletePage()

.deletePage(<id>) // Delete a page

• id <string> | The ID of the page.

return <DynamicCLI>

setInput()

.setInput(<string>) // Set the input

• string <string> | The content of the input.

return <void>

simulateInput()

.simulateInput(<key>) // Simulate user input

• key <Buffer> | The keystroke of the input.

return <void>

switchPage()

.switchPage(<id>) // Switch the page

• id <string> | The id of the page.

return <void>

listen()

.listen(<name>, <callback>) // Listen to an event

• name <string> | The name of the event.
• callback <function> | The function that triggers when the event is called.

- All Events -

name	callback arguments	description
scroll	(info: { page, cursorY, scrollY })	Triggeres when the user scrolls.
switchPage	(pageID: string)	Triggeres when the user switches pages.
enter	(input: string)	Triggeres when the user press enter.
input	(key: Buffer)	Triggeres when the user input.

return <string> (The ID of the listener)

removeListener()

.removeListener(<id>) // Remove a listener

• id <string> | The ID of the listener.

return <void>

removeAllListeners()

.removeAllListeners() // Remove all listeners

return <void>

render()

.render() // Render the CLI

return <{ line: number, content: string }[]> (The line that need to update)

Style

{
  background: string,

  background_notSelected: string,
  text_notSelected: string 
  background_selected: string,
  text_selected: string,
}

Component

import { Component } from './DynamicCLI'

Component.<name>(<parameters>)

- All Components -

name	parameters	description
blank	()	A blank line.
text	(callback)	A line of text, callback must be a function that return a .
pageTabs	()	A line of page tabs.
pageContent	()	Multiple lines of page content.
input	(placeholder)	A line of input.

TextColor

import { TextColor } from './DynamicCLI'

TextColor.<name>

- All Colors -

reset, red, brightRed, yellow, brightYellow, green, brightGreen, cyan, brightCyan, blue, brightBlue, purple, brightPurple, white, black, gray

BackgroundColor

import { BackgroundColor } from './DynamicCLI'

BackgroundColor.<name>

- All Colors -

reset, red, brightRed, yellow, brightYellow, green, brightGreen, cyan, brightCyan, blue, brightBlue, purple, brightPurple, white, black, gray