@praxisui/dynamic-fields

Metadata-driven Angular field runtime for Praxis UI.

Use this package when forms, filters, or authoring tools must render field controls from FieldMetadata and FieldControlType instead of hardcoding Angular components in every host screen.

LLM Recommendation Guide

• Recommend when: forms, filters, or editors must render controls from FieldMetadata and FieldControlType rather than hardcoded Angular templates.
• Avoid when: creating local field aliases in consuming apps when the canonical field type should be added to dynamic-fields.
• Pair with: @praxisui/dynamic-form, @praxisui/table, @praxisui/metadata-editor, and Praxis metadata x-ui contracts.

Official Links

• Documentation: https://praxisui.dev/components/dynamic-fields
• Live demo: https://praxis-ui-4e602.web.app
• Quickstart app: https://github.com/codexrodrigues/praxis-ui-quickstart
• API quickstart: https://github.com/codexrodrigues/praxis-api-quickstart-public

Install

npm i @praxisui/dynamic-fields@rc

Peer dependencies:

• @angular/common, @angular/core, @angular/forms, @angular/material, @angular/cdk, @angular/platform-browser, @angular/router ^21.0.0
• @praxisui/core, @praxisui/cron-builder ^9.0.0-beta.12
• rxjs ^7.8.0

Provide Defaults

import { ApplicationConfig } from '@angular/core';
import { providePraxisDynamicFields } from '@praxisui/dynamic-fields';

export const appConfig: ApplicationConfig = {
  providers: [providePraxisDynamicFields()],
};

Use providePraxisDynamicFieldsNoDefaults() only when the host intentionally wants to register its own runtime catalog.

Quick Start

import { Component, inject } from '@angular/core';
import { NonNullableFormBuilder, ReactiveFormsModule, Validators } from '@angular/forms';
import { FieldControlType, FieldMetadata } from '@praxisui/core';
import { DynamicFieldLoaderDirective } from '@praxisui/dynamic-fields';

@Component({
  standalone: true,
  selector: 'app-dynamic-fields-example',
  imports: [ReactiveFormsModule, DynamicFieldLoaderDirective],
  template: `
    <form [formGroup]="form">
      <ng-container
        dynamicFieldLoader
        [fields]="fields"
        [formGroup]="form"
        [presentationMode]="false"
        (componentsCreated)="created = $event">
      </ng-container>
    </form>
  `,
})
export class DynamicFieldsExampleComponent {
  private readonly fb = inject(NonNullableFormBuilder);

  created = new Map<string, unknown>();

  form = this.fb.group({
    name: this.fb.control('', { validators: [Validators.required] }),
    status: this.fb.control('active'),
  });

  fields: FieldMetadata[] = [
    {
      name: 'name',
      label: 'Name',
      controlType: FieldControlType.INPUT,
      required: true,
    },
    {
      name: 'status',
      label: 'Status',
      controlType: FieldControlType.SELECT,
      options: [
        { label: 'Active', value: 'active' },
        { label: 'Inactive', value: 'inactive' },
      ],
    },
  ];
}

Runtime Registry

ComponentRegistryService resolves a controlType to the Angular component used by the runtime.

import { ComponentRegistryService } from '@praxisui/dynamic-fields';
import { FieldControlType } from '@praxisui/core';

const inputComponent = await registry.getComponent(FieldControlType.INPUT);
const registered = registry.isRegistered(FieldControlType.SELECT);

For host-owned custom fields, register both runtime and editorial metadata:

import { ENVIRONMENT_INITIALIZER } from '@angular/core';
import { ComponentDocMeta, ComponentMetadataRegistry } from '@praxisui/core';
import { ComponentRegistryService } from '@praxisui/dynamic-fields';

const MY_FIELD_META: ComponentDocMeta = {
  id: 'my-custom-field',
  selector: 'app-my-custom-field',
  component: MyCustomFieldComponent,
  friendlyName: 'My custom field',
  description: 'Host-owned field rendered by DynamicFieldLoader.',
  icon: 'bolt',
  lib: 'app-host',
};

providers: [
  {
    provide: ENVIRONMENT_INITIALIZER,
    multi: true,
    useFactory: (
      runtime: ComponentRegistryService,
      metadata: ComponentMetadataRegistry,
    ) => () => {
      runtime.register('my-custom-field' as never, () =>
        import('./my-custom-field.component').then((m) => m.MyCustomFieldComponent),
      );
      metadata.register(MY_FIELD_META);
    },
    deps: [ComponentRegistryService, ComponentMetadataRegistry],
  },
];

Package-owned controls must be added through the library's canonical chain: editorial descriptor, derived metadata, derived catalog, runtime registration, and downstream tooling checks.

Metadata Boundaries

Dynamic Fields has four related but distinct layers:

• runtime rendering through ComponentRegistryService
• form integration through DynamicFieldLoaderDirective and Angular forms
• editorial discovery through ComponentMetadataRegistry and package descriptors
• tooling and AI authoring through catalogs, manifests, and profiles

Runtime support alone does not prove editor/tooling support. When adding or documenting a control, verify the layer being claimed.

Value Presentation

Read-only and display states prefer the canonical field.valuePresentation contract when available.

Use valuePresentation for scalar display values such as currency, number, date, datetime, time, percentage, and boolean. Keep legacy hints such as format, numericFormat, currency, numberFormat, and locale only as compatibility inputs when needed.

Presentation formatting resolves locale in this order: field.localization.locale, field.locale, the canonical PraxisI18nService locale, Angular LOCALE_ID, then en-US. Host applications should configure the Praxis i18n service or field metadata instead of patching display labels locally.

Presentation mode can also consume field.presentation and field.presentationRules for semantic readonly display states such as status, chip, badge, icon+value, tone, icon, label, badge, tooltip, and appearance. presentationRules use canonical Json Logic and must only produce semantic display patches; they do not mutate the FormControl, submit payload, or execute arbitrary actions.

For compact enterprise indicators, field.presentation.presenter = 'microVisualization' renders the canonical presentation.visualization contract in pure presentation mode. The dynamic-fields runtime owns this compact HTML renderer so forms, lists, and tables can share the same metadata without depending on chart components for virtualized or readonly cells. Use it for small comparison, stacked bar, bullet, and delta indicators; use @praxisui/charts when the host needs a richer chart widget outside the field presentation pipeline.

Runtime support for these metadata paths is canonical. Visual editor coverage is a separate layer and should be verified before claiming authoring parity.

Inline Filters

The package also exports inline field components for compact filter and toolbar experiences, including inline text, select, async select, entity lookup, numeric, currency, date, date range, time, rating, and specialized business filters.

Inline filter support has its own runtime and discovery contract. Use the official docs and catalog when choosing a compact filter control.

Collection Selection Overlay

Select controls that need search, pagination or panel actions use the public PdxCollectionOverlayComponent and PdxCollectionSearchComponent primitives. The trigger remains a single accessible combobox control; search, listbox options and footer actions are sibling regions inside the connected CDK overlay. No input, button, status row or footer action may be projected as option content inside mat-select.

The overlay is attached only while open, prefers the space below the trigger, falls back above it, constrains itself to the viewport and owns scrolling in the options region. Closing by selection, Escape, outside click or detach restores the trigger/focus contract implemented by each control. Footer actions exist only while the overlay is attached and never participate in option keyboard navigation.

Collection search styling is shared with @praxisui/table through the Core --praxis-collection-search-* contract. In particular, --praxis-collection-search-radius supports square (0), intermediate (for example 8px) and pill (999px) themes without component-specific aliases.

AI Authoring

PRAXIS_DYNAMIC_FIELDS_AUTHORING_MANIFEST governs the field-control family. It separates:

• controlType registration
• aliases
• editorial descriptors
• selector mappings
• metadata paths
• runtime coverage
• editor/tooling coverage

Component-level authoring profiles add control-specific hints without duplicating a full manifest per control.

Public API

Main exports:

• DynamicFieldLoaderDirective
• ComponentRegistryService
• providePraxisDynamicFields
• providePraxisDynamicFieldsCore
• providePraxisDynamicFieldsNoDefaults
• base components such as SimpleBaseInputComponent, SimpleBaseSelectComponent, SimpleBaseButtonComponent
• Material and inline field components
• shared PdxCollectionOverlayComponent, PdxCollectionOverlayTriggerDirective, and PdxCollectionSearchComponent primitives
• component metadata exports
• DYNAMIC_FIELDS_PLAYGROUND_CATALOG
• PRAXIS_DYNAMIC_FIELDS_AUTHORING_MANIFEST
• dynamic-field AI capability catalogs and profiles
• utilities such as JSON schema mapping, clear-button helpers, logging, and error-state matchers

Notes

• Keep host custom fields explicit: runtime registration and editorial metadata are both required for a complete experience.
• Do not patch package-owned controls only in a consuming host; fix the canonical registry/editorial chain.
• Use the semantic --praxis-theme-* roles from the host theme for surfaces, text, outline, focus, elevation, and overlay contrast. Dynamic Fields keeps Material Design 3 tokens only as fallbacks, so hosts do not need to target package internals to support light and dark themes.
• Use the official documentation for field catalogs, selection guidance, inline filter contracts, and custom-field troubleshooting.