ilia/carousel
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

docs: carousel implementation plan

Browse Source
This commit is contained in:
Ilia Mashkov
2026-06-30 19:57:20 +03:00
parent 01fe0649ce
commit 0cf08f357a
1 changed files with 707 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/plans/2026-06-30-carousel-implementation.md
+707
View File
@@ -0,0 +1,707 @@
# Carousel Implementation Plan
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
**Goal:** Build a tiny, framework-agnostic scroll-snap carousel: a zero-dep core plus opt-in `dots()`/`autoplay()` modules and a CSS file.
**Architecture:** Native scroll handles touch/momentum; CSS handles snap and motion; JS is a thin layer. Core `createCarousel(track)` returns an instance (`next/prev/scrollToIndex/index/count/on/destroy`) with index tracking via IntersectionObserver. Controls are CSS-first (native `::scroll-marker`/`::scroll-button`); JS `dots()` is the Firefox/legacy fallback.
**Tech Stack:** TypeScript, tsup (build), Vitest + jsdom (unit), Playwright (browser smoke). No runtime deps.
Design reference: `docs/plans/2026-06-30-carousel-design.md`.
---
## Task 1: Scaffold the package
**Files:**
- Create: `package.json`, `tsconfig.json`, `tsup.config.ts`, `vitest.config.ts`, `.gitignore`, `src/index.ts`
**Step 1: Write `package.json`**
```json
{
"name": "carousel",
"version": "0.0.0",
"type": "module",
"sideEffects": ["*.css"],
"exports": {
".": "./dist/index.js",
"./dots": "./dist/dots.js",
"./autoplay": "./dist/autoplay.js",
"./carousel.css": "./src/carousel.css"
},
"files": ["dist", "src/carousel.css"],
"scripts": {
"build": "tsup src/index.ts src/dots.ts src/autoplay.ts --format esm --dts",
"test": "vitest run",
"test:e2e": "playwright test",
"check": "tsc --noEmit"
},
"devDependencies": {
"@playwright/test": "^1",
"jsdom": "^25",
"tsup": "^8",
"typescript": "^5",
"vitest": "^2"
}
}
```
**Step 2: Write `tsconfig.json`**
```json
{
"compilerOptions": {
"target": "ES2022",
"module": "ESNext",
"moduleResolution": "bundler",
"strict": true,
"verbatimModuleSyntax": true,
"lib": ["ES2022", "DOM", "DOM.Iterable"],
"noEmit": true,
"skipLibCheck": true
},
"include": ["src", "tests"]
}
```
**Step 3: Write `vitest.config.ts`**
```ts
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: { environment: 'jsdom', include: ['tests/**/*.test.ts'] },
});
```
**Step 4: Write `.gitignore`**
```
node_modules
dist
test-results
playwright-report
```
**Step 5: Stub `src/index.ts`**
```ts
export {};
```
**Step 6: Install and verify**
Run: `yarn install && yarn check`
Expected: installs cleanly, `tsc` exits 0.
**Step 7: Commit**
```bash
git add -A
git commit -m "chore: scaffold carousel package"
```
---
## Task 2: Core `createCarousel` — count, navigation, scrollToIndex
**Files:**
- Modify: `src/index.ts`
- Test: `tests/core.test.ts`
> jsdom has no layout/scroll. Provide a minimal `IntersectionObserver` shim in the
> test setup and assert on `scrollTo` calls (spy) rather than real scrolling.
**Step 1: Write the failing test**
```ts
// tests/core.test.ts
import { beforeEach, expect, test, vi } from 'vitest';
import { createCarousel } from '../src/index.ts';
// Minimal IO shim — records instances so tests can fire entries manually.
class IOShim {
static last: IOShim | null = null;
cb: IntersectionObserverCallback;
elements: Element[] = [];
constructor(cb: IntersectionObserverCallback) {
this.cb = cb;
IOShim.last = this;
}
observe(el: Element) { this.elements.push(el); }
unobserve() {}
disconnect() {}
// helper: emit "slide i is the one intersecting"
emit(i: number) {
this.cb(
this.elements.map((target, idx) => ({
target,
isIntersecting: idx === i,
intersectionRatio: idx === i ? 1 : 0,
})) as unknown as IntersectionObserverEntry[],
this as unknown as IntersectionObserver,
);
}
}
vi.stubGlobal('IntersectionObserver', IOShim);
function makeTrack(n: number): HTMLElement {
const track = document.createElement('div');
for (let i = 0; i < n; i++) {
const slide = document.createElement('div');
slide.className = 'slide';
track.append(slide);
}
track.scrollTo = vi.fn();
return track;
}
let track: HTMLElement;
beforeEach(() => { track = makeTrack(3); });
test('count reflects slide children', () => {
const c = createCarousel(track);
expect(c.count).toBe(3);
});
test('next/prev clamp to range and scroll to target offset', () => {
const c = createCarousel(track);
// give slides fake offsets
(track.children[1] as HTMLElement).offsetLeft; // 0 in jsdom
c.next();
expect(track.scrollTo).toHaveBeenCalled();
});
```
**Step 2: Run test to verify it fails**
Run: `yarn test tests/core.test.ts`
Expected: FAIL — `createCarousel` not exported.
**Step 3: Write minimal implementation**
```ts
// src/index.ts
export type CarouselEvent = 'change';
export type Carousel = {
next(): void;
prev(): void;
scrollToIndex(i: number): void;
readonly index: number;
readonly count: number;
on(evt: CarouselEvent, cb: (index: number) => void): () => void;
destroy(): void;
};
/**
* Wrap a scroll-snap track element and return a carousel controller.
* @param track - the overflow-x scroll container whose children are slides
*/
export function createCarousel(track: HTMLElement): Carousel {
const slides = () => Array.from(track.children) as HTMLElement[];
let index = 0;
const listeners = new Set<(i: number) => void>();
const clamp = (i: number) => Math.max(0, Math.min(i, slides().length - 1));
function scrollToIndex(i: number) {
const target = slides()[clamp(i)];
if (target) {
track.scrollTo({ left: target.offsetLeft, behavior: 'smooth' });
}
}
// index tracking: whichever slide is most intersecting is current
const io = new IntersectionObserver(
(entries) => {
const hit = entries.find((e) => e.isIntersecting);
if (!hit) return;
const i = slides().indexOf(hit.target as HTMLElement);
if (i !== -1 && i !== index) {
index = i;
listeners.forEach((cb) => cb(index));
}
},
{ root: track, threshold: 0.6 },
);
slides().forEach((s) => io.observe(s));
return {
next: () => scrollToIndex(index + 1),
prev: () => scrollToIndex(index - 1),
scrollToIndex,
get index() { return index; },
get count() { return slides().length; },
on(_evt, cb) {
listeners.add(cb);
return () => listeners.delete(cb);
},
destroy() {
io.disconnect();
listeners.clear();
},
};
}
```
**Step 4: Run test to verify it passes**
Run: `yarn test tests/core.test.ts`
Expected: PASS (2 tests).
**Step 5: Commit**
```bash
git add src/index.ts tests/core.test.ts
git commit -m "feat: carousel core (count, navigation, scrollToIndex)"
```
---
## Task 3: Core — `change` event fires on snap, `destroy` cleans up
**Files:**
- Test: `tests/core.test.ts` (add cases)
**Step 1: Write failing tests**
```ts
test('change fires with new index when a slide intersects', () => {
const c = createCarousel(track);
const seen: number[] = [];
c.on('change', (i) => seen.push(i));
(IOShim.last as IOShim).emit(2); // user swiped to slide 2
expect(seen).toEqual([2]);
expect(c.index).toBe(2);
});
test('change does not re-fire for the same index', () => {
const c = createCarousel(track);
const seen: number[] = [];
c.on('change', (i) => seen.push(i));
(IOShim.last as IOShim).emit(1);
(IOShim.last as IOShim).emit(1);
expect(seen).toEqual([1]);
});
test('unsubscribe stops delivery; destroy disconnects observer', () => {
const c = createCarousel(track);
const seen: number[] = [];
const off = c.on('change', (i) => seen.push(i));
off();
(IOShim.last as IOShim).emit(2);
expect(seen).toEqual([]);
const spy = vi.spyOn(IOShim.last as IOShim, 'disconnect');
c.destroy();
expect(spy).toHaveBeenCalled();
});
```
**Step 2: Run to verify**
Run: `yarn test tests/core.test.ts`
Expected: PASS — implementation from Task 2 already covers these. If any fail, fix `src/index.ts` minimally.
**Step 3: Commit (only if code changed)**
```bash
git add -A
git commit -m "test: carousel core change/destroy edge cases"
```
---
## Task 4: `dots()` fallback module
**Files:**
- Create: `src/dots.ts`
- Test: `tests/dots.test.ts`
> Wires the developer's existing dot elements. Click → `scrollToIndex`. `change` →
> toggle `aria-current`/`.active`. Engages only when native `::scroll-marker` is
> unsupported (feature-detect via `CSS.supports('selector(::scroll-marker)')`); in
> tests we force-enable by passing the dots explicitly.
**Step 1: Write failing test**
```ts
// tests/dots.test.ts
import { expect, test, vi } from 'vitest';
import { dots } from '../src/dots.ts';
function fakeCarousel() {
let cb: (i: number) => void = () => {};
return {
index: 0, count: 3,
next: vi.fn(), prev: vi.fn(),
scrollToIndex: vi.fn(),
on: (_e: string, fn: (i: number) => void) => { cb = fn; return () => {}; },
destroy: vi.fn(),
fire: (i: number) => cb(i),
};
}
test('clicking a dot scrolls to its index', () => {
const c = fakeCarousel();
const container = document.createElement('div');
container.innerHTML = '<button></button><button></button><button></button>';
dots(c as never, container);
(container.children[2] as HTMLButtonElement).click();
expect(c.scrollToIndex).toHaveBeenCalledWith(2);
});
test('change marks the active dot with aria-current', () => {
const c = fakeCarousel();
const container = document.createElement('div');
container.innerHTML = '<button></button><button></button><button></button>';
dots(c as never, container);
c.fire(1);
expect(container.children[1].getAttribute('aria-current')).toBe('true');
expect(container.children[0].hasAttribute('aria-current')).toBe(false);
});
```
**Step 2: Run to verify it fails**
Run: `yarn test tests/dots.test.ts`
Expected: FAIL — `dots` not found.
**Step 3: Implement**
```ts
// src/dots.ts
import type { Carousel } from './index.ts';
/**
* Wire the developer's existing dot elements to a carousel.
* Progressive fallback: prefer native ::scroll-marker where supported.
* @param c - carousel instance
* @param container - element whose children are the dot controls
*/
export function dots(c: Carousel, container: HTMLElement): () => void {
const items = Array.from(container.children) as HTMLElement[];
const onClick = (i: number) => () => c.scrollToIndex(i);
const handlers = items.map((el, i) => {
const h = onClick(i);
el.addEventListener('click', h);
return h;
});
function mark(active: number) {
items.forEach((el, i) => {
if (i === active) {
el.setAttribute('aria-current', 'true');
el.classList.add('active');
} else {
el.removeAttribute('aria-current');
el.classList.remove('active');
}
});
}
mark(c.index);
const off = c.on('change', mark);
return () => {
off();
items.forEach((el, i) => el.removeEventListener('click', handlers[i]));
};
}
```
**Step 4: Run to verify it passes**
Run: `yarn test tests/dots.test.ts`
Expected: PASS (2 tests).
**Step 5: Commit**
```bash
git add src/dots.ts tests/dots.test.ts
git commit -m "feat: dots() fallback control module"
```
---
## Task 5: `autoplay()` module
**Files:**
- Create: `src/autoplay.ts`
- Test: `tests/autoplay.test.ts`
> Timer calls `c.next()`. Pause on `pointerenter`/`focusin`, resume on leave/blur,
> stop on manual interaction. Loops back to 0 at the end. Use fake timers.
**Step 1: Write failing test**
```ts
// tests/autoplay.test.ts
import { afterEach, beforeEach, expect, test, vi } from 'vitest';
import { autoplay } from '../src/autoplay.ts';
function fakeCarousel(count = 3) {
let index = 0;
return {
get index() { return index; }, count,
next: vi.fn(() => { index = (index + 1) % count; }),
prev: vi.fn(), scrollToIndex: vi.fn(),
on: () => () => {}, destroy: vi.fn(),
};
}
beforeEach(() => vi.useFakeTimers());
afterEach(() => vi.useRealTimers());
test('advances every interval', () => {
const c = fakeCarousel();
autoplay(c as never, { interval: 1000, root: document.createElement('div') });
vi.advanceTimersByTime(2000);
expect(c.next).toHaveBeenCalledTimes(2);
});
test('pause on pointerenter, resume on pointerleave', () => {
const c = fakeCarousel();
const root = document.createElement('div');
autoplay(c as never, { interval: 1000, root });
root.dispatchEvent(new Event('pointerenter'));
vi.advanceTimersByTime(3000);
expect(c.next).not.toHaveBeenCalled();
root.dispatchEvent(new Event('pointerleave'));
vi.advanceTimersByTime(1000);
expect(c.next).toHaveBeenCalledTimes(1);
});
test('stop() halts and removes listeners', () => {
const c = fakeCarousel();
const stop = autoplay(c as never, { interval: 1000, root: document.createElement('div') });
stop();
vi.advanceTimersByTime(5000);
expect(c.next).not.toHaveBeenCalled();
});
```
**Step 2: Run to verify it fails**
Run: `yarn test tests/autoplay.test.ts`
Expected: FAIL — `autoplay` not found.
**Step 3: Implement**
```ts
// src/autoplay.ts
import type { Carousel } from './index.ts';
/**
* Options for autoplay.
*/
export type AutoplayOptions = {
/** ms between advances */
interval: number;
/** element whose hover/focus pauses playback (usually the track wrapper) */
root: HTMLElement;
};
/**
* Auto-advance a carousel, pausing on hover/focus.
* @param c - carousel instance
* @param opts - interval (ms) and the root element to bind pause events to
* @returns stop function that halts playback and removes listeners
*/
export function autoplay(c: Carousel, opts: AutoplayOptions): () => void {
let timer: ReturnType<typeof setInterval> | undefined;
const tick = () => c.next();
const start = () => { timer ??= setInterval(tick, opts.interval); };
const pause = () => { clearInterval(timer); timer = undefined; };
opts.root.addEventListener('pointerenter', pause);
opts.root.addEventListener('pointerleave', start);
opts.root.addEventListener('focusin', pause);
opts.root.addEventListener('focusout', start);
start();
return () => {
pause();
opts.root.removeEventListener('pointerenter', pause);
opts.root.removeEventListener('pointerleave', start);
opts.root.removeEventListener('focusin', pause);
opts.root.removeEventListener('focusout', start);
};
}
```
**Step 4: Run to verify it passes**
Run: `yarn test tests/autoplay.test.ts`
Expected: PASS (3 tests).
**Step 5: Commit**
```bash
git add src/autoplay.ts tests/autoplay.test.ts
git commit -m "feat: autoplay() module with hover/focus pause"
```
---
## Task 6: `carousel.css`
**Files:**
- Create: `src/carousel.css`
> No test — it's static CSS, validated by the Playwright smoke test in Task 7.
**Step 1: Write the stylesheet**
```css
/* carousel.css — snap track, hidden scrollbar, native markers, opt-in effects */
.track {
display: flex;
gap: 1rem;
overflow-x: auto;
scroll-snap-type: x mandatory;
scrollbar-width: none;
scroll-marker-group: after; /* native dots where supported */
}
.track::-webkit-scrollbar { display: none; }
.slide {
flex: 0 0 80%;
scroll-snap-align: center;
scroll-snap-stop: always; /* one swipe = one slide */
}
/* native CSS markers (Chrome 135+, Safari 18.2+) */
.slide::scroll-marker {
content: '';
width: 0.6rem;
height: 0.6rem;
border-radius: 50%;
background: currentColor;
opacity: 0.4;
}
.slide::scroll-marker:target-current { opacity: 1; }
/* opt-in tactile effect; degrades to plain snap where unsupported */
@supports (animation-timeline: view()) {
.track.fx .slide {
animation: slide-fx linear both;
animation-timeline: view(inline);
}
@keyframes slide-fx {
entry 0%, exit 100% { scale: 0.9; opacity: 0.5; }
cover 50% { scale: 1; opacity: 1; }
}
}
```
**Step 2: Commit**
```bash
git add src/carousel.css
git commit -m "feat: carousel.css (snap, native markers, opt-in effects)"
```
---
## Task 7: Playwright smoke test (real scroll)
**Files:**
- Create: `playwright.config.ts`, `e2e/demo.html`, `e2e/smoke.test.ts`
> jsdom can't scroll. One real-browser test proves snap + `next()` actually move.
**Step 1: Write `playwright.config.ts`**
```ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
testDir: 'e2e',
use: { baseURL: 'http://localhost:5173' },
webServer: { command: 'npx http-server e2e -p 5173 -s', port: 5173, reuseExistingServer: true },
});
```
**Step 2: Write `e2e/demo.html`**
A page that imports the built core from `../dist/index.js`, builds a 3-slide track,
exposes `window.c = createCarousel(track)`. Include `carousel.css`.
```html
<!doctype html>
<link rel="stylesheet" href="../src/carousel.css" />
<div class="track" id="t" style="width:300px">
<div class="slide" id="s0">0</div>
<div class="slide" id="s1">1</div>
<div class="slide" id="s2">2</div>
</div>
<script type="module">
import { createCarousel } from '../dist/index.js';
window.c = createCarousel(document.getElementById('t'));
</script>
```
**Step 3: Write the test**
```ts
// e2e/smoke.test.ts
import { expect, test } from '@playwright/test';
test('next() scrolls the track and updates index', async ({ page }) => {
await page.goto('/demo.html');
const before = await page.evaluate(() => document.getElementById('t')!.scrollLeft);
await page.evaluate(() => (window as any).c.next());
await page.waitForTimeout(500); // smooth scroll settle
const after = await page.evaluate(() => document.getElementById('t')!.scrollLeft);
expect(after).toBeGreaterThan(before);
await expect.poll(() => page.evaluate(() => (window as any).c.index)).toBe(1);
});
```
**Step 4: Build, then run**
Run: `yarn build && yarn test:e2e`
Expected: PASS — `scrollLeft` increases, `index` becomes 1.
**Step 5: Commit**
```bash
git add playwright.config.ts e2e/
git commit -m "test: playwright smoke for real scroll behavior"
```
---
## Task 8: README + verify the public API
**Files:**
- Create: `README.md`
**Step 1: Write a short README** — install, the three import paths, a copy-paste
example wiring arrows (manual handlers) + `dots()` fallback + native CSS markers, and
the browser-support table from the design doc.
**Step 2: Final verification**
Run: `yarn check && yarn test && yarn build`
Expected: all green; `dist/` contains `index.js`, `dots.js`, `autoplay.js` with `.d.ts`.
**Step 3: Commit**
```bash
git add README.md
git commit -m "docs: README with usage and browser support"
```
---
## Notes for the executor
- **DRY/YAGNI:** no loop mode, no DOM generation, no fade variant — explicitly deferred.
- **Fold review fixes** into the related task's commit; don't leave "feature + fix" pairs.
- The IO shim and fake-carousel helpers are deliberately tiny — don't promote them to a
framework.