Add FOR-loop "code" bodies to user-defined functions (kind: 'block')

A custom function body could previously only be a single expression --
no way to iterate over a range's elements to build something like
PRODUCT (multiply every cell together), since none of the built-ins
(SUM/AVG/MIN/MAX/COUNT) do that and a body can only compose existing
functions, not define a new reduction. This adds a second body kind,
'block': a sequence of `name = expression` assignments and
`FOR var IN source DO name = expression` loops, ending in
`RETURN expression`. Flat scope -- every introduced name stays visible
for the rest of the body, including after its own loop, holding its
last iteration's value.

No runtime loop in the evaluator: a loop's source size is already known
once the caller's real argument is substituted in, so
userFunctions.ts's new compileBlock() unrolls every FOR loop into a
single nested expression (a left fold) at the same parse-time inlining
point Phase 1 already used -- the result is exactly the same shape of
static AST as any other inlined function call, so evaluator.ts and
graph.ts need no changes, dependency edges on every unrolled cell are
picked up automatically, and a bounded MAX_UNROLL_STEPS (10,000) keeps
it crash/hang-free. parser.ts's parseFunctionBlock() parses the new
grammar (a purely additive EQUALS lexer token; FOR/IN/DO/RETURN are
plain case-matched IDENTs, not new reserved tokens) into a BlockNode
kept outside the existing Node union, so no existing switch needs a
new case.

Store: CustomFunction/FunctionDef gain `kind: 'expression' | 'block'`
(defaulted for every function saved before this existed, including via
JSON import). validateCustomFunction validates the new grammar's local/
loop-variable names the same way as parameters (not cell-shaped, no
reserved words, no shadowing a parameter -- but reusing the same local
across statements, the accumulator pattern, is correctly not a
collision) and that every FOR source is structurally a parameter, cell,
or range. UI: a "𝑓 Funktionen" form toggle between "Einfache Formel"
and "Mit Schleife", with its own placeholder/hint (a PRODUCT example)
and a small badge on block-kind rows in the list.

237 tests passing (34 new), vue-tsc/eslint/build clean. Verified live
in the running app: defined PRODUCT via the loop UI, called
=PRODUCT(Umsatz!B2:E6), confirmed the correct value and recalculation
on a change to a cell inside the range, and an inline rejection for an
invalid FOR source at save time.

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

src/store/__tests__/document.spec.ts

@@ -815,6 +815,164 @@ describe('custom functions (document-level library)', () => {
   });
 });
 
+describe('custom functions: "block" kind (FOR loops)', () => {
+  const productBody = 'ergebnis = 1 FOR x IN bereich DO ergebnis = ergebnis * x RETURN ergebnis';
+
+  it('adds a block-kind function and a call evaluates through the unrolled loop', () => {
+    const s = fresh();
+    const id = s.addTable(s.doc.activeSheetId);
+    const name = s.tableById(id)!.name;
+    setCell(s, name, 'A1', '2');
+    setCell(s, name, 'A2', '3');
+    setCell(s, name, 'A3', '4');
+
+    const result = s.addCustomFunction('PRODUCT2', ['bereich'], productBody, 'block');
+    expect(typeof result).toBe('string');
+    expect(s.doc.customFunctions[0]).toMatchObject({ name: 'PRODUCT2', kind: 'block' });
+
+    setCell(s, name, 'B1', '=PRODUCT2(A1:A3)');
+    expect(val(s, name, 'B1')).toBe(24);
+  });
+
+  it('recalculates when a cell inside the passed range changes', () => {
+    const s = fresh();
+    const id = s.addTable(s.doc.activeSheetId);
+    const name = s.tableById(id)!.name;
+    setCell(s, name, 'A1', '2');
+    setCell(s, name, 'A2', '3');
+    s.addCustomFunction('PRODUCT2', ['bereich'], productBody, 'block');
+    setCell(s, name, 'B1', '=PRODUCT2(A1:A2)');
+    expect(val(s, name, 'B1')).toBe(6);
+
+    setCell(s, name, 'A1', '10');
+    expect(val(s, name, 'B1')).toBe(30);
+  });
+
+  it('defaults to "expression" when kind is omitted (backward-compatible call signature)', () => {
+    const s = fresh();
+    s.addCustomFunction('MARGE', ['x', 'y'], 'x - y');
+    expect(s.doc.customFunctions[0].kind).toBe('expression');
+  });
+
+  it('rejects a reserved word (FOR/IN/DO/RETURN) as a parameter name', () => {
+    const s = fresh();
+    const result = s.addCustomFunction('F', ['for'], 'for + 1', 'block') as { error: string };
+    expect(result.error).toBeTruthy();
+    expect(s.doc.customFunctions).toHaveLength(0);
+  });
+
+  it('rejects a reserved word as a local/loop variable name', () => {
+    const s = fresh();
+    // "do" parses fine as an ordinary name here (DO the keyword only ever
+    // appears in the one position the FOR grammar expects it) -- this
+    // specifically exercises the dedicated reserved-word name check, not a
+    // parser-level keyword clash.
+    const result = s.addCustomFunction(
+      'F',
+      ['bereich'],
+      'do = 1 FOR x IN bereich DO do = do * x RETURN do',
+      'block',
+    ) as { error: string };
+    expect(result.error).toBeTruthy();
+  });
+
+  it('rejects a local/loop variable name that looks like a cell address', () => {
+    const s = fresh();
+    const result = s.addCustomFunction(
+      'F',
+      ['bereich'],
+      'A1 = 1 FOR x IN bereich DO A1 = A1 * x RETURN A1',
+      'block',
+    ) as { error: string };
+    expect(result.error).toBeTruthy();
+  });
+
+  it('rejects a local name that shadows a parameter', () => {
+    const s = fresh();
+    const result = s.addCustomFunction(
+      'SHADOWTEST',
+      ['bereich'],
+      'bereich = 1 FOR x IN bereich DO bereich = bereich * x RETURN bereich',
+      'block',
+    ) as { error: string };
+    expect(result.error).toBeTruthy();
+  });
+
+  it('re-assigning the same local across statements (the accumulator pattern) is not a collision', () => {
+    const s = fresh();
+    // "ergebnis" is declared once and re-assigned inside the loop -- exactly
+    // productBody's shape -- this must save cleanly, not be flagged as a
+    // duplicate name.
+    const result = s.addCustomFunction('REASSIGNTEST', ['bereich'], productBody, 'block');
+    expect(typeof result).toBe('string');
+  });
+
+  it('rejects a FOR source that is structurally not a parameter, cell, or range', () => {
+    const s = fresh();
+    const result = s.addCustomFunction(
+      'F',
+      ['x'],
+      'total = 0 FOR y IN x + 1 DO total = total + y RETURN total',
+      'block',
+    ) as { error: string };
+    expect(result.error).toBeTruthy();
+  });
+
+  it('rejects malformed code (missing RETURN)', () => {
+    const s = fresh();
+    const result = s.addCustomFunction('F', ['bereich'], 'ergebnis = 1', 'block') as {
+      error: string;
+    };
+    expect(result.error).toBeTruthy();
+  });
+
+  it('a block-kind function can call another custom function inside its loop', () => {
+    const s = fresh();
+    const id = s.addTable(s.doc.activeSheetId);
+    const name = s.tableById(id)!.name;
+    setCell(s, name, 'A1', '2');
+    setCell(s, name, 'A2', '3');
+
+    s.addCustomFunction('DOUBLE', ['n'], 'n * 2');
+    s.addCustomFunction(
+      'SUMDOUBLED',
+      ['bereich'],
+      'total = 0 FOR x IN bereich DO total = total + DOUBLE(x) RETURN total',
+      'block',
+    );
+    setCell(s, name, 'B1', '=SUMDOUBLED(A1:A2)');
+    expect(val(s, name, 'B1')).toBe(2 * 2 + 3 * 2);
+  });
+
+  it('detects a cycle that runs through a block-kind function\'s loop body', () => {
+    const s = fresh();
+    const a = s.addCustomFunction('A', ['bereich'], 'total = 0 FOR x IN bereich DO total = total + B(x) RETURN total', 'block') as string;
+    expect(typeof a).toBe('string');
+    // B calling A closes the cycle A -> B -> A
+    const result = s.addCustomFunction('B', ['x'], 'A(x) + 1') as { error: string };
+    expect(result.error).toBeTruthy();
+    expect(s.doc.customFunctions).toHaveLength(1);
+  });
+
+  it('undo/redo covers a block-kind function change', () => {
+    vi.useFakeTimers();
+    try {
+      const s = fresh();
+      s.addCustomFunction('PRODUCT2', ['bereich'], productBody, 'block');
+      vi.advanceTimersByTime(600);
+      expect(s.doc.customFunctions).toHaveLength(1);
+
+      s.undo();
+      expect(s.doc.customFunctions).toHaveLength(0);
+      s.redo();
+      expect(s.doc.customFunctions[0]).toMatchObject({ name: 'PRODUCT2', kind: 'block' });
+    } finally {
+      vi.runOnlyPendingTimers();
+      vi.useRealTimers();
+    }
+  });
+});
+
 describe('undo / redo', () => {
   // rapid-fire changes (a resize drag, or several store calls in one
   // synchronous action) coalesce into a single undo step -- tests that want
@@ -1243,8 +1401,14 @@ describe('full-fidelity JSON export — backgrounds, formats, sheet settings', (
     s.addToSelection(umsatzId, 2, 2);
     s.addToSelection(umsatzId, 4, 5);
 
-    // a custom function
+    // a custom function -- one of each kind
     s.addCustomFunction('MARGE', ['revenue', 'cost'], '(revenue - cost) / revenue');
+    s.addCustomFunction(
+      'PRODUCT2',
+      ['bereich'],
+      'ergebnis = 1 FOR x IN bereich DO ergebnis = ergebnis * x RETURN ergebnis',
+      'block',
+    );
 
     return { analyse, umsatzId, chartId, txtId };
   }
@@ -1310,13 +1474,15 @@ describe('full-fidelity JSON export — backgrounds, formats, sheet settings', (
     // multi-range selection
     expect(doc.selection.ranges).toHaveLength(2);
 
-    // custom function
-    expect(doc.customFunctions).toHaveLength(1);
+    // custom functions -- one of each kind
+    expect(doc.customFunctions).toHaveLength(2);
     expect(doc.customFunctions[0]).toMatchObject({
       name: 'MARGE',
       params: ['revenue', 'cost'],
       body: '(revenue - cost) / revenue',
+      kind: 'expression',
     });
+    expect(doc.customFunctions[1]).toMatchObject({ name: 'PRODUCT2', kind: 'block' });
   });
 
   it('export -> import is lossless for the fully-loaded document', () => {
@@ -1362,4 +1528,17 @@ describe('v1 -> v2 migration', () => {
     const rep = tableId(store, 'Report');
     expect(store.cellValue(rep, 0, 0)).toBe(7);
   });
+
+  it('an older v2 document\'s customFunctions without a "kind" field default to "expression"', () => {
+    const s = fresh();
+    const before = s.snapshot();
+    const legacy = {
+      ...before,
+      customFunctions: [{ id: 'fn-1', name: 'MARGE', params: ['x', 'y'], body: 'x - y' }], // no "kind"
+    };
+    const parsed = parseDocument(JSON.stringify(legacy));
+    expect(parsed.customFunctions).toEqual([
+      { id: 'fn-1', name: 'MARGE', params: ['x', 'y'], body: 'x - y', kind: 'expression' },
+    ]);
+  });
 });

src/store/document.ts

@@ -26,8 +26,12 @@ import {
   looksLikeCell,
   parseA1,
   parseFormula,
+  parseFunctionBlock,
   hasFunction,
   collectCalledFunctionNames,
+  collectCalledFunctionNamesInBlock,
+  declaredBlockNames,
+  findInvalidForSource,
   type CellValue,
   type TableModel,
   type Token,
@@ -87,7 +91,13 @@ function toTableModels(doc: DocumentState): TableModel[] {
 }
 
 function toFunctionDefs(doc: DocumentState): FunctionDef[] {
-  return doc.customFunctions.map((f) => ({ id: f.id, name: f.name, params: f.params, body: f.body }));
+  return doc.customFunctions.map((f) => ({
+    id: f.id,
+    name: f.name,
+    params: f.params,
+    body: f.body,
+    kind: f.kind,
+  }));
 }
 
 /** A normalised rectangle (corners in either order) used by selection + clipboard. */
@@ -661,9 +671,11 @@ function createStore() {
    *  tolerant of a body that -- in theory -- no longer parses (shouldn't
    *  happen; a save always validates first, but this is only used for a
    *  best-effort cycle check, so fail open rather than block unrelated saves). */
-  function bodyCallSet(params: string[], body: string): Set<string> {
+  function bodyCallSet(f: Pick<CustomFunction, 'params' | 'body' | 'kind'>): Set<string> {
     try {
-      return collectCalledFunctionNames(parseFormula(body, params));
+      return f.kind === 'block'
+        ? collectCalledFunctionNamesInBlock(parseFunctionBlock(f.body, f.params))
+        : collectCalledFunctionNames(parseFormula(f.body, f.params));
     } catch {
       return new Set();
     }
@@ -690,18 +702,29 @@ function createStore() {
     return false;
   }
 
+  /** FOR/IN/DO/RETURN double as block-body keywords (see parser.ts's
+   *  parseFunctionBlock) -- never usable as a parameter/local name, in
+   *  either kind of function (so a name stays valid if the function is
+   *  later switched to "Mit Schleife"). */
+  const RESERVED_NAMES = new Set(['FOR', 'IN', 'DO', 'RETURN']);
+
   /**
    * Full validation for add/update: name & parameter shape, no collision with
-   * a built-in or another custom function, the body parses, and -- simulating
-   * the *whole* call graph with this function's (possibly new) definition in
-   * place -- no cycle. Returns a user-facing (German) error string, or null
-   * when the definition is safe to save. `ignoreId` excludes the function
-   * being edited from the collision/graph checks against its own old state.
+   * a built-in or another custom function, the body parses (as an
+   * expression, or -- for `kind: 'block'` -- as a FOR/DO/RETURN statement
+   * sequence, with every local/loop-variable name validated the same way as
+   * a parameter and every FOR source structurally a parameter/cell/range),
+   * and -- simulating the *whole* call graph with this function's (possibly
+   * new) definition in place -- no cycle. Returns a user-facing (German)
+   * error string, or null when the definition is safe to save. `ignoreId`
+   * excludes the function being edited from the collision/graph checks
+   * against its own old state.
    */
   function validateCustomFunction(
     name: string,
     params: string[],
     body: string,
+    kind: CustomFunction['kind'],
     ignoreId: string | null,
   ): string | null {
     const cleanName = name.trim();
@@ -723,32 +746,77 @@ function createStore() {
     for (const p of cleanParams) {
       if (!IDENT_RE.test(p)) return `"${p}" ist kein gültiger Parametername.`;
       if (looksLikeCell(p)) return `Parameter "${p}" sieht wie ein Zellbezug aus.`;
+      if (RESERVED_NAMES.has(p.toUpperCase())) {
+        return `"${p}" ist ein reserviertes Schlüsselwort (FOR/IN/DO/RETURN) und kann nicht als Parametername verwendet werden.`;
+      }
     }
     if (new Set(cleanParams.map((p) => p.toLowerCase())).size !== cleanParams.length) {
       return 'Parameternamen müssen eindeutig sein.';
     }
 
-    let ast;
-    try {
-      ast = parseFormula(body, cleanParams);
-    } catch (e) {
-      return `Formel ungültig: ${e instanceof Error ? e.message : String(e)}`;
+    let ownCalls: Set<string>;
+    if (kind === 'block') {
+      let block;
+      try {
+        block = parseFunctionBlock(body, cleanParams);
+      } catch (e) {
+        return `Code ungültig: ${e instanceof Error ? e.message : String(e)}`;
+      }
+      // declaredBlockNames() lists every assignment target/loop variable, but
+      // the SAME name legitimately reappears across statements (that's the
+      // whole point of an accumulator: `ergebnis = 1`, then later `FOR x IN
+      // bereich DO ergebnis = ergebnis * x` re-assigns "ergebnis", it doesn't
+      // declare a second one) -- so shape/reserved-word checks run on every
+      // occurrence (harmless to repeat), but the "no collision" check only
+      // looks at each *distinct* local name against the parameters, never
+      // against other locals (re-using a local's own name is exactly the
+      // point; two locals can even share a name across two separate loops).
+      const localNames = declaredBlockNames(block);
+      for (const n of localNames) {
+        if (!IDENT_RE.test(n)) return `"${n}" ist kein gültiger Name.`;
+        if (looksLikeCell(n)) return `"${n}" sieht wie ein Zellbezug aus und ist als Name nicht erlaubt.`;
+        if (RESERVED_NAMES.has(n.toUpperCase())) {
+          return `"${n}" ist ein reserviertes Schlüsselwort (FOR/IN/DO/RETURN) und kann nicht als Name verwendet werden.`;
+        }
+      }
+      const paramSet = new Set(cleanParams.map((p) => p.toLowerCase()));
+      for (const n of new Set(localNames.map((x) => x.toLowerCase()))) {
+        if (paramSet.has(n)) return `"${n}" ist bereits ein Parametername.`;
+      }
+      const badFor = findInvalidForSource(block);
+      if (badFor) {
+        return `FOR ${badFor.varName} IN ...: die Quelle muss ein Parameter, eine Zelle oder ein Bereich sein, kein berechneter Ausdruck.`;
+      }
+      ownCalls = collectCalledFunctionNamesInBlock(block);
+    } else {
+      let ast;
+      try {
+        ast = parseFormula(body, cleanParams);
+      } catch (e) {
+        return `Formel ungültig: ${e instanceof Error ? e.message : String(e)}`;
+      }
+      ownCalls = collectCalledFunctionNames(ast);
     }
 
     const graph = new Map<string, Set<string>>();
     for (const f of doc.customFunctions) {
       if (f.id === ignoreId) continue;
-      graph.set(f.name.toUpperCase(), bodyCallSet(f.params, f.body));
+      graph.set(f.name.toUpperCase(), bodyCallSet(f));
     }
-    graph.set(cleanName.toUpperCase(), collectCalledFunctionNames(ast));
+    graph.set(cleanName.toUpperCase(), ownCalls);
     if (callGraphHasCycle(graph)) {
       return `"${cleanName}" führt (direkt oder über andere Funktionen) zu einem Zyklus.`;
     }
     return null;
   }
 
-  function addCustomFunction(name: string, params: string[], body: string): string | { error: string } {
-    const error = validateCustomFunction(name, params, body, null);
+  function addCustomFunction(
+    name: string,
+    params: string[],
+    body: string,
+    kind: CustomFunction['kind'] = 'expression',
+  ): string | { error: string } {
+    const error = validateCustomFunction(name, params, body, kind, null);
     if (error) return { error };
     const id = uid('fn');
     const custom: CustomFunction = {
@@ -756,6 +824,7 @@ function createStore() {
       name: name.trim(),
       params: params.map((p) => p.trim()),
       body: body.startsWith('=') ? body.slice(1) : body,
+      kind,
     };
     doc.customFunctions.push(custom);
     syncWorkbook();
@@ -767,14 +836,16 @@ function createStore() {
     name: string,
     params: string[],
     body: string,
+    kind: CustomFunction['kind'] = 'expression',
   ): void | { error: string } {
     const f = doc.customFunctions.find((x) => x.id === id);
     if (!f) return { error: 'Funktion nicht gefunden.' };
-    const error = validateCustomFunction(name, params, body, id);
+    const error = validateCustomFunction(name, params, body, kind, id);
     if (error) return { error };
     f.name = name.trim();
     f.params = params.map((p) => p.trim());
     f.body = body.startsWith('=') ? body.slice(1) : body;
+    f.kind = kind;
     syncWorkbook();
   }
 

src/store/types.ts

@@ -159,8 +159,14 @@ export interface CustomFunction {
   name: string;
   /** parameter names, in call order; may be empty (a plain named formula). */
   params: string[];
-  /** raw formula text, no leading "=". */
+  /** raw formula text, no leading "=" -- a single expression for
+   *  `kind: 'expression'`, a FOR/DO/RETURN statement sequence for
+   *  `kind: 'block'`. */
   body: string;
+  /** 'expression' (default, single-formula body) or 'block' (FOR-loop
+   *  capable, "Mit Schleife" in the UI). Missing on any function saved
+   *  before this existed -- normalised to 'expression' on load. */
+  kind: 'expression' | 'block';
 }
 
 export interface DocumentState {