refactor(wiki-graph): components architecture

Author: AdrianRomanski

GEMINI.md

@@ -20,6 +20,11 @@ This is an Angular/NX monorepo used for library research, prototyping, and build
 - Kebab-case for all file and folder names
 - Follow NX project conventions for imports and project boundaries
 
+### Component Architecture
+- **UI Components**: Must ONLY have `input()` and `output()`. Never inject data services or manage external state directly.
+- **Container Components**: Responsible for wrapping UI components, composing layouts, rendering component structures and lists.
+- **Smart Components**: Responsible for knowing where data comes from (injecting state/data services like `GraphStateService`) and binding reactive state to containers and UI components.
+
 ### Research Workflows
 
 This workspace has two research workflows, each managed by the `research-buddy` skill:

apps/wiki-graph/src/app/README.md

@@ -0,0 +1,33 @@
+# Wiki Graph App
+
+The `apps/wiki-graph/src/app` directory contains the main application architecture for the Wiki Connections Visualizer. It provides interactive visualization, search, filtering, and topological analysis of interlinked wiki markdown documents.
+
+## Directory Structure
+
+```text
+apps/wiki-graph/src/app/
+├── components/           # Component architecture (UI, Containers, Smart)
+│   ├── ui/               # Pure presentation UI components (Inputs & Outputs ONLY)
+│   ├── containers/       # Layout composition & wrapper container components
+│   └── smart/            # State-aware smart components (Service injectors)
+├── d3/                   # D3 force simulation & SVG rendering engine
+├── models/               # Graph domain models & manifest types
+├── services/             # Parser service & reactive Signal state management
+├── app.config.ts         # Application configuration & providers
+├── app.routes.ts         # Route definitions
+└── README.md             # Top-level application documentation
+```
+
+## Component Architecture
+
+1. **UI Components (`components/ui/`)**:
+   - Pure presentational components receiving data strictly via `input()` signals and communicating user interactions strictly via `output()` events. No data/state services are injected.
+   - Includes `GraphCanvasComponent`, `GraphToolbarUiComponent`, `NodeDetailUiComponent`.
+
+2. **Container Components (`components/containers/`)**:
+   - Structural composition components that assemble layout grids/containers, wrap UI components, and handle template rendering.
+   - Includes `GraphViewportContainerComponent`.
+
+3. **Smart Components (`components/smart/`)**:
+   - State-aware orchestrators that inject data/state services (`GraphStateService`), query signals, and bind state inputs/action outputs.
+   - Includes `WikiGraphPageComponent` (`smart/wiki-graph-smart/`).

apps/wiki-graph/src/app/app.html

@@ -1 +1,2 @@
-<router-outlet />
+<router-outlet>
+</router-outlet>

apps/wiki-graph/src/app/app.routes.ts

@@ -4,7 +4,7 @@ export const appRoutes: Route[] = [
   {
     path: 'wiki-graph',
     loadComponent: () =>
-      import('./wiki-graph-page.component').then(
+      import('./components/smart/wiki-graph-smart/wiki-graph-smart.component').then(
         (m) => m.WikiGraphPageComponent
       ),
   },

apps/wiki-graph/src/app/components/README.md

@@ -0,0 +1,30 @@
+# Component Architecture (UI / Containers / Smart)
+
+This directory implements a strict three-tier component architecture for clarity, testability, and separation of concerns.
+
+## Architectural Layers
+
+### 1. UI Components (`components/ui/`)
+**Rule**: UI components can ONLY have `input()` signals and `output()` events. They must NEVER inject state/data services directly.
+
+- **`GraphCanvasComponent` (`ui/graph-canvas/`)**:
+  - Inputs: `graphData`, `visibleNodeIds`, `selectedNodeId`
+  - Output: `nodeSelected`
+- **`GraphToolbarUiComponent` (`ui/graph-toolbar-ui/`)**:
+  - Inputs: `nodeTypes`, `activeTypeFilters`, `searchQuery`, `activeTagFilter`, `allTags`, `visibleNodeCount`, `visibleEdgeCount`, `orphanCount`, `hubNodes`, `toolbarVisible`
+  - Outputs: `typeToggled`, `searchChanged`, `tagChanged`, `orphanHighlighted`, `hubSelected`, `refreshRequested`, `toolbarVisibilityToggled`
+- **`NodeDetailUiComponent` (`ui/node-detail-ui/`)**:
+  - Input: `node`
+  - Output: `closed`
+
+### 2. Container Components (`components/containers/`)
+**Rule**: Container components are responsible for wrapping UI components, composing layouts, and organizing lists/containers.
+
+- **`GraphViewportContainerComponent` (`containers/graph-viewport-container/`)**:
+  - Composes the interactive graph canvas, control toolbar UI, detail panel overlay, loading state, and error banner into a responsive viewport container.
+
+### 3. Smart Components (`components/smart/`)
+**Rule**: Smart components know where data comes from. They inject state/data services (`GraphStateService`), bind reactive state to container/UI inputs, and map action outputs to service actions.
+
+- **`WikiGraphPageComponent` (`smart/wiki-graph-smart/`)**:
+  - Main page route orchestrator injecting `GraphStateService`.

apps/wiki-graph/src/app/components/containers/graph-viewport-container/graph-viewport-container.component.html

@@ -0,0 +1,47 @@
+<div class="wiki-graph-page">
+
+  <app-graph-canvas
+    [graphData]="graphData()"
+    [visibleNodeIds]="visibleNodeIds()"
+    [selectedNodeId]="selectedNode()?.id ?? null"
+    (nodeSelected)="nodeSelected.emit($event)"
+  />
+
+  <app-graph-toolbar-ui
+    [nodeTypes]="nodeTypes()"
+    [activeTypeFilters]="activeTypeFilters()"
+    [searchQuery]="searchQuery()"
+    [activeTagFilter]="activeTagFilter()"
+    [allTags]="allTags()"
+    [visibleNodeCount]="visibleNodeCount()"
+    [visibleEdgeCount]="visibleEdgeCount()"
+    [orphanCount]="orphanCount()"
+    [hubNodes]="hubNodes()"
+    [toolbarVisible]="toolbarVisible()"
+    (typeToggled)="typeToggled.emit($event)"
+    (searchChanged)="searchChanged.emit($event)"
+    (tagChanged)="tagChanged.emit($event)"
+    (orphanHighlighted)="orphanHighlighted.emit()"
+    (hubSelected)="hubSelected.emit($event)"
+    (refreshRequested)="refreshRequested.emit()"
+    (toolbarVisibilityToggled)="toolbarVisibilityToggled.emit($event)"
+  />
+
+  <app-node-detail-ui
+    [node]="selectedNode()"
+    (closed)="detailClosed.emit()"
+  />
+
+  @if (isLoading()) {
+    <div class="loading-overlay" role="status" aria-live="polite">
+      <span class="spinner" aria-hidden="true"></span>Loading graph…
+    </div>
+  }
+
+  @if (error()) {
+    <div class="error-banner" role="alert">
+      <strong>Error:</strong> {{ error() }}
+    </div>
+  }
+
+</div>

apps/wiki-graph/src/app/components/containers/graph-viewport-container/graph-viewport-container.component.scss

@@ -0,0 +1,55 @@
+:host { display: block; width: 100vw; height: 100vh; }
+
+.wiki-graph-page {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  background: #181825;
+  color: #cdd6f4;
+  overflow: hidden;
+}
+
+app-graph-canvas {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+}
+
+.loading-overlay {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.75rem;
+  background: rgba(24, 24, 37, 0.8);
+  z-index: 20;
+  font-size: 1rem;
+  color: #a6adc8;
+}
+
+.spinner {
+  width: 20px; height: 20px;
+  border: 2px solid #585b70;
+  border-top-color: #89b4fa;
+  border-radius: 50%;
+  animation: spin 0.8s linear infinite;
+}
+
+@keyframes spin { to { transform: rotate(360deg); } }
+
+.error-banner {
+  position: absolute;
+  top: 4rem; left: 50%;
+  transform: translateX(-50%);
+  background: #3b1219;
+  border: 1px solid #f38ba8;
+  border-radius: 6px;
+  padding: 0.6rem 1.2rem;
+  color: #f38ba8;
+  font-size: 0.875rem;
+  z-index: 20;
+  max-width: 480px;
+  text-align: center;
+}

apps/wiki-graph/src/app/components/containers/graph-viewport-container/graph-viewport-container.component.ts

@@ -0,0 +1,40 @@
+import { ChangeDetectionStrategy, Component, input, output } from '@angular/core';
+import { GraphCanvasComponent } from '../../ui/graph-canvas/graph-canvas.component';
+import { GraphToolbarUiComponent } from '../../ui/graph-toolbar-ui/graph-toolbar-ui.component';
+import { NodeDetailUiComponent } from '../../ui/node-detail-ui/node-detail-ui.component';
+import type { GraphData, GraphNode, NodeType } from '../../../models/graph.models';
+
+@Component({
+  selector: 'app-graph-viewport-container',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [GraphCanvasComponent, GraphToolbarUiComponent, NodeDetailUiComponent],
+  templateUrl: './graph-viewport-container.component.html',
+  styleUrl: './graph-viewport-container.component.scss',
+})
+export class GraphViewportContainerComponent {
+  graphData = input<GraphData | null>(null);
+  visibleNodeIds = input<Set<string>>(new Set());
+  selectedNode = input<GraphNode | null>(null);
+  nodeTypes = input<NodeType[]>(['entity', 'concept', 'source']);
+  activeTypeFilters = input<Set<NodeType>>(new Set());
+  searchQuery = input<string>('');
+  activeTagFilter = input<string | null>(null);
+  allTags = input<string[]>([]);
+  visibleNodeCount = input<number>(0);
+  visibleEdgeCount = input<number>(0);
+  orphanCount = input<number>(0);
+  hubNodes = input<GraphNode[]>([]);
+  toolbarVisible = input<boolean>(true);
+  isLoading = input<boolean>(false);
+  error = input<string | null>(null);
+
+  nodeSelected = output<string | null>();
+  typeToggled = output<NodeType>();
+  searchChanged = output<string>();
+  tagChanged = output<string | null>();
+  orphanHighlighted = output<void>();
+  hubSelected = output<string>();
+  refreshRequested = output<void>();
+  toolbarVisibilityToggled = output<boolean>();
+  detailClosed = output<void>();
+}