@praxisui/dynamic-form 0.0.1

package/LICENSE

@@ -0,0 +1,7 @@
+This package is licensed under the Apache License, Version 2.0.
+
+For the full license text, see the repository root LICENSE file:
+../../LICENSE
+
+Apache License 2.0: https://www.apache.org/licenses/LICENSE-2.0
+

package/README.md

@@ -0,0 +1,166 @@
+# @praxisui/dynamic-form
+
+> Standalone dynamic form component with schema-driven UI, native field cascades, settings integration, and a built-in configuration editor.
+
+## Install
+
+```bash
+npm i @praxisui/dynamic-form
+```
+
+Peer dependencies (Angular v20):
+- `@angular/core` `^20.0.0`
+- `@angular/common` `^20.0.0`
+- `@angular/cdk` `^20.0.0`
+- `@praxisui/core` `^0.0.1`
+- `@praxisui/specification-core` `^0.0.1`
+- `@praxisui/specification` `^0.0.1`
+- `@praxisui/visual-builder` `^0.0.1`
+- `@praxisui/settings-panel` `^0.0.1`
+- `@praxisui/cron-builder` `^0.0.1`
+
+## Quick Start
+
+### 1) PraxisDynamicForm (standalone)
+
+```ts
+import { Component } from '@angular/core';
+import { PraxisDynamicForm } from '@praxisui/dynamic-form';
+import type { FormConfig } from '@praxisui/core';
+
+@Component({
+  selector: 'app-form-demo',
+  standalone: true,
+  imports: [PraxisDynamicForm],
+  template: `
+    <praxis-dynamic-form
+      [config]="config"
+      [mode]="'create'"
+      [editModeEnabled]="true"
+      (formSubmit)="onSubmit($event)"
+    ></praxis-dynamic-form>
+  `,
+})
+export class FormDemoComponent {
+  config: FormConfig = {
+    sections: [
+      {
+        id: 'main',
+        label: 'Employee',
+        rows: [
+          {
+            columns: [
+              { fields: [{ name: 'fullName', label: 'Full Name', controlType: 'text' }] },
+              { fields: [{ name: 'email', label: 'E-mail', controlType: 'email' }] },
+            ],
+          },
+        ],
+      },
+    ],
+  } as any;
+
+  onSubmit(evt: any) {
+    console.log('Submitted:', evt);
+  }
+}
+```
+
+Tip: connect to a backend resource by setting `resourcePath`/`resourceId`. The component can fetch schemas and reconcile local layout with server metadata when `editModeEnabled` is true.
+
+### 2) Config Editor component
+
+Use the standalone editor directly to edit and reconcile the form configuration.
+
+```ts
+import { Component } from '@angular/core';
+import { MatDialog } from '@angular/material/dialog';
+import { PraxisDynamicFormConfigEditor } from '@praxisui/dynamic-form';
+import type { FormConfig } from '@praxisui/core';
+
+@Component({
+  selector: 'app-form-editor-launcher',
+  standalone: true,
+  template: `<button (click)="openEditor()">Open Config Editor</button>`,
+})
+export class FormEditorLauncherComponent {
+  constructor(private dialog: MatDialog) {}
+
+  openEditor() {
+    const initial: FormConfig = { sections: [] } as any;
+    this.dialog.open(PraxisDynamicFormConfigEditor, {
+      width: '1024px',
+      data: { formConfig: initial, formId: 'employees-form', mode: 'edit' },
+    });
+  }
+}
+```
+
+Alternatively, when `editModeEnabled` is true, `praxis-dynamic-form` renders a gear button that opens the editor internally.
+
+## API Surface
+
+- Components: `PraxisDynamicForm`, `PraxisDynamicFormConfigEditor`, `JsonConfigEditorComponent`, `LayoutEditorComponent`
+- Services: `FormConfigService`, `FormLayoutService`, `DynamicFormLayoutService`, `FormContextService`
+- Utilities: form rule converters, normalize date arrays
+- Metadata helpers: `providePraxisDynamicFormMetadata`
+
+See public exports: `projects/praxis-dynamic-form/src/public-api.ts`.
+
+## Compatibility
+
+- `@praxisui/dynamic-form` `0.0.x` → Angular `20.x`
+- Module format: `ESM2022`
+
+## License
+
+Apache-2.0 – see the `LICENSE` packaged with this library or the repository root.
+
+# Praxis Dynamic Form — Cascata vs Connections
+
+### Concept Usage
+
+- [Data Driven Forms](../../../../docs/concepts/data-driven-forms.md)
+- [Declarative UI](../../../../docs/concepts/declarative-ui.md)
+- [Schema‑driven UI](../../../../docs/concepts/schema-driven-ui.md)
+
+## Quando usar cada mecanismo
+
+- Connections (dot‑path)
+  - Para orquestração “externa” (entre widgets, tabs, tabelas ou fora do formulário).
+  - Escrevem em `inputs.config.*` do widget do formulário, inclusive metadados de campos (ex.: `inputs.config.fieldMetadata[i].filterCriteria`).
+  - Escala bem para cenários de página e integração cross‑widget.
+
+- Cascata nativa (campo→campo, intra‑form)
+  - Declarativa via metadata (`dependencyFields`, `resetOnDependentChange`, etc.).
+  - Observa `FormControl.valueChanges` dos campos dependentes, aplica `filterCriteria` e recarrega conforme estratégia (`loadOn`, `dependencyLoadOnChange`).
+  - Elimina código ad hoc na página.
+
+## Convivência e fonte de verdade
+
+- Se Connections atualizam `filterCriteria` de um campo, considere desativar a cascata nativa nesse campo (`enableDependencyCascade: false`) ou usar `dependencyLoadOnChange: 'manual'` (cascata só atualiza filtros e Connections disparam o load).
+- Estratégia de merge recomendada: `dependencyMergeStrategy: 'merge'` para preservar chaves vindas de Connections.
+
+## Links úteis
+
+- Fluxo de Schema (ETag/304, schemaId, reconciliação): `docs/schemas/fluxo-schema.md`
+- Guia de implementação e metadados da cascata: `docs/CASCADE-NATIVA.md`
+- Padrões de endpoints (Options vs Filter) para selects: `docs/DEVS-GENERIC-CRUD-SERVICE.md`
+
+## Verificação de Schema (ETag/If-None-Match)
+
+- Inputs (opcionais; ativos apenas com `editModeEnabled=true`):
+  - `notifyIfOutdated: 'inline' | 'snackbar' | 'both' | 'none' = 'both'`
+  - `snoozeMs: number = 86400000`
+  - `autoOpenSettingsOnOutdated: boolean = false`
+- Output:
+  - `schemaStatusChange: { outdated: boolean; serverHash?: string; lastVerifiedAt?: string; formId?: string }`
+- Persistência (ConfigStorage):
+  - `form-schema-meta:{formId}` → `{ serverHash?: string; lastVerifiedAt?: string }`
+  - `form-schema-prefs:{formId}` → `{ notifyIfOutdated?, snoozeMs?, autoOpenSettingsOnOutdated? }`
+  - Por hash (suppress): `schemaIgnore:{formId}:{hash}`, `schemaSnooze:{formId}:{hash}`, `schemaNotified:{formId}:{hash}`
+- Comportamento:
+  - Quando já existe base local (ex.: `config.sections.length > 0`), o componente faz uma verificação leve via `/schemas/filtered` com `If-None-Match`.
+  - 304 → apenas atualiza `lastVerifiedAt` e emite `schemaStatusChange(outdated=false)`.
+  - 200 → atualiza `serverHash/lastVerifiedAt`, define `schemaOutdated = editModeEnabled && hadBase`, emite `schemaStatusChange`. Não aplica schema automaticamente.
+  - Primeira vez (sem base): baixa o corpo do schema para gerar o layout; persiste `form-schema-meta:{formId}`.
+  - Notificações respeitam preferências e são one‑shot por hash; o banner/snackbar oferecem ações para Reconciliar, Lembrar depois (snooze) e Ignorar.