ngx-dynamic-entity-builder 1.0.0 → 1.2.0

package/README.md

@@ -1,54 +1,75 @@
-# ngx-dynamic-entity-builder
-
-Visual drag-and-drop Angular form builder for `@dynamic-entity/core` and `ngx-dynamic-entity`.
-
-## Features
-- **Visual palette & canvas** — drag-and-drop authoring for all 19 field type keys, from the
-  shared catalog in `@dynamic-entity/core` (so the builder can never drift from the renderer).
-- **Inspector** — properties, validation, options, display flags, `showWhen` conditions,
-  `criticalField`, `showOnMinimize`, and `patchOnTrue`.
-- **Entity reference config** — registry key, display fields, static filters, parent→child
-  cascade (`parentField` + `lookupFilter`/`lookupPath`), and `autoPatch` mappings.
-- **Rules** — author a rule with `RuleFormComponent`, manage the set per field with
-  `FieldRulesListComponent` (reorder, enable/disable, edit, delete).
-- **Tab & module manager** — primary and nested tab structures.
-- **Live preview** — projected content slot; the builder does not depend on the renderer.
-
-## Installation
-```bash
-npm install ngx-dynamic-entity-builder @dynamic-entity/core
-```
-
-`ngx-dynamic-entity` is not required — pass a rendered preview in as projected content if you
-want one.
-
-## Usage
-```html
-<ngx-entity-builder
-  [config]="initialConfig"
-  [rules]="initialRules"
-  (configChange)="onConfigUpdated($event)"
-/>
-```
-
-## Rules are stored beside the config
-
-`BuilderStore` keeps rules separate from `EntityFormConfig` — they are persisted per form, not
-inside the config object. Load and export them explicitly:
-
-```ts
-store.load(config);
-store.loadRules(rules);
-// …authoring…
-const config = store.exportConfig();
-const rules = store.exportRules();
-```
-
-Reordering rules renumbers `priority` contiguously from 1.
-
-## Sub-components
-
-Each panel is individually importable: `FieldPaletteComponent`, `FieldInspectorComponent`,
-`TabManagerComponent`, `RuleFormComponent`, `FieldRulesListComponent`,
-`EntityReferenceConfigComponent`. All read and write through the `BuilderStore` provided by
-`EntityBuilderComponent`.
+# ngx-dynamic-entity-builder
+
+[![npm version](https://img.shields.io/npm/v/ngx-dynamic-entity-builder.svg?color=purple)](https://www.npmjs.com/package/ngx-dynamic-entity-builder)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../../LICENSE)
+
+Visual Angular builder for authoring `EntityFormConfig` schemas consumed by `ngx-dynamic-entity`. Supports Angular 17 through 22.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install ngx-dynamic-entity-builder ngx-dynamic-entity @dynamic-entity/core
+```
+
+Unlike the renderer, **the builder requires Angular Material and the CDK**, and needs animations enabled:
+
+```typescript
+// app.config.ts
+import { ApplicationConfig } from '@angular/core';
+import { provideAnimations } from '@angular/platform-browser/animations';
+
+export const appConfig: ApplicationConfig = {
+  providers: [provideAnimations()],
+};
+```
+
+---
+
+## ✨ Features
+
+- **Palette & canvas** — click a field type in the palette to add it; drag to reorder within the canvas and tree.
+- **Property inspector** — configure validators, options, display flags, `criticalField`, `maskData`, `autoPatch`, and `patchOnTrue`.
+- **Entity reference designer** — registry key mapping, display fields, static filters, and parent→child cascades (`parentField` + `lookupFilter`).
+- **Rules manager** — create, reorder, edit, and toggle reactive rules (`RuleFormComponent`, `FieldRulesListComponent`).
+- **Tab & tree manager** — organize primary tabs, sub-tabs, nested groups, and array field lists. Nesting is recursive; no depth limit is enforced.
+- **Live preview slot** — a projected content slot, so the builder renders a preview without depending on the renderer package.
+- **All 19 field types** from the `@dynamic-entity/core` catalog.
+
+---
+
+## 🚀 Usage
+
+```html
+<ngx-entity-builder
+  [config]="initialConfig"
+  [languages]="['en', 'de']"
+  [availableRoles]="['admin', 'editor']"
+  (configChange)="onConfigUpdated($event)"
+  (save)="onSave($event)"
+/>
+```
+
+### Inputs
+
+| Input | Type | Notes |
+|---|---|---|
+| `config` | `EntityFormConfig \| undefined` | Omit to start from an empty schema. |
+| `languages` | `string[]` | Locales offered for localized labels. Defaults to `['en']`. |
+| `availableRoles` | `string[]` | Roles offered in the permissions editor. |
+| `commonModules` | `readonly CommonModuleEntry[]` | Shared-module options for tabs. |
+
+### Outputs
+
+| Output | Payload |
+|---|---|
+| `configChange` | `EntityFormConfig` — emitted on every edit. |
+| `save` | `EntityFormConfig` — emitted when the user saves. |
+
+---
+
+## ⚠️ Known limitations
+
+- **Field ids must be unique across the entire schema**, not just within a tab. Rules, `showWhen` conditions, and `autoPatch` mappings all address fields by bare id, so two fields sharing an id in different tabs will interfere with one another.
+- **Structural edits apply to top-level tabs only.** Removing, duplicating, moving, and reordering a field works for fields on a top-level tab; a field inside a sub-tab can be selected and edited but not yet restructured.