twk 0.1.0
twk: ^0.1.0 copied to clipboard
Flutter's widget model for terminal UIs in Dart: layout, text, focus, the mouse, scrolling, editing, overlays, navigation and animation.
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.