@yewdiel21/motion-kit 0.9.1 → 0.10.0

package/src/components/slot-picker/README.md

@@ -0,0 +1,68 @@
+# slot-picker
+
+El selector de citas de Melon Mind («Agendar cita»): a la izquierda un mes compacto y a la derecha los horarios del día elegido. Sirve para reservas, citas o mesas.
+
+- **Cambiar de día:** los horarios salen 30 px hacia un lado y entran 30 px desde el otro (0.25 s `ease-out`), en la dirección del cambio. El original usa una View Transition `time-slot`.
+- **Primera lista:** entra creciendo (escala .7, blur 32 → 0, 0.3 s `cubic-bezier(.38,.49,0,1.1)`), 20 ms entre horarios.
+- **Encabezado del día:** se abre de 0 a 56 px en 0.5 s `cubic-bezier(.38,.49,0,1.4)`.
+- **Horario elegido:** se ilumina en 0.7 s (escala .8 → 1, blur 16 → 0).
+- **Cambiar de mes:** los días se deslizan igual que los horarios.
+
+Origen: REA de la app de Melon Mind (`appt-creator.css`, `schedulePicker.css`, `CreateApptManager.js`).
+
+## HTML / Astro
+
+```html
+<mk-slot-picker class="mk-slot-picker" locale="es" min="2026-10-23" closed-days="[0]"
+  slots='["09:00","10:00","11:30","16:00","17:30"]'>
+  <div class="mk-slot-picker__calendar">
+    <div class="mk-slot-picker__month">
+      <h3 class="mk-slot-picker__title" data-mk-slot-title></h3>
+      <button type="button" class="mk-slot-picker__nav" data-mk-slot-prev aria-label="Mes anterior">←</button>
+      <button type="button" class="mk-slot-picker__nav" data-mk-slot-next aria-label="Mes siguiente">→</button>
+    </div>
+    <div data-mk-slot-days></div>
+  </div>
+  <div class="mk-slot-picker__panel">
+    <p class="mk-slot-picker__heading" data-mk-slot-heading></p>
+    <div data-mk-slot-times></div>
+    <input type="hidden" name="cita" data-mk-slot-value>
+  </div>
+</mk-slot-picker>
+```
+
+El input oculto `[data-mk-slot-value]` lleva `YYYY-MM-DDTHH:mm` y emite `input`/`change`, así que funciona dentro de un `<form>`. Si cambias el atributo `slots`, la lista se actualiza sin perder el día. Sin custom element: `createSlotPicker(root, opciones)`.
+
+## React
+
+```tsx
+<SlotPicker
+  name="cita"
+  min={new Date()}
+  closedDays={[0]}
+  slots={(day) => fetch(`/api/horarios?dia=${dayKey(day)}`).then((r) => r.json())}
+  onChange={({ value }) => setCita(value)}
+  actions={<button className="mk-button">Agendar</button>}
+/>
+```
+
+## Opciones
+
+| Opción | Atributo | Por defecto | Qué hace |
+|---|---|---|---|
+| `slots` | `slots` (JSON) | `[]` | Lista igual todos los días, mapa `{"2026-10-23": [...]}` o función `(día) => lista \| Promise<lista>`. Horas `HH:mm` |
+| `date` | `date` | hoy | Mes inicial (y día elegido si no hay `value`) |
+| `value` | `value` | — | `"2026-10-23T10:30"` o `{ date, time }` |
+| `min`, `max` | `min`, `max` | — | Días fuera de rango deshabilitados; flechas de mes limitadas |
+| `closedDays` | `closed-days` (JSON) | `[]` | Días de la semana cerrados (0 = domingo) |
+| `isDisabled(date)` | — | — | Regla propia |
+| `firstDay` | `first-day` | `0` | Primer día de la semana |
+| `locale` | `locale` | `'es'` | Nombres de mes y día |
+| `labels` | — | español | `placeholder`, `empty`, `loading`, `heading(date)` |
+| `onChange({date, time, key, value})`, `onDateChange(date)` | — | — | Callbacks |
+
+API: `selectDate(d)`, `selectTime(t | null)`, `setSlots(fuente)`, `date`, `time`, `value`, `destroy()`. `mk:change` lleva `{date, time, key, value}`. Si los horarios llegan por promesa, mientras cargan se muestra `loading` con `aria-busy`, y una respuesta vieja nunca pisa a la más reciente.
+
+## Accesibilidad
+
+Los días forman una rejilla ARIA con foco móvil: flechas, Inicio/Fin y RePág/AvPág para cambiar de mes. Los horarios son un `radiogroup`: las flechas mueven la selección, y el grupo está etiquetado por el encabezado del día. Los días deshabilitados son botones `disabled`. Con movimiento reducido no hay deslizamiento, entradas ni resaltado animado.

package/src/components/slot-picker/element.ts

@@ -0,0 +1,27 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createSlotPicker, type SlotPickerInstance, type SlotSource } from './engine';
+
+/** Light DOM: supply the [data-mk-slot-days] and [data-mk-slot-times] markup shown in the README. */
+export class MkSlotPickerElement extends MkElement<SlotPickerInstance> {
+  static options: Record<string, OptionType> = {
+    date: 'string', value: 'string', slots: 'json', min: 'string', max: 'string', closedDays: 'json', firstDay: 'number', locale: 'string',
+  };
+
+  protected create(options: Record<string, unknown>) {
+    return createSlotPicker(this, options);
+  }
+
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.isConnected || !this.instance) return;
+    if (name === 'slots') {
+      this.instance.setSlots((this.options.slots as SlotSource | undefined) ?? []);
+      return;
+    }
+    // Keep the visitor's pick unless the value itself changed.
+    const value = this.instance.value ?? (this.instance.date ? this.instance.date : undefined);
+    this.instance.destroy();
+    this.instance = this.create({ ...(name !== 'value' && value ? (typeof value === 'string' ? { value } : { date: value }) : {}), ...this.options });
+  }
+}
+
+export const defineSlotPicker = () => defineElement('mk-slot-picker', MkSlotPickerElement);

package/src/components/slot-picker/engine.ts

@@ -0,0 +1,412 @@
+import { CustomEase, gsap, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import {
+  addDays, addMonths, capitalize, clampFirstDay, dayKey, monthWeeks, safeFormat, sameDay, sameMonth,
+  fromJson, startOfWeek, toDate, weekdayNames, type DateInput,
+} from '../../core/dates';
+import { flowIn } from '../../motion/flow';
+
+/*
+ * Slot picker (Melon Mind "Agendar cita"): a compact month on one side and the
+ * day's times on the other. From the reference: changing day slides the times
+ * out −30 px and the new ones in from +30 px, .25 s ease-out (view transition
+ * "time-slot", schedulePicker.css); the first list grows in (scale .7, blur 32,
+ * .3 s cubic-bezier(.38,.49,0,1.1)); the day heading opens 0 → 56 px in .5 s
+ * cubic-bezier(.38,.49,0,1.4) and a picked time lights up in .7 s
+ * (animation-highlight-1). Month changes slide the days the same way.
+ */
+
+export type SlotSource = string[] | Record<string, string[]> | ((date: Date) => string[] | Promise<string[]>);
+
+export interface SlotValue { date: Date; time: string; key: string; value: string }
+
+export interface SlotPickerLabels {
+  placeholder?: string;
+  empty?: string;
+  loading?: string;
+  heading?: (date: Date) => string;
+}
+
+export interface SlotPickerOptions {
+  /** Month shown first (and the selected day when `value` is not given). */
+  date?: DateInput;
+  /** Initial value: "2026-10-23T10:30" or { date, time }. */
+  value?: string | { date: DateInput; time: string } | null;
+  slots?: SlotSource;
+  min?: DateInput;
+  max?: DateInput;
+  /** Weekdays never available (0 = Sunday). */
+  closedDays?: number[];
+  isDisabled?: (date: Date) => boolean;
+  firstDay?: number;
+  locale?: string;
+  labels?: SlotPickerLabels;
+  onChange?: (value: SlotValue) => void;
+  onDateChange?: (date: Date) => void;
+}
+
+export interface SlotPickerInstance extends Instance {
+  selectDate(date: DateInput): void;
+  selectTime(time: string | null): void;
+  setSlots(slots: SlotSource): void;
+  readonly date: Date | null;
+  readonly time: string | null;
+  readonly value: string | null;
+}
+
+const SLIDE = 30;
+const SLIDE_DURATION = 0.25;
+let slotEaseReady = false;
+
+export function createSlotPicker(root: HTMLElement | null, options: SlotPickerOptions = {}): SlotPickerInstance {
+  const daysHost = root?.querySelector<HTMLElement>('[data-mk-slot-days]');
+  const timesHost = root?.querySelector<HTMLElement>('[data-mk-slot-times]');
+  if (!root || !daysHost || !timesHost) {
+    return inert({ selectDate() {}, selectTime() {}, setSlots() {}, date: null, time: null, value: null });
+  }
+  registerMotion();
+  if (!slotEaseReady && typeof window !== 'undefined') {
+    CustomEase.create('mk-slot-in', '.38,.49,0,1.1');
+    slotEaseReady = true;
+  }
+  const scope = createScope();
+  const ctx = gsap.context(() => {});
+  scope.add(() => ctx.revert());
+  const locale = options.locale ?? 'es';
+  const firstDay = clampFirstDay(options.firstDay);
+  const labels = {
+    placeholder: options.labels?.placeholder ?? 'Elige un día para ver los horarios.',
+    empty: options.labels?.empty ?? 'No hay horarios este día.',
+    loading: options.labels?.loading ?? 'Cargando horarios…',
+    heading: options.labels?.heading ?? ((d: Date) => capitalize(safeFormat(locale, { weekday: 'long', day: 'numeric', month: 'long' }).format(d))),
+  };
+  const min = options.min !== undefined ? toDate(options.min) : null;
+  const max = options.max !== undefined ? toDate(options.max) : null;
+  const closedList = fromJson<number[]>(options.closedDays);
+  const closed = new Set((Array.isArray(closedList) ? closedList : []).filter((n) => Number.isInteger(n)));
+  let slots: SlotSource = fromJson<SlotSource>(options.slots) ?? [];
+
+  const initial = (() => {
+    const v = options.value;
+    if (typeof v === 'string') {
+      const match = /^(\d{4}-\d{2}-\d{2})(?:T(\d{1,2}:\d{2}))?/.exec(v);
+      return match ? { date: toDate(match[1]), time: match[2] ?? null } : null;
+    }
+    return v ? { date: toDate(v.date), time: v.time ?? null } : null;
+  })();
+  let month = initial?.date ?? toDate(options.date);
+  let date: Date | null = initial?.date ?? (options.date !== undefined ? toDate(options.date) : null);
+  let time: string | null = initial?.time ?? null;
+  let focusDay = date ?? month;
+  let times: string[] = [];
+  let request = 0;
+
+  const title = root.querySelector<HTMLElement>('[data-mk-slot-title]');
+  const heading = root.querySelector<HTMLElement>('[data-mk-slot-heading]');
+  const prev = root.querySelector<HTMLButtonElement>('[data-mk-slot-prev]');
+  const next = root.querySelector<HTMLButtonElement>('[data-mk-slot-next]');
+  const output = root.querySelector<HTMLInputElement>('[data-mk-slot-value]');
+  const originals = [daysHost, timesHost, title, heading].filter(Boolean).map((el) => [el!, [...el!.childNodes]] as const);
+  scope.add(() => originals.forEach(([el, nodes]) => el.replaceChildren(...nodes)));
+  if (output) {
+    const before = output.value;
+    scope.add(() => { output.value = before; });
+  }
+  scope.attr(root, 'data-mk-ready', '');
+  scope.attr(daysHost, 'role', 'grid');
+  scope.attr(timesHost, 'role', 'radiogroup');
+  if (heading) {
+    if (!heading.id) scope.attr(heading, 'id', `mk-slot-${Math.random().toString(36).slice(2, 8)}`);
+    scope.attr(timesHost, 'aria-labelledby', heading.id);
+  }
+  if (title) {
+    if (!title.id) scope.attr(title, 'id', `mk-slot-month-${Math.random().toString(36).slice(2, 8)}`);
+    scope.attr(daysHost, 'aria-labelledby', title.id);
+  }
+
+  const monthTitle = safeFormat(locale, { month: 'long', year: 'numeric' });
+  const fullDay = safeFormat(locale, { weekday: 'long', day: 'numeric', month: 'long', year: 'numeric' });
+  const disabled = (d: Date) => (min && d < min) || (max && d > max) || closed.has(d.getDay()) || !!options.isDisabled?.(d);
+
+  /* ── Days ───────────────────────────────────────────── */
+  let daysBody: HTMLElement | null = null;
+  const leaving = new Set<HTMLElement>();
+  scope.add(() => leaving.forEach((el) => el.remove()));
+  const buildDays = () => {
+    const wrap = document.createElement('div');
+    wrap.className = 'mk-slot-picker__days';
+    wrap.setAttribute('role', 'rowgroup');
+    const head = document.createElement('div');
+    head.className = 'mk-slot-picker__weekdays';
+    head.setAttribute('role', 'row');
+    for (const name of weekdayNames(locale, firstDay, 'short')) {
+      const cell = document.createElement('span');
+      cell.setAttribute('role', 'columnheader');
+      cell.textContent = name.slice(0, 2);
+      head.append(cell);
+    }
+    wrap.append(head);
+    const focusKey = dayKey(focusDay);
+    for (const week of monthWeeks(month, firstDay)) {
+      const row = document.createElement('div');
+      row.className = 'mk-slot-picker__week';
+      row.setAttribute('role', 'row');
+      for (const d of week) {
+        const cell = document.createElement('span');
+        cell.setAttribute('role', 'gridcell');
+        if (!sameMonth(d, month)) {
+          row.append(cell);
+          continue;
+        }
+        const button = document.createElement('button');
+        button.type = 'button';
+        button.className = 'mk-slot-picker__day';
+        button.dataset.mkSlotDay = dayKey(d);
+        button.textContent = String(d.getDate());
+        button.tabIndex = dayKey(d) === focusKey ? 0 : -1;
+        button.setAttribute('aria-label', capitalize(fullDay.format(d)));
+        if (disabled(d)) button.disabled = true;
+        if (sameDay(d, new Date())) button.setAttribute('aria-current', 'date');
+        cell.setAttribute('aria-selected', String(sameDay(d, date)));
+        cell.append(button);
+        row.append(cell);
+      }
+      wrap.append(row);
+    }
+    return wrap;
+  };
+  const renderDays = (direction: number) => {
+    const fresh = buildDays();
+    if (title) title.textContent = capitalize(monthTitle.format(month));
+    // No earlier month when its last day is before `min`; no later one when its first day is after `max`.
+    if (prev) scope.attr(prev, 'disabled', min && new Date(month.getFullYear(), month.getMonth(), 0) < min ? '' : null);
+    if (next) scope.attr(next, 'disabled', max && new Date(month.getFullYear(), month.getMonth() + 1, 1) > max ? '' : null);
+    if (daysBody && direction && !reduced()) {
+      const old = daysBody;
+      old.style.top = `${old.offsetTop}px`;
+      old.classList.add('mk-slot-picker__leaving');
+      old.setAttribute('aria-hidden', 'true');
+      leaving.add(old);
+      daysHost.append(fresh);
+      ctx.add(() => {
+        gsap.to(old, { x: -SLIDE * direction, opacity: 0, duration: SLIDE_DURATION, ease: 'power1.out', onComplete: () => { old.remove(); leaving.delete(old); } });
+        gsap.fromTo(fresh, { x: SLIDE * direction, opacity: 0 }, { x: 0, opacity: 1, duration: SLIDE_DURATION, ease: 'power1.out', clearProps: 'transform,opacity' });
+      });
+    } else if (daysBody) daysBody.replaceWith(fresh);
+    else daysHost.replaceChildren(fresh);
+    daysBody = fresh;
+  };
+  const dayButton = (d: Date) => daysHost.querySelector<HTMLButtonElement>(`.mk-slot-picker__days:not(.mk-slot-picker__leaving) [data-mk-slot-day="${dayKey(d)}"]`);
+  const moveFocus = (to: Date, focus: boolean) => {
+    focusDay = to;
+    if (!sameMonth(to, month)) {
+      const direction = to > month ? 1 : -1;
+      month = to;
+      renderDays(direction);
+    } else daysHost.querySelectorAll<HTMLButtonElement>('[data-mk-slot-day]').forEach((b) => (b.tabIndex = b.dataset.mkSlotDay === dayKey(to) ? 0 : -1));
+    if (focus) dayButton(to)?.focus();
+  };
+
+  /* ── Times ──────────────────────────────────────────── */
+  let timesBody: HTMLElement | null = null;
+  let firstList = true;
+  const buildTimes = (state: 'placeholder' | 'loading' | 'ready') => {
+    const wrap = document.createElement('div');
+    wrap.className = 'mk-slot-picker__list';
+    if (state !== 'ready' || !times.length) {
+      const note = document.createElement('p');
+      note.className = 'mk-slot-picker__note';
+      note.textContent = state === 'placeholder' ? labels.placeholder : state === 'loading' ? labels.loading : labels.empty;
+      wrap.append(note);
+      return wrap;
+    }
+    const focusTime = time && times.includes(time) ? time : times[0];
+    for (const t of times) {
+      const button = document.createElement('button');
+      button.type = 'button';
+      button.className = 'mk-slot-picker__time';
+      button.setAttribute('role', 'radio');
+      button.dataset.mkSlotTime = t;
+      button.textContent = t;
+      button.setAttribute('aria-checked', String(t === time));
+      button.tabIndex = t === focusTime ? 0 : -1;
+      wrap.append(button);
+    }
+    return wrap;
+  };
+  const renderTimes = (state: 'placeholder' | 'loading' | 'ready', direction: number) => {
+    const fresh = buildTimes(state);
+    scope.attr(timesHost, 'aria-busy', state === 'loading' ? 'true' : null);
+    const motion = !reduced();
+    if (timesBody && direction && motion) {
+      const old = timesBody;
+      old.style.top = `${old.offsetTop}px`;
+      old.classList.add('mk-slot-picker__leaving');
+      old.setAttribute('aria-hidden', 'true');
+      old.querySelectorAll('button').forEach((b) => (b.tabIndex = -1));
+      leaving.add(old);
+      timesHost.append(fresh);
+      ctx.add(() => {
+        gsap.to(old, { x: -SLIDE * direction, opacity: 0, duration: SLIDE_DURATION, ease: 'power1.out', onComplete: () => { old.remove(); leaving.delete(old); } });
+        gsap.fromTo(fresh, { x: SLIDE * direction, opacity: 0 }, { x: 0, opacity: 1, duration: SLIDE_DURATION, ease: 'power1.out', clearProps: 'transform,opacity' });
+      });
+    } else if (timesBody) timesBody.replaceWith(fresh);
+    else timesHost.replaceChildren(fresh);
+    timesBody = fresh;
+    if (state === 'ready' && times.length && motion && firstList) {
+      firstList = false;
+      ctx.add(() => flowIn(fresh, { target: '.mk-slot-picker__time', style: 2, startScale: 0.7, blur: 32, duration: 0.3, stagger: 0.02, ease: 'mk-slot-in' }));
+    }
+  };
+  const resolve = (d: Date): string[] | Promise<string[]> => {
+    const source = slots;
+    if (Array.isArray(source)) return source;
+    if (typeof source === 'function') return source(d);
+    return source?.[dayKey(d)] ?? [];
+  };
+  const clean = (list: unknown) => (Array.isArray(list) ? [...new Set(list.filter((t): t is string => typeof t === 'string' && /^\d{1,2}:\d{2}$/.test(t)))] : []);
+  const load = (direction: number) => {
+    if (!date) {
+      times = [];
+      renderTimes('placeholder', 0);
+      return;
+    }
+    const mine = ++request;
+    let result: string[] | Promise<string[]>;
+    try {
+      result = resolve(date);
+    } catch {
+      result = [];
+    }
+    if (result && typeof (result as Promise<string[]>).then === 'function') {
+      renderTimes('loading', direction);
+      (result as Promise<string[]>).then(
+        (list) => { if (mine === request && !scope.disposed) { times = clean(list); renderTimes('ready', 0); } },
+        () => { if (mine === request && !scope.disposed) { times = []; renderTimes('ready', 0); } },
+      );
+    } else {
+      times = clean(result);
+      if (time && !times.includes(time)) time = null;
+      renderTimes('ready', direction);
+    }
+  };
+
+  const syncHeading = () => {
+    if (!heading) return;
+    if (date) {
+      heading.textContent = labels.heading(date);
+      if (!heading.hasAttribute('data-mk-shown')) scope.attr(heading, 'data-mk-shown', '');
+    }
+  };
+  const emit = () => {
+    const key = date ? dayKey(date) : '';
+    const value = date && time ? `${key}T${time}` : null;
+    if (output) {
+      output.value = value ?? '';
+      output.dispatchEvent(new Event('input', { bubbles: true }));
+      output.dispatchEvent(new Event('change', { bubbles: true }));
+    }
+    if (date && time && value) {
+      const detail: SlotValue = { date, time, key, value };
+      options.onChange?.(detail);
+      root.dispatchEvent(new CustomEvent('mk:change', { bubbles: true, detail }));
+    }
+  };
+
+  const selectDate = (input: DateInput, notify = true) => {
+    if (scope.disposed) return;
+    const d = toDate(input);
+    if (disabled(d)) return;
+    const direction = date ? Math.sign(d.getTime() - date.getTime()) : 0;
+    if (sameDay(d, date)) return;
+    date = d;
+    time = null;
+    focusDay = d;
+    if (!sameMonth(d, month)) {
+      const dir = d > month ? 1 : -1;
+      month = d;
+      renderDays(dir);
+    }
+    daysHost.querySelectorAll<HTMLElement>('[role="gridcell"]').forEach((cell) => {
+      const b = cell.querySelector<HTMLButtonElement>('[data-mk-slot-day]');
+      if (b) {
+        cell.setAttribute('aria-selected', String(b.dataset.mkSlotDay === dayKey(d)));
+        b.tabIndex = b.dataset.mkSlotDay === dayKey(d) ? 0 : -1;
+      }
+    });
+    syncHeading();
+    load(direction);
+    if (notify) {
+      options.onDateChange?.(d);
+      emit();
+    }
+  };
+  const selectTime = (t: string | null, notify = true) => {
+    if (scope.disposed || !date) return;
+    if (t !== null && !times.includes(t)) return;
+    time = t;
+    timesHost.querySelectorAll<HTMLButtonElement>('[data-mk-slot-time]').forEach((b) => {
+      b.setAttribute('aria-checked', String(b.dataset.mkSlotTime === t));
+      b.tabIndex = (t ? b.dataset.mkSlotTime === t : b === timesHost.querySelector('[data-mk-slot-time]')) ? 0 : -1;
+    });
+    if (notify) emit();
+  };
+
+  scope.on(root, 'click', (e) => {
+    const target = (e.target as Element).closest<HTMLButtonElement>('button');
+    if (!target || target.disabled || !root.contains(target)) return;
+    if (target === prev) moveFocus(addMonths(month, -1), false);
+    else if (target === next) moveFocus(addMonths(month, 1), false);
+    else if (target.dataset.mkSlotDay) selectDate(target.dataset.mkSlotDay);
+    else if (target.dataset.mkSlotTime) selectTime(target.dataset.mkSlotTime);
+  });
+  scope.on(daysHost, 'keydown', (e) => {
+    const event = e as KeyboardEvent;
+    const key = (event.target as HTMLElement).dataset?.mkSlotDay;
+    if (!key) return;
+    const d = toDate(key);
+    const to = ({
+      ArrowLeft: () => addDays(d, -1), ArrowRight: () => addDays(d, 1), ArrowUp: () => addDays(d, -7), ArrowDown: () => addDays(d, 7),
+      Home: () => startOfWeek(d, firstDay), End: () => addDays(startOfWeek(d, firstDay), 6),
+      PageUp: () => addMonths(d, -1), PageDown: () => addMonths(d, 1),
+    } as Record<string, () => Date>)[event.key]?.();
+    if (!to) return;
+    event.preventDefault();
+    moveFocus(to, true);
+  });
+  scope.on(timesHost, 'keydown', (e) => {
+    const event = e as KeyboardEvent;
+    const current = (event.target as HTMLElement).dataset?.mkSlotTime;
+    if (!current) return;
+    const i = times.indexOf(current);
+    const to = ({ ArrowRight: i + 1, ArrowDown: i + 1, ArrowLeft: i - 1, ArrowUp: i - 1, Home: 0, End: times.length - 1 } as Record<string, number>)[event.key];
+    if (to === undefined) return;
+    event.preventDefault();
+    const t = times[(to + times.length) % times.length];
+    selectTime(t);
+    timesHost.querySelector<HTMLButtonElement>(`[data-mk-slot-time="${t}"]`)?.focus();
+  });
+
+  renderDays(0);
+  if (date) {
+    syncHeading();
+    load(0);
+    if (time && !times.includes(time)) time = null;
+  } else renderTimes('placeholder', 0);
+
+  return {
+    selectDate: (d) => selectDate(d),
+    selectTime: (t) => selectTime(t),
+    setSlots(source) {
+      if (scope.disposed) return;
+      slots = fromJson<SlotSource>(source) ?? [];
+      load(0);
+    },
+    get date() { return date; },
+    get time() { return time; },
+    get value() { return date && time ? `${dayKey(date)}T${time}` : null; },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/slot-picker/react.tsx

@@ -0,0 +1,76 @@
+'use client';
+
+import { useRef, type HTMLAttributes, type ReactNode } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createSlotPicker, type SlotPickerInstance, type SlotPickerOptions } from './engine';
+
+export interface SlotPickerProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'>, SlotPickerOptions {
+  /** Form field name: a hidden input carries "YYYY-MM-DDTHH:mm". */
+  name?: string;
+  labels?: SlotPickerOptions['labels'] & { previous?: string; next?: string };
+  /** Rendered under the times (e.g. a submit button). */
+  actions?: ReactNode;
+}
+
+export function SlotPicker({
+  date, value, slots, min, max, closedDays, isDisabled, firstDay, locale, labels, onChange, onDateChange,
+  name, actions, className, ...props
+}: SlotPickerProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const instance = useRef<SlotPickerInstance | null>(null);
+  const kept = useRef<string | Date | null>(null);
+  const change = useLatest(onChange);
+  const dateChange = useLatest(onDateChange);
+  const disabledFn = useLatest(isDisabled);
+  // A function source is read through a ref (inline functions do not reload);
+  // lists and maps reload when their content changes.
+  const source = useLatest(slots);
+  const slotsKey = typeof slots === 'function' ? 'function' : JSON.stringify(slots ?? []);
+  const stable = () => {
+    const current = source.current;
+    return typeof current === 'function' ? (d: Date) => (source.current as (day: Date) => string[] | Promise<string[]>)(d) : current ?? [];
+  };
+  useIsomorphicLayoutEffect(() => {
+    const keep = kept.current;
+    const created = createSlotPicker(ref.current, {
+      date: date ?? (keep instanceof Date ? keep : undefined),
+      value: value !== undefined ? value : typeof keep === 'string' ? keep : undefined,
+      slots: stable(), min, max, closedDays, firstDay, locale, labels,
+      isDisabled: (d) => disabledFn.current?.(d) ?? false,
+      onChange: (v) => change.current?.(v),
+      onDateChange: (d) => dateChange.current?.(d),
+    });
+    instance.current = created;
+    return () => {
+      kept.current = created.value ?? created.date;
+      created.destroy();
+      instance.current = null;
+    };
+    // `slots` updates in place; the rest recreates the picker.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [date, value, min, max, firstDay, locale, JSON.stringify(closedDays ?? [])]);
+  const firstSlots = useRef(true);
+  useIsomorphicLayoutEffect(() => {
+    if (firstSlots.current) { firstSlots.current = false; return; }
+    instance.current?.setSlots(stable());
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [slotsKey]);
+  return (
+    <div {...props} ref={ref} className={['mk-slot-picker', className].filter(Boolean).join(' ')}>
+      <div className="mk-slot-picker__calendar">
+        <div className="mk-slot-picker__month">
+          <h3 className="mk-slot-picker__title" data-mk-slot-title />
+          <button type="button" className="mk-slot-picker__nav" data-mk-slot-prev aria-label={labels?.previous ?? 'Mes anterior'}>←</button>
+          <button type="button" className="mk-slot-picker__nav" data-mk-slot-next aria-label={labels?.next ?? 'Mes siguiente'}>→</button>
+        </div>
+        <div data-mk-slot-days />
+      </div>
+      <div className="mk-slot-picker__panel">
+        <p className="mk-slot-picker__heading" data-mk-slot-heading />
+        <div data-mk-slot-times />
+        {name && <input type="hidden" name={name} data-mk-slot-value />}
+        {actions && <div className="mk-slot-picker__actions">{actions}</div>}
+      </div>
+    </div>
+  );
+}