@yewdiel21/motion-kit 0.9.1 → 0.14.0

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/pagination/README.md

@@ -0,0 +1,17 @@
+# pagination
+
+Paginación con ventana acotada de números, extremos, elipsis y respuesta de elevación/presión.
+
+```html
+<mk-pagination class="mk-pagination" total-pages="30" page="4" role="navigation" aria-label="Artículos">
+  <button type="button" data-mk-pagination-previous aria-label="Página anterior">←</button>
+  <span data-mk-pagination-pages></span>
+  <button type="button" data-mk-pagination-next aria-label="Página siguiente">→</button>
+</mk-pagination>
+```
+
+`defineElements()`, `createPagination(root, options)`, o `<Pagination totalPages={30} page={page} onChange={setPage} />`.
+
+Opciones: `totalPages=10`, `page=1`, `siblings=1` (0…10), `pageLabel(n)`, `onChange(n)`. Total mínimo 1. API: `setPage(n, notify=true)`, `setTotalPages(n)`, `page`, `totalPages`, `destroy()`. `mk:change` lleva `{page,totalPages}`. Los cambios del total acotan la página y conservan el foco.
+
+Flechas izquierda/derecha, Home y End cambian la selección; botones nativos y aria-current=page. La aplicación decide cómo cargar los resultados. Sin animación con movimiento reducido.

package/src/components/pagination/element.ts

@@ -0,0 +1,14 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createPagination, type PaginationInstance } from './engine';
+/** Light DOM: supply the same child markup shown in the README. */
+export class MkPaginationElement extends MkElement<PaginationInstance> {
+  static options: Record<string, OptionType> = { totalPages: 'number', page: 'number', siblings: 'number' };
+  protected create(options: Record<string, unknown>) { return createPagination(this, options); }
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.isConnected || !this.instance) return;
+    const page = this.instance.page;
+    this.instance.destroy();
+    this.instance = this.create({ ...(!this.hasAttribute('page') ? { page } : {}), ...this.options });
+  }
+}
+export const definePagination = () => defineElement('mk-pagination', MkPaginationElement);

package/src/components/pagination/engine.ts

@@ -0,0 +1,102 @@
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+
+export interface PaginationOptions {
+  totalPages?: number;
+  page?: number;
+  siblings?: number;
+  pageLabel?: (page: number) => string;
+  onChange?: (page: number) => void;
+}
+export interface PaginationInstance extends Instance {
+  setPage(page: number, notify?: boolean): void;
+  setTotalPages(total: number): void;
+  readonly page: number;
+  readonly totalPages: number;
+}
+// Reserve room for the page-window arithmetic so incrementing always progresses.
+const positive = (n: number | undefined, fallback: number) => Number.isFinite(n) ? Math.max(1, Math.min(Number.MAX_SAFE_INTEGER - 32, Math.floor(n!))) : fallback;
+
+/** Renders a bounded window of pages, even when totalPages is very large. */
+export function createPagination(root: HTMLElement | null, options: PaginationOptions = {}): PaginationInstance {
+  const pages = root?.querySelector<HTMLElement>('[data-mk-pagination-pages]');
+  if (!root || !pages) return inert({ setPage() {}, setTotalPages() {}, page: 1, totalPages: 1 });
+  const scope = createScope();
+  const original = [...pages.childNodes];
+  const previous = root.querySelector<HTMLButtonElement>('[data-mk-pagination-previous]');
+  const next = root.querySelector<HTMLButtonElement>('[data-mk-pagination-next]');
+  let total = positive(options.totalPages, 10);
+  let page = Math.min(total, positive(options.page, 1));
+  const siblings = Math.min(10, Math.max(0, Number.isFinite(options.siblings) ? Math.floor(options.siblings!) : 1));
+  scope.attr(root, 'data-mk-ready', '');
+  const render = () => {
+    const hadFocus = pages.contains(document.activeElement);
+    const selected = new Set([1, total]);
+    for (let n = Math.max(1, page - siblings); n <= Math.min(total, page + siblings); n++) selected.add(n);
+    const fragment = document.createDocumentFragment();
+    let last = 0;
+    for (const n of [...selected].sort((a, b) => a - b)) {
+      if (last && n - last > 1) {
+        const gap = document.createElement('span');
+        gap.className = 'mk-pagination__gap';
+        gap.textContent = '…';
+        gap.setAttribute('aria-hidden', 'true');
+        fragment.append(gap);
+      }
+      const button = document.createElement('button');
+      button.type = 'button';
+      button.dataset.mkPage = String(n);
+      button.textContent = String(n);
+      button.setAttribute('aria-label', options.pageLabel?.(n) ?? `Página ${n}`);
+      if (n === page) button.setAttribute('aria-current', 'page');
+      fragment.append(button);
+      last = n;
+    }
+    pages.replaceChildren(fragment);
+    if (hadFocus) pages.querySelector<HTMLButtonElement>('[aria-current]')?.focus();
+    if (previous) scope.attr(previous, 'disabled', page === 1 ? '' : null);
+    if (next) scope.attr(next, 'disabled', page === total ? '' : null);
+  };
+  const setPage = (value: number, notify = true) => {
+    if (scope.disposed || !Number.isFinite(value)) return;
+    const candidate = Math.max(1, Math.min(total, Math.round(value)));
+    if (candidate === page) return;
+    const focused = pages.contains(document.activeElement);
+    page = candidate;
+    render();
+    if (focused) pages.querySelector<HTMLButtonElement>('[aria-current]')?.focus();
+    if (notify) {
+      options.onChange?.(page);
+      root.dispatchEvent(new CustomEvent('mk:change', { bubbles: true, detail: { page, totalPages: total } }));
+    }
+  };
+  scope.on(root, 'click', (event) => {
+    const target = (event.target as Element).closest<HTMLButtonElement>('button');
+    if (!target || target.disabled) return;
+    if (target === previous) setPage(page - 1);
+    else if (target === next) setPage(page + 1);
+    else if (target.dataset.mkPage) setPage(Number(target.dataset.mkPage));
+  });
+  scope.on(root, 'keydown', (event) => {
+    if (!(event.target instanceof HTMLButtonElement)) return;
+    const to = event.key === 'ArrowRight' ? page + 1 : event.key === 'ArrowLeft' ? page - 1 : event.key === 'Home' ? 1 : event.key === 'End' ? total : null;
+    if (to === null) return;
+    event.preventDefault();
+    setPage(to);
+    pages.querySelector<HTMLButtonElement>('[aria-current]')?.focus();
+  });
+  scope.add(() => pages.replaceChildren(...original));
+  render();
+  return {
+    setPage,
+    setTotalPages(value) {
+      if (scope.disposed || !Number.isFinite(value)) return;
+      total = positive(value, 1);
+      if (page > total) setPage(total);
+      else render();
+    },
+    get page() { return page; },
+    get totalPages() { return total; },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/pagination/pagination.css

@@ -0,0 +1,10 @@
+.mk-pagination, mk-pagination { display: flex; flex-wrap: wrap; justify-content: center; align-items: center; gap: .35rem; }
+.mk-pagination [data-mk-pagination-pages], mk-pagination [data-mk-pagination-pages] { display: flex; align-items: center; gap: .25rem; }
+.mk-pagination button, mk-pagination button { min-width: 2.5rem; height: 2.5rem; border: 0; border-radius: var(--mk-radius-full); background: var(--mk-surface-2); color: var(--mk-text); font: inherit; cursor: pointer; transition: transform .3s, background .3s, color .3s; }
+.mk-pagination button[aria-current], mk-pagination button[aria-current] { background: var(--mk-accent); color: var(--mk-on-accent); }
+.mk-pagination button:hover:not(:disabled), mk-pagination button:hover:not(:disabled) { transform: translateY(-3px); }
+.mk-pagination button:active:not(:disabled), mk-pagination button:active:not(:disabled) { transform: scale(.9); }
+.mk-pagination button:focus-visible, mk-pagination button:focus-visible { outline: 2px solid var(--mk-accent); outline-offset: 3px; }
+.mk-pagination button:disabled, mk-pagination button:disabled { opacity: .35; cursor: default; }
+.mk-pagination__gap { padding: 0 .15rem; color: var(--mk-muted); }
+@media (prefers-reduced-motion: reduce) { .mk-pagination button, mk-pagination button { transition: none; transform: none !important; } }

package/src/components/pagination/react.tsx

@@ -0,0 +1,22 @@
+'use client';
+import { useRef, type HTMLAttributes } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createPagination, type PaginationOptions } from './engine';
+export interface PaginationProps extends Omit<HTMLAttributes<HTMLElement>, 'onChange'>, PaginationOptions {
+  previousLabel?: string; nextLabel?: string;
+}
+export function Pagination({ totalPages, page, siblings, pageLabel, onChange, previousLabel = 'Página anterior', nextLabel = 'Página siguiente', className, ...props }: PaginationProps) {
+  const ref = useRef<HTMLElement>(null);
+  const selected = useRef<number | undefined>(undefined);
+  const change = useLatest(onChange);
+  const label = useLatest(pageLabel);
+  useIsomorphicLayoutEffect(() => {
+    const instance = createPagination(ref.current, { totalPages, page: page ?? selected.current, siblings, pageLabel: (n) => label.current?.(n) ?? `Página ${n}`, onChange: (n) => change.current?.(n) });
+    return () => { selected.current = instance.page; instance.destroy(); };
+  }, [totalPages, page, siblings, pageLabel]);
+  return <nav aria-label="Paginación" {...props} ref={ref} className={['mk-pagination', className].filter(Boolean).join(' ')}>
+    <button type="button" data-mk-pagination-previous aria-label={previousLabel}>←</button>
+    <span data-mk-pagination-pages />
+    <button type="button" data-mk-pagination-next aria-label={nextLabel}>→</button>
+  </nav>;
+}

package/src/components/password-strength/README.md

@@ -0,0 +1,17 @@
+# password-strength
+
+Campo de contraseña nativo con fortaleza en vivo: botón mostrar/ocultar (el ojo cambia con blur y su barra se dibuja), medidor de cuatro segmentos que se encienden en cascada y cambian de color por nivel (débil → aceptable → fuerte → muy fuerte), etiqueta que cambia con blur y lista de requisitos cuyos ✓ se dibujan. Un estado educado anuncia el nivel cuando dejas de escribir.
+
+```html
+<mk-password-strength class="mk-password-strength">
+  <input type="password" name="password" autocomplete="new-password" aria-label="Contraseña" />
+</mk-password-strength>
+```
+
+`defineElements()`, `createPasswordStrength(root, options)` o `<PasswordStrength name="password" requireScore={3} onStrength={setResult} />` (el campo sigue sin control; `onValueChange` da el texto).
+
+Opciones: `minLength=8`, `score(value)` (sustituye la puntuación), `requireScore` (por debajo, el campo se marca inválido con `setCustomValidity`), `labels {show, hide, invalid, checks}`, `onChange(result)`. API: `score`, `value`, `destroy()`. Evento `mk:strength` con `{score, label, met}`.
+
+Utilidad pura `scorePassword(value, minLength)`: la longitud y la variedad suben la puntuación; contraseñas comunes, secuencias (abc, 123) y repeticiones (aaa) la bajan. Es orientativa: el servidor decide qué acepta.
+
+Variables: `--mk-password-weak`, `--mk-password-fair`, `--mk-password-good`, `--mk-password-strong`. Movimiento reducido: los segmentos y la etiqueta cambian sin animación.

package/src/components/password-strength/element.ts

@@ -0,0 +1,22 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createPasswordStrength, type PasswordStrengthInstance } from './engine';
+
+/**
+ * <mk-password-strength class="mk-password-strength" min-length="10">
+ *   <input type="password" name="password" autocomplete="new-password" aria-label="Contraseña" />
+ * </mk-password-strength>
+ * Emits mk:strength ({score, label, met}).
+ */
+export class MkPasswordStrengthElement extends MkElement<PasswordStrengthInstance> {
+  static options: Record<string, OptionType> = { minLength: 'number', requireScore: 'number', labels: 'json' };
+
+  protected create(options: Record<string, unknown>) {
+    return createPasswordStrength(this, options);
+  }
+
+  get score() {
+    return this.instance?.score ?? 0;
+  }
+}
+
+export const definePasswordStrength = () => defineElement('mk-password-strength', MkPasswordStrengthElement);