@yewdiel21/motion-kit 0.17.0 → 0.18.0

package/src/components/morphing-page-dots/element.ts

@@ -0,0 +1,16 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createMorphingPageDots, type MorphingPageDotsInstance } from './engine';
+
+export class MkMorphingPageDotsElement extends MkElement<MorphingPageDotsInstance> {
+  static options: Record<string, OptionType> = { count: 'number', value: 'number', label: 'string', labels: 'json', pageIds: 'json', disabled: 'boolean' };
+  private retained: number | undefined;
+  protected create(options: Record<string, unknown>) { return createMorphingPageDots(this, { ...options, ...(this.retained === undefined ? {} : { value: this.retained }) }); }
+  disconnectedCallback() { this.retained = this.instance?.value ?? this.retained; super.disconnectedCallback(); }
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    const focusIndex = [...this.querySelectorAll('button')].findIndex((button) => button === document.activeElement);
+    if (previous !== next) this.retained = name === 'value' ? undefined : this.instance?.value ?? this.retained;
+    super.attributeChangedCallback(name, previous, next);
+    if (focusIndex >= 0) { const buttons = this.querySelectorAll('button'); buttons[Math.min(focusIndex, buttons.length - 1)]?.focus({ preventScroll: true }); }
+  }
+}
+export const defineMorphingPageDots = () => defineElement('mk-morphing-page-dots', MkMorphingPageDotsElement);

package/src/components/morphing-page-dots/engine.ts

@@ -0,0 +1,89 @@
+import { gsap, EASE, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { press } from '../../motion/micro';
+
+export interface MorphingPageDotsOptions {
+  count?: number;
+  value?: number;
+  label?: string;
+  /** Accessible page names; by default "Página 1 de 5". */
+  labels?: string[];
+  /** Optional ids of the real carousel slides controlled by each dot. */
+  pageIds?: string[];
+  disabled?: boolean;
+  onChange?: (index: number) => void;
+}
+export interface MorphingPageDotsInstance extends Instance {
+  setValue(index: number, notify?: boolean): void;
+  readonly value: number;
+}
+export function createMorphingPageDots(root: HTMLElement | null, options: MorphingPageDotsOptions = {}): MorphingPageDotsInstance {
+  if (!root) return inert({ setValue() {}, value: 0 });
+  registerMotion();
+  const scope = createScope();
+  const count = Number.isFinite(options.count) ? Math.min(20, Math.max(1, Math.round(options.count!))) : 5;
+  const normalize = (index: number) => Math.min(count - 1, Math.max(0, Math.round(index)));
+  let value = normalize(Number.isFinite(options.value) ? options.value! : 0);
+  const authored = [...root.childNodes];
+  const rail = document.createElement('span'); rail.dataset.mkPageRail = '';
+  const blob = document.createElement('i'); blob.dataset.mkPageBlob = ''; blob.setAttribute('aria-hidden', 'true'); rail.append(blob);
+  const buttons: HTMLButtonElement[] = [];
+  for (let i = 0; i < count; i++) {
+    const button = document.createElement('button'); button.type = 'button'; button.dataset.mkPageDot = '';
+    button.setAttribute('aria-label', options.labels?.[i] ?? `Página ${i + 1} de ${count}`);
+    if (options.pageIds?.[i]) button.setAttribute('aria-controls', options.pageIds[i]!);
+    button.disabled = Boolean(options.disabled);
+    const dot = document.createElement('i'); dot.setAttribute('aria-hidden', 'true'); button.append(dot); rail.append(button); buttons.push(button);
+  }
+  root.replaceChildren(rail);
+  scope.add(() => { rail.remove(); root.append(...authored); });
+  scope.attr(root, 'role', 'group');
+  scope.attr(root, 'aria-label', options.label ?? 'Páginas');
+  scope.attr(root, 'data-mk-morphing-page-dots', '');
+  scope.attr(root, 'data-mk-ready', '');
+  let moving: gsap.core.Timeline | null = null;
+  let pressing: gsap.core.Animation | null = null;
+  const at = (index: number) => {
+    const button = buttons[index]!;
+    const size = button.offsetWidth || 44;
+    return (button.offsetLeft || index * size) + size / 2 - 12;
+  };
+  const place = () => { moving?.kill(); moving = null; gsap.set(blob, { left: at(value), width: 24, scaleY: 1 }); };
+  const paint = () => buttons.forEach((button, i) => { button.setAttribute('aria-current', i === value ? 'page' : 'false'); button.tabIndex = i === value ? 0 : -1; });
+  const setValue = (index: number, notify = false) => {
+    if (scope.disposed || !Number.isFinite(index)) return;
+    const next = normalize(index);
+    if (value === next) return;
+    const start = at(value); const end = at(next);
+    value = next;
+    paint();
+    moving?.kill();
+    if (reduced()) place();
+    else {
+      // Stretch the leading edge, then let the tail catch up on the shared swatch curve.
+      const current = Number(gsap.getProperty(blob, 'left')) || start;
+      moving = gsap.timeline()
+        .to(blob, { left: Math.min(current, end), width: Math.abs(end - current) + 24, scaleY: .68, duration: .18, ease: EASE.wipe })
+        .to(blob, { left: end, width: 24, scaleY: 1, duration: .48, ease: EASE.swatch }, .13);
+    }
+    if (notify) { options.onChange?.(value); root.dispatchEvent(new CustomEvent('mk:change', { bubbles: true, detail: { value } })); }
+  };
+  buttons.forEach((button, i) => {
+    scope.on(button, 'click', () => { if (button.disabled) return; pressing?.kill(); pressing = press(button); setValue(i, true); });
+    scope.on(button, 'keydown', (event) => {
+      if (button.disabled) return;
+      const key = event.key;
+      if (!['ArrowLeft', 'ArrowRight', 'Home', 'End'].includes(key)) return;
+      event.preventDefault();
+      const rtl = getComputedStyle(root).direction === 'rtl';
+      let next = key === 'Home' ? 0 : key === 'End' ? count - 1 : (value + ((key === 'ArrowRight') !== rtl ? 1 : -1) + count) % count;
+      setValue(next, true); buttons[next]!.focus();
+    });
+  });
+  if (typeof ResizeObserver !== 'undefined') scope.observe(new ResizeObserver(place)).observe(rail);
+  paint(); place();
+  scope.add(() => { moving?.kill(); pressing?.kill(); });
+  return { setValue, get value() { return value; }, destroy: () => scope.dispose() };
+}

package/src/components/morphing-page-dots/morphing-page-dots.css

@@ -0,0 +1,12 @@
+.mk-morphing-page-dots,
+mk-morphing-page-dots { display: inline-flex; max-width: 100%; color: var(--mk-text); font-family: var(--mk-font); }
+[data-mk-page-rail] { position: relative; display: inline-flex; max-width: 100%; border-radius: 999px; background: var(--mk-surface-2); padding: 0; overflow-x: auto; }
+[data-mk-page-dot] { position: relative; flex: 0 0 44px; width: 44px; height: 44px; display: grid; place-items: center; padding: 0; background: transparent; border: 0; border-radius: 999px; cursor: pointer; }
+[data-mk-page-dot] > i { width: 8px; height: 8px; border-radius: 999px; background: var(--mk-muted); opacity: .45; transition: opacity 150ms; }
+[data-mk-page-dot]:hover > i { opacity: .85; }
+[data-mk-page-dot][aria-current='page'] > i { opacity: 0; }
+[data-mk-page-dot]:focus-visible { outline: 2px solid var(--mk-accent); outline-offset: -3px; }
+[data-mk-page-dot]:disabled { cursor: not-allowed; opacity: .4; }
+[data-mk-page-blob] { position: absolute; top: 18px; left: 10px; width: 24px; height: 8px; background: var(--mk-text); border-radius: 999px; pointer-events: none; }
+[data-mk-morphing-page-dots]:has(button:disabled) [data-mk-page-blob] { opacity: .4; }
+@media (prefers-reduced-motion: reduce) { [data-mk-page-dot] > i { transition: none; } }

package/src/components/morphing-page-dots/react.tsx

@@ -0,0 +1,32 @@
+'use client';
+import { useRef, type HTMLAttributes, type Ref } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createMorphingPageDots, type MorphingPageDotsInstance, type MorphingPageDotsOptions } from './engine';
+
+export interface MorphingPageDotsProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'dangerouslySetInnerHTML' | 'onChange'>, MorphingPageDotsOptions {
+  defaultValue?: number;
+  instanceRef?: Ref<MorphingPageDotsInstance>;
+}
+export function MorphingPageDots({ count, value, defaultValue = 0, label, labels, pageIds, disabled, onChange, instanceRef, className, ...props }: MorphingPageDotsProps) {
+  const { children: _children, dangerouslySetInnerHTML: _html, ...safe } = props as HTMLAttributes<HTMLDivElement>;
+  const root = useRef<HTMLDivElement>(null);
+  const instance = useRef<MorphingPageDotsInstance | null>(null);
+  const current = useLatest({ value, onChange });
+  const retained = useRef(defaultValue);
+  const labelsKey = JSON.stringify(labels); const pagesKey = JSON.stringify(pageIds);
+  useIsomorphicLayoutEffect(() => {
+    let created: MorphingPageDotsInstance;
+    created = createMorphingPageDots(root.current, {
+      count, value: current.current.value ?? retained.current, label, labels, pageIds, disabled,
+      onChange: (next) => { current.current.onChange?.(next); if (current.current.value !== undefined) created.setValue(current.current.value); },
+    });
+    instance.current = created;
+    return () => { retained.current = created.value; created.destroy(); instance.current = null; };
+  }, [count, label, labelsKey, pagesKey, disabled]);
+  useIsomorphicLayoutEffect(() => { if (value !== undefined) instance.current?.setValue(value); }, [value]);
+  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, count, label, labelsKey, pagesKey, disabled]);
+  return <div {...safe} ref={root} className={['mk-morphing-page-dots', className].filter(Boolean).join(' ')} />;
+}

package/src/components/not-found/README.md

@@ -0,0 +1,26 @@
+# Not found
+
+Estado 404 con ilustración vectorial original: dos cuatros y un pequeño portal en lugar del cero. Su entrada combina blur escalonado y un asentamiento `swatch`; permanece quieto después. Usa superficies del tema y reserva el acento para la brújula.
+
+```ts
+import { createNotFound } from '@yewdiel21/motion-kit';
+import '@yewdiel21/motion-kit/css/not-found';
+const missing = createNotFound(document.querySelector('#missing'), {
+  brand: 'Mi biblioteca', homeHref: '/library',
+});
+// missing.replay(); missing.destroy();
+```
+
+`NotFoundOptions`: `brand` (Motion Kit), `title`, `description`, `homeHref` (/), `homeLabel`, `backLabel`, `showBack` (true), `onBack`. El enlace Home navega a su href real. Back llama `history.back()`; se desactiva cuando no hay entrada previa. `onBack` permite que un router posea la acción. `NotFoundInstance`: `replay()`, `destroy()`. Todo el contenido configurable se inserta como texto, no como HTML.
+
+```tsx
+<NotFound brand="Mi biblioteca" homeHref="/library" instanceRef={missingRef} />
+```
+
+`NotFoundProps` añade atributos de div e `instanceRef`; el motor posee todos los hijos, por lo que filtra `children` y `dangerouslySetInnerHTML` en ejecución. Cambiar copy o destinos actualiza la instancia. Movimiento reducido conserva toda la navegación y muestra el estado completo inmediatamente.
+
+```html
+<mk-not-found brand="Mi biblioteca" home-href="/library" title="No encontramos esa lectura."></mk-not-found>
+```
+
+`defineNotFound()` registra `MkNotFoundElement`; atributos `brand`, `title`, `description`, `home-href`, `home-label`, `back-label`, `show-back`. El contenido usa heading h2 para poder incrustarlo en un layout; la página anfitriona determina su h1 y su código HTTP. `destroy()` detiene la entrada y devuelve los nodos y atributos originales.

package/src/components/not-found/element.ts

@@ -0,0 +1,15 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createNotFound, type NotFoundInstance } from './engine';
+
+export class MkNotFoundElement extends MkElement<NotFoundInstance> {
+  static options: Record<string, OptionType> = { brand: 'string', title: 'string', description: 'string', homeHref: 'string', homeLabel: 'string', backLabel: 'string', showBack: 'boolean' };
+  protected create(options: Record<string, unknown>) { return createNotFound(this, options); }
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    const active = document.activeElement;
+    const focused = this.contains(active);
+    const back = active?.tagName === 'BUTTON';
+    super.attributeChangedCallback(name, previous, next);
+    if (focused) (this.querySelector<HTMLElement>(back ? 'button:not(:disabled)' : 'a') ?? this.querySelector<HTMLElement>('a'))?.focus({ preventScroll: true });
+  }
+}
+export const defineNotFound = () => defineElement('mk-not-found', MkNotFoundElement);

package/src/components/not-found/engine.ts

@@ -0,0 +1,57 @@
+import { gsap, EASE, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { blurIn, press } from '../../motion/micro';
+
+export interface NotFoundOptions {
+  brand?: string;
+  title?: string;
+  description?: string;
+  homeHref?: string;
+  homeLabel?: string;
+  backLabel?: string;
+  showBack?: boolean;
+  /** A router may own Back. Without this callback it calls history.back(). */
+  onBack?: () => void;
+}
+export interface NotFoundInstance extends Instance { replay(): void; }
+const ILLUSTRATION = '<svg viewBox="0 0 320 140" fill="none" aria-hidden="true"><path data-mk-lost-track d="M20 115H100Q118 115 118 95V72Q118 53 138 53H185Q205 53 205 73V95Q205 115 224 115H300"/><g data-mk-lost-four><path d="M72 23L35 79H84M77 23V107"/><path d="M263 23L226 79H275M268 23V107"/></g><g data-mk-lost-portal><rect x="124" y="18" width="72" height="96" rx="32"/><ellipse cx="160" cy="66" rx="17" ry="29"/><path d="M145 66h30M160 51v30"/></g><path data-mk-lost-star d="M211 13v12m-6-6h12M105 118v8m-4-4h8"/></svg>';
+export function createNotFound(root: HTMLElement | null, options: NotFoundOptions = {}): NotFoundInstance {
+  if (!root) return inert({ replay() {} });
+  registerMotion();
+  const scope = createScope();
+  const authored = [...root.childNodes];
+  const content = document.createElement('div'); content.dataset.mkNotFoundContent = '';
+  const art = document.createElement('div'); art.dataset.mkNotFoundArt = ''; art.innerHTML = ILLUSTRATION;
+  const eyebrow = document.createElement('p'); eyebrow.dataset.mkNotFoundCode = ''; eyebrow.textContent = `404 · ${options.brand ?? 'Motion Kit'}`;
+  const heading = document.createElement('h2'); heading.textContent = options.title ?? 'Este camino se perdió.';
+  const description = document.createElement('p'); description.dataset.mkNotFoundDescription = ''; description.textContent = options.description ?? 'La página que buscas no está aquí. Volvamos a un lugar conocido.';
+  const actions = document.createElement('div'); actions.dataset.mkNotFoundActions = '';
+  const home = document.createElement('a'); home.href = options.homeHref ?? '/'; home.textContent = options.homeLabel ?? 'Volver al inicio';
+  actions.append(home);
+  const back = document.createElement('button'); back.type = 'button'; back.textContent = options.backLabel ?? 'Ir atrás';
+  back.disabled = !options.onBack && history.length <= 1;
+  if (options.showBack !== false) actions.append(back);
+  content.append(art, eyebrow, heading, description, actions);
+  root.replaceChildren(content);
+  scope.add(() => { content.remove(); root.append(...authored); });
+  scope.attr(root, 'data-mk-not-found', '');
+  scope.attr(root, 'data-mk-ready', '');
+  let entering: gsap.core.Animation | null = null;
+  let drawing: gsap.core.Animation | null = null;
+  let pressing: gsap.core.Animation | null = null;
+  const portal = art.querySelector('[data-mk-lost-portal]');
+  const replay = () => {
+    if (scope.disposed) return;
+    entering?.kill(); drawing?.kill();
+    if (reduced()) { gsap.set([art, eyebrow, heading, description, actions], { clearProps: 'all' }); return; }
+    entering = blurIn([art, eyebrow, heading, description, actions], { from: 'soft', duration: .5, stagger: .055 });
+    drawing = gsap.fromTo(portal, { rotation: -12, scale: .82, transformOrigin: '50% 50%' }, { rotation: 0, scale: 1, duration: .8, ease: EASE.swatch });
+  };
+  scope.on(back, 'click', () => { if (!back.disabled) { pressing?.kill(); pressing = press(back); if (options.onBack) options.onBack(); else history.back(); } });
+  scope.on(home, 'click', () => { pressing?.kill(); pressing = press(home); });
+  replay();
+  scope.add(() => { entering?.kill(); drawing?.kill(); pressing?.kill(); });
+  return { replay, destroy: () => scope.dispose() };
+}

package/src/components/not-found/not-found.css

@@ -0,0 +1,21 @@
+.mk-not-found,
+mk-not-found { display: block; max-width: 34rem; color: var(--mk-text); font-family: var(--mk-font); }
+[data-mk-not-found-content] { display: grid; justify-items: center; text-align: center; gap: .75rem; padding: .75rem 1rem; }
+[data-mk-not-found-art] { width: min(100%, 320px); }
+[data-mk-not-found-art] svg { display: block; width: 100%; overflow: visible; }
+[data-mk-lost-track] { stroke: var(--mk-outline); stroke-width: 1.5; stroke-dasharray: 3 5; }
+[data-mk-lost-four] { stroke: var(--mk-text); stroke-width: 9; stroke-linecap: round; stroke-linejoin: round; }
+[data-mk-lost-portal] rect { fill: var(--mk-surface-3); stroke: var(--mk-outline-soft); }
+[data-mk-lost-portal] ellipse { fill: var(--mk-surface-1); stroke: var(--mk-outline); stroke-width: 1.5; }
+[data-mk-lost-portal] path,
+[data-mk-lost-star] { stroke: var(--mk-accent); stroke-width: 2; stroke-linecap: round; }
+[data-mk-not-found-code] { margin: 0; color: var(--mk-muted); font-size: .6875rem; letter-spacing: .1em; text-transform: uppercase; }
+[data-mk-not-found-content] h2 { margin: 0; font-size: clamp(1.5rem, 4vw, 2rem); font-weight: 550; line-height: 1.15; letter-spacing: -.045em; }
+[data-mk-not-found-description] { max-width: 34ch; margin: 0; color: var(--mk-muted); font-size: .875rem; line-height: 1.55; }
+[data-mk-not-found-actions] { display: flex; flex-wrap: wrap; justify-content: center; gap: .5rem; margin-top: .5rem; }
+[data-mk-not-found-actions] :is(a, button) { display: inline-flex; align-items: center; justify-content: center; min-height: 44px; padding: .7rem 1rem; border: 0; border-radius: 16px; background: var(--mk-surface-3); color: var(--mk-text); font: 500 .875rem var(--mk-font); text-decoration: none; cursor: pointer; transition: background 160ms, border-radius 320ms var(--mk-ease-swatch); }
+[data-mk-not-found-actions] a { background: var(--mk-text); color: var(--mk-bg); }
+[data-mk-not-found-actions] :is(a, button):hover { border-radius: 24px; }
+[data-mk-not-found-actions] :is(a, button):focus-visible { outline: 2px solid var(--mk-accent); outline-offset: 4px; }
+[data-mk-not-found-actions] button:disabled { opacity: .4; cursor: not-allowed; }
+@media (prefers-reduced-motion: reduce) { [data-mk-not-found-actions] :is(a, button) { transition: none; } }

package/src/components/not-found/react.tsx

@@ -0,0 +1,23 @@
+'use client';
+import { useRef, type HTMLAttributes, type Ref } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createNotFound, type NotFoundInstance, type NotFoundOptions } from './engine';
+
+export interface NotFoundProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'dangerouslySetInnerHTML' | 'title'>, NotFoundOptions { instanceRef?: Ref<NotFoundInstance>; }
+export function NotFound({ brand, title, description, homeHref, homeLabel, backLabel, showBack, onBack, instanceRef, className, ...props }: NotFoundProps) {
+  const { children: _children, dangerouslySetInnerHTML: _html, ...safe } = props as HTMLAttributes<HTMLDivElement>;
+  const root = useRef<HTMLDivElement>(null);
+  const instance = useRef<NotFoundInstance | null>(null);
+  const current = useLatest(onBack);
+  const hasBack = Boolean(onBack);
+  useIsomorphicLayoutEffect(() => {
+    const created = createNotFound(root.current, { brand, title, description, homeHref, homeLabel, backLabel, showBack, onBack: hasBack ? () => current.current?.() : undefined });
+    instance.current = created;
+    return () => { created.destroy(); instance.current = null; };
+  }, [brand, title, description, homeHref, homeLabel, backLabel, showBack, hasBack]);
+  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, brand, title, description, homeHref, homeLabel, backLabel, showBack, hasBack]);
+  return <div {...safe} ref={root} className={['mk-not-found', className].filter(Boolean).join(' ')} />;
+}

package/src/components/notification-stack/README.md

@@ -0,0 +1,24 @@
+# Notification stack
+
+A local notification deck with overlapping tonal cards, explicit expand/collapse, actions, dismissal and pausable durations. It is independent of the global `toast` store, so several decks can coexist.
+
+```ts
+import { createNotificationStack } from '@yewdiel21/motion-kit';
+const stack = createNotificationStack(document.querySelector('#notifications'), {
+  items: [{ id: 'saved', title: 'Cambios guardados', tone: 'success', duration: 0 }],
+});
+stack.push({ id: 'review', title: 'Versión lista', duration: 6000, action: { label: 'Revisar', onClick: openReview } });
+stack.expand();
+// On unmount:
+stack.destroy();
+```
+
+Exports: `createNotificationStack`, `NotificationStackItem`, `NotificationStackOptions`, `NotificationStackInstance`; React `NotificationStack`, `NotificationStackProps`; elements `MkNotificationStackElement`, `defineNotificationStack` (`mk-notification-stack`). CSS: `notification-stack.css` plus the kit tokens/theme/fonts.
+
+Options: `items`, `expanded`, `direction` (`down` default, `up` or `side`), `duration` (milliseconds, default 6000, zero persists), `disabled`, `label`, `labels` (`expand`, `collapse`, `dismiss`, `empty`), `onDismiss(id)`, `onAction(id)`, `onExpandedChange(expanded)`. Items have `id`, `title`, optional `description`, `tone`, `duration`, `dismissible`, `action: {label,onClick?}`. IDs are unique; pushing an existing ID is ignored. `items` lists oldest first. `setOptions({items})` replaces data while preserving the remaining lifetime of matching IDs.
+
+`direction: 'up'` rests the cards on the deck's floor and grows above the front card (anchor its container to the bottom, for example with `flex-direction: column-reverse`); `'side'` peeks at the right edge and opens into a strip that scrolls sideways. A click on a closed deck opens it, and hovering spreads its peeks to invite that click; the toggle remains the keyboard path. Opening fans the cards out one by one as their blur clears.
+
+Instance: `push(item)`, `dismiss(id)`, `clear()`, `expand()`, `collapse()`, `toggle()`, `setOptions(partial)`, readonly `items`/`expanded`, `destroy()`. Events: `mk:dismiss` `{id}` and `mk:change` `{expanded}`. Hover, focus, document visibility and disabled state pause timers. Covered cards are inert until expanded. Dismissal moves focus to a surviving control or the region. Reduced motion applies the same state immediately.
+
+React owns an empty host; pass `items`, never children or HTML. `instanceRef` exposes the engine for `push`. An element accepts JSON `items`/`labels` and the other scalar options as attributes; `push`, `items` and `setOptions` also work as properties/methods. Attribute updates retain the live engine.

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

@@ -0,0 +1,26 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createNotificationStack, type NotificationStackInstance, type NotificationStackOptions, type NotificationStackItem } from './engine';
+
+export class MkNotificationStackElement extends MkElement<NotificationStackInstance> {
+  static options: Record<string, OptionType> = {"items":"json","expanded":"boolean","direction":"string","duration":"number","disabled":"boolean","label":"string","labels":"json"};
+  protected create(options: Record<string, unknown>) { return createNotificationStack(this, options); }
+  setOptions(options: Partial<NotificationStackOptions>) { this.instance?.setOptions(options); }
+
+  push(item: NotificationStackItem) { this.instance?.push(item); }
+  dismiss(id: string) { this.instance?.dismiss(id); }
+  clear() { this.instance?.clear(); }
+  expand() { this.instance?.expand(); }
+  collapse() { this.instance?.collapse(); }
+  toggle() { this.instance?.toggle(); }
+  get expanded() { return this.instance?.expanded ?? false; }
+  set expanded(value: boolean) { this.instance?.setOptions({ expanded: value }); }
+  get items() { return [...(this.instance?.items ?? [])]; }
+  set items(value: NotificationStackItem[]) { this.instance?.setOptions({ items: value }); }
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.isConnected || !this.instance) return;
+    const option = name.replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase());
+    const defaults: Record<string, unknown> = {"items":[],"expanded":false,"direction":"down","duration":6000,"disabled":false,"label":"Notificaciones","labels":{}};
+    this.instance.setOptions({ [option]: this.options[option] ?? defaults[option] });
+  }
+}
+export const defineNotificationStack = () => defineElement('mk-notification-stack', MkNotificationStackElement);