XWIKI-22165: Home page icons do not have a text alternative

xwiki-platform-core/xwiki-platform-icon/xwiki-platform-icon-macro/src/main/java/org/xwiki/icon/macro/DisplayIconMacroParameters.java

@@ -40,6 +40,8 @@ public class DisplayIconMacroParameters
 
     private String iconSet;
 
+    private String textAlternative;
+
     private boolean fallback = true;
 
     /**
@@ -100,4 +102,24 @@ public void setFallback(boolean fallback)
     {
         this.fallback = fallback;
     }
+
+    /**
+     * @since 16.8.0RC1
+     * @return the text alternative picked for the icon
+     */
+    public String getTextAlternative()
+    {
+        return this.textAlternative;
+    }
+
+    /**
+     * @since 16.8.0RC1
+     * @param textAlternative a text alternative for the icon
+     */
+    @PropertyName("Text Alternative")
+    @PropertyDescription("A text alternative for this icon.")
+    public void setTextAlternative(String textAlternative)
+    {
+        this.textAlternative = textAlternative;
+    }
 }

xwiki-platform-core/xwiki-platform-icon/xwiki-platform-icon-macro/src/main/java/org/xwiki/icon/macro/internal/DisplayIconMacro.java

@@ -19,6 +19,7 @@
  */
 package org.xwiki.icon.macro.internal;
 
+import java.util.ArrayList;
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
@@ -40,8 +41,11 @@
 import org.xwiki.rendering.async.internal.AbstractExecutedContentMacro;
 import org.xwiki.rendering.async.internal.block.BlockAsyncRendererConfiguration;
 import org.xwiki.rendering.block.Block;
+import org.xwiki.rendering.block.FormatBlock;
 import org.xwiki.rendering.block.ParagraphBlock;
+import org.xwiki.rendering.block.WordBlock;
 import org.xwiki.rendering.block.XDOM;
+import org.xwiki.rendering.listener.Format;
 import org.xwiki.rendering.listener.MetaData;
 import org.xwiki.rendering.macro.MacroExecutionException;
 import org.xwiki.rendering.syntax.Syntax;
@@ -142,6 +146,15 @@ public List<Block> execute(DisplayIconMacroParameters parameters, String content
             throw new MacroExecutionException("Failed parsing and executing the icon.", e);
         }
 
+        if (parameters.getTextAlternative() != null) {
+            // We complete the icon with a text alternative for screen readers.
+            Block textAltBlock = new FormatBlock(List.of(new WordBlock(parameters.getTextAlternative())), Format.NONE);
+            textAltBlock.setParameter("class", "sr-only");
+            ArrayList<Block> updatedList = new ArrayList<>(result);
+            updatedList.add(textAltBlock);
+            result = List.copyOf(updatedList);
+        }
+
         return result;
     }
 

xwiki-platform-core/xwiki-platform-icon/xwiki-platform-icon-macro/src/test/resources/macrodisplayicon6.test

@@ -0,0 +1,23 @@
+.runTransformations
+.#-----------------------------------------------------
+.input|xwiki/2.1
+.# Verify the text alternative functionality
+.#-----------------------------------------------------
+{{displayIcon name="home" textAlternative="Home" /}}
+.#-----------------------------------------------------
+.expect|event/1.0
+.#-----------------------------------------------------
+beginDocument
+beginMacroMarkerStandalone [displayIcon] [name=home|textAlternative=Home]
+beginMetaData [[syntax]=[XWiki 2.1]]
+beginParagraph
+beginFormat [NONE] [[class]=[icon][data-xwiki-icon]=[homeIcon]]
+onWord [i]
+endFormat [NONE] [[class]=[icon][data-xwiki-icon]=[homeIcon]]
+endParagraph
+endMetaData [[syntax]=[XWiki 2.1]]
+beginFormat [NONE] [[class]=[sr-only]]
+onWord [Home]
+endFormat [NONE] [[class]=[sr-only]]
+endMacroMarkerStandalone [displayIcon] [name=home|textAlternative=Home]
+endDocument

xwiki-platform-distribution/xwiki-platform-distribution-flavor/xwiki-platform-distribution-flavor-common/src/main/resources/Main/WebHome.xml

@@ -45,11 +45,13 @@ XWiki can be used as a knowledge base (support, documentation, sales, etc.), for
 
 To make the most out of your wiki, log-in and:
 
-Use the {{displayIcon name="pencil"/}} button above to //edit// this page and start customizing your wiki to your needs.
+Use the {{displayIcon name="pencil" textAlternative="Edit"/}} button above to //edit// this page and start customizing your wiki to your needs.
 
-Use the {{displayIcon name="add"/}} button above to //add// more pages to your wiki and create the //hierarchy// that best organizes your content.
+Use the {{displayIcon name="add" textAlternative="Create"/}} button above to //add// more pages to your wiki and create the //hierarchy// that best organizes your content.
 
-Use the {{displayIcon name="home"/}} breadcrumbs located above the title to //navigate// inside your pages. It's easy to get lost in a big wiki without them.
+Use the {{displayIcon name="home" textAlternative="Home"/}} breadcrumbs located above the title to //navigate// inside your pages. It's easy to get lost in a big wiki without them.
+
+{{html}}<p class="sr-only">Those three buttons are accessible using a keyboard between the global navbar elements and the main page content.</p>{{/html}}
 
 You can also use the [[Sandbox>>Sandbox.WebHome]] for more demo content and generally a place to experiment with your wiki's features.