docs-i18n 0.6.3 → 0.7.1

package/template/app/components/BlogList.tsx

@@ -0,0 +1,88 @@
+/**
+ * Blog post list component.
+ *
+ * Displays a responsive grid of blog post cards matching tanstack.com styling:
+ * - Header image (if present)
+ * - Title, author, date
+ * - Excerpt with line clamping
+ * - "Read More" link
+ */
+
+import { Link } from '@tanstack/react-router'
+import { Card } from '~/components/Card'
+import { format } from '~/utils/dates'
+import { formatAuthors } from '~/utils/blog'
+import type { BlogPostMeta } from '~/utils/blog'
+
+type BlogListProps = {
+  posts: BlogPostMeta[]
+  lang: string
+}
+
+export function BlogList({ posts, lang }: BlogListProps) {
+  if (posts.length === 0) {
+    return (
+      <div className="py-20 text-center">
+        <p className="text-lg text-gray-500 dark:text-gray-400">
+          No blog posts yet. Check back soon!
+        </p>
+      </div>
+    )
+  }
+
+  return (
+    <section className="grid grid-cols-1 md:grid-cols-2 2xl:grid-cols-3 gap-4">
+      {posts.map(
+        ({ slug, title, published, excerpt, headerImage, authors }) => {
+          return (
+            <Card
+              key={slug}
+              as={Link}
+              to={`/${lang}/blog/${slug}`}
+              className="relative flex flex-col justify-between overflow-hidden transition-all hover:shadow-sm hover:border-blue-500"
+            >
+              {headerImage ? (
+                <div className="aspect-video overflow-hidden bg-gray-100 dark:bg-gray-800">
+                  <img
+                    src={headerImage}
+                    alt=""
+                    loading="lazy"
+                    decoding="async"
+                    className="w-full h-full object-cover"
+                  />
+                </div>
+              ) : null}
+              <div className="p-4 md:p-8 flex flex-col gap-4 flex-1 justify-between">
+                <div>
+                  <div className="text-lg font-extrabold">{title}</div>
+                  <div className="text-xs italic font-light mt-1">
+                    by {formatAuthors(authors)}
+                    {published ? (
+                      <time
+                        dateTime={published}
+                        title={format(new Date(published), 'MMM d, yyyy')}
+                      >
+                        {' '}
+                        on {format(new Date(published), 'MMM d, yyyy')}
+                      </time>
+                    ) : null}
+                  </div>
+                  {excerpt ? (
+                    <p className="text-sm mt-4 text-gray-600 dark:text-gray-400 leading-7 line-clamp-4">
+                      {excerpt}
+                    </p>
+                  ) : null}
+                </div>
+                <div>
+                  <div className="text-blue-500 uppercase font-black text-sm">
+                    Read More
+                  </div>
+                </div>
+              </div>
+            </Card>
+          )
+        },
+      )}
+    </section>
+  )
+}

package/template/app/components/Breadcrumbs.tsx

@@ -0,0 +1,81 @@
+import { Link } from '@tanstack/react-router'
+import { ChevronDown } from 'lucide-react'
+import { twMerge } from 'tailwind-merge'
+import type { MarkdownHeading } from '~/types'
+import {
+  Dropdown,
+  DropdownTrigger,
+  DropdownContent,
+  DropdownItem,
+} from './Dropdown'
+
+type BreadcrumbsProps = {
+  /** Section label (e.g., "Getting Started", "Blog") */
+  section: string
+  /** Optional link for the section */
+  sectionTo?: string
+  headings?: MarkdownHeading[]
+  /** Breakpoint at which the TOC toggle is hidden (default: 'lg') */
+  tocHiddenBreakpoint?: 'md' | 'lg'
+}
+
+export function Breadcrumbs({
+  section,
+  sectionTo,
+  headings,
+  tocHiddenBreakpoint = 'lg',
+}: BreadcrumbsProps) {
+  const showTocToggle = headings && headings.length > 1
+  const hiddenClass = tocHiddenBreakpoint === 'md' ? 'md:hidden' : 'lg:hidden'
+
+  return (
+    <div className="flex flex-col">
+      <div className="flex items-center justify-between gap-4 text-sm text-gray-500 dark:text-gray-400">
+        {sectionTo ? (
+          <Link
+            to={sectionTo}
+            className="whitespace-nowrap hover:text-gray-700 dark:hover:text-gray-200 transition-colors"
+          >
+            {section}
+          </Link>
+        ) : (
+          <span className="whitespace-nowrap">{section}</span>
+        )}
+        {showTocToggle && (
+          <Dropdown>
+            <DropdownTrigger>
+              <button
+                className={twMerge(
+                  hiddenClass,
+                  'whitespace-nowrap inline-flex items-center gap-1 text-gray-500 dark:text-gray-400 hover:text-gray-700 dark:hover:text-gray-200 transition-colors cursor-pointer',
+                )}
+              >
+                <span>On this page</span>
+                <ChevronDown className="w-3.5 h-3.5" />
+              </button>
+            </DropdownTrigger>
+            <DropdownContent align="end" sideOffset={8} className={hiddenClass}>
+              {headings.map((heading) => (
+                <DropdownItem key={`breadcrumb-toc-${heading.id}`} asChild>
+                  <Link
+                    to="."
+                    hash={heading.id}
+                    style={{
+                      paddingLeft: `${(heading.level - 2) * 0.5 + 0.5}rem`,
+                    }}
+                    resetScroll={false}
+                    hashScrollIntoView={{
+                      behavior: 'smooth',
+                    }}
+                  >
+                    <span dangerouslySetInnerHTML={{ __html: heading.text }} />
+                  </Link>
+                </DropdownItem>
+              ))}
+            </DropdownContent>
+          </Dropdown>
+        )}
+      </div>
+    </div>
+  )
+}

package/template/app/components/Card.tsx

@@ -0,0 +1,31 @@
+import * as React from 'react'
+import { twMerge } from 'tailwind-merge'
+
+type CardOwnProps<TElement extends React.ElementType = 'div'> = {
+  as?: TElement
+  children: React.ReactNode
+  className?: string
+}
+
+type CardProps<TElement extends React.ElementType = 'div'> =
+  CardOwnProps<TElement> &
+    Omit<React.ComponentPropsWithoutRef<TElement>, keyof CardOwnProps<TElement>>
+
+type CardComponent = <TElement extends React.ElementType = 'div'>(
+  props: CardProps<TElement>,
+) => React.ReactNode
+
+export const Card: CardComponent = ({ as, children, className, ...props }) => {
+  const Component = as || 'div'
+  return React.createElement(
+    Component,
+    {
+      className: twMerge(
+        'bg-white dark:bg-gray-900 rounded-lg shadow-md border border-gray-200 dark:border-gray-800',
+        className,
+      ),
+      ...props,
+    },
+    children,
+  )
+}

package/template/app/components/Doc.tsx

@@ -0,0 +1,191 @@
+import * as React from 'react'
+import { FoldHorizontal, UnfoldHorizontal } from 'lucide-react'
+import { twMerge } from 'tailwind-merge'
+import { useWidthToggle, DocNavigation } from '~/components/DocsLayout'
+
+import { Toc } from './Toc'
+import { renderMarkdown } from '~/utils/markdown'
+import { DocBreadcrumb } from './DocBreadcrumb'
+import { FallbackBanner } from './FallbackBanner'
+import { MarkdownContent } from '~/components/markdown'
+import type { DocsConfig, MarkdownHeading } from '~/types'
+import { useLocalCurrentFramework } from './FrameworkSelect'
+import { useParams } from '@tanstack/react-router'
+
+type DocProps = {
+  title: string
+  content: string
+  repo: string
+  branch: string
+  filePath: string
+  shouldRenderToc?: boolean
+  colorFrom?: string
+  colorTo?: string
+  textColor?: string
+  // Breadcrumb props (optional)
+  config?: DocsConfig
+  // Footer content rendered after markdown
+  footer?: React.ReactNode
+  // Optional framework to use (overrides URL and local storage)
+  framework?: string
+  // Whether the content is a fallback (untranslated)
+  isFallback?: boolean
+  // Locale display name for fallback banner
+  locale?: string
+}
+
+export function Doc({
+  title,
+  content,
+  repo,
+  branch,
+  filePath,
+  shouldRenderToc = true,
+  colorFrom,
+  colorTo,
+  textColor,
+  config,
+  footer,
+  framework: frameworkProp,
+  isFallback = false,
+  locale,
+}: DocProps) {
+  // Extract headings synchronously during render to avoid hydration mismatch
+  const { headings, markup } = React.useMemo(
+    () => renderMarkdown(content),
+    [content],
+  )
+
+  // Get current framework from prop, URL params, or local storage
+  const { framework: paramsFramework } = useParams({ strict: false })
+  const localCurrentFramework = useLocalCurrentFramework()
+  const currentFramework = React.useMemo(() => {
+    const fw =
+      frameworkProp ||
+      paramsFramework ||
+      localCurrentFramework.currentFramework ||
+      'react'
+    return typeof fw === 'string' ? fw.toLowerCase() : fw
+  }, [frameworkProp, paramsFramework, localCurrentFramework.currentFramework])
+
+  const isTocVisible = shouldRenderToc && headings.length > 1
+
+  const markdownContainerRef = React.useRef<HTMLDivElement>(null)
+  const [activeHeadings, setActiveHeadings] = React.useState<Array<string>>([])
+
+  const headingElementRefs = React.useRef<
+    Record<string, IntersectionObserverEntry>
+  >({})
+
+  // Try to get the width toggle context from DocsLayout
+  let isFullWidth = false
+  let setIsFullWidth: ((isFullWidth: boolean) => void) | undefined
+
+  try {
+    const context = useWidthToggle()
+    isFullWidth = context.isFullWidth
+    setIsFullWidth = context.setIsFullWidth
+  } catch {
+    // Context not available, that's okay
+  }
+
+  React.useEffect(() => {
+    const callback = (headingsList: Array<IntersectionObserverEntry>) => {
+      headingElementRefs.current = headingsList.reduce(
+        (map, headingElement) => {
+          map[headingElement.target.id] = headingElement
+          return map
+        },
+        headingElementRefs.current,
+      )
+
+      const visibleHeadings: Array<IntersectionObserverEntry> = []
+      Object.keys(headingElementRefs.current).forEach((key) => {
+        const headingElement = headingElementRefs.current[key]
+        if (headingElement.isIntersecting) {
+          visibleHeadings.push(headingElement)
+        }
+      })
+
+      if (visibleHeadings.length >= 1) {
+        setActiveHeadings(visibleHeadings.map((h) => h.target.id))
+      }
+    }
+
+    const observer = new IntersectionObserver(callback, {
+      rootMargin: '0px',
+      threshold: 0.2,
+    })
+
+    const headingElements = Array.from(
+      markdownContainerRef.current?.querySelectorAll(
+        'h2[id], h3[id], h4[id], h5[id], h6[id]',
+      ) ?? [],
+    )
+    headingElements.forEach((el) => observer.observe(el))
+
+    return () => observer.disconnect()
+  }, [headings])
+
+  return (
+    <div className="flex-1 min-h-0 flex flex-col pt-4 lg:pt-6 xl:pt-8">
+      {isFallback && locale && <FallbackBanner locale={locale} />}
+
+      <div
+        className={twMerge(
+          'w-full flex mx-auto max-w-[768px]',
+          (isTocVisible || isFullWidth) && 'max-w-full',
+        )}
+      >
+        <div className="flex flex-col w-full min-w-0">
+          {config && (
+            <div className="mb-3">
+              <DocBreadcrumb
+                config={config}
+                headings={isTocVisible ? headings : undefined}
+              />
+            </div>
+          )}
+          <MarkdownContent
+            title={title}
+            repo={repo}
+            branch={branch}
+            filePath={filePath}
+            htmlMarkup={markup}
+            containerRef={markdownContainerRef}
+            currentFramework={currentFramework}
+            titleBarActions={
+              setIsFullWidth ? (
+                <button
+                  onClick={() => setIsFullWidth(!isFullWidth)}
+                  className="p-2 mr-4 text-gray-600 hover:text-gray-800 dark:text-gray-400 dark:hover:text-gray-200 hover:bg-gray-100 dark:hover:bg-gray-700 rounded-lg transition-colors shrink-0 hidden [@media(min-width:1535px)]:inline-flex"
+                  title={isFullWidth ? 'Constrain width' : 'Expand width'}
+                >
+                  {isFullWidth ? (
+                    <FoldHorizontal className="w-4 h-4" />
+                  ) : (
+                    <UnfoldHorizontal className="w-4 h-4" />
+                  )}
+                </button>
+              ) : null
+            }
+          />
+          {footer ?? <DocNavigation />}
+        </div>
+
+        {isTocVisible && (
+          <div className="pl-4 w-32 lg:w-36 xl:w-44 2xl:w-56 3xl:w-64 shrink-0 hidden lg:block transition-all">
+            <Toc
+              headings={headings}
+              activeHeadings={activeHeadings}
+              colorFrom={colorFrom}
+              colorTo={colorTo}
+              textColor={textColor}
+              currentFramework={currentFramework}
+            />
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}

package/template/app/components/DocBreadcrumb.tsx

@@ -0,0 +1,60 @@
+import { useParams } from '@tanstack/react-router'
+import { Breadcrumbs } from './Breadcrumbs'
+import type { DocsConfig, MarkdownHeading } from '~/types'
+
+function findSectionForDoc(
+  config: DocsConfig,
+  docPath: string,
+): string | null {
+  for (const section of config.sections) {
+    // Check core docs
+    for (const child of section.children) {
+      if (child.to === docPath) {
+        return section.label
+      }
+    }
+
+    // Check framework-specific docs in all frameworks
+    if (section.frameworks) {
+      for (const frameworkSection of section.frameworks) {
+        for (const child of frameworkSection.children) {
+          if (child.to === docPath) {
+            return section.label
+          }
+        }
+      }
+    }
+  }
+
+  return null
+}
+
+export function DocBreadcrumb({
+  config,
+  headings,
+}: {
+  config: DocsConfig
+  headings?: MarkdownHeading[]
+}) {
+  const { _splat, framework } = useParams({ strict: false })
+
+  // Build the full doc path as it appears in config
+  // Config paths are like "overview" or "framework/react/overview"
+  const fullDocPath = framework ? `framework/${framework}/${_splat}` : _splat
+
+  // Find the section for this doc
+  const section = fullDocPath ? findSectionForDoc(config, fullDocPath) : null
+
+  // Only show if we found a section
+  if (!section) {
+    return null
+  }
+
+  return (
+    <Breadcrumbs
+      section={section}
+      headings={headings}
+      tocHiddenBreakpoint="lg"
+    />
+  )
+}

package/template/app/components/DocContainer.tsx

@@ -0,0 +1,13 @@
+import { HTMLProps } from 'react'
+import { twMerge } from 'tailwind-merge'
+
+export function DocContainer({
+  children,
+  ...props
+}: { children: React.ReactNode } & HTMLProps<HTMLDivElement>) {
+  return (
+    <div {...props} className={twMerge('w-full max-w-full', props.className)}>
+      {children}
+    </div>
+  )
+}

package/template/app/components/DocTitle.tsx

@@ -0,0 +1,11 @@
+export function DocTitle(props: { children: React.ReactNode }) {
+  return (
+    <>
+      <h1
+        className={`flex gap-4 items-center flex-wrap text-xl md:text-2xl font-black`}
+      >
+        {props.children}
+      </h1>
+    </>
+  )
+}