@multimodal/component-gallery v0.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
• Quick Start
• Framework Structure
• Core Components
• Creating Component Pages
• Customization
• Utilities
• Best Practices

Installation

# 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:

// 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:

// 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.

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

Props

ComponentPage

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

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

Props

Creating Component Pages

1. Define Props

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

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

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:

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:

: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:

<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:

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:

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.