@yewdiel21/motion-kit 0.9.1 → 0.14.0

package/src/components/range-calendar/range-calendar.css

@@ -0,0 +1,185 @@
+/* range-calendar — a compact month (or two) on the Melon Mind surfaces: 2.5 rem days, the range as a soft band with
+   round ends at the range ends and at the edges of each week, ends as accent circles, a dashed preview band while
+   choosing the end, today with a ring. 20 px outer corners, 8 px buttons. */
+.mk-range-calendar,
+mk-range-calendar {
+  --mk-range-day: 2.5rem;
+  --mk-range-band: var(--mk-accent-soft);
+  display: inline-grid;
+  gap: 0.75rem;
+  max-width: 100%;
+  box-sizing: border-box;
+  padding: 0.75rem;
+  border-radius: 20px;
+  background: var(--mk-surface-1);
+  color: var(--mk-text);
+  font-variant-numeric: tabular-nums;
+}
+
+:is(.mk-range-calendar, mk-range-calendar) [data-mk-range-header] {
+  display: grid;
+  grid-template-columns: auto 1fr auto;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+:is(.mk-range-calendar, mk-range-calendar) [data-mk-range-title] {
+  margin: 0;
+  font-size: 0.9375rem;
+  font-weight: 600;
+  text-align: center;
+}
+
+:is(.mk-range-calendar, mk-range-calendar) :is([data-mk-range-prev], [data-mk-range-next]) {
+  display: grid;
+  place-items: center;
+  width: 2.25rem;
+  height: 2.25rem;
+  padding: 0;
+  border: 0;
+  border-radius: 8px;
+  background: var(--mk-surface-3);
+  color: inherit;
+  cursor: pointer;
+}
+
+:is(.mk-range-calendar, mk-range-calendar) :is([data-mk-range-prev], [data-mk-range-next]):focus-visible {
+  outline: 3px solid color-mix(in srgb, var(--mk-accent) 45%, transparent);
+  outline-offset: 2px;
+}
+
+:is(.mk-range-calendar, mk-range-calendar) [data-mk-range-months] {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 1.25rem;
+}
+
+:is(.mk-range-calendar, mk-range-calendar) [data-mk-range-month] {
+  display: grid;
+  grid-template-columns: repeat(7, var(--mk-range-day));
+  row-gap: 2px;
+}
+
+:is(.mk-range-calendar, mk-range-calendar) :is([data-mk-range-weekdays], [data-mk-range-week]) {
+  display: contents;
+}
+
+:is(.mk-range-calendar, mk-range-calendar) [data-mk-range-weekday] {
+  display: grid;
+  place-items: center;
+  height: 2rem;
+  color: var(--mk-muted);
+  font-size: 0.75rem;
+}
+
+:is(.mk-range-calendar, mk-range-calendar) [data-mk-range-cell] {
+  position: relative;
+  height: var(--mk-range-day);
+}
+
+:is(.mk-range-calendar, mk-range-calendar) [data-mk-day-band] {
+  position: absolute;
+  inset: 3px 0;
+  background: transparent;
+}
+
+:is(.mk-range-calendar, mk-range-calendar) [data-mk-range-cell]:has(> [data-mk-in-range]) [data-mk-day-band] {
+  background: var(--mk-range-band);
+}
+
+/* The tentative range: a lighter band with a dashed edge around the whole run (top and bottom on every day, the
+   sides only at its ends and at the edges of each week). */
+:is(.mk-range-calendar, mk-range-calendar) [data-mk-range-cell]:has(> [data-mk-preview]) [data-mk-day-band] {
+  box-sizing: border-box;
+  border-block: 1px dashed color-mix(in srgb, var(--mk-accent) 55%, transparent);
+  background: color-mix(in srgb, var(--mk-range-band) 55%, transparent);
+}
+
+:is(.mk-range-calendar, mk-range-calendar) [data-mk-range-cell]:has(> [data-mk-preview]):is(:has(> [data-mk-preview-start]), :first-child) [data-mk-day-band] {
+  border-left: 1px dashed color-mix(in srgb, var(--mk-accent) 55%, transparent);
+}
+
+:is(.mk-range-calendar, mk-range-calendar) [data-mk-range-cell]:has(> [data-mk-preview]):is(:has(> [data-mk-preview-end]), :last-child) [data-mk-day-band] {
+  border-right: 1px dashed color-mix(in srgb, var(--mk-accent) 55%, transparent);
+}
+
+/* Round ends: the range (or preview) ends and the first/last day of each week row (rows are display: contents, so
+   every row still holds exactly seven cells and :first-child / :last-child are its ends). The layout hangs on data
+   attributes, not roles: the copy that folds back into the button when a popover closes has no roles. */
+:is(.mk-range-calendar, mk-range-calendar) [data-mk-range-cell]:is(:has(> [data-mk-range-start], > [data-mk-preview-start]), :first-child) [data-mk-day-band] {
+  border-top-left-radius: 999px;
+  border-bottom-left-radius: 999px;
+}
+
+:is(.mk-range-calendar, mk-range-calendar) [data-mk-range-cell]:is(:has(> [data-mk-range-end], > [data-mk-preview-end]), :last-child) [data-mk-day-band] {
+  border-top-right-radius: 999px;
+  border-bottom-right-radius: 999px;
+}
+
+/* A month's first and last day also close the band (the cells around them are empty). */
+:is(.mk-range-calendar, mk-range-calendar) [data-mk-range-cell][data-mk-outside] + [data-mk-range-cell] [data-mk-day-band] {
+  border-top-left-radius: 999px;
+  border-bottom-left-radius: 999px;
+}
+
+:is(.mk-range-calendar, mk-range-calendar) [data-mk-range-cell]:has(+ [data-mk-range-cell][data-mk-outside]) [data-mk-day-band] {
+  border-top-right-radius: 999px;
+  border-bottom-right-radius: 999px;
+}
+
+:is(.mk-range-calendar, mk-range-calendar) [data-mk-day] {
+  position: relative;
+  z-index: 1;
+  width: 100%;
+  height: 100%;
+  padding: 0;
+  border: 0;
+  border-radius: 999px;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  cursor: pointer;
+  transition: background-color 0.2s ease, color 0.2s ease;
+}
+
+:is(.mk-range-calendar, mk-range-calendar) [data-mk-day]:hover {
+  background: var(--mk-surface-3);
+}
+
+:is(.mk-range-calendar, mk-range-calendar) [data-mk-day]:is([data-mk-range-start], [data-mk-range-end], [data-mk-anchor]) {
+  background: var(--mk-accent);
+  color: var(--mk-on-accent);
+  font-weight: 600;
+}
+
+:is(.mk-range-calendar, mk-range-calendar) [data-mk-day][data-mk-today]:not([data-mk-range-start], [data-mk-range-end], [data-mk-anchor]) {
+  box-shadow: inset 0 0 0 1.5px var(--mk-text);
+}
+
+:is(.mk-range-calendar, mk-range-calendar) [data-mk-day][aria-disabled='true'] {
+  color: var(--mk-muted);
+  text-decoration: line-through;
+  cursor: not-allowed;
+  opacity: 0.55;
+}
+
+:is(.mk-range-calendar, mk-range-calendar) [data-mk-day][aria-disabled='true']:hover {
+  background: transparent;
+}
+
+:is(.mk-range-calendar, mk-range-calendar) [data-mk-day]:focus-visible {
+  outline: 3px solid color-mix(in srgb, var(--mk-accent) 45%, transparent);
+  outline-offset: 1px;
+}
+
+@media (max-width: 380px) {
+  :is(.mk-range-calendar, mk-range-calendar) {
+    --mk-range-day: 2.25rem;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :is(.mk-range-calendar, mk-range-calendar) [data-mk-day] {
+    transition: none;
+  }
+}

package/src/components/range-calendar/react.tsx

@@ -0,0 +1,56 @@
+'use client';
+import { useRef, type HTMLAttributes } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { rangeKeys, toRange } from '../../core/date-range';
+import type { DateInput } from '../../core/dates';
+import { createRangeCalendar, type RangeCalendarInstance, type RangeCalendarOptions } from './engine';
+
+type RangeValue = { start: DateInput; end: DateInput } | null;
+
+export interface RangeCalendarProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue'>, Omit<RangeCalendarOptions, 'value'> {
+  /** Controlled range; without it the calendar keeps its own (defaultValue). */
+  value?: RangeValue;
+  defaultValue?: RangeValue;
+}
+
+const keyOf = (value: RangeValue | undefined) => {
+  const range = toRange(value);
+  return range ? JSON.stringify(rangeKeys(range)) : 'null';
+};
+
+/** <RangeCalendar value={range} onChange={setRange} visibleMonths={2} />. */
+export function RangeCalendar({ value, defaultValue, month, visibleMonths, firstDay, min, max, unavailable, locale, today, labels, onChange, className, ...props }: RangeCalendarProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const instance = useRef<RangeCalendarInstance | null>(null);
+  const change = useLatest(onChange);
+  const test = useLatest(unavailable);
+  const start = useRef<RangeValue>(value !== undefined ? value : (defaultValue ?? null));
+  const rules = typeof unavailable === 'function' ? 'function' : JSON.stringify(unavailable ?? null);
+  useIsomorphicLayoutEffect(() => {
+    const created = createRangeCalendar(ref.current, {
+      value: value !== undefined ? value : start.current,
+      month,
+      visibleMonths,
+      firstDay,
+      min,
+      max,
+      // A function is read through a ref so a new closure each render does not rebuild the calendar.
+      unavailable: typeof unavailable === 'function' ? (day) => (typeof test.current === 'function' ? test.current(day) : false) : unavailable,
+      locale,
+      today,
+      labels,
+      onChange: (range) => change.current?.(range),
+    });
+    instance.current = created;
+    return () => {
+      start.current = created.value;
+      created.destroy();
+      instance.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [String(month ?? ''), visibleMonths, firstDay, String(min ?? ''), String(max ?? ''), rules, locale, String(today ?? '')]);
+  useIsomorphicLayoutEffect(() => {
+    if (value !== undefined && instance.current && keyOf(value) !== keyOf(instance.current.value)) instance.current.setValue(value);
+  }, [keyOf(value)]);
+  return <div {...props} ref={ref} className={['mk-range-calendar', className].filter(Boolean).join(' ')} />;
+}

package/src/components/range-slider/README.md

@@ -0,0 +1,23 @@
+# range-slider
+
+Valor o intervalo sobre `<input type="range">` nativos: teclado, toque, formularios y `disabled` vienen de la plataforma. Dos inputs forman un intervalo cuyos extremos nunca se cruzan.
+
+```html
+<mk-range-slider class="mk-range-slider" min="0" max="1000" step="50" label="Presupuesto">
+  <div data-mk-range-track>
+    <input type="range" data-mk-range-input value="200" />
+    <input type="range" data-mk-range-input value="800" />
+  </div>
+  <output data-mk-range-output></output>
+</mk-range-slider>
+```
+
+`defineElements()`, `createRangeSlider(root, options)` o `<RangeSlider min={0} max={1000} defaultValue={[200, 800]} label="Presupuesto" onChange={setRange} />`. Sin inputs en el root, el motor crea uno (o dos si `value` es un array).
+
+Opciones: `min=0`, `max=100`, `step=1`, `value` (número o `[a, b]`), `disabled`, `name` (un intervalo envía `name[0]` y `name[1]`), `label` (aria-label; en intervalo «· mínimo/· máximo»), `formatValue(n)` (output y `aria-valuetext`), `onInput(value)`, `onChange(value)`. Sin opción, los límites se leen de los atributos del primer input; un `value` autorado que el navegador recortó al rango por defecto (0–100) se respeta. API: `setValue(value, notify=true)` (con `notify=false` no avisa ni cambia el valor confirmado, así un padre controlado puede reflejar cada `input` sin perder el `change`), `value` (copia), `destroy()`. En el custom element, `el.formatValue = (n) => …` aplica un formateador.
+
+`input` actualiza valor, relleno y output al instante y emite `mk:input`; `change` confirma una sola vez cuando el valor cambió y emite `mk:change` con `{value, previous}`. Los valores se ajustan al paso desde `min` sin errores decimales, se acotan al mayor `min + n·step ≤ max` e ignoran NaN. Al arrastrar un extremo más allá del otro se queda en el otro.
+
+El reset nativo del formulario recupera los valores por defecto de los inputs sin callbacks (un reset cancelado no cambia nada). `disabled` ignora la entrada del usuario. `destroy()` restaura valores, atributos, estilos y texto del output. React conserva la edición no controlada entre renders y la ajusta a nuevos límites; con `value` es controlado.
+
+Movimiento: el motor dibuja relleno, pulgares y una burbuja con el valor (`[data-mk-range-visual]`; los inputs nativos quedan como zona de toque transparente). Al pulsar, el pulgar crece y la burbuja aparece; arrastrar sigue al puntero sin retraso; `setValue` y el teclado se deslizan; confirmar un cambio da un pequeño rebote al output. Variables: `--mk-range-thumb` (1.5rem), `--mk-range-height` (8px), `--mk-range-track`, `--mk-range-fill`. El output no es región viva: los inputs anuncian su propio valor. Movimiento reducido quita escalas y deslizamientos.

package/src/components/range-slider/element.ts

@@ -0,0 +1,53 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createRangeSlider, type RangeSliderInstance, type RangeValue } from './engine';
+
+/**
+ * <mk-range-slider class="mk-range-slider" min="0" max="100" step="5" label="Precio" value="[20,80]">
+ *   <div data-mk-range-track><input type="range" data-mk-range-input value="20"><input type="range" data-mk-range-input value="80"></div>
+ *   <output data-mk-range-output></output>
+ * </mk-range-slider>
+ * Empty, it makes its input(s). Emits `mk:input` while dragging and `mk:change` ({value, previous}) on commit.
+ * `el.formatValue = (n) => `${n} €`` formats the output and aria-valuetext.
+ */
+export class MkRangeSliderElement extends MkElement<RangeSliderInstance> {
+  static options: Record<string, OptionType> = { min: 'number', max: 'number', step: 'number', value: 'json', disabled: 'boolean', name: 'string', label: 'string' };
+
+  private format: ((value: number) => string) | undefined;
+
+  /** Formatter for the output and aria-valuetext (code, so a property rather than an attribute). */
+  get formatValue() {
+    return this.format;
+  }
+
+  set formatValue(format: ((value: number) => string) | undefined) {
+    this.format = format;
+    this.rebuild(true);
+  }
+
+  protected create(options: Record<string, unknown>) {
+    return createRangeSlider(this, { ...options, formatValue: this.format });
+  }
+
+  /** Rebuild with the current attributes; keepValue keeps the edited value over the `value` attribute. */
+  private rebuild(keepValue: boolean) {
+    if (!this.isConnected || !this.instance) return;
+    const value = this.instance.value;
+    this.instance.destroy();
+    this.instance = this.create(keepValue ? { ...this.options, value } : { value, ...this.options });
+  }
+
+  // Bounds rebuild the engine but keep the edited value unless `value` is set.
+  attributeChangedCallback(_name: string, previous: string | null, next: string | null) {
+    if (previous !== next) this.rebuild(false);
+  }
+
+  setValue(value: RangeValue, notify?: boolean) {
+    this.instance?.setValue(value, notify);
+  }
+
+  get value() {
+    return this.instance?.value;
+  }
+}
+
+export const defineRangeSlider = () => defineElement('mk-range-slider', MkRangeSliderElement);

package/src/components/range-slider/engine.ts

@@ -0,0 +1,316 @@
+import { gsap, EASE, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { press } from '../../motion/micro';
+
+/*
+ * Range slider on native <input type="range"> (keyboard, touch and forms come
+ * from the platform). One input is a value, two are an interval whose thumbs
+ * never cross. `input` updates value and output at once; `change` commits (onChange /
+ * mk:change) only when the committed value differs. The native thumbs are
+ * transparent hit areas: the engine draws its own fill, thumbs and value
+ * bubbles and moves them with GSAP, tightly while dragging and with Melonmind's
+ * swing (.38,.49,0,1.5) for keys, presets, setValue and form reset. A grabbed
+ * thumb grows on the click curve and shows its value above it.
+ * Parts: [data-mk-range-input] (made when absent), [data-mk-range-track], [data-mk-range-output].
+ */
+
+export type RangeValue = number | [number, number];
+
+export interface RangeSliderOptions {
+  min?: number;
+  max?: number;
+  step?: number;
+  value?: RangeValue;
+  disabled?: boolean;
+  /** Form name; an interval submits name[0] and name[1]. */
+  name?: string;
+  /** Accessible name of the input(s). */
+  label?: string;
+  /** Text for the output and aria-valuetext. */
+  formatValue?: (value: number) => string;
+  onInput?: (value: RangeValue) => void;
+  onChange?: (value: RangeValue) => void;
+}
+
+export interface RangeSliderInstance extends Instance {
+  setValue(value: RangeValue, notify?: boolean): void;
+  readonly value: RangeValue;
+}
+
+const finite = (value: unknown): value is number => typeof value === 'number' && Number.isFinite(value);
+const attrNumber = (input: HTMLInputElement | undefined, name: string) => {
+  const raw = input?.getAttribute(name);
+  return raw !== null && raw !== undefined && raw.trim() !== '' && Number.isFinite(Number(raw)) ? Number(raw) : undefined;
+};
+const decimals = (n: number) => {
+  const [, fraction = ''] = String(n).split('.');
+  return fraction.length;
+};
+
+export function createRangeSlider(root: HTMLElement | null, options: RangeSliderOptions = {}): RangeSliderInstance {
+  if (!root) return inert({ setValue() {}, value: 0 });
+  registerMotion();
+  const scope = createScope();
+  let inputs = [...root.querySelectorAll<HTMLInputElement>('input[data-mk-range-input]')].slice(0, 2);
+  if (!inputs.length) {
+    const count = Array.isArray(options.value) ? 2 : 1;
+    inputs = Array.from({ length: count }, () => {
+      const input = document.createElement('input');
+      input.type = 'range';
+      input.dataset.mkRangeInput = '';
+      root.append(input);
+      scope.add(() => input.remove());
+      return input;
+    });
+  }
+  const pair = inputs.length === 2;
+  const first = inputs[0];
+  const min = finite(options.min) ? options.min : attrNumber(first, 'min') ?? 0;
+  const maxOption = finite(options.max) ? options.max : attrNumber(first, 'max') ?? 100;
+  const max = Math.max(min, maxOption);
+  const stepOption = finite(options.step) ? options.step : attrNumber(first, 'step') ?? 1;
+  const step = stepOption > 0 ? stepOption : 1;
+  const places = Math.min(10, Math.max(decimals(step), decimals(min)));
+  const fix = (n: number) => Number(n.toFixed(places));
+  const upper = Math.min(max, fix(min + Math.floor((max - min) / step + 1e-9) * step));
+  const normalize = (n: number) => Math.max(min, Math.min(upper, fix(min + Math.round((n - min) / step) * step)));
+  const disabled = options.disabled ?? inputs.some((input) => input.disabled);
+  const output = root.querySelector<HTMLElement>('[data-mk-range-output]');
+  const format = (n: number) => (options.formatValue ? options.formatValue(n) : String(n));
+  const originals = inputs.map((input) => input.value);
+
+  const ordered = (list: number[]) => (pair ? [...list].sort((a, b) => a - b) : list);
+  const read = () => inputs.map((input) => (input.value.trim() !== '' && Number.isFinite(Number(input.value)) ? normalize(Number(input.value)) : NaN));
+  /**
+   * Starting values. The parser clamps value="500" to the input's own range (0–100 by
+   * default) before min/max are set here: an authored value that was only clamped wins.
+   */
+  const authored = () => {
+    const current = read();
+    return inputs.map((input, i) => {
+      const written = attrNumber(input, 'value');
+      if (written === undefined) return current[i]!;
+      const low = attrNumber(input, 'min') ?? 0;
+      const high = Math.max(low, attrNumber(input, 'max') ?? 100);
+      return Number(input.value) === Math.min(high, Math.max(low, written)) ? normalize(written) : current[i]!;
+    });
+  };
+  const initial = (() => {
+    const wanted = options.value;
+    const fromOption = Array.isArray(wanted) ? wanted : finite(wanted) ? [wanted, wanted] : null;
+    const fromInputs = authored();
+    return inputs.map((_, i) => {
+      const candidate = fromOption?.[i];
+      if (finite(candidate)) return normalize(candidate);
+      return Number.isFinite(fromInputs[i]) ? fromInputs[i]! : i === 0 ? min : upper;
+    });
+  })();
+  let values = ordered(initial);
+  let committed = [...values];
+
+  // First registered, last undone: values return after min/max/step are authored again.
+  scope.add(() => inputs.forEach((input, i) => (input.value = originals[i]!)));
+  scope.attr(root, 'style', root.getAttribute('style'));
+  scope.attr(root, 'data-mk-ready', '');
+  scope.attr(root, 'data-mk-range', pair ? 'interval' : 'single');
+  inputs.forEach((input, i) => {
+    scope.attr(input, 'min', String(min));
+    scope.attr(input, 'max', String(upper));
+    scope.attr(input, 'step', String(step));
+    scope.attr(input, 'disabled', disabled ? '' : null);
+    if (pair) scope.attr(input, 'style', input.getAttribute('style'));
+    if (options.name) scope.attr(input, 'name', pair ? `${options.name}[${i}]` : options.name);
+    if (options.label) scope.attr(input, 'aria-label', pair ? `${options.label} · ${i === 0 ? 'mínimo' : 'máximo'}` : options.label);
+  });
+  if (output) {
+    const text = output.textContent;
+    // The inputs announce their own value; a live <output> would repeat every step of a drag.
+    scope.attr(output, 'aria-live', 'off');
+    scope.add(() => {
+      output.textContent = text;
+    });
+  }
+
+  // The drawn fill, thumbs and bubbles (decorative; the inputs stay the control).
+  const track = root.querySelector<HTMLElement>('[data-mk-range-track]') ?? first!.parentElement ?? root;
+  const visual = document.createElement('span');
+  visual.dataset.mkRangeVisual = '';
+  visual.setAttribute('aria-hidden', 'true');
+  const fill = document.createElement('span');
+  fill.dataset.mkPart = 'fill';
+  visual.append(fill);
+  const thumbs = inputs.map(() => {
+    const thumb = document.createElement('span');
+    thumb.dataset.mkPart = 'thumb';
+    const bubble = document.createElement('span');
+    bubble.dataset.mkPart = 'bubble';
+    thumb.append(bubble);
+    visual.append(thumb);
+    return { thumb, bubble };
+  });
+  track.append(visual);
+
+  const span = upper - min || 1;
+  const ratio = (n: number) => (n - min) / span;
+  /** What is drawn (ratios); it trails `values` while gliding. */
+  const shown = { a: pair ? ratio(values[0]!) : 0, b: ratio(pair ? values[1]! : values[0]!) };
+  const draw = () => {
+    root.style.setProperty('--mk-range-start', shown.a.toFixed(4));
+    root.style.setProperty('--mk-range-end', shown.b.toFixed(4));
+  };
+  let glide: gsap.core.Tween | null = null;
+  const effects = new Set<gsap.core.Animation>();
+  const trackEffect = (animation: gsap.core.Animation | null) => {
+    if (!animation) return;
+    effects.add(animation);
+    // Finished ones leave as new ones arrive: the animation's own onComplete stays untouched.
+    for (const effect of effects) if (effect.totalProgress() === 1) effects.delete(effect);
+  };
+  scope.add(() => {
+    glide?.kill();
+    for (const effect of effects) effect.kill();
+    effects.clear();
+    gsap.killTweensOf(thumbs.flatMap(({ thumb, bubble }) => [thumb, bubble]));
+    visual.remove();
+  });
+  let dragging = -1;
+  const bubbleFor = (i: number, on: boolean) => {
+    const part = thumbs[i];
+    if (!part) return;
+    part.thumb.toggleAttribute('data-mk-active', on);
+    if (reduced()) {
+      part.bubble.style.opacity = on ? '1' : '';
+      return;
+    }
+    gsap.killTweensOf(part.bubble);
+    if (on) trackEffect(gsap.fromTo(part.bubble, { opacity: 0, y: 4, scale: 0.9 }, { opacity: 1, y: 0, scale: 1, duration: 0.3, ease: EASE.pop }));
+    else trackEffect(gsap.to(part.bubble, { opacity: 0, y: 4, duration: 0.2, delay: 0.35, ease: 'power2.in', clearProps: 'transform' }));
+  };
+  const grow = (i: number, on: boolean) => {
+    const part = thumbs[i];
+    if (!part || reduced()) return;
+    trackEffect(gsap.to(part.thumb, { scale: on ? 1.22 : 1, duration: on ? 0.35 : 0.5, ease: EASE.click, overwrite: 'auto' }));
+  };
+
+  type Mode = 'set' | 'drag' | 'glide';
+  const current = (): RangeValue => (pair ? [values[0]!, values[1]!] : values[0]!);
+  const render = (mode: Mode = 'glide') => {
+    const target = { a: pair ? ratio(values[0]!) : 0, b: ratio(pair ? values[1]! : values[0]!) };
+    glide?.kill();
+    if (mode === 'set' || reduced()) {
+      Object.assign(shown, target);
+      draw();
+    } else glide = gsap.to(shown, { ...target, duration: mode === 'drag' ? 0.14 : 0.5, ease: mode === 'drag' ? 'power3.out' : EASE.swatch, onUpdate: draw });
+    inputs.forEach((input, i) => {
+      input.value = String(values[i]);
+      if (options.formatValue) scope.attr(input, 'aria-valuetext', format(values[i]!));
+      // The upper thumb stays reachable when both meet at the right end.
+      if (pair) input.style.zIndex = i === 0 && values[0]! >= upper ? '3' : '';
+      thumbs[i]!.bubble.textContent = format(values[i]!);
+    });
+    if (output) output.textContent = pair ? `${format(values[0]!)} – ${format(values[1]!)}` : format(values[0]!);
+  };
+  const same = (a: number[], b: number[]) => a.length === b.length && a.every((n, i) => n === b[i]);
+  const emit = (type: 'mk:input' | 'mk:change', previous?: RangeValue) =>
+    root.dispatchEvent(new CustomEvent(type, { bubbles: true, detail: type === 'mk:change' ? { value: current(), previous } : { value: current() } }));
+  const commit = (notify: boolean) => {
+    if (same(values, committed)) return;
+    const previous: RangeValue = pair ? [committed[0]!, committed[1]!] : committed[0]!;
+    committed = [...values];
+    if (!notify) return;
+    options.onChange?.(current());
+    emit('mk:change', previous);
+  };
+  /** The thumb `i` moved: keep it on the grid and behind/ahead of the other. */
+  const take = (i: number) => {
+    const raw = inputs[i]!.value;
+    const n = raw.trim() !== '' && Number.isFinite(Number(raw)) ? normalize(Number(raw)) : NaN;
+    if (!Number.isFinite(n)) return false;
+    let next = n;
+    if (pair) next = i === 0 ? Math.min(next, values[1]!) : Math.max(next, values[0]!);
+    const changed = next !== values[i];
+    values[i] = next;
+    return changed;
+  };
+
+  inputs.forEach((input, i) => {
+    // Inputs and the inputs of a destroyed instance are ignored by the scope.
+    scope.on(input, 'input', () => {
+      if (disabled) return render('set');
+      const changed = take(i);
+      render(dragging === i ? 'drag' : 'glide');
+      if (!changed) return;
+      // A key step nudges its thumb.
+      if (dragging !== i && !reduced()) trackEffect(gsap.fromTo(thumbs[i]!.thumb, { scale: 1.18 }, { scale: 1, duration: 0.45, ease: EASE.click }));
+      options.onInput?.(current());
+      emit('mk:input');
+    });
+    scope.on(input, 'change', () => {
+      if (disabled) return render('set');
+      take(i);
+      render(dragging === i ? 'drag' : 'glide');
+      const before = committed.join();
+      commit(true);
+      if (committed.join() !== before) trackEffect(press(output));
+    });
+    scope.on(input, 'pointerdown', () => {
+      if (disabled) return;
+      dragging = i;
+      grow(i, true);
+      bubbleFor(i, true);
+      const release = () => {
+        removeEventListener('pointerup', release);
+        removeEventListener('pointercancel', release);
+        if (dragging !== i) return;
+        dragging = -1;
+        grow(i, false);
+        if (document.activeElement !== input || !input.matches(':focus-visible')) bubbleFor(i, false);
+      };
+      addEventListener('pointerup', release);
+      addEventListener('pointercancel', release);
+      scope.add(release);
+    });
+    scope.on(input, 'focus', () => {
+      thumbs[i]!.thumb.toggleAttribute('data-mk-focus', input.matches(':focus-visible'));
+      if (input.matches(':focus-visible')) bubbleFor(i, true);
+    });
+    scope.on(input, 'blur', () => {
+      thumbs[i]!.thumb.removeAttribute('data-mk-focus');
+      if (dragging !== i) bubbleFor(i, false);
+    });
+  });
+  const form = first?.form;
+  if (form) {
+    scope.on(form, 'reset', (event) => {
+      // The native reset writes the default values after its listeners: read them next.
+      scope.timeout(() => {
+        if (event.defaultPrevented || scope.disposed) return;
+        const restored = read().map((n, i) => (Number.isFinite(n) ? n : i === 0 ? min : upper));
+        values = ordered(restored);
+        committed = [...values];
+        render('glide');
+      }, 0);
+    });
+  }
+  render('set');
+
+  return {
+    setValue(next, notify = true) {
+      if (scope.disposed) return;
+      const list = Array.isArray(next) ? next : [next, next];
+      const candidate = inputs.map((_, i) => (finite(list[i]) ? normalize(list[i]!) : values[i]!));
+      values = ordered(candidate);
+      // A controlled parent echoing the drag follows tightly; anything else glides.
+      render(dragging >= 0 ? 'drag' : 'glide');
+      // Silent sets (a controlled parent echoing a drag) leave the committed value alone,
+      // so the user's change still reports.
+      if (notify) commit(true);
+    },
+    get value() {
+      return current();
+    },
+    destroy: () => scope.dispose(),
+  };
+}