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

package/README.md

@@ -96,6 +96,7 @@ import { PraxisList } from '@praxisui/list';
       (itemClick)="onItem($event)"
       (actionClick)="onAction($event)"
       (selectionChange)="onSelection($event)"
+      (exportAction)="onExport($event)"
     />
   `,
 })
@@ -122,14 +123,31 @@ export class ListDemoComponent {
       { id: 'favorite', icon: 'favorite', label: 'Like' },
       { id: 'buy', icon: 'shopping_cart', kind: 'button', buttonVariant: 'stroked', label: 'Buy' },
     ],
+    export: {
+      enabled: true,
+      formats: ['csv', 'json'],
+      general: { scope: 'auto', includeFields: ['id', 'name', 'price'] },
+    },
   } satisfies import('@praxisui/list').PraxisListConfig;
 
   onItem(e: any) { console.log('itemClick', e); }
   onAction(e: any) { console.log('actionClick', e); }
   onSelection(e: any) { console.log('selectionChange', e); }
+  onExport(e: any) { console.log('exportAction', e); }
 }
 ```
 
+## Collection Export
+
+`@praxisui/list` uses the shared collection export contract from `@praxisui/core`, the same platform surface used by table exports.
+
+- `export.enabled` renders the export action menu.
+- `export.formats` accepts `csv`, `json`, `excel`, `pdf`, and `print`.
+- `export.general.scope` accepts `auto`, `selected`, `filtered`, `currentPage`, and `all`.
+- Local CSV/JSON exports run in the browser with formula escaping from `PraxisCollectionExportService`.
+- Remote `filtered`/`all` exports and advanced formats require a host-level `PRAXIS_COLLECTION_EXPORT_PROVIDER`.
+- Deferred exports and provider failures surface visible feedback through snackbar and live-region status.
+
 ## Runtime Contract (Data Mode and Precedence)
 
 Effective data mode resolution follows `ListDataService.stream()`:
@@ -151,6 +169,8 @@ Decision matrix (runtime today):
 
 Important behavior:
 - pagination/search/sort controls from `ui.*` are rendered only when `dataSource.resourcePath` is defined.
+- remote pagination uses Angular Material `mat-paginator` to keep the same paginator chrome and accessibility behavior used by the dynamic table.
+- when `ui.showRange` is `false`, the Material range text is hidden but the remote footer still exposes the total count.
 - remote mode uses `GenericCrudService.filter(query, pageable)` and falls back to `getAll()` when `/filter` fails.
 
 ## Runtime Status Matrix (High-Impact Paths)
@@ -288,7 +308,7 @@ actions: [
 - `showIf`: use Json Logic. Example: `{ "==": [{ "var": "row.status" }, "active"] }`.
 - `emitPayload`: authoring field in the config/editor; current runtime `actionClick` emission does not change shape based on this field.
 
-### Global actions (command)
+### Global actions
 
 ```ts
 actions: [
@@ -296,13 +316,34 @@ actions: [
     id: 'favorite',
     icon: 'favorite',
     label: 'Favorite',
-    command: 'global:api.post',
-    globalPayload: { url: '/api/favorite', body: { id: '${item.id}' } }
+    globalAction: {
+      actionId: 'api.post',
+      payload: { url: '/api/favorite', body: { id: '${item.id}' } }
+    }
   }
 ]
 ```
 
-When `command` is set, `actionClick` is **not emitted** by default. Use `emitLocal: true` to emit both.
+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
 
@@ -312,14 +353,16 @@ actions: [
     id: 'delete',
     icon: 'delete',
     label: 'Delete',
-    command: 'global:api.patch',
+    globalAction: {
+      actionId: 'api.patch',
+      payload: { url: '/api/items/${item.id}', body: { active: false } },
+    },
     showLoading: true,
     confirmation: {
       title: 'Confirm deletion',
       message: 'Are you sure you want to delete this item?',
       type: 'danger',
     },
-    globalPayload: { url: '/api/items/${item.id}', body: { active: false } },
   }
 ]
 ```
@@ -337,6 +380,18 @@ Outputs:
 - `(actionClick)`: `{ actionId, item, index }`
 - `(selectionChange)`: `{ mode, value, items, ids? }`
 
+## Agentic Authoring & Manifest
+
+`@praxisui/list` publishes `PRAXIS_LIST_AUTHORING_MANIFEST` as the executable authoring contract for list/card configuration.
+
+- **Component ID:** `praxis-list`
+- **Config Schema:** `PraxisListConfig`
+- **Editable targets:** the manifest exposes explicit targets for template slots, text, avatar, badge, item actions, empty state, selection, layout, row layout, data binding, interaction, expansion, rules, metadata, skin, toolbar UI, collection export, localization, accessibility and declarative event mappings.
+- **Operation families:** operations cover the required list authoring brief plus supported extensions for metadata, local/remote data, row layout, skin, interaction/expansion, conditional rules, executive template slots, features, skeleton, toolbar UI, export, i18n, accessibility and declarative event mappings.
+- **Validation:** deterministic validators cover field binding, stable action/rule/section IDs, destructive action removal, remote resource binding, local/remote precedence, enum support, query/sort support, row layout placement reachability, expansion schema safety, Json Logic, global actions, declared-only runtime warnings and editor round-trip preservation.
+- **Examples/evals:** fixtures cover every operation family in the manifest, including title/subtitle binding, action creation/update/removal, status badge, selection mode, missing field rejection, skin, toolbar, export, accessibility, event mapping, row layout, expansion, data modes, i18n, empty state and conditional row styling.
+- **Declared-only semantics:** fields documented as declared-only remain authorable only as config/editor round-trip fields and are guarded by `declared-only-runtime-warning`; the manifest does not claim runtime behavior that the component does not implement.
+
 ## Known limitations and mismatches
 
 1. `layout.virtualScroll` and `layout.stickySectionHeader` exist in the contract/editor, but have no runtime implementation.

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.