Module

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

1Class10Functions

Classes

SwapResolution 4 ▼
Recommended swap for a boosted GET navigation.

Recommended swap for a boosted GET navigation.

Attributes

Name Type Description
htmx_target str —
target_id str —
scope str —
fragment_block str | None —

Functions

normalize_route_path 1 str ▼
Normalize a URL path for comparisons (no query or fragment).
def normalize_route_path(path: str) -> str
Parameters
Name Type Description
path str
Returns
str
resolve_destination_path 2 str | None ▼
Resolve *href* to an absolute site path, or None if external / unusable.
def resolve_destination_path(current_path: str, href: str) -> str | None
Parameters
Name Type Description
current_path str
href str
Returns
str | None
common_layout_prefix_len 2 int ▼
Length of the longest common prefix of two layout chains (template-wise).
def common_layout_prefix_len(a: LayoutChain, b: LayoutChain) -> int
Parameters
Name Type Description
a LayoutChain
b LayoutChain
Returns
int
common_navigation_prefix_len 2 int ▼
Length of the longest common prefix of two navigation-domain paths.
def common_navigation_prefix_len(a: LayoutChain, b: LayoutChain) -> int
Parameters
Name Type Description
a LayoutChain
b LayoutChain
Returns
int
lookup_layout_chain_for_path 3 LayoutChain | None ▼
Resolve a concrete GET path to its filesystem ``LayoutChain``.
def lookup_layout_chain_for_path(path: str, *, router: Any | None, route_layout_chains: Mapping[str, Any]) -> LayoutChain | None
Parameters
Name Type Description
path str
router Any | None
route_layout_chains Mapping[str, Any]
Returns
LayoutChain | None
pick_navigation_layout_index 2 int | None ▼
Choose the destination layout whose outlet should own the navigation. Rules: -…
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 Description
layout_chain_current LayoutChain | None
layout_chain_dest LayoutChain
Returns
int | None
pick_outlet_layout_index 3 int ▼
Choose which layout level owns the primary outlet for this transition.
def pick_outlet_layout_index(*, nc: int, nd: int, common: int) -> int
Parameters
Name Type Description
nc int
nd int
common int
Returns
int
concrete_target_id 2 str ▼
Resolve DOM target id (no #) for a layout using scope map and metadata.
def concrete_target_id(layout: LayoutInfo, swap_scope_map: Mapping[str, str]) -> str
Parameters
Name Type Description
layout LayoutInfo
swap_scope_map Mapping[str, str]
Returns
str
resolve_navigation_swap 6 SwapResolution | None ▼
Return recommended swap metadata for boosted navigation, or None. *destination…
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 Description
current_path str
destination_path str
layout_chain_current LayoutChain | None
layout_chain_dest LayoutChain | None
registry FragmentTargetRegistry
swap_scope_map Mapping[str, str]
Returns
SwapResolution | None
make_swap_attrs 4 Any ▼
Build the template global ``swap_attrs(href, *, hx_boost=True)``.
def make_swap_attrs(*, route_layout_chains: Mapping[str, Any], router: Any | None, fragment_target_registry: FragmentTargetRegistry, swap_scope_map: Mapping[str, str]) -> Any
Parameters
Name Type Description
route_layout_chains Mapping[str, Any]
router Any | None
fragment_target_registry FragmentTargetRegistry
swap_scope_map Mapping[str, str]
Returns
Any