@yewdiel21/motion-kit 0.10.0 → 0.15.0

package/src/components/nav/react.tsx

@@ -2,7 +2,7 @@
 
 import { useRef, type HTMLAttributes, type MouseEvent, type ReactNode } from 'react';
 import { useIsomorphicLayoutEffect } from '../../react/use-recipe';
-import { revealShell, type NavStyle } from './engine';
+import { revealShell, toNavStyle, type NavStyle, type NavStyleAlias } from './engine';
 
 export interface NavItem {
   value: string;
@@ -19,7 +19,7 @@ export interface NavProps extends Omit<HTMLAttributes<HTMLElement>, 'onSelect'>
   /** Value of the current page. */
   active?: string;
   onSelect?: (value: string, event: MouseEvent<HTMLElement>) => void;
-  navStyle?: NavStyle;
+  navStyle?: NavStyle | NavStyleAlias;
   accent?: boolean;
   /** Reveal the surrounding .mk-shell from the first button on mount. */
   reveal?: boolean;
@@ -34,7 +34,7 @@ export function Nav({
   items,
   active,
   onSelect,
-  navStyle = 'bonita',
+  navStyle = 'pills',
   accent = false,
   reveal = false,
   first,
@@ -50,7 +50,7 @@ export function Nav({
     // Only on mount.
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
-  const classes = ['mk-nav', `mk-nav--${navStyle}`, accent && 'mk-nav--accent', className].filter(Boolean).join(' ');
+  const classes = ['mk-nav', `mk-nav--${toNavStyle(navStyle) ?? 'pills'}`, accent && 'mk-nav--accent', className].filter(Boolean).join(' ');
   return (
     <nav ref={ref} aria-label="Principal" {...props} className={classes}>
       {first}

package/src/components/notification-bell/README.md

@@ -0,0 +1,14 @@
+# notification-bell
+
+Campana de notificaciones con insignia. `notify()` la hace sonar: la campana oscila desde arriba con amortiguación (±18°) y el badajo va un instante detrás, salen ondas, la insignia aparece con curva elástica (o su cifra rueda hacia arriba) y un mensaje opcional sube a su lado en vidrio invertido durante unos segundos.
+
+```html
+<mk-notification-bell class="mk-notification-bell" count="2"></mk-notification-bell>
+<script>document.querySelector('mk-notification-bell').notify('Nueva cita a las 10:00');</script>
+```
+
+`defineElements()`, `createNotificationBell(root, options)` (root es el botón o lo contiene) o `<NotificationBell count={unread} message={latest} onOpen={openPanel} />` (una cifra mayor o un mensaje nuevo la hacen sonar).
+
+Opciones: `count=0`, `label='Notificaciones'`, `messageDuration=3200` ms, `max=99` (más se lee «99+»), `onOpen()`. API: `notify(message?)`, `setCount(n)`, `clear()`, `count`, `destroy()`. Eventos `mk:open` (clic) y `mk:count`. El nombre accesible incluye el número («Notificaciones, 3 sin leer») y un estado educado anuncia las nuevas. Las notificaciones reales (push, servidor) son de la app.
+
+Movimiento reducido: la cifra y el mensaje cambian sin oscilación ni ondas.

package/src/components/notification-bell/element.ts

@@ -0,0 +1,48 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createNotificationBell, type NotificationBellInstance } from './engine';
+
+/**
+ * <mk-notification-bell class="mk-notification-bell" count="2"></mk-notification-bell>
+ * el.notify('Nueva cita a las 10:00') rings it. Emits mk:open on click and mk:count when the count changes.
+ */
+export class MkNotificationBellElement extends MkElement<NotificationBellInstance> {
+  static options: Record<string, OptionType> = { count: 'number', label: 'string', messageDuration: 'number', max: 'number' };
+
+  protected create(options: Record<string, unknown>) {
+    let made: HTMLButtonElement | null = null;
+    if (!this.querySelector('button')) {
+      made = document.createElement('button');
+      made.type = 'button';
+      this.append(made);
+    }
+    const engine = createNotificationBell(this, options);
+    if (made) {
+      const destroy = engine.destroy;
+      engine.destroy = () => {
+        destroy();
+        made!.remove();
+      };
+    }
+    return engine;
+  }
+
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.instance) return;
+    if (name === 'count') this.instance.setCount(Number(next) || 0);
+    else super.attributeChangedCallback(name, previous, next);
+  }
+
+  notify(message?: string) {
+    this.instance?.notify(message);
+  }
+
+  clear() {
+    this.instance?.clear();
+  }
+
+  get count() {
+    return this.instance?.count ?? 0;
+  }
+}
+
+export const defineNotificationBell = () => defineElement('mk-notification-bell', MkNotificationBellElement);

package/src/components/notification-bell/engine.ts

@@ -0,0 +1,202 @@
+import { gsap, ELASTIC, EASE, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { blurIn, blurOut, rollDigits } from '../../motion/micro';
+
+/*
+ * Notification bell: a bell with a badge on a button. notify() rings it — the
+ * bell swings from its top in a damped arc (±18°) with the clapper a beat
+ * behind, waves ripple out, the badge pops in elastically (or its number rolls
+ * up), and an optional message rises beside it for a few seconds. The button's
+ * name carries the count and a polite status announces new ones.
+ */
+
+export interface NotificationBellOptions {
+  count?: number;
+  /** Accessible name before the count (default 'Notificaciones'). */
+  label?: string;
+  /** How long a message stays, in ms (default 3200). */
+  messageDuration?: number;
+  /** Above this the badge reads n+ (default 99). */
+  max?: number;
+  onOpen?: () => void;
+}
+
+export interface NotificationBellInstance extends Instance {
+  /** Ring with a new notification (and show `message`, as text). */
+  notify(message?: string): void;
+  setCount(count: number): void;
+  clear(): void;
+  readonly count: number;
+}
+
+const SVG = 'http://www.w3.org/2000/svg';
+const BODY = 'M6 16.5V11a6 6 0 0 1 12 0v5.5l1.5 2H4.5z';
+
+export function createNotificationBell(root: HTMLElement | null, options: NotificationBellOptions = {}): NotificationBellInstance {
+  const button = root ? ((root.matches('button') ? root : root.querySelector('button')) as HTMLButtonElement | null) : null;
+  if (!root || !button) return inert({ notify() {}, setCount() {}, clear() {}, count: 0 });
+  registerMotion();
+  const scope = createScope();
+  const max = Number.isFinite(options.max) && options.max! > 0 ? Math.floor(options.max!) : 99;
+  const label = options.label ?? 'Notificaciones';
+  const stay = Number.isFinite(options.messageDuration) ? Math.max(0, options.messageDuration!) : 3200;
+  let count = Math.max(0, Math.round(Number.isFinite(options.count) ? options.count! : 0));
+
+  const made: Element[] = [];
+  scope.add(() => made.forEach((element) => element.remove()));
+  const icon = document.createElementNS(SVG, 'svg');
+  icon.setAttribute('viewBox', '0 0 24 24');
+  icon.setAttribute('aria-hidden', 'true');
+  icon.dataset.mkBellIcon = '';
+  const bell = document.createElementNS(SVG, 'g');
+  bell.dataset.mkPart = 'bell';
+  const body = document.createElementNS(SVG, 'path');
+  body.setAttribute('d', BODY);
+  const top = document.createElementNS(SVG, 'path');
+  top.setAttribute('d', 'M12 3v2');
+  bell.append(body, top);
+  const clapper = document.createElementNS(SVG, 'path');
+  clapper.setAttribute('d', 'M10 20.5a2 2 0 0 0 4 0');
+  clapper.dataset.mkPart = 'clapper';
+  icon.append(bell, clapper);
+  const waves = document.createElement('span');
+  waves.dataset.mkBellWaves = '';
+  waves.setAttribute('aria-hidden', 'true');
+  const badge = document.createElement('span');
+  badge.dataset.mkBellBadge = '';
+  badge.setAttribute('aria-hidden', 'true');
+  button.prepend(waves, icon);
+  button.append(badge);
+  const bubble = document.createElement('span');
+  bubble.dataset.mkBellMessage = '';
+  bubble.setAttribute('aria-hidden', 'true');
+  bubble.hidden = true;
+  const live = document.createElement('span');
+  live.className = 'mk-sr-only';
+  live.setAttribute('role', 'status');
+  (root === button ? button : root).append(bubble, live);
+  made.push(waves, icon, badge, bubble, live);
+
+  scope.attr(button, 'type', button.getAttribute('type') ?? 'button');
+  scope.attr(button, 'data-mk-bell', '');
+  scope.attr(root, 'data-mk-ready', '');
+
+  let hideTimer: ReturnType<typeof setTimeout> | undefined;
+  const effects = new Set<gsap.core.Animation>();
+  const keep = (animation: gsap.core.Animation | null) => {
+    if (!animation) return;
+    effects.add(animation);
+    // Finished ones leave as new ones arrive: the animation's own onComplete stays untouched.
+    for (const effect of effects) if (effect.totalProgress() === 1) effects.delete(effect);
+  };
+  scope.add(() => {
+    clearTimeout(hideTimer);
+    for (const effect of effects) effect.kill();
+    effects.clear();
+    gsap.killTweensOf([bell, clapper, badge, bubble]);
+  });
+
+  const text = (n: number) => (n > max ? `${max}+` : String(n));
+  const name = () => (count ? `${label}, ${count} sin leer` : label);
+  const paint = () => {
+    scope.attr(button, 'aria-label', name());
+    badge.hidden = count === 0;
+  };
+
+  const showBadge = (previous: number) => {
+    if (count === 0) {
+      if (reduced() || previous === 0) {
+        badge.hidden = true;
+        return;
+      }
+      keep(gsap.to(badge, { scale: 0, duration: 0.2, ease: 'power2.in', onComplete: () => void (badge.hidden = true), clearProps: 'scale,transform' }));
+      return;
+    }
+    if (previous === 0) {
+      badge.textContent = text(count);
+      badge.hidden = false;
+      if (!reduced()) keep(gsap.fromTo(badge, { scale: 0 }, { scale: 1, duration: 0.8, ease: ELASTIC, clearProps: 'scale,transform' }));
+    } else keep(rollDigits(badge, text(count), count >= previous ? 1 : -1, 0.4));
+  };
+
+  const ring = () => {
+    if (reduced()) return;
+    gsap.killTweensOf([bell, clapper]);
+    keep(gsap.fromTo(bell, { rotation: 0 }, { keyframes: { rotation: [18, -14, 10, -6, 3, 0] }, duration: 1, ease: 'power1.out', svgOrigin: '12 4', clearProps: 'rotation,transform' }));
+    keep(gsap.fromTo(clapper, { x: 0 }, { keyframes: { x: [0, -2.5, 2, -1.4, 0.8, 0] }, duration: 1, delay: 0.06, ease: 'power1.out', clearProps: 'x,transform' }));
+    for (let i = 0; i < 2; i++) {
+      const wave = document.createElement('i');
+      waves.append(wave);
+      keep(gsap.fromTo(wave, { scale: 0.6, opacity: 0.55 }, { scale: 1.9, opacity: 0, duration: 0.8, delay: i * 0.18, ease: 'power2.out', onComplete: () => wave.remove() }));
+    }
+  };
+
+  // The message rises on the side with room inside the bell's container (and the window), so a bell at the
+  // right edge of a card speaks to its left instead of running over the next thing.
+  const place = () => {
+    bubble.style.maxWidth = '';
+    const box = root.getBoundingClientRect();
+    const frame = root.parentElement?.getBoundingClientRect();
+    const right = Math.min(frame?.right ?? innerWidth, innerWidth) - box.right;
+    const left = box.left - Math.max(frame?.left ?? 0, 0);
+    const side = right >= bubble.offsetWidth + 12 || right >= left ? 'right' : 'left';
+    bubble.dataset.mkSide = side;
+    bubble.style.maxWidth = `min(16rem, ${Math.max(140, (side === 'right' ? right : left) - 12)}px)`;
+  };
+
+  const say = (message: string) => {
+    clearTimeout(hideTimer);
+    gsap.killTweensOf(bubble);
+    bubble.textContent = message;
+    bubble.hidden = false;
+    place();
+    keep(blurIn(bubble, { from: 'pop' }));
+    hideTimer = setTimeout(() => {
+      if (scope.disposed) return;
+      const out = blurOut(bubble, {
+        to: 'up',
+        onComplete: () => {
+          bubble.hidden = true;
+          gsap.set(bubble, { clearProps: 'all' });
+        },
+      });
+      keep(out);
+    }, stay);
+  };
+
+  const setCount = (next: number, announce = false) => {
+    if (scope.disposed || !Number.isFinite(next)) return;
+    const previous = count;
+    count = Math.max(0, Math.round(next));
+    if (count === previous) return;
+    paint();
+    showBadge(previous);
+    if (announce) live.textContent = name();
+    root.dispatchEvent(new CustomEvent('mk:count', { bubbles: true, detail: { count } }));
+  };
+
+  scope.on(button, 'click', () => {
+    options.onOpen?.();
+    root.dispatchEvent(new CustomEvent('mk:open', { bubbles: true, detail: { count } }));
+  });
+  badge.textContent = text(count);
+  paint();
+
+  return {
+    notify(message) {
+      if (scope.disposed) return;
+      setCount(count + 1, true);
+      ring();
+      if (message) say(String(message));
+      if (message) live.textContent = `${name()}. ${message}`;
+    },
+    setCount: (next) => setCount(next),
+    clear: () => setCount(0),
+    get count() {
+      return count;
+    },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/notification-bell/notification-bell.css

@@ -0,0 +1,126 @@
+/* notification-bell — a round Melonmind icon button (surface tone) with a bell, a badge in the error tone and a
+   message that rises beside it in the inverse glass. */
+.mk-notification-bell,
+mk-notification-bell {
+  position: relative;
+  display: inline-flex;
+}
+
+[data-mk-bell] {
+  position: relative;
+  display: grid;
+  place-items: center;
+  width: 3rem;
+  height: 3rem;
+  padding: 0;
+  border: 0;
+  border-radius: 50%;
+  background: var(--mk-surface-3);
+  color: var(--mk-text);
+  cursor: pointer;
+  transition: background-color 0.2s ease;
+}
+
+[data-mk-bell]:hover {
+  background: var(--mk-surface-4);
+}
+
+[data-mk-bell]:active {
+  animation: mk-bell-press 500ms cubic-bezier(0.37, 1.42, 0.37, 1);
+}
+
+[data-mk-bell]:focus-visible {
+  outline: 2px solid var(--mk-accent);
+  outline-offset: 3px;
+}
+
+[data-mk-bell] [data-mk-bell-icon] {
+  width: 1.5rem;
+  height: 1.5rem;
+  overflow: visible;
+  fill: none;
+  stroke: currentColor;
+  stroke-width: 1.8;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+}
+
+[data-mk-bell] [data-mk-bell-waves] {
+  position: absolute;
+  inset: 0;
+  display: grid;
+  place-items: center;
+  pointer-events: none;
+}
+
+[data-mk-bell] [data-mk-bell-waves] i {
+  position: absolute;
+  inset: 0;
+  border-radius: 50%;
+  box-shadow: inset 0 0 0 2px var(--mk-text);
+}
+
+[data-mk-bell] [data-mk-bell-badge] {
+  position: absolute;
+  top: 0.15rem;
+  right: 0.1rem;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 1.25rem;
+  height: 1.25rem;
+  padding: 0 0.3rem;
+  border-radius: 64px;
+  background: var(--mk-error);
+  box-shadow: 0 0 0 2px var(--mk-bg);
+  color: var(--mk-on-error);
+  font-size: 0.6875rem;
+  font-weight: 600;
+  font-variant-numeric: tabular-nums;
+  line-height: 1;
+}
+
+[data-mk-bell] [data-mk-bell-badge][hidden] {
+  display: none;
+}
+
+:is(.mk-notification-bell, mk-notification-bell) [data-mk-bell-message] {
+  position: absolute;
+  top: 50%;
+  left: calc(100% + 0.75rem);
+  width: max-content;
+  max-width: 16rem;
+  padding: 0.5rem 0.85rem;
+  border-radius: 16px;
+  background: var(--mk-glass-inverse);
+  box-shadow: var(--mk-glass-bevel);
+  backdrop-filter: blur(16px);
+  color: var(--mk-on-glass-inverse);
+  font-size: 0.8125rem;
+  translate: 0 -50%;
+  pointer-events: none;
+  transform-origin: 0 50%;
+}
+
+:is(.mk-notification-bell, mk-notification-bell) [data-mk-bell-message][data-mk-side='left'] {
+  right: calc(100% + 0.75rem);
+  left: auto;
+  transform-origin: 100% 50%;
+}
+
+:is(.mk-notification-bell, mk-notification-bell) [data-mk-bell-message][hidden] {
+  display: none;
+}
+
+@keyframes mk-bell-press {
+  50% {
+    transform: scale(0.92);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-mk-bell] {
+    animation: none !important;
+    transition: none;
+  }
+}

package/src/components/notification-bell/react.tsx

@@ -0,0 +1,57 @@
+'use client';
+import { useRef, type ButtonHTMLAttributes, type MutableRefObject } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createNotificationBell, type NotificationBellInstance } from './engine';
+
+export interface NotificationBellProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children'> {
+  /** Unread count. A higher count than before rings the bell. */
+  count?: number;
+  /** The newest message: a new value rings the bell and shows it. */
+  message?: string;
+  label?: string;
+  messageDuration?: number;
+  max?: number;
+  onOpen?: () => void;
+  instanceRef?: MutableRefObject<NotificationBellInstance | null>;
+}
+
+/** <NotificationBell count={unread} message={latest} onOpen={openPanel} />. */
+export function NotificationBell({ count = 0, message, label, messageDuration, max, onOpen, instanceRef, className, ...props }: NotificationBellProps) {
+  const ref = useRef<HTMLSpanElement>(null);
+  const instance = useRef<NotificationBellInstance | null>(null);
+  const open = useLatest(onOpen);
+  const initial = useRef(count);
+  useIsomorphicLayoutEffect(() => {
+    const created = createNotificationBell(ref.current, { count: initial.current, label, messageDuration, max, onOpen: () => open.current?.() });
+    instance.current = created;
+    if (instanceRef) instanceRef.current = created;
+    return () => {
+      initial.current = created.count;
+      created.destroy();
+      instance.current = null;
+      if (instanceRef) instanceRef.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [label, messageDuration, max]);
+  const seen = useRef({ count, message });
+  useIsomorphicLayoutEffect(() => {
+    const bell = instance.current;
+    if (!bell) return;
+    const before = seen.current;
+    seen.current = { count, message };
+    const fresh = message !== undefined && message !== before.message;
+    if (count > bell.count) {
+      // One ring for the newest; the rest of the jump is set at once.
+      bell.setCount(count - 1);
+      bell.notify(fresh ? message : undefined);
+    } else {
+      bell.setCount(count);
+      if (fresh && message) bell.notify(message);
+    }
+  }, [count, message]);
+  return (
+    <span ref={ref} className={['mk-notification-bell', className].filter(Boolean).join(' ')}>
+      <button type="button" {...props} />
+    </span>
+  );
+}

package/src/components/orbit-menu/README.md

@@ -0,0 +1,46 @@
+# orbit-menu
+
+Menú central que despliega acciones en cruz o círculo con giro, desenfoque y resorte.
+
+## Instalación
+
+```tsx
+import '@yewdiel21/motion-kit/css';
+import { OrbitMenu } from '@yewdiel21/motion-kit/react';
+```
+
+```sh
+npx @yewdiel21/motion-kit add orbit-menu --react --elements
+```
+
+## React
+
+```tsx
+<OrbitMenu label="Acciones" items={[{ value: "add", label: "Crear", icon: "+" }, { value: "download", label: "Descargar", icon: "↓" }]} onSelect={run} />
+```
+
+Los callbacks del ejemplo (`ask`, `run`, `setTool`, `setVolume`) pertenecen a tu aplicación. React acepta `className`, `style` y atributos HTML. Los componentes con estado exponen `instanceRef` (excepto PillButton).
+
+## HTML / Astro
+
+```html
+<mk-orbit-menu radius="88"><button data-mk-orbit-toggle aria-label="Acciones"></button><button data-mk-orbit-item data-mk-value="add" aria-label="Crear">+</button><button data-mk-orbit-item data-mk-value="download" aria-label="Descargar">↓</button></mk-orbit-menu>
+<script type="module">
+  import { defineElements } from '@yewdiel21/motion-kit/elements';
+  defineElements(['mk-orbit-menu']);
+</script>
+```
+
+En Astro usa un `<script>` procesado por Astro. En HTML directo el import requiere bundler o import map. También puedes usar `import { createOrbitMenu } from '@yewdiel21/motion-kit'` y llamar a la factory con el contenedor y las mismas opciones. Al desmontar, llama a `instance.destroy()`.
+
+## Opciones
+
+radius: 96 px. start: 0 grados desde arriba. closeOnSelect: true. onToggle(open), onSelect(value). Reserva espacio alrededor del botón. Instancia: open(), close(), toggle(), isOpen.
+
+Los nombres camelCase se escriben como atributos kebab-case. Los arrays y objetos se pasan como JSON. Los booleanos aceptan atributo vacío o `"false"`.
+
+## Estilos y accesibilidad
+
+Variables: --mk-orbit-size, --mk-orbit-face, --mk-orbit-ink, --mk-orbit-shadow.
+
+Respeta los colores del tema, foco visible y `prefers-reduced-motion`. Los gráficos incluyen una tabla accesible y selección con flechas, Home, End y Escape. Heatmap usa arriba/abajo para un día e izquierda/derecha para una semana. Toolbar usa flechas y Home/End; OrbitMenu cierra con Escape y devuelve el foco. Los controles conservan nombres accesibles; VoiceDots anuncia los estados sin leer cada fotograma.

package/src/components/orbit-menu/element.ts

@@ -0,0 +1,27 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createOrbitMenu, type OrbitMenuInstance } from './engine';
+
+/**
+ * <mk-orbit-menu class="mk-orbit-menu">
+ *   <button data-mk-orbit-toggle aria-label="Acciones"></button>
+ *   <button data-mk-orbit-item data-mk-value="nuevo" aria-label="Nuevo">…svg…</button> …
+ * </mk-orbit-menu>
+ * Options swirl out around the middle button. Emits mk:toggle ({open}) and mk:select ({value}).
+ */
+export class MkOrbitMenuElement extends MkElement<OrbitMenuInstance> {
+  static options: Record<string, OptionType> = { radius: 'number', start: 'number', closeOnSelect: 'boolean' };
+
+  protected create(options: Record<string, unknown>) {
+    return createOrbitMenu(this, options);
+  }
+
+  open() {
+    this.instance?.open();
+  }
+
+  close() {
+    this.instance?.close();
+  }
+}
+
+export const defineOrbitMenu = () => defineElement('mk-orbit-menu', MkOrbitMenuElement);