Data Presentation Layouts
Relevant source files
The following files were used as context for generating this wiki page:
Data Presentation Layouts in HX-UI provide a standardized suite of components for displaying structured information, metrics, and visualizations. These components enforce visual consistency across the application by abstracting complex concerns such as sticky headers, responsive charting, and state-driven boundaries (loading, error, or empty).
The layout system separates concerns into high-level containers like Card and PageHeader, specialized data views like DataTable and Charts, and status indicators like StatCard and EmptyState. These layouts utilize a unified design token system for typography and colors to ensure professional appearance without hardcoded values.
Sources: src/index.ts:10-15, README.md:38-56
Tabular Data Systems
The DataTable component serves as the primary tool for displaying collections of structured data. It intentionally avoids internal data fetching to remain agnostic of the backend architecture, such as polling or Server-Sent Events (SSE).
Core Features
- Sticky Headers: Enabled by default to maintain context during vertical scrolling.
- CSS Grid Layout: Uses native browser column sizing instead of fixed table layouts for better responsiveness.
- Interactive Rows: Supports
onRowClickwith built-in keyboard accessibility (Enter/Space support). - Integrated States: Includes built-in support for loading skeletons and empty states within the table structure.
Sources: src/layout/DataTable.tsx:23-56, src/layout/DataTable.tsx:102-132
Search Integration
The useTableSearch hook provides synchronized filtering logic. It prevents the common "input-view desync" bug by encapsulating the query state and the filtered result set in a single hook.
Sources: src/layout/DataTable.tsx:181-197
Statistical Metrics and Grids
The StatCard displays single-point metrics with optional trend indicators (tones). To ensure visual stability during data refreshes, it uses tabular-nums for its value display, preventing horizontal jitter when numbers change.
| Component | Purpose | Key Property |
|---|---|---|
StatCard | Individual metric display | tone (good, bad, muted, accent) |
StatGrid | Layout for multiple metrics | columns (2, 3, 4, or 5) |
Sources: src/layout/StatCard.tsx:12-25, src/layout/StatCard.tsx:82-95
Data Visualization (Charts)
HX-UI wraps Recharts 3 to provide responsive, themed charts. Every chart component includes ResponsiveContainer to ensure it follows the parent container's width.
Incremental Animation Strategy
Unlike standard charts that redraw the entire line when data changes, HX-UI distinguishes between "Initial Load" and "Incremental Updates."
- Initial Load: Plays a full drawing animation (e.g., line drawing from left to right).
- Incremental Update: Uses
matchAppendormatchByDataKeyto keep existing points stationary while fading in new data.
State Boundary Management
The DataBoundary component centralizes the conditional logic for rendering different UI states based on data availability. It enforces a strict sequence of checks to prevent UI flickers (e.g., showing "No Data" briefly before "Loading").
Boundary Execution Order
- Loading: Renders
EmptyStatewith a spin animation. - Error: Renders
EmptyStatewith a destructive tone and an optional retry action. - Empty: Renders
EmptyStatewith the "No Data" placeholder. - Content: Renders the
childrenif all above conditions are false.
Sources: src/layout/EmptyState.tsx:88-110
Page and Content Structure
The library provides structural components to define the visual rhythm of a page.
PageHeader
PageHeader ensures that the title and right-aligned actions (e.g., buttons, search bars) maintain a consistent baseline. It enforces a "no-wrap" policy for titles, using truncation to preserve the vertical rhythm of the page.
Sources: src/layout/PageHeader.tsx:14-25
Card
Card is the fundamental container for data modules. It provides consistent padding, border-radius, and background colors defined in the tokens.
Sources: src/layout/Card.tsx:5-15
CodeBlock
For technical documentation, CodeBlock integrates the shiki engine with the one-dark-pro theme. It includes a built-in copy button with feedback and supports line highlighting.
Sources: src/layout/CodeBlock.tsx:15-40
Design Tokens and Typography
The presentation layer relies on specific font-size tokens defined in tokens.css. These tokens include half-pixel values (e.g., 10.5px, 12.5px) to accommodate the high information density required for complex data tables.
| Token | Size | Typical Usage |
|---|---|---|
--fs-xs | 11px | Table Headers, Metadata |
--fs-sm | 12px | Body Text, Tooltips |
--fs-sm-half | 12.5px | Data Table Cells |
--fs-2xl | 20px | Page Titles |
Sources: src/tokens.css:160-175
Conclusion
Data Presentation Layouts in HX-UI prioritize a "Data-First" philosophy. By enforcing specific behaviors like tabular-nums in metric cards, incremental animations in charts, and a strict DataBoundary sequence, the library ensures that complex data interfaces remain performant and visually stable regardless of data volatility.
Sources: README.md:10-25, src/index.ts:1-20