@yewdiel21/motion-kit 0.10.0 → 0.14.0

package/src/components/image-preview/engine.ts

@@ -0,0 +1,325 @@
+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 { rollDigits } from '../../motion/micro';
+
+/*
+ * Image preview: thumbnails ([data-mk-image]) open a modal <dialog> where the
+ * picture grows out of its thumbnail (0.7 s on the signature curve, the
+ * thumbnail's radius easing to 24 px) over a blurred backdrop. Previous/next
+ * (buttons, arrow keys, a swipe) slide the next picture in out of a blur; the
+ * counter rolls. A double click or tap zooms ×2 where you point and a drag pans
+ * it. Dragging down, Escape or the close button send the picture back to its
+ * thumbnail, and focus returns to it.
+ */
+
+export interface ImagePreviewOptions {
+  labels?: { close?: string; prev?: string; next?: string; dialog?: string };
+  /** Loop from the last picture to the first (default true). */
+  loop?: boolean;
+  onChange?: (index: number) => void;
+  onOpenChange?: (open: boolean) => void;
+}
+
+export interface ImagePreviewInstance extends Instance {
+  open(index?: number): void;
+  close(): void;
+  next(): void;
+  prev(): void;
+  readonly isOpen: boolean;
+  readonly index: number;
+}
+
+interface Picture {
+  thumb: HTMLElement;
+  src: string;
+  alt: string;
+  caption: string;
+}
+
+const button = (part: string, label: string, path: string) => {
+  const element = document.createElement('button');
+  element.type = 'button';
+  element.dataset.mkLightbox = part;
+  element.setAttribute('aria-label', label);
+  element.innerHTML = `<svg aria-hidden="true" width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="${path}"/></svg>`;
+  return element;
+};
+
+export function createImagePreview(root: HTMLElement | null, options: ImagePreviewOptions = {}): ImagePreviewInstance {
+  if (!root) return inert({ open() {}, close() {}, next() {}, prev() {}, isOpen: false, index: -1 });
+  registerMotion();
+  const scope = createScope();
+  const loop = options.loop ?? true;
+  const labels = { close: 'Cerrar', prev: 'Imagen anterior', next: 'Imagen siguiente', dialog: 'Vista de imagen', ...options.labels };
+
+  const pictures = (): Picture[] =>
+    [...root.querySelectorAll<HTMLElement>('[data-mk-image]')].map((thumb) => {
+      const img = thumb.matches('img') ? (thumb as HTMLImageElement) : thumb.querySelector('img');
+      return {
+        thumb,
+        src: thumb.dataset.mkSrc || thumb.getAttribute('href') || img?.getAttribute('src') || img?.currentSrc || '',
+        alt: img?.alt ?? thumb.getAttribute('aria-label') ?? '',
+        caption: thumb.dataset.mkCaption ?? '',
+      };
+    });
+
+  const dialog = document.createElement('dialog');
+  dialog.dataset.mkLightboxDialog = '';
+  dialog.setAttribute('aria-label', labels.dialog);
+  const backdrop = document.createElement('div');
+  backdrop.dataset.mkLightbox = 'backdrop';
+  const stage = document.createElement('figure');
+  stage.dataset.mkLightbox = 'stage';
+  const image = document.createElement('img');
+  image.dataset.mkLightbox = 'image';
+  image.draggable = false;
+  const caption = document.createElement('figcaption');
+  caption.dataset.mkLightbox = 'caption';
+  stage.append(image, caption);
+  const close = button('close', labels.close, 'M6 6l12 12M18 6L6 18');
+  const prev = button('prev', labels.prev, 'M15 5l-7 7 7 7');
+  const next = button('next', labels.next, 'M9 5l7 7-7 7');
+  const counter = document.createElement('span');
+  counter.dataset.mkLightbox = 'count';
+  counter.setAttribute('aria-live', 'polite');
+  dialog.append(backdrop, stage, prev, next, close, counter);
+  root.append(dialog);
+  scope.add(() => dialog.remove());
+  scope.attr(root, 'data-mk-ready', '');
+  for (const { thumb } of pictures()) {
+    if (thumb.matches('button, a[href]') || thumb.tabIndex >= 0) continue;
+    scope.attr(thumb, 'tabindex', '0');
+    scope.attr(thumb, 'role', 'button');
+  }
+
+  let isOpen = false;
+  let index = -1;
+  let zoomed = false;
+  let list: Picture[] = [];
+  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 thumbImg = (picture?: Picture) => (picture ? (picture.thumb.matches('img') ? picture.thumb : picture.thumb.querySelector('img') ?? picture.thumb) : null);
+  scope.add(() => {
+    for (const effect of effects) effect.kill();
+    effects.clear();
+    gsap.killTweensOf([image, backdrop, stage]);
+    for (const picture of list) thumbImg(picture)?.style.removeProperty('visibility');
+    if (dialog.open) dialog.close();
+  });
+
+  const write = (i: number) => {
+    const picture = list[i]!;
+    image.src = picture.src;
+    image.alt = picture.alt;
+    caption.textContent = picture.caption;
+    caption.hidden = !picture.caption;
+    const text = `${i + 1} / ${list.length}`;
+    if (counter.textContent && !reduced()) keep(rollDigits(counter, text, i >= index ? 1 : -1, 0.35));
+    else counter.textContent = text;
+    prev.disabled = !loop && i === 0;
+    next.disabled = !loop && i === list.length - 1;
+    prev.hidden = next.hidden = list.length < 2;
+  };
+
+  /** Transform that puts the big image over the thumbnail. */
+  const fromThumb = (picture: Picture) => {
+    const small = thumbImg(picture)!.getBoundingClientRect();
+    const big = image.getBoundingClientRect();
+    if (!small.width || !big.width) return null;
+    const radius = parseFloat(getComputedStyle(thumbImg(picture)!).borderRadius) || 0;
+    return {
+      x: small.left + small.width / 2 - (big.left + big.width / 2),
+      y: small.top + small.height / 2 - (big.top + big.height / 2),
+      scaleX: small.width / big.width,
+      scaleY: small.height / big.height,
+      borderRadius: radius / (small.width / big.width),
+    };
+  };
+
+  const unzoom = () => {
+    zoomed = false;
+    dialog.removeAttribute('data-mk-zoomed');
+    keep(gsap.to(image, { scale: 1, x: 0, y: 0, duration: reduced() ? 0 : 0.4, ease: EASE.signature }));
+  };
+
+  const open = (at = 0) => {
+    if (scope.disposed) return;
+    list = pictures();
+    if (!list.length) return;
+    const target = Math.max(0, Math.min(list.length - 1, Math.round(at)));
+    if (isOpen) return go(target);
+    isOpen = true;
+    index = target;
+    counter.textContent = '';
+    write(target);
+    if (typeof dialog.showModal === 'function') dialog.showModal();
+    else dialog.setAttribute('open', '');
+    close.focus({ preventScroll: true });
+    const picture = list[target]!;
+    options.onOpenChange?.(true);
+    root.dispatchEvent(new CustomEvent('mk:open', { bubbles: true, detail: { index } }));
+    if (reduced()) return;
+    keep(gsap.fromTo(backdrop, { opacity: 0 }, { opacity: 1, duration: 0.4, ease: 'power2.out', clearProps: 'opacity' }));
+    keep(gsap.fromTo([prev, next, close, counter, caption], { opacity: 0 }, { opacity: 1, duration: 0.3, delay: 0.3, clearProps: 'opacity' }));
+    const grow = () => {
+      const start = fromThumb(picture);
+      if (!start) return void keep(gsap.fromTo(image, { opacity: 0, scale: 0.92 }, { opacity: 1, scale: 1, duration: 0.35, ease: EASE.pop, clearProps: 'opacity,scale,transform' }));
+      thumbImg(picture)!.style.visibility = 'hidden';
+      keep(gsap.fromTo(image, start, { x: 0, y: 0, scaleX: 1, scaleY: 1, borderRadius: 24, duration: 0.7, ease: EASE.signature, clearProps: 'transform,borderRadius', onComplete: () => {
+        thumbImg(picture)?.style.removeProperty('visibility');
+      } }));
+    };
+    if (image.complete && image.naturalWidth) grow();
+    else image.addEventListener('load', grow, { once: true });
+  };
+
+  const finish = () => {
+    if (dialog.open) dialog.close();
+    gsap.set([image, backdrop], { clearProps: 'all' });
+    const picture = list[index];
+    if (picture) thumbImg(picture)?.style.removeProperty('visibility');
+    isOpen = false;
+    zoomed = false;
+    dialog.removeAttribute('data-mk-zoomed');
+    options.onOpenChange?.(false);
+    root.dispatchEvent(new CustomEvent('mk:close', { bubbles: true, detail: { index } }));
+    picture?.thumb.focus({ preventScroll: true });
+  };
+
+  const shut = () => {
+    if (!isOpen) return;
+    const picture = list[index];
+    if (reduced() || !picture) return finish();
+    gsap.killTweensOf(image);
+    gsap.set(image, { scale: 1, x: 0, y: 0 });
+    const end = fromThumb(picture);
+    keep(gsap.to(backdrop, { opacity: 0, duration: 0.35, ease: 'power2.in' }));
+    keep(gsap.to([prev, next, close, counter, caption], { opacity: 0, duration: 0.15 }));
+    if (!end) return void keep(gsap.to(image, { opacity: 0, scale: 0.92, duration: 0.25, ease: 'power2.in', onComplete: finish }));
+    thumbImg(picture)!.style.visibility = 'hidden';
+    keep(gsap.to(image, { ...end, duration: 0.5, ease: EASE.signature, onComplete: () => {
+      gsap.set([prev, next, close, counter, caption], { clearProps: 'opacity' });
+      finish();
+    } }));
+  };
+
+  function go(to: number) {
+    if (!isOpen || list.length < 2) return;
+    let target = to;
+    if (loop) target = (to + list.length) % list.length;
+    else if (to < 0 || to >= list.length) return;
+    if (target === index) return;
+    const direction = to > index ? 1 : -1;
+    if (zoomed) unzoom();
+    const before = index;
+    index = target;
+    options.onChange?.(index);
+    root!.dispatchEvent(new CustomEvent('mk:change', { bubbles: true, detail: { index, previous: before } }));
+    if (reduced()) return write(target);
+    gsap.killTweensOf(image);
+    keep(
+      gsap
+        .timeline()
+        .to(image, { x: -60 * direction, opacity: 0, filter: 'blur(12px)', duration: 0.18, ease: 'power2.in' })
+        .call(() => write(target))
+        .fromTo(image, { x: 60 * direction, opacity: 0, filter: 'blur(12px)' }, { x: 0, opacity: 1, filter: 'blur(0px)', duration: 0.4, ease: EASE.signature, clearProps: 'transform,opacity,filter' }),
+    );
+  }
+
+  scope.on(root, 'click', (event) => {
+    const thumb = (event.target as Element | null)?.closest<HTMLElement>('[data-mk-image]');
+    if (!thumb || !root.contains(thumb) || dialog.contains(thumb)) return;
+    event.preventDefault();
+    open(pictures().findIndex((picture) => picture.thumb === thumb));
+  });
+  scope.on(root, 'keydown', (event) => {
+    const key = (event as KeyboardEvent).key;
+    const thumb = (event.target as Element | null)?.closest<HTMLElement>('[data-mk-image]');
+    if (thumb && !dialog.contains(thumb) && (key === 'Enter' || key === ' ') && !thumb.matches('button, a[href]')) {
+      event.preventDefault();
+      open(pictures().findIndex((picture) => picture.thumb === thumb));
+    }
+  });
+  scope.on(dialog, 'keydown', (event) => {
+    const key = (event as KeyboardEvent).key;
+    if (key === 'ArrowRight') go(index + 1);
+    else if (key === 'ArrowLeft') go(index - 1);
+    else return;
+    event.preventDefault();
+  });
+  scope.on(dialog, 'cancel', (event) => {
+    event.preventDefault();
+    shut();
+  });
+  scope.on(close, 'click', shut);
+  scope.on(prev, 'click', () => go(index - 1));
+  scope.on(next, 'click', () => go(index + 1));
+  scope.on(backdrop, 'click', shut);
+
+  // Double click / tap zooms where you point; drag pans the zoom, swipes, or drags down to close.
+  scope.on(image, 'dblclick', (event) => {
+    const mouse = event as MouseEvent;
+    if (zoomed) return unzoom();
+    const box = image.getBoundingClientRect();
+    zoomed = true;
+    dialog.setAttribute('data-mk-zoomed', '');
+    const x = (box.left + box.width / 2 - mouse.clientX) || 0;
+    const y = (box.top + box.height / 2 - mouse.clientY) || 0;
+    keep(gsap.to(image, { scale: 2, x, y, duration: reduced() ? 0 : 0.45, ease: EASE.signature }));
+  });
+  let drag: { x: number; y: number; startX: number; startY: number; id: number } | null = null;
+  scope.on(image, 'pointerdown', (event) => {
+    const pointer = event as PointerEvent;
+    if (pointer.button !== 0) return;
+    drag = { x: pointer.clientX, y: pointer.clientY, startX: Number(gsap.getProperty(image, 'x')) || 0, startY: Number(gsap.getProperty(image, 'y')) || 0, id: pointer.pointerId };
+    image.setPointerCapture?.(pointer.pointerId);
+  });
+  scope.on(image, 'pointermove', (event) => {
+    const pointer = event as PointerEvent;
+    if (!drag || pointer.pointerId !== drag.id) return;
+    const dx = pointer.clientX - drag.x;
+    const dy = pointer.clientY - drag.y;
+    if (zoomed) gsap.set(image, { x: drag.startX + dx, y: drag.startY + dy });
+    else if (!reduced()) {
+      gsap.set(image, { x: dx * 0.6, y: Math.max(0, dy) });
+      gsap.set(backdrop, { opacity: 1 - Math.min(0.6, Math.max(0, dy) / 400) });
+    }
+  });
+  const release = (event: Event) => {
+    const pointer = event as PointerEvent;
+    if (!drag || pointer.pointerId !== drag.id) return;
+    const dx = pointer.clientX - drag.x;
+    const dy = pointer.clientY - drag.y;
+    drag = null;
+    if (zoomed) return;
+    if (dy > 120) return shut();
+    if (Math.abs(dx) > 70 && Math.abs(dx) > Math.abs(dy)) return go(index + (dx < 0 ? 1 : -1));
+    if (!reduced()) {
+      keep(gsap.to(image, { x: 0, y: 0, duration: 0.45, ease: EASE.swatch, clearProps: 'transform' }));
+      keep(gsap.to(backdrop, { opacity: 1, duration: 0.3, clearProps: 'opacity' }));
+    }
+  };
+  scope.on(image, 'pointerup', release);
+  scope.on(image, 'pointercancel', release);
+
+  return {
+    open,
+    close: shut,
+    next: () => go(index + 1),
+    prev: () => go(index - 1),
+    get isOpen() {
+      return isOpen;
+    },
+    get index() {
+      return index;
+    },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/image-preview/image-preview.css

@@ -0,0 +1,194 @@
+/* image-preview — thumbnails in Melonmind cards (16 px radius) and a full-screen dialog: a blurred dark backdrop, the
+   picture at 16 px radius, round glass buttons and a counter pill. */
+.mk-image-preview,
+mk-image-preview {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(8rem, 1fr));
+  gap: 0.75rem;
+}
+
+:is(.mk-image-preview, mk-image-preview) [data-mk-image] {
+  display: block;
+  padding: 0;
+  overflow: hidden;
+  border: 0;
+  border-radius: var(--mk-radius-md, 16px);
+  background: var(--mk-surface-3);
+  cursor: zoom-in;
+  transition: scale 0.5s cubic-bezier(0.38, 0.49, 0, 1.5);
+}
+
+:is(.mk-image-preview, mk-image-preview) [data-mk-image]:hover {
+  scale: 1.03;
+}
+
+:is(.mk-image-preview, mk-image-preview) [data-mk-image]:focus-visible {
+  outline: 2px solid var(--mk-accent);
+  outline-offset: 3px;
+}
+
+:is(.mk-image-preview, mk-image-preview) [data-mk-image] img {
+  display: block;
+  width: 100%;
+  aspect-ratio: 1;
+  border-radius: inherit;
+  object-fit: cover;
+}
+
+[data-mk-lightbox-dialog] {
+  position: fixed;
+  inset: 0;
+  width: 100vw;
+  max-width: none;
+  height: 100dvh;
+  max-height: none;
+  margin: 0;
+  padding: 0;
+  overflow: hidden;
+  border: 0;
+  background: transparent;
+  color: #fff;
+}
+
+[data-mk-lightbox-dialog][open] {
+  display: grid;
+  place-items: center;
+}
+
+[data-mk-lightbox-dialog]::backdrop {
+  background: transparent;
+}
+
+[data-mk-lightbox='backdrop'] {
+  position: absolute;
+  inset: 0;
+  background: rgb(8 8 10 / 0.82);
+  backdrop-filter: blur(20px);
+}
+
+[data-mk-lightbox='stage'] {
+  position: relative;
+  display: grid;
+  justify-items: center;
+  gap: 0.85rem;
+  margin: 0;
+  pointer-events: none;
+}
+
+[data-mk-lightbox='image'] {
+  display: block;
+  max-width: min(92vw, 1100px);
+  max-height: 78dvh;
+  border-radius: 16px;
+  object-fit: contain;
+  box-shadow: 0 30px 70px -30px rgb(0 0 0 / 0.7);
+  cursor: grab;
+  pointer-events: auto;
+  touch-action: none;
+  user-select: none;
+}
+
+[data-mk-lightbox-dialog][data-mk-zoomed] [data-mk-lightbox='image'] {
+  cursor: move;
+}
+
+[data-mk-lightbox='caption'] {
+  max-width: min(36rem, 90vw);
+  padding: 0.4rem 0.9rem;
+  border-radius: 64px;
+  background: rgb(255 255 255 / 0.1);
+  color: rgb(255 255 255 / 0.85);
+  font-size: 0.875rem;
+  text-align: center;
+}
+
+[data-mk-lightbox='caption'][hidden] {
+  display: none;
+}
+
+[data-mk-lightbox-dialog] button[data-mk-lightbox] {
+  position: absolute;
+  display: grid;
+  place-items: center;
+  width: 3rem;
+  height: 3rem;
+  padding: 0;
+  border: 0;
+  border-radius: 50%;
+  background: rgb(255 255 255 / 0.12);
+  box-shadow:
+    inset 1px 1px 1px rgb(255 255 255 / 0.16),
+    inset -1px -1px 1px rgb(255 255 255 / 0.06);
+  backdrop-filter: blur(16px);
+  color: #fff;
+  cursor: pointer;
+  transition:
+    background-color 0.2s ease,
+    scale 0.4s cubic-bezier(0.38, 0.49, 0, 1.5);
+}
+
+[data-mk-lightbox-dialog] button[data-mk-lightbox]:hover:not(:disabled) {
+  background: rgb(255 255 255 / 0.22);
+  scale: 1.08;
+}
+
+[data-mk-lightbox-dialog] button[data-mk-lightbox]:focus-visible {
+  outline: 2px solid #fff;
+  outline-offset: 3px;
+}
+
+[data-mk-lightbox-dialog] button[data-mk-lightbox]:disabled {
+  opacity: 0.3;
+  cursor: default;
+}
+
+[data-mk-lightbox-dialog] button[data-mk-lightbox][hidden] {
+  display: none;
+}
+
+[data-mk-lightbox='close'] {
+  top: 1rem;
+  right: 1rem;
+}
+
+[data-mk-lightbox='prev'] {
+  left: 1rem;
+  top: 50%;
+  margin-top: -1.5rem;
+}
+
+[data-mk-lightbox='next'] {
+  right: 1rem;
+  top: 50%;
+  margin-top: -1.5rem;
+}
+
+[data-mk-lightbox='count'] {
+  position: absolute;
+  top: 1.6rem;
+  left: 50%;
+  display: inline-flex;
+  padding: 0.25rem 0.75rem;
+  border-radius: 64px;
+  background: rgb(255 255 255 / 0.1);
+  font-size: 0.8125rem;
+  font-variant-numeric: tabular-nums;
+  translate: -50% 0;
+}
+
+@media (max-width: 680px) {
+  [data-mk-lightbox='prev'],
+  [data-mk-lightbox='next'] {
+    top: auto;
+    bottom: 1.25rem;
+    margin: 0;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :is(.mk-image-preview, mk-image-preview) [data-mk-image],
+  [data-mk-lightbox-dialog] button[data-mk-lightbox] {
+    transition: none;
+    scale: none !important;
+  }
+}

package/src/components/image-preview/react.tsx

@@ -0,0 +1,43 @@
+'use client';
+import { useRef, type HTMLAttributes, type MutableRefObject } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createImagePreview, type ImagePreviewInstance, type ImagePreviewOptions } from './engine';
+
+export interface PreviewImage {
+  src: string;
+  /** Smaller image for the thumbnail (default: src). */
+  thumb?: string;
+  alt: string;
+  caption?: string;
+}
+
+export interface ImagePreviewProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'>, ImagePreviewOptions {
+  images: PreviewImage[];
+  instanceRef?: MutableRefObject<ImagePreviewInstance | null>;
+}
+
+/** <ImagePreview images={[{ src, thumb, alt, caption }]} />: a grid of thumbnails that open a viewer. */
+export function ImagePreview({ images, labels, loop, onChange, onOpenChange, instanceRef, className, ...props }: ImagePreviewProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const change = useLatest(onChange);
+  const openChange = useLatest(onOpenChange);
+  const key = JSON.stringify(labels ?? {});
+  useIsomorphicLayoutEffect(() => {
+    const created = createImagePreview(ref.current, { labels, loop, onChange: (i) => change.current?.(i), onOpenChange: (open) => openChange.current?.(open) });
+    if (instanceRef) instanceRef.current = created;
+    return () => {
+      created.destroy();
+      if (instanceRef) instanceRef.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key, loop]);
+  return (
+    <div {...props} ref={ref} className={['mk-image-preview', className].filter(Boolean).join(' ')}>
+      {images.map((image, i) => (
+        <button key={`${image.src}-${i}`} type="button" data-mk-image="" data-mk-src={image.src} data-mk-caption={image.caption} aria-label={`Ver ${image.alt}`}>
+          <img src={image.thumb ?? image.src} alt={image.alt} loading="lazy" decoding="async" />
+        </button>
+      ))}
+    </div>
+  );
+}

package/src/components/json-viewer/README.md

@@ -0,0 +1,56 @@
+# json-viewer
+
+Visualizador de JSON con nodos expandibles, montado sobre `tree-view`. Muestra cada clave con su valor coloreado por tipo: textos en verde, números en azul, booleanos en violeta y `null` atenuado en cursiva; los colores (`"#7c5cff"`, `"rgb(…)"`) llevan su muestra. Los objetos y las listas se resumen («6 claves», «3 elementos») y se abren por niveles con el movimiento del árbol: la altura crece (.32 s, curva signature), los hijos salen de un blur y la flecha gira.
+
+Cada fila tiene un botón de copiar que se vuelve una palomita con un pop; Ctrl/⌘ + C copia el valor de la fila enfocada. La búsqueda resalta claves y valores y abre lo que los contiene. Con `setData()` se conserva lo abierto: los valores que cambiaron destellan un momento en el acento y las claves nuevas entran saliendo de un blur, ideal para respuestas que llegan en vivo. La ruta de la fila seleccionada (`$.user.roles[0]`) aparece abajo, lista para copiar.
+
+## HTML / Astro
+
+```html
+<mk-json-viewer class="mk-json-viewer" expand-depth="2" search
+  data='{"user":{"name":"Ana","roles":["admin","editor"],"color":"#7c5cff"},"total":1250.5}'></mk-json-viewer>
+
+<!-- O el JSON escrito dentro: -->
+<mk-json-viewer class="mk-json-viewer" root-name="respuesta">
+  <script type="application/json">{ "ok": true, "items": [1, 2, 3] }</script>
+</mk-json-viewer>
+
+<script>
+  const viewer = document.querySelector('mk-json-viewer');
+  viewer.addEventListener('mk:copy', (event) => console.log('Copiado', event.detail.path));
+</script>
+```
+
+## React
+
+```tsx
+<JsonViewer data={respuesta} expandDepth={2} search onSelect={(path, value) => console.log(path, value)} />
+```
+
+Cambiar `data` conserva lo abierto y marca lo que cambió.
+
+## Opciones
+
+| Opción | Atributo | Por defecto | Qué hace |
+|---|---|---|---|
+| `data` | `data` (JSON) | el JSON escrito dentro | El valor a mostrar. |
+| `expandDepth` | `expand-depth` | `1` | Niveles abiertos al empezar: `1` muestra las claves de arriba cerradas, `2` las abre… (`Infinity`, todo). |
+| `rootName` | `root-name` | — | Una fila para el valor completo con este nombre; sin ella, las claves de arriba son las primeras filas. |
+| `search` | `search` | `false` | Campo de búsqueda; un texto es su marcador. |
+| `toolbar` | `toolbar` | `true` | Botones para expandir, contraer y copiar todo. |
+| `sortKeys` | `sort-keys` | `false` | Claves en orden alfabético. |
+| `label` | `label` | `'Datos JSON'` | Nombre accesible. |
+| `onSelect(path, value)` | — | — | Se seleccionó una fila. |
+| `onCopy(text, path)` | — | — | Se copió un valor. |
+
+## API y eventos
+
+`setData(data)`, `expandAll()`, `collapseAll()`, `reveal(path)`, `filter(texto)`, `copy(path = '$')` (promesa: `true` si se copió), `data`, `destroy()`. Eventos `mk:select` con `{ path, value }` y `mk:copy` con `{ text, path }`. El ayudante `jsonPath(padre, clave)` arma rutas como las del visor.
+
+## Variables CSS
+
+`--mk-jv-height` (alto máximo antes de desplazarse dentro), `--mk-jv-string`, `--mk-jv-number`, `--mk-jv-boolean` (colores de los valores; cambian solos en modo oscuro).
+
+## Accesibilidad
+
+Es un árbol de WAI-ARIA con todo su teclado (↑ ↓, → abre, ← cierra, `*`, Inicio, Fin, escribir para saltar), con Ctrl/⌘ + C para copiar sin buscar el botón. Los botones de copiar no son paradas de tabulación y dicen qué copian («Copiar $.user.name»). Un estado discreto anuncia cada copia, las coincidencias y lo que cambió con datos nuevos. Con movimiento reducido no hay destellos ni animaciones.

package/src/components/json-viewer/element.ts

@@ -0,0 +1,37 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createJsonViewer, type JsonViewerInstance } from './engine';
+
+/**
+ * <mk-json-viewer class="mk-json-viewer" expand-depth="2" search data='{"user":{"name":"Ana","roles":["admin"]}}'></mk-json-viewer>
+ * Or the JSON as the element's text. Emits mk:select ({path, value}) and mk:copy ({text, path}).
+ */
+export class MkJsonViewerElement extends MkElement<JsonViewerInstance> {
+  static options: Record<string, OptionType> = {
+    data: 'json',
+    expandDepth: 'number',
+    rootName: 'string',
+    search: 'string',
+    toolbar: 'boolean',
+    sortKeys: 'boolean',
+    label: 'string',
+  };
+
+  protected create(options: Record<string, unknown>) {
+    // search="" (present without text) turns the field on with its default placeholder.
+    const search = this.hasAttribute('search') ? (this.getAttribute('search') || true) : undefined;
+    return createJsonViewer(this, { ...options, search });
+  }
+
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.instance) return;
+    if (name === 'data') {
+      try {
+        this.instance.setData(JSON.parse(next ?? 'null'));
+      } catch {
+        // Malformed JSON: keep the current data.
+      }
+    } else super.attributeChangedCallback(name, previous, next);
+  }
+}
+
+export const defineJsonViewer = () => defineElement('mk-json-viewer', MkJsonViewerElement);