@yewdiel21/motion-kit 0.16.0 → 0.18.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/drilldown-menu/README.md

@@ -0,0 +1,163 @@
+# Drilldown Menu
+
+A hierarchical action menu that shows one level at a time. Opening a branch slides the new level in from the right through a 6 px blur; going back reverses the direction. Motion uses the kit's signature curve over 360 ms. The engine keeps one live menu, cancels interrupted motion, and honors reduced motion.
+
+## Vanilla
+
+```html
+<div id="actions" class="mk-drilldown-menu"></div>
+```
+
+```ts
+import { createDrilldownMenu, type DrilldownMenuItem } from '@yewdiel21/motion-kit';
+import '@yewdiel21/motion-kit/css';
+
+const items: DrilldownMenuItem[] = [
+  {
+    id: 'project', label: 'Project', description: 'Manage your workspace',
+    children: [{
+      id: 'share', label: 'Share',
+      children: [
+        { id: 'link', label: 'Copy link', description: 'Anyone with the link can view' },
+        { id: 'invite', label: 'Invite people', disabled: true },
+      ],
+    }],
+  },
+  { id: 'help', label: 'Help' },
+];
+
+const menu = createDrilldownMenu(document.querySelector('#actions'), {
+  items,
+  label: 'Workspace actions',
+  onSelect: (item, path) => console.log(item.label, path),
+  onPathChange: (path) => console.log('Level', path),
+});
+
+menu.open('project');
+menu.open('share');
+menu.back();
+menu.root(); // reset() also returns to the root
+menu.setPath(['project', 'share']);
+menu.setItems(items);
+menu.update({ label: 'Quick actions', emptyText: 'No available actions' });
+// When the component is removed:
+menu.destroy();
+```
+
+Use `@yewdiel21/motion-kit/css/components/drilldown-menu` for just this component's styles; theme tokens must already be present. The root needs `mk-drilldown-menu`; the custom element receives the same styles directly.
+
+## React
+
+```tsx
+import { useState } from 'react';
+import { DrilldownMenu } from '@yewdiel21/motion-kit/react';
+import type { DrilldownMenuItem } from '@yewdiel21/motion-kit';
+
+function Actions({ items }: { items: DrilldownMenuItem[] }) {
+  const [path, setPath] = useState<string[]>([]);
+  const [selection, setSelection] = useState('Choose an action');
+  return <>
+    <DrilldownMenu
+      items={items}
+      label="Workspace actions"
+      path={path}
+      onPathChange={setPath}
+      onSelect={(item) => setSelection(item.label)}
+    />
+    <p role="status">{selection}</p>
+  </>;
+}
+```
+
+Omit `path` for internal navigation; use `defaultPath` to choose its initial level. Passing `path` makes navigation controlled: `onPathChange` requests the next branch path, and the parent accepts it by updating the prop. A parent that keeps the previous path declines the request. Invalid paths are safely truncated to their valid prefix. Updating `items` retains a valid path and focused action; removing or disabling an ancestor returns to the nearest valid parent and reports the repaired path.
+
+`DrilldownMenuProps` also accepts normal `<div>` attributes, excluding children and the native `onSelect`. A forwarded `DrilldownMenuHandle` exposes `open`, `back`, `root`, `reset`, `setPath`, and `focusItem`. In controlled mode the `path` prop remains authoritative over ref-driven navigation.
+
+## Custom element
+
+```ts
+import { defineDrilldownMenu, type MkDrilldownMenuElement } from '@yewdiel21/motion-kit/elements';
+defineDrilldownMenu(); // safe to call more than once
+
+const element = document.querySelector<MkDrilldownMenuElement>('mk-drilldown-menu')!;
+element.items = items; // may also be assigned before connection
+element.path = ['project'];
+element.addEventListener('mk:select', (event) => {
+  console.log((event as CustomEvent).detail); // { item, path }
+});
+```
+
+```html
+<mk-drilldown-menu
+  label="Workspace actions"
+  back-label="Previous level"
+  empty-text="No available actions"
+  items='[{"id":"project","label":"Project","children":[{"id":"share","label":"Share","children":[{"id":"link","label":"Copy link"}]}]}]'
+  path='["project"]'
+></mk-drilldown-menu>
+```
+
+`items` and `path` attributes accept JSON arrays and update the live instance; malformed JSON leaves the last valid value intact. `items`/`path` properties and `setItems`/`setPath` methods accept arrays directly. `open`, `back`, `root`, `reset`, and `focusItem` forward to the live engine. The `instance` property is null while disconnected. Reconnecting creates a fresh instance from the current attributes/properties. The element uses light DOM, so inherited themes apply.
+
+## Data and API
+
+```ts
+interface DrilldownMenuItem {
+  id: string;
+  label: string;
+  description?: string;
+  disabled?: boolean;
+  children?: DrilldownMenuItem[];
+}
+```
+
+IDs must be unique among siblings. The same ID may appear in unrelated levels. A `children` array marks a branch; `children: []` opens an empty level. An item without children is an action. Labels/descriptions are inserted as text; they never execute HTML. Input data and returned item arrays are copied, so the engine does not mutate application data. Supply finite, acyclic data.
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `items` | `[]` | Root actions and branches |
+| `path` | `[]` | Initial branch IDs (engine); controlled branch IDs (React) |
+| `label` | `Actions` | Root heading and accessible menu name |
+| `backLabel` | `Back` | Accessible name of the back button |
+| `emptyText` | `No actions available` | Empty-level status |
+| `onSelect(item, path)` | — | Leaf action and full ID path, including the leaf |
+| `onPathChange(path)` | — | User/programmatic navigation or a repaired data path |
+
+`DrilldownMenuInstance` exposes:
+
+| Member | Behavior |
+| --- | --- |
+| `open(id): boolean` | Opens a current-level enabled branch and focuses its first action |
+| `back(): boolean` | Returns one level and restores focus to its parent branch |
+| `root()` / `reset()` | Returns to the root; keeps focus inside if it was inside |
+| `setPath(path, notify = false)` | Navigates to a valid prefix; optional path callback/event |
+| `setItems(items)` | Replaces root data, repairs invalid paths and preserves focus |
+| `update(options)` | Updates data, path, text and callbacks together |
+| `focusItem(id)` | Focuses an enabled current-level item |
+| `path` | Copy of the current branch ID path |
+| `items` | Copy of the current level's items |
+| `element` | Original root element |
+| `destroy()` | Cancels motion, removes listeners, restores original child nodes/attributes; idempotent |
+
+`open`, `back`, `root`, and `reset` notify on a changed path. Explicit `setPath` and `update({ path })` are silent by default. `setItems` reports a path repaired by removed/disabled/non-branch ancestors. `mk:path-change` bubbles with `{ path }`; `mk:select` bubbles with `{ item, path }`. Callbacks receive the same information. Choosing an action leaves the menu at its current level.
+
+## Keyboard and accessibility
+
+The current level has `role="menu"`, named by its visible header. Each action is a button with `role="menuitem"`; its label provides its accessible name and its description is referenced separately. Branches expose `aria-haspopup="menu"`. Disabled actions use both native `disabled` and `aria-disabled` and are skipped by focus navigation. Header/back and ancestor breadcrumbs sit outside the menu. The current breadcrumb uses `aria-current="location"`.
+
+| Key | Action |
+| --- | --- |
+| Up / Down | Previous / next enabled item, wrapping |
+| Home / End | First / last enabled item |
+| Enter / Space | Open branch or choose leaf action |
+| Right | Open a focused branch |
+| Left / Escape | Return one level and focus the branch you came from |
+| Tab / Shift+Tab | Normal page navigation through header/crumb controls and one roving menu stop |
+
+At the root, Left/Escape are left available to a containing surface. Empty and all-disabled levels keep the menu itself focusable so the back keys work. The initial render does not take focus; opening a branch intentionally focuses the new level. Updates preserve focus only when focus was already inside. Reduced-motion users receive immediate navigation without slide, blur or animated height.
+
+## Styling
+
+The component inherits `--mk-text`, `--mk-muted`, `--mk-surface-1`, `--mk-surface-3`, `--mk-outline-soft`, and `--mk-accent`. Override `--mk-drilldown-radius` (28 px) and `--mk-drilldown-item-radius` (18 px) for corner shapes. Width is fluid up to 26 rem; override `max-width` on the root for wider panels. Labels wrap, breadcrumbs wrap, and descriptions remain readable in narrow surfaces.
+
+This is an inline hierarchical action menu. Place it in an existing dialog/popover if you need an anchored or dismissible surface. It does not route to URLs, fetch children, virtualize data, or provide typeahead.