v0.19.0 frontend: /docs/* route tree + flyout nav + sessions browser

Reorganizes the /docs surface from a single DOCS.md route into a hub with a left-side flyout nav and three new sub-routes for the on-site sessions browser (roadmap item #30): /docs → redirect to /docs/user-guide /docs/user-guide → existing DOCS.md content /docs/sessions → redirect to /docs/sessions/about /docs/sessions/about → README.md of ohm-session-history /docs/sessions/<NNNN> → per-session transcript index /docs/sessions/<NNNN>/<f> → per-transcript view The flyout is a persistent left sidebar on desktop and a slide-out drawer on mobile (toggled by a ☰ button in the docs header). Its session list is driven by the /api/docs/sessions/manifest fetch — loading shows a skeleton; 502 shows an inline retry; empty manifest shows only the "About" row. Each sub-route owns its own empty-state / error handling: - 404 transcripts render "This transcript isn't published yet" with a link back to the parent session index, no JS crash. - 502 (gitea unreachable) renders a retry button. - Manifest 404 is mapped to {} server-side so the flyout renders cleanly with no error banner when no sessions are published yet. Analytics (per SPEC §21): - new EVENTS.DOC_VIEWED ("Doc Viewed") fires on each sub-route mount with `section`: 'user-guide' | 'sessions/about' | 'sessions/<NNNN>' | 'sessions/<NNNN>/<filename>'. - every interactive nav element carries aria-label + data-amp-track-name so autocapture rows are readable. The existing v0.14.0 Docs.jsx component is dropped — its content moved verbatim into DocsUserGuide.jsx; the new layout subsumes the back-button + signed-out home affordances it used to carry. All four new sub-routes reuse the existing MarkdownPreview renderer (marked + mermaid lazy-load) so no second markdown library lands. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-28 09:07:20 -07:00
parent 39e57706d9
commit 822f4266f6
11 changed files with 864 additions and 56 deletions
@@ -0,0 +1,99 @@
+// DocsSessionsAbout.jsx — v0.19.0 / roadmap item #30.
+//
+// Renders the README.md of the public `wiggleverse/ohm-session-history`
+// repo at `/docs/sessions/about`. The framework backend mediates the
+// gitea fetch (see backend/app/docs_sessions.py); this component
+// handles three response paths:
+//
+//   200 → render the markdown via MarkdownPreview
+//   404 → "About not yet published" empty-state (the upstream README
+//         doesn't exist yet — happens when a deployment hasn't
+//         restructured its session-history repo yet, expected at
+//         v0.19.0 deploy time per the CHANGELOG)
+//   502 → "Couldn't reach the session-history repo" with a retry
+//         button. The retry just re-invokes the fetch — no extra
+//         backoff because the backend cache already smoothes
+//         repeated 502s.
+
+import { useEffect, useState, useCallback } from 'react'
+import MarkdownPreview from './MarkdownPreview.jsx'
+import { getSessionsAbout } from '../api.js'
+import { EVENTS, track } from '../lib/analytics'
+
+export default function DocsSessionsAbout() {
+  const [body, setBody] = useState('')
+  const [status, setStatus] = useState('loading') // loading | ok | notfound | error
+  const [reloadTick, setReloadTick] = useState(0)
+
+  useEffect(() => {
+    track(EVENTS.DOC_VIEWED, { section: 'sessions/about' })
+  }, [])
+
+  useEffect(() => {
+    let active = true
+    setStatus('loading')
+    getSessionsAbout()
+      .then(text => {
+        if (!active) return
+        setBody(text || '')
+        setStatus('ok')
+      })
+      .catch(e => {
+        if (!active) return
+        if (e.status === 404) {
+          setStatus('notfound')
+        } else {
+          setStatus('error')
+        }
+      })
+    return () => { active = false }
+  }, [reloadTick])
+
+  const retry = useCallback(() => setReloadTick(t => t + 1), [])
+
+  return (
+    <article className="docs-article">
+      <h1 className="docs-article-title">About sessions</h1>
+      {status === 'loading' && <p className="muted">Loading…</p>}
+      {status === 'notfound' && (
+        <div className="docs-empty">
+          <p>
+            The session-history About page isn't published yet. Sessions
+            are still authored — once a few have shipped, this page will
+            render the canonical introduction.
+          </p>
+          <p>
+            In the meantime, browse the source repo directly at{' '}
+            <a
+              href="https://git.wiggleverse.org/wiggleverse/ohm-session-history"
+              target="_blank"
+              rel="noopener noreferrer"
+              aria-label="Open session-history repo on gitea"
+              data-amp-track-name="Docs Sessions About Repo Link"
+            >
+              wiggleverse/ohm-session-history
+            </a>.
+          </p>
+        </div>
+      )}
+      {status === 'error' && (
+        <div className="docs-error" role="alert">
+          <p>Couldn't reach the session-history repo.</p>
+          <button
+            type="button"
+            onClick={retry}
+            aria-label="Retry"
+            data-amp-track-name="Docs Sessions About Retry"
+          >
+            Try again
+          </button>
+        </div>
+      )}
+      {status === 'ok' && (
+        <div className="philosophy-body">
+          <MarkdownPreview content={body} />
+        </div>
+      )}
+    </article>
+  )
+}