From 60aa2dfe07828d8f19455a29478bdded63c7bd43 Mon Sep 17 00:00:00 2001 From: Brandon Thomas Date: Sat, 10 Oct 2026 14:09:06 -0400 Subject: [PATCH] Progress docs: target-app parity, gaps, alpha gate, readiness by audience (#189) Progress docs per craftrules standards/progress-docs.md: target-app parity, gaps, roadmap with alpha gate, readiness by audience (full / mainstream / essentials) with Opus 5.5 hours, and feature, format, hardware, UI and localization parity docs. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 2 +- CLAUDE.md | 2 +- README.md | 13 +- ROADMAP.md | 263 +++++++++--------- crates/engine/src/catalog.rs | 2 +- docs/architecture.md | 71 +++++ docs/chart-parity.md | 82 ++++++ docs/file-format-parity.md | 78 ++++++ docs/function-parity.md | 100 +++++++ docs/gaps.md | 154 +++++++++++ docs/hardware-parity.md | 23 ++ docs/localization-parity.md | 77 ++++++ docs/{parity.md => parity-checklist.md} | 4 +- docs/releasing.md | 2 +- docs/roadmap.md | 117 ++++++++ docs/target-app-parity.md | 338 ++++++++++++++++++++++++ docs/ui-parity.md | 95 +++++++ xtask/src/main.rs | 8 +- xtask/src/parity.rs | 13 +- 19 files changed, 1296 insertions(+), 148 deletions(-) create mode 100644 docs/architecture.md create mode 100644 docs/chart-parity.md create mode 100644 docs/file-format-parity.md create mode 100644 docs/function-parity.md create mode 100644 docs/gaps.md create mode 100644 docs/hardware-parity.md create mode 100644 docs/localization-parity.md rename docs/{parity.md => parity-checklist.md} (98%) create mode 100644 docs/roadmap.md create mode 100644 docs/target-app-parity.md create mode 100644 docs/ui-parity.md diff --git a/AGENTS.md b/AGENTS.md index aaf3448..fdb7c49 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -50,7 +50,7 @@ People trust GridCraft with their numbers; a crash loses their work. **This outr - Parallel agents: separate `CARGO_TARGET_DIR` per agent; edit only the crates you own; delete your target dir when done. ## Roadmap -`ROADMAP.md` (committed) tracks status, milestones, parity and estimates. Update it whenever a milestone task lands. `cargo xtask parity` regenerates `docs/parity.md` from `crates/engine/src/catalog.rs`. +`ROADMAP.md` (committed) is the one-page summary: stage, headline numbers, dimensions, languages, progress log. It follows craftrules `standards/progress-docs.md` and points at the detail in `docs/`: `target-app-parity.md` (authoritative assessment), `gaps.md` (ranked work list: pick from it), `roadmap.md` (current focus, beta gates, milestones), `architecture.md`, and the area checklists `function-parity.md`, `chart-parity.md`, `file-format-parity.md`, `ui-parity.md`, `hardware-parity.md`, `localization-parity.md`. Update the affected docs (and their timestamp lines and revision history) whenever work lands. `cargo xtask parity` regenerates `docs/parity-checklist.md` from `crates/engine/src/catalog.rs`. ## Contributor credits (About window) diff --git a/CLAUDE.md b/CLAUDE.md index 54e9d03..4dc333b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -50,4 +50,4 @@ People trust GridCraft with their numbers; a crash loses their work. **This outr - Parallel agents: separate `CARGO_TARGET_DIR` per agent; edit only the crates you own; delete your target dir when done. ## Roadmap -`ROADMAP.md` (committed) tracks status, milestones, parity and estimates. Update it whenever a milestone task lands. `cargo xtask parity` regenerates `docs/parity.md` from `crates/engine/src/catalog.rs`. +`ROADMAP.md` (committed) is the one-page summary: stage, headline numbers, dimensions, languages, progress log. It follows craftrules `standards/progress-docs.md` and points at the detail in `docs/`: `target-app-parity.md` (authoritative assessment), `gaps.md` (ranked work list: pick from it), `roadmap.md` (current focus, beta gates, milestones), `architecture.md`, and the area checklists `function-parity.md`, `chart-parity.md`, `file-format-parity.md`, `ui-parity.md`, `hardware-parity.md`, `localization-parity.md`. Update the affected docs (and their timestamp lines and revision history) whenever work lands. `cargo xtask parity` regenerates `docs/parity-checklist.md` from `crates/engine/src/catalog.rs`. diff --git a/README.md b/README.md index d416eba..aa24ed8 100644 --- a/README.md +++ b/README.md @@ -191,12 +191,13 @@ egui frontend is a separate crate, so the UI can be swapped without touching the ## Roadmap -GridCraft is pre-alpha and moving fast. It covers 89% of Excel's ribbon and menu commands -([`docs/parity.md`](docs/parity.md)) and about 93% of its worksheet functions; weighted by depth, -we estimate about 65% of what Excel power users rely on. We're roughly 80% of the way to a first -alpha. Next up: signed release builds, XLSX fidelity on real-world files, performance on very large -sheets, then slicers, Solver, chart trendlines and a true Page Layout view. The plan and estimates -are in [ROADMAP.md](ROADMAP.md). +GridCraft is in **alpha**: the core workflow works end to end, but depth, fidelity and file +compatibility are still rough. It covers 89% of the Excel ribbon commands in our catalog +([`docs/parity-checklist.md`](docs/parity-checklist.md)) and 501 of Excel's 523 worksheet functions +([`docs/function-parity.md`](docs/function-parity.md)); weighted by what Excel users rely on, we +estimate it is about 50% ready for real work. Next up: XLSX fidelity on real-world files, very large +workbooks and multi-threaded recalc, chart depth, text in every script, and `.xls` import. Stage, +numbers and estimates are in [ROADMAP.md](ROADMAP.md); the ranked work list is [`docs/gaps.md`](docs/gaps.md). ## Downloads diff --git a/ROADMAP.md b/ROADMAP.md index 32ddbcd..1189fd7 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,138 +1,149 @@ # GridCraft roadmap -GridCraft aims at full Microsoft Excel parity — and to be better: faster, open (XLSX is the -native format), fully scriptable by agents (MCP + control channel + CLI), and available on the -web. +**Stage: alpha** · next: beta, ~25 points of "ready for real work" and ~160–240 h away -## Status (2026-10-07) +> **Last reviewed:** 2026-10-10 · **Last updated:** 2026-10-10 · **Change:** major (full re-measure against Excel for Mac 16.113.4; restructured to the craftrules progress-docs standard) · **Target:** Microsoft Excel (Microsoft 365) -### Where we are +GridCraft aims at full Microsoft Excel parity, and at being better in places: faster, open (XLSX +is the native format), fully scriptable by agents (MCP, control channel, CLI), and on the web. +This page is the summary. The detail is in: -| Measure | Value | Notes | +- [`docs/target-app-parity.md`](docs/target-app-parity.md): the authoritative assessment, method and weights +- [`docs/gaps.md`](docs/gaps.md): every known shortfall, ranked; the work list +- [`docs/roadmap.md`](docs/roadmap.md): milestones, current focus, what's next +- [`docs/parity-checklist.md`](docs/parity-checklist.md): generated by `cargo xtask parity` (ribbon commands) +- Area checklists: [functions](docs/function-parity.md) · [charts](docs/chart-parity.md) · + [file formats](docs/file-format-parity.md) · [UI](docs/ui-parity.md) · + [hardware](docs/hardware-parity.md) · [localization](docs/localization-parity.md) +- [`docs/architecture.md`](docs/architecture.md): how it is built + +## Headline numbers + +| Number | Value | Kind | |---|---|---| -| Ribbon/menu command catalog | **89%** (258 / 290) | `cargo xtask parity` → [`docs/parity.md`](docs/parity.md). Home, Draw, Page Layout, Formulas, Automate, Chart Design and PivotTable Design are at 100%. | -| Worksheet functions | **~93%** of Excel's ~545 | Missing: ODDF*/ODDL*, BAHTTEXT, IMAGE, TRANSLATE, COPILOT/PY, STOCKHISTORY, RTD | -| Feature depth (weighted) | **~65%** | The catalog counts a command once it exists; many are shallower than Excel's (see "What's left") | -| Tests | 332 passing | engine, formula, functions, calc, XLSX (incl. PivotTable round-trip), PDF, MCP, CLI, kittest UI | +| **Feature breadth** (weighted) | **~75%** | estimated, anchored on two measurements: ribbon catalog 258 / 290 (89.0%), worksheet functions 501 / 523 (95.8%; 492 working, 94.1%) | +| **Ready for real work** | **~50%** | estimated from written weights (51.6); [target-app-parity.md](docs/target-app-parity.md) | +| **Mainstream practitioner** | **~50%** | estimated: typical analyst/finance user, weekly features, × 0.90 interaction × 0.92 stability × 0.88 file exchange; [method](docs/target-app-parity.md#mainstream-practitioner) | +| **Essentials user** | **~63%** | estimated: core features only, × 0.92 launch/stability × 0.95 clarity × 0.90 opening sent files; [method](docs/target-app-parity.md#essentials-user) | +| Remaining to **beta** | **~160–240 Opus 5.5 agent-hours** | estimated; itemized in [roadmap.md](docs/roadmap.md#beta-gates) | +| Remaining to **full parity** | **~700–1,100 Opus 5.5 agent-hours** | estimated; sum of the dimension rows below | -The catalog number is generous: it says "this button does something real", not "it does -everything Excel's does". The weighted depth figure is our honest estimate of how much of what an -Excel power user relies on works as well as in Excel. +| Audience | Ready % | Opus 5.5 agent wall-clock hours to ~95% | Work that dominates | +|---|---|---|---| +| Full target (ready for real work) | ~50% | ~650–1,050 | Get & Transform and the data model, localization (twelve languages), charts depth, file fidelity (`.xls`, corpus, pass-through), PivotTables, collaboration, mobile | +| Mainstream practitioner | ~50% | ~200–310 | File exchange with Excel users (corpus and Excel verification, pass-through, large files, `.xls`, encryption: 63–97 h), common-chart depth (30–45 h), PivotTables (20–30 h), keyboard and interaction (18–28 h), calc correctness and functions (20–33 h) | +| Essentials user | ~63% | ~60–100 | Opening files people send (`.xls` and encrypted import 28–42 h; macOS Finder open 2–4 h), launch stability (6–10 h), basic chart resize and polish (6–10 h), print and Page Layout (8–12 h), small editing and UI fixes (10–16 h) | -### How close to an alpha? +Each tier is a subset of the one above, so its hours are too. Calibrated as in [Effort and +calibration](docs/target-app-parity.md#effort-and-calibration) (~6–10 h per readiness point for the remaining, verification-heavy +work; single features measured from PRs #66, #100, #101). Parallelism: the full and mainstream +work splits ~65–70% across 4–6 agents by area; the essentials work is mostly small fixes plus one +long `.xls` track, so about half parallelizes (≈30–50 wall-clock hours with three agents). -**About 80% of the way to an alpha. Estimate: ~35 wall-clock hours of Claude Opus 5.5 agent -work** (2–3 days with 2–3 parallel agents), plus a few minutes of human time to set up release -secrets. +Why alpha: all six core workflows in the [alpha gate](docs/roadmap.md#alpha-gate) pass end to end on macOS with save and reopen, and the core workflow works end to end (open an XLSX, enter formulas and data, format, sort +and filter, chart, pivot, print to PDF, save XLSX), but users still hit blocking gaps on real +files: 100 MB workbooks don't open (#175), there's no `.xls` (#121), Arabic and Devanagari text +isn't shaped (Chinese text still reported in #142), charts lose their type and options on round trip, and +nobody has yet confirmed that Excel opens our output without a repair prompt across a real +corpus. Beta needs those closed (see [beta gates](docs/roadmap.md#beta-gates)). -Alpha means: someone can download a signed build, open their real workbooks, edit and save them -without losing data, and not hit a crash in a normal session. The gates: +The 2026-10-07 numbers (catalog 89%, "feature depth ~65%", "~215 h to full parity") were +re-measured. Catalog and function counts held or rose; the depth and hours moved because of new +evidence: 82 issues filed by users and contributors in the repo's first five days, and scope the +old estimate left out (localization, legacy `.xls`, Power Query and the data model, +collaboration, mobile, AI). -| Alpha gate | State | Est. hours | +## By dimension + +| Dimension | Ready for real work | Hours to parity | Doc | +|---|---|---|---| +| Features (13 areas, table below) | ~59% (breadth ~75%) | 300–485 | [target-app-parity.md](docs/target-app-parity.md#feature-areas) | +| UI/UX fidelity | ~55% | 50–80 | [ui-parity.md](docs/ui-parity.md) | +| File formats | ~50% | 80–120 | [file-format-parity.md](docs/file-format-parity.md) | +| Performance | ~35% | 35–55 | [target-app-parity.md](docs/target-app-parity.md#performance) | +| Stability | ~60% | 15–25 | [gaps.md](docs/gaps.md) | +| Localization | ~10% (ribbon in 5 languages) | 100–165 | [localization-parity.md](docs/localization-parity.md) | +| Hardware (multi-core calc, GPU, pen, multi-window) | ~40% | 25–40 | [hardware-parity.md](docs/hardware-parity.md) | +| Platforms | ~80% (no iOS/Android; ahead on Linux, BSD, RISC-V) | 30–60 | [target-app-parity.md](docs/target-app-parity.md#platforms) | +| Ecosystem / add-ins | ~10% (VBA out of scope; own scripts, MCP, CLI) | 25–40 | [target-app-parity.md](docs/target-app-parity.md#ecosystem-and-ai) | +| AI features | ~15% (agent control strong; no in-app assistant) | 30–50 | [target-app-parity.md](docs/target-app-parity.md#ecosystem-and-ai) | +| **Total** | **~50%** | **~700–1,100** | | + +## Features + +| Area | Breadth | Ready | Hours | Doc | +|---|---|---|---|---| +| Formula language and calculation | ~92% | ~72% | 20–30 | [target-app-parity.md](docs/target-app-parity.md#feature-areas) | +| Worksheet functions | 95.8% measured | ~82% | 18–30 | [function-parity.md](docs/function-parity.md) | +| Editing, navigation, clipboard, fill | ~90% | ~70% | 15–25 | [ui-parity.md](docs/ui-parity.md) | +| Cell formatting, styles, conditional formatting | ~95% | ~80% | 8–14 | [target-app-parity.md](docs/target-app-parity.md#feature-areas) | +| Sort, filter, tables, validation, outline | ~82% | ~70% | 10–16 | [target-app-parity.md](docs/target-app-parity.md#feature-areas) | +| PivotTables | ~65% | ~45% | 25–40 | [target-app-parity.md](docs/target-app-parity.md#feature-areas) | +| Charts and sparklines | ~50% | ~30% | 40–60 | [chart-parity.md](docs/chart-parity.md) | +| Page layout, print, PDF | ~80% | ~55% | 12–20 | [target-app-parity.md](docs/target-app-parity.md#feature-areas) | +| What-if and analysis (Goal Seek, Solver, ToolPak, Forecast) | ~50% | ~40% | 22–35 | [target-app-parity.md](docs/target-app-parity.md#feature-areas) | +| Get & Transform, external data, data model | ~15% | ~10% | 60–100 | [target-app-parity.md](docs/target-app-parity.md#feature-areas) | +| Insert objects (pictures, shapes, ink, SmartArt, equations) | ~55% | ~45% | 25–40 | [target-app-parity.md](docs/target-app-parity.md#feature-areas) | +| Review, comments, protection, collaboration | ~55% | ~40% | 35–55 | [target-app-parity.md](docs/target-app-parity.md#feature-areas) | +| Automation (recorded scripts; no VBA) | ~30% | ~20% | 12–20 | [target-app-parity.md](docs/target-app-parity.md#feature-areas) | + +## Languages + +The ribbon is translated into Japanese, Simplified Chinese, Korean, Brazilian Portuguese and +Russian (266–268 labels each, ~12% of ~2,200 strings; merged 10-10 in #31, #104, #82), the +interface follows the system language, and CJK, Thai and Hebrew text falls back to system fonts +(#38). Dialogs, menus and messages are English; formulas and number formats are en-US only. German +is in PR #163. Detail: [localization-parity.md](docs/localization-parity.md). + +| Language | Code | Status | UI strings | +|---|---|---|---| +| English | en | full (source language) | 100% | +| Simplified Chinese | zh-Hans | menus only | ~12% | +| Spanish | es | none | 0% | +| Hindi | hi | none | 0% | +| Arabic | ar | none (no RTL layout, no shaping) | 0% | +| French | fr | none | 0% | +| Portuguese | pt-BR | menus only | ~12% | +| Indonesian | id | none | 0% | +| Japanese | ja | menus only | ~12% | +| German | de | none (PR #163 open) | 0% | +| Korean | ko | menus only | ~12% | +| Vietnamese | vi | none | 0% | + +Other shipped languages: 1 (Russian, menus only, ~12%). + +## Upcoming + +Ranked; estimates in Opus 5.5 agent-hours. Detail and the full beta-gate list in +[docs/roadmap.md](docs/roadmap.md). + +1. **Land the open PR queue** (50 open PRs on 2026-10-10, many fixing listed gaps: recalc and spill + correctness, chart kind round-trip, CJK font fallback, macOS Finder open, German and Chinese + UI). Review and merge: 8–15 h. +2. **XLSX fidelity on a real-world corpus**, with Excel opening our output without repair: 25–35 h. +3. **Large workbooks and recalc speed**: 100 MB XLSX, 1M rows, multi-threaded recalc: 40–60 h. +4. **Charts depth**: kinds and options round-trip, axes, trendlines, error bars: 25–35 h. +5. **Text in every script** (CJK, Thai, Arabic, Devanagari) in cells and PDF: 12–20 h. +6. **Legacy `.xls` import and password-protected workbooks**: 20–30 h. +7. **Localization**: extend the catalog past the ribbon, then the twelve languages: 100–165 h. + +## Progress log + +| Date | What landed | +|---|---| +| 2026-10-10 | Ribbon translated into Japanese, Chinese, Korean, Brazilian Portuguese and Russian with system-language default (#31, #104, #82); CJK/Thai/Hebrew font fallback (#38); clear messages for encrypted and `.xls` files (#17); smooth line charts (#62). Progress docs restructured to the craftrules standard; full re-measure (this page). Initial ribbon key tips (#43), in-place text box editing (#84), copy as HTML table (#36). ODS and XLSB data import (#100, #101); recalc linear in the number of range formulas (#66); RISC-V Linux build; Flatpak repository on Pages; web cell-commit trap fixed | +| 2026-10-09 | Community fixes: spill range operator `A1#`, sheet-scoped names, protection refuses locked-cell edits, Insert/Delete Cells adjust references, `DATE(1900,2,29)`, SUMIF sizing, `ROUND` at 15 digits, `_xlpm.` LAMBDA parameters in XLSX, vertical scrollbar, system appearance, border previews; v0.4.0 | +| 2026-10-08 | v0.2.0 and v0.3.0 releases; Flatpak, AppImage zsync, branded DMG; desktop log file; DirectX 12 default on Windows | +| 2026-10-07 | About window with contributor and model credits; macOS release runner | +| 2026-10-06 | M0–M13 first pass: engine, 478 functions, XLSX/CSV, egui UI, charts, PivotTables with XLSX round-trip, PDF and printing, what-if, spelling, Draw, task panes, MCP, CLI, web build, release packaging | +| 2026-10-05 | Repository created | + +## Revision history + +| Date | Change | Summary | |---|---|---| -| Signed release builds on every platform | Workflows and packaging ready; **blocked on the `release` environment and secrets, which need a human** (see [`docs/releasing.md`](docs/releasing.md)). Then a test build per platform | 4 | -| XLSX fidelity on real files | Round-trip tests pass for our own files. Needs a corpus run on real-world workbooks, and confirming Excel opens our output (including PivotTables) with no repair prompt | 10 | -| Performance | Virtualised grid and O(log n) geometry are in. Still need: 100k-cell edit recalc under 100 ms (currently ~0.4 s), faster write-back, 1M-row open | 8 | -| Never-crash soak | Every-command fuzz test exists. Needs a longer randomised UI soak and an autosave/recovery check | 4 | -| Papercuts | Dark-mode row/column headers, a true Page Layout (paper) view, focus edge cases, error messages | 6 | -| Docs and first-run | README, CLI/MCP docs exist; needs a "getting started" page and release notes | 3 | -| **Total** | | **≈ 35** | - -### How far to 100% parity? - -**Estimate: ~180 wall-clock hours of Claude Opus 5.5 agent work beyond the alpha** (about 1–1.5 -weeks running continuously with 3–4 parallel agents), so **≈ 215 hours in total from today**. -Breakdown under "What's left" below. - -Scope decisions that affect the count: VBA is out of scope (GridCraft has its own recorded and -editable scripts instead), and features that need Microsoft cloud services (Copilot, live Stocks/ -Geography data types, co-authoring through OneDrive, Smart Lookup, Translate) will be replaced -by open equivalents or left out, not cloned. - -### What's left - -| Area | What's missing | Est. hours | -|---|---|---| -| PivotTables | Slicers and timelines, calculated fields/items, PivotCharts, value/label filters, number grouping | 24 | -| Charts | Trendlines, error bars, full axis options (log scale, units, crossing), element-level Format pane, chart sheets, Recommended Charts dialog, maps | 26 | -| Data | Solver, Analysis ToolPak, Forecast Sheet, Get & Transform beyond CSV/JSON/HTML (Power Query editor lite), relationships / data model | 34 | -| Page layout & print | True Page Layout view, header/footer editor on the page, print preview polish | 12 | -| Insert & Review | Equations, WordArt, SmartArt-lite, signature line, comment navigation, Show Changes, Allow Edit Ranges, notes ↔ comments conversion | 20 | -| XLSX depth | Remaining OOXML parts (form controls, slicer caches, external links, OLE stubs), round-trip of everything we don't model | 16 | -| Functions | The remaining ~35 functions, exact Excel edge-case behaviour across the long tail | 10 | -| Performance | Parallel recalc, 1M-row workbooks everywhere (sort, filter, fill), memory | 14 | -| Fidelity | Side-by-side pixel tuning against Excel, keyboard shortcut completeness, accessibility, localisation | 24 | -| **Total** | | **≈ 180** | - -**Working today** -- Engine: A1/R1C1 formula parser with reference adjustment, dependency-graph recalculation with - dynamic arrays (spill + `#SPILL!`), cycle detection, LET/LAMBDA/MAP/REDUCE/SCAN/BYROW/BYCOL/ - MAKEARRAY, structured table references, defined names, INDIRECT/OFFSET/INDEX references, - 478 worksheet functions (math, statistics and distributions, text and regex, lookup incl. - XLOOKUP/FILTER/SORT/UNIQUE/VSTACK, dates, financial incl. bonds, engineering incl. complex - numbers and Bessel, database, information). -- Number formats: Excel's full format-code language (sections, conditions, colours, dates and - elapsed time, fractions, scientific, accounting fill), General narrowing to column width. -- Files: XLSX read/write (styles, themes, merges, CF, validation, tables, comments, hyperlinks, - charts, pictures, sparklines, print settings, defined names, shared/array/dynamic formulas), - CSV/TSV with encoding and delimiter detection, HTML export, JSON. -- Editing: cell entry with type detection and auto-formats, in-cell and formula-bar editing, - point mode (click/drag/arrow references), reference colouring, F4 anchor cycling, function - autocomplete and argument hints, copy/cut/paste and Paste Special (values, formats, transpose, - operations, link, skip blanks), AutoFill series (numbers, dates, months, weekdays, custom lists, - text+number), Fill Series, Flash Fill, find/replace with wildcards, Go To / Go To Special, - undo/redo with history, format painter. Quick selection drags retain their final endpoint; - the fill handle explains how to fill versus select cells. -- Formatting: fonts, fills, all border styles, alignment (wrap, indent, rotation, merge), number - formats, 47 cell styles, 60 table styles, conditional formatting (cell rules, text, dates, - duplicates, top/bottom, averages, data bars, colour scales, icon sets, formulas), automatic - row heights, autofit, hide/unhide, freeze panes. - Border presets include visual diagrams; Format Cells previews draft borders before applying. -- Data: sort (multi-level, by colour, custom lists), AutoFilter (values, custom, top 10, - average, colour), tables with totals rows, remove duplicates, text to columns, data validation - with error alerts, grouping/outline, subtotals. -- PivotTables: Insert/Recommended PivotTables, field list pane, compact/outline/tabular layouts, - date grouping, sort, filters, show-values-as, refresh, and XLSX round-trip. -- Page layout & print: Page Break Preview, print settings, PDF export and printing. -- What-if: Goal Seek, scenarios, data tables. Spelling (system word list) and thesaurus. -- Draw: pen, highlighter, eraser, ink strokes and Ink to Shape. Task panes: Comments (threaded - replies, resolve), Watch Window, Selection, Format Chart. -- Charts: column, bar, line, area, pie, doughnut, scatter, bubble, radar, histogram, waterfall, - funnel, treemap, sunburst, box & whisker, stock and combo charts; sparklines. -- UI (egui): Excel-style title bar with Quick Access Toolbar and AutoSave, the full ribbon with - galleries (cell styles, table styles, colour palettes, conditional formatting menus), - contextual Table/Chart Design tabs, formula bar with Name Box, virtualised grid (smooth - scrolling, zoom, frozen panes, text overflow), sheet tabs (rename, reorder, colour, hide), - status bar with Sum/Count/Average and zoom, dialogs (Format Cells, Formula Builder, Find and - Replace, Sort, Name Manager, Data Validation, Paste Special…), command palette, dark mode. -- Agents: every action is an engine command; JSON control channel in the desktop app (pointer, - keyboard, dialogs, screenshots); MCP server (headless or bridged); CLI (`info`, `convert`, - `eval`, `cat`, `run`, `commands`, `functions`, `mcp`, `send`). -- Platforms: macOS, Windows, Linux, FreeBSD; web (WASM via trunk). Release workflows for - signed/notarized macOS universal DMG, signed Windows x64/x86 MSI + zip, Linux AppImage/deb/rpm/ - tar.gz + Flatpak manifest, FreeBSD tarball and a web zip. - -## Milestones - -| # | Milestone | Status | -|---|---|---| -| M0 | Foundation: core, number formats, formula language, functions, model, calc, XLSX/CSV, engine | ✅ done | -| M1 | Excel look: chrome, ribbon, formula bar, grid, tabs, status bar, control channel | ✅ done (polish continues) | -| M2 | Formatting completeness | ✅ done | -| M3 | Editing power (AutoComplete, spelling, drag-move/copy) | ✅ done | -| M4 | Data (advanced filter, consolidate, what-if) | 🟡 most; Solver, ToolPak and Power Query remain | -| M5 | Formulas tab (trace arrows, watch window, evaluate, error checking) | ✅ done | -| M6 | Conditional formatting manager parity | ✅ done | -| M7 | Charts parity | 🟡 partial; Format pane in, trendlines/axes/error bars remain | -| M8 | Insert & Review | 🟡 partial; ink, icons, comments pane in | -| M9 | Page layout & print | 🟡 most; true Page Layout view remains | -| M10 | PivotTables, Solver, Analysis ToolPak | 🟡 PivotTables in; slicers, Solver, ToolPak remain | -| M11 | Automation (record actions, scripts) | ✅ done | -| M12 | Performance, accessibility, i18n | 🟡 partial | -| M13 | Release & polish | 🟡 tooling ready; needs release secrets | - -## How to measure - -- `cargo xtask parity` — catalog coverage (feature names from Excel's ribbon and menus). -- `cargo test --workspace` — engine, formula, function, XLSX and UI behaviour. -- `cargo run --release -p gridcraft-ui-egui --example snapshot -- --sample sales out.png` — look at the UI offscreen. +| 2026-10-10 | minor | Readiness-by-audience table with hours to ~95% per audience; full number unchanged (additive weighted sum) | +| 2026-10-10 | minor | Added Mainstream practitioner (~50%) and Essentials user (~63%); languages updated for the 10-10 merges (ribbon in ja, zh, ko, pt-BR, ru); localization 5%→10%; full number re-checked (51.6, unchanged) | +| 2026-10-10 | minor | Checked against the alpha gate (six core workflows pass): stays alpha | +| 2026-10-10 | major | Re-measured against Excel for Mac 16.113.4: stage alpha, breadth ~75%, ready ~50%, ~160–240 h to beta, ~700–1,100 h to full parity; restructured to the progress-docs standard; detail moved to `docs/` | +| 2026-10-07 | major | First estimates: catalog 89%, functions ~93%, depth ~65%, ~35 h to alpha, ~215 h to full parity | diff --git a/crates/engine/src/catalog.rs b/crates/engine/src/catalog.rs index 80b9156..d6b67e1 100644 --- a/crates/engine/src/catalog.rs +++ b/crates/engine/src/catalog.rs @@ -1,6 +1,6 @@ //! Excel's ribbon and menu tree (feature names only), used as the parity metric: a catalog //! entry counts as done when a command with its id is registered. `cargo xtask parity` writes -//! `docs/parity.md` from this list. +//! `docs/parity-checklist.md` from this list. /// (id, tab, group, label) pub const CATALOG: &[(&str, &str, &str, &str)] = &[ diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..5695036 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,71 @@ +# Architecture + +> **Last reviewed:** 2026-10-10 · **Last updated:** 2026-10-10 · **Change:** major (created from the code on main; supersedes the local-only plan/architecture.md for committed docs) · **Target:** Microsoft Excel (Microsoft 365) + +How GridCraft is built today. Rules for contributors are in [`AGENTS.md`](../AGENTS.md). + +## Workspace and layering + +An engine-first Cargo workspace. Layering is enforced by `cargo xtask layers`; nothing below L6 +depends on egui, eframe, winit or rfd, so the UI crate is swappable. Line counts are Rust lines +including tests, 2026-10-10. + +| Layer | Crate | Lines | Job | +|---|---|---|---| +| L0 | `core` | ~1.3k | Cell and range addresses (A1, R1C1, sheet-qualified; 1,048,576 × 16,384), `Value`, `CellError`, Excel coercion, 1900/1904 date serials, typed-input parsing | +| L0 | `numfmt` | ~2.1k | Excel number-format codes (sections, conditions, colours, dates, elapsed time, fractions, scientific, fill), General, `TEXT()`; en-US only | +| L1 | `formula` | ~1.7k | Tokenizer, parser, AST, printer (A1 and R1C1), reference adjustment for copy, fill and structural edits | +| L1 | `functions` | ~13.4k | The function library: `FnSpec` registry (name, arity, category, scalar args, signature, description) and pure implementations; automatic array lifting | +| L2 | `model` | ~2.2k | Workbook, sheets, copy-on-write cell store (64-row bands behind `Arc`), interned styles, names, tables, CF, validation, comments, charts, shapes, images, sparklines, print settings, protection | +| L2 | `calc` | ~2.9k | Evaluator (references, names, tables, LET/LAMBDA, special forms like OFFSET/INDIRECT/SUBTOTAL) and dependency-graph recalculation with dynamic arrays, spills and cycle detection; single-threaded | +| L2 | `xlsx` | ~10.7k | XLSX read/write (transitional and strict read), CSV/TSV, XLSB and ODS data import, PivotTable caches, DrawingML charts and drawings; byte slices only (WASM-safe); lenient reader that reports warnings | +| L2 | `pdf` | ~1k | Small PDF 1.7 writer (14 standard fonts, vectors, images) for print and export | +| L3 | `chart` | ~2.9k | Toolkit-free chart layout to drawing primitives, a rasterizer, sparklines | +| L5 | `engine` | ~17.7k | `Session`: open workbooks, selection, history (COW snapshots), clipboard, fill, sort, filter, PivotTables, what-if, print, file I/O (`io.rs`), and the command registry (`cmd/*`, 313 commands) with the Excel ribbon catalog (`catalog.rs`) | +| L6 | `ui-egui` | ~11.6k | Excel-style UI (title bar, QAT, ribbon, formula bar, virtualised grid, editor, tabs, status bar, dialogs, task panes, chart view) and the control channel | +| L6 | `mcp` | ~1.4k | MCP server over stdio (hand-written JSON-RPC), headless or bridged to a running app | +| L7 | `apps/gridcraft`, `apps/gridcraft-cli`, `apps/gridcraft-web` | ~2.2k | Desktop (eframe/wgpu), CLI (`info`, `convert`, `eval`, `cat`, `run`, `commands`, `functions`, `mcp`, `send`), web (WASM via trunk) | +| — | `xtask` | — | `ci`, `parity`, `assets`, `layers`, `wasm`, `version`, `stats` | + +## Data flow + +1. **Every action is a command.** The UI, CLI, control channel and MCP call + `Session::execute(id, params)`. Commands are `CommandSpec { id, label, menu, shortcut, params, + enabled, run, journal, undoable }`; ids follow Excel's ribbon (`home.bold`, `insert.chart`, + `data.sortAscending`) plus primitives (`cell.set`, `selection.set`, `range.setValues`). + `Session::execute` catches escaped panics and restores the workbook (never-crash guard). +2. **Edits** change the model through copy-on-write bands; undo keeps the previous snapshot. +3. **Recalc** marks dependents of changed cells dirty through the dependency graph (with range + nodes for range dependents), evaluates in topological order, spills dynamic arrays and reports + `#SPILL!`/cycles. Volatile functions are always dirty. +4. **Rendering**: the egui grid reads display values (number formats applied in `engine/display.rs`) + for the visible window only; charts render through `crates/chart` primitives. +5. **Files**: `engine/io.rs` sniffs content (XLSX, XLSB, ODS) before trusting the extension and + dispatches to `crates/xlsx`; imports that lose data return warnings shown to the user. + +## Agent control + +- Desktop control channel: `gridcraft --control 7979`, JSON lines on localhost + (`engine.execute`, `ui.screenshot`, pointer and keyboard input…), see + [`control-protocol.md`](control-protocol.md). +- MCP: `gridcraft-cli mcp`, headless or `--connect` to a running app, see [`mcp.md`](mcp.md). +- CLI: [`cli.md`](cli.md). + +## Platforms and builds + +macOS universal, Windows x64/x86/arm64, Linux x86_64/aarch64/riscv64 (AppImage, Flatpak, deb, +rpm, tarball), FreeBSD, and web (WASM; WebGPU or WebGL2). Release workflows in +`.github/workflows/release.yml`; see [`releasing.md`](releasing.md). + +## Known architectural gaps + +- No threading in calc (see [hardware-parity.md](hardware-parity.md)). +- No string catalog or text shaping (see [localization-parity.md](localization-parity.md)). +- XLSX reader builds the whole workbook in memory; no streaming (#175). +- Unmodelled XLSX parts are not carried through a save. + +## Revision history + +| Date | Change | Summary | +|---|---|---| +| 2026-10-10 | major | Created from the code on main: crates, layers, data flow, agent control, known gaps | diff --git a/docs/chart-parity.md b/docs/chart-parity.md new file mode 100644 index 0000000..0577929 --- /dev/null +++ b/docs/chart-parity.md @@ -0,0 +1,82 @@ +# Chart parity + +> **Last reviewed:** 2026-10-10 · **Last updated:** 2026-10-10 · **Change:** major (created from a source audit of the chart model, renderer and XLSX chart parts) · **Target:** Microsoft Excel (Microsoft 365), Excel for Mac 16.113.4 + +Excel's chart types and chart elements against GridCraft. Part of +[target-app-parity.md](target-app-parity.md). **Breadth ~50%, ready ~30%, 40–60 h** (estimated). + +Sources: `crates/model/src/features.rs` (`ChartKind`, `Chart`, `Series`), `crates/chart/src` +(layout and rendering), `crates/xlsx/src/chart.rs` (DrawingML chart parts), merged PRs #62 and #116, +open PRs #158, #161, and issue #190. + +## Chart types + +| Excel type | Excel subtypes | GridCraft | Notes | +|---|---|---|---| +| Column | clustered, stacked, 100% stacked, 3-D clustered/stacked/100%, 3-D column | 3 of 7 | no 3-D | +| Bar | clustered, stacked, 100%, 3-D ×3 | 3 of 6 | no 3-D | +| Line | line, stacked, 100% stacked, with markers ×3, 3-D line | 3 of 7 (line, with markers, stacked) | no 100% stacked; smoothed lines landed (#62) | +| Pie | pie, 3-D pie, pie of pie, bar of pie, doughnut | 2 of 5 (pie, doughnut) | no exploded, pie of pie, bar of pie | +| Area | area, stacked, 100%, 3-D ×3 | 2 of 6 | no 100%, no 3-D | +| X Y (scatter) | markers, smooth lines (±markers), straight lines (±markers) | 2 of 5 | no smooth lines | +| Bubble | bubble, 3-D bubble | 1 of 2 | | +| Stock | high-low-close, open-high-low-close, volume-HLC, volume-OHLC | 1 kind | combo/stock lose their kind in XLSX (PR #158) | +| Surface | 3-D surface, wireframe, contour, wireframe contour | 0 of 4 | | +| Radar | radar, with markers, filled | 1 of 3 | | +| Treemap, Sunburst | 1 each | 2 of 2 | lose their kind in XLSX (PR #161) | +| Histogram, Pareto | 2 | 1 of 2 | no Pareto | +| Box & Whisker | 1 | 1 of 1 | loses its kind in XLSX (PR #161) | +| Waterfall, Funnel | 2 | 2 of 2 | lose their kind in XLSX (PR #161) | +| Filled map | 1 | 0 | needs geographic boundary data (licensing decision) | +| Combo | custom combinations, secondary axis | yes (line on secondary axis) | | +| **Total** | ~60 subtypes | **25 (~42%)** | usage-weighted breadth higher (~65%): column, bar, line, pie and scatter dominate | + +## Chart elements and formatting + +| Element | Excel | GridCraft | +|---|---|---| +| Move and resize the chart object | yes | move yes; **resize broken** (#190) | +| Chart title, axis titles | text, linked to cells, full formatting | text only | +| Legend | position, overlay, formatting, per-entry delete | position only | +| Data labels | value, category, series, percentage, from cells, callouts, position | one on/off flag | +| Gridlines | major/minor per axis, formatting | one on/off flag | +| Axis options | min/max/units, log scale, reverse order, crossing point, display units, date axis, number format | **missing** (auto only) | +| Secondary axis | any series | line series in combo charts | +| Trendlines | linear, exponential, logarithmic, polynomial, power, moving average, equation and R² | **missing** | +| Error bars | fixed, %, standard deviation/error, custom | **missing** | +| Up/down bars, high-low lines, drop lines, series lines | yes | **missing** | +| Data table under the chart | yes | **missing** | +| Per-series / per-point fill, line, marker, effects | Format pane for every element | series colour only; Format Chart pane covers chart-level options | +| Chart styles and colour palettes | ~16 styles × colour sets | style number stored, own palettes | +| Chart sheets | yes | **missing** (skipped with a warning on open) | +| Chart templates (`.crtx`) | yes | **missing** | +| Recommended Charts | yes | partial (Insert ▸ Recommended) | +| Switch Row/Column, Select Data | yes | yes (Switch on charts read from files landed in #116) | +| Sparklines (line, column, win/loss, markers, axis) | yes | line, column, win/loss | +| PivotCharts | yes | **missing** | +| Animation on data change | yes (Windows) | no | + +## XLSX round-trip + +Charts are read from and written to DrawingML chart parts, but only the fields the model holds +survive: anything else (axis scaling, label options, trendlines, per-point formats, chartex +extensions) is lost when GridCraft saves a workbook it opened. That is the main reason charts are +**~30% ready**: a user who opens an Excel workbook with charts and saves it gets simpler charts +back. + +## Work (40–60 h) + +1. Kinds survive XLSX round-trip (merge PRs #158, #161): 2–4 h. Chart resizing (#190): 1–2 h. +2. Preserve unmodelled chart XML on round-trip (keep the original part, patch only edited fields): 6–10 h. +3. Axis options, label options, gridlines per axis, legend formatting: 10–15 h. +4. Trendlines and error bars (maths shared with LINEST/LOGEST/GROWTH): 6–10 h. +5. Per-element Format pane parity, smoothed lines, exploded pie, pie/bar of pie, 100% variants: 8–12 h. +6. 3-D column/bar/pie/area, surface and contour, Pareto: 8–12 h. +7. Chart sheets, PivotCharts, templates: 6–10 h. Filled map: owner decision on boundary data. + +## Revision history + +| Date | Change | Summary | +|---|---|---| +| 2026-10-10 | minor | Smooth lines (#62) and Switch Row/Column on file charts (#116) landed; chart resize bug (#190) | +| 2026-10-10 | major | Created from a source audit: 25 kinds (25 of ~60 subtypes), element gaps, round-trip loss | diff --git a/docs/file-format-parity.md b/docs/file-format-parity.md new file mode 100644 index 0000000..eeb2dd9 --- /dev/null +++ b/docs/file-format-parity.md @@ -0,0 +1,78 @@ +# File-format parity + +> **Last reviewed:** 2026-10-10 · **Last updated:** 2026-10-10 · **Change:** major (created; every format Excel reads or writes, against the code on main) · **Target:** Microsoft Excel (Microsoft 365), Excel for Mac 16.113.4 + +Every format Excel opens or saves, with GridCraft's read and write support, fidelity and tests. +Part of [target-app-parity.md](target-app-parity.md). **File formats: ~50% ready, 80–120 h** +(estimated). + +Excel's list comes from Microsoft's public "File formats that are supported in Excel" +documentation (the Office bundle is off limits under this repo's clean-room rule). GridCraft's +support comes from `crates/engine/src/io.rs` (`FileKind`), `crates/xlsx/src` and the tests in +`crates/xlsx/src/tests/` (round-trip, fixtures, malformed input, CSV, ODS, XLSB, PivotTables). + +## Workbook formats + +| Format | Excel | GridCraft read | GridCraft write | Fidelity / notes | Tests | +|---|---|---|---|---|---| +| `.xlsx` Excel Workbook (transitional) | R/W, native | yes | yes | Cells, shared/array/dynamic formulas, styles, themes, merges, CF, validation, tables, comments and notes, hyperlinks, names, freeze panes, outline, print settings, pictures, shapes, charts (simplified, see [chart-parity.md](chart-parity.md)), sparklines, PivotTables (caches and tables), protection, calc settings. **Not preserved:** unmodelled parts and extensions (form controls, slicer caches, timelines, external links, OLE objects, custom XML, data model, query tables, chart details). Never checked in Excel across a corpus: repair prompts unknown. 100 MB files fail (#175) | `roundtrip.rs`, `fixtures.rs`, `malformed.rs`, `pivot_tests.rs` | +| `.xlsx` Strict Open XML | R/W | yes | no (writes transitional) | Excel also saves transitional by default | fixtures | +| `.xlsm` Macro-Enabled Workbook | R/W | yes | yes, **without macros** | VBA project dropped with a warning; saving as `.xlsm` loses the macros (#6) | — | +| `.xltx` / `.xltm` templates | R/W | yes | partial | Saved with the workbook content type, not the template one; "new from template" behaviour missing | — | +| `.xlsb` Binary Workbook | R/W | **values only** (#101) | no | Names, visibility, numbers, text, booleans, errors, merges, cached formula results; no formulas, formatting, charts, names | `xlsb_tests.rs` | +| `.xls` Excel 97-2003 (BIFF8) | R/W | **no** (#121); recognised and refused with a message since #17 | no | Still common in finance, government and legacy systems | — | +| `.xlt` Excel 97-2003 template | R/W | no | no | | — | +| `.xlam` / `.xla` add-ins | R/W | no | no | VBA; out of scope | — | +| `.xml` XML Spreadsheet 2003 | R/W | no | no | Simple to support | — | +| `.ods` OpenDocument Spreadsheet | R/W | **values only** (#100) | no | Sheets, values, dates, merges, repeated cells, cached formula results; no formulas, formatting, charts; encrypted ODS refused | `ods_tests.rs` | +| Password-encrypted workbooks (Agile/Standard encryption) | R/W | **no**; recognised and refused with a clear message since #17 | no | Common in business; needs AES decryption on top of the new CFB reader (`crates/xlsx/src/cfb.rs`) | — | +| `.xlw` Excel 4.0 workbook, `.wk*`, `.dbf` | open only (some) | no | no | Rare | — | + +## Text and data formats + +| Format | Excel | GridCraft read | GridCraft write | Notes | +|---|---|---|---|---| +| `.csv` UTF-8 / Windows / Mac / MS-DOS | R/W | yes (UTF-8 and UTF-16 BOMs, UTF-8, Windows-1252 fallback; delimiter detection) | yes (UTF-8 without BOM, CRLF) | Excel writes the **displayed** values; we write raw values. No encoding choice on save. Re-import of a single-column export splits text (#127) | +| `.txt` tab-delimited, Unicode text | R/W | yes (`.txt`, `.tsv`, `.tab`) | yes | Text Import Wizard options partly via Text to Columns | +| `.prn` formatted text (space-delimited) | R/W | no | no | | +| `.dif`, `.slk` (SYLK) | R/W | no | no | Small, legacy | +| `.htm` / `.html` web page | R/W (Windows) | yes, via Get Data ▸ From HTML | yes (one sheet as a table) | Formatting not exported | +| `.mht` / `.mhtml` single-file web page | R/W (Windows) | no | no | | +| `.json` | via Power Query | GridCraft's own workbook JSON (debug) and JSON import | GridCraft JSON | Not Power Query's JSON shaping; notes and hyperlinks break export (#126) | +| `.xml` with XML maps | Developer ▸ Import/Export | no | no | | + +## Export and print + +| Format | Excel | GridCraft | Notes | +|---|---|---|---| +| PDF | Save As / Export | yes (own PDF 1.7 writer) | Only the 14 standard PDF fonts, no embedding: **non-Latin text (CJK, Arabic, Devanagari, Thai) does not export**; web build exports without a file prompt (#141) | +| XPS | Windows | no | Low priority | +| Print | yes | yes (via PDF, system dialog on desktop; PR #143 for web) | | +| Images of ranges/charts (Copy as Picture) | yes | chart raster in `crates/chart` | No range-to-image command | + +## Import sources (Get & Transform) + +Excel's Get Data reaches files (Excel, CSV, XML, JSON, PDF, Parquet, folders), databases (SQL +Server, Access, ODBC, …), web pages, SharePoint and online services, through Power Query. +GridCraft imports CSV/TSV, JSON and HTML tables only, with no query editor, no connections and no +refresh. Counted under features (Get & Transform, ~10% ready), not here. + +## Work (80–120 h) + +| Work | Hours | +|---|---| +| Real-world XLSX corpus run (craftrules test-corpora standard), and confirm Excel opens our output with no repair prompt (owner runs Excel) | 15–25 | +| Preserve unmodelled XLSX parts and extensions on round trip (pass-through with relationship fix-up) | 10–15 | +| Streaming XLSX reader for very large files (#175), part-size limits that degrade instead of failing | 10–15 | +| Legacy `.xls` (BIFF8) import: cells, formulas, styles, names; then write | 20–30 | +| Encrypted workbooks: open with password prompt, save with password (#11) | 8–12 | +| XLSB and ODS: formulas and formatting on import; then write | 10–15 | +| CSV/text: displayed-value export, encoding choice, `.prn`, `.dif`, `.slk`, XML Spreadsheet 2003 | 5–8 | +| PDF: embed subsetted system fonts so every script exports | (counted in [localization](localization-parity.md) script work) | + +## Revision history + +| Date | Change | Summary | +|---|---|---| +| 2026-10-10 | minor | Encrypted and `.xls` files are now recognised and refused with a message (#17) | +| 2026-10-10 | major | Created: every Excel format with our read/write support; XLSB and ODS values-only imports recorded; `.xls`, encryption and large files flagged as beta gates | diff --git a/docs/function-parity.md b/docs/function-parity.md new file mode 100644 index 0000000..8ff9d49 --- /dev/null +++ b/docs/function-parity.md @@ -0,0 +1,100 @@ +# Function parity: worksheet functions and formulas + +> **Last reviewed:** 2026-10-10 · **Last updated:** 2026-10-10 · **Change:** major (created; measured against Microsoft's published Excel function list) · **Target:** Microsoft Excel (Microsoft 365), Excel for Mac 16.113.4 + +Excel's worksheet functions, category by category, against GridCraft's function library. Part of +[target-app-parity.md](target-app-parity.md); gaps feed [gaps.md](gaps.md). + +## How this is measured + +- **Excel's list (523):** Microsoft's "Excel functions (alphabetical)" support page, fetched and + parsed on 2026-10-10 (506 rows with their category and the Excel version that introduced + them), plus 14 text functions the page lists under combined entries (FIND/FINDB, LEFT/LEFTB, + LEN/LENB, MID/MIDB, REPLACE/REPLACEB, RIGHT/RIGHTB, SEARCH/SEARCHB), BETA.INV, and COPILOT and + PY (Microsoft 365 functions not on that page when fetched). +- **Ours (501):** every function spec in `crates/functions/src/*.rs` (`f!("NAME", …)`) plus the + evaluator's special forms in `crates/calc/src/eval.rs` (`SPECIAL_FUNCTIONS`: IF, IFS, CHOOSE, + OFFSET, INDIRECT, INDEX, SUBTOTAL, AGGREGATE, TEXT, LET, LAMBDA, MAP, REDUCE, SCAN, BYROW, BYCOL, + MAKEARRAY…), excluding the test-only `ADD2`. Every one is an Excel name. +- **Working** excludes stubs that return an error by design: the 7 CUBE functions (`#N/A`, no + cube connections) and WEBSERVICE and FILTERXML (`#VALUE!`). Excel for Mac also lacks + WEBSERVICE and FILTERXML; Excel for Windows has them. +- The measurement is **presence**. Depth (edge cases matching Excel) is estimated below. + +## Coverage + +**Measured: 501 / 523 by name (95.8%); 492 / 523 working (94.1%).** + +| Category | Excel | Ours | Working | % working | Missing | +|---|---|---|---|---|---| +| Statistical | 111 | 107 | 107 | 96% | FORECAST.ETS, FORECAST.ETS.CONFINT, FORECAST.ETS.SEASONALITY, FORECAST.ETS.STAT | +| Math and trigonometry | 80 | 79 | 79 | 99% | PERCENTOF | +| Financial | 55 | 51 | 51 | 93% | ODDFPRICE, ODDFYIELD, ODDLPRICE, ODDLYIELD | +| Engineering | 54 | 54 | 54 | 100% | — | +| Text | 50 | 47 | 47 | 94% | BAHTTEXT, DETECTLANGUAGE, TRANSLATE | +| Lookup and reference | 40 | 36 | 36 | 90% | GETPIVOTDATA, IMAGE, RTD, TRIMRANGE | +| Compatibility | 40 | 40 | 40 | 100% | — | +| Date and time | 25 | 25 | 25 | 100% | — | +| Information | 22 | 21 | 21 | 95% | STOCKHISTORY | +| Logical | 19 | 19 | 19 | 100% | — | +| Database | 12 | 12 | 12 | 100% | — | +| Cube | 7 | 7 | 0 | 0% | (all 7 are `#N/A` stubs) | +| Web | 3 | 3 | 1 | 33% | (WEBSERVICE, FILTERXML are stubs; ENCODEURL works) | +| Add-in and Automation | 3 | 0 | 0 | 0% | CALL, EUROCONVERT, REGISTER.ID | +| AI and Python | 2 | 0 | 0 | 0% | COPILOT, PY | +| **Total** | **523** | **501** | **492** | **94.1%** | 22 missing, 9 stubs | + +By the Excel version that introduced them (working / total): before 2010 342 / 360, 2010 +56 / 56, 2013 49 / 51, 2016 1 / 5, 2019 6 / 6, 2021 11 / 11, 2024 22 / 23, Microsoft 365 5 / 11. +Dynamic-array and LAMBDA-era functions (FILTER, SORT, UNIQUE, XLOOKUP, VSTACK, TAKE, GROUPBY, +PIVOTBY, REGEXTEST…) are all present. + +### Scope of what's missing + +| Function(s) | In scope? | Estimate | Note | +|---|---|---|---| +| FORECAST.ETS family (4) | yes | 4–6 h | AAA exponential smoothing with seasonality detection; needed for Forecast Sheet too | +| ODDFPRICE, ODDFYIELD, ODDLPRICE, ODDLYIELD | yes | 2–4 h | Odd first/last period bond maths | +| GETPIVOTDATA | yes | 2–3 h | Needs the pivot engine's result cache; also the "Generate GetPivotData" option | +| TRIMRANGE, PERCENTOF, BAHTTEXT | yes | 1–2 h | TRIMRANGE also implies the `.:` trim-ref operators | +| IMAGE | yes | 3–5 h | Pictures in cells (see PR #105); fetching URLs needs a privacy decision | +| EUROCONVERT | yes | 0.5 h | Fixed conversion table | +| CUBE* (7), WEBSERVICE, FILTERXML | partly | 4–8 h | FILTERXML can work offline; CUBE needs an OLAP/data-model source | +| TRANSLATE, DETECTLANGUAGE, STOCKHISTORY, COPILOT, PY | no (cloud) | — | Microsoft cloud services; open equivalents only by owner decision | +| CALL, REGISTER.ID, RTD | no | — | Native DLL/COM calls; not portable or safe | + +## Formula language + +| Feature | Status | +|---|---| +| A1 and R1C1 references, absolute/relative/mixed, F4 cycling | done | +| 3-D references (`Sheet1:Sheet3!A1`) | done; endpoint-deletion bug (#140) | +| Structured references (`Table1[Col]`, `[#Totals]`, `@`) | done | +| Defined names (workbook and sheet scope), Create from Selection | done | +| Dynamic arrays, spill, `#SPILL!`, spill operator `A1#` | done; stale-spill bugs (#133, #139; PRs #148, #157) | +| Implicit intersection `@`, legacy CSE array formulas | done; legacy array range fill (PR #156) | +| LET, LAMBDA, named LAMBDAs, ISOMITTED, MAP/REDUCE/SCAN/BYROW/BYCOL/MAKEARRAY | done | +| Iterative calculation for circular references | cycle detection done; the Enable Iterative Calculation setting is stored and saved to XLSX, but the calc engine does not iterate (circular references stay unresolved) | +| 15-significant-digit comparison semantics | **missing** (#57: `=0.1+0.2=0.3` is FALSE) | +| External workbook references (`[Book.xlsx]Sheet1!A1`) | parsed; links dropped on open, no update | +| Localized function names and `;` separators | **missing** (#45); en-US only | +| Error values | the seven classic errors plus `#SPILL!`, `#CALC!`, `#GETTING_DATA` done; `#FIELD!`, `#BLOCKED!`, `#CONNECT!`, `#BUSY!`, `#UNKNOWN!`, `#PYTHON!` missing (minor: they come from data types, cloud and Python features) | + +## Depth (estimated) + +**~82% ready.** The library is broad and has 96 test functions in `crates/functions` with many +assertions each, but there is no conformance suite against Excel-computed results, and user +reports keep finding edge cases: MIN() with no arguments (#138), COUNTBLANK past the used range +(#137), ROUND at 15 digits and DATE(1900,2,29) (fixed 10-09), SUMIF sum-range sizing (fixed +10-09). Statistical distributions and financial functions with iterative solvers (RATE, IRR, +XIRR, YIELD) are the highest-risk for last-digit differences. + +Work to close (18–30 h in total): the in-scope missing functions (12–20 h with the table above), +an oracle corpus of Excel-computed results per function (owner runs Excel on generated +workbooks; results checked in as data, not Excel files) and fixing what it finds (6–10 h). + +## Revision history + +| Date | Change | Summary | +|---|---|---| +| 2026-10-10 | major | Created: 501 / 523 by name, 492 working, per category, against Microsoft's published list | diff --git a/docs/gaps.md b/docs/gaps.md new file mode 100644 index 0000000..aa752b8 --- /dev/null +++ b/docs/gaps.md @@ -0,0 +1,154 @@ +# Gaps + +> **Last reviewed:** 2026-10-10 · **Last updated:** 2026-10-10 · **Change:** major (created from the full re-measure against Excel for Mac 16.113.4 and the issue tracker) · **Target:** Microsoft Excel (Microsoft 365) + +Every known shortfall against Excel, one entry each, ranked by user impact (what blocks someone +using GridCraft for real work first). This is the work list: pick from the top, check the open +PRs first (50 open on 2026-10-10; several already address entries here), and update the entry +when you land work. Estimates are Opus 5.5 agent-hours. Area detail lives in the linked parity +docs; the summary is in [target-app-parity.md](target-app-parity.md). + +Kinds: **F** feature · **U** UI/UX · **FF** file format · **H** hardware · **L** localization · +**P** performance · **S** stability. + +## Beta blockers + +No alpha blockers: every core workflow passes the [alpha gate](roadmap.md#alpha-gate). + + +### 1. XLSX output not proven in Excel or on real files (FF) +- **Missing:** a run over a real-world XLSX corpus, and confirmation that Excel opens what we save + with no repair prompt (PivotTables, charts, CF, validation, dynamic arrays, tables). +- **Evidence:** round-trip tests cover our own files only (`crates/xlsx/src/tests/`); PivotTable + round-trip noted as "unverified in real Excel" since 10-07; #64 (dynamic-array flag) shows the + class of bug. +- **Impact:** the main format; a repair prompt or silent loss destroys trust. +- **Estimate:** 15–25 h, plus owner time in Excel. [file-format-parity.md](file-format-parity.md) + +### 2. Large workbooks don't open; recalc is single-threaded (P, H) +- **Missing:** streaming read for ~100 MB XLSX; multi-threaded recalc; 100k-dependent edit under + 100 ms (was ~0.4 s); whole-sheet operations bounded. +- **Evidence:** #175; no threading in `crates/calc`; PR #152 (whole-sheet Fill/Remove Duplicates + out of memory), PR #151 (current region past 10,000 rows). +- **Impact:** finance and data users routinely have big workbooks. +- **Estimate:** 25–40 h. [target-app-parity.md](target-app-parity.md#performance), [hardware-parity.md](hardware-parity.md) + +### 3. Unmodelled XLSX content is dropped on save (FF) +- **Missing:** pass-through of parts and extensions we don't model (form controls, slicers, + timelines, external links, OLE objects, custom XML, query tables, data model, chart details). +- **Evidence:** reader warns and skips (`crates/xlsx/src/read.rs`); external links "not supported". +- **Impact:** open-edit-save silently simplifies colleagues' workbooks. +- **Estimate:** 10–15 h. [file-format-parity.md](file-format-parity.md) + +### 4. Charts lose type and options on round trip; shallow chart model (F, FF) +- **Missing:** kinds that survive XLSX (stock, combo, histogram, box, waterfall, funnel, treemap, + sunburst), axis scaling, label options, trendlines, error bars, per-point formatting. +- **Evidence:** `Chart` holds only title, legend position, two flags and axis titles + (`crates/model/src/features.rs`); PRs #158, #161 open; charts can't be resized (#190). Smooth lines (#62) and Switch Row/Column (#116) landed. +- **Impact:** charts are in most business workbooks. +- **Estimate:** 25–35 h for beta (40–60 h full). [chart-parity.md](chart-parity.md) + +### 5. Text in non-Latin scripts doesn't render or export (L) +- **Missing:** CJK font fallback, complex shaping (Arabic, Devanagari, Thai), bidi, non-Latin PDF. +- **Evidence:** system-font fallback for CJK, Thai and Hebrew landed in #38 (closed #32); #142 + (Chinese text) awaits confirmation; #54 (symbols as boxes on Fedora); no shaping for Arabic or + Devanagari; PDF writer uses 14 standard fonts only. +- **Impact:** blocks most of the world's users even with an English UI. +- **Estimate:** 12–20 h. [localization-parity.md](localization-parity.md) + +### 6. Calculation correctness bugs (F) +- **Missing:** 15-significant-digit equality; spill updates after structural edits and cleared + blockers; 3-D span deletion; qualified names after sheet rename; iterative calculation. +- **Evidence:** #57, #133, #139, #140, #134; Enable Iterative Calculation stored but unused; + PRs #148, #155, #156, #157. +- **Impact:** wrong numbers are worse than missing features. +- **Estimate:** 10–15 h. [function-parity.md](function-parity.md#formula-language) + +### 7. No legacy `.xls`; no password-protected workbooks (FF) +- **Evidence:** #121. Since #17 (closed #11) both are recognised through a CFB sniff and refused with a clear message, but neither opens. +- **Impact:** common in finance, government and anything older than 2007; encrypted files are + routine in business. +- **Estimate:** 28–42 h (`.xls` read 20–30, encryption 8–12). [file-format-parity.md](file-format-parity.md) + +### 8. PivotTables: no slicers, calculated fields, PivotCharts; unverified in Excel (F) +- **Evidence:** `parity-checklist.md` missing `insert.slicer`, `insert.timeline`, + `insert.pivotChart`, `pivot.calculatedField`, `table.insertSlicer`; GETPIVOTDATA missing. +- **Impact:** pivots are the analyst's main tool. +- **Estimate:** 20–30 h for beta (25–40 h full). + +### 9. Keyboard-first users: key tips, shortcuts, context menus (U) +- **Evidence:** #33, #49 (key tips: initial Home-tab support landed in #43 on 10-10, the rest of the ribbon not yet), #110, #21 (Insert Copied Cells), #28 (selection), + 59 command shortcuts vs Excel's 200+. +- **Estimate:** 12–20 h. [ui-parity.md](ui-parity.md) + +### 10. Crashes and freezes reported from the field (S) +- **Evidence:** #120 (Intel UHD crash on Windows), #117 (error on close, macOS), #166 (freeze opening + from Finder; PRs #164, #167), #76 (flashing on Windows 11), #130 (caught panic in table styles). +- **Estimate:** 8–12 h plus an autosave/recovery soak. + +## After beta + +### 11. No localization at all (L) +- Ribbon-only catalog in five languages (#31, #104, #82; ~12% of strings each); dialogs, menus and + messages English; en-US function names and separators (#45); German in PR #163. **Estimate:** + 100–165 h including #5. [localization-parity.md](localization-parity.md) + +### 12. Get & Transform, external data, data model (F) +- No Power Query editor, connections, refresh, From Web/database/folder sources, relationships or + data model (`data.fromWeb`, `data.relationships` missing). **Estimate:** 60–100 h. + +### 13. Analysis tools: Solver, Analysis ToolPak, Forecast Sheet (F) +- `data.solver`, `data.analysisToolPak`, `data.forecastSheet` missing; FORECAST.ETS family missing. + **Estimate:** 22–35 h. + +### 14. Page Layout view and print polish (U, F) +- No paper view with rulers and in-place header/footer editing; web print exports only (#141, PR + #143). **Estimate:** 12–20 h. + +### 15. Remaining functions and an oracle suite (F) +- 22 missing, 9 stubs; no Excel-computed oracle corpus; #137, #138. **Estimate:** 18–30 h. + [function-parity.md](function-parity.md) + +### 16. Collaboration and review (F) +- No co-authoring, Show Changes, Allow Edit Ranges, comment navigation, notes ↔ comments + conversion; cloud storage requested (#86). **Estimate:** 35–55 h (co-authoring scope needs the owner). + +### 17. Insert objects (F) +- SmartArt, WordArt, equations, signature line, objects, 3-D models, screenshot; 8 shape kinds vs + ~170; pictures in cells (#61, PR #105). **Estimate:** 25–40 h. + +### 18. Accessibility (U) +- AccessKit on, but no accessible grid/ribbon tree, no high contrast, no checker. **Estimate:** 12–18 h. + [ui-parity.md](ui-parity.md#accessibility) + +### 19. XLSB/ODS beyond values; minor formats (FF) +- XLSB and ODS import values only, no write; no `.prn`, `.dif`, `.slk`, XML Spreadsheet 2003; CSV + writes raw instead of displayed values; templates saved with the workbook content type. + **Estimate:** 15–23 h. + +### 20. Multiple windows; pen pressure (H) +- One window (#162, PR #171); no pressure or tilt in ink. **Estimate:** 10–14 h. + [hardware-parity.md](hardware-parity.md) + +### 21. Automation and add-ins (F) +- VBA out of scope (dropped on open, #6); no Office Scripts compatibility; no plugin or custom + function API. **Estimate:** 25–40 h plus an owner decision. + +### 22. AI features (F) +- No in-app assistant, natural-language formulas or Analyze Data; agent control via MCP is + already strong. **Estimate:** 30–50 h; model choice needs the owner. + +### 23. Mobile (platform) +- No iOS, iPadOS or Android layout. **Estimate:** 30–60 h. + +### 24. Fonts and look (U) +- Font weights beyond regular/bold (#168), system font list (#4), Calibri metrics (#29), macOS + chrome (#169, #170), Linux title bar (#54), icon consistency across apps (#173). **Estimate:** 7–12 h. + +## Revision history + +| Date | Change | Summary | +|---|---|---| +| 2026-10-10 | minor | Updated for the 10-10 merges (#17, #31, #38, #62, #82, #104, #116) and the new chart resize bug (#190) | +| 2026-10-10 | minor | Noted that no gap blocks the alpha gate | +| 2026-10-10 | major | Created: 24 ranked gaps with evidence, from the full re-measure and the 60 open issues | diff --git a/docs/hardware-parity.md b/docs/hardware-parity.md new file mode 100644 index 0000000..083977d --- /dev/null +++ b/docs/hardware-parity.md @@ -0,0 +1,23 @@ +# Hardware parity + +> **Last reviewed:** 2026-10-10 · **Last updated:** 2026-10-10 · **Change:** major (created from a source audit) · **Target:** Microsoft Excel (Microsoft 365), Excel for Mac 16.113.4 + +The hardware Excel uses, per platform, against GridCraft. Part of +[target-app-parity.md](target-app-parity.md). **Hardware: ~40% ready, 25–40 h** (estimated). + +| Hardware feature | Excel | GridCraft (macOS · Windows · Linux · BSD · web) | Gap and estimate | +|---|---|---|---| +| Multi-core recalculation | Multi-threaded recalculation on all cores (Windows and Mac), configurable thread count | Single-threaded everywhere (no threading in `crates/calc`) | Parallel recalc of independent dependency chains on native builds; WASM stays single-threaded or uses workers later: 12–18 h | +| GPU rendering of the grid and charts | DirectX / Metal accelerated drawing | wgpu: Metal · DirectX 12 (default since 10-08) · Vulkan/GL · Vulkan/GL · WebGPU or WebGL2 | At parity in kind. Driver problems: Intel UHD crash on Windows (#120), screen flashing on Windows 11 (#76): 3–6 h | +| Pen and touch (Draw tab) | Pen pressure and tilt, eraser end, touch mode, Ink to Shape, ink replay | Pen, highlighter, eraser, Ink to Shape with mouse/pen input; **no pressure or tilt**, no touch mode | Pressure-sensitive strokes where winit reports force; touch-friendly ribbon spacing: 4–6 h | +| Trackpad and mouse | Smooth scrolling, pinch zoom, horizontal scroll, Magic Mouse | Smooth scrolling and zoom via egui | Verify pinch zoom on each platform: 1–2 h | +| Multiple windows and monitors | One window per workbook, New Window for the same workbook, per-monitor DPI | One window; multiple workbooks switch inside it (#162; PR #171) | Native window per workbook, New Window, Arrange All across monitors: 6–8 h | +| High-DPI and display scaling | yes | yes (display scale matched to desktop density) | — | +| Accessibility hardware (screen readers, braille displays, switch control) | Narrator, JAWS, NVDA, VoiceOver | AccessKit enabled in eframe; grid cells and ribbon not yet exposed as an accessible tree | Counted under UI ([ui-parity.md](ui-parity.md)) | +| Printers | System print with driver options | Desktop prints through the system dialog via PDF; web exports only | Counted under print | + +## Revision history + +| Date | Change | Summary | +|---|---|---| +| 2026-10-10 | major | Created: single-threaded calc, wgpu rendering, no pen pressure, single window | diff --git a/docs/localization-parity.md b/docs/localization-parity.md new file mode 100644 index 0000000..3a8a991 --- /dev/null +++ b/docs/localization-parity.md @@ -0,0 +1,77 @@ +# Localization parity + +> **Last reviewed:** 2026-10-10 · **Last updated:** 2026-10-10 · **Change:** minor (re-measured after the 10-10 language and font-fallback merges) · **Target:** Microsoft Excel (Microsoft 365), Excel for Mac 16.113.4 + +Per-language status against Excel, which ships its UI in dozens of languages (Windows language +packs cover 100+), with localized function names, argument separators, number and date formats, +right-to-left sheets and full complex-script support. Part of +[target-app-parity.md](target-app-parity.md). **Localization: ~10% ready, 100–165 h** (estimated). + +## Where we are (measured from source on `main`, after the 2026-10-10 merges) + +- **A first catalog exists, for the ribbon only.** `crates/ui-egui/src/i18n.rs` (merged 10-10 in + #31, #104, #82) adds an interface-language preference that defaults to the system language + (closes #20) and a View-tab switcher, with English-keyed lookup tables: Japanese 268 labels, + Simplified Chinese, Korean, Russian and Brazilian Portuguese 266 each. The tables are used by + the ribbon, sheet tabs and widgets (`ribbon.rs`, `tabs.rs`, `widgets.rs`); dialogs, menus, + context menus, task panes, status messages, command labels and function descriptions are still + English literals. Untranslated labels fall back to English. +- **About 2,200 user-visible strings** in all (heuristic source scan: ~1,700 UI and command + strings plus ~500 function descriptions), so each shipped language covers **~12%** (measured + count / estimated total). +- **en-US only formulas and formats.** Function names, `,` argument separator, `.` decimal + separator, en-US number and date formats (`crates/numfmt` says "en-US only"). Users ask for + localized function names and `;` separators (#45). German with localized numbers and formulas + is in PR #163 (open). +- **Script support.** System-font fallback for CJK, Thai and Hebrew landed in #38 (closes #32; + #142 is still open pending confirmation). There is no complex-text shaping: Arabic and + Devanagari don't join or reorder, and there is no bidirectional layout. **Sheet Right-to-Left** + is a stored flag (`view.rightToLeft`) but the grid doesn't mirror (#146). IME input goes + through egui/winit and is unverified for Chinese, Japanese and Korean. +- **PDF export** uses only the 14 standard PDF fonts: non-Latin text cannot export. + +## Languages + +UI strings translated are measured counts against the ~2,200 estimate. Estimates to `full` +include the rest of the catalog work below (10–20 h, counted once), localized function names, +separators, number/date formats, machine translation with agent review, and script work. + +| Language | Code | UI strings translated | Dialogs / tooltips / help | Script support | Native review | Status | Estimate to full | +|---|---|---|---|---|---|---|---| +| English | en | ~2,200 / ~2,200 (100%, source) | yes | Latin: yes | yes | full | — | +| Simplified Chinese (Mandarin) | zh-Hans | 266 (~12%) | no | CJK system-font fallback (#38); IME unverified; PDF can't export | no | menus only | 8–13 h | +| Spanish | es | 0 (0%) | no | Latin: yes | no | none | 6–10 h | +| Hindi | hi | 0 (0%) | no | Devanagari: **no shaping** | no | none | 12–18 h | +| Arabic | ar | 0 (0%) | no | **no shaping, no RTL UI, RTL sheet flag not rendered** (#146) | no | none | 25–35 h | +| French | fr | 0 (0%) | no | Latin: yes | no | none | 6–10 h | +| Portuguese | pt-BR | 266 (~12%) | no | Latin: yes | no | menus only | 4–8 h | +| Indonesian | id | 0 (0%) | no | Latin: yes | no | none | 5–8 h | +| Japanese | ja | 268 (~12%) | no | CJK system-font fallback; IME unverified; no furigana display | no | menus only | 8–12 h | +| German | de | 0 (0%; PR #163 open) | no | Latin: yes | no | none | 6–10 h | +| Korean | ko | 266 (~12%) | no | Hangul via the CJK fallback; IME unverified | no | menus only | 6–10 h | +| Vietnamese | vi | 0 (0%) | no | Latin with stacked diacritics: unverified | no | none | 6–10 h | + +Other shipped languages: Russian (ru), 266 labels (~12%), menus only. + +**Total:** catalog work 10–20 h + languages 92–144 h ≈ **100–165 h**. Parallelizes almost fully +once the catalog covers dialogs and commands. **Needs a human:** native-speaker review of every +language (none so far) and of localized function names. + +## Infrastructure (do first) + +1. Extend the catalog from the ribbon to every user-visible string (dialogs, menus, task panes, + status and error messages, command labels, function descriptions), with a missing-key check + in `cargo xtask ci`. Language switching and the system-language default already exist (#31). +2. Locale-aware formulas: localized function-name tables and separators at the formula-bar + boundary only (files keep en-US invariant names), locale number and date formats, list + separators in CSV. +3. Text shaping and fallback: a shaping engine for grid, editor and PDF text (Arabic, Devanagari, + Thai), system font fallback for CJK, bidirectional runs, and a real right-to-left sheet layout; + embedded subset fonts in PDF. + +## Revision history + +| Date | Change | Summary | +|---|---|---| +| 2026-10-10 | minor | Re-measured after #31, #104, #82, #38 merged: ribbon translated into ja, zh, ko, pt-BR and ru (266–268 labels, ~12%), system-language default, CJK/Thai/Hebrew font fallback; ~10% ready, 100–165 h | +| 2026-10-10 | major | Created: English only, no catalog, ~2,200 strings, script-support gaps, open language PRs | diff --git a/docs/parity.md b/docs/parity-checklist.md similarity index 98% rename from docs/parity.md rename to docs/parity-checklist.md index 0a88314..e98835d 100644 --- a/docs/parity.md +++ b/docs/parity-checklist.md @@ -1,8 +1,8 @@ -# Excel parity +# Excel parity checklist -Each entry is an Excel ribbon or menu command (feature names only). It counts as implemented when GridCraft registers a command with the same id. +Each entry is an Excel ribbon or menu command (feature names only). It counts as implemented when GridCraft registers a command with the same id. This measures breadth only; the overall assessment (depth, fidelity, effort) is in [target-app-parity.md](target-app-parity.md). **Overall: 258 / 290 commands implemented (89.0%).** diff --git a/docs/releasing.md b/docs/releasing.md index 0e0abfa..9f4e954 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -56,7 +56,7 @@ The pipeline references crates that don't exist yet; the first release run fails artifact and `SHA256SUMS.txt`. The notes are generated from the merged PRs. 4. **Check it.** Download an installer or two and read the job summaries. Any `::warning::` there means a signing secret was missing and that artifact is unsigned. -5. **Add the parity delta** to the notes: `git diff v v -- docs/parity.md` +5. **Add the parity delta** to the notes: `git diff v v -- docs/parity-checklist.md` (regenerated by `cargo xtask parity`). 6. **Publish** the draft in the GitHub UI. Publishing creates the `v0.2.0` tag. Versions with a pre-release suffix (`-rc.1`) are marked as pre-releases. diff --git a/docs/roadmap.md b/docs/roadmap.md new file mode 100644 index 0000000..b0c8eb8 --- /dev/null +++ b/docs/roadmap.md @@ -0,0 +1,117 @@ +# Roadmap detail + +> **Last reviewed:** 2026-10-10 · **Last updated:** 2026-10-10 · **Change:** major (created; milestones moved here from ROADMAP.md, beta gates added) · **Target:** Microsoft Excel (Microsoft 365) + +Forward-looking plan. The one-page summary is [`ROADMAP.md`](../ROADMAP.md); the ranked work +list is [`gaps.md`](gaps.md); numbers and method are in +[`target-app-parity.md`](target-app-parity.md). Estimates are Opus 5.5 agent-hours. + +## Current focus + +1. **Review and land the open PR queue** (50 PRs on 2026-10-10): recalc and spill fixes (#148, + #155, #156, #157), whole-sheet and large-range fixes (#151, #152, #153, #154), chart kinds + (#158, #161), macOS document open (#164, #167), German UI, numbers and formulas (#163), + 15-digit comparison (#187). 8–15 h. Language work should extend the new `i18n` catalog past the + ribbon rather than add scattered literals. +2. **XLSX on real files** (gaps #1, #3): corpus run plus Excel opening our output. +3. **Large workbooks and multi-threaded recalc** (gap #2). + +## Alpha gate + +The core workflows a typical Excel user runs every day, checked end to end on the main platform +(macOS desktop), including saving and reopening the work. Any "no", or a "partial" that blocks the +workflow, would make GridCraft pre-alpha. + +| Core workflow | Works end to end? | Evidence | Hours to pass | +|---|---|---|---| +| Build a model: enter data and formulas, recalc, save XLSX, reopen | yes | 492 working functions, dynamic arrays, LET/LAMBDA, names, tables; XLSX round-trip tests (`crates/xlsx/src/tests/roundtrip.rs`). Edge-case bugs (#57 15-digit equality, stale spills #133/#139) give wrong results in specific cases, not in the workflow | 0 (fixes are beta work, gap #6) | +| Open a colleague's XLSX, edit, save, hand it back | partial, not blocking | Typical workbooks open and save with cells, styles, CF, validation, tables, names and pivots; unmodelled parts are dropped with a warning (gap #3); Excel-side repair prompts unverified (gap #1); ~100 MB files fail (#175) | 0 for alpha (gaps #1–#3 are beta gates) | +| Format and present: number formats, styles, conditional formatting, print or PDF | yes | Full number-format language, 47 cell styles, all CF kinds, Page Break Preview, PDF export and printing. PDF can't carry non-Latin text (gap #5) | 0 | +| Analyze: sort, filter, tables, PivotTable | yes | Multi-level sort, AutoFilter, tables with totals, PivotTables with field list, layouts, grouping, refresh and XLSX round-trip. Slicers and calculated fields missing (gap #8) | 0 | +| Chart the data | partial, not blocking | Column, bar, line, pie, area, scatter and combo charts are created, edited and survive save and reopen; histogram, box, waterfall, funnel, treemap, sunburst and stock lose their kind in XLSX (fix in PRs #158, #161); no axis options or trendlines (gap #4) | 0 for alpha (2–4 h to merge the kind fixes) | +| Import and export CSV | yes | Encoding and delimiter detection on read, CSV/TSV write; exports raw rather than displayed values (gap #19) | 0 | + +**Passes:** every core workflow works end to end on macOS with save and reopen; the two partial +rows lose fidelity only on less common content (very large files, unmodelled parts, advanced +chart kinds), which are beta gates, not alpha blockers. Ready for real work ~50% is inside the +40–75% alpha band. + +## Beta gates + +Beta means: ~75% ready for real work, opens and saves XLSX reliably, remaining gaps are known bugs +and edge features. Each gate links its gap. + +| Gate | Gap | Hours | +|---|---|---| +| XLSX proven on a real-world corpus; Excel opens our output without repair | #1 | 15–25 | +| Unmodelled XLSX parts preserved on save | #3 | 10–15 | +| 100 MB workbooks open; 1M rows usable; multi-threaded recalc; 100k-edit recalc < 100 ms | #2 | 25–40 | +| Charts: kinds and options survive round trip; axes, trendlines, error bars | #4 | 25–35 | +| Text in every script renders and exports | #5 | 12–20 | +| Calculation correctness bugs closed; iterative calculation | #6 | 10–15 | +| `.xls` import, password-protected workbooks | #7 | 28–42 | +| PivotTables: slicers, calculated fields, PivotCharts, verified in Excel | #8 | 20–30 | +| Keyboard: key tips, shortcut audit, context menus | #9 | 12–20 | +| Field crashes and freezes closed; autosave/recovery soak | #10 | 8–12 | +| **Total** | | **~165–255 (≈160–240 after overlap with the PR queue)** | + +With 4–5 agents and an integrator, about 40–60 wall-clock hours. Needs the owner: running Excel +to check our files, and Windows machines with the reported GPU drivers. + +## Milestones + +| # | Milestone | Status | +|---|---|---| +| M0 | Foundation: core, number formats, formula language, functions, model, calc, XLSX/CSV, engine | done | +| M1 | Excel look: chrome, ribbon, formula bar, grid, tabs, status bar, control channel | done (polish continues) | +| M2 | Formatting completeness | done | +| M3 | Editing power (AutoComplete, spelling, drag-move/copy) | done | +| M4 | Data (advanced filter, consolidate, what-if) | most; Solver, ToolPak and Power Query remain | +| M5 | Formulas tab (trace arrows, watch window, evaluate, error checking) | done | +| M6 | Conditional formatting manager parity | done | +| M7 | Charts parity | partial; Format pane in; axes, trendlines, error bars, round-trip remain | +| M8 | Insert & Review | partial; ink, icons, comments pane in | +| M9 | Page layout & print | most; Page Layout view remains | +| M10 | PivotTables, Solver, Analysis ToolPak | PivotTables in; slicers, Solver, ToolPak remain | +| M11 | Automation (record actions, scripts) | done | +| M12 | Performance, accessibility, i18n | partial; i18n not started | +| M13 | Release & polish | releases shipping (v0.2.0–v0.4.0, signed) | +| M14 | **Beta gates** (table above) | not started as a milestone; parts in open PRs | +| M15 | Localization infrastructure and the twelve languages | started: ribbon catalog in ja, zh, ko, pt-BR, ru (#31, #104, #82); German in PR #163 | +| M16 | Get & Transform, data model | not started | + +## After beta (ranked) + +| Work | Gap | Hours | +|---|---|---| +| Localization: catalog past the ribbon, then twelve languages | #11 | 100–165 | +| Get & Transform and the data model | #12 | 60–100 | +| Solver, Analysis ToolPak, Forecast Sheet | #13 | 22–35 | +| Remaining functions, oracle suite | #15 | 18–30 | +| Collaboration and review | #16 | 35–55 | +| Insert objects | #17 | 25–40 | +| Accessibility | #18 | 12–18 | +| Page Layout view, print polish | #14 | 12–20 | +| Mobile layout | #23 | 30–60 | +| AI features with local models | #22 | 30–50 | +| Plugin / custom-function API | #21 | 25–40 | + +## Measuring + +- `cargo xtask parity` regenerates [`parity-checklist.md`](parity-checklist.md) (ribbon + catalog vs registered commands); `cargo xtask ci` checks it is current. +- `cargo test --workspace`: engine, formula, function, XLSX and UI behaviour. +- `cargo run --release -p gridcraft-ui-egui --example snapshot -- --sample sales out.png`: look at + the UI offscreen. +- Function coverage: the script method in [function-parity.md](function-parity.md). A + `cargo xtask functions` that diffs the registry against a checked-in Excel name list would make + it a CI number (1–2 h). +- No `cargo xtask scorecard` or `bench` yet. + +## Revision history + +| Date | Change | Summary | +|---|---|---| +| 2026-10-10 | minor | Current focus and M15 updated for the 10-10 merges | +| 2026-10-10 | minor | Added the alpha gate table (six core workflows; passes, stays alpha) | +| 2026-10-10 | major | Created: current focus, beta gates (~160–240 h), milestones moved from ROADMAP.md, post-beta ranking | diff --git a/docs/target-app-parity.md b/docs/target-app-parity.md new file mode 100644 index 0000000..2e5ed01 --- /dev/null +++ b/docs/target-app-parity.md @@ -0,0 +1,338 @@ +# Target-app parity: GridCraft vs Microsoft Excel + +> **Last reviewed:** 2026-10-10 · **Last updated:** 2026-10-10 · **Change:** major (first full assessment; re-measure against Excel for Mac 16.113.4, replacing the estimates that lived in ROADMAP.md) · **Target:** Microsoft Excel (Microsoft 365) + +This is the authoritative parity assessment. [`ROADMAP.md`](../ROADMAP.md) summarizes it, +[`gaps.md`](gaps.md) lists every shortfall, and the area checklists hold the detail: +[functions](function-parity.md), [charts](chart-parity.md), [file formats](file-format-parity.md), +[UI](ui-parity.md), [hardware](hardware-parity.md), [localization](localization-parity.md). The +generated ribbon checklist is [`parity-checklist.md`](parity-checklist.md). + +## Summary + +| Number | Value | Kind | +|---|---|---| +| Feature breadth (weighted by use) | **~75%** | estimated from the area table below; anchored on two measurements | +| Ribbon and menu catalog | **258 / 290 (89.0%)** | measured: `cargo xtask parity` (`crates/engine/src/catalog.rs` ∩ registered command ids) | +| Worksheet functions, by name | **501 / 523 (95.8%)** | measured: registered functions vs Microsoft's published function list (method below) | +| Worksheet functions that do real work | **492 / 523 (94.1%)** | measured: excludes 9 stubs (7 CUBE functions, WEBSERVICE, FILTERXML) | +| **Ready for real work** | **~50%** | estimated; written weights below (51.6 computed) | +| **Mainstream practitioner** | **~50%** | estimated; [method](#mainstream-practitioner) (69.5 depth × 0.90 × 0.92 × 0.88 = 50.6) | +| **Essentials user** | **~63%** | estimated; [method](#essentials-user) (80.2 depth × 0.92 × 0.95 × 0.90 = 63.1) | +| Stage | **alpha** | see [Stage](#stage) | +| Remaining to beta | **~160–240 Opus 5.5 agent-hours** | estimated; [roadmap.md](roadmap.md#beta-gates) | +| Remaining to full parity | **~700–1,100 Opus 5.5 agent-hours** | estimated; sum of the rows below | + +### Readiness by audience + +| Audience | Ready % | Opus 5.5 agent wall-clock hours to ~95% | Work that dominates | +|---|---|---|---| +| Full target (ready for real work) | ~50% | ~650–1,050 | Get & Transform and the data model, localization (twelve languages), charts depth, file fidelity (`.xls`, corpus, pass-through), PivotTables, collaboration, mobile | +| Mainstream practitioner | ~50% | ~200–310 | File exchange with Excel users (corpus and Excel verification, pass-through, large files, `.xls`, encryption: 63–97 h), common-chart depth (30–45 h), PivotTables (20–30 h), keyboard and interaction (18–28 h), calc correctness and functions (20–33 h) | +| Essentials user | ~63% | ~60–100 | Opening files people send (`.xls` and encrypted import 28–42 h; macOS Finder open 2–4 h), launch stability (6–10 h), basic chart resize and polish (6–10 h), print and Page Layout (8–12 h), small editing and UI fixes (10–16 h) | + +Each tier is a subset of the one above, so its hours are too. Calibrated as in [Effort and +calibration](#effort-and-calibration) (~6–10 h per readiness point for the remaining, verification-heavy +work; single features measured from PRs #66, #100, #101). Parallelism: the full and mainstream +work splits ~65–70% across 4–6 agents by area; the essentials work is mostly small fixes plus one +long `.xls` track, so about half parallelizes (≈30–50 wall-clock hours with three agents). + +## What we measured against, and how + +- **Target:** Microsoft Excel (Microsoft 365 channel). Version measured: **Excel for Mac + 16.113.4**, installed on the owner's Mac (version read from Spotlight metadata with `mdls`). + Where Excel for Windows has more (Power Pivot, VBA editor depth, COM add-ins, 3D Maps), the + Windows feature counts as part of the target. +- **Clean-room limits.** This repo's rule (AGENTS.md, "Non-negotiables") forbids reading anything + inside the Office bundle, so the bundle's `Info.plist`, `.lproj` folders and resources were + deliberately **not** inspected, and Excel was not launched for this pass. Excel's file formats, + functions and features come from Microsoft's public documentation, the owner's earlier + black-box observation (`plan/excel/observed-ui.md`, local only), and knowledge of the product. +- **Function list:** Microsoft's "Excel functions (alphabetical)" support page, fetched + 2026-10-10 and parsed (506 rows), plus 15 names the page lists under combined entries (FIND/FINDB, + LEFT/LEFTB, LEN/LENB, MID/MIDB, REPLACE/REPLACEB, RIGHT/RIGHTB, SEARCH/SEARCHB, BETA.INV) and + COPILOT and PY: **523 functions**. Ours: every `f!(…)` spec in `crates/functions/src/*.rs` plus + `SPECIAL_FUNCTIONS` in `crates/calc/src/eval.rs` (evaluator special forms), minus the test-only + `ADD2`: **501**, all of them Excel names. +- **Ribbon catalog:** `crates/engine/src/catalog.rs` (290 unique ids across 15 tabs) against the + 313 command ids registered in `crates/engine/src/cmd/*.rs`, recomputed from source by script and + identical to the committed `parity-checklist.md`. The catalog is our own transcription of + Excel's main ribbon tabs; it leaves out most contextual tabs (Picture Format, Shape Format, + Header & Footer, Sparkline, Slicer, Timeline), the Developer and Help tabs and sub-menu items, so + 89% of it is roughly **60–65% of Excel's full command surface** (estimated). +- **Depth and readiness:** source reading (the model types in `crates/model/src/features.rs`, + readers and writers in `crates/xlsx/src`, the evaluator), 478 `#[test]` functions, and the + issue tracker: 60 open issues and 50 open PRs on 2026-10-10, 82 issues filed in total. +- No cargo build or test ran for this pass (disk constraints); numbers come from source. + +## Weights + +Percentages are weighted by what Excel users actually do, not by item count. Feature-area +weights (sum 100) reflect a typical business, finance and analyst workload: formulas, functions, +editing and formatting dominate; Power Query, VBA and the data model matter to fewer users but +are decisive for those who use them. + +Dimension weights for **ready for real work**: features 45, file formats 15, UI/UX 12, +performance 8, stability 8, localization 4, hardware 2, platforms 2, ecosystem 2, AI 2. + +## Feature areas + +| Area | Weight | Breadth | Ready | Hours | Evidence | +|---|---|---|---|---|---| +| Formula language and calculation | 18 | ~92% | ~72% | 20–30 | A1/R1C1 parser, reference adjustment, dependency-graph recalc, dynamic arrays and `#SPILL!`, `A1#`, LET/LAMBDA and helpers, structured references, names, 3-D references. Open correctness bugs: 15-digit equality (#57), stale spills after structural edits and cleared blockers (#133, #139), 3-D span endpoint deletion (#140), sheet rename and qualified names (#134). Single-threaded | +| Worksheet functions | 12 | 95.8% (measured) | ~82% | 18–30 | 501 / 523 names, 492 working. Missing: FORECAST.ETS family, ODDF*/ODDL*, GETPIVOTDATA, TRIMRANGE, PERCENTOF, BAHTTEXT, IMAGE plus cloud functions. No conformance suite against Excel-computed oracles; edge-case bugs keep surfacing (#137, #138). [function-parity.md](function-parity.md) | +| Editing, navigation, clipboard, fill | 12 | ~90% | ~70% | 15–25 | Point mode, F4, AutoComplete, Paste Special, AutoFill, Flash Fill, Find/Replace, Go To Special. Bugs: rectangular drag-select (#28), monthly fill (#132), cut across sheets (#128), Insert Copied Cells missing (#21), key tips only on part of the Home tab (#43; #33, #49). [ui-parity.md](ui-parity.md) | +| Cell formatting, styles, conditional formatting | 10 | ~95% | ~80% | 8–14 | Full number-format language, borders, 47 cell styles, 60 table styles, all CF rule kinds including data bars, colour scales and icon sets. Gaps: font weights beyond regular/bold (#168), system fonts list (#4), themes | +| Sort, filter, tables, validation, outline | 8 | ~82% | ~70% | 10–16 | Multi-level sort, AutoFilter, Advanced Filter, tables with totals, validation, outline, subtotals, consolidate. Bugs: subtotal header (#131), validation edits (#129), table style panic caught (#130); no slicers on tables | +| PivotTables | 7 | ~65% | ~45% | 25–40 | Insert/Recommended, field list, three layouts, date grouping, show-values-as, refresh, XLSX round-trip. Missing: slicers, timelines, calculated fields/items, PivotCharts, value/label filters, number grouping, GETPIVOTDATA, data-model pivots. Round-trip never checked in Excel | +| Charts and sparklines | 8 | ~50% | ~30% | 40–60 | 25 chart kinds, all 2-D. The chart model holds title, legend position, a data-labels flag, gridlines flag and axis titles; no axis scaling, trendlines, error bars, per-point formatting, chart sheets, 3-D, surface, map, Pareto. Several kinds don't survive XLSX round trip (open PRs #158, #161). [chart-parity.md](chart-parity.md) | +| Page layout, print, PDF | 5 | ~80% | ~55% | 12–20 | Page setup, print titles, breaks, Page Break Preview, headers/footers, PDF export and printing. No true Page Layout view; the PDF writer uses only the 14 standard fonts without embedding (no CJK or other non-Latin text in PDF); web print only exports (#141, #143) | +| What-if and analysis | 4 | ~50% | ~40% | 22–35 | Goal Seek, Scenario Manager, data tables. Missing: Solver, Analysis ToolPak, Forecast Sheet, Analyze Data | +| Get & Transform, external data, data model | 5 | ~15% | ~10% | 60–100 | Import of CSV/TSV, JSON, HTML. No Power Query editor, no From Web, database or folder sources, no connections or refresh, no relationships or data model, no external workbook links (dropped with a warning) | +| Insert objects | 3 | ~55% | ~45% | 25–40 | Pictures, 8 shape kinds (Excel has ~170), text boxes, own icon set, ink with Ink to Shape, hyperlinks, checkboxes. Missing: SmartArt, WordArt, equations, signature line, objects, 3-D models, screenshot, pictures in cells (PR #105) | +| Review, comments, protection, collaboration | 4 | ~55% | ~40% | 35–55 | Threaded comments, notes, spelling (system dictionary), thesaurus, sheet and workbook protection. Missing: comment navigation, Show Changes, Allow Edit Ranges, notes-to-comments conversion, accessibility checker, co-authoring, opening password-encrypted files (refused with a message since #17) | +| Automation | 4 | ~30% | ~20% | 12–20 | Recorded, editable GridCraft scripts (Automate tab). VBA is out of scope by owner decision and is **dropped** when an `.xlsm` is opened (warning shown). No Office Scripts compatibility | +| **Weighted** | 100 | **~75%** | **~59%** | **300–485** | | + +## Dimensions + +| Dimension | Weight | Ready | Hours | Evidence | +|---|---|---|---|---| +| Features | 45 | ~59% | 300–485 | Table above | +| File formats | 15 | ~50% | 80–120 | XLSX read/write is broad but unproven on a real corpus and in Excel; XLSB and ODS are values-only import; no XLS, XML Spreadsheet 2003, SYLK, DIF, PRN; VBA dropped; 100 MB XLSX fails (#175). [file-format-parity.md](file-format-parity.md) | +| UI/UX fidelity | 12 | ~55% | 50–80 | Excel-style ribbon, galleries, dialogs, formula bar, status bar; 59 commands with shortcuts vs Excel's 200+; key tips on part of the Home tab only; short context menu; single window. [ui-parity.md](ui-parity.md) | +| Performance | 8 | ~35% | 35–55 | [Performance](#performance) | +| Stability | 8 | ~60% | 15–25 | Never-crash rules enforced by lint, every command fuzzed with hostile params, last-resort guard in `Session::execute`. Field reports: Windows Intel GPU crash (#120), error on close (#117), freeze opening from Finder (#166), screen flashing (#76) | +| Localization | 4 | ~10% | 100–165 | Ribbon-only catalog in five languages (ja, zh, ko, pt-BR, ru; ~12% of strings each), CJK/Thai/Hebrew font fallback, no shaping or RTL. [localization-parity.md](localization-parity.md) | +| Hardware | 2 | ~40% | 25–40 | GPU UI via wgpu; single-threaded calc; no pen pressure; one window. [hardware-parity.md](hardware-parity.md) | +| Platforms | 2 | ~80% | 30–60 | [Platforms](#platforms) | +| Ecosystem / add-ins | 2 | ~10% | 25–40 | [Ecosystem and AI](#ecosystem-and-ai) | +| AI features | 2 | ~15% | 30–50 | [Ecosystem and AI](#ecosystem-and-ai) | +| **Ready for real work** | 100 | **~50%** (51.6 computed: 0.45 × 59.0 features + the other rows × their weights) | **~700–1,100** | | + +How the full number is built: features ready is the weighted mean of the area table (59.0 with +charts at 30%); ready for real work is the weighted mean of this table with the weights written +under [Weights](#weights). Re-checked after the 10-10 merges: charts were corrected from 38% to +30% (round-trip loss, #190 chart resize) and localization rose from 5% to 10% (#31, #104, #82, +#38). The two moves cancel: 51.6 before and after, so **~50%** stands. + +## Mainstream practitioner + +The typical professional Excel user: an analyst, accountant or manager who builds and maintains +models, cleans and summarizes data, makes charts and pivots, and exchanges workbooks with Excel +users every week. Left out: Power Query and the data model, VBA and add-ins, Copilot and cloud +functions, co-authoring and admin, specialist hardware, and languages beyond the user's own +(localization is reported separately). + +| Area (weekly use) | Weight | Depth | Basis | +|---|---|---|---| +| Formula language and calculation | 20 | 72 | Feature-area table | +| Common worksheet functions | 15 | 85 | Missing functions are niche (ETS, odd-period bonds, cloud); edge bugs in common ones (#137, #138, #57) | +| Editing, navigation, clipboard, fill | 15 | 70 | Feature-area table | +| Cell formatting, styles, conditional formatting | 13 | 80 | Feature-area table | +| Sort, filter, tables, validation | 10 | 70 | Feature-area table | +| PivotTables (core: fields, layouts, grouping, refresh) | 8 | 60 | Slicers and calculated fields excluded as less frequent | +| Charts (column, bar, line, pie, scatter, combo) | 9 | 45 | Common kinds work and survive save; no axis options or trendlines; resize broken (#190) | +| Page layout, print, PDF | 5 | 60 | Latin text exports; no Page Layout view | +| Comments, notes, protection | 3 | 55 | Feature-area table | +| Pictures and shapes | 2 | 45 | Feature-area table | +| **Average depth** | 100 | **69.5** | | + +Discounts for what still stops real work: + +| Discount | Factor | Evidence | +|---|---|---| +| Interaction fidelity | × 0.90 | 59 command shortcuts vs Excel's 200+; key tips only on part of the Home tab (#43); rectangular selection bug (#28); charts can't be resized (#190); one window (#162); missing horizontal scrollbar report (#176) | +| Stability on real machines | × 0.92 | Never-crash lints, fuzzed commands and the `Session::execute` guard; but field reports of a startup crash on Intel UHD (#120), an error on close (#117), a freeze opening from Finder (#166) and screen flashing (#76) | +| File exchange with Excel users | × 0.88 | Excel opening our output is unverified across features; unmodelled parts dropped on save; advanced chart kinds lose their type; 100 MB files fail (#175); `.xls` and encrypted files are refused with a clear message (#17) rather than opened. Harsher than a drawing app's discount because spreadsheets are exchanged constantly | + +**Mainstream practitioner: 69.5 × 0.90 × 0.92 × 0.88 = 50.6 → ~50%** (estimated). Unlike most +apps it is not higher than the full number: GridCraft's breadth is wide (functions, formatting, +ribbon), so excluding the long tail removes little, while the discounts land on exactly what +mainstream users do every week (exchange files with Excel users). + +## Essentials user + +Someone who only touches the core: opens a workbook someone sent, types data and simple formulas, +formats, sorts, makes a basic chart, saves and prints. Advanced options, pro workflows and exchange +edge cases are left out, along with everything excluded from the mainstream number. + +| Core feature | Weight | Depth | Basis | +|---|---|---|---| +| Typing data, simple formulas, AutoSum (SUM, AVERAGE, arithmetic) | 20 | 88 | Solid; 15-digit equality (#57) is rare at this level | +| Basic formatting: fonts, bold, fills, borders, currency/percent/date formats | 15 | 85 | | +| Copy, paste, fill handle, undo/redo | 15 | 78 | Selection bug (#28), monthly fill (#132) | +| Rows and columns: insert, delete, widths, AutoFit | 10 | 82 | AutoFit fixed (#42, #88) | +| Sort and filter | 10 | 82 | | +| Save, Save As, reopen XLSX | 10 | 85 | | +| A basic chart | 8 | 55 | Created easily; can't be resized (#190) | +| Print and PDF | 7 | 65 | Desktop works; web PDF gives no file or feedback (#141) | +| Find and replace | 5 | 85 | | +| **Average depth** | 100 | **80.2** | | + +| Discount | Factor | Evidence | +|---|---|---| +| Launch and stability | × 0.92 | Startup crash on some Intel GPUs (#120), "Issue executing" (#59), error on close (#117) | +| Discoverability and UI clarity | × 0.95 | The Excel-style ribbon is familiar and labelled; system language by default (#31); small gaps (#176 scrollbar, #170 macOS window controls) | +| Opening files people send them | × 0.90 | Double-clicking a workbook in Finder freezes or errors on macOS (#166, #69; drag-and-drop works; fixes in PRs #164, #167); `.xls` and encrypted files are refused with a message | + +**Essentials user: 80.2 × 0.92 × 0.95 × 0.90 = 63.1 → ~63%** (estimated). + +## User evidence + +Counted from all 83 GitHub issues and 109 PRs on 2026-10-10; none of the issues were filed by +the maintainer. + +- **Praise:** 3 explicit ("this is brilliant. Tiny fast native binaries", #16; "Thanks for the + great work on GridCraft", #61; "i didnt have excel kind app on my macos", #69), plus polite + thanks in feature requests (#39, #45, #142). +- **"Switched from Excel" reports:** 0. One counter-signal: "without macro support most + professionals cannot switch from excel" (#6). +- **Issues by kind:** 50 core-path bugs (30 open, 20 closed) and 33 niche or feature requests + (25 open, 8 closed). 18 of the core-path bugs came from one auditing contributor (coygeek). +- **Contributors:** 104 PRs from 28 people outside the maintainer in five days, which shows + strong interest but not yet daily use. + +## Performance + +Excel recalculates on every core (multi-threaded recalculation), streams large files, and handles +1,048,576 × 16,384 sheets with millions of formulas. + +| Measure | GridCraft | Excel | Kind | +|---|---|---|---| +| Sheet size limits | 1,048,576 × 16,384 | same | measured (`crates/core/src/addr.rs`) | +| Recalc threads | 1 | all cores | measured (no threading in `crates/calc`) | +| Edit → recalc, 100k dependents | ~0.4 s (2026-10-07), target < 100 ms | tens of ms | measured on the owner's machine; #66 since made range-formula recalc linear, not re-timed | +| Grid scrolling | virtualised, O(log n) geometry with custom row heights | smooth | measured in code | +| Open a ~100 MB XLSX | fails (#175) | opens | user report | +| Whole-sheet operations | Fill and Remove Duplicates on a whole-sheet selection run out of memory or time (fix in PR #152) | fine | open PR | + +Work: streaming XLSX reader with shared-string and style dedup, multi-threaded recalc of +independent chains (native only; WASM stays single-threaded), whole-column reference +clamping, a `cargo xtask bench` with fixed workbooks so the numbers become measured. + +## Platforms + +| Platform | Excel | GridCraft | +|---|---|---| +| Windows x64 / arm64 | yes | yes (signed MSI and portable zip; also x86) | +| macOS (Apple silicon, Intel) | yes | yes (signed, notarized universal DMG) | +| Web | Excel for the web | yes (WASM; local files, no cloud) | +| iOS / iPadOS / Android | yes | no | +| Linux | no | yes (AppImage, Flatpak, deb, rpm, tarball; x86_64, aarch64, riscv64) | +| FreeBSD | no | yes | + +Mobile is the gap (30–60 h for a touch layout over the same engine). GridCraft is ahead on +Linux, BSD and RISC-V, where Excel doesn't run. + +## Ecosystem and AI + +- **Add-ins:** Excel has Office JavaScript add-ins, COM/XLL add-ins, VBA, Office Scripts and + Power Automate. GridCraft has its own recorded scripts, plus a control channel, MCP server and + CLI that reach every command. VBA is out of scope (owner decision). A plugin or custom-function + API (for example LAMBDA libraries and WASM custom functions) is the open-equivalent path: 25–40 h. +- **AI:** Excel has Copilot, the COPILOT() function, Analyze Data, Python in Excel and Flash + Fill. GridCraft has Flash Fill and best-in-class agent control (any MCP client can drive every + command headless or live), but no in-app assistant, no natural-language formulas and no + Analyze Data. Local-model equivalents: 30–50 h; model choice needs the owner. + +## Stage + +**Alpha.** All six core workflows in the [alpha gate](roadmap.md#alpha-gate) pass end to end on macOS with save and reopen (two pass with non-blocking fidelity loss). Core workflows exist end to end, but depth, fidelity and file compatibility are rough +(ready ~50%, inside the 40–75% alpha band). Not beta: the main format, XLSX, has not been proven +on real-world files or confirmed to open in Excel without repair, large files fail, `.xls` is +missing and text in several scripts doesn't render. Distance to beta: ~25 points of readiness and +~160–240 h, itemized in [roadmap.md](roadmap.md#beta-gates). + +## Effort and calibration + +Hours are **Opus 5.5 agent wall-clock hours**, one agent working sequentially, including tests +and verification. + +Calibrated against this repo's history: + +- **First pass, 2026-10-05 → 10-07:** M0–M13 (about 72,000 lines of Rust: engine, 478 functions, + XLSX, UI, charts, PivotTables, PDF, MCP, CLI, web, packaging) landed in commits from 22:09 on + 10-05 to 02:08 on 10-06, built by several parallel agents with work that preceded the first + commits; we put it at **~50–80 agent-hours** for 0 → ~50% ready, so **~1–1.5 h per point** + for the broad first pass. +- **Recent single features:** ODS import (#100, +2,232 lines with tests) and XLSB import (#101, + +1,212 lines) each fit in one agent session of roughly 2–3 h; the linear-recalc fix (#66, + +477 lines) about 1 h; single-function fixes (ROUND, DATE 1900, SUMIF sizing) 0.3–0.5 h each. + That is roughly **600–1,000 lines per agent-hour** including tests. +- **Tail factor:** what remains is verification-heavy (Excel as the oracle for files, functions + and rendering), and much of it is large self-contained subsystems (Power Query, Solver, + localization, `.xls`). We apply **5–7× the first-pass rate**: ~6–10 h per point of readiness. + +**Parallelism:** ~70% of the work splits cleanly by area (functions, charts, pivots, formats, +localization, Power Query) across 4–6 agents with one integrator; with five agents, beta is about +40–60 wall-clock hours away. **Needs a human:** checking our files in Excel (the owner's Mac), +native-speaker review of every language, scope decisions (co-authoring, cloud functions, +in-app AI models, mobile), and Windows hardware for GPU-driver crashes. + +## What works today + +The inventory carried over from the 2026-10-07 ROADMAP.md, updated for what landed since. Presence, not parity: the tables above grade depth. + +- Engine: A1/R1C1 formula parser with reference adjustment, dependency-graph recalculation with + dynamic arrays (spill + `#SPILL!`), cycle detection, LET/LAMBDA/MAP/REDUCE/SCAN/BYROW/BYCOL/ + MAKEARRAY, structured table references, defined names, INDIRECT/OFFSET/INDEX references, + 501 worksheet functions (478 at M0) (math, statistics and distributions, text and regex, lookup incl. + XLOOKUP/FILTER/SORT/UNIQUE/VSTACK, dates, financial incl. bonds, engineering incl. complex + numbers and Bessel, database, information). +- Number formats: Excel's full format-code language (sections, conditions, colours, dates and + elapsed time, fractions, scientific, accounting fill), General narrowing to column width. +- Files: XLSX read/write (styles, themes, merges, CF, validation, tables, comments, hyperlinks, + charts, pictures, sparklines, print settings, defined names, shared/array/dynamic formulas), + CSV/TSV with encoding and delimiter detection, HTML export, JSON; XLSB and ODS data import (values only, 10-10). +- Editing: cell entry with type detection and auto-formats, in-cell and formula-bar editing, + point mode (click/drag/arrow references), reference colouring, F4 anchor cycling, function + autocomplete and argument hints, copy/cut/paste and Paste Special (values, formats, transpose, + operations, link, skip blanks), AutoFill series (numbers, dates, months, weekdays, custom lists, + text+number), Fill Series, Flash Fill, find/replace with wildcards, Go To / Go To Special, + undo/redo with history, format painter. Quick selection drags retain their final endpoint; + the fill handle explains how to fill versus select cells. +- Formatting: fonts, fills, all border styles, alignment (wrap, indent, rotation, merge), number + formats, 47 cell styles, 60 table styles, conditional formatting (cell rules, text, dates, + duplicates, top/bottom, averages, data bars, colour scales, icon sets, formulas), automatic + row heights, autofit, hide/unhide, freeze panes. + Border presets include visual diagrams; Format Cells previews draft borders before applying. +- Data: sort (multi-level, by colour, custom lists), AutoFilter (values, custom, top 10, + average, colour), tables with totals rows, remove duplicates, text to columns, data validation + with error alerts, grouping/outline, subtotals. +- PivotTables: Insert/Recommended PivotTables, field list pane, compact/outline/tabular layouts, + date grouping, sort, filters, show-values-as, refresh, and XLSX round-trip. +- Page layout & print: Page Break Preview, print settings, PDF export and printing. +- What-if: Goal Seek, scenarios, data tables. Spelling (system word list) and thesaurus. +- Draw: pen, highlighter, eraser, ink strokes and Ink to Shape. Task panes: Comments (threaded + replies, resolve), Watch Window, Selection, Format Chart. +- Charts: column, bar, line, area, pie, doughnut, scatter, bubble, radar, histogram, waterfall, + funnel, treemap, sunburst, box & whisker, stock and combo charts; sparklines. +- UI (egui): Excel-style title bar with Quick Access Toolbar and AutoSave, the full ribbon with + galleries (cell styles, table styles, colour palettes, conditional formatting menus), + contextual Table/Chart Design tabs, formula bar with Name Box, virtualised grid (smooth + scrolling, zoom, frozen panes, text overflow), sheet tabs (rename, reorder, colour, hide), + status bar with Sum/Count/Average and zoom, dialogs (Format Cells, Formula Builder, Find and + Replace, Sort, Name Manager, Data Validation, Paste Special…), command palette, dark mode. +- Agents: every action is an engine command; JSON control channel in the desktop app (pointer, + keyboard, dialogs, screenshots); MCP server (headless or bridged); CLI (`info`, `convert`, + `eval`, `cat`, `run`, `commands`, `functions`, `mcp`, `send`). +- Platforms: macOS, Windows, Linux, FreeBSD; web (WASM via trunk). Release workflows for + signed/notarized macOS universal DMG, signed Windows x64/x86 MSI + zip, Linux AppImage/deb/rpm/ + tar.gz + Flatpak manifest, FreeBSD tarball and a web zip. + +## Not measured yet + +- Pixel comparison against Excel screenshots (planned; screenshots stay in `plan/excel/`). +- Function results against Excel-computed oracles (a corpus repo is the planned home). +- Recalc and open-time benchmarks on fixed workbooks (no `cargo xtask bench` yet). +- Whether Excel opens our XLSX output without repair, across features. + +## Revision history + +| Date | Change | Summary | +|---|---|---| +| 2026-10-10 | minor | Readiness-by-audience table: hours to ~95% for each of the three numbers (full 650–1,050, mainstream 200–310, essentials 60–100). Full number confirmed as the additive weighted sum over the written dimension weights (no change) | +| 2026-10-10 | minor | Added Mainstream practitioner (~50%) and Essentials user (~63%) with written weights and discounts, and user-evidence counts; re-checked the full number after the 10-10 merges (charts 38→30, localization 5→10; still 51.6, ~50%) | +| 2026-10-10 | minor | Stage checked against the new alpha gate (six core workflows, all pass): stays alpha | +| 2026-10-10 | major | Created. Full re-measure against Excel for Mac 16.113.4: functions 501 / 523 measured against Microsoft's list, catalog 258 / 290, breadth ~75%, ready ~50%, alpha; replaces the estimate tables previously in ROADMAP.md and keeps its "Working today" inventory | diff --git a/docs/ui-parity.md b/docs/ui-parity.md new file mode 100644 index 0000000..e85bca1 --- /dev/null +++ b/docs/ui-parity.md @@ -0,0 +1,95 @@ +# UI parity + +> **Last reviewed:** 2026-10-10 · **Last updated:** 2026-10-10 · **Change:** major (created from a source audit and the issue tracker) · **Target:** Microsoft Excel (Microsoft 365), Excel for Mac 16.113.4 + +Interaction, controls and feel, against Excel. Part of [target-app-parity.md](target-app-parity.md). +**UI/UX fidelity: ~55% ready, 50–80 h** (estimated). Ribbon command coverage is measured +separately in [parity-checklist.md](parity-checklist.md) (258 / 290). + +Sources: `crates/ui-egui/src` (ribbon, grid, editor, formula bar, dialogs, panes), +`crates/engine/src/cmd` (shortcuts in command specs), the owner's black-box notes +(`plan/excel/observed-ui.md`, local only) and user issues. + +## Window and chrome + +| Element | Excel | GridCraft | Status | +|---|---|---|---| +| Title bar, Quick Access Toolbar, AutoSave toggle | yes | yes | done; macOS window controls misaligned (#170), Dock icon size (#169) | +| Ribbon: tabs, groups, split buttons, galleries, contextual tabs | yes | yes (Table Design, Chart Design, Format, PivotTable tabs) | done; missing contextual tabs for pictures, shapes, sparklines, header/footer, slicers | +| Ribbon collapse, simplified ribbon, customize ribbon/QAT | yes | partial | customization missing (File ▸ Options is the one missing File command) | +| Key tips (Alt / F10 then letters) | yes, every ribbon control | **initial** (#43, 10-10): Alt or F10 shows key tips on Home for alignment, Paste Special and AutoFit plus legacy Alt sequences; other tabs and controls not yet (#33, #49) | 3–5 h | +| Formula bar with Name Box, expand, function hints | yes | yes | done | +| Sheet tabs: rename, reorder, colour, hide, scroll | yes | yes | rename focus bug on macOS (#145) | +| Status bar: Sum/Count/Average and more, view buttons, zoom | yes | yes | customizable statistics partial | +| Task panes (Format Chart, Comments, Watch, Selection, PivotTable fields) | yes | yes | element-level Format pane for shapes and pictures missing | +| Backstage (File) view: Info, New with templates, Open recent, Export, Options | yes | partial | Options dialog and template gallery missing | +| Dark mode, system appearance | yes | yes | done (10-09) | +| Page Layout view (paper view with rulers and header editing) | yes | **no** (Page Break Preview only) | 8–12 h | +| Multiple windows per workbook | yes | no (#162) | see [hardware-parity.md](hardware-parity.md) | + +## Grid interaction + +| Behaviour | Status | +|---|---| +| Click/drag/Shift/Ctrl selection, multi-area selection | rectangular drag works in one direction only in some cases (#28) | +| Fill handle: drag to fill series, double-click to fill down, right-drag menu | fill done; right-drag menu missing | +| Drag-move and drag-copy cells (border drag, Ctrl/Option, Shift to insert) | done (M3) | +| In-cell editing, Enter/Tab movement, Alt/Option+Enter line breaks | done | +| Point mode (click/drag/arrow references), reference colouring, F4 | done | +| AutoComplete in columns, function autocomplete and argument tips | done | +| Header resize and double-click AutoFit | done (#42, #88 for header dividers) | +| Freeze panes, split panes | freeze done; split to verify | +| Copy as HTML table for other apps | done (#36, 10-10) | +| Context menu on cells | 16 items (Cut, Copy, Paste, Paste Special, Insert, Delete, Clear Contents, Filter by value, Sort, New Comment, New Note, Format Cells, Pick From Drop-down List, Define Name, Link). Missing: Insert Copied/Cut Cells (#21), paste-option icons, Quick Analysis, Get Data from Table, Show Changes, Smart Lookup | +| Move and resize charts, pictures and shapes | charts can't be resized (#190) | +| Context menus on row/column headers, sheet tabs, charts, shapes | headers and tabs done; objects partial | +| Quick Analysis (Ctrl+Q) | missing | +| Smooth scrolling, scrollbars | done; vertical scrollbar added 10-09 (#73); horizontal scrollbar reported missing (#176) | +| Text overflow into empty neighbours, wrap, rotation, shrink to fit | done | + +## Keyboard + +| Area | Excel | GridCraft | +|---|---|---| +| Shortcuts bound to commands | 200+ documented shortcuts per platform | 59 command shortcuts plus grid and editor keys (55 distinct keys handled in `ui-egui`) | +| Ctrl+arrow, Ctrl+Shift+arrow, Ctrl+Home/End, Page Up/Down, Alt+Page | yes | done | +| Ctrl+1, Ctrl+; and Ctrl+Shift+; , Ctrl+D/R, Ctrl+E, Ctrl+T, Ctrl+K, Ctrl+Shift+L | yes | most done; audit pending | +| F2, F4, F5, F9 family, Shift+F3, F11 | yes | most; F11 chart sheet missing (no chart sheets) | +| Mac-specific (Cmd variants, Fn keys) | yes | Cmd mapping done | +| Requests | — | #110 (more shortcuts and hot keys), #33 (sequential Alt; initial support landed in #43) | + +Work: a shortcut table generated from the command catalog checked against Microsoft's published +shortcut lists for Windows and Mac, then fill the gaps: 6–10 h. + +## Dialogs + +Format Cells, Insert Function/Formula Builder, Find and Replace, Go To and Go To Special, Sort, +Name Manager, Data Validation, Paste Special, Conditional Formatting manager, Page Setup, Goal +Seek, Scenario Manager and others exist. Missing or partial: Options, Solver, Data Analysis, +Forecast Sheet, Power Query editor, Insert Object, Equation editor, Protect/Allow Edit Ranges, +Workbook Links, Accessibility checker. + +## Accessibility + +AccessKit is enabled, but the grid, ribbon and dialogs are not exposed as an accessible tree with +cell addresses and values, so screen readers can't navigate a sheet; there is no high-contrast +theme or accessibility checker. Excel is strong here. 12–18 h. + +## Feel + +Pixel comparison against Excel screenshots hasn't been run since M1; fonts depend on the system +(no Calibri; Carlito would match metrics, #29, #4, #168 for weights); icons are GridCraft's own +by rule and will never match Office's, by design. + +## Work (50–80 h) + +Key tips 3–5 · shortcut audit 6–10 · context menus and Quick Analysis 5–8 · Page Layout view +8–12 · Options dialog and ribbon/QAT customization 6–10 · accessibility 12–18 · selection and +scrollbar bugs 2–4 · pixel/feel pass against observed Excel 7–12. + +## Revision history + +| Date | Change | Summary | +|---|---|---| +| 2026-10-10 | minor | Chart resize bug (#190) | +| 2026-10-10 | major | Created: chrome, grid, keyboard, dialogs, accessibility; key tips, Page Layout view and accessibility tree flagged | diff --git a/xtask/src/main.rs b/xtask/src/main.rs index 9180758..603801f 100644 --- a/xtask/src/main.rs +++ b/xtask/src/main.rs @@ -21,12 +21,12 @@ usage: cargo xtask commands: ci fmt --check, clippy -D warnings, test, assets, layers, wasm, parity --check - (stops at the first failure; the parity check runs only if docs/parity.md exists) + (stops at the first failure; the parity check runs only if docs/parity-checklist.md exists) assets check that every icon/image/font/sample file is attributed in ATTRIBUTION.md layers enforce the crate dependency layering (AGENTS.md \"Layering\") wasm cargo check --target wasm32-unknown-unknown for the L0-L5 crates (+ gridcraft-web) parity [--check] [--out PATH] - write docs/parity.md from gridcraft_engine::catalog (implemented vs missing ids) + write docs/parity-checklist.md from gridcraft_engine::catalog (implemented vs missing ids) version [set X.Y.Z[-pre]] print or set the workspace version ([workspace.package] in Cargo.toml) stats [--exact] count tests and lines per crate (--exact: ask the test harness via `-- --list`) @@ -186,10 +186,10 @@ fn cmd_ci() -> Result<(), String> { ( "parity", Box::new(|| { - if root().join("docs/parity.md").exists() { + if root().join("docs/parity-checklist.md").exists() { parity::run(&root(), &["--check"]) } else { - println!("parity: docs/parity.md not generated yet; skipped (run `cargo xtask parity`)"); + println!("parity: docs/parity-checklist.md not generated yet; skipped (run `cargo xtask parity`)"); Ok(()) } }), diff --git a/xtask/src/parity.rs b/xtask/src/parity.rs index 6f00b09..f0efeca 100644 --- a/xtask/src/parity.rs +++ b/xtask/src/parity.rs @@ -1,8 +1,8 @@ -//! `cargo xtask parity [--check] [--out PATH]`: write `docs/parity.md` from the engine's command +//! `cargo xtask parity [--check] [--out PATH]`: write `docs/parity-checklist.md` from the engine's command //! catalog (`gridcraft_engine::catalog::CATALOG`, Excel's ribbon and menu tree). A catalog id is //! implemented when a command with that id is registered (`gridcraft_engine::find_command`). //! -//! `--check` fails if `docs/parity.md` is out of date instead of writing it; `--out` writes +//! `--check` fails if `docs/parity-checklist.md` is out of date instead of writing it; `--out` writes //! somewhere else. The rendering is pure (`render`) so it is unit-tested without the engine. use std::path::Path; @@ -23,7 +23,7 @@ fn pct(done: usize, total: usize) -> f64 { if total == 0 { 0.0 } else { 100.0 * done as f64 / total as f64 } } -/// The markdown for docs/parity.md. Ids are counted once (the first catalog row wins), tabs keep +/// The markdown for docs/parity-checklist.md. Ids are counted once (the first catalog row wins), tabs keep /// catalog order. pub fn render(entries: &[Entry]) -> String { let mut seen: Vec<&str> = Vec::new(); @@ -44,10 +44,11 @@ pub fn render(entries: &[Entry]) -> String { let total = unique.len(); let mut s = String::new(); - s += "# Excel parity\n\n"; + s += "# Excel parity checklist\n\n"; s += "\n\n"; s += "Each entry is an Excel ribbon or menu command (feature names only). It counts as implemented when GridCraft \ - registers a command with the same id.\n\n"; + registers a command with the same id. This measures breadth only; the overall assessment (depth, \ + fidelity, effort) is in [target-app-parity.md](target-app-parity.md).\n\n"; s += &format!("**Overall: {done} / {total} commands implemented ({:.1}%).**\n\n", pct(done, total)); s += "| Tab | Implemented | Total | Parity |\n|---|---|---|---|\n"; for t in &tabs { @@ -93,7 +94,7 @@ fn summary_line() -> String { #[cfg(feature = "engine")] pub fn run(root: &Path, args: &[&str]) -> Result<(), String> { let mut check = false; - let mut out: PathBuf = root.join("docs/parity.md"); + let mut out: PathBuf = root.join("docs/parity-checklist.md"); let mut it = args.iter(); while let Some(a) = it.next() { match *a {