@panphora/clayjs 1.21.0 → 1.23.0

package/src/plugins/menu/shell-style.js

@@ -0,0 +1,143 @@
+export const MENU_SAFETY = `@layer clay-menu-safety {
+  .clay-menu-dock [hidden], .clay-menu-spots[hidden], .clay-menu-dock[hidden] { display: none !important; }
+  .clay-menu :focus-visible:not(.clay-menu-edit) { outline: 2px solid var(--bevel-brass) !important; outline-offset: -2px !important; }
+  @media (pointer: coarse), (max-width: 680px) {
+    .clay-menu-goo, .clay-menu-list [part~="dismiss"], .clay-menu-list [part~="step"], .clay-menu-list [role^="menuitem"] { min-width: 44px !important; min-height: 44px !important; }
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .clay-menu-dock *, .clay-menu-dock *::before, .clay-menu-dock *::after { transition: none !important; animation: none !important; }
+  }
+  @media (forced-colors: active) {
+    .clay-menu-list { border: 1px solid CanvasText !important; }
+    .clay-menu :focus-visible:not(.clay-menu-edit) { outline-color: Highlight !important; }
+  }
+}
+`;
+
+export const SHELL_A = `.clay-menu-dock, .clay-menu-spots, .clay-seo {
+  --bevel-font-sans: system-ui, -apple-system, "Segoe UI", sans-serif;
+  --bevel-font-serif: Newsreader, Georgia, "Times New Roman", serif;
+  --bevel-font-mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  --bevel-ground: light-dark(#FDF8F0, #0B0C13);
+  --bevel-surface: light-dark(#FFFCF6, #1A1D2C);
+  --bevel-sunk: light-dark(#F4ECDF, #22263A);
+  --bevel-ink: light-dark(#2B241B, #ECEAF2);
+  --bevel-ink-2: light-dark(#4A4033, #C9CDE0);
+  --bevel-muted: light-dark(#6B5942, #A3A9C2);
+  --bevel-faint: light-dark(#9A8A70, #6A7090);
+  --bevel-line: light-dark(#E8DCC6, #2C3149);
+  --bevel-line-2: light-dark(#D8C8AF, #3A4058);
+  --bevel-line-3: light-dark(#C4B192, #4A536F);
+  --bevel-brass: light-dark(#8F6310, #D9A445);
+  --bevel-brass-soft: light-dark(#F0E4CC, #3A2F17);
+  --bevel-ox: light-dark(#A83A2C, #FF6B79);
+  --bevel-ox-soft: light-dark(#F6DED6, #3A2226);
+  --bevel-teal: light-dark(#256056, #4E9C8C);
+  --bevel-teal-soft: light-dark(#DCEBE7, #17332E);
+  --bevel-face: light-dark(#F1E7D4, #2A2F48);
+  --bevel-edge-hi: light-dark(#FFF9ED, #454C6C);
+  --bevel-edge-lo: light-dark(#D6C3A5, #171B2C);
+  --bevel-face-in: light-dark(#E3D0B3, #20253B);
+  --bevel-edge-in: light-dark(#B89F7B, #12152A);
+  --bevel-edge-in-hi: light-dark(#F0E1C9, #4D587A);
+  --bevel-knob: light-dark(#FCF8F1, #5A6286);
+  --bevel-knob-hi: light-dark(#FFF9ED, #7A83A8);
+  --clay-shadow: 0 1px 2px light-dark(rgb(43 36 27 / .07), rgb(0 0 0 / .35)), 0 10px 28px -10px light-dark(rgb(43 36 27 / .32), rgb(0 0 0 / .7));
+  --clay-sheet-shadow: 0 16px 30px -22px light-dark(rgb(43 36 27 / .45), rgb(0 0 0 / .85));
+  color-scheme: inherit;
+  font-family: var(--bevel-font-sans);
+  color: var(--bevel-ink);
+  -webkit-text-size-adjust: 100%;
+  text-size-adjust: 100%;
+}
+
+.clay-menu-dock { display: flex; align-items: center; gap: 6px; font-size: 13px; line-height: 1.4; }
+.clay-menu-dock[data-embedded] { position: relative; display: inline-flex; }
+.clay-menu-dock[hidden], .clay-menu-spots[hidden], .clay-menu-dock [hidden], .clay-seo [hidden] { display: none !important; }
+
+.clay-menu { box-sizing: border-box; display: inline-flex; align-items: center; gap: 2px; user-select: none; -webkit-user-select: none; }
+
+`;
+
+export const SHELL_B = `.clay-menu-goo { position: relative; display: inline-grid; place-items: center; box-sizing: border-box; margin: 0; padding: 0; cursor: pointer; }
+.clay-menu-goo svg { display: block; }
+.clay-menu-dot { position: absolute; top: -1px; right: -2px; width: 8px; height: 8px; border-radius: 50%; background: var(--bevel-brass); box-shadow: 0 0 0 2px var(--bevel-surface); }
+
+.clay-menu :focus-visible, .clay-roster:focus-visible { outline: 2px solid var(--bevel-brass); outline-offset: 2px; }
+.clay-menu-edit:focus-visible { outline: none; }
+.clay-menu-edit:focus-visible .clay-menu-track { outline: 2px solid var(--bevel-brass); outline-offset: 2px; }
+
+`;
+
+export const SHELL_C = `/* Popovers: the menu, the people panel, the status note. Below the dock, above it in a bottom corner. */
+.clay-menu-list, .clay-people, .clay-menu-note { position: absolute; z-index: 1; top: calc(100% + 8px); right: 0; box-sizing: border-box; margin: 0; color: var(--bevel-ink); text-align: left; }
+.clay-people, .clay-menu-note { border: 1px solid var(--bevel-line-2); background: var(--bevel-surface); box-shadow: var(--clay-shadow); }
+
+.clay-menu-list { width: max-content; max-width: calc(100vw - 24px); max-height: calc(100dvh - 72px); overflow-y: auto; overscroll-behavior: contain; }
+.clay-menu-list[popover] { position: fixed; inset: auto; margin: 0; }
+.clay-menu-list [role^="menuitem"] { box-sizing: border-box; display: flex; align-items: center; justify-content: space-between; gap: 12px; width: 100%; margin: 0; border: 0; background: none; text-align: left; text-decoration: none; cursor: pointer; }
+.clay-menu-list [role^="menuitem"]:hover:not([aria-disabled="true"]), .clay-menu-list [role^="menuitem"]:focus-visible { outline: none; background: var(--bevel-sunk); }
+.clay-menu-list [role^="menuitem"][aria-disabled="true"] { cursor: default; }
+.clay-menu-pair { display: flex; gap: 12px; padding: 3px 9px; }
+.clay-menu-list .clay-menu-pair [role="menuitem"] { flex: none; width: auto; justify-content: flex-start; gap: 9px; }
+.clay-menu-list kbd { flex: none; white-space: nowrap; }
+.clay-menu-row { display: flex; align-items: center; gap: 2px; }
+.clay-menu-list .clay-menu-row > [part~="item"] { flex: 1; width: auto; min-width: 0; }
+.clay-menu-list .clay-menu-row > [part~="dismiss"] { flex: none; width: 28px; justify-content: center; padding: 0; }
+.clay-menu-row > [part~="dismiss"] svg { display: block; width: 10px; height: 10px; fill: currentColor; }
+.clay-menu-upgrade { display: inline-flex; align-items: center; gap: 8px; }
+.clay-menu-upgrade::before { content: ""; width: 7px; height: 7px; border-radius: 50%; background: var(--bevel-brass); }
+.clay-menu-toggle .clay-menu-track { flex: none; }
+.clay-menu-version { box-sizing: border-box; margin: 0; padding: 7px 9px; }
+
+.clay-menu-note { z-index: 2; width: max-content; max-width: 264px; padding: 8px 12px; font-size: 13px; line-height: 1.45; }
+
+.clay-menu-stepper { display: flex; align-items: center; gap: 2px; padding-left: 9px; font: 400 13px/1.35 var(--bevel-font-sans); color: var(--bevel-ink); }
+.clay-menu-stepper-label { flex: 1; margin-right: 12px; white-space: nowrap; }
+.clay-menu-stepper-value { min-width: 5.5em; text-align: center; white-space: nowrap; font-variant-numeric: tabular-nums; }
+.clay-menu-list .clay-menu-stepper [role="menuitem"] { flex: none; display: inline-grid; place-items: center; box-sizing: border-box; width: 36px; min-height: 36px; padding: 0; }
+.clay-menu-stepper svg { display: block; width: 16px; height: 16px; fill: currentColor; }
+
+`;
+
+export const SHELL_BASE = SHELL_A + SHELL_B + SHELL_C;
+
+export const SHELL_FLOATING = `/* The dock: the roster (when a page opts in) and the capsule, fixed in one corner. */
+.clay-menu-dock { position: fixed; z-index: 2147482000; top: max(12px, env(safe-area-inset-top)); right: max(12px, env(safe-area-inset-right)); }
+.clay-menu-dock[data-corner$="left"] { right: auto; left: max(12px, env(safe-area-inset-left)); flex-direction: row-reverse; }
+.clay-menu-dock[data-corner^="bottom"] { top: auto; bottom: max(12px, env(safe-area-inset-bottom)); }
+.clay-menu-dock[data-corner$="left"] :is(.clay-menu-list, .clay-people, .clay-menu-note) { right: auto; left: 0; }
+.clay-menu-dock[data-corner^="bottom"] :is(.clay-menu-list, .clay-people, .clay-menu-note) { top: auto; bottom: calc(100% + 8px); }
+`;
+
+export const MENU_SKIN = `.clay-menu { height: 34px; padding: 0 4px 0 2px; border: 1px solid var(--bevel-line-3); background: var(--bevel-surface); box-shadow: var(--clay-shadow); }
+.clay-menu-goo { width: 28px; height: 28px; min-height: 0; border-radius: 0; border: 2px solid transparent; background: none; color: var(--bevel-ink); }
+.clay-menu-goo::before { content: ""; position: absolute; inset: -8px -8px -8px -4px; }
+.clay-menu-goo svg { width: 18px; height: auto; fill: currentColor; }
+.clay-menu-goo:hover svg { translate: 0 -1px; }
+.clay-menu-goo:active, .clay-menu-goo[aria-expanded="true"] { background: var(--bevel-face-in); border-color: var(--bevel-edge-in) var(--bevel-edge-in-hi) var(--bevel-edge-in-hi) var(--bevel-edge-in); }
+.clay-menu-goo:active svg, .clay-menu-goo[aria-expanded="true"] svg { translate: 1px 1px; }
+.clay-menu-list { min-width: 284px; padding: 6px; border: 1px solid var(--bevel-line-2); background: var(--bevel-surface); box-shadow: var(--clay-shadow); }
+.clay-menu-list [role^="menuitem"] { min-height: 32px; padding: 5px 9px; font: 400 13px/1.35 var(--bevel-font-sans); color: var(--bevel-ink); }
+.clay-menu-list [role^="menuitem"][aria-disabled="true"] { color: var(--bevel-faint); }
+.clay-menu-list [role^="menuitem"][aria-disabled="true"] kbd { opacity: .6; }
+.clay-menu-list .clay-menu-pair [role="menuitem"] { min-height: 30px; padding: 4px 6px 4px 9px; border: 1px solid var(--bevel-line); }
+.clay-menu-list kbd { font: 500 11px/1 var(--bevel-font-mono); padding: 3px 5px; border: 1px solid var(--bevel-line-2); background: var(--bevel-sunk); color: var(--bevel-muted); }
+.clay-menu-list [part~="quiet"] { font-size: 12px; color: var(--bevel-muted); }
+.clay-menu-sep { height: 1px; margin: 4px 2px; background: var(--bevel-line); }
+.clay-menu-version { font: 400 11.5px/1.4 var(--bevel-font-mono); color: var(--bevel-muted); }
+`;
+
+// Last, so no skin can shrink a touch target or bring motion back.
+export const MENU_TOUCH = `@media (pointer: coarse), (max-width: 680px) {
+  .clay-menu-list [role^="menuitem"] { min-height: 44px; font-size: 15px; }
+  .clay-menu-list .clay-menu-pair [role="menuitem"] { min-height: 44px; }
+  .clay-menu-list .clay-menu-stepper [role="menuitem"] { width: 44px; min-height: 44px; }
+  :is(.clay-menu-dock, .clay-seo) :is(input, textarea, select) { font-size: 16px; }
+  .clay-seo-input, .clay-people-input { min-height: 40px; }
+  .clay-menu-btn { min-height: 40px; }
+}
+@media (prefers-reduced-motion: reduce) {
+  .clay-menu-track, .clay-menu-thumb { transition: none; }
+}
+`;

package/src/plugins/menu/shell.js

@@ -0,0 +1,398 @@
+import CLAYGOO from "./claygoo.svg.js";
+import { mountEditorUI } from "../../ui/editor-ui.js";
+
+const SKIN_VERSION = "1";
+const EDGE_GAP = 8;
+const DISMISS_ICON = '<svg viewBox="0 0 10 10" aria-hidden="true" focusable="false"><path d="M1 0 5 4l4-4 1 1-4 4 4 4-1 1-4-4-4 4-1-1 4-4-4-4z"/></svg>';
+const ARROW_PREV = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" aria-hidden="true" focusable="false"><path d="M224,128a8,8,0,0,1-8,8H59.31l58.35,58.34a8,8,0,0,1-11.32,11.32l-72-72a8,8,0,0,1,0-11.32l72-72a8,8,0,0,1,11.32,11.32L59.31,120H216A8,8,0,0,1,224,128Z"/></svg>';
+const ARROW_NEXT = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" aria-hidden="true" focusable="false"><path d="M221.66,133.66l-72,72a8,8,0,0,1-11.32-11.32L196.69,136H40a8,8,0,0,1,0-16H196.69L138.34,61.66a8,8,0,0,1,11.32-11.32l72,72A8,8,0,0,1,221.66,133.66Z"/></svg>';
+export const TRACK = '<span class="clay-menu-track" aria-hidden="true"><span class="clay-menu-thumb"></span></span>';
+const NOTE_MS = 6000;
+
+// The first [clay-menu-slot] on the page holds the menu. With none, it floats in a corner.
+function findSlot() {
+  const slots = document.querySelectorAll("[clay-menu-slot]");
+  if (slots.length > 1) console.warn("[clay] This page has more than one clay-menu-slot. The menu uses the first.");
+  return slots[0] || null;
+}
+
+// A skin the page wrote, in <style clay-menu-skin="1" media="not all">. The media keeps it
+// off the page itself. An unknown version means the default skin.
+function pageSkin() {
+  const style = document.querySelector("style[clay-menu-skin]");
+  if (!style) return null;
+  if (style.getAttribute("clay-menu-skin") !== SKIN_VERSION) {
+    console.warn(`[clay] This runtime reads clay-menu-skin="${SKIN_VERSION}". The menu keeps its default look.`);
+    return null;
+  }
+  return style.textContent;
+}
+
+export function createShell({ capsuleStart = "", sections = [null] } = {}) {
+  const slotted = new Set(sections.flat().filter(Boolean));
+  const slot = findSlot();
+  const embedded = Boolean(slot);
+  const skin = embedded ? pageSkin() : null;
+
+  const root = document.createElement("div");
+  root.className = "clay-menu-dock";
+  root.setAttribute("clay", "editor-ui");
+  root.setAttribute("part", "dock");
+  if (embedded) root.dataset.embedded = "";
+  root.dataset.corner = "top-right";
+  root.innerHTML =
+    `<div class="clay-menu" part="capsule" clay="editor-ui">` +
+    capsuleStart +
+    `<button type="button" class="clay-menu-goo" part="button" aria-haspopup="menu" aria-expanded="false" aria-label="Clay menu">${CLAYGOO}</button>` +
+    `</div>` +
+    `<div class="clay-menu-list" part="list" role="menu" aria-label="Clay menu" hidden></div>` +
+    `<div class="clay-menu-note" part="note" role="status" hidden></div>`;
+
+  const goo = root.querySelector(".clay-menu-goo");
+  const list = root.querySelector(".clay-menu-list");
+  const noteEl = root.querySelector(".clay-menu-note");
+  const items = new Map();
+  const beforeOpen = [];
+
+  if (embedded) {
+    const icon = slot.querySelector("template[clay-menu-icon]");
+    if (icon) goo.replaceChildren(icon.content.cloneNode(true));
+    const name = slot.getAttribute("clay-menu-label");
+    if (name) {
+      goo.setAttribute("aria-label", name);
+      goo.title = name;
+      list.setAttribute("aria-label", name);
+    }
+  }
+
+  // Embedded, the list opens in the top layer, so a header's overflow cannot clip it.
+  const topLayer = embedded && typeof list.showPopover === "function";
+  if (topLayer) list.setAttribute("popover", "manual");
+
+  function placeList() {
+    const anchor = goo.getBoundingClientRect();
+    const { offsetWidth: width, offsetHeight: height } = list;
+    const left = Math.max(EDGE_GAP, Math.min(anchor.right - width, window.innerWidth - width - EDGE_GAP));
+    const below = anchor.bottom + EDGE_GAP;
+    const top = below + height > window.innerHeight - EDGE_GAP ? Math.max(EDGE_GAP, anchor.top - height - EDGE_GAP) : below;
+    list.style.left = `${Math.round(left)}px`;
+    list.style.top = `${Math.round(top)}px`;
+  }
+
+  // Focus inside the shadow root: document.activeElement only ever names the host.
+  const focusedEl = () => root.getRootNode().activeElement || null;
+  const isOpen = () => !list.hidden;
+
+  function setExpanded(open) {
+    list.hidden = !open;
+    goo.setAttribute("aria-expanded", open ? "true" : "false");
+    if (!topLayer) return;
+    if (open) {
+      list.showPopover();
+      placeList();
+    } else if (list.matches(":popover-open")) {
+      list.hidePopover();
+    }
+  }
+
+  const buttons = () => [...list.querySelectorAll('[role^="menuitem"]:not([aria-disabled="true"])')];
+
+  function focusItem(index) {
+    const all = buttons();
+    if (!all.length) return;
+    all[(index + all.length) % all.length].focus();
+  }
+
+  function close() {
+    if (!isOpen()) return;
+    setExpanded(false);
+  }
+
+  function open() {
+    if (isOpen()) return;
+    for (const fn of beforeOpen) fn();
+    render();
+    setExpanded(true);
+  }
+
+  function itemButton(item) {
+    const link = item.href && !item.disabled;
+    const button = document.createElement(link ? "a" : "button");
+    if (link) {
+      button.href = item.href;
+      button.target = "_blank";
+      button.rel = "noopener";
+    } else {
+      button.type = "button";
+    }
+    button.setAttribute("role", "menuitem");
+    button.setAttribute("part", item.quiet ? "item quiet" : "item");
+    button.dataset.menuId = item.id;
+    if (item.badge && item.id === "upgrade") {
+      const label = document.createElement("span");
+      label.className = "clay-menu-upgrade";
+      label.textContent = item.label;
+      button.append(label);
+    } else {
+      button.textContent = item.label;
+    }
+    if (item.keys) {
+      const kbd = document.createElement("kbd");
+      kbd.textContent = item.keys;
+      button.append(kbd);
+    }
+    if (item.toggle) {
+      button.setAttribute("role", "menuitemcheckbox");
+      button.setAttribute("aria-checked", item.checked ? "true" : "false");
+      button.classList.add("clay-menu-toggle");
+      button.insertAdjacentHTML("beforeend", TRACK);
+    }
+    if (item.disabled) button.setAttribute("aria-disabled", "true");
+    button.addEventListener("click", () => {
+      if (item.disabled) return;
+      if (!item.toggle && !item.keepOpen) close();
+      if (item.run) item.run({ anchor: goo });
+    });
+    return button;
+  }
+
+  function itemNode(item) {
+    if (item.text) {
+      const line = document.createElement("p");
+      line.className = "clay-menu-version";
+      line.setAttribute("part", "text");
+      line.dataset.menuId = item.id;
+      line.textContent = item.label;
+      return line;
+    }
+    if (item.pair) {
+      const pair = document.createElement("div");
+      pair.className = "clay-menu-pair";
+      pair.dataset.menuId = item.id;
+      for (const part of item.pair) pair.append(itemButton(part));
+      return pair;
+    }
+    if (item.stepper) return stepperRow(item);
+    if (item.dismiss) return dismissibleRow(item);
+    return itemButton(item);
+  }
+
+  function dismissibleRow(item) {
+    const row = document.createElement("div");
+    row.className = "clay-menu-row";
+    row.dataset.menuId = item.id;
+    const dismiss = document.createElement("button");
+    dismiss.type = "button";
+    dismiss.setAttribute("role", "menuitem");
+    dismiss.setAttribute("part", "dismiss");
+    dismiss.dataset.menuId = `${item.id}.dismiss`;
+    dismiss.setAttribute("aria-label", item.dismiss.label);
+    dismiss.title = item.dismiss.label;
+    dismiss.innerHTML = DISMISS_ICON;
+    dismiss.addEventListener("click", async () => {
+      dismiss.disabled = true;
+      let result;
+      try {
+        result = await item.dismiss.run?.();
+      } catch (error) {
+        console.warn("[clay] A menu item could not be removed.", error);
+        dismiss.disabled = false;
+        note("That didn't work. Try again.");
+        return;
+      }
+      if (result === false) {
+        dismiss.disabled = false;
+        return;
+      }
+      removeItem(item.id);
+    });
+    row.append(itemButton(item), dismiss);
+    return row;
+  }
+
+  function stepperRow(item) {
+    const { label, value, prevLabel, nextLabel } = item.stepper;
+    const row = document.createElement("div");
+    row.className = "clay-menu-stepper";
+    row.setAttribute("part", "stepper");
+    row.dataset.menuId = item.id;
+    const text = document.createElement("span");
+    text.className = "clay-menu-stepper-label";
+    text.textContent = label;
+    const shown = document.createElement("span");
+    shown.className = "clay-menu-stepper-value";
+    shown.setAttribute("aria-live", "polite");
+    shown.textContent = value;
+    const step = (suffix, icon, name) => {
+      const button = document.createElement("button");
+      button.type = "button";
+      button.setAttribute("role", "menuitem");
+      button.setAttribute("part", "step");
+      button.setAttribute("aria-label", name);
+      button.dataset.menuId = `${item.id}.${suffix}`;
+      button.innerHTML = icon;
+      button.addEventListener("click", () => items.get(item.id)?.stepper?.[suffix]?.());
+      return button;
+    };
+    row.append(text, step("prev", ARROW_PREV, prevLabel), shown, step("next", ARROW_NEXT, nextLabel));
+    return row;
+  }
+
+  function grouped() {
+    const inSection = (name) => [...items.values()].filter((item) => item.section === name);
+    const extra = [...items.keys()].filter((id) => !slotted.has(id) && !items.get(id).section);
+    const fixed = sections.map((ids) => (ids || extra).map((id) => items.get(id)).filter(Boolean));
+    return [inSection("start"), ...fixed, inSection("end")].filter((group) => group.length);
+  }
+
+  function render() {
+    const now = focusedEl();
+    const focused = now && list.contains(now) ? now.dataset.menuId : null;
+    list.textContent = "";
+    grouped().forEach((group, index) => {
+      if (index) {
+        const sep = document.createElement("div");
+        sep.className = "clay-menu-sep";
+        sep.setAttribute("role", "separator");
+        sep.setAttribute("part", "separator");
+        list.append(sep);
+      }
+      for (const item of group) list.append(itemNode(item));
+    });
+    const dot = goo.querySelector(".clay-menu-dot");
+    const wanted = [...items.values()].some((item) => item.badge);
+    if (wanted && !dot) {
+      const mark = document.createElement("span");
+      mark.className = "clay-menu-dot";
+      mark.setAttribute("aria-hidden", "true");
+      goo.append(mark);
+    } else if (!wanted && dot) {
+      dot.remove();
+    }
+    if (focused) {
+      const again = buttons().find((button) => button.dataset.menuId === focused);
+      if (again) again.focus();
+      else focusItem(0);
+    }
+  }
+
+  const clean = ({ id, label, run, badge, keys, disabled, href, keepOpen }) => ({
+    id,
+    href: typeof href === "string" ? href : "",
+    label: String(label ?? ""),
+    run: typeof run === "function" ? run : null,
+    badge: Boolean(badge),
+    keys: keys ? String(keys) : "",
+    disabled: Boolean(disabled),
+    keepOpen: Boolean(keepOpen),
+  });
+
+  function addItem({ id, label, run, badge, keys, disabled, text, pair, href, section, quiet, dismiss, toggle, checked, keepOpen, stepper } = {}) {
+    if (!id) return null;
+    const item = clean({ id, label, run, badge, keys, disabled, href, keepOpen });
+    if (section === "start" || section === "end") item.section = section;
+    if (quiet) item.quiet = true;
+    if (stepper) {
+      item.stepper = {
+        label: String(stepper.label ?? ""),
+        value: String(stepper.value ?? ""),
+        prev: typeof stepper.prev === "function" ? stepper.prev : null,
+        next: typeof stepper.next === "function" ? stepper.next : null,
+        prevLabel: String(stepper.prevLabel || "Previous"),
+        nextLabel: String(stepper.nextLabel || "Next"),
+      };
+      const shown = [...list.querySelectorAll(".clay-menu-stepper")].find((row) => row.dataset.menuId === id)?.querySelector(".clay-menu-stepper-value");
+      // Only the value changed: update it in place, so focus stays on the arrow. The
+      // buttons read their callbacks from the stored item when pressed.
+      const before = items.get(id);
+      const same = before?.stepper && ["label", "prevLabel", "nextLabel"].every((key) => before.stepper[key] === item.stepper[key]) && before.section === item.section && before.quiet === item.quiet;
+      if (same && shown) {
+        items.set(id, item);
+        shown.textContent = item.stepper.value;
+        return id;
+      }
+    }
+    if (text) item.text = true;
+    if (Array.isArray(pair)) item.pair = pair.map(clean);
+    if (toggle) {
+      item.toggle = true;
+      item.checked = Boolean(checked);
+    }
+    if (dismiss) item.dismiss = { label: String(dismiss.label || "Dismiss"), run: typeof dismiss.run === "function" ? dismiss.run : null };
+    items.set(id, item);
+    render();
+    return id;
+  }
+
+  function removeItem(id) {
+    if (items.delete(id)) render();
+  }
+
+  function note(text) {
+    if (!text) return;
+    noteEl.textContent = text;
+    noteEl.hidden = false;
+    clearTimeout(noteTimer);
+    noteTimer = setTimeout(() => {
+      noteEl.hidden = true;
+      noteEl.textContent = "";
+    }, NOTE_MS);
+  }
+
+  let noteTimer = 0;
+
+  goo.addEventListener("click", () => {
+    if (isOpen()) close();
+    else open();
+  });
+
+  document.addEventListener("click", (event) => {
+    if (isOpen() && !event.composedPath().includes(root)) close();
+  });
+
+  root.addEventListener("keydown", (event) => {
+    if (event.key === "Escape") {
+      if (!isOpen()) return;
+      event.preventDefault();
+      close();
+      goo.focus();
+      return;
+    }
+    if (event.target === goo && (event.key === "Enter" || event.key === " ")) {
+      event.preventDefault();
+      if (isOpen()) close();
+      else {
+        open();
+        focusItem(0);
+      }
+      return;
+    }
+    if (!isOpen()) return;
+    if (event.key === "Enter" && list.contains(event.target)) {
+      event.preventDefault();
+      event.target.click();
+      return;
+    }
+    const all = buttons();
+    if (!all.length) return;
+    const at = all.indexOf(focusedEl());
+    if (event.key === "ArrowDown") {
+      event.preventDefault();
+      focusItem(at < 0 ? 0 : at + 1);
+    } else if (event.key === "ArrowUp") {
+      event.preventDefault();
+      focusItem(at < 0 ? all.length - 1 : at - 1);
+    }
+  });
+
+  function mount(css) {
+    const ui = mountEditorUI({ name: "menu", content: root, css, parent: slot || document.body, attributes: { "clay-mode-toggle": "" } });
+    if (embedded) {
+      window.addEventListener("resize", close);
+      window.addEventListener("scroll", () => { if (topLayer && isOpen()) placeList(); }, { capture: true, passive: true });
+    }
+    return ui;
+  }
+
+  return { root, goo, list, slot, embedded, skin, items, addItem, removeItem, render, open, close, isOpen, note, beforeOpen, focusedEl, mount };
+}