feat: add adventure message extensions for books, boss bars, titles, … (#39)

Author: twisti-dev

gradle.properties

@@ -9,5 +9,5 @@ javaVersion=21
 mcVersion=1.21.4
 
 group=dev.slne.surf
-version=1.21.4-2.1.3-SNAPSHOT
+version=1.21.4-2.2.0-SNAPSHOT
 relocationPrefix=dev.slne.surf.surfapi.libs

surf-api-bukkit/surf-api-bukkit-plugin-test/src/main/kotlin/dev/slne/surf/surfapi/bukkit/test/command/subcommands/visualizer/SingleLocationVisualizerTest.kt

@@ -11,7 +11,7 @@ import dev.slne.surf.surfapi.bukkit.api.visualizer.surfVisualizerApi
 import dev.slne.surf.surfapi.bukkit.api.visualizer.visualizer.ExperimentalVisualizerApi
 import dev.slne.surf.surfapi.bukkit.api.visualizer.visualizer.SurfVisualizerSingleLocation
 import dev.slne.surf.surfapi.core.api.messages.Colors
-import dev.slne.surf.surfapi.core.api.messages.buildText
+import dev.slne.surf.surfapi.core.api.messages.adventure.buildText
 import dev.slne.surf.surfapi.core.api.random.RandomSelector
 import dev.slne.surf.surfapi.core.api.util.mutableObject2ObjectMapOf
 import net.kyori.adventure.text.Component

surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/messages/Colors.kt

@@ -6,97 +6,110 @@ import net.kyori.adventure.text.format.TextColor
 import net.kyori.adventure.text.format.TextColor.color
 
 /**
- * A class that contains all the colors used in the Surf system. This class is used to provide a
- * uniform appearance across all Surf plugins.
- * [Simons dc post](https://discord.com/channels/1094422317783851108/1096084922499862658)
+ * A class that defines all the colors used in the Surf system, ensuring a consistent visual style
+ * across all Surf plugins.
+ * This class provides predefined colors for various UI elements, including
+ * informational messages, warnings, errors, and formatting components.
+ *
+ * For reference,
+ * see [Simons dc post](https://discord.com/channels/1094422317783851108/1096084922499862658).
  *
  * @see [Simons dc post](https://discord.com/channels/1094422317783851108/1096084922499862658)
  */
 @Suppress("unused")
 interface Colors {
     companion object {
         // -------------------- Surf Colors -------------------- //
+
         /**
-         * PRIMARY color (#3b92d1). Generally not used in our system. However, an example of its use could
-         * be for titles, subtitles, etc.
+         * The primary Surf color (#3b92d1).
+         * Although rarely used in the system, it can be utilized
+         * for elements like titles and subtitles.
          */
         @JvmField
         val PRIMARY: TextColor = color(0x3b92d1)
 
         /**
-         * SECONDARY color (#5b5b5b). Also seldom used in our system. Could be used for elements like
-         * subtitles.
+         * The secondary Surf color (#5b5b5b), mainly used for elements such as subtitles.
          */
         @JvmField
         val SECONDARY: TextColor = color(0x5b5b5b)
 
         /**
-         * INFO color (#40d1db). Used to inform the user about a specific situation. Typically, it's not a
-         * follow-up to a user action. Exceptions include queued user actions that update after a delay
-         * (e.g., status changes not related to Success or Danger), and for toggle messages (e.g., "You
-         * have [deactivated/activated] the chat").
+         * The info color (#40d1db).
+         * Used to convey neutral information to users that is not directly
+         * a result of their actions,
+         * except in cases such as delayed status updates or toggle messages.
          */
         @JvmField
         val INFO: TextColor = color(0x40d1db)
 
         /**
-         * SUCCESS color (#65ff64). Indicates a positive outcome of an action performed by the user. Used
-         * only in direct response to the user.
+         * The success color (#65ff64).
+         * Indicates a positive outcome of a user action and is always
+         * used in direct response to the user.
          */
         @JvmField
         val SUCCESS: TextColor = color(0x65ff64)
 
         /**
-         * WARNING color (#f9c353). Used as a direct warning to the user. This could be a response to a
-         * user action or a system notification, and serves as a precursor to Danger.
+         * The warning color (#f9c353).
+         * Used to caution users about potential issues, often serving
+         * as a precursor to an error message.
          */
         @JvmField
         val WARNING: TextColor = color(0xf9c353)
 
         /**
-         * ERROR (or DANGER) color (#ee3d51). Represents error messages directed at the user. These can
-         * follow a direct action by the user, or serve as a warning about potential issues.
+         * The error (or danger) color (#ee3d51).
+         * Represents error messages directed at the user,
+         * often following a direct user action or warning of a critical issue.
          */
         @JvmField
         val ERROR: TextColor = color(0xee3d51)
 
         /**
-         * VARIABLE_KEY color (#3b92d1). Mainly used as a key in listings (e.g., "Key 1: Value", "Key 2:
-         * Value", etc.).
+         * The variable key color (#3b92d1).
+         * Typically used for key-value pair representations,
+         * such as in lists (for example, "Key 1: Value").
          */
         @JvmField
         val VARIABLE_KEY: TextColor = INFO
 
         /**
-         * VARIABLE_VALUE color (#f9c353). Primarily used in listings and chat messages as a variable
-         * (e.g., "Your property [PROPERTY] has been sold.").
+         * The variable value color (#f9c353).
+         * Commonly used to highlight values in lists and
+         * chat messages (for example, "Your property 'PROPERTY' has been sold.").
          */
         @JvmField
         val VARIABLE_VALUE: TextColor = WARNING
 
         /**
-         * SPACER color (GRAY). Used for various forms of spacers, such as "-, ..., /, etc."
+         * The spacer color (GRAY). Used for visual separators such as "-", "...", and "/".
          */
         @JvmField
         val SPACER: NamedTextColor = NamedTextColor.GRAY
 
         /**
-         * DARK_SPACER color (DARK_GRAY). Used for dark spacers, such as those needed in prefixes like
-         * ">>", "|", etc.
+         * The dark spacer color (DARK_GRAY).
+         * Used for darker separators, such as those found in
+         * prefixes like ">>" or "|".
          */
         @JvmField
         val DARK_SPACER: NamedTextColor = NamedTextColor.DARK_GRAY
 
         /**
-         * PREFIX color (#3b92d1). Used for the color of every prefix to provide a uniform appearance.
+         * The default prefix color (#3b92d1).
+         * Applied to all prefixes for consistency across Surf plugins.
          */
         @JvmField
         val PREFIX_COLOR: TextColor = PRIMARY
 
-        // ----------------------------------------------------- //
         // -------------------- Default Colors -------------------- //
+
         /**
-         * The prefix for all Surf plugins
+         * The default prefix used across all Surf plugins, ensuring a recognizable and uniform
+         * identifier in messages.
          */
         @JvmField
         val PREFIX: Component = Component.text(">> ", DARK_SPACER)
@@ -122,61 +135,61 @@ interface Colors {
         val DARK_GREEN: NamedTextColor = NamedTextColor.DARK_GREEN
 
         /**
-         * Represents the named text color DARK_AQUA.
+         * Represents the color dark aqua.
          */
         @JvmField
         val DARK_AQUA: NamedTextColor = NamedTextColor.DARK_AQUA
 
         /**
-         * Represents the dark red color.
+         * Represents the color dark red.
          */
         @JvmField
         val DARK_RED: NamedTextColor = NamedTextColor.DARK_RED
 
         /**
-         * Represents the dark purple named text color.
+         * Represents the color dark purple.
          */
         @JvmField
         val DARK_PURPLE: NamedTextColor = NamedTextColor.DARK_PURPLE
 
         /**
-         * The GOLD color for naming text.
+         * Represents the color gold.
          */
         @JvmField
         val GOLD: NamedTextColor = NamedTextColor.GOLD
 
         /**
-         * Represents the named text color "GRAY".
+         * Represents the color gray.
          */
         @JvmField
         val GRAY: NamedTextColor = NamedTextColor.GRAY
 
         /**
-         * Represents the named text color "DARK_GRAY".
+         * Represents the color dark gray.
          */
         @JvmField
         val DARK_GRAY: NamedTextColor = NamedTextColor.DARK_GRAY
 
         /**
-         * Represents the named text color "BLUE".
+         * Represents the color blue.
          */
         @JvmField
         val BLUE: NamedTextColor = NamedTextColor.BLUE
 
         /**
-         * Represents the named text color "GREEN".
+         * Represents the color green.
          */
         @JvmField
         val GREEN: NamedTextColor = NamedTextColor.GREEN
 
         /**
-         * Represents the named text color "AQUA".
+         * Represents the color aqua.
          */
         @JvmField
         val AQUA: NamedTextColor = NamedTextColor.AQUA
 
         /**
-         * Represents the named text color "RED".
+         * Represents the color red.
          */
         @JvmField
         val RED: NamedTextColor = NamedTextColor.RED
@@ -193,13 +206,10 @@ interface Colors {
         @JvmField
         val YELLOW: NamedTextColor = NamedTextColor.YELLOW
 
-        // --------------------------------------------------------- //
-        // -------------------- Prefix -------------------- //
         /**
          * Represents the color white.
          */
         @JvmField
         val WHITE: NamedTextColor = NamedTextColor.WHITE
-        // ------------------------------------------------ //
     }
 }