@marianmeres/stuic 3.118.0 → 3.119.0

package/dist/components/WheelPicker/README.md

@@ -0,0 +1,110 @@
+# WheelPicker
+
+iOS-style scrolling wheel / drum picker (à la `UIPickerView`) for selecting a value from a
+list — hours, minutes, days, units, anything. Supports **infinite looping** (scroll past the
+last option and the first reappears seamlessly, e.g. minutes 59 → 00).
+
+Built entirely on native scroll + CSS scroll-snap, so momentum/inertia feel native on touch
+devices for free — no hand-rolled physics. Looping works by silently teleporting the scroll
+position by a whole number of option-cycles **only at rest**, which is provably invisible
+(the centered value is identical before and after).
+
+## Usage
+
+```svelte
+<script lang="ts">
+	import { WheelPicker } from "@marianmeres/stuic";
+
+	let hour = $state(9);
+	const hours = Array.from({ length: 24 }, (_, i) => i);
+</script>
+
+<!-- looping wheel of 0..23 -->
+<WheelPicker options={hours} bind:value={hour} loop label="Hour" />
+```
+
+A simple time picker is three wheels side by side:
+
+```svelte
+<script lang="ts">
+	let h = $state(9),
+		m = $state(30);
+	const range = (n: number) => Array.from({ length: n }, (_, i) => i);
+	const pad = (n: number) => ({ label: String(n).padStart(2, "0"), value: n });
+</script>
+
+<div style="display:flex; gap:0.5rem">
+	<WheelPicker options={range(24).map(pad)} bind:value={h} loop label="Hour" />
+	<WheelPicker options={range(60).map(pad)} bind:value={m} loop label="Minute" />
+</div>
+```
+
+Options may be bare primitives or full objects:
+
+```svelte
+<WheelPicker
+	options={[
+		{ label: "Small", value: "s" },
+		{ label: "Medium", value: "m" },
+		{ label: "Large", value: "l", disabled: true },
+	]}
+	bind:value={size}
+/>
+```
+
+## Props
+
+| Prop                | Type                                                 | Default | Description                                                                 |
+| ------------------- | ---------------------------------------------------- | ------- | --------------------------------------------------------------------------- |
+| `options`           | `(string \| number \| WheelPickerOption)[]`          | —       | Options to scroll through. Primitives become `{ label, value }`.            |
+| `value`             | `T`                                                  | —       | **Bindable** selected value (the chosen option's `value`). Primary binding. |
+| `index`             | `number`                                             | —       | **Bindable** selected real index. Alternative/companion to `value`.         |
+| `loop`              | `boolean`                                            | `false` | Infinite wrap (59 → 00). When `false`, clamps at the ends.                  |
+| `itemHeight`        | `number`                                             | `36`    | Row height in px. Prefer an integer.                                        |
+| `visibleCount`      | `number`                                             | `5`     | How many rows are visible (forced odd, for an exact center).                |
+| `tiles`             | `number`                                             | `3`     | Loop buffer copies (a floor; auto-grown to guarantee fling runway).         |
+| `keyboard`          | `boolean`                                            | `true`  | Enable Arrow/Page/Home/End navigation.                                      |
+| `announce`          | `boolean`                                            | `true`  | Announce the committed label via an `aria-live` region.                     |
+| `label`             | `string`                                             | —       | Accessible name for the listbox. **Strongly recommended.**                  |
+| `onchange`          | `(option: WheelPickerOption, index: number) => void` | —       | Fired when the selection **settles** on a new option (not during a fling).  |
+| `unstyled`          | `boolean`                                            | `false` | Skip default styling.                                                       |
+| `class`             | `string`                                             | —       | Additional CSS classes on the root.                                         |
+| `classItem`         | `string`                                             | —       | Extra classes on each row.                                                  |
+| `classItemSelected` | `string`                                             | —       | Extra classes on the selected row.                                          |
+| `classBand`         | `string`                                             | —       | Extra classes on the center selection band.                                 |
+| `el`                | `HTMLDivElement`                                     | —       | **Bindable** root element ref.                                              |
+| `renderItem`        | `Snippet<[{ option, index, selected }]>`             | —       | Custom row renderer (alternative to the plain label).                       |
+
+`WheelPickerOption` is `{ label: string; value: string \| number; disabled?: boolean }`.
+
+## Behavior
+
+- **Native momentum**: touch fling, trackpad, mouse wheel and scrollbar all drive the native
+  scroll; CSS scroll-snap settles the nearest row under the center band. No custom physics.
+- **Commit on settle**: `value`/`index`/`onchange` update only when scrolling comes to rest,
+  not on every intermediate frame of a fling.
+- **Infinite loop** (`loop`): options repeat in both directions. The buffer is recentered by a
+  whole-cycle scroll teleport **only at rest**, so the seam is never visible and momentum is
+  never interrupted (important on iOS Safari, where `scrollend` is unavailable before 26.2 —
+  so the commit/settle path never depends on it).
+- **Keyboard**: ↑/↓ step one, PageUp/PageDown step `visibleCount`, Home/End jump to the
+  first/last option (wrapping when `loop`). Disabled options are skipped.
+- **Programmatic set**: changing the bound `value` (e.g. a ticking clock) scrolls the wheel to
+  match — deferred while the user is actively scrolling so it never yanks mid-gesture.
+- **Reduced motion**: respects `prefers-reduced-motion` — programmatic scrolls jump instantly.
+- **Accessibility**: the scroll viewport is a `role="listbox"` with `aria-activedescendant`
+  tracking the selected option; in loop mode only the canonical copy of each option carries
+  `role="option"` (duplicate tiles are `aria-hidden`), so screen readers never hear repeats.
+
+## CSS Tokens
+
+Prefix: `--stuic-wheel-picker-*`
+
+`item-height`, `visible-count`, `min-width`, `font-size`, `font-family`, `color`,
+`color-selected`, `font-weight-selected`, `band-bg`, `band-border-color`, `band-border-width`,
+`fade` (0–1 edge-fade strength), `ring-width`, `ring-color`, plus optional `radius`, `bg`,
+`transition` overrides.
+
+> **Note:** set `item-height` / `visible-count` via the **props**, not CSS — the component
+> writes them inline because the same numbers drive the scroll math. The shared structural
+> token `--stuic-radius-container` is used as the radius fallback.

package/dist/components/WheelPicker/WheelPicker.svelte

@@ -0,0 +1,496 @@
+<script lang="ts" module>
+	import type { HTMLAttributes } from "svelte/elements";
+	import type { Snippet } from "svelte";
+	import type { WheelPickerOption, WheelPickerOptionInput } from "./utils.js";
+
+	export type { WheelPickerOption, WheelPickerOptionInput } from "./utils.js";
+
+	export interface Props<T = string | number> extends Omit<
+		HTMLAttributes<HTMLDivElement>,
+		"children" | "onchange"
+	> {
+		/** Options to scroll through. Bare strings/numbers become `{ label, value }`; objects pass through. */
+		options: WheelPickerOptionInput<T>[];
+
+		/** Bindable selected value (the chosen option's `value`). Primary binding. */
+		value?: T;
+
+		/** Bindable selected real index (modulo-reduced). Alternative/companion to `value`. */
+		index?: number;
+
+		/** Infinite wrap (59 → 00). Default false (single copy, clamped at the ends). */
+		loop?: boolean;
+
+		/** Row height in px. Prefer an integer to avoid cross-copy drift. Default 36. */
+		itemHeight?: number;
+
+		/** How many rows are visible (forced odd, so there's an exact center). Default 5. */
+		visibleCount?: number;
+
+		/** Loop buffer copies (floor; auto-grown to guarantee fling runway). Default 3. */
+		tiles?: number;
+
+		/** Enable keyboard navigation (Arrow/Page/Home/End). Default true. */
+		keyboard?: boolean;
+
+		/** Announce the committed label via an aria-live region. Default true. */
+		announce?: boolean;
+
+		/** Accessible name for the listbox. Strongly recommended. */
+		label?: string;
+
+		/** Fired when the selection settles on a new option (not during a fling). */
+		onchange?: (option: WheelPickerOption<T>, index: number) => void;
+
+		/** Skip default styling. */
+		unstyled?: boolean;
+		/** Additional CSS classes on the root. */
+		class?: string;
+		/** Extra classes on each row. */
+		classItem?: string;
+		/** Extra classes on the selected row. */
+		classItemSelected?: string;
+		/** Extra classes on the center selection band. */
+		classBand?: string;
+		/** Bindable root element ref. */
+		el?: HTMLDivElement;
+		/** Custom row renderer (alternative to the plain label). */
+		renderItem?: Snippet<
+			[{ option: WheelPickerOption<T>; index: number; selected: boolean }]
+		>;
+	}
+
+	// Per-instance id base for aria wiring (option ids / activedescendant).
+	let _uid = 0;
+</script>
+
+<script lang="ts" generics="T = string | number">
+	import { untrack } from "svelte";
+	import { twMerge } from "../../utils/tw-merge.js";
+	import { prefersReducedMotion } from "../../utils/prefers-reduced-motion.svelte.js";
+	import {
+		normalizeOptions,
+		forceOdd,
+		clamp,
+		mod,
+		centerGlobalIndex,
+		realIndexFromGlobal,
+		resolveTiles,
+		homeBase,
+		driftTiles,
+		nextEnabledIndex,
+		indexOfValue,
+		nearestGlobalIndex,
+	} from "./utils.js";
+
+	let {
+		options,
+		value = $bindable(),
+		index = $bindable(),
+		loop = false,
+		itemHeight = 36,
+		visibleCount = 5,
+		tiles: tilesProp = 3,
+		keyboard = true,
+		announce = true,
+		label,
+		onchange,
+		unstyled = false,
+		class: classProp,
+		classItem,
+		classItemSelected,
+		classBand,
+		el = $bindable(),
+		renderItem,
+		// pulled out of `rest` so they name the listbox (the semantic control), not the wrapper
+		"aria-label": ariaLabel,
+		"aria-labelledby": ariaLabelledby,
+		...rest
+	}: Props<T> = $props();
+
+	const instanceId = `stuic-wp-${_uid++}`;
+	const optionId = (realIndex: number) => `${instanceId}-opt-${realIndex}`;
+
+	const reducedMotion = prefersReducedMotion();
+
+	// 120ms of scroll silence ≈ at rest. The PRIMARY commit path: `scrollend` is
+	// absent on iOS Safari < 26.2, so we never depend on it (we also listen for it
+	// as a crisp optimization when available).
+	const IDLE_MS = 120;
+
+	// ---- derived geometry (fully deterministic from props — no measurement) ----
+	const opts = $derived(normalizeOptions<T>(options));
+	const n = $derived(opts.length);
+	const vCount = $derived(forceOdd(visibleCount));
+	const centerPad = $derived(((vCount - 1) / 2) * itemHeight);
+	const containerH = $derived(vCount * itemHeight);
+	const tiles = $derived(resolveTiles(tilesProp, n, itemHeight, containerH, loop));
+	const tilePx = $derived(n * itemHeight);
+	const homeTile = $derived(Math.floor(tiles / 2));
+	const homeBaseVal = $derived(homeBase(tiles, n));
+
+	// Rendered rows: `tiles` copies when looping, one otherwise. Only the home tile
+	// carries the real listbox semantics; every other copy is aria-hidden so screen
+	// readers never encounter N duplicates of each value.
+	const rows = $derived.by(() => {
+		const out: {
+			gi: number;
+			realIndex: number;
+			isHome: boolean;
+			option: WheelPickerOption<T>;
+		}[] = [];
+		const total = tiles * n;
+		for (let gi = 0; gi < total; gi++) {
+			const realIndex = ((gi % n) + n) % n;
+			out.push({
+				gi,
+				realIndex,
+				isHome: loop ? Math.floor(gi / n) === homeTile : true,
+				option: opts[realIndex],
+			});
+		}
+		return out;
+	});
+
+	// committed selection (initialized once from value/index)
+	function initialIndex(): number {
+		const o = normalizeOptions<T>(options);
+		if (o.length === 0) return 0;
+		if (value !== undefined) {
+			const i = indexOfValue(o, value);
+			if (i >= 0) return i;
+		}
+		if (index !== undefined && index >= 0) return Math.min(index, o.length - 1);
+		return 0;
+	}
+	let selectedIndex = $state(initialIndex());
+
+	let scrollEl: HTMLDivElement | undefined = $state();
+	let announceText = $state("");
+	// Flipped each announce so the live-region text always differs (forces a re-announce
+	// even when two consecutive selections share the same label).
+	let announceNonce = false;
+
+	// True while the USER is actively interacting (pointer/touch/wheel) until the next
+	// settle — used to defer external `value` changes so we never yank the wheel out from
+	// under a drag. Driven by INPUT events (not scroll events), so our own programmatic
+	// scrolls (init/teleport/keyboard/value-set) never spuriously trip it.
+	let userScrolling = false;
+	// A smooth programmatic scroll is animating; coalesces rapid value changes to instant.
+	let pendingSmooth = false;
+	let idleTimer: ReturnType<typeof setTimeout> | undefined;
+	let lastScrollTop = 0;
+	let lastDir: 1 | -1 = 1;
+	// $state so the reconcile effect re-runs when mount flips it (cheap early-return),
+	// instead of depending on effect source-order.
+	let mounted = $state(false);
+
+	const selectedOptionId = $derived(n > 0 ? optionId(selectedIndex) : undefined);
+
+	// Genuine user intent to scroll. armIdle() guarantees a settle() that clears the flag
+	// even for a tap/click that doesn't actually move the scroll position.
+	function markUserScrolling() {
+		userScrolling = true;
+		armIdle();
+	}
+
+	/** Position scrollTop so `realIndex` sits centered (instant). */
+	function anchorTo(realIndex: number) {
+		if (!scrollEl || n === 0) return;
+		const gi = loop ? homeBaseVal + realIndex : realIndex;
+		scrollEl.scrollTop = gi * itemHeight;
+		lastScrollTop = scrollEl.scrollTop;
+	}
+
+	/** Commit a new real index outward (value/index/onchange/announce). No-op if unchanged. */
+	function commit(realIndex: number) {
+		const opt = opts[realIndex];
+		if (!opt) return;
+		const changed = realIndex !== selectedIndex || value !== opt.value;
+		selectedIndex = realIndex;
+		index = realIndex;
+		value = opt.value;
+		if (changed) {
+			if (announce) {
+				announceNonce = !announceNonce;
+				// trailing zero-width space on alternate commits => text always changes
+				announceText = announceNonce ? opt.label : opt.label + "\u200B";
+			}
+			onchange?.(opt, realIndex);
+		}
+	}
+
+	function armIdle() {
+		clearTimeout(idleTimer);
+		idleTimer = setTimeout(settle, IDLE_MS);
+	}
+
+	function onScroll() {
+		if (!scrollEl) return;
+		const st = scrollEl.scrollTop;
+		if (st !== lastScrollTop) lastDir = st > lastScrollTop ? 1 : -1;
+		lastScrollTop = st;
+		armIdle();
+	}
+
+	/**
+	 * Read the settled selection and commit it; recenter the loop buffer. Gated on
+	 * snap-alignment so we never commit/teleport mid-momentum (a momentum *pause*
+	 * leaves scrollTop off the snap grid → re-arm and wait for true rest).
+	 */
+	function settle() {
+		if (!scrollEl || n === 0) return;
+		const raw = scrollEl.scrollTop;
+		const snapped = Math.round(raw / itemHeight) * itemHeight;
+		if (Math.abs(raw - snapped) > 1.5) {
+			armIdle();
+			return;
+		}
+		clearTimeout(idleTimer);
+		pendingSmooth = false;
+		userScrolling = false;
+
+		const gi = centerGlobalIndex(raw, itemHeight);
+		let real = realIndexFromGlobal(gi, n, loop);
+
+		// Auto-skip a disabled landing by nudging to the nearest enabled row in the travel
+		// direction. anchorTo() lands it in the home tile, so the buffer stays recentered.
+		if (opts[real]?.disabled) {
+			const target = nextEnabledIndex(real + lastDir, lastDir, opts, loop);
+			if (target !== real && !opts[target]?.disabled) {
+				anchorTo(target);
+				commit(target);
+				return;
+			}
+		}
+
+		commit(real);
+
+		// Recenter to the home tile (invisible: an exact whole-tile teleport leaves the
+		// centered row and its value unchanged). drift becomes 0 afterwards → no recurse.
+		if (loop) {
+			const drift = driftTiles(gi, n, homeTile);
+			if (drift !== 0) {
+				scrollEl.scrollTop = raw - drift * tilePx;
+				lastScrollTop = scrollEl.scrollTop;
+			}
+		}
+	}
+
+	/** Scroll so `realIndex` becomes selected. Keeps within the copy nearest the current
+	 *  position (minimal/zero visible movement). Smooth unless instant/reduced-motion. */
+	function scrollToIndex(realIndex: number, instant = false) {
+		if (!scrollEl || n === 0) return;
+		const r = loop ? mod(realIndex, n) : clamp(realIndex, 0, n - 1);
+		let gi: number;
+		if (loop) {
+			// target the copy of `r` nearest the current position, so a wrap (59 -> 00)
+			// advances one step in the natural direction instead of rewinding the long way.
+			const curGi = centerGlobalIndex(scrollEl.scrollTop, itemHeight);
+			gi = nearestGlobalIndex(curGi, r, n);
+		} else {
+			gi = r;
+		}
+		const targetTop = gi * itemHeight;
+		// A zero-distance scroll fires no scroll/scrollend events. Commit directly and bail
+		// (also covers Arrow/Home/End at a non-loop edge).
+		if (Math.abs(scrollEl.scrollTop - targetTop) < 1) {
+			commit(r);
+			return;
+		}
+		// Coalesce rapid programmatic changes (e.g. a fast clock binding) to instant to
+		// avoid animation pile-up; otherwise animate.
+		const behavior: ScrollBehavior =
+			instant || reducedMotion.current || pendingSmooth ? "instant" : "smooth";
+		pendingSmooth = behavior === "smooth";
+		commit(r);
+		scrollEl.scrollTo({ top: targetTop, behavior });
+		lastScrollTop = targetTop;
+		// armIdle guarantees a settle() (clears pendingSmooth) even where `scrollend` is
+		// unavailable (iOS < 26.2) or a smooth scroll's end event doesn't fire.
+		armIdle();
+	}
+
+	function step(delta: number) {
+		if (n === 0) return;
+		const target = nextEnabledIndex(
+			selectedIndex + delta,
+			delta >= 0 ? 1 : -1,
+			opts,
+			loop
+		);
+		scrollToIndex(target);
+	}
+
+	function onKeydown(e: KeyboardEvent) {
+		if (!keyboard || n === 0) return;
+		switch (e.key) {
+			case "ArrowDown":
+				e.preventDefault();
+				step(1);
+				break;
+			case "ArrowUp":
+				e.preventDefault();
+				step(-1);
+				break;
+			case "PageDown":
+				e.preventDefault();
+				step(vCount);
+				break;
+			case "PageUp":
+				e.preventDefault();
+				step(-vCount);
+				break;
+			case "Home":
+				e.preventDefault();
+				scrollToIndex(nextEnabledIndex(0, 1, opts, loop));
+				break;
+			case "End":
+				e.preventDefault();
+				scrollToIndex(nextEnabledIndex(n - 1, -1, opts, loop));
+				break;
+		}
+	}
+
+	// Init, re-anchor on geometry change, AND reconcile the committed selection when the
+	// options array changes (shrinks/reorders). Structural deps only (incl. `opts` content);
+	// `selectedIndex`/`value`/`index` are read untracked so a user commit or an external
+	// value tick doesn't retrigger this (the separate reconcile effect owns that).
+	$effect(() => {
+		void scrollEl;
+		void opts;
+		void itemHeight;
+		void vCount;
+		void tiles;
+		void loop;
+		if (!scrollEl || n === 0) return;
+		untrack(() => {
+			if (!mounted) {
+				// initial: skip a disabled target, position, and make value+index
+				// authoritative from frame 1 (covers an unmatched/partial initial binding).
+				const sel0 = nextEnabledIndex(clamp(selectedIndex, 0, n - 1), 1, opts, loop);
+				selectedIndex = sel0;
+				anchorTo(sel0);
+				const opt = opts[sel0];
+				if (opt) {
+					value = opt.value;
+					index = sel0;
+				}
+				mounted = true;
+				return;
+			}
+			if (userScrolling) return; // don't disrupt an in-flight gesture; settle reconciles
+			// reconcile a now-invalid committed selection (options shrank/reordered)
+			const cur = opts[selectedIndex];
+			const stillValid =
+				selectedIndex < n && cur && (value === undefined || cur.value === value);
+			if (!stillValid) {
+				let cand = value !== undefined ? indexOfValue(opts, value) : -1;
+				if (cand < 0) cand = clamp(selectedIndex, 0, n - 1);
+				commit(nextEnabledIndex(cand, 1, opts, loop));
+			}
+			anchorTo(clamp(selectedIndex, 0, n - 1));
+		});
+	});
+
+	// Reconcile external value/index changes (e.g. a clock binding). Deferred while the
+	// user is actively scrolling; no-op when already in sync (prevents a commit→effect loop).
+	$effect(() => {
+		if (!mounted || !scrollEl || n === 0) return;
+		let desired = -1;
+		if (value !== undefined) {
+			const i = indexOfValue(opts, value);
+			if (i >= 0) desired = i;
+		} else if (index !== undefined) {
+			desired = clamp(index, 0, n - 1);
+		}
+		if (desired < 0 || desired === selectedIndex) return;
+		if (untrack(() => userScrolling)) return;
+		untrack(() => scrollToIndex(desired, reducedMotion.current));
+	});
+
+	// A listbox with no accessible name is a WCAG 4.1.2 failure for screen-reader users.
+	$effect(() => {
+		if (n > 0 && !label && !ariaLabel && !ariaLabelledby) {
+			console.warn(
+				"[WheelPicker] No `label` provided — the listbox has no accessible name for " +
+					"screen readers. Pass `label` (or aria-label/aria-labelledby)."
+			);
+		}
+	});
+
+	$effect(() => {
+		return () => clearTimeout(idleTimer);
+	});
+
+	let _class = $derived(unstyled ? classProp : twMerge("stuic-wheel-picker", classProp));
+</script>
+
+<div
+	bind:this={el}
+	class={_class}
+	data-loop={!unstyled && loop ? "true" : undefined}
+	style={unstyled
+		? undefined
+		: `--stuic-wheel-picker-item-height: ${itemHeight}px; --stuic-wheel-picker-visible-count: ${vCount};`}
+	{...rest}
+>
+	<div
+		bind:this={scrollEl}
+		class={unstyled ? undefined : "stuic-wheel-picker-scroll"}
+		role="listbox"
+		tabindex={keyboard ? 0 : undefined}
+		aria-label={label ?? ariaLabel}
+		aria-labelledby={ariaLabelledby}
+		aria-activedescendant={selectedOptionId}
+		onscroll={onScroll}
+		onscrollend={settle}
+		onpointerdown={markUserScrolling}
+		ontouchstart={markUserScrolling}
+		onwheel={markUserScrolling}
+		onkeydown={onKeydown}
+	>
+		<div
+			class={unstyled ? undefined : "stuic-wheel-picker-spacer"}
+			aria-hidden="true"
+		></div>
+		{#each rows as row (row.gi)}
+			{@const selected = row.isHome && row.realIndex === selectedIndex}
+			<div
+				class={twMerge(
+					!unstyled && "stuic-wheel-picker-item",
+					classItem,
+					selected && classItemSelected
+				)}
+				id={row.isHome ? optionId(row.realIndex) : undefined}
+				role={row.isHome ? "option" : undefined}
+				aria-hidden={row.isHome ? undefined : "true"}
+				aria-selected={row.isHome ? (selected ? "true" : "false") : undefined}
+				aria-disabled={row.option?.disabled ? "true" : undefined}
+				data-selected={selected ? "true" : undefined}
+				data-disabled={row.option?.disabled ? "true" : undefined}
+				data-label={row.option?.label}
+			>
+				{#if renderItem}
+					{@render renderItem({ option: row.option, index: row.realIndex, selected })}
+				{:else}
+					{row.option?.label}
+				{/if}
+			</div>
+		{/each}
+		<div
+			class={unstyled ? undefined : "stuic-wheel-picker-spacer"}
+			aria-hidden="true"
+		></div>
+	</div>
+
+	{#if !unstyled}
+		<div class={twMerge("stuic-wheel-picker-band", classBand)} aria-hidden="true"></div>
+	{/if}
+
+	{#if announce}
+		<div class="stuic-wheel-picker-sr" aria-live="polite" aria-atomic="true">
+			{announceText}
+		</div>
+	{/if}
+</div>

package/dist/components/WheelPicker/WheelPicker.svelte.d.ts

@@ -0,0 +1,72 @@
+import type { HTMLAttributes } from "svelte/elements";
+import type { Snippet } from "svelte";
+import type { WheelPickerOption, WheelPickerOptionInput } from "./utils.js";
+export type { WheelPickerOption, WheelPickerOptionInput } from "./utils.js";
+export interface Props<T = string | number> extends Omit<HTMLAttributes<HTMLDivElement>, "children" | "onchange"> {
+    /** Options to scroll through. Bare strings/numbers become `{ label, value }`; objects pass through. */
+    options: WheelPickerOptionInput<T>[];
+    /** Bindable selected value (the chosen option's `value`). Primary binding. */
+    value?: T;
+    /** Bindable selected real index (modulo-reduced). Alternative/companion to `value`. */
+    index?: number;
+    /** Infinite wrap (59 → 00). Default false (single copy, clamped at the ends). */
+    loop?: boolean;
+    /** Row height in px. Prefer an integer to avoid cross-copy drift. Default 36. */
+    itemHeight?: number;
+    /** How many rows are visible (forced odd, so there's an exact center). Default 5. */
+    visibleCount?: number;
+    /** Loop buffer copies (floor; auto-grown to guarantee fling runway). Default 3. */
+    tiles?: number;
+    /** Enable keyboard navigation (Arrow/Page/Home/End). Default true. */
+    keyboard?: boolean;
+    /** Announce the committed label via an aria-live region. Default true. */
+    announce?: boolean;
+    /** Accessible name for the listbox. Strongly recommended. */
+    label?: string;
+    /** Fired when the selection settles on a new option (not during a fling). */
+    onchange?: (option: WheelPickerOption<T>, index: number) => void;
+    /** Skip default styling. */
+    unstyled?: boolean;
+    /** Additional CSS classes on the root. */
+    class?: string;
+    /** Extra classes on each row. */
+    classItem?: string;
+    /** Extra classes on the selected row. */
+    classItemSelected?: string;
+    /** Extra classes on the center selection band. */
+    classBand?: string;
+    /** Bindable root element ref. */
+    el?: HTMLDivElement;
+    /** Custom row renderer (alternative to the plain label). */
+    renderItem?: Snippet<[
+        {
+            option: WheelPickerOption<T>;
+            index: number;
+            selected: boolean;
+        }
+    ]>;
+}
+declare function $$render<T = string | number>(): {
+    props: Props<T>;
+    exports: {};
+    bindings: "el" | "value" | "index";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<T = string | number> {
+    props(): ReturnType<typeof $$render<T>>['props'];
+    events(): ReturnType<typeof $$render<T>>['events'];
+    slots(): ReturnType<typeof $$render<T>>['slots'];
+    bindings(): "el" | "value" | "index";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T = string | number>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
+    } & ReturnType<__sveltets_Render<T>['exports']>;
+    <T = string | number>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const WheelPicker: $$IsomorphicComponent;
+type WheelPicker<T = string | number> = InstanceType<typeof WheelPicker<T>>;
+export default WheelPicker;

package/dist/components/WheelPicker/index.css

@@ -0,0 +1,201 @@
+/* ============================================================================
+   WHEEL PICKER COMPONENT TOKENS
+   iOS-style scrolling wheel / drum picker (UIPickerView).
+   Override globally: :root { --stuic-wheel-picker-color-selected: #f00; }
+   Override locally:  <WheelPicker style="--stuic-wheel-picker-band-bg: #0001;">
+
+   NOTE: geometry (item-height / visible-count) is set via the `itemHeight`/`visibleCount`
+   PROPS, not CSS — the component writes those vars inline (they also drive the JS scroll
+   math), so a CSS override of them is shadowed by the inline style. Set them via props.
+   ============================================================================ */
+
+:root {
+	/* Geometry (defaults; component overrides inline from props) */
+	--stuic-wheel-picker-item-height: 36px;
+	--stuic-wheel-picker-visible-count: 5;
+	--stuic-wheel-picker-min-width: 3rem;
+
+	/* Typography / color */
+	--stuic-wheel-picker-font-size: 1.125rem;
+	--stuic-wheel-picker-font-family: var(--font-sans);
+	--stuic-wheel-picker-color: var(--stuic-color-muted-foreground);
+	--stuic-wheel-picker-color-selected: var(--stuic-color-foreground);
+	--stuic-wheel-picker-font-weight-selected: 600;
+
+	/* Center selection band */
+	--stuic-wheel-picker-band-bg: color-mix(
+		in srgb,
+		var(--stuic-color-foreground) 4%,
+		transparent
+	);
+	--stuic-wheel-picker-band-border-color: var(--stuic-color-border);
+
+	/* Edge fade strength (0 = no fade, 1 = full fade to transparent at the rim) */
+	--stuic-wheel-picker-fade: 1;
+
+	/* Focus ring */
+	--stuic-wheel-picker-ring-width: 2px;
+	--stuic-wheel-picker-ring-color: var(--stuic-color-ring);
+}
+
+@layer components {
+	/* ========================================================================
+	   ROOT
+	   ======================================================================== */
+	.stuic-wheel-picker {
+		position: relative;
+		display: inline-block;
+		min-width: var(--stuic-wheel-picker-min-width);
+		font-family: var(--stuic-wheel-picker-font-family);
+		-webkit-tap-highlight-color: transparent;
+	}
+
+	/* ========================================================================
+	   SCROLL VIEWPORT
+	   The only scrollable element. Native overflow scroll + CSS scroll-snap do
+	   the momentum + settling; JS only reads/repositions at rest.
+	   ======================================================================== */
+	.stuic-wheel-picker-scroll {
+		height: calc(
+			var(--stuic-wheel-picker-visible-count) * var(--stuic-wheel-picker-item-height)
+		);
+		overflow-x: hidden;
+		overflow-y: auto;
+
+		scroll-snap-type: y mandatory;
+		overscroll-behavior: contain; /* stop iOS rubber-band bouncing the page at the ends */
+		-webkit-overflow-scrolling: touch;
+		touch-action: pan-y;
+
+		border-radius: var(--stuic-wheel-picker-radius, var(--stuic-radius-container));
+		background: var(--stuic-wheel-picker-bg, transparent);
+
+		/* Hide scrollbar (the band + fade convey position) */
+		scrollbar-width: none;
+		-ms-overflow-style: none;
+
+		/* Edge fade — center stays fully opaque, rows dim toward the rim. The clear
+		   band is ~1 row tall (1 / visible-count of the height) around the center. */
+		--_fade-edge: calc(
+			(50% - 0.5 * var(--stuic-wheel-picker-item-height)) * var(--stuic-wheel-picker-fade)
+		);
+		-webkit-mask-image: linear-gradient(
+			to bottom,
+			transparent 0,
+			#000 var(--_fade-edge),
+			#000 calc(100% - var(--_fade-edge)),
+			transparent 100%
+		);
+		mask-image: linear-gradient(
+			to bottom,
+			transparent 0,
+			#000 var(--_fade-edge),
+			#000 calc(100% - var(--_fade-edge)),
+			transparent 100%
+		);
+	}
+
+	.stuic-wheel-picker-scroll::-webkit-scrollbar {
+		display: none;
+	}
+
+	.stuic-wheel-picker-scroll:focus {
+		outline: none;
+	}
+
+	.stuic-wheel-picker-scroll:focus-visible {
+		outline: var(--stuic-wheel-picker-ring-width) solid
+			var(--stuic-wheel-picker-ring-color);
+		outline-offset: 2px;
+	}
+
+	/* ========================================================================
+	   SPACERS — let the first/last real row reach the vertical center
+	   ======================================================================== */
+	.stuic-wheel-picker-spacer {
+		flex: 0 0 auto;
+		height: calc(
+			(var(--stuic-wheel-picker-visible-count) - 1) / 2 *
+				var(--stuic-wheel-picker-item-height)
+		);
+	}
+
+	/* ========================================================================
+	   ROWS
+	   ======================================================================== */
+	.stuic-wheel-picker-item {
+		display: flex;
+		flex-direction: column; /* stack the bold-width ghost (below) with no row-width sum */
+		align-items: center;
+		justify-content: center;
+		height: var(--stuic-wheel-picker-item-height);
+		box-sizing: border-box;
+		padding-inline: 0.75rem;
+
+		scroll-snap-align: center;
+		scroll-snap-stop: always; /* best-effort; correctness never relies on it */
+
+		font-size: var(--stuic-wheel-picker-font-size);
+		line-height: 1;
+		color: var(--stuic-wheel-picker-color);
+		white-space: nowrap;
+		user-select: none;
+		-webkit-user-select: none;
+		transition: color var(--stuic-wheel-picker-transition, var(--stuic-transition));
+	}
+
+	/* Reserve the SELECTED (bold) label width on EVERY row via a zero-height, hidden
+	   ghost, so committing a wider/narrower bold word never resizes the shrink-to-fit
+	   wheel (prevents the 1–2px container width jitter while scrolling). */
+	.stuic-wheel-picker-item::after {
+		content: attr(data-label);
+		height: 0;
+		overflow: hidden;
+		visibility: hidden;
+		pointer-events: none;
+		font-weight: var(--stuic-wheel-picker-font-weight-selected);
+	}
+
+	.stuic-wheel-picker-item[data-selected="true"] {
+		color: var(--stuic-wheel-picker-color-selected);
+		font-weight: var(--stuic-wheel-picker-font-weight-selected);
+	}
+
+	.stuic-wheel-picker-item[data-disabled="true"] {
+		opacity: 0.4;
+	}
+
+	/* ========================================================================
+	   CENTER SELECTION BAND (purely visual)
+	   ======================================================================== */
+	.stuic-wheel-picker-band {
+		position: absolute;
+		left: 0;
+		right: 0;
+		top: 50%;
+		height: var(--stuic-wheel-picker-item-height);
+		transform: translateY(-50%);
+		pointer-events: none;
+		background: var(--stuic-wheel-picker-band-bg);
+		border-top: var(--stuic-wheel-picker-band-border-width, var(--stuic-border-width))
+			solid var(--stuic-wheel-picker-band-border-color);
+		border-bottom: var(--stuic-wheel-picker-band-border-width, var(--stuic-border-width))
+			solid var(--stuic-wheel-picker-band-border-color);
+	}
+
+	/* ========================================================================
+	   SCREEN-READER LIVE REGION (visually hidden)
+	   ======================================================================== */
+	.stuic-wheel-picker-sr {
+		position: absolute;
+		width: 1px;
+		height: 1px;
+		padding: 0;
+		margin: -1px;
+		overflow: hidden;
+		clip: rect(0 0 0 0);
+		clip-path: inset(50%);
+		white-space: nowrap;
+		border: 0;
+	}
+}

package/dist/components/WheelPicker/index.d.ts

@@ -0,0 +1,3 @@
+export { default as WheelPicker } from "./WheelPicker.svelte";
+export type { Props as WheelPickerProps } from "./WheelPicker.svelte";
+export type { WheelPickerOption, WheelPickerOptionInput } from "./utils.js";

package/dist/components/WheelPicker/index.js

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

package/dist/components/WheelPicker/utils.d.ts

@@ -0,0 +1,62 @@
+export interface WheelPickerOption<T = string | number> {
+    /** Visible text for the row (and what gets announced to screen readers). */
+    label: string;
+    /** The value committed to `bind:value` when this row is selected. */
+    value: T;
+    /** When true the row cannot be selected (auto-skipped on settle/keyboard). */
+    disabled?: boolean;
+}
+/** What callers may pass: a bare primitive (used as both label and value) or a full option. */
+export type WheelPickerOptionInput<T = string | number> = string | number | WheelPickerOption<T>;
+/** Px runway (each direction from the home tile) the loop buffer must guarantee so a
+ *  realistic fling never runs off the rendered content before it comes to rest. */
+export declare const MIN_RUNWAY_PX = 2400;
+/** Positive modulo — `((n % m) + m) % m` — so negative indices wrap correctly. */
+export declare function mod(n: number, m: number): number;
+export declare function clamp(n: number, lo: number, hi: number): number;
+/** Force an integer >= 1 and odd, so there is always a single exact center row. */
+export declare function forceOdd(n: number): number;
+/** Normalize mixed input to `{ label, value, disabled }`. */
+export declare function normalizeOptions<T = string | number>(options: WheelPickerOptionInput<T>[]): WheelPickerOption<T>[];
+/**
+ * The rendered row whose center currently sits under the selection band.
+ * With the top/bottom center spacer, row `j` is centered exactly when
+ * `scrollTop === j * itemHeight`, so the global (buffered) index is a rounded ratio.
+ */
+export declare function centerGlobalIndex(scrollTop: number, itemHeight: number): number;
+/** Map a global (buffered) index to the real option index — wrap when looping, clamp otherwise. */
+export declare function realIndexFromGlobal(globalIndex: number, n: number, loop: boolean): number;
+/**
+ * Number of identical tiles to render for the infinite buffer. Auto-grows (staying
+ * odd, min 3) until the runway from the home tile to either end covers both the
+ * viewport and `MIN_RUNWAY_PX`, so a single fling can't exhaust the buffer at rest.
+ * Returns 1 when not looping (single copy, clamped).
+ */
+export declare function resolveTiles(requested: number, n: number, itemHeight: number, containerHeight: number, loop: boolean, minRunwayPx?: number): number;
+/** Global index of real index 0 in the middle (home) tile. */
+export declare function homeBase(tiles: number, n: number): number;
+/**
+ * How many whole tiles the centered row has drifted from the home tile.
+ * Floor-based (which tile are we in), NOT round-based: after teleporting by this
+ * many tiles the center lands back in the home tile with drift 0 — no oscillation,
+ * and the real index (`gi mod n`) is unchanged, so the teleport is invisible.
+ */
+export declare function driftTiles(globalIndex: number, n: number, homeTile: number): number;
+/**
+ * Nearest selectable (non-disabled) real index starting at `start`, searching in
+ * `dir`. Returns `start` (reduced) if it is already enabled. Loop wraps; non-loop
+ * stops at the edge and returns the last index reached even if disabled. If every
+ * option is disabled, returns the reduced start.
+ */
+export declare function nextEnabledIndex(start: number, dir: 1 | -1, options: readonly {
+    disabled?: boolean;
+}[], loop: boolean): number;
+/** Index of the option matching `value` (strict equality), or -1. */
+export declare function indexOfValue<T>(options: WheelPickerOption<T>[], value: T): number;
+/**
+ * Global index of the copy of `realIndex` NEAREST `currentGlobal` (shortest signed path,
+ * ties resolve forward). This is what makes a wrap travel naturally: from 59 with n=60,
+ * targeting real 0 returns currentGlobal+1 (one step down) rather than rewinding 59 rows
+ * up to the same tile's 0. Used for programmatic/keyboard moves in loop mode.
+ */
+export declare function nearestGlobalIndex(currentGlobal: number, realIndex: number, n: number): number;

package/dist/components/WheelPicker/utils.js

@@ -0,0 +1,139 @@
+// ============================================================================
+// WheelPicker — framework-free index math
+//
+// The component leans entirely on native scroll + CSS scroll-snap. ALL of its
+// correctness-critical logic is the pure index arithmetic below: turning a
+// scrollTop into a selected option, wrapping/clamping indices, and computing the
+// "teleport" that makes the loop infinite. Keeping it here (no Svelte, no DOM)
+// means it is exhaustively unit-testable in the fast node project (utils.test.ts).
+// ============================================================================
+/** Px runway (each direction from the home tile) the loop buffer must guarantee so a
+ *  realistic fling never runs off the rendered content before it comes to rest. */
+export const MIN_RUNWAY_PX = 2400;
+/** Positive modulo — `((n % m) + m) % m` — so negative indices wrap correctly. */
+export function mod(n, m) {
+    if (m <= 0)
+        return 0;
+    return ((n % m) + m) % m;
+}
+export function clamp(n, lo, hi) {
+    if (hi < lo)
+        return lo;
+    return Math.min(hi, Math.max(lo, n));
+}
+/** Force an integer >= 1 and odd, so there is always a single exact center row. */
+export function forceOdd(n) {
+    let v = Math.max(1, Math.round(n));
+    if (v % 2 === 0)
+        v += 1;
+    return v;
+}
+/** Normalize mixed input to `{ label, value, disabled }`. */
+export function normalizeOptions(options) {
+    return (options ?? []).map((o) => {
+        if (o !== null && typeof o === "object" && "value" in o) {
+            const opt = o;
+            return {
+                label: String(opt.label ?? opt.value),
+                value: opt.value,
+                disabled: !!opt.disabled,
+            };
+        }
+        return { label: String(o), value: o };
+    });
+}
+/**
+ * The rendered row whose center currently sits under the selection band.
+ * With the top/bottom center spacer, row `j` is centered exactly when
+ * `scrollTop === j * itemHeight`, so the global (buffered) index is a rounded ratio.
+ */
+export function centerGlobalIndex(scrollTop, itemHeight) {
+    if (itemHeight <= 0)
+        return 0;
+    return Math.round(scrollTop / itemHeight);
+}
+/** Map a global (buffered) index to the real option index — wrap when looping, clamp otherwise. */
+export function realIndexFromGlobal(globalIndex, n, loop) {
+    if (n <= 0)
+        return 0;
+    return loop ? mod(globalIndex, n) : clamp(globalIndex, 0, n - 1);
+}
+/**
+ * Number of identical tiles to render for the infinite buffer. Auto-grows (staying
+ * odd, min 3) until the runway from the home tile to either end covers both the
+ * viewport and `MIN_RUNWAY_PX`, so a single fling can't exhaust the buffer at rest.
+ * Returns 1 when not looping (single copy, clamped).
+ */
+export function resolveTiles(requested, n, itemHeight, containerHeight, loop, minRunwayPx = MIN_RUNWAY_PX) {
+    if (!loop || n <= 0)
+        return 1;
+    let tiles = Math.max(3, Math.round(requested));
+    if (tiles % 2 === 0)
+        tiles += 1;
+    const tilePx = n * itemHeight;
+    if (tilePx > 0) {
+        const need = Math.max(containerHeight, minRunwayPx);
+        // runway on each side = floor(tiles/2) full tiles
+        while (Math.floor(tiles / 2) * tilePx < need)
+            tiles += 2;
+    }
+    return tiles;
+}
+/** Global index of real index 0 in the middle (home) tile. */
+export function homeBase(tiles, n) {
+    return Math.floor(tiles / 2) * n;
+}
+/**
+ * How many whole tiles the centered row has drifted from the home tile.
+ * Floor-based (which tile are we in), NOT round-based: after teleporting by this
+ * many tiles the center lands back in the home tile with drift 0 — no oscillation,
+ * and the real index (`gi mod n`) is unchanged, so the teleport is invisible.
+ */
+export function driftTiles(globalIndex, n, homeTile) {
+    if (n <= 0)
+        return 0;
+    return Math.floor(globalIndex / n) - homeTile;
+}
+/**
+ * Nearest selectable (non-disabled) real index starting at `start`, searching in
+ * `dir`. Returns `start` (reduced) if it is already enabled. Loop wraps; non-loop
+ * stops at the edge and returns the last index reached even if disabled. If every
+ * option is disabled, returns the reduced start.
+ */
+export function nextEnabledIndex(start, dir, options, loop) {
+    const n = options.length;
+    if (n === 0)
+        return start;
+    let i = loop ? mod(start, n) : clamp(start, 0, n - 1);
+    for (let step = 0; step < n; step++) {
+        if (!options[i]?.disabled)
+            return i;
+        let next = i + dir;
+        if (loop) {
+            next = mod(next, n);
+        }
+        else if (next < 0 || next > n - 1) {
+            return i; // hit the edge, give up
+        }
+        i = next;
+    }
+    return i; // all disabled
+}
+/** Index of the option matching `value` (strict equality), or -1. */
+export function indexOfValue(options, value) {
+    return options.findIndex((o) => o.value === value);
+}
+/**
+ * Global index of the copy of `realIndex` NEAREST `currentGlobal` (shortest signed path,
+ * ties resolve forward). This is what makes a wrap travel naturally: from 59 with n=60,
+ * targeting real 0 returns currentGlobal+1 (one step down) rather than rewinding 59 rows
+ * up to the same tile's 0. Used for programmatic/keyboard moves in loop mode.
+ */
+export function nearestGlobalIndex(currentGlobal, realIndex, n) {
+    if (n <= 0)
+        return currentGlobal;
+    let delta = mod(realIndex - mod(currentGlobal, n), n); // 0..n-1
+    if (delta > n / 2)
+        delta -= n; // fold into (-n/2, n/2]
+    return currentGlobal + delta;
+}

package/dist/index.css

@@ -100,6 +100,7 @@ In practice:
 @import "./components/Tree/index.css";
 @import "./components/TwCheck/index.css";
 @import "./components/UserAvatarMenu/index.css";
+@import "./components/WheelPicker/index.css";
 @import "./components/WithSidePanel/index.css";
 @import "./components/X/index.css";
 

package/dist/index.d.ts

@@ -75,6 +75,7 @@ export * from "./components/Tree/index.js";
 export * from "./components/TwCheck/index.js";
 export * from "./components/TypeaheadInput/index.js";
 export * from "./components/UserAvatarMenu/index.js";
+export * from "./components/WheelPicker/index.js";
 export * from "./components/WithSidePanel/index.js";
 export * from "./components/X/index.js";
 export * from "./utils/index.js";

package/dist/index.js

@@ -76,6 +76,7 @@ export * from "./components/Tree/index.js";
 export * from "./components/TwCheck/index.js";
 export * from "./components/TypeaheadInput/index.js";
 export * from "./components/UserAvatarMenu/index.js";
+export * from "./components/WheelPicker/index.js";
 export * from "./components/WithSidePanel/index.js";
 export * from "./components/X/index.js";
 // utils

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/stuic",
-	"version": "3.118.0",
+	"version": "3.119.0",
 	"packageManager": "pnpm@11.5.0",
 	"scripts": {
 		"dev": "vite dev",
@@ -140,12 +140,12 @@
 		"@milkdown/transformer": "^7.21.2",
 		"@milkdown/utils": "^7.21.2",
 		"@sveltejs/adapter-auto": "^4.0.0",
-		"@sveltejs/kit": "^2.63.0",
+		"@sveltejs/kit": "^2.64.0",
 		"@sveltejs/package": "^2.5.8",
 		"@sveltejs/vite-plugin-svelte": "^6.2.4",
 		"@tailwindcss/cli": "^4.3.0",
 		"@tailwindcss/forms": "^0.5.11",
-		"@tailwindcss/typography": "^0.5.19",
+		"@tailwindcss/typography": "^0.5.20",
 		"@tailwindcss/vite": "^4.3.0",
 		"@types/node": "^25.9.2",
 		"@vitest/browser-playwright": "^4.1.8",
@@ -156,12 +156,12 @@
 		"prettier": "^3.8.3",
 		"prettier-plugin-svelte": "^3.5.2",
 		"publint": "^0.3.21",
-		"svelte": "^5.56.2",
+		"svelte": "^5.56.3",
 		"svelte-check": "^4.6.0",
 		"tailwindcss": "^4.3.0",
 		"tsx": "^4.22.4",
 		"typescript": "^5.9.3",
-		"typescript-eslint": "^8.60.1",
+		"typescript-eslint": "^8.61.0",
 		"vite": "^7.3.5",
 		"vitest": "^4.1.8",
 		"vitest-browser-svelte": "^2.1.1"