docs: Guides zu Preset-Stapeln, Gruppen-Presets, Überdeckungen, Massenzuweisung und detach

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

docs/guides/divi-shortform.md

@@ -2,9 +2,9 @@
 
 Neue Divi-Inhalte beschreibt man als JSON-Knoten. `lit-divi-insert` (in `nodes`) und `lit-content-create` (in
 `divi`) nehmen dieselbe Form. Jeder Knoten hat einen `type`; dazu Kurzform-Felder, optional `label`
-(Admin-Label), `preset` (Name eines Modul-Presets aus `lit-divi-design-system`) und `attrs` (Vollform, siehe
-`divi-attrs`). Kurz- und Vollform lassen sich kombinieren, aber nicht für denselben Pfad (dann Fehler
-`validation_failed` mit dem Pfad).
+(Admin-Label), `preset` (Name oder Liste von Namen von Modul-Presets aus `lit-divi-design-system`),
+`group_presets` (Gruppen-Presets, siehe „Presets zuweisen“) und `attrs` (Vollform, siehe `divi-attrs`). Kurz- und
+Vollform lassen sich kombinieren, aber nicht für denselben Pfad (dann Fehler `validation_failed` mit dem Pfad).
 
 ## Aufbau
 
@@ -71,13 +71,68 @@ ist dort das Admin-Label). Beim Einfügen über `attrs` (`fieldItem.advanced.typ
 `socialNetwork.innerContent` mit `label`) setzen, danach auch mit `lit-divi-update` über `set`
 (`{"set": {"type": "email"}}`).
 
+## Presets zuweisen
+
+Presets (Namen aus `lit-divi-design-system`, Modul-Presets mit `kind: module`, Gruppen-Presets mit `kind: group`)
+gehen in `lit-divi-insert` (je Knoten in `nodes`), `lit-content-create` (je Knoten in `divi`) und
+`lit-divi-update` (je Eintrag in `changes`) in drei Feldern:
+
+- `preset` – ein Name **oder eine Liste von 1–10 Namen** (Stapel). Der Stapel wird in dieser Reihenfolge
+  gespeichert; bei gleicher Priorität gewinnt das letzte Preset im Stapel (Divi-Verhalten). `null` entfernt das
+  Preset. Eine leere Liste und doppelte Namen sind Fehler (`validation_failed`); wer das Preset entfernen will,
+  sendet `null`.
+- `group_presets` – Objekt `{"<Gruppe>": "<Name>" | ["<Name>", …] | null}`. Die Gruppe nennt man als Kurzname
+  (`font-body`), mit vollem Namen (`divi/font-body`) oder als Attributpfad (`content.decoration.bodyFont`). Hat
+  das Modul mehrere Gruppen mit demselben Namen (z. B. `spacing` für Modul und Button), ist der Kurzname ein
+  Fehler (`validation_failed`), der die Pfade zur Auswahl nennt – dann den Attributpfad als Schlüssel verwenden.
+  Gibt es die Gruppe am Modul nicht oder das Preset in dieser Gruppe nicht, kommt `validation_failed` mit dem
+  Eingabepfad. `null` entfernt den Eintrag dieser Gruppe.
+- `clear_overrides` – `true` oder `false` (nichts anderes), siehe „Überdeckte Werte“.
+
+Gruppen-Presets und Namen kommen immer aus Divi; die Werkzeuge schreiben nie frei erfundene IDs.
+
+Einfügen mit Stapel und Gruppen-Preset:
+
+```json
+{ "type": "button", "text": "Termin buchen", "url": "{{link:42}}",
+  "preset": ["CTA primär", "CTA groß"],
+  "group_presets": { "font": "Button-Schrift" } }
+```
+
+Ändern mit `lit-divi-update` (Stapel ersetzen, Gruppen-Preset einer anderen Gruppe entfernen):
+
+```json
+{ "post_id": 12, "tree_rev": "…",
+  "changes": [ { "id": "s0.r0.c1.m2",
+                 "preset": ["CTA primär"],
+                 "group_presets": { "font": "Button-Schrift", "spacing": null } } ] }
+```
+
+### Überdeckte Werte
+
+Lokale Werte eines Moduls (`attrs`, `set`) haben Vorrang vor den Werten seiner Presets. Weist ein Aufruf
+ausdrücklich Presets zu (oder liegen sie schon am Modul), prüft das Werkzeug Blatt für Blatt (Pfad, Breakpoint,
+Zustand): weicht ein lokaler Wert von dem des Presets ab, steht in `warnings` je Preset eine Zeile wie
+
+> `s0.r0.c1.m2: lokale Werte überdecken „CTA primär“: button.decoration.background – clear_overrides: true entfernt sie.`
+
+Die Zeile nennt bis zu fünf Pfade und „und N weitere“. Das Preset wirkt dort nicht; dem Nutzer sagen und fragen,
+ob die lokalen Werte weg sollen. Dann denselben Knoten mit `"clear_overrides": true` ändern (z. B.
+`{"id": "s0.r0.c1.m2", "preset": "CTA primär", "clear_overrides": true}`): das entfernt genau die lokalen Werte,
+die ein ausdrücklich zugewiesenes Preset überdecken, und sonst nichts. Beim Einfügen wirkt `clear_overrides` nach
+`set` und `attrs` desselben Knotens, entfernt also auch Werte, die der Aufruf selbst gesetzt hat. Standard-Presets
+zählen nicht (Divi wendet sie implizit an, ohne dass der Knoten sie nennt).
+
+Dasselbe Preset auf vielen Seiten oder Modulen setzen: `lit/divi-presets-assign` (siehe `divi-design-system`).
+
 ## Einfügen, ändern, verschieben, löschen
 
 - `lit-divi-insert`: `nodes` + Position – `parent` (Pfad-ID, z. B. Spalte `s0.r0.c1`; optional `index`),
   `before` oder `after`; ohne Position ans Seitenende. Oben auf der Seite sind nur Abschnitte erlaubt, in
   Abschnitten Zeilen, in Spalten Module.
 - `lit-divi-update`: `changes` = `[{"id": "s0.r0.c1.m2", "set": {"text": "Jetzt buchen"}, "preset": "CTA
-  primär", "label": "Hero – Button"}]` – mehrere Knoten in einem Aufruf; `null` entfernt einen Wert. Denselben
+  primär", "label": "Hero – Button"}]` – mehrere Knoten in einem Aufruf; `null` entfernt einen Wert. Neben
+  `preset` nehmen die Einträge `group_presets` und `clear_overrides` (siehe „Presets zuweisen“). Denselben
   Pfad nicht zugleich über `set` und `attrs` ändern (dann zwei Änderungen senden).
 - `lit-divi-move`: `id` + Position (auch in andere Zeilen oder Abschnitte).
 - `lit-divi-delete`: `ids`, erst nach Rückfrage mit `confirm: true`.
@@ -117,5 +172,6 @@ weiterarbeiten).
 ## Warnungen
 
 Neue oder geänderte Knoten werden geprüft: feste Farben/Schriften, obwohl eine passende globale existiert;
-Bilder ohne Alt-Text; leere Module; Sprünge in der Überschriftenhierarchie; Code-Modul. Warnungen dem Nutzer
-nennen und möglichst gleich beheben.
+Bilder ohne Alt-Text; leere Module; Sprünge in der Überschriftenhierarchie; Code-Modul; lokale Werte, die ein
+zugewiesenes Preset überdecken (siehe „Überdeckte Werte“). Warnungen dem Nutzer nennen und möglichst gleich
+beheben.