@thefreshop/tb 1.1.2 → 1.1.4

package/README.md

@@ -0,0 +1,273 @@
+# @thefreshop/tb — tb framework
+
+## 1) 패키지 이름 + 한 줄 소개
+Ant Design 기반의 React UI 프레임워크로, 탭형 어드민 프레임과 CRUD 테이블/검색/페이지 스캐폴드를 제공합니다.
+
+## 2) Why / What it solves
+- 탭 기반 어드민 프레임(Top/Nav/Bottom)과 라우팅을 빠르게 구성.
+- 검색/테이블/모달 CRUD 흐름을 재사용 가능한 컴포넌트로 표준화.
+- Ant Design을 기반으로 일관된 관리자 UI 구축.
+
+## 3) Features
+- [x] 탭 기반 프레임 레이아웃 + 동적 라우팅
+- [x] 세션 기반 탭 상태 저장(`sessionStorage`)
+- [x] 검색 박스 + 테이블 + 로딩 레이아웃 스캐폴드
+- [x] Ant Design Table 기반 CRUD 래퍼 + 모달 생성/수정
+- [x] 한국어 로케일 기본 제공(dayjs/moment/antd)
+
+## 4) Installation
+```bash
+npm i @thefreshop/tb
+```
+
+```bash
+yarn add @thefreshop/tb
+```
+
+```bash
+pnpm add @thefreshop/tb
+```
+
+### Peer Dependencies
+이 패키지는 아래 피어 의존성을 필요로 합니다:
+```bash
+npm i react react-dom react-router antd @ant-design/icons dayjs moment react-error-boundary @monaco-editor/react
+```
+
+## 5) Quick Start
+```tsx
+import React from "react";
+import { TbProvider, TbpProvider, TbFrame } from "@thefreshop/tb";
+import type { navType, topType, tbframeType } from "@thefreshop/tb";
+
+const setting: tbframeType = { islogin: false, startTabKey: "dashboard" };
+const top: topType = { title: "TB Admin", topMenuSetting: [{ key: "main", title: "Main" }] };
+const nav: navType = {
+  menuSet: [
+    {
+      parentkey: "main",
+      menuSetting: [
+        { tab: { key: "dashboard", title: "Dashboard", page: <div>Home</div> }, hasPage: true },
+      ],
+    },
+  ],
+};
+
+export default function App() {
+  return (
+    <TbProvider basename="/">
+      <TbpProvider>
+        <TbFrame setting={setting} top={top} nav={nav} />
+      </TbpProvider>
+    </TbProvider>
+  );
+}
+```
+
+## 6) Usage
+### 기본 사용
+```tsx
+import { Tbpage } from "@thefreshop/tb";
+
+const columns = [
+  {
+    tableProps: { dataIndex: "name", title: "Name" },
+    search: true,
+    create: true,
+    modify: true,
+  },
+];
+
+export default function Users() {
+  return (
+    <Tbpage
+      title="Users"
+      decs="User list"
+      searchOption={[{ key: "base", items: [{ type: "input", key: "name", title: "Name" }] }]}
+      tableProps={{ rowKey: "id", columns, dataSource: [] }}
+    />
+  );
+}
+```
+
+### 옵션/설정(핵심 props 요약)
+#### TbFrame
+| 이름 | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `setting` | `tbframeType` | - | 로그인/시작 탭 등 기본 프레임 설정 |
+| `top` | `topType` | - | 상단 영역 설정 |
+| `nav` | `navType` | - | 네비게이션/탭 정의 |
+| `bottom` | `bottomType` | `undefined` | 하단 영역 |
+| `top_banner` | `React.ReactNode` | `undefined` | 상단 배너 영역 |
+| `hashmode` | `boolean` | `false` | 해시 라우팅 사용 여부 |
+| `frameStyle` | `FrameStyleType` | `undefined` | 스타일 오버라이드 |
+
+#### Tbpage
+| 이름 | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `tableProps` | `any` | - | AntBaseTable에 전달되는 props |
+| `searchOption` | `any` | `undefined` | SearchBox 옵션 |
+| `searchDisabled` | `boolean` | `false` | 검색 비활성화 |
+| `onSubmit` | `(searchdata?, rowdata?, isReset?) => void` | `undefined` | 검색 제출/리셋 콜백 |
+| `isLoading` | `boolean` | `undefined` | 로딩 오버레이 |
+| `title`/`decs` | `string` | `undefined` | 타이틀/설명 |
+| `PageStyle` | `PageStyleType` | `undefined` | 스타일 오버라이드 |
+
+> 더 많은 props 및 타입은 `docs/API.md`를 참고하세요.
+
+### 반환값/에러
+| 항목 | 반환 | 에러/주의사항 |
+| --- | --- | --- |
+| `useTbState()` | `ProviderType` | `TbProvider` 밖에서 호출 시 Error throw |
+
+## 7) API Reference
+API가 많은 관계로 `docs/API.md`로 분리했습니다.
+- 핵심 export: `TbProvider`, `useTbState`, `tbContext`, `TbFrame`, `TbpProvider`, `ContentLayout`, `Tbpage`, `TbpageSm`, `Tblist`, `TbpageMulti`, `AntBaseTable`, `AntBaseModalCreate`, `AuthTable` 및 타입들
+
+## 8) TypeScript
+- 타입 엔트리: `package.json`의 `types: ./dist/cjs/index.d.ts`
+- 공개 타입: `export type * from "./types"`로 노출
+
+```ts
+import type { tbframeType, navType, antBasePropsType } from "@thefreshop/tb";
+```
+
+## 9) Compatibility
+- **Runtime**: 브라우저 기반 React 앱 (DOM lib 사용)
+- **React**: `react@^19.1.1` (peer)
+- **Router**: `react-router@^7.10.0` (peer)
+- **UI**: `antd@^6.0.0` (peer)
+- **CJS/ESM**: `main`(CJS), `module`(ESM) 빌드 제공
+- **Node 엔진**: Not found in repository
+
+## 10) Bundling / Tree-shaking
+- `exports`/`sideEffects` 필드가 없어 트리 셰이킹 동작은 번들러 설정에 의존합니다.
+- Rollup 빌드에서 CSS Modules를 런타임 inject 하므로 일부 부수효과(side effects)가 있을 수 있습니다.
+
+## 11) Examples
+### Basic (프레임 구성)
+```tsx
+import { TbProvider, TbpProvider, TbFrame } from "@thefreshop/tb";
+import type { navType, topType, tbframeType } from "@thefreshop/tb";
+
+const setting: tbframeType = { islogin: false };
+const top: topType = { title: "Admin", topMenuSetting: [{ key: "main", title: "Main" }] };
+const nav: navType = {
+  menuSet: [
+    {
+      parentkey: "main",
+      menuSetting: [{ tab: { key: "home", title: "Home", page: <div>Home</div> }, hasPage: true }],
+    },
+  ],
+};
+
+export default function App() {
+  return (
+    <TbProvider>
+      <TbpProvider>
+        <TbFrame setting={setting} top={top} nav={nav} />
+      </TbpProvider>
+    </TbProvider>
+  );
+}
+```
+
+### Advanced (검색 + 테이블)
+```tsx
+import { Tbpage } from "@thefreshop/tb";
+
+const columns = [
+  { tableProps: { dataIndex: "name", title: "Name" }, search: true, create: true, modify: true },
+];
+
+export default function Users() {
+  return (
+    <Tbpage
+      title="Users"
+      searchOption={[{ key: "base", items: [{ type: "input", key: "name", title: "Name" }] }]}
+      tableProps={{ rowKey: "id", columns, dataSource: [] }}
+      onSubmit={(query, data) => {
+        console.log(query, data);
+      }}
+    />
+  );
+}
+```
+
+### Real-world (멀티 패널)
+```tsx
+import { TbpageMulti } from "@thefreshop/tb";
+
+export default function Dashboard() {
+  return (
+    <TbpageMulti
+      title="Dashboard"
+      arrtableProps={[
+        { type: "table", title: "Left", tableprops: { rowKey: "id", columns: [], dataSource: [] } },
+        { type: "module", title: "Right", module: <div>Custom Module</div> },
+      ]}
+      arrflex={[2, 1]}
+      direction="row"
+    />
+  );
+}
+```
+
+## 12) Troubleshooting
+1. **peerDependencies 충돌**: React/antd/react-router 버전이 맞지 않으면 런타임 오류가 발생합니다.
+2. **CSS Modules 미적용**: 소비 앱 번들러에서 CSS Modules가 비활성화되면 레이아웃이 깨집니다.
+3. **SSR 환경 오류**: `sessionStorage` 사용으로 SSR 시 `window` 관련 에러가 날 수 있습니다.
+4. **CJS/ESM 혼용 오류**: 번들러가 `module`/`main` 선택을 잘못하면 중복 React 경고가 발생할 수 있습니다.
+5. **타입 인식 실패**: `types` 경로(`dist/cjs/index.d.ts`)가 올바르게 배포되었는지 확인하세요.
+6. **Ant Design 스타일 누락**: 소비 앱에서 antd 스타일을 로드하지 않으면 컴포넌트가 깨집니다.
+7. **모달 폼 초기값 미반영**: `AntBaseModalCreate`에서 `initialValues` 사용 시 `open` 타이밍을 확인하세요.
+
+## 13) FAQ
+1. **React 18에서도 동작하나요?** Not found in repository (peerDependencies는 React 19 기준입니다).
+2. **React Router v6 사용 가능?** Not found in repository (peerDependencies는 v7 기준입니다).
+3. **라우팅 구조는 어떻게 만들나요?** `nav.menuSet`과 `nav.globalTabs` 기반으로 라우트가 자동 생성됩니다.
+4. **해시 라우팅을 지원하나요?** `TbFrame`의 `hashmode`로 지원합니다.
+5. **탭 상태는 어디에 저장되나요?** `sessionStorage`의 `tbFrameState` 키에 저장됩니다.
+6. **로케일 설정은 어디서 하나요?** `TbpProvider`가 `antd` `ConfigProvider`와 `ko_KR` 로케일을 설정합니다.
+7. **테스트 예제나 Storybook이 있나요?** Not found in repository.
+8. **변경 이력(Changelog)이 있나요?** No changelog found.
+
+## 14) Contributing
+### 로컬 개발
+```bash
+yarn install
+```
+
+```bash
+yarn dev
+```
+
+```bash
+yarn build
+```
+
+- 테스트/린트 스크립트: Not found in repository
+- 배포 스크립트: Not found in repository
+
+## 15) Security
+- 공급망 보안: peerDependencies 버전을 고정/검증하세요.
+- 토큰/시크릿 관리: 레포에 환경변수 파일이 없으므로 소비 앱에서 안전하게 관리하세요.
+- 취약점 신고: `package.json`의 `bugs.url` 참고.
+
+## 16) License
+- `package.json`: MIT
+- LICENSE 파일: No license file found
+
+## 17) Quick Commands
+| 목적 | 명령 | 비고 |
+| --- | --- | --- |
+| 개발(와치) | ```bash
+yarn dev
+``` | Rollup watch 빌드 |
+| 빌드 | ```bash
+yarn build
+``` | `dist/` 출력 |
+| 테스트 | Not found in repository | - |
+| 린트 | Not found in repository | - |
+| 타입체크 | Not found in repository | - |
+| 퍼블리시 | Not found in repository | - |

package/dist/cjs/index.js

@@ -40,7 +40,7 @@ var React__namespace = /*#__PURE__*/_interopNamespaceDefault(React);
 const tbContext = React.createContext(undefined);
 
 const SESSION_STORAGE_KEY = "tbFrameState";
-const TbProvider = ({ children }) => {
+const TbProvider = ({ basename, children }) => {
     const [topkey, setTopkey] = React.useState("");
     const [tabList, setTabList] = React.useState([]);
     const [currentTabKey, setCurrentTabKey] = React.useState();
@@ -142,6 +142,7 @@ const TbProvider = ({ children }) => {
             errMsg,
             tabList,
             setTabList,
+            basename,
         } }, children));
 };
 const useTbState = () => {
@@ -402,11 +403,11 @@ var css_248z$7 = ".main-module_mainFrame__Etjvl{height:100%;width:100%}.main-mod
 var styles$5 = {"mainFrame":"main-module_mainFrame__Etjvl","mainFrameFullscreen":"main-module_mainFrameFullscreen__oEwV8"};
 styleInject(css_248z$7);
 
-const Main = () => {
+const Main = ({ style }) => {
     const [sp] = reactRouter.useSearchParams();
     const isFs = sp.get("fs") === "1" || sp.get("fullscreen") === "1";
     // console.log("Main render, isFs:", isFs);
-    return (React.createElement("div", { className: isFs ? styles$5.mainFrameFullscreen : styles$5.mainFrame },
+    return (React.createElement("div", { className: isFs ? styles$5.mainFrameFullscreen : styles$5.mainFrame, style: style },
         React.createElement(reactRouter.Outlet, null)));
 };
 
@@ -501,7 +502,7 @@ const NullPage = () => {
 };
 
 const TbFrame = ({ setting, top, bottom, nav, top_banner, hashmode = false, frameStyle, }) => {
-    const { user, errMsg, tabList, setTabList, startTabKey, setStartTabKey, loginUser } = useTbState();
+    const { basename, user, errMsg, tabList, setTabList, startTabKey, setStartTabKey, loginUser } = useTbState();
     React.useEffect(() => {
         let p_tabList = [];
         nav.menuSet.forEach((item) => {
@@ -574,7 +575,9 @@ const TbFrame = ({ setting, top, bottom, nav, top_banner, hashmode = false, fram
                     children: route(),
                     errorElement: React.createElement(NullPage, null),
                 },
-            ]);
+            ], {
+                basename: basename ?? "/",
+            });
         }
         else {
             return reactRouter.createBrowserRouter([
@@ -584,9 +587,11 @@ const TbFrame = ({ setting, top, bottom, nav, top_banner, hashmode = false, fram
                     children: route(),
                     errorElement: React.createElement(NullPage, null),
                 },
-            ]);
+            ], {
+                basename: basename ?? "/",
+            });
         }
-    }, [hashmode, user, top, nav, setting, top_banner, bottom, frameStyle]);
+    }, [hashmode, user, top, nav, setting, top_banner, bottom, frameStyle, basename]);
     return React.createElement(reactRouter.RouterProvider, { router: router });
 };
 const MainLayout = ({ errMsg, setting, top_banner, nav, user, top, bottom, frameStyle, }) => {
@@ -631,7 +636,7 @@ const MainLayout = ({ errMsg, setting, top_banner, nav, user, top, bottom, frame
             React.createElement(Nav, { nav: nav, islogin: setting.islogin ?? false, frameStyle: frameStyle }),
             React.createElement("div", { className: styles$9.contentsFrame, style: frameStyle?.contentsFrame },
                 React.createElement(Tabs, { nav: nav, frameStyle: frameStyle }),
-                React.createElement(Main, null))),
+                React.createElement(Main, { style: frameStyle?.contentsMainFrame }))),
         React.createElement("div", { className: styles$9.bottomFrame, style: frameStyle?.bottomFrame }, bottom && React.createElement(Bottom, { bottom: bottom, frameStyle: frameStyle }))))));
 };
 
@@ -700,7 +705,7 @@ const FORM_CREATE = "등록";
 
  * @todo
 */
-const TableTopButtonGroup = ({ isSelect, onRefresh, isCounter, autoRefreshTime, addProps, modifyProps, deleteProps, removeProps, resetProps, customProps, }) => {
+const TableTopButtonGroup = ({ isSelect, onRefresh, isCounter, autoRefreshTime, addProps, modifyProps, deleteProps, removeProps, resetProps, customProps, isInSearch = false, onInSearch, }) => {
     if (!addProps && !modifyProps && !deleteProps && !removeProps && !resetProps && !customProps && !onRefresh) {
         return null;
     }
@@ -747,7 +752,8 @@ const TableTopButtonGroup = ({ isSelect, onRefresh, isCounter, autoRefreshTime,
                 deleteProps ? (React.createElement(antd.Button, { danger: true, disabled: !isSelect || deleteProps.disable, onClick: deleteProps.onFun }, deleteProps.title ? deleteProps.title : TABLE_DELETE)) : null,
                 resetProps ? (React.createElement(antd.Button, { disabled: !isSelect || resetProps.disable, onClick: resetProps.onFun }, resetProps.title ? resetProps.title : TABLE_RESET)) : null,
                 removeProps ? (React.createElement(antd.Button, { danger: true, type: "primary", disabled: !isSelect || removeProps.disable, onClick: removeProps.onFun }, removeProps.title ? removeProps.title : TABLE_REMOVE)) : null,
-                customProps?.rightRender && customProps?.rightRender()))));
+                customProps?.rightRender && customProps?.rightRender(),
+                isInSearch && onInSearch ? React.createElement(InSearchForm, { onInSearch: onInSearch }) : null))));
 };
 const TableBottomButtonGroup = ({ isSelect, topProps, bottomProps, upProps, downProps, }) => {
     return (React.createElement(antd.Row, { justify: "space-between" },
@@ -761,6 +767,22 @@ const TableBottomButtonGroup = ({ isSelect, topProps, bottomProps, upProps, down
                 downProps ? (React.createElement(antd.Button, { disabled: !isSelect || downProps.disable, onClick: downProps.onFun }, TABLE_DOWN)) : null,
                 bottomProps ? (React.createElement(antd.Button, { disabled: !isSelect || bottomProps.disable, onClick: bottomProps.onFun }, TABLE_BOTTOM)) : null))));
 };
+const InSearchForm = ({ onInSearch }) => {
+    const [inputSearch, setInputSearch] = React.useState("");
+    const SearchClick = () => {
+        onInSearch(inputSearch);
+    };
+    const activeEnter = (e) => {
+        if (e.key === "Enter") {
+            SearchClick();
+        }
+    };
+    return (React.createElement(antd.Space.Compact, null,
+        React.createElement(antd.Input, { style: { width: "150px" }, onChange: (e) => {
+                setInputSearch(e.target.value);
+            }, value: inputSearch, onKeyDown: (e) => activeEnter(e) }),
+        React.createElement(antd.Button, { onClick: SearchClick }, "\uAC80\uC0C9")));
+};
 
 var commonjsGlobal = typeof globalThis !== 'undefined' ? globalThis : typeof window !== 'undefined' ? window : typeof global !== 'undefined' ? global : typeof self !== 'undefined' ? self : {};
 
@@ -23338,11 +23360,24 @@ const AntBaseModalCreate = ({ modalProps, formProps, props }) => {
 
 const { Title: Title$1 } = antd.Typography;
 const { confirm: confirm$1 } = antd.Modal;
-const AntBaseTable = ({ bordered, className, rowKey, rowName, dataSource, initData, customColumn, customValue, columns, expandable, size, onDoubleClick, onClick, selectProps, addProps, modifyProps, deleteProps, removeProps, resetProps, customProps, topProps, bottomProps, upProps, downProps, pageProps, scroll, onRefresh, isCounter, autoRefreshTime, createModalWidth = 1000, onCreateClose, }, ref) => {
+const AntBaseTable = ({ bordered, className, rowKey, rowName, dataSource, initData, customColumn, customValue, columns, expandable, size, onDoubleClick, onClick, selectProps, addProps, modifyProps, deleteProps, removeProps, resetProps, customProps, topProps, bottomProps, upProps, downProps, pageProps, scroll, onRefresh, isCounter, autoRefreshTime, createModalWidth = 1000, onCreateClose, isInSearch = false, }, ref) => {
     const [selectedRowKeys, setSelectedRowKeys] = React.useState([]);
     const [selectedRow, setSelectedRow] = React.useState();
     const [popupCreate, setPopupCreate] = React.useState(false);
     const [popupModify, setPopupModify] = React.useState(false);
+    const [viewData, setViewData] = React.useState(dataSource);
+    const onInSearch = (value) => {
+        const search = value.trim().toLowerCase();
+        if (!search) {
+            setViewData(dataSource);
+            return;
+        }
+        setViewData(dataSource.filter((item) => Object.values(item).some((itemValue) => {
+            if (itemValue == null)
+                return false;
+            return String(itemValue).toLowerCase().includes(search);
+        })));
+    };
     React.useEffect(() => {
         setSelectedRow(dataSource?.find((m) => {
             if (m) {
@@ -23435,7 +23470,7 @@ const AntBaseTable = ({ bordered, className, rowKey, rowName, dataSource, initDa
             height: "100%",
             padding: "20px",
         } },
-        React.createElement(TableTopButtonGroup, { isSelect: isSelect, isCounter: isCounter, onRefresh: onRefresh, autoRefreshTime: autoRefreshTime, addProps: addProps && {
+        React.createElement(TableTopButtonGroup, { isInSearch: isInSearch, onInSearch: onInSearch, isSelect: isSelect, isCounter: isCounter, onRefresh: onRefresh, autoRefreshTime: autoRefreshTime, addProps: addProps && {
                 ...addProps,
                 onFun: () => {
                     if (addProps.customModal) {
@@ -23616,7 +23651,7 @@ const AntBaseTable = ({ bordered, className, rowKey, rowName, dataSource, initDa
                 return {
                     onClick: () => { }, // click header row
                 };
-            }, dataSource: dataSource?.map((i) => i), 
+            }, dataSource: viewData?.map((i) => i), 
             // columns={tableColumns(
             //   columns.concat(
             //     deleteCol({