@machinerd/js-module 0.3.0 → 0.4.0

package/README.md

@@ -1,43 +1,169 @@
-# JS-Module
+# @machinerd/js-module
 
-- install
+React용 공용 UI·훅·유틸·API 클라이언트 패키지입니다.
+
+**현재 버전:** `0.4` (`package.json`의 `version` 필드와 동일합니다. 배포 전에는 해당 값을 확인하세요.)
+
+**Peer dependency:** `react`, `react-dom` — `^18.3.1` 또는 `^19.0.0`
+
+---
+
+## 설치
 
 ```bash
+pnpm add @machinerd/js-module
+# 또는
 npm install @machinerd/js-module
-# or
 yarn add @machinerd/js-module
-# or
-pnpm add @machinerd/js-module
 ```
 
-- api client
+스타일을 쓰는 UI를 사용한다면 CSS도 함께 import 합니다.
 
 ```js
-import apiClient from "@machinerd/js-module";
+import '@machinerd/js-module/styles/index.css';
 ```
 
-- function
+---
 
-```js
-import { sleep } from "@machinerd/js-module/util";
+## API 클라이언트 (`@machinerd/js-module`)
+
+기본 export는 `ApiClient` 클래스입니다. 인스턴스를 만들어 props나 훅 인자로 넘깁니다.
+
+```ts
+import ApiClient, { type ApiConfig } from '@machinerd/js-module';
+
+const client = new ApiClient({
+  apiEndpoint: 'https://api.example.com',
+  cdnEndpoint: 'https://cdn.example.com',
+});
+
+await client.login(/* ... */);
+client.cdnMedia('path/to/key');
 ```
 
-- components
+일부 UI·훅은 **`ApiClient` 인스턴스**를 인자로 받습니다. 앱 구조에 맞게 한 번 생성해 전달하면 됩니다.
 
-```js
-import { Button } from "@machinerd/js-module/ui";
-import "@machinerd/js-module/styles/index.css";
+---
+
+## UI 컴포넌트 (`@machinerd/js-module/ui`)
+
+서버·클라이언트 구분 없이 쓸 수 있는 컴포넌트입니다.
+
+```tsx
+import {
+  BottomAppBar,
+  Button,
+  ConditionalWrapper,
+  Input,
+  Skeleton,
+} from '@machinerd/js-module/ui';
+import '@machinerd/js-module/styles/index.css';
 ```
 
-- components (client-side only)
+각 컴포넌트의 props·변형은 Storybook(`pnpm storybook`) 또는 소스의 타입 정의를 참고하면 됩니다.
 
-```js
-import { Carousel } from "@machinerd/js-module/ui/client";
-import "@machinerd/js-module/styles/index.css";
+---
+
+## 클라이언트 전용 UI (`@machinerd/js-module/ui-client`)
+
+브라우저 API·상태에 의존하는 컴포넌트입니다. **번들/페이지의 클라이언트 경계 안**에서만 사용하세요.
+
+```tsx
+import { Carousel, CarouselItem, Image, Tooltip /* … */ } from '@machinerd/js-module/ui-client';
+import '@machinerd/js-module/styles/index.css';
 ```
 
-- hooks
+`Image` 등은 `ApiClient` 인스턴스·CDN 상대 경로 등 앱 설정이 필요합니다. 자세한 props는 타입 정의와 Storybook 문서를 참고하세요.
 
-```js
-import { useOutsideClick } from "@machinerd/js-module/hooks";
+> **참고:** export 경로는 `ui/client`가 아니라 **`ui-client`** 입니다 (`package.json`의 `exports`와 일치).
+
+---
+
+## 훅 (`@machinerd/js-module/hooks`)
+
+```ts
+import { useOutsideClick, useWindowSize } from '@machinerd/js-module/hooks';
+```
+
+`useOutsideClick`은 타입 `UseOutsideClickProps`도 함께 export 합니다.
+
+---
+
+## 유틸 (`@machinerd/js-module/util`)
+
+`browser`, `common`, `date`, `file`, `format`, `generator` 등 모듈에서 필요한 심볼을 re-export 합니다.
+
+```ts
+import { formatI18nNumber } from '@machinerd/js-module/util';
+import { isExternalSrc } from '@machinerd/js-module/util';
 ```
+
+전체 목록은 `src/util/index.ts`를 보거나 IDE 자동완성으로 확인하는 것이 좋습니다.
+
+---
+
+## 로컬 개발·다른 프로젝트에서 검증
+
+### 1. 이 저장소에서 빌드
+
+```bash
+pnpm install
+pnpm build
+```
+
+`prepublishOnly`에 `pnpm build`가 걸려 있어 `pnpm publish` 전에도 빌드가 돌지만, pack 테스트 전에 한 번 빌드하는 것을 권장합니다.
+
+### 2. tarball로 다른 프로젝트에 넣기 (`pnpm pack`)
+
+```bash
+pnpm pack
+```
+
+현재 버전 기준으로 예: `machinerd-js-module-0.4.0.tgz` 형태의 파일이 상위 디렉터리(또는 현재 디렉터리)에 생성됩니다. 정확한 파일명은 명령 출력을 따르세요.
+
+소비하는 프로젝트에서:
+
+```bash
+pnpm add /절대/또는/상대/경로/machinerd-js-module-0.4.0.tgz
+```
+
+또는 `package.json`에:
+
+```json
+{
+  "dependencies": {
+    "@machinerd/js-module": "file:../js-module/machinerd-js-module-0.4.0.tgz"
+  }
+}
+```
+
+### 3. `pnpm link` (글로벌 링크)
+
+```bash
+# js-module 쪽
+pnpm link --global
+
+# 소비 프로젝트 쪽
+pnpm link --global @machinerd/js-module
+```
+
+워크스페이스 모노레포라면 `pnpm-workspace.yaml`에 패키지 경로를 넣고 `workspace:*` 의존성으로 연결하는 방식이 더 안정적입니다.
+
+### 4. Storybook으로 UI만 확인
+
+```bash
+pnpm storybook
+```
+
+---
+
+## 스크립트 요약
+
+| 명령 | 설명 |
+|------|------|
+| `pnpm build` | 라이브러리 + CSS 빌드 |
+| `pnpm storybook` | 컴포넌트 문서·예제 (로컬) |
+| `pnpm build-storybook` | 정적 Storybook 빌드 |
+| `pnpm pack` | npm 패키지 tarball 생성 (로컬 설치 테스트용) |
+
+---

package/dist/hooks/index.cjs

@@ -1 +1 @@
-const e=require(`../hooks-DPYIex_y.cjs`);exports.useOutsideClick=e.t,exports.useWindowSize=e.n;
+require(`../util-BMnQ9hLK.cjs`);const e=require(`../hooks-B6OJ8mCP.cjs`);exports.SUBSETS=e.n,exports.useDelayUnmount=e.c,exports.useDragScroll=e.s,exports.useOutsideClick=e.o,exports.useScrollLock=e.a,exports.useScrollTop=e.i,exports.useSubsetImage=e.r,exports.useWindowSize=e.t;

package/dist/hooks/index.d.cts

@@ -1,18 +1,3 @@
-import { Dispatch, RefObject, SetStateAction } from "react";
-
-//#region src/hooks/use-window-size.d.ts
-declare function useWindowSize(defaultWidth?: number): {
-  windowSize: number;
-};
-//#endregion
-//#region src/hooks/use-outside-click.d.ts
-interface UseOutsideClickProps {
-  ref: RefObject<HTMLElement | null>;
-  setOpen: Dispatch<SetStateAction<boolean>>;
-}
-declare function useOutsideClick({
-  ref,
-  setOpen
-}: UseOutsideClickProps): void;
-//#endregion
-export { type UseOutsideClickProps, useOutsideClick, useWindowSize };
+import { a as UseSubsetImageProps, c as UseScrollTopProps, d as useScrollLock, f as UseOutsideClickProps, h as useDelayUnmount, i as SUBSETS, l as useScrollTop, m as useDragScroll, n as BaseProps, o as UseSubsetImagePropsWithoutApiClient, p as useOutsideClick, r as Folder, s as useSubsetImage, t as useWindowSize, u as UseScrollLockProps } from "../index-CWgr7lXX.cjs";
+import "../index-OjfbEYpE.cjs";
+export { BaseProps, Folder, SUBSETS, UseOutsideClickProps, UseScrollLockProps, UseScrollTopProps, UseSubsetImageProps, UseSubsetImagePropsWithoutApiClient, useDelayUnmount, useDragScroll, useOutsideClick, useScrollLock, useScrollTop, useSubsetImage, useWindowSize };

package/dist/hooks/index.d.mts

@@ -1,18 +1,3 @@
-import { Dispatch, RefObject, SetStateAction } from "react";
-
-//#region src/hooks/use-window-size.d.ts
-declare function useWindowSize(defaultWidth?: number): {
-  windowSize: number;
-};
-//#endregion
-//#region src/hooks/use-outside-click.d.ts
-interface UseOutsideClickProps {
-  ref: RefObject<HTMLElement | null>;
-  setOpen: Dispatch<SetStateAction<boolean>>;
-}
-declare function useOutsideClick({
-  ref,
-  setOpen
-}: UseOutsideClickProps): void;
-//#endregion
-export { type UseOutsideClickProps, useOutsideClick, useWindowSize };
+import { a as UseSubsetImageProps, c as UseScrollTopProps, d as useScrollLock, f as UseOutsideClickProps, h as useDelayUnmount, i as SUBSETS, l as useScrollTop, m as useDragScroll, n as BaseProps, o as UseSubsetImagePropsWithoutApiClient, p as useOutsideClick, r as Folder, s as useSubsetImage, t as useWindowSize, u as UseScrollLockProps } from "../index-CfKO4Lbp.mjs";
+import "../index-DiZ4xS_f.mjs";
+export { BaseProps, Folder, SUBSETS, UseOutsideClickProps, UseScrollLockProps, UseScrollTopProps, UseSubsetImageProps, UseSubsetImagePropsWithoutApiClient, useDelayUnmount, useDragScroll, useOutsideClick, useScrollLock, useScrollTop, useSubsetImage, useWindowSize };

package/dist/hooks/index.mjs

@@ -1 +1 @@
-import{n as e,t}from"../hooks-C9M3V-Pb.mjs";export{t as useOutsideClick,e as useWindowSize};
+import"../util-BNSPNLzy.mjs";import{a as e,c as t,i as n,n as r,o as i,r as a,s as o,t as s}from"../hooks-Dr3L4nS9.mjs";export{r as SUBSETS,t as useDelayUnmount,o as useDragScroll,i as useOutsideClick,e as useScrollLock,n as useScrollTop,a as useSubsetImage,s as useWindowSize};

package/dist/hooks-B6OJ8mCP.cjs

@@ -0,0 +1 @@
+const e=require(`./chunk-Bmb41Sf3.cjs`),t=require(`./util-BMnQ9hLK.cjs`);let n=require(`lodash-es`),r=require(`react`);function i(e,t){let[n,i]=(0,r.useState)(!1);return(0,r.useEffect)(()=>{let r;return e&&!n?i(!0):!e&&n&&(r=setTimeout(()=>i(!1),t)),()=>clearTimeout(r)},[e,t,n]),n}function a(e=1){let t=(0,r.useRef)(null),[n,i]=(0,r.useState)(!1),[a,o]=(0,r.useState)(0),[s,c]=(0,r.useState)(0),l=(0,r.useRef)(!1);return{ref:t,onMouseDown:e=>{t.current&&(i(!0),l.current=!1,o(e.pageX-t.current.offsetLeft),c(t.current.scrollLeft))},onMouseLeave:()=>i(!1),onMouseUp:()=>i(!1),onMouseMove:r=>{if(!n||!t.current)return;r.preventDefault();let i=(r.pageX-t.current.offsetLeft-a)*e;Math.abs(i)>10&&(l.current=!0),t.current.scrollLeft=s-i},onClickCapture:e=>{l.current&&(e.stopPropagation(),e.preventDefault())}}}function o({ref:e,setOpen:t}){let n=(0,r.useCallback)(n=>{e.current?.contains(n.target)||t(!1)},[e,t]);(0,r.useEffect)(()=>(document.addEventListener(`mousedown`,n),document.addEventListener(`touchstart`,n),()=>{document.removeEventListener(`mousedown`,n),document.removeEventListener(`touchstart`,n)}),[n])}const s=[`mouse`,`touch`];function c({open:e,type:t=s}){let n=(0,r.useCallback)(e=>{e.preventDefault()},[]),i=(0,r.useCallback)(e=>{e.preventDefault()},[]);(0,r.useEffect)(()=>{let r=e&&t.includes(`mouse`),a=e&&t.includes(`touch`);return r?(document.body.classList.add(`overflow-hidden`),document.addEventListener(`wheel`,i,{passive:!1})):(document.body.classList.remove(`overflow-hidden`),document.removeEventListener(`wheel`,i)),a?document.addEventListener(`touchmove`,n,{passive:!1}):document.removeEventListener(`touchmove`,n),()=>{document.body.classList.remove(`overflow-hidden`),document.removeEventListener(`touchmove`,n),document.removeEventListener(`wheel`,i)}},[e,t,n,i])}function l({enabled:e=!0,behavior:t=`smooth`}={}){let[n,i]=(0,r.useState)(!1),a=(0,r.useRef)(null),o=(0,r.useCallback)(()=>{window.scrollTo({top:0,behavior:t})},[t]);return(0,r.useEffect)(()=>{let t=a.current;if(!t||!e){i(!1);return}let n=new IntersectionObserver(e=>{let t=e[0];t&&i(!t.isIntersecting)},{root:null,rootMargin:`0px`,threshold:0});return n.observe(t),()=>n.disconnect()},[e]),{isVisible:n,handleScrolToTop:o,ref:a}}const u=[12,120,240,300,406,512,612,768,960,1024,1280,1440,1560,1920,2560,3840];function d({ref:e,src:n,forceLoad:i=!1,folder:a=`media`,fallbackSrc:o,origin:s,originalWidth:c,loading:l=`lazy`,apiClient:d,...f}){let[p,m]=(0,r.useState)(0),[h,g]=(0,r.useState)(i||!n),[_,v]=(0,r.useState)(!n),y=(0,r.useRef)(null),b=(0,r.useRef)(null),x=(0,r.useCallback)(t=>{y.current=t,typeof e==`function`?e(t):e&&(e.current=t)},[e]),S=(0,r.useCallback)((e,t)=>{let n=e.startsWith(`/`)?e.slice(1):e;return t===`static`?d.cdnStatic(n):d.cdnMedia(n)},[d]),C=(0,r.useMemo)(()=>u.filter(e=>e<=c),[c]),w=(0,r.useMemo)(()=>t.m(n)?n:S(n,a),[S,n,a]),T=(0,r.useMemo)(()=>{if(s||!t.h(n)||C.length===0)return;let{filenameWithoutExtension:e,directory:r}=t.g(n,a);if(f.width){let t=C.find(e=>e>=f.width)??C[C.length-1],n=t*2,i=C.find(e=>e>=n)??C[C.length-1];return`${S(`${r}/subsets/w${t}/${e}.webp`,a)} 1x,${S(`${r}/subsets/w${i}/${e}.webp`,a)} 2x`}let i=``;for(let t of C)i+=`${S(`${r}/subsets/w${t}/${e}.webp`,a)} ${t}w, `;return i.trim()},[C,S,a,s,n,f.width]),E=(0,r.useCallback)((e,n)=>{let{filenameWithoutExtension:r,directory:i}=t.g(e,n);return`${S(`${i}/subsets/origin/${r}.webp`,n)}`},[S]),D=(0,r.useMemo)(()=>{if(n)return`${E(n,a)} 1x`},[n,a,E]),O=(0,r.useCallback)(e=>{m(t=>t>=2?(e&&(b.current=e),3):t+1)},[]),k=(()=>{if(p===0)return T;if(p===1)return D}),A=p>=3?o:w,j=p===0?f.sizes:void 0,M=p>0?`eager`:l;(0,r.useEffect)(()=>{p<3||v(!0)},[p]),(0,r.useEffect)(()=>{let e=y.current;if(!e||_)return;if(e.complete&&e.naturalWidth===0&&e.getAttribute(`src`)){O();return}if(e.complete&&e.naturalWidth>0){g(!0);return}let t=()=>{e.naturalWidth>0&&g(!0)};return e.addEventListener(`load`,t),()=>e.removeEventListener(`load`,t)},[_,p,O]);let{fill:N,...P}=f;return{ref:x,isLoad:h,isError:_,imageProps:{...P,src:A,srcSet:k(),sizes:j,loading:M,onError:_?void 0:O}}}function f(e=1280){let[t,i]=(0,r.useState)(e);return(0,r.useEffect)(()=>{let e=(0,n.throttle)(()=>{let e=window.innerWidth;i(e)},200);return window.addEventListener(`resize`,e),e(),()=>window.removeEventListener(`resize`,e)},[]),{windowSize:t}}Object.defineProperty(exports,`a`,{enumerable:!0,get:function(){return c}}),Object.defineProperty(exports,`c`,{enumerable:!0,get:function(){return i}}),Object.defineProperty(exports,`i`,{enumerable:!0,get:function(){return l}}),Object.defineProperty(exports,`n`,{enumerable:!0,get:function(){return u}}),Object.defineProperty(exports,`o`,{enumerable:!0,get:function(){return o}}),Object.defineProperty(exports,`r`,{enumerable:!0,get:function(){return d}}),Object.defineProperty(exports,`s`,{enumerable:!0,get:function(){return a}}),Object.defineProperty(exports,`t`,{enumerable:!0,get:function(){return f}});

package/dist/hooks-Dr3L4nS9.mjs

@@ -0,0 +1 @@
+import{g as e,h as t,m as n}from"./util-BNSPNLzy.mjs";import{throttle as r}from"lodash-es";import{useCallback as i,useEffect as a,useMemo as o,useRef as s,useState as c}from"react";function l(e,t){let[n,r]=c(!1);return a(()=>{let i;return e&&!n?r(!0):!e&&n&&(i=setTimeout(()=>r(!1),t)),()=>clearTimeout(i)},[e,t,n]),n}function u(e=1){let t=s(null),[n,r]=c(!1),[i,a]=c(0),[o,l]=c(0),u=s(!1);return{ref:t,onMouseDown:e=>{t.current&&(r(!0),u.current=!1,a(e.pageX-t.current.offsetLeft),l(t.current.scrollLeft))},onMouseLeave:()=>r(!1),onMouseUp:()=>r(!1),onMouseMove:r=>{if(!n||!t.current)return;r.preventDefault();let a=(r.pageX-t.current.offsetLeft-i)*e;Math.abs(a)>10&&(u.current=!0),t.current.scrollLeft=o-a},onClickCapture:e=>{u.current&&(e.stopPropagation(),e.preventDefault())}}}function d({ref:e,setOpen:t}){let n=i(n=>{e.current?.contains(n.target)||t(!1)},[e,t]);a(()=>(document.addEventListener(`mousedown`,n),document.addEventListener(`touchstart`,n),()=>{document.removeEventListener(`mousedown`,n),document.removeEventListener(`touchstart`,n)}),[n])}const f=[`mouse`,`touch`];function p({open:e,type:t=f}){let n=i(e=>{e.preventDefault()},[]),r=i(e=>{e.preventDefault()},[]);a(()=>{let i=e&&t.includes(`mouse`),a=e&&t.includes(`touch`);return i?(document.body.classList.add(`overflow-hidden`),document.addEventListener(`wheel`,r,{passive:!1})):(document.body.classList.remove(`overflow-hidden`),document.removeEventListener(`wheel`,r)),a?document.addEventListener(`touchmove`,n,{passive:!1}):document.removeEventListener(`touchmove`,n),()=>{document.body.classList.remove(`overflow-hidden`),document.removeEventListener(`touchmove`,n),document.removeEventListener(`wheel`,r)}},[e,t,n,r])}function m({enabled:e=!0,behavior:t=`smooth`}={}){let[n,r]=c(!1),o=s(null),l=i(()=>{window.scrollTo({top:0,behavior:t})},[t]);return a(()=>{let t=o.current;if(!t||!e){r(!1);return}let n=new IntersectionObserver(e=>{let t=e[0];t&&r(!t.isIntersecting)},{root:null,rootMargin:`0px`,threshold:0});return n.observe(t),()=>n.disconnect()},[e]),{isVisible:n,handleScrolToTop:l,ref:o}}const h=[12,120,240,300,406,512,612,768,960,1024,1280,1440,1560,1920,2560,3840];function g({ref:r,src:l,forceLoad:u=!1,folder:d=`media`,fallbackSrc:f,origin:p,originalWidth:m,loading:g=`lazy`,apiClient:_,...v}){let[y,b]=c(0),[x,S]=c(u||!l),[C,w]=c(!l),T=s(null),E=s(null),D=i(e=>{T.current=e,typeof r==`function`?r(e):r&&(r.current=e)},[r]),O=i((e,t)=>{let n=e.startsWith(`/`)?e.slice(1):e;return t===`static`?_.cdnStatic(n):_.cdnMedia(n)},[_]),k=o(()=>h.filter(e=>e<=m),[m]),A=o(()=>n(l)?l:O(l,d),[O,l,d]),j=o(()=>{if(p||!t(l)||k.length===0)return;let{filenameWithoutExtension:n,directory:r}=e(l,d);if(v.width){let e=k.find(e=>e>=v.width)??k[k.length-1],t=e*2,i=k.find(e=>e>=t)??k[k.length-1];return`${O(`${r}/subsets/w${e}/${n}.webp`,d)} 1x,${O(`${r}/subsets/w${i}/${n}.webp`,d)} 2x`}let i=``;for(let e of k)i+=`${O(`${r}/subsets/w${e}/${n}.webp`,d)} ${e}w, `;return i.trim()},[k,O,d,p,l,v.width]),M=i((t,n)=>{let{filenameWithoutExtension:r,directory:i}=e(t,n);return`${O(`${i}/subsets/origin/${r}.webp`,n)}`},[O]),N=o(()=>{if(l)return`${M(l,d)} 1x`},[l,d,M]),P=i(e=>{b(t=>t>=2?(e&&(E.current=e),3):t+1)},[]),F=(()=>{if(y===0)return j;if(y===1)return N}),I=y>=3?f:A,L=y===0?v.sizes:void 0,R=y>0?`eager`:g;a(()=>{y<3||w(!0)},[y]),a(()=>{let e=T.current;if(!e||C)return;if(e.complete&&e.naturalWidth===0&&e.getAttribute(`src`)){P();return}if(e.complete&&e.naturalWidth>0){S(!0);return}let t=()=>{e.naturalWidth>0&&S(!0)};return e.addEventListener(`load`,t),()=>e.removeEventListener(`load`,t)},[C,y,P]);let{fill:z,...B}=v;return{ref:D,isLoad:x,isError:C,imageProps:{...B,src:I,srcSet:F(),sizes:L,loading:R,onError:C?void 0:P}}}function _(e=1280){let[t,n]=c(e);return a(()=>{let e=r(()=>{let e=window.innerWidth;n(e)},200);return window.addEventListener(`resize`,e),e(),()=>window.removeEventListener(`resize`,e)},[]),{windowSize:t}}export{p as a,l as c,m as i,h as n,d as o,g as r,u as s,_ as t};