@yewdiel21/motion-kit 0.18.0 → 0.19.1

package/src/components/heatmap-chart/README.md

@@ -1,48 +1,48 @@
-# heatmap-chart
-
-Calendario de actividad tipo GitHub con intensidad por día, tooltips y desplazamiento horizontal.
-
-## Instalación
-
-```tsx
-import '@yewdiel21/motion-kit/css';
-import { HeatmapChart } from '@yewdiel21/motion-kit/react';
-```
-
-```sh
-npx @yewdiel21/motion-kit add heatmap-chart --react --elements
-```
-
-## React
-
-```tsx
-<HeatmapChart end="2026-10-31" weeks={26} data={{ "2026-10-30": 4, "2026-10-31": 8 }} unit="sesiones" locale="es-MX" />
-```
-
-Los callbacks del ejemplo (`ask`, `run`, `setTool`, `setVolume`) pertenecen a tu aplicación. React acepta `className`, `style` y atributos HTML. Los componentes con estado exponen `instanceRef` (excepto PillButton).
-
-## HTML / Astro
-
-```html
-<mk-heatmap-chart end="2026-10-31" weeks="26" data='{"2026-10-30":4,"2026-10-31":8}'></mk-heatmap-chart>
-<script type="module">
-  import { defineElements } from '@yewdiel21/motion-kit/elements';
-  defineElements(['mk-heatmap-chart']);
-</script>
-```
-
-En Astro usa un `<script>` procesado por Astro. En HTML directo el import requiere bundler o import map. También puedes usar `import { createHeatmapChart } from '@yewdiel21/motion-kit'` y llamar a la factory con el contenedor y las mismas opciones. Al desmontar, llama a `instance.destroy()`.
-
-## Opciones
-
-data: {date, value}[] o mapa YYYY-MM-DD a valor. end: hoy. weeks: 53. firstDay: 1 (lunes). levels: 4. color: acento. locale, unit, legend. onSelect(date, value). Instancia: select(date | null), update(options), selected.
-
-Todos los gráficos aceptan `label`, `emptyLabel` y `formatValue`. Se actualizan con `update(options)` sin desmontarse; `select(index | null)` y `selected` controlan la selección (en heatmap se usa una fecha). `onSelect` también emite `mk:select`.
-
-Los nombres camelCase se escriben como atributos kebab-case. Los arrays y objetos se pasan como JSON. Los booleanos aceptan atributo vacío o `"false"`.
-
-## Estilos y accesibilidad
-
-Variables: --mk-heatmap-color, --mk-heatmap-empty; --mk-chart-surface.
-
-Respeta los colores del tema, foco visible y `prefers-reduced-motion`. Los gráficos incluyen una tabla accesible y selección con flechas, Home, End y Escape. Heatmap usa arriba/abajo para un día e izquierda/derecha para una semana. Toolbar usa flechas y Home/End; OrbitMenu cierra con Escape y devuelve el foco. Los controles conservan nombres accesibles; VoiceDots anuncia los estados sin leer cada fotograma.
+# heatmap-chart
+
+Calendario de actividad tipo GitHub con intensidad por día, tooltips y desplazamiento horizontal. Las semanas se desplazan con la barra de [`scroll-area`](../scroll-area/README.md), que tiene su propio carril bajo la última fila.
+
+## Instalación
+
+```tsx
+import '@yewdiel21/motion-kit/css';
+import { HeatmapChart } from '@yewdiel21/motion-kit/react';
+```
+
+```sh
+npx @yewdiel21/motion-kit add heatmap-chart --react --elements
+```
+
+## React
+
+```tsx
+<HeatmapChart end="2026-10-31" weeks={26} data={{ "2026-10-30": 4, "2026-10-31": 8 }} unit="sesiones" locale="es-MX" />
+```
+
+Los callbacks del ejemplo (`ask`, `run`, `setTool`, `setVolume`) pertenecen a tu aplicación. React acepta `className`, `style` y atributos HTML. Los componentes con estado exponen `instanceRef` (excepto PillButton).
+
+## HTML / Astro
+
+```html
+<mk-heatmap-chart end="2026-10-31" weeks="26" data='{"2026-10-30":4,"2026-10-31":8}'></mk-heatmap-chart>
+<script type="module">
+  import { defineElements } from '@yewdiel21/motion-kit/elements';
+  defineElements(['mk-heatmap-chart']);
+</script>
+```
+
+En Astro usa un `<script>` procesado por Astro. En HTML directo el import requiere bundler o import map. También puedes usar `import { createHeatmapChart } from '@yewdiel21/motion-kit'` y llamar a la factory con el contenedor y las mismas opciones. Al desmontar, llama a `instance.destroy()`.
+
+## Opciones
+
+data: {date, value}[] o mapa YYYY-MM-DD a valor. end: hoy. weeks: 53. firstDay: 1 (lunes). levels: 4. color: acento. locale, unit, legend. onSelect(date, value). Instancia: select(date | null), update(options), selected.
+
+Todos los gráficos aceptan `label`, `emptyLabel` y `formatValue`. Se actualizan con `update(options)` sin desmontarse; `select(index | null)` y `selected` controlan la selección (en heatmap se usa una fecha). `onSelect` también emite `mk:select`.
+
+Los nombres camelCase se escriben como atributos kebab-case. Los arrays y objetos se pasan como JSON. Los booleanos aceptan atributo vacío o `"false"`.
+
+## Estilos y accesibilidad
+
+Variables: --mk-heatmap-color, --mk-heatmap-empty; --mk-chart-surface.
+
+Respeta los colores del tema, foco visible y `prefers-reduced-motion`. Los gráficos incluyen una tabla accesible y selección con flechas, Home, End y Escape. Heatmap usa arriba/abajo para un día e izquierda/derecha para una semana. Toolbar usa flechas y Home/End; OrbitMenu cierra con Escape y devuelve el foco. Los controles conservan nombres accesibles; VoiceDots anuncia los estados sin leer cada fotograma.

package/src/components/heatmap-chart/engine.ts

@@ -4,6 +4,7 @@ import { reduced } from '../../core/reduced';
 import { createScope } from '../../core/scope';
 import { inert, type Instance } from '../../core/types';
 import { chartFrame, finite, formatNumber, onWidth, round, svg } from '../chart/parts';
+import { createScrollArea } from '../scroll-area/engine';
 
 /*
  * Heatmap chart: daily activity on a calendar, a column per week like
@@ -13,7 +14,8 @@ import { chartFrame, finite, formatNumber, onWidth, round, svg } from '../chart/
  * crossfades their colours. Pointing at a day (or the arrows: up and down a
  * day, left and right a week, PageUp/PageDown four) lifts it with a ring and
  * the tooltip says its value and date; the "less … more" scale lights the
- * days of a step. Narrow screens scroll the weeks, ending on the latest.
+ * days of a step. Narrow screens scroll the weeks, ending on the latest, under
+ * the kit's scroll-area bar (its own lane below the last row).
  */
 
 export interface HeatmapDatum {
@@ -70,6 +72,9 @@ export function createHeatmapChart(root: HTMLElement | null, initial: HeatmapCha
   plot.prepend(scroller);
   scroller.append(canvas);
   scope.add(() => scroller.remove());
+  // The arrows already move through the days: the bar is not a tab stop.
+  const area = createScrollArea(plot, { viewport: scroller, axis: 'x', focusable: false, decorative: true });
+  scope.add(() => area.destroy());
 
   const scale = document.createElement('div');
   scale.dataset.mkHeatmapScale = '';

package/src/components/heatmap-chart/heatmap-chart.css

@@ -13,7 +13,11 @@ mk-heatmap-chart {
   overflow-x: auto;
   overflow-y: hidden;
   padding-block: 4px;
-  scrollbar-width: thin;
+}
+
+/* Weeks that scroll leave the scroll-area bar a lane below the last row, so a click on a day never lands on it. */
+[data-mk-overflow-x] > [data-mk-heatmap-scroll] {
+  padding-bottom: 16px;
 }
 
 [data-mk-chart-type='heatmap'] [data-mk-chart-svg] {

package/src/components/icons.ts

@@ -14,6 +14,7 @@ export const ICON_PATHS = {
   mic: 'M12 3a3 3 0 00-3 3v6a3 3 0 006 0V6a3 3 0 00-3-3zM5.5 11a6.5 6.5 0 0013 0M12 17.5V21',
   sparkle: 'M12 3l1.9 5.1L19 10l-5.1 1.9L12 17l-1.9-5.1L5 10l5.1-1.9z',
   grip: 'M9 6h.01M15 6h.01M9 12h.01M15 12h.01M9 18h.01M15 18h.01',
+  toTop: 'M12 20V9M6.5 14.5L12 9l5.5 5.5M6 4.5h12',
 } as const;
 
 export type IconName = keyof typeof ICON_PATHS;

package/src/components/pill-button/engine.ts

@@ -7,7 +7,7 @@ import { press } from '../../motion/micro';
  * Pill button: a dark pill with a label and an arrow. When the pointer comes in
  * (or the keyboard focuses it) the dark fill gathers into a circle around the
  * icon on the swatch curve (.38,.49,0,1.5, a small overshoot), the label slides
- * left and turns to the text colour, and the arrow nudges forward; leaving, the
+ * left and turns to the text colour, and the arrow stays centred; leaving, the
  * fill spreads back into the pill. `expand` turns it around: a circle by the
  * label that spreads into the pill. The motion is CSS (pill-button.css); the
  * engine builds the label, icon and fill when the markup lacks them, presses on

package/src/components/pill-button/pill-button.css

@@ -51,19 +51,24 @@ mk-pill-button {
 
 [data-mk-pill-icon] {
   display: inline-grid;
+  flex: none;
   place-items: center;
   width: 1.125rem;
   height: 1.125rem;
+  font-size: 1.125rem;
   color: var(--mk-pill-on-ink);
-  transition: transform 0.45s var(--mk-ease-swatch);
 }
 
-[data-mk-pill-icon] svg {
+[data-mk-pill-icon] :is(svg, .mk-icon) {
   display: block;
   width: 100%;
   height: 100%;
 }
 
+[data-mk-pill-icon] .mk-icon {
+  font-size: inherit;
+}
+
 /* Gathered: on hover, keyboard focus or a tap. */
 @media (hover: hover) {
   :is([data-mk-pill=''], .mk-pill-button:is(button, a):not([data-mk-pill])):hover [data-mk-pill-fill] {
@@ -73,9 +78,6 @@ mk-pill-button {
     color: var(--mk-pill-ink);
     transform: translateX(-0.5rem);
   }
-  :is([data-mk-pill], .mk-pill-button:is(button, a)):hover [data-mk-pill-icon] {
-    transform: translateX(2px);
-  }
 }
 [data-mk-pill='']:is(:focus-visible, [data-mk-active]) [data-mk-pill-fill] {
   clip-path: var(--mk-pill-gathered);

package/src/components/scroll-area/README.md

@@ -0,0 +1,89 @@
+# scroll-area
+
+Área desplazable con barras propias del kit en lugar de la barra del sistema. El desplazamiento sigue siendo el nativo: teclado, tacto, inercia, `scroll-snap` y buscar en la página funcionan como siempre.
+
+Origen: Melonmind oculta las barras nativas (`::-webkit-scrollbar { display: none }`) y no tiene barra visible. Esta barra se construye con su lenguaje: píldoras, superficies tonales y sus curvas.
+
+- **Reposo:** una píldora de 6 px (el texto al 32 %) que aparece al pasar el puntero o al desplazarte y se desvanece 0,9 s después.
+- **Hover:** sobre la barra aparece un carril tonal y la píldora crece a 10 px con la curva swing (`.38,.49,0,1.5`).
+- **Arrastre:** al agarrarla se presiona (curva click), toma el acento y sigue al puntero sin suavizado.
+- **Clic en el carril:** desliza hasta ese punto (0,6 s, curva signature). La rueda, un toque, una tecla u otro agarre lo cortan.
+- **Bordes y volver arriba:** los bordes con más contenido se funden. Con `backToTop`, una píldora tonal entra con pop cuando has bajado una pantalla.
+
+## HTML / Astro
+
+```html
+<mk-scroll-area class="mk-scroll-area" style="height: 20rem" label="Notas" back-to-top>
+  <article>…contenido largo…</article>
+</mk-scroll-area>
+<script>
+  import { defineElements } from '@yewdiel21/motion-kit/elements';
+  defineElements(['mk-scroll-area']);
+</script>
+```
+
+El contenido se envuelve en un viewport `[data-mk-scroll-viewport]`; al destruirlo vuelve a su sitio.
+
+## React
+
+```tsx
+<ScrollArea style={{ height: 320 }} label="Notas" backToTop onScroll={({ y }) => setRead(y)}>
+  <article>…</article>
+</ScrollArea>
+```
+
+## Vanilla
+
+```ts
+const area = createScrollArea(document.querySelector('.panel'), { axis: 'y' });
+area.scrollTo({ top: 0 });
+// Con un scroller que ya existe dentro de la raíz (no se envuelve nada):
+createScrollArea(dialog, { viewport: dialog.querySelector('.list'), focusable: false, decorative: true });
+```
+
+**El área necesita una altura (`height` o `max-height`).** Si el contenido cabe, no se muestra ninguna barra.
+
+## Opciones
+
+| Opción | Atributo | Por defecto | Qué hace |
+|---|---|---|---|
+| `visibility` | `visibility` | `'hover'` | `hover`: al pasar el puntero por el área o al desplazarte. `scroll`: solo al desplazarte. `always`: siempre que haya desbordamiento. Con el puntero encima, la barra siempre se ve. |
+| `axis` | `axis` | `'both'` | `y`, `x` o `both`. Cada barra solo aparece si su eje desborda. |
+| `idle` | `idle` | `900` | ms antes de ocultarse. |
+| `fade` | `fade` | `true` | Funde los bordes con contenido oculto hasta 24 px. `false` lo quita; un número fija la profundidad. |
+| `backToTop` | `back-to-top` | `false` | Botón «Volver arriba». `true`: aparece tras bajar una altura del área; un número: tras esos px. |
+| `label` | `label` | — | Nombre accesible; el viewport pasa a ser una `region`. |
+| `focusable` | `focusable` | `true` | El viewport entra en el orden de Tab para desplazarlo con el teclado. `false` si su contenido ya recibe foco (un menú). |
+| `decorative` | `decorative` | `false` | Saca las barras del árbol accesible: dentro de un `menu` o `listbox`, cuyos hijos deben ser sus opciones. |
+| `viewport` | — | — | Un scroller que ya existe dentro de la raíz; se usa tal cual. |
+| `onScroll({ x, y })` | — | — | Progreso de cada eje, de 0 a 1. |
+
+## API
+
+`scrollTo({ top, left }, { animate = true })` desliza (salta con `animate: false` o con movimiento reducido). `refresh()` vuelve a medir. `viewport` es el elemento que se desplaza. `destroy()` lo deshace todo.
+
+## Eventos
+
+`mk:scroll` con `{ x, y }`.
+
+## Variables CSS
+
+| Variable | Qué controla |
+|---|---|
+| `--mk-scroll-thumb` | Píldora en reposo (texto al 32 %). |
+| `--mk-scroll-thumb-hover` | Píldora con el puntero encima (48 %). |
+| `--mk-scroll-thumb-active` | Píldora mientras se arrastra (el acento). |
+| `--mk-scroll-rail` | Carril tonal (6 %). |
+| `--mk-scroll-inset` | Distancia de los extremos de la barra a las esquinas (6 px). Súbela en contenedores muy redondeados. |
+
+El motor escribe `--mk-scroll-fade-top/right/bottom/left` en el viewport y `--mk-scroll-view-top/right/bottom/left` en las barras: las barras siguen la caja del viewport aunque la raíz sea más grande (una paleta con campo y pie, el cuerpo de un diálogo).
+
+## Accesibilidad
+
+- **Viewport:** desplazamiento nativo y `tabindex="0"`; con `label` es una región con nombre. Al enfocarlo con el teclado, el área muestra un anillo de acento.
+- **Barras:** `role="scrollbar"` con `aria-controls`, `aria-orientation` y `aria-valuenow` (0–100). No son paradas de Tab: el teclado desplaza el viewport.
+- **Volver arriba:** es un `<button>` con nombre. Si desaparece mientras tiene el foco, el foco pasa al área.
+- **Tacto:** se arrastra la píldora con `touch-action: none` y se mantiene la inercia del sistema.
+- **Movimiento reducido:** sin crecimientos, fundidos animados ni deslizamientos; la barra salta a su sitio y todo sigue funcionando.
+
+`destroy()` mata las animaciones, suelta la captura del puntero, limpia temporizadores, observadores y eventos, quita las barras y devuelve el contenido.

package/src/components/scroll-area/element.ts

@@ -0,0 +1,35 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createScrollArea, type ScrollAreaInstance, type ScrollAreaOptions } from './engine';
+
+/** `fade` / `back-to-top`: present or "true" → true, "false" → false, a number → that many px. */
+const flagOrNumber = (raw: unknown): boolean | number | undefined => {
+  if (raw === undefined) return undefined;
+  const text = String(raw).trim();
+  if (text === '' || text === 'true') return true;
+  if (text === 'false') return false;
+  const value = Number(text);
+  return Number.isFinite(value) ? value : true;
+};
+
+/**
+ * <mk-scroll-area class="mk-scroll-area" style="height: 20rem" back-to-top>…</mk-scroll-area>
+ * Its content is wrapped in the viewport. Emits mk:scroll ({x, y}).
+ */
+export class MkScrollAreaElement extends MkElement<ScrollAreaInstance> {
+  static options: Record<string, OptionType> = {
+    visibility: 'string',
+    axis: 'string',
+    idle: 'number',
+    fade: 'string',
+    backToTop: 'string',
+    label: 'string',
+    focusable: 'boolean',
+    decorative: 'boolean',
+  };
+
+  protected create(options: Record<string, unknown>) {
+    return createScrollArea(this, { ...options, fade: flagOrNumber(options.fade), backToTop: flagOrNumber(options.backToTop) } as ScrollAreaOptions);
+  }
+}
+
+export const defineScrollArea = () => defineElement('mk-scroll-area', MkScrollAreaElement);