@weing-dev/ui-kit-primitive 0.0.0

package/src/components/Cascader/README.md

@@ -0,0 +1,735 @@
+# Cascader UI
+
+## Contents List
+
+1. [Quick Start](#QuickStart)
+2. [Reference](#Reference)
+3. [Example](#Example)
+
+## Quick Start
+
+```ts
+import { Cascader } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+  const options = [
+    { id: "1", label: "Option 1" },
+    { id: "2", label: "Option 2" },
+    { id: "3", label: "Option 3" },
+  ];
+
+  const { activeOptions, selectedOptions, columns } = Cascader.useCascader({
+    options,
+  });
+
+  return (
+    <Cascader.Root
+      options={options}
+      activeOptions={activeOptions}
+      selectedOptions={selectedOptions}
+    >
+      <Cascader.Menu>
+        {columns.map((options, level) => {
+          return (
+            <Cascader.Column key={level} index={level}>
+              {options.map((option, optionIdx) => {
+                return (
+                  <Cascader.Item
+                    key={option.id + optionIdx}
+                    index={optionIdx}
+                    option={option}
+                    level={level}
+                  />
+                );
+              })}
+            </Cascader.Column>
+          );
+        })}
+      </Cascader.Menu>
+    </Cascader.Root>
+  );
+};
+```
+
+## Reference
+
+### Option Type
+
+`Cascader`에 사용되는 옵션의 데이터 타입입니다.
+
+기본적으로 정의 되어 있는 `props`를 제외하고도 커스텀으로 정의 하여 `Cascader.Item`에서 `as`를 통해 커스텀할때 이용할 수 있습니다.
+
+```ts
+type CascaderOption = {
+  id: string;
+  label: string;
+  disabled?: boolean;
+  role?: "title" | "divider";
+  children?: CascaderOption[];
+  [key: string]: unknown;
+};
+```
+
+### Root
+
+| Prop                                                  |                       Type                        | Required | Default Value |
+| :---------------------------------------------------- | :-----------------------------------------------: | :------: | :-----------: |
+| [options](#options)                                   |         [CascaderOption](#option-type)[ ]         |   true   |      []       |
+| [activeOptions](#activeOptions)                       |         [CascaderOption](#option-type)[ ]         |    -     |       -       |
+| [selectedOptions](#selectedOptions)                   |       [CascaderOption](#option-type)[ ][ ]        |    -     |       -       |
+| [showChildrenCount](#showChildrenCount)               |                      boolean                      |    -     |     false     |
+| [columnPositionFromParent](#columnPositionFromParent) |                      boolean                      |    -     |     false     |
+| [columnOpenAnimation](#columnOpenAnimation)           |                      boolean                      |    -     |     false     |
+| [maxColumnView](#maxColumnView)                       |                      number                       |    -     |       6       |
+| [onSelect](#onSelect)                                 | (props?: [OnSelectProps](#OnSelectProps)) => void |    -     |       -       |
+| [className](#Root-className)                          |                      String                       |    -     |       -       |
+| [children](#Root-children)                            |                  React.ReactNode                  |    -     |       -       |
+| [rest](#Root-rest)                                    |  Omit<JSX.IntrinsicElements["div"], "onSelect">   |    -     |       -       |
+
+#### options
+
+`Cascader`의 ui를 보여주고 컨트롤 하기 위한 데이터입니다. 필수 값입니다.
+
+```ts
+import { Cascader } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+  const options = [
+    { id: "1", label: "Option 1" },
+    { id: "2", label: "Option 2" },
+    { id: "3", label: "Option 3" },
+  ];
+
+  return (
+    <Cascader.Root options={options}>
+      <!-- ... -->
+    </Cascader.Root>
+  );
+}
+```
+
+#### activeOptions
+
+`Cascader`에 `active`상태인 옵션을 전달하기 위한 속성입니다.
+
+`Cascader.useCascader`에서 반환되는 `activeOptions`를 전달하면 됩니다. [↗참고](#useCascader)
+
+`Cascader.Item`에서 사용되는 속성으로 오로지 스타일링을 위해 사용되기 때문에 필수 값이 아닙니다.
+
+```ts
+import { Cascader } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+  const options = [
+    { id: "1", label: "Option 1" },
+    { id: "2", label: "Option 2" },
+    { id: "3", label: "Option 3" },
+  ];
+
+  const { activeOptions } = Cascader.useCascader({
+    options,
+  });
+
+  return (
+    <Cascader.Root activeOptions={activeOptions}>
+      <!-- ... -->
+    </Cascader.Root>
+  );
+}
+```
+
+#### selectedOptions
+
+`Cascader`에 `selected`상태인 옵션을 전달하기 위한 속성입니다.
+
+`Cascader.useCascader`에서 반환되는 `selectedOptions`를 전달하면 됩니다. [↗참고](#useCascader)
+
+`Cascader.Item`에서 사용되는 속성으로 오로지 스타일링을 위해 사용되기 때문에 필수 값이 아닙니다.
+
+```ts
+import { Cascader } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+  const options = [
+    { id: "1", label: "Option 1" },
+    { id: "2", label: "Option 2" },
+    { id: "3", label: "Option 3" },
+  ];
+
+  const { selectedOptions } = Cascader.useCascader({
+    options,
+  });
+
+  return (
+    <Cascader.Root selectedOptions={selectedOptions}>
+      <!-- ... -->
+    </Cascader.Root>
+  );
+}
+```
+
+#### showChildrenCount
+
+`Cascader`의 `Item`에 자식 옵션의 개수를 보여주기 위한 속성입니다. 기본 값은 `false`입니다.
+
+```ts
+import { Cascader } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+  // ...
+
+  return (
+    <Cascader.Root showChildrenCount>
+      <!-- ... -->
+    </Cascader.Root>
+  );
+}
+```
+
+#### columnPositionFromParent
+
+`Cascader`의 `Column`의 위치를 부모 옵션의 위치에 따라 보여주기 위한 속성입니다. 기본 값은 `false`입니다.
+
+```ts
+import { Cascader } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+  // ...
+
+  return (
+    <Cascader.Root columnPositionFromParent>
+      <!-- ... -->
+    </Cascader.Root>
+  );
+}
+```
+
+#### columnOpenAnimation
+
+`Cascader`의 `Column`의 위치가 이동될때 애니메이션을 적용하기 위한 속성입니다. 기본 값은 `false`입니다.
+
+```ts
+import { Cascader } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+  // ...
+
+  return (
+    <Cascader.Root columnOpenAnimation>
+      <!-- ... -->
+    </Cascader.Root>
+  );
+}
+```
+
+#### maxColumnView
+
+`Cascader`의 `Column`의 최대 노출 개수를 정하기 위한 속성입니다. 기본 값은 `6`입니다.
+
+```ts
+import { Cascader } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+  // ...
+
+  return (
+    <Cascader.Root maxColumnView={3}>
+      <!-- ... -->
+    </Cascader.Root>
+  );
+}
+```
+
+#### onSelect
+
+`Cascader`의 `Item`이 선택되었을때 호출되는 함수입니다.
+
+콜백함수로 `params`는 선택된 `item`의 `option`과 column의 `level`을 받습니다.
+
+직접 콜백함수를 구현해도 되지만 일반적으로는 `Cascader.useCascader`에서 반환되는 `selectHandler`를 전달하면 됩니다. [↗참고](#useCascader)
+
+```ts
+import { Cascader } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+  // ...
+
+  const { selectHandler } = Cascader.useCascader({
+    options,
+  });
+
+  return (
+    <Cascader.Root onSelect={selectHandler}>
+      <!-- ... -->
+    </Cascader.Root>
+  );
+}
+```
+
+#### Root-className
+
+`Cascader.Root`에 `className` class를 전달하기 위한 `props`입니다.
+
+```ts
+import { Cascader } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+
+  return (
+    <Casacder.Root className="RootClassName">
+      <!-- ... -->
+    </Casacder.Root>
+  );
+}
+```
+
+#### Root-children
+
+`Casacder.Root`의 내부에 `Casacder.Menu`와 `Cascader.Column`, `Casacder.Item`을 추가하여 기본 Cascader를 구성합니다.[↗기본 예시](#QuickStart)
+
+`Casacder`컴포넌트 외에도 여러 컴포넌트를 조합하여 ui를 구성할 수 있습니다.
+
+#### Root-rest
+
+`Casacder.Root`의 의 가장 바깥 `div`에 전달되는 `props`입니다. 기본 `div`에서 사용되는 속성들을 전부 전달할 수 있으며 `onSelect`는 제외됩니다.[↗참고](#onSelect)
+
+### Menu
+
+`Cascader.Menu`는 스타일링만을 위한 컴포넌트이기때문에 다른 컴포넌트로 대체가 가능합니다.
+
+| Prop                         |                          Type                           | Required | Default Value |
+| :--------------------------- | :-----------------------------------------------------: | :------: | :-----------: |
+| [as](#Menu-as)               | (props: [MenuAsProps](#MenuAsProps)) => React.ReactNode |    -     |       -       |
+| [className](#Menu-className) |                         String                          |    -     |       -       |
+| [children](#Menu-children)   |                     React.ReactNode                     |    -     |       -       |
+| [rest](#Menu-rest)           |     Omit<JSX.IntrinsicElements["div"], "onSelect">      |    -     |       -       |
+
+#### Menu-as
+
+`Cascader.Menu`를 대체하기 위한 `props`입니다. 주 사용방법은 `as`를 통해 기본 `Menu`의 스타일을 가지고와서 추가적인 스타일링을 할때 사용합니다.
+
+##### MenuAsProps
+
+```ts
+type MenuAsProps = {
+  defaultClassName: string;
+};
+```
+
+```ts
+import { Cascader } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+  const options = [
+    { id: "1", label: "Option 1" },
+    { id: "2", label: "Option 2" },
+    { id: "3", label: "Option 3" },
+  ];
+
+  return (
+    <Cascader.Root options={options}>
+      <Cascader.Menu as={({defaultClassName})=>{
+        return <div className={defaultClassName}>
+          <!-- ... -->
+        </div>
+      }}>
+        <!-- ... -->
+      </Cascader.Menu>
+    </Cascader.Root>
+  );
+}
+```
+
+#### Menu-className
+
+`Cascader.Menu`에 `className` class를 전달하기 위한 `props`입니다.
+
+```ts
+import { Cascader } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+  // ...
+
+  return (
+    <Cascader.Root options={options}>
+      <Cascader.Menu className="MenuClassName">
+        <!-- ... -->
+      </Cascader.Menu>
+    </Cascader.Root>
+  );
+}
+```
+
+#### Menu-children
+
+`Casacder.Menu`의 내부에 `Cascader.Column`, `Casacder.Item`을 추가하여 기본 Cascader를 구성합니다.[↗기본 예시](#QuickStart)
+
+`Casacder`컴포넌트 외에도 여러 컴포넌트를 조합하여 ui를 구성할 수 있습니다.
+
+#### Menu-rest
+
+`Casacder.Menu`의 의 가장 바깥 `div`에 전달되는 `props`입니다. 기본 `div`에서 사용되는 속성들을 전부 전달할 수 있습니다.
+
+### Column
+
+`Cascader.Column`은 `Cascader.useCascader`에서 반환되는 `columns`를 전달하여 사용합니다.[↗기본 예시](#QuickStart)
+
+| Prop                           |                            Type                             | Required | Default Value |
+| :----------------------------- | :---------------------------------------------------------: | :------: | :-----------: |
+| [index](#Column-index)         |                           number                            |   true   |       -       |
+| [as](#Column-as)               | (props: [ColumnAsProps](#ColumnAsProps)) => React.ReactNode |    -     |       -       |
+| [className](#Column-className) |                           String                            |    -     |       -       |
+| [children](#Column-children)   |                       React.ReactNode                       |    -     |       -       |
+| [rest](#Column-rest)           |       Omit<JSX.IntrinsicElements["div"], "onSelect">        |    -     |       -       |
+
+#### Column-index
+
+`Cascader.Column`의 인덱스를 전달하기 위한 `props`입니다. 해당 인덱스는 현재 `Column`의 레벨을 의미합니다.
+
+```ts
+import { Cascader } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+  // ...
+
+  return (
+    <Cascader.Root options={options}>
+      <Cascader.Menu>
+        {columns.map((options, level) => {
+          return (
+            <Cascader.Column key={level} index={level}>
+              {
+                // ...
+              }
+            </Cascader.Column>
+          );
+        })}
+      </Cascader.Menu>
+    </Cascader.Root>
+  );
+};
+```
+
+#### Column-as
+
+`Cascader.Column`를 대체하기 위한 `props`입니다. 주 사용방법은 `as`를 통해 기본 `Column`의 스타일을 가지고와서 추가적인 스타일링을 할때 사용합니다.
+
+##### ColumnAsProps
+
+```ts
+type ColumnAsProps = {
+  defaultClassName: string;
+  maxColumnView?: number;
+  columnPositionFromParent?: boolean;
+  selectedOptionTop?: number[];
+  index?: number;
+  topOffset?: number;
+};
+```
+
+```ts
+import { Cascader } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+  // ...
+
+  return (
+    <Cascader.Root options={options}>
+      <Cascader.Menu as={({defaultClassName})=>{
+        return <div className={defaultClassName}>
+          <!-- ... -->
+        </div>
+      }}>
+        <!-- ... -->
+      </Cascader.Menu>
+    </Cascader.Root>
+  );
+}
+```
+
+#### Column-className
+
+`Cascader.Column`에 `className` class를 전달하기 위한 `props`입니다.
+
+```ts
+import { Cascader } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+  // ...
+
+  return (
+    <Cascader.Root options={options}>
+      <Cascader.Menu>
+        {columns.map((options, level) => {
+          return (
+            <Cascader.Column
+              key={level}
+              index={level}
+              className="ColumnClassName"
+            >
+              {
+                // ...
+              }
+            </Cascader.Column>
+          );
+        })}
+      </Cascader.Menu>
+    </Cascader.Root>
+  );
+};
+```
+
+#### Column-children
+
+`Cascader.Column`의 내부에 `Cascader.useCascader`를 통해 생성한 `columns`의 옵션을 통해 `Cascader.Item`을 추가하여 기본 Cascader를 구성합니다.[↗기본 예시](#QuickStart)
+
+`Cascader.Item`컴포넌트 외에도 여러 컴포넌트를 조합하여 ui를 구성할 수 있습니다.
+
+#### Column-rest
+
+`Cascader.Column`의 의 가장 바깥 `div`에 전달되는 `props`입니다. 기본 `div`에서 사용되는 속성들을 전부 전달할 수 있습니다.
+
+### Item
+
+`Cascader.Item`은 `Cascader.useCascader`에서 반환되는 `columns`를 전달하여 사용합니다.[↗기본 예시](#QuickStart)
+
+| Prop                         |                          Type                           | Required | Default Value |
+| :--------------------------- | :-----------------------------------------------------: | :------: | :-----------: |
+| [option](#Item-option)       |             [CascaderOption](#option-type)              |   true   |       -       |
+| [level](#Item-level)         |                         number                          |   true   |       -       |
+| [as](#Item-as)               | (props: [ItemAsProps](#ItemAsProps)) => React.ReactNode |    -     |       -       |
+| [className](#Item-className) |                         String                          |    -     |       -       |
+| [rest](#Item-rest)           |     Omit<JSX.IntrinsicElements["div"], "onSelect">      |    -     |       -       |
+
+#### Item-option
+
+`Cascader.Item`의 옵션을 전달하기 위한 `props`입니다.
+
+```ts
+import { Cascader } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+  // ...
+
+  return (
+    <Cascader.Root options={options}>
+      <Cascader.Menu>
+        {columns.map((options, level) => {
+          return (
+            <Cascader.Column key={level} index={level}>
+              {options.map((option, optionIdx) => {
+                return (
+                  <Cascader.Item key={option.id + optionIdx} option={option} level={level}>
+                    <!-- ... -->
+                  </Cascader.Item>
+                );
+              })}
+            </Cascader.Column>
+          );
+        })}
+      </Cascader.Menu>
+    </Cascader.Root>
+  );
+}
+```
+
+#### Item-level
+
+`Cascader.Item`의 레벨을 전달하기 위한 `props`입니다. 해당 레벨은 `Cascader.Column`의 인덱스와 동일합니다.
+
+```ts
+import { Cascader } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+  // ...
+
+  return (
+    <Cascader.Root options={options}>
+      <Cascader.Menu>
+        {columns.map((options, level) => {
+          return (
+            <Cascader.Column key={level} index={level}>
+              {options.map((option, optionIdx) => {
+                return (
+                  <Cascader.Item key={option.id + optionIdx} option={option} level={level}>
+                    <!-- ... -->
+                  </Cascader.Item>
+                );
+              })}
+            </Cascader.Column>
+          );
+        })}
+      </Cascader.Menu>
+    </Cascader.Root>
+  );
+}
+```
+
+#### Item-as
+
+`Cascader.Item`를 대체하기 위한 `props`입니다.
+
+##### ItemAsProps
+
+```ts
+type ItemAsProps = {
+  ref: React.RefObject<HTMLDivElement>;
+  option: CascaderOption;
+  level: number;
+  disabled?: boolean;
+  role?: CascaderOption["role"];
+  isSelected?: boolean;
+  showChildrenCount?: boolean;
+  defaultClassName: string;
+  onClick: () => void;
+};
+```
+
+```ts
+import { Cascader } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+  // ...
+
+  return (
+    <Cascader.Root options={options}>
+      <Cascader.Menu>
+        {columns.map((options, level) => {
+          return (
+            <Cascader.Column key={level} index={level}>
+              {options.map((option, optionIdx) => {
+                return (
+                  <Cascader.Item key={option.id + optionIdx} option={option} level={level} as={({defaultClassName})=>{
+                    return <div className={defaultClassName}>
+                      <!-- ... -->
+                    </div>
+                  }}>
+                    <!-- ... -->
+                  </Cascader.Item>
+                );
+              })}
+            </Cascader.Column>
+          );
+        })}
+      </Cascader.Menu>
+    </Cascader.Root>
+  );
+}
+```
+
+#### Item-className
+
+`Cascader.Item`에 `className` class를 전달하기 위한 `props`입니다.
+
+```ts
+import { Cascader } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+  // ...
+
+  return (
+    <Cascader.Root options={options}>
+      <Cascader.Menu>
+        {columns.map((options, level) => {
+          return (
+            <Cascader.Column key={level} index={level}>
+              {options.map((option, optionIdx) => {
+                return (
+                  <Cascader.Item key={option.id + optionIdx} option={option} level={level} className="ItemClassName">
+                    <!-- ... -->
+                  </Cascader.Item>
+                );
+              })}
+            </Cascader.Column>
+          );
+        })}
+      </Cascader.Menu>
+    </Cascader.Root>
+  );
+}
+```
+
+#### Item-rest
+
+`Cascader.Item`의 의 가장 바깥 `div`에 전달되는 `props`입니다. 기본 `div`에서 사용되는 속성들을 전부 전달할 수 있습니다.
+
+### useCascader
+
+`Cascader.useCascader`는 `Cascader`의 상태를 관리하기 위한 훅입니다.
+
+| Prop                              |       Type       | Required | Default Value |
+| :-------------------------------- | :--------------: | :------: | :-----------: |
+| [options](#useCascader-options)   | CascaderOption[] |   true   |       -       |
+| [multiple](#useCascader-multiple) |     boolean      |    -     |       -       |
+
+`Cascader.useCascader`는 다음과 같은 값들을 반환합니다:
+
+| Return Value       |                                        Type                                         |                         Description                         |
+| :----------------- | :---------------------------------------------------------------------------------: | :---------------------------------------------------------: |
+| activeOptions      |                                  CascaderOption[ ]                                  |            현재 활성화된(열려있는) 옵션들의 배열            |
+| selectedOptions    |                                CascaderOption[ ][ ]                                 | 선택된 옵션들의 2차원 배열. 각 레벨별 선택된 옵션들을 포함  |
+| columns            |                                CascaderOption[ ][ ]                                 |              보여줄 컬럼 옵션들의 2차원 배열.               |
+| selectedResult     |                                  CascaderOption[ ]                                  |       선택된 옵션들의 배열. 최종 선택된 옵션들만 포함       |
+| selectHandler      |                  (params: [OnSelectProps](#OnSelectProps)) => void                  |              Item 선택 시 호출되는 핸들러 함수              |
+| selectByIdHandler  |         (params: [SelectByIdHandlerProps](#SelectByIdHandlerProps)) => void         |     옵션의 id를 통해 선택된 옵션을 선택하는 핸들러 함수     |
+| resetAll           |           (params: [ResetAllHandlerProps](#ResetAllHandlerProps)) => void           |        활성화와 선택되어 있는 옵션을 초기화하는 함수        |
+| resetSelectedById  |  (params: [ResetSelectedByIdHandlerProps](#ResetSelectedByIdHandlerProps)) => void  | 옵션의 id를 통해 선택된 옵션과 하위 옵션을 초기화 하는 함수 |
+| resetActiveOptions | (params: [resetActiveOptionsHandlerProps](#resetActiveOptionsHandlerProps)) => void |      현재 활성화된(열려있는) 옵션들을 초기화 하는 함수      |
+
+#### useCascader-options
+
+`Cascader.useCascader`의 옵션을 전달하기 위한 `props`입니다. 이 옵션은 `Cascader.Root`의 `options`와 동일하며 필수 값입니다.
+
+최초 옵션의 데이터를 넣어야 합니다.
+
+#### useCascader-multiple
+
+`Cascader.useCascader`의 다중 선택 여부를 전달하기 위한 `props`입니다. 기본 값은 `false`입니다.
+
+#### OnSelectProps
+
+```ts
+type OnSelectProps = {
+  option: CascaderOption;
+  level: number;
+};
+```
+
+#### SelectByIdHandlerProps
+
+```ts
+type SelectByIdHandlerProps = {
+  id: string;
+};
+```
+
+#### ResetAllHandlerProps
+
+기본값은 `{active: true, selected: true}`입니다. `false`로 전달하면 해당 상태의 초기화를 막을 수 있습니다.
+
+```ts
+type ResetAllHandlerProps = {
+  active?: boolean;
+  selected?: boolean;
+};
+```
+
+#### ResetSelectedByIdHandlerProps
+
+```ts
+type ResetSelectedByIdHandlerProps = {
+  id: string;
+};
+```
+
+#### resetActiveOptionsHandlerProps
+
+```ts
+type resetActiveOptionsHandlerProps = {
+  level?: number;
+};
+```
+
+## Example
+
+프로젝트를 실행하고 해당 [Link](http://localhost:3000/users/cascader)에서 확인할 수 있습니다.