docs-i18n 0.6.2 → 0.7.0

package/template/app/components/icons/YouTubeIcon.tsx

@@ -0,0 +1,24 @@
+import * as React from 'react'
+
+export function YouTubeIcon({
+  className,
+  width = '1em',
+  height = '1em',
+  ...props
+}: React.SVGProps<SVGSVGElement>) {
+  return (
+    <svg
+      viewBox="0 0 461 461"
+      fill="currentColor"
+      width={width}
+      height={height}
+      role="img"
+      aria-hidden={props['aria-label'] ? undefined : true}
+      className={className}
+      {...props}
+      xmlns="http://www.w3.org/2000/svg"
+    >
+      <path d="M365.257,67.393H95.744C42.866,67.393,0,110.259,0,163.137v134.728 c0,52.878,42.866,95.744,95.744,95.744h269.513c52.878,0,95.744-42.866,95.744-95.744V163.137 C461.001,110.259,418.135,67.393,365.257,67.393z M300.506,237.056l-126.06,60.123c-3.359,1.602-7.239-0.847-7.239-4.568V168.607 c0-3.774,3.982-6.22,7.348-4.514l126.06,63.881C304.363,229.873,304.298,235.248,300.506,237.056z" />
+    </svg>
+  )
+}

package/template/app/components/markdown/CodeBlock.tsx

@@ -0,0 +1,254 @@
+import * as React from 'react'
+import { twMerge } from 'tailwind-merge'
+import { Copy } from 'lucide-react'
+import type { Mermaid } from 'mermaid'
+import { transformerNotationDiff } from '@shikijs/transformers'
+import type { HighlighterGeneric } from 'shiki'
+import { createHighlighter } from 'shiki'
+import { Button } from '../ui/Button'
+
+// Language aliases mapping
+const LANG_ALIASES: Record<string, string> = {
+  ts: 'typescript',
+  js: 'javascript',
+  sh: 'bash',
+  shell: 'bash',
+  console: 'bash',
+  zsh: 'bash',
+  cmd: 'bash',
+  md: 'markdown',
+  txt: 'plaintext',
+  text: 'plaintext',
+  yml: 'yaml',
+  json5: 'jsonc',
+  eslintrc: 'jsonc',
+}
+
+// Lazy highlighter singleton
+let highlighterPromise: Promise<HighlighterGeneric<any, any>> | null = null
+let mermaidInstance: Mermaid | null = null
+const genSvgMap = new Map<string, string>()
+const failedLanguages = new Set<string>()
+
+async function getHighlighter(language: string): Promise<{
+  highlighter: HighlighterGeneric<any, any>
+  effectiveLang: string
+}> {
+  if (!highlighterPromise) {
+    highlighterPromise = createHighlighter({
+      themes: ['github-light', 'aurora-x'],
+      langs: [
+        'typescript',
+        'javascript',
+        'tsx',
+        'jsx',
+        'bash',
+        'json',
+        'html',
+        'css',
+        'markdown',
+        'plaintext',
+        'toml',
+        'yaml',
+        'sql',
+        'diff',
+        'vue',
+        'svelte',
+        'scss',
+        'jsonc',
+        'vue-html',
+        'angular-html',
+        'angular-ts',
+      ],
+    })
+  }
+
+  const highlighter = await highlighterPromise
+  const normalizedLang = LANG_ALIASES[language] || language
+  const langToLoad = normalizedLang === 'mermaid' ? 'plaintext' : normalizedLang
+
+  // Return plaintext for known failed languages
+  if (failedLanguages.has(langToLoad)) {
+    return { highlighter, effectiveLang: 'plaintext' }
+  }
+
+  // Load language if not already loaded
+  if (!highlighter.getLoadedLanguages().includes(langToLoad as any)) {
+    try {
+      await highlighter.loadLanguage(langToLoad as any)
+    } catch {
+      console.warn(`Shiki: Language "${langToLoad}" not found, using plaintext`)
+      failedLanguages.add(langToLoad)
+      return { highlighter, effectiveLang: 'plaintext' }
+    }
+  }
+
+  return { highlighter, effectiveLang: langToLoad }
+}
+
+// Lazy load mermaid only when needed
+async function getMermaid(): Promise<Mermaid> {
+  if (!mermaidInstance) {
+    const { default: mermaid } = await import('mermaid')
+    mermaid.initialize({ startOnLoad: false, securityLevel: 'loose' })
+    mermaidInstance = mermaid
+  }
+  return mermaidInstance
+}
+
+function extractPreAttributes(html: string): {
+  class: string | null
+  style: string | null
+} {
+  const match = html.match(/<pre\b([^>]*)>/i)
+  if (!match) {
+    return { class: null, style: null }
+  }
+
+  const attributes = match[1]
+
+  const classMatch = attributes.match(/\bclass\s*=\s*["']([^"']*)["']/i)
+  const styleMatch = attributes.match(/\bstyle\s*=\s*["']([^"']*)["']/i)
+
+  return {
+    class: classMatch ? classMatch[1] : null,
+    style: styleMatch ? styleMatch[1] : null,
+  }
+}
+
+export function CodeBlock({
+  isEmbedded,
+  showTypeCopyButton = true,
+  ...props
+}: React.HTMLProps<HTMLPreElement> & {
+  isEmbedded?: boolean
+  showTypeCopyButton?: boolean
+  dataCodeTitle?: string
+}) {
+  // Extract title from data-code-title attribute, handling both camelCase and kebab-case
+  const rawTitle = ((props as any)?.dataCodeTitle ||
+    (props as any)?.['data-code-title']) as string | undefined
+
+  // Filter out "undefined" strings, null, and empty strings
+  const title =
+    rawTitle && rawTitle !== 'undefined' && rawTitle.trim().length > 0
+      ? rawTitle.trim()
+      : undefined
+
+  const childElement = props.children as
+    | undefined
+    | { props?: { className?: string; children?: string } }
+  const lang = childElement?.props?.className?.replace('language-', '')
+
+  const children = props.children as
+    | undefined
+    | {
+        props: {
+          children: string
+        }
+      }
+
+  const [copied, setCopied] = React.useState(false)
+  const ref = React.useRef<any>(null)
+
+  const code = children?.props.children
+
+  const [codeElement, setCodeElement] = React.useState(
+    <pre ref={ref} className={`shiki h-full github-light dark:aurora-x`}>
+      <code>{lang === 'mermaid' ? <svg /> : code}</code>
+    </pre>,
+  )
+
+  React[
+    typeof document !== 'undefined' ? 'useLayoutEffect' : 'useEffect'
+  ](() => {
+    ;(async () => {
+      const themes = ['github-light', 'aurora-x']
+      const langStr = lang || 'plaintext'
+
+      const { highlighter, effectiveLang } = await getHighlighter(langStr)
+      // Trim trailing newlines to prevent empty lines at end of code block
+      const trimmedCode = (code || '').trimEnd()
+
+      const htmls = await Promise.all(
+        themes.map(async (theme) => {
+          const output = highlighter.codeToHtml(trimmedCode, {
+            lang: effectiveLang,
+            theme,
+            transformers: [transformerNotationDiff()],
+          })
+
+          if (lang === 'mermaid') {
+            const preAttributes = extractPreAttributes(output)
+            let svgHtml = genSvgMap.get(trimmedCode)
+            if (!svgHtml) {
+              const mermaid = await getMermaid()
+              const { svg } = await mermaid.render('foo', trimmedCode)
+              genSvgMap.set(trimmedCode, svg)
+              svgHtml = svg
+            }
+            return `<div class='${preAttributes.class} py-4 bg-neutral-50'>${svgHtml}</div>`
+          }
+
+          return output
+        }),
+      )
+
+      setCodeElement(
+        <div
+          className={twMerge(
+            isEmbedded ? 'h-full [&>pre]:h-full [&>pre]:rounded-none' : '',
+          )}
+          dangerouslySetInnerHTML={{ __html: htmls.join('') }}
+          ref={ref}
+        />,
+      )
+    })()
+  }, [code, lang])
+
+  return (
+    <div
+      className={twMerge(
+        'codeblock w-full max-w-full relative not-prose border border-gray-500/20 rounded-md [&_pre]:rounded-md',
+        props.className,
+      )}
+      style={props.style}
+    >
+      {(title || showTypeCopyButton) && (
+        <div className="flex items-center justify-between px-4 py-2 bg-gray-50 dark:bg-gray-900">
+          <div className="text-xs text-gray-700 dark:text-gray-300">
+            {title || (lang?.toLowerCase() === 'bash' ? 'sh' : (lang ?? ''))}
+          </div>
+
+          <Button
+            variant="ghost"
+            size="xs"
+            className={twMerge('border-0 rounded-md transition-opacity')}
+            onClick={() => {
+              let copyContent =
+                typeof ref.current?.innerText === 'string'
+                  ? ref.current.innerText
+                  : ''
+
+              if (copyContent.endsWith('\n')) {
+                copyContent = copyContent.slice(0, -1)
+              }
+
+              navigator.clipboard.writeText(copyContent)
+              setCopied(true)
+              setTimeout(() => setCopied(false), 2000)
+            }}
+            aria-label="Copy code to clipboard"
+          >
+            {copied ? (
+              <span className="text-xs">Copied!</span>
+            ) : (
+              <Copy className="w-4 h-4" />
+            )}
+          </Button>
+        </div>
+      )}
+      {codeElement}
+    </div>
+  )
+}

package/template/app/components/markdown/FileTabs.tsx

@@ -0,0 +1,58 @@
+import * as React from 'react'
+
+export type FileTabDefinition = {
+  slug: string
+  name: string
+}
+
+export type FileTabsProps = {
+  tabs: Array<FileTabDefinition>
+  children: Array<React.ReactNode> | React.ReactNode
+}
+
+export function FileTabs({ tabs, children }: FileTabsProps) {
+  const id = React.useId()
+  const childrenArray = React.Children.toArray(children)
+  const [activeSlug, setActiveSlug] = React.useState(tabs[0]?.slug ?? '')
+
+  if (tabs.length === 0) return null
+
+  return (
+    <div className="not-prose my-4">
+      <div className="flex items-center justify-start gap-0 overflow-x-auto overflow-y-hidden bg-gray-100 dark:bg-gray-900 border border-b-0 border-gray-500/20 rounded-t-md">
+        {tabs.map((tab) => (
+          <button
+            key={`${id}-${tab.slug}`}
+            type="button"
+            onClick={() => setActiveSlug(tab.slug)}
+            aria-label={tab.name}
+            title={tab.name}
+            className={`px-3 py-1.5 text-sm font-medium transition-colors border-b-2 -mb-[1px] ${
+              activeSlug === tab.slug
+                ? 'border-current text-current bg-white dark:bg-gray-950'
+                : 'border-transparent text-gray-600 dark:text-gray-400 hover:text-gray-900 dark:hover:text-gray-200 hover:bg-gray-200 dark:hover:bg-gray-800'
+            }`}
+          >
+            {tab.name}
+          </button>
+        ))}
+      </div>
+      <div>
+        {childrenArray.map((child, index) => {
+          const tab = tabs[index]
+          if (!tab) return null
+          return (
+            <div
+              key={`${id}-${tab.slug}-panel`}
+              data-tab={tab.slug}
+              hidden={tab.slug !== activeSlug}
+              className="file-tabs-panel"
+            >
+              {child}
+            </div>
+          )
+        })}
+      </div>
+    </div>
+  )
+}

package/template/app/components/markdown/FrameworkContent.tsx

@@ -0,0 +1,76 @@
+import { useParams } from '@tanstack/react-router'
+import { Tabs } from './Tabs'
+import { Children, ReactNode } from 'react'
+
+type CodeBlockMeta = {
+  title: string
+  code: string
+  language: string
+}
+
+type FrameworkContentProps = {
+  codeBlocksByFramework: Record<string, CodeBlockMeta[]>
+  availableFrameworks: string[]
+  /** Pre-rendered React children for each framework (from domToReact) */
+  panelsByFramework: Record<string, ReactNode>
+}
+
+// Simple localStorage-based framework preference (replaces useCurrentUserQuery auth dependency)
+function useLocalFrameworkPreference(): string | undefined {
+  if (typeof document === 'undefined') return undefined
+  return localStorage.getItem('framework') || undefined
+}
+
+/**
+ * Renders content for the currently selected framework.
+ * - If no content for framework: shows nothing
+ * - If 1 code block: shows just the code block (minimal style)
+ * - If multiple code blocks: shows as file tabs
+ * - If no code blocks but has content: shows the content directly
+ */
+export function FrameworkContent({
+  codeBlocksByFramework,
+  panelsByFramework,
+}: FrameworkContentProps) {
+  const { framework: paramsFramework } = useParams({ strict: false })
+  const localFramework = useLocalFrameworkPreference()
+
+  const actualFramework = (paramsFramework ||
+    localFramework ||
+    'react') as string
+
+  const normalizedFramework = actualFramework.toLowerCase()
+
+  // Find the framework's code blocks
+  const frameworkBlocks = codeBlocksByFramework[normalizedFramework] || []
+  const frameworkPanel = panelsByFramework[normalizedFramework]
+
+  // If no panel content at all for this framework, show nothing
+  if (!frameworkPanel) {
+    return null
+  }
+
+  // If no code blocks, just render the content directly
+  if (frameworkBlocks.length === 0) {
+    return <div className="framework-content">{frameworkPanel}</div>
+  }
+
+  // If 1 code block, render minimal style
+  if (frameworkBlocks.length === 1) {
+    return <div className="framework-content">{frameworkPanel}</div>
+  }
+
+  // Multiple code blocks - show as file tabs
+  const tabs = frameworkBlocks.map((block, index) => ({
+    slug: `file-${index}`,
+    name: block.title || 'Untitled',
+  }))
+
+  const childrenArray = Children.toArray(frameworkPanel)
+
+  return (
+    <div className="framework-content">
+      <Tabs tabs={tabs}>{childrenArray}</Tabs>
+    </div>
+  )
+}

package/template/app/components/markdown/Markdown.tsx

@@ -0,0 +1,216 @@
+import type { HTMLProps } from 'react'
+import * as React from 'react'
+import { MarkdownLink } from './MarkdownLink'
+
+import parse, {
+  attributesToProps,
+  domToReact,
+  Element,
+  HTMLReactParserOptions,
+} from 'html-react-parser'
+
+import { CodeBlock } from './CodeBlock'
+import { handleTabsComponent } from './MarkdownTabsHandler'
+import { handleFrameworkComponent } from './MarkdownFrameworkHandler'
+import { InlineCode } from '../ui/InlineCode'
+import { MarkdownImg } from '../ui/MarkdownImg'
+import type { SiteConfig } from '~/types'
+
+type HeadingLevel = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'
+
+const CustomHeading = ({
+  Comp,
+  id,
+  children,
+  ...props
+}: HTMLProps<HTMLHeadingElement> & {
+  Comp: HeadingLevel
+}) => {
+  // Convert children to array and strip any inner anchor (native 'a' or MarkdownLink)
+  const childrenArray = React.Children.toArray(children)
+  const sanitizedChildren = childrenArray.map((child) => {
+    if (
+      React.isValidElement(child) &&
+      (child.type === 'a' || child.type === MarkdownLink)
+    ) {
+      // replace anchor child with its own children so outer anchor remains the only link
+      return (child.props as { children?: React.ReactNode }).children ?? null
+    }
+    return child
+  })
+
+  const heading = (
+    <Comp id={id} {...props}>
+      {sanitizedChildren}
+    </Comp>
+  )
+
+  if (id) {
+    return (
+      <a
+        href={`#${id}`}
+        className={`anchor-heading *:scroll-my-20 *:lg:scroll-my-4`}
+      >
+        {heading}
+      </a>
+    )
+  }
+
+  return heading
+}
+
+const makeHeading =
+  (type: HeadingLevel) => (props: HTMLProps<HTMLHeadingElement>) => (
+    <CustomHeading
+      Comp={type}
+      {...props}
+      className={`${props.className ?? ''} block`}
+    />
+  )
+
+const MarkdownIframe = React.memo(function MarkdownIframe(
+  props: HTMLProps<HTMLIFrameElement>,
+) {
+  return <iframe {...props} className="w-full" title="Embedded Content" />
+})
+
+const markdownComponents: Record<string, React.FC> = {
+  a: MarkdownLink,
+  pre: CodeBlock,
+  h1: makeHeading('h1'),
+  h2: makeHeading('h2'),
+  h3: makeHeading('h3'),
+  h4: makeHeading('h4'),
+  h5: makeHeading('h5'),
+  h6: makeHeading('h6'),
+  code: InlineCode,
+  iframe: MarkdownIframe,
+  img: MarkdownImg,
+}
+
+// Cache for lazily-loaded custom components keyed by component name
+const lazyComponentCache = new Map<string, React.LazyExoticComponent<React.ComponentType<any>>>()
+
+function getLazyComponent(
+  name: string,
+  loader: () => Promise<{ default: React.ComponentType<any> }>,
+): React.LazyExoticComponent<React.ComponentType<any>> {
+  let cached = lazyComponentCache.get(name)
+  if (!cached) {
+    cached = React.lazy(loader)
+    lazyComponentCache.set(name, cached)
+  }
+  return cached
+}
+
+function createParserOptions(
+  customComponents?: SiteConfig['components'],
+): HTMLReactParserOptions {
+  const options: HTMLReactParserOptions = {
+    replace: (domNode) => {
+      if (domNode instanceof Element && domNode.attribs) {
+        if (domNode.name === 'md-comment-component') {
+          const componentName = domNode.attribs['data-component']
+          const rawAttributes = domNode.attribs['data-attributes']
+          const attributes: Record<string, any> = {}
+          try {
+            Object.assign(attributes, JSON.parse(rawAttributes))
+          } catch {
+            // ignore JSON parse errors and fall back to empty props
+          }
+
+          switch (componentName?.toLowerCase()) {
+            case 'tabs':
+              return handleTabsComponent(domNode, attributes, options)
+            case 'framework':
+              return handleFrameworkComponent(domNode, attributes, options)
+            default: {
+              // Check custom components for md-comment-component with unknown data-component
+              if (componentName && customComponents?.[componentName]) {
+                const LazyComp = getLazyComponent(componentName, customComponents[componentName])
+                return (
+                  <React.Suspense fallback={<div />}>
+                    <LazyComp {...attributes}>
+                      {domToReact(domNode.children as any, options)}
+                    </LazyComp>
+                  </React.Suspense>
+                )
+              }
+              return <div>{domToReact(domNode.children as any, options)}</div>
+            }
+          }
+        }
+
+        // Check if an unknown HTML element matches a custom component
+        if (customComponents?.[domNode.name]) {
+          const LazyComp = getLazyComponent(domNode.name, customComponents[domNode.name])
+          return (
+            <React.Suspense fallback={<div />}>
+              <LazyComp {...attributesToProps(domNode.attribs)}>
+                {domToReact(domNode.children as any, options)}
+              </LazyComp>
+            </React.Suspense>
+          )
+        }
+
+        const replacer = markdownComponents[domNode.name]
+        if (replacer) {
+          return React.createElement(
+            replacer,
+            attributesToProps(domNode.attribs),
+            domToReact(domNode.children as any, options),
+          )
+        }
+      }
+
+      return
+    },
+  }
+  return options
+}
+
+// Default options (no custom components) for backward compatibility
+const defaultOptions = createParserOptions()
+
+type MarkdownProps = {
+  /** Raw markdown content -- will be rendered to HTML if provided */
+  rawContent?: string
+  /** Pre-rendered HTML markup. If not provided, rawContent will be used. */
+  htmlMarkup?: string
+  /** Optional render function for raw markdown to HTML. Must be provided if rawContent is used. */
+  renderMarkdown?: (raw: string) => { markup: string; headings: any[] }
+  /** Custom components from SiteConfig for lazy-loading unknown elements */
+  customComponents?: SiteConfig['components']
+}
+
+export const Markdown = React.memo(function Markdown({
+  rawContent,
+  htmlMarkup,
+  renderMarkdown,
+  customComponents,
+}: MarkdownProps) {
+  const rendered = React.useMemo(() => {
+    if (rawContent && renderMarkdown) {
+      return renderMarkdown(rawContent)
+    }
+
+    if (htmlMarkup) {
+      return { markup: htmlMarkup, headings: [] }
+    }
+
+    return { markup: '', headings: [] }
+  }, [rawContent, htmlMarkup, renderMarkdown])
+
+  const options = React.useMemo(
+    () => (customComponents ? createParserOptions(customComponents) : defaultOptions),
+    [customComponents],
+  )
+
+  return React.useMemo(() => {
+    if (!rendered.markup) {
+      return null
+    }
+
+    return parse(rendered.markup, options)
+  }, [rendered.markup, options])
+})