hxdeck Slide Components
Relevant source files
The following files were used as context for generating this wiki page:
The hxdeck system provides a specialized UI framework within the HXLoLi project for creating presentation slides. It functions as an independent UI layer that consumes theme tokens to maintain visual consistency across different slide decks. The system organizes components into layers, including layout primitives, content blocks, data visualization, and specialized diagramming tools.
Sources: src/hxdeck/index.ts:1-12, src/hxdeck/Demo.tsx:64-70
Layered Architecture
The hxdeck system divides its functionality into six distinct layers. This structure ensures that UI controls remain decoupled from specific theme implementations and runtime logic.
The layered architecture separates theme contracts, runtime navigation, and various categories of visual components.
Sources: src/hxdeck/index.ts:8-15
Core Layers Description
| Layer | Responsibility | Key Elements |
|---|---|---|
| Theme | Defines token contracts and theme implementations. | DeckTheme, hxloliTheme, whaleTheme |
| Deck | Manages runtime state, navigation, and input handling. | Deck, Slide, Nav |
| UI | Provides layout primitives and content blocks. | Split, Columns, Bullets, Callout |
| Charts | Renders data visualizations using Recharts. | PieChartBlock, LineChartBlock, Tree |
| Code | Displays syntax-highlighted code snippets. | CodeBlock, CodeDiff |
| Meme | Handles theme-specific mascot and decorative assets. | Mascot, SlotMascot, Meme |
Sources: src/hxdeck/index.ts:8-15, src/hxdeck/theme/types.ts:157-170
Primary Layout Components
Layout components define the structure of a slide. They enforce specific grid or flex behaviors while remaining responsive to the current theme's scaling and spacing tokens.
Slide and Deck Containers
The Deck component serves as the root provider for theme context and handles slide transitions. The Slide component acts as the primary container for individual presentation screens, accepting title and chapter props for navigation.
The interaction flow shows how the Deck manages state and transitions between Slides while enforcing theme constraints.
Sources: src/hxdeck/Demo.tsx:55-70, src/hxdeck/index.ts:47-52
Layout Primitives
- Split: Creates a two-column layout with customizable ratios (e.g.,
1.15fr 1fr). It supports horizontal alignment and vertical centering. - Columns: Arranges content into 2 to 4 equal-width columns.
- PageHeader: Standardizes the opening structure of a slide with an eyebrow label, title, and description.
- Cover: Designed for title slides, featuring high-impact text placements for eyebrows, main titles, and subtitles.
Sources: src/hxdeck/Demo.tsx:78-85, src/hxdeck/blocks.tsx:1-20, src/hxdeck/ui/index.ts
Content and Data Blocks
Content blocks are modular components used within layout primitives to display information, data, or media.
Text and Information Blocks
- Bullets: Renders unordered lists with support for bold highlights.
- Callout: Displays semantic alerts (tip, warn, info, danger) using theme-defined colors.
- KeyValues: Presents metadata in a key-value pair grid.
- Quote: Provides styled blockquotes with citation fields.
- Steps: Visualizes sequential processes or methodologies.
Sources: src/hxdeck/Demo.tsx:81-125, src/hxdeck/index.ts:58-71
Data Visualization
The data layer utilizes recharts to render themed visualizations:
- PieChartBlock / LineChartBlock / BarChartBlock: Wrappers for standard charts that automatically adopt theme colors.
- Stat: Displays high-level metrics with labels, values, units, and hints.
- Tree: Renders hierarchical data structures in a node-link diagram.
Sources: src/hxdeck/Demo.tsx:132-150, src/hxdeck/index.ts:80-81
Diagramming System
The Diagram component renders inline SVG assets produced by archify. It supports advanced interaction features and theme integration.
- Theme Synchronization: Inline SVGs consume theme CSS variables, allowing diagrams to change colors instantly when the user switches themes.
- Interaction: The component provides independent wheel zooming and drag-to-pan functionality. These interactions are confined to the diagram container and do not trigger slide transitions.
- Variants:
architecture: Optimized for system structures.workflow: Designed for swimlanes and sequential nodes.DiagramWithNotes: A split layout combining a diagram with complementary side notes.
Sources: src/hxdeck/diagram.tsx:1-20, src/hxdeck/Demo.tsx:156-168, src/hxdeck/index.ts:74-75
Theming Contract
Themes are defined by a DeckTheme interface, ensuring that components only reference semantic tokens rather than hardcoded values.
export interface DeckColors {
bg: string; // Page background
surface: string; // Card/Panel surface
text: string; // Main text
primary: string; // Brand/Highlight color
success: string; // Semantic success
warn: string; // Semantic warning
danger: string; // Semantic danger
border: string; // Strokes
}
Sources: src/hxdeck/theme/types.ts:12-36
Scaling and Fluid Typography
The system uses absolute pixel values relative to a fixed 1600x900画布 (canvas). This prevents double-scaling issues when slides are projected or viewed on different screen sizes. The DeckScale interface manages font sizes (hero, display, h1, body) and grid spacing (sp2 through sp7).
Sources: src/hxdeck/theme/types.ts:60-90, src/hxdeck/theme/types.ts:133-140
Summary
The hxdeck component library provides a structured approach to presentation authoring within the HXLoLi ecosystem. By utilizing a strict token-based theme system and specialized layout blocks like Split and Diagram, it enables the creation of complex, interactive slides that maintain aesthetic integrity across different viewing environments. The system effectively separates content definition from visual implementation and runtime navigation.
Sources: src/hxdeck/index.ts:1-20, src/hxdeck/Demo.tsx:210-215