recon_gen.common.tree.actions

Typed drill action wrapper (L.1.10).

A Drill is one custom action attached to a typed Visual — left-click or right-click on a data point fires it. The drill navigates to a target sheet (same-sheet or cross-sheet) and optionally sets parameter values from the clicked data point.

The L.1.10 typed wrapper keeps K.2’s shape-validated parameter writes (DrillParam + DrillSourceField + ColumnShape) and adds:

  • target_sheet is a typed Sheet object ref, not a SheetId string. The App’s emit-time validation catches “drill into a sheet that isn’t on this analysis” the same way the dataset and calc-field walks catch unregistered references.

  • action_id is Optional — the App walker assigns act-s{sheet_idx}-v{visual_idx}-{action_idx} at emit time.

Visual subtypes (KPI / Table / BarChart / Sankey) accept a typed actions: list[Drill] field; their emit() passes the resolved list into the underlying model’s Actions slot.

Classes

CrossAppDrill(writes, name, ...[, trigger, ...])

CF.X-infra — drill action that targets a DIFFERENT app's dashboard (not just another sheet inside the owning app's tree).

Drill(writes, name[, trigger, action_id, ...])

One custom action on a Visual.

SameSheetFilter(target_visuals, name[, ...])

A click action that filters target visuals on the same sheet via ALL_FIELDS — the click-a-bar-to-narrow-the-table pattern.
class recon_gen.common.tree.actions.Drill(writes, name, trigger='DATA_POINT_CLICK', action_id=AUTO, target_sheet=AUTO)[source]

Bases: object

One custom action on a Visual.

target_sheet is the destination Sheet object ref. Two binding modes:

  • Cross-sheet drill — pass an explicit target_sheet=sheet. The drill navigates to that sheet (and writes parameter values to it).

  • Same-sheet drill (the walk-the-flow / re-render-around-new-anchor pattern) — leave target_sheet as None. App.resolve_auto_ids back-fills the field with the sheet that owns the visual carrying the drill, so the author never types target_sheet=this_sheet when wiring a drill inside the function that builds the sheet. Resolves the chicken-and-egg cycle (sheet doesn’t exist yet when the drill is constructed inside Sheet.add_visual(...)) without a back-fill loop at the call site.

writes is a list of (DrillParam, DrillSourceField | DrillResetSentinel) tuples — same shape K.2 introduced. The DrillParam carries its own ColumnShape; DrillSourceField.shape must match or cross_sheet_drill raises (call-site shape validation).

trigger picks the click semantic — DATA_POINT_CLICK for left-click, DATA_POINT_MENU for right-click context menu.

action_id is Optional — the App walker assigns one at emit time when not specified.

name is the visible label QuickSight shows in the right-click menu (for DATA_POINT_MENU triggers). For DATA_POINT_CLICK actions the name doesn’t surface in the UI but is still required by the underlying model.

Parameters:
action_id: str | Literal[_AutoSentinel.AUTO] = 'auto'
emit()[source]
Return type:

VisualCustomAction

name: str
target_sheet: Sheet | Literal[_AutoSentinel.AUTO] = 'auto'
trigger: Literal['DATA_POINT_CLICK', 'DATA_POINT_MENU'] = 'DATA_POINT_CLICK'
writes: list[tuple[DrillParam, Dim | Measure | DrillSourceField | DrillResetSentinel | DrillStaticDateTime]]
class recon_gen.common.tree.actions.DrillParam(name, shape)[source]

Bases: object

Destination parameter on a drill action — name + expected shape.

The shape captures the parameter’s value semantics; set_drill_parameters refuses to write a source field whose shape differs.

Parameters:
name: ParameterName
shape: ColumnShape
class recon_gen.common.tree.actions.DrillResetSentinel(value='__ALL__')[source]

Bases: object

Marker that a drill should reset a parameter to the sentinel value.

The destination calc-field filter recognizes the sentinel as PASS, so writing this clears the filter without needing an empty-string or null-value path that QuickSight’s drill-action code path won’t deliver to calc fields cleanly.

Parameters:

value (str)

value: str = '__ALL__'
class recon_gen.common.tree.actions.DrillSourceField(field_id, shape)[source]

Bases: object

Source field on a drill action — visual field id + resolved shape.

Build via field_source(field_id, dataset_id, column_name) so the shape is read from the dataset contract, not duplicated by hand.

Parameters:
field_id: str
shape: ColumnShape
class recon_gen.common.tree.actions.DrillStaticDateTime(value)[source]

Bases: object

Marker that a drill should write a fixed ISO-8601 datetime literal to a DateTimeParam destination.

Use case: cross-sheet drills where the destination sheet has a universal date-range filter the source sheet doesn’t share — e.g. L1’s Pending Aging → Transactions. The aging sheet is a current-state view (rows can be arbitrarily old); the Transactions sheet’s universal-filter window defaults to last 7 days. Without a date write the drill-target leg falls outside the destination’s window and the table renders empty. Writing DrillStaticDateTime("1990-01-01T00:00:00.000Z") to the destination’s date-start param widens the window so the drill- target row is always visible.

QuickSight has no “now” or “rolling” expression you can write via SetParametersOperation — the only options are SourceField (column ref) or static CustomValues. Pick the static value carefully so the picker-shown date isn’t misleading; the L1 app uses "1990-01-01T..." for start and "2099-12-31T..." for end, framing the explicit “all time” intent.

Format: ISO-8601 with millisecond precision and the trailing Z, matching what the L2FT app already uses for its static StaticValues defaults.

Parameters:

value (str)

value: str
class recon_gen.common.tree.actions.SameSheetFilter(target_visuals, name, trigger='DATA_POINT_CLICK', action_id=AUTO)[source]

Bases: object

A click action that filters target visuals on the same sheet via ALL_FIELDS — the click-a-bar-to-narrow-the-table pattern.

target_visuals is a list of typed VisualLike object refs. The action’s emitted TargetVisuals field reads each visual’s (resolved) visual_id at emit time, so the action survives auto- ID resolution and refactors that rename a visual.

Distinct from Drill — emits a FilterOperation rather than a NavigationOperation + SetParametersOperation pair. Doesn’t cross sheets, doesn’t write parameters.

Parameters:

  • target_visuals (list[VisualLike])

  • name (str)

  • trigger (Literal['DATA_POINT_CLICK', 'DATA_POINT_MENU'])

  • action_id (str | Literal[_AutoSentinel.AUTO])

action_id: str | Literal[_AutoSentinel.AUTO] = 'auto'
emit()[source]
Return type:

VisualCustomAction

name: str
target_visuals: list[VisualLike]
trigger: Literal['DATA_POINT_CLICK', 'DATA_POINT_MENU'] = 'DATA_POINT_CLICK'