actual-css 0.1.0 → 0.2.0

package/src/js/surface.js

@@ -1,3 +1,4 @@
+import enhance from "./enhance.js";
 import { EVENTS } from "./events.js";
 import { reposition, repositionAt, track } from "./floating.js";
 import { hasMenuItem, onMenuKeydown } from "./menu.js";
@@ -12,6 +13,35 @@ const BREAKPOINTS = {
 const openSurfaces = new Set();
 const surfaceMap = new WeakMap();
 const mountedSurfaces = new WeakMap();
+const clickBoundDocuments = new WeakSet();
+
+// data-actual-surface is written by the runtime, never by an author, and never
+// selected on by CSS. It is namespaced because "data-surface" is a name an
+// application may already own. surface.js reaps its own surfaces so consumers
+// do not have to maintain panel-side lifecycle hooks.
+const SURFACE_MARKER = "data-actual-surface";
+const reapers = new WeakMap();
+
+// Registered lazily, per owning document, and never at import time: enhance()
+// binds its observer to the root it is given, so a module-scope
+// enhance() would watch whichever document existed when this module was first
+// imported. Surfaces in any other document (an iframe, or a fresh test
+// document) would then never be swept. Keyed by Document, so nothing is
+// retained once a document is gone.
+function reaperFor(menu) {
+  const root = menu.ownerDocument?.documentElement;
+  if (!root) return null;
+
+  let reaper = reapers.get(root);
+  if (!reaper) {
+    reaper = enhance(
+      { [`[${SURFACE_MARKER}]`]: (el) => () => disconnectSurface(el, { restore: false }) },
+      root,
+    );
+    reapers.set(root, reaper);
+  }
+  return reaper;
+}
 
 function waitForAnimations(...elements) {
   const animations = elements
@@ -170,6 +200,7 @@ function positionSurface(menu) {
 function ensureSurfaceWired(menu) {
   if (surfaceMap.has(menu)) return surfaceMap.get(menu);
 
+  ensureDocumentClick(menu);
   const controller = new AbortController();
   const state = {
     controller,
@@ -237,7 +268,7 @@ function ensureSurfaceWired(menu) {
         return;
       }
       if (!state || state.autoClose === "outside" || state.autoClose === "false") return;
-      if (hasMenuItem(e.target)) closeSurface(menu);
+      if (hasMenuItem(menu, e.target)) closeSurface(menu);
     },
     { signal: controller.signal },
   );
@@ -255,6 +286,10 @@ export function prepareSurface(menu) {
   menu.style.position = "fixed";
   menu.hidden = true;
   syncExpanded(menu, false);
+  // Both steps are idempotent, so they run unguarded: that also keeps the
+  // reaper correct if a surface is ever adopted into another document.
+  menu.setAttribute(SURFACE_MARKER, "");
+  reaperFor(menu)?.refresh(menu);
 }
 
 export function openSurface(menu, opts = {}) {
@@ -332,8 +367,9 @@ export function closeSurface(menu, opts = {}) {
   });
 }
 
-export function disconnectSurface(menu) {
+export function disconnectSurface(menu, { restore = true } = {}) {
   if (!menu) return;
+  if (!restore) mountedSurfaces.delete(menu);
   closeSurface(menu);
   const state = surfaceMap.get(menu);
   if (state) {
@@ -345,14 +381,23 @@ export function disconnectSurface(menu) {
   restoreSurface(menu);
 }
 
-// Global outside-click listener runs at import time; keep SSR imports inert.
-if (typeof document !== "undefined") {
-  document.addEventListener("click", (e) => {
-    for (const menu of openSurfaces) {
-      const state = surfaceMap.get(menu);
-      if (!state || state.autoClose === "inside" || state.autoClose === "false") continue;
-      if (menu.contains(e.target) || state?.trigger?.contains(e.target)) continue;
-      closeSurface(menu);
-    }
-  });
+function onDocumentClick(e) {
+  for (const menu of openSurfaces) {
+    const state = surfaceMap.get(menu);
+    if (!state || state.autoClose === "inside" || state.autoClose === "false") continue;
+    if (menu.contains(e.target) || state?.trigger?.contains(e.target)) continue;
+    closeSurface(menu);
+  }
+}
+
+// Bound per owning document on first use, not at import time — same reason as
+// reaperFor(): an import-time listener attaches to whichever document existed
+// then, and stays attached to it. Nothing can need this listener before a
+// surface has been wired, so binding here costs nothing and keeps SSR imports
+// inert without a typeof guard.
+function ensureDocumentClick(menu) {
+  const doc = menu.ownerDocument;
+  if (!doc || clickBoundDocuments.has(doc)) return;
+  clickBoundDocuments.add(doc);
+  doc.addEventListener("click", onDocumentClick);
 }

package/src/js/tab.js

@@ -1,7 +1,7 @@
 /*
  * Tabs — in-place panel switcher using real tab semantics.
  *
- * Tab list:  .tabs[role="tablist"]
+ * Tab list:  [data-enhance="tabs"] with role="tablist"
  * Tab:       [role="tab"]  with aria-selected, aria-controls, id, tabindex
  * Panel:     [role="tabpanel"]  with id matching aria-controls
  *
@@ -9,17 +9,16 @@
  *            ArrowUp/Down for aria-orientation="vertical"
  *            ArrowDown (focus selected panel)
  *
- * Self-registers via enhance: injected tablists wire automatically.
+ * Self-registers via registerEnhancement: injected tablists wire automatically.
  * The tab→panel map is rebuilt from the live tablist on each interaction,
  * so tabs added after connect are picked up with no extra work.
  * Cleanup is the AbortController.abort() returned to enhance.
  */
 
-import enhance from "./enhance.js";
+import { registerEnhancement } from "./enhance.js";
 import { firstItem, lastItem, nextItem } from "./keys.js";
-import { CLASSES } from "./selectors.js";
 
-const TABLIST_SELECTOR = `.${CLASSES.tabs}[role="tablist"]`;
+const TABLIST_SELECTOR = '[data-enhance~="tabs"]';
 
 function tabsOf(list) {
   return [...list.querySelectorAll('[role="tab"]')];
@@ -162,12 +161,10 @@ function onClick(e) {
   tab.focus();
 }
 
-enhance({
-  [TABLIST_SELECTOR]: (list) => {
-    const controller = new AbortController();
-    initialize(list);
-    list.addEventListener("click", onClick, { signal: controller.signal });
-    list.addEventListener("keydown", onKeydown, { signal: controller.signal });
-    return () => controller.abort();
-  },
+registerEnhancement("tabs", (list) => {
+  const controller = new AbortController();
+  initialize(list);
+  list.addEventListener("click", onClick, { signal: controller.signal });
+  list.addEventListener("keydown", onKeydown, { signal: controller.signal });
+  return () => controller.abort();
 });

package/src/js/validation.js

@@ -8,27 +8,22 @@
  * framework: server / AJAX validation lives in app code and feeds results
  * back through FormValidator.setErrors().
  *
- * Opt in with the .needs-validation class. Importing the module registers
- * the behavior; there is no init call.
+ * Opt in with data-enhance="validation". The .needs-validation class
+ * remains valid for presentation-only (CSS :user-invalid feedback without
+ * the JS behavior). Importing the module registers the behavior; there is
+ * no init call.
  *
- * The .needs-validation class is a static, init-time contract: this module
- * does not observe attribute mutations, so toggling the class after connect
- * only takes effect on the next focusout/input event, not immediately. A
- * submit that races that window can still bypass native validation (the
- * managed novalidate attribute is still present). Treat the class as fixed
- * for a form's lifetime rather than something toggled at runtime. Removing
- * the form from the DOM, however, is fully supported: the enhance() sweep
- * runs the cleanup below, which aborts all listeners, removes the managed
- * novalidate attribute, and releases the form's internal state.
+ * The marker is a static, init-time contract. Removing the form from the
+ * DOM tears down everything, including the managed novalidate attribute.
  */
 
-import enhance from "./enhance.js";
+import enhance, { enhancementSelector } from "./enhance.js";
 import { EVENTS } from "./events.js";
 import { CLASSES } from "./selectors.js";
 
 const NOVALIDATE = "novalidate";
 const WAS_VALIDATED_CLASS = CLASSES.wasValidated;
-const NEEDS_VALIDATION_CLASS = CLASSES.needsValidation;
+const VALIDATION_SELECTOR = enhancementSelector("validation");
 const FIELD_CLASS = CLASSES.field;
 const DANGER_CLASS = CLASSES.danger;
 const MANAGED_NOVALIDATE_ATTR = "validationManagedNovalidate";
@@ -177,7 +172,7 @@ function errorEl(el) {
   if (!ids) return null;
   for (const id of ids.split(/\s+/)) {
     const node = el.ownerDocument.getElementById(id);
-    if (node?.classList.contains(CLASSES.fieldError)) {
+    if (node?.matches(`.${CLASSES.fieldError}, [data-field-error]`)) {
       return node;
     }
   }
@@ -205,14 +200,6 @@ function hydrateServerErrors(form) {
   }
 }
 
-function ensureManagedNoValidate(form) {
-  if (!form.classList.contains(NEEDS_VALIDATION_CLASS)) return;
-  if (form.hasAttribute(NOVALIDATE)) return;
-
-  form.setAttribute(NOVALIDATE, "");
-  form.dataset[MANAGED_NOVALIDATE_ATTR] = "";
-}
-
 function releaseManagedNoValidate(form) {
   if (form.dataset[MANAGED_NOVALIDATE_ATTR] === undefined) return;
   form.removeAttribute(NOVALIDATE);
@@ -220,8 +207,6 @@ function releaseManagedNoValidate(form) {
 }
 
 function validateField(el, trigger) {
-  const form = el.form;
-  if (!form?.classList.contains(NEEDS_VALIDATION_CLASS)) return;
   if (ignoreField(el)) return;
 
   if (trigger === "input" && el.dataset.validationErrors === "server") {
@@ -261,11 +246,6 @@ function connectForm(form) {
     (event) => {
       const el = event.target;
       if (el instanceof Element && el.form === form) {
-        if (!form.classList.contains(NEEDS_VALIDATION_CLASS)) {
-          releaseManagedNoValidate(form);
-          return;
-        }
-        ensureManagedNoValidate(form);
         validateField(el, "blur");
       }
     },
@@ -277,11 +257,6 @@ function connectForm(form) {
     (event) => {
       const el = event.target;
       if (el instanceof Element && el.form === form) {
-        if (!form.classList.contains(NEEDS_VALIDATION_CLASS)) {
-          releaseManagedNoValidate(form);
-          return;
-        }
-        ensureManagedNoValidate(form);
         validateField(el, "input");
       }
     },
@@ -306,13 +281,6 @@ function connectForm(form) {
     (event) => {
       if (event.submitter?.formNoValidate) return;
 
-      if (!form.classList.contains(NEEDS_VALIDATION_CLASS)) {
-        releaseManagedNoValidate(form);
-        return;
-      }
-
-      ensureManagedNoValidate(form);
-
       let firstInvalid = null;
 
       for (const el of form.elements) {
@@ -373,7 +341,7 @@ export class FormValidator {
     rules[name] = callback;
   }
 
-  static init(selector = `.${NEEDS_VALIDATION_CLASS}`) {
+  static init(selector = VALIDATION_SELECTOR) {
     if (typeof document === "undefined") return;
     for (const form of document.querySelectorAll(selector)) {
       if (isFormElement(form)) connectForm(form);
@@ -412,7 +380,7 @@ export class FormValidator {
 
 if (typeof document !== "undefined") {
   enhance({
-    [`form.${NEEDS_VALIDATION_CLASS}`]: (form) => connectForm(form),
+    [`form${VALIDATION_SELECTOR}`]: (form) => connectForm(form),
   });
 }