@praxisui/table 10.0.0-rc.3 → 10.0.0-rc.31

package/README.md

@@ -98,6 +98,97 @@ The host demonstrates this at `/dynamic-page-lab/archetypes/bulk-partial`, using
 `praxis-dynamic-page.bulk-partial.ui-composition-plan.artifact.json`. The real
 backend proof creates and removes exclusive payroll-event fixtures.
 
+### Analytical drawer discovery
+
+The analytical drawer preserves explicit `drawerConfig` and DI-registered layouts. For a remote resource, it queries `/schemas/catalog` for the exact governed `POST {resourcePath}/filter` operation and follows that endpoint's published `schemaLinks.response`. Core `ResourceDiscoveryService` resolves root-relative discovery URLs against the API origin; `API_URL.default` can retain its `/api` prefix for resource requests. No match, multiple matches, a missing response href, or a schema without an explicit drawer layout leaves the remote layout absent. Discovery is cancelled and discarded on resource/context change or destroy; remote layouts are not retained across authorization-context changes.
+
+The drawer's existing explicit schema extensions (`x-ui.surfaces.drawer`, `x-ui.drawer`, or `behavior.drawer`) remain layout sources for hosts that publish them. They are not a Metadata surface-catalog contract: `/schemas/surfaces` publishes operation descriptors, never inferred drawer layouts, and a resource path must not be converted into a semantic resource key. The beta `PraxisAnalyticalDrawerComponent.surfaceName` input has been removed: it selected a layout from an unsupported surface-catalog response shape and had no internal consumers. External templates binding that input must remove the binding and supply their explicit layout through `drawerConfig` or the DI registry.
+
+### Governed synchronous update candidate
+
+For a remote resource whose collection capabilities explicitly publish an allowed
+`operations['bulk-update']` descriptor with `UNIFORM_UPDATE`, `SYNC`, `EXPLICIT`
+and `PER_ITEM`, the table offers **Atualizar seleção**. It is separate from the
+collection workflow actions above and from the configured one-step `bulkAction`.
+The table takes a detached snapshot of selected wire IDs and their canonical
+`self` links. Missing IDs/links, an unsupported descriptor or more than the
+published `maxTargets` disable the action. Each item is read from its exact
+`self` link for a strong quoted resource ETag before evaluation; a failed or
+changed identity prevents evaluation.
+
+The Quickstart candidate's existing uniform update operation is moving to an
+`ASYNC`-only profile, with host adoption still under validation. This BASIC table
+surface accepts `SYNC / EXPLICIT / PER_ITEM` and omits that `ASYNC`-only operation
+without a synchronous fallback. An ASYNC table workflow requires its own consumer
+acceptance; this note does not certify a Render deployment or an ASYNC UI journey.
+
+The transient Dynamic Form uses the descriptor's `editableFields.requestSchema`
+as an editor and emits a non-destructive payload preview. Its layout includes
+only the published writable fields; other controls from the full unit PUT schema
+are disabled at form readiness so unrelated required DTO properties do not turn
+the changed-field editor invalid. Its native submit
+action is hidden and implicit Enter submission is prevented. Only valid, dirty,
+published writable fields become `SET`; an explicitly changed `null` becomes
+`CLEAR` only for a published clearable field. Empty defaults do not clear data.
+The table evaluates the frozen selection, shows the server's READY/BLOCKED
+proposal and authorized paged per-item preview. It also shows the exact
+submitted SET/CLEAR fields and values as **requested change**, distinct from
+the server's preview. The current host's `redactedIntent` publishes selection
+summary only; it does not provide field values or old values. The table enables a separate human
+confirmation only after that preview loads. A confirmation retry retains the
+same session, proposal and Idempotency-Key after an uncertain response. HTTP 202
+and nonterminal states remain pending until an explicit status read; terminal
+per-item results are paged. Server authorization, expiry and conflict responses
+remain authoritative.
+
+An uncertain confirmation or pending execution keeps the same private table
+session and key while this table instance exists. Closing is disabled until a
+terminal state. A change of principal, tenant, organization, authorities, resource or resolved
+API context hides the panel immediately; returning to the same allowed context
+reattaches only after fresh authorized reads, without evaluating or confirming
+automatically. Destroying the host or reloading the page does not preserve this
+in-memory session. The backend remains the authority for recovery outside it.
+
+
+The synchronous uniform bulk workflow hides all retained projections, including the
+selection count, intent, totals, item identifiers and cursors, when a protected read
+or confirmation returns 401, 403, 404 or 410. The session, frozen intent and original
+confirmation key remain in table custody; an uncertain 503 never starts a new intent.
+Late responses from a previous authorization cannot restore hidden data or overwrite
+a newer read's loading/error state. Reopening any retained proposal requires fresh
+proposal and preview reads; execution recovery requires a fresh status and, when
+terminal, its result page. An already dispatched session request settles before
+recovery reads and is never cancelled or automatically repeated.
+
+Custody includes the canonical active organization as well as actor, tenant and
+operational context. Returning to that context remounts the workflow behind fresh
+authorization. A terminal mixed result presents all nine backend totals independently
+of how many result rows have been loaded. This in-memory custody does not promise
+continuity after a page reload or destruction of the owning table. The backend remains
+the authority for every mutation and protected read.
+
+
+BASIC selected-item, proposal, preview, execution and result GETs use the existing
+`behavior.loading.requestTimeoutMs` policy, captured for each read (default 30000 ms).
+Explicit 0 disables that deadline only when the host has another governed policy;
+view teardown still cancels the transport. This is the Table loading policy, not a
+new bulk timeout or the server unit deadline. Expiry releases local busy state and
+permits an explicit protected retry with the same proposal/execution and cursor;
+it neither declares a terminal execution nor proves that a mutation failed.
+
+The table-owned pending work contains only already dispatched evaluation/confirmation
+POSTs. Destroying a workflow cancels GET subscriptions and ignores stale callbacks;
+remount reads the same retained intent under fresh authorization, without waiting on
+an abandoned GET or repeating a POST. An uncertain pending POST remains in custody
+and is awaited, with its original key. Context denial still hides all protected
+projections, and recovery requires the complete fresh authorized read sequence.
+
+This first visual cut does not offer DOMAIN_COMMAND, PER_ITEM_UPDATE, QUERY,
+ASYNC, ATOMIC or durable jobs. The existing `bulk-partial` demo above uses its
+older collection action contract and does not certify this new candidate flow.
+The candidate is a library runtime change, not a live Quickstart acceptance or
+published UI release. Public examples and AI guidance need review before adoption.
+
 ## LLM Recommendation Guide
 
 - Recommend when: Angular apps need metadata-driven data grids with TableConfig, filtering, sorting, pagination, row actions, visual rules, detail rows, export, and AI-assisted authoring.
@@ -351,9 +442,11 @@ For row-specific corporate indicators, declare `*Expr` properties inside the vis
 
 Table-safe micro visualization kinds are `line`, `area`, `column`, `comparison`, `stackedBar`, `radial`, `harveyBall`, `bullet`, `delta`, and `processFlow`. For enterprise authoring, `delta`, `bullet`, `radial`, `harveyBall`, and `stackedBar` are recommended for rapid scanning in compact cells. `line`, `area`, and `column` are conditional on horizontal space; `comparison` is conditional because it increases row height; and `processFlow` is conditional because its steps must remain recognizable. Use an expanded row or related surface when those trade-offs do not directly support the decision. This is guidance rather than a runtime blocker, so existing governed documents remain faithfully rendered. If a row does not provide the minimum series/step data for a visual kind, the renderer keeps an accessible compact fallback with `role="img"` and the configured fallback or aria text.
 
+For `microVisualization` kinds that resolve numeric values (`delta`, `bullet`, `radial`, `harveyBall`, `line`, `area`, `column`, and `comparison`), `ColumnsConfigEditorComponent` provides visual authoring for `visualization.thresholds` (`min`, `max`, `tone`, reordering, removal, and a one-click traffic-light preset `0–39 danger`, `40–69 warning`, `70–100 success`) in both primary column renderers and `conditionalRenderers[]` overrides. In `PraxisPresentationVisualizationConfig`, an explicit fixed `visualization.tone` overrides `thresholds` unless `toneExpr` resolves at runtime; choosing **Automatic** (`tone` omitted) or adding/applying threshold bands clears the default fixed tone so `thresholds` take effect immediately, and the editor warns when both a fixed `tone` and `thresholds` are present. Thresholds use the Core condition vocabulary: discrete `equals` matches take priority, then numeric ranges (`min <= value <= max`, with open-ended `min` or `max` allowed) and progressive `value` cutoffs are evaluated in order. Existing `value` and `equals` conditions (including `0`, `false`, and strings) remain valid in primary and conditional renderers and survive tone edits, Apply and reopen; range controls do not convert them. Thresholds without a supported condition or with `min > max` fail renderer validation before Apply. The editor also includes a deterministic numeric sample strip (default `15, 40, 69, 70, 98`) so authors can verify threshold color transitions immediately without depending on generic string sample rows.
+
 A `conditionalRenderers[]` rule can materialize the same `microVisualization` contract when its Json Logic condition is true. Keep `surface: 'table-cell'`, the data property required by the selected kind, and `fallbackText`; first-match precedence still applies. Conditional visuals communicate a row state already defined by the canonical condition—they do not encode a new business rule in the table.
 
-The guided conditional-renderer editor covers icon, image, badge, link, button, chip, progress, avatar, rating, toggle, menu, HTML, compose layout and text items, and micro visualization. Link overrides support fixed or row-derived text and URLs; `_blank` links are rendered with a safe default `rel="noopener noreferrer"` when none is authored. Button and toggle overrides expose the canonical action id, JSON Logic disabled condition, and accessible label. Menu overrides bind the canonical row action collection; HTML overrides expose the existing template, sanitization, and fallback contract. Compose overrides intentionally guide only layout and text items; their other supported item documents remain preserved and continue through governed advanced JSON until dedicated controls exist.
+The guided conditional-renderer editor covers icon, image, badge, link, button, chip, progress, avatar, rating, toggle, menu, HTML, compose layout and text items, and micro visualization (including `thresholds` color bands). Link overrides support fixed or row-derived text and URLs; `_blank` links are rendered with a safe default `rel="noopener noreferrer"` when none is authored. Button and toggle overrides expose the canonical action id, JSON Logic disabled condition, and accessible label. Menu overrides bind the canonical row action collection; HTML overrides expose the existing template, sanitization, and fallback contract. Compose overrides intentionally guide only layout and text items; their other supported item documents remain preserved and continue through governed advanced JSON until dedicated controls exist.
 
 ### Enterprise rich-cell evidence lab
 
@@ -675,7 +768,7 @@ O editor de conteúdo da tabela recebe a configuração efetiva em contexto tran
 
 O editor do filtro permite selecionar o recurso e carregar seus campos pelo schema de filtro canônico. `resourcePath` e preferências visuais são persistidos; os metadados carregados permanecem derivados da API.
 
-Ao receber novos `filterCriteria` ou `queryContext` de outro widget, a consulta remota reinicia na página zero. Para um recurso paginado, selecione estratégia de paginação `server` no editor; a estratégia cliente continua sendo uma opção explícita para dados locais.
+Ao receber novos `filterCriteria` ou `queryContext` de outro widget, a consulta remota reinicia na página zero. Com a estratégia omitida, paginação e ordenação são inferidas da origem: `server` para remoto e `client` para local. O editor oferece **Automática (pela fonte de dados)**, que remove a propriedade; escolhas explícitas são preservadas. Consulte [a precedência oficial](docs/local-data-mode-precedence.md) para as regras de round-trip e validação do total remoto.
 
 ## Filter heading and advanced-action presentation
 

package/ai/component-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": "1.0.0",
-  "generatedAt": "2026-10-07T02:07:06.204Z",
+  "generatedAt": "2026-10-16T17:45:27.774Z",
   "packageName": "@praxisui/table",
-  "packageVersion": "10.0.0-rc.3",
+  "packageVersion": "10.0.0-rc.31",
   "sourceRegistry": "praxis-component-registry-ingestion",
   "sourceRegistryVersion": "1.0.0",
   "componentCount": 3,
@@ -7621,6 +7621,20 @@
           "type": "LoadingState",
           "required": false,
           "description": "Emitido quando a tabela muda de fase de carregamento no runtime"
+        },
+        {
+          "name": "queryContextClear",
+          "type": "PraxisTableQueryContextClearEvent",
+          "required": false,
+          "description": "Emitido quando um filtro cruzado ou queryContext ativo é removido na toolbar da tabela",
+          "label": "Filtro cruzado limpo"
+        },
+        {
+          "name": "queryContextChange",
+          "type": "PraxisDataQueryContext",
+          "required": false,
+          "description": "Emitido quando o queryContext interno da tabela é modificado por interações locais ou remoção de filtros",
+          "label": "Query Context alterado"
         }
       ],
       "configSchemaId": "TableConfig",
@@ -8006,6 +8020,40 @@
             "public": true,
             "group": "status"
           }
+        },
+        {
+          "id": "queryContextClear",
+          "label": "Query Context Clear",
+          "direction": "output",
+          "semanticKind": "event",
+          "schema": {
+            "id": "PraxisTableQueryContextClearEvent",
+            "kind": "structural-shape",
+            "ref": "{ tableId?: string; clearedFields: string[]; remainingFilterCount: number }"
+          },
+          "cardinality": "stream",
+          "description": "Evento emitido quando filtros externos ou cruzados vinculados ao queryContext sao removidos da toolbar.",
+          "exposure": {
+            "public": true,
+            "group": "data"
+          }
+        },
+        {
+          "id": "queryContextChange",
+          "label": "Query Context Change",
+          "direction": "output",
+          "semanticKind": "query-context",
+          "schema": {
+            "id": "PraxisDataQueryContext",
+            "kind": "ts-type",
+            "ref": "PraxisDataQueryContext"
+          },
+          "cardinality": "stream",
+          "description": "Contexto de consulta atualizado apos reconciliacao ou limpeza de filtros editaveis na regiao unica de filtros da tabela.",
+          "exposure": {
+            "public": true,
+            "group": "data"
+          }
         }
       ],
       "runtimeProfiles": [
@@ -31301,9 +31349,9 @@
         {
           "chunkIndex": 0,
           "chunkKind": "summary",
-          "content": "Component ID: praxis-table\nSelector: praxis-table\nFriendly Name: Praxis Table\nDescription: Tabela interativa com paginação, ordenação e ações em massa.\nCategory: table\nLib/Package: @praxisui/table\nTags: widget, table, configurable, hasWizard, stable\nInputs:\n  - config (TableConfig)\n  - resourcePath (string)\n  - data (any[])\n  - configPersistenceStrategy ('local-first' | 'input-first' | 'volatile')\n  - queryContext (PraxisDataQueryContext | null)\n  - aiContext (TableAiContext | null)\n  - aiAssistantVoiceInputMode ('disabled' | 'browser-speech')\n  - aiAssistantVoiceLanguage (string)\n  - filterCriteria (Record<string, any>)\n  - autoDelete (boolean)\n  - enableCustomization (boolean)\n  - authoringCapability (string)\n  - dense (boolean)\n  - horizontalScroll ('auto' | 'wrap' | 'none')\n  - tableId (string)\n  - componentInstanceId (string)\n  - title (string)\n  - subtitle (string)\n  - icon (string)\n  - notifyIfOutdated ('inline' | 'snackbar' | 'both' | 'none')\n  - snoozeMs (number)\n  - autoOpenSettingsOnOutdated (boolean)\n  - crudContext (any)\nOutputs:\n  - rowClick ({ row: any; index: number })\n  - widgetEvent (WidgetEventEnvelope)\n  - resourceEvent (PraxisResourceEvent)\n  - rowDoubleClick ({ action: string; row: any })\n  - rowExpansionChange (RowExpansionChangeEvent)\n  - selectionChange ({ trigger: string; row?: any; selectedRows: any[]; selectedCount: number; tableId?: string })\n  - rowAction ({ action: string; row: any })\n  - toolbarAction ({ action: string })\n  - bulkAction ({ action: string; rows: any[] })\n  - columnReorder ({ action: string; trigger: \"drag\" | \"keyboard\" | \"undo\"; operationId: number; tableId: string; sourceField: string; targetField: string; previousIndex: number; currentIndex: number; sourceZone: \"start\" | \"center\" | \"end\"; targetZone: \"start\" | \"center\" | \"end\"; previousOrder: string[]; currentOrder: string[]; persisted: boolean })\n  - columnReorderAttempt ({ action: \"columnReorderAttempt\"; trigger: \"drag\" | \"keyboard\"; operationId: number; tableId: string; sourceField: string; targetField: string; previousIndex: number; currentIndex: number; sourceZone: \"start\" | \"center\" | \"end\"; targetZone: \"start\" | \"center\" | \"end\"; result: \"blocked\"; reasonCode: \"drop-zone-policy-blocked\"; configuredColumnDropZones: string[] })\n  - beforeDelete (any)\n  - afterDelete (any)\n  - deleteError ({ row: any; error: unknown })\n  - beforeBulkDelete (any[])\n  - afterBulkDelete (any[])\n  - bulkDeleteError ({ rows: any[]; error: unknown })\n  - schemaStatusChange ({ outdated: boolean; serverHash?: string; lastVerifiedAt?: string; trigger?: string; tableId?: string })\n  - metadataChange ({ trigger: string; meta: any; tableId?: string })\n  - configChange (TableConfig)\n  - loadingStateChange (LoadingState)\nInsertion Presets:\n  - page-table: Tabela da página - Configuração autorada no Page Builder, com prioridade sobre preferências anteriores da tabela.\n",
+          "content": "Component ID: praxis-table\nSelector: praxis-table\nFriendly Name: Praxis Table\nDescription: Tabela interativa com paginação, ordenação e ações em massa.\nCategory: table\nLib/Package: @praxisui/table\nTags: widget, table, configurable, hasWizard, stable\nInputs:\n  - config (TableConfig)\n  - resourcePath (string)\n  - data (any[])\n  - configPersistenceStrategy ('local-first' | 'input-first' | 'volatile')\n  - queryContext (PraxisDataQueryContext | null)\n  - aiContext (TableAiContext | null)\n  - aiAssistantVoiceInputMode ('disabled' | 'browser-speech')\n  - aiAssistantVoiceLanguage (string)\n  - filterCriteria (Record<string, any>)\n  - autoDelete (boolean)\n  - enableCustomization (boolean)\n  - authoringCapability (string)\n  - dense (boolean)\n  - horizontalScroll ('auto' | 'wrap' | 'none')\n  - tableId (string)\n  - componentInstanceId (string)\n  - title (string)\n  - subtitle (string)\n  - icon (string)\n  - notifyIfOutdated ('inline' | 'snackbar' | 'both' | 'none')\n  - snoozeMs (number)\n  - autoOpenSettingsOnOutdated (boolean)\n  - crudContext (any)\nOutputs:\n  - rowClick ({ row: any; index: number })\n  - widgetEvent (WidgetEventEnvelope)\n  - resourceEvent (PraxisResourceEvent)\n  - rowDoubleClick ({ action: string; row: any })\n  - rowExpansionChange (RowExpansionChangeEvent)\n  - selectionChange ({ trigger: string; row?: any; selectedRows: any[]; selectedCount: number; tableId?: string })\n  - rowAction ({ action: string; row: any })\n  - toolbarAction ({ action: string })\n  - bulkAction ({ action: string; rows: any[] })\n  - columnReorder ({ action: string; trigger: \"drag\" | \"keyboard\" | \"undo\"; operationId: number; tableId: string; sourceField: string; targetField: string; previousIndex: number; currentIndex: number; sourceZone: \"start\" | \"center\" | \"end\"; targetZone: \"start\" | \"center\" | \"end\"; previousOrder: string[]; currentOrder: string[]; persisted: boolean })\n  - columnReorderAttempt ({ action: \"columnReorderAttempt\"; trigger: \"drag\" | \"keyboard\"; operationId: number; tableId: string; sourceField: string; targetField: string; previousIndex: number; currentIndex: number; sourceZone: \"start\" | \"center\" | \"end\"; targetZone: \"start\" | \"center\" | \"end\"; result: \"blocked\"; reasonCode: \"drop-zone-policy-blocked\"; configuredColumnDropZones: string[] })\n  - beforeDelete (any)\n  - afterDelete (any)\n  - deleteError ({ row: any; error: unknown })\n  - beforeBulkDelete (any[])\n  - afterBulkDelete (any[])\n  - bulkDeleteError ({ rows: any[]; error: unknown })\n  - schemaStatusChange ({ outdated: boolean; serverHash?: string; lastVerifiedAt?: string; trigger?: string; tableId?: string })\n  - metadataChange ({ trigger: string; meta: any; tableId?: string })\n  - configChange (TableConfig)\n  - loadingStateChange (LoadingState)\n  - queryContextClear (PraxisTableQueryContextClearEvent)\n  - queryContextChange (PraxisDataQueryContext)\nInsertion Presets:\n  - page-table: Tabela da página - Configuração autorada no Page Builder, com prioridade sobre preferências anteriores da tabela.\n",
           "sourcePointer": "projects/praxis-table/src/lib/praxis-table.metadata.ts",
-          "contentHash": "64d2a59402198b1eccbeaa937ba155379b3409b1d3f1d695e2f17b73b66f7447",
+          "contentHash": "190f781b06cc93cae5292f354b0a1a09ae4fd0ee9007180e6f1e21ceb82a45ad",
           "sourceKind": "component_definition",
           "sourceId": "praxis-table",
           "corpusVersion": "1.0.0"

package/docs/local-data-mode-precedence.md

@@ -11,6 +11,27 @@ Regras de conflito:
 - `resourcePath` + `data` ao mesmo tempo resolve para `remote`.
 - Limpar `document.bindings.resourcePath` no documento autorado é a forma explícita de remover a conexão remota via editor.
 
+## Estratégia contextual de paginação e ordenação
+
+`pagination.strategy` e `sorting.strategy` são opcionais. Quando ausentes, o
+runtime usa `server` para uma origem remota e `client` para dados locais. Os
+defaults compartilhados e o reset dos editores preservam essa ausência; não
+transformam uma configuração parcial em uma escolha explícita de cliente.
+
+Os editores apresentam **Automática (pela fonte de dados)**. Essa opção
+remove a propriedade do documento. As únicas estratégias públicas continuam
+sendo `client` e `server`; não existe um valor serializado `auto`. Uma escolha
+explícita é preservada, respeitando as restrições e diagnostics do modo local.
+Uma operação parcial de authoring que omite a estratégia mantém uma escolha
+anterior; omissão em um patch não significa limpar essa escolha.
+
+Na paginação remota, o total vem da resposta do backend. O paginator e o sort
+cliente do `MatTableDataSource` não devem ser anexados nessa estratégia, pois
+seus callbacks assíncronos podem substituir o total pela quantidade de registros
+da página e voltar o índice para zero. A prova deve aguardar esses callbacks e
+as materializações de capabilities, navegar à segunda página e confirmar que o
+total e o intervalo continuam corretos. Uma captura intermediária não basta.
+
 ## Ciclo da primeira consulta remota
 
 Quando `resourcePath`, `config` e `queryContext` chegam no primeiro ciclo de inputs, o