twk

Flutter's widget model for terminal UIs in Dart. Widgets, elements and State behave as in Flutter: StatelessWidget, StatefulWidget, setState, InheritedWidget, keys, LayoutBuilder. Everything is measured in cells. Under the widgets is twk_core, a rendering core that writes only the cells that changed.

The Table page of the twk gallery, dark theme

Features

  • Layout: Row, Column, Flex with Expanded and Flexible, Stack, Grid, Wrap, Padding, Align, SizedBox, Box with borders and titles, and SplitView.
  • Text: Text and Text.rich with styled spans, wrapping and ellipsis, links, and bidirectional text; the output of a command with ANSI escape sequences read into spans (parseAnsi, AnsiStream).
  • Input: a focus tree with Tab traversal, KeyBindings and Shortcuts, and the mouse through a hit test (Listener, hover, drag, the wheel).
  • Scrolling and data: ListView, Table (also over a data source), TreeView, Scrollbar, charts, sparklines and gauges.
  • Editing: TextField, multi-line text areas, and Form with validated FormFields.
  • Overlays: dialogs, menus, a menu bar, context menus, toasts, a command palette and tooltips.
  • Navigation and controls: Navigator with routes, tabs, buttons, switches, checkboxes, radio buttons, sliders, progress bars and spinners.
  • Animation and theming: tickers, animation controllers and implicit animations; Theme with dark and light themes, chosen from the terminal's background.
  • Screen modes: fullscreen, inline below the shell's history (lines committed into the scrollback with Static), or a fixed viewport.
  • Accessibility and debugging: semantics and a screen-reader mode; a frame overlay, repaint rainbow, log console and tree dumps.
  • State: hooks in the flutter_hooks style (package:twk/hooks.dart) and Provider's API (package:twk/provider.dart), each a library of its own.
  • Command-line tools: a console for a tool that is no app (package:twk/cli.dart): messages by level, any widget printed, prompts and progress, as a terminal, a pipe or CI takes them.
  • The web: an app builds with dart2wasm and runs on xterm.js.

Getting started

dart pub add twk

A counter: Up counts, q quits (example/counter.dart):

import 'package:twk/twk.dart';

Future<void> main(List<String> args) => runApp(
  const Counter(),
  mode: args.contains('--inline') ? .inline : .fullscreen,
);

final class Counter extends StatefulWidget {
  const Counter({super.key});

  @override
  State<Counter> createState() => _CounterState();
}

final class _CounterState extends State<Counter> {
  var _n = 0;

  @override
  Widget build(BuildContext context) => KeyBindings(
    {
      'up': () => setState(() => _n++),
      'q': () => AppBinding.of(context).quit(),
    },
    child: Box(
      border: const .all(type: .rounded),
      titles: const [
        BorderTitle(' up: count  q: quit ', alignment: .bottomRight),
      ],
      padding: const .all(1),
      child: Text.rich(['Count: '.dim, '$_n'.bold.fg(.green)]),
    ),
  );
}

dart run example/counter.dart runs it on the alternate screen; with --inline it runs below the shell's prompt and stays in the history when it quits.

The examples include larger apps: a chat with a list, a text field and focus; settings with menus, tabs, a form, a dialog and toasts; a process monitor with a sorted table and a tree; an operations dashboard of live figures, a chart, a heatmap and a log; and a file manager with two panes.

Testing

Apps are tested with testTwk from twk_test (dart pub add dev:twk_test): the app runs on a terminal in memory under a fake clock, keys and the mouse go in as the bytes a terminal sends, and the screen is read back through a strict emulator.

testTwk('Up counts', (t) async {
  await t.pumpWidget(const Counter(), size: (24, 6));
  await t.press('up up up');
  await t.pump();
  expect(t, containsLine('│ Count: 3             │'));
});

Learn more

  • Guides: getting started, layout, input and focus, theming, screen modes, state and testing.
  • Widget catalog: every widget with its pictures, its code and its options.
  • Reference: every topic, widget and parameter, and how the package is tested.
  • The gallery: every widget live, with its options and the Dart that builds it.
  • SKILL.md: a guide for coding agents that build apps with twk.
  • twk_core: the rendering core, and its platforms and limitations.

License

MIT. The colors of ThemeData.nord are those of Nord, Copyright (c) 2016-present Sven Greb, and those of ThemeData.catppuccinMocha and ThemeData.catppuccinLatte those of Catppuccin, Copyright (c) 2021 Catppuccin, each under the MIT License: NOTICE.

Libraries

cli
A console for command-line tools on twk: messages by channel and level, styled as the terminal takes them, any twk widget shown in the output, and, in the interactive mode, one inline twk app that prompts and progress are live in while finished output is committed above them.
format
How the widgets write sizes and times, for an app to write them the same way: formatBytes a size in decimal (4.1 kB) or binary units (ByteUnits.binary, 4.0 KiB), and formatTook the time something took (3.1 s, 01:05).
hooks
Hooks for widgets of the twk package, in the flutter_hooks style: state, effects, memoized values, listenables, streams, futures, animations and controllers that a build keeps by calling functions (useState, useEffect, …), over the framework's elements.
log
The log of an app: log records a message, with its LogLevel, and a LogSink keeps what is recorded as LogRecords.
provider
Provider for widgets of the twk package, as package:provider is for Flutter's: values provided to a subtree and found by their type (context.read, context.watch, context.select), the widgets that depend on them rebuilt when they change.
twk
Widgets for terminal UIs on top of the twk_core rendering core.