@yewdiel21/motion-kit 0.17.0 → 0.18.0

package/src/components/signature-pad/signature-pad.css

@@ -1,103 +1,130 @@
-/* Normalized SVG ink survives layout changes. Only the drawing area captures touch. */
-.mk-signature-pad,
-mk-signature-pad {
-  --mk-signature-height: clamp(12rem, 32vw, 17rem);
-  display: block;
-  min-width: 0;
-  overflow: hidden;
-  border: 1px solid var(--mk-outline-soft);
-  border-radius: 24px;
-  background: var(--mk-surface-1);
-  color: var(--mk-text);
-  font-family: var(--mk-font);
-}
-
-:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-surface] {
-  position: relative;
-  height: var(--mk-signature-height);
-  min-height: 8rem;
-  overflow: hidden;
-  background: var(--mk-signature-paper, var(--mk-surface-2));
-  cursor: crosshair;
-  touch-action: none;
-  user-select: none;
-  -webkit-user-select: none;
-}
-
-:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-surface]::after {
-  position: absolute;
-  right: 1.5rem;
-  bottom: 2rem;
-  left: 1.5rem;
-  border-bottom: 1px dashed var(--mk-outline-soft);
-  content: '';
-  pointer-events: none;
-}
-
-:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-drawing] {
-  position: absolute;
-  inset: 0;
-  display: block;
-  width: 100%;
-  height: 100%;
-  overflow: hidden;
-}
-
-:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-placeholder] {
-  position: absolute;
-  inset: 0;
-  display: grid;
-  place-items: center;
-  color: var(--mk-muted);
-  font-size: 1.5rem;
-  font-style: italic;
-  font-weight: 400;
-  pointer-events: none;
-}
-
-:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-placeholder][hidden] { display: none; }
-
-:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-footer] {
-  display: flex;
-  flex-wrap: wrap;
-  align-items: center;
-  justify-content: space-between;
-  gap: 0.75rem;
-  padding: 0.875rem 1rem 0;
-}
-
-:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-toolbar] {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 0.375rem;
-}
-
-:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-action] {
-  min-height: 2.75rem;
-  padding: 0.5rem 0.875rem;
-  border: 1px solid var(--mk-outline-soft);
-  border-radius: 64px;
-  background: var(--mk-surface-3);
-  color: var(--mk-text);
-  font: inherit;
-  font-size: 0.8125rem;
-  font-weight: 500;
-  cursor: pointer;
-}
-
-:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-action]:hover:enabled { background: var(--mk-surface-4); }
-:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-action]:focus-visible { outline: 2px solid var(--mk-accent); outline-offset: 2px; }
-:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-action]:disabled { opacity: 0.4; cursor: default; }
-
-:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-status],
-:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-hint] {
-  color: var(--mk-muted);
-  font-size: 0.75rem;
-  line-height: 1.5;
-}
-
-:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-status] { font-variant-numeric: tabular-nums; }
-:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-hint] { margin: 0; padding: 0.75rem 1rem 1rem; }
-:is(.mk-signature-pad, mk-signature-pad)[data-mk-readonly] [data-mk-signature-surface],
-:is(.mk-signature-pad, mk-signature-pad)[data-mk-disabled] [data-mk-signature-surface] { cursor: default; touch-action: auto; }
-:is(.mk-signature-pad, mk-signature-pad)[data-mk-disabled] [data-mk-signature-surface] { opacity: 0.55; }
+/* Normalized SVG ink survives layout changes. Only the drawing area captures touch. */
+.mk-signature-pad,
+mk-signature-pad {
+  --mk-signature-height: clamp(12rem, 32vw, 17rem);
+  display: block;
+  min-width: 0;
+  overflow: hidden;
+  border: 1px solid var(--mk-outline-soft);
+  border-radius: 24px;
+  background: var(--mk-surface-1);
+  color: var(--mk-text);
+  font-family: var(--mk-font);
+}
+[data-mk-signature-header] { display: flex; flex-wrap: wrap; justify-content: space-between; align-items: center; gap: .5rem; padding: 1rem 1.25rem; font-size: .8125rem; font-weight: 500; }
+[data-mk-signature-header] [data-mk-signature-status] { display: inline-flex; gap: .4rem; align-items: center; }
+[data-mk-signature-status]::before { content: ''; width: 6px; height: 6px; flex: none; border-radius: 50%; background: var(--mk-muted); transition: background .2s; }
+:is(.mk-signature-pad, mk-signature-pad):not([data-mk-empty]) [data-mk-signature-status]::before { background: var(--mk-accent); animation: mk-signature-dot .45s var(--mk-ease-swatch); }
+@keyframes mk-signature-dot { from { scale: .2; } }
+
+:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-surface] {
+  position: relative;
+  height: var(--mk-signature-height);
+  min-height: 8rem;
+  overflow: hidden;
+  background: var(--mk-signature-paper, var(--mk-surface-2));
+  margin-inline: 8px;
+  border-radius: var(--mk-radius-md);
+  cursor: crosshair;
+  touch-action: none;
+  user-select: none;
+  -webkit-user-select: none;
+}
+[data-mk-signature-cursor] { position: absolute; top: 0; left: 0; width: 16px; height: 16px; border: 1px solid currentColor; border-radius: 50%; opacity: 0; transform: translate(-50%, -50%) scale(.5); pointer-events: none; transition: opacity .12s, width .3s var(--mk-ease-click), height .3s var(--mk-ease-click), transform .3s var(--mk-ease-click); }
+[data-mk-pen-visible]:not([data-mk-disabled]):not([data-mk-readonly]) [data-mk-signature-cursor] { opacity: .45; transform: translate(-50%, -50%) scale(1); }
+[data-mk-drawing] [data-mk-signature-cursor] { width: 8px; height: 8px; background: currentColor; }
+
+:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-surface]::after {
+  position: absolute;
+  right: 1.5rem;
+  bottom: 2rem;
+  left: 1.5rem;
+  border-bottom: 1px dashed var(--mk-outline-soft);
+  content: '';
+  pointer-events: none;
+  transition: border-color .25s;
+}
+/* The line you sign on wakes while the pen is down. */
+:is(.mk-signature-pad, mk-signature-pad)[data-mk-drawing] [data-mk-signature-surface]::after { border-bottom-color: color-mix(in srgb, var(--mk-text) 40%, transparent); }
+
+:is(.mk-signature-pad, mk-signature-pad) :is([data-mk-signature-drawing], [data-mk-signature-ghost]) {
+  position: absolute;
+  inset: 0;
+  display: block;
+  width: 100%;
+  height: 100%;
+  overflow: hidden;
+}
+
+:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-placeholder] {
+  position: absolute;
+  inset: 0;
+  display: grid;
+  place-items: center;
+  color: var(--mk-muted);
+  font-size: 1.5rem;
+  font-style: italic;
+  font-weight: 400;
+  pointer-events: none;
+  /* Returning waits for leaving ink, so the prompt never sits on top of it. */
+  transition: opacity .3s ease .3s, filter .3s ease .3s, scale .45s var(--mk-ease-swatch) .3s;
+}
+
+:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-placeholder][hidden] { display: grid; opacity: 0; filter: blur(6px); scale: .96; transition-duration: .16s; transition-delay: 0s; }
+
+:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-footer] {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.75rem;
+  padding: 0.875rem 1rem 0;
+}
+
+:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-toolbar] {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.375rem;
+}
+
+:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-action] {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: .4rem;
+  min-height: 2.75rem;
+  padding: 0.5rem 0.875rem;
+  border: 0;
+  border-radius: var(--mk-radius-sm);
+  background: var(--mk-surface-3);
+  color: var(--mk-text);
+  font: inherit;
+  font-size: 0.8125rem;
+  font-weight: 500;
+  cursor: pointer;
+  transition: background .15s, border-radius .3s var(--mk-ease-playful), opacity .2s;
+}
+[data-mk-signature-action] svg { width: 17px; height: 17px; }
+
+:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-action]:hover:enabled { background: var(--mk-surface-4); border-radius: var(--mk-radius-full); }
+:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-action]:focus-visible { outline: 2px solid var(--mk-accent); outline-offset: 2px; }
+:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-action]:disabled { opacity: 0.4; cursor: default; }
+
+:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-status],
+:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-hint] {
+  color: var(--mk-muted);
+  font-size: 0.75rem;
+  line-height: 1.5;
+}
+
+:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-status] { font-variant-numeric: tabular-nums; }
+:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-hint] { margin: 0; padding: 0.75rem 1rem 1rem; }
+:is(.mk-signature-pad, mk-signature-pad)[data-mk-readonly] [data-mk-signature-surface],
+:is(.mk-signature-pad, mk-signature-pad)[data-mk-disabled] [data-mk-signature-surface] { cursor: default; touch-action: auto; }
+:is(.mk-signature-pad, mk-signature-pad)[data-mk-disabled] [data-mk-signature-surface] { opacity: 0.55; }
+@media (prefers-reduced-motion: reduce) {
+  [data-mk-signature-cursor], [data-mk-signature-action], [data-mk-signature-placeholder], [data-mk-signature-surface]::after { transition: none !important; }
+  [data-mk-signature-status]::before { animation: none !important; }
+}
+
+:is(.mk-signature-pad, mk-signature-pad) [data-mk-signature-ghost] { pointer-events: none; }

package/src/components/stepper/README.md

@@ -0,0 +1,46 @@
+# Stepper
+
+Navegación de progreso para workflows, con marcadores horizontales, verticales, compactos o puntos. El paso actual cambia su radio y la marca entra con pop; las filas llegan con blur escalonado. El contenido de cada paso pertenece a la aplicación, distinto del motor de paneles steps.
+
+```ts
+import { createStepper } from '@yewdiel21/motion-kit';
+import '@yewdiel21/motion-kit/css/stepper';
+
+const control = createStepper(document.querySelector('.mk-stepper'), {
+  items: [{label: 'Cuenta'}, {label: 'Perfil'}, {label: 'Listo'}],
+  value: 0, label: 'Alta', onChange: renderCurrentStep,
+});
+control.next();
+control.previous();
+control.setValue(2);
+```
+
+## Opciones y contrato
+
+`items: { label, description?, disabled?, completed?, error? }[]`, `variant: horizontal | vertical | compact | dots` (horizontal), `value` / `defaultValue` (índice desde 0), `linear`, `disabled`, `label`, `name`, `onChange(index)`.
+
+Los botones tienen type=button y solo uno lleva aria-current=step. linear permite entrar al siguiente paso habilitado y volver a los visitados. next/previous omiten pasos disabled. setValue permite a la app navegar de forma explícita; las opciones disabled bloquean los gestos del usuario, no las actualizaciones imperativas. name añade un input oculto con el índice. La lista vacía indica que no hay pasos.
+
+La instancia expone `value: number`, `setValue(value, notify = false)`, `reset(notify = false)` y `destroy()`. Las escrituras imperativas actualizan el control incluso estando disabled. `setValue` no cambia el valor inicial al que vuelve reset. Las notificaciones usan callbacks y eventos `mk:change` con `detail: { value }`.
+
+## React y HTML
+
+```tsx
+import { Stepper } from '@yewdiel21/motion-kit/react';
+
+<Stepper items={steps} value={step} onChange={setStep} variant="compact" />
+<section>{panels[step]}</section>
+```
+
+`value` controla la instancia; `defaultValue` inicia una instancia que conserva sus propios cambios. Las opciones pueden cambiar sin perder la selección no controlada. `instanceRef` recibe la instancia y admite cambiar de objeto ref. Los children y dangerouslySetInnerHTML no se pasan al host porque el motor posee ese DOM.
+
+```html
+<mk-stepper class="mk-stepper" items='[{"label":"Cuenta"},{"label":"Perfil"},{"label":"Listo"}]' value="0" variant="horizontal"></mk-stepper>
+```
+
+Registra con `defineStepper()` desde `@yewdiel21/motion-kit/elements` o utiliza el auto registro. Los atributos de opciones se pueden cambiar en vivo; el valor imperativo se conserva al cambiar otra opción. `disabled="false"` se lee como false. El elemento expone `value`, `setValue`, `reset`, `next` y `previous`.
+
+## Accesibilidad y lifecycle
+
+Los botones mantienen Tab, Enter y Espacio; cada estado se describe en el nombre accesible. El reset de formulario es cancelable; el control espera al reset nativo y verifica defaultPrevented. Movimiento reducido conserva toda la funcionalidad. destroy es idempotente y libera animaciones, eventos y timers, elimina solo las partes creadas y restaura los atributos del host. Los temas utilizan DM Sans y tokens --mk-*; el CSS de este componente es independiente de los otros estilos.
+

package/src/components/stepper/element.ts

@@ -0,0 +1,42 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createStepper, type StepperInstance } from './engine';
+
+/** Light DOM; attribute changes keep the current imperative value and reset baseline. */
+export class MkStepperElement extends MkElement<StepperInstance> {
+  static options: Record<string, OptionType> = {"items":"json","value":"number","label":"string","name":"string","variant":"string","linear":"boolean","disabled":"boolean"};
+  private baseline: number | undefined;
+  private saved: number | undefined;
+  protected create(options: Record<string, unknown>) {
+    const created = createStepper(this, { ...options, value: this.saved !== undefined ? this.saved : options.value as number | undefined, defaultValue: this.baseline });
+    if (this.baseline === undefined) this.baseline = created.value;
+    this.saved = undefined;
+    return created;
+  }
+  disconnectedCallback() {
+    this.saved = this.instance?.value;
+    super.disconnectedCallback();
+  }
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next) return;
+    if (name === 'value' && (!this.instance || !this.isConnected)) {
+      this.saved = next === null ? this.baseline ?? 0 : Number.isFinite(Number(next)) ? Number(next) : this.baseline ?? 0;
+      return;
+    }
+    if (!this.instance || !this.isConnected) return;
+    if (name === 'value') {
+      const parsed = next === null ? this.baseline ?? 0 : Number(next);
+      this.instance.setValue(parsed, false);
+      return;
+    }
+    this.saved = this.instance.value;
+    super.attributeChangedCallback(name, previous, next);
+  }
+  get value(): number { return this.instance?.value ?? this.saved ?? 0; }
+  set value(next: number) { this.setValue(next); }
+  setValue(value: number, notify = false) { if (this.instance) this.instance.setValue(value, notify); else this.saved = value; }
+  reset(notify = false) { this.instance?.reset(notify); }
+  next(notify = true) { this.instance?.next(notify); }
+  previous(notify = true) { this.instance?.previous(notify); }
+}
+export const defineStepper = () => defineElement('mk-stepper', MkStepperElement);
+

package/src/components/stepper/engine.ts

@@ -0,0 +1,103 @@
+import { gsap, EASE, registerMotion } from '../../core/gsap';
+import { createScope } from '../../core/scope';
+import { reduced } from '../../core/reduced';
+import { inert, type Instance } from '../../core/types';
+import { blurIn, press, rollDigits } from '../../motion/micro';
+
+export interface StepperItem { label: string; description?: string; disabled?: boolean; completed?: boolean; error?: boolean }
+export interface StepperOptions {
+  items?: StepperItem[]; value?: number; defaultValue?: number; label?: string; name?: string;
+  variant?: 'horizontal' | 'vertical' | 'compact' | 'dots';
+  /** Only the next unfinished step can be entered with the navigation buttons. */
+  linear?: boolean; disabled?: boolean;
+  onChange?: (value: number) => void;
+}
+export interface StepperInstance extends Instance {
+  readonly value: number;
+  setValue(value: number, notify?: boolean): void;
+  next(notify?: boolean): void; previous(notify?: boolean): void; reset(notify?: boolean): void;
+}
+export function createStepper(root: HTMLElement | null, options: StepperOptions = {}): StepperInstance {
+  if (!root) return inert({ value: 0, setValue() {}, next() {}, previous() {}, reset() {} });
+  registerMotion();
+  const scope = createScope();
+  const effects = new Set<gsap.core.Animation>();
+  const keep = (effect: gsap.core.Animation | null) => {
+    for (const prior of effects) if (prior.totalProgress() === 1) effects.delete(prior);
+    if (effect) effects.add(effect);
+  };
+  scope.add(() => { effects.forEach((effect) => effect.kill()); effects.clear(); });
+  const items = (Array.isArray(options.items) ? options.items : []).filter((item) => item && typeof item.label === 'string');
+  const clamp = (n: number) => Math.max(0, Math.min(Math.max(0, items.length - 1), Number.isFinite(n) ? Math.round(n) : 0));
+  const initial = clamp(options.defaultValue ?? options.value ?? 0);
+  let value = clamp(options.value ?? initial); let furthest = value;
+  let pending: { value: number; furthest: number } | null = null;
+  const nav = document.createElement('nav'); nav.dataset.mkStepperBody = ''; nav.setAttribute('aria-label', options.label ?? 'Progreso');
+  const list = document.createElement('ol'); list.dataset.mkStepperList = ''; nav.append(list);
+  const caption = document.createElement('span'); caption.dataset.mkStepperCaption = ''; caption.setAttribute('aria-live', 'polite'); nav.append(caption);
+  root.append(nav); scope.add(() => nav.remove());
+  const buttons: HTMLButtonElement[] = []; const rows: HTMLLIElement[] = []; const marks: HTMLElement[] = [];
+  items.forEach((item, index) => {
+    const row = document.createElement('li'); row.dataset.mkStepperItem = '';
+    const button = document.createElement('button'); button.type = 'button'; button.dataset.mkStepperStep = String(index);
+    const marker = document.createElement('span'); marker.dataset.mkStepperMarker = ''; marker.setAttribute('aria-hidden', 'true');
+    const copy = document.createElement('span'); copy.dataset.mkStepperCopy = '';
+    const title = document.createElement('span'); title.dataset.mkStepperLabel = ''; title.textContent = item.label; copy.append(title);
+    if (item.description) { const description = document.createElement('span'); description.dataset.mkStepperDescription = ''; description.textContent = item.description; copy.append(description); }
+    button.append(marker, copy); row.append(button); list.append(row); buttons.push(button); rows.push(row); marks.push(marker);
+    scope.on(button, 'click', () => { if (!button.disabled && !button.matches(':disabled')) choose(index, true); });
+  });
+  const hidden = options.name ? document.createElement('input') : null;
+  if (hidden) { hidden.type = 'hidden'; hidden.name = options.name!; hidden.disabled = Boolean(options.disabled); nav.append(hidden); }
+  scope.attr(root, 'data-mk-ready', ''); scope.attr(root, 'data-mk-variant', options.variant ?? 'horizontal');
+  scope.attr(root, 'data-mk-disabled', options.disabled ? '' : null);
+  const paint = (animate: boolean, before: number) => {
+    const nextEnabled = items.findIndex((item, index) => index > furthest && !item.disabled);
+    const availableThrough = Math.max(furthest, nextEnabled);
+    items.forEach((item, index) => {
+      const selected = index === value; const complete = item.completed || index < value;
+      rows[index]!.toggleAttribute('data-mk-current', selected);
+      rows[index]!.toggleAttribute('data-mk-complete', Boolean(complete));
+      rows[index]!.toggleAttribute('data-mk-error', Boolean(item.error));
+      const button = buttons[index]!;
+      button.disabled = Boolean(options.disabled || item.disabled || options.linear && index > availableThrough);
+      if (selected) button.setAttribute('aria-current', 'step'); else button.removeAttribute('aria-current');
+      button.setAttribute('aria-label', `${index + 1}. ${item.label}${item.error ? ', requiere atención' : complete ? ', completado' : ''}`);
+      marks[index]!.textContent = item.error ? '!' : complete ? '✓' : String(index + 1);
+    });
+    if (hidden) hidden.value = String(value);
+    const text = items.length ? `${value + 1} / ${items.length} · ${items[value]?.label ?? ''}` : 'No hay pasos';
+    if (animate && !reduced()) keep(rollDigits(caption, text, value >= before ? 1 : -1, 0.3)); else caption.textContent = text;
+  };
+  const choose = (next: number, notify = false) => {
+    if (scope.disposed) return;
+    if (notify) pending = { value, furthest };
+    const before = value; value = clamp(next); furthest = Math.max(furthest, value); paint(before !== value, before);
+    if (before === value) return;
+    if (!reduced() && buttons[value]) {
+      keep(press(buttons[value]));
+      keep(gsap.fromTo(marks[value]!, { scale: 0.7, filter: 'blur(4px)' }, { scale: 1, filter: 'blur(0px)', duration: 0.4, ease: EASE.pop, overwrite: 'auto', clearProps: 'transform,filter' }));
+    }
+    if (notify) { const emitted = value; options.onChange?.(emitted); if (!scope.disposed) root.dispatchEvent(new CustomEvent('mk:change', { bubbles: true, detail: { value: emitted } })); }
+  };
+  const move = (direction: number, notify = true) => {
+    if (options.disabled) return;
+    for (let i = value + direction; i >= 0 && i < items.length; i += direction) if (!items[i]?.disabled) { choose(i, notify); break; }
+  };
+  const form = root.closest('form');
+  if (form) scope.on(form, 'reset', (event) => scope.timeout(() => { if (!scope.disposed && !event.defaultPrevented) { furthest = initial; choose(initial); } }, 0));
+  paint(false, value); keep(blurIn(rows, { from: 'soft', stagger: 0.04, duration: 0.35 }));
+  return {
+    get value() { return value; },
+    setValue(next, notify = false) {
+      const target = clamp(next);
+      // A consumer can veto a notified navigation by restoring its prior value.
+      // Roll the visit history back with it, before unlocking any later step.
+      if (!notify && pending && target === pending.value) furthest = pending.furthest;
+      pending = null;
+      choose(target, notify);
+    },
+    next: (notify = true) => move(1, notify), previous: (notify = true) => move(-1, notify),
+    reset: (notify = false) => { pending = null; furthest = initial; choose(initial, notify); }, destroy: () => scope.dispose(),
+  };
+}

package/src/components/stepper/react.tsx

@@ -0,0 +1,60 @@
+'use client';
+import { useRef, type HTMLAttributes, type MutableRefObject } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createStepper, type StepperOptions, type StepperInstance } from './engine';
+
+export interface StepperProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'onInput' | 'defaultValue' | 'children' | 'dangerouslySetInnerHTML'>, Omit<StepperOptions, 'value' | 'defaultValue'> {
+  value?: number;
+  defaultValue?: number;
+  instanceRef?: MutableRefObject<StepperInstance | null>;
+  /** The engine owns this component's DOM. */
+  children?: never;
+  dangerouslySetInnerHTML?: never;
+}
+export function Stepper({ value, defaultValue, items, label, name, variant, linear, disabled, onChange, instanceRef, className, children: _children, dangerouslySetInnerHTML: _html, ...props }: StepperProps) {
+  const root = useRef<HTMLDivElement>(null);
+  const engine = useRef<StepperInstance | null>(null);
+  const latestValue = useLatest(value);
+  const change = useLatest(onChange);
+  
+  const baseline = useRef(value !== undefined ? value : defaultValue);
+  const current = useRef(baseline.current);
+  const reconcile = () => queueMicrotask(() => {
+    if (latestValue.current !== undefined) engine.current?.setValue(latestValue.current, false);
+  });
+  useIsomorphicLayoutEffect(() => {
+    const created = createStepper(root.current, {
+      items, label, name, variant, linear, disabled, value: latestValue.current !== undefined ? latestValue.current : current.current, defaultValue: baseline.current,
+      onChange: (next) => { change.current?.(next); reconcile(); },
+      
+    });
+    engine.current = created;
+    const form = root.current?.closest('form');
+    const pending = new Set<ReturnType<typeof setTimeout>>();
+    const reset = (event: Event) => {
+      const timer = setTimeout(() => {
+        pending.delete(timer);
+        if (!event.defaultPrevented && latestValue.current !== undefined) created.setValue(latestValue.current, false);
+      }, 0);
+      pending.add(timer);
+    };
+    form?.addEventListener('reset', reset);
+    return () => {
+      form?.removeEventListener('reset', reset);
+      pending.forEach((timer) => clearTimeout(timer));
+      current.current = created.value; created.destroy(); engine.current = null;
+    };
+    // Callbacks and controlled value are read through refs.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [items, label, name, variant, linear, disabled]);
+  useIsomorphicLayoutEffect(() => {
+    if (value !== undefined) engine.current?.setValue(value, false);
+  });
+  useIsomorphicLayoutEffect(() => {
+    if (!instanceRef) return;
+    instanceRef.current = engine.current;
+    return () => { instanceRef.current = null; };
+  }, [instanceRef, items, label, name, variant, linear, disabled]);
+  return <div {...props} ref={root} className={['mk-stepper', className].filter(Boolean).join(' ')} />;
+}
+

package/src/components/stepper/stepper.css

@@ -0,0 +1,35 @@
+:is(.mk-stepper, mk-stepper) { display: block; min-width: 0; color: var(--mk-text); font: 500 .875rem/1.35 var(--mk-font); }
+[data-mk-stepper-body] { display: grid; gap: 1rem; }
+[data-mk-stepper-list] { display: flex; align-items: stretch; gap: .5rem; list-style: none; margin: 0; padding: 0; }
+[data-mk-stepper-item] { position: relative; flex: 1; min-width: 0; }
+[data-mk-stepper-step] { position: relative; display: flex; flex-direction: column; align-items: flex-start; gap: .75rem; width: 100%; min-height: 44px; padding: .75rem; border: 0; border-radius: 16px; background: transparent; color: var(--mk-muted); font: inherit; text-align: start; cursor: pointer; transition: background .25s, border-radius .4s var(--mk-ease-swatch), color .2s; -webkit-tap-highlight-color: transparent; }
+[data-mk-stepper-marker] { display: grid; place-items: center; flex: none; box-sizing: border-box; width: 36px; height: 36px; border-radius: 12px; background: var(--mk-surface-2); color: var(--mk-muted); font-size: .8125rem; transition: background .25s, color .25s, width .4s var(--mk-ease-swatch), border-radius .4s var(--mk-ease-swatch); }
+[data-mk-stepper-copy] { display: grid; gap: .25rem; min-width: 0; }
+[data-mk-stepper-description] { font-size: .75rem; color: var(--mk-muted); font-weight: 400; }
+[data-mk-stepper-item][data-mk-current] [data-mk-stepper-step] { background: var(--mk-surface-2); color: var(--mk-text); border-radius: 24px; }
+[data-mk-stepper-item][data-mk-current] [data-mk-stepper-marker] { background: var(--mk-text); color: var(--mk-bg); border-radius: 64px; }
+[data-mk-stepper-item][data-mk-complete] [data-mk-stepper-marker] { background: var(--mk-surface-3); color: var(--mk-text); border-radius: 64px; }
+[data-mk-stepper-item][data-mk-error] [data-mk-stepper-marker] { background: var(--mk-error-soft); color: var(--mk-error); }
+[data-mk-stepper-step]:focus-visible { outline: 2px solid var(--mk-accent); outline-offset: 3px; }
+[data-mk-stepper-step]:disabled { opacity: .4; cursor: not-allowed; }
+[data-mk-stepper-caption] { min-height: 1.3em; color: var(--mk-muted); font-size: .75rem; text-align: center; font-variant-numeric: tabular-nums; }
+:is(.mk-stepper, mk-stepper)[data-mk-variant='vertical'] [data-mk-stepper-list] { flex-direction: column; gap: .375rem; }
+:is(.mk-stepper, mk-stepper)[data-mk-variant='vertical'] [data-mk-stepper-step] { flex-direction: row; align-items: center; }
+:is(.mk-stepper, mk-stepper)[data-mk-variant='vertical'] [data-mk-stepper-caption] { text-align: start; padding-inline: .75rem; }
+:is(.mk-stepper, mk-stepper)[data-mk-variant='compact'] [data-mk-stepper-step] { flex-direction: row; align-items: center; padding: .375rem; border-radius: 64px; }
+:is(.mk-stepper, mk-stepper)[data-mk-variant='compact'] [data-mk-stepper-item] { flex: 0 1 auto; }
+:is(.mk-stepper, mk-stepper)[data-mk-variant='compact'] [data-mk-stepper-item][data-mk-current] { flex: 1; }
+:is(.mk-stepper, mk-stepper)[data-mk-variant='compact'] [data-mk-stepper-marker] { border-radius: 64px; }
+:is(.mk-stepper, mk-stepper)[data-mk-variant='compact'] [data-mk-stepper-copy] { display: none; }
+:is(.mk-stepper, mk-stepper)[data-mk-variant='compact'] [data-mk-current] [data-mk-stepper-copy] { display: grid; padding-inline-end: .75rem; }
+:is(.mk-stepper, mk-stepper)[data-mk-variant='compact'] [data-mk-stepper-description] { display: none; }
+:is(.mk-stepper, mk-stepper)[data-mk-variant='dots'] [data-mk-stepper-list] { justify-content: center; gap: .25rem; }
+:is(.mk-stepper, mk-stepper)[data-mk-variant='dots'] [data-mk-stepper-item] { flex: none; }
+:is(.mk-stepper, mk-stepper)[data-mk-variant='dots'] [data-mk-stepper-step] { width: 44px; height: 44px; padding: 0; display: grid; place-items: center; background: transparent; }
+:is(.mk-stepper, mk-stepper)[data-mk-variant='dots'] [data-mk-stepper-marker] { width: 8px; height: 8px; border-radius: 64px; font-size: 0; }
+:is(.mk-stepper, mk-stepper)[data-mk-variant='dots'] [data-mk-current] [data-mk-stepper-marker] { width: 28px; }
+:is(.mk-stepper, mk-stepper)[data-mk-variant='dots'] [data-mk-stepper-copy] { display: none; }
+@media (hover: hover) { [data-mk-stepper-step]:not(:disabled):hover { background: var(--mk-surface-2); border-radius: 24px; color: var(--mk-text); } }
+@media (max-width: 420px) { :is(.mk-stepper, mk-stepper)[data-mk-variant='horizontal'] [data-mk-stepper-step] { padding: .5rem; font-size: .75rem; } :is(.mk-stepper, mk-stepper)[data-mk-variant='horizontal'] [data-mk-stepper-description] { display: none; } }
+@media (prefers-reduced-motion: reduce) { [data-mk-stepper-step], [data-mk-stepper-marker] { transition: none; } }
+@media (forced-colors: active) { [data-mk-current] [data-mk-stepper-marker] { outline: 2px solid Highlight; } }

package/src/components/sticky-header/README.md

@@ -0,0 +1,30 @@
+# Sticky header
+
+An authored sticky surface continuously compacts inside a stable expanded-height slot. The reserved slot prevents content from jumping when its geometry changes.
+
+```html
+<div id="scroller" style="height:320px;overflow:auto">
+  <header id="header">
+    <div data-mk-sticky-surface>
+      <div><h2 data-mk-sticky-title>Mi espacio</h2><p data-mk-sticky-subtitle>Todo lo que estás creando.</p></div>
+      <button type="button">Nuevo</button>
+    </div>
+  </header>
+  …content…
+</div>
+```
+
+```ts
+const header = createStickyHeader(document.querySelector('#header'), {
+  scroller: document.querySelector('#scroller'), expandedHeight: 104, compactHeight: 64,
+});
+header.destroy();
+```
+
+Exports: `createStickyHeader`, `StickyHeaderOptions`, `StickyHeaderInstance`; React `StickyHeader`, `StickyHeaderProps`; elements `MkStickyHeaderElement`, `defineStickyHeader` (`mk-sticky-header`). CSS: `sticky-header.css` plus kit tokens/theme/fonts.
+
+Options: `scroller` (element/selector, otherwise window), `expandedHeight` (104px), `compactHeight` (64px), `threshold` (8px), `range` (96px of scroll), `top` (sticky inset, 0px), `disabled` (holds expanded geometry; native child controls remain usable), `onChange(compact)`. Geometry follows scroll progress through the supplied range; `compact` changes at half range. The title shrinks and subtitle folds into a blur as radius, padding, height and tonal surface change.
+
+Instance: `update()`, `setOptions(partial)`, readonly `compact`/`progress`, `destroy()`. `mk:change` carries `{compact,progress}` at compact-state crossings. Native links/buttons and focus order stay authored. Reduced motion applies geometry immediately. Destroy restores exact authored styles/attributes and removes listeners, animation frames, observers and animations.
+
+React intentionally accepts children and renders the required surface wrapper; mark title/subtitle parts inside them. In Vanilla/elements, author `[data-mk-sticky-surface]` explicitly. The element accepts scalar option attributes and exposes `setOptions`, `update`, `compact` and `progress`; changing attributes preserves its instance.

package/src/components/sticky-header/element.ts

@@ -0,0 +1,19 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createStickyHeader, type StickyHeaderInstance, type StickyHeaderOptions } from './engine';
+
+export class MkStickyHeaderElement extends MkElement<StickyHeaderInstance> {
+  static options: Record<string, OptionType> = {"scroller":"string","expandedHeight":"number","compactHeight":"number","threshold":"number","range":"number","top":"number","disabled":"boolean"};
+  protected create(options: Record<string, unknown>) { return createStickyHeader(this, options); }
+  setOptions(options: Partial<StickyHeaderOptions>) { this.instance?.setOptions(options); }
+
+  update() { this.instance?.update(); }
+  get compact() { return this.instance?.compact ?? false; }
+  get progress() { return this.instance?.progress ?? 0; }
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.isConnected || !this.instance) return;
+    const option = name.replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase());
+    const defaults: Record<string, unknown> = {"scroller":null,"expandedHeight":104,"compactHeight":64,"threshold":8,"range":96,"top":0,"disabled":false};
+    this.instance.setOptions({ [option]: this.options[option] ?? defaults[option] });
+  }
+}
+export const defineStickyHeader = () => defineElement('mk-sticky-header', MkStickyHeaderElement);