@yewdiel21/motion-kit 0.17.0 → 0.19.0

package/src/components/scroll-area/scroll-area.css

@@ -0,0 +1,260 @@
+/* scroll-area — the scroller keeps native scrolling with its system bar hidden; the kit's bars ride on top: a 6 px pill
+   (text at 32 %) that shows while hovered or scrolling, swells to 10 px over a tonal rail on the swing curve and turns the
+   accent while dragged. Edges with more content fade out; an optional tonal pill takes the view back to the top. */
+@property --mk-scroll-thickness {
+  syntax: '<length>';
+  inherits: true;
+  initial-value: 6px;
+}
+
+.mk-scroll-area,
+mk-scroll-area {
+  --mk-scroll-thumb: color-mix(in srgb, var(--mk-text) 32%, transparent);
+  --mk-scroll-thumb-hover: color-mix(in srgb, var(--mk-text) 48%, transparent);
+  --mk-scroll-rail: color-mix(in srgb, var(--mk-text) 6%, transparent);
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  min-height: 0;
+  overflow: hidden;
+}
+
+/* Its own viewport fills the area (a height or a max-height on the area both work). */
+:is(.mk-scroll-area, mk-scroll-area) > [data-mk-scroll-viewport] {
+  flex: 1 1 auto;
+  min-width: 0;
+  min-height: 0;
+  overflow: auto;
+  overscroll-behavior: contain;
+  border-radius: inherit;
+  outline: none;
+}
+
+:is(.mk-scroll-area, mk-scroll-area)[data-mk-scroll-axis='y'] > [data-mk-scroll-viewport] {
+  overflow-x: hidden;
+}
+
+:is(.mk-scroll-area, mk-scroll-area)[data-mk-scroll-axis='x'] > [data-mk-scroll-viewport] {
+  overflow-y: hidden;
+}
+
+[data-mk-scroll-anchor] {
+  position: relative;
+}
+
+/* The kit's bars replace the system's wherever the scroller's own styles asked for a thin one. */
+[data-mk-scroll-viewport] {
+  scrollbar-width: none !important;
+}
+
+[data-mk-scroll-viewport]::-webkit-scrollbar {
+  display: none !important;
+}
+
+[data-mk-scroll-area]:has(> [data-mk-scroll-viewport]:focus-visible) {
+  outline: 2px solid var(--mk-accent);
+  outline-offset: 2px;
+}
+
+/* Edge fades: as deep as what is hidden past each edge, up to 24 px (written by the engine). */
+[data-mk-fade] > [data-mk-scroll-viewport] {
+  --mk-scroll-fade-top: 0px;
+  --mk-scroll-fade-right: 0px;
+  --mk-scroll-fade-bottom: 0px;
+  --mk-scroll-fade-left: 0px;
+  -webkit-mask-image:
+    linear-gradient(to bottom, transparent, #000 var(--mk-scroll-fade-top), #000 calc(100% - var(--mk-scroll-fade-bottom)), transparent),
+    linear-gradient(to right, transparent, #000 var(--mk-scroll-fade-left), #000 calc(100% - var(--mk-scroll-fade-right)), transparent);
+  -webkit-mask-composite: source-in;
+  mask-image:
+    linear-gradient(to bottom, transparent, #000 var(--mk-scroll-fade-top), #000 calc(100% - var(--mk-scroll-fade-bottom)), transparent),
+    linear-gradient(to right, transparent, #000 var(--mk-scroll-fade-left), #000 calc(100% - var(--mk-scroll-fade-right)), transparent);
+  mask-composite: intersect;
+}
+
+/* Rails: a 14 px grip along the edge; its tonal rail and the pill inside are drawn smaller. */
+[data-mk-scroll-rail] {
+  --mk-scroll-thickness: 6px;
+  position: absolute;
+  z-index: 2;
+  opacity: 0;
+  touch-action: none;
+  -webkit-user-select: none;
+  user-select: none;
+  transition:
+    opacity 0.2s ease,
+    --mk-scroll-thickness 0.35s var(--mk-ease-swatch);
+}
+
+[data-mk-scroll-rail][hidden] {
+  display: none;
+}
+
+/* The rails run along the viewport's box inside the root (--mk-scroll-view-*, written by the engine);
+   --mk-scroll-inset keeps their ends clear of rounded corners. */
+[data-mk-scroll-rail][data-mk-axis='y'] {
+  top: calc(var(--mk-scroll-view-top, 0px) + var(--mk-scroll-inset, 6px));
+  right: var(--mk-scroll-view-right, 0px);
+  bottom: calc(var(--mk-scroll-view-bottom, 0px) + var(--mk-scroll-inset, 6px));
+  width: 14px;
+}
+
+[data-mk-scroll-rail][data-mk-axis='x'] {
+  right: calc(var(--mk-scroll-view-right, 0px) + var(--mk-scroll-inset, 6px));
+  bottom: var(--mk-scroll-view-bottom, 0px);
+  left: calc(var(--mk-scroll-view-left, 0px) + var(--mk-scroll-inset, 6px));
+  height: 14px;
+}
+
+/* Both bars: each stops short of the other, no corner square. */
+[data-mk-overflow-x] > [data-mk-scroll-rail][data-mk-axis='y'] {
+  bottom: calc(var(--mk-scroll-view-bottom, 0px) + 14px);
+}
+
+[data-mk-overflow-y] > [data-mk-scroll-rail][data-mk-axis='x'] {
+  right: calc(var(--mk-scroll-view-right, 0px) + 14px);
+}
+
+[data-mk-active] > [data-mk-scroll-rail],
+[data-mk-scroll-rail]:hover,
+[data-mk-scroll-rail][data-mk-dragging] {
+  opacity: 1;
+}
+
+[data-mk-scroll-rail]:hover,
+[data-mk-scroll-rail][data-mk-dragging] {
+  --mk-scroll-thickness: 10px;
+}
+
+[data-mk-scroll-rail]::before {
+  content: '';
+  position: absolute;
+  border-radius: 999px;
+  background: var(--mk-scroll-rail, color-mix(in srgb, var(--mk-text) 6%, transparent));
+  opacity: 0;
+  transition: opacity 0.2s ease;
+}
+
+[data-mk-scroll-rail][data-mk-axis='y']::before {
+  top: 0;
+  right: 2px;
+  bottom: 0;
+  width: 10px;
+}
+
+[data-mk-scroll-rail][data-mk-axis='x']::before {
+  right: 0;
+  bottom: 2px;
+  left: 0;
+  height: 10px;
+}
+
+[data-mk-scroll-rail]:hover::before,
+[data-mk-scroll-rail][data-mk-dragging]::before {
+  opacity: 1;
+}
+
+[data-mk-scroll-thumb] {
+  position: absolute;
+  top: 0;
+  left: 0;
+  cursor: grab;
+  will-change: transform;
+}
+
+[data-mk-scroll-rail][data-mk-axis='y'] [data-mk-scroll-thumb] {
+  width: 100%;
+}
+
+[data-mk-scroll-rail][data-mk-axis='x'] [data-mk-scroll-thumb] {
+  height: 100%;
+}
+
+[data-mk-scroll-rail][data-mk-dragging] [data-mk-scroll-thumb] {
+  cursor: grabbing;
+}
+
+/* The pill stays centred on the 10 px rail while it swells. */
+[data-mk-scroll-pill] {
+  position: absolute;
+  border-radius: 999px;
+  background: var(--mk-scroll-thumb, color-mix(in srgb, var(--mk-text) 32%, transparent));
+  transition: background-color 0.2s ease;
+}
+
+[data-mk-scroll-rail][data-mk-axis='y'] [data-mk-scroll-pill] {
+  top: 0;
+  right: calc(2px + (10px - var(--mk-scroll-thickness)) / 2);
+  bottom: 0;
+  width: var(--mk-scroll-thickness);
+}
+
+[data-mk-scroll-rail][data-mk-axis='x'] [data-mk-scroll-pill] {
+  right: 0;
+  bottom: calc(2px + (10px - var(--mk-scroll-thickness)) / 2);
+  left: 0;
+  height: var(--mk-scroll-thickness);
+}
+
+[data-mk-scroll-rail]:hover [data-mk-scroll-pill] {
+  background: var(--mk-scroll-thumb-hover, color-mix(in srgb, var(--mk-text) 48%, transparent));
+}
+
+[data-mk-scroll-rail][data-mk-dragging] [data-mk-scroll-pill] {
+  background: var(--mk-scroll-thumb-active, var(--mk-accent));
+}
+
+[data-mk-dragging] [data-mk-scroll-viewport] {
+  -webkit-user-select: none;
+  user-select: none;
+}
+
+/* Back to top: a tonal pill in the corner, clear of the bars. */
+[data-mk-scroll-top] {
+  position: absolute;
+  z-index: 3;
+  right: calc(var(--mk-scroll-view-right, 0px) + 20px);
+  bottom: calc(var(--mk-scroll-view-bottom, 0px) + 16px);
+  display: inline-grid;
+  place-items: center;
+  width: 40px;
+  height: 40px;
+  padding: 0;
+  border: 0;
+  border-radius: 999px;
+  background: var(--mk-surface-4);
+  box-shadow: 0 8px 24px -8px color-mix(in srgb, var(--mk-shadow-color, #000) 45%, transparent);
+  color: var(--mk-text);
+  cursor: pointer;
+  transition:
+    background-color 0.15s,
+    box-shadow 0.2s;
+}
+
+[data-mk-overflow-x] > [data-mk-scroll-top] {
+  bottom: calc(var(--mk-scroll-view-bottom, 0px) + 22px);
+}
+
+[data-mk-scroll-top][hidden] {
+  display: none;
+}
+
+[data-mk-scroll-top]:hover {
+  background: color-mix(in srgb, var(--mk-surface-4) 80%, var(--mk-text) 10%);
+}
+
+[data-mk-scroll-top]:focus-visible {
+  outline: none;
+  box-shadow:
+    0 0 0 3px color-mix(in srgb, var(--mk-accent) 45%, transparent),
+    0 8px 24px -8px color-mix(in srgb, var(--mk-shadow-color, #000) 45%, transparent);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-mk-scroll-rail],
+  [data-mk-scroll-rail]::before,
+  [data-mk-scroll-pill],
+  [data-mk-scroll-top] {
+    transition: none;
+  }
+}

package/src/components/scroll-preview-dock/README.md

@@ -0,0 +1,24 @@
+# Scroll preview dock
+
+Section links with thumbnails, a travelling selected pill and an adjacent hover/focus preview. Selection follows the actual scroll position in the supplied scroller.
+
+```ts
+const dock = createScrollPreviewDock(document.querySelector('#dock'), {
+  scroller: document.querySelector('#story'),
+  offset: 12,
+  items: [
+    { id: 'idea', label: 'La idea', description: 'Un punto de partida', thumbnail: '/idea.webp' },
+    { id: 'shape', label: 'La forma', thumbnail: '/shape.webp' },
+  ],
+});
+dock.select('shape');
+dock.destroy();
+```
+
+Exports: `createScrollPreviewDock`, `ScrollPreviewDockItem`, `ScrollPreviewDockOptions`, `ScrollPreviewDockInstance`; React `ScrollPreviewDock`, `ScrollPreviewDockProps`; elements `MkScrollPreviewDockElement`, `defineScrollPreviewDock` (`mk-scroll-preview-dock`). CSS: `scroll-preview-dock.css` plus kit tokens/theme/fonts.
+
+Options: `items`, `scroller` (element/selector, otherwise window), `offset` (pixels), `label`, `disabled`, `onChange(id)`. Each item has `id`, `label`, optional `description`, `thumbnail`, `section` (element/selector, defaults to the element with that ID), `disabled`. Give each target section a real `id` to preserve native fragment-link behavior. Missing sections leave a working native link and do not initiate scripted scrolling.
+
+Instance: `select(id)`, `update()`, `setOptions(partial)`, readonly `value`, `destroy()`. `mk:change` emits `{value}` for the tracked section. Hover/focus changes only the preview. ArrowLeft/ArrowRight and Home/End move focus among enabled links; normal Tab/Enter and modified link clicks retain native semantics. Wheel/touch interrupts scripted scrolling. Reduced motion jumps immediately.
+
+React owns an empty host and accepts data through `items`, with optional `instanceRef`; children/HTML are ignored at runtime. An element accepts JSON `items`, scalar attributes and `setOptions`, `items`, `select`/`update` methods. Updates retain the engine and restore focus to a surviving link. Destroy removes listeners, pending animation frames and scroll tweens, restoring authored content.

package/src/components/scroll-preview-dock/element.ts

@@ -0,0 +1,20 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createScrollPreviewDock, type ScrollPreviewDockInstance, type ScrollPreviewDockOptions, type ScrollPreviewDockItem } from './engine';
+
+export class MkScrollPreviewDockElement extends MkElement<ScrollPreviewDockInstance> {
+  static options: Record<string, OptionType> = {"items":"json","scroller":"string","offset":"number","label":"string","disabled":"boolean"};
+  protected create(options: Record<string, unknown>) { return createScrollPreviewDock(this, options); }
+  setOptions(options: Partial<ScrollPreviewDockOptions>) { this.instance?.setOptions(options); }
+
+  select(id: string) { this.instance?.select(id); }
+  update() { this.instance?.update(); }
+  get value() { return this.instance?.value ?? ''; }
+  set items(value: ScrollPreviewDockItem[]) { this.instance?.setOptions({ items: value }); }
+  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> = {"items":[],"scroller":null,"offset":0,"label":"Explorar secciones","disabled":false};
+    this.instance.setOptions({ [option]: this.options[option] ?? defaults[option] });
+  }
+}
+export const defineScrollPreviewDock = () => defineElement('mk-scroll-preview-dock', MkScrollPreviewDockElement);

package/src/components/scroll-preview-dock/engine.ts

@@ -0,0 +1,228 @@
+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 } from '../../motion/micro';
+
+export interface ScrollPreviewDockItem {
+  id: string;
+  label: string;
+  description?: string;
+  thumbnail?: string;
+  /** A section element or selector. Defaults to the element with this item's id. */
+  section?: HTMLElement | string;
+  disabled?: boolean;
+}
+export interface ScrollPreviewDockOptions {
+  items?: ScrollPreviewDockItem[];
+  scroller?: HTMLElement | string | null;
+  offset?: number;
+  label?: string;
+  disabled?: boolean;
+  onChange?: (id: string) => void;
+}
+export interface ScrollPreviewDockInstance extends Instance {
+  select(id: string): void;
+  update(): void;
+  setOptions(options: Partial<ScrollPreviewDockOptions>): void;
+  readonly value: string;
+}
+
+/** Native section links, a travelling selection pill, and a focus/hover preview. */
+export function createScrollPreviewDock(root: HTMLElement | null, options: ScrollPreviewDockOptions = {}): ScrollPreviewDockInstance {
+  if (!root) return inert({ select() {}, update() {}, setOptions() {}, value: '' });
+  registerMotion();
+  const scope = createScope();
+  let opts = { ...options };
+  let current = '';
+  let previewed = '';
+  let frame = 0;
+  let scrolling: gsap.core.Tween | null = null;
+  let unbindScroller = () => {};
+  let scroller: HTMLElement | null = null;
+  const original = [...root.childNodes];
+  const animations = new Set<gsap.core.Animation>();
+  const track = (animation: gsap.core.Animation | null) => { if (animation) animations.add(animation); };
+  const panel = document.createElement('div');
+  panel.className = 'mk-scroll-preview-dock__preview';
+  panel.setAttribute('aria-hidden', 'true');
+  const image = document.createElement('span');
+  image.className = 'mk-scroll-preview-dock__image';
+  const copy = document.createElement('span');
+  const title = document.createElement('strong');
+  const description = document.createElement('span');
+  description.className = 'mk-scroll-preview-dock__description';
+  copy.append(title, description);
+  panel.append(image, copy);
+  const nav = document.createElement('nav');
+  nav.className = 'mk-scroll-preview-dock__nav';
+  const pill = document.createElement('span');
+  pill.className = 'mk-scroll-preview-dock__pill';
+  pill.setAttribute('aria-hidden', 'true');
+  const empty = document.createElement('p');
+  empty.className = 'mk-scroll-preview-dock__empty';
+  empty.textContent = 'No hay secciones para explorar.';
+  root.replaceChildren(panel, nav, empty);
+  scope.attr(root, 'class', `${root.className} mk-scroll-preview-dock`.trim());
+  scope.attr(root, 'data-mk-ready', '');
+  const items = () => opts.items ?? [];
+  const enabled = (item: ScrollPreviewDockItem) => !opts.disabled && !item.disabled;
+  const section = (item: ScrollPreviewDockItem) => {
+    if (item.section instanceof HTMLElement) return item.section;
+    if (!item.section) return document.getElementById(item.id);
+    try { return (scroller ?? document).querySelector<HTMLElement>(item.section); } catch { return null; }
+  };
+  const links = () => [...nav.querySelectorAll<HTMLAnchorElement>('a')];
+  const thumb = (node: HTMLElement, item: ScrollPreviewDockItem) => {
+    node.replaceChildren();
+    if (item.thumbnail) { const img = document.createElement('img'); img.src = item.thumbnail; img.alt = ''; img.draggable = false; node.append(img); }
+    else { const letter = document.createElement('span'); letter.textContent = item.label.slice(0, 2); node.append(letter); }
+  };
+  const preview = (id: string, animate = true) => {
+    const item = items().find((item) => item.id === id);
+    if (!item || previewed === id) return;
+    previewed = id;
+    thumb(image, item);
+    title.textContent = item.label;
+    description.textContent = item.description ?? 'Explorar sección';
+    for (const link of links()) link.dataset.mkPreview = String(link.dataset.mkSection === id);
+    if (animate) { gsap.killTweensOf(panel); track(blurIn(panel, { from: 'soft', duration: .28 })); }
+  };
+  const place = (animate = true) => {
+    const active = links().find((link) => link.dataset.mkSection === current);
+    pill.hidden = !active;
+    if (!active) return;
+    track(gsap.to(pill, { x: active.offsetLeft, y: active.offsetTop, width: active.offsetWidth, height: active.offsetHeight, duration: reduced() || !animate ? 0 : .45, ease: EASE.swatch, overwrite: 'auto' }));
+  };
+  const activate = (id: string, notify = true) => {
+    if (scope.disposed || current === id) return;
+    current = id;
+    for (const link of links()) {
+      if (link.dataset.mkSection === id) link.setAttribute('aria-current', 'location');
+      else link.removeAttribute('aria-current');
+    }
+    place();
+    if (!root.contains(document.activeElement) && !root.matches(':hover')) preview(id);
+    else if (!previewed) preview(id, false);
+    if (notify) {
+      opts.onChange?.(id);
+      root.dispatchEvent(new CustomEvent('mk:change', { bubbles: true, detail: { value: id } }));
+    }
+  };
+  const update = () => {
+    frame = 0;
+    if (scope.disposed) return;
+    const top = scroller ? scroller.getBoundingClientRect().top + scroller.clientTop : 0;
+    const height = scroller ? scroller.clientHeight : window.innerHeight;
+    const line = top + Math.min(120, height * .3) + (opts.offset ?? 0);
+    const targets = items().filter(enabled).map((item) => ({ item, node: section(item) })).filter((entry): entry is { item: ScrollPreviewDockItem; node: HTMLElement } => !!entry.node);
+    let target: (typeof targets)[number] | undefined = targets[0];
+    for (const entry of targets) if (entry.node.getBoundingClientRect().top <= line) target = entry;
+    const atEnd = scroller ? scroller.scrollHeight > scroller.clientHeight && scroller.scrollTop + scroller.clientHeight >= scroller.scrollHeight - 2 : document.documentElement.scrollHeight > window.innerHeight && window.scrollY + window.innerHeight >= document.documentElement.scrollHeight - 2;
+    if (atEnd) target = targets.at(-1);
+    if (target) activate(target.item.id);
+    place(false);
+  };
+  const queue = () => { if (!frame) frame = requestAnimationFrame(update); };
+  const bindScroller = () => {
+    unbindScroller();
+    scroller = typeof opts.scroller === 'string' ? (() => { try { return root.closest<HTMLElement>(opts.scroller) ?? document.querySelector<HTMLElement>(opts.scroller); } catch { return null; } })() : opts.scroller ?? null;
+    const target = scroller ?? window;
+    target.addEventListener('scroll', queue, { passive: true });
+    target.addEventListener('wheel', cancelScroll, { passive: true });
+    target.addEventListener('touchstart', cancelScroll, { passive: true });
+    unbindScroller = () => { target.removeEventListener('scroll', queue); target.removeEventListener('wheel', cancelScroll); target.removeEventListener('touchstart', cancelScroll); };
+  };
+  function cancelScroll() { scrolling?.kill(); scrolling = null; }
+  const select = (id: string) => {
+    if (scope.disposed) return;
+    const item = items().find((entry) => entry.id === id);
+    if (!item || !enabled(item)) return;
+    const target = section(item);
+    if (!target) return;
+    cancelScroll();
+    const top = Math.max(0, (scroller ? scroller.scrollTop + target.getBoundingClientRect().top - scroller.getBoundingClientRect().top - scroller.clientTop : window.scrollY + target.getBoundingClientRect().top) - (opts.offset ?? 0));
+    activate(id);
+    preview(id);
+    if (scroller) {
+      if (reduced()) scroller.scrollTop = top;
+      else scrolling = gsap.to(scroller, { scrollTop: top, duration: .65, ease: EASE.signature, overwrite: 'auto', onUpdate: queue });
+    } else if (reduced()) window.scrollTo({ top, behavior: 'instant' });
+    else {
+      const position = { top: window.scrollY };
+      scrolling = gsap.to(position, { top, duration: .65, ease: EASE.signature, onUpdate: () => { window.scrollTo(0, position.top); queue(); } });
+    }
+  };
+  const render = () => {
+    gsap.killTweensOf(pill);
+    nav.replaceChildren(pill);
+    nav.setAttribute('aria-label', opts.label ?? 'Explorar secciones');
+    const unique = new Set<string>();
+    for (const item of items()) {
+      if (!item.id || unique.has(item.id)) continue;
+      unique.add(item.id);
+      const link = document.createElement('a');
+      link.href = `#${encodeURIComponent(section(item)?.id || item.id)}`;
+      link.dataset.mkSection = item.id;
+      link.className = 'mk-scroll-preview-dock__item';
+      const cover = document.createElement('span');
+      cover.className = 'mk-scroll-preview-dock__thumb';
+      cover.setAttribute('aria-hidden', 'true');
+      thumb(cover, item);
+      const label = document.createElement('span');
+      label.textContent = item.label;
+      link.append(cover, label);
+      if (!enabled(item)) { link.setAttribute('aria-disabled', 'true'); link.tabIndex = -1; }
+      nav.append(link);
+    }
+    empty.hidden = unique.size > 0;
+    panel.hidden = unique.size === 0;
+    nav.hidden = unique.size === 0;
+    scope.attr(root, 'data-mk-disabled', opts.disabled ? '' : null);
+    previewed = '';
+    const next = items().find((item) => item.id === current && enabled(item)) ?? items().find(enabled);
+    current = '';
+    if (next) { activate(next.id, false); preview(next.id, false); }
+    else pill.hidden = true;
+  };
+  scope.on(nav, 'click', (event) => {
+    const link = (event.target as Element).closest<HTMLAnchorElement>('a[data-mk-section]');
+    if (!link) return;
+    if (link.getAttribute('aria-disabled') === 'true') { event.preventDefault(); return; }
+    if (event.metaKey || event.ctrlKey || event.altKey || event.shiftKey || event.button !== 0) return;
+    const item = items().find((item) => item.id === link.dataset.mkSection);
+    if (!item || !section(item)) return;
+    event.preventDefault(); track(press(link)); select(item.id);
+  });
+  scope.on(nav, 'pointerover', (event) => { const link = (event.target as Element).closest<HTMLElement>('a[data-mk-section]'); if (link && link.getAttribute('aria-disabled') !== 'true') preview(link.dataset.mkSection!); });
+  scope.on(nav, 'focusin', (event) => { const link = (event.target as Element).closest<HTMLElement>('a[data-mk-section]'); if (link) preview(link.dataset.mkSection!); });
+  scope.on(root, 'pointerleave', () => { if (!root.contains(document.activeElement)) preview(current); });
+  scope.on(root, 'focusout', (event) => { if (!root.contains(event.relatedTarget as Node | null)) preview(current); });
+  scope.on(nav, 'keydown', (event) => {
+    if (!['ArrowLeft', 'ArrowRight', 'Home', 'End'].includes(event.key)) { if (['PageUp', 'PageDown', 'ArrowUp', 'ArrowDown', ' '].includes(event.key)) cancelScroll(); return; }
+    const available = links().filter((link) => link.getAttribute('aria-disabled') !== 'true');
+    const index = available.indexOf(document.activeElement as HTMLAnchorElement);
+    if (index < 0 || !available.length) return;
+    event.preventDefault();
+    available[event.key === 'Home' ? 0 : event.key === 'End' ? available.length - 1 : (index + (event.key === 'ArrowRight' ? 1 : -1) + available.length) % available.length]?.focus();
+  });
+  scope.on(window, 'resize', queue, { passive: true });
+  if (typeof ResizeObserver === 'function') { const resize = scope.observe(new ResizeObserver(queue)); resize.observe(nav); }
+  bindScroller(); render(); update();
+  return {
+    select, update,
+    get value() { return current; },
+    setOptions(next) {
+      if (scope.disposed) return;
+      const focusedId = root.contains(document.activeElement)
+        ? (document.activeElement as HTMLElement | null)?.closest<HTMLAnchorElement>('a[data-mk-section]')?.dataset.mkSection
+        : undefined;
+      opts = { ...opts, ...next };
+      if ('scroller' in next) { cancelScroll(); bindScroller(); }
+      render();
+      if (focusedId) { const target = links().find((link) => link.dataset.mkSection === focusedId && link.getAttribute('aria-disabled') !== 'true') ?? links().find((link) => link.getAttribute('aria-disabled') !== 'true'); if (target) target.focus(); else { scope.attr(root, 'tabindex', root.getAttribute('tabindex')); root.tabIndex = -1; root.focus(); } }
+      update();
+    },
+    destroy() { if (scope.disposed) return; cancelAnimationFrame(frame); cancelScroll(); unbindScroller(); animations.forEach((animation) => animation.kill()); gsap.killTweensOf([...root.querySelectorAll('*')]); scope.dispose(); root.replaceChildren(...original); },
+  };
+}

package/src/components/scroll-preview-dock/react.tsx

@@ -0,0 +1,26 @@
+'use client';
+import { useRef, type HTMLAttributes, type MutableRefObject } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createScrollPreviewDock, type ScrollPreviewDockOptions, type ScrollPreviewDockInstance } from './engine';
+
+export interface ScrollPreviewDockProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'children' | 'dangerouslySetInnerHTML'>, ScrollPreviewDockOptions {
+  instanceRef?: MutableRefObject<ScrollPreviewDockInstance | null>;
+  children?: never;
+  dangerouslySetInnerHTML?: never;
+}
+export function ScrollPreviewDock({ items, scroller, offset, label, disabled, onChange, instanceRef, className, children, dangerouslySetInnerHTML: _html, ...props }: ScrollPreviewDockProps) {
+  const root = useRef<HTMLDivElement>(null);
+  const instance = useRef<ScrollPreviewDockInstance | null>(null);
+  const onChangeRef = useLatest(onChange);
+  useIsomorphicLayoutEffect(() => {
+    const created = createScrollPreviewDock(root.current, { items, scroller, offset, label, disabled, onChange: (...args) => onChangeRef.current?.(...args) });
+    instance.current = created;
+    return () => { created.destroy(); instance.current = null; };
+    // Options update the existing engine so timers, selection and scroll state survive.
+  }, []);
+  useIsomorphicLayoutEffect(() => {
+    instance.current?.setOptions({ items, scroller, offset, label, disabled });
+  }, [items, scroller, offset, label, disabled]);
+  useIsomorphicLayoutEffect(() => { if (instanceRef) instanceRef.current = instance.current; return () => { if (instanceRef) instanceRef.current = null; }; }, [instanceRef]);
+  return <div {...props} ref={root} className={['mk-scroll-preview-dock', className].filter(Boolean).join(' ')}></div>;
+}

package/src/components/scroll-preview-dock/scroll-preview-dock.css

@@ -0,0 +1,17 @@
+.mk-scroll-preview-dock, mk-scroll-preview-dock { box-sizing: border-box; display: grid; gap: 10px; width: min(100%, 400px); color: var(--mk-text); font-family: var(--mk-font); }
+.mk-scroll-preview-dock__preview { display: flex; align-items: center; gap: 12px; min-height: 60px; box-sizing: border-box; padding: 12px 16px; border-radius: 24px; background: var(--mk-surface-2); box-shadow: 0 1px 0 var(--mk-outline-soft) inset; }
+.mk-scroll-preview-dock__image { display: grid; place-items: center; flex: 0 0 44px; width: 44px; height: 44px; border-radius: 12px; background: var(--mk-surface-3, var(--mk-surface)); overflow: hidden; font-weight: 600; font-size: 14px; }
+.mk-scroll-preview-dock__image img, .mk-scroll-preview-dock__thumb img { display: block; width: 100%; height: 100%; object-fit: cover; }
+.mk-scroll-preview-dock__preview strong { display: block; font-size: 13px; font-weight: 600; line-height: 1.4; }
+.mk-scroll-preview-dock__description { display: block; color: var(--mk-muted); font-size: 11px; line-height: 1.5; }
+.mk-scroll-preview-dock__nav { position: relative; box-sizing: border-box; display: flex; align-items: stretch; justify-content: space-between; gap: 4px; width: 100%; padding: 6px; border-radius: 32px; background: var(--mk-surface); }
+.mk-scroll-preview-dock__pill { position: absolute; top: 0; left: 0; border-radius: 24px; background: var(--mk-surface-3, var(--mk-surface-2)); pointer-events: none; box-shadow: 0 1px 0 var(--mk-outline-soft) inset; }
+.mk-scroll-preview-dock__item { position: relative; z-index: 1; display: flex; flex: 1 1 0; align-items: center; flex-direction: column; justify-content: center; gap: 6px; min-width: 0; min-height: 68px; padding: 6px; border-radius: 24px; text-align: center; color: var(--mk-muted); text-decoration: none; font-size: 10px; line-height: 1.3; -webkit-tap-highlight-color: transparent; transition: color .2s; }
+.mk-scroll-preview-dock__thumb { display: grid; place-items: center; width: 32px; height: 32px; border-radius: 12px; background: var(--mk-surface-2); overflow: hidden; color: var(--mk-text); font-size: 10px; font-weight: 600; transition: transform .4s var(--mk-ease-swatch), border-radius .4s var(--mk-ease-swatch); }
+.mk-scroll-preview-dock__item[aria-current] { color: var(--mk-text); }
+.mk-scroll-preview-dock__item[data-mk-preview=true] .mk-scroll-preview-dock__thumb { transform: translateY(-3px) rotate(-4deg) scale(1.08); border-radius: 8px; }
+.mk-scroll-preview-dock__item:focus-visible { outline: 2px solid var(--mk-accent); outline-offset: 2px; }
+.mk-scroll-preview-dock__item[aria-disabled=true] { opacity: .4; cursor: not-allowed; }
+.mk-scroll-preview-dock [hidden] { display: none !important; }
+.mk-scroll-preview-dock__empty { margin: 0; padding: 20px; text-align: center; background: var(--mk-surface); border-radius: 24px; font-size: 12px; color: var(--mk-muted); }
+@media (prefers-reduced-motion: reduce) { .mk-scroll-preview-dock * { transition: none !important; } }

package/src/components/select/README.md

@@ -1,34 +1,48 @@
 # select
 
-Qué hace, en una frase.
-
-Origen: archivo del kit y parámetros (tiempos, curvas).
+Una elección de una lista que se abre como el `menu` del kit (crece desde su botón y las opciones entran escalonadas) en lugar de la lista del sistema. Mejora un `<select>` escrito a mano, o crea uno desde `options`, y lo mantiene sincronizado y oculto: los formularios lo envían y sus escuchas de `change` siguen funcionando. El valor elegido entra con un blur breve y el chevron gira. Una lista larga se desplaza con la barra de [`scroll-area`](../scroll-area/README.md), no con la del sistema; respeta las esquinas redondeadas del menú y funde los bordes.
 
 ## HTML / Astro
 
 ```html
-<mk-select></mk-select>
+<mk-select class="mk-select" label="Responsable">
+  <select name="owner">
+    <option value="">Elige a alguien</option>
+    <optgroup label="Diseño"><option value="ana">Ana Gómez</option></optgroup>
+    <optgroup label="Código"><option value="leo">Leo Ruiz</option></optgroup>
+  </select>
+</mk-select>
 <script>
   import { defineElements } from '@yewdiel21/motion-kit/elements';
   defineElements(['mk-select']);
 </script>
 ```
 
+Dentro de un `.mk-field` el botón toma la altura, el radio y el relleno de los demás campos. Para cambiar el valor desde fuera usa el atributo `value` (o `setValue` en la instancia); el `<select>` y el botón se actualizan juntos.
+
 ## React
 
 ```tsx
-<Select />
+<Select label="Prioridad" name="priority" value={priority} onChange={setPriority}
+  options={[{ value: 'low', label: 'Baja' }, { value: 'normal', label: 'Normal' }, { value: 'high', label: 'Alta' }]} />
 ```
 
+`options` acepta `{ value, label, disabled?, group? }`; `group` crea encabezados como `<optgroup>`.
+
 ## Opciones
 
 | Opción | Atributo | Por defecto | Qué hace |
 |---|---|---|---|
+| `options` | — | las del `<select>` | Opciones; sin ellas se leen del `<select>` interior. |
+| `value` | `value` | el del `<select>` | Valor elegido. |
+| `name` | `name` | — | Nombre del `<select>` que crea (uno escrito conserva el suyo). |
+| `label` | `label` | `'Opciones'` | Nombre accesible; el botón se lee «label: elegido». |
+| `placeholder` | `placeholder` | texto de la opción vacía o `'Elige…'` | Texto mientras no hay elección. |
+| `disabled` | `disabled` | `false` | Desactiva el botón. |
+| `onChange(value)` | evento `change` del `<select>` / `mk:change` | — | Avisa al elegir. |
 
-## Variables CSS
-
-`--mk-select-radius`
+Instancia: `setValue(value, notify?)`, `setOptions(options)`, `refresh()`, `open()`, `close()`, `value`, `destroy()`.
 
 ## Accesibilidad
 
-Roles, foco y teclado. Con movimiento reducido…
+El botón tiene `aria-haspopup="menu"` y `aria-expanded`; el menú usa `menuitemradio` con `aria-checked` en la opción elegida. ↓ ↑ Intro y Espacio abren el menú; con el botón cerrado, escribir una letra elige la siguiente opción que empieza por ella. Funciona dentro de diálogos, paneles y popovers sin cerrarlos. Con movimiento reducido el menú aparece sin escalonado y el valor cambia sin blur.