- commit
- bd5d0bbd57e9f2e735e742b61c9d5d8dc9663161
- parent
- b86ff790297260f9bd8444da911d10e39b56d8f2
- parent
- c987c9126e1583cdf02edc91550129e59692fad4
- author
- Dami <dami.etoile@gmail.com>
| M | README.md | 24 | ++++++-------- |
| M | ROADMAP.md | 6 | +-- |
| M | docs/ | 2 | +- |
| M | docs/ | 29 | +++++++++++++---- |
| M | docs/ | 20 | +++--------- |
| M | docs/ | 4 | +- |
| M | docs/ | 2 | + |
| M | docs/ | 2 | + |
| M | docs/ | 2 | + |
| M | docs/ | 51 | +++++++++++++++++------------- |
| M | docs/ | 5 | +-- |
@@ -29,7 +29,8 @@ rest: building from a clone, importing files, `012 serve` and settings.
2929 mouse, named ranges, references between sheets, arrays that spill3030 (FILTER, SORT, UNIQUE, LAMBDA), optional decimal3131 arithmetic for money, and undo for everything32- ([formulas](docs/formulas/README.md)).32+ ([formulas](docs/formulas/README.md)); numbers, dates and formulas33+ typed and shown in a [locale](docs/sheets/locale.md) per file.3334 - **Data tools**: freeze, sort, filter, find and replace, conditional3435 formatting, dropdowns and checkboxes, notes, protected ranges, and live3536 pivot tables ([working with data](docs/sheets/README.md)); wrapped@@ -56,19 +57,16 @@ rest: building from a clone, importing files, `012 serve` and settings.
5657 | Menus and the command palette (Ctrl+K) | Charts that float over the grid and follow their data |5758 |  |  |5859 | Conditional formatting and data validation | Pivot tables, live |59-|  |  |60-| Freeze, sort and filter | Find and replace |61-|  |  |62-| JEV functions in formulas | Formats detected as you type |63-|  |  |64-| Arrays that spill | Macros |65-|  |  |66-| Wrapped text, borders and merged cells | A locale per file |60+|  |  |61+| Arrays that spill | Wrapped text, borders and merged cells |62+|  |  |63+| JEV functions in formulas | Macros |6764 68-The recordings are [VHS](https://github.com/charmbracelet/vhs) tapes in69-[`demos/`](demos), rendered by `make demos` in the Catppuccin Mocha70-palette; 012 draws in your terminal's own colors by default71-([themes](docs/terminal/themes.md)). Charts show as text here.65+Each guide shows its own recordings too. They are66+[VHS](https://github.com/charmbracelet/vhs) tapes in [`demos/`](demos),67+rendered by `make demos` in the Catppuccin Mocha palette; 012 draws in68+your terminal's own colors by default ([themes](docs/terminal/themes.md)).69+Charts show as text here.7270 7371 ## More7472 @@ -18,7 +18,6 @@ Sizes: S (a day or two), M (about a week), L (weeks).
1818 1919 | Item | Why | Size |2020 |---|---|---|21-| Open 012's XLSX output in Excel and LibreOffice before releases, as was done for Google Sheets | The writer is otherwise checked by excelize and 012's reader | S |2221 | Conditional formatting and validation, what's left: data bars and icon sets, "top 10", "duplicate values", date periods (this week, last month), rules moving with cells cut to another sheet, a dropdown's chip look, and custom checkbox values | Excel's other rule types come in as notes | M |2322 | Remaining overlays get narrow hosts: filter picker, sort and choice bars, chart editor, shortcuts, named ranges, cell entry and prompts | Components testable without the model ([Architecture](docs/contributing/architecture.md#the-ui)) | M |2423 @@ -74,8 +73,7 @@ by a gateway dialing the iroh ticket.
7473 - Dynamic arrays that spill (FILTER, SORT, UNIQUE, SEQUENCE and more, ARRAYFORMULA), LET and LAMBDA, SPLIT and the REGEX functions: [Arrays and spills](docs/formulas/arrays.md)7574 - Opt-in decimal arithmetic for money: [Decimal arithmetic](docs/formulas/decimal.md)7675 - A locale per file, as Sheets' File > Settings > Locale: decimal commas, date order, currency and `;` in formulas, typed and shown while files store en-US's form: [Locale](docs/sheets/locale.md)77-- An Excel-sized grid with a `max-cells` budget; operations cost the data, not the grid: [Bounds of support](docs/contributing/limits.md#sheet-size)78-- Compact column storage and a ten-million-cell `max-cells` budget: [Bounds of support](docs/contributing/limits.md#sheet-size)76+- An Excel-sized grid in compact column storage, with a ten-million-cell `max-cells` budget; operations cost the data, not the grid: [Bounds of support](docs/contributing/limits.md#sheet-size)7977 - Undo steps in the compact form: clearing a full ten-million-cell sheet holds about what the sheet does, and a step past 1 GB asks first: [Bounds of support](docs/contributing/limits.md#undo)8078 - Spilled cells and pivot results in the compact form, about 20 B each: [Bounds of support](docs/contributing/limits.md#sheet-size)8179 @@ -114,6 +112,6 @@ by a gateway dialing the iroh ticket.
114112 **Upkeep**115113 116114 - `make check` before every push; demo tapes (`make demos`); annotated version tags with release notes (v0.2.0 onward; v0.1.0 remains on the Go module proxy): [Testing](docs/contributing/testing.md)117-- A release checklist and `make dist`, release archives cross-compiled locally with SHA256SUMS: [Releasing](docs/contributing/releasing.md)115+- A release checklist (XLSX output opened in Excel, LibreOffice and Google Sheets) and `make dist`, release archives cross-compiled locally with SHA256SUMS: [Releasing](docs/contributing/releasing.md)118116 - `make stress-report` flags regressions against the last release's run, allowing for noise: [Observability](docs/contributing/observability.md#regressions-against-the-last-release)119117 - Grafana: recent traces and a trace view of the nested spans: [Observability](docs/contributing/observability.md#the-stack)@@ -325,7 +325,7 @@ move without touching callers:
325325 the places functions read ranges.326326 - **Files.** The `.012` reader and writer stream (`fileread.go`,327327 `filescan.go`) and meet the store only through its methods, so another328- encoding would sit beside them; [The .012 format](../files/format.md#reading-and-writing)328+ encoding would sit beside them; [Bounds of support](limits.md#the-012-file)329329 says why there is one.330330 - **Depth limits.** `internal/formula`'s parser caps nesting at331331 `formula.MaxDepth` (1024 levels), so a pathological formula fails to@@ -48,9 +48,8 @@ ten million cells by default): imports keep whole rows up to it, pastes
4848 and fills write at most that many cells at once. WK1 files keep their own4949 8192 x 256. The costs below grow with the cells; the grid itself costs5050 nothing (see [The grid](#the-grid)). A `.012` file is read and written51-as a stream, cells straight into and out of the store ([The .01252-format](../files/format.md#reading-and-writing)), so opening costs about53-the memory the workbook then holds.51+as a stream, so opening costs about the memory the workbook then holds52+([The .012 file](#the-012-file)).5453 5554 | Measure | 8192 x 26 (213 k cells) | 8192 x 256 (2.1 M cells) | 1,000,000 x 10 (10 M cells) |5655 |---|---|---|---|@@ -81,6 +80,22 @@ them out is in [Architecture](architecture.md#the-engine). Reading a
8180 cell's value is an index into its column's block: 2.8 ns8281 (`BenchmarkRead`), 8.6 ns a cell read by a SUM in a full recalculation.8382 83+### The .012 file84+85+The reader and writer stream (`internal/sheet/fileread.go`,86+`filescan.go`): each cell goes into its sheet as its line is read, a87+number typed plainly straight into its 16-byte slot, and the other88+fields are small and decoded whole. Saving writes the cells in89+row-major order as it reads them from the sheet, straight into the90+file.91+92+There is one format. A binary one that stored the slots themselves93+would open ten million numbers in about 0.3 s at best (storing ten94+million slots alone takes 0.17 s) where the JSON takes 1.2 s: a second95+saved on sheets near `max-cells`, and nothing a smaller sheet would96+notice, for the loss of what the JSON gives, diffs, merges, and a file97+anyone can read and fix.98+8499 ## The grid85100 86101 Nothing costs what the grid costs. The cells' occupancy@@ -213,7 +228,9 @@ every cell on screen a shade), at 200 x 60 (`BenchmarkFrame`,
213228 | Typing a number and Enter, through to the frame | 0.89 ms | 2.3 ms (the scale's percentile over 213 k numbers) |214229 215230 Shades and rule colors keep their escape codes, so a plain cell on one216-costs a string concatenation, not a style render.231+costs a string concatenation, not a style render. A custom formula is232+evaluated for each cell drawn, once per recalculation, with its233+references moved for the cell.217234 218235 Wrapped text, borders, row heights and merged cells cost what the219236 screen shows too. A sheet with none of them is drawn a line per row@@ -229,9 +246,7 @@ top (`BenchmarkFrame`, `BenchmarkKeystroke`):
229246 |---|---|---|---|230247 | 8192 x 26 numbers, a frame | 0.18 ms | 0.90 ms | 3.1 ms |231248 | The same laid out, a frame | 0.24 ms | 1.28 ms | 4.3 ms |232-| The same laid out, an arrow key through to its frame | 0.25 ms | 1.25 ms | | A custom formula is233-evaluated for each cell drawn, once per recalculation, with its234-references moved for the cell.249+| The same laid out, an arrow key through to its frame | 0.25 ms | 1.25 ms | |235250 236251 A chart drawn as text costs 4 to 50 us at 24 x 10 to 120 x 40 cells,237252 whatever its data: only the categories that fit are drawn (a pie of 8192@@ -39,26 +39,16 @@ only for their formatting and notes.
3939 4040 ## Reading and writing4141 42-012 reads and writes the file as a stream (`internal/sheet/fileread.go`,43-`filescan.go`). Each cell goes into its sheet as its line is read, a44-number typed plainly straight into the 16-byte slot the sheet keeps it45-in, so opening a file takes about the memory of the workbook, however46-large the file; the other fields are small and decoded whole. Saving47-writes the cells in row-major order as it reads them from the sheet,48-straight into the file. Ten million numbers (236 MB of JSON) open in49-1.2 s and save in 0.5 s ([Bounds of support](../contributing/limits.md#sheet-size)).50-5142 Any JSON with the same fields reads the same: the order of keys,5243 spacing, and the case of field names don't matter. A cell given twice5344 takes its last entry, though an invalid earlier one is refused; the5445 `version` or the `sheets` list given twice around cells is refused.5546 56-There is one format. A binary one that stored the slots themselves57-would open ten million numbers in about 0.3 s at best (storing ten58-million slots alone takes 0.17 s) where the JSON takes 1.2 s: a second59-saved on sheets near `max-cells`, and nothing a smaller sheet would60-notice, for the loss of what the JSON gives, diffs, merges, and a file61-anyone can read and fix.47+012 reads and writes the file as a stream, each cell straight into or48+out of its sheet, so opening a file takes about the memory of the49+workbook however large the file; what that costs, and why there is no50+binary format beside this one, is in51+[Bounds of support](../contributing/limits.md#the-012-file).6252 6353 ## Versions6454 @@ -5,6 +5,8 @@ sidebar_position: 7
55 66 # JEV functions77 8+9+810 With a TypeSafe API key, four functions ask the hosted JEV model about a911 value (a cell, a range or text). They follow Sheets' argument style: the1012 value, the question, then what the answers mean.@@ -22,8 +24,6 @@ line shows the confidence for the selected cell. Data > Ask JEV again
2224 re-asks the selection.2325 2426 Without a key the functions show `#N/A` and say how to add one.25-`JEV_LIVE_TEST=1 go test ./internal/jev -run TestLive` checks the real26-service.2727 2828 ## Setup2929 @@ -5,6 +5,8 @@ sidebar_position: 10
55 66 # Charts77 8+9+810 Insert > Chart charts the selection, or the table around the active cell,911 guessing the header row, the label column and a title. The chart floats over1012 the grid, pinned to a cell, and redraws when its data changes.@@ -5,6 +5,8 @@ sidebar_position: 6
55 66 # Find and replace77 8+9+810 Ctrl+F opens a find bar on the context line: matches highlight as you type,911 the active cell follows the current one, and Enter and Shift+Enter step1012 through them. Ctrl+H adds a replacement field; Enter replaces and moves on,@@ -13,6 +13,8 @@ whole columns or rows, then pick a format from the Format menu, a key
1313 1414 ## Number formats1515 16+17+1618 Format > Number, as Sheets names them:1719 1820 | Format | Shows |@@ -53,16 +53,6 @@ results. They follow inserted and deleted rows and columns, and a rule
5353 whose cells are all deleted goes. Format > Clear conditional formats5454 takes the selection out of every rule.5555 56-Rules, conditional formats and validation alike, move with cut and57-paste on a sheet, as in Sheets: the cut cells take their rules to where58-they land, and the cells they land on lose theirs. A rule whose cells59-partly move keeps both parts; with a custom formula it becomes two60-rules, each with the formula written for its own first cell, so the61-cells that stayed read what they read and the moved ones read the cells62-beside their new places. Formulas in rules follow cells that63-move. Cut on one sheet and pasted on another, the cells leave their64-rules behind and meet the rules where they land.65-6656 ## Data validation6757 6858 Data > Data validation opens the sheet's validation rules in the same@@ -96,19 +86,36 @@ own words there. A formula is checked by the value it computes. Blanks
9686 are always valid.9787 9888 Each cell has one rule: a rule added over cells that had another takes99-them from it. Validation checks what's typed, picked from a dropdown and100-entered by macros. Pastes (Ctrl+V, paste values, text pasted from101-another program) and fills (Ctrl+D, Ctrl+R, Ctrl+Enter, the fill102-handle) are checked after they're written, as in Sheets: when a cell's103-rule rejects what landed there, the whole paste or fill is undone and104-ERROR mode says which cell and why ("Paste undone: Invalid entry in105-B2: ..."; Ctrl+Enter keeps the entry open instead); when only rules that106-warn fail, it stays, the cells are marked, and the context line says how107-many ("2 cells invalid, first B2: ..."). Imports aren't checked, and what108-they leave invalid is marked. Validation can't go on a pivot table's109-results, which take no entries. Data > Remove data validation takes the110-selection out of every rule.89+them from it. Validation can't go on a pivot table's results, which take90+no entries. Data > Remove data validation takes the selection out of91+every rule.92+93+What validation checks:94+95+- **Typing, a dropdown's pick and macros' entries**, as they're96+ entered, rejected or warned as above.97+- **Pastes and fills** (Ctrl+V, paste values, text pasted from another98+ program; Ctrl+D, Ctrl+R, Ctrl+Enter, the fill handle), after they're99+ written, as in Sheets. When a cell's rule rejects what landed there,100+ the whole paste or fill is undone and ERROR mode says which cell and101+ why ("Paste undone: Invalid entry in B2: ..."); Ctrl+Enter keeps the102+ entry open instead. When only rules that warn fail, it stays, the103+ cells are marked, and the context line says how many ("2 cells104+ invalid, first B2: ...").105+- **Imports** aren't checked; what they leave invalid is marked.111106 112107 Adding a checkbox or a dropdown changes no cells, so on a protected range113108 it doesn't ask first (on a protected sheet it does); checking a box or114109 picking an item asks as typing does ([protection](notes-protection.md#protected-sheets-and-ranges)).110+111+## Moving cells112+113+Conditional formats and validation rules move with cut and paste on a114+sheet, as in Sheets: the cut cells take their rules to where115+they land, and the cells they land on lose theirs. A rule whose cells116+partly move keeps both parts; with a custom formula it becomes two117+rules, each with the formula written for its own first cell, so the118+cells that stayed read what they read and the moved ones read the cells119+beside their new places. Formulas in rules follow cells that120+move. Cut on one sheet and pasted on another, the cells leave their121+rules behind and meet the rules where they land.@@ -62,9 +62,8 @@ muted text included, and 4.5:1 for lines, borders, chart axes and
6262 unavailable menu items. The pointer is black on cyan, the selection6363 white on blue, errors a light red on black (a dark red on white).6464 65-States never rest on color alone in any theme: the pointer and the66-selection are in reverse video, errors have a curly underline, invalid67-entries a dotted one, spilled values are italic, and so on65+States never rest on color alone in any theme: each also shows as66+text, a glyph or an attribute such as reverse video or an underline6867 ([Reading without color](../contributing/ux.md#reading-without-color)).6968 7069 ## Your own schemes