Skip to content

dwgx/SmartCLI / skills/tui-ui

tui-ui

Verified

Design web-like user interfaces in the terminal and inside tmux with a cell-grid Canvas, CSS-like box model, flexbox/grid layout, and 17 reusable widgets such as Panel, Table, Card, ProgressBar, Meter, Tabs, Tree, Badge, Banner, and a braille line chart. Use when an agent needs a dashboard, panel, table, status page, TUI layout, tmux dashboard, screenshot-driven CLI/TUI replica, ANSI frame, truecolor render, pyte PNG screenshot smoke test, wide-character alignment, or a new terminal widget.

"""ui CLI: widgets | demo | gallery.

Run as a package from ``skills/tui-ui``::

    python -m ui widgets
    python -m ui demo table --width 80 --height 12 --theme dashboard
    python -m ui gallery --width 120 --height 40

or by path (the PEP-366 prelude makes the direct form work from any cwd)::

    python skills/tui-ui/ui/cli.py gallery

Every command renders ONCE to stdout and exits — bounded, no loop. Output is a
tmux-safe ANSI string (SGR + newlines) you can pipe, print, or feed to the
pyte->PNG harness.
"""
from __future__ import annotations

import os
import sys

if __package__ in (None, ""):  # executed by path: bootstrap the ui package
    sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
    __package__ = "ui"
    import ui  # noqa: F401

import argparse

from . import registry
from .box import Box, Fr
from .core import get_theme, theme_names
from .layout import Grid, HStack, Page, VStack, grid


def _ensure_utf8():
    try:
        enc = (getattr(sys.stdout, "encoding", "") or "").lower()
        if enc.replace("-", "") not in ("utf8", "utf8mb4"):
            sys.stdout.reconfigure(encoding="utf-8", errors="replace")
    except Exception:
        pass


def _enable_vt():
    _ensure_utf8()
    if os.name == "nt":
        try:
            import ctypes
            k = ctypes.windll.kernel32
            h = k.GetStdHandle(-11)
            import ctypes as _c
            mode = _c.c_uint32()
            if k.GetConsoleMode(h, _c.byref(mode)):
                k.SetConsoleMode(h, mode.value | 0x0001 | 0x0004)
        except Exception:
            os.system("")


# --------------------------------------------------------------------------
# commands
# --------------------------------------------------------------------------
def cmd_widgets(args) -> int:
    widgets = registry.all_widgets()
    if args.json:
        import json
        print(json.dumps([{"key": w.key, "summary": getattr(w, "summary", "")}
                          for w in widgets], indent=2))
    else:
        wkey = max((len(w.key) for w in widgets), default=4)
        for w in widgets:
            print(f"{w.key:<{wkey}}  {getattr(w, 'summary', '')}")
    for mod, _tb in registry.load_errors():
        print(f"warning: {mod} failed to import", file=sys.stderr)
    return 0


def cmd_demo(args) -> int:
    _enable_vt()
    theme = get_theme(args.theme)
    try:
        cls = registry.get(args.name)
    except KeyError as exc:
        raise SystemExit(f"error: {exc.args[0]}")
    widget = cls.sample(theme)
    # Wrap in a titled panel-ish box so the demo shows the widget in context.
    page = Page(Box(content=widget, padding=(0, 0), bg=theme.bg),
                width=args.width, height=args.height, bg=theme.bg)
    print(page.to_ansi())
    return 0


def _build_gallery(theme, width, height):
    """Compose a web-like dashboard 'page' from several widgets.

    Layout (top->bottom): a banner header, a badge status row, a middle region
    (left column = Resources meter + Files tree; right = Services table), a Tabs
    detail panel, and a Deploy progress footer. Fixed heights are chosen so each
    bordered box gets enough rows; the middle table flexes to fill the width.
    """
    from .widgets import (Badge, Banner, Meter, ProgressBar, Table, Tabs, Tree)

    def panel(content, title, h=None, border="single", w=None):
        return Box(content=content, border=border, title=title, padding=(0, 1),
                   bg=theme.bg, fg=theme.fg, border_fg=theme.border,
                   height=h, width=w if w is not None else "auto")

    banner = Banner("DASH", theme=theme)
    bh = banner.measure(width, 10)[1]
    header = Box(content=banner, padding=(0, 1), border="rounded",
                 border_fg=theme.accent, bg=theme.bg, height=bh + 2)

    status_row = Box(content=HStack([
        Box(content=Badge("ONLINE", kind="ok", theme=theme), bg=theme.bg, width="auto"),
        Box(content=Badge("3 ALERTS", kind="warn", theme=theme), bg=theme.bg, width="auto"),
        Box(content=Badge("v2.4.1", kind="accent", theme=theme), bg=theme.bg, width="auto"),
    ], gap=1), bg=theme.bg, height=1)

    resources = panel(Meter(theme=theme), "Resources", h=5)
    filetree = panel(Tree(theme=theme), "Files", h=Fr(1))
    services = panel(Table(theme=theme), "Services", w=Fr(1))
    mid = HStack([VStack([resources, filetree], gap=0), services], gap=1)

    tabs = panel(Tabs.sample(theme), "Details", h=6, border="rounded")
    footer = panel(ProgressBar(0.73, label="Deploy", theme=theme), "Progress",
                   h=3, border="rounded")

    # Give the middle region the leftover rows so nothing clips.
    fixed = (bh + 2) + 1 + 6 + 3
    mid_h = max(6, height - fixed)
    mid_box = Box(content=mid, bg=theme.bg, height=mid_h)

    root = VStack([header, status_row, mid_box, tabs, footer], gap=0, bg=theme.bg)
    return Page(root, width=width, height=height, bg=theme.bg)


def cmd_gallery(args) -> int:
    _enable_vt()
    theme = get_theme(args.theme)
    page = _build_gallery(theme, args.width, args.height)
    print(page.to_ansi())
    return 0


def _demo_raster(cols: int, rows: int):
    """A small self-contained RGB test image (no PIL): a smooth hue/brightness
    gradient with a bright disc, so `ui sixel` shows something without a file."""
    from .raster import SubcellRaster
    r = SubcellRaster(cols, rows, "quad")
    pw, ph = max(1, r.pw), max(1, r.ph)
    for y in range(r.ph):
        for x in range(r.pw):
            red = int(255 * x / pw)
            grn = int(255 * y / ph)
            blu = int(255 * (1 - x / pw))
            r.px[y][x] = (red, grn, blu)
    # a white disc so a shape is visible
    cx, cy, rad = r.pw / 2, r.ph / 2, min(r.pw, r.ph) / 4
    r.disc(cx, cy, rad, (255, 255, 255))
    return r


def cmd_sixel(args) -> int:
    _enable_vt()
    from .sixel import raster_to_sixel, supports_sixel

    if args.probe:
        res = supports_sixel()
        label = {True: "yes", False: "no", None: "unknown"}[res]
        print(f"sixel support (DA1 probe): {label}")
        return 0

    if args.image:
        from .raster import from_image
        try:
            raster = from_image(args.image, args.cols, args.rows, mode=args.mode)
        except RuntimeError as exc:  # PIL missing — clear message, not a traceback
            print(f"error: {exc}", file=sys.stderr)
            return 2
    else:
        raster = _demo_raster(args.cols, args.rows)

    sys.stdout.write(raster_to_sixel(raster))
    sys.stdout.write("\n")
    sys.stdout.flush()
    return 0


# --------------------------------------------------------------------------
# parser
# --------------------------------------------------------------------------
def build_parser() -> argparse.ArgumentParser:
    p = argparse.ArgumentParser(
        prog="ui",
        description="HTML/CSS-like terminal layout engine + web-style widgets.")
    sub = p.add_subparsers(dest="command", required=True)

    sp = sub.add_parser("widgets", help="list registered widgets")
    sp.add_argument("--json", action="store_true")
    sp.set_defaults(func=cmd_widgets)

    sp = sub.add_parser("demo", help="render one widget sample to stdout")
    sp.add_argument("name", help="widget key (see 'widgets')")
    sp.add_argument("--width", type=int, default=60)
    sp.add_argument("--height", type=int, default=12)
    sp.add_argument("--theme", help=f"palette ({', '.join(theme_names())})")
    sp.set_defaults(func=cmd_demo)

    sp = sub.add_parser("gallery", help="render a composed dashboard 'page'")
    sp.add_argument("--width", type=int, default=100)
    sp.add_argument("--height", type=int, default=30)
    sp.add_argument("--theme", help=f"palette ({', '.join(theme_names())})")
    sp.set_defaults(func=cmd_gallery)

    sp = sub.add_parser("sixel",
                        help="emit a Sixel bitmap (true graphics) for a terminal "
                             "that supports it (Windows Terminal >=1.22, xterm, "
                             "WezTerm, mlterm). With no image, draws a demo gradient.")
    sp.add_argument("image", nargs="?",
                    help="image file to render (PNG/JPG via Pillow); omit for a demo")
    sp.add_argument("--cols", type=int, default=40, help="width in terminal cells")
    sp.add_argument("--rows", type=int, default=20, help="height in terminal cells")
    sp.add_argument("--mode", default="quad",
                    choices=("half", "quad", "sextant", "braille"),
                    help="sub-cell pixel density used to sample the image")
    sp.add_argument("--probe", action="store_true",
                    help="just report whether this terminal advertises sixel (DA1)")
    sp.set_defaults(func=cmd_sixel)

    return p


def main(argv=None) -> int:
    args = build_parser().parse_args(argv)
    registry.load_all()
    return args.func(args)


if __name__ == "__main__":
    sys.exit(main())
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 321kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 321kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 321kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 197kUpdated Claude CodeCodexVerifiedInstall