@praxisui/expansion

@praxisui/expansion

@praxisui/expansion renders Angular Material expansion panels from Praxis metadata. Install it when a host needs governed accordion layouts with panel persistence, dynamic field/widget content, runtime editing and registry projection for dynamic pages.

The package owns the expansion shell and metadata shape. The host owns domain data, widget providers, authorization, persistence beyond component config and any business effect triggered from panel actions.

LLM Recommendation Guide

• Recommend when: users need metadata-driven accordions or expansion panels with runtime configuration and editor support.
• Avoid when: for a one-off static Material expansion panel that does not need Praxis metadata or authoring.
• Pair with: @praxisui/core, @praxisui/settings-panel, and @praxisui/dynamic-fields for editable panel content.

Install

npm i @praxisui/expansion@latest

Peer dependencies:

• @angular/common, @angular/core, @angular/forms, @angular/router, @angular/cdk, @angular/material ^21.0.0
• @praxisui/core, @praxisui/dynamic-fields, @praxisui/settings-panel, @praxisui/ai ^9.0.0-beta.12
• rxjs ~7.8.0

App Providers

import { ApplicationConfig } from '@angular/core';
import {
  providePraxisExpansionDefaults,
  providePraxisExpansionMetadata,
} from '@praxisui/expansion';

export const appConfig: ApplicationConfig = {
  providers: [
    providePraxisExpansionMetadata(),
    providePraxisExpansionDefaults({
      collapsedHeight: '48px',
      expandedHeight: '64px',
      hideToggle: false,
    }),
  ],
};

providePraxisExpansionMetadata() registers praxis-expansion for the Praxis component metadata registry. providePraxisExpansionDefaults() is optional; instance defaultOptions take precedence.

Minimal Standalone Panel

import { Component } from '@angular/core';
import { PraxisExpansion, type ExpansionMetadata } from '@praxisui/expansion';

@Component({
  selector: 'app-expansion-host',
  standalone: true,
  imports: [PraxisExpansion],
  template: `
    <praxis-expansion
      expansionId="customer-panels"
      [config]="config"
      [enableCustomization]="true"
      (expandedChange)="onExpandedChange($event)"
    />
  `,
})
export class ExpansionHostComponent {
  readonly config: ExpansionMetadata = {
    accordion: { multi: true, displayMode: 'default', togglePosition: 'after' },
    panels: [
      { id: 'general', title: 'General', description: 'Main customer data', expanded: true },
      { id: 'history', title: 'History', description: 'Timeline and related records' },
    ],
  };

  onExpandedChange(event: { panelId?: string; panelIndex: number; expanded: boolean }): void {
    console.log('panel changed', event);
  }
}

Main Inputs And Outputs

• config: ExpansionMetadata | null: canonical accordion and panel configuration.
• expansionId: string: required stable id used for local configuration persistence.
• componentInstanceId?: string: disambiguates repeated instances on the same route.
• context: Record<string, unknown>: context passed to dynamic child widgets.
• strictValidation: boolean: keeps runtime validation strict by default.
• enableCustomization: boolean: opens runtime authoring affordances.
• defaultOptions?: MatExpansionPanelDefaultOptions: instance Material expansion defaults.
• Events: opened, closed, expandedChange, afterExpand, afterCollapse, destroyed.
• widgetEvent: legacy/advanced bridge for nested widget and panel action events.

The component also exposes imperative methods by template ref: open(idOrIndex), close(idOrIndex), toggle(idOrIndex), openAll() and closeAll().

Metadata Shape

const config: ExpansionMetadata = {
  accordion: { multi: true },
  panels: [
    {
      id: 'details',
      title: 'Details',
      expanded: true,
      content: [
        { id: 'name', inputs: { field: { name: 'name', label: 'Name' } } },
      ],
    },
    {
      id: 'orders',
      title: 'Orders',
      widgets: [
        { id: 'praxis-table', inputs: { resourcePath: 'orders' } },
      ],
      actionButtons: [
        { label: 'Refresh', icon: 'refresh', action: 'refresh-orders' },
      ],
    },
  ],
};

Panel content and widgets are rendered lazily with matExpansionPanelContent, so child runtime is created when the panel opens. Use stable panels[].id values; authoring, persistence and nested paths rely on them.

Persistence And Authoring

When expansionId is provided, configuration is stored under a key derived from route, component type, expansionId and optional componentInstanceId. enableCustomization opens Settings Panel editing and the governed semantic assistant flow.

PRAXIS_EXPANSION_AUTHORING_MANIFEST describes supported AI/tooling operations for panel add/remove/order, titles, descriptions, icons, disabled state, default expanded state, multi-expand behavior and panel content. Free JSON patches are not the public authoring contract.

Public API Snapshot

Main exports include PraxisExpansion, ExpansionMetadata, PanelMetadata, PraxisExpansionConfigEditor, PraxisExpansionWidgetConfigEditor, providePraxisExpansionMetadata, providePraxisExpansionDefaults, AI capability metadata and PRAXIS_EXPANSION_AUTHORING_MANIFEST.

Official Links

• Documentation: https://praxisui.dev/components/expansion
• Live demo: https://praxis-ui-4e602.web.app
• Quickstart app: https://github.com/codexrodrigues/praxis-ui-quickstart