Merge pull request #262 from dotCMS/javadocs-page

Added new Javadocs page, replacing old vanity url

Author: jdcmsd

app/docs/[slug]/page.js

@@ -22,6 +22,7 @@ import Script from "next/script";
 import { getSecurityIssues } from "@/services/docs/getSecurityIssues/getSecurityIssues";
 import Deprecations from "@/components/deprecations/Deprecations";
 import getDeprecations from "@/services/docs/getDeprecations/getDeprecations";
+import { JavadocEmbeddedDocs } from "@/components/javadocs/JavadocEmbeddedDocs";
 
 /**
  * Process slug consistently across all functions
@@ -237,72 +238,76 @@ export default async function Home({ searchParams, params }) {
 
     if (!pageData || !pageData.pageAsset) {
         notFound();
-        return null; // Unreachable, but ensures code path terminates
+        return null;
     }
 
     const { pageAsset } = pageData;
-    
+
     const sideNav = await getSideNav();
-    const navSections = await getNavSections({ path: '/docs/nav', depth: 4, languageId: 1, ttlSeconds: 600 });
-    
-    // Check if urlContentMap exists
+    const navSections = await getNavSections({
+        path: "/docs/nav",
+        depth: 4,
+        languageId: 1,
+        ttlSeconds: 600,
+    });
+
     if (!pageAsset?.urlContentMap?.inode) {
         notFound();
     }
-    
-    // Handle GitHub docs if needed (this sets githubSource flag)
+
     if (isGitHubDoc(slug)) {
         const githubConfig = getGitHubConfig(slug);
-        
+
         if (githubConfig && pageAsset?.urlContentMap?.inode) {
             const contentResult = await getDocsContentWithGitHub(
                 slug,
                 githubConfig,
-                () => pageAsset?.urlContentMap?._map?.documentation || ''
+                () => pageAsset?.urlContentMap?._map?.documentation || ""
             );
 
-            if (contentResult.source === 'github') {
+            if (contentResult.source === "github") {
                 if (!pageAsset.urlContentMap._map) {
                     pageAsset.urlContentMap._map = {};
                 }
-                
-                pageAsset.urlContentMap._map.documentation = contentResult.content;
+
+                pageAsset.urlContentMap._map.documentation =
+                    contentResult.content;
                 pageAsset.urlContentMap._map.githubSource = true;
-                pageAsset.urlContentMap._map.githubConfig = contentResult.config;
+                pageAsset.urlContentMap._map.githubConfig =
+                    contentResult.config;
             }
         }
     }
-    
-    // Fetch all deprecations once (GraphQL response cached ~15m by default)
+
     let allDeprecations = null;
     try {
         allDeprecations = await getDeprecations();
-    } catch(e) {
+    } catch (e) {
         console.error("Error fetching deprecations:", e);
         allDeprecations = null;
     }
 
-    // Find matching deprecation for this specific page (OR logic - always check)
     let deprecationForPage = null;
     if (allDeprecations && Array.isArray(allDeprecations)) {
-        deprecationForPage = allDeprecations.find(dep => 
-            dep.docLinks && 
-            Array.isArray(dep.docLinks) && 
-            dep.docLinks.some(link => link.urlTitle === slug)
-        ) || null;
+        deprecationForPage =
+            allDeprecations.find(
+                (dep) =>
+                    dep.docLinks &&
+                    Array.isArray(dep.docLinks) &&
+                    dep.docLinks.some((link) => link.urlTitle === slug)
+            ) || null;
     }
 
     const data = {
         contentlet: pageAsset.urlContentMap,
-        sideNav: sideNav,
+        sideNav,
         currentPath: slug,
         searchParams: finalSearchParams,
         deprecation: deprecationForPage,
-        allDeprecations: slug === 'deprecations' ? allDeprecations : undefined
-    }
+        allDeprecations: slug === "deprecations" ? allDeprecations : undefined,
+    };
 
-    // Add more path-component mappings here as needed:
-    // "path-name": (contentlet) => <ComponentName contentlet={contentlet} />,
+    // Add more path-component mappings here as needed.
     const componentMap = {
         "changelogs": (data) => <ChangeLogList {...data} slug={slug} />,
         "current-releases": (data) => <CurrentReleases  {...data} slug={slug} />,
@@ -312,6 +317,14 @@ export default async function Home({ searchParams, params }) {
         "deprecations": (data) => <Deprecations {...data} slug={slug} initialItems={data.allDeprecations || []} />,
         "rest-api-sampler": (data) => <RestApiPlayground {...data} slug={slug} />,
         "all-rest-apis": (data) => <SwaggerUIComponent {...data} slug={slug} />,
+        "javadocs": (data) => (
+            <JavadocEmbeddedDocs
+                contentlet={data.contentlet}
+                sideNav={data.sideNav}
+                slug={slug}
+                searchParams={data.searchParams}
+            />
+        ),
         default: (data) => {
             // Check if this is GitHub-sourced content
             // githubSource is set on urlContentMap._map, so check _map property
@@ -325,7 +338,7 @@ export default async function Home({ searchParams, params }) {
 
     return (
         <div className="flex flex-col min-h-screen">
-            <Header sideNavItems={sideNav[0]?.dotcmsdocumentationchildren || []} currentPath={slug} navSections={navSections} />
+            <Header sideNavItems={data.sideNav[0]?.dotcmsdocumentationchildren || []} currentPath={slug} navSections={navSections} />
             <JsonLd pageData={data} path={path} hostname={hostname} />
 
             <div className="flex-1">

components/javadocs/JavadocEmbeddedDocs.tsx

@@ -0,0 +1,58 @@
+import { listJavadocS3Versions } from '@/services/javadocs/listJavadocS3Versions';
+import { JavadocEmbeddedDocsClient } from './JavadocEmbeddedDocsClient';
+
+const DEFAULT_JAVADOCS_BASE = 'https://static.dotcms.com/docs';
+
+type SideNavEntry = { dotcmsdocumentationchildren?: unknown[] };
+
+type Props = {
+  contentlet: { navTitle?: string; title?: string };
+  sideNav: SideNavEntry[];
+  slug: string;
+  searchParams?: Record<string, string | string[] | undefined>;
+};
+
+function resolveInitialVersion(
+  versions: string[],
+  requested: string | undefined
+): string | null {
+  if (requested && versions.includes(requested)) {
+    return requested;
+  }
+  return versions.length > 0 ? versions[0] : null;
+}
+
+export async function JavadocEmbeddedDocs({
+  contentlet,
+  sideNav,
+  slug,
+  searchParams,
+}: Props) {
+  const { versions, status: versionListStatus } =
+    await listJavadocS3Versions();
+  const baseFromEnv = process.env.NEXT_PUBLIC_JAVADOCS_BASE_URL;
+  const baseUrl = (baseFromEnv || DEFAULT_JAVADOCS_BASE).replace(/\/$/, '');
+
+  const rawV = searchParams?.v;
+  const requested =
+    typeof rawV === 'string' ? rawV : Array.isArray(rawV) ? rawV[0] : undefined;
+
+  const initialSelectedVersion = resolveInitialVersion(versions, requested);
+
+  const title =
+    contentlet?.navTitle || contentlet?.title || 'Java API (Javadoc)';
+
+  const sideNavItems = sideNav?.[0]?.dotcmsdocumentationchildren ?? [];
+
+  return (
+    <JavadocEmbeddedDocsClient
+      versions={versions}
+      versionListStatus={versionListStatus}
+      baseUrl={baseUrl}
+      slug={slug}
+      sideNavItems={sideNavItems}
+      title={title}
+      initialSelectedVersion={initialSelectedVersion}
+    />
+  );
+}

components/javadocs/JavadocEmbeddedDocsClient.tsx

@@ -0,0 +1,152 @@
+'use client';
+
+import { useCallback, useState } from 'react';
+import { ExternalLink } from 'lucide-react';
+import Breadcrumbs from '@/components/navigation/Breadcrumbs';
+import { Label } from '@/components/ui/label';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select';
+import type { JavadocVersionListStatus } from '@/services/javadocs/listJavadocS3Versions';
+
+function versionListHelp(status: JavadocVersionListStatus): string {
+  switch (status) {
+    case 'missing_env':
+      return 'Set JAVADOCS_S3_ACCESS_KEY_ID, JAVADOCS_S3_SECRET_ACCESS_KEY, and JAVADOCS_S3_BUCKET on the server, then restart the dev server so Next.js picks up .env.local.';
+    case 's3_error':
+      return 'S3 listing failed (see server terminal logs). Common fixes: correct JAVADOCS_S3_REGION for the bucket, IAM permission s3:ListBucket on that bucket, and a bucket name that matches AWS exactly.';
+    case 'empty':
+      return 'Listing succeeded but no version folders matched. Check JAVADOCS_S3_DOCS_PREFIX (default docs/) matches keys in the bucket, and that folder names look like 26.04.28-02 (digits, dots, hyphens; not starting with 99).';
+    default:
+      return '';
+  }
+}
+
+export type JavadocEmbeddedDocsClientProps = {
+  versions: string[];
+  versionListStatus: JavadocVersionListStatus;
+  /** No trailing slash, e.g. https://static.dotcms.com/docs */
+  baseUrl: string;
+  slug: string;
+  sideNavItems: unknown[];
+  title: string;
+  initialSelectedVersion: string | null;
+};
+
+function buildJavadocIndexUrl(baseUrl: string, version: string): string {
+  const enc = encodeURIComponent(version);
+  return `${baseUrl}/${enc}/javadocs/index.html`;
+}
+
+export function JavadocEmbeddedDocsClient({
+  versions,
+  versionListStatus,
+  baseUrl,
+  slug,
+  sideNavItems,
+  title,
+  initialSelectedVersion,
+}: JavadocEmbeddedDocsClientProps) {
+  const [selectedVersion, setSelectedVersion] = useState<string | null>(
+    initialSelectedVersion
+  );
+
+  const iframeSrc = selectedVersion
+    ? buildJavadocIndexUrl(baseUrl, selectedVersion)
+    : null;
+
+  const onVersionChange = useCallback((value: string) => {
+    setSelectedVersion(value);
+  }, []);
+
+  return (
+    <div className="flex flex-col gap-6 py-6 w-full min-w-0">
+      <Breadcrumbs items={sideNavItems as never[]} slug={slug} />
+
+      <div className="flex flex-col gap-4 lg:flex-row lg:items-end lg:justify-between lg:gap-6">
+        <h1 className="text-3xl sm:text-4xl font-bold tracking-tight text-foreground lg:min-w-0 lg:flex-1">
+          {title}
+        </h1>
+
+        <div className="flex flex-col gap-3 sm:flex-row sm:items-end sm:gap-5 shrink-0">
+          {iframeSrc ? (
+            <a
+              href={iframeSrc}
+              target="_blank"
+              rel="noopener noreferrer"
+              className="inline-flex items-center gap-1.5 text-sm font-medium text-primary underline-offset-4 hover:underline sm:mb-2"
+            >
+              <ExternalLink className="h-4 w-4 shrink-0" aria-hidden />
+              Open Javadoc in new tab
+            </a>
+          ) : null}
+
+          <div className="flex flex-col gap-2 w-full sm:w-72">
+          <Label htmlFor="javadoc-version" className="text-sm font-medium">
+            Javadoc version
+          </Label>
+          {versions.length > 0 ? (
+            <Select
+              value={selectedVersion ?? undefined}
+              onValueChange={onVersionChange}
+            >
+              <SelectTrigger id="javadoc-version" className="w-full">
+                <SelectValue placeholder="Select a version" />
+              </SelectTrigger>
+              <SelectContent>
+                {versions.map((v) => (
+                  <SelectItem key={v} value={v}>
+                    {v}
+                  </SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+          ) : (
+            <div className="space-y-2 rounded-md border border-dashed border-border bg-muted/30 px-3 py-2 text-sm text-muted-foreground">
+              <p className="font-medium text-foreground">No versions in the list yet</p>
+              <p>{versionListHelp(versionListStatus)}</p>
+              <p className="text-xs leading-relaxed">
+                In S3, the <span className="text-foreground">bucket</span> is the
+                top-level store (one name), not a folder inside something else.
+                If Cyberduck shows{' '}
+                <code className="rounded bg-muted px-1 py-0.5 text-foreground">
+                  /static.dotcms.com
+                </code>{' '}
+                at the root, set{' '}
+                <code className="rounded bg-muted px-1 py-0.5 text-foreground">
+                  JAVADOCS_S3_BUCKET=static.dotcms.com
+                </code>{' '}
+                (no leading slash). Version folders live under keys like{' '}
+                <code className="rounded bg-muted px-1 py-0.5 text-foreground">
+                  docs/26.04.28-02/…
+                </code>{' '}
+                inside that bucket.
+              </p>
+            </div>
+          )}
+          </div>
+        </div>
+      </div>
+
+      <div className="relative w-full rounded-lg border border-border bg-muted/20 overflow-hidden shadow-sm min-h-[70vh] h-[min(85vh,1200px)]">
+        {iframeSrc ? (
+          <iframe
+            key={iframeSrc}
+            title={`Javadoc ${selectedVersion}`}
+            src={iframeSrc}
+            className="absolute inset-0 w-full h-full border-0 bg-background"
+            referrerPolicy="no-referrer-when-downgrade"
+          />
+        ) : (
+          <div className="absolute inset-0 flex items-center justify-center p-8 text-center text-muted-foreground text-sm">
+            Select a version to load Javadoc in this frame.
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}

next.config.js

@@ -4,6 +4,14 @@ const url = new URL(process.env.NEXT_PUBLIC_DOTCMS_HOST);
 
 const nextConfig = {
     reactStrictMode: true,
+    // Avoid broken ./vendor-chunks/* for packages Next splits oddly on the server
+    // (consola via @dotcms/client; highlight.js via react-syntax-highlighter; AWS SDK).
+    serverExternalPackages: [
+        "consola",
+        "@aws-sdk/client-s3",
+        "highlight.js",
+        "react-syntax-highlighter",
+    ],
     // Fixes confusing dev/build behavior when Next infers the wrong repo root due to multiple lockfiles.
     // Also helps make stack traces and tracing output more consistent.
     outputFileTracingRoot: __dirname,