Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

19.2 KB
Raw Blame
"use client";

import { useState, useCallback, useEffect, useLayoutEffect, useMemo } from "react";
import useSWR from "swr";
import { useSearchParams, useRouter } from "next/navigation";
import { BookOpen, PanelLeftClose, PanelLeft, Search } from "lucide-react";
import { cn } from "@/lib/utils/cn";
import { usePages } from "@/lib/hooks/use-pages";
import { DocsTree } from "@repowise-dev/ui/docs/docs-tree";
import { DocsCommandPalette } from "@repowise-dev/ui/docs/command-palette";
import {
  PresentOverlay,
  buildPresentModel,
  canPresent,
  loadPresentSource,
} from "@repowise-dev/ui/present";
import {
  DEFAULT_PERSONA,
  type ReaderPersona,
  isReaderPersona,
  personaFilteringApplies,
} from "@repowise-dev/ui/docs/reader-persona";
import { DocsHeader } from "./docs-header";
import { DocsViewer } from "./docs-viewer";
import { AskAboutThis } from "@repowise-dev/ui/chat";
import {
  ReaderLevelControl,
  SidebarToggle,
} from "@repowise-dev/ui/docs/docs-page-actions";
import { BulkGenerateDialogs, BulkWriteButton } from "./bulk-generate-dialogs";
import { buildDocsMenuGroups } from "./docs-menu";
import { useBulkGenerate } from "@/lib/hooks/use-bulk-generate";
import { HostedNudgeSlot } from "@/components/hosted/hosted-nudge-slot";
import { isStubPage } from "@repowise-dev/ui/lib/page-types";
import { search as searchPages } from "@/lib/api/search";
import { getPageById, listAllPages } from "@/lib/api/pages";
import { downloadTextFile } from "@/lib/utils/download";
import { Skeleton } from "@repowise-dev/ui/ui/skeleton";
import { useTranslations } from "next-intl";
import type { DocPage, DocPageSummary } from "@repowise-dev/types/docs";
import type { PageSummary } from "@/lib/api/types";

interface DocsExplorerProps {
  repoId: string;
}

export function DocsExplorer({ repoId }: DocsExplorerProps) {
  const t = useTranslations("docs");
  const tc = useTranslations("common");
  const { pages, isLoading, mutate } = usePages(repoId);
  // The list carries no bodies, so the reader's page is fetched on its own.
  // Only the id is state; the page itself is whatever that id resolves to,
  // which keeps it correct after a regeneration without a second copy to sync.
  const [selectedPageId, setSelectedPageId] = useState<string | null>(null);
  const {
    data: selectedPage = null,
    isLoading: pageLoading,
    mutate: mutateSelectedPage,
  } = useSWR(
    selectedPageId ? `page:${selectedPageId}` : null,
    () => getPageById(selectedPageId!, repoId),
    // No retry: the one expected failure is a ?page= id that no longer exists,
    // and retrying a 404 just delays the empty state.
    { revalidateOnFocus: false, shouldRetryOnError: false },
  );
  // Both panels default to whether the layout can afford them, not to `true`:
  // the tree from md, the rail from the 2xl breakpoint the reader uses to place
  // its sections. A manual toggle wins from then on, same contract as the app
  // sidebar's route-based collapse. The server cannot see the viewport, so the
  // default is CSS until hydration: `null` renders the tree hidden below md and
  // as a column from md (the rail is already `hidden 2xl:block`), and a phone
  // never paints an open drawer. The layout effect then takes the breakpoint
  // as state before paint; reading it during render failed hydration.
  const [treePanelOpen, setTreePanelOpen] = useState<boolean | null>(null);
  const [sidebarOpen, setSidebarOpen] = useState(true);
  useLayoutEffect(() => {
    setTreePanelOpen(window.matchMedia("(min-width: 768px)").matches);
    setSidebarOpen(window.matchMedia("(min-width: 1536px)").matches);
  }, []);
  const [searchOpen, setSearchOpen] = useState(false);
  const [isExporting, setIsExporting] = useState(false);
  const searchParams = useSearchParams();
  const router = useRouter();

  // Reader persona — a client-side section filter, persisted in the URL
  // (?reader=) so a chosen depth is shareable and survives navigation. Owned
  // here (not in the viewer) because the control renders in the DocsHeader.
  const readerParam = searchParams.get("reader");
  const persona: ReaderPersona = isReaderPersona(readerParam) ? readerParam : DEFAULT_PERSONA;
  const setPersona = useCallback(
    (next: ReaderPersona) => {
      const params = new URLSearchParams(searchParams.toString());
      if (next === DEFAULT_PERSONA) params.delete("reader");
      else params.set("reader", next);
      const qs = params.toString();
      router.replace(qs ? `?${qs}` : "?", { scroll: false });
    },
    [router, searchParams],
  );
  // The reader control only renders when filtering would change this page —
  // on curated pages (guided tour, overviews) it's a no-op, so it hides.
  const personaHasEffect = useMemo(
    () => (selectedPage ? personaFilteringApplies(selectedPage.content) : false),
    [selectedPage],
  );

  // The bar's one bulk model action, shown only while concept pages are still
  // stubs, with how many. A structural page is never a stub.
  const stubCount = useMemo(
    () => pages.filter((p) => isStubPage(p)).length,
    [pages],
  );
  const hasStubs = stubCount > 0;
  const bulk = useBulkGenerate(repoId);

  // Keep the selected page in sync with the ?page= URL param. This fires on
  // mount and whenever the param changes — including when an in-content wiki
  // link or breadcrumb navigates via <Link href="?page=...">.
  const pageParam = searchParams.get("page");
  useEffect(() => {
    if (pageParam) {
      // Set straight from the URL without waiting for the list: a page id is
      // enough to fetch it, so the reading column and the tree load side by
      // side rather than one behind the other.
      //
      // Deliberately no fallback to the overview when the id resolves to
      // nothing. Opening a different page would look like the link worked and
      // put a reader who asked about one file in front of another's prose;
      // the reader says which page was missing instead. Every caller that
      // builds `?page=file_page:<path>` for an arbitrary path — the hotspot
      // and symbol row actions, the file card — depends on that, because page
      // selection is budgeted and most files have no page.
      setSelectedPageId(pageParam);
      return;
    }
    // No ?page= in the URL — open the repo overview by default (falling back
    // to the first page) so the viewer never lands on an empty state.
    if (selectedPageId || pages.length === 0) return;
    const overview = pages.find((p) => p.page_type === "repo_overview");
    setSelectedPageId((overview ?? pages[0])?.id ?? null);
  }, [pages, pageParam, selectedPageId]);

  // After a page is (re)generated, pull the fresh list (freshness and stub
  // state live there) and refetch the page on screen so its content and
  // provenance flip in place.
  const handleGenerated = useCallback(async () => {
    await Promise.all([mutate(), mutateSelectedPage()]);
  }, [mutate, mutateSelectedPage]);

  const handleSelectPage = useCallback((page: DocPageSummary) => {
    setSelectedPageId(page.id);
    // Update URL without full navigation
    const params = new URLSearchParams(searchParams.toString());
    params.set("page", page.id);
    router.replace(`?${params.toString()}`, { scroll: false });
  }, [searchParams, router]);

  // Present mode: a short deck derived from the same pages, never generated.
  // Open state lives in ?present so a deck link is shareable; any value opens
  // it, which keeps older ?present=deck links working.
  const presentable = useMemo(() => canPresent(pages), [pages]);
  const presentOpen = searchParams.has("present");
  // A deck draws on a handful of pages out of thousands, so their bodies are
  // fetched when Present is opened, not carried by the page list.
  const { data: presentModel = null } = useSWR(
    presentable && presentOpen ? `present:${repoId}` : null,
    async () => {
      const source = await loadPresentSource(pages, (id) =>
        getPageById(id, repoId) as Promise<DocPage>,
      );
      return source ? buildPresentModel(source) : null;
    },
    { revalidateOnFocus: false },
  );
  const setPresent = useCallback(
    (open: boolean, pageId?: string) => {
      const params = new URLSearchParams(searchParams.toString());
      if (open) params.set("present", "deck");
      else params.delete("present");
      if (pageId) params.set("page", pageId);
      const qs = params.toString();
      router.replace(qs ? `?${qs}` : "?", { scroll: false });
    },
    [searchParams, router],
  );
  const openInReaderFromPresent = useCallback(
    (pageId: string) => {
      setSelectedPageId(pageId);
      setPresent(false, pageId);
    },
    [setPresent],
  );

  // Server-backed search for the ⌘K palette. The palette matches titles and
  // paths itself; bodies are matched here, because the loaded list carries
  // none. Both search modes run: full-text is the literal body match the
  // palette used to do client-side, semantic finds pages that mean the same
  // thing without sharing a word. Results map back to the loaded rows so
  // selection behaves identically to a local hit; unknown ids are dropped.
  const searchFn = useCallback(
    async (q: string) => {
      const [fulltext, semantic] = await Promise.all([
        searchPages(q, { repo_id: repoId, limit: 20, search_type: "fulltext" }),
        searchPages(q, { repo_id: repoId, limit: 20, search_type: "semantic" }),
      ]);
      const byId = new Map(pages.map((p) => [p.id, p]));
      const seen = new Set<string>();
      const hits: { page: PageSummary; snippet?: string }[] = [];
      for (const r of [...fulltext, ...semantic]) {
        const page = byId.get(r.page_id);
        if (!page || seen.has(page.id)) continue;
        seen.add(page.id);
        hits.push({ page, ...(r.snippet ? { snippet: r.snippet } : {}) });
      }
      return hits;
    },
    [repoId, pages],
  );

  // Every page's markdown in one file. The bodies aren't loaded — that is the
  // point of the summary listing — so this is the one place that still asks
  // for the whole wiki, at the moment someone asks for the whole wiki.
  const handleExportAll = useCallback(async () => {
    setIsExporting(true);
    try {
      const full = await listAllPages(repoId);
      const sorted = [...full].sort((a, b) =>
        a.target_path.localeCompare(b.target_path),
      );
      const content = sorted
        .map((p) => `# ${p.title}\n\n> ${p.target_path}\n\n${p.content}`)
        .join("\n\n---\n\n");
      downloadTextFile(content, "documentation-export.md");
    } finally {
      setIsExporting(false);
    }
  }, [repoId]);

  const handleExportPage = useCallback(() => {
    if (!selectedPage) return;
    const filename =
      (selectedPage.target_path || selectedPage.title).replace(/\//g, "_") + ".md";
    const header = `# ${selectedPage.title}\n\n> Path: ${selectedPage.target_path}\n\n`;
    downloadTextFile(header + selectedPage.content, filename);
  }, [selectedPage]);

  const menuGroups = buildDocsMenuGroups({
    t,
    hasPage: !!selectedPage,
    onExportPage: handleExportPage,
    onExportAll: handleExportAll,
    exporting: isExporting,
    zipHref: `/api/repos/${repoId}/export`,
    onPresent: presentable ? () => setPresent(true) : null,
    reader: personaHasEffect ? { persona, setPersona } : null,
  });

  // The tree panel, rendered at every state so it keeps the full height of the
  // window rather than starting below a chrome bar. Its skeleton lives here
  // too, so the layout does not reflow once the pages land.
  const treePanel = (
    // No right border. Tree, reading column and rail sit on one plane and are
    // separated by space; a rule on each side of the reading column made it
    // read as a trench between two panels.
    // Below md the tree is a drawer over the reader, not a column beside it.
    // As a column it would claim the full width and starve the header column
    // it now sits next to, squashing the view switch into a few pixels.
    <div
      className={cn(
        "bg-[var(--color-bg-surface)] transition-all duration-200 shrink-0 overflow-y-auto",
        treePanelOpen === null
          ? "absolute inset-y-0 left-0 z-30 w-full hidden md:static md:block md:w-[288px]"
          : treePanelOpen
            ? "absolute inset-y-0 left-0 z-30 w-full md:static md:w-[288px]"
            : "w-0 overflow-hidden",
      )}
    >
      {isLoading ? (
        <div className="space-y-2 p-3">
          <Skeleton className="h-8 w-full rounded-md" />
          <Skeleton className="h-4 w-3/4 rounded" />
          <Skeleton className="h-4 w-1/2 rounded" />
          <Skeleton className="h-4 w-5/6 rounded" />
          <Skeleton className="h-4 w-2/3 rounded" />
          <Skeleton className="h-4 w-3/4 rounded" />
          <Skeleton className="h-4 w-1/2 rounded" />
        </div>
      ) : (
        <DocsTree
          pages={pages}
          // The id, not the fetched page: the row should highlight on click,
          // not once its body has come back.
          selectedPageId={selectedPageId}
          onSelectPage={(p) => {
            handleSelectPage(p);
            if (typeof window !== "undefined" && !window.matchMedia("(min-width: 768px)").matches) {
              setTreePanelOpen(false);
            }
          }}
        />
      )}
    </div>
  );

  // The reader no longer waits on the page list — it has an id from the URL
  // and fetches its own page — so the only thing that blocks on the list is
  // knowing whether there is any documentation at all.
  let body: React.ReactNode;
  if (!isLoading && pages.length === 0) {
    body = (
      <div className="flex flex-col items-center justify-center h-full gap-4 text-center px-8">
        <div className="rounded-full bg-[var(--color-bg-elevated)] border border-[var(--color-border-default)] p-4">
          <BookOpen className="h-8 w-8 text-[var(--color-text-tertiary)]" />
        </div>
        <div className="space-y-1">
          <h3 className="text-sm font-semibold text-[var(--color-text-primary)]">
            {t("explorer.emptyTitle")}
          </h3>
          <p className="text-xs text-[var(--color-text-secondary)] max-w-sm">
            {t("explorer.emptyBody")}
          </p>
        </div>
      </div>
    );
  } else {
    body = (
      <div className="h-full min-w-0">
        <DocsViewer
          page={selectedPage}
          pages={pages}
          repoId={repoId}
          // Reading-column skeleton while its own page is in flight, and while
          // the list is still deciding which page to open on.
          isLoading={pageLoading || (!selectedPageId && isLoading)}
          // The id resolved to nothing. Guarded on `!pageLoading` so the
          // "no page for this one" line cannot flash over a request still in
          // flight, and on `!selectedPage` so it never shows over a page that
          // did land.
          missingPageId={
            selectedPageId && !pageLoading && !selectedPage ? selectedPageId : undefined
          }
          onSelectPage={handleSelectPage}
          persona={persona}
          sidebarOpen={sidebarOpen}
          onGenerated={handleGenerated}
        />
      </div>
    );
  }

  // Tree beside the chrome, not under it. The header used to span the full
  // width, which pushed the tree down by its height on every screen and cost
  // that much of the list for a bar that says "Documentation" on a page whose
  // route is already /docs. The tree now starts at the top and the bar sits to
  // the right of it, over the reading column it actually acts on.
  return (
    <div className="relative flex h-full">
      {treePanel}

      <button
        onClick={() => setTreePanelOpen((o) => !o)}
        aria-label={treePanelOpen ? t("explorer.hideTree") : t("explorer.showTree")}
        aria-expanded={treePanelOpen ?? undefined}
        className={cn(
          "absolute top-3.5 z-20 rounded-md p-1 text-[var(--color-text-tertiary)] hover:text-[var(--color-text-primary)] hover:bg-[var(--color-bg-elevated)] transition-colors",
          treePanelOpen === null
            ? "left-1 md:left-[292px]"
            : treePanelOpen
              ? "hidden md:block left-[292px]"
              : "left-1",
        )}
      >
        {treePanelOpen === null ? (
          <>
            <PanelLeft className="h-3.5 w-3.5 md:hidden" />
            <PanelLeftClose className="hidden h-3.5 w-3.5 md:block" />
          </>
        ) : treePanelOpen ? (
          <PanelLeftClose className="h-3.5 w-3.5" />
        ) : (
          <PanelLeft className="h-3.5 w-3.5" />
        )}
      </button>

      <div className="flex flex-1 min-w-0 flex-col">
        {/* Reading, searching and the one bulk model action stay in the bar;
            the rest is in More. The page's own model action and its freshness
            live in the reader's metadata row, under the title they act on. */}
        <DocsHeader menuGroups={menuGroups} menuBusy={isExporting}>
          {personaHasEffect && (
            <ReaderLevelControl
              persona={persona}
              setPersona={setPersona}
              className="hidden sm:inline-flex"
            />
          )}
          {selectedPage && (
            <AskAboutThis
              context={{
                kind: "documentation",
                label: selectedPage.title,
                target: selectedPage.id,
                targetKind: "documentation",
              }}
              question={t("explorer.askQuestion", { title: selectedPage.title })}
              label={t("explorer.askLabel", { title: selectedPage.title })}
              className="shrink-0"
            />
          )}
          <BulkWriteButton
            count={stubCount}
            running={bulk.jobId != null}
            onClick={bulk.open}
          />
          <button
            onClick={() => setSearchOpen(true)}
            aria-label={tc("search")}
            className="flex h-7 shrink-0 items-center gap-2 rounded-md border border-[var(--color-border-default)] bg-[var(--color-bg-elevated)] px-2 text-xs text-[var(--color-text-tertiary)] transition-colors hover:text-[var(--color-text-secondary)] sm:px-2.5"
          >
            <Search className="h-3.5 w-3.5" />
            <span className="hidden sm:inline">{tc("search")}</span>
            <kbd className="hidden rounded border border-[var(--color-border-default)] px-1 py-0.5 text-[10px] sm:inline">
              ⌘K
            </kbd>
          </button>
          {selectedPage && (
            <SidebarToggle
              open={sidebarOpen}
              onToggle={() => setSidebarOpen((o) => !o)}
            />
          )}
        </DocsHeader>

        <BulkGenerateDialogs flow={bulk} repoId={repoId} onGenerated={handleGenerated} />

        {/* Only while pages are still rendered from structure. */}
        <HostedNudgeSlot
          candidates={[hasStubs && "docs"]}
          repoId={repoId}
          className="mx-3 mt-2 sm:mx-6"
        />

        <div className="flex-1 min-h-0">{body}</div>
      </div>

      {/* Present mode overlay — full-screen, escapes the dashboard chrome */}
      {presentOpen && presentModel && (
        <PresentOverlay
          model={presentModel}
          onClose={() => setPresent(false)}
          onOpenPage={openInReaderFromPresent}
        />
      )}

      {/* ⌘K full-text command palette over loaded pages */}
      <DocsCommandPalette
        pages={pages}
        open={searchOpen}
        onOpenChange={setSearchOpen}
        onSelect={handleSelectPage}
        searchFn={searchFn}
      />
    </div>
  );
}