Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxindex 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.tsxindex 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.tsxnew file mode 100644index 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.tsxindex 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.tsxindex 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">·</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 Overviewpage'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">·</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>→</span></LinkComponent>)}+ {pageActionSlot}</div>{/* What this page was written from. The rail carried this asdiff --git a/packages/ui/src/docs/index.ts b/packages/ui/src/docs/index.tsindex 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.tsxindex 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 ? (<buttontype="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.jsonindex 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.jsonindex 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.tsxdeleted file mode 100644index 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxindex 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 && (+ <ReaderLevelControlpersona={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}+ /><buttononClick={() => 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 && (<SidebarToggleopen={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. */}<HostedNudgeSlotcandidates={[hasStubs && "docs"]}diff --git a/packages/web/src/components/docs/docs-header.test.tsx b/packages/web/src/components/docs/docs-header.test.tsxnew file mode 100644index 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.tsxindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsxdeleted file mode 100644index 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.tsxindex 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) ? (<PageGenerateButtonpage={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 ? (<VersionHistoryWrapperdiff --git a/packages/web/src/components/docs/page-generate-button.tsx b/packages/web/src/components/docs/page-generate-button.tsxindex 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({<><RegenerateButtonmode={mode}- inline={variant === "inline"}+ quiet+ label={mode === "write" ? t("pageGenerate.write") : t("pageGenerate.rewrite")}onRegenerate={openConfirm}isLoading={launching && !jobId}isInProgress={jobId != null}