Clapilot Docs
Docs

Excel Editor

Bundled spreadsheet module for XLS/XLSX/XLSM/XLSB/CSV analysis and editing.

What it does

Excel Editor (excel-canvas) is a bundled module for working with spreadsheet documents (.xls, .xlsx, .xlsm, .xlsb, .csv) directly in Clapilot. It renders a workbook-aware grid with Word-like cell formatting, keeps formulas intact while showing calculated results, and saves back to the original file while preserving native Excel metadata. The agent can read and mutate cells live, with changes flashing in the open grid.

How to open it

  • Open the module from the Clapilot module menu; the route is /modules/excel-canvas.
  • In /dokumente and other shared document lists, a primary click opens supported spreadsheet documents directly in Excel Editor; the eye action still opens preview. /dokumente also exposes Neues Dokument, which can create a new Excel workbook and route directly into Excel Editor.
  • Deep links from document lists are supported: /modules/excel-canvas?docId=<dokument-id>, with optional sheet preselection via &sheet=<sheet-name>.
  • Uploads can go through the Clapilot inbox endpoint POST /api/documents/inbox.
  • Manifest: bundled-modules/excel-canvas/module.json (slug excel-canvas, entry index.html, renderer react, icon table). The React UI is src/components/modules/excel-canvas-module.tsx, hosted by src/app/(app)/modules/[slug]/page.tsx; the bundled frontend assets remain in bundled-modules/excel-canvas/ but the app renders the module directly in the main React tree.

Key workflows

Edit a sheet in the grid

  • Drag across cells to create a rectangular multi-cell selection; use Shift + mouse or Shift + arrow keys to extend it.
  • Enter/Shift+Enter commit and move down/up; Tab/Shift+Tab move right/left. F2 enters in-cell edit mode, while ready-mode arrows, Home, Page Up/Down, and Ctrl/Cmd navigation follow spreadsheet conventions.
  • Undo/redo covers cell edits, paste/clear, formatting, structural operations, resize, sort, autofill, replace-all, and live agent mutations (100-entry history).
  • Copy/cut writes raw TSV plus an HTML table with portable formatting. Internal paste retains styles, adjusts relative formula references, supports tiling, and clears a cut source only when paste completes; Einfügen (nur Werte) pastes evaluated values.
  • Drag the selection fill handle to continue numeric/text/calendar series or copy formulas with adjusted references and copied styles.
  • Drag the right edge of a column header or the bottom edge of a row header to resize that column/row directly in the grid.
  • Right click opens spreadsheet actions for the active cell or selection, including copy/cut/paste, values-only paste, sort, clear, merge/unmerge, hide/show, and row/column insert or delete. Row and column headers select whole loaded rows/columns and retain their resize edge.
  • The compact formatting toolbar covers font settings, emphasis/strikethrough, text/fill colors, borders, alignment, wrapping, number formats/decimal places, merge-and-center, and freeze panes.
  • A non-modal find/replace panel supports case-sensitive and whole-cell matching over raw and displayed values.
  • The grid keeps a dedicated bottom horizontal scrollbar visible for left/right navigation without a trackpad.
  • Formulas remain stored as formulas, while the grid renders the calculated result locally for common formulas such as SUM(...) and simple arithmetic/reference expressions.

Formulas

  • The handler ships a real formula engine (recursive-descent parser, no eval) that recalculates every formula cell on save and stores the formula plus its cached value (<f> + <v>) in the written file, so Excel, the module grid, and other consumers all see up-to-date results.
  • Supported: arithmetic (+ - * / ^ %), comparisons, & concatenation, cell refs and ranges (relative and $-absolute), and the common function set — SUM, AVERAGE, MIN, MAX, COUNT, COUNTA, IF, ROUND/ROUNDUP/ROUNDDOWN, ABS, SQRT, POWER, MOD, INT, TODAY, NOW, CONCAT/CONCATENATE, LEFT, RIGHT, MID, LEN, UPPER, LOWER, TRIM, AND, OR, NOT, SUMIF, COUNTIF, AVERAGEIF — including German aliases (SUMME, WENN, MITTELWERT, …) and ; argument separators.
  • Excel error values (#DIV/0!, #VALUE!, #NUM!, …) are computed, propagated, and serialized as real error cells; circular references resolve to an error instead of hanging.
  • Formulas the engine cannot evaluate (cross-sheet references, unsupported functions such as VLOOKUP) are left untouched together with their previously cached values.
  • The bundled iframe UI evaluates the same engine client-side (ui/formula.ts) for instant recalculation while typing.

Faithful import and save

  • The module reads a workbook-aware sheet snapshot for merges, hidden rows/columns, display text, comments, hyperlinks, style metadata, and unsupported-feature warnings, so imported XLSX layouts render close to the source file — including imported font family / size / bold / italic / underline formatting in the visible grid.
  • Save operations patch existing workbook state instead of rewriting only a raw cell matrix, which preserves more native Excel metadata on XLS/XLSX/XLSM/XLSB files.
  • Cell formatting now genuinely round-trips on XLSX/XLSM: SheetJS CE drops styles on write, so the handler hydrates per-cell styles from the original styles.xml on read and regenerates styles.xml (fonts, fills, borders, alignment, number formats incl. custom formats like #,##0.00 "€") plus the per-cell s= attributes inside the written container. Imported formatting and set_styles edits both survive save→reload.
  • Custom row heights and column widths are persisted for XLS/XLSX sheets on save and restored on reload; CSV can be resized in-session but does not store layout metadata in the file format.
  • Freeze panes round-trip on XLSX/XLSM: pane metadata is hydrated from the source worksheet on read and a <pane state="frozen"> element is re-injected on write, so set_pane operations and imported panes survive a fresh file reload.
  • .xls/.xlsb (binary) writes still go through plain SheetJS CE and keep values/formulas but not styling; CSV stores raw values only.

Toolbar actions

  • The native editor header uses two compact rows: the first contains the accessible worksheet selector plus reload, upload, save, and share actions; the second contains the formula bar, history/search commands, the complete formatting toolset, freeze panes, charts, and the current selection label.
  • The share action opens a keyboard-accessible menu for sending the saved document by fax, opening the email composer after copying the document link, or copying the document link directly. Non-default worksheet links preserve the active sheet.
  • Fax now lives inside the share menu rather than occupying a standalone toolbar button; its existing saved-version warning remains in place when the workbook has unsaved changes.
  • Dokumente back action returns to the shared documents list.

Worksheet management

  • The operations contract supports add_sheet ({name}), rename_sheet ({name, to}) and delete_sheet ({name}) alongside the cell-level operations. Names are sanitized/uniquified like Excel does; deleting the last worksheet is rejected. Stored module charts follow sheet renames and deletions.

Bundled iframe UI (index.html + ui/index.ts)

The bundled fallback UI (used when the module runs with the iframe renderer, e.g. distributed standalone) now covers the core spreadsheet workflows natively:

  • Formula bar with client-side recalculation via the shared engine in ui/formula.ts (same semantics as the server engine).
  • Formatting toolbar: bold/italic/underline, font size, text/fill color, horizontal alignment, number formats (Standard, Zahl, Tausender, Prozent, Währung €, Datum), clear-formatting — applied optimistically and persisted through set_styles operations.
  • Keyboard model: arrow/Home/PageUp/PageDown navigation, Shift-extend, Ctrl/Cmd+Arrow data-edge jumps, Enter/Tab commit-and-move, F2 edit, type-to-replace, Delete/Backspace clear, Ctrl/Cmd+C/X/V, Ctrl/Cmd+D fill down (with relative formula shifting), Ctrl/Cmd+Z/Y undo/redo (100 entries), Ctrl/Cmd+F find, Ctrl/Cmd+A, Ctrl/Cmd+S.
  • TSV clipboard interop with real Excel (copy/cut/paste of ranges, tile-paste of single values into a selection).
  • Find & replace bar (Suchen & Ersetzen) over raw and displayed values with next/previous, replace and replace-all.
  • Sort ascending/descending by the active column (selection-scoped or data region below the header row).
  • Row/column insert/delete from the toolbar and context menu, sent as insert_delete workbook operations so server-side styles shift along; column resize by dragging the header edge (persisted via resize).
  • Sheet tabs with add (+), rename (double-click or ✎, window.prompt) and two-step delete (🗑).
  • Selection statistics (Summe / Ø / Anzahl) in the status row, like Excel's status bar.

How the agent can drive it (tools)

Native ClapilotAICore tools for spreadsheet work:

  • excel_list_documents
  • excel_read_document
  • excel_read_cell
  • excel_update_cell
  • excel_update_cells
  • excel_apply_operations (workbook-aware structural operations)
  • excel_sum_selected_column_above

Live-update behavior:

  • Live tool mutations can return structured UI actions (excel.cells.updated) so the active module updates the affected cell values immediately and flashes the changed cells in place.
  • Workbook-aware live mutations can return excel.sheet.updated, allowing the active module to replace the visible sheet snapshot in place without a full reload.
  • There is no in-module chat UI; assistant actions proxy through the Clapilot runtime path. Use the global chat while the module is open.

Native iOS/macOS editor

The Apple client (clients/apple/ClapilotApple) ships a fully native SwiftUI spreadsheet editor for the same documents — no web view involved:

  • Opening a spreadsheet document (.xls, .xlsx, .xlsm, .xlsb, .csv) from the native Dokumente screen renders the native grid editor; newly created Excel workbooks open natively as well. Other document types keep the existing preview path.
  • The editor consumes the same module REST API and worksheet-operations contract as the web module (set_cells, set_styles, merge, insert_delete, set_pane, set_charts), so web, agent tools, and native clients stay interoperable on the same files.
  • Features: grid rendering with imported styles/merges/hidden rows/columns, cell + formula-bar editing, drag range selection, formatting toolbar (bold/italic/underline/strikethrough, text/fill colors, alignment, wrap, number formats, borders, merge), row/column insert/delete, sort, freeze panes, clipboard TSV copy/cut/paste, sheet switching, undo/redo, and native Swift Charts rendering of stored module charts (insert/edit/delete included).
  • Formula recalculation happens server-side: edits autosave through the operations endpoint (debounced), and the returned snapshot refreshes computed display values in the grid.
  • Implementation: Sources/Clapilot/Models/ExcelCanvasModels.swift, Sources/Clapilot/Views/ExcelCanvasEditorView.swift, Sources/Clapilot/Views/ExcelCanvasGridView.swift; API bindings in Sources/Clapilot/Networking/ClapilotAPI.swift (listExcelCanvasDocuments, getExcelCanvasDocument, applyExcelCanvasOperations).

Configuration & limits

  • Only spreadsheet file types are supported (.xls, .xlsx, .xlsm, .xlsb, .csv).
  • The module reads dokumente and mandanten metadata from the database and enforces access checks via document path resolution.
  • Runtime token resolution supports multiple sources (env/config/app settings); the health endpoint reports runtime reachability for the module UI.
  • CSV files cannot persist row/column layout metadata (format limitation).
  • CSV has no style or pane storage; those edits remain session-only while raw values continue to save.

API endpoints exposed by module

Base: /api/modules/excel-canvas/api — implementation: bundled-modules/excel-canvas/api/handler.mjs.

  • GET /docs (list supported documents)
  • POST /docs (create a new workbook in inbox)
  • GET /docs/:id (load spreadsheet data; returns a sheetSnapshot payload with workbook-aware display metadata in addition to raw cells)
  • POST /docs/:id (save rows/cells plus optional columnWidths / rowHeights layout metadata)
  • PATCH /docs/:id (update cells or apply workbook-aware operations[], incl. add_sheet / rename_sheet / delete_sheet; formulas are recalculated and styles re-serialized on every write)
  • PATCH /docs/:id/sheets/:sheet/cells (sheet-specific cell updates and operations)
  • POST /chat (gateway-backed assistant actions)
  • GET /health (module and gateway health)