@yewdiel21/motion-kit 0.9.1 → 0.14.0

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

@@ -0,0 +1,350 @@
+import { gsap, registerMotion } from '../../core/gsap';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { dayKey, toDate, type DateInput } from '../../core/dates';
+import { daysIn, formatTime, to12, to24 } from '../../core/segments';
+import { createSegmentField, type SegmentValues } from '../../core/segment-field';
+import { isPickable, type DayRules } from '../../core/date-range';
+import { press, shake } from '../../motion/micro';
+import { flowInMenu } from '../../motion/entrances';
+import { createDialog } from '../dialog/engine';
+import { createRangeCalendar } from '../range-calendar/engine';
+import { createTimeField } from '../time-field/engine';
+
+/*
+ * Date-time picker: date and time in one segmented field, in the locale's
+ * order and joint ("23/11/2026, 13:05" in Spanish; 12 h with AM/PM where the
+ * locale writes it). The calendar button grows a panel out of itself (an
+ * anchored dialog, like menu) whose content flows in like a menu's options: a
+ * one-day calendar (range-calendar, selection: 'single'), a time field and
+ * "Ahora" / "Listo". Picking a day keeps the time; changing the time keeps the
+ * day; every change rolls the field's digits. Typing a complete date and time
+ * checks min, max and unavailable days: out of bounds marks the field invalid,
+ * says why under it and shakes once when focus leaves. onChange reports valid
+ * values (and null when the field is emptied).
+ */
+
+export interface DateTimePickerOptions {
+  /** A Date or 'YYYY-MM-DDTHH:MM' (local). */
+  value?: DateInput | null;
+  min?: DateInput | null;
+  max?: DateInput | null;
+  locale?: string;
+  hourCycle?: 12 | 24;
+  /** Arrow step of the minutes (default 5). */
+  minuteStep?: number;
+  firstDay?: number;
+  unavailable?: string[] | ((day: Date) => boolean);
+  /** Override "today" (demos, tests). */
+  today?: DateInput;
+  /** Accessible name of the field (default 'Fecha y hora'). */
+  label?: string;
+  /** Hidden input with 'YYYY-MM-DDTHH:MM'. */
+  name?: string;
+  disabled?: boolean;
+  onChange?: (value: Date | null) => void;
+}
+
+export interface DateTimePickerInstance extends Instance {
+  open(): void;
+  close(): void;
+  setValue(value: DateInput | null): void;
+  readonly value: Date | 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"/><path d="M12 13.5v2.5l1.6 1"/></svg>';
+let sequence = 0;
+const pad = (n: number) => String(n).padStart(2, '0');
+
+/** A local date-time from a Date or 'YYYY-MM-DD[T ]HH:MM[:SS]'; null when unreadable. */
+export function toDateTimeValue(input: DateInput | null | undefined): Date | null {
+  if (input === null || input === undefined || input === '') return null;
+  if (input instanceof Date) return Number.isNaN(input.getTime()) ? null : new Date(input.getTime());
+  if (typeof input === 'string') {
+    const match = /^(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2})(?::(\d{2}))?)?$/.exec(input.trim());
+    if (match) {
+      const date = new Date(2000, 0, 1);
+      date.setFullYear(Number(match[1]), Number(match[2]) - 1, Number(match[3]));
+      date.setHours(Number(match[4] ?? 0), Number(match[5] ?? 0), Number(match[6] ?? 0), 0);
+      return date;
+    }
+  }
+  const parsed = new Date(input);
+  return Number.isNaN(parsed.getTime()) ? null : parsed;
+}
+
+/** 'YYYY-MM-DDTHH:MM' of a local date-time (what <input type="datetime-local"> posts). */
+export const dateTimeKey = (date: Date) => `${dayKey(date)}T${pad(date.getHours())}:${pad(date.getMinutes())}`;
+
+export function createDateTimePicker(root: HTMLElement | null, options: DateTimePickerOptions = {}): DateTimePickerInstance {
+  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);
+  };
+  scope.add(() => {
+    for (const effect of effects) effect.kill();
+    effects.clear();
+  });
+  const uid = `mk-datetime-${++sequence}`;
+  const locale = options.locale ?? root.closest('[lang]')?.getAttribute('lang') ?? 'es';
+  const step = options.minuteStep && options.minuteStep > 0 ? Math.round(options.minuteStep) : 5;
+  const min = toDateTimeValue(options.min);
+  const max = toDateTimeValue(options.max);
+  const unavailable = options.unavailable;
+  const rules: DayRules = {
+    isUnavailable: typeof unavailable === 'function' ? unavailable : Array.isArray(unavailable) ? (day) => unavailable.includes(dayKey(day)) : undefined,
+  };
+  let value: Date | null = toDateTimeValue(options.value);
+
+  const made: Element[] = [];
+  const box = document.createElement('div');
+  box.dataset.mkDtField = '';
+  root.append(box);
+  made.push(box);
+  const field = createSegmentField(box, {
+    kind: 'datetime',
+    locale,
+    hour12: options.hourCycle ? options.hourCycle === 12 : undefined,
+    steps: { minute: step },
+    disabled: options.disabled,
+    onChange: () => typed(),
+  });
+  scope.add(() => field.destroy());
+  field.element.setAttribute('aria-label', options.label ?? 'Fecha y hora');
+  field.element.setAttribute('aria-describedby', `${uid}-error`);
+  const twelve = field.element.querySelector('[data-mk-segment="dayPeriod"]') !== null;
+  const button = document.createElement('button');
+  button.type = 'button';
+  button.dataset.mkDtButton = '';
+  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;
+  box.append(button);
+  const error = document.createElement('p');
+  error.id = `${uid}-error`;
+  error.dataset.mkDtError = '';
+  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-dt-popover';
+  dialogElement.dataset.mkDtPopover = '';
+  dialogElement.setAttribute('aria-label', 'Elegir fecha y hora');
+  const calendarHost = document.createElement('div');
+  calendarHost.className = 'mk-range-calendar';
+  const timeRow = document.createElement('div');
+  timeRow.dataset.mkDtTimeRow = '';
+  const timeLabel = document.createElement('span');
+  timeLabel.dataset.mkDtTimeLabel = '';
+  timeLabel.textContent = 'Hora';
+  const timeHost = document.createElement('div');
+  timeHost.className = 'mk-time-field';
+  timeRow.append(timeLabel, timeHost);
+  const footer = document.createElement('div');
+  footer.dataset.mkDtFooter = '';
+  const now = document.createElement('button');
+  now.type = 'button';
+  now.dataset.mkDtNow = '';
+  now.textContent = 'Ahora';
+  const done = document.createElement('button');
+  done.type = 'button';
+  done.dataset.mkDtDone = '';
+  done.dataset.mkClose = '';
+  done.textContent = 'Listo';
+  footer.append(now, done);
+  dialogElement.append(calendarHost, timeRow, footer);
+  root.append(dialogElement);
+  made.push(dialogElement);
+  let hidden: HTMLInputElement | null = null;
+  if (options.name) {
+    hidden = document.createElement('input');
+    hidden.type = 'hidden';
+    hidden.name = options.name;
+    root.append(hidden);
+    made.push(hidden);
+  }
+  scope.add(() => made.forEach((node) => node.remove()));
+  // Listeners on the picker hear the picker, not the calendar and time field inside its panel.
+  scope.on(dialogElement, 'mk:change', (event) => event.stopPropagation());
+  scope.attr(root, 'data-mk-ready', '');
+
+  const segmentsOf = (date: Date | null): SegmentValues => {
+    if (!date) return { day: null, month: null, year: null, hour: null, minute: null, dayPeriod: null };
+    const hour = date.getHours();
+    const clock = twelve ? to12(hour) : { hour, period: null };
+    return { day: date.getDate(), month: date.getMonth() + 1, year: date.getFullYear(), hour: clock.hour, minute: date.getMinutes(), dayPeriod: clock.period };
+  };
+  const dateOf = (values: SegmentValues): Date | null => {
+    const { day, month, year, hour, minute } = values;
+    if (day == null || month == null || year == null || hour == null || minute == null || (twelve && values.dayPeriod == null)) return null;
+    if (day > daysIn(year, month)) return null;
+    const date = new Date(2000, 0, 1);
+    date.setFullYear(year, month - 1, day);
+    date.setHours(twelve ? to24(hour, values.dayPeriod!) : hour, minute, 0, 0);
+    return date;
+  };
+  const empty = (values: SegmentValues) => Object.values(values).every((part) => part == null);
+
+  const showError = (message: string | null) => {
+    error.textContent = message ?? '';
+    error.hidden = !message;
+    field.invalid(Boolean(message));
+  };
+  const problem = (date: Date) => {
+    if ((min && date < min) || (max && date > max)) return 'Fuera del rango permitido';
+    if (!isPickable(toDate(date), rules)) return 'Ese día no está disponible';
+    return null;
+  };
+
+  let calendarReady = false;
+  /** Make `next` the value: the field (rolling), the calendar, the time field, the form; report it. */
+  const commit = (next: Date | null, fill: boolean, notify = true) => {
+    const same = next && value ? next.getTime() === value.getTime() : next === value;
+    value = next;
+    if (fill) field.setValues(segmentsOf(next), true);
+    showError(null);
+    if (hidden) hidden.value = next ? dateTimeKey(next) : '';
+    if (calendarReady) {
+      calendar.setValue(next ? { start: dayKey(next), end: dayKey(next) } : null, false);
+      timeField.setValue(next ? formatTime({ hour: next.getHours(), minute: next.getMinutes(), second: 0 }) : null, true);
+    }
+    if (same || !notify) return;
+    options.onChange?.(next ? new Date(next.getTime()) : null);
+    root.dispatchEvent(new CustomEvent('mk:change', { bubbles: true, detail: { value: next ? dateTimeKey(next) : null } }));
+  };
+
+  // Typing: a complete, allowed date-time becomes the value; an emptied field reports null.
+  const typed = () => {
+    const values = field.values();
+    if (empty(values)) return commit(null, false);
+    const date = dateOf(values);
+    if (!date) return showError(null);
+    const why = problem(date);
+    if (why) return showError(why);
+    commit(date, false);
+  };
+  scope.on(box, 'focusout', (event) => {
+    if (!box.contains((event as FocusEvent).relatedTarget as Node | null) && field.element.hasAttribute('aria-invalid')) keep(shake(box));
+  });
+
+  /** The time of day to keep when only the day is picked: the value's, else the time field's, else now (on the step). */
+  const rounded = (date: Date) => {
+    const result = new Date(date.getTime());
+    result.setSeconds(0, 0);
+    result.setMinutes(Math.round(result.getMinutes() / step) * step);
+    return result;
+  };
+  /** Inside min and max (a day picked in the panel keeps its time unless that falls outside). */
+  const clamp = (date: Date) => (min && date < min ? new Date(min.getTime()) : max && date > max ? new Date(max.getTime()) : date);
+  const timeOfDay = () => {
+    if (value) return { hour: value.getHours(), minute: value.getMinutes() };
+    const time = timeField.value?.split(':').map(Number);
+    if (time && time.length >= 2) return { hour: time[0]!, minute: time[1]! };
+    const current = rounded(new Date());
+    return { hour: current.getHours(), minute: current.getMinutes() };
+  };
+
+  const calendar = createRangeCalendar(calendarHost, {
+    selection: 'single',
+    value: value ? { start: dayKey(value), end: dayKey(value) } : null,
+    firstDay: options.firstDay,
+    min: min ? dayKey(min) : null,
+    max: max ? dayKey(max) : null,
+    unavailable: options.unavailable,
+    locale,
+    today: options.today,
+    onChange: (range) => {
+      const { hour, minute } = timeOfDay();
+      const next = new Date(range.start.getTime());
+      next.setHours(hour, minute, 0, 0);
+      commit(clamp(next), true);
+    },
+  });
+  scope.add(() => calendar.destroy());
+  const timeField = createTimeField(timeHost, {
+    value: value ? formatTime({ hour: value.getHours(), minute: value.getMinutes(), second: 0 }) : null,
+    locale,
+    hourCycle: options.hourCycle,
+    minuteStep: step,
+    label: 'Hora',
+    onChange: (time) => {
+      if (!time) return;
+      const [hour, minute] = time.split(':').map(Number);
+      const base = value ?? toDate(options.today ?? new Date());
+      const next = new Date(base.getTime());
+      next.setHours(hour!, minute!, 0, 0);
+      commit(clamp(next), true);
+    },
+  });
+  scope.add(() => timeField.destroy());
+  calendarReady = true;
+
+  const startDay = () => value ?? toDate(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 calendar, the time and the buttons flow in while the surface grows.
+      keep(flowInMenu([...dialogElement.querySelectorAll<HTMLElement>('[data-mk-range-header], [data-mk-range-month], [data-mk-dt-time-row], [data-mk-dt-footer]')]));
+    },
+    onClose: () => button.setAttribute('aria-expanded', 'false'),
+  });
+  scope.add(() => popover.destroy());
+
+  const open = () => {
+    if (options.disabled || popover.isOpen) return;
+    // The calendar shows the value's month before the panel is measured and placed.
+    calendar.setValue(value ? { start: dayKey(value), end: dayKey(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();
+  });
+  scope.on(now, 'click', () => {
+    keep(press(now));
+    const current = rounded(new Date());
+    commit(problem(current) ? value : current, true);
+    calendar.focusDay(current, false);
+  });
+
+  field.setValues(segmentsOf(value));
+  if (hidden) hidden.value = value ? dateTimeKey(value) : '';
+
+  return {
+    open,
+    close: () => popover.close(),
+    setValue(next) {
+      if (scope.disposed) return;
+      commit(toDateTimeValue(next), true, false);
+    },
+    get value() {
+      return value ? new Date(value.getTime()) : null;
+    },
+    get isOpen() {
+      return popover.isOpen;
+    },
+    destroy: () => scope.dispose(),
+  };
+}

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

@@ -0,0 +1,54 @@
+'use client';
+import { useRef, type HTMLAttributes } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import type { DateInput } from '../../core/dates';
+import { createDateTimePicker, dateTimeKey, toDateTimeValue, type DateTimePickerInstance, type DateTimePickerOptions } from './engine';
+
+export interface DateTimePickerProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue'>, Omit<DateTimePickerOptions, 'value'> {
+  /** Controlled value (Date or 'YYYY-MM-DDTHH:MM'); without it the picker keeps its own (defaultValue). */
+  value?: DateInput | null;
+  defaultValue?: DateInput | null;
+}
+
+const keyOf = (value: DateInput | null | undefined) => {
+  const date = toDateTimeValue(value);
+  return date ? dateTimeKey(date) : 'null';
+};
+
+/** <DateTimePicker value={when} onChange={setWhen} minuteStep={15} />. */
+export function DateTimePicker({ value, defaultValue, min, max, locale, hourCycle, minuteStep, firstDay, unavailable, today, label, name, disabled, onChange, className, ...props }: DateTimePickerProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const instance = useRef<DateTimePickerInstance | null>(null);
+  const change = useLatest(onChange);
+  const test = useLatest(unavailable);
+  const start = useRef<DateInput | null>(value !== undefined ? value : (defaultValue ?? null));
+  const rules = typeof unavailable === 'function' ? 'function' : JSON.stringify(unavailable ?? null);
+  useIsomorphicLayoutEffect(() => {
+    const created = createDateTimePicker(ref.current, {
+      value: value !== undefined ? value : start.current,
+      min,
+      max,
+      locale,
+      hourCycle,
+      minuteStep,
+      firstDay,
+      unavailable: typeof unavailable === 'function' ? (day) => (typeof test.current === 'function' ? test.current(day) : false) : unavailable,
+      today,
+      label,
+      name,
+      disabled,
+      onChange: (next) => change.current?.(next),
+    });
+    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 ?? ''), locale, hourCycle, minuteStep, firstDay, rules, String(today ?? ''), label, name, 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-time-picker', className].filter(Boolean).join(' ')} />;
+}

package/src/components/dialog/README.md

@@ -1,102 +1,103 @@
-# dialog
-
-El diálogo sobre `<dialog>` nativo (foco atrapado, Escape, capa superior). El botón que lo abre se convierte en el diálogo y al cerrar vuelve a él.
-
-- **Abrir desde el botón (morph):** la superficie viaja recortada desde el rect del botón en 0.7 s con la curva signature y toma su color en 0.3 s; el contenido crece como grupo desde la caja del botón con blur 8 → 0. El botón se oculta en 80 ms mientras está "dentro".
-- **Elementos compartidos:** `data-mk-shared="titulo"` en una pieza del botón y otra del diálogo: el texto vuela de una a otra (0.7 s al abrir, 0.5 s al cerrar).
-- **Sin botón en pantalla:** escala .92 → 1 en 0.35 s (`power2.out`).
-- **Cerrar:** el diálogo se cierra al instante (el foco vuelve y la página responde) mientras una copia inerte se pliega al botón: forma 0.5 s, contenido con blur → 32 px (`.37,.35,0,1`) y fundido (`.56,.27,0,1`), velo `power3.in`; el botón reaparece 0.3 s tras 0.2 s. Sin botón: escala .9 + blur 32.
-- **Líquido** (`variant="liquid"`): dos blobs bajo filtro goo; posición con resorte 144/14 y patada de 2400 px/s, tamaño 0.3 s `cubic(.8,.3,.5,.8)`, radio 0.7 s, contenido `scale 2 → 1` y blur 8 → 0, color 0.4 s tras 0.15 s. Cierre con resorte 130/18.
-- **Backdrop:** tinte 0.5 s con la curva signature (`linear()`).
-- **Auto-resize:** si el contenido crece o se encoge, la altura se ajusta en 0.45 s (signature).
-- **Arrastrar para cerrar:** sigue al puntero a la mitad y encoge (`1 − y/400`); pasados 100 px se cierra donde quedó, si no vuelve con `elastic.out(.5,.5)` 0.5 s. También con la rueda. Ignora controles, áreas con scroll y `[data-mk-no-drag]`.
-- **Ventana flotante** (`float="clave"`, escritorio ≥ 680 px): el asa la levanta (la página sigue usable), se mueve con resorte 1100/38 e inercia, se queda dentro de la pantalla, se redimensiona por las esquinas (mín. 320 × 240) y recuerda su sitio. Un clic en el asa la devuelve.
-- **Móvil (< 680 px):** pantalla completa, radio 0.
-
-- **Sheet** (`variant="sheet"`): la hoja sube desde abajo (`y 100% → 0`, 0.72 s `cubic-bezier(.16,1,.3,1)`) y lo marcado con `[data-mk-underlay]` se hunde a escala .98 y opacidad .4 con un resorte 300/30. Al cerrar, una copia inerte cae por debajo de la pantalla y el foco vuelve al instante. No sale del botón. Mientras está abierta, la página no hace scroll.
-
-## HTML / Astro
-
-```html
-<button class="mk-button" data-mk-open="crear">Crear proyecto</button>
-
-<mk-dialog id="crear" heading="Crear proyecto" description="Se guarda en tu espacio.">
-  <label class="mk-field"><span class="mk-field__label">Nombre</span><input /></label>
-  <div data-mk-part="footer">
-    <button class="mk-button mk-button--text" data-mk-close>Cancelar</button>
-    <button class="mk-button mk-button--primary">Crear</button>
-  </div>
-</mk-dialog>
-
-<script>
-  import { defineElements } from '@yewdiel21/motion-kit/elements';
-  defineElements(['mk-dialog']);
-</script>
-```
-
-Sin `heading`, tus hijos van dentro tal cual si ya usan partes (`data-mk-part="header|body|footer"`), o dentro de un cuerpo si no. Sobre tu propio `<dialog class="mk-dialog">`: `createDialog(dialog, opciones)`.
-
-## React
-
-```tsx
-<Dialog.Root variant="liquid" onOpenChange={setOpen}>
-  <Dialog.Trigger className="mk-button">Crear</Dialog.Trigger>
-  <Dialog.Content>
-    <Dialog.Header>
-      <div><Dialog.Title>Crear proyecto</Dialog.Title></div>
-      <Dialog.Actions><Dialog.Close /></Dialog.Actions>
-    </Dialog.Header>
-    <Dialog.Body>…</Dialog.Body>
-    <Dialog.Footer>…</Dialog.Footer>
-  </Dialog.Content>
-</Dialog.Root>
-```
-
-Las opciones van en `Dialog.Root` (`variant`, `placement`, `float`…). Controlado con `open` + `onOpenChange`, o libre con `defaultOpen`. `Dialog.Trigger` registra su botón como origen.
-
-## Opciones
-
-| Opción | Atributo | Por defecto | Qué hace |
-|---|---|---|---|
-| `variant` | `variant` | `'morph'` | `'liquid'` para la versión líquida; `'sheet'` para la hoja que sube desde abajo |
-| `placement` | `placement` | `'center'` | `'anchor'` junto al botón, `'side'` panel lateral |
-| `backdrop` | `no-backdrop` | `true` | Velo tintado |
-| `closeOnBackdrop` | `persistent` | `true` | Clic fuera cierra |
-| `drag` | `no-drag` | `true` | Arrastrar para cerrar |
-| `float` | `float="clave"` | `false` | Ventana flotante (necesita un `[data-mk-part="handle"]`; con `heading` se crea) |
-| `autoResize` | — | `true` | Ajuste suave de altura |
-| `triggers` | (el `id`) | `true` | `[data-mk-open="<id>"]` lo abre |
-| `modal` | — | `true` | Modal o no |
-| `labels` | `close-label` | `{ close: 'Cerrar', float, dock }` | Textos accesibles |
-| `size` | `size` | `md` (400 px) | `sm` 360, `lg` 640, `xl` 960 |
-
-## Sheet
-
-```html
-<main data-mk-underlay>…la página…</main>
-<button class="mk-button" data-mk-open="proyecto">Ver proyecto</button>
-<mk-dialog id="proyecto" variant="sheet" heading="Private Space">…</mk-dialog>
-```
-
-```tsx
-<Dialog.Root variant="sheet">
-  <Dialog.Trigger>Ver proyecto</Dialog.Trigger>
-  <Dialog.Content>…</Dialog.Content>
-</Dialog.Root>
-```
-
-Ancho hasta `--mk-sheet-max-width` (720px), alto hasta `100dvh − 24px`, radio solo arriba; en el móvil ocupa todo el ancho. Se cierra con Escape, con el fondo, arrastrando hacia abajo o con `[data-mk-close]`. Con movimiento reducido aparece y desaparece sin animar y la página de detrás no cambia. Funciones sueltas: `sheetOpen`, `sheetClose`, `pushUnderlay`, `releaseUnderlay`.
-
-## Controles y eventos
-
-`open(origen?)`, `close()`, `toggle(origen?)`, `float()`, `dock()`, `isOpen`, `isFloating`, `destroy()`.
-Eventos que burbujean desde el `<dialog>`: `mk:open` (`detail.origin`), `mk:close` (cancelable; `detail.inPlace` tras un arrastre), `mk:closed`.
-Cualquier `[data-mk-part="close"]` o `[data-mk-close]` dentro lo cierra.
-
-## Variables CSS
-
-`--mk-dialog-bg` (surface-2), `--mk-dialog-radius` (40px), `--mk-dialog-width` (400px), `--mk-dialog-padding` (24px), `--mk-dialog-shadow`.
-
-## Accesibilidad
-
-`<dialog>` nativo: foco atrapado, Escape, fondo inerte. El título (`data-mk-part="title"`) nombra el diálogo y la descripción lo describe. El foco va al primer campo al abrir y vuelve al botón al cerrar. Con movimiento reducido abre y cierra sin viaje ni arrastre.
+# dialog
+
+El diálogo sobre `<dialog>` nativo (foco atrapado, Escape, capa superior). El botón que lo abre se convierte en el diálogo y al cerrar vuelve a él.
+
+- **Abrir desde el botón (morph):** la superficie viaja recortada desde el rect del botón en 0.7 s con la curva signature y toma su color en 0.3 s; el contenido crece como grupo desde la caja del botón con blur 8 → 0. El botón se oculta en 80 ms mientras está "dentro".
+- **Elementos compartidos:** `data-mk-shared="titulo"` en una pieza del botón y otra del diálogo: el texto vuela de una a otra (0.7 s al abrir, 0.5 s al cerrar).
+- **Sin botón en pantalla:** escala .92 → 1 en 0.35 s (`power2.out`).
+- **Cerrar:** el diálogo se cierra al instante (el foco vuelve y la página responde) mientras una copia inerte se pliega al botón: forma 0.5 s, contenido con blur → 32 px (`.37,.35,0,1`) y fundido (`.56,.27,0,1`), velo `power3.in`; el botón reaparece 0.3 s tras 0.2 s. Sin botón: escala .9 + blur 32.
+- **Líquido** (`variant="liquid"`): dos blobs bajo filtro goo; posición con resorte 144/14 y patada de 2400 px/s, tamaño 0.3 s `cubic(.8,.3,.5,.8)`, radio 0.7 s, contenido `scale 2 → 1` y blur 8 → 0, color 0.4 s tras 0.15 s. Cierre con resorte 130/18.
+- **Backdrop:** tinte 0.5 s con la curva signature (`linear()`).
+- **Auto-resize:** si el contenido crece o se encoge, la altura se ajusta en 0.45 s (signature).
+- **Arrastrar para cerrar:** sigue al puntero a la mitad y encoge (`1 − y/400`); pasados 100 px se cierra donde quedó, si no vuelve con `elastic.out(.5,.5)` 0.5 s. También con la rueda. Ignora controles, áreas con scroll y `[data-mk-no-drag]`.
+- **Ventana flotante** (`float="clave"`, escritorio ≥ 680 px): el asa la levanta (la página sigue usable), se mueve con resorte 1100/38 e inercia, se queda dentro de la pantalla, se redimensiona por las esquinas (mín. 320 × 240) y recuerda su sitio. Un clic en el asa la devuelve.
+- **Móvil (< 680 px):** pantalla completa, radio 0.
+
+- **Sheet** (`variant="sheet"`): la hoja sube desde abajo (`y 100% → 0`, 0.72 s `cubic-bezier(.16,1,.3,1)`) y lo marcado con `[data-mk-underlay]` se hunde a escala .98 y opacidad .4 con un resorte 300/30. Al cerrar, una copia inerte cae por debajo de la pantalla y el foco vuelve al instante. No sale del botón. Mientras está abierta, la página no hace scroll.
+
+## HTML / Astro
+
+```html
+<button class="mk-button" data-mk-open="crear">Crear proyecto</button>
+
+<mk-dialog id="crear" heading="Crear proyecto" description="Se guarda en tu espacio.">
+  <label class="mk-field"><span class="mk-field__label">Nombre</span><input /></label>
+  <div data-mk-part="footer">
+    <button class="mk-button mk-button--text" data-mk-close>Cancelar</button>
+    <button class="mk-button mk-button--primary">Crear</button>
+  </div>
+</mk-dialog>
+
+<script>
+  import { defineElements } from '@yewdiel21/motion-kit/elements';
+  defineElements(['mk-dialog']);
+</script>
+```
+
+Sin `heading`, tus hijos van dentro tal cual si ya usan partes (`data-mk-part="header|body|footer"`), o dentro de un cuerpo si no. Sobre tu propio `<dialog class="mk-dialog">`: `createDialog(dialog, opciones)`.
+
+## React
+
+```tsx
+<Dialog.Root variant="liquid" onOpenChange={setOpen}>
+  <Dialog.Trigger className="mk-button">Crear</Dialog.Trigger>
+  <Dialog.Content>
+    <Dialog.Header>
+      <div><Dialog.Title>Crear proyecto</Dialog.Title></div>
+      <Dialog.Actions><Dialog.Close /></Dialog.Actions>
+    </Dialog.Header>
+    <Dialog.Body>…</Dialog.Body>
+    <Dialog.Footer>…</Dialog.Footer>
+  </Dialog.Content>
+</Dialog.Root>
+```
+
+Las opciones van en `Dialog.Root` (`variant`, `placement`, `float`…). Controlado con `open` + `onOpenChange`, o libre con `defaultOpen`. `Dialog.Trigger` registra su botón como origen.
+
+## Opciones
+
+| Opción | Atributo | Por defecto | Qué hace |
+|---|---|---|---|
+| `variant` | `variant` | `'morph'` | `'liquid'` para la versión líquida; `'sheet'` para la hoja que sube desde abajo; `'drawer'` desliza desde su lado (`data-mk-drawer`, ver [drawer](../drawer/README.md)) |
+| `placement` | `placement` | `'center'` | `'anchor'` junto al botón, `'side'` panel lateral |
+| `anchor` | — | caja del origen | Con `placement: 'anchor'`, función que devuelve la caja (`DOMRect`) junto a la que se coloca; se lee al abrir y al redimensionar ([context-menu](../context-menu/README.md) la usa para el puntero) |
+| `backdrop` | `no-backdrop` | `true` | Velo tintado |
+| `closeOnBackdrop` | `persistent` | `true` | Clic fuera cierra |
+| `drag` | `no-drag` | `true` | Arrastrar para cerrar |
+| `float` | `float="clave"` | `false` | Ventana flotante (necesita un `[data-mk-part="handle"]`; con `heading` se crea) |
+| `autoResize` | — | `true` | Ajuste suave de altura |
+| `triggers` | (el `id`) | `true` | `[data-mk-open="<id>"]` lo abre |
+| `modal` | — | `true` | Modal o no |
+| `labels` | `close-label` | `{ close: 'Cerrar', float, dock }` | Textos accesibles |
+| `size` | `size` | `md` (400 px) | `sm` 360, `lg` 640, `xl` 960 |
+
+## Sheet
+
+```html
+<main data-mk-underlay>…la página…</main>
+<button class="mk-button" data-mk-open="proyecto">Ver proyecto</button>
+<mk-dialog id="proyecto" variant="sheet" heading="Private Space">…</mk-dialog>
+```
+
+```tsx
+<Dialog.Root variant="sheet">
+  <Dialog.Trigger>Ver proyecto</Dialog.Trigger>
+  <Dialog.Content>…</Dialog.Content>
+</Dialog.Root>
+```
+
+Ancho hasta `--mk-sheet-max-width` (720px), alto hasta `100dvh − 24px`, radio solo arriba; en el móvil ocupa todo el ancho. Se cierra con Escape, con el fondo, arrastrando hacia abajo o con `[data-mk-close]`. Con movimiento reducido aparece y desaparece sin animar y la página de detrás no cambia. Funciones sueltas: `sheetOpen`, `sheetClose`, `pushUnderlay`, `releaseUnderlay`.
+
+## Controles y eventos
+
+`open(origen?)`, `close()`, `toggle(origen?)`, `float()`, `dock()`, `isOpen`, `isFloating`, `destroy()`.
+Eventos que burbujean desde el `<dialog>`: `mk:open` (`detail.origin`), `mk:close` (cancelable; `detail.inPlace` tras un arrastre), `mk:closed`.
+Cualquier `[data-mk-part="close"]` o `[data-mk-close]` dentro lo cierra.
+
+## Variables CSS
+
+`--mk-dialog-bg` (surface-2), `--mk-dialog-radius` (40px), `--mk-dialog-width` (400px), `--mk-dialog-padding` (24px), `--mk-dialog-shadow`.
+
+## Accesibilidad
+
+`<dialog>` nativo: foco atrapado, Escape, fondo inerte. El título (`data-mk-part="title"`) nombra el diálogo y la descripción lo describe. El foco va al primer campo al abrir y vuelve al botón al cerrar. Con movimiento reducido abre y cierra sin viaje ni arrastre.