npm package: @multimodal/component-gallery
Description: A sleek, minimalist framework for showcasing and documenting React components with an elegant black, white, and gray design aesthetic.
Latest version: 0.0.3

# Component Gallery Framework Documentation

A sleek, minimalist framework for showcasing and documenting React components with an elegant black, white, and gray design aesthetic.

## Table of Contents

- [Installation](#installation)
- [Quick Start](#quick-start)
- [Framework Structure](#framework-structure)
- [Core Components](#core-components)
- [Creating Component Pages](#creating-component-pages)
- [Customization](#customization)
- [Utilities](#utilities)
- [Best Practices](#best-practices)

## Installation

```bash
# Using npm
npm install @multimodal/component-gallery

# Using yarn
yarn add @multimodal/component-gallery

# Using pnpm
pnpm add @multimodal/component-gallery
```

## Quick Start

1. Create your component pages:

```tsx
// pages/ButtonPage.tsx
import React from 'react';
import { ComponentPage } from '@multimodal/component-gallery';
import { Button } from '@your-library/components';

export const ButtonPage = () => {
  const propDefinitions = [
    {
      name: 'variant',
      type: '"primary" | "secondary" | "ghost"',
      defaultValue: '"primary"',
      description: 'The button style variant',
    },
    {
      name: 'size',
      type: '"sm" | "md" | "lg"',
      defaultValue: '"md"',
      description: 'Button size',
    },
    // More props...
  ];

  const examples = [
    {
      title: 'Basic Button',
      description: 'A simple button example',
      code: `<Button>Click me</Button>`,
      showResult: true,
    },
    // More examples...
  ];

  return (
    <ComponentPage
      meta={{
        name: 'Button',
        description:
          'Interactive button component with multiple variants and sizes',
      }}
      props={propDefinitions}
      examples={examples}
      scenarios={[
        'Form submission buttons',
        'Call-to-action elements',
        'Modal dialog controls',
      ]}
    />
  );
};
```

2. Set up your gallery:

```tsx
// App.tsx
import React from 'react';
import { ComponentGallery } from '@multimodal/component-gallery';
import { ButtonPage } from './pages/ButtonPage';
import { InputPage } from './pages/InputPage';
// Import other component pages

const App = () => {
  const components = [
    {
      category: 'Basic',
      items: [
        { id: 'button', name: 'Button', component: ButtonPage },
        { id: 'input', name: 'Input', component: InputPage },
      ],
    },
    {
      category: 'Layout',
      items: [
        // Layout components...
      ],
    },
  ];

  return (
    <ComponentGallery title="Your Component Library" components={components} />
  );
};

export default App;
```

## Framework Structure

The framework is built with a clear separation of concerns:

```
component-gallery/
├── framework/
│   ├── ComponentGallery.tsx     # Main container
│   ├── ComponentPage.tsx        # Component details page
│   ├── CodeBlock.tsx            # Code display with syntax highlighting
│   ├── Tabs.tsx                 # Tabbed interface
│   ├── PropsTable.tsx           # Properties documentation table
│   └── types.ts                 # Type definitions
├── pages/                       # Example component pages
├── utils/                       # Helper utilities
└── index.ts                     # Public exports
```

## Core Components

### `ComponentGallery`

The main container that provides navigation and layout for your component documentation.

```tsx
<ComponentGallery
  title="Your Component Library"
  components={componentsList}
  logo={YourLogoComponent} // Optional
  defaultComponent="button" // Optional
  onComponentChange={(componentId) => console.log(componentId)} // Optional
/>
```

#### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | string | - | Gallery title |
| `components` | ComponentCategory[] | [] | Component categories and items |
| `logo` | React.ReactNode | null | Custom logo element |
| `defaultComponent` | string | First component ID | Initially selected component |
| `onComponentChange` | (id: string) => void | - | Callback when component changes |

### `ComponentPage`

Displays a component's documentation, examples, and usage information.

```tsx
<ComponentPage
  meta={{
    name: 'Component Name',
    description: 'Component description...',
  }}
  props={propDefinitions}
  examples={examplesList}
  scenarios={usageScenarios}
  ExamplesComponent={CustomExamplesComponent} // Optional
/>
```

#### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `meta` | { name: string; description: string } | - | Component metadata |
| `props` | PropDefinition[] | [] | Component properties documentation |
| `examples` | Example[] | [] | Code examples |
| `scenarios` | string[] | [] | Usage scenarios |
| `ExamplesComponent` | React.ComponentType | null | Custom examples component |

## Creating Component Pages

### 1. Define Props

```tsx
const propDefinitions = [
  {
    name: 'propName', // Property name
    type: 'string', // Property type
    defaultValue: '""', // Default value (optional)
    description: 'Description text', // Description
    required: false, // Is this prop required?
  },
  // More props...
];
```

### 2. Create Examples

```tsx
const examples = [
  {
    title: 'Example Title',
    description: 'Brief description of what this example demonstrates',
    code: `import { YourComponent } from '@your-library/components';

const ExampleUsage = () => (
  <YourComponent prop="value">
    Content
  </YourComponent>
);`,
    showResult: true, // Whether to show the rendered result
  },
  // More examples...
];
```

### 3. Define Usage Scenarios

```tsx
const scenarios = [
  'Scenario 1: Where this component is useful',
  'Scenario 2: Another use case for this component',
  'Scenario 3: Yet another application',
];
```

### 4. Custom Examples Component

For more control over how examples are displayed:

```tsx
const CustomExamplesComponent = () => {
  return (
    <div className="space-y-10">
      {/* Custom example implementations */}
      <div className="bg-white border rounded-lg overflow-hidden">
        <div className="p-4 border-b">
          <h3 className="font-medium text-lg">Example Title</h3>
          <p className="text-sm text-[#666] mt-1">Example description</p>
        </div>

        <div className="p-6 border-b">
          {/* Rendered component example */}
          <YourComponent />
        </div>

        <div className="p-4 bg-[#FAFAFA]">
          <pre className="font-mono text-sm overflow-x-auto">
            <code className="language-tsx">{`<YourComponent />`}</code>
          </pre>
        </div>
      </div>

      {/* More examples */}
    </div>
  );
};
```

## Customization

### Custom Theme

You can customize the appearance of the gallery by providing CSS variables:

```css
:root {
  --gallery-primary: #000000;
  --gallery-background: #ffffff;
  --gallery-sidebar-bg: #f5f5f5;
  --gallery-border: #eaeaea;
  --gallery-text: #333333;
  --gallery-text-secondary: #666666;
  --gallery-accent: #0070f3;
  --gallery-code-bg: #fafafa;
}
```

### Custom Layout

Use the available render props to customize layout structure:

```tsx
<ComponentGallery
  // ...other props
  renderHeader={(title, logo) => (
    <header className="custom-header">
      {logo}
      <h1>{title}</h1>
      <YourCustomSearchComponent />
    </header>
  )}
  renderSidebar={(categories) => (
    <nav className="custom-sidebar">
      {/* Your custom sidebar implementation */}
      {categories.map(category => (
        // Custom rendering...
      ))}
    </nav>
  )}
/>
```

## Utilities

The framework provides several utility functions to help with component documentation:

### `extractPropTypesFromComponent`

Automatically extracts prop types from TypeScript components:

```tsx
import { extractPropTypesFromComponent } from '@multimodal/component-gallery/utils';

// Use with a component
const propDefinitions = extractPropTypesFromComponent(YourComponent);

// Now use with ComponentPage
<ComponentPage props={propDefinitions} /* ...other props */ />;
```

### `generateExampleCode`

Helps generate code examples from component usage:

```tsx
import { generateExampleCode } from '@multimodal/component-gallery/utils';

const exampleCode = generateExampleCode(
  <Button variant="primary" size="lg">
    Click Me
  </Button>,
);

// Result: "<Button variant="primary" size="lg">Click Me</Button>"
```

## Best Practices

1. **Consistent Structure**: Keep your component documentation structure consistent across all components.

2. **Complete Props Documentation**: Document all props, including types, defaults, and descriptions.

3. **Progressive Examples**: Start with basic examples and progress to more complex ones.

4. **Real-World Scenarios**: Include practical usage scenarios that show when and how to use the component.

5. **Visual Differentiation**: Use clear visual cues to distinguish between different states and variants.

6. **Responsive Design**: Ensure your examples look good on all screen sizes.

7. **Code Formatting**: Keep your code examples well-formatted and consistent.

8. **Performance**: For interactive examples, be mindful of performance, especially with complex components.