Module

`templating.composition`

Python-first composition vocabulary for shell/content assembly.

ViewRef, RegionUpdate, and PageComposition replace block_name/page_block_name mental overhead with explicit role-based fields. Routes return these objects; the render-plan layer decides what to render based on request headers.

Classes

ViewRef 3 ▼

Reference to a template block with context. Used for both main content and region updates (shell a…

Reference to a template block with context.

Used for both main content and region updates (shell actions, badges, breadcrumbs, etc.).

Attributes

Name	Type	Description
`template`	`str`	—
`block`	`str`	—
`context`	`dict[str, Any]`	—

RegionUpdate 3 ▼

Out-of-band update for a persistent shell region. Renders a ViewRef and delivers it as hx-swap-oob…

Out-of-band update for a persistent shell region.

Renders a ViewRef and delivers it as hx-swap-oob to the named region (DOM element ID). Mode defaults to "oob".

Attributes

Name	Type	Description
`region`	`str`	—
`view`	`ViewRef`	—
`mode`	`str`	—

PageComposition 7 ▼

Explicit page composition with fragment, page block, and regions. Replaces Page/LayoutPage block_n…

Explicit page composition with fragment, page block, and regions.

Replaces Page/LayoutPage block_name/page_block_name with:

fragment_block: narrow block for non-boosted fragment requests. When None, resolved from FragmentTargetRegistry via HX-Target.
page_block: wider root for boosted navigation (or full page)
regions: shell actions, badges, and other persistent-region refreshes

Usage::

PageComposition(
    template="skills/page.html",
    fragment_block="page_content",
    page_block="page_root",
    context={"skills": skills},
    regions=(
        RegionUpdate(
            region="shell_actions",
            view=ViewRef(
                template="chirp/shell_actions.html",
                block="content",
                context={"shell_actions": actions},
            ),
        ),
    ),
)

Attributes

Name	Type	Description
`template`	`str`	—
`fragment_block`	`str \| None`	—
`page_block`	`str \| None`	—
`context`	`dict[str, Any]`	—
`regions`	`tuple[RegionUpdate, ...]`	—
`layout_chain`	`LayoutChain \| None`	—
`context_providers`	`tuple[ContextProvider, ...]`	—