@yewdiel21/motion-kit 0.10.0 → 0.15.0

package/src/core/listbox.ts

@@ -0,0 +1,332 @@
+import { gsap, EASE, registerMotion } from './gsap';
+import { requestFrame } from './frame';
+import { reduced } from './reduced';
+import { createScope } from './scope';
+import { place } from './position';
+import { matchScore } from '../components/command-search/match';
+
+/*
+ * Listbox (multi-select, tag-input): the options under a combobox field, in
+ * the top layer (popover API) so no overflow clips them, as wide as the field,
+ * below it or above when there is no room. It opens out of the field (from 96 %
+ * and a 6 px blur, .22 s, pop curve) while its first options flow in (20 ms
+ * apart); a pill glides behind the active option (.3 s, swing) as the arrows or
+ * the pointer move it; the letters that match the query are marked (as text);
+ * chosen options show a check that draws itself. The component keeps the
+ * keyboard: it calls move(), pick() and hide().
+ */
+
+export interface ListboxOption {
+  value: string;
+  label: string;
+  group?: string;
+  hint?: string;
+  disabled?: boolean;
+}
+
+export interface ListboxOptions {
+  /** The combobox input: it gets aria-controls and aria-activedescendant. */
+  input: HTMLInputElement;
+  /** The box the list hangs from (the field). */
+  anchor: HTMLElement;
+  /** Where the list element lives in the DOM (it is shown in the top layer). */
+  host: HTMLElement;
+  multiselectable?: boolean;
+  label?: string;
+  emptyLabel?: string;
+  /** Chosen options (a check and aria-selected). */
+  isSelected?: (value: string) => boolean;
+  onPick: (option: ListboxOption) => void;
+}
+
+export interface Listbox {
+  readonly element: HTMLElement;
+  /** Show these options with `query`'s letters marked; opens it. */
+  show(options: ListboxOption[], query?: string): void;
+  hide(): void;
+  readonly isOpen: boolean;
+  /** Move the active option (wraps); 'first' / 'last' jump. */
+  move(delta: number | 'first' | 'last'): void;
+  /** Choose the active option; false when there is none. */
+  pick(): boolean;
+  readonly active: ListboxOption | null;
+  /** Re-mark the chosen options (after the value changed). */
+  refresh(): void;
+  destroy(): void;
+}
+
+const CHECK = '<svg aria-hidden="true" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.6" stroke-linecap="round" stroke-linejoin="round"><path d="M5 12.5l4.5 4.5L19 7.5" pathLength="1"/></svg>';
+let sequence = 0;
+
+/** `text` with the matched ranges in <mark>, built as text nodes. */
+function marked(text: string, query: string) {
+  const fragment = document.createDocumentFragment();
+  const match = query.trim() ? matchScore(query, text) : null;
+  let at = 0;
+  for (const [start, end] of match?.ranges ?? []) {
+    if (start > at) fragment.append(text.slice(at, start));
+    const mark = document.createElement('mark');
+    mark.textContent = text.slice(start, end);
+    fragment.append(mark);
+    at = end;
+  }
+  if (at < text.length) fragment.append(text.slice(at));
+  return fragment;
+}
+
+/** Options that match `query` (fuzzy, accents ignored), best first; all of them, in order, without a query. */
+export function filterOptions<T extends ListboxOption>(options: T[], query: string): T[] {
+  if (!query.trim()) return [...options];
+  return options
+    .map((option, order) => ({ option, order, match: matchScore(query, option.label) ?? (option.hint ? matchScore(query, option.hint) : null) }))
+    .filter((entry) => entry.match)
+    .sort((a, b) => b.match!.score - a.match!.score || a.order - b.order)
+    .map((entry) => entry.option);
+}
+
+export function createListbox(options: ListboxOptions): Listbox {
+  registerMotion();
+  const scope = createScope();
+  const uid = `mk-listbox-${++sequence}`;
+  const list = document.createElement('div');
+  list.id = uid;
+  list.dataset.mkListbox = '';
+  list.setAttribute('role', 'listbox');
+  if (options.multiselectable) list.setAttribute('aria-multiselectable', 'true');
+  if (options.label) list.setAttribute('aria-label', options.label);
+  const pill = document.createElement('span');
+  pill.dataset.mkListboxPill = '';
+  pill.setAttribute('aria-hidden', 'true');
+  const items = document.createElement('div');
+  items.dataset.mkListboxItems = '';
+  list.append(pill, items);
+  const topLayer = typeof list.showPopover === 'function';
+  if (topLayer) list.setAttribute('popover', 'manual');
+  else list.hidden = true;
+  options.host.append(list);
+  scope.attr(options.input, 'aria-controls', uid);
+  scope.attr(options.input, 'aria-expanded', 'false');
+  scope.attr(options.input, 'aria-activedescendant', null);
+  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();
+    gsap.killTweensOf([list, pill]);
+    list.remove();
+  });
+
+  let isOpen = false;
+  let shown: ListboxOption[] = [];
+  let active = -1;
+
+  const optionEls = () => [...items.querySelectorAll<HTMLElement>('[role="option"]')];
+  const shownNow = () => (topLayer ? list.matches(':popover-open') : !list.hidden);
+
+  const position = () => {
+    const anchor = options.anchor.getBoundingClientRect();
+    list.style.width = `${Math.round(anchor.width)}px`;
+    const box = list.getBoundingClientRect();
+    const placed = place(anchor, { width: anchor.width, height: box.height }, { placement: 'bottom', align: 'start', gap: 6 });
+    list.style.left = `${placed.x}px`;
+    list.style.top = `${placed.y}px`;
+    list.dataset.mkSide = placed.side;
+    return placed;
+  };
+  let pending: (() => void) | null = null;
+  const follow = () => {
+    if (!isOpen || pending) return;
+    pending = requestFrame(() => {
+      pending = null;
+      if (isOpen) position();
+    });
+  };
+  scope.add(() => pending?.());
+  scope.on(window, 'resize', follow);
+  scope.on(window, 'scroll', follow, { capture: true, passive: true });
+
+  const movePill = (animate: boolean) => {
+    const option = optionEls()[active];
+    if (!option) {
+      pill.style.opacity = '0';
+      return;
+    }
+    const box = { y: option.offsetTop, height: option.offsetHeight };
+    if (!animate || reduced() || pill.style.opacity === '0') {
+      gsap.set(pill, box);
+      pill.style.opacity = '1';
+      return;
+    }
+    keep(gsap.to(pill, { ...box, duration: 0.3, ease: EASE.swatch, overwrite: 'auto' }));
+  };
+
+  const setActive = (index: number, animate = true) => {
+    const all = optionEls();
+    const enabled = all.map((option, i) => (option.getAttribute('aria-disabled') === 'true' ? -1 : i)).filter((i) => i >= 0);
+    if (!enabled.length) {
+      active = -1;
+      options.input.removeAttribute('aria-activedescendant');
+      movePill(false);
+      return;
+    }
+    active = index;
+    all.forEach((option, i) => option.toggleAttribute('data-mk-active', i === active));
+    const option = all[active];
+    if (option) {
+      options.input.setAttribute('aria-activedescendant', option.id);
+      option.scrollIntoView?.({ block: 'nearest' });
+    } else options.input.removeAttribute('aria-activedescendant');
+    movePill(animate);
+  };
+
+  const mark = () => {
+    for (const option of optionEls()) {
+      const selected = Boolean(options.isSelected?.(option.dataset.value!));
+      const was = option.getAttribute('aria-selected') === 'true';
+      option.setAttribute('aria-selected', String(selected));
+      if (selected && !was && !reduced()) {
+        const path = option.querySelector<SVGPathElement>('[data-mk-option-check] path');
+        if (path) keep(gsap.fromTo(path, { strokeDasharray: 1, strokeDashoffset: 1 }, { strokeDashoffset: 0, duration: 0.3, ease: EASE.wipe, clearProps: 'strokeDasharray,strokeDashoffset' }));
+      }
+    }
+  };
+
+  const render = (query: string) => {
+    items.replaceChildren();
+    let group: string | undefined;
+    shown.forEach((option, i) => {
+      if (option.group && option.group !== group) {
+        group = option.group;
+        const heading = document.createElement('div');
+        heading.dataset.mkListboxGroup = '';
+        heading.setAttribute('role', 'presentation');
+        heading.textContent = option.group;
+        items.append(heading);
+      }
+      const element = document.createElement('div');
+      element.id = `${uid}-${i}`;
+      element.dataset.mkOption = '';
+      element.dataset.value = option.value;
+      element.dataset.mkIndex = String(i);
+      element.setAttribute('role', 'option');
+      element.setAttribute('aria-selected', 'false');
+      if (option.disabled) element.setAttribute('aria-disabled', 'true');
+      if (options.multiselectable) {
+        const check = document.createElement('span');
+        check.dataset.mkOptionCheck = '';
+        check.innerHTML = CHECK;
+        element.append(check);
+      }
+      const label = document.createElement('span');
+      label.dataset.mkOptionLabel = '';
+      label.append(marked(option.label, query));
+      element.append(label);
+      if (option.hint) {
+        const hint = document.createElement('span');
+        hint.dataset.mkOptionHint = '';
+        hint.textContent = option.hint;
+        element.append(hint);
+      }
+      items.append(element);
+    });
+    if (!shown.length) {
+      const empty = document.createElement('div');
+      empty.dataset.mkListboxEmpty = '';
+      empty.textContent = options.emptyLabel ?? 'Sin coincidencias';
+      items.append(empty);
+    }
+    // Without the transition into the new marks: only real changes draw their check.
+    for (const option of optionEls()) option.setAttribute('aria-selected', String(Boolean(options.isSelected?.(option.dataset.value!))));
+  };
+
+  const show = (next: ListboxOption[], query = '') => {
+    const opening = !isOpen;
+    shown = next;
+    render(query);
+    if (opening) {
+      isOpen = true;
+      if (topLayer) {
+        if (!shownNow()) list.showPopover();
+      } else list.hidden = false;
+      options.input.setAttribute('aria-expanded', 'true');
+    }
+    const placed = position();
+    const first = shown.findIndex((option) => !option.disabled);
+    pill.style.opacity = '0';
+    setActive(query.trim() ? first : -1, false);
+    if (opening && !reduced()) {
+      gsap.killTweensOf(list);
+      gsap.set(list, { transformOrigin: placed.side === 'top' ? '50% 100%' : '50% 0%' });
+      keep(gsap.fromTo(list, { opacity: 0, scaleY: 0.96, filter: 'blur(6px)' }, { opacity: 1, scaleY: 1, filter: 'blur(0px)', duration: 0.22, ease: EASE.pop, clearProps: 'opacity,transform,filter' }));
+      const firstOptions = optionEls().slice(0, 10);
+      if (firstOptions.length) keep(gsap.fromTo(firstOptions, { opacity: 0, y: -4 }, { opacity: 1, y: 0, duration: 0.25, stagger: 0.02, ease: 'power2.out', clearProps: 'opacity,transform' }));
+    }
+  };
+
+  const hide = () => {
+    if (!isOpen) return;
+    isOpen = false;
+    active = -1;
+    options.input.setAttribute('aria-expanded', 'false');
+    options.input.removeAttribute('aria-activedescendant');
+    const finish = () => {
+      if (topLayer) {
+        if (shownNow()) list.hidePopover();
+      } else list.hidden = true;
+      gsap.set(list, { clearProps: 'opacity,transform,filter' });
+    };
+    if (reduced()) return finish();
+    gsap.killTweensOf(list);
+    keep(gsap.to(list, { opacity: 0, scaleY: 0.97, duration: 0.12, ease: 'power2.in', onComplete: finish }));
+  };
+
+  scope.on(items, 'pointermove', (event) => {
+    const option = (event.target as Element | null)?.closest<HTMLElement>('[role="option"]');
+    if (!option || option.getAttribute('aria-disabled') === 'true') return;
+    const index = Number(option.dataset.mkIndex);
+    if (index !== active) setActive(index);
+  });
+  // The pointer must not take the focus from the field.
+  scope.on(list, 'pointerdown', (event) => event.preventDefault());
+  scope.on(items, 'click', (event) => {
+    const option = (event.target as Element | null)?.closest<HTMLElement>('[role="option"]');
+    if (!option || option.getAttribute('aria-disabled') === 'true') return;
+    options.onPick(shown[Number(option.dataset.mkIndex)]!);
+  });
+
+  return {
+    element: list,
+    show,
+    hide,
+    get isOpen() {
+      return isOpen;
+    },
+    move(delta) {
+      if (!isOpen) return;
+      const all = optionEls();
+      const enabled = all.map((option, i) => (option.getAttribute('aria-disabled') === 'true' ? -1 : i)).filter((i) => i >= 0);
+      if (!enabled.length) return;
+      if (delta === 'first') return setActive(enabled[0]!);
+      if (delta === 'last') return setActive(enabled[enabled.length - 1]!);
+      const at = enabled.indexOf(active);
+      const next = at < 0 ? (delta > 0 ? 0 : enabled.length - 1) : (at + delta + enabled.length) % enabled.length;
+      setActive(enabled[next]!);
+    },
+    pick() {
+      const option = shown[active];
+      if (!option || option.disabled) return false;
+      options.onPick(option);
+      return true;
+    },
+    get active() {
+      return shown[active] ?? null;
+    },
+    refresh: mark,
+    destroy: () => scope.dispose(),
+  };
+}

package/src/core/mark.ts

@@ -0,0 +1,29 @@
+/*
+ * Marking matches (tree-view, json-viewer, data-table): text folded for
+ * comparing (accents and case ignored), and text with the matches of a query
+ * wrapped in <mark>.
+ */
+
+/** Lower case without accents ("Canción" → "cancion"); lengths stay the same for precomposed text. */
+export const foldText = (text: string) => text.normalize('NFD').replace(/[̀-ͯ]/g, '').toLowerCase();
+
+/** `text` with the folded matches of `query` in <mark> (accents and case ignored). */
+export function markText(text: string, query: string): DocumentFragment {
+  const fragment = document.createDocumentFragment();
+  const needle = foldText(query.trim());
+  if (!needle) {
+    fragment.append(text);
+    return fragment;
+  }
+  const hay = foldText(text);
+  let at = 0;
+  for (let found = hay.indexOf(needle); found >= 0; found = hay.indexOf(needle, found + needle.length)) {
+    if (found > at) fragment.append(text.slice(at, found));
+    const mark = document.createElement('mark');
+    mark.textContent = text.slice(found, found + needle.length);
+    fragment.append(mark);
+    at = found + needle.length;
+  }
+  if (at < text.length) fragment.append(text.slice(at));
+  return fragment;
+}

package/src/core/position.ts

@@ -0,0 +1,89 @@
+/*
+ * Floating placement (tooltip, chart-tooltip, listboxes): a box of `size` goes
+ * next to `anchor` on the preferred side, flips to the opposite side when its
+ * own has no room and the other has more ('auto' takes the roomiest side),
+ * slides along the edge to stay `edge` px inside the viewport, and reports
+ * where an arrow should point (the anchor's centre, kept off the corners).
+ * Pure: the callers measure and write the result.
+ */
+
+export type Side = 'top' | 'bottom' | 'left' | 'right';
+export type Placement = Side | 'auto';
+
+export interface Box {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+export interface PlaceOptions {
+  placement?: Placement;
+  /** Space between anchor and box (default 8). */
+  gap?: number;
+  /** Distance kept from the viewport edges (default 8). */
+  edge?: number;
+  /** Along the edge: centred on the anchor (default) or flush with its start or end. */
+  align?: 'center' | 'start' | 'end';
+  /** The arrow stays this far from the box's corners (default 12). */
+  arrowPad?: number;
+  viewport?: { width: number; height: number };
+}
+
+export interface Placed {
+  side: Side;
+  /** Viewport coordinates of the box's top-left corner. */
+  x: number;
+  y: number;
+  /** Arrow position along the box's edge facing the anchor, in px from its start. */
+  arrow: number;
+}
+
+export const OPPOSITE: Record<Side, Side> = { top: 'bottom', bottom: 'top', left: 'right', right: 'left' };
+
+const clamp = (value: number, min: number, max: number) => Math.max(min, Math.min(value, max));
+const round = (n: number) => Math.round(n * 100) / 100;
+
+export function place(anchor: Box, size: { width: number; height: number }, options: PlaceOptions = {}): Placed {
+  const { placement = 'top', gap = 8, edge = 8, align = 'center', arrowPad = 12 } = options;
+  const view = options.viewport ?? { width: innerWidth, height: innerHeight };
+  const room: Record<Side, number> = {
+    top: anchor.top - gap - edge,
+    bottom: view.height - (anchor.top + anchor.height) - gap - edge,
+    left: anchor.left - gap - edge,
+    right: view.width - (anchor.left + anchor.width) - gap - edge,
+  };
+  const need = (side: Side) => (side === 'top' || side === 'bottom' ? size.height : size.width);
+  let side: Side;
+  if (placement === 'auto') {
+    const order: Side[] = ['top', 'bottom', 'right', 'left'];
+    side = order.find((candidate) => room[candidate] >= need(candidate)) ?? order.reduce((best, candidate) => (room[candidate] - need(candidate) > room[best] - need(best) ? candidate : best));
+  } else {
+    side = placement;
+    if (room[side] < need(side) && room[OPPOSITE[side]] > room[side]) side = OPPOSITE[side];
+  }
+  const vertical = side === 'top' || side === 'bottom';
+  let x: number;
+  let y: number;
+  if (vertical) {
+    y = side === 'top' ? anchor.top - gap - size.height : anchor.top + anchor.height + gap;
+    x = align === 'start' ? anchor.left : align === 'end' ? anchor.left + anchor.width - size.width : anchor.left + anchor.width / 2 - size.width / 2;
+    x = clamp(x, edge, view.width - edge - size.width);
+  } else {
+    x = side === 'left' ? anchor.left - gap - size.width : anchor.left + anchor.width + gap;
+    y = align === 'start' ? anchor.top : align === 'end' ? anchor.top + anchor.height - size.height : anchor.top + anchor.height / 2 - size.height / 2;
+    y = clamp(y, edge, view.height - edge - size.height);
+  }
+  const length = vertical ? size.width : size.height;
+  const centre = vertical ? anchor.left + anchor.width / 2 - x : anchor.top + anchor.height / 2 - y;
+  const pad = Math.min(arrowPad, length / 2);
+  return { side, x: round(x), y: round(y), arrow: round(clamp(centre, pad, length - pad)) };
+}
+
+/** The point the box should grow from: its edge facing the anchor, at the arrow. */
+export function originOf({ side, arrow }: Placed): string {
+  if (side === 'top') return `${arrow}px 100%`;
+  if (side === 'bottom') return `${arrow}px 0%`;
+  if (side === 'left') return `100% ${arrow}px`;
+  return `0% ${arrow}px`;
+}

package/src/core/relative-time.ts

@@ -0,0 +1,77 @@
+import { capitalize, safeFormat, startOfDay } from './dates';
+
+/*
+ * Relative times for timelines and feeds: "ahora", "hace 5 min", "hace 2 h",
+ * "ayer", "hace 3 días", then the date ("12 nov."; with the year when it is
+ * another one). dayLabel() heads groups of a day: "Hoy", "Ayer",
+ * "Lunes, 12 de noviembre". everyMinute() shares one timer between every
+ * component that refreshes its times.
+ */
+
+export type TimeInput = Date | string | number;
+
+/** A date from a Date, an ISO string or a timestamp; null when unreadable. */
+export function toTime(input: TimeInput | null | undefined): Date | null {
+  if (input === null || input === undefined || input === '') return null;
+  if (input instanceof Date) return Number.isNaN(input.getTime()) ? null : input;
+  if (typeof input === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(input.trim())) {
+    const [y, m, d] = input.trim().split('-').map(Number);
+    return new Date(y!, m! - 1, d!);
+  }
+  const date = new Date(input);
+  return Number.isNaN(date.getTime()) ? null : date;
+}
+
+/** Short for minutes and hours ("hace 5 min", "hace 2 h"), long for days ("hace 3 días", "ayer"). */
+const relative = (locale: string, style: 'short' | 'long' = 'short') => {
+  try {
+    return new Intl.RelativeTimeFormat(locale, { numeric: 'auto', style });
+  } catch {
+    return new Intl.RelativeTimeFormat(undefined, { numeric: 'auto', style });
+  }
+};
+
+const daysBetween = (a: Date, b: Date) => Math.round((startOfDay(a).getTime() - startOfDay(b).getTime()) / 86_400_000);
+
+/** "ahora", "hace 5 min", "hace 2 h", "ayer", "hace 3 días", then "12 nov." (with the year when it differs). */
+export function relativeTime(date: Date, now: Date = new Date(), locale = 'es'): string {
+  const seconds = Math.round((date.getTime() - now.getTime()) / 1000);
+  const abs = Math.abs(seconds);
+  const format = relative(locale);
+  if (abs < 45) return locale.startsWith('es') ? 'ahora' : format.format(0, 'second');
+  if (abs < 3600) return format.format(Math.round(seconds / 60), 'minute');
+  const days = daysBetween(date, now);
+  if (days === 0) return format.format(Math.round(seconds / 3600), 'hour');
+  if (Math.abs(days) < 7) return relative(locale, 'long').format(days, 'day');
+  const sameYear = date.getFullYear() === now.getFullYear();
+  return safeFormat(locale, { day: 'numeric', month: 'short', ...(sameYear ? {} : { year: 'numeric' }) }).format(date);
+}
+
+/** The full date and time, for a title or a screen reader. */
+export function fullTime(date: Date, locale = 'es'): string {
+  return safeFormat(locale, { dateStyle: 'full', timeStyle: 'short' }).format(date);
+}
+
+/** "Hoy", "Ayer", "Mañana", else "Lunes, 12 de noviembre" (with the year when it differs). */
+export function dayLabel(date: Date, now: Date = new Date(), locale = 'es'): string {
+  const days = daysBetween(date, now);
+  if (Math.abs(days) <= 1) return capitalize(relative(locale, 'long').format(days, 'day'));
+  const sameYear = date.getFullYear() === now.getFullYear();
+  return capitalize(safeFormat(locale, { weekday: 'long', day: 'numeric', month: 'long', ...(sameYear ? {} : { year: 'numeric' }) }).format(date));
+}
+
+const listeners = new Set<() => void>();
+let timer: ReturnType<typeof setInterval> | undefined;
+
+/** Call `fn` every minute (one shared timer); returns the function that stops it. */
+export function everyMinute(fn: () => void): () => void {
+  listeners.add(fn);
+  timer ??= setInterval(() => listeners.forEach((listener) => listener()), 60_000);
+  return () => {
+    listeners.delete(fn);
+    if (!listeners.size && timer !== undefined) {
+      clearInterval(timer);
+      timer = undefined;
+    }
+  };
+}