@modern-kit/react
Version:
1 lines • 5.45 kB
Source Map (JSON)
{"version":3,"file":"index.cjs","sources":["../../../src/components/OutsidePointerDownHandler/index.tsx"],"sourcesContent":["import React from 'react';\nimport { ReactNode } from 'react';\nimport { useOutsidePointerDown } from '../../hooks/useOutsidePointerDown';\nimport { useMergeRefs } from '../../hooks/useMergeRefs';\nimport { polymorphicForwardRef } from '../../utils/polymorphicForwardRef';\nimport { Slot } from '../Slot';\n\ninterface OutsidePointerDownHandlerProps {\n children: ReactNode;\n onPointerDown: (targetElement: HTMLElement) => void;\n excludeRefs?: React.RefObject<HTMLElement>[];\n asChild?: boolean;\n}\n\nconst OUTSIDE_POINTER_DOWN_HANDLER_ERROR_MESSAGE =\n 'OutsidePointerDownHandler는 asChild가 true일 경우 children으로 유효한 React 요소만을 허용합니다. 또한, 단일 요소만 허용합니다.';\n\n/**\n * @description `OutsidePointerDownHandler`는 컴포넌트 외부 영역 클릭 및 터치를 감지하여 `onPointerDown` 함수를 호출하는 컴포넌트입니다.\n *\n * @modern-kit/react의 `useOutsidePointerDown` 훅을 기반으로 구현됐습니다.\n *\n * @see https://modern-agile-team.github.io/modern-kit/docs/react/hooks/useOutsidePointerDown\n *\n * `as` 속성을 통해 `다형성(polymorphism)`을 지원합니다:\n * - 기본적으로 `div` 태그로 자식 요소를 감싸서 렌더링하며, `as` 속성을 통해 감싸는 Wrapper 요소의 태그를 변경해 렌더링할 수 있습니다. (ex. div -> article)\n * - 이때, 해당 Wrapper 요소의 외부 영역을 클릭 혹은 터치 시 `onPointerDown` 콜백 함수가 호출됩니다.\n *\n * `asChild` 속성을 통해 `합성(Composition)`, `렌더링 위임(Rendering Delegation)` 패턴을 지원합니다:\n * - `asChild` 속성이 `true`라면 `Slot`을 통해 래퍼 요소 없이 자식 요소를 렌더링합니다.\n * - 이때, 자식 요소의 외부 영역을 클릭 혹은 터치 시 `onPointerDown` 콜백 함수가 호출됩니다.\n * - `asChild`를 사용 할 경우 아래 링크를 참고하세요.\n *\n * @see https://modern-agile-team.github.io/modern-kit/docs/react/components/Slot\n *\n * @param {OutsidePointerDownHandlerProps} props - OutsidePointerDownHandler 컴포넌트의 속성입니다.\n * @param {string} [props.as='div'] - 자식 요소를 감싸는 요소를 지정합니다. 기본 값은 `div`입니다. 해당 요소 외부를 클릭 혹은 터치 시 onPointerDown 함수가 호출됩니다.\n * @param {boolean} [props.asChild=false] - `true`일 경우 `Slot`을 통해 자식 요소를 그대로 렌더링하고, 해당 자식 요소 외부를 클릭 혹은 터치 시 onPointerDown 함수가 호출됩니다.\n * @param {() => void} props.onPointerDown - 외부 영역 클릭 혹은 터치 시 실행될 함수\n * @param {React.RefObject<HTMLElement>[]} [props.excludeRefs] - 외부 클릭 및 터치 감지를 제외할 요소의 ref 배열입니다.\n * @param {ReactNode} props.children - 자식 컴포넌트\n *\n * @returns {JSX.Element} 외부 영역 클릭 혹은 터치 시 onPointerDown 함수가 호출되는 컴포넌트를 반환합니다.\n *\n * @example\n * ```tsx\n * // default\n * <OutsidePointerDownHandler onPointerDown={onPointerDown}>\n * <div>Contents</div>\n * </OutsidePointerDownHandler>\n *\n * // excludeRefs 속성을 통해 외부 클릭 및 터치 감지를 제외할 요소를 지정할 수 있습니다.\n * <div>\n * <OutsidePointerDownHandler onPointerDown={onPointerDown} excludeRefs={[excludeRef]}>\n * <div>Contents</div>\n * </OutsidePointerDownHandler>\n * <div ref={excludeRef}>Exclude Box</div>\n * </div>\n * ```\n *\n * @example\n * // as: ul\n * <OutsidePointerDownHandler as='ul' onPointerDown={onPointerDown}>\n * <li>List Item1</li>\n * <li>List Item2</li>\n * </OutsidePointerDownHandler>\n *\n * @example\n * // asChild\n * <OutsidePointerDownHandler asChild onPointerDown={onPointerDown}>\n * <input type=\"text\" />\n * </OutsidePointerDownHandler>\n */\nexport const OutsidePointerDownHandler = polymorphicForwardRef<\n 'div',\n OutsidePointerDownHandlerProps\n>(\n (\n {\n children,\n as = 'div',\n asChild = false,\n onPointerDown,\n excludeRefs = [],\n ...props\n },\n ref\n ) => {\n const { ref: targetRef } = useOutsidePointerDown<HTMLElement>(\n onPointerDown,\n {\n excludeRefs,\n }\n );\n\n const Wrapper = asChild ? Slot : as;\n\n if (asChild && !React.isValidElement(children)) {\n throw new Error(OUTSIDE_POINTER_DOWN_HANDLER_ERROR_MESSAGE);\n }\n\n return (\n <Wrapper ref={useMergeRefs(targetRef, ref)} {...props}>\n {children}\n </Wrapper>\n );\n }\n);\n"],"names":["polymorphicForwardRef","useOutsidePointerDown","Slot","jsx","useMergeRefs"],"mappings":";;;;;;;;;;;;;;AAcA,MAAM,0CAAA,GACJ,4PAAA;AA0DK,MAAM,yBAAA,GAA4BA,gDAAA;AAAA,EAIvC,CACE;AAAA,IACE,QAAA;AAAA,IACA,EAAA,GAAK,KAAA;AAAA,IACL,OAAA,GAAU,KAAA;AAAA,IACV,aAAA;AAAA,IACA,cAAc,EAAC;AAAA,IACf,GAAG;AAAA,KAEL,GAAA,KACG;AACH,IAAA,MAAM,EAAE,GAAA,EAAK,SAAA,EAAU,GAAIC,gDAAA;AAAA,MACzB,aAAA;AAAA,MACA;AAAA,QACE;AAAA;AACF,KACF;AAEA,IAAA,MAAM,OAAA,GAAU,UAAUC,mBAAA,GAAO,EAAA;AAEjC,IAAA,IAAI,OAAA,IAAW,CAAC,KAAA,CAAM,cAAA,CAAe,QAAQ,CAAA,EAAG;AAC9C,MAAA,MAAM,IAAI,MAAM,0CAA0C,CAAA;AAAA,IAC5D;AAEA,IAAA,uBACEC,cAAA,CAAC,WAAQ,GAAA,EAAKC,8BAAA,CAAa,WAAW,GAAG,CAAA,EAAI,GAAG,KAAA,EAC7C,QAAA,EACH,CAAA;AAAA,EAEJ;AACF;;;;"}