@yewdiel21/motion-kit 0.9.1 → 0.14.0

package/src/components/link-preview/element.ts

@@ -0,0 +1,29 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createLinkPreview, type LinkPreviewInstance } from './engine';
+
+/**
+ * <mk-link-preview class="mk-link-preview" url="https://…" title="…" description="…" image="/thumb.jpg" site-name="Blog"></mk-link-preview>
+ * variant="hover" turns it into a link that previews the card (label = link text).
+ */
+export class MkLinkPreviewElement extends MkElement<LinkPreviewInstance> {
+  static options: Record<string, OptionType> = {
+    url: 'string',
+    title: 'string',
+    description: 'string',
+    image: 'string',
+    imageAlt: 'string',
+    siteName: 'string',
+    variant: 'string',
+    label: 'string',
+    target: 'string',
+    openDelay: 'number',
+    closeDelay: 'number',
+    placement: 'string',
+  };
+
+  protected create(options: Record<string, unknown>) {
+    return createLinkPreview(this, options);
+  }
+}
+
+export const defineLinkPreview = () => defineElement('mk-link-preview', MkLinkPreviewElement);

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

@@ -0,0 +1,192 @@
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { createHoverCard, type HoverCardInstance, type HoverCardOptions } from '../hover-card/engine';
+
+/*
+ * Link preview: a resource card (thumbnail or domain initial, site, title,
+ * description) around a real link, or a link that previews that card in a
+ * hover card (pointer, focus, tap). The app supplies the metadata; nothing is
+ * fetched. Links accept http(s) and relative URLs only; strings are text; a
+ * thumbnail that fails to load gives way to the domain initial.
+ * Made into an empty root; with authored markup ([data-mk-link-card],
+ * img[data-mk-link-image], [data-mk-hover-trigger]) only the behaviour is added.
+ */
+
+/** card: image on top (default); row: thumbnail beside the text; hover: a link that previews the card. */
+export type LinkPreviewVariant = 'card' | 'row' | 'hover';
+
+/** The arrow of the card's go button (decorative). */
+const GO_ICON =
+  '<svg aria-hidden="true" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M7 17L17 7M9 7h8v8"/></svg>';
+
+export interface LinkPreviewOptions extends Pick<HoverCardOptions, 'openDelay' | 'closeDelay' | 'placement' | 'onOpenChange'> {
+  url?: string;
+  title?: string;
+  description?: string;
+  /** Thumbnail URL (http(s), relative, data:image or blob). */
+  image?: string;
+  imageAlt?: string;
+  siteName?: string;
+  variant?: LinkPreviewVariant;
+  /** Text of the hover variant's link (default: the title). */
+  label?: string;
+  /** '_blank' opens a new tab (with rel="noopener noreferrer"). */
+  target?: string;
+}
+
+export interface LinkPreviewInstance extends Instance {
+  /** The link actually used (null when the URL was refused). */
+  readonly href: string | null;
+  readonly hoverCard: HoverCardInstance | null;
+}
+
+// Browsers drop tabs/newlines inside URLs ("java\nscript:"): check what they will see.
+const squash = (url: string) => url.replace(/[\u0000- \u007f]+/g, '');
+const schemeOf = (url: string) => /^([a-z][a-z\d+.-]*):/i.exec(squash(url))?.[1]?.toLowerCase() ?? null;
+
+/** http(s) or relative links; anything else (javascript:, data:, vbscript:…) is null. */
+export function safeHref(url: string | null | undefined): string | null {
+  if (typeof url !== 'string' || !url.trim()) return null;
+  const scheme = schemeOf(url.trim());
+  return scheme === null || scheme === 'http' || scheme === 'https' ? url.trim() : null;
+}
+
+/** Image sources: http(s), relative, blob: and data:image/… */
+export function safeImage(url: string | null | undefined): string | null {
+  if (typeof url !== 'string' || !url.trim()) return null;
+  const value = url.trim();
+  const scheme = schemeOf(value);
+  if (scheme === null || scheme === 'http' || scheme === 'https' || scheme === 'blob') return value;
+  return scheme === 'data' && /^data:image\//i.test(squash(value)) ? value : null;
+}
+
+/** Host without www. of an absolute link; relative links have none (same on server and client). */
+export function linkDomain(href: string | null) {
+  if (!href) return '';
+  try {
+    return new URL(href.startsWith('//') ? `https:${href}` : href).hostname.replace(/^www\./, '');
+  } catch {
+    return '';
+  }
+}
+
+let sequence = 0;
+
+const part = (tag: string, name: string, text?: string) => {
+  const element = document.createElement(tag);
+  element.dataset.mkPart = name;
+  if (text !== undefined) element.textContent = text;
+  return element;
+};
+
+/** The card markup (also used by the hover panel). Text only; the href is already safe. */
+function buildCard(options: LinkPreviewOptions, href: string | null) {
+  const domain = linkDomain(href);
+  // Spans (not divs): the hover variant lives inside running text.
+  const card = document.createElement(href ? 'a' : 'span');
+  card.dataset.mkLinkCard = '';
+  if (href) {
+    card.setAttribute('href', href);
+    if (options.target) {
+      card.setAttribute('target', options.target);
+      if (options.target === '_blank') card.setAttribute('rel', 'noopener noreferrer');
+    }
+  }
+  const id = `mk-link-${++sequence}`;
+  const media = part('span', 'media');
+  const fallback = part('span', 'fallback', (options.siteName || domain || options.title || '?').trim().charAt(0).toUpperCase());
+  fallback.setAttribute('aria-hidden', 'true');
+  media.append(fallback);
+  const image = safeImage(options.image);
+  if (image) {
+    const img = document.createElement('img');
+    img.dataset.mkLinkImage = '';
+    img.alt = options.imageAlt ?? '';
+    img.loading = 'lazy';
+    img.decoding = 'async';
+    img.src = image;
+    media.append(img);
+  }
+  const text = part('span', 'text');
+  const site = [options.siteName, domain].filter(Boolean).filter((value, i, all) => all.indexOf(value) === i).join(' · ');
+  if (site) {
+    const meta = part('span', 'meta');
+    const favicon = part('span', 'favicon', (options.siteName || domain).trim().charAt(0).toUpperCase());
+    favicon.setAttribute('aria-hidden', 'true');
+    meta.append(favicon, part('span', 'site', site));
+    text.append(meta);
+  }
+  const title = part('span', 'title', options.title || domain || href || '');
+  title.id = `${id}-title`;
+  text.append(title);
+  if (options.description) {
+    const description = part('span', 'description', options.description);
+    description.id = `${id}-description`;
+    text.append(description);
+    card.setAttribute('aria-describedby', description.id);
+  }
+  card.setAttribute('aria-labelledby', title.id);
+  const go = part('span', 'go');
+  go.setAttribute('aria-hidden', 'true');
+  go.innerHTML = GO_ICON;
+  card.append(media, text, go);
+  return card;
+}
+
+export function createLinkPreview(root: HTMLElement | null, options: LinkPreviewOptions = {}): LinkPreviewInstance {
+  if (!root) return inert({ href: null, hoverCard: null });
+  const scope = createScope();
+  const variant: LinkPreviewVariant = options.variant === 'hover' || options.variant === 'row' ? options.variant : 'card';
+  const href = safeHref(options.url);
+  const authored = root.querySelector('[data-mk-link-card], [data-mk-hover-trigger]');
+  const made: Node[] = [];
+  if (!authored) {
+    const card = buildCard(options, href);
+    if (variant === 'hover') {
+      const trigger = document.createElement(href ? 'a' : 'span');
+      trigger.dataset.mkHoverTrigger = '';
+      if (href) trigger.setAttribute('href', href);
+      else trigger.tabIndex = 0;
+      if (href && options.target) {
+        trigger.setAttribute('target', options.target);
+        if (options.target === '_blank') trigger.setAttribute('rel', 'noopener noreferrer');
+      }
+      trigger.textContent = options.label || options.title || linkDomain(href) || href || '';
+      const panel = document.createElement('span');
+      panel.dataset.mkHoverPanel = '';
+      panel.setAttribute('role', 'region');
+      panel.setAttribute('aria-label', `Vista previa: ${options.title || linkDomain(href)}`);
+      panel.hidden = true;
+      panel.append(card);
+      made.push(trigger, panel);
+    } else made.push(card);
+    root.append(...made);
+    scope.add(() => made.forEach((node) => node.parentNode?.removeChild(node)));
+  }
+  scope.attr(root, 'data-mk-link-variant', variant);
+  if (variant === 'hover' && !root.classList.contains('mk-hover-card')) {
+    scope.attr(root, 'class', root.getAttribute('class'));
+    root.classList.add('mk-hover-card');
+  }
+  scope.attr(root, 'data-mk-ready', '');
+
+  // A thumbnail that fails gives way to the initial (listeners go with destroy).
+  for (const img of root.querySelectorAll<HTMLImageElement>('img[data-mk-link-image]')) {
+    const failed = () => {
+      scope.attr(img, 'hidden', '');
+      scope.attr(root, 'data-mk-image', 'error');
+    };
+    scope.on(img, 'error', failed);
+  }
+
+  const hoverCard = root.querySelector('[data-mk-hover-trigger]') ? createHoverCard(root, options) : null;
+  if (hoverCard) scope.add(() => hoverCard.destroy());
+
+  return {
+    get href() {
+      return href ?? root.querySelector<HTMLAnchorElement>('a[data-mk-link-card], a[data-mk-hover-trigger]')?.getAttribute('href') ?? null;
+    },
+    hoverCard,
+    destroy: () => scope.dispose(),
+  };
+}

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

@@ -0,0 +1,274 @@
+/* link-preview — Melonmind content box: a 24 px card with the image on top (16 px inner radius, 8 px inset), favicon and
+   site, a two-line title, the description and a round go button that springs on hover. Row: thumbnail beside the text.
+   Hover: the card in Melonmind's inverse glass popover. */
+.mk-link-preview,
+mk-link-preview {
+  --mk-link-radius: var(--mk-radius-lg, 24px);
+  --mk-link-inset: 8px;
+  --mk-link-thumb: 5.5rem;
+  display: block;
+  color: var(--mk-text);
+  font-family: var(--mk-font);
+}
+
+:is(.mk-link-preview, mk-link-preview)[data-mk-link-variant='hover'] {
+  display: inline-flex;
+}
+
+:is(.mk-link-preview, mk-link-preview) [data-mk-link-card] {
+  position: relative;
+  display: grid;
+  gap: 0;
+  padding: var(--mk-link-inset);
+  border-radius: var(--mk-link-radius);
+  background: var(--mk-surface-1);
+  box-shadow: inset 0 0 0 1px var(--mk-outline-soft);
+  color: inherit;
+  text-decoration: none;
+  transition:
+    translate 0.5s var(--mk-ease-signature, cubic-bezier(0.2, 0.8, 0.2, 1)),
+    box-shadow 0.3s ease;
+}
+
+:is(.mk-link-preview, mk-link-preview) a[data-mk-link-card]:hover {
+  translate: 0 -3px;
+  box-shadow:
+    inset 0 0 0 1px var(--mk-outline-soft),
+    0 18px 40px -22px color-mix(in srgb, var(--mk-shadow-color) 45%, transparent);
+}
+
+:is(.mk-link-preview, mk-link-preview) a[data-mk-link-card]:active {
+  animation: mk-link-press 500ms cubic-bezier(0.37, 1.42, 0.37, 1);
+}
+
+:is(.mk-link-preview, mk-link-preview) a[data-mk-link-card]:focus-visible,
+:is(.mk-link-preview, mk-link-preview) [data-mk-hover-trigger]:focus-visible {
+  outline: 2px solid var(--mk-accent);
+  outline-offset: 3px;
+}
+
+:is(.mk-link-preview, mk-link-preview) [data-mk-part='media'] {
+  position: relative;
+  display: grid;
+  place-items: center;
+  overflow: hidden;
+  aspect-ratio: 16 / 9;
+  border-radius: calc(var(--mk-link-radius) - var(--mk-link-inset));
+  background: var(--mk-surface-3);
+  color: var(--mk-muted);
+}
+
+:is(.mk-link-preview, mk-link-preview) [data-mk-part='fallback'] {
+  font-size: clamp(2rem, 8vw, 3.5rem);
+  font-weight: 500;
+  letter-spacing: -0.04em;
+}
+
+:is(.mk-link-preview, mk-link-preview) [data-mk-link-image] {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  transition: scale 0.7s var(--mk-ease-signature, cubic-bezier(0.2, 0.8, 0.2, 1));
+}
+
+:is(.mk-link-preview, mk-link-preview) a[data-mk-link-card]:hover [data-mk-link-image] {
+  scale: 1.04;
+}
+
+:is(.mk-link-preview, mk-link-preview) [data-mk-link-image][hidden] {
+  display: none;
+}
+
+:is(.mk-link-preview, mk-link-preview) [data-mk-part='text'] {
+  display: grid;
+  gap: 0.35rem;
+  min-width: 0;
+  padding: 0.85rem 3.25rem 0.6rem 0.6rem;
+}
+
+:is(.mk-link-preview, mk-link-preview) [data-mk-part='meta'] {
+  display: flex;
+  align-items: center;
+  gap: 0.45rem;
+  min-width: 0;
+}
+
+:is(.mk-link-preview, mk-link-preview) [data-mk-part='favicon'] {
+  display: grid;
+  flex: none;
+  place-items: center;
+  width: 1.25rem;
+  height: 1.25rem;
+  border-radius: 50%;
+  background: var(--mk-text);
+  color: var(--mk-bg);
+  font-size: 0.6875rem;
+  font-weight: 600;
+}
+
+:is(.mk-link-preview, mk-link-preview) [data-mk-part='site'] {
+  overflow: hidden;
+  color: var(--mk-muted);
+  font-size: 0.8125rem;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+:is(.mk-link-preview, mk-link-preview) [data-mk-part='title'] {
+  font-size: 1.0625rem;
+  font-weight: 500;
+  line-height: 1.25;
+  letter-spacing: -0.01em;
+  display: -webkit-box;
+  overflow: hidden;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 2;
+}
+
+:is(.mk-link-preview, mk-link-preview) [data-mk-part='description'] {
+  color: var(--mk-muted);
+  font-size: 0.875rem;
+  line-height: 1.4;
+  display: -webkit-box;
+  overflow: hidden;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 2;
+}
+
+/* The go button: bottom right, it turns and fills on hover (Melonmind playful curve). */
+:is(.mk-link-preview, mk-link-preview) [data-mk-part='go'] {
+  position: absolute;
+  right: calc(var(--mk-link-inset) + 0.5rem);
+  bottom: calc(var(--mk-link-inset) + 0.5rem);
+  display: grid;
+  place-items: center;
+  width: 2.5rem;
+  height: 2.5rem;
+  border-radius: 50%;
+  background: var(--mk-surface-3);
+  color: var(--mk-text);
+  rotate: 45deg;
+  transition:
+    rotate 0.4s cubic-bezier(0.38, 0.49, 0, 2),
+    background-color 0.2s ease,
+    color 0.2s ease,
+    scale 0.4s cubic-bezier(0.38, 0.49, 0, 1.5);
+}
+
+:is(.mk-link-preview, mk-link-preview) a[data-mk-link-card]:is(:hover, :focus-visible) [data-mk-part='go'] {
+  rotate: 0deg;
+  scale: 1.08;
+  background: var(--mk-text);
+  color: var(--mk-bg);
+}
+
+:is(.mk-link-preview, mk-link-preview) span[data-mk-link-card] [data-mk-part='go'] {
+  display: none;
+}
+
+/* Row: the thumbnail beside the text. */
+:is(.mk-link-preview, mk-link-preview)[data-mk-link-variant='row'] [data-mk-link-card] {
+  grid-template-columns: var(--mk-link-thumb) minmax(0, 1fr);
+  align-items: center;
+  gap: 0.25rem;
+  border-radius: var(--mk-radius-md, 16px);
+}
+
+:is(.mk-link-preview, mk-link-preview)[data-mk-link-variant='row'] [data-mk-part='media'] {
+  aspect-ratio: 1;
+  border-radius: 10px;
+}
+
+:is(.mk-link-preview, mk-link-preview)[data-mk-link-variant='row'] [data-mk-part='fallback'] {
+  font-size: 2rem;
+}
+
+:is(.mk-link-preview, mk-link-preview)[data-mk-link-variant='row'] [data-mk-part='text'] {
+  padding: 0.25rem 3.25rem 0.25rem 0.75rem;
+}
+
+:is(.mk-link-preview, mk-link-preview)[data-mk-link-variant='row'] [data-mk-part='go'] {
+  top: 50%;
+  bottom: auto;
+  margin-top: -1.25rem;
+}
+
+/* Hover: an underlined link; the card sits in the inverse glass. */
+:is(.mk-link-preview, mk-link-preview) [data-mk-hover-trigger] {
+  color: inherit;
+  font-weight: 500;
+  text-decoration: underline;
+  text-decoration-color: color-mix(in srgb, currentColor 35%, transparent);
+  text-decoration-thickness: 1.5px;
+  text-underline-offset: 0.22em;
+  cursor: pointer;
+  transition: text-decoration-color 0.2s ease;
+}
+
+:is(.mk-link-preview, mk-link-preview) [data-mk-hover-trigger]:hover {
+  text-decoration-color: currentColor;
+}
+
+:is(.mk-link-preview, mk-link-preview) [data-mk-hover-panel] {
+  width: min(20rem, calc(100vw - 1.5rem));
+  padding: 0;
+  border: 0;
+  border-radius: var(--mk-link-radius);
+  background: var(--mk-glass-inverse);
+  box-shadow: var(--mk-glass-bevel);
+  backdrop-filter: blur(16px);
+  color: var(--mk-on-glass-inverse);
+}
+
+:is(.mk-link-preview, mk-link-preview) [data-mk-hover-panel] [data-mk-link-card] {
+  background: transparent;
+  box-shadow: none;
+  translate: none;
+}
+
+:is(.mk-link-preview, mk-link-preview) [data-mk-hover-panel] [data-mk-part='media'] {
+  background: color-mix(in srgb, var(--mk-on-glass-inverse) 12%, transparent);
+  color: var(--mk-on-glass-inverse);
+}
+
+:is(.mk-link-preview, mk-link-preview) [data-mk-hover-panel] :is([data-mk-part='site'], [data-mk-part='description']) {
+  color: color-mix(in srgb, var(--mk-on-glass-inverse) 70%, transparent);
+}
+
+:is(.mk-link-preview, mk-link-preview) [data-mk-hover-panel] [data-mk-part='favicon'] {
+  background: var(--mk-on-glass-inverse);
+  color: var(--mk-text);
+}
+
+:is(.mk-link-preview, mk-link-preview) [data-mk-hover-panel] [data-mk-part='go'] {
+  background: color-mix(in srgb, var(--mk-on-glass-inverse) 14%, transparent);
+  color: var(--mk-on-glass-inverse);
+}
+
+:is(.mk-link-preview, mk-link-preview) [data-mk-hover-panel] a[data-mk-link-card]:is(:hover, :focus-visible) [data-mk-part='go'] {
+  background: var(--mk-on-glass-inverse);
+  color: var(--mk-text);
+}
+
+@keyframes mk-link-press {
+  50% {
+    transform: scale(0.97, 0.95);
+  }
+}
+
+@media (max-width: 420px) {
+  :is(.mk-link-preview, mk-link-preview) {
+    --mk-link-thumb: 4.25rem;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :is(.mk-link-preview, mk-link-preview) :is([data-mk-link-card], [data-mk-link-image], [data-mk-part='go']) {
+    transition: none;
+    animation: none !important;
+    translate: none !important;
+    scale: none !important;
+  }
+}

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

@@ -0,0 +1,101 @@
+'use client';
+import { useEffect, useId, useRef, useState, type HTMLAttributes } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createHoverCard } from '../hover-card/engine';
+import { linkDomain, safeHref, safeImage, type LinkPreviewOptions } from './engine';
+
+export interface LinkPreviewProps extends Omit<HTMLAttributes<HTMLElement>, 'title'>, LinkPreviewOptions {}
+
+function Card({ url, title, description, image, imageAlt, siteName, target }: LinkPreviewOptions) {
+  const id = useId();
+  const href = safeHref(url);
+  const domain = linkDomain(href);
+  const source = safeImage(image);
+  const [failed, setFailed] = useState(false);
+  useEffect(() => setFailed(false), [source]);
+  const site = [siteName, domain].filter(Boolean).filter((value, i, all) => all.indexOf(value) === i).join(' · ');
+  const content = (
+    <>
+      <span data-mk-part="media">
+        <span data-mk-part="fallback" aria-hidden="true">
+          {(siteName || domain || title || '?').trim().charAt(0).toUpperCase()}
+        </span>
+        {source && !failed ? <img data-mk-link-image="" src={source} alt={imageAlt ?? ''} loading="lazy" decoding="async" onError={() => setFailed(true)} /> : null}
+      </span>
+      <span data-mk-part="text">
+        {site && (
+          <span data-mk-part="meta">
+            <span data-mk-part="favicon" aria-hidden="true">
+              {(siteName || domain).trim().charAt(0).toUpperCase()}
+            </span>
+            <span data-mk-part="site">{site}</span>
+          </span>
+        )}
+        <span data-mk-part="title" id={`${id}-title`}>
+          {title || domain || href}
+        </span>
+        {description && (
+          <span data-mk-part="description" id={`${id}-description`}>
+            {description}
+          </span>
+        )}
+      </span>
+      <span data-mk-part="go" aria-hidden="true">
+        <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={2} strokeLinecap="round" strokeLinejoin="round">
+          <path d="M7 17L17 7M9 7h8v8" />
+        </svg>
+      </span>
+    </>
+  );
+  const labelled = { 'aria-labelledby': `${id}-title`, 'aria-describedby': description ? `${id}-description` : undefined };
+  return href ? (
+    <a data-mk-link-card="" href={href} target={target} rel={target === '_blank' ? 'noopener noreferrer' : undefined} {...labelled}>
+      {content}
+    </a>
+  ) : (
+    <span data-mk-link-card="" {...labelled}>
+      {content}
+    </span>
+  );
+}
+
+/**
+ * <LinkPreview url="https://…" title="…" description="…" image="/thumb.jpg" siteName="Blog" />, or
+ * variant="hover" for a link that previews the card on pointer, focus or tap. Metadata comes from the app.
+ */
+export function LinkPreview({ url, title, description, image, imageAlt, siteName, variant = 'card', label, target, openDelay, closeDelay, placement, onOpenChange, className, ...props }: LinkPreviewProps) {
+  const ref = useRef<HTMLSpanElement>(null);
+  const change = useLatest(onOpenChange);
+  const href = safeHref(url);
+  const hover = variant === 'hover';
+  useIsomorphicLayoutEffect(() => {
+    if (!hover) return;
+    const instance = createHoverCard(ref.current, { openDelay, closeDelay, placement, onOpenChange: (open) => change.current?.(open) });
+    return () => instance.destroy();
+  }, [hover, openDelay, closeDelay, placement]);
+  const card = <Card url={url} title={title} description={description} image={image} imageAlt={imageAlt} siteName={siteName} target={target} />;
+  if (!hover) {
+    return (
+      <div {...props} className={['mk-link-preview', className].filter(Boolean).join(' ')} data-mk-link-variant={variant === 'row' ? 'row' : 'card'}>
+        {card}
+      </div>
+    );
+  }
+  const text = label || title || linkDomain(href) || href;
+  return (
+    <span {...props} ref={ref} className={['mk-link-preview mk-hover-card', className].filter(Boolean).join(' ')} data-mk-link-variant="hover">
+      {href ? (
+        <a data-mk-hover-trigger="" href={href} target={target} rel={target === '_blank' ? 'noopener noreferrer' : undefined}>
+          {text}
+        </a>
+      ) : (
+        <span data-mk-hover-trigger="" tabIndex={0}>
+          {text}
+        </span>
+      )}
+      <span data-mk-hover-panel="" role="region" aria-label={`Vista previa: ${title || linkDomain(href)}`} hidden>
+        {card}
+      </span>
+    </span>
+  );
+}

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

@@ -0,0 +1,45 @@
+# loading-button
+
+Botón que muestra su trabajo. Al pulsarlo (o con `run()`) hace el press de Melon Mind, su texto se desvanece con blur y entra un indicador de carga mientras el botón se desliza a su nuevo ancho (.4 s, curva swing). En éxito pasa al color de éxito con una marca que se dibuja sola (.35 s) y rebota; en error pasa al color de error, se sacude y dibuja una cruz. Tras `resetAfter` vuelve a su texto.
+
+## HTML / Astro
+
+```html
+<mk-loading-button>
+  <button class="mk-button mk-button--primary">Guardar cambios</button>
+</mk-loading-button>
+<script>
+  const save = document.querySelector('mk-loading-button');
+  save.addEventListener('click', () => save.run(() => fetch('/api/guardar', { method: 'POST' })));
+</script>
+```
+
+El atributo `state` (`idle`, `loading`, `success`, `error`) lo controla desde fuera.
+
+## React
+
+```tsx
+<LoadingButton className="mk-button mk-button--primary" action={() => api.save(form)} labels={{ success: 'Guardado' }}>
+  Guardar cambios
+</LoadingButton>
+```
+
+Con `action`, la promesa decide el resultado (se resuelve → éxito; se rechaza → error). Sin ella, `state` lo controla.
+
+## Opciones
+
+| Opción | Atributo | Por defecto | Qué hace |
+|---|---|---|---|
+| `action` | — | — | Se ejecuta al pulsar; su promesa recorre los estados. |
+| `labels` | `labels` (JSON) | Cargando… / Listo / Error | Textos que se anuncian (y se muestran si no es compacto). |
+| `compact` | `compact` | `true` | Solo el icono mientras trabaja; con `false`, icono y texto. |
+| `resetAfter` | `reset-after` | `1800` | ms en éxito o error antes de volver; `0` se queda. |
+| `onStateChange(state)` | — | — | Cada cambio de estado. |
+
+## API y eventos
+
+`setState(state)`, `run(action?)` (resuelve `true` si salió bien), `state`, `destroy()`. Evento `mk:state-change` con `{ state }`.
+
+## Accesibilidad y estilo
+
+Mientras carga sigue siendo enfocable pero no responde (`aria-disabled`, `aria-busy`), y un estado discreto junto a él dice qué pasó. El botón conserva su propio estilo (`.mk-button` o el tuyo); el componente añade los colores de estado (`--mk-loading-success`, `--mk-error`) en `data-mk-state`. Con movimiento reducido el indicador queda quieto y no hay deslizamientos ni sacudida.

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

@@ -0,0 +1,34 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createLoadingButton, type LoadingButtonInstance, type LoadingState } from './engine';
+
+/**
+ * <mk-loading-button><button class="mk-button">Guardar</button></mk-loading-button>
+ * The `state` attribute (idle | loading | success | error) drives it from outside; run(action) walks the states.
+ * Emits mk:state-change ({state}).
+ */
+export class MkLoadingButtonElement extends MkElement<LoadingButtonInstance> {
+  static options: Record<string, OptionType> = { labels: 'json', compact: 'boolean', resetAfter: 'number', state: 'string' };
+
+  protected create(options: Record<string, unknown>) {
+    const { state, ...rest } = options as { state?: LoadingState };
+    const instance = createLoadingButton(this, rest);
+    if (state) instance.setState(state);
+    return instance;
+  }
+
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.instance) return;
+    if (name === 'state') this.instance.setState((next as LoadingState) || 'idle');
+    else super.attributeChangedCallback(name, previous, next);
+  }
+
+  run(action: () => unknown) {
+    return this.instance?.run(action) ?? Promise.resolve(false);
+  }
+
+  get state() {
+    return this.instance?.state ?? 'idle';
+  }
+}
+
+export const defineLoadingButton = () => defineElement('mk-loading-button', MkLoadingButtonElement);