@xyd-js/uniform 0.1.0-build.172

package/src/plugins/__tests__/pluginJsonView.test.ts

@@ -0,0 +1,132 @@
+import { describe, it, expect } from 'vitest';
+import fs from 'fs';
+import { pluginJsonView } from '../pluginJsonView';
+import type { Reference } from '../../types';
+import uniform from '../../index'
+
+describe('pluginJsonView', () => {
+    it('should handle properties without examples', () => {
+        const plugin = pluginJsonView();
+
+        const inputs: Reference[] = [
+            {
+                title: 'Test title',
+                description: 'Test description',
+                canonical: 'test-canonical',
+                examples: {
+                    groups: []
+                },
+                "definitions": [
+                    {
+                        "title": "Properties",
+                        "properties": [
+                            {
+                                "name": "charset",
+                                "type": "string",
+                                "description": "Character encoding for the document\n",
+                                "examples": [
+                                    "\"UTF-8\""
+                                ]
+                            },
+                            {
+                                "name": "robots",
+                                "type": "string",
+                                "description": "Standard meta tag for controlling search engine crawling and indexing\n",
+                                "examples": [
+                                    "\"index, follow\"",
+                                    "\"noindex, nofollow\""
+                                ]
+                            }
+                        ]
+                    }
+                ]
+            },
+            {
+                title: 'Test title',
+                description: 'Test description',
+                canonical: 'test-canonical',
+                examples: {
+                    groups: []
+                },
+                "definitions": [
+                    {
+                        "title": "Properties",
+                        "properties": [
+                            {
+                                "name": "charset",
+                                "type": "string",
+                                "description": "Character encoding for the document\n",
+                                "examples": [
+                                    "UTF-8"
+                                ]
+                            },
+                            {
+                                "name": "robots",
+                                "type": "string",
+                                "description": "Standard meta tag for controlling search engine crawling and indexing\n",
+                                "examples": [
+                                    "index, follow",
+                                    "noindex, nofollow"
+                                ]
+                            }
+                        ]
+                    }
+                ]
+            },
+            {
+                title: 'Test title',
+                description: 'Test description',
+                canonical: 'test-canonical',
+                examples: {
+                    groups: []
+                },
+                "definitions": [
+                    {
+                        "title": "Properties",
+                        "properties": [
+                            {
+                                "name": "robots",
+                                "type": "string",
+                                "description": "Standard meta tag for controlling search engine crawling and indexing\n",
+                                "examples": [
+                                    "index, follow",
+                                    "noindex, nofollow"
+                                ]
+                            },
+                            {
+                                "name": "charset",
+                                "type": "string",
+                                "description": "Character encoding for the document\n",
+                                "examples": [
+                                    "UTF-8"
+                                ]
+                            },
+                        ]
+                    }
+                ]
+            }
+        ];
+
+        const outputs: string[] = [
+            '{\n' +
+            '    "charset": "UTF-8",\n' +
+            '    "robots": "index, follow" // or "noindex, nofollow"\n' +
+            '}',
+
+            '{\n' +
+            '    "charset": "UTF-8",\n' +
+            '    "robots": "index, follow" // or "noindex, nofollow"\n' +
+            '}',
+
+            '{\n' +
+            '    "robots": "index, follow", // or "noindex, nofollow"\n' +
+            '    "charset": "UTF-8"\n' +
+            '}',
+        ]
+        const result = uniform(inputs, {
+            plugins: [plugin]
+        });
+
+        expect(result.out.jsonViews).toStrictEqual(outputs);
+    });
+}); 

package/src/plugins/index.ts

@@ -0,0 +1,2 @@
+export { pluginJsonView } from "./pluginJsonView"
+export { pluginNavigation } from "./pluginNavigation"

package/src/plugins/pluginJsonView.ts

@@ -0,0 +1,54 @@
+import type { UniformPluginArgs, UniformPlugin } from "../index";
+import { Reference } from "../types";
+
+export interface pluginJsonViewOptions {
+}
+
+type pluginJsonViewOutput = {
+    jsonViews: string;
+}
+
+export function pluginJsonView(
+    options?: pluginJsonViewOptions
+): UniformPlugin<pluginJsonViewOutput> {
+
+    return function pluginJsonViewInner({
+        defer,
+    }: UniformPluginArgs) {
+        const jsonViews: string[] = [];
+
+        defer(() => ({
+            jsonViews
+        }))
+
+        return (ref: Reference) => {
+            // Build the output string manually to ensure exact format
+            const lines: string[] = [];
+            lines.push('{');
+            
+            ref.definitions.forEach(def => {
+                def.properties.forEach((prop, index) => {
+                    // Remove any quotes and trailing characters from the value
+                    const value = (prop.examples?.[0] || '').replace(/^"|"$|[^a-zA-Z0-9\s\-_.,:/@#=;+()]/g, '');
+                    const comment = prop.examples && prop.examples.length > 1 
+                        ? ` // or "${(prop.examples as string[])[1].replace(/^"|"$|[^a-zA-Z0-9\s\-_.,:/@#=;+()]/g, '')}"`
+                        : '';
+                    const isLast = index === def.properties.length - 1;
+                    // Add comma after the value but before the comment
+                    lines.push(`    "${prop.name}": "${value}"${isLast ? '' : ','}${comment}`);
+                });
+            });
+            
+            lines.push('}');
+            
+            jsonViews.push(lines.join('\n'));
+        }
+    }
+}
+
+// example usage:
+// const response = uniform([/* references */], {
+//     plugins: [pluginJsonView({
+//         
+//     })],
+// });

package/src/plugins/pluginNavigation.ts

@@ -0,0 +1,135 @@
+import path from 'node:path';
+
+import type { Sidebar, Metadata, MetadataMap, Settings, PageURL } from "@xyd-js/core";
+
+import type { UniformPluginArgs, UniformPlugin } from "../index";
+import { CodeBlockTab, Example, ExampleGroup, Reference } from "../types";
+
+const DEFAULT_VIRTUAL_FOLDER = ".xyd/.cache/.content" // TODO: share this + .xyd/.build/.content for build
+
+const DEFAULT_GROUP_NAME = "API Reference" // TODO: configurable
+
+type GroupMap = {
+    [key: string]: {
+        __groups: GroupMap
+        pages: Set<string>
+    }
+}
+
+export interface pluginNavigationOptions {
+    urlPrefix: string
+    defaultGroup?: string
+}
+
+type pluginNavigationOutput = {
+    pageFrontMatter: MetadataMap;
+    sidebar: Sidebar[];
+}
+
+export function pluginNavigation(
+    settings: Settings,
+    options: pluginNavigationOptions
+): UniformPlugin<pluginNavigationOutput> {
+    if (!options.urlPrefix) {
+        throw new Error("urlPrefix is required")
+    }
+
+    return function pluginNavigationInner({
+        defer,
+    }: UniformPluginArgs) {
+        const pageFrontMatter: MetadataMap = {}
+        const groupMaps: GroupMap = {}
+
+        defer(() => ({
+            pageFrontMatter,
+            sidebar: convertGroupMapsToSidebar(settings, groupMaps) as Sidebar[]
+        }))
+
+        return (ref: Reference) => {
+            const dataCtx = ref.context
+            const pagePath = path.join(options.urlPrefix, ref.canonical)
+
+            let group = dataCtx?.group || []
+            let title = ref.title
+
+            if (pageFrontMatter[pagePath]) {
+                console.error("(pluginNavigation): pageFrontMatter[pagePath] already exists", pagePath)
+            }
+
+            if (!group) {
+                group = [options.defaultGroup || DEFAULT_GROUP_NAME]
+            }
+
+            pageFrontMatter[pagePath] = {
+                title,
+            }
+
+            if (typeof group === "string") {
+                // TODO: seek nested group (it's not always from 0)
+                throw new Error("group as string is not supported yet")
+            }
+
+            group.reduce((groups: GroupMap, groupName: string, i: number) => {
+                if (!groups[groupName]) {
+                    groups[groupName] = {
+                        __groups: {},
+                        pages: new Set()
+                    }
+                }
+
+                if (i === group.length - 1) {
+                    groups[groupName].pages.add(pagePath)
+                }
+
+                return groups[groupName].__groups
+            }, groupMaps)
+        }
+    }
+}
+
+function convertGroupMapsToSidebar(settings: Settings, groupMaps: GroupMap): Sidebar[] {
+    const nav: Sidebar[] = []
+
+    Object.keys(groupMaps).map((groupName) => {
+        const current = groupMaps[groupName]
+
+        const pages: PageURL[] = []
+
+        current.pages.forEach((page: string) => {
+            if (settings?.engine?.uniform?.store) {
+                pages.push(page)
+                return
+            }
+            pages.push({
+                virtual: path.join(DEFAULT_VIRTUAL_FOLDER, page),
+                page: page,
+            })
+        })
+
+        if (Object.keys(current.__groups).length) {
+            const subNav: Sidebar = {
+                group: groupName,
+                pages: convertGroupMapsToSidebar(settings, current.__groups)
+            }
+
+            nav.push(subNav)
+
+            return
+        }
+
+        nav.push({
+            group: groupName,
+            pages,
+        })
+    })
+
+    return nav
+}
+
+// TODO: in the future xyd settings must be removed cuz uniform will be part of opendocs
+// example usage:
+// const response = uniform([/* references */], {
+//     plugins: [pluginNavigation({}, {
+//         urlPrefix: "/docs"
+//     })],
+// });

package/src/types.ts

@@ -0,0 +1,294 @@
+import React from "react";
+import {HighlightedCode} from "codehike/code";
+
+// TODO: type, and category also as generic?
+export interface Reference<
+    C = ReferenceContext,
+    M extends DefinitionMeta = DefinitionMeta,
+    VM extends DefinitionVariantMeta = DefinitionVariantMeta
+> {
+    title: string;
+    description: string | React.ReactNode;
+    canonical: string;
+
+    definitions: Definition<M, VM>[] // TODO: in the future from generic?
+    examples: ExampleRoot
+
+
+    category?: ReferenceCategory; // TODO: do we need that?
+
+    type?: ReferenceType; // TODO: do we need that?
+
+    context?: C;
+
+    /**
+     * TODO: !!!! BETTER !!!!
+     * @internal
+     */
+    __UNSAFE_selector?: (selector: string) => any;
+}
+
+export type DefinitionOpenAPIMeta = Meta<"contentType" | "required" | "definitionDescription">;
+export type DefinitionTypeDocMeta = Meta<"type">;
+export type DefinitionGraphqlMeta = Meta<"type" | "graphqlName">;
+
+export type DefinitionMeta = DefinitionOpenAPIMeta | DefinitionTypeDocMeta | DefinitionGraphqlMeta
+
+export type SymbolDef = {
+    id?: string | string[];
+
+    canonical?: string | string[];
+}
+
+export interface Definition<
+    M extends DefinitionMeta = DefinitionMeta,
+    VM extends DefinitionVariantMeta = DefinitionVariantMeta
+> {
+    title: string;
+
+    properties: DefinitionProperty[];
+
+    rootProperty?: DefinitionProperty
+
+    variants?: DefinitionVariant<VM>[];
+
+    description?: string | React.ReactNode;
+
+    meta?: M[];
+
+    /**
+     * @internal
+     */
+    symbolDef?: SymbolDef;
+
+    /**
+     * @internal
+     */
+    id?: string;
+
+    /**
+     * @internal
+     */
+    type?: string;
+}
+
+export type DefinitionVariantOpenAPIMeta = Meta<"status" | "contentType" | "definitionDescription" | "required">;
+export type CommonDefinitionVariantMeta = Meta<"symbolName">;
+
+export type DefinitionVariantMeta = CommonDefinitionVariantMeta | DefinitionVariantOpenAPIMeta
+
+export interface DefinitionVariant<
+    M extends DefinitionVariantMeta = DefinitionVariantMeta
+> {
+    title: string;
+
+    properties: DefinitionProperty[];
+
+    rootProperty?: DefinitionProperty
+
+    description?: string | React.ReactNode;
+
+    symbolDef?: SymbolDef;
+
+    meta?: M[];
+}
+
+export interface Meta<T = string> {
+    name: T;
+
+    value?: unknown; // TODO: better type?
+}
+
+export type DefinitionPropertyMeta = Meta<"required" | "deprecated" | "internal" | "defaults" | "nullable" | "example" | "examples" | "minimum" | "maximum" | "enum-type"> // TODO: better solution than enum-type?
+
+export enum DEFINED_DEFINITION_PROPERTY_TYPE {
+    UNION = "$$union",
+
+    XOR = "$$xor",
+
+    ARRAY = "$$array",
+
+    ENUM = "$$enum",
+
+    // TYPE = "$$type", TODO: good idea?
+}
+
+export interface DefinitionProperty {
+    name: string;
+
+    type: string | DEFINED_DEFINITION_PROPERTY_TYPE
+
+    description: string | React.ReactNode;
+
+    // TODO: in the future more advanced examples?
+    examples?: string | string[];
+
+    symbolDef?: SymbolDef;
+
+    meta?: DefinitionPropertyMeta[];
+
+    context?: any // TODO: better type
+
+    properties?: DefinitionProperty[];
+
+    ofProperty?: DefinitionProperty;
+}
+
+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 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;
+
+    // TODO: highlighted code
+    highlighted?: HighlightedCode;
+}
+
+export type ExampleContext = GraphQLExampleContext | OpenAPIExampleContext;
+
+// 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
+    // TODO: better type system for specific api typesl like gql or rest
+    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",
+    REST_HTTP_OPTIONS = "rest_options",
+    REST_HTTP_HEAD = "rest_head",
+    REST_HTTP_TRACE = "rest_trace",
+
+    REST_COMPONENT_SCHEMA = "rest_component_schema",
+    // ---
+    GRAPHQL_QUERY = "graphql_query",
+    GRAPHQL_MUTATION = "graphql_mutation",
+    GRAPHQL_SUBSCRIPTION = "graphql_subscription",
+
+    GRAPHQL_SCALAR = "graphql_scalar",
+    GRAPHQL_OBJECT = "graphql_object",
+    GRAPHQL_INTERFACE = "graphql_interface",
+    GRAPHQL_UNION = "graphql_union",
+    GRAPHQL_ENUM = "graphql_enum",
+    GRAPHQL_INPUT = "graphql_input",
+    // end for API
+
+    // for code
+    FUNCTION_JS = "function_js",
+    // end for code
+}
+
+export interface BaseReferenceContext {
+    group?: string[];
+
+    scopes?: string[];
+}
+
+export interface GraphQLReferenceContext extends BaseReferenceContext {
+    /**
+     * @internal
+     */
+    graphqlTypeShort: string;
+
+    graphqlName: string;
+}
+
+// TODO: custom value?
+export interface OpenAPIReferenceContext extends BaseReferenceContext {
+    method?: string;
+
+    path?: string;
+
+    fullPath?: string;
+
+    componentSchema?: string
+}
+
+export type TypeDocReferenceContextMeta = Meta<"internal">
+
+// Add TypeDocReferenceContext to the union type
+export interface TypeDocReferenceContext extends BaseReferenceContext {
+    symbolId: string;
+    symbolName: string;
+    symbolKind: number;
+    packageName: string;
+    fileName: string;
+    fileFullPath: string;
+    line: number;
+    col: number;
+    signatureText: {
+        code: string;
+        lang: string;
+    };
+    sourcecode: {
+        code: string;
+        lang: string;
+    };
+    category?: string;
+    meta?: TypeDocReferenceContextMeta[]
+}
+
+export type ReferenceContext = GraphQLReferenceContext | OpenAPIReferenceContext | TypeDocReferenceContext
+
+export interface GraphQLExampleContext {
+    schema?: any; // TODO:
+}
+
+export interface OpenAPIExampleContext {
+    status?: number;
+
+    content?: string;
+}
+
+

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "paths": {
+      "@xyd-js/core": ["../xyd-core/index.ts"],
+    },
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "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);

package/vitest.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['src/**/*.test.ts' ,'packages/ts/**/*.test.ts'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      include: ['src/**/*.ts', 'packages/ts/**/*.ts'],
+      exclude: ['src/**/*.test.ts', 'src/**/*.d.ts', 'packages/ts/**/*.test.ts', 'packages/ts/**/*.d.ts']
+    }
+  }
+});