@xyd-js/content 0.0.0-build

package/packages/md/plugins/mdImage.ts

@@ -0,0 +1,55 @@
+import { visit } from "unist-util-visit";
+import { mdParameters } from "./utils/mdParameters";
+
+/**
+ * remark plugin to inject image meta/attributes (e.g. caption) into image nodes
+ * Supports both attributes in alt/title and trailing {caption="..."} blocks after the image.
+ */
+export function mdImage() {
+    return (tree: any) => {
+        // helper: extract MD parameters and merge into hProperties
+        function mergeProps(target: Record<string, any>, raw: string) {
+            const { props, attributes } = mdParameters(raw, { htmlMd: true });
+            // mdParameters returns props for text blocks, attributes for alt/title; unify
+            Object.assign(target, props ?? attributes);
+        }
+
+        // Option 1: support trailing attribute blocks after images
+        visit(tree, 'paragraph', (node: any) => {
+            for (let idx = 0; idx < node.children.length - 1; idx++) {
+                const curr = node.children[idx];
+                const next = node.children[idx + 1];
+
+                if (curr.type === 'image' && next.type === 'text') {
+                    const raw = next.value.trim();
+                    if (/^\{.*\}$/.test(raw)) {
+                        curr.data = curr.data || {};
+                        curr.data.hProperties = curr.data.hProperties || {};
+                        mergeProps(curr.data.hProperties, raw);
+                        // remove the attribute block text node
+                        node.children.splice(idx + 1, 1);
+                    }
+                }
+            }
+        });
+
+        // Option 2: process inline attributes in alt and title
+        visit(tree, 'image', (node: any) => {
+            const hProps = (node.data = node.data || {}).hProperties = node.data.hProperties || {};
+
+            // alt: look for { ... } suffix
+            if (typeof node.alt === 'string') {
+                const altMatch = node.alt.match(/^(.*?)\s*(\{.*\})$/);
+                if (altMatch) {
+                    node.alt = altMatch[1].trim();
+                    mergeProps(hProps, altMatch[2]);
+                }
+            }
+
+            // title: process any attributes
+            if (node.title) {
+                mergeProps(hProps, node.title);
+            }
+        });
+    };
+}

package/packages/md/plugins/mdImageRehype.ts

@@ -0,0 +1,13 @@
+import { visit } from "unist-util-visit";
+
+export function mdImageRehype() {
+    return (tree: any) => {
+        visit(tree, 'element', (node) => {
+            if (node.tagName === 'img' && node.properties) {
+                // If caption or other custom props are present, keep them
+                // (hProperties from remark should already be on properties)
+                // No-op, but could add logic here if needed in future
+            }
+        });
+    };
+} 

package/packages/md/plugins/mdPage.ts

@@ -0,0 +1,35 @@
+import {Plugin} from 'unified';
+import {Node as UnistNode} from 'unist';
+import {visit} from 'unist-util-visit';
+
+declare global {
+    var page: boolean | null | undefined
+}
+
+// TODO: to delete
+/**
+ * This plugin extracts the `page` variable from the markdown file.
+ * This variable(`page`) is used to determine if theme should be dropped out.
+ *
+ * It means that if page=true, theme is not used, and we can use the markdown file as a standalone page.
+ */
+export const extractPage: Plugin = () => {
+    return (tree: UnistNode) => {
+        console.time('plugin:extractPage');
+        visit(tree, 'exportNamedDeclaration', (node: any) => {
+            const declaration = node.declaration;
+
+            if (!declaration || !declaration.declarations || !declaration.declarations.length) {
+                return;
+            }
+
+            // seek declarations like export const page = true in md files
+            declaration.declarations.forEach((decl: any) => {
+                if (decl.id.name === 'page') {
+                    global.page = decl.init as boolean;
+                }
+            });
+        });
+        console.timeEnd('plugin:extractPage');
+    };
+};

package/packages/md/plugins/mdThemeSettings.ts

@@ -0,0 +1,34 @@
+import {Plugin} from 'unified';
+import {Node as UnistNode} from 'unist';
+import {visit} from 'unist-util-visit';
+
+interface ThemeSettings {
+    bigArticle: boolean;
+}
+
+declare global {
+    var themeSettings: ThemeSettings | undefined;
+}
+
+// TODO: to delete
+/**
+ * This plugin adds the `themeSettings` variable to the global scope.
+ * This variable is used to determine the theme settings for the current page.
+ */
+export const extractThemeSettings: Plugin = () => {
+    return (tree: UnistNode) => {
+        visit(tree, 'exportNamedDeclaration', (node: any) => {
+            console.time('plugin:extractThemeSettings');
+
+            const declaration = node.declaration;
+            if (declaration && declaration.declarations) {
+                declaration.declarations.forEach((decl: any) => {
+                    if (decl.id.name === 'themeSettings') {
+                        global.themeSettings = decl.init as ThemeSettings;
+                    }
+                });
+            }
+            console.timeEnd('plugin:extractThemeSettings');
+        });
+    };
+};

package/packages/md/plugins/mdToc.ts

@@ -0,0 +1,229 @@
+import { Root, Heading } from "mdast";
+import { MdxjsEsm } from "mdast-util-mdx";
+import { Plugin } from "unified";
+import { MdxJsxFlowElement, MdxJsxAttribute } from "mdast-util-mdx-jsx";
+
+import { mdParameters } from './utils/mdParameters';
+
+export type TocEntry = {
+    depth: number,
+    id: string,
+    value: string,
+    attributes: { [key: string]: string },
+    children: TocEntry[],
+    maxTocDepth?: number
+};
+
+export type CustomTag = {
+    name: RegExp,
+    depth: (name: string) => number
+};
+
+export interface RemarkMdxTocOptions {
+    name?: string,
+    customTags?: CustomTag[],
+    maxDepth?: number,
+    minDepth?: number
+}
+
+// TODO: fix any
+export function remarkMdxToc(options: RemarkMdxTocOptions): Plugin {
+    return function remarkMdxToc() {
+        return async function remarkMdxToc(ast: any) {
+            if (!options?.minDepth) {
+                options.minDepth = 2
+            }
+
+            console.time('plugin:remarkMdxToc');
+            const { visit } = await import("unist-util-visit");
+            const { toString } = await import("mdast-util-to-string");
+            const { valueToEstree } = await import('estree-util-value-to-estree')
+            const { name: isIdentifierName } = await import('estree-util-is-identifier-name');
+
+            const mdast = ast as Root;
+            const name = options.name ?? "toc"
+            if (!isIdentifierName(name)) {
+                throw new Error(`Invalid name for an identifier: ${name}`);
+            }
+
+            const toc: TocEntry[] = [];
+            const flatToc: TocEntry[] = [];
+            const nodesToRemove: number[] = [];
+
+            const createEntry = (node: Heading | MdxJsxFlowElement, depth: number, index: number): TocEntry | null => {
+                let attributes = (node.data || {}) as TocEntry['attributes'];
+                if (node.type === "mdxJsxFlowElement") {
+                    attributes = Object.fromEntries(
+                        node.attributes
+                            .filter(attribute => attribute.type === 'mdxJsxAttribute' && typeof attribute.value === 'string')
+                            .map(attribute => [(attribute as MdxJsxAttribute).name, attribute.value])
+                    ) as TocEntry['attributes'];
+                }
+
+                let value = toString(node, { includeImageAlt: false });
+                const { attributes: parsedAttributes, sanitizedText } = mdParameters(value);
+
+                // Merge parsed attributes with existing ones
+                attributes = { ...attributes, ...parsedAttributes };
+
+                // Handle toc attribute
+                if (attributes.toc === 'false') {
+                    return null; // Skip this entry
+                }
+
+                // If toc attribute is present, update the node's content to remove the [toc] part
+                if (attributes.toc === 'true' && node.type === "heading") {
+                    // Keep the heading but remove the [toc] text and hide it
+                    (node as any).data = {
+                        ...(node as any).data,
+                        hProperties: {
+                            ...(node as any).data?.hProperties,
+                            hideHeading: "true",
+                            removeHeading: attributes.content === "false" ? "true" : ""
+                        }
+                    };
+                    node.children = node.children.map(child => {
+                        if (child.type === "text") {
+                            return {
+                                ...child,
+                                value: ""
+                            };
+                        }
+                        return child;
+                    });
+                }
+
+                // Use toc value if provided, otherwise use clean text
+                const tocValue = attributes.toc === 'true' ? sanitizedText : (attributes.toc || sanitizedText);
+
+                return {
+                    depth,
+                    id: (node.data as any)?.hProperties?.id,
+                    value: tocValue,
+                    attributes,
+                    children: [],
+                    maxTocDepth: attributes.maxTocDepth ? parseInt(attributes.maxTocDepth) : undefined
+                };
+            };
+
+            visit(mdast, ["heading", "mdxJsxFlowElement"], (node, index) => {
+                // @ts-ignore
+                let depth = 0;
+                if (node.type === "mdxJsxFlowElement") {
+                    let valid = false;
+                    if (/^h[1-6]$/.test(node.name || "")) {
+                        valid = true;
+                        depth = parseInt(node.name!.substring(1));
+                    } else if (options.customTags) {
+                        for (const tag of options.customTags) {
+                            if (tag.name.test(node.name || "")) {
+                                valid = true;
+                                depth = tag.depth(node.name || "");
+                                break;
+                            }
+                        }
+                    }
+
+                    if (!valid) {
+                        return;
+                    }
+                } else if (node.type === "heading") {
+                    depth = node.depth;
+                } else {
+                    return;
+                }
+
+                const entry = createEntry(node, depth, index as number);
+                if (!entry) return;
+
+                // If toc attribute is explicitly set to true or +toc is present, include it regardless of depth
+                if (entry.attributes.toc === 'true' || entry.attributes["+toc"] === 'true') {
+                    flatToc.push(entry);
+                    let parent: TocEntry[] = toc;
+                    for (let i = flatToc.length - 1; i >= 0; --i) {
+                        const current = flatToc[i];
+                        if (current.depth < entry.depth) {
+                            parent = current.children;
+                            break;
+                        }
+                    }
+                    parent.push(entry);
+                    return;
+                }
+
+                // First check if this entry should be included based on parent's maxTocDepth
+                let parentMaxDepth = options.maxDepth;
+                for (let i = flatToc.length - 1; i >= 0; --i) {
+                    const parent = flatToc[i];
+                    if (parent.depth < entry.depth) {
+                        if (parent.maxTocDepth !== undefined) {
+                            parentMaxDepth = parent.maxTocDepth;
+                        }
+                        break;
+                    }
+                }
+
+                // Now check against the effective max depth (either global or parent's maxTocDepth)
+                if (depth && parentMaxDepth && depth > parentMaxDepth) {
+                    return;
+                }
+
+                if (depth && (options?.minDepth && depth < options.minDepth)) {
+                    return;
+                }
+
+                flatToc.push(entry);
+
+                let parent: TocEntry[] = toc;
+                for (let i = flatToc.length - 1; i >= 0; --i) {
+                    const current = flatToc[i];
+                    if (current.depth < entry.depth) {
+                        parent = current.children;
+                        break;
+                    }
+                }
+                parent.push(entry);
+            });
+
+            // Remove nodes marked for removal
+            nodesToRemove.sort((a, b) => b - a).forEach(index => {
+                mdast.children.splice(index, 1);
+            });
+
+            const tocExport: MdxjsEsm = {
+                type: "mdxjsEsm",
+                value: "",
+                data: {
+                    estree: {
+                        type: "Program",
+                        sourceType: "module",
+                        body: [
+                            {
+                                type: "ExportNamedDeclaration",
+                                specifiers: [],
+                                attributes: [],
+                                source: null,
+                                declaration: {
+                                    type: "VariableDeclaration",
+                                    kind: "const",
+                                    declarations: [
+                                        {
+                                            type: "VariableDeclarator",
+                                            id: {
+                                                type: "Identifier",
+                                                name
+                                            },
+                                            init: valueToEstree(toc)
+                                        }
+                                    ],
+                                }
+                            }
+                        ]
+                    }
+                }
+            };
+            mdast.children.unshift(tocExport);
+            console.timeEnd('plugin:remarkMdxToc');
+        };
+    };
+}

package/packages/md/plugins/meta/index.ts

@@ -0,0 +1 @@
+export { mdMeta } from "./mdMeta";

package/packages/md/plugins/meta/mdMeta.ts

@@ -0,0 +1,198 @@
+import { Root } from 'mdast';
+import { matter } from 'vfile-matter';
+
+
+import { Metadata, Settings, Theme } from '@xyd-js/core';
+import { getMetaComponent } from '@xyd-js/context';
+import { Reference, TypeDocReferenceContext } from '@xyd-js/uniform';
+import { uniformToMiniUniform } from '@xyd-js/sources/ts';
+
+import { FunctionName } from '../functions/types';
+import { parseFunctionCall, parseImportPath } from '../functions/utils';
+import { processUniformFunctionCall } from '../functions/uniformProcessor';
+import { componentLike } from '../utils';
+import { SymbolxVfile } from '../types';
+
+export interface MdMetaOptions {
+  resolveFrom?: string
+}
+
+// TODO: IT SHOULD BE PART OF COMPOSER
+
+export function mdMeta(settings?: Settings, options?: MdMetaOptions) {
+  return function() {
+    return async (tree: Root, file: SymbolxVfile<any>) => {
+      console.time('plugin:mdMeta:total');
+      console.time('plugin:mdMeta:frontmatter');
+      // Parse frontmatter and expose it at file.data.matter
+      matter(file as any);
+      console.timeEnd('plugin:mdMeta:frontmatter');
+
+      if (!file.data.matter) {
+        console.timeEnd('plugin:mdMeta:total');
+        return
+      }
+
+      console.time('plugin:mdMeta:metaProcessing');
+      const meta = file.data.matter as Metadata<Record<string, any>>
+      if (!meta) {
+        console.timeEnd('plugin:mdMeta:metaProcessing');
+        console.timeEnd('plugin:mdMeta:total');
+        return
+      }
+
+      let uniformMeta = false
+      if (meta?.uniform || meta?.openapi || meta?.graphql) {
+        uniformMeta = true
+        if (meta.graphql) {
+          meta.uniform = meta.graphql
+        } else if (meta.openapi) {
+          meta.uniform = meta.openapi
+        }
+        meta.component = "atlas"
+
+        if (typeof meta.uniform === "string") {
+          meta.componentProps = {
+            references: `@uniform('${meta.uniform}')`
+          }
+        } else if (typeof meta.uniform === "object") {
+          const uniformArgs = {}
+          
+          if (meta.uniform.eager) {
+            // TODO: support eager line ranges?
+            const { filePath, regions } = parseImportPath(meta.uniform.path)
+
+            if (regions.length > 1) {
+              console.warn("Eager uniform with multiple regions is not supported")
+            }
+            
+            if (regions.length) {
+              uniformArgs["eager"] = regions[0].name
+            }
+            
+            meta.uniform.path = filePath
+          }
+
+          meta.componentProps = {
+            references: `@uniform('${meta.uniform.path}', ${JSON.stringify(uniformArgs)})`
+          }
+        }
+      }
+
+      if (!meta || !meta.component) {
+        console.timeEnd('plugin:mdMeta:metaProcessing');
+        console.timeEnd('plugin:mdMeta:total');
+        return
+      }
+
+      const metaComponent = getMetaComponent(meta.component)
+
+      if (!metaComponent) {
+        console.timeEnd('plugin:mdMeta:metaProcessing');
+        console.timeEnd('plugin:mdMeta:total');
+        return
+      }
+      console.timeEnd('plugin:mdMeta:metaProcessing');
+
+      console.time('plugin:mdMeta:propsProcessing');
+      const promises: Promise<void>[] = []
+
+      let resolvedProps: Record<string, any> = {}
+
+      if (uniformMeta && meta.componentProps && typeof meta.componentProps === "object") {
+        // TODO: ??? TO DELETE ???
+        for (const key in meta.componentProps) { // TODO: support nested props
+          const value = meta.componentProps[key]
+
+          const result = parseFunctionCall({
+            children: [
+              {
+                type: "text",
+                value: value
+              }
+            ]
+          }, FunctionName.Uniform);
+
+          if (!result) {
+            resolvedProps[key] = value
+            continue
+          }
+
+          const importPath = result[0]
+          const importArgs = result[1];
+
+          if (!importPath) {
+            continue
+          }
+
+          const promise = (async () => {
+            let references = await processUniformFunctionCall(
+              importPath,
+              file,
+              options?.resolveFrom,
+              settings,
+            );
+
+
+            if (importArgs?.eager && references) { // TODO: move to `processUniformFunctionCall`
+              // TODO: rename uniformToMiniUniform eager
+              // TODO: support multile regions
+              references = uniformToMiniUniform(importArgs.eager, references as Reference<TypeDocReferenceContext>[]);
+            }
+
+            resolvedProps[key] = references
+          })()
+
+          promises.push(promise)
+        }
+      } else {
+        resolvedProps = meta.componentProps || {}
+      }
+
+      await Promise.all(promises)
+      console.timeEnd('plugin:mdMeta:propsProcessing');
+
+      console.time('plugin:mdMeta:transform');
+      const resolvedComponentProps = await metaComponent.transform(
+        (settings?.theme || {}) as Theme,
+        resolvedProps,
+        file.data.outputVars,
+        Object.freeze(tree.children) as any,
+        meta,
+        // @ts-ignore
+        settings
+      )
+      console.timeEnd('plugin:mdMeta:transform');
+
+      console.time('plugin:mdMeta:componentCreation');
+      const exportNode = componentLike(
+        metaComponent.componentName,
+        resolvedComponentProps,
+        []
+      )
+
+      tree.children = [
+        ...treeSanitize(tree),
+        ...exportNode.children
+      ]
+      console.timeEnd('plugin:mdMeta:componentCreation');
+      console.timeEnd('plugin:mdMeta:total');
+    }
+  }
+}
+
+// TODO: add more / BETTER SOLUTION FOR CLEARIN
+const allowedNodes = [
+  "mdxjsEsm",
+  // "outputVars", // TODO: !!! cuz some issues with outputvars + containerDirective !!!
+]
+
+function treeSanitize(tree: Root) {
+  return tree.children.filter((child) => {
+    if (allowedNodes.includes(child.type)) {
+      return true
+    }
+
+    return false
+  })
+}

package/packages/md/plugins/output-variables/__fixtures__/1.simple/input.md

@@ -0,0 +1,22 @@
+# Heading 1
+
+
+<<<example
+  ```bash npm
+  npm i -g xyd-js
+  ```
+
+  ```bash yarn
+  yarn global add xyd-js
+  ```
+
+  ```bash pnpm
+  pnpm add -g xyd-js
+  ```
+<<<
+
+## Heading 2
+
+Lorem ipsum
+
+