@weing-dev/ui-kit-primitive 0.0.0 → 0.0.2

package/src/components/Cascader/README.md

@@ -1,735 +0,0 @@
-# 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)에서 확인할 수 있습니다.