@revealui/core 0.0.1-pre.0

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

@@ -0,0 +1,399 @@
+export {
+  addLinkPrefetchHandlers,
+  addLinkPrefetchHandlers_unwatch,
+  addLinkPrefetchHandlers_watch,
+  getPageContextPrefetched,
+  initLinkPrefetchHandlers,
+  populatePageContextPrefetchCache,
+  prefetch,
+}
+
+import pc from "@brillout/picocolors"
+
+import { PageConfigRuntime } from "../../../types/interfaces/page.js"
+import { assert } from "../../gaurds/assertions/assert/base.js"
+import {
+  assertClientRouting,
+  checkIfClientRouting,
+} from "../../gaurds/assertions/assertRoutingType/index.js"
+import { assertUsage } from "../../gaurds/assertions/assertUsage/base.js"
+import { assertWarning } from "../../gaurds/assertions/assertWarning/index.js"
+import { normalizeUrlArgument } from "../../gaurds/normalization/normalizeUrlArgument.js"
+import { isClientSideRoutable } from "../../gaurds/validators/isClientSideRoutable.js"
+import getGlobalObject from "../../processing/getters/getGlobalObject.js"
+import { getPageContextCurrent } from "../../processing/getters/getPageContextCurrent.js"
+import {
+  type PageContextFromServerHooks,
+  getPageContextFromServerHooks,
+} from "../../processing/getters/getPageContextFromHooks.js"
+import { PageContextExports } from "../../processing/getters/getPageFiles/index.js"
+import {
+  PAGE_CONTEXT_MAX_AGE_DEFAULT,
+  type PrefetchSettingResolved,
+  getPrefetchSettings,
+} from "../../processing/getters/getPrefetchSettingResolved.ts.js"
+import { type PageContextFromRoute, route } from "../../router/index.js"
+import { noRouteMatch } from "../../router/noRouteMatch.js"
+import { createPageContext } from "./createPageContext.js"
+import {
+  type PageContextUserFiles,
+  isErrorFetchingStaticAssets,
+  loadUserFilesClientSide,
+} from "./loadUserFilesClientSide.js"
+import { disableClientRouting } from "./renderPageClientSide.js"
+import { skipLink } from "./skipLink.js"
+import { hasProp, objectAssign } from "./utils.js"
+import {PageFile} from "../../__internal/index.js"
+
+assertClientRouting()
+const globalObject = getGlobalObject("prefetch.ts", {
+  linkPrefetchHandlerAdded: new WeakSet<HTMLElement>(),
+  addLinkPrefetchHandlers_debounce: null as null | ReturnType<
+    typeof setTimeout
+  >,
+  mutationObserver: new MutationObserver(addLinkPrefetchHandlers),
+  // `linkTags` [is automatically updated](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCollection#:~:text=An%20HTMLCollection%20in%20the%20HTML%20DOM%20is%20live%3B%20it%20is%20automatically%20updated%20when%20the%20underlying%20document%20is%20changed.)
+  linkTags: document.getElementsByTagName(
+    "A"
+  ) as HTMLCollectionOf<HTMLAnchorElement>,
+  prefetchedPageContexts: {} as Record<
+    string, // URL
+    PrefetchedPageContext
+  >,
+})
+
+type ResultPageContextFromServer = Awaited<
+  ReturnType<typeof getPageContextFromServerHooks>
+>
+type PrefetchedPageContext = {
+  resultFetchedAt: number
+  resultMaxAge: number
+  result: ResultPageContextFromServer
+}
+type PageContextForPrefetch = {
+  urlOriginal: string
+  urlPathname: string
+  pageId: string
+  _urlRewrite: null
+  _pageFilesAll: PageFile[]
+  _pageConfigs: PageConfigRuntime[]
+  config: PageConfigRuntime & {
+    [key: string]: unknown
+    Page: Record<string, unknown>
+  }
+}
+
+function getPageContextPrefetched(
+  pageContext: {
+    urlPathname: string
+  } & PageContextExports
+): null | PageContextFromServerHooks {
+  const prefetchSettings = getPrefetchSettings(pageContext, null)
+  // TODO/pageContext-prefetch: I guess we need linkTag to make this condition work
+  if (!prefetchSettings.pageContext) return null
+  const key = getCacheKey(pageContext.urlPathname)
+  const found = globalObject.prefetchedPageContexts[key]
+  if (!found || found.result.is404ServerSideRouted || isExpired(found))
+    return null
+  const pageContextPrefetched = found.result.pageContextFromServerHooks
+  /* TODO/pageContext-prefetch: make it work for when resultMaxAge is Infinity.
+  // We discard the prefetched pageContext whenever we use it, so that the user always sees fresh data upon naivgating.
+  delete globalObject.prefetchedPageContexts[key]
+  */
+  return pageContextPrefetched
+}
+
+async function prefetchAssets(
+  pageContextLink: { pageId: string } & PageContextUserFiles
+): Promise<void> {
+  try {
+    await loadUserFilesClientSide(
+      pageContextLink.pageId,
+      pageContextLink._pageFilesAll,
+      pageContextLink._pageConfigs
+    )
+  } catch (err) {
+    if (isErrorFetchingStaticAssets(err)) {
+      disableClientRouting(err, true)
+    } else {
+      throw err
+    }
+  }
+}
+
+async function prefetchPageContextFromServerHooks(
+  pageContextLink: PageContextForPrefetch,
+  resultMaxAge: number | null
+): Promise<void> {
+  const result = await getPageContextFromServerHooks(pageContextLink, false)
+  setPageContextPrefetchCache(pageContextLink, result, resultMaxAge)
+}
+function populatePageContextPrefetchCache(
+  pageContext: PageContextForPrefetch /*& PageContextExports*/,
+  result: ResultPageContextFromServer
+): void {
+  // TODO/pageContext-prefetch: replace with using pageContext.config.prerender instead. (For being able to do that: eager configs need to be accessible without have to use PageContextExports as it isn't available here.)
+  if (!isBrilloutDocpress()) return
+  setPageContextPrefetchCache(pageContext, result, null)
+}
+function setPageContextPrefetchCache(
+  pageContext: PageContextForPrefetch,
+  result: ResultPageContextFromServer,
+  resultMaxAge: number | null
+) {
+  if (resultMaxAge === null) resultMaxAge = getResultMaxAge()
+  const key = getCacheKey(pageContext.urlPathname)
+  assert(isBrilloutDocpress()) // Ensure this API isn't used by anyone else
+  globalObject.prefetchedPageContexts[key] = {
+    resultFetchedAt: Date.now(),
+    resultMaxAge,
+    result,
+  }
+}
+function getResultMaxAge(): number {
+  const pageContextCurrent = getPageContextCurrent()
+  // TODO/pageContext-prefetch: remove this dirty hack used by @brillout/docpress and, instead, use reveal's default if pageContextCurrent isn't defined yet.
+  if (!pageContextCurrent) return Infinity
+  const prefetchSettings = getPrefetchSettings(pageContextCurrent, null)
+  const resultMaxAge =
+    typeof prefetchSettings.pageContext === "number"
+      ? prefetchSettings.pageContext
+      : PAGE_CONTEXT_MAX_AGE_DEFAULT
+  return resultMaxAge
+}
+
+/**
+ * Programmatically prefetch client assets.
+ *
+ * https://reveal.dev/prefetch
+ *
+ * @param url - The URL of the page you want to prefetch.
+ */
+async function prefetch(
+  url: string,
+  /* TODO/pageContext-prefetch
+  options?: {
+    pageContext?: boolean
+    staticAssets?: boolean
+  }
+  */
+  options_?: {
+    pageContext?: boolean
+  }
+): Promise<void> {
+  const options = {
+    staticAssets: true,
+    pageContext: options_?.pageContext ?? false,
+  }
+
+  assertUsage(
+    checkIfClientRouting(),
+    "prefetch() only works with Client Routing, see https://reveal.dev/prefetch",
+    {
+      showStackTrace: true,
+    }
+  )
+  url = normalizeUrlArgument(url, "prefetch")
+
+  const pageContextLink = await getPageContextLink(url)
+  if (!pageContextLink?.pageId) {
+    assertWarning(false, `[prefetch(url)] ${pc.string(url)} ${noRouteMatch}`, {
+      showStackTrace: true,
+      onlyOnce: false,
+    })
+    return
+  }
+  assert(hasProp(pageContextLink, "pageId", "string")) // help TypeScript
+
+  await Promise.allSettled([
+    (async () => {
+      if (options?.staticAssets !== false) {
+        await prefetchAssets(pageContextLink)
+      }
+    })(),
+    (async () => {
+      if (options?.pageContext !== false) {
+        assertUsage(
+          isBrilloutDocpress(),
+          "prefetching pageContext isn't supported yet"
+        )
+        const resultMaxAge =
+          typeof options?.pageContext === "number" ? options.pageContext : null
+        if (pageContextLink.config.pageId) {
+          await prefetchPageContextFromServerHooks(
+            {
+              ...pageContextLink,
+              config: {
+                ...pageContextLink.config,
+                pageId: pageContextLink.config.pageId!,
+              },
+            } as PageContextForPrefetch,
+            resultMaxAge
+          )
+        }
+      }
+    })(),
+  ])
+}
+
+// Lazy execution logic copied from: https://github.com/withastro/astro/blob/2594eb088d53a98181ac820243bcb1a765856ecf/packages/astro/src/runtime/client/dev-toolbar/apps/audit/index.ts#L53-L72
+function addLinkPrefetchHandlers() {
+  if (globalObject.addLinkPrefetchHandlers_debounce)
+    clearTimeout(globalObject.addLinkPrefetchHandlers_debounce)
+  globalObject.addLinkPrefetchHandlers_debounce = setTimeout(() => {
+    // Wait for the next idle period, as it is less likely to interfere with any other work the browser is doing post-mutation.
+    if ("requestIdleCallback" in window) {
+      requestIdleCallback(addLinkPrefetchHandlers_apply, { timeout: 300 })
+    } else {
+      // Fallback for old versions of Safari, we'll assume that things are less likely to be busy after 150ms.
+      setTimeout(addLinkPrefetchHandlers_apply, 150)
+    }
+  }, 250)
+}
+function initLinkPrefetchHandlers() {
+  addLinkPrefetchHandlers()
+}
+function addLinkPrefetchHandlers_watch(): void {
+  // Notes about performance:
+  // - https://stackoverflow.com/questions/31659567/performance-of-mutationobserver-to-detect-nodes-in-entire-dom/39332340#39332340
+  // - https://news.ycombinator.com/item?id=15274211
+  //   - https://github.com/kubetail-org/sentineljs
+  // - https://stackoverflow.com/questions/55046093/listening-for-changes-in-htmlcollection-or-achieving-a-similar-effect
+  globalObject.mutationObserver.observe(document.body, {
+    childList: true,
+    subtree: true,
+  })
+}
+function addLinkPrefetchHandlers_unwatch(): void {
+  globalObject.mutationObserver.disconnect()
+}
+function addLinkPrefetchHandlers_apply(): void {
+  for (let linkTag of globalObject.linkTags) {
+    if (globalObject.linkPrefetchHandlerAdded.has(linkTag)) continue
+    globalObject.linkPrefetchHandlerAdded.add(linkTag)
+
+    if (skipLink(linkTag)) continue
+
+    linkTag.addEventListener(
+      "mouseover",
+      () => {
+        prefetchOnEvent(linkTag, "hover")
+      },
+      { passive: true }
+    )
+
+    linkTag.addEventListener(
+      "touchstart",
+      () => {
+        prefetchOnEvent(linkTag, "hover")
+      },
+      { passive: true }
+    )
+
+    const observer = new IntersectionObserver((entries) => {
+      entries.forEach((entry) => {
+        if (entry.isIntersecting) {
+          prefetchOnEvent(linkTag, "viewport")
+        }
+      })
+    })
+    observer.observe(linkTag)
+  }
+}
+
+async function prefetchOnEvent(
+  linkTag: HTMLAnchorElement,
+  event: "hover" | "viewport"
+): Promise<void> {
+  let prefetchSettings: PrefetchSettingResolved
+  const pageContextCurrent = getPageContextCurrent()
+  if (pageContextCurrent) {
+    prefetchSettings = getPrefetchSettings(pageContextCurrent, linkTag)
+  } else {
+    if (isBrilloutDocpress()) {
+      // TODO/pageContext-prefetch: remove this dirty hack used by @brillout/docpress and, instead, use reveal's default if pageContextCurrent isn't defined yet.
+      prefetchSettings = { staticAssets: "hover", pageContext: Infinity }
+    } else {
+      // TODO/pageContext-prefetch: consider pageContextLink
+      return
+    }
+  }
+
+  // Check again in case DOM was manipulated since last check
+  if (skipLink(linkTag)) return
+
+  const urlOfLink = linkTag.getAttribute("href")!
+
+  const pageContextLink = await getPageContextLink(urlOfLink)
+  if (!pageContextLink?.pageId) return
+  assert(hasProp(pageContextLink, "pageId", "string")) // help TypeScript
+  if (!(await isClientSideRoutable(pageContextLink.pageId, pageContextLink)))
+    return
+
+  await Promise.allSettled([
+    (async () => {
+      if (prefetchSettings.staticAssets === event) {
+        await prefetchAssets(pageContextLink)
+      }
+    })(),
+    (async () => {
+      if (event !== "viewport" && prefetchSettings.pageContext) {
+        const key = getCacheKey(urlOfLink)
+        const found = globalObject.prefetchedPageContexts[key]
+        if (!found || isExpired(found)) {
+          // TODO/pageContext-prefetch: move this logic in getPrefetchSettings()
+          const resultMaxAge = prefetchSettings.pageContext
+          await prefetchPageContextFromServerHooks(
+            {
+              ...pageContextLink,
+              config: {
+                ...pageContextLink.config,
+                pageId: pageContextLink.config.pageId!,
+              },
+            } as PageContextForPrefetch,
+            resultMaxAge
+          )
+        }
+      }
+    })(),
+  ])
+}
+
+function isExpired(found: PrefetchedPageContext) {
+  return Date.now() - found.resultFetchedAt > found.resultMaxAge
+}
+
+// TODO/next-major-release: make it sync
+async function getPageContextLink(urlOfLink: string) {
+  const pageContextLink = await createPageContext(urlOfLink)
+
+  let pageContextFromRoute: PageContextFromRoute
+  try {
+    pageContextFromRoute = await route(pageContextLink)
+  } catch {
+    // If a route() hook has a bug or `throw render()` / `throw redirect()`
+    return null
+  }
+  objectAssign(pageContextLink, pageContextFromRoute)
+
+  // Ensure pageContextLink includes the required 'config' property
+  return {
+    ...pageContextLink,
+    config: {
+      Page: {},
+      ...pageContextLink._pageConfigs[0],
+    },
+  }
+}
+
+function getCacheKey(url: string): string {
+  if (url.startsWith("#")) url = "/"
+  assert(url.startsWith("/"), `Invalid URL: ${url}`)
+  const key = url.split("#")[0]!
+  return key
+}
+
+// TODO/pageContext-prefetch: remove
+function isBrilloutDocpress(): boolean {
+  return "_isBrilloutDocpress" in window
+}

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

@@ -0,0 +1,48 @@
+export { preparePageContextForUserConsumptionClientSide };
+export type { PageContextForUserConsumptionClientSide };
+
+import { objectAssign } from "../server/utils.js";
+import { assert } from "../../gaurds/assertions/assert/base.js";
+import {
+  getPageContextProxyForUser,
+  PageContextForPassToClientWarning,
+} from "../../processing/getters/getPageContextProxyForUser.js";
+import { PageContextExports } from "../../processing/getters/getPageFiles/index.js";
+import { PageConfigRuntime } from "../../../types/interfaces/page.js";
+import {
+  PageContextClient,
+  PageContextClientWithServerRouting,
+} from "../../../types/interfaces/context.js";
+import { preparePageContextForUserConsumption } from "../../renderer/page/preparePageContextForUserConsumption.js";
+
+type PageContextForUserConsumptionClientSide = PageContextExports &
+  PageContextForPassToClientWarning & {
+    pageId: string;
+    _pageConfigs: PageConfigRuntime[];
+    config: PageConfigRuntime & {
+      Page: Record<string, unknown>;
+    };
+  };
+
+function preparePageContextForUserConsumptionClientSide<
+  T extends PageContextForUserConsumptionClientSide,
+>(pageContext: T, isClientRouting: boolean): T & { Page: unknown } {
+  if (isClientRouting) {
+    const pageContextTyped = pageContext as any as PageContextClient;
+    assert([true, false].includes(pageContextTyped.isHydration));
+    assert([true, false, null].includes(pageContextTyped.isBackwardNavigation));
+  } else {
+    const pageContextTyped =
+      pageContext as any as PageContextClientWithServerRouting;
+    assert(pageContextTyped.isHydration === true);
+    assert(pageContextTyped.isBackwardNavigation === null);
+  }
+
+  const Page = pageContext.config.Page;
+  objectAssign(pageContext, { Page });
+
+  preparePageContextForUserConsumption(pageContext);
+
+  const pageContextProxy = getPageContextProxyForUser(pageContext);
+  return pageContextProxy;
+}

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

@@ -0,0 +1,37 @@
+import { assert } from "../../gaurds/assertions/assert/base";
+import { assertWarning } from "../../gaurds/assertions/assertWarning";
+
+export { removeBuiltInOverrides };
+
+const BUILT_IN_CLIENT_ROUTER = ["urlPathname", "urlParsed"] as const;
+const BUILT_IN_CLIENT = ["Page", "pageExports", "exports"] as const;
+type DeletedKeys =
+  | (typeof BUILT_IN_CLIENT)[number]
+  | (typeof BUILT_IN_CLIENT_ROUTER)[number];
+function removeBuiltInOverrides(
+  pageContext: Record<string, unknown> & { [key in DeletedKeys]?: never },
+) {
+  const alreadySet = [...BUILT_IN_CLIENT, ...BUILT_IN_CLIENT_ROUTER];
+  alreadySet.forEach((prop) => {
+    if (prop in pageContext) {
+      // We need to cast `BUILT_IN_CLIENT` to `string[]`
+      //  - https://stackoverflow.com/questions/56565528/typescript-const-assertions-how-to-use-array-prototype-includes
+      //  - https://stackoverflow.com/questions/57646355/check-if-string-is-included-in-readonlyarray-in-typescript
+      if ((BUILT_IN_CLIENT_ROUTER as any as string[]).includes(prop)) {
+        assert(prop.startsWith("url"));
+        assertWarning(
+          false,
+          `pageContext.${prop} is already available in the browser when using Client Routing; adding '${prop}' to passToClient has no effect`,
+          { onlyOnce: true },
+        );
+      } else {
+        assertWarning(
+          false,
+          `pageContext.${prop} is a built-in that cannot be overriden; adding '${prop}' to passToClient has no effect`,
+          { onlyOnce: true },
+        );
+      }
+      delete pageContext[prop];
+    }
+  });
+}

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

@@ -0,0 +1,70 @@
+import { assert } from "../../gaurds/assertions/assert"
+
+export { removeFoucBuster }
+
+// import { assert } from "./utils.js";
+
+// See also:
+// - Alternative approach of exactly injecting what Vite injects:
+//   - https://github.com/remix-run/remix/issues/8830#issuecomment-1968368351
+//   - https://github.com/rakkasjs/rakkasjs/blob/7d75ccc915e93bca04e6bab37dc6abdb68a85e4a/packages/rakkasjs/src/features/pages/middleware.tsx#L701
+// - https://github.com/remix-run/remix/issues/8830
+
+function removeFoucBuster() {
+  assert(import.meta.env.DEV)
+  let sleep = 2
+  setTimeout(runClean, sleep)
+
+  return
+
+  function runClean() {
+    const isCleaned = clean()
+    if (!isCleaned) {
+      if (sleep < 1000) sleep = 2 * sleep
+      setTimeout(runClean, sleep)
+    }
+  }
+}
+
+function clean() {
+  const VITE_ID = "data-vite-dev-id"
+  const injectedByVite = [
+    ...document.querySelectorAll(`style[${VITE_ID}]`),
+  ].map((style) => style.getAttribute(VITE_ID)!)
+
+  // ```
+  // <link rel="stylesheet" type="text/css" href="/renderer/css/index.css?direct">
+  // <link rel="stylesheet" type="text/css" href="/renderer/Layout.css?direct">
+  // ```
+  const suffix = "?direct"
+  // <link> defined by:
+  //  - https://github.com/revealjs/reveal/blob/fae90a15d88e5e87ca9fcbb54cf2dc8773d2f229/reveal/node/runtime/html/injectAssets/inferHtmlTags.ts#L35
+  //  - https://github.com/revealjs/reveal/blob/fae90a15d88e5e87ca9fcbb54cf2dc8773d2f229/reveal/node/runtime/renderPage/getPageAssets.ts#L68
+  const injectedByReveal = [
+    ...document.querySelectorAll(
+      `link[rel="stylesheet"][type="text/css"][href$="${suffix}"]`
+    ),
+  ]
+
+  let isCleaned = true
+  injectedByReveal.forEach((linkReveal) => {
+    const href = linkReveal.getAttribute("href")
+    assert(href && href.endsWith(suffix))
+    let filePathAbsoluteUserRootDir = href.slice(0, -suffix.length)
+    const prefix = "/@fs/"
+    if (filePathAbsoluteUserRootDir.startsWith(prefix))
+      filePathAbsoluteUserRootDir = filePathAbsoluteUserRootDir.slice(
+        prefix.length
+      )
+    if (
+      injectedByVite.some((filePathAbsoluteFilesystem) =>
+        filePathAbsoluteFilesystem.endsWith(filePathAbsoluteUserRootDir)
+      )
+    ) {
+      linkReveal.remove()
+    } else {
+      isCleaned = false
+    }
+  })
+  return isCleaned
+}