fix: improve docs navigation and search UX

Author: 0xharkirat

content/navigation-bar/docs-navigation-bar.json

@@ -9,6 +9,7 @@
           "title": "Introduction",
           "items": [
             {
+              "title": "Documentation",
               "slug": "content/docs/index.mdx",
               "_template": "item"
             }
@@ -18,18 +19,22 @@
           "title": "OACP Protocol",
           "items": [
             {
+              "title": "What is OACP?",
               "slug": "content/docs/oacp/what-is-oacp.mdx",
               "_template": "item"
             },
             {
+              "title": "How OACP Works",
               "slug": "content/docs/oacp/how-it-works.mdx",
               "_template": "item"
             },
             {
+              "title": "Getting Started",
               "slug": "content/docs/oacp/getting-started.mdx",
               "_template": "item"
             },
             {
+              "title": "OACP Integration",
               "slug": "content/docs/oacp/non-flutter-integration.mdx",
               "_template": "item"
             }
@@ -39,14 +44,17 @@
           "title": "Hark",
           "items": [
             {
+              "title": "Hark Overview",
               "slug": "content/docs/hark/overview.mdx",
               "_template": "item"
             },
             {
+              "title": "Architecture",
               "slug": "content/docs/hark/architecture.mdx",
               "_template": "item"
             },
             {
+              "title": "OACP Test App Demo",
               "slug": "content/docs/hark/demo-walkthrough.mdx",
               "_template": "item"
             }
@@ -59,18 +67,22 @@
               "title": "Kotlin SDK",
               "items": [
                 {
+                  "title": "Quick Start",
                   "slug": "content/docs/sdks/kotlin/quick-start.mdx",
                   "_template": "item"
                 },
                 {
+                  "title": "Core Components",
                   "slug": "content/docs/sdks/kotlin/core-components.mdx",
                   "_template": "item"
                 },
                 {
+                  "title": "Async Results",
                   "slug": "content/docs/sdks/kotlin/async-results.mdx",
                   "_template": "item"
                 },
                 {
+                  "title": "API Reference",
                   "slug": "content/docs/sdks/kotlin/api-reference.mdx",
                   "_template": "item"
                 }
@@ -81,6 +93,7 @@
               "title": "Flutter SDK (under development)",
               "items": [
                 {
+                  "title": "Under development",
                   "slug": "content/docs/sdks/flutter/overview.mdx",
                   "_template": "item"
                 }
@@ -91,6 +104,7 @@
               "title": "React Native SDK (under development)",
               "items": [
                 {
+                  "title": "Under development",
                   "slug": "content/docs/sdks/react-native/overview.mdx",
                   "_template": "item"
                 }
@@ -103,6 +117,7 @@
           "title": "Roadmap",
           "items": [
             {
+              "title": "Roadmap",
               "slug": "content/docs/roadmap.mdx",
               "_template": "item"
             }

src/app/docs/layout.tsx

@@ -1,13 +1,19 @@
 import { TabsLayout } from "@/components/docs/layout/tab-layout";
 import navigationBar from "@/content/navigation-bar/docs-navigation-bar.json";
+import { enrichNavigationBar } from "@/utils/docs/navigation/server-navigation";
 import type React from "react";
 
-export default function DocsLayout({
+export default async function DocsLayout({
   children,
 }: {
   children: React.ReactNode;
 }) {
+  const enrichedNavigationBar = await enrichNavigationBar(navigationBar);
+
   return (
-    <TabsLayout props={{ children }} tinaProps={{ data: { navigationBar } }} />
+    <TabsLayout
+      props={{ children }}
+      tinaProps={{ data: { navigationBar: enrichedNavigationBar } }}
+    />
   );
 }

src/components/navigation/navigation-items/nav-level.tsx

@@ -24,11 +24,36 @@ const getEndpointSlug = (endpoint_slug: string | string[] | undefined) => {
   if (typeof endpoint_slug === "string") {
     return titleCase(endpoint_slug?.replace(/-/g, " "));
   }
-  return endpoint_slug.length === 1
-    ? titleCase(endpoint_slug[0]?.replace(/-/g, " "))
+  const validSlugs = endpoint_slug.filter(
+    (slug): slug is string => typeof slug === "string" && slug.length > 0
+  );
+  return validSlugs.length === 1
+    ? titleCase(validSlugs[0].replace(/-/g, " "))
     : "";
 };
 
+const formatAcronyms = (value: string) =>
+  value
+    .replace(/\bOacp\b/g, "OACP")
+    .replace(/\bSdk\b/g, "SDK")
+    .replace(/\bApi\b/g, "API")
+    .replace(/\bLlm\b/g, "LLM")
+    .replace(/\bNlu\b/g, "NLU");
+
+const getSlugTitle = (slug: unknown) => {
+  if (typeof slug !== "string" || slug.length === 0) return "";
+
+  const normalizedSlug = getUrl(slug).replace(/\/$/, "");
+  if (normalizedSlug === "/docs") {
+    return "Documentation";
+  }
+
+  const lastSegment = normalizedSlug.split("/").filter(Boolean).pop();
+  if (!lastSegment) return "";
+
+  return formatAcronyms(titleCase(lastSegment.replace(/-/g, " ")));
+};
+
 export const NavLevel: React.FC<NavLevelProps> = ({
   navListElem,
   categoryData,
@@ -43,6 +68,7 @@ export const NavLevel: React.FC<NavLevelProps> = ({
   // If there is only one endpoint slug, use it as the default title
   // This will be used only when endpoint title is not set
   const defaultTitle = getEndpointSlug(endpoint_slug);
+  const fallbackSlugTitle = getSlugTitle(categoryData.slug);
   const slug = getUrl(categoryData.slug).replace(/\/$/, "");
   const [expanded, setExpanded] = React.useState(
     matchActualTarget(slug || getUrl(categoryData.href), path) ||
@@ -181,6 +207,7 @@ export const NavLevel: React.FC<NavLevelProps> = ({
                 >
                   {categoryData.slug.title ||
                     categoryData.title ||
+                    fallbackSlugTitle ||
                     defaultTitle}
                 </span>
                 <ChevronRightIcon className="ml-2 flex-shrink-0 opacity-0 w-5 h-auto" />

src/components/search-docs/search-results.tsx

@@ -4,29 +4,34 @@ interface SearchResult {
   url: string;
   title: string;
   excerpt: string;
+  sectionPath: string[];
 }
 
 interface SearchResultsProps {
   results: SearchResult[];
   isLoading: boolean;
   searchTerm: string;
+  onSelect?: () => void;
 }
 
 const searchResultsContainer =
-  "absolute mt-2 p-4 z-10 py-2 max-h-[45vh] md:w-11/12 w-full mx-auto rounded-lg shadow-lg md:ml-2 left translate-x-1 overflow-y-auto bg-neutral-background";
+  "rounded-2xl bg-neutral-surface/35 p-1 dark:bg-neutral-surface/20";
 
 export function SearchResults({
   results,
   isLoading,
   searchTerm,
+  onSelect,
 }: SearchResultsProps) {
   if (isLoading) {
     return (
       <div
         className={searchResultsContainer}
         data-testid="search-results-container"
       >
-        <h4 className="text-brand-primary font-bold my-2">Searching docs...</h4>
+        <h4 className="px-3 py-4 text-sm font-semibold text-brand-primary">
+          Searching docs...
+        </h4>
       </div>
     );
   }
@@ -41,13 +46,19 @@ export function SearchResults({
           <Link
             key={index}
             href={result.url}
-            className="block p-2 border-b-1 border-b-gray-200 last:border-b-0 group"
+            className="group block rounded-xl px-3 py-3 transition hover:bg-brand-primary/8"
+            onClick={onSelect}
           >
+            {result.sectionPath.length > 0 && (
+              <p className="mb-1 text-[11px] font-semibold uppercase tracking-[0.12em] text-neutral-text-secondary">
+                {result.sectionPath.join(" / ")}
+              </p>
+            )}
             <h3 className="font-medium text-brand-primary group-hover:text-brand-primary-hover">
               {result.title}
             </h3>
             <p
-              className="mt-1 text-sm text-neutral-text"
+              className="mt-1 text-sm text-neutral-text-secondary"
               // biome-ignore lint/security/noDangerouslySetInnerHtml: For Highlighting the search term, it is important to use dangerouslySetInnerHTML
               dangerouslySetInnerHTML={{
                 __html: result.excerpt || "",
@@ -66,7 +77,7 @@ export function SearchResults({
         data-testid="search-results-container"
       >
         <div
-          className="py-2 px-4 text-md font-inter font-semibold text-neutral-text-secondary text-bold"
+          className="px-3 py-4 text-sm font-semibold text-neutral-text-secondary"
           data-testid="no-results-message"
         >
           No matching docs found.