blocks_gallery - chirp-ui

Registry-backed blocks gallery — copy-paste snippets and live previews.

Generates the manifest-driven blocks catalog consumed by the component showcase and freshness-gated in CI (scripts/build_blocks_gallery.py).

blocks_gallery

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

function is_public_component

Return whether a manifest entry belongs in the public blocks gallery.

function summary_line

Return the first non-empty line of a template doc-block.

function extract_usage_snippet

Extract the Usage example from a template doc-block, if present.

function _classify_pseudo_line

Classify one Usage line for pseudo-syntax normalization.

function normalize_usage_snippet

Convert template doc-block pseudo-syntax into valid Kida.

function is_visual_preview

Return whether rendered preview HTML contains a chirp-ui component.

function fallback_copy_snippet

Synthesize a minimal import + call when the doc-block has no Usage section.

function copy_snippet_for

Return the copy-paste Kida snippet for one manifest component.

function render_preview_html

Try to render a usage snippet; return(html, error).

function preview_snippet_for

Render a snippet, falling back to a synthesized import/call when needed.

function build_block_entry

Build one gallery record for a manifest component.

function build_gallery

Build the full blocks gallery payload from the live registry projection.

function gallery_check_payload

Return a platform-stable gallery payload for CI freshness checks.

Live preview HTML/error strings can differ across OS/Python builds; the gate compares manifest-derived metadata and…

function to_json_gallery

Serialize a gallery payload to canonical JSON.

function to_json_gallery_check

Serialize the freshness-gate view of a gallery payload.

is_public_component

function

def is_public_component(entry: dict[str, Any]) -> bool

Return whether a manifest entry belongs in the public blocks gallery.

Parameters

Name	Type	Default	Description
`entry`	`dict[str, Any]`	—

summary_line

function

def summary_line(description: str) -> str

Return the first non-empty line of a template doc-block.

Parameters

Name	Type	Default	Description
`description`	`str`	—

extract_usage_snippet

function

def extract_usage_snippet(description: str) -> str

Extract the Usage example from a template doc-block, if present.

Parameters

Name	Type	Default	Description
`description`	`str`	—

_classify_pseudo_line

function

def _classify_pseudo_line(stripped: str) -> tuple[str, str | None]

Classify one Usage line for pseudo-syntax normalization.

Parameters

Name	Type	Default	Description
`stripped`	`str`	—

normalize_usage_snippet

function

def normalize_usage_snippet(snippet: str) -> str

Convert template doc-block pseudo-syntax into valid Kida.

Parameters

Name	Type	Default	Description
`snippet`	`str`	—

is_visual_preview

function

def is_visual_preview(html: str | None) -> bool

Return whether rendered preview HTML contains a chirp-ui component.

Parameters

Name	Type	Default	Description
`html`	`str \| None`	—

fallback_copy_snippet

function

def fallback_copy_snippet(name: str, entry: dict[str, Any]) -> str

Synthesize a minimal import + call when the doc-block has no Usage section.

Parameters

Name	Type	Default	Description
`name`	`str`	—
`entry`	`dict[str, Any]`	—

copy_snippet_for

function

def copy_snippet_for(name: str, entry: dict[str, Any]) -> str

Return the copy-paste Kida snippet for one manifest component.

Parameters

Name	Type	Default	Description
`name`	`str`	—
`entry`	`dict[str, Any]`	—

render_preview_html

function

def render_preview_html(env: Environment, snippet: str) -> tuple[str | None, str | None]

Try to render a usage snippet; return(html, error).

Parameters

Name	Type	Default	Description
`env`	`Environment`	—
`snippet`	`str`	—

preview_snippet_for

function

def preview_snippet_for(name: str, entry: dict[str, Any], env: Environment, snippet: str) -> tuple[str | None, str | None]

Render a snippet, falling back to a synthesized import/call when needed.

Parameters

Name	Type	Default
`name`	`str`	—
`entry`	`dict[str, Any]`	—
`env`	`Environment`	—
`snippet`	`str`	—

build_block_entry

function

def build_block_entry(name: str, entry: dict[str, Any], *, env: Environment | None = None) -> dict[str, Any]

Build one gallery record for a manifest component.

Parameters

Name	Type	Default
`name`	`str`	—
`entry`	`dict[str, Any]`	—
`env`	`Environment \| None`	`None`

build_gallery

function

def build_gallery(*, with_previews: bool = True) -> dict[str, Any]

Build the full blocks gallery payload from the live registry projection.

Parameters

Name	Type	Default	Description
`with_previews`	`bool`	`True`

gallery_check_payload

function

def gallery_check_payload(gallery: dict[str, Any]) -> dict[str, Any]

Return a platform-stable gallery payload for CI freshness checks.

Live preview HTML/error strings can differ across OS/Python builds; the gate compares manifest-derived metadata and copy snippets only.

Parameters

Name	Type	Default	Description
`gallery`	`dict[str, Any]`	—

to_json_gallery

function

def to_json_gallery(gallery: dict[str, Any], *, indent: int = 2) -> str

Serialize a gallery payload to canonical JSON.

Parameters

Name	Type	Default	Description
`gallery`	`dict[str, Any]`	—
`indent`	`int`	`2`

to_json_gallery_check

function

def to_json_gallery_check(gallery: dict[str, Any], *, indent: int = 2) -> str

Serialize the freshness-gate view of a gallery payload.

Parameters

Name	Type	Default	Description
`gallery`	`dict[str, Any]`	—
`indent`	`int`	`2`

View source · /home/runner/work/chirp-ui/chirp-ui/site/../src/chirp_ui/blocks_gallery.py:1