Pular para o conteúdo
Formulário

Tree

/componentes/tree.mdmarkdown cru, para quem lê com agent em vez de olho

Estado misto

  • Financeiro
    • Contas a pagar
    • Contas a receber
  • Operação
    • Expedição
    • Estoque

Busca que guarda o caminho

  • Operação
    • Estoque

Árvore de arquivos

  • src
    • index.ts
    • tree.tsx
  • package.json

Aberto: tree.tsx

Importar
import { Tree } from '@rivocode/ui'

Quando usar

A arvore sozinha, sem campo nem painel. Serve para navegador de pastas, para árvore de arquivos com o arquivo aberto em destaque, e para escolha em tela cheia.

Pai com parte das filhas marcadas fica no estado misto. Marcar o pai marca só as filhas habilitadas, e desmarcar também não mexe nas desabilitadas. A busca guarda o caminho até quem casou, senão o resultado aparece solto e ninguém sabe de onde veio, e ignora acento e caixa: sao acha São Paulo.

As setas do teclado andam pelas linhas que estão na tela, e não pela árvore inteira: a navegação segue o que o olho vê. Home e End levam à primeira e à última linha, e o Tab volta para a última linha que teve foco. Linha desabilitada não se escolhe, nem pelo clique nem pelo Enter ou pelo espaço.

O recuo

Cada nível recua 1,5rem, que é a seta mais o respiro dela: a seta do filho cai debaixo do ícone ou do nome do pai, e nunca na mesma coluna da seta dele. Cada grupo aberto desenha uma guia de 1px em border, descendo da seta do pai até o último filho, e é ela que faz o nível ser lido quando a lista é longa e o pai já saiu da tela.

A coluna do ícone vale por grupo de irmãos: quando um nó do grupo tem icon, os irmãos sem ícone guardam a coluna, e os nomes do grupo alinham. Um grupo sem ícone nenhum não guarda coluna vazia, mesmo que o pai tenha ícone: o recuo do nível já separa o filho do pai, e o quadrado vazio só tirava largura do nome num painel estreito.

A escolha

value e onValueChange, o mesmo par do TreeSelect (que é esta peça dentro de um painel) e o mesmo vocabulário do resto do catálogo. Os dois são opcionais: sem nenhum deles a árvore guarda a própria escolha, e defaultValue diz com que ela começa.

Eram obrigatórios, e com outro nome: trocar o painel pela árvore inline reescrevia o binding inteiro, e uma árvore que só queria abrir e fechar ainda pagava um useState para existir.

Sentido da escrita

Em dir="rtl" a árvore inteira vira. O recuo de cada nível cresce a partir da borda onde a leitura começa, a seta do galho aponta para o lado que ele abre, e → e ← trocam de papel: ← abre o galho e entra nele, → fecha e sobe para o pai. É o que o padrão WAI-ARIA de treeview pede, e a razão é o desenho: a tecla que abre é a que aponta para onde a indentação cresce.

A direção vem do RivoProvider, e não de um dir escrito à mão num elemento acima da peça. E o recuo é padding-inline-start, e não padding-left: com a propriedade física os três níveis paravam no mesmo ponto em rtl, a hierarquia sumia da tela e sobrava uma lista plana. Trocar só a tecla teria consertado o teclado para um desenho que continuava errado.

A linha diz mais que o nome

description é a segunda linha, menor e em fg-muted, embaixo do nome: "Vence dia 10", "3 arquivos". count é o número no canto da direita, em algarismos de largura fixa: as notas da pasta, os itens do centro de custo. Quem conta é quem chama; a peça só escreve. Os dois cortam com reticências e não empurram o recuo.

Os dois entram no nome falado da linha, na mesma ordem e com as mesmas vírgulas do pacote nativo: "Financeiro, 1 item, Centro 101, 12". O galho diz também quantas folhas tem, e com multiple quantas estão marcadas ("Financeiro, 7 itens, 2 escolhidos"), por labels.branch. Esse nome se monta do label de texto, ou do search quando o label é um nó; sem nenhum dos dois, a linha se anuncia pelo que mostra.

<Tree
  aria-label="Centros de custo"
  items={[
    {
      id: 'financeiro',
      label: 'Financeiro',
      description: 'Centro 101',
      count: 12,
      children: [{ id: 'pagar', label: 'Contas a pagar', description: 'Vence dia 10', count: 3 }],
    },
  ]}
/>

Árvore de arquivos

Quatro props fazem da mesma peça um explorador de arquivos, e nenhuma delas mexe no que a árvore já fazia:

  • icon no nó, no espaço de ícone da linha, forçado a 16px como em toda peça da casa. Pode ser um nó pronto ou uma função que recebe { open }: a pasta troca de desenho ao abrir sem ninguém controlar o estado dela. A função e não um par { open, closed } porque a mesma forma serve a folha (que ignora o argumento) e qualquer outro desenho que dependa do estado, e porque é a forma do icon no pacote nativo.
  • active, o arquivo aberto agora. Não é a escolha: sai em aria-current="true", pinta a linha com o fundo de selecionado e um traço na borda onde a leitura começa, e existe com ou sem value. É controlável (active e onActiveChange) ou solto (defaultActive), e o Tab entra na árvore por ele.
  • onActivate, abrir a folha: dispara no Enter e no duplo clique. Quando a árvore não escolhe (nenhum de value, defaultValue, onValueChange e multiple), dispara também no clique simples e no espaço, e o clique num galho abre e fecha o galho, como num explorador. Com escolha, o clique e o espaço continuam escolhendo, e o duplo clique não desfaz a escolha que o primeiro clique fez. Abrir sempre torna a folha ativa.
  • hasChildren e onLoadChildren, o galho sob demanda. O nó com hasChildren e sem children tem seta de galho; ao abrir, a peça chama onLoadChildren(node) e gira na linha enquanto a promessa corre. Quem chama põe os filhos em items: a peça não guarda cópia, então a árvore continua sendo o que items diz. Se a promessa rejeitar, a linha diz "Não carregou" com "Tentar de novo" ao lado, e a seta para dentro ou o Enter também tentam de novo. Cada galho é pedido uma vez; children: [] depois de carregar é pasta vazia, e não folha.
  • children: [] é sempre pasta vazia, carregada ou não: tem seta, abre e não se escolhe. Para a API que manda a lista vazia em toda folha, hasChildren: false faz folha.

Duas decisões sobre o galho que ainda não carregou. A busca não carrega nada: ela anda só no que já está em items, acha o galho pelo próprio nome e o mostra fechado. Carregar a árvore inteira a cada letra seria uma requisição por pasta, e quem precisa buscar em tudo busca no servidor e devolve a árvore filtrada. E ele não se marca: com multiple, a caixa dele fica desabilitada até os filhos chegarem, porque não há como saber quais folhas ela marcaria, e marcar o pai marca só as folhas já carregadas.

import { Tree, type TreeNode } from '@rivocode/ui'
import { FileText, Folder, FolderOpen } from 'lucide-react'
import { useState } from 'react'

const folder = ({ open }: { open: boolean }) => (open ? <FolderOpen /> : <Folder />)
const file = <FileText />

type Entry = { path: string; name: string; isFolder: boolean }

function toNode(entry: Entry): TreeNode {
  return entry.isFolder
    ? { id: entry.path, label: entry.name, icon: folder, hasChildren: true }
    : { id: entry.path, label: entry.name, icon: file }
}

function withChildren(items: TreeNode[], id: string, children: TreeNode[]): TreeNode[] {
  return items.map((node) =>
    node.id === id
      ? { ...node, children }
      : node.children
        ? { ...node, children: withChildren(node.children, id, children) }
        : node,
  )
}

export function ProjectFiles({
  list,
  onOpenFile,
}: {
  list: (path: string) => Promise<Entry[]>
  onOpenFile: (path: string) => void
}) {
  const [items, setItems] = useState<TreeNode[]>([
    { id: 'src', label: 'src', icon: folder, hasChildren: true },
    { id: 'package.json', label: 'package.json', icon: file },
  ])
  const [active, setActive] = useState<string | null>('package.json')

  async function loadChildren(node: TreeNode) {
    const entries = await list(node.id)
    setItems((all) => withChildren(all, node.id, entries.map(toNode)))
  }

  return (
    <Tree
      aria-label="Arquivos do projeto"
      items={items}
      active={active}
      onActiveChange={setActive}
      onActivate={(node) => onOpenFile(node.id)}
      onLoadChildren={loadChildren}
    />
  )
}

Os textos novos moram no mesmo labels: loading (o que o giro anuncia), loadError e retry.

Quando não usar

Para escolher um nó num campo de formulário (setor, categoria, centro de custo), use TreeSelect: é esta árvore dentro de um painel, com busca, e não ocupa a tela enquanto a pessoa preenche o resto. A árvore solta é para navegar pastas na própria tela.

A navegação do app, de página em página, é Sidebar, e não a árvore com active: o ativo daqui é o arquivo aberto numa ferramenta (aria-current true), e o da barra lateral é a página onde a pessoa está (page). Lista plana com o item aberto ao lado é ListDetail.

Lista de um nível só, sem pai nem filho, não pede árvore: escolher de uma lista longa é Combobox, e montar um conjunto vendo o que ficou de fora é TransferList.

No React Native

Traduz, e a regra sobrevive inteira: quem vale é a folha. Marcar um galho marca todas as folhas debaixo dele, e o que sai em onValueChange é sempre uma lista de folhas.

O desenho é que não porta. No web os níveis abertos aparecem ao mesmo tempo, um recuo por nível; a 390px o terceiro nível começa depois do meio da tela e o nome do nó cabe em quatro letras. A peça fica ilegível justamente onde ela é mais útil. Aqui é um nível por vez: tocar num galho empurra o nível de dentro, e o cabeçalho mostra o caminho ("Financeiro › Contas a pagar", cortado pela frente, porque o pedaço que importa é o último) e volta um nível.

Duas consequências do empilhamento. O galho tem dois alvos: tocar no nome entra, e a caixa ao lado marca o galho inteiro: com um alvo só não havia como marcar "Financeiro" sem visitar as sete folhas de dentro. E a caixa do galho usa o estado misto, como no web: com parte das folhas marcadas, ela desenha o traço e anuncia mixed, e tocá-la marca o galho inteiro. A conta exata não aparece na tela, como no web; ela vai no nome falado do galho ("Financeiro, 7 itens, 2 escolhidos"), porque é por ele que se entra.

Como árvore de arquivos, as mesmas props do web: icon no nó, active/defaultActive/onActiveChange, onActivate, hasChildren e onLoadChildren. Duas diferenças. O icon é a função ({ color, size }) das outras peças nativas, e não recebe open: o galho não abre no lugar, ele empurra o nível, então a pasta não tem desenho de aberta. E o gesto de abrir não é o duplo toque, que no celular é o gesto do leitor de tela e não da pessoa: sem escolha (value, onValueChange e multiple ausentes, que aqui deixaram de ser obrigatórios), o toque na folha abre; com multiple, a folha ganha dois alvos como o galho, a caixa marca e o nome abre; com escolha única, o toque escolhe e abrir é o toque longo, que o leitor de tela oferece como ação. O ativo não tem aria-current: o leitor de tela ouve labels.current ("aberto agora") como valor da linha. O galho sob demanda pede os filhos ao entrar, e o nível de dentro mostra o carregando, o erro com "Tentar de novo" ou o emptyMessage.

A linha diz mais que o nome: description é a segunda linha, menor, e count o número no canto da direita, os dois também na fala, com os mesmos nomes e a mesma frase do web ("Financeiro, 1 item, Centro 101, 12"). children: [] é pasta vazia, nos dois pacotes: entra-se nela e ela diz o emptyMessage. Para a API que manda a lista vazia em toda folha, hasChildren: false faz folha.

Fora, por decisão: filter (buscar dentro de árvore achata os níveis, e lista achatada com busca já é o Combobox), open/onOpenChange (não há aberto e fechado, há o nível onde o dedo está) e o label do nó, que aqui é string. Ele é montado dentro do rótulo falado e do caminho, e de um ReactNode não há como ler o texto de volta.

API

PropTipoPadrão
itemsobrigatória0.4.0TreeNode[]sem padrão
active

O id da linha ativa - o arquivo aberto agora -, para quem controla.

string | nullsem padrão
defaultActive

A linha ativa na primeira pintura, sem controlar.

string | nullsem padrão
defaultOpen

Os galhos abertos na primeira pintura, sem controlar.

string[]sem padrão
defaultValue

Os ids iniciais, quando a arvore controla o proprio estado.

string[]sem padrão
filter0.4.0

Filtra pela busca, mantendo o caminho ate quem casou.

string""
labels

Os textos da peca, para trocar o idioma: `expand` e `collapse` sao os nomes do botao que abre e fecha um ramo; `loading` o que o giro anuncia enquanto os filhos chegam; `loadError` o aviso na linha quando eles nao chegam; `retry` o botao ao lado dele; e `branch` o nome falado de um galho, com o total de folhas e, com `multiple`, quantas estao marcadas.

Partial<TreeLabels>sem padrão
multiple0.4.0

Sem isto, so uma folha por vez.

booleansem padrão
onActivate

Abrir a folha: o arquivo no editor, o registro no painel.

((node: TreeNode) => void)sem padrão
onActiveChange

Chamado quando uma folha vira a ativa, pelo mesmo gesto que chama `onActivate`.

((id: string) => void)sem padrão
onLoadChildren

Busca os filhos de um galho com `hasChildren` e sem `children`, ao abrir.

((node: TreeNode) => void | Promise<unknown>)sem padrão
onOpenChange((ids: string[]) => void)sem padrão
onValueChange((ids: string[]) => void)sem padrão
open

Ids dos galhos abertos, para quem controla.

string[]sem padrão
value

Ids marcados, quando quem usa controla o estado.

string[]sem padrão

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

@rivocode/ui, 149 peças no catálogo. Esta página é gerada dos mesmos arquivos que alimentam o design system, então ela não envelhece sozinha.

Feito por RivoCode.