@praxisui/table 8.0.0-beta.30 → 8.0.0-beta.31

package/README.md

@@ -168,10 +168,21 @@ Filtro runtime:
 - The table assistant is part of the global Praxis semantic copilot experience, not a standalone table patch bot.
 - In customization mode, opening the assistant registers a `PraxisAssistantContextSnapshot` through `PraxisAssistantSessionRegistryService`.
 - The table session identity follows `table:{routeKey}:{componentInstanceId || tableId}` so multiple tables on the same page can preserve separate assistant sessions.
-- Minimizing the table shell keeps a global minimized session that the App Shell can reopen; the App Shell does not interpret or execute table semantics.
+- Minimizing the table shell keeps the governed session in `PraxisAssistantSessionRegistryService` with `presence: 'origin-anchor'`; the visual affordance returns to the table assistant trigger, which changes to the minimized state and reopens the preserved session. The App Shell does not interpret or execute table semantics.
 - The table snapshot stores only safe context: table identity, target, context chips, manifest reference, resource path, schema field names, data/runtime digests, capability refs and governance hints.
 - Prompts that indicate shared business decisions, such as rules, policies, compliance, LGPD, approval, eligibility or access control, must be routed to governed `domain-rules` handoff instead of local table config patches.
 
+### Consultative answers vs governed edits
+
+`@praxisui/table` declares two component-level response modes through its authoring context:
+
+- `consult/answer`: use when the user asks a factual or how-to question about the current table. Examples: "qual endpoint esta servindo esta tabela?", "quais campos existem nesta tabela?", "quais recursos de estilização a tabela suporta?" and "como criar uma coluna que soma duas colunas?".
+- `edit/componentEditPlan`: use when the user asks to apply or materialize a change. Examples: "mostre ativo como badge verde", "crie uma coluna bonus com 10% do salario", "deixe o avatar vermelho quando salario for maior que 30000" and "anime as linhas com salario acima de 30000".
+
+Consultative answers are selected by the backend/LLM from the component `responseModes` contract and return `type: "info"`. The table runtime must not classify user intent through local keywords; it only sends grounded context such as `resourcePath`, schema fields and the table authoring manifest, then renders the orchestrator response without an apply action. For how-to or documentation-style turns, the orchestrator should explain the governed operation shape and give a safe example instead of collecting missing edit parameters.
+
+Governed edits must be selected by the same backend/LLM response-mode decision and produce a validated `componentEditPlan`; the table compiles that plan into a patch and only then exposes the review/apply step.
+
 ## Migration Note
 
 - This release treats `enableCustomization=false` as the canonical default.
@@ -295,6 +306,29 @@ animacao. `rowConditionalRenderers` fica tipado no contrato publico para tooltip
 e animacao de linha, preservando os campos planos `tooltip`/`animation` como
 fallback.
 
+Animações condicionais devem ser authoradas como decisão semântica, não como CSS
+manual em `style.animation`. Para animar a linha inteira, use
+`rowConditionalRenderers[].animation`; para animar somente uma célula/coluna, use
+`columns[].conditionalRenderers[].animation`. Prefira presets semânticos
+(`info-soft`, `success-confirm`, `warning-attention`, `critical-alert`,
+`audit-review`, `sync-pending` ou aliases como `pulse-soft`, `sla-breach`,
+`risk-critical`) antes de `type` bruto. Exemplo:
+
+```ts
+rowConditionalRenderers: [
+  {
+    id: 'salario-alto-pulse',
+    condition: { '>': [{ var: 'salario' }, 30000] },
+    animation: { preset: 'pulse-soft', trigger: 'onAppear', intensity: 'subtle', repeat: 'once' },
+    enabled: true,
+  },
+]
+```
+
+`appearance.animations.enabled = false` desativa animações; os flags
+`appearance.animations.specific.row` e `appearance.animations.specific.cell`
+desativam seletivamente animações condicionais de linha e célula.
+
 Colunas calculadas usam `columns[].computed.expression` como AST JSON Logic
 canonico. Regras, estilos e renderers condicionais podem referenciar esses
 valores via `computed.<field>`. Quando uma coluna calculada depende de outra
@@ -1757,9 +1791,9 @@ Deteccao:
 - somente quando `FieldDefinition.controlType === 'avatar'`
 
 Renderer aplicado:
-- `renderer: { type: 'avatar', avatar: { srcField, initialsExpr, shape: 'circle', size: 28 } }`
+- `renderer: { type: 'avatar', avatar: { srcField, initialsField: 'nomeCompleto', shape: 'circle', size: 32 } }`
 - alinhamento central e largura compacta (~56px)
-- `initialsExpr` com fallback para `nomeCompleto|nome|fullName|name|title`
+- `initialsField` deriva as iniciais a partir de um campo textual bruto
 
 Avatar explicito:
 - `renderer: { type: 'avatar', avatar: { srcField, initialsExpr, initialsField, shape: 'circle', size: 28 } }`
@@ -1767,7 +1801,7 @@ Avatar explicito:
 - `initialsExpr` deve retornar as iniciais prontas; ele nao transforma automaticamente um campo bruto em iniciais
 - quando quiser derivar iniciais a partir de um campo textual, prefira `initialsField`
 - exemplo recomendado: `avatar: { srcField: 'photoUrl', initialsField: 'name' }`
-- exemplo de `initialsExpr` explicito: `avatar: { initialsExpr: \"= (row.name || '').trim().split(/\\s+/).slice(0,2).map(p => p[0] || '').join('').toUpperCase()\" }`
+- exemplo de `initialsExpr` explicito: `avatar: { initialsExpr: 'initials' }`
 
 Comportamento importante:
 - a autodeteccao ocorre apenas no bootstrap (nao sobrescreve configuracoes de colunas persistidas)
@@ -1777,8 +1811,11 @@ Comportamento importante:
 Ajustes comuns:
 - `renderer.avatar.shape`: `'square' | 'rounded' | 'circle'`
 - `renderer.avatar.size`: numero em px
+- `renderer.avatar.backgroundColor`: cor de fundo do circulo
+- `renderer.avatar.textColor`: cor das iniciais
 - `renderer.avatar.alt` / `altField`
 - use `conditionalRenderers` para variar renderer por linha
+- exemplo condicional: `condition: { ">": [{ "var": "salario" }, 30000] }` com `avatar: { initialsField: 'name', backgroundColor: '#D32F2F', textColor: '#FFFFFF' }`
 
 A11y, seguranca e performance:
 - `alt`/`altField` sao respeitados