@yewdiel21/motion-kit 0.10.0 → 0.14.0

package/src/components/questionnaire/engine.ts

@@ -0,0 +1,255 @@
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { createSteps } from '../steps/engine';
+import { shake } from '../../motion/micro';
+
+/*
+ * Questionnaire: a native form split into [data-mk-question] steps, moved by
+ * the steps engine (flow out/in, counter, focus on the title). Next validates
+ * the current step first — required text, choices and checkbox groups (one
+ * checked is enough) — marks invalid fields, writes the message and focuses
+ * the first one. Submitting on the last step completes once; native reset
+ * clears errors and completion and returns to the first step.
+ * Parts: [data-mk-question], [data-mk-question-next|prev], [data-mk-question-error],
+ * [data-mk-question-complete], [data-mk-counter] (step number).
+ */
+
+export type QuestionnaireAnswers = Record<string, string | string[]>;
+
+export interface QuestionnaireLabels {
+  required?: string;
+  choice?: string;
+}
+
+export interface QuestionnaireOptions {
+  index?: number;
+  labels?: QuestionnaireLabels;
+  onChange?: (index: number, answers: QuestionnaireAnswers) => void;
+  onComplete?: (answers: QuestionnaireAnswers) => void;
+}
+
+export interface QuestionnaireInstance extends Instance {
+  /** Validate the current step and go on (or complete on the last one). */
+  next(): Promise<boolean>;
+  prev(): Promise<void>;
+  /** Native form reset: clears answers, errors and completion. */
+  reset(): void;
+  readonly answers: QuestionnaireAnswers;
+  readonly index: number;
+  readonly count: number;
+  readonly complete: boolean;
+}
+
+type Field = HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;
+const FIELDS = 'input[name], select[name], textarea[name]';
+const SKIP = new Set(['button', 'submit', 'reset', 'image', 'file']);
+let sequence = 0;
+
+/** Answers of a form keyed by field name: checkboxes and multi-selects give arrays. */
+export function readAnswers(form: HTMLElement): QuestionnaireAnswers {
+  const answers: QuestionnaireAnswers = {};
+  for (const field of form.querySelectorAll<Field>(FIELDS)) {
+    if (field.disabled || SKIP.has(field.type)) continue;
+    const { name } = field;
+    if (field instanceof HTMLInputElement && field.type === 'checkbox') {
+      const list = (answers[name] as string[] | undefined) ?? [];
+      if (field.checked) list.push(field.value);
+      answers[name] = list;
+    } else if (field instanceof HTMLInputElement && field.type === 'radio') {
+      if (field.checked) answers[name] = field.value;
+      else answers[name] ??= '';
+    } else if (field instanceof HTMLSelectElement && field.multiple) {
+      answers[name] = [...field.selectedOptions].map((option) => option.value);
+    } else answers[name] = field.value;
+  }
+  return answers;
+}
+
+export function createQuestionnaire(root: HTMLElement | null, options: QuestionnaireOptions = {}): QuestionnaireInstance {
+  const form = root instanceof HTMLFormElement ? root : root?.querySelector('form') ?? null;
+  const sections = form ? [...form.querySelectorAll<HTMLElement>('[data-mk-question]')] : [];
+  if (!root || !form || !sections.length) {
+    return inert({ next: async () => false, prev: async () => {}, reset() {}, answers: {}, index: -1, count: 0, complete: false });
+  }
+  const scope = createScope();
+  const labels = { required: 'Completa este campo.', choice: 'Elige al menos una opción.', ...options.labels };
+  for (const section of sections) if (!section.hasAttribute('data-mk-step')) scope.attr(section, 'data-mk-step', '');
+  const start = Math.min(sections.length - 1, Math.max(0, Math.round(options.index ?? 0)));
+  let index = start;
+  let complete = false;
+  // Our own navigation buttons only (not [data-mk-step-*]): steps never skips validation.
+  const steps = createSteps(form, { index: start, animateFirst: false });
+  scope.add(() => steps.destroy());
+  scope.attr(form, 'novalidate', '');
+  scope.attr(form, 'data-mk-questionnaire', '');
+
+  const fieldsOf = (section: HTMLElement) => [...section.querySelectorAll<Field>(FIELDS)].filter((field) => !field.disabled && !SKIP.has(field.type));
+  const errorOf = (section: HTMLElement) => section.querySelector<HTMLElement>('[data-mk-question-error]') ?? form.querySelector<HTMLElement>('[data-mk-question-error]');
+  const errorTexts = new Map<HTMLElement, string | null>();
+  const writeError = (element: HTMLElement | null, text: string) => {
+    if (!element) return;
+    if (!errorTexts.has(element)) errorTexts.set(element, element.textContent);
+    element.textContent = text;
+  };
+  scope.add(() => errorTexts.forEach((text, element) => (element.textContent = text)));
+  for (const element of form.querySelectorAll<HTMLElement>('[data-mk-question-error]')) {
+    if (!element.id) scope.attr(element, 'id', `mk-question-error-${++sequence}`);
+    if (!element.matches('output') && !element.hasAttribute('role')) scope.attr(element, 'role', 'alert');
+  }
+
+  const markValid = (field: Field) => {
+    scope.attr(field, 'aria-invalid', null);
+    scope.attr(field, 'aria-errormessage', null);
+  };
+  const clearErrors = () => {
+    for (const field of form.querySelectorAll<Field>(FIELDS)) markValid(field);
+    for (const element of form.querySelectorAll<HTMLElement>('[data-mk-question-error]')) writeError(element, '');
+  };
+
+  /** Invalid fields of a step and the first message. */
+  const check = (section: HTMLElement) => {
+    const invalid: Field[] = [];
+    let message = '';
+    const groups = new Map<string, HTMLInputElement[]>();
+    for (const field of fieldsOf(section)) {
+      if (field instanceof HTMLInputElement && (field.type === 'checkbox' || field.type === 'radio')) {
+        const group = groups.get(field.name) ?? [];
+        group.push(field);
+        groups.set(field.name, group);
+        continue;
+      }
+      const empty = field.required && !field.value.trim();
+      if (empty || !field.checkValidity()) {
+        invalid.push(field);
+        message ||= empty ? labels.required : field.validationMessage || labels.required;
+      }
+    }
+    for (const group of groups.values()) {
+      const required = group.some((field) => field.required) || Boolean(group[0]!.closest('[data-mk-required]'));
+      if (required && !group.some((field) => field.checked)) {
+        invalid.push(...group);
+        message ||= labels.choice;
+      }
+    }
+    return { invalid, message };
+  };
+
+  const validate = (section: HTMLElement) => {
+    clearErrors();
+    const { invalid, message } = check(section);
+    if (!invalid.length) return true;
+    const error = errorOf(section);
+    writeError(error, message);
+    for (const field of invalid) {
+      scope.attr(field, 'aria-invalid', 'true');
+      if (error?.id) scope.attr(field, 'aria-errormessage', error.id);
+    }
+    invalid[0]!.focus();
+    shake(invalid[0]!.closest('[data-mk-question-options], [data-mk-question-field]') ?? invalid[0]!);
+    root.dispatchEvent(new CustomEvent('mk:invalid', { bubbles: true, detail: { index, fields: invalid } }));
+    return false;
+  };
+
+  const render = () => {
+    scope.attr(form, 'data-mk-complete', complete ? '' : null);
+    form.style.setProperty('--mk-question-progress', String(complete ? 1 : (index + 1) / sections.length));
+    for (const panel of form.querySelectorAll<HTMLElement>('[data-mk-question-complete]')) scope.attr(panel, 'hidden', complete ? null : '');
+  };
+  scope.attr(form, 'style', form.getAttribute('style'));
+
+  const finish = () => {
+    if (complete) return;
+    complete = true;
+    render();
+    const answers = readAnswers(form);
+    const panel = form.querySelector<HTMLElement>('[data-mk-question-complete]');
+    if (panel) {
+      if (!panel.hasAttribute('tabindex')) scope.attr(panel, 'tabindex', '-1');
+      panel.focus({ preventScroll: true });
+    }
+    options.onComplete?.(answers);
+    root.dispatchEvent(new CustomEvent('mk:complete', { bubbles: true, detail: { answers } }));
+  };
+
+  const go = async (to: number) => {
+    const previous = index;
+    index = to;
+    render();
+    await steps.goTo(to);
+    if (scope.disposed) return;
+    const answers = readAnswers(form);
+    options.onChange?.(index, answers);
+    root.dispatchEvent(new CustomEvent('mk:question', { bubbles: true, detail: { index, previous, answers } }));
+  };
+
+  // Everything before the first await runs at once: a submit completes synchronously.
+  const next = async () => {
+    if (scope.disposed) return false;
+    if (complete) return true;
+    if (!validate(sections[index]!)) return false;
+    if (index === sections.length - 1) {
+      finish();
+      return true;
+    }
+    await go(index + 1);
+    return !scope.disposed;
+  };
+  const prev = async () => {
+    if (scope.disposed || complete || index === 0) return;
+    clearErrors();
+    await go(index - 1);
+  };
+
+  scope.on(form, 'click', (event) => {
+    const trigger = (event.target as Element | null)?.closest<HTMLElement>('[data-mk-question-next], [data-mk-question-prev]');
+    if (!trigger || !form.contains(trigger)) return;
+    event.preventDefault();
+    if (trigger.hasAttribute('data-mk-question-next')) void next();
+    else void prev();
+  });
+  scope.on(form, 'submit', (event) => {
+    event.preventDefault();
+    void next();
+  });
+  // A corrected field stops being invalid as soon as it is.
+  const recheck = (event: Event) => {
+    const field = (event.target as Element | null)?.closest<Field>(FIELDS);
+    if (!field || field.getAttribute('aria-invalid') !== 'true') return;
+    const section = field.closest<HTMLElement>('[data-mk-question]');
+    if (!section) return;
+    const { invalid } = check(section);
+    for (const candidate of fieldsOf(section)) if (!invalid.includes(candidate)) markValid(candidate);
+    if (!invalid.length) writeError(errorOf(section), '');
+  };
+  scope.on(form, 'input', recheck);
+  scope.on(form, 'change', recheck);
+  scope.on(form, 'reset', (event) => {
+    if (event.defaultPrevented) return;
+    clearErrors();
+    complete = false;
+    if (index !== 0) void go(0);
+    else render();
+  });
+  render();
+
+  return {
+    next,
+    prev,
+    reset() {
+      if (!scope.disposed) form.reset();
+    },
+    get answers() {
+      return readAnswers(form);
+    },
+    get index() {
+      return index;
+    },
+    get count() {
+      return sections.length;
+    },
+    get complete() {
+      return complete;
+    },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/questionnaire/questionnaire.css

@@ -0,0 +1,216 @@
+/* questionnaire — one question at a time on a soft card: a thin progress line, large title, pill choices. */
+.mk-questionnaire,
+mk-questionnaire > form {
+  --mk-question-radius: var(--mk-radius-lg, 24px);
+  --mk-question-option-radius: var(--mk-radius-md, 16px);
+  display: grid;
+  gap: 1.25rem;
+  padding: clamp(1.25rem, 4vw, 2rem);
+  border-radius: var(--mk-question-radius);
+  background: var(--mk-surface-1);
+  box-shadow: inset 0 0 0 1px var(--mk-outline-soft);
+  color: var(--mk-text);
+  font-family: var(--mk-font);
+}
+
+mk-questionnaire {
+  display: block;
+}
+
+:is(.mk-questionnaire, mk-questionnaire) [data-mk-question-progress] {
+  height: 4px;
+  overflow: hidden;
+  border-radius: var(--mk-radius-full);
+  background: color-mix(in srgb, var(--mk-text) 9%, transparent);
+}
+
+:is(.mk-questionnaire, mk-questionnaire) [data-mk-question-bar] {
+  display: block;
+  height: 100%;
+  border-radius: inherit;
+  background: var(--mk-accent);
+  transform: scaleX(var(--mk-question-progress, 0));
+  transform-origin: left center;
+  transition: transform 0.7s cubic-bezier(0.38, 0.49, 0, 1);
+}
+
+/* A full-width column (steps' own flex centring does not apply here). */
+:is(.mk-questionnaire, mk-questionnaire) [data-mk-question] {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr);
+  gap: 1rem;
+  align-content: start;
+  justify-content: normal;
+  justify-items: stretch;
+}
+
+:is(.mk-questionnaire, mk-questionnaire) [data-mk-question][hidden],
+:is(.mk-questionnaire, mk-questionnaire)[data-mk-complete] [data-mk-question],
+:is(.mk-questionnaire, mk-questionnaire) [data-mk-question-complete][hidden] {
+  display: none !important;
+}
+
+:is(.mk-questionnaire, mk-questionnaire) [data-mk-question-step] {
+  margin: 0;
+  color: var(--mk-muted);
+  font-size: 0.8125rem;
+  letter-spacing: 0.02em;
+}
+
+:is(.mk-questionnaire, mk-questionnaire) [data-mk-question] h3 {
+  margin: 0;
+  font-size: clamp(1.35rem, 3vw, 1.75rem);
+  font-weight: 500;
+  line-height: 1.15;
+  letter-spacing: -0.02em;
+}
+
+:is(.mk-questionnaire, mk-questionnaire) [data-mk-question] h3:focus {
+  outline: none;
+}
+
+:is(.mk-questionnaire, mk-questionnaire) [data-mk-question-required] {
+  color: var(--mk-accent);
+}
+
+:is(.mk-questionnaire, mk-questionnaire) [data-mk-question-description] {
+  margin: -0.5rem 0 0;
+  color: var(--mk-muted);
+}
+
+:is(.mk-questionnaire, mk-questionnaire) :is(input[type='text'], input[type='email'], input[type='number'], textarea, select) {
+  width: 100%;
+  min-height: 3.25rem;
+  padding: 0.75rem 1.1rem;
+  border: 1px solid var(--mk-outline-soft);
+  border-radius: var(--mk-question-option-radius);
+  background: var(--mk-surface-3);
+  color: var(--mk-text);
+  font: inherit;
+  transition:
+    border-color 0.2s ease,
+    background-color 0.2s ease;
+}
+
+:is(.mk-questionnaire, mk-questionnaire) textarea {
+  resize: vertical;
+}
+
+:is(.mk-questionnaire, mk-questionnaire) :is(input, textarea, select):focus-visible {
+  border-color: var(--mk-accent);
+  outline: 2px solid color-mix(in srgb, var(--mk-accent) 35%, transparent);
+  outline-offset: 1px;
+}
+
+:is(.mk-questionnaire, mk-questionnaire) [data-mk-question-options] {
+  display: grid;
+  gap: 0.5rem;
+}
+
+/* Melonmind label.style-1: padding and radius spring; a chosen option becomes a pill. */
+:is(.mk-questionnaire, mk-questionnaire) [data-mk-question-option] {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  min-height: 3.25rem;
+  padding: 0.5rem 1.1rem;
+  border-radius: 16px;
+  background: var(--mk-surface-3);
+  cursor: pointer;
+  user-select: none;
+  transition:
+    padding 300ms cubic-bezier(0.38, 0.49, 0, 2),
+    background-color 300ms cubic-bezier(0.38, 0.49, 0, 1.5),
+    color 300ms cubic-bezier(0.38, 0.49, 0, 1.5),
+    border-radius 200ms cubic-bezier(0.38, 0.49, 0, 1.5);
+}
+
+:is(.mk-questionnaire, mk-questionnaire) [data-mk-question-option]:hover {
+  padding-inline: 1.3rem;
+  background: var(--mk-surface-4);
+}
+
+:is(.mk-questionnaire, mk-questionnaire) [data-mk-question-option]:active {
+  animation: mk-question-press 500ms cubic-bezier(0.37, 1.42, 0.37, 1);
+}
+
+:is(.mk-questionnaire, mk-questionnaire) [data-mk-question-option]:has(input:checked) {
+  padding-inline: 1.5rem;
+  border-radius: 64px;
+  background: var(--mk-accent-soft);
+  color: var(--mk-on-accent-soft);
+}
+
+@keyframes mk-question-press {
+  50% {
+    transform: scale(0.98, 0.94);
+  }
+}
+
+:is(.mk-questionnaire, mk-questionnaire) [data-mk-question-option]:has(input:focus-visible) {
+  outline: 2px solid var(--mk-accent);
+  outline-offset: 2px;
+}
+
+:is(.mk-questionnaire, mk-questionnaire) [data-mk-question-option] input {
+  width: 1.15rem;
+  height: 1.15rem;
+  margin: 0;
+  accent-color: var(--mk-accent);
+}
+
+:is(.mk-questionnaire, mk-questionnaire) [aria-invalid='true']:not([type='checkbox'], [type='radio']) {
+  border-color: var(--mk-error);
+}
+
+:is(.mk-questionnaire, mk-questionnaire) [data-mk-question-option]:has([aria-invalid='true']) {
+  border-color: color-mix(in srgb, var(--mk-error) 60%, transparent);
+}
+
+:is(.mk-questionnaire, mk-questionnaire) [data-mk-question-actions] {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: flex-end;
+  gap: 0.5rem;
+  margin-top: 0.25rem;
+}
+
+:is(.mk-questionnaire, mk-questionnaire) [data-mk-question-error] {
+  margin: 0;
+  color: var(--mk-error);
+  font-size: 0.875rem;
+}
+
+:is(.mk-questionnaire, mk-questionnaire) [data-mk-question-error]:empty {
+  display: none;
+}
+
+:is(.mk-questionnaire, mk-questionnaire) [data-mk-question-complete] {
+  display: grid;
+  gap: 1rem;
+  justify-items: start;
+  animation: mk-question-done 0.45s var(--mk-ease-sheet, ease-out) both;
+}
+
+:is(.mk-questionnaire, mk-questionnaire) [data-mk-question-complete]:focus {
+  outline: none;
+}
+
+@keyframes mk-question-done {
+  from {
+    opacity: 0;
+    transform: translateY(8px);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :is(.mk-questionnaire, mk-questionnaire) :is([data-mk-question-bar], [data-mk-question-option], [data-mk-question-complete]) {
+    transition: none;
+    animation: none;
+    transform: none;
+  }
+
+  :is(.mk-questionnaire, mk-questionnaire) [data-mk-question-bar] {
+    transform: scaleX(var(--mk-question-progress, 0));
+  }
+}

package/src/components/questionnaire/react.tsx

@@ -0,0 +1,140 @@
+'use client';
+import { useRef, useState, type FormHTMLAttributes, type ReactNode } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createQuestionnaire, type QuestionnaireAnswers, type QuestionnaireInstance, type QuestionnaireLabels } from './engine';
+
+export type QuestionType = 'text' | 'textarea' | 'single' | 'multiple';
+
+export interface QuestionOption {
+  value: string;
+  label: string;
+}
+
+export interface Question {
+  /** Field name and answer key. */
+  id: string;
+  label: string;
+  type: QuestionType;
+  options?: Array<string | QuestionOption>;
+  required?: boolean;
+  description?: string;
+  placeholder?: string;
+}
+
+export interface QuestionnaireProps extends Omit<FormHTMLAttributes<HTMLFormElement>, 'onChange' | 'children'> {
+  questions: Question[];
+  /** Answers the fields start with. */
+  defaultAnswers?: QuestionnaireAnswers;
+  labels?: QuestionnaireLabels & { next?: string; prev?: string; finish?: string; restart?: string; step?: (index: number, count: number) => ReactNode };
+  onChange?: (index: number, answers: QuestionnaireAnswers) => void;
+  onComplete?: (answers: QuestionnaireAnswers) => void;
+  /** Shown after the last step; a function receives the answers. */
+  complete?: ReactNode | ((answers: QuestionnaireAnswers) => ReactNode);
+  instanceRef?: { current: QuestionnaireInstance | null };
+}
+
+const optionOf = (option: string | QuestionOption): QuestionOption => (typeof option === 'string' ? { value: option, label: option } : option);
+
+/**
+ * <Questionnaire questions={[{ id: 'name', label: 'Nombre', type: 'text', required: true }, …]} onComplete={save} />.
+ * Fields are native and uncontrolled, so answers survive steps and rerenders; the app owns persistence.
+ */
+export function Questionnaire({ questions, defaultAnswers = {}, labels = {}, onChange, onComplete, complete, instanceRef, className, ...props }: QuestionnaireProps) {
+  const ref = useRef<HTMLFormElement>(null);
+  const [answers, setAnswers] = useState<QuestionnaireAnswers | null>(null);
+  const change = useLatest(onChange);
+  const completed = useLatest(onComplete);
+  const key = JSON.stringify(questions.map(({ id, type, required, options }) => [id, type, required, options]));
+  const { required, choice } = labels;
+  useIsomorphicLayoutEffect(() => {
+    const created = createQuestionnaire(ref.current, {
+      labels: { required, choice },
+      onChange: (index, current) => change.current?.(index, current),
+      onComplete: (current) => {
+        setAnswers(current);
+        completed.current?.(current);
+      },
+    });
+    if (instanceRef) instanceRef.current = created;
+    return () => {
+      created.destroy();
+      if (instanceRef) instanceRef.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key, required, choice]);
+  const count = questions.length;
+  const defaults = (id: string) => defaultAnswers[id];
+  return (
+    <form {...props} ref={ref} noValidate className={['mk-questionnaire', className].filter(Boolean).join(' ')} onReset={() => setAnswers(null)}>
+      <div data-mk-question-progress="" aria-hidden="true">
+        <span data-mk-question-bar="" />
+      </div>
+      {questions.map((question, i) => {
+        const titleId = `${question.id}-title`;
+        const describedBy = question.description ? `${question.id}-description` : undefined;
+        const value = defaults(question.id);
+        return (
+          <section key={question.id} data-mk-question="" data-mk-step="" hidden={i !== 0} aria-labelledby={titleId}>
+            <p data-mk-question-step="">{labels.step ? labels.step(i, count) : `Pregunta ${i + 1} de ${count}`}</p>
+            <h3 id={titleId} data-mk-step-title="" data-mk-flow-item="">
+              {question.label}
+              {question.required ? <span data-mk-question-required="" aria-hidden="true"> *</span> : null}
+            </h3>
+            {question.description && (
+              <p id={describedBy} data-mk-question-description="" data-mk-flow-item="">
+                {question.description}
+              </p>
+            )}
+            <div data-mk-question-field="" data-mk-flow-item="">
+              {question.type === 'text' && (
+                <input name={question.id} type="text" required={question.required} aria-labelledby={titleId} aria-describedby={describedBy} placeholder={question.placeholder} defaultValue={typeof value === 'string' ? value : ''} />
+              )}
+              {question.type === 'textarea' && (
+                <textarea name={question.id} rows={4} required={question.required} aria-labelledby={titleId} aria-describedby={describedBy} placeholder={question.placeholder} defaultValue={typeof value === 'string' ? value : ''} />
+              )}
+              {(question.type === 'single' || question.type === 'multiple') && (
+                <div role={question.type === 'single' ? 'radiogroup' : 'group'} aria-labelledby={titleId} aria-describedby={describedBy} data-mk-question-options="">
+                  {(question.options ?? []).map(optionOf).map((option) => (
+                    <label key={option.value} data-mk-question-option="">
+                      <input
+                        type={question.type === 'single' ? 'radio' : 'checkbox'}
+                        name={question.id}
+                        value={option.value}
+                        required={question.required}
+                        defaultChecked={Array.isArray(value) ? value.includes(option.value) : value === option.value}
+                      />
+                      <span>{option.label}</span>
+                    </label>
+                  ))}
+                </div>
+              )}
+            </div>
+            <div data-mk-question-actions="" data-mk-flow-item="">
+              {i > 0 && (
+                <button type="button" className="mk-button mk-button--text" data-mk-question-prev="">
+                  {labels.prev ?? 'Anterior'}
+                </button>
+              )}
+              {i < count - 1 ? (
+                <button type="button" className="mk-button" data-mk-question-next="">
+                  {labels.next ?? 'Siguiente'}
+                </button>
+              ) : (
+                <button type="submit" className="mk-button">
+                  {labels.finish ?? 'Finalizar'}
+                </button>
+              )}
+            </div>
+          </section>
+        );
+      })}
+      <p data-mk-question-error="" role="alert" />
+      <div data-mk-question-complete="" hidden>
+        {answers && (typeof complete === 'function' ? complete(answers) : complete)}
+        <button type="reset" className="mk-button mk-button--tonal">
+          {labels.restart ?? 'Empezar de nuevo'}
+        </button>
+      </div>
+    </form>
+  );
+}

package/src/components/range-calendar/README.md

@@ -0,0 +1,58 @@
+# range-calendar
+
+Calendario para elegir un rango de fechas en dos clics, de uno o dos meses. El primer clic (o Enter) fija el inicio, que rebota; mientras eliges el final, al señalar se ve una banda más clara con borde discontinuo; el segundo clic cierra el rango (en cualquier dirección) y su banda se dibuja desde el inicio hasta el final (curva wipe, 12 ms entre días, 0,35 s como mucho); el día final rebota. Los días que no se pueden elegir (`min`, `max`, `unavailable`) aparecen tachados y un rango no puede cruzarlos: si lo intentas, el día pulsado pasa a ser el nuevo inicio. Al cambiar de mes, la cuadrícula se desliza como en `calendar`.
+
+## HTML / Astro
+
+```html
+<mk-range-calendar class="mk-range-calendar" visible-months="2" min="2026-11-10"
+  unavailable="2026-12-24,2026-12-25"></mk-range-calendar>
+<mk-range-calendar class="mk-range-calendar" start="2026-11-23" end="2026-11-26"></mk-range-calendar>
+```
+
+## React
+
+```tsx
+const [range, setRange] = useState<{ start: Date; end: Date } | null>(null);
+<RangeCalendar value={range} onChange={setRange} visibleMonths={2} unavailable={(day) => day.getDay() === 0} />
+```
+
+## Opciones
+
+| Opción | Atributo | Por defecto | Qué hace |
+|---|---|---|---|
+| `value` | `start`, `end` | — | Rango `{start, end}` (Date o `'AAAA-MM-DD'`). |
+| `month` | `month` | inicio del rango, o hoy | Primer mes visible. |
+| `visibleMonths` | `visible-months` | `1` | `1` o `2` meses. |
+| `firstDay` | `first-day` | `1` (lunes) | Primer día de la semana (0 = domingo). |
+| `min`, `max` | `min`, `max` | — | Límites. |
+| `unavailable` | `unavailable` (lista con comas) | — | Días `'AAAA-MM-DD'` o una función `(día) => boolean`. |
+| `locale` | `locale` | `lang` de la página, o `es` | Nombres de meses y días. |
+| `today` | `today` | hoy | Para demos y pruebas. |
+| `labels` | — | Mes anterior / Mes siguiente | Nombres de los botones. |
+| `selection` | — | `'range'` | `'single'`: un clic elige un solo día (lo usa `date-time-picker`). |
+| `onChange(range)` | — | — | Rango cerrado `{start, end}` (Date). |
+
+## Teclado
+
+| Tecla | Acción |
+|---|---|
+| ← / → | Día anterior / siguiente |
+| ↑ / ↓ | Semana anterior / siguiente |
+| Inicio / Fin | Principio / final de la semana |
+| RePág / AvPág | Mes anterior / siguiente (con Mayús: año) |
+| Enter / Espacio | El primer día fija el inicio; el segundo cierra el rango |
+
+Solo un día es tabulable (tabindex itinerante); al salir de los meses visibles con el teclado, el calendario cambia de mes.
+
+## API y eventos
+
+`setValue(range | null, animate = true)`, `next()`, `prev()`, `focusDay(día, animate = true)` (con `animate=false` cambia de mes sin deslizar), `value`, `month`, `destroy()`. `bandDuration(días)` dice cuántos segundos tarda en asentarse un rango (banda y rebote del día final). Evento `mk:change` con `{ start: 'AAAA-MM-DD', end: 'AAAA-MM-DD', length }` (días incluidos).
+
+## Estado de los días
+
+Atributos en cada botón de día: `data-mk-today`, `data-mk-anchor`, `data-mk-in-range`, `data-mk-range-start`, `data-mk-range-end`, `data-mk-preview` (y `-start`/`-end`), `aria-disabled="true"`. La celda (`role="gridcell"`) lleva `aria-selected="true"` en los días del rango.
+
+## Variables CSS
+
+`--mk-range-day` (2.5rem; 2.25rem bajo 380 px), `--mk-range-band` (`--mk-accent-soft`). Esquinas exteriores de 20 px, botones de 8 px. Con movimiento reducido no hay deslizamiento, banda animada ni rebotes.