Components Overview

Glyph JS ships with 24 built-in UI components that transform YAML payloads inside fenced code blocks into rich, interactive visualizations. Each component has a Zod schema that validates its YAML at compile time, producing clear diagnostics if anything is wrong.

Authoring syntax

All components use the same fenced-code-block pattern. Write a fenced code block whose info string is ui: followed by the component name, and place valid YAML inside:

```ui:callout
type: info
content: This is an informational callout.
```

The YAML inside the block is parsed and validated by @glyphjs/compiler against the component Zod schema defined in @glyphjs/schemas.

Component catalog

Layout

Component	Type	Description
Columns	ui:columns	Place blocks side by side with proportional column widths.
Rows	ui:rows	Stack blocks vertically with gap control and optional ratio.
Panel	ui:panel	Wrap a block in a styled card, bordered, elevated, or ghost container.

Nest ui:columns and ui:rows recursively to build any 2D layout. See the Layouts guide for patterns and examples.

Content & Structure

Component	Type	Description
Callout	ui:callout	Highlighted info, warning, error, and tip blocks for narrative structuring.
Tabs	ui:tabs	Tabbed content containers with switchable panels.
Steps	ui:steps	Sequential step-by-step guides with progress indication.
Accordion	ui:accordion	Collapsible content sections with expand/collapse interaction.
Card	ui:card	Grid of cards with titles, descriptions, and optional actions.
KPI	ui:kpi	Key performance indicator metrics with trends and formatting.

Data & Comparison

Component	Type	Description
Table	ui:table	Sortable, filterable, aggregatable data tables.
Chart	ui:chart	Line, bar, area, and OHLC financial charts.
Comparison	ui:comparison	Side-by-side feature comparison tables.
CodeDiff	ui:codediff	Syntax-highlighted code diffs with line-level changes.

Diagrams & Visualization

Component	Type	Description
Graph	ui:graph	DAGs, flowcharts, mind maps, and force-directed graphs.
Relation	ui:relation	Entity-relationship diagrams with cardinality annotations.
Flowchart	ui:flowchart	Process flowcharts with decision nodes and directional edges.
Sequence	ui:sequence	Sequence diagrams for message passing between actors.
MindMap	ui:mindmap	Hierarchical mind map diagrams with radial layout.
Architecture	ui:architecture	System architecture diagrams with grouped nodes and connections.
FileTree	ui:filetree	Interactive file and directory tree views.

Narrative & Interactive

Component	Type	Description
Timeline	ui:timeline	Chronological event sequences on a visual timeline.
Infographic	ui:infographic	Multi-section visual infographics with icons and stats.
Equation	ui:equation	Step-by-step mathematical equations with annotations.
Quiz	ui:quiz	Interactive quizzes with multiple-choice questions and feedback.

Reserved YAML keys

Three top-level YAML keys are reserved and processed by the compiler before schema validation:

• glyph-id — An explicit, user-assigned block ID that overrides the auto-generated ID. Enables stable cross-block references.
• refs — An array of reference objects ({ target, type, label }) that declare relationships between blocks.
• interactive — When set to true, enables interaction event emission for this block. The runtime injects an onInteraction callback that the component calls when the user interacts (clicks, sorts, selects, etc.).

These keys are stripped from the component data before it reaches the component schema.

Interaction events

Components marked with interactive: true can emit events when users interact with them. The following components support interaction events:

Component	Event kind	Payload
Quiz	quiz-submit	questionIndex, question, selected, correct, score
Table	table-sort	state (sort column, direction, filters, visible rows)
Table	table-filter	state (sort column, direction, filters, visible rows)
Tabs	tab-select	tabIndex, tabLabel
Accordion	accordion-toggle	sectionIndex, sectionTitle, expanded
FileTree	filetree-select	path, type (file/directory), expanded
Graph	graph-node-click	nodeId, nodeLabel
Chart	chart-select	seriesIndex, dataIndex, label, value
Comparison	comparison-select	optionIndex, optionName

See the Authoring Guide for usage details and the Plugin API for the TypeScript types.

Container components

ui:tabs and ui:steps are container components whose children are expressed as Markdown strings inside the YAML content fields. The compiler re-parses each content field recursively, producing child Block[] entries in the IR. This allows tabs and steps to contain rich Markdown (paragraphs, lists, code blocks) but not nested ui: components in v1.

Layout components

ui:columns, ui:rows, and ui:panel are layout components that arrange other blocks in 2D space. Their children are suppressed block variables — blocks defined with =_name that are compiled but not rendered directly. The layout component resolves these names at compile time and stores them in block.children. The runtime renders each child via BlockRenderer inside the layout’s grid or container. See the Layouts guide for usage.