Page MenuHomePhabricator

Collapse ToC into page title at narrow screens
Open, HighPublic5 Estimated Story Points

Description

Background

See T306660: [Goal] Table of contents on narrow screens in vector-2022

Description

This is the first of two tickets that will provide collapsible behavior for the table of contents. The first part (this ticket) will allow the ToC to automatically collapse into a button next to the page title for narrow screens (below 1000px). The second part will allow the ToC to be collapsed manually at any screen sizes.

Design & prototype

https://di-collapsible-menus.web.app/Brown_bear

Acceptance criteria

  • When the page width is less than 1000px, automatically collapse the table of contents into an icon-button next to the page title
    Screen Shot 2022-05-09 at 12.21.54 PM.png (494×774 px, 158 KB)
  • Clicking the icon-button will open the table of contents
    image.png (1×1 px, 634 KB)
  • If both sidebar and ToC are open, the ToC will display under the sidebar (this is how it works currently)
  • The ToC icon-button in the title is accessible via keyboard ('space' & 'enter' keys will toggle the menu)
  • The ToC icon-button in the title has correct aria attributes (aria-haspopup and aria-expanded) and markup consistent with other checkbox hack implementations
  • After the ToC icon-button in the title opens the menu, the menu is accessible as the next element for screen readers and keyboard users (i.e. tab) << to be addressed in follow up

QA steps

  • Beta cluster link TK
  • Verify that above desktop (1000px) view port, sticky TOC behaves as it does currently on production.
  • For the following use cases, see 1st 2 screenshots in T307900#7958897 :
    • Between tablet (720px) and desktop (1000px) view ports:
      • Verify that the collapsible TOC icon renders next to the page title when at the top of the page when the sidebar menu is open.
      • Verify that the collapsible TOC icon renders next to the page title when at the top of the page when the sidebar menu is closed.
      • Verify that clicking on the collapsible TOC icon next to page title opens the TOC as an overlay
      • Verify that clicking on a TOC section navigates the user to that section with the collapsed TOC icon sticky in the sidebar (for both sidebar menu expanded/collapsed states) will be addressed in T308689
      • Verify that the collapsible TOC icon is navigable via keyboard tabs:
        • Tabbing to TOC icon and hitting "Enter" will toggle the TOC open/closed
        • Tabbing to TOC icon, hitting "Enter" to open TOC, then tabbing to TOC section navigates user to that section.
    • Below tablet (720px) view port:
      • Verify above steps but note that sidebar menu collapses full width above main content so there is no expanded sidebar container state for the expanded/collapsed TOC.
    • Repeat above steps for the no-js context - note that the TOC headings will not be collapsed.
    • Cross-check in other supported browsers.

Event Timeline

There are a very large number of changes, so older changes are hidden. Show Older Changes

hi @alexhollender_WMF a few clarifications at your convenience:

  1. Regarding the 1st AC:

If both sidebar and ToC are open, the ToC will display under the sidebar (this is how it works currently)

This applies only to view ports above desktop (1000px)?

  1. In the prototype, the sidebar menu toggles to overlay the sidebar menu items instead of populating/collapsing the sidebar container - confirming this new functionality is not within scope of this ticket?

If so, then between tablet (720px) and desktop (1000px), if the sidebar menu is toggled open, the sidebar menu items will still appear in the sidebar container (as opposed to as an overlay like in the prototype). Depending on sidebar menu toggling, lower down on the page, the TOC icon will remain sticky in the sidebar within either the collapsed sidebar (TOC overlays main content) or expanded sidebar (TOC fills sidebar adjacent to main content).

Can you confirm if the use cases below match your expectations? (screenshots below captured around 800px view port)

At the top of the page with sidebar menu expanded, TOC icon positioned next to page title and when TOC toggled open, overlays main content and sidebar menu items fill expanded sidebar container:

Screen Shot 2022-05-25 at 6.06.15 PM.png (1×1 px, 515 KB)

At the top of the page with sidebar menu collapsed, TOC icon positioned next to page title and when TOC toggled open, overlays main content but sidebar container is collapsed:

Screen Shot 2022-05-25 at 6.06.51 PM.png (1×1 px, 500 KB)

Lower on the page (by scrolling or clicking on lower TOC section) with sidebar menu expanded, TOC icon with TOC collapsed remains sticky within expanded sidebar container:

Screen Shot 2022-05-25 at 6.13.36 PM.png (1×1 px, 390 KB)

Lower on the page (by scrolling or clicking on lower TOC section) with sidebar menu expanded, TOC icon with TOC expanded remains sticky and fills expanded sidebar container:

Screen Shot 2022-05-25 at 6.07.56 PM.png (1×1 px, 434 KB)

Lower on the page (by scrolling or clicking on lower TOC section) with sidebar menu collapsed, TOC icon with TOC collapsed remains sticky within collapsed sidebar container:

Screen Shot 2022-05-25 at 6.18.01 PM.png (1×1 px, 495 KB)

Lower on the page (by scrolling or clicking on lower TOC section) with sidebar menu collapsed, TOC icon with TOC expanded remains sticky within collapsed sidebar container and expanded TOC overlays main content:

Screen Shot 2022-05-25 at 6.07.36 PM.png (1×1 px, 445 KB)

@cjming

  1. Regarding the 1st AC: this applies only to view ports above desktop (1000px)?
    • Yes, that's correct. Below 1000px the TOC will always be a floating element (i.e. higher z-index, absolute position, doesn't displace other elements in the layout)
  1. In the prototype, the sidebar menu toggles to overlay the sidebar menu items instead of populating/collapsing the sidebar container - confirming this new functionality is not within scope of this ticket?
    • Yes, that's correct. The sidebar will remain as it is currently in production (i.e. no floating panel, whenever it is open it always displaces other elements in the layout)
  1. Screenshots:
    • All of the screenshots look correct to me. Below 1000px when the TOC is open it will always either be overlapping the article content, or overlapping the sidebar (if the sidebar is open).
    • The only thing that's slightly hard to confirm from the screenshots is: in the 4th screenshot I assume the sidebar is visible below the TOC?
      Screen Shot 2022-05-25 at 6.07.56 PM.png (1×1 px, 434 KB)

thanks for confirming @alexhollender_WMF

  • The only thing that's slightly hard to confirm from the screenshots is: in the 4th screenshot I assume the sidebar is visible below the TOC?
    Screen Shot 2022-05-25 at 6.07.56 PM.png (1×1 px, 434 KB)

It is not currently - sidebar menu should be visible beneath TOC below desktop (1000px) when sidebar is open and user has navigated lower down on the page?

In production, when sidebar is open above desktop, clicking/scrolling lower on the page, only the TOC is visible in the sidebar (not other sidebar menu items) -- should this stay consistent at lower view ports?

@cjming my bad, I forgot that the sidebar isn't sticky. Please ignore that last comment ("in the 4th screenshot I assume the sidebar is visible below the TOC?".)

Test wiki created on Patch demo by CMing (WMF) using patch(es) linked to this task:
https://patchdemo.wmflabs.org/wikis/9b9fe58d2a/w/

cjming updated the task description. (Show Details)

Note that associated patch covers the 1st design use case outlined in T308689 where there is no sticky header visible below desktop (1000px) view port.

hi @Jdlrobson cc @bwang -- thanks for the code review -- I met with Bernard to pick his brain about the accessibility and positioning issues around the new TOC icon. Based on that convo, I'm inclined with Bernard's advice to duplicate the TOC (option 1 from T307900#7921695) and try to leverage existing dropdown menu styles given the fragile CSS needed to position the button. Doing this will hopefully make CSS less brittle/error-prone and keep collapsible TOC keyboard accessible.

Do you have any concerns around that before I dive into refactoring the current patch?

Also adding this and sidebar main menu accessibility on SHDT agenda to discuss how we want to approach since it will continue to be an issue if/when we pursue floating main menu.

@cjming I just chatted with @Jdlrobson, and it sounds like we should go with the simplest solution for now in the interest of unblocking the TOC, i.e. going with your original approach of styling the original TOC element, and also adding an a button element before the h1. Jon also mentioned concerns about the duplicated ids, and that there might be a point later on where we can think of a better solution, i.e. using JS to move elements to the right location when needed.

Change 803580 had a related patch set uploaded (by Bernard Wang; author: Bernard Wang):

[mediawiki/skins/Vector@master] Collapse ToC into page title at narrow view ports

https://gerrit.wikimedia.org/r/803580

cjming assigned this task to bwang.

Change 803580 abandoned by Bernard Wang:

[mediawiki/skins/Vector@master] POC:Collapse ToC into page title at narrow view ports

Reason:

https://gerrit.wikimedia.org/r/803580

Change 794029 abandoned by Clare Ming:

[mediawiki/skins/Vector@master] Collapse ToC into page title at narrow view ports

Reason:

in favor of https://gerrit.wikimedia.org/r/c/mediawiki/skins/Vector/+/803941

https://gerrit.wikimedia.org/r/794029

Change 803941 had a related patch set uploaded (by Bernard Wang; author: Bernard Wang):

[mediawiki/skins/Vector@master] Collapse ToC into page title at narrow view ports with CSS/template changes only

https://gerrit.wikimedia.org/r/803941

Change 804652 had a related patch set uploaded (by Jdlrobson; author: Jdlrobson):

[mediawiki/skins/Vector@master] Cached CSS is no longer a problem

https://gerrit.wikimedia.org/r/804652

Change 804653 had a related patch set uploaded (by Jdlrobson; author: Jdlrobson):

[mediawiki/skins/Vector@master] Cached HTML is no longer a problem

https://gerrit.wikimedia.org/r/804653

Change 804656 had a related patch set uploaded (by Jdlrobson; author: Jdlrobson):

[mediawiki/skins/Vector@master] Disable table of contents toggle on VE activation

https://gerrit.wikimedia.org/r/804656

Change 803941 merged by jenkins-bot:

[mediawiki/skins/Vector@master] Collapse ToC into page title at narrow view ports with CSS/template changes only

https://gerrit.wikimedia.org/r/803941

Jdlrobson added a subscriber: Edtadros.

Alex this will be available shortly on the beta cluster. Please remember this is iterative so not complete work (the work to make it sticky for example is T308689). The current state is primarily an interim state to make sure there's some kind of access for narrow screens.

When done please move back to "doing" and unassign as we still have some work to do around accessibility.

Test wiki on Patch demo by CMing (WMF) using patch(es) linked to this task was deleted:

https://patchdemo.wmflabs.org/wikis/9b9fe58d2a/w/

Change 804656 merged by jenkins-bot:

[mediawiki/skins/Vector@master] Disable table of contents toggle on VE activation

https://gerrit.wikimedia.org/r/804656

this is looking great. two small things:

  1. could we offset the icon by ~10px so that the edge of it lines up with the edge of the container (when it isn't being hovered)?
currentoffset
Screen Shot 2022-06-13 at 12.49.39 PM.png (469×979 px, 230 KB)
Screen Shot 2022-06-13 at 12.52.53 PM.png (470×979 px, 233 KB)
  1. is it possible that when you click on a link the TOC menu/panel closes? currently it seems to stay open, so if you scroll back up to the top of the page after clicking on something you find it open:

Change 804621 had a related patch set uploaded (by Bernard Wang; author: Bernard Wang):

[mediawiki/skins/Vector@master] Add support for floating TOC lower down the page

https://gerrit.wikimedia.org/r/804621

hi @alexhollender_WMF

this is looking great. two small things:

  1. could we offset the icon by ~10px so that the edge of it lines up with the edge of the container (when it isn't being hovered)?

Sure - does that mean that you still want the TOC itself to vertically align with the edge of the icon on hover?

i.e. current

Screen Shot 2022-06-13 at 3.53.19 PM.png (1×1 px, 254 KB)

vs

margin-left: -10px

Screen Shot 2022-06-13 at 3.53.03 PM.png (770×1 px, 156 KB)

  1. is it possible that when you click on a link the TOC menu/panel closes? currently it seems to stay open, so if you scroll back up to the top of the page after clicking on something you find it open:

I need to dig into this -- I have a feeling this is on the complex side because current behavior is that when you click on a section, it brings you to that section (above desktop) with the TOC open. We want to preserve this behavior presumably above desktop but change it below desktop by checking view port and scroll position. I'm also unclear how we could make this work for no-js context.

Do you want TOC to automatically close when jumping to a section at all view ports below desktop regardless of scroll position?

@cjming

  1. thanks for asking about that detail. the menu should still be aligned with the button as it is currently:
defaulthoverclicked
image.png (656×896 px, 207 KB)
image.png (656×896 px, 207 KB)
image.png (656×896 px, 157 KB)

also you'll notice that i've added a small gap between the outline of the icon and the title so they are not touching as they are currently:

Screen Shot 2022-06-14 at 10.47.29 AM.png (77×99 px, 2 KB)

  1. the way i'm thinking about it is: if we're presenting the TOC in a menu/panel (which currently only happens below 1000px, but eventually will be possible even at larger screens), it should act as other menus do in the sense that if you open it up, then click on an item, the menu automatically closes. does that make sense? i don't think it's a high priority, so if it's complex we can definitely create a separate ticket and worry about it down the road.

thanks for the clarifications @alexhollender_WMF

  1. the way i'm thinking about it is: if we're presenting the TOC in a menu/panel (which currently only happens below 1000px, but eventually will be possible even at larger screens), it should act as other menus do in the sense that if you open it up, then click on an item, the menu automatically closes. does that make sense? i don't think it's a high priority, so if it's complex we can definitely create a separate ticket and worry about it down the road.

Makes sense -- it's more how things need to work in the interim state (i.e. until T307901 is completed wherein the collapsible TOC will be made available at all view ports) - the complexity lies in differentiating between above and below desktop, as well as between the js/no-js contexts. It might be worth separating that task out into its own (I haven't dug deep into what it would take to accomplish this) - but maybe/hopefully it will only be a temporary issue if T307901 gets resolved sooner than later.

cc @bwang -- maybe you have some thoughts about this?

Change 805411 had a related patch set uploaded (by Clare Ming; author: Clare Ming):

[mediawiki/skins/Vector@master] Minor adjustments to collapsible TOC

https://gerrit.wikimedia.org/r/805411

Test wiki created on Patch demo by CMing (WMF) using patch(es) linked to this task:
https://patchdemo.wmflabs.org/wikis/0f9ca956ca/w/

Test wiki on Patch demo by CMing (WMF) using patch(es) linked to this task was deleted:

https://patchdemo.wmflabs.org/wikis/0f9ca956ca/w/

Test wiki created on Patch demo by CMing (WMF) using patch(es) linked to this task:
https://patchdemo.wmflabs.org/wikis/423b7cbf7c/w/

hi @alexhollender_WMF I added a patch demo link to see if I got the minor adjustments right - please look at https://patchdemo.wmflabs.org/wikis/423b7cbf7c/wiki/Barack_Obama?useskin=vector-2022&tableofcontents=1 below desktop

When comparing to prototype, some of the vertical alignments seem slighty askew - is this ok?

protoype - note that the TOC vertically aligns with content

Screen Shot 2022-06-14 at 9.50.43 AM.png (1×1 px, 331 KB)

patchdemo with sidebar main menu nav closed

Screen Shot 2022-06-14 at 10.00.31 AM.png (1×1 px, 466 KB)

patchdemo with sidebar main menu nav open -- slight more noticeable

Screen Shot 2022-06-14 at 10.00.39 AM.png (1×1 px, 922 KB)

lmk if anything else needs adjusting re: your 1st feedback comment in T307900#7999651

@cjming thanks for the detailed comparison with the prototype — much appreciated. the patchdemo looks great all around. the only other change is adding a 4px gap between the icon and the page title:

currentupdated
image.png (212×352 px, 20 KB)
image.png (212×352 px, 20 KB)
cjming assigned this task to bwang.

Test wiki created on Patch demo by BWang (WMF) using patch(es) linked to this task:
https://patchdemo.wmflabs.org/wikis/2512e6ce25/w/

Test wiki on Patch demo by BWang (WMF) using patch(es) linked to this task was deleted:

https://patchdemo.wmflabs.org/wikis/2512e6ce25/w/

@alexhollender_WMF do you mind confirming if there should be a little space vertically between the TOC icon and the TOC like in the prototype?
Fwiw I think all the other dropdowns are flush -- tho the prototype looks like there's a little vertical space between them (looking at the user menu for example)

We had it flush between the hover state background border of the icon and the TOC but I might have misinterpreted your comment about having breathing room horizontally (between icon + title) vs vertically (between icon + toc)

Screen Shot 2022-06-14 at 3.09.01 PM.png (612×658 px, 81 KB)

  1. the way i'm thinking about it is: if we're presenting the TOC in a menu/panel (which currently only happens below 1000px, but eventually will be possible even at larger screens), it should act as other menus do in the sense that if you open it up, then click on an item, the menu automatically closes. does that make sense? i don't think it's a high priority, so if it's complex we can definitely create a separate ticket and worry about it down the road.

@cjming @alexhollender_WMF I think this is doable, my personal preference is for it to be tracked in a new task. I believe the TOC menu behaves differently because every other menu item is a link to a different page, which automatically closes the menu. TOC menu items stay on the same page, so we'd need some extra JS to handle this.

@alexhollender_WMF do you mind confirming if there should be a little space vertically between the TOC icon and the TOC like in the prototype?
Fwiw I think all the other dropdowns are flush -- tho the prototype looks like there's a little vertical space between them (looking at the user menu for example)

ah, my bad for not noticing that had changed. flush sounds good:

image.png (656×896 px, 157 KB)

Change 805411 merged by jenkins-bot:

[mediawiki/skins/Vector@master] Minor adjustments to collapsible TOC

https://gerrit.wikimedia.org/r/805411

Change 794029 restored by Bernard Wang:

[mediawiki/skins/Vector@master] Collapse ToC into page title at narrow view ports

https://gerrit.wikimedia.org/r/794029

Test wiki created on Patch demo by BWang (WMF) using patch(es) linked to this task:
https://patchdemo.wmflabs.org/wikis/747ae75d6e/w/

Change 794029 abandoned by Bernard Wang:

[mediawiki/skins/Vector@master] POC: Collapse ToC into page title at narrow view ports by duplicating TOC

Reason:

https://gerrit.wikimedia.org/r/794029

Change 804652 merged by jenkins-bot:

[mediawiki/skins/Vector@master] Cached CSS is no longer a problem

https://gerrit.wikimedia.org/r/804652

Change 804653 merged by jenkins-bot:

[mediawiki/skins/Vector@master] Table of contents: Cached HTML is no longer a problem

https://gerrit.wikimedia.org/r/804653

Change 807603 had a related patch set uploaded (by Clare Ming; author: Clare Ming):

[mediawiki/skins/Vector@master] Restore sticky header class

https://gerrit.wikimedia.org/r/807603

Test Result - Beta

Status:
Environment: beta
OS: macOS Monterey
Browser: Chrome
Device: MBP
Emulated Device:NA

Test Artifact(s):

QA Steps
  • Beta cluster link TK
  • ✅ AC1: Verify that above desktop (1000px) view port, sticky TOC behaves as it does currently on production.
    • Verified with sidebar collapsed, expanded, scrolling toc, non-scrolling toc, section "highlighting", clicking items, and expanding/collapsing sections, and visual similarity to Prod.
  • For the following use cases, see 1st 2 screenshots in T307900#7958897 :
    • Between tablet (720px) and desktop (1000px) view ports:
      • ✅ AC2: Verify that the collapsible TOC icon renders next to the page title when at the top of the page when the sidebar menu is open.
        Screen Shot 2022-06-26 at 2.59.52 PM.png (665×677 px, 160 KB)
      • ✅ AC3: Verify that the collapsible TOC icon renders next to the page title when at the top of the page when the sidebar menu is closed.
        Screen Shot 2022-06-26 at 3.01.02 PM.png (655×682 px, 145 KB)
      • ❌ AC4: Verify that clicking on the collapsible TOC icon next to page title opens the TOC as an overlay
        • The TOC does open as an overlay, but the button stays above the overlay and blocks a section. Additionally it covers a section of the TOC border.
          Screen Shot 2022-06-26 at 3.02.46 PM.png (776×669 px, 182 KB)
          Screen Shot 2022-06-26 at 3.02.37 PM.png (727×532 px, 143 KB)
      • ✅ AC5: Verify that clicking on a TOC section navigates the user to that section with the collapsed TOC icon sticky in the sidebar (for both sidebar menu expanded/collapsed states) will be addressed in T308689
        Screen Recording 2022-06-26 at 3.04.59 PM.mov.gif (998×984 px, 616 KB)
        Screen Recording 2022-06-26 at 3.06.09 PM.mov.gif (998×984 px, 734 KB)
      • Verify that the collapsible TOC icon is navigable via keyboard tabs:
        • ✅ AC6: Tabbing to TOC icon and hitting "Enter" will toggle the TOC open/closed{F35278121}
        • Tabbing to TOC icon, hitting "Enter" to open TOC, then tabbing to TOC section navigates user to that section.
    • Below tablet (720px) view port:
      • ✅ AC7: Verify above steps but note that sidebar menu collapses full width above main content so there is no expanded sidebar container state for the expanded/collapsed TOC.
        Screen Recording 2022-06-26 at 3.28.40 PM.mov.gif (998×680 px, 1 MB)
    • ❌ AC8: Repeat above steps for the no-js context - note that the TOC headings will not be collapsed.
>1000px<1000 >720<720
also validated scroll bar, not shown below
Screen Recording 2022-06-26 at 3.35.20 PM.mov.gif (526×638 px, 1 MB)
Button stays in place, has the same issue with the boder, Doesn't Expand/Collapse with keyboard. Scroll bar functions.
Screen Recording 2022-06-26 at 3.37.20 PM.mov.gif (826×436 px, 2 MB)
also validated scroll bar, not shown below
Screen Recording 2022-06-26 at 3.46.29 PM.mov.gif (826×436 px, 2 MB)
  • ✅ AC9 Cross-check in other supported browsers. -Validated safari and firefox

Those results look expected. The issue with the menu placement is tracked here: T311178, although it will likely be fixed by T311447