@uniai-fe/next-providers 0.1.11 → 0.1.13

package/README.md

@@ -1,3 +1,11 @@
 # client / next-providers
 
 상태관리 도구 \<Provider /> 및 보조 도구 커스텀 등 관리
+
+## Exported utilities
+
+- `NextRoots` — React Query/Jotai/Airtable 등 루트 Provider 묶음
+  - `modalProviders` 슬롯을 통해 `@uniai-fe/ui-legacy`나 신규 `@uniai-fe/uds-*` 모달 Provider를 서비스 측에서 직접 주입한다.
+  - `onRouteChange` 콜백을 전달해 라우트 변경 시 모달 스택 초기화 등 앱 전용 부가 로직을 실행할 수 있다.
+- `SetQueryCookie` — query string 기반 쿠키 동기화
+- `RuntimeRouteGuard` / `runtimeRouteRedirectAtom` — 런타임 환경에 따라 `/mobile` 등 경로를 강제하거나 차단하는 가드 + Jotai 토글 atom

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/next-providers",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Next.js State Providers for UNIAI FE Projects",
   "type": "module",
   "private": false,
@@ -48,7 +48,9 @@
     "@tanstack/react-query": ">= 5",
     "jotai": ">= 2",
     "styled-components": ">= 6",
-    "airtable": ">= 0.12"
+    "airtable": ">= 0.12",
+    "@uniai-fe/runtime-env": ">= 0.1.6",
+    "@uniai-fe/util-jotai": ">= 0.1.5"
   },
   "peerDependenciesMeta": {
     "optional": {
@@ -62,8 +64,8 @@
     "@uniai-fe/tsconfig": "workspace:*",
     "@uniai-fe/next-devkit": "workspace:*",
     "@uniai-fe/util-functions": "workspace:*",
+    "@uniai-fe/runtime-env": "workspace:*",
     "@uniai-fe/util-jotai": "workspace:*",
-    "@uniai-fe/ui-legacy": "workspace:*",
     "@uniai-fe/i18n": "workspace:*",
     "@tanstack/react-query": "^5.90.12",
     "@types/node": "^24.10.2",

package/src/NextRoots.tsx

@@ -1,11 +1,7 @@
-import { Suspense } from "react";
-import { Modal } from "@uniai-fe/ui-legacy";
-
 import StyledComponentsRegistry from "./lib/StyledComponentsRegistry";
 import AirtableProvider from "./provider/AirtableProvider";
 import { JotaiProvider } from "./provider/JotaiProvider";
 import { ReactQueryProvider } from "./provider/ReactQueryProvider";
-import RouterEventDetector from "./lib/RouterEventsDetector";
 import SetQueryCookie from "./lib/SetQueryCookie";
 import SystemThemeChecker from "./lib/SystemThemeChecker";
 import type { SystemLanguageType } from "@uniai-fe/next-devkit/types";
@@ -17,23 +13,27 @@ import type { SystemLanguageType } from "@uniai-fe/next-devkit/types";
  * @param {SystemLanguageType} [props.locale] 언어설정; "ko", "en"
  * @param {object} [props.systemThemeOptions] 시스템 테마 체크 옵션
  * @param {string[]} [props.systemThemeOptions.exceptPaths] 테마 체크 제외 경로
+ * @param {React.ReactNode} [props.modalProviders] 모달 Provider 슬롯(@uniai-fe/ui-legacy 등 서비스 선택)
+ * @param {() => void} [props.onRouteChange] 경로 변경 시 실행할 콜백(예: 모달 스택 초기화)
  * @param {React.ReactNode} props.children
  * @desc
  * - React Query
  * - Jotai
- * - Apollo GraphQL
  * - Airtable
- * - Modal / Draggable Modal
  * - System Theme Checker
  * - Router Event Detector
  */
 export default function NextRoots({
   locale = "ko",
   systemThemeOptions,
+  modalProviders,
+
   children,
 }: {
   locale?: SystemLanguageType;
   systemThemeOptions?: { exceptPaths: string[] };
+  modalProviders?: React.ReactNode;
+
   children: React.ReactNode;
 }) {
   return (
@@ -43,13 +43,9 @@ export default function NextRoots({
         <StyledComponentsRegistry>
           <AirtableProvider locale={locale}>
             {children}
-            <Modal.Basic.Provider />
-            <Modal.Draggable.Provider />
+            {modalProviders}
           </AirtableProvider>
           <SystemThemeChecker exceptPaths={systemThemeOptions?.exceptPaths} />
-          <Suspense fallback={null}>
-            <RouterEventDetector />
-          </Suspense>
         </StyledComponentsRegistry>
       </JotaiProvider>
     </ReactQueryProvider>

package/src/index.tsx

@@ -1,4 +1,7 @@
-import NextRoots from "./NextRoots";
-import SetQueryCookie from "./lib/SetQueryCookie";
+export {
+  RuntimeRouteGuard,
+  runtimeRouteRedirectAtom,
+} from "./lib/RuntimeRouteGuard";
 
-export { NextRoots, SetQueryCookie };
+export { default as NextRoots } from "./NextRoots";
+export { default as SetQueryCookie } from "./lib/SetQueryCookie";

package/src/lib/RuntimeRouteGuard.tsx

@@ -0,0 +1,106 @@
+"use client";
+
+import { useEffect } from "react";
+import { usePathname, useRouter } from "next/navigation";
+import { atom, type PrimitiveAtom, useAtomValue } from "jotai";
+import {
+  runtimeEnvState,
+  type RuntimeEnvState,
+} from "@uniai-fe/runtime-env/client";
+
+const DEFAULT_MOBILE_BASE_PATH = "/mobile";
+const DEFAULT_DESKTOP_FALLBACK_PATH = "/";
+
+/**
+ * 런타임 라우팅 가드 판단에 필요한 환경 상태.
+ * @typedef {Pick<RuntimeEnvState, "hardware" | "isStandalone" | "isMobileNonPwa">} RuntimeRouteConditions
+ */
+export type RuntimeRouteConditions = Pick<
+  RuntimeEnvState,
+  "hardware" | "isStandalone" | "isMobileNonPwa"
+>;
+
+export interface RuntimeRouteGuardProps {
+  mobileBasePath?: string;
+  desktopFallbackPath?: string;
+  redirectAtom?: PrimitiveAtom<boolean>;
+}
+
+/**
+ * 모바일 경로 리디렉션 on/off 상태를 제어하는 Jotai atom.
+ * @constant
+ */
+export const runtimeRouteRedirectAtom = atom(true);
+
+const isMobilePath = (pathname?: string | null, basePath?: string): boolean =>
+  typeof pathname === "string" &&
+  typeof basePath === "string" &&
+  pathname.startsWith(basePath);
+
+const shouldForceMobilePath = (
+  pathname: string | null,
+  { isStandalone, hardware }: RuntimeRouteConditions,
+  basePath: string,
+): boolean => {
+  if (!isStandalone) return false;
+  if (hardware !== "mobile" && hardware !== "tablet") return false;
+  return !isMobilePath(pathname, basePath);
+};
+
+const shouldPreventMobilePath = (
+  pathname: string | null,
+  { isStandalone, isMobileNonPwa }: RuntimeRouteConditions,
+  basePath: string,
+): boolean => {
+  if (isStandalone) return false;
+  if (!isMobileNonPwa) return false;
+  return isMobilePath(pathname, basePath);
+};
+
+/**
+ * Runtime 환경에 따라 모바일 경로를 강제 또는 제한하는 라우트 가드.
+ * @component
+ * @param {RuntimeRouteGuardProps} props
+ * @param {string} [props.mobileBasePath="/mobile"] 모바일 PWA 화면 루트 경로
+ * @param {string} [props.desktopFallbackPath="/"] 모바일 접근 제한 시 이동할 데스크톱 경로
+ * @param {PrimitiveAtom<boolean>} [props.redirectAtom=runtimeRouteRedirectAtom] 리디렉션 on/off를 제어하는 Jotai atom
+ * @example
+ * <RuntimeRouteGuard mobileBasePath="/mobile" desktopFallbackPath="/" />
+ * @desc
+ * - 모바일 standalone(PWA) 환경에서는 지정된 모바일 경로로 강제 이동한다.
+ * - 모바일 브라우저 환경(비 PWA)에서는 모바일 경로 접근을 막고 기본 경로로 전환한다.
+ * - redirectAtom을 이용해 DevTools 또는 UI에서 손쉽게 토글할 수 있다.
+ */
+export function RuntimeRouteGuard({
+  mobileBasePath = DEFAULT_MOBILE_BASE_PATH,
+  desktopFallbackPath = DEFAULT_DESKTOP_FALLBACK_PATH,
+  redirectAtom = runtimeRouteRedirectAtom,
+}: RuntimeRouteGuardProps = {}) {
+  const router = useRouter();
+  const pathname = usePathname();
+  const env = useAtomValue(runtimeEnvState);
+  const redirectEnabled = useAtomValue(redirectAtom);
+
+  useEffect(() => {
+    if (!redirectEnabled) return;
+    if (typeof pathname !== "string") return;
+
+    if (shouldForceMobilePath(pathname, env, mobileBasePath)) {
+      router.replace(mobileBasePath);
+      return;
+    }
+
+    if (shouldPreventMobilePath(pathname, env, mobileBasePath)) {
+      router.replace(desktopFallbackPath);
+    }
+  }, [
+    desktopFallbackPath,
+    env,
+    mobileBasePath,
+    pathname,
+    redirectEnabled,
+    router,
+  ]);
+
+  return null;
+}

package/src/lib/RouterEventsDetector.tsx

@@ -1,30 +0,0 @@
-"use client";
-
-import { usePathname } from "next/navigation";
-import { useEffect } from "react";
-import { useSetAtom } from "jotai";
-
-import { modalState, modalDraggableState } from "@uniai-fe/ui-legacy";
-
-/**
- * 경로변경 이벤트 감지
- * @component
- * @desc
- * - 최상위 layout에서, 경로 변경을 감지
- */
-export default function RouterEventDetector() {
-  const resetModalStack = useSetAtom(modalState);
-  const resetDraggableModalStack = useSetAtom(modalDraggableState);
-
-  const pathname = usePathname();
-
-  // 경로 변경 감지
-  useEffect(() => {
-    // 모달 스택 초기화
-    resetModalStack([]);
-    // 드래거블 모달 스택 초기화
-    resetDraggableModalStack([]);
-  }, [pathname, resetDraggableModalStack, resetModalStack]);
-
-  return null;
-}