[layouts] Updates PageLayout to be main controller for layouts

[katydecorah]

This branch merges into layouts-main.

To do:

• Fix catalog site
• Add Topbar/Sticker and all code to generate the main navigation (ProductMenu, TabList, Search).
• Add Feedback by default with a frontMatter option hideFeedback: true to disable it on a given page.
• [] Add user context: This has been moved to Create Context; Make contextless components contextfull #315 and is now a stretch goal of this sprint.
  • UserAccessToken - for adding to code examples
  • UserName - for adding to code examples
  • UserPreferredLanguage - for iOS and Android code toggles
• Add an ErrorBoundary to better catch errors. Ref [layouts] Add ErrorBoundary component #272
• Add BackTopButton
• Add appendTabList prop to append a custom dropdown to TabList.
• Add documentation page in catalog site

How to test

QA checklist

• No errors logged to console.
• Accessibility score in Chrome DevTools Audit/Lighthouse is 100% with Lighthouse version: 6.0.0.
  • Score is 83 since PageLayout test case is duplicating views it's catching ids that are not unique. It's also picking up Improve color contrast of Feedback component #257 and NavigationDropdown, SectionedNavigation - Form elements do not have associated labels #248
• Component is accessible at mobile-size viewport.
• Component is accessible at tablet-size viewport.
• Component is accessible at laptop-size viewport.
• Component is accessible at big-monitor-size viewport.
• Create a PR in a site repo, copy the component, and test it. Push to staging and let the reviewer know they can also test the component there.

Open the test cases app locally on:

• Chrome, no errors logged to console.
• Firefox, no errors logged to console.
• Safari, no errors logged to console.
• Edge, no errors logged to console.
• IE11, no errors logged to console.
• Mobile Safari, no errors logged to console.
• Android Chrome, no errors logged to console.

[katydecorah]

@colleenmcginnis Ready for review 😅 .

A few notes

• Created a dr-ui beta release and tested in the following repos:
  • https://github.com/mapbox/android-docs/pull/1462 (multi-structure)
  • https://github.com/mapbox/geographic-analytics/pull/31 (common use case)
  • https://github.com/mapbox/api-documentation/pull/986 (split page pattern)
  • https://github.com/mapbox/docs-starter-kit/pull/41
  • https://github.com/mapbox/mapbox-gl-js-docs/pull/383 (advanced usage, custom sidebars)
  • https://github.com/mapbox/account-docs/pull/133 (split page pattern)
  • https://github.com/mapbox/help/pull/2722 (advanced usage, noShellHeaderBuffer for custom header)
• Created remark-lint-mapbox (ref https://github.com/mapbox/remark-lint-mapbox/pull/49 ) beta release and updated each testing PR so we can test out the new rules.
• The PageLayout guide doesn't feel complete yet and think we can and should continue to update it as we roll out. I think we'll be able to better documentation special use cases. I'm curious what you feel is lacking.
• While the UI changes should be minimal (you may notice slight padding adjustments), I think we should discontinue the sidebar title:

I've found that the implementation of the sidebar title has been inconsistent across sites (some sites use it, others don't). I think that the sidebar title adds repetition to the page as it's often the same name as its respective top nav tav navigation item.

If you feel strongly that we should keep it, let me know and I can make it happen.

How to review

In addition to this PR, you can also:

• View the tests cases /PageLayout (npm start)
• View the PageLayout component in the catalog page (/dr-ui/#pagelayout) and PageLayout guide (/dr-ui/guides/page-layout/) (npm run start-docs)
• View PRs: https://github.com/mapbox/android-docs/pull/1462 , https://github.com/mapbox/geographic-analytics/pull/31 , and https://github.com/mapbox/api-documentation/pull/986 for implementation details.

[colleenmcginnis]

Wow @katydecorah. This is incredible!

The PageLayout guide doesn't feel complete yet and think we can and should continue to update it as we roll out. I think we'll be able to better documentation special use cases. I'm curious what you feel is lacking.

I agree! For me the two hardest concepts to wrap my head around (when attempting to unlearn what I already know about our sites) are multi-level (or multi-structured) sites and the difference between navOrder and order (which relies on a common understand of what "top level navigation" means). We should think about adding more examples to the language about these terms. I think we should also consider more consistently linking back to the components tab when we mention specific components in the guides.

If you feel strongly that we should keep it [sidebar titles], let me know and I can make it happen.

I do not feel strongly!

I left some other minor comments and questions below, but the overall approach here is wonderful. I love the separation of structure (in the components) and logic (in the helper functions). ❤️

[colleenmcginnis]

Are you planning to expand on this as we prep for the rollout?

[katydecorah]

Yes! I wanted to wait for a full list of breaking changes.

[katydecorah]

For me the two hardest concepts to wrap my head around (when attempting to unlearn what I already know about our sites) are multi-level (or multi-structured) sites and the difference between navOrder and order (which relies on a common understand of what "top level navigation" means). We should think about adding more examples to the language about these terms. I think we should also consider more consistently linking back to the components tab when we mention specific components in the guides.

@colleenmcginnis This is really helpful feedback! I'll work to add more about each concept. I'll also look for more linking opportunities.

[katydecorah]

@colleenmcginnis thanks again for your thorough review and notes.

Here a few commits to address your specific comments:

• Adds a guide to creating a multi-structured site 598c1a2
• Reworks "Top level navigation" into "Navigation bar" and expands on the concept: 138583f
• Adds note to distinguish navOrder and order and documents order: 6befc9e
• Linked back to components: d0e5ad8

Ready for review!

[colleenmcginnis]

👩‍🍳 😚 Looks great @katydecorah! I made just a few v small suggestions below.

I love the new guide on multi-structured sites. Good timing with the work you're doing with the data services docs. 🥂