Documentation

CHANGELOG.md

@@ -6,7 +6,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
-### CHanged
+### Changed
 
 - Refactor builder classes for simple (empty) and container-like HTML and SVG elements
 
@@ -22,7 +22,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [1.1.0] - 2023-08-23
 
-Please don't use this release.
+Not an official release - please don't use!
 
 ## [1.0.15] - 2023-08-20
 
@@ -40,7 +40,7 @@ Please don't use this release.
 
 ## [1.0.14] - 2023-08-20
 
-Please don't use this release. 
+Not an official release - please don't use!
 
 ## [1.0.13] - 2023-08-03
 

src/demo/java/ElementsBagDemo.java

@@ -10,7 +10,7 @@
 import static org.jboss.elemento.Elements.dl;
 import static org.jboss.elemento.Elements.dt;
 
-@SuppressWarnings({"MismatchedQueryAndUpdateOfCollection", "RedundantOperationOnEmptyContainer", "unused"})
+@SuppressWarnings({"RedundantOperationOnEmptyContainer", "MismatchedQueryAndUpdateOfCollection"})
 public class ElementsBagDemo {
 
     public void bagDemo() {

src/demo/java/ElementsDemo.java

@@ -79,7 +79,7 @@ public void findAllDemo() {
 
     public void streamDemo() {
         // @start region = stream
-        HTMLElement parent = find(document.body, By.data("foo", "bar"));
+        HTMLElement parent = find(body(), By.data("foo", "bar"));
         if (parent != null) {
             List<HTMLElement> htmlElements = stream(parent)
                     .filter(htmlElements())

src/demo/java/HtmlContainerDemo.java → src/demo/java/HasChildrenDemo.java

@@ -3,7 +3,7 @@
 import static org.jboss.elemento.Elements.ul;
 
 @SuppressWarnings("unused")
-public class HtmlContainerDemo {
+public class HasChildrenDemo {
 
     public void addAllDemo() {
         // @start region = addAll

src/demo/java/SvgDemo.java

@@ -0,0 +1,24 @@
+import org.jboss.elemento.By;
+
+import static org.jboss.elemento.By.AttributeOperator.STARTS_WITH;
+import static org.jboss.elemento.Elements.circle;
+import static org.jboss.elemento.Elements.g;
+import static org.jboss.elemento.Elements.svg;
+
+@SuppressWarnings("unused")
+public class SvgDemo {
+
+    public void svgDemo() {
+        // @start region = svg
+        svg().css("spinner", "large")
+                .aria("label", "Loading...")
+                .attr("role", "progressbar")
+                .attr("viewBox", "0 0 100 100")
+                .add(circle().css("spinner", "path")
+                        .attr("cx", 50)
+                        .attr("cy", 50)
+                        .attr("r", 45)
+                        .attr("fill", "none"));
+        // @end region = svg
+    }
+}

src/demo/java/TodoElement.java

@@ -33,7 +33,7 @@ public class TodoElement implements IsElement<HTMLElement>, Attachable {
     private HandlerRegistration handlerRegistration;
 
     TodoElement(Todo todo) {
-        this.root = li().data("item", todo.id)
+        root = li().data("item", todo.id)
                 .add(div().css("view")
                         .add(toggle = input(checkbox).css("toggle")
                                 .checked(todo.completed)
@@ -42,9 +42,9 @@ public class TodoElement implements IsElement<HTMLElement>, Attachable {
                         .add(destroy = button().css("destroy").element()))
                 .add(summary = input(text).css("edit").element())
                 .element();
-        this.root.classList.toggle("completed", todo.completed);
-        this.toggle.checked = todo.completed;
-        Attachable.register(this, this);
+        root.classList.toggle("completed", todo.completed);
+        toggle.checked = todo.completed;
+        Attachable.register(root, this);
     }
 
     @Override

src/main/java/org/jboss/elemento/ElementsBag.java

@@ -22,7 +22,7 @@
 import elemental2.dom.HTMLElement;
 
 /**
- * Class to collect {@link HTMLElement}s
+ * Class to collect {@link Element}s
  * <p>
  * {@snippet class = ElementsBagDemo region = bag}
  */
@@ -39,13 +39,13 @@ public ElementsBag that() {
         return this;
     }
 
-    // ------------------------------------------------------ mirror add() methods from HtmlContent
-
     /** @return the elements in this bag. */
     public Iterable<Element> elements() {
         return iterable;
     }
 
+    // ------------------------------------------------------ mirror add() methods from HasChildren
+
     /** Adds the given element. */
     public ElementsBag add(Element element) {
         iterable.elements.push(element);
@@ -60,6 +60,14 @@ public ElementsBag add(IsElement<?> element) {
         return that();
     }
 
+    /** Adds all elements. */
+    public ElementsBag addAll(Element... elements) {
+        for (Element element : elements) {
+            add(element);
+        }
+        return that();
+    }
+
     /** Adds all elements. */
     public ElementsBag addAll(HTMLElement... elements) {
         for (HTMLElement element : elements) {

src/main/java/org/jboss/elemento/HasChildren.java

@@ -19,7 +19,11 @@
 import elemental2.dom.HTMLElement;
 import elemental2.dom.Node;
 
-/** Interface for elements with children */
+/**
+ * Interface for elements with children
+ <p>
+ * {@snippet class = HasChildrenDemo region = addAll}
+ */
 public interface HasChildren<E extends Element, B extends TypedBuilder<E, B>> extends TypedBuilder<E, B>, IsElement<E> {
 
     /** Adds the given node. */

src/main/java/org/jboss/elemento/svg/SVGCircleElement.java

@@ -18,6 +18,12 @@
 import jsinterop.annotations.JsPackage;
 import jsinterop.annotations.JsType;
 
+/**
+ * The SVGCircleElement interface is an interface for the {@code <circle>} element.
+ *
+ * @see <a
+ * href="https://developer.mozilla.org/en-US/docs/Web/API/SVGCircleElement">https://developer.mozilla.org/en-US/docs/Web/API/SVGCircleElement</a>
+ */
 @JsType(isNative = true, namespace = JsPackage.GLOBAL)
 public class SVGCircleElement extends SVGElement {
 }

src/main/java/org/jboss/elemento/svg/SVGElement.java

@@ -22,6 +22,11 @@
 import jsinterop.annotations.JsType;
 import jsinterop.base.JsPropertyMap;
 
+/**
+ * All of the SVG DOM interfaces that correspond directly to elements in the SVG language derive from the SVGElement interface.
+ *
+ * @see <a href="https://developer.mozilla.org/en-US/docs/Web/API/SVGElement">https://developer.mozilla.org/en-US/docs/Web/API/SVGElement</a>
+ */
 @JsType(isNative = true, namespace = JsPackage.GLOBAL)
 public class SVGElement extends Element {
 

src/main/java/org/jboss/elemento/svg/SVGEllipseElement.java

@@ -18,6 +18,12 @@
 import jsinterop.annotations.JsPackage;
 import jsinterop.annotations.JsType;
 
+/**
+ * The SVGEllipseElement interface provides access to the properties of {@code <ellipse>} elements.
+ *
+ * @see <a
+ * href="https://developer.mozilla.org/en-US/docs/Web/API/SVGEllipseElement">https://developer.mozilla.org/en-US/docs/Web/API/SVGEllipseElement</a>
+ */
 @JsType(isNative = true, namespace = JsPackage.GLOBAL)
 public class SVGEllipseElement extends SVGElement {
 }

src/main/java/org/jboss/elemento/svg/SVGGElement.java

@@ -18,6 +18,12 @@
 import jsinterop.annotations.JsPackage;
 import jsinterop.annotations.JsType;
 
+/**
+ * The SVGGElement interface corresponds to the {@code <g>} element.
+ *
+ * @see <a
+ * href="https://developer.mozilla.org/en-US/docs/Web/API/SVGGElement">https://developer.mozilla.org/en-US/docs/Web/API/SVGGElement</a>
+ */
 @JsType(isNative = true, namespace = JsPackage.GLOBAL)
 public class SVGGElement extends SVGElement {
 }

src/main/java/org/jboss/elemento/svg/SVGLineElement.java

@@ -18,6 +18,13 @@
 import jsinterop.annotations.JsPackage;
 import jsinterop.annotations.JsType;
 
+/**
+ * The SVGLineElement interface provides access to the properties of {@code <line>} elements, as well as methods to
+ * manipulate them.
+ *
+ * @see <a
+ * href="https://developer.mozilla.org/en-US/docs/Web/API/SVGLineElement">https://developer.mozilla.org/en-US/docs/Web/API/SVGLineElement</a>
+ */
 @JsType(isNative = true, namespace = JsPackage.GLOBAL)
 public class SVGLineElement extends SVGElement {
 }

src/main/java/org/jboss/elemento/svg/SVGPathElement.java

@@ -18,6 +18,12 @@
 import jsinterop.annotations.JsPackage;
 import jsinterop.annotations.JsType;
 
+/**
+ * The SVGPathElement interface corresponds to the {@code <path>} element.
+ *
+ * @see <a
+ * href="https://developer.mozilla.org/en-US/docs/Web/API/SVGPathElement">https://developer.mozilla.org/en-US/docs/Web/API/SVGPathElement</a>
+ */
 @JsType(isNative = true, namespace = JsPackage.GLOBAL)
 public class SVGPathElement extends SVGElement {
 }

src/main/java/org/jboss/elemento/svg/SVGPolygonElement.java

@@ -18,6 +18,13 @@
 import jsinterop.annotations.JsPackage;
 import jsinterop.annotations.JsType;
 
+/**
+ * The SVGPolygonElement interface provides access to the properties of {@code <polygon>} elements, as well as methods to
+ * manipulate them.
+ *
+ * @see <a
+ * href="https://developer.mozilla.org/en-US/docs/Web/API/SVGPolygonElement">https://developer.mozilla.org/en-US/docs/Web/API/SVGPolygonElement</a>
+ */
 @JsType(isNative = true, namespace = JsPackage.GLOBAL)
 public class SVGPolygonElement extends SVGElement {
 }

src/main/java/org/jboss/elemento/svg/SVGRectElement.java

@@ -18,6 +18,13 @@
 import jsinterop.annotations.JsPackage;
 import jsinterop.annotations.JsType;
 
+/**
+ * The SVGRectElement interface provides access to the properties of {@code <rect>} elements, as well as methods to
+ * manipulate them.
+ *
+ * @see <a
+ * href="https://developer.mozilla.org/en-US/docs/Web/API/SVGRectElement">https://developer.mozilla.org/en-US/docs/Web/API/SVGRectElement</a>
+ */
 @JsType(isNative = true, namespace = JsPackage.GLOBAL)
 public class SVGRectElement extends SVGElement {
 }

src/main/java/org/jboss/elemento/svg/SVGTextElement.java

@@ -18,6 +18,12 @@
 import jsinterop.annotations.JsPackage;
 import jsinterop.annotations.JsType;
 
+/**
+ * The SVGTextElement interface corresponds to the {@code <text>} elements.
+ *
+ * @see <a
+ * href="https://developer.mozilla.org/en-US/docs/Web/API/SVGTextElement">https://developer.mozilla.org/en-US/docs/Web/API/SVGTextElement</a>
+ */
 @JsType(isNative = true, namespace = JsPackage.GLOBAL)
 public class SVGTextElement extends SVGElement {
 }

src/main/java/org/jboss/elemento/svg/SvgContainerBuilder.java

@@ -18,7 +18,11 @@
 import org.jboss.elemento.ElementBuilder;
 import org.jboss.elemento.HasChildren;
 
-/** Builder for container-like SVG elements. */
+/**
+ * Builder for container-like SVG elements.
+ * <p>
+ * {@snippet class = SvgDemo region = svg}
+ */
 public class SvgContainerBuilder<E extends SVGElement> extends ElementBuilder<E, SvgContainerBuilder<E>>
         implements WithSvgElement<E, SvgContainerBuilder<E>>, HasChildren<E, SvgContainerBuilder<E>> {
 

src/main/java/org/jboss/elemento/svg/SvgElementBuilder.java

@@ -17,7 +17,11 @@
 
 import org.jboss.elemento.ElementBuilder;
 
-/** Builder for simple SVG elements. */
+/**
+ * Builder for simple SVG elements.
+ * <p>
+ * {@snippet class = SvgDemo region = svg}
+ */
 public class SvgElementBuilder<E extends SVGElement> extends ElementBuilder<E, SvgElementBuilder<E>>
         implements WithSvgElement<E, SvgElementBuilder<E>> {
 

src/main/java/org/jboss/elemento/svg/WithSvgElement.java

@@ -18,6 +18,9 @@
 import org.jboss.elemento.IsElement;
 import org.jboss.elemento.TypedBuilder;
 
+/**
+ * Combines common methods for manipulating an SVG element.
+ */
 public interface WithSvgElement<E extends SVGElement, B extends TypedBuilder<E, B>>
         extends TypedBuilder<E, B>, IsElement<E> {
 
@@ -30,8 +33,8 @@ default B style(String style) {
     /**
      * Adds a {@code data-} attribute to the element.
      *
-     * @param name The name of the data attribute w/o the {@code data-} prefix. However, it won't be added if it's already
-     *        present.
+     * @param name The name of the data attribute w/o the {@code data-} prefix. However, it won't be added if it's
+     *             already present.
      */
     default B data(String name, String value) {
         element().dataset.set(name.replaceFirst("^data-", ""), value);