Feature suggestion: Add scrollbar to left nav area in API reference

[sethladd]

From @Kbhredsox on March 9, 2017 3:47

Overview

On some of the Flutter API reference pages, the left nav is much taller than the main content area yet doesn't contain any sort of sub-element scrolling capabilities. As a result, the page's scrollable area includes this (much longer) left nav, falsely implying to readers that the page is very long (and therefore should only be skimmed :P).

Suggestion: Use a scrollable left nav area, as the Android API reference does; for example:
https://developer.android.com/reference/android/app/usage/package-summary.html

Steps to Reproduce

1. Navigate to https://docs.flutter.io/flutter/widgets/Align-class.html.
2. Scroll down toward the bottom of the page.
3. ! Notice that the left nav content continues long after the main content area's bottom edge.

Copied from original issue: flutter/flutter#8671

[sethladd]

@devoncarew @jcollins-g I mocked it up here: https://gist.github.com/sethladd/6e7f0721144e444f4d894865c8de54d2

It's self-contained, you can download it and load it up. Thoughts?

Notes:

• Eliminates a lot of bootstrap's rows, containers, and columns
• Doesn't yet implement the responsive slide-in nav, but I built this in a way where that will work once we add the JS
• All three columns (left, center, right) can scroll independently
• None of the padding is tweaked, of course. That's easy to add back in :)

Thoughts?

If you like this, I can merge it into dartdoc proper and make the cool slide-in nav work on narrow screens. We wouldn't need bootstrap anymore, as far as I could tell, which I presume would be a win.

[sethladd]

[jcollins-g]

This is interesting enough I'd like to see a merged dartdoc version, assuming we can find some way to do the disappearing scrollbar thing that seems to be all the rage, like the sidebar here: https://www.dartlang.org/guides/language

[sethladd]

Did you download the HTML file and try different screen sizes? It's only mostly responsive, but hopefully you'll get the idea.

The scrollbars only appear when content is too large for the area.

Also, are you and @devoncarew OK if we remove bootstrap? I think that would be a natural outcome from this work.

[devoncarew]

Yeah, no particular attachment to bootstrap here. I believe bootstrap uses normalize.css to reset browser styles - we'd probably want to do the same.

My main concerns are that we look similar to dartlang.org when generating for api.dartlang.org (the default styles), and look similar to flutter.io when generating for docs.flutter.io. dartlang.org has a nice column system (visible here https://www.dartlang.org/guides/testing) - we don't need to use their same css, but we'll want to work towards looking and acting similar. The general nav layout you have above looks good :)

[sethladd]

The general nav layout you have above looks good

OK, so what I'm hearing is that you're OK with:

• three column layout
• not necessarily based on bootstrap
• independently scrollable columns
• able to be styled closely with dartlang.org and flutter.io (don't impose restrictive style constraints with a new layout)
• solution for resetting styles

I can do that with the structure and layout above :)

It's going to be non-trivial to make this work in dartdoc, so I want to be double-sure yall are comfortable with this :)

Happy to help, thanks!

[sethladd]

Update!

w/ flexbox and scrolling:

current:

Very minimal changes required:

• About 4 small edits to styles.css
• Additional block of styles from the https://gist.github.com/sethladd/6e7f0721144e444f4d894865c8de54d2 examples
• A few padding tweaks to match current style

Note: the scrollbars are styled now.

TODO: style tweaks because we lost bootstrap (e.g. the dd margin-left needs to be set to zero. The normalize.css might do that.)

Thoughts? Should I go ahead and create a PR? Or, are there concerns?

[jcollins-g]

The screenshots look generally good -- I'd really like to see a complex package with this style serving somewhere so I can see how navigation and browsing really works. That'll help us figure out if we're on the right track.

[sethladd]

Hopefully, there's no impact on navigation (page structure is untouched, same pages in same locations). But sounds like you're ready for the PR. Can do.

[sethladd]

Example here: https://sethladd.github.io/test-dartdoc-flexbox/

Diff here: #1452

If you approve, I'll finish fixing the small style bugs (that shouldn't affect your eval of the navigation).

[devoncarew]

I like the responsiveness! Does it lose the right-hand column near the same place as dartlang.org? I seemed like I had to make it pretty narrow to go down to lose the right column.

I would not use a colored background for the scroll bars. It adds a solid divider between the sections, where we're probably better off just using padding.

[sethladd]

Does it lose the right-hand column near the same place as dartlang.org?

It should. I didn't change any of that CSS.

I would not use a colored background for the scroll bars.

I assume you mean the bar itself, not the scroller ?

[devoncarew]

I think it's the scrollbar track color (::-webkit-scrollbar-track):

[sethladd]

Got it, can do!

[jcollins-g]

I'm not thrilled about the black copyright bar always being visible, it'd be nice if when you scroll down it becomes visible somewhat like the one on this page does:

https://www.dartlang.org/guides/get-started

However, my eyes are drawn to what annoys me, and the important bit is I'm much less annoyed with this layout and scroll navigation than the old one! Thanks! (I presume things like the white border around the search box are part of the small style fixes you mentioned).

[sethladd]

I'm not thrilled about the black copyright bar always being visible, it'd be nice if when you scroll down it becomes visible somewhat like the one on this page does

Frankly, I don't know how to do what you want. :/ . I, too, would love to solve that.

However, we don't need to make it black :)

I presume things like the white border around the search box are part of the small style fixes you mentioned

Yup! That's a weird one...

[sethladd]

@devoncarew what's the intention of the "property actions" text on the far right? This is the current design:

Should I keep that there?

[sethladd]

@devoncarew @jcollins-g the PR is updated, and the staged example is uploaded. PTAL, thanks!

[devoncarew]

That is the parent name of the content on the right hand side. So the element type is 'property' and the name is 'actions'. It look better w/ content in there, like for a class page.

There's an issue about refactoring our page titles a bit to better emphasize the current element (#1441).

[jcollins-g]

New staging area looks great. There are little things that I now realize I want (keeping the scroll position of the left hand side somehow when jumping between pages) but all that is icing. You've got a great cake here. LGTM.

[sethladd]

keeping the scroll position of the left hand side somehow when jumping between pages

whoa, I'm not sure how to do that :)