@threadlabs/looma 0.14.7 → 0.15.0

package/components/ui-toast/ui-toast.html

@@ -0,0 +1,88 @@
+<link rel="component" href="../ui-icon-button/ui-icon-button.html">
+<link rel="component" href="../ui-icon/ui-icon.html">
+<template component="ui-toast" controller="./ui-toast.js">
+  <defs>
+    <prop name="tone" type="neutral | info | success | warning | danger" default="neutral"
+    >Semantic accent for this message. Danger uses an assertive alert role; the other tones use polite status semantics.</prop>
+    <prop name="duration" type="number" default="0"
+    >Milliseconds before requesting dismissal; 0 keeps the toast until an action dismisses it. The timer pauses on hover or focus.</prop>
+    <event name="dismiss" type="object({ id: string, reason: action | timeout, trigger: keyboard | pointer | programmatic })"></event>
+  </defs>
+  <div :role="{ neutral: 'status', info: 'status', success: 'status', warning: 'status', danger: 'alert' }[tone]">
+    <div class="message"><slot></slot></div>
+    <div class="action" $ref="action"><slot name="action"></slot></div>
+    <ui-icon-button class="dismiss" size="sm" variant="ghost" :round="true" label="Dismiss notification">
+      <ui-icon name="x"></ui-icon>
+    </ui-icon-button>
+  </div>
+  <style>
+    /* Component hooks stay on this toast; group overlay values may inherit from the region. */
+    @property --ui-toast-surface {
+      syntax: "*";
+      inherits: false;
+    }
+    @property --ui-toast-border {
+      syntax: "*";
+      inherits: false;
+    }
+    @property --ui-toast-radius {
+      syntax: "*";
+      inherits: false;
+    }
+    @property --ui-toast-shadow {
+      syntax: "*";
+      inherits: false;
+    }
+    @property --ui-toast-accent {
+      syntax: "*";
+      inherits: false;
+    }
+
+    :host {
+      --_ui-toast-accent: var(--ui-border-strong);
+
+      display: flex;
+      align-items: center;
+      gap: var(--ui-space-2);
+      box-sizing: border-box;
+      inline-size: 100%;
+      margin: 0;
+      padding: var(--ui-space-3) var(--ui-space-4);
+      border: 1px solid var(--ui-toast-border, var(--ui-overlay-border, var(--ui-border-default)));
+      border-inline-start: 3px solid var(--ui-toast-accent, var(--_ui-toast-accent));
+      border-radius: var(--ui-toast-radius, var(--ui-overlay-radius, var(--ui-radius-lg)));
+      background: var(--ui-toast-surface, var(--ui-overlay-surface, var(--ui-surface-elevated)));
+      color: var(--ui-text-primary);
+      box-shadow: var(--ui-toast-shadow, var(--ui-overlay-shadow, var(--ui-elevation-overlay, var(--ui-shadow-lg))));
+      pointer-events: auto;
+    }
+
+    :host-state([tone="info"]) {
+      --_ui-toast-accent: var(--ui-info-solid);
+    }
+    :host-state([tone="success"]) {
+      --_ui-toast-accent: var(--ui-success-solid);
+    }
+    :host-state([tone="warning"]) {
+      --_ui-toast-accent: var(--ui-warning-solid);
+    }
+    :host-state([tone="danger"]) {
+      --_ui-toast-accent: var(--ui-danger-solid);
+    }
+
+    .message {
+      min-inline-size: 0;
+      flex: 1;
+    }
+    .action:not(:has(> *)) {
+      display: none;
+    }
+    .dismiss {
+      margin-inline-end: calc(var(--ui-space-2) * -1);
+    }
+
+    :host[hidden] {
+      display: none;
+    }
+  </style>
+</template>

package/components/ui-toast/ui-toast.js

@@ -0,0 +1,68 @@
+let toastSequence = 0;
+
+function inputFor(event) {
+  return event.detail === 0 ? "keyboard" : "pointer";
+}
+
+/** Authored toasts request dismissal; their consumer owns removal from the rendered list. */
+export default function controller(host) {
+  const element = host.element;
+  const { action } = host.refs;
+  if (!element.id) element.id = `ui-toast-authored-${++toastSequence}`;
+  let remaining = Math.max(0, Number(host.state.duration) || 0);
+  let started = 0;
+  let timer = null;
+  let paused = false;
+  let dismissed = false;
+
+  const dismiss = (reason, trigger) => {
+    if (dismissed) return;
+    dismissed = true;
+    clearTimeout(timer);
+    host.dispatch("dismiss", { id: element.id, reason, trigger });
+  };
+  const start = () => {
+    clearTimeout(timer);
+    if (paused || dismissed || remaining <= 0) return;
+    started = Date.now();
+    timer = setTimeout(() => dismiss("timeout", "programmatic"), remaining);
+  };
+  const pause = () => {
+    if (paused) return;
+    paused = true;
+    if (timer !== null) remaining = Math.max(0, remaining - (Date.now() - started));
+    clearTimeout(timer);
+    timer = null;
+  };
+  const resume = () => {
+    if (!paused || element.matches(":hover, :focus-within")) return;
+    paused = false;
+    if (host.state.duration > 0 && remaining <= 0) { dismiss("timeout", "programmatic"); return; }
+    start();
+  };
+  const onFocusOut = () => queueMicrotask(resume);
+  const onClick = (event) => {
+    if (event.target.closest?.(".dismiss") || action?.contains(event.target)) dismiss("action", inputFor(event));
+  };
+  const stop = host.effect(() => {
+    const duration = Math.max(0, Number(host.state.duration) || 0);
+    if (duration === remaining || dismissed) return;
+    remaining = duration;
+    start();
+  });
+  element.addEventListener("click", onClick);
+  element.addEventListener("pointerenter", pause);
+  element.addEventListener("pointerleave", resume);
+  element.addEventListener("focusin", pause);
+  element.addEventListener("focusout", onFocusOut);
+  start();
+  return () => {
+    stop();
+    clearTimeout(timer);
+    element.removeEventListener("click", onClick);
+    element.removeEventListener("pointerenter", pause);
+    element.removeEventListener("pointerleave", resume);
+    element.removeEventListener("focusin", pause);
+    element.removeEventListener("focusout", onFocusOut);
+  };
+}

package/components/ui-toast-region/ui-toast-region.html

@@ -1,35 +1,48 @@
 <link rel="component" href="../ui-icon-button/ui-icon-button.html">
+<link rel="component" href="../ui-icon/ui-icon.html">
 <template component="ui-toast-region" controller="./ui-toast-region.js">
   <defs>
-    <prop name="open" type="boolean" default="false">Whether the messages authored inside the region are visible.</prop>
-    <prop name="message" type="string" default="Notification">Fallback message used by the declarative show command.</prop>
-    <prop name="auto" type="boolean" default="false"
-    >Dismiss each message automatically after its duration. Timers pause while the pointer or focus is on a message.</prop>
-    <prop name="duration" type="number" default="5000">Milliseconds an automatically dismissed message stays visible.</prop>
-    <state name="internalOpen" :value="false"></state>
-    <state name="toasts" type="list(object({ id: string, message: string, role: alert | status, closing: boolean }))" :value="[]"></state>
-    <event
-      name="close"
-      type="object({ open: boolean, reason: action | timeout | programmatic | light-dismiss | escape, trigger: keyboard | pointer | programmatic })"
-    ></event>
+    <prop name="duration" type="number" default="0"
+    >Default milliseconds for toasts added with show() or the show command; 0 keeps each until dismissed. Hover or focus pauses a timer.</prop>
+    <prop name="placement" type="top | top-start | top-end | bottom | bottom-start | bottom-end" default="top"
+    >Screen edge where the stack appears. Start and end follow the writing direction.</prop>
+    <state
+      name="toasts"
+      type="list(object({ id: string, message: string, tone: neutral | info | success | warning | danger, role: alert | status, closing: boolean }))"
+      :value="[]"
+    ></state>
     <event name="dismiss" type="object({ id: string, reason: action | timeout, trigger: keyboard | pointer | programmatic })"></event>
     <method name="show" export="show" returns="promise(string)"></method>
   </defs>
   <div role="region" aria-label="Notifications" aria-live="polite" popover="manual">
     <slot></slot>
-    <div $each="toast of toasts" $key="toast.id" class="toast" class:closing="toast.closing" :id="toast.id" :role="toast.role">
+    <div $each="toast of toasts" $key="toast.id" class="toast" class:closing="toast.closing" :id="toast.id" :role="toast.role" :data-tone="toast.tone">
       <span class="message" $value="toast.message"></span>
       <span class="dismiss" :data-toast="toast.id">
         <ui-icon-button size="sm" variant="ghost" :round="true" :label="format('Dismiss %s', toast.message)">
-          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true">
-            <path d="M18 6 6 18M6 6l12 12"></path>
-          </svg>
+          <ui-icon name="x"></ui-icon>
         </ui-icon-button>
       </span>
     </div>
   </div>
   <style>
     /* This component's hooks style the element they are set on, and never a nested one. */
+    @property --ui-toast-region-surface {
+      syntax: "*";
+      inherits: false;
+    }
+    @property --ui-toast-region-border {
+      syntax: "*";
+      inherits: false;
+    }
+    @property --ui-toast-region-radius {
+      syntax: "*";
+      inherits: false;
+    }
+    @property --ui-toast-region-shadow {
+      syntax: "*";
+      inherits: false;
+    }
     @property --ui-toast-region-enter-duration {
       syntax: "*";
       inherits: false;
@@ -41,6 +54,10 @@
 
     :host {
       /* Hooks do not inherit, so the parts below read them from the root. */
+      --_ui-toast-region-surface: var(--ui-toast-region-surface);
+      --_ui-toast-region-border: var(--ui-toast-region-border);
+      --_ui-toast-region-radius: var(--ui-toast-region-radius);
+      --_ui-toast-region-shadow: var(--ui-toast-region-shadow);
       --_ui-toast-region-enter-duration: var(--ui-toast-region-enter-duration);
       --_ui-toast-region-exit-duration: var(--ui-toast-region-exit-duration);
 
@@ -70,6 +87,29 @@
       display: none;
     }
 
+    :host-state([placement="top-start"]),
+    :host-state([placement="bottom-start"]) {
+      left: auto;
+      right: auto;
+      inset-inline-start: calc(var(--ui-space-4) + env(safe-area-inset-left));
+      transform: none;
+    }
+
+    :host-state([placement="top-end"]),
+    :host-state([placement="bottom-end"]) {
+      left: auto;
+      right: auto;
+      inset-inline-end: calc(var(--ui-space-4) + env(safe-area-inset-right));
+      transform: none;
+    }
+
+    :host-state([placement="bottom"]),
+    :host-state([placement="bottom-start"]),
+    :host-state([placement="bottom-end"]) {
+      top: auto;
+      bottom: calc(var(--ui-space-4) + env(safe-area-inset-bottom));
+    }
+
     :host > .toast,
     :host > :slotted(*) {
       pointer-events: auto;
@@ -80,21 +120,42 @@
       grid-template-columns: 1fr auto;
       gap: var(--ui-space-2);
       align-items: start;
-      border: 1px solid var(--ui-border-default);
-      border-radius: var(--ui-radius-lg);
+      border: 1px solid var(--_ui-toast-region-border, var(--ui-overlay-border, var(--ui-border-default)));
+      border-radius: var(--_ui-toast-region-radius, var(--ui-overlay-radius, var(--ui-radius-lg)));
       padding: var(--ui-space-3) var(--ui-space-4);
-      background: var(--ui-surface-elevated);
+      background: var(--_ui-toast-region-surface, var(--ui-overlay-surface, var(--ui-surface-elevated)));
       color: var(--ui-text-primary);
-      box-shadow: var(--ui-elevation-overlay, var(--ui-shadow-lg));
+      box-shadow: var(--_ui-toast-region-shadow, var(--ui-overlay-shadow, var(--ui-elevation-overlay, var(--ui-shadow-lg))));
       animation: ui-toast-enter var(--_ui-toast-region-enter-duration, 0.32s) var(--ui-motion-ease-out, cubic-bezier(0.16, 1, 0.3, 1)) both;
     }
 
+    .toast[data-tone="info"] {
+      border-inline-start: 3px solid var(--ui-info-solid);
+    }
+    .toast[data-tone="success"] {
+      border-inline-start: 3px solid var(--ui-success-solid);
+    }
+    .toast[data-tone="warning"] {
+      border-inline-start: 3px solid var(--ui-warning-solid);
+    }
+    .toast[data-tone="danger"] {
+      border-inline-start: 3px solid var(--ui-danger-solid);
+    }
+
     /* Leaving slides on down and fades; the controller removes the toast when this ends. */
     .toast.closing {
       animation: ui-toast-exit var(--_ui-toast-region-exit-duration, 0.22s) var(--ui-motion-ease) both;
       pointer-events: none;
     }
 
+    :is(:host-state([placement="bottom"]), :host-state([placement="bottom-start"]), :host-state([placement="bottom-end"])) .toast {
+      animation-name: ui-toast-enter-bottom;
+    }
+
+    :is(:host-state([placement="bottom"]), :host-state([placement="bottom-start"]), :host-state([placement="bottom-end"])) .toast.closing {
+      animation-name: ui-toast-exit-bottom;
+    }
+
     @keyframes ui-toast-enter {
       from {
         opacity: 0;
@@ -117,6 +178,28 @@
       }
     }
 
+    @keyframes ui-toast-enter-bottom {
+      from {
+        opacity: 0;
+        transform: translateY(1rem);
+      }
+      to {
+        opacity: 1;
+        transform: translateY(0);
+      }
+    }
+
+    @keyframes ui-toast-exit-bottom {
+      from {
+        opacity: 1;
+        transform: translateY(0);
+      }
+      to {
+        opacity: 0;
+        transform: translateY(-0.75rem);
+      }
+    }
+
     @media (prefers-reduced-motion: reduce) {
       .toast, .toast.closing {
         animation: none;

package/components/ui-toast-region/ui-toast-region.js

@@ -8,19 +8,16 @@ export async function show(host, message, options = {}) {
 }
 
 /**
- * Shows the region while `open` is set and it has authored messages, or while any message added
- * with show() or the --show-toast command remains. Added messages dismiss by action or timeout.
+ * Shows the region while it has authored or generated messages. Generated messages dismiss by
+ * action or timeout; authored ui-toast children own their removal through the dismiss event.
  */
 export default function controller(host) {
   const element = host.element;
   const [trigger, stopTracking] = trackTrigger(host);
-  let external = host.state.open;
-  host.state.internalOpen = Boolean(external);
-
   const toasts = () => host.state.toasts ?? [];
   const authored = () => Array.from(element.children).some((child) => !child.classList.contains("toast"));
   const sync = () => {
-    const visible = (host.state.internalOpen && authored()) || toasts().length > 0;
+    const visible = authored() || toasts().length > 0;
     if (visible && !element.matches(":popover-open")) element.showPopover();
     else if (!visible && element.matches(":popover-open")) element.hidePopover();
   };
@@ -59,7 +56,6 @@ export default function controller(host) {
     if (!toast || toast.closing) return;
     host.state.toasts = toasts().map((candidate) => candidate.id === id ? { ...candidate, closing: true } : candidate);
     host.dispatch("dismiss", { id, reason, trigger: how });
-    if (toasts().every((candidate) => candidate.closing)) host.dispatch("close", { open: false, reason, trigger: how });
     // Removed once the exit animation ends; reduced motion has none, and the timeout guards a missed end.
     const node = element.ownerDocument.getElementById(id);
     if (!node || getComputedStyle(node).animationName === "none") remove(id);
@@ -70,9 +66,11 @@ export default function controller(host) {
   };
   const add = (message, options = {}) => {
     const id = String(options.id || `ui-toast-${++toastIds}`);
-    host.state.toasts = [...toasts(), { id, message: String(message), role: options.tone === "danger" ? "alert" : "status", closing: false }];
-    if (options.auto ?? host.state.auto) {
-      timers.set(id, { remaining: Math.max(0, Number(options.duration ?? host.state.duration ?? 5000)), started: 0, handle: 0 });
+    const tone = ["neutral", "info", "success", "warning", "danger"].includes(options.tone) ? options.tone : "neutral";
+    host.state.toasts = [...toasts(), { id, message: String(message), tone, role: tone === "danger" ? "alert" : "status", closing: false }];
+    const duration = Math.max(0, Number(options.duration ?? host.state.duration ?? 0));
+    if (duration > 0) {
+      timers.set(id, { remaining: duration, started: 0, handle: 0 });
       startTimer(id);
     }
     return id;
@@ -83,15 +81,9 @@ export default function controller(host) {
     if (id) dismiss(id, "action", trigger());
   };
   const onCommand = (event) => {
-    if (event.command === "--show-toast") add(event.source?.value || host.state.message || "Notification");
+    if (event.command === "--show-toast" && event.source?.value) add(event.source.value);
   };
-  const stop = host.effect(() => {
-    if (host.state.open !== external) {
-      external = host.state.open;
-      host.state.internalOpen = Boolean(external);
-    }
-    sync();
-  });
+  const stop = host.effect(sync);
   const observer = new MutationObserver(sync);
   observer.observe(element, { childList: true });
   element.addEventListener("click", onClick);

package/components/ui-tooltip/ui-tooltip.html

@@ -2,7 +2,11 @@
   <defs>
     <prop name="for" type="string" default="">ID of the control described and visually anchored by the tooltip.</prop>
     <prop name="open" type="boolean" default="false">Whether the tooltip is open initially or when set externally.</prop>
-    <prop name="placement" type="string" default="top-start">Positions the description relative to its trigger.</prop>
+    <prop
+      name="placement"
+      type="top | top-start | top-end | bottom | bottom-start | bottom-end | left | left-start | left-end | right | right-start | right-end"
+      default="top"
+    >Positions the description around its trigger. Start and end on top or bottom follow the writing direction.</prop>
     <prop name="trigger" type="hover | click | focus" default="hover"
     >How the trigger opens it. hover also opens on keyboard focus; click toggles it and suits a help button, where hovering a question mark says nothing; focus
       opens only while the trigger holds focus.</prop>
@@ -42,6 +46,10 @@
       syntax: "*";
       inherits: false;
     }
+    @property --ui-tooltip-offset {
+      syntax: "*";
+      inherits: false;
+    }
     @property --ui-tooltip-radius {
       syntax: "*";
       inherits: false;
@@ -93,19 +101,19 @@
     }
 
     .surface {
-      --_tooltip-line: var(--_ui-tooltip-border, var(--ui-border-default));
+      --_tooltip-line: var(--_ui-tooltip-border, var(--ui-overlay-border, var(--ui-border-default)));
       position: relative;
       box-sizing: border-box;
       max-inline-size: var(--_ui-tooltip-max-inline-size, 18rem);
       border: 1px solid var(--_tooltip-line);
-      border-radius: var(--_ui-tooltip-radius, var(--ui-radius-sm));
-      background: var(--_ui-tooltip-surface, var(--ui-surface-elevated));
+      border-radius: var(--_ui-tooltip-radius, var(--ui-overlay-radius, var(--ui-radius-sm)));
+      background: var(--_ui-tooltip-surface, var(--ui-overlay-surface, var(--ui-surface-elevated)));
       color: var(--_ui-tooltip-text, var(--ui-text-primary));
       padding: var(--ui-space-1) var(--ui-space-2);
       font-family: var(--ui-font-family-sans);
       font-size: var(--ui-font-size-sm);
       line-height: var(--ui-line-height-tight);
-      box-shadow: var(--_ui-tooltip-shadow, var(--ui-elevation-tooltip, var(--ui-shadow-md)));
+      box-shadow: var(--_ui-tooltip-shadow, var(--ui-overlay-shadow, var(--ui-elevation-tooltip, var(--ui-shadow-md))));
     }
 
     :host-state([inverse]) .surface {
@@ -133,7 +141,7 @@
       transform: rotate(45deg);
     }
 
-    :is(:host-state([placement="bottom"]), :host-state([placement="bottom-start"]), :host-state([placement="bottom-end"])) .surface::after {
+    :host[data-ui-actual-placement="bottom"] .surface::after {
       inset-block-start: calc(var(--_ui-tooltip-arrow-size, 0.5rem) / -2 - 0.5px);
       inset-block-end: auto;
       border-inline-end-width: 0;
@@ -144,11 +152,47 @@
       border-start-start-radius: 1px;
     }
 
-    :is(:host-state([placement="top-end"]), :host-state([placement="bottom-end"])) .surface::after {
+    :host[data-ui-actual-align="center"] .surface::after {
+      inset-inline-start: calc(50% - var(--_ui-tooltip-arrow-size, 0.5rem) / 2);
+    }
+
+    :host[data-ui-actual-align="end"] .surface::after {
       inset-inline-start: auto;
       inset-inline-end: var(--ui-space-3);
     }
 
+    :host[data-ui-actual-placement="left"] .surface::after,
+    :host[data-ui-actual-placement="right"] .surface::after {
+      inset-block-start: calc(50% - var(--_ui-tooltip-arrow-size, 0.5rem) / 2);
+      inset-block-end: auto;
+      border: 0 solid var(--_tooltip-line);
+    }
+
+    :host[data-ui-actual-placement="left"] .surface::after {
+      inset-inline-start: auto;
+      inset-inline-end: calc(var(--_ui-tooltip-arrow-size, 0.5rem) / -2 - 0.5px);
+      border-inline-end-width: 1px;
+      border-block-end-width: 1px;
+    }
+
+    :host[data-ui-actual-placement="right"] .surface::after {
+      inset-inline-start: calc(var(--_ui-tooltip-arrow-size, 0.5rem) / -2 - 0.5px);
+      inset-inline-end: auto;
+      border-inline-start-width: 1px;
+      border-block-start-width: 1px;
+    }
+
+    :host[data-ui-actual-placement="left"][data-ui-actual-align="start"] .surface::after,
+    :host[data-ui-actual-placement="right"][data-ui-actual-align="start"] .surface::after {
+      inset-block-start: var(--ui-space-3);
+    }
+
+    :host[data-ui-actual-placement="left"][data-ui-actual-align="end"] .surface::after,
+    :host[data-ui-actual-placement="right"][data-ui-actual-align="end"] .surface::after {
+      inset-block-start: auto;
+      inset-block-end: var(--ui-space-3);
+    }
+
     :host:popover-open {
       opacity: 1;
       transform: translateY(0);

package/components/ui-tooltip/ui-tooltip.js

@@ -1,8 +1,30 @@
 import { closeOverlay, createAnchoredSurface, createIdResolver, openOverlay } from "../shared/overlay.js";
 
+const warmTooltips = new WeakMap();
+
 export default function controller(host) {
   const element = host.element;
   const document = element.ownerDocument;
+  const warm = warmTooltips.get(document) ?? { active: 0, until: 0 };
+  warmTooltips.set(document, warm);
+  let counted = false;
+  const trackVisible = (visible) => {
+    if (counted === visible) return;
+    counted = visible;
+    if (visible) warm.active += 1;
+    else {
+      warm.active = Math.max(0, warm.active - 1);
+      warm.until = Date.now() + 400;
+    }
+  };
+  const offset = () => {
+    const value = getComputedStyle(element).getPropertyValue("--ui-tooltip-offset").trim();
+    const amount = Number.parseFloat(value);
+    if (!Number.isFinite(amount)) return 4;
+    if (value.endsWith("rem")) return amount * Number.parseFloat(getComputedStyle(document.documentElement).fontSize);
+    if (value.endsWith("em")) return amount * Number.parseFloat(getComputedStyle(element).fontSize);
+    return amount;
+  };
   const overlayId = element.id || `ui-tooltip-${Math.random().toString(36).slice(2, 11)}`;
   if (!element.id) element.id = overlayId;
   let focused = false;
@@ -21,6 +43,7 @@ export default function controller(host) {
   const setOpen = (open, input) => {
     if (Boolean(host.state.internalOpen) === open) return;
     host.state.internalOpen = open;
+    trackVisible(open);
     if (trigger && host.state.trigger === "click") trigger.setAttribute("aria-expanded", String(open));
     host.dispatch(open ? "open" : "close", { open, reason: "action", trigger: input });
   };
@@ -37,7 +60,7 @@ export default function controller(host) {
     showTimer = setTimeout(() => {
       showTimer = null;
       setOpen(true, "pointer");
-    }, Math.max(0, Number(host.state.showDelay ?? 500)));
+    }, warm.active > 0 || warm.until > Date.now() ? 0 : Math.max(0, Number(host.state.showDelay ?? 500)));
   };
   const onLeave = () => {
     clearShow();
@@ -101,7 +124,7 @@ export default function controller(host) {
   });
   const setup = () => {
     const nextFor = String(host.state.for ?? "");
-    const nextPlacement = String(host.state.placement ?? "top-start");
+    const nextPlacement = String(host.state.placement ?? "top");
     if (surface && nextFor === lastFor && nextPlacement === lastPlacement) return;
     lastFor = nextFor;
     lastPlacement = nextPlacement;
@@ -112,12 +135,13 @@ export default function controller(host) {
       attach();
     }
     surface?.destroy();
-    surface = createAnchoredSurface(element, { anchor: trigger, placement: nextPlacement });
+    surface = createAnchoredSurface(element, { anchor: trigger, placement: nextPlacement, gap: offset });
   };
   const close = (reason, input) => {
     if (reason !== "escape" && reason !== "light-dismiss") return;
     clearTimers();
     host.state.internalOpen = false;
+    trackVisible(false);
     host.dispatch("close", { open: false, reason, trigger: input });
   };
   const apply = () => {
@@ -128,6 +152,7 @@ export default function controller(host) {
     }
     setup();
     const open = Boolean(host.state.internalOpen);
+    trackVisible(open);
     element.hidden = !open;
     if (open) {
       surface?.show();
@@ -146,6 +171,7 @@ export default function controller(host) {
     stop();
     ids.stop();
     clearTimers();
+    trackVisible(false);
     detach();
     surface?.destroy();
     element.removeEventListener("pointerenter", onSurfaceEnter);

package/components/ui-tree/ui-tree.html

@@ -3,6 +3,9 @@
   <defs>
     <prop name="density" type="comfortable | compact" default="comfortable">Compact trades padding and type size for rows that fit more on screen.</prop>
     <prop name="label" type="string" default="Tree">The tree's accessible name, announced when focus enters it. Name what the tree holds.</prop>
+    <prop name="selection" type="none | single | multiple" default="none"
+    >How selection works. None keeps rows for navigation and expansion; single requests one selected item; multiple shows checkboxes and requests an item with
+      its descendants. The application owns each Tree Item's selected state and responds to select.</prop>
     <prop name="hoverExpandDelay" type="number" default="700"
     >How long, in milliseconds, a dragged item must hover over the middle of a collapsed branch before the branch opens to receive it. 0 opens it at
       once.</prop>
@@ -20,6 +23,7 @@
       name="reorder-rejected"
       type="object({ sourceId: string, targetId: string, position: before | inside | after, reason: max-depth, maxDepth: integer, resultingDepth: integer, trigger: keyboard | pointer | programmatic })"
     ></event>
+    <event name="select" type="object({ ids: list(string), trigger: keyboard | pointer | programmatic })"></event>
   </defs>
   <div role="tree"><slot></slot></div>
   <style>
@@ -64,6 +68,14 @@
       padding-inline-start: var(--ui-tree-gutter, 0px);
     }
 
+    :host[data-move-mode]::after {
+      content: "Choose a destination row, or use Up and Down; Right nests inside a branch. Enter places it, Escape cancels.";
+      display: block;
+      padding: var(--ui-space-2);
+      color: var(--ui-text-secondary);
+      font-size: var(--ui-font-size-sm);
+    }
+
     /* A component that sets its display still honours the hidden attribute on its root. */
     :host[hidden] {
       display: none;