lazer-slider 1.1.2 → 1.1.3

package/README.md

@@ -7,10 +7,12 @@ A lightweight, accessible slider with smooth scroll-to-snap animations, drag-to-
 - **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)
+- **Vertical & Horizontal** - Support for both horizontal and vertical slider directions
 - **Loop Mode** - Infinite loop navigation
 - **Autoplay** - Automatic slide advancement with pause on hover
 - **Marquee Mode** - Continuous smooth scrolling with seamless infinite loop
 - **Automatic Bullets** - Auto-generate navigation bullets from slides
+- **Thumbs Gallery** - Auto-generate thumbnail navigation from slide images
 - **Accessible** - Full ARIA support, keyboard navigation (arrow keys)
 - **Lightweight** - Zero dependencies, ~20KB unminified
 - **TypeScript** - Full type definitions included
@@ -26,58 +28,61 @@ npm install lazer-slider
 ### 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 class="lazer-slider">
+  <button class="lazer-prev">Previous</button>
+  <button class="lazer-next">Next</button>
+
+  <div class="lazer-feed">
+    <div class="lazer-slide">Slide 1</div>
+    <div class="lazer-slide">Slide 2</div>
+    <div class="lazer-slide">Slide 3</div>
   </div>
 
-  <div class="slider-bullets"></div>
+  <div class="lazer-bullets"></div>
 </div>
 ```
 
-### CSS (Required)
+### CSS
 
-```css
-.slider-feed {
-  display: flex;
-  overflow-x: auto;
-  -webkit-overflow-scrolling: touch;
-  scrollbar-width: none; /* Firefox */
-}
+**Zero-Config (Recommended):** Critical CSS is auto-injected when you call `createSlider()`. The slider automatically adds `.lazer-feed` and `.lazer-slide` classes to your elements!
 
-.slider-feed::-webkit-scrollbar {
-  display: none; /* Chrome, Safari */
-}
+```html
+<div class="lazer-slider">
+  <button class="lazer-prev">Previous</button>
+  <button class="lazer-next">Next</button>
+
+  <div class="lazer-feed">
+    <div class="lazer-slide">Slide 1</div>
+    <div class="lazer-slide">Slide 2</div>
+    <div class="lazer-slide">Slide 3</div>
+  </div>
 
-.slide {
-  scroll-snap-align: start;
-  flex-shrink: 0;
-}
+  <div class="lazer-bullets"></div>
+</div>
+```
 
-.slider-bullets {
-  display: flex;
-  gap: 8px;
-  justify-content: center;
-  margin-top: 16px;
-}
+**Optional Styles:** For bullets, thumbs, scrollbar, and navigation styling, import the optional CSS file:
 
-.slider-bullet {
-  width: 12px;
-  height: 12px;
-  border-radius: 50%;
-  border: none;
-  background: #ccc;
-  cursor: pointer;
-  transition: background 0.3s;
+```typescript
+// Import optional styles for bullets, thumbs, scrollbar, etc.
+import 'lazer-slider/css'
+```
+
+Or in HTML:
+```html
+<link rel="stylesheet" href="node_modules/lazer-slider/dist/lazer-slider.css">
+```
+
+**Custom CSS:** You can override the auto-injected styles easily:
+
+```css
+/* Override the auto-injected styles */
+.lazer-feed {
+  gap: 20px;
 }
 
-.slider-bullet.active {
-  background: #333;
+.lazer-slide {
+  scroll-snap-align: center; /* Change snap alignment */
 }
 ```
 
@@ -87,11 +92,11 @@ npm install lazer-slider
 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'),
-  bulletsContainer: document.querySelector('.slider-bullets'),
+  feed: document.querySelector('.lazer-feed'),
+  slides: [...document.querySelectorAll('.lazer-slide')],
+  prevSlideButton: document.querySelector('.lazer-prev'),
+  nextSlideButton: document.querySelector('.lazer-next'),
+  bulletsContainer: document.querySelector('.lazer-bullets'),
   enableDragToScroll: true
 })
 
@@ -116,10 +121,15 @@ slider.unload()
 | `nextSlideButton` | `HTMLElement \| null` | `null` | Next slide button |
 | `thumbs` | `HTMLElement[]` | `undefined` | Thumbnail/dot elements for direct navigation (manual) |
 | `bulletsContainer` | `HTMLElement \| null` | `null` | Container element for auto-generated bullets |
-| `bulletsClass` | `string` | `'slider-bullet'` | CSS class for bullet elements |
+| `bulletsClass` | `string` | `'lazer-bullet'` | CSS class for bullet elements |
 | `bulletsActiveClass` | `string` | `'active'` | CSS class for active bullet element |
+| `thumbsContainer` | `HTMLElement \| null` | `null` | Container element for auto-generated thumbnails |
+| `thumbsClass` | `string` | `'lazer-thumb'` | CSS class for thumbnail elements |
+| `thumbsActiveClass` | `string` | `'active'` | CSS class for active thumbnail element |
+| `thumbImageSelector` | `string` | `'img'` | CSS selector to find image inside each slide |
+| `thumbSize` | `{ width: number; height: number }` | `undefined` | Fixed dimensions for thumbnail images |
 
-> **Note:** When `bulletsContainer` is provided, bullets are automatically generated. If `thumbs` is also provided, `bulletsContainer` is ignored. Bullets are only generated for visible slides.
+> **Note:** When `bulletsContainer` or `thumbsContainer` is provided, navigation elements are automatically generated. If `thumbs` is also provided, both containers are ignored. Elements are only generated for visible slides.
 
 ### Responsive
 
@@ -139,6 +149,7 @@ slider.unload()
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
+| `direction` | `'horizontal' \| 'vertical'` | `'horizontal'` | Slider orientation |
 | `enableDragToScroll` | `boolean` | `false` | Enable mouse/touch drag to scroll |
 | `loop` | `boolean` | `false` | Enable infinite loop navigation |
 | `autoplay` | `boolean` | `false` | Enable automatic slide advancement |
@@ -244,7 +255,7 @@ const slider = createSlider({
 
 ```typescript
 const slider = createSlider({
-  feed: document.querySelector('.slider-feed'),
+  feed: document.querySelector('.lazer-feed'),
   slides: [...document.querySelectorAll('.slide')]
 })
 ```
@@ -253,10 +264,10 @@ const slider = createSlider({
 
 ```typescript
 const slider = createSlider({
-  feed: document.querySelector('.slider-feed'),
+  feed: document.querySelector('.lazer-feed'),
   slides: [...document.querySelectorAll('.slide')],
   prevSlideButton: document.querySelector('.prev'),
-  nextSlideButton: document.querySelector('.next')
+  nextSlideButton: document.querySelector('.lazer-next')
 })
 ```
 
@@ -264,7 +275,7 @@ const slider = createSlider({
 
 ```typescript
 const slider = createSlider({
-  feed: document.querySelector('.slider-feed'),
+  feed: document.querySelector('.lazer-feed'),
   slides: [...document.querySelectorAll('.slide')],
   mobileSlidesPerView: 1,
   desktopSlidesPerView: 3,
@@ -278,7 +289,7 @@ const slider = createSlider({
 
 ```typescript
 const slider = createSlider({
-  feed: document.querySelector('.slider-feed'),
+  feed: document.querySelector('.lazer-feed'),
   slides: [...document.querySelectorAll('.slide')],
   loop: true,
   autoplay: true,
@@ -317,6 +328,68 @@ marquee.play()   // Resume marquee
 - **Marquee**: For continuous ticker-style scrolling (news tickers, logo carousels, announcements)
 - **Autoplay**: For slide-by-slide carousel navigation (image galleries, product showcases)
 
+### Vertical Slider
+
+Create a vertical scrolling slider for content that flows top-to-bottom.
+
+```html
+<div class="vertical-slider">
+  <button class="lazer-prev">↑</button>
+  <button class="lazer-next">↓</button>
+
+  <div class="slider-feed">
+    <div class="lazer-slide">Slide 1</div>
+    <div class="lazer-slide">Slide 2</div>
+    <div class="lazer-slide">Slide 3</div>
+  </div>
+</div>
+```
+
+```css
+.lazer-feed {
+  display: flex;
+  flex-direction: column;
+  overflow-y: auto;
+  height: 400px; /* Set a fixed height for vertical scrolling */
+  scrollbar-width: none;
+}
+
+.lazer-feed::-webkit-scrollbar {
+  display: none;
+}
+
+.slide {
+  scroll-snap-align: start;
+  flex-shrink: 0;
+}
+```
+
+```typescript
+const verticalSlider = createSlider({
+  feed: document.querySelector('.lazer-feed'),
+  slides: [...document.querySelectorAll('.slide')],
+  prevSlideButton: document.querySelector('.lazer-prev'),
+  nextSlideButton: document.querySelector('.lazer-next'),
+  direction: 'vertical',
+  mobileSlidesPerView: 1,
+  desktopSlidesPerView: 1,
+  enableDragToScroll: true
+})
+```
+
+**Key Features:**
+- Full vertical scrolling support with smooth animations
+- Keyboard navigation with ArrowUp/ArrowDown keys
+- Drag-to-scroll works in vertical direction
+- Loop mode and autoplay work vertically
+- Custom scrollbar can be styled vertically
+
+**When to use Vertical Slider:**
+- Full-page vertical carousels
+- Testimonial/review sliders with tall content
+- Timeline or step-by-step displays
+- Mobile-first vertical content experiences
+
 ### Bullets/Dots Navigation
 
 You can add clickable dots that navigate to specific slides using either manual or automatic generation.
@@ -328,9 +401,9 @@ The slider can automatically generate bullets from your slides. Just provide a c
 ```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 class="lazer-slide">Slide 1</div>
+    <div class="lazer-slide">Slide 2</div>
+    <div class="lazer-slide">Slide 3</div>
   </div>
 
   <div class="slider-bullets"></div>
@@ -338,14 +411,14 @@ The slider can automatically generate bullets from your slides. Just provide a c
 ```
 
 ```css
-.slider-bullets {
+.lazer-bullets {
   display: flex;
   gap: 8px;
   justify-content: center;
   margin-top: 16px;
 }
 
-.slider-bullet {
+.lazer-bullet {
   width: 12px;
   height: 12px;
   border-radius: 50%;
@@ -355,16 +428,16 @@ The slider can automatically generate bullets from your slides. Just provide a c
   transition: background 0.3s;
 }
 
-.slider-bullet.active {
+.lazer-bullet.active {
   background: #333;
 }
 ```
 
 ```typescript
 const slider = createSlider({
-  feed: document.querySelector('.slider-feed'),
+  feed: document.querySelector('.lazer-feed'),
   slides: [...document.querySelectorAll('.slide')],
-  bulletsContainer: document.querySelector('.slider-bullets'),
+  bulletsContainer: document.querySelector('.lazer-bullets'),
   bulletsClass: 'slider-bullet',      // Optional: default is 'slider-bullet'
   bulletsActiveClass: 'active'        // Optional: default is 'active'
 })
@@ -383,9 +456,9 @@ Alternatively, you can create bullets manually and pass them via the `thumbs` op
 ```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 class="lazer-slide">Slide 1</div>
+    <div class="lazer-slide">Slide 2</div>
+    <div class="lazer-slide">Slide 3</div>
   </div>
 
   <div class="slider-dots">
@@ -421,7 +494,7 @@ Alternatively, you can create bullets manually and pass them via the `thumbs` op
 
 ```typescript
 const slider = createSlider({
-  feed: document.querySelector('.slider-feed'),
+  feed: document.querySelector('.lazer-feed'),
   slides: [...document.querySelectorAll('.slide')],
   thumbs: [...document.querySelectorAll('.dot')]
 })
@@ -429,6 +502,88 @@ const slider = createSlider({
 
 > **Note:** If both `bulletsContainer` and `thumbs` are provided, `bulletsContainer` is ignored and manual `thumbs` are used instead.
 
+### Thumbs Gallery
+
+Auto-generate clickable thumbnail images from your slides. Perfect for product galleries, image carousels, and any slider where visual previews enhance navigation.
+
+```html
+<div class="slider">
+  <div class="slider-feed">
+    <div class="lazer-slide">
+      <img src="/images/product-1.jpg" alt="Product 1">
+      <h3>Product Title 1</h3>
+    </div>
+    <div class="lazer-slide">
+      <img src="/images/product-2.jpg" alt="Product 2">
+      <h3>Product Title 2</h3>
+    </div>
+    <div class="lazer-slide">
+      <img src="/images/product-3.jpg" alt="Product 3">
+      <h3>Product Title 3</h3>
+    </div>
+  </div>
+
+  <!-- Empty container - thumbnails are auto-generated -->
+  <div class="thumbs-gallery"></div>
+</div>
+```
+
+```css
+.thumbs-gallery {
+  display: flex;
+  gap: 8px;
+  margin-top: 16px;
+  justify-content: center;
+}
+
+.lazer-thumb {
+  padding: 0;
+  border: 2px solid transparent;
+  background: none;
+  cursor: pointer;
+  opacity: 0.6;
+  transition: opacity 0.2s, border-color 0.2s;
+}
+
+.lazer-thumb:hover {
+  opacity: 0.8;
+}
+
+.lazer-thumb.active {
+  opacity: 1;
+  border-color: #007bff;
+}
+
+.lazer-thumb img {
+  display: block;
+  border-radius: 4px;
+}
+```
+
+```typescript
+const slider = createSlider({
+  feed: document.querySelector('.lazer-feed'),
+  slides: [...document.querySelectorAll('.slide')],
+  thumbsContainer: document.querySelector('.thumbs-gallery'),
+  thumbsClass: 'slider-thumb',           // Optional: default is 'slider-thumb'
+  thumbsActiveClass: 'active',           // Optional: default is 'active'
+  thumbImageSelector: 'img',             // Optional: CSS selector for slide images
+  thumbSize: { width: 80, height: 60 }   // Optional: fixed thumbnail dimensions
+})
+```
+
+**Features:**
+- Automatically extracts images from each slide using `thumbImageSelector`
+- Creates clickable thumbnail buttons with proper accessibility attributes
+- Full ARIA support (`role="tablist"`, `aria-selected`, etc.)
+- Active state automatically managed on scroll and click
+- Only generates thumbnails for visible slides
+- Optional fixed dimensions with `thumbSize` for consistent layouts
+
+**When to use Thumbs Gallery vs Bullets:**
+- **Thumbs Gallery**: For image-heavy sliders where visual previews help navigation (product galleries, portfolios)
+- **Bullets**: For simpler navigation where slide content preview isn't needed (text carousels, testimonials)
+
 ### Custom Scrollbar
 
 Create a draggable scrollbar that syncs with the slider position.
@@ -436,9 +591,9 @@ 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 class="lazer-slide">Slide 1</div>
+    <div class="lazer-slide">Slide 2</div>
+    <div class="lazer-slide">Slide 3</div>
   </div>
 
   <div class="scrollbar-track">
@@ -467,7 +622,7 @@ Create a draggable scrollbar that syncs with the slider position.
 
 ```typescript
 const slider = createSlider({
-  feed: document.querySelector('.slider-feed'),
+  feed: document.querySelector('.lazer-feed'),
   slides: [...document.querySelectorAll('.slide')],
   scrollbarThumb: document.querySelector('.scrollbar-thumb'),
   scrollbarTrack: document.querySelector('.scrollbar-track')
@@ -499,7 +654,7 @@ Use `slidesPerView: 'auto'` when slides have different natural widths defined in
 
 ```typescript
 const slider = createSlider({
-  feed: document.querySelector('.slider-feed'),
+  feed: document.querySelector('.lazer-feed'),
   slides: [...document.querySelectorAll('.slide')],
   mobileSlidesPerView: 'auto',
   desktopSlidesPerView: 'auto',
@@ -512,11 +667,16 @@ const slider = createSlider({
 
 ```typescript
 const slider = createSlider({
-  feed: document.querySelector('.slider-feed'),
+  feed: document.querySelector('.lazer-feed'),
   slides: [...document.querySelectorAll('.slide')],
   prevSlideButton: document.querySelector('.prev'),
-  nextSlideButton: document.querySelector('.next'),
-  bulletsContainer: document.querySelector('.slider-bullets'), // Auto-generated bullets
+  nextSlideButton: document.querySelector('.lazer-next'),
+
+  // Navigation (choose one: bullets OR thumbs)
+  bulletsContainer: document.querySelector('.lazer-bullets'), // Auto-generated bullets
+  // OR for image galleries:
+  // thumbsContainer: document.querySelector('.thumbs-gallery'),
+  // thumbSize: { width: 80, height: 60 },
 
   // Responsive
   mobileSlidesPerView: 1,
@@ -536,6 +696,93 @@ const slider = createSlider({
 })
 ```
 
+## CSS Customization
+
+When using the optional CSS file (`import 'lazer-slider/css'`), you can customize styles using CSS custom properties:
+
+```css
+:root {
+  /* Bullets / Dots */
+  --lazer-bullet-size: 12px;
+  --lazer-bullet-gap: 8px;
+  --lazer-bullet-color: #cbd5e1;
+  --lazer-bullet-active-color: #1e293b;
+  --lazer-bullet-hover-scale: 1.2;
+
+  /* Thumbnails */
+  --lazer-thumb-gap: 8px;
+  --lazer-thumb-opacity: 0.6;
+  --lazer-thumb-hover-opacity: 0.8;
+  --lazer-thumb-active-opacity: 1;
+  --lazer-thumb-border-width: 2px;
+  --lazer-thumb-border-color: transparent;
+  --lazer-thumb-active-border-color: #3b82f6;
+  --lazer-thumb-border-radius: 4px;
+
+  /* Scrollbar */
+  --lazer-track-height: 4px;
+  --lazer-track-color: #e2e8f0;
+  --lazer-thumb-color: #1e293b;
+  --lazer-track-radius: 2px;
+
+  /* Navigation Buttons */
+  --lazer-nav-size: 40px;
+  --lazer-nav-offset: 12px;
+  --lazer-nav-bg: rgba(255, 255, 255, 0.9);
+  --lazer-nav-hover-bg: white;
+  --lazer-nav-radius: 50%;
+  --lazer-nav-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+
+  /* Transitions */
+  --lazer-duration: 0.3s;
+  --lazer-easing: ease;
+}
+```
+
+### CSS Classes
+
+The slider automatically adds these classes for CSS targeting:
+
+| Class | Applied To | Description |
+|-------|------------|-------------|
+| `.lazer-feed` | Feed element | Scrollable container |
+| `.lazer-slide` | Slide elements | Individual slides |
+| `.lazer-vertical` | Feed element | When using vertical direction |
+| `.lazer-marquee` | Feed element | When marquee mode is enabled |
+
+You can use these classes in your CSS:
+
+```css
+.lazer-feed {
+  /* Style the feed container */
+}
+
+.lazer-slide {
+  /* Style individual slides */
+}
+
+.lazer-feed.lazer-vertical {
+  /* Style vertical sliders */
+}
+```
+
+### Available Classes
+
+| Class | Element | Description |
+|-------|---------|-------------|
+| `.lazer-slider` | Container | Optional wrapper |
+| `.lazer-feed` | Feed | Scrollable container |
+| `.lazer-slide` | Slide | Individual slides |
+| `.lazer-bullets` | Bullets container | Dot navigation wrapper |
+| `.lazer-bullet` | Bullet | Individual dot |
+| `.lazer-thumbs` | Thumbs container | Thumbnail navigation wrapper |
+| `.lazer-thumb` | Thumb | Individual thumbnail |
+| `.lazer-track` | Scrollbar track | Scrollbar background |
+| `.lazer-scrollbar` | Scrollbar thumb | Draggable scrollbar |
+| `.lazer-nav` | Nav button | Navigation button base |
+| `.lazer-prev` | Prev button | Previous button |
+| `.lazer-next` | Next button | Next button |
+
 ## Accessibility
 
 The slider automatically adds ARIA attributes for accessibility:
@@ -554,6 +801,9 @@ Full TypeScript support with exported types:
 import {
   createSlider,
   generateBullets,
+  generateThumbs,
+  injectStyles,
+  removeStyles,
   type SliderSettings,
   type Slider,
   type EasingFunction,
@@ -564,7 +814,9 @@ import {
 } from 'lazer-slider'
 ```
 
-> **Note:** `generateBullets` is also exported if you need to manually generate bullets outside of the slider initialization.
+> **Note:** `generateBullets` and `generateThumbs` are also exported if you need to manually generate navigation elements outside of the slider initialization.
+
+> **Note:** `injectStyles()` is called automatically by `createSlider()`. Use it manually only if you need to inject styles before creating a slider (e.g., for SSR hydration). `removeStyles()` removes the injected styles from the document.
 
 ## Browser Support