diff --git a/AGENTS.md b/AGENTS.md index 4342b49..fc2a92b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,7 +13,7 @@ Ely GPUI Component. A component library for GPUI, in light and dark. - Web views: `wry` 0.57 (Apache-2.0 OR MIT, default features off, macOS only) lays a child WKWebView over the window. - Terminal: `alacritty_terminal` 0.26 (Apache-2.0, default features off, native only) for the grid, its parser and the pseudo-terminal; `futures` carries its events. `vte` 0.15 (Apache-2.0 OR MIT), the parser it re-exports, reads `AnsiText`'s codes alone, so colored output builds for wasm32. - Diffs: `similar` 3.2 (Apache-2.0) for line and word diffs and three-way merges; its `unicode` feature splits words at punctuation. -- Markdown: `markdown` 1.0.0 (markdown-rs, MIT) reads GitHub's flavor and math into a syntax tree with byte positions for `MarkdownRenderer`, `MarkdownEditor`, the highlights, block ranges and outline. `MarkdownRenderer` draws display math through `typography::Latex`, a ```` ```mermaid ```` block through `documents::Diagram`, and pictures from the owner's folder (`base`) or `data:` addresses (`base64` 0.22, MIT OR Apache-2.0); web pictures stay unloaded. Inline math shows as TeX: gpui text carries no inline pictures. Inline it reads as Typora's defaults: `:shortcode:` turns to its emoji as GitHub reads it (the `emojis` crate's names, GitHub's today, so `:cricket:` is the insect; read after escapes and references, so `\:smile:` turns too; inside an autolink or `` it stays text; within one DOM text node, which filtered tags do not split, the first `:name:`-shaped run decides for all: blank text or a space before it turns every shortcode, else none, so `x:smile: :smile:` stays), inline HTML's `u`, `b`/`strong`, `i`/`em`, `s`/`del`/`strike`, `code`/`kbd`, `mark`, `br` and `a href` draw as what they mean GFM's filtered tags (`script`, `style`, `title`, `textarea`, `iframe`, `xmp`, `noembed`, `noframes`, `plaintext`) show as text, and other tags, hyphenated names too, vanish, leaving their text; a tag's name runs to white space or `/`, as HTML5 reads it; attribute values split on ASCII whitespace alone and decode as HTML decodes them; each Markdown container is the element GitHub writes (`em`, `strong`, `del`, `a`), on one stack with the tags and repaired as HTML5 repairs: an end tag closes the innermost element of its name and all above it, of which only formatting elements (`a`, `b`, `code`, `em`, `i`, `s`, `strike`, `strong`, `u`) reopen, a new `a` ends the open one and an `a` without `href` links nothing; other tags are not tracked, and `
` breaks as `
` does; and a footnote reference is its number in superscript, numbered by first reference, as its definition is; one `~` still strikes. At the root, blocks read as GitHub shows them: a quote whose first line is plain text reading `[!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]` or `[!CAUTION]` in any case, after escapes and references, spaces and tabs around it, with more after it, is an alert under its title (Important in the palette's violet, `syntax.keyword`, read at 4.5:1); a paragraph that is `[toc]` alone, as Typora reads it, lists every heading by depth, and a press on one reveals it as a link press does (`MarkdownDocument`'s `reveal`), the heading found where `CodeEditor` anchors carried it through each edit since the read, gone if an edit or an undo took it, and a secondary press acts on press, since a block writing back moves the list; front matter shows in a box without its fences; an HTML block shows its text with the inline tags above, white space collapsed and owed as a browser lays it, block elements breaking lines and closing what opened inside them, HTML5's start tags ending an open `p`, `fieldset` and `menu` too, and an `li` start an `li`, a `dd` or `dt` start either, as HTML5 ends them, comments dropped, the filtered tags shown as text, and an unclosed tag dropping the rest; a rule is a 2px `border_strong` line; bullets go •, ◦, ▪ by list depth, ordered lists counted. `MarkdownDocument` holds a whole file in one `CodeEditor` (text and undo, colored by `CodeEditor::highlighter` with `markdown_highlights`): visual draws the file's top-level blocks in a gpui `list`, a pressed block opening as its source in a `TextInput` whose typing is the document's text at once and whose write-back is one undo step; source is the editor; preview draws without presses. A written-back block, a mode switch or a new text is read at once up to 128 KiB, longer ones on the background executor; typing in source or split reads 300 ms after the last key, off the main thread (markdown-rs grows with the square of a paragraph's lines: 40,000 lines take 0.9 s). Texts past `LARGEST_READ` (2 MiB) are never read: no blocks, no outline. A new read keeps the list's blocks alike at both ends. One caret serves every mode: the editor's selection, which a written-back block moves; `set_caret` and `set_top_line` set caret and view apart; a top line asked (numbered, so a late frame callback finishes only its own ask; new text places it again, clamped to the text as it then is) waits for the read, lands on its block, then a frame later at its share of the block's height; `reveal` is such an ask with the caret at its line; a switch between source and the list keeps the top line, one between visual and preview keeps the list's scroll as it is. A block opens only when the read is of the text as it is now. A pressed block keeps its identity across the write-back of the one before it. Blocks are Tab stops that Enter or Space opens; preview takes no presses, undo or redo. `CodeEditor` keeps at most 64 MiB of undo and redo text, dropping the oldest undo and then the farthest redo after every record, composition, undo and redo. `BlockData::from_markdown` and its export still read with `pulldown-cmark` 0.13 (MIT, default features off); it adds GitHub's alerts, a callout's form, and reads each field's inline Markdown from the source by offset, as written. +- Markdown: `markdown` 1.0.0 (markdown-rs, MIT) reads GitHub's flavor and math into a syntax tree with byte positions for `MarkdownRenderer`, `MarkdownEditor`, the highlights, block ranges and outline. `MarkdownRenderer` draws display math through `typography::Latex`, a ```` ```mermaid ```` block through `documents::Diagram`, and pictures from the owner's folder (`base`) or `data:` addresses (`base64` 0.22, MIT OR Apache-2.0); web pictures stay unloaded. Inline math shows as TeX: gpui text carries no inline pictures. Inline it reads as Typora's defaults: `:shortcode:` turns to its emoji as GitHub reads it (the `emojis` crate's names, GitHub's today, so `:cricket:` is the insect; read after escapes and references, so `\:smile:` turns too; inside an autolink or `` it stays text; within one DOM text node, which filtered tags do not split, the first `:name:`-shaped run decides for all: blank text or a space before it turns every shortcode, else none, so `x:smile: :smile:` stays), inline HTML's `u`, `b`/`strong`, `i`/`em`, `s`/`del`/`strike`, `code`/`kbd`, `mark`, `br` and `a href` draw as what they mean GFM's filtered tags (`script`, `style`, `title`, `textarea`, `iframe`, `xmp`, `noembed`, `noframes`, `plaintext`) show as text, and other tags, hyphenated names too, vanish, leaving their text; a tag's name runs to white space or `/`, as HTML5 reads it; attribute values split on ASCII whitespace alone and decode as HTML decodes them; each Markdown container is the element GitHub writes (`em`, `strong`, `del`, `a`), on one stack with the tags and repaired as HTML5 repairs: an end tag closes the innermost element of its name and all above it, of which only formatting elements (`a`, `b`, `code`, `em`, `i`, `s`, `strike`, `strong`, `u`) reopen, a new `a` ends the open one and an `a` without `href` links nothing; other tags are not tracked, and `
` breaks as `
` does; and a footnote reference is its number in superscript, numbered by first reference, as its definition is; one `~` still strikes. At the root, blocks read as GitHub shows them: a quote whose first line is plain text reading `[!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]` or `[!CAUTION]` in any case, after escapes and references, spaces and tabs around it, with more after it, is an alert under its title (Important in the palette's violet, `syntax.keyword`, read at 4.5:1); a paragraph that is `[toc]` alone, as Typora reads it, lists every heading by depth, and a press on one reveals it as a link press does (`MarkdownDocument`'s `reveal`), the heading found where `CodeEditor` anchors carried it through each edit since the read, gone if an edit or an undo took it, and a secondary press acts on press, since a block writing back moves the list; front matter shows in a box without its fences; an HTML block shows its text with the inline tags above, white space collapsed and owed as a browser lays it, block elements breaking lines and closing what opened inside them, HTML5's start tags ending an open `p`, `fieldset` and `menu` too, and an `li` start an `li`, a `dd` or `dt` start either, as HTML5 ends them, comments dropped, the filtered tags shown as text, and an unclosed tag dropping the rest; a rule is a 2px `border_strong` line; bullets go •, ◦, ▪ by list depth, ordered lists counted. Exports read a tree as the drawing does through `MarkdownReader` (`block` gives its `MarkdownBlock`s, `inline` its text, `note` and `label` its footnotes, `headings` the `[toc]` list), one fresh stack per paragraph, heading or cell. `MarkdownDocument` holds a whole file in one `CodeEditor` (text and undo, colored by `CodeEditor::highlighter` with `markdown_highlights`): visual draws the file's top-level blocks in a gpui `list`, a pressed block opening as its source in a `TextInput` whose typing is the document's text at once and whose write-back is one undo step; source is the editor; preview draws without presses. A written-back block, a mode switch or a new text is read at once up to 128 KiB, longer ones on the background executor; typing in source or split reads 300 ms after the last key, off the main thread (markdown-rs grows with the square of a paragraph's lines: 40,000 lines take 0.9 s). Texts past `LARGEST_READ` (2 MiB) are never read: no blocks, no outline. A new read keeps the list's blocks alike at both ends. One caret serves every mode: the editor's selection, which a written-back block moves; `set_caret` and `set_top_line` set caret and view apart; a top line asked (numbered, so a late frame callback finishes only its own ask; new text places it again, clamped to the text as it then is) waits for the read, lands on its block, then a frame later at its share of the block's height; `reveal` is such an ask with the caret at its line; a switch between source and the list keeps the top line, one between visual and preview keeps the list's scroll as it is. A block opens only when the read is of the text as it is now. A pressed block keeps its identity across the write-back of the one before it. Blocks are Tab stops that Enter or Space opens; preview takes no presses, undo or redo. `CodeEditor` keeps at most 64 MiB of undo and redo text, dropping the oldest undo and then the farthest redo after every record, composition, undo and redo. `BlockData::from_markdown` and its export still read with `pulldown-cmark` 0.13 (MIT, default features off); it adds GitHub's alerts, a callout's form, and reads each field's inline Markdown from the source by offset, as written. - Pictures: `image` 0.25 (MIT OR Apache-2.0), the crate gpui decodes with, default features off; it turns decoded frames and rims map tiles. - Math and diagrams: RaTeX 0.1.14 (`ratex-parser`, `ratex-layout`, `ratex-svg` with `embed-fonts`, `ratex-types`; MIT, KaTeX's fonts OFL) typesets `Latex` to SVG with outlined glyphs; `mermaid-rs-renderer` 0.3.1 (MIT, default features off) draws `Diagram`. Both go through gpui's `SvgRenderer` at the window's scale, loaded as gpui assets off the main thread; `usvg` 0.46, gpui's own, reads a diagram's size. A RaTeX or Mermaid panic on parsed input becomes the element's error. Each element holds its picture through `primitives::held`: a new source, or the element leaving the window, removes the old asset from gpui's cache and drops its image from the atlas after the frame. - Maps: Natural Earth's 110m countries (public domain). `assets/maps/countries.geojson`, trimmed by `scripts/countries.py` to an ISO code, a name and positions to 0.01°, backs `maps::WorldMap`; the gallery's tiles are cut from the same file, z0 to z3, by `scripts/tiles.py` with Pillow. diff --git a/src/documents/mod.rs b/src/documents/mod.rs index 88ddc32..26d9eb8 100644 --- a/src/documents/mod.rs +++ b/src/documents/mod.rs @@ -58,8 +58,7 @@ pub use thumbs::PageThumbnailList; pub use todo::{Checklist, TodoItem}; pub use toolbar::FixedFormatToolbar; pub use tree::{ - AlertKind, Inline, InlineTag, Shortcodes, Style, alert, headings, html_block_text, inline_tag, - is_toc, + AlertKind, Inline, Node as MarkdownBlock, Reader as MarkdownReader, Style, alert, is_toc, }; pub(crate) use viewer::step as zoom_step; pub use viewer::{DocPage, DocumentViewer, PageHit, PageNote}; diff --git a/src/documents/tree/blocks.rs b/src/documents/tree/blocks.rs index 3d283fb..c33df80 100644 --- a/src/documents/tree/blocks.rs +++ b/src/documents/tree/blocks.rs @@ -1,7 +1,7 @@ use markdown::mdast; use super::{Inline, Node, Reader, Run, html}; -use crate::documents::markdown::{file_tree, span}; +use crate::documents::markdown::span; /// A heading anywhere in the file. #[derive(Clone, Debug, PartialEq)] @@ -77,7 +77,7 @@ impl Reader<'_> { } /// An HTML block's text, as a browser shows it. -pub fn html_block_text(written: &str) -> Inline { +pub(super) fn html_block_text(written: &str) -> Inline { let mut run = Run::default(); let mut rest = written; while let Some(at) = rest.find('<') { @@ -232,11 +232,6 @@ pub fn is_toc(node: &mdast::Node, source: &str) -> bool { && source[span(node)].trim().eq_ignore_ascii_case("[toc]") } -/// Every heading in `text`, as `[toc]` lists them. -pub fn headings(text: &str) -> Vec { - Reader::new(text, &file_tree(text)).headings -} - /// A plain first line naming a kind, and what follows. fn marker(children: &[mdast::Node]) -> Option<(AlertKind, Vec)> { let mut line = String::new(); diff --git a/src/documents/tree/emoji.rs b/src/documents/tree/emoji.rs index f737380..bec179a 100644 --- a/src/documents/tree/emoji.rs +++ b/src/documents/tree/emoji.rs @@ -49,7 +49,7 @@ fn candidate(text: &str) -> Option { /// One DOM text node's shortcodes, as GitHub reads them. #[derive(Default)] -pub struct Shortcodes { +pub(super) struct Shortcodes { /// Settled by the node's first `:name:`. reads: Option, /// Text before it held more than white space. @@ -59,12 +59,12 @@ pub struct Shortcodes { impl Shortcodes { /// A new DOM text node starts. - pub fn split(&mut self) { + pub(super) fn split(&mut self) { *self = Self::default(); } /// Blank or spaced text before the first reads them all. - pub fn read(&mut self, text: &str) -> String { + pub(super) fn read(&mut self, text: &str) -> String { if self.reads.is_none() { let at = candidate(text); let lead = &text[..at.unwrap_or(text.len())]; diff --git a/src/documents/tree/html.rs b/src/documents/tree/html.rs index 64acec5..c5d45ed 100644 --- a/src/documents/tree/html.rs +++ b/src/documents/tree/html.rs @@ -98,7 +98,7 @@ pub(crate) fn breaks(name: &str) -> bool { /// What one inline HTML tag does, as GitHub shows it. #[derive(Clone, Debug, PartialEq)] -pub enum InlineTag { +pub(super) enum InlineTag { /// Opens `name`; an anchor styles only with an address. Open { name: String, @@ -114,7 +114,7 @@ pub enum InlineTag { } /// What the inline HTML `written` does. -pub fn inline_tag(written: &str) -> InlineTag { +pub(super) fn inline_tag(written: &str) -> InlineTag { let Some(tag) = tag(written) else { return InlineTag::Gone; }; diff --git a/src/documents/tree/mod.rs b/src/documents/tree/mod.rs index 920d34e..4d3e49d 100644 --- a/src/documents/tree/mod.rs +++ b/src/documents/tree/mod.rs @@ -8,9 +8,9 @@ mod blocks; mod emoji; mod html; -pub use blocks::{AlertKind, DocumentHeading, alert, headings, html_block_text, is_toc}; -pub use emoji::Shortcodes; -pub use html::{InlineTag, inline_tag}; +use blocks::html_block_text; +pub use blocks::{AlertKind, DocumentHeading, alert, is_toc}; +use html::InlineTag; /// How a stretch of inline text prints. #[derive(Clone, Copy, Debug, PartialEq, Eq)] @@ -80,11 +80,12 @@ pub enum Node { } /// A tree read against its source and its link definitions. -pub(crate) struct Reader<'a> { +pub struct Reader<'a> { source: &'a str, urls: HashMap, /// Footnotes numbered by their first reference. notes: HashMap, + /// Every heading, as `[toc]` lists them. pub headings: Vec, } @@ -243,7 +244,7 @@ pub fn parse(markdown: &str) -> Vec { impl<'a> Reader<'a> { /// A reader of `root`, parsed from `source`. - pub(crate) fn new(source: &'a str, root: &mdast::Node) -> Self { + pub fn new(source: &'a str, root: &mdast::Node) -> Self { let mut nodes = Vec::new(); walk(root, &mut nodes); let (mut urls, mut notes, mut headings) = (HashMap::new(), HashMap::new(), Vec::new()); @@ -298,7 +299,8 @@ impl<'a> Reader<'a> { .expect("a reference names a definition") } - pub(crate) fn block(&self, node: &mdast::Node, out: &mut Vec) { + /// `node`'s blocks, as the drawing reads them. + pub fn block(&self, node: &mdast::Node, out: &mut Vec) { match node { mdast::Node::Paragraph(paragraph) => self.paragraph(node, ¶graph.children, out), mdast::Node::Heading(heading) => { @@ -350,13 +352,7 @@ impl<'a> Reader<'a> { } mdast::Node::ThematicBreak(_) => out.push(Node::Rule), mdast::Node::FootnoteDefinition(note) => out.push(Node::Footnote { - label: match self.notes.get(¬e.identifier) { - Some(number) => number.to_string(), - None => note - .label - .clone() - .unwrap_or_else(|| note.identifier.clone()), - }, + label: self.label(note), body: self.nested(¬e.children), }), mdast::Node::Html(html) => text_block(html_block_text(&html.value), out), @@ -381,8 +377,21 @@ impl<'a> Reader<'a> { text_block(run.cut(), out); } + /// A footnote's number, by its first reference. + pub fn note(&self, identifier: &str) -> Option { + self.notes.get(identifier).copied() + } + + /// A note's label: its number, once referenced. + pub fn label(&self, note: &mdast::FootnoteDefinition) -> String { + match self.note(¬e.identifier) { + Some(number) => number.to_string(), + None => note.label.clone().unwrap_or_else(|| note.identifier.clone()), + } + } + /// Inline text where images draw as their alt text. - pub(crate) fn inline(&self, nodes: &[mdast::Node]) -> Inline { + pub fn inline(&self, nodes: &[mdast::Node]) -> Inline { let mut run = Run::default(); for node in nodes { self.inline_into(node, &mut run, &mut Images::Alt);