actual-css 0.6.0 → 0.8.0

package/src/js/tooltip.js

@@ -25,11 +25,24 @@
  *
  * Show:       hover + focus (150ms delay), click toggle, or always visible
  * Hide:       blur, pointer leave, Escape
+ *
+ * Geometry:   a trigger scrolled out of the positioning boundary takes its tip
+ *             down and keeps it tracked, so scrolling back brings the same tip
+ *             up again with no second hover or tap.
+ *
+ * Coordinates: viewport by default, document coordinates whenever the trigger
+ *             scrolls with the page. See positionModeFor().
+ *
+ * Transport:  the top layer, via popover="manual", written by the runtime on
+ *             every tip it manages. A .tooltip[popover] with no data-tooltip
+ *             trigger pointing at it is never reached from here and stays the
+ *             application's own to drive.
  */
 
+import { autoUpdate, reposition } from "@lekoala/floating";
 import enhance from "./enhance.js";
 import { registerEscapeDismissal } from "./escape.js";
-import { autoUpdate, reposition } from "./floating.js";
+import { positionModeFor } from "./floating-space.js";
 import { CLASSES } from "./selectors.js";
 
 const SHOW_DELAY_MS = 150;
@@ -40,11 +53,14 @@ const HIDE_DELAY_MS = 100;
  * @property {Set<Element>} refs Triggers that currently reference this tip.
  * @property {Element | null} activeRef Trigger that last showed this tip.
  * @property {AbortController} controller Tip-level event listener cleanup.
- * @property {(() => void) | null} stopTracking Floating-position cleanup while visible.
+ * @property {(() => void) | null} stopTracking Floating-position cleanup while wanted.
+ * @property {Element | null} trackedRef Reference the current subscription observes.
  * @property {(() => void) | null} unregisterEscape Escape-stack cleanup while visible and dismissable.
  * @property {Element | null} escapeRef Trigger represented by the current Escape-stack entry.
  * @property {boolean} generated True when the tip was created from data-tooltip text.
- * @property {{ parent: Node, next: ChildNode | null } | null} mount Original DOM position for explicit tips moved into a dialog/body root.
+ * @property {boolean} wanted True while the interaction asks for this tip, positionable or not.
+ * @property {boolean} visible True while the tip is promoted to the top layer.
+ * @property {"viewport" | "document"} space Coordinate space the tip is written in.
  * @property {ReturnType<typeof setTimeout> | null} timer Pending delayed show.
  * @property {ReturnType<typeof setTimeout> | null} hideTimer Pending delayed hide.
  * @property {boolean} hovered Pointer is over the active trigger.
@@ -55,30 +71,69 @@ const HIDE_DELAY_MS = 100;
 let uid = 0;
 const triggerStates = new WeakMap(); // trigger -> { tip, cleanup }
 /** @type {WeakMap<Element, TooltipState>} */
-const tipStates = new WeakMap(); // tip -> { refs, activeRef, controller, stopTracking, generated, mount, timer }
+const tipStates = new WeakMap(); // tip -> { refs, activeRef, controller, stopTracking, generated, visible, timer }
 
-function mountTip(tip, trigger) {
-  const root = trigger.closest("dialog") || trigger.ownerDocument.body;
-  const parent = tip.parentNode;
-  if (!root || !parent || parent === root) return null;
+/*
+ * Transport, the same shape surface.js uses and for the same reason: the
+ * platform promotes the tip to the top layer and does nothing else, leaving
+ * the hover/focus/click policy, the show delays and the Escape ordering here
+ * untouched. showPopover/hidePopover throw on an out-of-order call, which the
+ * state below should already have excluded — the try/catch is there so a
+ * surprising DOM does not take the lifecycle down with it.
+ */
+function showTransport(tip) {
+  try {
+    tip.showPopover();
+    return true;
+  } catch {
+    return false;
+  }
+}
 
-  const mount = { parent, next: tip.nextSibling };
-  root.append(tip);
-  return mount;
+function hideTransport(tip) {
+  try {
+    tip.hidePopover();
+  } catch {
+    /* Already closed or detached; nothing left to hide. */
+  }
 }
 
-function restoreTip(tip, state) {
-  const mount = state.mount;
-  if (!mount) return;
+/*
+ * [hidden] stops being the runtime's state here and goes back to what the
+ * author wrote: the state before enhancement. Wiring is lazy, so an explicit
+ * tip that is never hovered keeps it for the whole life of the page — which
+ * is why .tooltip[hidden] has to stay in the CSS. The runtime strips it only
+ * at the moment it takes the lifecycle over, because an author declaration
+ * outranks the platform's own hidden state for a closed popover.
+ */
+function prepareTip(tip) {
+  tip.style.position = "fixed";
+  tip.removeAttribute("hidden");
+  tip.setAttribute("popover", "manual");
+}
 
-  if (mount.parent.isConnected) {
-    const next = mount.next?.parentNode === mount.parent ? mount.next : null;
-    mount.parent.insertBefore(tip, next);
-  } else {
-    tip.remove();
-  }
+/** True while the tip is promoted. The runtime's state, not :popover-open. */
+export function isTooltipVisible(tip) {
+  return tipStates.get(tip)?.visible === true;
 }
 
+/*
+ * Coordinate space, resolved once per shown tip.
+ *
+ * The engine always measures in viewport coordinates; the space only decides
+ * what gets written. Document coordinates let the browser scroll the tip along
+ * with the page, so it stays attached during touch scrolling instead of
+ * trailing its trigger until the next autoUpdate() frame. That holds only
+ * while the trigger scrolls with the page too: against a viewport-anchored
+ * trigger the browser would carry the tip away on every scroll and each update
+ * would snap it back, which is worse than the lag it removes.
+ *
+ * Which is why this asks about the trigger, not about the tip. An open popover
+ * is in the top layer, where an absolutely positioned box resolves against the
+ * initial containing block whatever its ancestors do — measured for
+ * position: relative, transform, filter, contain and both dialog modes — so
+ * the tip's own placement never enters into it.
+ */
 function placementFor(ref) {
   return ref?.getAttribute("data-tooltip-placement") || "top";
 }
@@ -134,46 +189,70 @@ function nextTooltipId(doc) {
   return id;
 }
 
-function repositionTip(ref, tip) {
+function repositionTip(ref, tip, space) {
   return reposition(ref, tip, {
     placement: placementFor(ref),
     distance: 6,
     flip: true,
     shift: true,
+    coordinateSpace: space,
   });
 }
 
+/*
+ * One update, from show() or from a tracking tick.
+ *
+ * Two separate notions, deliberately: `wanted` is what the interaction asks
+ * for — hover, focus, a click toggle, data-tooltip-visible — and `visible` is
+ * what is actually promoted. They come apart whenever the trigger leaves the
+ * positioning boundary, because reposition() returning false means "not
+ * positionable right now", not "the interaction is over": the tip goes down
+ * and its tracking stays, so scrolling the trigger back into view brings the
+ * same tip up again with no second hover or tap. Only hideTip() ends a tip.
+ *
+ * A closed popover has no box to measure, so the tip has to be promoted
+ * before it can be positioned, and demoted again when that fails.
+ */
 function updateTrackedTip(tip, state) {
   const ref = state.activeRef;
-  if (!ref) return;
-
-  const alwaysVisible = isAlwaysVisible(ref);
-  // Reveal before measuring: an always-visible tooltip may currently be
-  // hidden because its trigger was outside the positioning boundary.
-  if (alwaysVisible) tip.hidden = false;
-  if (tip.hidden || repositionTip(ref, tip)) {
-    syncEscapeDismissal(tip, state);
-    return;
+  if (!ref || !state.wanted) return;
+
+  if (!state.visible) {
+    if (!showTransport(tip)) return;
+    state.visible = true;
   }
 
-  if (alwaysVisible) tip.hidden = true;
-  else hideTip(tip, true);
+  if (!repositionTip(ref, tip, state.space)) {
+    state.visible = false;
+    hideTransport(tip);
+  }
+  syncEscapeDismissal(tip, state);
 }
 
+// A subscription observes one reference, so a shared tip re-shown from another
+// trigger has to resubscribe — tracking now outlives a demoted tip, and would
+// otherwise keep watching the trigger that is no longer active.
 function startTracking(tip, state) {
-  if (state.stopTracking) return;
+  if (state.stopTracking) {
+    if (state.trackedRef === state.activeRef) return;
+    stopTracking(state);
+  }
 
-  state.stopTracking = autoUpdate(tip, () => updateTrackedTip(tip, state));
+  state.trackedRef = state.activeRef;
+  state.stopTracking = autoUpdate(state.activeRef, tip, () => updateTrackedTip(tip, state));
 }
 
 function stopTracking(state) {
   state?.stopTracking?.();
-  if (state) state.stopTracking = null;
+  if (state) {
+    state.stopTracking = null;
+    state.trackedRef = null;
+  }
 }
 
 function syncEscapeDismissal(tip, state) {
   const ref = state.activeRef;
-  const dismissable = !tip.hidden && !isAlwaysVisible(ref);
+  const dismissable = state.visible && !isAlwaysVisible(ref);
   // Position tracking calls this after every successful update. Preserve the
   // current entry so a scroll/resize tick cannot reorder the LIFO stack.
   if (dismissable && state.unregisterEscape && state.escapeRef === ref) return;
@@ -198,7 +277,11 @@ function hideTip(tip, force = false) {
     clearTimeout(state.hideTimer);
     state.hideTimer = null;
   }
-  tip.hidden = true;
+  if (state) {
+    state.wanted = false;
+    state.visible = false;
+  }
+  hideTransport(tip);
   state?.unregisterEscape?.();
   if (state) {
     state.unregisterEscape = null;
@@ -239,10 +322,13 @@ function wireTip(tip, options = {}) {
     activeRef: null,
     controller,
     stopTracking: null,
+    trackedRef: null,
     unregisterEscape: null,
     escapeRef: null,
     generated: options.generated === true,
-    mount: options.mount || null,
+    wanted: false,
+    visible: false,
+    space: "viewport",
     timer: null,
     hideTimer: null,
     hovered: false,
@@ -277,7 +363,6 @@ function ensureTip(trigger) {
 
   let tip;
   let generated = false;
-  let mount = null;
   let descriptionAdded = false;
   const text = trigger.getAttribute("data-tooltip");
   const doc = trigger.ownerDocument;
@@ -289,12 +374,25 @@ function ensureTip(trigger) {
     tip.role = "tooltip";
     tip.id = nextTooltipId(doc);
     tip.textContent = text;
-    tip.hidden = true;
-    tip.style.position = "fixed";
     generated = true;
 
+    /*
+     * A generated tip is Actual's to place, so the placement has to be
+     * structurally neutral — not trigger.after(). Structural pseudo-classes
+     * are DOM-based and position: fixed does not exempt a generated sibling
+     * from :last-child, so it would take `.join > :last-child` from the
+     * trigger and drop the group's trailing corner. The shorthand therefore
+     * promises no inheritance; authors who need a local theme, density or
+     * custom property use the explicit form, which stays where they wrote it.
+     *
+     * The dialog hop is not geometry any more — the top layer handles that.
+     * It is inertness: a modal dialog inerts the rest of the document, and
+     * promotion does not lift an element out of that, because inertness is
+     * computed on the DOM and not on paint order.
+     */
     const parent = trigger.closest("dialog") || doc.body;
     parent.appendChild(tip);
+    prepareTip(tip);
     descriptionAdded = addDescription(trigger, tip.id);
   }
 
@@ -302,16 +400,14 @@ function ensureTip(trigger) {
   if (!tip) {
     tip = explicitTipFor(trigger);
     if (!tip) return null;
-    // Wire and mount the shared tip only on first retain. A later trigger
-    // must not re-hide a tooltip that is currently visible for another.
-    if (!tipStates.has(tip)) {
-      tip.hidden = true;
-      tip.style.position = "fixed";
-      mount = mountTip(tip, trigger);
-    }
+    // Wire the shared tip only on first retain. A later trigger must not
+    // re-hide a tooltip that is currently visible for another.
+    // It is not moved: an explicit tip is author-placed, so it keeps every
+    // scope that reaches it by inheritance.
+    if (!tipStates.has(tip)) prepareTip(tip);
   }
 
-  const state = wireTip(tip, { generated, mount });
+  const state = wireTip(tip, { generated });
   state.refs.add(trigger);
 
   const triggerController = new AbortController();
@@ -349,8 +445,8 @@ function ensureTip(trigger) {
     state.controller.abort();
     stopTracking(state);
     tipStates.delete(tip);
+    // An explicit tip is left exactly where the author wrote it, closed.
     if (state.generated) tip.remove();
-    else restoreTip(tip, state);
   };
 
   triggerStates.set(trigger, { tip, cleanup });
@@ -368,12 +464,15 @@ function show(tip, ref, immediate = false) {
   if (!state) return;
 
   state.activeRef = ref;
+  const mode = positionModeFor(ref);
+  state.space = mode.space;
+  tip.style.position = mode.position;
   syncEscapeDismissal(tip, state);
   clearHide(tip);
   if (state.timer) clearTimeout(state.timer);
   const reveal = () => {
     state.timer = null;
-    tip.hidden = false;
+    state.wanted = true;
     startTracking(tip, state);
     updateTrackedTip(tip, state);
   };
@@ -414,8 +513,8 @@ function handleTriggerClick(e) {
   if (!tip) return;
 
   e.preventDefault();
-  if (tip.hidden) show(tip, trigger, true);
-  else hideTip(tip, true);
+  if (isTooltipVisible(tip)) hideTip(tip, true);
+  else show(tip, trigger, true);
 }
 
 // Delegated discovery listeners run at import time; keep SSR imports inert.

package/src/js/validation.js

@@ -367,7 +367,7 @@ export class FormValidator {
     rules[name] = callback;
   }
 
-  static init(selector = VALIDATION_SELECTOR) {
+  static init(selector = `form${VALIDATION_SELECTOR}`) {
     if (typeof document === "undefined") return;
     for (const form of document.querySelectorAll(selector)) {
       if (isFormElement(form)) connectForm(form);

package/src/css/components/surface.css

@@ -1,49 +0,0 @@
-/*
- * Surface — shared modal scrim and backdrop for flyout and drawer.
- *
- * Drawn by .drawer::backdrop (native dialog top-layer) and .surface-backdrop
- * (custom fixed div for flyout sheets on coarse pointers). The native
- * .modal::backdrop uses the same fill and animates opacity from 0 to 1
- * (modal.css), so the scrim strength stays consistent across the dialog
- * family.
- *
- * .surface-backdrop, .is-sheet, and .is-open are runtime markers set by
- * surface.js. Authors opt in via [data-flyout-mobile="sheet|auto|none|anchored"]
- * — the JS resolves "auto" into .is-sheet at run time.
- */
-/* Custom backdrop for overlays that do not use the native dialog top-layer.
- * Its z-index sits just below the flyout it accompanies. */
-.surface-backdrop {
-  position: fixed;
-  inset: 0;
-  z-index: calc(var(--z-menu) - 1);
-  background: var(--backdrop-fill);
-  opacity: 1;
-  /* A scrim never travels; it fades on the neutral `ease`. Duration matches
-     the flyout sheet it accompanies so it never lags the panel. */
-  transition: opacity var(--duration-fast) ease;
-}
-
-.surface-backdrop[hidden] {
-  display: none;
-  opacity: 0;
-}
-
-@starting-style {
-  .surface-backdrop:not([hidden]) {
-    opacity: 0;
-  }
-}
-
-@supports (transition-behavior: allow-discrete) {
-  .surface-backdrop {
-    transition:
-      opacity var(--duration-fast) ease,
-      display var(--duration-fast) allow-discrete;
-  }
-}
-@media print {
-  .surface-backdrop {
-    display: none !important;
-  }
-}