@miragon/modeler-shell 0.1.0 → 0.2.1

package/src/dom/feedback/feedback.css

@@ -0,0 +1,435 @@
+/*
+ * Feedback of @miragon/modeler-shell (owned by src/dom/feedback): the toast stack and the problems
+ * popover (guide §5.10, §8, §9). Colours only from var(--cd-ui-*), sizes from var(--cd-shell-*).
+ * Toasts render in the web and embedded hosts, so their rules also reset what a foreign page's
+ * element rules would set (font, colour, letter spacing, text transform), like shell-dom.css.
+ * The toast action is a .cd-shell-button (buttons.css), which resets itself and is left out here.
+ * Private helper properties are named --modeler-shell-*, never --cd-*.
+ */
+
+/* ---- Foreign-page reset --------------------------------------------------------------------- */
+
+:where(.cd-shell)
+  :is(
+    .cd-shell-toasts,
+    .cd-shell-toast,
+    .cd-shell-toast-text,
+    .cd-shell-toast-close,
+    .cd-shell-problems-popover,
+    .cd-shell-problems-popover-title,
+    .cd-shell-problems-list,
+    .cd-shell-problem,
+    .cd-shell-problem-message,
+    .cd-shell-problem-location
+  ) {
+  color: inherit;
+  font: inherit;
+  letter-spacing: normal;
+  word-spacing: normal;
+  text-transform: none;
+  text-indent: 0;
+  text-shadow: none;
+}
+
+/* ---- Toast stack (guide §8, §9) ------------------------------------------------------------- */
+
+/*
+ * Centred column at the bottom; the script sets `bottom` (toastStackBottom). In the web host it is
+ * a manual popover in the top layer, so the UA's popover box (fixed, centred, bordered, padded,
+ * Canvas colours) is reset; in the embedded host it is absolute in the root at layer 60.
+ */
+.cd-shell-toasts {
+  position: absolute;
+  top: auto;
+  right: 0;
+  bottom: var(--cd-shell-rand);
+  left: 0;
+  z-index: var(--cd-shell-ebene-toast);
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: var(--cd-shell-luecke);
+  width: min(480px, 100cqw - 2 * var(--cd-shell-rand));
+  height: auto;
+  min-height: 0;
+  max-height: none;
+  margin: 0 auto;
+  padding: 0;
+  overflow: visible;
+  color: var(--cd-ui-text);
+  background: transparent;
+  border: 0;
+  pointer-events: none;
+}
+
+/* Always in the DOM, no box while empty (data-chrome="toasts" measures nothing then). */
+.cd-shell-toasts:empty {
+  display: none;
+}
+
+/* The author display above would otherwise show a closed popover; engines without it drop the rule. */
+.cd-shell-toasts[popover]:not(:popover-open) {
+  display: none;
+}
+
+.cd-shell-toast {
+  --modeler-shell-toast-status: var(--cd-ui-info);
+  position: relative;
+  box-sizing: border-box;
+  display: flex;
+  flex: none;
+  align-items: center;
+  gap: var(--cd-shell-luecke);
+  max-width: 100%;
+  min-height: var(--cd-shell-zeile);
+  margin: 0;
+  padding: 4px 4px 4px 16px;
+  overflow: hidden;
+  color: var(--cd-ui-text);
+  font-size: 13px;
+  font-weight: 400;
+  line-height: 1.5;
+  text-align: left;
+  background: var(--cd-ui-flaeche-hoch);
+  border: 1px solid var(--cd-ui-linie);
+  border-radius: var(--cd-radius-md);
+  box-shadow: var(--cd-shadow-3);
+  pointer-events: auto;
+  user-select: none;
+  -webkit-user-select: none;
+  animation: cd-shell-toast-in var(--cd-motion-base) var(--cd-ease-out);
+}
+
+.cd-shell-toast[data-status="success"] {
+  --modeler-shell-toast-status: var(--cd-ui-success);
+}
+
+.cd-shell-toast[data-status="warning"] {
+  --modeler-shell-toast-status: var(--cd-ui-warning);
+}
+
+.cd-shell-toast[data-status="danger"] {
+  --modeler-shell-toast-status: var(--cd-ui-danger);
+}
+
+/* Its own element, clipped by the card: a border-left would follow the radius into a crescent. */
+.cd-shell-toast::before {
+  content: "";
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  left: 0;
+  width: 4px;
+  background: var(--modeler-shell-toast-status);
+}
+
+.cd-shell-toast-dot {
+  flex: none;
+  width: 8px;
+  height: 8px;
+  background: var(--modeler-shell-toast-status);
+  border-radius: var(--cd-radius-pill);
+}
+
+.cd-shell-toast-text {
+  flex: 1 1 auto;
+  min-width: 0;
+  margin: 0;
+  padding: 6px 0;
+  color: var(--cd-ui-text);
+  font-size: 13px;
+  line-height: 1.5;
+  overflow-wrap: anywhere;
+}
+
+/* A 32px ghost button (buttons.css), before Close. */
+.cd-shell-toast .cd-shell-toast-action {
+  height: var(--cd-shell-ziel);
+}
+
+.cd-shell-toast-close {
+  box-sizing: border-box;
+  display: inline-grid;
+  flex: none;
+  place-items: center;
+  width: var(--cd-shell-ziel);
+  height: var(--cd-shell-ziel);
+  margin: 0;
+  padding: 0;
+  color: var(--cd-ui-text);
+  background: transparent;
+  border: 0;
+  border-radius: var(--cd-radius-sm);
+  cursor: pointer;
+  transition:
+    background-color var(--cd-motion-fast) var(--cd-ease),
+    color var(--cd-motion-fast) var(--cd-ease);
+}
+
+.cd-shell-toast-close:hover {
+  color: var(--cd-ui-interaktion);
+  background: var(--cd-ui-hover);
+}
+
+.cd-shell-toast-close svg {
+  display: block;
+  flex: none;
+}
+
+.cd-shell-toast[data-leaving] {
+  pointer-events: none;
+  animation: cd-shell-toast-out var(--cd-motion-base) var(--cd-ease) forwards;
+}
+
+@keyframes cd-shell-toast-in {
+  from {
+    opacity: 0;
+    transform: translateY(8px);
+  }
+}
+
+@keyframes cd-shell-toast-out {
+  to {
+    opacity: 0;
+    transform: translateY(8px);
+  }
+}
+
+/* The toasts' live regions: in the accessibility tree at all times, never on screen. */
+.cd-shell-live {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+  pointer-events: none;
+}
+
+/* ---- Problems popover (guide §5.10) --------------------------------------------------------- */
+
+/* Left-aligned with the pill, its bottom 8px above the pill's top: 12 + 40 + 8, web 12 + 20 + 8 + 40 + 8. */
+.cd-shell-problems-popover {
+  --modeler-shell-problems-bottom: calc(
+    var(--cd-shell-rand) + var(--cd-shell-zeile) + var(--cd-shell-luecke)
+  );
+  position: absolute;
+  left: var(--cd-shell-rand);
+  bottom: var(--modeler-shell-problems-bottom);
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  width: min(320px, 100cqw - 2 * var(--cd-shell-rand));
+  max-height: min(320px, 100cqh - var(--modeler-shell-problems-bottom) - var(--cd-shell-rand));
+  margin: 0;
+  padding: 6px;
+  color: var(--cd-ui-text);
+  font-size: 13px;
+  font-weight: 400;
+  line-height: 1.5;
+  background: var(--cd-ui-flaeche-hoch);
+  border: 1px solid var(--cd-ui-linie);
+  border-radius: var(--cd-radius-md);
+  box-shadow: var(--cd-shadow-3);
+  pointer-events: auto;
+  user-select: none;
+  -webkit-user-select: none;
+  animation: cd-shell-problems-in var(--cd-motion-fast) var(--cd-ease-out);
+}
+
+.cd-shell[data-cd-shell-host="web"] .cd-shell-problems-popover {
+  --modeler-shell-problems-bottom: calc(
+    var(--cd-shell-rand) + var(--modeler-shell-legal-height, 20px) + var(--cd-shell-luecke) +
+      var(--cd-shell-zeile) + var(--cd-shell-luecke)
+  );
+}
+
+.cd-shell-problems-popover[hidden] {
+  display: none;
+}
+
+/* Focus lands on the dialog itself only when it has no row to take it; inside, as in a scroller. */
+.cd-shell-problems-popover:focus {
+  outline: none;
+}
+
+.cd-shell-problems-popover:focus-visible {
+  outline: 2px solid var(--cd-ui-fokus);
+  outline-offset: -2px;
+}
+
+.cd-shell-problems-popover-title {
+  flex: none;
+  margin: 0;
+  padding: 8px 12px 4px;
+  color: var(--cd-ui-text);
+  font-size: 13px;
+  font-weight: 600;
+  line-height: 1.5;
+}
+
+.cd-shell-problems-list {
+  flex: 1 1 auto;
+  min-height: 0;
+  margin: 0;
+  padding: 0;
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  list-style: none;
+}
+
+.cd-shell-problems-list > li {
+  display: block;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.cd-shell-problem {
+  box-sizing: border-box;
+  display: grid;
+  grid-template-columns: 16px minmax(0, 1fr);
+  column-gap: 12px;
+  align-items: start;
+  width: 100%;
+  min-height: var(--cd-shell-eintrag);
+  margin: 0;
+  padding: 8px 12px;
+  color: var(--cd-ui-text);
+  font-size: 13px;
+  font-weight: 400;
+  line-height: 1.5;
+  text-align: left;
+  background: transparent;
+  border: 0;
+  border-radius: var(--cd-radius-sm);
+}
+
+button.cd-shell-problem {
+  cursor: pointer;
+  transition: background-color var(--cd-motion-fast) var(--cd-ease);
+}
+
+button.cd-shell-problem:hover,
+button.cd-shell-problem:focus-visible {
+  background: var(--cd-ui-hover);
+}
+
+/* The pill's icon, centred on the message's first line (19.5px). */
+.cd-shell-problem-icon {
+  display: grid;
+  grid-row: 1 / span 2;
+  place-items: center;
+  width: 16px;
+  height: 16px;
+  margin-top: 2px;
+}
+
+.cd-shell-problem-icon svg {
+  display: block;
+  flex: none;
+}
+
+.cd-shell-problem[data-severity="error"] .cd-shell-problem-icon {
+  color: var(--cd-ui-danger);
+}
+
+.cd-shell-problem[data-severity="warning"] .cd-shell-problem-icon {
+  color: var(--cd-ui-warning);
+}
+
+.cd-shell-problem-message {
+  grid-column: 2;
+  color: var(--cd-ui-text);
+  overflow-wrap: anywhere;
+}
+
+.cd-shell-problem-location {
+  grid-column: 2;
+  color: var(--cd-ui-text-leise);
+  overflow-wrap: anywhere;
+}
+
+@keyframes cd-shell-problems-in {
+  from {
+    opacity: 0;
+    transform: translateY(4px);
+  }
+}
+
+/* ---- Focus (guide §8): inside the dense toast and the scrolling list ------------------------ */
+
+.cd-shell :is(.cd-shell-toast-close, .cd-shell-problem):focus {
+  outline: none;
+}
+
+.cd-shell :is(.cd-shell-toast-close, .cd-shell-toast-action, .cd-shell-problem):focus-visible {
+  outline: 2px solid var(--cd-ui-fokus);
+  outline-offset: -2px;
+}
+
+/* ---- High contrast (guide §5.3): no shadows, 3px focus -------------------------------------- */
+
+.cd-shell:is([data-cd-kontrast="hoch"], [data-cd-kontrast="hoch"] *)
+  :is(.cd-shell-toast, .cd-shell-problems-popover) {
+  box-shadow: none;
+}
+
+.cd-shell:is([data-cd-kontrast="hoch"], [data-cd-kontrast="hoch"] *)
+  :is(
+    .cd-shell-toast-close,
+    .cd-shell-toast-action,
+    .cd-shell-problem,
+    .cd-shell-problems-popover
+  ):focus-visible {
+  outline-width: 3px;
+  outline-offset: -3px;
+}
+
+/* ---- Forced colours (guide §5.14): nothing disappears --------------------------------------- */
+
+@media (forced-colors: active) {
+  .cd-shell :is(.cd-shell-toast, .cd-shell-problems-popover) {
+    border-color: CanvasText;
+  }
+
+  /* Bar and dot keep their shape; the text carries the status. */
+  .cd-shell .cd-shell-toast::before,
+  .cd-shell .cd-shell-toast-dot {
+    forced-color-adjust: none;
+    background: CanvasText;
+  }
+
+  .cd-shell
+    :is(
+      .cd-shell-toast-close,
+      .cd-shell-toast-action,
+      .cd-shell-problem,
+      .cd-shell-problems-popover
+    ):focus-visible {
+    outline-color: Highlight;
+  }
+
+  /* The hover fill is forced away; a thin ring shows which row the pointer is on. */
+  .cd-shell button.cd-shell-problem:hover:not(:focus-visible) {
+    outline: 1px solid Highlight;
+    outline-offset: -1px;
+  }
+}
+
+/* ---- Reduced motion (guide §7): no slide, no pop-in ----------------------------------------- */
+
+@media (prefers-reduced-motion: reduce) {
+  .cd-shell :is(.cd-shell-toast, .cd-shell-problems-popover) {
+    animation: none;
+  }
+}
+
+/* The host asks for it although the OS does not: VS Code's workbench.reduceMotion. */
+html.cd-shell-reduce-motion .cd-shell :is(.cd-shell-toast, .cd-shell-problems-popover) {
+  animation: none;
+}

package/src/dom/feedback/problems-popover.ts

@@ -0,0 +1,287 @@
+import { matchChromeKey, type ProblemItem, type ShellMessages } from "../../core/index.js";
+import { createElement } from "../element.js";
+import { iconElement } from "../icons.js";
+
+export interface ProblemsPopoverContext {
+  ownerDocument: Document;
+  /** The shell root: outside clicks and the window's blur close the popover, as the menu does. */
+  root: HTMLElement;
+  /** The shell's layer (40): the popover lives there, like the dropdown. */
+  layer: HTMLElement;
+  /** The pill, its trigger: gets `aria-haspopup="dialog"`, `aria-expanded` and `aria-controls`. */
+  pill: HTMLButtonElement;
+  /** `cd-shell-problems-N` on the popover. */
+  id: string;
+  /** `cd-shell-problems-title-N` on its title. */
+  titleId: string;
+  messages: ShellMessages;
+  onSelectItem?: ((item: ProblemItem) => void) | undefined;
+}
+
+export interface ProblemsPopover {
+  /** The `<div data-chrome="problems-popover" role="dialog">`. */
+  readonly element: HTMLElement;
+  isOpen(): boolean;
+  /** Open (focus on the first row, else the popover) or close (focus back to the pill). */
+  toggle(): void;
+  open(): void;
+  close(options?: { restoreFocus?: boolean | undefined }): void;
+  /** The rows; while open the list re-renders and keeps the focused row. */
+  setItems(items: readonly ProblemItem[]): void;
+  destroy(): void;
+}
+
+interface Row {
+  /** The same problem across `setItems`, so a re-render keeps the focus on it. */
+  key: string;
+  /** A `<button>` for a row with an element, else a `<div tabindex="-1">`. */
+  element: HTMLElement;
+}
+
+const PILL_ATTRIBUTES = ["aria-haspopup", "aria-expanded", "aria-controls"] as const;
+
+function isPrintable(event: KeyboardEvent): boolean {
+  return event.key.length === 1 && /\S/.test(event.key) && !event.ctrlKey && !event.metaKey && !event.altKey;
+}
+
+/**
+ * The web app's problems list (guide §5.10): a popover above the pill, left-aligned with it
+ * (`left: 12px`, its bottom 8px above the pill's top), `role="dialog"` without `aria-modal`,
+ * `aria-labelledby` its title `messages.problemsTitle` (13px/600); opaque `--cd-ui-flaeche-hoch`,
+ * 1px `--cd-ui-linie`, radius `md`, `shadow-3`, `min(320px, 100cqw − 24px)` wide, at most 320px
+ * high with a scrolling list; pop-in 150ms from `translateY(4px)`. A row is at least 36px: the 16px
+ * icon of the pill (`circle-x` in `--cd-ui-danger`, `triangle-alert` in `--cd-ui-warning`), the
+ * message 13px `--cd-ui-text`, below it the location 13px `--cd-ui-text-leise`. Rows with an
+ * `elementId` are buttons: a click closes the popover, returns the focus to the canvas and then
+ * calls `onSelectItem(item)`; rows without one are text that still takes the focus (`tabindex="-1"`),
+ * so the keyboard reads every row. ↑/↓/Home/End move between all rows and scroll the focused one
+ * into the list; Enter and Space act only on a row button. Escape (the popover's own handler) and
+ * Tab out close it with the focus back on the pill (Tab then moves on from the pill, Shift+Tab stays
+ * on it); an outside `pointerdown` (capture) and the window's blur close it without moving the
+ * focus. The zoom keys keep working (not modal).
+ */
+export function createProblemsPopover(context: ProblemsPopoverContext): ProblemsPopover {
+  const { ownerDocument, root, layer, pill, id, titleId, messages } = context;
+  const view = ownerDocument.defaultView;
+
+  const list = createElement(ownerDocument, "ul", { class: "cd-shell-problems-list", role: "list" });
+  const element = createElement(
+    ownerDocument,
+    "div",
+    {
+      class: "cd-shell-problems-popover",
+      "data-chrome": "problems-popover",
+      role: "dialog",
+      id,
+      "aria-labelledby": titleId,
+      tabindex: "-1",
+    },
+    createElement(
+      ownerDocument,
+      "h2",
+      { class: "cd-shell-problems-popover-title", id: titleId },
+      messages.problemsTitle,
+    ),
+    list,
+  );
+  element.hidden = true;
+  layer.append(element);
+
+  pill.setAttribute("aria-haspopup", "dialog");
+  pill.setAttribute("aria-expanded", "false");
+  pill.setAttribute("aria-controls", id);
+
+  let items: readonly ProblemItem[] = [];
+  let rows: Row[] = [];
+  let destroyed = false;
+
+  const isOpen = (): boolean => !element.hidden;
+
+  function keyOf(item: ProblemItem): string {
+    return `${item.elementId ?? ""}\u0000${item.severity}\u0000${item.message}`;
+  }
+
+  function rowElement(item: ProblemItem): HTMLElement {
+    const severity = item.severity === "error" ? "error" : "warning";
+    const parts = [
+      // The shape and colour of the icon carry the severity on screen, its name for screen readers.
+      createElement(
+        ownerDocument,
+        "span",
+        { class: "cd-shell-problem-icon", role: "img", "aria-label": messages.problemSeverity(severity) },
+        iconElement(severity === "error" ? "circle-x" : "triangle-alert"),
+      ),
+      createElement(ownerDocument, "span", { class: "cd-shell-problem-message" }, item.message),
+      item.location
+        ? createElement(ownerDocument, "span", { class: "cd-shell-problem-location" }, item.location)
+        : undefined,
+    ];
+    const attributes = { class: "cd-shell-problem", "data-severity": severity };
+    if (!item.elementId) {
+      const text = createElement(ownerDocument, "div", { ...attributes, tabindex: "-1" }, ...parts);
+      rows.push({ key: keyOf(item), element: text });
+      return text;
+    }
+    const button = createElement(ownerDocument, "button", { type: "button", ...attributes }, ...parts);
+    button.addEventListener("click", () => select(item));
+    rows.push({ key: keyOf(item), element: button });
+    return button;
+  }
+
+  function focusedRowIndex(): number {
+    return rows.findIndex((row) => row.element === ownerDocument.activeElement);
+  }
+
+  function render(): void {
+    const focusedIndex = focusedRowIndex();
+    const focusedKey = rows[focusedIndex]?.key;
+    rows = [];
+    list.replaceChildren(...items.map((item) => createElement(ownerDocument, "li", {}, rowElement(item))));
+    if (focusedKey === undefined || !isOpen()) return;
+    const kept = rows.find((row) => row.key === focusedKey) ?? rows[Math.min(focusedIndex, rows.length - 1)];
+    if (kept) focusRowElement(kept.element);
+    else element.focus({ preventScroll: true });
+  }
+
+  // Scrolls only the list: `focus()` and `scrollIntoView()` would also scroll the shell root.
+  function revealInList(row: HTMLElement): void {
+    const rowBox = row.getBoundingClientRect();
+    const listBox = list.getBoundingClientRect();
+    if (rowBox.top < listBox.top) list.scrollTop -= listBox.top - rowBox.top;
+    else if (rowBox.bottom > listBox.bottom) list.scrollTop += rowBox.bottom - listBox.bottom;
+  }
+
+  function focusRowElement(row: HTMLElement): void {
+    row.focus({ preventScroll: true });
+    revealInList(row);
+  }
+
+  function focusCanvas(): void {
+    const canvas = root.querySelector<HTMLElement | SVGElement>(".cd-shell-canvas svg[tabindex]");
+    canvas?.focus({ preventScroll: true });
+    if ((!canvas || ownerDocument.activeElement !== canvas) && !pill.hidden)
+      pill.focus({ preventScroll: true });
+  }
+
+  function select(item: ProblemItem): void {
+    close();
+    focusCanvas();
+    context.onSelectItem?.(item);
+  }
+
+  function focusRow(index: number): void {
+    if (rows.length === 0) return;
+    const row = rows[(index + rows.length) % rows.length];
+    if (row) focusRowElement(row.element);
+  }
+
+  const onOutsidePointerDown = (event: PointerEvent): void => {
+    const target = event.target as Node | null;
+    if (target && (element.contains(target) || pill.contains(target))) return;
+    close();
+  };
+
+  // The focus left the document (another window, an iframe of the host page): from the user's
+  // view a click outside, so the popover closes without moving the focus.
+  const onWindowBlur = (): void => close();
+
+  function open(): void {
+    if (destroyed || isOpen()) return;
+    element.hidden = false;
+    pill.setAttribute("aria-expanded", "true");
+    // Capture phase: diagram-js stops pointer events on palette, context pad and canvas.
+    ownerDocument.addEventListener("pointerdown", onOutsidePointerDown, true);
+    view?.addEventListener("blur", onWindowBlur);
+    list.scrollTop = 0;
+    const first = rows[0];
+    if (first) focusRowElement(first.element);
+    else element.focus({ preventScroll: true });
+  }
+
+  function close(options: { restoreFocus?: boolean | undefined } = {}): void {
+    if (!isOpen()) return;
+    element.hidden = true;
+    pill.setAttribute("aria-expanded", "false");
+    ownerDocument.removeEventListener("pointerdown", onOutsidePointerDown, true);
+    view?.removeEventListener("blur", onWindowBlur);
+    if (options.restoreFocus && !pill.hidden) pill.focus({ preventScroll: true });
+  }
+
+  // Keys typed in the list stop here, like the menu's: a modeler's keyboard on document (Event
+  // Storming deletes the selection on Delete) must never act on them.
+  function consume(event: KeyboardEvent): void {
+    event.preventDefault();
+    event.stopPropagation();
+  }
+
+  element.addEventListener("keydown", (event) => {
+    // Zoom and fit keys still act with the popover open; the shell's key listener runs them.
+    if (matchChromeKey(event)) return;
+    const index = focusedRowIndex();
+    switch (event.key) {
+      case "Escape":
+        consume(event);
+        close({ restoreFocus: true });
+        return;
+      case "Tab": {
+        // Without a row the popover itself holds the focus and is first and last at once.
+        const first = index <= 0;
+        const last = rows.length === 0 || index === rows.length - 1;
+        if (event.shiftKey && first) {
+          consume(event);
+          close({ restoreFocus: true });
+        } else if (!event.shiftKey && last) {
+          // The browser's Tab runs after this handler from the pill, so it moves on to what follows it.
+          event.stopPropagation();
+          close({ restoreFocus: true });
+        }
+        return;
+      }
+      case "ArrowDown":
+        focusRow(index + 1);
+        break;
+      case "ArrowUp":
+        focusRow(index < 0 ? rows.length - 1 : index - 1);
+        break;
+      case "Home":
+        focusRow(0);
+        break;
+      case "End":
+        focusRow(rows.length - 1);
+        break;
+      case "Enter":
+      case " ":
+      case "Delete":
+      case "Backspace":
+        // A row button's native click handles Enter and Space; nothing else may act on these keys.
+        event.stopPropagation();
+        return;
+      default:
+        if (isPrintable(event)) event.stopPropagation();
+        return;
+    }
+    consume(event);
+  });
+
+  return {
+    element,
+    isOpen,
+    toggle() {
+      if (isOpen()) close({ restoreFocus: true });
+      else open();
+    },
+    open,
+    close,
+    setItems(next) {
+      items = next;
+      if (!destroyed) render();
+    },
+    destroy() {
+      if (destroyed) return;
+      close();
+      destroyed = true;
+      for (const name of PILL_ATTRIBUTES) pill.removeAttribute(name);
+      element.remove();
+    },
+  };
+}