@haventmet/carousel 1.0.0

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+	"mcpServers": {
+		"chrome-devtools": {
+			"command": "bunx",
+			"args": ["chrome-devtools-mcp@latest"]
+		}
+	}
+}

package/CLAUDE.md

@@ -0,0 +1,177 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Blossom Carousel is a native-scroll-first carousel component library with physics-based drag support. It provides a core implementation and framework-specific wrappers for React, Vue, Svelte, Alpine.js, and Web Components.
+
+**Key characteristics:**
+- Native scrolling with CSS scroll-snap support
+- Custom drag physics for fine pointer devices (mouse/trackpad) only - 0kb on touch devices
+- Conditional loading - physics engine only loads on devices with `(hover: hover) and (pointer: fine)`
+- Physics-based momentum scrolling with configurable friction and damping
+- Optional repeat/infinite scroll mode (disabled by default on touch devices)
+- Rubber banding overscroll effects
+- Programmatic navigation with `prev()` and `next()` methods
+- Index tracking with custom change events
+
+## Repository Structure
+
+This is a **pnpm workspace monorepo** with the following packages:
+
+- `packages/core` - Core TypeScript library with Vite build ([blossom-carousel.ts](packages/core/src/blossom-carousel.ts:1))
+- `packages/react` - React 19 wrapper component
+- `packages/vue` - Vue 3 wrapper component
+- `packages/svelte` - Svelte wrapper component
+- `packages/alpine` - Alpine.js plugin wrapper
+- `packages/web` - Web Component implementation
+- `packages/dev` - Development sandbox (Vue-based)
+
+All framework wrappers depend on `@numbered/carousel/core` and provide thin component layers that initialize/destroy the core Blossom instance.
+
+## Development Commands
+
+Use pnpm for all package management:
+
+```bash
+# Install dependencies
+pnpm install
+
+# Development servers (runs specific package dev server)
+pnpm dev              # Run dev sandbox (packages/dev)
+pnpm dev:react        # Run React package dev server
+pnpm dev:vue          # Run Vue package dev server
+pnpm dev:svelte       # Run Svelte package dev server
+pnpm dev:alpine       # Run Alpine.js package dev server
+pnpm dev:web          # Run Web Component package dev server
+
+# Build individual packages
+cd packages/core && pnpm build
+cd packages/react && pnpm build
+# etc...
+```
+
+## Core Architecture
+
+### Main Entry Point
+[packages/core/src/blossom-carousel.ts](packages/core/src/blossom-carousel.ts:15) exports the `Blossom` factory function which accepts:
+- `scroller: HTMLElement` - The scrollable container element
+- `options: CarouselOptions` - Configuration options:
+  - `repeat?: boolean` - Enable infinite scroll mode (automatically disabled on touch devices)
+  - `load?: 'always'` - Force physics loading on all devices including touch
+
+Returns an object with:
+- `init()` - Initialize the carousel
+- `destroy()` - Clean up and remove event listeners
+- `prev()` - Navigate to previous slide
+- `next()` - Navigate to next slide
+- `snap` - Boolean indicating if snap is enabled
+- `hasOverflow` - Proxy object tracking overflow state
+
+### Physics System
+The carousel uses a custom physics ticker ([tick function](packages/core/src/blossom-carousel.ts:423)) with:
+- **Friction** (`FRICTION = 0.72`) - Applied to velocity each frame
+- **Damping** (`DAMPING = 0.12`) - Smooth interpolation using exponential decay via `damp()` function
+- **Velocity projection** - Predicts final resting position for snap point selection
+- **Rubber banding** - 0.2x resistance when dragging beyond edges
+
+### Key Systems
+1. **Conditional loading** - Physics engine only loads on devices with `(hover: hover) and (pointer: fine)` media query, touch devices use native CSS scroll-snap
+2. **Pointer interaction** - Only activates on fine pointer devices (mouse/trackpad)
+3. **Scroll interception** - Patches `scrollTo`, `scrollBy`, and `Element.prototype.scrollIntoView` to disable physics during programmatic scrolling
+4. **Snap point calculation** - Traverses DOM to find elements with `scroll-snap-align`, computes their positions relative to scroll container
+5. **Virtual snap points** - Improved slide positioning system for more precise alignment
+6. **Repeat mode** - Translates slides to create infinite scroll illusion, resets scroll position when reaching edges (disabled on touch devices)
+7. **Index tracking** - Dispatches custom `change` events with `detail.index` when the active slide changes
+8. **Navigation methods** - `prev()` and `next()` methods for programmatic slide navigation
+
+### Important State Variables
+- `virtualScroll` - The smoothed scroll position updated by physics ticker
+- `target` - The target scroll position (updated by drag or velocity)
+- `velocity` - Current momentum vector
+- `isDragging` - Pointer down state
+- `isTicking` - Whether the animation frame loop is active
+- `hasOverflow` - Proxy that adds/removes event listeners when overflow changes
+
+## Framework Wrappers
+
+All wrappers follow the same pattern:
+1. Accept children/slots and forward props to rendered element
+2. Create a ref to the DOM element
+3. Call `Blossom(element, options)` on mount
+4. Call `blossom.init()` to start
+5. Call `blossom.destroy()` on unmount
+
+Example: [packages/react/src/BlossomCarousel.tsx](packages/react/src/BlossomCarousel.tsx:32)
+
+### React Wrapper
+- React 19 compatible
+- Uses custom `onChange` event pattern instead of traditional props
+- Dispatches custom `change` events with index information
+- Example: `<BlossomCarousel repeat={true} />`
+
+### Alpine.js Wrapper
+- Registered as an Alpine.js plugin via `Alpine.data('carousel', ...)`
+- Provides reactive `currentIndex` property
+- Exposes `prev()` and `next()` methods in the component scope
+- Listens for custom `change` events to update reactive state
+- Example: `<div x-data="carousel({ load: 'always' })">...</div>`
+
+### Custom Events
+All framework wrappers dispatch a standard `change` event on the carousel element:
+```javascript
+// Event structure
+new CustomEvent('change', {
+  detail: { index: number }
+})
+
+// Listening for changes
+carouselElement.addEventListener('change', (e) => {
+  console.log('Current index:', e.detail.index)
+})
+```
+
+## Mobile & Performance Optimization
+
+### Conditional Loading Strategy
+Blossom Carousel uses a smart loading strategy to optimize for different device types:
+
+**Desktop/Laptop (fine pointer devices)**
+- Full physics engine loads (~5-10kb)
+- Custom drag interactions with momentum
+- Physics-based scrolling with friction and damping
+- Rubber banding effects
+
+**Mobile/Touch devices**
+- Physics engine does NOT load (0kb overhead)
+- Native CSS `scroll-snap-type` handles snapping
+- Native touch scrolling for optimal performance
+- No repeat mode (infinite scroll disabled)
+
+**Detection**
+```javascript
+const hasMouse = window.matchMedia('(hover: hover) and (pointer: fine)').matches
+```
+
+**Force loading on all devices**
+```javascript
+Blossom(element, { load: 'always' })
+```
+
+### Performance Features
+- **Passive event listeners** - Scroll performance optimization
+- **ResizeObserver** - Efficient dimension updates
+- **MutationObserver** - Automatic recalculation when slides change
+- **RequestAnimationFrame** - Smooth 60fps animations
+- **Scroll interception** - Prevents physics conflicts during programmatic scrolling
+
+## Publishing
+
+Packages use `publishConfig.access: "public"` and are built to `dist/` directories with:
+- UMD build: `dist/blossom-carousel-{package}.umd.cjs`
+- ESM build: `dist/blossom-carousel-{package}.js`
+- Types: `dist/index.d.ts`
+- Styles: `dist/blossom-carousel-{package}.css`
+
+Vite is used for all builds with `vite-plugin-dts` for TypeScript declarations.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jesper Vos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,76 @@
+![Blossom Carousel](./public/cover.jpg)
+
+# Blossom Carousel
+
+<p>
+<a href="https://www.npmjs.com/package/@numbered/carousel/core"><img src="https://img.shields.io/npm/v/@numbered/carousel/core.svg?color=%23c1a8e2"></a>
+<a href="https://bundlephobia.com/package/@numbered/carousel/core"><img src="https://img.shields.io/bundlephobia/minzip/@numbered/carousel/core?color=%238ab4f8&label=gzip%20size"></a>
+</p>
+
+The native-first carousel enhanced with drag support.
+
+➥ [www.blossom-carousel.com](http://www.blossom-carousel.com)
+
+## Why Blossom?
+
+<ul style="list-style: none; padding: 0;">
+<li>🥇 <strong>Native scrolling</strong>: Full performance and accessibility.</li>
+<li>🚀 <strong>Dragging</strong>: Custom physics-based dragging for all pointer types.</li>
+<li>✨ <strong>No abstraction</strong>: use all native web API's.</li>
+<li>💡 <strong>Configure with CSS</strong>: Works with native scroll-snap, position sticky and scroll-driven animations.</li>
+<li>🪶 <strong>0kb on touch devices</strong>: Blossom only loads when a fine pointer device is detected.</li>
+<li>🧱 <strong>Works with major frameworks</strong>: Components for React, Vue, Svelte and Web Components.</li>
+</ul>
+
+## Installation
+
+### React
+
+[React Docs](./packages/react)
+
+```bash
+npm install @numbered/carousel/react
+```
+
+### Vue
+
+[Vue Docs](./packages/vue)
+
+```bash
+npm install @numbered/carousel/vue
+```
+
+### Svelte
+
+[Svelte Docs](./packages/svelte)
+
+```bash
+npm install @numbered/carousel/svelte
+```
+
+### Web Component
+
+[Web Component Docs](./packages/web)
+
+```bash
+npm install @numbered/carousel/web
+```
+
+### Core
+
+[Core Docs](./packages/core)
+
+```bash
+npm install @numbered/carousel/core
+```
+
+## Examples
+
+- [Simple](https://www.blossom-carousel.com/docs/examples#simple)
+- [Variable widths](https://www.blossom-carousel.com/docs/examples#variable-widths)
+- [CSS Grid](https://www.blossom-carousel.com/docs/examples#css-grid)
+- [Multiple rows](https://www.blossom-carousel.com/docs/examples#multiple-rows)
+- [Snapping](https://www.blossom-carousel.com/docs/examples#snapping)
+- [Grouping](https://www.blossom-carousel.com/docs/examples#grouping)
+- [Sticky](https://www.blossom-carousel.com/docs/examples#sticky)
+- [Coverflow](https://www.blossom-carousel.com/docs/examples#cover-flow)

package/biome.json

@@ -0,0 +1,174 @@
+{
+	"$schema": "https://biomejs.dev/schemas/2.2.2/schema.json",
+	"vcs": {
+		"enabled": false,
+		"clientKind": "git",
+		"useIgnoreFile": false
+	},
+	"files": {
+		"ignoreUnknown": true,
+		"experimentalScannerIgnores": ["node_modules", ".next"],
+		"includes": [
+			"**/*.{js,jsx,ts,tsx,css,scss,json}",
+			"!**/node_modules/**/*",
+			"!**/dist"
+		]
+	},
+	"formatter": {
+		"enabled": true,
+		"indentStyle": "tab",
+		"indentWidth": 2,
+		"lineWidth": 150
+	},
+	"assist": { "actions": { "source": { "organizeImports": "on" } } },
+	"linter": {
+		"enabled": true,
+		"rules": {
+			"correctness": {
+				"useExhaustiveDependencies": "off",
+				"useHookAtTopLevel": "off",
+				"useUniqueElementIds": "off"
+			},
+			"complexity": {
+				"useOptionalChain": {
+					"level": "error",
+					"fix": "safe"
+				}
+			},
+			"style": {
+				"noNonNullAssertion": "off",
+				"useTemplate": {
+					"level": "error",
+					"fix": "safe"
+				},
+				"noUnusedTemplateLiteral": {
+					"level": "error",
+					"fix": "safe"
+				},
+				"useNodejsImportProtocol": {
+					"level": "error",
+					"fix": "safe"
+				},
+				"noUselessElse": {
+					"level": "warn",
+					"fix": "safe"
+				},
+				"useAsConstAssertion": "error",
+				"useEnumInitializers": "error",
+				"useSelfClosingElements": "error",
+				"useSingleVarDeclarator": "error",
+				"useNumberNamespace": "error",
+				"noInferrableTypes": "error"
+			},
+			"suspicious": {
+				"noExplicitAny": "off",
+				"noImplicitAnyLet": "off",
+				"noArrayIndexKey": "off",
+				"noAssignInExpressions": "off"
+			},
+			"nursery": {
+				"useSortedClasses": {
+					"level": "error",
+					"fix": "safe",
+					"options": {}
+				}
+			}
+		},
+		"includes": [
+			"**",
+			"!**/.turbo",
+			"!**/dist",
+			"!**/node_modules"
+		]
+	},
+	"javascript": {
+		"formatter": {
+			"quoteStyle": "single",
+			"semicolons": "asNeeded",
+			"bracketSameLine": true,
+			"jsxQuoteStyle": "single"
+		},
+		"globals": ["document", "navigator", "window"]
+	},
+	"json": {
+		"formatter": {
+			"trailingCommas": "none",
+			"lineWidth": 100
+		}
+	},
+	"overrides": [
+		{
+			"includes": ["**/*.json"],
+			"linter": {
+				"rules": {}
+			}
+		},
+		{
+			"includes": ["**/*.css"],
+			"linter": {
+				"rules": {
+					"suspicious": {
+						"noUnknownAtRules": "warn"
+					}
+				}
+			}
+		},
+		{
+			"includes": ["**/*.ts", "**/*.tsx", "**/*.mts", "**/*.cts"],
+			"linter": {
+				"rules": {
+					"performance": {
+						"noDelete": "off",
+						"noAccumulatingSpread": "off"
+					},
+					"a11y": {
+						"noAutofocus": "off",
+						"noSvgWithoutTitle": "off",
+						"useValidAriaRole": "info",
+						"useKeyWithClickEvents": "warn",
+						"useButtonType": "off",
+						"useSemanticElements": "info",
+						"noStaticElementInteractions": "info"
+					},
+					"complexity": {
+						"noForEach": "off",
+						"noArguments": "error"
+					},
+					"correctness": {
+						"noConstAssign": "off",
+						"noGlobalObjectCalls": "off",
+						"noInvalidBuiltinInstantiation": "off",
+						"noInvalidConstructorSuper": "off",
+						"noSetterReturn": "off",
+						"noUndeclaredVariables": "off",
+						"noUnreachable": "off",
+						"noUnusedImports": "error",
+						"noUnreachableSuper": "off"
+					},
+					"style": {
+						"noParameterAssign": "off",
+						"useConst": "error",
+						"useDefaultParameterLast": "off"
+					},
+					"security": {
+						"noDangerouslySetInnerHtml": "off"
+					},
+					"suspicious": {
+						"noMisleadingCharacterClass": "off",
+						"noShadowRestrictedNames": "off",
+						"noDuplicateClassMembers": "off",
+						"noDuplicateObjectKeys": "off",
+						"noDuplicateParameters": "off",
+						"noFunctionAssign": "off",
+						"noImportAssign": "off",
+						"noRedeclare": "off",
+						"noUnsafeNegation": "off",
+						"useGetterReturn": "off",
+						"noVar": "error",
+						"useIterableCallbackReturn": "warn"
+					}
+				}
+			}
+		}
+	]
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+	"name": "@haventmet/carousel",
+	"version": "1.0.0",
+	"private": false,
+	"author": "Loris",
+	"license": "MIT",
+	"description": "A native-scroll-first carousel component for the web.",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/loris-numbered/carousel.git"
+	},
+	"bugs": {
+		"url": "https://github.com/loris-numbered/carousel/issues"
+	},
+	"main": "index.js",
+	"scripts": {
+		"test": "echo \"Error: no test specified\" && exit 1",
+		"dev": "pnpm --filter @haventmet/carousel-dev dev",
+		"dev:vue": "pnpm --filter @haventmet/carousel-vue dev",
+		"dev:react": "pnpm --filter @haventmet/carousel-react dev",
+		"dev:svelte": "pnpm --filter @haventmet/carousel-svelte dev",
+		"dev:web": "pnpm --filter @haventmet/carousel-web dev",
+		"dev:alpine": "pnpm --filter @haventmet/carousel-alpine dev"
+	},
+	"workspaces": [
+		"packages/*"
+	],
+	"devDependencies": {
+		"biome": "^0.3.3",
+		"turbo": "^2.5.0"
+	},
+	"packageManager": "pnpm@10.14.0+sha512.ad27a79641b49c3e481a16a805baa71817a04bbe06a38d17e60e2eaee83f6a146c6a688125f5792e48dd5ba30e7da52a5cda4c3992b9ccf333f9ce223af84748"
+}

package/packages/alpine/index.html

@@ -0,0 +1,50 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+	<meta charset="UTF-8" />
+	<link rel="icon" type="image/svg+xml" href="/vite.svg" />
+	<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+	<title>Blossom Carousel - Alpine.js</title>
+	<link rel="stylesheet" href="./style.css" />
+</head>
+
+<body>
+	<div class="page">
+		<h1>Blossom Carousel - Alpine.js</h1>
+
+		<div x-data="carousel({ load: 'always' })" class="wrapper">
+			<p>Current slide: <span x-text="currentIndex + 1"></span></p>
+
+			<ul class="carousel" x-ref="carousel">
+				<li class="slide">1</li>
+				<li class="slide">2</li>
+				<li class="slide">3</li>
+				<li class="slide">4</li>
+				<li class="slide">5</li>
+				<li class="slide">6</li>
+				<li class="slide">7</li>
+				<li class="slide">8</li>
+				<li class="slide">9</li>
+				<li class="slide">10</li>
+				<li class="slide">11</li>
+				<li class="slide">12</li>
+			</ul>
+
+			<div class="controls">
+				<button @click="prev()">Previous</button>
+				<button @click="next()">Next</button>
+			</div>
+		</div>
+	</div>
+
+	<script type="module">
+		import Alpine from 'alpinejs'
+		import blossomCarousel from './src/index.ts'
+
+		Alpine.plugin(blossomCarousel)
+		Alpine.start()
+	</script>
+</body>
+
+</html>

package/packages/alpine/package.json

@@ -0,0 +1,70 @@
+{
+	"name": "@haventmet/carousel-alpine",
+	"version": "0.1.2",
+	"author": "Loris",
+	"license": "MIT",
+	"description": "A native-scroll-first carousel component for Alpine.js.",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/loris-numbered/carousel"
+	},
+	"bugs": {
+		"url": "https://github.com/loris-numbered/carousel/issues"
+	},
+	"homepage": "https://www.blossom-carousel.com",
+	"keywords": [
+		"blossom",
+		"carousel",
+		"slider",
+		"slideshow",
+		"scroll",
+		"scroller",
+		"drag",
+		"dragging",
+		"js",
+		"javascript",
+		"typescript",
+		"web",
+		"html",
+		"css",
+		"alpine",
+		"alpinejs"
+	],
+	"type": "module",
+	"files": [
+		"dist"
+	],
+	"main": "dist/blossom-carousel-alpine.umd.cjs",
+	"module": "dist/blossom-carousel-alpine.js",
+	"types": "dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/blossom-carousel-alpine.js",
+			"require": "./dist/blossom-carousel-alpine.umd.cjs"
+		},
+		"./style.css": "./dist/blossom-carousel-alpine.css"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"dev": "vite",
+		"build": "vite build",
+		"preview": "vite preview"
+	},
+	"peerDependencies": {
+		"alpinejs": "^3.0.0"
+	},
+	"devDependencies": {
+		"@types/alpinejs": "^3.13.11",
+		"@types/node": "^24.8.0",
+		"alpinejs": "^3.15.0",
+		"typescript": "^5.9.3",
+		"vite": "^7.1.10",
+		"vite-plugin-dts": "^4.5.4"
+	},
+	"dependencies": {
+		"@haventmet/carousel": "workspace:*"
+	}
+}

package/packages/alpine/src/index.ts

@@ -0,0 +1,46 @@
+import { Blossom, type CarouselOptions } from '@numbered/carousel'
+import type { Alpine } from 'alpinejs'
+
+export default function blossomCarousel(Alpine: Alpine) {
+	Alpine.data('carousel', (options: CarouselOptions & { load?: 'always' } = {}) => ({
+		blossom: null as ReturnType<typeof Blossom> | null,
+		currentIndex: 0,
+
+		init() {
+			// Find the carousel element (first child with class 'carousel')
+			const carouselEl = this.$refs.carousel || this.$el
+
+			// Set the blossom-carousel attribute
+			carouselEl.setAttribute('blossom-carousel', 'true')
+
+			// Check if should load based on media query
+			const hasMouse = window.matchMedia('(hover: hover) and (pointer: fine)').matches
+
+			// Don't load if the user has no mouse (unless load: 'always')
+			if (!hasMouse && options.load !== 'always') {
+				return
+			}
+
+			this.blossom = Blossom(carouselEl, options)
+			this.blossom.init()
+
+			// Listen for change events
+			carouselEl.addEventListener('change', (e: Event) => {
+				const customEvent = e as CustomEvent<{ index: number }>
+				this.currentIndex = customEvent.detail.index
+			})
+		},
+
+		destroy() {
+			this.blossom?.destroy()
+		},
+
+		next() {
+			this.blossom?.next()
+		},
+
+		prev() {
+			this.blossom?.prev()
+		},
+	}))
+}