@yewdiel21/motion-kit 0.9.1 → 0.10.0

package/src/components/hover-card/element.ts

@@ -0,0 +1,8 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createHoverCard, type HoverCardInstance } from './engine';
+/** Light DOM: supply the same child markup shown in the README. */
+export class MkHoverCardElement extends MkElement<HoverCardInstance> {
+  static options: Record<string, OptionType> = { openDelay: 'number', closeDelay: 'number', placement: 'string' };
+  protected create(options: Record<string, unknown>) { return createHoverCard(this, options); }
+}
+export const defineHoverCard = () => defineElement('mk-hover-card', MkHoverCardElement);

package/src/components/hover-card/engine.ts

@@ -0,0 +1,69 @@
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+
+export interface HoverCardOptions {
+  openDelay?: number;
+  closeDelay?: number;
+  placement?: 'top' | 'bottom';
+  onOpenChange?: (open: boolean) => void;
+}
+export interface HoverCardInstance extends Instance {
+  open(): void;
+  close(): void;
+  readonly isOpen: boolean;
+}
+let sequence = 0;
+
+/** Nonmodal preview: pointer, keyboard focus and tap all reveal the same panel. */
+export function createHoverCard(root: HTMLElement | null, options: HoverCardOptions = {}): HoverCardInstance {
+  const trigger = root?.querySelector<HTMLElement>('[data-mk-hover-trigger]');
+  const panel = root?.querySelector<HTMLElement>('[data-mk-hover-panel]');
+  if (!root || !trigger || !panel) return inert({ open() {}, close() {}, isOpen: false });
+  const scope = createScope();
+  const openDelay = Number.isFinite(options.openDelay) ? Math.max(0, options.openDelay!) : 120;
+  const closeDelay = Number.isFinite(options.closeDelay) ? Math.max(0, options.closeDelay!) : 140;
+  let opened = false;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let pointerInside = false;
+  let id = panel.id;
+  if (!id) { do { id = `mk-hover-${++sequence}`; } while (document.getElementById(id)); }
+  scope.attr(panel, 'id', id);
+  scope.attr(trigger, 'aria-controls', id);
+  scope.attr(root, 'data-mk-placement', options.placement ?? 'top');
+  scope.attr(root, 'data-mk-ready', '');
+  const cancel = () => { clearTimeout(timer); timer = undefined; };
+  const set = (value: boolean) => {
+    cancel();
+    if (scope.disposed) return;
+    const changed = value !== opened;
+    opened = value;
+    scope.attr(trigger, 'aria-expanded', String(value));
+    scope.attr(panel, 'hidden', value ? null : '');
+    scope.attr(root, 'data-mk-open', value ? '' : null);
+    if (changed) {
+      options.onOpenChange?.(value);
+      root.dispatchEvent(new CustomEvent('mk:open-change', { bubbles: true, detail: { open: value } }));
+    }
+  };
+  const schedule = (value: boolean, delay: number) => { cancel(); timer = setTimeout(() => set(value), delay); };
+  scope.on(root, 'pointerenter', () => { pointerInside = true; schedule(true, openDelay); });
+  scope.on(root, 'pointerleave', () => {
+    pointerInside = false;
+    if (!root.contains(document.activeElement)) schedule(false, closeDelay);
+  });
+  scope.on(root, 'focusin', () => set(true));
+  scope.on(root, 'focusout', (event) => {
+    if (!pointerInside && !root.contains((event as FocusEvent).relatedTarget as Node | null)) schedule(false, closeDelay);
+  });
+  scope.on(trigger, 'click', () => set(true));
+  scope.on(document, 'pointerdown', (event) => { if (!root.contains(event.target as Node)) set(false); });
+  scope.on(root, 'keydown', (event) => {
+    if (event.key !== 'Escape' || !opened) return;
+    event.preventDefault();
+    trigger.focus();
+    set(false);
+  });
+  scope.add(cancel);
+  set(false);
+  return { open: () => set(true), close: () => set(false), get isOpen() { return opened; }, destroy: () => scope.dispose() };
+}

package/src/components/hover-card/hover-card.css

@@ -0,0 +1,13 @@
+.mk-hover-card, mk-hover-card { position: relative; display: inline-flex; }
+.mk-hover-card [data-mk-hover-panel], mk-hover-card [data-mk-hover-panel] {
+  position: absolute; z-index: 10; bottom: calc(100% + .75rem); left: 0;
+  width: min(19rem, calc(100vw - 3rem)); padding: 1.25rem; border-radius: var(--mk-radius-lg);
+  color: var(--mk-text); background: var(--mk-surface-3); border: 1px solid var(--mk-outline-soft);
+  box-shadow: 0 12px 40px color-mix(in srgb, var(--mk-shadow-color) 20%, transparent);
+  animation: mk-hover-card-in .28s cubic-bezier(.2,.8,.2,1) both;
+}
+.mk-hover-card [data-mk-hover-panel]::after, mk-hover-card [data-mk-hover-panel]::after { content: ''; position: absolute; inset: -1rem 0; z-index: -1; }
+.mk-hover-card[data-mk-placement=bottom] [data-mk-hover-panel], mk-hover-card[data-mk-placement=bottom] [data-mk-hover-panel] { top: calc(100% + .75rem); bottom: auto; }
+.mk-hover-card [hidden], mk-hover-card [hidden] { display: none !important; }
+@keyframes mk-hover-card-in { from { opacity: 0; transform: translateY(7px) scale(.97); } to { opacity: 1; transform: none; } }
+@media (prefers-reduced-motion: reduce) { .mk-hover-card [data-mk-hover-panel], mk-hover-card [data-mk-hover-panel] { animation: none; } }

package/src/components/hover-card/react.tsx

@@ -0,0 +1,19 @@
+'use client';
+import { useRef, type HTMLAttributes, type ReactNode } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createHoverCard, type HoverCardOptions } from './engine';
+export interface HoverCardProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'>, HoverCardOptions {
+  trigger: ReactNode; children: ReactNode; triggerLabel?: string; panelLabel?: string;
+}
+export function HoverCard({ trigger, children, triggerLabel, panelLabel = 'Vista previa', openDelay, closeDelay, placement, onOpenChange, className, ...props }: HoverCardProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const change = useLatest(onOpenChange);
+  useIsomorphicLayoutEffect(() => {
+    const instance = createHoverCard(ref.current, { openDelay, closeDelay, placement, onOpenChange: (n) => change.current?.(n) });
+    return () => instance.destroy();
+  }, [openDelay, closeDelay, placement]);
+  return <div {...props} ref={ref} className={['mk-hover-card', className].filter(Boolean).join(' ')}>
+    <button type="button" className="mk-button mk-button--tonal" data-mk-hover-trigger aria-label={triggerLabel} aria-expanded="false">{trigger}</button>
+    <div data-mk-hover-panel role="region" aria-label={panelLabel} hidden>{children}</div>
+  </div>;
+}

package/src/components/input-otp/README.md

@@ -0,0 +1,18 @@
+# input-otp
+
+OTP numérico con un único input nativo y slots decorativos. Conserva edición, selección, pegado, ceros iniciales y autocomplete=one-time-code.
+
+```html
+<mk-input-otp class="mk-input-otp" length="6">
+  <span data-mk-otp-slots aria-hidden="true"></span>
+  <input data-mk-otp-input type="text" name="code" aria-label="Código de verificación" />
+</mk-input-otp>
+```
+
+`defineElements()`, `createInputOtp(root, options)`, o `<InputOtp length={6} onChange={setCode} onComplete={verify} />`.
+
+Opciones: `length=6` (1…16), `value`, `mask=false`, `onChange(value)`, `onComplete(value)`. API `setValue(text, notify=true)`, `focus()`, `value`, `destroy()`. Limpia caracteres no ASCII numéricos y limita longitud. Eventos `mk:change {value,complete}`, `mk:complete {value}`; escribir el mismo valor no repite callbacks. No envía ni valida códigos contra un servidor.
+
+React acepta `defaultValue`, `label`, `name`, `disabled`, `required`, `invalid`. Variables `--mk-otp-size`, `--mk-otp-gap`; foco y error usan tokens. Sin movimiento con reduced-motion. Al destruir restaura input y nodos previos.
+
+El reset nativo del formulario sincroniza el control sin emitir callbacks de edición. Los atributos de custom elements conservan el estado editado si value no está presente; value explícito tiene precedencia.

package/src/components/input-otp/element.ts

@@ -0,0 +1,14 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createInputOtp, type InputOtpInstance } from './engine';
+/** Light DOM: supply the same child markup shown in the README. */
+export class MkInputOtpElement extends MkElement<InputOtpInstance> {
+  static options: Record<string, OptionType> = { length: 'number', value: 'string', mask: 'boolean' };
+  protected create(options: Record<string, unknown>) { return createInputOtp(this, options); }
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.isConnected || !this.instance) return;
+    const value = this.instance.value;
+    this.instance.destroy();
+    this.instance = this.create({ ...(!this.hasAttribute('value') ? { value } : {}), ...this.options });
+  }
+}
+export const defineInputOtp = () => defineElement('mk-input-otp', MkInputOtpElement);

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

@@ -0,0 +1,106 @@
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+
+export interface InputOtpOptions {
+  length?: number;
+  value?: string;
+  mask?: boolean;
+  onChange?: (value: string) => void;
+  onComplete?: (value: string) => void;
+}
+export interface InputOtpInstance extends Instance {
+  setValue(value: string, notify?: boolean): void;
+  focus(): void;
+  readonly value: string;
+}
+
+/** One real input preserves native editing, mobile autofill and password managers. */
+export function createInputOtp(root: HTMLElement | null, options: InputOtpOptions = {}): InputOtpInstance {
+  const input = root?.querySelector<HTMLInputElement>('[data-mk-otp-input]');
+  const slots = root?.querySelector<HTMLElement>('[data-mk-otp-slots]');
+  if (!root || !input || !slots) return inert({ setValue() {}, focus() {}, value: '' });
+  const scope = createScope();
+  const length = Number.isFinite(options.length) ? Math.min(16, Math.max(1, Math.round(options.length!))) : 6;
+  const clean = (text: string) => text.replace(/[^0-9]/g, '').slice(0, length);
+  const original = input.value;
+  const originalNodes = [...slots.childNodes];
+  let value = clean(options.value ?? input.value);
+  let pendingReset: Event | null = null;
+  const cells = Array.from({ length }, () => {
+    const cell = document.createElement('span');
+    cell.className = 'mk-input-otp__slot';
+    return cell;
+  });
+  slots.replaceChildren(...cells);
+  scope.attr(slots, 'aria-hidden', 'true');
+  scope.attr(input, 'type', 'text');
+  scope.attr(input, 'inputmode', 'numeric');
+  scope.attr(input, 'autocomplete', 'one-time-code');
+  scope.attr(input, 'maxlength', String(length));
+  scope.attr(input, 'pattern', `[0-9]{${length}}`);
+  scope.attr(root, 'data-mk-ready', '');
+  const render = () => {
+    if (pendingReset) {
+      if (pendingReset.eventPhase !== 0) return;
+      if (!pendingReset.defaultPrevented) value = clean(input.value);
+      pendingReset = null;
+    }
+    input.value = value;
+    const active = document.activeElement === input ? Math.min(length - 1, input.selectionStart ?? value.length) : -1;
+    cells.forEach((cell, i) => {
+      const text = value[i] ? options.mask ? '•' : value[i]! : '';
+      if (cell.textContent !== text) cell.textContent = text;
+      cell.toggleAttribute('data-mk-active', i === active);
+      cell.toggleAttribute('data-mk-filled', i < value.length);
+    });
+    scope.attr(root, 'data-mk-complete', value.length === length ? '' : null);
+  };
+  const setValue = (next: string, notify = true) => {
+    if (scope.disposed) return;
+    if (pendingReset?.eventPhase === 0) pendingReset = null;
+    const previous = value;
+    value = clean(String(next));
+    render();
+    if (notify && value !== previous) {
+      options.onChange?.(value);
+      root.dispatchEvent(new CustomEvent('mk:change', { bubbles: true, detail: { value, complete: value.length === length } }));
+      if (value.length === length) {
+        options.onComplete?.(value);
+        root.dispatchEvent(new CustomEvent('mk:complete', { bubbles: true, detail: { value } }));
+      }
+    }
+  };
+  scope.on(input, 'input', (event) => {
+    if ((event as InputEvent).isComposing) return;
+    const caret = clean(input.value.slice(0, input.selectionStart ?? input.value.length)).length;
+    setValue(input.value);
+    input.setSelectionRange(caret, caret);
+    render();
+  });
+  scope.on(input, 'compositionend', () => setValue(input.value));
+  scope.on(input, 'paste', (event) => {
+    const text = (event as ClipboardEvent).clipboardData?.getData('text');
+    if (text === undefined) return;
+    event.preventDefault();
+    const start = input.selectionStart ?? value.length;
+    const end = input.selectionEnd ?? start;
+    const inserted = clean(text);
+    setValue(value.slice(0, start) + inserted + value.slice(end));
+    const caret = Math.min(length, start + inserted.length);
+    input.setSelectionRange(caret, caret);
+    render();
+  });
+  scope.on(input, 'focus', render);
+  scope.on(input, 'blur', render);
+  scope.on(input, 'keyup', render);
+  scope.on(input, 'click', render);
+  scope.on(document, 'selectionchange', () => { if (document.activeElement === input) render(); });
+  if (input.form) scope.on(input.form, 'reset', (event) => {
+    render();
+    pendingReset = event;
+    scope.timeout(() => { if (pendingReset === event) render(); }, 0);
+  });
+  scope.add(() => { slots.replaceChildren(...originalNodes); input.value = original; });
+  render();
+  return { setValue, focus: () => { if (!scope.disposed) input.focus(); }, get value() { return value; }, destroy: () => scope.dispose() };
+}

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

@@ -0,0 +1,9 @@
+.mk-input-otp, mk-input-otp { --mk-otp-size: 2.75rem; --mk-otp-gap: .4rem; display: inline-block; position: relative; max-width: 100%; }
+.mk-input-otp [data-mk-otp-slots], mk-input-otp [data-mk-otp-slots] { display: flex; flex-wrap: wrap; gap: var(--mk-otp-gap); }
+.mk-input-otp__slot { box-sizing: border-box; width: var(--mk-otp-size); height: 3.5rem; display: grid; place-items: center; border: 1px solid var(--mk-outline-soft); border-radius: var(--mk-radius-sm); color: var(--mk-text); background: var(--mk-surface-1); font: 1.5rem var(--mk-font-mono, monospace); transition: border-color .2s, background .2s, transform .2s; }
+.mk-input-otp__slot[data-mk-active] { outline: 2px solid var(--mk-accent); outline-offset: 2px; background: var(--mk-accent-soft); color: var(--mk-on-accent-soft); transform: translateY(-2px); }
+.mk-input-otp [data-mk-otp-input], mk-input-otp [data-mk-otp-input] { position: absolute; inset: 0; box-sizing: border-box; width: 100%; height: 100%; border: 0; background: transparent; color: transparent; caret-color: transparent; outline: 0; font: 1.5rem var(--mk-font-mono, monospace); letter-spacing: calc(var(--mk-otp-size) + var(--mk-otp-gap) - 1ch); padding: 0 0 0 calc((var(--mk-otp-size) - 1ch) / 2); }
+.mk-input-otp:has([aria-invalid=true]) .mk-input-otp__slot, mk-input-otp:has([aria-invalid=true]) .mk-input-otp__slot { border-color: var(--mk-error); }
+.mk-input-otp:has(:disabled), mk-input-otp:has(:disabled) { opacity: .45; }
+@media (max-width: 420px) { .mk-input-otp, mk-input-otp { --mk-otp-size: 2.25rem; --mk-otp-gap: .3rem; } }
+@media (prefers-reduced-motion: reduce) { .mk-input-otp__slot { transition: none; transform: none !important; } }

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

@@ -0,0 +1,21 @@
+'use client';
+import { useRef, type HTMLAttributes } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createInputOtp, type InputOtpOptions } from './engine';
+export interface InputOtpProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'onComplete' | 'defaultValue'>, InputOtpOptions {
+  label?: string; name?: string; disabled?: boolean; required?: boolean; invalid?: boolean; defaultValue?: string;
+}
+export function InputOtp({ length, value, defaultValue, mask, onChange, onComplete, label = 'Código de verificación', name, disabled, required, invalid, className, ...props }: InputOtpProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const edited = useRef<string | undefined>(undefined);
+  const change = useLatest(onChange);
+  const complete = useLatest(onComplete);
+  useIsomorphicLayoutEffect(() => {
+    const instance = createInputOtp(ref.current, { length, value: value ?? edited.current, mask, onChange: (n) => change.current?.(n), onComplete: (n) => complete.current?.(n) });
+    return () => { edited.current = instance.value; instance.destroy(); };
+  }, [length, value, mask]);
+  return <div {...props} ref={ref} className={['mk-input-otp', className].filter(Boolean).join(' ')}>
+    <span data-mk-otp-slots aria-hidden="true" />
+    <input data-mk-otp-input type="text" aria-label={label} name={name} defaultValue={value ?? defaultValue ?? ''} disabled={disabled} required={required} aria-invalid={invalid || undefined} />
+  </div>;
+}

package/src/components/pagination/README.md

@@ -0,0 +1,17 @@
+# pagination
+
+Paginación con ventana acotada de números, extremos, elipsis y respuesta de elevación/presión.
+
+```html
+<mk-pagination class="mk-pagination" total-pages="30" page="4" role="navigation" aria-label="Artículos">
+  <button type="button" data-mk-pagination-previous aria-label="Página anterior">←</button>
+  <span data-mk-pagination-pages></span>
+  <button type="button" data-mk-pagination-next aria-label="Página siguiente">→</button>
+</mk-pagination>
+```
+
+`defineElements()`, `createPagination(root, options)`, o `<Pagination totalPages={30} page={page} onChange={setPage} />`.
+
+Opciones: `totalPages=10`, `page=1`, `siblings=1` (0…10), `pageLabel(n)`, `onChange(n)`. Total mínimo 1. API: `setPage(n, notify=true)`, `setTotalPages(n)`, `page`, `totalPages`, `destroy()`. `mk:change` lleva `{page,totalPages}`. Los cambios del total acotan la página y conservan el foco.
+
+Flechas izquierda/derecha, Home y End cambian la selección; botones nativos y aria-current=page. La aplicación decide cómo cargar los resultados. Sin animación con movimiento reducido.

package/src/components/pagination/element.ts

@@ -0,0 +1,14 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createPagination, type PaginationInstance } from './engine';
+/** Light DOM: supply the same child markup shown in the README. */
+export class MkPaginationElement extends MkElement<PaginationInstance> {
+  static options: Record<string, OptionType> = { totalPages: 'number', page: 'number', siblings: 'number' };
+  protected create(options: Record<string, unknown>) { return createPagination(this, options); }
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.isConnected || !this.instance) return;
+    const page = this.instance.page;
+    this.instance.destroy();
+    this.instance = this.create({ ...(!this.hasAttribute('page') ? { page } : {}), ...this.options });
+  }
+}
+export const definePagination = () => defineElement('mk-pagination', MkPaginationElement);

package/src/components/pagination/engine.ts

@@ -0,0 +1,102 @@
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+
+export interface PaginationOptions {
+  totalPages?: number;
+  page?: number;
+  siblings?: number;
+  pageLabel?: (page: number) => string;
+  onChange?: (page: number) => void;
+}
+export interface PaginationInstance extends Instance {
+  setPage(page: number, notify?: boolean): void;
+  setTotalPages(total: number): void;
+  readonly page: number;
+  readonly totalPages: number;
+}
+// Reserve room for the page-window arithmetic so incrementing always progresses.
+const positive = (n: number | undefined, fallback: number) => Number.isFinite(n) ? Math.max(1, Math.min(Number.MAX_SAFE_INTEGER - 32, Math.floor(n!))) : fallback;
+
+/** Renders a bounded window of pages, even when totalPages is very large. */
+export function createPagination(root: HTMLElement | null, options: PaginationOptions = {}): PaginationInstance {
+  const pages = root?.querySelector<HTMLElement>('[data-mk-pagination-pages]');
+  if (!root || !pages) return inert({ setPage() {}, setTotalPages() {}, page: 1, totalPages: 1 });
+  const scope = createScope();
+  const original = [...pages.childNodes];
+  const previous = root.querySelector<HTMLButtonElement>('[data-mk-pagination-previous]');
+  const next = root.querySelector<HTMLButtonElement>('[data-mk-pagination-next]');
+  let total = positive(options.totalPages, 10);
+  let page = Math.min(total, positive(options.page, 1));
+  const siblings = Math.min(10, Math.max(0, Number.isFinite(options.siblings) ? Math.floor(options.siblings!) : 1));
+  scope.attr(root, 'data-mk-ready', '');
+  const render = () => {
+    const hadFocus = pages.contains(document.activeElement);
+    const selected = new Set([1, total]);
+    for (let n = Math.max(1, page - siblings); n <= Math.min(total, page + siblings); n++) selected.add(n);
+    const fragment = document.createDocumentFragment();
+    let last = 0;
+    for (const n of [...selected].sort((a, b) => a - b)) {
+      if (last && n - last > 1) {
+        const gap = document.createElement('span');
+        gap.className = 'mk-pagination__gap';
+        gap.textContent = '…';
+        gap.setAttribute('aria-hidden', 'true');
+        fragment.append(gap);
+      }
+      const button = document.createElement('button');
+      button.type = 'button';
+      button.dataset.mkPage = String(n);
+      button.textContent = String(n);
+      button.setAttribute('aria-label', options.pageLabel?.(n) ?? `Página ${n}`);
+      if (n === page) button.setAttribute('aria-current', 'page');
+      fragment.append(button);
+      last = n;
+    }
+    pages.replaceChildren(fragment);
+    if (hadFocus) pages.querySelector<HTMLButtonElement>('[aria-current]')?.focus();
+    if (previous) scope.attr(previous, 'disabled', page === 1 ? '' : null);
+    if (next) scope.attr(next, 'disabled', page === total ? '' : null);
+  };
+  const setPage = (value: number, notify = true) => {
+    if (scope.disposed || !Number.isFinite(value)) return;
+    const candidate = Math.max(1, Math.min(total, Math.round(value)));
+    if (candidate === page) return;
+    const focused = pages.contains(document.activeElement);
+    page = candidate;
+    render();
+    if (focused) pages.querySelector<HTMLButtonElement>('[aria-current]')?.focus();
+    if (notify) {
+      options.onChange?.(page);
+      root.dispatchEvent(new CustomEvent('mk:change', { bubbles: true, detail: { page, totalPages: total } }));
+    }
+  };
+  scope.on(root, 'click', (event) => {
+    const target = (event.target as Element).closest<HTMLButtonElement>('button');
+    if (!target || target.disabled) return;
+    if (target === previous) setPage(page - 1);
+    else if (target === next) setPage(page + 1);
+    else if (target.dataset.mkPage) setPage(Number(target.dataset.mkPage));
+  });
+  scope.on(root, 'keydown', (event) => {
+    if (!(event.target instanceof HTMLButtonElement)) return;
+    const to = event.key === 'ArrowRight' ? page + 1 : event.key === 'ArrowLeft' ? page - 1 : event.key === 'Home' ? 1 : event.key === 'End' ? total : null;
+    if (to === null) return;
+    event.preventDefault();
+    setPage(to);
+    pages.querySelector<HTMLButtonElement>('[aria-current]')?.focus();
+  });
+  scope.add(() => pages.replaceChildren(...original));
+  render();
+  return {
+    setPage,
+    setTotalPages(value) {
+      if (scope.disposed || !Number.isFinite(value)) return;
+      total = positive(value, 1);
+      if (page > total) setPage(total);
+      else render();
+    },
+    get page() { return page; },
+    get totalPages() { return total; },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/pagination/pagination.css

@@ -0,0 +1,10 @@
+.mk-pagination, mk-pagination { display: flex; flex-wrap: wrap; justify-content: center; align-items: center; gap: .35rem; }
+.mk-pagination [data-mk-pagination-pages], mk-pagination [data-mk-pagination-pages] { display: flex; align-items: center; gap: .25rem; }
+.mk-pagination button, mk-pagination button { min-width: 2.5rem; height: 2.5rem; border: 0; border-radius: var(--mk-radius-full); background: var(--mk-surface-2); color: var(--mk-text); font: inherit; cursor: pointer; transition: transform .3s, background .3s, color .3s; }
+.mk-pagination button[aria-current], mk-pagination button[aria-current] { background: var(--mk-accent); color: var(--mk-on-accent); }
+.mk-pagination button:hover:not(:disabled), mk-pagination button:hover:not(:disabled) { transform: translateY(-3px); }
+.mk-pagination button:active:not(:disabled), mk-pagination button:active:not(:disabled) { transform: scale(.9); }
+.mk-pagination button:focus-visible, mk-pagination button:focus-visible { outline: 2px solid var(--mk-accent); outline-offset: 3px; }
+.mk-pagination button:disabled, mk-pagination button:disabled { opacity: .35; cursor: default; }
+.mk-pagination__gap { padding: 0 .15rem; color: var(--mk-muted); }
+@media (prefers-reduced-motion: reduce) { .mk-pagination button, mk-pagination button { transition: none; transform: none !important; } }

package/src/components/pagination/react.tsx

@@ -0,0 +1,22 @@
+'use client';
+import { useRef, type HTMLAttributes } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createPagination, type PaginationOptions } from './engine';
+export interface PaginationProps extends Omit<HTMLAttributes<HTMLElement>, 'onChange'>, PaginationOptions {
+  previousLabel?: string; nextLabel?: string;
+}
+export function Pagination({ totalPages, page, siblings, pageLabel, onChange, previousLabel = 'Página anterior', nextLabel = 'Página siguiente', className, ...props }: PaginationProps) {
+  const ref = useRef<HTMLElement>(null);
+  const selected = useRef<number | undefined>(undefined);
+  const change = useLatest(onChange);
+  const label = useLatest(pageLabel);
+  useIsomorphicLayoutEffect(() => {
+    const instance = createPagination(ref.current, { totalPages, page: page ?? selected.current, siblings, pageLabel: (n) => label.current?.(n) ?? `Página ${n}`, onChange: (n) => change.current?.(n) });
+    return () => { selected.current = instance.page; instance.destroy(); };
+  }, [totalPages, page, siblings, pageLabel]);
+  return <nav aria-label="Paginación" {...props} ref={ref} className={['mk-pagination', className].filter(Boolean).join(' ')}>
+    <button type="button" data-mk-pagination-previous aria-label={previousLabel}>←</button>
+    <span data-mk-pagination-pages />
+    <button type="button" data-mk-pagination-next aria-label={nextLabel}>→</button>
+  </nav>;
+}

package/src/components/quantity/README.md

@@ -0,0 +1,20 @@
+# quantity
+
+Selector inspirado en [Bernice](https://bernicebakery.com/collections/cakes). Botones nativos, mordida geométrica propia y giro de 15° en .4 s. La forma adapta el original; no usa su SVG.
+
+```html
+<mk-quantity class="mk-quantity" min="1" max="9">
+  <button type="button" data-mk-quantity-decrease aria-label="Disminuir">−</button>
+  <input data-mk-quantity-input type="number" value="1" aria-label="Cantidad" />
+  <button type="button" data-mk-quantity-increase aria-label="Aumentar">+</button>
+</mk-quantity>
+```
+
+Registrar con `defineElements()` de `/elements`, o usar `createQuantity(root, options)`. React: `<Quantity min={1} max={9} value={value} onChange={setValue} />` desde `/react`.
+
+Opciones: `min=1`, `max=999`, `step=1`, `value`, `disabled`, `onChange(value)`. API: `setValue(number, notify=true)`, `value`, `destroy()`. El input acepta edición: un número válido y dentro del rango se aplica mientras escribes (sin tocar el texto); uno parcial o fuera de rango se ajusta al paso desde min y se acota al confirmar o salir del campo. Evento `mk:change` con `{value, previous}`. No realiza operaciones de carrito.
+
+Variables: `--mk-quantity-size` (3rem), colores semánticos. Movimiento reducido conserva controles sin rotación. React acepta label/decreaseLabel/increaseLabel/name y props HTML. Desmontar llama destroy y restaura marcado/valores originales.
+
+El reset nativo del formulario sincroniza el control sin emitir callbacks de edición. Los atributos de custom elements conservan el estado editado si value no está presente; value explícito tiene precedencia.
+Si max no coincide con un paso desde min, el límite efectivo es el mayor min+n×step que no supere max, para mantener validez HTML nativa.

package/src/components/quantity/element.ts

@@ -0,0 +1,14 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createQuantity, type QuantityInstance } from './engine';
+/** Light DOM: supply the same child markup shown in the README. */
+export class MkQuantityElement extends MkElement<QuantityInstance> {
+  static options: Record<string, OptionType> = { min: 'number', max: 'number', step: 'number', value: 'number', disabled: 'boolean' };
+  protected create(options: Record<string, unknown>) { return createQuantity(this, options); }
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.isConnected || !this.instance) return;
+    const value = this.instance.value;
+    this.instance.destroy();
+    this.instance = this.create({ ...(!this.hasAttribute('value') ? { value } : {}), ...this.options });
+  }
+}
+export const defineQuantity = () => defineElement('mk-quantity', MkQuantityElement);

package/src/components/quantity/engine.ts

@@ -0,0 +1,85 @@
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+
+export interface QuantityOptions {
+  min?: number;
+  max?: number;
+  step?: number;
+  value?: number;
+  disabled?: boolean;
+  onChange?: (value: number) => void;
+}
+export interface QuantityInstance extends Instance {
+  setValue(value: number, notify?: boolean): void;
+  readonly value: number;
+}
+
+/** Bounded numeric control. Bite/rotation is CSS; buttons remain native. */
+export function createQuantity(root: HTMLElement | null, options: QuantityOptions = {}): QuantityInstance {
+  const input = root?.querySelector<HTMLInputElement>('[data-mk-quantity-input]');
+  if (!root || !input) return inert({ setValue() {}, value: 0 });
+  const scope = createScope();
+  const min = Number.isFinite(options.min) ? options.min! : 1;
+  const max = Number.isFinite(options.max) ? Math.max(min, options.max!) : Math.max(min, 999);
+  const step = Number.isFinite(options.step) && options.step! > 0 ? options.step! : 1;
+  const steps = Math.floor((max - min) / step + 1e-9);
+  const upper = Math.min(max, Number((min + steps * step).toFixed(10)));
+  const normalize = (n: number) => Math.max(min, Math.min(upper, Number((min + Math.round((n - min) / step) * step).toFixed(10))));
+  const original = input.value;
+  const disabled = options.disabled ?? input.disabled;
+  const decrease = root.querySelector<HTMLButtonElement>('[data-mk-quantity-decrease]');
+  const increase = root.querySelector<HTMLButtonElement>('[data-mk-quantity-increase]');
+  scope.attr(input, 'min', String(min));
+  scope.attr(input, 'max', String(max));
+  scope.attr(input, 'step', String(step));
+  scope.attr(input, 'disabled', disabled ? '' : null);
+  scope.attr(root, 'data-mk-ready', '');
+  const initial = input.value.trim() ? Number(input.value) : NaN;
+  let value = normalize(Number.isFinite(options.value) ? options.value! : Number.isFinite(initial) ? initial : min);
+  let pendingReset: Event | null = null;
+  const typed = () => (input.value.trim() && Number.isFinite(input.valueAsNumber) ? input.valueAsNumber : NaN);
+  const render = (syncInput = true) => {
+    if (pendingReset) {
+      if (pendingReset.eventPhase !== 0) return;
+      if (!pendingReset.defaultPrevented) value = normalize(Number.isFinite(typed()) ? typed() : min);
+      pendingReset = null;
+    }
+    if (syncInput) input.value = String(value);
+    if (decrease) scope.attr(decrease, 'disabled', disabled || value <= min ? '' : null);
+    if (increase) scope.attr(increase, 'disabled', disabled || value >= upper ? '' : null);
+  };
+  const commit = (next: number, notify: boolean, syncInput: boolean) => {
+    if (scope.disposed || !Number.isFinite(next)) return;
+    if (pendingReset?.eventPhase === 0) pendingReset = null;
+    const previous = value;
+    value = normalize(next);
+    render(syncInput);
+    if (notify && value !== previous) {
+      options.onChange?.(value);
+      root.dispatchEvent(new CustomEvent('mk:change', { bubbles: true, detail: { value, previous } }));
+    }
+  };
+  const setValue = (next: number, notify = true) => commit(next, notify, true);
+  if (decrease) scope.on(decrease, 'click', () => { if (!decrease.disabled) setValue(value - step); });
+  if (increase) scope.on(increase, 'click', () => { if (!increase.disabled) setValue(value + step); });
+  // While typing, commit only numbers that are already valid and leave the text alone;
+  // partial or out-of-range input settles on change/blur.
+  scope.on(input, 'input', () => {
+    const n = typed();
+    if (Number.isFinite(n) && normalize(n) === n) commit(n, true, false);
+  });
+  scope.on(input, 'change', () => {
+    if (Number.isFinite(typed())) setValue(typed());
+    else render();
+  });
+  scope.on(input, 'blur', () => render());
+  if (input.form) scope.on(input.form, 'reset', (event) => {
+    // reset's native default action runs after its listeners. Match the final input silently.
+    render();
+    pendingReset = event;
+    scope.timeout(() => { if (pendingReset === event) render(); }, 0);
+  });
+  scope.add(() => { input.value = original; });
+  render();
+  return { setValue, get value() { return value; }, destroy: () => scope.dispose() };
+}

package/src/components/quantity/quantity.css

@@ -0,0 +1,15 @@
+.mk-quantity, mk-quantity { display: inline-flex; align-items: center; gap: .5rem; --mk-quantity-size: 3rem; }
+.mk-quantity [data-mk-quantity-decrease], .mk-quantity [data-mk-quantity-increase], mk-quantity button {
+  width: var(--mk-quantity-size); height: var(--mk-quantity-size); border: 0; border-radius: 50%;
+  background: var(--mk-secondary-soft); color: var(--mk-on-secondary-soft); font: inherit; font-size: 1.65rem;
+  cursor: pointer; transition: transform .4s cubic-bezier(.28,.71,0,.98), opacity .2s;
+}
+.mk-quantity [data-mk-quantity-increase], mk-quantity [data-mk-quantity-increase] { background: var(--mk-accent-soft); color: var(--mk-on-accent-soft); }
+.mk-quantity button:is(:hover,:focus-visible):not(:disabled), mk-quantity button:is(:hover,:focus-visible):not(:disabled) {
+  transform: rotate(15deg); mask-image: radial-gradient(circle at 100% 0, transparent 22%, #000 23%);
+}
+.mk-quantity button:focus-visible, mk-quantity button:focus-visible { outline: 2px solid var(--mk-accent); outline-offset: 4px; }
+.mk-quantity button:disabled, mk-quantity button:disabled { opacity: .4; cursor: default; }
+.mk-quantity input, mk-quantity input { width: 3.5rem; padding: .4rem 0; border: 0; border-radius: var(--mk-radius-sm); text-align: center; font: inherit; font-variant-numeric: tabular-nums; background: transparent; color: var(--mk-text); appearance: textfield; }
+.mk-quantity input::-webkit-inner-spin-button, mk-quantity input::-webkit-inner-spin-button { appearance: none; }
+@media (prefers-reduced-motion: reduce) { .mk-quantity button, mk-quantity button { transition: none; transform: none !important; } }

package/src/components/quantity/react.tsx

@@ -0,0 +1,21 @@
+'use client';
+import { useRef, type HTMLAttributes } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createQuantity, type QuantityOptions } from './engine';
+export interface QuantityProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue'>, QuantityOptions {
+  label?: string; decreaseLabel?: string; increaseLabel?: string; name?: string;
+}
+export function Quantity({ min, max, step, value, disabled, onChange, label = 'Cantidad', decreaseLabel = 'Disminuir', increaseLabel = 'Aumentar', name, className, ...props }: QuantityProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const edited = useRef<number | undefined>(undefined);
+  const change = useLatest(onChange);
+  useIsomorphicLayoutEffect(() => {
+    const instance = createQuantity(ref.current, { min, max, step, value: value ?? edited.current, disabled, onChange: (n) => change.current?.(n) });
+    return () => { edited.current = instance.value; instance.destroy(); };
+  }, [min, max, step, value, disabled]);
+  return <div {...props} ref={ref} className={['mk-quantity', className].filter(Boolean).join(' ')} role="group" aria-label={label}>
+    <button type="button" data-mk-quantity-decrease aria-label={decreaseLabel}>−</button>
+    <input data-mk-quantity-input type="number" aria-label={label} name={name} defaultValue={value ?? min ?? 1} disabled={disabled} />
+    <button type="button" data-mk-quantity-increase aria-label={increaseLabel}>+</button>
+  </div>;
+}