@praxisui/list 8.0.0-beta.2 → 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`