@yewdiel21/motion-kit 0.10.0 → 0.14.0

package/src/components/tag-input/engine.ts

@@ -0,0 +1,313 @@
+import { registerMotion } from '../../core/gsap';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { createChips } from '../../core/chips';
+import { createListbox, filterOptions } from '../../core/listbox';
+import { shake } from '../../motion/micro';
+
+/*
+ * Tag input: free tags as chips, with suggestions. Enter or a comma adds what
+ * was typed (or the highlighted suggestion); pasting "a, b; c" adds each, one
+ * after another. New chips pop in and removed ones fold away
+ * (core/chips.ts); the suggestions open out of the field with a gliding
+ * active pill and the typed letters marked (core/listbox.ts). A duplicate
+ * rings the chip that already has it; a tag that `validate`, `restrict` or
+ * `max` refuses shakes the field and says why under it (aria-invalid, the
+ * message described by the input). Backspace in an empty input arms the last
+ * chip, then removes it; ← reaches the chips.
+ */
+
+export interface TagInputOptions {
+  value?: string[];
+  /** Offered while typing (fuzzy, accents ignored). */
+  suggestions?: string[];
+  placeholder?: string;
+  /** Accessible name (default: the authored <label>, else 'Etiquetas'). */
+  label?: string;
+  /** Hidden inputs name[] for forms. */
+  name?: string;
+  max?: number;
+  /** Only tags from the suggestions. */
+  restrict?: boolean;
+  allowDuplicates?: boolean;
+  /** Return a message to refuse a tag. */
+  validate?: (tag: string, tags: string[]) => string | null | undefined | void;
+  /** Clean a tag before adding it (default: trim and collapse spaces). */
+  transform?: (tag: string) => string;
+  disabled?: boolean;
+  onChange?: (tags: string[]) => void;
+}
+
+export interface TagInputInstance extends Instance {
+  setValue(tags: string[], notify?: boolean): void;
+  /** Add a tag as if typed; false when refused. */
+  add(tag: string): boolean;
+  remove(tag: string): void;
+  setSuggestions(suggestions: string[]): void;
+  readonly value: string[];
+}
+
+const fold = (text: string) => text.normalize('NFD').replace(/[̀-ͯ]/g, '').toLowerCase();
+const SEPARATORS = /[,;\n]+/;
+let sequence = 0;
+
+export function createTagInput(root: HTMLElement | null, settings: TagInputOptions = {}): TagInputInstance {
+  if (!root) return inert({ setValue() {}, add: () => false, remove() {}, setSuggestions() {}, value: [] });
+  registerMotion();
+  const scope = createScope();
+  const uid = `mk-tags-${++sequence}`;
+  const max = Number.isFinite(settings.max) && settings.max! > 0 ? Math.floor(settings.max!) : Infinity;
+  const clean = settings.transform ?? ((tag: string) => tag.replace(/\s+/g, ' ').trim());
+  let suggestions = [...(settings.suggestions ?? [])];
+  let tags: string[] = [];
+  const labelText = settings.label ?? root.querySelector('label')?.textContent?.trim() ?? 'Etiquetas';
+
+  const field = document.createElement('div');
+  field.dataset.mkTagField = '';
+  const chips = createChips({ disabled: settings.disabled, onRemove: (tag) => remove(tag, true), onExit: () => input.focus() });
+  scope.add(() => chips.destroy());
+  const input = document.createElement('input');
+  input.type = 'text';
+  input.dataset.mkTagInput = '';
+  input.setAttribute('role', 'combobox');
+  input.setAttribute('aria-autocomplete', 'list');
+  input.setAttribute('aria-label', labelText);
+  input.setAttribute('aria-describedby', `${uid}-error`);
+  input.autocomplete = 'off';
+  input.spellcheck = false;
+  input.enterKeyHint = 'enter';
+  input.disabled = Boolean(settings.disabled);
+  field.append(chips.element, input);
+  const error = document.createElement('p');
+  error.id = `${uid}-error`;
+  error.dataset.mkTagError = '';
+  error.hidden = true;
+  const status = document.createElement('span');
+  status.className = 'mk-sr-only';
+  status.setAttribute('role', 'status');
+  const hiddenHost = document.createElement('span');
+  hiddenHost.hidden = true;
+  root.append(field, error, status, hiddenHost);
+  scope.add(() => {
+    field.remove();
+    error.remove();
+    status.remove();
+    hiddenHost.remove();
+  });
+  scope.attr(root, 'data-mk-ready', '');
+
+  const listbox = createListbox({
+    input,
+    anchor: field,
+    host: root,
+    label: 'Sugerencias',
+    emptyLabel: 'Sin sugerencias',
+    onPick: (option) => {
+      if (add(option.value, true)) {
+        input.value = '';
+        listbox.hide();
+      }
+    },
+  });
+  scope.add(() => listbox.destroy());
+
+  const placeholder = () => {
+    input.placeholder = tags.length >= max ? '' : (settings.placeholder ?? 'Añadir etiqueta…');
+  };
+  const showError = (message: string | null) => {
+    error.textContent = message ?? '';
+    error.hidden = !message;
+    if (message) input.setAttribute('aria-invalid', 'true');
+    else input.removeAttribute('aria-invalid');
+  };
+  const sync = (animate: boolean) => {
+    chips.set(tags.map((tag) => ({ value: tag, label: tag })), animate);
+    placeholder();
+    if (settings.name) {
+      hiddenHost.replaceChildren(
+        ...tags.map((tag) => {
+          const hidden = document.createElement('input');
+          hidden.type = 'hidden';
+          hidden.name = `${settings.name}[]`;
+          hidden.value = tag;
+          return hidden;
+        }),
+      );
+    }
+  };
+  const emit = () => {
+    settings.onChange?.([...tags]);
+    root.dispatchEvent(new CustomEvent('mk:change', { bubbles: true, detail: { value: [...tags] } }));
+  };
+
+  /** The suggestions not chosen yet that match the typed text (all of them for an empty query). */
+  const available = (query: string) => {
+    const chosen = new Set(tags.map(fold));
+    return filterOptions(
+      suggestions.filter((tag) => !chosen.has(fold(tag))).map((tag) => ({ value: tag, label: tag })),
+      query,
+    ).slice(0, 50);
+  };
+  /** While typing: matching suggestions, or none (a new tag needs no empty list). */
+  const offer = () => {
+    const query = input.value;
+    const matches = query.trim() && suggestions.length ? available(query) : [];
+    if (!matches.length) return listbox.hide();
+    listbox.show(matches, query);
+  };
+
+  /** Add one tag; false (and why, shaken) when refused. */
+  const add = (raw: string, animate: boolean, notify = true) => {
+    const tag = clean(raw);
+    if (!tag || settings.disabled) return false;
+    const refuse = (message: string) => {
+      showError(message);
+      shake(field);
+      return false;
+    };
+    const twin = tags.find((existing) => fold(existing) === fold(tag));
+    if (twin && !settings.allowDuplicates) {
+      chips.flash(twin);
+      status.textContent = `Ya existe «${twin}»`;
+      return false;
+    }
+    if (tags.length >= max) return refuse(`Máximo ${max} ${max === 1 ? 'etiqueta' : 'etiquetas'}`);
+    const known = suggestions.find((suggestion) => fold(suggestion) === fold(tag));
+    if (settings.restrict && !known) return refuse(`«${tag}» no está en la lista`);
+    const message = settings.validate?.(known ?? tag, [...tags]);
+    if (message) return refuse(message);
+    tags = [...tags, known ?? tag];
+    showError(null);
+    chips.arm(null);
+    sync(animate);
+    status.textContent = `${known ?? tag} añadida`;
+    if (notify) emit();
+    return true;
+  };
+
+  const remove = (tag: string, notify: boolean) => {
+    if (!tags.includes(tag) || settings.disabled) return;
+    tags = tags.filter((existing) => existing !== tag);
+    chips.arm(null);
+    sync(true);
+    status.textContent = `${tag} quitada`;
+    if (notify) emit();
+  };
+
+  const commit = () => {
+    if (!input.value.trim()) return false;
+    if (add(input.value, true)) {
+      input.value = '';
+      listbox.hide();
+      return true;
+    }
+    return false;
+  };
+
+  scope.on(field, 'pointerdown', (event) => {
+    const target = event.target as Element | null;
+    if (target?.closest('[data-mk-chip-remove]')) return;
+    if (target !== input) event.preventDefault();
+    input.focus();
+  });
+  scope.on(input, 'input', () => {
+    showError(null);
+    chips.arm(null);
+    // A typed separator (mobile keyboards have no key events for it) commits what came before.
+    if (SEPARATORS.test(input.value)) {
+      const parts = input.value.split(SEPARATORS);
+      const rest = parts.pop() ?? '';
+      for (const part of parts) add(part, true);
+      input.value = rest;
+    }
+    offer();
+  });
+  scope.on(input, 'paste', (event) => {
+    const text = (event as ClipboardEvent).clipboardData?.getData('text') ?? '';
+    if (!SEPARATORS.test(text)) return;
+    event.preventDefault();
+    const parts = text.split(SEPARATORS).map(clean).filter(Boolean);
+    let added = 0;
+    for (const part of parts) if (add(part, true, false)) added++;
+    if (added) emit();
+  });
+  scope.on(input, 'keydown', (event) => {
+    const key = event as KeyboardEvent;
+    switch (key.key) {
+      case 'Enter':
+        if (listbox.isOpen && listbox.active) {
+          key.preventDefault();
+          listbox.pick();
+        } else if (input.value.trim()) {
+          key.preventDefault();
+          commit();
+        }
+        return;
+      case ',':
+      case ';':
+        key.preventDefault();
+        commit();
+        return;
+      case 'ArrowDown':
+      case 'ArrowUp':
+        if (!suggestions.length) return;
+        key.preventDefault();
+        if (!listbox.isOpen) listbox.show(available(input.value), input.value);
+        listbox.move(key.key === 'ArrowDown' ? 1 : -1);
+        return;
+      case 'Escape':
+        if (listbox.isOpen) {
+          key.preventDefault();
+          listbox.hide();
+        }
+        return;
+      case 'Backspace':
+        if (input.value || !tags.length) return;
+        key.preventDefault();
+        if (chips.armed) remove(chips.armed, true);
+        else chips.arm(tags[tags.length - 1]!);
+        return;
+      case 'ArrowLeft':
+        if (input.selectionStart === 0 && input.selectionEnd === 0 && chips.focusLast()) {
+          key.preventDefault();
+          listbox.hide();
+        }
+        return;
+      case 'Tab':
+        listbox.hide();
+        return;
+    }
+  });
+  scope.on(input, 'blur', () => {
+    chips.arm(null);
+    listbox.hide();
+  });
+
+  for (const tag of settings.value ?? []) add(tag, false, false);
+  sync(false);
+
+  return {
+    setValue(next, notify = false) {
+      if (scope.disposed) return;
+      tags = [];
+      for (const tag of next) {
+        const cleaned = clean(tag);
+        if (cleaned && (settings.allowDuplicates || !tags.some((existing) => fold(existing) === fold(cleaned)))) tags.push(cleaned);
+      }
+      tags = tags.slice(0, max);
+      showError(null);
+      sync(true);
+      if (notify) emit();
+    },
+    add: (tag) => add(tag, true),
+    remove: (tag) => remove(tag, true),
+    setSuggestions(next) {
+      suggestions = [...next];
+      if (listbox.isOpen) offer();
+    },
+    get value() {
+      return [...tags];
+    },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/tag-input/react.tsx

@@ -0,0 +1,54 @@
+'use client';
+import { useRef, type HTMLAttributes } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createTagInput, type TagInputInstance, type TagInputOptions } from './engine';
+
+export interface TagInputProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue'>, TagInputOptions {
+  /** Controlled tags; without it the field keeps its own (defaultValue). */
+  value?: string[];
+  defaultValue?: string[];
+}
+
+/** <TagInput value={tags} onChange={setTags} suggestions={known} max={8} />. */
+export function TagInput({ value, defaultValue, suggestions, placeholder, label, name, max, restrict, allowDuplicates, validate, transform, disabled, onChange, className, ...props }: TagInputProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const instance = useRef<TagInputInstance | null>(null);
+  const change = useLatest(onChange);
+  const check = useLatest(validate);
+  const shape = useLatest(transform);
+  const start = useRef(value ?? defaultValue ?? []);
+  useIsomorphicLayoutEffect(() => {
+    const created = createTagInput(ref.current, {
+      value: value ?? start.current,
+      suggestions,
+      placeholder,
+      label,
+      name,
+      max,
+      restrict,
+      allowDuplicates,
+      disabled,
+      validate: validate ? (tag, tags) => check.current?.(tag, tags) : undefined,
+      transform: transform ? (tag) => shape.current?.(tag) ?? tag : undefined,
+      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
+  }, [placeholder, label, name, max, restrict, allowDuplicates, disabled, Boolean(validate), Boolean(transform)]);
+  const suggestionsKey = JSON.stringify(suggestions ?? null);
+  useIsomorphicLayoutEffect(() => {
+    if (suggestions) instance.current?.setSuggestions(suggestions);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [suggestionsKey]);
+  const valueKey = JSON.stringify(value ?? null);
+  useIsomorphicLayoutEffect(() => {
+    if (value && instance.current && JSON.stringify(instance.current.value) !== valueKey) instance.current.setValue(value);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [valueKey]);
+  return <div {...props} ref={ref} className={['mk-tag-input', className].filter(Boolean).join(' ')} />;
+}

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