@yewdiel21/motion-kit 0.9.1 → 0.14.0

package/src/components/tag-input/tag-input.css

@@ -0,0 +1,243 @@
+/* tag-input — a 12 px field on surface-3 with 8 px chips and the input; the reason a tag was refused sits under it in
+   the error colour. The chips and the listbox rules below are shared with multi-select (each stylesheet works alone). */
+.mk-tag-input,
+mk-tag-input {
+  display: block;
+  min-width: 0;
+}
+
+[data-mk-tag-field] {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.35rem;
+  box-sizing: border-box;
+  min-height: 2.75rem;
+  padding: 0.35rem 0.5rem;
+  border-radius: 12px;
+  background: var(--mk-surface-3);
+  color: var(--mk-text);
+  cursor: text;
+  transition: box-shadow 0.2s ease;
+}
+
+[data-mk-tag-field]:focus-within {
+  box-shadow: 0 0 0 3px color-mix(in srgb, var(--mk-accent) 35%, transparent);
+}
+
+[data-mk-tag-field]:has([aria-invalid='true']) {
+  box-shadow: 0 0 0 2px var(--mk-error, #c62828);
+}
+
+[data-mk-tag-input] {
+  flex: 1;
+  min-width: 8ch;
+  height: 1.75rem;
+  padding: 0 0.25rem;
+  border: 0;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  outline: none;
+}
+
+[data-mk-tag-input]::placeholder {
+  color: var(--mk-muted);
+}
+
+[data-mk-tag-error] {
+  margin: 0.4rem 0 0;
+  color: var(--mk-error, #c62828);
+  font-size: 0.8125rem;
+}
+
+[data-mk-tag-error][hidden] {
+  display: none;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-mk-tag-field] {
+    transition: none;
+  }
+}
+
+/* Chips (core/chips.ts): 8 px, accent-soft, a round remove button; the armed one (next Backspace) gets a ring. */
+[data-mk-chips] {
+  display: contents;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+[data-mk-chip] {
+  display: inline-flex;
+  flex: none;
+  align-items: center;
+  gap: 0.15rem;
+  box-sizing: border-box;
+  max-width: 100%;
+  height: 1.75rem;
+  padding: 0 0.2rem 0 0.6rem;
+  overflow: hidden;
+  border-radius: 8px;
+  background: var(--mk-accent-soft);
+  color: var(--mk-on-accent-soft, var(--mk-text));
+  font-size: 0.8125rem;
+  font-weight: 500;
+  white-space: nowrap;
+  outline: none;
+  transition: box-shadow 0.2s ease;
+}
+
+[data-mk-chip-label] {
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+[data-mk-chip]:focus-visible,
+[data-mk-chip][data-mk-armed] {
+  box-shadow: 0 0 0 2px var(--mk-accent);
+}
+
+[data-mk-chip-remove] {
+  display: grid;
+  flex: none;
+  place-items: center;
+  width: 1.25rem;
+  height: 1.25rem;
+  padding: 0;
+  border: 0;
+  border-radius: 50%;
+  background: transparent;
+  color: inherit;
+  cursor: pointer;
+  opacity: 0.7;
+  transition: background-color 0.15s ease, opacity 0.15s ease;
+}
+
+[data-mk-chip-remove]:hover {
+  background: color-mix(in srgb, currentColor 14%, transparent);
+  opacity: 1;
+}
+
+/* Listbox (core/listbox.ts): a 16 px panel in the top layer under the field; the active option sits on a pill. */
+[data-mk-listbox] {
+  position: fixed;
+  inset: auto;
+  z-index: 2147482000;
+  box-sizing: border-box;
+  max-height: min(18rem, 50vh);
+  margin: 0;
+  padding: 0.35rem;
+  overflow: auto;
+  border: 1px solid var(--mk-outline-soft);
+  border-radius: 16px;
+  background: var(--mk-surface-1);
+  color: var(--mk-text);
+  box-shadow: 0 16px 40px -14px color-mix(in srgb, var(--mk-shadow-color, #000) 35%, transparent);
+  font: 0.9375rem/1.3 var(--mk-font, system-ui, sans-serif);
+  overscroll-behavior: contain;
+}
+
+[data-mk-listbox][hidden] {
+  display: none;
+}
+
+[data-mk-listbox-items] {
+  position: relative;
+  display: grid;
+  gap: 2px;
+}
+
+[data-mk-listbox-pill] {
+  position: absolute;
+  top: 0.35rem;
+  right: 0.35rem;
+  left: 0.35rem;
+  border-radius: 10px;
+  background: var(--mk-accent-soft);
+  opacity: 0;
+  pointer-events: none;
+}
+
+[data-mk-option] {
+  position: relative;
+  z-index: 1;
+  display: flex;
+  align-items: center;
+  gap: 0.6rem;
+  min-height: 2.5rem;
+  padding: 0 0.75rem;
+  border-radius: 10px;
+  cursor: pointer;
+  user-select: none;
+}
+
+[data-mk-option][aria-disabled='true'] {
+  color: var(--mk-muted);
+  cursor: not-allowed;
+  opacity: 0.55;
+}
+
+[data-mk-option-label] {
+  flex: 1;
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
+
+[data-mk-option-label] mark {
+  background: transparent;
+  color: inherit;
+  font-weight: 700;
+  text-decoration: underline;
+  text-decoration-color: var(--mk-accent);
+  text-decoration-thickness: 2px;
+  text-underline-offset: 3px;
+}
+
+[data-mk-option-hint] {
+  color: var(--mk-muted);
+  font-size: 0.8125rem;
+}
+
+[data-mk-option-check] {
+  display: grid;
+  flex: none;
+  place-items: center;
+  width: 1.15rem;
+  height: 1.15rem;
+  border: 1.5px solid var(--mk-outline);
+  border-radius: 5px;
+  color: transparent;
+  transition: background-color 0.2s ease, border-color 0.2s ease, color 0.2s ease;
+}
+
+[data-mk-option][aria-selected='true'] [data-mk-option-check] {
+  border-color: var(--mk-accent);
+  background: var(--mk-accent);
+  color: var(--mk-on-accent);
+}
+
+[data-mk-listbox-group] {
+  padding: 0.6rem 0.75rem 0.25rem;
+  color: var(--mk-muted);
+  font-size: 0.75rem;
+  font-weight: 600;
+  letter-spacing: 0.02em;
+  text-transform: uppercase;
+}
+
+[data-mk-listbox-empty] {
+  padding: 0.75rem;
+  color: var(--mk-muted);
+  font-size: 0.875rem;
+  text-align: center;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-mk-chip],
+  [data-mk-chip-remove],
+  [data-mk-option-check] {
+    transition: none;
+  }
+}

package/src/components/time-field/README.md

@@ -0,0 +1,54 @@
+# time-field
+
+Hora por segmentos: hora, minutos (y segundos) en el orden del idioma, con a. m./p. m. donde el idioma escribe 12 horas (`es`: 24 h; `en-US`: 12 h). El valor siempre es texto de 24 h («13:05»).
+
+Cada segmento es un `role="spinbutton"`. Las flechas cambian el valor con vuelta y los dígitos ruedan en la dirección del cambio; al teclear se rellena el segmento y se pasa al siguiente; una píldora se desliza tras el segmento con foco (curva swing). En el móvil se abre el teclado numérico (`inputmode="numeric"`), pero el componente escribe siempre el texto: no se cuela nada raro. `min` y `max` marcan el grupo como no válido (una sacudida al pasar a no válido), aunque el valor se sigue informando, como en un input nativo.
+
+## HTML / Astro
+
+```html
+<mk-time-field class="mk-time-field" value="09:30" minute-step="15" min="09:00" max="20:00" name="hora"></mk-time-field>
+<mk-time-field class="mk-time-field" locale="en-US" seconds></mk-time-field>
+```
+
+## React
+
+```tsx
+const [time, setTime] = useState<string | null>('09:30');
+<TimeField value={time} onChange={setTime} minuteStep={15} />
+```
+
+## Opciones
+
+| Opción | Atributo | Por defecto | Qué hace |
+|---|---|---|---|
+| `value` | `value` | vacío | `'HH:MM'` o `'HH:MM:SS'` (24 h). |
+| `locale` | `locale` | `lang` de la página, o `es` | Orden de los segmentos y formato de 12/24 h. |
+| `hourCycle` | `hour-cycle` | el del idioma | `12` o `24`. |
+| `seconds` | `seconds` | `false` | Añade los segundos. |
+| `minuteStep` | `minute-step` | `1` | Paso de las flechas en minutos (y segundos). |
+| `min`, `max` | `min`, `max` | — | `'HH:MM'`; fuera de rango marca `aria-invalid`. |
+| `label` | `label` | `'Hora'` | Nombre accesible del grupo. |
+| `name` | `name` | — | Input oculto con el texto de 24 h. |
+| `disabled`, `readOnly` | `disabled`, `read-only` | `false` | Estados. |
+| `onChange(value)` | — | — | Cada cambio; `null` mientras falte algún segmento. |
+
+## Teclado
+
+| Tecla | Acción |
+|---|---|
+| ↑ / ↓ | Cambia el segmento (con vuelta: 23 → 00) |
+| RePág / AvPág | Saltos grandes (3 horas, 15 minutos) |
+| Inicio / Fin | Mínimo / máximo del segmento |
+| ← / → | Segmento anterior / siguiente |
+| Dígitos | Rellenan el segmento y pasan al siguiente |
+| Retroceso / Supr | Vacía el segmento; si ya está vacío, vuelve al anterior |
+| «a» / «p» | a. m. / p. m. |
+
+## API y eventos
+
+`setValue(value | null, animate = true)`, `focus()`, `value`, `destroy()`. Evento `mk:change` con `{ value }`.
+
+## Estilos
+
+Campo de 12 px sobre `--mk-surface-3`, cifras tabulares, píldora de foco de 6 px en `--mk-accent-soft`; los segmentos vacíos se ven atenuados; no válido dibuja un anillo de `--mk-error`. Con movimiento reducido no hay rodillo ni píldora: el segmento con foco toma el color directamente.

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

@@ -0,0 +1,38 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createTimeField, type TimeFieldInstance } from './engine';
+
+/**
+ * <mk-time-field class="mk-time-field" value="09:30" minute-step="15" name="hora"></mk-time-field>
+ * Emits mk:change ({value}: 24 h text, null while incomplete).
+ */
+export class MkTimeFieldElement extends MkElement<TimeFieldInstance> {
+  static options: Record<string, OptionType> = {
+    value: 'string',
+    locale: 'string',
+    hourCycle: 'number',
+    seconds: 'boolean',
+    minuteStep: 'number',
+    min: 'string',
+    max: 'string',
+    label: 'string',
+    name: 'string',
+    disabled: 'boolean',
+    readOnly: 'boolean',
+  };
+
+  protected create(options: Record<string, unknown>) {
+    return createTimeField(this, options);
+  }
+
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.instance) return;
+    if (name === 'value') this.instance.setValue(next);
+    else super.attributeChangedCallback(name, previous, next);
+  }
+
+  get value() {
+    return this.instance?.value ?? null;
+  }
+}
+
+export const defineTimeField = () => defineElement('mk-time-field', MkTimeFieldElement);

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);