🔀 merge pull request #796 from tonightpass/ibaky/combobox-docs

📝 add documentation combobox

docs/pages/docs/components/_meta.json

@@ -5,6 +5,7 @@
   "calendar": "Calendar",
   "checkbox": "Checkbox",
   "collapse": "Collapse",
+  "combobox": "Combobox",
   "drawer": "Drawer",
   "dropdown": "Dropdown",
   "entity": "Entity",

docs/pages/docs/components/combobox.mdx

@@ -0,0 +1,272 @@
+---
+title: "React Combobox component"
+description: "The Combobox component combines a text input with a dropdown list of options, supporting search, custom rendering, and various selection modes."
+---
+
+import Playground from "@components/Playground";
+
+# Combobox
+
+The Combobox component provides an enhanced input field with autocomplete functionality, allowing users to either select from predefined options or enter custom values.
+
+## Usage
+
+First of all, you need to import the `Combobox` component from the `kitchn` package.
+
+```js
+import { Combobox } from "kitchn"
+```
+
+## Default
+
+
+<Playground
+  code={`() => {
+    const [options1, setOptions1] = React.useState();
+    const options = [
+      { 
+        label: "London", 
+        value: "london" 
+      },
+      { 
+        label: "Sydney", 
+        value: "sydney" 
+      },
+      { 
+        label: "Shanghai", 
+        value: "shanghai" 
+      }
+    ];
+
+    return (
+      <Container gap={"small"}>
+        <Text>{"default"}</Text>
+        <Container gap={10}>
+          <Combobox placeholder={"Enter here"} options={options} />
+        </Container>
+      </Container>
+    );
+  }`}
+/>
+
+## Disabled
+<Playground
+  code={`
+    () => {
+      const options = [
+        { label: "London", value: "london" },
+        { label: "Sydney", value: "sydney" },
+        { label: "Shanghai", value: "shanghai" },
+      ];
+      
+      return (
+        <Combobox 
+          disabled 
+          initialValue="London" 
+          options={options} 
+        />
+      );
+    }
+  `}
+/>
+
+## Search
+<Playground
+  code={`
+    () => {
+      const options = [
+        { label: "London", value: "london" },
+        { label: "Sydney", value: "sydney" },
+        { label: "Shanghai", value: "shanghai" },
+      ];
+
+      const [filteredOptions, setFilteredOptions] = React.useState();
+
+      const searchHandler = (currentValue) => {
+        if (!currentValue) return setFilteredOptions([]);
+
+        const relatedOptions = options.filter((item) =>
+          item.value.includes(currentValue)
+        );
+
+        setFilteredOptions(relatedOptions);
+      };
+
+      return (
+        <Combobox 
+          options={filteredOptions}
+          placeholder="Enter here"
+          onSearch={searchHandler}
+        />
+      );
+    }
+  `}
+/>
+
+
+## Only Allow Selected
+
+<Playground
+ code={`() => {
+   const options = [
+     { 
+       label: "London", 
+       value: "london" 
+     },
+     { 
+       label: "Sydney", 
+       value: "sydney" 
+     },
+     { 
+       label: "Shanghai", 
+       value: "shanghai" 
+     }
+   ];
+
+   return (
+     <Container gap={"small"}>
+       <Text>{"only allow selected"}</Text>
+       <Container gap={10}>
+         <Combobox 
+           disableFreeSolo 
+           options={options} 
+           initialValue={"sydney"} 
+         />
+       </Container>
+     </Container>
+   );
+ }`}
+/>
+
+## Loading State
+
+<Playground
+ code={`() => {
+   const options = [
+     { 
+       label: "London", 
+       value: "london" 
+     },
+     { 
+       label: "Sydney", 
+       value: "sydney" 
+     },
+     { 
+       label: "Shanghai", 
+       value: "shanghai" 
+     }
+   ];
+
+   const [filteredOptions, setFilteredOptions] = React.useState();
+   const [isSearching, setIsSearching] = React.useState(false);
+
+   const searchHandler = (currentValue) => {
+     if (!currentValue) return setFilteredOptions([]);
+     setIsSearching(true);
+
+     // Simulate API call
+     setTimeout(() => {
+       const relatedOptions = options.filter((item) =>
+         item.value.includes(currentValue)
+       );
+       setFilteredOptions(relatedOptions);
+       setIsSearching(false);
+     }, 1000);
+   };
+
+   return (
+     <Container gap={"small"}>
+       <Text>{"loading state"}</Text>
+       <Container gap={10}>
+         <Combobox 
+           searching={isSearching}
+           options={filteredOptions}
+           placeholder="Enter here"
+           onSearch={searchHandler}
+         />
+       </Container>
+     </Container>
+   );
+ }`}
+/>
+
+## Waiting in Search
+
+<Playground
+ code={`() => {
+   const options = [
+     { 
+       label: "London", 
+       value: "london" 
+     },
+     { 
+       label: "Sydney", 
+       value: "sydney" 
+     },
+     { 
+       label: "Shanghai", 
+       value: "shanghai" 
+     }
+   ];
+
+   const [options2, setOptions2] = React.useState();
+   const [searching1, setSearching1] = React.useState(false);
+   const timer = React.useRef();
+
+   const searchHandler2 = (currentValue) => {
+     if (!currentValue) return setOptions2([]);
+     setSearching1(true);
+
+     timer.current && clearTimeout(timer.current);
+     timer.current = setTimeout(() => {
+       const relatedOptions = options.filter((item) =>
+         item.value.includes(currentValue)
+       );
+       setOptions2(relatedOptions);
+       setSearching1(false);
+       clearTimeout(timer.current);
+     }, 1000);
+   };
+
+   return (
+     <Container gap={"small"}>
+       <Text>{"waiting in search"}</Text>
+       <Container gap={10}>
+         <Combobox
+           searching={searching1}
+           options={options2}
+           placeholder={"Enter here"}
+           onSearch={searchHandler2}
+         />
+       </Container>
+     </Container>
+   );
+ }`}
+/>
+## Props
+
+### Combobox Props
+
+| Name | Type | Default | Required | Description |
+| :--- | :--- | :-----: | :------: | :---------- |
+| `options` | `Array<{ label: string; value: string }>` | `[]` | No | Array of options to display in the dropdown |
+| `placeholder` | `string` | `""` | No | Placeholder text for the input field |
+| `initialValue` | `string` | `undefined` | No | Initial value for the input field |
+| `disabled` | `boolean` | `false` | No | If `true`, the combobox becomes non-interactive |
+| `disableFreeSolo` | `boolean` | `false` | No | If `true`, only allows selection from provided options |
+| `searching` | `boolean` | `false` | No | Indicates if the component is in a loading state |
+| `clearable` | `boolean` | `false` | No | If `true`, shows a clear button when there is input |
+| `onSearch` | `(value: string) => void` | `undefined` | No | Callback function triggered on input change |
+| `onChange` | `(value: string) => void` | `undefined` | No | Callback function triggered when value changes |
+
+### ComboboxSearching Props
+
+| Name | Type | Default | Required | Description |
+| :--- | :--- | :-----: | :------: | :---------- |
+| `children` | `React.ReactNode` | `undefined` | No | Custom content to display during loading state |
+
+### ComboboxEmpty Props
+
+| Name | Type | Default | Required | Description |
+| :--- | :--- | :-----: | :------: | :---------- |
+| `children` | `React.ReactNode` | `undefined` | No | Custom content to display when no options match |