@yewdiel21/motion-kit 0.9.1 → 0.14.0

package/src/components/popover/popover.css

@@ -0,0 +1,24 @@
+/* popover — an anchored .mk-dialog (needs dialog.css): 20 px corners on surface-1, as wide as its content up to
+   22rem, 1rem padding. Styled by class: the copy that folds back into the trigger keeps classes only. */
+.mk-popover,
+mk-popover {
+  display: inline-block;
+}
+
+.mk-dialog.mk-popover-panel {
+  --mk-dialog-radius: 20px;
+  --mk-dialog-bg: var(--mk-surface-1);
+  --mk-dialog-shadow: 0 16px 48px -12px color-mix(in srgb, var(--mk-shadow-color, #000) 35%, transparent);
+  gap: 0.75rem;
+  width: max-content;
+  min-width: min(14rem, calc(100vw - 32px));
+  max-width: min(22rem, calc(100vw - 32px));
+  padding: 1rem;
+}
+
+/* Phones: the anchored dialog is centred by dialog.css; keep it a panel, not a sheet. */
+@media (max-width: 679px) {
+  .mk-dialog.mk-popover-panel {
+    max-width: calc(100vw - 32px);
+  }
+}

package/src/components/popover/react.tsx

@@ -0,0 +1,50 @@
+'use client';
+import { forwardRef, useImperativeHandle, useRef, type HTMLAttributes, type ReactNode } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createPopover, type PopoverInstance, type PopoverOptions } from './engine';
+
+export interface PopoverProps extends Omit<HTMLAttributes<HTMLDivElement>, 'content'>, PopoverOptions {
+  /** The control that opens it (a button). */
+  trigger: ReactNode;
+  /** Controlled open state (optional). */
+  open?: boolean;
+  /** Extra class for the panel. */
+  panelClassName?: string;
+}
+
+export interface PopoverHandle {
+  open(): void;
+  close(): void;
+}
+
+/** <Popover trigger={<button>Filtros</button>}>…</Popover>: the panel grows out of the trigger. */
+export const Popover = forwardRef<PopoverHandle, PopoverProps>(function Popover({ trigger, open, label, onOpenChange, panelClassName, className, children, ...props }, handle) {
+  const ref = useRef<HTMLDivElement>(null);
+  const instance = useRef<PopoverInstance | null>(null);
+  const change = useLatest(onOpenChange);
+  useImperativeHandle(handle, () => ({ open: () => instance.current?.open(), close: () => instance.current?.close() }), []);
+  useIsomorphicLayoutEffect(() => {
+    const created = createPopover(ref.current, { label, onOpenChange: (value) => change.current?.(value) });
+    instance.current = created;
+    return () => {
+      created.destroy();
+      instance.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [label]);
+  useIsomorphicLayoutEffect(() => {
+    if (open === undefined || !instance.current || instance.current.isOpen === open) return;
+    if (open) instance.current.open();
+    else instance.current.close();
+  }, [open]);
+  return (
+    <div {...props} ref={ref} className={['mk-popover', className].filter(Boolean).join(' ')}>
+      <span data-mk-popover-trigger-slot="" style={{ display: 'contents' }}>
+        {trigger}
+      </span>
+      <dialog data-mk-popover-panel="" className={panelClassName}>
+        {children}
+      </dialog>
+    </div>
+  );
+});

package/src/components/progress/README.md

@@ -0,0 +1,17 @@
+# progress
+
+Barra o anillo de progreso con valor determinado o indeterminado. El anillo sigue el `MetricsRing` de Melon Mind: radio `(tamaño − trazo) / 2`, `stroke-dasharray` derivado del ratio y arranque a las 12.
+
+```html
+<mk-progress class="mk-progress" value="40" label="Subiendo informe" show-value></mk-progress>
+<mk-progress class="mk-progress" variant="ring" value="72" label="Meta mensual" show-value></mk-progress>
+<mk-progress class="mk-progress" label="Procesando"></mk-progress> <!-- indeterminado -->
+```
+
+`defineElements()` desde `/elements`, `createProgress(root, options)` o `<Progress value={42} label="Subida" showValue />` desde `/react`.
+
+Opciones: `value` (número o `null` = indeterminado; por defecto `min`), `min=0`, `max=100`, `label` (aria-label), `variant='linear'|'ring'`, `showValue`, `formatValue(value, ratio)` (texto visible y `aria-valuetext`), `duration=.7` (segundos del deslizamiento). API: `setValue(number | null)`, `value`, `destroy()`.
+
+El root recibe `role="progressbar"`, `aria-valuemin/max/now` (sin `aria-valuenow` cuando es indeterminado). Valores no finitos se ignoran y los demás se acotan a los límites. No hay región viva: el valor se lee al llegar a la barra, sin anunciar cada cambio.
+
+El dibujo es un único hijo decorativo `[data-mk-progress-visual]`; el contenido que ya tenga el root se conserva y `destroy()` restaura atributos y estilos. Al subir o bajar, el relleno (o el arco) se desliza con GSAP, las cifras ruedan, la punta brilla al avanzar, el anillo respira y llegar al máximo lanza un estallido. Variables: `--mk-progress-height` (10px), `--mk-progress-size` (anillo, 4.5rem), `--mk-progress-track`, `--mk-progress-fill`. Movimiento reducido: el valor cambia sin transición y el indeterminado queda como relleno parcial estático.

package/src/components/progress/element.ts

@@ -0,0 +1,30 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createProgress, type ProgressInstance } from './engine';
+
+/**
+ * <mk-progress class="mk-progress" value="40" label="Subida" show-value></mk-progress>
+ * Without `value` (or value="indeterminate") it is indeterminate. A new value moves the fill.
+ */
+export class MkProgressElement extends MkElement<ProgressInstance> {
+  static options: Record<string, OptionType> = { value: 'number', min: 'number', max: 'number', label: 'string', variant: 'string', showValue: 'boolean' };
+
+  protected create(options: Record<string, unknown>) {
+    return createProgress(this, { ...options, value: typeof options.value === 'number' ? options.value : null });
+  }
+
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.instance) return;
+    if (name === 'value') this.instance.setValue(next === null || !Number.isFinite(Number(next)) ? null : Number(next));
+    else super.attributeChangedCallback(name, previous, next);
+  }
+
+  setValue(value: number | null) {
+    this.instance?.setValue(value);
+  }
+
+  get value() {
+    return this.instance?.value ?? null;
+  }
+}
+
+export const defineProgress = () => defineElement('mk-progress', MkProgressElement);

package/src/components/progress/engine.ts

@@ -0,0 +1,173 @@
+import { gsap, EASE, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { burst, rollDigits } from '../../motion/micro';
+
+/*
+ * Progress: a bar or a ring (Melon Mind's MetricsRing: radius (size - stroke) / 2,
+ * dasharray from the ratio, starting at 12 o'clock). The root is the progressbar;
+ * the drawing is one decorative [data-mk-progress-visual] child. ARIA follows a
+ * new value at once; the drawing glides to it with GSAP (Melonmind's playful
+ * swing, .38,.49,0,1.5): going up, a light runs at the head and the figure rolls
+ * up; going down, the figure rolls down. Reaching the maximum fires a small burst.
+ * null is indeterminate. Nothing is live: assistive tech reads the value on arrival.
+ */
+
+export type ProgressVariant = 'linear' | 'ring';
+
+export interface ProgressOptions {
+  /** Current value; null is indeterminate. Default: min. */
+  value?: number | null;
+  min?: number;
+  max?: number;
+  label?: string;
+  variant?: ProgressVariant;
+  /** Write the percentage beside the bar (inside the ring). */
+  showValue?: boolean;
+  /** Text for the value (also aria-valuetext). Default: rounded percentage. */
+  formatValue?: (value: number, ratio: number) => string;
+  /** Glide duration in seconds (default .7). */
+  duration?: number;
+}
+
+export interface ProgressInstance extends Instance {
+  setValue(value: number | null): void;
+  readonly value: number | null;
+}
+
+const SVG = 'http://www.w3.org/2000/svg';
+const RING_SIZE = 48;
+const RING_STROKE = 5;
+const RADIUS = (RING_SIZE - RING_STROKE) / 2;
+const CIRCUMFERENCE = 2 * Math.PI * RADIUS;
+
+const finite = (value: unknown): value is number => typeof value === 'number' && Number.isFinite(value);
+
+export function createProgress(root: HTMLElement | null, options: ProgressOptions = {}): ProgressInstance {
+  if (!root) return inert({ setValue() {}, value: null });
+  registerMotion();
+  const scope = createScope();
+  const min = finite(options.min) ? options.min : 0;
+  const max = finite(options.max) && options.max > min ? options.max : Math.max(min + 1, 100);
+  const variant: ProgressVariant = options.variant === 'ring' ? 'ring' : 'linear';
+  const duration = finite(options.duration) ? Math.max(0, options.duration) : 0.7;
+  const clamp = (n: number) => Math.min(max, Math.max(min, n));
+  let value: number | null = options.value === null ? null : clamp(finite(options.value) ? options.value : min);
+
+  const visual = document.createElement('span');
+  visual.dataset.mkProgressVisual = '';
+  visual.setAttribute('aria-hidden', 'true');
+  let arc: SVGCircleElement | null = null;
+  let head: HTMLElement | null = null;
+  let ring: SVGSVGElement | null = null;
+  if (variant === 'ring') {
+    ring = document.createElementNS(SVG, 'svg');
+    ring.setAttribute('viewBox', `0 0 ${RING_SIZE} ${RING_SIZE}`);
+    ring.dataset.mkPart = 'ring';
+    const circle = (part: string) => {
+      const element = document.createElementNS(SVG, 'circle');
+      element.setAttribute('cx', String(RING_SIZE / 2));
+      element.setAttribute('cy', String(RING_SIZE / 2));
+      element.setAttribute('r', String(RADIUS));
+      element.setAttribute('fill', 'none');
+      element.setAttribute('stroke-width', String(RING_STROKE));
+      element.dataset.mkPart = part;
+      ring!.append(element);
+      return element;
+    };
+    circle('track');
+    arc = circle('arc');
+    arc.setAttribute('stroke-linecap', 'round');
+    visual.append(ring);
+  } else {
+    const track = document.createElement('span');
+    track.dataset.mkPart = 'track';
+    const bar = document.createElement('span');
+    bar.dataset.mkPart = 'bar';
+    head = document.createElement('span');
+    head.dataset.mkPart = 'head';
+    track.append(bar, head);
+    visual.append(track);
+  }
+  const text = options.showValue ? document.createElement('span') : null;
+  if (text) {
+    text.dataset.mkPart = 'value';
+    visual.append(text);
+  }
+  root.append(visual);
+
+  scope.attr(root, 'style', root.getAttribute('style'));
+  scope.attr(root, 'role', 'progressbar');
+  scope.attr(root, 'aria-valuemin', String(min));
+  scope.attr(root, 'aria-valuemax', String(max));
+  if (options.label) scope.attr(root, 'aria-label', options.label);
+  scope.attr(root, 'data-mk-variant', variant);
+  scope.attr(root, 'data-mk-ready', '');
+
+  const ratioOf = (n: number | null) => (n === null ? 0 : (n - min) / (max - min));
+  const labelOf = (n: number | null) => (n === null ? '' : options.formatValue ? options.formatValue(n, ratioOf(n)) : `${Math.round(ratioOf(n) * 100)} %`);
+  /** What is drawn now (it trails `value` while gliding). */
+  const shown = { ratio: ratioOf(value) };
+  const draw = () => {
+    const ratio = Math.min(1, Math.max(0, shown.ratio));
+    root.style.setProperty('--mk-progress', ratio.toFixed(4));
+    if (arc) {
+      const length = value === null ? CIRCUMFERENCE * 0.25 : CIRCUMFERENCE * ratio;
+      arc.setAttribute('stroke-dasharray', `${length.toFixed(2)} ${CIRCUMFERENCE.toFixed(2)}`);
+    }
+  };
+  let glide: gsap.core.Tween | null = null;
+  const motion: gsap.core.Animation[] = [];
+  scope.add(() => {
+    glide?.kill();
+    for (const animation of motion.splice(0)) animation.progress(1).kill();
+    visual.remove();
+  });
+
+  const render = (previous: number | null, animate: boolean) => {
+    const label = labelOf(value);
+    scope.attr(root, 'aria-valuenow', value === null ? null : String(value));
+    scope.attr(root, 'aria-valuetext', value !== null && options.formatValue ? label : null);
+    scope.attr(root, 'data-mk-indeterminate', value === null ? '' : null);
+    scope.attr(root, 'data-mk-complete', value !== null && value >= max ? '' : null);
+    const target = ratioOf(value);
+    const direction: 1 | -1 = previous === null || value === null || value >= previous ? 1 : -1;
+    glide?.kill();
+    if (!animate || reduced() || value === null || previous === null || duration === 0) {
+      shown.ratio = target;
+      draw();
+      if (text) text.textContent = label;
+      return;
+    }
+    glide = gsap.to(shown, { ratio: target, duration, ease: EASE.swatch, onUpdate: draw });
+    if (text) {
+      const roll = rollDigits(text, label, direction);
+      if (roll) motion.push(roll);
+    }
+    // Going up: a light runs at the head of the bar; the ring breathes.
+    if (direction > 0 && head) motion.push(gsap.fromTo(head, { opacity: 1, scale: 0.4 }, { opacity: 0, scale: 1.6, duration: 0.6, ease: 'power2.out' }));
+    if (ring) motion.push(gsap.fromTo(ring, { scale: direction > 0 ? 1.06 : 0.95 }, { scale: 1, duration: 0.5, ease: EASE.click, clearProps: 'scale,transform' }));
+    if (value >= max && previous < max) {
+      const done = burst(variant === 'ring' ? visual : (text ?? visual), { count: 6, distance: 22, ring: variant === 'ring' });
+      if (done) motion.push(done);
+    }
+    if (motion.length > 12) motion.splice(0, motion.length - 12);
+  };
+  render(null, false);
+
+  return {
+    setValue(next) {
+      if (scope.disposed) return;
+      const previous = value;
+      if (next === null) value = null;
+      else if (finite(next)) value = clamp(next);
+      else return;
+      render(previous, true);
+    },
+    get value() {
+      return value;
+    },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/progress/progress.css

@@ -0,0 +1,139 @@
+/* progress — Melonmind line: a neutral track, the accent only for the value; a ring (MetricsRing) with the figure inside.
+   The fill is drawn from --mk-progress, which the engine glides with GSAP. */
+.mk-progress,
+mk-progress {
+  --mk-progress-height: 10px;
+  --mk-progress-size: 4.5rem;
+  --mk-progress-track: var(--mk-surface-4);
+  --mk-progress-fill: var(--mk-accent);
+  display: block;
+  color: var(--mk-text);
+  font-family: var(--mk-font);
+}
+
+:is(.mk-progress, mk-progress) [data-mk-progress-visual] {
+  display: flex;
+  align-items: center;
+  gap: 0.875rem;
+}
+
+/* Linear */
+:is(.mk-progress, mk-progress) span[data-mk-part='track'] {
+  position: relative;
+  flex: 1;
+  height: var(--mk-progress-height);
+  border-radius: var(--mk-radius-full);
+  background: var(--mk-progress-track);
+}
+
+:is(.mk-progress, mk-progress) [data-mk-part='bar'] {
+  position: absolute;
+  inset: 0;
+  border-radius: inherit;
+  background: var(--mk-progress-fill);
+  clip-path: inset(0 calc((1 - var(--mk-progress, 0)) * 100%) 0 0 round var(--mk-radius-full));
+}
+
+/* The light at the head of the bar (flashes when the value goes up). */
+:is(.mk-progress, mk-progress) [data-mk-part='head'] {
+  position: absolute;
+  top: 50%;
+  left: calc(var(--mk-progress, 0) * 100%);
+  width: calc(var(--mk-progress-height) * 2.4);
+  aspect-ratio: 1;
+  border-radius: 50%;
+  background: radial-gradient(circle, color-mix(in srgb, var(--mk-progress-fill) 70%, white) 0%, transparent 70%);
+  opacity: 0;
+  pointer-events: none;
+  translate: -50% -50%;
+}
+
+:is(.mk-progress, mk-progress)[data-mk-indeterminate] [data-mk-part='bar'] {
+  clip-path: none;
+  width: 38%;
+  animation: mk-progress-slide 1.4s cubic-bezier(0.65, 0, 0.35, 1) infinite;
+}
+
+:is(.mk-progress, mk-progress) [data-mk-part='value'] {
+  min-width: 4.5ch;
+  color: var(--mk-muted);
+  font-size: 0.875rem;
+  font-weight: 500;
+  font-variant-numeric: tabular-nums;
+  text-align: right;
+}
+
+:is(.mk-progress, mk-progress)[data-mk-complete] [data-mk-part='value'] {
+  color: var(--mk-text);
+}
+
+/* Ring */
+:is(.mk-progress, mk-progress)[data-mk-variant='ring'] {
+  display: inline-block;
+  width: var(--mk-progress-size);
+}
+
+:is(.mk-progress, mk-progress)[data-mk-variant='ring'] [data-mk-progress-visual] {
+  position: relative;
+  display: grid;
+  place-items: center;
+  aspect-ratio: 1;
+}
+
+:is(.mk-progress, mk-progress) [data-mk-part='ring'] {
+  grid-area: 1 / 1;
+  width: 100%;
+  height: 100%;
+  overflow: visible;
+  rotate: -90deg;
+}
+
+:is(.mk-progress, mk-progress) circle[data-mk-part='track'] {
+  stroke: var(--mk-progress-track);
+}
+
+:is(.mk-progress, mk-progress) [data-mk-part='arc'] {
+  stroke: var(--mk-progress-fill);
+}
+
+:is(.mk-progress, mk-progress)[data-mk-variant='ring'][data-mk-indeterminate] [data-mk-part='ring'] {
+  animation: mk-progress-spin 1.1s linear infinite;
+}
+
+:is(.mk-progress, mk-progress)[data-mk-variant='ring'] [data-mk-part='value'] {
+  grid-area: 1 / 1;
+  min-width: 0;
+  color: var(--mk-text);
+  font-size: calc(var(--mk-progress-size) * 0.24);
+  letter-spacing: -0.02em;
+  text-align: center;
+}
+
+@keyframes mk-progress-slide {
+  from {
+    translate: -100% 0;
+  }
+  to {
+    translate: 265% 0;
+  }
+}
+
+@keyframes mk-progress-spin {
+  from {
+    rotate: -90deg;
+  }
+  to {
+    rotate: 270deg;
+  }
+}
+
+/* Reduced motion: values jump; indeterminate becomes a still, partial fill. */
+@media (prefers-reduced-motion: reduce) {
+  :is(.mk-progress, mk-progress) :is([data-mk-part='bar'], [data-mk-part='ring']) {
+    animation: none !important;
+  }
+
+  :is(.mk-progress, mk-progress)[data-mk-indeterminate] [data-mk-part='bar'] {
+    opacity: 0.55;
+  }
+}

package/src/components/progress/react.tsx

@@ -0,0 +1,35 @@
+'use client';
+import { useRef, type HTMLAttributes } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createProgress, type ProgressInstance, type ProgressOptions } from './engine';
+
+export interface ProgressProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'>, ProgressOptions {}
+
+/** <Progress value={42} label="Subida" showValue />; value={null} is indeterminate. The engine owns the drawing and ARIA. */
+export function Progress({ value, min, max, label, variant, showValue, formatValue, className, ...props }: ProgressProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const instance = useRef<ProgressInstance | null>(null);
+  const current = useLatest(value);
+  const format = useLatest(formatValue);
+  const formatted = formatValue !== undefined;
+  useIsomorphicLayoutEffect(() => {
+    const created = createProgress(ref.current, {
+      value: current.current,
+      min,
+      max,
+      label,
+      variant,
+      showValue,
+      formatValue: formatted ? (n, ratio) => format.current?.(n, ratio) ?? '' : undefined,
+    });
+    instance.current = created;
+    return () => {
+      created.destroy();
+      instance.current = null;
+    };
+  }, [min, max, label, variant, showValue, formatted]);
+  useIsomorphicLayoutEffect(() => {
+    instance.current?.setValue(value === undefined ? (min ?? 0) : value);
+  }, [value]);
+  return <div {...props} ref={ref} className={['mk-progress', className].filter(Boolean).join(' ')} />;
+}

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>;
+}