Sistema de Layout Mestre-Detalhe

O que Sistema de Layout Mestre-Detalhe faz?

Propósito

O Sistema de Layout Mestre-Detalhe (também conhecido como Painel Dividido ou UI de Lista-Detalhe) fornece um layout visual padronizado e um framework de interação para navegar em uma lista primária de itens (o painel "Mestre") enquanto exibe atributos abrangentes, ações contextuais e histórico profundamente aninhado para o registro atualmente selecionado em um espaço de trabalho adjacente e sincronizado (o painel "Detalhe").

Padrões mestre-detalhe são fundamentais para aplicações web de produtividade de alta eficiência, como clientes de e-mail, helpdesks de suporte ao cliente, visualizadores de negócios CRM, plataformas de revisão de código, logs de auditoria e consoles de recursos em nuvem.

Projetar uma interface Mestre-Detalhe eficaz requer estabelecer proporções espaciais precisas, contenção vertical independente (evitando rolagem global da página), estados de seleção visual claros, sincronização perfeita de múltiplos painéis e transições fluidas de viewport móvel de visão dividida lado a lado para navegação de pilha de painel único, tudo isso aderindo estritamente às diretrizes de acessibilidade WCAG 2.1 AA para gerenciamento de foco e navegação por teclado.

Casos de Uso

• Portais de Help Desk & Suporte ao Cliente: Navegar por uma lista de tickets abertos no painel mestre enquanto lê conversas completas de threads, histórico do cliente e notas internas no painel detalhe.
• CRM Empresarial & Pipelines de Vendas: Escanear contatos ou contas em um painel mestre enquanto inspeciona o histórico de estágios de negócios, atividades futuras e detalhes de contato no painel detalhe.
• Aplicações de Webmail & Mensagens: Revisar um feed de caixa de entrada na coluna mestre esquerda enquanto lê, responde ou arquiva a mensagem ativa no painel detalhe direito.
• Dashboards de DevOps & Inspetor de Nuvem: Filtrar instâncias de servidor, streams de log ou pipelines de implantação no painel mestre enquanto inspeciona métricas em tempo real, rastreamentos de erro e configurações YAML no painel detalhe.
• Sistemas de RH & Rastreamento de Candidatos (ATS): Navegar por candidaturas enquanto revisa currículos, classificações de entrevistadores e ferramentas de agendamento lado a lado.

Quando NÃO Usar

• Espaços de Trabalho de Dados Tabulares que Exigem Comparações de Múltiplas Linhas: Se os usuários precisam comparar dezenas de registros simultaneamente em múltiplos atributos estruturados, use data-table-ui-system.
• Quadros de Pipeline de Fluxo de Trabalho: Para fluxos de trabalho de colunas de status onde cartões são movidos horizontalmente através de estágios discretos de pipeline, use kanban-board-ui-system.
• Árvores de Documentos Hierárquicas: Para navegação de documentos profundamente aninhados em estrutura de árvore (por exemplo, árvores de diretório de sistema de arquivos), use tree-view-navigation-system.
• Assistentes Lineares Passo a Passo: Para formulários sequenciais de múltiplas etapas onde cada visão se baseia na anterior, use step-progress-system ou multi-step-form-implementation.
• Páginas de Destino Simples e Independentes: Para páginas de destino de marketing ou feeds de artigo lineares simples onde o conteúdo flui verticalmente em uma única coluna, use article-layout-system ou section-composition-system.

Entradas

1. Arquitetura da Informação & Esquema de Itens: Atributos a renderizar no cartão de item Mestre (por exemplo, Selo de Status, Título/Assunto, Metadados Primários, Timestamp) versus o espaço de trabalho Detalhe (Corpo Completo do Registro, Histórico de Atividades, Registros Relacionados, Barras de Ação Contextual).
2. Contexto do Shell da Viewport: Limites de layout fornecidos pelo shell da aplicação externa (dashboard-layout-system ou sidebar-navigation-system).
3. Preferências de Proporção de Largura do Painel: Requisitos de dimensionamento de coluna (por exemplo, Largura Fixa do Mestre 360px + Detalhe Fluido flex: 1, ou Divisão Percentual 35% / 65%).
4. Tokens de Design: Elevações de superfície, bordas neutras, indicadores de anel de foco e escalas tipográficas (accessible-color-system, elevation-and-depth-system, fluid-spacing-system).

Saídas

1. Especificação de Layout de Painel Dividido: Definições espaciais CSS Grid / Flexbox para proporções de painel fixas vs. fluidas, contêineres de rolagem vertical independentes (overflow-y: auto) e divisores visuais.
2. Seleção de Item Mestre & Blueprint de Estado Ativo: Especificações visuais para estados de não lido, hover, focado, selecionado (aria-selected="true") e caixa de seleção múltipla dentro da lista.
3. Hierarquia do Espaço de Trabalho Detalhe & Anatomia do Cabeçalho: Layout espacial para a barra de ação da visão detalhe (cabeçalho fixo, botão voltar, controles de status, gatilhos de ação primária/secundária) e abas/seções de conteúdo.
4. Modelo de Adaptação de Viewport Responsiva: Regras de transição de layout passo a passo alternando de visão de painel duplo em desktop/laptop para navegação de pilha de painel único com slides de painel animados em telas de tablet/mobile.
5. Modelo de Interação Acessível por Teclado & ARIA: Captura de foco, roving tabindex ou roteamento de foco APG Listbox, marcos ARIA (role="region", aria-controls) e notificações de status para leitores de tela via aria-live="polite".

---

Fluxo de Trabalho

1. Estabelecer o Contêiner de Tela de Painel Duplo

Construir o wrapper mestre-detalhe externo dentro do shell da aplicação (dashboard-layout-system):

• Bloqueio da Viewport do Contêiner: Definir o wrapper externo como display: flex; height: 100vh; max-height: 100vh; overflow: hidden; (ou ajustar dentro da área de conteúdo do dashboard pai) para travar a altura geral do layout e eliminar a rolagem da janela no nível do navegador.
• Grade de Colunas de Proporção de Divisão: Definir a proporção do painel dividido usando CSS Grid ou Flexbox:
  • Padrão Mestre Fixo (Recomendado para Caixas de Entrada/CRMs): grid-template-columns: minmax(300px, 380px) 1fr; (O painel Mestre permanece em uma largura de escaneamento confortável entre 300px e 380px; O painel Detalhe consome todo o espaço horizontal restante).
  • Padrão de Divisão Proporcional: grid-template-columns: 35% 65%; ou 40% 60% para ferramentas de inspeção densas.
• Separador Visual do Painel: Inserir uma borda sólida de 1px (border-right: 1px solid var(--border-subtle)) ou uma barra de divisão redimensionável acessível (accessible-split-pane-implementation) entre os painéis.

2. Projetar a Estrutura do Painel da Lista Mestre

O painel Mestre serve como o índice de escaneamento rápido para a coleção de registros:

• Região de Cabeçalho Fixo: Posicionar uma barra de controle de busca e filtro fixa no topo do painel Mestre (flex-shrink: 0; padding: 12px 16px; border-bottom: 1px solid var(--border-subtle); background: var(--surface-card)). Incluir um campo de busca rápida (search-interface-system), chips de filtro e gatilhos de ação em massa.
• Lista de Itens Rolável Independente: Envolver os itens da lista em um contêiner com flex: 1; overflow-y: auto; overflow-x: hidden; -webkit-overflow-scrolling: touch; (role="list" ou role="listbox").
• Anatomia do Cartão de Item Mestre:
  1. Linha Superior: Identificador Primário / Autor (font-weight: 600; font-size: 0.875rem; color: var(--text-primary)), Pílula/Selo de Status e Timestamp (font-size: 0.75rem; color: var(--text-muted)).
  2. Linha do Meio: Assunto ou Título do Item (font-weight: 500; font-size: 0.875rem; color: var(--text-primary); text-truncate: 1 line).
  3. Linha Inferior: Trecho ou Texto de Pré-visualização (font-size: 0.8125rem; color: var(--text-secondary); line-clamp: 2), Tags/Categoria e Avatar do Responsável (user-avatar-system).
• Regras de Estilização de Estado:
  • Estado Não Lido / Não Processado: Título em negrito com uma dica visual sutil (por exemplo, ponto de destaque primário de 8x8px à esquerda).
  • Estado de Hover: Destaque de fundo (background: var(--surface-hover); cursor: pointer).
  • Estado Ativo / Selecionado: Fundo de superfície ativo distinto (background: var(--surface-active-subtle)), uma faixa indicadora de destaque primário sólida de 3px na borda esquerda (border-left: 3px solid var(--brand-primary)) e aria-selected="true".
  • Estado de Foco Visível: Contorno de foco altamente visível (outline: 2px solid var(--focus-ring); outline-offset: -2px).

3. Construir a Estrutura do Painel do Espaço de Trabalho Detalhe

O painel Detalhe renderiza o contexto completo e o espaço de trabalho do registro ativo:

• Exibição de Estado Vazio: Quando nenhum registro é selecionado no painel mestre, exibir um estado vazio acessível (empty-state-system) no painel detalhe com um ícone sutil, título claro ("Nenhum registro selecionado") e dica útil ("Selecione um item da lista para ver os detalhes").
• Barra de Ação Detalhe Fixa: Renderizar uma barra de cabeçalho superior persistente dentro do painel detalhe (position: sticky; top: 0; z-index: 10; display: flex; align-items: center; justify-content: space-between; padding: 12px 24px; border-bottom: 1px solid var(--border-subtle); background: var(--surface-card)):
  • Gatilho Voltar Mobile: Incluir um botão oculto no desktop "Voltar para a Lista" (<button class="mobile-back-btn">← Voltar</button>).
  • Identificação do Registro: Resumo do ID/Título do Registro (font-weight: 600; font-size: 1rem).
  • Controles de Ação: Botões de ação primários (por exemplo, "Responder", "Editar", "Atribuir", "Excluir") estilizados usando button-and-action-system.
• Região de Rolagem de Conteúdo Independente: Envolver o corpo principal do conteúdo detalhe em um contêiner de rolagem (flex: 1; overflow-y: auto; padding: 24px).
• Layout do Conteúdo Detalhe:
  • Seção de Cabeçalho: Título do Registro H1, Selo de Status, Grade de Metadados (Data de Criação, Autor, Prioridade, Responsável).
  • Área do Corpo Principal: Descrição completa, mensagem de thread HTML ou bloco de código de configuração.
  • Subseções com Abas: Usar abas (tab-ui-system) para separar "Histórico de Atividades", "Anexos", "Logs de Auditoria" e "Registros Relacionados".

4. Implementar Navegação de Pilha Responsiva para Mobile & Tablet

Em telas mais estreitas que 768px (ou 1024px para aplicativos densos), exibir painéis lado a lado resulta em texto ilegível e apertado e botões compactados. Transformar o layout em um modelo de pilha de painel único:

• Visão de Painel Único Mobile: Renderizar apenas um painel por vez com largura total da viewport (width: 100%).
• Máquina de Estado de Navegação:
  • Estado A (Mestre Ativo): O painel da lista Mestre ocupa 100% da largura. O painel Detalhe está visualmente oculto (display: none ou traduzido para fora da tela com transform: translateX(100%)).
  • Estado B (Detalhe Ativo): Quando o usuário toca em um item mestre, alternar as viewports. O painel Detalhe ocupa 100% da largura e o painel Mestre está oculto.
• Botão Voltar Mobile: No Estado B, o painel Detalhe exibe um botão "Voltar para a Lista" proeminente no canto superior esquerdo. Tocar nele redefine a máquina de estado de volta para o Estado A e retorna o foco do teclado para o item da lista mestre selecionado anteriormente.
• Animação da Viewport: Usar transições de deslizamento suaves (view-transitions-implementation ou transformações CSS horizontais transform 0.25s ease-in-out) para reforçar a orientação direcional (deslizar para a esquerda para detalhes, deslizar para a direita de volta para a lista mestre).

5. Garantir Foco Acessível & Interação com Leitor de Tela

• Marcos & Funções de Região ARIA: Atribuir role="region" aria-label="Lista de Itens" ao contêiner do painel Mestre e role="region" aria-label="Espaço de Trabalho de Detalhes do Item" ao contêiner do painel Detalhe.
• Listbox / Marcação de Seleção: Se a lista mestre se comporta como um widget de seleção única, aplicar role="listbox" aria-label="..." à lista e role="option" aria-selected="true|false" aos itens da lista. Alternativamente, usar <nav> padrão com aria-current="page" ou aria-current="true".
• Gerenciamento de Foco na Seleção de Registro: Quando um usuário seleciona um item mestre usando teclado ou ponteiro:
  • Manter o foco do teclado dentro da lista mestre se o usuário estiver escaneando rapidamente com teclas de seta (Up / Down).
  • Atualizar o DOM do painel Detalhe assincronamente e anunciar o carregamento do registro via uma região de status aria-live="polite": "Ticket #1042 carregado: Erro de processamento de pagamento".
  • Quando o usuário pressionar Enter ou Tab a partir de um item de lista selecionado, mover o foco perfeitamente para a ação primária do painel Detalhe ou cabeçalho H1 (tabindex="-1").
• Captura e Restauração de Foco na Viewport Mobile: Ao alternar para a visão Detalhe no mobile, mover automaticamente o foco para o Botão Voltar Mobile ou Cabeçalho Detalhe. Ao retornar para a visão Mestre, restaurar o foco para o item mestre que estava ativo anteriormente.

---

Regras de Decisão

Layout do Painel & Estratégia de Divisão

Largura da Viewport	Padrão de Layout Recomendado	Largura do Painel Mestre	Largura do Painel Detalhe
Desktop Largo (>1280px)	Visão de Painel Duplo (ou 3 Painéis com Barra Lateral)	Fixo 360px - 400px	Fluido flex: 1 (min-width: 600px)
Desktop Padrão (1024px - 1279px)	Visão de Painel Duplo	Fixo 320px - 350px	Fluido flex: 1 (min-width: 480px)
Tablet (768px - 1023px)	Painel Duplo Estreito OU Pilha de Painel Único	Fixo 280px - 300px (ou Recolhível)	Fluido flex: 1
Mobile (<768px)	Visão de Pilha de Painel Único	100% (Estado A)	100% (Estado B)

Seleção da Lista Mestre vs Modelo de Foco

• Seleção Automática ao Focar (Escaneamento Rápido): Pressionar as teclas de seta Up ou Down muda imediatamente a seleção ativa e atualiza o painel Detalhe em tempo real. Recomendado para leitura de e-mail, auditoria de log e triagem de tickets de alto volume.
• Seleção Explícita por Ação (Pressionar Enter / Clicar): Navegar pelos itens mestre com teclas de seta move um anel de foco visual sem atualizar o painel Detalhe. O painel Detalhe é atualizado apenas quando o usuário pressiona explicitamente Enter, Espaço ou clica. Recomendado quando carregar registros detalhados envolve requisições de API de rede pesadas ou edições de estado de formulário.

---

Restrições

• Acessibilidade (WCAG 2.1 AA):
  • SC 2.1.1 Teclado: Os usuários devem ser capazes de rolar itens mestre, selecionar registros, navegar para o espaço de trabalho detalhe, acionar ações e retornar à lista mestre usando apenas controles de teclado.
  • SC 2.4.7 Foco Visível: Itens mestre ativos e focados devem apresentar um anel de foco sem cortes com uma relação de contraste de no mínimo 3:1 contra o fundo.
  • SC 4.1.2 Nome, Função, Valor: Itens mestre devem comunicar explicitamente seu estado ativo/selecionado para a tecnologia assistiva via aria-selected="true" ou aria-current="true".
  • SC 2.5.8 Tamanho do Alvo: Os alvos de toque em itens da lista mestre e botões de ação detalhe devem fornecer uma área de alvo mínima de 24x24px (44x44px preferido em telas touch mobile).
• Contenção de Layout & CLS: O

...

[truncado para tradução]