actual-css 0.1.0

package/src/js/dialog.js

@@ -0,0 +1,503 @@
+/*
+ * Dialog — thin declarative layer over native <dialog>.
+ *
+ * Trigger:       <button commandfor="dialog-id" command="show-modal">
+ * Close button:  <button commandfor="dialog-id" command="request-close">
+ * Dialog:        <dialog id="dialog-id" data-dialog-dismissible>
+ *
+ * Command semantics are explicit: show-modal calls showModal(), show calls
+ * show(). data-dialog-modal still defines the default for direct openDialog()
+ * calls when no command mode is forced.
+ * Dismissible means backdrop click/light dismiss is allowed.
+ *
+ * View transitions (opt-in via data-dialog-view-transition):
+ *   When the browser supports document.startViewTransition and the user allows
+ *   motion, the dialog morphs to/from its trigger using a shared
+ *   view-transition-name. Otherwise native dialog behavior remains the
+ *   baseline: the dialog simply opens and closes.
+ *
+ * Browsers without native <dialog> can get a rudimentary per-element shim
+ * from the optional, standalone dialog-fallback.js module; this module has
+ * no dependency on it and alerts when no shim or polyfill made the target
+ * controllable.
+ */
+
+import { registerCommands, targetFor } from "./command.js";
+import enhance from "./enhance.js";
+import { EVENTS } from "./events.js";
+import { CLASSES } from "./selectors.js";
+
+const dialogMap = new WeakMap();
+const wiredDialogs = new Set();
+const DIALOG_COMMANDS = ["show-modal", "show", "request-close", "close"];
+const DIALOG_SELECTOR = "dialog";
+const DIALOG_TITLE_SELECTOR = "[data-title], h1, h2, h3, h4, h5, h6";
+const DEFAULT_UNSUPPORTED_MESSAGE =
+  "This dialog cannot open because this browser does not support this feature.";
+let uid = 0;
+
+function supportsDialog() {
+  return (
+    typeof HTMLDialogElement !== "undefined" &&
+    typeof HTMLDialogElement.prototype.showModal === "function"
+  );
+}
+function isDialogElement(el) {
+  return (
+    typeof Node !== "undefined" && el?.nodeType === Node.ELEMENT_NODE && el.localName === "dialog"
+  );
+}
+
+function canControlDialog(el) {
+  // Optional polyfills may patch registered <dialog> elements without making
+  // supportsDialog() true globally, so check the actual element before opening.
+  return (
+    isDialogElement(el) &&
+    typeof el.show === "function" &&
+    typeof el.showModal === "function" &&
+    typeof el.close === "function"
+  );
+}
+
+function isDialog(el) {
+  return canControlDialog(el);
+}
+
+function boolData(el, name) {
+  return el.hasAttribute(name) && el.getAttribute(name) !== "false";
+}
+
+function ensureId(el, prefix) {
+  if (!el.id) {
+    uid++;
+    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");
+  }
+
+  if (dialog.hasAttribute("aria-label") || dialog.hasAttribute("aria-labelledby")) {
+    return;
+  }
+
+  const label = dialog.getAttribute("data-title")?.trim();
+  if (label) {
+    dialog.setAttribute("aria-label", label);
+    return;
+  }
+
+  const title = dialog.querySelector(DIALOG_TITLE_SELECTOR);
+  if (title) {
+    dialog.setAttribute("aria-labelledby", ensureId(title, "dialog-title"));
+  }
+}
+
+// Reached only when neither the optional dialog-fallback module nor an
+// adopter polyfill made the target controllable on a legacy browser.
+function notifyUnsupportedDialog(trigger) {
+  const win = trigger.ownerDocument.defaultView;
+  win?.alert?.(DEFAULT_UNSUPPORTED_MESSAGE);
+}
+
+function isModal(dialog) {
+  return dialog.getAttribute("data-dialog-modal") !== "false";
+}
+
+function resolveModalMode(dialog, forcedModal = null) {
+  return forcedModal == null ? isModal(dialog) : forcedModal;
+}
+
+function isModalOpen(dialog) {
+  if (!dialog.open) return false;
+  // :modal distinguishes a top-layer showModal() dialog from one opened via
+  // show() or a bare `open` attribute in the initial HTML (never modal per
+  // spec, whatever data-dialog-modal says).
+  try {
+    return dialog.matches(":modal");
+  } catch {
+    // Selector unsupported: the only way a dialog is open before we wire it
+    // is the `open` attribute, which is non-modal.
+    return false;
+  }
+}
+
+function syncModalOpenClass(doc = document) {
+  let hasOpenModal = false;
+
+  for (const dialog of wiredDialogs) {
+    const state = dialogMap.get(dialog);
+    if (
+      dialog.ownerDocument === doc &&
+      dialog.isConnected &&
+      dialog.open &&
+      state?.modalOpen === true
+    ) {
+      hasOpenModal = true;
+      break;
+    }
+  }
+
+  const root = doc.documentElement;
+  const wasOpen = root.classList.contains(CLASSES.modalOpen);
+
+  if (hasOpenModal && !wasOpen) {
+    const viewportWidth = doc.defaultView?.innerWidth;
+    root.classList.toggle(
+      CLASSES.hadScrollbar,
+      Number.isFinite(viewportWidth) && viewportWidth > root.clientWidth,
+    );
+  } else if (!hasOpenModal) {
+    root.classList.remove(CLASSES.hadScrollbar);
+  }
+
+  root.classList.toggle(CLASSES.modalOpen, hasOpenModal);
+}
+
+function isDismissible(dialog) {
+  return boolData(dialog, "data-dialog-dismissible");
+}
+
+function wantsViewTransition(dialog) {
+  return boolData(dialog, "data-dialog-view-transition");
+}
+
+const VT_NAME = "actual-dialog";
+
+function supportsViewTransitions(doc = document) {
+  return typeof doc.startViewTransition === "function";
+}
+
+function motionAllowed(doc = document) {
+  return !doc.defaultView?.matchMedia?.("(prefers-reduced-motion: reduce)").matches;
+}
+
+function setVtName(target, name) {
+  if (target) target.style.viewTransitionName = name;
+}
+
+function clearVtName(...targets) {
+  for (const target of targets) {
+    if (target) target.style.viewTransitionName = "";
+  }
+}
+
+function canViewTransition(dialog, trigger) {
+  const doc = dialog.ownerDocument;
+  return (
+    wantsViewTransition(dialog) &&
+    supportsViewTransitions(doc) &&
+    motionAllowed(doc) &&
+    trigger?.isConnected === true
+  );
+}
+
+function openDialogWithViewTransition(dialog, trigger, forcedModal = null) {
+  if (!canViewTransition(dialog, trigger)) {
+    openDialog(dialog, trigger, forcedModal);
+    return;
+  }
+
+  setVtName(trigger, VT_NAME);
+
+  const transition = dialog.ownerDocument.startViewTransition(() => {
+    clearVtName(trigger);
+    setVtName(dialog, VT_NAME);
+    openDialog(dialog, trigger, forcedModal);
+  });
+
+  transition.finished.finally(() => clearVtName(dialog, trigger)).catch(() => {});
+}
+
+function isOutsideDialog(dialog, event) {
+  const rect = dialog.getBoundingClientRect();
+
+  return (
+    event.clientX < rect.left ||
+    event.clientX > rect.right ||
+    event.clientY < rect.top ||
+    event.clientY > rect.bottom
+  );
+}
+
+function flashStatic(dialog) {
+  const state = ensureDialogWired(dialog);
+
+  if (state.staticTimer) {
+    window.clearTimeout(state.staticTimer);
+  }
+
+  dialog.classList.remove(CLASSES.static);
+  void dialog.offsetWidth;
+  dialog.classList.add(CLASSES.static);
+
+  state.staticTimer = window.setTimeout(() => {
+    dialog.classList.remove(CLASSES.static);
+    state.staticTimer = null;
+  }, 250);
+}
+
+function finishClose(dialog, returnValue = "") {
+  const state = dialogMap.get(dialog);
+
+  if (state) {
+    state.closing = false;
+    state.returnValue = "";
+  }
+
+  if (dialog.open) {
+    dialog.close(returnValue);
+  }
+}
+
+export function closeDialog(dialog, returnValue = "") {
+  if (!isDialog(dialog) || !dialog.open) return;
+
+  const state = ensureDialogWired(dialog);
+  if (state.closing) return;
+
+  const trigger = state.restoreFocusTo;
+  if (canViewTransition(dialog, trigger)) {
+    state.closing = true;
+    setVtName(dialog, VT_NAME);
+
+    const transition = dialog.ownerDocument.startViewTransition(() => {
+      clearVtName(dialog);
+      setVtName(trigger, VT_NAME);
+      dialog.close(returnValue);
+    });
+
+    transition.finished
+      .finally(() => {
+        state.closing = false;
+        clearVtName(trigger);
+      })
+      .catch(() => {});
+    return;
+  }
+
+  finishClose(dialog, returnValue);
+}
+
+export function requestDialogClose(dialog, returnValue = "") {
+  if (!isDialog(dialog) || !dialog.open) return;
+
+  if (typeof dialog.requestClose === "function") {
+    ensureDialogWired(dialog).returnValue = returnValue;
+    dialog.requestClose(returnValue);
+    return;
+  }
+
+  closeDialog(dialog, returnValue);
+}
+
+export function openDialog(dialog, trigger = null, forcedModal = null) {
+  if (!isDialog(dialog) || dialog.open || !dialog.isConnected) return;
+
+  const state = ensureDialogWired(dialog);
+  const modal = resolveModalMode(dialog, forcedModal);
+  syncDialogSemantics(dialog, modal);
+
+  state.closing = false;
+  state.restoreFocusTo = trigger || document.activeElement;
+
+  if (modal) {
+    dialog.showModal();
+    state.modalOpen = true;
+  } else {
+    dialog.show();
+    state.modalOpen = false;
+  }
+
+  syncModalOpenClass(dialog.ownerDocument);
+}
+
+function handleDialogClick(event) {
+  const dialog = event.currentTarget;
+
+  if (event.target !== dialog || !isOutsideDialog(dialog, event)) return;
+
+  event.preventDefault();
+
+  if (isDismissible(dialog)) {
+    requestDialogClose(dialog);
+    return;
+  }
+
+  flashStatic(dialog);
+}
+
+function handleDialogSubmit(event) {
+  const dialog = event.currentTarget;
+  const form = event.target;
+
+  if (!(form instanceof HTMLFormElement)) return;
+  if (form.method.toLowerCase() !== "dialog") return;
+  if (!canViewTransition(dialog, dialogMap.get(dialog)?.restoreFocusTo)) return;
+
+  event.preventDefault();
+  closeDialog(dialog, event.submitter?.value || "");
+}
+
+function handleDialogCancel(event) {
+  const dialog = event.currentTarget;
+
+  if (!isDismissible(dialog)) {
+    event.preventDefault();
+    flashStatic(dialog);
+    return;
+  }
+
+  const request = new CustomEvent(EVENTS.dialogCancel, {
+    bubbles: true,
+    cancelable: true,
+    detail: { dialog, sourceEvent: event },
+  });
+  if (!dialog.dispatchEvent(request)) {
+    event.preventDefault();
+    return;
+  }
+
+  event.preventDefault();
+  closeDialog(dialog, dialogMap.get(dialog)?.returnValue || "");
+}
+
+function handleDialogClose(event) {
+  const dialog = event.currentTarget;
+  const state = dialogMap.get(dialog);
+
+  clearVtName(dialog);
+
+  if (!state) return;
+
+  if (state.staticTimer) {
+    window.clearTimeout(state.staticTimer);
+    state.staticTimer = null;
+  }
+
+  dialog.classList.remove(CLASSES.static);
+  state.closing = false;
+  state.returnValue = "";
+  state.modalOpen = false;
+  syncModalOpenClass(dialog.ownerDocument);
+
+  const restoreFocusTo = state.restoreFocusTo;
+  state.restoreFocusTo = null;
+
+  if (restoreFocusTo?.isConnected) {
+    restoreFocusTo.focus();
+  }
+}
+
+function ensureDialogWired(dialog) {
+  if (dialogMap.has(dialog)) return dialogMap.get(dialog);
+
+  const controller = new AbortController();
+  const state = {
+    controller,
+    closing: false,
+    modalOpen: isModalOpen(dialog),
+    restoreFocusTo: null,
+    returnValue: "",
+    staticTimer: null,
+  };
+
+  syncDialogSemantics(dialog);
+
+  dialog.addEventListener("click", handleDialogClick, { signal: controller.signal });
+  dialog.addEventListener("submit", handleDialogSubmit, { signal: controller.signal });
+  dialog.addEventListener("cancel", handleDialogCancel, { signal: controller.signal });
+  dialog.addEventListener("close", handleDialogClose, { signal: controller.signal });
+
+  // Let modern browsers know the intended native close policy. Backdrop click
+  // is still handled above so animation remains consistent across browsers.
+  if ("closedBy" in dialog) {
+    // Keep native Esc/back close requests, but handle backdrop clicks ourselves
+    // so animated light dismiss behaves consistently across browsers.
+    dialog.closedBy = "closerequest";
+  }
+
+  dialogMap.set(dialog, state);
+  wiredDialogs.add(dialog);
+  syncModalOpenClass(dialog.ownerDocument);
+  return state;
+}
+
+function connectDialog(dialog) {
+  ensureDialogWired(dialog);
+}
+
+function disconnectDialog(dialog) {
+  const state = dialogMap.get(dialog);
+  if (!state) return;
+
+  if (state.staticTimer) {
+    window.clearTimeout(state.staticTimer);
+  }
+
+  state.controller.abort();
+  dialog.classList.remove(CLASSES.static);
+  state.modalOpen = false;
+  dialogMap.delete(dialog);
+  wiredDialogs.delete(dialog);
+  syncModalOpenClass(dialog.ownerDocument);
+}
+
+registerCommands(DIALOG_COMMANDS, {
+  resolve: (trigger) => {
+    const dialog = targetFor(trigger);
+    return isDialogElement(dialog) ? dialog : null;
+  },
+  prepare: (trigger, dialog, command) => {
+    if (isDialog(dialog)) {
+      ensureDialogWired(dialog);
+    }
+
+    trigger.setAttribute("aria-controls", dialog.id);
+
+    if (
+      !trigger.hasAttribute("aria-haspopup") &&
+      (command === "show-modal" || command === "show")
+    ) {
+      trigger.setAttribute("aria-haspopup", "dialog");
+    }
+  },
+  handle: (event, trigger, dialog, command) => {
+    event.preventDefault();
+
+    if (!isDialog(dialog)) {
+      if (command === "show-modal" || command === "show") {
+        notifyUnsupportedDialog(trigger);
+      }
+      return;
+    }
+
+    if (command === "show-modal" || command === "show") {
+      openDialogWithViewTransition(dialog, trigger, command === "show-modal");
+      return;
+    }
+
+    if (command === "request-close") {
+      requestDialogClose(dialog, trigger.value || "");
+      return;
+    }
+
+    if (command === "close") {
+      closeDialog(dialog, trigger.value || "");
+    }
+  },
+});
+
+if (supportsDialog()) {
+  enhance({
+    [DIALOG_SELECTOR]: (dialog) => {
+      connectDialog(dialog);
+      return () => disconnectDialog(dialog);
+    },
+  });
+}

package/src/js/enhance.js

@@ -0,0 +1,208 @@
+/*
+ * Enhance — DOM lifecycle engine for behavioral enhancers.
+ *
+ * One MutationObserver per root watches DOM insertions/removals. Multiple calls
+ * to enhance() share that observer while keeping separate teardown handles.
+ *
+ * Sweep (not removedNodes scanning) is the key design choice: it reasons
+ * 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.
+ *
+ * enhancers: { [selector]: (el) => cleanup | void }
+ * Returns: { refresh, forget, disconnect }
+ */
+
+const registries = new WeakMap();
+
+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
+  );
+}
+
+function createRegistry(root) {
+  const records = new Set();
+  let selectorString = "";
+
+  function isValidSelector(selector) {
+    try {
+      root.querySelector?.(selector);
+      if (root instanceof Element) root.matches(selector);
+      return true;
+    } catch (error) {
+      console.error(`Invalid enhancer selector "${selector}"`, error);
+      return false;
+    }
+  }
+
+  function updateSelectorString() {
+    selectorString = [...records].flatMap((record) => record.selectors).join(",");
+  }
+
+  function start(record, el) {
+    if (!(el instanceof Element)) return;
+    let active = record.instances.get(el);
+
+    for (const selector of record.selectors) {
+      if (!el.matches(selector)) continue;
+      if (active?.has(selector)) continue;
+
+      let cleanup;
+      try {
+        cleanup = record.enhancers[selector](el);
+      } catch (error) {
+        console.error(`Enhancer failed for selector "${selector}"`, error);
+        continue;
+      }
+      if (!active) {
+        active = new Map();
+        record.instances.set(el, active);
+      }
+      active.set(selector, typeof cleanup === "function" ? cleanup : null);
+    }
+  }
+
+  function stop(record, el) {
+    const active = record.instances.get(el);
+    if (!active) return;
+    for (const cleanup of active.values()) {
+      cleanup?.();
+    }
+    record.instances.delete(el);
+  }
+
+  function scanFor(record, node) {
+    if (!canScan(node)) return;
+    if (node instanceof Element) start(record, node);
+    if (record.selectorString) {
+      node.querySelectorAll?.(record.selectorString).forEach((el) => {
+        start(record, el);
+      });
+    }
+  }
+
+  function scan(node) {
+    if (!canScan(node) || !selectorString) return;
+    if (node instanceof Element) {
+      for (const record of records) start(record, node);
+    }
+    node.querySelectorAll?.(selectorString).forEach((el) => {
+      for (const record of records) start(record, el);
+    });
+  }
+
+  function sweepDisconnected() {
+    for (const record of records) {
+      for (const el of Array.from(record.instances.keys())) {
+        if (!el.isConnected) stop(record, el);
+      }
+    }
+  }
+
+  const observer = new MutationObserver((mutationRecords) => {
+    let hasRemoval = false;
+    for (const mutationRecord of mutationRecords) {
+      for (const node of mutationRecord.addedNodes) {
+        scan(node);
+      }
+      if (mutationRecord.removedNodes.length > 0) {
+        hasRemoval = true;
+      }
+    }
+    if (hasRemoval) sweepDisconnected();
+  });
+
+  observer.observe(root, { childList: true, subtree: true });
+
+  return {
+    add(enhancers) {
+      const selectors = Object.keys(enhancers).filter(isValidSelector);
+      if (!selectors.length) return null;
+      const validEnhancers = Object.fromEntries(
+        selectors.map((selector) => [selector, enhancers[selector]]),
+      );
+
+      const record = {
+        disconnected: false,
+        enhancers: validEnhancers,
+        instances: new Map(),
+        selectors,
+        selectorString: selectors.join(","),
+      };
+      records.add(record);
+      updateSelectorString();
+      scanFor(record, root);
+      return record;
+    },
+    refresh(record, node) {
+      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;
+      for (const el of Array.from(record.instances.keys())) {
+        stop(record, el);
+      }
+      records.delete(record);
+      updateSelectorString();
+      if (records.size === 0) {
+        observer.disconnect();
+        registries.delete(root);
+      }
+    },
+  };
+}
+
+function registryFor(root) {
+  let registry = registries.get(root);
+  if (!registry) {
+    registry = createRegistry(root);
+    registries.set(root, registry);
+  }
+  return registry;
+}
+
+/**
+ * @param {Record<string, (el: Element) => (() => void) | void>} enhancers
+ * @param {Document | Element | DocumentFragment} [root]
+ * @returns {{ refresh: (node: Node) => void, forget: (el: Element) => void, disconnect: () => void }}
+ */
+export default function enhance(enhancers, root) {
+  if (typeof document === "undefined") {
+    return noopRuntime();
+  }
+
+  root ??= document.documentElement;
+  const registry = registryFor(root);
+  const record = registry.add(enhancers);
+  if (!record) return noopRuntime();
+
+  return {
+    refresh: (node) => registry.refresh(record, node),
+    forget: (el) => {
+      registry.forget(record, el);
+    },
+    disconnect: () => {
+      registry.remove(record);
+    },
+  };
+}