Canvas

Visão geral

Canvas é um wrapper fino da Gremorie em torno do ReactFlow de @xyflow/react. Ele define os defaults que a Gremorie espera para canvases de workflow de IA: panOnScroll, selectionOnDrag, fitView no primeiro render, deleção vinculada a Backspace e Delete, e um Background no tom da sidebar.

Use-o para qualquer superfície de nós e edges: editores de fluxo de agentes, visualizações de grafo de prompt, construtores de pipeline, roteamento de LLM em múltiplas etapas. Componha com Node, Edge, Connection, Controls, Panel e Toolbar da mesma família.

O stylesheet do xyflow é importado no nível do módulo (@xyflow/react/dist/style.css), então os projetos consumidores não precisam gerenciá-lo manualmente - embora importá-lo uma vez no entry da app ainda seja recomendado para evitar surpresas de ordem de execução.

Preview

'use client';import '@xyflow/react/dist/style.css';import { Canvas, Controls, Panel } from '@gremorie/rx-ai';import {  type Edge as FlowEdge,  type Node as FlowNode,  ReactFlowProvider,} from '@xyflow/react';const canvasNodes: FlowNode[] = [  {    id: '1',    position: { x: 0, y: 0 },    data: { label: 'Prompt' },    type: 'input',  },  {    id: '2',    position: { x: 220, y: -40 },    data: { label: 'Retrieve context' },  },  {    id: '3',    position: { x: 220, y: 80 },    data: { label: 'Generate answer' },    type: 'output',  },];const canvasEdges: FlowEdge[] = [  { id: 'e1-2', source: '1', target: '2' },  { id: 'e1-3', source: '1', target: '3' },];export function CanvasPreview() {  return (    <div className="h-[360px] w-full">      <ReactFlowProvider>        <Canvas edges={canvasEdges} nodes={canvasNodes}>          <Controls />          <Panel position="top-right">            <span className="px-2 text-muted-foreground text-xs">              3 nodes · 2 edges            </span>          </Panel>        </Canvas>      </ReactFlowProvider>    </div>  );}

Anatomia

Canvas                    React Flow viewport
├─ Node …                 nodeTypes (custom renderers)
├─ Edge …                 edgeTypes (Edge.Temporary · Edge.Animated)
├─ Connection             in-progress connection line
└─ overlays (children)    Panel · Controls · Toolbar

Instalação

Requer @xyflow/react como peer dependency.

Uso

import { useNodesState, useEdgesState } from "@xyflow/react";
import {
  Canvas,
  Controls,
  Panel,
  Node,
  NodeContent,
  NodeHeader,
  NodeTitle,
} from "@gremorie/rx-ai";

const nodeTypes = { card: (props) => (

  <Node {...props} handles={{ target: true, source: true }}>
    <NodeHeader>
      <NodeTitle>{props.data.label}</NodeTitle>
    </NodeHeader>
    <NodeContent>{props.data.body}</NodeContent>
  </Node>
)};

export function Workflow() {
  const [nodes, , onNodesChange] = useNodesState(initialNodes);
  const [edges, , onEdgesChange] = useEdgesState(initialEdges);

return (

<div className="h-[480px] w-full">
<Canvas
        nodes={nodes}
        edges={edges}
        nodeTypes={nodeTypes}
        onNodesChange={onNodesChange}
        onEdgesChange={onEdgesChange}
      >
<Controls />
<Panel position="top-right">Workflow tools</Panel>
</Canvas>
</div>
);
}

API

<Canvas>

Encaminha todas as ReactFlowProps de @xyflow/react. O wrapper da Gremorie define estes defaults (qualquer prop que você passe os sobrescreve):

Renderiza um Background com bgColor="var(--sidebar)" para que o canvas combine com o shell ao redor.

children são renderizados dentro do ReactFlow. Use este slot para Controls, Panel, MiniMap, etc.

Composição

1. <Canvas> detém a superfície. Passe nodes, edges, nodeTypes, edgeTypes e os change handlers do xyflow.
2. Node types custom são componentes React que renderizam Node de @gremorie/rx-ai com seus handles.
3. <Controls>, <Panel>, <Toolbar> são children que ficam sobre o canvas.
4. <Connection> é a linha que segue o cursor enquanto o usuário arrasta a partir de um handle - passe-a via a prop connectionLineComponent do xyflow.

Variações

Viewer read-only

Para visualizar um fluxo estático (por exemplo, um trace de agente), desabilite as interações.

<Canvas
  nodes={trace.nodes}
  edges={trace.edges}
  nodesDraggable={false}
  nodesConnectable={false}
  elementsSelectable={false}
>
  <Controls showInteractive={false} />
</Canvas>

Editor com connection line custom

Combine com Connection para um preview de conexão no tema da Gremorie.

import { Connection } from '@gremorie/rx-ai';

<Canvas
  nodes={nodes}
  edges={edges}
  connectionLineComponent={Connection}
  onConnect={onConnect}
>
  <Controls />
</Canvas>;

Com minimap e overlay de panel

import { MiniMap } from '@xyflow/react';

<Canvas nodes={nodes} edges={edges}>
  <Controls />
  <Panel position="top-left">
    <p className="text-xs font-medium">Agent graph</p>
  </Panel>
  <MiniMap pannable zoomable />
</Canvas>;

Acessibilidade

• Keyboard: o xyflow traz um modelo de teclado documentado - Tab foca o canvas, depois as setas movem os nós selecionados; Backspace / Delete os removem. A caixa de seleção ainda exige input de ponteiro. Para paridade total de teclado, forneça atalhos no nível do Panel.
• Focus visible: o xyflow expõe seu próprio focus ring no canvas. Não sobrescreva outline: none na raiz.
• Reduced motion: as animações de pan e zoom respeitam prefers-reduced-motion via o tratamento interno do xyflow. Animações de edge custom (por exemplo, a classe animated do Connection) devem ser envolvidas nos seus próprios overrides de @media (prefers-reduced-motion: reduce).
• Screen readers: os nós são renderizados como DOM puro. Garanta que o conteúdo de cada nó tenha texto significativo (não só ícones) e adicione aria-label aos children interativos dentro do Node.

Relacionados

• Node - nó em formato de card usado dentro do Canvas
• Edge - componente de edge com tema
• Connection - linha de conexão em progresso durante o arraste
• Controls - controles de zoom e fit ancorados em um canto
• Panel - overlay flutuante ancorado a um canto do canvas
• Toolbar - barra de ações flutuante por nó