Skip to content

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

feat(import): gather every import behind one "Import from…" picker

Pouzorc9e7c950f2f0
diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx
index d068a9f..7550766 100644
--- a/frontend/src/App.tsx
+++ b/frontend/src/App.tsx
@@ -29,6 +29,7 @@ import { ZigbeeImportModal } from '@/components/zigbee/ZigbeeImportModal'
import { ZwaveImportModal } from '@/components/zwave/ZwaveImportModal'
import { ProxmoxImportModal } from '@/components/proxmox/ProxmoxImportModal'
import { UnifiImportModal } from '@/components/unifi/UnifiImportModal'
+import { ImportSourceModal, type ImportSourceKey } from '@/components/modals/ImportSourceModal'
import { GroupRectModal, type GroupRectFormData } from '@/components/modals/GroupRectModal'
import { TextModal, type TextFormData } from '@/components/modals/TextModal'
import { ThemeModal } from '@/components/modals/ThemeModal'
@@ -160,6 +161,7 @@ export default function App() {
const [zwaveImportOpen, setZwaveImportOpen] = useState(false)
const [proxmoxImportOpen, setProxmoxImportOpen] = useState(false)
const [unifiImportOpen, setUnifiImportOpen] = useState(false)
+ const [importPickerOpen, setImportPickerOpen] = useState(false)
// Declare handleSave before the Ctrl+S effect so it is in scope.
// Returns true on success, false on failure — the design-switch effect relies
@@ -371,6 +373,16 @@ export default function App() {
void loadDesignsAndCanvasRef.current()
}, [])
+ /** The picker hands off to the source's own modal and gets out of the way —
+ * it is a menu, not a step the user has to come back through. */
+ const openImportSource = useCallback((source: ImportSourceKey) => {
+ setImportPickerOpen(false)
+ if (source === 'zigbee') setZigbeeImportOpen(true)
+ else if (source === 'zwave') setZwaveImportOpen(true)
+ else if (source === 'proxmox') setProxmoxImportOpen(true)
+ else setUnifiImportOpen(true)
+ }, [])
+
// Bridge the Getting Started tour steps to the App's modal controls. The overlay
// calls closeAll() before each step, then the step's action to open the target.
const walkthroughActions = useMemo<WalkthroughActionApi>(() => ({
@@ -383,6 +395,7 @@ export default function App() {
setEditNodeId(null)
setThemeModalOpen(false)
setZigbeeImportOpen(false)
+ setImportPickerOpen(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')
@@ -420,7 +433,7 @@ export default function App() {
}))
},
openStyle: () => setThemeModalOpen(true),
- openZigbeeImport: () => setZigbeeImportOpen(true),
+ openImportPicker: () => setImportPickerOpen(true),
openDocumentation: () => setAppView('documentation'),
}), [openInventoryModal, setAppView])
@@ -1141,10 +1154,7 @@ export default function App() {
onAddGroupRect={() => setAddGroupRectOpen(true)}
onAddText={() => setAddTextOpen(true)}
onScan={() => setScanConfigOpen(true)}
- onZigbeeImport={() => setZigbeeImportOpen(true)}
- onUnifiImport={() => setUnifiImportOpen(true)}
- onZwaveImport={() => setZwaveImportOpen(true)}
- onProxmoxImport={() => setProxmoxImportOpen(true)}
+ onOpenImports={() => setImportPickerOpen(true)}
onSave={handleSave}
onOpenSettings={() => setSettingsOpen(true)}
onOpenHistory={() => setScanHistoryOpen(true)}
@@ -1295,6 +1305,14 @@ export default function App() {
/>
)}
+ {!STANDALONE && (
+ <ImportSourceModal
+ open={importPickerOpen}
+ onClose={() => setImportPickerOpen(false)}
+ onPick={openImportSource}
+ />
+ )}
+
{!STANDALONE && (
<ZigbeeImportModal
open={zigbeeImportOpen}
diff --git a/frontend/src/components/modals/ImportSourceModal.tsx b/frontend/src/components/modals/ImportSourceModal.tsx
new file mode 100644
index 0000000..1bcd852
--- /dev/null
+++ b/frontend/src/components/modals/ImportSourceModal.tsx
@@ -0,0 +1,199 @@
+import { Network, RadioTower, Server, Wifi, ArrowRight, Clock } from 'lucide-react'
+import type { LucideIcon } from 'lucide-react'
+import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogDescription } from '@/components/ui/dialog'
+import { brandIconUrl } from '@/utils/nodeIcons'
+
+export type ImportSourceKey = 'zigbee' | 'zwave' | 'proxmox' | 'unifi'
+
+interface ImportSourceModalProps {
+ open: boolean
+ onClose: () => void
+ onPick: (source: ImportSourceKey) => void
+}
+
+interface ImportSource {
+ key: ImportSourceKey
+ /** Product name, not the canvas vocabulary — this is what the user runs. */
+ label: string
+ /** dashboard-icons slug; the lucide icon is the fallback when it fails to load. */
+ brandSlug: string
+ fallbackIcon: LucideIcon
+ accent: string
+ description: string
+ /** Rough wall-clock for a typical homelab — sets the expectation, not a promise. */
+ duration: string
+ /** What makes the range a range, when the spread is wide enough to explain. */
+ durationNote?: string
+ /** What lands in the inventory / on the canvas. */
+ imports: string[]
+ dataTour?: string
+}
+
+const SOURCES: ImportSource[] = [
+ {
+ key: 'zigbee',
+ label: 'Zigbee2MQTT',
+ brandSlug: 'zigbee2mqtt',
+ fallbackIcon: Network,
+ accent: '#00d4ff',
+ description: 'Reads the coordinator over MQTT and brings the whole mesh in, routers and end devices alike.',
+ duration: '30 s – a few min',
+ durationNote: 'with the mesh size',
+ imports: ['Devices', 'Mesh links'],
+ dataTour: 'import-zigbee',
+ },
+ {
+ key: 'zwave',
+ label: 'Z-Wave JS',
+ brandSlug: 'z-wave-js-ui',
+ fallbackIcon: RadioTower,
+ accent: '#ff6e00',
+ description: 'Pulls the Z-Wave JS UI node list with each node’s neighbours, so the mesh keeps its shape.',
+ duration: '30 s – a few min',
+ durationNote: 'with the mesh size',
+ imports: ['Nodes', 'Neighbours'],
+ },
+ {
+ key: 'proxmox',
+ label: 'Proxmox VE',
+ brandSlug: 'proxmox',
+ fallbackIcon: Server,
+ accent: '#e57000',
+ description: 'Queries the API for every node of the cluster and the guests running on them.',
+ duration: '~10 s',
+ imports: ['Hosts', 'VMs', 'LXC'],
+ },
+ {
+ key: 'unifi',
+ label: 'UniFi',
+ brandSlug: 'unifi',
+ fallbackIcon: Wifi,
+ accent: '#0559c9',
+ description: 'Talks to the controller for adopted gear, and optionally for the clients it sees.',
+ duration: '~20 s',
+ imports: ['Gateways', 'Switches', 'APs', 'Clients'],
+ },
+]
+
+/**
+ * The one entry point for every import. The sources are picked here rather than
+ * listed in the sidebar: the list only grows, and a stack of near-identical
+ * links reads worse the longer it gets.
+ */
+export function ImportSourceModal({ open, onClose, onPick }: ImportSourceModalProps) {
+ return (
+ <Dialog open={open} onOpenChange={(v) => !v && onClose()}>
+ {/* The dialog primitive pins `sm:max-w-sm`, and a variant utility outranks
+ every plain `max-w-*` class — only an inline width actually widens it,
+ and four tiles need the room. */}
+ <DialogContent
+ className="bg-[#161b22] border-border max-h-[85vh] flex flex-col"
+ style={{ maxWidth: 'min(1120px, calc(100vw - 3rem))' }}
+ >
+ <DialogHeader>
+ <DialogTitle className="text-foreground">Import from…</DialogTitle>
+ <DialogDescription>
+ Pick a source to pull devices from. Everything lands in the Device Inventory first — nothing
+ touches the canvas until you approve it.
+ </DialogDescription>
+ </DialogHeader>
+
+ <div className="flex-1 overflow-y-auto min-h-0 py-2">
+ <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-3">
+ {SOURCES.map((source) => (
+ <ImportSourceTile key={source.key} source={source} onPick={() => onPick(source.key)} />
+ ))}
+ </div>
+ </div>
+ </DialogContent>
+ </Dialog>
+ )
+}
+
+function ImportSourceTile({ source, onPick }: { source: ImportSource; onPick: () => void }) {
+ const Fallback = source.fallbackIcon
+
+ return (
+ <button
+ type="button"
+ onClick={onPick}
+ data-tour={source.dataTour}
+ aria-label={`Import from ${source.label}`}
+ className="group relative flex flex-col gap-3 rounded-lg border border-border bg-[#21262d] p-4 text-left transition-colors cursor-pointer hover:bg-[#2a313a] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[#00d4ff]"
+ >
+ {/* The accent only shows on hover/focus — four saturated brand colors side
+ by side fight each other at rest. */}
+ <span
+ aria-hidden
+ className="absolute inset-x-0 top-0 h-0.5 rounded-t-lg opacity-0 transition-opacity group-hover:opacity-100 group-focus-visible:opacity-100"
+ style={{ backgroundColor: source.accent }}
+ />
+
+ <div className="flex items-center justify-between">
+ <span
+ className="flex h-11 w-11 items-center justify-center rounded-md"
+ style={{ backgroundColor: `${source.accent}1a` }}
+ >
+ <BrandGlyph slug={source.brandSlug} accent={source.accent} fallback={Fallback} />
+ </span>
+ <ArrowRight
+ size={16}
+ className="text-muted-foreground opacity-0 transition-opacity group-hover:opacity-100 group-focus-visible:opacity-100"
+ />
+ </div>
+
+ <div className="space-y-1">
+ <div className="text-sm font-medium text-foreground">{source.label}</div>
+ <p className="text-xs leading-relaxed text-muted-foreground">{source.description}</p>
+ </div>
+
+ <div className="mt-auto space-y-2 pt-1">
+ <div className="flex flex-wrap gap-1">
+ {source.imports.map((item) => (
+ <span
+ key={item}
+ className="rounded border border-border bg-[#161b22] px-1.5 py-0.5 font-mono text-[10px] text-muted-foreground"
+ >
+ {item}
+ </span>
+ ))}
+ </div>
+ <div className="flex items-start gap-1 text-[11px] text-muted-foreground">
+ <Clock size={11} className="mt-0.5 shrink-0" />
+ <span>
+ {source.duration}
+ {source.durationNote && <span className="text-muted-foreground/70"> · {source.durationNote}</span>}
+ </span>
+ </div>
+ </div>
+ </button>
+ )
+}
+
+/**
+ * The brand logos come from the dashboard-icons CDN, which is offline in
+ * standalone-ish setups and blocked on some networks — swap in the lucide icon
+ * rather than leaving a broken image in the tile.
+ */
+function BrandGlyph({ slug, accent, fallback: Fallback }: { slug: string; accent: string; fallback: LucideIcon }) {
+ return (
+ <>
+ <img
+ src={brandIconUrl(slug)}
+ alt=""
+ width={24}
+ height={24}
+ loading="lazy"
+ style={{ width: 24, height: 24, objectFit: 'contain' }}
+ onError={(e) => {
+ const img = e.currentTarget
+ img.style.display = 'none'
+ img.nextElementSibling?.removeAttribute('hidden')
+ }}
+ />
+ <span hidden>
+ <Fallback size={22} style={{ color: accent }} />
+ </span>
+ </>
+ )
+}
diff --git a/frontend/src/components/modals/__tests__/ImportSourceModal.test.tsx b/frontend/src/components/modals/__tests__/ImportSourceModal.test.tsx
new file mode 100644
index 0000000..7dc964c
--- /dev/null
+++ b/frontend/src/components/modals/__tests__/ImportSourceModal.test.tsx
@@ -0,0 +1,70 @@
+import { describe, it, expect, vi, afterEach } from 'vitest'
+import { render, screen, fireEvent, cleanup } from '@testing-library/react'
+import { ImportSourceModal, type ImportSourceKey } from '../ImportSourceModal'
+
+afterEach(() => cleanup())
+
+function setup(overrides: Partial<{ open: boolean; onClose: () => void; onPick: (s: ImportSourceKey) => void }> = {}) {
+ const props = {
+ open: true,
+ onClose: vi.fn(),
+ onPick: vi.fn(),
+ ...overrides,
+ }
+ render(<ImportSourceModal {...props} />)
+ return props
+}
+
+describe('ImportSourceModal', () => {
+ it('renders nothing when closed', () => {
+ setup({ open: false })
+ expect(screen.queryByText('Import from…')).not.toBeInTheDocument()
+ })
+
+ it('lists every import source', () => {
+ setup()
+ for (const label of ['Zigbee2MQTT', 'Z-Wave JS', 'Proxmox VE', 'UniFi']) {
+ expect(screen.getByText(label)).toBeInTheDocument()
+ }
+ })
+
+ it('shows the expected duration and the data each source brings in', () => {
+ setup()
+ // The tile promises a rough wall-clock and the record kinds — that is what
+ // makes the picker a choice rather than four unlabelled doors.
+ expect(screen.getByText('~10 s')).toBeInTheDocument()
+ // A mesh walk is not a fixed cost, so the tile says what the range tracks.
+ expect(screen.getAllByText('30 s – a few min')).toHaveLength(2)
+ expect(screen.getAllByText('· with the mesh size')).toHaveLength(2)
+ expect(screen.getByText('Mesh links')).toBeInTheDocument()
+ expect(screen.getByText('LXC')).toBeInTheDocument()
+ expect(screen.getByText('APs')).toBeInTheDocument()
+ })
+
+ it.each([
+ ['Zigbee2MQTT', 'zigbee'],
+ ['Z-Wave JS', 'zwave'],
+ ['Proxmox VE', 'proxmox'],
+ ['UniFi', 'unifi'],
+ ])('reports %s as the picked source', (label, key) => {
+ const { onPick } = setup()
+ fireEvent.click(screen.getByLabelText(`Import from ${label}`))
+ expect(onPick).toHaveBeenCalledExactlyOnceWith(key)
+ })
+
+ it('carries the walkthrough anchor on the Zigbee tile', () => {
+ setup()
+ // The tour steps into the picker and then spotlights Zigbee inside it.
+ expect(document.querySelector('[data-tour="import-zigbee"]')).toBeInTheDocument()
+ })
+
+ it('falls back to a lucide glyph when the brand logo fails to load', () => {
+ setup()
+ const tile = screen.getByLabelText('Import from UniFi')
+ const img = tile.querySelector('img')!
+ expect(img.nextElementSibling).toHaveAttribute('hidden')
+ fireEvent.error(img)
+ expect(img.style.display).toBe('none')
+ expect(img.nextElementSibling).not.toHaveAttribute('hidden')
+ })
+})
diff --git a/frontend/src/components/panels/Sidebar.tsx b/frontend/src/components/panels/Sidebar.tsx
index b397584..89df4a2 100644
--- a/frontend/src/components/panels/Sidebar.tsx
+++ b/frontend/src/components/panels/Sidebar.tsx
@@ -1,5 +1,5 @@
import { useState, useCallback, useEffect } from 'react'
-import { Plus, Save, ScanLine, ChevronLeft, ChevronRight, LayoutDashboard, Clock, Square, Settings, LogOut, Network, RadioTower, Server, Wifi, Type, PlusCircle, Pencil, Trash2, Rows3, BookOpen, Loader2 } from 'lucide-react'
+import { Plus, Save, ScanLine, ChevronLeft, ChevronRight, LayoutDashboard, Clock, Square, Settings, LogOut, Download, Type, PlusCircle, Pencil, Trash2, Rows3, BookOpen, Loader2 } from 'lucide-react'
import { Logo } from '@/components/ui/Logo'
import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
import { useCanvasStore } from '@/stores/canvasStore'
@@ -25,17 +25,14 @@ interface SidebarProps {
onAddGroupRect: () => void
onAddText: () => void
onScan: () => void
- onZigbeeImport: () => void
- onZwaveImport: () => void
- onProxmoxImport: () => void
- onUnifiImport: () => void
+ onOpenImports: () => void
onSave: () => void
onOpenSettings: () => void
onOpenHistory: () => void
onOpenInventory: (deviceId?: string, status?: 'pending' | 'hidden') => void
}
-export function Sidebar({ onAddNode, onAddGroupRect, onAddText, onScan, onZigbeeImport, onZwaveImport, onProxmoxImport, onUnifiImport, onSave, onOpenSettings, onOpenHistory, onOpenInventory }: SidebarProps) {
+export function Sidebar({ onAddNode, onAddGroupRect, onAddText, onScan, onOpenImports, onSave, onOpenSettings, onOpenHistory, onOpenInventory }: SidebarProps) {
const [collapsed, setCollapsed] = useState(false)
const logout = useAuthStore((s) => s.logout)
const { designs, activeDesignId, activeDesignType, setActiveDesign, addDesign, updateDesign, removeDesign } = useDesignStore()
@@ -314,10 +311,9 @@ export function Sidebar({ onAddNode, onAddGroupRect, onAddText, onScan, onZigbee
</>
)}
{!STANDALONE && !isRack && <SidebarItem icon={ScanLine} label="Scan Network" collapsed={collapsed} onClick={handleScan} dataTour="scan-network" />}
- {!STANDALONE && !isRack && <SidebarItem icon={Network} label="Zigbee Import" collapsed={collapsed} onClick={onZigbeeImport} dataTour="zigbee-import" />}
- {!STANDALONE && !isRack && <SidebarItem icon={RadioTower} label="Z-Wave Import" collapsed={collapsed} onClick={onZwaveImport} dataTour="zwave-import" />}
- {!STANDALONE && !isRack && <SidebarItem icon={Server} label="Proxmox Import" collapsed={collapsed} onClick={onProxmoxImport} dataTour="proxmox-import" />}
- {!STANDALONE && !isRack && <SidebarItem icon={Wifi} label="UniFi Import" collapsed={collapsed} onClick={onUnifiImport} dataTour="unifi-import" />}
+ {/* One entry for every import source — the list grows with each new
+ integration and four near-identical links crowded the rail. */}
+ {!STANDALONE && !isRack && <SidebarItem icon={Download} label="Import from…" collapsed={collapsed} onClick={onOpenImports} dataTour="imports" />}
<SidebarItem
icon={Save}
label={isRack ? 'Save Rack' : 'Save Canvas'}
diff --git a/frontend/src/components/panels/__tests__/Sidebar.test.tsx b/frontend/src/components/panels/__tests__/Sidebar.test.tsx
index 2fd96e5..6eb1f23 100644
--- a/frontend/src/components/panels/__tests__/Sidebar.test.tsx
+++ b/frontend/src/components/panels/__tests__/Sidebar.test.tsx
@@ -74,8 +74,7 @@ const defaultProps = {
onAddGroupRect: vi.fn(),
onAddText: vi.fn(),
onScan: vi.fn(),
- onZigbeeImport: vi.fn(),
- onZwaveImport: vi.fn(),
+ onOpenImports: vi.fn(),
onSave: vi.fn(),
onOpenSettings: vi.fn(),
onOpenHistory: vi.fn(),
@@ -203,10 +202,10 @@ describe('Sidebar', () => {
expect(defaultProps.onAddGroupRect).toHaveBeenCalledOnce()
})
- it('calls onZwaveImport when Z-Wave Import is clicked', () => {
+ it('calls onOpenImports when Import from… is clicked', () => {
render(<Sidebar {...defaultProps} />)
- fireEvent.click(screen.getByText('Z-Wave Import'))
- expect(defaultProps.onZwaveImport).toHaveBeenCalledOnce()
+ fireEvent.click(screen.getByText('Import from…'))
+ expect(defaultProps.onOpenImports).toHaveBeenCalledOnce()
})
it('calls onSave when Save Canvas is clicked', () => {
@@ -327,6 +326,12 @@ describe('Sidebar', () => {
expect(docs?.anchor).toBe('[data-tour="documentation"]')
expect(document.querySelector(docs!.anchor!)).toBeInTheDocument()
+ // The imports step now points at the single picker entry, not at one of the
+ // per-source links it replaced.
+ const imports = STEPS.find((s) => s.id === 'imports')
+ expect(imports?.anchor).toBe('[data-tour="imports"]')
+ expect(document.querySelector(imports!.anchor!)).toBeInTheDocument()
+
// Unmount before restoring, so the store reset never re-renders the sidebar.
unmount()
useDesignStore.setState({
@@ -376,9 +381,7 @@ describe('Sidebar (rack canvas)', () => {
render(<Sidebar {...defaultProps} />)
// Nothing here is scanned onto a rack — those actions belong to a diagram.
expect(screen.queryByText('Scan Network')).not.toBeInTheDocument()
- expect(screen.queryByText('Zigbee Import')).not.toBeInTheDocument()
- expect(screen.queryByText('Z-Wave Import')).not.toBeInTheDocument()
- expect(screen.queryByText('Proxmox Import')).not.toBeInTheDocument()
+ expect(screen.queryByText('Import from…')).not.toBeInTheDocument()
// The Device Inventory stays: a rack mounts what the scans found.
expect(screen.getByText('Device Inventory')).toBeInTheDocument()
})
diff --git a/frontend/src/walkthrough/actions.ts b/frontend/src/walkthrough/actions.ts
index be522ed..5b93344 100644
--- a/frontend/src/walkthrough/actions.ts
+++ b/frontend/src/walkthrough/actions.ts
@@ -18,7 +18,7 @@ export interface WalkthroughActionApi {
editFirstNode: () => void
selectTwoNodes: () => void
openStyle: () => void
- openZigbeeImport: () => void
+ openImportPicker: () => void
/** Swaps the whole main pane for the Documentation section (`closeAll` swaps it back). */
openDocumentation: () => void
}
diff --git a/frontend/src/walkthrough/steps.ts b/frontend/src/walkthrough/steps.ts
index 16ca140..48ccb91 100644
--- a/frontend/src/walkthrough/steps.ts
+++ b/frontend/src/walkthrough/steps.ts
@@ -134,16 +134,16 @@ export const STEPS: TourStep[] = [
{
id: 'imports',
title: 'Import from your stack',
- body: 'Already running Zigbee2MQTT, Z-Wave JS, or Proxmox? Import devices directly from them instead of scanning. One click brings the whole topology in.',
- anchor: '[data-tour="zigbee-import"]',
+ body: 'Already running Zigbee2MQTT, Z-Wave JS, Proxmox or UniFi? Import devices straight from them instead of scanning — pick a source and the whole topology comes in.',
+ anchor: '[data-tour="imports"]',
placement: 'right',
- action: 'openZigbeeImport',
+ action: 'openImportPicker',
mode: 'full',
},
{
id: 'end',
title: "You're all set",
- body: "That's the tour! Build your map, save it, and share a read-only view. In full mode you also get network scanning, a device inventory, and Zigbee / Z-Wave / Proxmox import. Have a question or an idea?",
+ body: "That's the tour! Build your map, save it, and share a read-only view. In full mode you also get network scanning, a device inventory, and Zigbee / Z-Wave / Proxmox / UniFi import. Have a question or an idea?",
placement: 'center',
mode: 'all',
link: { label: 'Ask on GitHub', href: 'https://github.com/Pouzor/homelable/issues' },