actual-css 0.2.0 → 0.3.0

package/src/js/enhancement-loader.js

@@ -0,0 +1,301 @@
+/*
+ * enhancement-loader.js — Server-declared enhancement manifest loader.
+ *
+ * Reads <script type="application/json" data-enhance-modules"> blocks or
+ * the Enhance-Modules HTTP header, dynamically imports the declared ES
+ * module entrypoints, and registers them with the Actual lifecycle engine.
+ *
+ * Manifests declare document-wide modules: dynamically loaded enhancements
+ * always register on the default document root. A scope passed to
+ * loadEnhancements() only limits where manifest blocks are looked up.
+ *
+ * One map keyed by name reserves the slot immediately, so concurrent calls
+ * for the same name share one promise. The browser's native module cache
+ * handles URL dedup. Script/style helpers fill the gap for non-ESM assets.
+ *
+ * Exports prefixed with `__` are test hooks and are not part of the
+ * supported public API or SemVer contract.
+ */
+
+import enhance, { registerEnhancement } from "./enhance.js";
+import { parseConfig } from "./parse-config.js";
+
+const MANIFEST_SELECTOR = 'script[type="application/json"][data-enhance-modules]';
+
+const enhancements = new Map();
+
+const scriptLoads = new Map();
+const styleLoads = new Map();
+
+let moduleImporter = (url) => import(url);
+
+export function loadScript(url) {
+  const absoluteUrl = new URL(url, document.baseURI).href;
+
+  if (!scriptLoads.has(absoluteUrl)) {
+    scriptLoads.set(
+      absoluteUrl,
+      new Promise((resolve, reject) => {
+        const script = document.createElement("script");
+        script.src = absoluteUrl;
+        script.onload = resolve;
+        script.onerror = () => {
+          scriptLoads.delete(absoluteUrl);
+          script.remove();
+          reject(new Error(`Unable to load script: ${absoluteUrl}`));
+        };
+        document.head.append(script);
+      }),
+    );
+  }
+
+  return scriptLoads.get(absoluteUrl);
+}
+
+export function loadStyle(url) {
+  const absoluteUrl = new URL(url, document.baseURI).href;
+
+  if (!styleLoads.has(absoluteUrl)) {
+    styleLoads.set(
+      absoluteUrl,
+      new Promise((resolve, reject) => {
+        const link = document.createElement("link");
+        link.rel = "stylesheet";
+        link.href = absoluteUrl;
+        link.onload = resolve;
+        link.onerror = () => {
+          styleLoads.delete(absoluteUrl);
+          link.remove();
+          reject(new Error(`Unable to load style: ${absoluteUrl}`));
+        };
+        document.head.append(link);
+      }),
+    );
+  }
+
+  return styleLoads.get(absoluteUrl);
+}
+
+function makeInit(name, connect) {
+  return (element) => {
+    const controller = new AbortController();
+    const source = element.getAttribute("data-enhance-config");
+    const config = parseConfig(source ?? "");
+
+    const emit = (type, detail, options = {}) =>
+      element.dispatchEvent(
+        new CustomEvent(`actual:${name}:${type}`, {
+          bubbles: true,
+          detail,
+          ...options,
+        }),
+      );
+
+    let cleanup;
+    try {
+      cleanup = connect(element, {
+        config,
+        signal: controller.signal,
+        emit,
+      });
+    } catch (error) {
+      // A throwing connect() must not leak the local controller's listeners.
+      controller.abort();
+      throw error;
+    }
+
+    if (cleanup?.then) {
+      controller.abort();
+      throw new TypeError(
+        `Enhancement "${name}" returned a Promise. connect() must be synchronous; use prepare() for asynchronous setup.`,
+      );
+    }
+
+    if (cleanup !== undefined && typeof cleanup !== "function") {
+      controller.abort();
+      throw new TypeError(`Enhancement "${name}" must return a cleanup function or undefined.`);
+    }
+
+    return () => {
+      controller.abort();
+      cleanup?.();
+    };
+  };
+}
+
+function assertManifestUrl(name, url) {
+  if (typeof url !== "string" || url.trim() === "") {
+    throw new TypeError(`Enhancement "${name}" must declare a non-empty module URL.`);
+  }
+}
+
+export function loadEnhancement(name, url) {
+  assertManifestUrl(name, url);
+  const absoluteUrl = new URL(url, document.baseURI).href;
+  const existing = enhancements.get(name);
+
+  if (existing) {
+    if (existing.url !== absoluteUrl) {
+      throw new Error(
+        `Enhancement "${name}" is already declared from ${existing.url} and cannot be replaced by ${absoluteUrl}.`,
+      );
+    }
+    return existing.promise.then(() => ({ name, status: "skipped" }));
+  }
+
+  const promise = moduleImporter(absoluteUrl)
+    .then(async (mod) => {
+      if (typeof mod.default !== "function") {
+        throw new TypeError(`Enhancement "${name}" must export a default function.`);
+      }
+
+      if (mod.prepare !== undefined) {
+        if (typeof mod.prepare !== "function") {
+          throw new TypeError(`Enhancement "${name}" exports an invalid prepare().`);
+        }
+
+        await mod.prepare({
+          resolve: (path) => new URL(path, absoluteUrl).href,
+          loadScript,
+          loadStyle,
+        });
+      }
+
+      registerEnhancement(name, makeInit(name, mod.default));
+
+      return { name, status: "loaded" };
+    })
+    .catch((error) => {
+      if (enhancements.get(name)?.promise === promise) {
+        enhancements.delete(name);
+      }
+      throw error;
+    });
+
+  enhancements.set(name, { url: absoluteUrl, promise });
+
+  return promise;
+}
+
+async function loadManifest(manifest) {
+  const entries = Object.entries(manifest);
+  const results = await Promise.allSettled(
+    entries.map(([name, url]) => loadEnhancement(name, url)),
+  );
+
+  const output = { names: [], failed: [], skipped: [] };
+
+  results.forEach((result, index) => {
+    const name = entries[index][0];
+
+    if (result.status === "rejected") {
+      output.failed.push({ name, error: result.reason });
+    } else if (result.value.status === "skipped") {
+      output.skipped.push(name);
+    } else {
+      output.names.push(name);
+    }
+  });
+
+  return output;
+}
+
+function parseManifestEntries(text) {
+  const data = JSON.parse(text);
+
+  if (typeof data !== "object" || data === null || Array.isArray(data)) {
+    throw new TypeError("Manifest must be a JSON object.");
+  }
+
+  return Object.entries(data);
+}
+
+/**
+ * Load every enhancement declared in the manifest blocks under `scope`.
+ *
+ * @param {Document | Element | DocumentFragment} [scope] Where to look for
+ * manifest blocks. It only limits discovery; loaded enhancements register on
+ * the default document root.
+ * @returns {Promise<{ names: string[], failed: { name: string, error: Error }[], skipped: string[] }>}
+ */
+export async function loadEnhancements(scope = document) {
+  const blocks = scope.querySelectorAll(MANIFEST_SELECTOR);
+
+  const manifest = new Map();
+
+  for (const block of blocks) {
+    const entries = parseManifestEntries(block.textContent);
+
+    for (const [name, rawUrl] of entries) {
+      assertManifestUrl(name, rawUrl);
+      const url = new URL(rawUrl, document.baseURI).href;
+      const existing = manifest.get(name);
+
+      if (existing && existing !== url) {
+        throw new Error(`Enhancement "${name}" is declared from both ${existing} and ${url}.`);
+      }
+
+      manifest.set(name, url);
+    }
+  }
+
+  const result = await loadManifest(Object.fromEntries(manifest));
+
+  if (result.failed.length === 0) {
+    for (const block of blocks) block.remove();
+  }
+
+  return result;
+}
+
+async function loadManifestBlock(block) {
+  const entries = parseManifestEntries(block.textContent);
+  const result = await loadManifest(Object.fromEntries(entries));
+
+  for (const failure of result.failed) {
+    console.error(`Enhancement "${failure.name}" failed to load:`, failure.error);
+  }
+  if (result.failed.length === 0) block.remove();
+
+  return result;
+}
+
+export function watchEnhancementManifests() {
+  return enhance({
+    [MANIFEST_SELECTOR]: (block) => {
+      loadManifestBlock(block).catch((error) => {
+        console.error("Failed to parse enhancement manifest:", error);
+      });
+    },
+  });
+}
+
+export async function loadResponse(response) {
+  const header = response.headers.get("Enhance-Modules");
+
+  if (!header) return { names: [], failed: [], skipped: [] };
+
+  let manifest;
+  try {
+    manifest = JSON.parse(header);
+  } catch (error) {
+    throw new SyntaxError(`Invalid JSON in Enhance-Modules header: ${error.message}`);
+  }
+
+  if (typeof manifest !== "object" || manifest === null || Array.isArray(manifest)) {
+    throw new TypeError("Enhance-Modules header must be a JSON object.");
+  }
+
+  return loadManifest(manifest);
+}
+
+export function __setModuleImporter(fn) {
+  moduleImporter = fn;
+}
+
+export function __reset() {
+  enhancements.clear();
+  scriptLoads.clear();
+  styleLoads.clear();
+  moduleImporter = (url) => import(url);
+}

package/src/js/events.js

@@ -19,4 +19,7 @@ export const EVENTS = {
   // Cancelable: dispatched by dialog.js before handling native cancel close.
   // detail: { dialog, sourceEvent }
   dialogCancel: `${ACTUAL_EVENT_PREFIX}:dialog-cancel`,
+  // Dispatched after a command hides its target.
+  // detail: { trigger }
+  dismiss: `${ACTUAL_EVENT_PREFIX}:dismiss`,
 };

package/src/js/filter.js

@@ -60,12 +60,12 @@ function normalizeText(value) {
 function filterSlug(value, event) {
   const keepTrailingSeparator = event?.inputType === "insertText" && /[^\p{L}\p{N}]$/u.test(value);
   const slug = normalizeText(value)
-    .toLocaleLowerCase()
+    .toLowerCase()
     .replace(/[^\p{L}\p{N}]+/gu, "-")
     .replace(/-{2,}/g, "-")
-    .replace(/^-+/g, "");
+    .replace(/^-+/, "");
 
-  return keepTrailingSeparator ? slug : slug.replace(/-+$/g, "");
+  return keepTrailingSeparator ? slug : slug.replace(/-+$/, "");
 }
 
 function filterValue(value, modes, event) {

package/src/js/floating.js

@@ -1,12 +1,11 @@
 /*
  * Compact positioning engine for menus, tooltips, and popovers.
  *
- * Core math ported from Floating UI. Uses a single global scroll/resize
- * listener to reposition all registered floating elements via rAF.
+ * Core math ported from Floating UI. autoUpdate() batches scroll, resize,
+ * and element-resize callbacks per ownerDocument so each document owns its
+ * own listener set — no global import-time side effects.
  */
 
-import { EVENTS } from "./events.js";
-
 /* ── Placement parsing ────────────────────────────────── */
 
 function getSide(p) {
@@ -65,7 +64,7 @@ function computeCoords(reference, floating, placement, rtl) {
   return coords;
 }
 
-function applyOffset(coords, side, offset, rtl) {
+function applyOffset(coords, side, offset) {
   switch (side) {
     case "top":
       coords.y -= offset;
@@ -74,10 +73,10 @@ function applyOffset(coords, side, offset, rtl) {
       coords.y += offset;
       break;
     case "left":
-      coords.x += rtl ? offset : -offset;
+      coords.x -= offset;
       break;
     case "right":
-      coords.x += rtl ? -offset : offset;
+      coords.x += offset;
       break;
   }
 }
@@ -103,7 +102,8 @@ function isRTL(el) {
   if (el.dir === "rtl") return true;
   if (el.dir === "ltr") return false;
   if (supportsDirSelector) return el.matches(":dir(rtl)");
-  return el.ownerDocument?.dir === "rtl";
+  const style = el.ownerDocument?.defaultView?.getComputedStyle?.(el);
+  return style?.direction === "rtl";
 }
 
 function getDocEl(doc) {
@@ -134,8 +134,6 @@ function getViewportBoundary(doc) {
       doc.compatMode === "CSS1Compat"
         ? toNumber(bodyStyle?.marginLeft) + toNumber(bodyStyle?.marginRight)
         : 0;
-    // Classic stable scrollbars reserve inline space on the body. Subtract only
-    // plausible scrollbar widths so unusual body sizing does not shrink the viewport.
     const stableScrollbar = Math.abs(docEl.clientWidth - body.clientWidth - bodyMargin);
     if (stableScrollbar <= STABLE_SCROLLBAR_MAX_WIDTH) {
       width -= stableScrollbar;
@@ -181,15 +179,6 @@ function isVisible(el) {
   return el.getClientRects().length > 0;
 }
 
-function topVisibleTracked() {
-  const elements = [...tracked];
-  for (let i = elements.length - 1; i >= 0; i--) {
-    const el = elements[i];
-    if (el.isConnected && isVisible(el)) return el;
-  }
-  return null;
-}
-
 function getFloatingSize(float) {
   const rect = float.getBoundingClientRect();
   return {
@@ -198,138 +187,120 @@ function getFloatingSize(float) {
   };
 }
 
-/* ── Global scroll / resize tracking ──────────────────── */
-
-const tracked = new Set();
-let resizeObserver = null;
-let tick = false;
-const pendingTypes = new Set();
-
-function notify(type) {
-  if (type === "escape") {
-    const el = topVisibleTracked();
-    if (!el) return;
-    el.dispatchEvent(
-      new CustomEvent(EVENTS.hide, {
-        bubbles: false,
-        detail: { type: "escape" },
-      }),
-    );
-    return;
-  }
+/* ── Per-document batched callbacks ────────────────────── */
 
-  for (const el of tracked) {
-    el.dispatchEvent(
-      new CustomEvent(EVENTS.reposition, {
-        bubbles: false,
-        detail: { type },
-      }),
-    );
-  }
-}
+const trackers = new WeakMap();
 
-function hasOpenSurface() {
-  return topVisibleTracked() !== null;
-}
+function createTracker(doc) {
+  const win = doc.defaultView;
+  const ResizeObserver = win?.ResizeObserver;
 
-function rafNotify(e) {
-  if (e?.type) pendingTypes.add(e.type);
-  if (!tick) {
-    requestAnimationFrame(() => {
-      const types = [...pendingTypes];
-      pendingTypes.clear();
-      for (const type of types) notify(type);
-      tick = false;
-    });
-  }
-  tick = true;
-}
+  const entries = new Map();
+  let resizeObserver = null;
+  let tick = false;
+  const pending = new Map();
 
-function getResizeObserver() {
-  if (resizeObserver || typeof window === "undefined" || !window.ResizeObserver) {
+  function getResizeObserver() {
+    if (resizeObserver || !ResizeObserver) return resizeObserver;
+
+    resizeObserver = new ResizeObserver((entries, observer) => {
+      for (const entry of entries) {
+        observer.unobserve(entry.target);
+        rafNotify("element-resize", entry);
+        win.requestAnimationFrame(() => {
+          if (tracker.entries.has(entry.target)) observer.observe(entry.target);
+        });
+      }
+    });
     return resizeObserver;
   }
 
-  resizeObserver = new window.ResizeObserver((entries, observer) => {
-    for (const entry of entries) {
-      observer.unobserve(entry.target);
-      rafNotify({ type: "element-resize" });
-      requestAnimationFrame(() => {
-        if (tracked.has(entry.target)) observer.observe(entry.target);
+  function rafNotify(type, source) {
+    for (const element of entries.keys()) {
+      let notifications = pending.get(element);
+      if (!notifications) {
+        notifications = new Map();
+        pending.set(element, notifications);
+      }
+      let notification = notifications.get(type);
+      if (!notification) {
+        notification = { targets: new Set(), timeStamp: 0 };
+        notifications.set(type, notification);
+      }
+      if (source?.target) notification.targets.add(source.target);
+      notification.timeStamp = Math.max(notification.timeStamp, source?.timeStamp || 0);
+    }
+    if (!tick) {
+      win.requestAnimationFrame(() => {
+        const notifications = [...pending];
+        pending.clear();
+        for (const [element, types] of notifications) {
+          const cb = entries.get(element);
+          if (!cb || !element.isConnected) continue;
+          for (const [pendingType, detail] of types) {
+            cb({ type: pendingType, ...detail });
+          }
+        }
+        tick = false;
       });
     }
-  });
-  return resizeObserver;
-}
+    tick = true;
+  }
 
-// Global document listeners run at import time; keep SSR imports inert.
-if (typeof document !== "undefined") {
-  document.addEventListener("scroll", rafNotify, { passive: true, capture: true });
-  document.addEventListener("keydown", (e) => {
-    if (e.key === "Escape" && !e.ctrlKey && !e.altKey && !e.shiftKey) {
-      if (!hasOpenSurface()) return;
-      e.preventDefault();
-      notify("escape");
-    }
+  doc.addEventListener("scroll", (e) => rafNotify(e.type, e), {
+    passive: true,
+    capture: true,
   });
-}
-// Global window listener runs at import time; keep SSR imports inert.
-if (typeof window !== "undefined") {
-  window.addEventListener("resize", rafNotify, { passive: true });
+  win.addEventListener("resize", (e) => rafNotify("resize", e), { passive: true });
+
+  const tracker = {
+    entries,
+    add(element, callback) {
+      entries.set(element, callback);
+      getResizeObserver()?.observe(element);
+      return () => {
+        entries.delete(element);
+        pending.delete(element);
+        resizeObserver?.unobserve(element);
+      };
+    },
+  };
+
+  return tracker;
 }
 
-/* ── Public API ────────────────────────────────────────── */
+function trackerFor(element) {
+  const doc = element.ownerDocument;
+  let tracker = trackers.get(doc);
+  if (!tracker) {
+    tracker = createTracker(doc);
+    trackers.set(doc, tracker);
+  }
+  return tracker;
+}
 
-/**
- * Register a floating element for auto-reposition on scroll/resize.
- * Returns a cleanup function that removes the element from tracking.
- */
-export function track(el) {
-  tracked.add(el);
-  getResizeObserver()?.observe(el);
-  return () => {
-    tracked.delete(el);
-    resizeObserver?.unobserve(el);
-  };
+export function autoUpdate(element, callback) {
+  return trackerFor(element).add(element, callback);
 }
 
-/**
- * Compute and apply position for a floating element relative to a reference.
- *
- * @param {Element} ref
- * @param {HTMLElement} float
- * @param {object} [opts]
- * @param {string} [opts.placement]  default "bottom-start"
- * @param {number} [opts.distance]   px offset from reference
- * @param {boolean} [opts.flip]      flip if overflows viewport
- * @param {boolean} [opts.shift]     shift if overflows x-axis
- * @param {number} [opts.shiftPadding] px padding when shifting
- * @param {Element} [opts.scope]     constrain to a bounding element
- */
+/* ── Positioning ──────────────────────────────────────── */
+
 export function reposition(ref, float, opts = {}) {
-  if (!isVisible(float)) return;
+  if (!isVisible(float)) return false;
 
   const placement = opts.placement || "bottom-start";
   const distance = opts.distance || 0;
   const flip = opts.flip !== false;
   const shift = opts.shift !== false;
-  const shiftPad = opts.shiftPadding || 4;
+  const shiftPad = opts.shiftPadding ?? 4;
   const rtl = isRTL(ref);
 
   const rects = ref.getClientRects();
   const refRect = placement.startsWith("bottom") ? rects[rects.length - 1] : rects[0];
-  if (!refRect) return;
+  if (!refRect) return false;
 
   const boundary = getBoundary(ref, opts);
-  if (isOutsideBoundary(refRect, boundary)) {
-    float.dispatchEvent(
-      new CustomEvent(EVENTS.outOfView, {
-        bubbles: false,
-        detail: { type: "out-of-view" },
-      }),
-    );
-    return;
-  }
+  if (isOutsideBoundary(refRect, boundary)) return false;
 
   const floatRect = getFloatingSize(float);
   const sx = boundary.x;
@@ -342,7 +313,7 @@ export function reposition(ref, float, opts = {}) {
   let axis = getMainAxis(placement);
   let current = placement;
   let coords = computeCoords(refRect, floatRect, current, rtl);
-  applyOffset(coords, side, distance, rtl);
+  applyOffset(coords, side, distance);
 
   if (flip) {
     const cx = Math.ceil(coords.x);
@@ -355,11 +326,9 @@ export function reposition(ref, float, opts = {}) {
       side = flipSide(side);
       current = align ? `${side}-${align}` : side;
       coords = computeCoords(refRect, floatRect, current, rtl);
-      applyOffset(coords, side, distance, rtl);
+      applyOffset(coords, side, distance);
     }
 
-    // Narrow side placements can fit neither left nor right. In that case,
-    // fall back to top so compact mobile layouts get a usable placement.
     if (
       axis === "y" &&
       (coords.x < sx || coords.x + floatRect.width > cw) &&
@@ -369,7 +338,7 @@ export function reposition(ref, float, opts = {}) {
       axis = "x";
       current = align ? `${side}-${align}` : side;
       coords = computeCoords(refRect, floatRect, current, rtl);
-      applyOffset(coords, side, distance, rtl);
+      applyOffset(coords, side, distance);
     }
   }
 
@@ -382,7 +351,7 @@ export function reposition(ref, float, opts = {}) {
       const nextAlign = getAlignment(current) === "end" ? "start" : "end";
       const candidatePlacement = `${side}-${nextAlign}`;
       const candidate = computeCoords(refRect, floatRect, candidatePlacement, rtl);
-      applyOffset(candidate, side, distance, rtl);
+      applyOffset(candidate, side, distance);
 
       if (getInlineOverflow(candidate, floatRect, minX, maxX) < currentOverflow) {
         current = candidatePlacement;
@@ -391,7 +360,6 @@ export function reposition(ref, float, opts = {}) {
     }
   }
 
-  // shift on x axis
   let p = 50;
   if (shift || floatRect.width > refRect.width) {
     const minX = sx + shiftPad;
@@ -433,6 +401,8 @@ export function reposition(ref, float, opts = {}) {
     left: `${coords.x}px`,
     top: `${coords.y}px`,
   });
+
+  return true;
 }
 
 export function repositionAt(x, y, float, opts = {}) {
@@ -458,5 +428,5 @@ export function repositionAt(x, y, float, opts = {}) {
     ],
   };
 
-  reposition(ref, float, opts);
+  return reposition(ref, float, opts);
 }