Markdown view

markdown(text) shows a Markdown document: headings, paragraphs with inline styles and links, bullet and numbered lists, block quotes, fenced code blocks and rules. It takes the width it is given and the height its content needs. It does not scroll and cannot be edited, so it fits in a chat bubble, a release note, a help page, or inside a scroll when the text can be long.

use day::prelude::*;

markdown(res::str::release_notes())

// A reply that arrives a token at a time.
let reply = Signal::new(String::new());
markdown(reply)
    .selectable_text()
    .code_accessory(move |code| {
        button(res::str::copy())
            .icon(Symbol::Copy)
            .icon_only()
            .plain()
            .action(move || {
                day_part_clipboard::set_text(&code.text());
            })
    })

The text is a literal, a localized message, a Signal<String> or a closure. For one styled paragraph inside other text, label(t).markdown() is lighter (text-runs). To edit styled text, use the text editor.

The UI snippets use generated res::str accessors from an app’s Fluent catalog; see the example messages and catalog setup.

The grammar

MarkdownResult
a line of text, blank-line separateda paragraph; a line break inside it is a space
a line ending in two spaces or \a line break inside the paragraph
# Heading to ###### Headinga heading, levels 1 to 6
- item, * item, + itema bullet list item
1. item, 1) itema numbered item; the list counts up from its first number
an item indented under anothera nested list
a paragraph indented under an itema second paragraph of that item
> texta block quote; quotes nest, and hold lists and code
three or more backticks or tildes, an optional language, the code, the same fencea code block
---, ***, ___a rule

Inside a paragraph, a heading or a list item the inline grammar applies: bold, italic, inline code, strikethrough, links and backslash escapes. Code blocks are literal.

A code fence that has not been closed yet runs to the end of the text, so code shows while it is still arriving. Tables, setext headings (a line of === under a title), indented code blocks, HTML blocks, images and reference-style links are read as paragraph text.

Options

BuilderEffect
.font(font)the font of paragraphs, list items, quotes and code (default Font::Body)
.color(c)the text color of every block: a constant, a signal or a closure
.spacing(s)the gap between blocks, a Space step or points (default Space::M)
.selectable_text()let the reader select and copy each block’s text
.on_link(f)handle a tapped link yourself
.code_accessory(f)a piece in every code block’s header
.block_ids(f)an element id for each block’s text

Headings take the platform’s title styles (Title, Title2, Title3, Headline, Subheadline, Footnote), so they follow the type ramp and the reader’s text size like every other label, and each announces itself to a screen reader as a heading of its level.

A link opens through open_link, the same policy as a link and a Markdown label: a #route target navigates in the app and any other target opens in the platform’s default handler. .on_link(f) replaces that for the whole view. Activation is Cap::TextLinks (text-runs).

Code blocks

A code block draws its code in the platform’s monospaced face on the platform’s card surface. Long lines wrap. When the fence names a language, the block’s header shows it.

.code_accessory(f) puts a piece of yours at the trailing edge of that header: a copy button, a “Run” button, a badge. The closure runs once per code block and gets a MarkdownCode. Its text() and language() read the block as it is at the moment they are called, so an action copies the whole code even when it was still streaming in when the button was built.

Copying is the app’s to do, because the clipboard is a part the app chooses to link:

markdown(reply).code_accessory(|code| {
    button(res::str::copy())
        .icon(Symbol::Copy)
        .icon_only()
        .plain()
        .action(move || {
            day_part_clipboard::set_text(&code.text());
        })
})

Selection

.selectable_text() makes each block selectable. A selection stays inside one block, because each block is its own native label (selectable text).

Streamed text

A reply from a language model arrives a few characters at a time, and each arrival changes the text. The view does two things so that the cost of one arrival does not grow with the length of the reply.

It parses only the block being written. MarkdownDocument::update finds the first byte that differs from the text it holds, goes back to the last top-level block boundary before it, and parses from there. A boundary is a line start with no list, quote, paragraph or code fence open, so everything before it is settled whatever follows.

It keeps the rows it has. Each block is a row, and a row whose block kept its shape gets the new text through a signal: one native label patch. A row is built again only when its shape changes (a paragraph that turned into a heading, a list item that gained a level), and rows are added and removed at the end as blocks start and go away.

Appending a word to the last paragraph of a long reply therefore costs one block parse and one label update. crates/day-pieces/tests/text_mock.rs asserts exactly that against the mock toolkit’s operation log, and crates/day-spec/src/markdown.rs checks the incremental result against a full parse at every prefix of a sample document.

An edit in the middle of the text is handled the same way, from the boundary before the edit.

How it is built

The view is composed in day-pieces from native labels and Day’s containers. There is one implementation for every toolkit and no toolkit duty behind it.

BlockBuilt from
paragraph, headinga label(…).markdown()
list itema marker label (a bullet or the number) beside the item’s content, indented one step per level
block quotea vertical divider beside the quoted blocks, one per level
code blocka monospaced label in a .card(), under a header row
rulea divider

A native rich-text view per toolkit was the alternative. It would select across blocks, which this composition does not. It would also be eight implementations of block layout, list markers and code surfaces with eight sets of differences, and each would need its own self-sizing and its own incremental update. The label already has the text behavior that matters here on every toolkit: wrapping, runs, links, selection, accessibility and Dynamic Type. The composition inherits all of it, and inherits every later improvement to the label.

The block model is public in day_spec::markdown: a MarkdownDocument is a flat list of MarkdownBlocks, each a paragraph, heading, code block or rule with its quote depth, its list depth and its marker. An app that wants a different look can lay those blocks out itself.

Testing

.block_ids(|i| id!(reply_block, i)) gives the text of block i the id reply_block:<i>, so a test or a DayScript step can read it:

d.assert_text("reply_block:0", "Release notes").await?;

A rule has no text and takes no id. The conformance cases markdown-view-blocks, markdown-view-streams and markdown-view-code-accessory run on every toolkit.

Toolkit support

The view draws with labels, so each toolkit’s label limits apply to it unchanged: line limits, truncation and selection reports in text, and decoration styles and run small capitals in text-runs. The view adds none of its own.

Limits

  • Selection does not cross blocks.
  • A code block wraps long lines; it does not scroll sideways.
  • Tables are not parsed.
  • Images and other inline attachments are not shown.