@yewdiel21/motion-kit 0.10.0 → 0.14.0

package/src/components/date-range-picker/engine.ts

@@ -0,0 +1,352 @@
+import { gsap, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { dayKey, toDate, type DateInput } from '../../core/dates';
+import { daysIn } from '../../core/segments';
+import { createSegmentField, type SegmentValues } from '../../core/segment-field';
+import { isPickable, rangeIsPickable, rangeKeys, rangeLength, toRange, type DateRange, type DayRules } from '../../core/date-range';
+import { press, shake } from '../../motion/micro';
+import { flowInMenu } from '../../motion/entrances';
+import { createDialog } from '../dialog/engine';
+import { bandDuration, createRangeCalendar } from '../range-calendar/engine';
+
+/*
+ * Date range picker: a field group with two segmented dates (start – end, the
+ * locale's order: dd/mm/aaaa in Spanish) and a calendar button. The button
+ * opens a range-calendar in an anchored dialog that grows out of it (two months
+ * from 680 px, one below), with optional preset chips above; like a menu's
+ * options, its content flows in while the surface grows. Typing two
+ * complete dates validates them: an end before the start, a day out of
+ * min/max or a range crossing an unavailable day marks the field invalid,
+ * explains why under it and shakes once when focus leaves. Picking in the
+ * calendar fills both fields (the digits roll), keeps the popover while the
+ * band draws and the end day pops, plus a moment to see them (SETTLE), then
+ * folds it back into the button, which gets the focus back; touching the
+ * calendar meanwhile keeps it open. onChange only reports valid ranges.
+ */
+
+export interface DateRangePreset {
+  label: string;
+  start: DateInput;
+  end: DateInput;
+}
+
+export interface DateRangePickerOptions {
+  value?: { start: DateInput; end: DateInput } | null;
+  min?: DateInput | null;
+  max?: DateInput | null;
+  unavailable?: string[] | ((day: Date) => boolean);
+  firstDay?: number;
+  locale?: string;
+  today?: DateInput;
+  /** Accessible name of the field (default 'Fechas'). */
+  label?: string;
+  /** Hidden inputs name[start] and name[end] (YYYY-MM-DD). */
+  name?: string;
+  presets?: DateRangePreset[];
+  disabled?: boolean;
+  onChange?: (range: DateRange | null) => void;
+}
+
+export interface DateRangePickerInstance extends Instance {
+  open(): void;
+  close(): void;
+  setValue(range: { start: DateInput; end: DateInput } | null): void;
+  readonly value: DateRange | null;
+  readonly isOpen: boolean;
+}
+
+const CALENDAR_ICON =
+  '<svg aria-hidden="true" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="3.5" y="5" width="17" height="15.5" rx="3"/><path d="M3.5 10h17M8 3v4M16 3v4"/></svg>';
+
+const ERRORS = {
+  order: 'La fecha de fin es anterior a la de inicio',
+  bounds: 'Fecha fuera del rango permitido',
+  blocked: 'El rango incluye días no disponibles',
+} as const;
+
+let sequence = 0;
+/** Seconds the picked range stays in view after its band has drawn, before the popover folds back. */
+const SETTLE = 0.35;
+
+/** A complete date from the segments, or null; years 0–99 stay years 0–99 (setFullYear). */
+const dateOf = (values: SegmentValues): Date | null => {
+  const { day, month, year } = values;
+  if (day == null || month == null || year == null || day > daysIn(year, month)) return null;
+  const date = new Date(2000, 0, 1);
+  date.setFullYear(year, month - 1, day);
+  return date;
+};
+
+const segmentsOf = (date: Date | null) => (date ? { day: date.getDate(), month: date.getMonth() + 1, year: date.getFullYear() } : { day: null, month: null, year: null });
+
+export function createDateRangePicker(root: HTMLElement | null, options: DateRangePickerOptions = {}): DateRangePickerInstance {
+  if (!root) return inert({ open() {}, close() {}, setValue() {}, value: null, isOpen: false });
+  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 uid = `mk-range-${++sequence}`;
+  const locale = options.locale ?? root.closest('[lang]')?.getAttribute('lang') ?? 'es';
+  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,
+  };
+  const presets = options.presets ?? [];
+  let value: DateRange | null = toRange(options.value);
+
+  const made: Element[] = [];
+  const field = document.createElement('div');
+  field.dataset.mkRangeField = '';
+  field.setAttribute('role', 'group');
+  field.setAttribute('aria-label', options.label ?? 'Fechas');
+  field.setAttribute('aria-describedby', `${uid}-error`);
+  root.append(field);
+  made.push(field);
+
+  const which = (suffix: string) => ({ day: `día ${suffix}`, month: `mes ${suffix}`, year: `año ${suffix}` });
+  const startField = createSegmentField(field, { kind: 'date', locale, labels: which('de inicio'), disabled: options.disabled, onChange: () => typed() });
+  startField.element.setAttribute('data-mk-range-start', '');
+  startField.element.setAttribute('aria-label', 'Fecha de inicio');
+  const dash = document.createElement('span');
+  dash.dataset.mkRangeDash = '';
+  dash.setAttribute('aria-hidden', 'true');
+  dash.textContent = '–';
+  field.append(dash);
+  const endField = createSegmentField(field, { kind: 'date', locale, labels: which('de fin'), disabled: options.disabled, onChange: () => typed() });
+  endField.element.setAttribute('data-mk-range-end', '');
+  endField.element.setAttribute('aria-label', 'Fecha de fin');
+  scope.add(() => {
+    startField.destroy();
+    endField.destroy();
+  });
+  const button = document.createElement('button');
+  button.type = 'button';
+  button.dataset.mkRangeButton = '';
+  button.setAttribute('aria-label', 'Abrir calendario');
+  button.setAttribute('aria-haspopup', 'dialog');
+  button.setAttribute('aria-expanded', 'false');
+  button.disabled = Boolean(options.disabled);
+  button.innerHTML = CALENDAR_ICON;
+  field.append(button);
+
+  const error = document.createElement('p');
+  error.dataset.mkRangeError = '';
+  error.id = `${uid}-error`;
+  error.setAttribute('aria-live', 'polite');
+  error.hidden = true;
+  root.append(error);
+  made.push(error);
+
+  const dialogElement = document.createElement('dialog');
+  // A class, not only an attribute: the copy that folds back into the button on close keeps classes only.
+  dialogElement.className = 'mk-dialog mk-range-popover';
+  dialogElement.dataset.mkRangePopover = '';
+  dialogElement.setAttribute('aria-label', 'Elegir fechas');
+  const presetsHost = document.createElement('div');
+  presetsHost.dataset.mkRangePresets = '';
+  presetsHost.setAttribute('role', 'group');
+  presetsHost.setAttribute('aria-label', 'Atajos');
+  presets.forEach((preset, index) => {
+    const chip = document.createElement('button');
+    chip.type = 'button';
+    chip.dataset.mkRangePreset = '';
+    chip.dataset.mkIndex = String(index);
+    chip.textContent = preset.label;
+    presetsHost.append(chip);
+  });
+  const calendarHost = document.createElement('div');
+  calendarHost.className = 'mk-range-calendar';
+  if (presets.length) dialogElement.append(presetsHost);
+  dialogElement.append(calendarHost);
+  root.append(dialogElement);
+  made.push(dialogElement);
+
+  let hiddenStart: HTMLInputElement | null = null;
+  let hiddenEnd: HTMLInputElement | null = null;
+  if (options.name) {
+    const hiddenInput = (key: 'start' | 'end') => {
+      const input = document.createElement('input');
+      input.type = 'hidden';
+      input.name = `${options.name}[${key}]`;
+      root.append(input);
+      made.push(input);
+      return input;
+    };
+    hiddenStart = hiddenInput('start');
+    hiddenEnd = hiddenInput('end');
+  }
+  scope.add(() => made.forEach((node) => node.remove()));
+  // Listeners on the picker hear the picker, not the calendar inside its popover.
+  scope.on(dialogElement, 'mk:change', (event) => event.stopPropagation());
+  scope.attr(root, 'data-mk-ready', '');
+
+  const showError = (code: keyof typeof ERRORS | null) => {
+    error.textContent = code ? ERRORS[code] : '';
+    error.hidden = !code;
+    if (code) field.setAttribute('aria-invalid', 'true');
+    else field.removeAttribute('aria-invalid');
+  };
+
+  const check = (range: DateRange): keyof typeof ERRORS | null => {
+    if (range.end < range.start) return 'order';
+    const bounds = { min: rules.min, max: rules.max };
+    if (!isPickable(range.start, bounds) || !isPickable(range.end, bounds)) return 'bounds';
+    if (!rangeIsPickable(range, rules)) return 'blocked';
+    return null;
+  };
+
+  const writeHidden = () => {
+    if (hiddenStart) hiddenStart.value = value ? dayKey(value.start) : '';
+    if (hiddenEnd) hiddenEnd.value = value ? dayKey(value.end) : '';
+  };
+
+  let calendarReady = false;
+  const commit = (range: DateRange | null, fill: boolean) => {
+    const same = range && value ? dayKey(range.start) === dayKey(value.start) && dayKey(range.end) === dayKey(value.end) : range === value;
+    value = range;
+    if (fill) {
+      startField.setValues(segmentsOf(range?.start ?? null), true);
+      endField.setValues(segmentsOf(range?.end ?? null), true);
+      showError(null);
+    }
+    writeHidden();
+    if (same) return;
+    if (calendarReady) calendar.setValue(range ? rangeKeys(range) : null, false);
+    options.onChange?.(range ? { ...range } : null);
+    root.dispatchEvent(new CustomEvent('mk:change', { bubbles: true, detail: range ? { ...rangeKeys(range), length: rangeLength(range) } : null }));
+  };
+
+  // Typing: validate as soon as both dates are complete; report only a new valid range.
+  const typed = () => {
+    const start = dateOf(startField.values());
+    const end = dateOf(endField.values());
+    if (!start || !end) return showError(null);
+    const range = { start, end };
+    const code = check(range);
+    showError(code);
+    if (code) return;
+    commit(range, false);
+  };
+  // The shake waits until focus leaves the field, so it never fires mid-typing.
+  scope.on(field, 'focusout', (event) => {
+    if (!field.contains((event as FocusEvent).relatedTarget as Node | null) && field.hasAttribute('aria-invalid')) keep(shake(field));
+  });
+
+  const wide = typeof matchMedia === 'function' && matchMedia('(min-width: 680px)').matches;
+  const calendar = createRangeCalendar(calendarHost, {
+    value: value ? rangeKeys(value) : null,
+    visibleMonths: wide ? 2 : 1,
+    firstDay: options.firstDay,
+    min: options.min,
+    max: options.max,
+    unavailable: options.unavailable,
+    locale,
+    today: options.today,
+    onChange: (range) => {
+      commit(range, true);
+      cancelClose();
+      if (reduced()) return popover.close();
+      // The band draws and the end day pops; the range stays in view a moment, then the panel folds back.
+      closing = setTimeout(() => {
+        closing = undefined;
+        popover.close();
+      }, (bandDuration(rangeLength(range)) + SETTLE) * 1000);
+    },
+  });
+  calendarReady = true;
+  scope.add(() => calendar.destroy());
+
+  let closing: ReturnType<typeof setTimeout> | undefined;
+  const cancelClose = () => {
+    clearTimeout(closing);
+    closing = undefined;
+  };
+  scope.add(cancelClose);
+  // Touching the calendar again while a picked range settles keeps the popover open (capture: before a pick).
+  scope.on(dialogElement, 'pointerdown', cancelClose, true);
+  scope.on(dialogElement, 'keydown', cancelClose, true);
+  const startDay = () => value?.start ?? options.today ?? new Date();
+
+  const popover = createDialog(dialogElement, {
+    placement: 'anchor',
+    backdrop: false,
+    drag: false,
+    autoResize: false,
+    triggers: false,
+    animateContent: false,
+    onOpen: () => {
+      calendar.focusDay(startDay(), false);
+      // Like a menu's options: the presets, the header and the months flow in while the surface grows.
+      keep(flowInMenu([...dialogElement.querySelectorAll<HTMLElement>('[data-mk-range-presets], [data-mk-range-header], [data-mk-range-month]')]));
+    },
+    onClose: () => {
+      cancelClose();
+      button.setAttribute('aria-expanded', 'false');
+    },
+  });
+  scope.add(() => popover.destroy());
+
+  const open = () => {
+    if (options.disabled || popover.isOpen) return;
+    // The calendar shows the range (or today) before the panel is measured and placed; a half-picked range is dropped.
+    calendar.setValue(value ? rangeKeys(value) : null, false);
+    calendar.focusDay(startDay(), false);
+    popover.open(button);
+    button.setAttribute('aria-expanded', 'true');
+  };
+  scope.on(button, 'click', () => {
+    keep(press(button));
+    if (popover.isOpen) popover.close();
+    else open();
+  });
+  // Presets: commit, show it in the calendar, close.
+  scope.on(presetsHost, 'click', (event) => {
+    const chip = (event.target as Element | null)?.closest<HTMLButtonElement>('[data-mk-range-preset]');
+    if (!chip) return;
+    const chosen = toRange(presets[Number(chip.dataset.mkIndex)]);
+    if (!chosen) return;
+    keep(press(chip));
+    commit(chosen, true);
+    popover.close();
+  });
+  scope.add(() => {
+    for (const effect of effects) effect.kill();
+    effects.clear();
+  });
+
+  startField.setValues(segmentsOf(value?.start ?? null));
+  endField.setValues(segmentsOf(value?.end ?? null));
+  writeHidden();
+
+  return {
+    open,
+    close: () => popover.close(),
+    setValue(next) {
+      if (scope.disposed) return;
+      const range = toRange(next);
+      const same = range && value ? dayKey(range.start) === dayKey(value.start) && dayKey(range.end) === dayKey(value.end) : range === value;
+      value = range;
+      startField.setValues(segmentsOf(range?.start ?? null), true);
+      endField.setValues(segmentsOf(range?.end ?? null), true);
+      showError(null);
+      writeHidden();
+      if (!same) calendar.setValue(range ? rangeKeys(range) : null, false);
+    },
+    get value() {
+      return value ? { ...value } : null;
+    },
+    get isOpen() {
+      return popover.isOpen;
+    },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/date-range-picker/react.tsx

@@ -0,0 +1,57 @@
+'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 { createDateRangePicker, type DateRangePickerInstance, type DateRangePickerOptions } from './engine';
+
+type RangeValue = { start: DateInput; end: DateInput } | null;
+
+export interface DateRangePickerProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue'>, Omit<DateRangePickerOptions, 'value'> {
+  /** Controlled range; without it the picker keeps its own (defaultValue). */
+  value?: RangeValue;
+  defaultValue?: RangeValue;
+}
+
+const keyOf = (value: RangeValue | undefined) => {
+  const range = toRange(value);
+  return range ? JSON.stringify(rangeKeys(range)) : 'null';
+};
+
+/** <DateRangePicker value={range} onChange={setRange} presets={[…]} />. */
+export function DateRangePicker({ value, defaultValue, min, max, unavailable, firstDay, locale, today, label, name, presets, disabled, onChange, className, ...props }: DateRangePickerProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const instance = useRef<DateRangePickerInstance | 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);
+  const presetKey = JSON.stringify(presets ?? null);
+  useIsomorphicLayoutEffect(() => {
+    const created = createDateRangePicker(ref.current, {
+      value: value !== undefined ? value : start.current,
+      min,
+      max,
+      unavailable: typeof unavailable === 'function' ? (day) => (typeof test.current === 'function' ? test.current(day) : false) : unavailable,
+      firstDay,
+      locale,
+      today,
+      label,
+      name,
+      presets,
+      disabled,
+      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(min ?? ''), String(max ?? ''), rules, firstDay, locale, String(today ?? ''), label, name, presetKey, disabled]);
+  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-date-range-picker', className].filter(Boolean).join(' ')} />;
+}

package/src/components/date-time-picker/README.md

@@ -0,0 +1,48 @@
+# date-time-picker
+
+Fecha y hora en un solo control: un campo por segmentos en el orden y con la unión del idioma («23/11/2026, 13:05» en español; 12 h con AM/PM donde el idioma lo usa). El botón del calendario hace crecer un panel desde sí mismo (un diálogo anclado, como `menu`), y su contenido entra en cascada como las opciones de un menú:
+- un calendario de un solo día (`range-calendar` con `selection: 'single'`);
+- un campo de hora (`time-field`);
+- los botones «Ahora» y «Listo».
+
+Elegir un día conserva la hora; cambiar la hora conserva el día; cada cambio hace rodar los dígitos del campo. Al escribir una fecha y hora completas se comprueban `min`, `max` y los días no disponibles: fuera de rango marca el campo, dice por qué debajo y lo sacude una vez al salir. `onChange` informa de los valores válidos (y de `null` si se vacía el campo).
+
+Importa también `css/components/dialog.css`, `range-calendar.css` y `time-field.css` (o el CSS completo). La CLI los copia: la entrada `requires` dialog, range-calendar y time-field.
+
+## HTML / Astro
+
+```html
+<mk-date-time-picker class="mk-date-time-picker" value="2026-11-23T10:30" minute-step="15"
+  min="2026-11-10T08:00" name="cita"></mk-date-time-picker>
+```
+
+## React
+
+```tsx
+<DateTimePicker value={when} onChange={setWhen} minuteStep={15} unavailable={(day) => day.getDay() === 0} />
+```
+
+## Opciones
+
+| Opción | Atributo | Por defecto | Qué hace |
+|---|---|---|---|
+| `value` | `value` | — | Date o `'AAAA-MM-DDTHH:MM'` (hora local). |
+| `min`, `max` | `min`, `max` | — | Límites (con hora). |
+| `locale` | `locale` | `lang` de la página, o `es` | Orden de los segmentos y nombres. |
+| `hourCycle` | `hour-cycle` | el del idioma | `12` o `24`. |
+| `minuteStep` | `minute-step` | `5` | Paso de los minutos con las flechas. |
+| `firstDay` | `first-day` | `1` (lunes) | Primer día de la semana. |
+| `unavailable` | `unavailable` (lista) | — | Días `'AAAA-MM-DD'` o una función. |
+| `today` | `today` | hoy | Para demos y pruebas. |
+| `label` | `label` | `'Fecha y hora'` | Nombre accesible del campo. |
+| `name` | `name` | — | Campo oculto con `'AAAA-MM-DDTHH:MM'`. |
+| `disabled` | `disabled` | `false` | Desactivado. |
+| `onChange(value)` | — | — | Date válido o `null`. |
+
+## API y eventos
+
+`open()`, `close()`, `setValue(valor | null)`, `value`, `isOpen`, `destroy()`. Evento `mk:change` con `{ value: 'AAAA-MM-DDTHH:MM' | null }`. Utilidades `toDateTimeValue(input)` y `dateTimeKey(date)`.
+
+## Teclado
+
+En el campo, el de `time-field`: las flechas cambian el segmento, los dígitos lo rellenan y pasan al siguiente, Retroceso borra y vuelve. En el panel, el de `range-calendar` y `time-field`; Escape o «Listo» lo cierran y el foco vuelve al botón. Con movimiento reducido el panel aparece sin crecer y no hay rodillo, sacudida ni píldora.

package/src/components/date-time-picker/date-time-picker.css

@@ -0,0 +1,177 @@
+/* date-time-picker — one 12 px field on surface-3 holding the date and time segments and an 8 px calendar button;
+   the focused segment sits on a 6 px accent-soft pill; invalid draws an error ring and a message under it. The popover
+   (an anchored dialog: needs dialog.css, range-calendar.css and time-field.css) has 20 px corners. */
+.mk-date-time-picker,
+mk-date-time-picker {
+  display: inline-block;
+  max-width: 100%;
+}
+
+[data-mk-dt-field] {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.35rem;
+  box-sizing: border-box;
+  max-width: 100%;
+  min-height: 2.75rem;
+  padding: 0.25rem 0.25rem 0.25rem 0.75rem;
+  border-radius: 12px;
+  background: var(--mk-surface-3);
+  color: var(--mk-text);
+  font-variant-numeric: tabular-nums;
+  transition: box-shadow 0.2s ease;
+}
+
+[data-mk-dt-field]:focus-within {
+  box-shadow: 0 0 0 3px color-mix(in srgb, var(--mk-accent) 35%, transparent);
+}
+
+[data-mk-dt-field]:has([aria-invalid='true']) {
+  box-shadow: 0 0 0 2px var(--mk-error, #c62828);
+}
+
+[data-mk-dt-field] [data-mk-segments] {
+  position: relative;
+  display: inline-flex;
+  flex-wrap: wrap;
+  align-items: center;
+  min-width: 0;
+}
+
+[data-mk-dt-field] [data-mk-segment] {
+  position: relative;
+  z-index: 1;
+  padding: 0.2rem 0.15rem;
+  border-radius: 6px;
+  caret-color: transparent;
+  outline: none;
+  cursor: default;
+}
+
+[data-mk-dt-field] [data-mk-segment][data-mk-empty] {
+  color: var(--mk-muted);
+}
+
+[data-mk-dt-field] [data-mk-segment]:focus {
+  color: var(--mk-on-accent-soft, var(--mk-text));
+}
+
+[data-mk-dt-field] [data-mk-segment]::selection {
+  background: transparent;
+}
+
+[data-mk-dt-field] [data-mk-segment-literal] {
+  padding: 0 0.05rem;
+  color: var(--mk-muted);
+  white-space: pre;
+}
+
+[data-mk-dt-field] [data-mk-segment-focus] {
+  position: absolute;
+  top: 50%;
+  left: 0;
+  height: 1.75rem;
+  margin-top: -0.875rem;
+  border-radius: 6px;
+  background: var(--mk-accent-soft);
+  opacity: 0;
+  pointer-events: none;
+}
+
+[data-mk-dt-button] {
+  display: grid;
+  flex: none;
+  place-items: center;
+  width: 2.25rem;
+  height: 2.25rem;
+  margin-left: auto;
+  padding: 0;
+  border: 0;
+  border-radius: 8px;
+  background: var(--mk-surface-1);
+  color: inherit;
+  cursor: pointer;
+}
+
+[data-mk-dt-button]:focus-visible {
+  outline: 3px solid color-mix(in srgb, var(--mk-accent) 45%, transparent);
+  outline-offset: 2px;
+}
+
+[data-mk-dt-error] {
+  margin: 0.4rem 0 0;
+  color: var(--mk-error, #c62828);
+  font-size: 0.8125rem;
+}
+
+[data-mk-dt-error][hidden] {
+  display: none;
+}
+
+/* Classes, not data attributes: the copy that folds back into the button on close keeps only the classes. */
+.mk-dialog.mk-dt-popover {
+  --mk-dialog-radius: 20px;
+  --mk-dialog-bg: var(--mk-surface-1);
+  width: max-content;
+  max-width: calc(100vw - 16px);
+}
+
+.mk-dialog.mk-dt-popover > .mk-range-calendar {
+  display: grid;
+  box-sizing: border-box;
+  max-width: 100%;
+  padding-bottom: 0.25rem;
+}
+
+[data-mk-dt-time-row] {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.75rem;
+  padding: 0.25rem 0.75rem;
+}
+
+[data-mk-dt-time-label] {
+  color: var(--mk-muted);
+  font-size: 0.875rem;
+  font-weight: 500;
+}
+
+[data-mk-dt-footer] {
+  display: flex;
+  justify-content: flex-end;
+  gap: 0.5rem;
+  padding: 0.5rem 0.75rem 0.75rem;
+}
+
+[data-mk-dt-footer] button {
+  min-height: 2.25rem;
+  padding: 0 0.9rem;
+  border: 0;
+  border-radius: 8px;
+  background: var(--mk-surface-3);
+  color: var(--mk-text);
+  font: inherit;
+  font-size: 0.875rem;
+  font-weight: 500;
+  cursor: pointer;
+}
+
+[data-mk-dt-footer] [data-mk-dt-done] {
+  background: var(--mk-accent);
+  color: var(--mk-on-accent);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-mk-dt-field] [data-mk-segment]:focus {
+    background: var(--mk-accent-soft);
+  }
+
+  [data-mk-dt-field] [data-mk-segment-focus] {
+    display: none;
+  }
+
+  [data-mk-dt-field] {
+    transition: none;
+  }
+}

package/src/components/date-time-picker/element.ts

@@ -0,0 +1,47 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createDateTimePicker, type DateTimePickerInstance } from './engine';
+
+/**
+ * <mk-date-time-picker class="mk-date-time-picker" value="2026-11-23T10:30" minute-step="15" name="cita"></mk-date-time-picker>
+ * Emits mk:change ({value: 'YYYY-MM-DDTHH:MM' | null}).
+ */
+export class MkDateTimePickerElement extends MkElement<DateTimePickerInstance> {
+  static options: Record<string, OptionType> = {
+    value: 'string',
+    min: 'string',
+    max: 'string',
+    locale: 'string',
+    hourCycle: 'number',
+    minuteStep: 'number',
+    firstDay: 'number',
+    unavailable: 'list',
+    today: 'string',
+    label: 'string',
+    name: 'string',
+    disabled: 'boolean',
+  };
+
+  protected create(options: Record<string, unknown>) {
+    return createDateTimePicker(this, options);
+  }
+
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.instance) return;
+    if (name === 'value') this.instance.setValue(next);
+    else super.attributeChangedCallback(name, previous, next);
+  }
+
+  open() {
+    this.instance?.open();
+  }
+
+  close() {
+    this.instance?.close();
+  }
+
+  get value() {
+    return this.instance?.value ?? null;
+  }
+}
+
+export const defineDateTimePicker = () => defineElement('mk-date-time-picker', MkDateTimePickerElement);