handoff - Chirp

http.handoff

module

UI-neutral hypermedia handoff helpers Chirp owns.

Covers the minimal browser-facing contract for shell and fragment responses:

focus target / fallback after swaps
document title and history (HX-Push-Url / HX-Replace-Url)
announcements via a…

UI-neutral hypermedia handoff helpers Chirp owns.

Covers the minimal browser-facing contract for shell and fragment responses:

focus target / fallback after swaps
document title and history (HX-Push-Url / HX-Replace-Url)
announcements via a live region OOB payload
OOB transport helpers that compose with existing shell regions

These helpers do not prescribe component classes or a theme. Focus movement is delivered as anHX-Trigger-After-Settle event (chirp:focus) consumed by chirp-handoff.js— a CSP-safe external script, not inline handlers. RFC 017 focus/live-region policy is the accessibility input; this module does not invent a competing contract system.

http.handoff

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 FocusHandoff

Focus destination after an HTMX settle (or full-page equivalent).

targetis a CSS selector for the preferred focus destination. fallbackis used when the…

class TitleHandoff

Document title update, optionally paired with history headers.

class AnnouncementHandoff

Live-region announcement payload for HTMX OOB (or full-page seed).

class HypermediaHandoff

Bundle of Chirp-owned handoff intents for one response.

function focus_trigger_payload

Return theHX-Trigger-After-Settle payload for chirp:focus.

function title_oob_html

Render a<title>OOB fragment for document title updates.

function announce_oob_html

Render a live-region OOB fragment that replaces announcement text.

function handoff_oob_html

Concatenate OOB markup for title and announcement handoffs.

function apply_handoff

Apply handoff headers and append OOB markup to a buffered Response.

Full-page responses still receive title OOB (harmless no-op if the element is already…

FocusHandoff

class

Focus destination after an HTMX settle (or full-page equivalent).

targetis a CSS selector for the preferred focus destination. fallback is used when the target is missing (default #main, which Chirp shells marktabindex="-1"when they own an outlet).

TitleHandoff

class

Document title update, optionally paired with history headers.

AnnouncementHandoff

class

Live-region announcement payload for HTMX OOB (or full-page seed).

HypermediaHandoff

class

Bundle of Chirp-owned handoff intents for one response.

focus_trigger_payload

function

def focus_trigger_payload(focus: FocusHandoff) -> dict[str, Any]

Return theHX-Trigger-After-Settle payload for chirp:focus.

Parameters

Name	Type	Default	Description
`focus`	`FocusHandoff`	—

title_oob_html

function

def title_oob_html(title: TitleHandoff | str, *, element_id: str | None = None) -> str

Render a<title>OOB fragment for document title updates.

Parameters

Name	Type	Default	Description
`title`	`TitleHandoff \| str`	—
`element_id`	`str \| None`	`None`

announce_oob_html

function

def announce_oob_html(announcement: AnnouncementHandoff | str, *, politeness: Literal['polite', 'assertive'] = 'polite', region_id: str = ANNOUNCEMENTS_ELEMENT_ID) -> str

Render a live-region OOB fragment that replaces announcement text.

Parameters

Name	Type	Default
`announcement`	`AnnouncementHandoff \| str`	—
`politeness`	`Literal['polite', 'assertive']`	`'polite'`
`region_id`	`str`	`ANNOUNCEMENTS_ELEMENT_ID`

handoff_oob_html

function

def handoff_oob_html(handoff: HypermediaHandoff) -> str

Concatenate OOB markup for title and announcement handoffs.

Parameters

Name	Type	Default	Description
`handoff`	`HypermediaHandoff`	—

apply_handoff

function

def apply_handoff(response: Response, handoff: HypermediaHandoff) -> Response

Apply handoff headers and append OOB markup to a buffered Response.

Full-page responses still receive title OOB (harmless no-op if the element is already the document title) and announcement OOB when requested. Focus and history headers are HTMX-oriented; plain navigations ignore them.

Parameters

Name	Type	Default	Description
`response`	`Response`	—
`handoff`	`HypermediaHandoff`	—

View source · /home/runner/work/chirp/chirp/site/../src/chirp/http/handoff.py:1