npm package: @pierregoeddertz/ii-ii-ii
Description: A lightweight, accessible horizontal drag-to-scroll component for React and vanilla JavaScript
Author: II-II-II
Latest version: 1.0.6

# Xer - Simple Horizontal Scroll Component

A lightweight, accessible horizontal drag-to-scroll component for React and vanilla JavaScript.

## Features

- 🎯 **Simple Integration**: Just wrap your items and it works
- ♿ **Accessible**: Built-in accessibility features
- 📱 **Touch Friendly**: Optimized for touch devices
- ⚡ **Lightweight**: Minimal bundle size
- 🎭 **Smooth Animations**: Inertia scrolling and smooth interactions
- 🎨 **Customizable**: Flexible styling options
- 🔄 **Auto-Structure**: Automatically creates proper ul/li structure
- 🌐 **SSR Compatible**: Works with Next.js, Gatsby, and other SSR frameworks
- 🚀 **Universal Import**: One import works for both React and Vanilla

## Installation

```bash
npm install @pierregoeddertz/ii-ii-ii
```

## Usage

### Universal Import (Recommended)

```jsx
// Works in both React and Vanilla environments!
import Xer from '@pierregoeddertz/ii-ii-ii';
import '@pierregoeddertz/ii-ii-ii/css';

// React
function MyComponent() {
  return (
    <Xer>
      <div>Item 1</div>
      <div>Item 2</div>
      <div>Item 3</div>
    </Xer>
  );
}

// Vanilla
const container = document.getElementById('my-scroll-container');
const xer = new Xer(container, { center: true });
```

### Next.js (App Router)

```tsx
// app/page.tsx
import Xer from '@pierregoeddertz/ii-ii-ii';
import '@pierregoeddertz/ii-ii-ii/css';

export default function Page() {
  return (
    <div>
      <h1>My App</h1>
      <Xer>
        <div>Item 1</div>
        <div>Item 2</div>
        <div>Item 3</div>
      </Xer>
    </div>
  );
}
```

### Explicit Version Selection

```jsx
// React-specific import
import Xer from '@pierregoeddertz/ii-ii-ii/react';

// Vanilla-specific import
import Xer from '@pierregoeddertz/ii-ii-ii/vanilla';

// CSS
import '@pierregoeddertz/ii-ii-ii/css';
```

### Vanilla JavaScript Version

```html
<ul id="my-scroll-container">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
  <!-- Add more items -->
</ul>

<script type="module">
  import Xer from '@pierregoeddertz/ii-ii-ii';
  import '@pierregoeddertz/ii-ii-ii/css';
  
  const container = document.getElementById('my-scroll-container');
  const xer = new Xer(container, {
    center: true,
    direction: 'ltr',
    gap: '1rem',
    padding: '1rem'
  });
</script>
```

## SSR Compatibility

Xer is **fully SSR compatible** and works with:

- ✅ **Next.js** (App Router & Pages Router)
- ✅ **Gatsby**
- ✅ **Remix**
- ✅ **Nuxt.js**
- ✅ **Vite SSR**
- ✅ **Any React SSR framework**

The component automatically:
- Renders the correct HTML structure during SSR
- Hydrates interactivity on the client
- Handles browser APIs safely
- Maintains accessibility during SSR

## How It Works

The component automatically:
- Creates the proper `ul`/`li` structure
- Handles drag-to-scroll interactions
- Provides smooth inertia scrolling
- Works on both desktop and mobile
- Hides scrollbars for a clean look
- Includes full accessibility support
- Renders safely during SSR
- Auto-detects React vs Vanilla environment

## API

### React Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `React.ReactNode` | - | Content to render |
| `className` | `string` | `''` | Additional CSS classes |
| `ariaLabel` | `string` | `'Horizontal list frame'` | ARIA label |
| `ariaDescription` | `string` | - | ARIA description |
| `role` | `string` | `'region'` | ARIA role |
| `center` | `boolean` | `true` | Center content |
| `direction` | `'ltr' \| 'rtl'` | `'ltr'` | Text direction |
| `gap` | `string` | `'1rem'` | Gap between items |
| `padding` | `string` | `'1rem'` | Container padding |

### Vanilla JavaScript Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `center` | `boolean` | `true` | Center content |
| `direction` | `'ltr' \| 'rtl'` | `'ltr'` | Text direction |
| `gap` | `string` | `'1rem'` | Gap between items |
| `padding` | `string` | `'1rem'` | Container padding |
| `inertiaDecay` | `number` | `0.92` | Inertia scroll decay |
| `dragThreshold` | `number` | `10` | Drag threshold in pixels |

## Examples

### Basic Usage

```jsx
// Universal import - works everywhere!
import Xer from '@pierregoeddertz/ii-ii-ii';

// React
<Xer>
  <div>Card 1</div>
  <div>Card 2</div>
  <div>Card 3</div>
</Xer>

// Vanilla
const container = document.querySelector('.scroll-container');
new Xer(container);
```

### Custom Styling

```jsx
// React
<Xer className="custom-scroll" gap="2rem" padding="2rem">
  <div>Item 1</div>
  <div>Item 2</div>
</Xer>

// Vanilla
new Xer(container, {
  gap: '2rem',
  padding: '2rem'
});
```

### RTL Support

```jsx
// React
<Xer direction="rtl">
  <div>Item 1</div>
  <div>Item 2</div>
</Xer>

// Vanilla
new Xer(container, { direction: 'rtl' });
```

## Browser Support

- Chrome 60+
- Firefox 55+
- Safari 12+
- Edge 79+

## License

MIT © II-II-II