@yewdiel21/motion-kit 0.10.0 → 0.14.0

package/src/components/progress/engine.ts

@@ -0,0 +1,173 @@
+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 { burst, rollDigits } from '../../motion/micro';
+
+/*
+ * Progress: a bar or a ring (Melon Mind's MetricsRing: radius (size - stroke) / 2,
+ * dasharray from the ratio, starting at 12 o'clock). The root is the progressbar;
+ * the drawing is one decorative [data-mk-progress-visual] child. ARIA follows a
+ * new value at once; the drawing glides to it with GSAP (Melonmind's playful
+ * swing, .38,.49,0,1.5): going up, a light runs at the head and the figure rolls
+ * up; going down, the figure rolls down. Reaching the maximum fires a small burst.
+ * null is indeterminate. Nothing is live: assistive tech reads the value on arrival.
+ */
+
+export type ProgressVariant = 'linear' | 'ring';
+
+export interface ProgressOptions {
+  /** Current value; null is indeterminate. Default: min. */
+  value?: number | null;
+  min?: number;
+  max?: number;
+  label?: string;
+  variant?: ProgressVariant;
+  /** Write the percentage beside the bar (inside the ring). */
+  showValue?: boolean;
+  /** Text for the value (also aria-valuetext). Default: rounded percentage. */
+  formatValue?: (value: number, ratio: number) => string;
+  /** Glide duration in seconds (default .7). */
+  duration?: number;
+}
+
+export interface ProgressInstance extends Instance {
+  setValue(value: number | null): void;
+  readonly value: number | null;
+}
+
+const SVG = 'http://www.w3.org/2000/svg';
+const RING_SIZE = 48;
+const RING_STROKE = 5;
+const RADIUS = (RING_SIZE - RING_STROKE) / 2;
+const CIRCUMFERENCE = 2 * Math.PI * RADIUS;
+
+const finite = (value: unknown): value is number => typeof value === 'number' && Number.isFinite(value);
+
+export function createProgress(root: HTMLElement | null, options: ProgressOptions = {}): ProgressInstance {
+  if (!root) return inert({ setValue() {}, value: null });
+  registerMotion();
+  const scope = createScope();
+  const min = finite(options.min) ? options.min : 0;
+  const max = finite(options.max) && options.max > min ? options.max : Math.max(min + 1, 100);
+  const variant: ProgressVariant = options.variant === 'ring' ? 'ring' : 'linear';
+  const duration = finite(options.duration) ? Math.max(0, options.duration) : 0.7;
+  const clamp = (n: number) => Math.min(max, Math.max(min, n));
+  let value: number | null = options.value === null ? null : clamp(finite(options.value) ? options.value : min);
+
+  const visual = document.createElement('span');
+  visual.dataset.mkProgressVisual = '';
+  visual.setAttribute('aria-hidden', 'true');
+  let arc: SVGCircleElement | null = null;
+  let head: HTMLElement | null = null;
+  let ring: SVGSVGElement | null = null;
+  if (variant === 'ring') {
+    ring = document.createElementNS(SVG, 'svg');
+    ring.setAttribute('viewBox', `0 0 ${RING_SIZE} ${RING_SIZE}`);
+    ring.dataset.mkPart = 'ring';
+    const circle = (part: string) => {
+      const element = document.createElementNS(SVG, 'circle');
+      element.setAttribute('cx', String(RING_SIZE / 2));
+      element.setAttribute('cy', String(RING_SIZE / 2));
+      element.setAttribute('r', String(RADIUS));
+      element.setAttribute('fill', 'none');
+      element.setAttribute('stroke-width', String(RING_STROKE));
+      element.dataset.mkPart = part;
+      ring!.append(element);
+      return element;
+    };
+    circle('track');
+    arc = circle('arc');
+    arc.setAttribute('stroke-linecap', 'round');
+    visual.append(ring);
+  } else {
+    const track = document.createElement('span');
+    track.dataset.mkPart = 'track';
+    const bar = document.createElement('span');
+    bar.dataset.mkPart = 'bar';
+    head = document.createElement('span');
+    head.dataset.mkPart = 'head';
+    track.append(bar, head);
+    visual.append(track);
+  }
+  const text = options.showValue ? document.createElement('span') : null;
+  if (text) {
+    text.dataset.mkPart = 'value';
+    visual.append(text);
+  }
+  root.append(visual);
+
+  scope.attr(root, 'style', root.getAttribute('style'));
+  scope.attr(root, 'role', 'progressbar');
+  scope.attr(root, 'aria-valuemin', String(min));
+  scope.attr(root, 'aria-valuemax', String(max));
+  if (options.label) scope.attr(root, 'aria-label', options.label);
+  scope.attr(root, 'data-mk-variant', variant);
+  scope.attr(root, 'data-mk-ready', '');
+
+  const ratioOf = (n: number | null) => (n === null ? 0 : (n - min) / (max - min));
+  const labelOf = (n: number | null) => (n === null ? '' : options.formatValue ? options.formatValue(n, ratioOf(n)) : `${Math.round(ratioOf(n) * 100)} %`);
+  /** What is drawn now (it trails `value` while gliding). */
+  const shown = { ratio: ratioOf(value) };
+  const draw = () => {
+    const ratio = Math.min(1, Math.max(0, shown.ratio));
+    root.style.setProperty('--mk-progress', ratio.toFixed(4));
+    if (arc) {
+      const length = value === null ? CIRCUMFERENCE * 0.25 : CIRCUMFERENCE * ratio;
+      arc.setAttribute('stroke-dasharray', `${length.toFixed(2)} ${CIRCUMFERENCE.toFixed(2)}`);
+    }
+  };
+  let glide: gsap.core.Tween | null = null;
+  const motion: gsap.core.Animation[] = [];
+  scope.add(() => {
+    glide?.kill();
+    for (const animation of motion.splice(0)) animation.progress(1).kill();
+    visual.remove();
+  });
+
+  const render = (previous: number | null, animate: boolean) => {
+    const label = labelOf(value);
+    scope.attr(root, 'aria-valuenow', value === null ? null : String(value));
+    scope.attr(root, 'aria-valuetext', value !== null && options.formatValue ? label : null);
+    scope.attr(root, 'data-mk-indeterminate', value === null ? '' : null);
+    scope.attr(root, 'data-mk-complete', value !== null && value >= max ? '' : null);
+    const target = ratioOf(value);
+    const direction: 1 | -1 = previous === null || value === null || value >= previous ? 1 : -1;
+    glide?.kill();
+    if (!animate || reduced() || value === null || previous === null || duration === 0) {
+      shown.ratio = target;
+      draw();
+      if (text) text.textContent = label;
+      return;
+    }
+    glide = gsap.to(shown, { ratio: target, duration, ease: EASE.swatch, onUpdate: draw });
+    if (text) {
+      const roll = rollDigits(text, label, direction);
+      if (roll) motion.push(roll);
+    }
+    // Going up: a light runs at the head of the bar; the ring breathes.
+    if (direction > 0 && head) motion.push(gsap.fromTo(head, { opacity: 1, scale: 0.4 }, { opacity: 0, scale: 1.6, duration: 0.6, ease: 'power2.out' }));
+    if (ring) motion.push(gsap.fromTo(ring, { scale: direction > 0 ? 1.06 : 0.95 }, { scale: 1, duration: 0.5, ease: EASE.click, clearProps: 'scale,transform' }));
+    if (value >= max && previous < max) {
+      const done = burst(variant === 'ring' ? visual : (text ?? visual), { count: 6, distance: 22, ring: variant === 'ring' });
+      if (done) motion.push(done);
+    }
+    if (motion.length > 12) motion.splice(0, motion.length - 12);
+  };
+  render(null, false);
+
+  return {
+    setValue(next) {
+      if (scope.disposed) return;
+      const previous = value;
+      if (next === null) value = null;
+      else if (finite(next)) value = clamp(next);
+      else return;
+      render(previous, true);
+    },
+    get value() {
+      return value;
+    },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/progress/progress.css

@@ -0,0 +1,139 @@
+/* progress — Melonmind line: a neutral track, the accent only for the value; a ring (MetricsRing) with the figure inside.
+   The fill is drawn from --mk-progress, which the engine glides with GSAP. */
+.mk-progress,
+mk-progress {
+  --mk-progress-height: 10px;
+  --mk-progress-size: 4.5rem;
+  --mk-progress-track: var(--mk-surface-4);
+  --mk-progress-fill: var(--mk-accent);
+  display: block;
+  color: var(--mk-text);
+  font-family: var(--mk-font);
+}
+
+:is(.mk-progress, mk-progress) [data-mk-progress-visual] {
+  display: flex;
+  align-items: center;
+  gap: 0.875rem;
+}
+
+/* Linear */
+:is(.mk-progress, mk-progress) span[data-mk-part='track'] {
+  position: relative;
+  flex: 1;
+  height: var(--mk-progress-height);
+  border-radius: var(--mk-radius-full);
+  background: var(--mk-progress-track);
+}
+
+:is(.mk-progress, mk-progress) [data-mk-part='bar'] {
+  position: absolute;
+  inset: 0;
+  border-radius: inherit;
+  background: var(--mk-progress-fill);
+  clip-path: inset(0 calc((1 - var(--mk-progress, 0)) * 100%) 0 0 round var(--mk-radius-full));
+}
+
+/* The light at the head of the bar (flashes when the value goes up). */
+:is(.mk-progress, mk-progress) [data-mk-part='head'] {
+  position: absolute;
+  top: 50%;
+  left: calc(var(--mk-progress, 0) * 100%);
+  width: calc(var(--mk-progress-height) * 2.4);
+  aspect-ratio: 1;
+  border-radius: 50%;
+  background: radial-gradient(circle, color-mix(in srgb, var(--mk-progress-fill) 70%, white) 0%, transparent 70%);
+  opacity: 0;
+  pointer-events: none;
+  translate: -50% -50%;
+}
+
+:is(.mk-progress, mk-progress)[data-mk-indeterminate] [data-mk-part='bar'] {
+  clip-path: none;
+  width: 38%;
+  animation: mk-progress-slide 1.4s cubic-bezier(0.65, 0, 0.35, 1) infinite;
+}
+
+:is(.mk-progress, mk-progress) [data-mk-part='value'] {
+  min-width: 4.5ch;
+  color: var(--mk-muted);
+  font-size: 0.875rem;
+  font-weight: 500;
+  font-variant-numeric: tabular-nums;
+  text-align: right;
+}
+
+:is(.mk-progress, mk-progress)[data-mk-complete] [data-mk-part='value'] {
+  color: var(--mk-text);
+}
+
+/* Ring */
+:is(.mk-progress, mk-progress)[data-mk-variant='ring'] {
+  display: inline-block;
+  width: var(--mk-progress-size);
+}
+
+:is(.mk-progress, mk-progress)[data-mk-variant='ring'] [data-mk-progress-visual] {
+  position: relative;
+  display: grid;
+  place-items: center;
+  aspect-ratio: 1;
+}
+
+:is(.mk-progress, mk-progress) [data-mk-part='ring'] {
+  grid-area: 1 / 1;
+  width: 100%;
+  height: 100%;
+  overflow: visible;
+  rotate: -90deg;
+}
+
+:is(.mk-progress, mk-progress) circle[data-mk-part='track'] {
+  stroke: var(--mk-progress-track);
+}
+
+:is(.mk-progress, mk-progress) [data-mk-part='arc'] {
+  stroke: var(--mk-progress-fill);
+}
+
+:is(.mk-progress, mk-progress)[data-mk-variant='ring'][data-mk-indeterminate] [data-mk-part='ring'] {
+  animation: mk-progress-spin 1.1s linear infinite;
+}
+
+:is(.mk-progress, mk-progress)[data-mk-variant='ring'] [data-mk-part='value'] {
+  grid-area: 1 / 1;
+  min-width: 0;
+  color: var(--mk-text);
+  font-size: calc(var(--mk-progress-size) * 0.24);
+  letter-spacing: -0.02em;
+  text-align: center;
+}
+
+@keyframes mk-progress-slide {
+  from {
+    translate: -100% 0;
+  }
+  to {
+    translate: 265% 0;
+  }
+}
+
+@keyframes mk-progress-spin {
+  from {
+    rotate: -90deg;
+  }
+  to {
+    rotate: 270deg;
+  }
+}
+
+/* Reduced motion: values jump; indeterminate becomes a still, partial fill. */
+@media (prefers-reduced-motion: reduce) {
+  :is(.mk-progress, mk-progress) :is([data-mk-part='bar'], [data-mk-part='ring']) {
+    animation: none !important;
+  }
+
+  :is(.mk-progress, mk-progress)[data-mk-indeterminate] [data-mk-part='bar'] {
+    opacity: 0.55;
+  }
+}

package/src/components/progress/react.tsx

@@ -0,0 +1,35 @@
+'use client';
+import { useRef, type HTMLAttributes } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createProgress, type ProgressInstance, type ProgressOptions } from './engine';
+
+export interface ProgressProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'>, ProgressOptions {}
+
+/** <Progress value={42} label="Subida" showValue />; value={null} is indeterminate. The engine owns the drawing and ARIA. */
+export function Progress({ value, min, max, label, variant, showValue, formatValue, className, ...props }: ProgressProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const instance = useRef<ProgressInstance | null>(null);
+  const current = useLatest(value);
+  const format = useLatest(formatValue);
+  const formatted = formatValue !== undefined;
+  useIsomorphicLayoutEffect(() => {
+    const created = createProgress(ref.current, {
+      value: current.current,
+      min,
+      max,
+      label,
+      variant,
+      showValue,
+      formatValue: formatted ? (n, ratio) => format.current?.(n, ratio) ?? '' : undefined,
+    });
+    instance.current = created;
+    return () => {
+      created.destroy();
+      instance.current = null;
+    };
+  }, [min, max, label, variant, showValue, formatted]);
+  useIsomorphicLayoutEffect(() => {
+    instance.current?.setValue(value === undefined ? (min ?? 0) : value);
+  }, [value]);
+  return <div {...props} ref={ref} className={['mk-progress', className].filter(Boolean).join(' ')} />;
+}

package/src/components/questionnaire/README.md

@@ -0,0 +1,32 @@
+# questionnaire
+
+Preguntas por pasos sobre un formulario nativo: texto, respuesta única y múltiple, anterior/siguiente, progreso, validación de obligatorios y finalización. Compone el motor de [steps](../steps/README.md) (entrada/salida en flujo, contador y foco en el título); la persistencia es de la app.
+
+```html
+<mk-questionnaire>
+  <form class="mk-questionnaire">
+    <section data-mk-question>
+      <h3>¿Cómo te llamas?</h3>
+      <input name="name" required aria-label="Nombre" />
+      <button type="button" data-mk-question-next>Siguiente</button>
+    </section>
+    <section data-mk-question>
+      <h3>¿Qué te interesa?</h3>
+      <label><input type="checkbox" name="topics" value="diseño" required /> Diseño</label>
+      <label><input type="checkbox" name="topics" value="código" required /> Código</label>
+      <button type="button" data-mk-question-prev>Anterior</button>
+      <button type="submit">Finalizar</button>
+    </section>
+    <p data-mk-question-error role="alert"></p>
+    <div data-mk-question-complete hidden>¡Gracias! <button type="reset">Empezar de nuevo</button></div>
+  </form>
+</mk-questionnaire>
+```
+
+Vacío, `<mk-questionnaire questions='[{"id":"name","label":"Nombre","type":"text","required":true}]'>` crea el mismo marcado. React: `<Questionnaire questions={questions} onComplete={save} complete={(answers) => <Summary answers={answers} />} />` con `Question {id, label, type: 'text'|'textarea'|'single'|'multiple', options?, required?, description?, placeholder?}` y `defaultAnswers`.
+
+Opciones: `index`, `labels {required, choice}`, `onChange(index, answers)`, `onComplete(answers)`. API: `next(): Promise<boolean>`, `prev()`, `reset()`, `answers`, `index`, `count`, `complete`, `destroy()`. `readAnswers(form)` devuelve `QuestionnaireAnswers` (`string` o `string[]` por nombre de campo: casillas y selects múltiples dan arrays).
+
+Siguiente valida el paso actual: los campos obligatorios vacíos o inválidos y los grupos de casillas/radios obligatorios (basta uno marcado por grupo). Marca `aria-invalid`, escribe el mensaje en `[data-mk-question-error]`, enfoca el primer campo inválido y emite `mk:invalid`. Un campo corregido deja de estar inválido al momento. Los botones `[data-mk-question-next|prev]` son propios: nunca saltan la validación. Enviar en el último paso completa una sola vez (`mk:complete` con `{answers}`), muestra `[data-mk-question-complete]` y evita la navegación. El reset nativo limpia respuestas, errores y finalización y vuelve al primer paso. Cada cambio de paso emite `mk:question` `{index, previous, answers}`.
+
+Las respuestas viven en los controles nativos, así que se conservan al volver atrás y entre renders de React. `destroy()` restaura atributos, textos y visibilidad. Variables: `--mk-question-radius` (24px), `--mk-question-option-radius` (16px); `--mk-question-progress` lo escribe el motor. Movimiento reducido: los pasos cambian sin flujo y la barra sin transición.

package/src/components/questionnaire/element.ts

@@ -0,0 +1,118 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import type { Instance } from '../../core/types';
+import { createQuestionnaire, type QuestionnaireInstance } from './engine';
+
+interface QuestionData {
+  id: string;
+  label: string;
+  type: 'text' | 'textarea' | 'single' | 'multiple';
+  options?: Array<string | { value: string; label: string }>;
+  required?: boolean;
+  description?: string;
+}
+
+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;
+};
+
+/** The same form the React <Questionnaire> renders, built with DOM APIs (all text as text). */
+function buildForm(questions: QuestionData[]) {
+  const form = el('form', { class: 'mk-questionnaire', novalidate: '' });
+  const progress = el('div', { 'data-mk-question-progress': '', 'aria-hidden': 'true' });
+  progress.append(el('span', { 'data-mk-question-bar': '' }));
+  form.append(progress);
+  questions.forEach((question, i) => {
+    const titleId = `${question.id}-title`;
+    const section = el('section', { 'data-mk-question': '', 'aria-labelledby': titleId });
+    if (i) section.hidden = true;
+    section.append(el('p', { 'data-mk-question-step': '' }, `Pregunta ${i + 1} de ${questions.length}`));
+    const title = el('h3', { id: titleId, 'data-mk-step-title': '', 'data-mk-flow-item': '' }, question.label);
+    if (question.required) title.append(el('span', { 'data-mk-question-required': '', 'aria-hidden': 'true' }, ' *'));
+    section.append(title);
+    if (question.description) section.append(el('p', { 'data-mk-question-description': '', 'data-mk-flow-item': '' }, question.description));
+    const field = el('div', { 'data-mk-question-field': '', 'data-mk-flow-item': '' });
+    if (question.type === 'text' || question.type === 'textarea') {
+      const input = question.type === 'text' ? el('input', { type: 'text' }) : el('textarea', { rows: '4' });
+      input.name = question.id;
+      input.required = Boolean(question.required);
+      input.setAttribute('aria-labelledby', titleId);
+      field.append(input);
+    } else {
+      const group = el('div', { role: question.type === 'single' ? 'radiogroup' : 'group', 'aria-labelledby': titleId, 'data-mk-question-options': '' });
+      for (const raw of question.options ?? []) {
+        const option = typeof raw === 'string' ? { value: raw, label: raw } : raw;
+        const label = el('label', { 'data-mk-question-option': '' });
+        const input = el('input', { type: question.type === 'single' ? 'radio' : 'checkbox' });
+        input.name = question.id;
+        input.value = option.value;
+        input.required = Boolean(question.required);
+        label.append(input, el('span', {}, option.label));
+        group.append(label);
+      }
+      field.append(group);
+    }
+    section.append(field);
+    const actions = el('div', { 'data-mk-question-actions': '', 'data-mk-flow-item': '' });
+    if (i) actions.append(el('button', { type: 'button', class: 'mk-button mk-button--text', 'data-mk-question-prev': '' }, 'Anterior'));
+    actions.append(
+      i < questions.length - 1
+        ? el('button', { type: 'button', class: 'mk-button', 'data-mk-question-next': '' }, 'Siguiente')
+        : el('button', { type: 'submit', class: 'mk-button' }, 'Finalizar'),
+    );
+    section.append(actions);
+    form.append(section);
+  });
+  form.append(el('p', { 'data-mk-question-error': '', role: 'alert' }));
+  const done = el('div', { 'data-mk-question-complete': '' });
+  done.hidden = true;
+  done.append(el('p', {}, '¡Gracias! Respuestas enviadas.'), el('button', { type: 'reset', class: 'mk-button mk-button--tonal' }, 'Empezar de nuevo'));
+  form.append(done);
+  return form;
+}
+
+/**
+ * <mk-questionnaire><form>…<section data-mk-question>…</section>…</form></mk-questionnaire>
+ * or, empty, <mk-questionnaire questions='[{"id":"name","label":"Nombre","type":"text","required":true}]'>.
+ * Emits mk:question ({index, previous, answers}), mk:invalid and mk:complete ({answers}).
+ */
+export class MkQuestionnaireElement extends MkElement<Instance> {
+  static options: Record<string, OptionType> = { questions: 'json', index: 'number' };
+
+  questionnaire: QuestionnaireInstance | null = null;
+
+  protected create(options: Record<string, unknown>): Instance {
+    const questions = Array.isArray(options.questions) ? (options.questions as QuestionData[]) : null;
+    const built = questions && !this.querySelector('[data-mk-question]') ? buildForm(questions) : null;
+    if (built) this.append(built);
+    const engine = createQuestionnaire(this, { index: options.index as number | undefined });
+    this.questionnaire = engine;
+    return {
+      destroy: () => {
+        engine.destroy();
+        built?.remove();
+        this.questionnaire = null;
+      },
+    };
+  }
+
+  next() {
+    return this.questionnaire?.next() ?? Promise.resolve(false);
+  }
+
+  prev() {
+    return this.questionnaire?.prev() ?? Promise.resolve();
+  }
+
+  reset() {
+    this.questionnaire?.reset();
+  }
+
+  get answers() {
+    return this.questionnaire?.answers ?? {};
+  }
+}
+
+export const defineQuestionnaire = () => defineElement('mk-questionnaire', MkQuestionnaireElement);