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

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# @xyd-js/plugin-docs
+
+## 0.1.0-xyd.3
+
+### Patch Changes
+
+- documan + plugin-docs
+
+## 0.1.0-xyd.2
+
+### Patch Changes
+
+- test
+- Updated dependencies
+  - @xyd-js/components@0.1.0-xyd.13
+  - @xyd-js/composer@0.1.0-xyd.2
+  - @xyd-js/content@0.1.0-xyd.16
+  - @xyd-js/core@0.1.0-xyd.15
+  - @xyd-js/framework@0.1.0-xyd.34
+  - @xyd-js/gql@0.1.0-xyd.15
+  - @xyd-js/openapi@0.1.0-xyd.13
+  - @xyd-js/sources@0.1.1-xyd.5
+  - @xyd-js/themes@0.1.1-xyd.5
+  - @xyd-js/uniform@0.1.0-xyd.17
+
+## 0.1.0-xyd.1
+
+### Patch Changes
+
+- update packages
+- Updated dependencies
+  - @xyd-js/components@0.1.0-xyd.12
+  - @xyd-js/composer@0.1.0-xyd.1
+  - @xyd-js/content@0.1.0-xyd.15
+  - @xyd-js/core@0.1.0-xyd.14
+  - @xyd-js/framework@0.1.0-xyd.33
+  - @xyd-js/gql@0.1.0-xyd.14
+  - @xyd-js/openapi@0.1.0-xyd.12
+  - @xyd-js/sources@0.1.1-xyd.4
+  - @xyd-js/themes@0.1.1-xyd.4
+  - @xyd-js/uniform@0.1.0-xyd.16

package/TODO.md

@@ -0,0 +1 @@
+1. better API

package/package.json

@@ -1,25 +1,15 @@
 {
   "name": "@xyd-js/plugin-docs",
-  "version": "0.1.0-xyd.2",
+  "version": "0.1.0-xyd.3",
   "description": "",
   "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "exports": {
-    "./package.json": "./package.json",
-    ".": "./dist/index.js"
-  },
-  "files": [
-    "dist",
-    "package.json"
-  ],
   "dependencies": {
     "codehike": "^1.0.3",
     "@code-hike/lighter": "^1.0.3",
-    "@xyd-js/openapi": "0.1.0-xyd.13",
     "@xyd-js/uniform": "0.1.0-xyd.17",
+    "@xyd-js/sources": "0.1.1-xyd.5",
     "@xyd-js/gql": "0.1.0-xyd.15",
-    "@xyd-js/sources": "0.1.1-xyd.5"
+    "@xyd-js/openapi": "0.1.0-xyd.13"
   },
   "peerDependencies": {
     "@react-router/dev": "^7.5.0",
@@ -31,8 +21,8 @@
     "@xyd-js/framework": "0.1.0-xyd.34",
     "@xyd-js/composer": "0.1.0-xyd.2",
     "@xyd-js/themes": "0.1.1-xyd.5",
-    "@xyd-js/content": "0.1.0-xyd.16",
     "@xyd-js/components": "0.1.0-xyd.13",
+    "@xyd-js/content": "0.1.0-xyd.16",
     "@xyd-js/core": "0.1.0-xyd.15"
   },
   "devDependencies": {

package/src/const.ts

@@ -0,0 +1,7 @@
+import {ThemePresetName} from "@xyd-js/core";
+
+export const THEME_CONFIG_FOLDER = ".docs/theme" // TODO: in the future shared internal const like `.xyd` and `.docs` ?
+// TODO: SHARED
+export const VIRTUAL_CONTENT_FOLDER = ".xyd/.cache/.content"
+
+export const DEFAULT_THEME: ThemePresetName = "poetry"

package/src/declarations.d.ts

@@ -0,0 +1,23 @@
+// declarations.d.ts
+
+
+declare module 'virtual:xyd-settings' {
+    import type {Settings} from "@xyd-js/core";
+
+    const settings: Settings;
+    export default settings;
+    export {
+        settings as Settings
+    }
+}
+
+declare module 'virtual:xyd-theme' {
+    import {BaseTheme} from "@xyd-js/themes";
+    import {Theme as ThemeSettings} from "@xyd-js/core";
+
+    // Export a concrete theme class that extends BaseTheme
+    class ConcreteTheme extends BaseTheme {
+        constructor();
+    }
+    export default ConcreteTheme;
+}

package/src/index.ts

@@ -0,0 +1,305 @@
+import {Navigation, Settings} from "@xyd-js/core";
+import type {Plugin as VitePlugin} from "vite";
+import {RouteConfigEntry} from "@react-router/dev/routes";
+import type {PageURL, Sidebar, SidebarRoute} from "@xyd-js/core";
+import fs from "fs";
+import path from "path";
+
+import {docsPreset} from "./presets/docs";
+import {graphqlPreset} from "./presets/graphql";
+import {openapiPreset} from "./presets/openapi";
+import {sourcesPreset} from "./presets/sources";
+
+import type {PluginOutput, Plugin} from "./types";
+import {ensureAndCleanupVirtualFolder} from "./presets/uniform";
+
+export {readSettings} from "./presets/docs/settings"
+
+export interface PluginDocsOptions {
+    disableAPIGeneration?: boolean
+    disableFSWrite?: boolean
+}
+
+// TODO: better plugin runner
+// TODO: REFACTOR
+export async function pluginDocs(options?: PluginDocsOptions): Promise<PluginOutput | null> {
+    let settings: Settings | null = null
+    const vitePlugins: VitePlugin[] = []
+    const routes: RouteConfigEntry[] = []
+    let basePath = ""
+
+    // base docs preset setup
+    {
+        const options = {
+            urlPrefix: "" // TODO: configurable
+        }
+
+        const docs = docsPreset(undefined, options)
+        docs.preinstall = docs.preinstall || []
+
+        let preinstallMerge = {}
+
+        for (const preinstall of docs.preinstall) {
+            const resp = await preinstall()({}, {
+                routes: docs.routes
+            })
+
+            if (resp && typeof resp === 'object') {
+                preinstallMerge = {
+                    ...preinstallMerge,
+                    ...resp
+                }
+            }
+        }
+
+        docs.vitePlugins = docs.vitePlugins || []
+        for (const vitePlugin of docs.vitePlugins) {
+            const vitePlug = await vitePlugin()({
+                preinstall: preinstallMerge
+            })
+
+            vitePlugins.push(vitePlug)
+        }
+
+        if ("settings" in preinstallMerge) {
+            settings = preinstallMerge.settings as Settings
+        }
+
+        docs.routes = docs.routes || []
+        routes.push(...docs.routes)
+        basePath = docs.basePath
+    }
+
+    if (!settings) {
+        return null
+    }
+
+    await ensureAndCleanupVirtualFolder()
+
+    // graphql preset setup
+    if (!options?.disableAPIGeneration && settings?.api?.graphql) {
+        const opt = {
+            disableFSWrite: options?.disableFSWrite
+        }
+
+        const gql = graphqlPreset(settings, opt)
+        gql.preinstall = gql.preinstall || []
+
+        let preinstallMerge = {}
+
+        for (const preinstall of gql.preinstall) {
+            const resp = await preinstall(opt)(settings, {
+                routes: gql.routes,
+            })
+
+            if (resp && typeof resp === 'object') {
+                preinstallMerge = {
+                    ...preinstallMerge,
+                    ...resp
+                }
+            }
+        }
+
+        gql.vitePlugins = gql.vitePlugins || []
+        for (const vitePlugin of gql.vitePlugins) {
+            const vitePlug = await vitePlugin()({
+                preinstall: preinstallMerge
+            })
+
+            vitePlugins.push(vitePlug)
+        }
+
+        gql.routes = gql.routes || []
+        routes.push(...gql.routes)
+    }
+
+    // openapi preset setup
+    if (!options?.disableAPIGeneration && settings?.api?.openapi) {
+        const opt = {
+            disableFSWrite: options?.disableFSWrite
+        }
+
+        const oap = openapiPreset(settings, opt)
+        oap.preinstall = oap.preinstall || []
+
+        let preinstallMerge = {}
+
+        for (const preinstall of oap.preinstall) {
+            const resp = await preinstall(opt)(settings, {
+                routes: oap.routes,
+            })
+
+            if (resp && typeof resp === 'object') {
+                preinstallMerge = {
+                    ...preinstallMerge,
+                    ...resp
+                }
+            }
+        }
+
+        oap.vitePlugins = oap.vitePlugins || []
+        for (const vitePlugin of oap.vitePlugins) {
+            const vitePlug = await vitePlugin()({
+                preinstall: preinstallMerge
+            })
+
+            vitePlugins.push(vitePlug)
+        }
+
+        oap.routes = oap.routes || []
+        routes.push(...oap.routes)
+    }
+
+    if (!options?.disableAPIGeneration && settings?.api?.sources) {
+        const opt = {
+            disableFSWrite: options?.disableFSWrite
+        }
+
+        const src = sourcesPreset(settings, opt)
+        src.preinstall = src.preinstall || []
+
+        let preinstallMerge = {}
+
+        for (const preinstall of src.preinstall) {
+            const resp = await preinstall(opt)(settings, {
+                routes: src.routes,
+            })
+
+            if (resp && typeof resp === 'object') {
+                preinstallMerge = {
+                    ...preinstallMerge,
+                    ...resp
+                }
+            }
+        }
+
+        src.vitePlugins = src.vitePlugins || []
+        for (const vitePlugin of src.vitePlugins) {
+            const vitePlug = await vitePlugin()({
+                preinstall: preinstallMerge
+            })
+
+            vitePlugins.push(vitePlug)
+        }
+
+        src.routes = src.routes || []
+        routes.push(...src.routes)
+    }
+
+    let pagePathMapping: Record<string, string> = {}
+
+    if (settings?.navigation) {
+        pagePathMapping = mapNavigationToPagePathMapping(settings?.navigation)
+    } else {
+        console.warn("No navigation found in settings")
+    }
+
+    sortSidebarGroups(settings?.navigation?.sidebar || [])
+    
+    return {
+        vitePlugins,
+        settings,
+        routes,
+        basePath,
+        pagePathMapping
+    }
+}
+
+function sortSidebarGroups(sidebar: (SidebarRoute | Sidebar | string)[]) {
+    // Sort items within each SidebarRoute
+    for (const group of sidebar) {
+        if (typeof group === 'string') {
+            continue // Skip string entries
+        }
+        if ('pages' in group && Array.isArray(group.pages)) {
+            group.pages.sort((a, b) => {
+                // If both have numeric sort values, compare them
+                if (typeof a.sort === 'number' && typeof b.sort === 'number') {
+                    return a.sort - b.sort
+                }
+                // If only a has numeric sort, it comes first
+                if (typeof a.sort === 'number') {
+                    return -1
+                }
+                // If only b has numeric sort, it comes first
+                if (typeof b.sort === 'number') {
+                    return 1
+                }
+                // If neither has numeric sort, maintain original order
+                return 0
+            })
+        }
+    }
+}
+
+// TODO: in the future better algorithm - we should be .md/.mdx faster than checking fs here
+function mapNavigationToPagePathMapping(navigation: Navigation) {
+    const mapping: Record<string, string> = {}
+
+    function getExistingFilePath(basePath: string): string | null {
+        const mdPath = `${basePath}.md`
+        const mdxPath = `${basePath}.mdx`
+
+        if (fs.existsSync(mdPath)) {
+            return mdPath
+        }
+        if (fs.existsSync(mdxPath)) {
+            return mdxPath
+        }
+        return null
+    }
+
+    function processPages(pages: PageURL[]) {
+        for (const page of pages) {
+            if (typeof page === 'string') {
+                // Handle regular page
+                const existingPath = getExistingFilePath(page)
+                if (existingPath) {
+                    mapping[page] = existingPath
+                }
+            } else if (typeof page === 'object' && 'virtual' in page) {
+                // Handle virtual page
+                const virtualPath = page.virtual
+                const pagePath = page.page
+                const existingPath = getExistingFilePath(virtualPath)
+                if (existingPath) {
+                    mapping[pagePath] = existingPath
+                }
+            } else if (typeof page === 'object' && 'pages' in page) {
+                // Handle nested sidebar
+                processPages(page.pages || [])
+            }
+        }
+    }
+
+    let sidebarFlatOnly = false
+    // Process each sidebar route
+    for (const sidebar of navigation.sidebar) {
+        if (typeof sidebar === 'string') {
+            sidebarFlatOnly = true
+            break
+        } else if ('pages' in sidebar && "route" in sidebar) {
+            // Handle SidebarRoute
+            for (const item of sidebar.pages) {
+                if (item?.pages) {
+                    processPages(item.pages)
+                }
+            }
+        } else if ('pages' in sidebar) {
+            // Handle Sidebar
+            processPages(sidebar.pages || [])
+        }
+    }
+
+    if (sidebarFlatOnly) {
+        const sidebar = navigation.sidebar as string[]
+        processPages(sidebar)
+    }
+
+    return mapping
+}
+
+export type {
+    Plugin,
+    PluginOutput
+}

package/src/pages/context.tsx

@@ -0,0 +1,9 @@
+import { createContext } from "react";
+
+import { BaseTheme } from "@xyd-js/themes";
+
+export const PageContext = createContext<{
+    theme: BaseTheme | null
+}>({
+    theme: null
+})

package/src/pages/layout.tsx

@@ -0,0 +1,263 @@
+import { useMemo } from "react";
+import {
+    Outlet,
+    useLoaderData,
+    useLocation,
+    useNavigate,
+    useNavigation,
+    useMatches
+} from "react-router";
+
+import { mapSettingsToProps } from "@xyd-js/framework/hydration";
+
+import type { Metadata, MetadataMap, Theme as ThemeSettings } from "@xyd-js/core";
+import type { INavLinks, IBreadcrumb } from "@xyd-js/ui";
+import { Framework, FwLink, useSettings, type FwSidebarGroupProps } from "@xyd-js/framework/react";
+import { ReactContent } from "@xyd-js/components/content";
+import { Atlas, AtlasContext, type VariantToggleConfig } from "@xyd-js/atlas";
+import AtlasXydPlugin from "@xyd-js/atlas/xydPlugin";
+
+import { Surfaces } from "@xyd-js/framework/react";
+import { Composer } from "@xyd-js/composer";
+// @ts-ignore
+import { iconSet } from 'virtual:xyd-icon-set';
+
+// @ts-ignore
+import virtualSettings from "virtual:xyd-settings";
+// @ts-ignore
+const { settings: getSettings } = virtualSettings
+// const settings = globalThis.__xydSettings
+import Theme from "virtual:xyd-theme";
+
+// @ts-ignore
+import "virtual:xyd-theme/index.css"
+import "virtual:xyd-theme-override/index.css"
+
+import { PageContext } from "./context";
+import React from "react";
+import { markdownPlugins } from "@xyd-js/content/md";
+import { ContentFS } from "@xyd-js/content";
+import { IconProvider } from "@xyd-js/components/writer";
+import { CoderProvider } from "@xyd-js/components/coder";
+
+globalThis.__xydSettings = getSettings
+
+new Composer() // TODO: better API
+const settings = globalThis.__xydSettings
+
+const surfaces = new Surfaces()
+const atlasXyd = AtlasXydPlugin()(settings) // TODO: in the future via standard plugin API
+const SidebarItemRight = atlasXyd?.customComponents?.["AtlasSidebarItemRight"]
+
+if (SidebarItemRight) {
+    surfaces.define(
+        SidebarItemRight.surface,
+        SidebarItemRight.component,
+    )
+}
+
+const reactContent = new ReactContent(settings, {
+    Link: FwLink,
+    components: {
+        Atlas,
+    },
+    useLocation, // // TODO: !!!! BETTER API !!!!!
+    useNavigate,
+    useNavigation
+})
+globalThis.__xydThemeSettings = settings?.theme
+globalThis.__xydReactContent = reactContent
+globalThis.__xydSurfaces = surfaces
+
+const theme = new Theme()
+
+const { Layout: BaseThemeLayout } = theme
+
+interface LoaderData {
+    sidebarGroups: FwSidebarGroupProps[]
+    breadcrumbs: IBreadcrumb[],
+    toc: MetadataMap,
+    slug: string
+    metadata: Metadata | null
+    navlinks?: INavLinks,
+    bannerContentCode?: string
+}
+
+export async function loader({ request }: { request: any }) {
+    const slug = getPathname(request.url || "index") || "index"
+
+    const {
+        groups: sidebarGroups,
+        breadcrumbs,
+        navlinks,
+        metadata
+    } = await mapSettingsToProps(
+        settings,
+        globalThis.__xydPagePathMapping,
+        slug,
+    )
+
+    let bannerContentCode = ""
+
+    const mdPlugins = markdownPlugins({
+        maxDepth: metadata?.maxTocDepth || settings?.theme?.maxTocDepth || 2,
+    }, settings)
+    const contentFs = new ContentFS(settings, mdPlugins.remarkPlugins, mdPlugins.rehypePlugins)
+
+    if (settings?.theme?.banner?.content && typeof settings?.theme?.banner?.content === "string") {
+        bannerContentCode = await contentFs.compileContent(
+            settings?.theme?.banner?.content,
+        )
+    }
+
+    return {
+        sidebarGroups,
+        breadcrumbs,
+        navlinks,
+        slug,
+        metadata,
+        bannerContentCode
+    } as LoaderData
+}
+
+export default function Layout() {
+    const loaderData = useLoaderData<LoaderData>()
+    const matches = useMatches()
+
+    const lastMatchId = matches[matches.length - 1]?.id || null
+
+    let atlasVariantToggles: VariantToggleConfig[] = [];
+
+    // TODO: BETTER HANDLE THAT
+    if (loaderData.metadata?.openapi) {
+        atlasVariantToggles = [
+            { key: "status", defaultValue: "200" },
+            { key: "contentType", defaultValue: "application/json" }
+        ];
+    } else {
+        atlasVariantToggles = [
+            { key: "symbolName", defaultValue: "" }
+        ];
+    }
+
+    let bannerContent: any = null
+    // TODO: !!!! BETTER API !!!!
+    if (loaderData.bannerContentCode) {
+        const content = mdxContent(loaderData.bannerContentCode)
+        const BannerContent = MemoMDXComponent(content.component)
+
+        bannerContent = function () {
+            return <BannerContent components={theme.reactContentComponents()} />
+        }
+    }
+
+    return <>
+        <IconProvider value={{
+            iconSet: iconSet
+        }}>
+            <Framework
+                settings={settings || globalThis.__xydSettings}
+                sidebarGroups={loaderData.sidebarGroups || []}
+                metadata={loaderData.metadata || {}}
+                surfaces={surfaces}
+                BannerContent={bannerContent}
+            >
+                <AtlasContext
+                    value={{
+                        syntaxHighlight: settings?.theme?.coder?.syntaxHighlight || null,
+                        baseMatch: lastMatchId || "",
+                        variantToggles: atlasVariantToggles
+                    }}
+                >
+                    <CoderProvider lines={settings?.theme?.coder?.lines} scroll={settings?.theme?.coder?.scroll}>
+                        <BaseThemeLayout>
+                            <PageContext value={{ theme }}>
+                                <Outlet />
+                            </PageContext>
+                        </BaseThemeLayout>
+                    </CoderProvider>
+                </AtlasContext>
+            </Framework>
+        </IconProvider>
+    </>
+}
+
+function getPathname(url: string) {
+    const parsedUrl = new URL(url);
+    return parsedUrl.pathname.replace(/^\//, '');
+}
+
+
+// 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,
+    }
+}
+
+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
+    });
+};
+
+function MemoMDXComponent(codeComponent: any) {
+    return useMemo(
+        () => codeComponent ? codeComponent : null,
+        [codeComponent]
+    )
+}