Self-hosted homelab infrastructure visualizer — interactive network diagram with live status monitoring
TypeScript diagramhomelabhomelab-infrastructure-observabilitynetworkproxmox-veself-hostedzigbeezwavezwave-js
feat(walkthrough): walk the tour through the Documentation section
Pouzoracac515d18e5
diff --git a/frontend/src/App.tsx b/frontend/src/App.tsxindex 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.tsxindex 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, onZigbeecollapsed={collapsed}active={view === 'documentation'}onClick={() => setView('documentation')}+ dataTour="documentation"/>)}{/* The hidden devices are a filter of this same modal, reached fromdiff --git a/frontend/src/components/panels/__tests__/Sidebar.test.tsx b/frontend/src/components/panels/__tests__/Sidebar.test.tsxindex 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.tsxnew file mode 100644index 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.tsxindex 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><DocTreeGroupsdiff --git a/frontend/src/walkthrough/__tests__/steps.test.ts b/frontend/src/walkthrough/__tests__/steps.test.tsindex 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.tsindex d110302..be522ed 100644--- a/frontend/src/walkthrough/actions.ts+++ b/frontend/src/walkthrough/actions.ts@@ -19,6 +19,8 @@ export interface WalkthroughActionApi {selectTwoNodes: () => voidopenStyle: () => voidopenZigbeeImport: () => 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.tsindex 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',