# @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

```bash
npm i @praxisui/dynamic-fields@latest
```

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

```ts
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

```ts
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.

```ts
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:

```ts
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.

## 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
- 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 Material Design 3 tokens from the host theme for surfaces, text, outline, semantic colors, and overlay contrast.
- Use the official documentation for field catalogs, selection guidance, inline filter contracts, and custom-field troubleshooting.