Add table block caption #15554

talldan · 2019-05-10T08:13:20Z

Related #15283, #6923

Fixes #11589

Description

Adds the ability to specify a caption for the table block.

How has this been tested?

Add a table
Add a caption to the table
Preview the post and check that the table has a caption

Screenshots

Side-by-side of image and table captions in the editor

Types of changes

New feature (non-breaking change which adds functionality)

Checklist:

My code is tested.
My code follows the WordPress code style.
My code follows the accessibility standards.
My code has proper inline documentation.
I've included developer documentation if appropriate.

talldan · 2019-05-10T08:22:05Z

It'd be great to get some accessibility feedback on this PR, especially on the editor implementation of the caption.

Initially I thought this would be easy, but the tricky part is that the html table element has only a very specific set of elements it allows as children. I wasn't able to use a <RichText> directly within the table to represent the caption, as that component outputs a <div> as its root element.

Instead I've added a normal caption tag to the table and made it visibility: hidden (not sure if making it zero height and overflow hidden would be preferable?). Then I've added a RichText outside the table for editing the caption.

Is there a better way to do this?

talldan · 2019-05-15T05:53:09Z

Thinking that adding a rootTagName prop to RichText might be a better solution so that I don't have to add a hack in this PR.

talldan · 2019-05-16T07:56:06Z

Well ... I don't know why I didn't think of this before, but the obvious solution is to put the RichText component in the caption element. Not sure why I didn't think of this before.🤦‍♂

However, I tested it out, and that introduces other problems. The HTML spec mentions to put the caption before the tbody in a table, but if the caption is first in the DOM the tab order is wrong for users of the table block.

The tbody also overlaps the caption's inline toolbar, and adjusting the z-index doesn't seem to resolve this. 🤔

Perhaps the original solution was the better one.

aduth · 2019-05-17T15:15:32Z

@talldan I think it could be appropriate here to use the figure element? In general, I'd see this as being implemented almost identical to the image block (though I'm not really a fan of its save implementation with always-figure and div wrappers).

<figure>
    <table><!-- ... --></table>
    <figcaption>My lovely caption</figcaption>
</figure>

See also: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/table#attr-summary

Include the <table> element in a <figure> element and add the description in prose next to it.

Edit: Aha! I didn't realize this was the original implementation. It seems to me like it would be a reasonable approach.

afercia · 2019-05-18T16:34:46Z

Re: the div wrappers problem within the editor:
I'm not sure if it's technically possible, but I'd vote for a contenteditable <caption> element. Is it possible to use that instead of a RichText component?

Also, while HTML allows to omit the caption element when the table is wrapped in a figure with a figcaption, I'm not sure about actual support from assistive technologies. I'd recommend to use the <caption> element.

Hiding the <caption> element seems a bit hacky to me, as it wouldn't be perceived by assistive technologies and as a consequence the table wouldn't have an associated title.

If it's not possible to use a <caption> within the editor, I guess we should just accept the table won't have a 100% correct semantic in the editor.

The default placement of the caption should be at the top. That's the default for table captions. The placement at the bottom could be implemented as a style variation. Worth noting a table caption is something different from what generally Gutenberg means for "captions". Therefore, I'd also propose to rename this field to "Table caption".

talldan · 2019-05-23T05:45:29Z

Many thanks for the feedback, @aduth and @afercia. I haven't had much time lately to develop this further. I'll do some thinking on this, and try to come up with a way forward. It sounds like I also need to do some testing to understand the difference between how caption and figcaption might work in assistive tech.

talldan · 2019-06-10T10:45:15Z

Have been doing some initial testing in VoiceOver of the various options for the table caption implementation. (cc: @afercia, would be interested in your thoughts on this).

I've implemented option 2 described below on this branch if anyone wants to test it.

Option 1 (RichText inside the caption element)

<table>
    <caption><RichText ... /></caption>
     // ...
</table>

For:

Correct table markup

Against:

I haven't figured out a way to make the tab order work when using caption-side: bottom;, so this option might be limited to only displaying the caption above the table.
VoiceOver didn't seem to know what to do with a contenteditable inside a table caption. It doesn't seem to announce it when editing. That would seem to rule this option out.

Option 2 (RichText outside the table, visibly hidden caption)

<table>
    <caption className="screen-reader-text">{ caption }</caption>
     // ...
</table>
<RichText ... />

Pros:

Correct table markup.
Could support both caption-side: top; and caption-side: bottom;.

Cons:

The user has to leave the context of the table to edit the caption. Though they're at least still within the context of the table block.
After altering the content of the RichText, the updated table caption wasn't read by VoiceOver in Chrome (worked fine in Safari). Forcing the element to be replaced in the DOM instead of updated resolved this, but it's a bit of a hack!

Option 3 (figure/figcaption)

<figure>
    <table>
         // ...
    </table>
     <figcaption><RichText /></figcaption>
<figure>

Pros:

Could support both caption-side: top; and caption-side: bottom;.

Cons:

While this is considered ok, it's not quite how table captions are supposed to be marked up.
The caption isn't read by voiceover when interacting with the table.
The user has to leave the context of the table to edit the caption. Though they're at least still within the context of the table block.

afercia · 2019-06-10T12:43:58Z

@talldan thanks for working on this. Right, I tested also on Windows and seems most of the browser / screen reader combinations have troubles with the editable within the <caption> element. Some of them focus the editable but don't announce anything. Some don't even focus the editable. Basically only Safari + VoiceOver get it right.

Codepen for testing: https://codepen.io/afercia/full/RzbMvx

The same happens with a native <input> field so this appears to be some unfortunate browsers limitation.

Will ping around to see if others have faced the same issue. For now, I don't have suggestions other than using a div element with an aria-label="Table caption" to clarify what it is. The important thing is that in the front end it's rendered as a real <caption> element.

talldan · 2019-06-11T11:23:20Z

Thanks @afercia. Hopefully what I've done so far is the best compromise. The contenteditable has the aria label 'Write caption ...' at the moment, which matches the image block.

patrikhuber · 2019-11-01T12:26:02Z

Hi! This is great. Any estimates on when we can see this in official WordPress?
Thanks!

ellatrix · 2019-11-06T11:13:16Z

@talldan Looks good. There's just a failing test left?

ellatrix

Looks good. This should include a fixture for the deprecation(s) though. Why is there a deprecation is the first place?

Try using a figcaption for the table caption Revert "Try using a figcaption for the table caption" Switch back to a standard table caption This reverts commit b5f00dd. Add comment explaining location of RichText Ensure table cell is deselected when navigating from a table cell to the caption Styling tweaks Add an inline toolbar to the caption to match the image block implementation Adjust margin to match image block Add e2e test for the table block caption Refine caption accessibility. Use a div for the caption content Update caption to use a figcaption element with aria-labelledby Update table block deprecation so that it has its own attribute definition Update existing fixtures and add a new fixture for table captions Minor refinements Fix hasCaption logic Update snapshots Update comment with latest understanding of issue Use client id to generate non-clashing caption element id Update block-transforms fixture Update test to use a regular expression

…apshots

talldan · 2019-12-02T06:20:07Z

@ellatrix Thanks for the follow-up review.

There's a very minor fix in this PR that required the deprecation. I think it's best to move that over to another PR so that it can be reviewed separately.

edit: #18861 is the fix that I've moved out of this PR. Turns out it didn't even require a deprecation 🤦‍♂

This reverts commit f3ae751.

…pdate snapshots" This reverts commit 0265104.

afercia · 2020-03-09T09:42:00Z

At some point there was consensus the best option was:

It looks like figcaption + aria-labelledby is the best option

See #15554 (comment)

Also, see #15554 (comment)

The important thing is that in the front end it's rendered as a real <caption> element.

Maybe I'm missing something but seems to me there's no aria-labelledby, nor the caption is rendered in a <caption> element on the front end. Is there any follow-up issue to address these points? /Cc @talldan 👋 (when you have a chance, thanks!)

paaljoachim · 2020-06-13T06:59:38Z

Hey Dan @talldan

Could something similar be used for inline alignment of image captions? #12997 (comment)

For at the moment the caption begins on the left bottom of the image. It would be great to have inline captions to choose where to have the caption. Left - center - right.

Thanks!

cirkut · 2020-07-20T20:40:54Z

I want to go back to @afercia and their comment. Table captions should be using the native <caption> element that are supported by tables. This will allow themes to directly and easily support native captions and caption placements for tables, and additionally provide the proper semantics for tables. Even adding a toggle for top/bottom placement for the captions and writing the proper CSS would be welcomed.

talldan added [Type] Enhancement A suggestion for improvement. Needs Accessibility Feedback Need input from accessibility [Block] Table Affects the Table Block labels May 10, 2019

talldan requested review from aduth, ajitbohra, gziolo, jorgefilipecosta, nerrad, noisysocks, notnownikki, ntwb, Soean and youknowriad as code owners May 10, 2019 08:13

talldan self-assigned this May 10, 2019

gziolo added the Good First Review A PR that's suitable for someone looking to contribute for the first time by reviewing code label May 10, 2019

talldan mentioned this pull request May 10, 2019

Users cannot add table metadata in the visual editor #15283

Closed

afercia added [Focus] Accessibility (a11y) Changes that impact accessibility and need corresponding review (e.g. markup changes). and removed Needs Accessibility Feedback Need input from accessibility labels May 18, 2019

talldan force-pushed the add/table-block-caption branch from 1c315a4 to 95236f4 Compare June 10, 2019 10:40

talldan force-pushed the add/table-block-caption branch from 95236f4 to e27beab Compare June 11, 2019 11:20

talldan added the Needs Design Feedback Needs general design feedback. label Jun 11, 2019

talldan force-pushed the add/table-block-caption branch from f43f3cf to 801f6cf Compare October 21, 2019 09:32

patrikhuber mentioned this pull request Nov 1, 2019

Table block: flesh out editor features #6923

Open

ellatrix approved these changes Nov 7, 2019

View reviewed changes

talldan added 8 commits December 2, 2019 14:10

Reuse the captionId when already set as an attribute

3e05aff

Change style rule to use figcaption selector

1793afb

Explain use of aria-labelledby

8f5d4ec

Update deprecation

65e2063

Use RichText for figcaption, strip out a11y hacks

91c3e80

Ensure empty classname is not output onto table element and update sn…

0265104

…apshots

Update raw handling test

f3ae751

talldan force-pushed the add/table-block-caption branch from 801f6cf to f3ae751 Compare December 2, 2019 06:17

talldan added 3 commits December 2, 2019 14:22

Revert "Update raw handling test"

a0adac7

This reverts commit f3ae751.

Revert "Ensure empty classname is not output onto table element and u…

9181248

…pdate snapshots" This reverts commit 0265104.

Update table caption fixtures and deprecations

6474a17

talldan force-pushed the add/table-block-caption branch from 1f4f4af to 6474a17 Compare December 2, 2019 07:54

talldan merged commit 4a4bd4a into master Dec 2, 2019

talldan deleted the add/table-block-caption branch December 2, 2019 08:11

youknowriad added this to the Gutenberg 7.1 milestone Dec 9, 2019

phpbits mentioned this pull request Dec 27, 2019

Add Alignment to Table Caption CakeWP/block-options#212

Closed

etoledom removed their request for review March 9, 2020 12:01

joedolson mentioned this pull request Jul 24, 2020

Finish resolving accessibility issues with Table Block #24205

Open

tellthemachines mentioned this pull request Jun 2, 2022

Improve table caption accessibility #41502

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add table block caption #15554

Add table block caption #15554

talldan commented May 10, 2019 •

edited

Loading

talldan commented May 10, 2019 •

edited

Loading

talldan commented May 15, 2019 •

edited

Loading

talldan commented May 16, 2019

aduth commented May 17, 2019 •

edited

Loading

afercia commented May 18, 2019

talldan commented May 23, 2019

talldan commented Jun 10, 2019

afercia commented Jun 10, 2019 •

edited

Loading

talldan commented Jun 11, 2019

patrikhuber commented Nov 1, 2019

ellatrix commented Nov 6, 2019

ellatrix left a comment

talldan commented Dec 2, 2019 •

edited

Loading

afercia commented Mar 9, 2020

paaljoachim commented Jun 13, 2020

cirkut commented Jul 20, 2020 •

edited

Loading

Add table block caption #15554

Add table block caption #15554

Conversation

talldan commented May 10, 2019 • edited Loading

Description

How has this been tested?

Screenshots

Types of changes

Checklist:

talldan commented May 10, 2019 • edited Loading

talldan commented May 15, 2019 • edited Loading

talldan commented May 16, 2019

aduth commented May 17, 2019 • edited Loading

afercia commented May 18, 2019

talldan commented May 23, 2019

talldan commented Jun 10, 2019

afercia commented Jun 10, 2019 • edited Loading

talldan commented Jun 11, 2019

patrikhuber commented Nov 1, 2019

ellatrix commented Nov 6, 2019

ellatrix left a comment

Choose a reason for hiding this comment

talldan commented Dec 2, 2019 • edited Loading

afercia commented Mar 9, 2020

paaljoachim commented Jun 13, 2020

cirkut commented Jul 20, 2020 • edited Loading

talldan commented May 10, 2019 •

edited

Loading

talldan commented May 10, 2019 •

edited

Loading

talldan commented May 15, 2019 •

edited

Loading

aduth commented May 17, 2019 •

edited

Loading

afercia commented Jun 10, 2019 •

edited

Loading

talldan commented Dec 2, 2019 •

edited

Loading

cirkut commented Jul 20, 2020 •

edited

Loading