@praxisui/list 9.0.0-beta.73 → 9.0.0-beta.74

package/README.md

@@ -115,6 +115,7 @@ Remote controls are rendered when `resourcePath` is present. The runtime uses `/
 - Template expressions use `${item.field}`. Currency/date/number templates can use config i18n defaults.
 - Selection supports `none`, `single` and `multiple`, with return modes `value`, `item` or `id`.
 - Item actions can emit local events or delegate to `GlobalActionService`; collection export uses the shared `@praxisui/core` contract for `csv`, `json`, `excel`, `pdf` and `print`.
+- A governed `actions[].recordOpen` resolves the identity declared by the backend against the current-principal resource and contextual surface catalogs before executing `surface.open`; it never derives the target from the displayed label or from `item.id`.
 
 ## Known Runtime Boundaries
 
@@ -126,6 +127,8 @@ Do not document those as active runtime behavior in app-specific guides until th
 
 `enableCustomization` opens the canonical list editor and semantic assistant flow. `PRAXIS_LIST_AUTHORING_MANIFEST` is the executable authoring contract for template slots, actions, empty state, selection, layout, data binding, rules, skin, export, localization, accessibility and declared-only warnings.
 
+`actions[].recordOpen` is runtime materialization evidence produced by governed platform authoring. It round-trips through list config but is intentionally not a free-form field in the visual editor or the list-specific AI manifest. Authors choose business intent; Metadata and Config publish the canonical source field and target identities.
+
 Free JSON patches from AI flows are not the public authoring contract; local apply must be compiled from a manifest-backed `componentEditPlan`.
 
 ## Public API Snapshot

package/ai/component-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": "1.0.0",
-  "generatedAt": "2026-07-12T01:34:40.567Z",
+  "generatedAt": "2026-07-16T21:05:04.797Z",
   "packageName": "@praxisui/list",
-  "packageVersion": "9.0.0-beta.73",
+  "packageVersion": "9.0.0-beta.74",
   "sourceRegistry": "praxis-component-registry-ingestion",
   "sourceRegistryVersion": "1.0.0",
   "componentCount": 1,

package/fesm2022/praxisui-list.mjs

@@ -7,7 +7,7 @@ import * as i3 from '@angular/material/list';
 import { MatListModule } from '@angular/material/list';
 import * as i4 from '@angular/material/icon';
 import { MatIconModule } from '@angular/material/icon';
-import { resolveValuePresentation, LoggerService, GenericCrudService, toTitleCase, PraxisIconDirective, validateGlobalActionRefs, providePraxisI18n, PraxisI18nService, IconPickerService, GLOBAL_ACTION_CATALOG, PRAXIS_GLOBAL_ACTION_CATALOG, getGlobalActionCatalog, SURFACE_OPEN_I18N_NAMESPACE, getGlobalActionUiSchema, SurfaceOpenActionEditorComponent, PRAXIS_I18N_CONFIG, providePraxisI18nConfig, SURFACE_OPEN_I18N_CONFIG, deepMerge, ASYNC_CONFIG_STORAGE, ComponentKeyService, PraxisJsonLogicService, PraxisCollectionExportService, GlobalActionService, GLOBAL_DIALOG_SERVICE, assertPraxisCollectionExportArtifact, normalizePraxisDataQueryContext, ComponentMetadataRegistry, API_URL, LocalStorageAsyncAdapter, LocalStorageConfigService } from '@praxisui/core';
+import { resolveValuePresentation, LoggerService, GenericCrudService, toTitleCase, PraxisIconDirective, validateGlobalActionRefs, providePraxisI18n, PraxisI18nService, IconPickerService, GLOBAL_ACTION_CATALOG, PRAXIS_GLOBAL_ACTION_CATALOG, getGlobalActionCatalog, SURFACE_OPEN_I18N_NAMESPACE, getGlobalActionUiSchema, SurfaceOpenActionEditorComponent, PRAXIS_I18N_CONFIG, providePraxisI18nConfig, SURFACE_OPEN_I18N_CONFIG, deepMerge, ASYNC_CONFIG_STORAGE, ComponentKeyService, PraxisJsonLogicService, PraxisCollectionExportService, ResourceRecordOpenService, GlobalActionService, GLOBAL_DIALOG_SERVICE, ResourceRecordOpenError, assertPraxisCollectionExportArtifact, normalizePraxisDataQueryContext, ComponentMetadataRegistry, API_URL, LocalStorageAsyncAdapter, LocalStorageConfigService } from '@praxisui/core';
 import * as i5 from '@angular/material/chips';
 import { MatChipsModule } from '@angular/material/chips';
 import { MatDividerModule } from '@angular/material/divider';
@@ -3644,6 +3644,7 @@ const PRAXIS_LIST_EN_US = {
     itemDetails: 'Item details',
     emptyState: 'No items available',
     emptyStateConnectResource: 'Connect this list to a resource to load items.',
+    recordOpenUnavailable: 'Unable to open details for this item.',
     'pagination.itemsPerPage': 'Items per page:',
     'pagination.nextPage': 'Next page',
     'pagination.previousPage': 'Previous page',
@@ -4004,6 +4005,7 @@ const PRAXIS_LIST_PT_BR = {
     itemDetails: 'Detalhes do item',
     emptyState: 'Nenhum item disponível',
     emptyStateConnectResource: 'Conecte a lista a um recurso para carregar os itens.',
+    recordOpenUnavailable: 'Não foi possível abrir os detalhes deste item.',
     'pagination.itemsPerPage': 'Itens por página:',
     'pagination.nextPage': 'Próxima página',
     'pagination.previousPage': 'Página anterior',
@@ -4258,7 +4260,7 @@ const PRAXIS_LIST_PT_BR = {
     Width: 'Largura',
     'Min width': 'Largura mínima',
     'Max width': 'Largura máxima',
-    Justify: 'Justificar',
+    'Justify': 'Justificar',
     'Move column left': 'Mover coluna para a esquerda',
     'Move column right': 'Mover coluna para a direita',
     'Remove column': 'Remover coluna',
@@ -12534,6 +12536,7 @@ class PraxisList {
     jsonLogic = inject(PraxisJsonLogicService);
     i18n = inject(PraxisI18nService);
     collectionExport = inject(PraxisCollectionExportService);
+    recordOpenResolver = inject(ResourceRecordOpenService);
     paginatorIntl = inject(MatPaginatorIntl);
     snackBar = inject(MatSnackBar);
     aiApi = inject(AiBackendApiService);
@@ -13522,11 +13525,18 @@ class PraxisList {
                 return;
         }
         const globalAction = action?.globalAction;
+        const recordOpenIntent = action?.action === 'surface.open';
+        const recordOpenReference = recordOpenIntent
+            ? action?.recordOpen
+            : undefined;
         const loadingKey = this.buildActionLoadingKey(actionId, item, index);
         if (action?.showLoading)
             this.actionLoadingState[loadingKey] = true;
         try {
-            if (globalAction?.actionId) {
+            if (recordOpenIntent) {
+                await this.executeRecordOpenAction(actionId, recordOpenReference, item);
+            }
+            else if (globalAction?.actionId) {
                 const hasConfiguredPayload = Object.prototype.hasOwnProperty.call(globalAction, 'payload');
                 const shouldUseDefaultPayload = !hasConfiguredPayload && !globalAction.payloadExpr;
                 const payload = hasConfiguredPayload
@@ -13553,7 +13563,10 @@ class PraxisList {
             }
         }
         catch (error) {
-            if (isDevMode()) {
+            if (recordOpenIntent) {
+                this.reportRecordOpenFailure(actionId, recordOpenReference, error);
+            }
+            else if (isDevMode()) {
                 this.logger.warn('[PraxisList] global action execution failed.', this.buildLogOptions({ globalActionId: globalAction?.actionId, actionId, error }, {
                     context: { actionId },
                     throttleKey: `praxis-list:global-action-execution-failed:${actionId}`,
@@ -13564,11 +13577,54 @@ class PraxisList {
             if (action?.showLoading)
                 delete this.actionLoadingState[loadingKey];
         }
-        const emitLocal = action?.emitLocal ?? !globalAction?.actionId;
+        const emitLocal = action?.emitLocal ?? (!recordOpenIntent && !globalAction?.actionId);
         if (emitLocal) {
             this.actionClick.emit({ actionId, item, index });
         }
     }
+    async executeRecordOpenAction(actionId, reference, item) {
+        if (!reference) {
+            throw new ResourceRecordOpenError('INVALID_REFERENCE', 'List record-open action is missing its governed reference.');
+        }
+        if (!this.globalActions) {
+            throw new Error('GlobalActionService is unavailable for surface.open.');
+        }
+        const resolution = await firstValueFrom(this.recordOpenResolver.resolve(reference, item));
+        const result = await this.globalActions.executeRef({ actionId: 'surface.open', payload: resolution.payload }, {
+            sourceId: this.listId,
+            output: 'actionClick',
+            payload: resolution.payload,
+            runtime: { item },
+            meta: {
+                actionId,
+                resourceKey: reference.target.resourceKey,
+                resourceId: resolution.resourceId,
+                surfaceId: resolution.surface.id,
+            },
+        });
+        if (result && !result.success) {
+            throw new Error(result.error || 'The surface.open executor rejected the resolved payload.');
+        }
+    }
+    reportRecordOpenFailure(actionId, reference, error) {
+        const failureCode = error instanceof ResourceRecordOpenError
+            ? error.code
+            : 'EXECUTION_FAILED';
+        if (isDevMode()) {
+            this.logger.warn('[PraxisList] contextual record-open failed.', this.buildLogOptions({
+                globalActionId: 'surface.open',
+                actionId,
+                resourceKey: reference?.target.resourceKey,
+                surfaceId: reference?.target.surfaceId,
+                failureCode,
+                error,
+            }, {
+                context: { actionId },
+                throttleKey: `praxis-list:record-open-failed:${actionId}:${failureCode}`,
+            }));
+        }
+        this.snackBar.open(this.t('recordOpenUnavailable', 'Unable to open details for this item.'), undefined, { duration: 4000 });
+    }
     resolveActionPayload(raw, item, index) {
         if (raw == null)
             return { item, index };

package/package.json

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

package/src/lib/editors/praxis-list-config-editor.json-api.md

@@ -335,6 +335,7 @@ A integracao com host ocorre por `SettingsValueProvider`:
 | `actions[].id/icon/label/color/kind/buttonVariant/showIf/placement` | Active | Authoring completo de acoes por item; `showIf` usa Json Logic serializavel e `placement` controla a regiao visual da acao. |
 | `actions[].globalAction/emitLocal/showLoading/confirmation` | Active | Suporte a acoes globais estruturadas, confirmacao para acoes locais e globais, loading por acao e emissao local opcional. |
 | `actions[].globalAction.payload/payloadExpr` | Active | `payload` estruturado e `payloadExpr` avancado sao editaveis; ao definir um deles, o editor remove o outro para manter semantica canonica de execucao. |
+| `actions[].action/recordOpen` | Runtime-governed | Preservado no round-trip, mas nao editavel: Metadata/Config publicam a referencia minima e o runtime reconsulta a surface contextual. |
 | `actions[].emitPayload` | Declared-only | Preservado em JSON/config round-trip; nao aparece no editor visual de Ações porque nao altera o payload nativo da lista. |
 | `ui.showSearch/searchField/searchPlaceholder` | Active | Bloco de busca. |
 | `ui.showSort/sortOptions` | Active | Editor visual com deteccao de duplicatas. |

package/src/lib/praxis-list.json-api.md

@@ -687,6 +687,8 @@ Notas de UX/WCAG:
 | `actions[].buttonVariant`        | Active        | `stroked/raised/flat`                                       |
 | `actions[].showIf`               | Active        | condição Json Logic avaliada no contexto `row`              |
 | `actions[].emitPayload`          | Declared-only | sem uso no payload de ações nativas; ações `rich-content` hospedadas podem emitir `payload?` próprio |
+| `actions[].action`               | Active        | `surface.open` identifica a execução contextual governada quando acompanhada de `recordOpen` |
+| `actions[].recordOpen`           | Active        | referência mínima `{ sourceIdentityField, target: { resourceKey, surfaceId } }`; o runtime reconsulta catálogo, item e `_links.surfaces` antes de materializar |
 | `actions[].globalAction`         | Active        | integra com `GlobalActionService.executeRef`; suporta `navigation.openRoute` para navegação interna canônica |
 | `actions[].globalAction.actionId` | Active       | identificador canonico da acao global                        |
 | `actions[].globalAction.payload` | Active        | template/JSON resolvido recursivamente, inclusive `item.id` em rotas internas |
@@ -700,9 +702,12 @@ Notas de UX/WCAG:
 Semantica de execucao:
 
 1. valida confirmacao (quando configurada);
-2. executa acao global estruturada (se `globalAction` estiver presente), incluindo `navigation.openRoute` para abrir rotas internas com contexto do item;
-3. remove loading;
-4. emite `actionClick` conforme regra `emitLocal`.
+2. quando `action='surface.open'`, exige `recordOpen`, extrai somente o `sourceIdentityField` declarado, reconsulta o recurso e a surface contextual do principal corrente e falha fechado se qualquer identidade/availability divergir;
+3. fora desse fluxo, executa acao global estruturada (se `globalAction` estiver presente), incluindo `navigation.openRoute` para abrir rotas internas com contexto do item;
+4. remove loading;
+5. emite `actionClick` conforme regra `emitLocal`; uma intencao `recordOpen` nao cai em emissao local por default quando a resolucao falha.
+
+`recordOpen` e materializacao governada de runtime e round-trip. O editor visual e o manifesto AI local nao authoram esse campo livremente; a fonte e a projection validada por Metadata/Config.
 
 #### UI, i18n, a11y e events
 
@@ -868,6 +873,8 @@ AI:
 | `actions[].buttonVariant`              | Active        | raised/flat/stroked                    |
 | `actions[].showIf`                     | Active        | visibilidade                           |
 | `actions[].emitPayload`                | Declared-only | sem efeito runtime                     |
+| `actions[].action`                     | Active        | `surface.open` contextual governado    |
+| `actions[].recordOpen`                 | Active        | identidade mínima resolvida por catálogo e HATEOAS |
 | `actions[].globalAction`               | Active        | acao global estruturada                |
 | `actions[].globalAction.actionId`      | Active        | identificador canonico da acao global  |
 | `actions[].globalAction.payload`       | Active        | payload template/json                  |

package/types/praxisui-list.d.ts

@@ -6,7 +6,7 @@ import { MatSelectionListChange } from '@angular/material/list';
 import { MatPaginatorSelectConfig, PageEvent } from '@angular/material/paginator';
 import { FormGroup, FormControl } from '@angular/forms';
 import * as _praxisui_core from '@praxisui/core';
-import { PraxisExportFormat, PraxisExportScope, PraxisRuntimeConditionalEffectRule, JsonLogicExpression, RichContentDocument, GlobalActionRef, LocalizationConfig, AiCapability, PraxisDataQueryContext, RichBlockNode, RichBlockHostCapabilities, GlobalActionCatalogEntry, SurfaceOpenPayload, SettingsValueProvider as SettingsValueProvider$1, RichPresenterNode, RichComposeNode, ComponentDocMeta, AiCapabilityCategory, AiCapabilityCatalog, AiValueKind, ComponentAuthoringManifest } from '@praxisui/core';
+import { PraxisExportFormat, PraxisExportScope, PraxisRuntimeConditionalEffectRule, JsonLogicExpression, RichContentDocument, ResourceRecordOpenRef, GlobalActionRef, LocalizationConfig, AiCapability, PraxisDataQueryContext, RichBlockNode, RichBlockHostCapabilities, GlobalActionCatalogEntry, SurfaceOpenPayload, SettingsValueProvider as SettingsValueProvider$1, RichPresenterNode, RichComposeNode, ComponentDocMeta, AiCapabilityCategory, AiCapabilityCatalog, AiValueKind, ComponentAuthoringManifest } from '@praxisui/core';
 import { BaseAiAdapter, AiResponseCompileResult, PatchResult, PraxisAssistantTurnViewState, PraxisAssistantShellLayout, PraxisAssistantShellLabels, PraxisAssistantSessionSnapshot, PraxisAssistantShellQuickReply, PraxisAssistantShellMessage } from '@praxisui/ai';
 import { SettingsValueProvider } from '@praxisui/settings-panel';
 import * as _praxisui_list from '@praxisui/list';
@@ -294,6 +294,8 @@ interface PraxisListConfig {
         buttonVariant?: 'stroked' | 'raised' | 'flat';
         showIf?: JsonLogicExpression | null;
         emitPayload?: 'item' | 'id' | 'value';
+        action?: 'surface.open';
+        recordOpen?: ResourceRecordOpenRef;
         globalAction?: GlobalActionRef;
         emitLocal?: boolean;
         showLoading?: boolean;
@@ -521,6 +523,7 @@ declare class PraxisList implements OnInit, OnChanges, AfterViewInit, OnDestroy
     private readonly jsonLogic;
     private readonly i18n;
     private readonly collectionExport;
+    private readonly recordOpenResolver;
     private readonly paginatorIntl;
     private readonly snackBar;
     private readonly aiApi;
@@ -652,6 +655,8 @@ declare class PraxisList implements OnInit, OnChanges, AfterViewInit, OnDestroy
         buttonVariant?: "stroked" | "raised" | "flat";
         showIf?: JsonLogicExpression | null;
         emitPayload?: "item" | "id" | "value";
+        action?: "surface.open";
+        recordOpen?: ResourceRecordOpenRef;
         globalAction?: GlobalActionRef;
         emitLocal?: boolean;
         showLoading?: boolean;
@@ -673,6 +678,8 @@ declare class PraxisList implements OnInit, OnChanges, AfterViewInit, OnDestroy
     emptyStateLabel(): string;
     isResourceConnectionMissing(): boolean;
     onActionClick(ev: MouseEvent, actionId: string, item: any, index: number): Promise<void>;
+    private executeRecordOpenAction;
+    private reportRecordOpenFailure;
     private resolveActionPayload;
     private resolveTemplate;
     private isDeferredTemplateExpressionKey;
@@ -2049,6 +2056,8 @@ declare class PraxisListDocPageComponent {
                 buttonVariant?: "stroked" | "raised" | "flat";
                 showIf?: _praxisui_core.JsonLogicExpression | null;
                 emitPayload?: "item" | "id" | "value";
+                action?: "surface.open";
+                recordOpen?: _praxisui_core.ResourceRecordOpenRef;
                 globalAction?: _praxisui_core.GlobalActionRef;
                 emitLocal?: boolean;
                 showLoading?: boolean;
@@ -2119,6 +2128,7 @@ declare const PRAXIS_LIST_EN_US: {
     readonly itemDetails: "Item details";
     readonly emptyState: "No items available";
     readonly emptyStateConnectResource: "Connect this list to a resource to load items.";
+    readonly recordOpenUnavailable: "Unable to open details for this item.";
     readonly 'pagination.itemsPerPage': "Items per page:";
     readonly 'pagination.nextPage': "Next page";
     readonly 'pagination.previousPage': "Previous page";
@@ -2482,6 +2492,7 @@ declare const PRAXIS_LIST_PT_BR: {
     readonly itemDetails: "Detalhes do item";
     readonly emptyState: "Nenhum item disponível";
     readonly emptyStateConnectResource: "Conecte a lista a um recurso para carregar os itens.";
+    readonly recordOpenUnavailable: "Não foi possível abrir os detalhes deste item.";
     readonly 'pagination.itemsPerPage': "Itens por página:";
     readonly 'pagination.nextPage': "Próxima página";
     readonly 'pagination.previousPage': "Página anterior";