Add scroll-to-change navigation from diff sidebar

Clicking on a change in the diff sidebar now scrolls to that operation
in the documentation viewer. Supports all three visualizers:
- SwaggerUI: DOM-based scrolling with operation expansion
- Stoplight: Hash-based navigation
- Redocly: Hash set on iframe

Also removes unused DiffDialog component.

Author: ulrikandersen

src/features/docs/navigation/index.ts

@@ -0,0 +1 @@
+export { scrollToOperation } from "./scrollToOperation"

src/features/docs/navigation/scrollToOperation.ts

@@ -0,0 +1,82 @@
+import { DocumentationVisualizer } from "@/features/settings/domain"
+
+/**
+ * Finds and scrolls to a SwaggerUI operation element.
+ * SwaggerUI elements have IDs in the format: operations-{tag}-{operationId}
+ * Since we may not know the tag, we search for elements containing the operationId.
+ */
+function scrollToSwaggerOperation(operationId: string): boolean {
+  // SwaggerUI uses element IDs in the format: operations-{tag}-{operationId}
+  const allOpBlocks = document.querySelectorAll('[id^="operations-"]')
+
+  for (let i = 0; i < allOpBlocks.length; i++) {
+    const block = allOpBlocks[i]
+    if (block.id.endsWith(`-${operationId}`)) {
+      block.scrollIntoView({ behavior: "smooth", block: "start" })
+      // Expand the operation by clicking on its control button
+      const button = block.querySelector(".opblock-summary-control")
+      if (button instanceof HTMLElement) {
+        button.click()
+      }
+      return true
+    }
+  }
+
+  return false
+}
+
+/**
+ * Scrolls to an operation in Redocly by setting the hash on the iframe.
+ * Redocly uses hash format: #operation/{operationId}
+ */
+function scrollToRedoclyOperation(operationId: string): void {
+  const iframe = document.querySelector("iframe")
+  if (!iframe?.contentWindow) {
+    return
+  }
+  iframe.contentWindow.location.hash = `operation/${operationId}`
+}
+
+/**
+ * Scrolls to an operation in the documentation viewer.
+ * Each visualizer has its own mechanism for deep linking.
+ *
+ * For SwaggerUI: Uses DOM-based scrolling to find operations-{tag}-{operationId} elements
+ * For Stoplight: #/operations/{operationId}
+ * For Redocly: #operation/{operationId} (set on iframe)
+ */
+export function scrollToOperation(
+  visualizer: DocumentationVisualizer,
+  operationId?: string,
+  method?: string,
+  path?: string
+): void {
+  if (!operationId && (!method || !path)) {
+    return
+  }
+
+  switch (visualizer) {
+    case DocumentationVisualizer.SWAGGER:
+      // SwaggerUI: Use DOM-based scrolling since hash changes don't trigger navigation
+      // after initial page load
+      if (operationId) {
+        scrollToSwaggerOperation(operationId)
+      }
+      break
+
+    case DocumentationVisualizer.STOPLIGHT:
+      // Stoplight uses hash-based navigation: #/operations/{operationId}
+      if (operationId) {
+        window.location.hash = `/operations/${operationId}`
+      }
+      break
+
+    case DocumentationVisualizer.REDOCLY:
+      // Redocly runs in an iframe and uses hash format: #tag/{tag}/operation/{operationId}
+      // We need to set the hash on the iframe's content window
+      if (operationId) {
+        scrollToRedoclyOperation(operationId)
+      }
+      break
+  }
+}

src/features/projects/view/toolbar/MobileToolbar.tsx

@@ -28,7 +28,11 @@ const MobileToolbar = () => {
         sx={{ width: "100%" }}
       />
       <Selector
-        items={version.specifications}
+        items={version.specifications.map(spec => ({
+          id: spec.id,
+          name: spec.name,
+          hasChanges: !!spec.diffURL
+        }))}
         selection={specification.id}
         onSelect={selectSpecification}
         sx={{ width: "100%" }}

src/features/projects/view/toolbar/TrailingToolbarItem.tsx

@@ -59,7 +59,11 @@ const TrailingToolbarItem = () => {
         />
         <Typography variant="h6" sx={{ marginRight: 1 }}>/</Typography>
         <Selector
-          items={version.specifications}
+          items={version.specifications.map(spec => ({
+            id: spec.id,
+            name: spec.name,
+            hasChanges: !!spec.diffURL
+          }))}
           selection={specification.id}
           onSelect={selectSpecification}
           sx={{ marginRight: 0.5 }}

src/features/sidebar/view/internal/diffbar/DiffContent.tsx

@@ -1,18 +1,21 @@
 "use client"
 
 import { Alert, Box, Typography, Link } from "@mui/material"
-import { useState } from "react"
 import useDiff from "@/features/sidebar/data/useDiff"
 import { useProjectSelection } from "@/features/projects/data"
+import useDocumentationVisualizer from "@/features/settings/data/useDocumentationVisualizer"
+import { scrollToOperation } from "@/features/docs/navigation"
 import DiffList, { DiffListStatus } from "./components/DiffList"
-import DiffDialog from "./components/DiffDialog"
+import { DiffChange } from "@/features/diff/domain/DiffChange"
 
 const DiffContent = () => {
   const { data, loading, changes, error, isNewFile } = useDiff()
   const { specification } = useProjectSelection()
-  const [selectedChange, setSelectedChange] = useState<number | null>(null)
+  const [visualizer] = useDocumentationVisualizer()
 
-  const closeModal = () => setSelectedChange(null)
+  const handleChangeClick = (change: DiffChange) => {
+    scrollToOperation(visualizer, change.operationId, change.operation, change.path)
+  }
 
   const hasData = Boolean(data)
   const hasChanges = changes.length > 0
@@ -101,17 +104,10 @@ const DiffContent = () => {
           <DiffList
             changes={changes}
             status={diffStatus}
-            selectedChange={selectedChange}
-            onClick={(i) => setSelectedChange(i)}
+            onClick={handleChangeClick}
           />
         </Box>
       )}
-
-      <DiffDialog
-        open={selectedChange !== null}
-        change={selectedChange !== null ? changes[selectedChange] : null}
-        onClose={closeModal}
-      />
     </Box>
   )
 }

src/features/sidebar/view/internal/diffbar/components/DiffDialog.tsx

@@ -9,13 +9,11 @@ export type DiffListStatus = "idle" | "loading" | "empty" | "ready" | "error"
 const DiffList = ({
   changes,
   status,
-  selectedChange,
   onClick,
 }: {
   changes: DiffChange[]
   status: DiffListStatus
-  selectedChange: number | null
-  onClick: (i: number) => void
+  onClick: (change: DiffChange) => void
 }) => {
   if (status === "loading") {
     return (
@@ -37,7 +35,6 @@ const DiffList = ({
     return (
       <PopulatedDiffList
         changes={changes}
-        selectedChange={selectedChange}
         onClick={onClick}
       />
     )

src/features/sidebar/view/internal/diffbar/components/DiffList.tsx

@@ -10,22 +10,19 @@ const DiffListItem = ({
   text,
   level,
   operation,
-  selected,
   onClick,
 }: {
   path?: string
   text?: string
   level?: number
   operation?: string
-  selected: boolean
   onClick: () => void
 }) => {
   const levelConfig = getLevelConfig((level ?? 1) as Level)
 
   return (
     <ListItem disableGutters disablePadding>
       <ListItemButton
-        selected={selected}
         onClick={onClick}
         disableGutters
         sx={{ width: "100%", px: 0, alignItems: "flex-start" }}

src/features/sidebar/view/internal/diffbar/components/DiffListItem.tsx

@@ -6,12 +6,10 @@ import { DiffChange } from "@/features/diff/domain/DiffChange"
 
 const PopulatedDiffList = ({
   changes,
-  selectedChange,
   onClick,
 }: {
   changes: DiffChange[]
-  selectedChange: number | null
-  onClick: (i: number) => void
+  onClick: (change: DiffChange) => void
 }) => {
   return (
     <SpacedList
@@ -21,15 +19,14 @@ const PopulatedDiffList = ({
         "& .menu-item-highlight": { px: 1, py: 1.25 },
       }}
     >
-      {changes.map((change, i) => (
+      {changes.map((change) => (
         <DiffListItem
           key={change.id}
           path={change?.path}
           text={change?.text}
           level={change?.level}
           operation={change?.operation}
-          selected={selectedChange === i}
-          onClick={() => onClick(i)}
+          onClick={() => onClick(change)}
         />
       ))}
     </SpacedList>