@uinstinct/svelte-wheel-picker 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aditya Mitra
+
+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,304 @@
+# @uinstinct/svelte-wheel-picker
+
+[![npm version](https://img.shields.io/npm/v/@uinstinct/svelte-wheel-picker)](https://www.npmjs.com/package/@uinstinct/svelte-wheel-picker)
+[![license](https://img.shields.io/npm/l/@uinstinct/svelte-wheel-picker)](https://github.com/uinstinct/svelte-wheel-picker/blob/main/LICENSE)
+
+iOS-style wheel picker for Svelte 5 with smooth inertia scrolling, infinite loop support, keyboard navigation, and cylindrical 3D effect.
+
+## Features
+
+- Svelte 5 runes-based reactivity
+- Smooth inertia scrolling with spring physics
+- Infinite loop mode
+- Cylindrical/drum 3D visual effect
+- Full keyboard navigation (arrow keys, Home/End, type-ahead search)
+- Controlled and uncontrolled modes
+- Disabled options support
+- `WheelPickerWrapper` for multi-wheel layouts (time picker, date picker)
+- Headless/unstyled with data attributes for CSS targeting
+- Zero runtime dependencies
+- TypeScript types included
+- SSR safe
+
+## Installation
+
+### npm
+
+```bash
+npm install @uinstinct/svelte-wheel-picker
+```
+
+```bash
+pnpm add @uinstinct/svelte-wheel-picker
+```
+
+```bash
+yarn add @uinstinct/svelte-wheel-picker
+```
+
+### shadcn-svelte
+
+```bash
+npx shadcn-svelte@latest add https://svelte-wheel-picker.vercel.app/r/wheel-picker.json
+```
+
+This copies the component source directly into your project under `src/lib/components/ui/wheel-picker/`.
+
+## Quick Start
+
+```svelte
+<script lang="ts">
+  import { WheelPicker } from '@uinstinct/svelte-wheel-picker';
+
+  const fruits = [
+    { value: 'apple', label: 'Apple' },
+    { value: 'banana', label: 'Banana' },
+    { value: 'cherry', label: 'Cherry' },
+    { value: 'date', label: 'Date' },
+    { value: 'fig', label: 'Fig' },
+  ];
+
+  let selected = $state('cherry');
+</script>
+
+<WheelPicker
+  options={fruits}
+  value={selected}
+  onValueChange={(v) => { selected = v; }}
+/>
+```
+
+## Examples
+
+### Basic (controlled mode)
+
+```svelte
+<script lang="ts">
+  import { WheelPicker } from '@uinstinct/svelte-wheel-picker';
+
+  const options = [
+    { value: 'a', label: 'Option A' },
+    { value: 'b', label: 'Option B' },
+    { value: 'c', label: 'Option C' },
+  ];
+
+  let value = $state('a');
+</script>
+
+<WheelPicker
+  {options}
+  {value}
+  onValueChange={(v) => { value = v; }}
+/>
+```
+
+### Infinite loop
+
+```svelte
+<script lang="ts">
+  import { WheelPicker } from '@uinstinct/svelte-wheel-picker';
+
+  const fruits = [
+    { value: 'apple', label: 'Apple' },
+    { value: 'banana', label: 'Banana' },
+    { value: 'cherry', label: 'Cherry' },
+  ];
+
+  let selected = $state('apple');
+</script>
+
+<WheelPicker
+  options={fruits}
+  value={selected}
+  onValueChange={(v) => { selected = v; }}
+  infinite={true}
+/>
+```
+
+### Cylindrical/drum effect
+
+```svelte
+<script lang="ts">
+  import { WheelPicker } from '@uinstinct/svelte-wheel-picker';
+
+  const fruits = [
+    { value: 'apple', label: 'Apple' },
+    { value: 'banana', label: 'Banana' },
+    { value: 'cherry', label: 'Cherry' },
+  ];
+
+  let selected = $state('apple');
+</script>
+
+<WheelPicker
+  options={fruits}
+  value={selected}
+  onValueChange={(v) => { selected = v; }}
+  cylindrical={true}
+/>
+```
+
+### Multi-wheel with WheelPickerWrapper
+
+```svelte
+<script lang="ts">
+  import { WheelPicker, WheelPickerWrapper } from '@uinstinct/svelte-wheel-picker';
+
+  const hourOptions = Array.from({ length: 12 }, (_, i) => ({
+    value: String(i + 1).padStart(2, '0'),
+    label: String(i + 1).padStart(2, '0'),
+  }));
+
+  const minuteOptions = Array.from({ length: 60 }, (_, i) => ({
+    value: String(i).padStart(2, '0'),
+    label: String(i).padStart(2, '0'),
+  }));
+
+  let hour = $state('12');
+  let minute = $state('00');
+</script>
+
+<WheelPickerWrapper classNames={{ group: 'time-picker' }}>
+  <WheelPicker
+    options={hourOptions}
+    value={hour}
+    onValueChange={(v) => { hour = v; }}
+  />
+  <WheelPicker
+    options={minuteOptions}
+    value={minute}
+    onValueChange={(v) => { minute = v; }}
+  />
+</WheelPickerWrapper>
+
+<style>
+  :global([data-swp-group].time-picker) {
+    display: flex;
+    flex-direction: row;
+    align-items: stretch;
+  }
+</style>
+```
+
+## API Reference
+
+### `WheelPickerProps<T>`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `options` | `WheelPickerOption<T>[]` | — | The list of selectable options. Required. |
+| `value` | `T` | `undefined` | Current value (controlled mode). `undefined` means no option selected. |
+| `defaultValue` | `T` | `undefined` | Initial value (uncontrolled mode). |
+| `onValueChange` | `(value: T) => void` | `undefined` | Callback when value changes. Presence signals controlled mode. |
+| `classNames` | `WheelPickerClassNames` | `{}` | Per-element CSS class overrides. |
+| `visibleCount` | `number` | `5` | Number of visible option rows. Must be odd. |
+| `optionItemHeight` | `number` | `30` | Height in pixels of each option row. |
+| `dragSensitivity` | `number` | `3` | Pointer drag delta multiplier (affects inertia deceleration). |
+| `scrollSensitivity` | `number` | `5` | Scroll wheel delta multiplier (affects snap animation duration). |
+| `infinite` | `boolean` | `false` | Enable infinite loop scrolling (wraps at both ends). |
+| `cylindrical` | `boolean` | `false` | Enable rotating drum/cylinder visual style with faux-3D scaleY compression. |
+
+### `WheelPickerOption<T>`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `value` | `T` | The option's value. Must be `string` or `number`. |
+| `label` | `string` | Display text rendered in the wheel. |
+| `textValue` | `string` (optional) | Fallback text for type-ahead search when `label` is not plain text. |
+| `disabled` | `boolean` (optional) | Whether this option is disabled (skipped in navigation). |
+
+### `WheelPickerWrapperProps`
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `classNames` | `WheelPickerWrapperClassNames` | Per-element CSS class overrides for the wrapper group container. |
+
+**`WheelPickerWrapperClassNames`**: `{ group?: string }` — optional CSS class for the outer group container div.
+
+## Styling
+
+The library ships no CSS. It is fully headless. Use the `classNames` prop to assign your own CSS classes, then target elements with your stylesheet.
+
+### Data Attributes
+
+All elements expose data attributes for CSS targeting:
+
+| Attribute | Element | Notes |
+|-----------|---------|-------|
+| `data-swp-wrapper` | Outer container of `WheelPicker` | Always present |
+| `data-swp-option` | Each option row | Always present |
+| `data-swp-option-text` | Text span inside each option | Always present |
+| `data-swp-selection` | Center selection highlight overlay | Always present |
+| `data-swp-selected` | Option row | Present with value `"true"` when the option is currently selected |
+| `data-swp-disabled` | Option row | Present with value `"true"` when the option is disabled |
+| `data-swp-group` | Outer container of `WheelPickerWrapper` | Always present |
+
+### CSS Example
+
+```css
+/* Make the wheel container draggable */
+[data-swp-wrapper].my-wheel {
+  width: 200px;
+  cursor: grab;
+  user-select: none;
+  touch-action: none;
+}
+
+[data-swp-wrapper].my-wheel:active {
+  cursor: grabbing;
+}
+
+/* Style the selection highlight */
+[data-swp-selection].my-selection {
+  background: rgba(59, 130, 246, 0.15);
+  border-top: 1px solid rgba(59, 130, 246, 0.3);
+  border-bottom: 1px solid rgba(59, 130, 246, 0.3);
+}
+
+/* Style each option row */
+[data-swp-option].my-option {
+  font-size: 16px;
+  transition: opacity 0.15s;
+}
+
+/* Dim disabled options */
+[data-swp-option][data-swp-disabled='true'] {
+  opacity: 0.3;
+}
+
+/* Bold the selected option */
+[data-swp-option][data-swp-selected='true'] {
+  font-weight: 600;
+}
+```
+
+Pass your class names via the `classNames` prop:
+
+```svelte
+<WheelPicker
+  {options}
+  {value}
+  onValueChange={(v) => { value = v; }}
+  classNames={{
+    wrapper: 'my-wheel',
+    selection: 'my-selection',
+    option: 'my-option',
+  }}
+/>
+```
+
+## Keyboard Navigation
+
+When the wheel picker is focused:
+
+| Key | Action |
+|-----|--------|
+| `Arrow Up` | Move selection up by one |
+| `Arrow Down` | Move selection down by one |
+| `Home` | Jump to first option |
+| `End` | Jump to last option |
+| Type a character | Type-ahead search: jump to the next option whose label (or `textValue`) starts with the typed character(s) |
+
+## License
+
+MIT

package/dist/WheelPicker.svelte

@@ -0,0 +1,349 @@
+<script lang="ts">
+	import { untrack } from 'svelte';
+	import type { WheelPickerProps } from './types.js';
+	import { WheelPhysics } from './use-wheel-physics.svelte.js';
+	import { useControllableState } from './use-controllable-state.svelte.js';
+	import { useTypeaheadSearch } from './use-typeahead-search.svelte.js';
+	import {
+		DEFAULT_VISIBLE_COUNT,
+		DEFAULT_ITEM_HEIGHT,
+		DEFAULT_DRAG_SENSITIVITY,
+		DEFAULT_SCROLL_SENSITIVITY,
+		cylindricalScaleY,
+	} from './wheel-physics-utils.js';
+	import { wrapIndex } from './wheel-physics-utils.js';
+
+	let {
+		options,
+		value,
+		defaultValue,
+		onValueChange,
+		classNames,
+		visibleCount: rawVisibleCount = DEFAULT_VISIBLE_COUNT,
+		optionItemHeight = DEFAULT_ITEM_HEIGHT,
+		dragSensitivity = DEFAULT_DRAG_SENSITIVITY,
+		scrollSensitivity = DEFAULT_SCROLL_SENSITIVITY,
+		infinite = false,
+		cylindrical = false,
+	}: WheelPickerProps = $props();
+
+	// D-07: visibleCount must be odd — warn and round up if even
+	const visibleCount = $derived.by(() => {
+		if (rawVisibleCount % 2 === 0) {
+			console.warn(
+				`[WheelPicker] visibleCount must be an odd number. Received ${rawVisibleCount}, rounding up to ${rawVisibleCount + 1}.`,
+			);
+			return rawVisibleCount + 1;
+		}
+		return rawVisibleCount;
+	});
+
+	// Controlled/uncontrolled state management
+	const state = useControllableState({
+		value,
+		defaultValue,
+		onChange: onValueChange,
+	});
+
+	// Derive the currently selected index
+	const selectedIndex = $derived(options.findIndex((o) => o.value === state.current));
+
+	// Determine initial index — use selectedIndex if found, otherwise first enabled
+	const initialIndex = $derived.by(() => {
+		if (selectedIndex >= 0) return selectedIndex;
+		const first = options.findIndex((o) => !o.disabled);
+		return first >= 0 ? first : 0;
+	});
+
+	// Instantiate the physics engine
+	const physics = new WheelPhysics({
+		itemHeight: optionItemHeight,
+		visibleCount: visibleCount,
+		dragSensitivity,
+		scrollSensitivity,
+		options,
+		initialIndex,
+		infinite,
+		onSnap: (index: number) => {
+			console.log('[onSnap] index=', index, 'infinite=', infinite, 'offset=', physics.offset);
+			if (infinite) {
+				// D-04: Normalize offset on snap settle
+				const wrappedIndex = wrapIndex(index, options.length);
+				physics.jumpTo(wrappedIndex);
+				const opt = options[wrappedIndex];
+				console.log(
+					'[onSnap] wrappedIndex=',
+					wrappedIndex,
+					'opt=',
+					opt?.value,
+					'jumpTo offset=',
+					physics.offset,
+				);
+				if (opt && !opt.disabled) {
+					state.current = opt.value;
+				}
+			} else {
+				const opt = options[index];
+				if (opt && !opt.disabled) {
+					state.current = opt.value;
+				}
+			}
+		},
+	});
+
+	// Typeahead search instance
+	const typeahead = useTypeaheadSearch();
+
+	// Cleanup on component destroy
+	$effect(() => {
+		return () => {
+			physics.destroy();
+			typeahead.destroy();
+		};
+	});
+
+	// Keep state.current reactive in controlled mode — update tracked value when value prop changes
+	$effect(() => {
+		state.updateControlledValue(value);
+	});
+
+	// React to external `value` prop changes (D-05: cancel mid-flight, jump to new position)
+	// Guard: only animate if the target index differs from the current visual position.
+	// IMPORTANT: physics.currentIndex reads physics.offset ($state) — must be untracked to prevent
+	// this effect from re-running on every pointer-move or animation tick.
+	$effect(() => {
+		const v = value;
+		if (v === undefined) return;
+		const idx = options.findIndex((o) => o.value === v);
+		if (idx >= 0 && idx !== untrack(() => physics.currentIndex)) {
+			physics.cancelAnimation();
+			physics.animateTo(idx);
+		}
+	});
+
+	// Helper: animate the wheel to a given index and update state
+	function setValue(index: number) {
+		physics.animateTo(index);
+	}
+
+	// Keyboard navigation (per RESEARCH Pattern 5)
+	function handleKeydown(e: KeyboardEvent) {
+		const currentIdx = selectedIndex >= 0 ? selectedIndex : 0;
+		switch (e.key) {
+			case 'ArrowDown': {
+				e.preventDefault();
+				if (infinite) {
+					let next = currentIdx + 1;
+					let guard = 0;
+					while (options[wrapIndex(next, options.length)]?.disabled && guard < options.length) {
+						next++;
+						guard++;
+					}
+					if (guard < options.length) {
+						// Animate to the extended index (ghost position) for correct direction.
+						// onSnap will normalize back to [0, N-1] via wrapIndex + jumpTo.
+						setValue(next);
+					}
+				} else {
+					let next = currentIdx + 1;
+					while (next < options.length && options[next].disabled) next++;
+					if (next < options.length) setValue(next);
+				}
+				break;
+			}
+			case 'ArrowUp': {
+				e.preventDefault();
+				if (infinite) {
+					let next = currentIdx - 1;
+					let guard = 0;
+					while (options[wrapIndex(next, options.length)]?.disabled && guard < options.length) {
+						next--;
+						guard++;
+					}
+					if (guard < options.length) {
+						// Animate to the extended index (ghost position) for correct direction.
+						setValue(next);
+					}
+				} else {
+					let next = currentIdx - 1;
+					while (next >= 0 && options[next].disabled) next--;
+					if (next >= 0) setValue(next);
+				}
+				break;
+			}
+			case 'Home': {
+				e.preventDefault();
+				const first = options.findIndex((o) => !o.disabled);
+				if (first !== -1) setValue(first);
+				break;
+			}
+			case 'End': {
+				e.preventDefault();
+				for (let i = options.length - 1; i >= 0; i--) {
+					if (!options[i].disabled) {
+						setValue(i);
+						break;
+					}
+				}
+				break;
+			}
+			default: {
+				const result = typeahead.search(e.key, options, currentIdx);
+				if (result !== -1) setValue(result);
+			}
+		}
+	}
+
+	// Pointer event handlers (Pattern 2: Pointer Capture for reliable drag tracking)
+	function onPointerDown(e: PointerEvent) {
+		console.log(
+			'[onPointerDown] type=',
+			e.type,
+			'currentTarget=',
+			e.currentTarget,
+			'target=',
+			e.target,
+		);
+		const el = e.currentTarget as HTMLElement;
+		el.setPointerCapture(e.pointerId);
+		console.log(
+			'[onPointerDown] setPointerCapture called, hasCapture=',
+			el.hasPointerCapture(e.pointerId),
+		);
+		physics.startDrag(e.clientY);
+	}
+
+	function onPointerMove(e: PointerEvent) {
+		physics.moveDrag(e.clientY);
+	}
+
+	function onPointerUp(e: PointerEvent) {
+		console.log(
+			'[onPointerUp] type=',
+			e.type,
+			'currentTarget=',
+			e.currentTarget,
+			'target=',
+			e.target,
+			'clientY=',
+			e.clientY,
+		);
+		(e.currentTarget as HTMLElement).releasePointerCapture(e.pointerId);
+		physics.endDrag();
+	}
+
+	// Wheel/trackpad scroll handler — one item per scroll event
+	function onWheel(e: WheelEvent) {
+		e.preventDefault();
+		physics.handleWheel(e.deltaY);
+	}
+</script>
+
+<div
+	data-swp-wrapper
+	data-swp-cylindrical={cylindrical ? 'true' : undefined}
+	class={classNames?.wrapper ?? undefined}
+	style:height="{visibleCount * optionItemHeight}px"
+	style:overflow="hidden"
+	style:position="relative"
+	tabindex="0"
+	role="listbox"
+	onpointerdown={onPointerDown}
+	onpointermove={onPointerMove}
+	onpointerup={onPointerUp}
+	onpointercancel={onPointerUp}
+	onwheel={onWheel}
+	onkeydown={handleKeydown}
+>
+	<!-- Selection overlay — absolutely positioned center row indicator -->
+	<div
+		data-swp-selection
+		class={classNames?.selection ?? undefined}
+		style:position="absolute"
+		style:top="{Math.floor(visibleCount / 2) * optionItemHeight}px"
+		style:left="0"
+		style:right="0"
+		style:height="{optionItemHeight}px"
+		style:pointer-events="none"
+	></div>
+
+	<!-- Options container — translated by physics offset -->
+	<div style:transform="translateY({physics.offset}px)">
+		{#if infinite}
+			<!-- Before-ghosts: reversed so options[N-1] appears just above real section (Pitfall 3) -->
+			{#each [...options].reverse() as option, g}
+				{@const scale = cylindrical
+					? cylindricalScaleY(g - options.length, physics.offset, optionItemHeight, visibleCount)
+					: undefined}
+				<div
+					data-swp-option
+					data-swp-disabled={option.disabled ? 'true' : undefined}
+					class={classNames?.option ?? undefined}
+					style:height="{optionItemHeight}px"
+					style:display="flex"
+					style:align-items="center"
+					style:justify-content="center"
+					style:transform={scale !== undefined ? `scaleY(${scale})` : undefined}
+					style:opacity={scale}
+					role="option"
+					aria-selected={false}
+				>
+					<span data-swp-option-text class={classNames?.optionText ?? undefined}>
+						{option.label}
+					</span>
+				</div>
+			{/each}
+		{/if}
+
+		<!-- Real items section -->
+		{#each options as option, i}
+			{@const scale = cylindrical
+				? cylindricalScaleY(i, physics.offset, optionItemHeight, visibleCount)
+				: undefined}
+			<div
+				data-swp-option
+				data-swp-selected={selectedIndex === i ? 'true' : undefined}
+				data-swp-disabled={option.disabled ? 'true' : undefined}
+				class={classNames?.option ?? undefined}
+				style:height="{optionItemHeight}px"
+				style:display="flex"
+				style:align-items="center"
+				style:justify-content="center"
+				style:transform={scale !== undefined ? `scaleY(${scale})` : undefined}
+				style:opacity={scale}
+				role="option"
+				aria-selected={selectedIndex === i}
+			>
+				<span data-swp-option-text class={classNames?.optionText ?? undefined}>
+					{option.label}
+				</span>
+			</div>
+		{/each}
+
+		{#if infinite}
+			<!-- After-ghosts: same order as real items -->
+			{#each options as option, j}
+				{@const scale = cylindrical
+					? cylindricalScaleY(options.length + j, physics.offset, optionItemHeight, visibleCount)
+					: undefined}
+				<div
+					data-swp-option
+					data-swp-disabled={option.disabled ? 'true' : undefined}
+					class={classNames?.option ?? undefined}
+					style:height="{optionItemHeight}px"
+					style:display="flex"
+					style:align-items="center"
+					style:justify-content="center"
+					style:transform={scale !== undefined ? `scaleY(${scale})` : undefined}
+					style:opacity={scale}
+					role="option"
+					aria-selected={false}
+				>
+					<span data-swp-option-text class={classNames?.optionText ?? undefined}>
+						{option.label}
+					</span>
+				</div>
+			{/each}
+		{/if}
+	</div>
+</div>

package/dist/WheelPicker.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { WheelPickerProps } from './types.js';
+declare const WheelPicker: import("svelte").Component<WheelPickerProps<string>, {}, "">;
+type WheelPicker = ReturnType<typeof WheelPicker>;
+export default WheelPicker;

package/dist/WheelPickerWrapper.svelte

@@ -0,0 +1,10 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import type { WheelPickerWrapperProps } from './types.js';
+
+	let { classNames, children }: WheelPickerWrapperProps & { children?: Snippet } = $props();
+</script>
+
+<div data-swp-group class={classNames?.group ?? undefined}>
+	{@render children?.()}
+</div>

package/dist/WheelPickerWrapper.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { Snippet } from 'svelte';
+import type { WheelPickerWrapperProps } from './types.js';
+type $$ComponentProps = WheelPickerWrapperProps & {
+    children?: Snippet;
+};
+declare const WheelPickerWrapper: import("svelte").Component<$$ComponentProps, {}, "">;
+type WheelPickerWrapper = ReturnType<typeof WheelPickerWrapper>;
+export default WheelPickerWrapper;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { default as WheelPicker } from './WheelPicker.svelte';
+export { default as WheelPickerWrapper } from './WheelPickerWrapper.svelte';
+export type { WheelPickerOption, WheelPickerProps, WheelPickerClassNames, WheelPickerWrapperProps, WheelPickerWrapperClassNames, } from './types.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { default as WheelPicker } from './WheelPicker.svelte';
+export { default as WheelPickerWrapper } from './WheelPickerWrapper.svelte';