@jorgemadrid/open-carousel 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +148 -0
- package/dist/index.cjs +2529 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +618 -0
- package/dist/index.d.ts +618 -0
- package/dist/index.js +2471 -0
- package/dist/index.js.map +1 -0
- package/dist/styles.css +102 -0
- package/package.json +71 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 jorgemadridportillo
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
# open-carousel
|
|
2
|
+
|
|
3
|
+
A high-performance, infinite-scroll React carousel with smooth animations, teleportation, and zero dependencies (except React).
|
|
4
|
+
|
|
5
|
+
## Features
|
|
6
|
+
|
|
7
|
+
- 🔄 **Infinite Scroll** - Seamless teleportation-based infinite scrolling
|
|
8
|
+
- 🎯 **CSS Snap Points** - Native scroll snapping for perfect alignment
|
|
9
|
+
- 🖱️ **Drag to Scroll** - Mouse and touch drag support with momentum
|
|
10
|
+
- ⌨️ **Arrow Navigation** - Accessible keyboard and button navigation
|
|
11
|
+
- 📏 **Responsive** - CSS variable-based responsive widths
|
|
12
|
+
- 🎨 **Visual Effects** - Scale, opacity, and shadow effects based on position
|
|
13
|
+
- 💾 **Persistence** - Optional scroll position persistence across navigation
|
|
14
|
+
- 🐛 **Debug Tools** - Built-in logging system for development
|
|
15
|
+
|
|
16
|
+
## Installation
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
npm install open-carousel
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## Quick Start
|
|
23
|
+
|
|
24
|
+
```tsx
|
|
25
|
+
import { Carousel } from 'open-carousel'
|
|
26
|
+
import 'open-carousel/styles.css'
|
|
27
|
+
|
|
28
|
+
const items = [
|
|
29
|
+
{ id: '1', title: 'First Item' },
|
|
30
|
+
{ id: '2', title: 'Second Item' },
|
|
31
|
+
{ id: '3', title: 'Third Item' },
|
|
32
|
+
]
|
|
33
|
+
|
|
34
|
+
function MyCarousel() {
|
|
35
|
+
return (
|
|
36
|
+
<Carousel
|
|
37
|
+
items={items}
|
|
38
|
+
getItemKey={(item) => item.id}
|
|
39
|
+
renderItem={(item) => (
|
|
40
|
+
<div className="card">
|
|
41
|
+
<h3>{item.title}</h3>
|
|
42
|
+
</div>
|
|
43
|
+
)}
|
|
44
|
+
infinite
|
|
45
|
+
/>
|
|
46
|
+
)
|
|
47
|
+
}
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## Props
|
|
51
|
+
|
|
52
|
+
| Prop | Type | Default | Description |
|
|
53
|
+
|------|------|---------|-------------|
|
|
54
|
+
| `items` | `T[]` | required | Array of items to display |
|
|
55
|
+
| `getItemKey` | `(item: T, index: number) => string` | required | Unique key extractor |
|
|
56
|
+
| `renderItem` | `(item: T, index: number, helpers) => ReactNode` | required | Item renderer |
|
|
57
|
+
| `infinite` | `boolean` | `false` | Enable infinite scrolling |
|
|
58
|
+
| `itemWidthCssVar` | `string` | - | **Recommended**: Custom CSS variable for width |
|
|
59
|
+
| `itemWidthVar` | `'default' \| 'review' \| ...` | `'default'` | Legacy: Predefined width variant |
|
|
60
|
+
| `initialIndex` | `number` | `0` | Start at specific index |
|
|
61
|
+
| `gap` | `number` | auto | Gap between items in pixels |
|
|
62
|
+
| `snap` | `boolean` | `true` | Enable CSS scroll snapping |
|
|
63
|
+
| `snapType` | `'mandatory' \| 'proximity'` | `'mandatory'` | Snap behavior type |
|
|
64
|
+
| `disableOpacityEffect` | `boolean` | `false` | Disable opacity fade on edges |
|
|
65
|
+
| `disableScaleEffect` | `boolean` | `false` | Disable scale effect on edges |
|
|
66
|
+
| `verticalPadding` | `string` | `'20px'` | Vertical padding for container |
|
|
67
|
+
| `persistKey` | `string` | - | Key for scroll position persistence |
|
|
68
|
+
| `onActiveItemChange` | `(item: T) => void` | - | Callback when active item changes |
|
|
69
|
+
| `onEndReached` | `() => void` | - | Callback when scrolling to end |
|
|
70
|
+
| `hasNextPage` | `boolean` | `false` | Whether more items can be loaded |
|
|
71
|
+
| `prevLabel` | `string` | `'Previous'` | Aria label for previous button |
|
|
72
|
+
| `nextLabel` | `string` | `'Next'` | Aria label for next button |
|
|
73
|
+
|
|
74
|
+
## 📏 Responsive Item Widths (Recommended)
|
|
75
|
+
|
|
76
|
+
The most flexible way to control item widths is using your own CSS variable and `itemWidthCssVar`.
|
|
77
|
+
|
|
78
|
+
**1. Define Variable in CSS**
|
|
79
|
+
```css
|
|
80
|
+
/* styles.css */
|
|
81
|
+
:root {
|
|
82
|
+
--my-card-width: 220px;
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
@media (min-width: 768px) {
|
|
86
|
+
:root {
|
|
87
|
+
--my-card-width: 300px;
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
**2. Pass to Component**
|
|
93
|
+
```tsx
|
|
94
|
+
<Carousel
|
|
95
|
+
itemWidthCssVar="--my-card-width"
|
|
96
|
+
items={items}
|
|
97
|
+
// ...
|
|
98
|
+
/>
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
## Advanced Usage
|
|
102
|
+
|
|
103
|
+
### Custom Hooks
|
|
104
|
+
|
|
105
|
+
The package exports all internal hooks for advanced customization:
|
|
106
|
+
|
|
107
|
+
```tsx
|
|
108
|
+
import {
|
|
109
|
+
useCarouselCoordinator,
|
|
110
|
+
useCarouselLayout,
|
|
111
|
+
useCarouselNavigation,
|
|
112
|
+
useCarouselTeleport,
|
|
113
|
+
useCarouselVisuals,
|
|
114
|
+
useCarouselPersistence,
|
|
115
|
+
useDraggableScroll,
|
|
116
|
+
} from 'open-carousel'
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
### Debugging
|
|
120
|
+
|
|
121
|
+
Enable debug logging for development:
|
|
122
|
+
|
|
123
|
+
```tsx
|
|
124
|
+
<Carousel
|
|
125
|
+
items={items}
|
|
126
|
+
debugId="my-carousel"
|
|
127
|
+
debug={{ channels: { NAV: true, TELEPORT: true } }}
|
|
128
|
+
// ...
|
|
129
|
+
/>
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
Or dump logs from the console:
|
|
133
|
+
|
|
134
|
+
```js
|
|
135
|
+
window.__DUMP_CAROUSEL_LOGS() // All logs
|
|
136
|
+
window.__DUMP_CAROUSEL_LOGS('my-carousel') // Specific carousel
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
## Browser Support
|
|
140
|
+
|
|
141
|
+
- Chrome 89+
|
|
142
|
+
- Firefox 90+
|
|
143
|
+
- Safari 15.4+
|
|
144
|
+
- Edge 89+
|
|
145
|
+
|
|
146
|
+
## License
|
|
147
|
+
|
|
148
|
+
MIT © 2025
|