feat: add pageable message builder interface and implementation

Author: TheBjoRedCraft

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

@@ -0,0 +1,60 @@
+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
+
+    /**
+     * The base command used for navigating between pages.
+     * Example: "/example page %page%"
+     */
+    var pageCommand: String
+
+    /**
+     * 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)
+        }
+    }
+}

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

@@ -0,0 +1,95 @@
+package dev.slne.surf.surfapi.core.api.messages.builder
+
+import dev.slne.surf.surfapi.core.api.font.toSmallCaps
+import dev.slne.surf.surfapi.core.api.messages.adventure.buildText
+import dev.slne.surf.surfapi.core.api.messages.adventure.clickRunsCommand
+import dev.slne.surf.surfapi.core.api.messages.adventure.sendText
+import dev.slne.surf.surfapi.core.api.util.mutableObjectListOf
+import net.kyori.adventure.audience.Audience
+import net.kyori.adventure.text.Component
+import kotlin.math.ceil
+import kotlin.math.min
+
+/**
+ * Default implementation of the [SurfPageableMessageBuilder] interface.
+ */
+@SurfPageableMessageBuilderDsl
+class PageableMessageBuilder(
+    override var linesPerPage: Int = 10
+) : SurfPageableMessageBuilder {
+
+    private val lines = mutableObjectListOf<Component>()
+    private var title: Component = Component.empty()
+
+    override var pageCommand: String = "An error occurred while trying to display the page."
+
+    override fun line(block: SurfComponentBuilder.() -> Unit) {
+        lines.add(SurfComponentBuilder(block))
+    }
+
+    override fun title(block: SurfComponentBuilder.() -> Unit) {
+        title = SurfComponentBuilder(block)
+    }
+
+    override fun send(sender: Audience, page: Int) {
+        val totalPages = ceil(lines.size.toDouble() / linesPerPage).toInt().coerceAtLeast(1)
+        if (page < 1 || page > totalPages) {
+            sender.sendText {
+                error("Seite ")
+                variableValue(page.toString())
+                error(" existiert nicht.")
+            }
+            return
+        }
+
+        val start = (page - 1) * linesPerPage
+        val end = min(start + linesPerPage, lines.size)
+
+        sender.sendText {
+            if (title != Component.empty()) {
+                append(title)
+                appendNewline()
+            }
+
+            for (i in start until end) {
+                append(lines[i])
+                appendNewline()
+            }
+
+            if (totalPages > 1) {
+                append(paginationComponent(page, totalPages))
+            }
+        }
+    }
+
+    private fun navButton(label: String, targetPage: Int, enabled: Boolean): Component {
+        return buildText {
+            if (enabled) {
+                success(label)
+                clickRunsCommand(pageCommand.replace("%page%", targetPage.toString()))
+            } else {
+                error(label)
+            }
+        }
+    }
+
+    private fun paginationComponent(page: Int, totalPages: Int): Component {
+        return buildText {
+            append(navButton("[<<] ", 1, page > 1))
+            append(navButton("[<] ", page - 1, page > 1))
+            darkSpacer("Seite $page/$totalPages".toSmallCaps())
+            append(navButton(" [>] ", page + 1, page < totalPages))
+            append(navButton(" [>>]", totalPages, page < totalPages))
+        }
+    }
+
+    companion object {
+        /**
+         * DSL-style builder entry point.
+         */
+        @JvmStatic
+        operator fun invoke(block: PageableMessageBuilder.() -> Unit): PageableMessageBuilder {
+            return PageableMessageBuilder().apply(block)
+        }
+    }
+}