@lunit/design-system 2.2.0 → 2.2.3

package/src/stories/components/Dropdown/Dropdown.stories.tsx

@@ -1,40 +1,46 @@
-import React, { useState } from "react";
-import { StoryFn, Meta, StoryObj } from "@storybook/react-webpack5";
+import React, { useState } from 'react';
+import { StoryFn, Meta, StoryObj } from '@storybook/react-webpack5';
 
-import Dropdown, { DropdownItem } from "@/components/Dropdown";
-import { Box, SelectChangeEvent } from "@mui/material";
+import Dropdown, { DropdownItem } from '@/components/Dropdown';
+import { Box, SelectChangeEvent } from '@mui/material';
 
 export default {
-  title: "Components/Dropdown",
+  title: 'Components/Dropdown',
   component: Dropdown,
+  args: {
+    size: 'medium',
+    select: 'single',
+    error: false,
+    disabled: false,
+  },
   argTypes: {
     size: {
       control: {
-        type: "radio",
+        type: 'radio',
       },
-      options: ["small", "medium", "large"],
-      description: "The size of the dropdown. Default is medium.",
+      options: ['small', 'medium', 'large'],
+      description: 'The size of the dropdown. Default is medium.',
     },
     select: {
       control: {
-        type: "radio",
+        type: 'radio',
       },
-      options: ["single", "multiple"],
-      description: "The select type of the dropdown. Default is single.",
+      options: ['single', 'multiple'],
+      description: 'The select type of the dropdown. Default is single.',
     },
     error: {
       control: {
-        type: "radio",
+        type: 'radio',
       },
       options: [true, false],
-      description: "The error prop toggles the error state.",
+      description: 'The error prop toggles the error state.',
     },
     disabled: {
       control: {
-        type: "radio",
+        type: 'radio',
       },
       options: [true, false],
-      description: "If true, the text field will be disabled.",
+      description: 'If true, the text field will be disabled.',
     },
   },
 } as Meta<typeof Dropdown>;
@@ -44,29 +50,29 @@ const BasicDropdownTemplate: StoryFn<typeof Dropdown> = (args, context) => {
 
   // In a single select, selectedValue can be used as a string type instead of an array.
   // In the current Storybook Template, we use selectedValue as a string[] in order to also use it as multiple depending on the control selection.
-  const [selectedValue, setSelectedValue] = useState<string[]>(["test1"]);
+  const [selectedValue, setSelectedValue] = useState<string[]>(['test1']);
   const handleSelectedValueChange = (event: SelectChangeEvent<unknown>) => {
     const {
       target: { value },
     } = event;
     setSelectedValue(
       // On autofill we get a stringified value.
-      typeof value === "string" ? value.split(",") : (value as string[]),
+      typeof value === 'string' ? value.split(',') : (value as string[]),
     );
   };
 
   return (
     <Box>
       <Dropdown
+        {...args}
         className={classNameFromGlobal}
         value={selectedValue}
         onChange={handleSelectedValueChange}
-        sx={{ width: "150px" }}
-        {...args}
+        sx={{ width: '150px' }}
       >
-        <DropdownItem value={"test1"}>Conquer cancer through AI</DropdownItem>
-        <DropdownItem value={"test2"}>test item 2</DropdownItem>
-        <DropdownItem value={"test3"}>test item 3</DropdownItem>
+        <DropdownItem value={'test1'}>Conquer cancer through AI</DropdownItem>
+        <DropdownItem value={'test2'}>test item 2</DropdownItem>
+        <DropdownItem value={'test3'}>test item 3</DropdownItem>
       </Dropdown>
     </Box>
   );
@@ -84,59 +90,59 @@ const SizeTemplate: StoryFn<typeof Dropdown> = (args, context) => {
 
   // In a single select, selectedValue can be used as a string type instead of an array.
   // In the current Storybook Template, we use selectedValue as a string[] in order to also use it as multiple depending on the control selection.
-  const [selectedValue, setSelectedValue] = useState<string[]>(["test1"]);
+  const [selectedValue, setSelectedValue] = useState<string[]>(['test1']);
   const handleSelectedValueChange = (event: SelectChangeEvent<unknown>) => {
     const {
       target: { value },
     } = event;
     setSelectedValue(
       // On autofill we get a stringified value.
-      typeof value === "string" ? value.split(",") : (value as string[]),
+      typeof value === 'string' ? value.split(',') : (value as string[]),
     );
   };
 
   return (
-    <Box sx={{ display: "flex", alignItems: "center", gap: 4 }}>
+    <Box sx={{ display: 'flex', alignItems: 'center', gap: 4 }}>
       <Box>
         <Dropdown
+          {...args}
           className={classNameFromGlobal}
           value={selectedValue}
           onChange={handleSelectedValueChange}
           size="small"
-          sx={{ width: "150px" }}
-          {...args}
+          sx={{ width: '150px' }}
         >
-          <DropdownItem value={"test1"}>Small item 1</DropdownItem>
-          <DropdownItem value={"test2"}>Small item 2</DropdownItem>
-          <DropdownItem value={"test3"}>Small item 3</DropdownItem>
+          <DropdownItem value={'test1'}>Small item 1</DropdownItem>
+          <DropdownItem value={'test2'}>Small item 2</DropdownItem>
+          <DropdownItem value={'test3'}>Small item 3</DropdownItem>
         </Dropdown>
       </Box>
       <Box>
         <Dropdown
+          {...args}
           className={classNameFromGlobal}
           value={selectedValue}
           onChange={handleSelectedValueChange}
           size="medium"
-          sx={{ width: "150px" }}
-          {...args}
+          sx={{ width: '150px' }}
         >
-          <DropdownItem value={"test1"}>Medium item 1</DropdownItem>
-          <DropdownItem value={"test2"}>Medium item 2</DropdownItem>
-          <DropdownItem value={"test3"}>Medium item 3</DropdownItem>
+          <DropdownItem value={'test1'}>Medium item 1</DropdownItem>
+          <DropdownItem value={'test2'}>Medium item 2</DropdownItem>
+          <DropdownItem value={'test3'}>Medium item 3</DropdownItem>
         </Dropdown>
       </Box>
       <Box>
         <Dropdown
+          {...args}
           className={classNameFromGlobal}
           value={selectedValue}
           onChange={handleSelectedValueChange}
           size="large"
-          sx={{ width: "150px" }}
-          {...args}
+          sx={{ width: '150px' }}
         >
-          <DropdownItem value={"test1"}>Large item 1</DropdownItem>
-          <DropdownItem value={"test2"}>Large item 2</DropdownItem>
-          <DropdownItem value={"test3"}>Large item 3</DropdownItem>
+          <DropdownItem value={'test1'}>Large item 1</DropdownItem>
+          <DropdownItem value={'test2'}>Large item 2</DropdownItem>
+          <DropdownItem value={'test3'}>Large item 3</DropdownItem>
         </Dropdown>
       </Box>
     </Box>
@@ -146,61 +152,63 @@ const SizeTemplate: StoryFn<typeof Dropdown> = (args, context) => {
 export const Size: StoryObj<typeof Dropdown> = {
   render: SizeTemplate,
   parameters: {
-    controls: {
-      include: ["select", "error", "disabled"],
-    },
     chromatic: { disableSnapshot: true },
   },
+  argTypes: {
+    size: {
+      control: false,
+    },
+  },
 };
 
 const SelectTypeTemplate: StoryFn<typeof Dropdown> = (args, context) => {
   const classNameFromGlobal = context.globals.theme;
 
-  const [selectedValue, setSelectedValue] = useState<string>("single1");
+  const [selectedValue, setSelectedValue] = useState<string>('single1');
   const handleSelectedValueChange = (event: SelectChangeEvent<unknown>) => {
     const {
       target: { value },
     } = event;
     setSelectedValue(value as string);
   };
-  const [selectedValue2, setSelectedValue2] = useState<string[]>(["multiple1"]);
+  const [selectedValue2, setSelectedValue2] = useState<string[]>(['multiple1']);
   const handleSelectedValueChange2 = (event: SelectChangeEvent<unknown>) => {
     const {
       target: { value },
     } = event;
     setSelectedValue2(
       // On autofill we get a stringified value.
-      typeof value === "string" ? value.split(",") : (value as string[]),
+      typeof value === 'string' ? value.split(',') : (value as string[]),
     );
   };
 
   return (
-    <Box sx={{ display: "flex", alignItems: "center", gap: 4 }}>
+    <Box sx={{ display: 'flex', alignItems: 'center', gap: 4 }}>
       <Box>
         <Dropdown
+          {...args}
           className={classNameFromGlobal}
           value={selectedValue}
           onChange={handleSelectedValueChange}
-          sx={{ width: "150px" }}
-          {...args}
+          sx={{ width: '150px' }}
         >
-          <DropdownItem value={"single1"}>Single item 1</DropdownItem>
-          <DropdownItem value={"single2"}>Single item 2</DropdownItem>
-          <DropdownItem value={"single3"}>Single item 3</DropdownItem>
+          <DropdownItem value={'single1'}>Single item 1</DropdownItem>
+          <DropdownItem value={'single2'}>Single item 2</DropdownItem>
+          <DropdownItem value={'single3'}>Single item 3</DropdownItem>
         </Dropdown>
       </Box>
       <Box>
         <Dropdown
+          {...args}
           className={classNameFromGlobal}
           value={selectedValue2}
           onChange={handleSelectedValueChange2}
           select="multiple"
-          sx={{ width: "200px" }}
-          {...args}
+          sx={{ width: '200px' }}
         >
-          <DropdownItem value={"multiple1"}>Multiple item 1</DropdownItem>
-          <DropdownItem value={"multiple2"}>Multiple item 2</DropdownItem>
-          <DropdownItem value={"multiple3"}>Multiple item 3</DropdownItem>
+          <DropdownItem value={'multiple1'}>Multiple item 1</DropdownItem>
+          <DropdownItem value={'multiple2'}>Multiple item 2</DropdownItem>
+          <DropdownItem value={'multiple3'}>Multiple item 3</DropdownItem>
         </Dropdown>
       </Box>
     </Box>
@@ -210,11 +218,13 @@ const SelectTypeTemplate: StoryFn<typeof Dropdown> = (args, context) => {
 export const SelectType: StoryObj<typeof Dropdown> = {
   render: SelectTypeTemplate,
   parameters: {
-    controls: {
-      include: ["size", "error", "disabled"],
-    },
     chromatic: { disableSnapshot: true },
   },
+  argTypes: {
+    select: {
+      control: false,
+    },
+  },
 };
 
 const ErrorTemplate: StoryFn<typeof Dropdown> = (args, context) => {
@@ -222,31 +232,31 @@ const ErrorTemplate: StoryFn<typeof Dropdown> = (args, context) => {
 
   // In a single select, selectedValue can be used as a string type instead of an array.
   // In the current Storybook Template, we use selectedValue as a string[] in order to also use it as multiple depending on the control selection.
-  const [selectedValue, setSelectedValue] = useState<string[]>(["test1"]);
+  const [selectedValue, setSelectedValue] = useState<string[]>(['test1']);
   const handleSelectedValueChange = (event: SelectChangeEvent<unknown>) => {
     const {
       target: { value },
     } = event;
     setSelectedValue(
       // On autofill we get a stringified value.
-      typeof value === "string" ? value.split(",") : (value as string[]),
+      typeof value === 'string' ? value.split(',') : (value as string[]),
     );
   };
 
   return (
-    <Box sx={{ display: "flex", alignItems: "center", gap: 4 }}>
+    <Box sx={{ display: 'flex', alignItems: 'center', gap: 4 }}>
       <Box>
         <Dropdown
+          {...args}
           className={classNameFromGlobal}
           value={selectedValue}
           onChange={handleSelectedValueChange}
           error
-          sx={{ width: "150px" }}
-          {...args}
+          sx={{ width: '150px' }}
         >
-          <DropdownItem value={"test1"}>Small item 1</DropdownItem>
-          <DropdownItem value={"test2"}>Small item 2</DropdownItem>
-          <DropdownItem value={"test3"}>Small item 3</DropdownItem>
+          <DropdownItem value={'test1'}>Small item 1</DropdownItem>
+          <DropdownItem value={'test2'}>Small item 2</DropdownItem>
+          <DropdownItem value={'test3'}>Small item 3</DropdownItem>
         </Dropdown>
       </Box>
     </Box>
@@ -256,11 +266,13 @@ const ErrorTemplate: StoryFn<typeof Dropdown> = (args, context) => {
 export const Error: StoryObj<typeof Dropdown> = {
   render: ErrorTemplate,
   parameters: {
-    controls: {
-      include: [],
-    },
     chromatic: { disableSnapshot: true },
   },
+  argTypes: {
+    error: {
+      control: false,
+    },
+  },
 };
 
 const DisabledTemplate: StoryFn<typeof Dropdown> = (args, context) => {
@@ -268,31 +280,31 @@ const DisabledTemplate: StoryFn<typeof Dropdown> = (args, context) => {
 
   // In a single select, selectedValue can be used as a string type instead of an array.
   // In the current Storybook Template, we use selectedValue as a string[] in order to also use it as multiple depending on the control selection.
-  const [selectedValue, setSelectedValue] = useState<string[]>(["test1"]);
+  const [selectedValue, setSelectedValue] = useState<string[]>(['test1']);
   const handleSelectedValueChange = (event: SelectChangeEvent<unknown>) => {
     const {
       target: { value },
     } = event;
     setSelectedValue(
       // On autofill we get a stringified value.
-      typeof value === "string" ? value.split(",") : (value as string[]),
+      typeof value === 'string' ? value.split(',') : (value as string[]),
     );
   };
 
   return (
-    <Box sx={{ display: "flex", alignItems: "center", gap: 4 }}>
+    <Box sx={{ display: 'flex', alignItems: 'center', gap: 4 }}>
       <Box>
         <Dropdown
+          {...args}
           className={classNameFromGlobal}
           value={selectedValue}
           onChange={handleSelectedValueChange}
           disabled
-          sx={{ width: "150px" }}
-          {...args}
+          sx={{ width: '150px' }}
         >
-          <DropdownItem value={"test1"}>Small item 1</DropdownItem>
-          <DropdownItem value={"test2"}>Small item 2</DropdownItem>
-          <DropdownItem value={"test3"}>Small item 3</DropdownItem>
+          <DropdownItem value={'test1'}>Small item 1</DropdownItem>
+          <DropdownItem value={'test2'}>Small item 2</DropdownItem>
+          <DropdownItem value={'test3'}>Small item 3</DropdownItem>
         </Dropdown>
       </Box>
     </Box>
@@ -302,9 +314,11 @@ const DisabledTemplate: StoryFn<typeof Dropdown> = (args, context) => {
 export const Disabled: StoryObj<typeof Dropdown> = {
   render: DisabledTemplate,
   parameters: {
-    controls: {
-      include: [],
-    },
     chromatic: { disableSnapshot: true },
   },
+  argTypes: {
+    disabled: {
+      control: false,
+    },
+  },
 };

package/src/stories/components/Dropdown/DropdownDocs.mdx

@@ -0,0 +1,275 @@
+import { Canvas, Stories, Controls, Meta, Story } from '@storybook/addon-docs/blocks';
+import Box from '@mui/material/Box';
+import Demo from '@lunit/design-system-icons/Demo';
+import ViewfinderT1 from '@lunit/design-system-icons/ViewfinderT1';
+import RulerT2 from '@lunit/design-system-icons/RulerT2';
+
+import Dropdown, { DropdownItem, DropdownDivider, DropdownSubtitle } from '@/components/Dropdown';
+import * as DropdownStories from './Dropdown.stories';
+import * as DropdownExampleStories from './DropdownExamples.stories';
+import * as DropdownItemStories from './DropdownItem.stories';
+
+<Meta name="Dropdown Docs" of={DropdownStories} />
+
+# Dropdown
+
+Dropdowns allow users to select one or multiple options from a list of choices.
+
+## Usage
+
+### Basic Dropdown
+
+```tsx
+import { Dropdown, DropdownItem } from '@lunit/design-system';
+// or
+import Dropdown, { DropdownItem } from '@lunit/design-system/Dropdown';
+
+<Dropdown value={selectedValue} onChange={handleChange}>
+  <DropdownItem value="option1">Option 1</DropdownItem>
+  <DropdownItem value="option2">Option 2</DropdownItem>
+</Dropdown>;
+```
+
+### Demo
+
+<Canvas of={DropdownStories.BasicDropdown} sourceState="none" />
+
+<Controls />
+
+### Size
+
+The Dropdown has three sizes: `small`, `medium` and `large`.<br />
+Using the `size` prop, you can change the size of the Dropdown.<br />
+Default size is `medium`.
+
+<Canvas of={DropdownStories.Size} meta={DropdownStories} sourceState="none" />
+
+```tsx
+<Dropdown size="small" value={selectedValue} onChange={handleChange}>
+  <DropdownItem value="option1">Small Option 1</DropdownItem>
+  <DropdownItem value="option2">Small Option 2</DropdownItem>
+</Dropdown>
+
+<Dropdown size="medium" value={selectedValue} onChange={handleChange}>
+  <DropdownItem value="option1">Medium Option 1</DropdownItem>
+  <DropdownItem value="option2">Medium Option 2</DropdownItem>
+</Dropdown>
+
+<Dropdown size="large" value={selectedValue} onChange={handleChange}>
+  <DropdownItem value="option1">Large Option 1</DropdownItem>
+  <DropdownItem value="option2">Large Option 2</DropdownItem>
+</Dropdown>
+```
+
+### Select Type
+
+The Dropdown has two select types: `single` and `multiple`.<br />
+Using the `select` prop, you can change the select type of the Dropdown.<br />
+Default select type is `single`.
+
+<Canvas of={DropdownStories.SelectType} meta={DropdownStories} sourceState="none" />
+
+```tsx
+// Single select
+<Dropdown select="single" value={selectedValue} onChange={handleChange}>
+  <DropdownItem value="option1">Single Option 1</DropdownItem>
+  <DropdownItem value="option2">Single Option 2</DropdownItem>
+</Dropdown>
+
+// Multiple select
+<Dropdown select="multiple" value={selectedValues} onChange={handleChange}>
+  <DropdownItem value="option1">Multiple Option 1</DropdownItem>
+  <DropdownItem value="option2">Multiple Option 2</DropdownItem>
+</Dropdown>
+```
+
+### Error State
+
+If you want to show an error state, you can use the `error` prop.<br />
+Default error is `false`.
+
+<Canvas of={DropdownStories.Error} sourceState="none" />
+
+```tsx
+<Dropdown error value={selectedValue} onChange={handleChange}>
+  <DropdownItem value="option1">Option 1</DropdownItem>
+  <DropdownItem value="option2">Option 2</DropdownItem>
+</Dropdown>
+```
+
+### Disabled
+
+If you want to disable the Dropdown, you can use the `disabled` prop.<br />
+Default disabled is `false`.
+
+<Canvas of={DropdownStories.Disabled} sourceState="none" />
+
+```tsx
+<Dropdown disabled value={selectedValue} onChange={handleChange}>
+  <DropdownItem value="option1">Option 1</DropdownItem>
+  <DropdownItem value="option2">Option 2</DropdownItem>
+</Dropdown>
+```
+
+## DropdownItem
+
+### Basic DropdownItem
+
+<Canvas of={DropdownItemStories.BasicDropdownItem} sourceState="none" />
+
+```tsx
+<DropdownItem value="option1">Basic Option</DropdownItem>
+```
+
+### DropdownItem Filled Style
+
+For GNB or specific single select situations, you can use the `isFilledStyle` prop.<br />
+Default isFilledStyle is `false`.
+
+<Canvas
+  of={DropdownItemStories.DropdownItemSelectStyle}
+  meta={DropdownItemStories}
+  sourceState="none"
+/>
+
+```tsx
+// Filled Style DropdownItem in GNB
+<DropdownItem value="option1" isFilledStyle>
+  Filled Style Option
+</DropdownItem>
+```
+
+### DropdownItem with Left Icon and Right Text
+
+DropdownItem can have a left icon and right text using the `leftIcon` and `rightText` props.
+
+<Canvas
+  of={DropdownItemStories.DropdownItemWithIconText}
+  meta={DropdownItemStories}
+  sourceState="none"
+/>
+
+```tsx
+<DropdownItem value="option1" leftIcon={<Demo fontSize="small" />} rightText="shortcut">
+  Option with Icon
+</DropdownItem>
+```
+
+### DropdownItem with Divider and Subtitle
+
+You can organize dropdown items using `DropdownDivider` and `DropdownSubtitle` components.
+
+<Canvas
+  of={DropdownItemStories.DropdownItemDividerSubtitle}
+  meta={DropdownItemStories}
+  sourceState="none"
+/>
+
+```tsx
+<Dropdown value={selectedValue} onChange={handleChange}>
+  <DropdownSubtitle title="Category 1" />
+  <DropdownItem value="option1">Option 1</DropdownItem>
+  <DropdownItem value="option2">Option 2</DropdownItem>
+  <DropdownDivider />
+  <DropdownSubtitle title="Category 2" />
+  <DropdownItem value="option3">Option 3</DropdownItem>
+  <DropdownItem value="option4">Option 4</DropdownItem>
+</Dropdown>
+```
+
+## Advanced Examples
+
+<Canvas
+  of={DropdownExampleStories.DropdownExamples}
+  meta={DropdownExampleStories}
+  sourceState="none"
+/>
+
+### Placeholder
+
+You can implement placeholder functionality using the `displayEmpty` and `renderValue` props.<br /><br />
+This example is simplified for demonstration purposes and may not fully match the default component behavior.<br />
+For multiple select, the selected items in this example are shown in the order the user selected them.
+However, the default Dropdown component displays selected items based on their order in the option list.
+
+```tsx
+// Single select with placeholder
+<Dropdown
+  value={selectedValue}
+  onChange={handleChange}
+  displayEmpty
+  renderValue={(selected) => {
+    if (!selected) {
+      // This code applies styling to the placeholder text
+      return <Box sx={{ color: 'text.secondary' }}>Select an option</Box>;
+    }
+    return selected;
+  }}
+>
+  <DropdownItem value="option1">Option 1</DropdownItem>
+  <DropdownItem value="option2">Option 2</DropdownItem>
+</Dropdown>
+
+// Multiple select with placeholder
+<Dropdown
+  select="multiple"
+  value={selectedValues}
+  onChange={handleChange}
+  displayEmpty
+  renderValue={(selected) => {
+    if ((selected as string[]).length === 0) {
+       // This code applies styling to the placeholder text
+      return <Box sx={{ color: 'text.secondary' }}>Select options</Box>;
+    }
+    return (selected as string[]).join(', ');
+  }}
+>
+  <DropdownItem value="option1">Option 1</DropdownItem>
+  <DropdownItem value="option2">Option 2</DropdownItem>
+</Dropdown>
+```
+
+### Button Dropdown
+
+You can create a button-triggered dropdown by controlling the `open`, `onClose`, and `onOpen` props.<br /><br />
+In most cases, you don’t need to manage the `open` state manually, as the Dropdown handles it internally.
+This example explicitly defines the `open` state to demonstrate how a dropdown can be controlled using an external trigger, such as a button.
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Box sx={{ position: 'relative' }}>
+  <Button onClick={() => setOpen(true)}>Dropdown Button</Button>
+  <Dropdown
+    value={selectedValue}
+    onChange={handleChange}
+    open={open}
+    onClose={() => setOpen(false)}
+    onOpen={() => setOpen(true)}
+    sx={{
+      position: 'absolute',
+      clip: 'rect(0 0 0 0)',
+      clipPath: 'inset(50%)',
+      height: '1px',
+      overflow: 'hidden',
+      whiteSpace: 'nowrap',
+      width: '1px',
+    }}
+  >
+    <DropdownItem value="option1">Option 1</DropdownItem>
+    <DropdownItem value="option2">Option 2</DropdownItem>
+  </Dropdown>
+</Box>;
+```
+
+## Reference
+
+- [Material-UI Select](https://mui.com/material-ui/react-select/)
+- [Material-UI Select API](https://mui.com/material-ui/api/select/)
+- [Material-UI MenuItem API](https://mui.com/material-ui/api/menu-item/)
+- [Lunit Design System Dropdown Figma](https://www.figma.com/design/9CoirIDPof6exynJosiGXi/Design-System_2.0.0_Latest?node-id=474-56086&m=dev)
+
+## Support
+
+- Github: [Create a new issue](https://github.com/lunit-io/design-system/issues/new)
+- Slack: #tf_design_system