Skip to main content

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}