ui-form-interpreter
@mmm/ui-form-interpreter
Installation
pnpm add @mmm/ui-form-interpreterPeer Dependencies muessen im Service vorhanden sein:
"@angular/common": "^17.0.0 || ^18.0.0 || ^19.0.0 || ^20.3.16 || ^21.2.16""@angular/core": "^17.0.0 || ^18.0.0 || ^19.0.0 || ^20.3.16 || ^21.2.16""@angular/forms": "^17.0.0 || ^18.0.0 || ^19.0.0 || ^20.3.16 || ^21.2.16""@angular/router": "^17.0.0 || ^18.0.0 || ^19.0.0 || ^20.3.16 || ^21.2.16""@angular/cdk": "^21.0.0""@mmm/designsystem": "^1.9.0""rxjs": "^7.8.2"
Schnellstart
Modul registrieren
Das Modul kann über das imports-Array einer Komponente sowie als Provider eingebunden werden.
Service konfigurieren
Um ein Formular mittels des Forminterpreters anzeigen zu können, muss das Schema dem FormInterpreterService übergeben werden. Hierfŭr kann der setSchema-Aufruf des InterpreterService verwendet werden.
const schema: TFormSchema = { "id": "signup", "version": 1, "title": "Newsletter Sign-up", "description": "Example", "boxed": "true", // neu, per default true, zeigt boxed design an. false, versteckt es "hideProgress": "false", // default false, true für reguläre formulare "sections": [ { "key": "base", "title": "Basic Data", "fields": [ { "key": "newsletter", "type": "checkbox", "label": "Subscribe to newsletter", "defaultValue": false }, { "key": "email", "type": "input", "label": "E-mail", "placeholder": "you@example.com", "requiredIf": { "field": "newsletter", "op": "==", "value": true }, "validators": [{ "name": "email" }], "visibleIf": { "field": "newsletter", "op": "==", "value": true } }, { "key": "country", "type": "select", "label": "Country", "options": { "source": "static", "items": [ { "value": "DE", "label": "Germany" }, { "value": "AT", "label": "Austria" } ] } }, { "key": "zip", "type": "input", "label": "ZIP", "validators": [{ "name": "pattern", "pattern": "^\\d{5}$" }], "enabledIf": { "any": [ { "field": "country", "op": "==", "value": "DE" }, { "field": "country", "op": "==", "value": "AT" } ] } }, { "key": "start", "type": "date", "label": "Start date" }, { "key": "end", "type": "date", "label": "End date", "validators": [{ "name": "dateBounds", "minField": "start" }] } ] } ], "submit": { "label": "Submit" }}
this.formInterpreter.setSchema(schema)Dem Schema können auch Standardwerte für Formwerte übergeben werden:
this.formInterpreter.setSchema(schema, {email: "test@example.org"})Bedingte Auswahlmöglichkeiten
Statische Auswahlmöglichkeiten (select, radio, checkboxGroup) können über visibleIf ausgeblendet werden. Der Ausdruck wird wie visibleIf eines Feldes ausgewertet, also auch gegen configs:
{ "key": "verbindlichkeiten", "type": "checkboxGroup", "options": { "source": "static", "items": [ { "value": "kredite", "label": "Kredite" }, { "value": "buergschaften", "label": "Bürgschaften", "visibleIf": { "field": "entryId", "op": "==", "value": "3" } } ] }}Verschwindet eine ausgewählte Möglichkeit, wird die Auswahl zurückgesetzt: bei select und radio auf null, bei checkboxGroup werden nur die ausgeblendeten Werte entfernt. Das gilt auch für Startwerte aus setSchema, deren Möglichkeit für dieses Formular ausgeblendet ist. Eigene Bausteine mit Optionen filtern über InterpreterService.visibleOptions(items, group).
Bedingte Werte (Fallunterscheidung)
Jedes Attribut eines Feldes kann statt eines festen Werts eine Fallunterscheidung enthalten. field wird wie in Ausdrücken aufgelöst (Control der Gruppe, Pfad mit Punkt ab der Wurzel, configs); der erste Fall, dessen case dem Wert entspricht oder ihn als Liste enthält, gewinnt, sonst default:
{ "key": "immobilienvermoegen", "type": "checkbox", "label": { "field": "entryId", "cases": [{ "case": "4", "value": "Ihre Immobilie" }], "default": "Immobilienvermögen" }, "defaultValue": { "field": "entryId", "cases": [{ "case": ["4", "5"], "value": true }], "default": false }}Anzeige-Attribute (label, hint, …) werden vor dem Rendern aufgelöst und folgen dem Formularzustand; eigene Bausteine erhalten über nodedata bereits aufgelöste Werte. defaultValue wird beim Anlegen des Controls aufgelöst und folgt seinem Bezugsfeld danach nur so lange, wie das Control unberührt ist und kein gespeicherter Wert geladen wurde – die erste Eingabe beendet das. Ohne setSchema-Gruppe (z. B. in Schleifen) stehen beim Anlegen nur die configs zur Verfügung. Zum Auflösen außerhalb des Interpreters gibt es resolveValueExpr, resolveIfValueExpr und InterpreterService.resolveField.
Ausgeblendete Felder
Ein Feld, das nicht sichtbar ist – durch sein eigenes visibleIf, das seines Layouts oder das seiner Sektion –, wird nicht validiert und blockiert weder „Weiter“ noch das Absenden. Wird es wieder sichtbar, gelten seine Validatoren sofort wieder. requiredIf und when an Validatoren lösen Werte genauso auf wie visibleIf (inklusive Pfaden mit Punkt, parentIndex und configs).
Alle Felder werden zu denselben Zeitpunkten validiert, ob mit Bedingungen oder ohne: bei jeder eigenen Änderung, einmal nachdem das Control im Formular hängt (bei setSchema noch bevor das Formular veröffentlicht wird) und immer dann, wenn sich Sichtbarkeit, requiredIf oder ein when des Feldes ändert. Das gilt auch für Controls, die eigene Bausteine über createControl anlegen, z. B. Schleifeneinträge.
Felder mit demselben Key in einer Sektion (z. B. in zusammengeführten Schemata einmal je Entry) teilen sich ein Control. Es gilt erst als ausgeblendet, wenn alle diese Felder ausgeblendet sind – jedes mit seinem eigenen visibleIf, seinem Layout und seiner Seite.
Eigene Bausteine, deren Control weitere Controls enthält (z. B. das FormArray einer Schleife), setzen es über InterpreterService.setContainerControl(group, field, control) an Stelle des Standard-Controls unter field.key ein. Ist der Baustein ausgeblendet – an jeder Stelle des ersetzten Controls im Schema, also durch das visibleIf, das Layout, die Seite oder die Sektion jedes Feldes mit diesem Key –, wird keines der Controls darin validiert, auch nicht in verschachtelten Bausteinen. Ohne ersetztes Control (z. B. in einem Schleifeneintrag) zählt nur das visibleIf von field, ausgewertet in group. Mit group.setControl eingesetzte Controls kennt der Interpreter dagegen nicht: Ihre Einträge würden weiter validiert, sobald der Baustein ausgeblendet ist.
Akkordeon-Variante
Layout-Felder vom Typ accordion können über variant die Darstellung des Designsystem-Akkordeons steuern:
{ "key": "antragsteller", "type": "accordion", "label": "Antragsteller", "variant": "boxed" }Erlaubt sind default (Standard) und boxed. Fehlt der Wert oder ist er unbekannt, wird default verwendet – bestehende Schemata rendern unverändert.
Ein Akkordeon zeigt den Fehlerzustand des Designsystems (error), sobald eines seiner sichtbaren Felder ungültig ist und seinen Fehler selbst anzeigt – also berührt oder geändert wurde, etwa nach „Weiter“ oder beim Verlassen eines Feldes. Ausgeblendete Felder zählen nicht; Controls eigener Bausteine (z. B. das FormArray einer Schleife) fassen ihre Einträge zusammen. Der Zustand folgt den Controls auch dann, wenn kein Elternteil der Untergruppe geprüft wird.
Unterseiten innerhalb einer Sektion
Eine Sektion kann in Unterseiten aufgeteilt werden, die der Nutzer mit „Weiter“/„Zurück“ durchläuft, ohne dass der Stepper weiterrückt. Eine Unterseite ist ein Layout-Feld vom Typ page – wie accordion nie ein Control, die Formularwerte bleiben flach pro Sektion. Felder und Layouts gehören über layoutKey zu einer Seite; Felder in einem Akkordeon zeigen weiterhin auf das Akkordeon, das Akkordeon selbst auf die Seite:
{ "key": "antragsteller", "fields": [ { "key": "page-person", "type": "page", "label": "Angaben zur Person", "description": "<p>…</p>", "imgUrl": "…", "imgAlt": "…" }, { "key": "person", "type": "accordion", "label": "Person", "layoutKey": "page-person" }, { "key": "name", "type": "input", "label": "Name", "layoutKey": "person", "validators": [{ "name": "required" }] }, { "key": "page-adresse", "type": "page", "label": "Adresse", "visibleIf": { "field": "entryId", "op": "==", "value": "3" } }, { "key": "strasse", "type": "input", "label": "Straße", "layoutKey": "page-adresse" } ]}- Gruppen ohne Seitenzuordnung gehören zur letzten
pagedavor in der Feldreihenfolge (Gruppen vor der ersten Seite zur ersten). Eine Sektion ohnepage-Feld verhält sich wie bisher. - „Weiter“ validiert nur die Felder der aktuellen Seite; beim Verlassen der letzten Seite die ganze Sektion. „Werte später ausfüllen“ überspringt Seiten ohne Prüfung, „Zurück“ geht seitenweise zurück und landet aus der Folgesektion auf der letzten Seite.
- Eine Seite, deren
visibleIfnicht zutrifft oder auf der kein Feld sichtbar ist, wird übersprungen; ihre Felder werden wie bei einem ausgeblendeten Akkordeon nicht validiert. - Ab zwei sichtbaren Seiten zeigt der Stepper die Seiten als Substeps des Schritts (Zustand je Seite wie der Schrittzustand).
label,description,imgUrlundimgAltrendert der Interpreter nicht selbst; die App bekommt die aktuelle Seite überInterpreter.currentPage$(Seite mit aufgelösten Fallunterscheidungen, Index und Anzahl) und wählt eine Seite mitInterpreter.goToPage(sectionKey, pageKey), z. B. aus der URL. Die Zusammenfassung springt mitgoToIndexauf die Seite des Feldes.- Hilfsfunktionen:
pagesOf(fields)liefert die Seiten mit ihren Gruppen,InterpreterService.visiblePages(section, form)nur die sichtbaren.
Aktionsleiste und Akkordeons konfigurieren
{ "labels": { "restart": "Neustart", "later": "Später ausfüllen", "next": "Weiter", "pdfPreview": "PDF Vorschau" }, "openFirstAccordion": true}labels überschreibt einzelne Beschriftungen der Aktionsleiste (nicht gesetzte behalten den Standard). openFirstAccordion öffnet je Sektion das erste Akkordeon initial, das tatsächlich gerendert wird (ausgeblendete Akkordeons zählen nicht); Standard ist false.
Eigene Bausteine, die Akkordeons rendern (z. B. Schleifen), nehmen über InterpreterService.claimOpenFirstAccordion(sectionKey) teil: Der erste Aufrufer je Sektion erhält true. Rendern sie fj-subgroup, passiert das automatisch; den Sektions-Key eines beliebigen Controls liefert InterpreterService.sectionKeyFor(control).
Komponentenbindings
Standardmäßig werden verschiedene Komponenten des Designsystems mittels des Feldtyps zu Formfeldern oder Layouts gerendert. Folgende Liste wird out of the box unterstützt:
Sollten weitere Komponenten benötigt werden oder aber eine der Standardkomponenten überschrieben werden, können eigene Komponenten für Feldtypen registriert werden.
Die zu registrierende Komponent muss entweder FormBindingBase (für die Verwendung als Formularfeld) oder BindingBase erweitern (für arbiträre Komponenten wie beispielsweise ein Video oder ein Hilfsrechner, die nicht Teil des Formulars sind und nicht validiert werden müssen).
Zur Registrierung kann folgender Aufruf verwendet werden:
this.interpreterService.registerCustomNode({ key: 'custom', component: CustomComponent})Exports
Das Paket exportiert:
FormInterpreterModuleFormInterpreterServiceTFormSchemaTExprTValidatorTOptionItemTOptionsTMaskTFieldTSectionevaluateExprgetValueAtPathBindingBaseFormBindingBaseInterpreterFjGroupFjFieldRendererFjSubgroup
@mmm/ui-form-interpreter/core
Schema und Auswertung ohne Angular, etwa um gespeicherte Werte auf einem Server so darzustellen, wie der Interpreter sie zeigt. Der Interpreter nutzt dieselben Funktionen, das Hauptpaket exportiert sie weiterhin mit.
- Typen des Schemas (
TFormSchema,TField,TExpr,TValueExpr, …) evaluateExpr,resolveValueExpr,resolveAttributes: Ausdrücke und Fallunterscheidungen auswertendataLookup: Werte für Ausdrücke aus gespeicherten Daten nachschlagen, mit denselben Regeln wie im Formular (Punktnotation global,parentIndex/parent,configsals Rückfall)groupFields,pagesOf: Felder wie der Interpreter in Layouts und Unterseiten gruppierenplaceGroups: die Gruppen einer Sektion mit den Bedingungen von Sektion, Unterseite und LayoutinterpolateSchema:{{platzhalter}}durch dieconfigsersetzen
import { dataLookup, evaluateExpr, interpolateSchema, placeGroups } from '@mmm/ui-form-interpreter/core';
const schema = interpolateSchema({ ...savedSchema, configs });for (const section of schema.sections) { const values = data[section.key]; const outer = dataLookup({ values: data, root: data, configs }); const inner = dataLookup({ values, root: data, configs }); for (const { group, conditions } of placeGroups(section)) { if (!conditions.every((condition) => evaluateExpr(condition, outer))) continue; const shown = group.fields.filter((field) => evaluateExpr(field.visibleIf, inner)); }}Das Paket liefert nur ESM aus. CommonJS-Projekte laden es ab Node 22.12 per
require, TypeScript braucht dafür "module": "nodenext" (ab 5.8).
Entwicklung
Build:
pnpm buildPublish passiert ueber die Bitbucket-Pipeline.
Vorabversionen (next)
Jeder Push auf den Branch next veroeffentlicht automatisch eine Vorabversion unter dem Dist-Tag next, z. B. 1.22.0-next.3. Die Basis ist die naechste stabile Version (hoechster vX.Y.Z-Tag, Minor + 1), die Nummer zaehlt pro Basis hoch. Normale Versionsbereiche wie ^1.21.0 installieren Vorabversionen nie, latest bleibt auf dem letzten stabilen Release. Vorabversionen erzeugen keinen Git-Tag.
git checkout -b feature/xyz nextgit push -u origin feature/xyz # veroeffentlicht nichts# PR nach next mergen → automatisch 1.X.0-next.N- Jeder Merge auf
nextveroeffentlicht eine neuenext-Version. - Fuer ein stabiles Release wird
nextnachmaingemerged. - Nach dem Release spult die Pipeline
nextper Fast-Forward aufmainvor. Hatnextinzwischen eigene Commits, schlaegt das fehl (nur Warnung im Log), dannmainmanuell nachnextmergen.
Major-Version
Enthaelt ein Commit seit dem letzten Release-Tag feat!: … (allgemein <typ>(<scope>)!:) oder eine Zeile BREAKING CHANGE: …, wird die Major-Version erhoeht. Auf next entsteht dann z. B. 2.0.0-next.1, beim Merge nach main wird daraus v2.0.0. Danach geht es normal mit 2.1.0 weiter.
Tags nicht von Hand auf next setzen: Jeder v*-Tag startet sofort die Tag-Pipeline und veroeffentlicht eine stabile Version unter latest.
next erhoeht die Major-Version nicht von allein: Taucht ein Breaking-Marker auf next auf, schlaegt die Pipeline fehl, statt 2.0.0-next.N zu veroeffentlichen. Fuer die naechste Major-Version gibt es den Branch v2 (siehe unten).
Naechste Major-Version (v2)
Der Branch v2 veroeffentlicht bei jedem Push eine Vorabversion der naechsten Major-Version unter dem Dist-Tag next-v2, z. B. 2.0.0-next.4. Die Pipeline verlangt den Major-Sprung: Mindestens ein Commit auf v2 traegt feat!: … oder BREAKING CHANGE: …, sonst schlaegt sie fehl. Die Nummer zaehlt unabhaengig von next hoch, latest und next bleiben unberuehrt. (v2 ist als Dist-Tag nicht erlaubt, npm liest es als Versionsbereich.)
pnpm add @mmm/ui-form-interpreter@next-v2 # neueste v2-Vorabversion- Jeder Merge auf
v2veroeffentlicht eine neue2.0.0-next.N. v2wird nicht automatisch vonmainvorgespult. Fixes ausmainregelmaessig nachv2mergen, damit der spaetere Merge klein bleibt.- Fuer das stabile
v2.0.0wirdv2nachmaingemerged (direkt oder uebernext). Der Breaking-Marker wandert mit,mainerzeugtv2.0.0. - Soll
v2vorher uebernextlaufen: Repository-VariableNEXT_MAJOR_BUMP=allowsetzen, sonst lehntnextden Major-Sprung ab. Nach dem Release wieder entfernen.
Nach v2.0.0 nimmt main den hoechsten Tag ueber alle Majors als Basis, eine 1.x-Pflegelinie gibt es ohne Anpassung der Pipeline nicht mehr. Der Branch v2 kann dann geloescht werden.
Installation:
pnpm add @mmm/ui-form-interpreter@next # neueste next-Versionpnpm add @mmm/ui-form-interpreter@latest # zurueck auf die stabile Version