praxis-list

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

Summary

• Tipo documental: API reference canonica de contrato JSON.
• Source of truth: runtime e codigo declarados no frontmatter.
• Objetivo operacional: consulta rapida, auditavel e deterministica sob pressao.
• Resumo funcional herdado: Referencia canonica da JSON API do praxis-list, com foco em:

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.

Source of truth

Rich content convergence

• mapListTemplateToRichContentP0(...) e a ponte publica e restrita entre a taxonomia atual de templating do praxis-list e o vocabulario compartilhado 1.0 de rich content em @praxisui/core.
• O subconjunto promovido nesta fase e intencionalmente pequeno: text, icon, image, chip -> badge, metric e compose.
• Tipos como component, slot, html, rating, currency e date continuam list-owned e fora do contrato compartilhado 1.0 ate uma promocao semantica explicita.

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 paths (public contract)

Supported legacy paths

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

Internal-only paths

Experimental paths

Nenhum path experimental permanece ativo nesta revisão. templating.features[] materializa o mesmo conjunto de TemplateDef dos slots principais, preservando também o formato legado { icon, expr, class, style }.

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

Input bindings

Output events

External side channels

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. contrato recebido em @Input() config ou documento vindo do editor runtime
2. hidratação opcional de config persistida (ASYNC_CONFIG_STORAGE)
3. parse do payload para ListAuthoringDocument
4. projeção para PraxisListConfig via buildListApplyPlan(...)
5. executor runtime fino para data, seleção, skin, persistência e inferência

Fallback order

config explícita -> config persistida por chave -> config corrente em memória -> comportamento seguro sem persistência.

Override points

• @Input() config e @Input() form
• editor runtime (openConfigEditor, apply plan)
• persistência por host (ASYNC_CONFIG_STORAGE)

Runtime normalization

• applyAuthoringPayload() faz parse, validação, apply plan e executor runtime sem recriar componente.
• buildListApplyPlan(...) também carrega a decisão explícita de inferência de schema; o host só executa essa etapa fina sem inferir a partir de estado runtime arbitrário.
• setupSelectionBinding() adapta shape de seleção para retorno declarativo.
• executeSchemaInferenceForPlan() infere templates quando faltantes ou quando slots de demonstracao nao estao aterrados nos campos publicados pelo schema do recurso.

Precedence rules

• config externa mais recente tem precedência sobre hidratação tardia de storage.
• editor saved persiste e reaplica; applied reaplica sem persistir obrigatoriamente.
• quando listId ausente, runtime segue sem persistencia e sem warning operacional; a lista continua renderizando e editando normalmente.

Validation and error semantics

Validation model

Error semantics

A maior parte das falhas opera em modo fail-open (persistência, inferência, comandos globais opcionais). O componente prioriza continuidade de renderização e emissão de eventos locais.

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)

Referencia canonica da JSON API do praxis-list, com foco em:

• cobrir 100% do contrato PraxisListConfig aceito hoje;
• separar com clareza o que esta Active, Partial e Declared-only;
• explicar como a lista interage com o ecossistema Praxis (data, skin, settings panel, AI e acoes globais).

Legenda de suporte:

• Active: ligado e observavel no runtime atual.
• Partial: parcialmente ligado (subconjunto funcional).
• Declared-only: existe no contrato, sem consumo direto no runtime atual.

Table of contents

• Overview
  • Porque este componente e diferente
  • Pitch de 30 segundos (valor)
  • Mapa de contrato e superficies
  • Integracao com ecossistema Praxis
  • Checklist corporativo pre-flight
• API
  • Component inputs
  • Component outputs
  • Data mode and flow
  • Persistencia e identidade
  • PraxisListConfig top-level
  • JSON coverage matrix (top-level)
  • DataSource API
  • Layout API
  • Skin API
  • Selection API
  • Templating API (deep dive)
  • Actions API
  • UI, i18n, a11y e events
  • Expressoes suportadas (expr e showIf)
  • Settings Panel e AI assistant
  • Complete JSON path index (cobertura total)
• Styling
• Examples
• Known limitations and mismatches
• Source references

Overview

praxis-list e um runtime schema-driven para listas visuais em tres variantes:

1. list
2. cards
3. tiles

O comportamento de runtime continua projetado a partir de PraxisListConfig, mas a autoria canônica e governada por ListAuthoringDocument.

Fluxo simplificado:

1. Recebe config.
2. Resolve origem de dados (local ou remota).
3. Aplica skin (classes + CSS vars + inline style sanitizado).
4. Renderiza slots de templating (leading, primary, meta, etc.).
5. Executa acoes por item (local/global) e emite eventos para host.

Porque este componente e diferente

praxis-list combina render declarativo e operacao de dados real no mesmo contrato:

• suporta local e remoto com pipeline unico;
• possui sistema de templating por slot com tipos visuais;
• integra skin tokenizada, editor runtime e assistente AI;
• permite acoes globais via catalogo do host sem acoplamento direto da lista.

Pitch de 30 segundos (valor)

Uma lista que funciona como plataforma de experiencia: layout, estilo, templating, dados e acoes ficam no JSON, e o runtime adapta list/cards/tiles com o mesmo contrato.

• Entrega rapida: altera UX por configuracao.
• Padrao corporativo: mesmo contrato em telas diferentes.
• Escalavel: composicao com actions globais, editor e AI sem fork de componente.

Mapa de contrato e superficies

Quatro superficies governam o componente:

1. Documento de autoria (ListAuthoringDocument): envelope persistivel e canônico para editor visual, editor JSON, host runtime e fluxos futuros de IA/playground.
2. Config canônica projetada (PraxisListConfig): dados, layout, skin, selecao, templating, acoes e UI.
3. Inputs externos: listId, componentInstanceId, form e enableCustomization.
4. Outputs: itemClick, actionClick, selectionChange, exportAction, configPatchChange.
5. Side channels: persistencia assinc, settings panel, global action bus e AI adapter.

Integracao com ecossistema Praxis

Checklist corporativo pre-flight

Antes de liberar para producao:

• Defina listId estavel por tela.
• Em multi-instancia, defina componentInstanceId.
• Se remoto: valide resourcePath; o fallback /filter -> getAll existe apenas para consulta sem critérios ativos.
• Em actions[].globalAction, aplique governanca de acoes globais no host.
• Para type='html', mantenha origem confiavel do conteudo.
• Nao trate showIf como autorizacao; backend continua soberano.

API

Component inputs

Component outputs

O editor hospedado oferece Origem da configuração para o input existente configPersistenceStrategy: Configuração da página (input-first), Preferências individuais da lista (local-first) e Configuração temporária (volatile). Para páginas compostas, escolha input-first para evitar que preferências antigas sobreponham o documento salvo da página. Apply, Save e Reset preservam essa escolha e os demais inputs.

Data mode and flow

Resolucao do modo de dados em ListDataService.stream():

1. Se dataSource.data existe, usa modo local.
2. Senao, se dataSource.resourcePath e GenericCrudService existem, usa modo remoto.
3. Senao, retorna vazio.

Regras operacionais:

• Local tem precedencia sobre remoto quando ambos estao presentes.
• Remoto usa filter(query, pageable).
• Em erro no /filter sem critérios ativos, faz fallback de compatibilidade para getAll() com warning deduplicado.
• Em erro no /filter com critérios ativos, falha fechado: mantém o contexto de filtro, zera o resultado, publica ListRemoteLoadError em ListDataService.error$ e oferece nova tentativa. Dados sem filtro nunca substituem silenciosamente a consulta solicitada.
• Busca (ui.showSearch) aplica debounce de 300ms e exige ui.searchField.
• Busca, ordenação e exportação compartilham a toolbar superior da coleção; paginação permanece no footer. Busca, ordenação e paginação remotas aparecem apenas quando o modo resolvido é remote, nunca quando data local tem precedência sobre resourcePath.
• Em viewport estreito, layout.rowLayout recompõe os slots semânticos canônicos (leading, primary, secondary, meta, trailing) em linhas ordenadas sem sobreposição; slots operacionais estendidos são empilhados no owner da lista, sem CSS corretivo no host.
• Atualizações síncronas de query, ordenação e página materializadas pelo mesmo queryContext são coalescidas antes do acesso HTTP; o backend recebe somente o estado final consistente.
• ListDataService.error$ é um Observable<ListRemoteLoadError | null> somente leitura; consumidores podem reagir e solicitar refresh(), mas não publicar estados de erro no serviço.
• Quando nao ha dataSource.data nem dataSource.resourcePath, o runtime renderiza um empty state operacional orientando a conexao da lista a um recurso.

Matriz de decisao (runtime atual):

Regra critica de autoria:

• Se o host enviar data e resourcePath ao mesmo tempo, o runtime usa data (modo local).
• Se a intencao for remoto obrigatorio, nao envie data no mesmo payload.

Persistencia e identidade

• Chave persistida: praxis-list-config-${componentKeyId}.
• componentKeyId deriva de:
  • componentType='praxis-list'
  • listId
  • componentInstanceId
  • contexto de rota.

Sem listId valido:

• persistencia e ignorada;
• nao ha warning; hosts de authoring dinamico podem renderizar e editar sem identidade persistente.

PraxisListConfig top-level

interface PraxisListConfig {
  id?: string;
  dataSource?: {...};
  layout?: {...};
  skin?: {...};
  selection?: {...};
  interaction?: {...};
  templating?: {...};
  expansion?: {...};
  actions?: Array<...>;
  i18n?: {
    locale?: string;
    currency?: string;
  };
  ui?: {...};
  export?: {...};
  a11y?: {...};
  events?: {...};
}

JSON coverage matrix (top-level)

DataSource API

Layout API

Skin API

Notas de seguranca:

• sanitizacao remove url(, @import, expression(, behavior: e comentarios CSS;
• regras sao escopadas ao seletor da instancia para reduzir vazamento de estilo.

Selection API

A identidade de renderização é independente da identidade escolhida para a seleção. Registros HATEOAS usam prioritariamente _links.self.href, evitando colisões quando o mesmo identificador de domínio aparece em competências ou projeções diferentes. Na ausência de self link, a lista aplica sua cadeia de identidade estável baseada nos identificadores e discriminadores presentes no registro; selection.compareBy continua restrito ao contrato de seleção.

Na variante list, a materialização acessível usa um mat-list neutro. Cada linha expõe checkbox (multiple) ou radio (single), ação principal, ações secundárias e expansão como alvos de teclado irmãos. Isso elimina controles interativos aninhados sem alterar PraxisListConfig, o FormControl, o formato de ListSelectionEvent ou a precedência de selection.compareBy.

Export API

Escopos remotos filtered/all e formatos excel/pdf/print exigem provider em @praxisui/core.

Nota critica de integridade:

• quando interaction.expandable=true e selection.mode !== 'none', o runtime canonico coerces interaction.expandTrigger para icon;
• essa coercao e aplicada na normalizacao do contrato antes do runtime para eliminar ambiguidade entre selecionar e expandir a mesma linha;
• a combinacao evita ambiguidade operacional entre selecionar linha e expandir detail row.
• quando interaction.expandable nao estiver ativo, a normalizacao nao deve materializar expandTrigger nem expandMode.

Interaction API

Escopo normativo da V1:

• suportado apenas quando layout.variant = 'list';
• fora de list, o authoring gera diagnostico de erro e o runtime nao materializa detail row.
• no exemplo oficial da lib, o cenario executive-expansion fixa variant = list, lines = 2 e selection.mode = none para manter aderencia a referencia visual e evitar controles inertes.

Templating API (deep dive)

Slots suportados:

• leading, primary, secondary, meta, trailing, sectionHeader, emptyState.

Tipos funcionais no runtime:

• text, icon, image, chip, rating, currency, date, html, metric, compose, component.

Inferencia opcional:

• Quando dataSource.resourcePath existe, GenericCrudService.getSchema() retorna campos e o runtime pode inferir uma materializacao inicial sem alterar o contrato canonico.
• A inferencia prioriza identidade (nomeCompleto/name), avatar (foto/avatar/photo/image), contato (telefone/email ou cpf/email), agrupamento organizacional (departamento/area/time) e status (status/ativo) usando os slots existentes.
• Slots de demonstracao que referenciam campos ausentes no schema do recurso sao descartados antes da inferencia. Campos tecnicos ou numericos como id, idade, age, ativo/status nao sao promovidos para meta por inferencia.

Tipo declarado sem renderer dedicado:

• slot.

Expansion API

Notas de UX/WCAG:

• aria-expanded e aria-controls ficam no owner real do trigger (row ou icon);
• com selection.mode !== 'none', a seleção é acionada pelo checkbox/radio explícito e a expansão permanece em um botão irmão, acionado apenas pelo ícone;
• expansion.sections[].itemsExpr pode resolver arrays/objetos JSON com placeholders; o runtime materializa a estrutura em vez de exibir JSON cru;
• para detalhes editoriais avancados, use type='rich-content' com document/documentExpr; a lista hospeda o contrato canonico RichContentDocument em vez de criar DSL visual paralela;
• ações dentro de seções rich-content são mediadas por hostCapabilities da própria lista, reemitidas em actionClick com payload? e source='rich-content', e confirmMessage usa o mesmo GLOBAL_DIALOG_SERVICE das ações nativas;
• a V1 nao suporta markup arbitrario nem detail builders livres;
• cards e tiles permanecem fora de escopo.
• o scenario executive-expansion da doc page e uma composicao editorial canonica de validacao visual; campos como balanceDisplay, limitDisplay, usageLabel, riskDisplay e riskLabel pertencem ao dataset de exemplo, nao ao contrato base de PraxisListConfig.

Actions API

Semantica de execucao:

1. valida confirmacao (quando configurada);
2. quando action='surface.open', exige recordOpen, extrai somente o sourceIdentityField declarado, reconsulta o recurso e a surface contextual do principal corrente e falha fechado se qualquer identidade/availability divergir;
3. fora desse fluxo, executa acao global estruturada (se globalAction estiver presente), incluindo navigation.openRoute para abrir rotas internas com contexto do item;
4. remove loading;
5. emite actionClick conforme regra emitLocal; uma intencao recordOpen nao cai em emissao local por default quando a resolucao falha.

recordOpen e materializacao governada de runtime e round-trip. O editor visual e o manifesto AI local nao authoram esse campo livremente; a fonte e a projection validada por Metadata/Config.

UI, i18n, a11y e events

Superfícies de expressão (expr e showIf)

templating.*.expr

Suporte principal:

• placeholders: ${item.campo};
• pipes em placeholder: bool, date, map, number;
• pipe top-level bool no expr completo.

Exemplos validos:

• ${item.active|bool:Ativo:Inativo}
• ${item.createdAt|date:pt-BR:short}
• ${item.status|map:done=Concluido;pending=Pendente}
• ${item.total|number:pt-BR:compact}

actions[].showIf

Usa Json Logic canônico com contexto row.

Exemplos válidos:

• {"==":[{"var":"row.status"},"done"]}
• {"and":[{"var":"row.active"},{"!":{"var":"row.archived"}}]}

Política de erro:

• fail-closed (ação fica oculta);
• warning apenas em dev mode, deduplicado.

Settings Panel e AI assistant

Quando enableCustomization=true:

• componente exibe botao de edicao + shell governada PraxisAiAssistantShellComponent;
• openConfigEditor() abre PraxisListConfigEditor;
• applied$ e saved$ aplicam config em runtime;
• saved$ persiste no storage quando chave valida existe.

AI:

• ListAgenticAuthoringTurnFlow envia contexto seguro para o backend e bloqueia patch livre;
• capability/context packs orientam mudancas por contrato governado, nao por patch JSON local.

Complete JSON path index (cobertura total)

Styling

Camadas de estilo no runtime:

1. classes de host (skin-*, density-*, model-*, lines-*, skin.class);
2. CSS vars geradas por ListSkinService.toCssVars;
3. CSS inline opcional (skin.inlineStyle) sanitizado e escopado por instancia.

Recomendacao corporativa:

• prefira skin.* estruturado para padrao multiplataforma;
• use inlineStyle apenas para excecoes auditadas.

Examples

Minimal valid

{}

Typical/common

{}

Advanced

{}

Enterprise scenario

{}

Known limitations and mismatches

Compatibility and migration notes

Source references