Skip to main content

reflex/pulse/model/
content.rs

1//! Page content: a small block/inline AST.
2//!
3//! There are no URLs here. Links point at a [`Target`] and the renderer resolves them
4//! through the [`Linker`](super::xref::Linker), so a base-url change or a slug change
5//! can never leave a stale link. Numbers are [`Inline::Fact`] references into the
6//! site's [`FactStore`](super::facts::FactStore), so every page shows the same count.
7
8use super::facts::FactId;
9use super::ids::AnchorId;
10use super::xref::{SourceLoc, Target};
11use serde::{Deserialize, Serialize};
12
13#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
14#[serde(tag = "type", rename_all = "kebab-case")]
15pub enum Block {
16    Heading {
17        level: u8,
18        text: String,
19        anchor: AnchorId,
20    },
21    Paragraph {
22        content: Vec<Inline>,
23    },
24    /// Markdown written by people (README, doc comments, CHANGELOG) or by the LLM.
25    /// The renderer treats it as untrusted: raw HTML is shown as text.
26    Markdown {
27        markdown: MarkdownText,
28    },
29    Code {
30        lang: String,
31        code: String,
32        #[serde(skip_serializing_if = "Option::is_none")]
33        title: Option<String>,
34    },
35    List {
36        ordered: bool,
37        items: Vec<Vec<Inline>>,
38    },
39    Table {
40        columns: Vec<String>,
41        rows: Vec<Vec<Vec<Inline>>>,
42    },
43    Callout {
44        kind: CalloutKind,
45        #[serde(skip_serializing_if = "Option::is_none")]
46        title: Option<String>,
47        body: Vec<Block>,
48    },
49    /// A graph. `links` maps node ids in `source` to link targets; the renderer binds
50    /// clicks itself, so the diagram source never carries URLs.
51    Diagram {
52        kind: DiagramKind,
53        source: String,
54        links: Vec<(String, Target)>,
55        #[serde(skip_serializing_if = "Option::is_none")]
56        caption: Option<String>,
57    },
58    Cards {
59        cards: Vec<Card>,
60    },
61    /// A row of headline numbers.
62    Stats {
63        stats: Vec<Stat>,
64    },
65    /// One documented item: signature, docs, parameters, source.
66    Symbol {
67        symbol: Box<SymbolBlock>,
68    },
69    /// A slot the writing pass may fill. `fallback` is always complete on its own, so a
70    /// site built without an LLM has no holes.
71    Narrative {
72        slot: String,
73        #[serde(skip_serializing_if = "Option::is_none")]
74        text: Option<MarkdownText>,
75        fallback: Vec<Block>,
76    },
77}
78
79#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
80#[serde(tag = "type", rename_all = "kebab-case")]
81pub enum Inline {
82    Text {
83        text: String,
84    },
85    Code {
86        code: String,
87    },
88    Strong {
89        content: Vec<Inline>,
90    },
91    Emph {
92        content: Vec<Inline>,
93    },
94    Link {
95        to: Target,
96        content: Vec<Inline>,
97    },
98    /// A number from the fact store, rendered with its provenance.
99    Fact {
100        fact: FactId,
101    },
102}
103
104impl Inline {
105    pub fn text(s: impl Into<String>) -> Self {
106        Inline::Text { text: s.into() }
107    }
108
109    pub fn code(s: impl Into<String>) -> Self {
110        Inline::Code { code: s.into() }
111    }
112
113    pub fn strong(s: impl Into<String>) -> Self {
114        Inline::Strong {
115            content: vec![Inline::text(s)],
116        }
117    }
118
119    pub fn link(to: Target, label: impl Into<String>) -> Self {
120        Inline::Link {
121            to,
122            content: vec![Inline::text(label)],
123        }
124    }
125
126    pub fn code_link(to: Target, code: impl Into<String>) -> Self {
127        Inline::Link {
128            to,
129            content: vec![Inline::code(code)],
130        }
131    }
132
133    pub fn fact(id: FactId) -> Self {
134        Inline::Fact { fact: id }
135    }
136}
137
138impl Block {
139    pub fn heading(level: u8, text: impl Into<String>) -> Self {
140        let text = text.into();
141        Block::Heading {
142            level,
143            anchor: super::ids::anchor_for(&text),
144            text,
145        }
146    }
147
148    pub fn para(content: Vec<Inline>) -> Self {
149        Block::Paragraph { content }
150    }
151
152    pub fn text(s: impl Into<String>) -> Self {
153        Block::Paragraph {
154            content: vec![Inline::text(s)],
155        }
156    }
157
158    pub fn note(body: impl Into<String>) -> Self {
159        Block::Callout {
160            kind: CalloutKind::Note,
161            title: None,
162            body: vec![Block::text(body)],
163        }
164    }
165}
166
167/// Markdown source plus where it came from.
168#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
169pub struct MarkdownText {
170    pub source: String,
171    pub origin: MarkdownOrigin,
172    #[serde(skip_serializing_if = "Option::is_none")]
173    pub from: Option<SourceLoc>,
174}
175
176#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
177#[serde(rename_all = "kebab-case")]
178pub enum MarkdownOrigin {
179    /// A repository document (README, docs/, CHANGELOG).
180    Doc,
181    /// A doc comment.
182    Comment,
183    /// A commit message.
184    Commit,
185    /// Written by the LLM writing pass.
186    Llm,
187}
188
189#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
190#[serde(rename_all = "kebab-case")]
191pub enum CalloutKind {
192    Note,
193    Tip,
194    Caution,
195    Danger,
196}
197
198#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
199#[serde(rename_all = "kebab-case")]
200pub enum DiagramKind {
201    Mermaid,
202}
203
204#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
205pub struct Card {
206    pub title: String,
207    pub to: Target,
208    #[serde(skip_serializing_if = "Option::is_none")]
209    pub description: Option<String>,
210}
211
212#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
213pub struct Stat {
214    pub label: String,
215    pub fact: FactId,
216}
217
218/// A documented item as the reference shows it.
219#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
220pub struct SymbolBlock {
221    pub id: super::ids::SymbolId,
222    pub anchor: AnchorId,
223    /// `fn`, `struct`, `method`, …
224    pub kind: String,
225    pub name: String,
226    /// Code language of the signature (`rust`).
227    pub lang: String,
228    pub signature: String,
229    #[serde(skip_serializing_if = "Option::is_none")]
230    pub doc: Option<MarkdownText>,
231    #[serde(default, skip_serializing_if = "Vec::is_empty")]
232    pub params: Vec<ParamRow>,
233    #[serde(skip_serializing_if = "Option::is_none")]
234    pub returns: Option<String>,
235    /// Deprecation message ("Deprecated since 1.2: use `sum`").
236    #[serde(skip_serializing_if = "Option::is_none")]
237    pub deprecated: Option<String>,
238    /// `async`, `unsafe`, `const`, `impl Display`…
239    #[serde(default, skip_serializing_if = "Vec::is_empty")]
240    pub badges: Vec<String>,
241    pub source: SourceLoc,
242}
243
244#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
245pub struct ParamRow {
246    pub name: String,
247    pub ty: String,
248}