dart_pretext

A high-performance text analysis and line-layout engine for pure Dart.

This package contains the core pretext logic with zero Flutter UI dependencies, so it can run in:

  • Dart CLI tools
  • Server-side Dart
  • PDF/document generators
  • Any other pure Dart environment

flutter_pretext can build on top of this package for Flutter widget rendering while keeping layout math reusable everywhere.

Why this package exists

dart_pretext is the engine layer.

It separates text analysis, segmentation, measuring, and line breaking from framework-specific rendering, so you can reuse the same behavior across Flutter and non-Flutter runtimes.

Features

  • Pure Dart core (no Flutter SDK required)
  • Unicode-aware segmentation and grapheme handling
  • Configurable whitespace modes (normal, preWrap)
  • Cached text measurement for speed
  • Fast line counting without materializing line text
  • Optional line materialization with start/end cursors for custom rendering pipelines
  • Friendly to adapters (PDF, canvas, terminal, custom engines)

Installation

Add to your package dependencies:

dependencies:
  dart_pretext: ^1.1.0

Quick Start

1) Provide a Font adapter

dart_pretext only needs one method: segment width measurement.

import 'package:dart_pretext/dart_pretext.dart';

class MonospaceFont extends Font {
  final double charWidth;
  MonospaceFont(this.charWidth);

  @override
  double measureWidth(String seg) => seg.length * charWidth;
}

2) Prepare once, layout many times

import 'package:dart_pretext/dart_pretext.dart';

void main() {
  final font = MonospaceFont(8);

  final prepared = prepare(
    'This is a long paragraph that should wrap predictably.',
    font,
  );

  final summary = layout(prepared, 120, 20);
  print('lines: ${summary.lineCount}, height: ${summary.height}');

  final lines = layoutWithLines(prepared, 120, 20);
  for (final line in lines.lines) {
    print(line.text);
  }
}

API Overview

Main exports from package:dart_pretext/dart_pretext.dart:

  • Font: measurement abstraction
  • prepare(...): analyze text and precompute widths/break opportunities
  • layout(...): fast line count + total height
  • layoutWithLines(...): full line texts + cursor ranges
  • layoutNextLine(...): pull-based line iteration for dynamic widths
  • walkLineRanges(...): iterate ranges without allocating line strings
  • measureNaturalWidth(...): widest-line width when unconstrained
  • WhiteSpaceMode, SegmentBreakKind: analysis controls and metadata

Using with package:pdf

See example/pdf_example.dart for a complete adapter that maps package:pdf font metrics into dart_pretext.

Relationship with flutter_pretext

  • dart_pretext: core text engine for Dart SDK targets
  • flutter_pretext: Flutter widget layer that depends on dart_pretext

This separation keeps core layout deterministic and reusable in servers, CLI pipelines, and document rendering.

Publishing Notes

To maximize pub.dev score and publish confidence:

  • Keep README.md and CHANGELOG.md updated per release
  • Add a LICENSE file before publishing
  • Ensure pubspec.yaml links (homepage, repository, issue_tracker) point to the final repo
  • Run:
dart format .
dart analyze
dart test
dart pub publish --dry-run

Credits

Inspired by the original pretext ideas and geometry-first text layout approach by chenglou.

Libraries

dart_pretext