Add support for gradient roles (#3426)

Splitting out from #3382 to rebase and fix it up.

---------

Co-authored-by: jamesbt365 <[email protected]>

Author: mkrasnitski

src/builder/edit_role.rs

@@ -54,6 +54,9 @@ pub struct EditRole<'a> {
     #[serde(rename = "color")]
     colour: Option<Colour>,
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[serde(rename = "colors")]
+    colours: Option<CreateRoleColours>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     hoist: Option<bool>,
     #[serde(skip_serializing_if = "Option::is_none")]
     icon: Option<Option<String>>,
@@ -86,6 +89,7 @@ impl<'a> EditRole<'a> {
             colour: Some(role.colour),
             unicode_emoji: role.unicode_emoji.as_ref().map(|v| Some(v.clone())),
             audit_log_reason: None,
+            colours: Some(role.colours.into()),
             // TODO: Do we want to download role.icon?
             icon: None,
         }
@@ -97,6 +101,12 @@ impl<'a> EditRole<'a> {
         self
     }
 
+    /// Sets the colours of the role. Supports gradient and holographic role colours.
+    pub fn colours(mut self, colours: impl Into<CreateRoleColours>) -> Self {
+        self.colours = Some(colours.into());
+        self
+    }
+
     /// Whether or not to hoist the role above lower-positioned roles in the user list.
     pub fn hoist(mut self, hoist: bool) -> Self {
         self.hoist = Some(hoist);
@@ -150,6 +160,55 @@ impl<'a> EditRole<'a> {
     }
 }
 
+/// The colours of a Discord role, secondary_colour and tertiary_colour may only be set if
+/// the [Guild] has the `ENHANCED_ROLE_COLORS` feature.
+///
+/// Note: 2024-07-05 - tertiary_colour is currently enforced to be set with a specific pair of
+/// primary and secondary colours, for current validation see
+/// [Discord docs](https://discord.com/developers/docs/topics/permissions#role-object-role-colors-object).
+#[derive(Clone, Debug, Default, Serialize)]
+#[must_use]
+#[allow(clippy::struct_field_names)]
+pub struct CreateRoleColours {
+    primary_color: Colour,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    secondary_color: Option<Colour>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    tertiary_color: Option<Colour>,
+}
+
+impl CreateRoleColours {
+    pub fn new(primary_colour: Colour) -> Self {
+        Self {
+            primary_color: primary_colour,
+            secondary_color: None,
+            tertiary_color: None,
+        }
+    }
+
+    /// Sets the secondary colour for this role.
+    pub fn secondary_colour(mut self, secondary_colour: Colour) -> Self {
+        self.secondary_color = Some(secondary_colour);
+        self
+    }
+
+    /// Sets the tertiary colour for this role, see struct documentation for limitations.
+    pub fn tertiary_colour(mut self, tertiary_colour: Colour) -> Self {
+        self.tertiary_color = Some(tertiary_colour);
+        self
+    }
+}
+
+impl From<RoleColours> for CreateRoleColours {
+    fn from(c: RoleColours) -> CreateRoleColours {
+        CreateRoleColours {
+            primary_color: c.primary_colour,
+            secondary_color: c.secondary_colour,
+            tertiary_color: c.tertiary_colour,
+        }
+    }
+}
+
 #[cfg(feature = "http")]
 #[async_trait::async_trait]
 impl Builder for EditRole<'_> {

src/model/colour.rs

@@ -19,10 +19,12 @@
 /// # use serenity::model::id::RoleId;
 /// # use serenity::model::id::GuildId;
 /// # use serenity::model::permissions;
+/// # use serenity::model::guild::RoleColours;
 /// #
 /// # fn main() {
 /// # let role = from_value::<Role>(json!({
 /// #     "color": Colour::BLURPLE,
+/// #     "colors": RoleColours::default(),
 /// #     "hoist": false,
 /// #     "id": RoleId::new(1),
 /// #     "guild_id": GuildId::new(2),

src/model/guild/role.rs

@@ -36,6 +36,8 @@ pub struct Role {
     /// The colour of the role.
     #[serde(rename = "color")]
     pub colour: Colour,
+    #[serde(rename = "colors")]
+    pub colours: RoleColours,
     /// Indicator of whether the role is pinned above lesser roles.
     ///
     /// In the client, this causes [`Member`]s in the role to be seen above those in roles with a
@@ -76,6 +78,24 @@ pub struct Role {
     pub unicode_emoji: Option<String>,
 }
 
+/// The colours of a Discord role, secondary_colour and tertiary_colour may only be set if
+/// the [Guild] has the `ENHANCED_ROLE_COLORS` feature.
+#[cfg_attr(feature = "typesize", derive(typesize::derive::TypeSize))]
+#[derive(Clone, Copy, Debug, Default, Deserialize, Serialize)]
+#[non_exhaustive]
+pub struct RoleColours {
+    /// the primary color for the role
+    #[serde(rename = "primary_color")]
+    pub primary_colour: Colour,
+    /// the secondary color for the role, this will make the role a gradient between the other
+    /// provided colors
+    #[serde(rename = "secondary_color")]
+    pub secondary_colour: Option<Colour>,
+    /// the tertiary color for the role, this will turn the gradient into a holographic style
+    #[serde(rename = "tertiary_color")]
+    pub tertiary_colour: Option<Colour>,
+}
+
 #[cfg(feature = "model")]
 impl Role {
     /// Deletes the role.