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).
BasicColor
A color specified as a hex string or ANSI string code.
Border
Defines the characters used to draw borders.
BorderSides
Controls which sides of a border are visible.
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.
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.
Ranges
A collection of StyleRanges that can be applied to a string.
Style Style
Fluent, chainable style builder for terminal output.
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.
WhitespaceOptions
Options for rendering whitespace in layout functions.

Enums

ColorProfile
Color profile indicating terminal color capabilities.
HorizontalAlign
Horizontal alignment options.
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
Global writer used by Print/Println/Printf, defaulting to stdout.
getter/setter pair

Functions

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.
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
Prints values to a specific sink without trailing newline.
Fprintf(IOSink sink, String format, List<Object?> args) → int
Prints formatted output to a specific sink.
Fprintln(IOSink sink, Iterable<Object?> values) → int
Prints values to a specific sink with trailing newline.
Print(Object? v1, [Object? v2, Object? v3, Object? v4, Object? v5, Object? v6]) → int
Prints values to Writer without a trailing newline.
PrintAll(Iterable<Object?> values) → int
Prints all values in values without separators or newline.
Printf(String format, [Object? v1, Object? v2, Object? v3, Object? v4, Object? v5, Object? v6]) → int
Prints formatted output to Writer.
Println([Object? v1, Object? v2, Object? v3, Object? v4, Object? v5, Object? v6]) → int
Prints values to Writer with a trailing newline.
PrintlnAll(Iterable<Object?> values) → int
Prints all values in values with space separators and trailing newline.
resetWriter() → void
Resets Writer back to a new terminal writer targeting stdout.
Sprint(Object? v1, [Object? v2, Object? v3, Object? v4, Object? v5, Object? v6]) → String
Returns concatenated values as a string (no trailing newline).
SprintAll(Iterable<Object?> values) → String
Returns all values in values concatenated without separators.
Sprintf(String format, [Object? v1, Object? v2, Object? v3, Object? v4, Object? v5, Object? v6]) → String
Returns formatted string.
SprintfAll(String format, List<Object?> args) → String
Returns formatted string using all args.
Sprintln([Object? v1, Object? v2, Object? v3, Object? v4, Object? v5, Object? v6]) → String
Returns concatenated values as a string with trailing newline.
SprintlnAll(Iterable<Object?> values) → String
Returns all values in values concatenated with spaces and newline.
stringForProfile(String input, ColorProfile profile) → String
Returns input processed for the given profile.
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.