@yewdiel21/motion-kit 0.10.0 → 0.14.0

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

@@ -0,0 +1,42 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createRangeCalendar, type RangeCalendarInstance } from './engine';
+
+/**
+ * <mk-range-calendar class="mk-range-calendar" start="2026-11-23" end="2026-11-26" visible-months="2"
+ *   unavailable="2026-12-24,2026-12-25"></mk-range-calendar>
+ * Emits mk:change ({start, end, length}). Changing start/end moves the range.
+ */
+export class MkRangeCalendarElement extends MkElement<RangeCalendarInstance> {
+  static options: Record<string, OptionType> = {
+    start: 'string',
+    end: 'string',
+    month: 'string',
+    visibleMonths: 'number',
+    firstDay: 'number',
+    min: 'string',
+    max: 'string',
+    unavailable: 'list',
+    locale: 'string',
+    today: 'string',
+  };
+
+  protected create(options: Record<string, unknown>) {
+    const { start, end, ...rest } = options as { start?: string; end?: string };
+    return createRangeCalendar(this, { ...rest, value: start && end ? { start, end } : null });
+  }
+
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.instance) return;
+    if (name === 'start' || name === 'end') {
+      const start = this.getAttribute('start');
+      const end = this.getAttribute('end');
+      this.instance.setValue(start && end ? { start, end } : null);
+    } else super.attributeChangedCallback(name, previous, next);
+  }
+
+  get value() {
+    return this.instance?.value ?? null;
+  }
+}
+
+export const defineRangeCalendar = () => defineElement('mk-range-calendar', MkRangeCalendarElement);

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

@@ -0,0 +1,390 @@
+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 {
+  addDays, addMonths, capitalize, clampFirstDay, dayKey, monthWeeks, safeFormat, sameDay, sameMonth, startOfMonth, startOfWeek, toDate, weekdayNames,
+  type DateInput,
+} from '../../core/dates';
+import { inRange, isPickable, pickDay, rangeKeys, rangeLength, toRange, type DateRange, type DayRules } from '../../core/date-range';
+import { blurIn, press, ringPulse, shake } from '../../motion/micro';
+
+/*
+ * Range calendar: one or two month grids (role="grid") with one tabbable day
+ * (roving tabindex). The first click (or Enter) fixes an anchor that pops; while
+ * choosing the end, pointing previews the range as a lighter band; the second
+ * click closes it and its band wipes in from the anchor to the end (EASE.wipe,
+ * 12 ms apart, .35 s at most), then the end pops. Days that cannot be picked
+ * (min, max, unavailable) are aria-disabled; a range may not cross one. Months
+ * slide like the calendar component (old grid out 30 px in .12 s, new in from
+ * the other side .25 s). Keyboard: arrows ±1/±7 days, Home/End week, PageUp/
+ * PageDown month (Shift: year), Enter/Space pick.
+ */
+
+export interface RangeCalendarOptions {
+  value?: { start: DateInput; end: DateInput } | null;
+  /** First visible month (default: the value's start, else today). */
+  month?: DateInput;
+  visibleMonths?: 1 | 2;
+  /** 0 = Sunday … 6 = Saturday (default 1, Monday). */
+  firstDay?: number;
+  min?: DateInput | null;
+  max?: DateInput | null;
+  /** 'YYYY-MM-DD' keys or a test. */
+  unavailable?: string[] | ((day: Date) => boolean);
+  locale?: string;
+  /** Override "today" (demos, tests). */
+  today?: DateInput;
+  labels?: { prev?: string; next?: string };
+  /** 'range' (default): two clicks; 'single': one click picks a day (date-time-picker). */
+  selection?: 'range' | 'single';
+  onChange?: (range: DateRange) => void;
+}
+
+export interface RangeCalendarInstance extends Instance {
+  setValue(range: { start: DateInput; end: DateInput } | null, animate?: boolean): void;
+  next(): void;
+  prev(): void;
+  /** Move the focus to `day`, changing month if needed (`animate` false: no slide). */
+  focusDay(day: DateInput, animate?: boolean): void;
+  readonly value: DateRange | null;
+  readonly month: Date;
+}
+
+/** The band of a finished range: each day draws in .22 s, 12 ms after the one before, the run within .35 s. */
+const BAND = { day: 0.22, gap: 0.012, spread: 0.35 };
+const bandGap = (days: number) => Math.min(BAND.gap, BAND.spread / Math.max(1, days));
+
+/** Seconds a finished range of `days` takes to settle: its band draws in while its end day pops (.3 s). */
+export const bandDuration = (days: number) => Math.max(0.3, BAND.day + bandGap(days) * Math.max(0, days - 1));
+
+const chevron = (path: string) =>
+  `<svg aria-hidden="true" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="${path}"/></svg>`;
+
+const el = <K extends keyof HTMLElementTagNameMap>(tag: K, attrs: Record<string, string> = {}, text?: string) => {
+  const element = document.createElement(tag);
+  for (const [name, value] of Object.entries(attrs)) element.setAttribute(name, value);
+  if (text !== undefined) element.textContent = text;
+  return element;
+};
+
+export function createRangeCalendar(root: HTMLElement | null, options: RangeCalendarOptions = {}): RangeCalendarInstance {
+  if (!root) return inert({ setValue() {}, next() {}, prev() {}, focusDay() {}, value: null, month: startOfMonth(new Date()) });
+  registerMotion();
+  const scope = createScope();
+  const effects = new Set<gsap.core.Animation>();
+  const keep = (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);
+  };
+
+  const locale = options.locale ?? root.closest('[lang]')?.getAttribute('lang') ?? 'es';
+  const firstDay = options.firstDay === undefined ? 1 : clampFirstDay(options.firstDay);
+  const count = options.visibleMonths === 2 ? 2 : 1;
+  const today = toDate(options.today ?? new Date());
+  const unavailable = options.unavailable;
+  const rules: DayRules = {
+    min: options.min ? toDate(options.min) : null,
+    max: options.max ? toDate(options.max) : null,
+    isUnavailable: typeof unavailable === 'function' ? unavailable : Array.isArray(unavailable) ? (day) => unavailable.includes(dayKey(day)) : undefined,
+  };
+  let range: DateRange | null = toRange(options.value);
+  let anchor: Date | null = null;
+  let hover: Date | null = null;
+  let month = startOfMonth(toDate(options.month ?? range?.start ?? today));
+  let focused: Date = range?.start && sameMonth(range.start, month) ? range.start : sameMonth(today, month) ? today : month;
+  const monthYear = safeFormat(locale, { month: 'long', year: 'numeric' });
+  const fullDate = safeFormat(locale, { weekday: 'long', day: 'numeric', month: 'long', year: 'numeric' });
+  const lastVisible = () => addDays(startOfMonth(addMonths(month, count)), -1);
+  const visible = (day: Date) => day >= month && day <= lastVisible();
+
+  const header = el('header', { 'data-mk-range-header': '' });
+  const prevButton = el('button', { type: 'button', 'data-mk-range-prev': '', 'aria-label': options.labels?.prev ?? 'Mes anterior' });
+  prevButton.innerHTML = chevron('M15 6l-6 6 6 6');
+  const titleEl = el('h3', { 'data-mk-range-title': '', 'aria-live': 'polite' });
+  const nextButton = el('button', { type: 'button', 'data-mk-range-next': '', 'aria-label': options.labels?.next ?? 'Mes siguiente' });
+  nextButton.innerHTML = chevron('M9 6l6 6-6 6');
+  header.append(prevButton, titleEl, nextButton);
+  const months = el('div', { 'data-mk-range-months': '' });
+  root.append(header, months);
+  scope.add(() => {
+    for (const effect of effects) effect.kill();
+    effects.clear();
+    gsap.killTweensOf([months, titleEl]);
+    header.remove();
+    months.remove();
+  });
+  scope.attr(root, 'data-mk-months', String(count));
+  const single = options.selection === 'single';
+  if (single) scope.attr(root, 'data-mk-selection', 'single');
+  scope.attr(root, 'data-mk-ready', '');
+
+  const title = () => capitalize(count > 1 && typeof monthYear.formatRange === 'function' ? monthYear.formatRange(month, lastVisible()) : monthYear.format(month));
+
+  const buttons = () => [...months.querySelectorAll<HTMLButtonElement>('button[data-mk-day]')];
+  const buttonOf = (day: Date) => months.querySelector<HTMLButtonElement>(`button[data-mk-day="${dayKey(day)}"]`);
+  const dayOf = (button: Element) => toDate((button as HTMLElement).dataset.mkDay!);
+
+  const build = () => {
+    const short = weekdayNames(locale, firstDay, 'narrow');
+    const long = weekdayNames(locale, firstDay, 'long');
+    const grids: HTMLElement[] = [];
+    for (let i = 0; i < count; i++) {
+      const shown = addMonths(month, i);
+      const grid = el('div', { role: 'grid', 'data-mk-range-month': '', 'aria-label': monthYear.format(shown) });
+      const head = el('div', { role: 'row', 'data-mk-range-weekdays': '' });
+      short.forEach((name, j) => head.append(el('span', { role: 'columnheader', 'data-mk-range-weekday': '', 'aria-label': long[j]! }, name.toLocaleUpperCase(locale))));
+      grid.append(head);
+      for (const week of monthWeeks(shown, firstDay)) {
+        const row = el('div', { role: 'row', 'data-mk-range-week': '' });
+        for (const day of week) {
+          const cell = el('div', { role: 'gridcell', 'data-mk-range-cell': '' });
+          if (!sameMonth(day, shown)) cell.setAttribute('data-mk-outside', '');
+          else {
+            cell.append(
+              el('span', { 'data-mk-day-band': '', 'aria-hidden': 'true' }),
+              el('button', { type: 'button', 'data-mk-day': dayKey(day), tabindex: '-1', 'aria-label': fullDate.format(day) }, String(day.getDate())),
+            );
+          }
+          row.append(cell);
+        }
+        grid.append(row);
+      }
+      grids.push(grid);
+    }
+    months.replaceChildren(...grids);
+    paint();
+  };
+
+  const ordered = (a: Date, b: Date): DateRange => (a <= b ? { start: a, end: b } : { start: b, end: a });
+
+  const paint = () => {
+    const shown = anchor ? null : range;
+    const preview = anchor && hover ? ordered(anchor, hover) : null;
+    const all = buttons();
+    const target = visible(focused) ? dayKey(focused) : dayKey(all.map(dayOf).find((day) => isPickable(day, rules)) ?? month);
+    for (const button of all) {
+      const day = dayOf(button);
+      const cell = button.parentElement!;
+      const selected = inRange(day, shown);
+      button.toggleAttribute('data-mk-today', sameDay(day, today));
+      button.toggleAttribute('data-mk-anchor', sameDay(day, anchor));
+      button.toggleAttribute('data-mk-in-range', selected);
+      button.toggleAttribute('data-mk-range-start', !!shown && sameDay(day, shown.start));
+      button.toggleAttribute('data-mk-range-end', !!shown && sameDay(day, shown.end));
+      button.toggleAttribute('data-mk-preview', inRange(day, preview));
+      button.toggleAttribute('data-mk-preview-start', !!preview && sameDay(day, preview.start));
+      button.toggleAttribute('data-mk-preview-end', !!preview && sameDay(day, preview.end));
+      if (isPickable(day, rules)) button.removeAttribute('aria-disabled');
+      else button.setAttribute('aria-disabled', 'true');
+      if (selected) cell.setAttribute('aria-selected', 'true');
+      else cell.removeAttribute('aria-selected');
+      button.setAttribute('tabindex', button.dataset.mkDay === target ? '0' : '-1');
+    }
+  };
+
+  const go = (next: Date, direction: 1 | -1, after?: () => void, animate = true) => {
+    month = startOfMonth(next);
+    gsap.killTweensOf([months, titleEl]);
+    if (reduced() || !animate) {
+      build();
+      titleEl.textContent = title();
+      after?.();
+      return;
+    }
+    keep(
+      gsap.to(months, {
+        x: -direction * 30,
+        opacity: 0,
+        duration: 0.12,
+        ease: 'power2.in',
+        onComplete: () => {
+          build();
+          titleEl.textContent = title();
+          keep(blurIn(titleEl, { from: 'soft', duration: 0.3 }));
+          keep(gsap.fromTo(months, { x: direction * 30, opacity: 0 }, { x: 0, opacity: 1, duration: 0.25, ease: 'power2.out', clearProps: 'x,opacity,transform' }));
+          after?.();
+        },
+      }),
+    );
+  };
+
+  const focusDay = (input: DateInput, animate = true) => {
+    focused = toDate(input);
+    if (anchor) hover = focused;
+    if (visible(focused)) {
+      paint();
+      buttonOf(focused)?.focus();
+      return;
+    }
+    const before = focused < month;
+    go(before ? startOfMonth(focused) : startOfMonth(addMonths(focused, -(count - 1))), before ? -1 : 1, () => buttonOf(focused)?.focus(), animate);
+  };
+
+  const pop = (button: HTMLElement | null) => {
+    if (button && !reduced()) keep(gsap.fromTo(button, { scale: 0.6 }, { scale: 1, duration: 0.3, ease: EASE.pop, clearProps: 'scale,transform' }));
+  };
+
+  /** The band of the finished range draws itself from the anchor to the end. */
+  const wipe = (forward: boolean, last: Date | null) => {
+    if (reduced() || !range) return;
+    const bands = buttons()
+      .filter((button) => button.hasAttribute('data-mk-in-range'))
+      .map((button) => button.previousElementSibling as HTMLElement);
+    if (!forward) bands.reverse();
+    if (bands.length) {
+      keep(
+        gsap.fromTo(
+          bands,
+          { scaleX: 0 },
+          {
+            scaleX: 1,
+            duration: BAND.day,
+            ease: EASE.wipe,
+            stagger: bandGap(bands.length),
+            transformOrigin: forward ? '0% 50%' : '100% 50%',
+            clearProps: 'scale,transform,transformOrigin',
+          },
+        ),
+      );
+    }
+    pop(last ? buttonOf(last) : null);
+  };
+
+  const emit = () => {
+    if (!range) return;
+    options.onChange?.({ ...range });
+    root.dispatchEvent(new CustomEvent('mk:change', { bubbles: true, detail: { ...rangeKeys(range), length: rangeLength(range) } }));
+  };
+
+  const pick = (day: Date) => {
+    const button = buttonOf(day);
+    if (!isPickable(day, rules)) {
+      if (button) keep(shake(button, 3));
+      return;
+    }
+    if (single) {
+      // One click, one day: it pops and the change is reported.
+      range = { start: day, end: day };
+      anchor = null;
+      hover = null;
+      paint();
+      pop(button);
+      emit();
+      return;
+    }
+    const wasAnchor = anchor;
+    const next = pickDay(anchor, day, rules);
+    anchor = next.anchor;
+    hover = anchor;
+    if (!next.range) {
+      paint();
+      if (anchor && button && !reduced()) {
+        pop(button);
+        keep(ringPulse(button));
+      }
+      return;
+    }
+    range = next.range;
+    paint();
+    wipe(wasAnchor !== null && wasAnchor <= day, day);
+    emit();
+  };
+
+  const KEYS: Record<string, (day: Date, shift: boolean) => Date> = {
+    ArrowLeft: (day) => addDays(day, -1),
+    ArrowRight: (day) => addDays(day, 1),
+    ArrowUp: (day) => addDays(day, -7),
+    ArrowDown: (day) => addDays(day, 7),
+    Home: (day) => startOfWeek(day, firstDay),
+    End: (day) => addDays(startOfWeek(day, firstDay), 6),
+    PageUp: (day, shift) => addMonths(day, shift ? -12 : -1),
+    PageDown: (day, shift) => addMonths(day, shift ? 12 : 1),
+  };
+  scope.on(months, 'keydown', (event) => {
+    const key = event as KeyboardEvent;
+    const button = (key.target as Element | null)?.closest('button[data-mk-day]');
+    if (!button) return;
+    const move = KEYS[key.key];
+    if (move) {
+      key.preventDefault();
+      focusDay(move(dayOf(button), key.shiftKey));
+    } else if (key.key === 'Enter' || key.key === ' ') {
+      key.preventDefault();
+      focused = dayOf(button);
+      pick(focused);
+    }
+  });
+  scope.on(months, 'click', (event) => {
+    const button = (event.target as Element | null)?.closest<HTMLButtonElement>('button[data-mk-day]');
+    if (!button) return;
+    focused = dayOf(button);
+    pick(focused);
+  });
+  scope.on(months, 'pointerover', (event) => {
+    if (!anchor) return;
+    const button = (event.target as Element | null)?.closest('button[data-mk-day]');
+    if (!button) return;
+    const day = dayOf(button);
+    if (hover && sameDay(hover, day)) return;
+    hover = day;
+    paint();
+  });
+  scope.on(months, 'pointerleave', () => {
+    if (!anchor || !hover) return;
+    hover = anchor;
+    paint();
+  });
+  const step = (direction: 1 | -1) => {
+    // The focused day follows so that the tabbable day stays in view.
+    focused = addMonths(focused, direction);
+    go(addMonths(month, direction), direction);
+  };
+  scope.on(prevButton, 'click', () => {
+    keep(press(prevButton));
+    step(-1);
+  });
+  scope.on(nextButton, 'click', () => {
+    keep(press(nextButton));
+    step(1);
+  });
+
+  titleEl.textContent = title();
+  build();
+
+  return {
+    setValue(next, animate = true) {
+      if (scope.disposed) return;
+      range = toRange(next);
+      anchor = null;
+      hover = null;
+      if (range && !visible(range.start)) {
+        focused = range.start;
+        go(
+          startOfMonth(range.start),
+          range.start < month ? -1 : 1,
+          () => {
+            if (animate) wipe(true, null);
+          },
+          animate,
+        );
+        return;
+      }
+      if (range) focused = range.start;
+      paint();
+      if (animate) wipe(true, null);
+    },
+    next: () => step(1),
+    prev: () => step(-1),
+    focusDay,
+    get value() {
+      return range ? { ...range } : null;
+    },
+    get month() {
+      return new Date(month);
+    },
+    destroy: () => scope.dispose(),
+  };
+}

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