@yewdiel21/motion-kit 0.10.0 → 0.14.0

package/src/components/virtual-list/react.tsx

@@ -0,0 +1,101 @@
+'use client';
+import { forwardRef, useImperativeHandle, useRef, useState, type HTMLAttributes, type ReactElement, type ReactNode, type Ref } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import type { VirtualRange } from '../../core/virtual';
+import { createVirtualList, type VirtualKey, type VirtualListInstance, type VirtualListOptions, type VirtualScrollOptions } from './engine';
+
+export interface VirtualListProps<T> extends Omit<HTMLAttributes<HTMLDivElement>, 'onSelect' | 'children'>, Omit<VirtualListOptions<T>, 'items' | 'renderItem' | 'onRange'> {
+  items: T[];
+  /** A row's content; without it, its text. */
+  renderItem?: (item: T, index: number) => ReactNode;
+}
+
+export interface VirtualListHandle {
+  scrollToIndex(index: number, options?: VirtualScrollOptions): void;
+}
+
+const keyFor = <T,>(getKey: VirtualListOptions<T>['getKey'], item: T, index: number): VirtualKey => {
+  if (getKey) return getKey(item, index);
+  const id = item && typeof item === 'object' ? (item as { id?: unknown }).id : undefined;
+  return typeof id === 'string' || typeof id === 'number' ? id : index;
+};
+
+/**
+ * <VirtualList items={rows} itemHeight={44} renderItem={(row) => <Row {...row} />} selectable="multiple" />.
+ * React renders only the rows in view; the engine adopts its viewport, and places, measures and picks the rows.
+ */
+function VirtualListInner<T>(
+  { items, renderItem, itemHeight, estimatedHeight, overscan, itemText, getKey, selectable, selected, label, emptyLabel, locale, onSelect, onActivate, onEndReached, className, ...props }: VirtualListProps<T>,
+  handle: Ref<VirtualListHandle>,
+) {
+  const ref = useRef<HTMLDivElement>(null);
+  const instance = useRef<VirtualListInstance<T> | null>(null);
+  const [range, setRange] = useState<VirtualRange>({ start: 0, end: 0 });
+  const shown = useRef(items);
+  const select = useLatest(onSelect);
+  const activate = useLatest(onActivate);
+  const more = useLatest(onEndReached);
+  const text = useLatest(itemText);
+  const key = useLatest(getKey);
+  useImperativeHandle(handle, () => ({ scrollToIndex: (index, options) => instance.current?.scrollToIndex(index, options) }), []);
+  const custom = Boolean(renderItem);
+  useIsomorphicLayoutEffect(() => {
+    const created = createVirtualList<T>(ref.current, {
+      items: shown.current,
+      itemHeight,
+      estimatedHeight,
+      overscan,
+      selectable,
+      selected,
+      label,
+      emptyLabel,
+      locale,
+      itemText: itemText ? (item) => text.current?.(item) ?? '' : undefined,
+      getKey: (item, index) => keyFor(key.current, item, index),
+      onSelect: (keys, chosen) => select.current?.(keys, chosen),
+      onActivate: (item, index) => activate.current?.(item, index),
+      onEndReached: onEndReached ? () => more.current?.() : undefined,
+      onRange: custom ? setRange : undefined,
+    });
+    instance.current = created;
+    return () => {
+      created.destroy();
+      instance.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [itemHeight, estimatedHeight, overscan, String(selectable), label, emptyLabel, locale, custom, Boolean(onEndReached), Boolean(itemText)]);
+  useIsomorphicLayoutEffect(() => {
+    if (shown.current === items) return;
+    shown.current = items;
+    instance.current?.setItems(items);
+  }, [items]);
+  const selectedKey = JSON.stringify(selected ?? null);
+  useIsomorphicLayoutEffect(() => {
+    if (selected && instance.current && JSON.stringify(instance.current.selected) !== JSON.stringify(selected)) instance.current.select(selected);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [selectedKey]);
+  // After React drew the window: place and measure it.
+  useIsomorphicLayoutEffect(() => {
+    if (custom) instance.current?.refresh();
+  });
+  return (
+    <div {...props} ref={ref} className={['mk-virtual-list', className].filter(Boolean).join(' ')}>
+      <div data-mk-vl-viewport="">
+        <div data-mk-vl-spacer="">
+          {renderItem
+            ? items.slice(range.start, Math.min(range.end, items.length)).map((item, i) => {
+                const index = range.start + i;
+                return (
+                  <div key={keyFor(getKey, item, index)} data-mk-vl-item="" data-index={index}>
+                    {renderItem(item, index)}
+                  </div>
+                );
+              })
+            : null}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export const VirtualList = forwardRef(VirtualListInner) as <T>(props: VirtualListProps<T> & { ref?: Ref<VirtualListHandle> }) => ReactElement;

package/src/components/virtual-list/virtual-list.css

@@ -0,0 +1,194 @@
+/* virtual-list — a 12 px box on surface-1 that scrolls inside (--mk-vl-height, 24rem); the rows sit on a spacer as tall
+   as all of them. Chosen rows take accent-soft and a check that pops; a 2 px accent ring glides between rows for the
+   keyboard; a row reached with scrollToIndex() flashes; the position pill (8 px, inverse glass) rides the right edge
+   while scrolling. */
+.mk-virtual-list,
+mk-virtual-list {
+  --mk-vl-height: 24rem;
+  position: relative;
+  display: block;
+  min-width: 0;
+  color: var(--mk-text);
+}
+
+[data-mk-vl-viewport] {
+  position: relative;
+  box-sizing: border-box;
+  height: var(--mk-vl-height);
+  overflow-y: auto;
+  border: 1px solid var(--mk-outline-soft);
+  border-radius: 12px;
+  outline: none;
+  background: var(--mk-surface-1);
+  overscroll-behavior: contain;
+}
+
+[data-mk-vl-viewport]:focus-visible {
+  box-shadow: 0 0 0 3px color-mix(in srgb, var(--mk-accent) 35%, transparent);
+}
+
+[data-mk-vl-spacer] {
+  position: relative;
+  width: 100%;
+}
+
+[data-mk-vl-item] {
+  position: absolute;
+  top: 0;
+  right: 0;
+  left: 0;
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  min-width: 0;
+  padding: 0.75rem 1rem;
+  border-bottom: 1px solid var(--mk-outline-soft);
+}
+
+[role='listbox'] > [data-mk-vl-spacer] > [data-mk-vl-item] {
+  cursor: pointer;
+  -webkit-user-select: none;
+  user-select: none;
+  transition:
+    background-color 0.15s,
+    color 0.15s;
+}
+
+[role='listbox'] > [data-mk-vl-spacer] > [data-mk-vl-item]:hover {
+  background: color-mix(in srgb, var(--mk-text) 5%, transparent);
+}
+
+[data-mk-vl-item][aria-selected='true'],
+[role='listbox'] > [data-mk-vl-spacer] > [data-mk-vl-item][aria-selected='true']:hover {
+  background: var(--mk-accent-soft);
+  color: var(--mk-on-accent-soft, var(--mk-text));
+}
+
+/* The check of a chosen row; it pops only on the row just chosen, not on rows scrolled into view. */
+[role='listbox'] > [data-mk-vl-spacer] > [data-mk-vl-item]::after {
+  content: '';
+  flex: none;
+  width: 1.125rem;
+  height: 1.125rem;
+  margin-left: auto;
+  background: var(--mk-accent);
+  -webkit-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='3' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M5 12.5l4.5 4.5L19 7.5'/%3E%3C/svg%3E") center / contain no-repeat;
+  mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='3' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M5 12.5l4.5 4.5L19 7.5'/%3E%3C/svg%3E") center / contain no-repeat;
+  opacity: 0;
+}
+
+[role='listbox'] > [data-mk-vl-spacer] > [data-mk-vl-item][aria-selected='true']::after {
+  opacity: 1;
+}
+
+[data-mk-vl-item][data-mk-vl-just]::after {
+  animation: mk-vl-check 0.4s cubic-bezier(0.38, 0.49, 0, 1.5);
+}
+
+@keyframes mk-vl-check {
+  from {
+    opacity: 0;
+    transform: scale(0.3) rotate(-20deg);
+  }
+}
+
+[data-mk-vl-cursor] {
+  position: absolute;
+  top: 0;
+  right: 4px;
+  left: 4px;
+  z-index: 1;
+  border-radius: 8px;
+  box-shadow: inset 0 0 0 2px var(--mk-accent);
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 0.15s;
+}
+
+[data-mk-vl-viewport]:focus-visible [data-mk-vl-cursor] {
+  opacity: 1;
+}
+
+[data-mk-vl-flash] {
+  animation: mk-vl-flash 1.2s cubic-bezier(0.38, 0.49, 0, 1);
+}
+
+@keyframes mk-vl-flash {
+  0%,
+  30% {
+    background-color: color-mix(in srgb, var(--mk-accent) 24%, var(--mk-surface-1));
+  }
+}
+
+[data-mk-vl-foot] {
+  position: absolute;
+  top: 0;
+  right: 0;
+  left: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.5rem;
+  height: 48px;
+  color: var(--mk-muted);
+  font-size: 0.875rem;
+}
+
+[data-mk-vl-foot][hidden],
+[data-mk-vl-empty][hidden],
+[data-mk-vl-pill][hidden] {
+  display: none;
+}
+
+[data-mk-vl-foot][aria-busy='true']::before {
+  content: '';
+  width: 0.875rem;
+  height: 0.875rem;
+  border: 2px solid currentColor;
+  border-right-color: transparent;
+  border-radius: 50%;
+  animation: mk-vl-spin 0.8s linear infinite;
+}
+
+@keyframes mk-vl-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+[data-mk-vl-empty] {
+  position: absolute;
+  inset: 0;
+  display: grid;
+  place-items: center;
+  margin: 0;
+  color: var(--mk-muted);
+  font-size: 0.875rem;
+  pointer-events: none;
+}
+
+[data-mk-vl-pill] {
+  position: absolute;
+  top: 0.5rem;
+  right: 0.875rem;
+  z-index: 2;
+  padding: 0.3rem 0.625rem;
+  border-radius: 8px;
+  background: var(--mk-glass-inverse, var(--mk-text));
+  box-shadow: 0 6px 18px -8px color-mix(in srgb, var(--mk-shadow-color, #000) 45%, transparent);
+  color: var(--mk-on-glass-inverse, var(--mk-surface-1));
+  font-size: 0.75rem;
+  font-variant-numeric: tabular-nums;
+  font-weight: 600;
+  white-space: nowrap;
+  pointer-events: none;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-mk-vl-item][data-mk-vl-just]::after,
+  [data-mk-vl-flash],
+  [data-mk-vl-foot][aria-busy='true']::before {
+    animation: none;
+  }
+}

package/src/core/chips.ts

@@ -0,0 +1,196 @@
+import { gsap, EASE, Flip, registerMotion } from './gsap';
+import { reduced } from './reduced';
+import { createScope } from './scope';
+import { TIMING } from './timing';
+import { ringPulse, shake } from '../motion/micro';
+
+/*
+ * Chips (multi-select, tag-input): removable chips in a list. A chip that
+ * arrives pops in (scale .6 → 1, blur 6 → 0, pop curve) while the others glide
+ * to make room (Flip, layout spring); one that leaves folds away (its width,
+ * padding and margin to 0 out of a blur, .22 s) and the rest close the gap.
+ * Keyboard: from the field, ← reaches the last chip; ← / → move between chips,
+ * Delete or Backspace removes the focused one, → past the last returns to the
+ * field. arm() rings a chip that the next Backspace will remove; flash()
+ * shakes and rings one (a duplicate, a value already chosen).
+ */
+
+export interface ChipItem {
+  value: string;
+  label: string;
+}
+
+export interface ChipsOptions {
+  /** A chip's remove button wants out. */
+  onRemove: (value: string) => void;
+  /** The keyboard left the chips towards the field. */
+  onExit?: () => void;
+  /** Accessible name of a chip's remove button (default 'Quitar <label>'). */
+  removeLabel?: (item: ChipItem) => string;
+  disabled?: boolean;
+}
+
+export interface Chips {
+  readonly element: HTMLUListElement;
+  /** Show these chips in this order; arrivals pop in and departures fold away when `animate`. */
+  set(items: ChipItem[], animate?: boolean): void;
+  /** Ring a chip as the next to go (null: none). */
+  arm(value: string | null): void;
+  readonly armed: string | null;
+  /** Shake and ring a chip. */
+  flash(value: string): void;
+  /** Focus the last chip (from the field). False when there are none. */
+  focusLast(): boolean;
+  destroy(): void;
+}
+
+const CLOSE = '<svg aria-hidden="true" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round"><path d="M7 7l10 10M17 7L7 17"/></svg>';
+
+export function createChips(options: ChipsOptions): Chips {
+  registerMotion();
+  const scope = createScope();
+  const list = document.createElement('ul');
+  list.dataset.mkChips = '';
+  list.setAttribute('role', 'list');
+  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();
+    list.remove();
+  });
+  let armed: string | null = null;
+
+  const chipOf = (value: string) => [...list.querySelectorAll<HTMLElement>('[data-mk-chip]')].find((chip) => chip.dataset.value === value && !chip.hasAttribute('data-mk-leaving')) ?? null;
+  const present = () => [...list.querySelectorAll<HTMLElement>('[data-mk-chip]:not([data-mk-leaving])')];
+
+  const make = (item: ChipItem) => {
+    const chip = document.createElement('li');
+    chip.dataset.mkChip = '';
+    chip.dataset.value = item.value;
+    chip.tabIndex = -1;
+    const label = document.createElement('span');
+    label.dataset.mkChipLabel = '';
+    label.textContent = item.label;
+    chip.append(label);
+    if (!options.disabled) {
+      const remove = document.createElement('button');
+      remove.type = 'button';
+      remove.tabIndex = -1;
+      remove.dataset.mkChipRemove = '';
+      remove.setAttribute('aria-label', options.removeLabel ? options.removeLabel(item) : `Quitar ${item.label}`);
+      remove.innerHTML = CLOSE;
+      chip.append(remove);
+    }
+    return chip;
+  };
+
+  const leave = (chip: HTMLElement, animate: boolean) => {
+    chip.setAttribute('data-mk-leaving', '');
+    if (!animate || reduced()) return chip.remove();
+    gsap.killTweensOf(chip);
+    keep(
+      gsap.to(chip, {
+        width: 0,
+        paddingLeft: 0,
+        paddingRight: 0,
+        marginLeft: 0,
+        marginRight: 0,
+        opacity: 0,
+        scale: 0.8,
+        filter: 'blur(6px)',
+        duration: 0.22,
+        ease: 'power2.in',
+        onComplete: () => chip.remove(),
+      }),
+    );
+  };
+
+  const set = (items: ChipItem[], animate = true) => {
+    const wanted = new Set(items.map((item) => item.value));
+    const staying = present().filter((chip) => wanted.has(chip.dataset.value!));
+    const state = animate && !reduced() && staying.length ? Flip.getState(staying) : null;
+    for (const chip of present()) if (!wanted.has(chip.dataset.value!)) leave(chip, animate);
+    const arriving: HTMLElement[] = [];
+    let previous: HTMLElement | null = null;
+    for (const item of items) {
+      let chip = chipOf(item.value);
+      if (!chip) {
+        chip = make(item);
+        arriving.push(chip);
+      } else chip.querySelector<HTMLElement>('[data-mk-chip-label]')!.textContent = item.label;
+      // Keep the given order; leaving chips stay where they were while they fold.
+      if (previous) previous.after(chip);
+      else list.prepend(chip);
+      previous = chip;
+    }
+    if (armed && !wanted.has(armed)) armed = null;
+    if (state) keep(Flip.from(state, { targets: staying, duration: TIMING.layoutTravel, ease: EASE.layoutReflow }));
+    if (animate && arriving.length && !reduced()) {
+      keep(gsap.fromTo(arriving, { scale: 0.6, opacity: 0, filter: 'blur(6px)' }, { scale: 1, opacity: 1, filter: 'blur(0px)', duration: 0.3, stagger: 0.04, ease: EASE.pop, clearProps: 'scale,opacity,filter,transform' }));
+    }
+  };
+
+  const arm = (value: string | null) => {
+    armed = value;
+    for (const chip of present()) chip.toggleAttribute('data-mk-armed', chip.dataset.value === value);
+    const chip = value ? chipOf(value) : null;
+    if (chip && !reduced()) keep(gsap.fromTo(chip, { scale: 1.08 }, { scale: 1, duration: 0.3, ease: EASE.click, clearProps: 'scale' }));
+  };
+
+  scope.on(list, 'click', (event) => {
+    const remove = (event.target as Element | null)?.closest('[data-mk-chip-remove]');
+    const chip = remove?.closest<HTMLElement>('[data-mk-chip]');
+    if (chip && !chip.hasAttribute('data-mk-leaving')) options.onRemove(chip.dataset.value!);
+  });
+  scope.on(list, 'keydown', (event) => {
+    const key = event as KeyboardEvent;
+    const chip = (key.target as Element | null)?.closest<HTMLElement>('[data-mk-chip]');
+    if (!chip) return;
+    const chips = present();
+    const index = chips.indexOf(chip);
+    if (key.key === 'ArrowLeft') {
+      key.preventDefault();
+      chips[Math.max(0, index - 1)]?.focus();
+    } else if (key.key === 'ArrowRight') {
+      key.preventDefault();
+      if (index >= chips.length - 1) options.onExit?.();
+      else chips[index + 1]?.focus();
+    } else if ((key.key === 'Delete' || key.key === 'Backspace') && !options.disabled) {
+      key.preventDefault();
+      const next = chips[index + 1] ?? chips[index - 1] ?? null;
+      options.onRemove(chip.dataset.value!);
+      if (next && next !== chip && next.isConnected && !next.hasAttribute('data-mk-leaving')) next.focus();
+      else options.onExit?.();
+    } else if (key.key === 'Escape' || key.key === 'Tab') {
+      if (key.key === 'Escape') key.preventDefault();
+      if (key.key === 'Escape') options.onExit?.();
+    }
+  });
+
+  return {
+    element: list,
+    set,
+    arm,
+    get armed() {
+      return armed;
+    },
+    flash(value) {
+      const chip = chipOf(value);
+      if (!chip) return;
+      keep(shake(chip, 3));
+      keep(ringPulse(chip));
+    },
+    focusLast() {
+      const chips = present();
+      chips[chips.length - 1]?.focus();
+      return chips.length > 0;
+    },
+    destroy: () => scope.dispose(),
+  };
+}