recon_gen.common.tree.controls

Typed Filter + Parameter control wrappers (L.1.9).

Each control binds to a typed source by object reference: parameter controls take a ParameterDeclLike (the parameter declaration node they read/write); filter controls take a FilterLike (the inner filter their UI drives). At emit time the wrapper reads parameter.name or filter.filter_id to populate the underlying models.SourceParameterName / SourceFilterId.

Naming convention: same as L.1.6 — tree wrappers use a clean, unsuffixed name that doesn’t collide with the underlying models.*Control classes (Parameter*Control, Filter*Control). User code reads:

from recon_gen.common.tree import (
ParameterDropdown, ParameterSlider, FilterDropdown, …,

)

LinkedValues / StaticValues typed wrappers replace the existing dict-shaped SelectableValues argument — LinkedValues takes a typed Dataset ref + column name (catches “dropdown populated from undeclared dataset” via the App’s dependency graph walk).

Auto-IDs (L.1.8.5 extension): control_id fields are Optional; the App walker assigns position-indexed IDs at emit time (pc-{kind}-s{sheet_idx}-{control_idx} for parameter controls, fc-{kind}-s{sheet_idx}-{control_idx} for filter controls).

Classes

`FilterControlLike`(args, *kwargs)	Tree-level filter control nodes.
`FilterCrossSheet`(filter[, control_id])	Cross-sheet filter control — surfaces the filter on multiple sheets via the same bound filter.
`FilterDateTimePicker`(filter, title[, type, ...])	Date/time picker control bound to a TimeRangeFilter.
`FilterDropdown`(filter, title[, type, ...])	Dropdown control bound to an inner filter (`CategoryFilter`).
`FilterSlider`(filter, title, minimum_value, ...)	Slider control bound to a NumericRangeFilter.
`LinkedValues`(dataset, column_name)	Auto-populate the dropdown's options from a dataset column.
`ParameterControlLike`(args, *kwargs)	Tree-level parameter control nodes.
`ParameterDateTimePicker`(parameter, title[, ...])	Date/time picker control bound to a DateTime parameter.
`ParameterDropdown`(parameter, title, ...[, ...])	Dropdown control bound to a `ParameterDeclLike` parameter.
`ParameterSlider`(parameter, title, ...[, ...])	Slider control bound to a numeric parameter.
`ParameterTextField`(parameter, title[, ...])	Free-text input control bound to a string parameter.
`StaticValues`(values)	Restrict the dropdown to a fixed list of options.

class recon_gen.common.tree.controls.FilterControlLike(*args, **kwargs)[source]

Bases: Protocol

Tree-level filter control nodes.

datasets() participates in the L.1.7 dependency-graph walk — same shape as ParameterControlLike.datasets().

control_id: str | Literal[_AutoSentinel.AUTO]

datasets()[source]

Return type:: set[Dataset]

emit()[source]

Return type:: FilterControl

class recon_gen.common.tree.controls.FilterCrossSheet(filter, control_id=AUTO)[source]

Bases: object

Cross-sheet filter control — surfaces the filter on multiple sheets via the same bound filter.

No title; the Cross-Sheet control inherits its UI from the underlying filter’s primary control.

Parameters:

filter (FilterLike)
control_id (str | Literal[_AutoSentinel.AUTO])

control_id: str | Literal[_AutoSentinel.AUTO] = 'auto'

datasets()[source]

Return type:: set[Dataset]

emit()[source]

Return type:: FilterControl

filter: FilterLike

class recon_gen.common.tree.controls.FilterDateTimePicker(filter, title, type='DATE_RANGE', control_id=AUTO)[source]

Bases: object

Date/time picker control bound to a TimeRangeFilter.

Parameters:

filter (FilterLike)
title (str)
type (Literal['SINGLE_VALUED', 'DATE_RANGE'])
control_id (str | Literal[_AutoSentinel.AUTO])

control_id: str | Literal[_AutoSentinel.AUTO] = 'auto'

datasets()[source]

Return type:: set[Dataset]

emit()[source]

Return type:: FilterControl

filter: FilterLike

title: str

type: Literal['SINGLE_VALUED', 'DATE_RANGE'] = 'DATE_RANGE'

class recon_gen.common.tree.controls.FilterDropdown(filter, title, type='MULTI_SELECT', selectable_values=None, control_id=AUTO)[source]

Bases: object

Dropdown control bound to an inner filter (CategoryFilter).

filter is the typed inner filter the dropdown drives — at emit time, the control’s SourceFilterId becomes filter.filter_id. The filter must be inside a FilterGroup that’s been registered on the analysis.

Parameters:

filter (FilterLike)
title (str)
type (Literal['SINGLE_SELECT', 'MULTI_SELECT'])
selectable_values (StaticValues | LinkedValues | None)
control_id (str | Literal[_AutoSentinel.AUTO])

control_id: str | Literal[_AutoSentinel.AUTO] = 'auto'

datasets()[source]

Return type:: set[Dataset]

emit()[source]

Return type:: FilterControl

filter: FilterLike

selectable_values: StaticValues | LinkedValues | None = None

title: str

type: Literal['SINGLE_SELECT', 'MULTI_SELECT'] = 'MULTI_SELECT'

class recon_gen.common.tree.controls.FilterSlider(filter, title, minimum_value, maximum_value, step_size, type='RANGE', control_id=AUTO)[source]

Bases: object

Slider control bound to a NumericRangeFilter.

Parameters:

filter (FilterLike)
title (str)
minimum_value (float)
maximum_value (float)
step_size (float)
type (Literal['SINGLE_POINT', 'RANGE'])
control_id (str | Literal[_AutoSentinel.AUTO])

control_id: str | Literal[_AutoSentinel.AUTO] = 'auto'

datasets()[source]

Return type:: set[Dataset]

emit()[source]

Return type:: FilterControl

filter: FilterLike

maximum_value: float

minimum_value: float

step_size: float

title: str

type: Literal['SINGLE_POINT', 'RANGE'] = 'RANGE'

class recon_gen.common.tree.controls.LinkedValues(dataset, column_name)[source]

Bases: object

Auto-populate the dropdown’s options from a dataset column.

Construct via the factory methods (L.1.22 — the canonical fields are dataset + column_name; the factories normalize the two legitimate construction forms into that pair, eliminating the dual-form __post_init__ validation):

LinkedValues.from_column(ds["col"]) — typed Column form. The Column carries its own dataset, so the factory derives dataset from the Column. Preferred — the contract validates the column name at the wiring site.
LinkedValues.from_string(dataset=ds, column_name="col") — bare-string escape hatch for datasets without a registered DatasetContract. Dataset must be passed explicitly.

The Dataset participates in the L.1.7 dependency-graph walk via the control’s datasets() method.

Parameters:

dataset (Dataset)
column_name (str)

column_name: str

dataset: Dataset

emit()[source]

Return type:: dict[str, Any]

classmethod from_column(column)[source]

Linked values pulled from a typed Column. The Column’s dataset is the source dataset.

Return type:: LinkedValues
Parameters:: column (Column)

classmethod from_string(*, dataset, column_name)[source]

Linked values pulled from a bare-string column name on the explicitly-passed dataset. Use when the dataset has no registered DatasetContract.

Return type:

LinkedValues

Parameters:

dataset (Dataset)
column_name (str)

class recon_gen.common.tree.controls.ParameterControlLike(*args, **kwargs)[source]

Bases: Protocol

Tree-level parameter control nodes.

datasets() participates in the L.1.7 dependency-graph walk — controls with LinkedValues populate from a Dataset, and that’s a dep. Controls with static values return an empty set.

control_id: str | Literal[_AutoSentinel.AUTO]

datasets()[source]

Return type:: set[Dataset]

emit()[source]

Return type:: ParameterControl

class recon_gen.common.tree.controls.ParameterDateTimePicker(parameter, title, control_id=AUTO)[source]

Bases: object

Date/time picker control bound to a DateTime parameter.

Parameters:

parameter (ParameterDeclLike)
title (str)
control_id (str | Literal[_AutoSentinel.AUTO])

control_id: str | Literal[_AutoSentinel.AUTO] = 'auto'

datasets()[source]

Return type:: set[Dataset]

emit()[source]

Return type:: ParameterControl

parameter: ParameterDeclLike

title: str

class recon_gen.common.tree.controls.ParameterDropdown(parameter, title, selectable_values, type='SINGLE_SELECT', hidden_select_all=False, cascade_source=None, cascade_match_column=None, control_id=AUTO)[source]

Bases: object

Dropdown control bound to a ParameterDeclLike parameter.

parameter is the typed parameter declaration the control reads/writes — at emit time, the control’s SourceParameterName becomes parameter.name. The type checker catches “control bound to a parameter that doesn’t exist” at the wiring site.

selectable_values accepts a StaticValues(["a", "b"]) for a fixed option list or LinkedValues(dataset, column) for an auto-populated list. The LinkedValues.dataset ref participates in the App’s dependency graph.

hidden_select_all=True suppresses the “Select all” entry — needed for SINGLE_SELECT dropdowns where empty/All semantics don’t apply (e.g. a Sankey anchor that needs exactly one value).

cascade_source makes this dropdown depend on another dropdown: when cascade_source changes value, QS refreshes THIS dropdown’s options. Required for cascading filters even when the source dataset’s params are bridged via MappedDataSetParameters — QS won’t refresh the dropdown widget without explicit UI-level cascade wiring (M.3.10c finding).

Parameters:

parameter (ParameterDeclLike)
title (str)
selectable_values (StaticValues | LinkedValues)
type (Literal['SINGLE_SELECT', 'MULTI_SELECT'])
hidden_select_all (bool)
cascade_source (ParameterDropdown | None)
cascade_match_column (Column | None)
control_id (str | Literal[_AutoSentinel.AUTO])

cascade_match_column: Column | None = None

cascade_source: ParameterDropdown | None = None

control_id: str | Literal[_AutoSentinel.AUTO] = 'auto'

datasets()[source]

Datasets this control references (via LinkedValues if any).

Return type:: set[Dataset]

emit()[source]

Return type:: ParameterControl

hidden_select_all: bool = False

parameter: ParameterDeclLike

selectable_values: StaticValues | LinkedValues

title: str

type: Literal['SINGLE_SELECT', 'MULTI_SELECT'] = 'SINGLE_SELECT'

class recon_gen.common.tree.controls.ParameterSlider(parameter, title, minimum_value, maximum_value, step_size, control_id=AUTO)[source]

Bases: object

Slider control bound to a numeric parameter.

Parameters:

parameter (ParameterDeclLike)
title (str)
minimum_value (float)
maximum_value (float)
step_size (float)
control_id (str | Literal[_AutoSentinel.AUTO])

control_id: str | Literal[_AutoSentinel.AUTO] = 'auto'

datasets()[source]

Return type:: set[Dataset]

emit()[source]

Return type:: ParameterControl

maximum_value: float

minimum_value: float

parameter: ParameterDeclLike

step_size: float

title: str

class recon_gen.common.tree.controls.ParameterTextField(parameter, title, control_id=AUTO)[source]

Bases: object

Free-text input control bound to a string parameter.

Right shape when the parameter’s option universe is unbounded / unknown at deploy time, or when the LinkedValues / StaticValues paths are unavailable. The analyst types a value; QS writes it to the bound parameter verbatim. No sample-values fetch — sidesteps the X.1.b Sample values not found failure mode entirely.

Y.1.m: rejects parameter.multi_valued=True at construction. QS text-field controls cannot commit non-empty values into a multi-valued parameter — the commit silently reverts both this parameter AND any sibling parameters back to their analysis-level defaults. Empty-string commits work (special case); any other string trips the state-reset bug. Reproduced live against L2FT Rails on 2026-05-06 — the metadata cascade was 100% broken in production for this reason. Construction-time error here prevents the whole class of regression at the wiring site.

Parameters: