feat: Role gradient colours

#10986

src/managers/GuildMemberRoleManager.js

@@ -64,7 +64,7 @@ class GuildMemberRoleManager extends DataManager {
    * @readonly
    */
   get color() {
-    const coloredRoles = this.cache.filter(role => role.color);
+    const coloredRoles = this.cache.filter(role => role.colors.primaryColor);
     if (!coloredRoles.size) return null;
     return coloredRoles.reduce((prev, role) => (role.comparePositionTo(prev) > 0 ? role : prev));
   }

src/managers/RoleManager.js

@@ -11,6 +11,8 @@ const { resolveColor } = require('../util/Util');
 const Util = require('../util/Util');
 
 let cacheWarningEmitted = false;
+let deprecationEmittedForCreate = false;
+let deprecationEmittedForEdit = false;
 
 /**
  * Manages API methods for roles and stores their cache.
@@ -123,11 +125,24 @@ class RoleManager extends CachedManager {
    * @returns {?Snowflake}
    */
 
+  /**
+   * @typedef {Object} RoleColorsResolvable
+   * @property {ColorResolvable} primaryColor The primary color of the role
+   * @property {ColorResolvable} [secondaryColor] The secondary color of the role.
+   * This will make the role a gradient between the other provided colors
+   * @property {ColorResolvable} [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`.
+   * These values are available as a constant: `Constants.HolographicStyle`
+   */
+
   /**
    * Options used to create a new role.
    * @typedef {Object} CreateRoleOptions
    * @property {string} [name] The name of the new role
    * @property {ColorResolvable} [color] The data to create the role with
+   * <warn>This property is deprecated. Use `colors` instead.</warn>
+   * @property {RoleColorsResolvable} [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
@@ -153,15 +168,31 @@ class RoleManager extends CachedManager {
    * // Create a new role with data and a reason
    * guild.roles.create({
    *   name: 'Super Cool Blue People',
-   *   color: 'BLUE',
+   *   colors: {
+   *     primaryColor: 'BLUE',
+   *   },
    *   reason: 'we needed a role for Super Cool People',
    * })
    *   .then(console.log)
    *   .catch(console.error);
+   * @example
+   * // Create a role with holographic colors
+   * guild.roles.create({
+   *   name: 'Holographic Role',
+   *   reason: 'Creating a role with holographic effect',
+   *   colors: {
+   *     primaryColor: Constants.HolographicStyles.PRIMARY,
+   *     secondaryColor: Constants.HolographicStyles.SECONDARY,
+   *     tertiaryColor: Constants.HolographicStyles.TERTIARY,
+   *   },
+   * })
+   *   .then(console.log)
+   *   .catch(console.error);
    */
   async create(options = {}) {
-    let { name, color, hoist, permissions, position, mentionable, reason, icon, unicodeEmoji } = options;
+    let { permissions, icon } = options;
-    color &&= resolveColor(color);
+    const { name, color, hoist, position, mentionable, reason, unicodeEmoji } = options;
+
     if (typeof permissions !== 'undefined') permissions = new Permissions(permissions);
     if (icon) {
       const guildEmojiURL = this.guild.emojis.resolve(icon)?.url;
@@ -169,10 +200,30 @@ class RoleManager extends CachedManager {
       if (typeof icon !== 'string') icon = undefined;
     }
 
+    let colors = options.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),
+    };
+
+    if (color !== undefined) {
+      if (!deprecationEmittedForCreate) {
+        process.emitWarning(`Passing "color" to RoleManager#create() is deprecated. Use "colors" instead.`);
+      }
+
+      deprecationEmittedForCreate = true;
+
+      colors = {
+        primary_color: resolveColor(color),
+        secondary_color: null,
+        tertiary_color: null,
+      };
+    }
+
     const data = await this.client.api.guilds(this.guild.id).roles.post({
       data: {
         name,
-        color,
+        colors,
         hoist,
         permissions,
         mentionable,
@@ -214,9 +265,29 @@ class RoleManager extends CachedManager {
       if (typeof icon !== 'string') icon = undefined;
     }
 
+    let colors = data.colors && {
+      primary_color: resolveColor(data.colors.primaryColor),
+      secondary_color: data.colors.secondaryColor && resolveColor(data.colors.secondaryColor),
+      tertiary_color: data.colors.tertiaryColor && resolveColor(data.colors.tertiaryColor),
+    };
+
+    if (data.color !== undefined) {
+      if (!deprecationEmittedForEdit) {
+        process.emitWarning(`Passing "color" to RoleManager#edit() is deprecated. Use "colors" instead.`);
+      }
+
+      deprecationEmittedForEdit = true;
+
+      colors = {
+        primary_color: resolveColor(data.color),
+        secondary_color: null,
+        tertiary_color: null,
+      };
+    }
+
     const _data = {
       name: data.name,
-      color: typeof data.color === 'undefined' ? undefined : resolveColor(data.color),
+      colors,
       hoist: data.hoist,
       permissions: typeof data.permissions === 'undefined' ? undefined : new Permissions(data.permissions),
       mentionable: data.mentionable,

src/structures/Role.js

@@ -64,10 +64,35 @@ class Role extends Base {
       /**
        * The base 10 color of the role
        * @type {number}
+       * @deprecated Use {@link Role#colors} instead.
        */
       this.color = data.color;
     }
 
+    /**
+     * @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`.
+     * These values are available as a constant: `Constants.HolographicStyle`
+     */
+
+    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
@@ -267,6 +292,8 @@ 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
+   * <warn>This property is deprecated. Use `colors` instead.</warn>
+   * @property {RoleColorsResolvable} [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
@@ -325,16 +352,37 @@ class Role extends Base {
    * @param {ColorResolvable} color The color of the role
    * @param {string} [reason] Reason for changing the role's color
    * @returns {Promise<Role>}
-   * @example
+   * @deprecated Use {@link Role#setColors} instead.
-   * // Set the color of a role
-   * role.setColor('#FF0000')
-   *   .then(updated => console.log(`Set color of role to ${updated.color}`))
-   *   .catch(console.error);
    */
   setColor(color, reason) {
     return this.edit({ color }, reason);
   }
 
+  /**
+   * Sets new colors for the role.
+   *
+   * @param {RoleColorsResolvable} 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);
+   * @example
+   * // Set holographic colors using constants
+   * role.setColors({
+   *   primaryColor: Constants.HolographicStyle.Primary,
+   *   secondaryColor: Constants.HolographicStyle.Secondary,
+   *   tertiaryColor: Constants.HolographicStyle.Tertiary,
+   * })
+   *   .then(updated => console.log(`Set holographic colors for role ${updated.name}`))
+   *   .catch(console.error);
+   */
+  setColors(colors, reason) {
+    return this.edit({ colors, reason });
+  }
+
   /**
    * Sets whether or not the role should be hoisted.
    * @param {boolean} [hoist=true] Whether or not to hoist the role
@@ -480,7 +528,9 @@ class Role extends Base {
       role &&
       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 &&

src/util/Constants.js

@@ -1044,6 +1044,21 @@ exports.Colors = {
   NOT_QUITE_BLACK: 0x23272a,
 };
 
+/**
+ * Holographic color values for role styling.
+ * When using `tertiaryColor`, the API enforces these specific values for holographic effect.
+ *
+ * * PRIMARY: 11127295 (0xA9FFFF)
+ * * SECONDARY: 16759788 (0xFFCCCC)
+ * * TERTIARY: 16761760 (0xFFE0A0)
+ * @typedef {Object<string, number>} HolographicStyle
+ */
+exports.HolographicStyles = {
+  PRIMARY: 11_127_295,
+  SECONDARY: 16_759_788,
+  TERTIARY: 16_761_760,
+};
+
 /**
  * The value set for the explicit content filter levels for a guild:
  * * DISABLED
@@ -1895,4 +1910,5 @@ function createEnum(keys) {
  * @property {Object<WebhookType, number>} WebhookTypes The value set for a webhooks type.
  * @property {WSCodes} WSCodes The types of WebSocket error codes.
  * @property {Object<WSEventType, WSEventType>} WSEvents The type of a WebSocket message event.
+ * @property {HolographicStyle} HolographicStyles Holographic color values for role styling.
  */

typings/index.d.ts

@@ -3044,9 +3044,23 @@ export class RichPresenceAssets {
   public setSmallText(text?: string): this;
 }
 
+export interface RoleColors {
+  primaryColor: number;
+  secondaryColor: number | null;
+  tertiaryColor: number | null;
+}
+
+export interface RoleColorsResolvable {
+  primaryColor: ColorResolvable;
+  secondaryColor?: ColorResolvable;
+  tertiaryColor?: ColorResolvable;
+}
+
 export class Role extends Base {
   private constructor(client: Client, data: RawRoleData, guild: Guild);
+  /** @deprecated Use {@link Role.colors} instead. */
   public color: number;
+  public colors: RoleColors;
   public readonly createdAt: Date;
   public readonly createdTimestamp: number;
   /** @deprecated This will be removed in the next major version, see https://github.com/discordjs/discord.js/issues/7091 */
@@ -3073,7 +3087,9 @@ export class Role extends Base {
   public equals(role: Role): boolean;
   public iconURL(options?: StaticImageURLOptions): string | null;
   public permissionsIn(channel: NonThreadGuildBasedChannel | Snowflake, checkAdmin?: boolean): Readonly<Permissions>;
+  /** @deprecated Use {@link Role.setColors} instead. */
   public setColor(color: ColorResolvable, reason?: string): Promise<Role>;
+  public setColors(colors: RoleColorsResolvable, 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>;
@@ -4203,6 +4219,11 @@ export const Constants: {
   GuildScheduledEventEntityTypes: EnumHolder<typeof GuildScheduledEventEntityTypes>;
   GuildScheduledEventPrivacyLevels: EnumHolder<typeof GuildScheduledEventPrivacyLevels>;
   GuildScheduledEventStatuses: EnumHolder<typeof GuildScheduledEventStatuses>;
+  HolographicStyles: {
+    PRIMARY: 11_127_295;
+    SECONDARY: 16_759_788;
+    TERTIARY: 16_761_760;
+  };
   IntegrationExpireBehaviors: IntegrationExpireBehaviors[];
   SelectMenuComponentTypes: EnumHolder<typeof SelectMenuComponentTypes>;
   RelationshipTypes: EnumHolder<typeof RelationshipTypes>;
@@ -7742,7 +7763,9 @@ export interface ResolvedOverwriteOptions {
 
 export interface RoleData {
   name?: string;
+  /** @deprecated Use {@link RoleData.colors} instead. */
   color?: ColorResolvable;
+  colors?: RoleColorsResolvable;
   hoist?: boolean;
   position?: number;
   permissions?: PermissionResolvable;