summaryrefslogtreecommitdiff
path: root/docs/next-tables.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-10-24 14:39:23 -0300
committerGabriel Schneider <[email protected]>2026-10-24 15:56:58 -0300
commitf4e295a0b61ae34e8abfd339eb1b6f658f8bf329 (patch)
treef8081ca747f8e1f332a646e63b918326951c8384 /docs/next-tables.md
parent349bc6fa736edcebd789c5a39885d08f251713a1 (diff)
downloadpardes-f4e295a0b61ae34e8abfd339eb1b6f658f8bf329.tar.gz
pardes-f4e295a0b61ae34e8abfd339eb1b6f658f8bf329.zip
Tables 4/4: a delimiter cell's colons kept at its edges; a wide table shown as source in a wrapping pane, tested; docs/next-tables.md, the design as built, the numbers and the open questions
Diffstat (limited to 'docs/next-tables.md')
-rw-r--r--docs/next-tables.md176
1 files changed, 176 insertions, 0 deletions
diff --git a/docs/next-tables.md b/docs/next-tables.md
new file mode 100644
index 00000000..cc9e567c
--- /dev/null
+++ b/docs/next-tables.md
@@ -0,0 +1,176 @@
+# Tables in markdown files, as built
+
+> Could we do special rendering for tables in markdown files?
+
+A GFM pipe table in a `.md` file is drawn as a table, in its own rows: every
+column's `|` on one screen column whatever the source spacing, the `|` drawn
+as rules, the delimiter row (`|:--|--:|`) drawn as one rule with its colons
+kept, the header bold on the tag's ground. Every byte stays in its row as the
+text it is: B1 selects it, B2/B3 take its words, the chords cut and paste it,
+the caret sits on it, and nothing is drawn over anything. Editing a cell
+re-aligns the table on the keystroke.
+
+## The one idea: a pad is a tab's extra cells
+
+The rows are not rewritten. A cell narrower than its column is given the
+cells it lacks as **virtual width before one of its bytes** (a *pad*): before
+the `|` that ends it (left), before its first byte (right), split (centred).
+A pad is to its byte what a tab's extra cells are to the tab: drawn blank,
+each of its cells maps back to that byte, and the caret before that byte is
+drawn after the pad, against its glyph. So there is no parallel map: the
+existing pane-aware column functions in `File.zig` add the pads, and so does
+every walk that draws a file row.
+
+| where | what changed |
+|---|---|
+| `File.rowPads` / `rowTable` | the gate: a row of a table of the text as it is now, that fits the pane |
+| `File.displayOffset`, `displayEndOffset`, `byteAtRowDisplay` | `+ Tables.between(pads)` / `Tables.byteAt` |
+| `File.fillBody` | writes the pads as blanks into the body string (so `paneText`, `expandedSel`, the sweep text see the drawn row) |
+| `File.recolorSyntax` | its screen walk steps over the pads |
+| `body_layer` | pointer-selection tint and the view-edge checks through the pane-aware functions |
+| `edit.capturePointerSelection` | a sweep's columns to bytes through `byteAtRowDisplay` |
+| `Text.verticalMove` / `visualMove` | j/k keep the column the table shows (a body of a file pane only) |
+
+Everything else (mouse.zig, exec.zig's B2 cells, look.zig's cursor word, the
+caret, multi-cursor tints, `gw` labels) already went through those three
+functions and needed no change. That is the evidence the mapping is in one
+place: the round-trip test clicks every cell of a row with pads of all three
+kinds and checks the caret lands on the byte and is drawn where it is.
+
+## The look (`Tables.paint`)
+
+Glyphs and colours only, on the cells the row has, after the syntax colours:
+`|` as `│`, the delimiter row as `├──┼──┤` (its `-`, blanks and pads as `─`,
+its `:` in the rule colour), the header bold on `tag_bg` (the compact context
+rows' ground: tables reuse a look the editor has). The rule colour is the
+theme's `border`, else `lineno`.
+
+## Finding the tables
+
+tree-sitter-markdown here does expose `pipe_table` (header, delimiter row,
+cells, alignments). I did not use the tree to find them: the highlighter
+parses only the lines around the view (`refreshHighlights`, a fragment from
+`scroll - slack`), which starts mid-table as soon as a long table is
+scrolled, and a fence is only known from the top. So `Tables.zig` finds
+tables by lines with the grammar's own rules (its scanner's
+`PIPE_TABLE_START`: a header's cells counted by pipes, a `:?-+:?` delimiter
+row of the same count with at least one pipe; rows until a blank line or a
+block that interrupts a paragraph; escaped `\|`), and the grammar is the
+**oracle in a test** (`tables are the pipe_tables tree-sitter finds`: five
+tables including an indented one, a no-pipe continuation row and an escaped
+pipe; the fenced one and the short-delimiter one not).
+
+## Cost (measured)
+
+`.scratch/stress-tables.md`: 2.7 MB, 54 508 lines, 2000 tables of 3-6 columns
+and 10-30 rows, fences every 50 tables. Debug build, 160x50, each step
+`update` + a full render, the same text as `.md` and as `.txt`
+(`zz tables timings`, `TABLES_TIMES=<path>`).
+
+| what | .md | .txt |
+|---|---|---|
+| a whole read of the tables (once, blocking, for comparison) | 127 ms | - |
+| the first frame | 27 ms | 18 ms |
+| frames until every table is read (4 ms a frame from the top) | 24 | - |
+| `j` and its frame, in a table | 1.0 ms (worst 1.5) | 0.6 ms (0.9) |
+| a letter typed in a cell and its frame | 3.2 ms (worst 8.5) | 2.0 ms (6.8) |
+
+The first version re-read the whole text on every edit: 119 ms a keystroke.
+Two changes the numbers forced, both Places' patterns:
+
+- **An edit reflows**: the tables it did not touch shift by the lines it
+ added (`File.State.splice`), and only its block (blank line to blank line,
+ the touched tables taken in) is read again. A fence line in the edit, or
+ in what it replaced, reads everything (a fence changes every line after
+ it). A random 1500-edit test checks every result against a whole read;
+ more than 1000 took the short way.
+- **Opening reads from the top a frame's budget at a time** (`Tables.frame_ns`,
+ `Pardes.nextWake` while `busy`): rows below the read point are drawn as
+ source until it gets there (a quarter second on this file). An edit past
+ the read point changes nothing read; one before it starts the read again.
+
+## GUI and tty
+
+Both draw the same grid: alignment, rules, header, the mapping are core.
+What only the GUI does: the light box-drawing rules (`─│┌┐└┘├┤┬┴┼`) are drawn
+by hand edge to edge (`gui.zig` `ruleArms`/`drawRule`, a `rule` bit in
+`GlyphKey`, never a slice of a shaped word), so a table's `│` joins the rows
+above and below at any line height and the delimiter row is one unbroken
+line. In a terminal they are the terminal font's glyphs, which may leave gaps
+between rows (the terminal's business). This applies to every box-drawing
+cell in the GUI, terminal panes' TUIs too (as Ghostty and kitty do).
+
+Things only a GUI could do next, not done: pixel-thin rules between cells
+rather than a cell-wide glyph (needs a cell decoration the surface does not
+have); a half-cell inset so a rule does not take a whole column.
+
+## Rough
+
+- A table wider than a wrapping pane is shown as its source, wrapped (a
+ padded row must not wrap: wrapping is byte-fitted). `Wrap off` lays it out
+ again with hscroll.
+- Inline markdown is not coloured inside cells: `syntax.inject` injects
+ `markdown_inline` into `inline` nodes, and `pipe_table_cell` is not one.
+- A table in a blockquote or list item is not found (the line detector has
+ no container prefixes); tree-sitter finds it.
+- Mixed leading pipes (`| a |` over `a |`) misalign by one cell; a leading
+ pipe's indentation is padded only when the pad is not at byte 0.
+- Columns past 64 are not aligned. Zerox twins do not share the splice, so a
+ twin re-reads the whole text after an edit (sliced, so it still does not
+ hold a frame).
+- The sweep-text fallback (`selectionText` without captured rows, a sweep
+ begun on the tag) reads the drawn row, so it would carry pad blanks; the
+ same is true of the callstack guide today.
+
+## Open questions, and my position on each
+
+1. **Hide redundant source spaces?** Position: no. Every byte stays visible;
+ only width is added, never taken. `| foo|` shows its two spaces. Hiding
+ bytes would make a click land on something you cannot see, which is the
+ constraint's spirit even if a space is "text".
+2. **The glyph substitution: is drawing `|` as `│` drawing over text?**
+ Position: no; it is the byte's glyph, like a font ligature (which the GUI
+ already does), with the byte selectable, searchable, typed over. The
+ alternative, keeping `|` and only padding, is one constant away
+ (`rule_v`); I find the plain `|` reads as source, not as a table.
+3. **Delimiter colons**: kept, in the rule colour, at the cell edges. The
+ alignment is visible anyway, but you edit them, so they must show.
+4. **Rule colour**: `border` is faint on doom_one, especially the 1 px
+ horizontal rule. `lineno` or a mix toward `fg` would read better; a theme
+ field (`table_rule`) is the honest answer if you want it tunable.
+5. **Wide tables**: source wrapped (now) versus clipped laid-out rows with
+ hscroll per table. Position: source; a clipped row hides text, and the
+ wrap is honest. A column could also be squeezed by wrapping a cell inside
+ it, but that is a virtual row, and virtual rows break the row = line
+ invariant everything here rests on.
+
+## Pushback
+
+- The NEXT brief says "check whether the grammar exposes pipe_table nodes and
+ use them if so". It does, and using them for detection would be worse here
+ (a view-local fragment parse starts mid-table; a whole-file parse is
+ ~seconds in Debug on the stress file, by converge's 4.8 s for 1.2 MB of
+ Zig). Using the grammar as the test oracle keeps its rules without its
+ cost. If a whole-file markdown tree ever exists (a worker parse, as
+ converge does for declarations), the detector could read it instead.
+- Re-aligning live means a column widens under the caret as you type in its
+ widest cell, so the rest of the row moves right per keystroke. That is the
+ point of the feature, but it is motion in text you are not editing; a
+ `TableAlign off` setting may be wanted for heavy table editing.
+- Making box-drawing rules procedural is a GUI-wide change (terminal TUIs
+ change look too). I think it is right (Ghostty, kitty, WezTerm all do it),
+ but it is a decision beyond tables.
+
+## Tests
+
+`zig build unit-test -Dplatform=gui -Dtest-filter="tables"`:
+`tables: a pipe table's columns, alignments and pads, by line`; `...every
+byte's cell maps back to it, and every pad cell to the byte after it`; `...is
+drawn aligned, its bytes in order, the caret and a click on each byte's cell`
+(also the look); `...typing in a cell re-aligns the table live, and j/k keep
+the column shown`; `...an edit's tables, shifted and found again around it,
+are the whole text's` (1500 random edits); `...a big text's tables are read
+a frame's budget at a time`; `...wider than a wrapping pane is shown as its
+source`; `tables are the pipe_tables tree-sitter finds` (syntax.zig);
+`a box-drawing rule reaches its cell's edges` (gui.zig); `zz tables timings`
+(skipped without `TABLES_TIMES`). No layout change, so no rects invariant.