Fix narration element indices and more JD tricks

8 files changed, 48 insertions, 2 deletions

diff --git a/build.gradle b/build.gradle
index b0c39a2..4e6d927 100644
--- a/build.gradle
+++ b/build.gradle
@@ -92,6 +92,7 @@ javadoc {
 
 	options {
 		links("https://maven.fabricmc.net/docs/yarn-$project.yarn_mappings")
+		taglets 'io.github.cottonmc.cotton.gui.jd.ExperimentalTaglet'
 		taglets 'io.github.cottonmc.cotton.gui.jd.PropertyTaglet'
 		tagletPath project(':javadoc').tasks.jar.outputs.files.singleFile
 	}
diff --git a/javadoc/src/main/java/io/github/cottonmc/cotton/gui/jd/ExperimentalTaglet.java b/javadoc/src/main/java/io/github/cottonmc/cotton/gui/jd/ExperimentalTaglet.java
new file mode 100644
index 0000000..dbd2391
--- /dev/null
+++ b/javadoc/src/main/java/io/github/cottonmc/cotton/gui/jd/ExperimentalTaglet.java
@@ -0,0 +1,30 @@
+package io.github.cottonmc.cotton.gui.jd;
+
+import com.sun.source.doctree.DocTree;
+import jdk.javadoc.doclet.Taglet;
+
+import java.util.List;
+import java.util.Set;
+import javax.lang.model.element.Element;
+
+public class ExperimentalTaglet implements Taglet {
+	@Override
+	public Set<Location> getAllowedLocations() {
+		return Set.of(Location.values());
+	}
+
+	@Override
+	public boolean isInlineTag() {
+		return false;
+	}
+
+	@Override
+	public String getName() {
+		return "experimental";
+	}
+
+	@Override
+	public String toString(List<? extends DocTree> tags, Element element) {
+		return "<dt>Experimental API:</dt><dd>Might be modified or removed without prior notice until stabilised.</dd>";
+	}
+}
diff --git a/src/main/java/io/github/cottonmc/cotton/gui/impl/client/NarrationHelper.java b/src/main/java/io/github/cottonmc/cotton/gui/impl/client/NarrationHelper.java
index 55095a3..54567be 100644
--- a/src/main/java/io/github/cottonmc/cotton/gui/impl/client/NarrationHelper.java
+++ b/src/main/java/io/github/cottonmc/cotton/gui/impl/client/NarrationHelper.java
@@ -18,11 +18,11 @@ public final class NarrationHelper {
 	public static void addNarrations(WPanel rootPanel, NarrationMessageBuilder builder) {
 		List<WWidget> narratableWidgets = getAllWidgets(rootPanel)
 			.filter(WWidget::isNarratable)
-			.filter(widget -> widget.isFocused() || widget.isHovered())
 			.collect(Collectors.toList());
 
 		for (int i = 0, childCount = narratableWidgets.size(); i < childCount; i++) {
 			WWidget child = narratableWidgets.get(i);
+			if (!child.isFocused() && !child.isHovered()) continue;
 
 			// replicates Screen.addElementNarrations
 			if (narratableWidgets.size() > 1) {
diff --git a/src/main/java/io/github/cottonmc/cotton/gui/widget/WPanel.java b/src/main/java/io/github/cottonmc/cotton/gui/widget/WPanel.java
index 3358d0a..204ea93 100644
--- a/src/main/java/io/github/cottonmc/cotton/gui/widget/WPanel.java
+++ b/src/main/java/io/github/cottonmc/cotton/gui/widget/WPanel.java
@@ -251,6 +251,7 @@ public abstract class WPanel extends WWidget {
 	/**
 	 * {@return a stream of all visible widgets in this panel}
 	 *
+	 * @experimental
 	 * @since 4.2.0
 	 */
 	@ApiStatus.Experimental
diff --git a/src/main/java/io/github/cottonmc/cotton/gui/widget/WTabPanel.java b/src/main/java/io/github/cottonmc/cotton/gui/widget/WTabPanel.java
index 88c0db5..718e44b 100644
--- a/src/main/java/io/github/cottonmc/cotton/gui/widget/WTabPanel.java
+++ b/src/main/java/io/github/cottonmc/cotton/gui/widget/WTabPanel.java
@@ -367,7 +367,7 @@ public class WTabPanel extends WPanel {
 		@Environment(EnvType.CLIENT)
 		@Override
 		public void addNarrations(NarrationMessageBuilder builder) {
-			Text label = data.getTitle(); // TODO: a separate narration message
+			Text label = data.getTitle();
 
 			if (label != null) {
 				builder.put(NarrationPart.TITLE, new TranslatableText(NarrationMessages.TAB_TITLE_KEY, label));
diff --git a/src/main/java/io/github/cottonmc/cotton/gui/widget/WWidget.java b/src/main/java/io/github/cottonmc/cotton/gui/widget/WWidget.java
index b300d43..27e62f8 100644
--- a/src/main/java/io/github/cottonmc/cotton/gui/widget/WWidget.java
+++ b/src/main/java/io/github/cottonmc/cotton/gui/widget/WWidget.java
@@ -11,6 +11,7 @@ import io.github.cottonmc.cotton.gui.GuiDescription;
 import io.github.cottonmc.cotton.gui.impl.VisualLogger;
 import io.github.cottonmc.cotton.gui.widget.data.InputResult;
 import io.github.cottonmc.cotton.gui.widget.data.ObservableProperty;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.Nullable;
 import org.lwjgl.glfw.GLFW;
 
@@ -466,9 +467,11 @@ public class WWidget {
 	 * Returns whether the user is hovering over this widget.
 	 * The result is an <i>observable property</i> that can be modified and listened to.
 	 *
+	 * @experimental
 	 * @return the {@code hovered} property
 	 * @since 4.2.0
 	 */
+	@ApiStatus.Experimental
 	public ObservableProperty<Boolean> hoveredProperty() {
 		return hovered;
 	}
@@ -477,9 +480,11 @@ public class WWidget {
 	 * Returns whether the user is hovering over this widget.
 	 * This is equivalent to calling <code>{@link #hoveredProperty()}.get()</code>.
 	 *
+	 * @experimental
 	 * @return true if this widget is hovered, false otherwise
 	 * @since 4.2.0
 	 */
+	@ApiStatus.Experimental
 	public final boolean isHovered() {
 		return hoveredProperty().get();
 	}
@@ -487,9 +492,11 @@ public class WWidget {
 	/**
 	 * Sets the {@link #hoveredProperty() hovered} property.
 	 *
+	 * @experimental
 	 * @param hovered the new value; true if hovered, false otherwise
 	 * @since 4.2.0
 	 */
+	@ApiStatus.Experimental
 	public final void setHovered(boolean hovered) {
 		hoveredProperty().set(hovered);
 	}
diff --git a/src/main/java/io/github/cottonmc/cotton/gui/widget/data/ObservableProperty.java b/src/main/java/io/github/cottonmc/cotton/gui/widget/data/ObservableProperty.java
index 39a078b..3bd24ef 100644
--- a/src/main/java/io/github/cottonmc/cotton/gui/widget/data/ObservableProperty.java
+++ b/src/main/java/io/github/cottonmc/cotton/gui/widget/data/ObservableProperty.java
@@ -1,5 +1,7 @@
 package io.github.cottonmc.cotton.gui.widget.data;
 
+import org.jetbrains.annotations.ApiStatus;
+
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Objects;
@@ -13,9 +15,11 @@ import java.util.function.Supplier;
  * {@code <property name>Property}. For example, the {@code WWidget.hovered} property can be retrieved with
  * {@link io.github.cottonmc.cotton.gui.widget.WWidget#hoveredProperty() hoveredProperty()}.
  *
+ * @experimental
  * @param <T> the contained value type
  * @since 4.2.0
  */
+@ApiStatus.Experimental
 public final class ObservableProperty<T> implements ObservableView<T> {
 	private Supplier<? extends T> value;
 	private final List<ChangeListener<? super T>> listeners = new ArrayList<>();
diff --git a/src/main/java/io/github/cottonmc/cotton/gui/widget/data/ObservableView.java b/src/main/java/io/github/cottonmc/cotton/gui/widget/data/ObservableView.java
index c670c07..8439e80 100644
--- a/src/main/java/io/github/cottonmc/cotton/gui/widget/data/ObservableView.java
+++ b/src/main/java/io/github/cottonmc/cotton/gui/widget/data/ObservableView.java
@@ -1,5 +1,6 @@
 package io.github.cottonmc.cotton.gui.widget.data;
 
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.Nullable;
 
 import java.util.function.Supplier;
@@ -7,9 +8,11 @@ import java.util.function.Supplier;
 /**
  * A read-only {@linkplain ObservableProperty observable property}.
  *
+ * @experimental
  * @param <T> the contained value type
  * @since 4.2.0
  */
+@ApiStatus.Experimental
 public interface ObservableView<T> extends Supplier<T> {
 	/**
 	 * Adds a change listener to this property view.