package org.openautonomousconnection.luascript.hosts;

import java.util.List;
import java.util.Map;

/**
 * Abstraction over DOM access for scripting.
 *
 * <p>All element references are by stable element {@code id}.</p>
 */
public interface DomHost {

    /**
     * Returns a list of all element ids in the document.
     *
     * @return list of ids (never null)
     */
    List<String> getAllElementIds();

    /**
     * Returns all attributes of the element.
     *
     * @param elementId element id
     * @return attributes map (never null)
     */
    Map<String, String> getAttributes(String elementId);

    /**
     * Returns the element tag name, lowercase if possible.
     *
     * @param elementId element id
     * @return tag name (never null)
     */
    String getTagName(String elementId);

    /**
     * Returns the element text content.
     *
     * @param elementId element id
     * @return text (never null)
     */
    String getTextContent(String elementId);

    /**
     * Sets the element text content.
     *
     * @param elementId element id
     * @param text      new text
     */
    void setTextContent(String elementId, String text);

    /**
     * Returns an attribute value or null if missing.
     *
     * @param elementId element id
     * @param name      attribute name
     * @return value or null if missing
     */
    String getAttribute(String elementId, String name);

    /**
     * Sets an attribute value (empty string allowed).
     *
     * @param elementId element id
     * @param name      attribute name
     * @param value     attribute value
     */
    void setAttribute(String elementId, String name, String value);

    /**
     * Removes an attribute from the element.
     *
     * @param elementId element id
     * @param name      attribute name
     */
    void removeAttribute(String elementId, String name);

    /**
     * Returns the parent element id or null if none.
     *
     * @param elementId element id
     * @return parent id or null
     */
    String getParentId(String elementId);

    /**
     * Returns children element ids.
     *
     * @param elementId element id
     * @return list of children ids (never null)
     */
    List<String> getChildrenIds(String elementId);

    /**
     * Creates an element and makes it addressable immediately.
     *
     * @param tagName     tag name
     * @param requestedId requested id or null
     * @return created element id
     */
    String createElement(String tagName, String requestedId);

    /**
     * Removes an element from the document.
     *
     * @param elementId element id
     */
    void removeElement(String elementId);

    /**
     * Appends a child element to a parent.
     *
     * @param parentId parent id
     * @param childId  child id
     */
    void appendChild(String parentId, String childId);

    /**
     * Inserts {@code childId} before {@code beforeChildId} within {@code parentId}.
     *
     * @param parentId      parent id
     * @param childId       child id
     * @param beforeChildId existing child id
     */
    void insertBefore(String parentId, String childId, String beforeChildId);

    /**
     * Checks if an element with the given id exists.
     *
     * @param id element id
     * @return true if exists
     */
    boolean exists(String id);

    /**
     * Queries elements by tag name and returns their ids.
     *
     * @param tagName tag name
     * @return list of ids (never null)
     */
    List<String> queryByTag(String tagName);

    /**
     * Queries elements by class token and returns their ids.
     *
     * @param className class name token
     * @return list of ids (never null)
     */
    List<String> queryByClass(String className);
}