rules_swap - Chirp

contracts.rules_swap

module

Swap safety checks for broad inherited hx-target scopes.

contracts.rules_swap

Name	Type	Default	Description
`type`		—
`qualified_name`		—
`element_type`		—
`description`		—
`source_file`		—
`line_number`		—
`is_autodoc`		—
`autodoc_element`		—
`_autodoc_template`		—
`_autodoc_url_path`		—
`_autodoc_page_type`		—
`title`		—
`doc_content_hash`		—

Symbols on this page

function _extends_ancestors

Return all templates reachable upward from start via {% extends %} chains.

function _collect_broad_selects_map

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…

function collect_broad_selects

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…

function collect_broad_targets

Collect broad inherited hx-target values.

function _has_live_updates

Return True if any template uses OOB or SSE live-update markers.

function _collect_broad_target_ids

Collect static broad hx-target IDs without template-name decoration.

function check_view_transition_safety

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…

function check_swap_safety

Warn when mutating swaps may inherit broad container targets or selects.

_extends_ancestors

function

def _extends_ancestors(start: str, template_sources: dict[str, str], template_aliases: Mapping[str, str] | None = None) -> set[str]

Return all templates reachable upward from start via {% extends %} chains.

Parameters

Name	Type	Default
`start`	`str`	—
`template_sources`	`dict[str, str]`	—
`template_aliases`	`Mapping[str, str] \| None`	`None`

_collect_broad_selects_map

function

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	Default	Description
`template_sources`	`dict[str, str]`	—

collect_broad_selects

function

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	Default	Description
`template_sources`	`dict[str, str]`	—

collect_broad_targets

function

def collect_broad_targets(template_sources: dict[str, str]) -> set[str]

Collect broad inherited hx-target values.

Parameters

Name	Type	Default	Description
`template_sources`	`dict[str, str]`	—

_has_live_updates

function

def _has_live_updates(template_sources: dict[str, str]) -> bool

Return True if any template uses OOB or SSE live-update markers.

Parameters

Name	Type	Default	Description
`template_sources`	`dict[str, str]`	—

_collect_broad_target_ids

function

def _collect_broad_target_ids(template_sources: dict[str, str]) -> set[str]

Collect static broad hx-target IDs without template-name decoration.

Parameters

Name	Type	Default	Description
`template_sources`	`dict[str, str]`	—

check_view_transition_safety

function

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	Default	Description
`template_sources`	`dict[str, str]`	—

check_swap_safety

function

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]

Warn when mutating swaps may inherit broad container targets or selects.

Parameters

Name	Type	Default
`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`

View source · /home/runner/work/chirp/chirp/site/../src/chirp/contracts/rules_swap.py:1