gridpath 0.4.0

This release makes the web spreadsheet predictable inside your app: typed errors, stated contracts, saving to your own backend, and a complete Next.js example.

• Errors you can act on. Everything the spreadsheet reports is a GridPathError.
  • Each one has a code: unsupported-file, malformed-file, engine-failed, storage-failed, save-failed, calculation-timeout, pending-changes, unsaved-changes, not-found or not-ready.
  • Each one has a message that says what happened, and a hint you can show users. For example: "rows.csv" is a text file (CSV or similar), not an .xlsx workbook.
  • When a file can't be opened, the spreadsheet shows why in place of the grid.
• Stated contracts.
  • getCell() waits for recalculation, up to 30 s, then fails with calculation-timeout.
  • whenCalculated(ms) now rejects when the time runs out. Before, it resolved silently.
  • open() refuses while AI changes await review. It saves unsaved edits first, and fails with UnsavedChangesError when it can't save them (pass { discardUnsaved: true } to drop them).
  • If open() gets a file that can't be opened, the previous workbook stays open.
  • New: openStored(id) and hasUnsavedChanges().
  • Unmounting the component saves unsaved edits first, so a client-side navigation doesn't lose them. After that, the old sheet object fails with not-ready.
  • The File menu asks in its own dialog before it discards anything.
• Saving to your backend. httpStore({ url, headers }) saves to your API over a small REST contract (documented in the guide).
  • The status says where things are saved: "Saved in this browser" or "Saved to your account".
  • A save that fails is retried after 2, 5, 15 and 30 s, then every minute.
  • Meanwhile, the edits are kept in this browser ("Saved in this browser only"). If the page closes first, they reopen next time and are saved to the backend.
  • If the backend can't be reached when a workbook opens, the spreadsheet offers Try again. It never shows a blank workbook that autosave would write over the saved one.
• Excel's saved values, explained. Some formulas keep the value Excel saved: add-in functions, functions GridPath doesn't support yet, and links to other workbooks.
  • getCell() marks these cells with fromFile and a note that says why.
  • getCalcIssues() lists them.
  • The toolbar shows a count, with a panel that lists each cell.
• A complete Next.js example (examples/nextjs-demo) has:
  • per-user workbooks at their own URLs;
  • the REST routes httpStore calls, with auth;
  • upload and new workbooks;
  • a loading indicator;
  • an action for each error code;
  • switching workbooks.
• Docs. The README now starts with the web package. The guide covers documents, saving, your backend and errors, and has an API reference.

Breaking, for code that relied on the old behaviour:

• whenCalculated() rejects on timeout.
• open() throws instead of asking with window.confirm.
• onError receives a GridPathError (still an Error).
• createSpreadsheet calls options.onError for errors after the workbook opens.

npm install gridpath@0.4.0

For Claude Desktop, download gridpath-0.4.0.mcpb below and open it. Try the spreadsheet in your browser.