@yewdiel21/motion-kit 0.14.0 → 0.16.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/scroll-island/README.md

@@ -0,0 +1,44 @@
+# scroll-island
+
+Una barra fina que se transforma en una píldora con el porcentaje y la sección actual al acercar el puntero al borde derecho. Arrastra la píldora o pulsa su carril para desplazarte.
+
+## React
+
+```tsx
+import '@yewdiel21/motion-kit/css';
+import { ScrollIsland } from '@yewdiel21/motion-kit/react';
+
+<ScrollIsland persistent style={{ height: 360, overflow: 'auto' }}
+  tabIndex={0} role="region" aria-label="Guía de diseño">
+  <section style={{ minHeight: 400 }}><h3>Introducción</h3>Contenido…</section>
+  <section style={{ minHeight: 400 }}><h3>Detalles</h3>Contenido…</section>
+</ScrollIsland>
+```
+
+**El contenedor debe tener altura limitada, overflow y contenido suficiente para desplazarse.** Si todo cabe, la barra se oculta. `persistent` deja visible la barra fina mientras está en reposo; por defecto aparece al desplazarse y desaparece después.
+
+## HTML / Astro
+
+```html
+<mk-scroll-island persistent style="display:block;height:360px;overflow:auto"
+  tabindex="0" role="region" aria-label="Guía">
+  <section style="min-height:400px"><h3>Introducción</h3>Contenido…</section>
+  <section style="min-height:400px"><h3>Detalles</h3>Contenido…</section>
+</mk-scroll-island>
+<script>
+  import { defineElements } from '@yewdiel21/motion-kit/elements';
+  defineElements(['mk-scroll-island']);
+</script>
+```
+
+## Opciones
+
+- `page`: sigue el scroll de la página en vez del contenedor. En React `<ScrollIsland page />` no dibuja contenedor propio.
+- `sections`: selector de encabezados, `h2, h3` por defecto; `false` omite el nombre de sección en la factory/React.
+- `reach`: distancia del borde que activa la píldora, 56 px.
+- `idle`: demora para ocultarse, 900 ms.
+- `persistent`: mantiene la barra fina visible, false por defecto.
+- `onSection(section)`: cambio de sección, también `mk:section` con `detail.section`.
+- Factory `createScrollIsland(root, options)`; instancia `refresh()` y `destroy()`.
+
+El overlay decorativo usa `aria-hidden`; el contenido mantiene su desplazamiento nativo por teclado y tacto. Dale `tabindex="0"` y un nombre al panel. Respeta movimiento reducido, se adapta al tamaño del contenedor y elimina el overlay al desmontarse.

package/src/components/scroll-island/element.ts

@@ -0,0 +1,16 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createScrollIsland, type ScrollIslandInstance } from './engine';
+
+/**
+ * <mk-scroll-island class="mk-scroll-island" style="height: 24rem; overflow: auto">…</mk-scroll-island>
+ * or <mk-scroll-island page></mk-scroll-island> for the page. Emits mk:section ({section}).
+ */
+export class MkScrollIslandElement extends MkElement<ScrollIslandInstance> {
+  static options: Record<string, OptionType> = { sections: 'string', reach: 'number', idle: 'number', persistent: 'boolean', page: 'boolean' };
+
+  protected create(options: Record<string, unknown>) {
+    return createScrollIsland(options.page ? document.documentElement : this, options);
+  }
+}
+
+export const defineScrollIsland = () => defineElement('mk-scroll-island', MkScrollIslandElement);