npm package: @sarthakb009/sources
Description: Sources
Author: Sarthak
Latest version: 1.0.2

# Sources

A React component for displaying a list of sources (papers, web articles, documents) with icons, metadata, and click handlers. Perfect for citation lists, reference sections, or source attribution. Built with TypeScript and GSAP animations.

## Installation

```bash
npm install @sarthakb009/sources
```

## Peer Dependencies

Make sure you have these installed in your project:

```bash
npm install react react-dom lucide-react gsap @gsap/react
```

Required versions:
- `react` ^18.0.0
- `react-dom` ^18.0.0
- `lucide-react` ^0.294.0
- `gsap` ^3.12.0
- `@gsap/react` ^2.1.0

## Usage

### Basic Example

```tsx
import { Sources } from '@sarthakb009/sources';

function App() {
  const sources = [
    {
      id: 1,
      title: 'Understanding Neural Networks',
      url: 'https://example.com/neural-networks',
      domain: 'example.com',
      type: 'paper',
    },
    {
      id: 2,
      title: 'React Best Practices',
      url: 'https://react.dev/best-practices',
      domain: 'react.dev',
      type: 'web',
    },
    {
      id: 3,
      title: 'TypeScript Handbook',
      url: 'https://typescriptlang.org/handbook',
      domain: 'typescriptlang.org',
      type: 'article',
    },
  ];

  return (
    <Sources
      sources={sources}
      title="References"
    />
  );
}
```

### With Click Handler

```tsx
import { Sources } from '@sarthakb009/sources';

function App() {
  return (
    <Sources
      sources={sources}
      title="Sources"
      onSourceClick={(source) => {
        console.log('Source clicked:', source);
        // Open in new tab
        window.open(source.url, '_blank');
      }}
    />
  );
}
```

### Different Source Types

```tsx
import { Sources } from '@sarthakb009/sources';

function App() {
  const sources = [
    {
      id: 1,
      title: 'Research Paper',
      url: 'https://example.com/paper.pdf',
      domain: 'example.com',
      type: 'paper', // Shows BookOpen icon
    },
    {
      id: 2,
      title: 'Web Article',
      url: 'https://example.com/article',
      domain: 'example.com',
      type: 'web', // Shows Globe icon
    },
    {
      id: 3,
      title: 'Documentation',
      url: 'https://example.com/docs',
      domain: 'example.com',
      type: 'article', // Shows FileText icon
    },
  ];

  return <Sources sources={sources} />;
}
```

### Custom Styling

```tsx
import { Sources } from '@sarthakb009/sources';

function App() {
  return (
    <Sources
      sources={sources}
      title="References"
      className="my-sources"
    />
  );
}
```

## Props

| Prop | Type | Default | Required | Description |
|------|------|---------|----------|-------------|
| `sources` | `Source[]` | `undefined` | No | Array of sources to display |
| `title` | `string` | `undefined` | No | Header title text |
| `onSourceClick` | `(source: Source) => void` | `undefined` | No | Callback fired when a source is clicked |
| `className` | `string` | `undefined` | No | Additional CSS classes for container |

## Source Type

```tsx
interface Source {
  id: number | string;
  title: string;
  url: string;
  domain: string;
  type: 'paper' | 'web' | 'article';
}
```

## Source Types

- **`paper`**: Shows BookOpen icon (academic papers, research documents)
- **`web`**: Shows Globe icon (web pages, websites)
- **`article`**: Shows FileText icon (articles, blog posts, documentation)

## Features

- ✅ **Source Display**: Clean list with icons and metadata
- ✅ **Type Icons**: Different icons for paper, web, and article types
- ✅ **Click Handlers**: Support for source click events
- ✅ **Domain Display**: Shows source domain
- ✅ **External Link**: Visual indicator for external links
- ✅ **Item Count**: Shows count of sources in header
- ✅ **Hover Effects**: Interactive hover states
- ✅ **Smooth Animations**: GSAP-powered entrance animations
- ✅ **TypeScript**: Full TypeScript support with exported types
- ✅ **Accessible**: Proper ARIA labels and semantic HTML

## TypeScript

The component is written in TypeScript and exports all types:

```tsx
import { Sources, SourcesProps, Source } from '@sarthakb009/sources';

const source: Source = {
  id: 1,
  title: 'Example Source',
  url: 'https://example.com',
  domain: 'example.com',
  type: 'web',
};

const props: SourcesProps = {
  sources: [source],
  title: 'References',
};
```

## License

MIT