chirp_ui - Chirp

ext.chirp_ui

module

chirp-ui integration — register static files and filters for chirp-ui components.

Requires: pip install chirp-ui

Usage::

from chirp import App from chirp.ext.chirp_ui import use_chirp_ui app = App(AppConfig(template_dir="templates")) use_chirp_ui(app) # Registers template loader,…

chirp-ui integration — register static files and filters for chirp-ui components.

Requires: pip install chirp-ui

Usage::

from chirp import App
from chirp.ext.chirp_ui import use_chirp_ui

app = App(AppConfig(template_dir="templates"))
use_chirp_ui(app)  # Registers template loader, static files, filters, and middleware
app.run()

ext.chirp_ui

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 _ChirpUIAppThemeInject

Inject ChirpUI's token-only app theme after the base stylesheet.

function use_chirp_ui

Call after App creation. Explicitly registers aPackageLoaderfor chirp-ui templates (chirp-ui is…

function _discover_chirpui_components

Return the set of available chirp-ui component template filenames.

ReturnsNoneif the chirp-ui templates directory cannot be found (e.g. editable install without the…

function check_chirpui_imports

Verify that{% from "chirpui/..." %}imports reference real components.

Catches typos like{% from "chirpui/cardd.html" import card %}at startup instead of letting…

function check_design_system_surface

Report design system surface and flag descriptor/template mismatches.

ComparesCOMPONENTSagainst the actual template files on disk. Components with a declaredtemplatethat does…

_ChirpUIAppThemeInject

class

Inject ChirpUI's token-only app theme after the base stylesheet.

use_chirp_ui

function

def use_chirp_ui(app: App, prefix: str = '/static', strict: bool | Literal['auto'] | None = None) -> None

Call after App creation. Explicitly registers aPackageLoaderfor chirp-ui templates (chirp-ui is never ambiently discovered from package presence alone), serves chirpui.css, chirpui-alpine.js, themes/, chirpui-transitions.css from the chirp-ui package, and registers chirp-ui filters (bem, field_errors, html_attrs, validate_variant) so components render correctly. It also upgrades chirp-ui's route_link_attrs global to use Chirp's route-aware swap_attrs resolution for supported internal links.

Alpine.js is auto-enabled (chirp-ui components require it). Chirp is the single authority for Alpine injection — theapp_shell_layout.htmldoes not include its own Alpine scripts.

htmx is not auto-enabled: unlike Alpine, the chirp-ui layouts (shell.html/boost.html) already ship their own htmx <script> tags (plus the SSE extension), soAppConfig(htmx=True)injection is left opt-in to avoid double-loading. Those hardcoded tags carry data-chirp="htmx" so that if an app does set htmx=Truealongside chirp-ui, the injector's dedup skips re-adding the core script.

strictcontrols chirp-ui variant validation (invalid variants escalate from warning toValueError). None(default) mirrors app.config.debug. True/Falseset the mode explicitly. "auto" delegates to chirp-ui's CHIRP_UI_DEVenv var so dev hosts opt in without code changes.

Raises ImportError if chirp-ui is not installed.

Parameters

Name	Type	Default
`app`	`App`	—
`prefix`	`str`	`'/static'`
`strict`	`bool \| Literal['auto'] \| None`	`None`

_discover_chirpui_components

function

def _discover_chirpui_components() -> frozenset[str] | None

Return the set of available chirp-ui component template filenames.

ReturnsNoneif the chirp-ui templates directory cannot be found (e.g. editable install without the expected layout).

No parameters.

check_chirpui_imports

function

def check_chirpui_imports(snapshot: ContractCheckSnapshot, result: CheckResult) -> None

Verify that{% from "chirpui/..." %}imports reference real components.

Catches typos like{% from "chirpui/cardd.html" import card %}at startup instead of letting them surface as runtimeTemplateNotFound errors.

Parameters

Name	Type	Default	Description
`snapshot`	`ContractCheckSnapshot`	—
`result`	`CheckResult`	—

check_design_system_surface

function

def check_design_system_surface(snapshot: ContractCheckSnapshot, result: CheckResult) -> None

Report design system surface and flag descriptor/template mismatches.

ComparesCOMPONENTSagainst the actual template files on disk. Components with a declaredtemplatethat does not exist on disk are flagged as errors. Templates that exist but have no descriptor are flagged as informational notes (not all templates need descriptors immediately).

Parameters

Name	Type	Default	Description
`snapshot`	`ContractCheckSnapshot`	—
`result`	`CheckResult`	—

View source · /home/runner/work/chirp/chirp/site/../src/chirp/ext/chirp_ui.py:1