@praxisui/expansion 8.0.0-beta.2 → 8.0.0-beta.20

package/README.md

@@ -130,9 +130,37 @@ const expansionConfig: ExpansionMetadata = {
 };
 ```
 
+## Nested Ports e Conexoes
+
+Para conectar widgets dentro de paineis a estado ou widgets externos, use `composition.links` com endpoint `component-port + nestedPath`.
+
+Exemplo de output de chart dentro do painel `analytics`:
+
+```json
+{
+  "kind": "component-port",
+  "ref": {
+    "widget": "expansion-widget",
+    "nestedPath": [
+      { "kind": "panel", "id": "analytics", "index": 0 },
+      { "kind": "widget", "key": "payroll-chart", "componentType": "praxis-chart" }
+    ],
+    "port": "pointClick",
+    "direction": "output"
+  }
+}
+```
+
+Regras:
+
+- `ref.widget` e a instancia top-level de `praxis-expansion`;
+- o segmento terminal deve ser `kind: "widget"` com `key` estavel;
+- `widgetEvent` permanece como bridge avancada/legado, nao como contrato principal;
+- inputs nested devem atualizar o config declarativo do widget filho, inclusive quando o painel ainda nao montou por lazy loading.
+
 ## Action Row por painel
 
-Adicione botões de ação no rodapé do painel com `actionButtons`. O evento é reemitido via `widgetEvent` com `output: 'action'`.
+Adicione botões de ação no rodapé do painel com `actionButtons`. O evento é reemitido via `widgetEvent` com `output: 'action'`; trate esse fluxo como bridge avancada/legado para acoes de painel, nao como modelo principal de nested component ports.
 
 ```ts
 const expansionConfig: ExpansionMetadata = {
@@ -205,6 +233,33 @@ O componente expõe métodos para controlar a expansão por índice (numérico)
 
 Cada evento inclui `{ panelId?: string; panelIndex: number }` (ou `expanded: boolean` no caso de `expandedChange`).
 
+## Agentic Authoring
+
+O contrato executavel de authoring fica em `PRAXIS_EXPANSION_AUTHORING_MANIFEST`.
+Ele modela edicoes em `ExpansionMetadata` por operacoes atomicas sobre paineis,
+cabecalhos, conteudo lazy, estado expandido/desabilitado e comportamento do
+accordion.
+
+Cobertura principal:
+
+- `panel.add`, `panel.remove`, `panel.order.set`
+- `panel.title.set`, `panel.description.set`, `panel.icon.set`
+- `panel.disabled.set`
+- `behavior.multiExpand.set`
+- `behavior.defaultExpanded.set`
+- `panel.content.set`
+
+As operacoes preservam `panels[].id` como identidade canonica. Remover um painel
+com `content`, `widgets` ou `actionButtons` exige confirmacao explicita. Quando
+`accordion.multi` estiver desabilitado, somente um painel pode ficar expandido por
+padrao; o authoring deve colapsar os demais ou falhar validacao.
+
+Cada operacao declara `target.resolver`, `preconditions`, `validators`,
+`affectedPaths`, `effects` e `submissionImpact` tipado. Edicoes de conteudo de
+painel podem afetar dados schema-backed porque `panels[].content` hospeda
+`FieldMetadata[]`; widgets filhos continuam governados pelos contratos dos
+respectivos componentes.
+
 ## Tokens de Estilo por instância
 
 Os tokens opcionais em `appearance.tokens` permitem customizações rápidas por instância; por exemplo:

package/fesm2022/praxisui-expansion.mjs

@@ -62,6 +62,7 @@ const CAPS = [
     { path: 'panels[].id', category: 'panels', valueKind: 'string', description: 'Panel id.' },
     { path: 'panels[].title', category: 'panels', valueKind: 'string', description: 'Panel title.' },
     { path: 'panels[].description', category: 'panels', valueKind: 'string', description: 'Panel description.' },
+    { path: 'panels[].icon', category: 'panels', valueKind: 'string', description: 'Panel header icon rendered through PraxisIconDirective.' },
     { path: 'panels[].disabled', category: 'panels', valueKind: 'boolean', description: 'Disable panel.' },
     { path: 'panels[].expanded', category: 'panels', valueKind: 'boolean', description: 'Expanded state.' },
     { path: 'panels[].hideToggle', category: 'panels', valueKind: 'boolean', description: 'Hide toggle icon for panel.' },
@@ -603,8 +604,9 @@ class PraxisExpansion {
             >
               <mat-expansion-panel-header
                 [collapsedHeight]="p.collapsedHeight || (defaultOptions?.collapsedHeight || injectedDefaults?.collapsedHeight) || ''"
-                [expandedHeight]="p.expandedHeight || (defaultOptions?.expandedHeight || injectedDefaults?.expandedHeight) || ''"
-              >
+              [expandedHeight]="p.expandedHeight || (defaultOptions?.expandedHeight || injectedDefaults?.expandedHeight) || ''"
+            >
+                <mat-icon *ngIf="p.icon" [praxisIcon]="p.icon"></mat-icon>
                 <mat-panel-title>{{ p.title }}</mat-panel-title>
                 <mat-panel-description *ngIf="p.description">{{ p.description }}</mat-panel-description>
               </mat-expansion-panel-header>
@@ -660,8 +662,9 @@ class PraxisExpansion {
           >
             <mat-expansion-panel-header
               [collapsedHeight]="p.collapsedHeight || (defaultOptions?.collapsedHeight || injectedDefaults?.collapsedHeight) || ''"
-              [expandedHeight]="p.expandedHeight || (defaultOptions?.expandedHeight || injectedDefaults?.expandedHeight) || ''"
-            >
+            [expandedHeight]="p.expandedHeight || (defaultOptions?.expandedHeight || injectedDefaults?.expandedHeight) || ''"
+          >
+              <mat-icon *ngIf="p.icon" [praxisIcon]="p.icon"></mat-icon>
               <mat-panel-title>{{ p.title }}</mat-panel-title>
               <mat-panel-description *ngIf="p.description">{{ p.description }}</mat-panel-description>
             </mat-expansion-panel-header>
@@ -775,8 +778,9 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.17", ngImpo
             >
               <mat-expansion-panel-header
                 [collapsedHeight]="p.collapsedHeight || (defaultOptions?.collapsedHeight || injectedDefaults?.collapsedHeight) || ''"
-                [expandedHeight]="p.expandedHeight || (defaultOptions?.expandedHeight || injectedDefaults?.expandedHeight) || ''"
-              >
+              [expandedHeight]="p.expandedHeight || (defaultOptions?.expandedHeight || injectedDefaults?.expandedHeight) || ''"
+            >
+                <mat-icon *ngIf="p.icon" [praxisIcon]="p.icon"></mat-icon>
                 <mat-panel-title>{{ p.title }}</mat-panel-title>
                 <mat-panel-description *ngIf="p.description">{{ p.description }}</mat-panel-description>
               </mat-expansion-panel-header>
@@ -832,8 +836,9 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.17", ngImpo
           >
             <mat-expansion-panel-header
               [collapsedHeight]="p.collapsedHeight || (defaultOptions?.collapsedHeight || injectedDefaults?.collapsedHeight) || ''"
-              [expandedHeight]="p.expandedHeight || (defaultOptions?.expandedHeight || injectedDefaults?.expandedHeight) || ''"
-            >
+            [expandedHeight]="p.expandedHeight || (defaultOptions?.expandedHeight || injectedDefaults?.expandedHeight) || ''"
+          >
+              <mat-icon *ngIf="p.icon" [praxisIcon]="p.icon"></mat-icon>
               <mat-panel-title>{{ p.title }}</mat-panel-title>
               <mat-panel-description *ngIf="p.description">{{ p.description }}</mat-panel-description>
             </mat-expansion-panel-header>
@@ -1321,6 +1326,9 @@ class PraxisExpansionConfigEditor {
           <mat-form-field appearance="outline"><mat-label>Descrição</mat-label>
             <input matInput [value]="p.description || ''" (input)="setPanel(i, 'description', $any($event.target).value)" />
           </mat-form-field>
+          <mat-form-field appearance="outline"><mat-label>Ícone</mat-label>
+            <input matInput [value]="p.icon || ''" (input)="setPanel(i, 'icon', $any($event.target).value)" placeholder="info" />
+          </mat-form-field>
           <mat-form-field appearance="outline"><mat-label>Altura recolhida</mat-label>
             <input matInput placeholder="48px" [value]="p.collapsedHeight || ''" (input)="setPanel(i, 'collapsedHeight', $any($event.target).value)" />
           </mat-form-field>
@@ -1571,6 +1579,9 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.17", ngImpo
           <mat-form-field appearance="outline"><mat-label>Descrição</mat-label>
             <input matInput [value]="p.description || ''" (input)="setPanel(i, 'description', $any($event.target).value)" />
           </mat-form-field>
+          <mat-form-field appearance="outline"><mat-label>Ícone</mat-label>
+            <input matInput [value]="p.icon || ''" (input)="setPanel(i, 'icon', $any($event.target).value)" placeholder="info" />
+          </mat-form-field>
           <mat-form-field appearance="outline"><mat-label>Altura recolhida</mat-label>
             <input matInput placeholder="48px" [value]="p.collapsedHeight || ''" (input)="setPanel(i, 'collapsedHeight', $any($event.target).value)" />
           </mat-form-field>
@@ -1595,6 +1606,35 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.17", ngImpo
                 type: Input
             }] } });
 
+const PRAXIS_EXPANSION_PORTS = [
+    {
+        id: 'config',
+        label: 'Configuracao',
+        direction: 'input',
+        semanticKind: 'config-fragment',
+        schema: {
+            id: 'ExpansionMetadata',
+            kind: 'ts-type',
+            ref: 'ExpansionMetadata',
+        },
+        description: 'Fragmento canonico de configuracao dos paineis e dos widgets internos.',
+        exposure: { public: true, group: 'config' },
+    },
+    {
+        id: 'widgetEvent',
+        label: 'Evento interno de widget',
+        direction: 'output',
+        semanticKind: 'event',
+        schema: {
+            id: 'WidgetEventEnvelope',
+            kind: 'ts-type',
+            ref: 'WidgetEventEnvelope',
+        },
+        cardinality: 'stream',
+        description: 'Bridge composta para transporte de eventos internos. As portas canonicas dos filhos sao resolvidas por component-port + nestedPath.',
+        exposure: { public: true, advanced: true, group: 'composite' },
+    },
+];
 const PRAXIS_EXPANSION_COMPONENT_METADATA = {
     id: 'praxis-expansion',
     selector: 'praxis-expansion',
@@ -1676,6 +1716,7 @@ const PRAXIS_EXPANSION_COMPONENT_METADATA = {
     ],
     tags: ['widget', 'expansion', 'accordion', 'configurable'],
     lib: '@praxisui/expansion',
+    ports: PRAXIS_EXPANSION_PORTS,
 };
 function providePraxisExpansionMetadata() {
     return {
@@ -1691,6 +1732,315 @@ function providePraxisExpansionDefaults(opts) {
     return { provide: MAT_EXPANSION_PANEL_DEFAULT_OPTIONS, useValue: opts };
 }
 
+const panelItemSchema = {
+    type: 'object',
+    required: ['id', 'title'],
+    properties: {
+        id: { type: 'string' },
+        title: { type: 'string' },
+        description: { type: 'string' },
+        icon: { type: 'string' },
+        disabled: { type: 'boolean' },
+        expanded: { type: 'boolean' },
+        hideToggle: { type: 'boolean' },
+        collapsedHeight: { type: 'string' },
+        expandedHeight: { type: 'string' },
+        content: { type: 'array', items: { type: 'object' } },
+        widgets: { type: 'array', items: { type: 'object' } },
+        actionButtons: { type: 'array', items: { type: 'object' } },
+    },
+};
+const panelPatchSchema = {
+    type: 'object',
+    minProperties: 1,
+    properties: {
+        id: { type: 'string' },
+        title: { type: 'string' },
+        description: { type: 'string' },
+        icon: { type: 'string' },
+        disabled: { type: 'boolean' },
+        expanded: { type: 'boolean' },
+        hideToggle: { type: 'boolean' },
+        collapsedHeight: { type: 'string' },
+        expandedHeight: { type: 'string' },
+        content: { type: 'array', items: { type: 'object' } },
+        widgets: { type: 'array', items: { type: 'object' } },
+        actionButtons: { type: 'array', items: { type: 'object' } },
+    },
+};
+const PRAXIS_EXPANSION_AUTHORING_MANIFEST = {
+    schemaVersion: '1.0.0',
+    componentId: 'praxis-expansion',
+    ownerPackage: '@praxisui/expansion',
+    configSchemaId: 'ExpansionMetadata',
+    manifestVersion: '1.0.0',
+    runtimeInputs: [
+        { name: 'config', type: 'ExpansionMetadata', description: 'Canonical accordion and panel configuration.' },
+        { name: 'expansionId', type: 'string', description: 'Stable id used to derive expansion config persistence scope.' },
+        { name: 'componentInstanceId', type: 'string', description: 'Optional instance discriminator for persistence scope.' },
+        { name: 'context', type: 'Record<string, any>', description: 'Context passed to nested widgets.' },
+        { name: 'strictValidation', type: 'boolean', description: 'Controls nested widget validation strictness.' },
+        { name: 'defaultOptions', type: 'MatExpansionPanelDefaultOptions', description: 'Instance-level Material expansion defaults.' },
+        { name: 'enableCustomization', type: 'boolean', description: 'Enables Settings Panel authoring surfaces.' },
+    ],
+    editableTargets: [
+        { kind: 'panel', resolver: 'panel-by-id-or-title', description: 'A panel in config.panels[].' },
+        { kind: 'panelHeader', resolver: 'panel-by-id-or-title', description: 'Header title, description, icon and heights for a panel.' },
+        { kind: 'panelContent', resolver: 'panel-content-by-id', description: 'Lazy panel content hosted through fields, widgets or action buttons.' },
+        { kind: 'expandedState', resolver: 'panel-by-id-or-title', description: 'Panel expanded state and default expanded selection.' },
+        { kind: 'disabledState', resolver: 'panel-by-id-or-title', description: 'Panel disabled state.' },
+        { kind: 'layout', resolver: 'expansion-layout-config', description: 'Accordion display mode, toggle position, density and visual layout.' },
+        { kind: 'behavior', resolver: 'expansion-behavior-config', description: 'Accordion multi-expand and hide-toggle behavior.' },
+    ],
+    operations: [
+        {
+            operationId: 'panel.add',
+            title: 'Add panel',
+            scope: 'global',
+            targetKind: 'panel',
+            target: { kind: 'panel', resolver: 'panels-array', ambiguityPolicy: 'fail', required: false },
+            inputSchema: panelItemSchema,
+            effects: [{ kind: 'append-unique', path: 'panels[]', key: 'id' }],
+            destructive: false,
+            requiresConfirmation: false,
+            validators: ['panel-id-unique', 'panel-order-deterministic', 'panel-content-valid'],
+            affectedPaths: ['panels[]'],
+            submissionImpact: 'config-only',
+            preconditions: ['config-initialized'],
+        },
+        {
+            operationId: 'panel.remove',
+            title: 'Remove panel',
+            scope: 'layout',
+            targetKind: 'panel',
+            target: { kind: 'panel', resolver: 'panel-by-id-or-title', ambiguityPolicy: 'fail', required: true },
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    replacementExpandedPanelId: { type: 'string' },
+                },
+            },
+            effects: [{
+                    kind: 'compile-domain-patch',
+                    handler: 'expansion-panel-remove',
+                    handlerContract: {
+                        reads: ['accordion.multi', 'panels[]', 'panels[].id', 'panels[].expanded'],
+                        writes: ['panels[]', 'panels[].expanded'],
+                        identityKeys: ['panels[].id'],
+                        inputSchema: {
+                            type: 'object',
+                            properties: {
+                                replacementExpandedPanelId: { type: 'string' },
+                            },
+                        },
+                        failureModes: ['panel-not-found', 'replacement-panel-not-found', 'content-removal-not-confirmed', 'single-expand-conflict'],
+                        description: 'Removes the target panel by stable id and applies replacement expanded state when the removed panel was expanded.',
+                    },
+                }],
+            destructive: true,
+            requiresConfirmation: true,
+            validators: ['panel-exists', 'default-expanded-removal-safe', 'panel-content-removal-confirmed'],
+            affectedPaths: ['panels[]', 'panels[].expanded'],
+            submissionImpact: 'config-only',
+            preconditions: ['config-initialized', 'target-panel-exists', 'confirmation-collected'],
+        },
+        {
+            operationId: 'panel.title.set',
+            title: 'Set panel title',
+            scope: 'layout',
+            targetKind: 'panelHeader',
+            target: { kind: 'panelHeader', resolver: 'panel-by-id-or-title', ambiguityPolicy: 'fail', required: true },
+            inputSchema: { type: 'object', required: ['title'], properties: { title: { type: 'string' } } },
+            effects: [{ kind: 'merge-by-key', path: 'panels[]', key: 'id' }],
+            destructive: false,
+            requiresConfirmation: false,
+            validators: ['panel-exists', 'panel-title-valid'],
+            affectedPaths: ['panels[].title'],
+            submissionImpact: 'config-only',
+            preconditions: ['config-initialized', 'target-panel-exists'],
+        },
+        {
+            operationId: 'panel.description.set',
+            title: 'Set panel description',
+            scope: 'layout',
+            targetKind: 'panelHeader',
+            target: { kind: 'panelHeader', resolver: 'panel-by-id-or-title', ambiguityPolicy: 'fail', required: true },
+            inputSchema: { type: 'object', required: ['description'], properties: { description: { type: 'string' } } },
+            effects: [{ kind: 'merge-by-key', path: 'panels[]', key: 'id' }],
+            destructive: false,
+            requiresConfirmation: false,
+            validators: ['panel-exists', 'panel-description-valid'],
+            affectedPaths: ['panels[].description'],
+            submissionImpact: 'config-only',
+            preconditions: ['config-initialized', 'target-panel-exists'],
+        },
+        {
+            operationId: 'panel.icon.set',
+            title: 'Set panel icon',
+            scope: 'layout',
+            targetKind: 'panelHeader',
+            target: { kind: 'panelHeader', resolver: 'panel-by-id-or-title', ambiguityPolicy: 'fail', required: true },
+            inputSchema: { type: 'object', required: ['icon'], properties: { icon: { type: 'string' } } },
+            effects: [{ kind: 'merge-by-key', path: 'panels[]', key: 'id' }],
+            destructive: false,
+            requiresConfirmation: false,
+            validators: ['panel-exists', 'panel-icon-valid', 'editor-runtime-round-trip'],
+            affectedPaths: ['panels[].icon'],
+            submissionImpact: 'config-only',
+            preconditions: ['config-initialized', 'target-panel-exists'],
+        },
+        {
+            operationId: 'panel.order.set',
+            title: 'Reorder panels',
+            scope: 'layout',
+            targetKind: 'panel',
+            target: { kind: 'panel', resolver: 'panel-by-id-or-title', ambiguityPolicy: 'fail', required: true },
+            inputSchema: { type: 'object', required: ['beforePanelId'], properties: { beforePanelId: { type: 'string' } } },
+            effects: [{ kind: 'reorder-by-key', path: 'panels[]', key: 'id' }],
+            destructive: false,
+            requiresConfirmation: false,
+            validators: ['panel-exists', 'panel-order-deterministic'],
+            affectedPaths: ['panels[]'],
+            submissionImpact: 'config-only',
+            preconditions: ['config-initialized', 'target-panel-exists'],
+        },
+        {
+            operationId: 'panel.disabled.set',
+            title: 'Set disabled state',
+            scope: 'interaction',
+            targetKind: 'disabledState',
+            target: { kind: 'disabledState', resolver: 'panel-by-id-or-title', ambiguityPolicy: 'fail', required: true },
+            inputSchema: { type: 'object', required: ['disabled'], properties: { disabled: { type: 'boolean' } } },
+            effects: [{ kind: 'merge-by-key', path: 'panels[]', key: 'id' }],
+            destructive: false,
+            requiresConfirmation: false,
+            validators: ['panel-exists', 'disabled-expanded-compatible'],
+            affectedPaths: ['panels[].disabled', 'panels[].expanded'],
+            submissionImpact: 'config-only',
+            preconditions: ['config-initialized', 'target-panel-exists'],
+        },
+        {
+            operationId: 'behavior.multiExpand.set',
+            title: 'Set multi-expand behavior',
+            scope: 'interaction',
+            targetKind: 'behavior',
+            target: { kind: 'behavior', resolver: 'expansion-behavior-config', ambiguityPolicy: 'fail', required: true },
+            inputSchema: { type: 'object', required: ['multi'], properties: { multi: { type: 'boolean' } } },
+            effects: [{
+                    kind: 'compile-domain-patch',
+                    handler: 'expansion-multi-expand-set',
+                    handlerContract: {
+                        reads: ['accordion.multi', 'panels[]', 'panels[].id', 'panels[].expanded'],
+                        writes: ['accordion.multi', 'panels[].expanded'],
+                        identityKeys: ['panels[].id'],
+                        inputSchema: { type: 'object', required: ['multi'], properties: { multi: { type: 'boolean' } } },
+                        failureModes: ['multiple-expanded-panels-conflict', 'panel-id-missing'],
+                        description: 'Sets accordion.multi and collapses competing expanded panels when switching to single-expand behavior.',
+                    },
+                }],
+            destructive: false,
+            requiresConfirmation: false,
+            validators: ['multi-expand-default-compatible', 'accordion-values-valid', 'editor-runtime-round-trip'],
+            affectedPaths: ['accordion.multi', 'panels[].expanded'],
+            submissionImpact: 'config-only',
+            preconditions: ['config-initialized'],
+        },
+        {
+            operationId: 'behavior.defaultExpanded.set',
+            title: 'Set default expanded panel',
+            scope: 'interaction',
+            targetKind: 'expandedState',
+            target: { kind: 'expandedState', resolver: 'panel-by-id-or-title', ambiguityPolicy: 'fail', required: true },
+            inputSchema: {
+                type: 'object',
+                required: ['expanded'],
+                properties: {
+                    expanded: { type: 'boolean' },
+                    collapseOthers: { type: 'boolean' },
+                },
+            },
+            effects: [{
+                    kind: 'compile-domain-patch',
+                    handler: 'expansion-default-expanded-upsert',
+                    handlerContract: {
+                        reads: ['accordion.multi', 'panels[]', 'panels[].id', 'panels[].expanded', 'panels[].disabled'],
+                        writes: ['panels[].expanded'],
+                        identityKeys: ['panels[].id'],
+                        inputSchema: {
+                            type: 'object',
+                            required: ['panelId', 'expanded'],
+                            properties: {
+                                panelId: { type: 'string' },
+                                expanded: { type: 'boolean' },
+                                collapseOthers: { type: 'boolean' },
+                            },
+                        },
+                        failureModes: ['panel-not-found', 'panel-disabled', 'single-expand-conflict'],
+                        description: 'Sets a panel expanded state and collapses competing panels when accordion.multi is false.',
+                    },
+                }],
+            validators: ['panel-exists', 'default-expanded-panel-exists', 'multi-expand-default-compatible', 'disabled-expanded-compatible'],
+            destructive: false,
+            requiresConfirmation: false,
+            affectedPaths: ['panels[].expanded', 'accordion.multi'],
+            submissionImpact: 'config-only',
+            preconditions: ['config-initialized', 'target-panel-exists'],
+        },
+        {
+            operationId: 'panel.content.set',
+            title: 'Set panel content',
+            scope: 'layout',
+            targetKind: 'panelContent',
+            target: { kind: 'panelContent', resolver: 'panel-content-by-id', ambiguityPolicy: 'fail', required: true },
+            inputSchema: panelPatchSchema,
+            effects: [{ kind: 'merge-by-key', path: 'panels[]', key: 'id' }],
+            destructive: false,
+            requiresConfirmation: false,
+            validators: ['panel-exists', 'panel-content-valid', 'lazy-content-compatible', 'nested-widget-contract-delegated'],
+            affectedPaths: ['panels[].content', 'panels[].widgets', 'panels[].actionButtons'],
+            submissionImpact: 'affects-schema-backed-data',
+            preconditions: ['config-initialized', 'target-panel-exists'],
+        },
+    ],
+    validators: [
+        { validatorId: 'panel-id-unique', level: 'error', code: 'PEXP001', description: 'Panel ids must be unique and stable within config.panels[].' },
+        { validatorId: 'panel-exists', level: 'error', code: 'PEXP002', description: 'Target panel must exist before applying the operation.' },
+        { validatorId: 'panel-order-deterministic', level: 'error', code: 'PEXP003', description: 'Panel ordering must use stable ids, not transient array index as identity.' },
+        { validatorId: 'panel-title-valid', level: 'error', code: 'PEXP004', description: 'Panel title must be a non-empty text value after localization/domain projection.' },
+        { validatorId: 'panel-description-valid', level: 'warning', code: 'PEXP005', description: 'Panel description should remain plain header-support text and not replace panel content.' },
+        { validatorId: 'panel-icon-valid', level: 'warning', code: 'PEXP006', description: 'Panel icon metadata must remain compatible with PraxisIconDirective and editor round-trip.' },
+        { validatorId: 'panel-content-valid', level: 'error', code: 'PEXP007', description: 'Panel content must remain valid FieldMetadata[], WidgetDefinition[] or action button metadata.' },
+        { validatorId: 'panel-content-removal-confirmed', level: 'error', code: 'PEXP008', description: 'Removing a panel with fields, widgets or action buttons is destructive and requires confirmation.' },
+        { validatorId: 'default-expanded-panel-exists', level: 'error', code: 'PEXP009', description: 'Default expanded state must reference an existing panel id.' },
+        { validatorId: 'default-expanded-removal-safe', level: 'error', code: 'PEXP010', description: 'Removing an expanded panel requires deterministic replacement state or explicit confirmation.' },
+        { validatorId: 'multi-expand-default-compatible', level: 'error', code: 'PEXP011', description: 'When accordion.multi is false, at most one panel may be marked expanded by default.' },
+        { validatorId: 'disabled-expanded-compatible', level: 'warning', code: 'PEXP012', description: 'A disabled panel should not be the only expanded/default focus target without explicit intent.' },
+        { validatorId: 'accordion-values-valid', level: 'error', code: 'PEXP013', description: 'Accordion behavior values must match ExpansionMetadata and Angular Material expansion bindings.' },
+        { validatorId: 'lazy-content-compatible', level: 'info', code: 'PEXP015', description: 'Panel content remains lazy through matExpansionPanelContent and should not require eager child runtime state.' },
+        { validatorId: 'nested-widget-contract-delegated', level: 'info', code: 'PEXP016', description: 'Nested widget content remains governed by child component contracts and component-port nestedPath semantics.' },
+        { validatorId: 'editor-runtime-round-trip', level: 'error', code: 'PEXP017', description: 'Settings Panel editor, runtime persistence and registry projection must preserve panel ids, order, icons and expanded state.' },
+    ],
+    roundTripRequirements: [
+        'Operations must preserve stable panel ids; array index may be used only as a resolver fallback, never as canonical identity.',
+        'Settings Panel editor, runtime persistence and registry projection must round-trip ExpansionMetadata without losing panel ids, order, icons or expanded state.',
+        'When accordion.multi is false, authoring must collapse competing panels or fail validation instead of producing multiple default-expanded panels.',
+        'Lazy panel content remains represented by panels[].content, panels[].widgets and panels[].actionButtons; authoring cannot require eager child component instances.',
+        'Nested widgets remain delegated through WidgetDefinition and component-port nestedPath semantics instead of being redefined by the expansion contract.',
+    ],
+    examples: [
+        { id: 'add-summary-panel', request: 'Add a summary panel before the audit panel.', operationId: 'panel.add', params: { id: 'summary', title: 'Summary' }, isPositive: true },
+        { id: 'rename-details-panel', request: 'Rename details to Account details.', operationId: 'panel.title.set', target: 'details', params: { title: 'Account details' }, isPositive: true },
+        { id: 'describe-audit-panel', request: 'Set audit panel description to Recent changes.', operationId: 'panel.description.set', target: 'audit', params: { description: 'Recent changes' }, isPositive: true },
+        { id: 'set-panel-icon', request: 'Use the info icon on the summary panel.', operationId: 'panel.icon.set', target: 'summary', params: { icon: 'info' }, isPositive: true },
+        { id: 'set-default-expanded-panel', request: 'Open the summary panel by default.', operationId: 'behavior.defaultExpanded.set', target: 'summary', params: { expanded: true, collapseOthers: true }, isPositive: true },
+        { id: 'enable-multi-expand', request: 'Allow multiple panels to stay open.', operationId: 'behavior.multiExpand.set', params: { multi: true }, isPositive: true },
+        { id: 'disable-archive-panel', request: 'Disable the archive panel.', operationId: 'panel.disabled.set', target: 'archive', params: { disabled: true }, isPositive: true },
+        { id: 'reject-missing-default-expanded', request: 'Open the missing panel by default.', operationId: 'behavior.defaultExpanded.set', target: 'missing', params: { expanded: true }, isPositive: false },
+        { id: 'reject-duplicate-panel-id', request: 'Add another panel with id summary.', operationId: 'panel.add', params: { id: 'summary', title: 'Duplicate summary' }, isPositive: false },
+        { id: 'confirm-remove-content-panel', request: 'Remove the details panel that contains widgets.', operationId: 'panel.remove', target: 'details', params: { replacementExpandedPanelId: 'summary' }, isPositive: true },
+    ],
+};
+
 /*
  * Public API Surface of praxis-expansion
  */
@@ -1699,4 +2049,4 @@ function providePraxisExpansionDefaults(opts) {
  * Generated bundle index. Do not edit.
  */
 
-export { EXPANSION_AI_CAPABILITIES, PRAXIS_EXPANSION_COMPONENT_METADATA, PraxisExpansion, PraxisExpansionConfigEditor, providePraxisExpansionDefaults, providePraxisExpansionMetadata };
+export { EXPANSION_AI_CAPABILITIES, PRAXIS_EXPANSION_AUTHORING_MANIFEST, PRAXIS_EXPANSION_COMPONENT_METADATA, PraxisExpansion, PraxisExpansionConfigEditor, providePraxisExpansionDefaults, providePraxisExpansionMetadata };

package/index.d.ts

@@ -2,7 +2,7 @@ import * as i0 from '@angular/core';
 import { OnChanges, OnInit, EventEmitter, QueryList, SimpleChanges, Provider } from '@angular/core';
 import { FormGroup } from '@angular/forms';
 import { MatAccordionDisplayMode, MatAccordionTogglePosition, MatExpansionPanelDefaultOptions, MatAccordion, MatExpansionPanel } from '@angular/material/expansion';
-import { AiCapability, FieldMetadata, WidgetDefinition, WidgetEventEnvelope, ComponentDocMeta, AiCapabilityCategory, AiValueKind, AiCapabilityCatalog } from '@praxisui/core';
+import { AiCapability, FieldMetadata, WidgetDefinition, WidgetEventEnvelope, ComponentDocMeta, AiCapabilityCategory, AiValueKind, AiCapabilityCatalog, ComponentAuthoringManifest } from '@praxisui/core';
 import { BehaviorSubject } from 'rxjs';
 import { BaseAiAdapter, PatchResult } from '@praxisui/ai';
 import { SettingsValueProvider } from '@praxisui/settings-panel';
@@ -89,6 +89,7 @@ interface PanelMetadata {
     id?: string;
     title: string;
     description?: string;
+    icon?: string;
     disabled?: boolean;
     expanded?: boolean;
     hideToggle?: boolean;
@@ -242,5 +243,7 @@ interface CapabilityCatalog extends AiCapabilityCatalog {
 }
 declare const EXPANSION_AI_CAPABILITIES: CapabilityCatalog;
 
-export { EXPANSION_AI_CAPABILITIES, PRAXIS_EXPANSION_COMPONENT_METADATA, PraxisExpansion, PraxisExpansionConfigEditor, providePraxisExpansionDefaults, providePraxisExpansionMetadata };
+declare const PRAXIS_EXPANSION_AUTHORING_MANIFEST: ComponentAuthoringManifest;
+
+export { EXPANSION_AI_CAPABILITIES, PRAXIS_EXPANSION_AUTHORING_MANIFEST, PRAXIS_EXPANSION_COMPONENT_METADATA, PraxisExpansion, PraxisExpansionConfigEditor, providePraxisExpansionDefaults, providePraxisExpansionMetadata };
 export type { Capability, CapabilityCatalog, CapabilityCategory, ExpansionAppearanceContainer, ExpansionAppearanceHeader, ExpansionAppearanceStates, ExpansionMetadata, PanelMetadata, ValueKind };

package/package.json

@@ -1,15 +1,19 @@
 {
   "name": "@praxisui/expansion",
-  "version": "8.0.0-beta.2",
+  "version": "8.0.0-beta.20",
   "description": "Expansion panel (accordion) components for Praxis UI with metadata configuration and editor integration.",
   "peerDependencies": {
     "@angular/common": "^20.0.0",
     "@angular/core": "^20.0.0",
     "@angular/material": "^20.0.0",
     "@angular/cdk": "^20.0.0",
-    "@praxisui/core": "^8.0.0-beta.2",
-    "@praxisui/dynamic-fields": "^8.0.0-beta.2",
-    "@praxisui/settings-panel": "^8.0.0-beta.2"
+    "@praxisui/core": "^8.0.0-beta.20",
+    "@praxisui/dynamic-fields": "^8.0.0-beta.20",
+    "@praxisui/settings-panel": "^8.0.0-beta.20",
+    "@angular/forms": "^20.0.0",
+    "@angular/router": "^20.0.0",
+    "@praxisui/ai": "^8.0.0-beta.20",
+    "rxjs": "~7.8.0"
   },
   "dependencies": {
     "tslib": "^2.3.0"