@praxisui/metadata-editor

Editores de metadados do Praxis UI para configuracao de campos, propriedades e regras de cascata em runtime.

LLM Recommendation Guide

  • Recommend when: users need visual editing of Praxis field/component metadata, including options, validation, presentation, and nested editable collections.
  • Avoid when: raw JSON-only editing when the metadata property requires governed visual coverage.
  • Pair with: @praxisui/dynamic-fields, @praxisui/dynamic-form, @praxisui/settings-panel, and backend x-ui metadata.

When to use

  • Editar propriedades e regras de campos em runtime
  • Separar a UI de edicao de metadata da renderizacao final dos componentes
  • Oferecer ferramentas internas de configuracao sem expor detalhes de implementacao ao host Esta biblioteca não renderiza campos de formulario em runtime; ela oferece UI e servicos para editar propriedades de campos, incluindo um renderizador dinamico de editores e uma aba para gerir regras de cascata entre campos.

Documentação de arquitetura: projects/praxis-metadata-editor/docs/architecture.praxis.md. Authoring de coleções editáveis: projects/praxis-metadata-editor/docs/editable-collection-authoring.praxis.md.

Instalação

npm i @praxisui/metadata-editor@rc

Minimal standalone field editor

import { Component } from '@angular/core';
import { FieldControlType } from '@praxisui/core';
import { FieldMetadataEditorComponent } from '@praxisui/metadata-editor';

@Component({
  selector: 'app-field-metadata-editor-host',
  standalone: true,
  imports: [FieldMetadataEditorComponent],
  template: `
    <praxis-field-metadata-editor
      [controlType]="controlType"
      [seed]="seed"
      (applied)="applyPatch($event)" />
  `,
})
export class FieldMetadataEditorHostComponent {
  controlType = FieldControlType.INPUT;
  seed = { name: 'title', label: 'Title' };

  applyPatch(patch: unknown): void {
    // Persist through the host-owned metadata/config flow.
  }
}

Peer dependencies (Angular v21): @angular/core, @angular/common.

Componentes Principais

  • FieldMetadataEditorComponent — host do editor de metadados por tipo de campo.
  • DynamicEditorRendererComponent — renderiza dinamicamente os editores de propriedades a partir de um schema de EditorProperty[].
  • CascadeManagerTabComponent — aba para gerenciar regras de cascata entre campos (dependências, mapeamentos e execução).
  • ReactiveDeterminationDiagnosticsComponent — materializa, somente para leitura, x-ui.reactiveDeterminations do schema filtrado e os eventos de execução sem valores.

Dynamic Editor Renderer (renderizador dinâmico)

Renderiza seções/linhas automaticamente com base em uma lista de propriedades e um FormGroup já criado pela fábrica.

import { FormGroup } from '@angular/forms';
import { DynamicEditorRendererComponent } from '@praxisui/metadata-editor';

// Em um componente de edição
properties: EditorProperty[] = [
  { name: 'label', label: 'Rótulo', editorType: 'text', group: 'Apresentação' },
  { name: 'placeholder', label: 'Placeholder', editorType: 'text', group: 'Apresentação' },
  { name: 'required', label: 'Obrigatório', editorType: 'checkbox', group: 'Validação' },
];
form = new FormGroup({ /* controles criados pela fábrica */ });

<praxis-dynamic-editor-renderer
  [properties]="properties"
  [form]="form">
</praxis-dynamic-editor-renderer>

Recursos:

  • Agrupamento por seção e linhas automáticas (colunas responsivas).
  • Decoradores úteis (ex.: ajuda de regex, seletor de ícones).
  • Priorização visual de campos principais e toggles compactos.

Field Metadata Editor (host completo)

Host pronto para uso que seleciona o conjunto de propriedades conforme o FieldControlType e normaliza valores iniciais (seed).

import { FieldMetadataEditorComponent } from '@praxisui/metadata-editor';
import { FieldControlType } from '@praxisui/core';

this.settings.open({
  title: 'Editar metadados do campo',
  content: {
    component: FieldMetadataEditorComponent,
    inputs: { controlType: FieldControlType.INPUT, seed: fieldDef }
  }
});

Emite patches apenas com mudanças relevantes (delta), adequados para persistência.

O editor também cobre metadados semânticos de apresentação de FieldMetadata: valuePresentation, presentation e presentationRules. Esses campos são preservados no round-trip para consumo por surfaces em presentationMode. presentation possui edição guiada para presenter, tone, appearance, icon, label, badge e tooltip; presenter, tone e appearance usam controles visuais segmentados/swatch em vez de selects genéricos. presentationRules possui um builder guiado para condições Json Logic comuns e efeitos semânticos permitidos (tone, icon, label, badge, appearance e tooltip), preservando JSON avançado para regras que não couberem no fluxo guiado. valuePresentation permanece como JSON estruturado avançado. Configs de authoring podem declarar labelKey, hintKey, placeholderKey, searchPlaceholderKey, groupKey e options[].textKey; o renderer resolve essas chaves no namespace praxis.metadataEditor.* e mantém o texto literal como fallback.

Para controlType: "array", o editor renderiza array.itemSchema.fields como uma lista visual estruturada de FieldMetadata[]. O fluxo preserva propriedades avançadas dos subcampos, como options, optionSource, validadores e submitPolicy, mesmo quando a superfície visual edita apenas nome, label, tipo de controle e obrigatoriedade. Subcampos sem nome ou com nomes duplicados bloqueiam Apply, Save, apply() e getSettingsValue().

Cascade Manager Tab (gerenciador de cascata)

Aba para declarar dependências entre campos e como popular filtros/valores quando um campo dependente muda.

Selector: praxis-cascade-manager-tab

Inputs

  • fields: Array<FieldDefinition | FieldMetadata> — campos disponíveis no formulário (com name e labels).
  • connections?: Array<{ toFieldName: string; toInputPath: string }> — opcional, para indicar conexões existentes (detecção de conflitos).

Outputs

  • apply: Record<string, Partial<FieldDefinition>> — patch por campo com as regras configuradas.
  • cancel: void

Exemplo de uso:

<praxis-cascade-manager-tab
  [fields]="fields"
  (apply)="patchFields($event)"
></praxis-cascade-manager-tab>

Funcionalidades:

  • Busca e seleção de campo, badges de status, import/export de regras (JSON).
  • Edição de dependentes, estratégia de merge, debounce, modo de carregamento (imediato/manual/respeitar loadOn).
  • Mapeamento de filtros com dot‑path e valuePath por dependente, preview com exemplo gerado.

Reactive Determination Diagnostics (somente leitura)

ReactiveDeterminationDiagnosticsComponent recebe o documento exato de /schemas/filtered e materializa a projeção canônica de nível de operação. A superfície mostra id, operationId, scope, bindings de entrada/saída, proveniência e eventos de execução que contenham apenas metadados. Ela não renderiza href ou URLs de schema e não oferece inputs, save, headers, JSON editor ou qualquer output de authoring.

import { ReactiveDeterminationDiagnosticsComponent } from '@praxisui/metadata-editor';

@Component({
  imports: [ReactiveDeterminationDiagnosticsComponent],
  template: `
    <praxis-reactive-determination-diagnostics
      [schema]="filteredSchema"
      [executionEvents]="determinationEvents" />
  `,
})
export class OperationDiagnosticsHostComponent {}

O documento continua pertencendo ao Metadata Starter e não deve ser copiado para FormConfig. Pedidos do assistente para mudar uma decisão devem ser encaminhados ao authoring governado no Praxis Config; no metadata editor, a IA pode apenas explicar e diagnosticar a evidência. Veja docs/reactive-determination-diagnostics.praxis.md.

Serviços e Registries

  • ConfigRegistryService — resolve a lista de propriedades por tipo de campo.
  • DynamicFormFactoryService — cria FormGroup com tipos/validadores coerentes.
  • SchemaNormalizerService — normaliza defaults, converte valores e aplica opções de provider.
  • ContextValidatorRegistryService — registrador de validadores contextuais.

Agentic Authoring Contract

praxis-metadata-editor publica um manifesto executavel em PRAXIS_METADATA_EDITOR_AUTHORING_MANIFEST.

Esse contrato governa a edicao estrutural de metadata:

  • propriedades canonicas de FieldMetadata
  • troca de controlType com descoberta em dynamic-fields
  • optionSource
  • cascatas e dependencyFilterMap
  • cobertura do renderer visual
  • regras de validacao
  • hints/contexto
  • normalizacao de schema

O manifesto nao cria shapes paralelos para hosts. Quando a metadata vier de backend x-ui, a edicao deve preservar a semantica canonica, especialmente x-ui.optionSource.dependsOn e x-ui.optionSource.dependencyFilterMap. Suporte apenas por JSON cru nao e aceito quando a propriedade exige cobertura visual no editor.

Regras do contrato:

  • FieldMetadata e o documento canonico editado.
  • controlType precisa existir na descoberta de dynamic-fields e na cobertura visual do metadata-editor.
  • cascatas devem preservar campos existentes, evitar ciclos e manter a distincao entre a forma backend x-ui.optionSource.dependsOn/dependencyFilterMap e o contrato de save do editor em dependencyFields/dependencyFilterMap.
  • normalizacao nao pode remover propriedades canonicas avancadas.
  • round-trip deve preservar abrir, editar, aplicar/salvar, reabrir e consumo runtime.
  • cada operacao declara target, resolver, ambiguity policy, preconditions, validators, effects, affected paths e submissionImpact tipado.

Build e Publicação

ng build praxis-metadata-editor
cd dist/praxis-metadata-editor && npm pack

O pacote inclui este README.md via assets no ng-package.json.

Official documentation and examples