@yewdiel21/motion-kit 0.9.1 → 0.14.0

package/src/components/json-viewer/json-viewer.css

@@ -0,0 +1,271 @@
+/* json-viewer — the tree in a monospace face inside a 12 px box on surface-2: keys in the text colour, a muted colon,
+   values by type (strings green, numbers blue, booleans violet, null muted and italic; colours with a swatch), objects
+   and lists as muted brackets and a count. Rows are 1.875rem; the copy button shows on hover or focus (always on touch
+   screens). A bar above (search, expand, collapse, copy) and the selected path below. Values that change flash in the
+   accent; new keys come in out of a blur. Give it a height with --mk-jv-height. */
+.mk-json-viewer,
+mk-json-viewer {
+  --mk-jv-height: none;
+  --mk-jv-string: #187a47;
+  --mk-jv-number: #2d5fc4;
+  --mk-jv-boolean: #8a3fc8;
+  display: grid;
+  gap: 0.5rem;
+  min-width: 0;
+  color: var(--mk-text);
+  font-family: var(--mk-font-mono, ui-monospace, SFMono-Regular, Menlo, Consolas, monospace);
+  font-size: 0.8125rem;
+}
+
+@media (prefers-color-scheme: dark) {
+  :where(:root:not([data-mk-mode='light'])) :is(.mk-json-viewer, mk-json-viewer) {
+    --mk-jv-string: #62d39b;
+    --mk-jv-number: #8db5ff;
+    --mk-jv-boolean: #cba0ff;
+  }
+}
+
+:where(:root[data-mk-mode='dark']) :is(.mk-json-viewer, mk-json-viewer) {
+  --mk-jv-string: #62d39b;
+  --mk-jv-number: #8db5ff;
+  --mk-jv-boolean: #cba0ff;
+}
+
+[data-mk-jv-bar] {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  min-width: 0;
+}
+
+[data-mk-jv-search] {
+  box-sizing: border-box;
+  flex: 1 1 auto;
+  min-width: 0;
+  height: 2.25rem;
+  padding: 0 0.75rem;
+  border: 0;
+  border-radius: 12px;
+  outline: none;
+  background: var(--mk-surface-3);
+  color: inherit;
+  font: inherit;
+}
+
+[data-mk-jv-search]:focus-visible {
+  box-shadow: 0 0 0 3px color-mix(in srgb, var(--mk-accent) 35%, transparent);
+}
+
+[data-mk-jv-tools] {
+  display: flex;
+  flex: none;
+  gap: 0.125rem;
+  margin-left: auto;
+}
+
+[data-mk-jv-tool],
+[data-mk-jv-copy] {
+  display: inline-grid;
+  flex: none;
+  place-items: center;
+  width: 2rem;
+  height: 2rem;
+  padding: 0;
+  border: 0;
+  border-radius: 8px;
+  background: transparent;
+  color: var(--mk-muted);
+  cursor: pointer;
+  transition:
+    background-color 0.15s,
+    color 0.15s,
+    opacity 0.15s;
+}
+
+[data-mk-jv-tool]:hover,
+[data-mk-jv-copy]:hover {
+  background: color-mix(in srgb, var(--mk-text) 8%, transparent);
+  color: var(--mk-text);
+}
+
+[data-mk-jv-tool]:focus-visible {
+  outline: 2px solid var(--mk-accent);
+  outline-offset: 1px;
+}
+
+[data-mk-jv-tool][data-mk-copied],
+[data-mk-jv-copy][data-mk-copied] {
+  color: var(--mk-accent);
+  opacity: 1;
+}
+
+[data-mk-jv-tree] {
+  max-height: var(--mk-jv-height);
+  overflow: auto;
+  padding: 0.375rem;
+  border: 1px solid var(--mk-outline-soft);
+  border-radius: 12px;
+  background: var(--mk-surface-2);
+  overscroll-behavior: contain;
+}
+
+[data-mk-jv-tree] [data-mk-tree-row] {
+  min-height: 1.875rem;
+  padding-right: 0.25rem;
+}
+
+[data-mk-jv-tree] [data-mk-tree-label] {
+  display: flex;
+  align-items: center;
+  gap: 0.375rem;
+}
+
+[data-mk-jv-key] {
+  flex: 0 0 auto;
+  max-width: 45%;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+[data-mk-jv-key='name'] {
+  font-weight: 600;
+}
+
+[data-mk-jv-key='index'] {
+  color: var(--mk-muted);
+}
+
+[data-mk-jv-colon] {
+  flex: none;
+  margin-left: -0.375rem;
+  color: var(--mk-muted);
+}
+
+[data-mk-jv-value] {
+  flex: 0 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  border-radius: 4px;
+  text-overflow: ellipsis;
+}
+
+[data-mk-jv-value='string'] {
+  color: var(--mk-jv-string);
+}
+
+[data-mk-jv-value='number'] {
+  color: var(--mk-jv-number);
+}
+
+[data-mk-jv-value='boolean'] {
+  color: var(--mk-jv-boolean);
+  font-weight: 600;
+}
+
+[data-mk-jv-value='null'] {
+  color: var(--mk-muted);
+  font-style: italic;
+}
+
+[data-mk-jv-swatch] {
+  display: inline-block;
+  width: 0.75rem;
+  height: 0.75rem;
+  margin-right: 0.375rem;
+  border-radius: 4px;
+  box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--mk-text) 20%, transparent);
+  vertical-align: -0.1em;
+}
+
+[data-mk-jv-brackets] {
+  flex: none;
+  color: var(--mk-muted);
+}
+
+[data-mk-jv-summary] {
+  flex: 0 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  color: var(--mk-muted);
+  font-size: 0.75rem;
+  text-overflow: ellipsis;
+}
+
+[data-mk-jv-copy] {
+  width: 1.625rem;
+  height: 1.625rem;
+  margin-left: auto;
+  border-radius: 6px;
+  opacity: 0;
+}
+
+[data-mk-tree-row]:hover [data-mk-jv-copy],
+[role='treeitem']:focus-visible > [data-mk-tree-row] [data-mk-jv-copy] {
+  opacity: 1;
+}
+
+@media (hover: none) {
+  [data-mk-jv-copy] {
+    opacity: 0.7;
+  }
+}
+
+[data-mk-jv-changed] {
+  animation: mk-jv-flash 1.6s cubic-bezier(0.38, 0.49, 0, 1) both;
+}
+
+@keyframes mk-jv-flash {
+  0%,
+  30% {
+    background: color-mix(in srgb, var(--mk-accent) 26%, transparent);
+    box-shadow: 0 0 0 3px color-mix(in srgb, var(--mk-accent) 26%, transparent);
+  }
+
+  100% {
+    background: transparent;
+    box-shadow: 0 0 0 3px transparent;
+  }
+}
+
+[data-mk-jv-added] {
+  animation: mk-jv-added 0.55s ease-out both;
+}
+
+@keyframes mk-jv-added {
+  from {
+    opacity: 0;
+    filter: blur(6px);
+    transform: translateX(-8px);
+  }
+}
+
+[data-mk-jv-foot] {
+  display: flex;
+  align-items: center;
+  gap: 0.25rem;
+  min-width: 0;
+}
+
+[data-mk-jv-foot][hidden] {
+  display: none;
+}
+
+[data-mk-jv-path] {
+  min-width: 0;
+  overflow: hidden;
+  padding: 0.25rem 0.5rem;
+  border-radius: 6px;
+  background: var(--mk-surface-3);
+  color: var(--mk-text);
+  font: inherit;
+  font-size: 0.75rem;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-mk-jv-changed],
+  [data-mk-jv-added] {
+    animation: none;
+  }
+}

package/src/components/json-viewer/react.tsx

@@ -0,0 +1,56 @@
+'use client';
+import { forwardRef, useImperativeHandle, useRef, type HTMLAttributes } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createJsonViewer, type JsonViewerInstance, type JsonViewerOptions } from './engine';
+
+export interface JsonViewerProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onSelect' | 'onCopy' | 'children'>, JsonViewerOptions {}
+
+export type JsonViewerHandle = Pick<JsonViewerInstance, 'expandAll' | 'collapseAll' | 'reveal' | 'filter' | 'copy'>;
+
+/** <JsonViewer data={response} expandDepth={2} search />. New data keeps what was open and flashes what changed. */
+export const JsonViewer = forwardRef<JsonViewerHandle, JsonViewerProps>(function JsonViewer(
+  { data, expandDepth, rootName, search, toolbar, sortKeys, label, onSelect, onCopy, className, ...props },
+  handle,
+) {
+  const ref = useRef<HTMLDivElement>(null);
+  const instance = useRef<JsonViewerInstance | null>(null);
+  const select = useLatest(onSelect);
+  const copied = useLatest(onCopy);
+  const shown = useRef(data);
+  useImperativeHandle(
+    handle,
+    () => ({
+      expandAll: () => instance.current?.expandAll(),
+      collapseAll: () => instance.current?.collapseAll(),
+      reveal: (path) => instance.current?.reveal(path),
+      filter: (query) => instance.current?.filter(query),
+      copy: (path) => instance.current?.copy(path) ?? Promise.resolve(false),
+    }),
+    [],
+  );
+  useIsomorphicLayoutEffect(() => {
+    const created = createJsonViewer(ref.current, {
+      data: shown.current,
+      expandDepth,
+      rootName,
+      search,
+      toolbar,
+      sortKeys,
+      label,
+      onSelect: (path, value) => select.current?.(path, value),
+      onCopy: (text, path) => copied.current?.(text, path),
+    });
+    instance.current = created;
+    return () => {
+      created.destroy();
+      instance.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [expandDepth, rootName, String(search), toolbar, sortKeys, label]);
+  useIsomorphicLayoutEffect(() => {
+    if (shown.current === data) return;
+    shown.current = data;
+    instance.current?.setData(data);
+  }, [data]);
+  return <div {...props} ref={ref} className={['mk-json-viewer', className].filter(Boolean).join(' ')} />;
+});

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

@@ -0,0 +1,13 @@
+# like-button
+
+Botón de «me gusta» con corazón y contador (`aria-pressed`). Al darle: el corazón se encoge, se rellena desde el centro y rebota a 1.25 con curva elástica, salen un anillo y siete pares de partículas y el contador rueda hacia arriba. Al quitarlo, el relleno se vacía y el contador rueda hacia abajo.
+
+```html
+<mk-like-button class="mk-like-button" count="128"></mk-like-button>
+```
+
+`defineElements()`, `createLikeButton(root, options)` (root es el botón o lo contiene) o `<LikeButton count={128} onChange={(liked, count) => save(liked)} />` (con `liked` es controlado; `defaultLiked` si no).
+
+Opciones: `liked=false`, `count=0`, `label='Me gusta'` (nombre accesible; el número visible se suma al nombre), `hideCount`, `onChange(liked, count)`. API: `setLiked(liked, notify=true)`, `setCount(n)`, `liked`, `count`, `destroy()`. Evento `mk:change` con `{liked, count}`. Cifras grandes en notación compacta.
+
+Variables: `--mk-like-color` (#f43f5e), `--mk-like-color-2` (partículas). Movimiento reducido: el estado cambia sin rebote ni partículas.

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

@@ -0,0 +1,47 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createLikeButton, type LikeButtonInstance } from './engine';
+
+/**
+ * <mk-like-button class="mk-like-button" count="128"><button></button></mk-like-button>
+ * Toggles with a burst; emits mk:change ({liked, count}).
+ */
+export class MkLikeButtonElement extends MkElement<LikeButtonInstance> {
+  static options: Record<string, OptionType> = { liked: 'boolean', count: 'number', label: 'string', hideCount: 'boolean' };
+
+  protected create(options: Record<string, unknown>) {
+    // Without a button inside, one is made (and removed again on destroy).
+    let made: HTMLButtonElement | null = null;
+    if (!this.querySelector('button')) {
+      made = document.createElement('button');
+      made.type = 'button';
+      this.append(made);
+    }
+    const engine = createLikeButton(this, options);
+    if (made) {
+      const destroy = engine.destroy;
+      engine.destroy = () => {
+        destroy();
+        made!.remove();
+      };
+    }
+    return engine;
+  }
+
+  // A new `liked` or `count` attribute updates in place (with the animation).
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.instance) return;
+    if (name === 'liked') this.instance.setLiked(next !== null && next !== 'false', false);
+    else if (name === 'count') this.instance.setCount(Number(next));
+    else super.attributeChangedCallback(name, previous, next);
+  }
+
+  get liked() {
+    return this.instance?.liked ?? false;
+  }
+
+  get count() {
+    return this.instance?.count ?? 0;
+  }
+}
+
+export const defineLikeButton = () => defineElement('mk-like-button', MkLikeButtonElement);

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

@@ -0,0 +1,145 @@
+import { gsap, ELASTIC, EASE, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { numberFormat } from '../../core/dates';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { burst, rollDigits } from '../../motion/micro';
+
+/*
+ * Like button: a heart and a count on a toggle button (aria-pressed). Liking it
+ * squeezes the heart, fills it from the centre and springs it to 1.25 and back
+ * (elastic), a ring and seven pairs of particles fly out, and the count rolls up.
+ * Unliking empties the heart with a small dip and rolls the count down.
+ */
+
+export interface LikeButtonOptions {
+  liked?: boolean;
+  count?: number;
+  /** Accessible name (default 'Me gusta'). */
+  label?: string;
+  /** Hide the count. */
+  hideCount?: boolean;
+  onChange?: (liked: boolean, count: number) => void;
+}
+
+export interface LikeButtonInstance extends Instance {
+  setLiked(liked: boolean, notify?: boolean): void;
+  setCount(count: number): void;
+  readonly liked: boolean;
+  readonly count: number;
+}
+
+const SVG = 'http://www.w3.org/2000/svg';
+const HEART = 'M12 20.5s-7.5-4.6-7.5-10.1A4.4 4.4 0 0 1 12 7.6a4.4 4.4 0 0 1 7.5 2.8c0 5.5-7.5 10.1-7.5 10.1z';
+
+export function createLikeButton(root: HTMLElement | null, options: LikeButtonOptions = {}): LikeButtonInstance {
+  const button = root ? ((root.matches('button') ? root : root.querySelector('button')) as HTMLButtonElement | null) : null;
+  if (!root || !button) return inert({ setLiked() {}, setCount() {}, liked: false, count: 0 });
+  registerMotion();
+  const scope = createScope();
+  let liked = Boolean(options.liked);
+  let count = Math.max(0, Math.round(Number.isFinite(options.count) ? options.count! : 0));
+  const format = (n: number) => numberFormat(root, { notation: n >= 10000 ? 'compact' : 'standard' }).format(n);
+
+  const made: Element[] = [];
+  scope.add(() => made.forEach((element) => element.remove()));
+  const icon = document.createElementNS(SVG, 'svg');
+  icon.setAttribute('viewBox', '0 0 24 24');
+  icon.setAttribute('aria-hidden', 'true');
+  icon.dataset.mkLikeIcon = '';
+  const outline = document.createElementNS(SVG, 'path');
+  outline.setAttribute('d', HEART);
+  outline.dataset.mkPart = 'outline';
+  const fill = document.createElementNS(SVG, 'path');
+  fill.setAttribute('d', HEART);
+  fill.dataset.mkPart = 'fill';
+  icon.append(outline, fill);
+  const name = document.createElement('span');
+  name.className = 'mk-sr-only';
+  name.textContent = options.label ?? 'Me gusta';
+  const counter = document.createElement('span');
+  counter.dataset.mkLikeCount = '';
+  counter.hidden = Boolean(options.hideCount);
+  button.prepend(icon);
+  button.append(name, counter);
+  made.push(icon, name, counter);
+
+  scope.attr(button, 'type', button.getAttribute('type') ?? 'button');
+  scope.attr(button, 'data-mk-like', '');
+  scope.attr(root, 'data-mk-ready', '');
+
+  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);
+  };
+  scope.add(() => {
+    for (const effect of effects) effect.kill();
+    effects.clear();
+    gsap.killTweensOf([icon, fill]);
+  });
+
+  const paint = () => {
+    scope.attr(button, 'aria-pressed', String(liked));
+    gsap.set(fill, { scale: liked ? 1 : 0, transformOrigin: '50% 55%' });
+    counter.textContent = format(count);
+  };
+
+  const animate = (on: boolean, previous: number) => {
+    keep(rollDigits(counter, format(count), count >= previous ? 1 : -1, 0.4));
+    if (reduced()) return;
+    gsap.killTweensOf([icon, fill]);
+    if (on) {
+      keep(
+        gsap
+          .timeline()
+          .to(icon, { scale: 0.7, duration: 0.12, ease: 'power2.in' })
+          .fromTo(fill, { scale: 0 }, { scale: 1, duration: 0.3, ease: EASE.pop, transformOrigin: '50% 55%' }, '<0.05')
+          .to(icon, { scale: 1, duration: 0.9, ease: ELASTIC, clearProps: 'scale,transform' }, '<'),
+      );
+      keep(burst(button, { count: 7, distance: 30, colors: ['var(--mk-like-color)', 'var(--mk-like-color-2)'] }));
+    } else {
+      keep(
+        gsap
+          .timeline()
+          .to(fill, { scale: 0, duration: 0.25, ease: 'power2.in', transformOrigin: '50% 55%' })
+          .fromTo(icon, { scale: 0.85 }, { scale: 1, duration: 0.5, ease: EASE.click, clearProps: 'scale,transform' }, 0),
+      );
+    }
+  };
+
+  const setLiked = (next: boolean, notify = true) => {
+    if (scope.disposed || next === liked) return;
+    const previous = count;
+    liked = next;
+    count = Math.max(0, count + (next ? 1 : -1));
+    scope.attr(button, 'aria-pressed', String(liked));
+    animate(liked, previous);
+    if (reduced()) paint();
+    if (!notify) return;
+    options.onChange?.(liked, count);
+    root.dispatchEvent(new CustomEvent('mk:change', { bubbles: true, detail: { liked, count } }));
+  };
+
+  scope.on(button, 'click', () => setLiked(!liked));
+  paint();
+
+  return {
+    setLiked,
+    setCount(next) {
+      if (scope.disposed || !Number.isFinite(next)) return;
+      const previous = count;
+      count = Math.max(0, Math.round(next));
+      if (count !== previous) keep(rollDigits(counter, format(count), count >= previous ? 1 : -1, 0.4));
+    },
+    get liked() {
+      return liked;
+    },
+    get count() {
+      return count;
+    },
+    destroy: () => scope.dispose(),
+  };
+}

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

@@ -0,0 +1,77 @@
+/* like-button — a Melonmind tonal pill with a heart and a count; liked, the heart fills with the like colour. */
+.mk-like-button,
+mk-like-button {
+  display: inline-flex;
+}
+
+[data-mk-like] {
+  --mk-like-color: #f43f5e;
+  --mk-like-color-2: #fb923c;
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.45rem;
+  min-height: 2.75rem;
+  padding: 0 1rem 0 0.8rem;
+  border: 0;
+  border-radius: 64px;
+  background: var(--mk-surface-3);
+  color: var(--mk-text);
+  font: inherit;
+  font-weight: 500;
+  font-variant-numeric: tabular-nums;
+  cursor: pointer;
+  transition:
+    background-color 0.2s ease,
+    padding 400ms cubic-bezier(0.38, 0.49, 0, 2);
+}
+
+[data-mk-like]:hover {
+  background: var(--mk-surface-4);
+  padding-inline: 0.95rem 1.15rem;
+}
+
+[data-mk-like][aria-pressed='true'] {
+  background: color-mix(in srgb, var(--mk-like-color) 14%, var(--mk-surface-3));
+}
+
+[data-mk-like]:focus-visible {
+  outline: 2px solid var(--mk-accent);
+  outline-offset: 3px;
+}
+
+[data-mk-like] [data-mk-like-icon] {
+  width: 1.5rem;
+  height: 1.5rem;
+  overflow: visible;
+}
+
+[data-mk-like] [data-mk-part='outline'] {
+  fill: none;
+  stroke: currentColor;
+  stroke-width: 1.8;
+  stroke-linejoin: round;
+}
+
+[data-mk-like] [data-mk-part='fill'] {
+  fill: var(--mk-like-color);
+}
+
+[data-mk-like][aria-pressed='true'] [data-mk-part='outline'] {
+  stroke: var(--mk-like-color);
+}
+
+[data-mk-like] [data-mk-like-count] {
+  display: inline-flex;
+  min-width: 1ch;
+}
+
+[data-mk-like] [data-mk-like-count][hidden] {
+  display: none;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-mk-like] {
+    transition: none;
+  }
+}

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

@@ -0,0 +1,39 @@
+'use client';
+import { useRef, type ButtonHTMLAttributes } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createLikeButton, type LikeButtonInstance } from './engine';
+
+export interface LikeButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onChange' | 'children'> {
+  /** Controlled state; without it the button keeps its own. */
+  liked?: boolean;
+  defaultLiked?: boolean;
+  count?: number;
+  label?: string;
+  hideCount?: boolean;
+  onChange?: (liked: boolean, count: number) => void;
+}
+
+/** <LikeButton count={128} onChange={(liked, count) => save(liked)} />. */
+export function LikeButton({ liked, defaultLiked, count = 0, label, hideCount, onChange, className, ...props }: LikeButtonProps) {
+  const ref = useRef<HTMLButtonElement>(null);
+  const instance = useRef<LikeButtonInstance | null>(null);
+  const change = useLatest(onChange);
+  const start = useRef({ liked: liked ?? defaultLiked ?? false, count });
+  useIsomorphicLayoutEffect(() => {
+    const created = createLikeButton(ref.current, { ...start.current, label, hideCount, onChange: (next, total) => change.current?.(next, total) });
+    instance.current = created;
+    return () => {
+      start.current = { liked: created.liked, count: created.count };
+      created.destroy();
+      instance.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [label, hideCount]);
+  useIsomorphicLayoutEffect(() => {
+    if (liked !== undefined && instance.current && instance.current.liked !== liked) instance.current.setLiked(liked, false);
+  }, [liked]);
+  useIsomorphicLayoutEffect(() => {
+    if (instance.current && instance.current.count !== count) instance.current.setCount(count);
+  }, [count]);
+  return <button type="button" {...props} ref={ref} className={['mk-like-button', className].filter(Boolean).join(' ')} />;
+}

package/src/components/link-preview/README.md

@@ -0,0 +1,19 @@
+# link-preview
+
+Tarjeta de enlace con miniatura (o la inicial del dominio), sitio, título y descripción alrededor de un enlace real; o un enlace que previsualiza esa tarjeta en un [hover-card](../hover-card/README.md) al señalar, enfocar o tocar. La app suministra los metadatos: no se descarga nada ni depende de un backend.
+
+```html
+<mk-link-preview class="mk-link-preview"
+  url="https://example.com/guia" title="Guía de movimiento" description="Curvas, duraciones y cuándo no animar."
+  image="/thumbs/guia.jpg" site-name="Motion Kit"></mk-link-preview>
+
+<p>Lee la <mk-link-preview class="mk-link-preview" variant="hover" label="guía de movimiento" url="https://example.com/guia" title="Guía de movimiento"></mk-link-preview>.</p>
+```
+
+`defineElements()`, `createLinkPreview(root, options)` o `<LinkPreview url="…" title="…" description="…" image="…" siteName="…" variant="hover" label="guía" />`.
+
+Opciones: `url`, `title`, `description`, `image`, `imageAlt` (por defecto decorativa), `siteName`, `variant='card'|'row'|'hover'` (`row`: miniatura al lado del texto), `label` (texto del enlace en hover), `target` (`_blank` añade `rel="noopener noreferrer"`) y, en hover, `openDelay`, `closeDelay`, `placement`, `onOpenChange`. API: `href` (el enlace usado o `null`), `hoverCard`, `destroy()`. Utilidades: `safeHref(url)`, `safeImage(url)`, `linkDomain(href)`.
+
+Los enlaces aceptan sólo http(s) y rutas relativas: `javascript:`, `data:` u otros esquemas (también con espacios o saltos intercalados) dejan una tarjeta sin enlace. Las imágenes aceptan http(s), relativas, `blob:` y `data:image/…`. Todos los textos se insertan como texto. Si la miniatura falla, se oculta y queda la inicial (`data-mk-image="error"`); después de `destroy()` no hay listeners que cambien nada.
+
+Con root vacío el motor crea el marcado y lo quita al destruir; con marcado propio (`[data-mk-link-card]`, `img[data-mk-link-image]`, `[data-mk-hover-trigger]` + `[data-mk-hover-panel]`) sólo añade el comportamiento. La tarjeta sigue a Melon Mind: imagen 16:9 con 8px de margen, inicial del sitio, título a dos líneas, descripción y un botón redondo que gira al señalar; en hover, la tarjeta va dentro del cristal inverso. Variables: `--mk-link-radius` (24px), `--mk-link-thumb` (5.5rem). Movimiento reducido quita la escala al pulsar y el giro.