update readme

README.md

@@ -43,7 +43,7 @@ try {
 scoreboardLibrary.close();
 ```
 
-### Sidebar
+### Sidebar (low-level)
 
 
 ```java
@@ -62,68 +62,156 @@ sidebar.addPlayer(player); // Add the player to the sidebar
 sidebar.close();
 ```
 
-### Sidebar (Kotlin)
+### Component sidebars
 
-```kotlin
-val sidebar = scoreboardLibrary.createSidebar(4)
+You can use `SidebarComponent`s to declaratively design sidebars. Here's how you create a `SidebarComponent` with a static line:
+```java
+SidebarComponent staticLine = SidebarComponent.staticLine(Component.text("A static line"));
+```
+You can chain nultiple `SidebarComponent`s together using `SidebarComponent.builder()`:
+```java
+SidebarComponent lines = SidebarComponent.builder()
+  .addComponent(SidebarComponent.staticLine(Component.text("A static line")))
+  .addStaticLine(Component.text("Another static line")) // Shorthand for line above
+  .build();
+```
+To use these components, create a `ComponentSidebarLayout`:
+```java
+ComponentSidebarLayout layout = new ComponentSidebarLayout(
+  SidebarComponent.staticLine(Component.text("Sidebar Title")),
+  lines
+);
 
-val timerLine: LinesBuilder.DynamicLine
-var timer = 0
+Sidebar sidebar = scoreboardLibrary.createSidebar();
 
-sidebar.title(Component.text("Timer Example", NamedTextColor.AQUA))
-sidebar.lines {
-  emptyLine()
-  timerLine = dynamicLine { Component.text("Timer: $timer") }
-  emptyLine()
-  line(Component.text("epicserver.net", NamedTextColor.AQUA))
+// Apply the title & lines components to the Sidebar
+// Do this every time the title or any line needs to be updated
+layout.apply(sidebar);
+```
+You can make animations with `SidebarAnimation`:
+```java
+Component lineComponent = Component.text("Line that changes colors");
+Set<NamedTextColor> colors = NamedTextColor.NAMES.values();
+List<Component> frames = new ArrayList<>(colors.size());
+for (NamedTextColor color : colors) {
+  frames.add(lineComponent.color(color));
 }
 
-plugin.server.scheduler.runTaskTimerAsynchronously(
-  plugin,
-  Runnable {
-    timer++
-    timerLine.update()
-  },
-  20,
-  20
-)
+SidebarAnimation<Component> animation = new CollectionSidebarAnimation<>(frames);
+// You can also implement SidebarAnimation yourself
 
-sidebar.addPlayer(player)
+SidebarComponent line = SidebarComponent.animatedLine(animation);
+
+// Advance to the next frame of the animation
+animation.nextFrame();
 ```
-
-### AbstractSidebar
-
+Animations can be used for pagination:
 ```java
-public class TimerSidebar extends AbstractSidebar {
-  private final DynamicLine timerLine;
-  private int timer;
+Player player = ...;
 
-  private final BukkitTask task;
+SidebarComponent firstPage = SidebarComponent.builder()
+  .addStaticLine(Component.text("First page"))
+  .addDynamicLine(() -> Component.text("Level: " + player.getLevel()))
+  .build();
 
-  public TimerSidebar(@NotNull Plugin plugin, @NotNull ScoreboardLibrary scoreboardLibrary, @NotNull Player player) {
-    super(scoreboardLibrary.createSidebar(4));
+SidebarComponent secondPage = SidebarComponent.builder()
+  .addStaticLine(Component.text("Second page"))
+  .addDynamicLine(() -> Component.text("Health: " + player.getHealth()))
+  .build();
 
-    sidebar.title(text("Timer Example", NamedTextColor.AQUA));
+List<SidebarComponent> pages = List.of(firstPage, secondPage);
+SidebarAnimation<SidebarComponent> pageAnimation = new CollectionSidebarAnimation<>(pages);
+SidebarComponent paginatedComponent = SidebarComponent.animatedComponent(pageAnimation);
 
-    registerEmptyLine(0);
-    timerLine = registerDynamicLine(1, () -> text("Timer: " + timer));
-    registerEmptyLine(2);
-    registerStaticLine(3, text("epicserver.net", NamedTextColor.AQUA));
+// ...
+```
+You can also create your own `SidebarComponent`s:
+```java
+public class KeyValueSidebarComponent implements SidebarComponent {
+  private final Component key;
+  private final Supplier<Component> valueSupplier;
 
-    task = plugin.getServer().getScheduler().runTaskTimerAsynchronously(plugin, () -> {
-      timer++;
-      timerLine.update();
-    }, 20, 20);
-
-    sidebar.addPlayer(player);
+  public KeyValueSidebarComponent(@NotNull Component key, @NotNull Supplier<Component> valueSupplier) {
+    this.key = key;
+    this.valueSupplier = valueSupplier;
   }
 
   @Override
-  protected void onClosed() {
-    task.cancel();
+  public void draw(@NotNull LineDrawable drawable) {
+    var value = valueSupplier.get();
+    var line = text()
+      .append(key)
+      .append(text(": "))
+      .append(value.colorIfAbsent(AQUA))
+      .build();
+
+    drawable.drawLine(line);
   }
 }
 ```
+Here's a full sidebar example:
+```java
+public class ExampleComponentSidebar {
+  private final Sidebar sidebar;
+  private final ComponentSidebarLayout componentSidebar;
+  private final SidebarAnimation<Component> titleAnimation;
+
+  public ExampleComponentSidebar(@NotNull Plugin plugin, @NotNull Sidebar sidebar) {
+    this.sidebar = sidebar;
+
+    this.titleAnimation = createGradientAnimation(text("Sidebar Example", style(BOLD)));
+    var title = SidebarComponent.animatedLine(titleAnimation);
+
+    SimpleDateFormat dtf = new SimpleDateFormat("HH:mm:ss");
+
+    // Custom SidebarComponent, see below for how an implementation might look like
+    SidebarComponent onlinePlayers = new KeyValueSidebarComponent(
+      text("Online players"),
+      () -> text(plugin.getServer().getOnlinePlayers().size())
+    );
+
+    SidebarComponent lines = SidebarComponent.builder()
+      .addDynamicLine(() -> {
+        var time = dtf.format(new Date());
+        return text(time, NamedTextColor.GRAY);
+      })
+      .addBlankLine()
+      .addStaticLine(text("A static line"))
+      .addComponent(onlinePlayers)
+      .addBlankLine()
+      .addStaticLine(text("epicserver.net", AQUA))
+      .build();
+
+
+    this.componentSidebar = new ComponentSidebarLayout(title, lines);
+  }
+
+  // Called every tick
+  public void tick() {
+    // Advance title animation to the next frame
+    titleAnimation.nextFrame();
+
+    // Update sidebar title & lines
+    componentSidebar.apply(sidebar);
+  }
+
+  private @NotNull SidebarAnimation<Component> createGradientAnimation(@NotNull Component text) {
+    float step = 1f / 8f;
+
+    TagResolver.Single textPlaceholder = Placeholder.component("text", text);
+    ArrayList<Component> frames = new ArrayList<Component>((int) (2f / step));
+
+    float phase = -1f;
+    while (phase < 1) {
+      frames.add(miniMessage().deserialize("<gradient:yellow:gold:" + phase + "><text>", textPlaceholder));
+      phase += step;
+    }
+
+    return new CollectionSidebarAnimation<>(frames);
+  }
+}
+```
+![Sidebar example](./assets/sidebar.gif)`
 
 ### TeamManager