Grupos dentro de um diagrama

Um grupo é um retângulo com nome, dentro de um diagrama, que reúne algumas das caixas daquele desenho: “Experiência”, “Domínio”, “Dados”.

Ele pertence ao diagrama, e não ao modelo. A mesma caixa pode estar num grupo chamado “Dados” num desenho e em nenhum grupo noutro — porque agrupar é uma decisão de leitura, e leituras diferentes agrupam diferente.

Um exemplo

kind: diagram
id: containers
title: Reserva de Salas — Containers
level: container
scope: reservas
order: 20
neighbors: 1
relations: auto

groups:
  - id: experiencia
    name: Experiencia
    orientation: row
    match:
      tag: experiencia
  - id: plataforma
    name: Plataforma
    include:
      - ref: api
      - ref: sincronizador
    groups:
      - id: dados
        name: Dados
        match:
          shape: [database, queue]

O que isso desenha: uma banda Experiência com o painel; uma banda Plataforma com a API e o sincronizador; e, dentro dela, uma banda Dados com o banco e a fila.

Os campos de um grupo

Campo	Obrigatório	O que faz
`id`	sim	o identificador dentro daquele diagrama
`name`	não	o rótulo exibido. Sem ele, o próprio `id`
`orientation`	não	`row` faz a banda ler como uma linha; sem isso, as caixas empilham
`include`	não	uma lista de seletores — os mesmos de um diagrama
`match`	não	atalho para um `include` de uma cláusula só
`groups`	não	grupos aninhados

include e match fazem a mesma coisa; match existe para o caso comum de um critério único, e aceita tag, meta, level, shape e project.

Aninhamento, e quem reivindica primeiro

Grupos aninham, e a regra é: a banda mais interna reivindica primeiro, e os ancestrais herdam. Uma caixa que casa com Dados fica em Dados, e por consequência dentro de Plataforma.

Isso é o que permite escrever a banda de fora por seletor largo e a de dentro por seletor estreito, sem tirar uma da outra à mão.

Só quem está dentro da fronteira

Uma caixa trazida por neighbors — contexto mudo, fora da moldura — não entra em grupo nenhum. Se entrasse, o retângulo da banda a desenharia dentro de uma fronteira que a exclui, e os dois retângulos se contradiriam.

Quando usar `groupBy` em vez disto

groupBy: meta.dominio cria uma banda por valor distinto, sem você escrever nenhuma. Use quando:

o agrupamento é um dado que já está no modelo (o domínio, o time, o nível);
você quer que uma caixa nova entre na banda certa sozinha.

Use grupos escritos à mão quando o agrupamento é editorial — quando o nome da banda é uma explicação, e não um valor.

Os dois não convivem: quando há groups, o groupBy é ignorado.

Próximo passo

Etiquetas e metadados — os dois eixos livres do formato.