Wenn Sie TrueFoundry bereits zum Bereitstellen eines Dienstes, Erstellen eines Clusters, Konfigurieren eines LLM-Modells oder Verwalten von Secrets verwendet haben, sind Sie mit Formularen in Berührung gekommen, die wie gewöhnliche Benutzeroberflächen aussehen, aber grundlegend anders aufgebaut sind als typische Webformulare.

Warum TrueFoundry schema-basierte Formulare verwendet

TrueFoundry-Formulare repräsentieren oft Manifeste – YAML/JSON-Objekte, die Sie auch über die CLI (tfy apply -f ...) anwenden können. Dasselbe Objekt kann in der Benutzeroberfläche bearbeitet, als YAML heruntergeladen oder an die API übermittelt werden.

Ein schema-basierter Ansatz bietet TrueFoundry:

• Eine einzige Quelle der Wahrheit für die Formularstruktur (wird pro Ressourcentyp vom Backend geladen).
• Konsistentes Verhalten bei Bereitstellungen, Clustern, Richtlinien, Modellen, Secrets, Einstellungsformularen oder jedem anderen Formular auf der Plattform.
• Verschachtelte und bedingte Felder, ohne die Formularlogik auf jedem Bildschirm neu schreiben zu müssen.
• Domänenspezifische Widgets (Cluster-Auswahl, Secret-Selektor, Ressourcenlimits), die in eine gemeinsame Laufzeitumgebung integriert sind.

Das mentale Modell: Das Schema beschreibt die Struktur der Daten und wie diese bearbeitet werden; der FormBuilder verwandelt diese Beschreibung in ein funktionierendes Formular.

1. Formularschema:

Ein Formularschema ist ein Array von Felddefinitionen. Jedes Feld ist ein Objekt mit einigen wichtigen Eigenschaften:

Hier ist ein vereinfachtes, allgemeines Beispiel – kein echtes TrueFoundry-Schema, aber nah an der Art und Weise, wie das Produkt Konfigurationen betrachtet:

[
  {
    "sort": 1,
    "jsonKey": "name",
    "label": "Service Name",
    "uiType": "Input",
    "validate": { "required": true, "pattern": "^[a-z0-9-]+$" }
  },
  {
    "sort": 2,
    "jsonKey": "image",
    "label": "Image",
    "uiType": "Group",
    "subParameters": [
      {
        "jsonKey": "type",
        "label": "Source",
        "uiType": "Radio",
        "validate": {
          "required": true,
          "defaultValue": "build",
          "options": [
            { "label": "Build", "value": "build" },
            { "label": "Existing image", "value": "existing" }
          ]
        }
      },
      {
        "jsonKey": "uri",
        "label": "Image URI",
        "uiType": "Input",
        "conditions": [
 		{ "jsonKey": "image.type", "op": "==", "value": "existing"  }
  ],
        "validate": { "required": true }
      }
    ]
  }
]

Resultierendes Manifest/Konfiguration beim Absenden:

{
  "name": "my-service",
  "image": { "type": "existing", "uri": "registry.io/app:v1" }
}

2. Wie Komponenten zugeordnet und Felder gerendert werden

Das Rendering erfolgt in einer kleinen Pipeline, der Ablauf ist wie folgt:

Der FormBuilder durchläuft den Schemabaum und wählt pro Knoten basierend auf dem uiType eine React-Komponente aus.

Komponententypen:

• Basis: Input, Select, Radio, Switch, Number
• Strukturell: Group (Abschnitt), Structs (wiederholbare Liste), KV / ENV (Key-Value)
• Domänenspezifisch: ClusterSelect, SecretSelect, Resources, ModelSelect, PermissionsMatrix, MCP-Felder und mehr

Bedingungen: Wenn image.type !== "existing", wird das URI-Feld nie eingebunden. Mit shouldUnregister: true wird es zudem aus dem Formularstatus entfernt, sodass versteckte Werte nicht in die Payload gelangen können.

Mapping-Logik im Code:

// FormComponentMap
const ComponentType = FormComponents[schema.uiType]
const CustomComp = CustomComponentsMap?.[schema.uiType]

if (!enabledByCondition) return null

return CustomComp
  ? <CustomComp schema={schema} />
  : <ComponentType schema={schema} />

3. Handhabung des Formularstatus

FormBuilder verwendet react-hook-form als State-Engine. Diese Wahl ist entscheidend für das Verhalten des Produkts.

Initialisierung/Komponentennutzung – Erstellen & Bearbeiten:

<FormBuilder
  schema={schema}
  defaultValues={existingManifest}   // edit: pre-fill; create: empty/template
  onSubmit={(manifest) => createOrUpdate({ manifest })}
/>

Formular-Setup:

const methods = useForm({
  mode: 'onChange',          // validate as user types
  defaultValues,
  shouldUnregister: true,    // hidden fields drop out of state
})

Feldregistrierung – jede Eingabe ist an ihren Pfad gebunden:

// Inside a text field component
const { register } = useFormContext()

<input
  {...register(schema.jsonKey, registerProps)}
  defaultValue={defaultValue}
/>

Zusätzlicher Kontext – spezifische Formulare übergeben Laufzeitdaten getrennt von den Feldwerten:

<FormBuilder
  schema={schema}
  extraContext={{
    workspace,
    cluster,
    serviceAccountOptions,  // dynamic dropdown options
    dataTestPrefix: 'create-cluster',
  }}
/>

Einzelnes Objekt, verschachtelte Pfade:

Alle Feldwerte befinden sich in einem einzigen Formularobjekt. Jedes Feld registriert sich unter seinem vollständigen jsonKey-Pfad:

• name → String auf oberster Ebene
• image.type → verschachtelter Wert
• ports.0.container_port → erstes Element in einem Array

Wenn Sie ein Feld bearbeiten, verändern Sie dieses gemeinsam genutzte Objekt. Beim Absenden liest FormBuilder das gesamte Objekt aus und übergibt es an den Handler des Formulars (der normalerweise die TrueFoundry-API aufruft oder YAML generiert).

Standardwerte und Bearbeitungsmodus:

Beim Öffnen eines Formulars zum Erstellen eines neuen Elements können die defaultValues leer sein oder aus einer Vorlage stammen.

Beim Bearbeiten entsprechen die defaultValues in der Regel dem bestehenden Manifest. Die Formularfelder werden mit diesem Objekt vorausgefüllt. Einige Felder sind im Bearbeitungsmodus als unveränderlich markiert (z. B. der Ressourcenname) und werden daher schreibgeschützt angezeigt.

Ausgeblendete Felder werden aus dem Status entfernt:

TrueFoundry-Formulare verwenden shouldUnregister: true. Das bedeutet:

• Wenn ein Feld durch eine Bedingung ausgeblendet wird, wird es aus dem Formularstatus entfernt.
• Sein Wert gelangt nicht in die übermittelte Nutzlast.

Dies ist wichtig für bedingte Formulare: Sie übermitteln nur das, was der Benutzer tatsächlich sehen und bearbeiten konnte.

4. Funktionsweise der Validierung

Die Validierung in TrueFoundry-Formularen erfolgt auf zwei Ebenen.

Ebene 1: Schema-Validierung (deklarativ)

Der validate-Block jedes Feldes kann Folgendes festlegen:

• required
• min / max (zulässiger Bereich eines Ganzzahlwerts)
• minLength / maxLength (Länge von Zeichenfolgen oder Arrays)
• pattern (Regex) mit benutzerdefinierter Meldung
• defaultValue
• immutable (schreibgeschützt im Bearbeitungsmodus)

Diese Regeln werden in Validierungsregeln für react-hook-form umgewandelt. Fehler werden direkt neben dem Feld angezeigt. Die Validierung erfolgt bei jeder Änderung (Modus: 'onChange'), sodass Benutzer während der Eingabe Feedback erhalten und nicht erst beim Absenden.

Ebene 2: Benutzerdefinierte und asynchrone Validierung

Schemata können auch eine benutzerdefinierte validate-Funktion enthalten, die häufig verwendet wird für:

• Eindeutigkeit von Namen („Eine Entität mit diesem Namen existiert bereits“)
• API-gestützte Prüfungen vor dem Absenden
• Feldübergreifende Regeln innerhalb einer benutzerdefinierten Komponente
• Bildschirme binden diese zur Laufzeit mit Hilfsfunktionen wie „Validierung an Feldnamen binden“ ein. Die Benutzeroberfläche zeigt einen Spinner an, während die asynchrone Validierung läuft (z. B. eine entprellte Namensprüfung).

useAttachValidation(schema, {
  name: async (name) => {
    const taken = await checkNameExists(name)
    return taken ? 'Name already exists' : true
  },
})

Zusammengefasst: Was Sie als Benutzer erleben

Wenn Sie „Cluster erstellen“, „Dienst bereitstellen“, „Modell hinzufügen“ oder „Geheimnisse verwalten“ öffnen:

• TrueFoundry lädt (oder erstellt) ein Schema für diese Ressource
• FormBuilder rendert jeden Schemaknoten als die gewünschte Eingabekomponente
• Ihre Änderungen aktualisieren ein einzelnes verschachteltes Formularobjekt
• Die Validierung läuft kontinuierlich und erneut beim Absenden
• Das finale Objekt ist ein Manifest – in derselben Form, die Sie auch in YAML oder über die CLI verwenden würden

Deshalb kann TrueFoundry sehr komplexe Konfigurations-UIs unterstützen, ohne dass jeder Bildschirm ein einmaliges Formular ist: Die Komplexität liegt im Schema und einer Bibliothek von Feldkomponenten, die von einer gemeinsamen Laufzeitumgebung orchestriert werden.