@terrafirmagreg-team/mdx 0.0.0-stage → 1.2.1

package/src/lib/mdx/preview.ts

@@ -0,0 +1,253 @@
+import { remarkDirectives } from './directives.ts';
+import {
+  remarkCodeTab,
+  remarkHeading,
+  remarkImage,
+  remarkMdxFiles,
+  remarkMdxMermaid,
+  remarkNpm,
+  remarkSteps,
+} from 'fumadocs-core/mdx-plugins';
+import remarkDirective from 'remark-directive';
+import remarkGfm from 'remark-gfm';
+import remarkMath from 'remark-math';
+import remarkParse from 'remark-parse';
+import { unified } from 'unified';
+import {
+  contentChildren,
+  extractDirectiveLabel,
+  jsxAttr,
+  type DirectiveNode,
+  type JsxElement,
+  type MdastNode,
+} from './directive-utils.ts';
+
+type VFileLike = {
+  path?: string;
+  cwd?: string;
+  value?: unknown;
+};
+
+type Positioned = {
+  position?: {
+    start?: { offset?: number };
+    end?: { offset?: number };
+  };
+};
+
+const previewSeq = new WeakMap<object, number>();
+
+function nextPreviewId(file: VFileLike): number {
+  const key = file as object;
+  const n = (previewSeq.get(key) ?? 0) + 1;
+  previewSeq.set(key, n);
+  return n;
+}
+
+function slugify(text: string): string {
+  return (
+    text
+      .toLowerCase()
+      .replace(/[^\p{L}\p{N}]+/gu, '-')
+      .replace(/^-+|-+$/g, '') || 'section'
+  );
+}
+
+function walk(node: MdastNode, visit: (n: MdastNode) => void): void {
+  visit(node);
+  for (const child of node.children ?? []) walk(child, visit);
+}
+
+function markHeadingNoToc(heading: MdastNode): void {
+  const kids = heading.children ?? [];
+  const last = kids[kids.length - 1];
+  if (last?.type === 'text' && typeof last.value === 'string') {
+    if (!last.value.includes('[!toc]')) {
+      last.value = `${last.value.replace(/\s+$/, '')} [!toc]`;
+    }
+    return;
+  }
+  kids.push({ type: 'text', value: ' [!toc]' });
+  heading.children = kids;
+}
+
+function uniquifyHeadingIds(tree: MdastNode): void {
+  const used = new Set<string>();
+  walk(tree, (node) => {
+    if (node.type !== 'heading') return;
+    const props = (node.data?.hProperties ?? {}) as { id?: string };
+    node.data ??= {};
+    node.data.hProperties = props;
+    if (typeof props.id !== 'string' || props.id.length === 0) return;
+
+    let id = props.id;
+    if (!used.has(id)) {
+      used.add(id);
+      return;
+    }
+    let n = 1;
+    while (used.has(`${id}-${n}`)) n += 1;
+    props.id = `${id}-${n}`;
+    used.add(props.id);
+  });
+}
+
+export function remarkPreview() {
+  return async (tree: MdastNode, file: VFileLike) => {
+    previewSeq.set(file as object, 0);
+    await expandPreviews(tree, file);
+    uniquifyHeadingIds(tree);
+  };
+}
+
+async function expandPreviews(parent: MdastNode, file: VFileLike): Promise<void> {
+  const children = parent.children;
+  if (!children) return;
+
+  for (let i = 0; i < children.length; i++) {
+    const child = children[i]!;
+    if (child.type === 'containerDirective' && child.name === 'preview') {
+      const expanded = await expandPreview(child as DirectiveNode, file);
+      children.splice(i, 1, ...expanded);
+      i += expanded.length - 1;
+      continue;
+    }
+    await expandPreviews(child, file);
+  }
+}
+
+function isMdEscapeFence(node: MdastNode): boolean {
+  if (node.type !== 'code' || typeof node.value !== 'string') return false;
+  const lang = typeof node.lang === 'string' ? node.lang.toLowerCase() : '';
+  return lang === 'md' || lang === 'markdown';
+}
+
+function fileText(file: VFileLike): string {
+  if (typeof file.value === 'string') return file.value;
+  if (file.value == null) return '';
+  if (Buffer.isBuffer(file.value)) return file.value.toString('utf8');
+  return String(file.value);
+}
+
+function offsetOf(node: MdastNode, side: 'start' | 'end'): number | undefined {
+  const pos = (node as Positioned).position?.[side]?.offset;
+  return typeof pos === 'number' ? pos : undefined;
+}
+
+function sourceFromChildren(
+  kids: MdastNode[],
+  file: VFileLike,
+): string | undefined {
+  if (kids.length === 0) return undefined;
+
+  if (kids.length === 1 && isMdEscapeFence(kids[0]!)) {
+    return kids[0]!.value as string;
+  }
+
+  const raw = fileText(file);
+  const start = offsetOf(kids[0]!, 'start');
+  const end = offsetOf(kids[kids.length - 1]!, 'end');
+  if (raw && start != null && end != null && end >= start) {
+    return raw.slice(start, end).replace(/\r\n/g, '\n').trimEnd();
+  }
+
+  return undefined;
+}
+
+async function expandPreview(
+  node: DirectiveNode,
+  file: VFileLike,
+): Promise<MdastNode[]> {
+  const kids = contentChildren(node);
+  const source = sourceFromChildren(kids, file);
+  if (source === undefined) return kids;
+
+  const label = extractDirectiveLabel(node);
+  const previewNo = nextPreviewId(file);
+
+  const input: JsxElement = {
+    type: 'mdxJsxFlowElement',
+    name: 'Input',
+    attributes: label ? [jsxAttr('label', label)] : [],
+    children: [
+      {
+        type: 'code',
+        lang: 'md',
+        meta: 'title="example.md" lineNumbers',
+        value: source,
+      },
+    ],
+  };
+
+  const parsed = await processOutputBody(source, file, previewNo);
+
+  const output: JsxElement = {
+    type: 'mdxJsxFlowElement',
+    name: 'Output',
+    attributes: [],
+    children: parsed.children ?? [],
+  };
+
+  const preview: JsxElement = {
+    type: 'mdxJsxFlowElement',
+    name: 'Preview',
+    attributes: [],
+    children: [input as unknown as MdastNode, output as unknown as MdastNode],
+  };
+
+  return [preview as unknown as MdastNode];
+}
+
+async function processOutputBody(
+  source: string,
+  file: VFileLike,
+  previewNo: number,
+): Promise<MdastNode> {
+
+  const { remarkInclude } = await import('fumadocs-core/mdx-plugins');
+
+  const used = new Map<string, number>();
+
+  const processor = unified()
+    .use(remarkParse)
+    .use(remarkGfm)
+    .use(remarkMath)
+    .use(remarkDirective)
+    .use(remarkDirectives)
+    .use(remarkInclude)
+    .use(remarkImage, { publicDir: 'public', useImport: false })
+    .use(remarkNpm)
+    .use(remarkCodeTab)
+    .use(remarkMdxFiles)
+    .use(remarkMdxMermaid)
+    .use(remarkSteps)
+    .use(remarkHeading, {
+      generateToc: false,
+      customId: false,
+      slug: (_root, _heading, text: string) => {
+        const base = slugify(text);
+        const n = used.get(base) ?? 0;
+        used.set(base, n + 1);
+        const local = n === 0 ? base : `${base}-${n}`;
+        return `preview-${previewNo}-${local}`;
+      },
+    });
+
+  const tree = processor.parse({ value: source, path: file.path });
+  const subFile = Object.assign(
+    Object.create(Object.getPrototypeOf(file)) as VFileLike,
+    file,
+    { value: source },
+  );
+  const result = (await processor.run(
+    tree,
+    subFile as never,
+  )) as unknown as MdastNode;
+
+  walk(result, (node) => {
+    if (node.type === 'heading') markHeadingNoToc(node);
+  });
+
+  return result;
+}
+

package/src/lib/mdx/references.ts

@@ -0,0 +1,57 @@
+type MdastNode = {
+  type: string;
+  value?: string;
+  url?: string;
+  children?: MdastNode[];
+};
+
+const ISSUE_REF = /^#\d+$/;
+const USER_REF = /^@[a-zA-Z\d](?:[a-zA-Z\d-]{0,37}[a-zA-Z\d])?$/;
+const AUTO_REF = /(\B#\d+\b|\B@[a-zA-Z\d](?:[a-zA-Z\d-]{0,37}[a-zA-Z\d])?)/g;
+const SKIP = new Set([
+  'link',
+  'linkReference',
+  'image',
+  'imageReference',
+  'code',
+  'inlineCode',
+  'html',
+]);
+
+const CHANGELOG_PATH = /[/\\]changelog[/\\]([^/\\]+)[/\\]/;
+
+export function remarkChangelogReferences(options: { datasetConfig?: Record<string, { repo?: string }> } = {}) {
+  const datasetConfig = options.datasetConfig ?? {};
+  return (tree: MdastNode, file: { path?: string }) => {
+    const pack = CHANGELOG_PATH.exec(file.path ?? '')?.[1];
+    const repo = pack ? datasetConfig[pack]?.repo : undefined;
+    if (!repo) return;
+    const repoUrl = `https://github.com/${repo}`;
+    const visit = (node: MdastNode) => {
+      if (SKIP.has(node.type) || !node.children) return;
+      node.children = node.children.flatMap((child): MdastNode[] => {
+        if (child.type !== 'text') {
+          visit(child);
+          return [child];
+        }
+        return (child.value ?? '').split(AUTO_REF).map((part) =>
+          ISSUE_REF.test(part)
+            ? {
+                type: 'link',
+                url: `${repoUrl}/issues/${part.slice(1)}`,
+                children: [{ type: 'text', value: part }],
+              }
+            : USER_REF.test(part)
+              ? {
+                  type: 'link',
+                  url: `https://github.com/${part.slice(1)}`,
+                  children: [{ type: 'text', value: part }],
+                }
+              : { type: 'text', value: part },
+        );
+      });
+    };
+    visit(tree);
+  };
+}
+

package/src/lib/mdx/tabs.ts

@@ -0,0 +1,76 @@
+import {
+  estreeStringArray,
+  extractLeafLabel,
+  jsxExpression,
+  toJsxAttributes,
+  walkContainers,
+  type DirectiveNode,
+  type JsxElement,
+  type MdastNode,
+} from './directive-utils.ts';
+
+export function remarkTabs() {
+  return (tree: MdastNode) => {
+    walkContainers(tree, (directive) => {
+      if (directive.name !== 'tabs') return;
+      toTabs(directive);
+      return false;
+    });
+  };
+}
+
+function escapeValue(value: string): string {
+  return value.toLowerCase().replace(/\s/, '-');
+}
+
+function toTabs(node: DirectiveNode): void {
+  const items: string[] = [];
+  const tabs: JsxElement[] = [];
+  let current: JsxElement | undefined;
+
+  for (const item of node.children ?? []) {
+    if (item.type === 'leafDirective' && (item as { name?: string }).name === 'tab') {
+      const label = extractLeafLabel(item);
+      items.push(label);
+      current = {
+        type: 'mdxJsxFlowElement',
+        name: 'Tab',
+        attributes: [
+          {
+            type: 'mdxJsxAttribute',
+            name: 'value',
+            value: escapeValue(label),
+          },
+        ],
+        children: [],
+      };
+      tabs.push(current);
+      continue;
+    }
+
+    current?.children.push(item);
+  }
+
+  const attributes = toJsxAttributes(node).map((attribute) =>
+    attribute.name === 'default'
+      ? {
+          type: 'mdxJsxAttribute' as const,
+          name: 'defaultValue',
+          value: escapeValue(String(attribute.value)),
+        }
+      : attribute,
+  );
+  attributes.unshift({
+    type: 'mdxJsxAttribute',
+    name: 'items',
+    value: jsxExpression(estreeStringArray(items)),
+  });
+
+  Object.assign(node, {
+    type: 'mdxJsxFlowElement',
+    name: 'Tabs',
+    attributes,
+    children: tabs,
+  });
+}
+

package/src/lib/pack-assets.ts

@@ -0,0 +1,46 @@
+import type { DocsImageProps } from '../types/mdx';
+
+export function packPublicUrl(pack: string, ...segments: string[]): string {
+  const rel = segments
+    .map((s) => s.replace(/^\/+/, '').replaceAll('\\', '/'))
+    .filter(Boolean)
+    .join('/');
+  return rel ? `/${pack}/${rel}` : `/${pack}`;
+}
+
+export function assetUrl(
+  pack: string,
+  modId: string,
+  ...pathSegments: string[]
+): string {
+  return packPublicUrl(pack, 'assets', modId, ...pathSegments);
+}
+
+export function resolveSrc(
+  props: Pick<DocsImageProps, 'src' | 'pack' | 'mod' | 'path'>,
+  packFallback?: string,
+): string | null {
+  if (props.src) {
+    const s = props.src.trim();
+    if (
+      s.startsWith('/') ||
+      s.startsWith('http://') ||
+      s.startsWith('https://')
+    ) {
+      return s;
+    }
+    return `/${s.replace(/^\/+/, '')}`;
+  }
+
+  const pack = props.pack ?? packFallback;
+  if (!pack) return null;
+
+  if (props.mod && props.path) {
+    return assetUrl(pack, props.mod, props.path);
+  }
+  if (props.path) {
+    return packPublicUrl(pack, props.path);
+  }
+  return null;
+}
+

package/src/lib/remark-highlight.ts

@@ -0,0 +1,82 @@
+export type RemarkToken = { text: string; cls?: string };
+
+const NAME = 'text-fd-primary font-medium';
+const STR = 'text-diff-add-symbol';
+const MUTED = 'text-fd-muted-foreground';
+
+function attrTokens(s: string): RemarkToken[] {
+  const out: RemarkToken[] = [];
+  const re = /"[^"]*"|[^"]+/g;
+  for (const m of s.matchAll(re)) {
+    out.push({ text: m[0], cls: m[0].startsWith('"') ? STR : undefined });
+  }
+  return out;
+}
+
+function inlineTokens(s: string): RemarkToken[] {
+  const out: RemarkToken[] = [];
+  const re = /\[[^\]]*\]|\{[^}]*\}/g;
+  let last = 0;
+  for (const m of s.matchAll(re)) {
+    if (m.index > last) out.push({ text: s.slice(last, m.index) });
+    const seg = m[0];
+    if (seg.startsWith('[')) {
+      out.push({ text: '[', cls: MUTED });
+      out.push({ text: seg.slice(1, -1), cls: STR });
+      out.push({ text: ']', cls: MUTED });
+    } else {
+      out.push({ text: '{', cls: MUTED });
+      out.push(...attrTokens(seg.slice(1, -1)));
+      out.push({ text: '}', cls: MUTED });
+    }
+    last = m.index + seg.length;
+  }
+  if (last < s.length) out.push({ text: s.slice(last) });
+  return out;
+}
+
+function lineTokens(line: string): RemarkToken[] {
+  const fence = line.match(/^(```+)(.*)$/);
+  if (fence) {
+    const rest = fence[2];
+    const sp = rest.search(/\s/);
+    const lang = sp === -1 ? rest : rest.slice(0, sp);
+    const meta = sp === -1 ? '' : rest.slice(sp);
+    const toks: RemarkToken[] = [
+      { text: fence[1] + lang, cls: NAME },
+    ];
+    if (meta) toks.push(...attrTokens(meta));
+    return toks;
+  }
+  if (/^:{2,3}$/.test(line)) return [{ text: line, cls: NAME }];
+  const dir = line.match(/^(:{1,3})([\w-]+)?(.*)$/);
+  if (dir && (dir[2] || dir[1].length >= 2)) {
+    return [
+      { text: dir[1], cls: NAME },
+      ...(dir[2] ? [{ text: dir[2], cls: NAME }] : []),
+      ...inlineTokens(dir[3]),
+    ];
+  }
+  const math = line.match(/^(\${1,2})(.*?)(\${1,2})?$/);
+  if (math) {
+    const toks: RemarkToken[] = [{ text: math[1], cls: NAME }];
+    if (math[2]) toks.push({ text: math[2] });
+    if (math[3]) toks.push({ text: math[3], cls: NAME });
+    return toks;
+  }
+  const head = line.match(/^(#{1,6}\s)(.*)$/);
+  if (head) {
+    return [{ text: head[1], cls: NAME }, { text: head[2] }];
+  }
+  return [{ text: line }];
+}
+
+export function highlightRemark(src: string): RemarkToken[] {
+  const out: RemarkToken[] = [];
+  src.split('\n').forEach((line, i) => {
+    if (i) out.push({ text: '\n' });
+    out.push(...lineTokens(line));
+  });
+  return out;
+}
+