feat(console): docs portal UX pass (landing, mobile nav, index, cards)

os-zhuang · claude · os-zhuang · commit 4c3044efbf60 · 2026-06-16T17:37:23.000+08:00
Browser-found polish across the portal:

- Book landing no longer duplicates the table of contents (sidebar + a
  second card list). `/docs/:slug` now opens the book to its overview doc
  (`*_index`, else the first in order) — a redirect into the reader, whose
  sidebar already is the TOC. A doc-less book shows an empty state.
- Narrow screens (&lt; lg) had no book nav at all (the sidebar is lg-only).
  The reader now collapses the book nav into a `&lt;details&gt;` disclosure above
  the content, so mobile/tablet readers can still move within the book.
- DocsIndex gains a page heading + intro and even-height cards.
- Implicit per-package book cards (no authored description) show their
  package id as a subtitle for context; AppDocsIndex matches.

book-nav gains `firstDoc` + a `Book.implicit` flag / `BookCard.subtitle`.
Tests: book-nav 19 (+2) + integration updated for the redirect and the
twice-rendered responsive sidebar; 49 in pages. tsc 0, eslint 0.
Verified in-browser against the showcase backend.

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/apps/console/src/pages/AppDocsIndex.tsx b/apps/console/src/pages/AppDocsIndex.tsx
@@ -73,6 +73,10 @@ export default function AppDocsIndex() {
                       <div className="mt-0.5 line-clamp-2 text-xs text-muted-foreground">
                         {card.description}
                       </div>
+                    ) : card.subtitle ? (
+                      <div className="mt-0.5 truncate font-mono text-[11px] text-muted-foreground/70">
+                        {card.subtitle}
+                      </div>
                     ) : null}
                     <div className="mt-1 text-xs text-muted-foreground/80">
                       {card.docCount} {card.docCount === 1 ? 'article' : 'articles'}
diff --git a/apps/console/src/pages/BookPage.tsx b/apps/console/src/pages/BookPage.tsx
@@ -7,34 +7,29 @@
  */
 
 import { useMemo } from 'react';
-import { Link, useParams } from 'react-router-dom';
-import { FileText, FileQuestion, Loader2 } from 'lucide-react';
+import { Navigate, useParams } from 'react-router-dom';
+import { BookOpen, FileQuestion, Loader2 } from 'lucide-react';
 import { DocShell } from './DocShell';
-import { BookSidebar } from './BookSidebar';
 import { useBookData } from './use-book-data';
-import { resolveBookTree, scopeDocsToBook, bookSlug } from './book-nav';
+import { resolveBookTree, scopeDocsToBook, bookSlug, firstDoc } from './book-nav';
 
 /**
- * `/docs/:slug` — a book landing page (ADR-0046 §6). Resolves the book's spine
- * against the current docs and shows the grouped table of contents: the
- * persistent nav sidebar plus an overview that lists every section's docs. Each
- * doc links to the in-book reader (`/docs/:slug/:name`), which keeps this
- * sidebar in view. `:slug` is the book's `slug` (an implicit per-package book
- * uses its packageId).
+ * `/docs/:slug` — a book landing (ADR-0046 §6). Opening a book means starting
+ * to read it, so this resolves the book's spine and redirects to its overview
+ * doc (`*_index`, else the first doc in order); the reader then shows that doc
+ * with the book sidebar. This avoids duplicating the table of contents (the
+ * sidebar already is it). A book with no readable docs shows an empty state.
  */
 export default function BookPage() {
   const { slug, appName } = useParams<{ slug: string; appName?: string }>();
-  const { books, docs, state, error } = useBookData();
+  const { books, docs, state } = useBookData();
 
   const found = useMemo(() => books.find((b) => bookSlug(b) === slug), [books, slug]);
-  const resolved = useMemo(
-    () => (found ? resolveBookTree(found, scopeDocsToBook(found, docs)) : null),
+  const opensTo = useMemo(
+    () => (found ? firstDoc(resolveBookTree(found, scopeDocsToBook(found, docs))) : undefined),
     [found, docs],
   );
 
-  const base = appName ? `/apps/${appName}/docs` : '/docs';
-  const docHref = (name: string) => `${base}/${slug}/${name}`;
-
   if (state === 'loading') {
     return (
       <div className="flex h-full items-center justify-center p-10 text-muted-foreground">
@@ -43,87 +38,30 @@ export default function BookPage() {
     );
   }
 
-  if (state === 'error' || !found || !resolved) {
-    return (
-      <DocShell breadcrumb={slug}>
-        <div className="mx-auto flex max-w-3xl flex-col items-center gap-3 p-10 text-center">
-          <FileQuestion className="h-10 w-10 text-muted-foreground" />
-          <h1 className="text-lg font-semibold">
-            {state === 'error' ? 'Failed to load documentation' : 'Book not found'}
-          </h1>
-          <p className="text-sm text-muted-foreground">
-            {error ?? (
-              <>
-                No book named <code className="rounded bg-muted px-1 py-0.5">{slug}</code> is installed.
-              </>
-            )}
-          </p>
-        </div>
-      </DocShell>
-    );
+  if (found && opensTo) {
+    const base = appName ? `/apps/${appName}/docs` : '/docs';
+    return <Navigate to={`${base}/${slug}/${opensTo}`} replace />;
   }
 
+  // Unknown book, or a book with no readable docs yet.
   return (
-    <DocShell breadcrumb={resolved.label ?? slug}>
-      <div className="mx-auto flex max-w-5xl gap-8 p-4 sm:p-6">
-        <aside className="hidden w-60 shrink-0 lg:block">
-          <div className="sticky top-20 max-h-[calc(100vh-6rem)] overflow-auto pr-1">
-            <BookSidebar book={resolved} docHref={docHref} />
-          </div>
-        </aside>
-
-        <div className="min-w-0 max-w-3xl flex-1">
-          <h1 className="text-2xl font-bold">{resolved.label ?? slug}</h1>
-          {resolved.description ? (
-            <p className="mt-2 text-sm text-muted-foreground">{resolved.description}</p>
-          ) : null}
-
-          <div className="mt-6 space-y-8">
-            {resolved.groups.map((group) => (
-              <section key={group.key}>
-                <h2 className="mb-2 text-xs font-semibold uppercase tracking-wide text-muted-foreground">
-                  {group.label}
-                </h2>
-                <ul className="divide-y divide-border rounded-md border border-border">
-                  {group.entries
-                    .filter((e) => !e.separator)
-                    .map((entry, i) =>
-                      entry.href ? (
-                        <li key={`ext-${i}`}>
-                          <a
-                            href={entry.href}
-                            target="_blank"
-                            rel="noreferrer"
-                            className="flex items-start gap-3 px-3 py-3 hover:bg-muted/50"
-                          >
-                            <FileText className="mt-0.5 h-4 w-4 shrink-0 text-muted-foreground" />
-                            <span className="text-sm font-medium">{entry.label ?? entry.href}</span>
-                          </a>
-                        </li>
-                      ) : entry.doc ? (
-                        <li key={entry.doc}>
-                          <Link
-                            to={docHref(entry.doc)}
-                            className="flex items-start gap-3 px-3 py-3 hover:bg-muted/50"
-                          >
-                            <FileText className="mt-0.5 h-4 w-4 shrink-0 text-muted-foreground" />
-                            <div className="min-w-0">
-                              <div className="text-sm font-medium">{entry.label ?? entry.doc}</div>
-                              {entry.description ? (
-                                <div className="mt-0.5 line-clamp-2 text-xs text-muted-foreground">
-                                  {entry.description}
-                                </div>
-                              ) : null}
-                            </div>
-                          </Link>
-                        </li>
-                      ) : null,
-                    )}
-                </ul>
-              </section>
-            ))}
-          </div>
-        </div>
+    <DocShell breadcrumb={found ? (found.label ?? slug) : slug}>
+      <div className="mx-auto flex max-w-3xl flex-col items-center gap-3 p-10 text-center">
+        {found ? (
+          <>
+            <BookOpen className="h-10 w-10 text-muted-foreground" />
+            <h1 className="text-lg font-semibold">{found.label ?? slug}</h1>
+            <p className="text-sm text-muted-foreground">This book has no documents yet.</p>
+          </>
+        ) : (
+          <>
+            <FileQuestion className="h-10 w-10 text-muted-foreground" />
+            <h1 className="text-lg font-semibold">Book not found</h1>
+            <p className="text-sm text-muted-foreground">
+              No book named <code className="rounded bg-muted px-1 py-0.5">{slug}</code> is installed.
+            </p>
+          </>
+        )}
       </div>
     </DocShell>
   );
diff --git a/apps/console/src/pages/DocPage.tsx b/apps/console/src/pages/DocPage.tsx
@@ -8,7 +8,7 @@
 
 import { useCallback, useEffect, useMemo, useState } from 'react';
 import { useNavigate, useParams } from 'react-router-dom';
-import { AlertCircle, FileQuestion, Loader2 } from 'lucide-react';
+import { AlertCircle, ChevronDown, FileQuestion, Loader2, Menu } from 'lucide-react';
 import { useAdapter } from '@object-ui/app-shell';
 import { MarkdownRenderer, extractToc } from '@object-ui/plugin-markdown';
 import { useObjectTranslation } from '@object-ui/i18n';
@@ -156,6 +156,20 @@ export default function DocPage() {
 
   return (
     <DocShell breadcrumb={doc?.label ?? name}>
+      {/* Narrow screens: the persistent left sidebar is hidden, so the book
+        * nav collapses into a disclosure above the content instead of vanishing. */}
+      {resolvedBook ? (
+        <details className="group mx-auto max-w-6xl px-4 pt-4 sm:px-6 lg:hidden">
+          <summary className="flex cursor-pointer list-none items-center gap-2 rounded-md border bg-muted/30 px-3 py-2 text-sm font-medium [&::-webkit-details-marker]:hidden">
+            <Menu className="h-4 w-4 text-muted-foreground" />
+            <span className="truncate">{resolvedBook.label ?? 'Contents'}</span>
+            <ChevronDown className="ml-auto h-4 w-4 text-muted-foreground transition-transform group-open:rotate-180" />
+          </summary>
+          <div className="mt-2 rounded-md border p-3">
+            <BookSidebar book={resolvedBook} activeDoc={name} docHref={docHref} />
+          </div>
+        </details>
+      ) : null}
       <div className={`mx-auto flex gap-8 p-4 sm:p-6 ${resolvedBook ? 'max-w-6xl' : 'max-w-5xl'}`}>
         {resolvedBook ? (
           <aside className="hidden w-56 shrink-0 lg:block">
diff --git a/apps/console/src/pages/DocsIndex.tsx b/apps/console/src/pages/DocsIndex.tsx
@@ -48,7 +48,13 @@ export default function DocsIndex() {
 
   return (
     <DocShell>
-      <div className="mx-auto max-w-3xl p-4 sm:p-6">
+      <div className="mx-auto max-w-4xl p-4 sm:p-6">
+        <header className="mb-6">
+          <h1 className="text-2xl font-bold tracking-tight">Documentation</h1>
+          <p className="mt-1 text-sm text-muted-foreground">
+            Books and guides from your installed packages.
+          </p>
+        </header>
         {cards.length === 0 ? (
           <div className="flex flex-col items-center gap-3 py-16 text-center text-muted-foreground">
             <BookOpen className="h-10 w-10" />
@@ -59,9 +65,9 @@ export default function DocsIndex() {
             </p>
           </div>
         ) : (
-          <ul className="grid gap-3 sm:grid-cols-2">
+          <ul className="grid items-stretch gap-3 sm:grid-cols-2">
             {cards.map((card) => (
-              <li key={card.name}>
+              <li key={card.name} className="h-full">
                 <Link
                   to={`/docs/${card.slug}`}
                   className="flex h-full items-start gap-3 rounded-md border border-border p-3 hover:bg-muted/50"
@@ -73,6 +79,10 @@ export default function DocsIndex() {
                       <div className="mt-0.5 line-clamp-2 text-xs text-muted-foreground">
                         {card.description}
                       </div>
+                    ) : card.subtitle ? (
+                      <div className="mt-0.5 truncate font-mono text-[11px] text-muted-foreground/70">
+                        {card.subtitle}
+                      </div>
                     ) : null}
                     <div className="mt-1 text-xs text-muted-foreground/80">
                       {card.docCount} {card.docCount === 1 ? 'article' : 'articles'}
diff --git a/apps/console/src/pages/book-nav.test.ts b/apps/console/src/pages/book-nav.test.ts
@@ -12,6 +12,7 @@ import {
   deriveImplicitPackageBook,
   buildBookCards,
   buildPortalBooks,
+  firstDoc,
   homeBook,
   bookSlug,
   pkgOf,
@@ -142,7 +143,18 @@ describe('buildPortalBooks (ADR-0046 §6.4 — no flat/book fork)', () => {
     expect(portal[0].name).toBe('crm_manual');
     expect(portal[portal.length - 1].name).toBe('misc');
     // implicit label is humanized, not the raw package id
-    expect(portal.find((b) => b.name === 'misc')?.label).toBe('Misc');
+    const misc = portal.find((b) => b.name === 'misc');
+    expect(misc?.label).toBe('Misc');
+    expect(misc?.implicit).toBe(true); // synthetic books are flagged
+  });
+
+  it('cards surface the package id as a subtitle for implicit books only', () => {
+    const authored: Book[] = [
+      { name: 'crm_manual', label: 'CRM Manual', description: 'd', groups: [{ key: 'g', label: 'G', include: 'crm_*' }] },
+    ];
+    const cards = buildBookCards(buildPortalBooks(authored, docs), docs);
+    expect(cards.find((c) => c.name === 'crm_manual')?.subtitle).toBeUndefined(); // authored: has a description
+    expect(cards.find((c) => c.name === 'misc')?.subtitle).toBe('misc'); // implicit: package id
   });
 
   it('with no authored books, every package becomes its own implicit book', () => {
@@ -213,6 +225,26 @@ describe('portal helpers', () => {
     expect(findBookContainingDoc(books, docs, 'misc_note')).toBeNull();
   });
 
+  it('firstDoc prefers an *_index doc, else the first in reading order', () => {
+    const withIndex = resolveBookTree(
+      { name: 'b', groups: [{ key: 'g', label: 'G', include: 'crm_*' }] },
+      [
+        { name: 'crm_guide_lead', order: 1 },
+        { name: 'crm_index', order: 9 }, // later in order, but the index wins
+      ],
+    );
+    expect(firstDoc(withIndex)).toBe('crm_index');
+
+    const noIndex = resolveBookTree(
+      { name: 'b', groups: [{ key: 'g', label: 'G', include: 'crm_*' }] },
+      [{ name: 'crm_b', order: 2 }, { name: 'crm_a', order: 1 }],
+    );
+    expect(firstDoc(noIndex)).toBe('crm_a'); // first by order
+
+    // A book with no readable docs → undefined.
+    expect(firstDoc({ name: 'b', label: 'B', groups: [] })).toBeUndefined();
+  });
+
   it('countEntries ignores separators', () => {
     const groups = [
       { key: 'g', label: 'G', entries: [{ doc: 'a' }, { separator: true }, { href: 'x' }] },
diff --git a/apps/console/src/pages/book-nav.ts b/apps/console/src/pages/book-nav.ts
@@ -53,6 +53,8 @@ export interface Book {
   groups?: BookGroup[];
   /** Owning package id (`_packageId`), stamped by the metadata API. */
   packageId?: string;
+  /** True for a synthetic implicit per-package book (ADR-0046 §6.4). */
+  implicit?: boolean;
 }
 
 /** Minimal doc header the resolver needs. */
@@ -267,6 +269,8 @@ export interface BookCard {
   slug: string;
   label: string;
   description?: string;
+  /** Context line for cards without a description — the owning package id. */
+  subtitle?: string;
   icon?: string;
   packageId?: string;
   /** Number of docs the book currently resolves to (excludes separators/links). */
@@ -335,6 +339,9 @@ export function buildBookCards(books: Book[], docs: ResolverDoc[]): BookCard[] {
     slug: bookSlug(b),
     label: b.label ?? b.name,
     description: b.description,
+    // Implicit per-package books have no authored description; surface the
+    // package id so the card still says where the docs come from.
+    subtitle: b.implicit && !b.description ? b.packageId : undefined,
     icon: b.icon,
     packageId: b.packageId,
     docCount: countBookDocs(b, docs),
@@ -356,7 +363,7 @@ export function buildPortalBooks(authored: Book[], docs: ResolverDoc[]): Book[]
     // Humanize the package id for the visible label (the slug/name stays the
     // full id so it remains unique and reversible); keep the group as the
     // generic "Documentation".
-    .map((p) => ({ ...deriveImplicitPackageBook(p), label: humanizePackageId(p), packageId: p }));
+    .map((p) => ({ ...deriveImplicitPackageBook(p), label: humanizePackageId(p), packageId: p, implicit: true }));
   // Authored books lead (curated, primary) in their own order; the synthetic
   // per-package books follow, alphabetically — so an authored book with an
   // explicit `order` is never pushed below a fallback.
@@ -404,6 +411,19 @@ export function findBookContainingDoc(
   return null;
 }
 
+/**
+ * The doc a book opens to — its overview. Prefers an `*_index` doc, else the
+ * first doc in reading order. Returns undefined for a book with no readable
+ * docs (only external links / separators).
+ */
+export function firstDoc(resolved: ResolvedBook): string | undefined {
+  const names: string[] = [];
+  for (const g of resolved.groups) {
+    for (const e of g.entries) if (e.doc && !e.separator) names.push(e.doc);
+  }
+  return names.find((n) => /(^|_)index$/.test(n)) ?? names[0];
+}
+
 /** Total docs an entry list covers — handy for "N articles" labels. */
 export function countEntries(groups: ResolvedGroup[]): number {
   let n = 0;
diff --git a/apps/console/src/pages/docs-portal.test.tsx b/apps/console/src/pages/docs-portal.test.tsx
