@yewdiel21/motion-kit 0.10.0 → 0.14.0

package/src/components/command-search/element.ts

@@ -0,0 +1,36 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createCommandSearch, type CommandItem, type CommandSearchInstance } from './engine';
+
+/**
+ * <mk-command-search class="mk-command-search" items='[{"id":"charts","label":"Charts","group":"Páginas","href":"/chart"}]'>
+ *   <button data-mk-command-open>Buscar <kbd>⌘K</kbd></button>
+ * </mk-command-search>
+ * ⌘K / Ctrl+K or the button opens it. Emits mk:select ({item}, cancelable), mk:open and mk:close.
+ */
+export class MkCommandSearchElement extends MkElement<CommandSearchInstance> {
+  static options: Record<string, OptionType> = { items: 'json', placeholder: 'string', emptyLabel: 'string', label: 'string', shortcut: 'boolean', limit: 'number' };
+
+  protected create(options: Record<string, unknown>) {
+    return createCommandSearch(this, options);
+  }
+
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.instance) return;
+    if (name === 'items') this.instance.setItems((this.options.items as CommandItem[] | undefined) ?? []);
+    else super.attributeChangedCallback(name, previous, next);
+  }
+
+  open() {
+    this.instance?.open();
+  }
+
+  close() {
+    this.instance?.close();
+  }
+
+  setItems(items: CommandItem[]) {
+    this.instance?.setItems(items);
+  }
+}
+
+export const defineCommandSearch = () => defineElement('mk-command-search', MkCommandSearchElement);

package/src/components/command-search/engine.ts

@@ -0,0 +1,356 @@
+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 { blurIn } from '../../motion/micro';
+import { morphClose, morphOpen, releaseShared, showOrigin } from '../../motion/morph';
+import { fadeBackdrop, openModal } from '../../motion/surface';
+import { matchScore } from './match';
+
+/*
+ * Command search: a command palette in a modal <dialog> on Melonmind's dark
+ * glass. ⌘K / Ctrl+K or a [data-mk-command-open] button opens it; it grows out
+ * of the button that opened it (motion/morph.ts container transform: the
+ * button's colour fades into the panel, the shape travels .7 s) and folds back
+ * into it on close. Typing filters by fuzzy
+ * match with the letters marked (as text); results are grouped. A pill glides
+ * under the active result on the swing curve; arrows, Home and End move it,
+ * Enter picks it (onSelect, mk:select; an href navigates), Escape closes and
+ * focus goes back. Combobox + listbox semantics with aria-activedescendant.
+ */
+
+export interface CommandItem {
+  id: string;
+  label: string;
+  /** Section title (e.g. 'Páginas'). */
+  group?: string;
+  /** Extra words that also match. */
+  keywords?: string[];
+  /** Small text on the right (a shortcut, a path). */
+  hint?: string;
+  /** Navigate here when chosen (unless mk:select is cancelled). */
+  href?: string;
+  /** A short glyph shown before the label (default →). */
+  icon?: string;
+}
+
+export interface CommandSearchOptions {
+  items?: CommandItem[];
+  placeholder?: string;
+  emptyLabel?: string;
+  /** Accessible name of the palette. */
+  label?: string;
+  /** ⌘K / Ctrl+K opens it (default true). */
+  shortcut?: boolean;
+  /** Most results shown (default 50). */
+  limit?: number;
+  onSelect?: (item: CommandItem) => void;
+  onOpenChange?: (open: boolean) => void;
+}
+
+export interface CommandSearchInstance extends Instance {
+  /** `origin`: the control it grows from; omitted, the clicked or on-screen trigger; null, none (scale-in). */
+  open(origin?: HTMLElement | null): void;
+  close(): void;
+  setItems(items: CommandItem[]): void;
+  readonly isOpen: boolean;
+}
+
+const SEARCH_ICON =
+  '<svg aria-hidden="true" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><circle cx="11" cy="11" r="6.5"/><path d="M16 16l4 4"/></svg>';
+let sequence = 0;
+
+const el = <K extends keyof HTMLElementTagNameMap>(tag: K, attrs: Record<string, string> = {}, text?: string) => {
+  const element = document.createElement(tag);
+  for (const [name, value] of Object.entries(attrs)) element.setAttribute(name, value);
+  if (text !== undefined) element.textContent = text;
+  return element;
+};
+
+/** `text` with the ranges wrapped in <mark>, built as text nodes. */
+function marked(text: string, ranges: Array<[number, number]>) {
+  const fragment = document.createDocumentFragment();
+  let at = 0;
+  for (const [start, end] of ranges) {
+    if (start > at) fragment.append(text.slice(at, start));
+    fragment.append(el('mark', {}, text.slice(start, end)));
+    at = end;
+  }
+  if (at < text.length) fragment.append(text.slice(at));
+  return fragment;
+}
+
+export function createCommandSearch(root: HTMLElement | null, options: CommandSearchOptions = {}): CommandSearchInstance {
+  if (!root) return inert({ open() {}, close() {}, setItems() {}, isOpen: false });
+  registerMotion();
+  const scope = createScope();
+  const uid = `mk-command-${++sequence}`;
+  let items = [...(options.items ?? [])];
+  const limit = Number.isFinite(options.limit) && options.limit! > 0 ? Math.floor(options.limit!) : 50;
+
+  const dialog = el('dialog', { 'data-mk-command': '', 'aria-label': options.label ?? 'Buscar' }) as HTMLDialogElement;
+  const panel = el('div', { 'data-mk-command-panel': '' });
+  const field = el('div', { 'data-mk-command-field': '' });
+  const glass = el('span', { 'data-mk-command-icon': '', 'aria-hidden': 'true' });
+  glass.innerHTML = SEARCH_ICON;
+  const input = el('input', {
+    type: 'text',
+    role: 'combobox',
+    'aria-expanded': 'true',
+    'aria-controls': `${uid}-list`,
+    'aria-autocomplete': 'list',
+    autocomplete: 'off',
+    spellcheck: 'false',
+    placeholder: options.placeholder ?? 'Buscar…',
+    'aria-label': options.label ?? 'Buscar',
+  });
+  field.append(glass, input);
+  const list = el('div', { 'data-mk-command-list': '', role: 'listbox', id: `${uid}-list`, 'aria-label': 'Resultados' });
+  const pill = el('span', { 'data-mk-command-pill': '', 'aria-hidden': 'true' });
+  const empty = el('p', { 'data-mk-command-empty': '' }, options.emptyLabel ?? 'Sin resultados');
+  empty.hidden = true;
+  const live = el('span', { class: 'mk-sr-only', role: 'status' });
+  const footer = el('footer', { 'data-mk-command-footer': '', 'aria-hidden': 'true' });
+  footer.append(el('kbd', {}, '↑'), el('kbd', {}, '↓'), el('span', {}, 'Navegar'), el('kbd', {}, '↵'), el('span', {}, 'Seleccionar'));
+  const scroller = el('div', { 'data-mk-command-scroll': '' });
+  scroller.append(pill, list, empty);
+  panel.append(field, scroller, footer, live);
+  dialog.append(panel);
+  root.append(dialog);
+  scope.add(() => dialog.remove());
+  scope.attr(root, 'data-mk-ready', '');
+
+  let isOpen = false;
+  let opener: HTMLElement | null = null;
+  /** The control the panel grows from and folds back into. */
+  let from: HTMLElement | null = null;
+  let closing = false;
+  let backdropOut: Animation | null = null;
+  const onScreen = (element: HTMLElement) => {
+    const box = element.getBoundingClientRect();
+    return box.width > 0 && box.height > 0 && box.bottom > 0 && box.right > 0 && box.top < innerHeight && box.left < innerWidth;
+  };
+  const originFor = (given: HTMLElement | null | undefined) => {
+    if (given !== undefined) return given;
+    const trigger = root.querySelector<HTMLElement>('[data-mk-command-open]');
+    return trigger && onScreen(trigger) ? trigger : null;
+  };
+  let shown: CommandItem[] = [];
+  let active = -1;
+  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(() => {
+    for (const effect of effects) effect.kill();
+    effects.clear();
+    gsap.killTweensOf(pill);
+  });
+
+  const options_ = () => [...list.querySelectorAll<HTMLElement>('[role="option"]')];
+  const movePill = (animate: boolean) => {
+    const option = options_()[active];
+    if (!option) {
+      pill.style.opacity = '0';
+      return;
+    }
+    const box = { y: option.offsetTop, height: option.offsetHeight, width: option.offsetWidth, x: option.offsetLeft };
+    if (!animate || reduced() || pill.style.opacity === '0') {
+      gsap.set(pill, box);
+      pill.style.opacity = '1';
+      return;
+    }
+    keep(gsap.to(pill, { ...box, duration: 0.3, ease: EASE.swatch, overwrite: 'auto' }));
+  };
+
+  const setActive = (index: number, animate = true) => {
+    const all = options_();
+    if (!all.length) {
+      active = -1;
+      input.removeAttribute('aria-activedescendant');
+      movePill(false);
+      return;
+    }
+    active = (index + all.length) % all.length;
+    all.forEach((option, i) => option.setAttribute('aria-selected', String(i === active)));
+    input.setAttribute('aria-activedescendant', all[active]!.id);
+    all[active]!.scrollIntoView?.({ block: 'nearest' });
+    movePill(animate);
+  };
+
+  const render = (animate: boolean) => {
+    const query = input.value;
+    const scored = items
+      .map((item, order) => {
+        const own = matchScore(query, item.label);
+        const extra = own ? null : [item.group ?? '', ...(item.keywords ?? [])].map((word) => matchScore(query, word)).find(Boolean);
+        const result = own ?? (extra ? { score: extra.score - 20, ranges: [] as Array<[number, number]> } : null);
+        return result ? { item, order, ...result } : null;
+      })
+      .filter((entry): entry is NonNullable<typeof entry> => Boolean(entry));
+    if (query.trim()) scored.sort((a, b) => b.score - a.score || a.order - b.order);
+    const top = scored.slice(0, limit);
+    shown = top.map((entry) => entry.item);
+    list.replaceChildren();
+    const groups = new Map<string, HTMLElement>();
+    top.forEach((entry, i) => {
+      const name = entry.item.group ?? '';
+      let group = groups.get(name);
+      if (!group) {
+        group = el('div', { role: 'group', 'data-mk-command-group': '' });
+        if (name) {
+          const title = el('div', { 'data-mk-command-group-label': '', id: `${uid}-g${groups.size}` }, name);
+          group.setAttribute('aria-labelledby', title.id);
+          group.append(title);
+        }
+        groups.set(name, group);
+        list.append(group);
+      }
+      const option = el('div', { role: 'option', id: `${uid}-o${i}`, 'data-mk-command-item': '', 'data-mk-index': String(i), 'aria-selected': 'false' });
+      option.append(el('span', { 'data-mk-command-arrow': '', 'aria-hidden': 'true' }, entry.item.icon ?? '→'));
+      const label = el('span', { 'data-mk-command-label': '' });
+      label.append(marked(entry.item.label, entry.ranges));
+      option.append(label);
+      if (entry.item.hint) option.append(el('span', { 'data-mk-command-hint': '' }, entry.item.hint));
+      group.append(option);
+    });
+    // Options were built in score order but sit under their group: index them in document order.
+    shown = options_().map((option, i) => {
+      const item = top[Number(option.dataset.mkIndex)]!.item;
+      option.dataset.mkIndex = String(i);
+      option.id = `${uid}-o${i}`;
+      return item;
+    });
+    empty.hidden = top.length > 0;
+    live.textContent = top.length ? `${top.length} ${top.length === 1 ? 'resultado' : 'resultados'}` : (options.emptyLabel ?? 'Sin resultados');
+    setActive(0, false);
+    if (animate) keep(blurIn(options_().slice(0, 12), { stagger: 0.025, duration: 0.35 }));
+  };
+
+  const finish = () => {
+    backdropOut?.cancel();
+    backdropOut = null;
+    if (dialog.open) dialog.close();
+    showOrigin(from);
+    releaseShared(from);
+    from = null;
+    closing = false;
+    isOpen = false;
+    options.onOpenChange?.(false);
+    root.dispatchEvent(new CustomEvent('mk:close', { bubbles: true }));
+    if (opener?.isConnected) opener.focus({ preventScroll: true });
+    opener = null;
+  };
+
+  const open = (origin?: HTMLElement | null) => {
+    if (scope.disposed || isOpen) return;
+    const focused = document.activeElement;
+    opener = focused instanceof HTMLElement && focused !== document.body ? focused : null;
+    from = originFor(origin);
+    isOpen = true;
+    input.value = '';
+    openModal(dialog);
+    // The rows grow with the panel: no entrance of their own on open.
+    render(false);
+    input.focus();
+    void fadeBackdrop(dialog, 'in');
+    morphOpen(panel, from, { hideOrigin: true });
+    options.onOpenChange?.(true);
+    root.dispatchEvent(new CustomEvent('mk:open', { bubbles: true, detail: { origin: from } }));
+  };
+
+  const close = () => {
+    if (!isOpen || closing) return;
+    closing = true;
+    // The backdrop fades with the fold; finish() drops this animation once the dialog is closed.
+    if (!reduced() && typeof dialog.animate === 'function') {
+      try {
+        backdropOut = dialog.animate([{ opacity: 1 }, { opacity: 0 }], { duration: 300, easing: 'linear', fill: 'forwards', pseudoElement: '::backdrop' });
+      } catch {
+        backdropOut = null;
+      }
+    }
+    morphClose(panel, from, finish);
+  };
+
+  const choose = (index: number) => {
+    const item = shown[index];
+    if (!item) return;
+    const event = new CustomEvent('mk:select', { bubbles: true, cancelable: true, detail: { item } });
+    options.onSelect?.(item);
+    const go = root.dispatchEvent(event) && item.href;
+    close();
+    if (go) location.assign(item.href!);
+  };
+
+  scope.on(input, 'input', () => render(false));
+  scope.on(input, 'keydown', (event) => {
+    const key = (event as KeyboardEvent).key;
+    const count = options_().length;
+    const moves: Record<string, number> = { ArrowDown: active + 1, ArrowUp: active - 1, Home: 0, End: count - 1 };
+    if (key in moves && count) {
+      event.preventDefault();
+      setActive(moves[key]!);
+    } else if (key === 'Enter') {
+      event.preventDefault();
+      choose(active);
+    }
+  });
+  scope.on(list, 'pointermove', (event) => {
+    const option = (event.target as Element | null)?.closest<HTMLElement>('[role="option"]');
+    if (option) {
+      const index = Number(option.dataset.mkIndex);
+      if (index !== active) setActive(index);
+    }
+  });
+  scope.on(list, 'click', (event) => {
+    const option = (event.target as Element | null)?.closest<HTMLElement>('[role="option"]');
+    if (option) choose(Number(option.dataset.mkIndex));
+  });
+  scope.on(dialog, 'cancel', (event) => {
+    event.preventDefault();
+    close();
+  });
+  scope.on(dialog, 'click', (event) => {
+    if (event.target === dialog) close();
+  });
+  scope.on(root, 'click', (event) => {
+    const trigger = (event.target as Element | null)?.closest('[data-mk-command-open]');
+    if (trigger && root.contains(trigger)) {
+      event.preventDefault();
+      open(trigger as HTMLElement);
+    }
+  });
+  if (options.shortcut !== false) {
+    scope.on(document, 'keydown', (event) => {
+      const key = event as KeyboardEvent;
+      if ((key.metaKey || key.ctrlKey) && key.key.toLowerCase() === 'k') {
+        key.preventDefault();
+        if (isOpen) close();
+        else open();
+      }
+    });
+  }
+  scope.add(() => {
+    backdropOut?.cancel();
+    showOrigin(from);
+    releaseShared(from);
+    if (dialog.open) dialog.close();
+  });
+
+  return {
+    open,
+    close,
+    setItems(next) {
+      items = [...next];
+      if (isOpen) render(false);
+    },
+    get isOpen() {
+      return isOpen;
+    },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/command-search/match.ts

@@ -0,0 +1,53 @@
+/*
+ * Fuzzy matching for the command search: the query's letters must appear in
+ * order (case and accents ignored). Word starts and runs of consecutive letters
+ * score higher; gaps cost. Returns the matched ranges for highlighting.
+ */
+
+export interface Match {
+  score: number;
+  /** [start, end) ranges in the original text. */
+  ranges: Array<[number, number]>;
+}
+
+const fold = (text: string) => text.normalize('NFD').replace(/[̀-ͯ]/g, '').toLowerCase();
+
+export function matchScore(query: string, text: string): Match | null {
+  const needle = fold(query.trim());
+  if (!needle) return { score: 0, ranges: [] };
+  // Folding removes combining marks, so map folded positions back to the original text.
+  const map: number[] = [];
+  let hay = '';
+  for (let i = 0; i < text.length; i++) {
+    const folded = fold(text[i]!);
+    for (const char of folded) {
+      hay += char;
+      map.push(i);
+    }
+  }
+  // A plain substring wins outright (best at a word start).
+  const direct = hay.indexOf(needle);
+  if (direct >= 0) {
+    const start = direct === 0 || /[\s\-_/.]/.test(hay[direct - 1]!) ? 30 : 15;
+    return { score: 100 + start - direct * 0.5, ranges: [[map[direct]!, map[direct + needle.length - 1]! + 1]] };
+  }
+  let score = 0;
+  let at = 0;
+  let previous = -2;
+  const ranges: Array<[number, number]> = [];
+  for (const char of needle) {
+    if (char === ' ') continue;
+    const found = hay.indexOf(char, at);
+    if (found < 0) return null;
+    const wordStart = found === 0 || /[\s\-_/.]/.test(hay[found - 1]!);
+    score += wordStart ? 8 : found === previous + 1 ? 5 : 1;
+    score -= Math.min(4, (found - at) * 0.2);
+    const original = map[found]!;
+    const last = ranges[ranges.length - 1];
+    if (last && last[1] === original) last[1] = original + 1;
+    else ranges.push([original, original + 1]);
+    previous = found;
+    at = found + 1;
+  }
+  return { score, ranges };
+}

package/src/components/command-search/react.tsx

@@ -0,0 +1,66 @@
+'use client';
+import { useRef, type HTMLAttributes, type MutableRefObject, type ReactNode } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createCommandSearch, type CommandItem, type CommandSearchInstance } from './engine';
+
+export interface CommandSearchProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'onSelect' | 'children'> {
+  items: CommandItem[];
+  placeholder?: string;
+  emptyLabel?: string;
+  label?: string;
+  shortcut?: boolean;
+  limit?: number;
+  /** The trigger's content (default: «Buscar» and the shortcut). null hides the trigger. */
+  trigger?: ReactNode;
+  onSelect?: (item: CommandItem) => void;
+  onOpenChange?: (open: boolean) => void;
+  instanceRef?: MutableRefObject<CommandSearchInstance | null>;
+}
+
+/** <CommandSearch items={commands} onSelect={(item) => navigate(item.id)} />: ⌘K / Ctrl+K or the trigger opens it. */
+export function CommandSearch({ items, placeholder, emptyLabel, label, shortcut, limit, trigger, onSelect, onOpenChange, instanceRef, className, ...props }: CommandSearchProps) {
+  const ref = useRef<HTMLSpanElement>(null);
+  const instance = useRef<CommandSearchInstance | null>(null);
+  const select = useLatest(onSelect);
+  const change = useLatest(onOpenChange);
+  const latest = useLatest(items);
+  useIsomorphicLayoutEffect(() => {
+    const created = createCommandSearch(ref.current, {
+      items: latest.current,
+      placeholder,
+      emptyLabel,
+      label,
+      shortcut,
+      limit,
+      onSelect: (item) => select.current?.(item),
+      onOpenChange: (open) => change.current?.(open),
+    });
+    instance.current = created;
+    if (instanceRef) instanceRef.current = created;
+    return () => {
+      created.destroy();
+      instance.current = null;
+      if (instanceRef) instanceRef.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [placeholder, emptyLabel, label, shortcut, limit]);
+  const key = JSON.stringify(items);
+  useIsomorphicLayoutEffect(() => {
+    instance.current?.setItems(latest.current);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key]);
+  return (
+    <span {...props} ref={ref} className={['mk-command-search', className].filter(Boolean).join(' ')}>
+      {trigger === null ? null : (
+        <button type="button" data-mk-command-open="" aria-haspopup="dialog">
+          {trigger ?? (
+            <>
+              <span>Buscar…</span>
+              <kbd aria-hidden="true">⌘K</kbd>
+            </>
+          )}
+        </button>
+      )}
+    </span>
+  );
+}

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

@@ -0,0 +1,31 @@
+# context-menu
+
+Menú contextual sobre el motor de [menu](../menu/README.md): misma superficie translúcida, cascada de opciones, flechas/Inicio/Fin, Enter, Escape, opciones deshabilitadas y separadores. Se abre con clic derecho en el puntero, con la tecla Menú o Shift+F10 junto al elemento enfocado, y con pulsación larga en táctil. Aparece con escala donde se abre (sin morph desde un origen invisible), se mantiene dentro del viewport y devuelve el foco al elemento enfocado antes de abrir.
+
+```html
+<mk-context-menu class="mk-context-menu">
+  <article class="file-tile">Informe.pdf</article>
+  <dialog class="mk-dialog mk-menu" data-mk-context-menu aria-label="Acciones del archivo">
+    <button data-mk-item data-mk-value="open">Abrir</button>
+    <button data-mk-item data-mk-value="rename">Renombrar</button>
+    <hr data-mk-separator />
+    <button data-mk-item data-mk-value="delete" disabled>Eliminar</button>
+  </dialog>
+</mk-context-menu>
+```
+
+`defineElements()` o `createContextMenu(root, options)`; el área es `[data-mk-context-trigger]` o, si no hay, el root (recibe `tabindex="0"` si no es enfocable). React:
+
+```tsx
+<ContextMenu
+  label="Acciones"
+  onSelect={(value) => run(value)}
+  menu={<><ContextMenu.Item value="open">Abrir</ContextMenu.Item><ContextMenu.Separator /><ContextMenu.Item value="delete" disabled>Eliminar</ContextMenu.Item></>}
+>
+  <FileTile />
+</ContextMenu>
+```
+
+Opciones: las de Menu (`variant`, `closeOnSelect`, `onSelect`, `labels`…) más `overrideEditable` (por defecto los inputs y el texto editable conservan el menú del navegador), `longPress=550` ms (0 lo desactiva) y `onOpenChange(open)`. API: `openAt(x, y, origin?)`, `open(origin?)`, `close()`, `isOpen`, `menu`, `destroy()`. Eventos de Menu/Dialog: `mk:select` `{value, item}`, `mk:open`, `mk:closed`. El área recibe `aria-haspopup="menu"` y `aria-expanded` mientras está abierto.
+
+En móvil (menos de 680 px) el menú se centra como el resto de menús anclados. `destroy()` cierra sin animación y restaura atributos.

package/src/components/context-menu/context-menu.css

@@ -0,0 +1,22 @@
+/* context-menu — the area that answers a right click; its menu is .mk-menu, placed at the pointer. */
+mk-context-menu {
+  display: block;
+}
+
+.mk-context-menu,
+mk-context-menu {
+  -webkit-touch-callout: none;
+}
+
+:is(.mk-context-menu, mk-context-menu):focus-visible,
+:is(.mk-context-menu, mk-context-menu) [data-mk-context-trigger]:focus-visible {
+  outline: 2px solid var(--mk-accent);
+  outline-offset: 3px;
+}
+
+/* The area pressed while its menu is open. */
+:is(.mk-context-menu, mk-context-menu)[aria-expanded='true'],
+:is(.mk-context-menu, mk-context-menu) [data-mk-context-trigger][aria-expanded='true'] {
+  outline: 2px solid color-mix(in srgb, var(--mk-accent) 45%, transparent);
+  outline-offset: 3px;
+}

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

@@ -0,0 +1,40 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createContextMenu, type ContextMenuInstance } from './engine';
+
+/**
+ * <mk-context-menu class="mk-context-menu">
+ *   <article>…the area…</article>
+ *   <dialog class="mk-dialog mk-menu" data-mk-context-menu aria-label="Acciones">
+ *     <button data-mk-item data-mk-value="rename">Renombrar</button>
+ *     <hr data-mk-separator />
+ *     <button data-mk-item data-mk-value="delete" disabled>Eliminar</button>
+ *   </dialog>
+ * </mk-context-menu>
+ * Emits mk:select (detail.value, detail.item) from the dialog.
+ */
+export class MkContextMenuElement extends MkElement<ContextMenuInstance> {
+  static options: Record<string, OptionType> = { keepOpen: 'boolean', overrideEditable: 'boolean', longPress: 'number', variant: 'string' };
+
+  protected create(options: Record<string, unknown>) {
+    const { keepOpen, ...rest } = options;
+    return createContextMenu(this, { ...rest, closeOnSelect: !keepOpen });
+  }
+
+  openAt(x: number, y: number) {
+    this.instance?.openAt(x, y);
+  }
+
+  open(origin?: HTMLElement | null) {
+    this.instance?.open(origin);
+  }
+
+  close() {
+    this.instance?.close();
+  }
+
+  get isOpen() {
+    return this.instance?.isOpen ?? false;
+  }
+}
+
+export const defineContextMenu = () => defineElement('mk-context-menu', MkContextMenuElement);