Place caption tag in tables in correct location

DEVSIX-7951

Author: guustysebie

layout/src/main/java/com/itextpdf/layout/tagging/ITaggingRule.java

@@ -22,6 +22,18 @@ This file is part of the iText (R) project.
  */
 package com.itextpdf.layout.tagging;
 
+/**
+ * Implementation of the interface is used to create required children
+ * structure for the specified role. E.g. table must have TRs as children.
+ */
 interface ITaggingRule {
+    /**
+     * Action which creates required children structure for the role.
+     *
+     * @param taggingHelper tagging helper.
+     * @param taggingHintKey element for which children structure will be created.
+     *
+     * @return {@code true} if the structure was created successfully, {@code false} otherwise.
+     */
     boolean onTagFinish(LayoutTaggingHelper taggingHelper, TaggingHintKey taggingHintKey);
 }

layout/src/main/java/com/itextpdf/layout/tagging/LayoutTaggingHelper.java

@@ -50,19 +50,26 @@ This file is part of the iText (R) project.
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+/**
+ * The class is a helper which is used to correctly create structure
+ * tree for layout element (with keeping right order for tags).
+ */
 public class LayoutTaggingHelper {
     private TagStructureContext context;
     private PdfDocument document;
     private boolean immediateFlush;
 
+    // kidsHints and parentHints fields represent tree of TaggingHintKey, where parentHints
+    // stores a parent for the key, and kidsHints stores kids for key.
     private Map<TaggingHintKey, List<TaggingHintKey>> kidsHints;
     private Map<TaggingHintKey, TaggingHintKey> parentHints;
 
     private Map<IRenderer, TagTreePointer> autoTaggingPointerSavedPosition;
 
     private Map<String, List<ITaggingRule>> taggingRules;
 
-    private Map<PdfObject, TaggingDummyElement> existingTagsDummies;
+    // dummiesForPreExistingTags is used to process TaggingDummyElement
+    private Map<PdfObject, TaggingDummyElement> dummiesForPreExistingTags;
 
     private final int RETVAL_NO_PARENT = -1;
     private final int RETVAL_PARENT_AND_KID_FINISHED = -2;
@@ -79,7 +86,7 @@ public LayoutTaggingHelper(PdfDocument document, boolean immediateFlush) {
         this.taggingRules = new HashMap<>();
         registerRules(context.getTagStructureTargetVersion());
 
-        existingTagsDummies = new LinkedHashMap<>();
+        dummiesForPreExistingTags = new LinkedHashMap<>();
     }
 
     public static void addTreeHints(LayoutTaggingHelper taggingHelper, IRenderer rootRenderer) {
@@ -103,10 +110,10 @@ public static TaggingHintKey getOrCreateHintKey(IPropertyContainer container) {
 
     public void addKidsHint(TagTreePointer parentPointer, Iterable<? extends IPropertyContainer> newKids) {
         PdfDictionary pointerStructElem = context.getPointerStructElem(parentPointer).getPdfObject();
-        TaggingDummyElement dummy = existingTagsDummies.get(pointerStructElem);
+        TaggingDummyElement dummy = dummiesForPreExistingTags.get(pointerStructElem);
         if (dummy == null) {
             dummy = new TaggingDummyElement(parentPointer.getRole());
-            existingTagsDummies.put(pointerStructElem, dummy);
+            dummiesForPreExistingTags.put(pointerStructElem, dummy);
         }
         context.getWaitingTagsManager().assignWaitingState(parentPointer, getOrCreateHintKey(dummy));
         addKidsHint(dummy, newKids);
@@ -295,11 +302,11 @@ public void releaseFinishedHints() {
     }
 
     public void releaseAllHints() {
-        for (TaggingDummyElement dummy : existingTagsDummies.values()) {
+        for (TaggingDummyElement dummy : dummiesForPreExistingTags.values()) {
             finishTaggingHint(dummy);
             finishDummyKids(getKidsHint(getHintKey(dummy)));
         }
-        existingTagsDummies.clear();
+        dummiesForPreExistingTags.clear();
 
         releaseFinishedHints();
 
@@ -524,6 +531,7 @@ private void addKidsHint(TaggingHintKey parentKey, Collection<TaggingHintKey> ne
             } else {
                 kidsHint.add(kidKey);
             }
+            kidsHints.put(parentKey, kidsHint);
             parentHints.put(kidKey, parentKey);
 
             if (parentTagAlreadyCreated) {
@@ -542,10 +550,6 @@ private void addKidsHint(TaggingHintKey parentKey, Collection<TaggingHintKey> ne
                 }
             }
         }
-
-        if (!kidsHint.isEmpty()) {
-            kidsHints.put(parentKey, kidsHint);
-        }
     }
 
     private boolean createSingleTag(TaggingHintKey hintKey, TagTreePointer tagPointer) {

layout/src/main/java/com/itextpdf/layout/tagging/TableTaggingRule.java

@@ -24,7 +24,11 @@ This file is part of the iText (R) project.
 
 import com.itextpdf.kernel.pdf.tagging.StandardRoles;
 import com.itextpdf.layout.element.Cell;
+import com.itextpdf.layout.element.Div;
 import com.itextpdf.layout.element.Table;
+import com.itextpdf.layout.properties.CaptionSide;
+import com.itextpdf.layout.properties.Property;
+
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
@@ -70,9 +74,12 @@ public boolean onTagFinish(LayoutTaggingHelper taggingHelper, TaggingHintKey tab
         TaggingDummyElement tbodyTag = null;
         tbodyTag = new TaggingDummyElement(createTBody ? StandardRoles.TBODY : null);
 
+
         for (TaggingHintKey nonCellKid : nonCellKids) {
             String kidRole = nonCellKid.getAccessibleElement().getAccessibilityProperties().getRole();
-            if (!StandardRoles.THEAD.equals(kidRole) && !StandardRoles.TFOOT.equals(kidRole)) {
+            if (!StandardRoles.THEAD.equals(kidRole) && !StandardRoles.TFOOT.equals(kidRole) && !StandardRoles.CAPTION.equals(kidRole)) {
+                // In usual cases it isn't expected that this for loop will work, but it is possible to
+                // create custom tag hierarchy by specifying role, and put any child to tableHintKey
                 taggingHelper.moveKidHint(nonCellKid, tableHintKey);
             }
         }
@@ -89,7 +96,6 @@ public boolean onTagFinish(LayoutTaggingHelper taggingHelper, TaggingHintKey tab
                 taggingHelper.moveKidHint(nonCellKid, tableHintKey);
             }
         }
-
         for (TreeMap<Integer, TaggingHintKey> rowTags : tableTags.values()) {
             TaggingDummyElement row = new TaggingDummyElement(StandardRoles.TR);
             TaggingHintKey rowTagHint = LayoutTaggingHelper.getOrCreateHintKey(row);
@@ -105,6 +111,35 @@ public boolean onTagFinish(LayoutTaggingHelper taggingHelper, TaggingHintKey tab
             taggingHelper.addKidsHint(tbodyTag, Collections.<TaggingDummyElement>singletonList(row), -1);
         }
 
+        for (TaggingHintKey nonCellKid : nonCellKids) {
+            String kidRole = nonCellKid.getAccessibleElement().getAccessibilityProperties().getRole();
+            if (StandardRoles.CAPTION.equals(kidRole)) {
+                moveCaption(taggingHelper, nonCellKid, tableHintKey);
+            }
+        }
+
         return true;
     }
+
+    private static void moveCaption(LayoutTaggingHelper taggingHelper, TaggingHintKey caption, TaggingHintKey tableHintKey) {
+        if (!(tableHintKey.getAccessibleElement() instanceof Table)) {
+            return;
+        }
+        Table tableElem = (Table) tableHintKey.getAccessibleElement();
+        Div captionDiv = tableElem.getCaption();
+        if (captionDiv == null) {
+            return;
+        }
+        CaptionSide captionSide;
+        if (captionDiv.<CaptionSide>getProperty(Property.CAPTION_SIDE) == null) {
+            captionSide = CaptionSide.TOP;
+        } else {
+            captionSide = (CaptionSide) captionDiv.<CaptionSide>getProperty(Property.CAPTION_SIDE);
+        }
+        if (CaptionSide.TOP.equals(captionSide)) {
+            taggingHelper.moveKidHint(caption, tableHintKey, 0);
+        } else {
+            taggingHelper.moveKidHint(caption, tableHintKey);
+        }
+    }
 }

layout/src/main/java/com/itextpdf/layout/tagging/TaggingDummyElement.java

@@ -22,25 +22,41 @@ This file is part of the iText (R) project.
  */
 package com.itextpdf.layout.tagging;
 
-import com.itextpdf.kernel.pdf.tagutils.DefaultAccessibilityProperties;
 import com.itextpdf.kernel.pdf.tagutils.AccessibilityProperties;
+import com.itextpdf.kernel.pdf.tagutils.DefaultAccessibilityProperties;
 import com.itextpdf.layout.IPropertyContainer;
 import com.itextpdf.layout.properties.Property;
 
+/**
+ * Instances of the class are used for {@link TaggingHintKey} which don't have model element
+ * e.g. TR or THEAD in the table. Nobody will call {@link LayoutTaggingHelper#finishTaggingHint(IPropertyContainer)}
+ * for them, it is why they should be handled separately.
+ */
 public class TaggingDummyElement implements IAccessibleElement, IPropertyContainer {
     private DefaultAccessibilityProperties properties;
 
     private Object id;
 
+    /**
+     * Instantiate a new {@link TaggingDummyElement} instance.
+     *
+     * @param role the role.
+     */
     public TaggingDummyElement(String role) {
         this.properties = new DefaultAccessibilityProperties(role);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public AccessibilityProperties getAccessibilityProperties() {
         return properties;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public <T1> T1 getProperty(int property) {
         if (property == Property.TAGGING_HINT_KEY) {
@@ -49,33 +65,51 @@ public <T1> T1 getProperty(int property) {
         return (T1) (Object) null;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public void setProperty(int property, Object value) {
         if (property == Property.TAGGING_HINT_KEY) {
             this.id = value;
         }
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public boolean hasProperty(int property) {
         throw new UnsupportedOperationException();
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public boolean hasOwnProperty(int property) {
         throw new UnsupportedOperationException();
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public <T1> T1 getOwnProperty(int property) {
         throw new UnsupportedOperationException();
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public <T1> T1 getDefaultProperty(int property) {
         throw new UnsupportedOperationException();
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public void deleteOwnProperty(int property) {
         throw new UnsupportedOperationException();

layout/src/main/java/com/itextpdf/layout/tagging/TaggingHintKey.java

@@ -22,46 +22,96 @@ This file is part of the iText (R) project.
  */
 package com.itextpdf.layout.tagging;
 
+import com.itextpdf.layout.element.IElement;
+import com.itextpdf.layout.renderer.IRenderer;
+import com.itextpdf.layout.renderer.RootRenderer;
+
+/**
+ * TaggingHintKey instances are created in the scope of {@link RootRenderer#addChild(IRenderer)}
+ * to preserve logical order of layout elements from model elements.
+ */
 public final class TaggingHintKey {
     private IAccessibleElement elem;
     private boolean isArtifact;
     private boolean isFinished;
     private String overriddenRole;
     private boolean elementBasedFinishingOnly;
 
+    /**
+     * Instantiate a new {@link TaggingHintKey} instance.
+     *
+     * @param elem element this hint key will be created for.
+     * @param createdElementBased {@code true} if element implements {@link IElement}.
+     */
     TaggingHintKey(IAccessibleElement elem, boolean createdElementBased) {
         this.elem = elem;
         this.elementBasedFinishingOnly = createdElementBased;
     }
 
+    /**
+     * Get accessible element.
+     *
+     * @return the accessible element.
+     */
     public IAccessibleElement getAccessibleElement() {
         return elem;
     }
 
+    /**
+     * Retrieve hint key finished flag.
+     *
+     * @return {@code true} if hint key is finished, {@code false} otherwise.
+     */
     boolean isFinished() {
         return isFinished;
     }
 
+    /**
+     * Set finished flag for hint key instance.
+     */
     void setFinished() {
         this.isFinished = true;
     }
 
+    /**
+     * Retrieve information whether this hint key is artifact or not.
+     *
+     * @return {@code true} if hint key corresponds to artifact, {@code false} otherwise.
+     */
     boolean isArtifact() {
         return isArtifact;
     }
 
+    /**
+     * Specify that hint key instance corresponds to artifact.
+     */
     void setArtifact() {
         this.isArtifact = true;
     }
 
+    /**
+     * Get overridden role.
+     *
+     * @return the overridden role.
+     */
     String getOverriddenRole() {
         return overriddenRole;
     }
 
+    /**
+     * Set the overridden role.
+     *
+     * @param overriddenRole overridden role.
+     */
     void setOverriddenRole(String overriddenRole) {
         this.overriddenRole = overriddenRole;
     }
 
+    /**
+     * Retrieve information whether the element backed by this hint key implements {@link IElement}.
+     *
+     * @return {@code} true if element implements {@link IElement}.
+     */
     boolean isElementBasedFinishingOnly() {
         return elementBasedFinishingOnly;
     }

layout/src/test/java/com/itextpdf/layout/LayoutTaggingTest.java

@@ -1128,6 +1128,31 @@ public void neutralRoleTaggingTest() throws Exception {
         compareResult(outFile, "cmp_" + outFile);
     }
 
+    @Test
+    public void unexpectedTableHintChildTest()
+            throws IOException, InterruptedException, ParserConfigurationException, SAXException {
+        String outFile = "unexpectedTableHintChildTest.pdf";
+
+        try (PdfDocument pdfDocument = new PdfDocument(new PdfWriter(destinationFolder + outFile))){
+            Document document = new Document(pdfDocument);
+            pdfDocument.setTagged();
+
+            Div div = new Div();
+            div.getAccessibilityProperties().setRole(StandardRoles.TABLE);
+
+            final Paragraph c1 = new Paragraph("c1");
+            c1.getAccessibilityProperties().setRole(StandardRoles.LINK);
+            div.add(c1);
+
+            Paragraph p1 = new Paragraph("c");
+            p1.getAccessibilityProperties().setRole(StandardRoles.TD);
+            div.add(p1);
+
+            document.add(div);
+        }
+        compareResult(outFile, "cmp_" + outFile);
+    }
+
     private Paragraph createParagraph1() throws IOException {
         PdfFont font = PdfFontFactory.createFont(StandardFonts.HELVETICA_BOLD);
         Paragraph p = new Paragraph().add("text chunk. ").add("explicitly added separate text chunk");