@yewdiel21/motion-kit 0.16.0 → 0.18.0

package/src/components/notification-stack/engine.ts

@@ -0,0 +1,329 @@
+import { gsap, EASE, registerMotion } from '../../core/gsap';
+import { createScope } from '../../core/scope';
+import { reduced } from '../../core/reduced';
+import { inert, type Instance } from '../../core/types';
+import { blurIn, press, rollDigits } from '../../motion/micro';
+
+export interface NotificationStackItem {
+  id: string;
+  title: string;
+  description?: string;
+  tone?: 'neutral' | 'success' | 'error' | 'info';
+  /** Milliseconds; zero keeps the notification until dismissed. */
+  duration?: number;
+  dismissible?: boolean;
+  action?: { label: string; onClick?: () => void };
+}
+export type NotificationStackDirection = 'down' | 'up' | 'side';
+export interface NotificationStackOptions {
+  items?: NotificationStackItem[];
+  expanded?: boolean;
+  /** Where the deck opens: below its front card (default), above it, or into a sideways strip. */
+  direction?: NotificationStackDirection;
+  duration?: number;
+  disabled?: boolean;
+  label?: string;
+  labels?: { expand?: string; collapse?: string; dismiss?: string; empty?: string };
+  onDismiss?: (id: string) => void;
+  onAction?: (id: string) => void;
+  onExpandedChange?: (expanded: boolean) => void;
+}
+export interface NotificationStackInstance extends Instance {
+  push(item: NotificationStackItem): void;
+  dismiss(id: string): void;
+  clear(): void;
+  expand(): void;
+  collapse(): void;
+  toggle(): void;
+  setOptions(options: Partial<NotificationStackOptions>): void;
+  readonly items: readonly NotificationStackItem[];
+  readonly expanded: boolean;
+}
+interface Entry { item: NotificationStackItem; card: HTMLElement; remaining: number; started: number; timer?: ReturnType<typeof setTimeout>; }
+let sequence = 0;
+
+/** An isolated notification deck. It deliberately does not subscribe to the global toast store. */
+export function createNotificationStack(root: HTMLElement | null, options: NotificationStackOptions = {}): NotificationStackInstance {
+  if (!root) return inert({ push() {}, dismiss() {}, clear() {}, expand() {}, collapse() {}, toggle() {}, setOptions() {}, items: [], expanded: false });
+  registerMotion();
+  const scope = createScope();
+  let opts = { ...options };
+  let expanded = options.expanded ?? false;
+  let hovered = false;
+  let focused = false;
+  let inviting = false;
+  let resize: ResizeObserver | null = null;
+  const heights = new WeakMap<HTMLElement, number>();
+  const original = [...root.childNodes];
+  const entries = new Map<string, Entry>();
+  const animations = new Set<gsap.core.Animation>();
+  const track = (animation: gsap.core.Animation | null) => {
+    // Keep an active set rather than retaining every dismissed card's timeline.
+    for (const prior of animations) if (prior.totalProgress() === 1 || !prior.parent) animations.delete(prior);
+    if (animation) animations.add(animation);
+  };
+  const deck = document.createElement('div');
+  deck.className = 'mk-notification-stack__deck';
+  deck.id = `mk-notifications-${++sequence}`;
+  const empty = document.createElement('p');
+  empty.className = 'mk-notification-stack__empty';
+  const toggle = document.createElement('button');
+  toggle.type = 'button';
+  toggle.className = 'mk-notification-stack__toggle';
+  toggle.setAttribute('aria-controls', deck.id);
+  const count = document.createElement('span');
+  const toggleText = document.createElement('span');
+  const chevron = document.createElement('span');
+  chevron.className = 'mk-notification-stack__chevron';
+  chevron.setAttribute('aria-hidden', 'true');
+  chevron.innerHTML = '<svg viewBox="0 0 16 16"><path d="m4 6 4 4 4-4"/></svg>';
+  toggle.append(count, toggleText, chevron);
+  const live = document.createElement('span');
+  live.className = 'mk-sr-only';
+  live.setAttribute('role', 'status');
+  live.setAttribute('aria-live', 'polite');
+  root.replaceChildren(deck, empty, toggle, live);
+  scope.attr(root, 'class', `${root.className} mk-notification-stack`.trim());
+  scope.attr(root, 'data-mk-ready', '');
+  scope.attr(root, 'role', 'region');
+  const pause = (entry: Entry) => {
+    if (entry.timer !== undefined) {
+      clearTimeout(entry.timer);
+      entry.timer = undefined;
+      entry.remaining = Math.max(0, entry.remaining - (Date.now() - entry.started));
+    }
+  };
+  const paused = () => hovered || focused || opts.disabled || document.hidden;
+  const start = (entry: Entry) => {
+    if (paused() || entry.remaining === Infinity || entry.timer !== undefined) return;
+    entry.started = Date.now();
+    entry.timer = setTimeout(() => dismiss(entry.item.id), entry.remaining);
+  };
+  const syncTimers = () => entries.forEach((entry) => paused() ? pause(entry) : start(entry));
+  const duration = (item: NotificationStackItem) => {
+    const ms = item.duration ?? opts.duration ?? 6000;
+    return Number.isFinite(ms) && ms > 0 ? ms : Infinity;
+  };
+  // `motion` marks an explicit open/close: the deck fans out card by card, newly
+  // revealed cards clear their blur and their content follows the same cadence.
+  const layout = (motion?: 'expand' | 'collapse') => {
+    if (scope.disposed) return;
+    const cards = [...entries.values()].reverse();
+    const direction: NotificationStackDirection = opts.direction === 'up' || opts.direction === 'side' ? opts.direction : 'down';
+    // Set first: the direction changes card anchoring and width before they are measured.
+    scope.attr(root, 'data-mk-direction', direction);
+    scope.attr(root, 'data-mk-expandable', !expanded && cards.length > 1 && !opts.disabled ? '' : null);
+    // Hovering a closed deck spreads its peeks a little, inviting the click that opens it.
+    const peek = inviting && !expanded && !reduced() ? 18 : 12;
+    cards.forEach((entry, index) => {
+      const visible = expanded || index === 0;
+      // Covered cards are decorative peeks; their controls are never focusable.
+      entry.card.inert = !visible || !!opts.disabled;
+      entry.card.setAttribute('aria-hidden', String(!visible));
+      entry.card.toggleAttribute('data-mk-peek', !visible);
+    });
+    // Peeks take the front card's outline, so only their surface shows beneath it.
+    if (cards[0]) deck.style.setProperty('--mk-stack-front', `${cards[0].card.offsetHeight}px`);
+    let offset = 0;
+    let tallest = 0;
+    cards.forEach((entry, index) => {
+      entry.card.style.zIndex = String(cards.length - index);
+      const layer = Math.min(index, 3);
+      let x = 0, y = 0;
+      if (expanded) {
+        if (direction === 'side') x = offset; else y = direction === 'up' ? -offset : offset;
+        offset += direction === 'side' ? entry.card.offsetWidth + 12 : entry.card.offsetHeight + 8;
+      } else if (direction === 'side') x = layer * peek;
+      else y = (direction === 'up' ? -1 : 1) * layer * peek;
+      tallest = Math.max(tallest, entry.card.offsetHeight);
+      const delay = reduced() ? 0 : motion === 'expand' ? index * .05 : motion === 'collapse' ? Math.max(0, cards.length - 1 - index) * .03 : 0;
+      entry.card.style.setProperty('--mk-stack-delay', `${delay}s`);
+      track(gsap.to(entry.card, { x, y, scale: expanded ? 1 : Math.max(.84, 1 - index * .045), opacity: expanded || index < 3 ? 1 : 0, duration: reduced() ? 0 : .45, delay, ease: EASE.swatch, overwrite: 'auto' }));
+      if (motion === 'expand' && index > 0 && !reduced()) track(gsap.fromTo(entry.card, { filter: 'blur(6px)' }, { filter: 'blur(0px)', duration: .4, delay, ease: 'power2.out', clearProps: 'filter' }));
+    });
+    const front = cards[0]?.card.offsetHeight || 100;
+    const height = !cards.length ? 0 : direction === 'side' ? expanded ? tallest : front : expanded ? offset - 8 : front + Math.min(cards.length - 1, 2) * peek;
+    if (!expanded && direction === 'side' && deck.scrollLeft) deck.scrollTo({ left: 0, behavior: reduced() ? 'auto' : 'smooth' });
+    track(gsap.to(deck, { height, duration: reduced() ? 0 : .4, ease: EASE.signature, overwrite: 'auto' }));
+    empty.hidden = cards.length > 0;
+    empty.textContent = opts.labels?.empty ?? 'Todo al día. No hay notificaciones.';
+    toggle.hidden = cards.length < 2;
+    toggle.disabled = !!opts.disabled;
+    toggle.setAttribute('aria-expanded', String(expanded));
+    const toggleLabel = expanded ? opts.labels?.collapse ?? 'Recoger' : opts.labels?.expand ?? 'Ver todas';
+    if (toggleText.textContent !== toggleLabel) {
+      toggleText.textContent = toggleLabel;
+      if (motion) track(blurIn(toggleText, { from: 'soft', duration: .25 }));
+    }
+    track(rollDigits(count, String(cards.length)));
+    scope.attr(root, 'aria-label', opts.label ?? 'Notificaciones');
+    scope.attr(root, 'data-mk-expanded', String(expanded));
+    scope.attr(root, 'data-mk-disabled', opts.disabled ? '' : null);
+  };
+  const dismiss = (id: string) => {
+    if (scope.disposed || opts.disabled) return;
+    const entry = entries.get(id);
+    if (!entry) return;
+    pause(entry);
+    resize?.unobserve(entry.card);
+    const hadFocus = entry.card.contains(document.activeElement);
+    entries.delete(id);
+    if (hadFocus) {
+      const next = [...entries.values()].reverse()[0];
+      const target = next?.card.querySelector<HTMLButtonElement>('button');
+      if (target) { next!.card.inert = false; target.focus(); }
+      else { root.setAttribute('tabindex', '-1'); root.focus(); }
+    }
+    gsap.killTweensOf(entry.card);
+    entry.card.inert = true;
+    entry.card.setAttribute('aria-hidden', 'true');
+    if (reduced()) entry.card.remove();
+    else track(gsap.to(entry.card, { y: '-=18', scale: .94, opacity: 0, filter: 'blur(8px)', duration: .23, ease: EASE.close, onComplete: () => entry.card.remove() }));
+    layout();
+    opts.onDismiss?.(id);
+    root.dispatchEvent(new CustomEvent('mk:dismiss', { bubbles: true, detail: { id } }));
+  };
+  const build = (item: NotificationStackItem): Entry => {
+    const card = document.createElement('article');
+    card.className = 'mk-notification-stack__card';
+    card.dataset.mkNotification = item.id;
+    card.dataset.mkTone = item.tone ?? 'neutral';
+    const mark = document.createElement('span');
+    mark.className = 'mk-notification-stack__mark';
+    mark.setAttribute('aria-hidden', 'true');
+    mark.textContent = item.tone === 'success' ? '✓' : item.tone === 'error' ? '!' : '↗';
+    const body = document.createElement('div');
+    body.className = 'mk-notification-stack__body';
+    const title = document.createElement('strong');
+    title.textContent = item.title;
+    body.append(title);
+    if (item.description) { const description = document.createElement('p'); description.textContent = item.description; body.append(description); }
+    if (item.action) {
+      const action = document.createElement('button');
+      action.type = 'button';
+      action.className = 'mk-notification-stack__action';
+      action.dataset.mkNotificationAction = item.id;
+      action.textContent = item.action.label;
+      action.disabled = !!opts.disabled;
+      body.append(action);
+    }
+    card.append(mark, body);
+    if (item.dismissible !== false) {
+      const close = document.createElement('button');
+      close.type = 'button';
+      close.className = 'mk-notification-stack__dismiss';
+      close.dataset.mkNotificationDismiss = item.id;
+      close.setAttribute('aria-label', `${opts.labels?.dismiss ?? 'Cerrar'}: ${item.title}`);
+      close.textContent = '×';
+      close.disabled = !!opts.disabled;
+      card.append(close);
+    }
+    return { item: { ...item }, card, remaining: duration(item), started: 0 };
+  };
+  const push = (item: NotificationStackItem) => {
+    if (scope.disposed || !item.id || entries.has(item.id)) return;
+    const entry = build(item);
+    entries.set(item.id, entry);
+    deck.append(entry.card);
+    resize?.observe(entry.card);
+    layout();
+    track(blurIn(entry.card, { from: 'pop', duration: .35 }));
+    live.textContent = `${item.title}${item.description ? `. ${item.description}` : ''}`;
+    start(entry);
+  };
+  const setExpanded = (next: boolean, notify = true, allowDisabled = false) => {
+    if (scope.disposed || expanded === next || (opts.disabled && !allowDisabled)) return;
+    // Collapsing while a covered card owns focus returns to the disclosure.
+    if (!next && [...entries.values()].slice(0, -1).some((entry) => entry.card.contains(document.activeElement))) {
+      if (opts.disabled) { root.tabIndex = -1; root.focus(); }
+      else toggle.focus();
+    }
+    expanded = next;
+    layout(next ? 'expand' : 'collapse');
+    if (notify) {
+      opts.onExpandedChange?.(expanded);
+      root.dispatchEvent(new CustomEvent('mk:change', { bubbles: true, detail: { expanded } }));
+    }
+  };
+  scope.attr(root, 'tabindex', root.getAttribute('tabindex'));
+  scope.on(root, 'pointerenter', () => { hovered = true; syncTimers(); });
+  scope.on(root, 'pointerleave', () => { hovered = false; syncTimers(); });
+  scope.on(root, 'focusin', () => { focused = true; syncTimers(); });
+  scope.on(root, 'focusout', (event) => { focused = root.contains(event.relatedTarget as Node | null); syncTimers(); });
+  scope.on(document, 'visibilitychange', syncTimers);
+  scope.on(deck, 'pointerenter', () => { inviting = true; if (!expanded && entries.size > 1) layout(); });
+  scope.on(deck, 'pointerleave', () => { inviting = false; if (!expanded && entries.size > 1) layout(); });
+  scope.on(root, 'click', (event) => {
+    if (opts.disabled) return;
+    // The closed deck is itself a way in; the toggle stays the keyboard path.
+    if (!expanded && entries.size > 1 && deck.contains(event.target as Node) && !(event.target as Element).closest('button')) { setExpanded(true); return; }
+    const button = (event.target as Element).closest<HTMLButtonElement>('button');
+    if (!button || !root.contains(button) || button.disabled) return;
+    track(press(button));
+    if (button === toggle) setExpanded(!expanded);
+    else if (button.dataset.mkNotificationDismiss) dismiss(button.dataset.mkNotificationDismiss);
+    else if (button.dataset.mkNotificationAction) {
+      const id = button.dataset.mkNotificationAction;
+      entries.get(id)?.item.action?.onClick?.();
+      opts.onAction?.(id);
+      dismiss(id);
+    }
+  });
+  if (typeof ResizeObserver === 'function') {
+    resize = scope.observe(new ResizeObserver((records) => {
+      let changed = false;
+      for (const record of records) {
+        const card = record.target as HTMLElement;
+        if (heights.get(card) !== card.offsetHeight) { heights.set(card, card.offsetHeight); changed = true; }
+      }
+      if (changed) layout();
+    }));
+  }
+  // Card heights, rather than deck height, trigger reflow on responsive changes.
+  scope.on(window, 'resize', () => layout(), { passive: true });
+  const setOptions = (next: Partial<NotificationStackOptions>) => {
+    if (scope.disposed) return;
+    opts = { ...opts, ...next };
+    if (next.items) {
+      const ids = new Set(next.items.map((item) => item.id));
+      for (const [id, entry] of entries) if (!ids.has(id)) {
+        pause(entry);
+        resize?.unobserve(entry.card);
+        if (entry.card.contains(document.activeElement)) { root.setAttribute('tabindex', '-1'); root.focus(); }
+        gsap.killTweensOf(entry.card); entry.card.remove(); entries.delete(id);
+      }
+      for (const item of next.items) {
+        const existing = entries.get(item.id);
+        if (!existing) { push(item); continue; }
+        // Updating copy preserves the remaining lifetime of a notification.
+        const replacement = build(item);
+        if (existing.card.contains(document.activeElement)) { root.setAttribute('tabindex', '-1'); root.focus(); }
+        pause(existing);
+        replacement.remaining = existing.remaining;
+        existing.card.replaceWith(replacement.card);
+        gsap.killTweensOf(existing.card);
+        entries.set(item.id, replacement);
+        resize?.unobserve(existing.card);
+        resize?.observe(replacement.card);
+      }
+      const ordered = next.items.map((item) => entries.get(item.id)).filter((entry): entry is Entry => !!entry);
+      entries.clear();
+      for (const entry of ordered) { entries.set(entry.item.id, entry); deck.append(entry.card); }
+    }
+    if (next.expanded !== undefined) setExpanded(next.expanded, false, true);
+    for (const entry of entries.values()) entry.card.querySelectorAll<HTMLButtonElement>('button').forEach((button) => {
+      button.disabled = !!opts.disabled;
+      if (button.hasAttribute('data-mk-notification-dismiss')) button.setAttribute('aria-label', `${opts.labels?.dismiss ?? 'Cerrar'}: ${entry.item.title}`);
+    });
+    layout(); syncTimers();
+  };
+  for (const item of options.items ?? []) push(item);
+  layout();
+  return {
+    push, dismiss, clear() { for (const id of [...entries.keys()]) dismiss(id); },
+    expand: () => setExpanded(true), collapse: () => setExpanded(false), toggle: () => setExpanded(!expanded), setOptions,
+    get items() { return [...entries.values()].map((entry) => ({ ...entry.item })); },
+    get expanded() { return expanded; },
+    destroy() { if (scope.disposed) return; entries.forEach(pause); animations.forEach((animation) => animation.kill()); gsap.killTweensOf([...root.querySelectorAll('*')]); scope.dispose(); root.replaceChildren(...original); },
+  };
+}

package/src/components/notification-stack/notification-stack.css

@@ -0,0 +1,41 @@
+.mk-notification-stack, mk-notification-stack { display: block; width: min(100%, 400px); color: var(--mk-text); font-family: var(--mk-font); }
+.mk-notification-stack__deck { position: relative; width: 100%; perspective: 900px; }
+.mk-notification-stack__card { box-sizing: border-box; position: absolute; inset: 0 0 auto; display: flex; align-items: flex-start; gap: 12px; padding: 20px; min-height: 100px; border-radius: 24px; background: var(--mk-surface-2); box-shadow: 0 1px 0 var(--mk-outline-soft) inset, 0 12px 24px -20px var(--mk-shadow-color, rgb(0 0 0 / .4)); transform-origin: center top; }
+.mk-notification-stack__body { min-width: 0; flex: 1; }
+.mk-notification-stack__card > * { transition: opacity .25s ease var(--mk-stack-delay, 0s); }
+.mk-notification-stack__card[data-mk-peek] { max-height: var(--mk-stack-front, 100px); overflow: hidden; }
+.mk-notification-stack__card[data-mk-peek] > * { opacity: 0; }
+.mk-notification-stack__body strong { display: block; font-size: 14px; font-weight: 600; line-height: 1.4; }
+.mk-notification-stack__body p { margin: 4px 0 0; color: var(--mk-muted); font-size: 12px; line-height: 1.5; overflow-wrap: anywhere; }
+.mk-notification-stack__mark { flex-shrink: 0; display: grid; place-items: center; width: 32px; height: 32px; border-radius: 12px; background: var(--mk-surface-3, var(--mk-surface)); font-size: 16px; }
+.mk-notification-stack__card[data-mk-tone=success] .mk-notification-stack__mark { background: var(--mk-accent-soft); color: var(--mk-on-accent-soft); }
+.mk-notification-stack__card[data-mk-tone=error] .mk-notification-stack__mark { background: color-mix(in srgb, var(--mk-error, #b3261e) 12%, var(--mk-surface-2)); color: var(--mk-error, #b3261e); }
+.mk-notification-stack button { border: 0; color: inherit; font: inherit; cursor: pointer; -webkit-tap-highlight-color: transparent; }
+.mk-notification-stack__dismiss { flex-shrink: 0; display: grid; place-items: center; width: 32px; height: 32px; margin: -6px -6px 0 0; border-radius: 64px; background: transparent; font-size: 20px !important; }
+.mk-notification-stack__action { margin-top: 10px; min-height: 32px; padding: 6px 12px; border-radius: 64px; background: var(--mk-surface-3, var(--mk-surface)); font-size: 12px !important; font-weight: 600 !important; }
+.mk-notification-stack__toggle { display: flex; align-items: center; gap: 8px; min-height: 36px; margin: 16px auto 0; padding: 6px 14px; border-radius: 64px; background: var(--mk-surface); font-size: 12px !important; transition: background .2s, padding .4s var(--mk-ease-swatch); }
+.mk-notification-stack__toggle > span:first-child { min-width: 20px; font-variant-numeric: tabular-nums; }
+.mk-notification-stack__chevron { display: grid; place-items: center; width: 16px; height: 16px; transition: rotate .45s var(--mk-ease-swatch); }
+.mk-notification-stack__chevron svg { width: 16px; height: 16px; fill: none; stroke: currentColor; stroke-width: 1.6; stroke-linecap: round; stroke-linejoin: round; }
+.mk-notification-stack[data-mk-expanded='true'] .mk-notification-stack__chevron { rotate: 180deg; }
+.mk-notification-stack__empty { padding: 24px; margin: 0; border-radius: 24px; background: var(--mk-surface); text-align: center; font-size: 13px; color: var(--mk-muted); }
+.mk-notification-stack [hidden] { display: none !important; }
+/* A closed deck with more than one card opens on click. */
+.mk-notification-stack[data-mk-expandable] .mk-notification-stack__deck { cursor: pointer; }
+/* Up: cards rest on the deck's floor and rise above the front one; the disclosure sits on top. */
+.mk-notification-stack[data-mk-direction='up'] { display: flex; flex-direction: column-reverse; }
+.mk-notification-stack[data-mk-direction='up'] .mk-notification-stack__card { inset: auto 0 0; transform-origin: center bottom; }
+.mk-notification-stack[data-mk-direction='up'] .mk-notification-stack__toggle { margin: 0 auto 16px; }
+.mk-notification-stack[data-mk-direction='up'] .mk-notification-stack__chevron { rotate: 180deg; }
+.mk-notification-stack[data-mk-direction='up'][data-mk-expanded='true'] .mk-notification-stack__chevron { rotate: 0deg; }
+/* Side: peeks show at the right edge; open, the cards become a strip that scrolls sideways. */
+.mk-notification-stack[data-mk-direction='side'] .mk-notification-stack__card { right: auto; width: min(86%, 340px); transform-origin: right center; }
+.mk-notification-stack[data-mk-direction='side'][data-mk-expanded='true'] .mk-notification-stack__deck { overflow-x: auto; overflow-y: hidden; overscroll-behavior-x: contain; scrollbar-width: none; }
+.mk-notification-stack[data-mk-direction='side'][data-mk-expanded='true'] .mk-notification-stack__deck::-webkit-scrollbar { display: none; }
+.mk-notification-stack[data-mk-direction='side'] .mk-notification-stack__chevron { rotate: -90deg; }
+.mk-notification-stack[data-mk-direction='side'][data-mk-expanded='true'] .mk-notification-stack__chevron { rotate: 90deg; }
+.mk-notification-stack button:focus-visible { outline: 2px solid var(--mk-accent); outline-offset: 3px; }
+.mk-notification-stack button:disabled { opacity: .4; cursor: not-allowed; }
+@media (hover: hover) { .mk-notification-stack button:not(:disabled):hover { background: var(--mk-surface-3, var(--mk-surface)); } .mk-notification-stack__toggle:not(:disabled):hover { padding-inline: 18px; } }
+@media (max-width: 480px) { .mk-notification-stack__card { padding: 16px; gap: 10px; } }
+@media (prefers-reduced-motion: reduce) { .mk-notification-stack * { transition: none !important; } }

package/src/components/notification-stack/react.tsx

@@ -0,0 +1,28 @@
+'use client';
+import { useRef, type HTMLAttributes, type MutableRefObject } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createNotificationStack, type NotificationStackOptions, type NotificationStackInstance } from './engine';
+
+export interface NotificationStackProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'children' | 'dangerouslySetInnerHTML'>, NotificationStackOptions {
+  instanceRef?: MutableRefObject<NotificationStackInstance | null>;
+  children?: never;
+  dangerouslySetInnerHTML?: never;
+}
+export function NotificationStack({ items, expanded, direction, duration, disabled, label, labels, onDismiss, onAction, onExpandedChange, instanceRef, className, children, dangerouslySetInnerHTML: _html, ...props }: NotificationStackProps) {
+  const root = useRef<HTMLDivElement>(null);
+  const instance = useRef<NotificationStackInstance | null>(null);
+  const onDismissRef = useLatest(onDismiss);
+  const onActionRef = useLatest(onAction);
+  const onExpandedChangeRef = useLatest(onExpandedChange);
+  useIsomorphicLayoutEffect(() => {
+    const created = createNotificationStack(root.current, { items, expanded, direction, duration, disabled, label, labels, onDismiss: (...args) => onDismissRef.current?.(...args), onAction: (...args) => onActionRef.current?.(...args), onExpandedChange: (...args) => onExpandedChangeRef.current?.(...args) });
+    instance.current = created;
+    return () => { created.destroy(); instance.current = null; };
+    // Options update the existing engine so timers, selection and scroll state survive.
+  }, []);
+  useIsomorphicLayoutEffect(() => {
+    instance.current?.setOptions({ items, expanded, direction, duration, disabled, label, labels });
+  }, [items, expanded, direction, duration, disabled, label, labels]);
+  useIsomorphicLayoutEffect(() => { if (instanceRef) instanceRef.current = instance.current; return () => { if (instanceRef) instanceRef.current = null; }; }, [instanceRef]);
+  return <div {...props} ref={root} className={['mk-notification-stack', className].filter(Boolean).join(' ')}></div>;
+}

package/src/components/particle-button/README.md

@@ -0,0 +1,26 @@
+# Particle button
+
+Botón tonal con una explosión breve de puntos al activarlo. Reutiliza `press` y `burst` del kit; las partículas salen desde el botón y desaparecen. Mantiene una sola explosión durante activaciones rápidas, con un máximo de 32 puntos. No hay efectos en reposo.
+
+```ts
+import { createParticleButton } from '@yewdiel21/motion-kit';
+import '@yewdiel21/motion-kit/css/particle-button';
+const effect = createParticleButton(document.querySelector('#done'), {
+  onAction: () => completeLocalStep(),
+});
+// effect.burst(); effect.destroy();
+```
+
+`ParticleButtonOptions`: `label` (Celebrar, solo si el botón no tiene contenido propio), `count` (9 pares, limitado a 3–16), `distance` (52px, limitado a 12–100), `onAction`. `ParticleButtonInstance`: `burst()`, `destroy()`. Emite `mk:action` en una activación. El factory admite un botón o un host con botón; si falta, crea un botón nativo. Conserva el `type` proporcionado; por defecto es `button`. Respeta `disabled`/`aria-disabled`; el motor no ejecuta operaciones de red ni altera formularios.
+
+```tsx
+<ParticleButton label="Completar un paso" onAction={completeLocalStep} />
+```
+
+`ParticleButtonProps` añade atributos de botón e `instanceRef`. El contenido se proporciona con `label`: los hijos y `dangerouslySetInnerHTML` se filtran porque el motor administra el DOM. Un cambio de `instanceRef` limpia el anterior.
+
+```html
+<mk-particle-button label="Celebrar"></mk-particle-button>
+```
+
+`defineParticleButton()` registra `MkParticleButtonElement`; atributos `label`, `count`, `distance`. También acepta un botón escrito a mano como hijo y restaura su contenido al destruirse. Movimiento reducido mantiene la acción y suprime la explosión y la pulsación. `destroy()` elimina partículas, animaciones, eventos y los nodos creados, y restaura estilos originales.

package/src/components/particle-button/element.ts

@@ -0,0 +1,13 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createParticleButton, type ParticleButtonInstance } from './engine';
+
+export class MkParticleButtonElement extends MkElement<ParticleButtonInstance> {
+  static options: Record<string, OptionType> = { label: 'string', count: 'number', distance: 'number' };
+  protected create(options: Record<string, unknown>) { return createParticleButton(this, options); }
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    const focused = this.contains(document.activeElement);
+    super.attributeChangedCallback(name, previous, next);
+    if (focused) this.querySelector<HTMLButtonElement>('button')?.focus({ preventScroll: true });
+  }
+}
+export const defineParticleButton = () => defineElement('mk-particle-button', MkParticleButtonElement);

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

@@ -0,0 +1,52 @@
+import { gsap, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { burst, press } from '../../motion/micro';
+
+export interface ParticleButtonOptions {
+  /** Used only when the control has no authored content. */
+  label?: string;
+  /** Number of particle pairs, clamped to 3–16. */
+  count?: number;
+  distance?: number;
+  onAction?: () => void;
+}
+export interface ParticleButtonInstance extends Instance { burst(): void; }
+
+export function createParticleButton(root: HTMLElement | null, options: ParticleButtonOptions = {}): ParticleButtonInstance {
+  if (!root) return inert({ burst() {} });
+  registerMotion();
+  const scope = createScope();
+  let button = root.matches('button') ? root as HTMLButtonElement : root.querySelector<HTMLButtonElement>('button');
+  if (!button) { button = document.createElement('button'); root.append(button); const made = button; scope.add(() => made.remove()); }
+  const control = button;
+  if (!control.textContent?.trim() && !control.querySelector('[aria-label], svg, img')) {
+    const name = document.createElement('span'); name.textContent = options.label ?? 'Celebrar'; control.append(name); scope.add(() => name.remove());
+  }
+  const originalStyle = control.getAttribute('style');
+  const originalTransform = control.style.transform;
+  scope.add(() => { if (originalStyle === null) control.removeAttribute('style'); else control.setAttribute('style', originalStyle); });
+  scope.attr(control, 'type', control.getAttribute('type') ?? 'button');
+  scope.attr(control, 'data-mk-particle-button', '');
+  scope.attr(root, 'data-mk-ready', '');
+  const count = Number.isFinite(options.count) ? Math.min(16, Math.max(3, Math.round(options.count!))) : 9;
+  const distance = Number.isFinite(options.distance) ? Math.min(100, Math.max(12, options.distance!)) : 52;
+  let particles: gsap.core.Animation | null = null;
+  let pressing: gsap.core.Animation | null = null;
+  const fire = () => {
+    if (scope.disposed || control.disabled || control.getAttribute('aria-disabled') === 'true') return;
+    particles?.kill();
+    particles = reduced() ? null : burst(control, { count, distance, ring: false, size: 5, colors: ['var(--mk-text)', 'var(--mk-accent)'] });
+  };
+  scope.on(control, 'click', (event) => {
+    if (control.disabled || control.getAttribute('aria-disabled') === 'true') { event.preventDefault(); return; }
+    pressing?.kill(); pressing = press(control);
+    pressing?.eventCallback('onComplete', () => { gsap.set(control, { clearProps: 'transform,scale' }); control.style.transform = originalTransform; if (!control.getAttribute('style')) control.removeAttribute('style'); });
+    fire();
+    options.onAction?.();
+    root.dispatchEvent(new CustomEvent('mk:action', { bubbles: true }));
+  });
+  scope.add(() => { particles?.kill(); pressing?.kill(); });
+  return { burst: fire, destroy: () => scope.dispose() };
+}

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

@@ -0,0 +1,13 @@
+.mk-particle-button,
+mk-particle-button { display: inline-flex; overflow: visible; }
+[data-mk-particle-button] {
+  position: relative; isolation: isolate; display: inline-flex; align-items: center; justify-content: center; gap: .6rem;
+  min-height: 48px; padding: .8rem 1.45rem; border: 1px solid var(--mk-outline-soft); border-radius: 16px;
+  background: var(--mk-surface-3); color: var(--mk-text); font: 500 .9375rem var(--mk-font); cursor: pointer;
+  transition: background 160ms, border-radius 320ms var(--mk-ease-swatch);
+}
+[data-mk-particle-button]:hover:not(:disabled) { background: var(--mk-surface-4); border-radius: 24px; }
+[data-mk-particle-button]:focus-visible { outline: 2px solid var(--mk-accent); outline-offset: 4px; }
+[data-mk-particle-button]:disabled,
+[data-mk-particle-button][aria-disabled='true'] { opacity: .4; cursor: not-allowed; }
+@media (prefers-reduced-motion: reduce) { [data-mk-particle-button] { transition: none; } }

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

@@ -0,0 +1,22 @@
+'use client';
+import { useRef, type ButtonHTMLAttributes, type Ref } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createParticleButton, type ParticleButtonInstance, type ParticleButtonOptions } from './engine';
+
+export interface ParticleButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children' | 'dangerouslySetInnerHTML'>, ParticleButtonOptions { instanceRef?: Ref<ParticleButtonInstance>; }
+export function ParticleButton({ label = 'Celebrar', count, distance, onAction, instanceRef, type = 'button', className, ...props }: ParticleButtonProps) {
+  const { children: _children, dangerouslySetInnerHTML: _html, ...safe } = props as ButtonHTMLAttributes<HTMLButtonElement>;
+  const root = useRef<HTMLButtonElement>(null);
+  const instance = useRef<ParticleButtonInstance | null>(null);
+  const action = useLatest(onAction);
+  useIsomorphicLayoutEffect(() => {
+    const created = createParticleButton(root.current, { label, count, distance, onAction: () => action.current?.() });
+    instance.current = created;
+    return () => { created.destroy(); instance.current = null; };
+  }, [label, count, distance]);
+  useIsomorphicLayoutEffect(() => {
+    if (typeof instanceRef === 'function') instanceRef(instance.current); else if (instanceRef) instanceRef.current = instance.current;
+    return () => { if (typeof instanceRef === 'function') instanceRef(null); else if (instanceRef) instanceRef.current = null; };
+  }, [instanceRef, label, count, distance]);
+  return <button {...safe} type={type} ref={root} className={['mk-particle-button', className].filter(Boolean).join(' ')} />;
+}

package/src/components/radio-group/README.md

@@ -0,0 +1,43 @@
+# RadioGroup
+
+Opciones nativas con selección tonal: píldoras, tarjetas descriptivas y filas de ajustes. El radio del elemento elegido cambia a una cápsula; la marca entra con swatch y cada pulsación responde con press.
+
+```ts
+import { createRadioGroup } from '@yewdiel21/motion-kit';
+import '@yewdiel21/motion-kit/css/radio-group';
+
+const control = createRadioGroup(document.querySelector('.mk-radio-group'), {
+  items: [{value: 'weekly', label: 'Semanal'}, {value: 'monthly', label: 'Mensual', description: 'Un resumen al mes'}],
+  value: 'weekly', name: 'frequency', variant: 'card', onChange: console.log,
+});
+control.setValue('monthly');
+```
+
+## Opciones y contrato
+
+`items: { value, label, description?, disabled? }[]`, `variant: pill | card | list` (pill), `value` / `defaultValue` (null), `name`, `label`, `required`, `disabled`, `error`, `onChange(value)`.
+
+Un valor desconocido o null limpia la selección. Los valores duplicados de items se omiten. Las opciones disabled conservan su semántica nativa y no se pueden elegir con el usuario. El grupo vacío explica que no hay opciones.
+
+La instancia expone `value: string | null`, `setValue(value, notify = false)`, `reset(notify = false)` y `destroy()`. Las escrituras imperativas actualizan el control incluso estando disabled. `setValue` no cambia el valor inicial al que vuelve reset. Las notificaciones usan callbacks y eventos `mk:change` con `detail: { value }`.
+
+## React y HTML
+
+```tsx
+import { RadioGroup } from '@yewdiel21/motion-kit/react';
+
+<RadioGroup items={items} value={frequency} onChange={setFrequency} name="frequency" variant="pill" />
+```
+
+`value` controla la instancia; `defaultValue` inicia una instancia que conserva sus propios cambios. Las opciones pueden cambiar sin perder la selección no controlada. `instanceRef` recibe la instancia y admite cambiar de objeto ref. Los children y dangerouslySetInnerHTML no se pasan al host porque el motor posee ese DOM.
+
+```html
+<mk-radio-group class="mk-radio-group" items='[{"value":"weekly","label":"Semanal"},{"value":"monthly","label":"Mensual"}]' value="weekly" name="frequency"></mk-radio-group>
+```
+
+Registra con `defineRadioGroup()` desde `@yewdiel21/motion-kit/elements` o utiliza el auto registro. Los atributos de opciones se pueden cambiar en vivo; el valor imperativo se conserva al cambiar otra opción. `disabled="false"` se lee como false. El elemento expone `value`, `setValue`, `reset`.
+
+## Accesibilidad y lifecycle
+
+Se conserva el input nativo, su etiqueta, teclado, tacto, validación y participación en formularios. El reset de formulario es cancelable; el control espera al reset nativo y verifica defaultPrevented. Movimiento reducido conserva toda la funcionalidad. destroy es idempotente y libera animaciones, eventos y timers, elimina solo las partes creadas y restaura los atributos del host. Los temas utilizan DM Sans y tokens --mk-*; el CSS de este componente es independiente de los otros estilos.
+

package/src/components/radio-group/element.ts

@@ -0,0 +1,41 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createRadioGroup, type RadioGroupInstance } from './engine';
+
+/** Light DOM; attribute changes keep the current imperative value and reset baseline. */
+export class MkRadioGroupElement extends MkElement<RadioGroupInstance> {
+  static options: Record<string, OptionType> = {"items":"json","value":"string","name":"string","label":"string","disabled":"boolean","required":"boolean","error":"string","variant":"string"};
+  private baseline: string | null | undefined;
+  private saved: string | null | undefined;
+  protected create(options: Record<string, unknown>) {
+    const created = createRadioGroup(this, { ...options, value: this.saved !== undefined ? this.saved : options.value as string | null | undefined, defaultValue: this.baseline });
+    if (this.baseline === undefined) this.baseline = created.value;
+    this.saved = undefined;
+    return created;
+  }
+  disconnectedCallback() {
+    this.saved = this.instance?.value;
+    super.disconnectedCallback();
+  }
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next) return;
+    if (name === 'value' && (!this.instance || !this.isConnected)) {
+      this.saved = next === null ? this.baseline ?? null : next;
+      return;
+    }
+    if (!this.instance || !this.isConnected) return;
+    if (name === 'value') {
+      const parsed = next === null ? this.baseline ?? null : next;
+      this.instance.setValue(parsed, false);
+      return;
+    }
+    this.saved = this.instance.value;
+    super.attributeChangedCallback(name, previous, next);
+  }
+  get value(): string | null { return this.instance?.value ?? this.saved ?? null; }
+  set value(next: string | null) { this.setValue(next); }
+  setValue(value: string | null, notify = false) { if (this.instance) this.instance.setValue(value, notify); else this.saved = value; }
+  reset(notify = false) { this.instance?.reset(notify); }
+  
+}
+export const defineRadioGroup = () => defineElement('mk-radio-group', MkRadioGroupElement);
+

package/src/components/radio-group/engine.ts

@@ -0,0 +1,11 @@
+import { createChoices, type ChoiceInstance, type ChoiceItem, type ChoiceOptions } from './shared';
+
+export interface RadioGroupItem extends ChoiceItem {}
+export interface RadioGroupOptions extends Omit<ChoiceOptions, 'variant' | 'caption' | 'eventValue'> {
+  /** Pill selectors, descriptive cards, or compact settings rows. */
+  variant?: 'pill' | 'card' | 'list';
+}
+export interface RadioGroupInstance extends ChoiceInstance {}
+export function createRadioGroup(root: HTMLElement | null, options: RadioGroupOptions = {}): RadioGroupInstance {
+  return createChoices(root, 'radio', options);
+}