@unbrained/pm-web 2026.8.10 → 2026.8.14

package/public/src/views/graph.js

@@ -50,6 +50,7 @@ function removeCtxMenu() {
         ctxMenuEl = null;
     }
 }
+/** Builds and shows the right-click context menu for a graph node, with actions to open the item, select and focus, show its neighborhood, expand two hops, and copy its id. */
 function showCtxMenu(nodeId, x, y) {
     removeCtxMenu();
     const graph = currentGraph?.graph || {};
@@ -121,6 +122,7 @@ function showCtxMenu(nodeId, x, y) {
 function nodeTitle(node) {
     return String(node.properties?.title || node.id);
 }
+/** Returns a display type for a node, preferring the `kind` property, then `type`, then a non-core label, defaulting to 'Item'. */
 function nodeType(node) {
     return String(node.properties?.kind
         || node.properties?.type
@@ -143,6 +145,7 @@ function nodeLane(node) {
         return 'external';
     return 'item';
 }
+/** Extracts a short user-facing error message from a raw error string (JSON detail, title, or code, otherwise the trimmed raw text), returning an empty string when the error is just the missing pm-graph extension. */
 function compactError(raw) {
     if (!raw)
         return '';
@@ -157,6 +160,7 @@ function compactError(raw) {
     }
 }
 // ── Graph data processing ─────────────────────────────────────
+/** Returns the set of ids directly connected to the given node (plus the node itself) across the provided relationships. */
 function directNeighborIds(nodeId, rels) {
     const ids = new Set([nodeId]);
     for (const r of rels) {
@@ -167,6 +171,7 @@ function directNeighborIds(nodeId, rels) {
     }
     return ids;
 }
+/** Returns the neighbor id(s) on the other end of a relationship relative to a node, filtered by traversal direction (incoming, outgoing, or connected). */
 function walkDirectionMatch(rel, nodeId, dir) {
     if (dir === 'incoming') {
         return rel.to === nodeId ? [rel.from] : [];
@@ -176,6 +181,7 @@ function walkDirectionMatch(rel, nodeId, dir) {
     }
     return rel.to === nodeId ? [rel.from] : rel.from === nodeId ? [rel.to] : [];
 }
+/** Performs a bounded breadth-first traversal out to `depth` hops from a node, returning all reachable ids (including the node itself) while respecting the traversal direction. */
 function expandedNeighborIds(nodeId, rels, depth, direction) {
     const ids = new Set([nodeId]);
     let frontier = new Set([nodeId]);
@@ -198,6 +204,7 @@ function expandedNeighborIds(nodeId, rels, depth, direction) {
     }
     return ids;
 }
+/** Counts both endpoints of every relationship, returning a map of node id to its total edge degree (incrementing the count for both `from` and `to`). */
 function degreeMap(rels) {
     const m = new Map();
     for (const r of rels) {
@@ -216,6 +223,7 @@ function blockingPair(rel) {
         return { blocked: rel.from, blocker: rel.to };
     return null;
 }
+/** Maps a relationship type to a human-readable dependency label (for example 'Depends on'), falling back to the lowercased type with underscores replaced by spaces. */
 function dependencyLabel(rel) {
     const labels = {
         DEPENDS_ON: 'Depends on',
@@ -230,6 +238,7 @@ function dependencyLabel(rel) {
     };
     return labels[rel.type] ?? rel.type.replace(/_/g, ' ').toLowerCase();
 }
+/** Computes the critical (longest) dependency path through the given relationships and returns its node ids as a set, or an empty set when there is no multi-step chain. */
 function computeCriticalPath(rels) {
     const depRels = rels.filter(isDependencyRel);
     if (!depRels.length)
@@ -247,6 +256,7 @@ function computeCriticalPath(rels) {
         allIds.add(pair.blocker);
     }
     const memo = new Map();
+    /** Memoized depth-first search returning the longest chain of blockers starting from the given id, guarding against cycles with a visited set. */
     function longestPathFrom(id, seen = new Set()) {
         if (memo.has(id))
             return memo.get(id);
@@ -271,6 +281,7 @@ function computeCriticalPath(rels) {
         .sort((a, b) => b.length - a.length)[0] ?? [];
     return longest.length < 2 ? new Set() : new Set(longest);
 }
+/** Builds per-node dependency stats from blocking relationships, mapping each node id to the sets of items that block it and that it blocks. */
 function blockerStats(rels) {
     const stats = new Map();
     const entry = (id) => {
@@ -287,6 +298,7 @@ function blockerStats(rels) {
     }
     return stats;
 }
+/** Applies the current filters (dep mode, focus neighborhood, node kind, status, text query, relationship type, and direction) to a graph, returning the surviving nodes, relationships, and the set of all connected node ids. */
 function visibleGraph(graph) {
     const nodes = graph.nodes || [];
     let rels = graph.relationships || [];
@@ -341,6 +353,7 @@ function visibleGraph(graph) {
     return { nodes: visNodes, rels: visRels, connected };
 }
 // ── Canvas data conversion ────────────────────────────────────
+/** Converts graph nodes into canvas display nodes, attaching each node's edge degree (computed from the relationships) so the renderer can size them. */
 function toCanvasNodes(nodes, rels) {
     const deg = degreeMap(rels);
     return nodes.map((n) => ({
@@ -361,6 +374,7 @@ function toCanvasEdges(rels) {
     return rels.map((r) => ({ from: r.from, to: r.to, type: r.type }));
 }
 // ── Info panel rendering ──────────────────────────────────────
+/** Renders the graph-coverage HTML: a linked-item percentage bar, the external cross-project reference count, and the top relationship type with its edge count. */
 function renderCoverage(itemNodes, rels, connected, relCounts) {
     const linked = itemNodes.filter((n) => connected.has(n.id)).length;
     const linkedPct = itemNodes.length > 0 ? Math.round((linked / itemNodes.length) * 100) : 0;
@@ -390,6 +404,7 @@ function renderCoverage(itemNodes, rels, connected, relCounts) {
       </div>
     </div>`;
 }
+/** Renders the selected-node HTML panel, including metadata, action buttons, blocker counts, the property grid, tags, an optional description, and its direct relationships. */
 function renderSelectedNode(node, rels, byId, fullItem) {
     if (!node)
         return '<div class="graph-node-empty">Click any node in the graph to inspect it.</div>';
@@ -454,6 +469,7 @@ function renderSelectedNode(node, rels, byId, fullItem) {
         }).join('') + (direct.length > 16 ? `<div class="graph-limit-note">+${direct.length - 16} more — use Focus scope to narrow</div>` : '')}
     </div>`;
 }
+/** Renders the neighborhood HTML for the selected node, showing clickable one-hop and two-hop neighbor chips. */
 function renderPaths(node, rels, byId) {
     if (!node)
         return '<div class="graph-node-empty">Select a node to explore paths.</div>';
@@ -471,6 +487,7 @@ function renderPaths(node, rels, byId) {
     <div class="graph-path-section"><div class="graph-path-label">One hop (${oneHop.size})</div><div class="graph-path-chips">${chips(oneHop) || '<span>None.</span>'}</div></div>
     <div class="graph-path-section"><div class="graph-path-label">Two hops (${twoHop.size})</div><div class="graph-path-chips">${chips(twoHop) || '<span>None.</span>'}</div></div>`;
 }
+/** Renders the item-hubs HTML, listing the top eight most-connected items by degree with their outgoing and incoming edge counts. */
 function renderHubs(nodes, rels) {
     const deg = degreeMap(rels);
     const hubs = nodes.filter(isItemNode)
@@ -487,6 +504,7 @@ function renderHubs(nodes, rels) {
       <small>${e.out}↑ ${e.inn}↓</small>
     </button>`).join('');
 }
+/** Renders the dependency-blocker HTML, listing the top eight items that block or are blocked by the most other items and flagging those on the critical path. */
 function renderBlockingInsights(nodes, rels) {
     const byId = new Map(nodes.map((n) => [n.id, n]));
     const stats = blockerStats(rels);
@@ -504,6 +522,7 @@ function renderBlockingInsights(nodes, rels) {
       <small>${row.blockers.size} blockers · ${row.blocked.size} items blocked${criticalPath.has(row.id) ? ' · critical path' : ''}</small>
     </button>`).join('');
 }
+/** Renders the dependency-chains HTML: the longest dependency chains, potential cycle warnings, and root blockers, with critical-path highlighting. */
 function renderDependencyChains(nodes, rels) {
     const byId = new Map(nodes.map((n) => [n.id, n]));
     const depRels = rels.filter(isDependencyRel);
@@ -525,6 +544,7 @@ function renderDependencyChains(nodes, rels) {
         .map(([id, blocked]) => ({ id, blocked: blocked.length }))
         .sort((a, b) => b.blocked - a.blocked || nodeTitle(byId.get(a.id) || { id: a.id }).localeCompare(nodeTitle(byId.get(b.id) || { id: b.id })))
         .slice(0, 4);
+    /** Depth-first trace of a dependency chain from the given id, recording detected cycle starts and returning the longest chain of blockers found. */
     function traceFrom(id, seen = new Set()) {
         if (seen.has(id)) {
             cycleStarts.add(id);
@@ -570,6 +590,7 @@ function renderDependencyChains(nodes, rels) {
       ${leafRows}
     </div>`;
 }
+/** Renders the full graph-analysis info panel HTML by composing the coverage, selected node, neighborhood, hubs, blockers, dependency-chain, and node/relationship count sections. */
 function renderInfoPanel(data, fullItem) {
     const graph = data.graph || {};
     const nodes = graph.nodes || [];
@@ -607,6 +628,7 @@ function renderInfoPanel(data, fullItem) {
     </div>`;
 }
 // ── Rel list (inside bottom drawer) ──────────────────────────
+/** Renders the relationship list shown in the bottom drawer: add/remove dependency buttons and up to 100 filtered relationship rows, each linking its two endpoints. */
 function renderRelList(data) {
     const graph = data.graph || {};
     const nodes = graph.nodes || [];
@@ -640,6 +662,7 @@ function renderRelList(data) {
     return editBtns + rows + limitNote;
 }
 // ── Immersive shell ───────────────────────────────────────────
+/** Returns whether the given preset id (knowledge, dependency, unlinked, metadata, critical, or tags) matches the current filter configuration. */
 function graphPresetActive(id) {
     if (id === 'knowledge') {
         return !filter.depMode && (filter.kind === 'items' || filter.kind === 'all') && filter.rel === 'all' && filter.scope === 'all' && filter.colorMode === 'status';
@@ -656,6 +679,7 @@ function graphPresetActive(id) {
         return !filter.depMode && filter.colorMode === 'tag';
     return false;
 }
+/** Renders the preset rail toolbar HTML, with one button per view preset (Knowledge, Dependencies, Unlinked, Tags, Metadata, Critical) showing live counts and active state. */
 function renderGraphPresets(depRels, isolatedCount) {
     const allNodes = currentGraph?.graph?.nodes ?? [];
     const tagSet = new Set();
@@ -681,6 +705,7 @@ function renderGraphPresets(depRels, isolatedCount) {
         </button>`).join('')}
     </div>`;
 }
+/** Renders the full immersive graph shell HTML: the canvas host, the top HUD bar with search and presets, physics controls, filter overlay, legend, info drawer, and relationship drawer. */
 function renderGraphShell(data) {
     const graph = data.graph || {};
     const nodes = graph.nodes || [];
@@ -878,6 +903,7 @@ function renderGraphShell(data) {
     </div>`;
 }
 // ── Canvas init / update ──────────────────────────────────────
+/** Fetches the full item record for the selected item-lane node and re-renders the info panel with its description; clears the cached item for non-item nodes or on failure. */
 async function fetchAndUpdateSelectedItem(nodeId) {
     if (!state.currentProject || !nodeId)
         return;
@@ -903,6 +929,7 @@ async function fetchAndUpdateSelectedItem(nodeId) {
         selectedItemCache = null;
     }
 }
+/** Pushes the current filters and selection onto the canvas and, when searching with no node selected, jumps the camera to the first matching node. */
 function syncCanvas() {
     if (!canvasRef.current || !currentGraph)
         return;
@@ -926,6 +953,7 @@ function syncCanvas() {
             canvasRef.current.jumpToNode(match.id);
     }
 }
+/** Creates the GraphCanvas instance for the current graph, wires its selection, open, and context-menu callbacks, computes the critical path, loads the data, and applies the initial filter. */
 function initCanvas() {
     const host = document.getElementById('graph-canvas-host');
     if (!host || !currentGraph)
@@ -965,6 +993,7 @@ function initCanvas() {
     syncCanvas();
 }
 // ── Panel / drawer updates ────────────────────────────────────
+/** Re-renders the info panel and relationship list into the DOM from the current graph (and cached selected item) and re-binds their event handlers. */
 function updateInfoPanel() {
     if (!currentGraph)
         return;
@@ -976,6 +1005,7 @@ function updateInfoPanel() {
         relList.innerHTML = renderRelList(currentGraph);
     bindInfoPanelEvents();
 }
+/** Synchronizes the filter toolbar DOM (direction select enabled state, depth slider and label, scope button text, and preset active states) with the current selection and filter. */
 function updateFilterToolbarState() {
     const dirSel = document.getElementById('graph-filter-direction');
     const depthSldr = document.getElementById('graph-filter-depth');
@@ -1001,6 +1031,7 @@ const TYPE_COLORS_MAP = {
     milestone: '#fbbf24', story: '#34d399', chore: '#94a3b8', release: '#38bdf8',
 };
 const TAG_PALETTE_JS = ['#2dd4bf', '#60a5fa', '#a78bfa', '#f87171', '#fbbf24', '#34d399', '#fb923c', '#e879f9'];
+/** Computes a tag-to-color map by ranking tags by how often they appear across the nodes and assigning each of the most frequent ones a palette color. */
 function computeTagColorMap(nodes) {
     const freq = new Map();
     for (const n of nodes) {
@@ -1011,6 +1042,7 @@ function computeTagColorMap(nodes) {
     const top = [...freq.entries()].sort((a, b) => b[1] - a[1]).slice(0, TAG_PALETTE_JS.length).map(([t]) => t);
     return new Map(top.map((t, i) => [t, TAG_PALETTE_JS[i]]));
 }
+/** Rebuilds the legend HUD HTML to match the current color mode (status, type, or tag) or dependency mode, including clickable tag chips when coloring by tag. */
 function updateLegend() {
     const legend = document.getElementById('graph-legend-hud');
     if (!legend)
@@ -1086,6 +1118,7 @@ function updateLegend() {
     }
 }
 // ── Event bindings ────────────────────────────────────────────
+/** Binds click handlers for the info-panel controls (open and clear the selected item, add and remove dependency) and for neighbor, tag, and relationship rows so they update the selection and canvas. */
 function bindInfoPanelEvents() {
     document.getElementById('graph-open-selected')?.addEventListener('click', () => {
         if (selectedNodeId)
@@ -1138,6 +1171,7 @@ function bindInfoPanelEvents() {
         });
     });
 }
+/** Binds all HUD control handlers for the graph view: back/refresh/sync/fit buttons, presets, physics toggles and sliders, filter selects, search input, drawer toggles, color mode, and global keyboard shortcuts. */
 function bindHudEvents() {
     // Back button
     document.getElementById('graph-back-btn')?.addEventListener('click', () => {
@@ -1482,6 +1516,7 @@ function bindHudEvents() {
     window.__graphKeyHandler = graphKeyHandler;
 }
 // ── URL routing (pushState) ─────────────────────────────────
+/** Serializes the current selection and filter into URL query parameters and replaces the browser history entry so the view can be restored or shared. */
 function pushGraphState() {
     if (!state.currentProject)
         return;
@@ -1505,6 +1540,7 @@ function pushGraphState() {
     history.replaceState(null, '', url);
 }
 let urlStateRestored = false;
+/** Reads graph view parameters from the current URL query string and applies them to the selection and filter, marking state as restored. */
 function restoreGraphState() {
     const params = new URLSearchParams(window.location.search);
     if (!params.has('graph'))
@@ -1524,6 +1560,7 @@ function restoreGraphState() {
         filter = { ...filter, layout: (params.get('layout') || 'force') };
 }
 // ── Dependency editing modals ────────────────────────────────
+/** Shows the add-dependency modal listing item nodes as source and target selects plus a relationship type, and POSTs the new dependency then refreshes the graph on submit. */
 function showAddDependencyModal() {
     if (!state.currentProject || !currentGraph)
         return;
@@ -1598,6 +1635,7 @@ function showAddDependencyModal() {
         }
     });
 }
+/** Shows the remove-dependency modal listing existing dependency relationships and DELETEs the chosen one on submit, then refreshes the graph. */
 function showRemoveDependencyModal() {
     if (!state.currentProject || !currentGraph)
         return;
@@ -1663,6 +1701,7 @@ function showRemoveDependencyModal() {
     });
 }
 // ── Main entry point ──────────────────────────────────────────
+/** Renders the full graph view into the `content-graph` element: clears any prior canvas, restores URL state, fetches the project graph, computes the critical path, renders the shell, binds events, and initializes the canvas. */
 export async function renderGraphView() {
     const el = document.getElementById('content-graph');
     if (!el)
@@ -1735,6 +1774,7 @@ export async function refreshGraphData() {
 // ── Local graph (embedded mini-graph for item detail) ─────────
 // Registry of active local graph canvases so they can be cleaned up
 const localGraphRegistry = new Map();
+/** Destroys and unregisters the local mini-graph canvas previously created for the given container id, if any. */
 export function destroyLocalGraph(containerId) {
     const existing = localGraphRegistry.get(containerId);
     if (existing) {
@@ -1742,6 +1782,7 @@ export function destroyLocalGraph(containerId) {
         localGraphRegistry.delete(containerId);
     }
 }
+/** Renders an embedded mini-graph for a single item showing its neighborhood out to the given depth, with neighbor-node clicks navigating to that item's detail view. */
 export async function renderLocalGraph(containerId, nodeId, depth = 2) {
     const container = document.getElementById(containerId);
     if (!container || !state.currentProject)