Skip to main content

text_document/
fragment.rs

1//! DocumentFragment — format-agnostic rich text interchange type.
2
3use crate::{CharVerticalAlignment, InlineContent, LINE_SEPARATOR, ListStyle};
4use frontend::common::parser_tools::content_parser::{
5    ParsedBlock, ParsedElement, ParsedSpan, html_line_ends_before, html_text_ends_open,
6    push_html_text, split_block_at_line_breaks,
7};
8use frontend::common::parser_tools::fragment_schema::{
9    FragmentBlock, FragmentData, FragmentElement, FragmentListStarts, FragmentQuoting,
10    FragmentTable, FragmentTableCell, as_a_whole_text, fragment_from_json,
11    fragment_with_list_starts_to_json,
12};
13
14/// A piece of rich text that can be inserted into a [`TextDocument`](crate::TextDocument).
15///
16/// `DocumentFragment` is the clipboard/interchange type. It carries
17/// blocks, per-character format runs, image anchors, and structural
18/// metadata in a format-agnostic internal representation.
19#[derive(Debug, Clone)]
20pub struct DocumentFragment {
21    data: String,
22    plain_text: String,
23}
24
25impl DocumentFragment {
26    /// Create an empty fragment.
27    pub fn new() -> Self {
28        Self {
29            data: String::new(),
30            plain_text: String::new(),
31        }
32    }
33
34    /// Create a fragment from plain text.
35    ///
36    /// Builds valid fragment data so the fragment can be inserted via
37    /// [`TextCursor::insert_fragment`](crate::TextCursor::insert_fragment).
38    pub fn from_plain_text(text: &str) -> Self {
39        let blocks: Vec<FragmentBlock> = text
40            .split('\n')
41            .map(|line| FragmentBlock {
42                plain_text: line.to_string(),
43                elements: vec![FragmentElement {
44                    content: InlineContent::Text(line.to_string()),
45                    fmt_font_family: None,
46                    fmt_font_point_size: None,
47                    fmt_font_weight: None,
48                    fmt_font_bold: None,
49                    fmt_font_italic: None,
50                    fmt_font_underline: None,
51                    fmt_font_overline: None,
52                    fmt_font_strikeout: None,
53                    fmt_letter_spacing: None,
54                    fmt_word_spacing: None,
55                    fmt_anchor_href: None,
56                    fmt_anchor_names: vec![],
57                    fmt_is_anchor: None,
58                    fmt_tooltip: None,
59                    fmt_underline_style: None,
60                    fmt_vertical_alignment: None,
61                }],
62                heading_level: None,
63                list: None,
64                alignment: None,
65                indent: None,
66                text_indent: None,
67                marker: None,
68                top_margin: None,
69                bottom_margin: None,
70                left_margin: None,
71                right_margin: None,
72                tab_positions: vec![],
73                line_height: None,
74                non_breakable_lines: None,
75                page_break_before: None,
76                direction: None,
77                background_color: None,
78                is_code_block: None,
79                code_language: None,
80                hyphenate: None,
81                language: None,
82            })
83            .collect();
84
85        let data = serde_json::to_string(&FragmentData {
86            blocks,
87            tables: vec![],
88        })
89        .expect("fragment serialization should not fail");
90
91        Self {
92            data,
93            plain_text: text.to_string(),
94        }
95    }
96
97    /// Create a fragment from HTML, as a clipboard carries a passage copied from a web page
98    /// or another application.
99    ///
100    /// A `<pre>` goes in as paragraphs, one for each of its lines, each keeping its spaces,
101    /// where [`TextDocument::set_html`](crate::TextDocument::set_html) loads it as a code
102    /// block: a preformatted passage pasted into prose is most often a poem or a letter set
103    /// line by line, and a code block keeps no emphasis and takes no footnote reference.
104    pub fn from_html(html: &str) -> Self {
105        let parsed = frontend::common::parser_tools::content_parser::parse_html_elements(html);
106        parsed_elements_to_fragment(parsed, ParsedFrom::Html)
107    }
108
109    /// Create a fragment from Markdown. The fragment is a whole text: see
110    /// [`from_djot`](Self::from_djot).
111    pub fn from_markdown(markdown: &str) -> Self {
112        let parsed = frontend::common::parser_tools::content_parser::parse_markdown(markdown);
113        parsed_elements_to_fragment(parsed, ParsedFrom::SavedSyntax)
114    }
115
116    /// Create a fragment from djot markup. Paste always uses the lossless
117    /// default [`crate::DjotImportOptions`]; per-feature selection is exposed on
118    /// the document-level import path (`TextDocument::set_djot_with_options`).
119    ///
120    /// The fragment is a whole text: inserted over a selection holding the whole of a
121    /// text, it reads as the same Djot loaded, even as a single plain paragraph (see
122    /// [`TextCursor::insert_fragment`](crate::TextCursor::insert_fragment)).
123    pub fn from_djot(djot: &str) -> Self {
124        let parsed = frontend::common::parser_tools::content_parser::parse_djot(
125            djot,
126            &frontend::common::parser_tools::DjotImportOptions::default(),
127        );
128        parsed_elements_to_fragment(parsed, ParsedFrom::SavedSyntax)
129    }
130
131    /// Create a fragment from an entire document. The fragment is a whole text: see
132    /// [`from_djot`](Self::from_djot).
133    pub fn from_document(doc: &crate::TextDocument) -> crate::Result<Self> {
134        let inner = doc.inner.lock();
135        // Use i64::MAX as anchor to ensure the full document is captured.
136        // Document positions include inter-block gaps, so character_count
137        // alone would truncate the last block.
138        let dto = frontend::document_inspection::ExtractFragmentDto {
139            position: 0,
140            anchor: i64::MAX,
141        };
142        let result =
143            frontend::commands::document_inspection_commands::extract_fragment(&inner.ctx, &dto)?;
144        Ok(Self::from_raw(
145            as_a_whole_text(&result.fragment_data),
146            result.plain_text,
147        ))
148    }
149
150    /// Create a fragment from the serialized internal format.
151    pub(crate) fn from_raw(data: String, plain_text: String) -> Self {
152        Self { data, plain_text }
153    }
154
155    /// Export the fragment as plain text.
156    pub fn to_plain_text(&self) -> &str {
157        &self.plain_text
158    }
159
160    /// Export the fragment as HTML.
161    pub fn to_html(&self) -> String {
162        if self.data.is_empty() {
163            return String::from("<html><head><meta charset=\"utf-8\"></head><body></body></html>");
164        }
165
166        let (fragment_data, list_starts) = match fragment_from_json(&self.data) {
167            Ok(carried) => (carried.data, carried.list_starts),
168            Err(_) => {
169                return String::from(
170                    "<html><head><meta charset=\"utf-8\"></head><body></body></html>",
171                );
172            }
173        };
174
175        let mut body = String::new();
176        let blocks = &fragment_data.blocks;
177
178        // Single inline-only block with no tables: emit inline HTML without block wrapper
179        if blocks.len() == 1 && blocks[0].is_inline_only() && fragment_data.tables.is_empty() {
180            push_inline_html(&mut body, &blocks[0].elements);
181            return format!(
182                "<html><head><meta charset=\"utf-8\"></head><body>{}</body></html>",
183                body
184            );
185        }
186
187        // Sort tables by block_insert_index so we can interleave them
188        let mut sorted_tables: Vec<&FragmentTable> = fragment_data.tables.iter().collect();
189        sorted_tables.sort_by_key(|t| t.block_insert_index);
190        let mut table_cursor = 0;
191
192        let mut i = 0;
193
194        while i < blocks.len() {
195            // Insert any tables whose block_insert_index == i
196            while table_cursor < sorted_tables.len()
197                && sorted_tables[table_cursor].block_insert_index <= i
198            {
199                push_table_html(&mut body, sorted_tables[table_cursor]);
200                table_cursor += 1;
201            }
202
203            let block = &blocks[i];
204
205            if let Some(ref list) = block.list {
206                let is_ordered = is_ordered_list_style(&list.style);
207                let list_tag = if is_ordered { "ol" } else { "ul" };
208                body.push('<');
209                body.push_str(list_tag);
210                // Where the list starts, when it is not 1.
211                if let Some(start) = list_starts.get(i).filter(|_| is_ordered) {
212                    body.push_str(&format!(" start=\"{start}\""));
213                }
214                body.push('>');
215
216                while i < blocks.len() {
217                    let b = &blocks[i];
218                    match &b.list {
219                        Some(l) if is_ordered_list_style(&l.style) == is_ordered => {
220                            body.push_str("<li>");
221                            push_inline_html(&mut body, &b.elements);
222                            body.push_str("</li>");
223                            i += 1;
224                        }
225                        _ => break,
226                    }
227                }
228
229                body.push_str("</");
230                body.push_str(list_tag);
231                body.push('>');
232            } else if let Some(level) = block.heading_level {
233                let n = level.clamp(1, 6);
234                body.push_str(&format!("<h{}>", n));
235                push_inline_html(&mut body, &block.elements);
236                body.push_str(&format!("</h{}>", n));
237                i += 1;
238            } else {
239                // Emit block-level formatting as inline styles (ISSUE-19)
240                let style = block_style_attr(block);
241                if style.is_empty() {
242                    body.push_str("<p>");
243                } else {
244                    body.push_str(&format!("<p style=\"{}\">", style));
245                }
246                push_inline_html(&mut body, &block.elements);
247                body.push_str("</p>");
248                i += 1;
249            }
250        }
251
252        // Emit any remaining tables after all blocks
253        while table_cursor < sorted_tables.len() {
254            push_table_html(&mut body, sorted_tables[table_cursor]);
255            table_cursor += 1;
256        }
257
258        format!(
259            "<html><head><meta charset=\"utf-8\"></head><body>{}</body></html>",
260            body
261        )
262    }
263
264    /// Export the fragment as Markdown.
265    pub fn to_markdown(&self) -> String {
266        if self.data.is_empty() {
267            return String::new();
268        }
269
270        let (fragment_data, list_starts) = match fragment_from_json(&self.data) {
271            Ok(carried) => (carried.data, carried.list_starts),
272            Err(_) => return String::new(),
273        };
274
275        // (rendered_text, is_list_item) — used for join logic
276        let mut parts: Vec<(String, bool)> = Vec::new();
277        let mut prev_was_list = false;
278        let mut list_counter: u32 = 0;
279
280        // Sort tables by block_insert_index for interleaving
281        let mut sorted_tables: Vec<&FragmentTable> = fragment_data.tables.iter().collect();
282        sorted_tables.sort_by_key(|t| t.block_insert_index);
283        let mut table_cursor = 0;
284
285        for (blk_idx, block) in fragment_data.blocks.iter().enumerate() {
286            // Insert tables before this block index
287            while table_cursor < sorted_tables.len()
288                && sorted_tables[table_cursor].block_insert_index <= blk_idx
289            {
290                parts.push((render_table_markdown(sorted_tables[table_cursor]), false));
291                prev_was_list = false;
292                list_counter = 0;
293                table_cursor += 1;
294            }
295
296            // An ATX heading is one line, so its line breaks are spaces.
297            let line_break = if block.heading_level.is_some() {
298                " "
299            } else {
300                "\\\n"
301            };
302            let inline_text = render_inline_markdown(&block.elements, line_break);
303            let is_list = block.list.is_some();
304
305            let indent_prefix = match block.indent {
306                Some(n) if n > 0 => "  ".repeat(n as usize),
307                _ => String::new(),
308            };
309
310            if let Some(level) = block.heading_level {
311                let n = level.clamp(1, 6) as usize;
312                let prefix = "#".repeat(n);
313                parts.push((format!("{} {}", prefix, inline_text), false));
314                prev_was_list = false;
315                list_counter = 0;
316            } else if let Some(ref list) = block.list {
317                let is_ordered = is_ordered_list_style(&list.style);
318                if !prev_was_list {
319                    // From where the list starts, when it is not 1.
320                    list_counter = list_starts
321                        .get(blk_idx)
322                        .and_then(|start| u32::try_from(start.saturating_sub(1)).ok())
323                        .unwrap_or(0);
324                }
325                if is_ordered {
326                    list_counter += 1;
327                    parts.push((
328                        format!("{}{}. {}", indent_prefix, list_counter, inline_text),
329                        true,
330                    ));
331                } else {
332                    parts.push((format!("{}- {}", indent_prefix, inline_text), true));
333                }
334                prev_was_list = true;
335            } else {
336                if indent_prefix.is_empty() {
337                    parts.push((inline_text, false));
338                } else {
339                    parts.push((format!("{}{}", indent_prefix, inline_text), false));
340                }
341                prev_was_list = false;
342                list_counter = 0;
343            }
344
345            if !is_list {
346                prev_was_list = false;
347            }
348        }
349
350        // Emit remaining tables after all blocks
351        while table_cursor < sorted_tables.len() {
352            parts.push((render_table_markdown(sorted_tables[table_cursor]), false));
353            table_cursor += 1;
354        }
355
356        // Join: list items with \n, others with \n\n
357        let mut result = String::new();
358        for (idx, (text, is_list)) in parts.iter().enumerate() {
359            if idx > 0 {
360                let (_, prev_is_list) = &parts[idx - 1];
361                if *prev_is_list && *is_list {
362                    result.push('\n');
363                } else {
364                    result.push_str("\n\n");
365                }
366            }
367            result.push_str(text);
368        }
369
370        result
371    }
372
373    /// Returns true if the fragment contains no text or elements.
374    pub fn is_empty(&self) -> bool {
375        self.plain_text.is_empty()
376    }
377
378    /// Returns the serialized internal representation.
379    pub(crate) fn raw_data(&self) -> &str {
380        &self.data
381    }
382}
383
384impl Default for DocumentFragment {
385    fn default() -> Self {
386        Self::new()
387    }
388}
389
390// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
391// Shared helpers (used by both to_html and to_markdown)
392// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
393
394fn is_ordered_list_style(style: &ListStyle) -> bool {
395    matches!(
396        style,
397        ListStyle::Decimal
398            | ListStyle::LowerAlpha
399            | ListStyle::UpperAlpha
400            | ListStyle::LowerRoman
401            | ListStyle::UpperRoman
402    )
403}
404
405// ── HTML helpers ────────────────────────────────────────────────
406
407fn escape_html(s: &str) -> String {
408    let mut out = String::with_capacity(s.len());
409    for c in s.chars() {
410        match c {
411            '&' => out.push_str("&amp;"),
412            '<' => out.push_str("&lt;"),
413            '>' => out.push_str("&gt;"),
414            '"' => out.push_str("&quot;"),
415            '\'' => out.push_str("&#x27;"),
416            // A raw CR in text content is normalised to LF by the HTML5 input
417            // preprocessor on re-import (CR-from-`&#xD;` survives, literal CR
418            // does not), which breaks serialiser idempotency. Emit it as a
419            // numeric reference so it round-trips losslessly.
420            '\r' => out.push_str("&#13;"),
421            _ => out.push(c),
422        }
423    }
424    out
425}
426
427/// Build a CSS `style` attribute value from block-level formatting (ISSUE-19).
428fn block_style_attr(block: &FragmentBlock) -> String {
429    use crate::Alignment;
430
431    let mut parts = Vec::new();
432    if let Some(ref alignment) = block.alignment {
433        let value = match alignment {
434            Alignment::Left => "left",
435            Alignment::Right => "right",
436            Alignment::Center => "center",
437            Alignment::Justify => "justify",
438        };
439        parts.push(format!("text-align: {}", value));
440    }
441    if let Some(n) = block.indent
442        && n > 0
443    {
444        parts.push(format!("margin-left: {}em", n));
445    }
446    if let Some(px) = block.text_indent
447        && px != 0
448    {
449        parts.push(format!("text-indent: {}px", px));
450    }
451    if let Some(px) = block.top_margin {
452        parts.push(format!("margin-top: {}px", px));
453    }
454    if let Some(px) = block.bottom_margin {
455        parts.push(format!("margin-bottom: {}px", px));
456    }
457    if let Some(px) = block.left_margin {
458        parts.push(format!("margin-left: {}px", px));
459    }
460    if let Some(px) = block.right_margin {
461        parts.push(format!("margin-right: {}px", px));
462    }
463    parts.join("; ")
464}
465
466fn push_inline_html(out: &mut String, elements: &[FragmentElement]) {
467    // Whether the text before an element, on its line, ends in whitespace a reader would
468    // collapse a space after it into (see `push_html_text`).
469    let mut after_space = true;
470    for (index, elem) in elements.iter().enumerate() {
471        let text = match &elem.content {
472            InlineContent::Text(t) => {
473                let ends_line =
474                    html_line_ends_before(elements[index + 1..].iter().map(|e| &e.content));
475                let mut html = String::new();
476                push_html_text(&mut html, t, after_space, ends_line, escape_html, "<br>");
477                after_space = html_text_ends_open(t, after_space);
478                html
479            }
480            // A reference carried onto the clipboard keeps its marker; the note
481            // body is not part of the fragment.
482            InlineContent::FootnoteRef { label } => {
483                after_space = false;
484                let id = escape_html(label);
485                out.push_str(&format!(
486                    "<a epub:type=\"noteref\" role=\"doc-noteref\" href=\"#fn-{id}\"><sup>{id}</sup></a>"
487                ));
488                continue;
489            }
490            InlineContent::Image {
491                name,
492                alt,
493                width,
494                height,
495                ..
496            } => {
497                after_space = false;
498                // This is the HTML written to the OS clipboard, so it is what
499                // another application receives on paste. It carried no `alt` at
500                // all, which made every copied image inaccessible in the target
501                // document.
502                let mut tag = format!(
503                    "<img src=\"{}\" alt=\"{}\"",
504                    escape_html(name),
505                    escape_html(alt)
506                );
507                if *width > 0 {
508                    tag.push_str(&format!(" width=\"{width}\""));
509                }
510                if *height > 0 {
511                    tag.push_str(&format!(" height=\"{height}\""));
512                }
513                tag.push('>');
514                tag
515            }
516            InlineContent::Empty => String::new(),
517        };
518
519        let is_monospace = elem
520            .fmt_font_family
521            .as_deref()
522            .is_some_and(|f| f == "monospace");
523        let is_bold = elem.fmt_font_bold.unwrap_or(false);
524        let is_italic = elem.fmt_font_italic.unwrap_or(false);
525        let is_underline = elem.fmt_font_underline.unwrap_or(false);
526        let is_strikeout = elem.fmt_font_strikeout.unwrap_or(false);
527        let is_anchor = elem.fmt_is_anchor.unwrap_or(false);
528        // Superscript and subscript are character formatting like the rest, and
529        // an exponent or a chemical index that lands on the baseline is simply
530        // the wrong text — so they belong in the clipboard payload alongside
531        // bold and italic rather than being dropped on the way out.
532        let vertical = elem.fmt_vertical_alignment.as_ref();
533
534        let mut result = text;
535
536        if is_monospace {
537            result = format!("<code>{}</code>", result);
538        }
539        if is_bold {
540            result = format!("<strong>{}</strong>", result);
541        }
542        if is_italic {
543            result = format!("<em>{}</em>", result);
544        }
545        if is_underline {
546            result = format!("<u>{}</u>", result);
547        }
548        if is_strikeout {
549            result = format!("<s>{}</s>", result);
550        }
551        match vertical {
552            Some(CharVerticalAlignment::SuperScript) => result = format!("<sup>{result}</sup>"),
553            Some(CharVerticalAlignment::SubScript) => result = format!("<sub>{result}</sub>"),
554            _ => {}
555        }
556        if is_anchor && let Some(ref href) = elem.fmt_anchor_href {
557            result = format!("<a href=\"{}\">{}</a>", escape_html(href), result);
558        }
559
560        out.push_str(&result);
561    }
562}
563
564/// Emit an HTML `<table>` for a `FragmentTable`.
565fn push_table_html(out: &mut String, table: &FragmentTable) {
566    out.push_str("<table>");
567    for row in 0..table.rows {
568        out.push_str("<tr>");
569        for col in 0..table.columns {
570            if let Some(cell) = table.cells.iter().find(|c| c.row == row && c.column == col) {
571                out.push_str("<td");
572                if cell.row_span > 1 {
573                    out.push_str(&format!(" rowspan=\"{}\"", cell.row_span));
574                }
575                if cell.column_span > 1 {
576                    out.push_str(&format!(" colspan=\"{}\"", cell.column_span));
577                }
578                out.push('>');
579                for (i, block) in cell.blocks.iter().enumerate() {
580                    if i > 0 {
581                        out.push_str("<br>");
582                    }
583                    push_inline_html(out, &block.elements);
584                }
585                out.push_str("</td>");
586            }
587            // Skip positions covered by spans — the HTML renderer handles them.
588        }
589        out.push_str("</tr>");
590    }
591    out.push_str("</table>");
592}
593
594// ── Markdown helpers ────────────────────────────────────────────
595
596fn escape_markdown(s: &str) -> String {
597    let mut out = String::with_capacity(s.len());
598    for c in s.chars() {
599        if matches!(
600            c,
601            '\\' | '`'
602                | '*'
603                | '_'
604                | '{'
605                | '}'
606                | '['
607                | ']'
608                | '('
609                | ')'
610                | '#'
611                | '+'
612                | '-'
613                | '.'
614                | '!'
615                | '|'
616                | '~'
617                | '<'
618                | '>'
619        ) {
620            out.push('\\');
621        }
622        out.push(c);
623    }
624    out
625}
626
627/// A block's inline content as Markdown, each line break inside it
628/// ([`LINE_SEPARATOR`]) written as `line_break`: a backslash hard break in a block, a
629/// space in a heading or a table cell, which are one line.
630///
631/// A break at the very end of the block is left out: a backslash there is not a hard
632/// break to a reader but the text `\`, and Markdown has nothing else to write it as. A
633/// code span cannot hold a hard break, so one over a break is written as one code span a
634/// line.
635fn render_inline_markdown(elements: &[FragmentElement], line_break: &str) -> String {
636    // The breaks the block ends with, in whichever elements hold them.
637    let mut trailing = 0usize;
638    for elem in elements.iter().rev() {
639        match &elem.content {
640            InlineContent::Text(t) => {
641                let kept = t.trim_end_matches(LINE_SEPARATOR);
642                trailing += t.len() - kept.len();
643                if !kept.is_empty() {
644                    break;
645                }
646            }
647            InlineContent::Empty => {}
648            _ => break,
649        }
650    }
651    let mut to_drop = trailing;
652    let trimmed: Vec<FragmentElement> = elements
653        .iter()
654        .rev()
655        .map(|elem| match &elem.content {
656            InlineContent::Text(t) if to_drop > 0 => {
657                let keep = t.len().saturating_sub(to_drop);
658                to_drop -= t.len() - keep;
659                FragmentElement {
660                    content: InlineContent::Text(t[..keep].to_string()),
661                    ..elem.clone()
662                }
663            }
664            _ => elem.clone(),
665        })
666        .collect::<Vec<_>>()
667        .into_iter()
668        .rev()
669        .collect();
670    let mut out = String::new();
671    for elem in &trimmed {
672        let raw_text = match &elem.content {
673            InlineContent::Text(t) => t.clone(),
674            // `name` was used as both alt and source, so a pasted image
675            // described itself with its filename.
676            InlineContent::Image { name, alt, .. } => format!("![{alt}]({name})"),
677            InlineContent::FootnoteRef { label } => format!("[^{label}]"),
678            InlineContent::Empty => String::new(),
679        };
680
681        let is_monospace = elem
682            .fmt_font_family
683            .as_deref()
684            .is_some_and(|f| f == "monospace");
685        let is_bold = elem.fmt_font_bold.unwrap_or(false);
686        let is_italic = elem.fmt_font_italic.unwrap_or(false);
687        let is_strikeout = elem.fmt_font_strikeout.unwrap_or(false);
688        let is_anchor = elem.fmt_is_anchor.unwrap_or(false);
689
690        if is_monospace {
691            // A code span is one line: one a line, the break between them.
692            let spans: Vec<String> = raw_text
693                .split(LINE_SEPARATOR)
694                .map(|line| {
695                    if line.is_empty() {
696                        String::new()
697                    } else {
698                        format!("`{line}`")
699                    }
700                })
701                .collect();
702            out.push_str(&spans.join(line_break));
703        } else {
704            let mut text = escape_markdown(&raw_text).replace(LINE_SEPARATOR, line_break);
705            if is_bold && is_italic {
706                text = format!("***{}***", text);
707            } else if is_bold {
708                text = format!("**{}**", text);
709            } else if is_italic {
710                text = format!("*{}*", text);
711            }
712            if is_strikeout {
713                text = format!("~~{}~~", text);
714            }
715            if is_anchor {
716                let href = elem.fmt_anchor_href.as_deref().unwrap_or("");
717                out.push_str(&format!("[{}]({})", text, href));
718            } else {
719                out.push_str(&text);
720            }
721        }
722    }
723    out
724}
725
726/// Render a `FragmentTable` as a pipe-delimited Markdown table.
727fn render_table_markdown(table: &FragmentTable) -> String {
728    let mut rows: Vec<Vec<String>> = vec![vec![String::new(); table.columns]; table.rows];
729
730    for cell in &table.cells {
731        let text: String = cell
732            .blocks
733            .iter()
734            .map(|b| render_inline_markdown(&b.elements, " "))
735            .collect::<Vec<_>>()
736            .join(" ");
737        if cell.row < table.rows && cell.column < table.columns {
738            rows[cell.row][cell.column] = text;
739        }
740    }
741
742    let mut out = String::new();
743    for (i, row) in rows.iter().enumerate() {
744        out.push_str("| ");
745        out.push_str(&row.join(" | "));
746        out.push_str(" |");
747        if i == 0 {
748            // Header separator
749            out.push('\n');
750            out.push('|');
751            for _ in 0..table.columns {
752                out.push_str(" --- |");
753            }
754        }
755        if i + 1 < rows.len() {
756            out.push('\n');
757        }
758    }
759    out
760}
761
762// ── Fragment construction from parsed content ───────────────────
763
764/// Convert parsed blocks (from HTML or Markdown parser) into a `DocumentFragment`.
765/// Convert a `ParsedSpan` to a `FragmentElement`.
766/// The plain text of a run of parsed spans, with an image standing as its
767/// `U+FFFC` sentinel.
768///
769/// That sentinel is the convention the *extract* side already writes (see
770/// `extract_fragment_uc`), and it is what `insert_fragment_uc` positions each
771/// `ImageAnchor` against — an image with no character in the text has nothing
772/// to anchor to, and every format run after it lands three bytes early.
773fn spans_plain_text(spans: &[ParsedSpan]) -> String {
774    spans
775        .iter()
776        .map(|s| {
777            // Every inline object contributes its sentinel: the anchors this
778            // fragment carries are positioned against *this* string, so an
779            // object missing from it puts every anchor after it out by three
780            // bytes.
781            if s.image.is_some() || s.footnote_ref.is_some() {
782                "\u{FFFC}"
783            } else {
784                s.text.as_str()
785            }
786        })
787        .collect()
788}
789
790fn span_to_fragment_element(span: &ParsedSpan) -> FragmentElement {
791    // An image span carries no text — the picture *is* the content. Emitting
792    // `Text("")` for it, which is what this did, produced a fragment with an
793    // empty element and no image anywhere: `insert_djot` of an image markup
794    // returned `Ok` and inserted nothing at all.
795    //
796    // A footnote reference is the same shape and the same trap: its span carries
797    // no text either, so the identical `Text("")` would have made
798    // `insert_footnote_reference` a no-op that reported success.
799    let content = match (&span.footnote_ref, &span.image) {
800        (Some(label), _) => InlineContent::FootnoteRef {
801            label: label.clone(),
802        },
803        (None, Some(img)) => InlineContent::Image {
804            name: img.src.clone(),
805            alt: img.alt.clone(),
806            width: img.width,
807            height: img.height,
808            // The source states a display size or it does not; nothing here
809            // re-encodes the image, so there is no quality to carry.
810            quality: 100,
811        },
812        (None, None) => InlineContent::Text(span.text.clone()),
813    };
814    let fmt_font_family = if span.code {
815        Some("monospace".into())
816    } else {
817        None
818    };
819    let fmt_font_bold = if span.bold { Some(true) } else { None };
820    let fmt_font_italic = if span.italic { Some(true) } else { None };
821    let fmt_font_underline = if span.underline { Some(true) } else { None };
822    let fmt_font_strikeout = if span.strikeout { Some(true) } else { None };
823    let (fmt_anchor_href, fmt_is_anchor) = if let Some(ref href) = span.link_href {
824        (Some(href.clone()), Some(true))
825    } else {
826        (None, None)
827    };
828    // Raised and lowered text is character formatting like bold and italic, and
829    // dropping it here is what silently flattened an exponent or a chemical
830    // index on the way in: the parsers set the flags, `character_format_from_span`
831    // maps them, and only this conversion — the one every `insert_html` /
832    // `insert_markdown` / `insert_djot` goes through — threw them away.
833    let fmt_vertical_alignment = if span.superscript {
834        Some(CharVerticalAlignment::SuperScript)
835    } else if span.subscript {
836        Some(CharVerticalAlignment::SubScript)
837    } else {
838        None
839    };
840
841    FragmentElement {
842        content,
843        fmt_font_family,
844        fmt_font_point_size: None,
845        fmt_font_weight: None,
846        fmt_font_bold,
847        fmt_font_italic,
848        fmt_font_underline,
849        fmt_font_overline: None,
850        fmt_font_strikeout,
851        fmt_letter_spacing: None,
852        fmt_word_spacing: None,
853        fmt_anchor_href,
854        fmt_anchor_names: vec![],
855        fmt_is_anchor,
856        fmt_tooltip: None,
857        fmt_underline_style: None,
858        fmt_vertical_alignment,
859    }
860}
861
862/// A parsed block as a fragment block: its text and spans, and everything a load of the
863/// same text keeps of the block, so a text put back by selecting all and inserting it reads
864/// as the text loaded: its alignment, marker, spacing and list markers, and its code-block
865/// format when `keep_code_block` says so. Only the heading and the line attributes were
866/// carried, and every code block of a restored version came back as a plain paragraph. The
867/// quotations the block stands in travel beside it (see [`FragmentQuoting`]).
868fn parsed_block_to_fragment_block(pb: ParsedBlock, keep_code_block: bool) -> FragmentBlock {
869    use frontend::common::parser_tools::fragment_schema::FragmentList;
870
871    let elements: Vec<FragmentElement> = pb.spans.iter().map(span_to_fragment_element).collect();
872    let plain_text: String = spans_plain_text(&pb.spans);
873    let list = pb.list_style.map(|style| FragmentList {
874        style,
875        indent: pb.list_indent as i64,
876        prefix: pb.list_prefix,
877        suffix: pb.list_suffix,
878    });
879    let is_code_block = keep_code_block && pb.is_code_block;
880    FragmentBlock {
881        plain_text,
882        elements,
883        heading_level: pb.heading_level,
884        list,
885        alignment: pb.alignment,
886        indent: None,
887        text_indent: pb.text_indent,
888        marker: pb.marker,
889        top_margin: pb.top_margin,
890        bottom_margin: None,
891        left_margin: None,
892        right_margin: None,
893        tab_positions: vec![],
894        line_height: pb.line_height,
895        non_breakable_lines: pb.non_breakable_lines,
896        page_break_before: pb.page_break_before,
897        direction: pb.direction,
898        background_color: pb.background_color,
899        is_code_block: is_code_block.then_some(true),
900        code_language: if is_code_block {
901            pb.code_language
902        } else {
903            None
904        },
905        hyphenate: None,
906        language: None,
907    }
908}
909
910/// What a fragment was parsed from, which decides what an insertion makes of it.
911#[derive(Debug, Clone, Copy, PartialEq, Eq)]
912enum ParsedFrom {
913    /// A text in a syntax a text is saved in, Djot or Markdown: a whole text, whose code
914    /// blocks are code blocks. Inserted over a selection holding the whole of a text, it
915    /// reads as the same text loaded (see `whole_text_to_json`).
916    SavedSyntax,
917    /// HTML, as a clipboard carries a passage from a web page or another application. A
918    /// `<pre>` is read as paragraphs, one for each of its lines: a code block keeps no
919    /// emphasis, takes no footnote reference, and a host with no command to make it prose
920    /// again left the writer with a passage set as code.
921    Html,
922}
923
924/// Convert parsed elements (blocks + tables) into a `DocumentFragment`,
925/// preserving table structure as `FragmentTable` entries.
926fn parsed_elements_to_fragment(parsed: Vec<ParsedElement>, from: ParsedFrom) -> DocumentFragment {
927    let mut blocks: Vec<FragmentBlock> = Vec::new();
928    let mut tables: Vec<FragmentTable> = Vec::new();
929    // The quotations each block and table stands in, carried beside them.
930    let mut quoting = FragmentQuoting::default();
931    // The number each list starts at, carried beside its items: every item of a list
932    // starting past 1 names it, and an insertion reads it where it makes the list.
933    let mut list_starts = FragmentListStarts::default();
934
935    for elem in parsed {
936        match elem {
937            // A clipboard fragment carries prose, not note bodies: a definition
938            // has no position in the flow being copied, and pasting one would
939            // splice a note's text into the middle of a sentence. The reference
940            // travels; the body stays where it is defined.
941            ParsedElement::FootnoteDefinition { .. } => {}
942            // A code block of a text in a saved syntax is a code block, and holds its lines.
943            // Any other block is prose, and a `\n` in prose is a new block: one line a
944            // block, as a plain-text paste gives. A line break inside the block (a
945            // `LINE_SEPARATOR`) is not one of those, and stays. A pasted `<pre>` is prose too (see
946            // `ParsedFrom::Html`). Kept in one block, it held line breaks, which the Djot
947            // writer used to write as they were, and its lines read back as whatever their
948            // markers spelled.
949            ParsedElement::Block(pb) => {
950                let depth = pb.blockquote_depth;
951                // The quotations opening at the block open at its first line.
952                let mut opens = pb.blockquote_opens;
953                // The quotation's role rides on its first block, as the parsers put it.
954                let mut role = pb.semantic_role.clone();
955                let keep_code_block = pb.is_code_block && from == ParsedFrom::SavedSyntax;
956                let lines = if keep_code_block {
957                    vec![pb]
958                } else {
959                    split_block_at_line_breaks(pb)
960                };
961                for pb in lines {
962                    if let Some(start) = pb.list_start.filter(|_| pb.list_style.is_some()) {
963                        list_starts.set(blocks.len(), start);
964                    }
965                    blocks.push(parsed_block_to_fragment_block(pb, keep_code_block));
966                    if depth > 0 {
967                        quoting.set_block(blocks.len() - 1, depth, role.take());
968                        quoting.set_block_opens(blocks.len() - 1, std::mem::take(&mut opens));
969                    }
970                }
971            }
972            ParsedElement::Table(pt) => {
973                let block_insert_index = blocks.len();
974                let num_columns = pt.column_count();
975                let num_rows = pt.rows.len();
976
977                let mut frag_cells: Vec<FragmentTableCell> = Vec::new();
978                for (row_idx, row) in pt.rows.iter().enumerate() {
979                    // A row shorter than the widest is completed with empty cells, as a
980                    // load completes it: a table with holes in its grid is one no edit
981                    // expects.
982                    for col_idx in 0..num_columns {
983                        let spans = row
984                            .get(col_idx)
985                            .map_or(&[][..], |cell| cell.spans.as_slice());
986                        let cell_elements: Vec<FragmentElement> =
987                            spans.iter().map(span_to_fragment_element).collect();
988                        let cell_text: String = spans_plain_text(spans);
989
990                        frag_cells.push(FragmentTableCell {
991                            row: row_idx,
992                            column: col_idx,
993                            row_span: 1,
994                            column_span: 1,
995                            blocks: vec![FragmentBlock {
996                                plain_text: cell_text,
997                                elements: cell_elements,
998                                heading_level: None,
999                                list: None,
1000                                alignment: None,
1001                                indent: None,
1002                                text_indent: None,
1003                                marker: None,
1004                                top_margin: None,
1005                                bottom_margin: None,
1006                                left_margin: None,
1007                                right_margin: None,
1008                                tab_positions: vec![],
1009                                line_height: None,
1010                                non_breakable_lines: None,
1011                                page_break_before: None,
1012                                direction: None,
1013                                background_color: None,
1014                                is_code_block: None,
1015                                code_language: None,
1016                                hyphenate: None,
1017                                language: None,
1018                            }],
1019                            fmt_padding: None,
1020                            fmt_border: None,
1021                            fmt_vertical_alignment: None,
1022                            fmt_background_color: None,
1023                        });
1024                    }
1025                }
1026
1027                tables.push(FragmentTable {
1028                    rows: num_rows,
1029                    columns: num_columns,
1030                    cells: frag_cells,
1031                    block_insert_index,
1032                    fmt_border: None,
1033                    fmt_cell_spacing: None,
1034                    fmt_cell_padding: None,
1035                    fmt_width: None,
1036                    fmt_alignment: None,
1037                    column_widths: vec![],
1038                });
1039                quoting.set_table(tables.len() - 1, pt.blockquote_depth);
1040                quoting.set_table_opens(tables.len() - 1, pt.blockquote_opens);
1041            }
1042        }
1043    }
1044
1045    // The blocks' own text, read before they are serialized: reading it back out of the
1046    // JSON parsed the whole fragment a second time.
1047    let plain_text = blocks
1048        .iter()
1049        .map(|b| b.plain_text.as_str())
1050        .collect::<Vec<_>>()
1051        .join("\n");
1052    let data = FragmentData { blocks, tables };
1053    let data = fragment_with_list_starts_to_json(
1054        &data,
1055        &quoting,
1056        &list_starts,
1057        from == ParsedFrom::SavedSyntax,
1058    )
1059    .expect("fragment serialization should not fail");
1060
1061    DocumentFragment { data, plain_text }
1062}
1063
1064#[cfg(test)]
1065mod tests {
1066    use super::*;
1067
1068    /// A paragraph as a manuscript holds it: emphasis, a link, a note reference.
1069    fn paragraph(i: usize) -> String {
1070        format!(
1071            "Paragraph {i} with *emphasis* and a [link](https://example.org/{i}) in it, and a \
1072             note[^n{i}] after the words that run on to a full line of prose."
1073        )
1074    }
1075
1076    /// A fragment is the text a cursor inserts, carried as JSON, and an insertion refuses
1077    /// JSON past 64 MiB. Every field of every block and every run was written, `null` or
1078    /// empty as most are: the JSON came to about 18 times the Djot it was made from, and
1079    /// putting back a whole text of 26,000 paragraphs failed. Fields holding nothing are
1080    /// left out now.
1081    #[test]
1082    fn a_fragment_holds_little_more_than_its_text() {
1083        let djot: String = (0..200).map(|i| format!("{}\n\n", paragraph(i))).collect();
1084        let fragment = DocumentFragment::from_djot(&djot);
1085        let ratio = fragment.raw_data().len() as f64 / djot.len() as f64;
1086        println!("fragment JSON: {ratio:.2} times the Djot");
1087        assert!(
1088            ratio < 4.0,
1089            "the fragment's JSON is {ratio:.1} times the Djot it was made from"
1090        );
1091        assert_eq!(fragment.to_plain_text().lines().count(), 200);
1092    }
1093
1094    /// A fragment written in full, as the builds before the compact form wrote it, still
1095    /// reads: every field left out reads as holding nothing.
1096    #[test]
1097    fn a_fragment_written_in_full_still_reads() {
1098        let full = r#"{"blocks":[{"plain_text":"Old","elements":[{"content":{"Text":"Old"},
1099            "fmt_font_family":null,"fmt_font_point_size":null,"fmt_font_weight":null,
1100            "fmt_font_bold":true,"fmt_font_italic":null,"fmt_font_underline":null,
1101            "fmt_font_overline":null,"fmt_font_strikeout":null,"fmt_letter_spacing":null,
1102            "fmt_word_spacing":null,"fmt_anchor_href":null,"fmt_anchor_names":[],
1103            "fmt_is_anchor":null,"fmt_tooltip":null,"fmt_underline_style":null,
1104            "fmt_vertical_alignment":null}],"heading_level":2,"list":null,"alignment":null,
1105            "indent":null,"text_indent":null,"marker":null,"top_margin":null,
1106            "bottom_margin":null,"left_margin":null,"right_margin":null,"tab_positions":[],
1107            "line_height":null,"non_breakable_lines":null,"direction":null,
1108            "background_color":null,"is_code_block":null,"code_language":null}]}"#;
1109        let data: FragmentData = serde_json::from_str(full).unwrap();
1110        assert_eq!(data.blocks[0].heading_level, Some(2));
1111        assert_eq!(data.blocks[0].elements[0].fmt_font_bold, Some(true));
1112        let compact = serde_json::to_string(&data).unwrap();
1113        let again: FragmentData = serde_json::from_str(&compact).unwrap();
1114        assert_eq!(again.blocks[0].heading_level, Some(2));
1115        assert_eq!(again.blocks[0].elements[0].fmt_font_bold, Some(true));
1116        assert!(compact.len() < full.len() / 3, "{compact}");
1117    }
1118}