makeover-layout 0.47.0

The renderer-agnostic half of the make-family design system: what a thing IS, named as intents and relationships and never as values. Colour defers to makeover, spacing to makeover-geometry; what is left is composition.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151

use crate::Intent;

// Names this module's prose links to, resolved for rustdoc.
#[allow(unused_imports)]
use crate::Column;

/// What a run of source code is, once something has classified it.
///
/// The description carries the classification and never the source, which is
/// the whole of decision `19d7602d` (2026-09-02, option d). An app that browses
/// source already has a lexer; a renderer does not and should not grow one, and
/// three renderers each growing their own would disagree about the same file.
///
/// # Why the app classifies and the renderer colours
///
/// Measured on MNW's source browser, which is the only consumer in the tree.
/// It highlights server-side with syntect and had already reduced syntect's
/// scope space to seven colours held fixed across all 31 themes, because a
/// reader recognises a highlighting palette and re-tinting it per theme costs
/// that recognition to gain nothing. So the classification existed on the app
/// side already: the only question was whether to throw it away at the seam and
/// have each renderer redo it. This is the answer.
///
/// The precedent is `docengine`'s `Emphasis`, which crosses the same seam the
/// same way: `quasi-tui` maps its four flags onto terminal modifiers, a webview
/// maps them onto elements, and neither parses markdown to do it.
///
/// # The eight, and why these eight
///
/// The seven MNW's palette fixes, plus [`Plain`](Self::Plain) for a run nothing
/// claimed. `Plain` is not an absence: a lexer that ran and found ordinary code
/// is saying something a renderer wants, and an `Option<Syntax>` would have made
/// "unclassified" and "not classified yet" one value.
///
/// `#[non_exhaustive]` from the first commit, deliberately. A ninth class is the
/// obvious next request and it must not be a breaking release across three
/// renderers and five apps.
///
/// # What it is not
///
/// A token type in a grammar. These are display classes, coarse on purpose:
/// the distinctions a reader uses at a glance, not the ones a parser makes.
/// A renderer wanting more has `language` on the node beside this and may do
/// whatever it likes with it.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
#[non_exhaustive]
pub enum Syntax {
    /// Ordinary code nothing else claimed.
    ///
    /// The default, and a real answer rather than a missing one. See the type's
    /// docs for why this is not an `Option`.
    #[default]
    Plain,
    /// A language keyword, and the storage and modifier words with it.
    Keyword,
    /// A string or character literal.
    String,
    /// A comment.
    Comment,
    /// A literal that is not a string: a number, a boolean, a constant name.
    Constant,
    /// A name being defined: a function, a type, a module.
    Entity,
    /// A name being used: a variable, a parameter, a field.
    Variable,
    /// Something the language or its library provides rather than this file.
    Support,
}

impl Syntax {
    /// The stable lowercase name, for a renderer keying its own palette off it.
    ///
    /// Named here rather than agreed between each renderer and each host, for
    /// the reason every other spelling in this crate is: that is how one
    /// renderer ends up calling it `str` and the next `string`, and a theme
    /// written against one stops working under the other.
    ///
    /// Not an [`Intent`] token, and the difference is worth stating. An intent
    /// resolves against a `makeover` theme token, and there are none for syntax
    /// colours: a highlighting palette is deliberately outside the theme, held
    /// fixed while everything around it changes. So this is a name a renderer
    /// maps however it can, and a renderer with no colours to spend maps every
    /// one of them onto the same face and is not wrong.
    #[must_use]
    pub const fn name(self) -> &'static str {
        match self {
            Self::Plain => "plain",
            Self::Keyword => "keyword",
            Self::String => "string",
            Self::Comment => "comment",
            Self::Constant => "constant",
            Self::Entity => "entity",
            Self::Variable => "variable",
            Self::Support => "support",
            // Exhaustive rather than wildcarded, which is `State`'s rule one
            // type up: within this crate `#[non_exhaustive]` does not apply, so
            // a class added here has to be given a spelling rather than
            // inheriting "plain" in silence. Consumers outside the crate take
            // the wildcard, and for them "plain" is the right degradation.
        }
    }
}

/// What one line of a diff is: added, removed, or neither.
///
/// The other half of decision `19d7602d`. A diff is a table of lines and the
/// only thing the vocabulary was missing was a way for a line to say which side
/// of the change it is on, so this rides on [`Column`] rather than arriving as a
/// `Node::Diff` carrying git's data model.
///
/// # Why three and not two
///
/// [`Context`](Self::Context) is a line that did not change, and it is most of
/// a diff. Said as `Option<Change>` with `None` for context, a renderer could
/// not tell an unchanged line from a line nobody marked, which is the same
/// argument [`Syntax::Plain`] makes one type up.
///
/// `#[non_exhaustive]` for [`Syntax`]'s reason. A fourth kind -- a moved line, a
/// conflict side -- is a plausible request and must not be a breaking release.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
#[non_exhaustive]
pub enum Change {
    /// The line is in both sides and did not change.
    #[default]
    Context,
    /// The line is only in the new side.
    Added,
    /// The line is only in the old side.
    Removed,
}

impl Intent for Change {
    fn token(self) -> &'static str {
        match self {
            // The status axis, reused rather than given a palette of its own.
            // A diff's green and red mean exactly what success and danger mean
            // everywhere else in the system, and an app that wants them held
            // fixed across themes says so in its own sheet, which is what MNW's
            // `--diff-add` / `--diff-del` pair already does.
            Self::Added => "success",
            Self::Removed => "danger",
            // Context is the bulk of a diff and is ordinary content. Muting it
            // would be the axis deciding that unchanged lines are less worth
            // reading, which is a renderer's call about a particular view.
            //
            // Exhaustive for `Syntax::name`'s reason: a fourth kind must answer
            // this rather than inherit an answer.
            Self::Context => "content",
        }
    }
}