catalyst-core 0.2.0-beta.3 → 0.3.0-beta.1

package/dist/web-router/components/RouterDataProvider.jsx

@@ -0,0 +1,332 @@
+import React, { useEffect, useState, createContext, useContext, useMemo, useRef } from "react"
+import {
+    useLocation,
+    useMatch,
+    useNavigate,
+    useParams,
+    useSearchParams,
+    UNSAFE_RouteContext,
+    matchRoutes,
+} from "react-router-dom"
+import { OneMgRouterContext } from "../context.jsx"
+// import sanitizeHtml from "sanitize-html"
+
+/**
+ * @description  Router Data
+ * @typedef {{data: any, error: any, isFetching: boolean, isFetched:boolean, refetch?:(args:any)=>Promise<void>}} RouteData
+ */
+
+/**
+ * @type {import("react").Context<Object.<string, RouteData>>}
+ */
+export const RouterContext = createContext({})
+
+/**
+ * @typedef RouterDataProviderConfig
+ * @property {boolean} [disableCaching=false] disableCaching disable caching of fetched data - default is false
+ */
+
+/**
+ * Initial State of context
+ */
+const INITIAL_DATA_STATE = {
+    data: null,
+    error: null,
+    isFetching: false,
+    isFetched: false,
+    refetch: () => {},
+    clear: () => {},
+}
+
+/**
+ * @typedef RouterFetcherProps
+ * @property {any} route route object
+ * @property {import("react-router-dom").Location} location the current location object, which represents the current URL in web browsers.
+ * @property {import("react-router-dom").Params} params object of key/value pairs of the dynamic params from the current URL that were matched by the route path.
+ * @property {URLSearchParams} searchParams search parameters via URLSearchParams interface.
+ * @property {import("react-router-dom").NavigateFunction} navigate function to navigate to other pages based on response.
+ */
+
+/**
+ * @typedef ServerFetchDataProps
+ * @property {import("react-router-dom").RouteObject[]} routes routes Array
+ * @property {string} url current url
+ * @property {import("express").Request} req Express request object
+ */
+
+/**
+ * @description call this function to fetch data using fetchers defined in routes
+ * @param {ServerFetchDataProps} serverFetchDataProps
+ * @param {Object.<string, any>} fetcherArgs anything passed in fetcherArgs prop of RouterProvider
+ * @returns RoutesData
+ */
+export const serverDataFetcher = async (serverFetchDataProps, fetcherArgs) => {
+    /**
+     * @type {Object.<string, RouteData>}
+     */
+    const routesData = {}
+    const { routes, url, req, res: responseInstance } = serverFetchDataProps
+    const matchedRoutes = matchRoutes(routes, url)
+    if (matchedRoutes) {
+        const searchParams = req.query
+        const params = matchedRoutes[matchedRoutes.length - 1].params
+        let searchParamsString = ""
+        if (searchParams) {
+            for (const key in searchParams) {
+                searchParamsString += `${key}=${searchParams[key]}&`
+            }
+            searchParamsString = searchParamsString.slice(0, -1)
+            searchParamsString = searchParamsString ? `?${searchParamsString}` : searchParamsString
+        }
+        await Promise.allSettled(
+            matchedRoutes.map(async (match) => {
+                const res = await fetchRouteData(
+                    { req, res: responseInstance, route: match.route, params, searchParams },
+                    fetcherArgs
+                )
+                routesData[generateRouteKey(match, searchParamsString)] = res
+            })
+        )
+    }
+    return routesData
+}
+
+/**
+ * @description call this function to fetch data using fetchers defined in [page].fetcher.js
+ * @param {RouterFetcherProps} routerProps
+ * @param {Object.<string, any>} fetcherArgs anything passed in fetcherArgs prop of RouterProvider
+ * @param {Object.<string, any>=} refetchArgs anything passed in argument of refetch function
+ * @returns {Promise<RouteData>}
+ */
+const fetchRouteData = async (routerProps, fetcherArgs, refetchArgs) => {
+    const routeData = { ...INITIAL_DATA_STATE }
+    const { route } = routerProps
+    const routeComponent = route.component || route.Component || route.element
+    let component = null
+    // If component is imported through loadable
+    if (typeof routeComponent?.load === "function") {
+        try {
+            component = await routeComponent.load()
+        } catch (err) {
+            console.error("Error loading component", err)
+        }
+    }
+
+    let fetcher = component?.default?.clientFetcher
+
+    if (typeof window === "undefined") {
+        fetcher = component?.default?.serverFetcher
+    }
+
+    if (fetcher && typeof fetcher === "function") {
+        routeData.fetcherNotAvailable = false
+        try {
+            const res = await fetcher(routerProps, fetcherArgs, refetchArgs)
+            routeData.data = res
+        } catch (error) {
+            // @ts-ignore
+            routeData.error = error
+        } finally {
+            routeData.isFetching = false
+            routeData.isFetched = true
+        }
+    } else {
+        routeData.fetcherNotAvailable = true
+    }
+    return routeData
+}
+
+/**
+ *
+ * @param {RouteContextObject} routeContext route context object
+ * @returns {import('react-router-dom').RouteMatch[]} Array of matched routes
+ */
+const getMatchedRoutes = ({ matches, outlet }) => {
+    if (outlet) {
+        return getMatchedRoutes(outlet.props.routeContext)
+    }
+    return matches
+}
+
+/**
+ * Generates route key for given route using pathname and query params
+ * @param {import('react-router-dom').RouteMatch} match Router Match Object
+ * @param {string} searchParamsString Query params string
+ * @returns {string} routerKey
+ */
+const generateRouteKey = (match, searchParamsString = "") => {
+    const { pathname, route } = match
+    const sanitizedPathname = pathname
+    const sanitizedParams = searchParamsString
+    if (route.children) {
+        return `index${sanitizedPathname}${sanitizedParams}`
+    }
+    return `${sanitizedPathname}${sanitizedParams}`
+}
+
+/**
+ * @typedef RouterDataProviderProps
+ * @property {any} initialState Initial State of Data Provider - Mostly used to hydrate client with data from server
+ * @property {any} children
+ * @property {Object.<string, any>} fetcherArgs anything passed in fetcherArgs is passed to all the fetcher functions
+ * @property  {RouterDataProviderConfig} config Global router data provider config
+ */
+
+/**
+ * @description Render the child components with router context and execute data fetchers on path change
+ * @param {RouterDataProviderProps} props
+ * @returns React.JSX.Element
+ */
+export const RouterDataProvider = ({ children, initialState, fetcherArgs = {}, config }) => {
+    const match = useMatch("*")
+    const location = useLocation()
+    const params = useParams()
+    const navigate = useNavigate()
+    const [searchParams] = useSearchParams()
+
+    const isHydrated = useRef(false)
+    const routeContext = useContext(UNSAFE_RouteContext)
+    const matchedRoutes = useMemo(() => getMatchedRoutes(routeContext), [routeContext])
+
+    /**
+     * @description HOF which returns a function to refetch the route data
+     * @param {import("react-router-dom").RouteObject} route
+     * @param {string} routeKey
+     * @returns
+     */
+    const refetchData = (route, routeKey) => {
+        return async (/** @type {{ [x: string]: any; } | undefined} */ args) => {
+            setRouteData((prevData) => ({
+                ...prevData,
+                [routeKey]: { ...INITIAL_DATA_STATE, isFetching: true },
+            }))
+            const routerDataRes = await fetchRouteData(
+                { route, location, params, searchParams, navigate },
+                fetcherArgs,
+                args
+            )
+            setRouteData((prevData) => ({
+                ...prevData,
+                [routeKey]: { ...routerDataRes, fetcherNotAvailable: false },
+            }))
+        }
+    }
+
+    /**
+     * @description HOF which returns a function to clear the route data immediately or after given time in ms
+     * @param {import("react-router-dom").RouteObject} route
+     * @param {string} routeKey
+     * @returns
+     */
+    const clear =
+        (routeKey) =>
+        (wait = 0) => {
+            // TODO :: Need to think this use case
+            // eslint-disable-next-line no-unused-vars
+            const timeout = setTimeout(() => {
+                setRouteData((prevData) => ({ ...prevData, [routeKey]: { ...INITIAL_DATA_STATE } }))
+            }, [wait])
+        }
+
+    /**
+     * @type {[Object.<string, RouteData>,React.Dispatch<React.SetStateAction<Object.<string, RouteData>>>]}
+     */
+    const [routeData, setRouteData] = useState(initialState)
+
+    /**
+     * @description Check the config for refetching the data
+     * @param {import('react-router-dom').RouteObject} route
+     * @returns {boolean}
+     */
+    const shouldFetch = (route) => {
+        // do not refetch on first render if we get something in initialState
+        if (!isHydrated.current && initialState) return false
+
+        // config at route level over rides config at global level
+        if (typeof route.disableCaching === "boolean") {
+            return route.disableCaching
+        } else if (typeof config.disableCaching === "boolean") {
+            // refetch if caching is disabled at global level
+            return config.disableCaching
+        }
+        return false
+    }
+
+    useEffect(() => {
+        matchedRoutes.forEach(async (match) => {
+            const route = match.route
+            const routeKey = generateRouteKey(match, location.search)
+            if (routeData[routeKey]?.isFetched && !shouldFetch(route)) return
+            setRouteData((prevData) => ({
+                ...(prevData || {}),
+                [routeKey]: { ...INITIAL_DATA_STATE, isFetching: true },
+            }))
+            const routerDataRes = await fetchRouteData(
+                { route, location, params, searchParams, navigate },
+                fetcherArgs
+            )
+            setRouteData((prevData) => ({ ...prevData, [routeKey]: { ...routerDataRes } }))
+        })
+    }, [match.pathname, match.params])
+
+    return (
+        <OneMgRouterContext.Provider value={{ matchedRoutes, refetchData, clear }}>
+            <RouterContext.Provider value={{ ...routeData, refetch: refetchData }}>
+                {children}
+            </RouterContext.Provider>
+        </OneMgRouterContext.Provider>
+    )
+}
+
+/**
+ * @description returns current router context object with three values: data, error, isFetching, isFetched
+ * @returns {RouteData}
+ * @throws If used outside RouterDataProvider Context
+ */
+export const useCurrentRouteData = () => {
+    const routeContext = useContext(UNSAFE_RouteContext)
+    const currentPageMatch = routeContext.matches[routeContext.matches.length - 1]
+    const context = useContext(RouterContext)
+    const { refetchData, clear } = useContext(OneMgRouterContext)
+    const location = useLocation()
+    // Throw error if the hook is not used within a RouterProvider
+    if (context === undefined) {
+        throw new Error("useCurrentRouteData must be used within a RouterDataProvider")
+    }
+
+    const routeKey = generateRouteKey(currentPageMatch, location.search)
+    let currentPageData = context[routeKey]
+
+    useEffect(() => {
+        if (currentPageData?.fetcherNotAvailable) {
+            refetchData(currentPageMatch.route, routeKey)()
+        }
+    }, [])
+
+    if (!currentPageData) return { ...INITIAL_DATA_STATE }
+
+    if (currentPageData) {
+        delete currentPageData.fetcherNotAvailable
+        currentPageData = {
+            ...currentPageData,
+            refetch: refetchData(currentPageMatch.route, routeKey),
+            clear: clear(routeKey),
+        }
+    }
+    return currentPageData
+}
+
+/**
+ * @description returns a router context object with data of all the fetchers in current route tree
+ * @returns {Object.<string, RouteData>}
+ * @throws If used outside RouterDataProvider Context
+ */
+export const useRouterData = () => {
+    const context = useContext(RouterContext)
+    // Throw error if the hook is not used within a RouterProvider
+    if (context === undefined) {
+        throw new Error("useRouterData must be used within a RouterDataProvider")
+    }
+
+    return context
+}

package/dist/web-router/components/Split.jsx

@@ -0,0 +1,200 @@
+import React, { Suspense, lazy, useContext, useEffect, useReducer } from "react"
+import { SsrRequestContext } from "./SsrRequestContext.jsx"
+import SplitInview from "./SplitInview.jsx"
+
+// Synchronous module cache: importFn → resolved module.
+// Populated by the eager importFn().then() calls at split() invocation time.
+// By the time window.load fires (when hydrateRoot runs), all chunk <script>
+// tags in the HTML have already executed, so every .then() has already
+// resolved and the module is available here synchronously.
+const moduleCache = new Map()
+
+// Collects one promise per SSR-rendered split() call on the client.
+// loadableReady() waits for all of them before hydration begins.
+const prefetchPromises = []
+
+/**
+ * Returns a promise that resolves once every SSR-rendered split component
+ * has been prefetched and stored in moduleCache.  Call this before
+ * hydrateRoot so the first render has all modules available synchronously
+ * and no Suspense fallback is shown.
+ *
+ * @example
+ * hydrationReady().then(() => {
+ *   hydrateRoot(document.getElementById("root"), <App />)
+ * })
+ */
+export const hydrationReady = () => Promise.all(prefetchPromises)
+
+/**
+ * Split component that wraps React's lazy and Suspense for SSR compatibility
+ * @param {Object} props
+ * @param {boolean} props.ssr - Whether to render the component on the server
+ * @param {React.ComponentType|React.ReactElement} props.fallback - Fallback component for loading state
+ * @param {Function} props.children - Function that returns the lazy component import
+ * @param {string} props.cacheKey - Resolved path for better asset tracking
+ */
+const Split = ({
+    ssr = true,
+    fallback = null,
+    cacheKey,
+    rootOptions,
+    onVisible,
+    skipVisibility,
+    children,
+}) => {
+    // Check if we're on the server
+    const isServer = typeof window === "undefined"
+    if (isServer) {
+        if (ssr) {
+            // On server with SSR enabled: actually load and render the component
+            try {
+                // Track this component for asset extraction
+                if (global.__CHUNK_EXTRACTOR__) {
+                    global.__CHUNK_EXTRACTOR__.addComponent(cacheKey)
+                }
+
+                return <Suspense fallback={fallback}>{children}</Suspense>
+            } catch (error) {
+                console.warn("Error loading component for SSR:", error)
+                return fallback
+            }
+        } else {
+            // Match SplitInview's client-side wrapper so hydration doesn't mismatch.
+            // SplitInview renders <div ref>{fallback}</div> until visible; without this
+            // wrap, server outputs `fallback` and client outputs `<div>{fallback}</div>`.
+            return <div>{fallback}</div>
+        }
+    } else {
+        if (skipVisibility) {
+            return <Suspense fallback={fallback}>{children}</Suspense>
+        }
+        return (
+            <SplitInview fallback={fallback} rootOptions={rootOptions} onVisible={onVisible}>
+                <Suspense fallback={fallback}>{children}</Suspense>
+            </SplitInview>
+        )
+    }
+}
+
+/**
+ * Like {@link split}, but forces SSR when the request is a known Google crawler (same UA rules as Head).
+ * Use for widgets that are `ssr: false` for humans but must be fully rendered for bots.
+ *
+ * Prefetch follows `window.__SSR_RENDERED_COMPONENTS__` only (not the `ssr` option) so bot-forced SSR
+ * still hydrates without a Suspense flash.
+ */
+export const split = (importFn, options = {}, thirdArg, fourthArg) => {
+    const { ssr = true, fallback = null } = options || {}
+    const hasThirdArg = typeof thirdArg !== "undefined"
+    const hasFourthArg = typeof fourthArg !== "undefined"
+    const cacheKey =
+        typeof fourthArg === "string" ? fourthArg : typeof thirdArg === "string" ? thirdArg : undefined
+    const rootOptions = hasFourthArg
+        ? thirdArg
+        : hasThirdArg && typeof thirdArg !== "string"
+          ? thirdArg
+          : undefined
+
+    const LazyComponent = lazy(importFn)
+    let loadInFlight = null
+
+    // Per-split instance subscribers. Pending wrapper instances register their
+    // forceUpdate here; notifyAll() wakes them when load() resolves or any
+    // sibling becomes visible, so they can re-render against the now-hot cache
+    // or skip their own observer setup.
+    const subscribers = new Set()
+    let anyVisible = false
+    const notifyAll = () => {
+        anyVisible = true
+        subscribers.forEach((fn) => fn())
+    }
+    const copyRouteStatics = (mod) => {
+        const Component = mod?.default || mod
+        for (const key of ["clientFetcher", "serverFetcher", "setMetaData"]) {
+            if (Component?.[key]) wrapper[key] = Component[key]
+        }
+        return mod
+    }
+
+    if (typeof window !== "undefined" && window.__SSR_RENDERED_COMPONENTS__?.has(cacheKey)) {
+        const prefetch = importFn().then((mod) => {
+            moduleCache.set(importFn, mod)
+            copyRouteStatics(mod)
+        })
+        prefetchPromises.push(prefetch)
+    }
+
+    const wrapper = ({ fallback: fallbackProp, ...props }) => {
+        const { isBot: isBotFromContext } = useContext(SsrRequestContext)
+        const isBotFromWindow = typeof window !== "undefined" && window.__CATALYST_IS_BOT__ === true
+        const isBot = Boolean(isBotFromContext || isBotFromWindow)
+        const effectiveSsr = ssr || isBot
+        const effectiveFallback = fallbackProp !== undefined ? fallbackProp : fallback
+
+        const [, forceUpdate] = useReducer((x) => x + 1, 0)
+        useEffect(() => {
+            subscribers.add(forceUpdate)
+            return () => {
+                subscribers.delete(forceUpdate)
+            }
+        }, [])
+
+        const mod = moduleCache.get(importFn)
+        if (mod) {
+            const Component = mod.default || mod
+            return (
+                <Suspense fallback={effectiveFallback}>
+                    <Component {...props} />
+                </Suspense>
+            )
+        }
+
+        return (
+            <Split
+                ssr={effectiveSsr}
+                fallback={effectiveFallback}
+                cacheKey={cacheKey}
+                rootOptions={rootOptions}
+                onVisible={() => {
+                    notifyAll()
+                    props.onVisible?.()
+                }}
+                skipVisibility={effectiveSsr || anyVisible}
+                {...props}
+                isBot={isBot}
+            >
+                <LazyComponent {...props} />
+            </Split>
+        )
+    }
+
+    wrapper.__cacheKey = cacheKey
+
+    /** Same contract as loadable components: RouterDataProvider awaits this before reading serverFetcher/clientFetcher. */
+    wrapper.load = () => {
+        const cached = moduleCache.get(importFn)
+        if (cached) return Promise.resolve(cached)
+        if (!loadInFlight) {
+            loadInFlight = importFn()
+                .then((mod) => {
+                    copyRouteStatics(mod)
+                    if (typeof window !== "undefined") {
+                        moduleCache.set(importFn, mod)
+                    }
+                    loadInFlight = null
+                    notifyAll()
+                    return mod
+                })
+                .catch((err) => {
+                    loadInFlight = null
+                    throw err
+                })
+        }
+        return loadInFlight
+    }
+
+    return wrapper
+}
+
+export default Split

package/dist/web-router/components/SplitInview.jsx

@@ -0,0 +1,106 @@
+import React, { useState, useEffect, useRef } from "react"
+
+// Load components 75% of viewport below the fold so they're ready by the time
+// the user scrolls to them. Matches react-loadable-visibility's default.
+const DEFAULT_ROOT_MARGIN = "0px 0px 75% 0px"
+
+// Shared IntersectionObserver for the default (no rootOptions) path.
+// Each observed element maps to a callback that fires once and unobserves.
+const callbacks = new Map()
+let sharedObserver = null
+
+function getSharedObserver() {
+    if (sharedObserver) return sharedObserver
+    sharedObserver = new IntersectionObserver(
+        (entries) => {
+            entries.forEach((entry) => {
+                if (entry.isIntersecting || entry.intersectionRatio > 0) {
+                    const cb = callbacks.get(entry.target)
+                    if (cb) {
+                        cb()
+                        callbacks.delete(entry.target)
+                        sharedObserver.unobserve(entry.target)
+                    }
+                }
+            })
+        },
+        { rootMargin: DEFAULT_ROOT_MARGIN }
+    )
+    return sharedObserver
+}
+
+const hasCustomOptions = (o) =>
+    o && typeof o === "object" && (o.root != null || o.rootMargin != null || o.threshold != null)
+
+/**
+ * Defers rendering of children until the placeholder enters the viewport.
+ * Once visible, it stays visible.
+ *
+ * On the server or when IntersectionObserver is unavailable, children render immediately.
+ *
+ * @param {Object} props
+ * @param {React.ReactNode} props.fallback - Shown while the component is outside the viewport
+ * @param {React.ReactNode} props.children - Rendered once the placeholder scrolls into view
+ * @param {Object=} props.rootOptions - Optional IntersectionObserver options for parity with react-loadable-visibility
+ * @param {Function=} props.onVisible - Called once when the placeholder enters the viewport
+ */
+const SplitInview = ({ fallback = null, children, rootOptions, onVisible }) => {
+    const isServer = typeof window === "undefined"
+    const [isVisible, setIsVisible] = useState(() => {
+        if (isServer) return true
+        if (!window.IntersectionObserver) return true
+        return false
+    })
+    const ref = useRef(null)
+    // Freeze rootOptions at mount. IO options are not expected to change mid-lifecycle,
+    // so we avoid array/object identity churn (e.g. inline `threshold: [0, 0.5, 1]`).
+    const rootOptionsRef = useRef(rootOptions)
+    const onVisibleRef = useRef(onVisible)
+    onVisibleRef.current = onVisible
+
+    useEffect(() => {
+        if (isVisible) return
+        const node = ref.current
+        if (!node) return
+
+        const opts = rootOptionsRef.current
+        const fire = () => {
+            setIsVisible(true)
+            onVisibleRef.current?.()
+        }
+
+        if (!hasCustomOptions(opts)) {
+            callbacks.set(node, fire)
+            getSharedObserver().observe(node)
+            return () => {
+                callbacks.delete(node)
+                if (sharedObserver) sharedObserver.unobserve(node)
+            }
+        }
+
+        const observer = new IntersectionObserver(
+            (entries) => {
+                entries.forEach((entry) => {
+                    if (entry.isIntersecting || entry.intersectionRatio > 0) {
+                        fire()
+                        observer.unobserve(entry.target)
+                    }
+                })
+            },
+            {
+                root: opts.root ?? null,
+                rootMargin: opts.rootMargin ?? DEFAULT_ROOT_MARGIN,
+                threshold: opts.threshold,
+            }
+        )
+
+        observer.observe(node)
+        return () => observer.disconnect()
+    }, [isVisible])
+
+    if (isVisible) return children
+
+    return <div ref={ref}>{fallback}</div>
+}
+
+export default SplitInview

package/dist/web-router/components/SsrRequestContext.jsx

@@ -0,0 +1,14 @@
+import React, { createContext } from "react"
+
+/**
+ * SSR request flags (e.g. crawler UA). Set by the document handler via SsrRequestProvider.
+ * Kept separate from Split.jsx so the server handler does not import lazy/Suspense code.
+ * `window.__CATALYST_IS_BOT__` is inlined for bots that execute JS so hydration matches the server.
+ */
+export const SsrRequestContext = createContext({ isBot: false })
+
+export function SsrRequestProvider({ value, children }) {
+    return (
+        <SsrRequestContext.Provider value={value ?? { isBot: false }}>{children}</SsrRequestContext.Provider>
+    )
+}

package/dist/web-router/context.jsx

@@ -0,0 +1,12 @@
+import { createContext } from "react"
+
+/**
+ * @typedef oneMgRouterContext
+ * @property {import("react-router-dom").RouteMatch<string, import("react-router-dom").RouteObject>[]=} matchedRoutes
+ */
+
+/**
+ * @description This is internal context made for sharing data among router components
+ * @type {import("react").Context<oneMgRouterContext>}
+ */
+export const OneMgRouterContext = createContext({})