@yewdiel21/motion-kit 0.17.0 → 0.18.0

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.
 
 ## 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.

package/src/components/select/select.css

@@ -133,3 +133,19 @@ mk-select {
     transition: none;
   }
 }
+
+/* Inside a kit field the trigger takes the field's height, radius, fill and type. */
+.mk-field :is(.mk-select, mk-select) {
+  display: flex;
+  width: 100%;
+}
+
+.mk-field [data-mk-select-trigger] {
+  height: auto;
+  min-height: 56px;
+  padding: 0 14px 0 16px;
+  border-radius: var(--mk-field-radius);
+  background: var(--mk-field-bg);
+  font-family: var(--md-sys-typescale-body-large-font);
+  font-size: var(--md-sys-typescale-body-large-size);
+}