Add a new sidebar that groups the API Docs by purpose #403
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…ties required to generate the sidebar
This is a big work in progress hack; right now, the old sidebar is being replaced, but it’s done from the search control when it should be done from the main canjs.js file. Additionally, clicking on links in the sidebar from the homepage works, but reloading and using the sidebar doesn’t work (need to fix the link URLs). Overall, it’s pretty broken, but a step in the right direction.
Previously, when an AJAX request was made to get the page, the sidebar would be replaced with the sidebar in the requested page. Now, the new sidebar will not be replaced.
This is relevant in the Guides section, where @subchildren is used to make sure everything under “recipes” displays.
This is required for the current tests and makes it way easier to build new features.
…earch control This required making a method for getting the search map available from outside the search control.
Each item in the sidebar now has a `isCollapsible` property that controls whether the expand/collapse button should be shown for that item. The property is only true for the pages directly under the API Docs page. The `isCollapsed` property keeps track of whether an item is collapsed; by default, everything is collapsed; we’ll get to that in a minute. The `collapse` method flips `isCollapsed` to true or false. In addition to `unsortedChildren` and `sortedChildren`, the new `visibleChildren` property returns the list of children that should be shown, depending on whether the page is currently collapsed or not. If `isCollapsible` and `isCollapsed` are both true, then only Core collection modules are returned. By default, every page `isCollapsed`, but this is relevant to pages with `isCollapsible` because otherwise, `visibleChildren` will return all children.
…debar is clicked As the user navigates throughout the site via in-page links, the new sidebar updates its selection to match the page the user is on.
Some modules, like those under can-connect and can-util, have long names that are shortened to just the bare minimum.
When the user navigates to a page that’s under a collapsed section, the page’s `isCollapsed` property will be set to false, which will cause each parent to have its `isCollapsed` property set to false as well, thus expanding any section above the selected page.
Any section the user chooses to expand is persisted to localStorage. If a section is not expanded by the user, it won’t be persisted (e.g. when a user lands on a page that would otherwise be in a collapsed section).
There is now a lot more padding around the bottom, left, and right sides of the expand/collapse buttons. This makes them a much easier hit-target than they were before.
They’re now marked as toggle buttons with `aria-pressed` and have better labels with `aria-label`.
When the page first loads or the user clicks a link in the content, the sidebar will scroll to the selected page so that it’s visible. Closes #339
Links immediately under the button would cover up a lot of the button click area, so this makes them a more reasonable size and more balanced.
When a user clicks on a purpose group page (Observables, Views, etc.), the group should not automatically be expanded. Instead, it should remain however it currently is and the user should have the option to expand or collapse it if they want.
… had no visible children If the user selects a purpose group page (Observables, Views, etc.) that has no visible children (e.g. JS/DOM Utilities, Typed Data, etc.), it’s helpful to automatically expand the section so they can see packages underneath it.
…page with no visible children is selected If the user selects a purpose group page (Observables, Views, etc.) that has no visible children (e.g. JS/DOM Utilities, Typed Data, etc.), we automatically expand the section so they can see packages underneath it. When this is the case, we shouldn’t show the collapse button.
…be expanded When the user selects a Core package, the sidebar does not need to automatically expand the section that it’s in to show packages in other collections.
…expand/collapse button This fixes an issue where the expand/collapse button was disappearing when navigating to any docs under a package.
…he sidebar is first initialized Previously, when the sidebar was inserted into the DOM, the elements with the “unanimated” class would not have the correct height until two requestAnimationFrames. This fixes that by immediately causing them to have the “unanimated” class removed when the sidebar is inserted into the DOM.
- Change the button focus indicator to only show on keyboard nav in Chrome - Add more spacing between the purpose names (Observables, Views, etc.) and the collection names - Make the +/- buttons a consistent width - Remove unnecessary check for @hide (none of the pages will ever have it)
Also add compatibility with the collection names being prefixed with `can-`
…ption A style that was meant just for the navigation was also being applied to the search results.
Previously, when the user clicked on a collection title in the new sidebar, the sidebar would reset to showing nothing opened or selected. Now, it doesn’t collapse any sections and just shows the collection title as selected.
- Don’t force `white-space: nowrap` on every link in the sidebar - Widen the sidebar on mobile none of the longer module names are cut off - Make the + / - buttons larger - Remove uses of !important
The newly-inserted DOM elements will be animated from one max-width to another, roughly based on the width the sidebar displays when it’s fully collapsed vs. when it’s fully expanded. This animation isn’t really performant and could use some improvement.
chasenlehara
changed the title
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Part of canjs/canjs#3404