GPALElement.cs

// =============================================================================
// GPAL - Generally Positive Automation Library
// Copyright © 2026 Software Decisions, Inc. All rights reserved.
//
// This file is part of GPAL.
// Licensed under the Business Source License 1.1
//
// Primary development, architecture, and vision by Michael B. Vederman,
// CEO of Software Decisions, Inc., Texas.
//
// Internal development maintained privately.
// Public releases appear on GitHub: https://github.com/SoftwareDecisionsInc/GPAL.
//
// See LICENSE for full terms, including Additional Use Grant.
// =============================================================================
 
using System;
using System.Collections.Generic;
using System.Collections.ObjectModel;
using System.Drawing;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using OpenQA.Selenium;
using static GenerallyPositive.Enums;
using GenerallyPositive.Browser;
using System.Reflection;
using DocumentFormat.OpenXml.Spreadsheet;
 
 
namespace GenerallyPositive
{
    public class XPathInfo
    {
        public string Xpath { get; set; }

        public int MatchedElements { get; set; }

        public XPathInfo(string xpath, int matchedElements)
        {
            Xpath = xpath;
            MatchedElements = matchedElements;
        }
    }

    public class ClientRectangle
    {
        public float Top { get; set; }
        public float Left { get; set; }
        public float Bottom { get; set; }
        public float Right { get; set; }
        public float X { get; set; }
        public float Y { get; set; }
        public float Width { get; set; }
        public float Height { get; set; }

        public Size Size
        {
            get => new Size((int)Width, (int)Height);
            set
            {
                Width = value.Width;
                Height = value.Height;
            }
        }

        public Dictionary<string, object> ToDictionary()
        {
            return new Dictionary<string, object>
            {
                { nameof(Top), Top },
                { nameof(Left), Left },
                { nameof(Bottom), Bottom },
                { nameof(Right), Right },
                { nameof(X), X },
                { nameof(Y), Y },
                { nameof(Width), Width },
                { nameof(Height), Height }
            };
        }
 
        internal ClientRectangle(Point point, Size size)
        {
            Top = point.Y;
            Left = point.X;
            Width = size.Width;
            Height = size.Height;
        }

        public ClientRectangle()
        {
        }

        public bool IsEmpty =>
            X == 0 && Y == 0 && Width == 0 && Height == 0;
    }

    public class GPALElement : IGPALElement, IDisposable
    {
        public Browser.Browser Browser { get; internal set; }

        public GPALElement ShadowRoot { get; internal set; }

        public Dictionary<string, object> Attributes { get; set; } = new Dictionary<string, object>(StringComparer.OrdinalIgnoreCase);
 
        private Dictionary<string, object> _cssAttributes;
        public Dictionary<string, object> CssAttributes
        {
            get
            {
                if (null == _cssAttributes)
                {
                    GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Getting Css Attributes for element [{TagName}]", this, GPALObjectType.Other);
 
                    if (Browser.UsePuppeteer)
                        _cssAttributes = Browser.PuppeteerClient.GetCssAttributes(ElementBackendNodeId.ToString()).Execute<Dictionary<string, object>>();
                    else if (Browser.UseOttoMagic)
                        _cssAttributes = Browser.MagicHelper.GetCssAttributes(Css);
                    else
                        _cssAttributes = ElementHelper.GetCssAttributes(Browser, WebElement);
 
                    if (null == _cssAttributes)
                        _cssAttributes = new Dictionary<string, object>();
 
                    GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Got [{_cssAttributes.Count}] Css Attributes for element [{TagName}]", this, GPALObjectType.Other);
                }
                return _cssAttributes;
            }
            set => _cssAttributes = value;
        }
 
        private Dictionary<string, object> _domAttributes;
        public Dictionary<string, object> DomAttributes
        {
            get
            {
                if (null == _domAttributes)
                {
                    GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Getting Dom Attributes for element [{TagName}]", this, GPALObjectType.Other);
 
                    if (Browser.UsePuppeteer)
                        _domAttributes = Browser.PuppeteerClient.GetDomAttributes(ElementBackendNodeId.ToString()).Execute<Dictionary<string, object>>();
                    else if (Browser.UseOttoMagic)
                        _domAttributes = Browser.MagicHelper.GetDomAttributes(Css);
                    else
                        _domAttributes = ElementHelper.GetDomAttributes(Browser, WebElement);
 
                    if (null == _domAttributes)
                        _domAttributes = new Dictionary<string, object>();
 
                    GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Got [{_domAttributes.Count}] Dom Attributes for element [{TagName}]", this, GPALObjectType.Other);
                }
                return _domAttributes;
            }
            set => _domAttributes = value;
        }
 
        private Dictionary<string, object> _domProperties;
        public Dictionary<string, object> DomProperties
        {
            get
            {
                if (null == _domProperties)
                {
                    GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Getting Dom Properties for element [{TagName}]", this, GPALObjectType.Other);
 
                    if (Browser.UsePuppeteer)
                        _domProperties = Browser.PuppeteerClient.GetDomProperties(ElementBackendNodeId.ToString()).Execute<Dictionary<string, object>>();
                    else if (Browser.UseOttoMagic)
                        _domProperties = Browser.MagicHelper.GetDomProperties(Css);
                    else
                        _domProperties = ElementHelper.GetDomProperties(Browser, WebElement);
 
                    if (null == _domProperties)
                        _domProperties = new Dictionary<string, object>();
 
                    GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Got [{_domProperties.Count}] Dom Properties for element [{TagName}]", this, GPALObjectType.Other);
                }
                return _domProperties;
            }
            set => _domProperties = value;
        }

        public IWebDriver WrappedDriver { get; set; }
 
        internal dynamic iWebElement;
        public dynamic WebElement
        {
            get => iWebElement;
            internal set => iWebElement = value;
        }
 
        public string ElementHandle { get; set; } // objectId for puppeteer
        public int ElementNodeId { get; set; }
        public int ElementBackendNodeId { get; set; }
        internal long? ContextId { get; set; }
        internal bool IsShadowRoot { get; set; } = false;
        internal bool IsClosedShadowRoot { get; set; } = false;

        public Selector Selector { get; internal set; }
 
        // ==================== Existing Properties ====================

        public string Name
        {
            get { return Attributes.ContainsKey("name") ? Attributes["name"] as string : null; }
            set { Attributes["name"] = value; }
        }

        public string AttributeName
        {
            get { return Attributes.ContainsKey("attributeName") ? Attributes["attributeName"] as string : null; }
            set { Attributes["attributeName"] = value; }
        }

        public string TagName
        {
            get { return Attributes.ContainsKey("tagName") ? Attributes["tagName"].ToString() : null; }
            set { Attributes["tagName"] = value; }
        }

        public string Text
        {
            get { return Attributes.ContainsKey("text") ? Attributes["text"] as string : null; }
            set { Attributes["text"] = value; }
        }

        public bool Enabled
        {
            get { return Attributes.ContainsKey("enabled") && Attributes["enabled"] is bool ? (bool)Attributes["enabled"] : false; }
            set { Attributes["enabled"] = value; }
        }

        public bool Selected
        {
            get { return Attributes.ContainsKey("selected") && Attributes["selected"] is bool ? (bool)Attributes["selected"] : false; }
            set { Attributes["selected"] = value; }
        }

        public bool? Checked
        {
            get
            {
                bool indeterminate = Attributes.ContainsKey("indeterminate")
                                  && Attributes["indeterminate"] is bool
                                  && true == (bool)Attributes["indeterminate"];
 
                return true == indeterminate ? (bool?)null : Selected;
            }
            set { Attributes["selected"] = true == value; Attributes["indeterminate"] = null == value; }
        }

        public Point Location
        {
            get { return Attributes.ContainsKey("location") && Attributes["location"] is Point ? (Point)Attributes["location"] : new Point(0, 0); }
            set { Attributes["location"] = value; }
        }

        internal CoordinateSpace CoordinateSpace
        {
            get { return Attributes.ContainsKey("coordinateSpace") && Attributes["coordinateSpace"] is CoordinateSpace ? (CoordinateSpace)Attributes["coordinateSpace"] : CoordinateSpace.Screen; }
            set { Attributes["coordinateSpace"] = value; }
        }

        internal GPALElement ImageMatch { get; set; }

        public Size Size
        {
            get { return Attributes.ContainsKey("size") && Attributes["size"] is Size ? (Size)Attributes["size"] : new Size(0, 0); }
            set { Attributes["size"] = value; }
        }

        public bool Displayed
        {
            get
            {
                bool visibilty = true;
                bool display = true;
                bool opacity = true;
 
                if (true == CssAttributes.ContainsKey("visibility"))
                    visibilty = CssAttributes["visibility"]?.ToString() != "hidden";
 
                if (true == CssAttributes.ContainsKey("display"))
                    display = CssAttributes["display"]?.ToString() != "none";
 
                if (true == CssAttributes.ContainsKey("opacity"))
                    opacity = CssAttributes["opacity"]?.ToString() != "0";
 
                bool notHidden = visibilty && display && opacity;
 
                bool hasSize = BoundingRect.Width > 0 && BoundingRect.Height > 0;
 
                return notHidden && hasSize;
            }
            set { Attributes["displayed"] = value; }
        }

        public string Href
        {
            get { return Attributes.ContainsKey("href") ? Attributes["href"] as string : null; }
            set { Attributes["href"] = value; }
        }

        public string Src
        {
            get { return Attributes.ContainsKey("src") ? Attributes["src"] as string : null; }
            set { Attributes["src"] = value; }
        }

        public string Value
        {
            get { return Attributes.ContainsKey("value") ? Attributes["value"] as string : null; }
            set { Attributes["value"] = value; }
        }

        public string Placeholder
        {
            get { return Attributes.ContainsKey("placeholder") ? Attributes["placeholder"] as string : null; }
            set { Attributes["placeholder"] = value; }
        }

        public string Xpath
        {
            get { return Attributes.ContainsKey("xpath") ? Attributes["xpath"] as string : null; }
            set { Attributes["xpath"] = value; }
        }

        public XPathInfo[] Xpaths
        {
            get { return Attributes.ContainsKey("xpaths") && Attributes["xpaths"] is XPathInfo[]? (XPathInfo[])Attributes["xpaths"] : new XPathInfo[0]; }
            set
            {
                Attributes["xpaths"] = value;
            }
        }

        public string Css
        {
            get { return Attributes.ContainsKey("css") ? Attributes["css"] as string : null; }
            set { Attributes["css"] = value; }
        }

        public string FullXPath
        {
            get { return Attributes.ContainsKey("fullXPath") ? Attributes["fullXPath"] as string : null; }
            set { Attributes["fullXPath"] = value; }
        }

        public ClientRectangle BoundingRect
        {
            get { return Attributes.ContainsKey("boundingRect") && Attributes["boundingRect"] is ClientRectangle ? (ClientRectangle)Attributes["boundingRect"] : null; }
            set { Attributes["boundingRect"] = value; }
        }

        public string PageURL
        {
            get { return Attributes.ContainsKey("pageURL") ? Attributes["pageURL"] as string : null; }
            set { Attributes["pageURL"] = value; }
        }

        public string Type
        {
            get { return Attributes.ContainsKey("type") ? Attributes["type"] as string : null; }
            set { Attributes["type"] = value; }
        }
 
        internal GPALElement()
        {
        }
 
        internal GPALElement(Browser.Browser browser)
        {
            Browser = browser;
        }

        internal GPALElement(Point location, Size size, string text, IWebDriver webDriver, string tagname = "img")
        {
            WrappedDriver = webDriver;
            TagName = tagname;
            Text = CleanText(text);
            Location = location;
            Size = size;
            BoundingRect = new ClientRectangle(Location, Size);
        }
 
        internal GPALElement(IWebElement webElement, string attributeName = "")
        {
            iWebElement = webElement;
            AttributeName = attributeName;
            if (webElement != null)
            {
                TagName = webElement.TagName;
                Text = CleanText(webElement.Text);
                Enabled = webElement.Enabled;
                Selected = webElement.Selected;
                Location = webElement.Location;
                Size = webElement.Size;
                Displayed = webElement.Displayed;
                Href = webElement.GetAttribute("href");
                Src = webElement.GetAttribute("src");
                Value = CleanText(webElement.GetAttribute("value"));
                Placeholder = CleanText(webElement.GetAttribute("placeholder"));
                Type = webElement.GetAttribute("type");
 
                PageURL = WrappedDriver != null ? WrappedDriver.Url : null;
 
                BoundingRect = new ClientRectangle(Location, Size);
            }
        }

        internal GPALElement(IWebElement webElement, string attributeName, Dictionary<string, object> properties, string pageUrl)
        {
            iWebElement = webElement;
            AttributeName = attributeName;
 
            TagName = StringOf(properties, "tag");
            Text = CleanText(StringOf(properties, "text"));
            Enabled = BoolOf(properties, "enabled");
            Selected = BoolOf(properties, "selected");
            Attributes["indeterminate"] = BoolOf(properties, "indeterminate");   // the third state of a checkbox, which Checked answers with null
            Displayed = BoolOf(properties, "displayed");
            Location = new Point(IntOf(properties, "x"), IntOf(properties, "y"));
            Size = new Size(IntOf(properties, "w"), IntOf(properties, "h"));
            Href = StringOf(properties, "href");
            Src = StringOf(properties, "src");
            Value = CleanText(StringOf(properties, "value"));
            Placeholder = CleanText(StringOf(properties, "placeholder"));
            Type = StringOf(properties, "type");
            PageURL = pageUrl;
 
            BoundingRect = new ClientRectangle(Location, Size);
        }
        static string StringOf(Dictionary<string, object> properties, string name)
        {
            return true == properties.TryGetValue(name, out object value) ? value?.ToString() : null;
        }
        static bool BoolOf(Dictionary<string, object> properties, string name)
        {
            return true == properties.TryGetValue(name, out object value) && true == Convert.ToBoolean(value);
        }
        static int IntOf(Dictionary<string, object> properties, string name)
        {
            return true == properties.TryGetValue(name, out object value) && null != value ? Convert.ToInt32(value) : 0;
        }
 
        internal GPALElement(Dictionary<string, object> attributes, Browser.Browser browser)
        {
            WrappedDriver = browser.BrowserSettings.BrowserDriver;
            Attributes = attributes ?? new Dictionary<string, object>(StringComparer.OrdinalIgnoreCase);
            Browser = browser;
        }

        public void Clear()
        {
            if (iWebElement != null)
                try
                {
                    iWebElement.Clear();
                }
                catch { }
        }

        public void Click(ModifierKeys modifierKeys)
        {
            string currentUrl = Browser.BrowserSettings.CurrentURL;
            Browser.CurrentUOW.ActionCalled = true;
 
            BrowserHelper.TopBrowser(Browser, false);
            ElementHelper.Click(Browser, Selector, this, ClickType.LeftClick, modifierKeys);
 
            string currentUrl2 = Browser.GetSetCurrentUrl();
 
            if (false == UrlHelper.AreEquivalent(currentUrl, currentUrl2))
                BrowserHelper.CheckDocumentReady(Browser);    // just a simple document ready check
        }

        public void Click()
        {
            Click(ModifierKeys.NONE);
        }

        public void MiddleClick(ModifierKeys modifierKeys = ModifierKeys.NONE)
        {
            Browser.CurrentUOW.ActionCalled = true;
            BrowserHelper.TopBrowser(Browser, false);
            ElementHelper.Click(Browser, Selector, this, ClickType.MiddleClick, modifierKeys);
            //BrowserHelper.CheckDocumentReady(Browser);    // just a simple document ready check
        }

        public void Hide()
        {
            Browser.CurrentUOW.ActionCalled = true;
            ElementHelper.Hide(Browser, this);
        }

        public IWebElement FindElement(By by)
        {
            if (iWebElement != null)
                return iWebElement.FindElement(by);
            throw new NoSuchElementException("Element not found using " + by);
        }

        public ReadOnlyCollection<IWebElement> FindElements(By by)
        {
            if (iWebElement != null)
                return iWebElement.FindElements(by);
            return new ReadOnlyCollection<IWebElement>(new List<IWebElement>());
        }

        public string GetAttribute(string attributeName)
        {
            string seleniumValue = null;
 
            if (iWebElement != null)
                seleniumValue = iWebElement.GetAttribute(char.ToUpper(attributeName[0]) + attributeName.Substring(1));   // NOTE: ours are lowercase, so search selenium as capitalized (TagName will get ours)
 
            if (null == seleniumValue)
                if (Attributes.ContainsKey(attributeName))
                {
                    object value = Attributes[attributeName];
                    if (value is Point p)
                        return string.Format("({0},{1})", p.X, p.Y);
                    if (value is Size s)
                        return string.Format("({0},{1})", s.Width, s.Height);
                    if (value is XPathInfo[] arr)
                        return string.Join("; ", arr.Select(x => string.Format("{0} ({1})", x.Xpath, x.MatchedElements)));
                    if (value is ClientRectangle r)
                        return string.Format("(top={0}, left={1}, bottom={2}, right={3}, x={4}, y={5}, width={6}, height={7})",
                            r.Top, r.Left, r.Bottom, r.Right, r.X, r.Y, r.Width, r.Height);
                    if (value == null)
                        return null;
                    return value.ToString();
                }
 
            PropertyInfo property = GetType().GetProperty(attributeName, BindingFlags.Public | BindingFlags.Instance | BindingFlags.IgnoreCase);
            if (property != null && property.CanRead)
                return property.GetValue(this, null)?.ToString();
 
            return null;
        }

        public void SetAttribute(string attributeName, string value)
        {
            ElementHelper.SetAttribute(Browser, this, attributeName, value);
        }

        public string GetCssValue(string propertyName)
        {
            return iWebElement != null ? iWebElement.GetCssValue(propertyName) : CssAttributes[propertyName];
        }

        public string GetDomAttribute(string attributeName)
        {
            return iWebElement != null ? iWebElement.GetDomAttribute(attributeName) : DomAttributes[attributeName];
        }

        public string GetDomProperty(string propertyName)
        {
            return iWebElement != null ? iWebElement.GetDomProperty(propertyName) : DomProperties[propertyName];
        }

        public ISearchContext GetShadowRoot()
        {
            // using puppeteer, ShadowRoot will be populated
            var shadowRoot = iWebElement != null ? iWebElement.GetShadowRoot() : ShadowRoot;
 
            return shadowRoot;
        }

        public void SendKeys(string text)
        {
            if (iWebElement != null)
                iWebElement.SendKeys(text);
        }

        public void Submit()
        {
            if (iWebElement != null)
                iWebElement.Submit();
        }

        public bool IsDisabled()
        {
            bool attrDisabled = Attributes.ContainsKey("disabled") && Attributes["disabled"].ToString() == "true";
            bool propDisabled = false;
 
            if (DomProperties.ContainsKey("disabled"))
                propDisabled = DomProperties["disabled"].ToString() == "true";
 
            return attrDisabled || propDisabled;
        }

        public bool IsEnabled()
        {
            return !IsDisabled();
        }

        public bool IsClickable(bool publishEvent = true)
        {
            bool isClickable = true;
 
            if (true == Browser.UseOttoMagic)
                isClickable = Browser.MagicHelper.IsClickAble(Css);
            //else if (true == Browser.UsePuppeteer)
            //    isClickable = Browser.PuppeteerClient.IsClickable(Css).Execute<bool>();
            else    // selenium
            {
                bool notDisabled = !IsDisabled();
 
                bool ariaDisabled =
                    Attributes.TryGetValue("aria-disabled", out var aria) &&
                    aria.ToString().Equals("true", StringComparison.OrdinalIgnoreCase);
 
                bool pointerOk = true;
                if (true == CssAttributes.TryGetValue("pointer-events", out var pe))
                    pointerOk = pe.ToString() != "none";
 
                isClickable =
                    Displayed &&
                    notDisabled &&
                    !ariaDisabled &&
                    pointerOk;
 
                if (false == isClickable && true == publishEvent)
                    GPAL.PublishSimpleEvent(
                        GPALEventType.WARNING,
                        $"Element [{TagName}] does not appear clickable.",
                        this,
                        GPALObjectType.Other);
            }
 
            return true;
        }
 
        // release any CDP created nodes and free up memory
        private bool disposed = false;

        public async Task DisposeAsync() // or void Dispose() with fire-and-forget
        {
            if (disposed || string.IsNullOrEmpty(ElementHandle)) return;
 
            if (true == Browser.UsePuppeteer)
                try
                {
                    // Use the same communicator/session that created it, or a global one
                    await Browser.PuppeteerCommunicator.SendCommand<object>(
                        DevToolsMethods.RuntimeReleaseObject,
                        new { objectId = ElementHandle },
                        null); // however you track the right session
                }
                catch
                {
                    // Session might already be detached — safe to ignore
                }
 
            ElementHandle = null;
            disposed = true;
        }

        public void Dispose()
        {
            _ = DisposeAsync(); // fire-and-forget if in sync context
        }
 
        static string CleanText(string str) => str is null ? null : System.Text.RegularExpressions.Regex.Replace(str, @"\s+", " ").Trim();
    }
}