@uniai-fe/uds-templates 0.4.3 → 0.4.4

package/README.md

@@ -59,11 +59,13 @@ Next.js 서비스에서 primitives와 동일한 방식으로 **Raw TypeScript**
   - `ServiceInquiry.Form`
   - `ServiceInquiry.OpenButton`
   - `ServiceInquiry.useOpen`
+  - `ServiceInquiry.useProvideContext`
   - `ServiceInquiry.useUserContext`
   - `ServiceInquiry.createModal`
   - `ServiceInquiryFieldMode`
   - `ServiceInquiryFormProps`
   - `ServiceInquiryFormValues`
+  - `ServiceInquiryProvidedContext`
 - `/cctv`
   - `CCTV.Provider`
   - `CCTV.CamList.Container`
@@ -105,8 +107,9 @@ Next.js 서비스에서 primitives와 동일한 방식으로 **Raw TypeScript**
   - ui-legacy 스택 기반 모달 Provider/Root/Container + 템플릿(`Modal.Alert`, `Modal.Dialog`)
   - Storybook(`apps/design-storybook/src/stories/templates/modal`)에서 Alert/Confirm 케이스를 검증한다.
 - `/service-inquiry/**`
-  - 문의 입력 전용 form, 기본 원형 `?` open button, 커스텀 trigger용 open hook, request context 조립 hook, modal preset factory를 제공한다.
+  - 문의 입력 전용 form, 기본 원형 `?` open button, 커스텀 trigger용 open hook, 페이지 context 등록 hook, request context 조립 hook, modal preset factory를 제공한다.
   - submit transport, React Query mutation, Next.js route handler, 에러 피드백(`Modal.Alert`)은 서비스 앱이 소유한다.
+  - 모듈 내부 Jotai registry를 사용하므로, layout 고정 버튼 1개와 페이지별 context 등록 hook 조합으로 ready-to-use 구성이 가능하다.
   - 로그인 후 `farm_name`, `contact`를 auto-fill + readonly로 보여야 할 때는 `formContextOptions.defaultValues`와 `farmNameField.mode`, `contactField.mode`를 함께 전달한다.
 - `/weather/**`
   - page-frame header utility에 결합되는 weather header 템플릿과 weather data hook/mock 도구를 제공한다.
@@ -120,10 +123,11 @@ Next.js 서비스에서 primitives와 동일한 방식으로 **Raw TypeScript**
 ### Service Inquiry 도입 흐름
 
 1. 서비스 앱이 `react-hook-form`으로 `defaultValues`와 `onSubmit`을 준비한다.
-2. 필요하면 `ServiceInquiry.useUserContext`로 `labels`, `page_path`, 추가 `user_context`를 조립한다.
-3. 기본 버튼은 `ServiceInquiry.OpenButton`, 커스텀 버튼은 `ServiceInquiry.useOpen`으로 모달 open을 연결한다.
-4. modal footer confirm이 `ServiceInquiry.Form` submit 진입을 담당한다.
-5. 실제 submit은 서비스 앱의 `useMutation + Next.js route handler + Modal.Alert` 조합으로 처리한다.
+2. layout 고정 버튼은 `ServiceInquiry.useUserContext()`로 모듈 내부 registry 기반 `requestContext`를 읽는다.
+3. 각 페이지/폼은 `ServiceInquiry.useProvideContext({ labels, pagePath, userContext })`로 `ServiceInquiryProvidedContext`를 등록한다.
+4. 기본 버튼은 `ServiceInquiry.OpenButton`, 커스텀 버튼은 `ServiceInquiry.useOpen`으로 모달 open을 연결한다.
+5. modal footer confirm이 `ServiceInquiry.Form` submit 진입을 담당한다.
+6. 실제 submit은 서비스 앱의 `useMutation + Next.js route handler + Modal.Alert` 조합으로 처리한다.
 
 `service-inquiry`는 구조와 request context까지만 제공하고, 네트워크 상태/재시도/성공·실패 피드백은 서비스 앱이 소유합니다.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-templates",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "description": "UNIAI Design System; UI Templates Package",
   "type": "module",
   "private": false,

package/src/service-inquiry/components/Form.tsx

@@ -43,9 +43,8 @@ const ServiceInquiryForm = ({
             className={clsx(
               "service-inquiry-field",
               "service-inquiry-field-farm-name",
-              farmNameField?.className,
             )}
-            width={farmNameField?.inputProps?.width ?? "full"}
+            width="full"
             headerProps={{
               required: farmNameField?.required,
               ...(typeof farmNameField?.label === "string"
@@ -63,13 +62,9 @@ const ServiceInquiryForm = ({
           >
             <Input.Base
               type="text"
-              block={farmNameField?.inputProps?.block ?? true}
-              readOnly={
-                farmNameField?.mode === "readonly" ||
-                farmNameField?.inputProps?.readOnly === true
-              }
+              block={true}
+              readOnly={farmNameField?.mode === "readonly"}
               placeholder={farmNameField?.placeholder ?? "농장명 입력"}
-              {...farmNameField?.inputProps}
               register={form.register("farm_name")}
             />
           </Form.Field.Template>
@@ -80,9 +75,8 @@ const ServiceInquiryForm = ({
             className={clsx(
               "service-inquiry-field",
               "service-inquiry-field-contact",
-              contactField?.className,
             )}
-            width={contactField?.inputProps?.width ?? "full"}
+            width="full"
             headerProps={{
               required: contactField?.required ?? true,
               ...(typeof contactField?.label === "string"
@@ -100,15 +94,11 @@ const ServiceInquiryForm = ({
           >
             <Input.Base
               type="text"
-              block={contactField?.inputProps?.block ?? true}
-              readOnly={
-                contactField?.mode === "readonly" ||
-                contactField?.inputProps?.readOnly === true
-              }
+              block={true}
+              readOnly={contactField?.mode === "readonly"}
               placeholder={
                 contactField?.placeholder ?? "이메일 또는 전화번호 입력"
               }
-              {...contactField?.inputProps}
               register={form.register("contact")}
             />
           </Form.Field.Template>
@@ -119,9 +109,8 @@ const ServiceInquiryForm = ({
             className={clsx(
               "service-inquiry-field",
               "service-inquiry-field-text",
-              textField?.className,
             )}
-            width={textField?.inputProps?.width ?? "full"}
+            width="full"
             headerProps={{
               required: textField?.required ?? true,
               ...(typeof textField?.label === "string"
@@ -138,13 +127,12 @@ const ServiceInquiryForm = ({
             footer={textField?.helper}
           >
             <Input.TextArea
-              block={textField?.inputProps?.block ?? true}
+              block={true}
               placeholder={
                 textField?.placeholder ?? "문의 내용을 자세히 입력해 주세요."
               }
-              height={textField?.inputProps?.height ?? 160}
-              length={textField?.inputProps?.length ?? 10000}
-              {...textField?.inputProps}
+              height={160}
+              length={10000}
               register={form.register("text")}
             />
           </Form.Field.Template>

package/src/service-inquiry/components/OpenButton.tsx

@@ -1,12 +1,12 @@
 "use client";
 
 import { useOpenServiceInquiry } from "../hooks";
-import type { ServiceInquiryOpenButtonProps } from "../types";
+import type { UseOpenServiceInquiryOptions } from "../types";
 
 /**
  * Service Inquiry Open Button; 문의 모달 trigger adapter
  * @component
- * @param {ServiceInquiryOpenButtonProps} props 문의 모달 열기 props
+ * @param {UseOpenServiceInquiryOptions} props 문의 모달 열기 props
  * @param {string} props.stackKey modal stack key
  * @param {ServiceInquiryFormProps} props.formProps 문의 form props
  * @param {Partial<DialogTemplateOptions<ServiceInquiryFormValues>>} [props.dialogOptions] 문의 모달 preset 위에 덮어쓸 dialog option
@@ -22,7 +22,7 @@ const ServiceInquiryOpenButton = ({
   formProps,
   dialogOptions,
   onOpen,
-}: ServiceInquiryOpenButtonProps) => {
+}: UseOpenServiceInquiryOptions) => {
   const { openServiceInquiry } = useOpenServiceInquiry({
     stackKey,
     formProps,

package/src/service-inquiry/hooks/index.ts

@@ -1,2 +1,3 @@
-export * from "./useOpenServiceInquiry";
-export * from "./useServiceInquiryUserContext";
+export * from "./useOpen";
+export * from "./useProvideContext";
+export * from "./useUserContext";

package/src/service-inquiry/hooks/useProvideContext.ts

@@ -0,0 +1,49 @@
+"use client";
+
+import { useEffect, useId } from "react";
+import { useSetAtom } from "jotai";
+import { serviceInquiryProvidedContextRegistryAtom } from "../jotai";
+import type { ServiceInquiryProvidedContext } from "../types";
+
+/**
+ * Service Inquiry Hook; 페이지별 문의 context 등록 Hook
+ * @hook
+ * @param {ServiceInquiryProvidedContext | null} context 페이지 또는 폼이 등록할 문의 context
+ * @example
+ * useProvideServiceInquiryContext({
+ *   labels: ["orders"],
+ *   userContext: { order_id: selectedOrderId },
+ * });
+ */
+export function useProvideServiceInquiryContext(
+  context: ServiceInquiryProvidedContext | null,
+): void {
+  const registrationId = useId();
+  const setProvidedContextRegistry = useSetAtom(
+    serviceInquiryProvidedContextRegistryAtom,
+  );
+
+  useEffect(() => {
+    setProvidedContextRegistry(currentRegistry => {
+      const nextRegistry = { ...currentRegistry };
+
+      if (context) {
+        nextRegistry[registrationId] = context;
+      } else {
+        delete nextRegistry[registrationId];
+      }
+
+      return nextRegistry;
+    });
+
+    return () => {
+      setProvidedContextRegistry(currentRegistry => {
+        const nextRegistry = { ...currentRegistry };
+
+        delete nextRegistry[registrationId];
+
+        return nextRegistry;
+      });
+    };
+  }, [context, registrationId, setProvidedContextRegistry]);
+}

package/src/service-inquiry/hooks/useUserContext.ts

@@ -0,0 +1,57 @@
+"use client";
+
+import { useAtom, useAtomValue } from "jotai";
+import type {
+  ServiceInquiryUserContext,
+  UseServiceInquiryUserContextReturn,
+} from "../types";
+import {
+  serviceInquiryAdditionalUserContextAtom,
+  serviceInquiryRequestContextAtom,
+} from "../jotai";
+
+/**
+ * Service Inquiry Hook; request context 제어 Hook
+ * @hook
+ * @returns {UseServiceInquiryUserContextReturn} request context 및 추가 user_context 제어 함수
+ * @example
+ * const inquiryContext = useServiceInquiryUserContext();
+ */
+export function useServiceInquiryUserContext(): UseServiceInquiryUserContextReturn {
+  /** 1) form init — request context snapshot과 trigger 추가 context를 atom 기반으로 읽는다. */
+  const requestContext = useAtomValue(serviceInquiryRequestContextAtom);
+  const [additionalUserContext, setAdditionalUserContext] = useAtom(
+    serviceInquiryAdditionalUserContextAtom,
+  );
+
+  /** 2) submit/액션 — trigger별 추가 context를 append/reset 할 수 있게 연다. */
+  const setNextAdditionalUserContext: UseServiceInquiryUserContextReturn["setAdditionalUserContext"] =
+    nextUserContext => {
+      setAdditionalUserContext(nextUserContext);
+    };
+
+  const appendUserContext: UseServiceInquiryUserContextReturn["appendUserContext"] =
+    (nextUserContext?: ServiceInquiryUserContext | null) => {
+      if (!nextUserContext) {
+        return;
+      }
+
+      setAdditionalUserContext(currentUserContext => ({
+        ...(currentUserContext ?? {}),
+        ...nextUserContext,
+      }));
+    };
+
+  const clearAdditionalUserContext: UseServiceInquiryUserContextReturn["clearAdditionalUserContext"] =
+    () => {
+      setAdditionalUserContext(null);
+    };
+
+  return {
+    requestContext,
+    additionalUserContext,
+    setAdditionalUserContext: setNextAdditionalUserContext,
+    appendUserContext,
+    clearAdditionalUserContext,
+  };
+}

package/src/service-inquiry/index.tsx

@@ -1,7 +1,11 @@
 import "./index.scss";
 import ServiceInquiryForm from "./components/Form";
 import ServiceInquiryOpenButton from "./components/OpenButton";
-import { useOpenServiceInquiry, useServiceInquiryUserContext } from "./hooks";
+import {
+  useOpenServiceInquiry,
+  useProvideServiceInquiryContext,
+  useServiceInquiryUserContext,
+} from "./hooks";
 import { createServiceInquiryModal } from "./utils/modal-option";
 
 /**
@@ -12,6 +16,7 @@ export const ServiceInquiry = {
   Form: ServiceInquiryForm,
   OpenButton: ServiceInquiryOpenButton,
   useOpen: useOpenServiceInquiry,
+  useProvideContext: useProvideServiceInquiryContext,
   useUserContext: useServiceInquiryUserContext,
   createModal: createServiceInquiryModal,
 };
@@ -20,6 +25,7 @@ export {
   ServiceInquiryForm,
   ServiceInquiryOpenButton,
   useOpenServiceInquiry,
+  useProvideServiceInquiryContext,
   useServiceInquiryUserContext,
   createServiceInquiryModal,
 };

package/src/service-inquiry/jotai/context.ts

@@ -0,0 +1,88 @@
+"use client";
+
+import { atom } from "jotai";
+import type {
+  ServiceInquiryRequestContext,
+  ServiceInquiryProvidedContext,
+  ServiceInquiryUserContext,
+} from "../types";
+
+/**
+ * Service Inquiry State; 페이지별 등록 context registry
+ * @state
+ */
+export const serviceInquiryProvidedContextRegistryAtom = atom<
+  Record<string, ServiceInquiryProvidedContext>
+>({});
+
+/**
+ * Service Inquiry State; trigger/interaction 추가 user_context
+ * @state
+ */
+export const serviceInquiryAdditionalUserContextAtom =
+  atom<ServiceInquiryUserContext | null>(null);
+
+/**
+ * Service Inquiry State; registry 병합 context
+ * @state
+ */
+export const serviceInquiryProvidedContextAtom =
+  atom<ServiceInquiryProvidedContext>(get => {
+    const providedContexts = Object.values(
+      get(serviceInquiryProvidedContextRegistryAtom),
+    );
+
+    return {
+      labels: Array.from(
+        new Set(
+          providedContexts.flatMap(
+            providedContext => providedContext.labels ?? [],
+          ),
+        ),
+      ),
+      pagePath:
+        [...providedContexts].reverse().find(providedContext => {
+          return (
+            typeof providedContext.pagePath === "string" &&
+            providedContext.pagePath.length > 0
+          );
+        })?.pagePath ?? "",
+      userContext: providedContexts.reduce<ServiceInquiryUserContext | null>(
+        (currentUserContext, providedContext) => {
+          if (!providedContext.userContext) {
+            return currentUserContext;
+          }
+
+          return {
+            ...(currentUserContext ?? {}),
+            ...providedContext.userContext,
+          };
+        },
+        null,
+      ),
+    };
+  });
+
+/**
+ * Service Inquiry State; 최종 request context
+ * @state
+ */
+export const serviceInquiryRequestContextAtom =
+  atom<ServiceInquiryRequestContext>(get => {
+    const providedContext = get(serviceInquiryProvidedContextAtom);
+    const additionalUserContext = get(serviceInquiryAdditionalUserContextAtom);
+
+    return {
+      labels: providedContext.labels ?? [],
+      page_path:
+        providedContext.pagePath ||
+        (typeof window === "undefined" ? "" : window.location.pathname),
+      user_context:
+        providedContext.userContext || additionalUserContext
+          ? {
+              ...(providedContext.userContext ?? {}),
+              ...(additionalUserContext ?? {}),
+            }
+          : null,
+    };
+  });

package/src/service-inquiry/jotai/index.ts

@@ -0,0 +1 @@
+export * from "./context";

package/src/service-inquiry/types/hooks.ts

@@ -4,47 +4,24 @@ import type {
 } from "./form-context";
 
 /**
- * Service Inquiry Hook; 페이지 경로 resolver
- * @returns {string} 문의하기를 연 페이지 경로
- */
-export type ServiceInquiryPagePathResolver = () => string;
-
-/**
- * Service Inquiry Hook; 서비스 user context resolver
- * @returns {ServiceInquiryUserContext | null} 서비스가 제공하는 기본 user_context
- */
-export type ServiceInquiryUserContextResolver =
-  () => ServiceInquiryUserContext | null;
-
-/**
- * Service Inquiry Hook; user_context 훅 옵션
+ * Service Inquiry Hook; 모듈 내부 공유 context 값
  * @property {string[]} [labels] 문의 request에 포함할 labels
- * @property {string} [pagePath] 고정 page_path
- * @property {ServiceInquiryPagePathResolver} [resolvePagePath] page_path 동적 resolver
- * @property {ServiceInquiryUserContext | null} [userContext] 서비스 기본 user_context
- * @property {ServiceInquiryUserContextResolver} [resolveUserContext] 서비스 기본 user_context 동적 resolver
+ * @property {string} [pagePath] 문의를 연 페이지 경로
+ * @property {ServiceInquiryUserContext | null} [userContext] 페이지/폼이 제공하는 추가 user_context
  */
-export interface UseServiceInquiryUserContextOptions {
+export interface ServiceInquiryProvidedContext {
   /**
    * 문의 request에 포함할 labels
    */
   labels?: string[];
   /**
-   * 고정 page_path
+   * 문의를 연 페이지 경로
    */
   pagePath?: string;
   /**
-   * page_path 동적 resolver
-   */
-  resolvePagePath?: ServiceInquiryPagePathResolver;
-  /**
-   * 서비스 기본 user_context
+   * 페이지/폼이 제공하는 추가 user_context
    */
   userContext?: ServiceInquiryUserContext | null;
-  /**
-   * 서비스 기본 user_context 동적 resolver
-   */
-  resolveUserContext?: ServiceInquiryUserContextResolver;
 }
 
 /**

package/src/service-inquiry/types/props.ts

@@ -1,6 +1,5 @@
 import type { ReactNode } from "react";
 import type { SubmitHandler } from "react-hook-form";
-import type { InputProps, InputTextAreaProps } from "@uniai-fe/uds-primitives";
 import type { DialogTemplateOptions } from "../../modal/types";
 import type { ServiceInquiryFormValues } from "./form-context";
 
@@ -17,16 +16,11 @@ export type ServiceInquiryFieldMode = "editable" | "readonly";
 
 /**
  * Service Inquiry Form; 공통 field 설정
- * @property {string} [className] field wrapper className
  * @property {ReactNode} [label] field label
  * @property {ReactNode} [helper] field helper
  * @property {boolean} [required] required 표시 여부
  */
 export interface ServiceInquiryFieldBaseProps {
-  /**
-   * field wrapper className
-   */
-  className?: string;
   /**
    * field label
    */
@@ -45,7 +39,6 @@ export interface ServiceInquiryFieldBaseProps {
  * Service Inquiry Form; 단일 line input field 설정
  * @property {"editable" | "readonly"} [mode] 서비스가 제어하는 field 입력 모드
  * @property {string} [placeholder] input placeholder
- * @property {InputProps} [inputProps] primitives Input.Base override
  */
 export interface ServiceInquiryInputFieldProps extends ServiceInquiryFieldBaseProps {
   /**
@@ -56,26 +49,17 @@ export interface ServiceInquiryInputFieldProps extends ServiceInquiryFieldBasePr
    * input placeholder
    */
   placeholder?: string;
-  /**
-   * primitives Input.Base override
-   */
-  inputProps?: InputProps;
 }
 
 /**
  * Service Inquiry Form; textarea field 설정
  * @property {string} [placeholder] textarea placeholder
- * @property {InputTextAreaProps} [inputProps] primitives Input.TextArea override
  */
 export interface ServiceInquiryTextAreaFieldProps extends ServiceInquiryFieldBaseProps {
   /**
    * textarea placeholder
    */
   placeholder?: string;
-  /**
-   * primitives Input.TextArea override
-   */
-  inputProps?: InputTextAreaProps;
 }
 
 /**
@@ -160,12 +144,3 @@ export interface UseOpenServiceInquiryReturn {
    */
   openServiceInquiry: () => void;
 }
-
-/**
- * Service Inquiry Open Button; 문의 모달 기본 버튼 props
- * @property {string} stackKey modal stack key
- * @property {ServiceInquiryFormProps} formProps 문의 form props
- * @property {Partial<DialogTemplateOptions<ServiceInquiryFormValues>>} [dialogOptions] 문의 모달 preset 위에 덮어쓸 dialog option
- * @property {() => void} [onOpen] 모달 open 직전 콜백
- */
-export interface ServiceInquiryOpenButtonProps extends UseOpenServiceInquiryOptions {}

package/src/service-inquiry/hooks/useServiceInquiryUserContext.ts

@@ -1,89 +0,0 @@
-"use client";
-
-import { useState } from "react";
-import type {
-  ServiceInquiryRequestContext,
-  ServiceInquiryUserContext,
-  UseServiceInquiryUserContextOptions,
-  UseServiceInquiryUserContextReturn,
-} from "../types";
-
-/**
- * Service Inquiry Hook; request context 제어 Hook
- * @hook
- * @param {UseServiceInquiryUserContextOptions} options user_context 훅 옵션
- * @param {string[]} [options.labels] 문의 request에 포함할 labels
- * @param {string} [options.pagePath] 고정 page_path
- * @param {ServiceInquiryPagePathResolver} [options.resolvePagePath] page_path 동적 resolver
- * @param {ServiceInquiryUserContext | null} [options.userContext] 서비스 기본 user_context
- * @param {ServiceInquiryUserContextResolver} [options.resolveUserContext] 서비스 기본 user_context 동적 resolver
- * @returns {UseServiceInquiryUserContextReturn} request context 및 추가 user_context 제어 함수
- * @example
- * const inquiryContext = useServiceInquiryUserContext({
- *   labels: ["help-desk"],
- *   resolveUserContext: () => ({ section: "dashboard" }),
- * });
- */
-export function useServiceInquiryUserContext({
-  labels,
-  pagePath,
-  resolvePagePath,
-  userContext,
-  resolveUserContext,
-}: UseServiceInquiryUserContextOptions): UseServiceInquiryUserContextReturn {
-  /** 1) form init — 서비스 기본 context와 별도 trigger 추가 context를 나눠 관리한다. */
-  const [additionalUserContext, setAdditionalUserContext] =
-    useState<ServiceInquiryUserContext | null>(null);
-
-  /** 2) register merge — 서비스 기본 context와 trigger 추가 context를 한 payload로 합친다. */
-  const resolvedPagePath =
-    pagePath ??
-    resolvePagePath?.() ??
-    (typeof window === "undefined" ? "" : window.location.pathname);
-  const resolvedBaseUserContext = userContext ?? resolveUserContext?.() ?? null;
-  const mergedUserContext =
-    resolvedBaseUserContext || additionalUserContext
-      ? {
-          ...(resolvedBaseUserContext ?? {}),
-          ...(additionalUserContext ?? {}),
-        }
-      : null;
-
-  /** 3) helper/state — submit에 바로 연결할 request context snapshot을 노출한다. */
-  const requestContext: ServiceInquiryRequestContext = {
-    labels: labels ?? [],
-    page_path: resolvedPagePath,
-    user_context: mergedUserContext,
-  };
-
-  /** 4) submit/액션 — trigger별 추가 context를 append/reset 할 수 있게 연다. */
-  const setNextAdditionalUserContext: UseServiceInquiryUserContextReturn["setAdditionalUserContext"] =
-    nextUserContext => {
-      setAdditionalUserContext(nextUserContext);
-    };
-
-  const appendUserContext: UseServiceInquiryUserContextReturn["appendUserContext"] =
-    (nextUserContext?: ServiceInquiryUserContext | null) => {
-      if (!nextUserContext) {
-        return;
-      }
-
-      setAdditionalUserContext(currentUserContext => ({
-        ...(currentUserContext ?? {}),
-        ...nextUserContext,
-      }));
-    };
-
-  const clearAdditionalUserContext: UseServiceInquiryUserContextReturn["clearAdditionalUserContext"] =
-    () => {
-      setAdditionalUserContext(null);
-    };
-
-  return {
-    requestContext,
-    additionalUserContext,
-    setAdditionalUserContext: setNextAdditionalUserContext,
-    appendUserContext,
-    clearAdditionalUserContext,
-  };
-}