Add Javadoc

AGENTS.md

@@ -1,40 +1,69 @@
 # Repository Guidelines
 
 ## Project Structure & Module Organization
-- `dramafinder/` — Core Playwright helpers for Vaadin (`src/main/java/...`), resources under `src/main/resources`.
-- `dramafinder-demo/` — Spring Boot Vaadin demo app; integration tests in `src/test/java` with `*IT.java`.
-- `dramafinder-test-reporting/` — Utilities for test reporting/aggregation.
-- Root `pom.xml` — Maven multi-module parent (Java 17).
+
+- Root `pom.xml` — Core Playwright helpers for Vaadin (`src/main/java/...`),
+  resources under `src/main/resources`.
 
 ## Build, Test, and Development Commands
+
 - Build all modules + unit tests: `./mvnw clean install`
-- Run demo locally: `./mvnw -pl dramafinder-demo spring-boot:run` (serves at http://localhost:8080)
-- Run integration tests (Failsafe, includes `**/*IT.java`): `./mvnw -pl dramafinder-demo verify -Pit`
+- Run demo locally: `./mvnw -pl dramafinder-demo spring-boot:run` (serves
+  at http://localhost:8080)
+- Run integration tests (Failsafe, includes `**/*IT.java`):
+  `./mvnw -B verify --file pom.xml`
 - Run a single test:
-  - Unit: `./mvnw -Dtest=MyClassTest test`
-  - IT: `./mvnw -pl dramafinder-demo -Dit.test=MyViewIT -Pit verify`
+    - IT: `./mvnw -Dit.test=MyViewIT -Pit verify`
 
 ## Coding Style & Naming Conventions
-- Java 17; 4-space indent; organize imports; no trailing whitespace.
-- Packages: lowercase (`org.vaadin.dramafinder`); classes: `PascalCase`; methods/fields: `camelCase`; constants: `UPPER_SNAKE_CASE`.
-- Public API in `dramafinder` should be small, cohesive, and documented with Javadoc.
+
+- Java 21; 4-space indent; organize imports; no trailing whitespace.
+- Packages: lowercase (`org.vaadin.dramafinder`); classes: `PascalCase`;
+  methods/fields: `camelCase`; constants: `UPPER_SNAKE_CASE`.
+- Public API in `dramafinder` should be small, cohesive, and documented with
+  Javadoc.
+- Prefer aria role for internal locators
+
+### Javadoc Conventions
+
+- Add a class-level Javadoc for each element class and shared mixin:
+  - Identify the Vaadin tag using inline code (e.g., `vaadin-text-field`).
+  - One–two sentence summary of responsibilities and notable behaviors.
+  - For factory helpers (e.g., `getByLabel`), mention the ARIA role used.
+- For public methods, document parameters, return values, and null semantics
+  (especially for assertion helpers where `null` implies absence).
+- Use `{@inheritDoc}` on simple overrides (e.g., locator accessors) to avoid
+  duplication.
+- Keep Javadoc concise and consistent; prefer present tense and active voice.
 
 ## Testing Guidelines
+
 - Frameworks: JUnit 5, Playwright (Java), Axe-core checks in demo.
-- Unit tests live with their module; integration tests go in `dramafinder-demo/src/test/java/**/*IT.java`.
-- Tests should be deterministic; avoid timing sleeps—prefer Playwright waits and assertions.
+- Unit tests live with their module; integration tests go in
+  `src/test/java/**/*IT.java`.
+- Tests should be deterministic; avoid timing sleeps—prefer Playwright waits and
+  assertions.
 
 ## Commit & Pull Request Guidelines
-- Commits: short, imperative subject; optional scope prefix (e.g., `core:`, `demo:`). Example: `core: add VaadinQuery helper for nested locators`.
-- PRs: describe intent and approach, link issues, list test coverage and manual steps; include screenshots/gifs for UI changes.
-- Keep changes module-scoped; update README/AGENTS.md when commands or workflows change.
+
+- Commits: short, imperative subject; optional scope prefix (e.g., `core:`,
+  `demo:`). Example: `core: add TestFieldElement to test a Vaadin Textfield`.
+- PRs: describe intent and approach, link issues, list test coverage and manual
+  steps; include screenshots/gifs for UI changes.
+- Keep changes module-scoped; update README/AGENTS.md when commands or workflows
+  change.
 
 ## Security & Configuration Tips
-- Requires Java 17. Vaadin demo uses Node tooling; first runs may download frontend and Playwright browser binaries.
-- Do not commit generated/build output: `target/`, `frontend/generated/`, `vite.generated.ts`.
-- Prefer configuration via `application.properties` in each module’s `src/main/resources`.
+
+- Requires Java 21. Vaadin demo uses Node tooling; first runs may download
+  frontend and Playwright browser binaries.
+- Do not commit generated/build output: `target/`, `frontend/generated/`,
+  `vite.generated.ts`.
+- Prefer configuration via `application.properties` in each module’s
+  `src/main/resources`.
 
 ## Agent-Specific Instructions
-- Follow this file’s conventions for any edits. Keep patches minimal and focused.
-- Add unit tests for new public APIs in `dramafinder`; use `*IT.java` only for end-to-end flows in `dramafinder-demo`.
 
+- Follow this file’s conventions for any edits. Keep patches minimal and
+  focused.
+- Use `*IT.java` only for end-to-end tests executed by Failsafe.

GEMINI.md

@@ -0,0 +1,75 @@
+# Drama Finder Project Overview
+
+This document provides an overview of the Drama Finder project, its purpose, and key development aspects relevant for automated agents.
+
+## Project Purpose
+
+Drama Finder is a set of helper classes designed to facilitate testing of Vaadin applications using Playwright. It offers a collection of assertions and actions for Vaadin components, simplifying the creation of robust integration tests.
+
+## Key Technologies
+
+*   **Vaadin:** Frontend framework for web applications.
+*   **Playwright:** A Node.js library to automate Chromium, Firefox and WebKit with a single API. Used here for browser automation and testing.
+*   **Spring Boot:** Used for the test/demo server and integration tests.
+*   **Maven:** Project build automation tool.
+*   **JUnit:** Testing framework.
+*   **Axe-core:** Used for accessibility testing within integration tests.
+
+## Project Structure Highlights
+
+*   `src/main/java/`: Contains the core Java helper classes for Vaadin and Playwright integration.
+*   `src/test/java/`: Contains unit and integration tests for the Drama Finder library itself, as well as demo application tests.
+*   `pom.xml`: Maven project configuration, including dependencies and build profiles.
+
+## Development & Testing
+
+### Starting the Demo Server
+
+To run the demo application (used for testing the Drama Finder library):
+
+```bash
+mvn spring-boot:run
+```
+
+The demo will be available at `http://localhost:8080`.
+
+### Running Unit Tests
+
+```bash
+mvn test
+```
+
+### Running Integration Tests
+
+Integration tests are located in `src/test/java/.../it/` and are run with the `it` Maven profile.
+
+```bash
+mvn -Pit verify
+```
+
+## How to Use Drama Finder
+
+To incorporate Drama Finder into a Vaadin project, add it as a test dependency in your `pom.xml`:
+
+```xml
+<dependency>
+    <groupId>org.vaadin.addons</groupId>
+    <artifactId>dramafinder</artifactId>
+    <version>1.0.0-SNAPSHOT</version>
+    <scope>test</scope>
+</dependency>
+```
+
+Example of an integration test:
+
+```java
+@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
+public class SimpleExampleViewIT extends SpringPlaywrightIT {
+    @Test
+    public void testTooltip() {
+        TextFieldElement textfield = TextFieldElement.getByLabel(page, "Textfield");
+        textfield.assertVisible();
+        textfield.assertTooltipHasText("Tooltip for textfield");
+    }
+}
+```

README.md

@@ -74,6 +74,15 @@ mvn spring-boot:run
 This deploys demo at http://localhost:8080
 The demo is only here to run the test
 
+### Javadoc
+
+Public APIs in the `dramafinder` module are documented with concise Javadoc:
+- Element classes include a short summary referencing the underlying Vaadin
+  tag (e.g., `vaadin-text-field`) and any noteworthy behaviors.
+- Public methods document parameters, return values, and null semantics.
+- Factory helpers (e.g., `getByLabel`) note the ARIA role used to locate the
+  element.
+
 ## Running tests
 
 To run the unit tests, execute the following command:

src/main/java/org/vaadin/addons/dramafinder/element/AbstractNumberFieldElement.java

@@ -16,22 +16,43 @@
 
 import static com.microsoft.playwright.assertions.PlaywrightAssertions.assertThat;
 
+/**
+ * Base abstraction for Vaadin number-like fields.
+ * <p>
+ * Provides shared behavior for numeric inputs, including access to step
+ * controls (increase/decrease buttons) and common mixins for validation,
+ * input handling, theming, accessibility, and focus.
+ */
 public abstract class AbstractNumberFieldElement extends VaadinElement
         implements HasValidationPropertiesElement, HasInputFieldElement,
         HasPrefixElement, HasSuffixElement, HasClearButtonElement,
         HasPlaceholderElement, HasAllowedCharPatternElement, HasThemeElement,
         FocusableElement, HasAriaLabelElement, HasEnabledElement, HasTooltipElement {
 
+    /**
+     * Creates a new {@code AbstractNumberFieldElement}.
+     *
+     * @param locator the locator pointing at the component root element
+     */
     public AbstractNumberFieldElement(Locator locator) {
         super(locator);
     }
 
-
+    /**
+     * Whether the step controls (increase/decrease buttons) are visible.
+     *
+     * @return {@code true} if the attribute is present, otherwise {@code false}
+     */
     public boolean getHasControls() {
         String v = getLocator().getAttribute("step-buttons-visible");
         return Boolean.parseBoolean(v);
     }
 
+    /**
+     * Assert the visibility of step controls.
+     *
+     * @param hasControls expected presence of the controls
+     */
     public void assertHasControls(boolean hasControls) {
         if (hasControls) {
             assertThat(getLocator()).hasAttribute("step-buttons-visible", "");
@@ -40,10 +61,16 @@ public void assertHasControls(boolean hasControls) {
         }
     }
 
+    /**
+     * Click the increase button.
+     */
     public void clickIncreaseButton() {
         getLocator().locator("[part='increase-button']").click();
     }
 
+    /**
+     * Click the decrease button.
+     */
     public void clickDecreaseButton() {
         getLocator().locator("[part='decrease-button']").click();
     }

src/main/java/org/vaadin/addons/dramafinder/element/AccordionElement.java

@@ -5,44 +5,79 @@
 
 import static com.microsoft.playwright.assertions.PlaywrightAssertions.assertThat;
 
+/**
+ * PlaywrightElement for {@code <vaadin-accordion>}.
+ * <p>
+ * Provides helpers to access panels by their summary text and to assert
+ * open/closed state and panel count.
+ */
 @PlaywrightElement(AccordionElement.FIELD_TAG_NAME)
 public class AccordionElement extends VaadinElement implements HasStyleElement {
 
     public static final String FIELD_TAG_NAME = "vaadin-accordion";
 
+    /**
+     * Create a new {@code AccordionElement}.
+     *
+     * @param locator the locator for the {@code <vaadin-accordion>} element
+     */
     public AccordionElement(Locator locator) {
         super(locator);
     }
 
+    /**
+     * Assert the number of panels present in the accordion.
+     */
     public void assertPanelCount(int count) {
         Locator panels = getLocator().locator(AccordionPanelElement.FIELD_TAG_NAME);
         assertThat(panels).hasCount(count);
     }
 
+    /**
+     * Get a panel by its summary text.
+     */
     public AccordionPanelElement getPanel(String summary) {
         return AccordionPanelElement.getAccordionPanelBySummary(getLocator(), summary);
     }
 
+    /**
+     * Open a panel by its summary text.
+     */
     public void openPanel(String summary) {
         getPanel(summary).setOpen(true);
     }
 
+    /**
+     * Close a panel by its summary text.
+     */
     public void closePanel(String summary) {
         getPanel(summary).setOpen(false);
     }
 
+    /**
+     * Whether the panel with the given summary is open.
+     */
     public boolean isPanelOpened(String summary) {
         return getPanel(summary).isOpen();
     }
 
+    /**
+     * Assert that the panel with the given summary is open.
+     */
     public void assertPanelOpened(String summary) {
         getPanel(summary).assertOpened();
     }
 
+    /**
+     * Assert that the panel with the given summary is closed.
+     */
     public void assertPanelClosed(String summary) {
         getPanel(summary).assertClosed();
     }
 
+    /**
+     * Get the currently opened panel.
+     */
     public AccordionPanelElement getOpenedPanel() {
         return AccordionPanelElement.getOpenedAccordionPanel(getLocator());
     }