tui.el

⚠ Requires emacs version 26.1 or higher ⚠

Introduction

This is an experiment in building purely text-based user interfaces (TUI’s). The ultimate goal is to explore new paradigms for user interface design and development using Emacs. To this end, tui.el implements an API based on the popular React JavaScript framework in order to reduce the demands involved with designing and building complex text-based UI’s.

This is all currently experimental! Expect things to change as I get feedback about what works, what does not!

Installing

Using Straight.el

(straight-use-package
 '(tui :type git :host github :repo "ebpa/tui.el" :files ("*.el" "components" "layout" "demo" "snippets")))

Manually

The package hasn’t been submitted to Melpa yet. To install the package manually: clone the repository, add the folder to your load path and install the dependencies with the following:

git clone [email protected]:ebpa/tui.el.git

(add-to-list 'load-path "~/path/to/tui.el")

(require 'package)
(add-to-list 'package-archives
             '("melpa" . "http://melpa.org/packages/") t)

(package-initialize)
(package-refresh-contents)

;; Manually install package dependencies
(package-install 'dash)
(package-install 's)

Getting started

Tic Tac Toe

Tui contains a tic tac toe game as a demonstration component. You can play the game with `M-x tui-play-tic-tac-toe`. Check out the source code with `M-x find-function “tui-play-tic-tac-toe”`.

Rendering content

If all goes well you should be able to require the library and render something to the buffer. The following will render a greeting at the point.

(tui-render-element "Hello world!")

Defining a component

Tui components are defined using `tui-define-component`.

Overview

Some familiarity with React should prove extremely helpful in using tui.el. I recommend checking out the introductory material on the React website. In particular- be sure to read the short primer on Thinking in React and the component lifecycle model (diagram).

Syntax

Tui offers an terse syntax for expressing content that roughly resembles the form of JSX. For instance, an expander control consists of a header and some content that is hidden when collapsed by the user:

(tui-expander
  :heading "A label for the following collapsible lorem ipsum content"
  "Curabitur lacinia pulvinar nibh. "
  "Fusce suscipit, wisi nec facilisis facilisis, est dui fermentum leo, quis tempor ligula erat quis odio. "
  "Sed id ligula quis est convallis tempor. ")

Inititial arguments as parsed key-value pairs and are passed as a plist to an element. A non-keyword-symbol following the property list and all following elements are treated as child elements. They are implicitly passed with the preceding plist properties as a value for :children. This avoids unnecessary repetition in typing :children.

(COMPONENT-NAME
  [[KEYWORD-PROP VALUE] ...]
  [CHILD-1 CHILD-2 ...])

The verbose equivalent to this syntax explicitly expresses the :children property. Note that multiple items must be enclosed by a single list or other element to follow the paired plist structure. The resulting content tree is identical to the previous example.

(tui-expander
  :heading "A label for the following collapsible lorem ipsum content"
  :children
  (list
    "Curabitur lacinia pulvinar nibh. "
    "Fusce suscipit, wisi nec facilisis facilisis, est dui fermentum leo, quis tempor ligula erat quis odio. "
    "Sed id ligula quis est convallis tempor. "))

Lists (and nil)

For convenience, lists may be used to arbitrarily group content. All lists are converted to tui-element nodes when the content is mounted. Null values may also be used arbitrarily. They are ignored at render time, so conditional code may return nil. Content is inserted in-order without separation, so while (list "foo" "bar" "baz") and (list (list "foo") nil (list "bar" "baz")) result in different content trees, they both render "foobarbaz".

The various forms of improper lists are currently not supported and are reserved for future use.

Text properties

To simplify styling, text properties may be applied to elements using the keyword :text-props. This property value should be a plist of text properties and their values. For example:

(tui-heading
  :text-props '(help-echo "Yup! This is a heading")
  "A heading!")

Comparison with React

ReactJS equivalents

ReactJS	tui.el
React.Component	tui-component
React.PureComponent	TODO
createElement()	tui-create-element
createFactory()	tui-define-component
cloneElement()	TODO
isValidElement()	tui-valid-element-p
React.Children	unnecessary (use tui-child-nodes)

Components

HTML-like components

(tui-div &key children)

(tui-heading &key children)

(tui-section &key children)

(tui-span &key children)

Other components

(tui-link &key target children)

(tui-icon &key icon-set icon-name)

(tui-buffer &key buffer children)

(tui-line &key children)

(tui-fixed-width &key children)

(tui-expander &key header initially-expanded children)

Future Work

Things I’m currently working on:

• [ ] Grid layout
• [ ] TUI Developer tools

Contributing

If you feel inspired by this little library, contact me on Twitter and let me know! The door is wide open for collaboration! If you have ideas for components I’d love to hear them.

Ideas

Here are a few things I have in mind in case you’re looking for an excuse to explore Emacs’ many features:

org-agenda

There are a lot of opportunities for customizing the org-mode agenda view that could be made possible with components designed for org-mode. Org-super-agenda offers striking examples of grouping agenda content into meaningful elements.

Structure editors

Structure editors are an exciting approach for editing source code and structured data. Build a set of components for representing and interacting with a syntax conceivably eliminates syntax errors altogether!

Charts and graphs

It would be very handy to have a variety of charts and graphs to visualize data within Emacs itself. Emacs already has a good start with the built-in chart.el for bar charts (examples). This would be a good application for drawille.el. Fancy animated charts like blessed-contrib anyone?

Virtual windows

There are circumstances where it would be useful to create divisions within a buffer/window without the behavior associated with additional windows. Imagine various tiled/floating window behavior demonstrated by blessed within a single buffer.

Touch-based interfaces

Why not give Emacs some big blocky buttons and sliders, so we can use our pervasive touchscreens with Emacs too? Or even: design progressive Emacs apps?

Running Tests

cask exec buttercup -L

Feedback

Requesting components

Suggestions

Button

Calendar

Dropdown

GitHub-style punchcard

Graphs/charts

Sparkline

Week

Related Projects

• Emacs
  • shr.el / eww
  • bui.el: Buffer interface library for Emacs
  • ewoc: “Emacs’s Widget for Object Collections”
• Non-Emacs
  • ncurses
  • A good list: Text-Based User Interfaces · Applied Go
  • vadimdemedes/ink: 🌈 React for interactive command-line apps
  • JoelOtter/termloop: Terminal-based game engine for Go, built on top …
  • VladimirMarkelov/clui: Command Line User Interface (Console UI inspi…
  • chjj/blessed: A high-level terminal interface library for node.js.
  • cznic/wm: Package wm is a terminal window manager.
  • gizak/termui: Golang terminal dashboard
  • gyscos/Cursive: A Text User Interface library for rust
  • jroimartin/gocui: Minimalist Go package aimed at creating Console Us…
  • marcusolsson/tui-go: A UI library for terminal applications.
  • ticki/termion: A bindless library for controlling terminals/TTY.
  • Yomguithereal/react-blessed: A react renderer for blessed.
  • manaflair/mylittledom: High-level DOM-like terminal interface library
  • fdehau/tui-rs: Build terminal user interfaces and dashboards using Rust
  • brick - A declarative terminal UI programming library written in Haskell
  • ceccopierangiolieugenio/pyTermTk: Python Terminal Toolkit