@revealui/core 0.0.1-pre.0

package/dist/types/interfaces/config.ts

@@ -0,0 +1,481 @@
+export type Viewport = "responsive" | number | null
+export type {
+  Config,
+  ConfigBuiltIn,
+  ConfigMeta,
+  ConfigNameBuiltIn,
+  HookName,
+  HookNameGlobal,
+  HookNamePage,
+  ImportString,
+}
+
+export type {
+  DataAsync,
+  DataSync,
+  GuardAsync,
+  GuardSync,
+  KeepScrollPosition,
+  OnBeforePrerenderStartAsync,
+  OnBeforePrerenderStartSync,
+  OnBeforeRenderAsync,
+  OnBeforeRenderSync,
+  OnBeforeRouteAsync,
+  OnBeforeRouteSync,
+  OnHydrationEndAsync,
+  OnHydrationEndSync,
+  OnPageTransitionEndAsync,
+  OnPageTransitionEndSync,
+  OnPageTransitionStartAsync,
+  OnPageTransitionStartSync,
+  OnPrerenderStartAsync,
+  OnPrerenderStartSync,
+  OnRenderClientAsync,
+  OnRenderClientSync,
+  OnRenderHtmlAsync,
+  OnRenderHtmlSync,
+  RouteSync,
+}
+
+import type { HooksTimeoutProvidedByUser } from "../../core/processing/getters/getHook.js"
+import type { ConfigDefinition } from "../../core/processing/getters/getRevealConfig/configDefinitionsBuiltIn.js"
+import type { DocumentHtml } from "../../core/renderer/stream/html.js"
+import type { InjectFilterEntry } from "../index.js"
+import type { Reveal, RevealPackages } from "../namespaces/RevealNamespace.js"
+import { PageContextClient, PageContextServer } from "./context.js"
+import type { PrefetchSetting } from "./node.js"
+import type { ConfigRevealUserProvided } from "./reveal.js"
+
+type HookName = HookNamePage | HookNameGlobal
+type HookNamePage =
+  | "onHydrationEnd"
+  | "onBeforePrerenderStart"
+  | "onBeforeRender"
+  | "onPageTransitionStart"
+  | "onPageTransitionEnd"
+  | "onRenderHtml"
+  | "onRenderClient"
+  | "guard"
+  | "data"
+type HookNameGlobal = "onBeforePrerender" | "onBeforeRoute" | "onPrerenderStart"
+
+type ConfigNameBuiltIn =
+  | Exclude<
+      keyof Config,
+      keyof ConfigRevealUserProvided | "onBeforeRoute" | "onPrerenderStart"
+    >
+  | "prerender"
+  | "isClientRuntimeLoaded"
+  | "onBeforeRenderEnv"
+  | "dataEnv"
+  | "hooksTimeout"
+  | "clientHooks"
+
+type Config = ConfigBuiltIn & Reveal.Config & RevealPackages.ConfigRevealReact
+
+// Purposeful code duplication for improving QuickInfo IntelliSense
+/** Hook for fetching data.
+ *
+ *  https://reveal.dev/data
+ */
+type DataAsync<Data = unknown> = (
+  pageContext: PageContextServer
+) => Promise<Data>
+/** Hook for fetching data.
+ *
+ *  https://reveal.dev/data
+ */
+type DataSync<Data = unknown> = (pageContext: PageContextServer) => Data
+/** Protect page(s), e.g. forbid unauthorized access.
+ *
+ *  https://reveal.dev/guard
+ */
+type GuardAsync = (pageContext: PageContextServer) => Promise<void>
+/** Protect page(s), e.g. forbid unauthorized access.
+ *
+ *  https://reveal.dev/guard
+ */
+type GuardSync = (pageContext: PageContextServer) => void
+/** Global Hook called before the whole pre-rendering process starts.
+ *
+ * https://reveal.dev/onBeforePrerenderStart
+ */
+type OnBeforePrerenderStartAsync<Data = unknown> = () => Promise<
+  (
+    | string
+    | {
+        url: string
+        pageContext: Partial<Reveal.PageContext & { data: Data }>
+      }
+  )[]
+>
+/** Global Hook called before the whole pre-rendering process starts.
+ *
+ * https://reveal.dev/onBeforePrerenderStart
+ */
+type OnBeforePrerenderStartSync<Data = unknown> = () => (
+  | string
+  | {
+      url: string
+      pageContext: Partial<Reveal.PageContext & { data: Data }>
+    }
+)[]
+/** Hook called before the page is rendered.
+ *
+ *  https://reveal.dev/onBeforeRender
+ */
+type OnBeforeRenderAsync = (
+  pageContext: PageContextServer
+) => Promise<{ pageContext: Partial<Reveal.PageContext> } | void>
+/** Hook called before the page is rendered.
+ *
+ *  https://reveal.dev/onBeforeRender
+ */
+type OnBeforeRenderSync = (
+  pageContext: PageContextServer
+) => { pageContext: Partial<Reveal.PageContext> } | void
+/** Hook called before the URL is routed to a page.
+ *
+ * https://reveal.dev/onBeforeRoute
+ */
+type OnBeforeRouteAsync = (pageContext: PageContextServer) => Promise<{
+  pageContext: Partial<
+    | {
+        /** The URL you provided to Reveal when calling `renderPage({ urlOriginal })` in your server middleware.
+         *
+         * https://reveal.dev/renderPage
+         */
+        urlOriginal: string
+      }
+    | Reveal.PageContext
+  >
+}>
+/** Hook called before the URL is routed to a page.
+ *
+ * https://reveal.dev/onBeforeRoute
+ */
+type OnBeforeRouteSync = (pageContext: PageContextServer) => {
+  pageContext: Partial<
+    | {
+        /** The URL you provided to Reveal when calling `renderPage({ urlOriginal })` in your server middleware.
+         *
+         * https://reveal.dev/renderPage
+         */
+        urlOriginal: string
+      }
+    | Reveal.PageContext
+  >
+}
+/** Hook called after the page is hydrated.
+ *
+ * https://reveal.dev/onHydrationEnd
+ */
+type OnHydrationEndAsync = (pageContext: PageContextClient) => Promise<void>
+/** Hook called after the page is hydrated.
+ *
+ * https://reveal.dev/onHydrationEnd
+ */
+type OnHydrationEndSync = (pageContext: PageContextClient) => void
+/** Hook called after the user navigates to a new page.
+ *
+ * https://reveal.dev/onPageTransitionEnd
+ */
+type OnPageTransitionEndAsync = (
+  pageContext: PageContextClient
+) => Promise<void>
+/** Hook called after the user navigates to a new page.
+ *
+ * https://reveal.dev/onPageTransitionEnd
+ */
+type OnPageTransitionEndSync = (pageContext: PageContextClient) => void
+/** Hook called before the user navigates to a new page.
+ *
+ * https://reveal.dev/onPageTransitionStart
+ */
+type OnPageTransitionStartAsync = (
+  pageContext: PageContextClient
+) => Promise<void>
+/** Hook called before the user navigates to a new page.
+ *
+ * https://reveal.dev/onPageTransitionStart
+ */
+type OnPageTransitionStartSync = (pageContext: PageContextClient) => void
+/** Page Hook called when pre-rendering starts.
+ *
+ * https://reveal.dev/onPrerenderStart
+ */
+type OnPrerenderStartAsync = (prerenderContext: {
+  pageContexts: PageContextServer[]
+}) => Promise<{ prerenderContext: { pageContexts: PageContextServer[] } }>
+/** Page Hook called when pre-rendering starts.
+ *
+ * https://reveal.dev/onPrerenderStart
+ */
+type OnPrerenderStartSync = (prerenderContext: {
+  pageContexts: PageContextServer[]
+}) => {
+  prerenderContext: { pageContexts: PageContextServer[] }
+}
+/** Hook called when page is rendered on the client-side.
+ *
+ * https://reveal.dev/onRenderClient
+ */
+type OnRenderClientAsync = (pageContext: PageContextClient) => Promise<void>
+/** Hook called when page is rendered on the client-side.
+ *
+ * https://reveal.dev/onRenderClient
+ */
+type OnRenderClientSync = (pageContext: PageContextClient) => void
+/** Hook called when page is rendered to HTML on the server-side.
+ *
+ * https://reveal.dev/onRenderHtml
+ */
+type OnRenderHtmlAsync = (
+  pageContext: PageContextServer
+) => Promise<OnRenderHtmlReturn>
+/** Hook called when page is rendered to HTML on the server-side.
+ *
+ * https://reveal.dev/onRenderHtml
+ */
+type OnRenderHtmlSync = (pageContext: PageContextServer) => OnRenderHtmlReturn
+type OnRenderHtmlReturn =
+  | DocumentHtml
+  | {
+      injectFilter?: (assets: InjectFilterEntry[]) => void
+      documentHtml?: DocumentHtml
+      pageContext?:
+        | OnRenderHtmlPageContextReturn
+        // See https://reveal.dev/streaming#initial-data-after-stream-end
+        | (() =>
+            | Promise<OnRenderHtmlPageContextReturn>
+            | OnRenderHtmlPageContextReturn)
+    }
+type OnRenderHtmlPageContextReturn = Partial<
+  Reveal.PageContext & {
+    /** See https://reveal.dev/streaming */
+    enableEagerStreaming: boolean
+  }
+>
+/** Use a sync route() with an async guard() instead */
+
+/** The page's URL(s).
+ *
+ *  https://reveal.dev/route
+ */
+type RouteSync = (
+  pageContext: PageContextServer | PageContextClient
+) => { routeParams?: Record<string, string>; precedence?: number } | boolean
+
+/** Whether the page scrolls to the top upon navigation.
+ *
+ * https://reveal.dev/keepScrollPosition
+ */
+type KeepScrollPosition =
+  | boolean
+  | string
+  | string[]
+  | ((pageContext: PageContextClient) => boolean | string | string[])
+
+/** Page configuration.
+ *
+ * https://reveal.dev/config
+ */
+type ConfigBuiltIn = {
+  /** The page's root component */
+  Page?: unknown
+
+  /** The page's URL(s).
+   *
+   *  https://reveal.dev/route
+   */
+  route?: string | RouteSync | ImportString
+
+  /** Protect page(s), e.g. forbid unauthorized access.
+   *
+   *  https://reveal.dev/guard
+   */
+  guard?: GuardAsync | GuardSync | ImportString
+  /**
+   * Whether to pre-render the page(s).
+   *
+   * https://reveal.dev/pre-rendering
+   */
+  prerender?: boolean | ImportString
+
+  /**
+   * Install reveal extensions.
+   *
+   * https://reveal.dev/extends
+   */
+  extends?: Config | Config[] | ImportString | ImportString[]
+
+  /** Hook called before the page is rendered.
+   *
+   *  https://reveal.dev/onBeforeRender
+   */
+  onBeforeRender?:
+    | OnBeforeRenderAsync
+    | OnBeforeRenderSync
+    | ImportString
+    | null
+
+  /** Hook for fetching data.
+   *
+   *  https://reveal.dev/data
+   */
+  data?: DataAsync<unknown> | DataSync<unknown> | ImportString | null
+
+  /** Determines what pageContext properties are sent to the client-side.
+   *
+   * https://reveal.dev/passToClient
+   */
+  passToClient?: string[] | ImportString
+
+  /** Hook called when page is rendered on the client-side.
+   *
+   * https://reveal.dev/onRenderClient
+   */
+  onRenderClient?: OnRenderClientAsync | OnRenderClientSync | ImportString
+  /** Hook called when page is rendered to HTML on the server-side.
+   *
+   * https://reveal.dev/onRenderHtml
+   */
+  onRenderHtml?: OnRenderHtmlAsync | OnRenderHtmlSync | ImportString
+
+  /** Enable async Route Functions.
+   *
+   * https://reveal.dev/route-function#async
+   */
+  iKnowThePerformanceRisksOfAsyncRouteFunctions?: boolean | ImportString
+
+  /** Change the URL root of Filesystem Routing.
+   *
+   * https://reveal.dev/filesystemRoutingRoot
+   */
+  filesystemRoutingRoot?: string | ImportString
+
+  /** Page Hook called when pre-rendering starts.
+   *
+   * https://reveal.dev/onPrerenderStart
+   */
+  onPrerenderStart?: OnPrerenderStartAsync | OnPrerenderStartSync | ImportString
+  /** Global Hook called before the whole pre-rendering process starts.
+   *
+   * https://reveal.dev/onBeforePrerenderStart
+   */
+  onBeforePrerenderStart?:
+    | OnBeforePrerenderStartAsync
+    | OnBeforePrerenderStartSync
+    | ImportString
+
+  /** Hook called before the URL is routed to a page.
+   *
+   * https://reveal.dev/onBeforeRoute
+   */
+  onBeforeRoute?: OnBeforeRouteAsync | OnBeforeRouteSync | ImportString
+
+  /** Hook called after the page is hydrated.
+   *
+   * https://reveal.dev/onHydrationEnd
+   */
+  onHydrationEnd?: OnHydrationEndAsync | OnHydrationEndSync | ImportString
+  /** Hook called before the user navigates to a new page.
+   *
+   * https://reveal.dev/onPageTransitionStart
+   */
+  onPageTransitionStart?:
+    | OnPageTransitionStartAsync
+    | OnPageTransitionStartSync
+    | ImportString
+  /** Hook called after the user navigates to a new page.
+   *
+   * https://reveal.dev/onPageTransitionEnd
+   */
+  onPageTransitionEnd?:
+    | OnPageTransitionEndAsync
+    | OnPageTransitionEndSync
+    | ImportString
+
+  /** Whether the UI framework (React/Vue/Solid/...) allows the page's hydration to be aborted.
+   *
+   * https://reveal.dev/hydrationCanBeAborted
+   */
+  hydrationCanBeAborted?: boolean | ImportString
+  /** Add client code.
+   *
+   * https://reveal.dev/client
+   */
+  client?: string | ImportString
+  /** Enable Client Routing.
+   *
+   * https://reveal.dev/clientRouting
+   */
+  clientRouting?: boolean | ImportString
+
+  /**
+   * Whether hooks are loaded on the client-side.
+   *
+   * https://reveal.dev/clientHooks
+   */
+  clientHooks?: boolean | null | ImportString
+
+  /** Create new or modify existing configurations.
+   *
+   * https://reveal.dev/meta
+   */
+  meta?: ConfigMeta | ImportString
+
+  /**
+   * Prefetch pages/links.
+   *
+   * https://reveal.dev/prefetch
+   */
+  prefetch?: PrefetchSetting | ImportString
+
+  // TODO/pageContext-prefetch: use following JSDoc to deprecate old interface.
+  /** @deprecated Use `prefetch` setting (https://reveal.dev/prefetch) instead.  */
+  /** Prefetch links.
+   *
+   * https://reveal.dev/prefetchStaticAssets
+   */
+  prefetchStaticAssets?: PrefetchSetting | ImportString
+
+  /** Modify the timeouts of hooks. */
+  hooksTimeout?: HooksTimeoutProvidedByUser
+
+  /** `Cache-Control` HTTP header value.
+   *
+   * Default: `no-store, max-age=0`
+   *
+   * Set to an empty string to not send the header.
+   *
+   * https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control
+   */
+  cacheControl?: string
+
+  /** Where scripts are injected in the HTML.
+   *
+   * https://reveal.dev/injectScriptsAt
+   */
+  injectScriptsAt?: "HTML_BEGIN" | "HTML_END" | "HTML_STREAM" | null
+
+  /** Used by Reveal extensions to set their name.
+   *
+   * https://reveal.dev/extends
+   */
+  name?: string
+
+  /** Used by Reveal extensions to enforce their peer dependencies.
+   *
+   * https://reveal.dev/require
+   */
+  require?: Record<string, string>
+
+  /** Whether the page scrolls to the top upon navigation.
+   *
+   * https://reveal.dev/keepScrollPosition
+   */
+  keepScrollPosition?: KeepScrollPosition
+}
+type ConfigMeta = Record<string, ConfigDefinition>
+type ImportString = `import:${string}`