Interactions

Root calculated fields can participate in internal filtering/highlighting and retain contributing source-row lineage for identity selection. They cannot directly become Power BI model filters; the exact runtime reason is calculated field has no direct Power BI model filter target.

HyperPBI has three independent declarative systems. A component may use none, one, or more of them; an interaction object is not required on every component.

1. UI actions

uiAction changes interface state and never directly sends a Power BI selection/filter:

Toast duration is persistent when omitted/zero, otherwise clamped to 1–30 seconds. UI actions are executed as data, never code. Overlay targets must exist.

2. Universal interaction

{
  "interaction": {
    "enabled": true,
    "trigger": "auto",
    "internalMode": "highlight",
    "internalScope": "self",
    "externalMode": "auto",
    "field": "status",
    "operator": "=",
    "selectionMode": "replace",
    "targets": ["detail_table", "operations_map"],
    "multiSelect": true,
    "showSelector": false,
    "clearOnSecondClick": true
  }
}

Exact enums:

• trigger: auto|click|change
• internalMode: none|highlight|filter
• internalScope: self|others|all
• externalMode: none|auto|selection|filter
• operator: =|!=|>|>=|<|<=|contains|in|between
• selectionMode: replace|toggle|add

target is the compatibility shorthand for one linked component; targets is an array of existing stable component IDs. When present, internal highlight/filter behavior applies only to those components instead of deriving recipients from internalScope. Strict 2.0 validation rejects missing target IDs. External Power BI behavior is report-level and is not limited by component targets.

auto trigger resolves to change for controls and click otherwise. auto external mode resolves to filter for controls and selection for data-point/custom components.

Internal modes

• none: no HyperPBI highlight/filter
• highlight: records selected source rows/keys; scope decides whether self, others, or all components consume the highlight
• filter: adds a scoped internal field/value filter, or a source-row-key filter when no field payload exists

selectionMode replaces, toggles, or adds matching row keys. With replace mode, a modifier gesture can toggle. clearOnSecondClick compares a stable signature of component, field, operator, value, and sorted row keys.

showSelector only controls table selector UI; row clicks still work whenever interaction is enabled.

External selection

Selection uses exact Power BI identities for source row indices. For a logical dataset, each output row carries source lineage; selecting a grouped/distinct row can select every contributing base identity. Selection is unavailable when the host/data view supplied no identities.

External filtering

Filtering constructs a Power BI basic or advanced JSON filter:

• =, in, != use In/NotIn
• contains, comparisons, and between use advanced conditions
• an empty value clears the filter

The field must resolve to a model column with sourceTable and sourceColumn. A true model measure has no basic filter target. A query wrapper such as Sum(Sales.Amount) may still target Sales.Amount because it is an implicitly aggregated column.

Dataset-derived fields and dataset metrics cannot directly filter Power BI. Renamed direct columns and dataset group fields can retain their original target metadata. Use identity selection for grouped metrics rather than pretending a metric is a model column.

Runtime Config crossFilter: false is a global gate; it does not redefine component semantics.

Chart zoom, range, brush, and drill

Charts expose a declarative events object separate from safe custom-content interactions:

{
  "events": {
    "zoom": { "enabled": true },
    "rangeSelect": {
      "enabled": true,
      "targets": ["detail_table"],
      "interaction": { "internalMode": "filter", "externalMode": "selection" }
    },
    "brush": {
      "enabled": true,
      "targets": ["detail_table", "operations_map"]
    }
  }
}

Zoom persists an ECharts data-zoom window. Range selection converts that visible window to adapter bindings; categorical ranges follow series order rather than lexical label order. Brush converts rectangle/polygon ECharts selections to exact series/data-index bindings. Both flatten and deduplicate original source-row lineage before calling the universal engine, so a grouped point can select every contributing Power BI identity. An empty brush clears stale row keys and its internal filter.

Chart drill.levels is navigation state, not an executable drill callback. Each level names a preloaded logical dataset and binding fields; parentField filters the child dataset by the selected parent binding value. Breadcrumbs move to an earlier level without reevaluating or fetching data, and source lineage remains available at every resolution.

3. Safe event-specific interactions

interactions is primarily used by custom content to map a supported event to one allowlisted payload or an allowed action array:

• selectRow, selectWhere, clearSelection
• setFilter, clearFilter
• setState, toggleState
• openTab, toggleCollapse
• drillToDetail, highlight, clearHighlight

Nested declarative action payloads, where expressions, and valueFromRow occurrences use the same canonical field traversal as preparation, validation, Inspector controls, repair diagnostics, and dependency reporting. selectWhere uses safe expression objects and may read a known clicked-row field via valueFromRow. The resolver converts supported data actions into the universal engine, so internal/external policies and diagnostics remain consistent.

No JavaScript callback, handler string, arbitrary dispatch name, URL navigation, or DOM script is accepted.

Dataset scope

Components validate fields against their selected logical dataset. Internal row behavior maps through source keys/lineage. An interaction field is not automatically remapped to a Power BI filter target: the selected field's retained origin metadata decides eligibility.

Map layers refine this rule: layer.dataset overrides the map dataset, and each layer carries its own rows, schema, row keys, and arrays of contributing Power BI identities. A grouped feature may select several source rows. ArcGIS joins preserve the same lineage on the Power BI side. External filter mode still requires an actual model-column target; service/joined attributes and dataset metrics cannot directly filter the semantic model.

Map Studio's layer Interaction tab edits the existing universal interaction contract rather than a map-only engine. Its field selector follows fieldSource. Power BI and joined features may use retained Power BI identities for external selection; an external filter is enabled only for a direct model column with source table/column metadata. ArcGIS reference-only features can use local highlight/filter behavior, but the editor reports external Power BI selection/filter as unavailable when no genuine model target or lineage exists. Multi-select and clear-on-second-click continue through the shared interaction runtime.

Map feature events have one stable trigger contract: map.layers[].interaction.trigger must be "click". Leaflet runs the interaction from the feature click handler, Map Studio exposes a fixed click value, and strict 2.0 validation emits MAP_INTERACTION_TRIGGER_UNSUPPORTED for map-layer change or auto. This restriction does not remove those trigger values from non-map components.

Map feature click, interactive legend click/hover, rectangle, lasso, circle/radius, Select visible, Invert, quick-filter reconciliation, external Power BI selection/filtering, and linked HyperPBI component state use one analytical controller. Operations are replace, add, remove, toggle, and clear. The spatial pass updates canonical feature keys, then submits the exact union of matching Power BI row indices and keys. Authored selection mode is used unless Ctrl/Cmd toggles, Shift adds, or Alt subtracts. Reference-only features remain locally selectable and never manufacture an external identity.

Map visual state distinguishes normal, hovered, selected, externally highlighted, dimmed, and filtered-out features. Legends, details, selected feature count, and contributing-row count derive from the same keys. Heatmap pixels and raster tiles are not interaction targets; an authored heatmap can retain a transparent point hit layer. Selection and Power BI identity limits are deterministic and reported rather than silently dropping state. See Analytical maps.

Compatibility

Schema 2.0 uses interaction exclusively. Top-level internal, external, table selectable, and table selectionMode are rejected. Properties such as externalSelection, selectionTarget, crossFilter, and powerBISelection are not dashboard JSON contracts and are rejected by strict validation.