# spance/tablegroup architecture

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

- Interactive diagram: https://gitdiagram.com/spance/tablegroup
- Repository: https://github.com/spance/tablegroup

## Overview

##### Project Type and Purpose
- This is a Java-based library designed for dynamically processing tabular data. It ingests 2D data (via a DataStore), applies various grouping rules (including cascaded and dependent grouping), builds an HTML element tree, and then renders a fully “merged” table complete with CSS-style modifications.
- The library is optimized for performance (see the CSS selector matching benchmarks) and aims to simplify the generation of complex tables—reducing the need for heavy, traditional reporting engines.

##### Main Components
- Data Input Module:
- DataStore implementations (e.g., SimpleDataStore) that abstract data ingestion. Indicate the “store” package (wong.spance.html.store) as the place where DataStore, RowIterator, and AbstractDataStore are implemented.

- Metadata and Configuration:
- TableMeta (invoked during TableGroup construction) where table columns and configuration are defined.
- This component is key for defining the blueprint that drives the grouping and rendering processes.

- Grouping Engine:
- Core grouping functionality provided by classes under the “merge” and “span” packages.
- The merge module (wong.spance.html.merge) encapsulates the logic for comparing individual cells (e.g., BasicCellComparator) and managing merge context.
- The span module (wong.spance.html.span) contains classes like RowSpan, CellSpan, SpanBy, etc. These classes capture grouping rules ranging from simple (on a single column) to cascaded (where grouping in subsequent columns is constrained by previous groups).

- HTML Element Tree Construction:
- Located in the “html/element” package, this part shows how the library builds a hierarchical structure of HtmlElement nodes (tables, rows, cells, header groups etc.).
- It forms the in-memory “DOM” that gets later rendered into the final HTML.

- Rendering and Modifier Engine:
- Found in the “html/render” package, where the RenderContext and multiple Modifier interfaces (BeforeRenderModifier, AfterRenderModifier, TextRenderModifier, DefaultModifiers, etc.) allow for customization of the HTML via CSS-like selectors.
- This module takes the HTML element tree and applies stylistic and attribute modifications according to parsed CSS selectors.

- CSS Selector Parsing and Matching:
- Within the “html/css” package, you have the CSS parsing and handling components (Selector, SelectorParser, Qualifier, IdQualifier, ClassNameQualifier, etc.) that are responsible for interpreting CSS strings and then matching them against the HTML element nodes.
- Even the performance metrics in the README illustrate that this matching system is high-performance.

- Statistics Module:
- Located under “html/stat”, this component (e.g., Statistics, StatisticsContext, StatisticsMatcher) focuses on computing summary statistics based on grouped data.
- It provides APIs to do simple aggregations (like sum) on the grouped results.

- Testing & Quality Assurance:

##### Relationships and Interaction Flows
- Data Flow:
- TableGroup uses the metadata (configured via TableMeta) to set up the table structure and grouping definitions.
- Grouping rules (from the merge and span modules) process this data to determine cells that can be merged (or grouped) based on specified columns.
- The outcome is a tree of HtmlElement objects (the DOM-like structure) built in the HTML Element Tree Construction module.

- Rendering Flow:
- Once the element tree is built, the rendering engine – which leverages the CSS Selector Parser/Matcher – applies modifiers. These modifiers (defined via different points of intervention like before or after rendering) adjust attributes, text, and styles as defined by the user (using a CSS selector syntax).
- Finally, the rendering layer produces the complete HTML output with all the grouping and styling results applied.

- Statistical Computation:
- Optionally, the Statistics Module is invoked to compute additional information (aggregations) from the grouped data, which could be delivered alongside the rendered table or to external components like charting libraries.

## Diagram (Mermaid)

```mermaid
flowchart TD
    DataInput["Data Input (DataStore)"]:::input
    TableMeta["Metadata & Configuration (TableMeta)"]:::config
    
    subgraph "Grouping Engine"
        G1["Merge Module"]:::grouping
        G2["Span Module"]:::grouping
        G1 --> G2
    end

    C["HTML Element Tree Builder"]:::builder
    R["Rendering & Modifier Engine"]:::rendering
    CSS["CSS Selector Parser/Matcher"]:::css
    S["Statistics Module"]:::stats

    DataInput --> TableMeta
    TableMeta --> G1
    G2 --> C
    G2 --> S
    C --> R
    CSS --> R

    click DataInput "https://github.com/spance/tablegroup/tree/master/src/main/java/wong/spance/html/store"
    click TableMeta "https://github.com/spance/tablegroup/blob/master/src/main/java/wong/spance/html/element/TableMeta.java"
    click G1 "https://github.com/spance/tablegroup/tree/master/src/main/java/wong/spance/html/merge"
    click G2 "https://github.com/spance/tablegroup/tree/master/src/main/java/wong/spance/html/span"
    click C "https://github.com/spance/tablegroup/tree/master/src/main/java/wong/spance/html/element"
    click R "https://github.com/spance/tablegroup/tree/master/src/main/java/wong/spance/html/render"
    click CSS "https://github.com/spance/tablegroup/tree/master/src/main/java/wong/spance/html/css"
    click S "https://github.com/spance/tablegroup/tree/master/src/main/java/wong/spance/html/stat"

    classDef input fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef config fill:#D7BDE2,stroke:#6C3483,stroke-width:2px;
    classDef grouping fill:#A9DFBF,stroke:#1E8449,stroke-width:2px;
    classDef builder fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef rendering fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef css fill:#D6EAF8,stroke:#2471A3,stroke-width:2px;
    classDef stats fill:#FAD7A0,stroke:#B9770E,stroke-width:2px;
```
