Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.
Python agent-orchestrationai-agentai-coding-assistantclaude-codecoding-agentcomputer-usedesktop-applocal-firstmcppersonal-jarvisvoice-assistantvoice-coding
feat(docs): redesign the in-app documentation section
rubenluetke10-beepd6efee5f2fa5
diff --git a/jarvis/ui/web/frontend/src/components/docs/Callout.tsx b/jarvis/ui/web/frontend/src/components/docs/Callout.tsxindex eb677e5382..9dcd2e367b 100644--- a/jarvis/ui/web/frontend/src/components/docs/Callout.tsx+++ b/jarvis/ui/web/frontend/src/components/docs/Callout.tsx@@ -1,30 +1,43 @@import type { ReactNode } from "react";-import { Info, AlertTriangle, Lightbulb, FileText } from "lucide-react";+import { AlertTriangle, Info, Lightbulb, NotebookPen } from "lucide-react";import { cn } from "@/lib/utils";+import { useT } from "@/i18n";export type CalloutType = "info" | "warning" | "tip" | "note";-const VARIANTS: Record<CalloutType, { className: string; icon: typeof Info }> = {+/*+ * Every variant is built from theme tokens, so it reads in light and dark+ * alike: a hairline in the status hue, a faint wash of the same hue, and the+ * hue on the icon and label only. Body text stays at body ink.+ */+const VARIANTS: Record<+ CalloutType,+ { frame: string; tone: string; icon: typeof Info; label: string }+> = {+ note: {+ frame: "border-border bg-secondary/40",+ tone: "text-foreground-secondary",+ icon: NotebookPen,+ label: "docs_content.callout_note",+ },info: {- className:- "border-l-blue-500/60 bg-blue-500/10 text-blue-100",+ frame: "border-accent/30 bg-accent-soft",+ tone: "text-accent",icon: Info,- },- warning: {- className:- "border-l-amber-500/60 bg-foreground/10 text-foreground",- icon: AlertTriangle,+ label: "docs_content.callout_info",},tip: {- className:- "border-l-emerald-500/60 bg-muted-foreground/10 text-muted-foreground",+ frame: "border-success/30 bg-success/[0.06]",+ tone: "text-success",icon: Lightbulb,+ label: "docs_content.callout_tip",},- note: {- className:- "border-l-slate-500/60 bg-slate-500/10 text-slate-100",- icon: FileText,+ warning: {+ frame: "border-warning/35 bg-warning/[0.07]",+ tone: "text-warning",+ icon: AlertTriangle,+ label: "docs_content.callout_warning",},};@@ -37,39 +50,59 @@ interface Props {* Admonition block for info/warning/tip/note.** Activation: in Markdown via `> [!info]`, `> [!warning]`, `> [!tip]`,- * `> [!note]` as the first tag inside a blockquote. A standard Markdown- * blockquote without a tag stays a default blockquote (the note variant).+ * `> [!note]` (and GitHub's `[!important]` / `[!caution]`) as the first tag+ * inside a blockquote. A blockquote without a tag stays a plain blockquote.*/export function Callout({ type = "note", children }: Props) {+ const t = useT();const variant = VARIANTS[type];const Icon = variant.icon;return (<asideclassName={cn(- "not-prose my-4 flex gap-3 rounded-md border-l-4 px-4 py-3 text-sm",- variant.className,+ "not-prose my-6 rounded-lg border px-4 py-3.5",+ variant.frame,)}>- <Icon className="mt-0.5 h-4 w-4 shrink-0" aria-hidden="true" />- <div className="flex-1 [&>p]:m-0 [&>p+p]:mt-2">{children}</div>+ <div+ className={cn(+ "mb-1 flex items-center gap-2 text-sm font-semibold",+ variant.tone,+ )}+ >+ <Icon className="h-4 w-4 shrink-0" aria-hidden="true" />+ {t(variant.label)}+ </div>+ <div className="text-base leading-6 text-foreground-secondary [&_a]:text-accent [&_a]:underline [&_a]:decoration-accent/40 [&_a]:underline-offset-2 [&_code]:rounded-sm [&_code]:bg-secondary [&_code]:px-1 [&_code]:font-mono [&_code]:text-sm [&_strong]:font-semibold [&_strong]:text-foreground-strong [&>p]:m-0 [&>p+p]:mt-2">+ {children}+ </div></aside>);}+const TAG_ALIASES: Record<string, CalloutType> = {+ info: "info",+ important: "info",+ warning: "warning",+ caution: "warning",+ tip: "tip",+ note: "note",+};+/**- * Heuristic: looks at the first text node of a blockquote. If it- * starts with ``[!info]``, ``[!warning]``, ``[!tip]``, or ``[!note]``- * (GitHub Markdown convention), returns the type + the rest as children.+ * Heuristic: looks at the first text node of a blockquote. If it starts+ * with a GitHub-style tag such as ``[!info]`` or ``[!warning]``, returns the+ * type + the rest as children.** No match -> ``null``, the renderer falls back to a normal blockquote.*/export function parseCalloutTag(text: string,): { type: CalloutType; rest: string } | null {- const m = text.match(/^\s*\[!(info|warning|tip|note)\]\s*/i);+ const m = text.match(/^\s*\[!(info|important|warning|caution|tip|note)\]\s*/i);if (!m) return null;return {- type: m[1].toLowerCase() as CalloutType,+ type: TAG_ALIASES[m[1].toLowerCase()],rest: text.slice(m[0].length),};}diff --git a/jarvis/ui/web/frontend/src/components/docs/CodeBlock.tsx b/jarvis/ui/web/frontend/src/components/docs/CodeBlock.tsxindex 2bf93759fb..7d4bb4ad97 100644--- a/jarvis/ui/web/frontend/src/components/docs/CodeBlock.tsx+++ b/jarvis/ui/web/frontend/src/components/docs/CodeBlock.tsx@@ -145,48 +145,49 @@ export function CodeBlock({ language, code, chrome = true }: CodeBlockProps) {<divclassName={cn("not-prose group relative overflow-hidden",- chrome && "my-4 rounded-md border border-border bg-muted/40",+ chrome && "my-6 rounded-lg border border-border bg-card",)}>- {/* Header-Bar */}{chrome && (- <div className="flex items-center justify-between border-b border-border/40 bg-muted/20 px-3 py-1">- <span className="text-micro uppercase tracking-wider text-muted-foreground">- {language || "text"}- </span>- <button- type="button"- onClick={handleCopy}- className={cn(- "rounded p-1 text-muted-foreground opacity-60 transition",- "hover:bg-muted hover:text-foreground hover:opacity-100",- "group-hover:opacity-100",- )}- title={t("docs_content.copy_code")}- aria-label={- copied ? t("docs_content.code_copied") : t("docs_content.copy_code")- }- >- {copied ? (- <Check className="h-3 w-3 text-muted-foreground" aria-hidden="true" />- ) : (- <Copy className="h-3 w-3" aria-hidden="true" />- )}- <span className="sr-only" aria-live="polite">- {copied ? t("docs_content.code_copied") : ""}+ <div className="flex h-9 items-center justify-between border-b border-border pl-4 pr-1.5">+ <span className="font-mono text-xs text-muted-foreground">+ {language || "text"}</span>- </button>- </div>+ <button+ type="button"+ onClick={handleCopy}+ className={cn(+ "inline-flex h-7 items-center gap-1.5 rounded-sm px-2 text-xs font-medium text-muted-foreground transition-colors",+ "hover:bg-secondary hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",+ )}+ title={t("docs_content.copy_code")}+ aria-label={+ copied ? t("docs_content.code_copied") : t("docs_content.copy_code")+ }+ >+ {copied ? (+ <Check className="h-3.5 w-3.5 text-success" aria-hidden="true" />+ ) : (+ <Copy className="h-3.5 w-3.5" aria-hidden="true" />+ )}+ <span aria-hidden="true">+ {copied ? t("docs_content.code_copied") : t("docs_content.copy")}+ </span>+ <span className="sr-only" aria-live="polite">+ {copied ? t("docs_content.code_copied") : ""}+ </span>+ </button>+ </div>)}{/* Body — either Shiki HTML or plain text */}{html ? (<div- className="overflow-x-auto px-3 py-2 text-xs leading-relaxed [&_pre]:m-0 [&_pre]:!bg-transparent"+ className="overflow-x-auto px-4 py-3.5 font-mono text-sm leading-6 [&_pre]:m-0 [&_pre]:!bg-transparent [&_pre]:font-mono"// sanitized by Shiki — our code is only rendered locallydangerouslySetInnerHTML={{ __html: html }}/>) : (- <pre className="m-0 overflow-x-auto px-3 py-2 text-xs leading-relaxed text-foreground/90">+ <pre className="m-0 overflow-x-auto px-4 py-3.5 font-mono text-sm leading-6 text-foreground"><code>{code}</code></pre>)}diff --git a/jarvis/ui/web/frontend/src/components/docs/DocTypeBadge.tsx b/jarvis/ui/web/frontend/src/components/docs/DocTypeBadge.tsxdeleted file mode 100644index db26e97dac..0000000000--- a/jarvis/ui/web/frontend/src/components/docs/DocTypeBadge.tsx+++ /dev/null@@ -1,48 +0,0 @@-import { cn } from "@/lib/utils";-import type { DocDiataxis } from "@/hooks/useDocs";--const DIATAXIS_VARIANTS: Record<DocDiataxis, string> = {- tutorial:- "bg-violet-500/15 text-violet-300 border-violet-500/30",- howto:- "bg-blue-500/15 text-blue-300 border-blue-500/30",- reference:- "bg-slate-500/15 text-slate-300 border-slate-500/30",- explanation:- "bg-muted-foreground/15 text-muted-foreground border-muted-foreground/30",- troubleshooting:- "bg-foreground/15 text-foreground border-foreground/30",- adr:- "bg-rose-500/15 text-rose-300 border-rose-500/30",- unclassified:- "bg-neutral-500/15 text-neutral-400 border-neutral-500/30",-};--const DIATAXIS_LABEL: Record<DocDiataxis, string> = {- tutorial: "Tutorial",- howto: "How-To",- reference: "Reference",- explanation: "Concept",- troubleshooting: "Trouble",- adr: "ADR",- unclassified: "Legacy",-};--interface Props {- diataxis: DocDiataxis;- className?: string;-}--export function DocTypeBadge({ diataxis, className }: Props) {- return (- <span- className={cn(- "inline-flex items-center rounded-md border px-1.5 py-0.5 text-micro font-medium uppercase tracking-wide",- DIATAXIS_VARIANTS[diataxis],- className,- )}- >- {DIATAXIS_LABEL[diataxis]}- </span>- );-}diff --git a/jarvis/ui/web/frontend/src/components/docs/DocsContent.test.tsx b/jarvis/ui/web/frontend/src/components/docs/DocsContent.test.tsxindex 14f7867ab1..78eace82c6 100644--- a/jarvis/ui/web/frontend/src/components/docs/DocsContent.test.tsx+++ b/jarvis/ui/web/frontend/src/components/docs/DocsContent.test.tsx@@ -76,4 +76,51 @@ describe("DocsContent", () => {expect(openSpy).toHaveBeenCalledWith("https://personaljarvis.ai/docs/");});+ it("labels callouts and shows the reading time from tokens, not raw colours", async () => {+ vi.stubGlobal(+ "fetch",+ vi.fn(async (input: RequestInfo | URL) => {+ const url = String(input);+ if (url.includes("/api/docs/grouped")) {+ return new Response(JSON.stringify({}), {+ status: 200,+ headers: { "Content-Type": "application/json" },+ });+ }+ return new Response(+ JSON.stringify({+ title: "Keys",+ slug: "keys",+ diataxis: "howto",+ summary: "Keep keys safe.",+ section: "Privacy",+ section_order: 1,+ order: 1,+ tags: [],+ related: [],+ last_reviewed: null,+ path: "docs/product/keys.md",+ body: "> [!warning] Never say a key out loud.",+ headings: [],+ }),+ { status: 200, headers: { "Content-Type": "application/json" } },+ );+ }),+ );+ const client = new QueryClient({+ defaultOptions: { queries: { retry: false, gcTime: 0 } },+ });++ render(+ <QueryClientProvider client={client}>+ <DocsContent slug="keys" onSelect={() => {}} onShowOverview={() => {}} />+ </QueryClientProvider>,+ );++ const label = await waitFor(() => screen.getByText("Warning"));+ const callout = label.closest("aside");+ expect(callout?.textContent).toContain("Never say a key out loud.");+ expect(callout?.className).toContain("border-warning");+ expect(screen.getByText("1 min read")).toBeTruthy();+ });});diff --git a/jarvis/ui/web/frontend/src/components/docs/DocsContent.tsx b/jarvis/ui/web/frontend/src/components/docs/DocsContent.tsxindex 032e0720b9..e5f91b486a 100644--- a/jarvis/ui/web/frontend/src/components/docs/DocsContent.tsx+++ b/jarvis/ui/web/frontend/src/components/docs/DocsContent.tsx@@ -1,11 +1,12 @@-import { useMemo } from "react";+import { useEffect, useMemo, useRef, useState } from "react";import type { Components } from "react-markdown";import {+ ArrowLeft,+ ArrowRight,+ Check,+ Copy,+ ExternalLink,FileWarning,- ChevronLeft,- ChevronRight,- Clock,- Link2,RefreshCw,} from "lucide-react";import ReactMarkdown from "react-markdown";@@ -23,19 +24,22 @@ import type { DocNavSummary } from "@/hooks/useDocs";import { DocsOverview } from "./DocsOverview";import { CodeBlock } from "./CodeBlock";import { Callout, parseCalloutTag, type CalloutType } from "./Callout";+import { docSourceUrl, readingMinutes } from "./docsShared";import { useT, useUiLanguage } from "@/i18n";import { localeForUiLanguage } from "@/components/runs/format";import { openExternalUrl } from "@/lib/openExternal";+import { robustCopy } from "@/lib/clipboard";interface Props {slug: string | null;onSelect: (slug: string) => void;onShowOverview: () => void;+ onOpenSearch?: () => void;}-export function DocsContent({ slug, onSelect, onShowOverview }: Props) {+export function DocsContent({ slug, onSelect, onShowOverview, onOpenSearch }: Props) {if (!slug) {- return <DocsOverview onSelect={onSelect} />;+ return <DocsOverview onSelect={onSelect} onOpenSearch={onOpenSearch} />;}return (<DocsContentInner@@ -46,6 +50,26 @@ export function DocsContent({ slug, onSelect, onShowOverview }: Props) {);}+/*+ * Reading typography for a guide. The typography plugin's colour variables+ * are pointed at theme tokens (identical for its normal and inverted+ * palettes), so one class list reads correctly in light and dark, and the+ * heading sizes are pinned to the app's own type scale.+ */+const ARTICLE_PROSE = [+ "docs-prose prose max-w-none",+ "prose-p:text-pretty prose-li:my-1 prose-li:marker:text-foreground-faint",+ "prose-headings:scroll-mt-8 prose-headings:text-pretty prose-headings:font-semibold prose-headings:text-foreground-strong",+ "prose-h2:mb-4 prose-h2:mt-12 prose-h2:text-xl",+ "prose-h3:mb-3 prose-h3:mt-8 prose-h3:text-lg",+ "prose-h4:text-base",+ "prose-a:font-normal prose-a:text-accent prose-a:underline prose-a:decoration-accent/30 prose-a:underline-offset-4 hover:prose-a:decoration-accent",+ "prose-strong:font-semibold prose-strong:text-foreground-strong",+ "prose-code:rounded-sm prose-code:bg-secondary prose-code:px-1.5 prose-code:py-0.5 prose-code:font-mono prose-code:text-sm prose-code:font-normal prose-code:text-foreground-strong prose-code:before:hidden prose-code:after:hidden",+ "prose-hr:my-10 prose-hr:border-border",+ "prose-img:rounded-lg prose-img:border prose-img:border-border",+].join(" ");+function DocsContentInner({slug,onSelect,@@ -84,112 +108,173 @@ function DocsContentInner({() => formatReviewDate(data?.last_reviewed, uiLanguage),[data?.last_reviewed, uiLanguage],);+ const minutes = useMemo(() => readingMinutes(data?.body ?? ""), [data?.body]);+ const markdownComponents = useMemo(+ () => makeMarkdownComponents({ knownSlugs, onInternalNavigate: onSelect }),+ [knownSlugs, onSelect],+ );if (isLoading) {return <DocPageSkeleton />;}if (error || !data) {return (- <div className="flex min-h-full items-center justify-center px-8 text-center">- <div className="max-w-sm rounded-xl border border-destructive/30 bg-destructive/5 p-6">+ <div className="flex min-h-full items-center justify-center px-8 py-20 text-center">+ <div className="max-w-sm"><FileWarning className="mx-auto h-6 w-6 text-destructive" aria-hidden="true" />- <p className="mt-3 text-sm font-medium text-foreground">+ <p className="mt-3 text-lg font-semibold text-foreground-strong">{t("docs.could_not_load")}</p>- <button- type="button"- onClick={() => void refetch()}- className="mt-4 inline-flex items-center gap-2 rounded-md border border-border bg-card px-3 py-2 text-xs font-medium transition hover:bg-muted"- >- <RefreshCw- className={- isFetching- ? "h-3.5 w-3.5 animate-spin motion-reduce:animate-none"- : "h-3.5 w-3.5"- }- aria-hidden="true"- />- {t("docs_overview.retry")}- </button>+ <div className="mt-5 flex justify-center gap-2">+ <button+ type="button"+ onClick={() => void refetch()}+ className="inline-flex h-8 items-center gap-2 rounded-md border border-border-strong px-3 text-sm font-medium text-foreground transition-colors hover:bg-secondary focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"+ >+ <RefreshCw+ className={+ isFetching+ ? "h-3.5 w-3.5 animate-spin motion-reduce:animate-none"+ : "h-3.5 w-3.5"+ }+ aria-hidden="true"+ />+ {t("docs_overview.retry")}+ </button>+ <button+ type="button"+ onClick={onShowOverview}+ className="inline-flex h-8 items-center rounded-md px-3 text-sm font-medium text-muted-foreground transition-colors hover:bg-secondary hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"+ >+ {t("docs_sidebar.overview")}+ </button>+ </div></div></div>);}+ const markdownPage = `# ${data.title}\n\n${data.body}`;+return (- <article className="prose prose-neutral dark:prose-invert prose-base mx-auto max-w-3xl px-8 py-10 prose-headings:scroll-mt-20 prose-headings:text-pretty prose-p:text-pretty prose-code:before:hidden prose-code:after:hidden prose-a:text-accent prose-a:no-underline hover:prose-a:underline lg:px-10">- <header className="not-prose mb-9 border-b border-border pb-6">- <nav- aria-label="Breadcrumb"- className="mb-4 flex items-center gap-1.5 text-xs text-muted-foreground"- >+ <article className="mx-auto w-full max-w-reading pb-20 pt-12">+ <header className="mb-10 border-b border-border pb-8">+ <nav aria-label="Breadcrumb" className="flex items-center gap-1.5 text-sm"><buttontype="button"onClick={onShowOverview}- className="rounded-sm transition-colors hover:text-primary focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"+ className="rounded-sm text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring">{t("docs_content.breadcrumb")}</button>- <ChevronRight className="h-3 w-3" aria-hidden="true" />- <span className="text-foreground/80" aria-current="page">+ <span className="text-foreground-faint" aria-hidden="true">/</span>+ <span className="font-medium text-accent" aria-current="page">{data.section}</span></nav>- <h1 className="m-0 text-pretty text-3xl tracking-tight">+ <h1 className="mt-3 text-pretty font-display text-2xl text-foreground-strong">{data.title}</h1>- <p className="mt-3 max-w-2xl text-pretty text-base leading-7 text-muted-foreground">- {data.summary}- </p>+ {data.summary && (+ <p className="mt-3 text-pretty text-lg text-muted-foreground">+ {data.summary}+ </p>+ )}+ <div className="mt-6 flex flex-wrap items-center justify-between gap-3">+ <p className="flex flex-wrap items-center gap-x-2 text-sm text-muted-foreground">+ <span>{t("docs_content.reading_time").replace("{0}", String(minutes))}</span>+ {data.last_reviewed && (+ <>+ <span className="text-foreground-faint" aria-hidden="true">·</span>+ <span>{t("docs_content.reviewed").replace("{0}", reviewedDate)}</span>+ </>+ )}+ </p>+ <div className="flex items-center gap-1.5">+ <CopyPageButton markdown={markdownPage} />+ {data.path && (+ <a+ href={docSourceUrl(data.path)}+ onClick={(event) => {+ event.preventDefault();+ void openExternalUrl(docSourceUrl(data.path));+ }}+ rel="noopener noreferrer"+ className="inline-flex h-8 items-center gap-1.5 rounded-md border border-border px-2.5 text-sm font-medium text-muted-foreground transition-colors hover:border-border-strong hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"+ >+ {t("docs_content.view_source")}+ <ExternalLink className="h-3 w-3" aria-hidden="true" />+ </a>+ )}+ </div>+ </div></header>- <ReactMarkdown- remarkPlugins={[remarkGfm]}- rehypePlugins={[- rehypeSlug,- [rehypeAutolinkHeadings, { behavior: "wrap" }],- ]}- components={makeMarkdownComponents({- knownSlugs,- onInternalNavigate: onSelect,- })}- >- {data.body}- </ReactMarkdown>+ <div className={ARTICLE_PROSE}>+ <ReactMarkdown+ remarkPlugins={[remarkGfm]}+ rehypePlugins={[+ rehypeSlug,+ [rehypeAutolinkHeadings, { behavior: "wrap" }],+ ]}+ components={markdownComponents}+ >+ {data.body}+ </ReactMarkdown>+ </div>{relatedDocs.length > 0 && (<RelatedGuides docs={relatedDocs} onSelect={onSelect} />)}- <footer className="not-prose mt-12 border-t border-border pt-6">- <div className="mb-4 flex flex-wrap items-center gap-2 text-xs text-muted-foreground">- <span className="flex items-center gap-1.5">- <Clock className="h-3 w-3" aria-hidden="true" />- {data.last_reviewed ? (- <>{t("docs_content.last_reviewed")} {reviewedDate}</>- ) : (- <>{t("docs_content.review_unavailable")}</>- )}- </span>- </div>-- <div className="grid grid-cols-1 gap-3 sm:grid-cols-2">- <NavCard- doc={neighbors.prev}- direction="prev"- onSelect={onSelect}- />- <NavCard- doc={neighbors.next}- direction="next"- onSelect={onSelect}- />- </div>- </footer>+ {(neighbors.prev || neighbors.next) && (+ <nav+ aria-label={t("docs_content.pagination")}+ className="mt-14 grid grid-cols-1 gap-3 border-t border-border pt-8 sm:grid-cols-2"+ >+ <NavCard doc={neighbors.prev} direction="prev" onSelect={onSelect} />+ <NavCard doc={neighbors.next} direction="next" onSelect={onSelect} />+ </nav>+ )}</article>);}+function CopyPageButton({ markdown }: { markdown: string }) {+ const t = useT();+ const [copied, setCopied] = useState(false);+ const timer = useRef<number | null>(null);+ useEffect(+ () => () => {+ if (timer.current !== null) window.clearTimeout(timer.current);+ },+ [],+ );+ return (+ <button+ type="button"+ onClick={() => {+ void robustCopy(markdown).then((ok) => {+ if (!ok) return;+ setCopied(true);+ if (timer.current !== null) window.clearTimeout(timer.current);+ timer.current = window.setTimeout(() => setCopied(false), 1500);+ });+ }}+ className="inline-flex h-8 items-center gap-1.5 rounded-md border border-border px-2.5 text-sm font-medium text-muted-foreground transition-colors hover:border-border-strong hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"+ >+ {copied ? (+ <Check className="h-3.5 w-3.5 text-success" aria-hidden="true" />+ ) : (+ <Copy className="h-3.5 w-3.5" aria-hidden="true" />+ )}+ <span aria-live="polite">+ {copied ? t("docs_content.page_copied") : t("docs_content.copy_page")}+ </span>+ </button>+ );+}+// ----------------------------------------------------------------------// Prev/next computation + NavCard// ----------------------------------------------------------------------@@ -218,22 +303,32 @@ function NavCard({onSelect: (slug: string) => void;}) {const t = useT();- if (!doc) return <div />;- const Icon = direction === "prev" ? ChevronLeft : ChevronRight;- const align = direction === "next" ? "text-right items-end" : "items-start";+ if (!doc) return <div className="hidden sm:block" />;+ const next = direction === "next";return (<buttontype="button"onClick={() => onSelect(doc.slug)}- className={`flex flex-col gap-1 rounded-md border border-border bg-card/40 p-3 text-left transition hover:bg-muted/40 ${align}`}+ className={`group flex flex-col gap-1 rounded-lg border border-border px-5 py-4 transition-colors hover:border-border-strong hover:bg-secondary/40 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring ${+ next ? "items-end text-right sm:col-start-2" : "items-start text-left"+ }`}>- <span className="flex items-center gap-1 text-micro uppercase tracking-wider text-muted-foreground">- {direction === "prev" ? <Icon className="h-3 w-3" aria-hidden="true" /> : null}- {direction === "prev" ? t("docs_content.prev") : t("docs_content.next")}- {direction === "next" ? <Icon className="h-3 w-3" aria-hidden="true" /> : null}+ <span className="flex items-center gap-1.5 text-sm text-muted-foreground">+ {!next && (+ <ArrowLeft+ className="h-3.5 w-3.5 transition-transform motion-safe:group-hover:-translate-x-0.5"+ aria-hidden="true"+ />+ )}+ {next ? t("docs_content.next") : t("docs_content.prev")}+ {next && (+ <ArrowRight+ className="h-3.5 w-3.5 transition-transform motion-safe:group-hover:translate-x-0.5"+ aria-hidden="true"+ />+ )}</span>- <span className="text-sm font-medium">{doc.title}</span>- <span className="text-xs leading-5 text-muted-foreground">{doc.summary}</span>+ <span className="text-lg font-medium text-foreground-strong">{doc.title}</span></button>);}@@ -257,26 +352,29 @@ function RelatedGuides({}) {const t = useT();return (- <section- className="not-prose mt-12 border-t border-border pt-8"- aria-labelledby="related-guides-title"- >- <div className="mb-4 flex items-center gap-2">- <Link2 className="h-4 w-4 text-primary" aria-hidden="true" />- <h2 id="related-guides-title" className="text-lg font-semibold">- {t("docs_content.related_guides")}- </h2>- </div>- <div className="grid gap-3 sm:grid-cols-2">+ <section className="mt-14" aria-labelledby="related-guides-title">+ <h2+ id="related-guides-title"+ className="text-sm font-semibold text-foreground-strong"+ >+ {t("docs_content.related_guides")}+ </h2>+ <div className="mt-3 grid gap-3 sm:grid-cols-2">{docs.map((doc) => (<buttonkey={doc.slug}type="button"onClick={() => onSelect(doc.slug)}- className="rounded-lg border border-border bg-card/30 p-4 text-left transition-colors hover:border-primary/30 hover:bg-card/60"+ className="group rounded-lg border border-border px-4 py-3.5 text-left transition-colors hover:border-border-strong hover:bg-secondary/40 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring">- <span className="text-sm font-semibold text-foreground">{doc.title}</span>- <span className="mt-1.5 block text-xs leading-5 text-muted-foreground">+ <span className="flex items-center justify-between gap-3 text-base font-medium text-foreground">+ {doc.title}+ <ArrowRight+ className="h-3.5 w-3.5 shrink-0 text-foreground-faint transition-colors group-hover:text-foreground"+ aria-hidden="true"+ />+ </span>+ <span className="mt-1 line-clamp-2 text-sm text-muted-foreground">{doc.summary}</span></button>@@ -289,29 +387,24 @@ function RelatedGuides({function DocPageSkeleton() {const t = useT();return (- <div className="mx-auto min-h-full w-full max-w-3xl px-8 py-10" role="status">- <div className="flex items-center gap-2 text-xs text-muted-foreground">- <RefreshCw- className="h-3.5 w-3.5 animate-spin text-primary motion-reduce:animate-none"- aria-hidden="true"- />- {t("docs_overview.loading_page")}- </div>- <div className="mt-6 animate-pulse motion-reduce:animate-none">- <div className="h-3 w-24 rounded-full bg-muted" />- <div className="mt-4 h-8 w-3/5 rounded-md bg-muted" />- <div className="mt-4 h-px bg-border" />- <div className="mt-8 space-y-3">- <div className="h-3 w-full rounded-full bg-muted/80" />- <div className="h-3 w-11/12 rounded-full bg-muted/80" />- <div className="h-3 w-4/5 rounded-full bg-muted/80" />+ <div className="mx-auto w-full max-w-reading pb-20 pt-12" role="status">+ <span className="sr-only">{t("docs_overview.loading_page")}</span>+ <div className="animate-pulse motion-reduce:animate-none" aria-hidden="true">+ <div className="h-3 w-40 rounded-full bg-muted" />+ <div className="mt-5 h-7 w-3/5 rounded-md bg-muted" />+ <div className="mt-4 h-3.5 w-4/5 rounded-full bg-muted/70" />+ <div className="mt-8 h-px bg-border" />+ <div className="mt-10 space-y-3.5">+ <div className="h-3 w-full rounded-full bg-muted/70" />+ <div className="h-3 w-11/12 rounded-full bg-muted/70" />+ <div className="h-3 w-4/5 rounded-full bg-muted/70" /></div>- <div className="mt-10 h-5 w-2/5 rounded-full bg-muted" />- <div className="mt-5 space-y-3">- <div className="h-3 w-full rounded-full bg-muted/80" />- <div className="h-3 w-5/6 rounded-full bg-muted/80" />- <div className="h-28 rounded-lg border border-border bg-card/40" />+ <div className="mt-12 h-4 w-2/5 rounded-full bg-muted" />+ <div className="mt-5 space-y-3.5">+ <div className="h-3 w-full rounded-full bg-muted/70" />+ <div className="h-3 w-5/6 rounded-full bg-muted/70" /></div>+ <div className="mt-6 h-28 rounded-lg border border-border bg-card" /></div></div>);@@ -400,7 +493,7 @@ function makeMarkdownComponents(ctx: MarkdownContext): Components {return <Callout type={tagged.type}>{tagged.children}</Callout>;}return (- <blockquote className="border-l-2 border-border pl-4 italic text-muted-foreground">+ <blockquote className="border-l-2 border-border-strong pl-4 not-italic text-foreground-secondary [&_p:before]:content-none [&_p:after]:content-none">{children}</blockquote>);@@ -447,14 +540,38 @@ function makeMarkdownComponents(ctx: MarkdownContext): Components {);},- // Tables with a bit more padding for better readability.+ // Tables sit in their own framed, horizontally scrollable box; cells are+ // styled here because the frame opts out of the prose rules.table({ children }) {return (- <div className="not-prose my-4 overflow-x-auto rounded-md border border-border">- <table className="w-full text-sm">{children}</table>+ <div className="not-prose my-6 overflow-x-auto rounded-lg border border-border">+ <table className="w-full border-collapse text-left text-base">{children}</table></div>);},+ thead({ children }) {+ return <thead className="bg-secondary/50">{children}</thead>;+ },+ th({ children, style }) {+ return (+ <th+ style={style}+ className="border-b border-border px-4 py-2.5 text-sm font-semibold text-foreground-strong"+ >+ {children}+ </th>+ );+ },+ td({ children, style }) {+ return (+ <td+ style={style}+ className="border-t border-border px-4 py-2.5 align-top text-foreground-secondary first:font-medium first:text-foreground [&_code]:rounded-sm [&_code]:bg-secondary [&_code]:px-1 [&_code]:font-mono [&_code]:text-sm"+ >+ {children}+ </td>+ );+ },};}diff --git a/jarvis/ui/web/frontend/src/components/docs/DocsOverview.test.tsx b/jarvis/ui/web/frontend/src/components/docs/DocsOverview.test.tsxindex 2c44705d1e..cfaf1c7628 100644--- a/jarvis/ui/web/frontend/src/components/docs/DocsOverview.test.tsx+++ b/jarvis/ui/web/frontend/src/components/docs/DocsOverview.test.tsx@@ -32,24 +32,26 @@ describe("DocsOverview", () => {expect(screen.getByRole("status")).toBeTruthy();});- it("renders local quick links and opens the redesigned online docs", async () => {+ it("draws the first topic as a reading path and the rest as topic cards", async () => {+ const doc = (slug: string, title: string, section: string, order: number) => ({+ title,+ slug,+ diataxis: "howto",+ summary: `About ${title}.`,+ section,+ section_order: order,+ order: 1,+ tags: [],+ related: [],+ });vi.stubGlobal("fetch",vi.fn(async () =>new Response(JSON.stringify({- unclassified: [- {- title: "Architecture overview",- slug: "architecture-overview",- diataxis: "unclassified",- summary: "See how the main parts work together.",- section: "Reference",- section_order: 7,- order: 1,- tags: [],- related: [],- },+ howto: [+ doc("welcome", "Welcome", "Start here", 1),+ doc("architecture-overview", "Architecture overview", "Reference", 7),],}),{ status: 200, headers: { "Content-Type": "application/json" } },@@ -59,17 +61,25 @@ describe("DocsOverview", () => {const openSpy = vi.spyOn(openExternal, "openExternalUrl").mockResolvedValue(true);-- renderOverview();+ const selected: string[] = [];+ const client = new QueryClient({+ defaultOptions: { queries: { retry: false, gcTime: 0 } },+ });+ render(+ <QueryClientProvider client={client}>+ <DocsOverview onSelect={(slug) => selected.push(slug)} />+ </QueryClientProvider>,+ );await waitFor(() => {- expect(screen.getByText("Architecture overview")).toBeTruthy();- expect(screen.getByText("Browse by Topic")).toBeTruthy();+ expect(screen.getByText("Get started")).toBeTruthy();+ expect(screen.getByText("Browse by topic")).toBeTruthy();});- fireEvent.click(- screen.getByRole("link", { name: /open redesigned online docs/i }),- );+ expect(screen.getByText("Welcome")).toBeTruthy();+ fireEvent.click(screen.getByRole("button", { name: /Architecture overview/ }));+ expect(selected).toEqual(["architecture-overview"]);+ fireEvent.click(screen.getByRole("link", { name: /view on github/i }));expect(openSpy).toHaveBeenCalledWith("https://github.com/PersonalJarvis/PersonalJarvis/tree/main/docs");});});diff --git a/jarvis/ui/web/frontend/src/components/docs/DocsOverview.tsx b/jarvis/ui/web/frontend/src/components/docs/DocsOverview.tsxindex a2afcd89d9..0dd61705bd 100644--- a/jarvis/ui/web/frontend/src/components/docs/DocsOverview.tsx+++ b/jarvis/ui/web/frontend/src/components/docs/DocsOverview.tsx@@ -1,4 +1,4 @@-import { useMemo } from "react";+import { useMemo, useState } from "react";import {ArrowRight,BookOpen,@@ -6,6 +6,7 @@ import {FileWarning,Loader2,RefreshCw,+ Search,} from "lucide-react";import {@@ -14,86 +15,93 @@ import {type DocSection,type DocNavSummary,} from "@/hooks/useDocs";+import { useRecentDocs } from "@/hooks/useRecentDocs";import { useT } from "@/i18n";import { openExternalUrl } from "@/lib/openExternal";+import { cn } from "@/lib/utils";+import { ONLINE_DOCS_URL, SearchTrigger, sectionIcon } from "./docsShared";++/** Links a topic card shows before it offers "Show all". */+const TOPIC_PREVIEW_COUNT = 4;-const ONLINE_DOCS_URL = "https://github.com/PersonalJarvis/PersonalJarvis/tree/main/docs";interface Props {onSelect: (slug: string) => void;+ onOpenSearch?: () => void;}-export function DocsOverview({ onSelect }: Props) {+/**+ * The docs home: a title with the search field, the first topic as a+ * numbered reading path, recently opened guides, and every other topic as a+ * card listing its guides.+ */+export function DocsOverview({ onSelect, onOpenSearch }: Props) {const t = useT();const { data, isLoading, isFetching, error, refetch } = useDocsGrouped();+ const { recent } = useRecentDocs();const sections = useMemo(() => buildDocSections(data), [data]);- const allDocs = useMemo(- () => sections.flatMap((section) => section.docs),- [sections],- );- const featured = allDocs.slice(0, 4);+ const sectionBySlug = useMemo(() => {+ const map = new Map<string, string>();+ for (const section of sections) {+ for (const doc of section.docs) map.set(doc.slug, section.name);+ }+ return map;+ }, [sections]);+ const [startSection, ...topics] = sections;+ const recentDocs = recent.filter((doc) => sectionBySlug.has(doc.slug)).slice(0, 3);return (- <section className="mx-auto min-h-full w-full max-w-5xl px-8 py-8 lg:px-12">- <div className="border-b border-border pb-8">- <div className="mb-3 flex items-center gap-2 text-sm font-medium text-muted-foreground">- <BookOpen className="h-4 w-4" aria-hidden="true" />+ <div className="mx-auto w-full max-w-page pb-20 pt-14">+ <header className="max-w-reading">+ <p className="text-sm font-medium text-accent">{t("docs_overview.eyebrow")}- </div>- <h1 className="text-2xl font-semibold text-foreground-strong">+ </p>+ <h1 className="mt-3 font-display text-2xl text-foreground-strong">{t("docs_overview.title")}</h1>- <p className="mt-2 max-w-2xl text-base text-muted-foreground">+ <p className="mt-4 text-lg text-muted-foreground">{t("docs_overview.description")}</p>- <a- href={ONLINE_DOCS_URL}- onClick={(event) => {- event.preventDefault();- void openExternalUrl(ONLINE_DOCS_URL);- }}- rel="noopener noreferrer"- className="mt-5 inline-flex h-9 items-center gap-2 rounded-md border border-border-strong px-4 text-base font-medium text-foreground transition-colors hover:bg-secondary focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background"- >- {t("docs_overview.online_docs")}- <ExternalLink className="h-3.5 w-3.5" aria-hidden="true" />- </a>- </div>+ {onOpenSearch && (+ <SearchTrigger+ size="lg"+ onClick={onOpenSearch}+ className="mt-8 max-w-xl"+ />+ )}+ </header>{isLoading ? (<OverviewSkeleton />) : error ? (- <div className="mt-8 rounded-lg border border-destructive/20 bg-destructive/[0.08] p-5">- <div className="flex items-start gap-3">- <FileWarning className="mt-0.5 h-5 w-5 text-destructive" aria-hidden="true" />- <div>- <h2 className="text-lg font-semibold text-foreground-strong">- {t("docs_overview.load_failed_title")}- </h2>- <p className="mt-1 text-base text-muted-foreground">- {t("docs_overview.load_failed_description")}- </p>- <button- type="button"- onClick={() => void refetch()}- className="mt-4 inline-flex items-center gap-2 rounded-md border border-border bg-card px-3 py-2 text-xs font-medium transition hover:bg-muted"- >- <RefreshCw- className={- isFetching- ? "h-3.5 w-3.5 animate-spin motion-reduce:animate-none"- : "h-3.5 w-3.5"- }- aria-hidden="true"- />- {t("docs_overview.retry")}- </button>- </div>+ <div className="mt-12 flex items-start gap-3 rounded-lg border border-destructive/30 bg-destructive/[0.06] p-5">+ <FileWarning className="mt-0.5 h-5 w-5 shrink-0 text-destructive" aria-hidden="true" />+ <div>+ <h2 className="text-lg font-semibold text-foreground-strong">+ {t("docs_overview.load_failed_title")}+ </h2>+ <p className="mt-1 text-base text-muted-foreground">+ {t("docs_overview.load_failed_description")}+ </p>+ <button+ type="button"+ onClick={() => void refetch()}+ className="mt-4 inline-flex h-8 items-center gap-2 rounded-md border border-border-strong px-3 text-sm font-medium text-foreground transition-colors hover:bg-secondary focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"+ >+ <RefreshCw+ className={cn(+ "h-3.5 w-3.5",+ isFetching && "animate-spin motion-reduce:animate-none",+ )}+ aria-hidden="true"+ />+ {t("docs_overview.retry")}+ </button></div></div>- ) : featured.length === 0 ? (- <div className="mt-8 rounded-lg border border-border bg-card p-8 text-center">- <BookOpen className="mx-auto h-8 w-8 text-muted-foreground/50" aria-hidden="true" />+ ) : !startSection ? (+ <div className="mt-12 rounded-lg border border-border p-10 text-center">+ <BookOpen className="mx-auto h-6 w-6 text-foreground-faint" aria-hidden="true" /><h2 className="mt-3 text-lg font-semibold text-foreground-strong">{t("docs_overview.empty_title")}</h2>@@ -102,74 +110,170 @@ export function DocsOverview({ onSelect }: Props) {</p></div>) : (- <div className="mt-10">- <div className="mb-5 flex items-end justify-between gap-4">+ <>+ <StartPath section={startSection} onSelect={onSelect} />++ {recentDocs.length > 0 && (+ <section className="mt-14" aria-labelledby="docs-recent-title">+ <h2+ id="docs-recent-title"+ className="text-sm font-semibold text-foreground-strong"+ >+ {t("docs_overview.recent_title")}+ </h2>+ <div className="mt-3 grid gap-3 sm:grid-cols-2 lg:grid-cols-3">+ {recentDocs.map((doc) => (+ <button+ key={doc.slug}+ type="button"+ onClick={() => onSelect(doc.slug)}+ className="group flex items-center justify-between gap-3 rounded-md border border-border px-4 py-3 text-left transition-colors hover:border-border-strong hover:bg-secondary/40 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"+ >+ <span className="min-w-0">+ <span className="block truncate text-base font-medium text-foreground">+ {doc.title}+ </span>+ <span className="mt-0.5 block truncate text-sm text-muted-foreground">+ {sectionBySlug.get(doc.slug)}+ </span>+ </span>+ <ArrowRight+ className="h-3.5 w-3.5 shrink-0 text-foreground-faint transition-colors group-hover:text-foreground"+ aria-hidden="true"+ />+ </button>+ ))}+ </div>+ </section>+ )}++ {topics.length > 0 && (+ <section className="mt-16" aria-labelledby="docs-topics-title">+ <h2+ id="docs-topics-title"+ className="text-xl font-semibold text-foreground-strong"+ >+ {t("docs_overview.browse_by_topic")}+ </h2>+ <p className="mt-1.5 text-base text-muted-foreground">+ {t("docs_overview.browse_description")}+ </p>+ <div className="mt-6 grid gap-4 md:grid-cols-2 xl:grid-cols-3">+ {topics.map((section) => (+ <TopicCard key={section.name} section={section} onSelect={onSelect} />+ ))}+ </div>+ </section>+ )}++ <section className="mt-16 flex flex-col gap-5 border-t border-border pt-8 md:flex-row md:items-center md:justify-between"><div><h2 className="text-lg font-semibold text-foreground-strong">- {t("docs_overview.local_library")}+ {t("docs_overview.help_title")}</h2><p className="mt-1 text-base text-muted-foreground">- {t("docs_overview.local_library_description")}+ {t("docs_overview.help_description")}</p></div>- <span className="shrink-0 text-sm text-foreground-faint">- {allDocs.length} {t("docs_sidebar.documents")}- </span>- </div>-- <div className="grid gap-4 sm:grid-cols-2">- {featured.map((doc) => (- <DocCard key={doc.slug} doc={doc} onSelect={onSelect} />- ))}- </div>-- <div className="mt-12 border-t border-border pt-8">- <h2 className="text-lg font-semibold text-foreground-strong">- {t("docs_overview.browse_by_topic")}- </h2>- <p className="mt-1 text-base text-muted-foreground">- {t("docs_overview.browse_description")}- </p>- <div className="mt-5 grid gap-4 md:grid-cols-2 xl:grid-cols-3">- {sections.map((section) => (- <SectionCard key={section.name} section={section} onSelect={onSelect} />- ))}+ <div className="flex shrink-0 flex-wrap gap-2">+ {onOpenSearch && (+ <button+ type="button"+ onClick={onOpenSearch}+ className="inline-flex h-9 items-center gap-2 rounded-md border border-border-strong px-4 text-base font-medium text-foreground transition-colors hover:bg-secondary focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"+ >+ <Search className="h-3.5 w-3.5" aria-hidden="true" />+ {t("docs.search_button")}+ </button>+ )}+ <a+ href={ONLINE_DOCS_URL}+ onClick={(event) => {+ event.preventDefault();+ void openExternalUrl(ONLINE_DOCS_URL);+ }}+ rel="noopener noreferrer"+ className="inline-flex h-9 items-center gap-2 rounded-md border border-border-strong px-4 text-base font-medium text-foreground transition-colors hover:bg-secondary focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"+ >+ {t("docs_overview.online_docs")}+ <ExternalLink className="h-3.5 w-3.5" aria-hidden="true" />+ </a></div>- </div>- </div>+ </section>+ </>)}- </section>+ </div>);}-function DocCard({- doc,+/** The first topic, drawn as an ordered reading path. */+function StartPath({+ section,onSelect,}: {- doc: DocNavSummary;+ section: DocSection;onSelect: (slug: string) => void;}) {+ const t = useT();+ const Icon = sectionIcon(section.name);+ const first = section.docs[0];return (- <button- type="button"- onClick={() => onSelect(doc.slug)}- className="group flex min-h-36 flex-col rounded-lg border border-border bg-card p-5 text-left transition-colors hover:border-border-strong focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background"+ <section+ className="mt-14 grid overflow-hidden rounded-lg border border-border bg-card lg:grid-cols-5"+ aria-labelledby="docs-start-title">- <span className="text-xs font-medium uppercase tracking-wide text-foreground-faint">- {doc.section}- </span>- <span className="mt-2 flex items-center gap-2 text-lg font-semibold text-foreground-strong">- {doc.title}- <ArrowRight className="h-4 w-4 text-muted-foreground transition motion-safe:group-hover:translate-x-0.5" aria-hidden="true" />- </span>- <span className="mt-2 text-base text-muted-foreground">- {doc.summary}- </span>- </button>+ <div className="flex flex-col border-b border-border p-7 lg:col-span-2 lg:border-b-0 lg:border-r">+ <span className="flex h-9 w-9 items-center justify-center rounded-md bg-accent-soft text-accent">+ <Icon className="h-4 w-4" aria-hidden="true" />+ </span>+ <h2+ id="docs-start-title"+ className="mt-5 text-xl font-semibold text-foreground-strong"+ >+ {t("docs_overview.start_title")}+ </h2>+ <p className="mt-2 text-base text-muted-foreground">+ {t("docs_overview.start_description")}+ </p>+ {first && (+ <button+ type="button"+ onClick={() => onSelect(first.slug)}+ className="mt-6 inline-flex h-9 w-fit items-center gap-2 rounded-md bg-primary px-4 text-base font-medium text-primary-foreground transition-opacity hover:opacity-90 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-card"+ >+ {t("docs_overview.start_reading")}+ <ArrowRight className="h-3.5 w-3.5" aria-hidden="true" />+ </button>+ )}+ </div>+ <ol className="p-3 lg:col-span-3">+ {section.docs.map((doc, index) => (+ <li key={doc.slug}>+ <button+ type="button"+ onClick={() => onSelect(doc.slug)}+ className="group flex w-full items-start gap-4 rounded-md px-4 py-3 text-left transition-colors hover:bg-secondary focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"+ >+ <span className="mt-px flex h-6 w-6 shrink-0 items-center justify-center rounded-full border border-border-strong text-xs font-medium tabular-nums text-muted-foreground transition-colors group-hover:border-accent group-hover:text-accent">+ {index + 1}+ </span>+ <span className="min-w-0">+ <span className="block text-base font-medium text-foreground">+ {doc.title}+ </span>+ <span className="mt-0.5 line-clamp-1 text-sm text-muted-foreground">+ {doc.summary}+ </span>+ </span>+ </button>+ </li>+ ))}+ </ol>+ </section>);}-function SectionCard({+function TopicCard({section,onSelect,}: {@@ -177,55 +281,82 @@ function SectionCard({onSelect: (slug: string) => void;}) {const t = useT();- const first = section.docs[0];+ const [expanded, setExpanded] = useState(false);+ const Icon = sectionIcon(section.name);+ const visible: DocNavSummary[] = expanded+ ? section.docs+ : section.docs.slice(0, TOPIC_PREVIEW_COUNT);+ const hidden = section.docs.length - TOPIC_PREVIEW_COUNT;return (- <button- type="button"- onClick={() => onSelect(first.slug)}- className="group rounded-lg border border-border bg-card p-5 text-left transition-colors hover:border-border-strong focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background"- >- <span className="flex items-center justify-between gap-3 text-lg font-semibold text-foreground-strong">- {section.name}- <ArrowRight className="h-4 w-4 text-muted-foreground transition-transform motion-safe:group-hover:translate-x-0.5" aria-hidden="true" />- </span>- <span className="mt-2 block text-base text-muted-foreground">- {first.summary}- </span>- <span className="mt-3 block text-sm text-foreground-faint">- {section.docs.length}{" "}- {section.docs.length === 1- ? t("docs_overview.guide")- : t("docs_overview.guides")}- </span>- </button>+ <section className="flex flex-col rounded-lg border border-border bg-card p-5">+ <div className="flex items-center gap-3">+ <span className="flex h-8 w-8 shrink-0 items-center justify-center rounded-md bg-secondary text-foreground-secondary">+ <Icon className="h-4 w-4" aria-hidden="true" />+ </span>+ <h3 className="text-lg font-semibold text-foreground-strong">+ {section.name}+ </h3>+ </div>+ <ul className="mt-4 flex-1 space-y-px">+ {visible.map((doc) => (+ <li key={doc.slug}>+ <button+ type="button"+ onClick={() => onSelect(doc.slug)}+ title={doc.summary}+ className="group flex w-full items-center justify-between gap-3 rounded-sm py-1.5 text-left text-base text-foreground-secondary transition-colors hover:text-accent focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"+ >+ <span className="min-w-0 truncate">{doc.title}</span>+ <ArrowRight+ className="h-3.5 w-3.5 shrink-0 opacity-0 transition-opacity group-hover:opacity-100"+ aria-hidden="true"+ />+ </button>+ </li>+ ))}+ </ul>+ {hidden > 0 && (+ <button+ type="button"+ onClick={() => setExpanded((value) => !value)}+ aria-expanded={expanded}+ className="mt-3 w-fit rounded-sm text-sm font-medium text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"+ >+ {expanded+ ? t("docs_overview.show_less")+ : t("docs_overview.show_all").replace("{0}", String(section.docs.length))}+ </button>+ )}+ </section>);}function OverviewSkeleton() {const t = useT();return (- <div className="mt-8" role="status" aria-live="polite">- <div className="flex items-start gap-3 rounded-lg border border-accent/20 bg-accent-soft p-4">+ <div className="mt-14" role="status" aria-live="polite">+ <div className="flex items-center gap-2 text-sm text-muted-foreground"><Loader2- className="mt-0.5 h-4 w-4 animate-spin text-primary motion-reduce:animate-none"+ className="h-3.5 w-3.5 animate-spin text-accent motion-reduce:animate-none"aria-hidden="true"/>- <div>- <p className="text-base font-medium">{t("docs_overview.indexing_title")}</p>- <p className="mt-1 text-base text-muted-foreground">- {t("docs_overview.indexing_description")}- </p>- </div>+ <span className="font-medium text-foreground">+ {t("docs_overview.indexing_title")}+ </span>+ <span className="hidden sm:inline">— {t("docs_overview.indexing_description")}</span></div>- <div className="mt-8 animate-pulse motion-reduce:animate-none">- <div className="h-4 w-36 rounded-full bg-muted" />- <div className="mt-2 h-3 w-72 max-w-full rounded-full bg-muted/70" />- <div className="mt-5 grid gap-3 sm:grid-cols-2">- {[0, 1, 2, 3].map((item) => (- <div key={item} className="h-28 rounded-xl border border-border bg-card/30 p-5">- <div className="h-2 w-20 rounded-full bg-muted" />- <div className="mt-4 h-3 w-3/5 rounded-full bg-muted" />- <div className="mt-5 h-2 w-2/5 rounded-full bg-muted/60" />+ <div className="mt-6 animate-pulse motion-reduce:animate-none" aria-hidden="true">+ <div className="h-56 rounded-lg border border-border bg-card" />+ <div className="mt-14 h-4 w-40 rounded-full bg-muted" />+ <div className="mt-6 grid gap-4 md:grid-cols-2 xl:grid-cols-3">+ {[0, 1, 2].map((item) => (+ <div key={item} className="h-48 rounded-lg border border-border bg-card p-5">+ <div className="h-3 w-1/2 rounded-full bg-muted" />+ <div className="mt-6 space-y-3">+ <div className="h-2.5 w-4/5 rounded-full bg-muted/70" />+ <div className="h-2.5 w-3/5 rounded-full bg-muted/70" />+ <div className="h-2.5 w-2/3 rounded-full bg-muted/70" />+ </div></div>))}</div>diff --git a/jarvis/ui/web/frontend/src/components/docs/DocsSearchModal.tsx b/jarvis/ui/web/frontend/src/components/docs/DocsSearchModal.tsxindex 5021a429e5..c1f8e26404 100644--- a/jarvis/ui/web/frontend/src/components/docs/DocsSearchModal.tsx+++ b/jarvis/ui/web/frontend/src/components/docs/DocsSearchModal.tsx@@ -1,9 +1,17 @@-import { useEffect, useState } from "react";+import { useEffect, useMemo, useState } from "react";import * as Dialog from "@radix-ui/react-dialog";import { Command } from "cmdk";-import { FileText, FileWarning, RefreshCw, Search } from "lucide-react";+import {+ Clock,+ FileText,+ FileWarning,+ Loader2,+ RefreshCw,+ Search,+} from "lucide-react";-import { useDocSearch } from "@/hooks/useDocs";+import { buildDocSections, useDocSearch, useDocsGrouped } from "@/hooks/useDocs";+import { useRecentDocs } from "@/hooks/useRecentDocs";import { cn } from "@/lib/utils";import { useT } from "@/i18n";@@ -35,24 +43,55 @@ export function DocsSearchModal({ open, onOpenChange, onSelect }: Props) {undefined,open,);+ const grouped = useDocsGrouped();+ const { recent } = useRecentDocs();++ // With nothing typed yet the dialog offers a starting point: the guides+ // opened most recently, then the first topic's reading path.+ const suggestions = useMemo(() => {+ const sections = buildDocSections(grouped.data);+ const known = new Map<string, { title: string; section: string }>();+ for (const section of sections) {+ for (const doc of section.docs) {+ known.set(doc.slug, { title: doc.title, section: section.name });+ }+ }+ const recentRows: SuggestionRow[] = [];+ for (const doc of recent) {+ const entry = known.get(doc.slug);+ if (entry) recentRows.push({ slug: doc.slug, ...entry });+ }+ const start = sections[0];+ const startRows: SuggestionRow[] = (start?.docs ?? [])+ .filter((doc) => !recentRows.some((row) => row.slug === doc.slug))+ .map((doc) => ({ slug: doc.slug, title: doc.title, section: start.name }));+ return { recentRows, startName: start?.name ?? "", startRows };+ }, [grouped.data, recent]);// Reset the query on close so a re-open starts fresh.useEffect(() => {if (!open) setQuery("");}, [open]);+ const choose = (slug: string) => {+ onSelect(slug);+ onOpenChange(false);+ };++ const hasSuggestions =+ suggestions.recentRows.length + suggestions.startRows.length > 0;+return (<Dialog.Root open={open} onOpenChange={onOpenChange}><Dialog.Portal><Dialog.Overlay className="fixed inset-0 z-40 bg-scrim/60 backdrop-blur-sm data-[state=open]:animate-in data-[state=open]:fade-in-0 motion-reduce:animate-none" />- <Dialog.Content className="fixed left-1/2 top-[15%] z-50 w-[min(640px,calc(100vw-2rem))] -translate-x-1/2 overflow-hidden rounded-lg bg-popover shadow-float data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 motion-reduce:animate-none">+ <Dialog.Content className="fixed left-1/2 top-[12%] z-50 w-[min(680px,calc(100vw-2rem))] -translate-x-1/2 overflow-hidden rounded-lg bg-popover shadow-float data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 motion-reduce:animate-none"><Dialog.Title className="sr-only">{t("docs.search_modal_title")}</Dialog.Title><Dialog.Description className="sr-only">{t("docs.search_hint")}</Dialog.Description><Command shouldFilter={false} loop>- {/* Header / Input */}- <div className="flex items-center gap-2 border-b border-border px-3 py-2">+ <div className="flex h-14 items-center gap-3 border-b border-border px-4"><Search className="h-4 w-4 shrink-0 text-muted-foreground" aria-hidden="true" /><Command.Inputvalue={query}@@ -62,26 +101,62 @@ export function DocsSearchModal({ open, onOpenChange, onSelect }: Props) {name="docs-search"autoComplete="off"autoFocus- className="flex-1 bg-transparent text-sm outline-none placeholder:text-muted-foreground"+ className="h-full flex-1 bg-transparent text-lg text-foreground outline-none placeholder:text-foreground-faint"/>- <kbd className="rounded border border-border bg-muted px-1.5 py-0.5 text-micro font-medium text-muted-foreground">+ {isFetching && debouncedQuery.trim() && (+ <Loader2+ className="h-4 w-4 shrink-0 animate-spin text-muted-foreground motion-reduce:animate-none"+ aria-hidden="true"+ />+ )}+ <kbd className="shrink-0 rounded-sm border border-border px-1.5 py-0.5 font-sans text-xs font-medium text-muted-foreground">Esc</kbd></div>- {/* Results */}- <Command.List className="max-h-80 overflow-y-auto p-1">+ <Command.List className="max-h-96 overflow-y-auto p-2">{!debouncedQuery.trim() ? (- <div className="px-3 py-6 text-center text-xs text-muted-foreground">- {t("docs.search_hint")}- </div>- ) : isFetching ? (- <div className="px-3 py-6 text-center text-xs text-muted-foreground">+ !hasSuggestions ? (+ <div className="px-3 py-10 text-center text-base text-muted-foreground">+ {t("docs.search_hint")}+ </div>+ ) : (+ <>+ {suggestions.recentRows.length > 0 && (+ <Command.Group heading={t("docs.recent")} className={GROUP_CLASS}>+ {suggestions.recentRows.map((row) => (+ <SuggestionItem+ key={`recent-${row.slug}`}+ value={`recent-${row.slug}`}+ icon={Clock}+ row={row}+ onSelect={() => choose(row.slug)}+ />+ ))}+ </Command.Group>+ )}+ {suggestions.startRows.length > 0 && (+ <Command.Group heading={suggestions.startName} className={GROUP_CLASS}>+ {suggestions.startRows.map((row) => (+ <SuggestionItem+ key={`start-${row.slug}`}+ value={`start-${row.slug}`}+ icon={FileText}+ row={row}+ onSelect={() => choose(row.slug)}+ />+ ))}+ </Command.Group>+ )}+ </>+ )+ ) : isFetching && results.length === 0 ? (+ <div className="px-3 py-10 text-center text-base text-muted-foreground">{t("docs.search_loading")}</div>) : error ? (<div- className="flex flex-col items-center px-3 py-6 text-center text-xs text-muted-foreground"+ className="flex flex-col items-center px-3 py-10 text-center text-base text-muted-foreground"role="alert"><FileWarning@@ -92,14 +167,14 @@ export function DocsSearchModal({ open, onOpenChange, onSelect }: Props) {<buttontype="button"onClick={() => void refetch()}- className="mt-3 inline-flex items-center gap-1.5 rounded-md border border-border bg-card px-3 py-1.5 font-medium text-foreground transition-colors hover:bg-muted"+ className="mt-3 inline-flex h-8 items-center gap-1.5 rounded-md border border-border-strong px-3 text-sm font-medium text-foreground transition-colors hover:bg-secondary"><RefreshCw className="h-3 w-3" aria-hidden="true" />{t("docs.search_retry")}</button></div>) : results.length === 0 ? (- <Command.Empty className="px-3 py-6 text-center text-xs text-muted-foreground">+ <Command.Empty className="px-3 py-10 text-center text-base text-muted-foreground">{t("docs.no_results").replace("{0}", debouncedQuery)}</Command.Empty>) : (@@ -107,40 +182,42 @@ export function DocsSearchModal({ open, onOpenChange, onSelect }: Props) {<Command.Itemkey={r.slug}value={r.slug}- onSelect={() => {- onSelect(r.slug);- onOpenChange(false);- }}+ onSelect={() => choose(r.slug)}className={cn(- "flex cursor-pointer flex-col gap-1 rounded-md px-3 py-2 text-sm",- "data-[selected=true]:bg-muted",+ "group flex cursor-pointer gap-3 rounded-md px-3 py-2.5",+ "data-[selected=true]:bg-secondary",)}>- <div className="flex items-center gap-2">- <FileText className="h-3 w-3 shrink-0 text-muted-foreground" aria-hidden="true" />- <span className="flex-1 truncate font-medium">- {r.title}- </span>- <span className="shrink-0 text-micro uppercase tracking-wider text-muted-foreground">- {r.section}- </span>- </div>- <div className="ml-5 line-clamp-2 text-xs text-muted-foreground [&>mark]:bg-foreground/30 [&>mark]:text-foreground">- {renderSearchSnippet(r.snippet)}+ <FileText+ className="mt-0.5 h-4 w-4 shrink-0 text-foreground-faint group-data-[selected=true]:text-accent"+ aria-hidden="true"+ />+ <div className="min-w-0 flex-1">+ <div className="flex items-baseline justify-between gap-3">+ <span className="truncate text-base font-medium text-foreground-strong">+ {r.title}+ </span>+ <span className="shrink-0 text-xs text-muted-foreground">+ {r.section}+ </span>+ </div>+ <div className="mt-0.5 line-clamp-2 text-sm text-muted-foreground [&>mark]:rounded-sm [&>mark]:bg-accent-soft [&>mark]:px-0.5 [&>mark]:text-foreground-strong">+ {renderSearchSnippet(r.snippet)}+ </div></div></Command.Item>)))}</Command.List>- {/* Footer */}- <div className="flex items-center justify-between border-t border-border bg-muted/20 px-3 py-1.5 text-micro text-muted-foreground">- <span>- <kbd className="rounded border border-border px-1 font-medium">↑↓</kbd>{" "}+ <div className="flex items-center gap-4 border-t border-border px-4 py-2 text-xs text-muted-foreground">+ <span className="flex items-center gap-1.5">+ <kbd className={KBD_CLASS}>↑</kbd>+ <kbd className={KBD_CLASS}>↓</kbd>{t("docs_search_modal.navigate")}</span>- <span>- <kbd className="rounded border border-border px-1 font-medium">↵</kbd>{" "}+ <span className="flex items-center gap-1.5">+ <kbd className={KBD_CLASS}>↵</kbd>{t("docs_search_modal.open")}</span></div>@@ -151,6 +228,45 @@ export function DocsSearchModal({ open, onOpenChange, onSelect }: Props) {);}+interface SuggestionRow {+ slug: string;+ title: string;+ section: string;+}++const GROUP_CLASS =+ "[&_[cmdk-group-heading]]:px-3 [&_[cmdk-group-heading]]:pb-1.5 [&_[cmdk-group-heading]]:pt-3 [&_[cmdk-group-heading]]:text-xs [&_[cmdk-group-heading]]:font-medium [&_[cmdk-group-heading]]:text-muted-foreground";++const KBD_CLASS =+ "inline-flex h-5 min-w-5 items-center justify-center rounded-sm border border-border px-1 font-sans text-xs font-medium";++function SuggestionItem({+ value,+ icon: Icon,+ row,+ onSelect,+}: {+ value: string;+ icon: typeof FileText;+ row: SuggestionRow;+ onSelect: () => void;+}) {+ return (+ <Command.Item+ value={value}+ onSelect={onSelect}+ className="group flex cursor-pointer items-center gap-3 rounded-md px-3 py-2 data-[selected=true]:bg-secondary"+ >+ <Icon+ className="h-4 w-4 shrink-0 text-foreground-faint group-data-[selected=true]:text-accent"+ aria-hidden="true"+ />+ <span className="min-w-0 flex-1 truncate text-base text-foreground">{row.title}</span>+ <span className="shrink-0 text-xs text-muted-foreground">{row.section}</span>+ </Command.Item>+ );+}+export function renderSearchSnippet(value: string): React.ReactNode {const parts = value.split(/(<mark>|<\/mark>)/gi);let marked = false;diff --git a/jarvis/ui/web/frontend/src/components/docs/DocsSidebar.tsx b/jarvis/ui/web/frontend/src/components/docs/DocsSidebar.tsxindex efe39e3f61..cabd93c872 100644--- a/jarvis/ui/web/frontend/src/components/docs/DocsSidebar.tsx+++ b/jarvis/ui/web/frontend/src/components/docs/DocsSidebar.tsx@@ -1,23 +1,12 @@-import { useMemo, useState } from "react";-import {- ChevronDown,- ChevronRight,- Clock,- FileText,- Loader2,- RefreshCw,- Search,-} from "lucide-react";+import { useEffect, useMemo, useState } from "react";+import { ChevronDown, ExternalLink, RefreshCw } from "lucide-react";import { ScrollArea } from "@/components/ui/scroll-area";import { cn } from "@/lib/utils";-import {- buildDocSections,- useDocsGrouped,- type DocNavSummary,-} from "@/hooks/useDocs";-import { useRecentDocs } from "@/hooks/useRecentDocs";+import { buildDocSections, useDocsGrouped } from "@/hooks/useDocs";import { useT } from "@/i18n";+import { openExternalUrl } from "@/lib/openExternal";+import { ONLINE_DOCS_URL, SearchTrigger } from "./docsShared";interface Props {selectedSlug: string | null;@@ -26,6 +15,11 @@ interface Props {onOpenSearch: () => void;}+/**+ * The docs navigation: one search field, an Overview entry, then every topic+ * as a collapsible group of plain text links. No per-row icons or counts —+ * the titles carry the navigation, the active row carries the accent.+ */export function DocsSidebar({selectedSlug,onSelect,@@ -34,244 +28,174 @@ export function DocsSidebar({}: Props) {const t = useT();const { data, isLoading, isFetching, error, refetch } = useDocsGrouped();- const { recent } = useRecentDocs();- const [query, setQuery] = useState("");const [collapsed, setCollapsed] = useState<Set<string>>(new Set());const sections = useMemo(() => buildDocSections(data), [data]);- const filteredSections = useMemo(() => {- const q = query.trim().toLowerCase();- if (!q) return sections;- return sections- .map((section) => ({- ...section,- docs: section.docs.filter(- (d) =>- d.title.toLowerCase().includes(q) ||- d.summary.toLowerCase().includes(q) ||- d.slug.toLowerCase().includes(q) ||- d.tags.some((t) => t.toLowerCase().includes(q)),- ),- }))- .filter((section) => section.docs.length > 0);- }, [query, sections]);+ // Opening a guide from search or a cross-link re-opens its group, so the+ // active row is never hidden inside a collapsed topic.+ useEffect(() => {+ if (!selectedSlug) return;+ const owner = sections.find((section) =>+ section.docs.some((doc) => doc.slug === selectedSlug),+ );+ if (!owner) return;+ setCollapsed((prev) => {+ if (!prev.has(owner.name)) return prev;+ const next = new Set(prev);+ next.delete(owner.name);+ return next;+ });+ }, [selectedSlug, sections]);- const totalCount = useMemo(() => {- return filteredSections.reduce((acc, section) => acc + section.docs.length, 0);- }, [filteredSections]);+ const toggle = (name: string) => {+ setCollapsed((prev) => {+ const next = new Set(prev);+ if (next.has(name)) next.delete(name);+ else next.add(name);+ return next;+ });+ };- // A standing rail, not a card: it runs the full height of the section, so it- // takes the rail ground and separates from the page by fill alone — a- // content-sized surface is what earns --card, and this is not one.return (- <aside className="flex h-full w-72 shrink-0 flex-col border-r border-border bg-sidebar">- {/* Header */}- <div className="border-b border-border px-3 py-3">- <div className="mb-2 flex items-center justify-between">- <button- type="button"- onClick={onShowOverview}- className="rounded-sm text-base font-semibold text-foreground-strong transition-colors hover:text-accent focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"- >- {t("docs_sidebar.title")}- </button>- <button- type="button"- onClick={onOpenSearch}- title={t("docs.fulltext_search")}- aria-label={t("docs.fulltext_search")}- className="rounded-md p-1.5 text-muted-foreground transition hover:bg-secondary hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"- >- <Search className="h-4 w-4" aria-hidden="true" />- </button>- </div>- <label htmlFor="docs-sidebar-filter" className="sr-only">- {t("docs.search_placeholder")}- </label>- <input- id="docs-sidebar-filter"- name="docs-filter"- type="text"- placeholder={t("docs.search_placeholder")}- autoComplete="off"- value={query}- onChange={(e: React.ChangeEvent<HTMLInputElement>) =>- setQuery(e.target.value)- }- className="flex h-9 w-full rounded-md border border-border-strong bg-input px-3 text-base ring-offset-sidebar placeholder:text-foreground-faint transition-colors focus-visible:border-accent focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2"- />- {isLoading ? (- <div- className="mt-2 flex items-center gap-2 text-xs text-muted-foreground"- role="status"- >- <Loader2 className="h-3 w-3 animate-spin text-primary motion-reduce:animate-none" aria-hidden="true" />- <span>{t("docs_sidebar.indexing")}</span>- </div>- ) : error ? (- <button- type="button"- onClick={() => void refetch()}- className="mt-2 inline-flex items-center gap-1.5 text-xs text-destructive transition hover:text-destructive/80"- >- <RefreshCw- className={cn(- "h-3 w-3",- isFetching && "animate-spin motion-reduce:animate-none",- )}- aria-hidden="true"- />- {t("docs_sidebar.retry")}- </button>- ) : (- <p className="mt-2 text-sm text-foreground-faint">- {totalCount} {t("docs_sidebar.documents")}- </p>- )}+ <aside+ aria-label={t("docs_sidebar.title")}+ className="flex h-full w-64 shrink-0 flex-col border-r border-border bg-background"+ >+ <div className="px-4 pb-3 pt-5">+ <SearchTrigger onClick={onOpenSearch} /></div>- {/* Tree */}<ScrollArea className="flex-1">- <div className="px-2 py-2">+ <nav className="px-3 pb-6">+ <NavRow+ label={t("docs_sidebar.overview")}+ active={selectedSlug === null}+ onClick={onShowOverview}+ />+{isLoading && <SidebarSkeleton />}- {/* Recent docs — only when not filtered + at least 1 entry */}- {!isLoading && !query && recent.length > 0 && (- <div className="mb-2">- <div className="mb-1 flex h-6 w-full items-center gap-1 rounded-sm px-3 text-xs font-medium uppercase tracking-wide text-foreground-faint">- <Clock className="h-3 w-3" aria-hidden="true" />- <span>{t("docs.recent")}</span>- <span className="ml-auto text-xs font-normal normal-case tracking-normal">- {recent.length}- </span>- </div>- {recent.map((doc) => (+ {error && !isLoading && (+ <button+ type="button"+ onClick={() => void refetch()}+ className="mt-4 inline-flex items-center gap-1.5 rounded-sm px-3 text-sm text-destructive transition-colors hover:text-destructive/80 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"+ >+ <RefreshCw+ className={cn(+ "h-3 w-3",+ isFetching && "animate-spin motion-reduce:animate-none",+ )}+ aria-hidden="true"+ />+ {t("docs_sidebar.retry")}+ </button>+ )}++ {sections.map((section) => {+ const isCollapsed = collapsed.has(section.name);+ const groupId = `docs-nav-${section.order}-${section.docs[0]?.slug ?? "group"}`;+ return (+ <div key={section.name} className="mt-5"><button- key={doc.slug}type="button"- onClick={() => onSelect(doc.slug)}- data-active={doc.slug === selectedSlug || undefined}- className={cn(- "flex min-h-8 w-full items-start gap-2 rounded-md px-3 py-1.5 text-left text-base text-muted-foreground transition-colors",- "hover:bg-secondary hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",- doc.slug === selectedSlug && "jarvis-nav-active bg-secondary font-medium text-foreground",- )}- title={doc.title}+ onClick={() => toggle(section.name)}+ aria-expanded={!isCollapsed}+ aria-controls={groupId}+ className="group flex w-full items-center justify-between gap-2 rounded-sm px-3 py-1 text-left text-sm font-semibold text-foreground-strong focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring">- <FileText className="mt-1 h-3.5 w-3.5 shrink-0" aria-hidden="true" />- <span className="flex-1 break-words line-clamp-2">- {doc.title}- </span>- </button>- ))}- <div className="my-2 border-b border-border/40" />- </div>- )}-- {filteredSections.map((section) => {- const isCollapsed = collapsed.has(section.name);- return (- <div key={section.name} className="mb-2">- <button- type="button"- onClick={() => {- const next = new Set(collapsed);- if (isCollapsed) next.delete(section.name);- else next.add(section.name);- setCollapsed(next);- }}- aria-expanded={!isCollapsed}- className="group mb-1 mt-4 flex h-6 w-full items-center gap-1 rounded-sm px-3 text-xs font-medium uppercase tracking-wide text-foreground-faint transition-colors hover:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"- >- {isCollapsed ? (- <ChevronRight className="h-3 w-3" aria-hidden="true" />- ) : (- <ChevronDown className="h-3 w-3" aria-hidden="true" />+ <span>{section.name}</span>+ <ChevronDown+ className={cn(+ "h-3.5 w-3.5 shrink-0 text-foreground-faint opacity-0 transition group-hover:opacity-100 group-focus-visible:opacity-100",+ isCollapsed && "-rotate-90 opacity-100",)}- <span>{section.name}</span>- <span className="ml-auto text-xs font-normal normal-case tracking-normal">- {section.docs.length}- </span>- </button>- {!isCollapsed &&- section.docs.map((doc) => (- <SidebarItem- key={doc.slug}- doc={doc}- active={doc.slug === selectedSlug}- onClick={() => onSelect(doc.slug)}- />+ aria-hidden="true"+ />+ </button>+ {!isCollapsed && (+ <ul id={groupId} className="mt-1 space-y-px">+ {section.docs.map((doc) => (+ <li key={doc.slug}>+ <NavRow+ label={doc.title}+ active={doc.slug === selectedSlug}+ onClick={() => onSelect(doc.slug)}+ />+ </li>))}- </div>- );- })}-- {!isLoading && !error && totalCount === 0 && (- <div className="px-3 py-8 text-center text-base text-muted-foreground">- {t("docs_sidebar.no_results")}- </div>- )}- </div>+ </ul>+ )}+ </div>+ );+ })}+ </nav></ScrollArea>++ <div className="border-t border-border px-4 py-3">+ <a+ href={ONLINE_DOCS_URL}+ onClick={(event) => {+ event.preventDefault();+ void openExternalUrl(ONLINE_DOCS_URL);+ }}+ rel="noopener noreferrer"+ className="inline-flex items-center gap-1.5 rounded-sm text-sm text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"+ >+ {t("docs_sidebar.github")}+ <ExternalLink className="h-3 w-3" aria-hidden="true" />+ </a>+ </div></aside>);}-interface ItemProps {- doc: DocNavSummary;+function NavRow({+ label,+ active,+ onClick,+}: {+ label: string;active: boolean;onClick: () => void;+}) {+ return (+ <button+ type="button"+ onClick={onClick}+ data-active={active || undefined}+ aria-current={active ? "page" : undefined}+ title={label}+ className={cn(+ "block w-full rounded-md px-3 py-1.5 text-left text-base text-muted-foreground transition-colors",+ "hover:bg-secondary hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",+ active && "jarvis-nav-active font-medium",+ )}+ >+ <span className="line-clamp-2 break-words">{label}</span>+ </button>+ );}function SidebarSkeleton() {return (<div- className="animate-pulse space-y-5 px-2 py-2 motion-reduce:animate-none"+ className="mt-5 animate-pulse space-y-6 px-3 motion-reduce:animate-none"aria-hidden="true">- {[4, 3, 5].map((rows, group) => (- <div key={group} className="space-y-2">- <div className="h-2 w-24 rounded-full bg-muted" />+ {[5, 4, 6].map((rows, group) => (+ <div key={group} className="space-y-3">+ <div className="h-2.5 w-24 rounded-full bg-muted" />{Array.from({ length: rows }, (_, row) => (- <div key={row} className="flex items-center gap-2 py-1">- <div className="h-3 w-3 rounded-sm bg-muted/80" />- <div- className="h-2.5 rounded-full bg-muted/80"- style={{ width: `${58 + ((row + group) % 3) * 12}%` }}- />- </div>+ <div+ key={row}+ className="h-2.5 rounded-full bg-muted/70"+ style={{ width: `${55 + ((row + group) % 3) * 14}%` }}+ />))}</div>))}</div>);}--function SidebarItem({ doc, active, onClick }: ItemProps) {- // Doc titles should be fully readable (user mandate 2026-04-29) —- // ``break-words`` allows wrapping inside German compound words,- // ``line-clamp-2`` caps it at 2 lines max so the list doesn't sprawl, and- // the ``title`` attribute stays as a hover tooltip for the full title.- // NO Diataxis pill — the section header above already carries that info- // (user mandate: no duplicate information, no truncated ``LEGAC...`` pill).- return (- <button- type="button"- onClick={onClick}- data-active={active || undefined}- aria-current={active ? "page" : undefined}- className={cn(- "flex min-h-8 w-full items-start gap-2 rounded-md px-3 py-1.5 text-left text-base text-muted-foreground transition-colors",- "hover:bg-secondary hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",- active && "jarvis-nav-active bg-secondary font-medium text-foreground",- )}- title={doc.title}- >- <FileText className="mt-1 h-3.5 w-3.5 shrink-0" aria-hidden="true" />- <span className="flex-1 break-words line-clamp-2">- {doc.title}- </span>- </button>- );-}diff --git a/jarvis/ui/web/frontend/src/components/docs/DocsToc.tsx b/jarvis/ui/web/frontend/src/components/docs/DocsToc.tsxindex 983c583c88..4a4e96f22c 100644--- a/jarvis/ui/web/frontend/src/components/docs/DocsToc.tsx+++ b/jarvis/ui/web/frontend/src/components/docs/DocsToc.tsx@@ -1,6 +1,6 @@import { useEffect, useMemo, useState } from "react";+import { AlignLeft } from "lucide-react";-import { ScrollArea } from "@/components/ui/scroll-area";import { cn } from "@/lib/utils";import type { DocHeading } from "@/hooks/useDocs";import { useT } from "@/i18n";@@ -13,7 +13,7 @@ interface Props {/*** Right-sidebar table of contents with active-heading tracking via- * IntersectionObserver — Anthropic/Mintlify style.+ * IntersectionObserver.** Reacts to H2 + H3. H4-H6 are rare in our docs but could be added here if* needed. The active-heading trigger is shifted by the heading height via@@ -40,6 +40,7 @@ export function DocsToc({ headings, contentRef }: Props) {if (el) observed.push(el);}if (!observed.length) return;+ setActiveSlug(observed[0].id);const observer = new IntersectionObserver((entries) => {@@ -64,46 +65,60 @@ export function DocsToc({ headings, contentRef }: Props) {);for (const el of observed) observer.observe(el);- return () => observer.disconnect();++ // The last sections of a page can be too short to ever reach the top+ // band; once the reader hits the bottom, the final heading is current.+ const onScroll = () => {+ const atBottom =+ container.scrollTop + container.clientHeight >= container.scrollHeight - 4;+ if (atBottom) setActiveSlug(observed[observed.length - 1].id);+ };+ container.addEventListener("scroll", onScroll, { passive: true });+ return () => {+ observer.disconnect();+ container.removeEventListener("scroll", onScroll);+ };}, [tocHeadings, contentRef]);if (!tocHeadings.length) {return null;}+ // Sticky inside the docs scroller, so it travels beside the article+ // instead of hugging the window edge.return (- <aside- className="hidden h-full w-64 shrink-0 border-l border-border xl:block"+ <nav+ className="sticky top-0 hidden max-h-screen w-56 shrink-0 self-start overflow-y-auto pb-10 pt-12 xl:block"aria-label={t("docs_content.on_this_page")}>- <ScrollArea className="h-full">- <div className="px-4 py-6">- <h3 className="mb-3 text-micro font-semibold uppercase tracking-wider text-muted-foreground">- {t("docs_content.on_this_page")}- </h3>- <ul className="space-y-1 text-xs">- {tocHeadings.map((h) => (- <li key={h.slug}>- <a- href={`#${h.slug}`}- onClick={(e) => handleClick(e, h.slug)}- aria-current={activeSlug === h.slug ? "location" : undefined}- className={cn(- "block rounded py-0.5 transition",- "text-muted-foreground hover:text-foreground",- h.level === 3 && "ml-3",- activeSlug === h.slug &&- "border-l-2 border-primary pl-2 -ml-px font-medium text-foreground",- )}- >- {h.text}- </a>- </li>- ))}- </ul>- </div>- </ScrollArea>- </aside>+ <p className="mb-3 flex items-center gap-2 text-sm font-semibold text-foreground-strong">+ <AlignLeft className="h-3.5 w-3.5 text-muted-foreground" aria-hidden="true" />+ {t("docs_content.on_this_page")}+ </p>+ <ul className="border-l border-border text-sm">+ {tocHeadings.map((h) => {+ const active = activeSlug === h.slug;+ return (+ <li key={h.slug}>+ <a+ href={`#${h.slug}`}+ onClick={(e) => handleClick(e, h.slug)}+ aria-current={active ? "location" : undefined}+ className={cn(+ "-ml-px block border-l py-1 pr-2 transition-colors",+ h.level === 3 ? "pl-7" : "pl-4",+ active+ ? "border-accent font-medium text-accent"+ : "border-transparent text-muted-foreground hover:border-border-strong hover:text-foreground",+ )}+ >+ {h.text}+ </a>+ </li>+ );+ })}+ </ul>+ </nav>);}diff --git a/jarvis/ui/web/frontend/src/components/docs/docsShared.tsx b/jarvis/ui/web/frontend/src/components/docs/docsShared.tsxnew file mode 100644index 0000000000..65106f5c41--- /dev/null+++ b/jarvis/ui/web/frontend/src/components/docs/docsShared.tsx@@ -0,0 +1,103 @@+import {+ BookOpen,+ Blocks,+ FileCode2,+ FileText,+ MessageSquare,+ Rocket,+ Search,+ ShieldCheck,+ SlidersHorizontal,+ type LucideIcon,+} from "lucide-react";++import { isMacClient } from "@/lib/embeddedDesktop";+import { cn } from "@/lib/utils";+import { useT } from "@/i18n";++/** Where the Markdown sources of the bundled docs live publicly. */+export const DOCS_REPO_URL = "https://github.com/PersonalJarvis/PersonalJarvis";+export const ONLINE_DOCS_URL = `${DOCS_REPO_URL}/tree/main/docs`;++/** Public URL of one guide's source file (``path`` is repo-relative). */+export function docSourceUrl(path: string): string {+ return `${DOCS_REPO_URL}/blob/main/${path.replace(/^\/+/, "")}`;+}++/**+ * One quiet glyph per topic. Section names come from the guides' front+ * matter, so the lookup is by keyword and any unknown section falls back to a+ * plain page glyph instead of failing.+ */+const SECTION_ICONS: Array<[RegExp, LucideIcon]> = [+ [/start/i, Rocket],+ [/everyday|use/i, MessageSquare],+ [/personali[sz]e|connect/i, SlidersHorizontal],+ [/knowledge|shar/i, BookOpen],+ [/extend|automat/i, Blocks],+ [/privacy|safety|support/i, ShieldCheck],+ [/reference/i, FileCode2],+];++export function sectionIcon(name: string): LucideIcon {+ for (const [pattern, icon] of SECTION_ICONS) {+ if (pattern.test(name)) return icon;+ }+ return FileText;+}++/** The platform's own name for the search chord. */+export function searchShortcutLabel(): string {+ const mac =+ typeof navigator !== "undefined" && isMacClient(navigator.userAgent);+ return mac ? "⌘K" : "Ctrl K";+}++/** Rounded-up reading time at a calm 220 words per minute. */+export function readingMinutes(markdown: string): number {+ const words = markdown+ .replace(/```[\s\S]*?```/g, " ")+ .split(/\s+/)+ .filter(Boolean).length;+ return Math.max(1, Math.ceil(words / 220));+}++/**+ * The search trigger: reads as a field, opens the full-text search dialog.+ * ``size="lg"`` is the hero variant on the docs home.+ */+export function SearchTrigger({+ onClick,+ size = "md",+ className,+}: {+ onClick: () => void;+ size?: "md" | "lg";+ className?: string;+}) {+ const t = useT();+ return (+ <button+ type="button"+ onClick={onClick}+ aria-label={t("docs.search_modal_title")}+ className={cn(+ "group flex w-full items-center gap-2.5 rounded-md border border-border bg-input text-left text-muted-foreground transition-colors",+ "hover:border-border-strong hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",+ size === "lg" ? "h-11 px-4 text-lg" : "h-9 px-3 text-base",+ className,+ )}+ >+ <Search+ className={cn("shrink-0", size === "lg" ? "h-4 w-4" : "h-3.5 w-3.5")}+ aria-hidden="true"+ />+ <span className="flex-1 truncate">+ {size === "lg" ? t("docs.search_hero") : t("docs.search_button")}+ </span>+ <kbd className="shrink-0 rounded-sm border border-border bg-background px-1.5 py-0.5 font-sans text-xs font-medium text-foreground-faint">+ {searchShortcutLabel()}+ </kbd>+ </button>+ );+}diff --git a/jarvis/ui/web/frontend/src/i18n/locales/de.json b/jarvis/ui/web/frontend/src/i18n/locales/de.jsonindex 1a8735774c..7086354819 100644--- a/jarvis/ui/web/frontend/src/i18n/locales/de.json+++ b/jarvis/ui/web/frontend/src/i18n/locales/de.json@@ -3246,7 +3246,9 @@"no_results": "Keine Treffer für \"{0}\"","for_fulltext": "für die Volltextsuche.","could_not_load": "Konnte Doc nicht laden.",- "recent": "Zuletzt"+ "recent": "Zuletzt",+ "search_button": "Doku durchsuchen",+ "search_hero": "Dokumentation durchsuchen"},"sessions": {"select_one": "Wähle links eine Session aus.",@@ -3671,7 +3673,9 @@"indexing": "Lokaler Index wird erstellt…","retry": "Erneut versuchen","documents": "Dokumente",- "no_results": "Keine passenden Dokumente"+ "no_results": "Keine passenden Dokumente",+ "overview": "Übersicht",+ "github": "Doku auf GitHub"},"docs_content": {"prev": "Vorher",@@ -3683,27 +3687,46 @@"on_this_page": "Auf dieser Seite","copy_code": "Code kopieren","code_copied": "Code kopiert",- "skip_to_content": "Zum Dokumentationsinhalt springen"+ "skip_to_content": "Zum Dokumentationsinhalt springen",+ "reading_time": "{0} Min. Lesezeit",+ "reviewed": "Geprüft am {0}",+ "copy_page": "Seite kopieren",+ "page_copied": "Kopiert",+ "view_source": "Quelle ansehen",+ "copy": "Kopieren",+ "pagination": "Vorherige und nächste Anleitung",+ "callout_note": "Hinweis",+ "callout_info": "Info",+ "callout_tip": "Tipp",+ "callout_warning": "Warnung"},"docs_overview": {"eyebrow": "Dokumentation",- "title": "Personal Jarvis Docs",- "description": "Alles von der ersten Einrichtung bis zur Architektur hinter der Sprachsteuerung. Durchsuche die vollständige lokale Bibliothek oder öffne die neu gestaltete öffentliche Dokumentation.",- "online_docs": "Neu gestaltete Online-Docs öffnen",+ "title": "Personal Jarvis Dokumentation",+ "description": "Anleitungen, Konzepte und Referenzen zum Einrichten, Nutzen und Erweitern deines Assistenten.",+ "online_docs": "Auf GitHub ansehen","load_failed_title": "Die Dokumentation konnte nicht geladen werden","load_failed_description": "Der lokale Index wurde nicht rechtzeitig bereit. Versuch es erneut, ohne die App neu zu starten.","retry": "Erneut versuchen","empty_title": "Keine lokalen Dokumente gefunden",- "empty_description": "Die Online-Dokumentation ist weiterhin über die Schaltfläche oben erreichbar.",+ "empty_description": "Die Dokumentation ist auch auf GitHub verfügbar.","local_library": "In der lokalen Bibliothek starten","local_library_description": "Schneller Offline-Zugriff auf die Dokumentation dieser Installation.","indexing_title": "Deine Dokumentation wird vorbereitet","indexing_description": "Die lokale Markdown-Bibliothek wird gelesen und die Volltextsuche aufgebaut. Das dauert normalerweise nur einen Moment.","loading_page": "Dokument wird geladen…",- "browse_by_topic": "Nach Thema durchsuchen",- "browse_description": "Folge einem Lernpfad oder springe direkt zum benötigten Feature.",+ "browse_by_topic": "Nach Thema stöbern",+ "browse_description": "Alle Anleitungen dieser Installation, sortiert nach dem, was du vorhast.","guide": "Anleitung",- "guides": "Anleitungen"+ "guides": "Anleitungen",+ "start_title": "Erste Schritte",+ "start_description": "Neu hier? Lies diese Anleitungen der Reihe nach – von der Installation bis zu deinem ersten Sprachgespräch.",+ "start_reading": "Jetzt lesen",+ "recent_title": "Weiterlesen, wo du aufgehört hast",+ "show_all": "Alle {0} anzeigen",+ "show_less": "Weniger anzeigen",+ "help_title": "Nicht gefunden, was du suchst?",+ "help_description": "Durchsuche alle Anleitungen nach Stichworten oder sieh dir die Quellen auf GitHub an."},"docs_search_modal": {"navigate": "navigieren",diff --git a/jarvis/ui/web/frontend/src/i18n/locales/en.json b/jarvis/ui/web/frontend/src/i18n/locales/en.jsonindex 0943d74fda..f3014b2ed5 100644--- a/jarvis/ui/web/frontend/src/i18n/locales/en.json+++ b/jarvis/ui/web/frontend/src/i18n/locales/en.json@@ -3246,7 +3246,9 @@"no_results": "No results for \"{0}\"","for_fulltext": "for full-text search.","could_not_load": "Could not load doc.",- "recent": "Recent"+ "recent": "Recent",+ "search_button": "Search docs",+ "search_hero": "Search the documentation"},"sessions": {"select_one": "Select a session on the left.",@@ -3671,7 +3673,9 @@"indexing": "Building local index…","retry": "Try again","documents": "documents",- "no_results": "No matching documents"+ "no_results": "No matching documents",+ "overview": "Overview",+ "github": "Docs on GitHub"},"docs_content": {"prev": "Previous",@@ -3683,27 +3687,46 @@"on_this_page": "On this page","copy_code": "Copy code","code_copied": "Code copied",- "skip_to_content": "Skip to documentation content"+ "skip_to_content": "Skip to documentation content",+ "reading_time": "{0} min read",+ "reviewed": "Reviewed {0}",+ "copy_page": "Copy page",+ "page_copied": "Copied",+ "view_source": "View source",+ "copy": "Copy",+ "pagination": "Previous and next guide",+ "callout_note": "Note",+ "callout_info": "Info",+ "callout_tip": "Tip",+ "callout_warning": "Warning"},"docs_overview": {"eyebrow": "Documentation",- "title": "Personal Jarvis docs",- "description": "Everything from first setup to the architecture behind the voice. Browse the complete local library or open the redesigned public documentation.",- "online_docs": "Open redesigned online docs",+ "title": "Personal Jarvis documentation",+ "description": "Guides, concepts, and reference for setting up, using, and extending your assistant.",+ "online_docs": "View on GitHub","load_failed_title": "Documentation could not be loaded","load_failed_description": "The local index did not become ready in time. Try again without restarting the app.","retry": "Try again","empty_title": "No local documents found",- "empty_description": "The online documentation is still available from the button above.",+ "empty_description": "The documentation is also available on GitHub.","local_library": "Start in the local library","local_library_description": "Fast, offline access to the documentation shipped with this installation.","indexing_title": "Preparing your documentation","indexing_description": "Scanning the local Markdown library and building full-text search. This usually takes only a moment.","loading_page": "Loading document…",- "browse_by_topic": "Browse by Topic",- "browse_description": "Follow a learning path or jump to the feature you need.",+ "browse_by_topic": "Browse by topic",+ "browse_description": "Every guide that ships with this installation, grouped by what you want to do.","guide": "guide",- "guides": "guides"+ "guides": "guides",+ "start_title": "Get started",+ "start_description": "New here? Read these guides in order, from installing the app to your first voice conversation.",+ "start_reading": "Start reading",+ "recent_title": "Pick up where you left off",+ "show_all": "Show all {0}",+ "show_less": "Show less",+ "help_title": "Can't find what you need?",+ "help_description": "Search every guide by keyword, or browse the sources on GitHub."},"docs_search_modal": {"navigate": "navigate",diff --git a/jarvis/ui/web/frontend/src/i18n/locales/es.json b/jarvis/ui/web/frontend/src/i18n/locales/es.jsonindex c3f1795e2a..c9c8be79b8 100644--- a/jarvis/ui/web/frontend/src/i18n/locales/es.json+++ b/jarvis/ui/web/frontend/src/i18n/locales/es.json@@ -3246,7 +3246,9 @@"no_results": "Sin resultados para \"{0}\"","for_fulltext": "para la búsqueda completa.","could_not_load": "No se pudo cargar el documento.",- "recent": "Recientes"+ "recent": "Recientes",+ "search_button": "Buscar en la documentación",+ "search_hero": "Buscar en la documentación"},"sessions": {"select_one": "Selecciona una sesión a la izquierda.",@@ -3671,7 +3673,9 @@"indexing": "Creando el índice local…","retry": "Intentar de nuevo","documents": "documentos",- "no_results": "No hay documentos coincidentes"+ "no_results": "No hay documentos coincidentes",+ "overview": "Resumen",+ "github": "Documentación en GitHub"},"docs_content": {"prev": "Anterior",@@ -3683,27 +3687,46 @@"on_this_page": "En esta página","copy_code": "Copiar código","code_copied": "Código copiado",- "skip_to_content": "Saltar al contenido de la documentación"+ "skip_to_content": "Saltar al contenido de la documentación",+ "reading_time": "{0} min de lectura",+ "reviewed": "Revisado el {0}",+ "copy_page": "Copiar página",+ "page_copied": "Copiado",+ "view_source": "Ver fuente",+ "copy": "Copiar",+ "pagination": "Guía anterior y siguiente",+ "callout_note": "Nota",+ "callout_info": "Información",+ "callout_tip": "Consejo",+ "callout_warning": "Advertencia"},"docs_overview": {"eyebrow": "Documentación","title": "Documentación de Personal Jarvis",- "description": "Todo, desde la configuración inicial hasta la arquitectura de la voz. Explora la biblioteca local completa o abre la documentación pública rediseñada.",- "online_docs": "Abrir la documentación web rediseñada",+ "description": "Guías, conceptos y referencias para configurar, usar y ampliar tu asistente.",+ "online_docs": "Ver en GitHub","load_failed_title": "No se pudo cargar la documentación","load_failed_description": "El índice local no estuvo listo a tiempo. Inténtalo de nuevo sin reiniciar la aplicación.","retry": "Intentar de nuevo","empty_title": "No se encontraron documentos locales",- "empty_description": "La documentación web sigue disponible mediante el botón de arriba.",+ "empty_description": "La documentación también está disponible en GitHub.","local_library": "Empieza en la biblioteca local","local_library_description": "Acceso rápido y sin conexión a la documentación incluida en esta instalación.","indexing_title": "Preparando tu documentación","indexing_description": "Se está leyendo la biblioteca Markdown local y creando la búsqueda de texto completo. Normalmente solo tarda un momento.","loading_page": "Cargando documento…","browse_by_topic": "Explorar por tema",- "browse_description": "Sigue una ruta de aprendizaje o ve directamente a la función que necesitas.",+ "browse_description": "Todas las guías incluidas en esta instalación, agrupadas según lo que quieras hacer.","guide": "guía",- "guides": "guías"+ "guides": "guías",+ "start_title": "Primeros pasos",+ "start_description": "¿Eres nuevo? Lee estas guías en orden, desde la instalación hasta tu primera conversación por voz.",+ "start_reading": "Empezar a leer",+ "recent_title": "Continúa donde lo dejaste",+ "show_all": "Mostrar las {0}",+ "show_less": "Mostrar menos",+ "help_title": "¿No encuentras lo que buscas?",+ "help_description": "Busca en todas las guías por palabra clave o consulta las fuentes en GitHub."},"docs_search_modal": {"navigate": "navegar",diff --git a/jarvis/ui/web/frontend/src/i18n/locales/zh.json b/jarvis/ui/web/frontend/src/i18n/locales/zh.jsonindex 947593e9f1..1929aaa07a 100644--- a/jarvis/ui/web/frontend/src/i18n/locales/zh.json+++ b/jarvis/ui/web/frontend/src/i18n/locales/zh.json@@ -3248,7 +3248,9 @@"no_results": "没有找到“{0}”的结果","for_fulltext": "进行全文搜索。","could_not_load": "无法加载文档。",- "recent": "最近"+ "recent": "最近",+ "search_button": "搜索文档",+ "search_hero": "搜索文档"},"sessions": {"select_one": "请在左侧选择一个会话。",@@ -3673,7 +3675,9 @@"indexing": "正在建立本地索引…","retry": "重试","documents": "篇文档",- "no_results": "没有匹配的文档"+ "no_results": "没有匹配的文档",+ "overview": "概览",+ "github": "GitHub 上的文档"},"docs_content": {"prev": "上一篇",@@ -3685,27 +3689,46 @@"on_this_page": "本页内容","copy_code": "复制代码","code_copied": "代码已复制",- "skip_to_content": "跳到文档内容"+ "skip_to_content": "跳到文档内容",+ "reading_time": "阅读约 {0} 分钟",+ "reviewed": "审阅于 {0}",+ "copy_page": "复制页面",+ "page_copied": "已复制",+ "view_source": "查看源文件",+ "copy": "复制",+ "pagination": "上一篇和下一篇指南",+ "callout_note": "注意",+ "callout_info": "信息",+ "callout_tip": "提示",+ "callout_warning": "警告"},"docs_overview": {"eyebrow": "文档","title": "Personal Jarvis 文档",- "description": "从首次设置到语音背后的架构,一应俱全。浏览完整的本地文档库,或打开全新设计的在线文档。",- "online_docs": "打开全新的在线文档",+ "description": "设置、使用和扩展你的助手所需的指南、概念与参考资料。",+ "online_docs": "在 GitHub 上查看","load_failed_title": "无法加载文档","load_failed_description": "本地索引未能及时就绪。无需重启应用,直接重试即可。","retry": "重试","empty_title": "未找到本地文档",- "empty_description": "你仍然可以通过上方按钮访问在线文档。",+ "empty_description": "文档也可以在 GitHub 上查看。","local_library": "从本地文档库开始","local_library_description": "快速、离线地访问此安装附带的文档。","indexing_title": "正在准备你的文档","indexing_description": "正在扫描本地 Markdown 文档库并建立全文搜索。通常只需片刻。","loading_page": "正在加载文档…","browse_by_topic": "按主题浏览",- "browse_description": "沿着学习路径前进,或直接跳到你需要的功能。",+ "browse_description": "本次安装附带的所有指南,按你想完成的事情分组。","guide": "篇指南",- "guides": "篇指南"+ "guides": "篇指南",+ "start_title": "快速开始",+ "start_description": "刚开始使用?按顺序阅读这些指南,从安装应用到第一次语音对话。",+ "start_reading": "开始阅读",+ "recent_title": "从上次离开的地方继续",+ "show_all": "显示全部 {0} 篇",+ "show_less": "收起",+ "help_title": "没有找到需要的内容?",+ "help_description": "按关键词搜索所有指南,或在 GitHub 上浏览源文件。"},"docs_search_modal": {"navigate": "导航",diff --git a/jarvis/ui/web/frontend/src/index.css b/jarvis/ui/web/frontend/src/index.cssindex bee7361903..cccd900132 100644--- a/jarvis/ui/web/frontend/src/index.css+++ b/jarvis/ui/web/frontend/src/index.css@@ -949,6 +949,53 @@ body {--tw-prose-invert-links: hsl(var(--accent));}+/* A docs guide reads from theme tokens only, so the same class list serves+ light and dark; the plugin's inverted palette is pointed at the same+ values. Body copy sits one step below heading ink. */+.docs-prose {+ --tw-prose-body: hsl(var(--foreground-secondary));+ --tw-prose-headings: hsl(var(--foreground-strong));+ --tw-prose-lead: hsl(var(--muted-foreground));+ --tw-prose-bold: hsl(var(--foreground-strong));+ --tw-prose-counters: hsl(var(--muted-foreground));+ --tw-prose-bullets: hsl(var(--foreground-faint));+ --tw-prose-hr: hsl(var(--border));+ --tw-prose-quotes: hsl(var(--foreground-secondary));+ --tw-prose-quote-borders: hsl(var(--border-strong));+ --tw-prose-code: hsl(var(--foreground-strong));+ --tw-prose-th-borders: hsl(var(--border));+ --tw-prose-td-borders: hsl(var(--border));+ --tw-prose-invert-body: hsl(var(--foreground-secondary));+ --tw-prose-invert-headings: hsl(var(--foreground-strong));+ --tw-prose-invert-bold: hsl(var(--foreground-strong));+ --tw-prose-invert-bullets: hsl(var(--foreground-faint));+ --tw-prose-invert-hr: hsl(var(--border));+ --tw-prose-invert-code: hsl(var(--foreground-strong));+ font-size: 16px;+ line-height: 28px;+ letter-spacing: 0;+}++/* Headings are wrapped in their own anchor (rehype-autolink-headings). The+ anchor keeps heading ink and reveals a quiet "#" on hover, so a section+ link can be copied without turning every heading into link colour. */+.docs-prose :is(h2, h3, h4) > a {+ color: inherit;+ font-weight: inherit;+ text-decoration: none;+}+.docs-prose :is(h2, h3, h4) > a::after {+ content: "#";+ margin-left: 0.4em;+ color: hsl(var(--foreground-faint));+ opacity: 0;+ transition: opacity 120ms ease;+}+.docs-prose :is(h2, h3, h4):hover > a::after,+.docs-prose :is(h2, h3, h4) > a:focus-visible::after {+ opacity: 1;+}+/* Selecting text answers in the theme's own material, not the engine'sdefault blue — the one saturated slab a black-and-white product used toshow every time someone dragged across a sentence. */diff --git a/jarvis/ui/web/frontend/src/views/DocsView.tsx b/jarvis/ui/web/frontend/src/views/DocsView.tsxindex 72220d58c0..8b4c64f31b 100644--- a/jarvis/ui/web/frontend/src/views/DocsView.tsx+++ b/jarvis/ui/web/frontend/src/views/DocsView.tsx@@ -9,9 +9,9 @@ import { useRecentDocs } from "@/hooks/useRecentDocs";import { useT } from "@/i18n";/**- * Top-level view for the docs section. 3-column layout (Anthropic/Mintlify style):- * left sidebar = Diataxis tree, middle = Markdown body, right = TOC with- * active-heading spy.+ * Top-level view for the docs section. The navigation rail stays put on the+ * left; the article and its "On this page" list share one centred scroller,+ * so the table of contents travels beside the text at every window width.** ``selectedSlug`` is view-local — not a state-store entry, because the doc* only matters within this view. When switching sections we deliberately@@ -106,15 +106,22 @@ export function DocsView() {id="docs-content"ref={contentRef as React.RefObject<HTMLElement>}tabIndex={-1}- className="min-w-0 flex-1 overflow-y-auto"+ className="min-w-0 flex-1 overflow-y-auto focus-visible:outline-none">- <DocsContent- slug={selectedSlug}- onSelect={selectDoc}- onShowOverview={showOverview}- />+ <div className="mx-auto flex w-full max-w-6xl gap-12 px-10">+ <div className="min-w-0 flex-1">+ <DocsContent+ slug={selectedSlug}+ onSelect={selectDoc}+ onShowOverview={showOverview}+ onOpenSearch={() => setSearchOpen(true)}+ />+ </div>+ {selectedSlug && (+ <DocsToc headings={headings} contentRef={contentRef} />+ )}+ </div></main>- <DocsToc headings={headings} contentRef={contentRef} /><DocsSearchModalopen={searchOpen}