package org.openautonomousconnection.luascript.hosts;

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

/**
 * Host capability that exposes a DOM-like API.
 *
 * <p>Element identity is the (stable) element id.</p>
 */
public interface DomHost {

    /**
     * Returns all element ids known to the renderer (must be stable).
     *
     * @return list of element ids
     */
    List<String> getAllElementIds();

    /**
     * Returns all attributes for the given element id.
     *
     * @param elementId element id
     * @return attributes map (attributeName -> attributeValue)
     */
    Map<String, String> getAttributes(String elementId);

    /**
     * Returns the tag name of the element (lowercase recommended), e.g. "script", "button".
     *
     * @param elementId element id
     * @return tag name
     */
    String getTagName(String elementId);

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

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

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

    /**
     * Sets an attribute (creates it if missing).
     *
     * @param elementId element id
     * @param name      attribute name
     * @param value     attribute value
     */
    void setAttribute(String elementId, String name, String value);

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

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

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

    /**
     * Creates a new element (detached) and returns its id.
     *
     * @param tagName     tag name
     * @param requestedId optional requested id, may be null/blank for auto id
     * @return created element id
     */
    String createElement(String tagName, String requestedId);

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

    /**
     * Moves/appends child under parent.
     *
     * @param parentId parent id
     * @param childId  child id
     */
    void appendChild(String parentId, String childId);

    /**
     * Inserts child before an existing direct child.
     *
     * @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 id exists.
     *
     * @param id element id
     * @return true if exists
     */
    boolean exists(String id);

    /**
     * Returns element ids by tag.
     *
     * @param tagName tag
     * @return ids
     */
    List<String> queryByTag(String tagName);

    /**
     * Returns element ids by class.
     *
     * @param className class
     * @return ids
     */
    List<String> queryByClass(String className);
}