Skip to content

Self-hosted homelab infrastructure visualizer — interactive network diagram with live status monitoring

feat(walkthrough): walk the tour through the Documentation section

Pouzoracac515d18e5
diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx
index 60eff30..e36a10f 100644
--- a/frontend/src/App.tsx
+++ b/frontend/src/App.tsx
@@ -383,6 +383,9 @@ export default function App() {
setEditNodeId(null)
setThemeModalOpen(false)
setZigbeeImportOpen(false)
+ // The Documentation steps replace the whole main pane; every other step
+ // anchors on the toolbar or the canvas, so put the view back first.
+ setAppView('canvas')
// Clear any tour-driven multi-selection so the DetailPanel closes.
useCanvasStore.setState((s) => ({
nodes: s.nodes.map((n) => (n.selected ? { ...n, selected: false } : n)),
@@ -418,7 +421,8 @@ export default function App() {
},
openStyle: () => setThemeModalOpen(true),
openZigbeeImport: () => setZigbeeImportOpen(true),
- }), [openInventoryModal])
+ openDocumentation: () => setAppView('documentation'),
+ }), [openInventoryModal, setAppView])
// Load designs + canvas on auth (or immediately in standalone mode, which has
// no auth gate).
diff --git a/frontend/src/components/panels/Sidebar.tsx b/frontend/src/components/panels/Sidebar.tsx
index 871821c..712ef9a 100644
--- a/frontend/src/components/panels/Sidebar.tsx
+++ b/frontend/src/components/panels/Sidebar.tsx
@@ -251,6 +251,7 @@ export function Sidebar({ onAddNode, onAddGroupRect, onAddText, onScan, onZigbee
collapsed={collapsed}
active={view === 'documentation'}
onClick={() => setView('documentation')}
+ dataTour="documentation"
/>
)}
{/* The hidden devices are a filter of this same modal, reached from
diff --git a/frontend/src/components/panels/__tests__/Sidebar.test.tsx b/frontend/src/components/panels/__tests__/Sidebar.test.tsx
index ae1fb67..1902e61 100644
--- a/frontend/src/components/panels/__tests__/Sidebar.test.tsx
+++ b/frontend/src/components/panels/__tests__/Sidebar.test.tsx
@@ -306,6 +306,12 @@ describe('Sidebar', () => {
// stops carrying leaves the step spotlighting nothing.
expect(document.querySelector(step!.anchor!)).toBeInTheDocument()
+ // The Documentation entry is the first Documentation step's target, and the
+ // only way the tour has into the section.
+ const docs = STEPS.find((s) => s.id === 'docs')
+ expect(docs?.anchor).toBe('[data-tour="documentation"]')
+ expect(document.querySelector(docs!.anchor!)).toBeInTheDocument()
+
// Unmount before restoring, so the store reset never re-renders the sidebar.
unmount()
useDesignStore.setState({
diff --git a/frontend/src/documentation/__tests__/TourAnchors.test.tsx b/frontend/src/documentation/__tests__/TourAnchors.test.tsx
new file mode 100644
index 0000000..3899e62
--- /dev/null
+++ b/frontend/src/documentation/__tests__/TourAnchors.test.tsx
@@ -0,0 +1,41 @@
+/**
+ * The Documentation tour steps ring elements of this view by selector. Nothing
+ * else reads those attributes, so only a test keeps a rename from quietly
+ * leaving two steps spotlighting an empty screen.
+ */
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest'
+import { cleanup, render, screen, waitFor } from '@testing-library/react'
+
+import { STEPS } from '@/walkthrough/steps'
+import { DocumentationView } from '../components/DocumentationView'
+import { useDocsStore } from '../store'
+
+vi.mock('sonner', async () => (await import('@/test/mocks')).mockSonner())
+
+vi.mock('@/api/client', () => ({
+ documentsApi: {
+ list: vi.fn().mockResolvedValue({ data: [] }),
+ coverage: vi.fn().mockResolvedValue({
+ data: { devices: 0, documented: 0, header_only: 0, notes_unmigrated: 0 },
+ }),
+ },
+ scanApi: { pending: vi.fn().mockResolvedValue({ data: [] }) },
+}))
+
+beforeEach(() => {
+ useDocsStore.setState({ docs: [], loaded: false, openDoc: null, filter: '' })
+})
+afterEach(() => cleanup())
+
+describe('Documentation tour anchors', () => {
+ it('carries the anchors the docs-write and docs-devices steps spotlight', async () => {
+ render(<DocumentationView />)
+ await waitFor(() => expect(screen.getByLabelText('New document')).toBeInTheDocument())
+
+ for (const id of ['docs-write', 'docs-devices']) {
+ const step = STEPS.find((s) => s.id === id)
+ expect(step?.anchor).toBeDefined()
+ expect(document.querySelector(step!.anchor!)).toBeInTheDocument()
+ }
+ })
+})
diff --git a/frontend/src/documentation/components/DocumentationView.tsx b/frontend/src/documentation/components/DocumentationView.tsx
index 0c25384..8fdfde7 100644
--- a/frontend/src/documentation/components/DocumentationView.tsx
+++ b/frontend/src/documentation/components/DocumentationView.tsx
@@ -376,7 +376,13 @@ export function DocumentationView() {
if (doc) await open(doc.id)
}}
trigger={
- <Button size="icon-xs" variant="ghost" aria-label="New document" title="New document">
+ <Button
+ size="icon-xs"
+ variant="ghost"
+ aria-label="New document"
+ title="New document"
+ data-tour="docs-new"
+ >
<FilePlus />
</Button>
}
@@ -436,7 +442,10 @@ export function DocumentationView() {
)}
</div>
- <p className="mt-3 px-2 pb-1 pt-1 text-[10px] font-semibold uppercase tracking-wide text-muted-foreground/50">
+ <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
diff --git a/frontend/src/walkthrough/__tests__/steps.test.ts b/frontend/src/walkthrough/__tests__/steps.test.ts
index 7ad7c4b..ee0248f 100644
--- a/frontend/src/walkthrough/__tests__/steps.test.ts
+++ b/frontend/src/walkthrough/__tests__/steps.test.ts
@@ -17,6 +17,31 @@ describe('getSteps', () => {
expect(ids).not.toContain('scan-history')
expect(ids).not.toContain('inventory')
expect(ids).not.toContain('imports')
+ // Documentation has nowhere to store a document without the backend.
+ expect(ids).not.toContain('docs')
+ expect(ids).not.toContain('docs-write')
+ expect(ids).not.toContain('docs-devices')
+ })
+
+ it('walks the Documentation section on anchors the view carries', () => {
+ const docs = STEPS.filter((s) => s.id.startsWith('docs'))
+ expect(docs.map((s) => s.id)).toEqual(['docs', 'docs-write', 'docs-devices'])
+ expect(docs.map((s) => s.anchor)).toEqual([
+ '[data-tour="documentation"]',
+ '[data-tour="docs-new"]',
+ '[data-tour="docs-devices"]',
+ ])
+ // Every one of them needs the section open: `closeAll` puts the view back
+ // to the canvas before each step, so the action cannot be dropped from the
+ // second and third.
+ expect(docs.every((s) => s.action === 'openDocumentation')).toBe(true)
+ expect(docs.every((s) => s.mode === 'full')).toBe(true)
+ })
+
+ it('documents the homelab once it has been mapped, before the styling step', () => {
+ const ids = STEPS.map((s) => s.id)
+ expect(ids.indexOf('docs')).toBeGreaterThan(ids.indexOf('rack'))
+ expect(ids.indexOf('docs-devices')).toBeLessThan(ids.indexOf('style'))
})
it('keeps the rack step in both modes — a rack canvas needs no backend', () => {
diff --git a/frontend/src/walkthrough/actions.ts b/frontend/src/walkthrough/actions.ts
index d110302..be522ed 100644
--- a/frontend/src/walkthrough/actions.ts
+++ b/frontend/src/walkthrough/actions.ts
@@ -19,6 +19,8 @@ export interface WalkthroughActionApi {
selectTwoNodes: () => void
openStyle: () => void
openZigbeeImport: () => void
+ /** Swaps the whole main pane for the Documentation section (`closeAll` swaps it back). */
+ openDocumentation: () => void
}
const WalkthroughActionsContext = createContext<WalkthroughActionApi | null>(null)
diff --git a/frontend/src/walkthrough/steps.ts b/frontend/src/walkthrough/steps.ts
index 2e99b1c..16ca140 100644
--- a/frontend/src/walkthrough/steps.ts
+++ b/frontend/src/walkthrough/steps.ts
@@ -95,6 +95,33 @@ export const STEPS: TourStep[] = [
placement: 'right',
mode: 'all',
},
+ {
+ id: 'docs',
+ title: 'Document your homelab',
+ body: 'Documentation sits beside the canvas, not inside a design: every device gets its own page, and the Library holds the runbooks, overviews and decisions that span several of them. A device is documented once and reads the same wherever it is drawn.',
+ anchor: '[data-tour="documentation"]',
+ placement: 'right',
+ action: 'openDocumentation',
+ mode: 'full',
+ },
+ {
+ id: 'docs-write',
+ title: 'Start from a template',
+ body: 'New document opens a template picker — Runbook, Incident, Decision (ADR), Network overview and more, each with its sections already laid out. Write in Markdown, type [[ to link another document, and every page lists what links back to it. Earlier versions stay one click away.',
+ anchor: '[data-tour="docs-new"]',
+ placement: 'right',
+ action: 'openDocumentation',
+ mode: 'full',
+ },
+ {
+ id: 'docs-devices',
+ title: 'A page per device',
+ body: 'Under Devices, every inventory entry has a page whose header is generated from the database — regenerate it after a change (the old body is kept in the history). Pivot the tree by zone, type, subnet, rack or tag, and reach a page straight from a node or an inventory row.',
+ anchor: '[data-tour="docs-devices"]',
+ placement: 'right',
+ action: 'openDocumentation',
+ mode: 'full',
+ },
{
id: 'style',
title: 'Make it yours',