Tree
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
- docs
- package.json
Aberto: tree.tsx
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:
iconno 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 doiconno pacote nativo.active, o arquivo aberto agora. Não é a escolha: sai emaria-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 semvalue. É controlável (activeeonActiveChange) ou solto (defaultActive), e oTabentra na árvore por ele.onActivate, abrir a folha: dispara no Enter e no duplo clique. Quando a árvore não escolhe (nenhum devalue,defaultValue,onValueChangeemultiple), 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.hasChildreneonLoadChildren, o galho sob demanda. O nó comhasChildrene semchildrentem seta de galho; ao abrir, a peça chamaonLoadChildren(node)e gira na linha enquanto a promessa corre. Quem chama põe os filhos emitems: a peça não guarda cópia, então a árvore continua sendo o queitemsdiz. 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: falsefaz 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
| Prop | Tipo | Padrão |
|---|---|---|
itemsobrigatória0.4.0 | TreeNode[] | sem padrão |
activeO id da linha ativa - o arquivo aberto agora -, para quem controla. | string | null | sem padrão |
defaultActiveA linha ativa na primeira pintura, sem controlar. | string | null | sem padrão |
defaultOpenOs galhos abertos na primeira pintura, sem controlar. | string[] | sem padrão |
defaultValueOs ids iniciais, quando a arvore controla o proprio estado. | string[] | sem padrão |
filter0.4.0Filtra pela busca, mantendo o caminho ate quem casou. | string | "" |
labelsOs 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.0Sem isto, so uma folha por vez. | boolean | sem padrão |
onActivateAbrir a folha: o arquivo no editor, o registro no painel. | ((node: TreeNode) => void) | sem padrão |
onActiveChangeChamado quando uma folha vira a ativa, pelo mesmo gesto que chama `onActivate`. | ((id: string) => void) | sem padrão |
onLoadChildrenBusca 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 |
openIds dos galhos abertos, para quem controla. | string[] | sem padrão |
valueIds 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.