create-appraisejs 0.3.0 → 0.3.1-alpha.0

package/templates/blank/src/components/diagram/flow-diagram-view.tsx

@@ -0,0 +1,179 @@
+'use client'
+
+/* eslint-disable react-hooks/refs -- The composite view model forwards refs without reading `.current` during render. */
+
+import {
+  Background,
+  ConnectionMode,
+  Controls,
+  ReactFlow,
+  type DefaultEdgeOptions,
+} from '@xyflow/react'
+import { FlowDiagramBlockDialog } from './flow-diagram-block-dialog'
+import { FlowDiagramBlockOverlays } from './flow-diagram-block-overlays'
+import { FlowDiagramGroupingHints } from './flow-diagram-grouping-hints'
+import { FlowDiagramToolbar } from './flow-diagram-toolbar'
+import NodeForm from './node-form'
+import type { ComponentType, RefObject } from 'react'
+
+import type { useFlowDiagram } from './use-flow-diagram'
+
+const defaultEdgeOptions: DefaultEdgeOptions = {
+  type: 'buttonEdge',
+  zIndex: 12,
+  style: {
+    stroke: 'rgb(148 163 184 / 0.9)',
+    strokeWidth: 1.75,
+    strokeLinecap: 'round',
+  },
+}
+
+const flowDiagramProOptions = { hideAttribution: true }
+const partialSelectionMode = 'partial' as never
+
+type FlowDiagramViewProps = {
+  model: ReturnType<typeof useFlowDiagram>
+  FlowLayoutRefresh: ComponentType<{
+    nodeIds: string[]
+    containerRef: RefObject<HTMLDivElement | null>
+    refreshKey?: string | number | boolean
+  }>
+}
+
+export function FlowDiagramView({ model, FlowLayoutRefresh }: FlowDiagramViewProps) {
+  return (
+    <>
+      <div className="relative flex h-full min-h-0 w-full flex-col" onPointerDown={model.search.handleFlowPointerDown}>
+        <FlowDiagramToolbar
+          enableNodeSearch={model.enableNodeSearch}
+          enableNodeGrouping={model.enableNodeGrouping}
+          isSearchOpen={model.search.isSearchOpen}
+          searchQuery={model.search.searchQuery}
+          searchInputRef={model.search.searchInputRef}
+          shouldShowSearchSuggestions={model.search.shouldShowSearchSuggestions}
+          nodeSearchResults={model.search.nodeSearchResults}
+          isGroupingSelectionMode={model.grouping.isGroupingSelectionMode}
+          onSearchQueryChange={model.search.setSearchQuery}
+          onToggleSearch={model.search.toggleSearch}
+          onSearchResultSelect={model.search.handleSearchResultClick}
+          onToggleGroupingSelectionMode={model.grouping.toggleGroupingSelectionMode}
+          onOpenAddNodeDialog={model.openAddNodeDialog}
+        />
+        <div ref={model.flowContainerRef} className="h-full min-h-80 flex-1">
+          <ReactFlow
+            className="size-full"
+            nodes={model.nodes}
+            onNodesChange={model.handleNodesChange}
+            edges={model.edges}
+            onEdgesChange={model.handleEdgesChange}
+            onConnect={model.onConnect}
+            onConnectStart={model.handleConnectStart}
+            onConnectEnd={model.handleConnectEnd}
+            fitView
+            colorMode="dark"
+            connectionMode={ConnectionMode.Loose}
+            edgeTypes={model.edgeTypes}
+            nodeTypes={model.nodeTypes}
+            defaultEdgeOptions={defaultEdgeOptions}
+            connectOnClick={false}
+            deleteKeyCode="Backspace"
+            edgesReconnectable
+            nodesConnectable
+            panOnDrag={!model.grouping.isGroupingSelectionMode}
+            selectionMode={partialSelectionMode}
+            selectionOnDrag={model.grouping.isGroupingSelectionMode}
+            selectNodesOnDrag={false}
+            onSelectionChange={model.grouping.handleSelectionChange}
+            onPaneClick={model.search.handlePaneClick}
+            onNodeClick={model.search.handleNodeClick}
+            isValidConnection={model.isValidConnection}
+            proOptions={flowDiagramProOptions}
+            onInit={model.handleFlowInit}
+          >
+            <FlowLayoutRefresh
+              nodeIds={model.layoutRefreshNodeIds}
+              containerRef={model.flowContainerRef}
+              refreshKey={model.layoutRefreshKey}
+            />
+            <FlowDiagramBlockOverlays
+              flowBlockBounds={model.grouping.flowBlockBounds}
+              onRenameBlock={model.grouping.openRenameBlockDialog}
+              onDeleteBlock={model.grouping.deleteBlock}
+            />
+            <Background />
+            <Controls />
+          </ReactFlow>
+        </div>
+        <FlowDiagramGroupingHints
+          showCreateBlock={
+            model.enableNodeGrouping &&
+            model.grouping.isGroupingSelectionMode &&
+            model.grouping.selectedGroupingNodeIds.length >= 2 &&
+            !model.grouping.hasOrphanedNodes
+          }
+          showOrphanMessage={
+            model.enableNodeGrouping &&
+            model.grouping.isGroupingSelectionMode &&
+            model.grouping.selectedGroupingNodeIds.length >= 2 &&
+            model.grouping.hasOrphanedNodes
+          }
+          orphanMessage={model.grouping.blockOrphanedNodeMessage}
+          onCreateBlock={model.grouping.openCreateBlockDialog}
+        />
+      </div>
+
+      <FlowDiagramBlockDialog
+        open={model.grouping.isBlockDialogOpen}
+        onOpenChange={model.grouping.setIsBlockDialogOpen}
+        editingBlockId={model.grouping.editingBlockId}
+        blockName={model.grouping.blockName}
+        onBlockNameChange={model.grouping.setBlockName}
+        onSubmit={model.grouping.handleBlockDialogSubmit}
+      />
+
+      <NodeForm
+        onSubmitAction={model.addNode}
+        mode="add"
+        initialValues={{
+          label: '',
+          gherkinStep: '',
+          templateStepId: '',
+          parameters: [],
+        }}
+        templateSteps={model.memoizedTemplateSteps}
+        templateStepParams={model.memoizedTemplateStepParams}
+        showAddNodeDialog={model.showAddNodeDialog}
+        setShowAddNodeDialog={model.setShowAddNodeDialog}
+        locators={model.mergedLocators}
+        defaultValueInput={model.defaultValueInput}
+        locatorGroups={model.mergedLocatorGroups}
+        environments={model.environments}
+        modules={model.modules}
+        onLocatorCreated={model.handleLocatorCreated}
+      />
+
+      {model.editNodeData ? (
+        <NodeForm
+          onSubmitAction={model.handleEditNodeSubmit}
+          mode="edit"
+          initialValues={{
+            label: model.editNodeData.label ?? '',
+            gherkinStep: model.editNodeData.gherkinStep ?? '',
+            templateStepId: model.editNodeData.templateStepId ?? '',
+            parameters: model.editNodeData.parameters ?? [],
+          }}
+          templateSteps={model.memoizedTemplateSteps}
+          templateStepParams={model.memoizedTemplateStepParams}
+          showAddNodeDialog={model.showEditNodeDialog}
+          setShowAddNodeDialog={model.setShowEditNodeDialog}
+          locators={model.mergedLocators}
+          defaultValueInput={model.defaultValueInput}
+          locatorGroups={model.mergedLocatorGroups}
+          environments={model.environments}
+          modules={model.modules}
+          onLocatorCreated={model.handleLocatorCreated}
+        />
+      ) : null}
+    </>
+  )
+}

package/templates/blank/src/components/diagram/flow-diagram.test.tsx

@@ -0,0 +1,501 @@
+// @vitest-environment jsdom
+
+import { render, screen, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import FlowDiagram from './flow-diagram'
+
+const xyflowMocks = vi.hoisted(() => ({
+  setCenter: vi.fn(),
+  updateNodeInternals: vi.fn(),
+}))
+
+vi.mock('@xyflow/react', async () => {
+  const React = await import('react')
+
+  return {
+    addEdge: (edge: unknown, edges: unknown[]) => [...edges, edge],
+    Background: () => <div data-testid="flow-background" />,
+    ConnectionMode: { Loose: 'loose' },
+    Controls: () => <div data-testid="flow-controls" />,
+    ReactFlow: ({
+      children,
+      edges = [],
+      nodes = [],
+      onInit,
+      onConnect,
+      onPaneClick,
+      onNodeClick,
+      onSelectionChange,
+    }: {
+      children: React.ReactNode
+      edges?: Array<{ source: string; target: string }>
+      nodes?: Array<{
+        id: string
+        data?: { isDeleteDisabled?: boolean; isSearchHighlighted?: boolean; label?: string }
+      }>
+      onInit?: (instance: unknown) => void
+      onConnect?: (connection: { source: string; target: string }) => void
+      onPaneClick?: () => void
+      onNodeClick?: (event: React.MouseEvent, node: { id: string }) => void
+      onSelectionChange?: (selection: { nodes: Array<{ id: string }> }) => void
+    }) => {
+      React.useEffect(() => {
+        onInit?.({ setCenter: xyflowMocks.setCenter })
+      }, [onInit])
+
+      const handlePaneKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
+        if (event.key === 'Enter' || event.key === ' ') {
+          event.preventDefault()
+          onPaneClick?.()
+        }
+      }
+
+      return (
+        <div
+          data-testid="react-flow"
+          role="group"
+          aria-label="Flow canvas mock"
+          tabIndex={0}
+          onClick={onPaneClick}
+          onKeyDown={handlePaneKeyDown}
+        >
+          {nodes.map(node => (
+            <button
+              key={node.id}
+              type="button"
+              data-testid={`flow-node-${node.id}`}
+              data-delete-disabled={node.data?.isDeleteDisabled ? 'true' : undefined}
+              data-search-highlighted={node.data?.isSearchHighlighted ? 'true' : undefined}
+              onClick={event => {
+                event.stopPropagation()
+                onNodeClick?.(event, node)
+              }}
+            >
+              {node.id}
+            </button>
+          ))}
+          <button type="button" onClick={() => onSelectionChange?.({ nodes })}>
+            Select all flow nodes
+          </button>
+          {nodes.some(node => node.id === 'node-3') && (
+            <button type="button" onClick={() => onConnect?.({ source: 'node-2', target: 'node-3' })}>
+              Connect node-2 to node-3
+            </button>
+          )}
+          <output data-testid="edge-count">{edges.length}</output>
+          {children}
+        </div>
+      )
+    },
+    ViewportPortal: ({ children }: { children: React.ReactNode }) => <>{children}</>,
+    useEdgesState: (initialEdges: unknown[]) => {
+      const [edges, setEdges] = React.useState(initialEdges)
+      return [edges, setEdges, vi.fn()]
+    },
+    useNodesState: (initialNodes: unknown[]) => {
+      const [nodes, setNodes] = React.useState(initialNodes)
+      return [nodes, setNodes, vi.fn()]
+    },
+    useUpdateNodeInternals: () => xyflowMocks.updateNodeInternals,
+  }
+})
+
+vi.mock('./node-form', () => ({
+  default: ({ mode, showAddNodeDialog }: { mode: string; showAddNodeDialog: boolean }) =>
+    showAddNodeDialog ? <div role="dialog">Node form {mode}</div> : null,
+}))
+
+const requiredProps = {
+  templateStepParams: [],
+  templateSteps: [],
+  locators: [],
+  locatorGroups: [],
+  environments: [],
+  modules: [],
+  onNodeOrderChange: vi.fn(),
+}
+
+function renderFlowDiagram(enableNodeSearch = true) {
+  return render(
+    <FlowDiagram
+      {...requiredProps}
+      enableNodeSearch={enableNodeSearch}
+      nodeOrder={{
+        'node-1': {
+          order: 1,
+          label: 'Open Checkout',
+          gherkinStep: 'Given cart page',
+          parameters: [],
+          templateStepId: 'step-1',
+        },
+        'node-2': {
+          order: 2,
+          label: 'Submit Payment',
+          gherkinStep: 'When the Visa card is submitted',
+          parameters: [
+            {
+              name: 'card',
+              value: 'visa',
+              type: 'STRING',
+              order: 1,
+            },
+          ],
+          templateStepId: 'step-2',
+        },
+      }}
+    />,
+  )
+}
+
+describe('FlowDiagram node search', () => {
+  beforeEach(() => {
+    xyflowMocks.setCenter.mockClear()
+    xyflowMocks.updateNodeInternals.mockClear()
+  })
+
+  it('reveals search input only when enabled', async () => {
+    const user = userEvent.setup()
+    renderFlowDiagram()
+
+    await user.click(screen.getByRole('button', { name: /search nodes/i }))
+
+    expect(screen.getByRole('textbox', { name: /search nodes/i })).toBeInTheDocument()
+  })
+
+  it('keeps suggestions hidden until three characters and renders matching labels only', async () => {
+    const user = userEvent.setup()
+    renderFlowDiagram()
+
+    await user.click(screen.getByRole('button', { name: /search nodes/i }))
+    await user.type(screen.getByRole('textbox', { name: /search nodes/i }), 'pa')
+
+    expect(screen.queryByText('Submit Payment')).not.toBeInTheDocument()
+
+    await user.type(screen.getByRole('textbox', { name: /search nodes/i }), 'y')
+
+    expect(screen.getByText('Submit Payment')).toBeInTheDocument()
+    expect(screen.queryByText('Open Checkout')).not.toBeInTheDocument()
+  })
+
+  it('shows an empty state when no labels match', async () => {
+    const user = userEvent.setup()
+    renderFlowDiagram()
+
+    await user.click(screen.getByRole('button', { name: /search nodes/i }))
+    await user.type(screen.getByRole('textbox', { name: /search nodes/i }), 'zzz')
+
+    expect(screen.getByText('No matching labels')).toBeInTheDocument()
+  })
+
+  it('closes search when clicking elsewhere in the flow builder', async () => {
+    const user = userEvent.setup()
+    renderFlowDiagram()
+
+    await user.click(screen.getByRole('button', { name: /search nodes/i }))
+    expect(screen.getByRole('textbox', { name: /search nodes/i })).toBeInTheDocument()
+
+    await user.pointer({ keys: '[MouseLeft]', target: screen.getByTestId('react-flow') })
+
+    await waitFor(() => {
+      expect(screen.queryByRole('textbox', { name: /search nodes/i })).not.toBeInTheDocument()
+    })
+  })
+
+  it('opens edit settings and focuses the matched node when a suggestion is selected', async () => {
+    const user = userEvent.setup()
+    renderFlowDiagram()
+
+    await user.click(screen.getByRole('button', { name: /search nodes/i }))
+    await user.type(screen.getByRole('textbox', { name: /search nodes/i }), 'pay')
+    await user.click(screen.getByText('Submit Payment'))
+
+    expect(screen.getByRole('dialog')).toHaveTextContent('Node form edit')
+    expect(xyflowMocks.setCenter).toHaveBeenCalledWith(1072, 72, {
+      zoom: 1.15,
+      duration: 420,
+    })
+  })
+
+  it('clears the search highlight when clicking away on the canvas', async () => {
+    const user = userEvent.setup()
+    renderFlowDiagram()
+
+    await user.click(screen.getByRole('button', { name: /search nodes/i }))
+    await user.type(screen.getByRole('textbox', { name: /search nodes/i }), 'pay')
+    await user.click(screen.getByText('Submit Payment'))
+
+    await waitFor(() => {
+      expect(screen.getByTestId('flow-node-node-2')).toHaveAttribute('data-search-highlighted', 'true')
+    })
+
+    await user.click(screen.getByTestId('react-flow'))
+
+    await waitFor(() => {
+      expect(screen.getByTestId('flow-node-node-2')).not.toHaveAttribute('data-search-highlighted')
+    })
+  })
+
+  it('clears the search highlight when selecting a different node', async () => {
+    const user = userEvent.setup()
+    renderFlowDiagram()
+
+    await user.click(screen.getByRole('button', { name: /search nodes/i }))
+    await user.type(screen.getByRole('textbox', { name: /search nodes/i }), 'pay')
+    await user.click(screen.getByText('Submit Payment'))
+
+    await waitFor(() => {
+      expect(screen.getByTestId('flow-node-node-2')).toHaveAttribute('data-search-highlighted', 'true')
+    })
+
+    await user.click(screen.getByTestId('flow-node-node-1'))
+
+    await waitFor(() => {
+      expect(screen.getByTestId('flow-node-node-2')).not.toHaveAttribute('data-search-highlighted')
+    })
+  })
+
+  it('refreshes node internals when the layout refresh key changes', async () => {
+    const { rerender } = render(
+      <FlowDiagram
+        {...requiredProps}
+        layoutRefreshKey={false}
+        nodeOrder={{
+          'node-1': {
+            order: 1,
+            label: 'Open Checkout',
+            gherkinStep: 'Given cart page',
+            parameters: [],
+            templateStepId: 'step-1',
+          },
+        }}
+      />,
+    )
+
+    await waitFor(() => {
+      expect(xyflowMocks.updateNodeInternals).toHaveBeenCalledWith(['node-1'])
+    })
+
+    xyflowMocks.updateNodeInternals.mockClear()
+
+    rerender(
+      <FlowDiagram
+        {...requiredProps}
+        layoutRefreshKey
+        nodeOrder={{
+          'node-1': {
+            order: 1,
+            label: 'Open Checkout',
+            gherkinStep: 'Given cart page',
+            parameters: [],
+            templateStepId: 'step-1',
+          },
+        }}
+      />,
+    )
+
+    await waitFor(() => {
+      expect(xyflowMocks.updateNodeInternals).toHaveBeenCalledWith(['node-1'])
+    })
+  })
+})
+
+describe('FlowDiagram node grouping', () => {
+  it('keeps the main add-node action available after a block exists', async () => {
+    const user = userEvent.setup()
+    render(
+      <FlowDiagram
+        {...requiredProps}
+        enableNodeGrouping
+        nodeOrder={{
+          'node-1': {
+            order: 1,
+            label: 'Open Checkout',
+            gherkinStep: 'Given cart page',
+            parameters: [],
+            templateStepId: 'step-1',
+          },
+          'node-2': {
+            order: 2,
+            label: 'Submit Payment',
+            gherkinStep: 'When payment is submitted',
+            parameters: [],
+            templateStepId: 'step-2',
+          },
+        }}
+        flowBlocks={[{ id: 'block-1', name: 'Checkout block', nodeIds: ['node-1', 'node-2'] }]}
+      />,
+    )
+
+    const addNodeButton = screen.getByRole('button', { name: 'Add Node' })
+
+    expect(addNodeButton).toBeEnabled()
+
+    await user.click(addNodeButton)
+
+    expect(screen.getByRole('dialog')).toHaveTextContent('Node form add')
+  })
+
+  it('disables delete only for nodes that belong to a block', async () => {
+    render(
+      <FlowDiagram
+        {...requiredProps}
+        enableNodeGrouping
+        nodeOrder={{
+          'node-1': {
+            order: 1,
+            label: 'Open Checkout',
+            gherkinStep: 'Given cart page',
+            parameters: [],
+            templateStepId: 'step-1',
+          },
+          'node-2': {
+            order: 2,
+            label: 'Submit Payment',
+            gherkinStep: 'When payment is submitted',
+            parameters: [],
+            templateStepId: 'step-2',
+          },
+          'node-3': {
+            order: -1,
+            label: 'Outside block',
+            gherkinStep: 'Then outside',
+            parameters: [],
+            templateStepId: 'step-3',
+          },
+        }}
+        flowBlocks={[{ id: 'block-1', name: 'Checkout block', nodeIds: ['node-1', 'node-2'] }]}
+      />,
+    )
+
+    await waitFor(() => {
+      expect(screen.getByTestId('flow-node-node-1')).toHaveAttribute('data-delete-disabled', 'true')
+      expect(screen.getByTestId('flow-node-node-3')).not.toHaveAttribute('data-delete-disabled')
+    })
+  })
+
+  it('does not open block creation when selection mode is toggled on an empty flow', async () => {
+    const user = userEvent.setup()
+    render(<FlowDiagram {...requiredProps} enableNodeGrouping nodeOrder={{}} />)
+
+    await user.click(screen.getByRole('button', { name: /select nodes for block/i }))
+
+    expect(screen.queryByRole('button', { name: /create block/i })).not.toBeInTheDocument()
+    expect(screen.queryByRole('dialog')).not.toBeInTheDocument()
+  })
+
+  it('does not allow block creation while any real node is orphaned', async () => {
+    const user = userEvent.setup()
+    render(
+      <FlowDiagram
+        {...requiredProps}
+        enableNodeGrouping
+        nodeOrder={{
+          'node-1': {
+            order: 1,
+            label: 'Open Checkout',
+            gherkinStep: 'Given cart page',
+            parameters: [],
+            templateStepId: 'step-1',
+          },
+          'node-2': {
+            order: 2,
+            label: 'Submit Payment',
+            gherkinStep: 'When payment is submitted',
+            parameters: [],
+            templateStepId: 'step-2',
+          },
+          'node-3': {
+            order: -1,
+            label: 'Orphaned node',
+            gherkinStep: 'Then orphaned',
+            parameters: [],
+            templateStepId: 'step-3',
+          },
+        }}
+      />,
+    )
+
+    await user.click(screen.getByRole('button', { name: /select nodes for block/i }))
+    await user.click(screen.getByRole('button', { name: /select all flow nodes/i }))
+
+    expect(screen.queryByRole('button', { name: /create block/i })).not.toBeInTheDocument()
+    expect(screen.getByText('Connect or remove orphaned nodes before creating a block.')).toBeInTheDocument()
+  })
+
+  it('allows a block node to connect to an outside node', async () => {
+    const user = userEvent.setup()
+    const onNodeOrderChange = vi.fn()
+
+    render(
+      <FlowDiagram
+        {...requiredProps}
+        onNodeOrderChange={onNodeOrderChange}
+        enableNodeGrouping
+        nodeOrder={{
+          'node-1': {
+            order: 1,
+            label: 'Open Checkout',
+            gherkinStep: 'Given cart page',
+            parameters: [],
+            templateStepId: 'step-1',
+          },
+          'node-2': {
+            order: 2,
+            label: 'Submit Payment',
+            gherkinStep: 'When payment is submitted',
+            parameters: [],
+            templateStepId: 'step-2',
+          },
+          'node-3': {
+            order: -1,
+            label: 'Outside block',
+            gherkinStep: 'Then outside',
+            parameters: [],
+            templateStepId: 'step-3',
+          },
+        }}
+        flowBlocks={[{ id: 'block-1', name: 'Checkout block', nodeIds: ['node-1', 'node-2'] }]}
+      />,
+    )
+
+    await user.click(screen.getByRole('button', { name: /connect node-2 to node-3/i }))
+
+    await waitFor(() => {
+      expect(onNodeOrderChange).toHaveBeenCalledWith(
+        expect.objectContaining({
+          'node-3': expect.objectContaining({ order: 3 }),
+        }),
+      )
+    })
+  })
+
+  it('renders block labels with stronger visual emphasis', () => {
+    render(
+      <FlowDiagram
+        {...requiredProps}
+        enableNodeGrouping
+        nodeOrder={{
+          'node-1': {
+            order: 1,
+            label: 'Open Checkout',
+            gherkinStep: 'Given cart page',
+            parameters: [],
+            templateStepId: 'step-1',
+          },
+          'node-2': {
+            order: 2,
+            label: 'Submit Payment',
+            gherkinStep: 'When payment is submitted',
+            parameters: [],
+            templateStepId: 'step-2',
+          },
+        }}
+        flowBlocks={[{ id: 'block-1', name: 'Checkout block', nodeIds: ['node-1', 'node-2'] }]}
+      />,
+    )
+
+    expect(screen.getByText('Checkout block').parentElement).toHaveClass('text-sm', 'font-semibold', 'text-foreground')
+  })
+})