@yewdiel21/motion-kit 0.10.0 → 0.15.0

package/src/components/time-field/engine.ts

@@ -0,0 +1,110 @@
+import { createScope } from '../../core/scope';
+import { registerMotion } from '../../core/gsap';
+import { inert, type Instance } from '../../core/types';
+import { formatTime, parseTime, timeMinutes, to12, to24 } from '../../core/segments';
+import { createSegmentField, type SegmentValues } from '../../core/segment-field';
+
+/*
+ * Time field: hour, minute (and second) segments in the locale's order, with
+ * a.m./p.m. where the locale writes 12 hours. The value is always 24 h text
+ * ("13:05"). Arrows step with wrap and the digits roll; typing fills and moves
+ * on; a pill glides to the focused segment (core/segment-field.ts). min/max
+ * mark the group invalid (one shake when it becomes invalid) but the value is
+ * still reported, like a native input.
+ */
+
+export interface TimeFieldOptions {
+  /** 'HH:MM' or 'HH:MM:SS' (24 h). */
+  value?: string | null;
+  locale?: string;
+  /** 12 or 24; default: the locale's. */
+  hourCycle?: 12 | 24;
+  seconds?: boolean;
+  /** Arrow step of the minutes (and seconds). */
+  minuteStep?: number;
+  min?: string;
+  max?: string;
+  /** Accessible name of the group (default 'Hora'). */
+  label?: string;
+  /** Hidden input with the 24 h text. */
+  name?: string;
+  disabled?: boolean;
+  readOnly?: boolean;
+  onChange?: (value: string | null) => void;
+}
+
+export interface TimeFieldInstance extends Instance {
+  setValue(value: string | null, animate?: boolean): void;
+  focus(): void;
+  readonly value: string | null;
+}
+
+export function createTimeField(root: HTMLElement | null, options: TimeFieldOptions = {}): TimeFieldInstance {
+  if (!root) return inert({ setValue() {}, focus() {}, value: null });
+  registerMotion();
+  const scope = createScope();
+  const locale = options.locale ?? root.closest('[lang]')?.getAttribute('lang') ?? 'es';
+  const seconds = Boolean(options.seconds);
+  const step = options.minuteStep && options.minuteStep > 0 ? Math.round(options.minuteStep) : 1;
+  const min = parseTime(options.min);
+  const max = parseTime(options.max);
+  let value: string | null = null;
+  let invalid = false;
+
+  const hidden = options.name ? document.createElement('input') : null;
+  const field = createSegmentField(root, {
+    kind: 'time',
+    locale,
+    hour12: options.hourCycle ? options.hourCycle === 12 : undefined,
+    seconds,
+    steps: { minute: step, second: step },
+    disabled: options.disabled,
+    readOnly: options.readOnly,
+    onChange: (values) => {
+      update(values);
+      options.onChange?.(value);
+      root.dispatchEvent(new CustomEvent('mk:change', { bubbles: true, detail: { value } }));
+    },
+  });
+  scope.add(() => field.destroy());
+  field.element.setAttribute('aria-label', options.label ?? 'Hora');
+  if (hidden) {
+    hidden.type = 'hidden';
+    hidden.name = options.name!;
+    root.append(hidden);
+    scope.add(() => hidden.remove());
+  }
+  scope.attr(root, 'data-mk-ready', '');
+  const twelve = field.element.querySelector('[data-mk-segment="dayPeriod"]') !== null;
+
+  const update = (values: SegmentValues, initial = false) => {
+    const complete = values.hour != null && values.minute != null && (!seconds || values.second != null) && (!twelve || values.dayPeriod != null);
+    const time = complete ? { hour: twelve ? to24(values.hour!, values.dayPeriod!) : values.hour!, minute: values.minute!, second: values.second ?? 0 } : null;
+    value = time ? formatTime(time, seconds) : null;
+    if (hidden) hidden.value = value ?? '';
+    const out = !!time && ((!!min && timeMinutes(time) < timeMinutes(min)) || (!!max && timeMinutes(time) > timeMinutes(max)));
+    field.invalid(out, out && !invalid && !initial);
+    invalid = out;
+  };
+
+  const setValue = (next: string | null, animate = true) => {
+    if (scope.disposed) return;
+    const time = parseTime(next);
+    if (!time) field.setValues({ hour: null, minute: null, second: null, dayPeriod: null }, animate);
+    else if (twelve) {
+      const { hour, period } = to12(time.hour);
+      field.setValues({ hour, dayPeriod: period, minute: time.minute, second: time.second }, animate);
+    } else field.setValues({ hour: time.hour, minute: time.minute, second: time.second }, animate);
+    update(field.values(), true);
+  };
+  setValue(options.value ?? null, false);
+
+  return {
+    setValue,
+    focus: () => field.focus('first'),
+    get value() {
+      return value;
+    },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/time-field/react.tsx

@@ -0,0 +1,45 @@
+'use client';
+import { useRef, type HTMLAttributes } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createTimeField, type TimeFieldInstance, type TimeFieldOptions } from './engine';
+
+export interface TimeFieldProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue'>, Omit<TimeFieldOptions, 'value'> {
+  /** Controlled time ('HH:MM', 24 h); without it the field keeps its own (defaultValue). */
+  value?: string | null;
+  defaultValue?: string | null;
+}
+
+/** <TimeField value={time} onChange={setTime} minuteStep={15} />. */
+export function TimeField({ value, defaultValue, locale, hourCycle, seconds, minuteStep, min, max, label, name, disabled, readOnly, onChange, className, ...props }: TimeFieldProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const instance = useRef<TimeFieldInstance | null>(null);
+  const change = useLatest(onChange);
+  const start = useRef(value !== undefined ? value : (defaultValue ?? null));
+  useIsomorphicLayoutEffect(() => {
+    const created = createTimeField(ref.current, {
+      value: value !== undefined ? value : start.current,
+      locale,
+      hourCycle,
+      seconds,
+      minuteStep,
+      min,
+      max,
+      label,
+      name,
+      disabled,
+      readOnly,
+      onChange: (next) => change.current?.(next),
+    });
+    instance.current = created;
+    return () => {
+      start.current = created.value;
+      created.destroy();
+      instance.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [locale, hourCycle, seconds, minuteStep, min, max, label, name, disabled, readOnly]);
+  useIsomorphicLayoutEffect(() => {
+    if (value !== undefined && instance.current && instance.current.value !== value) instance.current.setValue(value);
+  }, [value]);
+  return <div {...props} ref={ref} className={['mk-time-field', className].filter(Boolean).join(' ')} />;
+}

package/src/components/time-field/time-field.css

@@ -0,0 +1,87 @@
+/* time-field — a 12 px field on surface-3; tabular digits; the focused segment sits on a 6 px accent-soft pill that
+   glides between segments; empty segments are muted dashes; invalid draws an error ring. */
+.mk-time-field,
+mk-time-field {
+  display: inline-block;
+  max-width: 100%;
+}
+
+:is(.mk-time-field, mk-time-field) [data-mk-segments] {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  min-height: 2.75rem;
+  padding: 0 0.75rem;
+  border-radius: 12px;
+  background: var(--mk-surface-3);
+  color: var(--mk-text);
+  font-variant-numeric: tabular-nums;
+  white-space: nowrap;
+  transition: box-shadow 0.2s ease;
+}
+
+:is(.mk-time-field, mk-time-field) [data-mk-segments]:focus-within {
+  box-shadow: 0 0 0 3px color-mix(in srgb, var(--mk-accent) 35%, transparent);
+}
+
+:is(.mk-time-field, mk-time-field) [data-mk-segments][aria-invalid='true'] {
+  box-shadow: 0 0 0 2px var(--mk-error, #d93025);
+}
+
+:is(.mk-time-field, mk-time-field) [data-mk-segments][aria-disabled='true'] {
+  opacity: 0.5;
+}
+
+:is(.mk-time-field, mk-time-field) [data-mk-segment] {
+  position: relative;
+  z-index: 1;
+  padding: 0.2rem 0.15rem;
+  border-radius: 6px;
+  caret-color: transparent;
+  outline: none;
+  cursor: default;
+}
+
+:is(.mk-time-field, mk-time-field) [data-mk-segment][data-mk-empty] {
+  color: var(--mk-muted);
+}
+
+:is(.mk-time-field, mk-time-field) [data-mk-segment]:focus {
+  color: var(--mk-on-accent-soft, var(--mk-text));
+}
+
+:is(.mk-time-field, mk-time-field) [data-mk-segment]::selection {
+  background: transparent;
+}
+
+:is(.mk-time-field, mk-time-field) [data-mk-segment-literal] {
+  padding: 0 0.05rem;
+  color: var(--mk-muted);
+}
+
+:is(.mk-time-field, mk-time-field) [data-mk-segment-focus] {
+  position: absolute;
+  top: 50%;
+  left: 0;
+  height: 1.75rem;
+  margin-top: -0.875rem;
+  border-radius: 6px;
+  background: var(--mk-accent-soft);
+  opacity: 0;
+  pointer-events: none;
+}
+
+/* Without motion the pill is not drawn: the focused segment gets the colour directly. */
+@media (prefers-reduced-motion: reduce) {
+  :is(.mk-time-field, mk-time-field) [data-mk-segment]:focus {
+    background: var(--mk-accent-soft);
+  }
+
+  :is(.mk-time-field, mk-time-field) [data-mk-segment-focus] {
+    display: none;
+  }
+
+  :is(.mk-time-field, mk-time-field) [data-mk-segments] {
+    transition: none;
+  }
+}

package/src/components/timeline/README.md

@@ -0,0 +1,57 @@
+# timeline
+
+Línea de tiempo para historiales de actividades, cambios y eventos: cada evento es un punto sobre un riel, con su hora («hace 2 h», con la fecha completa en el título; se actualiza cada minuto), un título, una descripción y un dato pequeño. El punto lleva un icono o el color de su estado: hecho, en curso (su anillo respira), pendiente (con borde punteado) o con error. El tramo recorrido del riel se rellena con el acento hasta el evento en curso.
+
+Al entrar en pantalla, el riel se dibuja desde el primer punto (.8 s, curva wipe) y los eventos aparecen en cascada saliendo de un blur, 60 ms entre uno y otro. `add()` mete un evento al principio o al final: los demás se deslizan para hacerle sitio (el riel los sigue), el nuevo entra desde un blur, su punto hace pop y un resaltado suave se apaga detrás de él. `update()` lo cambia en su sitio (un estado nuevo vuelve a hacer pop) y `remove()` lo pliega. Con `layout="alternate"`, cuando la línea de tiempo mide 520 px o más, los eventos se reparten a los dos lados del riel; `group` pone cada día como una etiqueta sobre el riel («Hoy», «Ayer», «Lunes, 16 de noviembre»).
+
+## HTML / Astro
+
+```html
+<!-- Eventos en JSON… -->
+<mk-timeline class="mk-timeline" group
+  events='[{"id":"1","title":"Pedido recibido","time":"2026-11-23T09:12","status":"done","icon":"✓"},
+           {"id":"2","title":"En camino","time":"2026-11-23T14:30","status":"current","description":"Salió de Monterrey"},
+           {"id":"3","title":"Entrega","status":"upcoming","meta":"Estimada: jueves"}]'></mk-timeline>
+
+<!-- …o escritos: el texto del <li> es el título y el <p>, la descripción. -->
+<mk-timeline class="mk-timeline">
+  <ol>
+    <li data-status="done" data-time="2026-11-20">Alta de la cuenta<p>Plan Pro, facturación mensual</p></li>
+    <li data-status="current" data-time="2026-11-21T10:00" data-icon="★">Primer proyecto</li>
+  </ol>
+</mk-timeline>
+
+<script>
+  const timeline = document.querySelector('mk-timeline');
+  timeline.add({ id: '4', title: 'Entregado', status: 'done', time: new Date() });
+</script>
+```
+
+## React
+
+```tsx
+<Timeline events={history} layout="alternate" group />
+```
+
+Cambiar `events` actualiza en su sitio: un evento nuevo en un extremo entra con su animación, uno que cambia de estado vuelve a colorear su punto y uno que desaparece se pliega.
+
+## Opciones
+
+| Opción | Atributo | Por defecto | Qué hace |
+|---|---|---|---|
+| `events` | `events` (JSON) | los `<li>` escritos | `{ id, title, description?, time?, status?, icon?, meta? }[]`; `status`: `done`, `current`, `upcoming` o `error`. |
+| `layout` | `layout` | `'start'` | `'alternate'` reparte los eventos a los dos lados del riel cuando la línea mide 520 px o más. |
+| `group` | `group` | `false` | Un encabezado por día. |
+| `relative` | `relative` | `true` | Horas relativas («hace 5 min»); `false` muestra fecha y hora. |
+| `locale` | `locale` | el `lang` más cercano | Idioma de las fechas. |
+| `label` | `label` | `'Historial'` | Nombre accesible de la lista. |
+
+`time` acepta un `Date`, una cadena ISO (`2026-11-23` o `2026-11-23T09:12`) o una marca de tiempo.
+
+## API
+
+`add(event, 'start' | 'end')`, `update(id, cambios)`, `remove(id)`, `setEvents(events)`, `events`, `destroy()`.
+
+## Accesibilidad
+
+Una lista ordenada con nombre propio; cada hora es un `<time datetime>` con la fecha completa en su título, y el estado de cada evento («En curso», «Pendiente», «Con error») se lee después del título. Los encabezados de día son de presentación. Con movimiento reducido no hay animación de entrada y los cambios ocurren sin transición.

package/src/components/timeline/element.ts

@@ -0,0 +1,31 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createTimeline, type TimelineEvent, type TimelineInstance } from './engine';
+
+/**
+ * <mk-timeline class="mk-timeline" events='[{"id":"1","title":"Pedido recibido","time":"2026-11-23T09:12","status":"done"}]'>
+ * </mk-timeline> — or authored <ol><li data-status data-time>Title<p>Description</p></li></ol>.
+ */
+export class MkTimelineElement extends MkElement<TimelineInstance> {
+  static options: Record<string, OptionType> = { events: 'json', layout: 'string', group: 'boolean', relative: 'boolean', locale: 'string', label: 'string' };
+
+  protected create(options: Record<string, unknown>) {
+    return createTimeline(this, options);
+  }
+
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.instance) return;
+    if (name === 'events') {
+      try {
+        this.instance.setEvents(JSON.parse(next ?? '[]') as TimelineEvent[]);
+      } catch {
+        // Malformed JSON: keep the current events.
+      }
+    } else super.attributeChangedCallback(name, previous, next);
+  }
+
+  add(event: TimelineEvent, at?: 'start' | 'end') {
+    this.instance?.add(event, at);
+  }
+}
+
+export const defineTimeline = () => defineElement('mk-timeline', MkTimelineElement);

package/src/components/timeline/engine.ts

@@ -0,0 +1,300 @@
+import { gsap, EASE, Flip, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { TIMING } from '../../core/timing';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { dayKey, fromJson } from '../../core/dates';
+import { dayLabel, everyMinute, fullTime, relativeTime, toTime, type TimeInput } from '../../core/relative-time';
+import { blurIn, collapse } from '../../motion/micro';
+
+/*
+ * Timeline: events in order along a rail — dots with an icon or a state, a
+ * time ("hace 2 h", the full date in its title; refreshed every minute), a
+ * title, a description and small meta. When it comes into view the rail draws
+ * itself from the first dot (.8 s, wipe) and the events cascade in out of a
+ * blur (60 ms apart); the done stretch of the rail is filled in the accent up
+ * to the current event, whose dot breathes. add() drops an event in at the
+ * start or the end: the others glide to make room (layout reflow, the rail
+ * following), it comes in out of a blur, its dot pops and a soft highlight
+ * fades behind it; update() changes one in place (a new state pops its dot);
+ * remove() folds one away. 'alternate' puts the events on both sides of the
+ * rail when there is room; `group` heads each day with a chip on the rail.
+ */
+
+export type TimelineStatus = 'done' | 'current' | 'upcoming' | 'error';
+
+export interface TimelineEvent {
+  id: string;
+  title: string;
+  description?: string;
+  time?: TimeInput;
+  status?: TimelineStatus;
+  /** A short glyph in the dot (an emoji or one or two letters). */
+  icon?: string;
+  /** Small text under it (an author, a place). */
+  meta?: string;
+}
+
+export interface TimelineOptions {
+  events?: TimelineEvent[];
+  /** 'start' (default): the rail on the left; 'alternate': both sides on wide screens. */
+  layout?: 'start' | 'alternate';
+  /** A heading for each day (default false). */
+  group?: boolean;
+  /** Times as "hace 2 h", refreshed every minute (default true); false shows the date and time. */
+  relative?: boolean;
+  locale?: string;
+  /** Accessible name of the list (default 'Historial'). */
+  label?: string;
+}
+
+export interface TimelineInstance extends Instance {
+  add(event: TimelineEvent, at?: 'start' | 'end'): void;
+  update(id: string, patch: Partial<Omit<TimelineEvent, 'id'>>): void;
+  remove(id: string): void;
+  setEvents(events: TimelineEvent[]): void;
+  readonly events: TimelineEvent[];
+}
+
+const STATUS_LABEL: Record<TimelineStatus, string> = { done: 'Hecho', current: 'En curso', upcoming: 'Pendiente', error: 'Con error' };
+
+/** Events written as <li data-status data-time data-icon>Title<p>description</p></li>. */
+const readAuthored = (root: HTMLElement): TimelineEvent[] =>
+  [...root.querySelectorAll<HTMLElement>(':scope > ol > li, :scope > ul > li')].map((item, i) => {
+    const description = item.querySelector('p')?.textContent?.trim();
+    const title = [...item.childNodes].filter((node) => node.nodeType === Node.TEXT_NODE || (node instanceof HTMLElement && node.tagName !== 'P')).map((node) => node.textContent).join('').trim();
+    return {
+      id: item.id || `e${i}`,
+      title,
+      description,
+      time: item.dataset.time,
+      status: item.dataset.status as TimelineStatus | undefined,
+      icon: item.dataset.icon,
+      meta: item.dataset.meta,
+    };
+  });
+
+export function createTimeline(root: HTMLElement | null, options: TimelineOptions = {}): TimelineInstance {
+  if (!root) return inert({ add() {}, update() {}, remove() {}, setEvents() {}, events: [] });
+  registerMotion();
+  const scope = createScope();
+  const locale = options.locale ?? root.closest('[lang]')?.getAttribute('lang') ?? 'es';
+  const relative = options.relative !== false;
+  // JSON text too (data-mk-events through autoInit).
+  let events = (fromJson(options.events) ?? readAuthored(root)).map((event) => ({ ...event }));
+  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);
+  };
+
+  // Authored markup stays, out of sight; the engine draws its own list.
+  const holder = document.createElement('div');
+  holder.hidden = true;
+  holder.append(...root.childNodes);
+  const list = document.createElement('ol');
+  list.dataset.mkTimelineList = '';
+  list.setAttribute('aria-label', options.label ?? 'Historial');
+  const rail = document.createElement('span');
+  rail.dataset.mkTlRail = '';
+  rail.setAttribute('aria-hidden', 'true');
+  const progress = document.createElement('span');
+  progress.dataset.mkTlProgress = '';
+  rail.append(progress);
+  const wrap = document.createElement('div');
+  wrap.dataset.mkTlWrap = '';
+  wrap.append(rail, list);
+  root.append(wrap);
+  scope.add(() => {
+    for (const effect of effects) effect.kill();
+    effects.clear();
+    wrap.remove();
+    root.append(...holder.childNodes);
+  });
+  scope.attr(root, 'data-mk-layout', options.layout === 'alternate' ? 'alternate' : 'start');
+  scope.attr(root, 'data-mk-ready', '');
+
+  const timeText = (date: Date) => (relative ? relativeTime(date, new Date(), locale) : fullTime(date, locale));
+
+  const item = (event: TimelineEvent) => {
+    const li = document.createElement('li');
+    li.dataset.mkTlItem = '';
+    li.dataset.id = event.id;
+    li.dataset.status = event.status ?? 'done';
+    const dot = document.createElement('span');
+    dot.dataset.mkTlDot = '';
+    dot.setAttribute('aria-hidden', 'true');
+    dot.textContent = event.icon ?? '';
+    const body = document.createElement('div');
+    body.dataset.mkTlBody = '';
+    const date = toTime(event.time);
+    if (date) {
+      const time = document.createElement('time');
+      time.dataset.mkTlTime = '';
+      time.dateTime = date.toISOString();
+      time.title = fullTime(date, locale);
+      time.textContent = timeText(date);
+      body.append(time);
+    }
+    const title = document.createElement('strong');
+    title.dataset.mkTlTitle = '';
+    title.textContent = event.title;
+    body.append(title);
+    if (event.status && event.status !== 'done') {
+      const state = document.createElement('span');
+      state.className = 'mk-sr-only';
+      state.textContent = ` (${STATUS_LABEL[event.status]})`;
+      title.append(state);
+    }
+    if (event.description) {
+      const description = document.createElement('p');
+      description.dataset.mkTlDescription = '';
+      description.textContent = event.description;
+      body.append(description);
+    }
+    if (event.meta) {
+      const meta = document.createElement('span');
+      meta.dataset.mkTlMeta = '';
+      meta.textContent = event.meta;
+      body.append(meta);
+    }
+    li.append(dot, body);
+    return li;
+  };
+
+  const heading = (date: Date) => {
+    const li = document.createElement('li');
+    li.dataset.mkTlDay = '';
+    li.dataset.day = dayKey(date);
+    li.setAttribute('role', 'presentation');
+    li.dataset.flipId = `day-${li.dataset.day}`;
+    li.textContent = dayLabel(date, new Date(), locale);
+    return li;
+  };
+
+  /** The rail runs from the first dot to the last; its filled part reaches the current (or last done) event. */
+  const measureRail = () => {
+    const dots = [...list.querySelectorAll<HTMLElement>('[data-mk-tl-dot]')];
+    if (!dots.length) {
+      rail.hidden = true;
+      return;
+    }
+    rail.hidden = false;
+    // Centres measured against the wrapper, whatever positions the items.
+    const base = wrap.getBoundingClientRect().top;
+    const centre = (dot: HTMLElement) => {
+      const box = dot.getBoundingClientRect();
+      return box.top - base + box.height / 2;
+    };
+    const top = centre(dots[0]!);
+    const bottom = centre(dots[dots.length - 1]!);
+    rail.style.top = `${top}px`;
+    rail.style.height = `${Math.max(0, bottom - top)}px`;
+    const reached = [...list.querySelectorAll<HTMLElement>('[data-mk-tl-item]')].filter((li) => li.dataset.status === 'done' || li.dataset.status === 'current');
+    const last = reached[reached.length - 1]?.querySelector<HTMLElement>('[data-mk-tl-dot]');
+    progress.style.height = `${last ? Math.max(0, centre(last) - top) : 0}px`;
+  };
+  const itemOf = (id: string) => [...list.querySelectorAll<HTMLElement>('[data-mk-tl-item]')].find((li) => li.dataset.id === id) ?? null;
+
+  const render = () => {
+    const nodes: HTMLElement[] = [];
+    let day = '';
+    events.forEach((event, i) => {
+      const date = toTime(event.time);
+      if (options.group && date && dayKey(date) !== day) {
+        day = dayKey(date);
+        nodes.push(heading(date));
+      }
+      const element = item(event);
+      // 'alternate': the events take turns on each side of the rail.
+      element.dataset.side = i % 2 ? 'end' : 'start';
+      element.dataset.flipId = event.id;
+      nodes.push(element);
+    });
+    list.replaceChildren(...nodes);
+    measureRail();
+  };
+
+  const refreshTimes = () => {
+    for (const time of list.querySelectorAll<HTMLTimeElement>('[data-mk-tl-time]')) time.textContent = timeText(new Date(time.dateTime));
+    if (options.group) for (const day of list.querySelectorAll<HTMLElement>('[data-mk-tl-day]')) day.textContent = dayLabel(toTime(day.dataset.day!)!, new Date(), locale);
+  };
+  if (relative) scope.add(everyMinute(refreshTimes));
+  if (typeof ResizeObserver === 'function') scope.observe(new ResizeObserver(() => measureRail())).observe(list);
+
+  /** The entrance: the rail draws, the events cascade in. */
+  const enter = () => {
+    if (reduced()) return;
+    keep(gsap.fromTo(rail, { scaleY: 0 }, { scaleY: 1, transformOrigin: '50% 0%', duration: 0.8, ease: EASE.wipe, clearProps: 'transform' }));
+    keep(blurIn([...list.children], { from: 'rise', stagger: 0.06 }));
+  };
+
+  render();
+  if (typeof IntersectionObserver === 'function' && !reduced()) {
+    gsap.set([rail, ...list.children], { opacity: 0 });
+    const observer = scope.observe(
+      new IntersectionObserver((entries) => {
+        if (!entries.some((entry) => entry.isIntersecting)) return;
+        observer.disconnect();
+        gsap.set([rail, ...list.children], { clearProps: 'opacity' });
+        enter();
+      }, { threshold: 0.15 }),
+    );
+    observer.observe(root);
+  }
+
+  return {
+    add(event, at = 'end') {
+      if (scope.disposed) return;
+      // What is there glides to make room (the rail follows); the new event and a new day come in.
+      const state = reduced() ? null : Flip.getState([...list.children]);
+      events = at === 'start' ? [{ ...event }, ...events] : [...events, { ...event }];
+      render();
+      const added = itemOf(event.id);
+      if (!added || !state) return;
+      added.setAttribute('data-mk-tl-fresh', '');
+      scope.timeout(() => added.removeAttribute('data-mk-tl-fresh'), 1800);
+      keep(
+        Flip.from(state, {
+          targets: [...list.children],
+          duration: TIMING.layoutTravel,
+          ease: EASE.layoutReflow,
+          onUpdate: measureRail,
+          onComplete: measureRail,
+          onEnter: (entering) =>
+            gsap.fromTo(entering, { opacity: 0, y: at === 'start' ? -16 : 16, filter: 'blur(10px)' }, { opacity: 1, y: 0, filter: 'blur(0px)', duration: 0.45, ease: 'power2.out', clearProps: 'opacity,transform,filter' }),
+        }),
+      );
+      const dot = added.querySelector<HTMLElement>('[data-mk-tl-dot]')!;
+      keep(gsap.fromTo(dot, { scale: 0 }, { scale: 1, duration: 0.4, delay: 0.12, ease: EASE.pop, clearProps: 'transform' }));
+    },
+    update(id, patch) {
+      const event = events.find((entry) => entry.id === id);
+      if (!event || scope.disposed) return;
+      const statusChanged = patch.status && patch.status !== event.status;
+      Object.assign(event, patch);
+      render();
+      const dot = itemOf(id)?.querySelector<HTMLElement>('[data-mk-tl-dot]');
+      if (statusChanged && dot && !reduced()) keep(gsap.fromTo(dot, { scale: 0.6 }, { scale: 1, duration: 0.4, ease: EASE.pop, clearProps: 'transform' }));
+    },
+    remove(id) {
+      const element = itemOf(id);
+      events = events.filter((event) => event.id !== id);
+      if (!element) return render();
+      if (reduced()) return render();
+      keep(collapse(element, { onComplete: render }));
+    },
+    setEvents(next) {
+      if (scope.disposed) return;
+      events = next.map((event) => ({ ...event }));
+      render();
+      if (!reduced()) keep(blurIn([...list.children], { from: 'rise', stagger: 0.04 }));
+    },
+    get events() {
+      return events.map((event) => ({ ...event }));
+    },
+    destroy: () => scope.dispose(),
+  };
+}