@acmekit/docs-app 2.13.43

package/src/__tests__/search-scoring.spec.ts

@@ -0,0 +1,144 @@
+import { describe, expect, it } from "vitest"
+
+/**
+ * Tests for the scoreEntry function from SearchModal.
+ * We extract the pure function logic here to test without React dependencies.
+ */
+
+// Replicate the pure function from SearchModal.tsx
+function scoreEntry(
+  entry: { title: string; description: string; body: string },
+  words: string[]
+): number {
+  let score = 0
+  const title = entry.title.toLowerCase()
+  const desc = entry.description.toLowerCase()
+  const body = entry.body.toLowerCase()
+
+  for (const word of words) {
+    if (title.includes(word)) score += 3
+    if (desc.includes(word)) score += 2
+    if (body.includes(word)) score += 1
+  }
+
+  return score
+}
+
+describe("scoreEntry", () => {
+  it("should return 0 for no matching words", () => {
+    const entry = {
+      title: "Getting Started",
+      description: "How to get started",
+      body: "Follow these steps",
+    }
+    expect(scoreEntry(entry, ["unrelated"])).toBe(0)
+  })
+
+  it("should score 3 points for title match", () => {
+    const entry = {
+      title: "Authentication Guide",
+      description: "",
+      body: "",
+    }
+    expect(scoreEntry(entry, ["authentication"])).toBe(3)
+  })
+
+  it("should score 2 points for description match", () => {
+    const entry = {
+      title: "Guide",
+      description: "How to configure authentication",
+      body: "",
+    }
+    expect(scoreEntry(entry, ["authentication"])).toBe(2)
+  })
+
+  it("should score 1 point for body match", () => {
+    const entry = {
+      title: "Guide",
+      description: "A guide",
+      body: "Set up authentication in your project",
+    }
+    expect(scoreEntry(entry, ["authentication"])).toBe(1)
+  })
+
+  it("should accumulate scores across all fields", () => {
+    const entry = {
+      title: "auth setup",
+      description: "Configure auth for your app",
+      body: "Auth is important for security",
+    }
+    // "auth" matches title (3) + description (2) + body (1) = 6
+    expect(scoreEntry(entry, ["auth"])).toBe(6)
+  })
+
+  it("should accumulate scores across multiple words", () => {
+    const entry = {
+      title: "Authentication Guide",
+      description: "Setup steps",
+      body: "Follow the guide",
+    }
+    // "authentication" in title (3), "guide" in title (3) + body (1) = 7
+    expect(scoreEntry(entry, ["authentication", "guide"])).toBe(7)
+  })
+
+  it("should be case insensitive", () => {
+    const entry = {
+      title: "Getting Started",
+      description: "QUICK START",
+      body: "Start here",
+    }
+    expect(scoreEntry(entry, ["start"])).toBeGreaterThan(0)
+    expect(scoreEntry(entry, ["START"])).toBe(0) // words should be lowercased by caller
+    expect(scoreEntry(entry, ["getting"])).toBe(3)
+  })
+
+  it("should handle empty words array", () => {
+    const entry = {
+      title: "Test",
+      description: "Test",
+      body: "Test",
+    }
+    expect(scoreEntry(entry, [])).toBe(0)
+  })
+
+  it("should handle empty entry fields", () => {
+    const entry = {
+      title: "",
+      description: "",
+      body: "",
+    }
+    expect(scoreEntry(entry, ["test"])).toBe(0)
+  })
+
+  it("should match partial words (substring matching)", () => {
+    const entry = {
+      title: "Authentication",
+      description: "",
+      body: "",
+    }
+    // "auth" is a substring of "authentication"
+    expect(scoreEntry(entry, ["auth"])).toBe(3)
+  })
+
+  it("should weight title higher than description higher than body", () => {
+    // Same word appearing only in title vs only in description vs only in body
+    const titleOnly = scoreEntry(
+      { title: "test", description: "other", body: "other" },
+      ["test"]
+    )
+    const descOnly = scoreEntry(
+      { title: "other", description: "test", body: "other" },
+      ["test"]
+    )
+    const bodyOnly = scoreEntry(
+      { title: "other", description: "other", body: "test" },
+      ["test"]
+    )
+
+    expect(titleOnly).toBe(3)
+    expect(descOnly).toBe(2)
+    expect(bodyOnly).toBe(1)
+    expect(titleOnly).toBeGreaterThan(descOnly)
+    expect(descOnly).toBeGreaterThan(bodyOnly)
+  })
+})

package/src/components/DocPage.tsx

@@ -0,0 +1,31 @@
+import React, { useEffect, useRef } from "react"
+import { useLocation } from "react-router-dom"
+import { useSiteConfig } from "@acmekit/docs-ui"
+import { MDXContent } from "./MDXContent"
+
+type DocPageProps = {
+  children: React.ReactNode
+  frontmatter?: Record<string, any>
+}
+
+export function DocPage({ children, frontmatter }: DocPageProps) {
+  const { setFrontmatter, setToc } = useSiteConfig()
+  const location = useLocation()
+  const articleRef = useRef<HTMLElement>(null)
+
+  // Set frontmatter on route change
+  useEffect(() => {
+    setFrontmatter({
+      ...frontmatter,
+      generate_toc: true,
+    })
+    // Reset TOC so it regenerates for the new page
+    setToc([])
+  }, [location.pathname, frontmatter])
+
+  return (
+    <article ref={articleRef}>
+      <MDXContent>{children}</MDXContent>
+    </article>
+  )
+}

package/src/components/HomePage.tsx

@@ -0,0 +1,139 @@
+import React, { Suspense } from "react"
+import { Link } from "react-router-dom"
+import { Loading } from "@acmekit/docs-ui"
+import { config } from "virtual:acmekit/docs-config"
+import { routes, components } from "virtual:acmekit/docs-routes"
+import { DocPage } from "./DocPage"
+
+export function HomePage() {
+  // Render the root index.mdx content if it exists
+  const rootRoute = routes.find((r: any) => r.path === "/")
+  const RootComponent = components["/"]
+
+  if (RootComponent) {
+    return (
+      <DocPage frontmatter={rootRoute?.frontmatter}>
+        <Suspense fallback={<Loading count={8} />}>
+          <RootComponent />
+        </Suspense>
+      </DocPage>
+    )
+  }
+
+  // Areas mode: show area cards + plugin cards
+  if (config.areas?.length) {
+    const plugins = config.plugins || []
+
+    return (
+      <div className="py-docs_2">
+        <h1 className="text-docs-h1 font-docs-heading text-acmekit-fg-base mb-docs_0.5">
+          {config.title}
+        </h1>
+        <p className="text-body-regular text-acmekit-fg-muted mb-docs_2">
+          Browse the documentation areas below.
+        </p>
+        <div className="grid gap-docs_1 sm:grid-cols-2 lg:grid-cols-3">
+          {config.areas.map((area: any) => {
+            const sidebar = config.sidebars?.find(
+              (s: any) => s.sidebar_id === area.sidebar_id
+            )
+            const count = sidebar?.items?.length ?? 0
+
+            return (
+              <Link
+                key={area.id}
+                to={`/${area.id}`}
+                className="group block rounded-docs_DEFAULT border border-acmekit-border-base bg-acmekit-bg-base p-docs_1.5 no-underline transition-all hover:shadow-elevation-card-hover dark:hover:shadow-elevation-card-hover-dark"
+              >
+                <h3 className="text-compact-medium-plus text-acmekit-fg-base mb-docs_0.25 group-hover:text-acmekit-fg-interactive">
+                  {area.title}
+                </h3>
+                <p className="text-compact-small text-acmekit-fg-muted">
+                  {count} {count === 1 ? "section" : "sections"}
+                </p>
+              </Link>
+            )
+          })}
+        </div>
+
+        {plugins.length > 0 && (
+          <>
+            <h2 className="text-docs-h2 font-docs-heading text-acmekit-fg-base mt-docs_2 mb-docs_1">
+              Plugins
+            </h2>
+            <div className="grid gap-docs_1 sm:grid-cols-2 lg:grid-cols-3">
+              {plugins.map((plugin: any) => {
+                const sidebar = config.sidebars?.find(
+                  (s: any) => s.sidebar_id === plugin.sidebar_id
+                )
+                const count = sidebar?.items?.length ?? 0
+
+                return (
+                  <Link
+                    key={plugin.slug}
+                    to={`/plugins/${plugin.slug}`}
+                    className="group block rounded-docs_DEFAULT border border-acmekit-border-base bg-acmekit-bg-base p-docs_1.5 no-underline transition-all hover:shadow-elevation-card-hover dark:hover:shadow-elevation-card-hover-dark"
+                  >
+                    <h3 className="text-compact-medium-plus text-acmekit-fg-base mb-docs_0.25 group-hover:text-acmekit-fg-interactive">
+                      {plugin.title}
+                    </h3>
+                    {plugin.description && (
+                      <p className="text-compact-small text-acmekit-fg-muted mb-docs_0.25">
+                        {plugin.description}
+                      </p>
+                    )}
+                    <p className="text-compact-small text-acmekit-fg-subtle">
+                      {count} {count === 1 ? "page" : "pages"}
+                    </p>
+                  </Link>
+                )
+              })}
+            </div>
+          </>
+        )}
+      </div>
+    )
+  }
+
+  // Fallback: show category cards
+  const categories = (config.sidebars?.[0]?.items || []).filter(
+    (item: any) => item.type === "category" && item.children?.length
+  )
+
+  return (
+    <div className="py-docs_2">
+      <h1 className="text-docs-h1 font-docs-heading text-acmekit-fg-base mb-docs_0.5">
+        {config.title}
+      </h1>
+      <p className="text-body-regular text-acmekit-fg-muted mb-docs_2">
+        Browse the documentation to get started.
+      </p>
+      {categories.length > 0 && (
+        <div className="grid gap-docs_1 sm:grid-cols-2 lg:grid-cols-3">
+          {categories.map((cat: any) => {
+            const firstLink = cat.children?.find(
+              (c: any) => c.type === "link" && c.path
+            )
+            const targetPath = firstLink?.path || "/"
+
+            return (
+              <Link
+                key={cat.title}
+                to={targetPath}
+                className="group block rounded-docs_DEFAULT border border-acmekit-border-base bg-acmekit-bg-base p-docs_1.5 no-underline transition-all hover:shadow-elevation-card-hover dark:hover:shadow-elevation-card-hover-dark"
+              >
+                <h3 className="text-compact-medium-plus text-acmekit-fg-base mb-docs_0.25 group-hover:text-acmekit-fg-interactive">
+                  {cat.title}
+                </h3>
+                <p className="text-compact-small text-acmekit-fg-muted">
+                  {cat.children?.length}{" "}
+                  {cat.children?.length === 1 ? "article" : "articles"}
+                </p>
+              </Link>
+            )
+          })}
+        </div>
+      )}
+    </div>
+  )
+}

package/src/components/Layout.tsx

@@ -0,0 +1,103 @@
+import React from "react"
+import { Outlet, useLocation } from "react-router-dom"
+import {
+  Sidebar,
+  MainNav,
+  ContentMenu,
+  Breadcrumbs,
+  Footer,
+  useIsBrowser,
+  useLayout,
+  useSidebar,
+  useSiteConfig,
+} from "@acmekit/docs-ui"
+import clsx from "clsx"
+
+export function Layout() {
+  const { isBrowser } = useIsBrowser()
+  const { desktopSidebarOpen, sidebars } = useSidebar()
+  const { mainContentRef, showCollapsedNavbar } = useLayout()
+  const { frontmatter } = useSiteConfig()
+  const { pathname } = useLocation()
+
+  const isAreasRoot = pathname === "/" && sidebars.length > 1
+
+  React.useEffect(() => {
+    if (!isBrowser) return
+    const rootLayout = document.getElementById("root-layout")
+    if (desktopSidebarOpen && !isAreasRoot) {
+      rootLayout?.classList.add("lg:grid-cols-[221px_1fr]")
+    } else {
+      rootLayout?.classList.remove("lg:grid-cols-[221px_1fr]")
+    }
+  }, [desktopSidebarOpen, isBrowser, isAreasRoot])
+
+  const showContentMenu = !frontmatter.hide_content_menu && !isAreasRoot
+
+  return (
+    <div
+      className={clsx(
+        "bg-acmekit-bg-subtle font-base text-medium w-full",
+        "text-acmekit-fg-base",
+        "h-full overflow-hidden",
+        "grid grid-cols-1 lg:mx-auto",
+        !isAreasRoot && "lg:grid-cols-[221px_1fr]"
+      )}
+      id="root-layout"
+    >
+      {!isAreasRoot && <Sidebar />}
+      <div className="relative h-screen flex">
+        <div
+          className={clsx(
+            "relative max-w-full",
+            "h-full flex-1",
+            "flex flex-col",
+            "gap-docs_0.5 lg:py-docs_0.25 lg:mr-docs_0.25 scroll-m-docs_0.25",
+            !desktopSidebarOpen && "lg:ml-docs_0.25"
+          )}
+        >
+          <div
+            className={clsx(
+              "bg-acmekit-bg-base",
+              "flex-col items-center",
+              "h-full w-full",
+              "overflow-y-scroll overflow-x-hidden",
+              "md:rounded-docs_DEFAULT",
+              "shadow-elevation-card-rest dark:shadow-elevation-card-rest-dark"
+            )}
+            id="main"
+            ref={mainContentRef}
+          >
+            <MainNav />
+            <div
+              className={clsx(
+                "pt-docs_4 lg:pt-docs_6 pb-docs_8 lg:pb-docs_4",
+                showContentMenu && "grid grid-cols-1 lg:mx-auto",
+                desktopSidebarOpen && showContentMenu && "lg:grid-cols-[1fr_221px]"
+              )}
+              id="content"
+            >
+              <div className="flex justify-center">
+                <div
+                  className={clsx(
+                    "w-full h-fit",
+                    "max-w-inner-content-xs sm:max-w-inner-content-sm",
+                    "md:max-w-inner-content-md lg:max-w-inner-content-lg",
+                    "xl:max-w-inner-content-xl xxl:max-w-inner-content-xxl",
+                    "xxxl:max-w-inner-content-xxxl",
+                    "px-docs_1 md:px-docs_4 lg:px-0"
+                  )}
+                >
+                  <Breadcrumbs />
+                  <Outlet />
+                  <Footer showPagination={true} />
+                </div>
+              </div>
+            </div>
+            {showContentMenu && <ContentMenu />}
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}

package/src/components/MDXContent.tsx

@@ -0,0 +1,11 @@
+import React from "react"
+import { MDXProvider } from "@mdx-js/react"
+import { MDXComponents } from "@acmekit/docs-ui"
+
+type MDXContentProps = {
+  children: React.ReactNode
+}
+
+export function MDXContent({ children }: MDXContentProps) {
+  return <MDXProvider components={MDXComponents}>{children}</MDXProvider>
+}

package/src/components/RouteErrorBoundary.tsx

@@ -0,0 +1,22 @@
+import React from "react"
+import { ErrorPage } from "@acmekit/docs-ui"
+
+type State = { hasError: boolean }
+
+export class RouteErrorBoundary extends React.Component<
+  { children: React.ReactNode },
+  State
+> {
+  state: State = { hasError: false }
+
+  static getDerivedStateFromError(): State {
+    return { hasError: true }
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return <ErrorPage />
+    }
+    return this.props.children
+  }
+}

package/src/components/SearchModal.tsx

@@ -0,0 +1,167 @@
+import React, { useCallback, useEffect, useRef, useState } from "react"
+import { useNavigate } from "react-router-dom"
+import { SearchInput, useSearch } from "@acmekit/docs-ui"
+import { searchIndex } from "virtual:acmekit/docs-search"
+
+type SearchResult = {
+  path: string
+  title: string
+  description: string
+  score: number
+}
+
+function scoreEntry(
+  entry: { title: string; description: string; body: string },
+  words: string[]
+): number {
+  let score = 0
+  const title = entry.title.toLowerCase()
+  const desc = entry.description.toLowerCase()
+  const body = entry.body.toLowerCase()
+
+  for (const word of words) {
+    if (title.includes(word)) score += 3
+    if (desc.includes(word)) score += 2
+    if (body.includes(word)) score += 1
+  }
+
+  return score
+}
+
+export function SearchModal() {
+  const { isOpen, setIsOpen, modalRef } = useSearch()
+  const [query, setQuery] = useState("")
+  const [activeIndex, setActiveIndex] = useState(0)
+  const navigate = useNavigate()
+  const searchWrapperRef = useRef<HTMLDivElement>(null)
+
+  const results: SearchResult[] = React.useMemo(() => {
+    if (!query.trim()) return []
+
+    const words = query
+      .toLowerCase()
+      .split(/\s+/)
+      .filter((w) => w.length > 0)
+
+    return searchIndex
+      .map((entry) => ({
+        path: entry.path,
+        title: entry.title,
+        description: entry.description,
+        score: scoreEntry(entry, words),
+      }))
+      .filter((r) => r.score > 0)
+      .sort((a, b) => b.score - a.score)
+      .slice(0, 20)
+  }, [query])
+
+  // Reset active index when results change
+  useEffect(() => {
+    setActiveIndex(0)
+  }, [results])
+
+  // Open/close via Cmd+K / Ctrl+K
+  useEffect(() => {
+    function onKeyDown(e: KeyboardEvent) {
+      if ((e.metaKey || e.ctrlKey) && e.key === "k") {
+        e.preventDefault()
+        setIsOpen((prev) => !prev)
+      }
+    }
+    document.addEventListener("keydown", onKeyDown)
+    return () => document.removeEventListener("keydown", onKeyDown)
+  }, [setIsOpen])
+
+  // Manage dialog open/close
+  useEffect(() => {
+    const dialog = modalRef.current
+    if (!dialog) return
+
+    if (isOpen) {
+      dialog.showModal()
+      searchWrapperRef.current?.querySelector<HTMLInputElement>("input")?.focus()
+    } else {
+      dialog.close()
+      setQuery("")
+    }
+  }, [isOpen, modalRef])
+
+  const navigateTo = useCallback(
+    (path: string) => {
+      navigate(path)
+      setIsOpen(false)
+    },
+    [navigate, setIsOpen]
+  )
+
+  function onKeyDown(e: React.KeyboardEvent) {
+    if (e.key === "ArrowDown") {
+      e.preventDefault()
+      setActiveIndex((i) => Math.min(i + 1, results.length - 1))
+    } else if (e.key === "ArrowUp") {
+      e.preventDefault()
+      setActiveIndex((i) => Math.max(i - 1, 0))
+    } else if (e.key === "Enter" && results[activeIndex]) {
+      e.preventDefault()
+      navigateTo(results[activeIndex].path)
+    }
+  }
+
+  return (
+    <dialog
+      ref={modalRef}
+      className="fixed inset-0 z-50 m-0 h-full w-full max-h-full max-w-full bg-transparent p-0 backdrop:bg-acmekit-bg-overlay"
+      onClick={(e) => {
+        if (e.target === e.currentTarget) setIsOpen(false)
+      }}
+      onClose={() => setIsOpen(false)}
+    >
+      <div className="mx-auto mt-[15vh] w-full max-w-[540px] rounded-docs_DEFAULT border border-acmekit-border-base bg-acmekit-bg-base shadow-elevation-modal dark:shadow-elevation-modal-dark">
+        <div ref={searchWrapperRef} className="p-docs_1" onKeyDown={onKeyDown}>
+          <SearchInput
+            value={query}
+            onChange={setQuery}
+            placeholder="Search documentation..."
+            autoFocus
+          />
+        </div>
+
+        {results.length > 0 && (
+          <ul className="max-h-[50vh] overflow-y-auto border-t border-acmekit-border-base p-docs_0.5">
+            {results.map((result, i) => (
+              <li key={result.path}>
+                <button
+                  type="button"
+                  className={`w-full rounded-docs_sm px-docs_1 py-docs_0.5 text-left transition-colors ${
+                    i === activeIndex
+                      ? "bg-acmekit-bg-base-hover"
+                      : "hover:bg-acmekit-bg-base-hover"
+                  }`}
+                  onMouseEnter={() => setActiveIndex(i)}
+                  onClick={() => navigateTo(result.path)}
+                >
+                  <span className="text-compact-small-plus text-acmekit-fg-base block">
+                    {result.title}
+                  </span>
+                  {result.description && (
+                    <span className="text-compact-x-small text-acmekit-fg-muted block truncate">
+                      {result.description}
+                    </span>
+                  )}
+                </button>
+              </li>
+            ))}
+          </ul>
+        )}
+
+        {query.trim() && results.length === 0 && (
+          <div className="border-t border-acmekit-border-base p-docs_1 text-center">
+            <span className="text-compact-small text-acmekit-fg-muted">
+              No results found
+            </span>
+          </div>
+        )}
+      </div>
+    </dialog>
+  )
+}