Funktions-Autovervollständigung in der Formelbearbeitung

Beim Tippen eines Funktionsnamens (nach "=", einem Operator, "(" oder
";" -- nicht bei einem Zellbezug wie A1) zeigt sowohl die Formelleiste
als auch der In-Zellen-Editor jetzt ein Dropdown mit passenden
eingebauten UND eigenen Funktionen samt Kurzsignatur. ↑/↓ navigieren,
Tab/Enter/Klick übernehmen (fügt "NAME(" ein), Esc schließt nur das
Dropdown, ohne die Bearbeitung abzubrechen.

- engine/refs.ts: neue reine Funktion currentIdentifierAtCaret() --
  strukturell wie das schon vorhandene cycleReferenceLocks (=
  abstreifen, tokenize, am Cursor nachsehen), aber nur der Text bis
  zum Cursor wird tokenisiert und nur das letzte Token zählt; ein
  IDENT, das bis an den Cursor reicht und nicht wie ein Zellbezug
  aussieht, ist der Funktionsname. tokenize() hängt ein EOF-Token an
  -- muss beim Suchen des "letzten Tokens" herausgefiltert werden
  (von den eigenen Tests aufgedeckt).
- engine/functions.ts: BUILTIN_SIGNATURES (Name -> Kurzsignatur je
  eingebauter Funktion), gegen FUNCTIONS' Keys testabgesichert, damit
  eine künftige neue Funktion ohne Eintrag hier nicht still im
  Dropdown fehlt.
- store/document.ts: functionSuggestions(prefix) kombiniert eingebaute
  + dokumenteigene Funktionen, case-insensitiv gefiltert, sortiert.
- composables/useFormulaAutocomplete.ts: pro Editor-Instanz eigener
  State (suggestions/activeIndex), orchestriert die drei Bausteine
  oben; die Übernahme eines Vorschlags läuft über dieselbe
  replace(start,end,value)-Mechanik, die Point-Mode für den Bezug-
  Einfügeklick schon nutzt -- keine neue Einfüge-Infrastruktur nötig.
- components/FormulaSuggest.vue: geteiltes, rein präsentationelles
  Dropdown (position:absolute; top:100% relativ zum Editor-Wrapper,
  kein Caret-Pixel-Tracking).
- FormulaBar.vue + TableGrid.vue: gleiches Einbindungsmuster in
  beiden Editoren (Wrapper bekommt position:relative, onInput ruft
  autocomplete.update(), onKeydown fängt Pfeiltasten/Tab/Enter/Esc
  vor der bestehenden Logik ab, wenn Vorschläge offen sind, onBlur
  schließt das Dropdown).

Tests: 13 neue (refs.spec.ts: 7 Fälle für currentIdentifierAtCaret;
functions.spec.ts neu: Signatur-Tabelle deckungsgleich mit FUNCTIONS;
document.spec.ts: functionSuggestions Filter/Mischung/Sortierung).
318 -> 331 Tests, alle grün. vue-tsc/eslint/build sauber. Live per
Playwright verifiziert in Formelleiste UND In-Zellen-Editor: Filterung,
Pfeiltasten-Navigation, Tab-Übernahme, Maus-Klick-Übernahme, Esc
schließt nur das Dropdown, eigene Funktion (MARGE) erscheint neben
eingebauten (MAX) korrekt einsortiert.

READMEs aktualisiert (neuer Abschnitt "Funktions-Autovervollständigung",
Tastaturtabelle, Testliste, Bekannte Grenzen -- dabei eine veraltete
Aussage korrigiert, die Autovervollständigung für benutzerdefinierte
Funktionen noch als "bewusst fehlend" auflistete).

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

src/engine/README.md

@@ -18,7 +18,7 @@ genau die genannte Tabelle. Siehe "Blatt-Qualifier" weiter unten.
 | `parser.ts`    | Recursive-Descent → AST. Grammatik als EBNF-Kommentarblock im Kopf der Datei. |
 | `evaluator.ts` | AST + `EngineHost` → `CellValue`. Numerisches Auswertungsmodell, Fehler-Propagierung. Enthält auch den kleinen Interpreter für `kind: 'block'`-Funktionsaufrufe (`BlockCallNode`) – siehe „Schleifen" unten. |
 | `graph.ts`     | Dokumentweiter Abhängigkeitsgraph: `affected()`, `topoOrder()`, Zirkel-Erkennung (iterative DFS, white/grey/black). |
-| `refs.ts`      | A1 ↔ `(col,row)` inkl. `$`-Sperrachsen, Spaltenbuchstaben, Bereichs-Expansion, `F4`-Zyklus (`cycleReferenceLocks`). |
+| `refs.ts`      | A1 ↔ `(col,row)` inkl. `$`-Sperrachsen, Spaltenbuchstaben, Bereichs-Expansion, `F4`-Zyklus (`cycleReferenceLocks`), Funktionsnamen-Erkennung fürs Autovervollständigen (`currentIdentifierAtCaret`). |
 | `functions.ts` | `SUM/AVG/MIN/MAX/COUNT` (+ Alias `AVERAGE`), `DATE/TIME/TODAY/NOW` als Tabelle `{ NAME → fn(values) }`. `IF` und `XLOOKUP` sind hier nur als Platzhalter registriert (für `hasFunction()`/Namensreservierung); die echte Auswertung sitzt in `evaluator.ts`, s. u. Eingebaute Namen sind nie überschreibbar. |
 | `dates.ts`     | Datum/Zeit als Zahl ("Serial", Tage seit 1899-12-30): `dateToSerial`/`timeSerial` (Bausteine für `DATE`/`TIME`), `todaySerial`/`nowSerial`, `serialToUtcDate` (für die Anzeige), `parseDateTimeLiteral` (Eingabe-Erkennung, s. u. „Datum & Zeit"). |
 | `userFunctions.ts` | Benutzerdefinierte Funktionen (dokumentweite Bibliothek, angelegt über die UI — siehe Haupt-`README.md`). `expandUserFunctions()` setzt einen `kind: 'expression'`-Aufruf beim Parsen der aufrufenden Zelle als Kopie des rekursiv expandierten, parametersubstituierten Funktionskörpers in deren AST ein; einen `kind: 'block'`-Aufruf (FOR/IF/RETURN-Code) verpackt sie stattdessen in einen `BlockCallNode` mit bereits aufgelösten verschachtelten Aufrufen, siehe „Schleifen" unten. |
@@ -95,6 +95,18 @@ darin gefundenen Bezug auf einmal, jeden ausgehend vom eigenen Zustand.
 Tabellennamen werden **case-insensitiv** und whitespace-tolerant aufgelöst:
 `Kosten!A2`, `'Kosten'!A2`, `kosten!a2`, `Kosten::A2` sind identisch.
 
+`refs.ts#currentIdentifierAtCaret(formula, caret)` treibt die Funktions-
+Autovervollständigung (Formelleiste und Zell-Editor, `src/composables/
+useFormulaAutocomplete.ts`): strukturell dasselbe Muster wie
+`cycleReferenceLocks` (`=` abstreifen, tokenizen, am Cursor nachsehen), aber
+nur der Text **bis** zum Cursor wird überhaupt tokenisiert (was danach
+kommt, spielt nie eine Rolle — wie bei den meisten Editoren), und nur das
+*letzte* Token zählt. Ein `IDENT`-Token, das bis genau an den Cursor reicht
+und nicht wie ein Zellbezug aussieht (`looksLikeCell`), ist der gerade
+getippte Funktionsname; alles andere (kein Token dort, ein Zellbezug, der
+Cursor sitzt hinter Leerraum nach einem abgeschlossenen Wort, `tokenize()`
+wirft bei einem kaputten Präfix) liefert `null` — kein Dropdown.
+
 `parseFormula(src, paramNames?)` akzeptiert einen optionalen zweiten
 Parameter: eine Liste von Namen, gegen die ein bare `IDENT` (das nicht wie
 eine Zelle aussieht) zusätzlich geprüft wird — ein Treffer erzeugt statt eines

src/engine/__tests__/functions.spec.ts

@@ -0,0 +1,18 @@
+import { describe, it, expect } from 'vitest';
+import { FUNCTIONS, BUILTIN_SIGNATURES } from '../functions';
+
+describe('BUILTIN_SIGNATURES', () => {
+  it('has exactly one entry per registered built-in function, names matching', () => {
+    const registered = Object.keys(FUNCTIONS).sort();
+    const signatures = BUILTIN_SIGNATURES.map((s) => s.name).sort();
+    // A future new built-in without a matching hint entry fails loudly here
+    // instead of just silently being missing from the autocomplete dropdown.
+    expect(signatures).toEqual(registered);
+  });
+
+  it('every hint actually starts with its own name', () => {
+    for (const s of BUILTIN_SIGNATURES) {
+      expect(s.hint.startsWith(s.name)).toBe(true);
+    }
+  });
+});

src/engine/__tests__/refs.spec.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { parseA1, toA1, cycleReferenceLocks } from '../refs';
+import { parseA1, toA1, cycleReferenceLocks, currentIdentifierAtCaret } from '../refs';
 
 describe('parseA1 / toA1: $-locked (absolute/mixed) references', () => {
   it('parseA1 reports which axes are $-locked', () => {
@@ -86,3 +86,38 @@ describe('cycleReferenceLocks (F4) -- a real text selection spanning several ref
     expect(cycleReferenceLocks('=SUM(1;2)', 4, 8)).toBeNull();
   });
 });
+
+describe('currentIdentifierAtCaret -- function-name autocomplete detection', () => {
+  it('right after "=", right after an operator, right after "(" or ";"', () => {
+    expect(currentIdentifierAtCaret('=S', 2)).toEqual({ text: 'S', start: 1 });
+    expect(currentIdentifierAtCaret('=A1+S', 5)).toEqual({ text: 'S', start: 4 });
+    expect(currentIdentifierAtCaret('=SUM(A', 6)).toEqual({ text: 'A', start: 5 });
+    expect(currentIdentifierAtCaret('=SUM(1;A', 8)).toEqual({ text: 'A', start: 7 });
+  });
+
+  it('null outside a formula (no leading "=")', () => {
+    expect(currentIdentifierAtCaret('SUM', 3)).toBeNull();
+  });
+
+  it('null once the word looks like a cell reference (has a digit)', () => {
+    expect(currentIdentifierAtCaret('=SUM(A1', 7)).toBeNull();
+    expect(currentIdentifierAtCaret('=A1', 3)).toBeNull();
+  });
+
+  it('null right after an already-open, complete function call', () => {
+    expect(currentIdentifierAtCaret('=SUM(', 5)).toBeNull();
+  });
+
+  it('null once the caret has moved past the word (trailing whitespace)', () => {
+    expect(currentIdentifierAtCaret('=SUM ', 5)).toBeNull();
+  });
+
+  it('only looks at text up to the caret, ignoring what follows it', () => {
+    // caret between "SUM" and "X" in "SUMX" -- same result as if "X" weren't there
+    expect(currentIdentifierAtCaret('=SUMX', 4)).toEqual({ text: 'SUM', start: 1 });
+  });
+
+  it('null on a malformed prefix (unterminated string) rather than throwing', () => {
+    expect(currentIdentifierAtCaret('=SUM("x', 7)).toBeNull();
+  });
+});

src/engine/functions.ts

@@ -139,6 +139,27 @@ export const FUNCTIONS: Record<string, FunctionFn> = {
 // AVERAGE is an alias of AVG.
 FUNCTIONS.AVERAGE = FUNCTIONS.AVG;
 
+/** One-line signature hint per built-in, for the formula-autocomplete
+ *  dropdown (see store/document.ts's `functionSuggestions()` and
+ *  src/composables/useFormulaAutocomplete.ts). Hand-maintained -- kept
+ *  honest by a test asserting its names exactly match `FUNCTIONS`'s keys,
+ *  so a future new built-in without a matching entry here fails loudly
+ *  instead of just silently missing from the dropdown. */
+export const BUILTIN_SIGNATURES: ReadonlyArray<{ name: string; hint: string }> = [
+  { name: 'SUM', hint: 'SUM(Zahl1; Zahl2; …)' },
+  { name: 'AVG', hint: 'AVG(Zahl1; Zahl2; …)' },
+  { name: 'AVERAGE', hint: 'AVERAGE(Zahl1; Zahl2; …)' },
+  { name: 'MIN', hint: 'MIN(Zahl1; Zahl2; …)' },
+  { name: 'MAX', hint: 'MAX(Zahl1; Zahl2; …)' },
+  { name: 'COUNT', hint: 'COUNT(Zahl1; Zahl2; …)' },
+  { name: 'IF', hint: 'IF(Bedingung; Dann; Sonst?)' },
+  { name: 'DATE', hint: 'DATE(Jahr; Monat; Tag)' },
+  { name: 'TIME', hint: 'TIME(Std; Min; Sek)' },
+  { name: 'TODAY', hint: 'TODAY()' },
+  { name: 'NOW', hint: 'NOW()' },
+  { name: 'XLOOKUP', hint: 'XLOOKUP(Suchwert; Suchbereich; Rückgabebereich; …)' },
+];
+
 export function hasFunction(name: string): boolean {
   return Object.prototype.hasOwnProperty.call(FUNCTIONS, name.toUpperCase());
 }

src/engine/index.ts

@@ -18,7 +18,7 @@ export {
 } from './parser';
 export { evaluate } from './evaluator';
 export { DependencyGraph } from './graph';
-export { FUNCTIONS, getFunction, hasFunction } from './functions';
+export { FUNCTIONS, getFunction, hasFunction, BUILTIN_SIGNATURES } from './functions';
 export {
   colToNumber,
   numberToCol,
@@ -27,6 +27,7 @@ export {
   looksLikeCell,
   expandRange,
   cycleReferenceLocks,
+  currentIdentifierAtCaret,
 } from './refs';
 export {
   Workbook,

src/engine/refs.ts

@@ -131,6 +131,49 @@ function nextLock(colAbs: boolean, rowAbs: boolean): [boolean, boolean] {
   return [false, false]; // colAbs && !rowAbs
 }
 
+/**
+ * If the caret sits inside (anywhere within, or right at the end of) a bare
+ * identifier being typed in a formula -- not yet a resolved cell reference,
+ * not the start of an already-open function call -- return the identifier's
+ * text *up to the caret* and its start offset in `formula` (which still
+ * includes the leading "="). Drives function-name autocomplete; `null`
+ * means "nothing to suggest here" (not a formula at all, a cell reference
+ * like "A1", the caret sitting in whitespace or right after a completed
+ * token rather than still touching it, ...).
+ *
+ * Same shape as {@link cycleReferenceLocks} above: strip the leading "=",
+ * tokenize, and inspect the token(s) around the caret -- except here only
+ * the prefix up to the caret is tokenized (nothing after it is ever looked
+ * at, same as how autocomplete works in most editors), so the "identifier"
+ * found is always exactly what's to the *left* of the caret, regardless of
+ * whether more of the same word continues to its right.
+ */
+export function currentIdentifierAtCaret(
+  formula: string,
+  caret: number,
+): { text: string; start: number } | null {
+  if (!formula.startsWith('=')) return null;
+  const pos = caret - 1; // caret position relative to body = formula.slice(1)
+  if (pos < 0) return null;
+  let toks: Token[];
+  try {
+    toks = tokenize(formula.slice(1, caret));
+  } catch {
+    return null;
+  }
+  // tokenize() appends a trailing EOF marker -- skip it to get the last
+  // *real* token.
+  const real = toks.filter((t) => t.type !== 'EOF');
+  const last = real[real.length - 1];
+  if (!last || last.type !== 'IDENT') return null;
+  // the token must reach all the way to the caret -- if it doesn't, the
+  // caret has moved past it (trailing whitespace, e.g. "=SUM |") and
+  // there's no word actively being typed right at the caret any more.
+  if (last.pos + last.value.length !== pos) return null;
+  if (looksLikeCell(last.value)) return null; // looks like a cell reference, not a function name
+  return { text: last.value, start: last.pos + 1 };
+}
+
 /**
  * Expand a rectangular range (given by two corners, any order) into the list of
  * cell coordinates it covers, row-major.