@yewdiel21/motion-kit 0.10.0 → 0.15.0

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(),
+  };
+}

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

@@ -0,0 +1,191 @@
+/* range-slider — Melonmind line: a neutral track, the accent for the chosen span, white thumbs with a soft
+   shadow and a glass value bubble. The native thumbs stay as transparent hit areas; the engine draws and moves the rest. */
+.mk-range-slider,
+mk-range-slider {
+  --mk-range-thumb: 1.5rem;
+  --mk-range-height: 8px;
+  --mk-range-track: var(--mk-surface-4);
+  --mk-range-fill: var(--mk-accent);
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto;
+  align-items: center;
+  gap: 1rem;
+  color: var(--mk-text);
+  font-family: var(--mk-font);
+}
+
+:is(.mk-range-slider, mk-range-slider) [data-mk-range-track] {
+  position: relative;
+  display: grid;
+  align-items: center;
+  min-width: 0;
+  height: 2.75rem;
+}
+
+:is(.mk-range-slider, mk-range-slider) [data-mk-range-visual] {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+}
+
+/* Track */
+:is(.mk-range-slider, mk-range-slider) [data-mk-range-visual]::before {
+  content: '';
+  position: absolute;
+  top: 50%;
+  inset-inline: 0;
+  height: var(--mk-range-height);
+  border-radius: var(--mk-radius-full);
+  background: var(--mk-range-track);
+  translate: 0 -50%;
+}
+
+/* The span between the thumb centres. */
+:is(.mk-range-slider, mk-range-slider) [data-mk-part='fill'] {
+  position: absolute;
+  top: 50%;
+  left: calc((100% - var(--mk-range-thumb)) * var(--mk-range-start, 0) + var(--mk-range-thumb) / 2);
+  right: calc(100% - ((100% - var(--mk-range-thumb)) * var(--mk-range-end, 0) + var(--mk-range-thumb) / 2));
+  height: var(--mk-range-height);
+  border-radius: var(--mk-radius-full);
+  background: var(--mk-range-fill);
+  translate: 0 -50%;
+}
+
+:is(.mk-range-slider, mk-range-slider)[data-mk-range='single'] [data-mk-part='fill'] {
+  left: 0;
+}
+
+:is(.mk-range-slider, mk-range-slider) [data-mk-part='thumb'] {
+  position: absolute;
+  top: 50%;
+  left: calc((100% - var(--mk-range-thumb)) * var(--mk-range-start, 0) + var(--mk-range-thumb) / 2);
+  width: var(--mk-range-thumb);
+  height: var(--mk-range-thumb);
+  margin: calc(var(--mk-range-thumb) / -2) 0 0 calc(var(--mk-range-thumb) / -2);
+  border-radius: 50%;
+  background: var(--mk-surface-1);
+  box-shadow:
+    0 0 0 1px color-mix(in srgb, var(--mk-text) 8%, transparent),
+    0 2px 8px color-mix(in srgb, var(--mk-shadow-color) 22%, transparent);
+}
+
+/* Single value: its one thumb sits at the end of the fill. */
+:is(.mk-range-slider, mk-range-slider) [data-mk-part='thumb']:last-child {
+  left: calc((100% - var(--mk-range-thumb)) * var(--mk-range-end, 0) + var(--mk-range-thumb) / 2);
+}
+
+:is(.mk-range-slider, mk-range-slider) [data-mk-part='thumb']::after {
+  content: '';
+  position: absolute;
+  inset: 30%;
+  border-radius: 50%;
+  background: var(--mk-range-fill);
+}
+
+:is(.mk-range-slider, mk-range-slider) [data-mk-part='thumb'][data-mk-focus] {
+  box-shadow:
+    0 0 0 4px color-mix(in srgb, var(--mk-accent) 35%, transparent),
+    0 2px 8px color-mix(in srgb, var(--mk-shadow-color) 22%, transparent);
+}
+
+:is(.mk-range-slider, mk-range-slider) [data-mk-part='bubble'] {
+  position: absolute;
+  bottom: calc(100% + 10px);
+  left: 50%;
+  min-width: 2.5rem;
+  padding: 0.25rem 0.6rem;
+  width: max-content;
+  translate: -50% 0;
+  border-radius: var(--mk-radius-full);
+  background: var(--mk-glass-inverse);
+  box-shadow: var(--mk-glass-bevel);
+  backdrop-filter: blur(16px);
+  color: var(--mk-on-glass-inverse);
+  font-size: 0.8125rem;
+  font-weight: 500;
+  font-variant-numeric: tabular-nums;
+  text-align: center;
+  white-space: nowrap;
+  opacity: 0;
+}
+
+/* The native inputs: transparent, the same size, on top for pointer and keyboard. */
+:is(.mk-range-slider, mk-range-slider) [data-mk-range-track] input[type='range'] {
+  position: absolute;
+  inset: 0;
+  z-index: 1;
+  width: 100%;
+  height: 100%;
+  margin: 0;
+  background: transparent;
+  appearance: none;
+  -webkit-appearance: none;
+  cursor: grab;
+}
+
+:is(.mk-range-slider, mk-range-slider) [data-mk-range-track] input[type='range']:active {
+  cursor: grabbing;
+}
+
+:is(.mk-range-slider, mk-range-slider)[data-mk-range='interval'] [data-mk-range-track] input[type='range'] {
+  pointer-events: none;
+}
+
+:is(.mk-range-slider, mk-range-slider) input[type='range']::-webkit-slider-runnable-track {
+  height: 100%;
+  background: transparent;
+}
+
+:is(.mk-range-slider, mk-range-slider) input[type='range']::-moz-range-track {
+  background: transparent;
+}
+
+:is(.mk-range-slider, mk-range-slider) input[type='range']::-webkit-slider-thumb {
+  -webkit-appearance: none;
+  appearance: none;
+  width: var(--mk-range-thumb);
+  height: 2.75rem;
+  border: 0;
+  background: transparent;
+  pointer-events: auto;
+}
+
+:is(.mk-range-slider, mk-range-slider) input[type='range']::-moz-range-thumb {
+  width: var(--mk-range-thumb);
+  height: 2.75rem;
+  border: 0;
+  border-radius: 0;
+  background: transparent;
+  pointer-events: auto;
+}
+
+:is(.mk-range-slider, mk-range-slider) input[type='range']:focus-visible {
+  outline: none;
+}
+
+:is(.mk-range-slider, mk-range-slider) input[type='range']:disabled {
+  cursor: not-allowed;
+}
+
+:is(.mk-range-slider, mk-range-slider):has(input:disabled) [data-mk-range-visual] {
+  opacity: 0.45;
+}
+
+:is(.mk-range-slider, mk-range-slider) [data-mk-range-output] {
+  min-width: 4ch;
+  padding: 0.4rem 0.85rem;
+  border-radius: var(--mk-radius-full);
+  background: var(--mk-surface-3);
+  font-size: 0.875rem;
+  font-weight: 500;
+  font-variant-numeric: tabular-nums;
+  text-align: center;
+  white-space: nowrap;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :is(.mk-range-slider, mk-range-slider) [data-mk-part='thumb'][data-mk-active] [data-mk-part='bubble'] {
+    opacity: 1;
+  }
+}

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

@@ -0,0 +1,66 @@
+'use client';
+import { useRef, type HTMLAttributes } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createRangeSlider, type RangeSliderInstance, type RangeSliderOptions, type RangeValue } from './engine';
+
+export interface RangeSliderProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'onInput' | 'defaultValue'>, RangeSliderOptions {
+  /** Uncontrolled start; an array makes an interval. */
+  defaultValue?: RangeValue;
+  /** Show the formatted value beside the track (default true). */
+  showOutput?: boolean;
+}
+
+/**
+ * <RangeSlider min={0} max={100} defaultValue={[20, 80]} label="Precio" onChange={setRange} />.
+ * Controlled with `value`; otherwise the edited value survives rerenders and new bounds.
+ */
+export function RangeSlider({ min, max, step, value, defaultValue, disabled, name, label, formatValue, onInput, onChange, showOutput = true, className, ...props }: RangeSliderProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const instance = useRef<RangeSliderInstance | null>(null);
+  const edited = useRef<RangeValue | undefined>(undefined);
+  const input = useLatest(onInput);
+  const change = useLatest(onChange);
+  const format = useLatest(formatValue);
+  const formatted = formatValue !== undefined;
+  const start = value ?? defaultValue;
+  const count = Array.isArray(start) ? 2 : 1;
+  const current = useLatest(value);
+  useIsomorphicLayoutEffect(() => {
+    const created = createRangeSlider(ref.current, {
+      min,
+      max,
+      step,
+      disabled,
+      name,
+      label,
+      value: current.current ?? edited.current ?? start,
+      formatValue: formatted ? (n) => format.current?.(n) ?? String(n) : undefined,
+      onInput: (next) => input.current?.(next),
+      onChange: (next) => change.current?.(next),
+    });
+    instance.current = created;
+    return () => {
+      edited.current = created.value;
+      created.destroy();
+      instance.current = null;
+    };
+    // `start` only seeds the first creation; edits and `value` take over after it.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [min, max, step, disabled, name, label, formatted, count]);
+  const valueKey = JSON.stringify(value);
+  useIsomorphicLayoutEffect(() => {
+    if (value !== undefined) instance.current?.setValue(value, false);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [valueKey]);
+  const initial = Array.isArray(start) ? start : [start ?? min ?? 0];
+  return (
+    <div {...props} ref={ref} className={['mk-range-slider', className].filter(Boolean).join(' ')}>
+      <div data-mk-range-track="">
+        {initial.map((n, i) => (
+          <input key={i} type="range" data-mk-range-input="" defaultValue={n} />
+        ))}
+      </div>
+      {showOutput && <output data-mk-range-output="" />}
+    </div>
+  );
+}

package/src/components/resizable-panel/README.md

@@ -0,0 +1,61 @@
+# resizable-panel
+
+Paneles redimensionables con divisores arrastrables, uno al lado del otro o apilados. Cada divisor es una línea fina con un asa que crece y toma el color de acento al pasar el puntero, al enfocarlo y al arrastrarlo; mientras se mueve, una burbuja muestra los dos tamaños («32 % · 68 %»). Funciona con mouse, lápiz y pantalla táctil.
+
+Al llegar al límite de un panel, el arrastre cede solo una cuarta parte del camino (efecto goma) y al soltarlo vuelve con un resorte (.45 s, curva swing). Un panel plegable arrastrado muy por debajo de su mínimo se cierra de golpe (.3 s, curva swing) y se vuelve a abrir si lo arrastras de regreso, con Intro sobre su divisor o con los botones del divisor (`handleButtons`). Doble clic en un divisor devuelve los tamaños iniciales (.45 s, curva signature). Los tamaños se pueden recordar entre visitas (`storageKey`).
+
+## HTML / Astro
+
+```html
+<mk-resizable-panel class="mk-resizable-panel" sizes="22,48,30" collapsible="2" handle-buttons storage-key="correo">
+  <aside data-label="Carpetas" data-min="15">…</aside>
+  <main data-label="Mensajes">…</main>
+  <section data-label="Vista previa" data-min="20">…</section>
+</mk-resizable-panel>
+```
+
+Cada panel puede llevar `data-size`, `data-min`, `data-max` (en %), `data-collapsible` y `data-label`. Conviene poner el relleno (`padding`) en un elemento interior: un panel cerrado no conserva el suyo.
+
+## React
+
+```tsx
+const panels = useRef<ResizablePanelHandle>(null);
+
+<ResizablePanel ref={panels} sizes={[25, 75]} collapsible={[0]} handleButtons onResizeEnd={guardar} style={{ height: 420 }}>
+  <aside>…</aside>
+  <main>…</main>
+</ResizablePanel>;
+
+panels.current?.toggle(0);
+```
+
+Unos `sizes` nuevos se deslizan hasta ahí; agregar o quitar un panel reinicia el componente.
+
+## Opciones
+
+| Opción | Atributo | Por defecto | Qué hace |
+|---|---|---|---|
+| `orientation` | `orientation` | `'horizontal'` | `'horizontal'`: lado a lado; `'vertical'`: apilados. |
+| `sizes` | `sizes` (lista con comas) | `data-size`, si no, iguales | Tamaños en %; los que falten se reparten lo que sobra. |
+| `min` / `max` | `min` / `max` | `10` / `100` | Límites en % (los `data-min` y `data-max` de cada panel mandan). |
+| `collapsible` | `collapsible` (índices) | `[]` | Paneles que se cierran al arrastrarlos más allá de la mitad de su mínimo. |
+| `collapsed` | `collapsed` (índices) | `[]` | Paneles cerrados al empezar. |
+| `step` | `step` | `5` | Lo que mueven las flechas (Mayús: el cuádruple). |
+| `storageKey` | `storage-key` | — | Recordar tamaños y paneles cerrados en `localStorage`. |
+| `handleButtons` | `handle-buttons` | `false` | Botones en los divisores para cerrar y abrir los paneles de al lado. |
+| `labels` | `labels` (lista) | `data-label` | Nombres de los paneles para las etiquetas de los divisores. |
+| `onResize(sizes)` | — | — | Mientras cambia (una vez por cuadro). |
+| `onResizeEnd(sizes)` | — | — | Al terminar un arrastre, una tecla o una animación. |
+| `onCollapse(index, closed)` | — | — | Un panel se cerró o se abrió. |
+
+## API y eventos
+
+`setSizes(sizes, animate = true)`, `collapse(index)`, `expand(index)`, `toggle(index)`, `reset()`, `setOrientation(orientation)`, `sizes`, `collapsed`, `orientation`, `destroy()`. Eventos `mk:resize` con `{ sizes }` y `mk:collapse` con `{ index, collapsed }`.
+
+## Teclado
+
+Sobre un divisor: ← → (o ↑ ↓ si están apilados) mueven el 5 %, con Mayús el 20 %; Inicio y Fin llevan el panel a sus límites; Intro cierra o abre el panel plegable de al lado. En un límite, el asa se sacude un poco.
+
+## Accesibilidad
+
+Patrón *window splitter* de WAI-ARIA: cada divisor es un `separator` enfocable con `aria-valuenow`, `aria-valuemin`, `aria-valuemax`, un texto («40 %, cerrado»), `aria-controls` apuntando al panel anterior y una etiqueta con los nombres de los dos paneles. Un panel cerrado queda oculto también para los lectores de pantalla, y un estado discreto anuncia cada cierre y apertura. Con movimiento reducido los cambios son inmediatos.