npm package: @sergiovalerdev/react-ui
Description: React Components UI Library
Author: Sergio Valer
Latest version: 1.0.0

# @sergiovalerdev/react-ui

A React component library with **36 ready-to-use UI components**, built with TypeScript and SCSS. Supports dark and light themes out of the box. Fully tree-shakeable.

## Requirements

- React 17, 18, or 19
- React DOM 17, 18, or 19

## Installation

```bash
npm install @sergiovalerdev/react-ui
```

## Usage

Styles are injected automatically — no stylesheet import needed.

### Full import

```tsx
import { Button, StatCard, Toast } from '@sergiovalerdev/react-ui'

export default function App() {
  return (
    <div>
      <Button theme="dark">Click me</Button>
      <StatCard value="42" label="Projects completed" theme="dark" />
    </div>
  )
}
```

### Per-component import (recommended — tree-shaking)

Import only what you need — each component has its own entry point so bundlers load zero code from unused components:

```tsx
import { Button } from '@sergiovalerdev/react-ui/Button'
import { Toast } from '@sergiovalerdev/react-ui/Toast'
```

## Theming

All components accept a `theme` prop (`"dark"` | `"light"`):

```tsx
<Button theme="dark">Dark</Button>
<Button theme="light">Light</Button>
```

Accent colors can be customized globally via CSS custom properties without recompiling:

```css
:root {
  --color-accent:     #ff6b00;
  --color-accent-end: #ff0080;
}
```

## Components

### Layout & Navigation

| Component | Description |
|-----------|-------------|
| `NavBar` | Top navigation bar with links and optional branding |
| `Footer` | Page footer |
| `Divider` | Horizontal rule with optional label |
| `Modal` | Accessible dialog overlay |
| `TabGroup` | Tabbed panel with keyboard navigation |
| `Breadcrumb` | Hierarchical path navigation |

### Data Display

| Component | Description |
|-----------|-------------|
| `StatCard` | Displays a numeric value with a label |
| `CounterStat` | Animated counter that triggers when scrolled into view |
| `ContentCard` | Generic card with title, body, and optional image |
| `CardGrid` | Responsive grid wrapper for `ContentCard` items |
| `Table` | Styled HTML table |
| `Timeline` | Vertical timeline of events |
| `ExperienceCard` | Card for a single work/education experience |
| `ExperienceList` | List wrapper for `ExperienceCard` items |
| `TestimonialCard` | Quote card with author and avatar |
| `SectionHeader` | Section title with optional subtitle |

### Media & Code

| Component | Description |
|-----------|-------------|
| `AudioPlayer` | Full-featured audio player with spectrum visualizer and 3-band EQ (LOW/MID/HIGH); supports plain audio files, YouTube, and Twitch URLs. Both features can be toggled via `showVisualizer` and `showEq` props. |
| `AudioDetail` | Supplementary metadata panel for audio content |
| `Avatar` | Circular image with optional fallback initials |
| `LogoSlider` | Auto-scrolling ticker of logos with drag-to-scroll |
| `Carousel` | Touch- and pointer-friendly slide carousel |
| `CodeBlock` | Syntax-highlighted code snippet (powered by highlight.js) |

### Forms & Inputs

| Component | Description |
|-----------|-------------|
| `Button` | Styled button with size and variant props |
| `Select` | Custom styled dropdown |
| `ContactForm` | Pre-built contact form with validation |
| `ProgressBar` | Horizontal progress indicator |
| `RatingBar` | Read-only star or bar rating display |

### Feedback & Overlays

| Component | Description |
|-----------|-------------|
| `Alert` | Inline status message (info, success, warning, error) |
| `AlertBanner` | Full-width dismissible banner alert |
| `Toast` | Temporary notification that auto-dismisses |
| `Tooltip` | Hover-triggered text tooltip |

### Labels & Taxonomy

| Component | Description |
|-----------|-------------|
| `Badge` | Small count or status indicator |
| `Chip` | Removable or selectable tag element |
| `TagBadge` | Decorative tag for categorization |
| `CategoryList` | Horizontal list of category tags |

### Disclosure

| Component | Description |
|-----------|-------------|
| `Accordion` | Expandable/collapsible content panel |

## Examples

### Button

```tsx
import { Button } from '@sergiovalerdev/react-ui/Button'

<Button theme="dark">Primary</Button>
<Button theme="light">Secondary</Button>
```

### Toast

```tsx
import { Toast, useToast } from '@sergiovalerdev/react-ui/Toast'

function App() {
  const { toasts, showToast } = useToast()
  return (
    <>
      <button onClick={() => showToast('Saved!', 'success')}>Save</button>
      <Toast toasts={toasts} theme="dark" />
    </>
  )
}
```

### Modal

```tsx
import { Modal } from '@sergiovalerdev/react-ui/Modal'
import { useState } from 'react'

function App() {
  const [open, setOpen] = useState(false)
  return (
    <>
      <button onClick={() => setOpen(true)}>Open</button>
      <Modal isOpen={open} onClose={() => setOpen(false)} title="My Modal" theme="dark">
        Modal content here.
      </Modal>
    </>
  )
}
```

### CounterStat

```tsx
import { CounterStat } from '@sergiovalerdev/react-ui/CounterStat'

<CounterStat value={2500} label="Users" suffix="+" theme="dark" />
<CounterStat value={100} label="Completion rate" suffix="%" theme="dark" />
```

### LogoSlider

```tsx
import { LogoSlider } from '@sergiovalerdev/react-ui/LogoSlider'

const logos = [
  { name: 'React',      image: '/icons/react.svg' },
  { name: 'TypeScript', image: '/icons/ts.svg' },
  { name: 'Node.js',    image: '/icons/node.svg' },
]

<LogoSlider items={logos} theme="dark" />
```

### AudioPlayer

```tsx
import { AudioPlayer } from '@sergiovalerdev/react-ui/AudioPlayer'

// Full player — spectrum visualizer + 3-band EQ (defaults)
<AudioPlayer
  audioUrl="https://example.com/track.mp3"
  title="My Track"
  artist="Artist"
  cover="/cover.jpg"
  theme="dark"
/>

// Visualizer only (hide EQ)
<AudioPlayer audioUrl="..." title="My Track" artist="Artist" theme="dark" showEq={false} />

// EQ only (hide visualizer)
<AudioPlayer audioUrl="..." title="My Track" artist="Artist" theme="dark" showVisualizer={false} />

// Minimal — neither visualizer nor EQ
<AudioPlayer audioUrl="..." title="My Track" artist="Artist" theme="dark" showEq={false} showVisualizer={false} />

// YouTube (renders YouTube embed)
<AudioPlayer audioUrl="https://www.youtube.com/watch?v=..." title="Track" artist="Artist" theme="dark" />
```

## Custom Styling

All components use BEM class naming (e.g. `button`, `button--dark`, `button__icon`). Override styles by targeting these classes in your own CSS:

```css
.button--dark {
  background-color: #1a1a2e;
}
```

## TypeScript

Full TypeScript declarations are included. All props are typed and exported:

```ts
import type { ButtonProps, StatCardProps } from '@sergiovalerdev/react-ui'
```

## License

MIT © [Sergio Valer](https://github.com/sergiovalerDEV)