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.
Features
- Layout:
Row,Column,FlexwithExpandedandFlexible,Stack,Grid,Wrap,Padding,Align,SizedBox,Boxwith borders and titles, andSplitView. - Text:
TextandText.richwith 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,
KeyBindingsandShortcuts, 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, andFormwith validatedFormFields. - Overlays: dialogs, menus, a menu bar, context menus, toasts, a command palette and tooltips.
- Navigation and controls:
Navigatorwith routes, tabs, buttons, switches, checkboxes, radio buttons, sliders, progress bars and spinners. - Animation and theming: tickers, animation controllers and implicit
animations;
Themewith 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.
- 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. - 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.