feat: role gradient colors

Author: sdanialraza

packages/discord.js/src/managers/RoleManager.js

@@ -109,12 +109,23 @@ class RoleManager extends CachedManager {
    * @returns {?Snowflake}
    */
 
+  /**
+   * @typedef {Object} RoleColors
+   * @property {number} primaryColor The primary color of the role
+   * @property {?number} secondaryColor The secondary color of the role.
+   * This will make the role a gradient between the other provided colors
+   * @property {?number} tertiaryColor The tertiary color of the role.
+   * When sending `tertiaryColor` the API enforces the role color to be a holographic style with values of `primaryColor = 11127295`, `secondaryColor = 16759788`, and `tertiaryColor = 16761760`
+   */
+
   /**
    * Options used to create a new role.
    *
    * @typedef {Object} RoleCreateOptions
    * @property {string} [name] The name of the new role
-   * @property {ColorResolvable} [color] The data to create the role with
+   * @property {ColorResolvable} [color] The color to create the role with.
+   * This will still be returned by the API, but using the `colors` field is recommended when doing requests
+   * @property {RoleColors} [colors] The colors to create the role with
    * @property {boolean} [hoist] Whether or not the new role should be hoisted
    * @property {PermissionResolvable} [permissions] The permissions for the new role
    * @property {number} [position] The position of the new role
@@ -158,10 +169,20 @@ class RoleManager extends CachedManager {
       if (typeof icon !== 'string') icon = undefined;
     }
 
+    let colors;
+    if (options.colors) {
+      colors = {
+        primary_color: resolveColor(options.colors.primaryColor),
+        secondary_color: options.colors.secondaryColor && resolveColor(options.colors.secondaryColor),
+        tertiary_color: options.colors.tertiaryColor && resolveColor(options.colors.tertiaryColor),
+      };
+    }
+
     const data = await this.client.rest.post(Routes.guildRoles(this.guild.id), {
       body: {
         name,
         color,
+        colors,
         hoist,
         permissions,
         mentionable,
@@ -212,9 +233,19 @@ class RoleManager extends CachedManager {
       if (typeof icon !== 'string') icon = undefined;
     }
 
+    let colors;
+    if (options.colors) {
+      colors = {
+        primary_color: resolveColor(options.colors.primaryColor),
+        secondary_color: options.colors.secondaryColor && resolveColor(options.colors.secondaryColor),
+        tertiary_color: options.colors.tertiaryColor && resolveColor(options.colors.tertiaryColor),
+      };
+    }
+
     const body = {
       name: options.name,
       color: options.color === undefined ? undefined : resolveColor(options.color),
+      colors,
       hoist: options.hoist,
       permissions: options.permissions === undefined ? undefined : new PermissionsBitField(options.permissions),
       mentionable: options.mentionable,

packages/discord.js/src/structures/Role.js

@@ -66,6 +66,19 @@ class Role extends Base {
       this.color = data.color;
     }
 
+    if ('colors' in data) {
+      /**
+       * The colors of the role
+       *
+       * @type {RoleColors}
+       */
+      this.colors = {
+        primaryColor: data.colors.primary_color,
+        secondaryColor: data.colors.secondary_color,
+        tertiaryColor: data.colors.tertiary_color,
+      };
+    }
+
     if ('hoist' in data) {
       /**
        * If true, users that are part of this role will appear in a separate category in the users list
@@ -257,7 +270,9 @@ class Role extends Base {
    *
    * @typedef {Object} RoleData
    * @property {string} [name] The name of the role
-   * @property {ColorResolvable} [color] The color of the role, either a hex string or a base 10 number
+   * @property {ColorResolvable} [color] The color of the role, either a hex string or a base 10 number.
+   * This will still be returned by the API, but using the `colors` field is recommended when doing requests
+   * @property {RoleColors} [colors] The colors of the role
    * @property {boolean} [hoist] Whether or not the role should be hoisted
    * @property {number} [position] The position of the role
    * @property {PermissionResolvable} [permissions] The permissions of the role
@@ -330,6 +345,22 @@ class Role extends Base {
     return this.edit({ color, reason });
   }
 
+  /**
+   * Sets new colors for the role.
+   *
+   * @param {RoleColors} colors The colors of the role
+   * @param {string} [reason] Reason for changing the role's colors
+   * @returns {Promise<Role>}
+   * @example
+   * // Set the colors of a role
+   * role.setColors({ primaryColor: '#FF0000', secondaryColor: '#00FF00', tertiaryColor: '#0000FF' })
+   *   .then(updated => console.log(`Set colors of role to ${updated.colors}`))
+   *   .catch(console.error);
+   */
+  async setColors(colors, reason) {
+    return this.edit({ colors, reason });
+  }
+
   /**
    * Sets whether or not the role should be hoisted.
    *
@@ -476,6 +507,9 @@ class Role extends Base {
       this.id === role.id &&
       this.name === role.name &&
       this.color === role.color &&
+      this.colors.primaryColor === role.colors.primaryColor &&
+      this.colors.secondaryColor === role.colors.secondaryColor &&
+      this.colors.tertiaryColor === role.colors.tertiaryColor &&
       this.hoist === role.hoist &&
       this.position === role.position &&
       this.permissions.bitfield === role.permissions.bitfield &&

packages/discord.js/typings/index.d.ts

@@ -2834,9 +2834,16 @@ export class RichPresenceAssets {
   public smallImageURL(options?: ImageURLOptions): string | null;
 }
 
+export interface RoleColors {
+  primaryColor: number;
+  secondaryColor: number | null;
+  tertiaryColor: number | null;
+}
+
 export class Role extends Base {
   private constructor(client: Client<true>, data: APIRole, guild: Guild);
   public color: number;
+  public colors: RoleColors;
   public get createdAt(): Date;
   public get createdTimestamp(): number;
   public get editable(): boolean;
@@ -2865,6 +2872,7 @@ export class Role extends Base {
     checkAdmin?: boolean,
   ): Readonly<PermissionsBitField>;
   public setColor(color: ColorResolvable, reason?: string): Promise<Role>;
+  public setColors(colors: RoleColors, reason?: string): Promise<Role>;
   public setHoist(hoist?: boolean, reason?: string): Promise<Role>;
   public setMentionable(mentionable?: boolean, reason?: string): Promise<Role>;
   public setName(name: string, reason?: string): Promise<Role>;
@@ -6798,6 +6806,7 @@ export interface ResolvedOverwriteOptions {
 
 export interface RoleData {
   color?: ColorResolvable;
+  colors?: RoleColors;
   hoist?: boolean;
   icon?: Base64Resolvable | BufferResolvable | EmojiResolvable | null;
   mentionable?: boolean;