ClassyGitShadowzzh

KnowledgeGraph.tsx

KnowledgeGraph.tsx
// src/components/islands/KnowledgeGraph.tsx
// S5 — Interactive knowledge graph showing M01-M12 module dependencies.
// Reads static data from module-graph.ts; hydrates lazily via client:visible.
import { useState, useEffect, useRef, type CSSProperties } from 'react';
import { moduleNodes, moduleEdges, type ModuleNode } from '../../data/module-graph';

const NODE_R = 28;
const W = 1000;
const H = 600;

/** Edge lookup: which edges touch a given module id. */
function edgesTouching(moduleId: string) {
  return moduleEdges.filter((e) => e.from === moduleId || e.to === moduleId);
}

/** Returns true if the edge is related to the hovered node. */
function isEdgeHighlighted(edge: { from: string; to: string }, moduleId: string | null) {
  if (!moduleId) return false;
  return edge.from === moduleId || edge.to === moduleId;
}

/** Returns true if a node is a neighbour of the given module id (via edges). */
function isNodeNeighbour(nodeModule: string, moduleId: string | null) {
  if (!moduleId) return false;
  return moduleEdges.some(
    (e) =>
      (e.from === moduleId && e.to === nodeModule) ||
      (e.to === moduleId && e.from === nodeModule),
  );
}

export default function KnowledgeGraph() {
  const [hovered, setHovered] = useState<ModuleNode | null>(null);
  const [focused, setFocused] = useState<ModuleNode | null>(null);
  const [readModules, setReadModules] = useState<Set<string>>(new Set());
  const [reducedMotion, setReducedMotion] = useState(false);
  const nodeRefs = useRef<Map<string, SVGGElement>>(new Map());

  // Load "read" status from localStorage
  useEffect(() => {
    try {
      const stored = JSON.parse(localStorage.getItem('pi-agent-book:read') || '[]');
      setReadModules(new Set(stored));
    } catch {
      /* localStorage unavailable */
    }
  }, []);

  // Respect prefers-reduced-motion
  useEffect(() => {
    const mq = window.matchMedia('(prefers-reduced-motion: reduce)');
    setReducedMotion(mq.matches);
    const handler = (e: MediaQueryListEvent) => setReducedMotion(e.matches);
    mq.addEventListener('change', handler);
    return () => mq.removeEventListener('change', handler);
  }, []);

  // The "active" node is either focused (keyboard) or hovered (mouse).
  const active = focused ?? hovered;

  const statusFill = (n: ModuleNode): string => {
    if (active && (active.module === n.module || isNodeNeighbour(n.module, active.module))) {
      return 'var(--accent-soft)';
    }
    if (readModules.has(n.slug)) return 'var(--accent)';
    if (n.status === 'published') return 'var(--paper-raised)';
    if (n.status === 'draft') return 'var(--paper-sunken)';
    return 'var(--paper-sunken)';
  };

  const statusStroke = (n: ModuleNode): string => {
    if (active?.module === n.module) return 'var(--accent)';
    if (readModules.has(n.slug)) return 'var(--accent)';
    if (n.status === 'published') return 'var(--rule-strong)';
    return 'var(--rule)';
  };

  const nodeOpacity = (n: ModuleNode): number => {
    if (!active) return 1;
    if (active.module === n.module) return 1;
    if (isNodeNeighbour(n.module, active.module)) return 0.8;
    return 0.35;
  };

  const edgeOpacity = (edge: { from: string; to: string }): number => {
    if (!active) return 0.6;
    return isEdgeHighlighted(edge, active.module) ? 1 : 0.15;
  };

  const edgeStroke = (edge: { from: string; to: string }): string => {
    if (active && isEdgeHighlighted(edge, active.module)) return 'var(--accent)';
    return 'var(--rule-strong)';
  };

  // Keyboard: Arrow keys move between nodes along edges.
  const handleKeyDown = (e: React.KeyboardEvent, node: ModuleNode) => {
    const neighbours = moduleEdges
      .filter((edge) => edge.from === node.module || edge.to === node.module)
      .map((edge) => (edge.from === node.module ? edge.to : edge.from));
    const neighbourNodes = moduleNodes.filter((n) => neighbours.includes(n.module));

    // Defensive guard: if neighbourNodes is empty (isolated node), bail out.
    if (neighbourNodes.length === 0) {
      if (e.key === 'Enter' || e.key === ' ') {
        e.preventDefault();
        navigateTo(node);
      }
      return;
    }

    // Determine the effective focus source: the current focused node
    // if it is among the neighbours, otherwise fall back to the node
    // that triggered this keydown (avoids -1 findIndex edge cases).
    const effectiveFocus =
      focused && neighbourNodes.some((n) => n.module === focused.module) ? focused : node;

    let target: ModuleNode | null = null;
    if (e.key === 'ArrowRight' || e.key === 'ArrowDown') {
      // Next neighbour in array order
      const currentIdx = neighbourNodes.findIndex((n) => n.module === effectiveFocus.module);
      target = neighbourNodes[(currentIdx + 1) % neighbourNodes.length] ?? neighbourNodes[0];
    } else if (e.key === 'ArrowLeft' || e.key === 'ArrowUp') {
      const currentIdx = neighbourNodes.findIndex((n) => n.module === effectiveFocus.module);
      target =
        neighbourNodes[(currentIdx - 1 + neighbourNodes.length) % neighbourNodes.length] ??
        neighbourNodes[0];
    } else if (e.key === 'Enter' || e.key === ' ') {
      e.preventDefault();
      navigateTo(node);
      return;
    } else if (e.key === 'Tab') {
      // Let default Tab proceed; clear focus when leaving.
      return;
    }

    if (target) {
      e.preventDefault();
      setFocused(target);
      const el = nodeRefs.current.get(target.module);
      el?.focus();
    }
  };

  const navigateTo = (node: ModuleNode) => {
    if (node.status === 'published') {
      window.location.href = `/modules/${node.slug}`;
    }
  };

  const transitionStyle = reducedMotion
    ? 'none'
    : 'opacity var(--dur-base) var(--ease), fill var(--dur-fast) var(--ease), stroke var(--dur-fast) var(--ease)';

  return (
    <div className="kg-container">
      <svg
        viewBox={`0 0 ${W} ${H}`}
        className="kg-svg"
        role="application"
        aria-label="Pi Agent 模块依赖图:M01 至 M12 共 12 个模块,箭头表示依赖方向。使用 Tab 键在节点间移动,方向键切换相邻节点,回车进入模块。"
        aria-describedby="kg-sr-list"
      >
        <defs>
          <marker
            id="kg-arrow"
            viewBox="0 0 10 10"
            refX="9"
            refY="5"
            markerWidth="6"
            markerHeight="6"
            orient="auto"
          >
            <path d="M 0 0 L 10 5 L 0 10 z" fill="var(--rule-strong)" />
          </marker>
          <marker
            id="kg-arrow-active"
            viewBox="0 0 10 10"
            refX="9"
            refY="5"
            markerWidth="6"
            markerHeight="6"
            orient="auto"
          >
            <path d="M 0 0 L 10 5 L 0 10 z" fill="var(--accent)" />
          </marker>
        </defs>

        {/* Edges */}
        {moduleEdges.map((e, i) => {
          const from = moduleNodes.find((n) => n.module === e.from)!;
          const to = moduleNodes.find((n) => n.module === e.to)!;
          const dx = to.x - from.x;
          const dy = to.y - from.y;
          const dist = Math.sqrt(dx * dx + dy * dy);
          const ux = dx / dist;
          const uy = dy / dist;
          const highlighted = active ? isEdgeHighlighted(e, active.module) : false;
          return (
            <line
              key={`edge-${i}`}
              x1={from.x + ux * NODE_R}
              y1={from.y + uy * NODE_R}
              x2={to.x - ux * NODE_R}
              y2={to.y - uy * NODE_R}
              stroke={edgeStroke(e)}
              strokeWidth={highlighted ? '2.5' : '1.5'}
              strokeOpacity={edgeOpacity(e)}
              markerEnd={highlighted ? 'url(#kg-arrow-active)' : 'url(#kg-arrow)'}
              style={{ transition: transitionStyle }}
            />
          );
        })}

        {/* Nodes */}
        {moduleNodes.map((n) => (
          <g
            key={n.slug}
            ref={(el) => {
              if (el) {
                nodeRefs.current.set(n.module, el);
              } else {
                nodeRefs.current.delete(n.module);
              }
            }}
            transform={`translate(${n.x}, ${n.y})`}
            onMouseEnter={() => setHovered(n)}
            onMouseLeave={() => setHovered(null)}
            onFocus={() => setFocused(n)}
            onClick={() => navigateTo(n)}
            onKeyDown={(e) => handleKeyDown(e, n)}
            tabIndex={0}
            role="link"
            aria-label={`${n.module}:${n.title}。状态:${n.status === 'published' ? '已发布,可点击进入' : '草稿'}`}
            style={
              {
                cursor: n.status === 'published' ? 'pointer' : 'default',
                opacity: nodeOpacity(n),
                transition: transitionStyle,
                outline: 'none',
              } as CSSProperties
            }
          >
            <circle
              r={NODE_R}
              fill={statusFill(n)}
              stroke={statusStroke(n)}
              strokeWidth={active?.module === n.module ? '3' : '2'}
            />
            <text
              textAnchor="middle"
              dy="0.35em"
              fontFamily="var(--font-mono)"
              fontSize="13"
              fill={readModules.has(n.slug) ? 'var(--paper)' : 'var(--ink-strong)'}
              pointerEvents="none"
            >
              {n.module}
            </text>
          </g>
        ))}
      </svg>

      {/* Tooltip / detail card */}
      {(hovered ?? focused) && (
        <div className="kg-tooltip" role="status">
          <div className="kg-tooltip-module">{(hovered ?? focused)!.module}</div>
          <div className="kg-tooltip-title">{(hovered ?? focused)!.title}</div>
          <div className="kg-tooltip-summary">{(hovered ?? focused)!.summary}</div>
          <div className="kg-tooltip-status">{(hovered ?? focused)!.status}</div>
        </div>
      )}

      {/* Screen-reader fallback: full list */}
      <ul id="kg-sr-list" className="kg-sr-only">
        {moduleNodes.map((n) => (
          <li key={n.slug}>
            {n.module}:{n.title} — {n.summary}({n.status})
          </li>
        ))}
      </ul>

      {/* Inline styles — kept here so the Island is self-contained. */}
      <style>{`
        .kg-container {
          position: relative;
          max-width: 1000px;
          margin: 0 auto;
        }
        .kg-svg {
          width: 100%;
          height: auto;
          display: block;
        }
        .kg-svg:focus-within {
          outline: var(--outline-w) solid var(--accent);
          outline-offset: var(--hl-outline-offset);
          border-radius: var(--radius-md);
        }
        .kg-tooltip {
          position: absolute;
          top: 20px;
          left: 20px;
          background: var(--paper-raised);
          border: var(--border-w) solid var(--rule);
          border-radius: var(--radius-md);
          padding: var(--space-4);
          box-shadow: var(--shadow-2);
          max-width: 280px;
          pointer-events: none;
          z-index: 10;
        }
        .kg-tooltip-module {
          font-family: var(--font-mono);
          color: var(--accent);
          font-size: var(--fs-xs);
        }
        .kg-tooltip-title {
          font-size: var(--fs-h3);
          color: var(--ink-strong);
          margin: var(--space-1) 0;
        }
        .kg-tooltip-summary {
          font-size: var(--fs-small);
          color: var(--muted);
        }
        .kg-tooltip-status {
          font-size: var(--fs-xs);
          color: var(--soft);
          margin-top: var(--space-2);
          text-transform: uppercase;
        }
        .kg-sr-only {
          position: absolute;
          width: 1px;
          height: 1px;
          padding: 0;
          margin: -1px;
          overflow: hidden;
          clip: rect(0, 0, 0, 0);
          white-space: nowrap;
          border: 0;
        }
        @media (prefers-reduced-motion: reduce) {
          .kg-svg * {
            transition: none !important;
          }
        }
      `}</style>
    </div>
  );
}