Flow/Table of Contents spec

Spec for the new Table of Contents on a Flow board. Last updated Nov 24, 2014.

Use case and rationale
The core use case for Table of Contents on a Flow board is:


 * A user comes to a Flow board, and wants to browse through the list of topics, to find an interesting discussion to read and/or participate in.


 * Related use case: A user is searching for a particular discussion that's on the board. The Table of Contents may help with this, if the user can find the discussion by browsing topic titles. A more specific Search feature will be added after the ToC is done.

Header bar with ToC dropdown



 * The header bar at the top of a Flow board will now include an icon and "Browse topics" area on the left side, and the sorting will move to the right side.


 * Note: The "collapse" icon will no longer appear on the board, and the collapse functionality will be retired.

Opening the ToC dropdown



 * Clicking on the TOC icon or the "Browse topics" text opens the ToC dropdown panel. The panel is 85vh.


 * The panel includes the list of topics on the board, in the order of the user's current sort.


 * The panel has a vertical scroll bar, and the user will be able to scroll through the list of topics.


 * If a topic is too long to fit in the panel, the text is cut off with an ellipsis after the last complete word.


 * If the user clicks outside of the panel, the dropdown is dismissed.

Scrolling with the fixed header bar



 * As the user scrolls down the page, the header bar sticks at the top of the browser window.


 * The sorting dropdown goes away (to give more space to the title).


 * The text "Browse topics" is replaced by the title of the topic currently being scrolled through. The topic title is in bold.


 * If the topic title is too long to fit horizontally on the header bar, the text is cut off with an ellipsis after the last complete word.


 * As the user scrolls down, the topic title displayed should change as the header bar touches the top of each topic titlebar.


 * As the user scrolls up, the topic title displayed should change as the header bar clears the top of each topic titlebar.


 * When the user scrolls to the top of the page and the header bar detaches from the top of the browser window, the text should revert back to "Browse topics".

Opening the contents dropdown from lower on the page



 * When the user clicks on the topic title displayed in the header bar (or the TOC icon), the ToC dropdown opens.


 * The panel should be the same horizontal size as it was above. It should still have the list of topics and the scroll bar.


 * The topic that the user is currently on is still rendered as bold and black, as it was before the panel was opened.


 * The user can scroll up or down to see more topic titles on the page. As the user scrolls, the topic that the user is currently on should stay rendered as bold and black, to indicate that that's where the user is currently located on the page.

Clicking on a topic title



 * When the user clicks on a topic title in the Table of Contents list, the user is scrolled to the appropriate spot on the board (just above the topic titlebar).


 * The ToC panel closes, and the user can read the discussion.


 * The appropriate topic title is displayed in the header bar, as before.

Clicking on a title that's within the next set of topics to load

 * When the user clicks on a topic title that's <10 topics below the currently displayed topics, the page loads the next 10 topics (as it would normally if the user scrolled to the bottom). The user is scrolled to the appropriate topic.

Clicking on a title that's beyond the next set of topics to load



 * When the user clicks on a topic title that's >10 topics below the currently displayed topics, the page loads the set of 10 topics that includes the selected topic, and scrolls the user to the appropriate topic.


 * In the space above the newly-loaded topics, there's a "condensed" box that indicates the number of topics skipped between the end of the previous display and the topic that the user has just loaded.
 * The condensed box has a button to load 10 of the skipped topics "above" the topic -- example: 100 skipped topics (Load 10)


 * When the user clicks on Load 10, the new 10 topics load. The new 10 that load pushes the topic I can see on the page down, and you see a [90 skipped [load 10]] bar in place of the old one you just clicked.


 * If the user opens the ToC again and chooses a topic that's within the condensed topics, then that group of 10 topics will load, possibly creating multiple condensed boxes on the page.

Retiring the Collapse feature
With the new ToC change, the "collapse" feature will be retired.


 * The collapse icon will be taken out of the header bar.


 * Topics will not collapse if the user clicks on the topic titlebar.


 * When the user hovers over the topic titlebar, the "shadow" will not appear on the sides or the bottom of the titlebar.


 * Anything that keeps track of preferences related to collapsed states can be removed.

Questions

 * Mobile? Do we have the floating ToC bar as you scroll down?


 * Monobook?


 * No-JS?


 * Do we know the number of topics?


 * What is the limit of the number of titles that we load? When it gets beyond (let's say) 1,000, do we need to have a "lazy load" in the ToC? Would anybody actually scroll through 1,000 items anyway?


 * When the ToC panel is open, can you scroll the page behind it? What happens in the ToC if you do?


 * Sub-sections/sub-headers? (notes at https://trello.com/c/b1yETj6R/ )


 * Numbering? (For users using the "New topics" sort-order, it's useful to be able to count "the number of new topics since I last looked at this board". Eg. If I post a question at Help:Foo, and when I come back one day later I see that 25 topics have been posted since then, I gain an understanding of how active the page is.)