CodeBlock & Syntax Highlighting
Relevant source files
The following files were used as context for generating this wiki page:
The CodeBlock component provides a high-fidelity syntax highlighting solution for code snippets. It leverages the VS Code TextMate grammar engine through the shiki library to ensure that code rendering matches professional editor environments.
This component forms part of the "Layout" layer of the HX-UI library. It implements a fixed "One Dark Pro" theme to maintain visual consistency across the design system.
Sources: src/layout/CodeBlock.tsx:11-23, README.md:37, src/index.ts:133-136
Architecture and Data Flow
The highlighting process involves a performance-first pipeline that manages asynchronous processing, memory-efficient caching, and safety thresholds.
Highlighting Logic Flow
The following diagram illustrates how the component handles a code string from input to final rendering.
The component validates the input size before processing to prevent browser freezes. If the code exceeds limits, it falls back to a standard <pre> block.
Sources: src/layout/CodeBlock.tsx:86-118, src/layout/CodeBlock.tsx:156-173
Asynchronous Processing
Syntax highlighting occurs asynchronously inside a useEffect hook. A cancelled ref ensures that if the component unmounts or props change before shiki finishes, the state does not update with stale data.
Sources: src/layout/CodeBlock.tsx:139-173
Key Implementation Details
Performance Caching
HX-UI implements a manual LRU-style cache for highlighted HTML strings. This prevents layout jumps and re-processing overhead when components are scrolled in and out of view in virtualized lists.
| Cache Constraint | Value | Description |
|---|---|---|
MAX_ENTRIES | 128 | Maximum number of individual code snippets stored. |
MAX_UNITS | 4,000,000 | Maximum total characters (key + value) allowed in memory. |
Sources: src/layout/CodeBlock.tsx:59-80
Processing Budget
To maintain interface responsiveness, the system enforces specific complexity limits on code inputs.
- Maximum Length: 30,000 characters.
- Maximum Language String: 128 characters.
- Line Constraints: Maximum 1,000 lines or 2,000 characters per single line.
Sources: src/layout/CodeBlock.tsx:86-97
Theme and UI Integration
The component uses a fixed one-dark-pro theme. While it relies on shiki for token colors, it manually defines UI colors to ensure the container housing the code matches the syntax background perfectly.
export const ONE_DARK_PRO = {
background: "#282c34",
foreground: "#abb2bf",
lineNumber: "#495162",
lineHighlight: "#2c313c",
selection: "#67769660",
} as const;
Sources: src/layout/CodeBlock.tsx:44-51
API Reference
CodeBlockProps
The component is configured via the CodeBlockProps interface.
| Property | Type | Default | Description |
|---|---|---|---|
code | string | - | The raw source code to be highlighted. |
lang | string | "text" | Language identifier for shiki (e.g., tsx, bash). |
title | string | lang | Text displayed in the top-left header. |
showLineNumbers | boolean | false | Toggles visibility of the line number gutter. |
highlightLines | readonly number[] | - | An array of line numbers (1-indexed) to highlight. |
showHeader | boolean | true | Toggles the visibility of the top title/action bar. |
actions | ReactNode | - | Custom elements (buttons, links) in the header. |
Sources: src/layout/CodeBlock.tsx:100-117
Typography and Styling
The CodeBlock component utilizes the --font-mono token defined in the design system. This token prioritizes high-legibility programming fonts.
Font Stack Order:
- JetBrains Mono / JetBrainsMono Nerd Font
- Cascadia Code
- Fira Code
- SF Mono / SFMono-Regular
- Menlo / Consolas
- System Monospace
Sources: src/tokens.css:35-43
Features
Copy Functionality
A CopyButton provides immediate feedback. When you click "Copy," the text changes to "Copied" (已复制) and turns emerald for 1.2 seconds before resetting. It uses the navigator.clipboard API.
Sources: src/layout/CodeBlock.tsx:120-137
Line Highlighting
The component applies highlighting to specific lines by injecting CSS selectors. It uses semi-transparent white overlays (bg-white/[0.05]) on top of the One Dark Pro background to mark specific nth-child lines.
Sources: src/layout/CodeBlock.tsx:210-216
Summary
The CodeBlock system provides a robust, professional code viewing experience by integrating shiki with a custom-built React wrapper. It ensures performance through strict budgeting and caching while maintaining a high-fidelity visual standard using a consistent theme and optimized font stacks.