@capitol.ai/ui/README.md

Library of React components from Capitol AI

# Capitol AI - React components

## Local setup

First, install the package:

```
npm install @capitol.ai/ui
```

Then, import components you need and default styles (optional):
```
import { Summary } from '@capitol.ai/ui';
import '@capitol.ai/ui/dist/capitolai-ui.css';
```

## Components

### Summary

The main component that displays AI-generated summaries in different layouts.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| summaryId | string | "" | Unique identifier for the summary |
| prompt | string | "prompt" | The prompt text that generated the summary |
| title | string | "AI summary" | Title of the summary |
| className | string | "" | Additional CSS classes |
| summary | string | "" | The summary content |
| layout | "quoted" \| "clean" | "quoted" | Layout type for the summary. "quoted" shows prompt in quotes with decorative elements, "clean" provides a minimal design |
| format | "basic" \| "advanced" | "basic" | Format type for the summary |
| output | SummaryOutput | undefined | Additional output data for advanced format |
| useMarkdown | boolean | false | Whether to render the summary content as markdown. When true, the content will be rendered using ReactMarkdown with proper styling |

### Prompt

A component for user input with customizable styling.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| placeholderText | string | "Enter prompt" | Placeholder text for the input |
| minHeight | number | undefined | Minimum height of the input area |
| accentColor | string | undefined | Accent color for the submit button |
| onSubmit | (prompt: string) => void | () => {} | Callback when prompt is submitted |
| onChange | (text: string) => void | () => {} | Callback when prompt text changes |
| disabled | boolean | false | Whether the input is disabled |

### PromptSuggestions

Displays a list of prompt suggestions that users can click on.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| prompts | string[] | [] | Array of prompt suggestions |
| onClickHandler | (prompt: string) => void | () => {} | Callback when a suggestion is clicked |
| title | string | "Suggestions" | Title of the suggestions section |

### PromptWithOptions

Combines the Prompt component with suggestion options.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| placeholder | string | "Ask a question" | Placeholder text for the input |
| prompts | string[] | [] | Array of prompt suggestions |
| onSubmit | (prompt: string) => void | undefined | Callback when prompt is submitted |
| onChange | (text: string) => void | undefined | Callback when prompt text changes |

### Sources

Displays a list of sources with optional layout and pagination customization.

| Prop                | Type                                              | Default     | Description                                                                                 |
|---------------------|---------------------------------------------------|-------------|---------------------------------------------------------------------------------------------|
| sources             | Source[]                                          | []          | Array of source objects                                                                     |
| itemsPerPage        | number                                            | 4           | Number of items to display per page                                                         |
| layout              | 'default' \| 'masonry' \| 'compact'              | 'default'   | Layout style for sources: 'default', 'masonry', or 'compact'                                |
| paginationConfig    | Partial<PaginationProps>                          | undefined   | Pagination configuration object (see PaginationProps below for options)                     |

#### Example Usage

```jsx
import { Sources } from '@capitol.ai/ui';

const sources = [
  {
    url: 'https://example.com',
    title: 'Example Source',
    image: 'https://example.com/image.jpg',
  },
  // ...more sources
];

<Sources
  sources={sources}
  itemsPerPage={6}
  layout="masonry"
  paginationConfig={{
    maxVisiblePages: 7,
    selectedPageColor: 'bg-green-500',
    hoverPageColor: 'bg-yellow-100',
    useArrows: true,
    rounded: 'full',
  }}
/>
```

### Pagination

A reusable pagination component for navigating through pages of content. Mainly used as pagination for Sources, but can be used anywhere you need page navigation.

| Prop               | Type                       | Default         | Description                                                                 |
|--------------------|----------------------------|-----------------|-----------------------------------------------------------------------------|
| currentPage        | number                     | **required**    | Current page number (1-based)                                               |
| totalPages         | number                     | **required**    | Total number of pages                                                       |
| onPageChange       | (page: number) => void     | **required**    | Callback when page changes                                                  |
| maxVisiblePages    | number                     | 5               | Maximum number of visible page buttons                                      |
| selectedPageColor  | string                     | 'bg-blue-500'   | Tailwind class for the selected page button background                      |
| hoverPageColor     | string                     | 'bg-gray-100'   | Tailwind class for the hover state of page buttons                          |
| useArrows          | boolean                    | false           | Show arrow icons for prev/next buttons instead of text                      |
| rounded            | 'full' \| 'half' \| 'quarter' | undefined        | Rounded shape of the page buttons. When set, gap between elements is 8px    |

#### Example Usage

```jsx
import { Pagination } from '@capitol.ai/ui';

function MyPaginatedComponent() {
  const [currentPage, setCurrentPage] = useState(1);
  const totalPages = 10;

  return (
    <Pagination
      currentPage={currentPage}
      totalPages={totalPages}
      onPageChange={setCurrentPage}
      maxVisiblePages={7}
      selectedPageColor="bg-green-500"
      hoverPageColor="bg-yellow-100"
      useArrows
      rounded="full"
    />
  );
}
```

> **Note:** When the `rounded` prop is set, the gap between pagination elements (page numbers) is 8px for a visually pleasing layout.

### Navigation

Displays a navigation menu with active state tracking.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| title | string | "Navigation" | Title of the navigation section |
| navList | NavItem[] | [] | Array of navigation items |
| activeItem | string | "" | Currently active navigation item |

### GenerationLog

Displays a list of generation steps with loading animations.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| title | string | "Generating..." | Title of the generation log |
| logs | string[] | [] | Array of log messages |

## Types

### SummaryOutput

| Property | Type | Description |
|----------|------|-------------|
| header | string | Header text for the summary |
| body | string | Main body content of the summary |
| image | string | Optional image URL for the summary |

### Source

| Property | Type | Description |
|----------|------|-------------|
| url | string | URL of the source |
| title | string | Title of the source |
| image | string | Image URL for the source |

### NavItem

| Property | Type | Description |
|----------|------|-------------|
| ref | string | Reference ID for the navigation item |
| name | string | Display name of the navigation item |

## Example Usage

```jsx
import { Summary, PromptWithOptions, Sources, Navigation, GenerationLog } from '@capitol.ai/ui';
import '@capitol.ai/ui/dist/capitolai-ui.css';

const MyApp = () => {
  return (
    <div>
      <PromptWithOptions
        placeholder="Ask a question"
        prompts={["What is AI?", "How does it work?"]}
        onSubmit={(prompt) => console.log(prompt)}
      />
      <GenerationLog
        title="Generating Summary"
        logs={["Analyzing sources", "Generating content"]}
      />
      <Summary
        title="AI Summary"
        prompt="What is artificial intelligence?"
        summary="Artificial intelligence is..."
        layout="metric-media"
      />
      <Sources
        sources={[
          {
            url: "https://example.com",
            title: "Example Source",
            image: "https://example.com/image.jpg"
          }
        ]}
      />
      <Navigation
        title="Table of Contents"
        navList={[
          { ref: "section1", name: "Introduction" },
          { ref: "section2", name: "Main Content" }
        ]}
        activeItem="section1"
      />
    </div>
  );
}
```

## Building new package

It's always a good idea to test before publish (e.g. using App.jsx).

Once you absolutely happy with what you've done:

```
npm run build
npm version patch
npm publish
```