actual-css 0.9.2 → 0.10.0

package/src/css/utilities/extra.css

@@ -1,7 +1,7 @@
 /*
- * Optional utility helpers.
- *
- * These classes are intentionally not part of the core API.
+ * Extra utility helpers — explicit property/value names beside the curated
+ * shortcuts of base.css. Both are imported by utilities/index.css and are
+ * equally public (docs/design-notes/naming.md § Utilities).
  * They are escape hatches for layout nudges, not a full atomic scale.
  *
  * Core principle:
@@ -177,8 +177,9 @@
   overflow-y: auto;
 }
 
-/* Text */
-.white-space-normal {
+/* Text. .text-wrap is the counterpart of base's .text-nowrap: it restores
+   wrapping inside a component that sets nowrap (.badge). */
+.text-wrap {
   white-space: normal;
 }
 
@@ -251,7 +252,7 @@
 /* Surface. These are semantic surfaces, not arbitrary paint: each owns its
    matching ink and rebinds --heading to that ink, so it stays readable when it
    recreates a light surface inside a context that installed a dark one
-   (.inverted). Intent ink is not inherited through a surface utility; use
+   (e.g. a --surface-solid band). Intent ink is not inherited through a surface utility; use
    .intent-color for that. */
 .background-surface {
   --heading: currentColor;

package/src/js/dialog.js

@@ -24,7 +24,7 @@
  *
  * The runtime assumes native <dialog> with show()/showModal()/close() — the
  * Minimal browser tier. requestClose() is newer than the floor and is used
- * when present, falling back to close() otherwise.
+ * when present, falling back to a cancel event before close() otherwise.
  */
 
 import { registerCommands, targetFor } from "./command.js";
@@ -48,34 +48,69 @@ function boolData(el, name) {
   return el.hasAttribute(name) && el.getAttribute(name) !== "false";
 }
 
-function ensureId(el, prefix) {
+function setOwnedAttribute(state, el, name, value) {
+  const current = el.getAttribute(name);
+  if (current === value) return;
+
+  const previous = state.ownedAttributes.find((entry) => entry.el === el && entry.name === name);
+  if (previous && current !== previous.written) previous.original = current;
+  if (value === null) el.removeAttribute(name);
+  else el.setAttribute(name, value);
+
+  if (previous) previous.written = value;
+  else state.ownedAttributes.push({ el, name, original: current, written: value });
+}
+
+function restoreOwnedAttributes(state) {
+  for (const { el, name, original, written } of state.ownedAttributes) {
+    // An author may have changed an attribute while the dialog was connected.
+    if (el.getAttribute(name) !== written) continue;
+    if (original === null) el.removeAttribute(name);
+    else el.setAttribute(name, original);
+  }
+}
+
+function ensureId(el, prefix, state) {
   if (!el.id) {
     uid++;
-    el.id = `${prefix}-${uid}`;
+    setOwnedAttribute(state, el, "id", `${prefix}-${uid}`);
   }
   return el.id;
 }
 
-function syncDialogSemantics(dialog, modal = isModal(dialog)) {
-  if (modal) {
-    dialog.setAttribute("aria-modal", "true");
-  } else {
-    dialog.removeAttribute("aria-modal");
-  }
+function ownsCurrentAttribute(state, el, name) {
+  return state.ownedAttributes.some(
+    (entry) => entry.el === el && entry.name === name && el.getAttribute(name) === entry.written,
+  );
+}
 
-  if (dialog.hasAttribute("aria-label") || dialog.hasAttribute("aria-labelledby")) {
+function syncDialogSemantics(dialog, state, modal = isModal(dialog)) {
+  setOwnedAttribute(state, dialog, "aria-modal", modal ? "true" : null);
+
+  const ownsLabel = ownsCurrentAttribute(state, dialog, "aria-label");
+  const ownsLabelledby = ownsCurrentAttribute(state, dialog, "aria-labelledby");
+  if (dialog.hasAttribute("aria-labelledby") && !ownsLabelledby) {
+    if (ownsLabel) setOwnedAttribute(state, dialog, "aria-label", null);
+    return;
+  }
+  if (dialog.hasAttribute("aria-label") && !ownsLabel) {
+    if (ownsLabelledby) setOwnedAttribute(state, dialog, "aria-labelledby", null);
     return;
   }
 
   const label = dialog.getAttribute("data-title")?.trim();
   if (label) {
-    dialog.setAttribute("aria-label", label);
+    if (ownsLabelledby) setOwnedAttribute(state, dialog, "aria-labelledby", null);
+    setOwnedAttribute(state, dialog, "aria-label", label);
     return;
   }
 
   const title = dialog.querySelector(DIALOG_TITLE_SELECTOR);
+  if (ownsLabel) setOwnedAttribute(state, dialog, "aria-label", null);
   if (title) {
-    dialog.setAttribute("aria-labelledby", ensureId(title, "dialog-title"));
+    setOwnedAttribute(state, dialog, "aria-labelledby", ensureId(title, "dialog-title", state));
+  } else if (ownsLabelledby) {
+    setOwnedAttribute(state, dialog, "aria-labelledby", null);
   }
 }
 
@@ -262,13 +297,19 @@ export function closeDialog(dialog, returnValue = "") {
 export function requestDialogClose(dialog, returnValue = "") {
   if (!isDialogElement(dialog) || !dialog.open) return;
 
-  if (typeof dialog.requestClose === "function") {
-    ensureDialogWired(dialog).returnValue = returnValue;
-    dialog.requestClose(returnValue);
-    return;
+  const state = ensureDialogWired(dialog);
+  state.returnValue = returnValue;
+  state.requestingClose = true;
+  try {
+    if (typeof dialog.requestClose === "function") {
+      dialog.requestClose(returnValue);
+    } else {
+      // Older browsers still owe consumers the same cancel lifecycle.
+      dialog.dispatchEvent(new Event("cancel", { cancelable: true }));
+    }
+  } finally {
+    state.requestingClose = false;
   }
-
-  closeDialog(dialog, returnValue);
 }
 
 export function openDialog(dialog, trigger = null, forcedModal = null) {
@@ -276,7 +317,7 @@ export function openDialog(dialog, trigger = null, forcedModal = null) {
 
   const state = ensureDialogWired(dialog);
   const modal = resolveModalMode(dialog, forcedModal);
-  syncDialogSemantics(dialog, modal);
+  syncDialogSemantics(dialog, state, modal);
 
   state.closing = false;
   state.restoreFocusTo = trigger || dialog.ownerDocument.activeElement;
@@ -285,6 +326,7 @@ export function openDialog(dialog, trigger = null, forcedModal = null) {
   // while doing so; capture the position first and restore it so the page does
   // not jump to the top behind the modal.
   const viewport = dialog.ownerDocument.defaultView;
+  const scrollX = viewport?.scrollX ?? 0;
   const scrollY = viewport?.scrollY ?? 0;
 
   if (modal) {
@@ -295,17 +337,33 @@ export function openDialog(dialog, trigger = null, forcedModal = null) {
     state.modalOpen = false;
   }
 
-  if (scrollY > 0) {
-    viewport?.scrollTo(0, scrollY);
+  if (scrollX !== 0 || scrollY > 0) {
+    viewport?.scrollTo(scrollX, scrollY);
   }
 
   syncModalOpenClass(dialog.ownerDocument);
 }
 
+function handleDialogPointerDown(event) {
+  const dialog = event.currentTarget;
+  const state = dialogMap.get(dialog);
+  if (!state) return;
+
+  // Only a press that starts on the backdrop may dismiss on click. A
+  // text selection started inside the dialog and released over the backdrop
+  // produces a click on <dialog> with outside coordinates, which must not
+  // close (or flash static on) the dialog.
+  state.backdropPress = event.target === dialog && isOutsideDialog(dialog, event);
+}
+
 function handleDialogClick(event) {
   const dialog = event.currentTarget;
+  const state = dialogMap.get(dialog);
+  const backdropPress = state?.backdropPress === true;
+  if (state) state.backdropPress = false;
 
   if (event.target !== dialog || !isOutsideDialog(dialog, event)) return;
+  if (!backdropPress) return;
 
   // A native closedby="any" dialog owns its light dismiss; the runtime only
   // takes over when the author opted in via data-dialog-dismissible (which
@@ -338,7 +396,15 @@ function handleDialogCancel(event) {
   const dialog = event.currentTarget;
   const state = dialogMap.get(dialog);
 
-  // Escape and close requests always close, whatever the dismissible flag:
+  // Older dialogs may dispatch cancel for Escape without implementing
+  // closedBy. Explicit requestDialogClose() remains available to close them.
+  const closedBy = "closedBy" in dialog ? dialog.closedBy : dialog.getAttribute("closedby");
+  if (closedBy === "none" && !state?.requestingClose) {
+    event.preventDefault();
+    return;
+  }
+
+  // Escape and close requests close regardless of the dismissible flag:
   // data-dialog-dismissible only gates light dismiss (backdrop click, handled
   // in handleDialogClick). Applications intercept via actual:dialog-cancel.
   const request = new CustomEvent(EVENTS.dialogCancel, {
@@ -395,15 +461,19 @@ function ensureDialogWired(dialog) {
     controller,
     closing: false,
     modalOpen: isModalOpen(dialog),
+    ownedAttributes: [],
+    requestingClose: false,
     restoreFocusTo: null,
     returnValue: "",
     staticTimer: null,
+    backdropPress: false,
   };
 
   // A dialog that is already `open` in the markup is non-modal per spec,
   // whatever data-dialog-modal says; infer semantics from its actual state.
-  syncDialogSemantics(dialog, dialog.open ? isModalOpen(dialog) : isModal(dialog));
+  syncDialogSemantics(dialog, state, dialog.open ? isModalOpen(dialog) : isModal(dialog));
 
+  dialog.addEventListener("pointerdown", handleDialogPointerDown, { signal: controller.signal });
   dialog.addEventListener("click", handleDialogClick, { signal: controller.signal });
   dialog.addEventListener("submit", handleDialogSubmit, { signal: controller.signal });
   dialog.addEventListener("cancel", handleDialogCancel, { signal: controller.signal });
@@ -414,7 +484,7 @@ function ensureDialogWired(dialog) {
   // closedby keeps its native meaning — "any" closes on backdrop click,
   // "closerequest" on Escape, "none" disables both. Never override "none".
   if (isDismissible(dialog) && "closedBy" in dialog && dialog.closedBy === "any") {
-    dialog.closedBy = "closerequest";
+    setOwnedAttribute(state, dialog, "closedby", "closerequest");
   }
 
   dialogMap.set(dialog, state);
@@ -437,6 +507,7 @@ function disconnectDialog(dialog) {
 
   state.controller.abort();
   dialog.classList.remove(CLASSES.static);
+  restoreOwnedAttributes(state);
   state.modalOpen = false;
   dialogMap.delete(dialog);
   wiredDialogs.delete(dialog);

package/src/js/enhance.js

@@ -8,9 +8,13 @@
  * about final state after a batch, so a moved element (removed then
  * reinserted in the same batch) survives without a spurious disconnect.
  *
- * Attribute changes are intentionally not observed. Call refresh(node) after
- * adding a behavior attribute to an already-connected element. Behavior
- * attributes are setup-time contracts, not live enable/disable switches.
+ * Attribute changes are intentionally not observed. The owner of a handle
+ * calls refresh(node) after adding a behavior attribute to an
+ * already-connected element; for a data-enhance token, applyEnhancement()
+ * does it. The built-in data-* behaviors (mask, filter, context menu, …)
+ * keep their handle private, so for them insert the element with the
+ * attribute already set. Behavior attributes are setup-time contracts, not
+ * live enable/disable switches.
  *
  * enhancers: { [selector]: (el) => cleanup | void }
  * Returns: { refresh, disconnect }

package/src/js/escape.js

@@ -30,6 +30,7 @@ function onDocumentEscape(event) {
   if (
     event.defaultPrevented ||
     event.key !== "Escape" ||
+    event.isComposing ||
     event.ctrlKey ||
     event.altKey ||
     event.shiftKey ||

package/src/js/flyout.js

@@ -1,5 +1,6 @@
 import { registerEnhancement } from "./enhance.js";
 import { focusFirstDescendant } from "./focus.js";
+import { shouldIgnoreKey } from "./keys.js";
 import { connectMenu, focusFirstMenuItem, focusLastMenuItem } from "./menu.js";
 import { closeSurface, isSurfaceOpen, openSurface, retainSurface } from "./surface.js";
 
@@ -26,6 +27,13 @@ function isMenuFlyout(panel) {
   return panel.matches("menu") || panel.classList.contains("menu");
 }
 
+// ARIA-wise only [role="menu"] is a menu: <menu> carries the implicit list
+// role and .menu is a visual class. aria-haspopup="menu" must follow the
+// role, not the tag or class.
+function isAriaMenu(panel) {
+  return panel.getAttribute("role") === "menu";
+}
+
 function openFlyout(panel, trigger) {
   return openSurface(panel, {
     trigger,
@@ -57,6 +65,7 @@ function onTriggerClick(e) {
 
 function onTriggerKeydown(e) {
   const trigger = e.currentTarget;
+  if (shouldIgnoreKey(e)) return;
   const state = triggerMap.get(trigger);
   if (!state) return;
   const panel = resolvePanel(trigger, state);
@@ -153,7 +162,7 @@ function resolvePanel(trigger, state) {
       close: (menu) => closeSurface(menu),
     });
   }
-  if (!trigger.hasAttribute("aria-haspopup") && isMenuFlyout(panel)) {
+  if (!trigger.hasAttribute("aria-haspopup") && isAriaMenu(panel)) {
     trigger.setAttribute("aria-haspopup", "menu");
   }
 

package/src/js/focus-group.js

@@ -5,7 +5,7 @@
  * candidate list; the primitive does not observe the subtree.
  */
 
-import { itemForKey } from "./keys.js";
+import { itemForKey, shouldIgnoreKey } from "./keys.js";
 
 const ORIENTATIONS = new Set(["horizontal", "vertical"]);
 
@@ -82,6 +82,7 @@ export function connectFocusGroup(root, opts = {}) {
   }
 
   function onKeydown(event) {
+    if (shouldIgnoreKey(event)) return;
     const items = sync();
     const current = root.ownerDocument.activeElement;
     if (!items.includes(current)) return;

package/src/js/keys.js

@@ -5,6 +5,20 @@
  * centralize item lookup, edge handling, and optional wrapping.
  */
 
+// Shared guard for roving-focus key handlers. Composition (IME) and
+// ctrl/alt/meta-modified keys belong to the input method or the browser
+// (Alt+Arrow = history navigation) and must never be claimed by a widget.
+// Shift is deliberately excluded: Shift+Tab carries focus semantics that
+// callers handle themselves.
+export function shouldIgnoreKey(event) {
+  return (
+    event?.isComposing === true ||
+    event?.ctrlKey === true ||
+    event?.altKey === true ||
+    event?.metaKey === true
+  );
+}
+
 export function firstItem(items) {
   return items[0] || null;
 }

package/src/js/menu.js

@@ -10,7 +10,7 @@
 
 import { isElementVisible } from "./focus.js";
 import { connectFocusGroup } from "./focus-group.js";
-import { firstItem, itemForKey, lastItem } from "./keys.js";
+import { firstItem, itemForKey, lastItem, shouldIgnoreKey } from "./keys.js";
 
 const MENU_ITEM_SELECTOR = ":scope > li > .menu-item";
 const MENU_ITEM_ROLES = new Set(["menuitem", "menuitemcheckbox", "menuitemradio"]);
@@ -62,6 +62,7 @@ export function focusLastMenuItem(menu) {
 }
 
 export function onMenuKeydown(e, { close, navigate = true }) {
+  if (shouldIgnoreKey(e)) return;
   const menu = e.currentTarget;
   if (navigate) {
     const items = getMenuItems(menu);

package/src/js/status.js

@@ -67,6 +67,21 @@ let statusTimer;
 let statusGeneration = 0;
 let viewportTracker = null;
 const statusHomes = new WeakMap();
+// Reference kept only while the bar is temporarily mounted in a dialog. If
+// that dialog is removed from the DOM (htmx/Turbo swap), document lookup can
+// no longer find the bar — this reference lets the next status()/clear()
+// restore it to its home instead of silently no-opping forever.
+let mountedStatusTarget = null;
+
+function healDetachedStatusTarget() {
+  if (!mountedStatusTarget || mountedStatusTarget.isConnected) return;
+  if (!statusHomes.has(mountedStatusTarget)) {
+    mountedStatusTarget = null;
+    return;
+  }
+  restoreStatusTarget(mountedStatusTarget);
+  mountedStatusTarget = null;
+}
 
 function statusTarget() {
   if (typeof document === "undefined") return null;
@@ -83,6 +98,7 @@ function restoreStatusTarget(target) {
     parent.insertBefore(target, reference);
   }
   statusHomes.delete(target);
+  if (mountedStatusTarget === target) mountedStatusTarget = null;
 }
 
 function mountStatusTarget(target, source) {
@@ -97,6 +113,7 @@ function mountStatusTarget(target, source) {
     statusHomes.set(target, { parent: target.parentNode, nextSibling: target.nextSibling });
   }
   dialog.append(target);
+  mountedStatusTarget = target;
 }
 
 // The bar is fixed to the layout viewport, so the mobile software keyboard
@@ -149,6 +166,7 @@ function clearIntentClasses(target) {
 }
 
 export function status(message, options = {}) {
+  healDetachedStatusTarget();
   const target = statusTarget();
   if (!target || message == null) return;
 
@@ -186,6 +204,7 @@ export function status(message, options = {}) {
 
 status.clear = function clear() {
   clearTimeout(statusTimer);
+  healDetachedStatusTarget();
 
   const target = statusTarget();
   if (!target) {

package/src/js/surface.js

@@ -222,7 +222,10 @@ function startSurfaceResources(menu, state) {
 }
 
 export function isSurfaceOpen(menu) {
-  return menu.classList.contains(CLASSES.open);
+  // The open set is the source of truth; .is-open is only its visual
+  // projection. A morph touching classes must not orphan Escape entries,
+  // position tracking, or the open set.
+  return openSurfaces.has(menu);
 }
 
 export function prepareSurface(menu) {
@@ -304,8 +307,14 @@ export function openSurface(menu, opts = {}) {
   state.coordinateSpace = mode.space;
   menu.style.position = mode.position;
 
+  // Register before promoting: a position failure below closes the surface
+  // again, and that close must observe the open state to tear down.
+  openSurfaces.add(menu);
   // Promote before measuring: a closed popover has no box to position.
-  if (!showTransport(menu)) return false;
+  if (!showTransport(menu)) {
+    openSurfaces.delete(menu);
+    return false;
+  }
   menu.classList.add(CLASSES.open);
   syncExpanded(menu, true);
 
@@ -335,13 +344,12 @@ export function openSurface(menu, opts = {}) {
    * from; placing focus in the new surface is the caller's job, and both
    * callers in tree do it as soon as this returns.
    */
-  for (const other of openSurfaces) {
+  for (const other of [...openSurfaces]) {
     if (other !== menu && other.ownerDocument === menu.ownerDocument) {
       closeSurface(other, { restoreFocus: false });
     }
   }
 
-  openSurfaces.add(menu);
   startSurfaceResources(menu, state);
   return true;
 }
@@ -411,7 +419,3 @@ function ensureDocumentClick(menu) {
   clickBoundDocuments.add(doc);
   doc.addEventListener("click", onDocumentClick);
 }
-
-export function getSurfaceAutoClose(menu) {
-  return surfaceMap.get(menu)?.autoClose ?? "outside";
-}

package/src/js/tab.js

@@ -17,7 +17,7 @@
  */
 
 import { registerEnhancement } from "./enhance.js";
-import { itemForKey } from "./keys.js";
+import { itemForKey, shouldIgnoreKey } from "./keys.js";
 
 const TABLIST_SELECTOR = '[data-enhance~="tabs"]';
 
@@ -100,6 +100,7 @@ function initialize(list) {
 
 function onKeydown(e) {
   const list = e.currentTarget;
+  if (shouldIgnoreKey(e)) return;
   const tab = e.target.closest('[role="tab"]');
   if (!tab || tab.closest(TABLIST_SELECTOR) !== list) return;
 

package/src/js/tooltip.js

@@ -23,6 +23,12 @@
  *             for tooltips that are never triggered. AJAX-loaded triggers
  *             work automatically via bubbling delegated listeners.
  *
+ * Snapshot, not reactive: generated tooltip text is synchronized when
+ *             the tooltip is shown. Changes to data-tooltip do not rewrite
+ *             a tooltip that is already shown. Always-visible generated
+ *             tooltips therefore keep their initial text; use an explicit
+ *             tooltip when its content must update dynamically.
+ *
  * Show:       hover + focus (150ms delay), click toggle, or always visible
  * Hide:       focus leaving the trigger (focusout), pointer leave, Escape
  *
@@ -367,7 +373,10 @@ function ensureTip(trigger) {
   const text = trigger.getAttribute("data-tooltip");
   const doc = trigger.ownerDocument;
 
-  // shorthand: data-tooltip="text" → create element lazily
+  // shorthand: data-tooltip="text" → create element lazily.
+  // Shorthand content is always text. Never use innerHTML here:
+  // data-tooltip may hold application/user-provided strings. Rich content
+  // belongs in an explicit author-owned tooltip.
   if (text) {
     tip = doc.createElement("div");
     tip.className = CLASSES.tooltip;
@@ -467,6 +476,14 @@ function show(tip, ref, immediate = false) {
   const state = tipStates.get(tip);
   if (!state) return;
 
+  // Shorthand tips copy data-tooltip text at creation; re-read it on every
+  // show so a "Copy" → "Copied!" update is reflected without rewiring.
+  // Text only, never innerHTML — see the note at creation above.
+  if (state.generated) {
+    const text = ref.getAttribute("data-tooltip");
+    if (text && tip.textContent !== text) tip.textContent = text;
+  }
+
   state.activeRef = ref;
   const mode = positionModeFor(ref);
   state.space = mode.space;

package/src/js/validation.js

@@ -17,7 +17,7 @@
  * DOM tears down everything, including the managed novalidate attribute.
  */
 
-import enhance, { enhancementSelector } from "./enhance.js";
+import { enhancementSelector, registerEnhancement } from "./enhance.js";
 import { EVENTS } from "./events.js";
 import { CLASSES } from "./selectors.js";
 
@@ -435,10 +435,9 @@ export class FormValidator {
   }
 }
 
-if (typeof document !== "undefined") {
-  enhance({
-    [`form${VALIDATION_SELECTOR}`]: (form) => connectForm(form),
-  });
-}
+// Registered by name, not through a bare enhance(), so applyEnhancement()
+// refreshes it like the other token behaviors. The token only means
+// something on a form.
+registerEnhancement("validation", (el) => (isFormElement(el) ? connectForm(el) : undefined));
 
 export default FormValidator;