Editor: Add Semantic Headings to the Editor Sidebar

Feature Description

This feature will allow a user to select the text within a page and see and change the text element within the sidebar.

Many thanks to @swissspidy for the implementation idea, and to @aaskedall for the UX guidance.

Acceptance Criteria

• This should be under a new experimental feature flag.
  • The semantic headings experiment flag is on the branch titled: feature/11788-experiment-semantic-headings… Please branch off of this when working on this feature.
  • For an example of how to use it with a feature, see this PR: https://github.com/GoogleForCreators/web-stories-wp/pull/11626/files
• Within the Accessibility area of the Editor when text is selected, there should be a new Dropdown
• This dropdown should be titled “Heading Level” and should show the following properties:
  • Automatic (xyz) (stored as auto)
  • Heading 1 (stored as h1)
  • Heading 2 (stored as h2)
  • Heading 3 (stored as h3)
  • Paragraph (stored as p)
• When the dropdown item is changed to another option in the dropdown, it should update the text element’s tagName property

Example of implementation from @swissspidy (approved by @aaskedall):

Developer Notes

Notes from @swissspidy on implementation: xyz is replaced with whatever getTextElementTagNames() returns for the element.

When changing this option, the text element’s tagName property is updated.

getTextElementTagNames() is updated to take this tagName property into account.

Below the dropdown we can add a helper text <a>Learn more</a> about using headings in Web Stories., where we can link to the docs

Alternatives Considered

In addition to this space, this functionality will also be accomplished within a right-click menu on the text element.

Additional Context

[sblinde]

Hope that makes sense.

Happy to explain it with code too if that is helpful. But from what I can see you seem to be close–the pushUpdate thing to update the story data seems to be the main missing piece.

Thank you!!! This is the piece I was missing contextually. This all makes a lot of sense and I think I can move forward with this, it was that pushUpdate part that I was missing. Many thanks for the well detailed explanation and help!

[swissspidy]

So there’s a file where there’s logic done to add semantic headings, and a function is a part of this to change the tag name. See here: https://github.com/GoogleForCreators/web-stories-wp/blob/feature/11788-semantic-headings-editor-sidebar/includes/AMP/Traits/Sanitization_Utils.php

You should be able to safely ignore that file. The only thing it does is trying to retrofit heading tags for older stories. If there are are any heading tags anywhere in the story already it’s a no-op:

https://github.com/GoogleForCreators/web-stories-wp/blob/feature/11788-semantic-headings-editor-sidebar/includes/AMP/Traits/Sanitization_Utils.php#L142-L145

but that this file for getTextElementTagNames doesn’t actually change anything, it just creates a map that can be used in other spaces in the application with each element mapped

That map is used when generating the story output in OutputPage here:

https://github.com/GoogleForCreators/web-stories-wp/blob/54d0be958acc0fb9a02f692171fe8b6610a31998/packages/output/src/page.js#L77-L79

Which is then used to set/change/override the tag name for every text element here:

https://github.com/GoogleForCreators/web-stories-wp/blob/54d0be958acc0fb9a02f692171fe8b6610a31998/packages/output/src/page.js#L99

In order to support the idea of us updating the name of a tag, we need it to be beyond the component state, so that it’s saved as part of the published data of the selected element.

In TextAccessibilityPanel you can use the pushUpdate callback (which is passed as a prop to every panel) to update the element’s tagName.

Here’s an example of pushUpdate in another panel:

https://github.com/GoogleForCreators/web-stories-wp/blob/657866a2574ae5a02ece3ab88c990bec75eb0f3d/packages/story-editor/src/components/panels/design/videoAccessibility/videoAccessibility.js#L89-L102

pushUpdate updates the element only once you step out of the design panel again (e.g. when you click on the canvas)

You can verify that the tagName property is set on an element by inspecting the story data in the dev tools.

Circling back to OutputPage and getTextElementTagNames: With the tagName being properly set in the story data and your new change to getTextElementTagNames, this tagName should now be picked up when generating the story HTML that is visible on the frontend.

Hope that makes sense.

Happy to explain it with code too if that is helpful. But from what I can see you seem to be close–the pushUpdate thing to update the story data seems to be the main missing piece.