@praxisui/list 8.0.0-beta.19 → 8.0.0-beta.20

package/README.md

@@ -326,6 +326,25 @@ actions: [
 
 When `globalAction` is set, `actionClick` is **not emitted** by default. Use `emitLocal: true` to emit both.
 
+For internal navigation from a row or item button, use `navigation.openRoute` and bind the selected item id into `query` or `state`:
+
+```ts
+actions: [
+  {
+    id: 'details',
+    icon: 'open_in_new',
+    label: 'Open details',
+    globalAction: {
+      actionId: 'navigation.openRoute',
+      payload: {
+        path: '/clientes/detalhe',
+        query: { id: '${item.id}' },
+      },
+    },
+  }
+]
+```
+
 ### Confirmation and loading
 
 ```ts

package/docs/2026-03-executive-list-platform-backlog.md

@@ -0,0 +1,140 @@
+# Backlog Tecnico — Executive List Platform
+
+Data: 2026-03-20
+Escopo: `projects/praxis-list`
+Status: draft
+
+## Objetivo
+
+Evoluir a `praxis-list` para suportar listas executivas com fidelidade visual ao layout de referencia em `praxis-ui-landing-page/issues/playground/problemas/referencia-list`, sem criar uma API publica paralela (`V2`) e sem depender de hacks baseados em `html` inline, parsing por quebra de linha ou CSS acoplado a `nth-child`.
+
+## Principios
+
+- Manter a API publica em `PraxisListConfig`.
+- Introduzir um modelo interno normalizado unico para o runtime.
+- Reaproveitar da `praxis-table` o desenho correto de seguranca e resolucao remota.
+- Tratar a linha da list como composicao de slots renderizaveis, nao como HTML livre.
+- Priorizar a solucao correta de plataforma, nao remendos de demo.
+
+## Fase 1 — Base Contratual e Runtime
+
+Objetivo: suportar a linha fechada da referencia sem hacks.
+
+### Itens
+
+- Expandir `TemplateType` com `metric`, `compose` e `component`.
+- Evoluir `TemplateDef.props` para suportar `metric`, `compose` e `component`.
+- Adicionar `layout.rowLayout`.
+- Adicionar `rules.itemStyles`.
+- Adicionar `rules.slotOverrides`.
+- Criar `NormalizedListRuntimeConfig`.
+- Criar `normalizeListConfig()`.
+- Criar `normalizeTemplateNode()` e `normalizeTemplating()`.
+- Criar `normalizeLayout()`.
+- Atualizar o runtime da list para renderizar `metric`.
+- Atualizar o runtime da list para renderizar `compose`.
+- Aplicar `rules.itemStyles` no container do item.
+- Aplicar `rules.slotOverrides` por slot.
+
+### Criterios de aceite
+
+- A linha consegue alinhar colunas de forma estavel entre todos os itens.
+- O conteudo das colunas fica centralizado verticalmente.
+- As metricas `SALDO`, `LIMITE DISPONIVEL` e `RISCO` nao dependem de `nth-child`.
+- O risco pode variar cor e icone por regra.
+
+## Fase 2 — Renderers Canonicos da Linha Executiva
+
+Objetivo: reduzir verbosidade e eliminar `html` inline no cenario executivo.
+
+### Itens
+
+- Criar renderer `account-identity`.
+- Criar renderer `executive-metric`.
+- Criar renderer `executive-trailing`.
+- Criar registry interno de renderers da list.
+- Fazer `TemplateDef.type = 'component'` resolver via registry.
+- Migrar `PraxisListDocPageComponent` para o contrato canônico novo.
+- Remover dependencia de `executiveNameHtml`, `executiveSubtitleHtml` e `executiveTrailingHtml`.
+- Reduzir CSS hardcoded da `executive-inline-skin`.
+
+### Criterios de aceite
+
+- O cenario `Executive expansion` usa renderers canônicos para identidade, metricas e trailing.
+- O template nao depende mais de `innerHTML` para a linha executiva.
+- A skin volta a ser refinamento visual, nao mecanismo principal.
+
+## Fase 3 — Expansao Schema-Driven e Detail Remoto
+
+Objetivo: suportar a referencia aberta e preparar cenarios reais.
+
+### Itens
+
+- Evoluir `ListExpansionSectionDef` com `metadata` e `component`.
+- Evoluir `expansion` com `dataSource`, `schemaContract` e `rendering`.
+- Implementar `expansion.dataSource.mode = inline`.
+- Implementar `expansion.dataSource.mode = resource`.
+- Implementar `expansion.dataSource.mode = resourcePath`.
+- Implementar interpolacao por `paramsMap`.
+- Implementar `resourceAllowList`.
+- Bloquear `resourcePath` absoluto ou com scheme.
+- Implementar cache por item expandido.
+- Implementar cancelamento ao colapsar.
+- Implementar sanitizacao de schema com `allowedNodes`.
+- Implementar shell visual `attached` para detail row.
+
+### Criterios de aceite
+
+- A list suporta detalhe lazy por item expandido.
+- A politica de seguranca opera em fail-closed.
+- O detail remoto pode ser carregado por `resourcePath` relativo com allowlist.
+- A estrutura aberta da referencia pode ser reproduzida sem hardcode por tela.
+
+## Fase 4 — Testes, Docs e Governanca
+
+Objetivo: consolidar a plataforma.
+
+### Itens
+
+- Criar specs para o normalizador de config.
+- Criar specs para `metric`, `compose` e `component`.
+- Criar specs para `rules`.
+- Criar specs para `expansion.resourcePath`.
+- Criar regressao visual/estrutural do cenario executivo.
+- Atualizar `README.md` da list.
+- Atualizar a documentacao JSON API da list.
+- Documentar regras de seguranca da expansao remota.
+
+### Criterios de aceite
+
+- A cobertura de testes protege a normalizacao, renderizacao e seguranca.
+- A doc page reflete o contrato canonico.
+- O backlog desta rodada deixa de ser apenas analise e vira plataforma verificavel.
+
+## Ordem Recomendada
+
+1. Fase 1 completa
+2. Fase 2 completa
+3. Fase 3 completa
+4. Fase 4 completa
+
+## Decisoes Ja Tomadas
+
+- Nao criar `PraxisListConfigV2`.
+- Evoluir o contrato atual.
+- Introduzir modelo interno normalizado.
+- Reaproveitar o padrao de seguranca da `praxis-table` para detail remoto.
+
+## Riscos Conhecidos
+
+- Crescimento do template principal da list se a normalizacao nao vier antes dos renderers.
+- Acoplamento excessivo a CSS se `metric` e `compose` forem introduzidos sem `rowLayout`.
+- Duplicacao conceitual com a `praxis-table` se a expansao remota da list ignorar `schemaContract` e `resourceAllowList`.
+
+## Definicao de Pronto desta iniciativa
+
+- Linha executiva fechada identica a referencia.
+- Linha executiva aberta identica a referencia.
+- Variacoes do mesmo padrao possiveis via contrato.
+- Sem `html` inline como mecanismo principal.
+- Sem hacks de `nth-child` e pseudo-elementos como contrato.

package/docs/2026-03-executive-list-reference-checklist.md

@@ -0,0 +1,110 @@
+# Checklist de Aderencia — Referencia Executive List
+
+Data: 2026-03-20
+Escopo: `projects/praxis-list`
+Status: draft
+
+## Referencia
+
+- Fechado: `praxis-ui-landing-page/issues/playground/problemas/referencia-list/fechado.png`
+- Aberto: `praxis-ui-landing-page/issues/playground/problemas/referencia-list/aberto.png`
+
+## Objetivo
+
+Confirmar, ponto a ponto, que a evolucao proposta para a `praxis-list` cobre a referencia visual de forma 1:1 e ainda permite variacoes controladas do mesmo padrao.
+
+## Checklist Estrutural
+
+- [ ] A linha funciona como grade estavel de colunas.
+- [ ] Todas as linhas compartilham o mesmo alinhamento horizontal entre colunas.
+- [ ] O conteudo interno das colunas fica centralizado verticalmente.
+- [ ] A linha suporta variacao discreta de borda/tom por severidade.
+
+## Checklist de Identidade
+
+- [ ] O codigo/monograma da conta aparece em capsula dedicada.
+- [ ] O titulo principal suporta icone decorativo adjacente.
+- [ ] O subtitulo suporta badge de segmento.
+- [ ] O subtitulo suporta composicao `tipo de conta + desde ano`.
+- [ ] O bloco de identidade e reutilizavel como renderer proprio.
+
+## Checklist de Metricas
+
+- [ ] `SALDO` suporta label pequena + valor forte.
+- [ ] `LIMITE DISPONIVEL` suporta valor + barra inline + legenda.
+- [ ] `RISCO` suporta icone + valor + barra + legenda.
+- [ ] `RISCO` suporta variacao de icone por regra.
+- [ ] `RISCO` suporta variacao de cor por regra.
+- [ ] A barra de progresso pode variar por regra.
+- [ ] O alinhamento das metricas e identico entre linhas.
+
+## Checklist de Trailing
+
+- [ ] O trailing suporta alertas agregados.
+- [ ] O trailing suporta owner resumido.
+- [ ] O trailing suporta icones de acao.
+- [ ] O trailing suporta chevron de expansao.
+- [ ] A ordem visual do trailing e estavel.
+- [ ] O trailing pode ser empacotado como renderer reutilizavel.
+
+## Checklist de Expansao
+
+- [ ] A linha expandida fica visualmente anexada a linha principal.
+- [ ] A expansao suporta layout em 3 colunas.
+- [ ] `ALERTAS` suporta bloco de informacao destacado.
+- [ ] `PRODUTOS CONTRATADOS` suporta chips.
+- [ ] `PROXIMOS EVENTOS` suporta timeline.
+- [ ] O shell da expansao pode ser configurado sem hardcode por tela.
+
+## Checklist de Detail Remoto
+
+- [ ] A expansao pode operar com dados inline.
+- [ ] A expansao pode operar com `resource`.
+- [ ] A expansao pode operar com `resourcePath`.
+- [ ] O `resourcePath` suporta `paramsMap`.
+- [ ] O `resourcePath` exige `resourceAllowList`.
+- [ ] O runtime bloqueia URL absoluta ou com scheme.
+- [ ] O runtime sanitiza schema remoto por `schemaContract.allowedNodes`.
+
+## Checklist de Variacoes
+
+- [ ] A mesma estrutura suporta portfolios diferentes.
+- [ ] As metricas suportam layouts diferentes sem hacks.
+- [ ] O trailing suporta diferentes combinacoes de alertas/owner/acoes.
+- [ ] O bloco de identidade suporta variacao de badge, subtitulo e adornos.
+- [ ] A expansao suporta sections declarativas adicionais.
+
+## Cobertura Esperada do Contrato
+
+### Cobertura completa
+
+- `layout.rowLayout`
+- `templating.metric`
+- `templating.compose`
+- `rules.itemStyles`
+- `rules.slotOverrides`
+- `expansion.dataSource`
+- `expansion.schemaContract`
+- `expansion.rendering`
+
+### Cobertura completa, mas recomendando renderer dedicado
+
+- `account-identity`
+- `executive-metric`
+- `executive-trailing`
+
+## Sinais de Solucao Incorreta
+
+- Uso de `html` inline como mecanismo principal de composicao.
+- Dependencia de `nth-child` para semantica do contrato.
+- Barras desenhadas apenas por pseudo-elemento sem dado semantico.
+- Variacoes visuais dependentes de CSS acoplado ao cenario demo.
+- Detail remoto sem `resourceAllowList`.
+
+## Definicao de Aderencia Concluida
+
+- [ ] Fechado 1:1
+- [ ] Aberto 1:1
+- [ ] Variacoes controladas suportadas
+- [ ] Sem hacks estruturais
+- [ ] Composicao canônica reutilizavel

package/docs/2026-04-navigation-open-route-release-note.md

@@ -0,0 +1,40 @@
+# Release Note — Navigation Open Route
+
+Data: 2026-04-23
+Escopo: `projects/praxis-list`
+Status: concluido
+
+## Resumo
+
+A `praxis-list` agora documenta e demonstra o contrato canônico `navigation.openRoute` para acoes de item.
+O mesmo item que dispara `surface.open` também pode abrir uma rota interna, levando `item.id` no `query` ou no `state`.
+
+## O que foi alinhado
+
+- Runtime de demonstração com uma action de item que abre `/components-showcase/surface-open-guide`.
+- Spec unitária da demo ajustada para refletir o contrato real de `GlobalActionService.executeRef(...)`.
+- Playwright de demonstração validando navegação real no browser.
+- README e documentação JSON API da lista com exemplo de `navigation.openRoute`.
+- Manifesto de IA da lista com exemplo sugestivo de action interna usando `item.id`.
+
+## Contrato de uso
+
+Exemplo canônico:
+
+```ts
+{
+  actionId: 'navigation.openRoute',
+  payload: {
+    path: '/components-showcase/surface-open-guide',
+    query: { funcionarioId: '${item.id}' },
+    state: { funcionarioId: '${item.id}', source: 'surface-open-list-demo' },
+  },
+}
+```
+
+## Status do suporte
+
+- `navigation.openRoute`: ativo no core e consumido pela `praxis-list`.
+- `surface.open`: permanece como contrato canônico para abertura de superfícies.
+- `actionClick`: continua sendo o evento local da lista quando `emitLocal` estiver habilitado.
+

package/docs/adr/2026-03-list-authoring-protocol.md

@@ -0,0 +1,98 @@
+# ADR: Protocolo Canônico de Autoria do `praxis-list`
+
+## Status
+
+Aceito.
+
+## Problema
+
+`praxis-list` evoluiu com múltiplas superfícies de autoria e aplicação:
+
+- editor visual;
+- edição JSON/manual;
+- host runtime;
+- integrações futuras com playground e IA.
+
+Antes desta mudança, o boundary principal era implícito em `PraxisListConfig`, com lógica de normalização e apply espalhada entre editor e host. Isso criava fragilidade arquitetural, side effects opacos e risco de divergência entre superfícies.
+
+## Decisão
+
+O contrato canônico de autoria de `praxis-list` passa a ser `ListAuthoringDocument`.
+
+Regras normativas:
+
+1. O boundary principal de autoria é `ListAuthoringDocument`.
+2. `PraxisListConfig` continua sendo a projeção canônica de runtime, não o protocolo primário de autoria.
+3. O host deve aplicar documentos via:
+   - parse;
+   - validate;
+   - build apply plan;
+   - executor runtime fino.
+4. O editor visual e o editor JSON devem produzir e consumir `ListAuthoringDocument`.
+5. Regras de normalização, validação e inferência autoral pertencem à capability pública; o editor visual só pode projetar/hidratar estado transitório de UI.
+6. `applyConfigFromAdapter(...)` é mantido apenas por compatibilidade e deve delegar ao protocolo canônico.
+7. Inferência de schema não deve ficar escondida como side effect arquitetural opaco; ela deve ser uma etapa explícita do apply/runtime e sua decisão deve nascer do `ListApplyPlan`.
+8. Não forçamos `bindings` vazios no documento enquanto não houver requisito real fora de `config`.
+
+## Contrato novo
+
+O protocolo é composto por:
+
+- `ListAuthoringDocument`
+- `ListValidationContext`
+- `ListProjectionContext`
+- `ListRuntimeContext`
+- `ListApplyPlan`
+
+Capability pública:
+
+- `createListAuthoringDocument(...)`
+- `parseLegacyOrListDocument(...)`
+- `normalizeListAuthoringDocument(...)`
+- `validateListAuthoringDocument(...)`
+- `toCanonicalListConfig(...)`
+- `buildListApplyPlan(...)`
+- `serializeListAuthoringDocument(...)`
+
+## Boundary de Apply
+
+O host não deve usar `applyDocument(target, doc)` como boundary principal.
+
+O fluxo correto é:
+
+1. receber payload;
+2. converter para `ListAuthoringDocument`;
+3. validar;
+4. construir `ListApplyPlan`;
+5. executar o plano no runtime.
+
+O executor do host é responsável apenas por efeitos de runtime:
+
+- aplicar config;
+- rebinding de seleção;
+- reaplicar skin;
+- persistir config quando necessário;
+- executar inferência de schema explicitamente.
+
+## Compatibilidade legada
+
+Compatibilidade continua suportada para payloads legados baseados em `config`.
+
+Regra:
+
+- quando houver `document`, ele tem precedência;
+- quando houver apenas `config`, o host/editor convertem para `ListAuthoringDocument`.
+
+## Consequências
+
+Benefícios:
+
+- unificação entre editor visual, editor JSON e host;
+- apply declarativo e mais auditável;
+- menor risco de divergência conceitual com `praxis-table`;
+- base melhor para playground e fluxos de IA.
+
+Tradeoff:
+
+- aumenta a disciplina de contrato;
+- exige manutenção explícita da documentação e dos testes dos fluxos de autoria.