@luxalgo/vela 0.8.2 → 0.8.4

package/dist/ui.cjs

@@ -644,6 +644,55 @@ var Tooltip = class {
     this.trigger.removeAttribute("data-scope");
   }
 };
+
+// src/ui/surface-exit.ts
+var CLOSING_ATTR = "data-closing";
+var SURFACE_EXIT_CAP_MS = 1e3;
+function animationsOf(els) {
+  return els.flatMap((el) => el.getAnimations({ subtree: true }));
+}
+function ends(a) {
+  return Number.isFinite(a.effect?.getComputedTiming().endTime ?? Number.POSITIVE_INFINITY);
+}
+function holdForExit(els, done, opts = {}) {
+  const list = Array.isArray(els) ? els : [els];
+  if (list.length === 0 || !list.every((el) => typeof el.getAnimations === "function")) {
+    done();
+    return null;
+  }
+  const before = new Set(animationsOf(list));
+  for (const el of list) el.setAttribute(CLOSING_ATTR, "");
+  const exit = animationsOf(list).filter((a) => !before.has(a) && ends(a));
+  if (exit.length === 0) {
+    for (const el of list) el.removeAttribute(CLOSING_ATTR);
+    done();
+    return null;
+  }
+  const frozen = [...list, ...opts.inert ?? []];
+  const wasInert = frozen.map((el) => el.inert);
+  for (const el of frozen) el.inert = true;
+  let settled = false;
+  const settle = (complete) => {
+    if (settled) return;
+    settled = true;
+    clearTimeout(cap);
+    for (const el of list) el.removeAttribute(CLOSING_ATTR);
+    frozen.forEach((el, i) => {
+      el.inert = wasInert[i];
+    });
+    if (complete) done();
+  };
+  const cap = setTimeout(() => settle(true), SURFACE_EXIT_CAP_MS);
+  let pending = exit.length;
+  const one = () => {
+    if (--pending === 0) settle(true);
+  };
+  for (const a of exit) a.finished.then(one, one);
+  return {
+    cancel: () => settle(false),
+    finish: () => settle(true)
+  };
+}
 function menuController(opts) {
   return {
     machine: menu__namespace.machine,
@@ -725,6 +774,35 @@ var MENU_CSS = `
     color: var(--vela-fg-bright);
 }
 .vela-menu-item[data-checkmark] { color: var(--vela-fg-bright); }
+/* Badge mode (iconBadges): the row icon sits in a rounded tile and the row grows to fit
+   it. An icon-less row of the same level keeps an invisible slot, so labels align. */
+.vela-menu[data-badges] > .vela-menu-item { padding: 5px 10px 5px 6px; }
+.vela-menu-item .vela-menu-badge {
+    width: 24px;
+    height: 24px;
+    padding: 3px;
+    flex: none;
+    box-sizing: border-box;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    border-radius: var(--vela-radius-md);
+    background: var(--vela-hover);
+    border: 1px solid var(--vela-border);
+    color: var(--vela-fg-muted);
+    transition: background var(--vela-dur-fast) var(--vela-ease), border-color var(--vela-dur-fast) var(--vela-ease), color var(--vela-dur-fast) var(--vela-ease);
+}
+.vela-menu-item .vela-menu-badge:empty { background: transparent; border-color: transparent; }
+.vela-menu-item .vela-menu-badge .vela-icon { color: inherit; }
+.vela-menu-item[data-highlighted] .vela-menu-badge:not(:empty) { color: var(--vela-fg-bright); }
+/* The selected tile inverts: a bright fill under the surface-colored glyph. After the
+   hover rule, so a selected row keeps its tile while highlighted. */
+.vela-menu-item[data-checked] .vela-menu-badge:not(:empty),
+.vela-menu-item[data-checkmark] .vela-menu-badge:not(:empty) {
+    background: color-mix(in srgb, var(--vela-fg-bright) 83%, var(--vela-surface));
+    border-color: color-mix(in srgb, var(--vela-fg-bright) 40%, transparent);
+    color: var(--vela-surface);
+}
 /* Switch rows (boolean settings in a dropdown): a right-aligned toggle pill \u2014 the
    same control language as the settings dialog's toggles. */
 .vela-menu-switch {
@@ -791,11 +869,14 @@ var Surface = class _Surface {
     this.pinnedAnchor = null;
     /** The open state last announced — see {@link announce}. */
     this.shown = false;
+    /** The list's exit animation after a close; a reopen cancels it. */
+    this.exit = null;
     this.doc = doc;
     this.host = opts.host;
     this.onSelect = opts.onSelect;
     this.onFavorite = opts.onFavorite;
     this.checkmarks = opts.checkmarks === true;
+    this.iconBadges = opts.iconBadges === true;
     this.positioner = doc.createElement("div");
     this.positioner.className = "vela-ui-layer";
     this.list = doc.createElement("ul");
@@ -826,14 +907,30 @@ var Surface = class _Surface {
     if (opts.triggerId && trigger) trigger.id = opts.triggerId;
     this.handle = runMachine(this.ctrl.machine, this.ctrl.props, (service) => {
       const api = this.ctrl.connect(service);
-      if (this.shown && !api.open) this.announce(false);
+      const closing = this.shown && !api.open;
+      if (closing) this.announce(false);
+      if (api.open && this.exit) {
+        this.exit.cancel();
+        this.exit = null;
+      }
       if (trigger) vanilla.spreadProps(trigger, api.getTriggerProps(), this.mid);
       vanilla.spreadProps(this.positioner, api.getPositionerProps(), this.mid);
       vanilla.spreadProps(this.list, api.getContentProps(), this.mid);
       this.project(api);
+      if (closing) this.holdExit();
       if (api.open && !this.shown) this.announce(true);
     });
   }
+  /** Keep the just-closed list up through its exit animation. `spreadProps` re-applies
+   *  `hidden` only when the machine's value for it changes, so the list stays shown until
+   *  the exit ends — or until a reopen, which projects `hidden: false` itself. */
+  holdExit() {
+    this.list.hidden = false;
+    this.exit = holdForExit(this.list, () => {
+      this.exit = null;
+      if (!this.shown) this.list.hidden = true;
+    });
+  }
   get api() {
     return this.ctrl.connect(this.handle.service);
   }
@@ -857,6 +954,7 @@ var Surface = class _Surface {
   destroy() {
     for (const sub of this.subs.values()) sub.destroy();
     this.subs.clear();
+    this.exit?.finish();
     this.handle.stop();
     if (this.shown) this.announce(false);
     this.positioner.remove();
@@ -883,6 +981,10 @@ var Surface = class _Surface {
     const doc = this.doc;
     this.list.replaceChildren();
     const markable = this.checkmarks && this.items.some((i) => !(i.submenu && i.submenu.length > 0) && !i.toggle && i.checked !== void 0);
+    const iconic = this.items.some((i) => !!i.icon);
+    const badged = this.iconBadges && iconic;
+    if (badged) this.list.dataset.badges = "1";
+    else delete this.list.dataset.badges;
     for (const item of this.items) {
       if (item.separatorBefore) {
         const sep = doc.createElement("li");
@@ -908,7 +1010,16 @@ var Surface = class _Surface {
       } else if (!branch && !item.toggle && item.checked) {
         li.dataset.checked = "1";
       }
-      if (item.icon) li.appendChild(iconEl(item.icon, doc));
+      if (badged) {
+        const badge = doc.createElement("span");
+        badge.className = "vela-menu-badge";
+        if (item.icon) badge.appendChild(iconEl(item.icon, doc));
+        li.appendChild(badge);
+      } else if (item.icon) {
+        li.appendChild(iconEl(item.icon, doc));
+      } else if (iconic) {
+        li.appendChild(iconEl("", doc));
+      }
       const label = doc.createElement("span");
       label.className = "vela-menu-label";
       label.textContent = item.label;
@@ -956,6 +1067,7 @@ var Surface = class _Surface {
           onSelect: this.onSelect,
           onFavorite: this.onFavorite,
           checkmarks: this.checkmarks,
+          iconBadges: this.iconBadges,
           id: `${this.mid}--${item.id}`
         });
         sub.setItems(item.submenu ?? []);
@@ -981,7 +1093,8 @@ var Menu = class {
       id: opts.id,
       minWidth: opts.minWidth,
       onFavorite: opts.onFavorite,
-      checkmarks: opts.checkmarks
+      checkmarks: opts.checkmarks,
+      iconBadges: opts.iconBadges
     });
     this.root.setItems(opts.items);
   }
@@ -1085,6 +1198,7 @@ var POPOVER_CSS = `
 
 // src/ui/components/popover/view.ts
 var open = null;
+var leaving = /* @__PURE__ */ new Set();
 function closeOpenPopovers() {
   open?.hide();
 }
@@ -1112,6 +1226,8 @@ var Popover = class {
     this.shown = false;
     /** The pending removal of a fading-out shell; a show() that reuses the shell cancels it. */
     this.leaveTimer = null;
+    /** The shell's exit animation before it leaves the DOM; a show() that reuses the shell cancels it. */
+    this.exit = null;
     const doc = opts.trigger.ownerDocument;
     injectStyles(POPOVER_STYLE_ID, POPOVER_CSS, doc);
     this.trigger = opts.trigger;
@@ -1148,6 +1264,10 @@ var Popover = class {
       clearTimeout(this.leaveTimer);
       this.leaveTimer = null;
     }
+    this.exit?.cancel();
+    this.exit = null;
+    leaving.delete(this);
+    for (const p of [...leaving]) if (p.trigger === this.trigger) p.exit?.finish();
     ensureUIHost(this.el, this.inheritsTokens ? void 0 : this.theme);
     if (this.fadeMs > 0) {
       this.el.style.transition = `opacity ${this.fadeMs}ms ease`;
@@ -1204,7 +1324,12 @@ var Popover = class {
         this.el.remove();
       }, this.fadeMs);
     } else {
-      this.el.remove();
+      this.exit = holdForExit(this.el, () => {
+        this.exit = null;
+        leaving.delete(this);
+        this.el.remove();
+      });
+      if (this.exit) leaving.add(this);
     }
     if (open === this) open = null;
     this.ctrl.onClose?.();
@@ -1216,6 +1341,7 @@ var Popover = class {
   }
   destroy() {
     this.hide();
+    this.exit?.finish();
   }
   reposition() {
     if (this.shown) this.place();
@@ -1413,6 +1539,9 @@ var Dialog = class {
   constructor(opts = {}) {
     this.opener = null;
     this.wasOpen = false;
+    /** The panel and scrim's exit animation after a close; a reopen cancels it. */
+    this.exit = null;
+    this.destroyed = false;
     const doc = (opts.host ?? document.body).ownerDocument;
     injectStyles(DIALOG_STYLE_ID, DIALOG_CSS, doc);
     const host = opts.host ?? doc.body;
@@ -1509,19 +1638,57 @@ var Dialog = class {
     const mid = String(this.ctrl.props.id);
     this.handle = runMachine(this.ctrl.machine, this.ctrl.props, (service) => {
       const api = this.ctrl.connect(service);
-      if (this.wasOpen && !api.open) this.announce(false);
+      const closing = this.wasOpen && !api.open;
+      if (closing) this.announce(false);
       vanilla.spreadProps(this.backdrop, api.getBackdropProps(), mid);
       vanilla.spreadProps(this.positioner, api.getPositionerProps(), mid);
       vanilla.spreadProps(this.panel, api.getContentProps(), mid);
       vanilla.spreadProps(title, api.getTitleProps(), mid);
       vanilla.spreadProps(close, api.getCloseTriggerProps(), mid);
-      this.backdrop.style.display = api.open ? "" : "none";
-      this.positioner.style.display = api.open ? "" : "none";
+      if (api.open) {
+        this.exit?.cancel();
+        this.exit = null;
+        this.setShown(true);
+      } else if (closing) {
+        this.holdExit();
+      } else if (!this.exit) {
+        this.setShown(false);
+      }
       if (api.open && !this.wasOpen) this.announce(true);
       if (this.wasOpen && !api.open) this.restoreOpener();
       this.wasOpen = api.open;
     });
   }
+  setShown(shown) {
+    this.backdrop.style.display = shown ? "" : "none";
+    this.positioner.style.display = shown ? "" : "none";
+  }
+  /** Keep the just-closed dialog up through its exit animation, then hide it — or
+   *  remove it, when it was destroyed meanwhile. `spreadProps` re-applies the close
+   *  props' `hidden` only when its value changes, so lifting it keeps the panel and
+   *  scrim up until the exit ends. The positioner spans the viewport: inert, it lets
+   *  clicks through to the page while the panel animates out. */
+  holdExit() {
+    const held = [this.panel, this.backdrop];
+    for (const el of held) el.hidden = false;
+    this.exit = holdForExit(
+      held,
+      () => {
+        this.exit = null;
+        if (this.destroyed) {
+          this.detach();
+        } else if (!this.open) {
+          for (const el of held) el.hidden = true;
+          this.setShown(false);
+        }
+      },
+      { inert: [this.positioner] }
+    );
+  }
+  detach() {
+    this.backdrop.remove();
+    this.positioner.remove();
+  }
   /** Closing hands focus back to whatever opened it (Escape, the ✕, hide(), or a
    *  teardown that outruns the machine's close notification). */
   restoreOpener() {
@@ -1550,15 +1717,16 @@ var Dialog = class {
     return el?.closest(".vela-popover, .vela-menu") != null;
   }
   destroy() {
+    if (this.wasOpen && !this.open) this.handle.flush();
     if (this.open) this.hide();
     this.handle.stop();
+    this.destroyed = true;
     if (this.wasOpen) {
       this.wasOpen = false;
       this.announce(false);
     }
     this.restoreOpener();
-    this.backdrop.remove();
-    this.positioner.remove();
+    if (!this.exit) this.detach();
   }
 };
 function drawerController(opts = {}) {
@@ -1687,6 +1855,9 @@ var Drawer = class {
   constructor(opts = {}) {
     this.opener = null;
     this.wasOpen = false;
+    /** The sheet and scrim's exit animation after a close; a reopen cancels it. */
+    this.exit = null;
+    this.destroyed = false;
     const doc = (opts.host ?? document.body).ownerDocument;
     injectStyles(DRAWER_STYLE_ID, DRAWER_CSS, doc);
     const host = opts.host ?? doc.body;
@@ -1714,13 +1885,21 @@ var Drawer = class {
     const mid = String(this.ctrl.props.id);
     this.handle = runMachine(this.ctrl.machine, this.ctrl.props, (service) => {
       const api = this.ctrl.connect(service);
-      if (this.wasOpen && !api.open) this.announce(false);
+      const closing = this.wasOpen && !api.open;
+      if (closing) this.announce(false);
       vanilla.spreadProps(this.backdrop, api.getBackdropProps(), mid);
       vanilla.spreadProps(this.positioner, api.getPositionerProps(), mid);
       vanilla.spreadProps(this.panel, api.getContentProps(), mid);
       vanilla.spreadProps(this.titleEl, api.getTitleProps(), mid);
-      this.backdrop.style.display = api.open ? "" : "none";
-      this.positioner.style.display = api.open ? "" : "none";
+      if (api.open) {
+        this.exit?.cancel();
+        this.exit = null;
+        this.setShown(true);
+      } else if (closing) {
+        this.holdExit();
+      } else if (!this.exit) {
+        this.setShown(false);
+      }
       if (api.open && !this.wasOpen) this.announce(true);
       if (this.wasOpen && !api.open) this.restoreOpener();
       this.wasOpen = api.open;
@@ -1832,6 +2011,36 @@ var Drawer = class {
   setTitle(title) {
     this.titleEl.textContent = title;
   }
+  setShown(shown) {
+    this.backdrop.style.display = shown ? "" : "none";
+    this.positioner.style.display = shown ? "" : "none";
+  }
+  /** Keep the just-closed sheet up through its exit animation, then hide it — or
+   *  remove it, when it was destroyed meanwhile. `spreadProps` re-applies the close
+   *  props' `hidden` only when its value changes, so lifting it keeps the sheet and
+   *  scrim up until the exit ends. The positioner spans the host: inert, it lets
+   *  clicks through to the page while the sheet animates out. */
+  holdExit() {
+    const held = [this.panel, this.backdrop];
+    for (const el of held) el.hidden = false;
+    this.exit = holdForExit(
+      held,
+      () => {
+        this.exit = null;
+        if (this.destroyed) {
+          this.detach();
+        } else if (!this.open) {
+          for (const el of held) el.hidden = true;
+          this.setShown(false);
+        }
+      },
+      { inert: [this.positioner] }
+    );
+  }
+  detach() {
+    this.backdrop.remove();
+    this.positioner.remove();
+  }
   /** Closing hands focus back to whatever opened it (Escape, the ✕, hide(), or a
    *  teardown that outruns the machine's close notification). */
   restoreOpener() {
@@ -1854,14 +2063,15 @@ var Drawer = class {
     this.ctrl.connect(this.handle.service).setOpen(false);
   }
   destroy() {
+    if (this.wasOpen && !this.open) this.handle.flush();
     this.handle.stop();
+    this.destroyed = true;
     if (this.wasOpen) {
       this.wasOpen = false;
       this.announce(false);
     }
     this.restoreOpener();
-    this.backdrop.remove();
-    this.positioner.remove();
+    if (!this.exit) this.detach();
   }
 };
 

package/dist/ui.d.cts

@@ -1,4 +1,4 @@
-import { c as VelaTheme } from './options-NAUHiQEC.cjs';
+import { c as VelaTheme } from './options-CSXbjMM5.cjs';
 import { MachineSchema, Service, Machine } from '@zag-js/core';
 export { a as KeyBindingDescriptor, K as KeymapManager, b as KeymapOptions, R as ResolvedBinding } from './keymap-CGOz5F5f.cjs';
 import * as tooltip from '@zag-js/tooltip';
@@ -11,91 +11,6 @@ export { normalizeProps, spreadProps } from '@zag-js/vanilla';
  *  returned unchanged so callers can pass through `transparent`, `currentColor`, etc. */
 declare function withAlpha(color: string, alpha: number): string;
 
-/** A ready-to-insert element rendering the icon (empty span when unknown). */
-declare function iconEl(id: string, doc?: Document): HTMLElement;
-
-/** Overlay scrollbar used by settings panes, dialog bodies, and similar chrome. */
-declare function overlayScrollbarCss(selector: string, width?: number): string;
-/** Focus ring shared by typeable fields (combo inputs, textareas). */
-declare const FIELD_FOCUS_CSS = "outline:none;transition:border-color .12s ease,box-shadow .12s ease;";
-declare const FIELD_FOCUS_RING = "border-color:var(--vela-focus);box-shadow:0 0 0 3px var(--vela-focus-soft);";
-/** Inject a stylesheet once per root (document or shadow root). Idempotent by id. */
-declare function injectStyles(id: string, css: string, root?: Document | ShadowRoot): void;
-
-/** Write the theme-derived custom properties onto a host element (the widget root and
- *  every floating layer — menus/tooltips portal outside the root, so layers re-apply). */
-declare function applyThemeTokens(el: HTMLElement, t: VelaTheme): void;
-/** Re-token a chart-overlay host (statusline, watermark, toast — chrome floating OVER
- *  the plot) from the LIVE plot surface: a config edit can recolor the plot background
- *  independently of the app theme (a white plot typed into settings on the dark theme),
- *  and the overlay ink must stay readable either way. `config` is the renderer's
- *  `getConfig()` snapshot; a missing/shapeless one falls back to the base app theme.
- *  Floating menus and dropdowns do NOT use this — they mount on {@link floatingLayerHost}
- *  so their surface follows the app theme alone. */
-declare function applyPlotOverlayTokens(host: HTMLElement, base: VelaTheme, config: unknown): void;
-/** Mark an element as a kit host: static token sheet + the `.vela-ui` class. */
-declare function ensureUIHost(el: HTMLElement, theme?: VelaTheme): void;
-
-interface MachineHandle<T extends MachineSchema> {
-    service: Service<T>;
-    /** Re-run the view projection now (e.g. after external DOM swaps). */
-    flush(): void;
-    stop(): void;
-}
-/** Start a machine and keep `render(service)` in sync with every transition.
- *  `render` runs once immediately (initial projection) and on each machine notification. */
-declare function runMachine<T extends MachineSchema>(machine: Machine<T>, props: Partial<T['props']> | (() => Partial<T['props']>), render: (service: Service<T>) => void): MachineHandle<T>;
-/** Unique ids for machine instances (Zag keys its DOM lookups on them). */
-declare function nextUid(prefix: string): string;
-
-/** Dispatched on a surface's element once it is shown. */
-declare const SURFACE_OPEN_EVENT = "vela:surface-open";
-/** Dispatched on a surface's element as it starts to close, before it hides or leaves the DOM. */
-declare const SURFACE_CLOSE_EVENT = "vela:surface-close";
-/** What opened or closed: a menu (submenus included), a popover (select lists, color
- *  pickers, mark cards, the layout picker), a dialog, a drawer, or a side panel. */
-type SurfaceKind = 'menu' | 'popover' | 'dialog' | 'drawer' | 'panel';
-/** The `detail` of a {@link SURFACE_OPEN_EVENT} / {@link SURFACE_CLOSE_EVENT} event. */
-interface SurfaceEventDetail {
-    kind: SurfaceKind;
-    /** The element that opened it, when there is one (a menu's button, a popover's trigger). */
-    trigger: HTMLElement | null;
-}
-
-interface TooltipControllerOptions {
-    placement?: tooltip.Placement;
-    /** ms before opening on hover (default 0 — the reference tooltips are instant). */
-    openDelay?: number;
-    closeDelay?: number;
-    /** Keep open while the pointer is over the content (rich tooltips). */
-    interactive?: boolean;
-    /** Share the trigger's DOM id with other machines composed on the SAME element
-     *  (each Zag machine otherwise stamps its own id — last one wins and breaks the rest). */
-    triggerId?: string;
-}
-type TooltipService = tooltip.Service;
-type TooltipApi = tooltip.Api;
-interface TooltipController {
-    machine: typeof tooltip.machine;
-    props: Partial<tooltip.Props>;
-    connect(service: TooltipService): TooltipApi;
-}
-declare function tooltipController(opts?: TooltipControllerOptions): TooltipController;
-
-interface TooltipOptions extends TooltipControllerOptions {
-    content: string | Node | (() => Node);
-    host?: HTMLElement;
-}
-declare class Tooltip {
-    private readonly positioner;
-    private readonly content;
-    private readonly handle;
-    private readonly trigger;
-    constructor(trigger: HTMLElement, opts: TooltipOptions);
-    setContent(content: string | Node | (() => Node)): void;
-    destroy(): void;
-}
-
 /** One menu entry. `id` is the selection value reported to `onSelect`. */
 interface MenuItemDescriptor {
     id: string;
@@ -113,7 +28,8 @@ interface MenuItemDescriptor {
      *  instead of the selected-row highlight, and keep the menu OPEN on selection —
      *  the shape for boolean settings living inside a dropdown. */
     toggle?: boolean;
-    /** Icon id (see the `vela/ui` icon registry) rendered before the label. */
+    /** Icon id (see the `vela/ui` icon registry) rendered before the label. A level where
+     *  any row has one gives its iconless rows an empty slot, so the labels align. */
     icon?: string;
     /** Favorite-star affordance at the row's right edge: `false` renders an outline
      *  star revealed on row hover, `true` a filled star that stays visible. Clicking
@@ -175,6 +91,13 @@ interface MenuOptions extends MenuControllerOptions {
      *  edge. Submenus inherit the mode. Dropdown menus (a trigger button opening a
      *  picker) keep the default wash. */
     checkmarks?: boolean;
+    /** Sit each row's icon in a squared badge (a 24px rounded tile with a faint fill and a soft
+     *  border) instead of a bare glyph: its glyph brightens on a hovered row, and the tile
+     *  inverts on the selected one. A
+     *  level where some rows carry an icon reserves the badge column on all its rows so
+     *  labels align; a level with no icon keeps its natural left edge. With `checkmarks`,
+     *  the mark column leads and the badge follows. Submenus inherit the mode. */
+    iconBadges?: boolean;
 }
 declare class Menu {
     private readonly root;
@@ -189,6 +112,91 @@ declare class Menu {
     destroy(): void;
 }
 
+/** A ready-to-insert element rendering the icon (empty span when unknown). */
+declare function iconEl(id: string, doc?: Document): HTMLElement;
+
+/** Overlay scrollbar used by settings panes, dialog bodies, and similar chrome. */
+declare function overlayScrollbarCss(selector: string, width?: number): string;
+/** Focus ring shared by typeable fields (combo inputs, textareas). */
+declare const FIELD_FOCUS_CSS = "outline:none;transition:border-color .12s ease,box-shadow .12s ease;";
+declare const FIELD_FOCUS_RING = "border-color:var(--vela-focus);box-shadow:0 0 0 3px var(--vela-focus-soft);";
+/** Inject a stylesheet once per root (document or shadow root). Idempotent by id. */
+declare function injectStyles(id: string, css: string, root?: Document | ShadowRoot): void;
+
+/** Write the theme-derived custom properties onto a host element (the widget root and
+ *  every floating layer — menus/tooltips portal outside the root, so layers re-apply). */
+declare function applyThemeTokens(el: HTMLElement, t: VelaTheme): void;
+/** Re-token a chart-overlay host (statusline, watermark, toast — chrome floating OVER
+ *  the plot) from the LIVE plot surface: a config edit can recolor the plot background
+ *  independently of the app theme (a white plot typed into settings on the dark theme),
+ *  and the overlay ink must stay readable either way. `config` is the renderer's
+ *  `getConfig()` snapshot; a missing/shapeless one falls back to the base app theme.
+ *  Floating menus and dropdowns do NOT use this — they mount on {@link floatingLayerHost}
+ *  so their surface follows the app theme alone. */
+declare function applyPlotOverlayTokens(host: HTMLElement, base: VelaTheme, config: unknown): void;
+/** Mark an element as a kit host: static token sheet + the `.vela-ui` class. */
+declare function ensureUIHost(el: HTMLElement, theme?: VelaTheme): void;
+
+interface MachineHandle<T extends MachineSchema> {
+    service: Service<T>;
+    /** Re-run the view projection now (e.g. after external DOM swaps). */
+    flush(): void;
+    stop(): void;
+}
+/** Start a machine and keep `render(service)` in sync with every transition.
+ *  `render` runs once immediately (initial projection) and on each machine notification. */
+declare function runMachine<T extends MachineSchema>(machine: Machine<T>, props: Partial<T['props']> | (() => Partial<T['props']>), render: (service: Service<T>) => void): MachineHandle<T>;
+/** Unique ids for machine instances (Zag keys its DOM lookups on them). */
+declare function nextUid(prefix: string): string;
+
+/** Dispatched on a surface's element once it is shown. */
+declare const SURFACE_OPEN_EVENT = "vela:surface-open";
+/** Dispatched on a surface's element as it starts to close, before it hides or leaves the DOM. */
+declare const SURFACE_CLOSE_EVENT = "vela:surface-close";
+/** What opened or closed: a menu (submenus included), a popover (select lists, color
+ *  pickers, mark cards, the layout picker), a dialog, a drawer, or a side panel. */
+type SurfaceKind = 'menu' | 'popover' | 'dialog' | 'drawer' | 'panel';
+/** The `detail` of a {@link SURFACE_OPEN_EVENT} / {@link SURFACE_CLOSE_EVENT} event. */
+interface SurfaceEventDetail {
+    kind: SurfaceKind;
+    /** The element that opened it, when there is one (a menu's button, a popover's trigger). */
+    trigger: HTMLElement | null;
+}
+
+interface TooltipControllerOptions {
+    placement?: tooltip.Placement;
+    /** ms before opening on hover (default 0 — the reference tooltips are instant). */
+    openDelay?: number;
+    closeDelay?: number;
+    /** Keep open while the pointer is over the content (rich tooltips). */
+    interactive?: boolean;
+    /** Share the trigger's DOM id with other machines composed on the SAME element
+     *  (each Zag machine otherwise stamps its own id — last one wins and breaks the rest). */
+    triggerId?: string;
+}
+type TooltipService = tooltip.Service;
+type TooltipApi = tooltip.Api;
+interface TooltipController {
+    machine: typeof tooltip.machine;
+    props: Partial<tooltip.Props>;
+    connect(service: TooltipService): TooltipApi;
+}
+declare function tooltipController(opts?: TooltipControllerOptions): TooltipController;
+
+interface TooltipOptions extends TooltipControllerOptions {
+    content: string | Node | (() => Node);
+    host?: HTMLElement;
+}
+declare class Tooltip {
+    private readonly positioner;
+    private readonly content;
+    private readonly handle;
+    private readonly trigger;
+    constructor(trigger: HTMLElement, opts: TooltipOptions);
+    setContent(content: string | Node | (() => Node)): void;
+    destroy(): void;
+}
+
 interface DialogControllerOptions {
     /** Trap focus + backdrop (default true). Non-modal = floating panel. */
     modal?: boolean;
@@ -245,6 +253,17 @@ declare class Dialog {
     constructor(opts?: DialogOptions);
     private opener;
     private wasOpen;
+    /** The panel and scrim's exit animation after a close; a reopen cancels it. */
+    private exit;
+    private destroyed;
+    private setShown;
+    /** Keep the just-closed dialog up through its exit animation, then hide it — or
+     *  remove it, when it was destroyed meanwhile. `spreadProps` re-applies the close
+     *  props' `hidden` only when its value changes, so lifting it keeps the panel and
+     *  scrim up until the exit ends. The positioner spans the viewport: inert, it lets
+     *  clicks through to the page while the panel animates out. */
+    private holdExit;
+    private detach;
     /** Closing hands focus back to whatever opened it (Escape, the ✕, hide(), or a
      *  teardown that outruns the machine's close notification). */
     private restoreOpener;
@@ -312,6 +331,17 @@ declare class Drawer {
     setTitle(title: string): void;
     private opener;
     private wasOpen;
+    /** The sheet and scrim's exit animation after a close; a reopen cancels it. */
+    private exit;
+    private destroyed;
+    private setShown;
+    /** Keep the just-closed sheet up through its exit animation, then hide it — or
+     *  remove it, when it was destroyed meanwhile. `spreadProps` re-applies the close
+     *  props' `hidden` only when its value changes, so lifting it keeps the sheet and
+     *  scrim up until the exit ends. The positioner spans the host: inert, it lets
+     *  clicks through to the page while the sheet animates out. */
+    private holdExit;
+    private detach;
     /** Closing hands focus back to whatever opened it (Escape, the ✕, hide(), or a
      *  teardown that outruns the machine's close notification). */
     private restoreOpener;
@@ -425,6 +455,8 @@ declare class Popover {
     private readonly fadeMs;
     /** The pending removal of a fading-out shell; a show() that reuses the shell cancels it. */
     private leaveTimer;
+    /** The shell's exit animation before it leaves the DOM; a show() that reuses the shell cancels it. */
+    private exit;
     constructor(opts: PopoverOptions);
     get open(): boolean;
     get position(): PopoverPosition;