tinted-builder 0.16.0

A Tinted Theming template builder which uses yaml color schemes to generate theme files.
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

# tinted-builder

[![Matrix Chat](https://img.shields.io/matrix/tinted-theming:matrix.org)](https://matrix.to/#/#tinted-theming:matrix.org)
[![Crates.io](https://img.shields.io/crates/v/tinted-builder.svg)](https://crates.io/crates/tinted-builder)
[![Tests](https://github.com/tinted-theming/tinted-builder-rust/actions/workflows/ci.yml/badge.svg)](https://github.com/tinted-theming/tinted-builder-rust/actions/workflows/ci.yml)

A Rust library to generate [base16], [base24], and Tinted8 templates
using the `0.11.1` [builder specification].

This library exposes a `Scheme` enum and `Template` struct which you can
use to generate your own themes using base16, base24, and Tinted8
templates and scheme files.

Internally tinted-builder uses [ribboncurls] to render the templates.

## Tinted8 (library)

In addition to Base16/Base24, the library supports Tinted8 schemes. Deserialize a Tinted8 scheme and wrap it in `Scheme::Tinted8` to render templates with nested variables.

```rust
use tinted_builder::{Scheme, Template};
use tinted_builder::tinted8::Scheme as T8Scheme;

let yml = r##"
scheme:
  system: "tinted8"
  supports:
    styling-spec: "0.2.0"
  author: "User <user@example.com>"
  name: "Ayu Mirage"
  slug: "ayu-mirage"
variant: "dark"
palette:
  black:   "#131721"
  red:     "#f07178"
  green:   "#b8cc52"
  yellow:  "#ffb454"
  blue:    "#59c2ff"
  magenta: "#d2a6ff"
  cyan:    "#95e6cb"
  white:   "#e6e1cf"
"##;

let t8: T8Scheme = serde_yaml::from_str(yml).unwrap();
let scheme = Scheme::Tinted8(Box::new(t8));
let tpl = Template::new("{{ palette.blue.bright.hex }}".to_string(), scheme);
let out = tpl.render().unwrap();
```

### Tinted8 template variables

- Palette: `palette.<color>.<variant>.<field>` (e.g., `palette.red.normal.hex`)
- UI: `ui.<key>.<field>` (e.g., `ui.background.rgb.r`)
- Syntax: `syntax.<key>.<field>` (e.g., `syntax.string.dec.g`)

Each color object provides:

- hex: 6-digit hex string without `#`
- hex-r / hex-g / hex-b: 2-digit hex components
- hex-bgr: 6-digit hex in BGR order
- rgb: numbers { r, g, b } in 0–255
- rgb16: numbers { r, g, b } in 0–65535 (8-bit × 257)
- dec: strings { r, g, b } in 0–1 with 8-decimal precision

Note: Base16/Base24 templates use flat keys such as `base0A-hex`, `base0A-rgb-r`. Tinted8 uses nested objects as shown above.

## Installation

```sh
cargo add tinted-builder
```

## Usage

```rust
use tinted_builder::{Scheme, Template};

let template = String::from(r#"/* Some CSS file with {{scheme-name}} theme */
.someCssSelector { background-color: #{{base00-hex}} }
.someOtherCssSelector { background-color: #{{base0F-hex}} }"#);
let scheme_str = r##"system: "base16"
name: "UwUnicorn"
author: "Fernando Marques (https://github.com/RakkiUwU) and Gabriel Fontes (https://github.com/Misterio77)"
variant: "dark"
palette:
  base00: "#241b26"
  base01: "#2f2a3f"
  base02: "#46354a"
  base03: "#6c3cb2"
  base04: "#7e5f83"
  base05: "#eed5d9"
  base06: "#d9c2c6"
  base07: "#e4ccd0"
  base08: "#877bb6"
  base09: "#de5b44"
  base0A: "#a84a73"
  base0B: "#c965bf"
  base0C: "#9c5fce"
  base0D: "#6a9eb5"
  base0E: "#78a38f"
  base0F: "#a3a079""##;
let scheme = Scheme::from_yaml(scheme_str).unwrap();
let template = Template::new(template, scheme);
let output = template
  .render()
  .unwrap();

  assert_eq!(output, r#"/* Some CSS file with UwUnicorn theme */
.someCssSelector { background-color: #241b26 }
.someOtherCssSelector { background-color: #a3a079 }"#);
```

1. Parse the scheme YAML using `Scheme::from_yaml(&scheme_str)`, which
   auto-detects the system (base16, base24, or tinted8). You can also
   construct variants directly, e.g.
   `Scheme::Base16(serde_yaml::from_str(&scheme_str).unwrap())`.
2. Create a template by passing the mustache text and the `Scheme` into
   `Template::new(mustache_text, scheme)`.
3. Render the template with `template.render()`, which returns a
   `Result<String, TintedBuilderError>`.

## Contributing

Contributions are welcome! Have a look at [CONTRIBUTING.md] for more
information.

## License

tinted-builder falls under the [GPL-3.0] license. Have a look at the
[LICENSE] file.

[latest schemes repository]: https://github.com/tinted-theming/schemes
[home repository]: https://github.com/tinted-theming/home
[builder specification]: https://github.com/tinted-theming/home/blob/main/builder.md
[base16]: https://github.com/tinted-theming/home/blob/main/styling.md
[base24]: https://github.com/tinted-theming/base24/blob/master/styling.md
[ribboncurls]: https://github.com/tinted-theming/ribboncurls
[CONTRIBUTING.md]: ../CONTRIBUTING.md
[repository releases]: https://github.com/tinted-theming/tinted-builder-rust/releases/latest
[GPL-3.0]: https://github.com/IQAndreas/markdown-licenses/blob/master/gnu-gpl-v3.0.md
[LICENSE]: ../LICENSE