Explore options for allowing editors to create heading structures without using <h> tags

[wesrowe]

Description

User story

AS A Content Editor I WANT to be able to add heading-type formatting to limited RT content (e.g., VA Benefit Taxonomy's Eligibility summary) without adding specific heading levels SO THAT presentation layers can apply heading styles/hierarchy while also ensuring that heading hierarchies make sense in a given product.

The use case isn't 100% clear and needs to be clarified on several levels:

• How would such a heading hierarchy be passed to a FE product?
• What happens if headings aren't appropriate to that type of FE experience?
• How many heading levels would be useful?

Engineering notes / background

This ticket will result in a "proof of concept" build which can be in Tugboat that can be used for review with CMS collab cycle and Editor workshop for feedback. Code will not merge to main or ship to Staging / Prod under this ticket.

Quality / testing notes

Acceptance criteria

• [ ] Proof of concept build is design reviewed by Jordan for feedback / input on design
• [ ] Build screenshots are linked or added to ticket comments to serve as design artifact – see this Mural area
• [ ] Depending on the success of the first attempt at PoC, EITHER:
  • [ ] CMS collab cycle touchpoint is scheduled to review proposed build approach & design notes for design system
  • [x] Ticketed follow-on iteration to further explore - #13802
• [ ] Design implementation ticket is written & linked to this ticket - #13755
• [ ] Preserve first version as its own branch for future demo/investigation

[wesrowe]

@davidmpickett, I just assigned this to you so it would be easy to find. Note that I've started this as an implementation ticket, under the guise of refinement. But if it's significant work to figure it out (ie no easy answer), we can make it a discovery ticket and get it worked into an actual sprint plan when you have capacity.

@chri5tia, FYSA this is something we'll pursue as a follow-on to your initial efforts in Sprint 81.

[davidmpickett]

https://www.w3.org/WAI/GL/wiki/Using_Standard_Text_Formatting_For_Headings#Example_2:

[davidmpickett]

Bad idea - use tag with aria heading roles?!

https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/heading_role

[davidmpickett]

New Text format that allows just one h tag? h2 maybe?

[jilladams]

From Benefit sync:

• A change here would need a CMS collab cycle review. The CMS Team ultimately owns the rich-text toolbar config options, and what we start could / should be repurposed elsewhere.
• Using H2 as default could maybe work. We need to consider: talking to @laflannery for feedback; how can we actually harness and modify the header levels appropriately
• Per Christia, there's a bigger conversation brewing on this topic among CivicActions leadership + Drupal core folks around how to manage this sort of Heading level on reusable content Thing. Are we getting ahead of a bigger fix coming from elsewhere?

Engineering problem here:

1. Adding capability to the toolbar, whatever that is.
2. Serving to front-end
3. Front-end working out how to correctly serve the right semantic headers.
   • This is a familiar problem from accordion headers when we started by setting H4 by default. It's hard for FE code to know what semantic level should be, depending on how the templates are structured.

[jilladams]

Related thread: https://dsva.slack.com/archives/C52CL1PKQ/p1681389906497229

[davidmpickett]

Possible solution from discussion with @chri5tia and @laflannery today:

Create a new Paragraph Type that would contain the following:

• Plain text field for a header
• Limited rich text field for any content directly under that header
• Ability to say whether this blob of content is the same level as the blob preceding it, or one level higher or lower. Perhaps with some visual indentation in the UI.

For a given field (e.g. Eligibility Summary), editors could add a number of these blobs and have internal hierarchy of the blobs without specifying any specific heading level for the front end presentation

Not sure what the right name for this new Paragraph Type would be. Some names floated:

• outline
• section
• text with header

[davidmpickett]

Rough sketch of possible paragraph type solution https://app.mural.co/t/departmentofveteransaffairs9999/m/vagov6717/1660845137501/6eadf59a3f4d8dcd29da572a68115a22d6114fe4?wid=0-1681487526574

[wesrowe]

Update: Wes will raise with Dave C in sync on Monday

[jilladams]

Refinement:

• We have a design proposal.
• Christia is ready to explore technical means of prototyping.
• We don't want "the cart before the horse" re: dev before design: so we need dev/design in lock-step re: how Drupal can work + a good editor experience.

5 estimate is based on a first pass that is basically agreeable. Some risk associated that points will get bigger if initial passes don't fly.

[jilladams]

Reassigning to Christia, moving back to Next sprint, based on today's conversation in refinement.

[wesrowe]

@jilladams, could this become the design ticket for Jordan's collaboration with Christia? (And unassign Dave?) disregard, see comment below

[wesrowe]

OMG this is so weird – when I loaded this page for the previous comment dave was still assigned (by himself)!!!!!!!!! I restarted computer this morning, so this is just bizarre.

[swirtSJW]

Something like this is a more flat data model (no paragraph recursion)

The heading levels do not tie to an absolute heading value (1 does not mean h1) It leave it up to the consumer to make headings accordingly based on where the content is used. Example: content appears under an h1

• 1 = h2
• 2 = h3
• 3 = h4

Example: content appears under an h3

• 1 = h4
• 2 = h5
• 3 = h6

On the node view side we can alter the template to apply actual headings just like the front end would.

Entity validation could be employed to make sure levels are not skipped

• 1 followed by 2 = valid
• 1 followed by 3 = not valid
• 3 followed by 2 = valid
• first entry is 2 = not valid

[laflannery]

@swirtSJW Just so I am understanding - the validation you are talking about above regarding the levels, this would be done on save and some type of error messaging would be shown? Or would we limit the levels available within the dropdown (i.e. if you have a one, the next level dropdown would not have 1 available in it)?

[chri5tia]

Steve, I love this. Thank you!

[swirtSJW]

@swirtSJW Just so I am understanding - the validation you are talking about above regarding the levels, this would be done on save and some type of error messaging would be shown? Or would we limit the levels available within the dropdown (i.e. if you have a one, the next level dropdown would not have 1 available in it)?

@laflannery Great question. I was thinking only on node save and error messaging shown. In general that is what Drupal considers validation. There is either field validation (where a field checks itself, but has no access to other field values) or entity validation where the entity has access to all its own fields and can make comparative judgements about any combination of field values or node properties.

Re adjusting the level options dynamically: This at first seems like the easiest way.... BUT given that an editor could drag one heading around after creating the others, or change a heading level after creating the others, this could be quite a mess. The only way to fully judge it and limit the possibility would be upon save.

[swirtSJW]

If we had to implement these "buttons"

We could make it so the buttons are literally just increasing or decreasing the helading level value by 1

[chri5tia]

Is there a way to combine these ideas? I love what you have presented here with respect to the simplicity and writing the actual header level into the data, making it easier to get at for the data consumer. If there was a way to limit the number of nests to three and have the header level drop down value automatically update upon clicking the "Complete drag and drop", using some kind of layout builder entity alter hook or conditional logic, would that fix the issue with the blob being even blobbier? I liked the visual structure and the ease of arranging items as children or siblings, etc. After removing nesting, it lacks that visual hierarchal satisfaction.

Without the visual/nesting:

[laflannery]

@chri5tia would this new pattern allow for future iterations where we can introduction other blocks like Files and images to include under the headings as well?

[chri5tia]

Yes, for sure.

[wesrowe]

I adjusted the ACs to reflect that the uncertainty/ambiguity of the "explore" intent in the title was not reflected in the ACs, which previously said "scheduled CMS Collab Cycle meeting." Slacked Jill about how to ticket the follow-on iteration that this ticket scope-crept into.

[wesrowe]

I created #13802 for @chri5tia to do the 2nd, non-nested iteration with a hardened data model based on @swirtSJW's comments above.

Christia, you can close this ticket when you've done the documentation ACs:

• save branch of iteration 1 for posterity and future demonstration

[jilladams]

This ticket is complete, and follow up work is happening in #13802. We are leaving the ticket open for tonight, to prevent the Tugboat from being destroyed. We will close the ticket as soon as we verify if Tugboat will be affected by closing ticket.

[jilladams]

https://dsva.slack.com/archives/CT4GZBM8F/p1684880982390919, Closing.