@yewdiel21/motion-kit 0.9.1 → 0.14.0

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

@@ -0,0 +1,212 @@
+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 { scorePassword, type PasswordChecks, type PasswordScore } from './score';
+
+/*
+ * Password strength: a native password field with a show/hide toggle (the eye
+ * swaps with a blur), a four-segment meter whose segments light up one after
+ * another and change colour by level (error → warning → good → strong), a label
+ * that changes with a blur and a list of requirements whose checks draw
+ * themselves. A polite status announces the level once typing pauses.
+ */
+
+export interface PasswordStrengthOptions {
+  minLength?: number;
+  /** Replace the built-in scoring. */
+  score?: (value: string) => PasswordScore;
+  /** Below this score the field reports itself invalid (setCustomValidity). */
+  requireScore?: number;
+  labels?: { show?: string; hide?: string; invalid?: string; checks?: Partial<Record<keyof PasswordChecks, string>> };
+  onChange?: (result: PasswordScore) => void;
+}
+
+export interface PasswordStrengthInstance extends Instance {
+  readonly score: number;
+  readonly value: string;
+}
+
+const EYE = 'M2.5 12s3.5-6.5 9.5-6.5 9.5 6.5 9.5 6.5-3.5 6.5-9.5 6.5S2.5 12 2.5 12z';
+const PUPIL = 'M12 9.2a2.8 2.8 0 1 0 0 5.6 2.8 2.8 0 0 0 0-5.6z';
+const SLASH = 'M4 4l16 16';
+const CHECK = 'M5 12.5l4.5 4.5L19 7.5';
+const ORDER: Array<keyof PasswordChecks> = ['length', 'lower', 'upper', 'number', 'symbol'];
+let sequence = 0;
+
+const icon = (paths: string[], part: string) => {
+  const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+  svg.setAttribute('viewBox', '0 0 24 24');
+  svg.setAttribute('aria-hidden', 'true');
+  svg.dataset.mkPart = part;
+  for (const d of paths) {
+    const path = document.createElementNS('http://www.w3.org/2000/svg', 'path');
+    path.setAttribute('d', d);
+    path.setAttribute('pathLength', '1');
+    svg.append(path);
+  }
+  return svg;
+};
+
+export function createPasswordStrength(root: HTMLElement | null, options: PasswordStrengthOptions = {}): PasswordStrengthInstance {
+  if (!root) return inert({ score: 0, value: '' });
+  registerMotion();
+  const scope = createScope();
+  const uid = `mk-password-${++sequence}`;
+  const minLength = Number.isFinite(options.minLength) && options.minLength! > 0 ? Math.floor(options.minLength!) : 8;
+  const score = options.score ?? ((value: string) => scorePassword(value, minLength));
+  const labels = {
+    show: 'Mostrar contraseña',
+    hide: 'Ocultar contraseña',
+    invalid: 'Elige una contraseña más fuerte.',
+    ...options.labels,
+    checks: { length: `Al menos ${minLength} caracteres`, lower: 'Una minúscula', upper: 'Una mayúscula', number: 'Un número', symbol: 'Un símbolo', ...options.labels?.checks },
+  };
+  const made: Element[] = [];
+  scope.add(() => made.forEach((element) => element.remove()));
+
+  let input = root.querySelector<HTMLInputElement>('input[type="password"], input[data-mk-password]');
+  if (!input) {
+    input = document.createElement('input');
+    input.autocomplete = 'new-password';
+    input.setAttribute('aria-label', 'Contraseña');
+    root.append(input);
+    made.push(input);
+  }
+  scope.attr(input, 'type', 'password');
+  scope.attr(input, 'data-mk-password', '');
+  const field = document.createElement('span');
+  field.dataset.mkPasswordField = '';
+  input.replaceWith(field);
+  field.append(input);
+  scope.add(() => field.replaceWith(input!));
+  const toggle = document.createElement('button');
+  toggle.type = 'button';
+  toggle.dataset.mkPasswordToggle = '';
+  toggle.setAttribute('aria-pressed', 'false');
+  toggle.setAttribute('aria-label', labels.show);
+  if (input.id) toggle.setAttribute('aria-controls', input.id);
+  const eye = icon([EYE, PUPIL, SLASH], 'eye');
+  toggle.append(eye);
+  field.append(toggle);
+
+  const meter = document.createElement('div');
+  meter.dataset.mkPasswordMeter = '';
+  meter.setAttribute('aria-hidden', 'true');
+  const segments = Array.from({ length: 4 }, () => {
+    const segment = document.createElement('span');
+    segment.append(document.createElement('i'));
+    meter.append(segment);
+    return segment;
+  });
+  const label = document.createElement('span');
+  label.dataset.mkPasswordLabel = '';
+  meter.append(label);
+  const list = document.createElement('ul');
+  list.dataset.mkPasswordChecks = '';
+  list.id = `${uid}-checks`;
+  const items = ORDER.map((key) => {
+    const item = document.createElement('li');
+    item.dataset.mkCheck = key;
+    item.append(icon([CHECK], 'check'), labels.checks[key] ?? key);
+    list.append(item);
+    return item;
+  });
+  const live = document.createElement('span');
+  live.className = 'mk-sr-only';
+  live.setAttribute('role', 'status');
+  root.append(meter, list, live);
+  made.push(meter, list, live);
+  scope.attr(input, 'aria-describedby', [input.getAttribute('aria-describedby'), list.id].filter(Boolean).join(' '));
+  scope.attr(root, 'data-mk-ready', '');
+
+  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);
+  };
+  let announce: ReturnType<typeof setTimeout> | undefined;
+  scope.add(() => {
+    clearTimeout(announce);
+    for (const effect of effects) effect.kill();
+    effects.clear();
+  });
+
+  let result = score(input.value);
+  let lit = 0;
+  const paint = (animate: boolean) => {
+    const previous = lit;
+    const level = input!.value ? Math.max(1, result.score) : 0;
+    lit = level;
+    scope.attr(root, 'data-mk-score', input!.value ? String(result.score) : null);
+    const bars = segments.map((segment) => segment.firstElementChild as HTMLElement);
+    if (!animate || reduced()) gsap.set(bars, { scaleX: (i: number) => (i < level ? 1 : 0) });
+    else if (level > previous) keep(gsap.fromTo(bars.slice(previous, level), { scaleX: 0 }, { scaleX: 1, duration: 0.35, ease: EASE.swatch, stagger: 0.07 }));
+    else if (level < previous) keep(gsap.to(bars.slice(level, previous).reverse(), { scaleX: 0, duration: 0.2, ease: 'power2.in', stagger: 0.04 }));
+    if (label.textContent !== result.label) {
+      if (!animate || reduced()) label.textContent = result.label;
+      else {
+        gsap.killTweensOf(label);
+        keep(
+          gsap
+            .timeline()
+            .to(label, { opacity: 0, filter: 'blur(4px)', y: -3, duration: 0.12 })
+            .call(() => {
+              label.textContent = result.label;
+            })
+            .fromTo(label, { opacity: 0, filter: 'blur(4px)', y: 3 }, { opacity: 1, filter: 'blur(0px)', y: 0, duration: 0.25, ease: EASE.pop, clearProps: 'all' }),
+        );
+      }
+    }
+    items.forEach((item, i) => {
+      const met = result.checks[ORDER[i]!];
+      if (item.hasAttribute('data-mk-met') === met) return;
+      item.toggleAttribute('data-mk-met', met);
+      const path = item.querySelector('path');
+      if (met && path && animate && !reduced()) keep(gsap.fromTo(path, { strokeDashoffset: 1 }, { strokeDashoffset: 0, duration: 0.35, ease: 'power2.out' }));
+    });
+    if (Number.isFinite(options.requireScore)) input!.setCustomValidity(input!.value && result.score < options.requireScore! ? labels.invalid : '');
+  };
+
+  const update = () => {
+    result = score(input!.value);
+    paint(true);
+    options.onChange?.(result);
+    root.dispatchEvent(new CustomEvent('mk:strength', { bubbles: true, detail: { score: result.score, label: result.label, met: result.checks } }));
+    clearTimeout(announce);
+    announce = setTimeout(() => {
+      if (!scope.disposed) live.textContent = input!.value ? `Fortaleza: ${result.label}` : '';
+    }, 700);
+  };
+
+  scope.on(input, 'input', update);
+  scope.on(toggle, 'click', () => {
+    const show = input!.type === 'password';
+    input!.type = show ? 'text' : 'password';
+    toggle.setAttribute('aria-pressed', String(show));
+    toggle.setAttribute('aria-label', show ? labels.hide : labels.show);
+    root.toggleAttribute('data-mk-visible', show);
+    const slash = eye.querySelectorAll('path')[2];
+    if (!reduced()) {
+      keep(gsap.fromTo(eye, { scale: 0.7, filter: 'blur(3px)' }, { scale: 1, filter: 'blur(0px)', duration: 0.35, ease: EASE.click, clearProps: 'all' }));
+      if (slash) keep(gsap.fromTo(slash, { strokeDashoffset: show ? 1 : 0 }, { strokeDashoffset: show ? 0 : 1, duration: 0.3, ease: 'power2.out' }));
+    } else if (slash) gsap.set(slash, { strokeDashoffset: show ? 0 : 1 });
+  });
+  scope.add(() => root.removeAttribute('data-mk-visible'));
+  scope.add(() => input!.setCustomValidity(''));
+  gsap.set(eye.querySelectorAll('path')[2]!, { strokeDasharray: 1, strokeDashoffset: 1 });
+  for (const item of items) gsap.set(item.querySelector('path')!, { strokeDasharray: 1, strokeDashoffset: 0 });
+  paint(false);
+
+  return {
+    get score() {
+      return result.score;
+    },
+    get value() {
+      return input!.value;
+    },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/password-strength/password-strength.css

@@ -0,0 +1,182 @@
+/* password-strength — a Melonmind field (16 px radius, surface-container-high, 3 px focus ring) with an eye toggle,
+   four rounded segments that light up by level and a checklist whose checks draw themselves. */
+.mk-password-strength,
+mk-password-strength {
+  --mk-password-weak: var(--mk-error);
+  --mk-password-fair: #e8a317;
+  --mk-password-good: #3c9a5f;
+  --mk-password-strong: var(--mk-accent);
+  --mk-password-tone: var(--mk-outline);
+  display: grid;
+  gap: 0.75rem;
+  color: var(--mk-text);
+  font-family: var(--mk-font);
+}
+
+:is(.mk-password-strength, mk-password-strength):is([data-mk-score='0'], [data-mk-score='1']) {
+  --mk-password-tone: var(--mk-password-weak);
+}
+
+:is(.mk-password-strength, mk-password-strength)[data-mk-score='2'] {
+  --mk-password-tone: var(--mk-password-fair);
+}
+
+:is(.mk-password-strength, mk-password-strength)[data-mk-score='3'] {
+  --mk-password-tone: var(--mk-password-good);
+}
+
+:is(.mk-password-strength, mk-password-strength)[data-mk-score='4'] {
+  --mk-password-tone: var(--mk-password-strong);
+}
+
+:is(.mk-password-strength, mk-password-strength) [data-mk-password-field] {
+  position: relative;
+  display: flex;
+  align-items: center;
+}
+
+:is(.mk-password-strength, mk-password-strength) [data-mk-password] {
+  width: 100%;
+  min-height: 3.25rem;
+  padding: 0 3.5rem 0 1.1rem;
+  border: 0;
+  border-radius: 16px;
+  outline: none;
+  background: var(--mk-surface-4);
+  color: var(--mk-text);
+  font: inherit;
+  font-size: 1rem;
+  letter-spacing: 0.02em;
+  transition:
+    box-shadow 0.5s,
+    background-color 0.5s;
+}
+
+:is(.mk-password-strength, mk-password-strength) [data-mk-password]:hover {
+  background: var(--mk-surface-5);
+}
+
+:is(.mk-password-strength, mk-password-strength) [data-mk-password]:focus {
+  background: var(--mk-surface-2);
+  box-shadow:
+    0 0 0 3px var(--mk-outline-soft),
+    0 0.5px 2.5px rgb(0 0 0 / 0.3);
+}
+
+:is(.mk-password-strength, mk-password-strength) [data-mk-password-toggle] {
+  position: absolute;
+  right: 0.4rem;
+  display: grid;
+  place-items: center;
+  width: 2.5rem;
+  height: 2.5rem;
+  padding: 0;
+  border: 0;
+  border-radius: 50%;
+  background: transparent;
+  color: var(--mk-muted);
+  cursor: pointer;
+  transition:
+    background-color 0.2s ease,
+    color 0.2s ease;
+}
+
+:is(.mk-password-strength, mk-password-strength) [data-mk-password-toggle]:hover {
+  background: var(--mk-surface-3);
+  color: var(--mk-text);
+}
+
+:is(.mk-password-strength, mk-password-strength) [data-mk-password-toggle]:focus-visible {
+  outline: 2px solid var(--mk-accent);
+  outline-offset: 2px;
+}
+
+:is(.mk-password-strength, mk-password-strength) svg {
+  width: 1.25rem;
+  height: 1.25rem;
+  fill: none;
+  stroke: currentColor;
+  stroke-width: 1.8;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+}
+
+:is(.mk-password-strength, mk-password-strength) [data-mk-password-meter] {
+  display: grid;
+  grid-template-columns: repeat(4, minmax(0, 1fr)) auto;
+  align-items: center;
+  gap: 0.35rem;
+}
+
+:is(.mk-password-strength, mk-password-strength) [data-mk-password-meter] > span:not([data-mk-password-label]) {
+  height: 6px;
+  overflow: hidden;
+  border-radius: 64px;
+  background: var(--mk-surface-4);
+}
+
+:is(.mk-password-strength, mk-password-strength) [data-mk-password-meter] i {
+  display: block;
+  height: 100%;
+  border-radius: inherit;
+  background: var(--mk-password-tone);
+  transform: scaleX(0);
+  transform-origin: left center;
+  transition: background-color 0.3s ease;
+}
+
+:is(.mk-password-strength, mk-password-strength) [data-mk-password-label] {
+  min-width: 6.5rem;
+  margin-left: 0.4rem;
+  color: var(--mk-password-tone);
+  font-size: 0.8125rem;
+  font-weight: 500;
+  text-align: right;
+}
+
+:is(.mk-password-strength, mk-password-strength) [data-mk-password-checks] {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(10rem, 1fr));
+  gap: 0.3rem 1rem;
+  margin: 0;
+  padding: 0;
+  color: var(--mk-muted);
+  font-size: 0.8125rem;
+  list-style: none;
+}
+
+:is(.mk-password-strength, mk-password-strength) [data-mk-check] {
+  display: flex;
+  align-items: center;
+  gap: 0.4rem;
+  transition: color 0.2s ease;
+}
+
+:is(.mk-password-strength, mk-password-strength) [data-mk-check] svg {
+  flex: none;
+  width: 1rem;
+  height: 1rem;
+  padding: 2px;
+  border-radius: 50%;
+  background: var(--mk-surface-3);
+  stroke: transparent;
+  stroke-width: 3;
+  transition:
+    background-color 0.2s ease,
+    stroke 0.2s ease;
+}
+
+:is(.mk-password-strength, mk-password-strength) [data-mk-check][data-mk-met] {
+  color: var(--mk-text);
+}
+
+:is(.mk-password-strength, mk-password-strength) [data-mk-check][data-mk-met] svg {
+  background: var(--mk-password-good);
+  stroke: #fff;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :is(.mk-password-strength, mk-password-strength) :is([data-mk-password], [data-mk-check], [data-mk-check] svg, [data-mk-password-meter] i) {
+    transition: none;
+  }
+}

package/src/components/password-strength/react.tsx

@@ -0,0 +1,36 @@
+'use client';
+import { useRef, type InputHTMLAttributes } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createPasswordStrength, type PasswordStrengthOptions } from './engine';
+
+export interface PasswordStrengthProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'type' | 'onChange'>, Omit<PasswordStrengthOptions, 'onChange'> {
+  onStrength?: PasswordStrengthOptions['onChange'];
+  /** The text of the field as it changes. */
+  onValueChange?: (value: string) => void;
+}
+
+/** <PasswordStrength name="password" aria-label="Contraseña" requireScore={3} onStrength={setResult} />. The field stays uncontrolled. */
+export function PasswordStrength({ minLength, score, requireScore, labels, onStrength, onValueChange, className, ...props }: PasswordStrengthProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const strength = useLatest(onStrength);
+  const value = useLatest(onValueChange);
+  const scorer = useLatest(score);
+  const custom = score !== undefined;
+  const key = JSON.stringify(labels ?? {});
+  useIsomorphicLayoutEffect(() => {
+    const instance = createPasswordStrength(ref.current, {
+      minLength,
+      requireScore,
+      labels,
+      score: custom ? (text) => scorer.current!(text) : undefined,
+      onChange: (result) => strength.current?.(result),
+    });
+    return () => instance.destroy();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [minLength, requireScore, key, custom]);
+  return (
+    <div ref={ref} className={['mk-password-strength', className].filter(Boolean).join(' ')}>
+      <input autoComplete="new-password" aria-label="Contraseña" {...props} type="password" onInput={(event) => value.current?.(event.currentTarget.value)} />
+    </div>
+  );
+}

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

@@ -0,0 +1,62 @@
+/*
+ * Password strength (pure): length and variety raise the score, common
+ * passwords, runs (abc, 123) and repeats (aaa) lower it. 0–4, a label and the
+ * checks met. A heuristic for feedback, not a security guarantee: the server
+ * decides what it accepts.
+ */
+
+export interface PasswordChecks {
+  length: boolean;
+  lower: boolean;
+  upper: boolean;
+  number: boolean;
+  symbol: boolean;
+}
+
+export interface PasswordScore {
+  score: 0 | 1 | 2 | 3 | 4;
+  label: string;
+  checks: PasswordChecks;
+}
+
+export const STRENGTH_LABELS = ['Muy débil', 'Débil', 'Aceptable', 'Fuerte', 'Muy fuerte'] as const;
+
+const COMMON = new Set(
+  'password password1 123456 1234567 12345678 123456789 1234567890 qwerty qwerty123 abc123 111111 000000 iloveyou admin welcome letmein monkey dragon contraseña contrasena secreto hola123 football baseball sunshine princess'.split(' '),
+);
+
+const runs = (value: string) => {
+  const text = value.toLowerCase();
+  for (let i = 0; i + 2 < text.length; i++) {
+    const [a, b, c] = [text.charCodeAt(i), text.charCodeAt(i + 1), text.charCodeAt(i + 2)];
+    if ((b - a === 1 && c - b === 1) || (a - b === 1 && b - c === 1)) return true;
+  }
+  return false;
+};
+
+export function scorePassword(value: string, minLength = 8): PasswordScore {
+  const text = String(value ?? '');
+  const checks: PasswordChecks = {
+    length: text.length >= minLength,
+    lower: /[a-zà-ÿ]/.test(text),
+    upper: /[A-ZÀ-Þ]/.test(text),
+    number: /\d/.test(text),
+    symbol: /[^\p{L}\p{N}\s]/u.test(text),
+  };
+  if (!text) return { score: 0, label: '', checks };
+  const variety = [checks.lower, checks.upper, checks.number, checks.symbol].filter(Boolean).length;
+  let points = 0;
+  if (text.length >= minLength) points += 1;
+  if (text.length >= minLength + 4) points += 1;
+  if (text.length >= minLength + 8) points += 1;
+  if (variety >= 3) points += 1;
+  if (variety === 4) points += 1;
+  // Penalties count after the cap: a long, varied password with a pattern is not the best.
+  points = Math.min(4, points);
+  if (/(.)\1\1/.test(text)) points -= 1;
+  if (runs(text)) points -= 1;
+  if (text.length < minLength) points = Math.min(points, 1);
+  if (COMMON.has(text.toLowerCase())) points = 0;
+  const score = Math.max(0, Math.min(4, points)) as PasswordScore['score'];
+  return { score, label: STRENGTH_LABELS[score], checks };
+}

package/src/components/popover/README.md

@@ -0,0 +1,44 @@
+# popover
+
+Panel flotante interactivo anclado a su botón, sobre la misma superficie que `menu` y `color-picker`: crece desde el botón (transformación de contenedor de `motion/morph.ts`) mientras su contenido entra en cascada como las opciones de un menú (desde 90 % y un blur de 4 px, 40 ms entre piezas), y al cerrar se pliega de vuelta en él. Se cierra con Escape, con un clic fuera o con cualquier `[data-mk-close]` de dentro, y el foco vuelve al botón.
+
+Importa también `css/components/dialog.css` (o el CSS completo). La CLI lo copia: la entrada `requires` dialog.
+
+## HTML / Astro
+
+```html
+<mk-popover class="mk-popover">
+  <button class="mk-button" data-mk-popover-trigger>Filtros</button>
+  <div data-mk-popover-content>
+    <label class="mk-field">Estado <select>…</select></label>
+    <button class="mk-button mk-button--primary" data-mk-close>Aplicar</button>
+  </div>
+</mk-popover>
+```
+
+`[data-mk-popover-content]` pasa a un `<dialog>` que crea el motor y vuelve a su sitio al destruirlo. También puedes escribir directamente `<dialog data-mk-popover-panel>`.
+
+## React
+
+```tsx
+<Popover trigger={<button className="mk-button">Filtros</button>} onOpenChange={setOpen}>
+  <FiltersForm />
+</Popover>
+```
+
+Con `open` es controlado. `ref` da `open()` y `close()`.
+
+## Opciones
+
+| Opción | Atributo | Por defecto | Qué hace |
+|---|---|---|---|
+| `label` | `label` | el texto del botón | Nombre accesible del panel. |
+| `onOpenChange(open)` | — | — | Al abrirse o cerrarse. |
+
+## API y eventos
+
+`open()`, `close()`, `toggle()`, `isOpen`, `panel` (el `<dialog>`), `destroy()`. Evento `mk:open-change` con `{ open }`.
+
+## Estilo
+
+Esquinas de 20 px sobre `--mk-surface-1`, tan ancho como su contenido hasta 22rem, con 1rem de relleno. Se estiliza por clase (`.mk-popover-panel`), así la copia que se pliega al cerrar conserva su aspecto. En teléfonos el diálogo anclado se centra. Con movimiento reducido aparece sin crecer.

package/src/components/popover/element.ts

@@ -0,0 +1,31 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createPopover, type PopoverInstance } from './engine';
+
+/**
+ * <mk-popover class="mk-popover">
+ *   <button data-mk-popover-trigger>Filtros</button>
+ *   <div data-mk-popover-content>…</div>
+ * </mk-popover>
+ * Emits mk:open-change ({open}).
+ */
+export class MkPopoverElement extends MkElement<PopoverInstance> {
+  static options: Record<string, OptionType> = { label: 'string' };
+
+  protected create(options: Record<string, unknown>) {
+    return createPopover(this, options);
+  }
+
+  open() {
+    this.instance?.open();
+  }
+
+  close() {
+    this.instance?.close();
+  }
+
+  get isOpen() {
+    return this.instance?.isOpen ?? false;
+  }
+}
+
+export const definePopover = () => defineElement('mk-popover', MkPopoverElement);

package/src/components/popover/engine.ts

@@ -0,0 +1,114 @@
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { flowInMenu } from '../../motion/entrances';
+import { createDialog } from '../dialog/engine';
+
+/*
+ * Popover: an interactive panel anchored to its trigger, on the same anchored
+ * dialog surface as menu and color-picker. It grows out of the trigger
+ * (motion/morph.ts container transform) while its content flows in like a
+ * menu's options (from 90 % out of a 4 px blur, 40 ms apart), folds back into
+ * the trigger on close, closes with Escape, a click outside or any
+ * [data-mk-close] inside, and gives the focus back to the trigger. A
+ * dialog[data-mk-popover-panel] is used as it is; [data-mk-popover-content] is
+ * moved into a dialog the engine creates and put back on destroy.
+ */
+
+export interface PopoverOptions {
+  /** Accessible name of the panel (default: the trigger's text). */
+  label?: string;
+  onOpenChange?: (open: boolean) => void;
+}
+
+export interface PopoverInstance extends Instance {
+  open(): void;
+  close(): void;
+  toggle(): void;
+  readonly isOpen: boolean;
+  /** The panel (a <dialog>). */
+  readonly panel: HTMLElement | null;
+}
+
+let sequence = 0;
+
+export function createPopover(root: HTMLElement | null, options: PopoverOptions = {}): PopoverInstance {
+  const inertInstance = inert<PopoverInstance>({ open() {}, close() {}, toggle() {}, isOpen: false, panel: null });
+  if (!root) return inertInstance;
+  let dialog = root.querySelector<HTMLDialogElement>('dialog[data-mk-popover-panel]');
+  const content = dialog ? null : root.querySelector<HTMLElement>('[data-mk-popover-content]');
+  const trigger =
+    root.querySelector<HTMLElement>('[data-mk-popover-trigger]') ??
+    [...root.querySelectorAll<HTMLElement>('button, a[href], [role="button"]')].find((element) => !dialog?.contains(element) && !content?.contains(element)) ??
+    null;
+  if (!trigger || (!dialog && !content)) return inertInstance;
+  const scope = createScope();
+
+  if (!dialog) {
+    // The authored content moves into a dialog in its place, and back on destroy.
+    const created = document.createElement('dialog');
+    const anchor = content!.nextSibling;
+    const parent = content!.parentNode!;
+    parent.insertBefore(created, content);
+    created.append(content!);
+    dialog = created;
+    scope.add(() => {
+      if (content!.isConnected || created.isConnected) parent.insertBefore(content!, created.isConnected ? created : anchor);
+      created.remove();
+    });
+  }
+  const panel = dialog;
+  // Classes, not only attributes: the copy that folds back into the trigger on close keeps classes only.
+  scope.attr(panel, 'class', [panel.getAttribute('class'), 'mk-dialog', 'mk-popover-panel'].filter(Boolean).join(' '));
+  if (!panel.id) scope.attr(panel, 'id', `mk-popover-${++sequence}`);
+  if (!panel.hasAttribute('aria-label') && !panel.hasAttribute('aria-labelledby')) scope.attr(panel, 'aria-label', options.label ?? trigger.textContent?.trim() ?? 'Panel');
+  scope.attr(trigger, 'aria-haspopup', 'dialog');
+  scope.attr(trigger, 'aria-expanded', 'false');
+  scope.attr(trigger, 'aria-controls', panel.id);
+  scope.attr(root, 'data-mk-ready', '');
+
+  const announce = (open: boolean) => {
+    trigger.setAttribute('aria-expanded', String(open));
+    options.onOpenChange?.(open);
+    root.dispatchEvent(new CustomEvent('mk:open-change', { bubbles: true, detail: { open } }));
+  };
+  let flow: ReturnType<typeof flowInMenu> = null;
+  const surface = createDialog(panel, {
+    placement: 'anchor',
+    backdrop: false,
+    drag: false,
+    autoResize: false,
+    triggers: false,
+    animateContent: false,
+    // Like a menu's options: the content flows in while the surface grows out of the trigger.
+    onOpen: () => {
+      flow?.kill();
+      flow = flowInMenu([...panel.children].filter((child) => !child.classList.contains('mk-morph-face')));
+      announce(true);
+    },
+    onClose: () => announce(false),
+  });
+  scope.add(() => {
+    flow?.kill();
+    surface.destroy();
+  });
+
+  const open = () => {
+    if (!surface.isOpen) surface.open(trigger);
+  };
+  scope.on(trigger, 'click', (event) => {
+    event.preventDefault();
+    if (surface.isOpen) surface.close();
+    else open();
+  });
+
+  return {
+    open,
+    close: () => surface.close(),
+    toggle: () => (surface.isOpen ? surface.close() : open()),
+    get isOpen() {
+      return surface.isOpen;
+    },
+    panel,
+    destroy: () => scope.dispose(),
+  };
+}