@yewdiel21/motion-kit 0.17.0 → 0.18.0

package/dist/{reduced-YS6TZjpa.d.ts → reduced-dPsZYqtI.d.ts}

@@ -1,4 +1,4 @@
-import { c4 as MenuOptions, c3 as MenuInstance, bi as DialogOptions, bg as DialogInstance, cD as RevealSpeed } from './engine-Bn6hC87X.js';
+import { ct as MenuOptions, cs as MenuInstance, bB as DialogOptions, bz as DialogInstance, df as RevealSpeed } from './engine-t8d7brjn.js';
 import { I as Instance } from './types-BkS_raL8.js';
 import { SplitText } from 'gsap/SplitText';
 

package/dist/{store-CZ6vdtIE.d.ts → store-6hZNKiee.d.ts}

@@ -1,6 +1,6 @@
 import { I as Instance } from './types-BkS_raL8.js';
 import { Flip } from 'gsap/Flip';
-import { a8 as RevealHandle, a9 as DateInput } from './engine-Bn6hC87X.js';
+import { an as RevealHandle, ao as DateInput } from './engine-t8d7brjn.js';
 
 interface ThemePickerOptions {
     /** Theme ids to show, in order. Default: visible presets, or all with showHidden. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yewdiel21/motion-kit",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Motion toolkit for vanilla, Astro and React: GSAP recipes, accessible components, 19 themes, CSS controls and optional WebGL effects.",
   "type": "module",
   "license": "UNLICENSED",

package/registry.json

@@ -1155,6 +1155,186 @@
       "element": "components/wheel-picker/element.ts",
       "react": "components/wheel-picker/react.tsx",
       "since": "0.17.0"
+    },
+    "stepper": {
+      "kind": "component",
+      "description": "Indicadores de pasos horizontales, verticales, compactos y por puntos con progreso animado.",
+      "files": [
+        "components/stepper/engine.ts",
+        "components/stepper/stepper.css",
+        "components/stepper/README.md"
+      ],
+      "react": "components/stepper/react.tsx",
+      "element": "components/stepper/element.ts",
+      "since": "0.18.0"
+    },
+    "radio-group": {
+      "kind": "component",
+      "description": "Selección única con radios nativos, tarjetas o píldoras y resaltado elástico.",
+      "files": [
+        "components/radio-group/engine.ts",
+        "components/radio-group/radio-group.css",
+        "components/radio-group/README.md"
+      ],
+      "react": "components/radio-group/react.tsx",
+      "element": "components/radio-group/element.ts",
+      "since": "0.18.0"
+    },
+    "equalizer-slider": {
+      "kind": "component",
+      "description": "Control numérico de volumen con barras tipo ecualizador, respuesta al arrastre y cifras animadas.",
+      "files": [
+        "components/equalizer-slider/engine.ts",
+        "components/equalizer-slider/equalizer-slider.css",
+        "components/equalizer-slider/README.md"
+      ],
+      "react": "components/equalizer-slider/react.tsx",
+      "element": "components/equalizer-slider/element.ts",
+      "since": "0.18.0"
+    },
+    "temperature-slider": {
+      "kind": "component",
+      "description": "Temperatura con control nativo, transiciones de estado y cifra que rueda.",
+      "files": [
+        "components/temperature-slider/engine.ts",
+        "components/temperature-slider/temperature-slider.css",
+        "components/temperature-slider/README.md"
+      ],
+      "react": "components/temperature-slider/react.tsx",
+      "element": "components/temperature-slider/element.ts",
+      "since": "0.18.0"
+    },
+    "rating-scale": {
+      "kind": "component",
+      "description": "Escala de valoración numérica o de satisfacción con radios accesibles y selección animada.",
+      "files": [
+        "components/rating-scale/engine.ts",
+        "components/rating-scale/rating-scale.css",
+        "components/rating-scale/README.md"
+      ],
+      "react": "components/rating-scale/react.tsx",
+      "element": "components/rating-scale/element.ts",
+      "since": "0.18.0"
+    },
+    "notification-stack": {
+      "kind": "component",
+      "description": "Notificaciones superpuestas que se expanden, permiten acciones y se descartan con movimiento.",
+      "files": [
+        "components/notification-stack/engine.ts",
+        "components/notification-stack/notification-stack.css",
+        "components/notification-stack/README.md"
+      ],
+      "react": "components/notification-stack/react.tsx",
+      "element": "components/notification-stack/element.ts",
+      "since": "0.18.0"
+    },
+    "bento-grid": {
+      "kind": "component",
+      "description": "Grid adaptable con spans, filtros y reordenamiento animado mediante Flip.",
+      "files": [
+        "components/bento-grid/engine.ts",
+        "components/bento-grid/bento-grid.css",
+        "components/bento-grid/README.md"
+      ],
+      "react": "components/bento-grid/react.tsx",
+      "element": "components/bento-grid/element.ts",
+      "since": "0.18.0"
+    },
+    "scroll-preview-dock": {
+      "kind": "component",
+      "description": "Dock de navegación con vistas previas de secciones y seguimiento del scroll.",
+      "files": [
+        "components/scroll-preview-dock/engine.ts",
+        "components/scroll-preview-dock/scroll-preview-dock.css",
+        "components/scroll-preview-dock/README.md"
+      ],
+      "react": "components/scroll-preview-dock/react.tsx",
+      "element": "components/scroll-preview-dock/element.ts",
+      "since": "0.18.0"
+    },
+    "sticky-header": {
+      "kind": "component",
+      "description": "Cabecera que se compacta al desplazar sin cambiar el espacio del contenido.",
+      "files": [
+        "components/sticky-header/engine.ts",
+        "components/sticky-header/sticky-header.css",
+        "components/sticky-header/README.md"
+      ],
+      "react": "components/sticky-header/react.tsx",
+      "element": "components/sticky-header/element.ts",
+      "since": "0.18.0"
+    },
+    "handwriting-text": {
+      "kind": "component",
+      "description": "Texto trazado con glifos vectoriales originales, animación de escritura y repetición.",
+      "files": [
+        "components/handwriting-text/engine.ts",
+        "components/handwriting-text/handwriting-text.css",
+        "components/handwriting-text/README.md"
+      ],
+      "react": "components/handwriting-text/react.tsx",
+      "element": "components/handwriting-text/element.ts",
+      "since": "0.18.0"
+    },
+    "particle-button": {
+      "kind": "component",
+      "description": "Botón con pulsación elástica y partículas al completar una acción.",
+      "files": [
+        "components/particle-button/engine.ts",
+        "components/particle-button/particle-button.css",
+        "components/particle-button/README.md"
+      ],
+      "react": "components/particle-button/react.tsx",
+      "element": "components/particle-button/element.ts",
+      "since": "0.18.0"
+    },
+    "magnetize-button": {
+      "kind": "component",
+      "description": "Botón que atrae partículas al señalar o enfocar y las libera al salir.",
+      "files": [
+        "components/magnetize-button/engine.ts",
+        "components/magnetize-button/magnetize-button.css",
+        "components/magnetize-button/README.md"
+      ],
+      "react": "components/magnetize-button/react.tsx",
+      "element": "components/magnetize-button/element.ts",
+      "since": "0.18.0"
+    },
+    "badge-button": {
+      "kind": "component",
+      "description": "Botón con insignia, contador que rueda y respuesta al añadir o quitar.",
+      "files": [
+        "components/badge-button/engine.ts",
+        "components/badge-button/badge-button.css",
+        "components/badge-button/README.md"
+      ],
+      "react": "components/badge-button/react.tsx",
+      "element": "components/badge-button/element.ts",
+      "since": "0.18.0"
+    },
+    "morphing-page-dots": {
+      "kind": "component",
+      "description": "Paginación de carrusel con indicador que se estira entre páginas y teclado.",
+      "files": [
+        "components/morphing-page-dots/engine.ts",
+        "components/morphing-page-dots/morphing-page-dots.css",
+        "components/morphing-page-dots/README.md"
+      ],
+      "react": "components/morphing-page-dots/react.tsx",
+      "element": "components/morphing-page-dots/element.ts",
+      "since": "0.18.0"
+    },
+    "not-found": {
+      "kind": "component",
+      "description": "Estado 404 reutilizable con ilustración animada, regreso y enlace al inicio.",
+      "files": [
+        "components/not-found/engine.ts",
+        "components/not-found/not-found.css",
+        "components/not-found/README.md"
+      ],
+      "react": "components/not-found/react.tsx",
+      "element": "components/not-found/element.ts",
+      "since": "0.18.0"
     }
   }
 }

package/src/auto/auto-init.ts

@@ -1,3 +1,18 @@
+import { createNotFound } from '../components/not-found/engine';
+import { createMorphingPageDots } from '../components/morphing-page-dots/engine';
+import { createBadgeButton } from '../components/badge-button/engine';
+import { createMagnetizeButton } from '../components/magnetize-button/engine';
+import { createParticleButton } from '../components/particle-button/engine';
+import { createHandwritingText } from '../components/handwriting-text/engine';
+import { createStickyHeader } from '../components/sticky-header/engine';
+import { createScrollPreviewDock } from '../components/scroll-preview-dock/engine';
+import { createBentoGrid } from '../components/bento-grid/engine';
+import { createNotificationStack } from '../components/notification-stack/engine';
+import { createRatingScale } from '../components/rating-scale/engine';
+import { createTemperatureSlider } from '../components/temperature-slider/engine';
+import { createEqualizerSlider } from '../components/equalizer-slider/engine';
+import { createRadioGroup } from '../components/radio-group/engine';
+import { createStepper } from '../components/stepper/engine';
 import { createQuantity } from '../components/quantity/engine';
 import { createPagination } from '../components/pagination/engine';
 import { createHoverCard } from '../components/hover-card/engine';
@@ -120,6 +135,22 @@ import { createWheelPicker } from '../components/wheel-picker/engine';
 type Factory = (el: HTMLElement, options: Record<string, unknown>) => Instance;
 
 const factories = {
+  'stepper': createStepper,
+  'radio-group': createRadioGroup,
+  'equalizer-slider': createEqualizerSlider,
+  'temperature-slider': createTemperatureSlider,
+  'rating-scale': createRatingScale,
+  'notification-stack': createNotificationStack,
+  'bento-grid': createBentoGrid,
+  'scroll-preview-dock': createScrollPreviewDock,
+  'sticky-header': createStickyHeader,
+  'handwriting-text': createHandwritingText,
+  'particle-button': createParticleButton,
+  'magnetize-button': createMagnetizeButton,
+  'badge-button': createBadgeButton,
+  'morphing-page-dots': createMorphingPageDots,
+  'not-found': createNotFound,
+
   'wheel-picker': createWheelPicker,
   'drilldown-menu': createDrilldownMenu,
   'voice-message-bubble': createVoiceMessageBubble,

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);