artisanal #

A full-stack terminal toolkit for Dart, inspired by popular Go terminal libraries: Lip Gloss (styling), Bubble Tea (TUI framework), and Bubbles (reusable widgets).

Build everything from rich command-line tools to complex interactive TUI applications with a consistent, idiomatic Dart API.

Features #

Installation #

dependencies:
  artisanal: ^0.0.1

Note: This package uses workspace resolution. Use a path or git reference in standalone projects.

Library Exports #

Quick Start: CLI Output #

import 'package:artisanal/artisanal.dart';

Future<void> main() async {
  final io = Console();

  io.title('My App');
  io.section('Setup');
  io.info('Checking configuration...');

  await io.task('Running migrations', run: () async {
    await Future.delayed(const Duration(milliseconds: 200));
    return TaskResult.success;
  });

  io.table(
    headers: ['ID', 'Name', 'Status'],
    rows: [
      [1, 'users', io.style.success('DONE')],
      [2, 'posts', io.style.warning('PENDING')],
    ],
  );

  final proceed = io.confirm('Continue?', defaultValue: true);
  if (!proceed) return;

  io.success('All good.');
}

Quick Start: Styling (Lip Gloss) #

import 'package:artisanal/style.dart';

final style = Style()
    .bold()
    .foreground(Colors.purple)
    .padding(1, 2)
    .border(Border.rounded);

print(style.render('Hello, Artisanal!'));

Style Capabilities #

• Text effects: bold(), italic(), underline(), strikethrough(), dim(), inverse(), blink()
• Colors: ANSI 16, ANSI 256, TrueColor (RGB), AdaptiveColor (light/dark aware)
• Spacing: padding(), margin()
• Borders: rounded, thick, double, hidden, custom
• Alignment: align(), alignVertical()
• Dimensions: width(), height(), maxWidth(), maxHeight()
• Themes: ThemePalette with presets (dark, light, ocean, nord, dracula, monokai, solarized)

Quick Start: TUI (Elm Architecture) #

import 'package:artisanal/tui.dart';

class CounterModel implements Model {
  final int count;
  const CounterModel([this.count = 0]);

  @override
  Cmd? init() => null;

  @override
  (Model, Cmd?) update(Msg msg) {
    return switch (msg) {
      KeyMsg(key: Key(type: KeyType.up)) => (CounterModel(count + 1), null),
      KeyMsg(key: Key(type: KeyType.down)) => (CounterModel(count - 1), null),
      KeyMsg(key: Key(type: KeyType.runes, runes: [0x71])) => (this, Cmd.quit()),
      _ => (this, null),
    };
  }

  @override
  String view() => 'Count: \$count\n\nUse ↑/↓ to change, q to quit';
}

Future<void> main() async {
  await runProgram(CounterModel());
}

Bubbles (Reusable Widgets) #

Command Runner #

Build CLI tools with styled help and nested commands:

import 'package:artisanal/args.dart';

class HelloCommand extends Command {
  @override
  String get name => 'hello';
  
  @override
  String get description => 'Say hello';

  @override
  void run() {
    io.success('Hello, world!');
  }
}

void main(List<String> args) {
  final runner = CommandRunner('my-cli', 'A great CLI');
  runner.addCommand(HelloCommand());
  runner.run(args);
}

Ultraviolet Renderer #

High-performance rendering with diff-based updates for flicker-free TUI applications:

await runProgram(
  MyModel(),
  options: const ProgramOptions(
    useUltravioletRenderer: true,
    useUltravioletInputDecoder: true,
    altScreen: true,
    mouseTracking: true,
  ),
);

UV Features #

• 2D cell buffer with styled cells
• Diff-based terminal updates (minimal redraws)
• Layer composition and hit-testing
• Mouse support and focus events
• Graphics: Kitty, Sixel, iTerm2, half-block drawing

Console Methods #

Examples #

See the example/ directory for comprehensive demos:

• main.dart – Full feature showcase
• fluent_style_example.dart – Style API patterns
• spinner_demo.dart – Various spinner types
• lipgloss_table.dart – Styled tables
• log_viewer_demo.dart – Monitoring dashboard
• command_center_demo.dart – Multi-panel layouts
• uv_demo.dart – Ultraviolet renderer basics