docs: 문서 수정 및 결론 추가

Kernel360 · Oct 18, 2024 · 84cece6 · 84cece6
1 parent 4ab4791
commit 84cece6
Showing 1 changed file with 107 additions and 31 deletions.
diff --git a/기술블로그/_posts/2024-10-11-floatingUI.md b/기술블로그/_posts/2024-10-11-floatingUI.md
@@ -4,7 +4,7 @@ title: "Floating UI 소개"
 author: "김승태"
 categories: "프론트엔드 기술블로그"
 banner:
-  image: 썸네일로 넣고 싶은 이미지 링크
+  image: assets/images/post/2023-11-05.webp
   background: "#000"
   height: "100vh"
   min_height: "38vh"
@@ -14,8 +14,6 @@ banner:
 
 ## Floating Element란?
 
-Floating UI를 소개하기 앞서 먼저 Floating Element에 대해서 말하고자 합니다.
-
 Floating Element는 화면의 기본적인 문서 흐름에서 벗어나서, 다른 콘텐츠 위에 배치되는 UI 요소들을 말합니다. 보통 사용자가 특정 상호작용을 할 때 동적으로 나타나며, 화면의 특정 부분에 위치해 있거나, 특정 기준 (마우스 위치, 텍스트 필드 등)에 따라 위치가 조정됩니다.
 
 여기서 말하는 floating element의 예시는 다음과 같습니다.
@@ -59,38 +57,85 @@ function App() {
 
 `refs.setFloating` 는 floating element에 사용하는 함수입니다.
 
-다양한 요구사항을 충족하기 위해 useFloating은 아래와 같은 다양한 return value와 option이 존재합니다. 자세한 예시는 [공식 문서](https://floating-ui.com/docs/useFloating)에 나와있습니다.
+다양한 요구사항을 충족하기 위해 useFloating은 아래와 같은 다양한 API와 옵션이 존재합니다. 자세한 예시는 [공식 문서](https://floating-ui.com/docs/useFloating)에 나와있습니다.
 
 **return value**
 
 ```tsx
 interface UseFloatingReturn {
+  /**
+   * 이 context에는 관련 Hook과 컴포넌트에 제공되는 컨텍스트 데이터가 포함되어 있습니다.
+   * useHover, useClick, useDismiss 등의 다른 hook을 사용할 때 해당 context를 이용합니다.
+   */
   context: FloatingContext;
-  // 이 context에는 관련 Hook과 컴포넌트에 제공되는 컨텍스트 데이터가 포함되어 있습니다.
-  // useHover, useClick, useDusmiss 등의 다른 hook을 사용할 때 해당 context를 이용합니다.
+
+  /**
+   * reference에 대한 floating의 최종 배치입니다.
+   * 옵션에서 전달된 것과 달리 이 옵션은 flip()과 같은 미들웨어에 의해 변경될 수 있습니다.
+   */
   placement: Placement;
-  // reference에 대한 floating 의 최종 배치입니다.
-  // 옵션에서 전달된 것과 달리 이 옵션은 flip()과 같은 미들웨어에 의해 변경될 수 있습니다.
-  strategy: Strategy; // floating element의 포지셔닝 전략입니다.
-  x: number; // floating element의 최종 x 좌표입니다.
-  y: number; // floating element의 최종 y 좌표입니다.
-  middlewareData: MiddlewareData; // 사용된 미들웨어에서 제공하는 데이터입니다.
-  isPositioned: boolean; // floating element가 아직 위치가 지정되지 않았는지 여부입니다.
-  update(): void; // floating element의 위치를 수동으로 업데이트하는 함수입니다.
-  floatingStyles: React.CSSProperties; // floating element에 적용해야 하는 스타일입니다.
-  // inline으로 적용합니다. ex) <div style={...floatingStyles} />
+
+  /**
+   * floating element의 최종 x 좌표입니다.
+   */
+  strategy: Strategy;
+
+  /**
+   * floating element의 최종 x 좌표입니다.
+   */
+  x: number;
+
+  /**
+   * floating element의 최종 y 좌표입니다.
+   */
+  y: number;
+
+  /**
+   * 사용된 미들웨어에서 제공하는 데이터입니다.
+   */
+  middlewareData: MiddlewareData;
+
+  /**
+   * floating element가 아직 위치가 지정되지 않았는지 여부입니다.
+   */
+  isPositioned: boolean;
+
+  /**
+   * floating element의 위치를 수동으로 업데이트하는 함수입니다.
+   */
+  update(): void;
+
+  /**
+   * floating element에 적용해야 하는 스타일입니다.
+   * inline으로 적용합니다. 예: <div style={...floatingStyles} />
+   */
+  floatingStyles: React.CSSProperties;
+
   refs: {
+    /**
+     * reference로 지정한 element입니다. 예: ref.reference.current?
+     */
     reference: React.MutableRefObject<ReferenceElement | null>;
-    // reference로 지정한 element 입니다. ex) ref.reference.current?
+
+    /**
+     * floating으로 지정한 element입니다.
+     */
     floating: React.MutableRefObject<HTMLElement | null>;
-    // floating로 지정한 element 입니다
+
+    /**
+     * DOM reference element(사용 가능한 경우)에 대한 ref를 추가합니다.
+     * 이벤트 핸들러 내부 또는 이펙트에서 액세스할 수 있습니다.
+     */
     domReference: React.MutableRefObject<Element | null>;
-    // DOM reference element(사용 가능한 경우)에 대한 ref를 추가합니다.
-    // 이벤트 핸들러 내부 또는 이펙트에서 액세스할 수 있습니다.
-    setReference(node: RT | null): void; //  reference element를 설정하는 함수입니다.
+
+    /**
+     * reference element를 설정하는 함수입니다.
+     */
+    setReference(node: RT | null): void;
     setFloating(node: HTMLElement | null): void;
     setPositionReference(node: ReferenceElement): void;
   };
+
   elements: {
     reference: RT | null;
     floating: HTMLElement | null;
@@ -102,18 +147,44 @@ interface UseFloatingReturn {
 
 ```tsx
 interface UseFloatingOptions {
-  placement?: Placement; // reference element에 대한  floating element의 배치입니다.
-  // ex) 'top', 'right' 등등 setReference 의 어느 곳에 보여질지 정합니다.
-  strategy?: 'fixed' | 'absolute'; // 사용할 CSS 위치 속성 유형입니다.
-  transform?: boolean; // floating element의 위치를 지정하기 위해 CSS 트랜스폼을 사용할지 여부
-  // 인라일 스타일을 부여해서 placement의 위치를 잡습니다.
+  /**
+   * reference element에 대한 floating element의 배치입니다.
+   * 예: 'top', 'right' 등등 setReference의 어느 곳에 보여질지 정합니다.
+   */
+  placement?: Placement;
+
+  /**
+   * 사용할 CSS 위치 속성 유형입니다.
+   * 예: 'fixed' | 'absolute'.
+   */
+  strategy?: 'fixed' | 'absolute';
+
+  /**
+   * floating element의 위치를 지정하기 위해 CSS 트랜스폼을 사용할지 여부입니다.
+   * 인라인 스타일을 부여하여 placement의 위치를 잡습니다.
+   */
+  transform?: boolean;
+
+  /**
+   * floating element의 위치를 변경하는 미들웨어 객체 배열입니다.
+   */
   middleware?: Array<Middleware | undefined | null | false>;
-  // floating element의 위치를 변경하는 미들웨어 객체 배열입니다.
-  open?: boolean; // floating element가 열려 있는지 여부
-  onOpenChange?( // open 상태가 변경되어야 할 때 호출되는 함수입니다.
+
+  /**
+   * floating element가 열려 있는지 여부입니다.
+   */
+  open?: boolean;
+
+  /**
+   * open 상태가 변경되어야 할 때 호출되는 함수입니다.
+   * @param open - 현재 open 상태
+   * @param event - 이벤트 객체 (ex: MouseEvent)
+   * @param reason - 상태 변경의 이유 (ex: 'hover', 'click')
+   */
+  onOpenChange?(
     open: boolean,
-    event?: Event,  // e.g. MouseEvent
-    reason?: OpenChangeReason, // e.g. 'hover', 'click'
+    event?: Event,
+    reason?: OpenChangeReason,
   ): void;
   elements?: {
     reference?: ReferenceElement | null;
@@ -144,6 +215,11 @@ useFloating({
 });
 ```
 
+## 결론
+
+Floating UI는 floating element를 쉽게 구현하고, 관리할 수 있는 라이브리리이며 더욱 세밀한 조정을 위한 미들웨어까지 제공합니다.
+floating element가 필요하다면 Floating UI를 한번 고려해보세요.
+
 ## 출처
 
 [공식문서](https://floating-ui.com/)