@yewdiel21/motion-kit 0.9.0 → 0.10.0

package/skills/motion-kit/reference/recipes.md

@@ -1,20 +1,20 @@
-# Recipe parameters and origin
+# Recipe parameters
 
-Values were read from the public bundles of spencergabor.com (Nuxt 3, analysed with REA on 2026-10-14) and Stepbro Tasks/Money, then re-implemented. No third-party code is shipped.
+Parameters, defaults and behavior for the motion recipes.
 
 ## Shared
 
-| Name | Value | Origin |
-|---|---|---|
-| Spring | `v = v·friction^dt + (target − x)·stiffness·dt; x += v·dt`, stiffness .05, friction .8 | spencergabor.com `useSpring` |
-| Frame loop | one `gsap.ticker` callback, `dt = Δms / (1000/60)`, capped at 3; recipes subscribe only while visible | spencergabor.com shared rAF loop |
-| `--mk-ease-elastic` | `linear(0, .5737 7.6%, … 1.0011 81.26%, 1)` | spencergabor.com `--ease-out-elastic` |
-| `--mk-ease-elastic-hover` | `linear(0, .2178 2.1%, … .9981 86.66%, 1)` | spencergabor.com `--ease-out-elastic-100-30` |
-| `ELASTIC` (GSAP) | `elastic.out(1, 0.45)` | visual match of `--mk-ease-elastic` |
-| `mk-signature` | `M0,0 C0.308,0.19 0.107,0.633 0.288,0.866 0.382,0.987 0.656,1 1,1` | Stepbro signature curve |
-| `mk-flow` | `M0,0 C0.25,0.1 0.25,1 1,1` | Stepbro flowSoft |
-| `mk-close` | `.56,.27,0,1` | Stepbro close fade |
-| `--mk-shadow` | `0 9px 21px rgb(0 0 0/.1), 0 38px 38px rgb(0 0 0/.09), 0 85px 51px rgb(0 0 0/.05)` | spencergabor.com `--shadow` |
+| Name | Value |
+|---|---|
+| Spring | `v = v·friction^dt + (target − x)·stiffness·dt; x += v·dt`, stiffness .05, friction .8 |
+| Frame loop | one `gsap.ticker` callback, `dt = Δms / (1000/60)`, capped at 3; recipes subscribe only while visible |
+| `--mk-ease-elastic` | `linear(0, .5737 7.6%, … 1.0011 81.26%, 1)` |
+| `--mk-ease-elastic-hover` | `linear(0, .2178 2.1%, … .9981 86.66%, 1)` |
+| `ELASTIC` (GSAP) | `elastic.out(1, 0.45)` |
+| `mk-signature` | `M0,0 C0.308,0.19 0.107,0.633 0.288,0.866 0.382,0.987 0.656,1 1,1` |
+| `mk-flow` | `M0,0 C0.25,0.1 0.25,1 1,1` |
+| `mk-close` | `.56,.27,0,1` |
+| `--mk-shadow` | `0 9px 21px rgb(0 0 0/.1), 0 38px 38px rgb(0 0 0/.09), 0 85px 51px rgb(0 0 0/.05)` |
 
 ## spring-cards
 
@@ -22,12 +22,12 @@ Values were read from the public bundles of spencergabor.com (Nuxt 3, analysed w
 - Pointer push: `dx = (px − cx)/innerWidth·2`, `dy = (py − cy)/innerHeight·2`, `k = max(0, 1 − hypot(dx, dy))^6 · .4`, `push += movement·k`, `push *= .9^dt`.
 - CSS: `rotate: calc(tilt − velocity·.25deg)`; tilts 2°, −3°, 6°, −2°; vertical offsets 5 %, −6 %, 5 %, −4 %.
 - Entrance: `scale 0 → 1`, 1 s, elastic, `i·.08s + .4s`.
-- Portfolio change: 4:3 cards and −1.5 % overlap (Spencer: square, −6 %) so text on covers stays readable.
+- Layout: 4:3 cards and −1.5 % overlap so text on covers stays readable.
 
 ## curved-carousel
 
 - Friction .85; drag velocity = pointer movement per frame; on release `v·2`, rest `x − v·f/(1−f)`, snap to the nearest slide, approach `x += (target − x)(1 − f^dt)`.
-- Tap: under 6 px of travel (Spencer: < 10 px and < 100 ms).
+- Tap: under 6 px of travel.
 - Wheel: `v −= deltaX·.2` when horizontal; snap 150 ms after the last wheel event.
 - Arc: `rotate: t·.03deg`, origin `50% 70vw`, `translateY: cos(t·π/1000)·−3rem + 3rem`, title opacity `cos(t·π/600)`; `t` = slide centre − viewport centre in px.
 - Entrance: media from `scale .8; translate 0 20%`, 1.4 s elastic, delay `sin(k·π/2)·.12s`.
@@ -35,15 +35,15 @@ Values were read from the public bundles of spencergabor.com (Nuxt 3, analysed w
 ## pile
 
 - Layers: `rotation = rand(2,5)·(±1 alternating)`, `offsetX = rand(4,10)·random sign`, `offsetY = (n − i)·5`; seeded (mulberry32) so SSR and client match.
-- CSS: `rotate: rot·.6deg`, `translate: px·.3% py·.3%` (Spencer: .5deg / .25%).
+- CSS: `rotate: rot·.6deg`, `translate: px·.3% py·.3%`.
 - In view: media `scale .7 → 1`, shadow `0 → 1`, .8 s elastic; hover 1.01/1.02/1.03, active .97/.98/.99.
 
 ## words
 
 - `scaleY 0 → 1`, `yPercent 25 → 0`, origin bottom, .8 s, `ELASTIC`, 100 ms between words, 60 ms between letters.
-- Spencer did this with CSS transitions and `@starting-style`; the package uses GSAP SplitText so reduced motion and text replacement work.
+- Uses GSAP SplitText with reduced-motion support and text replacement.
 
-## flow (Stepbro)
+## flow
 
 - From `y −20`, `blur(16px)`, opacity 0 → 0, 0.5 s, 50 ms stagger, `mk-flow`.
 
@@ -62,21 +62,21 @@ Values were read from the public bundles of spencergabor.com (Nuxt 3, analysed w
 
 ## radial-menu
 
-- Item position: `translate(sin(i·.9 + 1.5708)·−r, cos(i·.9 + 1.5708)·r)`, r = 3.6rem (Spencer: spacing .75, start 1.25).
+- Item position: `translate(sin(i·.9 + 1.5708)·−r, cos(i·.9 + 1.5708)·r)`, r = 3.6rem.
 - Open: `scale .5 → 1`, .5 s elastic, `i·.05s`; close: .15 s `cubic-bezier(.55,.055,.675,.19)`.
 
 ## pill
 
 - Hover `scale 1.05` + shadow, active `.95`, .8 s elastic; `.mk-stretch` hover `scaleY(1.2)`, 1 s elastic-hover.
 
-## Stepbro v0.2 (Tasks `especificacion-replicacion.json`, Money `replication-catalog.json`)
+## Core motion and surfaces
 
-| Name | Value | Kit id |
-|---|---|---|
-| `mk-fade-away` / `mk-blur-away` | `.56,.27,0,1` / `.37,.35,0,1` | modal-close-origin |
-| `mk-chat-scroll` | `M0,0 C0.308,0.19 0.318,0.567 0.5,0.8 0.593,0.921 0.656,1 1,1` | chat-scroll |
-| `mk-layout-reflow` / `mk-sortable-land` | spring path `FA(.52)` / `FA(.62)` (stiffness 5.6, sampled 72 steps) | task-layout, task-drag |
-| `--mk-ease-signature` | Stepbro's own `linear()` sampling of the signature (its backdrop tint) | tasks-modal-backdrop |
+| Name | Value |
+|---|---|
+| `mk-fade-away` / `mk-blur-away` | `.56,.27,0,1` / `.37,.35,0,1` |
+| `mk-chat-scroll` | `M0,0 C0.308,0.19 0.318,0.567 0.5,0.8 0.593,0.921 0.656,1 1,1` |
+| `mk-layout-reflow` / `mk-sortable-land` | spring path `FA(.52)` / `FA(.62)` (stiffness 5.6, sampled 72 steps) |
+| `--mk-ease-signature` | own `linear()` sampling of the signature (its backdrop tint) |
 
 ### flowIn / flowOut / stepChange
 
@@ -86,7 +86,7 @@ Values were read from the public bundles of spencergabor.com (Nuxt 3, analysed w
 
 ### tabs
 
-- Indicator to the selected tab's box (Flip.fit in the original), 0.45 s, signature; centres a scrolling list; reduced: instant.
+- Indicator to the selected tab's box, 0.45 s, signature; centres a scrolling list; reduced: instant.
 
 ### counter
 
@@ -115,48 +115,47 @@ Values were read from the public bundles of spencergabor.com (Nuxt 3, analysed w
 
 ### sortable
 
-- Stepbro Tasks `useDragReorder` ("transform" mode). Threshold 6 px; floating copy (cloned into the item's own list, `position: fixed`, so the list's CSS still styles it) follows a spring 1100/38 with mass `clamp(√(w·h / 24000), 1, 2.5)`; tilt spring 170/13 toward `14·tanh(torque / 14)`, torque from smoothed velocity (×2e-3) and acceleration (×45e-5) about the grab point (arm Y ≥ .4). Lift 0.18 s `power2.out`, scale `1 + .03·lift`, shadow `0 12·lift 32·lift rgb(0 0 0 / .22·lift)`.
+- Drag threshold 6 px; floating copy (cloned into the item's own list, `position: fixed`, so the list's CSS still styles it) follows a spring 1100/38 with mass `clamp(√(w·h / 24000), 1, 2.5)`; tilt spring 170/13 toward `14·tanh(torque / 14)`, torque from smoothed velocity (×2e-3) and acceleration (×45e-5) about the grab point (arm Y ≥ .4). Lift 0.18 s `power2.out`, scale `1 + .03·lift`, shadow `0 12·lift 32·lift rgb(0 0 0 / .22·lift)`.
 - Neighbours: `y` by the item's height + the space to its neighbour, 0.62 s `mk-layout-reflow` (FA .52); insertion index by the pointer against item midpoints; group by pointer x (then y). Land 0.42 s `mk-sortable-land` (FA .62) to the slot, cross-fade 0.277 s `power1.inOut` to a copy styled by the destination list.
 - Auto-scroll: scrollable ancestors (and the page) within 56 px of an edge, `ceil(16 · min(1, d / 56))` px a frame. Touch (`pointer: coarse`): handle only. Escape / pointercancel: back. Keyboard (added): Space/Enter, arrows, Escape; reflow 0.62 s; `aria-live` announcements.
 
-## iyo.ai (v0.7, REA research `REA - iyo.ai`)
+## Floating navigation and cards
 
-### island (navbar `nav`/`d3`)
+### island
 
 - Shell fixed top 2rem, 23.5rem wide (28rem ≥ 1920 px; 1rem / 5vw side margins ≤ 767 / 479 px), radius 3em → 2em (0.4 s `cubic-bezier(.4,0,.2,1)`, closing 0.45 s late). Glass `blur(20px)` on `#38383899` + `linear-gradient(141deg, #a9c2f214, #62718c24)`.
 - Content `grid-template-rows 0fr → 1fr`, 0.6 s `cubic-bezier(.625,.05,0,1)`, 0.125 s late. Backdrop black 0 → .4, 0.7 s `cubic-bezier(.5,.5,0,1)`, 0.1 s late. Rows `opacity 0 → 1`, `translateY 3em → 0`, 0.6 s, delay `0.15 + i·0.025` s.
 - Entrance `yPercent −300 → 0`, 1.8 s (no ease given, so GSAP's `power1.out`). Card hover: siblings 20 % (0.15 s ease-out), picture 1.04 (0.4 s, back 0.3 s `cubic-bezier(.25,.46,.45,.94)`). Closes on a scroll > 1 px after wheel / touchmove.
 
-### card-dock (`product-cards`, `PM`)
+### card-dock
 
 - Stack, from the end: `translateY(90 % / 180 % / 270 % / 360 %) scale(.93 / .87 / .8 / .73)`; open 0.8 s, close 0.64 s, `cubic-bezier(.48,.01,0,1.08)`. Card 4rem → 4.5rem, 0.6 s `cubic-bezier(.77,0,.175,1)`; surface `#38383899 → #555555b0` 0.3 s `cubic-bezier(.65,0,.35,1)`; `blur(19px)`, border `#8a8a8a1a`, radius .9rem.
 - Title opacity 0.5 s, `translateX(−15 % → −120 %)` 0.4 s. Intro: spread 1600 ms from the call, then the CTA fades in. Tablet (768–1024 px, `hover: none`): the first tap opens.
 
-### snap-strip (`product-card-mobile`, `CM`)
+### snap-strip
 
-- 5000 ms a card, 2000 ms wait after mousedown / touchstart / wheel, `data-delay 500`, cards 68vw. iyo uses Smooothy (snap physics, cloned loop); here native scroll-snap.
+- 5000 ms a card, 2000 ms wait after mousedown / touchstart / wheel, `data-delay 500`, cards 68vw. Uses native scroll-snap.
 
-### fill-text (`GM`)
+### fill-text
 
 - SplitText `words, chars`; `fromTo(chars, { autoAlpha: .2 }, { autoAlpha: 1, stagger: .1, ease: 'linear' })` (0.5 s each), scrubbed `top 90%` → `center 40%`.
 
-### particle-hero (`wK` / `YW` / `dE`, adapted)
+### particle-hero
 
-- iyo: 1280² points, RGBA float ping-pong, Newton step .4 × 4 toward the field's zeros, Chladni `sin(mπx/a)·sin(nπy/b)`, destination by hash vs `texturePercent`, damping `.985^dt60`, pointer radius .16 / force .0225 × smoothed speed (`min(d·5, 1)`, `.8 old + .2 new`), fade in 1 s after .3 s `power2.out`. Timeline: modes m, n ∈ {3, 5, 7} every 6–12 s; frequency 20–45 every 5–10 s; Chladni 0–5 over 1.2–3 s `power2.inOut`; word cycle N = 3–6 s (out .4N, in .6N to .4–.8, hold 2–4 s).
-- Kit: own shaders, size² points (128² by default), damping .91, pointer radius .28, words drawn locally (dark pixels < 120 of a 640 × 320 canvas), Canvas2D fallback (~1800 points).
+- GPU simulation: `size²` points (128² by default), damping .91, pointer radius .28, Chladni modes 3/5/7 and word morph cycles, words drawn locally (dark pixels < 120 of a 640 × 320 canvas), Canvas2D fallback (~1800 points).
 
 ## Collections and menu (v0.8)
 
 All six have a `createX(root, options)` factory in the main entry, `useX(ref, options, deps)` in `/react`, CLI entry and vanilla/React playground page. `autoInit()` supports all six. Destroy restores the host and clears timers, tweens, listeners, observers and generated markup.
 
-| Name | Markup | Options and controls | Source |
+| Name | Markup | Options and controls | Motion |
 |---|---|---|---|
-| ticket-menu | `.mk-dialog.mk-menu` dialog with `[data-mk-item]` | `MenuOptions`; `open`, `close`, `toggle`, `items`, `isOpen`; also `<Menu.Root ticket>` / `<mk-menu ticket>` | Siena: .9 s opening, 1.1 s rows from 150%, stagger .02; clip-path adapts the site's grid panels |
-| infinite-reel | `.mk-infinite-reel > [data-mk-reel-track]` | `axis x/y`, `speed 0`, `friction .95`; `moveBy`, `position`, `pause`, `resume` | Siena: DOM/inertia adaptation, without original scene or snap |
-| repel-bento | `.mk-repel-bento` with cards | `distance 30`, `breakpoint 1024`; `play`, `reset` | Dousan: entry spring 60/15, stagger .006, .6 vector; neighbours min(5000/d,30), spring 300/25 |
-| rotator | `.mk-rotator` with one item per child | `interval 8000`, `autoplay true`, `index`, `onChange`; `select`, `next`, `previous`, `index` | Dousan testimonials: .25 s, y 5→0 |
-| drag-ruler | `.mk-drag-ruler[aria-label]` | `min 0`, `max 8`, `step .1`, `value max`, `pixelsPerUnit 60`, `onChange`; `set`, `value`; `mk:change` | Dousan's years ruler |
-| dock-pill | `.mk-dock-pill` with `[data-mk-dock-item]` links/buttons | `index`, `onSelect`; `select`, `index`; `mk:select` | Dousan's activeTabPill, spring 380/30 |
+| ticket-menu | `.mk-dialog.mk-menu` dialog with `[data-mk-item]` | `MenuOptions`; `open`, `close`, `toggle`, `items`, `isOpen`; also `<Menu.Root ticket>` / `<mk-menu ticket>` | .9 s opening, 1.1 s rows from 150%, stagger .02 |
+| infinite-reel | `.mk-infinite-reel > [data-mk-reel-track]` | `axis x/y`, `speed 0`, `friction .95`; `moveBy`, `position`, `pause`, `resume` | Continuous DOM track with inertial scrolling |
+| repel-bento | `.mk-repel-bento` with cards | `distance 30`, `breakpoint 1024`; `play`, `reset` | Entry spring 60/15, stagger .006, .6 vector; neighbours min(5000/d,30), spring 300/25 |
+| rotator | `.mk-rotator` with one item per child | `interval 8000`, `autoplay true`, `index`, `onChange`; `select`, `next`, `previous`, `index` | .25 s, y 5→0 |
+| drag-ruler | `.mk-drag-ruler[aria-label]` | `min 0`, `max 8`, `step .1`, `value max`, `pixelsPerUnit 60`, `onChange`; `set`, `value`; `mk:change` | Numeric marks with drag and keyboard input |
+| dock-pill | `.mk-dock-pill` with `[data-mk-dock-item]` links/buttons | `index`, `onSelect`; `select`, `index`; `mk:select` | Spring 380/30 |
 
 Reduced motion disables inertia, autoplay, entry and repulsion, keeping manual navigation. Reel copies are inert, aria-hidden and have no duplicate IDs. Ruler supports arrows, Home/End and PageUp/PageDown. Dock supports arrows/Home/End and skips disabled items. Keep rotator controls outside its child list.
 
@@ -164,9 +163,9 @@ Reduced motion disables inertia, autoplay, entry and repulsion, keeping manual n
 
 `createLiquidBlend`, `createMatcap`, `createShaderGrain`, `createShaderBlur` share `{ images?, progress?, amount?, maxDpr? }` and return `{ setProgress, setAmount, pause, resume, mode, destroy }`. Images default to the host's first two `<img>` elements; one image is repeated. Same-origin or CORS-enabled images; loading is observed. A host with explicit dimensions is required. React hooks have the corresponding `use…` names. These factories are not exported from the main entry or registered with autoInit.
 
-- Liquid: `amount .15`, progress 0→1 blends the two textures with centre-weighted UV waves. OFFFICE `liquid-swap` mechanism adapted to images without models or render targets.
-- Matcap: analytic sphere, normal UV .495+.5, hemispheric light and gain .15; optional image used as matcap. OFFFICE's model renderer is not included.
-- Grain: own temporal hash, amount .07 from Siena's postprocess; 24 Hz grain, fixed frame for reduced motion.
-- Blur: amount 5 image pixels, seven weighted samples with Siena's .19648255/.29690696/.09447040/.01038136 weights and 1.41176471/3.29411765/5.17647059 offsets. Progress rotates the direction x→y.
+- Liquid: `amount .15`, progress 0→1 blends the two textures with centre-weighted UV waves.
+- Matcap: analytic sphere, normal UV .495+.5, hemispheric light and gain .15; optional image used as matcap. It does not load models.
+- Grain: own temporal hash, amount .07 from postprocess; 24 Hz grain, fixed frame for reduced motion.
+- Blur: amount 5 image pixels, seven weighted samples with .19648255/.29690696/.09447040/.01038136 weights and 1.41176471/3.29411765/5.17647059 offsets. Progress rotates the direction x→y.
 
-WebGL unsupported, compilation/texture error or context loss leaves the original HTML available. Context restoration rebuilds resources. The canvas is decorative; loops pause offscreen and in hidden tabs. No Three/OGL dependency and no shaders/assets copied from the researched sites.
+WebGL unsupported, compilation/texture error or context loss leaves the original HTML available. Context restoration rebuilds resources. The canvas is decorative; loops pause offscreen and in hidden tabs. No additional rendering library is required.

package/src/auto/auto-init.ts

@@ -1,3 +1,22 @@
+import { createQuantity } from '../components/quantity/engine';
+import { createPagination } from '../components/pagination/engine';
+import { createHoverCard } from '../components/hover-card/engine';
+import { createInputOtp } from '../components/input-otp/engine';
+import { createJoinedCta } from '../recipes/joined-cta/create-joined-cta';
+import { createImageZoom } from '../recipes/image-zoom/create-image-zoom';
+import { createFontCycle } from '../recipes/font-cycle/create-font-cycle';
+import { createThumbnailNav } from '../recipes/thumbnail-nav/create-thumbnail-nav';
+import { createActionButton } from '../recipes/action-button/create-action-button';
+import { createFilmHero } from '../recipes/film-hero/create-film-hero';
+import { createEditorialReveal } from '../recipes/editorial-reveal/create-editorial-reveal';
+import { createStudioDock } from '../components/studio-dock/engine';
+import { createCalendar } from '../components/calendar/engine';
+import { createSlotPicker } from '../components/slot-picker/engine';
+import { createWeightHover } from '../recipes/weight-hover/create-weight-hover';
+import { createSticker } from '../recipes/sticker/create-sticker';
+import { createScrollDock } from '../recipes/scroll-dock/create-scroll-dock';
+import { createLocalClock } from '../recipes/local-clock/create-local-clock';
+import { createTrailer } from '../components/trailer/engine';
 import { ScrollTrigger } from '../core/gsap';
 import { warnOnce, type Instance } from '../core/types';
 import { createSpringCards } from '../recipes/spring-cards/create-spring-cards';
@@ -39,6 +58,25 @@ import { createDockPill } from '../recipes/dock-pill/create-dock-pill';
 type Factory = (el: HTMLElement, options: Record<string, unknown>) => Instance;
 
 const factories = {
+  'joined-cta': createJoinedCta,
+  'image-zoom': createImageZoom,
+  'font-cycle': createFontCycle,
+  'thumbnail-nav': createThumbnailNav,
+  'action-button': createActionButton,
+  'film-hero': createFilmHero,
+  'editorial-reveal': createEditorialReveal,
+  'studio-dock': createStudioDock,
+  'trailer': createTrailer,
+  'quantity': createQuantity,
+  'pagination': createPagination,
+  'hover-card': createHoverCard,
+  'input-otp': createInputOtp,
+  'calendar': createCalendar,
+  'slot-picker': createSlotPicker,
+  'weight-hover': createWeightHover,
+  'sticker': createSticker,
+  'scroll-dock': createScrollDock,
+  'local-clock': createLocalClock,
   'spring-cards': createSpringCards,
   'curved-carousel': (el, options) =>
     createCurvedCarousel(el, {

package/src/components/calendar/README.md

@@ -0,0 +1,82 @@
+# calendar
+
+El calendario de Melon Mind. Tiene vista de mes y de semana, día de hoy marcado y eventos como chips con estado (pendiente, completado o cancelado), hora y color propio.
+
+- **Al cargar:** los días entran desde arriba con blur (y −20 px, blur 16 → 0, 0.5 s), 5 ms uno tras otro, y después los eventos, 20 ms uno tras otro. Es el `flowChilds` del `CalendarComponent` original.
+- **Cambiar de mes o semana:** la rejilla vieja sale 30 px hacia un lado (0.12 s) y, cuando ya casi no se ve, la nueva entra 30 px desde el otro (0.25 s `ease-out`), como los horarios de su selector de citas. Van en secuencia, sin fundido cruzado, para que no se mezclen dos meses llenos de eventos. Luego vuelven a entrar los eventos.
+- **Hover:** el fondo del día cambia en 0.3 s y el número tiene resorte de radio y escala (`cubic-bezier(.38,.49,0,2)`).
+
+Origen: patrón observado en la app de Melon Mind.
+
+## HTML / Astro
+
+```html
+<mk-calendar class="mk-calendar" locale="es" first-day="0"
+  events='[{"id":1,"title":"Ana","start":"2026-10-23T10:00","status":"pending"}]'>
+  <div class="mk-calendar__header">
+    <h3 class="mk-calendar__title" data-mk-calendar-title>Calendario</h3>
+    <div class="mk-calendar__views" role="group" aria-label="Vista">
+      <button type="button" data-mk-calendar-view="month">Mes</button>
+      <button type="button" data-mk-calendar-view="week">Semana</button>
+    </div>
+    <button type="button" class="mk-calendar__nav" data-mk-calendar-prev aria-label="Anterior">←</button>
+    <button type="button" class="mk-calendar__nav" data-mk-calendar-today>Hoy</button>
+    <button type="button" class="mk-calendar__nav" data-mk-calendar-next aria-label="Siguiente">→</button>
+  </div>
+  <div data-mk-calendar-grid></div>
+</mk-calendar>
+<script>
+  import { defineElements } from '@yewdiel21/motion-kit/elements';
+  defineElements(['mk-calendar']);
+</script>
+```
+
+Sólo `[data-mk-calendar-grid]` es obligatorio. Las demás piezas del header son opcionales. Si cambias el atributo `events`, los eventos se actualizan sin perder el mes ni el foco. Sin custom element: `createCalendar(root, opciones)`.
+
+## React
+
+```tsx
+<Calendar
+  events={citas}
+  onSelect={(day) => abrirDia(day)}
+  onEventClick={(event) => abrirCita(event.id)}
+/>
+```
+
+`events` y `selected` se actualizan en el sitio. `date` y `view` son iniciales: el usuario navega libremente.
+
+## Opciones
+
+| Opción | Atributo | Por defecto | Qué hace |
+|---|---|---|---|
+| `date` | `date` | hoy | Mes o semana inicial (`Date` o `"2026-10-23"`) |
+| `view` | `view` | `'month'` | `'month'` o `'week'` |
+| `firstDay` | `first-day` | `0` | Primer día de la semana (0 = domingo) |
+| `locale` | `locale` | `'es'` | Nombres de mes y día, formato de hora |
+| `events` | `events` (JSON) | `[]` | `{ id, title, start, end?, allDay?, status?, color? }` |
+| `maxEvents` | `max-events` | `3` | Chips por día en la vista de mes antes de «+N más» |
+| `selected` | `selected` | — | Día seleccionado |
+| `today` | `today` | — | Fija «hoy» (demos, pruebas) |
+| `labels` | — | español | `more(n)`, `events(n)`, `status` |
+| `onSelect(date)`, `onEventClick(event)`, `onNavigate({start, end, view})` | — | — | Callbacks |
+
+API: `next()`, `prev()`, `goToday()`, `setDate(d)`, `setView(v)`, `setEvents(list)`, `select(d | null, notify)`, `date`, `view`, `selected`, `range`, `destroy()`. Eventos DOM: `mk:select` `{date, key}`, `mk:event` `{event}` y `mk:navigate` `{start, end, view}`.
+
+Un evento con `end` en otro día aparece en cada día que cubre, hasta dos meses.
+
+## Variables CSS
+
+`--mk-calendar-gap`, `--mk-calendar-radius`, `--mk-calendar-day-height` y `--mk-calendar-event-color` (por evento, con `color`).
+
+## Accesibilidad
+
+Rejilla ARIA (`grid` / `row` / `columnheader` / `gridcell`) con un solo botón de día en el orden de tabulación:
+
+| Tecla | Acción |
+|---|---|
+| Flechas | Día anterior/siguiente, misma semana anterior/siguiente |
+| Inicio / Fin | Principio/fin de semana |
+| RePág / AvPág | Mes anterior/siguiente (con Mayúsculas, año) |
+| Enter / Espacio | Seleccionar el día |
+
+Cada día anuncia la fecha completa y cuántos eventos tiene. Hoy lleva `aria-current="date"`. Los chips son botones con título, hora y estado. En móvil (< 680 px) los chips del mes se reducen a puntos de color. Con movimiento reducido no hay entradas, deslizamiento ni transiciones.

package/src/components/calendar/calendar.css

@@ -0,0 +1,158 @@
+/* calendar — Melon Mind's month/week grid on the --mk-* tokens; parts are .mk-calendar__*. */
+.mk-calendar,
+mk-calendar {
+  --mk-calendar-gap: 6px;
+  --mk-calendar-radius: var(--mk-radius-lg);
+  --mk-calendar-day-height: 112px;
+  display: flex;
+  flex-direction: column;
+  gap: var(--mk-space-3);
+  color: var(--mk-text);
+}
+.mk-calendar__header {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--mk-space-2);
+}
+.mk-calendar__title { margin: 0 auto 0 0; font-size: clamp(1.4rem, 2.6vw, 2rem); font-weight: 400; letter-spacing: -0.01em; }
+.mk-calendar__views { display: inline-flex; padding: 4px; gap: 2px; border-radius: var(--mk-radius-full); background: var(--mk-surface-3); }
+.mk-calendar__views button,
+.mk-calendar__nav {
+  display: inline-grid;
+  place-items: center;
+  min-width: 44px;
+  height: 44px;
+  padding: 0 12px;
+  border: 0;
+  border-radius: var(--mk-radius-full);
+  background: transparent;
+  color: var(--mk-muted);
+  font: inherit;
+  cursor: pointer;
+  transition: background 0.2s, color 0.2s, transform 0.3s var(--mk-ease-nav-move);
+}
+.mk-calendar__views button[aria-pressed='true'] { background: var(--mk-surface-5); color: var(--mk-text); }
+.mk-calendar__nav { background: var(--mk-surface-3); color: var(--mk-text); }
+.mk-calendar__nav:active { transform: scale(0.92); }
+:is(.mk-calendar__views button, .mk-calendar__nav):focus-visible { outline: 2px solid var(--mk-accent); outline-offset: 2px; }
+
+[data-mk-calendar-grid] { position: relative; display: flex; flex-direction: column; gap: var(--mk-calendar-gap); }
+.mk-calendar__head,
+.mk-calendar__week { display: grid; grid-template-columns: repeat(7, minmax(0, 1fr)); gap: var(--mk-calendar-gap); }
+.mk-calendar__body { display: flex; flex-direction: column; gap: var(--mk-calendar-gap); }
+.mk-calendar__body--leaving { position: absolute; left: 0; right: 0; pointer-events: none; }
+.mk-calendar__weekday {
+  padding: 8px 4px;
+  border-radius: var(--mk-radius-md);
+  background: var(--mk-surface-2);
+  text-align: center;
+  font-size: 0.95rem;
+}
+.mk-calendar__weekday-narrow { display: none; }
+
+.mk-calendar__day {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  min-width: 0;
+  min-height: var(--mk-calendar-day-height);
+  padding: 6px;
+  border-radius: var(--mk-calendar-radius);
+  background: var(--mk-surface-3);
+  transition: background 0.3s, box-shadow 0.3s;
+  container-type: inline-size;
+}
+.mk-calendar__body[data-view='week'] .mk-calendar__day { min-height: calc(var(--mk-calendar-day-height) * 3); }
+.mk-calendar__day[data-outside] { background: var(--mk-surface-1); color: var(--mk-muted); }
+.mk-calendar__day:hover { background: var(--mk-surface-4); }
+.mk-calendar__day[aria-selected='true'] { box-shadow: inset 0 0 0 2px var(--mk-accent); }
+.mk-calendar__number {
+  align-self: flex-end;
+  min-width: 2.2rem;
+  height: 2.2rem;
+  padding: 0 0.4rem;
+  border: 0;
+  border-radius: var(--mk-radius-full);
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  font-size: 1.15rem;
+  cursor: pointer;
+  transition: background 0.3s, color 0.3s, border-radius 0.3s var(--mk-ease-nav-radius), transform 0.3s var(--mk-ease-nav-radius);
+}
+.mk-calendar__number:hover { background: var(--mk-surface-5); }
+.mk-calendar__number:active { transform: scale(0.9); }
+.mk-calendar__number:focus-visible { outline: 2px solid var(--mk-accent); outline-offset: 2px; }
+.mk-calendar__day[data-today] .mk-calendar__number { background: var(--mk-accent); color: var(--mk-on-accent); }
+
+.mk-calendar__events { display: flex; flex-direction: column; gap: 3px; min-width: 0; }
+.mk-calendar__event,
+.mk-calendar__more {
+  --mk-calendar-event-color: var(--mk-accent);
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  width: 100%;
+  min-width: 0;
+  padding: 5px 8px;
+  border: 0;
+  border-radius: 10px;
+  background: var(--mk-surface-4);
+  color: var(--mk-text);
+  font: inherit;
+  font-size: 0.85rem;
+  text-align: left;
+  cursor: pointer;
+  transition: background 0.2s, transform 0.3s var(--mk-ease-nav-move);
+}
+.mk-calendar__event[data-state='pending'] {
+  background: color-mix(in srgb, var(--mk-calendar-event-color) 30%, var(--mk-surface-3));
+}
+.mk-calendar__event:hover,
+.mk-calendar__more:hover { transform: translateY(-1px); background: var(--mk-surface-5); }
+.mk-calendar__event:focus-visible,
+.mk-calendar__more:focus-visible { outline: 2px solid var(--mk-accent); outline-offset: 1px; }
+.mk-calendar__status {
+  flex: none;
+  width: 0.8rem;
+  height: 0.8rem;
+  border: 2px solid currentColor;
+  border-radius: 50%;
+}
+.mk-calendar__event[data-state='done'] .mk-calendar__status { background: currentColor; box-shadow: inset 0 0 0 2px var(--mk-surface-4); }
+.mk-calendar__event[data-state='cancelled'] .mk-calendar__event-title { text-decoration: line-through; opacity: 0.6; }
+.mk-calendar__event-title { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.mk-calendar__event-time { flex: none; font-variant-numeric: tabular-nums; opacity: 0.85; }
+.mk-calendar__more { justify-content: center; background: transparent; color: var(--mk-muted); }
+
+/* Narrow day cells: the month keeps the title (the time stays in the label); the week stacks the time under it. */
+@container (max-width: 150px) {
+  .mk-calendar__body[data-view='month'] .mk-calendar__event-time { display: none; }
+  .mk-calendar__body[data-view='week'] .mk-calendar__event { flex-wrap: wrap; column-gap: 5px; row-gap: 1px; }
+  .mk-calendar__body[data-view='week'] .mk-calendar__event-title { flex: 1 1 0; }
+  .mk-calendar__body[data-view='week'] .mk-calendar__event-time { flex-basis: 100%; padding-left: calc(0.8rem + 5px); font-size: 0.72rem; }
+}
+@media (max-width: 680px) {
+  .mk-calendar,
+  mk-calendar { --mk-calendar-day-height: 64px; --mk-calendar-gap: 4px; --mk-calendar-radius: var(--mk-radius-sm); }
+  .mk-calendar__weekday-long { display: none; }
+  .mk-calendar__weekday-narrow { display: inline; }
+  .mk-calendar__number { align-self: center; font-size: 0.95rem; }
+  .mk-calendar__body[data-view='month'] .mk-calendar__events { flex-direction: row; flex-wrap: wrap; justify-content: center; gap: 3px; }
+  .mk-calendar__body[data-view='month'] :is(.mk-calendar__event, .mk-calendar__more) {
+    width: 7px;
+    height: 7px;
+    padding: 0;
+    border-radius: 50%;
+    background: var(--mk-calendar-event-color);
+    font-size: 0;
+  }
+  .mk-calendar__body[data-view='month'] .mk-calendar__status { display: none; }
+  .mk-calendar__body[data-view='week'] .mk-calendar__event-time { display: none; }
+}
+@media (prefers-reduced-motion: reduce) {
+  .mk-calendar *,
+  mk-calendar * { transition: none !important; }
+}

package/src/components/calendar/element.ts

@@ -0,0 +1,27 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createCalendar, type CalendarEvent, type CalendarInstance } from './engine';
+
+/** Light DOM: supply the header and the [data-mk-calendar-grid] shown in the README. */
+export class MkCalendarElement extends MkElement<CalendarInstance> {
+  static options: Record<string, OptionType> = {
+    date: 'string', view: 'string', firstDay: 'number', locale: 'string', maxEvents: 'number', events: 'json', selected: 'string', today: 'string',
+  };
+
+  protected create(options: Record<string, unknown>) {
+    return createCalendar(this, options);
+  }
+
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.isConnected || !this.instance) return;
+    if (name === 'events') {
+      this.instance.setEvents((this.options.events as CalendarEvent[] | undefined) ?? []);
+      return;
+    }
+    // Keep where the visitor is unless the changed attribute says otherwise.
+    const { date, view, selected } = this.instance;
+    this.instance.destroy();
+    this.instance = this.create({ date, view, selected, ...this.options });
+  }
+}
+
+export const defineCalendar = () => defineElement('mk-calendar', MkCalendarElement);