@yewdiel21/motion-kit 0.9.1 → 0.14.0

package/src/components/scratch-card/scratch-card.css

@@ -0,0 +1,74 @@
+/* scratch-card — a Melonmind card (20 px radius) whose content hides under a metallic cover; a small glass
+   "Revelar" pill sits on top for the keyboard. */
+.mk-scratch-card,
+mk-scratch-card {
+  position: relative;
+  display: block;
+  overflow: hidden;
+  border-radius: 20px;
+  background: var(--mk-surface-1);
+  box-shadow: inset 0 0 0 1px var(--mk-outline-soft);
+  isolation: isolate;
+}
+
+:is(.mk-scratch-card, mk-scratch-card) [data-mk-scratch-content] {
+  position: relative;
+  min-height: 9rem;
+}
+
+:is(.mk-scratch-card, mk-scratch-card) [data-mk-scratch-cover] {
+  position: absolute;
+  inset: 0;
+  z-index: 1;
+  cursor: crosshair;
+  touch-action: none;
+}
+
+:is(.mk-scratch-card, mk-scratch-card) [data-mk-scratch-cover] canvas {
+  display: block;
+  width: 100%;
+  height: 100%;
+}
+
+:is(.mk-scratch-card, mk-scratch-card) [data-mk-scratch-cover][data-mk-scratch-fallback] {
+  display: grid;
+  place-items: center;
+  background: linear-gradient(135deg, #c9ccd2, #eef0f3 45%, #d7dadf 55%, #a9adb5);
+  color: rgb(40 42 48 / 0.75);
+  font-weight: 600;
+  cursor: default;
+}
+
+:is(.mk-scratch-card, mk-scratch-card) [data-mk-scratch-cover][hidden] {
+  display: none;
+}
+
+:is(.mk-scratch-card, mk-scratch-card) [data-mk-scratch-reveal] {
+  position: absolute;
+  right: 0.75rem;
+  bottom: 0.75rem;
+  z-index: 2;
+  min-height: 2.25rem;
+  padding: 0 0.9rem;
+  border: 0;
+  border-radius: 64px;
+  background: rgb(20 21 24 / 0.72);
+  box-shadow:
+    inset 1px 1px 1px rgb(255 255 255 / 0.14),
+    inset -1px -1px 1px rgb(255 255 255 / 0.05);
+  backdrop-filter: blur(12px);
+  color: #fff;
+  font: inherit;
+  font-size: 0.8125rem;
+  font-weight: 500;
+  cursor: pointer;
+}
+
+:is(.mk-scratch-card, mk-scratch-card) [data-mk-scratch-reveal]:focus-visible {
+  outline: 2px solid var(--mk-accent);
+  outline-offset: 2px;
+}
+
+:is(.mk-scratch-card, mk-scratch-card) [data-mk-scratch-reveal][hidden] {
+  display: none;
+}

package/src/components/skeleton/README.md

@@ -0,0 +1,15 @@
+# skeleton
+
+Marcador de carga para texto, avatar, imagen o tarjeta. El placeholder es decorativo (`aria-hidden`) y el root marca `aria-busy` con un estado oculto que nombra lo que carga. El contenido real queda oculto sólo mientras carga.
+
+```html
+<mk-skeleton class="mk-skeleton" shape="card" animation="shimmer" label="Cargando perfil">
+  <article data-mk-skeleton-content>…contenido real…</article>
+</mk-skeleton>
+```
+
+Con `[data-mk-skeleton-placeholder]` propio se usa ese marcado; sin él, el motor crea los huesos de `shape`. `defineElements()` (atributo `loaded` para terminar), `createSkeleton(root, options)` o `<Skeleton loading={pending} shape="avatar" label="Cargando autor"><Author /></Skeleton>`.
+
+Opciones: `loading=true`, `animation='pulse'|'shimmer'|'none'`, `shape='text'|'avatar'|'image'|'card'`, `lines=3` (texto), `label='Cargando'`. API: `setLoading(boolean)`, `loading`, `destroy()`; evento `mk:loading` con `{loading}`. `skeletonBones(shape, lines)` devuelve los huesos para dibujar el mismo placeholder desde otro framework.
+
+El contenido que el autor ya tenía `hidden` sigue oculto al terminar. En React, placeholder y contenido son subárboles distintos de React; el motor sólo cambia `hidden` y el estado. `destroy()` quita lo generado y restaura atributos. Variables: `--mk-skeleton-bone`, `--mk-skeleton-sheen`, `--mk-skeleton-radius`, `--mk-skeleton-duration` (1.6s). Movimiento reducido: superficie estática, sin pulso ni brillo.

package/src/components/skeleton/element.ts

@@ -0,0 +1,32 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createSkeleton, type SkeletonInstance } from './engine';
+
+/**
+ * <mk-skeleton class="mk-skeleton" shape="card" label="Cargando perfil">
+ *   <article data-mk-skeleton-content>…</article>
+ * </mk-skeleton>
+ * Loading until `loaded` is set (or `setLoading(false)`); a placeholder is made from `shape`.
+ */
+export class MkSkeletonElement extends MkElement<SkeletonInstance> {
+  static options: Record<string, OptionType> = { loaded: 'boolean', animation: 'string', shape: 'string', lines: 'number', label: 'string' };
+
+  protected create(options: Record<string, unknown>) {
+    return createSkeleton(this, { ...options, loading: !options.loaded });
+  }
+
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.instance) return;
+    if (name === 'loaded') this.instance.setLoading(next === null || next === 'false');
+    else super.attributeChangedCallback(name, previous, next);
+  }
+
+  setLoading(loading: boolean) {
+    this.instance?.setLoading(loading);
+  }
+
+  get loading() {
+    return this.instance?.loading ?? false;
+  }
+}
+
+export const defineSkeleton = () => defineElement('mk-skeleton', MkSkeletonElement);

package/src/components/skeleton/engine.ts

@@ -0,0 +1,104 @@
+import type { gsap } from '../../core/gsap';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { blurIn } from '../../motion/micro';
+
+/*
+ * Skeleton: a decorative placeholder ([data-mk-skeleton-placeholder], made from
+ * `shape` when absent) stands in for the real content ([data-mk-skeleton-content])
+ * while loading. The root is aria-busy and a hidden status names what loads; the
+ * placeholder is aria-hidden. Content the author hid stays hidden. Pulse and
+ * shimmer are CSS; reduced motion keeps a still surface.
+ */
+
+export type SkeletonShape = 'text' | 'avatar' | 'image' | 'card';
+export type SkeletonAnimation = 'pulse' | 'shimmer' | 'none';
+
+export interface SkeletonOptions {
+  loading?: boolean;
+  animation?: SkeletonAnimation;
+  /** Placeholder made when the markup has none. */
+  shape?: SkeletonShape;
+  /** Text lines of a generated text placeholder (default 3). */
+  lines?: number;
+  /** Announced while loading (default 'Cargando'). */
+  label?: string;
+}
+
+export interface SkeletonInstance extends Instance {
+  setLoading(loading: boolean): void;
+  readonly loading: boolean;
+}
+
+/** Bones of each shape: block (image), circle (avatar), line (text). */
+export function skeletonBones(shape: SkeletonShape, lines = 3): Array<'block' | 'circle' | 'line' | 'short'> {
+  const count = Math.max(1, Math.round(lines) || 1);
+  const text = Array.from({ length: count }, (_, i) => (i === count - 1 && count > 1 ? 'short' : 'line') as 'line' | 'short');
+  if (shape === 'avatar') return ['circle', 'line', 'short'];
+  if (shape === 'image') return ['block'];
+  if (shape === 'card') return ['block', 'line', 'short'];
+  return text;
+}
+
+export function createSkeleton(root: HTMLElement | null, options: SkeletonOptions = {}): SkeletonInstance {
+  if (!root) return inert({ setLoading() {}, loading: false });
+  const scope = createScope();
+  const shape = options.shape ?? 'text';
+  const animation = options.animation ?? 'pulse';
+  let loading = options.loading ?? true;
+
+  let placeholder = root.querySelector<HTMLElement>('[data-mk-skeleton-placeholder]');
+  if (!placeholder) {
+    const made = document.createElement('div');
+    made.dataset.mkSkeletonPlaceholder = '';
+    made.dataset.mkShape = shape;
+    for (const bone of skeletonBones(shape, options.lines)) {
+      const element = document.createElement('span');
+      element.dataset.mkBone = bone;
+      made.append(element);
+    }
+    root.prepend(made);
+    scope.add(() => made.remove());
+    placeholder = made;
+  }
+  const contents = [...root.querySelectorAll<HTMLElement>('[data-mk-skeleton-content]')];
+  const authoredHidden = new Map(contents.map((content) => [content, content.hidden]));
+  const status = document.createElement('span');
+  status.className = 'mk-sr-only';
+  status.dataset.mkSkeletonStatus = '';
+  root.append(status);
+  scope.add(() => status.remove());
+
+  scope.attr(placeholder, 'aria-hidden', 'true');
+  scope.attr(root, 'data-mk-shape', shape);
+  scope.attr(root, 'data-mk-animation', animation);
+  scope.attr(root, 'data-mk-ready', '');
+
+  // The reveal animates the content's inline style: the authored one comes back on destroy.
+  for (const content of contents) scope.attr(content, 'style', content.getAttribute('style'));
+  let reveal: gsap.core.Animation | null = null;
+  scope.add(() => reveal?.progress(1).kill());
+  const render = () => {
+    scope.attr(root, 'aria-busy', String(loading));
+    scope.attr(placeholder!, 'hidden', loading ? null : '');
+    for (const content of contents) scope.attr(content, 'hidden', loading || authoredHidden.get(content) ? '' : null);
+    status.textContent = loading ? options.label ?? 'Cargando' : '';
+  };
+  render();
+
+  return {
+    setLoading(next) {
+      if (scope.disposed || next === loading) return;
+      loading = next;
+      render();
+      // Melonmind's list entrance (blur 16, y −20, 50 ms apart) for what was waiting.
+      reveal?.progress(1).kill();
+      if (!loading) reveal = blurIn(contents.filter((content) => !content.hidden), { stagger: 0.05 });
+      root.dispatchEvent(new CustomEvent('mk:loading', { bubbles: true, detail: { loading } }));
+    },
+    get loading() {
+      return loading;
+    },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/skeleton/react.tsx

@@ -0,0 +1,41 @@
+'use client';
+import { useRef, type HTMLAttributes, type ReactNode } from 'react';
+import { useIsomorphicLayoutEffect } from '../../react/use-recipe';
+import { createSkeleton, skeletonBones, type SkeletonInstance, type SkeletonOptions } from './engine';
+
+export interface SkeletonProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'>, SkeletonOptions {
+  /** The real content, shown when loading ends. */
+  children?: ReactNode;
+  /** Custom placeholder instead of the shape's bones. */
+  placeholder?: ReactNode;
+}
+
+/**
+ * <Skeleton loading={pending} shape="card" label="Cargando perfil"><ProfileCard /></Skeleton>.
+ * React owns placeholder and content; the engine only toggles hidden and the busy state.
+ */
+export function Skeleton({ loading = true, animation, shape = 'text', lines, label, placeholder, children, className, ...props }: SkeletonProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const instance = useRef<SkeletonInstance | null>(null);
+  const current = useRef(loading);
+  current.current = loading;
+  useIsomorphicLayoutEffect(() => {
+    const created = createSkeleton(ref.current, { loading: current.current, animation, shape, lines, label });
+    instance.current = created;
+    return () => {
+      created.destroy();
+      instance.current = null;
+    };
+  }, [animation, shape, lines, label]);
+  useIsomorphicLayoutEffect(() => {
+    instance.current?.setLoading(loading);
+  }, [loading]);
+  return (
+    <div {...props} ref={ref} className={['mk-skeleton', className].filter(Boolean).join(' ')} data-mk-ssr-loading={loading ? '' : undefined}>
+      <div data-mk-skeleton-placeholder="" data-mk-shape={shape}>
+        {placeholder ?? skeletonBones(shape, lines).map((bone, i) => <span key={i} data-mk-bone={bone} />)}
+      </div>
+      <div data-mk-skeleton-content="">{children}</div>
+    </div>
+  );
+}

package/src/components/skeleton/skeleton.css

@@ -0,0 +1,107 @@
+/* skeleton — soft bones on the surface tone; pulse (opacity) or shimmer (a passing sheen). */
+.mk-skeleton,
+mk-skeleton {
+  --mk-skeleton-bone: var(--mk-surface-3);
+  --mk-skeleton-sheen: color-mix(in srgb, var(--mk-surface-1) 80%, transparent);
+  --mk-skeleton-radius: var(--mk-radius-md, 16px);
+  /* Melonmind animation-loading-2: a sheen crossing in 1 s. */
+  --mk-skeleton-duration: 1s;
+  display: block;
+}
+
+:is(.mk-skeleton, mk-skeleton) [data-mk-skeleton-placeholder] {
+  display: grid;
+  gap: 0.625rem;
+}
+
+:is(.mk-skeleton, mk-skeleton) [data-mk-skeleton-placeholder][hidden],
+:is(.mk-skeleton, mk-skeleton) [data-mk-skeleton-content][hidden] {
+  display: none !important;
+}
+
+/* Before the engine runs (server render), the React state decides what shows. */
+:is(.mk-skeleton, mk-skeleton):not([data-mk-ready])[data-mk-ssr-loading] > [data-mk-skeleton-content],
+:is(.mk-skeleton, mk-skeleton):not([data-mk-ready]):not([data-mk-ssr-loading]) > [data-mk-skeleton-placeholder] {
+  display: none;
+}
+
+:is(.mk-skeleton, mk-skeleton) [data-mk-bone] {
+  position: relative;
+  display: block;
+  overflow: hidden;
+  height: 0.875rem;
+  border-radius: var(--mk-radius-full);
+  background: var(--mk-skeleton-bone);
+}
+
+:is(.mk-skeleton, mk-skeleton) [data-mk-bone='short'] {
+  width: 62%;
+}
+
+:is(.mk-skeleton, mk-skeleton) [data-mk-bone='circle'] {
+  width: 3.5rem;
+  height: 3.5rem;
+  border-radius: 50%;
+}
+
+:is(.mk-skeleton, mk-skeleton) [data-mk-bone='block'] {
+  height: auto;
+  aspect-ratio: 16 / 9;
+  border-radius: var(--mk-skeleton-radius);
+}
+
+/* Avatar: circle beside two lines. */
+:is(.mk-skeleton, mk-skeleton) [data-mk-shape='avatar'] {
+  grid-template-columns: auto minmax(0, 1fr);
+  align-items: center;
+  column-gap: 1rem;
+}
+
+:is(.mk-skeleton, mk-skeleton) [data-mk-shape='avatar'] [data-mk-bone='circle'] {
+  grid-row: span 2;
+}
+
+:is(.mk-skeleton, mk-skeleton) [data-mk-shape='card'] {
+  padding: 0.5rem 0.5rem 1rem;
+  border-radius: var(--mk-radius-lg, 24px);
+  background: var(--mk-surface-1);
+  box-shadow: inset 0 0 0 1px var(--mk-outline-soft);
+}
+
+:is(.mk-skeleton, mk-skeleton)[data-mk-animation='pulse'][aria-busy='true'] [data-mk-bone] {
+  animation: mk-skeleton-pulse var(--mk-skeleton-duration) ease-in-out infinite;
+}
+
+:is(.mk-skeleton, mk-skeleton)[data-mk-animation='shimmer'][aria-busy='true'] [data-mk-bone]::after {
+  content: '';
+  position: absolute;
+  inset: 0;
+  background: linear-gradient(90deg, transparent, var(--mk-skeleton-sheen), transparent);
+  transform: translateX(-100%);
+  animation: mk-skeleton-shimmer var(--mk-skeleton-duration) linear infinite;
+}
+
+
+@keyframes mk-skeleton-pulse {
+  50% { opacity: 0.45; }
+}
+
+@keyframes mk-skeleton-shimmer {
+  to { transform: translateX(100%); }
+}
+
+@keyframes mk-skeleton-reveal {
+  from { opacity: 0; transform: translateY(4px); }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :is(.mk-skeleton, mk-skeleton) [data-mk-bone],
+  :is(.mk-skeleton, mk-skeleton) [data-mk-bone]::after,
+  :is(.mk-skeleton, mk-skeleton) [data-mk-skeleton-content] {
+    animation: none !important;
+  }
+
+  :is(.mk-skeleton, mk-skeleton) [data-mk-bone]::after {
+    display: none;
+  }
+}

package/src/components/slot-picker/README.md

@@ -0,0 +1,68 @@
+# slot-picker
+
+El selector de citas de Melon Mind («Agendar cita»): a la izquierda un mes compacto y a la derecha los horarios del día elegido. Sirve para reservas, citas o mesas.
+
+- **Cambiar de día:** los horarios salen 30 px hacia un lado y entran 30 px desde el otro (0.25 s `ease-out`), en la dirección del cambio. El original usa una View Transition `time-slot`.
+- **Primera lista:** entra creciendo (escala .7, blur 32 → 0, 0.3 s `cubic-bezier(.38,.49,0,1.1)`), 20 ms entre horarios.
+- **Encabezado del día:** se abre de 0 a 56 px en 0.5 s `cubic-bezier(.38,.49,0,1.4)`.
+- **Horario elegido:** se ilumina en 0.7 s (escala .8 → 1, blur 16 → 0).
+- **Cambiar de mes:** los días se deslizan igual que los horarios.
+
+Origen: REA de la app de Melon Mind (`appt-creator.css`, `schedulePicker.css`, `CreateApptManager.js`).
+
+## HTML / Astro
+
+```html
+<mk-slot-picker class="mk-slot-picker" locale="es" min="2026-10-23" closed-days="[0]"
+  slots='["09:00","10:00","11:30","16:00","17:30"]'>
+  <div class="mk-slot-picker__calendar">
+    <div class="mk-slot-picker__month">
+      <h3 class="mk-slot-picker__title" data-mk-slot-title></h3>
+      <button type="button" class="mk-slot-picker__nav" data-mk-slot-prev aria-label="Mes anterior">←</button>
+      <button type="button" class="mk-slot-picker__nav" data-mk-slot-next aria-label="Mes siguiente">→</button>
+    </div>
+    <div data-mk-slot-days></div>
+  </div>
+  <div class="mk-slot-picker__panel">
+    <p class="mk-slot-picker__heading" data-mk-slot-heading></p>
+    <div data-mk-slot-times></div>
+    <input type="hidden" name="cita" data-mk-slot-value>
+  </div>
+</mk-slot-picker>
+```
+
+El input oculto `[data-mk-slot-value]` lleva `YYYY-MM-DDTHH:mm` y emite `input`/`change`, así que funciona dentro de un `<form>`. Si cambias el atributo `slots`, la lista se actualiza sin perder el día. Sin custom element: `createSlotPicker(root, opciones)`.
+
+## React
+
+```tsx
+<SlotPicker
+  name="cita"
+  min={new Date()}
+  closedDays={[0]}
+  slots={(day) => fetch(`/api/horarios?dia=${dayKey(day)}`).then((r) => r.json())}
+  onChange={({ value }) => setCita(value)}
+  actions={<button className="mk-button">Agendar</button>}
+/>
+```
+
+## Opciones
+
+| Opción | Atributo | Por defecto | Qué hace |
+|---|---|---|---|
+| `slots` | `slots` (JSON) | `[]` | Lista igual todos los días, mapa `{"2026-10-23": [...]}` o función `(día) => lista \| Promise<lista>`. Horas `HH:mm` |
+| `date` | `date` | hoy | Mes inicial (y día elegido si no hay `value`) |
+| `value` | `value` | — | `"2026-10-23T10:30"` o `{ date, time }` |
+| `min`, `max` | `min`, `max` | — | Días fuera de rango deshabilitados; flechas de mes limitadas |
+| `closedDays` | `closed-days` (JSON) | `[]` | Días de la semana cerrados (0 = domingo) |
+| `isDisabled(date)` | — | — | Regla propia |
+| `firstDay` | `first-day` | `0` | Primer día de la semana |
+| `locale` | `locale` | `'es'` | Nombres de mes y día |
+| `labels` | — | español | `placeholder`, `empty`, `loading`, `heading(date)` |
+| `onChange({date, time, key, value})`, `onDateChange(date)` | — | — | Callbacks |
+
+API: `selectDate(d)`, `selectTime(t | null)`, `setSlots(fuente)`, `date`, `time`, `value`, `destroy()`. `mk:change` lleva `{date, time, key, value}`. Si los horarios llegan por promesa, mientras cargan se muestra `loading` con `aria-busy`, y una respuesta vieja nunca pisa a la más reciente.
+
+## Accesibilidad
+
+Los días forman una rejilla ARIA con foco móvil: flechas, Inicio/Fin y RePág/AvPág para cambiar de mes. Los horarios son un `radiogroup`: las flechas mueven la selección, y el grupo está etiquetado por el encabezado del día. Los días deshabilitados son botones `disabled`. Con movimiento reducido no hay deslizamiento, entradas ni resaltado animado.

package/src/components/slot-picker/element.ts

@@ -0,0 +1,27 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createSlotPicker, type SlotPickerInstance, type SlotSource } from './engine';
+
+/** Light DOM: supply the [data-mk-slot-days] and [data-mk-slot-times] markup shown in the README. */
+export class MkSlotPickerElement extends MkElement<SlotPickerInstance> {
+  static options: Record<string, OptionType> = {
+    date: 'string', value: 'string', slots: 'json', min: 'string', max: 'string', closedDays: 'json', firstDay: 'number', locale: 'string',
+  };
+
+  protected create(options: Record<string, unknown>) {
+    return createSlotPicker(this, options);
+  }
+
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.isConnected || !this.instance) return;
+    if (name === 'slots') {
+      this.instance.setSlots((this.options.slots as SlotSource | undefined) ?? []);
+      return;
+    }
+    // Keep the visitor's pick unless the value itself changed.
+    const value = this.instance.value ?? (this.instance.date ? this.instance.date : undefined);
+    this.instance.destroy();
+    this.instance = this.create({ ...(name !== 'value' && value ? (typeof value === 'string' ? { value } : { date: value }) : {}), ...this.options });
+  }
+}
+
+export const defineSlotPicker = () => defineElement('mk-slot-picker', MkSlotPickerElement);