@xyd-js/uniform 0.1.0-xyd.2

package/README.md

@@ -0,0 +1,3 @@
+# @xyd-js/uniform
+
+uniform is a collection of common interfaces and utils for xyd api reference content.

package/content.ts

@@ -0,0 +1 @@
+export * from "./src/content"

package/index.ts

@@ -0,0 +1,8 @@
+export {default} from "./src/index"
+
+export {
+    pluginNavigation
+} from "./src/utils"
+
+export * from "./src/types"
+

package/markdown.ts

@@ -0,0 +1 @@
+export * from "./src/markdown";

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@xyd-js/uniform",
+  "version": "0.1.0-xyd.2",
+  "description": "",
+  "main": "./dist/index.js",
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": "./dist/index.js",
+    "./markdown": "./dist/markdown.js",
+    "./content": "./dist/content.js"
+  },
+  "dependencies": {
+    "remark": "^15.0.1",
+    "remark-stringify": "^11.0.0",
+    "gray-matter": "^4.0.3",
+    "unist-builder": "^4.0.0",
+    "unist-util-visit": "^5.0.0",
+    "codehike": "^1.0.3",
+    "@xyd-js/core": "0.1.0-xyd.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.0"
+  },
+  "peerDependencies": {
+    "@mdx-js/mdx": "^3.1.0"
+  },
+  "scripts": {
+    "clean": "rimraf build",
+    "prebuild": "pnpm clean",
+    "build": "tsup"
+  }
+}

package/src/content/index.ts

@@ -0,0 +1,124 @@
+import path from "path";
+import {promises as fs} from "fs";
+
+import React from "react";
+import {parse} from "codehike";
+import {visit} from "unist-util-visit";
+import {recmaCodeHike, remarkCodeHike} from "codehike/mdx";
+import {compile as mdxCompile} from "@mdx-js/mdx";
+
+const codeHikeOptions = {
+    lineNumbers: true,
+    showCopyButton: true,
+    autoImport: true,
+    components: {code: "Code"},
+    // syntaxHighlighting: { // TODO: !!! FROM SETTINGS !!! wait for rr7 rsc ??
+    //     theme: "github-dark",
+    // },
+};
+//
+// // since unist does not support heading level > 6, we need to normalize them
+function normalizeCustomHeadings() {
+    return (tree: any) => {
+        visit(tree, 'paragraph', (node, index, parent) => {
+            const match = node.children[0] && node.children[0].value.match(/^(#+)\s+(.*)/);
+            if (match) {
+                const level = match[1].length;
+                const text = match[2];
+                if (level > 6) {
+                    // Create a new heading node with depth 6
+                    const headingNode = {
+                        type: 'heading',
+                        depth: level,
+                        children: [{type: 'text', value: text}]
+                    };
+                    // Replace the paragraph node with the new heading node
+                    //@ts-ignore
+                    parent.children[index] = headingNode;
+                }
+            }
+        });
+    };
+}
+
+//
+async function compile(content: string): Promise<string> {
+    const compiled = await mdxCompile(content, {
+        remarkPlugins: [normalizeCustomHeadings, [remarkCodeHike, codeHikeOptions]],
+        recmaPlugins: [
+            [recmaCodeHike, codeHikeOptions]
+        ],
+        outputFormat: 'function-body',
+        development: false,
+    });
+
+    return String(compiled)
+}
+
+async function compileBySlug(slug: string) {
+    // TODO: cwd ?
+    const filePath = path.join(process.cwd(), `${slug}.md`)
+
+    try {
+        await fs.access(filePath)
+    } catch (e) {
+        console.error(e)
+        return ""
+    }
+
+    const content = await fs.readFile(filePath, "utf-8");
+
+    return await compile(content)
+}
+
+function getMDXComponent(code: string) {
+    const mdxExport = getMDXExport(code)
+    return mdxExport.default
+}
+
+function getMDXExport(code: string) {
+    const scope = {
+        Fragment: React.Fragment,
+        jsxs: React.createElement,
+        jsx: React.createElement,
+        jsxDEV: React.createElement,
+    }
+    const fn = new Function(...Object.keys(scope), code)
+    return fn(scope)
+}
+
+//
+// function MDXContent(code: string) {
+//     return React.useMemo(
+//         () => code ? getMDXComponent(code) : null,
+//         [code]
+//     )
+// }
+
+// TODO: mod ts
+async function lazyReferences(mod: any) {
+    const references: any[] = []
+
+    if (Array.isArray(mod.default)) {
+        for (const chunk of mod.default) {
+            try {
+                const code = await compile(chunk) // TODO: do we need real path?
+                const Content = getMDXComponent(code)
+                const content = Content ? parse(Content) : null
+
+                references.push(...content.references as [])
+            } catch (e) {
+                console.error(e)
+            }
+        }
+    } else {
+        console.warn(`mod.default is not an array, current type is: ${typeof mod.default}`)
+    }
+
+    return references
+}
+
+export {
+    compileBySlug,
+    lazyReferences
+}

package/src/index.ts

@@ -0,0 +1,87 @@
+// Define the new PluginV type with a callback function that returns another function
+import {Reference} from "./types";
+
+// Define the new PluginV type with a callback function that returns another function
+export type UniformPlugin<T> = (cb: (cb: () => T) => void) => (ref: Reference) => void;
+
+// Utility type to infer if a type is an array and avoid wrapping it into an array twice
+type NormalizeArray<T> = T extends Array<infer U> ? U[] : T;
+
+// Infer the return type of the plugin callback properly and normalize array types
+type PluginResult<T extends UniformPlugin<any>> = T extends UniformPlugin<infer R> ? R : never;
+
+// Merge all plugin return types into a single object and normalize arrays
+type MergePluginResults<T extends UniformPlugin<any>[]> = {
+    [K in keyof UnionToIntersection<PluginResult<T[number]>>]: NormalizeArray<UnionToIntersection<PluginResult<T[number]>>[K]>
+};
+
+// Utility type to handle intersection to an object type
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+
+// Implement the uniform function
+export default function uniform<T extends UniformPlugin<any>[]>(
+    references: Reference[],
+    config: { plugins: T }
+) {
+    // Infer the merged result type from all plugins
+    type ResultType = MergePluginResults<T>;
+
+    // Initialize the response with a type-safe out object
+    const response: {
+        references: Reference[]
+        out: { [K in keyof ResultType]: ResultType[K] }
+    } = {
+        references,
+        out: {} as { [K in keyof ResultType]: ResultType[K] }
+    };
+
+
+    const finishCallbacks = new Set();
+
+    config.plugins.forEach((plugin) => {
+        const call = plugin(cb => {
+            finishCallbacks.add(cb);
+        })
+
+        references.forEach((ref) => {
+            call(ref)
+        });
+    })
+
+    finishCallbacks.forEach(cb => {
+        if (typeof cb === "function") {
+            const resp = cb()
+            if (typeof resp !== "object") {
+                throw new Error(`Invalid callback return type: ${typeof resp}`)
+            }
+
+            response.out = {
+                ...response.out,
+                ...resp
+            }
+        } else {
+            throw new Error(`Invalid callback type: ${typeof cb}`)
+        }
+    });
+
+    return response;
+}
+
+// Example usage
+// const examplePlugin: UniformPlugin<{ value: boolean }> = (cb) => {
+//     return (ref: Reference) => {
+//     };
+// };
+// function examplePlugin(cb: (cb: () => { value: boolean }) => void) {
+//     cb(() => ({
+//         value: true,
+//     }));
+//
+//     return (ref: Reference) => {
+//
+//     };
+// }
+// const response = uniform([/* references */], {
+//     plugins: [examplePlugin],
+// });
+// response.out

package/src/markdown/index.ts

@@ -0,0 +1,64 @@
+import {remark} from "remark";
+import remarkStringify from "remark-stringify";
+
+import {Reference} from "../types";
+
+import {definitions, examples, heading, root} from "./utils";
+
+// TODO: any
+export function compile(ast: any) {
+    return remark()
+        // .use(unlimitedHeadings)
+        .use(remarkStringify, {
+            bullet: '-',
+            fences: true,
+            listItemIndent: 'one',
+            incrementListMarker: false,
+            handlers: {
+                heading(node) {
+                    return `${"#".repeat(node.depth)} ${node.children[0].value}`;
+                },
+            },
+        })
+        .stringify(root(ast));
+}
+
+export function referenceAST(ref: Reference) {
+    const md = []
+
+    const mdHeading = heading(
+        ref.title,
+        ref.canonical,
+        ref.description,
+        ref.category,
+        ref.type,
+        ref.context
+    )
+
+    if (mdHeading?.description?.length) {
+        md.push(...mdHeading.description)
+    }
+
+    md.push(
+        mdHeading.title,
+        mdHeading.canonical,
+    )
+
+    if (mdHeading.category) {
+        md.push(mdHeading.category)
+    }
+
+    if (mdHeading.type) {
+        md.push(mdHeading.type)
+    }
+
+    if (mdHeading?.context?.length) {
+        md.push(...mdHeading.context)
+    }
+
+    const mdExamples = examples(ref.examples)
+    const mdDefinitions = definitions(ref.definitions)
+    md.push(...mdExamples, ...mdDefinitions)
+
+    return md;
+}

package/src/markdown/utils.ts

@@ -0,0 +1,235 @@
+import {u} from "unist-builder";
+
+import {
+    ExampleRoot,
+    Definition,
+    ReferenceCategory,
+    ReferenceContext,
+    ReferenceType,
+    DefinitionProperty
+} from "../types";
+
+// START_DEPTH_LEVEL is the start depth level for the markdown AST
+// starts from 2 because 1 is reserved for the title
+const START_DEPTH_LEVEL = 2
+
+// TODO: fix any
+export function root(ast: any) {
+    return u('root', ast);
+}
+
+export function heading(
+    title: string,
+    canonical: string,
+    description: string,
+    refCategory?: ReferenceCategory,
+    refType?: ReferenceType,
+    refContext?: ReferenceContext
+) {
+    const uTitle = u(
+        'heading',
+        {depth: START_DEPTH_LEVEL},
+        [u('text', `!!references ${title}`)]
+    )
+
+    const uCanonical = u(
+        'heading',
+        {depth: uTitle.depth + 1},
+        [u('text', `!canonical ${canonical}`)]
+    )
+
+    let uDesc = [
+        u(
+            'heading',
+            {depth: START_DEPTH_LEVEL},
+            [u('text', `!description`),]
+        ),
+        u('paragraph', [u('text', description)])
+    ]
+
+
+    let uRefCategory
+    if (refCategory) {
+        uRefCategory = u(
+            'heading',
+            {depth: uTitle.depth + 1},
+            [u('text', `!category ${refCategory}`)]
+        )
+    }
+
+    let uRefType
+    if (refType) {
+        uRefType = u(
+            'heading',
+            {depth: uTitle.depth + 1},
+            [u('text', `!type ${refType}`)]
+        )
+    }
+
+    let uContext = []
+
+    if (refContext && Object.keys(refContext)) {
+        uContext.push(u(
+            'heading',
+            {depth: uTitle.depth + 1},
+            [
+                u('text', `!context`),
+            ]
+        ))
+
+
+        for (const [key, value] of Object.entries(refContext)) {
+            uContext.push(u(
+                    'heading',
+                    {depth: uContext[0].depth + 1},
+                    [u('text', `!${key} ${value}`)]
+                )
+            )
+        }
+    }
+
+    return {
+        title: uTitle,
+        canonical: uCanonical,
+        description: uDesc,
+        category: uRefCategory || null,
+        type: uRefType || null,
+        context: uContext || null
+    }
+}
+
+export function examples(examples: ExampleRoot) {
+    const md = []
+
+    const uExampleRoot = u(
+        'heading',
+        {depth: START_DEPTH_LEVEL + 1},
+        [u('text', `!examples`)]
+    )
+    md.push(uExampleRoot)
+
+    examples.groups.forEach(group => {
+        const uExampleGroups = u(
+            'heading',
+            {depth: uExampleRoot.depth + 1},
+            [u('text', `!!groups`)]
+        )
+        md.push(uExampleGroups)
+
+        const uGroupDescription = u(
+            'heading',
+            {depth: uExampleGroups.depth + 1},
+            [u('text', `!description ${group.description}`)]
+        )
+        md.push(uGroupDescription)
+
+        group.examples.forEach(example => {
+            const uExamples = u(
+                'heading',
+                {depth: uExampleGroups.depth + 1},
+                [u('text', `!!examples`)]
+            )
+            md.push(uExamples)
+
+            const codeBlock = u(
+                'heading',
+                {depth: uExamples.depth + 1},
+                [u('text', `!codeblock`)]
+            )
+            md.push(codeBlock)
+
+            const codeBlockTitle = u(
+                'heading',
+                {depth: codeBlock.depth + 1},
+                [u('text', `!title ${example.codeblock.title}`)]
+            )
+            md.push(codeBlockTitle)
+
+            const tabs = u(
+                'heading',
+                {depth: codeBlock.depth + 1},
+                [u('text', `!!tabs`)]
+            )
+            md.push(tabs)
+
+            example.codeblock.tabs.forEach(tab => {
+                const code = u('code', {
+                    lang: tab.language,
+                    meta: `!code ${tab.title}`
+                }, tab.code);
+
+                md.push(code)
+            })
+
+        })
+    })
+
+    return md
+}
+
+export function definitions(definitions: Definition[]) {
+    const md: any[] = []
+
+    definitions.forEach(definition => {
+        const uDefinition = u(
+            'heading',
+            {depth: START_DEPTH_LEVEL + 1},
+            [u('text', `!!definitions`)]
+        )
+        md.push(uDefinition)
+
+        md.push(u(
+            'heading',
+            {depth: uDefinition.depth + 1},
+            [u('text', `!title ${definition.title}`)]
+        ))
+
+        definition.properties.forEach(prop => {
+            properties(
+                uDefinition.depth + 1,
+                {
+                    name: prop.name,
+                    type: prop.type,
+                    description: prop.description,
+                    properties: prop.properties  // TODO: fix ts
+                },
+                md,
+            )
+        })
+    })
+
+    return md
+}
+
+// TODO: any[]
+export function properties(
+    depth: number,
+    props: DefinitionProperty,
+    output: any[] = []
+) {
+    const paramName = props.name;
+
+    const propTitle = `!!properties ${paramName}`; // TODO: check if `!!properties is enough`
+    const uPropTitle = u('heading', {depth}, [u('text', propTitle)]);
+    const uPropName = u('paragraph', {depth}, [u('text', `!name ${paramName}`)]);
+    const uPropType = u('paragraph', {depth}, [u('text', `!type ${props.type}`)]);
+    const uPropDesc = u('paragraph', {depth}, [u('text', props.description || '')]);
+
+    output.push(
+        uPropTitle,
+        uPropName,
+        uPropType,
+        uPropDesc
+    );
+
+    if (props.properties) {
+        const deepDepth = depth + 1
+
+        for (const prop of props.properties) {
+            properties(deepDepth, prop, output)
+        }
+    }
+}
+
+
+

package/src/types.ts

@@ -0,0 +1,134 @@
+// TODO: concept only
+export enum ReferenceCategory {
+    // for React
+    COMPONENTS = "components",
+    HOOKS = "hooks",
+    // end for React
+
+    // for API
+    REST = "rest",
+    GRAPHQL = "graphql",
+    // end for API
+
+    // for code
+    FUNCTIONS = "functions",
+    //
+}
+
+// TODO: concept only
+export enum ReferenceType {
+    // for React
+    COMPONENT = "component",
+    HOOK = "hook",
+    // end for React
+
+    // for API
+    REST_HTTP_GET = "rest_get",
+    REST_HTTP_POST = "rest_post",
+    REST_HTTP_PUT = "rest_put",
+    REST_HTTP_PATCH = "rest_patch",
+    REST_HTTP_DELETE = "rest_delete",
+    // ---
+    GRAPHQL_QUERY = "graphql_query",
+    GRAPHQL_MUTATION = "graphql_mutation",
+    // end for API
+
+    // for code
+    FUNCTION_JS = "function_js",
+    // end for code
+}
+
+export interface GraphQLReferenceContext {
+}
+
+// TODO: custom value?
+export interface OpenAPIReferenceContext {
+    method: string;
+
+    path: string;
+}
+
+export type ReferenceContext = GraphQLReferenceContext | OpenAPIReferenceContext;
+
+export interface ExampleRoot {
+    groups: ExampleGroup[];
+}
+
+export interface ExampleGroup {
+    description?: string;
+
+    examples: Example[];
+}
+
+export interface Example {
+    description?: string; // TODO: replace with title ?
+
+    codeblock: CodeBlock;
+}
+
+export interface CodeBlock {
+    title?: string;
+
+    tabs: CodeBlockTab[];
+}
+
+export interface GraphQLExampleContext {
+    schema?: any; // TODO:
+}
+
+export interface OpenAPIExampleContext {
+    status?: number;
+
+    content?: string;
+}
+
+export type ExampleContext = GraphQLExampleContext | OpenAPIExampleContext;
+
+export interface CodeBlockTab {
+    // title of the tab e.g "JavaScript"
+    title: string;
+
+    // code in the tab e.g "console.log('Hello World')"
+    code: string
+    
+    // language of the code e.g "js"
+    language: string;
+
+    // context of the generation method e.g openapi or graphql
+    context?: ExampleContext;
+}
+
+export interface Reference {
+    title: string;
+    description: string;
+    canonical: string;
+
+    definitions: Definition[]
+    examples: ExampleRoot
+
+    category?: ReferenceCategory; // TODO: do we need that?
+    type?: ReferenceType; // TODO: do we need that?
+    context?: ReferenceContext;
+}
+
+export interface Definition {
+    title: string;
+
+    properties: DefinitionProperty[];
+
+    type?: string;
+
+    id?: string;
+
+    description?: string;
+}
+
+export interface DefinitionProperty {
+    name: string;
+
+    type: string;
+
+    description: string;
+
+    properties?: DefinitionProperty[];
+}

package/src/utils.ts

@@ -0,0 +1,123 @@
+import path from 'path';
+import matter from 'gray-matter';
+import {Sidebar, FrontMatter, PageFrontMatter} from "@xyd-js/core";
+
+import {Reference} from "./types";
+import uniform from "./index";
+
+// interface UniformFrontMatter extends FrontMatter { // TODO: it's concept only
+//     scopes?: string
+// }
+
+type GroupMap = {
+    [key: string]: {
+        __groups: GroupMap
+        pages: Set<string>
+    }
+}
+
+export interface pluginNavigationOptions {
+    urlPrefix: string
+}
+
+export function pluginNavigation(options: pluginNavigationOptions) {
+    if (!options.urlPrefix) {
+        throw new Error("urlPrefix is required")
+    }
+
+    return function pluginNavigationInner(cb: (cb: () => {
+        pageFrontMatter: PageFrontMatter
+        sidebar: Sidebar[]
+    }) => void) {
+        const pageFrontMatter: PageFrontMatter = {}
+        const groupMaps: GroupMap = {}
+
+        cb(() => {
+            return {
+                pageFrontMatter: pageFrontMatter,
+                sidebar: convertGroupMapsToNavigations(groupMaps) as Sidebar[]
+            }
+        })
+
+        return (ref: Reference) => {
+            const content = matter(ref.description || "") // TODO: pluginMatter before?
+
+            if (content.data) {
+                const data = content.data as FrontMatter
+
+                const pagePath = path.join(options.urlPrefix, ref.canonical)
+
+                if (data.title) {
+                    pageFrontMatter[pagePath] = {
+                        title: data.title,
+                    }
+                }
+
+                if (data.group) {
+                    if (typeof content?.data?.group === "string") {
+                        // TODO: seek nested group (it's not always from 0)
+                        throw new Error("group as string is not supported yet")
+                    }
+
+                    content.data.group.reduce((groups: GroupMap, group: string, i: number) => {
+                        if (!groups[group]) {
+                            groups[group] = {
+                                __groups: {},
+                                pages: new Set()
+                            }
+                        }
+
+                        if (i === content.data.group.length - 1) {
+                            groups[group].pages.add(pagePath)
+                        }
+
+                        return groups[group].__groups
+                    }, groupMaps)
+                }
+
+                // back description to original without frontmatter
+                ref.description = content.content
+            }
+        }
+    }
+}
+
+
+function convertGroupMapsToNavigations(groupMaps: GroupMap): Sidebar[] {
+    const nav: Sidebar[] = []
+
+    Object.keys(groupMaps).map((groupName) => {
+        const current = groupMaps[groupName]
+
+        const pages: string[] | Sidebar[] = []
+
+        current.pages.forEach((page: string) => {
+            pages.push(page)
+        })
+
+        if (Object.keys(current.__groups).length) {
+            const subNav: Sidebar = {
+                group: groupName,
+                pages: convertGroupMapsToNavigations(current.__groups)
+            }
+
+            nav.push(subNav)
+        } else {
+            nav.push({
+                group: groupName,
+                pages,
+            })
+        }
+    })
+
+    return nav
+}
+
+// example usage:
+// const response = uniform([/* references */], {
+//     plugins: [pluginNavigation({
+//         urlPrefix: "/docs"
+//     })],
+// });
+
+

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "./dist",
+    "declaration": true,
+    "declarationMap": true,
+    "incremental": true,
+    "tsBuildInfoFile": "./dist/tsconfig.tsbuildinfo"
+  },
+  "include": ["examples/basic-example/**/*.ts", "src/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/tsup.config.ts

@@ -0,0 +1,39 @@
+import {defineConfig, Options} from 'tsup';
+
+const config: Options = {
+    entry: {
+        index: 'index.ts',
+        markdown: 'markdown.ts',
+        content: 'content.ts',
+    },
+    format: ['esm', 'cjs'], // Output both ESM and CJS formats
+    target: 'node16', // Ensure compatibility with Node.js 16
+    dts: {
+        entry: {
+            index: 'index.ts',
+            markdown: 'markdown.ts',
+            content: 'content.ts',
+        },
+        resolve: true, // Resolve external types
+    },
+    splitting: false, // Disable code splitting
+    sourcemap: true, // Generate source maps
+    clean: true, // Clean the output directory before each build
+    esbuildOptions: (options) => {
+        options.platform = 'node'; // Ensure the platform is set to Node.js
+        options.external = [
+            'react',
+            'fs',
+            'path',
+            'node:fs',
+            'node:fs/promises',
+
+            'codehike',
+            'unist-util-visit',
+            '@mdx-js/mdx'
+        ]; // Mark these modules as external
+        options.loader = { '.js': 'jsx' }; // Ensure proper handling of .js files
+    },
+}
+
+export default defineConfig(config);