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.

feat(docs): calm the docs bar with one More menu and page-level actions (#4698)

Raghav Chamadiyaea2da18ba0e7
diff --git a/packages/ui/__tests__/docs/docs-more-menu.test.tsx b/packages/ui/__tests__/docs/docs-more-menu.test.tsx
new file mode 100644
index 000000000..eca465646
--- /dev/null
+++ b/packages/ui/__tests__/docs/docs-more-menu.test.tsx
@@ -0,0 +1,121 @@
+import { describe, it, expect, vi } from "vitest";
+import { render, screen, fireEvent } from "@testing-library/react";
+import { Sparkles } from "lucide-react";
+import { DocsMoreMenu, type DocsMenuGroup } from "../../src/docs/docs-more-menu.js";
+
+function groups(over: Partial<Record<string, () => void>> = {}): DocsMenuGroup[] {
+ return [
+ {
+ key: "export",
+ items: [
+ { key: "all", label: "Export all pages (Markdown)", onSelect: over.all ?? vi.fn() },
+ { key: "zip", label: "Download ZIP archive", href: "/export.zip", download: true },
+ ],
+ },
+ { key: "present", items: [{ key: "present", label: "Present", onSelect: vi.fn() }] },
+ {
+ key: "model",
+ items: [
+ {
+ key: "write-all",
+ label: "Write all subsystem pages",
+ icon: Sparkles,
+ tone: "model",
+ onSelect: over.writeAll ?? vi.fn(),
+ },
+ ],
+ },
+ ];
+}
+
+function open(gs: DocsMenuGroup[] = groups()) {
+ render(<DocsMoreMenu groups={gs} />);
+ fireEvent.click(screen.getByRole("button", { name: "More" }));
+}
+
+describe("DocsMoreMenu", () => {
+ it("holds export, present and the bulk write behind one trigger", () => {
+ open();
+ expect(screen.getAllByRole("menuitem").map((i) => i.textContent)).toEqual([
+ "Export all pages (Markdown)",
+ "Download ZIP archive",
+ "Present",
+ "Write all subsystem pages",
+ ]);
+ expect(screen.getByRole("menuitem", { name: "Download ZIP archive" })).toHaveAttribute(
+ "href",
+ "/export.zip",
+ );
+ });
+
+ it("marks the bulk write as model work", () => {
+ open();
+ expect(
+ screen.getByRole("menuitem", { name: "Write all subsystem pages" }).className,
+ ).toContain("--color-model");
+ });
+
+ it("runs the chosen item and closes", () => {
+ const writeAll = vi.fn();
+ open(groups({ writeAll }));
+ fireEvent.click(screen.getByRole("menuitem", { name: "Write all subsystem pages" }));
+ expect(writeAll).toHaveBeenCalledTimes(1);
+ expect(screen.queryByRole("menu")).toBeNull();
+ });
+
+ it("moves focus with the arrow keys, wrapping at the ends", () => {
+ open();
+ const menu = screen.getByRole("menu");
+ const items = screen.getAllByRole("menuitem");
+ items[0]!.focus();
+ fireEvent.keyDown(menu, { key: "ArrowDown" });
+ expect(document.activeElement).toBe(items[1]);
+ fireEvent.keyDown(menu, { key: "End" });
+ expect(document.activeElement).toBe(items[3]);
+ fireEvent.keyDown(menu, { key: "ArrowDown" });
+ expect(document.activeElement).toBe(items[0]);
+ fireEvent.keyDown(menu, { key: "ArrowUp" });
+ expect(document.activeElement).toBe(items[3]);
+ });
+
+ it("renders choices as radio items", () => {
+ open([
+ {
+ key: "reader",
+ label: "Reader level",
+ phoneOnly: true,
+ items: [
+ { key: "a", label: "Overview", checked: false, onSelect: vi.fn() },
+ { key: "b", label: "Deep", checked: true, onSelect: vi.fn() },
+ ],
+ },
+ ]);
+ expect(screen.getByRole("menuitemradio", { name: "Deep" })).toHaveAttribute(
+ "aria-checked",
+ "true",
+ );
+ expect(screen.getByRole("group", { name: "Reader level" }).className).toContain("sm:hidden");
+ });
+
+ it("marks the view on screen and makes the trigger read as active", () => {
+ render(
+ <DocsMoreMenu
+ groups={[{ key: "views", items: [{ key: "f", label: "Doc freshness", href: "/coverage", current: true }] }]}
+ LinkComponent={({ children, ...rest }) => <a data-router="" {...rest}>{children}</a>}
+ />,
+ );
+ const trigger = screen.getByRole("button", { name: "More" });
+ expect(trigger.className).toContain("font-medium");
+ fireEvent.click(trigger);
+ const item = screen.getByRole("menuitem", { name: "Doc freshness" });
+ expect(item).toHaveAttribute("aria-current", "page");
+ expect(item).toHaveAttribute("data-router");
+ });
+
+ it("renders nothing when every group is empty", () => {
+ const { container } = render(
+ <DocsMoreMenu groups={[{ key: "x", items: [] }]} />,
+ );
+ expect(container).toBeEmptyDOMElement();
+ });
+});
diff --git a/packages/ui/__tests__/docs/docs-reader-meta-row.test.tsx b/packages/ui/__tests__/docs/docs-reader-meta-row.test.tsx
new file mode 100644
index 000000000..9e882a18d
--- /dev/null
+++ b/packages/ui/__tests__/docs/docs-reader-meta-row.test.tsx
@@ -0,0 +1,92 @@
+import { describe, it, expect, beforeAll } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { DocsReader } from "../../src/docs/docs-reader.js";
+import type { DocPage } from "@repowise-dev/types/docs";
+
+/**
+ * The metadata row under a page title carries the page's own model action and
+ * its freshness. Fresh is the quiet default and draws nothing; only a page
+ * that fell behind its code gets a mark, and that mark leads to doc drift.
+ */
+
+beforeAll(() => {
+ Element.prototype.scrollTo = () => {};
+});
+
+function makePage(overrides: Partial<DocPage> = {}): DocPage {
+ return {
+ id: "module_page:src/core",
+ repository_id: "r1",
+ page_type: "module_page",
+ title: "Core",
+ content: "The core module.",
+ target_path: "src/core",
+ source_hash: "h",
+ model_name: "m",
+ provider_name: "anthropic",
+ input_tokens: 0,
+ output_tokens: 0,
+ cached_tokens: 0,
+ generation_level: 3,
+ version: 1,
+ confidence: 1,
+ freshness_status: "fresh",
+ metadata: {},
+ created_at: "2026-08-01T00:00:00Z",
+ updated_at: "2026-08-01T00:00:00Z",
+ ...overrides,
+ } as DocPage;
+}
+
+function renderReader(page: DocPage, extra: Partial<Parameters<typeof DocsReader>[0]> = {}) {
+ return render(
+ <DocsReader
+ page={page}
+ repoId="r1"
+ persona="contributor"
+ sidebarOpen={false}
+ buildPageHref={(id) => `?page=${id}`}
+ LinkComponent={({ href, children, ...rest }) => (
+ <a href={href} {...rest}>
+ {children}
+ </a>
+ )}
+ {...extra}
+ />,
+ );
+}
+
+/** The row directly under the h1. */
+function metaRow() {
+ return screen.getByRole("heading", { level: 1 }).nextElementSibling as HTMLElement;
+}
+
+describe("DocsReader metadata row", () => {
+ it("renders the page action in the row under the title", () => {
+ renderReader(makePage(), {
+ pageActionSlot: <button>Rewrite with AI</button>,
+ });
+ expect(metaRow()).toContainElement(screen.getByRole("button", { name: "Rewrite with AI" }));
+ });
+
+ it("draws no freshness mark on a fresh page", () => {
+ renderReader(makePage(), { freshnessHref: "/drift" });
+ expect(metaRow().textContent).not.toMatch(/fresh|out of date/i);
+ expect(screen.queryByRole("link", { name: /out of date/i })).toBeNull();
+ });
+
+ it("marks a stale page and links the mark to doc drift", () => {
+ renderReader(makePage({ freshness_status: "stale" }), { freshnessHref: "/drift" });
+ const mark = screen.getByRole("link", { name: "May be out of date" });
+ expect(mark).toHaveAttribute("href", "/drift");
+ expect(metaRow()).toContainElement(mark);
+ });
+
+ it("takes the host's wording and stays plain text without an href", () => {
+ renderReader(makePage({ freshness_status: "outdated" }), {
+ freshnessLabels: { outdated: "Behind its code" },
+ });
+ expect(metaRow().textContent).toContain("Behind its code");
+ expect(screen.queryByRole("link", { name: "Behind its code" })).toBeNull();
+ });
+});
diff --git a/packages/ui/__tests__/wiki/regenerate-button.test.tsx b/packages/ui/__tests__/wiki/regenerate-button.test.tsx
index fe35bc556..5d11199b1 100644
--- a/packages/ui/__tests__/wiki/regenerate-button.test.tsx
+++ b/packages/ui/__tests__/wiki/regenerate-button.test.tsx
@@ -20,6 +20,17 @@ describe("RegenerateButton", () => {
expect(onRegenerate).toHaveBeenCalledTimes(1);
});
+ it("names the page in the quiet metadata-row trigger", () => {
+ const { rerender } = render(
+ <RegenerateButton mode="write" quiet onRegenerate={vi.fn()} />,
+ );
+ expect(screen.getByRole("button", { name: "Write this page with AI" })).toBeInTheDocument();
+ rerender(<RegenerateButton mode="regenerate" quiet onRegenerate={vi.fn()} />);
+ expect(screen.getByRole("button", { name: "Rewrite with AI" })).toBeInTheDocument();
+ rerender(<RegenerateButton quiet label="Translated" onRegenerate={vi.fn()} />);
+ expect(screen.getByRole("button", { name: "Translated" })).toBeInTheDocument();
+ });
+
it("disables the button while loading", () => {
render(<RegenerateButton onRegenerate={vi.fn()} isLoading />);
expect(screen.getByRole("button", { name: /regenerate/i })).toBeDisabled();
diff --git a/packages/ui/src/docs/docs-header.tsx b/packages/ui/src/docs/docs-header.tsx
index c0c3f2a14..aa7702f2d 100644
--- a/packages/ui/src/docs/docs-header.tsx
+++ b/packages/ui/src/docs/docs-header.tsx
@@ -46,7 +46,8 @@ export function DocsHeader({
<h1 className="sr-only">Documentation</h1>
<nav
- className="flex shrink-0 items-center rounded-lg bg-[var(--color-bg-elevated)] p-0.5"
+ // h-7 to match the bar's right-hand controls (Search, More).
+ className="flex h-7 shrink-0 items-center rounded-lg bg-[var(--color-bg-elevated)] p-0.5"
aria-label="Docs views"
>
{tabs.map((tab) => {
@@ -58,7 +59,7 @@ export function DocsHeader({
aria-current={tab.isActive ? "page" : undefined}
title={tab.label}
className={cn(
- "flex items-center gap-1.5 rounded-md px-2 py-1 text-xs font-medium whitespace-nowrap transition-colors sm:px-2.5",
+ "flex h-6 items-center gap-1.5 rounded-md px-2 text-xs font-medium whitespace-nowrap transition-colors sm:px-2.5",
tab.isActive
? "bg-[var(--color-bg-surface)] text-[var(--color-text-primary)] shadow-sm"
: "text-[var(--color-text-tertiary)] hover:text-[var(--color-text-secondary)]",
@@ -71,7 +72,7 @@ export function DocsHeader({
already marked by its filled ground. */}
<span className="hidden sm:inline">{tab.label}</span>
{tab.badge !== undefined && (
- <span className="font-mono text-[10px] tabular-nums text-[var(--color-text-tertiary)]">
+ <span className="font-mono text-[10px] font-normal tabular-nums text-[var(--color-text-tertiary)]">
{tab.badge}
</span>
)}
diff --git a/packages/ui/src/docs/docs-more-menu.tsx b/packages/ui/src/docs/docs-more-menu.tsx
new file mode 100644
index 000000000..bea4994a2
--- /dev/null
+++ b/packages/ui/src/docs/docs-more-menu.tsx
@@ -0,0 +1,245 @@
+"use client";
+
+import { useRef, useState, type ElementType, type KeyboardEvent, type ReactNode } from "react";
+import { MoreHorizontal, type LucideIcon } from "lucide-react";
+import { Spinner } from "../ui/spinner";
+import { Popover, PopoverContent, PopoverTrigger } from "../ui/popover";
+import { cn } from "../lib/cn";
+
+export interface DocsMenuItem {
+ key: string;
+ label: string;
+ icon?: LucideIcon;
+ /** Runs on select; the menu closes first. */
+ onSelect?: () => void;
+ /** A link item (a download, say) instead of a callback. */
+ href?: string;
+ download?: boolean;
+ disabled?: boolean;
+ /** "model" marks optional model work with the model colour. */
+ tone?: "model";
+ /** Set on a choice within a group; the item renders as a radio item. */
+ checked?: boolean;
+ /** A link to the view on screen: marked `aria-current="page"`, and the
+ * trigger reads as active so the way back is visible from the bar. */
+ current?: boolean;
+}
+
+/** Router-aware anchor for in-app link items (Next's `Link`, say). */
+export type DocsMenuLinkComponent = ElementType<{
+ href: string;
+ role: string;
+ className?: string;
+ onClick?: () => void;
+ "aria-current"?: "page";
+ children: ReactNode;
+}>;
+
+export interface DocsMenuGroup {
+ key: string;
+ /** Micro-label above the group, for a set of choices. */
+ label?: string;
+ items: DocsMenuItem[];
+ /** Shown only below `sm`, for a control the bar hides on a phone. Put it
+ * last: a hidden first group would leave the next one's divider on top. */
+ phoneOnly?: boolean;
+}
+
+const ITEM_SELECTOR = '[role^="menuitem"]:not([disabled])';
+
+/** Arrow keys, Home and End move focus between items, wrapping at the ends. */
+function moveFocus(event: KeyboardEvent<HTMLDivElement>) {
+ const keys = ["ArrowDown", "ArrowUp", "Home", "End"];
+ if (!keys.includes(event.key)) return;
+ // A phone-only group is still in the DOM above `sm`; skip what is not drawn.
+ const items = Array.from(
+ event.currentTarget.querySelectorAll<HTMLElement>(ITEM_SELECTOR),
+ ).filter((el) => el.checkVisibility?.() ?? true);
+ if (items.length === 0) return;
+ event.preventDefault();
+ const at = items.indexOf(document.activeElement as HTMLElement);
+ let next = 0;
+ if (event.key === "End") next = items.length - 1;
+ else if (event.key === "ArrowDown") next = (at + 1) % items.length;
+ else if (event.key === "ArrowUp") next = at <= 0 ? items.length - 1 : at - 1;
+ items[next]?.focus();
+}
+
+const ITEM_CLASS =
+ "flex w-full items-center gap-2 rounded px-2 py-1.5 text-left text-xs transition-colors hover:bg-[var(--color-bg-elevated)] focus-visible:bg-[var(--color-bg-elevated)] focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-inset focus-visible:ring-[var(--color-focus-ring)] disabled:pointer-events-none disabled:opacity-50";
+
+/** Base, tone and selected-state classes for one item. */
+function itemClass(item: DocsMenuItem): string {
+ const tone =
+ item.tone === "model"
+ ? "text-[var(--color-model)] hover:text-[var(--color-model-hover)]"
+ : "text-[var(--color-text-secondary)] hover:text-[var(--color-text-primary)]";
+ const selected = item.current || item.checked;
+ return cn(ITEM_CLASS, tone, selected && "font-medium text-[var(--color-text-primary)]");
+}
+
+function ItemContent({ item }: { item: DocsMenuItem }) {
+ const Icon = item.icon;
+ return (
+ <>
+ {Icon ? <Icon aria-hidden className="h-3.5 w-3.5 shrink-0" /> : null}
+ <span className="min-w-0 flex-1 truncate">{item.label}</span>
+ </>
+ );
+}
+
+/** A link item: router-aware for an in-app view, a plain anchor for a download. */
+function LinkItem({
+ item,
+ href,
+ close,
+ LinkComponent,
+}: {
+ item: DocsMenuItem;
+ href: string;
+ close: () => void;
+ LinkComponent?: DocsMenuLinkComponent | undefined;
+}) {
+ const shared = {
+ role: "menuitem",
+ href,
+ className: itemClass(item),
+ onClick: close,
+ ...(item.current ? { "aria-current": "page" as const } : {}),
+ };
+ const Anchor: DocsMenuLinkComponent =
+ LinkComponent && !item.download ? LinkComponent : "a";
+ return (
+ <Anchor {...shared} {...(item.download ? { download: true } : {})}>
+ <ItemContent item={item} />
+ </Anchor>
+ );
+}
+
+function MenuItem({
+ item,
+ close,
+ LinkComponent,
+}: {
+ item: DocsMenuItem;
+ close: (selected?: boolean) => void;
+ LinkComponent?: DocsMenuLinkComponent | undefined;
+}) {
+ if (item.href) {
+ return (
+ <LinkItem item={item} href={item.href} close={() => close()} LinkComponent={LinkComponent} />
+ );
+ }
+ const isChoice = item.checked !== undefined;
+ return (
+ <button
+ type="button"
+ role={isChoice ? "menuitemradio" : "menuitem"}
+ {...(isChoice ? { "aria-checked": item.checked } : {})}
+ disabled={item.disabled}
+ className={itemClass(item)}
+ onClick={() => {
+ close(true);
+ item.onSelect?.();
+ }}
+ >
+ <ItemContent item={item} />
+ </button>
+ );
+}
+
+/**
+ * One overflow menu for the docs bar. Everything that is not reading or
+ * searching lives here, so the bar carries one trigger instead of a row of
+ * buttons. The host builds the groups (and translates their labels); this
+ * shell only renders them and keeps the keyboard contract: focus lands on the
+ * first item, arrows move, Escape closes and returns focus to the trigger.
+ *
+ * Portalled, so the header's scrolling action row cannot clip it.
+ */
+export function DocsMoreMenu({
+ groups,
+ label = "More",
+ busy = false,
+ LinkComponent,
+}: {
+ groups: DocsMenuGroup[];
+ /** Renders in-app link items; without it they are plain anchors. */
+ LinkComponent?: DocsMenuLinkComponent;
+ /** Trigger label, and its accessible name on a phone where it is an icon. */
+ label?: string;
+ /** Shows a spinner on the trigger while a menu action runs (an export). */
+ busy?: boolean;
+}) {
+ const [open, setOpen] = useState(false);
+ // Set when an item ran an action: that action may open a dialog, and the
+ // popover handing focus back to its trigger would race the dialog's own.
+ const selectedRef = useRef(false);
+ const visible = groups.filter((g) => g.items.length > 0);
+ if (visible.length === 0) return null;
+ const current = visible.some((g) => g.items.some((i) => i.current));
+ const close = (selected = false) => {
+ selectedRef.current = selected;
+ setOpen(false);
+ };
+
+ return (
+ <Popover open={open} onOpenChange={setOpen}>
+ <PopoverTrigger asChild>
+ <button
+ type="button"
+ aria-haspopup="menu"
+ aria-expanded={open}
+ aria-label={label}
+ className={cn(
+ "flex h-7 shrink-0 items-center gap-1.5 rounded-md border bg-[var(--color-bg-elevated)] px-2 text-xs transition-colors hover:text-[var(--color-text-primary)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-focus-ring)] sm:px-2.5",
+ // A view inside the menu is on screen: the trigger takes the
+ // active-tab look, so the bar still says where the reader is.
+ current
+ ? "border-[var(--color-border-hover)] bg-[var(--color-bg-surface)] font-medium text-[var(--color-text-primary)] shadow-sm"
+ : "border-[var(--color-border-default)] text-[var(--color-text-secondary)]",
+ )}
+ >
+ {busy ? (
+ <Spinner size="sm" />
+ ) : (
+ <MoreHorizontal aria-hidden className="h-3.5 w-3.5" />
+ )}
+ <span className="hidden sm:inline">{label}</span>
+ </button>
+ </PopoverTrigger>
+ <PopoverContent
+ role="menu"
+ aria-label={label}
+ align="end"
+ className="w-60 p-1"
+ onKeyDown={moveFocus}
+ onCloseAutoFocus={(e) => {
+ if (selectedRef.current) e.preventDefault();
+ selectedRef.current = false;
+ }}
+ >
+ {visible.map((group, i) => (
+ <div
+ key={group.key}
+ role="group"
+ {...(group.label ? { "aria-label": group.label } : {})}
+ className={cn(
+ i > 0 && "mt-1 border-t border-[var(--color-border-default)] pt-1",
+ group.phoneOnly && "sm:hidden",
+ )}
+ >
+ {group.label ? (
+ <p className="px-2 pb-0.5 pt-1 font-mono text-[10px] uppercase tracking-[0.12em] text-[var(--color-text-tertiary)]">
+ {group.label}
+ </p>
+ ) : null}
+ {group.items.map((item) => (
+ <MenuItem key={item.key} item={item} close={close} LinkComponent={LinkComponent} />
+ ))}
+ </div>
+ ))}
+ </PopoverContent>
+ </Popover>
+ );
+}
diff --git a/packages/ui/src/docs/docs-page-actions.tsx b/packages/ui/src/docs/docs-page-actions.tsx
index 0a6fb5726..c7694e213 100644
--- a/packages/ui/src/docs/docs-page-actions.tsx
+++ b/packages/ui/src/docs/docs-page-actions.tsx
@@ -17,9 +17,51 @@ import { READER_PERSONAS, type ReaderPersona } from "./reader-persona";
import { cn } from "../lib/cn";
/**
- * Per-page controls for the DocsHeader row — the compact freshness badge and
- * the reader-level segmented control. The reader control renders only when
- * filtering actually changes this page; on curated pages it disappears.
+ * The reader-level segmented control: how much of a page to show. Render it
+ * only when filtering changes the page; on curated pages it is a no-op.
+ */
+export function ReaderLevelControl({
+ persona,
+ setPersona,
+ className,
+}: {
+ persona: ReaderPersona;
+ setPersona: (next: ReaderPersona) => void;
+ className?: string;
+}) {
+ return (
+ <div
+ className={cn(
+ "inline-flex items-center rounded-md border border-[var(--color-border-default)] p-0.5 shrink-0",
+ className,
+ )}
+ role="group"
+ aria-label="Reader level"
+ >
+ {READER_PERSONAS.map((p) => (
+ <button
+ key={p.value}
+ onClick={() => setPersona(p.value)}
+ title={p.hint}
+ aria-pressed={persona === p.value}
+ className={cn(
+ "rounded px-1.5 py-0.5 text-[10px] font-medium transition-colors",
+ persona === p.value
+ ? "bg-[var(--color-control-selected)] text-[var(--color-control-selected-text)]"
+ : "text-[var(--color-text-tertiary)] hover:text-[var(--color-text-primary)]",
+ )}
+ >
+ {p.label}
+ </button>
+ ))}
+ </div>
+ );
+}
+
+/**
+ * Per-page controls for the DocsHeader row: the compact freshness badge and
+ * the reader-level control. The reader control renders only when filtering
+ * actually changes this page; on curated pages it disappears.
*/
export function DocsPageActions({
confidence,
@@ -38,27 +80,7 @@ export function DocsPageActions({
<>
<ConfidenceBadge score={confidence} status={freshnessStatus} compact />
{personaHasEffect && (
- <div
- className="inline-flex items-center rounded-md border border-[var(--color-border-default)] p-0.5 shrink-0"
- role="group"
- aria-label="Reader level"
- >
- {READER_PERSONAS.map((p) => (
- <button
- key={p.value}
- onClick={() => setPersona(p.value)}
- title={p.hint}
- className={cn(
- "rounded px-1.5 py-0.5 text-[10px] font-medium transition-colors",
- persona === p.value
- ? "bg-[var(--color-control-selected)] text-[var(--color-control-selected-text)]"
- : "text-[var(--color-text-tertiary)] hover:text-[var(--color-text-primary)]",
- )}
- >
- {p.label}
- </button>
- ))}
- </div>
+ <ReaderLevelControl persona={persona} setPersona={setPersona} />
)}
</>
);
diff --git a/packages/ui/src/docs/docs-reader.tsx b/packages/ui/src/docs/docs-reader.tsx
index 70f2f57c7..863d4a399 100644
--- a/packages/ui/src/docs/docs-reader.tsx
+++ b/packages/ui/src/docs/docs-reader.tsx
@@ -126,6 +126,77 @@ interface DocsReaderProps {
* on AI-written pages so only auto pages advertise the upgrade.
*/
upgradeSlot?: React.ReactNode;
+ /**
+ * The page's own model action ("Write this page with AI" / "Rewrite with
+ * AI"), rendered at the end of the metadata row under the title. Host owns
+ * the launch and decides which pages can be written; omit it elsewhere.
+ */
+ pageActionSlot?: React.ReactNode;
+ /**
+ * Where the "out of date" mark in the metadata row links (the host's doc
+ * drift view). Without it the mark is plain text. A fresh page shows no mark.
+ */
+ freshnessHref?: string | undefined;
+ /** Overrides for the out-of-date wording, for a host translating it. */
+ freshnessLabels?: FreshnessLabels | undefined;
+}
+
+export interface FreshnessLabels {
+ /** `freshness_status: "stale"`: the code moved since the page was written. */
+ stale?: string;
+ /** `freshness_status: "outdated"`. */
+ outdated?: string;
+}
+
+const DEFAULT_FRESHNESS_LABELS: Required<FreshnessLabels> = {
+ stale: "May be out of date",
+ outdated: "Out of date",
+};
+
+/**
+ * Freshness as metadata: nothing when the page is fresh (the quiet default),
+ * a warning dot and a word when it is not. Keyed on the stored status only;
+ * the confidence score is not a freshness signal for pages built from the
+ * index, so it is never used as a fallback here.
+ */
+function FreshnessMark({
+ status,
+ href,
+ labels,
+ LinkComponent,
+}: {
+ status: string | undefined;
+ href?: string | undefined;
+ labels?: FreshnessLabels | undefined;
+ LinkComponent: ReaderLinkComponent;
+}) {
+ if (status !== "stale" && status !== "outdated") return null;
+ const text = labels?.[status] ?? DEFAULT_FRESHNESS_LABELS[status];
+ const inner = (
+ <>
+ <span
+ aria-hidden
+ className="h-1.5 w-1.5 shrink-0 rounded-full bg-[var(--color-warning)]"
+ />
+ {text}
+ </>
+ );
+ const cls = "inline-flex items-center gap-1.5 text-[var(--color-text-secondary)]";
+ return (
+ <>
+ {href ? (
+ <LinkComponent
+ href={href}
+ className={cn(cls, "hover:text-[var(--color-text-primary)] hover:underline")}
+ >
+ {inner}
+ </LinkComponent>
+ ) : (
+ <span className={cls}>{inner}</span>
+ )}
+ <span aria-hidden className="opacity-40">&middot;</span>
+ </>
+ );
}
export function DocsReader({
@@ -144,6 +215,9 @@ export function DocsReader({
intelligenceSlot,
versionHistorySlot,
upgradeSlot,
+ pageActionSlot,
+ freshnessHref,
+ freshnessLabels,
}: DocsReaderProps) {
const scrollRef = useRef<HTMLDivElement>(null);
@@ -217,6 +291,9 @@ export function DocsReader({
intelligenceSlot={intelligenceSlot}
versionHistorySlot={versionHistorySlot}
upgradeSlot={upgradeSlot}
+ pageActionSlot={pageActionSlot}
+ freshnessHref={freshnessHref}
+ freshnessLabels={freshnessLabels}
/>
);
}
@@ -273,6 +350,9 @@ function DocsReaderBody({
intelligenceSlot,
versionHistorySlot,
upgradeSlot,
+ pageActionSlot,
+ freshnessHref,
+ freshnessLabels,
}: {
page: DocPage;
pages: DocPageSummary[];
@@ -287,6 +367,9 @@ function DocsReaderBody({
intelligenceSlot?: React.ReactNode;
versionHistorySlot?: React.ReactNode;
upgradeSlot?: React.ReactNode;
+ pageActionSlot?: React.ReactNode;
+ freshnessHref?: string | undefined;
+ freshnessLabels?: FreshnessLabels | undefined;
}) {
const nav = useMemo(() => computeDocNav(page, pages), [page, pages]);
const wikiLinks = useMemo(() => getWikiLinks(page.metadata), [page.metadata]);
@@ -492,11 +575,9 @@ function DocsReaderBody({
</h1>
{/* One quiet provenance line: what kind of page this is, who wrote
- it, and when. Previously this row carried an accent-filled
- "Regenerate" pill immediately beside the h1, which read as a
- statement about the page rather than an action on it and
- out-shouted the title. The upgrade affordance now sits at the
- end of the content, where a reader has seen the page is thin.
+ it, when, and whether it fell behind its code. A host's page
+ action (`pageActionSlot`) ends the row as plain model-coloured
+ text, so it never competes with the title.
"Written by <model>" / "Built from the index" is the Overview
page's vocabulary, deliberately: a page can lack prose because
@@ -515,6 +596,12 @@ function DocsReaderBody({
: "Written by a model"}
</span>
<span aria-hidden className="opacity-40">&middot;</span>
+ <FreshnessMark
+ status={page.freshness_status}
+ href={freshnessHref}
+ labels={freshnessLabels}
+ LinkComponent={LinkComponent}
+ />
<span title={page.updated_at}>
updated {formatRelativeTime(page.updated_at)}
</span>
@@ -572,6 +659,7 @@ function DocsReaderBody({
Open file page <span aria-hidden>&rarr;</span>
</LinkComponent>
)}
+ {pageActionSlot}
</div>
{/* What this page was written from. The rail carried this as
diff --git a/packages/ui/src/docs/index.ts b/packages/ui/src/docs/index.ts
index 2300b31ed..d996a18db 100644
--- a/packages/ui/src/docs/index.ts
+++ b/packages/ui/src/docs/index.ts
@@ -5,3 +5,4 @@ export * from "./reader-persona";
export * from "./docs-reader";
export * from "./docs-header";
export * from "./docs-page-actions";
+export * from "./docs-more-menu";
diff --git a/packages/ui/src/wiki/regenerate-button.tsx b/packages/ui/src/wiki/regenerate-button.tsx
index 62f2628b2..7d9df126e 100644
--- a/packages/ui/src/wiki/regenerate-button.tsx
+++ b/packages/ui/src/wiki/regenerate-button.tsx
@@ -39,6 +39,12 @@ export interface RegenerateButtonProps {
* copy (e.g. next to the provenance pill) rather than a toolbar. The
* progress dialog is unchanged. */
inline?: boolean;
+ /** Plain model-coloured text for a page's metadata row: no ground, no
+ * border. Its default label names the page ("Write this page with AI" /
+ * "Rewrite with AI"). Takes precedence over `inline`. */
+ quiet?: boolean;
+ /** Overrides the visible label (a host translating it, say). */
+ label?: string;
}
export function RegenerateButton({
@@ -49,13 +55,29 @@ export function RegenerateButton({
onDialogClose,
jobSlot,
inline = false,
+ quiet = false,
+ label,
}: RegenerateButtonProps) {
const isWrite = mode === "write";
const Icon = isWrite ? Sparkles : RefreshCw;
return (
<>
- {inline ? (
+ {quiet ? (
+ <button
+ type="button"
+ onClick={onRegenerate}
+ disabled={isLoading || isInProgress}
+ className="inline-flex shrink-0 items-center gap-1 rounded text-xs font-medium text-[var(--color-model)] transition-colors hover:text-[var(--color-model-hover)] hover:underline focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-model)] disabled:opacity-60"
+ >
+ {isLoading ? (
+ <Spinner className="h-3 w-3" />
+ ) : (
+ <Icon aria-hidden className="h-3 w-3" />
+ )}
+ {label ?? (isWrite ? "Write this page with AI" : "Rewrite with AI")}
+ </button>
+ ) : inline ? (
<button
type="button"
onClick={onRegenerate}
@@ -68,7 +90,7 @@ export function RegenerateButton({
) : (
<Icon className="h-2.5 w-2.5" />
)}
- {isWrite ? "Write with AI" : "Regenerate"}
+ {label ?? (isWrite ? "Write with AI" : "Regenerate")}
</button>
) : (
<Button
@@ -94,7 +116,7 @@ export function RegenerateButton({
/>
)}
<span className="hidden sm:inline">
- {isWrite ? "Write with AI" : "Regenerate"}
+ {label ?? (isWrite ? "Write with AI" : "Regenerate")}
</span>
</Button>
)}
diff --git a/packages/web/messages/en.json b/packages/web/messages/en.json
index 0f82e87fb..e4b5d39f4 100644
--- a/packages/web/messages/en.json
+++ b/packages/web/messages/en.json
@@ -1269,7 +1269,11 @@
"agentAuthored": "Agent-authored",
"renamedFrom": "Renamed from",
"historyCapped": "History capped during indexing, so older commits are not counted above.",
- "signals": "Signals"
+ "signals": "Signals",
+ "freshness": {
+ "stale": "May be out of date",
+ "outdated": "Out of date"
+ }
},
"explorer": {
"emptyTitle": "No documentation yet",
@@ -1277,10 +1281,19 @@
"hideTree": "Hide pages tree",
"showTree": "Show pages tree",
"askQuestion": "Explain \"{title}\" using the source code, and name the files it rests on.",
- "askLabel": "Ask about {title}"
+ "askLabel": "Ask about {title}",
+ "more": "More",
+ "menu": {
+ "exportPage": "Export this page (Markdown)",
+ "exportAll": "Export all pages (Markdown)",
+ "exportZip": "Download ZIP archive",
+ "present": "Present",
+ "readerLevel": "Reader level"
+ }
},
"bulk": {
- "button": "Write subsystem pages",
+ "button": "Write {count, plural, one {# page} other {# pages}} with AI",
+ "buttonShort": "Write with AI",
"title": "Write the subsystem pages",
"writing": "Writing the subsystem pages"
},
@@ -1290,7 +1303,9 @@
"writeWithAi": "Write with AI"
},
"pageGenerate": {
- "failed": "Couldn't start generation"
+ "failed": "Couldn't start generation",
+ "write": "Write this page with AI",
+ "rewrite": "Rewrite with AI"
}
},
"zoom": {
diff --git a/packages/web/messages/zh-CN.json b/packages/web/messages/zh-CN.json
index 6871097ae..7efed4ee4 100644
--- a/packages/web/messages/zh-CN.json
+++ b/packages/web/messages/zh-CN.json
@@ -1269,7 +1269,11 @@
"agentAuthored": "智能体撰写",
"renamedFrom": "重命名自",
"historyCapped": "索引时历史记录已截断,因此更早的提交未计入上方统计。",
- "signals": "信号"
+ "signals": "信号",
+ "freshness": {
+ "stale": "可能已过时",
+ "outdated": "已过时"
+ }
},
"explorer": {
"emptyTitle": "还没有文档",
@@ -1277,10 +1281,19 @@
"hideTree": "隐藏页面树",
"showTree": "显示页面树",
"askQuestion": "结合源码解释「{title}」,并列出它所依赖的文件。",
- "askLabel": "就 {title} 提问"
+ "askLabel": "就 {title} 提问",
+ "more": "更多",
+ "menu": {
+ "exportPage": "导出此页面(Markdown)",
+ "exportAll": "导出全部页面(Markdown)",
+ "exportZip": "下载 ZIP 压缩包",
+ "present": "演示",
+ "readerLevel": "阅读深度"
+ }
},
"bulk": {
- "button": "撰写子系统页面",
+ "button": "用 AI 撰写 {count} 个页面",
+ "buttonShort": "用 AI 撰写",
"title": "撰写子系统页面",
"writing": "正在撰写子系统页面"
},
@@ -1290,7 +1303,9 @@
"writeWithAi": "用 AI 撰写"
},
"pageGenerate": {
- "failed": "无法启动生成"
+ "failed": "无法启动生成",
+ "write": "用 AI 撰写此页面",
+ "rewrite": "用 AI 重写"
}
},
"zoom": {
diff --git a/packages/web/src/components/docs/bulk-generate-button.tsx b/packages/web/src/components/docs/bulk-generate-button.tsx
deleted file mode 100644
index 4845d3800..000000000
--- a/packages/web/src/components/docs/bulk-generate-button.tsx
+++ /dev/null
@@ -1,52 +0,0 @@
-"use client";
-
-import { Sparkles } from "lucide-react";
-import { Button } from "@repowise-dev/ui/ui/button";
-import { BulkGenerateConfirm } from "./bulk-generate-confirm";
-import { BulkGenerateProgress } from "./bulk-generate-progress";
-import { useBulkGenerate } from "@/lib/hooks/use-bulk-generate";
-import { useTranslations } from "next-intl";
-
-/**
- * The one bulk generation action, mounted in the docs header. Writes every
- * subsystem page still rendered from structure, with a single cost estimate.
- * Shown by the header only while stubs remain, so it retires itself once the
- * wiki is fully written.
- */
-export function BulkGenerateButton({
- repoId,
- onGenerated,
-}: {
- repoId: string;
- /** Called once a run completes so the host can refresh the page list. */
- onGenerated?: () => void;
-}) {
- const t = useTranslations("docs");
- const bulk = useBulkGenerate(repoId);
-
- return (
- <>
- <Button
- variant="outline"
- size="sm"
- onClick={bulk.open}
- disabled={bulk.jobId != null}
- className="h-7 gap-1.5 text-xs"
- >
- <Sparkles className="h-3.5 w-3.5" />
- <span className="hidden sm:inline">{t("bulk.button")}</span>
- </Button>
-
- <BulkGenerateConfirm
- flow={bulk}
- repoId={repoId}
- title={t("bulk.title")}
- />
-
- <BulkGenerateProgress
- flow={bulk}
- {...(onGenerated ? { onGenerated } : {})}
- />
- </>
- );
-}
diff --git a/packages/web/src/components/docs/bulk-generate-dialogs.tsx b/packages/web/src/components/docs/bulk-generate-dialogs.tsx
new file mode 100644
index 000000000..e41133b3a
--- /dev/null
+++ b/packages/web/src/components/docs/bulk-generate-dialogs.tsx
@@ -0,0 +1,67 @@
+"use client";
+
+import { Sparkles } from "lucide-react";
+import { Spinner } from "@repowise-dev/ui/ui/spinner";
+import { BulkGenerateConfirm } from "./bulk-generate-confirm";
+import { BulkGenerateProgress } from "./bulk-generate-progress";
+import { type useBulkGenerate } from "@/lib/hooks/use-bulk-generate";
+import { useTranslations } from "next-intl";
+
+/**
+ * The bar's one model action: write every subsystem page still built from the
+ * index. Renders only while such pages remain (`count > 0`). On a
+ * phone the label shortens; the count stays in the accessible name.
+ */
+export function BulkWriteButton({
+ count,
+ running,
+ onClick,
+}: {
+ count: number;
+ running: boolean;
+ onClick: () => void;
+}) {
+ const t = useTranslations("docs");
+ if (count <= 0) return null;
+ const label = t("bulk.button", { count });
+ return (
+ <button
+ type="button"
+ onClick={onClick}
+ disabled={running}
+ aria-label={label}
+ className="flex h-7 shrink-0 items-center gap-1.5 rounded-md border border-[var(--color-model)]/40 bg-[var(--color-model-muted)] px-2 text-xs font-medium text-[var(--color-model)] transition-colors hover:text-[var(--color-model-hover)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-model)] disabled:opacity-60 sm:px-2.5"
+ >
+ {running ? <Spinner size="sm" /> : <Sparkles aria-hidden className="h-3.5 w-3.5" />}
+ <span className="sm:hidden">{t("bulk.buttonShort")}</span>
+ <span className="hidden sm:inline">{label}</span>
+ </button>
+ );
+}
+
+/**
+ * The confirm and progress dialogs behind `BulkWriteButton`. Mounted on their
+ * own so a run's progress outlives the button, which the bar drops once no
+ * subsystem page is left to write.
+ */
+export function BulkGenerateDialogs({
+ flow,
+ repoId,
+ onGenerated,
+}: {
+ flow: ReturnType<typeof useBulkGenerate>;
+ repoId: string;
+ /** Called once a run completes so the host can refresh the page list. */
+ onGenerated?: () => void;
+}) {
+ const t = useTranslations("docs");
+ return (
+ <>
+ <BulkGenerateConfirm flow={flow} repoId={repoId} title={t("bulk.title")} />
+ <BulkGenerateProgress
+ flow={flow}
+ {...(onGenerated ? { onGenerated } : {})}
+ />
+ </>
+ );
+}
diff --git a/packages/web/src/components/docs/bulk-write-button.test.tsx b/packages/web/src/components/docs/bulk-write-button.test.tsx
new file mode 100644
index 000000000..245a41982
--- /dev/null
+++ b/packages/web/src/components/docs/bulk-write-button.test.tsx
@@ -0,0 +1,43 @@
+// @vitest-environment jsdom
+
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { NextIntlClientProvider } from "next-intl";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import zhMessages from "../../../messages/zh-CN.json";
+import { BulkWriteButton } from "./bulk-generate-dialogs";
+
+describe("BulkWriteButton", () => {
+ afterEach(cleanup);
+ it("names how many pages it writes and opens the flow", () => {
+ const onClick = vi.fn();
+ render(<BulkWriteButton count={12} running={false} onClick={onClick} />);
+ const button = screen.getByRole("button", { name: "Write 12 pages with AI" });
+ fireEvent.click(button);
+ expect(onClick).toHaveBeenCalledTimes(1);
+ expect(button.className).toContain("--color-model");
+ });
+
+ it("uses the singular for one page", () => {
+ render(<BulkWriteButton count={1} running={false} onClick={vi.fn()} />);
+ expect(screen.getByRole("button", { name: "Write 1 page with AI" })).toBeTruthy();
+ });
+
+ it("is disabled while a run is going", () => {
+ render(<BulkWriteButton count={3} running onClick={vi.fn()} />);
+ expect(screen.getByRole("button", { name: "Write 3 pages with AI" })).toHaveProperty("disabled", true);
+ });
+
+ it("renders nothing once no page is left to write", () => {
+ const { container } = render(<BulkWriteButton count={0} running={false} onClick={vi.fn()} />);
+ expect(container.innerHTML).toBe("");
+ });
+
+ it("carries the zh-CN copy", () => {
+ render(
+ <NextIntlClientProvider locale="zh-CN" messages={zhMessages}>
+ <BulkWriteButton count={12} running={false} onClick={vi.fn()} />
+ </NextIntlClientProvider>,
+ );
+ expect(screen.getByRole("button", { name: "用 AI 撰写 12 个页面" })).toBeTruthy();
+ });
+});
diff --git a/packages/web/src/components/docs/docs-explorer.tsx b/packages/web/src/components/docs/docs-explorer.tsx
index d49246491..883a712cc 100644
--- a/packages/web/src/components/docs/docs-explorer.tsx
+++ b/packages/web/src/components/docs/docs-explorer.tsx
@@ -9,7 +9,6 @@ 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 {
- PresentButton,
PresentOverlay,
buildPresentModel,
canPresent,
@@ -25,14 +24,14 @@ import { DocsHeader } from "./docs-header";
import { DocsViewer } from "./docs-viewer";
import { AskAboutThis } from "@repowise-dev/ui/chat";
import {
- DocsPageActions,
- ExportMenu,
+ ReaderLevelControl,
SidebarToggle,
-} from "./docs-page-actions";
-import { PageGenerateButton } from "./page-generate-button";
-import { BulkGenerateButton } from "./bulk-generate-button";
+} 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 { isModelWrittenType, isStubPage } from "@repowise-dev/ui/lib/page-types";
+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";
@@ -105,12 +104,14 @@ export function DocsExplorer({ repoId }: DocsExplorerProps) {
[selectedPage],
);
- // The docs header offers one bulk "write the subsystem pages" action, shown
- // only while concept pages are still stubs. A structural page is never a stub.
- const hasStubs = useMemo(
- () => pages.some((p) => isStubPage(p)),
+ // 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
@@ -235,6 +236,25 @@ export function DocsExplorer({ repoId }: DocsExplorerProps) {
}
}, [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.
@@ -363,13 +383,15 @@ export function DocsExplorer({ repoId }: DocsExplorerProps) {
</button>
<div className="flex flex-1 min-w-0 flex-col">
- <DocsHeader>
- {selectedPage && (
- <DocsPageActions
- page={selectedPage}
+ {/* 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}
- personaHasEffect={personaHasEffect}
+ className="hidden sm:inline-flex"
/>
)}
{selectedPage && (
@@ -385,17 +407,15 @@ export function DocsExplorer({ repoId }: DocsExplorerProps) {
className="shrink-0"
/>
)}
- {selectedPage && isModelWrittenType(selectedPage.page_type) && (
- <PageGenerateButton
- page={selectedPage}
- repoId={repoId}
- onGenerated={handleGenerated}
- />
- )}
- {hasStubs && <BulkGenerateButton repoId={repoId} onGenerated={handleGenerated} />}
+ <BulkWriteButton
+ count={stubCount}
+ running={bulk.jobId != null}
+ onClick={bulk.open}
+ />
<button
onClick={() => setSearchOpen(true)}
- className="flex items-center gap-2 rounded-md border border-[var(--color-border-default)] bg-[var(--color-bg-elevated)] px-2.5 py-1.5 text-xs text-[var(--color-text-tertiary)] transition-colors hover:text-[var(--color-text-secondary)]"
+ 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>
@@ -403,14 +423,6 @@ export function DocsExplorer({ repoId }: DocsExplorerProps) {
⌘K
</kbd>
</button>
- <ExportMenu
- isExporting={isExporting}
- onExportAll={handleExportAll}
- zipHref={`/api/repos/${repoId}/export`}
- page={selectedPage}
- repoId={repoId}
- />
- {presentable && <PresentButton onClick={() => setPresent(true)} />}
{selectedPage && (
<SidebarToggle
open={sidebarOpen}
@@ -419,6 +431,8 @@ export function DocsExplorer({ repoId }: DocsExplorerProps) {
)}
</DocsHeader>
+ <BulkGenerateDialogs flow={bulk} repoId={repoId} onGenerated={handleGenerated} />
+
{/* Only while pages are still rendered from structure. */}
<HostedNudgeSlot
candidates={[hasStubs && "docs"]}
diff --git a/packages/web/src/components/docs/docs-header.test.tsx b/packages/web/src/components/docs/docs-header.test.tsx
new file mode 100644
index 000000000..84079d5a1
--- /dev/null
+++ b/packages/web/src/components/docs/docs-header.test.tsx
@@ -0,0 +1,67 @@
+// @vitest-environment jsdom
+
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const nav = vi.hoisted(() => ({ pathname: "/repos/r1/docs" }));
+
+vi.mock("next/navigation", () => ({
+ usePathname: () => nav.pathname,
+ useParams: () => ({ id: "r1" }),
+}));
+vi.mock("swr", () => ({ default: () => ({ data: undefined }) }));
+vi.mock("@/lib/api/doc-drift", () => ({ getDocDrift: vi.fn() }));
+
+import { DocsHeader } from "./docs-header";
+
+function openMore() {
+ fireEvent.click(screen.getByRole("button", { name: "More" }));
+}
+
+describe("DocsHeader", () => {
+ afterEach(cleanup);
+ beforeEach(() => {
+ nav.pathname = "/repos/r1/docs";
+ });
+
+ it("switches between Explorer and Doc drift only", () => {
+ render(<DocsHeader />);
+ const views = screen.getByRole("navigation", { name: "Docs views" });
+ expect(Array.from(views.querySelectorAll("a")).map((a) => a.getAttribute("href"))).toEqual([
+ "/repos/r1/docs",
+ "/repos/r1/docs/drift",
+ ]);
+ });
+
+ it("links Doc freshness from the More menu", () => {
+ render(<DocsHeader />);
+ openMore();
+ const item = screen.getByRole("menuitem", { name: "Doc freshness" });
+ expect(item.getAttribute("href")).toBe("/repos/r1/docs/coverage");
+ expect(item.getAttribute("aria-current")).toBeNull();
+ });
+
+ it("marks Doc freshness as the current view on its route", () => {
+ nav.pathname = "/repos/r1/docs/coverage";
+ render(<DocsHeader />);
+ const views = screen.getByRole("navigation", { name: "Docs views" });
+ expect(views.querySelector('[aria-current="page"]')).toBeNull();
+ openMore();
+ expect(
+ screen.getByRole("menuitem", { name: "Doc freshness" }).getAttribute("aria-current"),
+ ).toBe("page");
+ });
+
+ it("appends the page's own items after the view link", () => {
+ render(
+ <DocsHeader
+ menuGroups={[{ key: "export", items: [{ key: "zip", label: "Download ZIP archive", href: "/x.zip", download: true }] }]}
+ />,
+ );
+ openMore();
+ expect(screen.getAllByRole("menuitem").map((i) => i.textContent)).toEqual([
+ "Doc freshness",
+ "Download ZIP archive",
+ ]);
+ });
+});
diff --git a/packages/web/src/components/docs/docs-header.tsx b/packages/web/src/components/docs/docs-header.tsx
index 39de82e55..3a0464b87 100644
--- a/packages/web/src/components/docs/docs-header.tsx
+++ b/packages/web/src/components/docs/docs-header.tsx
@@ -1,6 +1,7 @@
"use client";
import Link from "next/link";
+import { BarChart3 } from "lucide-react";
import { useParams, usePathname } from "next/navigation";
import { useTranslations } from "next-intl";
import useSWR from "swr";
@@ -8,23 +9,39 @@ import {
DocsHeader as DocsHeaderShell,
type DocsHeaderTab,
} from "@repowise-dev/ui/docs/docs-header";
+import {
+ DocsMoreMenu,
+ type DocsMenuGroup,
+} from "@repowise-dev/ui/docs/docs-more-menu";
import type { DocDriftResponse } from "@repowise-dev/types/doc-drift";
import { getDocDrift } from "@/lib/api/doc-drift";
-// "Doc freshness", not "Coverage" — coverage means test coverage everywhere
-// else in the app; this tab is about documentation staleness.
const TABS = [
{ labelKey: "explorer", segment: "", icon: "explorer" as const },
- { labelKey: "freshness", segment: "/coverage", icon: "freshness" as const },
{ labelKey: "drift", segment: "/drift", icon: "drift" as const },
];
+// "Doc freshness", not "Coverage": coverage means test coverage everywhere
+// else in the app. A secondary view, so it is a link in More, not a tab.
+const FRESHNESS_SEGMENT = "/coverage";
+
/**
* Web wrapper: resolves the route-aware tab list and injects Next's ``Link``
* into the presentational ``DocsHeader`` ui shell.
*/
-export function DocsHeader({ children }: { children?: React.ReactNode }) {
+export function DocsHeader({
+ children,
+ menuGroups = [],
+ menuBusy = false,
+}: {
+ children?: React.ReactNode;
+ /** The page's own More items (export, present...). The view link is added here. */
+ menuGroups?: DocsMenuGroup[];
+ /** Spinner on the More trigger while one of its actions runs. */
+ menuBusy?: boolean;
+}) {
const t = useTranslations("views.docsTabs");
+ const td = useTranslations("docs");
const pathname = usePathname();
const { id } = useParams<{ id: string }>();
const basePath = `/repos/${id}/docs`;
@@ -51,9 +68,32 @@ export function DocsHeader({ children }: { children?: React.ReactNode }) {
};
});
+ const freshnessHref = `${basePath}${FRESHNESS_SEGMENT}`;
+ const groups: DocsMenuGroup[] = [
+ {
+ key: "views",
+ items: [
+ {
+ key: "freshness",
+ label: t("freshness"),
+ icon: BarChart3,
+ href: freshnessHref,
+ current: pathname.startsWith(freshnessHref),
+ },
+ ],
+ },
+ ...menuGroups,
+ ];
+
return (
<DocsHeaderShell tabs={tabs} LinkComponent={Link}>
{children}
+ <DocsMoreMenu
+ label={td("explorer.more")}
+ busy={menuBusy}
+ groups={groups}
+ LinkComponent={Link}
+ />
</DocsHeaderShell>
);
}
diff --git a/packages/web/src/components/docs/docs-menu.test.ts b/packages/web/src/components/docs/docs-menu.test.ts
new file mode 100644
index 000000000..e6478009e
--- /dev/null
+++ b/packages/web/src/components/docs/docs-menu.test.ts
@@ -0,0 +1,53 @@
+import { describe, expect, it, vi } from "vitest";
+import { buildDocsMenuGroups, type DocsMenuInput } from "./docs-menu";
+
+const t = (key: string) => key;
+
+function input(over: Partial<DocsMenuInput> = {}): DocsMenuInput {
+ return {
+ t,
+ hasPage: true,
+ onExportPage: vi.fn(),
+ onExportAll: vi.fn(),
+ exporting: false,
+ zipHref: "/api/repos/r1/export",
+ onPresent: vi.fn(),
+ reader: null,
+ ...over,
+ };
+}
+
+const keys = (over: Partial<DocsMenuInput> = {}) =>
+ buildDocsMenuGroups(input(over)).flatMap((g) => g.items.map((i) => i.key));
+
+describe("buildDocsMenuGroups", () => {
+ it("holds export and present, and leaves the bulk write to the bar", () => {
+ expect(keys()).toEqual(["export-page", "export-all", "export-zip", "present"]);
+ });
+
+ it("holds the exports while one is running", () => {
+ const items = buildDocsMenuGroups(input({ exporting: true })).flatMap((g) => g.items);
+ expect(items.find((i) => i.key === "export-all")?.disabled).toBe(true);
+ expect(items.find((i) => i.key === "export-page")?.disabled).toBe(true);
+ });
+
+ it("offers present only when there is a deck", () => {
+ expect(keys({ onPresent: null })).not.toContain("present");
+ });
+
+ it("leaves out the page export without a page", () => {
+ expect(keys({ hasPage: false })).not.toContain("export-page");
+ });
+
+ it("carries the reader level as a phone-only last group", () => {
+ const setPersona = vi.fn();
+ const groups = buildDocsMenuGroups(
+ input({ reader: { persona: "deep", setPersona } }),
+ );
+ const reader = groups[groups.length - 1]!;
+ expect(reader.phoneOnly).toBe(true);
+ expect(reader.items.find((i) => i.checked)?.key).toBe("reader-deep");
+ reader.items[0]!.onSelect?.();
+ expect(setPersona).toHaveBeenCalledWith("overview");
+ });
+});
diff --git a/packages/web/src/components/docs/docs-menu.ts b/packages/web/src/components/docs/docs-menu.ts
new file mode 100644
index 000000000..4d3ff5a7e
--- /dev/null
+++ b/packages/web/src/components/docs/docs-menu.ts
@@ -0,0 +1,60 @@
+import { Download, FileText, FolderArchive, Presentation } from "lucide-react";
+import type { DocsMenuGroup } from "@repowise-dev/ui/docs/docs-more-menu";
+import { READER_PERSONAS, type ReaderPersona } from "@repowise-dev/ui/docs/reader-persona";
+
+type Translate = (key: string) => string;
+
+export interface DocsMenuInput {
+ t: Translate;
+ /** A page is open, so "Export this page" applies. */
+ hasPage: boolean;
+ onExportPage: () => void;
+ onExportAll: () => void;
+ /** An export is running; its items wait until it finishes. */
+ exporting: boolean;
+ zipHref: string;
+ /** Present opens only when the deck has pages to draw on. */
+ onPresent: (() => void) | null;
+ /** The reader-level choice, for a phone where the bar hides its control. */
+ reader: { persona: ReaderPersona; setPersona: (next: ReaderPersona) => void } | null;
+}
+
+/**
+ * The explorer's More items: export and present, grouped by kind. The bulk
+ * model action sits in the bar itself, and the view links come from the header. The reader-level group is phone-only and last, since the
+ * bar shows that control itself from `sm` up.
+ */
+export function buildDocsMenuGroups(input: DocsMenuInput): DocsMenuGroup[] {
+ const { t, onPresent, reader } = input;
+ return [
+ {
+ key: "export",
+ items: [
+ ...(input.hasPage
+ ? [{ key: "export-page", label: t("explorer.menu.exportPage"), icon: Download, onSelect: input.onExportPage, disabled: input.exporting }]
+ : []),
+ { key: "export-all", label: t("explorer.menu.exportAll"), icon: FileText, onSelect: input.onExportAll, disabled: input.exporting },
+ { key: "export-zip", label: t("explorer.menu.exportZip"), icon: FolderArchive, href: input.zipHref, download: true },
+ ],
+ },
+ {
+ key: "present",
+ items: onPresent
+ ? [{ key: "present", label: t("explorer.menu.present"), icon: Presentation, onSelect: onPresent }]
+ : [],
+ },
+ {
+ key: "reader",
+ label: t("explorer.menu.readerLevel"),
+ phoneOnly: true,
+ items: reader
+ ? READER_PERSONAS.map((p) => ({
+ key: `reader-${p.value}`,
+ label: p.label,
+ checked: reader.persona === p.value,
+ onSelect: () => reader.setPersona(p.value),
+ }))
+ : [],
+ },
+ ];
+}
diff --git a/packages/web/src/components/docs/docs-page-actions.tsx b/packages/web/src/components/docs/docs-page-actions.tsx
deleted file mode 100644
index aba92a953..000000000
--- a/packages/web/src/components/docs/docs-page-actions.tsx
+++ /dev/null
@@ -1,70 +0,0 @@
-"use client";
-
-import {
- DocsPageActions as DocsPageActionsShell,
- ExportMenu as ExportMenuShell,
- SidebarToggle,
-} from "@repowise-dev/ui/docs/docs-page-actions";
-import { downloadTextFile } from "@/lib/utils/download";
-import type { ReaderPersona } from "@repowise-dev/ui/docs/reader-persona";
-import type { PageResponse } from "@/lib/api/types";
-
-export { SidebarToggle };
-
-/** Web wrapper: maps the page object onto the presentational actions shell. */
-export function DocsPageActions({
- page,
- persona,
- setPersona,
- personaHasEffect,
-}: {
- page: PageResponse;
- persona: ReaderPersona;
- setPersona: (next: ReaderPersona) => void;
- personaHasEffect: boolean;
-}) {
- return (
- <DocsPageActionsShell
- confidence={page.confidence}
- freshnessStatus={page.freshness_status}
- persona={persona}
- setPersona={setPersona}
- personaHasEffect={personaHasEffect}
- />
- );
-}
-
-/**
- * Web wrapper around the Export menu shell — owns the actual download
- * side-effects (single-page + all-pages markdown writes).
- */
-export function ExportMenu({
- isExporting,
- onExportAll,
- zipHref,
- page,
-}: {
- isExporting: boolean;
- onExportAll: () => void;
- zipHref: string;
- page: PageResponse | null;
- /** Accepted for call-site compatibility; the shell builds hrefs itself. */
- repoId?: string;
-}) {
- const exportPage = () => {
- if (!page) return;
- const filename = (page.target_path || page.title).replace(/\//g, "_") + ".md";
- const header = `# ${page.title}\n\n> Path: ${page.target_path}\n\n`;
- downloadTextFile(header + page.content, filename);
- };
-
- return (
- <ExportMenuShell
- isExporting={isExporting}
- onExportPage={exportPage}
- onExportAll={onExportAll}
- zipHref={zipHref}
- hasPage={!!page}
- />
- );
-}
diff --git a/packages/web/src/components/docs/docs-viewer.tsx b/packages/web/src/components/docs/docs-viewer.tsx
index 69bceab0f..80979e01d 100644
--- a/packages/web/src/components/docs/docs-viewer.tsx
+++ b/packages/web/src/components/docs/docs-viewer.tsx
@@ -380,16 +380,23 @@ export function DocsViewer({
buildFileHref={buildFileHref}
missingPageId={missingPageId}
LinkComponent={Link}
- upgradeSlot={
+ // The page's own model action sits in its metadata row, on the page
+ // types a model writes. Not passed as `upgradeSlot` as well: one action
+ // per page, not a second copy at the foot.
+ pageActionSlot={
page && isModelWrittenType(page.page_type) ? (
<PageGenerateButton
page={page}
repoId={repoId}
onGenerated={onGenerated}
- variant="inline"
/>
) : undefined
}
+ freshnessHref={`/repos/${repoId}/docs/drift`}
+ freshnessLabels={{
+ stale: t("viewer.freshness.stale"),
+ outdated: t("viewer.freshness.outdated"),
+ }}
versionHistorySlot={
page ? (
<VersionHistoryWrapper
diff --git a/packages/web/src/components/docs/page-generate-button.tsx b/packages/web/src/components/docs/page-generate-button.tsx
index 67275fb51..565df248e 100644
--- a/packages/web/src/components/docs/page-generate-button.tsx
+++ b/packages/web/src/components/docs/page-generate-button.tsx
@@ -19,7 +19,8 @@ import type { PageResponse, GenerateEstimate } from "@/lib/api/types";
import { useTranslations } from "next-intl";
/**
- * Reader-side "Write with AI" / "Regenerate" for a single page. Owns the
+ * The page's own "Write this page with AI" / "Rewrite with AI", a quiet
+ * model-coloured action in the reader's metadata row. Owns the
* lazily-fetched cost estimate, the cascade choice, the launch, and the live
* progress — the shared `ui` components stay presentational.
*/
@@ -27,15 +28,11 @@ export function PageGenerateButton({
page,
repoId,
onGenerated,
- variant = "button",
}: {
page: PageResponse;
repoId: string;
/** Called once a run completes so the host can refresh the page list. */
onGenerated?: () => void;
- /** "button" is the header toolbar affordance; "inline" is the compact,
- * link-like entry point rendered beside the provenance pill in the reader. */
- variant?: "button" | "inline";
}) {
// "Write" on a stub concept page, "Regenerate" on a written one. Callers only
// mount this on the model-written page types, so a stub here is genuinely a
@@ -124,7 +121,8 @@ export function PageGenerateButton({
<>
<RegenerateButton
mode={mode}
- inline={variant === "inline"}
+ quiet
+ label={mode === "write" ? t("pageGenerate.write") : t("pageGenerate.rewrite")}
onRegenerate={openConfirm}
isLoading={launching && !jobId}
isInProgress={jobId != null}