feat: add dialog API with builders for various dialog components

[twisti-dev]

Overview of Changes

This PR introduces a new dialog API layer to the surf-api-bukkit module, enabling a fluent builder-style approach to constructing dialogs in Paper. It includes high-level helper functions, core API definitions, and a set of builder classes for dialog components (actions, buttons, body, inputs, types, and base configuration).

Details

• chore: configuration updates

  • Add Maven Pull Request repository (https://maven-prs.papermc.io/Paper/pr12671) to .idea/jarRepositories.xml and build.gradle.kts for testing dependencies.
  • Delete obsolete .idea/vcs.xml.
  • Bump version to 1.21.7-2.21.0 in gradle.properties.

• feat: define dialog API interface

  • Extend surf-api-bukkit-api.api to expose CommonDialogsKt, DialogBuilderKt, and builder classes under dev.slne.surf.surfapi.bukkit.api.dialog and ...dialog.builder.

• feat: high-level dialog helpers

  • CommonDialogs.kt: Add top-level noticeDialog and noticeDialogWithBuilder functions.
  • DialogBuilder.kt: Add dialog {}, Dialog {} helpers and extensions for DialogRegistryEntry.Builder.

• feat: builder implementations for dialog components

  • DialogActionBuilder.kt: Fluent API for creating DialogAction instances.
  • DialogActionButtonBuilder.kt: Builder for ActionButton (label, tooltip, width, action).
  • DialogBaseBuilder.kt: Configure DialogBase (title, external title, body, inputs, afterAction).
  • DialogBodyBuilder.kt: Compose DialogBody entries (plain messages, item displays).
  • DialogInputBuilder.kt: Define dialog inputs (text, boolean, number range, single option).
  • DialogTypeBuilder.kt: Configure dialog types (notice, confirmation, list, multi-action, server links).

Motivation

• Simplify and standardize dialog creation across the plugin ecosystem.
• Provide a clear, fluent API, reducing boilerplate when constructing complex dialogs.
• Leverage Kotlin DSLs to improve developer ergonomics and code readability.

Impact

• Developer Experience: Dramatically reduces code verbosity when creating dialogs.
• Consistency: Enforces a unified pattern for dialog construction.
• Extensibility: The builder pattern makes it easier to add new dialog features in the future.

Testing

• Manually verified basic dialogs:
  • Notice dialogs via noticeDialog { ... }.
  • Confirmation dialogs with custom yes/no buttons.
  • Multi-action and list-type dialogs.
• Confirmed Maven PR dependencies resolve correctly and module builds successfully under version 1.21.7-2.21.0.

Additional Notes

• Future work: Add automated unit tests for each builder and coverage tests for edge cases (e.g., missing required fields).
• Consider adding examples and documentation snippets to the project README.

---

Download Build‑JARs for this PR: pr-built-jars.zip

[Copilot]

Pull Request Overview

This PR introduces a fluent, builder-style API for constructing Paper dialogs in the surf-api-bukkit module.

• Adds high-level DSL functions (dialog {}, noticeDialog {}, etc.) and exposes them in the API.
• Implements builder classes for dialog types, bodies, inputs, base configuration, actions, and action buttons.
• Updates module exports and bumps version to 1.21.7-2.21.0.

Reviewed Changes

Copilot reviewed 10 out of 14 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/.../builder/DialogTypeBuilder.kt	Builds different DialogType variants
src/.../builder/DialogInputBuilder.kt	DSL for defining dialog inputs
src/.../builder/DialogBodyBuilder.kt	DSL for composing dialog body entries
src/.../builder/DialogBaseBuilder.kt	Configures common dialog base settings
src/.../builder/DialogActionButtonBuilder.kt	Fluent builder for action buttons
src/.../builder/DialogActionBuilder.kt	Fluent builder for dialog actions
src/.../DialogBuilder.kt	Top-level dialog {} DSL functions
src/.../CommonDialogs.kt	High-level notice dialog helpers
api/surf-api-bukkit-api.api	Exposes new DSL entry points in API surface
gradle.properties	Bumps version to 1.21.7-2.21.0

Files not reviewed (3)

• .idea/jarRepositories.xml: Language not supported
• .idea/modules.xml: Language not supported
• .idea/vcs.xml: Language not supported

Comments suppressed due to low confidence (3)

surf-api-bukkit/surf-api-bukkit-api/src/main/kotlin/dev/slne/surf/surfapi/bukkit/api/dialog/builder/DialogTypeBuilder.kt:14

• [nitpick] Add a KDoc comment explaining the purpose and usage of this builder to improve discoverability and maintainability of the DSL.

class DialogTypeBuilder {

surf-api-bukkit/surf-api-bukkit-api/src/main/kotlin/dev/slne/surf/surfapi/bukkit/api/dialog/builder/DialogTypeBuilder.kt:72

• Consider adding unit tests for DialogTypeBuilder.build() to verify each dialog type variant (notice, confirmation, list, etc.) is constructed correctly.

    internal fun build(): DialogType {

surf-api-bukkit/surf-api-bukkit-api/src/main/kotlin/dev/slne/surf/surfapi/bukkit/api/dialog/builder/DialogActionButtonBuilder.kt:11

• [nitpick] The inline comment // permission is unclear here. Either clarify its intent in a KDoc or remove it if it's vestigial.

class DialogActionButtonBuilder { // permission

[twisti-dev]

Depends on PaperMC/Paper#12671