Self-hosted homelab infrastructure visualizer — interactive network diagram with live status monitoring
TypeScript diagramhomelabhomelab-infrastructure-observabilitynetworkproxmox-veself-hostedzigbeezwavezwave-js
import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
import { Archive, BookOpen, ChevronDown, ChevronRight, FilePlus, FolderPlus, Link2, Search, X } from 'lucide-react'
import { toast } from 'sonner'
import { docsviewApi, scanApi } from '@/api/client'
import { Button } from '@/components/ui/button'
import { Input } from '@/components/ui/input'
import { useCanvasStore } from '@/stores/canvasStore'
import { useDesignStore } from '@/stores/designStore'
import type { InventoryEntry } from '@/types'
import { cn } from '@/lib/utils'
import { withBase } from '@/utils/basePath'
import { copyToClipboard } from '@/utils/clipboard'
import { formatRelative } from '@/utils/timeFormat'
import { downloadAllDocs, downloadDoc } from '../export'
import { isOverdue } from '../frontmatter'
import { driftedIds, useDocsStore } from '../store'
import {
buildDeviceTree,
buildLibraryTree,
canMoveInto,
deviceLabel,
filterGroups,
filterTree,
} from '../tree'
import { GROUP_BY_LABELS, type GroupBy, type TreeLeaf, type UpdatePreview } from '../types'
import { DocEditor } from './DocEditor'
import { DocTreeGroups, DocTreeItem, type TreeDnd } from './DocTree'
import { DocViewer } from './DocViewer'
import { MigrateNotesBanner } from './MigrateNotesBanner'
import { NewDocMenu } from './NewDocMenu'
import { RegenerateDocModal } from './RegenerateDocModal'
import { UpdateFromDeviceModal } from './UpdateFromDeviceModal'
const STANDALONE = import.meta.env.VITE_STANDALONE === 'true'
const GROUP_OPTIONS = Object.keys(GROUP_BY_LABELS) as GroupBy[]
function updateConfirmation(result: UpdatePreview): string {
const names = [...new Set(
result.changes
.filter((change) => change.status !== 'same')
.map((change) => change.name.trim())
.filter(Boolean),
)]
if (names.length === 0) return 'Documentation already matched the device — marked as up to date'
const shown = names.slice(0, 3).join(', ')
return `Documentation updated: ${shown}${names.length > 3 ? `, and ${names.length - 3} more` : ''}`
}
/**
* The Documentation section.
*
* The first part of the app that is not about one canvas: a device is
* documented once and reads the same wherever it is drawn, so this view sits
* beside the canvas rather than inside a design.
*/
export function DocumentationView() {
const {
docs,
loaded,
loadDocs,
openDoc,
open,
draft,
dirty,
saving,
pendingDraft,
startEdit,
setDraft,
cancelEdit,
save,
acceptPendingDraft,
discardPendingDraft,
create,
move,
remove,
toggleStar,
markReviewed,
setTags,
regenerate,
revisions,
revisionsLoading,
revisionPreview,
loadRevisions,
previewRevision,
closeRevisionPreview,
restore,
backlinks,
backlinksLoading,
coverage,
loadCoverage,
scaffold,
preview,
previewLoading,
resolutions,
openUpdatePreview,
setResolution,
clearResolutions,
applyUpdate,
groupBy,
setGroupBy,
expanded,
toggleExpanded,
setExpanded,
treeWidth,
setTreeWidth,
filter,
setFilter,
} = useDocsStore()
const designs = useDesignStore((s) => s.designs)
const activeDesignId = useDesignStore((s) => s.activeDesignId)
const nodes = useCanvasStore((s) => s.nodes)
const [devices, setDevices] = useState<InventoryEntry[]>([])
const [libraryOpen, setLibraryOpen] = useState(true)
const [regenerateOpen, setRegenerateOpen] = useState(false)
const [regenerating, setRegenerating] = useState(false)
const [historyOpen, setHistoryOpen] = useState(false)
const [updateOpen, setUpdateOpen] = useState(false)
const [exporting, setExporting] = useState(false)
const updateFlow = useRef(0)
useEffect(() => {
updateFlow.current++
setUpdateOpen(false)
}, [openDoc?.id])
useEffect(() => {
void loadDocs()
void loadCoverage()
if (STANDALONE) return
scanApi
.pending()
.then((res) => setDevices(res.data as InventoryEntry[]))
// The tree still renders the Library without the inventory.
.catch(() => setDevices([]))
}, [loadDocs, loadCoverage])
// `review_every` rides along on the summary, so the badge needs no bodies.
const overdue = useMemo(
() =>
new Set(
docs
.filter((doc) => isOverdue(doc.frontmatter ?? {}, doc.reviewed_at, doc.created_at))
.map((doc) => doc.id),
),
[docs],
)
const drifted = useMemo(() => driftedIds(docs), [docs])
const deviceGroups = useMemo(
() =>
filterGroups(
buildDeviceTree({
groupBy,
devices,
docs,
context: { nodes, designs, activeDesignId, ranges: [] },
drifted,
overdue,
}),
filter,
),
[activeDesignId, designs, devices, docs, drifted, filter, groupBy, nodes, overdue],
)
const libraryItems = useMemo(() => filterTree(buildLibraryTree(docs), filter), [docs, filter])
const starred = useMemo(() => new Set(docs.filter((d) => d.starred).map((d) => d.id)), [docs])
const linkableDevices = useMemo(
() => devices.map((d) => ({ id: d.id, label: deviceLabel(d) })),
[devices],
)
const handleSelect = useCallback(
async (leaf: TreeLeaf) => {
if (dirty && !window.confirm('Discard the unsaved changes to this document?')) return
if (leaf.docId) {
await open(leaf.docId)
return
}
if (!leaf.deviceId) return
const device = devices.find((d) => d.id === leaf.deviceId)
const doc = await create({
title: device ? deviceLabel(device) : leaf.label,
kind: 'device',
deviceId: leaf.deviceId,
})
if (doc) {
await open(doc.id)
toast.success('Document created from the device facts')
}
},
[create, devices, dirty, open],
)
// Filing by drag. The confirmation is the point — a document that moves
// because a pointer slipped is worse than one nobody filed.
const [draggingId, setDraggingId] = useState<string | null>(null)
const [overId, setOverId] = useState<string | null>(null)
const [rootOver, setRootOver] = useState(false)
const dragged = useMemo(
() => (draggingId ? (docs.find((d) => d.id === draggingId) ?? null) : null),
[docs, draggingId],
)
const allowDrop = useCallback(
(targetId: string | null) => (dragged ? canMoveInto(docs, dragged, targetId) : false),
[docs, dragged],
)
const handleDrop = useCallback(
async (targetId: string | null) => {
const doc = dragged
setDraggingId(null)
setOverId(null)
setRootOver(false)
if (!doc || !canMoveInto(docs, doc, targetId)) return
const target = targetId ? docs.find((d) => d.id === targetId) : null
if (targetId && !target) return
const question = target
? `Move \u201c${doc.title}\u201d into \u201c${target.title}\u201d?`
: `Move \u201c${doc.title}\u201d out to the top of the Library?`
if (!window.confirm(question)) return
try {
await move(doc.id, targetId)
// Land somewhere the user can see: a closed folder would swallow it.
if (targetId && !expanded.includes(targetId)) setExpanded([...expanded, targetId])
toast.success(target ? `Moved into \u201c${target.title}\u201d` : 'Moved to the top of the Library')
} catch {
toast.error('Could not move that document')
}
},
[docs, dragged, expanded, move, setExpanded],
)
const dnd: TreeDnd = useMemo(
() => ({
draggingId,
overId,
canDrop: allowDrop,
onDragStart: (leaf) => setDraggingId(leaf.docId ?? null),
onDragEnd: () => {
setDraggingId(null)
setOverId(null)
setRootOver(false)
},
onDragOver: setOverId,
onDrop: (targetId) => void handleDrop(targetId),
}),
[allowDrop, draggingId, handleDrop, overId],
)
const handleSave = useCallback(async () => {
if (await save()) toast.success('Saved')
}, [save])
const handleDelete = useCallback(async () => {
if (!openDoc) return
if (!window.confirm(`Delete “${openDoc.title}”? Its history goes with it.`)) return
await remove(openDoc.id)
toast.success('Document deleted')
}, [openDoc, remove])
// The whole space, zipped server-side: the tree only holds summaries, so the
// bodies to write are not in the browser yet.
const handleExportAll = useCallback(async () => {
setExporting(true)
try {
await downloadAllDocs()
toast.success('Documentation exported')
} catch {
toast.error('Could not export the documentation')
} finally {
setExporting(false)
}
}, [])
const handleRegenerate = useCallback(async () => {
if (!openDoc) return
setRegenerating(true)
const ok = await regenerate(openDoc.id)
setRegenerating(false)
if (!ok) {
toast.error('Could not regenerate that document')
return
}
setRegenerateOpen(false)
toast.success('Document regenerated — the old body is in its history')
}, [openDoc, regenerate])
const handleCancelUpdate = useCallback(() => {
updateFlow.current++
setUpdateOpen(false)
clearResolutions()
}, [clearResolutions])
const finishUpdate = useCallback(async (review: UpdatePreview, flow: number, docId: string) => {
const result = await applyUpdate()
const current = useDocsStore.getState()
if (
flow !== updateFlow.current ||
current.openDoc?.id !== docId ||
(current.preview !== null && current.preview.preview_id !== review.preview_id)
) return
if (result === 'failed') {
toast.error('Could not apply the update')
return
}
if (result === 'stale') {
// The document moved under the preview; show it again and re-compare,
// so the user is never applying against a body they have not seen.
setUpdateOpen(true)
await open(docId)
if (flow !== updateFlow.current || useDocsStore.getState().openDoc?.id !== docId) return
toast.error('That preview was out of date — review the current document again')
await openUpdatePreview()
return
}
setUpdateOpen(false)
clearResolutions()
toast.success(updateConfirmation(review), {
action: { label: 'View history', onClick: () => setHistoryOpen(true) },
})
}, [applyUpdate, clearResolutions, open, openUpdatePreview])
// The comparison only ever opens the review. Even an update with no conflict
// waits for the Update button: nothing is written to a document unseen.
const handleUpdatePreview = useCallback(async () => {
if (!openDoc) return
const flow = ++updateFlow.current
const docId = openDoc.id
setUpdateOpen(true)
const result = await openUpdatePreview()
if (flow !== updateFlow.current || useDocsStore.getState().openDoc?.id !== docId) return
if (result === null) toast.error('Could not compare this document with the device')
}, [openDoc, openUpdatePreview])
const handleApplyUpdate = useCallback(async () => {
if (!openDoc || !preview) return
const flow = ++updateFlow.current
await finishUpdate(preview, flow, openDoc.id)
}, [finishUpdate, openDoc, preview])
// Applying the merge on a doc with an edit in flight would silently destroy
// the draft text it replaced; the button is hidden while editing instead.
const showUpdate = openDoc !== null && draft === null
// The rail is loaded when it is opened, and again whenever the document it is
// showing changes underneath it — a save adds a revision to the list.
const openDocId = openDoc?.id
const openDocSavedAt = openDoc?.updated_at
useEffect(() => {
if (!historyOpen || !openDocId) return
void loadRevisions(openDocId)
}, [historyOpen, openDocId, openDocSavedAt, loadRevisions])
const handleToggleHistory = useCallback(() => {
setHistoryOpen((open) => {
// Closing the rail leaves the version being read; there would be no way
// back to the current body otherwise.
if (open) closeRevisionPreview()
return !open
})
}, [closeRevisionPreview])
const handleRestore = useCallback(
async (revisionId: string) => {
if (!openDoc) return
const revision = revisions.find((r) => r.id === revisionId)
const when = revision ? formatRelative(revision.saved_at) : 'that version'
if (!window.confirm(`Restore the version from ${when}? The current body is saved to the history first.`)) {
return
}
await restore(openDoc.id, revisionId)
toast.success('Version restored — the body it replaced is in the history')
},
[openDoc, restore, revisions],
)
const handleMigrate = useCallback(async () => {
const created = await scaffold({ onlyWithNotes: true })
await loadDocs()
toast.success(created === 1 ? '1 note became a document' : `${created} notes became documents`)
}, [loadDocs, scaffold])
// The read-only link to this documentation, when DOCS_VIEW_KEY is set. The
// key is admin-only — the app asks the server for it rather than being told
// at build time — and with the feature off there is simply no button.
const [docsLink, setDocsLink] = useState<string | null>(null)
useEffect(() => {
if (STANDALONE) return
docsviewApi
.getConfig()
.then(({ data }) =>
setDocsLink(
data.enabled && data.key
? `${window.location.origin}${withBase('docs')}?key=${encodeURIComponent(data.key)}`
: null,
),
)
.catch(() => setDocsLink(null))
}, [])
// Drag-to-resize the tree pane. Width lives in localStorage, per viewer.
const dragging = useRef(false)
useEffect(() => {
const move = (event: MouseEvent) => {
if (!dragging.current) return
setTreeWidth(Math.min(520, Math.max(180, event.clientX - 48)))
}
const up = () => {
dragging.current = false
}
window.addEventListener('mousemove', move)
window.addEventListener('mouseup', up)
return () => {
window.removeEventListener('mousemove', move)
window.removeEventListener('mouseup', up)
}
}, [setTreeWidth])
if (STANDALONE) {
return (
<div className="flex flex-1 items-center justify-center p-8 text-center">
<div className="max-w-md">
<BookOpen className="mx-auto mb-3 opacity-40" size={28} />
<h2 className="mb-1 text-sm font-semibold">Documentation needs the backend</h2>
<p className="text-xs text-muted-foreground">
Standalone mode keeps canvases in the browser and has nowhere to store documents or
search them. Run Homelable with its API to use this section.
</p>
</div>
</div>
)
}
return (
<div className="flex min-h-0 flex-1">
<aside
style={{ width: treeWidth }}
className="flex min-h-0 shrink-0 flex-col border-r border-border"
>
<div className="flex items-center gap-1 border-b border-border px-2 py-2">
<Search size={13} className="shrink-0 opacity-50" />
<Input
value={filter}
onChange={(event) => setFilter(event.target.value)}
placeholder="Filter documents"
aria-label="Filter documents"
className="h-6 border-0 bg-transparent px-1 text-xs shadow-none focus-visible:ring-0"
/>
{filter && (
<Button size="icon-xs" variant="ghost" aria-label="Clear filter" onClick={() => setFilter('')}>
<X />
</Button>
)}
</div>
<div className="flex items-center gap-1 border-b border-border px-2 py-1.5">
<label htmlFor="docs-group-by" className="text-[10px] uppercase tracking-wide text-muted-foreground/70">
Group by
</label>
<select
id="docs-group-by"
value={groupBy}
onChange={(event) => setGroupBy(event.target.value as GroupBy)}
className="ml-auto cursor-pointer rounded border border-border bg-transparent px-1 py-0.5 text-xs"
>
{GROUP_OPTIONS.map((option) => (
<option key={option} value={option}>
{GROUP_BY_LABELS[option]}
</option>
))}
</select>
</div>
<div className="min-h-0 flex-1 overflow-y-auto py-1">
<div className="flex items-center gap-0.5 px-2 pb-1 pt-1">
<button
type="button"
onClick={() => setLibraryOpen((value) => !value)}
aria-expanded={libraryOpen}
className="flex flex-1 cursor-pointer items-center gap-1 text-left text-[10px] font-semibold uppercase tracking-wide text-muted-foreground/50"
>
{libraryOpen ? <ChevronDown size={10} /> : <ChevronRight size={10} />}
Library
</button>
<NewDocMenu
placement="down"
onCreate={async (input) => {
const doc = await create(input)
if (doc) await open(doc.id)
}}
trigger={
<Button
size="icon-xs"
variant="ghost"
aria-label="New document"
title="New document"
data-tour="docs-new"
>
<FilePlus />
</Button>
}
/>
<Button
size="icon-xs"
variant="ghost"
aria-label="New folder"
title="New folder"
onClick={async () => {
const title = window.prompt('Folder name')
if (title?.trim()) await create({ title: title.trim(), kind: 'folder' })
}}
>
<FolderPlus />
</Button>
</div>
{/* Dropping on the empty space around the Library files a document at
its top level — the only way back out of a folder. */}
<div
onDragOver={(event) => {
if (!allowDrop(null)) return
event.preventDefault()
event.dataTransfer.dropEffect = 'move'
setRootOver(true)
}}
onDragLeave={() => setRootOver(false)}
onDrop={(event) => {
if (!allowDrop(null)) return
event.preventDefault()
void handleDrop(null)
}}
className={cn(
'min-h-6 rounded',
rootOver && 'bg-primary/10 ring-1 ring-inset ring-primary/40',
)}
>
{libraryOpen &&
libraryItems.map((leaf) => (
<DocTreeItem
key={leaf.id}
leaf={leaf}
depth={1}
activeId={openDoc?.id ?? null}
expanded={expanded}
starred={starred}
onSelect={(item) => void handleSelect(item)}
onToggle={toggleExpanded}
dnd={dnd}
/>
))}
{libraryOpen && libraryItems.length === 0 && (
<p className="px-3 py-1 text-xs text-muted-foreground/60">
Nothing here yet — runbooks and overviews live in the Library.
</p>
)}
</div>
<p
data-tour="docs-devices"
className="mt-3 px-2 pb-1 pt-1 text-[10px] font-semibold uppercase tracking-wide text-muted-foreground/50"
>
Devices
</p>
<DocTreeGroups
groups={deviceGroups}
activeId={openDoc?.id ?? null}
expanded={expanded}
starred={starred}
onSelect={(leaf) => void handleSelect(leaf)}
onToggle={toggleExpanded}
/>
</div>
<div className="flex items-center gap-1 border-t border-border px-2 py-1.5">
<Button
size="xs"
variant="ghost"
className="cursor-pointer gap-1 px-1.5"
title="Download every document as a zip of Markdown files"
disabled={exporting || docs.length === 0}
onClick={() => void handleExportAll()}
>
<Archive size={12} />
{exporting ? 'Exporting…' : 'Export all'}
</Button>
{docsLink && (
<Button
size="xs"
variant="ghost"
className="cursor-pointer gap-1 px-1.5"
title="Copy the read-only link — anyone holding it reads every document"
onClick={async () => {
if (await copyToClipboard(docsLink)) toast.success('Read-only link copied')
else toast.error('Could not copy the link')
}}
>
<Link2 size={12} />
Share link
</Button>
)}
{coverage && (
<span
className="ml-auto text-[10px] tabular-nums text-muted-foreground/70"
title={`${coverage.documented} of ${coverage.devices} devices documented · ${coverage.header_only} still only the generated header`}
>
{coverage.documented}/{coverage.devices}
</span>
)}
</div>
</aside>
<div
role="separator"
aria-orientation="vertical"
aria-label="Resize the document tree"
onMouseDown={() => {
dragging.current = true
}}
className="w-1 shrink-0 cursor-col-resize bg-transparent hover:bg-primary/30"
/>
<div className="flex min-h-0 min-w-0 flex-1 flex-col">
{coverage && coverage.notes_unmigrated > 0 && (
<MigrateNotesBanner count={coverage.notes_unmigrated} onMigrate={() => void handleMigrate()} />
)}
{pendingDraft !== null && (
<div className="flex items-center gap-2 border-b border-border bg-[var(--status-pending,#e3b341)]/10 px-4 py-1.5 text-xs">
<span className="text-[var(--status-pending,#e3b341)]">
Unsaved changes from a previous session were found.
</span>
<Button size="xs" variant="secondary" className="cursor-pointer" onClick={acceptPendingDraft}>
Restore them
</Button>
<Button size="xs" variant="ghost" className="cursor-pointer" onClick={discardPendingDraft}>
Discard
</Button>
</div>
)}
{!openDoc && (
<div className={cn('flex flex-1 items-center justify-center p-8 text-center')}>
<div className="max-w-sm">
<BookOpen className="mx-auto mb-3 opacity-30" size={26} />
<p className="text-sm font-medium">
{loaded && docs.length === 0 ? 'Nothing is documented yet' : 'Pick a document'}
</p>
<p className="mt-1 text-xs text-muted-foreground">
Selecting a device with no document creates one from its scanned facts, filled in
for you and yours to maintain from there.
</p>
</div>
</div>
)}
{openDoc && draft === null && (
<DocViewer
doc={openDoc}
docs={docs}
devices={linkableDevices}
drifted={openDoc.drifted ?? false}
backlinks={backlinks}
backlinksLoading={backlinksLoading}
history={{
open: historyOpen,
loading: revisionsLoading,
revisions,
preview: revisionPreview,
onToggle: handleToggleHistory,
onSelect: (id) => void previewRevision(id),
onClosePreview: closeRevisionPreview,
onRestore: (id) => void handleRestore(id),
}}
onEdit={startEdit}
onToggleStar={() => void toggleStar(openDoc.id)}
onMarkReviewed={() => void markReviewed(openDoc.id)}
onSetTags={(tags) => void setTags(tags)}
onUpdateFromDevice={() => void handleUpdatePreview()}
onRegenerate={() => setRegenerateOpen(true)}
onDownload={() => downloadDoc(openDoc)}
onDelete={() => void handleDelete()}
onOpenDoc={(id) => void open(id)}
onCreateFromLink={async (label) => {
const doc = await create({ title: label })
if (doc) await open(doc.id)
}}
onToggleTask={(body) => {
// A checkbox is an edit like any other: it goes through the draft
// so it is saved explicitly, never behind the user's back.
startEdit()
setDraft(body)
}}
/>
)}
{openDoc && draft !== null && (
<DocEditor
body={draft}
onChange={setDraft}
onSave={() => void handleSave()}
onCancel={cancelEdit}
dirty={dirty}
saving={saving}
deviceId={openDoc.device_id}
currentDocId={openDoc.id}
docs={docs}
devices={linkableDevices}
/>
)}
<RegenerateDocModal
open={regenerateOpen && openDoc !== null}
title={openDoc?.title ?? ''}
fromDevice={Boolean(openDoc?.device_id)}
busy={regenerating}
onCancel={() => setRegenerateOpen(false)}
onConfirm={() => void handleRegenerate()}
/>
<UpdateFromDeviceModal
open={showUpdate && updateOpen}
docTitle={openDoc?.title ?? ''}
preview={preview}
loading={previewLoading}
resolutions={resolutions}
onPreview={() => void handleUpdatePreview()}
onResolve={(id, item) => setResolution(id, item)}
onCancel={handleCancelUpdate}
onApply={() => void handleApplyUpdate()}
docs={docs}
devices={linkableDevices}
/>
</div>
</div>
)
}