docs(drawer): Add docs on the site (#1956)

vtex · Sep 20, 2024 · f98ada8 · f98ada8
2 parents d2696ba + 5c9342e
commit f98ada8
Show file tree

Hide file tree

Showing 22 changed files with 368 additions and 47 deletions.
diff --git a/packages/docs/examples/drawer-controlled.tsx b/packages/docs/examples/drawer-controlled.tsx
@@ -0,0 +1,64 @@
+import {
+  DrawerProvider,
+  Button,
+  DrawerPopover,
+  DrawerHeader,
+  DrawerHeading,
+  DrawerDismiss,
+  DrawerContent,
+  DrawerFooter,
+} from '@vtex/shoreline'
+import { DecorativeBox } from '../components/decorative-box'
+import { useState } from 'react'
+
+export default function Example() {
+  const [open, setOpen] = useState(false)
+  const [loading, setLoading] = useState(false)
+
+  async function someServerAction() {
+    if (open) {
+      setOpen(false)
+
+      return
+    }
+
+    setLoading(true)
+
+    // This promise simulates a call to an API.
+    // Using the controlled apporach of the Drawer
+    // is particullary useful in programmatic dispatch scenarios.
+    await new Promise((resolve) => {
+      setTimeout(resolve, 3000)
+    })
+
+    setLoading(false)
+    setOpen(true)
+  }
+
+  return (
+    <>
+      <Button loading={loading} onClick={someServerAction}>
+        Some action
+      </Button>
+      <DrawerProvider open={open} onOpenChange={setOpen}>
+        <DrawerPopover>
+          <DrawerHeader>
+            <DrawerHeading>Controlled Drawer</DrawerHeading>
+            <DrawerDismiss />
+          </DrawerHeader>
+          <DrawerContent>
+            <DecorativeBox height="32rem" color="blue" />
+          </DrawerContent>
+          <DrawerFooter>
+            <Button onClick={() => null} size="large">
+              Label
+            </Button>
+            <Button variant="primary" onClick={() => null} size="large">
+              Label
+            </Button>
+          </DrawerFooter>
+        </DrawerPopover>
+      </DrawerProvider>
+    </>
+  )
+}
diff --git a/packages/docs/examples/drawer-long-content.tsx b/packages/docs/examples/drawer-long-content.tsx
@@ -0,0 +1,39 @@
+import {
+  DrawerProvider,
+  DrawerTrigger,
+  Button,
+  DrawerPopover,
+  DrawerHeader,
+  DrawerHeading,
+  DrawerDismiss,
+  DrawerContent,
+  DrawerFooter,
+} from '@vtex/shoreline'
+import { DecorativeBox } from '../components/decorative-box'
+
+export default function Example() {
+  return (
+    <DrawerProvider>
+      <DrawerTrigger asChild>
+        <Button>Open</Button>
+      </DrawerTrigger>
+      <DrawerPopover>
+        <DrawerHeader>
+          <DrawerHeading>Drawer Heading</DrawerHeading>
+          <DrawerDismiss />
+        </DrawerHeader>
+        <DrawerContent>
+          <DecorativeBox height="100rem" color="blue" />
+        </DrawerContent>
+        <DrawerFooter>
+          <Button onClick={() => null} size="large">
+            Label
+          </Button>
+          <Button variant="primary" onClick={() => null} size="large">
+            Label
+          </Button>
+        </DrawerFooter>
+      </DrawerPopover>
+    </DrawerProvider>
+  )
+}
diff --git a/packages/docs/examples/drawer-small.tsx b/packages/docs/examples/drawer-small.tsx
@@ -0,0 +1,39 @@
+import {
+  DrawerProvider,
+  DrawerTrigger,
+  Button,
+  DrawerPopover,
+  DrawerHeader,
+  DrawerHeading,
+  DrawerDismiss,
+  DrawerContent,
+  DrawerFooter,
+} from '@vtex/shoreline'
+import { DecorativeBox } from '../components/decorative-box'
+
+export default function Example() {
+  return (
+    <DrawerProvider>
+      <DrawerTrigger asChild>
+        <Button>Open small drawer</Button>
+      </DrawerTrigger>
+      <DrawerPopover size="small">
+        <DrawerHeader>
+          <DrawerHeading>Small Drawer</DrawerHeading>
+          <DrawerDismiss />
+        </DrawerHeader>
+        <DrawerContent>
+          <DecorativeBox height="20rem" color="blue" />
+        </DrawerContent>
+        <DrawerFooter>
+          <Button onClick={() => null} size="large">
+            Label
+          </Button>
+          <Button variant="primary" onClick={() => null} size="large">
+            Label
+          </Button>
+        </DrawerFooter>
+      </DrawerPopover>
+    </DrawerProvider>
+  )
+}
diff --git a/packages/docs/examples/drawer.tsx b/packages/docs/examples/drawer.tsx
@@ -15,15 +15,15 @@ export default function Example() {
   return (
     <DrawerProvider>
       <DrawerTrigger asChild>
-        <Button variant="primary">Open</Button>
+        <Button>Open</Button>
       </DrawerTrigger>
-      <DrawerPopover size="medium">
+      <DrawerPopover>
         <DrawerHeader>
           <DrawerHeading>Drawer Heading</DrawerHeading>
           <DrawerDismiss />
         </DrawerHeader>
         <DrawerContent>
-          <DecorativeBox height="500px" color="blue" />
+          <DecorativeBox height="20rem" color="blue" />
         </DrawerContent>
         <DrawerFooter>
           <Button onClick={() => null} size="large">

diff --git a/packages/docs/pages/components/drawer.mdx b/packages/docs/pages/components/drawer.mdx
@@ -1,20 +1,82 @@
 # Drawer
 
-Comming soon
-
-{/* <ComponentDescription name="drawer-provider" />
+<ComponentDescription>Drawer displays content related to a minor job within a page's main job. It does not block interactions outside the overlay, allowing users to interact with content.</ComponentDescription>
 
 <Preview name="drawer" />
 
-## Optional props
+## Anatomy
+
+![Drawer anatomy](/assets/drawer-anatomy.png)
+
+The Drawer is a composition of several components:
+
+| Component | Description |
+| --- | --- |
+| [DrawerProvider](/components/drawer/drawer-provider) | Provides the state to all Drawer components |
+| [DrawerTrigger](/components/drawer/drawer-trigger) | A composition-first component that toggles the [DrawerPopover](/components/drawer/drawer-popover) |
+| [DrawerPopover](/components/drawer/drawer-popover) | Popover box of the Drawer |
+| [DrawerHeader](/components/drawer/drawer-header) | The fixed Header |
+| [DrawerHeading](/components/drawer/drawer-heading) | The title of the Drawer |
+| [DrawerDismiss](/components/drawer/drawer-dismiss) | Dismisses the [DrawerPopover](/components/drawer/drawer-popover) |
+| [DrawerContent](/components/drawer/drawer-content) | Main content inside of the [DrawerPopover](/components/drawer/drawer-popover) |
+| [DrawerFooter](/components/drawer/drawer-footer) | The fixed Footer mainly used for actions |
+
+
+The example code below, illustrates how these components interact with each other:
+
+```jsx
+function Anatomy() {
+  return (
+    <DrawerProvider>
+      <DrawerTrigger asChild>
+        <Button>Open</Button>
+      </DrawerTrigger>
+      <DrawerPopover>
+        <DrawerHeader>
+          <DrawerHeading>Drawer Heading</DrawerHeading>
+          <DrawerDismiss />
+        </DrawerHeader>
+        <DrawerContent>
+          Content goes here
+        </DrawerContent>
+        <DrawerFooter>
+          <Button size="large">
+            Label
+          </Button>
+          <Button variant="primary" size="large">
+            Label
+          </Button>
+        </DrawerFooter>
+      </DrawerPopover>
+    </DrawerProvider>
+  )
+}
+```
+
+## Examples
+
+### Controlled
+
+The `open` and `onChangeOpen` props of [DrawerProvider](/components/drawer/drawer-provider) are used to control the [DrawerPopover](/components/drawer/drawer-popover) open state.
+
+<Preview name="drawer-controlled" />
+
+### Long content
+
+The [DrawerContent](/components/drawer/drawer-content) adds a scrollbar for long content.
+
+<Preview name="drawer-long-content" />
+
+### Small size
+
+The [DrawerPopover](/components/drawer/drawer-popover) has either a `small` or `medium`(default) size.
 
-<PropsDocs name="drawer-provider" />
+<Preview name="drawer-small" />
 
 ## Related components
 
 <ComponentSummaryGrid>
   <ComponentSummary name="modal" />
   <ComponentSummary name="toast" />
-  <ComponentSummary name="alert" />
   <ComponentSummary name="contextual-help" />
-</ComponentSummaryGrid> */}
+</ComponentSummaryGrid>
diff --git a/packages/docs/pages/components/drawer/drawer-content.mdx b/packages/docs/pages/components/drawer/drawer-content.mdx
@@ -0,0 +1,9 @@
+# DrawerContent
+
+<ComponentDescription name="drawer-content" />
+
+<Preview name="drawer" />
+
+## Optional props
+
+<PropsDocs name="drawer-content" />
diff --git a/packages/docs/pages/components/drawer/drawer-dismiss.mdx b/packages/docs/pages/components/drawer/drawer-dismiss.mdx
@@ -0,0 +1,9 @@
+# DrawerDismiss
+
+<ComponentDescription name="drawer-dismiss" />
+
+<Preview name="drawer" />
+
+## Optional props
+
+<PropsDocs name="drawer-dismiss" />
diff --git a/packages/docs/pages/components/drawer/drawer-footer.mdx b/packages/docs/pages/components/drawer/drawer-footer.mdx
@@ -0,0 +1,9 @@
+# DrawerFooter
+
+<ComponentDescription name="drawer-footer" />
+
+<Preview name="drawer" />
+
+## Optional props
+
+All props of `<footer />` JSX element.
diff --git a/packages/docs/pages/components/drawer/drawer-header.mdx b/packages/docs/pages/components/drawer/drawer-header.mdx
@@ -0,0 +1,9 @@
+# DrawerHeader
+
+<ComponentDescription name="drawer-header" />
+
+<Preview name="drawer" />
+
+## Optional props
+
+All props of `<header />` JSX element.
diff --git a/packages/docs/pages/components/drawer/drawer-heading.mdx b/packages/docs/pages/components/drawer/drawer-heading.mdx
@@ -0,0 +1,9 @@
+# DrawerHeading
+
+<ComponentDescription name="drawer-heading" />
+
+<Preview name="drawer" />
+
+## Optional props
+
+<PropsDocs name="drawer-heading" />
diff --git a/packages/docs/pages/components/drawer/drawer-popover.mdx b/packages/docs/pages/components/drawer/drawer-popover.mdx
@@ -0,0 +1,13 @@
+# DrawerPopover
+
+<ComponentDescription name="drawer-popover" />
+
+<Preview name="drawer" />
+
+## Required props
+
+<PropsDocs name="drawer-popover" required />
+
+## Optional props
+
+<PropsDocs name="drawer-popover" />
diff --git a/packages/docs/pages/components/drawer/drawer-provider.mdx b/packages/docs/pages/components/drawer/drawer-provider.mdx
@@ -0,0 +1,13 @@
+# DrawerProvider
+
+<ComponentDescription name="drawer-provider" />
+
+<Preview name="drawer" />
+
+## Required props
+
+<PropsDocs name="drawer-provider" required />
+
+## Optional props
+
+<PropsDocs name="drawer-provider" />
diff --git a/packages/docs/pages/components/drawer/drawer-trigger.mdx b/packages/docs/pages/components/drawer/drawer-trigger.mdx
@@ -0,0 +1,13 @@
+# DrawerTrigger
+
+<ComponentDescription name="drawer-trigger" />
+
+<Preview name="drawer" />
+
+## Required props
+
+<PropsDocs name="drawer-trigger" required />
+
+## Optional props
+
+<PropsDocs name="drawer-trigger" />
diff --git a/packages/docs/public/assets/drawer-anatomy.png b/packages/docs/public/assets/drawer-anatomy.png
diff --git a/packages/shoreline/src/components/drawer/drawer-content.tsx b/packages/shoreline/src/components/drawer/drawer-content.tsx
@@ -1,4 +1,4 @@
-import { Content } from '../content'
+import { Content, type ContentOptions } from '../content'
 import { forwardRef, type ComponentPropsWithoutRef } from 'react'
 
 /**
@@ -24,4 +24,7 @@ export const DrawerContent = forwardRef<HTMLDivElement, DrawerContentProps>(
   }
 )
 
-export type DrawerContentProps = ComponentPropsWithoutRef<'div'>
+export type DrawerContentOptions = Omit<ContentOptions, 'narrow'>
+
+export type DrawerContentProps = DrawerContentOptions &
+  ComponentPropsWithoutRef<'div'>
diff --git a/packages/shoreline/src/components/drawer/drawer-dismiss.tsx b/packages/shoreline/src/components/drawer/drawer-dismiss.tsx
@@ -21,16 +21,16 @@ import { IconButton } from '../icon-button'
  */
 export const DrawerDismiss = forwardRef<HTMLButtonElement, DrawerDismissProps>(
   function DrawerDismiss(props, ref) {
-    const { children, size = 'large', ...otherProps } = props
+    const { children, label = 'Close', ...otherProps } = props
 
     return (
       <IconButton
         data-sl-modal-dismiss
         variant="tertiary"
-        label="close"
         asChild
-        size={size}
+        size="large"
         ref={ref}
+        label={label}
         {...otherProps}
       >
         <Vaul.Close>
@@ -41,7 +41,9 @@ export const DrawerDismiss = forwardRef<HTMLButtonElement, DrawerDismissProps>(
   }
 )
 
-export type DrawerDismissOptions = Pick<IconButtonOptions, 'size'>
+export type DrawerDismissOptions = Partial<
+  Pick<IconButtonOptions, 'loading' | 'label'>
+>
 
 export type DrawerDismissProps = DrawerDismissOptions &
   ComponentProps<typeof Vaul.Close>