@uinstinct/svelte-wheel-picker 0.1.0

package/dist/wheel-physics-utils.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Pure physics utility functions for the WheelPicker.
+ *
+ * All functions here are side-effect-free and do not reference DOM or Svelte
+ * reactivity — they can be unit-tested in a plain Node environment.
+ *
+ * Physics constants are copied from @ncdai/react-wheel-picker v1.2.2 to
+ * achieve UX parity with the React version.
+ */
+/** Boundary resistance factor — how much drag is applied when pulling past the ends. */
+export declare const RESISTANCE = 0.3;
+/** Maximum scroll velocity in items/second. */
+export declare const MAX_VELOCITY = 30;
+/** Default drag sensitivity (pointer drag delta multiplier for inertia). */
+export declare const DEFAULT_DRAG_SENSITIVITY = 3;
+/** Default scroll sensitivity (wheel event multiplier for snap animation duration). */
+export declare const DEFAULT_SCROLL_SENSITIVITY = 5;
+/** Default height in pixels of each option row. */
+export declare const DEFAULT_ITEM_HEIGHT = 30;
+/** Default number of visible option rows. */
+export declare const DEFAULT_VISIBLE_COUNT = 5;
+/** Deceleration constant used in snap-back calculations. */
+export declare const SNAP_BACK_DECELERATION = 10;
+/** Minimum scaleY for cylindrical mode to prevent items collapsing to zero height. */
+export declare const MIN_CYLINDRICAL_SCALE = 0.1;
+/**
+ * Cubic ease-out easing function.
+ * Matches the React version's easing: `Math.pow(p - 1, 3) + 1`
+ *
+ * @param p - Progress from 0 to 1
+ * @returns Eased progress from 0 to 1
+ */
+export declare function easeOutCubic(p: number): number;
+/**
+ * Converts a selected option index to a translateY offset value.
+ *
+ * The center slot is at `Math.floor(visibleCount / 2) * itemHeight`.
+ * Index 0 sits at the center slot (largest positive offset).
+ *
+ * @param index - The option index (0-based)
+ * @param itemHeight - Height in pixels of each option row
+ * @param visibleCount - Number of visible rows
+ * @returns The translateY offset value in pixels
+ */
+export declare function indexToOffset(index: number, itemHeight: number, visibleCount: number): number;
+/**
+ * Converts a translateY offset value to the nearest option index.
+ * Inverse of `indexToOffset`.
+ *
+ * @param offset - Current translateY offset in pixels
+ * @param itemHeight - Height in pixels of each option row
+ * @param visibleCount - Number of visible rows
+ * @returns The nearest option index
+ */
+export declare function offsetToIndex(offset: number, itemHeight: number, visibleCount: number): number;
+/**
+ * Clamps an index to the valid range [0, optionsLength - 1].
+ *
+ * @param index - The index to clamp
+ * @param optionsLength - Total number of options
+ * @returns The clamped index
+ */
+export declare function clampIndex(index: number, optionsLength: number): number;
+/**
+ * Wraps an index into the valid range [0, optionsLength) using modulo.
+ * Handles negative indices correctly (JavaScript modulo returns negative for negative inputs).
+ *
+ * Formula from @ncdai/react-wheel-picker v1.2.2: ((index % n) + n) % n
+ *
+ * @param index - The index to wrap (may be negative or >= optionsLength)
+ * @param optionsLength - Total number of options
+ * @returns The wrapped index in [0, optionsLength - 1]
+ */
+export declare function wrapIndex(index: number, optionsLength: number): number;
+/**
+ * Finds the nearest enabled option from a target index.
+ *
+ * Walks outward in both directions (lower-delta first), returning the nearest
+ * enabled option. If all options are disabled, returns the original targetIndex.
+ *
+ * @param targetIndex - The desired index
+ * @param options - Array of options (only `disabled` field is used)
+ * @returns The nearest enabled index
+ */
+export declare function snapToNearestEnabled(targetIndex: number, options: Array<{
+    disabled?: boolean;
+}>): number;
+/**
+ * Calculates the scroll velocity from recent pointer positions.
+ *
+ * Uses the last two entries in yList to compute items/second.
+ * Result is clamped to [-MAX_VELOCITY, MAX_VELOCITY].
+ *
+ * @param yList - Array of [clientY, timestamp] tuples (newest last)
+ * @param itemHeight - Height in pixels of each option row
+ * @returns Velocity in items/second (positive = scrolling down)
+ */
+export declare function calculateVelocity(yList: Array<[number, number]>, itemHeight: number): number;
+/**
+ * Computes the inertia overshoot snap target index.
+ *
+ * Based on: `baseDeceleration = dragSensitivity * 10`,
+ * `overshoot = 0.5 * v^2 / baseDeceleration`,
+ * `rawTarget = currentIndex + sign(v) * overshoot`
+ *
+ * @param currentIndexFromOffset - The index at current offset
+ * @param velocity - Current velocity in items/second
+ * @param dragSensitivity - Drag sensitivity (affects deceleration)
+ * @returns The rounded target index after inertia overshoot
+ */
+export declare function computeSnapTarget(currentIndexFromOffset: number, velocity: number, dragSensitivity: number): number;
+/**
+ * Computes the duration of a snap animation in seconds.
+ *
+ * Formula: `Math.sqrt(|distance| / scrollSensitivity)`
+ * Clamped to [0.1, 0.6] seconds.
+ *
+ * @param distance - Distance in index steps to travel
+ * @param scrollSensitivity - Scroll sensitivity (affects duration)
+ * @returns Animation duration in seconds
+ */
+export declare function computeAnimationDuration(distance: number, scrollSensitivity: number): number;
+/**
+ * Computes per-item scaleY (and opacity) for cylindrical drum mode.
+ *
+ * Derived from the cosine projection of a virtual cylinder: an item at angle
+ * theta from front-face has projected height cos(theta) * fullHeight.
+ * Maps floor(visibleCount/2) slots from center to PI/2, auto-scaling with visibleCount.
+ *
+ * slotIndex assignments:
+ *   - Non-infinite real item i:    slotIndex = i
+ *   - Infinite before-ghost g:     slotIndex = g - options.length
+ *   - Infinite after-ghost j:      slotIndex = options.length + j
+ *
+ * @param slotIndex - The item's position in the combined DOM list
+ * @param offset    - Current physics.offset (translateY px)
+ * @param itemHeight - Height of each option row in pixels
+ * @param visibleCount - Number of visible rows (must be odd)
+ * @returns scaleY in range [MIN_CYLINDRICAL_SCALE, 1.0]
+ */
+export declare function cylindricalScaleY(slotIndex: number, offset: number, itemHeight: number, visibleCount: number): number;

package/dist/wheel-physics-utils.js

@@ -0,0 +1,198 @@
+/**
+ * Pure physics utility functions for the WheelPicker.
+ *
+ * All functions here are side-effect-free and do not reference DOM or Svelte
+ * reactivity — they can be unit-tested in a plain Node environment.
+ *
+ * Physics constants are copied from @ncdai/react-wheel-picker v1.2.2 to
+ * achieve UX parity with the React version.
+ */
+// ---------------------------------------------------------------------------
+// Physics constants (from React source v1.2.2)
+// ---------------------------------------------------------------------------
+/** Boundary resistance factor — how much drag is applied when pulling past the ends. */
+export const RESISTANCE = 0.3;
+/** Maximum scroll velocity in items/second. */
+export const MAX_VELOCITY = 30;
+/** Default drag sensitivity (pointer drag delta multiplier for inertia). */
+export const DEFAULT_DRAG_SENSITIVITY = 3;
+/** Default scroll sensitivity (wheel event multiplier for snap animation duration). */
+export const DEFAULT_SCROLL_SENSITIVITY = 5;
+/** Default height in pixels of each option row. */
+export const DEFAULT_ITEM_HEIGHT = 30;
+/** Default number of visible option rows. */
+export const DEFAULT_VISIBLE_COUNT = 5;
+/** Deceleration constant used in snap-back calculations. */
+export const SNAP_BACK_DECELERATION = 10;
+/** Minimum scaleY for cylindrical mode to prevent items collapsing to zero height. */
+export const MIN_CYLINDRICAL_SCALE = 0.1;
+// ---------------------------------------------------------------------------
+// Pure physics functions
+// ---------------------------------------------------------------------------
+/**
+ * Cubic ease-out easing function.
+ * Matches the React version's easing: `Math.pow(p - 1, 3) + 1`
+ *
+ * @param p - Progress from 0 to 1
+ * @returns Eased progress from 0 to 1
+ */
+export function easeOutCubic(p) {
+    return Math.pow(p - 1, 3) + 1;
+}
+/**
+ * Converts a selected option index to a translateY offset value.
+ *
+ * The center slot is at `Math.floor(visibleCount / 2) * itemHeight`.
+ * Index 0 sits at the center slot (largest positive offset).
+ *
+ * @param index - The option index (0-based)
+ * @param itemHeight - Height in pixels of each option row
+ * @param visibleCount - Number of visible rows
+ * @returns The translateY offset value in pixels
+ */
+export function indexToOffset(index, itemHeight, visibleCount) {
+    return Math.floor(visibleCount / 2) * itemHeight - index * itemHeight;
+}
+/**
+ * Converts a translateY offset value to the nearest option index.
+ * Inverse of `indexToOffset`.
+ *
+ * @param offset - Current translateY offset in pixels
+ * @param itemHeight - Height in pixels of each option row
+ * @param visibleCount - Number of visible rows
+ * @returns The nearest option index
+ */
+export function offsetToIndex(offset, itemHeight, visibleCount) {
+    return Math.round((Math.floor(visibleCount / 2) * itemHeight - offset) / itemHeight);
+}
+/**
+ * Clamps an index to the valid range [0, optionsLength - 1].
+ *
+ * @param index - The index to clamp
+ * @param optionsLength - Total number of options
+ * @returns The clamped index
+ */
+export function clampIndex(index, optionsLength) {
+    return Math.max(0, Math.min(index, optionsLength - 1));
+}
+/**
+ * Wraps an index into the valid range [0, optionsLength) using modulo.
+ * Handles negative indices correctly (JavaScript modulo returns negative for negative inputs).
+ *
+ * Formula from @ncdai/react-wheel-picker v1.2.2: ((index % n) + n) % n
+ *
+ * @param index - The index to wrap (may be negative or >= optionsLength)
+ * @param optionsLength - Total number of options
+ * @returns The wrapped index in [0, optionsLength - 1]
+ */
+export function wrapIndex(index, optionsLength) {
+    return ((index % optionsLength) + optionsLength) % optionsLength;
+}
+/**
+ * Finds the nearest enabled option from a target index.
+ *
+ * Walks outward in both directions (lower-delta first), returning the nearest
+ * enabled option. If all options are disabled, returns the original targetIndex.
+ *
+ * @param targetIndex - The desired index
+ * @param options - Array of options (only `disabled` field is used)
+ * @returns The nearest enabled index
+ */
+export function snapToNearestEnabled(targetIndex, options) {
+    if (!options[targetIndex]?.disabled) {
+        return targetIndex;
+    }
+    // Walk outward from targetIndex to find the nearest enabled option
+    for (let delta = 1; delta < options.length; delta++) {
+        const lower = targetIndex - delta;
+        const upper = targetIndex + delta;
+        if (lower >= 0 && !options[lower]?.disabled) {
+            return lower;
+        }
+        if (upper < options.length && !options[upper]?.disabled) {
+            return upper;
+        }
+    }
+    // All options are disabled — return original target
+    return targetIndex;
+}
+/**
+ * Calculates the scroll velocity from recent pointer positions.
+ *
+ * Uses the last two entries in yList to compute items/second.
+ * Result is clamped to [-MAX_VELOCITY, MAX_VELOCITY].
+ *
+ * @param yList - Array of [clientY, timestamp] tuples (newest last)
+ * @param itemHeight - Height in pixels of each option row
+ * @returns Velocity in items/second (positive = scrolling down)
+ */
+export function calculateVelocity(yList, itemHeight) {
+    if (yList.length < 2) {
+        return 0;
+    }
+    const [y1, t1] = yList[yList.length - 2];
+    const [y2, t2] = yList[yList.length - 1];
+    if (t2 === t1) {
+        return 0;
+    }
+    const velocity = ((y2 - y1) / itemHeight) * (1000 / (t2 - t1));
+    const clamped = Math.max(-MAX_VELOCITY, Math.min(MAX_VELOCITY, velocity));
+    return clamped;
+}
+/**
+ * Computes the inertia overshoot snap target index.
+ *
+ * Based on: `baseDeceleration = dragSensitivity * 10`,
+ * `overshoot = 0.5 * v^2 / baseDeceleration`,
+ * `rawTarget = currentIndex + sign(v) * overshoot`
+ *
+ * @param currentIndexFromOffset - The index at current offset
+ * @param velocity - Current velocity in items/second
+ * @param dragSensitivity - Drag sensitivity (affects deceleration)
+ * @returns The rounded target index after inertia overshoot
+ */
+export function computeSnapTarget(currentIndexFromOffset, velocity, dragSensitivity) {
+    const baseDeceleration = dragSensitivity * 10;
+    const overshoot = (0.5 * velocity * velocity) / baseDeceleration;
+    // Velocity sign is inverted relative to index direction:
+    // drag down (positive velocity) increases offset → decreases index → overshoot toward lower index.
+    const rawTarget = currentIndexFromOffset - Math.sign(velocity) * overshoot;
+    return Math.round(rawTarget);
+}
+/**
+ * Computes the duration of a snap animation in seconds.
+ *
+ * Formula: `Math.sqrt(|distance| / scrollSensitivity)`
+ * Clamped to [0.1, 0.6] seconds.
+ *
+ * @param distance - Distance in index steps to travel
+ * @param scrollSensitivity - Scroll sensitivity (affects duration)
+ * @returns Animation duration in seconds
+ */
+export function computeAnimationDuration(distance, scrollSensitivity) {
+    const raw = Math.sqrt(Math.abs(distance) / scrollSensitivity);
+    return Math.max(0.1, Math.min(0.6, raw));
+}
+/**
+ * Computes per-item scaleY (and opacity) for cylindrical drum mode.
+ *
+ * Derived from the cosine projection of a virtual cylinder: an item at angle
+ * theta from front-face has projected height cos(theta) * fullHeight.
+ * Maps floor(visibleCount/2) slots from center to PI/2, auto-scaling with visibleCount.
+ *
+ * slotIndex assignments:
+ *   - Non-infinite real item i:    slotIndex = i
+ *   - Infinite before-ghost g:     slotIndex = g - options.length
+ *   - Infinite after-ghost j:      slotIndex = options.length + j
+ *
+ * @param slotIndex - The item's position in the combined DOM list
+ * @param offset    - Current physics.offset (translateY px)
+ * @param itemHeight - Height of each option row in pixels
+ * @param visibleCount - Number of visible rows (must be odd)
+ * @returns scaleY in range [MIN_CYLINDRICAL_SCALE, 1.0]
+ */
+export function cylindricalScaleY(slotIndex, offset, itemHeight, visibleCount) {
+    const dist = slotIndex + offset / itemHeight - Math.floor(visibleCount / 2);
+    const angle = (dist * Math.PI) / visibleCount;
+    return Math.max(MIN_CYLINDRICAL_SCALE, Math.cos(angle));
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@uinstinct/svelte-wheel-picker",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "iOS-style wheel picker for Svelte 5 with inertia scrolling, infinite loop, and keyboard navigation",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "svelte": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "svelte": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "svelte": "^5.0.0"
+  },
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build",
+    "package": "svelte-package && rm -rf dist/__tests__ && rm -f dist/*.test.js dist/*.test.d.ts && publint",
+    "prepack": "npm run package",
+    "test": "PLAYWRIGHT_BROWSERS_PATH=.playwright vitest run",
+    "test:watch": "PLAYWRIGHT_BROWSERS_PATH=.playwright vitest",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "registry:build": "shadcn-svelte registry build"
+  },
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "@sveltejs/adapter-vercel": "^6.3.3",
+    "@sveltejs/kit": "2.55.0",
+    "@sveltejs/package": "2.5.7",
+    "@sveltejs/vite-plugin-svelte": "7.0.0",
+    "@vitest/browser-playwright": "4.1.0",
+    "eslint": "10.1.0",
+    "eslint-plugin-svelte": "3.16.0",
+    "globals": "17.4.0",
+    "prettier": "3.8.1",
+    "prettier-plugin-svelte": "3.5.1",
+    "publint": "0.3.18",
+    "shadcn-svelte": "1.2.3",
+    "svelte": "5.54.1",
+    "svelte-eslint-parser": "1.6.0",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.57.1",
+    "vite": "8.0.1",
+    "vitest": "4.1.0",
+    "vitest-browser-svelte": "2.1.0"
+  }
+}