@yewdiel21/motion-kit 0.9.0 → 0.10.0

package/src/components/nav/README.md

@@ -1,20 +1,18 @@
 # nav
 
-La navegación de Stepbro (Money y Tasks): siete estilos de escritorio y una sola barra de cristal en el móvil (< 680 px), dentro de una cáscara de app (`.mk-shell`).
+Navegación con siete estilos de escritorio y una sola barra de cristal en el móvil (< 680 px), dentro de una cáscara de app (`.mk-shell`).
 
-| Estilo | Stepbro | Cómo se ve |
-|---|---|---|
-| `clasica` | style-1 | Barra lateral con borde; la página actual en una píldora rellena |
-| `bonita` | style-2 (por defecto en Money) | Píldoras de texto centradas que se ensanchan al pasar y al estar activas (padding con resorte, 0.3 s `cubic(.38,.49,0,1.5)`) |
-| `dock` | style-3 | Barra flotante de cristal centrada abajo; el botón activo se ensancha a 80 px |
-| `guapa` | style-4 | La vista es una tarjeta sobre la cáscara tintada; la página actual es un chip blanco |
-| `tasks` | style-5 | Riel de botones redondos de 56 px; el activo se cuadra (radio 0.3 s `cubic(.38,.49,0,2)`) |
-| `melon` | style-6 | Barra lateral suave con un lavado primario en la página actual |
-| `tunnel` | style-7 | Palabras grandes; la que tiene el ratón y sus vecinas crecen como un dock (1.2 / 1.09 / 1.03) |
+| Estilo | Cómo se ve |
+|---|---|
+| `clasica` | Barra lateral con borde; la página actual en una píldora rellena |
+| `bonita` | Píldoras de texto centradas que se ensanchan al pasar y al estar activas (padding con resorte, 0.3 s `cubic(.38,.49,0,1.5)`) |
+| `dock` | Barra flotante de cristal centrada abajo; el botón activo se ensancha a 80 px |
+| `guapa` | La vista es una tarjeta sobre la cáscara tintada; la página actual es un chip blanco |
+| `tasks` | Riel de botones redondos de 56 px; el activo se cuadra (radio 0.3 s `cubic(.38,.49,0,2)`) |
+| `melon` | Barra lateral suave con un lavado primario en la página actual |
+| `tunnel` | Palabras grandes; la que tiene el ratón y sus vecinas crecen como un dock (1.2 / 1.09 / 1.03) |
 
-`accent` (variant-1 de Stepbro) pinta la página actual en primary-container. Al cambiar de página el icono se rellena (`mk-nav-icon`, 125 ms, `FILL 0 → 1`, para fuentes de iconos como Material Symbols). Con `reveal`, al arrancar la cáscara se descubre desde el primer botón (`revealFrom`, como el `Nav` de Stepbro).
-
-Origen: Stepbro `navigation-styles.css`, `navigation.json`, componente `Nav` (Tasks).
+`accent` pinta la página actual en primary-container. Al cambiar de página el icono se rellena (`mk-nav-icon`, 125 ms, `FILL 0 → 1`, para fuentes de iconos como Material Symbols). Con `reveal`, al arrancar la cáscara se descubre desde el primer botón (`revealFrom`).
 
 ## HTML / Astro
 
@@ -73,7 +71,7 @@ const [page, setPage] = useState('home');
 
 - Al hacer clic se emite `mk:navigate` (cancelable; `detail`: `index`, `value`, `item`, `originalEvent`). Para una SPA, llama `event.detail.originalEvent.preventDefault()` y navega con tu router.
 - `select()` solo marca la página actual (sin evento): úsalo para seguir a tu router.
-- `storageKey` guarda el estilo elegido en `localStorage` (Stepbro: `money-nav`).
+- `storageKey` guarda el estilo elegido en `localStorage`.
 - `NAV_STYLES` lista los siete nombres.
 
 ## Variables CSS

package/src/components/nav/engine.ts

@@ -4,11 +4,11 @@ import { inert, warnOnce, type Instance } from '../../core/types';
 import { revealFrom, type RevealHandle } from '../../motion/reveal';
 
 /*
- * Stepbro's navigation: seven desktop styles (Clásica, Bonita, Dock, Guapa,
+ * navigation: seven desktop styles (Clásica, Bonita, Dock, Guapa,
  * Tasks, Melon, Tunnel) and one glass bar on phones, all in CSS (nav.css). The
  * engine marks the current page (aria-current="page"), switches styles (and can
- * remember the choice, like Stepbro's "money-nav"), and on start can reveal the
- * app shell from the first button (Stepbro's Nav runs revealFrom on mount).
+ * remember the choice), and on start can reveal the
+ * app shell from the first button.
  * Parts: .mk-nav__buttons .mk-nav__button (data-mk-value or href), .mk-nav__button--first.
  */
 
@@ -18,7 +18,7 @@ export type NavStyle = (typeof NAV_STYLES)[number];
 export interface NavOptions {
   /** Default: the saved one (storageKey), else the mk-nav--<style> class in the markup, else 'bonita' (Money's default). */
   style?: NavStyle;
-  /** The accent variant (Stepbro's variant-1): the current page in primary-container. */
+  /** The accent variant: the current page in primary-container. */
   accent?: boolean;
   /** Reveal the shell from the first button when the nav starts (off by default). */
   reveal?: boolean;
@@ -65,7 +65,7 @@ const write = (key: string, value: string) => {
   }
 };
 
-/** Stepbro's nav entrance: the app shell is uncovered from the nav's first button. */
+/** nav entrance: the app shell is uncovered from the nav's first button. */
 export function revealShell(nav: HTMLElement): RevealHandle | null {
   if (!entrances()) return null;
   const shell = nav.closest<HTMLElement>('.mk-shell') ?? nav.parentElement;

package/src/components/nav/nav.css

@@ -1,9 +1,5 @@
 /*
- * nav — Stepbro's navigation (Money and Tasks): seven desktop styles and one
- * mobile bar under 680 px, inside an app shell. Ported from Stepbro's
- * `.app-nav.style-N` rules: .app-container → .mk-shell, .app-view → .mk-shell__view,
- * .nav-button → .mk-nav__button, [active=true] → [aria-current="page"],
- * variant-1 → .mk-nav--accent.
+ * nav — seven desktop styles and one mobile bar under 680 px, inside an app shell.
  */
 
 /* Shell: the view and the nav side by side (the nav first), stacked on phones. */

package/src/components/nav/react.tsx

@@ -10,7 +10,7 @@ export interface NavItem {
   icon?: ReactNode;
   /** Render a link instead of a button. */
   href?: string;
-  /** Hidden in the phone bar (Stepbro's hide-on-mobile). */
+  /** Hidden in the phone bar. */
   hideOnMobile?: boolean;
 }
 
@@ -29,7 +29,7 @@ export interface NavProps extends Omit<HTMLAttributes<HTMLElement>, 'onSelect'>
   actions?: ReactNode;
 }
 
-/** Stepbro's navigation. Put it inside a <div className="mk-shell"> next to <main className="mk-shell__view">. */
+/** navigation. Put it inside a <div className="mk-shell"> next to <main className="mk-shell__view">. */
 export function Nav({
   items,
   active,
@@ -47,7 +47,7 @@ export function Nav({
     if (!reveal || !ref.current) return;
     const handle = revealShell(ref.current);
     return () => handle?.cancel();
-    // Only on mount, like Stepbro.
+    // Only on mount.
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
   const classes = ['mk-nav', `mk-nav--${navStyle}`, accent && 'mk-nav--accent', className].filter(Boolean).join(' ');

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

package/src/components/slot-picker/README.md

@@ -0,0 +1,68 @@
+# slot-picker
+
+El selector de citas de Melon Mind («Agendar cita»): a la izquierda un mes compacto y a la derecha los horarios del día elegido. Sirve para reservas, citas o mesas.
+
+- **Cambiar de día:** los horarios salen 30 px hacia un lado y entran 30 px desde el otro (0.25 s `ease-out`), en la dirección del cambio. El original usa una View Transition `time-slot`.
+- **Primera lista:** entra creciendo (escala .7, blur 32 → 0, 0.3 s `cubic-bezier(.38,.49,0,1.1)`), 20 ms entre horarios.
+- **Encabezado del día:** se abre de 0 a 56 px en 0.5 s `cubic-bezier(.38,.49,0,1.4)`.
+- **Horario elegido:** se ilumina en 0.7 s (escala .8 → 1, blur 16 → 0).
+- **Cambiar de mes:** los días se deslizan igual que los horarios.
+
+Origen: REA de la app de Melon Mind (`appt-creator.css`, `schedulePicker.css`, `CreateApptManager.js`).
+
+## HTML / Astro
+
+```html
+<mk-slot-picker class="mk-slot-picker" locale="es" min="2026-10-23" closed-days="[0]"
+  slots='["09:00","10:00","11:30","16:00","17:30"]'>
+  <div class="mk-slot-picker__calendar">
+    <div class="mk-slot-picker__month">
+      <h3 class="mk-slot-picker__title" data-mk-slot-title></h3>
+      <button type="button" class="mk-slot-picker__nav" data-mk-slot-prev aria-label="Mes anterior">←</button>
+      <button type="button" class="mk-slot-picker__nav" data-mk-slot-next aria-label="Mes siguiente">→</button>
+    </div>
+    <div data-mk-slot-days></div>
+  </div>
+  <div class="mk-slot-picker__panel">
+    <p class="mk-slot-picker__heading" data-mk-slot-heading></p>
+    <div data-mk-slot-times></div>
+    <input type="hidden" name="cita" data-mk-slot-value>
+  </div>
+</mk-slot-picker>
+```
+
+El input oculto `[data-mk-slot-value]` lleva `YYYY-MM-DDTHH:mm` y emite `input`/`change`, así que funciona dentro de un `<form>`. Si cambias el atributo `slots`, la lista se actualiza sin perder el día. Sin custom element: `createSlotPicker(root, opciones)`.
+
+## React
+
+```tsx
+<SlotPicker
+  name="cita"
+  min={new Date()}
+  closedDays={[0]}
+  slots={(day) => fetch(`/api/horarios?dia=${dayKey(day)}`).then((r) => r.json())}
+  onChange={({ value }) => setCita(value)}
+  actions={<button className="mk-button">Agendar</button>}
+/>
+```
+
+## Opciones
+
+| Opción | Atributo | Por defecto | Qué hace |
+|---|---|---|---|
+| `slots` | `slots` (JSON) | `[]` | Lista igual todos los días, mapa `{"2026-10-23": [...]}` o función `(día) => lista \| Promise<lista>`. Horas `HH:mm` |
+| `date` | `date` | hoy | Mes inicial (y día elegido si no hay `value`) |
+| `value` | `value` | — | `"2026-10-23T10:30"` o `{ date, time }` |
+| `min`, `max` | `min`, `max` | — | Días fuera de rango deshabilitados; flechas de mes limitadas |
+| `closedDays` | `closed-days` (JSON) | `[]` | Días de la semana cerrados (0 = domingo) |
+| `isDisabled(date)` | — | — | Regla propia |
+| `firstDay` | `first-day` | `0` | Primer día de la semana |
+| `locale` | `locale` | `'es'` | Nombres de mes y día |
+| `labels` | — | español | `placeholder`, `empty`, `loading`, `heading(date)` |
+| `onChange({date, time, key, value})`, `onDateChange(date)` | — | — | Callbacks |
+
+API: `selectDate(d)`, `selectTime(t | null)`, `setSlots(fuente)`, `date`, `time`, `value`, `destroy()`. `mk:change` lleva `{date, time, key, value}`. Si los horarios llegan por promesa, mientras cargan se muestra `loading` con `aria-busy`, y una respuesta vieja nunca pisa a la más reciente.
+
+## Accesibilidad
+
+Los días forman una rejilla ARIA con foco móvil: flechas, Inicio/Fin y RePág/AvPág para cambiar de mes. Los horarios son un `radiogroup`: las flechas mueven la selección, y el grupo está etiquetado por el encabezado del día. Los días deshabilitados son botones `disabled`. Con movimiento reducido no hay deslizamiento, entradas ni resaltado animado.

package/src/components/slot-picker/element.ts

@@ -0,0 +1,27 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createSlotPicker, type SlotPickerInstance, type SlotSource } from './engine';
+
+/** Light DOM: supply the [data-mk-slot-days] and [data-mk-slot-times] markup shown in the README. */
+export class MkSlotPickerElement extends MkElement<SlotPickerInstance> {
+  static options: Record<string, OptionType> = {
+    date: 'string', value: 'string', slots: 'json', min: 'string', max: 'string', closedDays: 'json', firstDay: 'number', locale: 'string',
+  };
+
+  protected create(options: Record<string, unknown>) {
+    return createSlotPicker(this, options);
+  }
+
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.isConnected || !this.instance) return;
+    if (name === 'slots') {
+      this.instance.setSlots((this.options.slots as SlotSource | undefined) ?? []);
+      return;
+    }
+    // Keep the visitor's pick unless the value itself changed.
+    const value = this.instance.value ?? (this.instance.date ? this.instance.date : undefined);
+    this.instance.destroy();
+    this.instance = this.create({ ...(name !== 'value' && value ? (typeof value === 'string' ? { value } : { date: value }) : {}), ...this.options });
+  }
+}
+
+export const defineSlotPicker = () => defineElement('mk-slot-picker', MkSlotPickerElement);