refactor(theme-common): allow optional desktopBreakpoint param in useWindowSize#9335
refactor(theme-common): allow optional desktopBreakpoint param in useWindowSize#9335slorber merged 16 commits intofacebook:mainfrom
Conversation
… fall back to 996
This reverts commit c629834.
✅ [V2]
To edit notification comments on pull requests, go to your Netlify site configuration. |
⚡️ Lighthouse report for the deploy preview of this PR
|
Josh-Cena
left a comment
Josh-Cena
left a comment
There was a problem hiding this comment.
One design suggestion. Otherwise I'm +1 on this. We would preferably also add some docs to the Swizzling page, explaining that you would need to keep this value in sync with custom CSS.
| * catch potential layout shifts, similar to strict mode calling effects twice. | ||
| */ | ||
| export function useWindowSize(): WindowSize { | ||
| export function useWindowSize(desktopThresholdWidth = 996): WindowSize { |
There was a problem hiding this comment.
Not fan of using a single arg there, please use a flexible object instead because we don't want to do a breaking change if we later introduce a new breakpoint some day or if you or someone else come with the need for 3 different sizes. If we add flexibility for your use case, let's make it flexible enough for other use cases as well.
This lib has a decent API to copy imho: https://github.com/iiroj/use-breakpoint
const BREAKPOINTS = { mobile: 0, tablet: 768, desktop: 1280 }
const CurrentBreakpoint = () => {
const { breakpoint, maxWidth, minWidth } = useBreakpoint(
BREAKPOINTS,
'desktop'
)
return <p>The current breakpoint is {breakpoint}!</p>
}(by the way you could as well use this lib directly in your code, similar behavior to what we implemented here).
| :::tip Customizing the breakpoint | ||
|
|
||
| Some React components, such as the header and the sidebar, implement different JavaScript logic when in mobile view by calling the [`useWindowSize`](./swizzling.mdx) hook. If you change the breakpoint value in your custom CSS, you probably also want to update the invocations of the `useWindowSize` hook by swizzling the components it's used in and passing an explicit option argument. For example, to change the breakpoint to 796px, pass the argument `796` to the `useWindowSize` hook. | ||
|
|
||
| ::: |
There was a problem hiding this comment.
@Josh-Cena to be honest I'm not sure we want to document this
@theme-common has many APIs and we only document a few ones that are meant to be used in userland explicitly. Even if this is considered "public API" and we want to avoid breaking changes on it, it doesn't mean we should document it IMHO.
If power users want to customize breakpoints and retro-engineer our helpers and want to use it, fine (although as I said you can provide your own code as well). But do we want to encourage usage, I'm not sure at all.
There was a problem hiding this comment.
If we mention customizing the CSS break point, we definitely need to mention customizing the JS break point. Users creating custom components (maybe through swizzling) always need to know both.
Josh-Cena
changed the title
|
Commenting to add myself as follower.
Side Note: I briefly played around with swizzling, but couldn't find a way to prevent mobile view from hiding the right side ToC of docs. I'm guessing this MR would make it easier to prevent the mobile view from taking effect (personally I wish mobile view could be turned off, as I think it'd improve consistency.) @hammerofthor8 of the previous PR also seemed interested in it. |
|
What matters slightly more is the physical width, not the pixel width—the former is what the user actually perceives. Even for a phone screen in landscape, the screen is not wide enough unless you have a phone that's 20cm long. Therefore I suspect if you use the desktop layout the items are going to either be too cramped or too small. I could be wrong, though, and I'm happy to see what it actually looks like on a phone. |
|
@Josh-Cena docusaurus's desktop view looks great on mobile! / far better than the Mobile UX in my opinion. Here's some screenshots of a Work in Progress Website from My Phone:
Btw here's a screenshot I've been tentatively planning to add to my site: |
|
Our biggest worry is that the navbar doesn't look good, as your example has already shown. We purposedly set the breakpoint to a very large number (most style frameworks use 768px instead), because for typical numbers of navbar items, the items would already get wrapped below 1000px and it's not easy to lay them out nicely. |
|
Josh, Thanks for offering background contextual explanation, and reading about my use case that aligns with the OP's. I think I get your reasoning, and that'd be solid reason to keep the defaults as they currently are. (I was playing around with CSS overrides earlier today I saw an interesting text overlap scenario that made me think that's why I saw a lot of spare white space in some places, so I think I have some understanding of what you mean.) (This merge requests seems to be helping to work towards making that a configurable value, and in case of the rough spots I think you're pointing out (menu text wrapping / not easy to layout nicely), I'd be able to do things like cut down on menu items, shorten menu names to single words, replace menu text with images, and manually QA edge case UI oddities.) |
|
I definitely have no intention to prevent this from being merged :) |
5 participants
Pre-flight checklist
Motivation
The
desktopThresholdWidthin theuseWindowSizehook is currently hardcoded at 996px. This makes it impossible to customize the breakpoint for the navbar, which creates inconsistencies when other CSS media query breakpoints are customized for the rest of the site.This change allows for customization of that value by allowing for an optional
desktopThresholdWidthparameter to be passed to theuseWindowSizehook. If none is provided, the original 996px value is used.Test Plan
Test links
Deploy preview: https://deploy-preview-_____--docusaurus-2.netlify.app/
Related issues/PRs
Discussed previously in #9261, decided on a simpler implementation with a smaller footprint.