As páginas sem tradução abrem em inglês e são identificadas como inglês.
Esta página é uma tradução automática da página em inglês, que prevalece. Machine-translated from the English page, which is authoritative.
Design do painel
O painel em / é construído sobre o design system da ClickHouse, o Interface Click, no tema escuro. Esta página explica de onde vêm a aparência e o comportamento, como alterá-los e as regras segundo as quais uma mudança no painel é verificada.
Click UI é a biblioteca de componentes
@clickhouse/click-ui (fixado exatamente em frontend/package.json) é uma dependência de runtime. src/main.tsx carrega diretamente seus tokens escuros e os padrões de página (o alias click-ui-styles em vite.config.ts) em vez de montar ClickUIProvider, cuja importação pelo barrel enviaria o CSS de todos os componentes e os dois temas; o provider de tooltip do Radix que os componentes do Click UI esperam é montado ali diretamente; index.html define data-cui-theme="dark". Os controles são componentes do Click UI, importados por subcaminho (@clickhouse/click-ui/Button), de modo que só entram no bundle os componentes que o painel importa, e os que apenas views carregadas sob demanda usam são carregados junto com essas views:
| Necessidade | Use |
|---|---|
| um botão | Button (type: primary, secondary, empty, danger; sempre passe htmlType) |
| um campo | TextField, SearchField, PasswordField, NumberField, TextAreaField, Select |
| uma caixa de seleção ou um switch | Checkbox, Switch (os rótulos são strings simples) |
| abas, um menu, um popover | Tabs (dê um nome ao Tabs.TriggersList), Dropdown, Popover (com os gatilhos do Loom abaixo) |
| uma tabela, um badge, um alerta, paginação | Table, Badge, Alert, Pagination, ProgressBar |
| um link de texto ou uma ação com aparência de link | Link (component="button" para uma ação; ui/ExternalLink para uma nova aba) |
| um ícone | Icon com um nome do Click UI, aria-hidden a menos que seja o único conteúdo |
Algumas primitivas do Loom em src/components envolvem o Click UI onde o Click UI 0.13 fica a desejar. Use-as, e não o componente do Click UI que fica por baixo:
| Primitiva | Envolve | Porque |
|---|---|---|
ui/Modal, ModalFooter |
Dialog |
o botão de fechar do Click UI recebe o nome do seu ícone ("cross"), seu overlay não tem z-index, e o foco só volta ao elemento que abriu o diálogo a partir de um Dialog.Trigger |
IconButton |
IconButton + Tooltip |
um controle só com ícone precisa de um nome e de um tooltip; o type="button" de um gatilho do Radix cai na prop de variante do Click UI |
ui/Menu: MenuTrigger, PopoverTrigger |
gatilhos do Radix | Dropdown.Trigger e Popover.Trigger do Click UI colocam aria-expanded em um div que os envolve e devolvem o foco a ele |
ui/AnchoredPopover |
Popover |
um link que abre um popover em um clique simples e é seguido em um clique com modificador: o gatilho do Radix só alterna em um clique que seu filho não impediu |
ui/Unavailable |
— | um controle indisponível por um motivo declarado: aria-disabled, seu tooltip e sua descrição |
ui/PageHeader |
— | a linha de título de cada página: um h1 de 20 px sem ícone, como os títulos de página do Click UI, o badge de escopo ao lado e as ações no final |
ui/ChoiceGroup |
RadioGroup |
o rótulo de grupo do Click UI não dá nome ao grupo, e o rótulo de um item que não é texto é anunciado como "[object Object]" |
ui/ExternalLink |
Link |
a prop icon do Click UI dá nome ao seu ícone ("popout"), lido depois do texto do link; este wrapper oculta o ícone e diz "(opens in a new tab)" |
ui/Tooltip (Tip) |
Tooltip |
um único formato de tooltip, no provider que main.tsx monta (os specs o recebem de src/test/rtl.tsx); o disabled do Click UI faz o Radix alternar entre controlado e não controlado, e um tip desligado ainda conta como aberto, então o próximo tip pula o seu atraso |
ui/TabTrigger |
Tabs.Trigger |
o Icon do Click UI é um bloco, então um ícone fica empilhado acima do rótulo sem um wrapper |
Toast (toast()) |
— | o Toast do Click UI não tem substituição por chave nem linha de request-id e seu botão de fechar se chama "cross"; o card do Loom usa os tokens de toast do Click UI, no canto inferior direito |
ConfirmDialog (confirmAction()) |
Modal + Button |
o ConfirmationDialog do Click UI dá foco ao botão de confirmar; o Loom dá foco a Cancelar |
ui/fieldError ({...fieldError(id, message)}) |
o error de um campo |
o Click UI desenha o erro como um <div> simples e não define aria-invalid nem aria-describedby; este helper liga a mensagem ao input |
ui/Alert |
Alert |
o Alert do Click UI coloca um role na raiz, mas o tipo de suas props não declara nenhum; um alerta ao vivo recebe role="alert" ou role="status", sem wrapper |
ui/DraftSearch |
SearchField |
uma caixa de busca sobre uma leitura do servidor que guarda o que é digitado para si e entrega à página o texto já estabilizado (após uma pausa, ou no Enter), de modo que uma tecla renderiza a caixa e não a página; uma mudança de key a esvazia |
ui/Stat |
BigStat |
um número em uma fileira deles: o BigStat pequeno com uma dica sob o valor, para a qual o BigStat não tem slot |
O Loom mantém alguns elementos próprios, sobre os tokens do Click UI:
Chip(o Click UI não tem chip de filtro),EmptyStateeSkeleton(nenhum existe no Click UI).Panel: o visual de card do Click UI com um slot de cabeçalho e um corpo com rolagem, que o contêinerPaneldo Click UI não tem.- A gaveta do inspetor de memória: uma folha de diálogo do Radix, porque o
Flyoutdo Click UI se reduz a uma faixa de hover em telas estreitas e não aceita ref. - Alternadores de disclosure: um botão nativo ou um
Buttonemptydo Click UI, comaria-expandede um chevron do Click UI, porque oCollapsibledo Click UI não definearia-expanded. - Gatilhos que mostram um avatar ou o nome de um namespace: botões nativos sobre tokens; o botão
emptydo Click UI é texto de link. - Campos de data e de data e hora (o "Valid as of" do grafo, o prazo de uma tarefa): inputs nativos
dateedatetime-localdesenhados com os tokens de campo do Click UI, porque oDatePickerdo Click UI não aceitanamenemidpara um rótulo e não tem hora. - A lista de repositórios da fonte do tracker: um input nativo dentro de uma caixa com estilo de campo que transforma cada entrada em uma tag removível, porque o Click UI não tem input de tags.
- Seletores de arquivo: um input nativo
fileoculto, aberto por umButtondo Click UI. Onde os arquivos também podem ser soltos (os diálogos de documentos), o botão fica emui/DropZone, um alvo de soltar tracejado (o Click UI não tem nenhum) com cor de destaque enquanto há arquivos sobre ele; sua dica some com um ponteiro grosseiro. - Um campo de id que sugere ids conhecidos e ainda aceita qualquer outro (o campo de usuário e agente do Assistant): um
TextFielddo Click UI com umdatalistnativo, porque oAutoCompletedo Click UI escolhe a partir da sua lista e não guarda texto livre. - O botão Ask AI abaixo de xl: o
Buttonsem moldura do Click UI desenhado com os tokens doIconButtonghost (.assistant-launcheremstyles.css), em vez de umIconButton: um único elemento em todas as larguras mantém o foco nele ao redimensionar, e a partir de xl o mesmo botão é umButtonsecondary com sua palavra, para a qual oIconButtonnão tem slot. Enquanto o painel está aberto, ele assume o visual pressionado a partir dos tokens:activedo seu tipo (o doButtonsecondary a partir de xl, o doIconButtonghost abaixo), já que oButtondo Click UI não tem estado selecionado. - "Go to Ask AI": um botão nativo estilizado como o skip link que ele segue, porque abre o painel em vez de se mover para uma âncora.
- O botão History do painel Ask AI enquanto o History é exibido: o
IconButtonghost do Click UI comaria-pressed, desenhado com os tokens:activedesse botão (.assistant-heademstyles.css), já que oIconButtondo Click UI não tem estado selecionado. - O "Ask" da opção Ask AI da busca: uma pílula sobre os tokens do
Buttonprimary (.search-ask), porque a opção de uma listbox não contém um botão. O Continue in chat do card de resposta é umButtondo Click UI com o papel de opção, de modo que Enter e as setas chegam a ele a partir do campo como chegam aos resultados abaixo dele; a opção para a qual as teclas moveram recebe o anel de foco (.search-continue). - Itens de navegação da barra lateral: âncoras desenhadas com os tokens
--click-sidebar-*do Click UI. OSidebarNavigationItemdo Click UI é umdivcujo rótulo pode conter um link, o que colocaria o estado selecionado nodive não no link. - A árvore de locais da Library: linhas desenhadas com os tokens de navegação da barra lateral e de linha de tabela do Click UI, porque a navegação da barra lateral do Click UI não tem aninhamento.
- Widgets específicos do Loom (o canvas do grafo, a grade e o quadro de tarefas, o quadro de padrões), com controles do Click UI dentro deles.
- A barra de lease de uma tarefa: uma barra de 56 × 4 px que passa para a cor de aviso com menos de dez minutos restantes. O
ProgressBarpequeno do Click UI tem uma só cor e uma linha de rótulo, e um lease prestes a expirar é um aviso.
Componente ou valores de design
Importe o componente do Click UI sempre que o elemento for esse componente: a mesma anatomia, o mesmo papel e o mesmo comportamento (teclas, foco, ARIA, portal, posicionamento). Onde o Click UI 0.13 erra o comportamento, envolva-o uma vez em components/ui/, com o comentário do wrapper citando a issue upstream, em vez de redesenhá-lo (ui/SplitButton: issue 1272 do ClickHouse/click-ui).
Desenhe um elemento em CSS do Loom somente quando ele não for um componente do Click UI (outra anatomia, ou nada no Click UI corresponde: uma linha de lista, um chip, um skeleton), e então pegue cada cor, padding, gap, raio e fonte dos tokens --click-* do componente que ele substitui, e um gap ou margem para o qual esse componente não tem token, da escala genérica --spaces-* do Click UI, em uma classe nomeada na camada de componentes de styles.css. Nada de px digitado à mão, e nada de valores arbitrários do Tailwind (px-[var(--click-…)]). Um tamanho manual é um tamanho medido, nomeado no comentário da sua classe. O comentário da classe cita o componente que ela substitui e por que o componente não serve. O CSS que alcança a marcação de um componente do Click UI ([data-testid=…], seus elementos filhos) pertence ao wrapper desse componente e é reverificado a cada release do Click UI.
Por quê: um componente importado traz seu comportamento de teclado e foco, que um redesenhado precisa reconstruir e acaba errando; um elemento desenhado com tokens custa só CSS, o que serve a um shell estático (um quadro de linha, um chip) em que o componente enviaria script à toa; e os tokens são o contrato estável do Click UI, ao contrário da sua marcação.
Estilos
- Ordem das camadas (inline em
index.html, antes de qualquer folha de estilo):properties, theme, base, clickui, components, utilities. O Click UI fica acima do reset do Tailwind e abaixo das utilities, então use em um componente do Click UI apenas utilities de layout (margin, width, posicionamento flex); uma utility de cor ou de padding sobrescreveria o Click UI. - Tokens em
src/styles.css: os nomes semânticos do Loom (--color-bg,--color-surface,--color-text-muted,--color-accent,--color-success, a escala tipográfica, os raios, as sombras) são definidos a partir das variáveis do Click UI, para os elementos próprios do Loom. Os componentes do Click UI leem diretamente as variáveis do Click UI. - Cores são variáveis do Click UI ou derivadas delas (uma tonalidade com
color-mix, umbg-x/15), e ostyles.cssnão redefine nenhuma variável do Click UI. O anel de foco é a cor de contorno do Click UI, 2 px com deslocamento de 2 px, em todo elemento focável: o Click UI desenha o anel de um botão tipado na cor do traço do próprio botão (o de um botão secundário tem 1.6:1, abaixo de 3:1) e não desenha nenhum em checkboxes, switches, abas, links e no botão de fechar do seu diálogo. Uma sobrescrita do anel fica fora de toda camada CSS, ao lado de*:focus-visibleemstyles.css, ou o anel sem camada prevalece; uma linha que atravessa uma caixa com recorte (uma aba, um item do contorno do Explorer, o cabeçalho e as linhas de uma raia de tarefas, as opções do seletor de namespace, os botões de grupo e o "Show all" de um grupo, a pré-visualização de texto da Library, que preenche seu painel) ou empilhada sem espaçamento (uma caixa de entrada) desenha seu anel por dentro, e uma caixa com recorte que contém outros controles (as facetas do Explorer, os filtros com rolagem de uma barra de ferramentas, o "Show all" de uma raia de tarefas, os botões de retirar e "Find public namespaces to join" do seletor) deixa 4 px de folga para eles.frontend/e2e/focus-rings.spec.tspercorre todas as páginas com Tab e falha diante de qualquer anel cortado por uma caixa. - Linhas de abas: o
styles.cssmantém cada rótulo de aba em uma única linha e deixa uma linha de abas mais larga que a página rolar na horizontal em sua própria caixa, com o anel de foco da aba desenhado por dentro dela. - Desabilitado com um motivo: o Click UI estiliza apenas um botão desabilitado nativamente;
ui/Unavailablemarca seu botão comdata-unavailable(com o tipo do botão), e ostyles.cssaplica a esse botão as cores de desabilitado do Click UI. - Camadas sobrepostas: o painel do assistente sobre a página em z-[15], a janela expandida também (seu scrim em z-[14]; o
<main>isola os z-indexes da própria página), a sobreposição do inspetor de memória em z-20 acima dele, os diálogos em z-50 (uma confirmação em z-[60]), os toasts em z-[65] e todo popper do Radix (menus, selects, popovers, tooltips) em z-[70]. - Tipografia: os tamanhos do Click UI, de 10 a 32 px: as legendas têm 12 px (
text-xs), o badge pequeno 10 px e o avatar pequeno 11 px; os títulos de página têm 20 px. Inter e Inconsolata, latin e latin-ext, são declaradas emstyles.csssob os nomes de família do Click UI.
O que o Click UI entrega
vite.config.tsaponta os mapas de bandeiras, logos e marcas de pagamento do Click UI para um módulo vazio (src/lib/emptyAssetMap.ts): oIcondo Click UI os importa por inteiro para resolver qualquer nome, e o painel desenha apenas ícones de interface. Assim, o Click UI entrega ~95 kB gz de script, em vez de ~325 kB.vite.config.tsreúne em um único chunkclickui(~64 kB gz) os módulos do Click UI que o shell importa de forma estática, e esse chunk é carregado por todas as páginas; o Rollup divide o restante (Select e sua lista ordenável, Table, Pagination) nas views lazy que os usam, e incorpora um chunk compartilhado de menos de 1 kB (uma primitiva comofieldError, que só as views lazy usam) a um chunk que é carregado junto com ele.npm run budgetfalha quando os scripts de boot passam de 198 kB gz.- O
Badgedo Click UI mede seu texto a cada renderização. Uma lista longa de badges memoriza suas linhas e passa a elas props estáveis, como fazMemoryCard, ou uma única mudança faz todas as linhas serem medidas de novo: um callback, um set ou um elemento criado durante a renderização é uma prop nova a cada vez, então a lista o cria comuseCallbackouuseMemo. Daí decorre onde fica o texto de busca de uma lista: sobre linhas memorizadas, a página mantém o texto, para que uma linha possa escrevê-lo (uma tag escolhida), e filtra as linhas carregadas por meio deuseDeferredValuedele, de modo que uma tecla pressionada pinta o campo antes de as linhas serem renderizadas de novo (Library, Profile, Audit log, Namespaces in your org, Repositories, Tasks; Memories aplica debounce à busca que envia). Sobre linhas não memorizadas, em que o texto já estabilizado inicia uma leitura no servidor, o campo é umui/DraftSearche uma tecla pressionada renderiza apenas o campo (Runs lê após uma pausa, Conversations ao pressionar Enter). src/lib/clickUiFixes.tsdá nome ao que o Select do Click UI 0.13 deixa sem nome em sua lista de opções: o campo de filtro, seu botão de limpar e o diálogo que contém ambos. Também mantém o foco do teclado durante o estadoloadingde um Button, que o Click UI implementa comodisablede que, por isso, joga o foco para a página: o botão pressionado recupera o foco quando é habilitado de novo, e um diálogo que ele abriu devolve o foco a ele (ui/Modal). Um botão que permanece na página enquanto sua própria leitura roda (Refresh, Load more, Search) é umui/BusyButton: ele mantém o foco o tempo todo e, quando a última página remove um Load more,lib/useLastPageFocuspassa o foco à primeira linha que essa página adicionou; se não houver, à última linha exibida; se também não houver, à busca da lista.
Acompanhar uma versão do Click UI
npm --prefix frontend i --save-exact @clickhouse/click-ui@<version>, e então execute as verificações do frontend abaixo. Confira novamente cada workaround na tabela de primitivos e em clickUiFixes.ts com as notas da versão: remova um workaround assim que o Click UI o corrigir. Um novo mapa de ícones, bandeiras ou logos no Click UI pode precisar ser adicionado ao alias.
Regras em relação às quais uma mudança é verificada
- Use o componente do Click UI, ou o primitivo do Loom acima, para todo controle. Uma imitação de botão, campo, diálogo, aba ou badge estilizada com Tailwind é um bug.
- Cores, raios, sombras e tamanhos de texto vêm de tokens: nada de
text-[13px],rounded-[6px], cor hexadecimal ou classe de paleta bruta em TSX. - Use capitalização de frase (apenas a primeira palavra em maiúscula) em todo rótulo, título e botão.
- O texto nomeia o que o usuário vê, em palavras simples. Em todas as páginas, o texto renderizado não nomeia nenhuma operação, caminho de API ou campo de consulta: o nome de uma operação que o leitor copia ou pesquisa (o tipo de um evento, a operação que o servidor informa, uma lista de nomes exatos) aparece somente em um painel de detalhes, em um campo mono, em uma lista
ExactNamesou em uma dica que insere o valor em tempo de execução, nunca em uma frase nem em um literal.views/copy.rules.test.tsverifica o texto literal em busca de nomes de operação e caminhos de API, e seu cabeçalho lista o que ele não lê; os campos de consulta ficam para a revisão; o nome de uma operação em mono dentro de uma frase ainda é prosa e, como o teste ignora texto mono, a revisão o detecta. A única exceção é o código que um desenvolvedor copia, na seção de configuração de SDK ou cliente de uma página (Tokens, "Your own bot" em Profile). Uma página nomeia uma variável de ambiente somente quando o leitor precisa pedir essa configuração a um operador pelo nome, depois do que o próprio painel oferece, e como um passo do operador: "an operator setsLOOM_Xto …"; caso contrário, diz que um operador desta implantação pode ativá-la. As páginas de operador (Health, a aba Health de um repositório, as páginas da plataforma, Settings › Models & keys e os cartões de inspeção do assistente) também podem nomear configurações, tabelas e workers, com replica, lease, extractor e embedder; nos demais lugares, o texto diz o que o usuário vê ("this file type can't be read"). Um só vocabulário, com cada termo explicado uma vez, onde aparece pela primeira vez (namespaces e compartilhamento): um namespace é a memória de um projeto ou de um agente; uma coleção é uma biblioteca de documentos, nunca chamada de namespace no painel; um repositório é código indexado; os lugares são o seletor de namespace, Namespaces in your org, Audit log, a Library e Repositories. - Uma página recebe o título com
PageHeader, que não leva ícone. Um painel, cartão ou seção de painel lateral recebe o título comSectionHeading(oTitledo Click UI, 14 px semibold)..section-label(12 px, esmaecido) rotula um grupo dentro de uma lista, menu ou barra lateral. - Um toggle mantém um único rótulo;
aria-pressedindica o estado. Uma escolha única entre algumas opções é umButtonGroup. - A dica de um campo é ligada ao controle com
aria-describedby. - Um
Alertrecebe sua introdução como<strong>emtext, não emtitle: o Click UI renderiza o título como um<h6>, o que quebra a ordem dos títulos. - Um botão primário por superfície. Os rodapés são alinhados à direita, com o secundário primeiro e o primário por último.
- Um controle indisponível que tem uma dica explicando o motivo usa
aria-disabled="true"em vez dedisabled, para que o motivo continue acessível. - Um controle dentro de uma página que o papel do chamador não pode usar permanece visível como
ui/Unavailable. O motivo éneedsRole(role, namespace)delib/namespaceRole.ts, oucallReason(op, …)delib/callReason.tspara uma op com restrição, que também informa quando o papel ainda não é conhecido ou cabe ao servidor decidir (o comentário de documentação lista os casos). Um controle cujo papel o painel não tem como saber mostra a linha "o servidor decide" e fica indisponível, exceto as escritas da Library em um namespace de memória, que permanecem disponíveis e deixam o servidor decidir. A seleção de uma lista, que contém apenas suas escritas em lote, aparece somente onde elas estão disponíveis (useRowSelectionhabilitado e as caixas de seleção renderizadas sob a mesma condição). - Um item de menu que um papel não pode usar é
aria-disabled, nãodisableddo Radix, que o removeria do foco do teclado, e seu motivo aparece uma vez abaixo dos itens:ui/GatedItem, ou umreasonem um item deui/RowMenu. Um botão de ícone usaui/GatedIconButton. - Estes são oferecidos somente onde o painel consegue saber que o token pode usá-los: a seção Sources da Library; em Repositories, as facetas Docs e Sources de um repositório e as fontes de registros de um tracker; os controles de mantenedor do cartão de um repositório (seu Settings, o Re-index e o Remove branch de um branch, e Add branch); e o Edit mapping, o Rotate e o Retire de um tracker. A aba Access do repositório mostra a um leitor seus controles de acesso com os respectivos motivos. A própria restrição de um namespace restrito (um token da organização que o nomeie e uma concessão direta) é verificada por suas configurações, seu limite de orçamento, pela aba Access de um repositório e por Refresh now; seus outros controles seguem o papel, e o servidor recusa um token que essa restrição não admita. O menu New do cabeçalho segue o papel que o painel conhece, e o servidor decide o resto. No namespace de um repositório, as escritas de memória de um membro (adicionar, e editar ou excluir uma linha) permanecem disponíveis seja qual for o papel, e o servidor verifica que a linha é do membro. Somente o que é da organização ou da plataforma, e não de um namespace, fica oculto para um papel que não pode usá-lo: as páginas da plataforma, as abas Workers, Operation mix e Projection failures de Health, Settings › Models & keys e a navegação do drawer de administração.
- Elementos semânticos antes de ARIA; um widget que precisa de um padrão WAI-ARIA (uma grid, um combobox) nomeia o padrão em um comentário.
- O texto mantém 4.5:1 e os anéis de foco 3:1, com três exceções que são valores do próprio Click UI dark: o texto de placeholder de um campo é 3.5:1, o título de uma etapa de onboarding incompleta é 2.6:1, e os limites dos controles (checkbox e radio 1.6:1, um campo 1.5:1, um switch 2.6:1) ficam abaixo de 3:1.
- As animações ficam em
styles.css, que as desativa sobprefers-reduced-motion: reduce, junto com as entradas de diálogo, popover, menu e tooltip do Click UI.
Listas, carregamento e navegação
- A cor carrega significado, nunca decoração. O status é um
Badgedo Click UI (success, warning, danger, info, neutral); o feedback é umAlert. Links, o anel de foco, a única ação primária, o tom de uma linha selecionada e os gráficos são os outros usos. Tags, agentes, chaves, contagens, títulos, ícones e timestamps permanecem neutros, e nada que não seja um aviso usa a cor de aviso. - Uma linha de lista é
ui/ListRow, nos tokens CardHorizontal do Click UI: o hover a tinge, a linha cujo detalhe está aberto recebe o traço ativo, e uma linha marcada recebe o tom de linha da Table do Click UI, embora seja a caixa de seleção que carrega o estado: o tom é discreto, e a Table do Click UI o aplica apenas à linha ativa. As tags sãoui/TagList(chips com contorno, três, depois "+N"); com um ponteiro grosseiro (coarse), as tags clicáveis de uma linha ficam em uma só linha e são truncadas, já que a área de toque de 44 px de cada uma ultrapassa sua caixa de 24 px e uma segunda linha ficaria sob a primeira, e o drawer as mostra por inteiro. Um agente é um badge neutro preenchido. Colunas de campos comparáveis (runs, usuários, auditoria) usam umaTabledo Click UI. Uma linha endereçada por uma chave (uma memória, uma seção de perfil) começa com a chave em mono de 12 px e coloca seu valor no corpo de 14 px, o inverso do título sobre a descrição do CardHorizontal: a chave é um identificador, e o valor é o que o leitor percorre. Uma linha de memória limita esse valor a duas linhas, já que uma linha cortava a maioria dos valores no meio da frase, e a lista pede amemory.listos 320 caracteres que duas linhas comportam em 1400 px de largura: uma linha com tags tem 126 px, 148 px abaixo de 640 px de largura, onde seus metadados ocupam uma linha própria. - Uma página de lista tem um único elemento fixo (sticky),
ui/ListToolbar: a busca, os filtros em vigor e a contagem em uma só linha de 48 px. As ações das linhas selecionadas ocupam o lugar dele na mesma linha, de modo que ele nunca cresce sobre as linhas. Títulos de seção dentro de uma lista não ficam fixos; uma coluna lateral ao lado da lista (a árvore da Library) pode ficar, pois não toma altura das linhas. - A paginação é
ui/ListPager, a Pagination do Click UI como barra completa, sob a lista: o intervalo, as páginas, um tamanho de página de 25/50/100 lembrado por visualização. Uma mudança de página move o foco para o topo da lista e anuncia a página. Um cursor sem total recebe "Load more"; resultados de busca ranqueados recebem "Show more". Uma lista lida por inteiro, mas longa, é desenhada aos poucos com "Show more" (lib/useShowMore); toda lista em um diálogo de membros que seja maior que um passo informa seu total. - O carregamento é
ui/Loadingouui/LoadingSkeleton, o loader do Click UI com um rótulo "Loading", ou um skeleton rotulado com o formato das linhas; nenhum aparece antes de 300 ms. Uma atualização mantém o que está na tela, marcado com aria-busy. UmSkeletonpuro fora deLoadingSkeletoné um bug (Loading.rules.test.tsverifica isso). Um loader não tem tempo mínimo na tela: ele é desmontado quando os dados chegam, e mantê-lo por mais tempo atrasaria os dados; a espera de 300 ms já evita que uma resposta rápida o faça piscar. - Ler algo mantém você onde está: um objeto relacionado abre no drawer, em um diálogo ou em um popover. Ir para outra ferramenta navega, adiciona ao histórico, e Voltar restaura a rolagem, o drawer aberto e o foco.
- O painel não tem atalhos de teclado e não mostra dicas de teclas: nenhum acorde global, nenhuma tecla de uma letra, nenhum chip de tecla, nenhuma tecla citada em um tooltip ou em
aria-keyshortcuts. Um widget mantém suas teclas padrão (as setas, Home/End, Enter, Space e Escape do padrão WAI-ARIA em um listbox, menu, tree, grid, tab list ou diálogo), o Enter de um campo de texto o envia, e toda ação é um controle visível. O campo Ask AI envia com Enter e adiciona uma linha com Shift+Enter; Enter escolhe a opção de busca destacada. - Os ícones são os do Click UI (
@clickhouse/click-ui/Icon), nunca um glifo de texto no lugar de um. - O horário de uma linha é
ui/ListTime(listTimeemlib/format.ts): "just now", "12m ago", "3h ago", "3d ago", depois "Sep 20" ou "Sep 20, 2025", em um<time dateTime>com o horário UTC em um tooltip. Um horário do servidor é lido comparseChTime, nunca comDate.parseounew Date(<string>), que leem um horário sem fuso como local (format.rules.test.tsfalha em qualquerDate.parse). - As ações por linha são
ui/RowMenu: o Dropdown do Click UI atrás de um botãodots-verticalsempre visível, chamado "Actions for", no extremo direito da linha; um item destrutivo é o item de perigo. No máximo uma outra ação fica em linha. Uma linha do conteúdo da linha pode apontar um link para o que ela resume (o resumo do guia em uma linha de namespace público abre o guia em Namespaces in your org), um .list-row-controlacima do botão de abrir; o menu então omite essa ação. - Uma lista sem linhas para mostrar é
ui/ListState:empty(oEmptyState: o que aparecerá ali e a única ação que o preenche, Connect an agent onde só um agente o preenche, "an operator …" onde só um operador pode, como as páginas descrevem; Repositories desenha seu próprioEmptyState, porque seus passos de primeiro uso ficam dentro dele),filtered("No documents match tag:billing" eClear filtersem uma só linha) ouerror("Couldn't load documents", a mensagem, o id da requisição e umRetrysecundário, nunca o estado vazio). - Um erro diz o que aconteceu e o que fazer, e não nomeia nenhuma causa da qual não tenha certeza.
humanizeError(lib/errorWords.ts, que dá a ordem em que uma linha é montada) redige toda falha: uma frase de abertura, as palavras do servidor e se deve tentar de novo, tirado do corpo (retryable,retry_after_s, a categoria) e nunca da frase de um código (paraSIGNED_IN_ELSEWHEREeANSWER_UNREADABLE, que o painel produz, vem do código); uma mensagem do servidor que já dá esse conselho é deixada para dá-lo. Um chamador com sua própria frase de abertura passabare, para que uma linha nunca leia "Couldn't delete x: Couldn't do that: …"; um chamador que apenas leu passaread, que remove "it may have been saved", o padrão seguro para uma escrita. Os toasts passam portoastError(context, e), outoastErrorLinepara um que monta sua própria frase (quanto de um lote foi concluído) com o erro redigido comobare, e uma leitura que falha diz o motivo ao lado de sua linha "Couldn't load" (errorLine). Uma escrita respondida comPUBLICATION_PENDINGfoi confirmada, e apenas listas e busca ficam atrasadas:toastErrora mostra como informação, cuja linha diz que a página ainda pode mostrar o estado antigo e que não se deve enviá-la de novo. A página da própria escrita também a trata como feita: o catch de um ponto de escrita chamacommittedAnyway(context, e)(lib/errorWords.ts, fora do chunk de boot), que emite o toast comotoastErrore retorna true para essa resposta (um diálogo que redige suas falhas em linha verificaisPublicationPendingprimeiro), e, em caso de true, segue como após um sucesso (fecha o diálogo, mantém a mudança otimista, lê a lista de novo), de modo que nada na tela convide a repetir. Renomear é a única exceção:memory.moveresponde isso antes de redirecionar ou apagar a chave antiga, então o formulário permanece aberto e diz que um segundo Rename conclui a movimentação. O Undo de uma exclusão queknowledge.restorerecusa por enquanto (BACKEND_UNAVAILABLE) volta em seu aviso. Uma linha própria de uma página sobre uma escrita confirmada, isoladamente, passa portoastCommitted, que lhe dá o id da requisição e o tempo de leitura de um erro; uma linha informativa própria de uma página sobre uma chamada recusada passa portoastWithId, que faz o mesmo, etoastErrorLineé sua forma com tom de erro.lib/errorWords.rules.test.tsverifica as frases de abertura e que as palavras de um erro terminem a linha em que são colocadas. Os códigos do servidor estão na referência de erros; os três que o painel produz sãoSIGNED_IN_ELSEWHERE(um login em corrida) eANSWER_UNREADABLE(readJson) emapi.ts, eSTREAM_ENDEDemapi/assistantChat.ts.npm run budgetverifica que o build mantém o chunk das mensagens chamadoerrorWords-*. - Uma lista de linhas é uma única parada de tab, por meio de
useRowNav(lib/useRowNav.ts) no contêiner das linhas:↑/↓movem,Home/Endsaltam,Enterabre,Spacealterna a caixa de seleção da linha; Escape pertence à página. O botão de abrir da linha carregadata-row-open, e o anel de foco é desenhado na linha (.list-row:has([data-row-open]:focus-visible)), nunca no botão. Somente os controles da linha atual (seus chips de tag, seu menu) são paradas de tab, depois de seu botão de abrir, e o Tab sai da lista a partir do último deles; os de todas as outras linhas ficam com tabindex -1, e focar um (por clique) torna sua linha a atual. As caixas de seleção nunca são paradas de tab (Space). Não há movimento de grade com Esquerda/Direita. Uma Table do Click UI cujas linhas abrem algo (Runs, a fila de revisão) também é uma lista de linhas: o botão de abrir carregadata-row-open, euseRowNavtrata seutrcomo a linha. Uma tabela cujas linhas apenas carregam ações (o Details de um evento de auditoria, o Delete de um guardrail) mantém uma parada de tab por ação, como qualquer tabela. A única exceção é a lista Tasks (views/tasks/TaskList.tsx): uma grid WAI-ARIA de faixas, onde Esquerda/Direita movem entre uma linha e os controles dentro dela. - Um agente é
AgentBadge: no máximo 180 px com reticências, o nome inteiro em um tooltip quando cortado. Outro nome de identidade (um autor, um id de usuário) é o mesmo badge comoNameBadge. - Um primitivo do Loom que traz um componente pesado do Click UI (
ListToolbar,ListPager,RowMenu,ListState) é importado pelo caminho, não decomponents/ui/index.ts, ou cai no chunk de boot de todas as páginas.
Antes de uma alteração ir para revisão
Toda alteração em páginas de lista é verificada com estes itens antes de ser revisada; cada linha é uma classe de defeito a que as páginas de lista estão sujeitas.
- Um servidor uma versão atrás: toda nova entrada de requisição é ignorada por ele (e citada em
ignored_args); a página continua funcionando com o que esse servidor responde (sem total, a primeira página de novo, correspondência exata). Teste com um servidor falso que ignore a entrada. - Maiúsculas e minúsculas: um filtro digitado corresponde em qualquer caixa, no servidor e no navegador; um valor enviado a um campo de correspondência exata é enviado como está armazenado. A única exceção é um agente digitado em Memories:
memory.listcompara agentes de forma exata, então um agente que a lista ainda não viu é enviado como foi digitado. - Estados: carregando, vazio, um filtro que não corresponde a nada, um erro e uma leitura ainda em andamento são cinco telas diferentes; a barra de ferramentas aparece em todas, e "nada corresponde" só é dito sobre uma leitura do filtro atual.
- O conjunto inteiro: um filtro, uma ordenação, uma contagem ou um selecionar tudo cobre o que o servidor guarda, ou diz o que cobre ("as 1,000 mais recentes").
- Foco: tudo que é desmontado enquanto tem o foco (um botão, uma barra, uma página) passa o foco para um lugar nomeado; uma mudança de página termina em um título visível.
- Celular: medido a 375 px com um ponteiro de toque (
hasTouch): nada cortado ou com largura zero (exceto as tags truncadas de uma linha: a gaveta as mostra por inteiro); alvos de 44 px; a primeira linha dentro do orçamento de chrome. - Primitivos, não cópias: uma segunda cópia de um hook, de um formato de hora ou de um padrão de estado vai para
lib/oucomponents/ui; um skeleton cru, uma cor hexadecimal ou um ícone de glifo é um bug. - Unicode: uma correspondência sem distinção de caixa normaliza os dois lados em um só lugar (
lowerUTF8do ClickHouse na linha e no valor pedido, nãolower, que só normaliza A–Z, e nem uma segunda normalização em Python); teste com um valor não ASCII. - Respostas tardias: toda leitura que uma página inicia (carregar, recarregar, Refresh, Retry, Load more) pode ser ultrapassada por uma mais nova; uma resposta para um escopo ou filtro que a página já deixou é descartada (aborte-a, ou verifique um carimbo de escopo).
- O que a alteração tocou: comentários, testes e documentação que descrevem o comportamento antigo são atualizados na mesma alteração.
Verificações
make linte o CI executam as regras de acessibilidade do Biome sobrefrontend/src(overrides embiome.json). Uma supressão informa a regra e o motivo.frontend/e2e/a11y.spec.tsexecuta o axe (WCAG 2.0–2.2 A e AA) em todas as rotas, nas larguras de desktop e de celular, e nos diálogos, menus e popovers do shell. Os specs do explorer também são executados em 1280×720.npm --prefix frontend run budgetlimita os scripts de boot, as folhas de estilo e o chunk de index;e2e/perf-budget.spec.tsee2e/route-budget.spec.tslimitam o tempo de renderização, as tarefas longas e a mudança de layout.