diff --git a/flare/core/src/main/java/space/maxus/flare/ui/compose/complex/Composition.java b/flare/core/src/main/java/space/maxus/flare/ui/compose/complex/Composition.java index 1b3036c..3ed49f2 100644 --- a/flare/core/src/main/java/space/maxus/flare/ui/compose/complex/Composition.java +++ b/flare/core/src/main/java/space/maxus/flare/ui/compose/complex/Composition.java @@ -4,6 +4,7 @@ import org.bukkit.event.inventory.InventoryClickEvent; import org.bukkit.event.inventory.InventoryDragEvent; import org.bukkit.inventory.ItemStack; +import org.jetbrains.annotations.ApiStatus; import org.jetbrains.annotations.Contract; import org.jetbrains.annotations.NotNull; import space.maxus.flare.ui.Composable; @@ -15,14 +16,30 @@ import java.util.*; +/** + * A composition is a collection of multiple components, composed by relative coordinates. + *
+ * See more in Flare docs: Composition + */ public interface Composition extends Composable, Configurable { + /** + * Constructs a composition out of an array of packed composables + * @param comps Composable elements to be included + * @return A new composition + * @see space.maxus.flare.ui.ComposableLike#inside(ComposableSpace) + */ @Contract("_ -> new") static @NotNull Composition of(PackedComposable... comps) { return new ExplicitComposition(Arrays.asList(comps)); } + @ApiStatus.Internal List fitIn(ComposableSpace space); + /** + * Returns all composable elements inside this composition + * @return All composable elements inside this composition + */ List children(); @Override diff --git a/flare/core/src/main/java/space/maxus/flare/ui/compose/complex/Modal.java b/flare/core/src/main/java/space/maxus/flare/ui/compose/complex/Modal.java index a38bdcb..ce3fa0d 100644 --- a/flare/core/src/main/java/space/maxus/flare/ui/compose/complex/Modal.java +++ b/flare/core/src/main/java/space/maxus/flare/ui/compose/complex/Modal.java @@ -3,6 +3,7 @@ import lombok.EqualsAndHashCode; import lombok.Getter; import lombok.ToString; +import org.jetbrains.annotations.ApiStatus; import org.jetbrains.annotations.NotNull; import space.maxus.flare.item.ItemProvider; import space.maxus.flare.ui.Composable; @@ -17,26 +18,76 @@ import java.util.concurrent.atomic.AtomicBoolean; import java.util.function.Consumer; +/** + * A modal is a composable that opens an inner frame on click. + *
+ * See more in Flare docs: Modal + * + * @see Modals + */ public interface Modal extends ProviderRendered, Configurable, Disable { + /** + * Constructs a new modal + * @param provider Item provider for modal + * @param dimensions Dimensions of the modal window + * @param initializer The modal frame configurator + * @return A new modal + */ static @NotNull Modal of(@NotNull ItemProvider provider, Dimensions dimensions, Consumer initializer) { return new ModalImpl(provider, "A Flare Modal", initializer, dimensions, false); } + /** + * Constructs a new modal builder + * @param provider Item provider for this modal + * @return A new modal builder + */ static @NotNull Builder builder(@NotNull ItemProvider provider) { return new ModalImpl.Builder(provider); } + /** + * Returns the frame of this modal + * @return The frame of this modal + */ ModalFrame getFrame(); + /** + * A builder for modals + */ interface Builder extends ComposableLike { + /** + * Sets the title of the modal frame + * @param title The title of the modal frame + * @return This builder + */ @NotNull Builder title(@NotNull String title); + /** + * Sets the dimensions of the modal frame + * @param dimensions Dimensions of the modal frame + * @return This builder + */ @NotNull Builder dimensions(@NotNull Dimensions dimensions); + /** + * Sets the modal frame initializer + * @param initializer The initializer for the modal frame + * @return This builder + */ @NotNull Builder initializer(@NotNull Consumer initializer); + /** + * Disables the modal button + * @param disabled Disabled state + * @return This builder + */ @NotNull Builder disabled(boolean disabled); + /** + * Builds this modal + * @return Built modal + */ @NotNull Modal build(); @Override @@ -45,11 +96,18 @@ default Composable asComposable() { } } + /** + * The modal frame + */ @EqualsAndHashCode(callSuper = true) @ToString abstract class ModalFrame extends PageFrame { + @ApiStatus.Internal @Getter protected final AtomicBoolean isClosing = new AtomicBoolean(false); + /** + * The parent modal used + */ @Getter protected Modal parent; @@ -64,6 +122,7 @@ public void close() { } } + @ApiStatus.Internal record ModalProps(Modal self, Dimensions dimensions, String title, Consumer initializer) { } diff --git a/flare/core/src/main/java/space/maxus/flare/ui/compose/complex/Modals.java b/flare/core/src/main/java/space/maxus/flare/ui/compose/complex/Modals.java index 552a9b8..4a519b0 100644 --- a/flare/core/src/main/java/space/maxus/flare/ui/compose/complex/Modals.java +++ b/flare/core/src/main/java/space/maxus/flare/ui/compose/complex/Modals.java @@ -12,27 +12,58 @@ import space.maxus.flare.ui.compose.Placeholder; import space.maxus.flare.ui.space.Slot; +/** + * Contains certain utility modals + */ @UtilityClass public class Modals { + /** + * A Yes/No modal + */ @Builder public static final class YesNoModal implements ComposableLike { + /** + * The name of the modal + */ @Builder.Default private final String name = "Modal"; + /** + * The description of the modal button + */ @Builder.Default private final String description = "Opens a modal"; + /** + * The name of the decline button + */ @Builder.Default private final String declineName = "Decline"; + /** + * The name of the accept button + */ @Builder.Default private final String acceptName = "Accept"; + /** + * Handler for when the accept button is clicked + */ @Builder.Default private final Runnable onAccept = () -> { }; + /** + * Handler for when the decline button + */ @Builder.Default private final Runnable onDecline = () -> { }; + /** + * Extra information in the modal + */ @Builder.Default private final @Nullable String extraInformation = null; + /** + * Converts this modal into a modal builder + * @return The modal builder + */ @SuppressWarnings("ConstantValue") public Modal.@NotNull Builder asBuilder() { return yesOrNoModalBuilder( diff --git a/flare/core/src/main/java/space/maxus/flare/ui/compose/complex/PaginationDisplay.java b/flare/core/src/main/java/space/maxus/flare/ui/compose/complex/PaginationDisplay.java index c5c5baa..eae2384 100644 --- a/flare/core/src/main/java/space/maxus/flare/ui/compose/complex/PaginationDisplay.java +++ b/flare/core/src/main/java/space/maxus/flare/ui/compose/complex/PaginationDisplay.java @@ -17,7 +17,17 @@ import space.maxus.flare.ui.page.Pagination; import space.maxus.flare.util.SafeComputable; +/** + * Pagination display is used to display pagination state. + *
+ * See more in Flare docs: PaginationDisplay + */ public interface PaginationDisplay extends Composable, Configurable { + /** + * Returns the item builder for arrow forward button + * @param disabled Whether the button is disabled + * @return Item builder + */ static @NotNull ItemStackBuilder arrowForwardButton(boolean disabled) { return Items.builder(Material.PLAYER_HEAD) .hideAllFlags() @@ -34,6 +44,11 @@ public interface PaginationDisplay extends Composable, Configurable pagination) { return new PaginationDisplayImpl(pagination, 0, null, null, null, null); } + /** + * Creates a new pagination display + * @param pagination The pagination used + * @param idx Currently selected page index + * @return New pagination display + */ static @NotNull PaginationDisplay of(Pagination pagination, int idx) { return new PaginationDisplayImpl(pagination, 0, null, null, null, null); } + /** + * Creates a new pagination builder + * @param pagination The pagination to use + * @return A new pagination builder + */ static @NotNull Builder builder(Pagination pagination) { return new PaginationDisplayImpl.Builder(pagination); } + /** + * Gets the current pagination + * @return The currently used pagination + */ Pagination getPagination(); + /** + * Returns the reactive state of the selected page index + * @return The reactive state of the selected page index + */ ReactiveState selectedIndex(); + /** + * Returns the reactive state of the selected page frame + * @return The reactive state of the selected page frame + */ ReactiveState selectedFrame(); + /** + * Switches to another page index + * @param page Page index to switch to + */ default void switchPage(int page) { getPagination().switchPage(viewer(), page); } + /** + * A pagination display builder + */ interface Builder extends ComposableLike { + /** + * Sets the currently selected page index + * @param index Index to be set + * @return This builder + */ @NotNull Builder selectedIndex(int index); + /** + * Sets the back button item provider + * @param back The provider to use + * @return This builder + */ @NotNull Builder backButton(@Nullable ItemProvider back); + /** + * Sets the forward button item provider + * @param forward The provider to use + * @return This builder + */ @NotNull Builder forwardButton(@Nullable ItemProvider forward); + /** + * Sets the selected page item builder + * @param page The provider to be set + * @return This builder + */ @NotNull Builder selectedPage(@Nullable SafeComputable, ItemStack> page); + /** + * Sets the unselected page item builder + * @param page The provider to be set + * @return This builder + */ @NotNull Builder unselectedPage(@Nullable SafeComputable, ItemStack> page); + /** + * Builds this pagination display + * @return Built pagination display + */ @NotNull PaginationDisplay build(); @Override diff --git a/flare/core/src/main/java/space/maxus/flare/ui/compose/complex/Tabulation.java b/flare/core/src/main/java/space/maxus/flare/ui/compose/complex/Tabulation.java index b7909d7..8f91953 100644 --- a/flare/core/src/main/java/space/maxus/flare/ui/compose/complex/Tabulation.java +++ b/flare/core/src/main/java/space/maxus/flare/ui/compose/complex/Tabulation.java @@ -14,7 +14,18 @@ import space.maxus.flare.ui.compose.Configurable; import space.maxus.flare.ui.page.Pagination; +/** + * Tabulation is used to display pagination state. + *
+ * See more in Flare docs: Tabulation + */ public interface Tabulation extends Composable, Configurable { + /** + * Returns the unselected item builder + * @param idx The page index + * @param frame The page frame + * @return Unselected item builder + */ static ItemStackBuilder unselectedItemBuilder(int idx, Frame frame) { return Items.builder(Material.PLAYER_HEAD) .headSkin("eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvYzNlNGI1MzNlNGJhMmRmZjdjMGZhOTBmNjdlOGJlZjM2NDI4YjZjYjA2YzQ1MjYyNjMxYjBiMjVkYjg1YiJ9fX0=") @@ -24,6 +35,12 @@ static ItemStackBuilder unselectedItemBuilder(int idx, Frame frame) { .hideAllFlags(); } + /** + * Returns the selected item builder + * @param idx The page index + * @param frame The page frame + * @return Selected item builder + */ static ItemStackBuilder selectedItemBuilder(int idx, Frame frame) { return Items.builder(Material.PLAYER_HEAD) .headSkin("eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvNWZmMzE0MzFkNjQ1ODdmZjZlZjk4YzA2NzU4MTA2ODFmOGMxM2JmOTZmNTFkOWNiMDdlZDc4NTJiMmZmZDEifX19") @@ -32,14 +49,33 @@ static ItemStackBuilder selectedItemBuilder(int idx, Frame frame) { .hideAllFlags(); } + /** + * Constructs a new tabulation + * @param pagination The pagination to use + * @return Constructed tabulation + */ static @NotNull Tabulation of(Pagination pagination) { return new TabulationImpl(pagination, null, null, 0); } + /** + * Constructs a new tabulation + * @param pagination The pagination to use + * @param idx Currently selected page index + * @return Constructed tabulation + */ static @NotNull Tabulation of(Pagination pagination, int idx) { return new TabulationImpl(pagination, null, null, idx); } + /** + * Constructs a new tabulation + * @param pagination The pagination to use + * @param selected Builder for selected page button + * @param unselected Builder for unselected page button + * @param idx Currently selected page index + * @return Constructed tabulation + */ static @NotNull Tabulation of( Pagination pagination, @Nullable Computable, ItemStack> selected, @@ -49,12 +85,28 @@ static ItemStackBuilder selectedItemBuilder(int idx, Frame frame) { return new TabulationImpl(pagination, selected, unselected, idx); } + /** + * Returns bound pagination + * @return Bound pagination + */ Pagination getPagination(); + /** + * Returns selected page index state + * @return Selected page index state + */ ReactiveState selectedIndex(); + /** + * Returns selected page frame state + * @return Selected page frame state + */ ReactiveState selectedFrame(); + /** + * Switches current page to the given page + * @param page Page index to switch to + */ default void switchPage(int page) { getPagination().switchPage(viewer(), page); }