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
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
//! # material-color-utils
//!
//! A high-performance Rust port of [Material Color Utilities](https://github.com/material-foundation/material-color-utilities).
//!
//! This crate provides algorithms and utilities for working with Material 3 (M3) dynamic color,
//! including the HCT color space, color quantization, and scheme generation.
//!
//! ## Core Concepts
//!
//! * **HCT (Hue, Chroma, Tone):** A perceptually accurate color space that separates hue from lightness (tone).
//! * **Dynamic Color:** A system that generates adaptive, accessible color schemes based on a user's source color.
//! * **Materialized Theme:** A flattened representation of a color scheme.
//!
//! ## Usage Examples
//!
//! ### High-Level Helpers (Simplified Theme Generation)
//!
//! The easiest way to get started is with the high-level `theme_from_color` helper.
//!
//! ```rust
//! use material_color_utils::utils::color_utils::Argb;
//! use material_color_utils::theme_from_color;
//!
//! // Create a theme from a source ARGB color
//! let source_color = Argb::from_hex("#4285F4").unwrap(); // Blue
//! // Builder with optional arguments for contrast, scheme variant, and more:
//! let theme = theme_from_color(source_color).call();
//!
//! // Access light and dark schemes
//! let primary_light = theme.schemes.light.primary;
//! let primary_dark = theme.schemes.dark.primary;
//!
//! println!("Light Primary: {}", primary_light);
//! println!("Dark Primary: {}", primary_dark);
//!
//! // The materialized theme structs support serde (de)serialization
//! println!("Theme json: {}", serde_json::to_string_pretty(&theme).unwrap())
//! ```
//!
//! ### Color Extraction from Image
//!
//! The `image` feature enables extracting prominent colors from images to use as source colors.
//!
//! ```rust
//! use material_color_utils::{extract_image_colors, theme_from_image};
//!
//! let img = image::open("tests/assets/img/river.png").unwrap();
//!
//! // Extract colors from an image
//! let colors = extract_image_colors(&img).call();
//! println!("Colors in 'river.png' to make a theme from: {:?}", colors);
//!
//! // Generate a theme directly from an image
//! let theme = theme_from_image(&img).call().unwrap();
//! ```
//!
//! ### Dynamic API (HCT & Custom Schemes)
//!
//! For more control, and lazy evaluation,
//! you can work directly with the HCT color space and individual scheme builders.
//!
//! ```rust
//! use material_color_utils::hct::Hct;
//! use material_color_utils::scheme::SchemeTonalSpot;
//! use material_color_utils::dynamic::material_dynamic_colors::MaterialDynamicColors;
//! use material_color_utils::dynamic::color_spec::SpecVersion;
//! use material_color_utils::utils::color_utils::Argb;
//!
//! // 1. Create a color in HCT space
//! let hct = Hct::from_argb(Argb(0xFF4285F4));
//! println!("H: {}, C: {}, T: {}", hct.hue(), hct.chroma(), hct.tone());
//!
//! // 2. Manually build a scheme (Tonal Spot, Dark Mode, High Contrast)
//! let scheme = SchemeTonalSpot::builder(hct.to_argb(), true, 0.5)
//! .spec_version(SpecVersion::Spec2026)
//! .build();
//!
//! // 3. Extract specific color roles using MaterialDynamicColors
//! let mdc = MaterialDynamicColors::new();
//! let primary = mdc.primary().get_argb(&scheme);
//! let on_primary = mdc.on_primary().get_argb(&scheme);
//!
//! println!("Primary: {:?}", primary);
//! println!("On-Primary: {:?}", on_primary);
//! ```
//!
//! ### Contrast Helpers
//!
//! Utilities for calculating contrast ratios and adjusting colors to meet accessibility standards.
//!
//! ```rust
//! use material_color_utils::utils::color_utils::Argb;
//! use material_color_utils::{get_contrast_ratio, lighter_tone, darker_tone, lighter_tone_unsafe, darker_tone_unsafe};
//!
//! let color1 = Argb(0xFF4285F4);
//! let color2 = Argb::from_hex("#FFFFFF").unwrap();
//!
//! // Calculate contrast ratio
//! let ratio = get_contrast_ratio(color1, color2);
//! println!("Contrast ratio: {:.2}", ratio);
//!
//! // Find a color that meets a target contrast ratio
//! if let Some(lighter) = lighter_tone(color1, 4.5) {
//! println!("Lighter color with 4.5 contrast: {}", lighter);
//! }
//!
//! // lighter_tone_unsafe will clip to white if it can't reach the desired contrast ratio.
//! let lighter_unsafe = lighter_tone_unsafe(color1, 4.5);
//! let darker_unsafe = darker_tone_unsafe(color1, 4.5);
//! println!("Lighter color, clipped if necessary at tone=100 (white): {}", lighter_unsafe);
//! println!("Darker color, clipped if necessary at tone=0 (black): {}", lighter_unsafe);
//! ```
//!
//! ### UI Integration
//!
//! Dynamic colors are designed for lazy evaluation, allowing for high-performance,
//! interfaces where only the colors used in the UI are calculated.
//!
//! ```rust
//! use material_color_utils::dynamic::dynamic_scheme::DynamicScheme;
//! use material_color_utils::dynamic::material_dynamic_colors::MaterialDynamicColors;
//!
//! struct MyUIComponent {
//! scheme: DynamicScheme,
//! mdc: MaterialDynamicColors,
//! }
//!
//! impl MyUIComponent {
//! fn on_render(&self) {
//! // Colors are evaluated on-demand from the current scheme
//! let bg = self.mdc.surface().get_argb(&self.scheme);
//! let primary = self.mdc.primary().get_argb(&self.scheme);
//!
//! // ... apply bg and primary to UI elements ...
//! }
//! }
//! ```
pub use *;