@xyd-js/plugin-docs 0.1.0-xyd.2 → 0.1.0-xyd.3

package/src/pages/metatags.ts

@@ -0,0 +1,96 @@
+import { MetaTags } from "@xyd-js/core";
+
+export const SUPPORTED_META_TAGS: MetaTags = {
+    "robots": "name",
+    "charset": "name",
+    "viewport": "name",
+    "description": "name",
+    "keywords": "name",
+    "author": "name",
+    "googlebot": "name",
+    "google": "name",
+    "google-site-verification": "name",
+    "generator": "name",
+    "theme-color": "name",
+    "color-scheme": "name",
+    "format-detection": "name",
+    "referrer": "name",
+    "refresh": "name",
+    "rating": "name",
+    "revisit-after": "name",
+    "language": "name",
+    "copyright": "name",
+    "reply-to": "name",
+    "distribution": "name",
+    "coverage": "name",
+    "category": "name",
+    "target": "name",
+    "HandheldFriendly": "name",
+    "MobileOptimized": "name",
+    "apple-mobile-web-app-capable": "name",
+    "apple-mobile-web-app-status-bar-style": "name",
+    "apple-mobile-web-app-title": "name",
+    "application-name": "name",
+    "msapplication-TileColor": "name",
+    "msapplication-TileImage": "name",
+    "msapplication-config": "name",
+
+    "og:title": "property",
+    "og:type": "property",
+    "og:url": "property",
+    "og:image": "property",
+    "og:description": "property",
+    "og:site_name": "property",
+    "og:locale": "property",
+    "og:video": "property",
+    "og:audio": "property",
+
+    "twitter:card": "property",
+    "twitter:site": "property",
+    "twitter:creator": "property",
+    "twitter:title": "property",
+    "twitter:description": "property",
+    "twitter:image": "property",
+    "twitter:image:alt": "property",
+    "twitter:player": "property",
+    "twitter:player:width": "property",
+    "twitter:player:height": "property",
+    "twitter:app:name:iphone": "property",
+    "twitter:app:id:iphone": "property",
+    "twitter:app:url:iphone": "property",
+
+    "article:published_time": "property",
+    "article:modified_time": "property",
+    "article:expiration_time": "property",
+    "article:author": "property",
+    "article:section": "property",
+    "article:tag": "property",
+
+    "book:author": "property",
+    "book:isbn": "property",
+    "book:release_date": "property",
+    "book:tag": "property",
+
+    "profile:first_name": "property",
+    "profile:last_name": "property",
+    "profile:username": "property",
+    "profile:gender": "property",
+
+    "music:duration": "property",
+    "music:album": "property",
+    "music:album:disc": "property",
+    "music:album:track": "property",
+    "music:musician": "property",
+    "music:song": "property",
+    "music:song:disc": "property",
+    "music:song:track": "property",
+
+    "video:actor": "property",
+    "video:actor:role": "property",
+    "video:director": "property",
+    "video:writer": "property",
+    "video:duration": "property",
+    "video:release_date": "property",
+    "video:tag": "property",
+    "video:series": "property"
+}

package/src/pages/page.tsx

@@ -0,0 +1,363 @@
+import path from "node:path";
+
+import * as React from "react";
+import { useMemo, useContext, ReactElement, SVGProps } from "react";
+import { redirect, ScrollRestoration, useLocation } from "react-router";
+
+import { MetadataMap, Metadata, Settings } from "@xyd-js/core"
+import { ContentFS } from "@xyd-js/content"
+import { markdownPlugins } from "@xyd-js/content/md"
+import { mapSettingsToProps } from "@xyd-js/framework/hydration";
+import { FrameworkPage, type FwSidebarGroupProps } from "@xyd-js/framework/react";
+import type { IBreadcrumb, INavLinks } from "@xyd-js/ui";
+
+// @ts-ignore
+import virtualSettings from "virtual:xyd-settings";
+// @ts-ignore
+const { settings } = virtualSettings as Settings
+import { PageContext } from "./context";
+import { SUPPORTED_META_TAGS } from "./metatags";
+
+function getPathname(url: string) {
+    const parsedUrl = new URL(url);
+    return parsedUrl.pathname.replace(/^\//, '');
+}
+
+interface loaderData {
+    sidebarGroups: FwSidebarGroupProps[]
+    breadcrumbs: IBreadcrumb[],
+    toc: MetadataMap,
+    slug: string
+    code: string
+    metadata: Metadata | null
+    rawPage: string // TODO: in the future routing like /docs/quickstart.md but some issues with react-router like *.md in `route` config
+    navlinks?: INavLinks,
+}
+
+class timedebugLoader {
+    static get total() {
+        console.time('loader:total')
+
+        return
+    }
+
+    static get totalEnd() {
+        console.timeEnd('loader:total')
+
+        return
+    }
+
+    static get compile() {
+        console.time('loader:compile')
+
+        return
+    }
+
+    static get compileEnd() {
+        console.timeEnd('loader:compile')
+
+        return
+    }
+
+    static get mapSettingsToProps() {
+        console.time('loader:mapSettingsToProps')
+
+        return
+    }
+
+    static get mapSettingsToPropsEnd() {
+        console.timeEnd('loader:mapSettingsToProps')
+
+        return
+    }
+}
+
+export async function loader({ request }: { request: any }) {
+    if (!globalThis.__xydPagePathMapping) {
+        throw new Error("PagePathMapping not found")
+    }
+
+    const timedebug = timedebugLoader
+
+    timedebug.total
+
+    const slug = getPathname(request.url || "index") || "index"
+    if (path.extname(slug)) {
+        console.log(`(loader): currently not supporting file extension in slug: ${slug}`);
+        timedebug.totalEnd
+        return {}
+    }
+
+    timedebug.mapSettingsToProps
+
+    const {
+        groups: sidebarGroups,
+        breadcrumbs,
+        navlinks,
+        hiddenPages,
+        metadata
+    } = await mapSettingsToProps( // TOOD: we use mapSettingsToProps twice (in layout) - refactor
+        settings || globalThis.__xydSettings,
+        globalThis.__xydPagePathMapping,
+        slug,
+    )
+    timedebug.mapSettingsToPropsEnd
+
+    function redirectFallback() {
+        if (!sidebarGroups) {
+            return
+        }
+        const firstItem = findFirstUrl(sidebarGroups?.[0]?.items);
+
+        if (firstItem) {
+            return redirect(firstItem)
+        }
+    }
+
+    if (hiddenPages?.[slug]) {
+        const resp = redirectFallback()
+        if (resp) {
+            timedebug.totalEnd
+            return resp
+        }
+    }
+
+    let code = ""
+    let rawPage = ""
+
+    const mdPlugins = markdownPlugins({
+        maxDepth: metadata?.maxTocDepth || settings?.theme?.maxTocDepth || 2,
+    }, settings)
+    
+    const contentFs = new ContentFS(settings, mdPlugins.remarkPlugins, mdPlugins.rehypePlugins)
+
+    const pagePath = globalThis.__xydPagePathMapping[slug]
+    if (pagePath) {
+        timedebug.compile
+        code = await contentFs.compile(pagePath)
+        rawPage = await contentFs.readRaw(pagePath)
+        timedebug.compileEnd
+    } else {
+        const resp = redirectFallback()
+        if (resp) {
+            timedebug.totalEnd
+            return resp
+        }
+    }
+
+    timedebug.totalEnd
+
+    return {
+        sidebarGroups,
+        breadcrumbs,
+        navlinks,
+        slug,
+        code,
+        metadata,
+        rawPage,
+    } as loaderData
+}
+
+interface MetaTag {
+    title?: string
+
+    name?: string
+
+    property?: string
+
+    content?: string
+}
+
+// TODO: better SEO (use https://github.com/unjs/unhead?)
+export function meta(props: any) {
+    const {
+        title = "",
+        description = "",
+    } = props?.data?.metadata || {}
+
+    const metaTags: MetaTag[] = [
+        { title: title },
+    ]
+
+    if (description) {
+        metaTags.push({
+            name: "description",
+            content: description,
+        })
+    }
+
+    const metaTagsMap: {[key: string]: MetaTag} = {}
+
+    for (const key in settings?.seo?.metatags) {
+        const metaType = SUPPORTED_META_TAGS[key]
+        if (!metaType) {
+            continue
+        }
+
+        if (description && key === "description") {
+            continue
+        }
+        
+        metaTagsMap[key] = {
+            [metaType]: key,
+            content: settings?.seo?.metatags[key],
+        }
+    }
+
+    // TOOD: filter?
+    for (const key in props?.data?.metadata) {
+        const metaType = SUPPORTED_META_TAGS[key]
+        if (!metaType) {
+            continue
+        }
+
+        if (description && key === "description") {
+            continue
+        }
+
+        metaTagsMap[key] = {
+            [metaType]: key,
+            content: props?.data?.metadata[key],
+        }
+    }
+
+    if (props?.data?.metadata?.noindex) {
+        metaTagsMap["robots"] = {
+            name: "robots",
+            content: "noindex",
+        }
+    }
+
+    for (const key in metaTagsMap) {
+        metaTags.push(metaTagsMap[key])
+    }
+
+    return metaTags
+}
+
+function findFirstUrl(items: any = []): string {
+    const queue = [...items];
+
+    while (queue.length > 0) {
+        const item = queue.shift();
+
+        if (item.href) {
+            return item.href;
+        }
+
+        if (item.items) {
+            queue.push(...item.items);
+        }
+    }
+
+    return "";
+}
+
+const createElementWithKeys = (type: any, props: any) => {
+    // Process children to add keys to all elements
+    const processChildren = (childrenArray: any[]): any[] => {
+        return childrenArray.map((child, index) => {
+            // If the child is a React element and doesn't have a key, add one
+            if (React.isValidElement(child) && !child.key) {
+                return React.cloneElement(child, { key: `mdx-${index}` });
+            }
+            // If the child is an array, process it recursively
+            if (Array.isArray(child)) {
+                return processChildren(child);
+            }
+            return child;
+        });
+    };
+
+    // Handle both cases: children as separate args or as props.children
+    let processedChildren;
+
+    if (props && props.children) {
+        if (Array.isArray(props.children)) {
+            processedChildren = processChildren(props.children);
+        } else if (React.isValidElement(props.children) && !props.children.key) {
+            // Single child without key
+            processedChildren = React.cloneElement(props.children, { key: 'mdx-child' });
+        } else {
+            // Single child with key or non-React element
+            processedChildren = props.children;
+        }
+    } else {
+        processedChildren = [];
+    }
+
+    // Create the element with processed children
+    return React.createElement(type, {
+        ...props,
+        children: processedChildren
+    });
+};
+
+// TODO: move to content?
+function mdxExport(code: string) {
+    // Create a wrapper around React.createElement that adds keys to elements in lists
+    const scope = {
+        Fragment: React.Fragment,
+        jsxs: createElementWithKeys,
+        jsx: createElementWithKeys,
+        jsxDEV: createElementWithKeys,
+    }
+    const fn = new Function(...Object.keys(scope), code)
+
+    return fn(scope)
+}
+
+// // TODO: move to content?
+function mdxContent(code: string) {
+    const content = mdxExport(code) // TODO: fix any
+    if (!mdxExport) {
+        return {}
+    }
+
+    return {
+        component: content?.default,
+        toc: content?.toc,
+        metadata: content?.frontmatter,
+        themeSettings: content?.themeSettings || {},
+        page: content?.page || false,
+    }
+}
+
+export function MemoMDXComponent(codeComponent: any) {
+    return useMemo(
+        () => codeComponent ? codeComponent : null,
+        [codeComponent]
+    )
+}
+
+export default function DocsPage({ loaderData }: { loaderData: loaderData }) {
+    const location = useLocation()
+
+    const { theme } = useContext(PageContext)
+    if (!theme) {
+        throw new Error("BaseTheme not found")
+    }
+
+    const content = mdxContent(loaderData.code)
+    const Content = MemoMDXComponent(content.component)
+
+    const themeContentComponents = theme.reactContentComponents()
+    const { Page } = theme
+
+    return <FrameworkPage
+        key={location.pathname}
+        metadata={content.metadata}
+        breadcrumbs={loaderData.breadcrumbs}
+        rawPage={loaderData.rawPage}
+        toc={content.toc || []}
+        navlinks={loaderData.navlinks}
+        ContentComponent={Content}
+    >
+        <Page>
+            <Content components={themeContentComponents} />
+            <ScrollRestoration />
+        </Page>
+    </FrameworkPage>
+}
+
+

package/src/presets/docs/index.ts

@@ -0,0 +1,232 @@
+import { promises as fs } from 'fs';
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { createServer, Plugin as VitePlugin } from "vite";
+import { route } from "@react-router/dev/routes";
+
+import { Settings } from "@xyd-js/core";
+
+import { Preset, PresetData } from "../../types";
+import { readSettings } from "./settings";
+import { DEFAULT_THEME, THEME_CONFIG_FOLDER } from "../../const";
+import { getDocsPluginBasePath, getHostPath } from "../../utils";
+
+interface docsPluginOptions {
+    urlPrefix?: string
+}
+
+// TODO: find better solution - maybe something what rr7 use?
+async function loadModule(filePath: string) {
+    const server = await createServer({
+        optimizeDeps: {
+            include: ["react/jsx-runtime"],
+        },
+    });
+
+    try {
+        const module = await server.ssrLoadModule(filePath);
+        return module.default;
+    } finally {
+        await server.close();
+    }
+}
+
+function preinstall() {
+    return async function docsPluginInner(_, data: PresetData) {
+        // TODO: configurable root?
+        const root = process.cwd()
+
+        const settings = await readSettings()
+        if (settings && !settings.theme) {
+            settings.theme = {
+                name: DEFAULT_THEME
+            }
+        }
+        
+        let themeRoutesExists = false
+        try {
+            await fs.access(path.join(root, THEME_CONFIG_FOLDER, "./routes.ts"))
+            themeRoutesExists = true
+        } catch (_) {
+        }
+
+        if (themeRoutesExists) {
+            const routeMod = await loadModule(path.join(root, THEME_CONFIG_FOLDER, "./routes.ts"))
+
+            const routes = routeMod((routePath, routeFile, routeOptions) => {
+                return route(routePath, path.join(root, THEME_CONFIG_FOLDER, routeFile), routeOptions)
+            })
+
+            data.routes.push(...routes)
+        }
+
+        return {
+            settings
+        }
+    }
+}
+
+// TODO: maybe later as a separate plugin?
+function vitePluginSettings() {
+    return async function ({ preinstall }): Promise<VitePlugin> {
+        return {
+            name: 'virtual:xyd-settings',
+            resolveId(id) {
+                if (id === 'virtual:xyd-settings') {
+                    return id + '.jsx'; // Return the module with .jsx extension
+                }
+                return null;
+            },
+            async load(id) { // TODO: better cuz we probably dont neeed `get settings()`
+                if (id === 'virtual:xyd-settings.jsx') {
+                    return `
+                        export default {
+                            get settings() {
+                                return globalThis.__xydSettings || ${typeof preinstall.settings === "string" ? preinstall.settings : JSON.stringify(preinstall.settings)}
+                            }
+                        }
+                    `
+                }
+                return null;
+            },
+        };
+    }
+}
+
+
+export function vitePluginThemeCSS() {
+    return async function ({
+        preinstall
+    }: {
+        preinstall: {
+            settings: Settings
+        }
+    }): Promise<VitePlugin> {
+        return {
+            name: 'virtual:xyd-theme/index.css',
+
+            resolveId(source) {
+                if (source === 'virtual:xyd-theme/index.css') {
+                    const __filename = fileURLToPath(import.meta.url);
+                    const __dirname = path.dirname(__filename);
+
+                    const themeName = preinstall.settings.theme?.name || DEFAULT_THEME
+                    let themePath = ""
+
+                    if (process.env.XYD_CLI) {
+                        themePath = path.join(getHostPath(), `node_modules/@xyd-js/theme-${themeName}/dist`)
+                    } else {
+                        themePath = path.join(path.resolve(__dirname, "../../"), `xyd-theme-${themeName}/dist`)
+                    }
+
+                    return path.join(themePath, "index.css")
+                }
+
+                return null;
+            }
+        };
+    }
+}
+
+export function vitePluginThemeOverrideCSS() {
+    return async function ({ preinstall }: { preinstall: { settings: Settings } }): Promise<VitePlugin> {
+        return {
+            name: 'virtual:xyd-theme-override-css',
+
+            async resolveId(id) {
+                if (id === 'virtual:xyd-theme-override/index.css') {
+                    const root = process.cwd();
+                    const filePath = path.join(root, THEME_CONFIG_FOLDER, "./index.css");
+
+                    try {
+                        await fs.access(filePath);
+                        return filePath;
+                    } catch {
+                        // File does not exist, omit it
+                        return 'virtual:xyd-theme-override/empty.css';
+                    }
+                }
+                return null;
+            },
+
+            async load(id) {
+                if (id === 'virtual:xyd-theme-override/empty.css') {
+                    // Return an empty module
+                    return '';
+                }
+                return null;
+            },
+        };
+    };
+}
+
+export function vitePluginTheme() {
+    return async function ({
+        preinstall
+    }: {
+        preinstall: {
+            settings: Settings
+        }
+    }): Promise<VitePlugin> {
+        return {
+            name: 'virtual:xyd-theme',
+            resolveId(id) {
+                if (id === 'virtual:xyd-theme') {
+                    return id;
+                }
+                return null;
+            },
+            async load(id) {
+                if (id === 'virtual:xyd-theme') {
+                    // return ''
+                    const __filename = fileURLToPath(import.meta.url);
+                    const __dirname = path.dirname(__filename);
+
+                    const themeName = preinstall.settings.theme?.name || DEFAULT_THEME
+                    let themePath = ""
+
+                    if (process.env.XYD_CLI) {
+                        themePath = `@xyd-js/theme-${themeName}`
+                    } else {
+                        themePath = path.join(path.resolve(__dirname, "../../"), `xyd-theme-${themeName}/src`)
+                    }
+
+                    // Return a module that imports the theme from the local workspace
+                    return `
+                        import Theme from '${themePath}';
+                        
+                        export default Theme;
+                    `;
+                }
+                return null;
+            }
+        };
+    }
+}
+
+function preset(settings: Settings, options: docsPluginOptions) {
+    const basePath = getDocsPluginBasePath()
+
+    return {
+        preinstall: [
+            preinstall,
+        ],
+        routes: [
+            route("", path.join(basePath, "src/pages/docs.tsx")),
+            // TODO: custom routes
+            route(options.urlPrefix ? `${options.urlPrefix}/*` : "*", path.join(basePath, "src/pages/docs.tsx"), {
+                id: "xyd-plugin-docs/docs",
+            }),
+        ],
+        vitePlugins: [
+            vitePluginSettings,
+            vitePluginTheme,
+            vitePluginThemeCSS,
+            vitePluginThemeOverrideCSS,
+        ],
+        basePath
+    }
+}
+
+export const docsPreset = preset as Preset<unknown>