Promote decorationIfAbsent to StyleSetter and Public API

api/src/main/java/net/kyori/adventure/text/AbstractComponentBuilder.java

@@ -243,6 +243,13 @@ private void prepareChildren() {
     return (B) this;
   }
 
+  @Override
+  @SuppressWarnings("unchecked")
+  public @NotNull B decorationIfAbsent(final @NotNull TextDecoration decoration, final TextDecoration.@NotNull State state) {
+    this.styleBuilder().decorationIfAbsent(decoration, state);
+    return (B) this;
+  }
+
   @Override
   @SuppressWarnings("unchecked")
   public @NotNull B clickEvent(final @Nullable ClickEvent event) {

api/src/main/java/net/kyori/adventure/text/Component.java

@@ -1988,6 +1988,26 @@ default boolean hasDecoration(final @NotNull TextDecoration decoration) {
     return this.style(this.style().decoration(decoration, state));
   }
 
+  /**
+   * Sets the state of a decoration on this component to {@code state} if the current state of
+   * the decoration is {@link TextDecoration.State#NOT_SET}.
+   *
+   * @param decoration the decoration
+   * @param state the state
+   * @return a component
+   * @since 4.12.0
+   */
+  @Override
+  default @NotNull Component decorationIfAbsent(final @NotNull TextDecoration decoration, @NotNull final TextDecoration.State state) {
+    requireNonNull(state, "state");
+    // Not delegating this method prevents object creation if decoration is NOT absent
+    final TextDecoration.@NotNull State oldState = this.decoration(decoration);
+    if (oldState == TextDecoration.State.NOT_SET) {
+      return this.style(this.style().decoration(decoration, state));
+    }
+    return this;
+  }
+
   /**
    * Gets a set of decorations this component has.
    *

api/src/main/java/net/kyori/adventure/text/ComponentBuilder.java

@@ -308,6 +308,19 @@ public interface ComponentBuilder<C extends BuildableComponent<C, B>, B extends
   @Override
   @NotNull B decoration(final @NotNull TextDecoration decoration, final TextDecoration.@NotNull State state);
 
+  /**
+   * Sets the state of a decoration on this component to {@code state} if the current state of
+   * the decoration is {@link TextDecoration.State#NOT_SET}.
+   *
+   * @param decoration the decoration
+   * @param state the state
+   * @return this builder
+   * @since 4.12.0
+   */
+  @Contract("_, _ -> this")
+  @Override
+  @NotNull B decorationIfAbsent(final @NotNull TextDecoration decoration, @NotNull final TextDecoration.State state);
+
   /**
    * Sets the click event of this component.
    *

api/src/main/java/net/kyori/adventure/text/format/Style.java

@@ -341,6 +341,18 @@ default boolean hasDecoration(final @NotNull TextDecoration decoration) {
   @Override
   @NotNull Style decoration(final @NotNull TextDecoration decoration, final TextDecoration.@NotNull State state);
 
+  /**
+   * Sets the state of a decoration on this style to {@code state} if the current state of
+   * the decoration is {@link TextDecoration.State#NOT_SET}.
+   *
+   * @param decoration the decoration
+   * @param state the state
+   * @return a style
+   * @since 4.12.0
+   */
+  @Override
+  @NotNull Style decorationIfAbsent(final @NotNull TextDecoration decoration, @NotNull final TextDecoration.State state);
+
   /**
    * Gets a map of decorations this style has.
    *
@@ -761,6 +773,18 @@ interface Builder extends AbstractBuilder<Style>, Buildable.Builder<Style>, Muta
     @Contract("_, _ -> this")
     @NotNull Builder decoration(final @NotNull TextDecoration decoration, final TextDecoration.@NotNull State state);
 
+    /**
+     * Sets the state of a decoration on this style to {@code state} if the current state of the decoration is {@link TextDecoration.State#NOT_SET}.
+     *
+     * @param decoration the decoration
+     * @param state the state
+     * @return this builder
+     * @since 4.12.0
+     */
+    @Override
+    @Contract("_, _ -> this")
+    @NotNull Builder decorationIfAbsent(final @NotNull TextDecoration decoration, @NotNull final TextDecoration.State state);
+
     /**
      * Sets the click event.
      *

api/src/main/java/net/kyori/adventure/text/format/StyleImpl.java

@@ -112,6 +112,19 @@ final class StyleImpl implements Style {
     return new StyleImpl(this.font, this.color, this.decorations.with(decoration, state), this.clickEvent, this.hoverEvent, this.insertion);
   }
 
+  @Override
+  public @NotNull Style decorationIfAbsent(final @NotNull TextDecoration decoration, final @NotNull TextDecoration.State state) {
+    requireNonNull(state, "state");
+    final TextDecoration.@Nullable State oldState = this.decorations.get(decoration);
+    if (oldState == TextDecoration.State.NOT_SET) {
+      return new StyleImpl(this.font, this.color, this.decorations.with(decoration, state), this.clickEvent, this.hoverEvent, this.insertion);
+    }
+    if (oldState != null) {
+      return this;
+    }
+    throw new IllegalArgumentException(String.format("unknown decoration '%s'", decoration));
+  }
+
   @Override
   public @NotNull Map<TextDecoration, TextDecoration.State> decorations() {
     return this.decorations;
@@ -280,14 +293,14 @@ static final class BuilderImpl implements Builder {
       return this;
     }
 
-    // todo(kashike): promote to public api?
-    @NotNull Builder decorationIfAbsent(final @NotNull TextDecoration decoration, final TextDecoration.@NotNull State state) {
+    @Override
+    public @NotNull Builder decorationIfAbsent(final @NotNull TextDecoration decoration, final TextDecoration.@NotNull State state) {
       requireNonNull(state, "state");
-      final TextDecoration.@Nullable State thisState = this.decorations.get(decoration);
-      if (thisState == TextDecoration.State.NOT_SET) {
+      final TextDecoration.@Nullable State oldState = this.decorations.get(decoration);
+      if (oldState == TextDecoration.State.NOT_SET) {
         this.decorations.put(decoration, state);
       }
-      if (thisState != null) {
+      if (oldState != null) {
         return this;
       }
       throw new IllegalArgumentException(String.format("unknown decoration '%s'", decoration));

api/src/main/java/net/kyori/adventure/text/format/StyleSetter.java

@@ -125,6 +125,16 @@ public interface StyleSetter<T extends StyleSetter<?>> {
    */
   @NotNull T decoration(final @NotNull TextDecoration decoration, final TextDecoration.@NotNull State state);
 
+  /**
+   * Sets the state of a decoration to {@code state} if the current state of the decoration is {@link TextDecoration.State#NOT_SET}.
+   *
+   * @param decoration the decoration
+   * @param state the state
+   * @return an object ({@code T})
+   * @since 4.12.0
+   */
+  @NotNull T decorationIfAbsent(final @NotNull TextDecoration decoration, final TextDecoration.@NotNull State state);
+
   /**
    * Sets decorations using the specified {@code decorations} map.
    *

api/src/test/java/net/kyori/adventure/text/ComponentDecorationTest.java

@@ -0,0 +1,53 @@
+/*
+ * This file is part of adventure, licensed under the MIT License.
+ *
+ * Copyright (c) 2017-2022 KyoriPowered
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package net.kyori.adventure.text;
+
+import com.google.common.collect.ImmutableSet;
+import net.kyori.adventure.text.format.Style;
+import net.kyori.adventure.text.format.TextDecoration;
+import org.junit.jupiter.api.Test;
+
+import static net.kyori.adventure.text.TextAssertions.assertDecorations;
+
+class ComponentDecorationTest {
+
+  @Test
+  void testDecorationIfAbsent() {
+    final Style s0 = Style.style(TextDecoration.BOLD);
+    final Component c0 = Component.text("tuba time", s0)
+      .decorationIfAbsent(TextDecoration.BOLD, TextDecoration.State.FALSE)
+      .decorationIfAbsent(TextDecoration.ITALIC, TextDecoration.State.FALSE);
+    assertDecorations(c0.style(), ImmutableSet.of(TextDecoration.BOLD), ImmutableSet.of(TextDecoration.ITALIC));
+  }
+
+  @Test
+  void testDecorationIfAbsentWithBuilder() {
+    final Style s0 = Style.style(TextDecoration.BOLD);
+    final Component c0 = Component.text().style(s0).content("tuba time")
+      .decorationIfAbsent(TextDecoration.BOLD, TextDecoration.State.FALSE)
+      .decorationIfAbsent(TextDecoration.ITALIC, TextDecoration.State.FALSE)
+      .build();
+    assertDecorations(c0.style(), ImmutableSet.of(TextDecoration.BOLD), ImmutableSet.of(TextDecoration.ITALIC));
+  }
+}

api/src/test/java/net/kyori/adventure/text/format/StyleTest.java

@@ -154,6 +154,23 @@ void testOf_decorations() {
     assertDecorations(s0, ImmutableSet.of(TextDecoration.BOLD, TextDecoration.ITALIC), ImmutableSet.of());
   }
 
+  @Test
+  void testDecorationIfAbsent() {
+    final Style s0 = Style.style(TextDecoration.BOLD)
+      .decorationIfAbsent(TextDecoration.BOLD, TextDecoration.State.FALSE)
+      .decorationIfAbsent(TextDecoration.ITALIC, TextDecoration.State.FALSE);
+    assertDecorations(s0, ImmutableSet.of(TextDecoration.BOLD), ImmutableSet.of(TextDecoration.ITALIC));
+  }
+
+  @Test
+  void testDecorationIfAbsentWithBuilder() {
+    final Style s0 = Style.style().decoration(TextDecoration.BOLD, TextDecoration.State.TRUE)
+      .decorationIfAbsent(TextDecoration.BOLD, TextDecoration.State.FALSE)
+      .decorationIfAbsent(TextDecoration.ITALIC, TextDecoration.State.FALSE)
+      .build();
+    assertDecorations(s0, ImmutableSet.of(TextDecoration.BOLD), ImmutableSet.of(TextDecoration.ITALIC));
+  }
+
   @Test
   void testOf_colorAndDecorations() {
     final Style s0 = Style.style(NamedTextColor.GREEN, TextDecoration.BOLD, TextDecoration.ITALIC);