chirp-ui API Reference

Framework-neutral package metadata for Chirp UI consumers. Frameworks and static-site generators can consume this module to discover the public Chirp UI template root, static assets, and manifest path without reading package internals or hardcoding filenames in theme templates.

Design system introspection — dump the chirp-ui API surface. Usage:: python -m chirp_ui.inspect # JSON report python -m chirp_ui.inspect --summary # compact table python -m chirp_ui.inspect --tokens # token catalog only python -m chirp_ui.inspect --components # component descriptors only python -m chirp_ui.inspect --provides # {% provide %} statements + annotations python -m chirp_ui.inspect --consumes # consume() calls + annotations python -m chirp_ui.inspect --audit-context # dead provides, unprovided consumes, annotation drift

Layout-affinity vocabulary for recipe-level workspace contracts. The current layout-affinity contract is intentionally narrow: rendered templates may emit documented ``data-chirpui-*`` attributes, and parent primitives may resolve those attributes inside their own scoped CSS. This module centralizes the allowed vocabulary without projecting it into the public manifest schema yet.

Alpine runtime detection for chirp-ui. chirp-ui has a small, enumerable set of macros that require ``chirpui-alpine.js`` to work at runtime (theme toggle, dialogs, dropdowns, collapsible sidebar, etc). When an app ships a layout that imports those macros but forgets the script tag, every interactive component breaks silently. This module exposes the manifest of Alpine-requiring factories and a pure `check_alpine_runtime`() helper. Chirp's ``use_chirp_ui(app)`` calls the helper against the first rendered response at freeze time so the mistake surfaces as a warning (or a raised error, in dev) at startup rather than as broken UI in production. Example:: from chirp_ui.alpine import check_alpine_runtime result = check_alpine_runtime(rendered_html) if not result.ok: missing = ", ".join(sorted(result.missing)) raise RuntimeError( f"layout uses Alpine factories {{{missing}}} but " "chirpui-alpine.js is not in the rendered HTML" )

Agent-groundable manifest of the chirp-ui component surface. This module publishes the component registry (``chirp_ui.components.COMPONENTS`` plus ``chirp_ui.tokens.TOKEN_CATALOG``) as a stable JSON snapshot. AI agents and docs tooling can read the manifest to cite real classes, tokens, slots, and templates instead of plausible-sounding ones. Schema ------ ``{"schema": "chirpui-manifest@5", "version": "<pkg>", "components": {...}, "tokens": {...}, "theme_packs": [...], "stats": {...}}`` * ``components`` keys sorted; each entry contains ``block``, ``variants``, ``sizes``, ``modifiers``, ``elements``, ``slots``, ``tokens``, ``extra_emits``, ``trim_emits``, ``emits``, ``template``, ``category``, ``maturity``, ``role``, ``authoring``, ``requires``, plus the ``@2`` additions ``macro``, ``params``, and ``lineno``, the ``@3`` composition additions ``composes``, ``slot_forwards``, and ``slots_yielded``, and the ``@4`` appearance/tone additions ``appearances`` and ``tones``. * ``params`` is a list of ``{"name": str, "has_default": bool, "is_required": bool}`` derived from the template AST via `chirp_ui._macro_introspect`. Empty when the descriptor has no template, the macro cannot be resolved, or the template has no ``{% def %}`` matching the resolved name. * ``macro`` is the resolved macro identifier (``descriptor.macro`` if set, else ``block.replace("-", "_")``). ``null`` when the descriptor has no template or no matching macro is found. * ``lineno`` is the source line of the ``{% def %}`` tag (``0`` when unavailable). * ``slots`` is the sorted union of ``descriptor.slots``, direct slots extracted from the macro body, and yielded slots accepted by composite wrappers. The unnamed default slot is represented as ``""``. Hand-authored descriptor entries can over-declare (e.g. for documentation), but the manifest never under-reports a real slot. * ``slots_extracted`` is the AST-derived slot list (sorted, default = ``""``) exposed separately so parity tests can spot descriptor↔template drift without losing the merged ``slots`` contract. * ``slots_yielded`` is the source-derived list of ``{% yield %}`` / ``{% yield name %}`` caller slots. Composite forwarding metadata is explicit in ``composes`` and ``slot_forwards``. * ``provides`` / ``consumes`` are sorted lists of context keys (e.g. ``"_card_variant"``) sourced from `chirp_ui.inspect`. A key is attributed to the macro whose ``{% def %}`` lineno is the largest one preceding the ``{% provide %}`` / ``consume()`` site. * ``description`` is the stripped text inside the leading ``{#- chirp-ui: ... -#}`` doc-block of the template file. One block per file, covering every macro; empty string when the descriptor has no template. New chirp-ui templates must carry a doc-block (``tests/test_description_coverage.py``). * ``tokens`` keys sorted; each entry is ``{"category": …, "scope": …}``. * ``theme_packs`` lists packaged token-only theme CSS resources in stable catalog order. * ``stats`` aggregates counts, including ``components_with_params``, a ``registry_debt`` scorecard for descriptor/CSS reconciliation burn-down, and a ``manifest_quality`` scorecard for agent-facing metadata coverage. Deterministic: two calls to `build_manifest`() yield byte-identical JSON. CLI --- ``python -m chirp_ui.manifest --json`` writes JSON to stdout. See ``docs/plans/done/PLAN-agent-grounding-depth.md`` and ``docs/DESIGN-manifest-signature-extraction.md``.

chirp-ui variant validation — strict mode, warning infrastructure, and registries. When strict mode is enabled (via `set_strict`()), validation warnings escalate to ``ValueError``. In non-strict mode, `_warn`() emits a filterable `ChirpUIValidationWarning` so developers see feedback without crashes. ``VARIANT_REGISTRY``, ``APPEARANCE_REGISTRY``, ``TONE_REGISTRY``, and ``SIZE_REGISTRY`` are derived from the canonical component descriptors in `chirp_ui.components`. Everything not in __all__ is internal and may change without notice.

Icon registry: semantic names → Unicode glyphs for chirp-ui components. Use the `icon` filter to resolve names in templates: `{{ "status" | icon }}` → ◎. Unknown names pass through unchanged for backward compatibility.

Fuzzy component discovery over the shipped manifest — ``python -m chirp_ui find``. Sprint 6 of the agent-grounding-depth epic. The manifest is the registry projection; this module turns it into a one-liner for humans and agents who know *what* they want but not the exact BEM block name. Search model ------------ A component matches a query when the query is a case-insensitive substring of any of: * ``name`` — the manifest key, e.g. ``metric-card`` * ``block`` — the BEM block, e.g. ``metric-card`` (usually same as name) * ``category`` — e.g. ``data-display``, ``feedback`` * ``description`` — the ``{#- chirp-ui: ... -#}`` doc-block text Query filters (``--category`` etc.) are applied AFTER substring match, so ``find --category=feedback`` lists every component in that category even when no term is given. Use ``--authoring=preferred`` to list the registry-blessed primitives agents should reach for first, or ``--authoring=compatibility`` to audit legacy helpers retained for existing templates. Output ------ One line per hit, stable/sorted:: {name:<30} {category:<16} {first-line-of-description} Exit code ``0`` always (including zero hits) — this is discovery, not validation. See ``docs/plans/PLAN-agent-grounding-depth.md § Sprint 6``.

chirp-ui — Reusable Kida component library for Chirp. Headless, htmx-native, zero JavaScript. Install and import:: pip install chirp-ui {%% from "chirpui/card.html" import card %%} {%% from "chirpui/modal.html" import modal, modal_trigger %%} When used with Chirp, components are auto-detected via ``PackageLoader``. For standalone Kida usage, call `get_loader`(). Call `register_filters`() to ensure bem/field_errors/html_attrs filters are available. Call `register_colors`() once per app if you use semantic color names with ``resolve_color`` / ``badge(..., color=...)`` / ``filter_chips`` (see ``docs/COMPONENT-OPTIONS.md``).

AST introspection for ``{% def %}`` macros — internal. Wraps `kida.lexer` + `kida.parser` to extract per-macro parameter metadata without compiling the template (so no chirp-ui filter stubs are required at manifest-build time). Used by `chirp_ui.manifest` to project macro Python signatures into the agent-groundable manifest. See ``docs/plans/done/PLAN-agent-grounding-depth.md`` and ``docs/DESIGN-manifest-signature-extraction.md``.

Template filters required by chirp-ui components. These match Chirp's filter API so chirp-ui works with any Chirp version. Register via `register_filters`() when using Chirp. Everything not in __all__ is internal and may change without notice.

``python -m chirp_ui`` dispatch — subcommand front door. Currently a single subcommand (``find``) plus a pointer to the existing ``python -m chirp_ui.manifest`` entry point. New subcommands go here. See ``docs/plans/PLAN-agent-grounding-depth.md § Sprint 6``.

CSS custom property catalog — machine-readable index of --chirpui-* tokens. Each `TokenDef` records a single CSS custom property: its name, semantic category, and scope (global or a component block name). The catalog is bootstrapped by ``scripts/extract_tokens.py`` and curated here as the source of truth. Tests validate it against ``chirpui.css`` to catch drift. Categories ---------- * **color** — semantic colors, state colors, gradients * **spacing** — fluid spacing scale and role aliases * **typography** — font sizes, weights, families, line-heights * **radius** — border-radius scale * **elevation** — box-shadow tokens * **motion** — easing curves and durations * **layout** — structural tokens (container max, grid min, sidebar dims) * **component** — per-component override knobs (scoped)

Route-family tab helpers for chirp-ui route_tabs component. Tab item: dict or object with ``href``, optional ``match`` (default ``"exact"``). Full dict shape (from Chirp ``TabItem`` via ``_tab_item_to_shell_dict``): ``{ label, href, icon?, badge?, match? }``.

Immutable catalog of token-only Chirp UI theme packs.

Component descriptors — single source of truth for chirp-ui's BEM API surface. Each `ComponentDescriptor` declares the full public contract of a component: block name, allowed variants (legacy/mutually exclusive), appearances, tones, sizes, boolean modifiers (additive), BEM elements, Kida slot names, and overridable CSS custom properties. Downstream consumers: * ``VARIANT_REGISTRY`` / ``SIZE_REGISTRY`` in `chirp_ui.validation` derive from ``COMPONENTS``. * The ``bem()`` filter validates against descriptors when strict mode is on. * Contract tests auto-generate expected CSS class names from descriptors. * `design_system_report`() exposes the full surface for introspection.

Browse Python API documentation by package.