@raylang/elements 0.0.0-stage → 0.3.0

package/core/host.js

@@ -0,0 +1,200 @@
+// The native host: what the program around the page can do that a browser
+// cannot (system file dialogs, native confirmations). Components ask for it
+// and keep their web behavior when there is none, so they stay agnostic of
+// the host: they never import a bridge, a bridge installs a host here.
+// core/raylang.js installs the one of std/ui windows.
+//
+// A host is an object with `name`, `can(op)` and the operations it offers:
+//
+//   pickFiles({ title, multiple, directory, filters: [{ name, extensions }] })
+//     -> Promise<HostFile[]>   ([] when the user cancels)
+//   pickPath({ mode, title, directory, suggested, filters })
+//     -> Promise<string|null>  (mode: "open", "folder" or "save"; null = cancelled)
+//   confirm({ title, message, confirmLabel, cancelLabel, style })
+//     -> Promise<boolean>      (style: "", "info", "warning" or "error")
+//   menuItems()
+//     -> Promise<[{ menu, tag, title, shortcut, enabled, checked }]>  (the app's menu bar)
+//   runMenu(tag)
+//     -> Promise<true>         (the program gets the item as if chosen in the menu bar)
+//   popupMenu([{ title, enabled, checked, separator }])
+//     -> Promise<number|null>  (a native context menu at the pointer: the index
+//                               chosen, null when dismissed or replaced)
+//   setEdited(edited)          (the window's "unsaved changes" mark)
+//     -> Promise<true>
+//   titlebar                   ({ height, inset } in px when the page runs under a
+//                               transparent title bar, else null: reserve `height`
+//                               at the top, `inset` at the start for the window
+//                               buttons; also --ray-titlebar-height and
+//                               --ray-titlebar-inset on <html>)
+
+let current = null;
+const listeners = new Set();
+
+/** Installs the host (null removes it) and tells the listeners. */
+export function setHost(host) {
+  current = host ?? null;
+  for (const cb of [...listeners]) cb(current);
+}
+
+/** The installed host, or null. */
+export function getHost() {
+  return current;
+}
+
+/** Whether the installed host offers `op` ("pick_files", "confirm"…). */
+export function hostCan(op) {
+  return Boolean(current && typeof current.can === "function" && current.can(op));
+}
+
+/** Calls `cb(host)` whenever the host changes; returns the unsubscribe function. */
+export function onHostChange(cb) {
+  listeners.add(cb);
+  return () => listeners.delete(cb);
+}
+
+/** The title bar the page runs under ({ height, inset } px), or null. */
+export function titlebar() {
+  const t = current?.titlebar;
+  return t && t.height > 0 ? t : null;
+}
+
+// Interactive elements inside a drag handle stay clickable.
+const INTERACTIVE = "button, a[href], input, select, textarea, label, summary, [contenteditable], [role=button], [role=tab], [role=link], [role=menuitem], [tabindex]:not([tabindex='-1']), [data-ray-no-drag]";
+
+/**
+ * Makes `el` drag the window when the page runs under a host's title bar
+ * (titlebar() is not null): it gets data-ray-drag, the attribute the std/ui
+ * shell reads. The shell looks at the event's target, which a shadow root
+ * retargets to its host, so for a pointer down on anything interactive
+ * inside `el` (a button in its shadow root too) the attribute steps aside
+ * until the pointer is up. Returns the function that undoes it.
+ */
+export function dragRegion(el) {
+  const guard = (e) => {
+    if (!el.hasAttribute("data-ray-drag")) return;
+    const path = e.composedPath();
+    const end = path.indexOf(el);
+    const hit = path.slice(0, end < 0 ? 0 : end).some((n) => n instanceof Element && n.matches(INTERACTIVE));
+    if (!hit) return;
+    el.removeAttribute("data-ray-drag");
+    const back = () => {
+      removeEventListener("pointerup", back, true);
+      removeEventListener("pointercancel", back, true);
+      if (titlebar()) el.setAttribute("data-ray-drag", "");
+    };
+    addEventListener("pointerup", back, true);
+    addEventListener("pointercancel", back, true);
+  };
+  const sync = () => el.toggleAttribute("data-ray-drag", Boolean(titlebar()));
+  el.addEventListener("pointerdown", guard, true);
+  const stop = onHostChange(sync);
+  sync();
+  return () => {
+    stop();
+    el.removeEventListener("pointerdown", guard, true);
+    el.removeAttribute("data-ray-drag");
+  };
+}
+
+const formKey = (data) => JSON.stringify([...data].map(([k, v]) => [k, typeof v === "string" ? v : `${v.name}:${v.size}:${v.lastModified}`]));
+
+/**
+ * Follows whether `form` has unsaved changes: its FormData differs from the
+ * one it had when tracking started (or since clean()). With a host that
+ * offers "set_edited", the window shows it (the macOS close button's dot).
+ * `onChange(dirty)` is called when it flips. Submit and reset make it clean.
+ */
+export function trackEdits(form, { onChange } = {}) {
+  let saved = formKey(new FormData(form));
+  let dirty = false;
+  const set = (next) => {
+    if (next === dirty) return;
+    dirty = next;
+    if (hostCan("set_edited")) current.setEdited(dirty).catch(() => {});
+    onChange?.(dirty);
+  };
+  const compare = () => set(formKey(new FormData(form)) !== saved);
+  // After the controls' own updates (form-associated elements set their
+  // value in a microtask when it is assigned by code).
+  const check = () => queueMicrotask(() => queueMicrotask(compare));
+  const clean = () => {
+    saved = formKey(new FormData(form));
+    set(false);
+  };
+  const onReset = () => setTimeout(clean, 0);
+  form.addEventListener("input", check);
+  form.addEventListener("change", check);
+  form.addEventListener("submit", clean);
+  form.addEventListener("reset", onReset);
+  return {
+    get dirty() { return dirty; },
+    /** Takes the current values as saved (after saving them some other way). */
+    clean,
+    /** Compares now (the events already do it). */
+    check: compare,
+    stop() {
+      form.removeEventListener("input", check);
+      form.removeEventListener("change", check);
+      form.removeEventListener("submit", clean);
+      form.removeEventListener("reset", onReset);
+      set(false);
+    },
+  };
+}
+
+const TYPES = {
+  png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", gif: "image/gif", webp: "image/webp",
+  avif: "image/avif", svg: "image/svg+xml", bmp: "image/bmp", heic: "image/heic", ico: "image/x-icon",
+  mp4: "video/mp4", mov: "video/quicktime", webm: "video/webm", mkv: "video/x-matroska",
+  mp3: "audio/mpeg", wav: "audio/wav", ogg: "audio/ogg", m4a: "audio/mp4", flac: "audio/flac",
+  txt: "text/plain", md: "text/markdown", csv: "text/csv", html: "text/html", css: "text/css",
+  js: "text/javascript", xml: "text/xml", json: "application/json", pdf: "application/pdf",
+  zip: "application/zip", gz: "application/gzip", tar: "application/x-tar",
+};
+
+/** The MIME type of a file name, from its extension ("" when unknown). */
+export function typeOfName(name) {
+  const dot = String(name).lastIndexOf(".");
+  return dot < 0 ? "" : TYPES[String(name).slice(dot + 1).toLowerCase()] ?? "";
+}
+
+/** The extensions of a MIME type or pattern ("image/*", "application/pdf"). */
+export function extensionsOfType(type) {
+  const t = String(type).toLowerCase();
+  const all = Object.keys(TYPES);
+  if (t.endsWith("/*")) return all.filter((x) => TYPES[x].startsWith(t.slice(0, -1)));
+  return all.filter((x) => TYPES[x] === t);
+}
+
+/**
+ * The file dialog filters of an `accept` list (".png,image/*", as in
+ * <input type=file>): one filter with every extension, called `name` (by
+ * default the extensions). [] (any file) when a type has no known
+ * extension, so the dialog never hides a file the list accepts.
+ */
+export function acceptFilters(accept, name = "") {
+  const exts = [];
+  const list = String(accept ?? "").split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
+  for (const a of list) {
+    const more = a.startsWith(".") ? [a.slice(1)] : extensionsOfType(a);
+    if (more.length === 0) return [];
+    for (const x of more) if (!exts.includes(x)) exts.push(x);
+  }
+  if (exts.length === 0) return [];
+  return [{ name: name || exts.map((x) => x.toUpperCase()).join(", "), extensions: exts }];
+}
+
+/**
+ * A file the host chose: a path on the user's disk instead of the bytes of
+ * a File. It has the File fields components read (name, size, type,
+ * lastModified), so it lists like one; the program reads the file.
+ */
+export class HostFile {
+  constructor({ path, name, size = 0, type, lastModified = 0 }) {
+    this.path = String(path);
+    this.name = name ?? this.path.split(/[\\/]/).pop();
+    this.size = size >= 0 ? size : 0;
+    this.type = type ?? typeOfName(this.name);
+    this.lastModified = lastModified;
+  }
+}

package/core/hotkey.js

@@ -0,0 +1,40 @@
+// Keyboard shortcuts written as "mod+k", "shift+alt+p", "/": `mod` is ⌘ on
+// macOS and Ctrl elsewhere. Shared by the command palette and ray-search.
+
+export const IS_MAC = typeof navigator !== "undefined" && /Mac|iPhone|iPad/.test(navigator.platform || navigator.userAgent);
+
+function parse(spec) {
+  const parts = String(spec ?? "").toLowerCase().trim().split("+").map((s) => s.trim());
+  const key = parts.pop() ?? "";
+  const want = { meta: false, ctrl: false, alt: false, shift: false };
+  for (const p of parts) {
+    if (p === "mod") want[IS_MAC ? "meta" : "ctrl"] = true;
+    else if (p === "cmd" || p === "meta") want.meta = true;
+    else if (p === "ctrl" || p === "control") want.ctrl = true;
+    else if (p === "alt" || p === "option") want.alt = true;
+    else if (p === "shift") want.shift = true;
+  }
+  return { key, want };
+}
+
+/** Whether a keydown event is the shortcut `spec` (repeats never match). */
+export function matchesHotkey(e, spec) {
+  const { key, want } = parse(spec);
+  if (!key || e.repeat) return false;
+  return e.key.toLowerCase() === key && e.metaKey === want.meta && e.ctrlKey === want.ctrl && e.altKey === want.alt && e.shiftKey === want.shift;
+}
+
+/** The shortcut as shown to the user: "⌘K" on macOS, "Ctrl K" elsewhere. */
+export function formatHotkey(spec) {
+  const { key, want } = parse(spec);
+  if (!key) return "";
+  const k = key.length === 1 ? key.toUpperCase() : key[0].toUpperCase() + key.slice(1);
+  if (IS_MAC) return `${want.ctrl ? "⌃" : ""}${want.alt ? "⌥" : ""}${want.shift ? "⇧" : ""}${want.meta ? "⌘" : ""}${k}`;
+  return [want.ctrl && "Ctrl", want.alt && "Alt", want.shift && "Shift", want.meta && "Meta", k].filter(Boolean).join(" ");
+}
+
+/** True when the event comes from a place where typing is expected. */
+export function isTyping(e) {
+  const t = e.composedPath?.()[0] ?? e.target;
+  return Boolean(t?.isContentEditable || (t?.localName === "input" && !["checkbox", "radio", "button"].includes(t.type)) || t?.localName === "textarea" || t?.localName === "select");
+}

package/core/icons.js

@@ -0,0 +1,104 @@
+// Icon registry: every icon a ray-elements component draws comes from here, so an
+// app can switch the whole set (Lucide, Tabler, its own…) in one call:
+//
+//   import { setIcons } from "@raylang/elements";
+//   setIcons({ close: '<svg viewBox="0 0 24 24">…</svg>', "chevron-down": … });
+//
+// setIcons() also adds new names, for <ray-icon name="…">. Icons are SVG
+// markup (or an SVGElement) drawn with currentColor; components size them.
+// The markup is inserted as HTML: register icons from your own code only,
+// never from user input.
+
+const svg = (body) =>
+  `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${body}</svg>`;
+
+/** The default set (24×24, 2px stroke). */
+const DEFAULTS = {
+  "close": svg(`<path d="M6 6l12 12M18 6 6 18"/>`),
+  "check": svg(`<path d="M5 12.5l4.5 4.5L19 7.5"/>`),
+  "minus": svg(`<path d="M6 12h12"/>`),
+  "plus": svg(`<path d="M12 5v14M5 12h14"/>`),
+  "chevron-down": svg(`<path d="m6 9 6 6 6-6"/>`),
+  "chevron-up": svg(`<path d="m6 15 6-6 6 6"/>`),
+  "chevron-right": svg(`<path d="m9 6 6 6-6 6"/>`),
+  "chevron-left": svg(`<path d="m15 6-6 6 6 6"/>`),
+  "chevrons-left": svg(`<path d="m11 6-6 6 6 6M18 6l-6 6 6 6"/>`),
+  "chevrons-right": svg(`<path d="m13 6 6 6-6 6M6 6l6 6-6 6"/>`),
+  "search": svg(`<circle cx="11" cy="11" r="7"/><path d="m20 20-3.5-3.5"/>`),
+  "arrow-up-right": svg(`<path d="M7 17 17 7M8 7h9v9"/>`),
+  "arrow-down-right": svg(`<path d="M7 7l10 10M17 8v9H8"/>`),
+  "sun": svg(`<circle cx="12" cy="12" r="4"/><path d="M12 2v2M12 20v2M4.9 4.9l1.4 1.4M17.7 17.7l1.4 1.4M2 12h2M20 12h2M4.9 19.1l1.4-1.4M17.7 6.3l1.4-1.4"/>`),
+  "moon": svg(`<path d="M20 14.5A8 8 0 0 1 9.5 4a8 8 0 1 0 10.5 10.5z"/>`),
+  "monitor": svg(`<rect x="3" y="4" width="18" height="12" rx="2"/><path d="M8 20h8M12 16v4"/>`),
+  "user": svg(`<circle cx="12" cy="8" r="4"/><path d="M4 21a8 8 0 0 1 16 0"/>`),
+  "info": svg(`<circle cx="12" cy="12" r="9"/><path d="M12 11v5M12 8h.01"/>`),
+  "circle-check": svg(`<circle cx="12" cy="12" r="9"/><path d="m8.5 12.5 2.5 2.5 4.5-5"/>`),
+  "alert-triangle": svg(`<path d="M10.3 4.2 2.6 17.5A2 2 0 0 0 4.3 20.5h15.4a2 2 0 0 0 1.7-3L13.7 4.2a2 2 0 0 0-3.4 0z"/><path d="M12 9v4M12 17h.01"/>`),
+  "circle-x": svg(`<circle cx="12" cy="12" r="9"/><path d="m15 9-6 6M9 9l6 6"/>`),
+  "menu": svg(`<path d="M4 6h16M4 12h16M4 18h16"/>`),
+  "more-horizontal": svg(`<circle cx="5" cy="12" r="1"/><circle cx="12" cy="12" r="1"/><circle cx="19" cy="12" r="1"/>`),
+  // Common in command palettes, menus and nav links.
+  "file": svg(`<path d="M14 3H7a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V8z"/><path d="M14 3v5h5"/>`),
+  "folder": svg(`<path d="M3 7a2 2 0 0 1 2-2h4l2 2h8a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/>`),
+  "pause": svg(`<rect x="6" y="5" width="4" height="14" rx="1"/><rect x="14" y="5" width="4" height="14" rx="1"/>`),
+  "play": svg(`<path d="M7 4.5v15a1 1 0 0 0 1.5.86l12-7.5a1 1 0 0 0 0-1.72l-12-7.5A1 1 0 0 0 7 4.5z"/>`),
+  "terminal": svg(`<path d="m5 7 5 5-5 5M12 17h7"/>`),
+  "calendar": svg(`<rect x="3" y="5" width="18" height="16" rx="2"/><path d="M3 10h18M8 3v4M16 3v4"/>`),
+  "image": svg(`<rect x="3" y="4" width="18" height="16" rx="2"/><circle cx="9" cy="10" r="2"/><path d="m21 17-5-5-9 8"/>`),
+  "download": svg(`<path d="M12 4v11M7 10l5 5 5-5M5 20h14"/>`),
+  eye: svg(`<path d="M2.1 12.3a1 1 0 0 1 0-.6 10.8 10.8 0 0 1 19.8 0 1 1 0 0 1 0 .6 10.8 10.8 0 0 1-19.8 0"/><circle cx="12" cy="12" r="3"/>`),
+  "eye-off": svg(`<path d="M10.7 5.1a10.7 10.7 0 0 1 11.2 6.6 1 1 0 0 1 0 .7 10.8 10.8 0 0 1-1.4 2.5"/><path d="M14.1 14.2a3 3 0 0 1-4.2-4.2"/><path d="M17.5 17.5a10.7 10.7 0 0 1-15.4-5.1 1 1 0 0 1 0-.7 10.8 10.8 0 0 1 4.4-5.2"/><path d="m2 2 20 20"/>`),
+  bell: svg(`<path d="M10.3 21a1.9 1.9 0 0 0 3.4 0"/><path d="M3.3 15.3A1 1 0 0 0 4 17h16a1 1 0 0 0 .7-1.7C19.4 14 18 12.6 18 8A6 6 0 0 0 6 8c0 4.6-1.4 6-2.7 7.3"/>`),
+  copy: svg(`<rect x="9" y="9" width="12" height="12" rx="2"/><path d="M5 15a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h8a2 2 0 0 1 2 2"/>`),
+  quote: `<svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d="M10 7.5C10 6 9 5 7.5 5 4.9 5 3 7.4 3 10.8V19h7v-7H6.1c.1-2.2 1.3-3.6 2.4-3.9.9-.3 1.5-.9 1.5-1.6zM21 7.5C21 6 20 5 18.5 5 15.9 5 14 7.4 14 10.8V19h7v-7h-3.9c.1-2.2 1.3-3.6 2.4-3.9.9-.3 1.5-.9 1.5-1.6z"/></svg>`,
+  pipette: svg(`<path d="m2 22 1-1h3l9-9"/><path d="M3 21v-3l9-9"/><path d="m15 6 3.4-3.4a2.1 2.1 0 1 1 3 3L18 9l.4.4a2.1 2.1 0 1 1-3 3l-3.8-3.8a2.1 2.1 0 1 1 3-3l.4.4Z"/>`),
+  "star": svg(`<path d="M12 3.5l2.6 5.3 5.9.9-4.3 4.1 1 5.8L12 16.9l-5.2 2.7 1-5.8-4.3-4.1 5.9-.9z" stroke-linejoin="round"/>`),
+  "upload": svg(`<path d="M12 16V5M7 10l5-5 5 5M5 20h14"/>`),
+  "paperclip": svg(`<path d="m20 11-8.5 8.5a5 5 0 0 1-7-7L13 4a3.3 3.3 0 0 1 4.7 4.7l-8.6 8.6a1.7 1.7 0 0 1-2.4-2.4L14.5 7"/>`),
+  "panel-left": svg(`<rect x="3" y="4" width="18" height="16" rx="2"/><path d="M9 4v16"/>`),
+  "settings": svg(`<path d="M4 6h10M18 6h2M4 12h4M12 12h8M4 18h12"/><circle cx="16" cy="6" r="2"/><circle cx="10" cy="12" r="2"/><circle cx="18" cy="18" r="2"/>`),
+  "home": svg(`<path d="M4 10.5 12 4l8 6.5V19a1 1 0 0 1-1 1h-4.5v-5.5h-5V20H5a1 1 0 0 1-1-1z"/>`),
+  "arrow-left": svg(`<path d="M19 12H5M11 6l-6 6 6 6"/>`),
+  "message-circle": svg(`<path d="M20 11.5a8 8 0 0 1-11.6 7.2L4 20l1.3-4.2A8 8 0 1 1 20 11.5z"/>`),
+};
+
+const registry = new Map(Object.entries(DEFAULTS));
+const listeners = new Set();
+const warned = new Set();
+
+/**
+ * Replaces or adds icons. Values are SVG markup or an SVGElement.
+ * @param {Record<string, string | SVGElement>} icons
+ */
+export function setIcons(icons) {
+  for (const [name, value] of Object.entries(icons)) {
+    const markup = typeof value === "string" ? value.trim() : value?.outerHTML;
+    if (typeof markup !== "string" || !/^<svg[\s>]/i.test(markup)) {
+      throw new TypeError(`setIcons: "${name}" is not SVG markup or an SVGElement`);
+    }
+    registry.set(name, markup);
+  }
+  for (const cb of listeners) cb();
+}
+
+/** The SVG markup of an icon ("" and one warning when it is not registered). */
+export function getIcon(name) {
+  const markup = registry.get(name);
+  if (markup !== undefined) return markup;
+  if (!warned.has(name)) {
+    warned.add(name);
+    console.warn(`ray-elements: no icon named "${name}" (setIcons to add it)`);
+  }
+  return "";
+}
+
+/** The registered icon names. */
+export function iconNames() {
+  return [...registry.keys()];
+}
+
+/** @internal Called by the core runtime to repaint components after setIcons. */
+export function onIconsChange(cb) {
+  listeners.add(cb);
+  return () => listeners.delete(cb);
+}

package/core/motion.js

@@ -0,0 +1,73 @@
+// Motion helpers: exit animations (the CSS keyframes cover the entries) and
+// height changes, with the Web Animations API so a component can wait for an
+// animation to end before it really hides an element (dialog.close(),
+// hidePopover(), remove()).
+//
+// Durations and easings come from the tokens (--ray-duration-*,
+// --ray-easing-*). No motion — and an immediate result — when the user asks
+// for reduced motion, when the duration token is 0, or when the page is not
+// visible (hidden windows do not run animations).
+
+const reduced = typeof matchMedia === "function" ? matchMedia("(prefers-reduced-motion: reduce)") : null;
+
+/** A duration token of `el` in milliseconds ("fast" | "base" | "slow"). */
+export function duration(el, name = "base") {
+  const v = getComputedStyle(el).getPropertyValue(`--ray-duration-${name}`).trim();
+  if (!v) return 0;
+  const n = parseFloat(v);
+  return Number.isNaN(n) ? 0 : v.endsWith("ms") ? n : n * 1000;
+}
+
+/** An easing token of `el` ("standard" | "in" | "out"). */
+export function easing(el, name = "in") {
+  return getComputedStyle(el).getPropertyValue(`--ray-easing-${name}`).trim() || "ease";
+}
+
+/** Whether animations should run for `el` now. */
+export function motionAllowed(el, name = "base") {
+  return !reduced?.matches && document.visibilityState === "visible" && duration(el, name) > 0 && typeof el.animate === "function";
+}
+
+/**
+ * Plays `keyframes` on `el` (optionally its ::backdrop) and resolves when it
+ * ends — at once when motion is not allowed. The final frame stays applied
+ * (fill: forwards) until `cancel()`: call it once the element is hidden.
+ * @returns {{ finished: Promise<void>, cancel: () => void }}
+ */
+export function play(el, keyframes, { speed = "base", ease = "in", pseudoElement } = {}) {
+  if (!motionAllowed(el, speed)) return { finished: Promise.resolve(), cancel() {} };
+  const ms = duration(el, speed);
+  let anim;
+  try {
+    anim = el.animate(keyframes, { duration: ms, easing: easing(el, ease), fill: "forwards", ...(pseudoElement ? { pseudoElement } : {}) });
+  } catch {
+    return { finished: Promise.resolve(), cancel() {} };
+  }
+  // A throttled or suspended timeline must not keep the element open forever.
+  const guard = new Promise((r) => setTimeout(r, ms + 150));
+  return {
+    finished: Promise.race([anim.finished.then(() => {}, () => {}), guard]),
+    cancel: () => anim.cancel(),
+  };
+}
+
+/** Plays several animations; resolves when all ended. */
+export function playAll(list) {
+  return { finished: Promise.all(list.map((a) => a.finished)).then(() => {}), cancel: () => list.forEach((a) => a.cancel()) };
+}
+
+/** Fades and shrinks an element to nothing (height, margins, padding), then resolves. */
+export function collapseOut(el, { speed = "base" } = {}) {
+  const cs = getComputedStyle(el);
+  const h = el.getBoundingClientRect().height;
+  return play(el, [
+    { height: `${h}px`, opacity: 1, marginTop: cs.marginTop, marginBottom: cs.marginBottom, paddingTop: cs.paddingTop, paddingBottom: cs.paddingBottom, overflow: "hidden" },
+    { height: "0px", opacity: 0, marginTop: "0px", marginBottom: "0px", paddingTop: "0px", paddingBottom: "0px", overflow: "hidden" },
+  ], { speed });
+}
+
+/** The exit of a floating panel (menus, popovers, dropdowns, tooltips). */
+export const POP_OUT = [
+  { opacity: 1, transform: "none" },
+  { opacity: 0, transform: "scale(0.97)" },
+];

package/core/position.js

@@ -0,0 +1,91 @@
+// Anchored positioning for floating elements (popovers, menus, tooltips).
+//
+// The floating element is position: fixed (it lives in the top layer via the
+// Popover API), placed next to an anchor rectangle, flipped to the opposite
+// side when it does not fit, and shifted to stay inside the viewport.
+// Done in JS rather than CSS anchor positioning, which not every webview
+// ships yet (WebKitGTK, older WKWebView).
+
+const OPPOSITE = { top: "bottom", bottom: "top", left: "right", right: "left" };
+
+/**
+ * @typedef {object} PlaceOptions
+ * @property {string} [placement]  side[-align]: top|bottom|left|right, -start|-end (default "bottom")
+ * @property {number} [offset]     gap to the anchor in px (default 8)
+ * @property {number} [padding]    minimum distance to the viewport edges (default 8)
+ * @property {boolean} [flip]      try the opposite side when it does not fit (default true)
+ * @property {boolean} [matchWidth] at least as wide as the anchor
+ */
+
+/**
+ * Places `floating` next to `anchor` (a DOMRect-like {left, top, right, bottom, width, height}).
+ * The floating element must be rendered (open) so it can be measured.
+ * @param {PlaceOptions} options
+ * @returns {string} the final placement, e.g. "top-start"
+ */
+export function place(anchor, floating, { placement = "bottom", offset = 8, padding = 8, flip = true, matchWidth = false } = {}) {
+  const vw = document.documentElement.clientWidth;
+  const vh = window.innerHeight;
+  floating.style.position = "fixed";
+  floating.style.inset = "auto";
+  floating.style.margin = "0";
+  if (matchWidth) floating.style.minWidth = `${anchor.width}px`;
+  const f = floating.getBoundingClientRect();
+  let [side, align = "center"] = placement.split("-");
+
+  const fits = (s) => {
+    if (s === "bottom") return anchor.bottom + offset + f.height <= vh - padding;
+    if (s === "top") return anchor.top - offset - f.height >= padding;
+    if (s === "right") return anchor.right + offset + f.width <= vw - padding;
+    return anchor.left - offset - f.width >= padding;
+  };
+  if (flip && !fits(side) && fits(OPPOSITE[side])) side = OPPOSITE[side];
+
+  let x;
+  let y;
+  if (side === "top" || side === "bottom") {
+    y = side === "bottom" ? anchor.bottom + offset : anchor.top - offset - f.height;
+    x = align === "start" ? anchor.left
+      : align === "end" ? anchor.right - f.width
+      : anchor.left + anchor.width / 2 - f.width / 2;
+  } else {
+    x = side === "right" ? anchor.right + offset : anchor.left - offset - f.width;
+    y = align === "start" ? anchor.top
+      : align === "end" ? anchor.bottom - f.height
+      : anchor.top + anchor.height / 2 - f.height / 2;
+  }
+  // Shift into the viewport.
+  x = Math.max(padding, Math.min(x, vw - f.width - padding));
+  y = Math.max(padding, Math.min(y, vh - f.height - padding));
+  floating.style.left = `${Math.round(x)}px`;
+  floating.style.top = `${Math.round(y)}px`;
+  const final = `${side}-${align}`;
+  floating.dataset.placement = final;
+  return final;
+}
+
+/** A zero-size rectangle at a point (context menus). */
+export function pointRect(x, y) {
+  return { left: x, right: x, top: y, bottom: y, width: 0, height: 0, x, y };
+}
+
+/**
+ * Calls `update` whenever the layout may have moved the anchor or resized
+ * the floating element: scroll (any ancestor), window resize, element resize.
+ * @returns {() => void} stops watching
+ */
+export function autoUpdate(anchor, floating, update) {
+  const onChange = () => update();
+  window.addEventListener("scroll", onChange, { capture: true, passive: true });
+  window.addEventListener("resize", onChange);
+  const ro = typeof ResizeObserver === "function" ? new ResizeObserver(onChange) : null;
+  if (ro) {
+    if (anchor instanceof Element) ro.observe(anchor);
+    ro.observe(floating);
+  }
+  return () => {
+    window.removeEventListener("scroll", onChange, { capture: true });
+    window.removeEventListener("resize", onChange);
+    ro?.disconnect();
+  };
+}