@yewdiel21/motion-kit 0.10.0 → 0.14.0

package/src/components/attachment/engine.ts

@@ -0,0 +1,469 @@
+import { gsap } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { blurIn, blurOut, collapse, shake } from '../../motion/micro';
+
+/*
+ * Attachment: native file chooser plus drop zone, and a card per file with
+ * name, type, size, upload progress/status and a remove button. Files are
+ * validated (accept, maxSize, maxFiles) and rejected with a reason; accepted
+ * ones are kept when more arrive. The app owns the upload: it reads
+ * onFiles / mk:files and reports back with setProgress(id, value, status).
+ * Image previews are object URLs, revoked when the file leaves or on destroy.
+ * Parts (made when absent): [data-mk-attachment-input], [data-mk-attachment-drop],
+ * [data-mk-attachment-list].
+ */
+
+export type AttachmentStatus = 'idle' | 'uploading' | 'complete' | 'error';
+export type AttachmentRejectCode = 'type' | 'size' | 'count';
+
+export interface AttachmentFile {
+  id: string;
+  name: string;
+  size: number;
+  type: string;
+  /** The picked File (absent for files described by metadata only). */
+  file?: File;
+  /** 0–100 once the app reports it. */
+  progress?: number;
+  status: AttachmentStatus;
+  /** Object URL of an image preview, or a URL supplied with initialFiles. */
+  preview?: string;
+}
+
+export interface AttachmentRejection {
+  file: File;
+  code: AttachmentRejectCode;
+  message: string;
+}
+
+export interface AttachmentLabels {
+  choose?: string;
+  drop?: string;
+  remove?: string;
+  list?: string;
+  uploading?: string;
+  complete?: string;
+  error?: string;
+  added?: (count: number) => string;
+  removed?: (name: string) => string;
+  rejected?: (rejection: { name: string; code: AttachmentRejectCode; limit: string }) => string;
+}
+
+export interface AttachmentOptions {
+  /** Like input[accept]: extensions (.pdf), MIME types (image/png) and wildcards (image/*). */
+  accept?: string;
+  multiple?: boolean;
+  /** Most files kept (multiple only). */
+  maxFiles?: number;
+  /** Largest file, in bytes. */
+  maxSize?: number;
+  disabled?: boolean;
+  /** Form name of the file input (it carries the kept files where the browser allows). */
+  name?: string;
+  /** Files shown from the start (e.g. already uploaded). */
+  initialFiles?: Array<Partial<AttachmentFile> & { name: string }>;
+  /** Visible hint under the drop text (default: the limits). */
+  hint?: string;
+  labels?: AttachmentLabels;
+  onFiles?: (added: AttachmentFile[], files: AttachmentFile[]) => void;
+  onRemove?: (removed: AttachmentFile, files: AttachmentFile[]) => void;
+  onReject?: (rejections: AttachmentRejection[]) => void;
+}
+
+export interface AttachmentInstance extends Instance {
+  /** Validate and add files; returns the accepted ones. */
+  addFiles(files: Iterable<File> | ArrayLike<File>): AttachmentFile[];
+  remove(id: string): void;
+  /** Report upload progress (0–100) and, optionally, the status. */
+  setProgress(id: string, value: number, status?: AttachmentStatus): void;
+  clear(): void;
+  readonly files: AttachmentFile[];
+}
+
+const DEFAULT_LABELS = {
+  choose: 'Elige archivos',
+  drop: 'o arrástralos aquí',
+  remove: 'Quitar',
+  list: 'Archivos adjuntos',
+  uploading: 'Subiendo',
+  complete: 'Listo',
+  error: 'Error al subir',
+  added: (count: number) => (count === 1 ? '1 archivo añadido' : `${count} archivos añadidos`),
+  removed: (name: string) => `${name} quitado`,
+  rejected: ({ name, code, limit }: { name: string; code: AttachmentRejectCode; limit: string }) =>
+    code === 'type' ? `${name}: tipo no permitido` : code === 'size' ? `${name}: supera ${limit}` : `${name}: máximo ${limit}`,
+} satisfies Required<AttachmentLabels>;
+
+let sequence = 0;
+
+/** 1 KB = 1024 B; one decimal under 10. */
+export function formatBytes(bytes: number) {
+  if (!Number.isFinite(bytes) || bytes < 0) return '';
+  const units = ['B', 'KB', 'MB', 'GB'];
+  let value = bytes;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit += 1;
+  }
+  const digits = unit && value < 10 ? 1 : 0;
+  return `${new Intl.NumberFormat(undefined, { maximumFractionDigits: digits }).format(value)} ${units[unit]}`;
+}
+
+const KINDS: Record<string, string> = { image: 'imágenes', video: 'vídeos', audio: 'audio', text: 'texto' };
+
+/** Readable accept list: image/* → imágenes, .pdf → PDF, application/zip → ZIP. */
+export function describeAccept(accept: string | undefined) {
+  return (accept ?? '')
+    .split(',')
+    .map((rule) => rule.trim().toLowerCase())
+    .filter(Boolean)
+    .map((rule) => (rule.startsWith('.') ? rule.slice(1).toUpperCase() : rule.endsWith('/*') ? KINDS[rule.slice(0, -2)] ?? rule : (rule.split('/')[1] ?? rule).toUpperCase()))
+    .filter((label, i, all) => all.indexOf(label) === i)
+    .join(', ');
+}
+
+/** Does a file match an accept list (extensions, MIME types, type/*)? */
+export function acceptsFile(file: { name: string; type: string }, accept: string | undefined) {
+  const rules = (accept ?? '').split(',').map((rule) => rule.trim().toLowerCase()).filter(Boolean);
+  if (!rules.length) return true;
+  const name = file.name.toLowerCase();
+  const type = (file.type || '').toLowerCase();
+  return rules.some((rule) => {
+    if (rule.startsWith('.')) return name.endsWith(rule);
+    if (rule.endsWith('/*')) return type.startsWith(rule.slice(0, -1));
+    return type === rule;
+  });
+}
+
+const extension = (name: string) => {
+  const dot = name.lastIndexOf('.');
+  return dot > 0 && dot < name.length - 1 ? name.slice(dot + 1).slice(0, 4).toUpperCase() : 'FILE';
+};
+const canPreview = (type: string) => /^image\//i.test(type) && typeof URL !== 'undefined' && typeof URL.createObjectURL === 'function';
+
+export function createAttachment(root: HTMLElement | null, options: AttachmentOptions = {}): AttachmentInstance {
+  if (!root) return inert({ addFiles: () => [], remove() {}, setProgress() {}, clear() {}, files: [] });
+  const scope = createScope();
+  const labels = { ...DEFAULT_LABELS, ...options.labels };
+  const multiple = options.multiple ?? false;
+  const maxFiles = multiple ? (options.maxFiles && options.maxFiles > 0 ? Math.floor(options.maxFiles) : Infinity) : 1;
+  const maxSize = options.maxSize && options.maxSize > 0 ? options.maxSize : Infinity;
+  const disabled = options.disabled ?? false;
+  const files: AttachmentFile[] = [];
+  const rows = new Map<string, HTMLElement>();
+  /** Rows on their way out (removed when their exit ends, or on destroy). */
+  const leaving = new Set<HTMLElement>();
+  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);
+  };
+  /** Object URLs this instance made (revoked when their file leaves). */
+  const owned = new Set<string>();
+
+  const made = <K extends keyof HTMLElementTagNameMap>(tag: K, parent: Element = root) => {
+    const element = document.createElement(tag);
+    parent.append(element);
+    scope.add(() => element.remove());
+    return element;
+  };
+
+  let drop = root.querySelector<HTMLElement>('[data-mk-attachment-drop]');
+  let input = root.querySelector<HTMLInputElement>('input[type="file"][data-mk-attachment-input], [data-mk-attachment-drop] input[type="file"]');
+  if (!drop) {
+    drop = made('label');
+    drop.dataset.mkAttachmentDrop = '';
+    const icon = document.createElement('span');
+    icon.dataset.mkPart = 'icon';
+    icon.setAttribute('aria-hidden', 'true');
+    const text = document.createElement('span');
+    text.dataset.mkPart = 'prompt';
+    const choose = document.createElement('strong');
+    choose.textContent = labels.choose;
+    text.append(choose, ` ${labels.drop}`);
+    const hint = document.createElement('small');
+    hint.dataset.mkPart = 'hint';
+    const kinds = describeAccept(options.accept);
+    const limits = [kinds && kinds.charAt(0).toUpperCase() + kinds.slice(1), Number.isFinite(maxSize) ? `hasta ${formatBytes(maxSize)}` : '', Number.isFinite(maxFiles) && multiple ? `máx. ${maxFiles} archivos` : '']
+      .filter(Boolean)
+      .join(' · ');
+    hint.textContent = options.hint ?? limits;
+    drop.append(icon, text);
+    if (hint.textContent) drop.append(hint);
+  }
+  if (!input) {
+    input = made('input', drop);
+    input.type = 'file';
+    input.dataset.mkAttachmentInput = '';
+  }
+  let list = root.querySelector<HTMLElement>('[data-mk-attachment-list]');
+  if (!list) {
+    list = made('ul');
+    list.dataset.mkAttachmentList = '';
+  }
+  const error = made('p');
+  error.dataset.mkAttachmentError = '';
+  error.setAttribute('role', 'alert');
+  error.hidden = true;
+  const status = made('p');
+  status.dataset.mkAttachmentStatus = '';
+  status.className = 'mk-sr-only';
+  status.setAttribute('role', 'status');
+
+  scope.attr(input, 'accept', options.accept ?? input.getAttribute('accept'));
+  scope.attr(input, 'multiple', multiple ? '' : null);
+  scope.attr(input, 'disabled', disabled ? '' : null);
+  if (options.name) scope.attr(input, 'name', options.name);
+  scope.attr(list, 'aria-label', list.getAttribute('aria-label') ?? labels.list);
+  scope.attr(root, 'data-mk-ready', '');
+  scope.attr(root, 'data-mk-disabled', disabled ? '' : null);
+
+  const snapshot = (file: AttachmentFile): AttachmentFile => ({ ...file });
+  const all = () => files.map(snapshot);
+  const announce = (text: string) => {
+    status.textContent = text;
+  };
+
+  const describe = (file: AttachmentFile) => {
+    const parts = [extension(file.name), formatBytes(file.size)];
+    if (file.status === 'uploading') parts.push(`${labels.uploading} ${Math.round(file.progress ?? 0)} %`);
+    else if (file.status === 'complete') parts.push(labels.complete);
+    else if (file.status === 'error') parts.push(labels.error);
+    return parts.filter(Boolean).join(' · ');
+  };
+
+  const paint = (file: AttachmentFile) => {
+    const row = rows.get(file.id);
+    if (!row) return;
+    row.dataset.mkStatus = file.status;
+    row.querySelector<HTMLElement>('[data-mk-part="detail"]')!.textContent = describe(file);
+    const progress = row.querySelector('progress')!;
+    progress.hidden = file.progress === undefined || file.status === 'idle';
+    progress.value = file.progress ?? 0;
+  };
+
+  const renderRow = (file: AttachmentFile) => {
+    const row = document.createElement('li');
+    row.dataset.mkAttachmentItem = '';
+    row.dataset.mkId = file.id;
+    const thumb = document.createElement('span');
+    thumb.dataset.mkPart = 'thumb';
+    thumb.setAttribute('aria-hidden', 'true');
+    if (file.preview) {
+      const image = document.createElement('img');
+      image.alt = '';
+      image.src = file.preview;
+      image.addEventListener('error', () => image.replaceWith(extension(file.name)), { once: true });
+      thumb.append(image);
+    } else thumb.textContent = extension(file.name);
+    const meta = document.createElement('span');
+    meta.dataset.mkPart = 'meta';
+    const name = document.createElement('span');
+    name.dataset.mkPart = 'name';
+    name.textContent = file.name;
+    name.title = file.name;
+    const detail = document.createElement('span');
+    detail.dataset.mkPart = 'detail';
+    const progress = document.createElement('progress');
+    progress.max = 100;
+    progress.setAttribute('aria-label', `${labels.uploading} ${file.name}`);
+    meta.append(name, detail, progress);
+    const remove = document.createElement('button');
+    remove.type = 'button';
+    remove.dataset.mkAttachmentRemove = '';
+    remove.setAttribute('aria-label', `${labels.remove} ${file.name}`);
+    remove.disabled = disabled;
+    remove.innerHTML = '<svg aria-hidden="true" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M6 6l12 12M18 6L6 18"/></svg>';
+    row.append(thumb, meta, remove);
+    list!.append(row);
+    rows.set(file.id, row);
+    paint(file);
+  };
+
+  const revoke = (file: AttachmentFile) => {
+    if (file.preview && owned.delete(file.preview)) URL.revokeObjectURL(file.preview);
+  };
+
+  /** Where the browser allows it, the input carries the kept files for a native form submit. */
+  const syncInput = () => {
+    if (!options.name || typeof DataTransfer === 'undefined') return;
+    try {
+      const transfer = new DataTransfer();
+      for (const file of files) if (file.file) transfer.items.add(file.file);
+      input!.files = transfer.files;
+    } catch {
+      // Older engines cannot assign files: the app reads them from onFiles.
+    }
+  };
+
+  const discard = (file: AttachmentFile, notify: boolean) => {
+    const at = files.indexOf(file);
+    if (at < 0) return;
+    files.splice(at, 1);
+    revoke(file);
+    const row = rows.get(file.id);
+    rows.delete(file.id);
+    // Keep the keyboard in the list: the next remove button, else the chooser.
+    const focused = row?.contains(document.activeElement);
+    const next = [row?.nextElementSibling, row?.previousElementSibling].find((sibling) => sibling && !leaving.has(sibling as HTMLElement));
+    if (row) {
+      // Out of reach at once; it slides left, blurs and folds (Melonmind item-out-left + collapse).
+      row.inert = true;
+      row.setAttribute('aria-hidden', 'true');
+      leaving.add(row);
+      const done = () => {
+        leaving.delete(row);
+        row.remove();
+      };
+      if (reduced()) done();
+      else keep(gsap.timeline({ onComplete: done }).add(blurOut(row, { to: 'left' }) ?? gsap.timeline()).add(collapse(row) ?? gsap.timeline(), 0.18));
+    }
+    if (focused) (next?.querySelector<HTMLElement>('[data-mk-attachment-remove]') ?? input)?.focus();
+    syncInput();
+    if (!notify) return;
+    announce(labels.removed(file.name));
+    const detail = { file: snapshot(file), files: all() };
+    options.onRemove?.(detail.file, detail.files);
+    root.dispatchEvent(new CustomEvent('mk:remove', { bubbles: true, detail }));
+  };
+
+  const create = (seed: Partial<AttachmentFile> & { name: string }, source?: File): AttachmentFile => {
+    const type = seed.type ?? source?.type ?? '';
+    let preview = seed.preview;
+    // A blob URL carried over from a destroyed instance was revoked with it: make a new one.
+    if (source && canPreview(type) && (!preview || preview.startsWith('blob:'))) {
+      preview = URL.createObjectURL(source);
+      owned.add(preview);
+    }
+    const progress = Number.isFinite(seed.progress) ? Math.min(100, Math.max(0, seed.progress!)) : undefined;
+    return { id: seed.id ?? `mk-file-${++sequence}`, name: seed.name, size: seed.size ?? source?.size ?? 0, type, file: source ?? seed.file, progress, status: seed.status ?? 'idle', preview };
+  };
+
+  const addFiles = (incoming: Iterable<File> | ArrayLike<File>) => {
+    if (scope.disposed || disabled) return [];
+    const incomingFiles = Array.from(incoming as ArrayLike<File>);
+    const accepted: AttachmentFile[] = [];
+    const rejected: AttachmentRejection[] = [];
+    const reject = (file: File, code: AttachmentRejectCode) => {
+      const limit = code === 'size' ? formatBytes(maxSize) : code === 'count' ? `${maxFiles} ${maxFiles === 1 ? 'archivo' : 'archivos'}` : options.accept ?? '';
+      rejected.push({ file, code, message: labels.rejected({ name: file.name, code, limit }) });
+    };
+    for (const file of incomingFiles) {
+      if (!acceptsFile(file, options.accept)) reject(file, 'type');
+      else if (file.size > maxSize) reject(file, 'size');
+      else if (multiple && files.length + accepted.length >= maxFiles) reject(file, 'count');
+      else if (!multiple && accepted.length) reject(file, 'count');
+      else accepted.push(create({ name: file.name }, file));
+    }
+    // One file at a time: a new valid pick replaces the current one.
+    if (!multiple && accepted.length) for (const old of [...files]) discard(old, true);
+    for (const file of accepted) {
+      files.push(file);
+      renderRow(file);
+    }
+    keep(blurIn(accepted.map((file) => rows.get(file.id)!).filter(Boolean)));
+    if (rejected.length) keep(shake(drop));
+    error.hidden = !rejected.length;
+    error.textContent = rejected.map((item) => item.message).join(' · ');
+    if (accepted.length) {
+      syncInput();
+      announce(labels.added(accepted.length));
+      const detail = { added: accepted.map(snapshot), files: all() };
+      options.onFiles?.(detail.added, detail.files);
+      root.dispatchEvent(new CustomEvent('mk:files', { bubbles: true, detail }));
+    }
+    if (rejected.length) {
+      options.onReject?.(rejected);
+      for (const rejection of rejected) root.dispatchEvent(new CustomEvent('mk:reject', { bubbles: true, detail: rejection }));
+    }
+    return accepted.map(snapshot);
+  };
+
+  for (const seed of options.initialFiles ?? []) {
+    const file = create(seed, seed.file);
+    files.push(file);
+    renderRow(file);
+  }
+
+  scope.on(input, 'change', () => {
+    if (disabled || !input!.files?.length) return;
+    const picked = [...input!.files];
+    addFiles(picked);
+    // Without DataTransfer the same file could not be picked twice: clear the pick.
+    if (!options.name || typeof DataTransfer === 'undefined') input!.value = '';
+  });
+  scope.on(list, 'click', (event) => {
+    const button = (event.target as Element | null)?.closest<HTMLButtonElement>('[data-mk-attachment-remove]');
+    const id = button?.closest<HTMLElement>('[data-mk-attachment-item]')?.dataset.mkId;
+    if (!button || button.disabled || !id) return;
+    const file = files.find((item) => item.id === id);
+    if (file) discard(file, true);
+  });
+  let depth = 0;
+  const dragging = (on: boolean) => scope.attr(drop, 'data-mk-dragging', on ? '' : null);
+  const hasFiles = (event: Event) => [...((event as DragEvent).dataTransfer?.types ?? ['Files'])].includes('Files');
+  scope.on(drop, 'dragenter', (event) => {
+    if (disabled || !hasFiles(event)) return;
+    event.preventDefault();
+    depth += 1;
+    dragging(true);
+  });
+  scope.on(drop, 'dragover', (event) => {
+    if (disabled || !hasFiles(event)) return;
+    event.preventDefault();
+    const transfer = (event as DragEvent).dataTransfer;
+    if (transfer) transfer.dropEffect = 'copy';
+  });
+  scope.on(drop, 'dragleave', () => {
+    depth = Math.max(0, depth - 1);
+    if (!depth) dragging(false);
+  });
+  scope.on(drop, 'drop', (event) => {
+    event.preventDefault();
+    depth = 0;
+    dragging(false);
+    if (disabled) return;
+    const dropped = (event as DragEvent).dataTransfer?.files;
+    if (dropped?.length) addFiles(dropped);
+  });
+  scope.add(() => {
+    for (const effect of effects) effect.kill();
+    effects.clear();
+    for (const row of leaving) row.remove();
+    leaving.clear();
+    for (const file of files) revoke(file);
+    for (const row of rows.values()) row.remove();
+    rows.clear();
+  });
+
+  return {
+    addFiles,
+    remove(id) {
+      if (scope.disposed || disabled) return;
+      const file = files.find((item) => item.id === id);
+      if (file) discard(file, true);
+    },
+    setProgress(id, value, nextStatus) {
+      if (scope.disposed) return;
+      const file = files.find((item) => item.id === id);
+      if (!file || !Number.isFinite(value)) return;
+      file.progress = Math.min(100, Math.max(0, value));
+      file.status = nextStatus ?? (file.progress >= 100 ? 'complete' : 'uploading');
+      paint(file);
+      if (file.status === 'complete' || file.status === 'error') announce(`${file.name}: ${file.status === 'complete' ? labels.complete : labels.error}`);
+    },
+    clear() {
+      if (scope.disposed || disabled) return;
+      for (const file of [...files]) discard(file, true);
+    },
+    get files() {
+      return all();
+    },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/attachment/react.tsx

@@ -0,0 +1,65 @@
+'use client';
+import { useRef, type HTMLAttributes, type MutableRefObject } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createAttachment, type AttachmentFile, type AttachmentInstance, type AttachmentOptions, type AttachmentStatus } from './engine';
+
+export interface AttachmentUpload {
+  progress: number;
+  status?: AttachmentStatus;
+}
+
+export interface AttachmentProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'>, AttachmentOptions {
+  /** Upload state by file id, reported by the app (from onFiles ids). */
+  uploads?: Record<string, AttachmentUpload>;
+  /** Receives the live instance (addFiles, remove, setProgress…). */
+  instanceRef?: MutableRefObject<AttachmentInstance | null>;
+}
+
+/**
+ * <Attachment multiple accept="image/*,.pdf" maxSize={5_000_000} onFiles={upload} uploads={progressById} />.
+ * The engine draws the chooser and cards; picked files survive rerenders and option changes.
+ */
+export function Attachment({ accept, multiple, maxFiles, maxSize, disabled, name, initialFiles, hint, labels, onFiles, onRemove, onReject, uploads, instanceRef, className, ...props }: AttachmentProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const instance = useRef<AttachmentInstance | null>(null);
+  const kept = useRef<AttachmentFile[] | undefined>(undefined);
+  const files = useLatest(onFiles);
+  const removed = useLatest(onRemove);
+  const rejected = useLatest(onReject);
+  const latestUploads = useLatest(uploads);
+  const seed = useLatest(initialFiles);
+  const labelKey = JSON.stringify(labels ?? {});
+  useIsomorphicLayoutEffect(() => {
+    const created = createAttachment(ref.current, {
+      accept,
+      multiple,
+      maxFiles,
+      maxSize,
+      disabled,
+      name,
+      hint,
+      labels,
+      initialFiles: kept.current ?? seed.current,
+      onFiles: (added, all) => files.current?.(added, all),
+      onRemove: (file, all) => removed.current?.(file, all),
+      onReject: (list) => rejected.current?.(list),
+    });
+    for (const [id, upload] of Object.entries(latestUploads.current ?? {})) created.setProgress(id, upload.progress, upload.status);
+    instance.current = created;
+    if (instanceRef) instanceRef.current = created;
+    return () => {
+      kept.current = created.files;
+      created.destroy();
+      instance.current = null;
+      if (instanceRef) instanceRef.current = null;
+    };
+    // labels are compared by content (labelKey); callbacks are read through refs.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [accept, multiple, maxFiles, maxSize, disabled, name, hint, labelKey]);
+  const uploadKey = JSON.stringify(uploads ?? {});
+  useIsomorphicLayoutEffect(() => {
+    for (const [id, upload] of Object.entries(uploads ?? {})) instance.current?.setProgress(id, upload.progress, upload.status);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [uploadKey]);
+  return <div {...props} ref={ref} className={['mk-attachment', className].filter(Boolean).join(' ')} />;
+}

package/src/components/breadcrumb/README.md

@@ -0,0 +1,38 @@
+# breadcrumb
+
+Ruta de navegación jerárquica: una lista ordenada dentro de `<nav aria-label>`, donde el último elemento es la página actual (`aria-current="page"`). Cuando no cabe (o pasa de `maxItems`), los niveles intermedios se pliegan en un botón «…»; al pulsarlo aparecen en su sitio, entrando desde la izquierda con blur (40 ms entre niveles) mientras el resto se desliza para hacerles hueco.
+
+`setItems()` conserva el principio común de la ruta: lo que se queda se desliza a su nuevo sitio (resorte de reflujo), lo nuevo entra desde la derecha y la antigua página actual se vuelve enlace. Los enlaces se subrayan desde la izquierda al señalarlos.
+
+## HTML / Astro
+
+```html
+<mk-breadcrumb class="mk-breadcrumb"
+  items='[{"label":"Inicio","href":"/"},{"label":"Proyectos","href":"/proyectos"},{"label":"Melon"}]'></mk-breadcrumb>
+
+<!-- O con enlaces escritos: -->
+<div class="mk-breadcrumb" data-mk="breadcrumb"><a href="/">Inicio</a><a href="/docs">Docs</a><span>API</span></div>
+```
+
+## React
+
+```tsx
+<Breadcrumb items={path} onNavigate={(item, index, event) => { event.preventDefault(); router.push(item.href!); }} />
+```
+
+## Opciones
+
+| Opción | Atributo | Por defecto | Qué hace |
+|---|---|---|---|
+| `items` | `items` (JSON) | lo escrito dentro | `{ label, href? }[]`; el último es la página actual. |
+| `label` | `label` | `'Ruta de navegación'` | Nombre accesible del `<nav>`. |
+| `maxItems` | `max-items` | `'auto'` | Número máximo de niveles visibles; `auto` pliega solo cuando no cabe. |
+| `onNavigate(item, index, event)` | — | — | Antes de seguir un enlace; `event.preventDefault()` deja la navegación a tu router. |
+
+## API y eventos
+
+`setItems(items)`, `items`, `destroy()`. Evento `mk:navigate` con `{ item, index }`, cancelable.
+
+## Estilo
+
+Enlaces atenuados con chevrons entre niveles; la página actual en el color del texto y con elipsis como último recurso; el «…» es un botón de 8 px sobre `--mk-surface-3`. Con movimiento reducido todo cambia sin transición.

package/src/components/breadcrumb/breadcrumb.css

@@ -0,0 +1,109 @@
+/* breadcrumb — muted links separated by chevrons, the current page in the text colour; links underline from the left
+   on hover (.25 s, wipe curve); the folded middle is a small 8 px "…" button on surface-3. The row never scrolls: it
+   folds, and the current page ellipsizes as a last resort. */
+.mk-breadcrumb,
+mk-breadcrumb {
+  display: block;
+  min-width: 0;
+}
+
+[data-mk-breadcrumb-list] {
+  display: flex;
+  flex-wrap: nowrap;
+  align-items: center;
+  gap: 0.25rem;
+  min-width: 0;
+  margin: 0;
+  padding: 0;
+  overflow: hidden;
+  color: var(--mk-muted);
+  font-size: 0.875rem;
+  line-height: 1.4;
+  list-style: none;
+}
+
+[data-mk-breadcrumb-nav][data-mk-expanded] [data-mk-breadcrumb-list] {
+  flex-wrap: wrap;
+  overflow: visible;
+}
+
+[data-mk-crumb] {
+  display: inline-flex;
+  flex: none;
+  align-items: center;
+  gap: 0.25rem;
+  min-width: 0;
+}
+
+[data-mk-crumb]:last-child {
+  flex: 0 1 auto;
+}
+
+/* While the engine measures, the current page keeps its full width. */
+[data-mk-breadcrumb-nav][data-mk-measuring] [data-mk-crumb]:last-child {
+  flex: none;
+}
+
+[data-mk-crumb] + [data-mk-crumb]::before {
+  content: '';
+  flex: none;
+  width: 1rem;
+  height: 1rem;
+  background: currentColor;
+  opacity: 0.6;
+  -webkit-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M9 6l6 6-6 6' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E") center / 1rem no-repeat;
+  mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M9 6l6 6-6 6' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E") center / 1rem no-repeat;
+}
+
+[data-mk-crumb-link] {
+  padding: 0.15rem 0;
+  background: linear-gradient(currentColor, currentColor) 0 100% / 0 1px no-repeat;
+  color: inherit;
+  text-decoration: none;
+  transition: background-size 0.25s cubic-bezier(0.38, 0.49, 0, 1), color 0.2s ease;
+}
+
+[data-mk-crumb-link]:hover {
+  background-size: 100% 1px;
+  color: var(--mk-text);
+}
+
+[data-mk-crumb-link]:focus-visible,
+[data-mk-crumb-more]:focus-visible {
+  border-radius: 6px;
+  outline: 2px solid var(--mk-accent);
+  outline-offset: 2px;
+}
+
+[data-mk-crumb-current] {
+  overflow: hidden;
+  color: var(--mk-text);
+  font-weight: 600;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+[data-mk-crumb-more] {
+  height: 1.5rem;
+  padding: 0 0.45rem;
+  border: 0;
+  border-radius: 8px;
+  background: var(--mk-surface-3);
+  color: inherit;
+  font: inherit;
+  line-height: 1;
+  cursor: pointer;
+  transition: background-color 0.2s ease, color 0.2s ease;
+}
+
+[data-mk-crumb-more]:hover {
+  background: var(--mk-surface-4, var(--mk-surface-3));
+  color: var(--mk-text);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-mk-crumb-link],
+  [data-mk-crumb-more] {
+    transition: none;
+  }
+}