@yewdiel21/motion-kit 0.10.0 → 0.14.0

package/src/components/activity-feed/activity-feed.css

@@ -0,0 +1,239 @@
+/* activity-feed — day headings in small caps, entries on 12 px rows: a 2.25rem avatar (a picture, or initials on a hue
+   from the name) with a badge for the kind of action, the sentence, a quote on surface-3, a muted time. New entries
+   keep an accent-soft highlight that fades; the "novedades" pill sticks to the top. Give the root a max-height (or
+   --mk-af-height) to scroll inside it. */
+.mk-activity-feed,
+mk-activity-feed {
+  --mk-af-height: none;
+  --mk-af-avatar-l: 86%;
+  --mk-af-avatar-ink-l: 28%;
+  position: relative;
+  display: block;
+  max-height: var(--mk-af-height);
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  color: var(--mk-text);
+}
+
+@media (prefers-color-scheme: dark) {
+  :where(:root:not([data-mk-mode='light'])) :is(.mk-activity-feed, mk-activity-feed) {
+    --mk-af-avatar-l: 28%;
+    --mk-af-avatar-ink-l: 86%;
+  }
+}
+
+:where(:root[data-mk-mode='dark']) :is(.mk-activity-feed, mk-activity-feed) {
+  --mk-af-avatar-l: 28%;
+  --mk-af-avatar-ink-l: 86%;
+}
+
+[data-mk-af-new] {
+  position: sticky;
+  top: 0.5rem;
+  z-index: 2;
+  display: flex;
+  align-items: center;
+  gap: 0.15rem;
+  width: max-content;
+  height: 2rem;
+  margin: 0 auto 0.5rem;
+  padding: 0 0.9rem;
+  border: 0;
+  border-radius: 999px;
+  background: var(--mk-accent);
+  color: var(--mk-on-accent);
+  box-shadow: 0 8px 20px -8px color-mix(in srgb, var(--mk-shadow-color, #000) 45%, transparent);
+  font: inherit;
+  font-size: 0.8125rem;
+  font-weight: 600;
+  cursor: pointer;
+}
+
+[data-mk-af-new][hidden] {
+  display: none;
+}
+
+[data-mk-af-day] + [data-mk-af-day] {
+  margin-top: 1rem;
+}
+
+/* Section > heading: strong enough for a page's own h3 rules (a card's `.card h3`, say). */
+[data-mk-af-day] > [data-mk-af-heading] {
+  margin: 0 0 0.35rem;
+  padding: 0 0.5rem;
+  color: var(--mk-muted);
+  font-size: 0.75rem;
+  font-weight: 700;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+}
+
+[data-mk-af-day] ul {
+  display: grid;
+  gap: 0.15rem;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+[data-mk-af-item] {
+  display: grid;
+  grid-template-columns: 2.25rem minmax(0, 1fr);
+  gap: 0.75rem;
+  padding: 0.6rem 0.5rem;
+  border-radius: 12px;
+  outline: none;
+}
+
+[data-mk-af-item]:focus-visible {
+  box-shadow: inset 0 0 0 2px var(--mk-accent);
+}
+
+[data-mk-af-item][data-mk-fresh] {
+  animation: mk-af-fresh 2.4s ease-out both;
+}
+
+@keyframes mk-af-fresh {
+  from {
+    background: color-mix(in srgb, var(--mk-accent-soft) 90%, transparent);
+  }
+
+  to {
+    background: transparent;
+  }
+}
+
+[data-mk-af-avatar] {
+  position: relative;
+  display: grid;
+  place-items: center;
+  width: 2.25rem;
+  height: 2.25rem;
+  border-radius: 50%;
+  background: hsl(var(--mk-af-hue, 210) 55% var(--mk-af-avatar-l));
+  color: hsl(var(--mk-af-hue, 210) 50% var(--mk-af-avatar-ink-l));
+  font-size: 0.8125rem;
+  font-weight: 700;
+}
+
+[data-mk-af-avatar] img {
+  width: 100%;
+  height: 100%;
+  border-radius: 50%;
+  object-fit: cover;
+}
+
+[data-mk-af-badge] {
+  position: absolute;
+  right: -3px;
+  bottom: -3px;
+  display: grid;
+  place-items: center;
+  width: 1.05rem;
+  height: 1.05rem;
+  border-radius: 50%;
+  background: var(--mk-text);
+  color: var(--mk-surface-1, var(--mk-bg));
+  box-shadow: 0 0 0 2px var(--mk-surface-1, var(--mk-bg));
+}
+
+[data-mk-af-badge='comment'],
+[data-mk-af-badge='mention'] {
+  background: var(--mk-accent);
+  color: var(--mk-on-accent);
+}
+
+[data-mk-af-badge='complete'] {
+  background: #1f9d5b;
+  color: #fff;
+}
+
+[data-mk-af-badge='delete'] {
+  background: var(--mk-error, #c62828);
+  color: var(--mk-on-error, #fff);
+}
+
+[data-mk-af-line] {
+  margin: 0;
+  font-size: 0.9375rem;
+  line-height: 1.45;
+  overflow-wrap: anywhere;
+}
+
+[data-mk-af-line] b {
+  font-weight: 600;
+}
+
+[data-mk-af-target] {
+  color: inherit;
+  font-weight: 600;
+  text-decoration: underline;
+  text-decoration-color: color-mix(in srgb, currentColor 30%, transparent);
+  text-underline-offset: 3px;
+}
+
+a[data-mk-af-target]:hover {
+  text-decoration-color: currentColor;
+}
+
+[data-mk-af-detail] {
+  margin: 0.4rem 0 0;
+  padding: 0.5rem 0.75rem;
+  border-radius: 10px;
+  background: var(--mk-surface-3);
+  font-size: 0.875rem;
+  line-height: 1.5;
+  overflow-wrap: anywhere;
+}
+
+[data-mk-af-time] {
+  display: block;
+  margin-top: 0.2rem;
+  color: var(--mk-muted);
+  font-size: 0.75rem;
+}
+
+[data-mk-af-more] {
+  display: block;
+  height: 2.25rem;
+  margin: 0.75rem auto 0;
+  padding: 0 1rem;
+  border: 0;
+  border-radius: 10px;
+  background: var(--mk-surface-3);
+  color: var(--mk-text);
+  font: inherit;
+  font-size: 0.875rem;
+  font-weight: 600;
+  cursor: pointer;
+}
+
+[data-mk-af-more][hidden],
+[data-mk-af-empty][hidden] {
+  display: none;
+}
+
+[data-mk-af-more][aria-busy='true'] {
+  cursor: progress;
+  opacity: 0.7;
+}
+
+[data-mk-af-more]:focus-visible,
+[data-mk-af-new]:focus-visible {
+  outline: 2px solid var(--mk-accent);
+  outline-offset: 2px;
+}
+
+[data-mk-af-end],
+[data-mk-af-empty] {
+  margin: 0.75rem 0 0;
+  color: var(--mk-muted);
+  font-size: 0.875rem;
+  text-align: center;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-mk-af-item][data-mk-fresh] {
+    animation: none;
+  }
+}

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

@@ -0,0 +1,36 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createActivityFeed, type ActivityFeedInstance, type ActivityItem } from './engine';
+
+/**
+ * <mk-activity-feed class="mk-activity-feed" items='[{"id":"1","actor":"Ana Gómez","action":"comentó en","target":"Tarea 12","time":"2026-11-23T09:12","kind":"comment"}]'>
+ * </mk-activity-feed>. element.prepend([...]) / element.append([...]) for live and older activity.
+ */
+export class MkActivityFeedElement extends MkElement<ActivityFeedInstance> {
+  static options: Record<string, OptionType> = { items: 'json', locale: 'string', label: 'string', emptyLabel: 'string' };
+
+  protected create(options: Record<string, unknown>) {
+    return createActivityFeed(this, options);
+  }
+
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.instance) return;
+    if (name === 'items') {
+      try {
+        this.instance.setItems(JSON.parse(next ?? '[]') as ActivityItem[]);
+      } catch {
+        // Malformed JSON: keep the current entries.
+      }
+    } else super.attributeChangedCallback(name, previous, next);
+  }
+
+  /** New activity on top (not Element.prepend). */
+  prependItems(items: ActivityItem[]) {
+    this.instance?.prepend(items);
+  }
+
+  appendItems(items: ActivityItem[]) {
+    this.instance?.append(items);
+  }
+}
+
+export const defineActivityFeed = () => defineElement('mk-activity-feed', MkActivityFeedElement);

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/attachment/README.md

@@ -0,0 +1,27 @@
+# attachment
+
+Selector de archivos nativo con zona para arrastrar y soltar y una tarjeta por archivo (nombre, tipo, tamaño, progreso, estado y quitar). Valida `accept`, tamaño y cantidad; la subida pertenece a la app, que informa el progreso.
+
+```html
+<mk-attachment class="mk-attachment" accept="image/*,.pdf" multiple max-files="4" max-size="5242880"></mk-attachment>
+```
+
+```ts
+const attachment = createAttachment(root, {
+  accept: 'image/*,.pdf',
+  multiple: true,
+  maxFiles: 4,
+  maxSize: 5 * 1024 * 1024,
+  onFiles: (added) => added.forEach((file) => upload(file.file!, (pct) => attachment.setProgress(file.id, pct))),
+});
+```
+
+React: `<Attachment multiple accept=".pdf" onFiles={upload} uploads={{ [id]: { progress: 40 } }} />`, o `instanceRef` para llamar a la API.
+
+Opciones: `accept` (extensiones, MIME y `tipo/*`), `multiple`, `maxFiles` (sólo multiple), `maxSize` (bytes), `disabled`, `name`, `initialFiles` (metadatos `{id?, name, size, type, preview?, progress?, status?}`), `hint`, `labels`, `onFiles(added, files)`, `onRemove(file, files)`, `onReject(rejections)`. API: `addFiles(files)` (devuelve los aceptados), `remove(id)`, `setProgress(id, 0–100, status?)`, `clear()`, `files` (copias), `destroy()`.
+
+Eventos: `mk:files` `{added, files}`, `mk:remove` `{file, files}` y `mk:reject` `{file, code: 'type' | 'size' | 'count', message}` (uno por archivo). Los archivos válidos se conservan al añadir más; en modo simple el nuevo sustituye al anterior. Las vistas previas de imagen son object URLs que se revocan al quitar el archivo o al destruir. Los nombres se muestran siempre como texto.
+
+`disabled` desactiva selector, soltar y quitar (también `remove()`). Con `name` y `DataTransfer` disponible, el input lleva los archivos conservados para un envío nativo. Quitar un archivo deja el foco en el siguiente botón o en el selector. `destroy()` elimina lo creado y restaura atributos. El custom element expone `addFiles`, `removeFile(id)` (`remove()` sigue siendo el de `HTMLElement`), `setProgress` y `files`, y conserva los archivos al cambiar un atributo.
+
+Variables: `--mk-attachment-radius`, `--mk-attachment-accent`. Movimiento reducido elimina escalas y entradas.