@yewdiel21/motion-kit 0.10.0 → 0.15.0

package/src/components/activity-feed/engine.ts

@@ -0,0 +1,351 @@
+import { gsap, EASE, Flip, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { TIMING } from '../../core/timing';
+import { inert, type Instance } from '../../core/types';
+import { dayKey, fromJson } from '../../core/dates';
+import { dayLabel, everyMinute, fullTime, relativeTime, toTime, type TimeInput } from '../../core/relative-time';
+import { blurIn, press, rollDigits } from '../../motion/micro';
+
+/*
+ * Activity feed: what people did, newest first, under day headings ("Hoy",
+ * "Ayer", "Lunes, 12 de noviembre"). Each entry has an avatar (a picture, or
+ * initials on a colour from the name) with a badge for the kind of action,
+ * "<b>Ana</b> comentó en <a>Tarea 12</a>", a time ("hace 5 min", refreshed
+ * every minute) and an optional quote. New activity (prepend()) comes in at the
+ * top: the entries below glide down (layout spring) while the new ones drop in
+ * out of a blur and keep a soft highlight that fades. If the reader has
+ * scrolled down, a "3 novedades" pill pops in at the top instead (its count
+ * rolls); pressing it scrolls up and brings them in. "Cargar más" at the end
+ * asks onLoadMore() for older entries (working while it waits) and flows them in.
+ */
+
+export interface ActivityActor {
+  name: string;
+  /** A picture URL; without it, the initials. */
+  avatar?: string;
+}
+
+export type ActivityKind = 'comment' | 'create' | 'update' | 'delete' | 'upload' | 'complete' | 'mention';
+
+export interface ActivityItem {
+  id: string;
+  actor: ActivityActor | string;
+  /** The verb: "comentó en", "cerró", "subió". */
+  action: string;
+  /** What it was done to. */
+  target?: string;
+  /** A link for the target. */
+  href?: string;
+  time: TimeInput;
+  /** A quote under it (the comment). */
+  detail?: string;
+  kind?: ActivityKind;
+}
+
+export interface ActivityFeedOptions {
+  items?: ActivityItem[];
+  locale?: string;
+  /** Accessible name (default 'Actividad'). */
+  label?: string;
+  /** Older entries for "Cargar más": resolve with them, or with [] when there are no more. */
+  onLoadMore?: () => Promise<ActivityItem[]> | ActivityItem[];
+  emptyLabel?: string;
+}
+
+export interface ActivityFeedInstance extends Instance {
+  /** New activity on top (or behind the "novedades" pill when the reader is scrolled down). */
+  prepend(items: ActivityItem[]): void;
+  append(items: ActivityItem[]): void;
+  setItems(items: ActivityItem[]): void;
+  readonly items: ActivityItem[];
+}
+
+const SVG = (path: string) => `<svg aria-hidden="true" width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"><path d="${path}"/></svg>`;
+const KIND_ICON: Record<ActivityKind, string> = {
+  comment: SVG('M5 6h14v9H9l-4 4z'),
+  create: SVG('M12 5v14M5 12h14'),
+  update: SVG('M5 19l1-4L16 5l3 3L9 18z'),
+  delete: SVG('M6 7h12M9 7V5h6v2M8 7l1 12h6l1-12'),
+  upload: SVG('M12 19V6M6 12l6-6 6 6'),
+  complete: SVG('M5 12.5l4.5 4.5L19 7.5'),
+  mention: SVG('M16 12a4 4 0 1 1-1.2-2.8M16 9v4a2 2 0 0 0 4 0v-1a8 8 0 1 0-3 6.2'),
+};
+
+const nameOf = (actor: ActivityActor | string) => (typeof actor === 'string' ? actor : actor.name);
+const initials = (name: string) =>
+  name
+    .split(/\s+/)
+    .filter(Boolean)
+    .slice(0, 2)
+    .map((part) => part[0]!.toLocaleUpperCase())
+    .join('');
+/** A hue from the name, so a person keeps their colour. */
+const hueOf = (name: string) => [...name].reduce((hash, char) => (hash * 31 + char.charCodeAt(0)) % 360, 7);
+
+export function createActivityFeed(root: HTMLElement | null, options: ActivityFeedOptions = {}): ActivityFeedInstance {
+  if (!root) return inert({ prepend() {}, append() {}, setItems() {}, items: [] });
+  registerMotion();
+  const scope = createScope();
+  const locale = options.locale ?? root.closest('[lang]')?.getAttribute('lang') ?? 'es';
+  // JSON text too (data-mk-items through autoInit).
+  let items = [...(fromJson(options.items) ?? [])];
+  let waiting: ActivityItem[] = [];
+  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);
+  };
+
+  const pill = document.createElement('button');
+  pill.type = 'button';
+  pill.dataset.mkAfNew = '';
+  pill.hidden = true;
+  const pillCount = document.createElement('span');
+  pillCount.dataset.mkAfNewCount = '';
+  const pillText = document.createElement('span');
+  pill.append('↑ ', pillCount, pillText);
+  const feed = document.createElement('div');
+  feed.dataset.mkAfFeed = '';
+  feed.setAttribute('role', 'feed');
+  feed.setAttribute('aria-label', options.label ?? 'Actividad');
+  const empty = document.createElement('p');
+  empty.dataset.mkAfEmpty = '';
+  empty.textContent = options.emptyLabel ?? 'Sin actividad todavía';
+  const more = document.createElement('button');
+  more.type = 'button';
+  more.dataset.mkAfMore = '';
+  more.textContent = 'Cargar más';
+  more.hidden = !options.onLoadMore;
+  const status = document.createElement('span');
+  status.className = 'mk-sr-only';
+  status.setAttribute('role', 'status');
+  root.append(pill, feed, empty, more, status);
+  scope.add(() => {
+    for (const effect of effects) effect.kill();
+    effects.clear();
+    for (const part of [pill, feed, empty, more, status]) part.remove();
+  });
+  scope.attr(root, 'data-mk-ready', '');
+
+  const entry = (item: ActivityItem) => {
+    const li = document.createElement('li');
+    li.dataset.mkAfItem = '';
+    li.dataset.id = item.id;
+    li.setAttribute('role', 'article');
+    li.tabIndex = -1;
+    const name = nameOf(item.actor);
+    const avatar = document.createElement('span');
+    avatar.dataset.mkAfAvatar = '';
+    avatar.setAttribute('aria-hidden', 'true');
+    avatar.style.setProperty('--mk-af-hue', String(hueOf(name)));
+    const picture = typeof item.actor === 'string' ? undefined : item.actor.avatar;
+    if (picture) {
+      const img = document.createElement('img');
+      img.src = picture;
+      img.alt = '';
+      img.loading = 'lazy';
+      avatar.append(img);
+    } else avatar.textContent = initials(name);
+    if (item.kind) {
+      const badge = document.createElement('span');
+      badge.dataset.mkAfBadge = item.kind;
+      badge.innerHTML = KIND_ICON[item.kind];
+      avatar.append(badge);
+    }
+    const body = document.createElement('div');
+    body.dataset.mkAfBody = '';
+    const line = document.createElement('p');
+    line.dataset.mkAfLine = '';
+    const who = document.createElement('b');
+    who.textContent = name;
+    line.append(who, ` ${item.action}`);
+    if (item.target) {
+      line.append(' ');
+      const target = document.createElement(item.href ? 'a' : 'span');
+      target.dataset.mkAfTarget = '';
+      if (target instanceof HTMLAnchorElement) target.href = item.href!;
+      target.textContent = item.target;
+      line.append(target);
+    }
+    body.append(line);
+    if (item.detail) {
+      const quote = document.createElement('blockquote');
+      quote.dataset.mkAfDetail = '';
+      quote.textContent = item.detail;
+      body.append(quote);
+    }
+    const date = toTime(item.time);
+    if (date) {
+      const time = document.createElement('time');
+      time.dataset.mkAfTime = '';
+      time.dateTime = date.toISOString();
+      time.title = fullTime(date, locale);
+      time.textContent = relativeTime(date, new Date(), locale);
+      body.append(time);
+    }
+    li.append(avatar, body);
+    return li;
+  };
+
+  const render = () => {
+    const days = new Map<string, { date: Date | null; list: HTMLUListElement }>();
+    const sections: HTMLElement[] = [];
+    for (const item of items) {
+      const date = toTime(item.time);
+      const key = date ? dayKey(date) : '';
+      let group = days.get(key);
+      if (!group) {
+        const section = document.createElement('section');
+        section.dataset.mkAfDay = key;
+        const heading = document.createElement('h3');
+        heading.dataset.mkAfHeading = '';
+        heading.textContent = date ? dayLabel(date, new Date(), locale) : 'Sin fecha';
+        const list = document.createElement('ul');
+        section.append(heading, list);
+        sections.push(section);
+        group = { date, list };
+        days.set(key, group);
+      }
+      group.list.append(entry(item));
+    }
+    feed.replaceChildren(...sections);
+    empty.hidden = items.length > 0;
+  };
+
+  const refreshTimes = () => {
+    for (const time of feed.querySelectorAll<HTMLTimeElement>('[data-mk-af-time]')) time.textContent = relativeTime(new Date(time.dateTime), new Date(), locale);
+    for (const section of feed.querySelectorAll<HTMLElement>('[data-mk-af-day]')) {
+      const key = section.dataset.mkAfDay!;
+      if (key) section.querySelector('h3')!.textContent = dayLabel(toTime(key)!, new Date(), locale);
+    }
+  };
+  scope.add(everyMinute(refreshTimes));
+
+  /** Re-render with `change`; what stays glides (Flip), the given new ids come in from `from`. */
+  const reflow = (change: () => void, fresh: Set<string>, from: 'top' | 'bottom') => {
+    const all = () => [...feed.querySelectorAll<HTMLElement>('[data-mk-af-item], [data-mk-af-heading]')];
+    for (const element of all()) element.dataset.flipId = element.dataset.id ?? `day-${element.closest<HTMLElement>('[data-mk-af-day]')!.dataset.mkAfDay}`;
+    const state = reduced() ? null : Flip.getState(all());
+    change();
+    for (const element of all()) element.dataset.flipId = element.dataset.id ?? `day-${element.closest<HTMLElement>('[data-mk-af-day]')!.dataset.mkAfDay}`;
+    const arriving = [...feed.querySelectorAll<HTMLElement>('[data-mk-af-item]')].filter((li) => fresh.has(li.dataset.id!));
+    for (const li of arriving) if (from === 'top') li.setAttribute('data-mk-fresh', '');
+    if (!state) return;
+    keep(
+      Flip.from(state, {
+        targets: all(),
+        duration: TIMING.layoutTravel,
+        ease: EASE.layoutReflow,
+        onEnter: (entering) => gsap.fromTo(entering, { opacity: 0, y: from === 'top' ? -14 : 14, filter: 'blur(10px)' }, { opacity: 1, y: 0, filter: 'blur(0px)', duration: 0.45, stagger: 0.05, ease: 'power2.out', clearProps: 'opacity,transform,filter' }),
+      }),
+    );
+  };
+
+  const showPill = () => {
+    const count = waiting.length;
+    const text = String(count);
+    pillText.textContent = count === 1 ? ' novedad' : ' novedades';
+    status.textContent = `${count} ${count === 1 ? 'novedad' : 'novedades'}`;
+    if (pill.hidden) {
+      pill.hidden = false;
+      pillCount.textContent = text;
+      if (!reduced()) keep(gsap.fromTo(pill, { opacity: 0, y: -10, scale: 0.85, filter: 'blur(6px)' }, { opacity: 1, y: 0, scale: 1, filter: 'blur(0px)', duration: 0.35, ease: EASE.pop, clearProps: 'opacity,transform,filter' }));
+    } else keep(rollDigits(pillCount, text, 1, 0.3));
+  };
+
+  const bringIn = (fresh: ActivityItem[]) => {
+    const ids = new Set(fresh.map((item) => item.id));
+    reflow(() => {
+      items = [...fresh, ...items.filter((item) => !ids.has(item.id))];
+      render();
+    }, ids, 'top');
+  };
+
+  scope.on(pill, 'click', () => {
+    const fresh = waiting;
+    waiting = [];
+    const finish = () => {
+      pill.hidden = true;
+      bringIn(fresh);
+      feed.querySelector<HTMLElement>('[data-mk-af-item]')?.focus({ preventScroll: true });
+    };
+    if (reduced() || root.scrollTop === 0) {
+      root.scrollTop = 0;
+      return finish();
+    }
+    keep(gsap.to(root, { scrollTop: 0, duration: 0.5, ease: EASE.signature, onComplete: finish }));
+  });
+
+  scope.on(more, 'click', async () => {
+    if (!options.onLoadMore || more.getAttribute('aria-busy') === 'true') return;
+    keep(press(more));
+    more.setAttribute('aria-busy', 'true');
+    more.textContent = 'Cargando…';
+    let older: ActivityItem[] = [];
+    try {
+      older = await options.onLoadMore();
+    } catch {
+      more.textContent = 'Reintentar';
+      more.removeAttribute('aria-busy');
+      return;
+    }
+    if (scope.disposed) return;
+    more.removeAttribute('aria-busy');
+    if (!older.length) {
+      more.hidden = true;
+      status.textContent = 'No hay más actividad';
+      const end = document.createElement('p');
+      end.dataset.mkAfEnd = '';
+      end.textContent = 'No hay más actividad';
+      more.after(end);
+      scope.add(() => end.remove());
+      return;
+    }
+    more.textContent = 'Cargar más';
+    const known = new Set(items.map((item) => item.id));
+    const added = older.filter((item) => !known.has(item.id));
+    items = [...items, ...added];
+    render();
+    const arriving = [...feed.querySelectorAll<HTMLElement>('[data-mk-af-item]')].filter((li) => added.some((item) => item.id === li.dataset.id));
+    keep(blurIn(arriving, { from: 'rise', stagger: 0.04 }));
+    status.textContent = `${added.length} más`;
+  });
+
+  render();
+
+  return {
+    prepend(fresh) {
+      if (scope.disposed || !fresh.length) return;
+      if (root.scrollTop > 24) {
+        const ids = new Set(fresh.map((item) => item.id));
+        waiting = [...fresh, ...waiting.filter((item) => !ids.has(item.id))];
+        showPill();
+        return;
+      }
+      bringIn(fresh);
+      status.textContent = fresh.length === 1 ? `${nameOf(fresh[0]!.actor)} ${fresh[0]!.action}${fresh[0]!.target ? ` ${fresh[0]!.target}` : ''}` : `${fresh.length} novedades`;
+    },
+    append(older) {
+      if (scope.disposed) return;
+      const ids = new Set(older.map((item) => item.id));
+      reflow(() => {
+        items = [...items.filter((item) => !ids.has(item.id)), ...older];
+        render();
+      }, ids, 'bottom');
+    },
+    setItems(next) {
+      if (scope.disposed) return;
+      items = [...next];
+      waiting = [];
+      pill.hidden = true;
+      render();
+    },
+    get items() {
+      return [...items];
+    },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/activity-feed/react.tsx

@@ -0,0 +1,32 @@
+'use client';
+import { forwardRef, useImperativeHandle, useRef, type HTMLAttributes } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createActivityFeed, type ActivityFeedInstance, type ActivityFeedOptions, type ActivityItem } from './engine';
+
+export interface ActivityFeedProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'>, Omit<ActivityFeedOptions, 'items'> {
+  /** Initial entries; later activity goes through the handle (prepend / append). */
+  items?: ActivityItem[];
+}
+
+export interface ActivityFeedHandle {
+  prepend(items: ActivityItem[]): void;
+  append(items: ActivityItem[]): void;
+}
+
+/** <ActivityFeed ref={feed} items={recent} onLoadMore={loadOlder} />, then feed.current.prepend(live). */
+export const ActivityFeed = forwardRef<ActivityFeedHandle, ActivityFeedProps>(function ActivityFeed({ items, locale, label, emptyLabel, onLoadMore, className, ...props }, handle) {
+  const ref = useRef<HTMLDivElement>(null);
+  const instance = useRef<ActivityFeedInstance | null>(null);
+  const load = useLatest(onLoadMore);
+  useImperativeHandle(handle, () => ({ prepend: (next) => instance.current?.prepend(next), append: (next) => instance.current?.append(next) }), []);
+  useIsomorphicLayoutEffect(() => {
+    const created = createActivityFeed(ref.current, { items, locale, label, emptyLabel, onLoadMore: onLoadMore ? () => load.current?.() ?? [] : undefined });
+    instance.current = created;
+    return () => {
+      created.destroy();
+      instance.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [locale, label, emptyLabel, Boolean(onLoadMore)]);
+  return <div {...props} ref={ref} className={['mk-activity-feed', className].filter(Boolean).join(' ')} />;
+});

package/src/components/add-to-cart/README.md

@@ -0,0 +1,34 @@
+# add-to-cart
+
+Qué hace, en una frase.
+
+Origen: archivo del kit y parámetros (tiempos, curvas).
+
+## HTML / Astro
+
+```html
+<mk-add-to-cart></mk-add-to-cart>
+<script>
+  import { defineElements } from '@yewdiel21/motion-kit/elements';
+  defineElements(['mk-add-to-cart']);
+</script>
+```
+
+## React
+
+```tsx
+<AddToCart />
+```
+
+## Opciones
+
+| Opción | Atributo | Por defecto | Qué hace |
+|---|---|---|---|
+
+## Variables CSS
+
+`--mk-add-to-cart-radius`
+
+## Accesibilidad
+
+Roles, foco y teclado. Con movimiento reducido…

package/src/components/add-to-cart/add-to-cart.css

@@ -0,0 +1,71 @@
+/* add-to-cart — the little box that carries the product to the cart: a kraft front with a tape stripe in the accent,
+   two flaps that close over the picture, a soft shadow; it flies above everything and never takes the pointer. */
+.mk-add-to-cart,
+mk-add-to-cart {
+  display: inline-flex;
+}
+
+[data-mk-cart-box] {
+  --mk-cart-box: #c99a62;
+  --mk-cart-box-shade: #b0824d;
+  --mk-cart-tape: var(--mk-accent);
+  position: fixed;
+  z-index: 2147483646;
+  pointer-events: none;
+  filter: drop-shadow(0 10px 14px rgb(0 0 0 / 0.28));
+}
+
+[data-mk-cart-thumb] {
+  position: absolute;
+  top: 6px;
+  left: 50%;
+  width: 40px;
+  height: 40px;
+  margin-left: -20px;
+  border-radius: 8px;
+  object-fit: cover;
+}
+
+[data-mk-cart-front] {
+  position: absolute;
+  right: 0;
+  bottom: 0;
+  left: 0;
+  height: 70%;
+  border-radius: 4px 4px 8px 8px;
+  background: linear-gradient(180deg, var(--mk-cart-box), var(--mk-cart-box-shade));
+  transform-origin: 50% 100%;
+}
+
+[data-mk-cart-tape] {
+  position: absolute;
+  top: 0;
+  left: 50%;
+  width: 10px;
+  height: 100%;
+  margin-left: -5px;
+  border-radius: 0 0 2px 2px;
+  background: var(--mk-cart-tape);
+  opacity: 0.9;
+  transform-origin: 50% 0;
+}
+
+[data-mk-cart-flap] {
+  position: absolute;
+  top: 18%;
+  width: 50%;
+  height: 14%;
+  background: var(--mk-cart-box-shade);
+}
+
+[data-mk-cart-flap='left'] {
+  left: 0;
+  border-radius: 4px 0 0 2px;
+  transform-origin: 0 100%;
+}
+
+[data-mk-cart-flap='right'] {
+  right: 0;
+  border-radius: 0 4px 2px 0;
+  transform-origin: 100% 100%;
+}

package/src/components/add-to-cart/element.ts

@@ -0,0 +1,20 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createAddToCart, type AddToCartInstance } from './engine';
+
+/**
+ * <mk-add-to-cart class="mk-add-to-cart" target="#carrito"><button>Agregar</button></mk-add-to-cart>
+ * Packs the product's [data-mk-cart-image] and flies it to the cart. Emits mk:add and mk:land ({count}).
+ */
+export class MkAddToCartElement extends MkElement<AddToCartInstance> {
+  static options: Record<string, OptionType> = { target: 'string', image: 'string', quantity: 'number', count: 'number', label: 'string' };
+
+  protected create(options: Record<string, unknown>) {
+    return createAddToCart(this, options);
+  }
+
+  get count() {
+    return this.instance?.count ?? 0;
+  }
+}
+
+export const defineAddToCart = () => defineElement('mk-add-to-cart', MkAddToCartElement);