navigation_swap

Route-aware boosted navigation swap resolution (hierarchical domains).

Pure helpers map (current path, destination path, layout chains) to a recommendedhx-targetand symbolic scope name. Server rendering still usesHX-Target and FragmentTargetRegistryat runtime; this module only helps authors avoid hand-authoring targets on every link.

templating.navigation_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

class SwapResolution

Recommended swap for a boosted GET navigation.

function normalize_route_path

Normalize a URL path for comparisons (no query or fragment).

function resolve_destination_path

Resolve href to an absolute site path, or None if external / unusable.

function common_layout_prefix_len

Length of the longest common prefix of two layout chains (template-wise).

function common_navigation_prefix_len

Length of the longest common prefix of two navigation-domain paths.

function lookup_layout_chain_for_path

Resolve a concrete GET path to its filesystemLayoutChain.

function pick_navigation_layout_index

Choose the destination layout whose outlet should own the navigation.

Rules:

no navigation metadata on either side: keep legacy geometry-only behavior
one side annotated,…

function pick_outlet_layout_index

Choose which layout level owns the primary outlet for this transition.

function concrete_target_id

Resolve DOM target id (no #) for a layout using scope map and metadata.

function resolve_navigation_swap

Return recommended swap metadata for boosted navigation, or None.

destination_path must be normalized (seenormalize_route_path()). When the destination has no layout chain, returns…

function make_swap_attrs

Build the template globalswap_attrs(href, *, hx_boost=True).

SwapResolution

class

Recommended swap for a boosted GET navigation.

normalize_route_path

function

def normalize_route_path(path: str) -> str

Normalize a URL path for comparisons (no query or fragment).

Parameters

Name	Type	Default	Description
`path`	`str`	—

resolve_destination_path

function

def resolve_destination_path(current_path: str, href: str) -> str | None

Resolve href to an absolute site path, or None if external / unusable.

Parameters

Name	Type	Default	Description
`current_path`	`str`	—
`href`	`str`	—

common_layout_prefix_len

function

def common_layout_prefix_len(a: LayoutChain, b: LayoutChain) -> int

Length of the longest common prefix of two layout chains (template-wise).

Parameters

Name	Type	Default	Description
`a`	`LayoutChain`	—
`b`	`LayoutChain`	—

common_navigation_prefix_len

function

def common_navigation_prefix_len(a: LayoutChain, b: LayoutChain) -> int

Length of the longest common prefix of two navigation-domain paths.

Parameters

Name	Type	Default	Description
`a`	`LayoutChain`	—
`b`	`LayoutChain`	—

lookup_layout_chain_for_path

function

def lookup_layout_chain_for_path(path: str, *, router: Any | None, route_layout_chains: Mapping[str, Any]) -> LayoutChain | None

Resolve a concrete GET path to its filesystemLayoutChain.

Parameters

Name	Type	Default
`path`	`str`	—
`router`	`Any \| None`	—
`route_layout_chains`	`Mapping[str, Any]`	—

pick_navigation_layout_index

function

def pick_navigation_layout_index(*, layout_chain_current: LayoutChain | None, layout_chain_dest: LayoutChain) -> int | None

Choose the destination layout whose outlet should own the navigation.

Rules:

no navigation metadata on either side: keep legacy geometry-only behavior
one side annotated, the other not: be conservative and returnNone
same navigation-domain path: use the existing geometry within that domain
shared navigation ancestry but diverging child domains: target the last shared navigation boundary in the destination chain

Parameters

Name	Type	Default	Description
`layout_chain_current`	`LayoutChain \| None`	—
`layout_chain_dest`	`LayoutChain`	—

pick_outlet_layout_index

function

def pick_outlet_layout_index(*, nc: int, nd: int, common: int) -> int

Choose which layout level owns the primary outlet for this transition.

Parameters

Name	Type	Default
`nc`	`int`	—
`nd`	`int`	—
`common`	`int`	—

concrete_target_id

function

def concrete_target_id(layout: LayoutInfo, swap_scope_map: Mapping[str, str]) -> str

Resolve DOM target id (no #) for a layout using scope map and metadata.

Parameters

Name	Type	Default	Description
`layout`	`LayoutInfo`	—
`swap_scope_map`	`Mapping[str, str]`	—

resolve_navigation_swap

function

def resolve_navigation_swap(*, current_path: str, destination_path: str, layout_chain_current: LayoutChain | None, layout_chain_dest: LayoutChain | None, registry: FragmentTargetRegistry, swap_scope_map: Mapping[str, str]) -> SwapResolution | None

Return recommended swap metadata for boosted navigation, or None.

destination_path must be normalized (seenormalize_route_path()). When the destination has no layout chain, returns None. When current and destination paths are equal, returns None (avoid redundant swaps).

Parameters

Name	Type	Default
`current_path`	`str`	—
`destination_path`	`str`	—
`layout_chain_current`	`LayoutChain \| None`	—
`layout_chain_dest`	`LayoutChain \| None`	—
`registry`	`FragmentTargetRegistry`	—
`swap_scope_map`	`Mapping[str, str]`	—

make_swap_attrs

function

def make_swap_attrs(*, route_layout_chains: Mapping[str, Any], router: Any | None, fragment_target_registry: FragmentTargetRegistry, swap_scope_map: Mapping[str, str]) -> Any

Build the template globalswap_attrs(href, *, hx_boost=True).

Parameters

Name	Type	Default
`route_layout_chains`	`Mapping[str, Any]`	—
`router`	`Any \| None`	—
`fragment_target_registry`	`FragmentTargetRegistry`	—
`swap_scope_map`	`Mapping[str, str]`	—

View source · /home/runner/work/chirp/chirp/site/../src/chirp/templating/navigation_swap.py:1