kochwas/docs/superpowers/plans/2026-04-19-ingredient-sections.md

Ingredient Sections Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Zutaten können im Editor in benannte Sektionen (z. B. „Für den Teig", „Für die Füllung") gruppiert werden; in der View werden die Sektionen als Überschriften über den zugehörigen Zutatenblöcken gerendert.

Architecture: Eine neue nullable Spalte section_heading auf ingredient. Ist sie gesetzt, startet an dieser Zeile eine neue Sektion — alle folgenden Zutaten gehören dazu bis zur nächsten Zeile mit gesetzter section_heading. Ordnung bleibt position. Keine neue Tabelle, keine zweite Ordnungsachse, Scaler/FTS/Importer bleiben unverändert im Verhalten (nur Type-Passthrough). Inline-Button „Abschnitt hinzufügen" erscheint im Editor vor jeder Zutatenzeile und am Listenende.

Tech Stack: better-sqlite3 Migration, TypeScript-strict, Svelte 5 runes, vitest.

Scope-Entscheidungen (vom User bestätigt):

• Sektionen nur für Zutaten, nicht für Zubereitungsschritte.
• „Abschnitt hinzufügen"-Button inline vor jeder Zeile (plus einer am Listenende).
• Keine Import-Extraction — JSON-LD hat keine Sektionen, Emmikochteinfach rendert sie nur im HTML. Später via HTML-Parse möglich, aber out-of-scope.

---

Task 1: Migration + Type-Erweiterung + parseIngredient-Sites

Files:

• Create: src/lib/server/db/migrations/012_ingredient_section.sql
• Modify: src/lib/types.ts (Ingredient type)
• Modify: src/lib/server/parsers/ingredient.ts (3 return sites)
• Test: tests/unit/ingredient.test.ts (bereits existierend, muss grün bleiben)

Warum zusammen: Nach der Type-Änderung schlägt svelte-check überall fehl, wo ein Ingredient-Literal gebaut wird. parseIngredient hat 3 solcher Stellen und ist vom selben Commit abhängig, sonst wird der Build rot.

• Step 1: Migration schreiben

Create src/lib/server/db/migrations/012_ingredient_section.sql:

-- Nullable — alte Zeilen behalten NULL, neue dürfen eine Überschrift haben.
-- Rendering-Regel: Ist section_heading gesetzt (nicht NULL und nicht leer),
-- startet an dieser Zeile eine neue Sektion mit diesem Titel.
ALTER TABLE ingredient ADD COLUMN section_heading TEXT;

• Step 2: Ingredient-Type erweitern

Modify src/lib/types.ts:

export type Ingredient = {
  position: number;
  quantity: number | null;
  unit: string | null;
  name: string;
  note: string | null;
  raw_text: string;
  section_heading: string | null;
};

• Step 3: parseIngredient-Return-Sites aktualisieren

Modify src/lib/server/parsers/ingredient.ts: Alle drei return { position, ... raw_text: rawText };-Literale (Zeilen 108, 115, 119) bekommen section_heading: null am Ende. Beispiel für Zeile 108:

return { position, quantity, unit, name, note, raw_text: rawText, section_heading: null };

Analog für Zeilen 115 und 119.

• Step 4: Bestehende Unit-Tests grün

Run: npm run test -- ingredient.test.ts Expected: PASS (Tests prüfen nur vorhandene Felder, neues Feld stört nicht).

• Step 5: Svelte-Check muss noch rot sein

Run: npm run check Expected: FAIL mit Fehlern in repository.ts (Select-Statement ohne section_heading). Das ist erwartet — wird in Task 2 behoben. Nicht hier fixen.

• Step 6: Commit

git add src/lib/types.ts src/lib/server/db/migrations/012_ingredient_section.sql src/lib/server/parsers/ingredient.ts
git commit -m "feat(schema): ingredient.section_heading (Migration 012 + Type)"

---

Task 2: Repository-Layer Persistenz

Files:

• Modify: src/lib/server/recipes/repository.ts (insertRecipe, replaceIngredients, getRecipeById)
• Test: tests/integration/recipe-repository.test.ts

Warum jetzt: Nach Task 1 ist der Type-Vertrag aufgemacht. Die DB muss das Feld lesen und schreiben, sonst gehen Sektionen beim Save/Load verloren.

• Step 1: Failing test für Roundtrip

Add to tests/integration/recipe-repository.test.ts inside describe('recipe repository', ...):

it('persistiert section_heading und gibt es beim Laden zurück', () => {
  const db = openInMemoryForTest();
  const recipe = baseRecipe({
    title: 'Torte',
    ingredients: [
      { position: 1, quantity: 200, unit: 'g', name: 'Mehl', note: null, raw_text: '200 g Mehl', section_heading: 'Für den Teig' },
      { position: 2, quantity: 100, unit: 'g', name: 'Zucker', note: null, raw_text: '100 g Zucker', section_heading: null },
      { position: 3, quantity: 300, unit: 'g', name: 'Beeren', note: null, raw_text: '300 g Beeren', section_heading: 'Für die Füllung' }
    ]
  });
  const id = insertRecipe(db, recipe);
  const loaded = getRecipeById(db, id);
  expect(loaded!.ingredients[0].section_heading).toBe('Für den Teig');
  expect(loaded!.ingredients[1].section_heading).toBeNull();
  expect(loaded!.ingredients[2].section_heading).toBe('Für die Füllung');
});

it('replaceIngredients persistiert section_heading', () => {
  const db = openInMemoryForTest();
  const id = insertRecipe(db, baseRecipe({ title: 'X' }));
  replaceIngredients(db, id, [
    { position: 1, quantity: null, unit: null, name: 'A', note: null, raw_text: 'A', section_heading: 'Kopf' }
  ]);
  const loaded = getRecipeById(db, id);
  expect(loaded!.ingredients[0].section_heading).toBe('Kopf');
});

• Step 2: Test laufen — muss fehlschlagen

Run: npm run test -- recipe-repository.test.ts Expected: FAIL — section_heading kommt als undefined zurück, weil SQL-SELECT es nicht holt.

• Step 3: INSERT-Statements erweitern

Modify src/lib/server/recipes/repository.ts:

In insertRecipe (line ~66): Spalte + Parameter anhängen.

const insIng = db.prepare(
  `INSERT INTO ingredient(recipe_id, position, quantity, unit, name, note, raw_text, section_heading)
   VALUES (?, ?, ?, ?, ?, ?, ?, ?)`
);
for (const ing of recipe.ingredients) {
  insIng.run(id, ing.position, ing.quantity, ing.unit, ing.name, ing.note, ing.raw_text, ing.section_heading);
}

In replaceIngredients (line ~217): gleiche Änderung.

const ins = db.prepare(
  `INSERT INTO ingredient(recipe_id, position, quantity, unit, name, note, raw_text, section_heading)
   VALUES (?, ?, ?, ?, ?, ?, ?, ?)`
);
for (const ing of ingredients) {
  ins.run(recipeId, ing.position, ing.quantity, ing.unit, ing.name, ing.note, ing.raw_text, ing.section_heading);
}

• Step 4: SELECT-Statement erweitern

In getRecipeById (line ~105):

const ingredients = db
  .prepare(
    `SELECT position, quantity, unit, name, note, raw_text, section_heading
       FROM ingredient WHERE recipe_id = ? ORDER BY position`
  )
  .all(id) as Ingredient[];

• Step 5: Tests grün

Run: npm run test -- recipe-repository.test.ts Expected: PASS.

• Step 6: Volle Suite + svelte-check

Run: npm test && npm run check Expected: Beides PASS. svelte-check ist jetzt auf Repo-Ebene typ-clean; View/Editor noch nicht berührt, deren Nutzung von Ingredient bleibt (Feld darf fehlen, weil der Type optional wirkt? — Nein, es ist string | null, also pflicht. Falls check rot wird, liegt es an Importer/Scaler-Aufrufern, die Ingredient-Literale bauen. Das ist dann Task 3.)

• Step 7: Commit

git add src/lib/server/recipes/repository.ts tests/integration/recipe-repository.test.ts
git commit -m "feat(db): section_heading roundtrip in recipe-repository"

---

Task 3: Importer-Passthrough + Scaler-Test

Files:

• Modify: src/lib/recipes/scaler.ts (nur falls Test rot — siehe unten)
• Test: tests/unit/scaler.test.ts
• Test: evtl. tests/integration/importer.test.ts

Warum: parseIngredient setzt section_heading: null (Task 1). Das reicht für den Importer — keine JSON-LD-Extraction. Aber der Scaler ruft .map((i) => ({ ...i, quantity: ... })) auf; das Spread erhält section_heading automatisch. Wir fügen nur einen Regressions-Test hinzu, dass das stimmt.

• Step 1: Scaler-Regressions-Test

Add to tests/unit/scaler.test.ts:

it('preserves section_heading through scaling', () => {
  const input: Ingredient[] = [
    { position: 1, quantity: 200, unit: 'g', name: 'Mehl', note: null, raw_text: '200 g Mehl', section_heading: 'Teig' },
    { position: 2, quantity: null, unit: null, name: 'Ei', note: null, raw_text: 'Ei', section_heading: null }
  ];
  const scaled = scaleIngredients(input, 2);
  expect(scaled[0].section_heading).toBe('Teig');
  expect(scaled[1].section_heading).toBeNull();
  expect(scaled[0].quantity).toBe(400);
});

• Step 2: Test laufen

Run: npm run test -- scaler.test.ts Expected: PASS (weil ...i das Feld durchreicht).

Falls FAIL: In src/lib/recipes/scaler.ts das .map prüfen — es sollte ...i spreaden und nur quantity überschreiben. Bei Abweichung angleichen.

• Step 3: Importer-Roundtrip-Test (Bolognese-Fixture)

Prüfen, dass Importer für Emmi-Fixture section_heading: null auf allen Zutaten liefert. Der existierende importer.test.ts sollte automatisch grün bleiben (parseIngredient setzt das Feld auf null), aber wir schauen kurz nach:

Run: npm run test -- importer.test.ts Expected: PASS.

• Step 4: Commit

git add tests/unit/scaler.test.ts
git commit -m "test(scaler): section_heading ueberlebt Skalierung"

---

Task 4: IngredientRow — Heading-Anzeige + Inline Insert-Button

Files:

• Modify: src/lib/components/recipe-editor-types.ts
• Modify: src/lib/components/IngredientRow.svelte
• Test: neue Svelte-Component-Tests via vitest-browser — ausgenommen: wir haben keine Svelte-Component-Unit-Tests im Repo. Stattdessen decken E2E + manuelle Verifikation ab. Das ist konsistent mit der bestehenden Praxis.

Verhalten:

• DraftIng bekommt section_heading: string | null (immer gesetzt, aber nullable).

• Hat eine Zeile section_heading als String (auch leer), wird oberhalb der Row ein <input> für den Titel gerendert plus ein kleiner „Sektion entfernen"-Button.

• Hat eine Zeile section_heading === null, wird ein dezenter <button class="add-section">Abschnitt hinzufügen</button> über der Row gerendert.

• IngredientRow bekommt Callbacks onaddSection, onremoveSection — Parent verwaltet das Array.

• Step 1: DraftIng-Typ erweitern

Modify src/lib/components/recipe-editor-types.ts:

export type DraftIng = {
  qty: string;
  unit: string;
  name: string;
  note: string;
  section_heading: string | null;
};
export type DraftStep = { text: string };

• Step 2: IngredientRow erweitern — Props

Modify src/lib/components/IngredientRow.svelte Script-Block:

<script lang="ts">
  import { Trash2, ChevronUp, ChevronDown, Plus, X } from 'lucide-svelte';
  import type { DraftIng } from './recipe-editor-types';

  type Props = {
    ing: DraftIng;
    idx: number;
    total: number;
    onmove: (dir: -1 | 1) => void;
    onremove: () => void;
    onaddSection: () => void;
    onremoveSection: () => void;
  };

  let { ing, idx, total, onmove, onremove, onaddSection, onremoveSection }: Props = $props();
</script>

• Step 3: IngredientRow-Template — Section-Block + Add-Button

Replace the existing <li class="ing-row">…</li> with:

{#if ing.section_heading === null}
  <li class="section-insert">
    <button type="button" class="add-section" onclick={onaddSection}>
      <Plus size={12} strokeWidth={2.5} />
      <span>Abschnitt hinzufügen</span>
    </button>
  </li>
{:else}
  <li class="section-heading-row">
    <input
      class="section-heading"
      type="text"
      bind:value={ing.section_heading}
      placeholder="Sektion, z. B. „Für den Teig""
      aria-label="Sektionsüberschrift"
    />
    <button
      type="button"
      class="section-remove"
      aria-label="Sektion entfernen"
      onclick={onremoveSection}
    >
      <X size={14} strokeWidth={2.5} />
    </button>
  </li>
{/if}
<li class="ing-row">
  <div class="move">
    <!-- unchanged -->
    <button class="move-btn" type="button" aria-label="Zutat nach oben" disabled={idx === 0} onclick={() => onmove(-1)}>
      <ChevronUp size={14} strokeWidth={2.5} />
    </button>
    <button class="move-btn" type="button" aria-label="Zutat nach unten" disabled={idx === total - 1} onclick={() => onmove(1)}>
      <ChevronDown size={14} strokeWidth={2.5} />
    </button>
  </div>
  <input class="qty" type="text" bind:value={ing.qty} placeholder="Menge" aria-label="Menge" />
  <input class="unit" type="text" bind:value={ing.unit} placeholder="Einheit" aria-label="Einheit" />
  <input class="name" type="text" bind:value={ing.name} placeholder="Zutat" aria-label="Zutat" />
  <input class="note" type="text" bind:value={ing.note} placeholder="Notiz" aria-label="Notiz" />
  <button class="del" type="button" aria-label="Zutat entfernen" onclick={onremove}>
    <Trash2 size={16} strokeWidth={2} />
  </button>
</li>

Hinweis: Wir rendern pro Row zwei <li>: optional einen Sektions-Block (Insert-Button ODER Heading-Input), plus die bestehende Zutaten-Row. Das passt in die <ul class="ing-list"> des Parents — semantisch unsauber (nicht-Zutat-<li> in Zutatenliste), aber praktikabel; alternativ könnte IngredientRow auf <div> umgestellt werden, das wäre aber ein Parent-Umbau. Wir bleiben bei <li> und geben dem Section-<li> list-style: none via CSS.

• Step 4: Styles für Section-UI

Add to <style>-Block in IngredientRow.svelte:

.section-insert {
  display: flex;
  justify-content: center;
  list-style: none;
  margin: -0.2rem 0 0.1rem;
  opacity: 0;
  transition: opacity 0.15s;
}
.ing-list:hover .section-insert,
.section-insert:focus-within {
  opacity: 1;
}
.add-section {
  display: inline-flex;
  align-items: center;
  gap: 0.25rem;
  padding: 0.2rem 0.55rem;
  border: 1px dashed #cfd9d1;
  background: white;
  color: #2b6a3d;
  border-radius: 999px;
  cursor: pointer;
  font-size: 0.75rem;
  font-family: inherit;
}
.add-section:hover {
  background: #f4f8f5;
}
.section-heading-row {
  display: grid;
  grid-template-columns: 1fr 32px;
  gap: 0.35rem;
  list-style: none;
  margin-top: 0.4rem;
}
.section-heading {
  padding: 0.45rem 0.7rem;
  border: 1px solid #cfd9d1;
  border-radius: 8px;
  font-size: 0.95rem;
  font-weight: 600;
  color: #2b6a3d;
  font-family: inherit;
  background: #f4f8f5;
}
.section-remove {
  width: 32px;
  height: 38px;
  border: 1px solid #cfd9d1;
  background: white;
  border-radius: 8px;
  color: #666;
  cursor: pointer;
  display: inline-flex;
  align-items: center;
  justify-content: center;
}
.section-remove:hover {
  background: #fdf3f3;
  border-color: #f1b4b4;
  color: #c53030;
}

Begründung opacity: 0 + Hover: Der Insert-Button erscheint vor jeder Zeile — das ist visuelles Rauschen auf statischem Zustand. Fade-in-on-hover hält die Zutatenliste lesbar und macht den Button auf Mouse-Interaktion trotzdem sichtbar. Auf Touch-Geräten ist :hover ggf. sticky — das ist OK, weil auf Mobile die Zutatenliste ohnehin explorativ bedient wird. :focus-within deckt Keyboard-Navigation ab.

• Step 5: svelte-check

Run: npm run check Expected: FAIL — RecipeEditor.svelte gibt die neuen Callbacks onaddSection / onremoveSection noch nicht rein, und DraftIng-Literale im Editor haben noch kein section_heading. Wird in Task 5 behoben.

• Step 6: Commit

git add src/lib/components/IngredientRow.svelte src/lib/components/recipe-editor-types.ts
git commit -m "feat(editor): Sektionsueberschriften in IngredientRow + Insert-Button"

---

Task 5: RecipeEditor — State, Handler, Save-Patch

Files:

• Modify: src/lib/components/RecipeEditor.svelte

• Step 1: DraftIng-Seeding erweitern

In RecipeEditor.svelte Script-Block, ingredients-State (line ~40):

let ingredients = $state<DraftIng[]>(
  untrack(() =>
    recipe.ingredients.map((i) => ({
      qty: i.quantity !== null ? String(i.quantity).replace('.', ',') : '',
      unit: i.unit ?? '',
      name: i.name,
      note: i.note ?? '',
      section_heading: i.section_heading
    }))
  )
);

• Step 2: addIngredient aktualisieren

function addIngredient() {
  ingredients = [...ingredients, { qty: '', unit: '', name: '', note: '', section_heading: null }];
}

• Step 3: Section-Handler einfügen

function addSection(idx: number) {
  const next = [...ingredients];
  next[idx] = { ...next[idx], section_heading: '' };
  ingredients = next;
}
function removeSection(idx: number) {
  const next = [...ingredients];
  next[idx] = { ...next[idx], section_heading: null };
  ingredients = next;
}

• Step 4: save()-Patch erweitern

In save() (line ~86), das cleanedIngredients-Mapping:

const cleanedIngredients: Ingredient[] = ingredients
  .filter((i) => i.name.trim())
  .map((i, idx) => {
    const qty = parseQty(i.qty);
    const unit = i.unit.trim() || null;
    const name = i.name.trim();
    const note = i.note.trim() || null;
    const rawParts: string[] = [];
    if (qty !== null) rawParts.push(String(qty).replace('.', ','));
    if (unit) rawParts.push(unit);
    rawParts.push(name);
    const heading = i.section_heading === null ? null : (i.section_heading.trim() || null);
    return {
      position: idx + 1,
      quantity: qty,
      unit,
      name,
      note,
      raw_text: rawParts.join(' '),
      section_heading: heading
    };
  });

Regel: Eine leere Sektion (section_heading === '' nach Trim) wird beim Speichern zu null. Begründung: User tippt „Abschnitt hinzufügen" und lässt das Feld leer → keine unbenannte Sektion in der View. Nur Zeilen mit echtem Titel werden als Sektionsanker persistiert.

• Step 5: IngredientRow-Callbacks verdrahten

In RecipeEditor.svelte Template (line ~170):

{#each ingredients as ing, idx (idx)}
  <IngredientRow
    {ing}
    {idx}
    total={ingredients.length}
    onmove={(dir) => moveIngredient(idx, dir)}
    onremove={() => removeIngredient(idx)}
    onaddSection={() => addSection(idx)}
    onremoveSection={() => removeSection(idx)}
  />
{/each}

• Step 6: svelte-check + Tests

Run: npm run check && npm test Expected: Beides grün.

• Step 7: Commit

git add src/lib/components/RecipeEditor.svelte
git commit -m "feat(editor): Sektionen-Handler + save-Patch mit section_heading"

---

Task 6: RecipeView — Sektions-Überschriften rendern

Files:

• Modify: src/lib/components/RecipeView.svelte

• Step 1: Zutatenliste umbauen

In RecipeView.svelte (line ~128), den <ul class="ing-list">-Block:

<ul class="ing-list">
  {#each scaled as ing, i (i)}
    {#if ing.section_heading && ing.section_heading.trim()}
      <li class="section-heading">{ing.section_heading}</li>
    {/if}
    <li>
      {#if ing.quantity !== null || ing.unit}
        <span class="qty">
          {formatQty(ing.quantity)}
          {#if ing.unit}
            {' '}{ing.unit}
          {/if}
        </span>
      {/if}
      <span class="name">
        {ing.name}
        {#if ing.note}<span class="note"> ({ing.note})</span>{/if}
      </span>
    </li>
  {/each}
</ul>

Hinweis: <li class="section-heading"> statt <h3> — wir sind in einer <ul> und dürfen dort nur <li> direkt verschachteln. Semantisch ist das OK, Screenreader lesen die Heading-Klasse nicht als Landmark, aber sie liest den Text als normales Listen-Item; für ein Rezept ist das akzeptabel. Alternativ: <ul> in mehrere <section>s aufsplitten — deutlich komplexer bei gleicher visueller Wirkung; verschoben, bis jemand klagt.

• Step 2: Style für .section-heading

Add to <style>-Block in RecipeView.svelte:

.ing-list .section-heading {
  list-style: none;
  font-weight: 600;
  color: #2b6a3d;
  font-size: 1rem;
  margin-top: 0.9rem;
  margin-bottom: 0.2rem;
  padding: 0.15rem 0;
  border-bottom: 1px solid #e4eae7;
}
.ing-list .section-heading:first-child {
  margin-top: 0;
}

• Step 3: Tests + Check

Run: npm run check && npm test Expected: Beides grün.

• Step 4: Dev-Build-Smoke-Test

Run: npm run build && npm run preview Manuell: Rezept öffnen, editieren, Sektion „Teig" auf Zeile 1 setzen und „Füllung" auf Zeile 3, speichern. Wechsel zu View → beide Überschriften sichtbar, Skalierung ändert nur Mengen. Screenshot ist nice-to-have, nicht Pflicht.

• Step 5: Commit

git add src/lib/components/RecipeView.svelte
git commit -m "feat(view): Zutaten-Sektionen als Ueberschriften rendern"

---

Task 7: Ship

• Step 1: Finale Testsuite

Run: npm run check && npm test Expected: Beides grün.

• Step 2: Push

git push -u origin feature/ingredient-sections

• Step 3: Auf Deploy warten (CI-Image-Build, Pi-Pull)

User wird manuell signalisieren, wenn deployed.

• Step 4: Nach Deploy — Playwright Remote-Smoke

Run: npm run test:e2e:remote Expected: 42/42 green (unchanged suite, wir haben keine Recipe-Edit-E2E-Tests hinzugefügt).

• Step 5: Merge zu main

Falls E2E grün:

git checkout main
git merge --no-ff feature/ingredient-sections -m "Merge ingredient-sections — Zutaten-Gruppierung via section_heading"
git push

---

Self-Review-Notiz

• Spec-Coverage: alle drei User-Anforderungen abgedeckt (Inline-Button vor jeder Zeile → Task 4, nur Zutaten → keine Step-Änderungen, Edit-Mode-only → Importer unverändert).
• Type-Konsistenz: section_heading: string | null überall einheitlich (Ingredient, DraftIng, Save-Patch).
• Keine Placeholder — alle SQL-/Code-Snippets ausgeschrieben.
• Migrations-Reihenfolge: 012_ nach 011_clear_favicon_for_rerun.sql.
• FTS-Impact: section_heading taucht nicht im FTS-Trigger auf (001_init.sql nutzt name, description, ingredients_concat, tags_concat). Das ist bewusst so — Sektionstitel sind Organisationshilfen, kein Suchinhalt. User suchen nach „Mehl", nicht nach „Für den Teig".