Skip to main content

sheetkit_xml/
threaded_comment.rs

1//! Threaded comments XML schema structures.
2//!
3//! Represents `xl/threadedComments/threadedComment{N}.xml` and
4//! `xl/persons/person.xml` in the OOXML package (Excel 2019+).
5
6use serde::{Deserialize, Serialize};
7
8/// Namespace for threaded comments (Excel 2018+).
9pub const THREADED_COMMENTS_NS: &str =
10    "http://schemas.microsoft.com/office/spreadsheetml/2018/threadedcomments";
11
12/// Content type for threaded comments parts.
13pub const THREADED_COMMENTS_CONTENT_TYPE: &str = "application/vnd.ms-excel.threadedcomments+xml";
14
15/// Content type for the person list part.
16pub const PERSON_LIST_CONTENT_TYPE: &str = "application/vnd.ms-excel.person+xml";
17
18/// Relationship type for threaded comments (worksheet-level).
19pub const REL_TYPE_THREADED_COMMENT: &str =
20    "http://schemas.microsoft.com/office/2017/10/relationships/threadedComment";
21
22/// Relationship type for the person list (workbook-level).
23pub const REL_TYPE_PERSON: &str =
24    "http://schemas.microsoft.com/office/2017/10/relationships/person";
25
26/// Root element for threaded comments XML.
27#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
28#[serde(rename = "ThreadedComments")]
29pub struct ThreadedComments {
30    #[serde(rename = "@xmlns", default = "default_threaded_comments_ns")]
31    pub xmlns: String,
32
33    #[serde(rename = "threadedComment", default)]
34    pub comments: Vec<ThreadedComment>,
35}
36
37/// Individual threaded comment entry.
38#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
39#[serde(rename = "threadedComment")]
40pub struct ThreadedComment {
41    #[serde(rename = "@ref")]
42    pub cell_ref: String,
43
44    #[serde(rename = "@dT")]
45    pub date_time: String,
46
47    #[serde(rename = "@personId")]
48    pub person_id: String,
49
50    #[serde(rename = "@id")]
51    pub id: String,
52
53    #[serde(rename = "@parentId", skip_serializing_if = "Option::is_none")]
54    pub parent_id: Option<String>,
55
56    #[serde(rename = "@done", skip_serializing_if = "Option::is_none", default)]
57    pub done: Option<String>,
58
59    pub text: String,
60}
61
62/// Root element for the person list XML (`xl/persons/person.xml`).
63#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
64#[serde(rename = "personList")]
65pub struct PersonList {
66    #[serde(rename = "@xmlns", default = "default_threaded_comments_ns")]
67    pub xmlns: String,
68
69    #[serde(rename = "person", default)]
70    pub persons: Vec<Person>,
71}
72
73/// Individual person entry in the person list.
74#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
75pub struct Person {
76    #[serde(rename = "@displayName")]
77    pub display_name: String,
78
79    #[serde(rename = "@id")]
80    pub id: String,
81
82    #[serde(rename = "@userId", skip_serializing_if = "Option::is_none")]
83    pub user_id: Option<String>,
84
85    #[serde(rename = "@providerId", skip_serializing_if = "Option::is_none")]
86    pub provider_id: Option<String>,
87}
88
89impl Default for ThreadedComments {
90    fn default() -> Self {
91        Self {
92            xmlns: THREADED_COMMENTS_NS.to_string(),
93            comments: Vec::new(),
94        }
95    }
96}
97
98impl Default for PersonList {
99    fn default() -> Self {
100        Self {
101            xmlns: THREADED_COMMENTS_NS.to_string(),
102            persons: Vec::new(),
103        }
104    }
105}
106
107fn default_threaded_comments_ns() -> String {
108    THREADED_COMMENTS_NS.to_string()
109}
110
111#[cfg(test)]
112mod tests {
113    use super::*;
114
115    #[test]
116    fn test_threaded_comments_default() {
117        let tc = ThreadedComments::default();
118        assert_eq!(tc.xmlns, THREADED_COMMENTS_NS);
119        assert!(tc.comments.is_empty());
120    }
121
122    #[test]
123    fn test_person_list_default() {
124        let pl = PersonList::default();
125        assert_eq!(pl.xmlns, THREADED_COMMENTS_NS);
126        assert!(pl.persons.is_empty());
127    }
128
129    #[test]
130    fn test_threaded_comment_roundtrip() {
131        let tc = ThreadedComments {
132            xmlns: THREADED_COMMENTS_NS.to_string(),
133            comments: vec![
134                ThreadedComment {
135                    cell_ref: "A1".to_string(),
136                    date_time: "2024-01-15T10:30:00.00".to_string(),
137                    person_id: "{PERSON-1}".to_string(),
138                    id: "{COMMENT-1}".to_string(),
139                    parent_id: None,
140                    done: None,
141                    text: "Initial comment".to_string(),
142                },
143                ThreadedComment {
144                    cell_ref: "A1".to_string(),
145                    date_time: "2024-01-15T11:00:00.00".to_string(),
146                    person_id: "{PERSON-2}".to_string(),
147                    id: "{REPLY-1}".to_string(),
148                    parent_id: Some("{COMMENT-1}".to_string()),
149                    done: Some("1".to_string()),
150                    text: "This is a reply".to_string(),
151                },
152            ],
153        };
154
155        let xml = quick_xml::se::to_string(&tc).unwrap();
156        assert!(xml.contains("A1"));
157        assert!(xml.contains("Initial comment"));
158        assert!(xml.contains("parentId"));
159        assert!(xml.contains("done=\"1\""));
160
161        let parsed: ThreadedComments = quick_xml::de::from_str(&xml).unwrap();
162        assert_eq!(parsed.comments.len(), 2);
163        assert_eq!(parsed.comments[0].cell_ref, "A1");
164        assert_eq!(parsed.comments[0].id, "{COMMENT-1}");
165        assert!(parsed.comments[0].parent_id.is_none());
166        assert_eq!(
167            parsed.comments[1].parent_id,
168            Some("{COMMENT-1}".to_string())
169        );
170        assert_eq!(parsed.comments[1].done, Some("1".to_string()));
171    }
172
173    #[test]
174    fn test_person_list_roundtrip() {
175        let pl = PersonList {
176            xmlns: THREADED_COMMENTS_NS.to_string(),
177            persons: vec![Person {
178                display_name: "John Doe".to_string(),
179                id: "{PERSON-GUID}".to_string(),
180                user_id: Some("[email protected]".to_string()),
181                provider_id: Some("ADAL".to_string()),
182            }],
183        };
184
185        let xml = quick_xml::se::to_string(&pl).unwrap();
186        assert!(xml.contains("John Doe"));
187        assert!(xml.contains("userId"));
188        assert!(xml.contains("providerId"));
189
190        let parsed: PersonList = quick_xml::de::from_str(&xml).unwrap();
191        assert_eq!(parsed.persons.len(), 1);
192        assert_eq!(parsed.persons[0].display_name, "John Doe");
193        assert_eq!(
194            parsed.persons[0].user_id,
195            Some("[email protected]".to_string())
196        );
197    }
198
199    #[test]
200    fn test_threaded_comment_without_optional_fields() {
201        let tc = ThreadedComment {
202            cell_ref: "B2".to_string(),
203            date_time: "2024-06-01T08:00:00.00".to_string(),
204            person_id: "{P1}".to_string(),
205            id: "{C1}".to_string(),
206            parent_id: None,
207            done: None,
208            text: "Simple comment".to_string(),
209        };
210
211        let xml = quick_xml::se::to_string(&tc).unwrap();
212        assert!(!xml.contains("parentId"));
213        assert!(!xml.contains("done"));
214
215        let parsed: ThreadedComment = quick_xml::de::from_str(&xml).unwrap();
216        assert!(parsed.parent_id.is_none());
217        assert!(parsed.done.is_none());
218    }
219
220    #[test]
221    fn test_person_without_optional_fields() {
222        let p = Person {
223            display_name: "Anonymous".to_string(),
224            id: "{P-ANON}".to_string(),
225            user_id: None,
226            provider_id: None,
227        };
228
229        let xml = quick_xml::se::to_string(&p).unwrap();
230        assert!(!xml.contains("userId"));
231        assert!(!xml.contains("providerId"));
232
233        let parsed: Person = quick_xml::de::from_str(&xml).unwrap();
234        assert!(parsed.user_id.is_none());
235        assert!(parsed.provider_id.is_none());
236    }
237
238    #[test]
239    fn test_parse_real_excel_threaded_comment_xml() {
240        let xml = r#"<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
241<ThreadedComments xmlns="http://schemas.microsoft.com/office/spreadsheetml/2018/threadedcomments">
242  <threadedComment ref="A1" dT="2024-01-15T10:30:00.00" personId="{GUID1}" id="{GUID2}">
243    <text>This is the initial comment</text>
244  </threadedComment>
245  <threadedComment ref="A1" dT="2024-01-15T11:00:00.00" personId="{GUID3}" id="{GUID4}" parentId="{GUID2}" done="1">
246    <text>This is a reply</text>
247  </threadedComment>
248</ThreadedComments>"#;
249
250        let parsed: ThreadedComments = quick_xml::de::from_str(xml).unwrap();
251        assert_eq!(parsed.comments.len(), 2);
252        assert_eq!(parsed.comments[0].text, "This is the initial comment");
253        assert_eq!(parsed.comments[1].text, "This is a reply");
254        assert_eq!(parsed.comments[1].parent_id, Some("{GUID2}".to_string()));
255        assert_eq!(parsed.comments[1].done, Some("1".to_string()));
256    }
257
258    #[test]
259    fn test_parse_real_excel_person_xml() {
260        let xml = r#"<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
261<personList xmlns="http://schemas.microsoft.com/office/spreadsheetml/2018/threadedcomments">
262  <person displayName="John Doe" id="{GUID}" userId="[email protected]" providerId="ADAL"/>
263</personList>"#;
264
265        let parsed: PersonList = quick_xml::de::from_str(xml).unwrap();
266        assert_eq!(parsed.persons.len(), 1);
267        assert_eq!(parsed.persons[0].display_name, "John Doe");
268        assert_eq!(parsed.persons[0].id, "{GUID}");
269    }
270}