@terrafirmagreg-team/kit 0.0.0-stage → 0.1.0

package/src/lib/mdx/html-style.ts

@@ -0,0 +1,135 @@
+import type { MdastNode } from './directive-utils.ts';
+
+type NodeWithValue = MdastNode & { value: string };
+type NodeWithChildren = MdastNode & { children: MdastNode[] };
+
+function objectToCss(body: string): string | undefined {
+  const entries: string[] = [];
+  const re = /(\w+)\s*:\s*['"]([^'"]*)['"]/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(body)) !== null) entries.push(`${m[1]}: ${m[2]}`);
+  return entries.length ? entries.join('; ') : undefined;
+}
+
+const JSX_ATTR = /(\w[\w-]*)=\{\{([\s\S]*?)\}\}/g;
+
+function rewriteAttrs(html: string): string {
+  return html.replace(JSX_ATTR, (all, attr: string, body: string) => {
+    if (attr !== 'style') return all;
+    const css = objectToCss(body);
+    return css ? `style="${css}"` : all;
+  });
+}
+
+const OPEN_TAG = /<([a-zA-Z][\w-]*)((?:[^>"']|"[^"]*"|'[^']*'|\{\{[\s\S]*?\}\})*?)>/;
+
+function stylesFromTag(tag: string): string | undefined {
+  const m = /style=\{\{([\s\S]*?)\}\}/.exec(tag);
+  return m ? objectToCss(m[1]!) : undefined;
+}
+
+function elementNode(
+  tag: string,
+  hName: string,
+  children: MdastNode[],
+): MdastNode {
+  const style = stylesFromTag(tag);
+  return {
+    type: 'emphasis',
+    children,
+    data: {
+      hName,
+      ...(style ? { hProperties: { style } } : {}),
+    },
+  } as MdastNode;
+}
+
+function textNode(value: string): MdastNode {
+  return { type: 'text', value } as MdastNode;
+}
+
+export function remarkHtmlStyle() {
+  return (tree: MdastNode) => {
+    const visitChildren = (parent: NodeWithChildren) => {
+      const kids = parent.children;
+      for (let i = 0; i < kids.length; i++) {
+        const child = kids[i]!;
+        if (child.type === 'html' && typeof child.value === 'string') {
+          (child as NodeWithValue).value = rewriteAttrs(child.value);
+        } else if (
+          child.type === 'text' &&
+          typeof child.value === 'string' &&
+          child.value.includes('={{')
+        ) {
+          if (fuseJsxStyleTags(kids, i)) i--;
+        } else if (child.children) {
+          visitChildren(child as NodeWithChildren);
+        }
+      }
+    };
+    visitChildren(tree as NodeWithChildren);
+  };
+}
+
+function fuseJsxStyleTags(kids: MdastNode[], i: number): boolean {
+  const text = kids[i] as NodeWithValue;
+  let open: RegExpExecArray | null;
+  const re = new RegExp(OPEN_TAG.source, 'g');
+  do {
+    open = re.exec(text.value);
+  } while (open && !open[2]?.includes('={{'));
+  if (!open) return false;
+
+  const [openTag, tagName] = open;
+  const prefix = text.value.slice(0, open.index);
+  const rest = text.value.slice(open.index + openTag.length);
+
+  const closeSelf = new RegExp(`</${tagName}\\s*>`).exec(rest);
+  if (closeSelf) {
+    const end = closeSelf.index + closeSelf[0].length;
+    kids.splice(
+      i,
+      1,
+      ...compact([
+        prefix ? textNode(prefix) : undefined,
+        elementNode(openTag, tagName, [textNode(rest.slice(0, closeSelf.index))]),
+        rest.slice(end) ? textNode(rest.slice(end)) : undefined,
+      ]),
+    );
+    return true;
+  }
+
+  for (let j = i + 1; j < kids.length; j++) {
+    const sib = kids[j]!;
+    if (
+      sib.type === 'html' &&
+      typeof sib.value === 'string' &&
+      new RegExp(`^</${tagName}\\s*>$`).test(sib.value.trim())
+    ) {
+      const inner = rest ? [textNode(rest)] : [];
+      kids.splice(
+        i,
+        j - i + 1,
+        ...compact([
+          prefix ? textNode(prefix) : undefined,
+          elementNode(openTag, tagName, [...inner, ...kids.slice(i + 1, j)]),
+        ]),
+      );
+      return true;
+    }
+  }
+
+  kids.splice(
+    i,
+    1,
+    ...compact([
+      prefix ? textNode(prefix) : undefined,
+      elementNode(openTag, tagName, rest ? [textNode(rest)] : []),
+    ]),
+  );
+  return true;
+}
+
+function compact(nodes: (MdastNode | undefined)[]): MdastNode[] {
+  return nodes.filter((n): n is MdastNode => n !== undefined);
+}

package/src/lib/mdx/preview.ts

@@ -0,0 +1,252 @@
+import { createRequire } from 'node:module';
+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, type Plugin } from 'unified';
+import {
+  contentChildren,
+  extractDirectiveLabel,
+  jsxAttr,
+  type DirectiveNode,
+  type JsxElement,
+  type MdastNode,
+} from './directive-utils.ts';
+
+const require = createRequire(import.meta.url);
+
+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 } = require('fumadocs-mdx/config') as {
+    remarkInclude: Plugin;
+  };
+
+  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 result = (await processor.run(
+    tree,
+    file 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,56 @@
+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,80 @@
+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/mdx-components.tsx

@@ -0,0 +1,139 @@
+import {
+  Tab,
+  Tabs,
+  TabsContent,
+  TabsList,
+  TabsTrigger,
+} from '@terrafirmagreg-team/ui/components/mdx/tabs';
+import {
+  Accordion,
+  Accordions,
+} from '@terrafirmagreg-team/ui/components/mdx/accordion';
+import { Step, Steps } from '@terrafirmagreg-team/ui/components/mdx/steps';
+import {
+  File,
+  Folder,
+  Files,
+} from '@terrafirmagreg-team/ui/components/mdx/files';
+import { ImageZoom } from '@terrafirmagreg-team/ui/components/mdx/image-zoom';
+import { Banner } from '@terrafirmagreg-team/ui/components/mdx/banner';
+import { TypeTable } from '@terrafirmagreg-team/ui/components/mdx/type-table';
+import { Card, Cards } from '@terrafirmagreg-team/ui/components/mdx/card';
+import { Table } from '@terrafirmagreg-team/ui/components/mdx/table';
+import {
+  CalloutDescription,
+  CalloutTitle,
+} from '@terrafirmagreg-team/ui/components/mdx/callout';
+import {
+  CodeBlock,
+  CodeBlockTab,
+  CodeBlockTabs,
+  CodeBlockTabsList,
+  CodeBlockTabsTrigger,
+  Pre,
+} from '@terrafirmagreg-team/ui/components/mdx/codeblock';
+import { Heading } from '@terrafirmagreg-team/ui/components/blocks/page/heading';
+import * as Twoslash from 'fumadocs-twoslash/ui';
+import { Mermaid } from '@terrafirmagreg-team/ui/components/mdx/mermaid';
+import { Callout, CalloutContainer } from '@terrafirmagreg-team/ui/components/mdx/callout';
+import { Input, Output, Preview } from '@terrafirmagreg-team/ui/components/mdx/preview';
+import { DocsImage } from '@terrafirmagreg-team/kit/components/docs-image';
+import { Multiblock } from '@terrafirmagreg-team/ui/components/mdx/multiblock';
+import { GradientText } from '@terrafirmagreg-team/ui/components/mdx/gradient-text';
+import { GlowHeader } from '@terrafirmagreg-team/ui/components/mdx/glow-header';
+import { LinkPreview } from '@terrafirmagreg-team/ui/components/blocks/link/link-preview';
+import type { MDXComponents } from 'mdx/types';
+import type { ComponentProps, HTMLAttributes } from 'react';
+
+const extras: MDXComponents = {};
+
+export function registerMdxComponents(map: MDXComponents): void {
+  Object.assign(extras, map);
+}
+
+export function getMDXComponents(components?: MDXComponents) {
+  return {
+    ...extras,
+    CodeBlockTab,
+    CodeBlockTabs,
+    CodeBlockTabsList,
+    CodeBlockTabsTrigger,
+    Tab,
+    Tabs,
+    TabsContent,
+    TabsList,
+    TabsTrigger,
+    ...Twoslash,
+    Accordion,
+    Accordions,
+    Step,
+    Steps,
+    File,
+    Folder,
+    Files,
+    Mermaid,
+    Banner,
+    TypeTable,
+    Card,
+    Cards,
+    Callout,
+    CalloutContainer,
+    CalloutTitle,
+    CalloutDescription,
+    Preview,
+    Input,
+    Output,
+    DocsImage,
+    Multiblock,
+    GradientText,
+    GlowHeader,
+    a: LinkPreview,
+    pre: (props: HTMLAttributes<HTMLPreElement>) => (
+      <CodeBlock {...props}>
+        <Pre>{props.children}</Pre>
+      </CodeBlock>
+    ),
+    h1: (props: HTMLAttributes<HTMLHeadingElement>) => (
+      <Heading as="h1" {...props} />
+    ),
+    h2: (props: HTMLAttributes<HTMLHeadingElement>) => (
+      <Heading as="h2" {...props} />
+    ),
+    h3: (props: HTMLAttributes<HTMLHeadingElement>) => (
+      <Heading as="h3" {...props} />
+    ),
+    h4: (props: HTMLAttributes<HTMLHeadingElement>) => (
+      <Heading as="h4" {...props} />
+    ),
+    h5: (props: HTMLAttributes<HTMLHeadingElement>) => (
+      <Heading as="h5" {...props} />
+    ),
+    h6: (props: HTMLAttributes<HTMLHeadingElement>) => (
+      <Heading as="h6" {...props} />
+    ),
+    table: Table,
+    img: (props: ComponentProps<'img'>) => {
+      if (typeof props.src !== 'string' || /^https?:\/\//i.test(props.src)) {
+        // eslint-disable-next-line @next/next/no-img-element
+        return <img {...props} alt={props.alt ?? ''} />;
+      }
+      const width = Number(props.width) || undefined;
+      const height = Number(props.height) || undefined;
+      return (
+        <ImageZoom
+          src={props.src}
+          alt={props.alt ?? ''}
+          width={width ?? 960}
+          height={height ?? 540}
+          sizes={props.sizes as string | undefined}
+          className={props.className}
+        />
+      );
+    },
+    ...components,
+  } as MDXComponents;
+}
+
+declare global {
+  type MDXProvidedComponents = ReturnType<typeof getMDXComponents>;
+}