@yewdiel21/motion-kit 0.10.0 → 0.15.0

package/src/components/add-to-cart/engine.ts

@@ -0,0 +1,206 @@
+import { gsap, EASE, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { press, ringPulse, rollDigits } from '../../motion/micro';
+
+/*
+ * Add to cart: the button packs the product and sends it to the cart. A copy of
+ * the product's picture shrinks and drops into a little box whose flaps close
+ * with a bounce and whose tape draws itself (.6 s); the box flies to the cart on
+ * an arc (x on the signature curve, y up then down, a slight spin, shrinking,
+ * .62 s), dives into it, and the cart bumps, pulses a ring and rolls its count.
+ * Each click sends its own box; the cart shows the latest count when a box
+ * lands. With reduced motion the count changes at once. The flight comes from
+ * the mini POS's flyToCart; the packing is new.
+ */
+
+export interface AddToCartOptions {
+  /** Where the box goes: an element, a selector, or (default) the first visible [data-mk-cart-target]. */
+  target?: HTMLElement | string;
+  /** The picture packed: an element, a selector, or (default) the [data-mk-cart-image] of the [data-mk-cart-item] around the button. */
+  image?: HTMLElement | string;
+  /** Items each click adds (default 1). */
+  quantity?: number;
+  /** The cart's count to start from (default: the number in the target's [data-mk-cart-count], else 0). */
+  count?: number;
+  /** Announced after a box lands (default 'Añadido al carrito'). */
+  label?: string;
+  /** A click: the new count (right away). */
+  onAdd?: (count: number) => void;
+  /** A box landed in the cart. */
+  onLand?: (count: number) => void;
+}
+
+export interface AddToCartInstance extends Instance {
+  /** Send a box, as a click does. */
+  add(): void;
+  setCount(count: number): void;
+  readonly count: number;
+}
+
+const BOX = 56;
+const FLIGHT = 0.62;
+
+/** An element from an option, a selector, or a default lookup. */
+const resolve = (option: HTMLElement | string | undefined, fallback: () => HTMLElement | null) =>
+  option instanceof HTMLElement ? option : typeof option === 'string' ? document.querySelector<HTMLElement>(option) : fallback();
+
+export function createAddToCart(root: HTMLElement | null, options: AddToCartOptions = {}): AddToCartInstance {
+  const button = root ? (root.matches('button') ? root : root.querySelector<HTMLElement>('button')) : null;
+  if (!root || !button) return inert({ add() {}, setCount() {}, count: 0 });
+  registerMotion();
+  const scope = createScope();
+  const quantity = Number.isFinite(options.quantity) && options.quantity! > 0 ? Math.round(options.quantity!) : 1;
+
+  const target = () =>
+    resolve(options.target, () => {
+      const all = [...document.querySelectorAll<HTMLElement>('[data-mk-cart-target]')];
+      return all.find((element) => {
+        const box = element.getBoundingClientRect();
+        return box.width > 0 && box.bottom > 0 && box.top < innerHeight;
+      }) ?? all[0] ?? null;
+    });
+  const image = () => resolve(options.image, () => button.closest('[data-mk-cart-item]')?.querySelector<HTMLElement>('[data-mk-cart-image]') ?? null);
+  const counter = () => target()?.querySelector<HTMLElement>('[data-mk-cart-count]') ?? null;
+  const read = Number.parseInt(counter()?.textContent ?? '', 10);
+  let count = Number.isFinite(options.count) ? Math.max(0, Math.round(options.count!)) : Number.isFinite(read) ? read : 0;
+
+  const status = document.createElement('span');
+  status.className = 'mk-sr-only';
+  status.setAttribute('role', 'status');
+  root.append(status);
+  scope.add(() => status.remove());
+  scope.attr(root, 'data-mk-ready', '');
+
+  const boxes = 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);
+  };
+  scope.add(() => {
+    for (const effect of effects) effect.kill();
+    effects.clear();
+    for (const box of boxes) box.remove();
+    boxes.clear();
+  });
+
+  /** The cart takes the box: it bumps, pulses and rolls its count to the latest number. */
+  const land = (animate: boolean) => {
+    const cart = target();
+    const number = counter();
+    const text = String(count);
+    if (number && number.textContent !== text) {
+      if (animate) keep(rollDigits(number, text, 1, 0.35));
+      else number.textContent = text;
+    }
+    if (cart && animate) {
+      keep(gsap.fromTo(cart, { scale: 1 }, { scale: 1.1, duration: 0.14, ease: 'power2.out', yoyo: true, repeat: 1, clearProps: 'transform' }));
+      keep(ringPulse(cart));
+    }
+    status.textContent = `${options.label ?? 'Añadido al carrito'}: ${count}`;
+    options.onLand?.(count);
+    root.dispatchEvent(new CustomEvent('mk:land', { bubbles: true, detail: { count } }));
+  };
+
+  /** The box: the picture inside, a front, two flaps and a strip of tape. */
+  const makeBox = (picture: HTMLElement | null) => {
+    const box = document.createElement('div');
+    box.dataset.mkCartBox = '';
+    box.setAttribute('aria-hidden', 'true');
+    let thumb: HTMLImageElement | null = null;
+    const src = picture instanceof HTMLImageElement ? picture.currentSrc || picture.getAttribute('src') : null;
+    if (src) {
+      thumb = document.createElement('img');
+      thumb.src = src;
+      thumb.alt = '';
+      thumb.dataset.mkCartThumb = '';
+      box.append(thumb);
+    }
+    const front = document.createElement('span');
+    front.dataset.mkCartFront = '';
+    const tape = document.createElement('span');
+    tape.dataset.mkCartTape = '';
+    front.append(tape);
+    const left = document.createElement('span');
+    left.dataset.mkCartFlap = 'left';
+    const right = document.createElement('span');
+    right.dataset.mkCartFlap = 'right';
+    box.append(front, left, right);
+    return { box, thumb, front, tape, left, right };
+  };
+
+  const add = () => {
+    if (scope.disposed) return;
+    count += quantity;
+    options.onAdd?.(count);
+    root.dispatchEvent(new CustomEvent('mk:add', { bubbles: true, detail: { count } }));
+    if (reduced()) return land(false);
+    keep(press(button));
+    const picture = image();
+    const from = (picture ?? button).getBoundingClientRect();
+    const cart = target();
+    const to = cart?.getBoundingClientRect() ?? null;
+    const { box, thumb, front, tape, left, right } = makeBox(picture);
+    const startX = from.left + from.width / 2 - BOX / 2;
+    const startY = from.top + from.height / 2 - BOX / 2;
+    Object.assign(box.style, { left: `${startX}px`, top: `${startY}px`, width: `${BOX}px`, height: `${BOX}px` });
+    document.body.append(box);
+    boxes.add(box);
+    const gone = () => {
+      box.remove();
+      boxes.delete(box);
+    };
+
+    const timeline = gsap.timeline({
+      onComplete: () => {
+        gone();
+        land(true);
+      },
+    });
+    // 1 · Packing: the picture shrinks into the box, the box rises around it, the flaps close, the tape draws.
+    if (thumb) {
+      const scale = Math.max(from.width, from.height) / 40 || 1;
+      timeline.fromTo(thumb, { scale, y: 0, opacity: 1 }, { scale: 1, y: -14, duration: 0.32, ease: EASE.signature }, 0);
+      timeline.to(thumb, { y: 4, duration: 0.16, ease: 'power2.in' }, 0.3);
+    }
+    timeline.fromTo(front, { scaleY: 0 }, { scaleY: 1, duration: 0.26, ease: EASE.pop }, 0.08);
+    timeline.fromTo([left, right], { opacity: 0 }, { opacity: 1, duration: 0.12 }, 0.12);
+    timeline.fromTo(left, { rotation: -70 }, { rotation: 0, duration: 0.3, ease: EASE.click }, 0.38);
+    timeline.fromTo(right, { rotation: 70 }, { rotation: 0, duration: 0.3, ease: EASE.click }, 0.43);
+    timeline.fromTo(tape, { scaleY: 0 }, { scaleY: 1, duration: 0.16, ease: EASE.wipe }, 0.62);
+    // 2 · The flight: an arc to the cart (x on the signature curve, y up then down), a slight spin, smaller.
+    const start = 0.74;
+    if (to) {
+      const dx = to.left + to.width / 2 - (startX + BOX / 2);
+      const dy = to.top + to.height / 2 - (startY + BOX / 2);
+      const lift = Math.min(dy, 0) - 70;
+      timeline.to(box, { x: dx, duration: FLIGHT, ease: EASE.signature }, start);
+      timeline.to(box, { y: lift, duration: FLIGHT * 0.42, ease: 'power2.out' }, start);
+      timeline.to(box, { y: dy, duration: FLIGHT * 0.58, ease: 'power2.in' }, start + FLIGHT * 0.42);
+      timeline.fromTo(box, { rotation: 0 }, { rotation: 10, scale: 0.55, duration: FLIGHT, ease: 'power1.inOut' }, start);
+      // 3 · Into the cart.
+      timeline.to(box, { scale: 0.15, opacity: 0, duration: 0.14, ease: 'power2.in' }, start + FLIGHT - 0.04);
+    } else timeline.to(box, { y: -24, opacity: 0, scale: 0.8, filter: 'blur(6px)', duration: 0.3, ease: 'power2.in' }, start);
+    keep(timeline);
+  };
+
+  scope.on(button, 'click', add);
+
+  return {
+    add,
+    setCount(next) {
+      if (!Number.isFinite(next)) return;
+      count = Math.max(0, Math.round(next));
+      const number = counter();
+      if (number) number.textContent = String(count);
+    },
+    get count() {
+      return count;
+    },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/add-to-cart/react.tsx

@@ -0,0 +1,29 @@
+'use client';
+import { useRef, type HTMLAttributes, type MutableRefObject } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createAddToCart, type AddToCartInstance, type AddToCartOptions } from './engine';
+
+export interface AddToCartProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onAdd'>, AddToCartOptions {
+  instanceRef?: MutableRefObject<AddToCartInstance | null>;
+}
+
+/** <AddToCart target="#carrito" onAdd={setCount}><button className="mk-button">Agregar</button></AddToCart>. */
+export function AddToCart({ target, image, quantity, count, label, onAdd, onLand, instanceRef, className, children, ...props }: AddToCartProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const add = useLatest(onAdd);
+  const landed = useLatest(onLand);
+  useIsomorphicLayoutEffect(() => {
+    const created = createAddToCart(ref.current, { target, image, quantity, count, label, onAdd: (n) => add.current?.(n), onLand: (n) => landed.current?.(n) });
+    if (instanceRef) instanceRef.current = created;
+    return () => {
+      created.destroy();
+      if (instanceRef) instanceRef.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [typeof target === 'string' ? target : null, typeof image === 'string' ? image : null, quantity, label]);
+  return (
+    <div {...props} ref={ref} className={['mk-add-to-cart', className].filter(Boolean).join(' ')}>
+      {children}
+    </div>
+  );
+}

package/src/components/attachment/README.md

@@ -0,0 +1,27 @@
+# attachment
+
+Selector de archivos nativo con zona para arrastrar y soltar y una tarjeta por archivo (nombre, tipo, tamaño, progreso, estado y quitar). Valida `accept`, tamaño y cantidad; la subida pertenece a la app, que informa el progreso.
+
+```html
+<mk-attachment class="mk-attachment" accept="image/*,.pdf" multiple max-files="4" max-size="5242880"></mk-attachment>
+```
+
+```ts
+const attachment = createAttachment(root, {
+  accept: 'image/*,.pdf',
+  multiple: true,
+  maxFiles: 4,
+  maxSize: 5 * 1024 * 1024,
+  onFiles: (added) => added.forEach((file) => upload(file.file!, (pct) => attachment.setProgress(file.id, pct))),
+});
+```
+
+React: `<Attachment multiple accept=".pdf" onFiles={upload} uploads={{ [id]: { progress: 40 } }} />`, o `instanceRef` para llamar a la API.
+
+Opciones: `accept` (extensiones, MIME y `tipo/*`), `multiple`, `maxFiles` (sólo multiple), `maxSize` (bytes), `disabled`, `name`, `initialFiles` (metadatos `{id?, name, size, type, preview?, progress?, status?}`), `hint`, `labels`, `onFiles(added, files)`, `onRemove(file, files)`, `onReject(rejections)`. API: `addFiles(files)` (devuelve los aceptados), `remove(id)`, `setProgress(id, 0–100, status?)`, `clear()`, `files` (copias), `destroy()`.
+
+Eventos: `mk:files` `{added, files}`, `mk:remove` `{file, files}` y `mk:reject` `{file, code: 'type' | 'size' | 'count', message}` (uno por archivo). Los archivos válidos se conservan al añadir más; en modo simple el nuevo sustituye al anterior. Las vistas previas de imagen son object URLs que se revocan al quitar el archivo o al destruir. Los nombres se muestran siempre como texto.
+
+`disabled` desactiva selector, soltar y quitar (también `remove()`). Con `name` y `DataTransfer` disponible, el input lleva los archivos conservados para un envío nativo. Quitar un archivo deja el foco en el siguiente botón o en el selector. `destroy()` elimina lo creado y restaura atributos. El custom element expone `addFiles`, `removeFile(id)` (`remove()` sigue siendo el de `HTMLElement`), `setProgress` y `files`, y conserva los archivos al cambiar un atributo.
+
+Variables: `--mk-attachment-radius`, `--mk-attachment-accent`. Movimiento reducido elimina escalas y entradas.

package/src/components/attachment/attachment.css

@@ -0,0 +1,265 @@
+/* attachment — a soft dashed drop zone and file cards with progress (Melon Mind surfaces: 16–24 px radius). */
+.mk-attachment,
+mk-attachment {
+  --mk-attachment-radius: var(--mk-radius-lg, 24px);
+  --mk-attachment-accent: var(--mk-accent);
+  display: grid;
+  gap: 0.75rem;
+  color: var(--mk-text);
+  font-family: var(--mk-font);
+}
+
+:is(.mk-attachment, mk-attachment) [data-mk-attachment-drop] {
+  position: relative;
+  display: grid;
+  justify-items: center;
+  gap: 0.35rem;
+  padding: 1.75rem 1.25rem;
+  border: 1.5px dashed var(--mk-outline-soft);
+  border-radius: var(--mk-attachment-radius);
+  background: var(--mk-surface-2);
+  text-align: center;
+  cursor: pointer;
+  transition:
+    background-color 0.2s ease,
+    border-color 0.2s ease,
+    transform 0.25s var(--mk-ease-press, ease);
+}
+
+:is(.mk-attachment, mk-attachment) [data-mk-attachment-drop]:hover,
+:is(.mk-attachment, mk-attachment) [data-mk-attachment-drop][data-mk-dragging] {
+  border-color: var(--mk-outline);
+  background: var(--mk-surface-3);
+}
+
+:is(.mk-attachment, mk-attachment) [data-mk-attachment-drop][data-mk-dragging] {
+  transform: scale(1.015);
+}
+
+:is(.mk-attachment, mk-attachment) [data-mk-attachment-drop]:active {
+  transform: scale(0.99);
+}
+
+:is(.mk-attachment, mk-attachment) [data-mk-attachment-drop]:has(input:focus-visible) {
+  outline: 2px solid var(--mk-accent);
+  outline-offset: 3px;
+}
+
+:is(.mk-attachment, mk-attachment)[data-mk-disabled] [data-mk-attachment-drop] {
+  opacity: 0.5;
+  cursor: not-allowed;
+  transform: none;
+}
+
+:is(.mk-attachment, mk-attachment) [data-mk-attachment-drop] input[type='file'] {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  opacity: 0;
+  pointer-events: none;
+}
+
+:is(.mk-attachment, mk-attachment) [data-mk-attachment-drop] [data-mk-part='icon'] {
+  display: grid;
+  place-items: center;
+  width: 2.75rem;
+  height: 2.75rem;
+  margin-bottom: 0.25rem;
+  border-radius: 50%;
+  background: var(--mk-text);
+  color: var(--mk-bg);
+  transition: translate 0.4s cubic-bezier(0.38, 0.49, 0, 2);
+}
+
+:is(.mk-attachment, mk-attachment) [data-mk-attachment-drop]:is(:hover, [data-mk-dragging]) [data-mk-part='icon'] {
+  translate: 0 -4px;
+}
+
+:is(.mk-attachment, mk-attachment) [data-mk-attachment-drop] [data-mk-part='icon']::before {
+  content: '';
+  width: 1.25rem;
+  height: 1.25rem;
+  background: currentColor;
+  mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M12 16V4M6.5 9.5 12 4l5.5 5.5M4 16v2a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2v-2'/%3E%3C/svg%3E") center / contain no-repeat;
+}
+
+:is(.mk-attachment, mk-attachment) [data-mk-attachment-drop] strong {
+  color: var(--mk-text);
+  font-weight: 600;
+  text-decoration: underline;
+  text-underline-offset: 0.2em;
+}
+
+:is(.mk-attachment, mk-attachment) [data-mk-attachment-drop] small {
+  color: var(--mk-muted);
+  font-size: 0.8125rem;
+}
+
+:is(.mk-attachment, mk-attachment) [data-mk-attachment-list] {
+  display: grid;
+  gap: 0.5rem;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+:is(.mk-attachment, mk-attachment) [data-mk-attachment-list]:empty {
+  display: none;
+}
+
+:is(.mk-attachment, mk-attachment) [data-mk-attachment-item] {
+  display: grid;
+  grid-template-columns: auto minmax(0, 1fr) auto;
+  align-items: center;
+  gap: 0.875rem;
+  padding: 0.625rem 0.625rem 0.625rem 0.75rem;
+  border-radius: calc(var(--mk-attachment-radius) - 8px);
+  background: var(--mk-surface-1);
+  box-shadow: inset 0 0 0 1px var(--mk-outline-soft);
+}
+
+:is(.mk-attachment, mk-attachment) [data-mk-attachment-item][data-mk-status='error'] {
+  box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--mk-error) 45%, transparent);
+}
+
+:is(.mk-attachment, mk-attachment) [data-mk-attachment-item] [data-mk-part='thumb'] {
+  display: grid;
+  place-items: center;
+  overflow: hidden;
+  width: 2.75rem;
+  height: 2.75rem;
+  border-radius: 0.875rem;
+  background: var(--mk-surface-3);
+  color: var(--mk-muted);
+  font-size: 0.6875rem;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+}
+
+:is(.mk-attachment, mk-attachment) [data-mk-part='thumb'] img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+:is(.mk-attachment, mk-attachment) [data-mk-part='meta'] {
+  display: grid;
+  gap: 0.15rem;
+  min-width: 0;
+}
+
+:is(.mk-attachment, mk-attachment) [data-mk-part='name'] {
+  overflow: hidden;
+  font-weight: 500;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+:is(.mk-attachment, mk-attachment) [data-mk-part='detail'] {
+  color: var(--mk-muted);
+  font-size: 0.8125rem;
+  font-variant-numeric: tabular-nums;
+}
+
+:is(.mk-attachment, mk-attachment) [data-mk-status='complete'] [data-mk-part='detail'] {
+  color: var(--mk-accent);
+}
+
+:is(.mk-attachment, mk-attachment) [data-mk-status='error'] [data-mk-part='detail'] {
+  color: var(--mk-error);
+}
+
+:is(.mk-attachment, mk-attachment) progress {
+  width: 100%;
+  height: 4px;
+  margin-top: 0.3rem;
+  overflow: hidden;
+  border: 0;
+  border-radius: var(--mk-radius-full);
+  background: var(--mk-surface-4);
+  appearance: none;
+  accent-color: var(--mk-attachment-accent);
+}
+
+:is(.mk-attachment, mk-attachment) progress[hidden] {
+  display: none;
+}
+
+:is(.mk-attachment, mk-attachment) progress::-webkit-progress-bar {
+  background: transparent;
+}
+
+:is(.mk-attachment, mk-attachment) progress::-webkit-progress-value {
+  border-radius: inherit;
+  background: var(--mk-attachment-accent);
+  transition: width 0.3s ease;
+}
+
+:is(.mk-attachment, mk-attachment) progress::-moz-progress-bar {
+  border-radius: inherit;
+  background: var(--mk-attachment-accent);
+}
+
+:is(.mk-attachment, mk-attachment) [data-mk-attachment-remove] {
+  display: grid;
+  place-items: center;
+  width: 2.5rem;
+  height: 2.5rem;
+  padding: 0;
+  border: 0;
+  border-radius: 50%;
+  background: transparent;
+  color: var(--mk-muted);
+  cursor: pointer;
+  transition:
+    background-color 0.2s ease,
+    color 0.2s ease,
+    transform 0.2s var(--mk-ease-press, ease);
+}
+
+:is(.mk-attachment, mk-attachment) [data-mk-attachment-remove]:hover:not(:disabled) {
+  background: color-mix(in srgb, var(--mk-error) 12%, transparent);
+  color: var(--mk-error);
+}
+
+:is(.mk-attachment, mk-attachment) [data-mk-attachment-remove]:active:not(:disabled) {
+  transform: scale(0.9);
+}
+
+:is(.mk-attachment, mk-attachment) [data-mk-attachment-remove]:focus-visible {
+  outline: 2px solid var(--mk-accent);
+  outline-offset: 2px;
+}
+
+:is(.mk-attachment, mk-attachment) [data-mk-attachment-remove]:disabled {
+  opacity: 0.4;
+  cursor: not-allowed;
+}
+
+:is(.mk-attachment, mk-attachment) [data-mk-attachment-error] {
+  margin: 0;
+  padding: 0.625rem 0.875rem;
+  border-radius: var(--mk-radius-lg);
+  background: var(--mk-error-soft);
+  color: var(--mk-on-error-soft);
+  font-size: 0.875rem;
+}
+
+:is(.mk-attachment, mk-attachment) [data-mk-attachment-error][hidden] {
+  display: none;
+}
+
+@keyframes mk-attachment-in {
+  from {
+    opacity: 0;
+    transform: translateY(6px) scale(0.98);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :is(.mk-attachment, mk-attachment) :is([data-mk-attachment-drop], [data-mk-attachment-item], [data-mk-attachment-remove]) {
+    transition: none;
+    animation: none;
+    transform: none !important;
+  }
+}

package/src/components/attachment/element.ts

@@ -0,0 +1,50 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createAttachment, type AttachmentInstance, type AttachmentStatus } from './engine';
+
+/**
+ * <mk-attachment class="mk-attachment" accept="image/*,.pdf" multiple max-files="4" max-size="5000000"></mk-attachment>
+ * Emits mk:files ({added, files}), mk:remove ({file, files}) and mk:reject ({file, code, message}).
+ * Changing an attribute keeps the files already chosen.
+ */
+export class MkAttachmentElement extends MkElement<AttachmentInstance> {
+  static options: Record<string, OptionType> = {
+    accept: 'string',
+    multiple: 'boolean',
+    maxFiles: 'number',
+    maxSize: 'number',
+    disabled: 'boolean',
+    name: 'string',
+    hint: 'string',
+    initialFiles: 'json',
+  };
+
+  protected create(options: Record<string, unknown>) {
+    return createAttachment(this, options);
+  }
+
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.isConnected || !this.instance) return;
+    const files = this.instance.files;
+    this.instance.destroy();
+    this.instance = this.create({ ...this.options, initialFiles: files });
+  }
+
+  addFiles(files: Iterable<File> | ArrayLike<File>) {
+    return this.instance?.addFiles(files) ?? [];
+  }
+
+  /** Remove one file (HTMLElement.remove() still removes the element). */
+  removeFile(id: string) {
+    this.instance?.remove(id);
+  }
+
+  setProgress(id: string, value: number, status?: AttachmentStatus) {
+    this.instance?.setProgress(id, value, status);
+  }
+
+  get files() {
+    return this.instance?.files ?? [];
+  }
+}
+
+export const defineAttachment = () => defineElement('mk-attachment', MkAttachmentElement);