# Taipy App — UI Architecture

The Taipy dashboard uses a template-driven architecture where pages are declarative data, not imperative layout code. All page rendering flows through `page_template.py` → `build_page(cfg: PageConfig)`. This document defines the rules for maintaining and extending it.

## Adding a New Page

A new page requires exactly 3 files and 2 edits (4 files for dashboard pages):

1. **`hf_taipy_app/src/state/<page_name>.py`** — State variables, callbacks, SQL queries, chart rendering. Must follow prefix naming (`<prefix>_variable`) to avoid Taipy namespace collisions.
2. **`hf_taipy_app/src/pages/<page_name>.py`** — A `page_config: PageConfig` and `page_md: str` (from `build_page(page_config)`). No hand-crafted Taipy Markdown — the page file is pure configuration.
3. **`hf_taipy_app/src/main.py`** — Import the page's `page_config` and `page_md`, add a `PageEntry` to `PAGE_REGISTRY`.
4. **`hf_taipy_app/src/template.py`** — Add page-specific glossary terms to `PAGE_TERMS`.

### Dashboard Page Variant

For operations/dashboard pages (stats cards + full-width content instead of 3fr/1fr layout):

- Use `stats: list[StatCard]` in `PageConfig` instead of `metrics` — this triggers the dashboard layout (`_build_dashboard_page`), which wraps content in a viewport-contained scroll wrapper (`ll-dashboard-scroll`).
- Call `register_page_refresher("Page-Name", refresh_fn, is_dashboard=True)` — the `is_dashboard` flag ensures the site-wide footer is hidden (dashboard pages render the footer inside the scroll wrapper).
- `ContentRow` wraps content blocks. `StatCard` defines the stat cards in the top bar.

## Template Rules

- **All pages must use `build_page()`**: Zero hand-crafted layouts. A page is a `PageConfig` (title, icon, description, metrics, sidebar widgets, content blocks, citations), not a string of Taipy Markdown.
- **`Metric` requires `help_text`**: If the metric name is not universally understood, `help_text` is mandatory — the `PageConfig` dataclass enforces this. "What does this mean?" and "Is this good or bad?" must be answerable from the tooltip alone.
- **`SidebarWidget` requires `help`**: Every filter widget must have a `help` tooltip explaining what it controls. Help icons are positioned absolute-right of the widget via CSS (`.md-para:has(> .ll-help)`), keeping all widget widths identical regardless of help presence.
- **`Citation` for every methodology**: Any page implementing a published algorithm must include a `Citation(text, url)` in its `PageConfig`. No uncited methodologies. Practitioner methodologies (course materials, coaching frameworks) use `Citation(text)` without a URL but must include "(course materials)" in the label.
- **`NOTICE` file maintenance**: When adding a new analytics module, page, or algorithm, add a corresponding entry to the `NOTICE` file in the project root. The NOTICE file is the authoritative record of all third-party data attributions, library credits, and mathematical/academic references. Every `Citation` in a `PageConfig` and every `references:` entry in a workflow card must have a corresponding NOTICE entry. Update NOTICE in the same change — not as a follow-up.
- **`StatCard` for dashboard stat cards**: Dashboard pages use `stats: list[StatCard]` in `PageConfig`. Each card has `label`, `var`, optional `detail_var`, `help_text`, and `detail_html`. The presence of `stats` activates the dashboard layout branch. Set `detail_html=True` to render `detail_var` as raw HTML via a content provider iframe (supports inline `<span style="">` coloring); default `False` renders as plain text. Convention: every `StatCard` should have `help_text` (same rationale as `Metric`).
- **`RequiredFilter` for filter requirements**: Pages that cannot display data until specific sidebar filters are set must declare `required_filters: list[RequiredFilter]` in `PageConfig`. The template auto-generates `empty_condition` + `empty_message` from these when not explicitly provided. This replaces hand-crafted filter-null-check conditions and ensures the "Select a X and Y to begin" guidance appears consistently. When a filter is required on some pages but optional on others (e.g., Team), `template.py` defines separate `SidebarWidget` instances with different `condition` tuples — one with `required=True` (no label suffix) and one with `required=False` (appends "(optional)"). SubView pages handle empty states per-SubView and do not use page-level `required_filters`.
- **`ContentBlock` for all content**: Images use `ContentBlock("image", var)`, tables use `ContentBlock("table", var)`, Plotly charts use `ContentBlock("chart", var)`. Tables accept `table_cell_class_name={column: callback_name}` for per-cell CSS styling via Taipy's `cell_class_name` attribute (the callback returns a CSS class string). Never construct raw `<|{var}|chart|>` markup in page files.
- **WCAG color-independence on table columns**: Table columns that use color for categorization (e.g., Type, Freshness) must include a `::before` shape marker as a WCAG 1.4.1 secondary visual cue. Each category gets a distinct CSS-drawn shape (circle, diamond, triangle, square, ring) via `currentColor` so shapes inherit the text color. If the page includes a legend (e.g., DAG legend), shapes and colored text in the legend must match the table column markers.
- **Layout changes go through the template**: If a visual change requires editing more than one page file, it belongs in `page_template.py`. Individual page files contain only page-specific data.
- **`_FOOTER_CONTENT` for footer text**: The footer text ("Published Datasets") is a shared constant in `page_template.py`. Dashboard pages render it inside the scroll wrapper; other pages render it as the site-wide footer. Do not hardcode footer text in page files.
- **`is_dashboard=True` on `register_page_refresher`**: Required for dashboard pages. Controls `show_site_footer` state variable — omitting it causes footer duplication.
- **`ll-dashboard-scroll` for dashboard viewport**: Dashboard content is wrapped in a viewport-contained scroll area (`overflow: auto`, `max-height: calc(100vh - 245px)`). Both horizontal and vertical scrollbars live inside this container. The horizontal scrollbar stays at the viewport bottom.
- **State module isolation**: Each page's state module manages its own variables and callbacks. Shared state (competition/team/match filters) lives in `state/shared.py`. No cross-page state imports except from `shared`.
- **Never use `tp_` as a state variable prefix**: Taipy reserves `tp_` internally for its expression evaluator (`TpExPr_`). Variables starting with `tp_` will have state updates silently dropped — no error, no warning. Also avoid `tpec_` (Taipy edge-case prefix). Safe prefixes: `tac_`, `gk_`, `ts_`, `pt_`, `dv_`, etc.
- **Glossary coverage**: Every domain-specific term used in metric names, chart labels, or descriptions must have an entry in `GLOSSARY` (in `template.py`) and be listed in the page's `PAGE_TERMS` entry.
- **Server-driven autocomplete (`SidebarWidget.kind="combobox"`)**: Dropdowns whose LOV would exceed ~200 items must use the `combobox` kind with `search_var` + `on_search_change` instead of the client-side `filterable=True` flag. The template emits a `<|{var}|ll_ext.combobox|...|>` fragment backed by the in-repo Taipy GUI extension at `src/extensions/ll_ext/` (React + MUI Autocomplete, bundle built into `front-end/dist/library.js`). Behaviour is WAI-ARIA APG combobox-with-list-autocomplete: the listbox is hidden until the user types, opens via ArrowDown / typing, closes on Escape / selection / blur, and full keyboard navigation + `aria-activedescendant` highlighting is handled natively. The search-change callback hits a `filters.search_*` function (SQL-backed) or filters an in-memory map (for DV / TAC where the candidate set is already loaded for the page's primary use). Every callback must set the LOV to `[..., filters.NO_MATCHES_SENTINEL]` when the match list is empty — Taipy's state diff treats `state.lov = []` as a no-op, so the bare empty list leaves a stale LOV visible. Previous provisional pattern (`searchable=True` flag on `kind="dropdown"`) was removed 2026-04-18 once all 8 migrations landed; the flag no longer exists on `SidebarWidget`.

## Why Template-First

Building pages as imperative layout code leads to inconsistency debt that compounds per-page. With 12+ pages, hand-crafting each one guarantees: missing tooltips on some pages, different metric formats, inconsistent empty-state handling, and layout drift. The template makes these structurally impossible — required fields are constructor parameters, not afterthoughts. A CHI audit against a template architecture produces template-level fixes (one change, all pages); without it, the same audit produces N per-page fixes.