feat: better check media overlays styling properties

- report schema error RSC-005 when the 'media:active-class' or
  'media:playback-active-class' properties are declared more than once.
- report schema error RSC-005 when the 'media:active-class' or
  'media:playback-active-class' properties define more than once class
  names.
- report new usage CSS-029 when a CSS selector is found referring to
  the widely-used '-epub-media-overlay-active' or '-epub-media-overlay-
  playing' class names but no 'media:active-class' or 'media:playback-
  active-class' properties were declared in the package document.
- report new error CSS-030 when the 'media:active-class' or
  'media:playback-active-class' properties are declared but no CSS is
  found in a content document with media overlays.
- added various test scenarios for the checks described above.

Closs #1218.

Author: rdeltour

src/main/java/com/adobe/epubcheck/css/CSSHandler.java

@@ -9,7 +9,9 @@
 import org.idpf.epubcheck.util.css.CssContentHandler;
 import org.idpf.epubcheck.util.css.CssErrorHandler;
 import org.idpf.epubcheck.util.css.CssExceptions.CssException;
+import org.idpf.epubcheck.util.css.CssGrammar;
 import org.idpf.epubcheck.util.css.CssGrammar.CssAtRule;
+import org.idpf.epubcheck.util.css.CssGrammar.CssComposedConstruct;
 import org.idpf.epubcheck.util.css.CssGrammar.CssConstruct;
 import org.idpf.epubcheck.util.css.CssGrammar.CssDeclaration;
 import org.idpf.epubcheck.util.css.CssGrammar.CssSelector;
@@ -201,6 +203,43 @@ public void endAtRule(String name)
   @Override
   public void selectors(List<CssSelector> selectors)
   {
+    for (CssSelector selector : selectors)
+    {
+      if (!context.featureReport.hasFeature(FeatureEnum.MEDIA_OVERLAYS_ACTIVE_CLASS)
+          && findClassName(selector, ".-epub-media-overlay-active"))
+      {
+        report.message(MessageId.CSS_029,
+            getCorrectedEPUBLocation(selector.getLocation().getLine(),
+                selector.getLocation().getColumn(), selector.toCssString()),
+            "-epub-media-overlay-active", "media:active-class");
+      }
+      if (!context.featureReport.hasFeature(FeatureEnum.MEDIA_OVERLAYS_PLAYBACK_ACTIVE_CLASS)
+          && findClassName(selector, ".-epub-media-overlay-playing"))
+      {
+        report.message(MessageId.CSS_029,
+            getCorrectedEPUBLocation(selector.getLocation().getLine(),
+                selector.getLocation().getColumn(), selector.toCssString()),
+            "-epub-media-overlay-playing", "media:playback-active-class");
+      }
+    }
+  }
+
+  private boolean findClassName(CssConstruct construct, String name)
+  {
+    if (construct.getType() == CssGrammar.CssConstruct.Type.CLASSNAME
+        && name.equals(construct.toCssString()))
+    {
+      return true;
+
+    }
+    else if (construct instanceof CssComposedConstruct)
+    {
+      for (CssConstruct component : ((CssComposedConstruct) construct).getComponents())
+      {
+        if (findClassName(component, name)) return true;
+      }
+    }
+    return false;
   }
 
   @Override

src/main/java/com/adobe/epubcheck/messages/DefaultSeverities.java

@@ -91,6 +91,8 @@ private void initialize()
     severities.put(MessageId.CSS_024, Severity.SUPPRESSED);
     severities.put(MessageId.CSS_025, Severity.SUPPRESSED);
     severities.put(MessageId.CSS_028, Severity.USAGE);
+    severities.put(MessageId.CSS_029, Severity.USAGE);
+    severities.put(MessageId.CSS_030, Severity.ERROR);
 
     // HTML
     severities.put(MessageId.HTM_001, Severity.ERROR);

src/main/java/com/adobe/epubcheck/messages/MessageId.java

@@ -85,6 +85,8 @@ public enum MessageId implements Comparable<MessageId>
   CSS_024("CSS-024"),
   CSS_025("CSS-025"),
   CSS_028("CSS-028"),
+  CSS_029("CSS-029"),
+  CSS_030("CSS-030"),
 
   // Messages relating to xhtml markup
   HTM_001("HTM-001"),

src/main/java/com/adobe/epubcheck/opf/OPFHandler30.java

@@ -566,6 +566,24 @@ private void processMeta()
     {
       metadataBuilders.peekFirst().meta(e.getAttribute("id"), prop.get(),
           (String) e.getPrivateData(), e.getAttribute("refines"));
+
+      // Primary metadata checks
+      if (metadataBuilders.size() == 1)
+      {
+        switch (prop.get().getPrefixedName())
+        {
+        case "media:active-class":
+          context.featureReport.report(FeatureEnum.MEDIA_OVERLAYS_ACTIVE_CLASS, location(),
+              e.getPrivateData().toString());
+          break;
+        case "media:playback-active-class":
+          context.featureReport.report(FeatureEnum.MEDIA_OVERLAYS_PLAYBACK_ACTIVE_CLASS, location(),
+              e.getPrivateData().toString());
+          break;
+        default:
+          break;
+        }
+      }
     }
 
     // just parse the scheme for vocab errors

src/main/java/com/adobe/epubcheck/ops/OPSHandler.java

@@ -51,6 +51,7 @@ public class OPSHandler extends XMLHandler
   protected boolean hasTh = false;
   protected boolean hasThead = false;
   protected boolean hasCaption = false;
+  protected boolean hasCSS = false;
   protected boolean epubTypeInUse = false;
   protected StringBuilder textNode;
   protected Stack<EPUBLocation> elementLocationStack = new Stack<EPUBLocation>();
@@ -94,10 +95,13 @@ protected void checkLink()
     XMLElement e = currentElement();
     URL href = checkURL(e.getAttribute("href"));
     String rel = e.getAttribute("rel");
-    if (xrefChecker.isPresent() && href != null && rel != null
+    if (href != null && rel != null
         && rel.toLowerCase(Locale.ROOT).contains("stylesheet"))
     {
-      xrefChecker.get().registerReference(href, XRefChecker.Type.STYLESHEET, location());
+      this.hasCSS = true;
+      if (xrefChecker.isPresent()) {
+        xrefChecker.get().registerReference(href, XRefChecker.Type.STYLESHEET, location());
+      }
     }
   }
 
@@ -365,6 +369,7 @@ public void endElement()
         String style = textNode.toString();
         if (style.length() > 0)
         {
+          this.hasCSS = true;
           new CSSChecker(context, style, currentLocation.getLine(), false).check();
         }
         textNode = null;

src/main/java/com/adobe/epubcheck/ops/OPSHandler30.java

@@ -815,6 +815,7 @@ public void endElement()
     String name = e.getName();
     if (openElements == 0 && (name.equals("html") || name.equals("svg")))
     {
+      checkOverlaysStyles();
       checkProperties();
     }
     else if (name.equals("object"))
@@ -902,6 +903,17 @@ protected void checkFallback(String elementType)
     }
   }
 
+  protected void checkOverlaysStyles()
+  {
+    if (context.opfItem.isPresent() && context.opfItem.get().getMediaOverlay() != null
+        && (context.featureReport.hasFeature(FeatureEnum.MEDIA_OVERLAYS_ACTIVE_CLASS)
+            || context.featureReport.hasFeature(FeatureEnum.MEDIA_OVERLAYS_PLAYBACK_ACTIVE_CLASS))
+                && !this.hasCSS)
+    {
+      report.message(MessageId.CSS_030, location());
+    }
+  }
+
   protected void checkProperties()
   {
     if (!context.container.isPresent()) // single file validation

src/main/java/com/adobe/epubcheck/util/FeatureEnum.java

@@ -64,6 +64,8 @@ public enum FeatureEnum
   LOI("list of illustrations"),
   LOT("list of tables"),
   LOV("list of videos"),
+  MEDIA_OVERLAYS_ACTIVE_CLASS("media:active-class"),
+  MEDIA_OVERLAYS_PLAYBACK_ACTIVE_CLASS("media:playback-active-class"),
   MODIFIED_DATE("modification date"),
   NAVIGATION_ORDER("navigation order"),
   PAGE_BREAK("epub:page-break"),

src/main/java/org/idpf/epubcheck/util/css/CssGrammar.java

@@ -130,7 +130,7 @@ public enum Type
   /**
    * A CssConstruct that is composed by a single token.
    */
-  static abstract class CssAtomicConstruct extends CssConstruct
+  public static abstract class CssAtomicConstruct extends CssConstruct
   {
     final String value;
 
@@ -434,7 +434,7 @@ public String toString()
    * A CssConstruct that is composed a list of atomic and/or composed CssConstructs,
    * and optionally a name.
    */
-  static abstract class CssComposedConstruct extends CssConstruct
+  public static abstract class CssComposedConstruct extends CssConstruct
   {
     final List<CssConstruct> components;
     final Optional<String> name;

src/main/resources/com/adobe/epubcheck/messages/MessageBundle.properties

@@ -67,6 +67,8 @@ CSS_024_SUG=Remove unused CSS selectors.
 CSS_025=CSS class Selector could not be found.
 CSS_025_SUG=Check for typos or define a class selector to document the use of the class.
 CSS_028=Use of Font-face declaration.
+CSS_029=Found CSS class name "%1$s" but no "%2$s" property was declared in the package document.
+CSS_030=The package document declares media overlays styling class names but no CSS was found in the content document. 
 
 #HTM - XHTML related messages
 HTM_001=Any publication resource that is an XML-based media type must be a valid XML 1.0 document. XML version found: %1$s.

src/main/resources/com/adobe/epubcheck/schema/30/package-30.sch

@@ -417,14 +417,24 @@
 	</pattern>
 
 	<pattern id="opf.media.overlay.metadata.active-class">
+	  <rule context="opf:package/opf:metadata">
+	    <assert test="count(opf:meta[normalize-space(@property)='media:active-class']) le 1">The 'active-class' property must not occur more than one time in the package
+	          metadata.</assert>
+	  </rule>
 		<rule context="opf:meta[normalize-space(@property)='media:active-class']">
 			<report test="@refines"> @refines must not be used with the media:active-class property</report>
+		  <report test="contains(normalize-space(.),' ')">the 'active-class' property must define a single class name</report>
 		</rule>
 	</pattern>
 
 	<pattern id="opf.media.overlay.metadata.playback-active-class">
+    <rule context="opf:package/opf:metadata">
+      <assert test="count(opf:meta[normalize-space(@property)='media:playback-active-class']) le 1">The 'playback-active-class' property must not occur more than one time in the package
+           metadata.</assert>
+    </rule>
 		<rule context="opf:meta[normalize-space(@property)='media:playback-active-class']">
 			<report test="@refines"> @refines must not be used with the media:playback-active-class property</report>
+		  <report test="contains(normalize-space(.),' ')">the 'playback-active-class' property must define a single class name</report>
 		</rule>
     </pattern>