fig_schema/present.rs
1//! Renderer-neutral presentation hints. A frontend maps these to its own
2//! symbols and colours (SwiftUI → SF Symbols + adaptive `Color`; ratatui →
3//! unicode + ANSI). Carried on [`crate::FieldRule`] but never interpreted by
4//! this crate — purely a payload for the embedder's renderer.
5
6/// Presentation hints for one field rule.
7///
8/// `#[non_exhaustive]`: this is the type that grows every time a frontend needs
9/// a new hint, so it is built from [`Presentation::default`] and the chainable
10/// setters below rather than a struct literal. Reading the fields is unchanged.
11///
12/// ```
13/// use fig_schema::{Icon, Presentation, Tint};
14///
15/// let p = Presentation::default()
16/// .title("Audience")
17/// .description("Who may read this")
18/// .icon(Icon::Globe)
19/// .tint(Tint::Positive);
20/// assert_eq!(p.title.as_deref(), Some("Audience"));
21/// ```
22#[derive(Debug, Clone, Default, PartialEq, Eq)]
23#[non_exhaustive]
24pub struct Presentation {
25 /// A human field label.
26 pub title: Option<String>,
27 /// Help text / section subtitle.
28 pub description: Option<String>,
29 /// A semantic icon.
30 pub icon: Option<Icon>,
31 /// A semantic tint.
32 pub tint: Option<Tint>,
33}
34
35impl Presentation {
36 /// Set the human field label.
37 pub fn title(mut self, title: impl Into<String>) -> Self {
38 self.title = Some(title.into());
39 self
40 }
41
42 /// Set the label from an optional one — for a caller reading a config where
43 /// the title may be absent. `None` leaves it unset.
44 pub fn title_opt(mut self, title: Option<impl Into<String>>) -> Self {
45 self.title = title.map(Into::into);
46 self
47 }
48
49 /// Set the help text.
50 pub fn description(mut self, description: impl Into<String>) -> Self {
51 self.description = Some(description.into());
52 self
53 }
54
55 /// Set the help text from an optional one. `None` leaves it unset.
56 pub fn description_opt(mut self, description: Option<impl Into<String>>) -> Self {
57 self.description = description.map(Into::into);
58 self
59 }
60
61 /// Set the semantic icon. Takes an [`Icon`] or an `Option<Icon>`.
62 pub fn icon(mut self, icon: impl Into<Option<Icon>>) -> Self {
63 self.icon = icon.into();
64 self
65 }
66
67 /// Set the semantic tint. Takes a [`Tint`] or an `Option<Tint>`.
68 pub fn tint(mut self, tint: impl Into<Option<Tint>>) -> Self {
69 self.tint = tint.into();
70 self
71 }
72}
73
74/// A semantic icon hint. Frontends map to their own symbol set.
75///
76/// `#[non_exhaustive]`: the set grows as fields do, so a `match` needs a `_`
77/// arm. Constructing a variant is unaffected.
78#[derive(Debug, Clone, PartialEq, Eq)]
79#[non_exhaustive]
80pub enum Icon {
81 Link,
82 Enum,
83 Toggle,
84 Lock,
85 Globe,
86 Clock,
87 Tag,
88 Text,
89 /// An escape hatch naming a frontend-specific symbol.
90 Other(String),
91}
92
93impl Icon {
94 /// The icon a schema document's `icon` key names. Never fails: a name that
95 /// is not one of the eight known is [`Icon::Other`], because a frontend's
96 /// own symbol name is not a typo — a presenter fails open.
97 ///
98 /// ```
99 /// use fig_schema::Icon;
100 ///
101 /// assert_eq!(Icon::from_name("globe"), Icon::Globe);
102 /// assert_eq!(Icon::from_name("sparkles"), Icon::Other("sparkles".into()));
103 /// ```
104 pub fn from_name(name: &str) -> Icon {
105 match name {
106 "link" => Icon::Link,
107 "enum" => Icon::Enum,
108 "toggle" => Icon::Toggle,
109 "lock" => Icon::Lock,
110 "globe" => Icon::Globe,
111 "clock" => Icon::Clock,
112 "tag" => Icon::Tag,
113 "text" => Icon::Text,
114 other => Icon::Other(other.to_owned()),
115 }
116 }
117
118 /// The name [`Icon::from_name`] reads this icon back from.
119 pub fn name(&self) -> &str {
120 match self {
121 Icon::Link => "link",
122 Icon::Enum => "enum",
123 Icon::Toggle => "toggle",
124 Icon::Lock => "lock",
125 Icon::Globe => "globe",
126 Icon::Clock => "clock",
127 Icon::Tag => "tag",
128 Icon::Text => "text",
129 Icon::Other(name) => name,
130 }
131 }
132}
133
134/// A semantic tint hint. Frontends map to theme-adaptive colours.
135///
136/// `#[non_exhaustive]`: a palette grows the same way an icon set does, so a
137/// `match` needs a `_` arm.
138#[derive(Debug, Clone, Copy, PartialEq, Eq)]
139#[non_exhaustive]
140pub enum Tint {
141 Accent,
142 Neutral,
143 Positive,
144 Warning,
145 Danger,
146}
147
148impl Tint {
149 /// Every tint, so a frontend can assert its colour mapping is total —
150 /// `for t in Tint::ALL { assert!(my_colour(*t).is_some()) }` — instead of
151 /// keeping a second copy of this list that silently falls behind.
152 ///
153 /// [`Icon`] deliberately has no equivalent, and the asymmetry is the point
154 /// rather than an oversight. Every other `#[non_exhaustive]` enum here is
155 /// safe against a new variant because *this crate never produces one*: it
156 /// defines the vocabulary, and every value in a workspace is constructed by
157 /// the embedder, so a new variant can only reach a `match` through a
158 /// deliberate, reviewed change to the producer. [`Tint`] is the one where
159 /// that gate is *not* the producer's: [`parse_vocabulary`](crate::parse_vocabulary)
160 /// reads a per-term `tint:`, and [`load_schema`](crate::load_schema) a
161 /// rule's, so a `Tint` arrives from *user data* and the gate is "someone
162 /// edited a file". This list existed before the parser learned the key,
163 /// so that the release which taught it would turn consumer tests red
164 /// instead of shipping a term that silently rendered untinted; a frontend
165 /// that asserts over it stays covered when a sixth tint is added here.
166 /// ([`Icon`] has an escape hatch instead: an unknown name is
167 /// [`Icon::Other`], which a frontend already has to draw.)
168 pub const ALL: &'static [Tint] = &[
169 Tint::Accent,
170 Tint::Neutral,
171 Tint::Positive,
172 Tint::Warning,
173 Tint::Danger,
174 ];
175
176 /// The tint a schema document's `tint` key — on a rule, or on a term —
177 /// names, or `None` for a spelling the crate cannot map. The loader drops
178 /// that `None` and `lint` notes it: a tint no frontend can name is one no
179 /// frontend can draw, and a presenter fails open.
180 ///
181 /// ```
182 /// use fig_schema::Tint;
183 ///
184 /// assert_eq!(Tint::from_name("positive"), Some(Tint::Positive));
185 /// assert_eq!(Tint::from_name("green"), None);
186 /// ```
187 pub fn from_name(name: &str) -> Option<Tint> {
188 Tint::ALL.iter().copied().find(|tint| tint.name() == name)
189 }
190
191 /// The name [`Tint::from_name`] reads this tint back from.
192 pub fn name(self) -> &'static str {
193 match self {
194 Tint::Accent => "accent",
195 Tint::Neutral => "neutral",
196 Tint::Positive => "positive",
197 Tint::Warning => "warning",
198 Tint::Danger => "danger",
199 }
200 }
201}
202
203#[cfg(test)]
204mod tests {
205 use super::*;
206
207 #[test]
208 fn every_tint_and_icon_round_trips_through_its_name() {
209 for tint in Tint::ALL {
210 assert_eq!(Tint::from_name(tint.name()), Some(*tint));
211 }
212 assert_eq!(Tint::from_name("Positive"), None);
213 for icon in [
214 Icon::Link,
215 Icon::Enum,
216 Icon::Toggle,
217 Icon::Lock,
218 Icon::Globe,
219 Icon::Clock,
220 Icon::Tag,
221 Icon::Text,
222 Icon::Other("sparkles".into()),
223 ] {
224 assert_eq!(Icon::from_name(icon.name()), icon);
225 }
226 }
227}