From 91de774f35b8446f0197f365f8224edaa982f28d Mon Sep 17 00:00:00 2001 From: Sia Date: Sat, 30 May 2026 15:20:07 +0200 Subject: [PATCH] docs: expand project documentation --- README.md | 7 +++++-- docs/architecture.md | 27 +++++++++++++++++++------- docs/development.md | 34 ++++++++++++++++++++++++++++++++- docs/supported-formats.md | 20 ++++++++++++++++---- docs/troubleshooting.md | 40 +++++++++++++++++++++++++++++++++++++++ docs/user-guide.md | 33 +++++++++++++++++++++++++++++--- 6 files changed, 144 insertions(+), 17 deletions(-) create mode 100644 docs/troubleshooting.md diff --git a/README.md b/README.md index f0357fb..96b218e 100644 --- a/README.md +++ b/README.md @@ -10,11 +10,12 @@ OpenWebSheet is an open-source, web-based spreadsheet application. It runs in th 1. Open the hosted app: 2. Install the PWA using the install icon in the browser address bar. -3. Download the sample file: +3. Download the sample file: 4. Use the folder/load icon in the app to open the sample `.ows` file. ## Features +- React application shell with shadcn-style controls - Canvas-based spreadsheet rendering - Basic cell content editing - Borders @@ -76,15 +77,17 @@ Additional documentation is available in the [`docs/`](docs/) directory: - [Development guide](docs/development.md) - [Architecture overview](docs/architecture.md) +- [UI structure](docs/ui-structure.md) - [User guide](docs/user-guide.md) - [Supported formats](docs/supported-formats.md) +- [Troubleshooting](docs/troubleshooting.md) ## Contributing 1. Create an issue or choose an existing one. 2. Create a focused branch for the change. 3. Keep changes small and reviewable. -4. Run linting and tests before opening a pull request. +4. Run tests, type checking, and the production build before opening a pull request. 5. Update documentation when behavior, setup, or architecture changes. ## License diff --git a/docs/architecture.md b/docs/architecture.md index ef56b18..0d29611 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -2,19 +2,32 @@ ## High-Level Components -- UI Layer (React-based) -- Spreadsheet core logic -- Canvas renderer -- Formula evaluation -- Import/export subsystem -- PWA integration +- React UI layer under `src/app`, `src/features`, and `src/shared`. +- Spreadsheet core logic under `src/lib/core`. +- Canvas rendering under `src/lib/rendering`. +- UI-to-core adapter logic under `src/lib/UI.ts` and `src/features/sheet`. +- Formula evaluation under `src/lib/core/formula`. +- Native `.ows` document import/export helpers under `src/features/document-io`. +- PWA integration through `src/registerServiceWorker.ts` and generated static assets. ## Design Principles - Keep spreadsheet logic independent from UI frameworks. - Minimize coupling between rendering and business logic. - Allow future UI migrations without rewriting the spreadsheet engine. +- Keep React components small and composed by feature area. +- Keep reusable UI primitives in `src/shared/ui`. +- Keep Tailwind class composition in `src/app/styles.css`. + +## Runtime Flow + +1. `src/main.ts` mounts the React app. +2. `src/app/App.tsx` owns top-level UI state for file mode, selection, formula bar value, and active appearance. +3. `SpreadsheetSurface` creates the existing `UI` adapter with a DOM element. +4. `UI` creates the canvas renderer and a `UIHandlerController`. +5. Ribbon and formula bar actions call `UI.execCmd`, which forwards commands to the spreadsheet core. +6. The core document emits changes back through `UI.addOnChangeEventListener`, and React updates the ribbon/formula state. ## Future Direction -A future React migration should focus on the UI layer only while preserving the existing spreadsheet core. +Advanced formula support, OpenDocument import/export, and richer spreadsheet interactions should extend the core APIs first, then expose those capabilities through the React features. diff --git a/docs/development.md b/docs/development.md index 8e58a23..146a824 100644 --- a/docs/development.md +++ b/docs/development.md @@ -1,5 +1,10 @@ # Development Guide +## Prerequisites + +- Node.js 18 or newer +- npm + ## Setup ```bash @@ -7,28 +12,55 @@ npm install npm run dev ``` +The development app is served from the Vite base path: + +```text +http://127.0.0.1:5173/OpenWebSheet/ +``` + ## Build ```bash npm run build ``` +The production build writes static assets to `docs/` so GitHub Pages can serve the app. + ## Testing ```bash npm test ``` +Use watch mode while working on UI behavior: + +```bash +npm run test:watch +``` + ## Type Checking ```bash npm run typecheck ``` +## Useful Scripts + +- `npm run dev`: start the local Vite server. +- `npm run build`: create the production build in `docs/`. +- `npm run preview`: preview the production build locally. +- `npm test`: run Vitest once. +- `npm run typecheck`: run TypeScript without emitting files. + ## Contribution Workflow 1. Create an issue. 2. Create a branch. 3. Implement changes. 4. Run tests and type checking. -5. Open a pull request. +5. Run the production build when changing UI, assets, or configuration. +6. Open a pull request with a summary and verification notes. + +## Build Warning + +The production build currently reports a direct `eval` warning from `src/lib/core/formula/Evaluator.ts`. The warning is known, and the build still succeeds. Changes to the formula engine should address that warning deliberately instead of hiding it in unrelated work. diff --git a/docs/supported-formats.md b/docs/supported-formats.md index 7c999e2..3ecd702 100644 --- a/docs/supported-formats.md +++ b/docs/supported-formats.md @@ -1,13 +1,25 @@ # Supported Formats -## Current +## Current Format -- .ows (OpenWebSheet native format) +### `.ows` + +OpenWebSheet's native format stores workbook data as JSON. It is the only supported import/export format today. + +Supported data includes: + +- Sheets and cells +- Cell values +- Basic formulas +- Merged cells +- Cell appearance used by the current renderer ## Planned -- OpenDocument Spreadsheet (.ods) +- OpenDocument Spreadsheet (`.ods`) ## Notes -Compatibility and import/export behavior should be documented as support expands. \ No newline at end of file +- `.ows` is intended for OpenWebSheet interoperability, not compatibility with other spreadsheet applications. +- `.ods` support is tracked separately and should include fixtures and interoperability tests when implemented. +- Unsupported features should fail gracefully and be documented as format support expands. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 0000000..9e8cb4e --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,40 @@ +# Troubleshooting + +## The Dev Server Opens A Blank Page + +Open the app at the Vite base path: + +```text +http://127.0.0.1:5173/OpenWebSheet/ +``` + +Opening `http://127.0.0.1:5173/` directly may not load the app because the project is configured for GitHub Pages under `/OpenWebSheet/`. + +## Dependencies Fail To Install + +Use a current Node.js 18+ runtime, then reinstall dependencies: + +```bash +rm -rf node_modules package-lock.json +npm install +``` + +Only remove `package-lock.json` when intentionally refreshing dependency resolution. + +## Production Build Shows An Eval Warning + +`npm run build` currently warns about direct `eval` in `src/lib/core/formula/Evaluator.ts`. This is known formula-engine behavior and does not fail the build. + +## Tests Cannot Find DOM APIs + +Vitest is configured with `jsdom` in `vite.config.ts`. If DOM APIs are missing, confirm tests are running through `npm test` and not through a bare TypeScript or Node command. + +## GitHub Pages Assets Look Stale + +Run a production build before publishing: + +```bash +npm run build +``` + +The generated files in `docs/` are part of the static GitHub Pages deployment. diff --git a/docs/user-guide.md b/docs/user-guide.md index d1fa577..926a74f 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -1,17 +1,44 @@ # User Guide +## Opening The App + +Open the hosted app at or run it locally with `npm run dev`. + ## Opening Files -Open the application and load an OWS spreadsheet file. +Use the folder button in the Home ribbon to load an `.ows` file. A sample file is available at . + +## Saving Files + +Use the save button in the Home ribbon to download the current workbook as an `.ows` file. + +## Local Storage Mode + +The Home ribbon includes a local storage mode. In local mode, document changes are saved in the browser's local storage. Return to file mode before using download/upload workflows. ## Editing -Select cells and modify their content. +Select a cell on the sheet and edit its value through the formula bar. The formula bar shows the selected cell name and the current value. ## Formatting -Borders, merge and split operations are supported. +The Home ribbon supports: + +- Font family and size +- Bold, italic, and underline +- Text and fill color +- Horizontal alignment +- Merge and split cells +- Border color and border presets ## Formulas Basic formula support is available. Advanced formula capabilities are tracked as a separate roadmap item. + +## View Layout + +The View ribbon includes layout controls for normal/page-oriented views and display toggles. These controls establish the UI surface for layout features; deeper renderer behavior will expand over time. + +## PWA Installation + +Modern browsers can install OpenWebSheet as a Progressive Web App. Use the install control in the address bar or browser menu while visiting the hosted app.