@yewdiel21/motion-kit 0.9.1 → 0.10.0

package/src/components/calendar/calendar.css

@@ -0,0 +1,158 @@
+/* calendar — Melon Mind's month/week grid on the --mk-* tokens; parts are .mk-calendar__*. */
+.mk-calendar,
+mk-calendar {
+  --mk-calendar-gap: 6px;
+  --mk-calendar-radius: var(--mk-radius-lg);
+  --mk-calendar-day-height: 112px;
+  display: flex;
+  flex-direction: column;
+  gap: var(--mk-space-3);
+  color: var(--mk-text);
+}
+.mk-calendar__header {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--mk-space-2);
+}
+.mk-calendar__title { margin: 0 auto 0 0; font-size: clamp(1.4rem, 2.6vw, 2rem); font-weight: 400; letter-spacing: -0.01em; }
+.mk-calendar__views { display: inline-flex; padding: 4px; gap: 2px; border-radius: var(--mk-radius-full); background: var(--mk-surface-3); }
+.mk-calendar__views button,
+.mk-calendar__nav {
+  display: inline-grid;
+  place-items: center;
+  min-width: 44px;
+  height: 44px;
+  padding: 0 12px;
+  border: 0;
+  border-radius: var(--mk-radius-full);
+  background: transparent;
+  color: var(--mk-muted);
+  font: inherit;
+  cursor: pointer;
+  transition: background 0.2s, color 0.2s, transform 0.3s var(--mk-ease-nav-move);
+}
+.mk-calendar__views button[aria-pressed='true'] { background: var(--mk-surface-5); color: var(--mk-text); }
+.mk-calendar__nav { background: var(--mk-surface-3); color: var(--mk-text); }
+.mk-calendar__nav:active { transform: scale(0.92); }
+:is(.mk-calendar__views button, .mk-calendar__nav):focus-visible { outline: 2px solid var(--mk-accent); outline-offset: 2px; }
+
+[data-mk-calendar-grid] { position: relative; display: flex; flex-direction: column; gap: var(--mk-calendar-gap); }
+.mk-calendar__head,
+.mk-calendar__week { display: grid; grid-template-columns: repeat(7, minmax(0, 1fr)); gap: var(--mk-calendar-gap); }
+.mk-calendar__body { display: flex; flex-direction: column; gap: var(--mk-calendar-gap); }
+.mk-calendar__body--leaving { position: absolute; left: 0; right: 0; pointer-events: none; }
+.mk-calendar__weekday {
+  padding: 8px 4px;
+  border-radius: var(--mk-radius-md);
+  background: var(--mk-surface-2);
+  text-align: center;
+  font-size: 0.95rem;
+}
+.mk-calendar__weekday-narrow { display: none; }
+
+.mk-calendar__day {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  min-width: 0;
+  min-height: var(--mk-calendar-day-height);
+  padding: 6px;
+  border-radius: var(--mk-calendar-radius);
+  background: var(--mk-surface-3);
+  transition: background 0.3s, box-shadow 0.3s;
+  container-type: inline-size;
+}
+.mk-calendar__body[data-view='week'] .mk-calendar__day { min-height: calc(var(--mk-calendar-day-height) * 3); }
+.mk-calendar__day[data-outside] { background: var(--mk-surface-1); color: var(--mk-muted); }
+.mk-calendar__day:hover { background: var(--mk-surface-4); }
+.mk-calendar__day[aria-selected='true'] { box-shadow: inset 0 0 0 2px var(--mk-accent); }
+.mk-calendar__number {
+  align-self: flex-end;
+  min-width: 2.2rem;
+  height: 2.2rem;
+  padding: 0 0.4rem;
+  border: 0;
+  border-radius: var(--mk-radius-full);
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  font-size: 1.15rem;
+  cursor: pointer;
+  transition: background 0.3s, color 0.3s, border-radius 0.3s var(--mk-ease-nav-radius), transform 0.3s var(--mk-ease-nav-radius);
+}
+.mk-calendar__number:hover { background: var(--mk-surface-5); }
+.mk-calendar__number:active { transform: scale(0.9); }
+.mk-calendar__number:focus-visible { outline: 2px solid var(--mk-accent); outline-offset: 2px; }
+.mk-calendar__day[data-today] .mk-calendar__number { background: var(--mk-accent); color: var(--mk-on-accent); }
+
+.mk-calendar__events { display: flex; flex-direction: column; gap: 3px; min-width: 0; }
+.mk-calendar__event,
+.mk-calendar__more {
+  --mk-calendar-event-color: var(--mk-accent);
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  width: 100%;
+  min-width: 0;
+  padding: 5px 8px;
+  border: 0;
+  border-radius: 10px;
+  background: var(--mk-surface-4);
+  color: var(--mk-text);
+  font: inherit;
+  font-size: 0.85rem;
+  text-align: left;
+  cursor: pointer;
+  transition: background 0.2s, transform 0.3s var(--mk-ease-nav-move);
+}
+.mk-calendar__event[data-state='pending'] {
+  background: color-mix(in srgb, var(--mk-calendar-event-color) 30%, var(--mk-surface-3));
+}
+.mk-calendar__event:hover,
+.mk-calendar__more:hover { transform: translateY(-1px); background: var(--mk-surface-5); }
+.mk-calendar__event:focus-visible,
+.mk-calendar__more:focus-visible { outline: 2px solid var(--mk-accent); outline-offset: 1px; }
+.mk-calendar__status {
+  flex: none;
+  width: 0.8rem;
+  height: 0.8rem;
+  border: 2px solid currentColor;
+  border-radius: 50%;
+}
+.mk-calendar__event[data-state='done'] .mk-calendar__status { background: currentColor; box-shadow: inset 0 0 0 2px var(--mk-surface-4); }
+.mk-calendar__event[data-state='cancelled'] .mk-calendar__event-title { text-decoration: line-through; opacity: 0.6; }
+.mk-calendar__event-title { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.mk-calendar__event-time { flex: none; font-variant-numeric: tabular-nums; opacity: 0.85; }
+.mk-calendar__more { justify-content: center; background: transparent; color: var(--mk-muted); }
+
+/* Narrow day cells: the month keeps the title (the time stays in the label); the week stacks the time under it. */
+@container (max-width: 150px) {
+  .mk-calendar__body[data-view='month'] .mk-calendar__event-time { display: none; }
+  .mk-calendar__body[data-view='week'] .mk-calendar__event { flex-wrap: wrap; column-gap: 5px; row-gap: 1px; }
+  .mk-calendar__body[data-view='week'] .mk-calendar__event-title { flex: 1 1 0; }
+  .mk-calendar__body[data-view='week'] .mk-calendar__event-time { flex-basis: 100%; padding-left: calc(0.8rem + 5px); font-size: 0.72rem; }
+}
+@media (max-width: 680px) {
+  .mk-calendar,
+  mk-calendar { --mk-calendar-day-height: 64px; --mk-calendar-gap: 4px; --mk-calendar-radius: var(--mk-radius-sm); }
+  .mk-calendar__weekday-long { display: none; }
+  .mk-calendar__weekday-narrow { display: inline; }
+  .mk-calendar__number { align-self: center; font-size: 0.95rem; }
+  .mk-calendar__body[data-view='month'] .mk-calendar__events { flex-direction: row; flex-wrap: wrap; justify-content: center; gap: 3px; }
+  .mk-calendar__body[data-view='month'] :is(.mk-calendar__event, .mk-calendar__more) {
+    width: 7px;
+    height: 7px;
+    padding: 0;
+    border-radius: 50%;
+    background: var(--mk-calendar-event-color);
+    font-size: 0;
+  }
+  .mk-calendar__body[data-view='month'] .mk-calendar__status { display: none; }
+  .mk-calendar__body[data-view='week'] .mk-calendar__event-time { display: none; }
+}
+@media (prefers-reduced-motion: reduce) {
+  .mk-calendar *,
+  mk-calendar * { transition: none !important; }
+}

package/src/components/calendar/element.ts

@@ -0,0 +1,27 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createCalendar, type CalendarEvent, type CalendarInstance } from './engine';
+
+/** Light DOM: supply the header and the [data-mk-calendar-grid] shown in the README. */
+export class MkCalendarElement extends MkElement<CalendarInstance> {
+  static options: Record<string, OptionType> = {
+    date: 'string', view: 'string', firstDay: 'number', locale: 'string', maxEvents: 'number', events: 'json', selected: 'string', today: 'string',
+  };
+
+  protected create(options: Record<string, unknown>) {
+    return createCalendar(this, options);
+  }
+
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.isConnected || !this.instance) return;
+    if (name === 'events') {
+      this.instance.setEvents((this.options.events as CalendarEvent[] | undefined) ?? []);
+      return;
+    }
+    // Keep where the visitor is unless the changed attribute says otherwise.
+    const { date, view, selected } = this.instance;
+    this.instance.destroy();
+    this.instance = this.create({ date, view, selected, ...this.options });
+  }
+}
+
+export const defineCalendar = () => defineElement('mk-calendar', MkCalendarElement);

package/src/components/calendar/engine.ts

@@ -0,0 +1,412 @@
+import { 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, toDateTime, weekDays, weekdayNames, type DateInput,
+} from '../../core/dates';
+import { flowIn } from '../../motion/flow';
+
+/*
+ * Calendar (Melon Mind, section-calendar-test): month and week grids with
+ * event chips. Motion from the reference: on first load the day cells flow in
+ * (search-result-item-in: y −20, blur 16, .5 s) 5 ms apart and the events
+ * 20 ms apart (CalendarComponent eventsSet → flowChilds). Changing month or
+ * week slides the grid like Melon Mind's time slots: out −30 px / in +30 px,
+ * .25 s ease-out (schedulePicker.css view transitions); the old grid leaves
+ * first (.12 s) so two dense months never overlap. Keyboard: an ARIA grid
+ * with a roving day button.
+ */
+
+export type CalendarView = 'month' | 'week';
+export type CalendarEventStatus = 'pending' | 'done' | 'cancelled';
+
+export interface CalendarEvent {
+  id: string | number;
+  title: string;
+  start: DateInput;
+  end?: DateInput;
+  allDay?: boolean;
+  status?: CalendarEventStatus;
+  /** Any CSS colour for the chip. */
+  color?: string;
+}
+
+export interface CalendarRange { start: Date; end: Date; view: CalendarView }
+
+export interface CalendarLabels {
+  more?: (count: number) => string;
+  events?: (count: number) => string;
+  status?: Partial<Record<CalendarEventStatus, string>>;
+}
+
+export interface CalendarOptions {
+  /** Date the calendar opens on. */
+  date?: DateInput;
+  view?: CalendarView;
+  /** 0 = Sunday … 6 = Saturday. */
+  firstDay?: number;
+  locale?: string;
+  events?: CalendarEvent[];
+  /** Chips per day in the month view before "+N". */
+  maxEvents?: number;
+  selected?: DateInput | null;
+  /** Override "today" (tests, demos in another zone). */
+  today?: DateInput;
+  labels?: CalendarLabels;
+  onSelect?: (date: Date) => void;
+  onEventClick?: (event: CalendarEvent) => void;
+  onNavigate?: (range: CalendarRange) => void;
+}
+
+export interface CalendarInstance extends Instance {
+  next(): void;
+  prev(): void;
+  goToday(): void;
+  setDate(date: DateInput): void;
+  setView(view: CalendarView): void;
+  setEvents(events: CalendarEvent[]): void;
+  select(date: DateInput | null, notify?: boolean): void;
+  readonly date: Date;
+  readonly view: CalendarView;
+  readonly selected: Date | null;
+  readonly range: CalendarRange;
+}
+
+const SLIDE = 30;
+const SLIDE_OUT = 0.12;
+const SLIDE_GAP = 0.1;
+const SLIDE_DURATION = 0.25;
+const CELL_STAGGER = 0.005;
+const EVENT_STAGGER = 0.02;
+
+export function createCalendar(root: HTMLElement | null, options: CalendarOptions = {}): CalendarInstance {
+  const grid = root?.querySelector<HTMLElement>('[data-mk-calendar-grid]');
+  if (!root || !grid) {
+    const now = toDate(null);
+    return inert({
+      next() {}, prev() {}, goToday() {}, setDate() {}, setView() {}, setEvents() {}, select() {},
+      date: now, view: 'month' as CalendarView, selected: null, range: { start: now, end: now, view: 'month' as CalendarView },
+    });
+  }
+  registerMotion();
+  const scope = createScope();
+  const ctx = gsap.context(() => {});
+  scope.add(() => ctx.revert());
+  const locale = options.locale ?? 'es';
+  const firstDay = clampFirstDay(options.firstDay);
+  const maxEvents = Number.isFinite(options.maxEvents) ? Math.max(0, Math.floor(options.maxEvents!)) : 3;
+  const labels = {
+    more: options.labels?.more ?? ((n: number) => `+${n} más`),
+    events: options.labels?.events ?? ((n: number) => (n === 1 ? '1 evento' : `${n} eventos`)),
+    status: { pending: 'pendiente', done: 'completado', cancelled: 'cancelado', ...options.labels?.status },
+  };
+  let date = toDate(options.date);
+  let view: CalendarView = options.view === 'week' ? 'week' : 'month';
+  let selected: Date | null = options.selected ? toDate(options.selected) : null;
+  let focusDay: Date = selected ?? date;
+  let events: CalendarEvent[] = [];
+  let byDay = new Map<string, CalendarEvent[]>();
+  let first = true;
+  const today = () => toDate(options.today ?? null);
+
+  const title = root.querySelector<HTMLElement>('[data-mk-calendar-title]');
+  const prevButton = root.querySelector<HTMLButtonElement>('[data-mk-calendar-prev]');
+  const nextButton = root.querySelector<HTMLButtonElement>('[data-mk-calendar-next]');
+  const todayButton = root.querySelector<HTMLButtonElement>('[data-mk-calendar-today]');
+  const viewButtons = [...root.querySelectorAll<HTMLButtonElement>('[data-mk-calendar-view]')];
+
+  const originalGrid = [...grid.childNodes];
+  const originalTitle = title ? [...title.childNodes] : [];
+  scope.add(() => {
+    grid.replaceChildren(...originalGrid);
+    title?.replaceChildren(...originalTitle);
+  });
+  scope.attr(root, 'data-mk-ready', '');
+  scope.attr(grid, 'role', 'grid');
+  if (title) {
+    if (!title.id) scope.attr(title, 'id', `mk-calendar-${Math.random().toString(36).slice(2, 8)}`);
+    scope.attr(grid, 'aria-labelledby', title.id);
+  }
+
+  const monthTitle = safeFormat(locale, { month: 'long', year: 'numeric' });
+  const rangeTitle = safeFormat(locale, { day: 'numeric', month: 'short', year: 'numeric' });
+  const fullDay = safeFormat(locale, { weekday: 'long', day: 'numeric', month: 'long', year: 'numeric' });
+  const timeFormat = safeFormat(locale, { hour: 'numeric', minute: '2-digit' });
+
+  const index = (list: CalendarEvent[]) => {
+    events = Array.isArray(list) ? list.filter((e) => e && toDateTime(e.start)) : [];
+    byDay = new Map();
+    const sorted = [...events].sort((a, b) => toDateTime(a.start)!.getTime() - toDateTime(b.start)!.getTime());
+    for (const event of sorted) {
+      const start = toDate(toDateTime(event.start)!);
+      const endTime = event.end ? toDateTime(event.end) : null;
+      const end = endTime && endTime > start ? toDate(endTime) : start;
+      // Multi-day events show on every day they cover (at most two months).
+      for (let day = start, n = 0; day <= end && n < 62; day = addDays(day, 1), n++) {
+        const key = dayKey(day);
+        byDay.set(key, [...(byDay.get(key) ?? []), event]);
+      }
+    }
+  };
+  index(fromJson<CalendarEvent[]>(options.events) ?? []);
+
+  const days = () => (view === 'week' ? [weekDays(date, firstDay)] : monthWeeks(date, firstDay));
+  const range = (): CalendarRange => {
+    const weeks = days();
+    return { start: weeks[0][0], end: weeks[weeks.length - 1][6], view };
+  };
+  const inRange = (day: Date) => {
+    const r = range();
+    return day >= r.start && day <= r.end;
+  };
+
+  const header = () => {
+    const row = document.createElement('div');
+    row.className = 'mk-calendar__head';
+    row.setAttribute('role', 'row');
+    const long = weekdayNames(locale, firstDay, 'short');
+    const narrow = weekdayNames(locale, firstDay, 'narrow');
+    long.forEach((name, i) => {
+      const cell = document.createElement('div');
+      cell.className = 'mk-calendar__weekday';
+      cell.setAttribute('role', 'columnheader');
+      cell.innerHTML = '<span class="mk-calendar__weekday-long"></span><span class="mk-calendar__weekday-narrow" aria-hidden="true"></span>';
+      cell.firstElementChild!.textContent = name;
+      cell.lastElementChild!.textContent = narrow[i];
+      row.append(cell);
+    });
+    return row;
+  };
+
+  const chip = (event: CalendarEvent) => {
+    const button = document.createElement('button');
+    button.type = 'button';
+    button.className = 'mk-calendar__event';
+    button.dataset.mkEvent = String(event.id);
+    const status = event.status ?? 'pending';
+    button.dataset.state = status;
+    if (event.color) button.style.setProperty('--mk-calendar-event-color', event.color);
+    const start = toDateTime(event.start)!;
+    const time = event.allDay ? '' : timeFormat.format(start);
+    button.innerHTML = '<span class="mk-calendar__status" aria-hidden="true"></span><span class="mk-calendar__event-title"></span><span class="mk-calendar__event-time"></span>';
+    button.children[1].textContent = event.title;
+    button.children[2].textContent = time;
+    button.setAttribute('aria-label', [event.title, time, labels.status[status]].filter(Boolean).join(', '));
+    return button;
+  };
+
+  const body = () => {
+    const wrap = document.createElement('div');
+    wrap.className = 'mk-calendar__body';
+    wrap.dataset.view = view;
+    wrap.setAttribute('role', 'rowgroup');
+    const now = today();
+    const focusKey = dayKey(focusDay);
+    for (const week of days()) {
+      const row = document.createElement('div');
+      row.className = 'mk-calendar__week';
+      row.setAttribute('role', 'row');
+      for (const day of week) {
+        const key = dayKey(day);
+        const cell = document.createElement('div');
+        cell.className = 'mk-calendar__day';
+        cell.setAttribute('role', 'gridcell');
+        cell.dataset.mkDate = key;
+        if (view === 'month' && !sameMonth(day, date)) cell.dataset.outside = '';
+        if (sameDay(day, now)) cell.dataset.today = '';
+        const isSelected = sameDay(day, selected);
+        cell.setAttribute('aria-selected', String(isSelected));
+        const list = byDay.get(key) ?? [];
+        const number = document.createElement('button');
+        number.type = 'button';
+        number.className = 'mk-calendar__number';
+        number.dataset.mkDay = key;
+        number.textContent = view === 'week' ? `${day.getDate()}` : String(day.getDate());
+        number.tabIndex = key === focusKey ? 0 : -1;
+        number.setAttribute('aria-label', `${capitalize(fullDay.format(day))}${list.length ? `, ${labels.events(list.length)}` : ''}`);
+        if (sameDay(day, now)) number.setAttribute('aria-current', 'date');
+        cell.append(number);
+        if (list.length) {
+          const box = document.createElement('div');
+          box.className = 'mk-calendar__events';
+          const shown = view === 'week' ? list : list.slice(0, maxEvents);
+          for (const event of shown) box.append(chip(event));
+          if (shown.length < list.length) {
+            const more = document.createElement('button');
+            more.type = 'button';
+            more.className = 'mk-calendar__more';
+            more.dataset.mkMore = key;
+            more.textContent = labels.more(list.length - shown.length);
+            box.append(more);
+          }
+          cell.append(box);
+        }
+        row.append(cell);
+      }
+      wrap.append(row);
+    }
+    return wrap;
+  };
+
+  let current: HTMLElement | null = null;
+  const leaving = new Set<HTMLElement>();
+  scope.add(() => leaving.forEach((el) => el.remove()));
+
+  const syncChrome = () => {
+    if (title) {
+      const r = range();
+      let text = capitalize(monthTitle.format(date));
+      if (view === 'week') {
+        const format = rangeTitle as Intl.DateTimeFormat & { formatRange?: (a: Date, b: Date) => string };
+        text = format.formatRange ? format.formatRange(r.start, r.end) : `${rangeTitle.format(r.start)} – ${rangeTitle.format(r.end)}`;
+      }
+      title.textContent = text;
+    }
+    for (const button of viewButtons) {
+      scope.attr(button, 'aria-pressed', String(button.dataset.mkCalendarView === view));
+    }
+  };
+
+  const render = (direction: number) => {
+    const next = body();
+    const motion = !reduced();
+    if (!current) {
+      grid.replaceChildren(header(), next);
+    } else if (motion && direction !== 0) {
+      const old = current;
+      old.style.top = `${old.offsetTop}px`;
+      old.classList.add('mk-calendar__body--leaving');
+      old.setAttribute('aria-hidden', 'true');
+      old.querySelectorAll('button').forEach((b) => (b.tabIndex = -1));
+      leaving.add(old);
+      grid.append(next);
+      ctx.add(() => {
+        // Out, then in: two dense month grids crossfading read as noise.
+        gsap.to(old, { x: -SLIDE * direction, opacity: 0, duration: SLIDE_OUT, ease: 'power1.in', onComplete: () => { old.remove(); leaving.delete(old); } });
+        gsap.fromTo(next, { x: SLIDE * direction, opacity: 0 }, { x: 0, opacity: 1, duration: SLIDE_DURATION, delay: SLIDE_GAP, ease: 'power2.out', clearProps: 'transform,opacity' });
+      });
+    } else {
+      current.replaceWith(next);
+    }
+    current = next;
+    syncChrome();
+    if (motion) {
+      ctx.add(() => {
+        if (first) flowIn(next, { target: '.mk-calendar__day', stagger: CELL_STAGGER });
+        flowIn(next, { target: '.mk-calendar__event, .mk-calendar__more', stagger: EVENT_STAGGER, delay: first ? 0.1 : direction ? SLIDE_GAP + SLIDE_DURATION * 0.5 : 0 });
+      });
+    }
+    first = false;
+  };
+
+  const focusButton = () => grid.querySelector<HTMLButtonElement>(`.mk-calendar__body:not(.mk-calendar__body--leaving) [data-mk-day="${dayKey(focusDay)}"]`);
+  const navigate = (to: Date, focus = false) => {
+    if (scope.disposed) return;
+    const from = date;
+    const moved = view === 'week' ? !sameDay(startOfWeek(to, firstDay), startOfWeek(from, firstDay)) : !sameMonth(to, from);
+    date = to;
+    focusDay = to;
+    if (moved) {
+      render(to > from ? 1 : -1);
+      const r = range();
+      options.onNavigate?.(r);
+      root.dispatchEvent(new CustomEvent('mk:navigate', { bubbles: true, detail: r }));
+    } else {
+      grid.querySelectorAll<HTMLButtonElement>('[data-mk-day]').forEach((b) => (b.tabIndex = b.dataset.mkDay === dayKey(to) ? 0 : -1));
+    }
+    if (focus) focusButton()?.focus();
+  };
+
+  const select = (value: DateInput | null, notify = true) => {
+    if (scope.disposed) return;
+    selected = value === null ? null : toDate(value);
+    grid.querySelectorAll<HTMLElement>('.mk-calendar__day').forEach((cell) => cell.setAttribute('aria-selected', String(!!selected && cell.dataset.mkDate === dayKey(selected))));
+    if (selected && notify) {
+      options.onSelect?.(selected);
+      root.dispatchEvent(new CustomEvent('mk:select', { bubbles: true, detail: { date: selected, key: dayKey(selected) } }));
+    }
+  };
+
+  scope.on(root, 'click', (e) => {
+    const target = (e.target as Element).closest<HTMLElement>('button');
+    if (!target || !root.contains(target) || (target as HTMLButtonElement).disabled) return;
+    if (target === prevButton) navigate(view === 'week' ? addDays(date, -7) : addMonths(date, -1));
+    else if (target === nextButton) navigate(view === 'week' ? addDays(date, 7) : addMonths(date, 1));
+    else if (target === todayButton) navigate(today(), true);
+    else if (target.dataset.mkCalendarView) setView(target.dataset.mkCalendarView as CalendarView);
+    else if (target.dataset.mkEvent !== undefined) {
+      const event = events.find((ev) => String(ev.id) === target.dataset.mkEvent);
+      if (event) {
+        options.onEventClick?.(event);
+        root.dispatchEvent(new CustomEvent('mk:event', { bubbles: true, detail: { event } }));
+      }
+    } else if (target.dataset.mkDay || target.dataset.mkMore) {
+      const day = toDate(target.dataset.mkDay ?? target.dataset.mkMore);
+      focusDay = day;
+      grid.querySelectorAll<HTMLButtonElement>('[data-mk-day]').forEach((b) => (b.tabIndex = b.dataset.mkDay === dayKey(day) ? 0 : -1));
+      select(day);
+    }
+  });
+
+  scope.on(grid, 'keydown', (e) => {
+    const event = e as KeyboardEvent;
+    const target = event.target as HTMLElement;
+    if (!target.dataset?.mkDay) return;
+    const day = toDate(target.dataset.mkDay);
+    const map: Record<string, () => Date> = {
+      ArrowLeft: () => addDays(day, -1),
+      ArrowRight: () => addDays(day, 1),
+      ArrowUp: () => addDays(day, -7),
+      ArrowDown: () => addDays(day, 7),
+      Home: () => startOfWeek(day, firstDay),
+      End: () => addDays(startOfWeek(day, firstDay), 6),
+      PageUp: () => addMonths(day, event.shiftKey ? -12 : -1),
+      PageDown: () => addMonths(day, event.shiftKey ? 12 : 1),
+    };
+    const to = map[event.key]?.();
+    if (!to) return;
+    event.preventDefault();
+    if (!event.key.startsWith('Page') && inRange(to)) {
+      focusDay = to;
+      grid.querySelectorAll<HTMLButtonElement>('[data-mk-day]').forEach((b) => (b.tabIndex = b.dataset.mkDay === dayKey(to) ? 0 : -1));
+      focusButton()?.focus();
+    } else navigate(to, true);
+  });
+
+  const setView = (next: CalendarView) => {
+    if (scope.disposed || (next !== 'month' && next !== 'week') || next === view) return;
+    view = next;
+    date = focusDay;
+    render(0);
+    const r = range();
+    options.onNavigate?.(r);
+    root.dispatchEvent(new CustomEvent('mk:navigate', { bubbles: true, detail: r }));
+  };
+
+  render(0);
+
+  return {
+    next: () => navigate(view === 'week' ? addDays(date, 7) : addMonths(date, 1)),
+    prev: () => navigate(view === 'week' ? addDays(date, -7) : addMonths(date, -1)),
+    goToday: () => navigate(today()),
+    setDate: (value) => navigate(toDate(value, date)),
+    setView,
+    setEvents(list) {
+      if (scope.disposed) return;
+      const hadFocus = grid.contains(document.activeElement);
+      index(fromJson<CalendarEvent[]>(list) ?? []);
+      const fresh = body();
+      current?.replaceWith(fresh);
+      current = fresh;
+      if (hadFocus) focusButton()?.focus();
+    },
+    select,
+    get date() { return date; },
+    get view() { return view; },
+    get selected() { return selected; },
+    get range() { return range(); },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/calendar/react.tsx

@@ -0,0 +1,69 @@
+'use client';
+
+import { useRef, type HTMLAttributes } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createCalendar, type CalendarInstance, type CalendarOptions, type CalendarView } from './engine';
+import type { DateInput } from '../../core/dates';
+
+export interface CalendarProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onSelect'>, CalendarOptions {
+  /** Hide the month/week switch. */
+  hideViews?: boolean;
+  labels?: CalendarOptions['labels'] & { previous?: string; next?: string; today?: string; month?: string; week?: string };
+}
+
+export function Calendar({
+  date, view, firstDay, locale, events, maxEvents, selected, today, labels, onSelect, onEventClick, onNavigate,
+  hideViews, className, ...props
+}: CalendarProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const instance = useRef<CalendarInstance | null>(null);
+  const kept = useRef<{ date?: DateInput; view?: CalendarView; selected?: DateInput | null }>({});
+  const select = useLatest(onSelect);
+  const eventClick = useLatest(onEventClick);
+  const navigate = useLatest(onNavigate);
+  useIsomorphicLayoutEffect(() => {
+    const created = createCalendar(ref.current, {
+      date: date ?? kept.current.date,
+      view: view ?? kept.current.view,
+      selected: selected !== undefined ? selected : kept.current.selected,
+      firstDay, locale, events, maxEvents, today, labels,
+      onSelect: (d) => select.current?.(d),
+      onEventClick: (e) => eventClick.current?.(e),
+      onNavigate: (r) => navigate.current?.(r),
+    });
+    instance.current = created;
+    return () => {
+      kept.current = { date: created.date, view: created.view, selected: created.selected };
+      created.destroy();
+      instance.current = null;
+    };
+    // Events and selection update in place; the rest recreates the grid.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [date, view, firstDay, locale, maxEvents, today]);
+  // Re-index only when the events' content changes, not on every new array identity.
+  const eventsKey = JSON.stringify(events ?? []);
+  const firstEvents = useRef(true);
+  useIsomorphicLayoutEffect(() => {
+    if (firstEvents.current) { firstEvents.current = false; return; }
+    instance.current?.setEvents(events ?? []);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [eventsKey]);
+  useIsomorphicLayoutEffect(() => { if (selected !== undefined) instance.current?.select(selected, false); }, [selected]);
+  return (
+    <div {...props} ref={ref} className={['mk-calendar', className].filter(Boolean).join(' ')}>
+      <div className="mk-calendar__header">
+        <h3 className="mk-calendar__title" data-mk-calendar-title />
+        {!hideViews && (
+          <div className="mk-calendar__views" role="group" aria-label="Vista">
+            <button type="button" data-mk-calendar-view="month">{labels?.month ?? 'Mes'}</button>
+            <button type="button" data-mk-calendar-view="week">{labels?.week ?? 'Semana'}</button>
+          </div>
+        )}
+        <button type="button" className="mk-calendar__nav" data-mk-calendar-prev aria-label={labels?.previous ?? 'Anterior'}>←</button>
+        <button type="button" className="mk-calendar__nav" data-mk-calendar-today>{labels?.today ?? 'Hoy'}</button>
+        <button type="button" className="mk-calendar__nav" data-mk-calendar-next aria-label={labels?.next ?? 'Siguiente'}>→</button>
+      </div>
+      <div data-mk-calendar-grid />
+    </div>
+  );
+}

package/src/components/hover-card/README.md

@@ -0,0 +1,16 @@
+# hover-card
+
+Vista previa no modal, accesible al señalar, enfocar o tocar. Los enlaces/botones del panel pueden recibir foco.
+
+```html
+<mk-hover-card class="mk-hover-card" placement="bottom">
+  <button type="button" data-mk-hover-trigger>Ver estudio</button>
+  <div data-mk-hover-panel hidden role="region" aria-label="Vista previa">Contenido</div>
+</mk-hover-card>
+```
+
+`defineElements()`, `createHoverCard(root, options)`, o `<HoverCard trigger="Ver estudio" placement="bottom">Contenido</HoverCard>`.
+
+Opciones: `openDelay=120` ms, `closeDelay=140` ms, `placement='top'|'bottom'`, `onOpenChange(boolean)`. API `open()`, `close()`, `isOpen`, `destroy()`. Evento `mk:open-change` con `{open}`.
+
+Escape cierra y retorna al disparador; salir con foco y puntero fuera o tocar fuera cierra. El panel se posiciona respecto al root: mantener un ancestro que permita overflow; no crea portal. No atrapa el foco. Entrada .28 s, instantánea bajo movimiento reducido. Limpia timers y restaura todos los atributos.