@weing-dev/ui-kit-primitive 0.0.0

package/src/components/Slider/README.md

@@ -0,0 +1,639 @@
+# Slider UI
+
+## Contents List
+
+1. [Quick Start](#QuickStart)
+2. [Reference](#Reference)
+3. [Example](#Example)
+
+## Quick Start
+
+```ts
+import { Slider } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+  // ...
+
+  return (
+    <Slider.Root>
+      <Slider.Progress>
+        <Slider.Thumb></Slider.Thumb>
+      </Slider.Progress>
+    </Slider.Root>
+  );
+};
+```
+
+## Reference
+
+### Root
+
+| Prop                                  |                       Type                       | Required | Default Value |
+| :------------------------------------ | :----------------------------------------------: | :------: | :-----------: |
+| [readOnly](#readOnly)                 |                     Boolean                      |    -     |     false     |
+| [disabled](#disabled)                 |                     Boolean                      |    -     |     false     |
+| [invert](#invert)                     |                     Boolean                      |    -     |     false     |
+| [min](#min)                           |                      Number                      |    -     |       0       |
+| [max](#max)                           |                      Number                      |    -     |      100      |
+| [step](#step)                         |                      Number                      |    -     |      10       |
+| [labelAlwaysOn](#labelAlwaysOn)       |                     Boolean                      |    -     |     false     |
+| [marks](#marks)                       |           [Object](#marksObjectType)[]           |    -     |       -       |
+| [markActiveEffect](#markActiveEffect) |                     Boolean                      |    -     |     true      |
+| [defaultValue](#defaultValue)         |                     Number[]                     |    -     |      [0]      |
+| [scale](#scale)                       |               (v:Number) => Number               |    -     |   (v) => v    |
+| [label](#label)                       |          ((v:Number) => string) or null          |    -     |       -       |
+| [onChange](#onChange)                 | (props: [onChangeProps](#onChangeProps)) => void |    -     |       -       |
+
+#### readOnly
+
+`Slider`의 `readOnly`을 관리하는 상태입니다. `readOnly`가 `true`일 경우 `Slider`의 색상은 보이지만 조작이 불가합니다.
+
+```ts
+import { Slider } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+
+  return (
+    <Slider.Root readOnly>
+       <!-- ... -->
+    </Slider.Root>
+  );
+}
+```
+
+#### disabled
+
+`Slider`의 `disabled`을 관리하는 상태입니다. `disabled`가 `true`일 경우 `Slider`의 조작이 불가합니다.
+
+```ts
+import { Slider } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+
+  return (
+    <Slider.Root disabled>
+       <!-- ... -->
+    </Slider.Root>
+  );
+}
+```
+
+#### invert
+
+`Slider`의 `invert`을 관리하는 상태입니다. `invert`가 `true`일 경우 `Slider`의 `value`의 색상이 반전됩니다.
+
+```ts
+import { Slider } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+
+  return (
+    <Slider.Root invert>
+       <!-- ... -->
+    </Slider.Root>
+  );
+}
+```
+
+#### min
+
+`Slider`의 `min`을 관리하는 상태입니다. 기본값으로 `0`입니다.
+
+`Slider`의 `value`의 최솟값을 지정합니다.
+
+```ts
+import { Slider } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+
+  return (
+    <Slider.Root min={0}>
+       <!-- ... -->
+    </Slider.Root>
+  );
+}
+```
+
+#### max
+
+`Slider`의 `max`을 관리하는 상태입니다. 기본값으로 `100`입니다.
+
+`Slider`의 `value`의 최댓값을 지정합니다.
+
+```ts
+import { Slider } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+
+  return (
+    <Slider.Root max={100}>
+       <!-- ... -->
+    </Slider.Root>
+  );
+}
+```
+
+#### step
+
+`Slider`의 `step`을 관리하는 상태입니다. 기본값으로 `10`입니다. 양수만 입력받아야 합니다.
+
+`Slider`의 `value`의 이동 간격을 지정합니다.
+
+```ts
+import { Slider } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+
+  return (
+    <Slider.Root step={10}>
+       <!-- ... -->
+    </Slider.Root>
+  );
+}
+```
+
+#### labelAlwaysOn
+
+`Slider`의 `labelAlwaysOn`을 관리하는 상태입니다. `true`일 경우 `label`이 항상 표시됩니다.
+
+```ts
+import { Slider } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+
+  return (
+    <Slider.Root labelAlwaysOn>
+       <!-- ... -->
+    </Slider.Root>
+  );
+}
+```
+
+#### marks
+
+`Slider`의 `marks`를 관리하는 상태입니다.
+
+`Slider.Progress`위에 지정된 위치에 `point`와 `label`을 표시해줍니다.
+
+`value`는 `<Slider.Progress/>`에서 위치할 비율입니다. `0 ~ 100`까지의 숫자로 값을 넣어야 합니다.
+
+`label`은 해당 위치에 `<Slider.Progress/>` 아래에 표현해줄 `text`입니다
+
+##### marksObjectType
+
+```ts
+{value:number, label: string}[]
+```
+
+해당 기능을 이용하기 위해서는 `<Slider.Marks/>` 아래 예시처럼 사용하여야 합니다.
+
+```ts
+import { Slider } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+
+  const marks = React.useMemo(
+    () => [
+      { value: 20, label: "20%" },
+      { value: 30, label: "30%" },
+      { value: 40, label: "40%" },
+      { value: 50, label: "50%" },
+      { value: 90, label: "90%" },
+    ],
+    []
+  );
+
+  return (
+    <Slider.Root marks={marks}>
+      <Slider.Progress>
+        <!-- ... -->
+        <Slider.Marks></Slider.Marks>
+      </Slider.Progress>
+    </Slider.Root>
+  );
+}
+```
+
+`🔔Tip: <Slider.Marks/> 컴포넌트는 <Slider.Progress/> 컴포넌트 내부에서 가장 마지막에 위치하는걸 권장합니다.`
+
+#### markActiveEffect
+
+`Slider`의 `markActiveEffect`를 관리하는 상태입니다.
+
+`marks`가 `value`에 포함되면 active되어있는 상태를 표현하기 위한 상태값입니다. 기본값은 `true` 입니다.
+
+해당 효과를 비활성화 하기위해서는 `false`를 주면 됩니다.
+
+```ts
+import { Slider } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+
+  const marks = React.useMemo(
+    () => [
+      { value: 20, label: "20%" },
+      { value: 30, label: "30%" },
+      { value: 40, label: "40%" },
+      { value: 50, label: "50%" },
+      { value: 90, label: "90%" },
+    ],
+    []
+  );
+
+  return (
+    <Slider.Root marks={marks} markActiveEffect={false}>
+      <Slider.Progress>
+        <!-- ... -->
+        <Slider.Marks></Slider.Marks>
+      </Slider.Progress>
+    </Slider.Root>
+  );
+}
+```
+
+#### labelAlwaysOn
+
+`Slider`의 `labelAlwaysOn`을 관리하는 상태입니다. `true`일 경우 `label`이 항상 표시됩니다.
+
+```ts
+import { Slider } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+
+  return (
+    <Slider.Root labelAlwaysOn>
+       <!-- ... -->
+    </Slider.Root>
+  );
+}
+```
+
+#### defaultValue
+
+`Slider`의 `defaultValue`을 관리하는 상태입니다.
+
+`Slider.Thumb`의 갯수만큼 숫자를 배열에 담아 기본값을 지정할 수 있습니다.
+
+```ts
+import { Slider } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+
+  return (
+    <Slider.Root defaultValue={[ 0, 10, 20]}>
+       <!-- ... -->
+    </Slider.Root>
+  );
+}
+```
+
+#### scale
+
+`Slider`의 `scale`을 관리하는 상태입니다.
+
+`value`의 값을 표현하기 위해 사용됩니다. 다음 예시에서 `value`가 2의 제곱으로 증가합니다.
+
+```ts
+import { Slider } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+
+  const valueLabelFormat = React.useCallback((value: number) => {
+    const units = ["KB", "MB", "GB", "TB"];
+
+    let unitIndex = 0;
+    let scaledValue = value;
+
+    while (scaledValue >= 1024 && unitIndex < units.length - 1) {
+      unitIndex += 1;
+      scaledValue /= 1024;
+    }
+
+    return `${scaledValue} ${units[unitIndex]}`;
+  }, []);
+
+  const getScale = React.useCallback((v: number) => 2 ** v, []);
+
+  return (
+    <Slider.Root
+      min={2}
+      max={30}
+      step={1}
+      label={valueLabelFormat}
+      scale={getScale}
+    >
+       <!-- ... -->
+    </Slider.Root>
+  );
+}
+```
+
+#### label
+
+`Slider`의 `label`을 관리하는 상태입니다.
+
+`Slider.Thumb`을 호버시에 나타나는 `label`의 문자를 표현할 수 있습니다.
+
+`null`값이 들어갈 시 `label`이 보이지 않습니다.
+
+```ts
+import { Slider } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+
+  return (
+    <Slider.Root label={(v) => `${v} m`}>
+       <!-- ... -->
+    </Slider.Root>
+  );
+}
+```
+
+#### onChange
+
+`Slider`의 `onChange`을 관리하는 상태입니다.
+
+`onChange`를 전달할 경우 `value`값에 대한 기본 컨트롤은 중단되며 `onChange`함수가 실행됩니다.
+
+`defaultValue`를 변경하기 위한 상태값과 기본 컨트롤 함수가 제공됩니다.
+
+`defaultSetChangeHandler`를 외부 set함수에 전달하면 기본 컨트롤 동작을 이용할 수 있습니다.
+
+##### onChangeProps
+
+```
+{
+  value: number;
+  idx: number;
+  min: number;
+  max: number;
+  step: number;
+  defaultSetChangeHandler: (curr: number[]) => number[];
+}
+```
+
+```ts
+import { Slider } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+
+  const [defaultMultiValue, setDefaultMultiValue] = React.useState([0, 10]);
+
+  return (
+    <Slider.Root
+      defaultValue={defaultMultiValue}
+      onChange={({ defaultSetChangeHandler }) =>
+        setDefaultMultiValue(defaultSetChangeHandler)
+      }
+    >
+       <!-- ... -->
+    </Slider.Root>
+  );
+}
+```
+
+`🔔Tip: onChange만 전달할 경우 value값이 변경되지 않으니 defaultValue와 같이 사용하는걸 권장합니다.`
+
+### Progress
+
+| Prop                                       |             Type             | Required | Default Value |
+| :----------------------------------------- | :--------------------------: | :------: | :-----------: |
+| [children](#children)                      |       React.ReactNode        |   true   |       -       |
+| [color](#color)                            | React.CSSProperties["color"] |    -     |   "#688DEE"   |
+| [className](#Progress-className)           |            string            |    -     |       -       |
+| [valueClassName](#Progress-valueClassName) |            string            |    -     |       -       |
+
+#### children
+
+`Progress`에 전달하기 위한 `children`입니다.
+
+`<Slider.Thumb/>`이 1개만 전달할 경우 `Progress`의 `value`가 왼쪽 끝 부터 표시됩니다.
+
+2개 이상일 경우 가장 `value`가 작은 것과 가장 큰 사이의 `value`의 range가 표시됩니다.
+
+```ts
+import { Slider } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+  return (
+    <Slider.Root>
+      <Slider.Progress>
+        <Slider.Thumb></Slider.Thumb>
+        <Slider.Thumb></Slider.Thumb>
+        <Slider.Marks></Slider.Marks>
+      </Slider.Progress>
+    </Slider.Root>
+  );
+};
+```
+
+#### color
+
+`Progress`의 `value`의 배경색으로 사용되는 `color`입니다.
+
+```ts
+import { Slider } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+  return (
+    <Slider.Root>
+      <Slider.Progress color="tomato">
+        <!-- ... -->
+      </Slider.Progress>
+    </Slider.Root>
+  );
+};
+```
+
+#### Progress-className
+
+`Progress`의 `style`을 조정하기 위한 `className`입니다.
+
+```ts
+import { Slider } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+  return (
+    <Slider.Root>
+      <Slider.Progress className="progressClass">
+        <!-- ... -->
+      </Slider.Progress>
+    </Slider.Root>
+  );
+};
+```
+
+#### Progress-valueClassName
+
+`Progress`의 `value`의 `style`을 조정하기 위한 `className`입니다.
+
+```ts
+import { Slider } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+  return (
+    <Slider.Root>
+      <Slider.Progress className="valueClass">
+        <!-- ... -->
+      </Slider.Progress>
+    </Slider.Root>
+  );
+};
+```
+
+### Thumb
+
+| Prop                          |                           Type                            | Required | Default Value |
+| :---------------------------- | :-------------------------------------------------------: | :------: | :-----------: |
+| [index](#index)               |                          number                           |    -     |       0       |
+| [className](#Thumb-className) |                          string                           |    -     |       -       |
+| [as](#Thumb-as)               | (props: [ThumbAsProps](#ThumbAsProps)) => React.ReactNode |    -     |       -       |
+| [children](#Thumb-children)   |                      React.ReactNode                      |    -     |       -       |
+
+#### index
+
+`Thumb`의 `index`입니다. 전달하지 않아도 자동으로 컴포넌트의 `index`가 들어가기에 사용하지 않아도 됩니다.
+
+#### Thumb-className
+
+`Thumb`에 전달하기 위한 `className`입니다.
+
+```ts
+import { Slider } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+  return (
+    <Slider.Root>
+      <Slider.Progress>
+        <Slider.Thumb className="ThumbClass"></Slider.Thumb>
+      </Slider.Progress>
+    </Slider.Root>
+  );
+};
+```
+
+#### Thumb-as
+
+`Thumb`의 `Point`를 대체하기 위한 `render-prop`입니다.
+
+##### ThumbAsProps
+
+```
+{
+  hidden: boolean;
+  isDragging: boolean;
+  children: React.ReactNode;
+  labelAlwaysOn?: boolean;
+  value?: string | number;
+}
+```
+
+```ts
+import { Slider } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+  return (
+    <Slider.Root>
+      <Slider.Progress>
+        <Slider.Thumb
+          className={cx("Thumb")}
+          as={({ labelAlwaysOn, hidden, isDragging, value, children }) => (
+            <div
+              className={cx("ThumbPointClass", {
+                labelAlwaysOn,
+                hidden,
+                isDragging,
+              })}
+              data-value={value}
+            >
+              {children}
+            </div>
+          )}
+        ></Slider.Thumb>
+      </Slider.Progress>
+    </Slider.Root>
+  );
+};
+```
+
+#### Thumb-children
+
+`Thumb`의 `point` 내부에 `children`을 전달하여 ui를 커스텀할 수 있습니다.
+
+```ts
+import { Slider, Icon } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+  return (
+    <Slider.Root>
+      <Slider.Progress>
+        <Slider.Thumb>
+          <Icon name="Settings" />
+        </Slider.Thumb>
+      </Slider.Progress>
+    </Slider.Root>
+  );
+};
+```
+
+### Marks
+
+| Prop                          |                           Type                            | Required | Default Value |
+| :---------------------------- | :-------------------------------------------------------: | :------: | :-----------: |
+| [className](#Marks-className) |                          string                           |    -     |       -       |
+| [as](#Marks-as)               | (props: [MarksAsProps](#MarksAsProps)) => React.ReactNode |    -     |       -       |
+
+#### Marks-className
+
+`Marks`에 전달하기 위한 `className`입니다.
+
+```ts
+import { Slider } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+  return (
+    <Slider.Root>
+      <Slider.Progress>
+        <Slider.Marks className="MarksClass"></Slider.Marks>
+      </Slider.Progress>
+    </Slider.Root>
+  );
+};
+```
+
+#### Marks-as
+
+`Marks`의 `point`를 대체하기 위한 `render-prop`입니다.
+
+##### MarksAsProps
+
+```
+{
+  label: string | number | React.ReactNode;
+  active: boolean;
+}
+```
+
+```ts
+import { Slider } from "@weing-dev/ui-kit-primitive";
+
+const components = () => {
+  return (
+    <Slider.Root>
+      <Slider.Progress>
+        <Slider.Marks
+          as={({ label, active }) => (
+            <div className={cx("MarkPoint")}>
+              <div className={cx("Label", { active })}>{label}</div>
+            </div>
+          )}
+        ></Slider.Marks>
+      </Slider.Progress>
+    </Slider.Root>
+  );
+};
+```
+
+## Example
+
+프로젝트를 실행하고 해당 [Link](http://localhost:3000/users/slider)에서 확인할 수 있습니다.