---
title: Table Rendering & UI
---

# Specification: Table Rendering & UI

## Scope

Defines how the repository overview is transformed into a Markdown table (plus optional group headings) which is then embedded by higher-level renderers (see [Renderers](./spec_renderer_markdown.md)).

---

## 1. Input Contract

* **Rows** – any ordered collection of key→row mappings *or* a sequence of `(key,row)` tuples. Each *row* is a mapping from column-key to cell value.
* **Column Configuration** – ordered list where each entry contains:
  * `key` – the column key present in rows (string). Mandatory.
  * `label` – heading text shown in the table (string). Optional, defaults to key.
  * `visible` – whether the column appears (boolean). Optional, defaults to true.
* **Groups (optional)** – mapping `group-name → [row-keys]` enabling logical sections.

---

## 2. Column Handling

1. Preserve the exact order provided by the configuration list.
2. A column with `visible = false` is **omitted** from both header and body.
3. Cells whose value is `None`, empty, or one of the placeholder dashes (`"-", "–", "—"`) are rendered as a single m-dash (`—`).
4. No implicit data formatting is applied besides formatting explicitly mentioned in the spec; values are rendered verbatim except for the placeholder rule above explicit exceptions below.

---

## 3. Table Structure

* The first line is the header row using configured labels.
* The second line is the Markdown separator row (`| --- | --- | … |`).
* Subsequent lines list body rows in the exact order they were supplied.
* Each line starts and ends with `|` and separates cells with `|`.
* There is **no trailing whitespace**.
* If columns with keys `priority` or `urgency` are visible their numeric value will be converted in a *Star Scale*

---

## 4. Star Scale

* A star scale is a display of low numeric values (usually 0-5)
* The amount of **filled** stars (★) is the numeric value, the others **empty** stars (☆).
* The amount of stars in the scale is `min(5,max(value in column))`.

---

## 5. Group Sections (optional)

When a *Groups* mapping is provided:

1. Emit `### <Group-Name>` before the first table pertaining to that group followed by an empty line.
2. Within each section, include only the rows whose key appears in the corresponding list, and **maintain** their pre-existing order.
3. Multiple groups are rendered sequentially by amount of projects within that group (or alphabetically on tie) with empty lines in between.
4. Rows not referenced by any group appear *after* all groups under an implicit "Ungrouped" table (heading optional).

---

## 6. Error Handling

| Issue | Behaviour |
|-------|-----------|
| Column configuration references unknown key | Fail fast with configuration error. |
| Duplicate column keys in configuration | Configuration error. |
| Group lists reference unknown row keys | Warning or silent ignore; never duplicate rows. |

---

## 7. Non-Goals

* Styling for HTML previews is out of scope; responsibility of the downstream renderer.
* Does not define *how* sorting is performed – see [Table Sorting](./spec_table_sorting.md).