Improved CSS API

Author: FlorianRappl

doc/API.md

@@ -28,3 +28,17 @@ The `ICssValue` interface is split in various interfaces with respect to their u
 ![The CSSOM Value Tree](cssom-value-tree.png)
 
 A converter may also implement the `IValueAggregator` interface, which indicates that the declaration behind it is actually a shorthand that can additionally merge values into a shorthand representation or split the shorthand representation into the atoms described by the shorthand.
+
+For convenience some (extension) methods have been introduced to make working with the CSSOM (specifically values) simpler. The shown extension methods are placed in the `AngleSharp.Css.Dom` namespace.
+
+```cs
+// sheet is a stylesheet, e.g., obtained from a document, with content:
+//   p > a { border: 1px solid red }
+var rule = sheet.GetStyleRuleWith("p>a");
+var color = rule.GetValueOf("border-right-color").AsRgba();
+// the color is an Int32, e.g., 0xFF_FF - same as rgba(255, 0, 0, 1)
+```
+
+The idea behind `GetStyleRuleWith` is to get the first top-level style rule that matches the given selector exactly. The text of the selector does not have to be equal to the text of the selector in the stylesheet, but it needs to be equal *semantically*, i.e., in the provided example the spaces do not matter as the semantics are not influenced by them.
+
+The `GetValueOf` obtains the `ICssValue` instance behind the property with the given name. The `AsRgba` works (like all the other `As*` extension methods) against the `ICssValue` to get an elementary value out of it. This works in simple cases, but will fail, e.g., when there are multiple values available or when the primitive value is hidden in a composite one.

src/AngleSharp.Css.Tests/Styling/CssSheet.cs

@@ -3,6 +3,7 @@ namespace AngleSharp.Css.Tests.Styling
     using AngleSharp.Css.Converters;
     using AngleSharp.Css.Dom;
     using AngleSharp.Css.Parser;
+    using AngleSharp.Css.Values;
     using NUnit.Framework;
     using System;
     using System.IO;
@@ -987,6 +988,24 @@ public void CssStyleSheetInsertShouldSetParentStyleSheetCorrectly()
             Assert.AreEqual(s, s.Rules[0].Owner);
         }
 
+        [Test]
+        public void GetImageRefOfACertainDeclarationFromSheet()
+        {
+            var s = ParseStyleSheet("body { background: url(http://example.com/foo.png) no-repeat }");
+            var rule = s.GetStyleRuleWith("body");
+            var url = rule.GetValueOf("background-image").AsUrl();
+            Assert.AreEqual("http://example.com/foo.png", url);
+        }
+
+        [Test]
+        public void GetBorderRightColorOfACertainDeclarationFromSheet()
+        {
+            var s = ParseStyleSheet("p > a { border: 1px solid red }");
+            var rule = s.GetStyleRuleWith("p > a");
+            var color = rule.GetValueOf("border-right-color").AsRgba();
+            Assert.AreEqual(0x00_00_ff_ff, color);
+        }
+
         [Test]
         public void CssColorFunctionsMixAllShouldWork()
         {

src/AngleSharp.Css/Dom/ICssProperties .cs

@@ -1,4 +1,4 @@
-namespace AngleSharp.Css.Dom
+namespace AngleSharp.Css.Dom
 {
     using AngleSharp.Attributes;
     using System;
@@ -33,6 +33,13 @@ public interface ICssProperties : IEnumerable<ICssProperty>
         [DomName("getPropertyValue")]
         String GetPropertyValue(String propertyName);
 
+        /// <summary>
+        /// Gets the full property model for the given property name.
+        /// </summary>
+        /// <param name="propertyName">The name of the property to get.</param>
+        /// <returns>The computed or stored property model.</returns>
+        ICssProperty GetProperty(String propertyName);
+
         /// <summary>
         /// Returns the optional priority, "important" or null, if no priority
         /// has been set.

src/AngleSharp.Css/Dom/Internal/CssStyleDeclaration.cs

@@ -74,6 +74,21 @@ public String CssText
 
         #region Methods
 
+        public ICssProperty GetProperty(String name)
+        {
+            for (var i = 0; i < _declarations.Count; i++)
+            {
+                var declaration = _declarations[i];
+
+                if (declaration.Name.Isi(name))
+                {
+                    return declaration;
+                }
+            }
+
+            return GetPropertyShorthand(name);
+        }
+
         public void SetParent(ICssRule parent) => _parent = parent;
 
         public void Update(String value)
@@ -290,24 +305,6 @@ public void SetProperty(String propertyName, String propertyValue, String priori
 
         #region Internal Methods
 
-        internal ICssProperty GetProperty(String name)
-        {
-            for (var i = 0; i < _declarations.Count; i++)
-            {
-                var declaration = _declarations[i];
-
-                if (declaration.Name.Isi(name))
-                {
-                    return declaration;
-                }
-            }
-
-            return GetPropertyShorthand(name);
-        }
-
-        private ICssProperty GetPropertyShorthand(String name) =>
-            TryCreateShorthand(name, Enumerable.Empty<String>(), new List<String>(), true);
-
         internal void SetDeclarations(IEnumerable<ICssProperty> decls) =>
             ChangeDeclarations(decls, m => false, (o, n) => !o.IsImportant || n.IsImportant);
 
@@ -318,6 +315,9 @@ internal void UpdateDeclarations(IEnumerable<ICssProperty> decls) =>
 
         #region Helpers
 
+        private ICssProperty GetPropertyShorthand(String name) =>
+            TryCreateShorthand(name, Enumerable.Empty<String>(), new List<String>(), true);
+
         private ICssProperty CreateProperty(String propertyName) =>
             GetProperty(propertyName) ?? _context.CreateProperty(propertyName);
 

src/AngleSharp.Css/Dom/Internal/Rules/CssDeclarationRule.cs

@@ -42,20 +42,15 @@ internal CssDeclarationRule(ICssStyleSheet owner, CssRuleType type, String name,
 
         #region Methods
 
-        public String GetPropertyValue(String propertyName)
-        {
-            return GetValue(propertyName);
-        }
+        public ICssProperty GetProperty(String propertyName) =>
+            _declarations.Find(m => m.Name.Is(propertyName));
 
-        public String GetPropertyPriority(String propertyName)
-        {
-            return null;
-        }
+        public String GetPropertyValue(String propertyName) => GetValue(propertyName);
 
-        public void SetProperty(String propertyName, String propertyValue, String priority = null)
-        {
+        public String GetPropertyPriority(String propertyName) => null;
+
+        public void SetProperty(String propertyName, String propertyValue, String priority = null) =>
             SetValue(propertyName, propertyValue);
-        }
 
         public String RemoveProperty(String propertyName)
         {
@@ -73,15 +68,9 @@ public String RemoveProperty(String propertyName)
             return null;
         }
 
-        public IEnumerator<ICssProperty> GetEnumerator()
-        {
-            return _declarations.GetEnumerator();
-        }
+        public IEnumerator<ICssProperty> GetEnumerator() => _declarations.GetEnumerator();
 
-        IEnumerator IEnumerable.GetEnumerator()
-        {
-            return GetEnumerator();
-        }
+        IEnumerator IEnumerable.GetEnumerator() => GetEnumerator();
 
         public override void ToCss(TextWriter writer, IStyleFormatter formatter)
         {

src/AngleSharp.Css/Extensions/CssOmExtensions.cs

@@ -0,0 +1,68 @@
+namespace AngleSharp.Css.Dom
+{
+    using AngleSharp.Css.Parser;
+    using AngleSharp.Text;
+    using System;
+    using System.Linq;
+
+    /// <summary>
+    /// CSSOM API extension methods.
+    /// </summary>
+    public static class CssOmExtensions
+    {
+        /// <summary>
+        /// Gets the style rule with the provided selector text.
+        /// </summary>
+        /// <param name="rule">The container rule.</param>
+        /// <param name="selectorText">The selector text to look for.</param>
+        /// <returns>The style rule, if any.</returns>
+        public static ICssStyleRule GetStyleRuleWith(this ICssGroupingRule rule, String selectorText) =>
+            rule.Rules.GetStyleRuleWith(selectorText, rule.Owner?.Context);
+
+        /// <summary>
+        /// Gets the style rule with the provided selector text.
+        /// </summary>
+        /// <param name="sheet">The sheet.</param>
+        /// <param name="selectorText">The selector text to look for.</param>
+        /// <returns>The style rule, if any.</returns>
+        public static ICssStyleRule GetStyleRuleWith(this ICssStyleSheet sheet, String selectorText) =>
+            sheet.Rules.GetStyleRuleWith(selectorText, sheet.Context);
+
+        /// <summary>
+        /// Gets the style rule with the provided selector text.
+        /// </summary>
+        /// <param name="rules">The rules to look in.</param>
+        /// <param name="selectorText">The selector text to look for.</param>
+        /// <param name="context">The context for normalizing the CSS selector.</param>
+        /// <returns>The style rule, if any.</returns>
+        public static ICssStyleRule GetStyleRuleWith(this ICssRuleList rules, String selectorText, IBrowsingContext context = null)
+        {
+            var styleRules = rules.OfType<ICssStyleRule>();
+            var parser = context?.GetService<ICssSelectorParser>();
+            var normalizedSelectorText = parser?.ParseSelector(selectorText)?.Text ?? selectorText;
+
+            foreach (var rule in styleRules)
+            {
+                if (rule.SelectorText.Is(normalizedSelectorText))
+                {
+                    return rule;
+                }
+            }
+
+            return null;
+        }
+
+        /// <summary>
+        /// Gets the ICssValue of a property with the given name.
+        /// </summary>
+        /// <param name="rule">The rule to extend.</param>
+        /// <param name="propertyName">The property to obtain.</param>
+        /// <returns>The value of the provided property, if any.</returns>
+        public static ICssValue GetValueOf(this ICssStyleRule rule, String propertyName)
+        {
+            rule = rule ?? throw new ArgumentNullException(nameof(rule));
+            var property = rule.Style.GetProperty(propertyName);
+            return property?.RawValue;
+        }
+    }
+}