recon_gen.common.tree.visuals

Typed Visual subtypes — one per visual kind in active use.

L.1.1 catalog: KPI ×29, Table ×22, BarChart ×13, Sankey ×2 across the three apps. Each subtype owns its field-well shape and emits the corresponding models.py Visual instance.

Classes

`BarChart`(title, subtitle[, category, ...])	Bar chart visual — one bar per distinct `category`, height by `values`.
`ForceGraph`(title, subtitle[, actions, visual_id])	Force-directed network visual — HTMX-dialect only (X.2 spike capability test for X.4).
`KPI`(title, subtitle[, values, ...])	KPI visual — single number per `values` entry, no grouping.
`KPIValueSignIndicator`([inflow_is_healthy])	BK.9 — sign-aware (▲ inflow / ▼ outflow) state indicator for a KPI's primary value.
`KPIValueThresholdBanding`(amber_at, red_at)	CF.X-infra — 3-band threshold indicator on a KPI's primary value.
`KPIValueZeroIndicator`([healthy_when_zero])	BK.2 — binary healthy-when-zero state indicator for a KPI's primary value.
`LineChart`(title, subtitle[, category, ...])	Line chart visual — one line per distinct `colors` value, plotted across `category` (x-axis) with height by `values` (y-axis).
`Sankey`(title, subtitle[, source, target, ...])	Sankey diagram visual — flows from `source` nodes to `target` nodes, ribbon thickness by `weight`.
`Table`(title, subtitle[, group_by, values, ...])	Table visual — two field-well shapes:
`VisualLike`(args, *kwargs)	Structural type for tree-level visual nodes.

class recon_gen.common.tree.visuals.BarChart(title, subtitle, category=<factory>, values=<factory>, colors=<factory>, orientation=None, bars_arrangement=None, category_label=None, value_label=None, color_label=None, sort_by=None, actions=<factory>, log_scale=False, visual_id=AUTO)[source]

Bases: object

Bar chart visual — one bar per distinct category, height by values.

Field-well shape: Category=[Dim, ...] + Values=[Measure, ...].

orientation ("VERTICAL" or "HORIZONTAL") and bars_arrangement ("CLUSTERED" / "STACKED" / "STACKED_PERCENT") pass through to the underlying BarChartConfiguration. sort_by is a (field_id, direction) tuple — direction "ASC" or "DESC" — and emits a CategorySort entry. All three default to None so the QuickSight defaults apply when not specified.

visual_id is optional (L.1.8.5 auto-ID).

Parameters:

title (str)
subtitle (str)
category (list[Dim])
values (list[Measure])
colors (list[Dim])
orientation (Literal['HORIZONTAL', 'VERTICAL'] | None)
bars_arrangement (Literal['CLUSTERED', 'STACKED', 'STACKED_PERCENT'] | None)
category_label (str | None)
value_label (str | None)
color_label (str | None)
sort_by (tuple[Dim | Measure | str, Literal['ASC', 'DESC']] | None)
actions (list[Drill | SameSheetFilter])
log_scale (bool)
visual_id (VisualId | Literal[_AutoSentinel.AUTO])

actions: list[Drill | SameSheetFilter]

bars_arrangement: Literal['CLUSTERED', 'STACKED', 'STACKED_PERCENT'] | None = None

calc_fields()[source]

Return type:: set[CalcField]

category: list[Dim]

category_label: str | None = None

color_label: str | None = None

colors: list[Dim]

datasets()[source]

Return type:: set[Dataset]

property element_id: str

property element_type: Literal['VISUAL', 'FILTER_CONTROL', 'PARAMETER_CONTROL', 'TEXT_BOX', 'IMAGE']

emit()[source]

Return type:: Visual

log_scale: bool = False

orientation: Literal['HORIZONTAL', 'VERTICAL'] | None = None

sort_by: tuple[Dim | Measure | str, Literal['ASC', 'DESC']] | None = None

subtitle: str

title: str

value_label: str | None = None

values: list[Measure]

visual_id: VisualId | Literal[_AutoSentinel.AUTO] = 'auto'

class recon_gen.common.tree.visuals.ForceGraph(title, subtitle, actions=<factory>, visual_id=AUTO)[source]

Bases: object

Force-directed network visual — HTMX-dialect only (X.2 spike capability test for X.4).

QuickSight’s standard visual library doesn’t include a force layout (only hierarchical SankeyDiagramVisual), so this primitive exists to prove the L1 tree primitives can host a visual kind that no QS dialect emit knows how to render. The HTMX renderer’s bootstrap dispatches to renderForceGraph via d3-force; emit() raises because the QS pipeline intentionally has no path for this kind.

Phase.1 design call: either keep this HTMX-only or wire a custom-visual emitter for QS. The capability test is the artifact; the layering decision is downstream.

No field-well slots — the visual’s data shape (nodes + links) flows through the data fetcher directly, not through QS field wells. visual_id is optional (L.1.8.5 auto-ID).

Parameters:

title (str)
subtitle (str)
actions (list[Drill | SameSheetFilter])
visual_id (VisualId | Literal[_AutoSentinel.AUTO])

actions: list[Drill | SameSheetFilter]

calc_fields()[source]

Return type:: set[CalcField]

datasets()[source]

Return type:: set[Dataset]

property element_id: str

property element_type: Literal['VISUAL', 'FILTER_CONTROL', 'PARAMETER_CONTROL', 'TEXT_BOX', 'IMAGE']

emit()[source]

Return type:: Visual

subtitle: str

title: str

visual_id: VisualId | Literal[_AutoSentinel.AUTO] = 'auto'

class recon_gen.common.tree.visuals.KPI(title, subtitle, values=<factory>, value_zero_indicator=None, value_sign_indicator=None, value_threshold_banding=None, visual_id=AUTO)[source]

Bases: object

KPI visual — single number per values entry, no grouping.

Field-well shape: Values=[Measure, ...]. Most KPIs use one measure; multiple are allowed and render as side-by-side numbers.

value_zero_indicator (BK.2) — optional binary check/X+color state on the primary value. See KPIValueZeroIndicator. Only fires on single-value KPIs (multi-value KPIs would need per-value indicators; not currently supported).

visual_id is optional (L.1.8.5 auto-ID). When omitted, the App’s tree walker assigns v-kpi-s{sheet_idx}-{visual_idx} at emit time. Pass an explicit VisualId(...) to override.

Parameters:

title (str)
subtitle (str)
values (list[Measure])
value_zero_indicator (KPIValueZeroIndicator | None)
value_sign_indicator (KPIValueSignIndicator | None)
value_threshold_banding (KPIValueThresholdBanding | None)
visual_id (VisualId | Literal[_AutoSentinel.AUTO])

calc_fields()[source]

CalcFields this visual references via its field-well leaves.

Return type:: set[CalcField]

datasets()[source]

Return type:: set[Dataset]

property element_id: str

property element_type: Literal['VISUAL', 'FILTER_CONTROL', 'PARAMETER_CONTROL', 'TEXT_BOX', 'IMAGE']

emit()[source]

Return type:: Visual

subtitle: str

title: str

value_sign_indicator: KPIValueSignIndicator | None = None

value_threshold_banding: KPIValueThresholdBanding | None = None

value_zero_indicator: KPIValueZeroIndicator | None = None

values: list[Measure]

visual_id: VisualId | Literal[_AutoSentinel.AUTO] = 'auto'

class recon_gen.common.tree.visuals.KPIValueSignIndicator(inflow_is_healthy=True)[source]

Bases: object

BK.9 — sign-aware (▲ inflow / ▼ outflow) state indicator for a KPI’s primary value. Renders ARROW_UP in green when the aggregated value is non-negative, ARROW_DOWN in red when it’s negative.

Accessibility: icon is the load-bearing channel (▲ vs ▼ is distinguishable to all viewers regardless of color perception); color rides along as a parallel signal.

Same QS wire shape as KPIValueZeroIndicator (see for the three layered gotchas around hex case + expression DSL); the semantic differs — sign of the aggregated value, not zero-vs- not-zero. Currently used on Exec “Net Money Moved” (signed flow).

Parameters:: inflow_is_healthy (bool)

inflow_is_healthy: bool = True

class recon_gen.common.tree.visuals.KPIValueThresholdBanding(amber_at, red_at)[source]

Bases: object

CF.X-infra — 3-band threshold indicator on a KPI’s primary value. Renders CHECKMARK (green) when the aggregated value is below amber_at, EXCLAMATION_CIRCLE (amber) between amber_at and red_at, and X (red) at or above red_at.

Accessibility (per BK.2 convention): ICON is the load-bearing channel — colorblind users see distinct ✓ / ⚠ / ✗ glyphs. Color rides along as parallel signal.

Use this on count-style KPIs where the operator wants a glance- readable “is anything wrong, anywhere?” tripwire. Bound Measure kind must be sum / max / min / average — count / distinct_count are blocked at the emit boundary (use a sum-of-1s shape in the dataset SQL and kind='sum' instead).

Wire shape: - QS: emits KPIVisual.ConditionalFormatting with three

ConditionalFormattingOptions entries ordered RED → AMBER → GREEN (most-restrictive-first); QS picks the first matching expression at render time.

App2: the data-fetcher reads the primary value and emits state_icon (Unicode glyph) + state_color (semantic keyword — success / warning / danger) on each values entry. bootstrap.js::renderKPI prepends the glyph + applies the color class.

First consumer: CF.2 Exec program-health rollup (amber_at=1, red_at=20).

Parameters:

amber_at (int)
red_at (int)

amber_at: int

red_at: int

class recon_gen.common.tree.visuals.KPIValueZeroIndicator(healthy_when_zero=True)[source]

Bases: object

BK.2 — binary healthy-when-zero state indicator for a KPI’s primary value. Renders a CHECKMARK in green when the aggregated value equals zero, an X in red otherwise.

Accessibility (per user 2026-05-29 — colorblind users in the loop): the ICON is the load-bearing channel. Color is a parallel signal for users who can read it, but the icon alone fully communicates healthy/broken state to red/green-colorblind viewers.

Wire shape: - QS: emits KPIVisual.ConditionalFormatting with two

ConditionalFormattingOptions entries, each carrying a PrimaryValue.Icon.CustomCondition block — the first matches zero, the second matches non-zero. QS evaluates the expression at render time against the displayed primary value.

App2: the data-fetcher reads the primary value and emits state_icon (Unicode glyph) + state_color (semantic keyword) on each values entry. bootstrap.js::renderKPI prepends the glyph + applies the color class.

The TWO renderers see different payloads but render the semantically-equivalent shape — same icon glyph, same color intent — so the operator gets the same signal on either surface.

Parameters:: healthy_when_zero (bool)

healthy_when_zero: bool = True

class recon_gen.common.tree.visuals.LineChart(title, subtitle, category=<factory>, values=<factory>, colors=<factory>, chart_type=None, category_label=None, value_label=None, sort_by=None, actions=<factory>, visual_id=AUTO)[source]

Bases: object

Line chart visual — one line per distinct colors value, plotted across category (x-axis) with height by values (y-axis).

Field-well shape: Category=[Dim, ...] + Values=[Measure, ...] + Colors=[Dim, ...].

chart_type selects LINE (default), AREA, or STACKED_AREA. sort_by is a (field_id, direction) tuple — direction "ASC" or "DESC" — and emits a CategorySort entry. All optional fields default to None so the QuickSight defaults apply when not specified.

visual_id is optional (L.1.8.5 auto-ID).

Parameters:

title (str)
subtitle (str)
category (list[Dim])
values (list[Measure])
colors (list[Dim])
chart_type (Literal['LINE', 'AREA', 'STACKED_AREA'] | None)
category_label (str | None)
value_label (str | None)
sort_by (tuple[Dim | Measure | str, Literal['ASC', 'DESC']] | None)
actions (list[Drill | SameSheetFilter])
visual_id (VisualId | Literal[_AutoSentinel.AUTO])

actions: list[Drill | SameSheetFilter]

calc_fields()[source]

Return type:: set[CalcField]

category: list[Dim]

category_label: str | None = None

chart_type: Literal['LINE', 'AREA', 'STACKED_AREA'] | None = None

colors: list[Dim]

datasets()[source]

Return type:: set[Dataset]

property element_id: str

property element_type: Literal['VISUAL', 'FILTER_CONTROL', 'PARAMETER_CONTROL', 'TEXT_BOX', 'IMAGE']

emit()[source]

Return type:: Visual

sort_by: tuple[Dim | Measure | str, Literal['ASC', 'DESC']] | None = None

subtitle: str

title: str

value_label: str | None = None

values: list[Measure]

visual_id: VisualId | Literal[_AutoSentinel.AUTO] = 'auto'

class recon_gen.common.tree.visuals.Sankey(title, subtitle, source=None, target=None, weight=None, items_limit=None, actions=<factory>, visual_id=AUTO)[source]

Bases: object

Sankey diagram visual — flows from source nodes to target nodes, ribbon thickness by weight.

Field-well shape: each of source / target / weight is a single Dim / Measure (the underlying model expects lists, but every usage today has exactly one entry; emit wraps).

items_limit caps the number of source / destination nodes rendered (matches the ItemsLimit shape on the underlying sort configuration). OtherCategories defaults to "INCLUDE" so capped flows roll into a “(others)” bucket rather than being dropped silently.

visual_id is optional (L.1.8.5 auto-ID).

Parameters:

title (str)
subtitle (str)
source (Dim | None)
target (Dim | None)
weight (Measure | None)
items_limit (int | None)
actions (list[Drill | SameSheetFilter])
visual_id (VisualId | Literal[_AutoSentinel.AUTO])

actions: list[Drill | SameSheetFilter]

calc_fields()[source]

Return type:: set[CalcField]

datasets()[source]

Return type:: set[Dataset]

property element_id: str

property element_type: Literal['VISUAL', 'FILTER_CONTROL', 'PARAMETER_CONTROL', 'TEXT_BOX', 'IMAGE']

emit()[source]

Return type:: Visual

items_limit: int | None = None

source: Dim | None = None

subtitle: str

target: Dim | None = None

title: str

visual_id: VisualId | Literal[_AutoSentinel.AUTO] = 'auto'

weight: Measure | None = None

class recon_gen.common.tree.visuals.Table(title, subtitle, group_by=<factory>, values=<factory>, columns=<factory>, sort_by=None, actions=<factory>, conditional_formatting=None, visual_id=AUTO)[source]

Bases: object

Table visual — two field-well shapes:

Aggregated (default): group_by=[Dim, ...] + values=[Measure, ...]. One row per distinct group_by combination, aggregated by values. Emits TableAggregatedFieldWells.
Unaggregated: pass columns=[Dim, ...] (and leave group_by / values empty). Each cell shows the raw column value — no aggregation, one row per source row. Emits TableUnaggregatedFieldWells. Use this for detail/drill-source tables (AR Balances, AR Daily Statement transaction list).

Optional sort_by is a (field_ref, direction) tuple — direction is "ASC" or "DESC".

Optional conditional_formatting passes through to the model’s raw dict (see common/clickability.py for the standard accent-text and tint-background helpers).

visual_id is optional (L.1.8.5 auto-ID).

Parameters:

title (str)
subtitle (str)
group_by (list[Dim])
values (list[Measure])
columns (list[Dim])
sort_by (tuple[Dim | Measure | str, Literal['ASC', 'DESC']] | list[tuple[~recon_gen.common.tree.fields.Dim | ~recon_gen.common.tree.fields.Measure | str, ~typing.Literal['ASC', 'DESC']]] | None)
actions (list[Drill | SameSheetFilter])
conditional_formatting (list[CellAccentText | CellAccentMenu] | None)
visual_id (VisualId | Literal[_AutoSentinel.AUTO])

actions: list[Drill | SameSheetFilter]

calc_fields()[source]

Return type:: set[CalcField]

columns: list[Dim]

conditional_formatting: list[CellAccentText | CellAccentMenu] | None = None

datasets()[source]

Return type:: set[Dataset]

property element_id: str

property element_type: Literal['VISUAL', 'FILTER_CONTROL', 'PARAMETER_CONTROL', 'TEXT_BOX', 'IMAGE']

emit()[source]

Return type:: Visual

group_by: list[Dim]

sort_by: tuple[Dim | Measure | str, Literal['ASC', 'DESC']] | list[tuple[Dim | Measure | str, Literal['ASC', 'DESC']]] | None = None

subtitle: str

title: str

values: list[Measure]

visual_id: VisualId | Literal[_AutoSentinel.AUTO] = 'auto'

class recon_gen.common.tree.visuals.VisualLike(*args, **kwargs)[source]

Bases: Protocol

Structural type for tree-level visual nodes.

Typed subtypes (KPI / Table / BarChart / Sankey) satisfy this Protocol — duck-typed so subtypes don’t have to inherit from a base class. Subtypes contribute to the L.1.7 dependency-graph walk via datasets() / calc_fields().

All visual nodes also satisfy LayoutNode (in structure.py) via element_id + element_type so they can be placed in a sheet’s grid layout (sheet.layout.row(...).add_<kind>(...)).

visual_id is VisualId | AutoResolved — typed subtypes default to AUTO and App.resolve_auto_ids replaces it with the derived id before emit. The walker / emit assert via isinstance narrowing.

calc_fields()[source]

Return type:: set[CalcField]

datasets()[source]

Return type:: set[Dataset]

emit()[source]

Return type:: Visual

visual_id: VisualId | Literal[_AutoSentinel.AUTO]