@yewdiel21/motion-kit 0.14.0 → 0.15.0

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

@@ -0,0 +1,252 @@
+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 { blurIn } from '../../motion/micro';
+
+/*
+ * Scroll island: the scroller's own bar is hidden and a thin pill takes its
+ * place, shown while scrolling (it fades .9 s after). When the mouse comes near
+ * the edge, the pill swells into an island, a dark capsule (like iOS's island)
+ * with the percentage read and the current section (its last heading above a
+ * third of the view), on Melonmind's swing; dragging the island scrolls, a click
+ * on the rail glides there. Far from the edge it shrinks back into the bar. It
+ * follows the page or any scrolling element; touch keeps the native scrolling.
+ * The island is decorative (aria-hidden): keyboard and assistive tech scroll as
+ * always.
+ */
+
+export interface ScrollIslandOptions {
+  /** Headings that name the sections (default 'h2, h3'); false: only the percentage. */
+  sections?: string | false;
+  /** How near the edge, in px, the pointer turns the bar into the island (default 56). */
+  reach?: number;
+  /** ms the bar stays after scrolling stops (default 900). */
+  idle?: number;
+  /** Follow the page's scroll (default: when the root is <html> or <body>). */
+  page?: boolean;
+  /** The current section changed (its heading's text, or null before the first). */
+  onSection?: (section: string | null) => void;
+}
+
+export interface ScrollIslandInstance extends Instance {
+  /** Measure again (after the content changed size). */
+  refresh(): void;
+}
+
+type State = 'hidden' | 'bar' | 'island';
+/** Space kept from the scroller's edges. */
+const INSET = 6;
+const BAR_WIDTH = 4;
+const ISLAND_HEIGHT = 36;
+const MIN_BAR = 28;
+
+export function createScrollIsland(root: HTMLElement | null, options: ScrollIslandOptions = {}): ScrollIslandInstance {
+  if (!root) return inert({ refresh() {} });
+  registerMotion();
+  const scope = createScope();
+  const page = options.page ?? (root === document.documentElement || root === document.body);
+  const scroller = page ? ((document.scrollingElement as HTMLElement | null) ?? document.documentElement) : root;
+  const reach = Number.isFinite(options.reach) ? Math.max(8, options.reach!) : 56;
+  const idle = Number.isFinite(options.idle) ? Math.max(0, options.idle!) : 900;
+  const marked = page ? document.documentElement : root;
+  // The scroller's own bar hides (scroll-island.css).
+  scope.attr(marked, 'data-mk-scroll-island-host', '');
+
+  const island = document.createElement('div');
+  island.dataset.mkScrollIsland = '';
+  island.dataset.mkState = 'hidden';
+  island.setAttribute('aria-hidden', 'true');
+  const rail = document.createElement('span');
+  rail.dataset.mkIslandRail = '';
+  const thumb = document.createElement('div');
+  thumb.dataset.mkIslandThumb = '';
+  const content = document.createElement('span');
+  content.dataset.mkIslandContent = '';
+  const percent = document.createElement('span');
+  percent.dataset.mkIslandPercent = '';
+  const sectionText = document.createElement('span');
+  sectionText.dataset.mkIslandSection = '';
+  content.append(percent, sectionText);
+  thumb.append(content);
+  island.append(rail, thumb);
+  document.body.append(island);
+  scope.add(() => island.remove());
+
+  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);
+  };
+  scope.add(() => {
+    for (const effect of effects) effect.kill();
+    effects.clear();
+  });
+
+  /** The scroller's box on screen (the window for the page). */
+  const frame = () => (page ? { top: 0, left: 0, right: innerWidth, bottom: innerHeight, height: innerHeight } : root.getBoundingClientRect());
+  const track = () => {
+    const box = frame();
+    return { top: box.top + INSET, height: Math.max(0, box.height - INSET * 2), right: box.right, left: box.left, bottom: box.bottom };
+  };
+  const range = () => Math.max(0, scroller.scrollHeight - scroller.clientHeight);
+  const scrollable = () => range() > 1;
+  const progress = () => (range() ? Math.min(1, Math.max(0, scroller.scrollTop / range())) : 0);
+
+  let state: State = 'hidden';
+  let section: string | null | undefined;
+  let hideTimer: ReturnType<typeof setTimeout> | undefined;
+  let dragging: { id: number; offset: number } | null = null;
+  scope.add(() => clearTimeout(hideTimer));
+
+  const headings = () => (options.sections === false ? [] : [...(page ? document.body : root).querySelectorAll<HTMLElement>(options.sections ?? 'h2, h3')]);
+  const currentSection = () => {
+    const box = frame();
+    const line = box.top + scroller.clientHeight * 0.3;
+    let found: HTMLElement | null = null;
+    for (const heading of headings()) if (heading.getBoundingClientRect().top <= line) found = heading;
+    return found?.textContent?.trim() || null;
+  };
+
+  /** Where the thumb goes: the bar's length follows the view; the island is a fixed capsule. */
+  const geometry = (as: State) => {
+    const { height } = track();
+    const size = as === 'island' ? ISLAND_HEIGHT : Math.max(MIN_BAR, Math.min(height, height * (scroller.clientHeight / Math.max(1, scroller.scrollHeight))));
+    const top = (height - size) * progress();
+    if (as !== 'island') return { top, height: size, width: BAR_WIDTH, borderRadius: BAR_WIDTH / 2 };
+    return { top, height: size, width: Math.max(ISLAND_HEIGHT, content.scrollWidth + 28), borderRadius: size / 2 };
+  };
+
+  const place = () => {
+    const box = track();
+    Object.assign(island.style, { top: `${box.top}px`, height: `${box.height}px`, left: `${box.left}px`, width: `${Math.max(0, box.right - box.left - 4)}px` });
+  };
+
+  const paintText = () => {
+    percent.textContent = `${Math.round(progress() * 100)} %`;
+    const now = currentSection();
+    if (now !== section) {
+      const first = section === undefined;
+      section = now;
+      sectionText.textContent = now ?? '';
+      sectionText.hidden = !now;
+      if (!first && state === 'island' && !reduced()) keep(blurIn(sectionText, { from: 'soft', duration: 0.3 }));
+      options.onSection?.(now);
+      root.dispatchEvent(new CustomEvent('mk:section', { bubbles: true, detail: { section: now } }));
+    }
+  };
+
+  /** Move to a state; `follow` keeps the thumb on the position without a tween (while scrolling or dragging). */
+  const go = (next: State, follow = false) => {
+    if (!scrollable()) next = 'hidden';
+    const changed = next !== state;
+    state = next;
+    island.dataset.mkState = next;
+    place();
+    const shape = geometry(next === 'hidden' ? 'bar' : next);
+    if (follow || !changed || reduced()) {
+      gsap.killTweensOf(thumb);
+      gsap.set(thumb, shape);
+      return;
+    }
+    gsap.killTweensOf(thumb);
+    keep(gsap.to(thumb, { ...shape, duration: next === 'island' ? 0.42 : 0.32, ease: next === 'island' ? EASE.swatch : 'power3.out' }));
+  };
+
+  const settleLater = () => {
+    clearTimeout(hideTimer);
+    hideTimer = setTimeout(() => {
+      if (state === 'bar' && !dragging) go('hidden');
+    }, idle);
+  };
+
+  const onScroll = () => {
+    paintText();
+    if (state === 'island' || dragging) go(state, true);
+    else {
+      go('bar', true);
+      settleLater();
+    }
+  };
+  scope.on(page ? window : root, 'scroll', onScroll, { passive: true });
+  // A scroller inside the page moves with the page: the overlay follows it.
+  if (!page) scope.on(window, 'scroll', () => state !== 'hidden' && place(), { passive: true, capture: true });
+  scope.on(window, 'resize', () => go(state, true));
+
+  const near = (x: number, y: number) => {
+    const box = track();
+    return y >= box.top - INSET && y <= box.top + box.height + INSET && x <= box.right && box.right - x <= reach;
+  };
+  scope.on(window, 'pointermove', (event) => {
+    const move = event as PointerEvent;
+    if (move.pointerType === 'touch') return;
+    if (dragging) {
+      if (move.pointerId !== dragging.id) return;
+      const box = track();
+      const shape = geometry('island');
+      const ratio = (move.clientY - box.top - dragging.offset) / Math.max(1, box.height - shape.height);
+      scroller.scrollTop = Math.min(1, Math.max(0, ratio)) * range();
+      onScroll();
+      return;
+    }
+    if (near(move.clientX, move.clientY)) {
+      if (state !== 'island' && scrollable()) {
+        clearTimeout(hideTimer);
+        paintText();
+        go('island');
+      }
+    } else if (state === 'island') {
+      const box = track();
+      // A little slack, so the island does not flicker at the border of its reach.
+      if (box.right - move.clientX > reach + 24 || move.clientY < box.top - 24 || move.clientY > box.top + box.height + 24) {
+        go('bar');
+        settleLater();
+      }
+    }
+  });
+
+  // Dragging the island scrolls; a click on the rail glides there.
+  scope.on(thumb, 'pointerdown', (event) => {
+    const down = event as PointerEvent;
+    if (state !== 'island' || down.button !== 0) return;
+    down.preventDefault();
+    down.stopPropagation();
+    const box = thumb.getBoundingClientRect();
+    dragging = { id: down.pointerId, offset: down.clientY - box.top || ISLAND_HEIGHT / 2 };
+    island.setAttribute('data-mk-dragging', '');
+    try {
+      thumb.setPointerCapture(down.pointerId);
+    } catch {
+      // jsdom and synthetic events have no active pointer to capture.
+    }
+  });
+  const release = (event: Event) => {
+    if (!dragging || (event as PointerEvent).pointerId !== dragging.id) return;
+    dragging = null;
+    island.removeAttribute('data-mk-dragging');
+  };
+  scope.on(window, 'pointerup', release);
+  scope.on(window, 'pointercancel', release);
+  scope.on(rail, 'pointerdown', (event) => {
+    const down = event as PointerEvent;
+    if (state !== 'island' || down.button !== 0) return;
+    down.preventDefault();
+    const box = track();
+    const size = geometry('island').height;
+    const ratio = (down.clientY - box.top - size / 2) / Math.max(1, box.height - size);
+    scroller.scrollTo({ top: Math.round(Math.min(1, Math.max(0, ratio)) * range()), behavior: reduced() ? 'auto' : 'smooth' });
+  });
+
+  paintText();
+  go('hidden');
+
+  return {
+    refresh: () => {
+      paintText();
+      go(state, true);
+    },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/scroll-island/react.tsx

@@ -0,0 +1,26 @@
+'use client';
+import { useRef, type HTMLAttributes } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createScrollIsland, type ScrollIslandOptions } from './engine';
+
+export interface ScrollIslandProps extends HTMLAttributes<HTMLDivElement>, ScrollIslandOptions {}
+
+/**
+ * <ScrollIsland style={{ height: 400, overflow: 'auto' }}>…</ScrollIsland> scrolls its children with the island;
+ * <ScrollIsland page /> puts it on the page (it renders nothing of its own then).
+ */
+export function ScrollIsland({ sections, reach, idle, page, onSection, className, children, ...props }: ScrollIslandProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const section = useLatest(onSection);
+  useIsomorphicLayoutEffect(() => {
+    const created = createScrollIsland(page ? document.documentElement : ref.current, { sections, reach, idle, page, onSection: (name) => section.current?.(name) });
+    return () => created.destroy();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [sections, reach, idle, page]);
+  if (page) return null;
+  return (
+    <div {...props} ref={ref} className={['mk-scroll-island', className].filter(Boolean).join(' ')}>
+      {children}
+    </div>
+  );
+}

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

@@ -0,0 +1,110 @@
+/* scroll-island — the scroller's bar hides and a thin pill takes its place while scrolling; near the edge it swells
+   into a dark capsule (iOS-island style) with the percentage and the current section, which can be dragged. */
+.mk-scroll-island,
+mk-scroll-island {
+  display: block;
+}
+
+[data-mk-scroll-island-host] {
+  scrollbar-width: none;
+}
+
+[data-mk-scroll-island-host]::-webkit-scrollbar {
+  display: none;
+}
+
+[data-mk-scroll-island] {
+  position: fixed;
+  z-index: 2147483640;
+  pointer-events: none;
+}
+
+[data-mk-island-rail] {
+  position: absolute;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  width: 1.5rem;
+  cursor: pointer;
+  pointer-events: none;
+}
+
+[data-mk-island-thumb] {
+  position: absolute;
+  top: 0;
+  right: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 4px;
+  overflow: hidden;
+  border-radius: 999px;
+  background: color-mix(in srgb, var(--mk-text) 42%, transparent);
+  color: #fff;
+  opacity: 0;
+  transition:
+    opacity 0.25s ease,
+    background-color 0.3s ease,
+    box-shadow 0.3s ease;
+}
+
+[data-mk-scroll-island][data-mk-state='bar'] [data-mk-island-thumb] {
+  opacity: 1;
+}
+
+[data-mk-scroll-island][data-mk-state='island'] [data-mk-island-rail],
+[data-mk-scroll-island][data-mk-state='island'] [data-mk-island-thumb] {
+  pointer-events: auto;
+}
+
+[data-mk-scroll-island][data-mk-state='island'] [data-mk-island-thumb] {
+  background: #0c0c0e;
+  box-shadow:
+    inset 0 0 0 1px rgb(255 255 255 / 0.08),
+    0 12px 30px -8px rgb(0 0 0 / 0.45);
+  opacity: 1;
+  cursor: grab;
+}
+
+[data-mk-scroll-island][data-mk-dragging] [data-mk-island-thumb] {
+  cursor: grabbing;
+}
+
+[data-mk-island-content] {
+  display: inline-flex;
+  flex: none;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0 14px;
+  font-family: var(--mk-font);
+  font-size: 0.8125rem;
+  font-weight: 600;
+  font-variant-numeric: tabular-nums;
+  white-space: nowrap;
+  opacity: 0;
+  transition: opacity 0.18s ease;
+}
+
+[data-mk-scroll-island][data-mk-state='island'] [data-mk-island-content] {
+  opacity: 1;
+  transition-delay: 0.1s;
+}
+
+[data-mk-island-section] {
+  max-width: 12rem;
+  overflow: hidden;
+  color: rgb(255 255 255 / 0.68);
+  font-weight: 500;
+  text-overflow: ellipsis;
+}
+
+[data-mk-island-section][hidden] {
+  display: none;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-mk-island-thumb],
+  [data-mk-island-content] {
+    transition: none;
+  }
+}

package/src/components/select/README.md

@@ -0,0 +1,34 @@
+# select
+
+Qué hace, en una frase.
+
+Origen: archivo del kit y parámetros (tiempos, curvas).
+
+## HTML / Astro
+
+```html
+<mk-select></mk-select>
+<script>
+  import { defineElements } from '@yewdiel21/motion-kit/elements';
+  defineElements(['mk-select']);
+</script>
+```
+
+## React
+
+```tsx
+<Select />
+```
+
+## Opciones
+
+| Opción | Atributo | Por defecto | Qué hace |
+|---|---|---|---|
+
+## Variables CSS
+
+`--mk-select-radius`
+
+## Accesibilidad
+
+Roles, foco y teclado. Con movimiento reducido…

package/src/components/select/element.ts

@@ -0,0 +1,26 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createSelect, type SelectInstance } from './engine';
+
+/**
+ * <mk-select class="mk-select" label="Equipo"><select name="equipo">…</select></mk-select>
+ * The select inside gives the options and stays in step (forms post it). Emits mk:change ({value}).
+ */
+export class MkSelectElement extends MkElement<SelectInstance> {
+  static options: Record<string, OptionType> = { value: 'string', name: 'string', label: 'string', placeholder: 'string', disabled: 'boolean' };
+
+  protected create(options: Record<string, unknown>) {
+    return createSelect(this, options);
+  }
+
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.instance) return;
+    if (name === 'value' && next !== null) this.instance.setValue(next, false);
+    else super.attributeChangedCallback(name, previous, next);
+  }
+
+  get value() {
+    return this.instance?.value ?? '';
+  }
+}
+
+export const defineSelect = () => defineElement('mk-select', MkSelectElement);