@terrafirmagreg-team/mdx 0.0.0-stage → 1.2.1

package/src/components/story-panel.tsx

@@ -0,0 +1,181 @@
+'use client';
+
+import {
+  StoryProvider,
+  useStory,
+  useStoryArgs,
+  type WithControlProps,
+} from '@fumadocs/story';
+import { StoryFields } from './story-fields';
+import { remarkFor, tweakControls } from '../lib/story-remark';
+import { highlightRemark } from '../lib/remark-highlight';
+import { useCopyButton } from '@terrafirmagreg-team/ui/hooks/use-copy-button';
+import { Check, Clipboard } from 'lucide-react';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@terrafirmagreg-team/ui/components/ui/select';
+import {
+  Component,
+  createElement,
+  useMemo,
+  type ErrorInfo,
+  type ReactNode,
+} from 'react';
+import { CircleAlert, RotateCcw } from 'lucide-react';
+
+function RemarkHint() {
+  const { displayName, preset, variant } = useStory();
+  const args = useStoryArgs();
+  const text = useMemo(
+    () => remarkFor(displayName ?? 'component', args, preset?.controls, variant),
+    [displayName, args, preset, variant],
+  );
+  const tokens = useMemo(() => highlightRemark(text), [text]);
+  const { checked, onClick } = useCopyButton(() =>
+    navigator.clipboard.writeText(text),
+  );
+  return (
+    <div className="relative border-t">
+      <pre className="overflow-x-auto px-4 py-2.5 pe-9 font-mono text-xs leading-relaxed text-fd-muted-foreground whitespace-pre-wrap">
+        {tokens.map((t, i) => (
+          <span key={i} className={t.cls}>
+            {t.text}
+          </span>
+        ))}
+      </pre>
+      <button
+        type="button"
+        aria-label="Copy markdown"
+        title="Copy markdown"
+        onClick={onClick}
+        className="absolute top-1.5 right-1.5 rounded-md p-1.5 text-fd-muted-foreground hover:bg-fd-accent hover:text-fd-foreground"
+      >
+        {checked ? (
+          <Check className="size-3.5" />
+        ) : (
+          <Clipboard className="size-3.5" />
+        )}
+      </button>
+    </div>
+  );
+}
+
+class PreviewBoundary extends Component<
+  { children: ReactNode; resetKey: unknown },
+  { error: Error | null }
+> {
+  state = { error: null as Error | null };
+  static getDerivedStateFromError(error: Error) {
+    return { error };
+  }
+  componentDidCatch(error: Error, info: ErrorInfo) {
+    console.error(error, info);
+  }
+  componentDidUpdate(prev: { resetKey: unknown }) {
+    if (prev.resetKey !== this.props.resetKey && this.state.error)
+      this.setState({ error: null });
+  }
+  render() {
+    if (this.state.error)
+      return (
+        <div role="alert" className="flex items-center gap-2 text-sm">
+          <CircleAlert className="size-3.5 shrink-0 text-fd-error" />
+          <span className="font-mono text-xs break-all text-fd-muted-foreground">
+            {this.state.error.message}
+          </span>
+        </div>
+      );
+    return this.props.children;
+  }
+}
+
+function VariantSelect() {
+  const { presets, variant, setVariant } = useStory();
+  return (
+    <Select value={variant} onValueChange={(v) => v && setVariant(v)}>
+      <SelectTrigger className="h-7 w-auto max-w-64 gap-1.5 border-0 bg-transparent px-2 text-xs hover:bg-fd-accent focus:ring-0 focus-visible:ring-2">
+        <span className="text-fd-muted-foreground">Variant</span>
+        <SelectValue className="truncate font-medium" />
+      </SelectTrigger>
+      <SelectContent align="end">
+        {presets.map((item) => (
+          <SelectItem
+            key={item.variant}
+            value={item.variant}
+            className="text-xs"
+          >
+            {item.variant}
+          </SelectItem>
+        ))}
+      </SelectContent>
+    </Select>
+  );
+}
+
+function Content() {
+  const { presets, displayName, preset, variant, setVariant, Component } =
+    useStory();
+  const args = useStoryArgs();
+  const reset = () => setVariant(variant);
+  return (
+    <div className="not-prose overflow-hidden rounded-xl border bg-fd-card text-fd-card-foreground">
+      {(displayName || presets.length > 1) && (
+        <div className="flex h-10 items-center justify-end gap-1 border-b ps-4 pe-1.5">
+          {displayName && (
+            <p className="me-auto truncate font-mono text-[0.8125rem] font-medium">
+              {displayName}
+            </p>
+          )}
+          <button
+            type="button"
+            aria-label="Reset"
+            title="Reset"
+            onClick={reset}
+            className="rounded-md p-1.5 text-fd-muted-foreground hover:bg-fd-accent"
+          >
+            <RotateCcw className="size-3.5" />
+          </button>
+          {presets.length > 1 && <VariantSelect />}
+        </div>
+      )}
+      <div className="bg-fd-background p-4 not-last:border-b">
+        <PreviewBoundary resetKey={args}>
+          {createElement(Component, args)}
+        </PreviewBoundary>
+      </div>
+      {preset && (
+        <StoryFields
+          key={variant}
+          node={preset.controls}
+          storyKey={displayName ?? ''}
+        />
+      )}
+      <RemarkHint />
+    </div>
+  );
+}
+
+export function DocsWithControl({ presets, ...rest }: WithControlProps) {
+  const tweaked = useMemo(
+    () =>
+      presets.map((preset) => ({
+        ...preset,
+        controls: tweakControls(
+          rest.displayName ?? '',
+          preset.controls,
+          preset.defaultValues,
+        ),
+      })),
+    [presets, rest.displayName],
+  );
+  return (
+    <StoryProvider {...rest} presets={tweaked}>
+      <Content />
+    </StoryProvider>
+  );
+}
+

package/src/lib/markdown/dom.ts

@@ -0,0 +1,104 @@
+'use client';
+import type TurndownService from 'turndown';
+
+function decodedUrl(raw: string): string {
+  const url = raw.replace(/(?:%[0-9A-Fa-f]{2})+/g, (run) => {
+    let decoded: string;
+    try {
+      decoded = decodeURIComponent(run);
+    } catch {
+      return run;
+    }
+    return /[/?#&=%+]/.test(decoded) ? run : decoded;
+  });
+  return /[\s<>()]/.test(url) ? `<${url}>` : url;
+}
+
+let servicePromise: Promise<TurndownService> | undefined;
+
+function turndownService(): Promise<TurndownService> {
+  servicePromise ??= (async () => {
+    const [{ default: TurndownServiceImpl }, { gfm }] = await Promise.all([
+      import('turndown'),
+      // @ts-expect-error -- no published type declarations
+      import('turndown-plugin-gfm'),
+    ]);
+    const service = new TurndownServiceImpl({
+      headingStyle: 'atx',
+      codeBlockStyle: 'fenced',
+      bulletListMarker: '-',
+    });
+    service.use(gfm);
+    service.remove([
+      'script',
+      'style',
+      'noscript',
+      'template',
+      'button',
+      'select',
+      'nav',
+      'aside',
+      'footer',
+    ]);
+    service.remove(
+      (node) =>
+        node.nodeName === 'SVG' ||
+        (node instanceof HTMLImageElement &&
+          (node.src.startsWith('data:') ||
+            (node.width > 0 && node.width <= 48))) ||
+        (node instanceof HTMLElement && node.dataset.mdSkip !== undefined),
+    );
+    service.addRule('decodedLink', {
+      filter: 'a',
+      replacement(content, node) {
+        const anchor = node as HTMLAnchorElement;
+        const href = anchor.getAttribute('href');
+        if (!href) return content;
+        const title = anchor.getAttribute('title');
+        const titlePart = title ? ` "${title.replace(/"/g, '\\"')}"` : '';
+        return `[${content}](${decodedUrl(href)}${titlePart})`;
+      },
+    });
+    service.addRule('decodedImage', {
+      filter: 'img',
+      replacement(_content, node) {
+        const image = node as HTMLImageElement;
+        const src = image.getAttribute('src');
+        if (!src) return '';
+        const alt = image.getAttribute('alt') ?? '';
+        const title = image.getAttribute('title');
+        const titlePart = title ? ` "${title.replace(/"/g, '\\"')}"` : '';
+        return `![${alt}](${decodedUrl(src)}${titlePart})`;
+      },
+    });
+    return service;
+  })();
+  return servicePromise;
+}
+
+export async function domToMarkdown(
+  root: Element | null | undefined,
+): Promise<string> {
+  if (!root) return '';
+  return (await turndownService()).turndown(root as HTMLElement);
+}
+
+export function pageMarkdown(
+  root: Element | null | undefined,
+  title: string,
+): Promise<string> {
+  return domToMarkdown(root).then((body) => `# ${title}\n\n${body}`);
+}
+
+export async function openPageMarkdown(
+  root: Element | null | undefined,
+  title: string,
+): Promise<void> {
+  const markdown = await pageMarkdown(root, title);
+  const url = URL.createObjectURL(
+    new Blob([markdown], { type: 'text/markdown;charset=utf-8' }),
+  );
+  window.open(url, '_blank', 'noopener');
+  setTimeout(() => URL.revokeObjectURL(url), 60_000);
+}
+

package/src/lib/markdown/index.ts

@@ -0,0 +1,18 @@
+export * from './dom';
+export * from './providers';
+
+export async function renderSectionMarkdown(page: {
+  data: {
+    title?: string;
+    content?: string;
+    getText?: (type: 'processed' | 'raw') => Promise<string>;
+  };
+}) {
+  const body = page.data.getText
+    ? await page.data.getText('processed')
+    : (page.data.content ?? '');
+  return `# ${page.data.title}
+
+${body}`;
+}
+

package/src/lib/markdown/providers.ts

@@ -0,0 +1,26 @@
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+
+export interface MarkdownProviderCtx {
+
+  slugs: string[];
+  lang: Lang;
+}
+
+export type MarkdownProvider = (
+  req: Request,
+  ctx: MarkdownProviderCtx,
+) => Promise<Response | undefined>;
+
+const providers = new Map<string, MarkdownProvider>();
+
+export function registerMarkdownProvider(
+  section: string,
+  provider: MarkdownProvider,
+): void {
+  providers.set(section, provider);
+}
+
+export function markdownProvider(section: string): MarkdownProvider | undefined {
+  return providers.get(section);
+}
+

package/src/lib/md-plugins.ts

@@ -0,0 +1,113 @@
+import { rehypeCode } from 'fumadocs-core/mdx-plugins/rehype-code';
+import {
+  rehypeCodeDefaultOptions,
+  remarkDirectiveAdmonition,
+  remarkMdxFiles,
+  remarkMdxMermaid,
+  remarkSteps,
+} from 'fumadocs-core/mdx-plugins';
+import { remarkBlockId } from 'fumadocs-core/mdx-plugins/remark-block-id';
+import { transformerTwoslash } from 'fumadocs-twoslash';
+import { fileGenerator, remarkDocGen, remarkShow } from 'fumadocs-docgen';
+import { remarkAutoTypeTable } from 'fumadocs-typescript';
+import remarkDirective from 'remark-directive';
+import remarkMath from 'remark-math';
+import rehypeKatex from 'rehype-katex';
+import rehypeRaw from 'rehype-raw';
+import { remarkAccordions } from './mdx/accordions';
+import { remarkBanner } from './mdx/banner';
+import { remarkDirectives } from './mdx/directives';
+import { remarkHtmlStyle } from './mdx/html-style';
+import { remarkGameExport } from './mdx/game-export';
+import { remarkPreview } from './mdx/preview';
+import { remarkChangelogReferences } from './mdx/references';
+import { remarkTabs } from './mdx/tabs';
+import type { PluggableList } from 'unified';
+
+const rehypeCodeOptions = {
+  ...rehypeCodeDefaultOptions,
+  inline: 'tailing-curly-colon' as const,
+  transformers: [
+    ...(rehypeCodeDefaultOptions.transformers ?? []),
+    transformerTwoslash(),
+    {
+      name: 'code-lang-title',
+      pre(this: { options?: { lang?: string } }, node: {
+        properties?: Record<string, unknown>;
+      }) {
+        node.properties ??= {};
+        node.properties.title ??= this.options?.lang;
+      },
+    },
+  ],
+  langs: [
+    ...(rehypeCodeDefaultOptions.langs ?? []),
+    'java',
+    'json',
+    'yaml',
+    'bash',
+    'md',
+    'toml',
+    'diff',
+  ],
+};
+
+export const mdOptions = (
+  datasetConfig: Record<string, { repo?: string }> = {},
+) => ({
+  mdOptions: {
+    remarkPlugins: [
+      remarkDirective,
+      remarkPreview,
+      remarkTabs,
+      remarkAccordions,
+      remarkBanner,
+      remarkDirectives,
+      remarkHtmlStyle,
+      remarkGameExport,
+      [remarkChangelogReferences, { datasetConfig }],
+      [remarkDocGen, { generators: [fileGenerator()] }],
+      remarkShow,
+      remarkAutoTypeTable,
+      [
+        remarkDirectiveAdmonition,
+        {
+          types: {
+            note: 'note',
+            tip: 'tip',
+            info: 'info',
+            warn: 'warning',
+            warning: 'warning',
+            danger: 'error',
+            success: 'success',
+            idea: 'idea',
+          },
+        },
+      ],
+      remarkMath,
+      remarkSteps,
+      remarkMdxFiles,
+      remarkMdxMermaid,
+      [remarkBlockId, { addDataAttribute: 'feedback' }],
+    ] as PluggableList,
+    remarkRehypeOptions: { allowDangerousHtml: true },
+    rehypeCodeOptions: false,
+    rehypePlugins: [
+      rehypeKatex,
+      [rehypeCode, rehypeCodeOptions],
+      [
+        rehypeRaw,
+        {
+          passThrough: [
+            'mdxjsEsm',
+            'mdxJsxFlowElement',
+            'mdxJsxTextElement',
+            'mdxFlowExpression',
+            'mdxTextExpression',
+          ],
+        },
+      ],
+    ] as PluggableList,
+  } as const,
+});
+

package/src/lib/md.ts

@@ -0,0 +1,20 @@
+export function md(
+  strings: TemplateStringsArray,
+  ...values: unknown[]
+): string {
+  const raw = String.raw(strings, ...values);
+  const lines = raw
+    .replace(/^\n/, '')
+    .replace(/\s+$/, '')
+    .split('\n');
+  const indent = Math.min(
+    ...lines
+      .filter((l) => l.trim())
+      .map((l) => (l.match(/^ */)?.[0].length ?? 0)),
+  );
+  return lines
+    .map((l) => l.slice(indent))
+    .join('\n')
+    .replaceAll('\\`', '`');
+}
+

package/src/lib/mdx/accordions.ts

@@ -0,0 +1,102 @@
+import {
+  contentChildren,
+  estreeBoolean,
+  extractDirectiveLabel,
+  extractLeafLabel,
+  jsxAttr,
+  jsxExpression,
+  walkContainers,
+  type DirectiveNode,
+  type JsxAttribute,
+  type JsxElement,
+  type MdastNode,
+} from './directive-utils.ts';
+
+export function remarkAccordions() {
+  return (tree: MdastNode) => {
+    walkContainers(tree, (directive) => {
+      if (directive.name === 'accordion' || directive.name === 'details') {
+        wrapSingle(directive);
+        return false;
+      }
+      if (directive.name === 'accordions') {
+        toAccordions(directive);
+        return false;
+      }
+    });
+  };
+}
+
+function toAccordion(node: DirectiveNode): JsxElement {
+  return {
+    type: 'mdxJsxFlowElement',
+    name: 'Accordion',
+    attributes: [jsxAttr('title', extractDirectiveLabel(node))],
+    children: contentChildren(node),
+  };
+}
+
+function wrapSingle(node: DirectiveNode): void {
+  Object.assign(node, {
+    type: 'mdxJsxFlowElement',
+    name: 'Accordions',
+    attributes: [],
+    children: [toAccordion(node)],
+  });
+}
+
+function accordionsAttributes(node: DirectiveNode): JsxAttribute[] {
+  const attrs = node.attributes ?? {};
+  const out: JsxAttribute[] = [];
+  const isMultiple =
+    attrs.multiple === true ||
+    attrs.multiple === '' ||
+    attrs.type === 'multiple';
+
+  if (isMultiple) out.push(jsxAttr('multiple', true));
+
+  for (const [name, value] of Object.entries(attrs)) {
+    if (name === 'type' || name === 'multiple') continue;
+    out.push({
+      type: 'mdxJsxAttribute',
+      name,
+      value:
+        value == null || value === ''
+          ? jsxExpression(estreeBoolean(true))
+          : value,
+    });
+  }
+
+  return out;
+}
+
+function toAccordions(node: DirectiveNode): void {
+  const items: JsxElement[] = [];
+  let current: JsxElement | undefined;
+
+  for (const item of node.children ?? []) {
+    if (
+      item.type === 'leafDirective' &&
+      (item as { name?: string }).name === 'accordion'
+    ) {
+      current = {
+        type: 'mdxJsxFlowElement',
+        name: 'Accordion',
+        attributes: [jsxAttr('title', extractLeafLabel(item))],
+        children: [],
+      };
+      items.push(current);
+      continue;
+    }
+
+    current?.children.push(item);
+  }
+
+  Object.assign(node, {
+    type: 'mdxJsxFlowElement',
+    name: 'Accordions',
+    attributes: accordionsAttributes(node),
+    children: items,
+  });
+}
+

package/src/lib/mdx/banner.ts

@@ -0,0 +1,57 @@
+import {
+  estreeBoolean,
+  estreeStringArray,
+  jsxExpression,
+  walkContainers,
+  type DirectiveNode,
+  type MdastNode,
+} from './directive-utils.ts';
+
+export function remarkBanner() {
+  return (tree: MdastNode) => {
+    walkContainers(tree, (directive) => {
+      if (directive.name !== 'banner') return;
+      Object.assign(directive, {
+        type: 'mdxJsxFlowElement',
+        name: 'Banner',
+        attributes: [
+          {
+            type: 'mdxJsxAttribute',
+            name: 'changeLayout',
+            value: jsxExpression(estreeBoolean(false)),
+          },
+          ...toAttributes(directive),
+        ],
+        children: directive.children,
+      });
+      return false;
+    });
+  };
+}
+
+function toAttributes(directive: DirectiveNode) {
+  return Object.entries(directive.attributes ?? {})
+    .filter(([name]) => name !== 'id')
+    .map(([name, value]) => {
+      if (name === 'rainbowColors' && typeof value === 'string') {
+        const colors = value
+          .split(',')
+          .map((color) => color.trim())
+          .filter(Boolean);
+        return {
+          type: 'mdxJsxAttribute' as const,
+          name,
+          value: jsxExpression(estreeStringArray(colors)),
+        };
+      }
+      return {
+        type: 'mdxJsxAttribute' as const,
+        name,
+        value:
+          value == null || value === ''
+            ? jsxExpression(estreeBoolean(true))
+            : value,
+      };
+    });
+}
+