Module

contracts.rules_swap

Swap safety checks for broad inherited hx-target scopes.

8Functions

Functions

_extends_ancestors 3 set[str] ▼
Return all templates reachable upward from *start* via {% extends %} chains.
def _extends_ancestors(start: str, template_sources: dict[str, str], template_aliases: Mapping[str, str] | None = None) -> set[str]
Parameters
Name Type Description
start str
template_sources dict[str, str]
template_aliases Mapping[str, str] | None Default:None
Returns
set[str]
_collect_broad_selects_map 1 dict[str, list[str]] ▼
Return {template_name: [select_value, ...]} for broad containers. A broad cont…
def _collect_broad_selects_map(template_sources: dict[str, str]) -> dict[str, list[str]]

Return {template_name: [select_value, ...]} for broad containers.

A broad container is a<body>, <main>, or any element with hx-boost="true" that also carries an hx-selectattribute.

Parameters
Name Type Description
template_sources dict[str, str]
Returns
dict[str, list[str]]
collect_broad_selects 1 set[str] ▼
Collect hx-select values from broad containers (body, main, or hx-boost="true" …
def collect_broad_selects(template_sources: dict[str, str]) -> set[str]

Collect hx-select values from broad containers (body, main, or hx-boost="true" elements).

These are potential inheritance sources: any mutating HTMX element nested inside such a container will inherit the select, which silently breaks fragment swaps when the response doesn't contain the selector target.

Parameters
Name Type Description
template_sources dict[str, str]
Returns
set[str]
collect_broad_targets 1 set[str] ▼
Collect broad inherited hx-target values.
def collect_broad_targets(template_sources: dict[str, str]) -> set[str]
Parameters
Name Type Description
template_sources dict[str, str]
Returns
set[str]
_has_live_updates 1 bool ▼
Return True if any template uses OOB or SSE live-update markers.
def _has_live_updates(template_sources: dict[str, str]) -> bool
Parameters
Name Type Description
template_sources dict[str, str]
Returns
bool
_collect_broad_target_ids 1 set[str] ▼
Collect static broad hx-target IDs without template-name decoration.
def _collect_broad_target_ids(template_sources: dict[str, str]) -> set[str]
Parameters
Name Type Description
template_sources dict[str, str]
Returns
set[str]
check_view_transition_safety 1 list[ContractIssue] ▼
Warn when View Transitions are scoped to broad live-update containers. OOB swa…
def check_view_transition_safety(template_sources: dict[str, str]) -> list[ContractIssue]

Warn when View Transitions are scoped to broad live-update containers.

OOB swaps and SSE fragments update descendants after the page has loaded. If a broad content container ownstransition:trueor a CSS view-transition-name, those child updates can animate the entire content region and make the UI appear to disappear.

Parameters
Name Type Description
template_sources dict[str, str]
Returns
list[ContractIssue]
check_swap_safety 4 list[ContractIssue] ▼
Warn when mutating swaps may inherit broad container targets or selects.
def check_swap_safety(template_sources: dict[str, str], *, all_ids: set[str] | None = None, all_ids_with_disinherit: set[str] | None = None, template_aliases: Mapping[str, str] | None = None) -> list[ContractIssue]
Parameters
Name Type Description
template_sources dict[str, str]
all_ids set[str] | None Default:None
all_ids_with_disinherit set[str] | None Default:None
template_aliases Mapping[str, str] | None Default:None
Returns
list[ContractIssue]