actual-css 0.1.0 → 0.3.0

package/src/js/enhance.js

@@ -13,24 +13,40 @@
  * attributes are setup-time contracts, not live enable/disable switches.
  *
  * enhancers: { [selector]: (el) => cleanup | void }
- * Returns: { refresh, forget, disconnect }
+ * Returns: { refresh, disconnect }
+ *
+ * Enhancement tokens — the data-enhance layer on top of enhance().
+ *
+ * enhancementSelector("tabs") returns [data-enhance~="tabs"], the generic
+ * opt-in for root-controller behaviors. registerEnhancement() owns a name per
+ * root — a second registration for the same name on the same root throws, and
+ * disconnect() releases ownership. Third-party behaviors register exactly
+ * like built-in ones.
+ *
+ * See docs/design-notes/enhancement-contract.md.
  */
 
 const registries = new WeakMap();
+const ownedNames = new WeakMap();
+
+// Node type constants as literals, not the realm's Node global, so nodes from
+// another document/window compare correctly.
+const ELEMENT_NODE = 1;
+const DOCUMENT_NODE = 9;
+const DOCUMENT_FRAGMENT_NODE = 11;
 
 function noopRuntime() {
   return {
     refresh() {},
-    forget() {},
     disconnect() {},
   };
 }
 
 function canScan(node) {
   return (
-    node?.nodeType === Node.ELEMENT_NODE ||
-    node?.nodeType === Node.DOCUMENT_NODE ||
-    node?.nodeType === Node.DOCUMENT_FRAGMENT_NODE
+    node?.nodeType === ELEMENT_NODE ||
+    node?.nodeType === DOCUMENT_NODE ||
+    node?.nodeType === DOCUMENT_FRAGMENT_NODE
   );
 }
 
@@ -41,7 +57,7 @@ function createRegistry(root) {
   function isValidSelector(selector) {
     try {
       root.querySelector?.(selector);
-      if (root instanceof Element) root.matches(selector);
+      if (root.nodeType === ELEMENT_NODE) root.matches(selector);
       return true;
     } catch (error) {
       console.error(`Invalid enhancer selector "${selector}"`, error);
@@ -54,7 +70,7 @@ function createRegistry(root) {
   }
 
   function start(record, el) {
-    if (!(el instanceof Element)) return;
+    if (el?.nodeType !== ELEMENT_NODE) return;
     let active = record.instances.get(el);
 
     for (const selector of record.selectors) {
@@ -80,14 +96,18 @@ function createRegistry(root) {
     const active = record.instances.get(el);
     if (!active) return;
     for (const cleanup of active.values()) {
-      cleanup?.();
+      try {
+        cleanup?.();
+      } catch (error) {
+        console.error("Enhancer cleanup failed", error);
+      }
     }
     record.instances.delete(el);
   }
 
   function scanFor(record, node) {
     if (!canScan(node)) return;
-    if (node instanceof Element) start(record, node);
+    if (node.nodeType === ELEMENT_NODE) start(record, node);
     if (record.selectorString) {
       node.querySelectorAll?.(record.selectorString).forEach((el) => {
         start(record, el);
@@ -97,7 +117,7 @@ function createRegistry(root) {
 
   function scan(node) {
     if (!canScan(node) || !selectorString) return;
-    if (node instanceof Element) {
+    if (node.nodeType === ELEMENT_NODE) {
       for (const record of records) start(record, node);
     }
     node.querySelectorAll?.(selectorString).forEach((el) => {
@@ -108,7 +128,7 @@ function createRegistry(root) {
   function sweepDisconnected() {
     for (const record of records) {
       for (const el of Array.from(record.instances.keys())) {
-        if (!el.isConnected) stop(record, el);
+        if (!el.isConnected || !root.contains(el)) stop(record, el);
       }
     }
   }
@@ -152,10 +172,6 @@ function createRegistry(root) {
       if (record.disconnected) return;
       scanFor(record, node);
     },
-    forget(record, el) {
-      if (record.disconnected) return;
-      record.instances.delete(el);
-    },
     remove(record) {
       if (record.disconnected) return;
       record.disconnected = true;
@@ -172,6 +188,50 @@ function createRegistry(root) {
   };
 }
 
+const ENHANCEMENT_NAME = /^[a-z][a-z0-9-]*$/;
+
+export function enhancementSelector(name) {
+  if (!ENHANCEMENT_NAME.test(name)) {
+    throw new TypeError(`Invalid enhancement name: ${name}`);
+  }
+  return `[data-enhance~="${name}"]`;
+}
+
+export function hasEnhancement(el, name) {
+  return el.matches(enhancementSelector(name));
+}
+
+export function registerEnhancement(name, init, root) {
+  if (typeof document === "undefined") return noopRuntime();
+
+  enhancementSelector(name);
+  if (typeof init !== "function") {
+    throw new TypeError("registerEnhancement() requires a function init.");
+  }
+
+  root ??= document.documentElement;
+  let names = ownedNames.get(root);
+  if (!names) {
+    names = new Map();
+    ownedNames.set(root, names);
+  }
+  if (names.has(name)) {
+    throw new Error(`Enhancement "${name}" is already registered on this root.`);
+  }
+
+  const runtime = enhance({ [enhancementSelector(name)]: init }, root);
+  names.set(name, runtime);
+
+  return {
+    refresh: (node) => runtime.refresh(node),
+    disconnect: () => {
+      runtime.disconnect();
+      if (names.get(name) === runtime) names.delete(name);
+      if (names.size === 0) ownedNames.delete(root);
+    },
+  };
+}
+
 function registryFor(root) {
   let registry = registries.get(root);
   if (!registry) {
@@ -184,7 +244,7 @@ function registryFor(root) {
 /**
  * @param {Record<string, (el: Element) => (() => void) | void>} enhancers
  * @param {Document | Element | DocumentFragment} [root]
- * @returns {{ refresh: (node: Node) => void, forget: (el: Element) => void, disconnect: () => void }}
+ * @returns {{ refresh: (node: Node) => void, disconnect: () => void }}
  */
 export default function enhance(enhancers, root) {
   if (typeof document === "undefined") {
@@ -198,9 +258,6 @@ export default function enhance(enhancers, root) {
 
   return {
     refresh: (node) => registry.refresh(record, node),
-    forget: (el) => {
-      registry.forget(record, el);
-    },
     disconnect: () => {
       registry.remove(record);
     },

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) {