style library Style

Fluent styling system for terminal text (Lip Gloss for Dart).

This library provides a powerful, declarative styling system for terminal applications. It allows you to define styles for text, borders, padding, margins, and alignment using a fluent API.

Key Concepts

  • Style: The primary entry point for defining text formatting.
  • Color: Support for ANSI 16, ANSI 256, and TrueColor (RGB).
  • Layout: Utilities for joining styled blocks horizontally or vertically.
  • Border: Predefined and custom border styles for boxes.
  • List: Support for styled bulleted or numbered lists.
  • Table: Support for rendering data in styled grids.

Usage

import 'package:artisanal/style.dart';

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

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

Fluent Styling

Artisanal Style uses a fluent, immutable API inspired by Lip Gloss. Each method call returns a new Style instance with the property applied, allowing for easy composition and reuse.

Styles can include:

  • Text effects (bold, italic, underline, strikethrough)
  • Colors (foreground, background, underline color)
  • Spacing (padding, margin)
  • Borders (rounded, thick, double, etc.)
  • Alignment (horizontal and vertical)

Colors and Profiles

Colors in Artisanal are profile-aware. The ColorProfile determines how colors are rendered (ANSI 16, ANSI 256, or TrueColor).

Layout and Composition

Use the Layout class to join multiple styled blocks together:

  • Layout.joinHorizontal: Place blocks side-by-side.
  • Layout.joinVertical: Stack blocks on top of each other.

You can also use Style.width and Style.height to create fixed-size boxes with alignment.

Artisanal Style uses a fluent, immutable API inspired by Lip Gloss. Each method call returns a new Style instance with the property applied, allowing for easy composition and reuse.

Styles can include:

  • Text effects (bold, italic, underline, strikethrough)
  • Colors (foreground, background, underline color)
  • Spacing (padding, margin)
  • Borders (rounded, thick, double, etc.)
  • Alignment (horizontal and vertical)

Colors in Artisanal are profile-aware. The ColorProfile determines how colors are rendered (ANSI 16, ANSI 256, or TrueColor).

Use the Layout class to join multiple styled blocks together:

  • Layout.joinHorizontal: Place blocks side-by-side.
  • Layout.joinVertical: Stack blocks on top of each other.

You can also use Style.width and Style.height to create fixed-size boxes with alignment.

Classes

AdaptiveColor
An adaptive color that switches based on terminal background.
Align
Combined alignment for both horizontal and vertical positioning.
AnsiColor
An explicit ANSI color code (0-255).
ArcSegments
Arc segment and circle-segment characters for spinning animations (U+25D8–U+25E1).
Arrows
Common arrow glyphs used in key help and navigation labels.
BasicColor
A color specified as a hex string or ANSI string code.
BlockMedium
Medium-weight block elements (U+25B0–U+25B1).
BlockQuadrants
Quadrant block glyphs for sub-pixel rendering (U+2596–U+259F).
BlockShades
Block shade characters (U+2580–U+259F).
Border
Defines the characters used to draw borders.
BorderSides
Controls which sides of a border are visible.
BoxMetrics
BrailleChars
Braille pattern characters for progress indicators.
Circles
Circle glyphs (U+25CB–U+25D5).
Color Style
Abstract base class for terminal colors.
Colors
Semantic and named color presets.
CompleteAdaptiveColor
A color with explicit values for each profile, with light and dark variants.
CompleteColor
A color with explicit values for each color profile.
ConsoleTagParser
Parser for console-style tags.
DefaultColor
The terminal default color.
DotChars
Dot and marker characters.
EllipsisChars
Miscellaneous singleton punctuation glyphs.
InteractiveStyle
Style set for interactive states.
KeyboardChars
Common keyboard glyphs used in key help labels.
Layout
Layout utilities for composing rendered blocks.
LipList
A fluent, chainable list builder inspired by Go's lipgloss list.
ListEnumerators
Predefined list enumerators.
ListIndenters
Predefined list indenters.
ListItem
A single item in a list.
ListItems
Provides access to list items for style/enumerator functions.
Margin
Represents margin (external spacing) for styled content.
NoColor
No color (absence of color styling).
Padding
Represents padding (internal spacing) for styled content.
PaginationDots
Pagination dot characters.
PanelBoxChars
Box drawing characters for panels and borders.
PanelBoxCharSet
A set of box drawing characters.
Ranges
A collection of StyleRanges that can be applied to a string.
RenderContext
ResponsiveBreakpoints
Configurable responsive thresholds with helpers for breakpoint branching.
ScannerChars
Predefined scanner animation character sets.
ScannerCharSet
Character pair for a scanner (Knight Rider) animation style.
SparkBars
Sparkline bar characters (U+2581–U+2588).
SparseBlocks
Sparse block shapes (U+25A0–U+25AB).
StatusChars
Status indicator symbols.
Style Style
Fluent, chainable style builder for terminal output.
StyleData
StyledSegment
A styled segment containing child segments.
StyleRange
A range of visible cells and an associated Style to apply.
TagSegment
A parsed segment of tagged text.
TextSegment
Plain text segment (no tags).
ThemePalette
A semantic color palette for theming TUI applications.
Triangles
Triangular indicator glyphs (U+25B2–U+25C0).
WhitespaceOptions
Options for rendering whitespace in layout functions.

Enums

BoxSizing
ColorProfile
Color profile indicating terminal color capabilities.
HorizontalAlign
Horizontal alignment options.
LayoutBreakpoint
Breakpoint names for responsive terminal layouts.
UnderlineStyle
Underline style for terminal cells.
VerticalAlign
Vertical alignment options.

Extensions

HorizontalAlignPosition on HorizontalAlign
Extension to convert HorizontalAlign to a fractional position.
StyleConvenienceExtensions on Style
Convenience extensions for common semantic styles.
VerticalAlignPosition on VerticalAlign
Extension to convert VerticalAlign to a fractional position.

Properties

Writer ↔ Renderer
getter/setter pair

Functions

bestTextColor(Color background, {List<Color> candidates = const [Colors.black, Colors.white], bool hasDarkBackground = true}) → Color
Picks the candidate color with the highest contrast against background.
blend1D(int steps, List<Color> stops, {required bool hasDarkBackground}) → List<Color>
Blends a series of Color stops into steps colors (1D gradient).
blend2D(int width, int height, double angle, List<Color> stops, {required bool hasDarkBackground}) → List<Color>
Blends a series of Color stops into a 2D gradient.
blendColor(Color from, Color to, double t, {required bool hasDarkBackground}) → Color
Blends two colors into a single interpolated color.
contrastRatio(Color foreground, Color background, {bool hasDarkBackground = true}) → double
Computes the WCAG contrast ratio of foreground vs background.
cutAnsiByCells(String s, int start, int end) → String
Cuts an ANSI string by visible cell indices, preserving any active SGR/OSC 8 state at the start boundary.
Fprint(IOSink sink, Iterable<Object?> values) → int
Fprintf(IOSink sink, String format, List<Object?> args) → int
Fprintln(IOSink sink, Iterable<Object?> values) → int
isDarkColorRgb({required int red, required int green, required int blue}) → bool
Returns true when the supplied sRGB color is dark enough to prefer white text.
meetsWcagAa(Color foreground, Color background, {bool largeText = false, bool hasDarkBackground = true}) → bool
Returns true when colors satisfy WCAG AA contrast requirements.
meetsWcagAaa(Color foreground, Color background, {bool largeText = false, bool hasDarkBackground = true}) → bool
Returns true when colors satisfy WCAG AAA contrast requirements.
overlayBackgroundRangesPreservingAnsi(String s, Iterable<StyleRange> ranges) → String
Applies range backgrounds to an ANSI string while preserving existing text styling inside those ranges.
Print(Object? v1, [Object? v2, Object? v3, Object? v4, Object? v5, Object? v6]) → int
PrintAll(Iterable<Object?> values) → int
Printf(String format, [Object? v1, Object? v2, Object? v3, Object? v4, Object? v5, Object? v6]) → int
Println([Object? v1, Object? v2, Object? v3, Object? v4, Object? v5, Object? v6]) → int
PrintlnAll(Iterable<Object?> values) → int
relativeLuminance(Color color, {bool hasDarkBackground = true}) → double
Returns WCAG-style relative luminance for a color.
relativeLuminanceRgb(int red, int green, int blue) → double
Returns WCAG-style relative luminance for explicit sRGB channels.
resetWriter() → void
Sprint(Object? v1, [Object? v2, Object? v3, Object? v4, Object? v5, Object? v6]) → String
SprintAll(Iterable<Object?> values) → String
Sprintf(String format, [Object? v1, Object? v2, Object? v3, Object? v4, Object? v5, Object? v6]) → String
SprintfAll(String format, List<Object?> args) → String
Sprintln([Object? v1, Object? v2, Object? v3, Object? v4, Object? v5, Object? v6]) → String
SprintlnAll(Iterable<Object?> values) → String
stringForProfile(String input, ColorProfile profile) → String
styleRanges(String s, Iterable<StyleRange> ranges) → String
Styles ranges in an ANSI string.
styleRunes(String s, Style styler(int rune, int index)) → String
Styles individual runes in a string using a styler function.

Typedefs

ListEnumeratorFunc = String Function(ListItems items, int index)
Callback for generating the enumerator string for a list item.
ListIndenterFunc = String Function(ListItems items, int index)
Callback for generating indentation for nested items.
ListStyleFunc = Style Function(ListItems items, int index)
Callback for determining the style of a list item.