# charmbracelet/lipgloss architecture

> Architecture diagram of the GitHub repository charmbracelet/lipgloss, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/charmbracelet/lipgloss
- Repository: https://github.com/charmbracelet/lipgloss

## Overview

##### Main Components
- Rendering Utilities: Functions/methods that process and render the styled text – for instance, Render() functions, dimension measurement (Width(), Height()), and utilities for placing text.
- Specialized Sub-packages:
– Table Rendering: Located in the “table” directory, which provides functionality for constructing, styling, and rendering tables (see table.go, resizing.go, rows.go, etc.).
– List Rendering: Found in the “list” directory with support for enumerators and nesting.
– Tree Rendering: In the “tree” directory, which manages tree structures and renders hierarchical text layouts.
- Examples and Tests:
– The “examples” directory shows how the library is meant to be used, with real-world usage patterns (e.g., different style applications, table, list, and tree examples).
– Various *_test.go files throughout the project along with testdata folders validate outputs and ensure the integrity of rendering under different scenarios.

##### Relationships and Interactions
- The Core Styling Engine is at the heart of the library. It provides an API for users to build styles and then send strings through the Render() functions to produce styled terminal output.
- Each specialized sub-package (table, list, tree) builds on the core engine – inheriting styles and applying additional rendering logic specific to their layout semantics.
- The examples illustrate how these components are composed; they often import the main package (lipgloss) along with the sub-packages to showcase a complete TUI setup.

##### Architectural Patterns and Design Principles
- Declarative API: The library uses a fluent (chainable) API to allow users to define styling in a way similar to CSS.
- Separation of Concerns: The core styling is decoupled from the table, list, and tree rendering logic.
- Modularity: Each sub-component (core, table, list, tree) is organized in its own package, making the project both extensible and maintainable.

##### Technologies and Frameworks Involved
- Language: Go, which influences how packages, modules, and tests are structured.
- CI/CD and Quality Tools: Notice the GitHub workflows for build, lint, test coverage, etc., which indicate an automated testing and release process.

##### Specific Elements
- Create distinct nodes for:
- Table Sub-package (table/table.go, table/resizing.go, etc.)
- Sub-package (list/list.go, enumerator.go)
- Tree Sub-package (tree/tree.go, renderer.go)
- Example Applications (from the “examples” directory)
- Test Suites (various *_test.go files and testdata directories)
- Input (user-defined style configuration) → Core Styling API → Sub-package Renderers → Terminal Output
- Inheritance flow (e.g., styles inheriting from base style definitions).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Nodes
    User["User Style Config"]:::input
    Terminal["Terminal Output"]:::output
    Externals["External Dependencies: Termenv & Reflow"]:::external

    %% Core Styling Engine Subgraph
    subgraph "Core Styling Engine"
        Style["style.go"]:::core
        Align["align.go"]:::core
        Color["color.go"]:::core
        Borders["borders.go"]:::core
    end

    %% Core Rendering Utilities Node
    Renderer["renderer.go"]:::core

    %% Table Rendering Subgraph
    subgraph "Table Rendering"
        TableGo["table.go"]:::table
        Resizing["resizing.go"]:::table
        Rows["rows.go"]:::table
    end

    %% List Rendering Subgraph
    subgraph "List Rendering"
        ListGo["list.go"]:::list
        Enumerator["enumerator.go"]:::list
    end

    %% Tree Rendering Subgraph
    subgraph "Tree Rendering"
        TreeGo["tree.go"]:::tree
        TreeRenderer["renderer.go"]:::tree
    end

    %% Examples Node
    Examples["Examples"]:::example

    %% Test Suites Subgraph
    subgraph "Test Suites"
        TestCore["Core Tests"]:::test
        TestTable["Table Tests"]:::test
        TestList["List Tests"]:::test
        TestTree["Tree Tests"]:::test
    end

    %% Data Flow Connections
    User --> Style
    User --> Align
    User --> Color
    User --> Borders

    Style --> Renderer
    Align --> Renderer
    Color --> Renderer
    Borders --> Renderer

    Renderer --- TableGo
    Renderer --- ListGo
    Renderer --- TreeGo

    TableGo --> Resizing
    Resizing --> Rows
    Rows --> Terminal

    ListGo --> Enumerator
    Enumerator --> Terminal

    TreeGo --> TreeRenderer
    TreeRenderer --> Terminal

    %% Examples interact with Core and Sub-packages
    Examples --- Style
    Examples --- TableGo
    Examples --- ListGo
    Examples --- TreeGo

    %% Test Suites validation connections
    TestCore --- Style
    TestTable --- TableGo
    TestList --- ListGo
    TestTree --- TreeGo

    %% External dependencies support
    Externals --- Style

    %% Click Events for Core Styling Engine Files
    click Style "https://github.com/charmbracelet/lipgloss/blob/master/style.go"
    click Align "https://github.com/charmbracelet/lipgloss/blob/master/align.go"
    click Color "https://github.com/charmbracelet/lipgloss/blob/master/color.go"
    click Borders "https://github.com/charmbracelet/lipgloss/blob/master/borders.go"

    %% Click Event for Core Rendering Utilities
    click Renderer "https://github.com/charmbracelet/lipgloss/blob/master/renderer.go"

    %% Click Events for Table Rendering Sub-package Files
    click TableGo "https://github.com/charmbracelet/lipgloss/blob/master/table/table.go"
    click Resizing "https://github.com/charmbracelet/lipgloss/blob/master/table/resizing.go"
    click Rows "https://github.com/charmbracelet/lipgloss/blob/master/table/rows.go"

    %% Click Events for List Rendering Sub-package Files
    click ListGo "https://github.com/charmbracelet/lipgloss/blob/master/list/list.go"
    click Enumerator "https://github.com/charmbracelet/lipgloss/blob/master/list/enumerator.go"

    %% Click Events for Tree Rendering Sub-package Files
    click TreeGo "https://github.com/charmbracelet/lipgloss/blob/master/tree/tree.go"
    click TreeRenderer "https://github.com/charmbracelet/lipgloss/blob/master/tree/renderer.go"

    %% Click Event for Examples
    click Examples "https://github.com/charmbracelet/lipgloss/tree/master/examples"

    %% Click Events for Test Suites
    click TestCore "https://github.com/charmbracelet/lipgloss/blob/master/align_test.go"
    click TestTable "https://github.com/charmbracelet/lipgloss/blob/master/table/table_test.go"
    click TestList "https://github.com/charmbracelet/lipgloss/blob/master/list/list_test.go"
    click TestTree "https://github.com/charmbracelet/lipgloss/blob/master/tree/tree_test.go"

    %% Styles
    classDef input fill:#f9e79f,stroke:#000,stroke-width:1px;
    classDef core fill:#aed6f1,stroke:#000,stroke-width:1px;
    classDef table fill:#d5f5e3,stroke:#000,stroke-width:1px;
    classDef list fill:#fcf3cf,stroke:#000,stroke-width:1px;
    classDef tree fill:#f5cba7,stroke:#000,stroke-width:1px;
    classDef output fill:#d6eaf8,stroke:#000,stroke-width:1px;
    classDef example fill:#fadbd8,stroke:#000,stroke-width:1px;
    classDef test fill:#e8daef,stroke:#000,stroke-width:1px;
    classDef external fill:#d1f2eb,stroke:#000,stroke-width:1px;
```
