@yewdiel21/motion-kit 0.9.1 → 0.14.0

package/src/components/loading-button/engine.ts

@@ -0,0 +1,201 @@
+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 { press, shake } from '../../motion/micro';
+
+/*
+ * Loading button: a button that shows its work. Pressed (or run()), it gives
+ * Melon Mind's press, its label blurs out and a spinner draws in while the
+ * button glides to its new width (.4 s, swing); success turns it to the
+ * success colour with a check that draws itself (.35 s) and pops; error turns
+ * it to the error colour, shakes it and draws a cross; after `resetAfter` it
+ * glides back to its label. `compact` (default) shows only the icon while
+ * working; otherwise the state's text sits beside it. While loading it stays
+ * focusable but inert (aria-disabled, aria-busy) and a polite status beside it
+ * says what happened. data-mk-state carries the state for CSS.
+ */
+
+export type LoadingState = 'idle' | 'loading' | 'success' | 'error';
+
+export interface LoadingButtonOptions {
+  /** Runs on click; its promise drives the states (resolve → success, reject → error). */
+  action?: () => unknown;
+  /** Texts for the states (announced; shown beside the icon when not compact). */
+  labels?: { loading?: string; success?: string; error?: string };
+  /** Icon only while working (default true). */
+  compact?: boolean;
+  /** ms in success or error before going back to the label (default 1800; 0 stays). */
+  resetAfter?: number;
+  onStateChange?: (state: LoadingState) => void;
+}
+
+export interface LoadingButtonInstance extends Instance {
+  setState(state: LoadingState): void;
+  /** Runs `action` (or the option) and walks the states; resolves true on success. */
+  run(action?: () => unknown): Promise<boolean>;
+  readonly state: LoadingState;
+}
+
+const LABELS = { loading: 'Cargando…', success: 'Listo', error: 'Error' };
+const SVG = 'http://www.w3.org/2000/svg';
+const ICONS: Record<Exclude<LoadingState, 'idle'>, string> = {
+  loading: '<circle cx="12" cy="12" r="8.5" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-dasharray="40 14" data-mk-loading-spinner/>',
+  success: '<path d="M6 12.5l4 4L18 8" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round" data-mk-loading-draw/>',
+  error: '<path d="M7.5 7.5l9 9M16.5 7.5l-9 9" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" data-mk-loading-draw/>',
+};
+
+export function createLoadingButton(root: HTMLElement | null, options: LoadingButtonOptions = {}): LoadingButtonInstance {
+  const button = root ? (root.matches('button') ? root : root.querySelector<HTMLElement>('button')) : null;
+  if (!root || !button) return inert({ setState() {}, run: async () => false, state: 'idle' });
+  registerMotion();
+  const scope = createScope();
+  const labels = { ...LABELS, ...options.labels };
+  const compact = options.compact !== false;
+  const resetAfter = Number.isFinite(options.resetAfter) ? Math.max(0, options.resetAfter!) : 1800;
+  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();
+  });
+
+  // The authored content becomes the label (an authored [data-mk-loading-label] is used as it is: React owns its
+  // children); the icon and the state's text sit beside it.
+  const authored = button.querySelector<HTMLElement>(':scope > [data-mk-loading-label]');
+  const label = authored ?? document.createElement('span');
+  label.dataset.mkLoadingLabel = '';
+  const original = authored ? [] : [...button.childNodes];
+  label.append(...original);
+  const icon = document.createElement('span');
+  icon.dataset.mkLoadingIcon = '';
+  icon.setAttribute('aria-hidden', 'true');
+  icon.hidden = true;
+  const text = document.createElement('span');
+  text.dataset.mkLoadingText = '';
+  text.setAttribute('aria-hidden', 'true');
+  text.hidden = true;
+  if (authored) button.prepend(icon, text);
+  else button.append(icon, text, label);
+  const status = document.createElement('span');
+  status.className = 'mk-sr-only';
+  status.dataset.mkLoadingStatus = '';
+  status.setAttribute('role', 'status');
+  button.after(status);
+  scope.add(() => {
+    gsap.killTweensOf([button, label, icon, text]);
+    status.remove();
+    icon.remove();
+    text.remove();
+    if (authored) {
+      label.hidden = false;
+      return;
+    }
+    label.remove();
+    button.append(...original);
+  });
+  scope.attr(button, 'style', button.getAttribute('style'));
+  scope.attr(button, 'data-mk-state', 'idle');
+  scope.attr(button, 'aria-busy', null);
+  scope.attr(button, 'aria-disabled', button.getAttribute('aria-disabled'));
+  scope.attr(root, 'data-mk-ready', '');
+
+  let state: LoadingState = 'idle';
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  scope.add(() => clearTimeout(timer));
+
+  const drawIcon = (next: Exclude<LoadingState, 'idle'>) => {
+    const svg = document.createElementNS(SVG, 'svg');
+    svg.setAttribute('viewBox', '0 0 24 24');
+    svg.setAttribute('width', '20');
+    svg.setAttribute('height', '20');
+    svg.innerHTML = ICONS[next];
+    icon.replaceChildren(svg);
+    if (reduced()) return;
+    keep(gsap.fromTo(icon, { scale: 0.6, opacity: 0, filter: 'blur(4px)' }, { scale: 1, opacity: 1, filter: 'blur(0px)', duration: 0.3, ease: EASE.pop, clearProps: 'scale,opacity,filter,transform' }));
+    const path = svg.querySelector<SVGGeometryElement>('[data-mk-loading-draw]');
+    if (path) {
+      const length = typeof path.getTotalLength === 'function' ? path.getTotalLength() || 20 : 20;
+      keep(gsap.fromTo(path, { strokeDasharray: length, strokeDashoffset: length }, { strokeDashoffset: 0, duration: 0.35, delay: 0.05, ease: EASE.wipe }));
+    }
+  };
+
+  const setState = (next: LoadingState) => {
+    if (scope.disposed || next === state) return;
+    clearTimeout(timer);
+    const from = button.offsetWidth;
+    state = next;
+    button.setAttribute('data-mk-state', next);
+    if (next === 'loading') {
+      button.setAttribute('aria-busy', 'true');
+      button.setAttribute('aria-disabled', 'true');
+    } else {
+      button.removeAttribute('aria-busy');
+      button.removeAttribute('aria-disabled');
+    }
+    status.textContent = next === 'idle' ? '' : labels[next];
+    const working = next !== 'idle';
+    // Content: the label for idle; the icon (and the state's text unless compact) otherwise.
+    label.hidden = working;
+    icon.hidden = !working;
+    text.hidden = !working || compact;
+    text.textContent = working ? labels[next] : '';
+    if (working) drawIcon(next);
+    else icon.replaceChildren();
+    // The width glides from the old content's to the new one's.
+    if (!reduced() && from > 0) {
+      gsap.killTweensOf(button, 'width');
+      button.style.width = '';
+      const to = button.offsetWidth;
+      if (Math.abs(to - from) > 1) keep(gsap.fromTo(button, { width: from }, { width: to, duration: 0.4, ease: EASE.swatch, clearProps: 'width' }));
+      const entering = working ? (compact ? [icon] : [icon, text]) : [label];
+      keep(gsap.fromTo(entering.filter((part) => part !== icon), { opacity: 0, filter: 'blur(6px)', y: 4 }, { opacity: 1, filter: 'blur(0px)', y: 0, duration: 0.25, ease: 'power2.out', clearProps: 'opacity,filter,transform' }));
+    }
+    if (next === 'error') keep(shake(button));
+    if (next === 'success' || next === 'error') {
+      if (resetAfter) timer = setTimeout(() => setState('idle'), resetAfter);
+    }
+    options.onStateChange?.(next);
+    root.dispatchEvent(new CustomEvent('mk:state-change', { bubbles: true, detail: { state: next } }));
+  };
+
+  const run = async (action = options.action) => {
+    if (state === 'loading' || scope.disposed) return false;
+    setState('loading');
+    try {
+      await action?.();
+      if (scope.disposed) return true;
+      setState('success');
+      return true;
+    } catch {
+      if (scope.disposed) return false;
+      setState('error');
+      return false;
+    }
+  };
+
+  scope.on(button, 'click', (event) => {
+    if (state === 'loading') {
+      // Inert while working, but still focusable (aria-disabled, not disabled).
+      event.preventDefault();
+      event.stopImmediatePropagation();
+      return;
+    }
+    keep(press(button));
+    if (options.action) void run();
+  });
+
+  return {
+    setState,
+    run,
+    get state() {
+      return state;
+    },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/loading-button/loading-button.css

@@ -0,0 +1,76 @@
+/* loading-button — the button keeps its own look (.mk-button or yours); this adds the state colours, the icon slot and
+   the spinner. Success uses --mk-loading-success (a green that reads on both modes), error --mk-error. */
+.mk-loading-button,
+mk-loading-button button,
+mk-loading-button {
+  --mk-loading-success: #1f9d5b;
+}
+
+mk-loading-button {
+  display: inline-flex;
+}
+
+:is(.mk-loading-button, mk-loading-button button) {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.5rem;
+  overflow: hidden;
+  white-space: nowrap;
+  transition: background-color 0.25s ease, color 0.25s ease, box-shadow 0.25s ease;
+}
+
+:is(.mk-loading-button, mk-loading-button button)[data-mk-state='loading'] {
+  cursor: progress;
+}
+
+/* Working is not disabled: keep the button's colour (beats .mk-button[aria-disabled] whatever the order). */
+:is(.mk-loading-button, mk-loading-button button)[data-mk-state='loading'][aria-busy='true'] {
+  opacity: 1;
+}
+
+:is(.mk-loading-button, mk-loading-button button)[data-mk-state='success'] {
+  background: var(--mk-loading-success);
+  color: #fff;
+}
+
+:is(.mk-loading-button, mk-loading-button button)[data-mk-state='error'] {
+  background: var(--mk-error, #c62828);
+  color: var(--mk-on-error, #fff);
+}
+
+:is(.mk-loading-button, mk-loading-button button) [data-mk-loading-icon] {
+  display: inline-grid;
+  place-items: center;
+  flex: none;
+  width: 20px;
+  height: 20px;
+}
+
+:is(.mk-loading-button, mk-loading-button button) [data-mk-loading-icon][hidden],
+:is(.mk-loading-button, mk-loading-button button) [data-mk-loading-text][hidden],
+:is(.mk-loading-button, mk-loading-button button) [data-mk-loading-label][hidden] {
+  display: none;
+}
+
+:is(.mk-loading-button, mk-loading-button button) [data-mk-loading-spinner] {
+  transform-origin: 50% 50%;
+  animation: mk-loading-spin 0.8s linear infinite;
+}
+
+@keyframes mk-loading-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+/* Without motion the spinner stands still: a partial ring still reads as "working". */
+@media (prefers-reduced-motion: reduce) {
+  :is(.mk-loading-button, mk-loading-button button) {
+    transition: none;
+  }
+
+  :is(.mk-loading-button, mk-loading-button button) [data-mk-loading-spinner] {
+    animation: none;
+  }
+}

package/src/components/loading-button/react.tsx

@@ -0,0 +1,43 @@
+'use client';
+import { useRef, type ButtonHTMLAttributes } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createLoadingButton, type LoadingButtonInstance, type LoadingButtonOptions, type LoadingState } from './engine';
+
+export interface LoadingButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onClick'>, Omit<LoadingButtonOptions, 'action'> {
+  /** Runs on click; its promise drives loading → success / error. */
+  action?: () => unknown;
+  /** Controlled state (optional): drive it yourself instead of `action`. */
+  state?: LoadingState;
+}
+
+/** <LoadingButton action={save} className="mk-button">Guardar</LoadingButton>. */
+export function LoadingButton({ action, state, labels, compact, resetAfter, onStateChange, className, children, type = 'button', ...props }: LoadingButtonProps) {
+  const ref = useRef<HTMLButtonElement>(null);
+  const instance = useRef<LoadingButtonInstance | null>(null);
+  const run = useLatest(action);
+  const change = useLatest(onStateChange);
+  const key = JSON.stringify(labels ?? null);
+  useIsomorphicLayoutEffect(() => {
+    const created = createLoadingButton(ref.current, {
+      labels,
+      compact,
+      resetAfter,
+      action: action ? () => run.current?.() : undefined,
+      onStateChange: (next) => change.current?.(next),
+    });
+    instance.current = created;
+    return () => {
+      created.destroy();
+      instance.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key, compact, resetAfter, Boolean(action)]);
+  useIsomorphicLayoutEffect(() => {
+    if (state && instance.current && instance.current.state !== state) instance.current.setState(state);
+  }, [state]);
+  return (
+    <button {...props} type={type} ref={ref} className={['mk-loading-button', className].filter(Boolean).join(' ')}>
+      <span data-mk-loading-label="">{children}</span>
+    </button>
+  );
+}

package/src/components/multi-select/README.md

@@ -0,0 +1,48 @@
+# multi-select
+
+Selección múltiple con chips y búsqueda: un campo combobox que guarda lo elegido como chips y deja escribir para filtrar. Al escribir, la lista se filtra (letras en orden, sin importar tildes ni mayúsculas) y marca las letras que coinciden. La lista sale del campo (desde 96 % y un blur de 6 px, .22 s, curva pop) y la opción activa es una píldora que se desliza (.3 s, curva swing). Enter o un clic marcan o desmarcan una opción, y su casilla se dibuja sola.
+
+Los chips aparecen con un pop y se pliegan al quitarlos mientras los demás se recolocan. Retroceso con la búsqueda vacía marca el último chip (un anillo) y la segunda vez lo quita; ← llega a los chips y Supr quita el enfocado. Con `max`, al llegar al límite el campo se sacude y las demás opciones se desactivan.
+
+## HTML / Astro
+
+```html
+<!-- Con un <select multiple> escrito: da las opciones y se mantiene sincronizado, así el formulario envía como siempre. -->
+<mk-multi-select class="mk-multi-select" label="Equipo">
+  <select multiple name="equipo">
+    <optgroup label="Diseño"><option value="ana">Ana Gómez</option><option value="luis" selected>Luis Peña</option></optgroup>
+    <optgroup label="Código"><option value="sofia">Sofía Ruiz</option></optgroup>
+  </select>
+</mk-multi-select>
+
+<!-- O con opciones en JSON (y name para los campos ocultos name[]): -->
+<mk-multi-select options='[{"value":"mx","label":"México"},{"value":"es","label":"España"}]' value="mx" name="paises" max="3"></mk-multi-select>
+```
+
+## React
+
+```tsx
+<MultiSelect options={people} value={chosen} onChange={setChosen} label="Responsables" max={3} />
+```
+
+## Opciones
+
+| Opción | Atributo | Por defecto | Qué hace |
+|---|---|---|---|
+| `options` | `options` (JSON) | el `<select multiple>` | `{ value, label, group?, hint?, disabled? }[]`. |
+| `value` | `value` (lista con comas) | lo seleccionado | Valores elegidos. |
+| `placeholder` | `placeholder` | `'Buscar…'` | Texto de la búsqueda vacía. |
+| `label` | `label` | el `<label>` escrito | Nombre accesible. |
+| `name` | `name` | — | Campos ocultos `name[]` (sin `<select>` escrito). |
+| `max` | `max` | sin límite | Máximo de opciones. |
+| `closeOnSelect` | `close-on-select` | `false` | Cerrar la lista tras cada elección. |
+| `disabled` | `disabled` | `false` | Desactivado. |
+| `onChange(values)` | — | — | Cada cambio. |
+
+## API y eventos
+
+`setValue(values, notify = false)`, `setOptions(options)`, `open()`, `close()`, `value`, `destroy()`. Evento `mk:change` con `{ value }`.
+
+## Accesibilidad
+
+Combobox con `aria-expanded`, `aria-controls` y `aria-activedescendant`; lista `role="listbox"` con `aria-multiselectable`; los botones de los chips dicen «Quitar <nombre>» y un estado discreto anuncia cada cambio. La lista vive en la capa superior, así que ningún `overflow` la recorta. Con movimiento reducido todo cambia sin animación.

package/src/components/multi-select/element.ts

@@ -0,0 +1,28 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createMultiSelect, type MultiSelectInstance } from './engine';
+
+/**
+ * <mk-multi-select class="mk-multi-select" label="Etiquetas">
+ *   <select multiple name="etiquetas"><option>Diseño</option><option selected>Código</option></select>
+ * </mk-multi-select>
+ * Or options='[{"value":"ana","label":"Ana"}]' value="ana" name="personas". Emits mk:change ({value}).
+ */
+export class MkMultiSelectElement extends MkElement<MultiSelectInstance> {
+  static options: Record<string, OptionType> = { options: 'json', value: 'list', placeholder: 'string', label: 'string', name: 'string', max: 'number', closeOnSelect: 'boolean', disabled: 'boolean' };
+
+  protected create(options: Record<string, unknown>) {
+    return createMultiSelect(this, options);
+  }
+
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.instance) return;
+    if (name === 'value') this.instance.setValue((next ?? '').split(',').map((item) => item.trim()).filter(Boolean));
+    else super.attributeChangedCallback(name, previous, next);
+  }
+
+  get value() {
+    return this.instance?.value ?? [];
+  }
+}
+
+export const defineMultiSelect = () => defineElement('mk-multi-select', MkMultiSelectElement);