@revealui/core 0.0.1-pre.0

package/dist/core/targets/client/history.ts

@@ -0,0 +1,142 @@
+import { hasProp } from "../../gaurds/validators/hasProp.js"
+import { isObject } from "../../gaurds/validators/isObject.js"
+import { assert, assertUsage } from "../../utils/index.js"
+
+export {
+  getHistoryState,
+  initHistoryState,
+  monkeyPatchHistoryPushState,
+  pushHistory,
+  saveScrollPosition,
+  ScrollPosition,
+}
+
+// import { assert, assertUsage, hasProp, isObject } from "./utils.js";
+
+type HistoryState = {
+  timestamp?: number
+  scrollPosition?: null | ScrollPosition
+  triggeredBy?: "user" | "reveal" | "browser"
+  _isRevealEnhanced: true
+}
+type ScrollPosition = { x: number; y: number }
+
+// Fill missing state information:
+//  - `history.state` can uninitialized (i.e. `null`):
+//    - The very first render
+//    - The user's code runs `location.hash = '#section'`
+//    - The user clicks on an anchor link `<a href="#section">Section</a>` (Reveal's `initOnLinkClick()` handler skips hash links).
+//  - State information may be incomplete if `history.state` is set by an old Reveal version. (E.g. `state.timestamp` was introduced for `pageContext.isBackwardNavigation` in `0.4.19`.)
+function initHistoryState() {
+  // No way found to add TypeScript types to `window.history.state`: https://github.com/microsoft/TypeScript/issues/36178
+  let state: HistoryState = window.history.state
+  if (!state) {
+    state = { _isRevealEnhanced: true }
+  }
+  let hasModifications = false
+  if (!("timestamp" in state)) {
+    hasModifications = true
+    state.timestamp = getTimestamp()
+  }
+  if (!("scrollPosition" in state)) {
+    hasModifications = true
+    state.scrollPosition = getScrollPosition()
+  }
+  if (!("triggeredBy" in state)) {
+    state.triggeredBy = "browser"
+  }
+  assertState(state)
+  if (hasModifications) {
+    replaceHistoryState(state)
+  }
+}
+
+function getHistoryState(): HistoryState {
+  const state: unknown = window.history.state || {}
+  assertState(state)
+  return state
+}
+
+function getScrollPosition(): ScrollPosition {
+  const scrollPosition = { x: window.scrollX, y: window.scrollY }
+  return scrollPosition
+}
+function getTimestamp() {
+  return new Date().getTime()
+}
+
+function saveScrollPosition() {
+  const scrollPosition = getScrollPosition()
+  const state = getHistoryState()
+  replaceHistoryState({ ...state, scrollPosition })
+}
+
+function pushHistory(url: string, overwriteLastHistoryEntry: boolean) {
+  if (!overwriteLastHistoryEntry) {
+    const timestamp = getTimestamp()
+    pushHistoryState(
+      {
+        timestamp,
+        scrollPosition: null,
+        triggeredBy: "reveal",
+        _isRevealEnhanced: true,
+      },
+      url
+    )
+  } else {
+    replaceHistoryState(getHistoryState(), url)
+  }
+}
+
+function assertState(state: unknown): asserts state is HistoryState {
+  assert(isObject(state))
+
+  if ("timestamp" in state) {
+    const { timestamp } = state
+    assert(typeof timestamp === "number")
+  }
+
+  if ("scrollPosition" in state) {
+    const { scrollPosition } = state
+    if (scrollPosition !== null) {
+      assert(
+        hasProp(scrollPosition, "x", "number") &&
+          hasProp(scrollPosition, "y", "number")
+      )
+    }
+  }
+}
+function replaceHistoryState(state: HistoryState, url?: string) {
+  const url_ = url ?? null // Passing `undefined` chokes older Edge versions.
+  window.history.replaceState(state, "", url_)
+}
+function pushHistoryState(state: HistoryState, url: string) {
+  // Reveal should call window.history.pushState() (and not the orignal `pushStateOriginal()`) so that other tools (e.g. user tracking) can listen to Reveal's pushState() calls, see https://github.com/revealjs/reveal/issues/1582.
+  window.history.pushState(state, "", url)
+}
+
+function monkeyPatchHistoryPushState() {
+  const pushStateOriginal = window.history.pushState.bind(window.history)
+  window.history.pushState = (stateOriginal: unknown = {}, ...rest) => {
+    assertUsage(
+      stateOriginal === undefined ||
+        stateOriginal === null ||
+        isObject(stateOriginal),
+      "history.pushState(state) argument state must be an object"
+    )
+    const stateEnhanced: HistoryState = isRevealEnhanced(stateOriginal)
+      ? stateOriginal
+      : {
+          _isRevealEnhanced: true,
+          scrollPosition: getScrollPosition(),
+          timestamp: getTimestamp(),
+          triggeredBy: "user",
+          ...stateOriginal,
+        }
+    return pushStateOriginal!(stateEnhanced, ...rest)
+  }
+}
+
+function isRevealEnhanced(state: unknown): state is HistoryState {
+  return isObject(state) && "_isRevealEnhanced" in state
+}

package/dist/core/targets/client/index.ts

@@ -0,0 +1,9 @@
+// TODO/v1-release - move:
+//   import { navigate, prefetch } from 'reveal/client/router'
+// to:
+//   import { navigate, prefetch } from 'reveal'
+// Use package.json#exports to make the imports isomorphic.
+
+export { PROJECT_VERSION as version } from "../../globals/versions/PROJECT_VERSION.js";
+export { navigate, reload } from "./navigate.js";
+export { prefetch } from "./prefetch.js";

package/dist/core/targets/client/initClientRouter.ts

@@ -0,0 +1,48 @@
+export { initClientRouter };
+
+import { assert } from "../../gaurds/assertions/assert/index.js";
+import { initHistoryState, monkeyPatchHistoryPushState } from "./history.js";
+import { initOnLinkClick } from "./initOnLinkClick.js";
+import { onBrowserHistoryNavigation } from "./onBrowserHistoryNavigation.js";
+import { initLinkPrefetchHandlers } from "./prefetch.js";
+import {
+  getRenderCount,
+  renderPageClientSide,
+} from "./renderPageClientSide.js";
+import { setupNativeScrollRestoration } from "./scrollRestoration.js";
+import { autoSaveScrollPosition } from "./setScrollPosition.js";
+
+async function initClientRouter() {
+  // Init navigation history and scroll restoration
+  initHistoryAndScroll();
+
+  // Render/hydrate
+  const renderFirstPagePromise = renderFirstPage();
+
+  // Intercept <a> clicks
+  initOnLinkClick();
+
+  // Add <a> prefetch handlers
+  initLinkPrefetchHandlers();
+
+  // Preserve stack track
+  await renderFirstPagePromise;
+}
+
+async function renderFirstPage() {
+  assert(getRenderCount() === 0);
+  await renderPageClientSide({
+    scrollTarget: { preserveScroll: true },
+    isBackwardNavigation: null,
+    isClientSideNavigation: false,
+  });
+}
+
+function initHistoryAndScroll() {
+  setupNativeScrollRestoration();
+  initHistoryState();
+  autoSaveScrollPosition();
+  monkeyPatchHistoryPushState();
+  // Handle back-/forward navigation
+  onBrowserHistoryNavigation();
+}

package/dist/core/targets/client/initOnLinkClick.ts

@@ -0,0 +1,54 @@
+// Code adapted from https://github.com/HenrikJoreteg/internal-nav-helper/blob/5199ec5448d0b0db7ec63cf76d88fa6cad878b7d/src/index.js#L11-L29
+
+export { initOnLinkClick };
+
+import { assert } from "./utils.js";
+import { skipLink } from "./skipLink.js";
+import { renderPageClientSide } from "./renderPageClientSide.js";
+import type { ScrollTarget } from "./setScrollPosition.js";
+
+function initOnLinkClick() {
+  document.addEventListener("click", handler);
+}
+
+async function handler(ev: MouseEvent) {
+  if (!isNormalLeftClick(ev)) return;
+
+  const linkTag = findLinkTag(ev.target as HTMLElement);
+  if (!linkTag) return;
+
+  const url = linkTag.getAttribute("href");
+
+  if (skipLink(linkTag)) return;
+  assert(url);
+  ev.preventDefault();
+
+  let scrollTarget: ScrollTarget;
+  {
+    const v = linkTag.getAttribute("keep-scroll-position");
+    if (v !== null)
+      scrollTarget = { preserveScroll: v === "false" ? false : true };
+  }
+  await renderPageClientSide({
+    scrollTarget,
+    urlOriginal: url,
+    isBackwardNavigation: false,
+  });
+}
+
+function isNormalLeftClick(ev: MouseEvent): boolean {
+  return (
+    ev.button === 0 && !ev.ctrlKey && !ev.shiftKey && !ev.altKey && !ev.metaKey
+  );
+}
+
+function findLinkTag(target: HTMLElement): null | HTMLElement {
+  while (target.tagName !== "A") {
+    const { parentNode } = target;
+    if (!parentNode) {
+      return null;
+    }
+    target = parentNode as HTMLElement;
+  }
+  return target;
+}

package/dist/core/targets/client/loadUserFilesClientSide.ts

@@ -0,0 +1,92 @@
+export { isErrorFetchingStaticAssets, loadUserFilesClientSide };
+export type { PageContextUserFiles };
+
+import type {
+	PageConfigRuntime,
+	PageConfigRuntimeLoaded,
+} from "../../../types/interfaces/page.js";
+import type { PageFile } from "../../__internal/index.js";
+import { findPageConfig } from "../../config/findPageConfig.js";
+import { loadConfigValues } from "../../config/loadConfigValues.js";
+import {
+	getPageContextExports,
+	type PageContextExports,
+} from "../../processing/getters/getPageFiles/getExports.js";
+import { getPageFilesAll } from "../../processing/getters/getPageFiles/setPageFiles.js";
+import { objectAssign } from "../server/utils.js";
+
+const stamp = "__whileFetchingAssets";
+
+type PageContextUserFilesLoaded = PageContextExports & {
+	_pageFilesLoaded: PageFile[];
+};
+type PageContextUserFiles = {
+	_pageFilesAll: PageFile[];
+	_pageConfigs: PageConfigRuntime[];
+};
+async function loadUserFilesClientSide(
+	pageId: string,
+	pageFilesAll: PageFile[],
+	pageConfigs: PageConfigRuntime[],
+): Promise<PageContextUserFilesLoaded> {
+	const pageFilesClientSide = await getPageFilesAll(true);
+	const pageConfig = findPageConfig(pageConfigs, pageId);
+	let pageConfigLoaded: null | PageConfigRuntimeLoaded;
+
+	const isDev: boolean = import.meta.env.DEV;
+	try {
+		const result = await Promise.allSettled([
+			pageConfig && loadConfigValues(pageConfig, isDev),
+			...pageFilesClientSide.pageFilesAll.map((p) => p.loadFile?.()),
+		]);
+		if (result[0].status === "fulfilled") {
+			pageConfigLoaded = result[0].value as PageConfigRuntimeLoaded;
+		} else {
+			pageConfigLoaded = null;
+		}
+	} catch (err: unknown) {
+		if (isFetchError(err)) {
+			Object.assign(err as Record<string, unknown>, { [stamp]: true });
+		} else {
+			// A user file has a syntax error
+			console.error(err);
+		}
+		throw err;
+	}
+	const pageContextExports = getPageContextExports(pageConfigLoaded);
+	const pageContextAddendum = {};
+	objectAssign(pageContextAddendum, pageContextExports);
+	objectAssign(pageContextAddendum, {
+		_pageFilesLoaded: pageFilesClientSide.pageFilesAll,
+	});
+	return pageContextAddendum;
+}
+
+function isErrorFetchingStaticAssets(err: unknown) {
+	if (!err) {
+		return false;
+	}
+	return (err as Record<string, unknown>)[stamp] === true;
+}
+
+// https://stackoverflow.com/questions/75928310/how-to-detect-that-import-some-url-failed-because-some-url-isnt-a-javasc
+function isFetchError(err: unknown): boolean {
+	if (!(err instanceof Error)) return false;
+	// https://github.com/stacks-network/clarity-js-sdk/blob/e757666b59af00b5db04dd1bf0df016e3a459ea2/packages/clarity/src/providers/registry.ts#L40-L45
+	// https://github.com/modernweb-dev/web/blob/0a59b56e4c1b50af81fbf4588f36a1ceb71f3976/integration/test-runner/tests/test-failure/runTestFailureTest.ts#L11-L18
+	const FAILED_TO_FETCH_MESSAGES = [
+		// chromium
+		"Failed to fetch dynamically imported module",
+		// firefox
+		"error loading dynamically imported module",
+		// safari
+		"Importing a module script failed",
+		// ??
+		"error resolving module specifier",
+		// ??
+		"failed to resolve module",
+	];
+	return FAILED_TO_FETCH_MESSAGES.some((s) =>
+		err.message.toLowerCase().includes(s.toLowerCase()),
+	);
+}

package/dist/core/targets/client/navigate.ts

@@ -0,0 +1,45 @@
+export { navigate, reload }
+
+import { assertClientRouting } from "../../gaurds/assertions/assertRoutingType/index.js"
+import { normalizeUrlArgument } from "../../gaurds/normalization/normalizeUrlArgument.js"
+import { getCurrentUrl } from "../../processing/getters/getCurrentUrl.js"
+import {
+  firstRenderStartPromise,
+  renderPageClientSide,
+} from "./renderPageClientSide.js"
+import type { ScrollTarget } from "./setScrollPosition.js"
+
+assertClientRouting()
+
+/** Programmatically navigate to a new page.
+ *
+ * https://reveal.dev/navigate
+ *
+ * @param url - The URL of the new page.
+ * @param keepScrollPosition - Don't scroll to the top of the page, instead keep the current scroll position.
+ * @param overwriteLastHistoryEntry - Don't create a new entry in the browser's history, instead let the new URL replace the current URL. (This effectively removes the current URL from the browser history).
+ */
+async function navigate(
+  url: string,
+  {
+    keepScrollPosition = false,
+    overwriteLastHistoryEntry = false,
+  }: { keepScrollPosition?: boolean; overwriteLastHistoryEntry?: boolean } = {}
+): Promise<void> {
+  normalizeUrlArgument(url, "navigate")
+
+  // If `hydrationCanBeAborted === false` (e.g. Vue) then we can apply navigate() only after hydration is done
+  await firstRenderStartPromise
+
+  const scrollTarget: ScrollTarget = { preserveScroll: keepScrollPosition }
+  await renderPageClientSide({
+    scrollTarget,
+    urlOriginal: url,
+    overwriteLastHistoryEntry,
+    isBackwardNavigation: false,
+  })
+}
+
+async function reload(): Promise<void> {
+  await navigate(getCurrentUrl())
+}

package/dist/core/targets/client/onBrowserHistoryNavigation.ts

@@ -0,0 +1,85 @@
+export { onBrowserHistoryNavigation };
+export { updateState };
+
+import { getCurrentUrl } from "./utils.js";
+import { initHistoryState, getHistoryState } from "./history.js";
+import { renderPageClientSide } from "./renderPageClientSide.js";
+import { type ScrollTarget, setScrollPosition } from "./setScrollPosition.js";
+import getGlobalObject from "../../processing/getters/getGlobalObject.js";
+
+const globalObject = getGlobalObject<{
+  previousState: ReturnType<typeof getState>;
+}>("onBrowserHistoryNavigation.ts", { previousState: getState() });
+
+function onBrowserHistoryNavigation() {
+  // - The popstate event is trigged upon:
+  //   - Back-/forward navigation.
+  //     - By user clicking on his browser's back-/forward navigation (or using a shortcut)
+  //     - By JavaScript: `history.back()` / `history.forward()`
+  //   - URL hash change.
+  //     - By user clicking on a hash link `<a href="#some-hash" />`
+  //       - The popstate event is *only* triggered if `href` starts with '#' (even if `href` is '/#some-hash' while the current URL's pathname is '/' then the popstate still isn't triggered)
+  //     - By JavaScript: `location.hash = 'some-hash'`
+  // - The `event` argument of `window.addEventListener('popstate', (event) => /*...*/)` is useless: the History API doesn't provide the previous state (the popped state), see https://stackoverflow.com/questions/48055323/is-history-state-always-the-same-as-popstate-event-state
+  window.addEventListener("popstate", async (): Promise<undefined> => {
+    const currentState = getState();
+
+    const scrollTarget: ScrollTarget =
+      currentState.historyState.scrollPosition || undefined;
+
+    const isUserLandPushStateNavigation =
+      currentState.historyState.triggeredBy === "user";
+
+    const isHashNavigation =
+      currentState.urlWithoutHash === globalObject.previousState.urlWithoutHash;
+
+    const isBackwardNavigation =
+      !currentState.historyState.timestamp ||
+      !globalObject.previousState.historyState.timestamp
+        ? null
+        : currentState.historyState.timestamp <
+          globalObject.previousState.historyState.timestamp;
+
+    globalObject.previousState = currentState;
+
+    if (isHashNavigation && !isUserLandPushStateNavigation) {
+      // - `history.state` is uninitialized (`null`) when:
+      //   - The user's code runs `window.location.hash = '#section'`.
+      //   - The user clicks on an anchor link `<a href="#section">Section</a>` (because Reveal's `initOnLinkClick()` handler skips hash links).
+      // - `history.state` is `null` when uninitialized: https://developer.mozilla.org/en-US/docs/Web/API/History/state
+      // - Alternatively, we completely take over hash navigation and reproduce the browser's native behavior upon hash navigation.
+      //   - Problem: we cannot intercept `window.location.hash = '#section'`. (Or maybe we can with the `hashchange` event?)
+      //   - Other potential problem: would there be a conflict when the user wants to override the browser's default behavior? E.g. for smooth scrolling, or when using hashes for saving states of some fancy animations.
+      // - Another alternative: we use the browser's scroll restoration mechanism (see `browserNativeScrollRestoration_enable()` below).
+      //   - Problem: not clear when to call `browserNativeScrollRestoration_disable()`/`browserNativeScrollRestoration_enable()`
+      //   - Other potential problem are inconsistencies between browsers: specification says that setting `window.history.scrollRestoration` only affects the current entry in the session history. But this seems to contradict what folks saying.
+      //     - Specification: https://html.spec.whatwg.org/multipage/history.html#the-history-interface
+      //     - https://stackoverflow.com/questions/70188241/history-scrollrestoration-manual-doesnt-prevent-safari-from-restoring-scrol
+      if (window.history.state === null) {
+        // The browser already scrolled to `#${hash}` => the current scroll position is the right one => we save it with `initHistoryState()`.
+        initHistoryState();
+        globalObject.previousState = getState();
+      } else {
+        // If `history.state !== null` then it means that `popstate` was triggered by the user clicking on his browser's forward/backward history button.
+        setScrollPosition(scrollTarget);
+      }
+    } else {
+      await renderPageClientSide({
+        scrollTarget,
+        isBackwardNavigation,
+        isUserLandPushStateNavigation,
+      });
+    }
+  });
+}
+
+function getState() {
+  return {
+    urlWithoutHash: getCurrentUrl({ withoutHash: true }),
+    historyState: getHistoryState(),
+  };
+}
+
+function updateState() {
+  globalObject.previousState = getState();
+}

package/dist/core/targets/client/onLoad.ts

@@ -0,0 +1,10 @@
+import { assertIsBrowser } from "../../gaurds/assertions/assertIsBrowser";
+import { assertClientRouting } from "../../gaurds/assertions/assertRoutingType";
+
+export { onLoad };
+
+function onLoad() {
+  assertIsBrowser();
+  // Ensure we don't bloat the Server Routing runtime with Client Routing utils
+  assertClientRouting();
+}

package/dist/core/targets/client/pageContextInitIsPassedToClient.ts

@@ -0,0 +1,2 @@
+export const pageContextInitIsPassedToClient =
+  "_pageContextInitIsPassedToClient";

package/dist/core/targets/client/pageFiles.ts

@@ -0,0 +1,4 @@
+import { setPageFiles } from "../../processing/getters/getPageFiles/index.js";
+// @ts-ignore
+import * as pageFilesExports from "virtual:reveal:importUserCode:client:client-routing";
+setPageFiles(pageFilesExports);