docs(Drawer): add API decision #2009
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,147 @@ | ||
| # Drawer | ||
|
|
||
| A drawer is a panel that slides in mostly from right side of the screen over the existing content in the viewport. It helps in providing additional details or context and can also be used to promote product features or new products. | ||
|
|
||
| <img width="500px" src="./2024-02-07-20-04-07.png" alt="Drawer Figma Skeleton"> | ||
|
|
||
| ## Design | ||
|
There was a problem hiding this comment. Will Drawer be absolute positioned always? What if it needs to be used as a left/right navigation drawer? There was a problem hiding this comment. It will be fixed positioned on top right. It is always positioned like navigation drawer There was a problem hiding this comment. So we are setting a default position for Drawers on the top-right across all products? Like we set There was a problem hiding this comment. There are use-cases where drawer is used for navigation on left side in a lot of apps. Won't that ever be a use-case for us? There was a problem hiding this comment.
Nope. So for desktop, our navigation bar itself is on left so there won't be anything opening from that side. On mobile too we have drawers opening from right side only. Plus navigation component is something that we might tackle separately. This navigation component will use our Drawer internally on mobile. So at that time we can relook at this. Anyway even if usecase comes up, its just addition of new prop so not much effort and no breaking change |
||
|
|
||
| - [Drawer - Figma Design](https://www.figma.com/file/jubmQL9Z8V7881ayUD95ps/Blade-DSL?node-id=78667%3A66663&mode=dev) | ||
|
There was a problem hiding this comment. Does the drawer have a fixed width? Will the width change based on the content? If it is fixed width, why do we not have size options? There was a problem hiding this comment. It currently has a fixed max-width of 420px and inside that it takes width based on the content. Let me check with design once if we want to go with max-width or defined size because in Modal I see its defined size There was a problem hiding this comment. Just checked with RK. It is fixed width of 420px on desktop always. We will only support one size right now There was a problem hiding this comment.
There was a problem hiding this comment. nope. Drawer is always 420px irrespective of the content. |
||
|
|
||
| ## Proposed API | ||
|
|
||
| ```jsx | ||
| <Drawer | ||
| isOpen={} | ||
| onDismiss={() => {}} | ||
| showOverlay | ||
| > | ||
| <DrawerHeader | ||
Rozamo marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| title="" | ||
| subtitle="" | ||
| leading={<DrawerHeaderIcon />} | ||
| titleSuffix={<DrawerHeaderBadge />} | ||
| trailing={ | ||
| <> | ||
| <DrawerHeaderLink /> | ||
| <DrawerHeaderButton /> | ||
| </> | ||
| } | ||
| /> | ||
| <DrawerBody> | ||
| <Slot /> | ||
| </DrawerBody> | ||
|
|
||
| <Drawer> | ||
| ``` | ||
|
|
||
| <details> | ||
| <summary><b>Full Usage Example</b></summary> | ||
|
|
||
| ```jsx | ||
| const MyCuteDrawer = () => { | ||
| const [showDrawer, setShowDrawer] = React.useState(false); | ||
| return ( | ||
| <Box> | ||
| <Button onClick={() => setShowDrawer(true)}>Open Drawer</Button> | ||
| <Drawer | ||
| isOpen={showDrawer} | ||
| onDismiss={() => { | ||
| setShowDrawer(false); | ||
| }} | ||
| > | ||
| <DrawerHeader | ||
| title="Announcements" | ||
| /> | ||
| <DrawerBody> | ||
| <FTXAnnouncement /> | ||
| <RazorpayOnePromotions /> | ||
| <CatPictures /> | ||
| </DrawerBody> | ||
| <Drawer> | ||
| </Box> | ||
| ) | ||
| } | ||
|
|
||
| ``` | ||
|
|
||
| </details> | ||
|
|
||
| ### Props | ||
|
|
||
| ```ts | ||
| type DrawerProps = { | ||
| /** | ||
| * Controlled state of drawer open or not | ||
| */ | ||
| isOpen: boolean; | ||
|
There was a problem hiding this comment. What happens if multiple drawers are opened together? I'm guessing same behaviour as Modal? There was a problem hiding this comment. Yes similar but only 2 drawers can be kept open at once from design-side. And the 2nd drawer has a back button instead of close button. Let me add the stacking behaviour to this API doc I didn't mention it in this There was a problem hiding this comment. Would we need a separate callback for the back button? There was a problem hiding this comment. back button is just dismiss of 2nd Drawer. Consumer knows which is their second drawer so they can use that |
||
|
|
||
| /** | ||
| * Dismiss handler | ||
| */ | ||
| onDismiss: () => void; | ||
|
|
||
| /** | ||
| * Show or hide overlay. | ||
| * | ||
| * Also decides if clicking outside on overlay closes the drawer or not | ||
|
There was a problem hiding this comment. Wont there ever be a possibility where overlay isn't needed but click outside still needs to close the drawer? There was a problem hiding this comment. no I did ask this to designers. If someone wants clicking outside to close drawer, they should always have overlay There was a problem hiding this comment.
I feel we should have a separate prop for deciding this, it shouldn't be dependant on the presence of overlay. There was a problem hiding this comment. you mean for a usecase where someone doesn't want to show overlay but still want to close Drawer on clicking outside? I can confirm this once with design if this should be possible. Ideally overlay should be present in most cases except few exceptional cases where outer items have to be interactive There was a problem hiding this comment. I would also vote for the separation of the logic to dismiss the overlay items on click outside on a different prop. If Modal and BottomSheet have a prop tomorrow to disable dismiss on click outside on the overlay the same prop should be extended over here. There was a problem hiding this comment. Agreed. Better to have a separate prop since we might be adding the same to Modal & BottomSheet too There was a problem hiding this comment. Modal and BottomSheet would anyway have different prop than Drawer in this particular case no? E.g. in Modal and BottomSheet, we always want to show overlay so there will never be a If we're having that prop and we know interactions outside have to be consistent with display of overlay, wouldn't adding new prop be extra overhead for consumers here? Because if we add 2 props, it creates impossible states of <>
<Drawer
showOverlay={true}
shouldDismissOnOutsideClick={false}
/>
<Drawer
showOverlay={false}
shouldDismissOnOutsideClick={true}
/>
</>These scenarios should throw error in 2 props case because its not correct usage from UX perspective There was a problem hiding this comment. Oh anyway just discussed this with design - https://razorpay.slack.com/archives/G01B3LQ9H0W/p1707808893726369 Usecase that we have on Modal is something that we would have it here as well. I'll make changes to add 2 props. |
||
| */ | ||
| showOverlay?: boolean; | ||
|
There was a problem hiding this comment. So overlay is optional? Won't that look weird? What is the use case? There was a problem hiding this comment. We have usecases where Drawer is used for Announcements. In those cases, users should still be able to interact with dashboard items even with Drawer open so we cant show overlay or hide drawer on clicking outside. 
There was a problem hiding this comment. when overlay is disabled, does the area outside the drawer remain interactive? There was a problem hiding this comment.
We should ideally control this with a new prop like
Rozamo marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| }; | ||
|
|
||
| type DrawerHeaderProps = { | ||
| /** | ||
| * Title of the Drawer | ||
| */ | ||
| title: string; | ||
|
|
||
| /** | ||
| * Subtitle of the Drawer | ||
| */ | ||
| subtitle?: string; | ||
|
|
||
| /** | ||
| * Leading element | ||
| * | ||
| * DrawerHeaderIcon or DrawerHeaderAsset | ||
| */ | ||
| leading?: ReactNode; | ||
|
|
||
| /** | ||
| * Title suffix element | ||
| * | ||
| * DrawerHeaderBadge | ||
| */ | ||
| titleSuffix?: ReactNode; | ||
|
|
||
| /** | ||
| * Title trailing element | ||
| * | ||
| * DrawerHeaderLink, DrawerHeaderButton[] | ||
| */ | ||
| trailing?: ReactNode; | ||
| }; | ||
| ``` | ||
|
|
||
| Other supporting wrapper components for trailing and leading space- | ||
|
|
||
| - DrawerHeaderBadge | ||
| - DrawerHeaderIcon | ||
| - DrawerHeaderAsset | ||
| - DrawerHeaderLink | ||
| - DrawerHeaderButton | ||
|
There was a problem hiding this comment. We keep creating these components for multiple components... Modal, Bottomsheet, Drawer. We might need to look into changing these into just There was a problem hiding this comment. true. There was a problem hiding this comment. How are these components different from normal There was a problem hiding this comment. These subcomponents usually have defined defaults that are different from defaults of actual component. E.g. However in some examples like CardHeaderBadge, the defaults of wrapper are same as defaults of actual component. There it is just for consistency in API otherwise some components will be like |
||
|
|
||
| _No alternate APIs were considered because Drawer is closer to Modal on overall meaning and API perspective so made sense to go with API that is closer to Modal, also all DS Drawer components I referenced have similar API_ | ||
|
|
||
| ## Accessibility | ||
|
|
||
| - **Aria Attributes:** Drawer will have `aria-modal="true"` and `role="dialog"` and will be treated as modal for voiceover users. | ||
| - **Focus Handling:** Ensure Close Icon is focussable | ||
|
There was a problem hiding this comment. Like Modal & Bottomsheet, should we also expose i There was a problem hiding this comment. Yes I think we should. Drawer will also have similar usecases like Modal and BottomSheet so requirement will anyway come There was a problem hiding this comment. Add keyboard handling details, e.g, |
||
|
|
||
| Will work in a similar manner as [Ant Design - Drawer](https://ant.design/components/drawer) | ||
|
|
||
| ## References | ||
|
|
||
| - https://atlassian.design/components/drawer/examples | ||
| - https://ant.design/components/drawer | ||
|
|
||
| ## Open Questions | ||
Uh oh!
There was an error while loading. Please reload this page.