feat: add pageable message builder interface and implementation

gradle.properties

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

surf-api-bukkit/surf-api-bukkit-api/api/surf-api-bukkit-api.api

@@ -3830,6 +3830,25 @@ public final class dev/slne/surf/surfapi/core/api/messages/adventure/Title_exten
 	public static final fun titleTimes (Lkotlin/jvm/functions/Function1;)Lnet/kyori/adventure/title/Title$Times;
 }
 
+public final class dev/slne/surf/surfapi/core/api/messages/builder/PageableMessageBuilder : dev/slne/surf/surfapi/core/api/messages/builder/SurfPageableMessageBuilder {
+	public static final field Companion Ldev/slne/surf/surfapi/core/api/messages/builder/PageableMessageBuilder$Companion;
+	public fun <init> ()V
+	public fun <init> (I)V
+	public synthetic fun <init> (IILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public fun getLinesPerPage ()I
+	public fun getPageCommand ()Ljava/lang/String;
+	public static final fun invoke (Lkotlin/jvm/functions/Function1;)Ldev/slne/surf/surfapi/core/api/messages/builder/PageableMessageBuilder;
+	public fun line (Lkotlin/jvm/functions/Function1;)V
+	public fun send (Lnet/kyori/adventure/audience/Audience;I)V
+	public fun setLinesPerPage (I)V
+	public fun setPageCommand (Ljava/lang/String;)V
+	public fun title (Lkotlin/jvm/functions/Function1;)V
+}
+
+public final class dev/slne/surf/surfapi/core/api/messages/builder/PageableMessageBuilder$Companion {
+	public final fun invoke (Lkotlin/jvm/functions/Function1;)Ldev/slne/surf/surfapi/core/api/messages/builder/PageableMessageBuilder;
+}
+
 public abstract interface class dev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder : net/kyori/adventure/text/TextComponent$Builder {
 	public static final field Companion Ldev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder$Companion;
 	public abstract fun append (Ljava/lang/Iterable;)Ldev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder;
@@ -4082,6 +4101,26 @@ public final class dev/slne/surf/surfapi/core/api/messages/builder/SurfComponent
 	public static fun warning (Ldev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder;Z)Ldev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder;
 }
 
+public abstract interface class dev/slne/surf/surfapi/core/api/messages/builder/SurfPageableMessageBuilder {
+	public static final field Companion Ldev/slne/surf/surfapi/core/api/messages/builder/SurfPageableMessageBuilder$Companion;
+	public abstract fun getLinesPerPage ()I
+	public abstract fun getPageCommand ()Ljava/lang/String;
+	public static fun invoke (ILkotlin/jvm/functions/Function1;)Ldev/slne/surf/surfapi/core/api/messages/builder/PageableMessageBuilder;
+	public abstract fun line (Lkotlin/jvm/functions/Function1;)V
+	public abstract fun send (Lnet/kyori/adventure/audience/Audience;I)V
+	public abstract fun setLinesPerPage (I)V
+	public abstract fun setPageCommand (Ljava/lang/String;)V
+	public abstract fun title (Lkotlin/jvm/functions/Function1;)V
+}
+
+public final class dev/slne/surf/surfapi/core/api/messages/builder/SurfPageableMessageBuilder$Companion {
+	public final fun invoke (ILkotlin/jvm/functions/Function1;)Ldev/slne/surf/surfapi/core/api/messages/builder/PageableMessageBuilder;
+	public static synthetic fun invoke$default (Ldev/slne/surf/surfapi/core/api/messages/builder/SurfPageableMessageBuilder$Companion;ILkotlin/jvm/functions/Function1;ILjava/lang/Object;)Ldev/slne/surf/surfapi/core/api/messages/builder/PageableMessageBuilder;
+}
+
+public abstract interface annotation class dev/slne/surf/surfapi/core/api/messages/builder/SurfPageableMessageBuilderDsl : java/lang/annotation/Annotation {
+}
+
 public final class dev/slne/surf/surfapi/core/api/messages/bundle/SurfMessageBundle {
 	public fun <init> (Ljava/lang/Class;Ljava/lang/String;Ljava/nio/file/Path;)V
 	public fun <init> (Ljava/lang/Class;Ljava/lang/String;Ljava/nio/file/Path;Ljava/lang/ClassLoader;)V

surf-api-core/surf-api-core-api/api/surf-api-core-api.api

@@ -2586,6 +2586,25 @@ public final class dev/slne/surf/surfapi/core/api/messages/adventure/Title_exten
 	public static final fun titleTimes (Lkotlin/jvm/functions/Function1;)Lnet/kyori/adventure/title/Title$Times;
 }
 
+public final class dev/slne/surf/surfapi/core/api/messages/builder/PageableMessageBuilder : dev/slne/surf/surfapi/core/api/messages/builder/SurfPageableMessageBuilder {
+	public static final field Companion Ldev/slne/surf/surfapi/core/api/messages/builder/PageableMessageBuilder$Companion;
+	public fun <init> ()V
+	public fun <init> (I)V
+	public synthetic fun <init> (IILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public fun getLinesPerPage ()I
+	public fun getPageCommand ()Ljava/lang/String;
+	public static final fun invoke (Lkotlin/jvm/functions/Function1;)Ldev/slne/surf/surfapi/core/api/messages/builder/PageableMessageBuilder;
+	public fun line (Lkotlin/jvm/functions/Function1;)V
+	public fun send (Lnet/kyori/adventure/audience/Audience;I)V
+	public fun setLinesPerPage (I)V
+	public fun setPageCommand (Ljava/lang/String;)V
+	public fun title (Lkotlin/jvm/functions/Function1;)V
+}
+
+public final class dev/slne/surf/surfapi/core/api/messages/builder/PageableMessageBuilder$Companion {
+	public final fun invoke (Lkotlin/jvm/functions/Function1;)Ldev/slne/surf/surfapi/core/api/messages/builder/PageableMessageBuilder;
+}
+
 public abstract interface class dev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder : net/kyori/adventure/text/TextComponent$Builder {
 	public static final field Companion Ldev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder$Companion;
 	public abstract fun append (Ljava/lang/Iterable;)Ldev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder;
@@ -2838,6 +2857,26 @@ public final class dev/slne/surf/surfapi/core/api/messages/builder/SurfComponent
 	public static fun warning (Ldev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder;Z)Ldev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder;
 }
 
+public abstract interface class dev/slne/surf/surfapi/core/api/messages/builder/SurfPageableMessageBuilder {
+	public static final field Companion Ldev/slne/surf/surfapi/core/api/messages/builder/SurfPageableMessageBuilder$Companion;
+	public abstract fun getLinesPerPage ()I
+	public abstract fun getPageCommand ()Ljava/lang/String;
+	public static fun invoke (ILkotlin/jvm/functions/Function1;)Ldev/slne/surf/surfapi/core/api/messages/builder/PageableMessageBuilder;
+	public abstract fun line (Lkotlin/jvm/functions/Function1;)V
+	public abstract fun send (Lnet/kyori/adventure/audience/Audience;I)V
+	public abstract fun setLinesPerPage (I)V
+	public abstract fun setPageCommand (Ljava/lang/String;)V
+	public abstract fun title (Lkotlin/jvm/functions/Function1;)V
+}
+
+public final class dev/slne/surf/surfapi/core/api/messages/builder/SurfPageableMessageBuilder$Companion {
+	public final fun invoke (ILkotlin/jvm/functions/Function1;)Ldev/slne/surf/surfapi/core/api/messages/builder/PageableMessageBuilder;
+	public static synthetic fun invoke$default (Ldev/slne/surf/surfapi/core/api/messages/builder/SurfPageableMessageBuilder$Companion;ILkotlin/jvm/functions/Function1;ILjava/lang/Object;)Ldev/slne/surf/surfapi/core/api/messages/builder/PageableMessageBuilder;
+}
+
+public abstract interface annotation class dev/slne/surf/surfapi/core/api/messages/builder/SurfPageableMessageBuilderDsl : java/lang/annotation/Annotation {
+}
+
 public final class dev/slne/surf/surfapi/core/api/messages/bundle/SurfMessageBundle {
 	public fun <init> (Ljava/lang/Class;Ljava/lang/String;Ljava/nio/file/Path;)V
 	public fun <init> (Ljava/lang/Class;Ljava/lang/String;Ljava/nio/file/Path;Ljava/lang/ClassLoader;)V

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

@@ -0,0 +1,54 @@
+package dev.slne.surf.surfapi.core.api.messages.builder
+
+import net.kyori.adventure.audience.Audience
+
+/**
+ * DSL interface for building pageable messages using [PageableMessageBuilder].
+ * Provides a structured way to define paginated message content and send it to an [Audience].
+ */
+@DslMarker
+annotation class SurfPageableMessageBuilderDsl
+
+@SurfPageableMessageBuilderDsl
+interface SurfPageableMessageBuilder {
+
+    /**
+     * The number of lines displayed per page.
+     */
+    var linesPerPage: Int
+
+    /**
+     * Sets the message title.
+     *
+     * @param block a builder block to configure the title using [SurfComponentBuilder]
+     */
+    fun title(block: SurfComponentBuilder.() -> Unit)
+
+    /**
+     * Adds a line of content to the message.
+     *
+     * @param block a builder block to configure the line using [SurfComponentBuilder]
+     */
+    fun line(block: SurfComponentBuilder.() -> Unit)
+
+    /**
+     * Sends the paginated message to the given [Audience] at the specified page.
+     *
+     * @param sender the audience receiving the message
+     * @param page the page number to display (starting at 1)
+     */
+    fun send(sender: Audience, page: Int)
+
+    companion object {
+        /**
+         * Creates a new [PageableMessageBuilder] instance and applies the provided DSL block.
+         *
+         * @param block the DSL configuration block
+         * @return a fully constructed [PageableMessageBuilder] instance
+         */
+        @JvmStatic
+        operator fun invoke(linesPerPage: Int = 10, block: PageableMessageBuilder.() -> Unit): PageableMessageBuilder {
+            return PageableMessageBuilder(linesPerPage).apply(block)
+        }
+    }
+}