awesome-rolodex-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.txt ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) [2026-27] [Pravinkumar Dabade]
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,425 @@
1
+ # Awesome Rolodex Carousel
2
+
3
+ A beautifully animated rolodex carousel component for React with a mechanical drum illusion effect. Features smooth drag interaction, keyboard navigation, auto-scroll, and customizable cards with accent colors.
4
+
5
+
6
+ ## Features
7
+
8
+ - 🎯 **Mechanical Drum Illusion** — Authentic 3D cylinder rotation effect using pure 2D CSS
9
+ - 🎨 **Customizable Cards** — Full control over colors, metrics, content, and callbacks
10
+ - 🖱️ **Smooth Interactions** — Drag, scroll, keyboard arrows, and click navigation
11
+ - ⚡ **Auto-Scroll** — Automatic card advancement with pause on hover
12
+ - 📱 **Responsive** — Full-screen responsive design with touch support
13
+ - 🔄 **Multiple Data Modes** — Load from static data, local JSON, or REST API
14
+ - 🎭 **Rich Styling** — Brass frame, textured cards, glowing accents, and elegant typography
15
+
16
+
17
+ ## Watch the demo here
18
+
19
+ [![Watch the Demo](https://res.cloudinary.com/de8mdnuxm/image/upload/v1773423660/rolodex-carousel_s1hja9.png)](https://youtu.be/gPex69Gz1MU)
20
+
21
+ ## Installation
22
+
23
+ ```bash
24
+ npm install awesome-rolodex-carousel
25
+ ```
26
+
27
+ Or with yarn:
28
+
29
+ ```bash
30
+ yarn add awesome-rolodex-carousel
31
+ ```
32
+
33
+ ## Quick Start
34
+
35
+ ### Basic Usage
36
+
37
+ ```jsx
38
+ import React from 'react'
39
+ import { AwesomeRolodexCarousel } from 'awesome-rolodex-carousel'
40
+ import 'awesome-rolodex-carousel/styles'
41
+
42
+ const cards = [
43
+ {
44
+ id: 1,
45
+ title: 'Neural Core',
46
+ subtitle: 'AI Infrastructure',
47
+ tag: 'AI',
48
+ accent: '#00e5ff',
49
+ bgFrom: '#020d1f',
50
+ bgTo: '#041a30',
51
+ metric: '99.7',
52
+ metricLabel: 'Uptime %',
53
+ body: 'At the heart of every intelligent system lies a lattice of weights and connections.',
54
+ onClick: (card) => console.log('Clicked:', card.title)
55
+ },
56
+ {
57
+ id: 2,
58
+ title: 'Void Protocol',
59
+ subtitle: 'Zero-Trust Security',
60
+ tag: 'SEC',
61
+ accent: '#ff2d6f',
62
+ bgFrom: '#1a040a',
63
+ bgTo: '#2e0812',
64
+ metric: '0',
65
+ metricLabel: 'Breaches',
66
+ body: 'In an architecture of zero trust, every packet is a stranger.'
67
+ },
68
+ // ... more cards
69
+ ]
70
+
71
+ export default function App() {
72
+ return (
73
+ <AwesomeRolodexCarousel
74
+ data={cards}
75
+ onCardChange={(index, card) => console.log(`Active: [${index + 1}] ${card.title}`)}
76
+ onCardClick={(card) => console.log('Card clicked:', card.title)}
77
+ />
78
+ )
79
+ }
80
+ ```
81
+
82
+ ### With Styling
83
+
84
+ To use the built-in styles, import them in your main file:
85
+
86
+ ```jsx
87
+ import 'awesome-rolodex-carousel/styles'
88
+ ```
89
+
90
+ Custom CSS variables can override defaults:
91
+
92
+ ```css
93
+ :root {
94
+ --font-display: 'Georgia', serif;
95
+ --font-mono: 'Courier New', monospace;
96
+ --font-ui: 'Arial', sans-serif;
97
+ --bg: #1a1208;
98
+ --brass: #b8860b;
99
+ --cream: #f5efe0;
100
+ }
101
+ ```
102
+
103
+ ## Props Table
104
+
105
+ | Prop | Type | Default | Description |
106
+ |------|------|---------|-------------|
107
+ | `data` | `RolodexCard[]` | `undefined` | Array of card objects to display. Use one of: `data`, `apiEndpoint` |
108
+ | `apiEndpoint` | `string` | `undefined` | URL to fetch cards from (local JSON or REST API). Response format: `RolodexCard[]` or `{ data: RolodexCard[] }` |
109
+ | `apiHeaders` | `Record<string, string>` | `undefined` | Custom HTTP headers for API requests (e.g., auth tokens) |
110
+ | `apiTransform` | `(raw: unknown) => RolodexCard[]` | `undefined` | Function to transform API response into card array |
111
+ | `cardWidth` | `number` | `560` | Width of each card in pixels |
112
+ | `cardHeight` | `number` | `200` | Height of each card in pixels |
113
+ | `slotGap` | `number` | `54` | Vertical spacing between card slots in pixels |
114
+ | `visibleRadius` | `number` | `3` | Number of cards visible above/below active card |
115
+ | `autoInterval` | `number` | `3200` | Auto-advance interval in milliseconds. Pauses on hover. Set to 0 to disable |
116
+ | `snapDuration` | `number` | `420` | Snap animation duration in milliseconds when navigating |
117
+ | `onCardClick` | `(card: RolodexCard) => void` | `undefined` | Callback when clicking the active card (fallback if card has no `onClick`) |
118
+ | `onCardChange` | `(index: number, card: RolodexCard) => void` | `undefined` | Callback fired when active card changes |
119
+
120
+ ## RolodexCard Type
121
+
122
+ ```typescript
123
+ interface RolodexCard {
124
+ id: number
125
+ /** Primary label — shown large in active state */
126
+ title: string
127
+ /** Secondary descriptor */
128
+ subtitle?: string
129
+ /** Category tab label */
130
+ tag?: string
131
+ /** Main body text shown when card is active */
132
+ body?: string
133
+ /** Accent colour — drives tab colour and glow */
134
+ accent: string
135
+ /** Card background — warm tones recommended */
136
+ bgFrom: string
137
+ bgTo: string
138
+ /** Big stat / value shown prominently */
139
+ metric?: string
140
+ metricLabel?: string
141
+ /** Called when card is clicked in active position */
142
+ onClick?: (card: RolodexCard) => void
143
+ }
144
+ ```
145
+
146
+ ## Data Loading Modes
147
+
148
+ ### Mode 1: Static Data (Default)
149
+
150
+ Pass card data directly as a prop:
151
+
152
+ ```jsx
153
+ <AwesomeRolodexCarousel
154
+ data={cards}
155
+ onCardChange={(index, card) => console.log(index, card)}
156
+ />
157
+ ```
158
+
159
+ ### Mode 2: Local JSON File
160
+
161
+ ```jsx
162
+ <AwesomeRolodexCarousel
163
+ apiEndpoint="/data/cards.json"
164
+ />
165
+ ```
166
+
167
+ File format: `/public/data/cards.json`
168
+ ```json
169
+ [
170
+ {
171
+ "id": 1,
172
+ "title": "Card Title",
173
+ "subtitle": "Subtitle",
174
+ "tag": "TAG",
175
+ "accent": "#00e5ff",
176
+ "bgFrom": "#020d1f",
177
+ "bgTo": "#041a30",
178
+ "metric": "99.7",
179
+ "metricLabel": "Uptime %",
180
+ "body": "Description text"
181
+ }
182
+ ]
183
+ ```
184
+
185
+ ### Mode 3: REST API
186
+
187
+ ```jsx
188
+ <AwesomeRolodexCarousel
189
+ apiEndpoint="https://api.example.com/cards"
190
+ apiHeaders={{ Authorization: 'Bearer TOKEN' }}
191
+ apiTransform={(raw) => raw.data} // if response is { data: ... }
192
+ />
193
+ ```
194
+
195
+ ## Complete Example
196
+
197
+ ```jsx
198
+ import React, { useState } from 'react'
199
+ import { AwesomeRolodexCarousel, RolodexCard } from 'awesome-rolodex-carousel'
200
+ import 'awesome-rolodex-carousel/styles'
201
+
202
+ const SAMPLE_CARDS: RolodexCard[] = [
203
+ {
204
+ id: 1,
205
+ title: 'Neural Core',
206
+ subtitle: 'AI Infrastructure',
207
+ tag: 'AI',
208
+ accent: '#00e5ff',
209
+ bgFrom: '#020d1f',
210
+ bgTo: '#041a30',
211
+ metric: '99.7',
212
+ metricLabel: 'Uptime %',
213
+ body: 'At the heart of every intelligent system lies a lattice of weights and connections that approximate thought itself.',
214
+ onClick: (card) => alert(`Opened: ${card.title}`),
215
+ },
216
+ {
217
+ id: 2,
218
+ title: 'Void Protocol',
219
+ subtitle: 'Zero-Trust Security',
220
+ tag: 'SEC',
221
+ accent: '#ff2d6f',
222
+ bgFrom: '#1a040a',
223
+ bgTo: '#2e0812',
224
+ metric: '0',
225
+ metricLabel: 'Breaches',
226
+ body: 'In an architecture of zero trust, every packet is a stranger. Every handshake is a negotiation.',
227
+ },
228
+ {
229
+ id: 3,
230
+ title: 'Orbital DB',
231
+ subtitle: 'Vector Storage Engine',
232
+ tag: 'DB',
233
+ accent: '#9d4dff',
234
+ bgFrom: '#0b0518',
235
+ bgTo: '#140a28',
236
+ metric: '1.4B',
237
+ metricLabel: 'Vectors',
238
+ body: 'Meaning is distance. In high-dimensional space, concepts cluster by affinity forming constellations of semantics.',
239
+ },
240
+ {
241
+ id: 4,
242
+ title: 'Flux Stream',
243
+ subtitle: 'Real-Time Pipeline',
244
+ tag: 'DATA',
245
+ accent: '#00ff9d',
246
+ bgFrom: '#011a0c',
247
+ bgTo: '#022e16',
248
+ metric: '4.2M',
249
+ metricLabel: 'Events/sec',
250
+ body: 'Data is not a resource to be mined — it is a river to be navigated. The stream never stops.',
251
+ },
252
+ {
253
+ id: 5,
254
+ title: 'Halo Edge',
255
+ subtitle: 'Global Edge Network',
256
+ tag: 'EDGE',
257
+ accent: '#ff9d00',
258
+ bgFrom: '#1a0e02',
259
+ bgTo: '#2a1603',
260
+ metric: '312',
261
+ metricLabel: 'PoPs',
262
+ body: 'Deploy models to the periphery. Compute lives where your users live. Latency measured in microseconds.',
263
+ },
264
+ ]
265
+
266
+ export default function App() {
267
+ const [activeCard, setActiveCard] = useState<RolodexCard | null>(null)
268
+
269
+ return (
270
+ <div>
271
+ <AwesomeRolodexCarousel
272
+ data={SAMPLE_CARDS}
273
+ cardWidth={560}
274
+ cardHeight={200}
275
+ slotGap={54}
276
+ visibleRadius={3}
277
+ autoInterval={3200}
278
+ snapDuration={420}
279
+ onCardChange={(index, card) => {
280
+ setActiveCard(card)
281
+ console.log(`Active: [${index + 1}] ${card.title}`)
282
+ }}
283
+ onCardClick={(card) => {
284
+ alert(`You clicked: ${card.title}`)
285
+ }}
286
+ />
287
+
288
+ {activeCard && (
289
+ <div style={{ position: 'fixed', bottom: 20, left: 20 }}>
290
+ <p>Active: {activeCard.title}</p>
291
+ </div>
292
+ )}
293
+ </div>
294
+ )
295
+ }
296
+ ```
297
+
298
+ ## Sample Data
299
+
300
+ Use this sample data to test the component:
301
+
302
+ ```json
303
+ [
304
+ {
305
+ "id": 1,
306
+ "title": "Neural Core",
307
+ "subtitle": "AI Infrastructure",
308
+ "tag": "AI",
309
+ "accent": "#00e5ff",
310
+ "bgFrom": "#020d1f",
311
+ "bgTo": "#041a30",
312
+ "metric": "99.7",
313
+ "metricLabel": "Uptime %",
314
+ "body": "At the heart of every intelligent system lies a lattice of weights and connections that approximate thought itself."
315
+ },
316
+ {
317
+ "id": 2,
318
+ "title": "Void Protocol",
319
+ "subtitle": "Zero-Trust Security",
320
+ "tag": "SEC",
321
+ "accent": "#ff2d6f",
322
+ "bgFrom": "#1a040a",
323
+ "bgTo": "#2e0812",
324
+ "metric": "0",
325
+ "metricLabel": "Breaches",
326
+ "body": "In an architecture of zero trust, every packet is a stranger. Every handshake is a negotiation."
327
+ },
328
+ {
329
+ "id": 3,
330
+ "title": "Orbital DB",
331
+ "subtitle": "Vector Storage Engine",
332
+ "tag": "DB",
333
+ "accent": "#9d4dff",
334
+ "bgFrom": "#0b0518",
335
+ "bgTo": "#140a28",
336
+ "metric": "1.4B",
337
+ "metricLabel": "Vectors",
338
+ "body": "Meaning is distance. In high-dimensional space, concepts cluster by affinity forming constellations of semantics."
339
+ },
340
+ {
341
+ "id": 4,
342
+ "title": "Flux Stream",
343
+ "subtitle": "Real-Time Pipeline",
344
+ "tag": "DATA",
345
+ "accent": "#00ff9d",
346
+ "bgFrom": "#011a0c",
347
+ "bgTo": "#022e16",
348
+ "metric": "4.2M",
349
+ "metricLabel": "Events/sec",
350
+ "body": "Data is not a resource to be mined — it is a river to be navigated. The stream never stops."
351
+ },
352
+ {
353
+ "id": 5,
354
+ "title": "Halo Edge",
355
+ "subtitle": "Global Edge Network",
356
+ "tag": "EDGE",
357
+ "accent": "#ff9d00",
358
+ "bgFrom": "#1a0e02",
359
+ "bgTo": "#2a1603",
360
+ "metric": "312",
361
+ "metricLabel": "PoPs",
362
+ "body": "Deploy models to the periphery. Compute lives where your users live. Latency measured in microseconds."
363
+ }
364
+ ]
365
+ ```
366
+
367
+ ## Styling
368
+
369
+ ### CSS Variables
370
+
371
+ The component uses CSS custom properties (CSS variables) for theming. Override them in your `:root`:
372
+
373
+ ```css
374
+ :root {
375
+ /* Typography */
376
+ --font-display: 'Cormorant Garamond', Georgia, serif;
377
+ --font-mono: 'Courier Prime', 'Courier New', monospace;
378
+ --font-ui: 'Barlow Condensed', sans-serif;
379
+
380
+ /* Colors */
381
+ --bg: #1a1208;
382
+ --bg-mid: #211808;
383
+ --brass: #b8860b;
384
+ --brass-light: #d4a017;
385
+ --brass-dim: #7a5a08;
386
+ --amber: #f5a623;
387
+ --cream: #f5efe0;
388
+ --cream-dim: #c8b898;
389
+ --mahogany: #4a1f0a;
390
+ --linen: #e8dcc8;
391
+ --shadow: rgba(0, 0, 0, 0.7);
392
+ }
393
+ ```
394
+
395
+ ### Including Styles
396
+
397
+ ```jsx
398
+ // Option 1: Import CSS file
399
+ import 'awesome-rolodex-carousel/styles'
400
+
401
+ // Option 2: Use CSS variables in your own stylesheet
402
+ ```
403
+
404
+ ## Interactions
405
+
406
+ - **Mouse Drag**: Drag the carousel vertically to rotate through cards
407
+ - **Scroll Wheel**: Scroll up/down to navigate
408
+ - **Keyboard**: Use ↑ and ↓ arrow keys to navigate
409
+ - **Click**: Click on the active card to trigger its onClick handler
410
+ - **Auto-scroll**: Carousel auto-advances every 3.2 seconds (configurable)
411
+ - **Hover**: Hovering pauses auto-scroll
412
+
413
+ ## Browser Support
414
+
415
+ - Chrome/Edge (latest)
416
+ - Firefox (latest)
417
+ - Safari (latest)
418
+ - Mobile browsers (iOS Safari, Chrome Mobile)
419
+
420
+ ## Performance
421
+
422
+ - Uses `requestAnimationFrame` for smooth 60fps animations
423
+ - CSS transforms for performant hardware acceleration
424
+ - Minimal re-renders with efficient state management
425
+ - Loads images lazily when data is provided via API
@@ -0,0 +1,32 @@
1
+ [
2
+ {
3
+ "id": 1, "title": "Neural Core", "subtitle": "AI Infrastructure", "tag": "AI", "accent": "#00e5ff", "bgFrom": "#020d1f", "bgTo": "#041a30", "metric": "99.7", "metricLabel": "Uptime %", "body": "At the heart of every intelligent system lies a lattice of weights and connections that approximate thought itself."
4
+ },
5
+ {
6
+ "id": 2, "title": "Void Protocol", "subtitle": "Zero-Trust Security", "tag": "SEC", "accent": "#ff2d6f", "bgFrom": "#1a040a", "bgTo": "#2e0812", "metric": "0", "metricLabel": "Breaches", "body": "In an architecture of zero trust, every packet is a stranger. Every handshake is a negotiation."
7
+ },
8
+ {
9
+ "id": 3, "title": "Orbital DB", "subtitle": "Vector Storage", "tag": "DB", "accent": "#9d4dff", "bgFrom": "#0b0518", "bgTo": "#140a28", "metric": "1.4B", "metricLabel": "Vectors", "body": "Meaning is distance. In high-dimensional space, concepts cluster by affinity."
10
+ },
11
+ {
12
+ "id": 4, "title": "Flux Stream", "subtitle": "Real-Time Pipeline", "tag": "DATA", "accent": "#00ff9d", "bgFrom": "#011a0c", "bgTo": "#022e16", "metric": "4.2M", "metricLabel": "Events/sec", "body": "Data is not a resource to be mined — it is a river to be navigated."
13
+ },
14
+ {
15
+ "id": 5, "title": "Halo Edge", "subtitle": "Edge Network", "tag": "EDGE", "accent": "#ff9d00", "bgFrom": "#1a0e02", "bgTo": "#2a1603", "metric": "312", "metricLabel": "PoPs", "body": "Deploy models to the periphery. Compute lives where your users live."
16
+ },
17
+ {
18
+ "id": 6, "title": "Phantom UI", "subtitle": "Interface Layer", "tag": "UX", "accent": "#ff6af0", "bgFrom": "#1a0318", "bgTo": "#260428", "metric": "0ms", "metricLabel": "Friction", "body": "The best interface is the one you forget you are using."
19
+ },
20
+ {
21
+ "id": 7, "title": "LLM Studio", "subtitle": "Fine-Tune & Prompt", "tag": "LLM", "accent": "#818cf8", "bgFrom": "#080022", "bgTo": "#0e0038", "metric": "128K", "metricLabel": "Context", "body": "Shape language models to your domain. Ship inference endpoints that scale."
22
+ },
23
+ {
24
+ "id": 8, "title": "Cloud Infra", "subtitle": "Auto-Scaling Arch", "tag": "CLOUD", "accent": "#4ade80", "bgFrom": "#021408", "bgTo": "#03200c", "metric": "∞", "metricLabel": "Scale", "body": "Infrastructure that breathes with demand. Never over-provision again."
25
+ },
26
+ {
27
+ "id": 9, "title": "Zero Point", "subtitle": "Latency Engine", "tag": "RT", "accent": "#38bdf8", "bgFrom": "#011520", "bgTo": "#012030", "metric": "<1ms", "metricLabel": "P99 Global", "body": "When latency approaches zero, request and response dissolve into thought."
28
+ },
29
+ {
30
+ "id": 10,"title": "Singularity", "subtitle": "Model Convergence", "tag": "AGI", "accent": "#fb7185", "bgFrom": "#1a0508", "bgTo": "#260610", "metric": "∞²", "metricLabel": "Capability", "body": "The convergence point where specialised models merge into general capability."
31
+ }
32
+ ]