@jsenv/navi 0.0.1

package/src/browser_integration/browser_integration.js

@@ -0,0 +1,191 @@
+import { useEffect, useRef } from "preact/hooks";
+import { updateActions } from "../actions.js";
+import {
+  setBrowserIntegration,
+  setOnRouteDefined,
+  updateRoutes,
+} from "../route/route.js";
+import {
+  documentIsBusySignal,
+  routingWhile,
+  windowIsLoadingSignal,
+  workingWhile,
+} from "./document_loading_signal.js";
+import { setupBrowserIntegrationViaHistory } from "./via_history.js";
+
+const applyActions = (params) => {
+  const updateActionsResult = updateActions(params);
+  const { allResult, runningActionSet } = updateActionsResult;
+  const pendingTaskNameArray = [];
+  for (const runningAction of runningActionSet) {
+    pendingTaskNameArray.push(runningAction.name);
+  }
+  workingWhile(() => allResult, pendingTaskNameArray);
+  return updateActionsResult;
+};
+
+const applyRouting = (
+  url,
+  { globalAbortSignal, abortSignal, state, replace, isVisited },
+) => {
+  const {
+    loadSet,
+    reloadSet,
+    abortSignalMap,
+    routeLoadRequestedMap,
+    activeRouteSet,
+  } = updateRoutes(url, { state, replace, isVisited });
+  if (loadSet.size === 0 && reloadSet.size === 0) {
+    return {
+      allResult: undefined,
+      requestedResult: undefined,
+      activeRouteSet: new Set(),
+    };
+  }
+  const updateActionsResult = updateActions({
+    globalAbortSignal,
+    abortSignal,
+    runSet: loadSet,
+    rerunSet: reloadSet,
+    abortSignalMap,
+    reason: `Document navigating to ${url}`,
+  });
+  const { allResult, runningActionSet } = updateActionsResult;
+  const pendingTaskNameArray = [];
+  for (const [route, routeAction] of routeLoadRequestedMap) {
+    if (runningActionSet.has(routeAction)) {
+      pendingTaskNameArray.push(`${route.relativeUrl} -> ${routeAction.name}`);
+    }
+  }
+  routingWhile(() => allResult, pendingTaskNameArray);
+  return { ...updateActionsResult, activeRouteSet };
+};
+
+const browserIntegration = setupBrowserIntegrationViaHistory({
+  applyActions,
+  applyRouting,
+});
+
+setOnRouteDefined(() => {
+  browserIntegration.init();
+});
+setBrowserIntegration(browserIntegration);
+
+export const actionIntegratedVia = browserIntegration.integration;
+export const goTo = browserIntegration.goTo;
+export const stopLoad = (reason = "stopLoad() called") => {
+  const windowIsLoading = windowIsLoadingSignal.value;
+  if (windowIsLoading) {
+    window.stop();
+  }
+  const documentIsBusy = documentIsBusySignal.value;
+  if (documentIsBusy) {
+    browserIntegration.stop(reason);
+  }
+};
+export const reload = browserIntegration.reload;
+export const goBack = browserIntegration.goBack;
+export const goForward = browserIntegration.goForward;
+export const isVisited = browserIntegration.isVisited;
+export const visitedUrlsSignal = browserIntegration.visitedUrlsSignal;
+export const handleActionTask = browserIntegration.handleActionTask;
+
+const idUsageMap = new Map();
+const useNavStateWithWarnings = (id, initialValue, options) => {
+  const idRef = useRef(undefined);
+  if (idRef.current !== id) {
+    const oldId = idRef.current;
+    idUsageMap.delete(oldId);
+    idRef.current = id;
+
+    const usage = idUsageMap.get(id);
+    if (!usage) {
+      idUsageMap.set(id, {
+        stackTrace: new Error().stack,
+      });
+    } else {
+      console.warn(
+        `useNavState ID conflict detected!
+ID "${id}" is already in use by another component.
+This can cause UI state conflicts and unexpected behavior.
+Consider using unique IDs for each component instance.`,
+      );
+    }
+  }
+
+  useEffect(() => {
+    return () => {
+      idUsageMap.delete(id);
+    };
+  }, [id]);
+
+  return useNavStateBasic(id, initialValue, options);
+};
+
+const NOT_SET = {};
+const NO_OP = () => {};
+const NO_ID_GIVEN = [undefined, NO_OP, NO_OP];
+const useNavStateBasic = (id, initialValue, { debug } = {}) => {
+  const navStateRef = useRef(NOT_SET);
+  if (!id) {
+    return NO_ID_GIVEN;
+  }
+
+  if (navStateRef.current === NOT_SET) {
+    const documentState = browserIntegration.getDocumentState();
+    const valueInDocumentState = documentState ? documentState[id] : undefined;
+    if (valueInDocumentState === undefined) {
+      navStateRef.current = initialValue;
+      if (initialValue !== undefined) {
+        console.debug(
+          `useNavState(${id}) initial value is ${initialValue} (from initialValue passed in as argument)`,
+        );
+      }
+    } else {
+      navStateRef.current = valueInDocumentState;
+      if (debug) {
+        console.debug(
+          `useNavState(${id}) initial value is ${initialValue} (from nav state)`,
+        );
+      }
+    }
+  }
+
+  const set = (value) => {
+    const currentValue = navStateRef.current;
+    if (typeof value === "function") {
+      value = value(currentValue);
+    }
+    if (debug) {
+      console.debug(
+        `useNavState(${id}) set ${value} (previous was ${currentValue})`,
+      );
+    }
+
+    const currentState = browserIntegration.getDocumentState() || {};
+    if (value === undefined) {
+      delete currentState[id];
+    } else {
+      currentState[id] = value;
+    }
+    browserIntegration.replaceDocumentState(currentState);
+  };
+
+  return [
+    navStateRef.current,
+    set,
+    () => {
+      set(undefined);
+    },
+  ];
+};
+
+export const useNavState = import.meta.dev
+  ? useNavStateWithWarnings
+  : useNavStateBasic;
+
+if (import.meta.hot) {
+  import.meta.hot.dispose(() => {
+    idUsageMap.clear();
+  });
+}

package/src/browser_integration/document_back_and_forward.js

@@ -0,0 +1,17 @@
+import { signal } from "@preact/signals";
+
+export const canGoBackSignal = signal(false);
+export const updateCanGoBack = (can) => {
+  canGoBackSignal.value = can;
+};
+export const useCanGoBack = () => {
+  return canGoBackSignal.value;
+};
+
+export const canGoForwardSignal = signal(false);
+export const updateCanGoForward = (can) => {
+  canGoBackSignal.value = can;
+};
+export const useCanGoForward = () => {
+  return canGoForwardSignal.value;
+};

package/src/browser_integration/document_loading_signal.js

@@ -0,0 +1,100 @@
+import { computed, signal } from "@preact/signals";
+import { arraySignal } from "../utils/array_signal.js";
+import { executeWithCleanup } from "../utils/execute_with_cleanup.js";
+
+let DEBUG = false;
+export const enableDebugOnDocumentLoading = () => {
+  DEBUG = true;
+};
+
+export const windowIsLoadingSignal = signal(true);
+if (document.readyState === "complete") {
+  windowIsLoadingSignal.value = false;
+} else {
+  document.addEventListener("readystatechange", () => {
+    if (document.readyState === "complete") {
+      windowIsLoadingSignal.value = false;
+    }
+  });
+}
+
+const [
+  documentLoadingRouteArraySignal,
+  addToDocumentLoadingRouteArraySignal,
+  removeFromDocumentLoadingRouteArraySignal,
+] = arraySignal([]);
+export { documentLoadingRouteArraySignal };
+export const routingWhile = (fn, routeNames = []) => {
+  if (DEBUG && routeNames.length > 0) {
+    console.debug(`routingWhile: Adding routes to loading state:`, routeNames);
+  }
+  addToDocumentLoadingRouteArraySignal(...routeNames);
+  return executeWithCleanup(fn, () => {
+    removeFromDocumentLoadingRouteArraySignal(...routeNames);
+    if (DEBUG && routeNames.length > 0) {
+      console.debug(
+        `routingWhile: Removed routes from loading state:`,
+        routeNames,
+        "state after removing:",
+        documentLoadingRouteArraySignal.peek(),
+      );
+    }
+  });
+};
+
+const [
+  documentLoadingActionArraySignal,
+  addToDocumentLoadingActionArraySignal,
+  removeFromDocumentLoadingActionArraySignal,
+] = arraySignal([]);
+export { documentLoadingActionArraySignal };
+export const workingWhile = (fn, actionNames = []) => {
+  if (DEBUG && actionNames.length > 0) {
+    console.debug(
+      `workingWhile: Adding actions to loading state:`,
+      actionNames,
+    );
+  }
+  addToDocumentLoadingActionArraySignal(...actionNames);
+  return executeWithCleanup(fn, () => {
+    removeFromDocumentLoadingActionArraySignal(...actionNames);
+    if (DEBUG && actionNames.length > 0) {
+      console.debug(
+        `routingWhile: Removed action from loading state:`,
+        actionNames,
+        "start after removing:",
+        documentLoadingActionArraySignal.peek(),
+      );
+    }
+  });
+};
+
+export const documentIsBusySignal = computed(() => {
+  return (
+    documentLoadingRouteArraySignal.value.length > 0 ||
+    documentLoadingActionArraySignal.value.length > 0
+  );
+});
+
+const documentLoadingReasonArraySignal = computed(() => {
+  const windowIsLoading = windowIsLoadingSignal.value;
+  const routesLoading = documentLoadingRouteArraySignal.value;
+  const actionsLoading = documentLoadingActionArraySignal.value;
+  const reasonArray = [];
+  if (windowIsLoading) {
+    reasonArray.push("window_loading");
+  }
+  if (routesLoading.length > 0) {
+    reasonArray.push("document_routing");
+  }
+  if (actionsLoading.length > 0) {
+    reasonArray.push("document_working");
+  }
+  return reasonArray;
+});
+export const useDocumentLoadingReasonArray = () => {
+  return documentLoadingReasonArraySignal.value;
+};
+export const useDocumentIsLoading = () => {
+  return documentLoadingReasonArraySignal.value.length > 0;
+};

package/src/browser_integration/document_state_signal.js

@@ -0,0 +1,9 @@
+import { signal } from "@preact/signals";
+
+export const documentStateSignal = signal(null);
+export const useDocumentState = () => {
+  return documentStateSignal.value;
+};
+export const updateDocumentState = (value) => {
+  documentStateSignal.value = value;
+};

package/src/browser_integration/document_url_signal.js

@@ -0,0 +1,9 @@
+import { signal } from "@preact/signals";
+
+export const documentUrlSignal = signal(window.location.href);
+export const useDocumentUrl = () => {
+  return documentUrlSignal.value;
+};
+export const updateDocumentUrl = (value) => {
+  documentUrlSignal.value = value;
+};

package/src/browser_integration/use_is_visited.js

@@ -0,0 +1,19 @@
+import { useMemo } from "preact/hooks";
+import { isVisited, visitedUrlsSignal } from "./browser_integration.js";
+
+/**
+ * Hook that reactively checks if a URL is visited.
+ * Re-renders when the visited URL set changes.
+ *
+ * @param {string} url - The URL to check
+ * @returns {boolean} Whether the URL has been visited
+ */
+export const useIsVisited = (url) => {
+  return useMemo(() => {
+    // Access the signal to create reactive dependency
+    // eslint-disable-next-line no-unused-expressions
+    visitedUrlsSignal.value;
+
+    return isVisited(url);
+  }, [url, visitedUrlsSignal.value]);
+};

package/src/browser_integration/via_history.js

@@ -0,0 +1,199 @@
+import { signal } from "@preact/signals";
+import { setActionDispatcher } from "../actions.js";
+import { executeWithCleanup } from "../utils/execute_with_cleanup.js";
+import { updateDocumentState } from "./document_state_signal.js";
+import { documentUrlSignal, updateDocumentUrl } from "./document_url_signal.js";
+
+export const setupBrowserIntegrationViaHistory = ({
+  applyActions,
+  applyRouting,
+}) => {
+  const { history } = window;
+
+  let globalAbortController = new AbortController();
+  const triggerGlobalAbort = (reason) => {
+    globalAbortController.abort(reason);
+    globalAbortController = new AbortController();
+  };
+
+  const dispatchActions = (params) => {
+    const { requestedResult } = applyActions({
+      globalAbortSignal: globalAbortController.signal,
+      abortSignal: new AbortController().signal,
+      ...params,
+    });
+    return requestedResult;
+  };
+  setActionDispatcher(dispatchActions);
+
+  const getDocumentState = () => {
+    return window.history.state ? { ...window.history.state } : null;
+  };
+
+  const replaceDocumentState = (newState) => {
+    const url = window.location.href;
+    window.history.replaceState(newState, null, url);
+    handleRoutingTask(url, { state: newState });
+  };
+
+  const historyStartAtStart = getDocumentState();
+  const visitedUrlSet = historyStartAtStart
+    ? new Set(historyStartAtStart.jsenv_visited_urls || [])
+    : new Set();
+
+  // Create a signal that tracks visited URLs for reactive updates
+  // Using a counter instead of the Set directly for better performance
+  // Links will check isVisited() when this signal changes
+  const visitedUrlsSignal = signal(0);
+
+  const isVisited = (url) => {
+    url = new URL(url, window.location.href).href;
+    return visitedUrlSet.has(url);
+  };
+  const markUrlAsVisited = (url) => {
+    if (visitedUrlSet.has(url)) {
+      return;
+    }
+    visitedUrlSet.add(url);
+
+    // Increment signal to notify subscribers that visited URLs changed
+    visitedUrlsSignal.value++;
+
+    const historyState = getDocumentState() || {};
+    const hsitoryStateWithVisitedUrls = {
+      ...historyState,
+      jsenv_visited_urls: Array.from(visitedUrlSet),
+    };
+    window.history.replaceState(
+      hsitoryStateWithVisitedUrls,
+      null,
+      window.location.href,
+    );
+    updateDocumentState(hsitoryStateWithVisitedUrls);
+  };
+
+  let abortController = null;
+  const handleRoutingTask = (url, { state, replace }) => {
+    markUrlAsVisited(url);
+    updateDocumentUrl(url);
+    updateDocumentState(state);
+    if (abortController) {
+      abortController.abort(`navigating to ${url}`);
+    }
+    abortController = new AbortController();
+
+    const { allResult, requestedResult } = applyRouting(url, {
+      globalAbortSignal: globalAbortController.signal,
+      abortSignal: abortController.signal,
+      state,
+      replace,
+      isVisited,
+    });
+
+    executeWithCleanup(
+      () => allResult,
+      () => {
+        abortController = undefined;
+      },
+    );
+    return requestedResult;
+  };
+
+  // Browser event handlers
+  window.addEventListener(
+    "click",
+    (e) => {
+      if (e.button !== 0) {
+        // Ignore non-left clicks
+        return;
+      }
+      if (e.metaKey) {
+        // Ignore clicks with meta key (e.g. open in new tab)
+        return;
+      }
+      const linkElement = e.target.closest("a");
+      if (!linkElement) {
+        return;
+      }
+      const href = linkElement.href;
+      if (!href || !href.startsWith(window.location.origin)) {
+        return;
+      }
+      if (linkElement.hasAttribute("data-readonly")) {
+        return;
+      }
+      // TODO: ignore anchor navigation
+      e.preventDefault();
+      const state = null;
+      history.pushState(state, null, href);
+      handleRoutingTask(href, { state });
+    },
+    { capture: true },
+  );
+
+  window.addEventListener(
+    "submit",
+    () => {
+      // TODO: Handle form submissions
+    },
+    { capture: true },
+  );
+
+  window.addEventListener("popstate", (popstateEvent) => {
+    const url = window.location.href;
+    const state = popstateEvent.state;
+    handleRoutingTask(url, { state });
+  });
+
+  const goTo = async (url, { state = null, replace } = {}) => {
+    const currentUrl = documentUrlSignal.peek();
+    if (url === currentUrl) {
+      return;
+    }
+    if (replace) {
+      window.history.replaceState(state, null, url);
+    } else {
+      window.history.pushState(state, null, url);
+    }
+    handleRoutingTask(url, { state, replace });
+  };
+
+  const stop = (reason = "stop called") => {
+    triggerGlobalAbort(reason);
+  };
+
+  const reload = () => {
+    const url = window.location.href;
+    const state = history.state;
+    handleRoutingTask(url, { state });
+  };
+
+  const goBack = () => {
+    window.history.back();
+  };
+
+  const goForward = () => {
+    window.history.forward();
+  };
+
+  const init = () => {
+    const url = window.location.href;
+    const state = history.state;
+    history.replaceState(state, null, url);
+    handleRoutingTask(url, { state, replace: true });
+  };
+
+  return {
+    integration: "browser_history_api",
+    init,
+    goTo,
+    stop,
+    reload,
+    goBack,
+    goForward,
+    getDocumentState,
+    replaceDocumentState,
+    isVisited,
+    visitedUrlsSignal,
+  };
+};