Release v0.20.0: /docs/specs surface + nested flyout nav + session body-list removal
Wave 9 follow-up to roadmap item #30 (Session 0017.0 shipped #30 as v0.19.0; v0.20.0 lands the operator-feedback follow-ups on top). 1. Specs on /docs/specs/<name> (backend docs_specs.py + frontend DocsSpec.jsx + DocsSpecsIndex.jsx). Configured via OHM_DOCS_SPECS; framework default carries OHM's two specs (rfc-app/SPEC.md + flotilla SPEC.md). Runtime fetch from gitea raw with 5-min TTL cache, mirroring docs_sessions.py. 2. Nested flyout nav hierarchy (DocsLayout.jsx). Sessions render as a tree with transcripts nested under each session row (labeled by .N ordinal). New Specs section between User Guide and Sessions. 3. /docs/sessions/<NNNN> body-list removed (DocsSessionIndex.jsx). Body becomes a session-overview card; navigation lives in the left nav. 19 new pytest cases for docs_specs (332 backend total green). Frontend build clean. Sync frontend/package-lock.json version drift (0.15.0 → 0.20.0) alongside the VERSION + package.json bump. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ben Stull
@@ -1,40 +1,64 @@
|
||||
// DocsLayout.jsx — v0.19.0 / roadmap item #30.
|
||||
// DocsLayout.jsx — v0.20.0 (was v0.19.0 / roadmap item #30).
|
||||
//
|
||||
// Left-side flyout nav + content area for the `/docs/*` route tree:
|
||||
//
|
||||
// /docs → redirect to /docs/user-guide
|
||||
// /docs/user-guide → DOCS.md (existing v0.14.0 content)
|
||||
// /docs/specs → client-side redirect to first configured spec
|
||||
// /docs/specs/:name → a single framework spec (v0.20.0)
|
||||
// /docs/sessions → redirect to /docs/sessions/about
|
||||
// /docs/sessions/about → README.md from the sessions repo
|
||||
// /docs/sessions/:nnnn → per-session index page
|
||||
// /docs/sessions/:nnnn → per-session overview (nav-only navigation)
|
||||
// /docs/sessions/:nnnn/:file → per-transcript view
|
||||
//
|
||||
// v0.20.0 changes (Session 0018.0):
|
||||
// - Adds a "Specs" section between User Guide and Sessions, driven
|
||||
// by `/api/docs/specs/manifest`.
|
||||
// - Sessions render a nested tree: each session row has the
|
||||
// session's transcripts nested under it as their own nav rows
|
||||
// (labeled by `.N` ordinal). The transcript list is fetched per
|
||||
// session via `/api/docs/sessions/:nnnn/index` (cached server-
|
||||
// side, so the manifest+index fan-out is cheap on subsequent
|
||||
// loads). Always-expanded; no collapse toggle (current scale is
|
||||
// under twenty sessions — well under the threshold where lazy
|
||||
// expansion would pay).
|
||||
//
|
||||
// The flyout is a persistent left sidebar on desktop and a slide-out
|
||||
// drawer on mobile (toggled by the icon button in the docs header).
|
||||
// The session list is driven by the `/api/docs/sessions/manifest`
|
||||
// fetch:
|
||||
// - loading → skeleton in the nav (three placeholder rows)
|
||||
// - manifest 502 → error banner in the nav with "Try again"
|
||||
// - empty manifest → only "About" under Sessions; no NNNN rows
|
||||
//
|
||||
// Amplitude analytics (per SPEC §21):
|
||||
// - track('Doc Viewed', { section: '...' }) on each sub-route mount;
|
||||
// the sub-route component owns the fire (it knows the section).
|
||||
// the sub-route component owns the fire.
|
||||
// - flyout buttons + links carry `aria-label` + `data-amp-track-name`
|
||||
// so autocapture rows are readable rather than ":nth-child(7)".
|
||||
|
||||
import { useEffect, useState, useCallback } from 'react'
|
||||
import { Link, useNavigate, useLocation, Outlet } from 'react-router-dom'
|
||||
import { getSessionsManifest } from '../api.js'
|
||||
import { getSessionsManifest, getSessionIndex, getSpecsManifest } from '../api.js'
|
||||
|
||||
// Extract the `.N` ordinal from a transcript filename:
|
||||
// "SESSION-0014.1-TRANSCRIPT-...md" → "0014.1"
|
||||
// "SESSION-0013.1.1-TRANSCRIPT-...md" → "0013.1.1" (nested subagent)
|
||||
// Returns the bare filename as fallback if the expected shape isn't
|
||||
// matched (which shouldn't happen — the backend index endpoint
|
||||
// filters by the same regex).
|
||||
function transcriptOrdinal(filename) {
|
||||
const m = /^SESSION-(\d{4}\.\d+(?:\.\d+)*)-TRANSCRIPT/.exec(filename)
|
||||
return m ? m[1] : filename
|
||||
}
|
||||
|
||||
export default function DocsLayout({ authenticated }) {
|
||||
const [manifest, setManifest] = useState(null)
|
||||
const [manifestState, setManifestState] = useState('loading') // loading | ok | error
|
||||
const [sessionFiles, setSessionFiles] = useState({}) // { nnnn: [filename, ...] }
|
||||
const [specs, setSpecs] = useState([])
|
||||
const [specsState, setSpecsState] = useState('loading') // loading | ok | error
|
||||
const [drawerOpen, setDrawerOpen] = useState(false)
|
||||
const [reloadTick, setReloadTick] = useState(0)
|
||||
const navigate = useNavigate()
|
||||
const location = useLocation()
|
||||
|
||||
// Manifest fetch — drives the Sessions section.
|
||||
useEffect(() => {
|
||||
let active = true
|
||||
setManifestState('loading')
|
||||
@@ -52,6 +76,45 @@ export default function DocsLayout({ authenticated }) {
|
||||
return () => { active = false }
|
||||
}, [reloadTick])
|
||||
|
||||
// Per-session transcript lists — fan out from the manifest. Always-
|
||||
// expanded means we pre-fetch every session's index alongside the
|
||||
// manifest, gated on the manifest having loaded successfully. The
|
||||
// backend's 5-minute content TTL makes the repeat cost negligible.
|
||||
useEffect(() => {
|
||||
if (manifestState !== 'ok' || !manifest) return
|
||||
let active = true
|
||||
const nnnnList = Object.keys(manifest).sort()
|
||||
Promise.all(
|
||||
nnnnList.map(nnnn =>
|
||||
getSessionIndex(nnnn)
|
||||
.then(payload => [nnnn, (payload && payload.files) || []])
|
||||
.catch(() => [nnnn, []])
|
||||
)
|
||||
).then(pairs => {
|
||||
if (!active) return
|
||||
setSessionFiles(Object.fromEntries(pairs))
|
||||
})
|
||||
return () => { active = false }
|
||||
}, [manifest, manifestState])
|
||||
|
||||
// Specs fetch — drives the Specs section. Independent of sessions.
|
||||
useEffect(() => {
|
||||
let active = true
|
||||
setSpecsState('loading')
|
||||
getSpecsManifest()
|
||||
.then(payload => {
|
||||
if (!active) return
|
||||
setSpecs((payload && payload.specs) || [])
|
||||
setSpecsState('ok')
|
||||
})
|
||||
.catch(() => {
|
||||
if (!active) return
|
||||
setSpecs([])
|
||||
setSpecsState('error')
|
||||
})
|
||||
return () => { active = false }
|
||||
}, [reloadTick])
|
||||
|
||||
// Close the mobile drawer on every navigation so a click in the nav
|
||||
// doesn't strand the user on a drawer-open view.
|
||||
useEffect(() => {
|
||||
@@ -99,6 +162,9 @@ export default function DocsLayout({ authenticated }) {
|
||||
<DocsNav
|
||||
manifest={manifest}
|
||||
manifestState={manifestState}
|
||||
sessionFiles={sessionFiles}
|
||||
specs={specs}
|
||||
specsState={specsState}
|
||||
onRetry={retryManifest}
|
||||
currentPath={location.pathname}
|
||||
/>
|
||||
@@ -119,12 +185,18 @@ export default function DocsLayout({ authenticated }) {
|
||||
)
|
||||
}
|
||||
|
||||
function DocsNav({ manifest, manifestState, onRetry, currentPath }) {
|
||||
function DocsNav({
|
||||
manifest,
|
||||
manifestState,
|
||||
sessionFiles,
|
||||
specs,
|
||||
specsState,
|
||||
onRetry,
|
||||
currentPath,
|
||||
}) {
|
||||
const isActive = (path) => currentPath === path || currentPath.startsWith(path + '/')
|
||||
const isExactly = (path) => currentPath === path
|
||||
|
||||
// Sort session keys ascending (newest sessions render last). The
|
||||
// manifest's keys are zero-padded 4-digit strings so lexicographic
|
||||
// order is the same as numeric.
|
||||
const sessionKeys = Object.keys(manifest || {}).sort()
|
||||
|
||||
return (
|
||||
@@ -145,13 +217,48 @@ function DocsNav({ manifest, manifestState, onRetry, currentPath }) {
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<div className="docs-nav-section">
|
||||
<div className="docs-nav-section-label">Specs</div>
|
||||
{specsState === 'loading' && (
|
||||
<ul className="docs-nav-list docs-nav-skeleton" aria-hidden>
|
||||
<li><span className="skeleton-row" /></li>
|
||||
<li><span className="skeleton-row" /></li>
|
||||
</ul>
|
||||
)}
|
||||
{specsState === 'error' && (
|
||||
<div className="docs-nav-error" role="alert">
|
||||
<span>Couldn't load specs.</span>
|
||||
</div>
|
||||
)}
|
||||
{specsState === 'ok' && specs.length > 0 && (
|
||||
<ul className="docs-nav-list">
|
||||
{specs.map(spec => {
|
||||
const to = `/docs/specs/${spec.name}`
|
||||
return (
|
||||
<li key={spec.name}>
|
||||
<Link
|
||||
to={to}
|
||||
className={isExactly(to) ? 'active' : ''}
|
||||
aria-label={`Spec: ${spec.title}`}
|
||||
data-amp-track-name="Docs Nav Spec"
|
||||
data-amp-track-spec={spec.name}
|
||||
>
|
||||
{spec.title}
|
||||
</Link>
|
||||
</li>
|
||||
)
|
||||
})}
|
||||
</ul>
|
||||
)}
|
||||
</div>
|
||||
|
||||
<div className="docs-nav-section">
|
||||
<div className="docs-nav-section-label">Sessions</div>
|
||||
<ul className="docs-nav-list">
|
||||
<li>
|
||||
<Link
|
||||
to="/docs/sessions/about"
|
||||
className={currentPath === '/docs/sessions/about' ? 'active' : ''}
|
||||
className={isExactly('/docs/sessions/about') ? 'active' : ''}
|
||||
aria-label="About sessions"
|
||||
data-amp-track-name="Docs Nav Sessions About"
|
||||
>
|
||||
@@ -183,23 +290,45 @@ function DocsNav({ manifest, manifestState, onRetry, currentPath }) {
|
||||
)}
|
||||
|
||||
{manifestState === 'ok' && sessionKeys.length > 0 && (
|
||||
<ul className="docs-nav-list">
|
||||
<ul className="docs-nav-list docs-nav-list--tree">
|
||||
{sessionKeys.map(nnnn => {
|
||||
const entry = manifest[nnnn] || {}
|
||||
const title = entry.title || ''
|
||||
const label = title ? `${nnnn} — ${title}` : nnnn
|
||||
const to = `/docs/sessions/${nnnn}`
|
||||
const files = sessionFiles[nnnn] || []
|
||||
return (
|
||||
<li key={nnnn}>
|
||||
<Link
|
||||
to={to}
|
||||
className={isActive(to) ? 'active' : ''}
|
||||
className={isExactly(to) ? 'active' : ''}
|
||||
aria-label={`Session ${nnnn}${title ? ': ' + title : ''}`}
|
||||
data-amp-track-name="Docs Nav Session"
|
||||
data-amp-track-session={nnnn}
|
||||
>
|
||||
{label}
|
||||
</Link>
|
||||
{files.length > 0 && (
|
||||
<ul className="docs-nav-list docs-nav-list--children">
|
||||
{files.map(f => {
|
||||
const tTo = `/docs/sessions/${nnnn}/${f}`
|
||||
return (
|
||||
<li key={f}>
|
||||
<Link
|
||||
to={tTo}
|
||||
className={isExactly(tTo) ? 'active' : ''}
|
||||
aria-label={`Transcript ${transcriptOrdinal(f)}`}
|
||||
data-amp-track-name="Docs Nav Transcript"
|
||||
data-amp-track-session={nnnn}
|
||||
data-amp-track-filename={f}
|
||||
>
|
||||
{transcriptOrdinal(f)}
|
||||
</Link>
|
||||
</li>
|
||||
)
|
||||
})}
|
||||
</ul>
|
||||
)}
|
||||
</li>
|
||||
)
|
||||
})}
|
||||
|
||||
@@ -1,14 +1,16 @@
|
||||
// DocsSessionIndex.jsx — v0.19.0 / roadmap item #30.
|
||||
// DocsSessionIndex.jsx — v0.20.0 (was v0.19.0 / roadmap item #30).
|
||||
//
|
||||
// Per-session index page at `/docs/sessions/:nnnn`. Lists every
|
||||
// transcript published under the session's NNNN/ folder, linked to
|
||||
// the per-transcript view.
|
||||
// Per-session landing at `/docs/sessions/:nnnn`. v0.19.0 listed the
|
||||
// transcripts as body links; v0.20.0 drops the body list — navigation
|
||||
// is via the left flyout nav (which renders each session's transcripts
|
||||
// nested under the session row). The body now serves as a
|
||||
// session-overview card with the title, file count, and a hint to
|
||||
// pick a transcript from the nav.
|
||||
//
|
||||
// The transcript list comes from `/api/docs/sessions/:nnnn/index`,
|
||||
// which the framework derives via the gitea contents API (see
|
||||
// backend/app/docs_sessions.fetch_session_index). We also read the
|
||||
// session's `title` from the manifest fetch so the page header
|
||||
// matches the flyout nav entry.
|
||||
// The transcript count still comes from `/api/docs/sessions/:nnnn/index`
|
||||
// so the empty-state ("no transcripts yet"), not-found, and error
|
||||
// paths remain meaningful — the page still does something useful when
|
||||
// the upstream is mid-publish or unreachable.
|
||||
|
||||
import { useEffect, useState, useCallback } from 'react'
|
||||
import { Link, useParams } from 'react-router-dom'
|
||||
@@ -105,21 +107,14 @@ export default function DocsSessionIndex() {
|
||||
</div>
|
||||
)}
|
||||
{status === 'ok' && files.length > 0 && (
|
||||
<ul className="docs-session-files">
|
||||
{files.map(f => (
|
||||
<li key={f}>
|
||||
<Link
|
||||
to={`/docs/sessions/${nnnn}/${f}`}
|
||||
aria-label={`Open transcript ${f}`}
|
||||
data-amp-track-name="Docs Session Transcript Open"
|
||||
data-amp-track-session={nnnn}
|
||||
data-amp-track-filename={f}
|
||||
>
|
||||
{f}
|
||||
</Link>
|
||||
</li>
|
||||
))}
|
||||
</ul>
|
||||
<div className="docs-session-overview">
|
||||
<p>
|
||||
{files.length === 1
|
||||
? '1 transcript in this session.'
|
||||
: `${files.length} transcripts in this session.`}{' '}
|
||||
Select one from the navigation on the left.
|
||||
</p>
|
||||
</div>
|
||||
)}
|
||||
</article>
|
||||
)
|
||||
|
||||
@@ -0,0 +1,134 @@
|
||||
// DocsSpec.jsx — v0.20.0.
|
||||
//
|
||||
// Per-spec view at `/docs/specs/:name`. Fetches a configured spec
|
||||
// body via the backend mediator (which proxies the gitea raw URL)
|
||||
// and renders it through the shared MarkdownPreview. The page header
|
||||
// pulls the spec's `title` from the manifest so the breadcrumb-free
|
||||
// page still names what you're looking at.
|
||||
//
|
||||
// Empty-state contract:
|
||||
// 404 → "This spec isn't published yet / unknown name" with a hint
|
||||
// to pick a configured spec from the nav.
|
||||
// 502 → "Couldn't reach the spec source" + retry button.
|
||||
//
|
||||
// History view is intentionally absent — the operator's framing for
|
||||
// v0.20.0 is "current version only; git is the history surface".
|
||||
// A small "View on gitea" link beside the title points at the
|
||||
// upstream source URL the manifest carries so the history gesture
|
||||
// remains one click away.
|
||||
|
||||
import { useEffect, useState, useCallback } from 'react'
|
||||
import { Link, useParams } from 'react-router-dom'
|
||||
import MarkdownPreview from './MarkdownPreview.jsx'
|
||||
import { getSpec, getSpecsManifest } from '../api.js'
|
||||
import { EVENTS, track } from '../lib/analytics'
|
||||
|
||||
export default function DocsSpec() {
|
||||
const { name } = useParams()
|
||||
const [title, setTitle] = useState('')
|
||||
const [sourceUrl, setSourceUrl] = useState('')
|
||||
const [body, setBody] = useState('')
|
||||
const [status, setStatus] = useState('loading') // loading | ok | notfound | error
|
||||
const [reloadTick, setReloadTick] = useState(0)
|
||||
|
||||
useEffect(() => {
|
||||
track(EVENTS.DOC_VIEWED, { section: `specs/${name}` })
|
||||
}, [name])
|
||||
|
||||
// Title + upstream URL from the manifest (cheap — the manifest is
|
||||
// derived from an env var on the backend, no network).
|
||||
useEffect(() => {
|
||||
let active = true
|
||||
getSpecsManifest()
|
||||
.then(payload => {
|
||||
if (!active) return
|
||||
const entry = (payload && payload.specs || []).find(s => s.name === name)
|
||||
setTitle((entry && entry.title) || '')
|
||||
setSourceUrl((entry && entry.url) || '')
|
||||
})
|
||||
.catch(() => {
|
||||
// Title + source link are decorative; the body fetch below
|
||||
// is the load-bearing one. A failed manifest fetch just
|
||||
// leaves the page rendering the bare name.
|
||||
})
|
||||
return () => { active = false }
|
||||
}, [name])
|
||||
|
||||
useEffect(() => {
|
||||
let active = true
|
||||
setStatus('loading')
|
||||
getSpec(name)
|
||||
.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 }
|
||||
}, [name, reloadTick])
|
||||
|
||||
const retry = useCallback(() => setReloadTick(t => t + 1), [])
|
||||
|
||||
const header = title || `Spec: ${name}`
|
||||
|
||||
return (
|
||||
<article className="docs-article">
|
||||
<header className="docs-article-header">
|
||||
<h1 className="docs-article-title">{header}</h1>
|
||||
{sourceUrl && (
|
||||
<a
|
||||
className="docs-source-link"
|
||||
href={sourceUrl}
|
||||
target="_blank"
|
||||
rel="noopener noreferrer"
|
||||
aria-label="View spec source on gitea"
|
||||
data-amp-track-name="Docs Spec Source Link"
|
||||
data-amp-track-spec={name}
|
||||
>
|
||||
View source
|
||||
</a>
|
||||
)}
|
||||
</header>
|
||||
{status === 'loading' && <p className="muted">Loading…</p>}
|
||||
{status === 'notfound' && (
|
||||
<div className="docs-empty">
|
||||
<p>This spec isn't available.</p>
|
||||
<p>
|
||||
<Link
|
||||
to="/docs/user-guide"
|
||||
aria-label="User guide"
|
||||
data-amp-track-name="Docs Spec Notfound User Guide Link"
|
||||
>
|
||||
← Back to the user guide
|
||||
</Link>
|
||||
</p>
|
||||
</div>
|
||||
)}
|
||||
{status === 'error' && (
|
||||
<div className="docs-error" role="alert">
|
||||
<p>Couldn't reach the spec source.</p>
|
||||
<button
|
||||
type="button"
|
||||
onClick={retry}
|
||||
aria-label="Retry"
|
||||
data-amp-track-name="Docs Spec Retry"
|
||||
>
|
||||
Try again
|
||||
</button>
|
||||
</div>
|
||||
)}
|
||||
{status === 'ok' && (
|
||||
<div className="philosophy-body">
|
||||
<MarkdownPreview content={body} />
|
||||
</div>
|
||||
)}
|
||||
</article>
|
||||
)
|
||||
}
|
||||
@@ -0,0 +1,82 @@
|
||||
// DocsSpecsIndex.jsx — v0.20.0.
|
||||
//
|
||||
// Landing route at `/docs/specs`. The operator-stated body shape for
|
||||
// the parallel `/docs/sessions/:nnnn` page is "no body list — pick a
|
||||
// transcript from the nav", and the same gesture applies here: the
|
||||
// `/docs/specs` route either redirects to the first configured spec
|
||||
// (the common case) or renders a "no specs configured" empty state
|
||||
// (only reachable if a deployment overrides `OHM_DOCS_SPECS` to an
|
||||
// empty list — the framework default has two entries).
|
||||
//
|
||||
// The redirect is client-side because the manifest is a single API
|
||||
// call away; server-side redirect would require either a backend
|
||||
// route for the bare `/docs/specs` path (out of scope for v0.20.0)
|
||||
// or a build-time bake of the first spec name (which couples the
|
||||
// frontend bundle to the deployment overlay, which we don't do).
|
||||
|
||||
import { useEffect, useState } from 'react'
|
||||
import { Navigate, Link } from 'react-router-dom'
|
||||
import { getSpecsManifest } from '../api.js'
|
||||
import { EVENTS, track } from '../lib/analytics'
|
||||
|
||||
export default function DocsSpecsIndex() {
|
||||
const [firstName, setFirstName] = useState(null)
|
||||
// Tri-state: 'loading' (waiting on manifest), 'redirect' (we have a
|
||||
// name to redirect to — render <Navigate>), 'empty' (no specs
|
||||
// configured), or 'error' (couldn't load the manifest at all).
|
||||
const [status, setStatus] = useState('loading')
|
||||
|
||||
useEffect(() => {
|
||||
track(EVENTS.DOC_VIEWED, { section: 'specs' })
|
||||
}, [])
|
||||
|
||||
useEffect(() => {
|
||||
let active = true
|
||||
getSpecsManifest()
|
||||
.then(payload => {
|
||||
if (!active) return
|
||||
const specs = (payload && payload.specs) || []
|
||||
if (specs.length === 0) {
|
||||
setStatus('empty')
|
||||
} else {
|
||||
setFirstName(specs[0].name)
|
||||
setStatus('redirect')
|
||||
}
|
||||
})
|
||||
.catch(() => {
|
||||
if (!active) return
|
||||
setStatus('error')
|
||||
})
|
||||
return () => { active = false }
|
||||
}, [])
|
||||
|
||||
if (status === 'redirect' && firstName) {
|
||||
return <Navigate to={firstName} replace />
|
||||
}
|
||||
|
||||
return (
|
||||
<article className="docs-article">
|
||||
<h1 className="docs-article-title">Specs</h1>
|
||||
{status === 'loading' && <p className="muted">Loading…</p>}
|
||||
{status === 'empty' && (
|
||||
<div className="docs-empty">
|
||||
<p>No specs are configured for this deployment.</p>
|
||||
<p>
|
||||
<Link
|
||||
to="/docs/user-guide"
|
||||
aria-label="User guide"
|
||||
data-amp-track-name="Docs Specs Empty User Guide Link"
|
||||
>
|
||||
← Back to the user guide
|
||||
</Link>
|
||||
</p>
|
||||
</div>
|
||||
)}
|
||||
{status === 'error' && (
|
||||
<div className="docs-error" role="alert">
|
||||
<p>Couldn't load the spec list.</p>
|
||||
</div>
|
||||
)}
|
||||
</article>
|
||||
)
|
||||
}
|
||||
Reference in New Issue
Block a user