Canvas

Overview

Canvas é o container raiz dos workflow components. Wrapper sobre @xyflow/react com defaults otimizados pra agent workflows: pan-on-scroll (não drag), select-on-drag, no zoom-on-doubleclick, fit-view automático.

Os outros componentes da categoria Workflow (Node, Edge, Connection, Panel, Controls, Toolbar) só funcionam dentro de Canvas.

Anatomy

<Canvas nodes edges nodeTypes edgeTypes>
  ├─ <Controls />          ← zoom in/out/fit
  ├─ <Panel position>...    ← painel flutuante
  └─ <Toolbar isVisible nodeId>...  ← contextual ao node
</Canvas>

Backgrounds são adicionados internamente (cor --sidebar).

Usage

"use client";

import "@xyflow/react/dist/style.css";
import { Canvas } from "@kalvner/kds/ai/canvas";

const nodes = [
  { id: "1", position: { x: 0, y: 0 }, data: { label: "Receber prompt" }, type: "input" },
  { id: "2", position: { x: 220, y: 0 }, data: { label: "Buscar contexto" } },
  { id: "3", position: { x: 440, y: 0 }, data: { label: "Gerar resposta" }, type: "output" }
];

const edges = [
  { id: "e1-2", source: "1", target: "2", animated: true },
  { id: "e2-3", source: "2", target: "3", animated: true }
];

export function Workflow() {
  return (
    <div className="h-[600px] w-full">
      <Canvas nodes={nodes} edges={edges} />
    </div>
  );
}

Props

Canvas (Root)

Aceita todos os props de <ReactFlow>. Os mais comuns:

KDS aplica esses defaults; você pode override individualmente.

Subcomponents

Canvas é monolítico — não tem subcomponentes próprios. Os "filhos" canônicos vêm de outros primitivos do mesmo namespace:

• Node — vai em nodeTypes ou inline via custom render.
• Edge — vai em edgeTypes (Animated, Temporary).
• Connection — passe em connectionLineComponent.
• Controls — zoom UI dentro do Canvas.
• Panel — painel flutuante.
• Toolbar — toolbar contextual de um Node selecionado.

When to use

• Agent workflows visuais (n8n-style, Langflow, Flowise).
• Pipeline editors (input → process → output).
• DAG visualization.

When not to use

• Listas lineares — use Plan ou ChainOfThought.
• Decision trees curtas — use Accordion ou Collapsible.
• Charts de dados — use Chart.

Best practices

• Container com altura fixa. Canvas precisa de height definido (não auto) — sem isso, o ReactFlow não inicializa.
• Import o CSS. import "@xyflow/react/dist/style.css" no topo do arquivo é obrigatório.
• fitView garante que o conteúdo cabe no viewport ao montar.
• deleteKeyCode customizado evita perdas acidentais.

Accessibility

Related

• Node — entidade visual.
• Edge — conexão entre nodes.
• Controls / Panel / Toolbar — UI dentro do Canvas.
• @xyflow/react docs — biblioteca subjacente.