lazer-slider 1.0.2 → 1.0.4

package/README.md

@@ -0,0 +1,457 @@
+# Lazer Slider
+
+A lightweight, accessible slider with smooth scroll-to-snap animations, drag-to-scroll support, and full keyboard navigation.
+
+## Features
+
+- **Smooth Animations** - Buttery smooth scroll animations using `requestAnimationFrame` with customizable easing
+- **Drag to Scroll** - Mouse and touch drag support with momentum physics
+- **Responsive** - Separate settings for mobile and desktop (slidesPerView, slidesPerScroll)
+- **Loop Mode** - Infinite loop navigation
+- **Autoplay** - Automatic slide advancement with pause on hover
+- **Accessible** - Full ARIA support, keyboard navigation (arrow keys)
+- **Lightweight** - Zero dependencies, ~20KB unminified
+- **TypeScript** - Full type definitions included
+
+## Installation
+
+```bash
+npm install lazer-slider
+```
+
+## Quick Start
+
+### HTML Structure
+
+```html
+<div class="slider">
+  <button class="slider-prev">Previous</button>
+  <button class="slider-next">Next</button>
+
+  <div class="slider-feed">
+    <div class="slide">Slide 1</div>
+    <div class="slide">Slide 2</div>
+    <div class="slide">Slide 3</div>
+  </div>
+
+  <div class="slider-dots">
+    <button class="dot"></button>
+    <button class="dot"></button>
+    <button class="dot"></button>
+  </div>
+</div>
+```
+
+### CSS (Required)
+
+```css
+.slider-feed {
+  display: flex;
+  overflow-x: auto;
+  scroll-snap-type: x mandatory;
+  -webkit-overflow-scrolling: touch;
+  scrollbar-width: none; /* Firefox */
+}
+
+.slider-feed::-webkit-scrollbar {
+  display: none; /* Chrome, Safari */
+}
+
+.slide {
+  scroll-snap-align: start;
+  flex-shrink: 0;
+}
+```
+
+### JavaScript
+
+```typescript
+import { createSlider } from 'lazer-slider'
+
+const slider = createSlider({
+  feed: document.querySelector('.slider-feed'),
+  slides: [...document.querySelectorAll('.slide')],
+  prevSlideButton: document.querySelector('.slider-prev'),
+  nextSlideButton: document.querySelector('.slider-next'),
+  thumbs: [...document.querySelectorAll('.dot')],
+  enableDragToScroll: true
+})
+
+// Cleanup when done
+slider.unload()
+```
+
+## Configuration Options
+
+### Required
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `feed` | `HTMLElement` | Container element that holds the slides (scrollable) |
+| `slides` | `HTMLElement[]` | Array of slide elements |
+
+### Navigation
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `prevSlideButton` | `HTMLElement \| null` | `null` | Previous slide button |
+| `nextSlideButton` | `HTMLElement \| null` | `null` | Next slide button |
+| `thumbs` | `HTMLElement[]` | `undefined` | Thumbnail/dot elements for direct navigation |
+
+### Responsive
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `mobileSlidesPerView` | `number \| 'auto'` | `undefined` | Slides visible at once on mobile |
+| `desktopSlidesPerView` | `number \| 'auto'` | `undefined` | Slides visible at once on desktop |
+| `mobileSlidesPerScroll` | `number` | `1` | Slides to scroll per nav click on mobile |
+| `desktopSlidesPerScroll` | `number` | `1` | Slides to scroll per nav click on desktop |
+| `slideGap` | `number` | `0` | Gap between slides in pixels |
+
+> **Note:** Desktop breakpoint is `min-width: 64rem` (1024px)
+
+> **Tip:** Use `'auto'` for `slidesPerView` when slides have different/natural widths defined in CSS.
+
+### Behavior
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enableDragToScroll` | `boolean` | `false` | Enable mouse/touch drag to scroll |
+| `loop` | `boolean` | `false` | Enable infinite loop navigation |
+| `autoplay` | `boolean` | `false` | Enable automatic slide advancement |
+| `autoplayInterval` | `number` | `3000` | Autoplay interval in milliseconds |
+| `pauseOnHover` | `boolean` | `true` | Pause autoplay on hover/touch |
+| `easing` | `EasingFunction` | `easeOutExpo` | Custom easing function |
+
+### Scrollbar (Optional)
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `scrollbarThumb` | `HTMLElement \| null` | `null` | Custom scrollbar thumb element |
+| `scrollbarTrack` | `HTMLElement \| null` | `null` | Custom scrollbar track element |
+
+### Callbacks
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `onScrollStart` | `(params) => void` | Fired when scroll animation starts |
+| `onScroll` | `(params) => void` | Fired during scroll |
+| `onScrollEnd` | `(params) => void` | Fired when scroll animation ends |
+
+#### Callback Parameters
+
+```typescript
+// onScrollStart
+{
+  currentScroll: number    // Current scroll position in pixels
+  target: HTMLElement      // Target slide element
+  direction: 'prev' | 'next'
+}
+
+// onScroll, onScrollEnd
+{
+  currentScroll: number      // Current scroll position in pixels
+  currentSlideIndex: number  // Index of the current slide
+}
+```
+
+## API Methods
+
+```typescript
+const slider = createSlider({ /* options */ })
+
+// Navigate to specific slide (0-indexed)
+slider.goToIndex(2)
+
+// Navigate prev/next (respects loop setting)
+slider.next()
+slider.prev()
+
+// Autoplay control
+slider.play()   // Start autoplay
+slider.pause()  // Stop autoplay
+
+// Recalculate dimensions (call after DOM changes)
+slider.refresh()
+
+// Cleanup all event listeners
+slider.unload()
+```
+
+## Easing Functions
+
+Built-in easing functions for smooth animations:
+
+```typescript
+import {
+  createSlider,
+  easeOutExpo,    // Default - smooth deceleration
+  easeOutCubic,   // Gentler deceleration
+  easeInOutCubic, // Smooth acceleration & deceleration
+  easeOutQuad,    // Gentle deceleration
+  linear          // Constant speed
+} from 'lazer-slider'
+
+const slider = createSlider({
+  // ... options
+  easing: easeOutCubic
+})
+```
+
+### Custom Easing
+
+```typescript
+// Custom easing function (t goes from 0 to 1)
+const customEase = (t: number) => t * t * t
+
+const slider = createSlider({
+  // ... options
+  easing: customEase
+})
+```
+
+## Examples
+
+### Basic Slider
+
+```typescript
+const slider = createSlider({
+  feed: document.querySelector('.slider-feed'),
+  slides: [...document.querySelectorAll('.slide')]
+})
+```
+
+### With Navigation Buttons
+
+```typescript
+const slider = createSlider({
+  feed: document.querySelector('.slider-feed'),
+  slides: [...document.querySelectorAll('.slide')],
+  prevSlideButton: document.querySelector('.prev'),
+  nextSlideButton: document.querySelector('.next')
+})
+```
+
+### Responsive Multi-Slide
+
+```typescript
+const slider = createSlider({
+  feed: document.querySelector('.slider-feed'),
+  slides: [...document.querySelectorAll('.slide')],
+  mobileSlidesPerView: 1,
+  desktopSlidesPerView: 3,
+  slideGap: 16,
+  mobileSlidesPerScroll: 1,
+  desktopSlidesPerScroll: 3
+})
+```
+
+### Autoplay Carousel
+
+```typescript
+const slider = createSlider({
+  feed: document.querySelector('.slider-feed'),
+  slides: [...document.querySelectorAll('.slide')],
+  loop: true,
+  autoplay: true,
+  autoplayInterval: 5000,
+  pauseOnHover: true
+})
+```
+
+### Bullets/Dots Navigation
+
+Use the `thumbs` option to add clickable dots that navigate to specific slides. The slider automatically manages the `active` class.
+
+```html
+<div class="slider">
+  <div class="slider-feed">
+    <div class="slide">Slide 1</div>
+    <div class="slide">Slide 2</div>
+    <div class="slide">Slide 3</div>
+  </div>
+
+  <div class="slider-dots">
+    <button class="dot" aria-label="Go to slide 1"></button>
+    <button class="dot" aria-label="Go to slide 2"></button>
+    <button class="dot" aria-label="Go to slide 3"></button>
+  </div>
+</div>
+```
+
+```css
+.slider-dots {
+  display: flex;
+  gap: 8px;
+  justify-content: center;
+  margin-top: 16px;
+}
+
+.dot {
+  width: 12px;
+  height: 12px;
+  border-radius: 50%;
+  border: none;
+  background: #ccc;
+  cursor: pointer;
+  transition: background 0.3s;
+}
+
+.dot.active {
+  background: #333;
+}
+```
+
+```typescript
+const slider = createSlider({
+  feed: document.querySelector('.slider-feed'),
+  slides: [...document.querySelectorAll('.slide')],
+  thumbs: [...document.querySelectorAll('.dot')]
+})
+```
+
+### Custom Scrollbar
+
+Create a draggable scrollbar that syncs with the slider position.
+
+```html
+<div class="slider">
+  <div class="slider-feed">
+    <div class="slide">Slide 1</div>
+    <div class="slide">Slide 2</div>
+    <div class="slide">Slide 3</div>
+  </div>
+
+  <div class="scrollbar-track">
+    <div class="scrollbar-thumb"></div>
+  </div>
+</div>
+```
+
+```css
+.scrollbar-track {
+  width: 100%;
+  height: 4px;
+  background: #eee;
+  border-radius: 2px;
+  margin-top: 16px;
+  position: relative;
+}
+
+.scrollbar-thumb {
+  height: 100%;
+  background: #333;
+  border-radius: 2px;
+  /* Width is set automatically by the slider */
+}
+```
+
+```typescript
+const slider = createSlider({
+  feed: document.querySelector('.slider-feed'),
+  slides: [...document.querySelectorAll('.slide')],
+  scrollbarThumb: document.querySelector('.scrollbar-thumb'),
+  scrollbarTrack: document.querySelector('.scrollbar-track')
+})
+```
+
+The slider automatically:
+- Sets the thumb width based on visible content ratio
+- Updates thumb position on scroll
+- Hides the scrollbar when all content is visible
+
+### Auto Width Slides
+
+Use `slidesPerView: 'auto'` when slides have different natural widths defined in CSS.
+
+```html
+<div class="slider-feed">
+  <div class="slide slide--small">Small</div>
+  <div class="slide slide--medium">Medium</div>
+  <div class="slide slide--large">Large content here</div>
+</div>
+```
+
+```css
+.slide--small { width: 150px; }
+.slide--medium { width: 250px; }
+.slide--large { width: 400px; }
+```
+
+```typescript
+const slider = createSlider({
+  feed: document.querySelector('.slider-feed'),
+  slides: [...document.querySelectorAll('.slide')],
+  mobileSlidesPerView: 'auto',
+  desktopSlidesPerView: 'auto',
+  slideGap: 16,
+  enableDragToScroll: true
+})
+```
+
+### Full Featured
+
+```typescript
+const slider = createSlider({
+  feed: document.querySelector('.slider-feed'),
+  slides: [...document.querySelectorAll('.slide')],
+  prevSlideButton: document.querySelector('.prev'),
+  nextSlideButton: document.querySelector('.next'),
+  thumbs: [...document.querySelectorAll('.dot')],
+
+  // Responsive
+  mobileSlidesPerView: 1,
+  desktopSlidesPerView: 3,
+  slideGap: 20,
+
+  // Behavior
+  enableDragToScroll: true,
+  loop: true,
+  autoplay: true,
+  autoplayInterval: 4000,
+
+  // Callbacks
+  onScrollEnd: ({ currentSlideIndex }) => {
+    console.log('Now viewing slide:', currentSlideIndex)
+  }
+})
+```
+
+## Accessibility
+
+The slider automatically adds ARIA attributes for accessibility:
+
+- `role="region"` and `aria-roledescription="carousel"` on the feed
+- `role="group"` and `aria-label="Slide X of Y"` on each slide
+- `aria-controls` linking buttons to the feed
+- `aria-hidden` and `tabindex` management for visibility
+- Keyboard navigation with arrow keys when feed is focused
+
+## TypeScript
+
+Full TypeScript support with exported types:
+
+```typescript
+import {
+  createSlider,
+  type SliderSettings,
+  type Slider,
+  type EasingFunction,
+  type ScrollParams,
+  type ScrollStartParams,
+  type SliderDirection
+} from 'lazer-slider'
+```
+
+## Browser Support
+
+- Chrome (latest)
+- Firefox (latest)
+- Safari (latest)
+- Edge (latest)
+
+Requires `scroll-snap-type` CSS support for snap behavior.
+
+## License
+
+UNLICENSED