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

package/docs/adr/2026-03-list-inline-expansion-v1.md

@@ -0,0 +1,309 @@
+# ADR: Expansão Inline V1 para o `praxis-list`
+
+## Status
+
+Proposto.
+
+Nao implementado no runtime atual.
+
+## Problema
+
+O `praxis-list` ja atende bem leituras fechadas em `list`, `cards` e `tiles`, mas nao oferece um mecanismo oficial para `detail row` ou expansao inline por item.
+
+Essa lacuna ficou explicita ao tentar reproduzir referencias corporativas com duas camadas:
+
+1. uma linha executiva resumida;
+2. um painel expandido inline com secoes como alertas, produtos contratados e proximos eventos.
+
+Hoje isso nao cabe no contrato publico atual de `PraxisListConfig`, nem no template do runtime.
+
+Consequencias da ausencia de contrato formal:
+
+- playground pode cair em hacks de apresentacao que parecem suportar algo que o componente nao suporta;
+- integradores nao tem boundary claro para estado expandido, trigger e acessibilidade;
+- UX corporativa fica inconsistente entre hosts;
+- qualquer tentativa de resolver com `html` livre degrada governanca, consistencia visual e testabilidade.
+
+## Decisao
+
+Tratar expansao inline como evolucao formal do contrato do `praxis-list`, com escopo reduzido e governado.
+
+Regras normativas da proposta V1:
+
+1. A V1 cobre apenas `layout.variant = 'list'`.
+2. A V1 adiciona dois blocos novos ao contrato: `interaction` e `expansion`.
+3. `interaction` governa habilitacao, trigger e politica de estado expandido.
+4. `expansion` governa apenas conteudo expandido inline estruturado, nao markup arbitrario.
+5. O conteudo expandido e composto por secoes com tipos fechados e previsiveis.
+6. `cards` e `tiles` ficam fora do escopo da V1.
+7. `selection` e expansao podem coexistir, mas o trigger padrao deve favorecer icone dedicado quando houver selecao ativa.
+8. A API canônica so deve promover esse contrato para `Active` depois de implementacao, testes de acessibilidade e exemplos oficiais.
+
+## Motivacao
+
+Essa decisao existe para resolver um problema real de produto sem quebrar o perfil enterprise do componente.
+
+Objetivos:
+
+- manter integridade do contrato;
+- evitar hacks de playground como falsa demostracao de capacidade;
+- preservar acessibilidade e navegacao por teclado;
+- limitar a V1 a um conjunto pequeno de padroes forte, em vez de abrir um renderer arbitrario;
+- dar base formal para examples, authoring e documentacao futura.
+
+Referencia visual-alvo desta evolucao:
+
+- `praxis-ui-landing-page/issues/playground/problemas/referencia-list/img.png`
+- `praxis-ui-landing-page/issues/playground/problemas/referencia-list/img_1.png`
+
+Essas imagens representam o objetivo funcional e visual da combinacao:
+
+1. linha executiva fechada com KPIs e acoes;
+2. expansao inline governada com secoes semanticas abaixo da linha principal.
+
+## Proposta de Contrato V1
+
+### Bloco `interaction`
+
+```ts
+interaction?: {
+  expandable?: boolean;
+  expandTrigger?: 'row' | 'icon' | 'row+icon';
+  expandMode?: 'single' | 'multiple';
+  collapseOnPageChange?: boolean;
+};
+```
+
+Semantica:
+
+- `expandable`
+  - default: `false`
+  - habilita ou nao o estado expandido por item.
+- `expandTrigger`
+  - default proposto: `'row'`
+  - quando `selection.mode !== 'none'`, default recomendado: `'icon'`
+  - evita conflito entre selecao e expansao na mesma superficie.
+- `expandMode`
+  - default: `'single'`
+  - `'single'`: uma linha aberta por vez.
+  - `'multiple'`: varias linhas abertas ao mesmo tempo.
+- `collapseOnPageChange`
+  - default: `true`
+  - simplifica comportamento em listas remotas e reduz risco de estado invisivel apos paginação.
+
+### Bloco `expansion`
+
+```ts
+interaction?: {
+  expandable?: boolean;
+  expandTrigger?: 'row' | 'icon' | 'row+icon';
+  expandMode?: 'single' | 'multiple';
+  collapseOnPageChange?: boolean;
+};
+
+expansion?: {
+  emptyLabel?: string;
+  sections: Array<{
+    id: string;
+    title?: string;
+    type: 'info-list' | 'chip-list' | 'timeline' | 'key-value';
+    itemsExpr: string;
+    emptyLabel?: string;
+  }>;
+};
+```
+
+Semantica:
+
+- `expansion.sections`
+  - obrigatorio quando `interaction.expandable = true`
+  - define as secoes renderizadas abaixo da linha principal.
+- `id`
+  - chave estavel da secao.
+- `title`
+  - rotulo visual e acessivel da secao.
+- `type`
+  - renderer fechado e governado da secao.
+- `itemsExpr`
+  - expressao que aponta para a colecao renderizada a partir do item atual.
+- `emptyLabel`
+  - fallback local ou global quando a secao nao tiver conteudo.
+
+## Tipos de Secao da V1
+
+### `info-list`
+
+Uso:
+
+- alertas;
+- observacoes;
+- pendencias simples.
+
+Shape esperado do array:
+
+```ts
+Array<{
+  label?: string;
+  value: string;
+  tone?: 'neutral' | 'info' | 'success' | 'warning' | 'danger';
+  icon?: string;
+}>
+```
+
+### `chip-list`
+
+Uso:
+
+- produtos contratados;
+- tags operacionais;
+- capacidades ativas.
+
+Shape esperado do array:
+
+```ts
+Array<{
+  label: string;
+  tone?: 'neutral' | 'info' | 'success' | 'warning' | 'danger';
+}>
+```
+
+### `timeline`
+
+Uso:
+
+- proximos eventos;
+- vencimentos;
+- marcos operacionais.
+
+Shape esperado do array:
+
+```ts
+Array<{
+  date?: string;
+  label: string;
+  helper?: string;
+  tone?: 'neutral' | 'info' | 'success' | 'warning' | 'danger';
+}>
+```
+
+### `key-value`
+
+Uso:
+
+- bloco resumido de fatos;
+- indicadores secundarios;
+- metadados regulatórios.
+
+Shape esperado do array:
+
+```ts
+Array<{
+  key: string;
+  value: string;
+}>
+```
+
+## Exemplo V1
+
+```ts
+const config = {
+  dataSource: {
+    resourcePath: 'api/customer-accounts/vw-account-portfolio',
+    sort: ['saldoDisponivel,desc'],
+  },
+  layout: {
+    variant: 'list',
+    lines: 2,
+    density: 'comfortable',
+    dividers: 'between',
+    pageSize: 8,
+  },
+  interaction: {
+    expandable: true,
+    expandTrigger: 'icon',
+    expandMode: 'single',
+    collapseOnPageChange: true,
+  },
+  templating: {
+    leading: { type: 'text', expr: '${item.sigla}' },
+    primary: { type: 'text', expr: '${item.nomeConta}' },
+    secondary: { type: 'text', expr: '${item.segmento} • ${item.tipoConta}' },
+    meta: { type: 'currency', expr: '${item.saldoDisponivel}|BRL:pt-BR' },
+    trailing: { type: 'chip', expr: '${item.risco}', variant: 'outlined' },
+    features: [
+      { icon: 'account_balance_wallet', expr: 'Saldo ${item.saldo|currency:BRL:pt-BR}' },
+      { icon: 'credit_card', expr: 'Limite ${item.limite|currency:BRL:pt-BR}' },
+      { icon: 'percent', expr: 'Uso ${item.usoPercentual}%' },
+    ],
+  },
+  expansion: {
+    emptyLabel: 'Nenhum detalhe complementar disponivel.',
+    sections: [
+      {
+        id: 'alerts',
+        title: 'Alertas',
+        type: 'info-list',
+        itemsExpr: '${item.alertas}',
+        emptyLabel: 'Sem alertas ativos.',
+      },
+      {
+        id: 'products',
+        title: 'Produtos contratados',
+        type: 'chip-list',
+        itemsExpr: '${item.produtosContratados}',
+      },
+      {
+        id: 'events',
+        title: 'Próximos eventos',
+        type: 'timeline',
+        itemsExpr: '${item.proximosEventos}',
+        emptyLabel: 'Sem eventos futuros.',
+      },
+    ],
+  },
+};
+```
+
+## Fora de Escopo na V1
+
+- expansao em `cards` e `tiles`;
+- conteudo arbitrario via `html` como surface principal da expansao;
+- tabs dentro da expansao;
+- formulários inline dentro da detail row;
+- persistencia cross-page do estado aberto;
+- nesting de expansao dentro de expansao.
+
+## Acessibilidade e WCAG AA
+
+Requisitos minimos da implementacao:
+
+1. item expansivel deve expor `aria-expanded`;
+2. trigger por icone deve expor `aria-controls`;
+3. a regiao expandida deve ter `role="region"` e rotulo associado;
+4. foco por teclado deve permitir abrir/fechar sem mouse;
+5. contraste visual da area expandida deve respeitar AA;
+6. expansao nao deve depender apenas de cor para indicar estado.
+
+## Impacto Esperado
+
+Beneficios:
+
+- capacidade oficial para padroes de “linha + detalhe inline”;
+- melhor aderencia a cenarios enterprise densos;
+- playground, editor e examples passam a demonstrar capacidade real;
+- reduz pressao para criar componentes duplicados apenas por detail row.
+
+Tradeoffs:
+
+- aumenta a superficie do contrato publico;
+- exige testes adicionais de keyboard/focus/ARIA;
+- exige governanca de interacao com `selection`, `actions` e paginação remota.
+
+## Referencias
+
+- `projects/praxis-list/src/lib/models/list-config.model.ts`
+- `projects/praxis-list/src/lib/components/praxis-list.component.html`
+- `projects/praxis-list/src/lib/components/praxis-list.component.scss`
+- `projects/praxis-list/docs/adr/2026-03-list-authoring-protocol.md`
+- `praxis-ui-landing-page/issues/playground/problemas/referencia-list/img.png`
+- `praxis-ui-landing-page/issues/playground/problemas/referencia-list/img_1.png`

package/fesm2022/praxisui-list.mjs

@@ -6940,13 +6940,13 @@ const LIST_AI_CAPABILITIES = {
             path: 'actions[].globalAction.[actionId]',
             category: 'actions',
             valueKind: 'string',
-            description: 'Canonical global app action id (ex.: "toast.success").',
+            description: 'Canonical global app action id (ex.: "toast.success" ou "navigation.openRoute").',
         },
         {
             path: 'actions[].globalAction.payload',
             category: 'actions',
             valueKind: 'object',
-            description: 'Structured payload for the global app action (JSON/template).',
+            description: 'Structured payload for the global app action (JSON/template), including internal route payloads resolved from item context.',
         },
         {
             path: 'actions[].emitLocal',
@@ -10267,11 +10267,11 @@ class PraxisList {
     syncPaginatorIntl() {
         const locale = this.config?.i18n?.locale || this.hostLocale || 'en-US';
         const english = this.isEnglishLocaleValue(locale);
-        this.paginatorIntl.itemsPerPageLabel = this.t('pagination.itemsPerPage', english ? 'Items per page:' : 'Itens por página:');
-        this.paginatorIntl.nextPageLabel = this.t('pagination.nextPage', english ? 'Next page' : 'Próxima página');
-        this.paginatorIntl.previousPageLabel = this.t('pagination.previousPage', english ? 'Previous page' : 'Página anterior');
-        this.paginatorIntl.firstPageLabel = this.t('pagination.firstPage', english ? 'First page' : 'Primeira página');
-        this.paginatorIntl.lastPageLabel = this.t('pagination.lastPage', english ? 'Last page' : 'Última página');
+        this.paginatorIntl.itemsPerPageLabel = this.tWithLocale(locale, 'pagination.itemsPerPage', english ? 'Items per page:' : 'Itens por página:');
+        this.paginatorIntl.nextPageLabel = this.tWithLocale(locale, 'pagination.nextPage', english ? 'Next page' : 'Próxima página');
+        this.paginatorIntl.previousPageLabel = this.tWithLocale(locale, 'pagination.previousPage', english ? 'Previous page' : 'Página anterior');
+        this.paginatorIntl.firstPageLabel = this.tWithLocale(locale, 'pagination.firstPage', english ? 'First page' : 'Primeira página');
+        this.paginatorIntl.lastPageLabel = this.tWithLocale(locale, 'pagination.lastPage', english ? 'Last page' : 'Última página');
         this.paginatorIntl.getRangeLabel = (page, pageSize, length) => this.formatPaginatorRangeLabel(page, pageSize, length, locale);
         this.paginatorIntl.changes.next();
     }
@@ -10317,6 +10317,7 @@ class PraxisList {
         this.initializeDataStreams();
         this.config = normalizeListConfig(plan.canonicalConfig);
         this.appliedRuntimeConfig = this.config;
+        this.syncPaginatorIntl();
         this.syncExpansionState();
         if (plan.runtime?.applyConfig) {
             this.data.setConfig(this.config);
@@ -11041,6 +11042,9 @@ class PraxisList {
     t(key, fallback) {
         return this.i18n.t(key, undefined, fallback, PRAXIS_LIST_I18N_NAMESPACE);
     }
+    tWithLocale(locale, key, fallback) {
+        return this.i18n.tForLocale(locale, key, undefined, fallback, PRAXIS_LIST_I18N_NAMESPACE);
+    }
     ensureExpansionItemObjectId(value) {
         const current = this.expansionItemObjectIds.get(value);
         if (current)
@@ -12729,6 +12733,29 @@ const PRAXIS_LIST_AUTHORING_MANIFEST = {
             params: { id: 'edit', placement: 'actions', showLoading: true },
             isPositive: true,
         },
+        {
+            id: 'add-navigation-open-route-action',
+            request: 'Add an item action that opens the guide route with the selected employee id.',
+            operationId: 'item.action.add',
+            params: {
+                id: 'open-guide-route',
+                label: 'Abrir Guia',
+                icon: 'travel_explore',
+                kind: 'button',
+                buttonVariant: 'stroked',
+                globalAction: {
+                    actionId: 'navigation.openRoute',
+                    payload: {
+                        path: '/components-showcase/surface-open-guide',
+                        query: { funcionarioId: '${item.id}' },
+                        state: { funcionarioId: '${item.id}', source: 'surface-open-list-demo' },
+                    },
+                },
+                emitLocal: false,
+                showLoading: true,
+            },
+            isPositive: true,
+        },
         {
             id: 'remove-item-action-with-confirmation',
             request: 'Remove the edit action after confirmation.',

package/index.d.ts

@@ -730,6 +730,7 @@ declare class PraxisList implements OnInit, OnChanges, OnDestroy {
     private syncExpansionState;
     private itemExpansionKey;
     t(key: string, fallback: string): string;
+    private tWithLocale;
     private ensureExpansionItemObjectId;
     private sanitizeDomId;
     private evaluateExpansionExpr;

package/package.json

@@ -1,13 +1,19 @@
 {
   "name": "@praxisui/list",
-  "version": "8.0.0-beta.19",
+  "version": "8.0.0-beta.20",
   "description": "List components and helpers for Praxis UI.",
   "peerDependencies": {
     "@angular/common": ">=16 <21",
     "@angular/core": ">=16 <21",
     "@angular/material": ">=16 <21",
-    "@praxisui/dynamic-fields": "^8.0.0-beta.19",
-    "rxjs": ">=7 <9"
+    "@praxisui/dynamic-fields": "^8.0.0-beta.20",
+    "rxjs": ">=7 <9",
+    "@angular/forms": ">=16 <21",
+    "@angular/router": ">=16 <21",
+    "@praxisui/ai": "^8.0.0-beta.20",
+    "@praxisui/core": "^8.0.0-beta.20",
+    "@praxisui/rich-content": "^8.0.0-beta.20",
+    "@praxisui/settings-panel": "^8.0.0-beta.20"
   },
   "dependencies": {
     "tslib": "^2.3.0",