docs-i18n 0.6.2 → 0.7.0

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

@@ -0,0 +1,89 @@
+import * as React from 'react'
+import { SquarePen } from 'lucide-react'
+import { twMerge } from 'tailwind-merge'
+import { Markdown } from './Markdown'
+import { Button } from '../ui/Button'
+
+type MarkdownContentProps = {
+  title: string
+  repo: string
+  branch: string
+  filePath: string
+  /** Pre-rendered HTML markup (from renderMarkdown). If not provided, rawContent will be rendered. */
+  htmlMarkup?: string
+  /** Raw markdown content to render. Used if htmlMarkup is not provided. */
+  rawContent?: string
+  /** Optional render function for raw markdown to HTML */
+  renderMarkdown?: (raw: string) => { markup: string; headings: any[] }
+  /** Additional elements to render in the title bar (e.g., width toggle button) */
+  titleBarActions?: React.ReactNode
+  /** Additional class names for the prose container */
+  proseClassName?: string
+  /** Ref for the markdown container (used for heading intersection observer in docs) */
+  containerRef?: React.RefObject<HTMLDivElement | null>
+  /** Current framework for filtering markdown content */
+  currentFramework?: string
+}
+
+export function MarkdownContent({
+  title,
+  repo,
+  branch,
+  filePath,
+  htmlMarkup,
+  rawContent,
+  renderMarkdown,
+  titleBarActions,
+  proseClassName,
+  containerRef,
+}: MarkdownContentProps) {
+  const markdownElement = htmlMarkup ? (
+    <Markdown htmlMarkup={htmlMarkup} />
+  ) : rawContent ? (
+    <Markdown rawContent={rawContent} renderMarkdown={renderMarkdown} />
+  ) : null
+
+  return (
+    <>
+      {title ? (
+        <div className="flex flex-wrap items-center justify-between gap-2">
+          <h1
+            className={`flex gap-4 items-center flex-wrap text-xl md:text-2xl font-black`}
+          >
+            {title}
+          </h1>
+          <div className="flex items-center gap-2 shrink-0">
+            {titleBarActions}
+          </div>
+        </div>
+      ) : null}
+      <div className="h-4" />
+      <div className="h-px bg-gray-500 opacity-20" />
+      <div className="h-4" />
+      <div
+        ref={containerRef}
+        className={twMerge(
+          'prose prose-gray dark:prose-invert max-w-none',
+          '[font-size:16px]',
+          'styled-markdown-content',
+          proseClassName,
+        )}
+      >
+        {markdownElement}
+      </div>
+      <div className="h-12" />
+      <div className="w-full h-px bg-gray-500 opacity-30" />
+      <div className="flex py-4">
+        <Button
+          variant="ghost"
+          size="xs"
+          as="a"
+          href={`https://github.com/${repo}/edit/${branch}/${filePath}`}
+        >
+          <SquarePen className="w-3.5 h-3.5" />
+          Edit on GitHub
+        </Button>
+      </div>
+    </>
+  )
+}

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

@@ -0,0 +1,66 @@
+import * as React from 'react'
+import { domToReact, Element } from 'html-react-parser'
+import type { HTMLReactParserOptions } from 'html-react-parser'
+
+// Helper to resolve different module shapes (named export vs default)
+function resolveModuleDefault(mod: any, key: string): React.ComponentType<any> {
+  if (!mod) return undefined as any
+  if (mod[key] && typeof mod[key] === 'function') return mod[key]
+  if (mod.default) {
+    if (mod.default[key] && typeof mod.default[key] === 'function')
+      return mod.default[key]
+    if (typeof mod.default === 'function') return mod.default
+  }
+  if (typeof mod === 'function') return mod
+  return (mod as any).default ?? (mod as any)
+}
+
+const FrameworkContent = React.lazy<React.ComponentType<any>>(() =>
+  import('./FrameworkContent').then((mod) => ({
+    default: resolveModuleDefault(mod, 'FrameworkContent'),
+  })),
+)
+
+export function handleFrameworkComponent(
+  domNode: Element,
+  attributes: Record<string, any>,
+  options: HTMLReactParserOptions,
+) {
+  const frameworkMeta = domNode.attribs['data-framework-meta']
+  if (!frameworkMeta) {
+    return null
+  }
+
+  try {
+    const { codeBlocksByFramework } = JSON.parse(frameworkMeta)
+    const availableFrameworks = JSON.parse(
+      domNode.attribs['data-available-frameworks'] || '[]',
+    )
+
+    const panelElements = domNode.children?.filter(
+      (child): child is Element =>
+        child instanceof Element && child.name === 'md-framework-panel',
+    )
+
+    // Build panelsByFramework map
+    const panelsByFramework: Record<string, React.ReactNode> = {}
+    panelElements?.forEach((panel) => {
+      const fw = panel.attribs['data-framework']
+      if (fw) {
+        panelsByFramework[fw] = domToReact(panel.children as any, options)
+      }
+    })
+
+    return (
+      <React.Suspense fallback={<div>Loading...</div>}>
+        <FrameworkContent
+          codeBlocksByFramework={codeBlocksByFramework}
+          availableFrameworks={availableFrameworks}
+          panelsByFramework={panelsByFramework}
+        />
+      </React.Suspense>
+    )
+  } catch {
+    return null
+  }
+}

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

@@ -0,0 +1,35 @@
+import * as React from 'react'
+
+export type MarkdownHeading = {
+  depth: number
+  slug: string
+  text: string
+}
+
+const MarkdownHeadingContext = React.createContext<{
+  headings: MarkdownHeading[]
+  setHeadings(headings: MarkdownHeading[]): void
+}>({
+  headings: [],
+  setHeadings: () => undefined,
+})
+
+export function MarkdownHeadingProvider({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  const [headings, setHeadings] = React.useState<MarkdownHeading[]>([])
+
+  const value = React.useMemo(() => ({ headings, setHeadings }), [headings])
+
+  return (
+    <MarkdownHeadingContext.Provider value={value}>
+      {children}
+    </MarkdownHeadingContext.Provider>
+  )
+}
+
+export function useMarkdownHeadings() {
+  return React.useContext(MarkdownHeadingContext)
+}

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

@@ -0,0 +1,46 @@
+import { Link } from '@tanstack/react-router'
+import type { HTMLProps } from 'react'
+
+function isRelativeLink(link: string) {
+  return (
+    !link.startsWith(`/`) &&
+    !link.startsWith('http://') &&
+    !link.startsWith('https://') &&
+    !link.startsWith('//') &&
+    !link.startsWith('#') &&
+    !link.startsWith('mailto:')
+  )
+}
+
+export function MarkdownLink({
+  href: hrefProp,
+  ...rest
+}: HTMLProps<HTMLAnchorElement>) {
+  if (!isRelativeLink(hrefProp ?? '')) {
+    // eslint-disable-next-line jsx-a11y/anchor-has-content
+    return <a {...rest} href={hrefProp} />
+  }
+
+  const [hrefWithoutHash, hash] = hrefProp?.split('#') ?? []
+  let hrefWithoutMd = hrefWithoutHash.replace('.md', '')
+
+  // Force relative links to resolve one level higher
+  if (hrefWithoutMd.startsWith('../')) {
+    hrefWithoutMd = hrefWithoutMd.replace(/^\.\.\//gm, '../../')
+  } else if (hrefWithoutMd.startsWith('./')) {
+    hrefWithoutMd = hrefWithoutMd.replace(/^\.\//gm, '../')
+  } else {
+    hrefWithoutMd = `../${hrefWithoutMd}`
+  }
+
+  return (
+    <Link
+      {...rest}
+      unsafeRelative="path"
+      to={hrefWithoutMd}
+      hash={hash}
+      preload={undefined}
+      ref={undefined}
+    />
+  )
+}

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

@@ -0,0 +1,109 @@
+import * as React from 'react'
+import { domToReact, Element } from 'html-react-parser'
+import type { HTMLReactParserOptions } from 'html-react-parser'
+
+// Helper to resolve different module shapes (named export vs default)
+function resolveModuleDefault(mod: any, key: string): React.ComponentType<any> {
+  if (!mod) return undefined as any
+  if (mod[key] && typeof mod[key] === 'function') return mod[key]
+  if (mod.default) {
+    if (mod.default[key] && typeof mod.default[key] === 'function')
+      return mod.default[key]
+    if (typeof mod.default === 'function') return mod.default
+  }
+  if (typeof mod === 'function') return mod
+  return (mod as any).default ?? (mod as any)
+}
+
+const Tabs = React.lazy<React.ComponentType<any>>(() =>
+  import('./Tabs').then((mod) => ({
+    default: resolveModuleDefault(mod, 'Tabs'),
+  })),
+)
+const PackageManagerTabs = React.lazy<React.ComponentType<any>>(() =>
+  import('./PackageManagerTabs').then((mod) => ({
+    default: resolveModuleDefault(mod, 'PackageManagerTabs'),
+  })),
+)
+const FileTabs = React.lazy<React.ComponentType<any>>(() =>
+  import('./FileTabs').then((mod) => ({
+    default: resolveModuleDefault(mod, 'FileTabs'),
+  })),
+)
+
+export function handleTabsComponent(
+  domNode: Element,
+  attributes: Record<string, any>,
+  options: HTMLReactParserOptions,
+) {
+  const pmMeta = domNode.attribs['data-package-manager-meta']
+
+  // Handle package-manager variant
+  if (pmMeta) {
+    try {
+      const { packagesByFramework, mode } = JSON.parse(pmMeta)
+      const frameworks = Object.keys(packagesByFramework)
+
+      return (
+        <React.Suspense fallback={<div>Loading...</div>}>
+          <PackageManagerTabs
+            packagesByFramework={packagesByFramework}
+            mode={mode}
+            frameworks={frameworks}
+          />
+        </React.Suspense>
+      )
+    } catch {
+      // Fall through to default tabs if parsing fails
+    }
+  }
+
+  // Check if this is files variant
+  const filesMeta = domNode.attribs['data-files-meta']
+  if (filesMeta) {
+    try {
+      const tabs = attributes.tabs || []
+
+      const panelElements = domNode.children?.filter(
+        (child): child is Element =>
+          child instanceof Element && child.name === 'md-tab-panel',
+      )
+
+      const children = panelElements?.map((panel) =>
+        domToReact(panel.children as any, options),
+      )
+
+      return (
+        <React.Suspense fallback={<div>Loading...</div>}>
+          <FileTabs tabs={tabs} children={children as any} />
+        </React.Suspense>
+      )
+    } catch {
+      // Fall through to default tabs if parsing fails
+    }
+  }
+
+  // Handle default tabs variant
+  const tabs = attributes.tabs
+
+  if (!tabs || !Array.isArray(tabs)) {
+    return null
+  }
+
+  const panelElements = domNode.children?.filter(
+    (child): child is Element =>
+      child instanceof Element && child.name === 'md-tab-panel',
+  )
+
+  const children = panelElements?.map((panel) => {
+    const result = domToReact(panel.children as any, options)
+    // Wrap in fragment to ensure it's a single React node
+    return <>{result}</>
+  })
+
+  return (
+    <React.Suspense fallback={<div>Loading...</div>}>
+      <Tabs tabs={tabs} children={children as any} />
+    </React.Suspense>
+  )
+}

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

@@ -0,0 +1,95 @@
+import { useParams } from '@tanstack/react-router'
+import { create } from 'zustand'
+import { Tabs, type TabDefinition } from './Tabs'
+import { CodeBlock } from './CodeBlock'
+import {
+  getInstallCommand,
+  PACKAGE_MANAGERS,
+  type PackageManager,
+  type InstallMode,
+} from '../../utils/markdown/installCommand'
+
+// Use zustand for cross-component synchronization
+// This ensures all PackageManagerTabs instances on the page stay in sync
+const usePackageManagerStore = create<{
+  packageManager: PackageManager
+  setPackageManager: (pm: PackageManager) => void
+}>((set) => ({
+  packageManager:
+    typeof document !== 'undefined'
+      ? (localStorage.getItem('packageManager') as PackageManager) || 'npm'
+      : 'npm',
+  setPackageManager: (pm: PackageManager) => {
+    localStorage.setItem('packageManager', pm)
+    set({ packageManager: pm })
+  },
+}))
+
+// Simple localStorage-based framework preference (replaces useCurrentUserQuery auth dependency)
+function useLocalFrameworkPreference(): string | undefined {
+  if (typeof document === 'undefined') return undefined
+  return localStorage.getItem('framework') || undefined
+}
+
+type PackageManagerTabsProps = {
+  packagesByFramework: Record<string, string[][]>
+  mode: InstallMode
+  frameworks: string[]
+}
+
+export function PackageManagerTabs({
+  packagesByFramework,
+  mode,
+}: PackageManagerTabsProps) {
+  const { packageManager: storedPackageManager, setPackageManager } =
+    usePackageManagerStore()
+
+  const { framework: paramsFramework } = useParams({ strict: false })
+  const localFramework = useLocalFrameworkPreference()
+
+  const actualFramework = (paramsFramework ||
+    localFramework ||
+    'react') as string
+
+  const normalizedFramework = actualFramework.toLowerCase()
+  const packageGroups = packagesByFramework[normalizedFramework]
+
+  // Hide component if current framework not in package list
+  if (!packageGroups || packageGroups.length === 0) {
+    return null
+  }
+
+  // Use stored package manager if valid, otherwise default to first one
+  const selectedPackageManager = PACKAGE_MANAGERS.includes(storedPackageManager)
+    ? storedPackageManager
+    : PACKAGE_MANAGERS[0]
+
+  // Generate tabs for each package manager
+  const tabs: TabDefinition[] = PACKAGE_MANAGERS.map((pm) => ({
+    slug: pm,
+    name: pm,
+    headers: [],
+  }))
+
+  // Generate children (command blocks) for each package manager
+  const children = PACKAGE_MANAGERS.map((pm) => {
+    const commands = getInstallCommand(pm, packageGroups, mode)
+    const commandText = commands.join('\n')
+    return (
+      <CodeBlock key={pm}>
+        <code className="language-bash">{commandText}</code>
+      </CodeBlock>
+    )
+  })
+
+  return (
+    <div className="package-manager-tabs">
+      <Tabs
+        tabs={tabs}
+        children={children}
+        activeSlug={selectedPackageManager}
+        onTabChange={(slug) => setPackageManager(slug as PackageManager)}
+      />
+    </div>
+  )
+}

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

@@ -0,0 +1,139 @@
+import { useParams } from '@tanstack/react-router'
+import * as React from 'react'
+
+export type FrameworkOption = {
+  label: string
+  value: string
+  logo: string
+  color: string
+  fontColor: string
+}
+
+export type TabDefinition = {
+  slug: string
+  name: string
+  headers?: Array<string>
+}
+
+export type TabsProps = {
+  tabs?: Array<TabDefinition>
+  children?: Array<React.ReactNode> | React.ReactNode
+  activeSlug?: string
+  onTabChange?: (slug: string) => void
+  /** Optional framework options for showing logos in tab buttons */
+  frameworkOptions?: FrameworkOption[]
+}
+
+export function Tabs({
+  tabs: tabsProp = [],
+  children: childrenProp,
+  activeSlug: controlledActiveSlug,
+  onTabChange,
+  frameworkOptions = [],
+}: TabsProps) {
+  const id = React.useId()
+  const childrenArray = React.Children.toArray(childrenProp)
+
+  const params = useParams({ strict: false })
+  const framework = params?.framework ?? undefined
+
+  const [internalActiveSlug, setInternalActiveSlug] = React.useState(() => {
+    const match = framework
+      ? tabsProp.find((tab) => tab.slug === framework)
+      : undefined
+    return match?.slug ?? tabsProp[0]?.slug ?? ''
+  })
+
+  const activeSlug = controlledActiveSlug ?? internalActiveSlug
+  const setActiveSlug = React.useCallback(
+    (slug: string) => {
+      if (onTabChange) {
+        onTabChange(slug)
+      } else {
+        setInternalActiveSlug(slug)
+      }
+    },
+    [onTabChange],
+  )
+
+  if (tabsProp.length === 0) return null
+
+  return (
+    <div className="my-4">
+      <div className="not-prose flex items-center justify-start gap-2 rounded-t-md border-1 border-b-none border-gray-200 dark:border-gray-800 overflow-x-auto overflow-y-hidden bg-white dark:bg-gray-950">
+        {tabsProp.map((tab) => {
+          return (
+            <Tab
+              key={`${id}-${tab.slug}`}
+              id={id}
+              tab={tab}
+              activeSlug={activeSlug}
+              setActiveSlug={setActiveSlug}
+              frameworkOptions={frameworkOptions}
+            />
+          )
+        })}
+      </div>
+      <div
+        className={`border border-gray-500/20 rounded-b-md bg-gray-100 dark:bg-gray-900`}
+      >
+        {childrenArray.map((child, index) => {
+          const tab = tabsProp[index]
+          if (!tab) return null
+          return (
+            <div
+              key={`${id}-${tab.slug}`}
+              data-tab={tab.slug}
+              hidden={tab.slug !== activeSlug}
+              className="max-w-none flex flex-col gap-2 text-base"
+            >
+              {child}
+            </div>
+          )
+        })}
+      </div>
+    </div>
+  )
+}
+
+const Tab = React.memo(
+  ({
+    tab,
+    activeSlug,
+    setActiveSlug,
+    frameworkOptions = [],
+  }: {
+    id?: string
+    tab: TabDefinition
+    activeSlug: string
+    setActiveSlug: (slug: string) => void
+    frameworkOptions?: FrameworkOption[]
+  }) => {
+    const option = React.useMemo(
+      () =>
+        frameworkOptions.find(
+          (o) =>
+            o.value === tab.slug.toLowerCase() ||
+            o.label.toLowerCase() === tab.name.toLowerCase(),
+        ),
+      [tab.slug, tab.name, frameworkOptions],
+    )
+
+    return (
+      <button
+        aria-label={tab.name}
+        title={tab.name}
+        type="button"
+        onClick={() => setActiveSlug(tab.slug)}
+        className={`inline-flex items-center justify-center gap-2 px-3 py-1.5 -mb-[1px] border-b-2 text-sm font-bold transition-colors hover:bg-gray-100 dark:hover:bg-gray-800 rounded-t-md overflow-y-none ${
+          activeSlug === tab.slug
+            ? 'border-current text-current bg-gray-100 dark:bg-gray-900'
+            : 'border-transparent text-gray-600 hover:text-gray-900 dark:text-gray-400 dark:hover:text-gray-200'
+        }`}
+      >
+        {option && <img src={option.logo} alt="" className="w-4 h-4 -ml-1" />}
+        <span>{tab.name}</span>
+      </button>
+    )
+  },
+)

package/template/app/components/markdown/index.ts

@@ -0,0 +1,15 @@
+export { CodeBlock } from './CodeBlock'
+export { Markdown } from './Markdown'
+export { MarkdownContent } from './MarkdownContent'
+export { MarkdownLink } from './MarkdownLink'
+export { Tabs, type TabDefinition, type TabsProps, type FrameworkOption } from './Tabs'
+export { FileTabs, type FileTabDefinition, type FileTabsProps } from './FileTabs'
+export { PackageManagerTabs } from './PackageManagerTabs'
+export { FrameworkContent } from './FrameworkContent'
+export { handleTabsComponent } from './MarkdownTabsHandler'
+export { handleFrameworkComponent } from './MarkdownFrameworkHandler'
+export {
+  MarkdownHeadingProvider,
+  useMarkdownHeadings,
+  type MarkdownHeading,
+} from './MarkdownHeadingContext'