code-block-usage

name	code-block-usage
description	Instructions and guidelines for using the code-block components (CodeBlock, CodeBlockSource, InternalCodeBlock) within the sona-ui repository.

Code Block Components in Sona-UI

This skill describes how to correctly utilize the suite of code-block components available within the sona-ui repository: CodeBlock, CodeBlockSource, and InternalCodeBlock. These components provide rich syntax highlighting using Shiki, line highlighting, and diff support.

Available Components

1. CodeBlock

Location: src/components/code-block/code-block.tsx

This is the main foundational block that creates a context-aware boundary. It provides elements like tabs, header, line numbers, and floating copy capabilities.

Usage: Use CodeBlock when you need maximum granular control over the UI, explicitly laying out headers, tabs, or applying specific stylings to the <pre> wrapper.

import { CodeBlock, CodeBlockHeader, CodeBlockPre, CodeBlockCode } from "@/components/code-block/code-block";

<CodeBlock code={"const x = 1;"} language="typescript" showDiff={false} highlightLines={[1]}>
  <CodeBlockHeader filename="example.ts" />
  <CodeBlockPre lineNumbers={true}>
    <CodeBlockCode />
  </CodeBlockPre>
</CodeBlock>

Props:

• code (string): The raw code to be highlighted.
• language (string): The syntax highlighting language (default: javascript).
• floatingCopy (boolean): Shows a floating copy button overlay.
• highlightLines (number[] | string): Array of line numbers to highlight differently.
• focusLines (number[] | string): Blurs out lines that are not in focus.
• showDiff (boolean): Indicates deleted/added lines using the [data-diff] lines internally.

---

2. CodeBlockSource

Location: src/components/code-block/code-block-source.tsx

This component takes a filePath (or falls back to code prop) to dynamically read the exact source code of a file from the disk and pass it down into the CodeBlock.

Usage: Ideal for documentation pages where you want the code block to stay intrinsically synchronized with the file's current truth instead of manually copy-pasting code snippets into your TSX. Requires usage within a server component since it performs filesystem reads (readFileContent).

import { CodeBlockSource } from "@/components/code-block/code-block-source";

// Usage in a server component
<CodeBlockSource filePath="src/components/button/button.tsx" language="tsx">
  <CodeBlockPre>
    <CodeBlockCode />
  </CodeBlockPre>
</CodeBlockSource>

---

3. InternalCodeBlock

Location: src/components/code-block/internal-code-block.tsx

A pre-wired abstraction perfectly suited for simple code block rendering without boilerplate.

Usage: When you just want to pass code, language, and filename and get a standard block structure.

import { InternalCodeBlock } from "@/components/code-block/internal-code-block";

<InternalCodeBlock
  code="console.log('Hello');"
  language="javascript"
  filename="hello.js"
/>

---

Technical Dependencies

When modifying or working with these components, be aware of the following cross-dependencies:

• Shiki: Handles syntax highlighting dynamically.
• Base UI: Components like <Menu> and styling merge utilities (@base-ui/react/use-render, @base-ui/react/merge-props).
• Icons: lucide-react for standard UI icons and @icons-pack/react-simple-icons for language-specific glyphs.
• Internal Components:
  • Tabs from @/components/tabs/tabs
  • ScrollArea from @/components/scroll-area/scroll-area
  • CopyButton from ../copy-button/copy-button
  • readFileContent from @/lib/file-utils (For CodeBlockSource)

Best Practices

1. Prefer CodeBlockSource for internal code: When referencing files already within the sona-ui repository, use CodeBlockSource with absolute paths relative to root or workspace relative paths that readFileContent supports. This keeps documentation synced with reality.
2. Handle Context properly: CodeBlockHeader, CodeBlockPre, CodeBlockLanguage, CodeBlockCode, etc., must be placed inside <CodeBlock>, as they consume context (like lines, nodes, code, showDiff).
3. Use the built-in diff functionality: When showcasing changes to code, instead of manually typing - and +, use showDiff and let the component's internal shiki parsing colorize the deltas appropriately via the standard patch formatting.

Reference Files

If you need to bootstrap these components into another standalone project, full source code for the components is provided in the reference/ block of this skill.

• code-block.tsx
• code-block-source.tsx
• internal-code-block.tsx