sh40-celadon 0.10.0

Celadon

A modern TUI library taking the right lessons from the web.

pip install sh40-celadon

Development Note

Since the project is in early stages a lot of optimization remains on the table. It already runs well on most machines, but certain domains (such as styling & layouts) might hog older computers.

This will be remedied in the future, once the related framework is in place to allow for more generalized testing.

Purpose

Celadon is a library for creating good looking and performant UIs in the terminal. While it is possible to use standalone, you generally wanna use it through a framework like celx.

Feature highlights

YAML Styling

Celadon includes a powerful CSS-inspired engine for styling your applications. It supports your basic #id, .group (.class in CSS land) selector primitives, as well as direct (Parent > Widget) and indirect hierarchal matching (Parent *> Widget, where Widget is a part of Parent but not necessarily a first-degree descendant).

It replaces CSS' notion of a 'pseudoclass' with a more direct notion of widget state, controlled by a state machine internal to all widgets.

Button:
    fill_style: '@ui.primary'
    # Automatically use either white or black, based on the W3C contrast
    # guidelines
    content_style: ''

    # On hover, become a bit brighter
    /hover: # Equivalent to 'Button/hover'
        fill_style: '@ui.primary+1'

    # Become a bit taller if in the 'big' group
    .big:
        height: 3

    # If part of a Row in the 'button-row' group, fill available width.
    # '&' stands for the selector in the previous nesting layer, `Button`
    # in this case.
    Row.button-row > &:
        width: null

A great layout system

Layouts are one of the biggest difficulties in any UI environment, especially on the web. We try to solve most of these issues by stripping down the amount of settings you need to be aware of (no more "align-items or justify-items?") and controlling almost all layout parameters within widget dimension settings.

A dimension can be one of three types:

• int: Sets a static size, i.e. button.width = 5 will make that button take up 5 cells of space horizontally, regardless of its parent's size.
• float: Sets a relative size to the parent's size of the same dimension, i.e. button.width = 0.5 will make the button be half the width of the parent.
• None: Sets a so-called fill height, meaning the parent will divide its space remaining after sizing the widgets with the previous two dimension types, and divide it evenly amongst the fill sized.

Exhibit A: Traditional 'web' Header-Body-Footer layout

app += Page(
    Tower(
        Row(
            Text("I mimick the web"),
            Text("For it cannot mimick me"),
            eid="header",
        ),
        Tower(Text.lorem(), eid="body", group="center"),
        Row(
            Button("Ctrl-C : Quit"),
            Button("F12 : Screenshot"),
            eid="footer",
        ),
    ),
    rules="""
    Tower#body:
        frame: [null, heavy, null, heavy]

    Row#header, Row#footer:
        alignment: [center, start]
        height: 1
""",
)

Here, specifying a static dimension for both header and footer's height allows the body to fill up the remaining space, and not specifying a width for either (leaving it to the default None) makes them take up the entire width.

Exhibit B: N*K grid

By making use of the fill dimension type, we can create responsive grids that work regardless of the amount of widgets we have in each column / row.

rows, cols = [10] * 2
grid = Tower(eid="grid")

for _ in range(rows):
    grid += Row(*[Button("Grid Item") for _ in range(cols)])

app += Page(
    grid,
    rules="""
    Tower#grid *> Button:
        width: null
        height: null

        # ...or, you could apply the pre-defined `fill` group to the widget
        groups: [fill]
""",
)

Documentation

Once the library gets to a settled state (near 1.0), documentation will be hosted both online and as a celx application. Until then peep the examples folder, or check out some of the widget references by using python3 -m pydoc <name>.

See also

• Slate: The terminal interfacing library that forms much of Celadon's backend.
• Zenith: The markup language & palette generator used for styling content in Celadon.
• celx: A hypermedia-driven TUI application framework written on top of Celadon.