Escolha a superfície mínima útil para leitura
No aplicativo ilustrativo de trilhas, um cartão ajuda a decidir se vale abrir uma referência histórica. Comece com texto disponível, contexto de origem, data e link utilizável. A API retorna registros planos, não um modelo de cartão pronto, e não garante todos os campos escolhidos. Crie um pequeno adaptador entre os registros e a tela.
Trate a identidade separadamente do texto exibido. Um id presente pode ajudar a acompanhar um item, mas título ou trecho não substituem a identidade com segurança. Não una registros diferentes por falarem da mesma expressão. Preserve os dados originais para o adaptador sem expor credenciais ou detalhes internos de depuração no cartão.
Não adivinhe tipo ou título ausentes
Use kind válido quando disponível: post e comment permitem rótulos distintos. Se estiver ausente ou desconhecido, use algo neutro como Registro arquivado. Não classifique todo registro desconhecido como comentário nem sugira que um comentário isolado represente a conversa inteira.
Considere um caso de teste proposto com kind=comment, texto legível, sem título nem link utilizável. O cartão pode mostrar Comentário e Link de origem indisponível, seguidos do texto. Não precisa de título gerado ou URL inventada. Outro caso pode ter título longo: deixe quebrar em linhas ou ofereça expansão clara. São exemplos de teste, não registros cuja existência esteja sendo afirmada.
Trate o texto como conteúdo não confiável
Escape o texto com segurança antes de inseri-lo na interface. Preserve quebras de parágrafo relevantes, mas não trate conteúdo arbitrário como instruções HTML. Se adicionar Markdown depois, escolha e teste uma política restrita de renderização. Texto simples é uma primeira versão válida e evita prometer uma formatação não implementada.
Valide o link antes de torná-lo acionável e trate um valor ausente ou inutilizável como ausente. Identifique claramente o destino externo. Ofereça ações com rótulos legíveis, acesso pelo teclado e ordem de foco adequada. Uma dica flutuante sozinha não explica uma data ou link indisponível a todos os leitores.
Seja preciso sobre datas e contexto
Se houver data de criação utilizável, mostre seu significado e formatação de maneira consistente. Caso contrário, indique Data indisponível. Não copie a data da publicação-pai para um comentário: os conteúdos não necessariamente foram criados juntos. A data de consulta do aplicativo descreve a busca, não a idade da conversa original.
Quando parent_id ou link_id estiverem presentes, o agrupamento local pode conectar registros já recebidos. Isso não recupera ancestrais ausentes, estabelece uma conversa completa ou cria um filtro de consulta. A API atual não expõe filtros parent_id ou link_id. O cartão pode reconhecer a falta de contexto sem montar uma conversa fictícia.
Separe os controles da lista do adaptador
A paginação da lista deve ler pagination.has_more e respeitar o limite de páginas. Não habilite ou desabilite Mostrar mais apenas porque pagination.relation é eq ou gte: a relação descreve o total, não a continuação. Um total desconhecido ou expresso como limite inferior também não prova que os registros visíveis sejam inválidos.
Um data vazio numa resposta bem-sucedida pertence ao estado vazio da lista, não a um cartão de erro; custa um crédito de recuperação. Inclua na revisão proposta título longo, texto ausente, data ausente, link inválido e tipo desconhecido, e examine o comportamento em tela estreita. São verificações da implementação futura, não testes feitos por este guia. Volte a /pt/#field-notes para datas e estados.
