@yewdiel21/motion-kit 0.10.0 → 0.15.0

package/src/components/sankey-chart/engine.ts

@@ -0,0 +1,401 @@
+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 { chartFrame, finite, formatNumber, onWidth, round, slotColor, svg, SVG_NS } from '../chart/parts';
+
+/*
+ * Sankey chart: flows between stages as bands as wide as their value, in
+ * chart's family. Nodes stand in columns by their depth (the ones that lead
+ * nowhere end at the right), stacked in the given order and centred; each
+ * band fades from its source's colour to its target's. The nodes grow from
+ * their middles, column after column, while the bands are wiped in from the
+ * left (.9 s); new data with the same nodes and flows glides every node and
+ * band. Pointing at a band (or the arrows) lights it and dims the rest, with
+ * "A → B" and its share in the tooltip; pointing at a node lights its bands.
+ */
+
+export interface SankeyNode {
+  id: string;
+  label?: string;
+  color?: string;
+}
+
+export interface SankeyLink {
+  source: string;
+  target: string;
+  value: number;
+}
+
+export interface SankeyChartOptions {
+  nodes?: SankeyNode[];
+  links?: SankeyLink[];
+  /** Plot height in px (default 320). */
+  height?: number;
+  /** Node width in px (default 12). */
+  nodeWidth?: number;
+  /** Space between nodes in a column, px (default 14). */
+  nodePadding?: number;
+  label?: string;
+  formatValue?: (value: number) => string;
+  emptyLabel?: string;
+  /** A flow was chosen (its index in `links`), or none. */
+  onSelect?: (index: number | null) => void;
+}
+
+export interface SankeyChartInstance extends Instance {
+  update(options: SankeyChartOptions): void;
+  select(index: number | null): void;
+  readonly selected: number | null;
+}
+
+interface Layout {
+  nodes: Array<{ x: number; y0: number; y1: number }>;
+  links: Array<{ sy: number; ty: number; width: number }>;
+}
+
+export function createSankeyChart(root: HTMLElement | null, initial: SankeyChartOptions = {}): SankeyChartInstance {
+  if (!root) return inert({ update() {}, select() {}, selected: null });
+  registerMotion();
+  const scope = createScope();
+  const frame = chartFrame(root, scope, 'sankey');
+  const { plot, canvas } = frame;
+  let options: SankeyChartOptions = { ...initial };
+  let selected: number | null = null;
+  let hoverNode: number | null = null;
+  const uid = `mk-sankey-${Math.random().toString(36).slice(2, 8)}`;
+
+  const format = (value: number) => (options.formatValue ? options.formatValue(value) : formatNumber(value));
+  const modelOf = () => {
+    const nodes = (options.nodes ?? []).map((node, i, all) => ({ id: String(node.id), label: String(node.label ?? node.id), color: node.color ?? slotColor(i, Math.max(2, all.length)) }));
+    const index = new Map(nodes.map((node, i) => [node.id, i]));
+    const links = (options.links ?? [])
+      .map((link, i) => ({ source: index.get(String(link.source)) ?? -1, target: index.get(String(link.target)) ?? -1, value: link.value, given: i }))
+      .filter((link) => link.source >= 0 && link.target >= 0 && link.source !== link.target && finite(link.value) && link.value > 0);
+    // Depth: the longest way in from a source (bounded, so a loop cannot run away).
+    const depth = nodes.map(() => 0);
+    for (let pass = 0; pass < nodes.length; pass++) {
+      let moved = false;
+      for (const link of links) {
+        if (depth[link.target]! < depth[link.source]! + 1 && depth[link.source]! + 1 < nodes.length) {
+          depth[link.target] = depth[link.source]! + 1;
+          moved = true;
+        }
+      }
+      if (!moved) break;
+    }
+    const columns = Math.max(0, ...depth) + 1;
+    // The ones that lead nowhere end at the right.
+    nodes.forEach((_, i) => {
+      if (links.some((link) => link.source === i) || !links.some((link) => link.target === i)) return;
+      depth[i] = columns - 1;
+    });
+    const used = nodes.map((_, i) => links.some((link) => link.source === i || link.target === i));
+    const value = nodes.map((_, i) => Math.max(links.filter((link) => link.target === i).reduce((s, l) => s + l.value, 0), links.filter((link) => link.source === i).reduce((s, l) => s + l.value, 0)));
+    return { nodes, links, depth, columns, used, value };
+  };
+  let model = modelOf();
+  const hasData = () => model.links.length > 0;
+
+  let width = 600;
+  let height = 320;
+  const layoutOf = (): Layout => {
+    width = Math.max(240, Math.round(plot.clientWidth || root.clientWidth || 600));
+    height = Math.max(160, finite(options.height) ? options.height : 320);
+    const nodeWidth = Math.max(4, finite(options.nodeWidth) ? options.nodeWidth : 12);
+    const pad = Math.max(2, finite(options.nodePadding) ? options.nodePadding : 14);
+    const top = 6;
+    const usable = height - top * 2;
+    const columns = Array.from({ length: model.columns }, (_, c) => model.nodes.map((_, i) => i).filter((i) => model.used[i] && model.depth[i] === c));
+    const ky = Math.min(...columns.filter((list) => list.length).map((list) => (usable - pad * (list.length - 1)) / list.reduce((sum, i) => sum + model.value[i]!, 0)));
+    const step = model.columns > 1 ? (width - nodeWidth) / (model.columns - 1) : 0;
+    const nodes = model.nodes.map(() => ({ x: 0, y0: 0, y1: 0 }));
+    for (const list of columns) {
+      const total = list.reduce((sum, i) => sum + model.value[i]! * ky, 0) + pad * Math.max(0, list.length - 1);
+      let y = top + (usable - total) / 2;
+      for (const i of list) {
+        const h = Math.max(1, model.value[i]! * ky);
+        nodes[i] = { x: model.depth[i]! * step, y0: y, y1: y + h };
+        y += h + pad;
+      }
+    }
+    // Bands leave a node in the order of their targets and arrive in the order of their sources.
+    const out = new Map<number, number>();
+    const into = new Map<number, number>();
+    const centre = (i: number) => (nodes[i]!.y0 + nodes[i]!.y1) / 2;
+    const links = model.links.map(() => ({ sy: 0, ty: 0, width: 0 }));
+    const order = model.links.map((_, k) => k);
+    for (const k of [...order].sort((a, b) => centre(model.links[a]!.target) - centre(model.links[b]!.target))) {
+      const link = model.links[k]!;
+      const w = link.value * ky;
+      const at = out.get(link.source) ?? nodes[link.source]!.y0;
+      links[k]!.sy = at + w / 2;
+      links[k]!.width = w;
+      out.set(link.source, at + w);
+    }
+    for (const k of [...order].sort((a, b) => centre(model.links[a]!.source) - centre(model.links[b]!.source))) {
+      const link = model.links[k]!;
+      const at = into.get(link.target) ?? nodes[link.target]!.y0;
+      links[k]!.ty = at + links[k]!.width / 2;
+      into.set(link.target, at + links[k]!.width);
+    }
+    return { nodes, links };
+  };
+
+  let shown: Layout | null = null;
+  let rects: SVGRectElement[] = [];
+  let bands: SVGPathElement[] = [];
+  let names: SVGTextElement[] = [];
+  let glide: gsap.core.Animation | null = null;
+  scope.add(() => glide?.kill());
+  const nodeWidth = () => Math.max(4, finite(options.nodeWidth) ? options.nodeWidth : 12);
+
+  const build = () => {
+    canvas.replaceChildren();
+    canvas.setAttribute('viewBox', `0 0 ${width} ${height}`);
+    canvas.setAttribute('width', String(width));
+    canvas.setAttribute('height', String(height));
+    const defs = svg('defs');
+    const flows = svg('g', { 'data-mk-part': 'links' });
+    bands = model.links.map((link, k) => {
+      const gradient = svg('linearGradient', { id: `${uid}-${k}`, gradientUnits: 'userSpaceOnUse' });
+      const from = svg('stop', { offset: '0' });
+      from.style.stopColor = model.nodes[link.source]!.color;
+      const to = svg('stop', { offset: '1' });
+      to.style.stopColor = model.nodes[link.target]!.color;
+      gradient.append(from, to);
+      defs.append(gradient);
+      const band = svg('path', { 'data-mk-index': k });
+      band.style.fill = `url(#${uid}-${k})`;
+      flows.append(band);
+      return band;
+    });
+    const nodesLayer = svg('g', { 'data-mk-part': 'nodes' });
+    rects = model.nodes.map((node, i) => {
+      const rect = svg('rect', { width: nodeWidth(), rx: 3, 'data-mk-node': i });
+      rect.style.fill = node.color;
+      if (!model.used[i]) rect.style.display = 'none';
+      nodesLayer.append(rect);
+      return rect;
+    });
+    const labels = svg('g', { 'data-mk-part': 'labels' });
+    names = model.nodes.map((node, i) => {
+      const text = svg('text', { 'dominant-baseline': 'middle' });
+      text.textContent = node.label;
+      const amount = document.createElementNS(SVG_NS, 'tspan');
+      amount.setAttribute('data-mk-part', 'amount');
+      amount.textContent = ` ${format(model.value[i]!)}`;
+      text.append(amount);
+      if (!model.used[i]) text.style.display = 'none';
+      labels.append(text);
+      return text;
+    });
+    canvas.append(defs, flows, nodesLayer, labels);
+  };
+
+  const paint = (layout: Layout) => {
+    shown = layout;
+    const w = nodeWidth();
+    layout.nodes.forEach((node, i) => {
+      const rect = rects[i]!;
+      rect.setAttribute('x', String(round(node.x)));
+      rect.setAttribute('y', String(round(node.y0)));
+      rect.setAttribute('height', String(round(Math.max(1, node.y1 - node.y0))));
+      const last = model.depth[i] === model.columns - 1 && model.columns > 1;
+      const name = names[i]!;
+      const first = model.depth[i] === 0;
+      const x = round(last ? node.x - 8 : first ? node.x + w + 8 : node.x + w / 2);
+      const available = model.columns > 1 ? (width - w) / (model.columns - 1) - 20 : width - w - 16;
+      const characters = Math.max(3, Math.floor(available / 7));
+      const label = model.nodes[i]!.label;
+      if (name.firstChild) name.firstChild.textContent = label.length > characters ? `${label.slice(0, characters - 1)}…` : label;
+      name.setAttribute('x', String(x));
+      name.setAttribute('y', String(round((node.y0 + node.y1) / 2 - 7)));
+      name.setAttribute('text-anchor', last ? 'end' : first ? 'start' : 'middle');
+      const amount = name.querySelector('tspan');
+      amount?.setAttribute('x', String(x));
+      amount?.setAttribute('dy', '14');
+    });
+    layout.links.forEach((link, k) => {
+      const { source, target } = model.links[k]!;
+      const x0 = layout.nodes[source]!.x + w;
+      const x1 = layout.nodes[target]!.x;
+      const xm = (x0 + x1) / 2;
+      const h = link.width / 2;
+      const [s0, s1, t0, t1] = [link.sy - h, link.sy + h, link.ty - h, link.ty + h].map(round);
+      bands[k]!.setAttribute('d', `M${round(x0)},${s0}C${round(xm)},${s0} ${round(xm)},${t0} ${round(x1)},${t0}L${round(x1)},${t1}C${round(xm)},${t1} ${round(xm)},${s1} ${round(x0)},${s1}Z`);
+      const gradient = canvas.querySelector(`#${uid}-${k}`);
+      gradient?.setAttribute('x1', String(round(x0)));
+      gradient?.setAttribute('x2', String(round(x1)));
+    });
+  };
+
+  const share = (part: number, whole: number) => new Intl.NumberFormat(undefined, { style: 'percent', maximumFractionDigits: 1 }).format(part / (whole || 1));
+  const paintSelection = (announce: boolean) => {
+    const lit = (k: number) => (selected !== null ? k === selected : hoverNode !== null ? model.links[k]!.source === hoverNode || model.links[k]!.target === hoverNode : false);
+    const any = selected !== null || hoverNode !== null;
+    bands.forEach((band, k) => {
+      band.toggleAttribute('data-mk-on', lit(k));
+      band.toggleAttribute('data-mk-dim', any && !lit(k));
+    });
+    rects.forEach((rect, i) => rect.toggleAttribute('data-mk-dim', any && !model.links.some((link, k) => lit(k) && (link.source === i || link.target === i))));
+    if (!shown || (selected === null && hoverNode === null)) {
+      frame.tip(null);
+      return;
+    }
+    if (selected !== null) {
+      const link = model.links[selected]!;
+      const geometry = shown.links[selected]!;
+      const x = (shown.nodes[link.source]!.x + shown.nodes[link.target]!.x + nodeWidth()) / 2;
+      const y = (geometry.sy + geometry.ty) / 2 - geometry.width / 2;
+      const from = model.nodes[link.source]!;
+      const to = model.nodes[link.target]!;
+      const rows = [{ name: `${share(link.value, model.value[link.source]!)} de ${from.label}`, color: from.color, value: format(link.value) }];
+      frame.tip({ x: round(x), y: round(y), title: `${from.label} → ${to.label}`, rows });
+      if (announce) frame.live.textContent = `${from.label} a ${to.label}: ${format(link.value)}`;
+    } else {
+      const i = hoverNode!;
+      const node = shown.nodes[i]!;
+      frame.tip({ x: round(node.x + nodeWidth() / 2), y: round(node.y0), title: model.nodes[i]!.label, rows: [{ name: 'Total', color: model.nodes[i]!.color, value: format(model.value[i]!) }] });
+    }
+  };
+
+  const draw = (animate: boolean) => {
+    glide?.kill();
+    const name = options.label ?? 'Diagrama de flujo';
+    canvas.setAttribute('aria-label', hasData() ? `${name}. ${model.links.length} flujos entre ${model.used.filter(Boolean).length} etapas. Usa las flechas para recorrer los flujos.` : `${name}: ${options.emptyLabel ?? 'sin datos'}`);
+    frame.fillTable(name, ['Flujo', 'Valor'], model.links.map((link) => [`${model.nodes[link.source]!.label} → ${model.nodes[link.target]!.label}`, format(link.value)]));
+    frame.fillLegend([], false);
+    const ok = hasData();
+    frame.empty.hidden = ok;
+    frame.empty.textContent = options.emptyLabel ?? 'Sin datos para mostrar';
+    plot.hidden = !ok;
+    if (!ok) {
+      canvas.replaceChildren();
+      shown = null;
+      selected = null;
+      return;
+    }
+    if (selected !== null && selected >= model.links.length) selected = null;
+    const before = shown;
+    const target = layoutOf();
+    const comparable = before && before.nodes.length === target.nodes.length && before.links.length === target.links.length;
+    build();
+    const done = () => {
+      paint(target);
+      paintSelection(false);
+    };
+    if (!animate || reduced()) return done();
+    if (comparable) {
+      // Same nodes and flows: every node and band glides to its new place.
+      const state = { t: 0 };
+      const mix = (a: number, b: number) => a + (b - a) * state.t;
+      glide = gsap.to(state, {
+        t: 1,
+        duration: 0.6,
+        ease: EASE.swatch,
+        onUpdate: () =>
+          paint({
+            nodes: target.nodes.map((node, i) => ({ x: mix(before!.nodes[i]!.x, node.x), y0: mix(before!.nodes[i]!.y0, node.y0), y1: mix(before!.nodes[i]!.y1, node.y1) })),
+            links: target.links.map((link, k) => ({ sy: mix(before!.links[k]!.sy, link.sy), ty: mix(before!.links[k]!.ty, link.ty), width: mix(before!.links[k]!.width, link.width) })),
+          }),
+        onComplete: done,
+      });
+      return;
+    }
+    // First appearance: nodes grow from their middles column by column; the bands are wiped in from the left.
+    done();
+    const timeline = gsap.timeline();
+    rects.forEach((rect, i) => {
+      timeline.fromTo(rect, { scaleY: 0, transformOrigin: '50% 50%' }, { scaleY: 1, duration: 0.5, ease: EASE.swatch, clearProps: 'transform' }, (model.depth[i] ?? 0) * 0.12);
+    });
+    timeline.fromTo(names, { opacity: 0 }, { opacity: 1, duration: 0.4, stagger: 0.02, clearProps: 'opacity' }, 0.2);
+    const clip = svg('clipPath', { id: `${uid}-wipe` });
+    const rect = svg('rect', { x: 0, y: 0, width: 0, height });
+    clip.append(rect);
+    canvas.prepend(clip);
+    const flows = canvas.querySelector('[data-mk-part="links"]')!;
+    flows.setAttribute('clip-path', `url(#${uid}-wipe)`);
+    timeline.to(rect, { attr: { width }, duration: 0.9, ease: EASE.wipe, onComplete: () => {
+      flows.removeAttribute('clip-path');
+      clip.remove();
+    } }, 0.1);
+    glide = timeline;
+  };
+
+  const select = (index: number | null, announce = false) => {
+    if (scope.disposed) return;
+    const n = model.links.length;
+    const next = index === null || !n ? null : ((Math.round(index) % n) + n) % n;
+    if (next === selected) return;
+    selected = next;
+    paintSelection(announce);
+    options.onSelect?.(selected === null ? null : model.links[selected]!.given);
+    const link = selected === null ? null : model.links[selected]!;
+    root.dispatchEvent(new CustomEvent('mk:select', { bubbles: true, detail: { index: link?.given ?? null, source: link ? model.nodes[link.source]!.id : null, target: link ? model.nodes[link.target]!.id : null, value: link?.value ?? null } }));
+  };
+
+  scope.on(canvas, 'pointermove', (event) => {
+    const target = event.target as Element;
+    const band = target.closest('[data-mk-index]');
+    const node = target.closest('[data-mk-node]');
+    if (node) {
+      const i = Number(node.getAttribute('data-mk-node'));
+      if (selected !== null) select(null);
+      if (hoverNode !== i) {
+        hoverNode = i;
+        paintSelection(false);
+      }
+      return;
+    }
+    if (hoverNode !== null) {
+      hoverNode = null;
+      paintSelection(false);
+    }
+    select(band ? Number(band.getAttribute('data-mk-index')) : null);
+  });
+  scope.on(canvas, 'pointerleave', (event) => {
+    if ((event as PointerEvent).pointerType !== 'mouse') return;
+    hoverNode = null;
+    select(null);
+    paintSelection(false);
+  });
+  scope.on(canvas, 'focus', () => {
+    if (selected === null && hasData()) select(0, true);
+  });
+  scope.on(canvas, 'blur', () => select(null));
+  scope.on(canvas, 'keydown', (event) => {
+    const key = (event as KeyboardEvent).key;
+    const moves: Record<string, number | null> = { ArrowDown: (selected ?? -1) + 1, ArrowRight: (selected ?? -1) + 1, ArrowUp: (selected ?? 1) - 1, ArrowLeft: (selected ?? 1) - 1, Home: 0, End: model.links.length - 1, Escape: null };
+    if (!(key in moves) || !hasData()) return;
+    event.preventDefault();
+    select(moves[key]!, true);
+  });
+  onWidth(root, scope, () => {
+    if (!hasData()) return;
+    const layout = layoutOf();
+    build();
+    paint(layout);
+    paintSelection(false);
+  });
+
+  draw(true);
+
+  return {
+    update(next) {
+      if (scope.disposed) return;
+      options = { ...options, ...next };
+      model = modelOf();
+      draw(true);
+    },
+    select: (index) => {
+      // `index` is the flow's place in `links`.
+      const at = index === null ? null : model.links.findIndex((link) => link.given === index);
+      select(at === null || at < 0 ? null : at);
+    },
+    get selected() {
+      return selected === null ? null : model.links[selected]!.given;
+    },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/sankey-chart/react.tsx

@@ -0,0 +1,14 @@
+'use client';
+import type { HTMLAttributes } from 'react';
+import { useChart } from '../chart/use-chart';
+import { createSankeyChart, type SankeyChartInstance, type SankeyChartOptions } from './engine';
+
+export interface SankeyChartProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onSelect' | 'children'>, SankeyChartOptions {
+  instanceRef?: { current: SankeyChartInstance | null };
+}
+
+/** <SankeyChart label="Embudo" nodes={[{ id: 'visitas' }, …]} links={[{ source: 'visitas', target: 'carrito', value: 420 }, …]} /> */
+export function SankeyChart({ nodes, links, height, nodeWidth, nodePadding, label, emptyLabel, formatValue, onSelect, instanceRef, className, ...props }: SankeyChartProps) {
+  const ref = useChart(createSankeyChart, { nodes, links, height, nodeWidth, nodePadding, label, emptyLabel } as SankeyChartOptions, { formatValue, onSelect }, instanceRef);
+  return <div {...props} ref={ref} className={['mk-chart mk-sankey-chart', className].filter(Boolean).join(' ')} />;
+}

package/src/components/sankey-chart/sankey-chart.css

@@ -0,0 +1,60 @@
+/* sankey-chart — bands that fade from their source's colour to their target's (35 %), nodes with 3 px corners;
+   needs chart.css for the family. The flow under the pointer lights up, the rest step back. */
+.mk-sankey-chart,
+mk-sankey-chart {
+  display: grid;
+  gap: 1rem;
+}
+
+[data-mk-chart-type='sankey'] [data-mk-chart-svg] {
+  cursor: pointer;
+}
+
+[data-mk-chart-type='sankey'] [data-mk-part='links'] path {
+  opacity: 0.35;
+  transition: opacity 0.2s ease;
+}
+
+[data-mk-chart-type='sankey'] [data-mk-part='links'] path[data-mk-on] {
+  opacity: 0.7;
+}
+
+[data-mk-chart-type='sankey'] [data-mk-part='links'] path[data-mk-dim] {
+  opacity: 0.1;
+}
+
+[data-mk-chart-type='sankey'] [data-mk-part='nodes'] rect {
+  transition: opacity 0.2s ease;
+}
+
+[data-mk-chart-type='sankey'] [data-mk-part='nodes'] rect[data-mk-dim] {
+  opacity: 0.45;
+}
+
+[data-mk-chart-type='sankey'] [data-mk-part='labels'] text {
+  fill: var(--mk-text);
+  font-size: 12px;
+  font-weight: 500;
+  paint-order: stroke;
+  stroke: var(--mk-chart-surface);
+  stroke-width: 3px;
+  stroke-linejoin: round;
+  pointer-events: none;
+}
+
+[data-mk-chart-type='sankey'] [data-mk-part='amount'] {
+  fill: var(--mk-muted);
+  font-weight: 400;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-mk-chart-type='sankey'] :is([data-mk-part='links'] path, [data-mk-part='nodes'] rect) {
+    transition: none;
+  }
+}
+
+@media (forced-colors: active) {
+  [data-mk-chart-type='sankey'] [data-mk-part='nodes'] rect {
+    fill: CanvasText !important;
+  }
+}

package/src/components/scratch-card/README.md

@@ -0,0 +1,15 @@
+# scratch-card
+
+Rasca y gana para cupones: el contenido HTML real queda bajo una cubierta metalizada dibujada en canvas con brillo y «Rasca aquí». El puntero rasca con un pincel redondo y el progreso se mide por muestreo. Al pasar el umbral, el resto se disuelve con blur, el cupón entra con `pop` y salta confeti. Mientras está cubierto, el contenido es `inert`; el botón «Revelar» es la vía para teclado y lectores de pantalla, y la revelación se anuncia. Sin canvas 2D, la cubierta es CSS y el botón la retira.
+
+```html
+<mk-scratch-card class="mk-scratch-card">
+  <div data-mk-scratch-content><strong>OTOÑO25</strong> · 25 % de descuento</div>
+</mk-scratch-card>
+```
+
+`defineElements()`, `createScratchCard(root, options)` (sin `[data-mk-scratch-content]`, los hijos del root pasan a uno) o `<ScratchCard onReveal={claim}>…</ScratchCard>`.
+
+Opciones: `threshold=0.5`, `brush=22` px, `coverLabel='Rasca aquí'`, `revealLabel='Revelar'`, `revealedLabel='Premio revelado'`, `celebrate=true`, `onProgress(p)`, `onReveal()`. API: `reveal()`, `reset()`, `revealed`, `progress`, `destroy()`. Eventos `mk:progress` `{progress}` y `mk:reveal`. El premio es de la app: el componente sólo lo tapa.
+
+Movimiento reducido: la cubierta desaparece sin blur ni confeti.

package/src/components/scratch-card/element.ts

@@ -0,0 +1,30 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createScratchCard, type ScratchCardInstance } from './engine';
+
+/**
+ * <mk-scratch-card class="mk-scratch-card" threshold="0.5">
+ *   <div data-mk-scratch-content>…the coupon…</div>
+ * </mk-scratch-card>
+ * Emits mk:progress ({progress}) and mk:reveal.
+ */
+export class MkScratchCardElement extends MkElement<ScratchCardInstance> {
+  static options: Record<string, OptionType> = { threshold: 'number', brush: 'number', coverLabel: 'string', revealLabel: 'string', revealedLabel: 'string', celebrate: 'boolean' };
+
+  protected create(options: Record<string, unknown>) {
+    return createScratchCard(this, options);
+  }
+
+  reveal() {
+    this.instance?.reveal();
+  }
+
+  reset() {
+    this.instance?.reset();
+  }
+
+  get revealed() {
+    return this.instance?.revealed ?? false;
+  }
+}
+
+export const defineScratchCard = () => defineElement('mk-scratch-card', MkScratchCardElement);