praxis-table

Este documento e a referencia canonica da API JSON de praxis-table.

Summary

• Tipo documental: API reference canonica de contrato JSON.
• Evidencia canonica permanece governada no frontmatter para auditoria interna, sem expor paths na publicacao.
• Objetivo operacional: consulta rapida, auditavel e deterministica sob pressao.
• Resumo funcional herdado: Referencia canonica da API JSON do praxis-table.

Authoring contract

• O contrato primario de autoria do praxis-table e TableAuthoringDocument (kind: "praxis.table.editor").
• TableAuthoringDocument encapsula config + bindings e e o formato correto para editor visual, editor JSON, playground e fluxos de IA.
• TableConfig continua sendo a projeção canonica de runtime consumida pela tabela apos normalizacao e apply plan.
• meta.schemaId e meta.serverHash devem ser tratados como snapshot persistido de reconciliacao, nao como fonte primaria do runtime.
• Em contexto de praxis-crud, o authoring canonico de CrudMetadata pertence a @praxisui/crud, mesmo que o ponto visual de entrada continue sendo o icone da tabela.
• A superficie crud-integration-editor da tabela existe apenas para overrides operacionais de runtime e nao deve ser tratada como editor canonico do documento CRUD.

Scope and positioning

• Escopo: contrato JSON publico e limites de comportamento observavel.
• Fora de escopo: tutorial de adocao e walkthrough operacional detalhado.
• Posicionamento: referencia canonicamente governada para consumidores, arquitetos e mantenedores.

Collection export actions

• config.export.enabled habilita o pipeline nativo de exportacao da tabela e deve declarar os formatos permitidos em config.export.formats.
• O menu nativo de exportacao dispara exportAction e baixa o artefato retornado por PraxisCollectionExportService.
• Acoes em massa podem acionar o mesmo pipeline quando usam uma chave claramente de exportacao, como bulk-export ou export-selected, ou quando declaram exportFormat.
• Quando exportFormat e declarado, o formato precisa estar habilitado em config.export.formats; a tabela nao deve substituir silenciosamente por outro formato.
• Acoes genericas de download, como download-contract, permanecem no output bulkAction enquanto nao declararem exportFormat; isso evita capturar workflows corporativos que nao sejam exportacao tabular.
• Para exportar apenas a selecao, combine behavior.selection.enabled, config.export.general.scope: "selected" e uma bulk action visivel apenas quando selectedCount > 0.
• Quando config.export.general.scope e "selected", a exportacao sem linhas selecionadas e bloqueada com feedback de usuario em vez de gerar um arquivo vazio.

AI assistant entrypoint

• config.ai.assistant.enabled controla a visibilidade e o acionamento do assistente de IA embarcado na tabela.
• Ausencia do campo equivale ao comportamento historico: o entrypoint continua disponivel quando o adapter de IA da tabela estiver carregado.
• Use false para surfaces em que o host precisa remover a acao de IA por contrato publico, sem CSS contra classes internas da tabela ou do Angular Material.
• Ao mudar para false, a tabela fecha o assistente e remove a sessao contextual da tabela no registry compartilhado de IA.

Columns visibility dropdown

• config.toolbar.columnsVisibility.enabled controla a exibição do botão de visibilidade de colunas na barra de ferramentas.
• Por padrão, o botão de visibilidade rápida de colunas estará habilitado caso a toolbar esteja visível.
• Guardrail de UX: O último controle ativo no dropdown de colunas é automaticamente desabilitado quando apenas 1 coluna permanece visível, para impedir que o usuário oculte todas as colunas de dados da tabela.
• A desativação rápida de colunas reflete instantaneamente no layout visual (displayedColumns) e emite o evento configChange.

[!WARNING] Segurança Corporativa em Cenários Corporativos: A visibilidade de colunas via dropdown da toolbar é um recurso estritamente visual (layout de apresentação do lado do cliente). A ocultação de colunas não protege o dado sensível da transmissão de rede nem de inspeção técnica. Se determinados campos (ex: salários, senhas ou tokens) forem confidenciais para o nível de permissão do usuário atual, a restrição de dados deve ser realizada obrigatoriamente no lado do servidor (através da filtragem de propriedades nas APIs de CRUD e consulta), e nunca por meio de ocultação puramente visual na tabela.

Quick filters, unified filter region, and density

• Região única de filtros e dono explícito da consulta: Em telas de coleção com praxis-table, a própria tabela é a dona canônica dos filtros editáveis pelo usuário. Quando um campo (ex.: ativo / status) é governado por config.toolbar.filters.quickFilters[], evite duplicá-lo em alwaysVisibleFields (mantenha-o apenas nos escopos rápidos e opcionalmente na gaveta avançada selectedFieldIds).
• config.toolbar.filters.quickFilters[] materializa um seletor de escopo governado na toolbar. Cada item declara id, label, filter e icon opcional.
  • Um item com filter: {} representa o escopo "Todos" (sem restrição editável): acioná-lo limpa critérios editáveis anteriores em filterCriteria e em queryContext.filters não estruturais sem exigir reload da página.
  • Critérios booleanos explícitos false (ex.: { ativo: false }) são preservados integralmente na serialização remota e na avaliação local.
• Reconciliação de atalhos externos (queryContext.filters) vs. filtros estruturais (queryContext.meta):
  • Quando cards de KPI ou widgets externos aplicam um filtro editável via queryContext.filters (ex.: { ativo: true }), a tabela sincroniza advancedFilterValue, activeCrossFilters e activeQuickFilterId correspondente.
  • Se o operador alterar o escopo rápido (onQuickFilterChange), submeter/limpar os filtros da tabela (onAdvancedFilterSubmit / onAdvancedFilterClear) ou remover chips (onClearCrossFilter / onClearAllCrossFilters), a tabela reconcilia as chaves editáveis em queryContext.filters e emite queryContextChange e queryContextClear, impedindo que queryContext.filters órfãos continuem sobrescrevendo filterCriteria.
  • Filtros estruturais de contexto (queryContext.meta.relatedResource === true + parentFilterField, queryContext.meta.structuralFields, queryContext.meta.immutableFields ou queryContext.meta.structural === true) permanecem protegidos e nunca são limpos por ações de filtro do usuário.
• A composição adaptativa é responsabilidade do runtime: identidade, escopo, consulta e comandos se reorganizam pela largura do container da tabela. Dentro da consulta, campos editáveis formam a região de critérios; tags/atalhos salvos e comandos de gerenciamento formam um único cluster auxiliar. Em largura intermediária, os critérios e esse cluster completo compartilham o mesmo fluxo de quebra para aproveitar a faixa final sem criar uma linha órfã; em largura estreita, o cluster migra inteiro para a faixa seguinte. O host não precisa declarar coordenadas, breakpoints ou ordem visual adicional.
• Em superfícies de até 640px, os campos de consulta absorvem o espaço residual da própria linha até o limite do arquétipo; em 320px, entradas que não cabem em pares ocupam a largura útil integral. Presets e comandos curtos preservam largura intrínseca. Grupos binários de filtros rápidos equilibram as duas opções em até 540px, enquanto grupos maiores mantêm largura por conteúdo e overflow acessível.
• advancedFilters.settings.alwaysVisibleFields deve conter apenas critérios frequentes. Atalhos persistidos e comandos de gerenciamento não devem ser simulados como campos sempre visíveis nem reposicionados por seletores CSS internos do host.
• Cada item de tags[] deve declarar id, label e patch; as chaves e os valores de patch devem corresponder ao FilterDTO canônico. Tags fornecidas pelo host são acionáveis, mas não podem ser renomeadas ou excluídas como atalhos persistidos pelo usuário. A aplicação imediata é emitida por submit.
• config.toolbar.densityToggle.enabled materializa o seletor de densidade. values pode restringir as opções entre compact, comfortable e spacious.
• A alteração de densidade atualiza config.appearance.density e emite configChange, permitindo ao host decidir se a preferência será apenas transitória ou persistida.

Rich content convergence

• mapTableRendererToRichContentP0(...) e a ponte publica e restrita entre a taxonomia atual de cell renderers do praxis-table e o vocabulario compartilhado 1.0 de rich content em @praxisui/core.
• O subconjunto promovido nesta fase e intencionalmente pequeno: icon, image, badge, chip -> badge, avatar, progress e compose.
• Renderers interativos como button, toggle, menu, link, html e rating, alem do shell de detail/expansion, continuam table-owned e fora do contrato compartilhado 1.0 ate promocao semantica explicita.

Detail rich surfaces

• richContent incorpora um documento canônico praxis.rich-content@1.0.0 no corpo do registro selecionado. Use-o para callout, cartões semânticos, ícones, hierarquia tipográfica e ações sem duplicar essa taxonomia dentro de Table.

• O documento é validado integralmente antes do render. Cada actionId do conteúdo rico precisa existir em actions.row.actions[]; referências não declaradas ficam indisponíveis e não são despachadas. Ações declaradas são mediadas pelo host e seguem onRowAction; confirmação, capabilities e autorização continuam governadas pela Table e pelo backend.

• O editor visual de Detalhes delega richContent.document ao PraxisRichContentConfigEditor, incluindo tons neutral|info|success|warning|danger, bindings como row.note, mídia e botões. Tokens semânticos são o caminho recomendado; gradientes são estilo avançado e exigem prova de contraste nos temas suportados.

• actionBar entra na mesma fronteira canônica de detail row para agrupar ações contextuais host-mediated.

• actionBar é host-mediated:

  • o host resolve visibilidade, disabled e dispatch
  • o conteúdo visual de cada botão continua em PraxisRichContent

• timeline entra na mesma fronteira canônica de detail row ao lado de detailList e cardGrid.

• timeline e host-mediated:

  • a colecao vem de field ou items
  • cada entrada usa itemSchema para mapear title, subtitle, meta, icon e badge
  • o host resolve dados e fallback, mas o rendering cronologico final fica no PraxisRichContent

• behavior.detail.schemaContract.allowedNodes inclui detailList e cardGrid como surfaces canônicas de detail row.

• list continua sendo lista simples e nao aceita subtree declarativa por item.

• mediaBlock tambem faz parte da fronteira canonica do detail row, como primitive compartilhada para avatar/imagem, headline, subtitle, meta e trailing leve.

• detailList e host-mediated:

  • a colecao vem de field ou items
  • cada item usa itemSchema.nodes com RichBlockNode[]
  • o contexto do item expõe detailItem e detailIndex, com aliases opcionais via itemContext
  • itemActions permanecem no host, mas o conteudo visual do botao usa PraxisRichContent

• cardGrid tambem e host-mediated:

  • o host resolve o shell do grid
  • cada card e convertido para RichCardNode e renderizado por PraxisRichContent
  • o conteudo dos cards e limitado a RichPresenterNode | RichComposeNode

• mediaBlock e primitive compartilhada:

  • a tabela nao cria renderer proprio; ela delega diretamente para PraxisRichContent
  • o shape e voltado a avatar/imagem, headline, subtitle, meta e trailing leve

• O contrato alvo do primeiro corte de colecao rica e:

type DetailListNode = {
  type: 'detailList';
  title?: string;
  field?: string;
  items?: unknown[];
  emptyText?: string;
  itemKeyField?: string;
  itemSchema: {
    layout?: 'stack' | 'row' | 'card-list';
    nodes: RichBlockNode[];
  };
  itemContext?: {
    itemAlias?: string;
    indexAlias?: string;
  };
  itemActions?: Array<{
    actionId: string;
    label: string;
    icon?: string;
    payloadExpr?: string;
    visibleWhen?: JsonLogicExpression | null;
    disabledWhen?: JsonLogicExpression | null;
  }>;
};

• O contrato alvo do segundo corte de cards densos e:

type CardGridNode = {
  type: 'cardGrid';
  title?: string;
  subtitle?: string;
  columns?: 1 | 2 | 3 | 4 | 'auto';
  minCardWidth?: number;
  cards: Array<{
    id?: string;
    title?: string;
    subtitle?: string;
    content: Array<RichPresenterNode | RichComposeNode>;
  }>;
};

• O contrato alvo do terceiro corte de topo rico e:

type MediaBlockNode = {
  type: 'mediaBlock';
  avatar?: RichAvatarNode;
  title?: RichTextNode;
  subtitle?: RichTextNode;
  meta?: RichComposeNode;
  trailing?: RichBlockNode[];
};

• O contrato alvo do quarto corte cronologico e:

type TimelineNode = {
  type: 'timeline';
  title?: string;
  field?: string;
  items?: unknown[];
  emptyText?: string;
  itemSchema?: {
    titleField?: string;
    subtitleField?: string;
    metaField?: string;
    iconField?: string;
    badgeField?: string;
  };
};

type ActionBarNode = {
  type: 'actionBar';
  title?: string;
  emptyText?: string;
  actions: Array<{
    actionId: string;
    label: string;
    icon?: string;
    payloadExpr?: string;
    visibleWhen?: JsonLogicExpression | null;
    disabledWhen?: JsonLogicExpression | null;
  }>;
};

Support legend

• Active: suportado e observado no runtime atual.
• Partial: suporte parcial, com restricoes conhecidas.
• Declared-only: declarado em tipos/schema sem ligacao runtime confirmada.
• Schema-only: presente em schema/modelo sem confirmacao de execucao.
• Deprecated: mantido por compatibilidade legada com migracao prevista.

Contract classification

Canonical runtime paths (public contract)

Supported legacy paths

Nenhum path legado suportado foi identificado nesta revisão baseada em evidência textual preservada.

Canonical authoring envelope

type TableAuthoringDocument = {
  kind: 'praxis.table.editor';
  version: 1;
  config: TableConfig;
  bindings?: {
    resourcePath?: string | null;
    horizontalScroll?: 'auto' | 'wrap' | 'none';
  };
};

Internal-only paths

Experimental paths

Hypermedia detail semantics

• behavior.detail.source.mode = "hypermedia" começa sempre em _links.capabilities.
• surfaces, actions e canonicalOperations são lidos do ResourceCapabilitySnapshot retornado pelo backend.
• O primeiro corte monta um detail schema leve de resumo contextual; ele não embute execução inline de surface.open nem de workflow.
• O runtime faz prefetch por linha somente quando existe ao menos uma ação contextual configurada para projeção inline (display="icons"|"buttons"). Ações restritas ao menu preservam discovery sob demanda ao abrir o overflow; expansion hypermedia sem row actions continua resolvendo o contexto ao expandir a linha.
• actions.collection.discovery.enabled=false desliga somente a materialização automática de ações da coleção, incluindo create e workflows descobertos por HATEOAS/capabilities. Dados, schema, paginação, capabilities de leitura, ações explícitas da toolbar e ações por linha permanecem disponíveis. O default permanece habilitado quando o campo é omitido.
• actions.row.discovery.enabled=false desliga somente o enriquecimento automático de ações por linha. Use este modo para telas corporativas curadas, nas quais o host quer expor apenas actions.row.actions[] e evitar overflow/actions descobertas por HATEOAS/capabilities. O default permanece habilitado quando o campo é omitido.

Overview

Este arquivo foi adaptado para o padrao canonico atual sem remover conteudo tecnico existente. O conteudo detalhado anterior foi preservado para manter rastreabilidade historica e reduzir perda de contexto.

Public contract surface

Top-level configuration blocks

Nested configuration blocks

Quando actions.row.discovery.enabled esta ativo e o item publica capabilities CRUD canonicas, PraxisTable pode sintetizar entradas contextuais view, edit e delete. Quando o backend publica explicitamente operations["duplicate-draft"], a tabela tambem materializa duplicate-draft como operacao estendida de item. Essas entradas continuam sendo capabilities, nao workflow actions. Em uma tabela standalone, view/byId abre um Dynamic Form somente leitura por surface.open, usando a resolucao canonica do GET de item e do schema de resposta. O host deve fornecer o runtime de surfaces e autorizar essas leituras na sua politica de rede. Surfaces nomeadas preservam seus proprios ids, paths e schemas. Dentro de um contexto CRUD, view continua emitindo rowAction com actionConfig apontando para a capability; as demais capabilities delegadas e actions globais explicitas preservam seu fluxo. Injector e origem do foco acompanham apenas o contexto efemero de execucao, nunca o JSON authorado ou o payload HTTP.

Renderer defaults:

• columns[].renderer.type = "avatar" aplica columns[].align = "center" quando a coluna não declara alinhamento explícito. Esse default governa header e célula para manter foto/avatar centralizados em colunas dedicadas, preservando align, width e demais overrides declarados pelo host.

• columns[].renderer.type = "microVisualization" renderiza a visualização compacta declarada em renderer.microVisualization.visualization. O caminho preferencial é metadata-driven: campos de schema com presentation.presenter = "microVisualization" e presentation.visualization.surface = "table-cell" são convertidos automaticamente para esse renderer quando o tipo é seguro para tabela. O contrato visual e a normalização pertencem a @praxisui/core (PraxisPresentationVisualizationConfig); a tabela apenas hospeda o HTML compacto em célula, compose item ou renderer condicional.

• Em renderer.compose.items[] com type = "value", emphasis = "strong" representa o valor primário e emphasis = "subtle" o contexto de apoio. São os únicos níveis de hierarquia visual no item de texto; style arbitrário não integra o contrato de compose.

• Em tabela, campos *Expr da visualizacao, como valueExpr, targetExpr, segmentsExpr, toneExpr e fallbackTextExpr, sao resolvidos contra o contexto da linha antes de renderizar. Strings simples sao caminhos (row.slaAtual) e objetos seguem Json Logic. Para kind = "comparison", use points/pointsExpr; items fica reservado para visualizacoes orientadas a itens/etapas.

Toolbar contract

• Acoes globais de toolbar, row e bulk usam effects[].kind = "global-action" como envelope canonico de novo authoring. O campo globalAction plano continua aceito como fallback compatibilidade, mas nao e a superficie preferida.

• payloadExpr e escape avancado explicito de GlobalActionRef; visual authoring deve preferir payload estruturado e preservar payloadExpr existente apenas quando a mesma actionId for mantida.

• O bloco toolbar continua parte do contrato público principal.

• Use toolbar.actions[] para quick actions e toolbar.search para busca quando o host não injeta shell própria.

• Use toolbar.appearance para personalizar o chrome da toolbar por contrato governado. O runtime materializa variant, density, shape, divider e tokens como classes e CSS custom properties públicas; o host pode trocar aparência sem redefinir intenção, capability ou roteamento.

• Use toolbar.appearance.preset = "table-integrated" para compor toolbar e tabela como um unico bloco visual com tokens públicos estáveis, evitando CSS do host sobre classes internas como praxis-toolbar-stack-top ou table-stack-top.

• Tokens públicos suportados em toolbar.appearance.tokens: bg, fg, borderColor, borderWidth, radius, shadow, paddingBlock, paddingInline, minHeight, gap, actionsGap, dividerColor, actionSize, actionRadius, actionBg, actionFg, actionHoverBg, actionActiveBg, actionFocusRing, aiAccentColor, statusFg, titleFg, subtitleFg, iconFg, titleFontSize, subtitleFontSize, titleFontWeight, identityGap, identityFilterGap, identityMinHeight, identityMarginBottom, identityIconSize e identityIconRadius.

• Ações da toolbar e do estado vazio compartilham a geometria pública --praxis-action-control-*. actionSize e actionRadius continuam sendo overrides por tabela e têm precedência sobre os defaults compartilhados.

• Em coleções relacionadas graváveis, CREATE permanece estável na toolbar nos estados vazio e preenchido. O estado vazio gerado é informativo e não repete CREATE; behavior.emptyState.actions fica reservado a uma intenção contextual explícita e distinta, preservada exatamente quando declarada pelo host.

• Para localizar paths específicos de toolbar, complemente a leitura com o Appendix: JSON path index.

Messages contract

• O bloco messages governa copy operacional, affordances de confirmação, labels de toolbar e feedbacks corporativos.
• Prefira messages para texto/public contract; reserve providers globais para políticas de tenant.
• Para busca rápida de paths e defaults parciais, complemente a leitura com o Appendix: JSON path index.

Input bindings

Migration note:

• enableCustomization=false is now the canonical default.
• Hosts that need runtime authoring/settings must pass enableCustomization=true explicitly.

Output events

selectionChange is an active output for Dynamic Page composition. It emits { trigger, row?, selectedRows, selectedCount, tableId? } when the user changes row selection through table affordances.

When the table assistant is opened, selected rows are projected into a governed table-row-selection runtime digest with selectedCount, idField, selectedIds and a limited sanitized sampleRows array. This digest grounds LLM answers or requested actions about the selected records, but it does not route the user's primary intent and it is not a second source of business rules.

The assistant can also materialize declared runtime operations through tableRuntimeOperations. This is a reviewed, table-owned operation envelope, not a free-form component patch. Supported operations are:

Compound filter semantics should evolve through the canonical PraxisDataQueryContext.filterExpression proposal in projects/praxis-core/docs/rfc-query-context-filter-expression.md, not through implicit OR payloads in criteria.

When /schemas/filtered publishes x-ui.resource.capabilities, the table assistant includes a resource capability digest in its authoring contract. capabilities.filter=true only declares the flat /filter DTO/simple conjunction surface. capabilities.filterExpression=false tells the assistant to clarify or explain OR/nested boolean requests instead of silently applying a degraded filter.

External side channels

resourcePath mantém precedência canônica sobre analyticsProjection: quando ambos estão presentes, o runtime cancela o transporte analítico e materializa somente a coleção REST.

Host/runtime dependencies

Coverage matrix

Runtime coverage boundaries

• Cobertura consolidada com base em documentacao existente e source of truth declarado.
• Comportamentos fora de evidencia direta foram marcados como not-yet-verified ou Partial.
• Compatibilidade legada, quando detectada, foi separada em classificacao explicita.

Resolution model

Merge order

1. defaults base (createDefaultTableConfig + TableDefaultsProvider)
2. contrato recebido em @Input() config
3. hidratação opcional de config persistida (table-config:*) e inputs persistidos (table-inputs:*)
4. ajustes de runtime (ensureConfigDefaults, guards de recursos não suportados, reconciliação de modo de dados)
5. alterações vindas de editor/settings panel (applied$/saved$)

Fallback order

resourcePath explícito -> conexão persistida (CONNECTION_STORAGE) -> data local -> tabela sem fetch remoto.

Override points

• @Input() config, @Input() resourcePath, @Input() data
• edição via SettingsPanelService (config editor, quick connect, quick setup)
• persistência de host (ASYNC_CONFIG_STORAGE e CONNECTION_STORAGE)

Runtime normalization

• ensureConfigDefaults() preenche blocos ausentes sem sobrescrever intenção explícita do contrato.
• parseLegacyOrTableDocument() absorve payloads legados do editor e converte para o envelope canônico de autoria antes do apply plan.
• sanitizeExpansionDetailSchema() aplica contrato de nós permitidos e política de fallback.

Precedence rules

• input explícito de runtime tem precedência sobre persistência local.
• paths canônicos têm precedência sobre aliases internos remanescentes (__forceRemoteMode__).
• em behavior.detail, contrato inválido aplica fail-closed para detail row.
• behavior.detail.source.mode = "hypermedia" usa _links.capabilities como ponto único de entrada e não executa surface.open inline no primeiro corte.

Observação adicional:

• no primeiro corte, behavior.detail.source.mode = "hypermedia" usa _links.capabilities como ponto único de entrada, consome surfaces/actions/canonicalOperations do snapshot agregado e não executa surface.open inline.

Validation and error semantics

Validation model

Error semantics

Warnings cobrem preferências inválidas e ausência de tableId para persistência. Falhas de contratos de detail schema aplicam bloqueio local (detail row) sem derrubar renderização base da tabela.

Fail-open / fail-closed behavior

Invalid or unknown field handling

• Campos desconhecidos: comportamento depende da estrategia do componente (ignore, warn ou reject).
• Campos invalidos: podem gerar fallback, warning ou falha conforme implementacao.
• Registrar divergencias observadas em Known limitations and mismatches.

Runtime warnings vs hard failures

Detailed API

Preserved technical reference (normalized from previous revision)

Summary

Referencia canonica da API JSON do praxis-table.

• O componente consome TableConfig + inputs externos (resourcePath, data, tableId) e side-channels de integracao.
• Este documento cobre contrato, cobertura de runtime, precedencia, defaults, eventos e exemplos copiaveis.
• Fora de escopo: implementacao detalhada do host app, backend e UI de editores alem dos contratos que afetam runtime.

Support legend

• Active
• Partial
• Declared-only
• Schema-only
• Deprecated

Overview

praxis-table é uma superfície operacional para dados corporativos. Com uma declaração pequena, a aplicação consegue exibir dados reais, paginação, colunas, filtros, ações, mensagens e regras visuais sem reconstruir a tela a cada novo cenário. A primeira renderização pode nascer do recurso publicado pelo backend; os refinamentos podem vir da aplicação, do editor visual ou das preferências persistidas.

Em arquiteturas tradicionais, cada variação de colunas, ações e filtros costuma virar uma nova camada de HTML, estado e condicionais. Aqui, a estratégia é inverter esse custo: a mudança entra em uma configuração governada. Quando o requisito muda, a experiência evolui sem transformar cada ajuste em uma nova implementação de tabela.

Conceitos-chave:

• Uma declaração publicada define estrutura, dados e experiência.
• O backend pode descrever o recurso para que a tabela derive a primeira leitura.
• Dados, apresentação e interação ficam separados, mas evoluem no mesmo contrato.
• Regras condicionais governam estilos, visibilidade e renderização sem espalhar decisões pelo template.
• Fluxos remotos ou locais preservam paginação, ordenação e filtros de forma previsível.

Por que este componente é diferente

O valor da Table aparece quando a tela deixa de ser um template isolado e passa a ser uma superfície governada por contrato. Em tabelas convencionais, cada mudança de coluna, filtro, ação ou visual pede código e template; aqui, essas mudanças entram em uma configuração declarativa e o componente responde de forma consistente:

• A configuração da tabela governa visual, dados e regras sem espalhar decisões pelo template.
• Dados remotos e dados locais têm estratégias próprias, com impacto claro na experiência.
• O editor visual convive com a tabela renderizada para permitir autoria governada.
• Regras condicionais cobrem destaque visual, renderização e comportamento sem duplicar tela.
• Identidade estável permite persistir preferências e reconciliar instâncias com segurança.

O resultado é um componente "plataforma": cada bloco do contrato vira um módulo do componente, e as interações entre esses módulos permitem evoluir experiências corporativas sem transformar cada nova regra em uma nova implementação de tela.

Valor em uma leitura rápida

Uma tabela que vira plataforma. praxis-table transforma decisões declarativas em experiência: colunas, ações, filtros, mensagens e regras vivem no mesmo contrato operacional, pronto para dados remotos ou locais, sem retrabalho de template.

• Entrega rápida: ajuste comportamento e visual por configuração governada.
• Padrão de UX: regras, ações e mensagens consistentes entre telas.
• Escalável: regras e comandos estruturados permitem crescer a complexidade sem criar forks de tela.

Menos código de tela, mais contrato

Uma tabela que vira plataforma. Em vez de programar cada capacidade de tabela do zero, você ativa recursos nativos via contrato:

• Iteração sem código de tela: adicionar botões, trocar densidade, ajustar colunas, filtros e diálogos por configuração governada.
• Lógica desacoplada: destaque de linha, visibilidade de ação e variação visual ficam em regras condicionais, não em *ngIf espalhado.
• Ecossistema embutido: paginação remota, virtual scroll, reorder de colunas, exportação e praxis-filter avançado como capacidades prontas.
• Eventos estruturados: ações de linha, lote, toolbar, exportação e reordenação entregam intenções claras para a aplicação.
• Governança de estado: identidade estável organiza persistência, reconciliação e isolamento de instância.

Receitas de impacto

As receitas abaixo mostram capacidades que normalmente exigiriam código de tela, mas que a Table materializa a partir do contrato. Elas funcionam como portas de entrada para o leitor entender o valor antes de mergulhar na matriz completa da API.

1. Dashboard financeiro: prova computed + densidade + regra visual.
2. Micro-layout compose (CRM): prova poder de layout sem componente custom.
3. Backoffice seguro: prova bulk com travas de negócio e confirmação.
4. Rastreador de SLA: prova de regra temporal em JSON Logic + alerta visual declarativo.

Receita 1 - Dashboard Financeiro

{
  "appearance": { "density": "compact" },
  "columns": [
    { "field": "asset", "header": "Ativo" },
    { "field": "costPrice", "header": "Custo", "type": "currency", "format": "BRL|symbol|2" },
    { "field": "salePrice", "header": "Venda", "type": "currency", "format": "BRL|symbol|2" },
    {
      "field": "margin",
      "header": "Margem",
      "type": "currency",
      "format": "BRL|symbol|2",
      "computed": { "expression": { "-": [{ "var": "salePrice" }, { "var": "costPrice" }] }, "outputType": "number" }
    }
  ],
  "rowConditionalStyles": [
    { "condition": { "<": [{ "var": "computed.margin" }, 0] }, "cssClass": "row--danger" }
  ]
}

Receita 2 - Micro-layout sem scroll (compose)

{
  "columns": [
    {
      "field": "contact",
      "header": "Cliente",
      "renderer": {
        "type": "compose",
        "compose": {
          "layout": { "direction": "row", "gap": 8, "align": "center" },
          "items": [
            { "type": "avatar", "avatar": { "srcField": "photoUrl", "initialsField": "name" } },
            { "type": "value", "field": "name" },
            { "type": "badge", "badge": { "textField": "status", "variant": "soft" } }
          ]
        }
      }
    }
  ]
}

Receita 3 - Backoffice Seguro (ações em lote)

{
  "actions": {
    "row": {
      "enabled": true,
      "actions": [
        {
          "id": "approve",
          "label": "Aprovar",
          "action": "approve",
          "visibleWhen": { "===": [{ "var": "status" }, "PENDENTE"] }
        }
      ]
    },
    "bulk": {
      "enabled": true,
      "position": "toolbar",
      "actions": [
        {
          "id": "delete",
          "label": "Excluir selecionados",
          "action": "delete",
          "minSelections": 1,
          "requiresConfirmation": true
        }
      ]
    }
  },
  "messages": {
    "actions": {
      "confirmations": {
        "deleteMultiple": "Tem certeza que deseja excluir os itens selecionados?"
      }
    }
  }
}

Internal route global action

Configurações novas devem persistir a integração em effects[].globalAction. O runtime e os validadores também leem globalAction plano para documentos existentes, mas editores e AI manifest devem tratar esse campo como compatibilidade. O adapter da Table preserva payload/payloadExpr ao reabrir e re-selecionar a mesma actionId, e limpa payloads ao trocar de global action para evitar semântica cruzada.

{
  "actions": {
    "row": {
      "enabled": true,
      "actions": [
        {
          "id": "open-details",
          "label": "Abrir detalhe",
          "icon": "open_in_new",
          "globalAction": {
            "actionId": "navigation.openRoute",
            "payload": {
              "path": "/funcionarios/detalhe",
              "query": { "id": "${row.id}" },
              "state": { "source": "table", "selectedId": "${row.id}" }
            }
          }
        }
      ]
    }
  }
}

Receita 4 - Rastreador de SLA (tempo + alerta visual)

{
  "columns": [
    {
      "field": "ageDays",
      "header": "Dias em aberto",
      "computed": { "expression": { "daysSince": [{ "var": "createdAt" }] }, "outputType": "number" }
    }
  ],
  "rowConditionalStyles": [
    {
      "condition": {
        "and": [
          { ">": [{ "var": "computed.ageDays" }, 5] },
          { "!==": [{ "var": "status" }, "RESOLVIDO"] }
        ]
      },
      "cssClass": "row--danger text-bold"
    }
  ],
  "rowConditionalRenderers": [
    {
      "condition": {
        "and": [
          { ">": [{ "var": "computed.ageDays" }, 5] },
          { "!==": [{ "var": "status" }, "RESOLVIDO"] }
        ]
      },
      "tooltip": { "text": "SLA violado: ação imediata necessária", "position": "top" },
      "animation": { "preset": "warning-attention", "repeat": 3 }
    }
  ]
}

Essas quatro receitas cobrem o primeiro impacto. Cenários mais longos, como filtros avançados, logs massivos e overrides CRUD, pertencem à trilha de exemplos completos para não diluir a tese principal do runtime.

Dominando a cauda longa das interfaces

Em sistemas corporativos e aplicações complexas, o esforço de engenharia raramente está nos fluxos principais. O custo aparece na cauda longa dos requisitos de UI: variações de regras condicionais, formatações específicas, mensagens baseadas em estado e permissões de ação que mudam por linha, perfil ou contexto operacional.

praxis-table foi desenhado para reduzir drasticamente esse custo de manutenção. Em vez de espalhar condicionais pelo código da tela, o componente move essas decisões para uma configuração governada. Quem define a experiência ganha controle fino sobre leitura visual, ações, filtros e mensagens, com mais autonomia para produto e menos acoplamento no frontend.

Impacto prático:

• Menos ramificação de código no frontend.
• Mais autonomia para evoluir UX por configuração.
• Menor risco de regressão ao escalar regras condicionais.

Mapa de contrato e superfícies

O contrato governa 6 áreas principais:

A API detalha cada área e explicita onde o comportamento está ativo, parcial, declarado ou dependente de schema.

Arquitetura orientada a contrato (como funciona)

O componente separa estritamente dados, apresentação e interação, operando em dois eixos principais: motor interno da tabela e integrações externas.

Fluxo simplificado de execução:

1. Interpretação da configuração: resolve se a tabela usará dados remotos, dados locais ou estado vazio.
2. Montagem da superfície: renderiza colunas, toolbar, filtros e comportamentos visuais definidos pela configuração.
3. Pipeline de dados + motor de regras:
   • remoto: consulta a operação publicada pelo backend;
   • local: aplica paginação, ordenação e filtros no conjunto recebido;
   • regras: avalia destaque visual, visibilidade de ações e variações por linha.
4. Ciclo de eventos: emite ações estruturadas para que a aplicação reaja às intenções do usuário.

Integração com ecossistema Praxis (frontend e backend)

praxis-table compõe o ecossistema Praxis de ponta a ponta. O mapa de integração cobre frontend, contratos e backend.

Frontend (UI):

Backend e contratos:

No modo de edição, quando a aplicação habilita customização, a tabela exibe o editor visual para ajustar colunas, comportamento, aparência e regras sem editar código de tela. Esse editor compõe a configuração com consistência e evita divergência entre o que o usuário authora e o que a tabela renderiza.

Checklist de integração (pre-flight)

Antes de plugar a tabela em uma aplicação, valide estes pontos:

• A instância tem identidade estável para persistir preferências sem colisão.
• O modo de dados está decidido: recurso remoto ou conjunto local informado pela aplicação.
• As colunas descrevem o conjunto de dados real e usam apresentação coerente.
• Ações de linha, lote e toolbar estão alinhadas com os comandos da aplicação.
• Regras condicionais têm fonte clara e não ficam espalhadas pelo template.
• Aparência, mensagens e localização foram revisadas para evitar inconsistências entre padrões globais e comportamento esperado.

Top-level contract

O contrato principal e TableConfig (alias de TableConfigV2) com extensoes de runtime aceitas no JSON:

• Base tipada: meta, columns, columnProjection, behavior, appearance, toolbar, actions, export, messages, localization.
• Extensoes fora do tipo estrito: dialogs.confirm.delete, rowConditionalRenderers[], aliases legados de behavior.virtualScroll.* e chaves legadas de header em actions.row.*.
• Artefatos auxiliares fora do TableConfig: crud-overrides:<componentKeyId> e o envelope autorado TableAuthoringDocument, que carrega bindings.resourcePath e bindings.horizontalScroll. A chave operacional da linha pertence ao TableConfig em config.meta.idField.

Projeção governada de colunas

Quando columnProjection.source = "schema", a declaração explícita de columns é opcional. A lista estrutural de colunas é materializada em tempo de execução a partir de /schemas/filtered; a configuração declara apenas a seleção ordenada em columnProjection.include e as decisões editoriais pontuais em columnProjection.overrides, indexadas pelo nome canônico do campo:

{
  "columnProjection": {
    "source": "schema",
    "include": ["competencia", "salarioBruto", "salarioLiquido"],
    "overrides": {
      "salarioLiquido": {
        "sticky": "end",
        "width": "160px"
      }
    }
  }
}

Quando consumido dentro de <praxis-crud>, o contrato também auto-infere a schemaUrl de behavior.filtering.advancedFilters a partir de resource.schemaPath ou resource.path (normalizado para /schemas/filtered?path=/api/.../filter&operation=post&schemaType=request), eliminando URLs estáticas duplicadas nos arquivos de configuração.

O runtime reaplica os overrides após bootstrap e atualização do schema. Uma chave desconhecida não cria coluna, e field não pode ser alterado pelo override. Este contrato não cria “defaults da surface” paralelos: tipo, visibilidade, ordem e apresentação continuam pertencendo ao schema canônico; a página conserva apenas as decisões editoriais específicas da experiência.

Durante a renderização, columns contém a materialização completa somente em memória. Ao salvar, aplicar ou emitir configChange, o runtime compacta essa materialização novamente: a ordem e os campos canônicos formam include, as diferenças formam overrides e colunas computadas/client-owned sem equivalente no schema formam additions. Uma addition cujo field colida com o schema é ignorada; ela não pode sombrear a identidade canônica.

include é uma allowlist ordenada. Em recursos financeiros, pessoais ou regulados, ela deve ser preferida para impedir que um novo campo do schema passe a integrar a experiência sem decisão editorial explícita. A ausência de include significa “todos os campos que o backend marcou como visíveis”.

Coverage matrix

Resumo de cobertura por bloco:

Preserved source snapshot

Events

selectionChange is an active output for Dynamic Page composition. It emits { trigger, row?, selectedRows, selectedCount, tableId? } when the user changes row selection through table affordances.

Styling API

CSS vars principais

Host classes

appearance.density seleciona apenas o preset de defaults. appearance.spacing.* e defaults globais também alimentam tokens *-default. Hosts podem redefinir livremente os tokens finais sem depender de seletores internos, por exemplo --p-table-row-height, --p-table-header-height, --p-cell-padding, --p-actions-btn-size e --p-table-paginator-select-height. Em virtualização sem itemHeight explícito, o runtime deriva a altura da densidade efetiva.

DnD classes (globais)

Horizontal scroll classes

A superficie usa horizontalScroll com classes:

• scroll-auto
• scroll-wrap
• scroll-none

Em scroll-auto, o viewport e uma regiao focalizavel por teclado para que o scroll horizontal continue acessivel sem mouse, inclusive no Safari. O nome acessivel usa accessibility.ariaLabels.scrollViewport, depois toolbar.title e, por fim, o fallback localizado do runtime. scroll-wrap e scroll-none nao introduzem uma parada de tabulacao adicional.

Mobile card mode

appearance.responsive.mobile.cardMode: true materializa cada linha não virtualizada como um card rotulado quando a menor largura entre o viewport e o host da tabela entra em appearance.responsive.breakpoints.mobile. Isso inclui widgets redimensionados e painéis estreitos em desktop. Um host ainda sem medida usa o viewport como referência. A tabela continua sendo a fonte semântica e todos os campos permanecem no DOM; cada valor recebe o respectivo cabeçalho como rótulo visual. Até 480 px de área interna, rótulo e valor ficam empilhados. Essa adaptação não altera a política de horizontalScroll nem ativa cartões sem cardMode: true.

appearance.responsive.mobile.priorityColumns é uma lista ordenada de fields que aparecem primeiro no card. Campos não prioritários continuam disponíveis abaixo deles; o runtime não oculta dados silenciosamente. Tabelas virtualizadas mantêm o modo de rolagem horizontal, pois um card pode ter altura variável.

Row/cell conditional styling

• rowConditionalStyles aplica classes/estilo por linha.
• columns[].conditionalStyles aplica por celula.
• Para intenções semânticas cobertas pelo catálogo oficial, use surfacePresetRef, por exemplo { "id": "warning", "catalogVersion": "0.2.0" }. A versão 0.2.0 oferece success, warning, danger e highlight nos escopos de linha e célula.
• Fundo sólido determinístico sem color usa foreground acessível derivado no runtime; a cor derivada não é persistida no TableConfig.
• color explícito continua sendo intenção autorada e deve atingir contraste WCAG AA (4.5:1) contra o fundo sólido efetivo.
• O authoring bloqueia pares explícitos abaixo de AA. Para configuração legada ou manual que bypassou esse gate, o runtime substitui apenas o foreground renderizado por um fallback acessível e preserva o documento original para diagnóstico/correção governada.
• Hover e zebra não apagam uma superfície condicional. Seleção possui precedência explícita com seu próprio par --p-table-row-selected-bg/--p-table-row-selected-fg.
• Alpha, var(...), cssClass externa, gradiente e shorthand não determinístico exigem preview contextual e não devem ser declarados acessíveis apenas por validação estrutural. O fundo contextual fica adiado no HTML inicial. Após o render, o runtime aplica fundo e foreground no mesmo frame e emite evidência DOM derived-contextual somente quando uma transparência ou variável CSS puder ser composta até uma base opaca e reduzida a uma única cor sólida. Gradientes, imagens e composições sem base opaca permanecem unresolved-suppressed, sem pintar o fundo inseguro.
• Em CSP estrito, estilos condicionais inline são desativados e o runtime não faz reparos via CSSOM. Apenas um surfacePresetRef válido é convertido na classe privada correspondente; cssClass arbitrária falha fechado. Os nomes dessas classes são detalhe interno e não fazem parte do contrato de authoring.
• A observação runtime publica affordances.visualMaterialization.inlineStyle, governedClass e surfacePresetCatalog (ID, versão, tema, modo, escopos e presets instalados), sem expor nonce ou a política CSP bruta. O backend usa essa evidência somente para restringir o preview: estilos inline exigem inlineStyle=supported; presets exigem instalação compatível comprovada. Capability ausente, unknown, versão/escopo/preset divergente ou modo de tema ainda não certificado falham fechado.
• muted não integra o catálogo acessível: opacidade aplicada à linha pode compor com descendentes e invalidar o contraste. O modo high-contrast é observado pelo runtime, mas permanece não aplicável pelo authoring até ter evidência visual certificada; o catálogo 0.2.0 está certificado para light e dark.
• Quando a cor comunicar estado ou classificação de negócio, materialize também uma pista visível independente de cor, como marcador lateral, ícone ou label.

Examples

Minimal valid

{
  "appearance": { "density": "compact" },
  "columns": [
    { "field": "asset", "header": "Ativo" },
    { "field": "costPrice", "header": "Custo", "type": "currency", "format": "BRL|symbol|2" },
    { "field": "salePrice", "header": "Venda", "type": "currency", "format": "BRL|symbol|2" },
    {
      "field": "margin",
      "header": "Margem",
      "type": "currency",
      "format": "BRL|symbol|2",
      "computed": { "expression": { "-": [{ "var": "salePrice" }, { "var": "costPrice" }] }, "outputType": "number" }
    }
  ],
  "rowConditionalStyles": [
    { "condition": { "<": [{ "var": "computed.margin" }, 0] }, "cssClass": "row--danger" }
  ]
}

Typical/common

{
  "columns": [
    {
      "field": "contact",
      "header": "Cliente",
      "renderer": {
        "type": "compose",
        "compose": {
          "layout": { "direction": "row", "gap": 8, "align": "center" },
          "items": [
            { "type": "avatar", "avatar": { "srcField": "photoUrl", "initialsField": "name" } },
            { "type": "value", "field": "name" },
            { "type": "badge", "badge": { "textField": "status", "variant": "soft" } }
          ]
        }
      }
    }
  ]
}

Advanced

{
  "actions": {
    "row": {
      "enabled": true,
      "actions": [
        {
          "id": "approve",
          "label": "Aprovar",
          "action": "approve",
          "visibleWhen": { "===": [{ "var": "status" }, "PENDENTE"] }
        }
      ]
    },
    "bulk": {
      "enabled": true,
      "position": "toolbar",
      "actions": [
        {
          "id": "delete",
          "label": "Excluir selecionados",
          "action": "delete",
          "minSelections": 1,
          "requiresConfirmation": true
        }
      ]
    }
  },
  "messages": {
    "actions": {
      "confirmations": {
        "deleteMultiple": "Tem certeza que deseja excluir os itens selecionados?"
      }
    }
  }
}

Enterprise scenario

{
  "columns": [
    {
      "field": "ageDays",
      "header": "Dias em aberto",
      "computed": { "expression": { "daysSince": [{ "var": "createdAt" }] }, "outputType": "number" }
    }
  ],
  "rowConditionalStyles": [
    {
      "condition": {
        "and": [
          { ">": [{ "var": "computed.ageDays" }, 5] },
          { "!==": [{ "var": "status" }, "RESOLVIDO"] }
        ]
      },
      "cssClass": "row--danger text-bold"
    }
  ],
  "rowConditionalRenderers": [
    {
      "condition": {
        "and": [
          { ">": [{ "var": "computed.ageDays" }, 5] },
          { "!==": [{ "var": "status" }, "RESOLVIDO"] }
        ]
      },
      "tooltip": { "text": "SLA violado: acao imediata necessaria", "position": "top" },
      "animation": { "preset": "warning-attention", "repeat": 3 }
    }
  ]
}

Known limitations and mismatches

Compatibility and migration notes

• No corte beta que unificou o lifecycle operacional, consumidores que chamavam diretamente os helpers públicos do componente devem migrar canCancelRemoteLoad() para canCancelLoad() e cancelRemoteLoad() para cancelLoad(). Não há aliases paralelos.
• Paths e aliases legados continuam aceitos para compatibilidade (behavior.virtualScroll.*, chaves legadas de header em actions.row.*), mas novos contratos devem usar caminhos canonicos atuais.
• O side-channel de overrides CRUD (crud-overrides:<componentKeyId>) nao faz parte do TableConfig; mantenha migracao/backup dessa chave separado do payload principal.
• Para regex em regras, a forma canonica persistida e infixa (field matches value); matches(field, value) permanece como legado suportado.
• O editor manual de regras da tabela autora apenas JSON Logic.
• Se houver comportamento divergente entre schema e runtime, priorize as indicacoes desta pagina em Known limitations and mismatches e mantenha has_known_mismatches=true no frontmatter enquanto a lacuna existir.

Source references

• projects/praxis-table/src/lib/praxis-table.ts
• projects/praxis-table/src/lib/praxis-table.html
• projects/praxis-table/src/lib/praxis-table.scss
• projects/praxis-table/src/lib/praxis-table-toolbar.ts
• projects/praxis-table/src/lib/praxis-table-config-editor.ts
• projects/praxis-table/src/lib/behavior-config-editor/behavior-config-editor.component.ts
• projects/praxis-table/src/lib/header-appearance-editor/header-appearance-editor.component.ts
• projects/praxis-table/src/lib/columns-config-editor/columns-config-editor.component.ts
• projects/praxis-table/src/lib/rules-editor/table-rules-editor.component.ts
• projects/praxis-table/src/lib/toolbar-actions-editor/toolbar-actions-editor.component.ts
• projects/praxis-table/src/lib/filter-settings/filter-settings.component.ts
• projects/praxis-table/src/lib/messages-localization-editor/messages-localization-editor.component.ts
• projects/praxis-table/src/lib/dialogs/confirm-dialog-appearance-editor.component.ts
• projects/praxis-table/src/lib/crud-integration-editor/crud-integration-editor.component.ts
• projects/praxis-core/src/lib/models/table-config-v2.model.ts
• projects/praxis-table/src/lib/utils/action-utils.ts
• projects/praxis-core/src/lib/tokens/global-action.catalog.ts
• projects/praxis-core/src/lib/models/global-action.model.ts
• projects/praxis-core/src/lib/actions/global-action-ui.ts

Appendix: JSON path index

Appendix: Events summary

selectionChange emits { trigger, row?, selectedRows, selectedCount, tableId?, resourceIdentity? } for row selection changes initiated by the user and with trigger: "data-reconcile" when a data update removes identities from the effective selection. Rehydrating the same identities does not emit a new selection event.

Assistant turns can also receive the selected-row digest as context; textual matching on row values must not decide primary intent.

Appendix: Styling API summary

Fallback global de aparencia

Quando o host salva GlobalConfig.table.appearance, a tabela usa esses valores como fallback corporativo para:

• appearance.density
• appearance.spacing.cellPadding
• appearance.spacing.headerPadding
• appearance.typography.fontSize
• appearance.typography.headerFontSize

Precedencia efetiva:

1. TableConfig local informado pelo host
2. GlobalConfig.table.appearance
3. defaults hardcoded de createDefaultTableConfig()

Campos fora de table.appearance mantem a semantica anterior de fallback do provider.

Editor and tooling notes

• Cobertura de editor/tooling foi separada da cobertura de runtime para evitar confusao de suporte.
• Quando nao houver evidencia direta no codigo, o status deve permanecer not yet verified.

Appendix: Examples summary

Appendix minimal valid

{
  "columns": []
}

Appendix typical/common

{
  "columns": [
    {
      "field": "name",
      "header": "Nome"
    }
  ],
  "behavior": {
    "pagination": {
      "enabled": true,
      "pageSize": 25
    }
  }
}

Appendix advanced

{
  "columns": [
    {
      "field": "status",
      "header": "Status",
      "renderer": {
        "type": "badge"
      }
    }
  ],
  "toolbar": {
    "actions": [
      {
        "id": "refresh",
        "label": "Atualizar"
      }
    ]
  },
  "behavior": {
    "selection": {
      "mode": "multiple"
    }
  }
}

Appendix enterprise scenario

{
  "columns": [],
  "messages": {
    "emptyState": "Nenhum registro encontrado."
  },
  "behavior": {
    "expansion": {
      "enabled": true
    }
  },
  "data": {
    "mode": "remote",
    "resourcePath": "customers/table"
  }
}

Nota: exemplos especificos do componente foram preservados na secao detalhada para evitar perda de cobertura durante esta migracao canonicamente orientada.

Known limitations and mismatches

Compatibility and migration notes

Governed embeds

Contextual detail presentation

behavior.detail owns the shared schema, source, rendering, height and lazy-load configuration. presentation.placement selects row (the default) or bottom; presentation.initiallyCollapsed sets the initial disclosure state. For bottom presentation, presentation.bottomStackPosition selects afterControls (the default) or beforeControls, and presentation.emptyBehavior selects an instructional message (the default) or hide. A missing height defaults to dynamic sizing. height.mode accepts explicit dynamic or fixed; fixed mode requires a positive px. behavior.expansion owns row interaction only. Do not store detail inside expansion: the finite migration moves that branch and rejects differing old/new definitions. Runtime does not read the old path.

Bottom detail uses the existing selection model. Exactly one visible record with a stable identity may provide the body. Zero or multiple selections retain an explicit empty/status region; a retained selection outside the current page never reads a detail body. Refreshing the same ID refreshes its context. Selection never executes a business action.

Use detail.presentation.configure to choose bottom: it disables row expansion and enables single selection when selection is disabled, preserving an already enabled multiple-selection policy. Choosing row enables row expansion; disabling detail disables expansion. Conflicting hand-authored configurations fail closed. detail.configure and expansion.configure apply their declared activation semantics. detail.source.configure changes only the source; extension properties inside that source never act as presentation commands. Unknown extensions remain preserved, while malformed known groups, booleans and source modes block Apply. An existing dynamic height requires an explicit positive fixed-height adjustment before choosing bottom.

The Details section edits the authored tree and preserves field expressions, unknown nodes and provider references. Its local preview does not perform remote reads or persist sample values. Invalid advanced JSON blocks Apply/Save. Discard restores detail edits; global defaults retain their existing reset semantics.

The bottom body defaults to dynamic height with a small-viewport CSS limit. Fixed mode starts at 192px in the editor and provides vertical scrolling. It is outside the virtual viewport and defaults to after the footer controls, preserving the collection stack. Explicit collapse persists across selection changes. Inline charts require the Charts provider; unresolved references remain explained placeholders.

• behavior.detail.schemaContract.allowedNodes agora tambem pode incluir formRef, tableRef, chartRef, templateRef e diagramEmbed.
• Esses nodes continuam host-mediated:
  • o host resolve discovery, registry, abertura e policy
  • a tabela padroniza o shell, os metadados e a CTA do embed
  • o miolo visual continua delegado para PraxisRichContent
• diagramEmbed adiciona provider, source ou sourceField para preview governado de diagrama, sem abrir uma segunda DSL de detail row.

type DetailEmbedNode = {
  type: 'formRef' | 'tableRef' | 'chartRef' | 'templateRef';
  title?: string;
  subtitle?: string;
  description?: string;
  caption?: string;
  emptyText?: string;
  schemaId?: string;
  templateId?: string;
  inputs?: Record<string, unknown>;
  presetRef?: CorePresetRef;
  action?: {
    actionId: string;
    label: string;
    icon?: string;
    payloadExpr?: string;
    visibleWhen?: JsonLogicExpression | null;
    disabledWhen?: JsonLogicExpression | null;
  };
};

type DiagramEmbedNode = {
  type: 'diagramEmbed';
  title?: string;
  subtitle?: string;
  description?: string;
  caption?: string;
  emptyText?: string;
  provider: 'mermaid' | 'bpmn' | 'custom';
  source?: string;
  sourceField?: string;
  inputs?: Record<string, unknown>;
  presetRef?: CorePresetRef;
  action?: {
    actionId: string;
    label: string;
    icon?: string;
    payloadExpr?: string;
    visibleWhen?: JsonLogicExpression | null;
    disabledWhen?: JsonLogicExpression | null;
  };
};

Filter presentation

FilterPresentationConfig is owned by Core. Tables author it at behavior.filtering.advancedFilters.settings.presentation; standalone filters use FilterConfig.presentation, projected directly to the runtime presentation input. It changes presentation only, never the filter DTO or query semantics.

With filter persistence enabled, an acknowledged persisted FilterConfig.presentation overrides the authored input for the same component identity on reload. Apply remains a preview-only operation. Hosts that require input-only materialization set disablePersistence, which prevents preference loading and saving.

The guided preferences editor roundtrips the complete effective FilterConfig; changing presentation or another managed section preserves unmanaged siblings such as selectedFieldIds and field metadata overrides.

{
  "header": { "visible": true, "text": "Filtros", "position": "above", "size": "medium" },
  "advancedAction": { "display": "icon-text", "text": "Mais filtros", "icon": "filter_list", "size": "compact", "position": "end" }
}

Absent presentation preserves the existing icon action and hidden heading. header.visible explicitly enables the heading. An empty icon removes that icon. If the advanced action uses icon-only display with an empty icon, it falls back to its localized/authored text so the action remains discoverable. Text-only display never renders an icon. Nonempty authored text takes precedence over localized copy and the default catalog label. Empty or whitespace-only header/action text inherits the localized label, so it cannot create an unnamed action. Action position applies inside the auxiliary controls group, not the page. Existing showAdvancedButton controls whether the advanced action is available; presentation introduces no second visibility switch.

The embedded table supplies the heading, advanced-action label, dialog title and opening/unavailable feedback from the praxisTableRuntime catalog through the existing filter i18n input. Host locale changes and external translator overrides apply without modifying the filter query. Explicit presentation text still wins; clearing it restores catalog resolution. Standalone filters keep their explicit i18n input. Other legacy filter-manager copy is outside this localized projection.

Tokens project to CSS custom properties --pfx-filter-gap, --pfx-filter-header-gap, --pfx-filter-header-color, --pfx-filter-header-font-size, --pfx-filter-header-font-weight, --pfx-filter-icon-size, --pfx-filter-action-gap, --pfx-filter-action-font-size, and --pfx-filter-action-font-weight. Prefer the semantic size/position controls for ordinary authoring; tokens are for deliberate theme customization.

AI authoring extends existing operations: filter.advanced.configure receives settings.presentation for tables; filter.settings.configure receives presentation for standalone filters. Neither operation authors a query through this object. Corporate context changes use the existing EnterpriseRuntimeContextService: Table invalidates rows, selection, discovery and pending data/detail responses before a new remote load. Local hosts must replace data for the effective context and discard their own obsolete asynchronous deliveries. This is runtime state isolation, not backend authorization. initiallyCollapsed is reapplied after persisted hydration and configuration Apply.