fix(docs): preserve focus in workflow illustrations

Author: waleedlatif1

apps/docs/components/workflow-preview/docs-block-node.tsx

@@ -1,6 +1,7 @@
 'use client'
 
 import { type ComponentType, memo, useContext } from 'react'
+import { cn } from '@sim/emcn'
 import {
   type CanvasSentenceSegment,
   CanvasSentenceView,
@@ -13,6 +14,7 @@ import { normalizeBlockType, resolveIcon } from '@/components/workflow-preview/b
 import { PreviewSelectionContext } from '@/components/workflow-preview/preview-selection-context'
 import {
   BLOCK_STAGGER,
+  DIMMED_PREVIEW_CLASS,
   EASE_OUT,
   type PreviewTool,
 } from '@/components/workflow-preview/workflow-data'
@@ -38,6 +40,7 @@ export interface DocsBlockData extends Record<string, unknown> {
   index?: number
   animate?: boolean
   isHighlighted?: boolean
+  isDimmed?: boolean
 }
 
 export type DocsBlockNodeType = Node<DocsBlockData, 'previewBlock'>
@@ -66,6 +69,7 @@ export const DocsBlockNode = memo(function DocsBlockNode({
     index = 0,
     animate = false,
     isHighlighted = false,
+    isDimmed = false,
   } = data
 
   /** The View gates router handle topology on `type === 'router_v2'`. */
@@ -133,7 +137,7 @@ export const DocsBlockNode = memo(function DocsBlockNode({
 
   return (
     <m.div
-      className='relative transition-opacity duration-300'
+      className={cn('relative transition-opacity duration-300', isDimmed && DIMMED_PREVIEW_CLASS)}
       initial={animate ? { opacity: 0 } : false}
       animate={{ opacity: 1 }}
       transition={{ duration: 0.45, delay, ease: EASE_OUT }}

apps/docs/components/workflow-preview/docs-container-node.tsx

@@ -1,24 +1,27 @@
 'use client'
 
 import { memo, useContext } from 'react'
+import { cn } from '@sim/emcn'
 import { type SubflowNodeData, SubflowNodeView } from '@sim/workflow-renderer'
 import type { Node, NodeProps } from '@xyflow/react'
 import { PreviewSelectionContext } from '@/components/workflow-preview/preview-selection-context'
+import { DIMMED_PREVIEW_CLASS } from '@/components/workflow-preview/workflow-data'
 
 export interface DocsContainerData extends Record<string, unknown> {
   name: string
   blockType: string
   size?: { width: number; height: number }
   parentId?: string
   isHighlighted?: boolean
+  isDimmed?: boolean
 }
 
 export type DocsContainerNodeType = Node<DocsContainerData, 'previewContainer'>
 
 /**
  * Docs adapter for loop/parallel container blocks: maps the static preview data
- * to {@link SubflowNodeView}'s read-only `isPreview` shape. Carries no stores,
- * hooks, or queries — it only reshapes data into View props.
+ * to {@link SubflowNodeView}'s read-only `isPreview` shape. Carries no stores
+ * or queries — it only reshapes data into View props.
  */
 export const DocsContainerNode = memo(function DocsContainerNode({
   id,
@@ -36,15 +39,17 @@ export const DocsContainerNode = memo(function DocsContainerNode({
   }
 
   return (
-    <SubflowNodeView
-      id={id}
-      data={subflowData}
-      isEnabled
-      isLocked={false}
-      isFocused={false}
-      nestingLevel={0}
-      canEditWorkflow={false}
-      onSelect={() => selectBlock?.(id)}
-    />
+    <div className={cn('h-full w-full', data.isDimmed && DIMMED_PREVIEW_CLASS)}>
+      <SubflowNodeView
+        id={id}
+        data={subflowData}
+        isEnabled
+        isLocked={false}
+        isFocused={false}
+        nestingLevel={0}
+        canEditWorkflow={false}
+        onSelect={() => selectBlock?.(id)}
+      />
+    </div>
   )
 })

apps/docs/components/workflow-preview/workflow-data.test.ts

@@ -106,3 +106,40 @@ describe('authored canvas presentation', () => {
     }
   })
 })
+
+describe('authored diagram focus', () => {
+  it('keeps every node visible when no step is emphasized', () => {
+    const { nodes } = toReactFlowElements(workflow)
+    expect(nodes.every((node) => !node.data.isDimmed)).toBe(true)
+  })
+
+  it('de-emphasizes surrounding cards and containers for a highlighted step', () => {
+    const { nodes } = toReactFlowElements(workflow, false, { highlightBlock: 'agent' })
+    expect(nodes.filter((node) => node.data.isDimmed).map((node) => node.id)).toEqual([
+      'start',
+      'loop',
+      'parallel',
+    ])
+    expect(nodes.find((node) => node.id === 'agent')?.data.isHighlighted).toBe(true)
+  })
+
+  it('keeps both the authored focus and inspected block at full emphasis', () => {
+    const { nodes } = toReactFlowElements(workflow, false, {
+      highlightBlock: 'agent',
+      selectedBlock: 'loop',
+    })
+    expect(nodes.filter((node) => !node.data.isDimmed).map((node) => node.id)).toEqual([
+      'loop',
+      'agent',
+    ])
+  })
+
+  it('de-emphasizes nodes when the illustration focuses on an edge', () => {
+    const { nodes, edges } = toReactFlowElements(workflow, false, {
+      highlightEdge: 'loop-agent',
+    })
+    expect(nodes.every((node) => node.data.isDimmed)).toBe(true)
+    expect(edges.find((edge) => edge.id === 'loop-agent')?.style?.opacity).toBe(1)
+    expect(edges.find((edge) => edge.id === 'start-loop')?.style?.opacity).toBeLessThan(1)
+  })
+})

apps/docs/components/workflow-preview/workflow-data.ts

@@ -82,6 +82,10 @@ const EDGE_STYLE_HIGHLIGHT = { stroke: 'var(--brand-secondary)', strokeWidth: 2.
 /** Edges leaving a block's error port render red, matching the editor. */
 const EDGE_STYLE_ERROR = { stroke: 'var(--text-error)', strokeWidth: 2 } as const
 
+/** De-emphasizes diagram context without reducing the contrast of its text. */
+export const DIMMED_PREVIEW_CLASS =
+  '[&_[data-workflow-block-border]]:opacity-35 [&_[data-workflow-type-accent]]:grayscale [&_[data-subflow-type-tag]]:grayscale'
+
 /** Optional emphasis: light one block or one edge and dim everything else. */
 export interface HighlightOptions {
   highlightBlock?: string
@@ -165,6 +169,7 @@ export function toReactFlowElements(
         index,
         animate,
         isHighlighted: highlightBlock === block.id || selectedBlock === block.id,
+        isDimmed: hasHighlight && highlightBlock !== block.id && selectedBlock !== block.id,
       }
       return {
         ...commonNode,
@@ -191,6 +196,7 @@ export function toReactFlowElements(
       index,
       animate,
       isHighlighted: highlightBlock === block.id || selectedBlock === block.id,
+      isDimmed: hasHighlight && highlightBlock !== block.id && selectedBlock !== block.id,
     }
     return {
       ...commonNode,

packages/workflow-renderer/src/workflow-block/workflow-block-border.tsx

@@ -1717,6 +1717,7 @@ export function WorkflowBlockBorder({
   return (
     <svg
       ref={svgRef}
+      data-workflow-block-border=''
       viewBox={`${-BORDER_PADDING_PX} ${-BORDER_PADDING_PX} ${size.width + BORDER_PADDING_PX * 2} ${size.height + BORDER_PADDING_PX * 2}`}
       preserveAspectRatio='none'
       className='pointer-events-none absolute z-0 overflow-visible'