chore: v5 update Avatar docs (#262)

* chore: update avatar docs to be more aligned with existing convention

Author: nurm717123

src/components/avatar-rectangle/avatar-rectangle.mdx

@@ -1,4 +1,4 @@
-import { Meta, Canvas, Controls } from '@storybook/blocks'
+import { Meta, Canvas, Controls, Description } from '@storybook/blocks'
 import { RenderHtmlMarkup } from '../../storybook/render-html-markup'
 import * as AvatarRectangleStories from './avatar-rectangle.stories'
 
@@ -10,30 +10,24 @@ A versatile component designed to render property image.
 
 <Controls />
 
-## Default Usage
-
-The default usage use the residential variant and medium size, each can be set using the `data-` attribute.
+## Default
 
+<Description of={AvatarRectangleStories.DefaultUsage} />
 <Canvas of={AvatarRectangleStories.DefaultUsage} />
 <RenderHtmlMarkup of={AvatarRectangleStories.DefaultUsage} />
 
+## Avatar Rectangle Variant
+
+<Canvas of={AvatarRectangleStories.AvatarRectangleVariant} />
+<RenderHtmlMarkup of={AvatarRectangleStories.AvatarRectangleVariant} />
+
 ## Using Residential Placeholder
 
 <Canvas of={AvatarRectangleStories.UsingResidentialPlaceholder} />
 <RenderHtmlMarkup of={AvatarRectangleStories.UsingResidentialPlaceholder} />
 
-## Using Commercial Variant
-
-<Canvas of={AvatarRectangleStories.UsingCommercialVariant} />
-<RenderHtmlMarkup of={AvatarRectangleStories.UsingCommercialPlaceholder} />
 
 ## Using Commercial Placeholder
 
 <Canvas of={AvatarRectangleStories.UsingCommercialPlaceholder} />
 <RenderHtmlMarkup of={AvatarRectangleStories.UsingCommercialPlaceholder} />
-
-## React Usage
-
-<Canvas of={AvatarRectangleStories.ReactUsage} />
-
-<RenderHtmlMarkup of={AvatarRectangleStories.ReactUsage} />

src/components/avatar-rectangle/avatar-rectangle.stories.tsx

@@ -1,18 +1,14 @@
 import type { Meta, StoryObj } from '@storybook/react'
 import { AvatarRectangle } from '.'
-import {
-  ElAvatarRectangle,
-  ElAvatarRectResidentialPlaceholder,
-  ElAvatarRectBottomImage,
-  ElAvatarRectCommercialPlaceholder,
-} from './styles'
+import { ElAvatarRectResidentialPlaceholder, ElAvatarRectCommercialPlaceholder } from './styles'
 
 export default {
   title: 'Components/Avatar Rectangle',
   component: AvatarRectangle,
   args: {
     variant: 'residential',
     size: 'medium',
+    src: 'https://picsum.photos/id/206/100/100',
   },
   argTypes: {
     variant: {
@@ -26,36 +22,23 @@ export default {
   },
 } as Meta<typeof AvatarRectangle>
 
-const exampleImageUrl = 'https://picsum.photos/id/206/100/100'
+type Story = StoryObj<typeof AvatarRectangle>
 
-export const DefaultUsage = {
-  render: ({}) => (
-    <ElAvatarRectangle>
-      <img src={exampleImageUrl} alt="example" />
-    </ElAvatarRectangle>
-  ),
-}
+/**
+ * The default usage use the residential variant and medium size, each can be set using the `data-` attribute.
+ */
+export const DefaultUsage: Story = {}
 
-export const UsingResidentialPlaceholder = {
-  render: ({}) => <ElAvatarRectResidentialPlaceholder aria-label="Image placeholder" />,
+export const AvatarRectangleVariant: Story = {
+  args: {
+    variant: 'commercial',
+  },
 }
 
-export const UsingCommercialVariant = {
-  render: ({}) => (
-    <ElAvatarRectangle data-variant="commercial">
-      <img src={exampleImageUrl} alt="example" />
-      <ElAvatarRectBottomImage aria-hidden="true" />
-    </ElAvatarRectangle>
-  ),
+export const UsingResidentialPlaceholder = {
+  render: () => <ElAvatarRectResidentialPlaceholder aria-label="Image placeholder" />,
 }
 
 export const UsingCommercialPlaceholder = {
-  render: ({}) => <ElAvatarRectCommercialPlaceholder aria-label="Image placeholder" />,
-}
-
-export const ReactUsage: StoryObj<typeof AvatarRectangle> = {
-  args: {
-    src: exampleImageUrl,
-  },
-  render: (props) => <AvatarRectangle {...props}></AvatarRectangle>,
+  render: () => <ElAvatarRectCommercialPlaceholder aria-label="Image placeholder" />,
 }

src/components/avatar/avatar.mdx

@@ -1,47 +1,43 @@
-import { Meta, Story, Canvas, Controls } from '@storybook/blocks'
+import { Meta, Story, Canvas, Controls, Description
+} from '@storybook/blocks'
 import { RenderHtmlMarkup } from '../../storybook/render-html-markup'
 import * as AvatarStories from './avatar.stories'
 
 <Meta of={AvatarStories} />
 
 # Avatar
 
-An avatar component to be used typically with a `Card` or `Nav` component. The default variant renders a circle with children.
+<Description of={AvatarStories.Default} />
 
-There are multiple variants that can be used by utilizing the data props, such as size, colour, and shape (see the HTML version of React usage). In addition to text, it also accepts an Icon as a child.
-
-## Style Only Usage
-
-<Canvas of={AvatarStories.StyleOnlyUsage} />
+<Controls />
 
-<RenderHtmlMarkup of={AvatarStories.StyleOnlyUsage} />
+## Default
 
-<Canvas of={AvatarStories.WithIconUsage} />
+<Canvas of={AvatarStories.Default} />
 
-<RenderHtmlMarkup of={AvatarStories.WithIconUsage} />
+<RenderHtmlMarkup of={AvatarStories.Default} />
 
-## With Colour
+## Avatar with Icon
 
-<Canvas of={AvatarStories.WithColour} />
+<Canvas of={AvatarStories.AvatarWithIcon} />
 
-<RenderHtmlMarkup of={AvatarStories.WithColour} />
+<RenderHtmlMarkup of={AvatarStories.AvatarWithIcon} />
 
-## With Square Shape
 
-<Canvas of={AvatarStories.WithSquareShape} />
+## Avatar Colour
 
-<RenderHtmlMarkup of={AvatarStories.WithSquareShape} />
+<Canvas of={AvatarStories.AvatarColour} />
 
-## With Small Size
+<RenderHtmlMarkup of={AvatarStories.AvatarColour} />
 
-<Canvas of={AvatarStories.WithSmallSize} />
+## Avatar Shape
 
-<RenderHtmlMarkup of={AvatarStories.WithSmallSize} />
+<Canvas of={AvatarStories.AvatarShape} />
 
-## React Usage
+<RenderHtmlMarkup of={AvatarStories.AvatarShape} />
 
-<Controls />
+## Avatar Size
 
-<Canvas of={AvatarStories.ReactUsage} />
+<Canvas of={AvatarStories.AvatarSize} />
 
-<RenderHtmlMarkup of={AvatarStories.ReactUsage} />WithColourWithColour
+<RenderHtmlMarkup of={AvatarStories.AvatarSize} />

src/components/avatar/avatar.stories.tsx

@@ -1,49 +1,49 @@
-import type { StoryObj } from '@storybook/react'
-import { Avatar, ElAvatar } from '.'
+import type { Meta, StoryObj } from '@storybook/react'
+import { Avatar } from '.'
 import { Icon } from '../icon'
 
 export default {
   title: 'Components/Avatar',
   component: Avatar,
-}
+  args: {
+    children: 'AD',
+  },
+} as Meta<typeof Avatar>
 
-export const StyleOnlyUsage = {
-  render: ({}) => <ElAvatar>AD</ElAvatar>,
-}
+type Story = StoryObj<typeof Avatar>
+
+/**
+ * An avatar component to be used typically with a `Card` or `Nav` component.
+ * The default variant renders a circle with children.
+ *
+ * There are multiple variants that can be used by utilizing the `data-` props
+ * such as `size`, `colour`, and `shape` (see the HTML version of each version).
+ * In addition to text, it also accepts an Icon as a child.
+ */
+export const Default: Story = {}
 
-export const WithIconUsage = {
-  render: ({}) => (
-    <ElAvatar>
+export const AvatarWithIcon: Story = {
+  render: (props) => (
+    <Avatar {...props}>
       <Icon icon="contact" />
-    </ElAvatar>
+    </Avatar>
   ),
 }
 
-export const WithColour = {
-  render: ({}) => <ElAvatar data-colour="purple">AD</ElAvatar>,
-  name: 'Colour: Purple',
-}
-
-export const WithSquareShape = {
-  render: ({}) => <ElAvatar data-shape="square">AD</ElAvatar>,
-  name: 'Shape: Square',
+export const AvatarColour: Story = {
+  args: {
+    colour: 'purple',
+  },
 }
 
-export const WithSmallSize = {
-  render: ({}) => (
-    <ElAvatar data-size="small">
-      <Icon icon="contact" />
-    </ElAvatar>
-  ),
-  name: 'Size: Small',
+export const AvatarShape: Story = {
+  args: {
+    shape: 'square',
+  },
 }
 
-export const ReactUsage: StoryObj<typeof Avatar> = {
+export const AvatarSize: Story = {
   args: {
-    shape: 'circle',
-    size: 'medium',
-    colour: 'default',
-    children: 'AD',
+    size: 'small',
   },
-  render: (props) => <Avatar {...props}>{props.children}</Avatar>,
 }