@yewdiel21/motion-kit 0.9.1 → 0.14.0

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

@@ -0,0 +1,40 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createStatCard, type StatCardInstance } from './engine';
+
+/**
+ * <mk-stat-card class="mk-stat-card" label="Ingresos" value="128400" previous="118900"
+ *   format='{"style":"currency","currency":"MXN","maximumFractionDigits":0}' series="90,98,104,101,118,128"></mk-stat-card>
+ * Changing value, previous, series or target updates it in place (the figure counts).
+ */
+export class MkStatCardElement extends MkElement<StatCardInstance> {
+  static options: Record<string, OptionType> = {
+    label: 'string',
+    value: 'number',
+    previous: 'number',
+    format: 'json',
+    locale: 'string',
+    positive: 'string',
+    comparison: 'string',
+    series: 'list',
+    target: 'number',
+    countOnView: 'boolean',
+  };
+
+  protected create(options: Record<string, unknown>) {
+    return createStatCard(this, normalise(options));
+  }
+
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.instance) return;
+    if (name === 'locale' || name === 'count-on-view') return super.attributeChangedCallback(name, previous, next);
+    this.instance.update(normalise(this.options));
+  }
+}
+
+/** The series attribute is a comma list: numbers. */
+const normalise = (options: Record<string, unknown>) => ({
+  ...options,
+  series: Array.isArray(options.series) ? (options.series as string[]).map(Number).filter(Number.isFinite) : undefined,
+});
+
+export const defineStatCard = () => defineElement('mk-stat-card', MkStatCardElement);

package/src/components/stat-card/engine.ts

@@ -0,0 +1,283 @@
+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 { countTo } from '../../motion/count';
+import { rollDigits } from '../../motion/micro';
+
+/*
+ * Stat card: a KPI with its trend. The figure (Intl format of the page: money,
+ * percent, compact) counts up when the card comes into view (.9 s, flow); the
+ * change from `previous` sits in a badge (▲ / ▼ and the percentage, green when
+ * it moves the good way — `positive` says which — red when not, neutral when
+ * flat) that pops in after it while its arrow nudges; a sparkline of `series`
+ * draws itself (.9 s, wipe) with a soft area and an end dot that pops; a
+ * `target` fills a bar. update() counts from the shown figure to the new one,
+ * rolls the badge's digits, turns the arrow when the trend flips and morphs the
+ * sparkline to the new points. The visual figure is aria-hidden: a sentence
+ * with the final values speaks for it.
+ */
+
+export interface StatCardOptions {
+  label?: string;
+  value?: number;
+  /** The value it is compared with (the previous period). */
+  previous?: number;
+  /** Intl.NumberFormat options (e.g. { style: 'currency', currency: 'MXN' }) or a formatter. */
+  format?: Intl.NumberFormatOptions | ((value: number) => string);
+  /** Locale for the numbers (default: the page's language). */
+  locale?: string;
+  /** Which way is good (default 'up'; 'down' for costs, churn, latency). */
+  positive?: 'up' | 'down';
+  /** What the change compares with (default 'vs. periodo anterior'). */
+  comparison?: string;
+  /** Values for the sparkline (two or more). */
+  series?: number[];
+  /** A goal: a bar shows how far the value is. */
+  target?: number;
+  /** Count when it comes into view (default true); false shows the figure at once. */
+  countOnView?: boolean;
+}
+
+export interface StatCardInstance extends Instance {
+  update(next: Omit<StatCardOptions, 'countOnView' | 'locale'>): void;
+}
+
+type Trend = 'up' | 'down' | 'flat';
+const SVG = 'http://www.w3.org/2000/svg';
+const ARROW = '<svg aria-hidden="true" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.6" stroke-linecap="round" stroke-linejoin="round"><path d="M12 19V5M6 11l6-6 6 6"/></svg>';
+
+/** Sparkline points in a 100 × 32 box (2 px of air top and bottom). */
+const pointsOf = (series: number[]) => {
+  const lo = Math.min(...series);
+  const hi = Math.max(...series);
+  const span = hi - lo || 1;
+  return series.map((value, i) => [series.length === 1 ? 50 : (i / (series.length - 1)) * 100, 30 - ((value - lo) / span) * 28] as [number, number]);
+};
+const pathOf = (points: Array<[number, number]>) => `M${points.map(([x, y]) => `${x.toFixed(2)},${y.toFixed(2)}`).join('L')}`;
+
+export function createStatCard(root: HTMLElement | null, initial: StatCardOptions = {}): StatCardInstance {
+  if (!root) return inert({ update() {} });
+  registerMotion();
+  const scope = createScope();
+  let options: StatCardOptions = { ...initial };
+  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);
+  };
+  const locale = options.locale ?? root.closest('[lang]')?.getAttribute('lang') ?? undefined;
+  const formatter = () => {
+    if (typeof options.format === 'function') return options.format;
+    let intl: Intl.NumberFormat;
+    try {
+      intl = new Intl.NumberFormat(locale, { maximumFractionDigits: 1, ...options.format });
+    } catch {
+      intl = new Intl.NumberFormat(undefined, { maximumFractionDigits: 1 });
+    }
+    return (value: number) => intl.format(value);
+  };
+  const percent = new Intl.NumberFormat(locale, { maximumFractionDigits: 1, minimumFractionDigits: 1 });
+
+  const el = <K extends keyof HTMLElementTagNameMap>(tag: K, attribute: string) => {
+    const element = document.createElement(tag);
+    element.setAttribute(attribute, '');
+    return element;
+  };
+  const labelEl = el('span', 'data-mk-stat-label');
+  const row = el('div', 'data-mk-stat-row');
+  const valueEl = el('strong', 'data-mk-stat-value');
+  valueEl.setAttribute('aria-hidden', 'true');
+  const badge = el('span', 'data-mk-stat-delta');
+  badge.setAttribute('aria-hidden', 'true');
+  const arrow = el('span', 'data-mk-stat-arrow');
+  arrow.innerHTML = ARROW;
+  const deltaText = el('span', 'data-mk-stat-delta-text');
+  badge.append(arrow, deltaText);
+  row.append(valueEl, badge);
+  const comparisonEl = el('p', 'data-mk-stat-comparison');
+  comparisonEl.setAttribute('aria-hidden', 'true');
+  const sparkHost = el('div', 'data-mk-stat-spark');
+  sparkHost.setAttribute('aria-hidden', 'true');
+  const svg = document.createElementNS(SVG, 'svg');
+  svg.setAttribute('viewBox', '0 0 100 32');
+  svg.setAttribute('preserveAspectRatio', 'none');
+  const area = document.createElementNS(SVG, 'path');
+  area.setAttribute('data-mk-stat-area', '');
+  const line = document.createElementNS(SVG, 'path');
+  line.setAttribute('data-mk-stat-line', '');
+  line.setAttribute('vector-effect', 'non-scaling-stroke');
+  line.setAttribute('pathLength', '1');
+  svg.append(area, line);
+  const dot = el('span', 'data-mk-stat-dot');
+  sparkHost.append(svg, dot);
+  const target = el('div', 'data-mk-stat-target');
+  const targetBar = el('span', 'data-mk-stat-target-bar');
+  const targetFill = el('span', 'data-mk-stat-target-fill');
+  targetBar.append(targetFill);
+  const targetText = el('span', 'data-mk-stat-target-text');
+  target.append(targetBar, targetText);
+  const summary = el('span', 'data-mk-stat-summary');
+  summary.className = 'mk-sr-only';
+  root.append(labelEl, row, comparisonEl, sparkHost, target, summary);
+  scope.add(() => {
+    for (const effect of effects) effect.kill();
+    effects.clear();
+    gsap.killTweensOf([valueEl, badge, arrow, line, area, dot, targetFill]);
+    for (const part of [labelEl, row, comparisonEl, sparkHost, target, summary]) part.remove();
+  });
+  scope.attr(root, 'role', 'group');
+  scope.attr(root, 'aria-label', options.label ?? null);
+  scope.attr(root, 'data-mk-trend', null);
+  scope.attr(root, 'data-mk-good', null);
+  scope.attr(root, 'data-mk-ready', '');
+
+  const trendOf = (): { trend: Trend; change: number | null } => {
+    const { value, previous } = options;
+    if (typeof value !== 'number' || typeof previous !== 'number' || !Number.isFinite(value) || !Number.isFinite(previous) || previous === 0) return { trend: 'flat', change: null };
+    const change = ((value - previous) / Math.abs(previous)) * 100;
+    return { trend: Math.abs(change) < 0.05 ? 'flat' : change > 0 ? 'up' : 'down', change };
+  };
+
+  let shownPoints: Array<[number, number]> | null = null;
+  const drawSpark = (points: Array<[number, number]>) => {
+    line.setAttribute('d', pathOf(points));
+    area.setAttribute('d', `${pathOf(points)}L100,32L0,32Z`);
+    const [x, y] = points[points.length - 1]!;
+    dot.style.left = `${x}%`;
+    dot.style.top = `${(y / 32) * 100}%`;
+  };
+
+  /** Write everything but the figure; `animate` runs the update motion. */
+  const paint = (animate: boolean, previousTrend: Trend | null) => {
+    const format = formatter();
+    labelEl.textContent = options.label ?? '';
+    labelEl.hidden = !options.label;
+    if (options.label) root.setAttribute('aria-label', options.label);
+    else root.removeAttribute('aria-label');
+    const { trend, change } = trendOf();
+    const good = trend === 'flat' ? 'neutral' : (trend === 'up') === ((options.positive ?? 'up') === 'up') ? 'good' : 'bad';
+    root.setAttribute('data-mk-trend', trend);
+    root.setAttribute('data-mk-good', good);
+    badge.hidden = change === null;
+    const text = change === null ? '' : `${trend === 'flat' ? '' : trend === 'up' ? '+' : '−'}${percent.format(Math.abs(change))} %`;
+    if (animate && !reduced() && deltaText.textContent && deltaText.textContent !== text) keep(rollDigits(deltaText, text, trend === 'down' ? -1 : 1, 0.3));
+    else deltaText.textContent = text;
+    if (animate && previousTrend && previousTrend !== trend && !reduced()) keep(gsap.fromTo(arrow, { scale: 0.6 }, { scale: 1, duration: 0.35, ease: EASE.click, clearProps: 'scale' }));
+    const comparison = options.comparison ?? 'vs. periodo anterior';
+    comparisonEl.textContent = typeof options.previous === 'number' ? `${comparison} (${format(options.previous)})` : '';
+    comparisonEl.hidden = typeof options.previous !== 'number';
+    // Sparkline: draw, or morph from the shown points.
+    const series = (options.series ?? []).filter((value) => Number.isFinite(value));
+    sparkHost.hidden = series.length < 2;
+    if (series.length >= 2) {
+      const next = pointsOf(series);
+      if (animate && shownPoints && shownPoints.length === next.length && !reduced()) {
+        const from = shownPoints.map((point) => [...point]) as Array<[number, number]>;
+        const state = { t: 0 };
+        keep(
+          gsap.to(state, {
+            t: 1,
+            duration: 0.6,
+            ease: EASE.swatch,
+            onUpdate: () => drawSpark(from.map(([x, y], i) => [x + (next[i]![0] - x) * state.t, y + (next[i]![1] - y) * state.t])),
+          }),
+        );
+      } else drawSpark(next);
+      shownPoints = next;
+    } else shownPoints = null;
+    // Target bar.
+    const goal = options.target;
+    const hasTarget = typeof goal === 'number' && goal > 0 && typeof options.value === 'number';
+    target.hidden = !hasTarget;
+    if (hasTarget) {
+      const ratio = Math.max(0, Math.min(1, options.value! / goal!));
+      targetText.textContent = `${percent.format(ratio * 100)} % de la meta (${format(goal!)})`;
+      if (animate && !reduced()) keep(gsap.to(targetFill, { scaleX: ratio, duration: 0.6, ease: EASE.wipe }));
+      else gsap.set(targetFill, { scaleX: ratio });
+    }
+    // The sentence that speaks for the figure.
+    const value = typeof options.value === 'number' ? format(options.value) : '—';
+    const said = change === null ? '' : trend === 'flat' ? ` Sin cambio ${comparison}.` : ` ${trend === 'up' ? 'Sube' : 'Baja'} ${percent.format(Math.abs(change))} % ${comparison}.`;
+    summary.textContent = `${options.label ? `${options.label}: ` : ''}${value}.${said}`;
+  };
+
+  /** The figure: counted (from `from`) or written. */
+  const figure = (from: number | null) => {
+    const value = options.value;
+    if (typeof value !== 'number') {
+      valueEl.textContent = '—';
+      return;
+    }
+    if (from === null || reduced()) {
+      countTo(valueEl, value, { from: value, format: formatter() });
+      return;
+    }
+    keep(countTo(valueEl, value, { from, duration: 0.9, format: formatter() }));
+  };
+
+  /** The first appearance: figure counts, badge pops, sparkline draws, target fills. */
+  const enter = () => {
+    paint(false, null);
+    if (reduced() || options.countOnView === false) {
+      figure(null);
+      return;
+    }
+    figure(0);
+    if (!badge.hidden) {
+      keep(gsap.fromTo(badge, { opacity: 0, scale: 0.6, filter: 'blur(4px)' }, { opacity: 1, scale: 1, filter: 'blur(0px)', duration: 0.35, delay: 0.45, ease: EASE.pop, clearProps: 'opacity,transform,filter' }));
+      keep(gsap.fromTo(arrow, { y: root.dataset.mkTrend === 'down' ? -4 : 4 }, { y: 0, duration: 0.45, delay: 0.6, ease: EASE.click, clearProps: 'transform' }));
+    }
+    if (!sparkHost.hidden) {
+      keep(gsap.fromTo(line, { strokeDasharray: 1, strokeDashoffset: 1 }, { strokeDashoffset: 0, duration: 0.9, ease: EASE.wipe, clearProps: 'strokeDasharray,strokeDashoffset' }));
+      keep(gsap.fromTo(area, { opacity: 0 }, { opacity: 1, duration: 0.5, delay: 0.4, ease: 'power1.out', clearProps: 'opacity' }));
+      keep(gsap.fromTo(dot, { scale: 0 }, { scale: 1, duration: 0.3, delay: 0.85, ease: EASE.pop, clearProps: 'scale' }));
+    }
+    if (!target.hidden) {
+      const ratio = gsap.getProperty(targetFill, 'scaleX') as number;
+      keep(gsap.fromTo(targetFill, { scaleX: 0 }, { scaleX: ratio, duration: 0.8, delay: 0.2, ease: EASE.wipe }));
+    }
+  };
+
+  let entered = false;
+  if (typeof IntersectionObserver === 'function' && options.countOnView !== false && !reduced()) {
+    paint(false, null);
+    valueEl.textContent = formatter()(0);
+    gsap.set([badge, dot], { opacity: 0 });
+    const observer = scope.observe(
+      new IntersectionObserver((entries) => {
+        if (entered || !entries.some((entry) => entry.isIntersecting)) return;
+        entered = true;
+        gsap.set([badge, dot], { clearProps: 'opacity' });
+        observer.disconnect();
+        enter();
+      }, { threshold: 0.4 }),
+    );
+    observer.observe(root);
+  } else {
+    entered = true;
+    paint(false, null);
+    figure(null);
+  }
+
+  return {
+    update(next) {
+      if (scope.disposed) return;
+      const previousTrend = (root.dataset.mkTrend as Trend | undefined) ?? null;
+      options = { ...options, ...next };
+      if (!entered) {
+        paint(false, null);
+        return;
+      }
+      paint(true, previousTrend);
+      const value = options.value;
+      if (typeof value !== 'number') valueEl.textContent = '—';
+      // countTo carries on from the figure it last wrote.
+      else if (reduced()) countTo(valueEl, value, { from: value, format: formatter() });
+      else keep(countTo(valueEl, value, { duration: 0.9, format: formatter() }));
+    },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/stat-card/react.tsx

@@ -0,0 +1,36 @@
+'use client';
+import { useRef, type HTMLAttributes } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createStatCard, type StatCardInstance, type StatCardOptions } from './engine';
+
+export interface StatCardProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'>, StatCardOptions {}
+
+/** <StatCard label="Ingresos" value={128400} previous={118900} format={{ style: 'currency', currency: 'MXN' }} series={week} />. */
+export function StatCard({ label, value, previous, format, locale, positive, comparison, series, target, countOnView, className, ...props }: StatCardProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const instance = useRef<StatCardInstance | null>(null);
+  const formatter = useLatest(format);
+  const custom = typeof format === 'function';
+  const data = { label, value, previous, positive, comparison, series, target, format: custom ? undefined : format };
+  const key = JSON.stringify(data);
+  const options = () => ({ ...data, format: custom ? (n: number) => (formatter.current as (n: number) => string)(n) : data.format });
+  useIsomorphicLayoutEffect(() => {
+    const created = createStatCard(ref.current, { ...options(), locale, countOnView });
+    instance.current = created;
+    return () => {
+      created.destroy();
+      instance.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [locale, countOnView]);
+  const first = useRef(true);
+  useIsomorphicLayoutEffect(() => {
+    if (first.current) {
+      first.current = false;
+      return;
+    }
+    instance.current?.update(options());
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key, custom]);
+  return <div {...props} ref={ref} className={['mk-stat-card', className].filter(Boolean).join(' ')} />;
+}

package/src/components/stat-card/stat-card.css

@@ -0,0 +1,163 @@
+/* stat-card — a 20 px card on surface-1: a muted label, a 2rem tabular figure, a pill badge with the change (green
+   when it moves the good way, red when not, neutral when flat), the comparison line, a 2 px sparkline over a soft
+   area with an end dot, and an optional goal bar. --mk-stat-good / --mk-stat-bad recolour the badge. */
+.mk-stat-card,
+mk-stat-card {
+  --mk-stat-good: #1f9d5b;
+  --mk-stat-bad: var(--mk-error, #c62828);
+  --mk-stat-line: var(--mk-accent);
+  display: grid;
+  gap: 0.5rem;
+  box-sizing: border-box;
+  min-width: 0;
+  padding: 1.1rem 1.2rem 1.2rem;
+  border: 1px solid var(--mk-outline-soft);
+  border-radius: 20px;
+  background: var(--mk-surface-1);
+  color: var(--mk-text);
+}
+
+[data-mk-stat-label] {
+  overflow: hidden;
+  color: var(--mk-muted);
+  font-size: 0.875rem;
+  font-weight: 500;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+[data-mk-stat-row] {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.35rem 0.6rem;
+  min-width: 0;
+}
+
+[data-mk-stat-value] {
+  min-width: 0;
+  overflow-wrap: anywhere;
+  font-size: clamp(1.5rem, 4vw, 2rem);
+  font-variant-numeric: tabular-nums;
+  font-weight: 600;
+  letter-spacing: -0.02em;
+  line-height: 1.1;
+}
+
+[data-mk-stat-delta] {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.2rem;
+  height: 1.5rem;
+  padding: 0 0.5rem 0 0.4rem;
+  border-radius: 999px;
+  background: color-mix(in srgb, var(--mk-muted) 14%, transparent);
+  color: var(--mk-muted);
+  font-size: 0.8125rem;
+  font-variant-numeric: tabular-nums;
+  font-weight: 600;
+  white-space: nowrap;
+  transition: background-color 0.3s ease, color 0.3s ease;
+}
+
+:is(.mk-stat-card, mk-stat-card)[data-mk-good='good'] [data-mk-stat-delta] {
+  background: color-mix(in srgb, var(--mk-stat-good) 16%, transparent);
+  color: var(--mk-stat-good);
+}
+
+:is(.mk-stat-card, mk-stat-card)[data-mk-good='bad'] [data-mk-stat-delta] {
+  background: color-mix(in srgb, var(--mk-stat-bad) 14%, transparent);
+  color: var(--mk-stat-bad);
+}
+
+[data-mk-stat-arrow] {
+  display: inline-grid;
+  transition: rotate 0.35s cubic-bezier(0.38, 0.49, 0, 1.5);
+}
+
+:is(.mk-stat-card, mk-stat-card)[data-mk-trend='down'] [data-mk-stat-arrow] {
+  rotate: 180deg;
+}
+
+:is(.mk-stat-card, mk-stat-card)[data-mk-trend='flat'] [data-mk-stat-arrow] {
+  rotate: 90deg;
+}
+
+[data-mk-stat-comparison] {
+  margin: 0;
+  color: var(--mk-muted);
+  font-size: 0.8125rem;
+}
+
+[data-mk-stat-spark] {
+  position: relative;
+  height: 2.5rem;
+  margin-top: 0.25rem;
+  color: var(--mk-stat-line);
+}
+
+[data-mk-stat-spark] svg {
+  display: block;
+  width: 100%;
+  height: 100%;
+  overflow: visible;
+}
+
+[data-mk-stat-line] {
+  fill: none;
+  stroke: currentColor;
+  stroke-width: 2px;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+}
+
+[data-mk-stat-area] {
+  fill: color-mix(in srgb, currentColor 14%, transparent);
+}
+
+[data-mk-stat-dot] {
+  position: absolute;
+  width: 8px;
+  height: 8px;
+  margin: -4px 0 0 -4px;
+  border-radius: 50%;
+  background: currentColor;
+  box-shadow: 0 0 0 2.5px var(--mk-surface-1);
+}
+
+[data-mk-stat-target] {
+  display: grid;
+  gap: 0.35rem;
+}
+
+[data-mk-stat-target-bar] {
+  display: block;
+  height: 6px;
+  overflow: hidden;
+  border-radius: 999px;
+  background: var(--mk-surface-3);
+}
+
+[data-mk-stat-target-fill] {
+  display: block;
+  height: 100%;
+  border-radius: inherit;
+  background: var(--mk-stat-line);
+  transform-origin: 0 50%;
+}
+
+[data-mk-stat-target-text] {
+  color: var(--mk-muted);
+  font-size: 0.75rem;
+}
+
+:is(.mk-stat-card, mk-stat-card) [hidden] {
+  display: none;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-mk-stat-delta],
+  [data-mk-stat-arrow] {
+    transition: none;
+  }
+}

package/src/components/studio-dock/README.md

@@ -0,0 +1,44 @@
+# studio-dock
+
+Navegación de estudio que pasa de una píldora a un panel de tarjetas. Inspirada en el comportamiento público de Mubien; código y gráficos propios, sin sus fuentes, marcas o videos.
+
+```html
+<div class="mk-studio-dock" data-mk="studio-dock">
+  <div class="mk-studio-dock__bar">
+    <a href="/" class="mk-studio-dock__brand">ST</a>
+    <span class="mk-studio-dock__label">Estudio</span>
+    <button type="button" class="mk-studio-dock__toggle" data-mk-studio-toggle aria-label="Abrir navegación"><span aria-hidden="true">+</span></button>
+  </div>
+  <section class="mk-studio-dock__panel" data-mk-studio-panel hidden>
+    <div data-mk-studio-view="menu">
+      <div class="mk-studio-dock__grid">
+        <a href="/work" class="mk-studio-dock__tile">Proyectos</a>
+        <a href="/about" class="mk-studio-dock__tile">Estudio</a>
+      </div>
+      <button type="button" data-mk-studio-slide>Contacto</button>
+    </div>
+    <div data-mk-studio-view="contact" hidden>
+      <h2>Conversemos</h2><a href="mailto:hello@example.com">hello@example.com</a>
+      <button type="button" data-mk-studio-to="menu">Volver</button>
+    </div>
+  </section>
+</div>
+```
+
+```ts
+import { createStudioDock } from '@yewdiel21/motion-kit';
+import { useStudioDock, StudioDock } from '@yewdiel21/motion-kit/react';
+import '@yewdiel21/motion-kit/css';
+const dock = createStudioDock(root, { duration: 1.3, ease: 'back.out(0.52)' });
+dock.open('contact'); dock.selectPage(1); dock.close(); dock.destroy();
+```
+
+`StudioDock` es un shell React con los mismos slots y `instanceRef`; `useStudioDock(ref, options, deps)` permite usar tu markup. Web component: `defineStudioDock()` registra `<mk-studio-dock>`. El evento `mk:studio-dock` y `onChange` entregan `{ open, view, page }`.
+
+Slots opcionales: `[data-mk-studio-to="menu|contact|reel"]`, `[data-mk-studio-close]`, `[data-mk-studio-pages]`, `[data-mk-studio-page]`, botones `[data-mk-studio-page-to="0"]` y `<time data-mk-studio-timezone="America/Mazatlan">`. Las páginas se ocultan con `hidden`; el paginado tiene flechas izquierda/derecha y botones numerados. Los relojes usan `Intl` y actualizan cada minuto; no consultan ningún servidor.
+
+El botón de contacto funciona con clic, Enter y Espacio. Dentro de `.mk-studio-dock__slide-track` también acepta arrastre y abre al superar 70 % del recorrido. Las vistas reciben foco, Escape cierra, clic fuera cierra sin robar foco al destino y el cierre explícito devuelve el foco anterior. `trapFocus` y `focusOnOpen` son `true` por defecto y se pueden desactivar. El panel es un diálogo contenido, sin bloqueo del body ni cambios en otros componentes. `aria-expanded` refleja el estado y el panel cerrado queda fuera del árbol de accesibilidad.
+
+El panel se revela/colapsa por `clip-path` y desplazamiento de 16 px; duración configurable de 1.3 s, rebote `.52`. Con movimiento reducido se salta el recorrido. `destroy()` es idempotente: revierte estilos/atributos, listeners, temporizadores y animaciones. Los videos aportados por el consumidor se pausan al salir de su vista. No se envía ningún formulario desde este motor.
+
+Por defecto permanece dentro del layout. Usa `.mk-studio-dock--fixed` o `<StudioDock fixed>` para fijarlo abajo de la ventana. Al abrirse, el panel mide el espacio que queda en la ventana: su alto se limita a ese hueco (con scroll interno) y, si arriba no cabe y abajo hay más sitio, se abre bajo la barra (`data-mk-studio-below`). `--mk-studio-dock-offset` (76 px) es la distancia del panel al borde del dock. Variables de color: `--mk-surface`, `--mk-surface-2`, `--mk-accent`, `--mk-on-accent`, `--mk-outline-soft`.

package/src/components/studio-dock/element.ts

@@ -0,0 +1,11 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createStudioDock, type StudioDockInstance, type StudioDockView } from './engine';
+export class MkStudioDockElement extends MkElement<StudioDockInstance> {
+  static options: Record<string, OptionType> = { duration: 'number', ease: 'string', focusOnOpen: 'boolean', trapFocus: 'boolean' };
+  protected create(options: Record<string, unknown>) { return createStudioDock(this, options); }
+  open(view?: StudioDockView) { this.instance?.open(view); }
+  close() { this.instance?.close(); }
+  toggle() { this.instance?.toggle(); }
+  selectPage(index: number) { this.instance?.selectPage(index); }
+}
+export const defineStudioDock = () => defineElement('mk-studio-dock', MkStudioDockElement);