numolus/app/frontend/data/help.ts

/**
 * Content of the in-app help (components/HelpModal.vue): user-facing topics
 * and the keyboard shortcuts. Kept as plain data so the dialog's search can
 * run over it; the formula functions are not listed here but taken from
 * data/codeReference.ts, so a new built-in shows up in the help by itself.
 *
 * Text may use `**fett**` and `` `Code` `` -- see HelpModal's `rich()`.
 * Hand-maintained: whoever adds or changes a shortcut or a visible feature
 * updates this file too (the shortcut test only checks its shape).
 */

export interface HelpSection {
  heading?: string;
  items: string[];
}

export interface HelpTopic {
  id: string;
  title: string;
  sections: HelpSection[];
}

export interface Shortcut {
  /** As on Windows and Linux, with `Mod` for the platform's command key --
   *  see {@link shortcutKeys}. */
  keys: string;
  /** Mac keys where they differ by more than ⌘/⌥ (no Pos1/Bild/Entf keys on
   *  most Mac keyboards, F-keys behind fn, trackpad gestures). */
  mac?: string;
  description: string;
}

export type KeyPlatform = 'pc' | 'mac';

/** The keys of a shortcut as written on the given platform: `Mod` is Strg on
 *  Windows/Linux and ⌘ on a Mac, `Alt` is ⌥ on a Mac. Text that is not a key
 *  name (e.g. "Mod" in a help topic) is converted the same way. */
export function shortcutKeys(s: Pick<Shortcut, 'keys' | 'mac'> | string, platform: KeyPlatform): string {
  const text = typeof s === 'string' ? s : platform === 'mac' ? (s.mac ?? s.keys) : s.keys;
  if (platform === 'pc') return text.replace(/\bMod\b/g, 'Strg');
  return text.replace(/\bMod\b/g, '⌘').replace(/\bAlt\b/g, '⌥');
}

export interface ShortcutGroup {
  title: string;
  shortcuts: Shortcut[];
}

export const HELP_TOPICS: HelpTopic[] = [
  {
    id: 'start',
    title: 'Erste Schritte',
    sections: [
      {
        items: [
          'Ein **Blatt** ist eine freie Fläche, auf der **Objekte** liegen: Tabellen, Diagramme, Textfelder und Buttons. Sie werden über die Symbole in der Werkzeugleiste eingefügt.',
          'Objekte an ihrer Kopfleiste verschieben, an der Ecke unten rechts in der Größe ändern. Ein Doppelklick auf den Namen benennt sie um, das `×` in der Kopfleiste löscht sie.',
          'Mehrere Blätter über die Reiter unten: hinzufügen mit `+`, umbenennen per Doppelklick, Reihenfolge durch Ziehen.',
          'Das Zahnrad neben dem Titel öffnet die **Einstellungen** für das gewählte Objekt, das Blatt und das Dokument.',
          'Zoomen mit `Mod` + Mausrad oder über die Zoom-Leiste unten rechts.',
        ],
      },
    ],
  },
  {
    id: 'tables',
    title: 'Tabellen & Auswahl',
    sections: [
      {
        heading: 'Auswählen',
        items: [
          'Klick wählt eine Zelle, **Umschalt+Klick** oder Ziehen einen Bereich.',
          'Klick auf einen Spalten- oder Zeilenkopf wählt die ganze Spalte oder Zeile, die Ecke oben links die ganze Tabelle.',
          '**Mod+Klick** fügt eine weitere Zelle hinzu, **Mod+Ziehen** einen weiteren Bereich.',
          '**Mod+A** wählt den zusammenhängenden Bereich um die aktive Zelle, ein zweites Mal alle befüllten Zellen.',
          'Die Statusleiste zeigt Summe, Mittelwert und Anzahl der Auswahl.',
        ],
      },
      {
        heading: 'Eingeben',
        items: [
          'Einfach lostippen oder **F2** bzw. Doppelklick, um den Inhalt zu bearbeiten. **Enter** übernimmt, **Escape** bricht ab.',
          'Zeilenumbruch in einer Zelle mit **Alt+Enter** oder **Mod+Enter**.',
          'Der Inhalt der aktiven Zelle steht auch in der **Formelleiste** oben und kann dort bearbeitet werden. Links daneben zeigt das Namensfeld, wo man sich befindet. Dort kann auch ein Ziel eingegeben werden (`B5`, `Umsatz::A1:C4`, ein Tabellen- oder Blattname).',
        ],
      },
      {
        heading: 'Zeilen & Spalten',
        items: [
          'Rechtsklick auf einen Zeilen- oder Spaltenkopf: einfügen oder löschen.',
          'Rechtsklick in eine Zelle: kopieren, einfügen, Zeile oder Spalte am Ende hinzufügen, Abhängigkeiten anzeigen.',
          'Spaltenbreite und Zeilenhöhe durch Ziehen am Rand des Kopfs.',
          'In den Einstellungen kann eine Tabelle eine **feste Größe** mit eigenem Scrollbereich und fixierten Kopfzeilen und Spalten bekommen.',
        ],
      },
    ],
  },
  {
    id: 'formulas',
    title: 'Formeln',
    sections: [
      {
        heading: 'Grundlagen',
        items: [
          'Eine Formel beginnt mit `=`, z. B. `=SUM(B2:B6)*1.1` oder `=B2+C2`. Argumente werden mit `;` getrennt.',
          'Bezüge: `A1` eine Zelle, `A1:C4` ein Bereich, `B:B` eine ganze Spalte, `2:2` eine ganze Zeile.',
          'Andere Tabelle: `Umsatz!B2` oder `Umsatz::B2`. Gibt es den Tabellennamen auf mehreren Blättern: `Analyse!Umsatz::B2`. Namen mit Leerzeichen in einfachen Anführungszeichen: `\'Kosten Q3\'!A1`.',
          'Text in doppelten Anführungszeichen: `="Summe: " & B7`.',
          'Fehlt beim Übernehmen mit Enter eine schließende Klammer, wird sie ergänzt.',
        ],
      },
      {
        heading: 'Bezüge zeigen statt tippen',
        items: [
          'Während der Eingabe einer Formel fügt ein Klick in eine Zelle ihren Bezug ein, Ziehen einen Bereich. Das geht auch in anderen Tabellen.',
          'Mit der Tastatur: Direkt nach `=`, `(`, `;` oder einem Rechenzeichen wählen die **Pfeiltasten** eine Zelle, mit **Umschalt** einen Bereich.',
          'Alle Bezüge der Formel werden farbig umrahmt. **Am Rand ziehen** verschiebt einen Bezug, **an einer Ecke ziehen** ändert seine Größe. Die Formel passt sich sofort an.',
          '**F4** schaltet den Bezug am Cursor durch: `A1` → `$A$1` → `A$1` → `$A1`. Ein `$` hält Spalte oder Zeile beim Kopieren fest.',
        ],
      },
      {
        heading: 'Funktionen',
        items: [
          'Beim Tippen eines Funktionsnamens erscheint eine Vorschlagsliste. **Pfeil auf/ab** wählt, **Tab** oder **Enter** übernimmt.',
          'Alle eingebauten Funktionen stehen unter **Funktionen** in dieser Hilfe.',
          '**Eigene Funktionen** legt man über `fx` in der Werkzeugleiste an. Sie werden danach wie eingebaute aufgerufen.',
          '**Benannte Bereiche** (Etikett-Symbol) geben einem Bereich einen Namen, z. B. `=SUM(Umsatz_Q1)`.',
          'Rechtsklick in eine Zelle › **Abhängigkeiten anzeigen** zeigt, woraus eine Formel rechnet und wer sie verwendet.',
        ],
      },
    ],
  },
  {
    id: 'format',
    title: 'Formatierung',
    sections: [
      {
        items: [
          'Zellen auswählen, dann in den Einstellungen unter **Auswahl**: Ausrichtung, Zahlenformat, **F**ett, **K**ursiv, **U**nterstrichen, Text- und Füllfarbe.',
          'Mit der Tastatur: **Mod+Umschalt+B** (oder **F**) fett, **Mod+Umschalt+I** kursiv, **Mod+Umschalt+U** unterstrichen. Erneut drücken schaltet wieder aus.',
          'Die Formatierung gilt für die ganze Auswahl, auch für mehrere Bereiche.',
          'Wie Zahlen dargestellt werden (Dezimal- und Tausendertrennzeichen), richtet sich nach der Ländereinstellung von Objekt, Blatt oder Dokument.',
        ],
      },
    ],
  },
  {
    id: 'macros',
    title: 'Makros & Buttons',
    sections: [
      {
        items: [
          '**Makros** (Symbol in der Werkzeugleiste) ändern per Skript Zellen, Zeilen, Spalten, Tabellen und Blätter, auch dokumentweit.',
          'Ein Makro läuft nur, wenn man es startet: mit **Ausführen** im Makro-Dialog oder per Klick auf ein **Button**-Objekt auf der Fläche.',
          'Welches Makro ein Button startet, wird in den Einstellungen oder per Rechtsklick auf den Button gewählt.',
          'Neben dem Editor steht eine durchsuchbare Befehlsreferenz. Ein Klick fügt den Befehl ein.',
        ],
      },
    ],
  },
  {
    id: 'files',
    title: 'Speichern & Teilen',
    sections: [
      {
        heading: 'Speichern',
        items: [
          'Ohne Anmeldung liegen Dokumente **in diesem Browser** und werden automatisch gespeichert. In einem anderen Browser oder nach dem Löschen der Browserdaten sind sie dort nicht vorhanden.',
          'Mit **Anmelden** (Link oder Code per E-Mail) liegen Dokumente im Konto und sind überall verfügbar.',
          '**Datei › Dokumente …** listet alle Dokumente: öffnen, umbenennen, duplizieren, löschen, ins Konto hochladen.',
          '**Datei** öffnet und importiert `.num`, `.json`, `.csv` und `.xlsx` und exportiert in diese Formate.',
        ],
      },
      {
        heading: 'Teilen & gemeinsam bearbeiten',
        items: [
          '**Teilen** erstellt einen Link zum Ansehen oder Bearbeiten oder lädt per E-Mail ein. Ein lokales Dokument wird dafür zuerst hochgeladen.',
          'Änderungen der anderen erscheinen sofort. Ihre Auswahl ist als farbiger Rahmen mit Namen zu sehen, oben rechts stehen ihre Avatare.',
          'Rückgängig nimmt nur die eigenen Änderungen zurück.',
          'Wer nur ansehen darf, sieht „Nur Lesen“ und kann nichts ändern.',
        ],
      },
    ],
  },
];

export const SHORTCUT_GROUPS: ShortcutGroup[] = [
  {
    title: 'In der Tabelle',
    shortcuts: [
      { keys: 'Pfeiltasten', description: 'Zelle wechseln' },
      { keys: 'Umschalt+Pfeiltasten', description: 'Auswahl erweitern' },
      { keys: 'Mod+Pfeiltasten', description: 'An den Rand des Datenblocks springen (mit Umschalt: Auswahl bis dorthin)' },
      { keys: 'Tab / Umschalt+Tab', description: 'Nach rechts / links, innerhalb einer Auswahl der Reihe nach' },
      { keys: 'Enter / Umschalt+Enter', description: 'Nach unten / oben, innerhalb einer Auswahl der Reihe nach' },
      { keys: 'Pos1 / Ende', mac: 'fn+← / fn+→', description: 'Anfang / Ende der Zeile' },
      { keys: 'Mod+Pos1 / Mod+Ende', mac: 'fn+⌘+← / fn+⌘+→', description: 'Erste / letzte Zelle der Tabelle' },
      { keys: 'Bild auf / Bild ab', mac: 'fn+↑ / fn+↓', description: 'Seitenweise blättern' },
      { keys: 'Mod+A', description: 'Zusammenhängenden Bereich wählen, zweimal: alle befüllten Zellen' },
      { keys: 'F2', mac: 'F2 (ggf. fn+F2)', description: 'Aktive Zelle bearbeiten (oder einfach lostippen)' },
      { keys: 'Entf / Rücktaste', mac: '⌫ / fn+⌫', description: 'Inhalt der Auswahl leeren' },
      { keys: 'Mod+C / Mod+X / Mod+V', description: 'Kopieren / Ausschneiden / Einfügen' },
      { keys: 'Escape', description: 'Markierung der kopierten Zellen aufheben' },
      { keys: 'Mod+Umschalt+B oder F', description: 'Fett ein/aus' },
      { keys: 'Mod+Umschalt+I', description: 'Kursiv ein/aus' },
      { keys: 'Mod+Umschalt+U', description: 'Unterstrichen ein/aus' },
    ],
  },
  {
    title: 'Beim Bearbeiten einer Zelle',
    shortcuts: [
      { keys: 'Enter / Tab', description: 'Übernehmen und nach unten / rechts' },
      { keys: 'Umschalt+Enter / Umschalt+Tab', description: 'Übernehmen und nach oben / links' },
      { keys: 'Escape', description: 'Abbrechen' },
      { keys: 'Alt+Enter oder Mod+Enter', description: 'Zeilenumbruch in der Zelle' },
      { keys: 'Pfeiltasten nach = ( ; oder Rechenzeichen', description: 'Zellbezug wählen, mit Umschalt einen Bereich' },
      { keys: 'F4', mac: 'F4 (ggf. fn+F4)', description: 'Bezug sperren: A1 → $A$1 → A$1 → $A1' },
      { keys: 'Pfeil auf/ab, Tab oder Enter', description: 'In der Vorschlagsliste wählen und übernehmen' },
    ],
  },
  {
    title: 'Allgemein',
    shortcuts: [
      { keys: 'Mod+Z', description: 'Rückgängig' },
      { keys: 'Mod+Y oder Mod+Umschalt+Z', description: 'Wiederholen' },
      { keys: 'Mod+Mausrad', mac: '⌘+Mausrad oder Trackpad mit zwei Fingern auseinander/zusammen', description: 'Zoomen' },
      { keys: 'Entf / Rücktaste', mac: '⌫', description: 'Gewähltes Diagramm löschen' },
      { keys: 'F1', mac: 'F1 (ggf. fn+F1)', description: 'Diese Hilfe öffnen' },
    ],
  },
];