@yewdiel21/motion-kit 0.17.0 → 0.19.0

package/src/components/badge-button/README.md

@@ -0,0 +1,28 @@
+# Badge button
+
+Botón con contador: el primer elemento hace aparecer el badge con `pop`; las cifras cambian con `rollDigits` y una pequeña pulsación `swatch`. El valor y el nombre accesible se actualizan en el momento de la acción. El badge visual usa `99+` por defecto, mientras el nombre conserva la cantidad real.
+
+```ts
+import { createBadgeButton } from '@yewdiel21/motion-kit';
+import '@yewdiel21/motion-kit/css/badge-button';
+const button = createBadgeButton(document.querySelector('#pending'), {
+  count: 0, onChange: (count) => updateLocalList(count),
+});
+button.setCount(10); // sin notificar
+button.setCount(0, true);
+// button.destroy();
+```
+
+`BadgeButtonOptions`: `label` (Guardar, cuando falta contenido), `count` (0), `step` (1, incremento por activación; admite 0 y valores negativos), `hideZero` (true), `max` (99), `onChange(count)`. Los valores se redondean y limitan a enteros no negativos. `BadgeButtonInstance`: `setCount(count, notify = false)`, `count`, `destroy()`. Emite `mk:change` con `{count}` al notificar. Un paso 0 conserva el contador y permite que la app gestione su acción con un listener nativo.
+
+```tsx
+<BadgeButton label="Añadir pendiente" count={count} onChange={setCount} />
+```
+
+React admite `count` controlado o `defaultCount`, atributos de botón e `instanceRef`. El valor controlado sigue siendo la autoridad si el padre rechaza un cambio. Usa `label`; los hijos y `dangerouslySetInnerHTML` se filtran en ejecución. Cambiar presentación conserva el estado no controlado.
+
+```html
+<mk-badge-button count="0" hide-zero="true"><button type="button">Añadir pendiente</button></mk-badge-button>
+```
+
+`defineBadgeButton()` registra `MkBadgeButtonElement`; atributos `label`, `count`, `step`, `hide-zero`, `max`. Conserva el contador vivo en cambios de presentación y reconexiones; el atributo `count` explícito lo reemplaza. El botón nativo tiene type button por defecto y respeta disabled. Movimiento reducido actualiza directamente. `destroy()` restaura el contenido y estilos escritos por el consumidor y libera las animaciones y eventos.

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

@@ -0,0 +1,15 @@
+.mk-badge-button,
+mk-badge-button { display: inline-flex; }
+[data-mk-badge-button] {
+  display: inline-flex; align-items: center; justify-content: center; gap: .7rem; position: relative;
+  min-height: 48px; padding: .65rem 1rem .65rem 1.25rem; border: 1px solid var(--mk-outline-soft); border-radius: 16px;
+  background: var(--mk-surface-3); color: var(--mk-text); font: 500 .9375rem var(--mk-font); cursor: pointer;
+  transition: background 160ms, border-radius 320ms var(--mk-ease-swatch);
+}
+[data-mk-badge-button]:hover:not(:disabled) { border-radius: 24px; background: var(--mk-surface-4); }
+[data-mk-badge-button]:focus-visible { outline: 2px solid var(--mk-accent); outline-offset: 4px; }
+[data-mk-badge-button]:disabled,
+[data-mk-badge-button][aria-disabled='true'] { opacity: .4; cursor: not-allowed; }
+[data-mk-badge-count] { display: inline-grid; place-items: center; min-width: 26px; height: 26px; padding: 0 6px; border-radius: 999px; background: var(--mk-accent); color: var(--mk-on-accent); font-size: .75rem; font-weight: 650; font-variant-numeric: tabular-nums; }
+[data-mk-badge-count][hidden] { display: none; }
+@media (prefers-reduced-motion: reduce) { [data-mk-badge-button] { transition: none; } }

package/src/components/badge-button/element.ts

@@ -0,0 +1,16 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createBadgeButton, type BadgeButtonInstance } from './engine';
+
+export class MkBadgeButtonElement extends MkElement<BadgeButtonInstance> {
+  static options: Record<string, OptionType> = { label: 'string', count: 'number', step: 'number', hideZero: 'boolean', max: 'number' };
+  private retained: number | undefined;
+  protected create(options: Record<string, unknown>) { return createBadgeButton(this, { ...options, ...(this.retained === undefined ? {} : { count: this.retained }) }); }
+  disconnectedCallback() { this.retained = this.instance?.count ?? this.retained; super.disconnectedCallback(); }
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    const focused = this.contains(document.activeElement);
+    if (previous !== next) this.retained = name === 'count' ? undefined : this.instance?.count ?? this.retained;
+    super.attributeChangedCallback(name, previous, next);
+    if (focused) this.querySelector<HTMLButtonElement>('button')?.focus({ preventScroll: true });
+  }
+}
+export const defineBadgeButton = () => defineElement('mk-badge-button', MkBadgeButtonElement);

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

@@ -0,0 +1,85 @@
+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 { press, rollDigits } from '../../motion/micro';
+
+export interface BadgeButtonOptions {
+  label?: string;
+  count?: number;
+  /** Increment requested by an activation; use 0 for a host-owned count. Default 1. */
+  step?: number;
+  /** Hide the badge when its count is zero (default true). */
+  hideZero?: boolean;
+  max?: number;
+  onChange?: (count: number) => void;
+}
+export interface BadgeButtonInstance extends Instance {
+  setCount(count: number, notify?: boolean): void;
+  readonly count: number;
+}
+const normalize = (value: number) => Number.isFinite(value) ? Math.max(0, Math.min(Number.MAX_SAFE_INTEGER, Math.round(value))) : 0;
+let sequence = 0;
+export function createBadgeButton(root: HTMLElement | null, options: BadgeButtonOptions = {}): BadgeButtonInstance {
+  if (!root) return inert({ setCount() {}, count: 0 });
+  registerMotion();
+  const scope = createScope();
+  let button = root.matches('button') ? root as HTMLButtonElement : root.querySelector<HTMLButtonElement>('button');
+  if (!button) { button = document.createElement('button'); root.append(button); const made = button; scope.add(() => made.remove()); }
+  const control = button;
+  if (!control.textContent?.trim() && !control.querySelector('[aria-label], svg, img')) {
+    const label = document.createElement('span'); label.textContent = options.label ?? 'Guardar'; control.append(label); scope.add(() => label.remove());
+  }
+  const originalStyle = control.getAttribute('style');
+  const originalTransform = control.style.transform;
+  scope.add(() => { if (originalStyle === null) control.removeAttribute('style'); else control.setAttribute('style', originalStyle); });
+  const badge = document.createElement('span'); badge.dataset.mkBadgeCount = ''; badge.setAttribute('aria-hidden', 'true'); control.append(badge); scope.add(() => badge.remove());
+  // Keep the actual quantity in the accessible name even when the visual badge reads "99+".
+  const spoken = document.createElement('span'); spoken.className = 'mk-sr-only'; control.append(spoken); scope.add(() => spoken.remove());
+  const authoredLabel = control.getAttribute('aria-label');
+  const labelledBy = control.getAttribute('aria-labelledby');
+  if (labelledBy?.trim()) {
+    spoken.id = `mk-badge-quantity-${++sequence}`;
+    scope.attr(control, 'aria-labelledby', `${labelledBy} ${spoken.id}`);
+  }
+  scope.attr(control, 'type', control.getAttribute('type') ?? 'button');
+  scope.attr(control, 'data-mk-badge-button', '');
+  scope.attr(root, 'data-mk-ready', '');
+  let count = normalize(options.count ?? 0);
+  const max = Math.max(1, normalize(options.max ?? 99));
+  const step = Number.isFinite(options.step) ? Math.round(options.step!) : 1;
+  let rolling: gsap.core.Animation | null = null;
+  let bump: gsap.core.Animation | null = null;
+  let pressing: gsap.core.Animation | null = null;
+  const format = () => count > max ? `${max}+` : String(count);
+  const announce = () => {
+    spoken.textContent = ` (${count})`;
+    if (!labelledBy?.trim() && authoredLabel?.trim()) scope.attr(control, 'aria-label', `${authoredLabel} (${count})`);
+  };
+  const paint = () => { badge.hidden = options.hideZero !== false && count === 0; badge.textContent = format(); announce(); };
+  const setCount = (next: number, notify = false) => {
+    if (scope.disposed || !Number.isFinite(next)) return;
+    const previous = count;
+    count = normalize(next);
+    if (count === previous) return;
+    const wasHidden = badge.hidden;
+    badge.hidden = options.hideZero !== false && count === 0;
+    announce();
+    rolling?.kill(); bump?.kill();
+    if (reduced() || badge.hidden) paint();
+    else {
+      rolling = rollDigits(badge, format(), count >= previous ? 1 : -1, .34);
+      bump = gsap.fromTo(badge, { scale: wasHidden ? .35 : .8, y: wasHidden ? 7 : 0 }, { scale: 1, y: 0, duration: .5, ease: wasHidden ? EASE.pop : EASE.swatch });
+    }
+    if (notify) { options.onChange?.(count); root.dispatchEvent(new CustomEvent('mk:change', { bubbles: true, detail: { count } })); }
+  };
+  scope.on(control, 'click', (event) => {
+    if (control.disabled || control.getAttribute('aria-disabled') === 'true') { event.preventDefault(); return; }
+    pressing?.kill(); pressing = press(control);
+    pressing?.eventCallback('onComplete', () => { gsap.set(control, { clearProps: 'transform,scale' }); control.style.transform = originalTransform; if (!control.getAttribute('style')) control.removeAttribute('style'); });
+    setCount(count + step, true);
+  });
+  paint();
+  scope.add(() => { rolling?.kill(); bump?.kill(); pressing?.kill(); gsap.killTweensOf(badge); });
+  return { setCount, get count() { return count; }, destroy: () => scope.dispose() };
+}

package/src/components/badge-button/react.tsx

@@ -0,0 +1,31 @@
+'use client';
+import { useRef, type ButtonHTMLAttributes, type Ref } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createBadgeButton, type BadgeButtonInstance, type BadgeButtonOptions } from './engine';
+
+export interface BadgeButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children' | 'dangerouslySetInnerHTML' | 'onChange'>, BadgeButtonOptions {
+  defaultCount?: number;
+  instanceRef?: Ref<BadgeButtonInstance>;
+}
+export function BadgeButton({ label = 'Guardar', count, defaultCount = 0, step, hideZero, max, onChange, instanceRef, type = 'button', className, ...props }: BadgeButtonProps) {
+  const { children: _children, dangerouslySetInnerHTML: _html, ...safe } = props as ButtonHTMLAttributes<HTMLButtonElement>;
+  const root = useRef<HTMLButtonElement>(null);
+  const instance = useRef<BadgeButtonInstance | null>(null);
+  const current = useLatest({ count, onChange });
+  const retained = useRef(defaultCount);
+  useIsomorphicLayoutEffect(() => {
+    let created: BadgeButtonInstance;
+    created = createBadgeButton(root.current, {
+      label, count: current.current.count ?? retained.current, step, hideZero, max,
+      onChange: (next) => { current.current.onChange?.(next); if (current.current.count !== undefined) created.setCount(current.current.count); },
+    });
+    instance.current = created;
+    return () => { retained.current = created.count; created.destroy(); instance.current = null; };
+  }, [label, step, hideZero, max]);
+  useIsomorphicLayoutEffect(() => { if (count !== undefined) instance.current?.setCount(count); }, [count]);
+  useIsomorphicLayoutEffect(() => {
+    if (typeof instanceRef === 'function') instanceRef(instance.current); else if (instanceRef) instanceRef.current = instance.current;
+    return () => { if (typeof instanceRef === 'function') instanceRef(null); else if (instanceRef) instanceRef.current = null; };
+  }, [instanceRef, label, step, hideZero, max]);
+  return <button {...safe} type={type} ref={root} className={['mk-badge-button', className].filter(Boolean).join(' ')} />;
+}

package/src/components/bento-grid/README.md

@@ -0,0 +1,26 @@
+# Bento grid
+
+A reusable responsive authored grid. Existing cards travel with Flip when reordered or filtered; entering cards pop through a short blur. No hover-repulsion recipe is required.
+
+```html
+<div id="grid">
+  <article data-mk-bento-item="activity" data-mk-col-span="2" data-mk-category="work">…</article>
+  <article data-mk-bento-item="notes" data-mk-row-span="2" data-mk-category="work files">…</article>
+</div>
+```
+
+```ts
+const grid = createBentoGrid(document.querySelector('#grid'), { columns: 3, gap: 12 });
+grid.setFilter('files'); // null shows everything
+grid.reorder(['notes', 'activity']);
+grid.mutate(() => document.querySelector('#grid').append(newCard));
+grid.destroy();
+```
+
+Exports: `createBentoGrid`, `BentoGridOptions`, `BentoGridInstance`; React `BentoGrid`, `BentoGridProps`; elements `MkBentoGridElement`, `defineBentoGrid` (`mk-bento-grid`). CSS: `bento-grid.css` plus kit tokens/theme/fonts.
+
+Options: `columns` (default 3, bounded 1–12), `gap` (pixels, default 12), `filter` (category or null), `duration` (seconds, default .55), `onChange(keys)`. Direct children opt in with unique `data-mk-bento-item` keys; column/row spans default to one. The grid reduces to two columns below 440px of its own width and one below 280px; spans clamp to available columns.
+
+Instance: `refresh()`, `setFilter(filter)`, `reorder(keys)`, `mutate(change)`, `setOptions(partial)`, readonly `filter`/`keys` (visible order), `destroy()`. `mk:change` carries `{keys,filter}`. `mutate` measures before authored DOM edits; a MutationObserver also handles framework additions and authored category/span changes. Unknown/duplicate reorder keys are ignored; unlisted keys follow in their existing order. Focus survives reordering; filtering a focused card returns focus to the grid. Filtered cards are hidden and inert. Customize the empty copy with `data-mk-empty-label`.
+
+React deliberately accepts authored children with stable keys and the same data attributes. Change their array order to reorder declaratively. Elements accept scalar option attributes and expose the instance methods. Destroy restores authored attributes and original order, retaining externally added children. Reduced motion keeps filtering and layout immediate.

package/src/components/bento-grid/bento-grid.css

@@ -0,0 +1,12 @@
+.mk-bento-grid, mk-bento-grid { container-type: inline-size; display: grid; grid-template-columns: repeat(var(--mk-bento-columns, 3), minmax(0, 1fr)); grid-auto-rows: minmax(112px, auto); gap: var(--mk-bento-gap, 12px); color: var(--mk-text); font-family: var(--mk-font); }
+.mk-bento-grid > [data-mk-bento-item], mk-bento-grid > [data-mk-bento-item] { box-sizing: border-box; min-width: 0; grid-column: span var(--mk-bento-col-span, 1); grid-row: span var(--mk-bento-row-span, 1); padding: 20px; border-radius: 24px; background: var(--mk-surface); transition: background .2s, box-shadow .25s; }
+.mk-bento-grid > [data-mk-bento-item][hidden], mk-bento-grid > [data-mk-bento-item][hidden] { display: none !important; }
+.mk-bento-grid > [data-mk-bento-item]:focus-within, mk-bento-grid > [data-mk-bento-item]:focus-within { background: var(--mk-surface-2); }
+.mk-bento-grid :is(a,button):focus-visible, mk-bento-grid :is(a,button):focus-visible { outline: 2px solid var(--mk-accent); outline-offset: 4px; }
+.mk-bento-grid :is(button,a)[aria-disabled=true], .mk-bento-grid button:disabled { opacity: .4; cursor: not-allowed; }
+.mk-bento-grid[data-mk-empty]::after, mk-bento-grid[data-mk-empty]::after { content: attr(data-mk-empty-label); grid-column: 1 / -1; min-height: 112px; display: grid; place-items: center; border-radius: 24px; color: var(--mk-muted); background: var(--mk-surface); font-size: 13px; }
+@media (hover: hover) { :is(.mk-bento-grid,mk-bento-grid) > [data-mk-bento-item]:hover { background: var(--mk-surface-2); box-shadow: 0 10px 24px -24px var(--mk-text); } }
+/* The container can be a 640px playground card, independent of viewport width. */
+@container (max-width: 440px) { :is(.mk-bento-grid,mk-bento-grid) > [data-mk-bento-item] { grid-column: span min(var(--mk-bento-col-span, 1), 2); padding: 16px; border-radius: 16px; } }
+@media (max-width: 480px) { :is(.mk-bento-grid,mk-bento-grid) > [data-mk-bento-item] { padding: 16px; border-radius: 16px; } }
+@media (prefers-reduced-motion: reduce) { :is(.mk-bento-grid,mk-bento-grid) * { transition: none !important; } }

package/src/components/bento-grid/element.ts

@@ -0,0 +1,22 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createBentoGrid, type BentoGridInstance, type BentoGridOptions } from './engine';
+
+export class MkBentoGridElement extends MkElement<BentoGridInstance> {
+  static options: Record<string, OptionType> = {"columns":"number","gap":"number","filter":"string","duration":"number"};
+  protected create(options: Record<string, unknown>) { return createBentoGrid(this, options); }
+  setOptions(options: Partial<BentoGridOptions>) { this.instance?.setOptions(options); }
+
+  refresh() { this.instance?.refresh(); }
+  setFilter(filter: string | null) { this.instance?.setFilter(filter); }
+  reorder(keys: string[]) { this.instance?.reorder(keys); }
+  mutate(change: () => void) { this.instance?.mutate(change); }
+  get filter() { return this.instance?.filter ?? null; }
+  get keys() { return this.instance?.keys ?? []; }
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.isConnected || !this.instance) return;
+    const option = name.replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase());
+    const defaults: Record<string, unknown> = {"columns":3,"gap":12,"filter":null,"duration":0.55};
+    this.instance.setOptions({ [option]: this.options[option] ?? defaults[option] });
+  }
+}
+export const defineBentoGrid = () => defineElement('mk-bento-grid', MkBentoGridElement);

package/src/components/bento-grid/engine.ts

@@ -0,0 +1,153 @@
+import { Flip, gsap, EASE, registerMotion } from '../../core/gsap';
+import { createScope } from '../../core/scope';
+import { reduced } from '../../core/reduced';
+import { inert, type Instance } from '../../core/types';
+import { blurIn, press } from '../../motion/micro';
+
+export interface BentoGridOptions {
+  columns?: number;
+  gap?: number;
+  /** Matches a whitespace-separated data-mk-category. Null shows every item. */
+  filter?: string | null;
+  duration?: number;
+  onChange?: (keys: string[]) => void;
+}
+export interface BentoGridInstance extends Instance {
+  refresh(): void;
+  setFilter(filter: string | null): void;
+  reorder(keys: string[]): void;
+  /** Capture before an authored DOM mutation (add/remove/replace), then animate to its layout. */
+  mutate(change: () => void): void;
+  setOptions(options: Partial<BentoGridOptions>): void;
+  readonly filter: string | null;
+  readonly keys: string[];
+}
+
+/** Authored direct children are the grid items. Spans live in data-mk-col-span / data-mk-row-span. */
+export function createBentoGrid(root: HTMLElement | null, options: BentoGridOptions = {}): BentoGridInstance {
+  if (!root) return inert({ refresh() {}, setFilter() {}, reorder() {}, mutate() {}, setOptions() {}, filter: null, keys: [] });
+  registerMotion();
+  const scope = createScope();
+  let opts = { ...options };
+  let filter = opts.filter ?? null;
+  let animation: gsap.core.Timeline | null = null;
+  const micro = new Set<gsap.core.Animation>();
+  const track = (value: gsap.core.Animation | null) => { if (value) micro.add(value); };
+  const originals = [...root.childNodes];
+  const originalItems = new Set(root.children);
+  const remembered = new Set<HTMLElement>();
+  let queued = 0;
+  scope.attr(root, 'class', `${root.className} mk-bento-grid`.trim());
+  scope.attr(root, 'style', root.getAttribute('style'));
+  scope.attr(root, 'data-mk-ready', '');
+  const items = () => [...root.children].filter((node): node is HTMLElement => node instanceof HTMLElement && node.hasAttribute('data-mk-bento-item'));
+  const key = (item: HTMLElement) => item.dataset.mkBentoItem!;
+  const visible = () => items().filter((item) => !item.hidden);
+  const save = (item: HTMLElement) => {
+    if (remembered.has(item)) return;
+    remembered.add(item);
+    for (const attr of ['style', 'hidden', 'inert', 'aria-hidden', 'data-flip-id']) scope.attr(item, attr, item.getAttribute(attr));
+  };
+  items().forEach(save);
+  let last: ReturnType<typeof Flip.getState> | undefined;
+  const notify = () => {
+    const keys = visible().map(key);
+    opts.onChange?.(keys);
+    root.dispatchEvent(new CustomEvent('mk:change', { bubbles: true, detail: { keys, filter } }));
+  };
+  const paint = () => {
+    const desired = Number.isFinite(opts.columns) ? Math.max(1, Math.min(12, Math.round(opts.columns!))) : 3;
+    const cols = root.clientWidth > 0 && root.clientWidth < 280 ? 1 : root.clientWidth > 0 && root.clientWidth < 440 ? Math.min(2, desired) : desired;
+    root.style.setProperty('--mk-bento-columns', String(cols));
+    root.style.setProperty('--mk-bento-gap', `${Math.max(0, opts.gap ?? 12)}px`);
+    items().forEach((item) => {
+      save(item);
+      item.style.setProperty('--mk-bento-col-span', String(Math.max(1, Math.min(cols, Number(item.dataset.mkColSpan) || 1))));
+      item.style.setProperty('--mk-bento-row-span', String(Math.max(1, Math.min(8, Number(item.dataset.mkRowSpan) || 1))));
+      const show = !filter || (item.dataset.mkCategory ?? '').split(/\s+/).includes(filter);
+      if (!show && item.contains(document.activeElement)) { scope.attr(root, 'tabindex', root.getAttribute('tabindex')); root.tabIndex = -1; root.focus(); }
+      item.hidden = !show;
+      item.inert = !show;
+      item.setAttribute('aria-hidden', String(!show));
+    });
+    scope.attr(root, 'data-mk-empty', visible().length ? null : '');
+    if (!root.hasAttribute('data-mk-empty-label')) scope.attr(root, 'data-mk-empty-label', 'No hay elementos en esta vista.');
+  };
+  const transition = (state = last, entering: HTMLElement[] = []) => {
+    if (scope.disposed) return;
+    animation?.kill();
+    paint();
+    if (!reduced()) {
+      animation = Flip.from(state ?? Flip.getState([]), { targets: visible(), duration: Math.max(0, opts.duration ?? .55), ease: EASE.signature, stagger: .025, absolute: false, scale: false, prune: true, onComplete: () => { if (!scope.disposed) last = Flip.getState(visible()); } });
+      track(blurIn(entering.filter((item) => !item.hidden), { from: 'soft', stagger: .04, duration: .35 }));
+    }
+    if (!reduced()) last = Flip.getState(visible());
+  };
+  const capture = () => {
+    animation?.kill();
+    if (reduced()) return undefined;
+    const focused = document.activeElement as HTMLElement | null;
+    Flip.killFlipsOf(items());
+    const state = Flip.getState(visible());
+    if (focused?.isConnected && focused !== document.activeElement) focused.focus({ preventScroll: true });
+    return state;
+  };
+  const mutate = (change: () => void) => {
+    if (scope.disposed) return;
+    const focused = document.activeElement as HTMLElement | null;
+    const state = capture();
+    const before = new Set(items());
+    change();
+    transition(state, items().filter((item) => !before.has(item)));
+    if (focused && focused !== document.body && root.contains(focused) && !focused.closest('[hidden], [inert]')) focused.focus({ preventScroll: true });
+    else if (focused && !focused.isConnected) { scope.attr(root, 'tabindex', root.getAttribute('tabindex')); root.tabIndex = -1; root.focus(); }
+    observer?.takeRecords();
+    notify();
+  };
+  const setFilter = (next: string | null) => {
+    if (scope.disposed || next === filter) return;
+    const state = capture();
+    const before = new Set(visible());
+    filter = next;
+    paint();
+    transition(state, visible().filter((item) => !before.has(item)));
+    notify();
+  };
+  const refresh = () => {
+    if (scope.disposed) return;
+    transition(last, items().filter((item) => !remembered.has(item)));
+  };
+  const observer = typeof MutationObserver === 'function' ? scope.observe(new MutationObserver((records) => {
+    // Observe authored data only: engine style/hidden writes and nested content
+    // changes must not schedule another layout or create an observer loop.
+    if (!records.some((record) => record.type === 'childList' ? record.target === root : record.target instanceof HTMLElement && record.target.parentElement === root)) return;
+    cancelAnimationFrame(queued);
+    queued = requestAnimationFrame(refresh);
+  })) : null;
+  observer?.observe(root, { childList: true, subtree: true, attributes: true, attributeFilter: ['data-mk-category', 'data-mk-col-span', 'data-mk-row-span'] });
+  scope.on(root, 'click', (event) => {
+    const control = (event.target as Element).closest<HTMLElement>('button, a');
+    if (control && root.contains(control) && !control.matches(':disabled, [aria-disabled="true"]')) { scope.attr(control, 'style', control.getAttribute('style')); track(press(control)); }
+  });
+  if (typeof ResizeObserver === 'function') {
+    let width = root.clientWidth;
+    const resize = scope.observe(new ResizeObserver(() => { if (root.clientWidth !== width) { width = root.clientWidth; animation?.kill(); paint(); last = Flip.getState(visible()); } }));
+    resize.observe(root);
+  }
+  paint(); if (!reduced()) last = Flip.getState(visible());
+  track(blurIn(visible(), { from: 'soft', stagger: .04 }));
+  return {
+    refresh, mutate, setFilter,
+    reorder(keys) { mutate(() => { const byKey = new Map(items().map((item) => [key(item), item])); for (const id of new Set(keys)) { const item = byKey.get(id); if (item) { root.append(item); byKey.delete(id); } } byKey.forEach((item) => root.append(item)); }); },
+    setOptions(next) { if (scope.disposed) return; const state = capture(); opts = { ...opts, ...next }; if (next.filter !== undefined) filter = next.filter; transition(state); },
+    get filter() { return filter; }, get keys() { return visible().map(key); },
+    destroy() {
+      if (scope.disposed) return;
+      cancelAnimationFrame(queued); animation?.kill(); micro.forEach((value) => value.kill()); if (!reduced()) Flip.killFlipsOf(items()); gsap.killTweensOf([...remembered]);
+      scope.dispose();
+      // Preserve externally added content while restoring the initial authored order.
+      const added = [...root.childNodes].filter((node) => !originals.includes(node) && !(node instanceof Element && originalItems.has(node)));
+      root.replaceChildren(...originals, ...added);
+    },
+  };
+}

package/src/components/bento-grid/react.tsx

@@ -0,0 +1,25 @@
+'use client';
+import { useRef, type HTMLAttributes, type MutableRefObject } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createBentoGrid, type BentoGridOptions, type BentoGridInstance } from './engine';
+
+export interface BentoGridProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'>, BentoGridOptions {
+  instanceRef?: MutableRefObject<BentoGridInstance | null>;
+
+}
+export function BentoGrid({ columns, gap, filter, duration, onChange, instanceRef, className, children, ...props }: BentoGridProps) {
+  const root = useRef<HTMLDivElement>(null);
+  const instance = useRef<BentoGridInstance | null>(null);
+  const onChangeRef = useLatest(onChange);
+  useIsomorphicLayoutEffect(() => {
+    const created = createBentoGrid(root.current, { columns, gap, filter, duration, onChange: (...args) => onChangeRef.current?.(...args) });
+    instance.current = created;
+    return () => { created.destroy(); instance.current = null; };
+    // Options update the existing engine so timers, selection and scroll state survive.
+  }, []);
+  useIsomorphicLayoutEffect(() => {
+    instance.current?.setOptions({ columns, gap, filter, duration });
+  }, [columns, gap, filter, duration]);
+  useIsomorphicLayoutEffect(() => { if (instanceRef) instanceRef.current = instance.current; return () => { if (instanceRef) instanceRef.current = null; }; }, [instanceRef]);
+  return <div {...props} ref={root} className={['mk-bento-grid', className].filter(Boolean).join(' ')}>{children}</div>;
+}

package/src/components/code-block/README.md

@@ -1,6 +1,6 @@
 # code-block
 
-Bloque de código con título y lenguaje opcionales, números de línea y botón copiar con confirmación. El código siempre se trata como texto: una cadena que parece HTML se muestra como código, nunca se interpreta.
+Bloque de código con título y lenguaje opcionales, números de línea y botón copiar con confirmación. El código siempre se trata como texto: una cadena que parece HTML se muestra como código, nunca se interpreta. Las líneas largas se desplazan con la barra de [`scroll-area`](../scroll-area/README.md), clara sobre el editor; al arrastrarla toma el color de las palabras clave.
 
 ```html
 <mk-code-block class="mk-code-block" title="Instalar" language="bash">

package/src/components/code-block/code-block.css

@@ -20,6 +20,11 @@ mk-code-block {
   --mk-code-property: #8fd6ff;
   --mk-code-punctuation: #9aa0aa;
   --mk-code-operator: #c9ced6;
+  /* The scroll-area bar, light on the editor in both modes; dragged, it takes the keyword colour like the focus ring. */
+  --mk-scroll-thumb: rgb(255 255 255 / 0.2);
+  --mk-scroll-thumb-hover: rgb(255 255 255 / 0.36);
+  --mk-scroll-thumb-active: var(--mk-code-keyword);
+  --mk-scroll-rail: rgb(255 255 255 / 0.05);
   position: relative;
   display: block;
   overflow: hidden;

package/src/components/code-block/engine.ts

@@ -3,6 +3,7 @@ import { reduced } from '../../core/reduced';
 import { createScope } from '../../core/scope';
 import { inert, type Instance } from '../../core/types';
 import { press } from '../../motion/micro';
+import { createScrollArea } from '../scroll-area/engine';
 import { languageFamily, renderCode } from './highlight';
 
 /*
@@ -11,6 +12,7 @@ import { languageFamily, renderCode } from './highlight';
  * show as code. Copy writes the exact string with the Clipboard API and reports
  * success or failure in a polite status; on failure the code is selected so it
  * can be copied by hand. A copy that finishes after destroy changes nothing.
+ * Long lines scroll under the kit's scroll-area bar, light on the dark editor.
  * Parts (made when absent): pre > code, [data-mk-code-copy], [data-mk-code-status].
  */
 
@@ -136,6 +138,9 @@ export function createCodeBlock(root: HTMLElement | null, options: CodeBlockOpti
   if (options.language) scope.attr(root, 'data-mk-language', options.language);
   if (options.lineNumbers) scope.attr(root, 'data-mk-line-numbers', '');
   scope.attr(root, 'data-mk-ready', '');
+  // The <pre> is already the keyboard's way in; the bar follows it under the header.
+  const area = createScrollArea(root, { viewport: pre, focusable: false, decorative: true });
+  scope.add(() => area.destroy());
 
   // A framework that already rendered the lines owns them; the engine only copies.
   const prerendered = Boolean(code.querySelector('[data-mk-code-line]'));

package/src/components/command-search/README.md

@@ -1,6 +1,6 @@
 # command-search
 
-Paleta de comandos en un `<dialog>` modal sobre vidrio oscuro. Se abre con ⌘K / Ctrl+K o con un botón `[data-mk-command-open]` y crece desde el botón que la abre (o desde el disparador visible con ⌘K/Ctrl+K) y se pliega de vuelta en él al cerrar: el color del botón se funde en el panel y la forma viaja 0,7 s; `open(origen)` elige otro control y `open(null)` la abre en su sitio. Al escribir filtra por coincidencia aproximada (letras en orden, sin tildes ni mayúsculas) y marca las letras con `<mark>` creado como texto. Los resultados se agrupan; una píldora se desliza bajo el activo con la curva swing.
+Paleta de comandos en un `<dialog>` modal sobre vidrio oscuro. Se abre con ⌘K / Ctrl+K o con un botón `[data-mk-command-open]` y crece desde el botón que la abre (o desde el disparador visible con ⌘K/Ctrl+K) y se pliega de vuelta en él al cerrar: el color del botón se funde en el panel y la forma viaja 0,7 s; `open(origen)` elige otro control y `open(null)` la abre en su sitio. Al escribir filtra por coincidencia aproximada (letras en orden, sin tildes ni mayúsculas) y marca las letras con `<mark>` creado como texto. Los resultados se agrupan; una píldora se desliza bajo el activo con la curva swing. Los resultados largos se desplazan con la barra de [`scroll-area`](../scroll-area/README.md), clara sobre el vidrio oscuro; el foco sigue en el campo.
 
 ```html
 <mk-command-search class="mk-command-search" items='[{"id":"charts","label":"Charts","group":"Páginas","href":"/chart"},{"id":"chart","label":"Chart","group":"Componentes","href":"/chart"}]'>

package/src/components/command-search/command-search.css

@@ -86,8 +86,18 @@ mk-command-search {
   overflow-y: auto;
   padding: 0 0.6rem 0.6rem;
   overscroll-behavior: contain;
-  scrollbar-width: thin;
-  scrollbar-color: rgb(255 255 255 / 0.15) transparent;
+}
+
+/* The scroll-area bar, light on the dark glass in both modes; long results leave it a lane. */
+[data-mk-command] [data-mk-command-panel] {
+  --mk-scroll-thumb: rgb(255 255 255 / 0.2);
+  --mk-scroll-thumb-hover: rgb(255 255 255 / 0.36);
+  --mk-scroll-thumb-active: rgb(255 255 255 / 0.62);
+  --mk-scroll-rail: rgb(255 255 255 / 0.05);
+}
+
+[data-mk-command] [data-mk-command-panel][data-mk-overflow-y] [data-mk-command-scroll] {
+  padding-right: 14px;
 }
 
 [data-mk-command] [data-mk-command-pill] {

package/src/components/command-search/engine.ts

@@ -5,6 +5,7 @@ import { inert, type Instance } from '../../core/types';
 import { blurIn } from '../../motion/micro';
 import { morphClose, morphOpen, releaseShared, showOrigin } from '../../motion/morph';
 import { fadeBackdrop, openModal } from '../../motion/surface';
+import { createScrollArea } from '../scroll-area/engine';
 import { matchScore } from './match';
 
 /*
@@ -17,6 +18,7 @@ import { matchScore } from './match';
  * under the active result on the swing curve; arrows, Home and End move it,
  * Enter picks it (onSelect, mk:select; an href navigates), Escape closes and
  * focus goes back. Combobox + listbox semantics with aria-activedescendant.
+ * Long results scroll under the kit's scroll-area bar, kept light on the glass.
  */
 
 export interface CommandItem {
@@ -119,6 +121,9 @@ export function createCommandSearch(root: HTMLElement | null, options: CommandSe
   root.append(dialog);
   scope.add(() => dialog.remove());
   scope.attr(root, 'data-mk-ready', '');
+  // The bar runs between the field and the footer; the input keeps the focus, so it is not a tab stop.
+  const area = createScrollArea(panel, { viewport: scroller, axis: 'y', focusable: false, decorative: true });
+  scope.add(() => area.destroy());
 
   let isOpen = false;
   let opener: HTMLElement | null = null;
@@ -255,6 +260,7 @@ export function createCommandSearch(root: HTMLElement | null, options: CommandSe
     openModal(dialog);
     // The rows grow with the panel: no entrance of their own on open.
     render(false);
+    area.refresh();
     input.focus();
     void fadeBackdrop(dialog, 'in');
     morphOpen(panel, from, { hideOrigin: true });