@revealui/core 0.0.1-pre.1 → 0.0.1-pre.2

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

@@ -1,94 +0,0 @@
-export { executeOnRenderClientHook };
-export type { PageContextBeforeRenderClient };
-
-import { getHook, type Hook } from "../../processing/getters/getHook.js";
-import { assert, executeHook } from "../server/utils.js";
-
-import { PageConfigRuntime } from "../../../types/interfaces/page.js";
-import { PageContextExports } from "../../processing/getters/getPageFiles/index.js";
-
-import {
-  type PageContextForUserConsumptionClientSide,
-  preparePageContextForUserConsumptionClientSide,
-} from "./preparePageContextForUserConsumptionClientSide.js";
-import { assertUsage } from "../../gaurds/assertions/assertUsage/index.js";
-import {PageFile} from "../../__internal/index.js";
-
-type PageContextBeforeRenderClient = {
-  _pageFilesLoaded: PageFile[];
-  urlOriginal?: string;
-  urlPathname?: string;
-  pageId: string;
-  _pageConfigs: PageConfigRuntime[];
-} & PageContextExports &
-  PageContextForUserConsumptionClientSide;
-
-async function executeOnRenderClientHook<
-  PC extends PageContextBeforeRenderClient,
->(pageContext: PC, isClientRouting: boolean): Promise<void> {
-  const pageContextForUserConsumption =
-    preparePageContextForUserConsumptionClientSide(
-      pageContext,
-      isClientRouting,
-    );
-
-  let hook: null | Hook = null;
-  let hookName: "onRenderClient";
-
-  {
-    const renderHook = getHook(pageContext, "onRenderClient");
-    hook = renderHook;
-    hookName = "onRenderClient";
-  }
-  {
-    const renderHook = getHook(pageContext, "onRenderClient");
-    if (renderHook) {
-      hook = renderHook;
-      hookName = "onRenderClient";
-    }
-  }
-
-  if (!hook) {
-    const urlToShowToUser = getUrlToShowToUser(pageContext);
-    assert(urlToShowToUser);
-    if (pageContext._pageConfigs.length > 0) {
-      // V1 design
-      assertUsage(
-        false,
-        `No onRenderClient() hook defined for URL '${urlToShowToUser}', but it's needed.`,
-      );
-    }
-  }
-
-  assert(hook);
-  const renderHook = hook.hookFn;
-  assert(hookName);
-
-  // We don't use a try-catch wrapper because rendering errors are usually handled by the UI framework. (E.g. React's Error Boundaries.)
-  const hookResult = await executeHook(
-    () => renderHook(pageContextForUserConsumption),
-    hook,
-    pageContext,
-  );
-  assertUsage(
-    hookResult === undefined,
-    `The ${hookName}() hook defined by ${hook.hookFilePath} isn't allowed to return a value`,
-  );
-}
-
-function getUrlToShowToUser(pageContext: {
-  urlOriginal?: string;
-  urlPathname?: string;
-}): string {
-  let url: string | undefined;
-  // try/catch to avoid passToClient assertUsage() (although: this may not be needed anymore, since we're now accessing pageContext and not pageContextForUserConsumption)
-  try {
-    url =
-      // Client Routing
-      pageContext.urlPathname ??
-      // Server Routing
-      pageContext.urlOriginal;
-  } catch {}
-  url = url ?? window.location.href;
-  return url;
-}

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

@@ -1,142 +0,0 @@
-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

@@ -1,9 +0,0 @@
-// 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

@@ -1,48 +0,0 @@
-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

@@ -1,54 +0,0 @@
-// 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

@@ -1,92 +0,0 @@
-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

@@ -1,45 +0,0 @@
-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

@@ -1,85 +0,0 @@
-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

@@ -1,10 +0,0 @@
-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

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

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

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