docs(react-drawer): add missing documentation for Drawer stories

packages/react-components/react-drawer/stories/Drawer/DrawerAlwaysOpen.stories.tsx

@@ -41,3 +41,14 @@ export const AlwaysOpen = () => {
     </div>
   );
 };
+
+AlwaysOpen.parameters = {
+  docs: {
+    description: {
+      story: [
+        'A drawer can be always open, in which case it will not be able to be closed by the user.',
+        'This is useful for drawers that are used for navigation, and should always be visible.',
+      ].join('\n'),
+    },
+  },
+};

packages/react-components/react-drawer/stories/Drawer/DrawerCustomSize.stories.tsx

@@ -70,3 +70,11 @@ export const CustomSize = () => {
     </div>
   );
 };
+
+CustomSize.parameters = {
+  docs: {
+    description: {
+      story: 'The Drawer can be sized to any custom width, by overriding the `width` style property.',
+    },
+  },
+};

packages/react-components/react-drawer/stories/Drawer/DrawerDescription.md

@@ -1 +1,7 @@
-The Drawer gives users a quick entry point to configuration and information. It should be used when retaining context is beneficial to users. An overlay is optional depending on whether or not interacting with the background content is beneficial to the user’s context/scenario. An overlay makes the Drawer blocking and signifies that the users full attention is required when making configurations.
+The Drawer gives users a quick entry point to configuration and information. It should be used when retaining context is beneficial to users.
+
+There are three main components to represent a Drawer:
+
+- `DrawerOverlay`: Represents an overlay Drawer. This component renders on top of the whole page. By default blocks the screen and will require users full attention. Uses Dialog component under the hood.
+- `DrawerInline`: Represents an inline Drawer. This is rendered within a container and can be placed next to any content.
+- `Drawer`: It is a combination of DrawerOverlay and DrawerInline. Used when toggling between the two modes is necessary. Often used for responsiveness.

packages/react-components/react-drawer/stories/Drawer/DrawerInline.stories.tsx

@@ -84,3 +84,15 @@ export const Inline = () => {
     </div>
   );
 };
+
+Inline.parameters = {
+  docs: {
+    description: {
+      story: [
+        'DrawerInline is often used for navigation that is not dismissible.',
+        'As it is on the same level as the main surface, users can still interact with other UI elements.',
+        'This could be useful for swapping between different items in the main surface.',
+      ].join('\n'),
+    },
+  },
+};

packages/react-components/react-drawer/stories/Drawer/DrawerOverlay.stories.tsx

@@ -35,3 +35,15 @@ export const Overlay = () => {
     </div>
   );
 };
+
+Overlay.parameters = {
+  docs: {
+    description: {
+      story: [
+        'DrawerOverlay contains supplementary content and are used for complex creation, edit, or management experiences.',
+        'For example, viewing details about an item in a list or editing settings.',
+        'By default, drawer is blocking and signifies that the users full attention is required when making configurations.',
+      ].join('\n'),
+    },
+  },
+};

packages/react-components/react-drawer/stories/Drawer/DrawerOverlayNoModal.stories.tsx

@@ -35,3 +35,14 @@ export const OverlayNoModal = () => {
     </div>
   );
 };
+
+OverlayNoModal.parameters = {
+  docs: {
+    description: {
+      story: [
+        "An overlay is optional depending on whether or not interacting with the background content is beneficial to the user's context/scenario.",
+        'By setting the `modalType` prop to `non-modal`, the Drawer will not be blocking and the user can interact with the background content.',
+      ].join('\n'),
+    },
+  },
+};

packages/react-components/react-drawer/stories/Drawer/DrawerPosition.stories.tsx

@@ -63,3 +63,14 @@ export const Position = () => {
     </div>
   );
 };
+
+Position.parameters = {
+  docs: {
+    description: {
+      story: [
+        'When a Drawer is invoked, it slides in from either the left or right side of the screen.',
+        'This can be specified by the `position` prop.',
+      ].join('\n'),
+    },
+  },
+};

packages/react-components/react-drawer/stories/Drawer/DrawerPreventClose.stories.tsx

@@ -35,3 +35,14 @@ export const PreventClose = () => {
     </div>
   );
 };
+
+PreventClose.parameters = {
+  docs: {
+    description: {
+      story: [
+        'By setting the `modalType` prop to `alert`, the Drawer will not be closable by clicking outside nor using the "ESC" key.',
+        'This is useful for scenarios where the user must interact with the Drawer before continuing, when opening a Drawer is a critical action or when multiple Drawers are open at the same time.',
+      ].join('\n'),
+    },
+  },
+};

packages/react-components/react-drawer/stories/Drawer/DrawerResizable.stories.tsx

@@ -91,3 +91,11 @@ export const Resizable = () => {
     </div>
   );
 };
+
+Resizable.parameters = {
+  docs: {
+    description: {
+      story: 'This example shows how to implement a resizable drawer.',
+    },
+  },
+};

packages/react-components/react-drawer/stories/Drawer/DrawerResponsive.stories.tsx

@@ -76,3 +76,14 @@ export const Responsive = () => {
     </div>
   );
 };
+
+Responsive.parameters = {
+  docs: {
+    description: {
+      story: [
+        'When using the `Drawer` component, the `type` prop can be used to change the drawer type based on the viewport size.',
+        'The example below will change the drawer type to `overlay` when the viewport is smaller than 720px.',
+      ].join('\n'),
+    },
+  },
+};

packages/react-components/react-drawer/stories/Drawer/DrawerSeparator.stories.tsx

@@ -84,3 +84,14 @@ export const Separator = () => {
     </div>
   );
 };
+
+Separator.parameters = {
+  docs: {
+    description: {
+      story: [
+        'The `separator` prop adds a line separator between the drawer and the content.',
+        'Its placement will be determined by the `position` prop',
+      ].join('\n'),
+    },
+  },
+};

packages/react-components/react-drawer/stories/Drawer/DrawerSize.stories.tsx

@@ -76,3 +76,11 @@ export const Size = () => {
     </div>
   );
 };
+
+Size.parameters = {
+  docs: {
+    description: {
+      story: 'The `size` prop controls the width of the drawer. The default is `small`.',
+    },
+  },
+};

packages/react-components/react-drawer/stories/Drawer/DrawerWithNavigation.stories.tsx

@@ -58,3 +58,15 @@ export const WithNavigation = () => {
     </div>
   );
 };
+
+WithNavigation.parameters = {
+  docs: {
+    description: {
+      story: [
+        'Drawers can have any type of content and one great case is to have a toolbar in the header.',
+        'Drawer ships with a `DrawerHeaderNavigation` component that can be used to display a toolbar in the header of the drawer.',
+        'This can be combined with `DrawerHeaderTitle` to display a title in the header.',
+      ].join('\n'),
+    },
+  },
+};

packages/react-components/react-drawer/stories/Drawer/DrawerWithScroll.stories.tsx

@@ -73,3 +73,14 @@ export const WithScroll = () => {
     </div>
   );
 };
+
+WithScroll.parameters = {
+  docs: {
+    description: {
+      story: [
+        'By default, the drawer will not scroll its content when it overflows.',
+        'To enable this behavior, the DrawerBody component can be used to wrap the content of the drawer.',
+      ].join('\n'),
+    },
+  },
+};