component-preview-usage

name	component-preview-usage
description	Instructions and guidelines for using the component-preview and component-preview-server components within the Sona-UI repository. Includes details on registry fetching.

Component Preview in Sona-UI

This skill covers the usage of the Component Preview ecosystem in the sona-ui repository. The preview system handles displaying live React components alongside their raw source code in an interactive tabbed interface.

Core Components

The system relies on three primary files:

1. ComponentPreview (src/components/common/component-preview.tsx): The client-side UI wrapper providing the Tabs (Preview / Code) and invoking CodeBlock under the hood. It takes raw component and code nodes.
2. ComponentPreviewServer (src/components/common/component-preview-server.tsx): A server component wrapper that automatically resolves a component and its source code from a global registry map.
3. ComponentWrapper (src/components/common/component-wrapper.tsx): The visual layout shell that adds the standard background, padding, and centered layout to the actual rendered component.

Usage Guidelines

1. Manual Usage (ComponentPreview)

If you already have the component node and its raw string code, you can use ComponentPreview directly. This is generalized and can be used on any path or any arbitrary block of UI.

import ComponentPreview from "@/components/common/component-preview";
import MyButton from "./my-button";

const codeString = `
export default function MyButton() {
  return <button>Click</button>
}
`;

export default function Page() {
  return (
    <ComponentPreview 
      component={<MyButton />} 
      code={codeString} 
    />
  )
}

2. Registry Usage (ComponentPreviewServer)

To build scalable documentation (like a UI library docs site), rely on ComponentPreviewServer. This abstracts away importing explicit components and parsing raw strings by reading from a central registry.

import { ComponentPreviewServer } from "@/components/common/component-preview-server";

// Auto fetches the "default" example from the "button" category
// in the exampleRegistry
<ComponentPreviewServer 
  component="button" 
  name="default" 
/>

How Registry Fetching Works

The ComponentPreviewServer component integrates tightly with the @/registry/index file (specifically exampleRegistry). When you pass component="button" and name="default":

1. It queries exampleRegistry["button"] to get an array of button examples.
2. It .find()s the specific example where e.name === "default".
3. If found, it passes the example's lazy-loaded/imported functional component <example.component /> and its literal string example.code down to ComponentPreview.
4. If it fails, it gracefully handles the error by returning an inline message: Example default not found in registry for component button.

Reference Files

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

• component-preview.tsx
• component-preview-server.tsx
• component-wrapper.tsx