@uniai-fe/uds-templates 0.4.2 → 0.4.4

package/README.md

@@ -55,6 +55,17 @@ Next.js 서비스에서 primitives와 동일한 방식으로 **Raw TypeScript**
   - `weatherCoordinate`
   - `useWeatherKorea`
   - `useOpenWeatherMap`
+- `/service-inquiry`
+  - `ServiceInquiry.Form`
+  - `ServiceInquiry.OpenButton`
+  - `ServiceInquiry.useOpen`
+  - `ServiceInquiry.useProvideContext`
+  - `ServiceInquiry.useUserContext`
+  - `ServiceInquiry.createModal`
+  - `ServiceInquiryFieldMode`
+  - `ServiceInquiryFormProps`
+  - `ServiceInquiryFormValues`
+  - `ServiceInquiryProvidedContext`
 - `/cctv`
   - `CCTV.Provider`
   - `CCTV.CamList.Container`
@@ -95,6 +106,11 @@ Next.js 서비스에서 primitives와 동일한 방식으로 **Raw TypeScript**
 - `/modal/**`
   - 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, 페이지 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 도구를 제공한다.
 - `/cctv/**`
@@ -104,6 +120,17 @@ Next.js 서비스에서 primitives와 동일한 방식으로 **Raw TypeScript**
 
 각 템플릿의 상세한 범위와 의사결정은 `CONTEXT-*.md` 문서에서 관리합니다.
 
+### Service Inquiry 도입 흐름
+
+1. 서비스 앱이 `react-hook-form`으로 `defaultValues`와 `onSubmit`을 준비한다.
+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까지만 제공하고, 네트워크 상태/재시도/성공·실패 피드백은 서비스 앱이 소유합니다.
+
 ### 회원가입 Step 구조
 
 1. **Step1 — User Info (name + phone)**: 기본 정보 입력. PhoneInput은 인증 UI 없이 마스킹만 제공한다.

package/dist/styles.css

@@ -1732,3 +1732,35 @@
 .cctv-viewer-desktop-pagination-container {
   margin-top: var(--spacing-gap-8);
 }
+
+.service-inquiry-form {
+  display: flex;
+  flex-direction: column;
+}
+
+.service-inquiry-fields {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-padding-5);
+}
+
+.service-inquiry-field {
+  display: flex;
+  flex-direction: column;
+}
+
+.service-inquiry-open-button {
+  width: 40px;
+  height: 40px;
+  border-radius: 20px;
+  border: 1px solid var(--color-border-standard-cool-gray);
+  background: var(--color_100);
+  color: var(--color-label-neutral);
+  font-size: 24px;
+  font-weight: 400;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
+  cursor: pointer;
+}

package/package.json

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

package/src/index.scss

@@ -9,3 +9,4 @@
 @use "./auth/index.scss" as authStyles;
 @use "./weather/index.scss" as weatherStyles;
 @use "./cctv/index.scss" as cctvStyles;
+@use "./service-inquiry/index.scss" as serviceInquiryStyles;

package/src/index.tsx

@@ -6,5 +6,6 @@ export * from "./auth";
 export * from "./modal";
 export * from "./weather";
 export * from "./cctv";
+export * from "./service-inquiry";
 
 export type * from "./types";

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

@@ -0,0 +1,145 @@
+"use client";
+
+import clsx from "clsx";
+import { Form, Input } from "@uniai-fe/uds-primitives";
+import { useFormContext } from "react-hook-form";
+import type { ServiceInquiryFieldKey, ServiceInquiryFormProps } from "../types";
+import type { ServiceInquiryFormValues } from "../types";
+
+/**
+ * Service Inquiry Form; 문의 입력 form
+ * @component
+ * @param {ServiceInquiryFormProps} props 문의 form props
+ * @param {string} [props.className] form className
+ * @param {ServiceInquiryFieldKey[]} [props.visibleFields] 노출 필드 목록
+ * @param {ServiceInquiryInputFieldProps} [props.farmNameField] 농장명 필드 설정
+ * @param {ServiceInquiryInputFieldProps} [props.contactField] 연락처 필드 설정
+ * @param {ServiceInquiryTextAreaFieldProps} [props.textField] 문의 본문 필드 설정
+ * @param {SubmitHandler<ServiceInquiryFormValues>} props.onSubmit 문의 제출 핸들러
+ * @example
+ * <ServiceInquiryForm onSubmit={values => console.info(values)} />
+ */
+const ServiceInquiryForm = ({
+  className,
+  visibleFields,
+  farmNameField,
+  contactField,
+  textField,
+  onSubmit,
+}: ServiceInquiryFormProps) => {
+  const form = useFormContext<ServiceInquiryFormValues>();
+
+  // 변경 설명: Modal.Dialog confirm 기본 submit과 연결되도록 form.handleSubmit 결과를 그대로 onSubmit에 바인딩한다.
+  const handleSubmit = form.handleSubmit(onSubmit);
+
+  return (
+    <form
+      className={clsx("service-inquiry-form", className)}
+      onSubmit={handleSubmit}
+    >
+      <div className="service-inquiry-fields">
+        {(visibleFields?.includes("farm_name") ?? true) ? (
+          <Form.Field.Template
+            className={clsx(
+              "service-inquiry-field",
+              "service-inquiry-field-farm-name",
+            )}
+            width="full"
+            headerProps={{
+              required: farmNameField?.required,
+              ...(typeof farmNameField?.label === "string"
+                ? { label: farmNameField.label }
+                : typeof farmNameField?.label === "number"
+                  ? { label: String(farmNameField.label) }
+                  : {
+                      labelJsx:
+                        typeof farmNameField?.label === "undefined"
+                          ? "농장명"
+                          : farmNameField.label,
+                    }),
+            }}
+            footer={farmNameField?.helper}
+          >
+            <Input.Base
+              type="text"
+              block={true}
+              readOnly={farmNameField?.mode === "readonly"}
+              placeholder={farmNameField?.placeholder ?? "농장명 입력"}
+              register={form.register("farm_name")}
+            />
+          </Form.Field.Template>
+        ) : null}
+
+        {(visibleFields?.includes("contact") ?? true) ? (
+          <Form.Field.Template
+            className={clsx(
+              "service-inquiry-field",
+              "service-inquiry-field-contact",
+            )}
+            width="full"
+            headerProps={{
+              required: contactField?.required ?? true,
+              ...(typeof contactField?.label === "string"
+                ? { label: contactField.label }
+                : typeof contactField?.label === "number"
+                  ? { label: String(contactField.label) }
+                  : {
+                      labelJsx:
+                        typeof contactField?.label === "undefined"
+                          ? "연락처"
+                          : contactField.label,
+                    }),
+            }}
+            footer={contactField?.helper}
+          >
+            <Input.Base
+              type="text"
+              block={true}
+              readOnly={contactField?.mode === "readonly"}
+              placeholder={
+                contactField?.placeholder ?? "이메일 또는 전화번호 입력"
+              }
+              register={form.register("contact")}
+            />
+          </Form.Field.Template>
+        ) : null}
+
+        {(visibleFields?.includes("text") ?? true) ? (
+          <Form.Field.Template
+            className={clsx(
+              "service-inquiry-field",
+              "service-inquiry-field-text",
+            )}
+            width="full"
+            headerProps={{
+              required: textField?.required ?? true,
+              ...(typeof textField?.label === "string"
+                ? { label: textField.label }
+                : typeof textField?.label === "number"
+                  ? { label: String(textField.label) }
+                  : {
+                      labelJsx:
+                        typeof textField?.label === "undefined"
+                          ? "문의 내용"
+                          : textField.label,
+                    }),
+            }}
+            footer={textField?.helper}
+          >
+            <Input.TextArea
+              block={true}
+              placeholder={
+                textField?.placeholder ?? "문의 내용을 자세히 입력해 주세요."
+              }
+              height={160}
+              length={10000}
+              register={form.register("text")}
+            />
+          </Form.Field.Template>
+        ) : null}
+      </div>
+    </form>
+  );
+};
+
+export default ServiceInquiryForm;

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

@@ -0,0 +1,46 @@
+"use client";
+
+import { useOpenServiceInquiry } from "../hooks";
+import type { UseOpenServiceInquiryOptions } from "../types";
+
+/**
+ * Service Inquiry Open Button; 문의 모달 trigger adapter
+ * @component
+ * @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
+ * @param {() => void} [props.onOpen] 모달 open 직전 콜백
+ * @example
+ * <ServiceInquiryOpenButton
+ *   stackKey="sample"
+ *   formProps={{ onSubmit: values => console.info(values) }}
+ * />
+ */
+const ServiceInquiryOpenButton = ({
+  stackKey,
+  formProps,
+  dialogOptions,
+  onOpen,
+}: UseOpenServiceInquiryOptions) => {
+  const { openServiceInquiry } = useOpenServiceInquiry({
+    stackKey,
+    formProps,
+    dialogOptions,
+    onOpen,
+  });
+
+  return (
+    <button
+      type="button"
+      className="service-inquiry-open-button"
+      aria-label="문의하기"
+      // 변경 설명: 기본 제공 버튼은 고정 원형 `?` 버튼 사양으로 렌더링한다.
+      onClick={openServiceInquiry}
+    >
+      ?
+    </button>
+  );
+};
+
+export default ServiceInquiryOpenButton;

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

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

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

@@ -0,0 +1,48 @@
+"use client";
+
+import { Modal } from "../../modal";
+import { createServiceInquiryModal } from "../utils/modal-option";
+import type {
+  UseOpenServiceInquiryOptions,
+  UseOpenServiceInquiryReturn,
+} from "../types";
+
+/**
+ * Service Inquiry Hook; 문의 모달 열기 Hook
+ * @hook
+ * @param {UseOpenServiceInquiryOptions} options 문의 모달 열기 훅 옵션
+ * @param {string} options.stackKey modal stack key
+ * @param {ServiceInquiryFormProps} options.formProps 문의 form props
+ * @param {Partial<DialogTemplateOptions<ServiceInquiryFormValues>>} [options.dialogOptions] 문의 모달 preset 위에 덮어쓸 dialog option
+ * @param {() => void} [options.onOpen] 모달 open 직전 콜백
+ * @returns {UseOpenServiceInquiryReturn} 문의 모달 open 함수
+ * @example
+ * const { openServiceInquiry } = useOpenServiceInquiry({
+ *   stackKey: "sample",
+ *   formProps: { onSubmit: values => console.info(values) },
+ * });
+ */
+export function useOpenServiceInquiry({
+  stackKey,
+  formProps,
+  dialogOptions,
+  onOpen,
+}: UseOpenServiceInquiryOptions): UseOpenServiceInquiryReturn {
+  const { newModal } = Modal.useModal();
+
+  // 변경 설명: 커스텀 버튼은 render prop 대신 hook이 돌려주는 단일 open 함수로 연결한다.
+  const openServiceInquiry = () => {
+    onOpen?.();
+    newModal(
+      createServiceInquiryModal({
+        stackKey,
+        formProps,
+        dialogOptions,
+      }),
+    );
+  };
+
+  return {
+    openServiceInquiry,
+  };
+}

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.scss

@@ -0,0 +1 @@
+@use "./styles/index.scss";

package/src/service-inquiry/index.tsx

@@ -0,0 +1,32 @@
+import "./index.scss";
+import ServiceInquiryForm from "./components/Form";
+import ServiceInquiryOpenButton from "./components/OpenButton";
+import {
+  useOpenServiceInquiry,
+  useProvideServiceInquiryContext,
+  useServiceInquiryUserContext,
+} from "./hooks";
+import { createServiceInquiryModal } from "./utils/modal-option";
+
+/**
+ * Service Inquiry; 문의 form + modal option 엔트리
+ * - 변경 설명: Step 2에서 Form과 Modal.Dialog 기반 factory를 첫 runtime 조각으로 연다.
+ */
+export const ServiceInquiry = {
+  Form: ServiceInquiryForm,
+  OpenButton: ServiceInquiryOpenButton,
+  useOpen: useOpenServiceInquiry,
+  useProvideContext: useProvideServiceInquiryContext,
+  useUserContext: useServiceInquiryUserContext,
+  createModal: createServiceInquiryModal,
+};
+
+export {
+  ServiceInquiryForm,
+  ServiceInquiryOpenButton,
+  useOpenServiceInquiry,
+  useProvideServiceInquiryContext,
+  useServiceInquiryUserContext,
+  createServiceInquiryModal,
+};
+export type * from "./types";

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/styles/form.scss

@@ -0,0 +1,15 @@
+.service-inquiry-form {
+  display: flex;
+  flex-direction: column;
+}
+
+.service-inquiry-fields {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-padding-5);
+}
+
+.service-inquiry-field {
+  display: flex;
+  flex-direction: column;
+}

package/src/service-inquiry/styles/index.scss

@@ -0,0 +1,2 @@
+@use "./form.scss";
+@use "./open-button.scss";

package/src/service-inquiry/styles/open-button.scss

@@ -0,0 +1,15 @@
+.service-inquiry-open-button {
+  width: 40px;
+  height: 40px;
+  border-radius: 20px;
+  border: 1px solid var(--color-border-standard-cool-gray);
+  background: var(--color_100);
+  color: var(--color-label-neutral);
+  font-size: 24px;
+  font-weight: 400;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
+  cursor: pointer;
+}

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

@@ -0,0 +1,68 @@
+import type { ServiceInquiryUserContext } from "./form-context";
+
+/**
+ * Service Inquiry API; 문의 등록 요청
+ * @property {string} text 문의 본문
+ * @property {string} farm_name 문의 대상 농장명 또는 빈 문자열
+ * @property {string[]} labels JIRA label 목록
+ * @property {string} contact 문의자 연락처(email 또는 phone number)
+ * @property {string} page_path 문의하기를 연 페이지 경로
+ * @property {ServiceInquiryUserContext | null} user_context 문의 시점 사용자/환경 맥락
+ */
+export interface API_Req_ServiceInquiry {
+  /**
+   * 문의 본문
+   */
+  text: string;
+  /**
+   * 문의 대상 농장명 또는 빈 문자열
+   */
+  farm_name: string;
+  /**
+   * JIRA label 목록
+   */
+  labels: string[];
+  /**
+   * 문의자 연락처
+   */
+  contact: string;
+  /**
+   * 문의하기를 연 페이지 경로
+   */
+  page_path: string;
+  /**
+   * 문의 시점 사용자/환경 맥락
+   */
+  user_context: ServiceInquiryUserContext | null;
+}
+
+/**
+ * Service Inquiry API; 문의 등록 응답
+ * @property {boolean} success 문의 등록 성공 여부
+ * @property {string} issue_key JIRA issue key
+ * @property {string} issue_url JIRA issue URL
+ * @property {string} summary JIRA issue 제목
+ * @property {string} message 서버 응답 메시지
+ */
+export interface API_Res_ServiceInquiry {
+  /**
+   * 문의 등록 성공 여부
+   */
+  success: boolean;
+  /**
+   * JIRA issue key
+   */
+  issue_key: string;
+  /**
+   * JIRA issue URL
+   */
+  issue_url: string;
+  /**
+   * JIRA issue 제목
+   */
+  summary: string;
+  /**
+   * 서버 응답 메시지
+   */
+  message: string;
+}

package/src/service-inquiry/types/form-context.ts

@@ -0,0 +1,48 @@
+/**
+ * Service Inquiry Form; 사용자 입력값
+ * @property {string} text 문의 본문
+ * @property {string} farm_name 농장명 또는 빈 문자열
+ * @property {string} contact 문의자 연락처
+ */
+export interface ServiceInquiryFormValues {
+  /**
+   * 문의 본문
+   */
+  text: string;
+  /**
+   * 농장명 또는 빈 문자열
+   */
+  farm_name: string;
+  /**
+   * 문의자 연락처
+   */
+  contact: string;
+}
+
+/**
+ * Service Inquiry Form; 시스템 주입 request context
+ * @property {string[]} labels JIRA label 목록
+ * @property {string} page_path 문의를 연 페이지 경로
+ * @property {ServiceInquiryUserContext | null} user_context 문의 시점 사용자/환경 맥락
+ */
+export interface ServiceInquiryRequestContext {
+  /**
+   * JIRA label 목록
+   */
+  labels: string[];
+  /**
+   * 문의를 연 페이지 경로
+   */
+  page_path: string;
+  /**
+   * 문의 시점 사용자/환경 맥락
+   */
+  user_context: ServiceInquiryUserContext | null;
+}
+
+/**
+ * Service Inquiry Form; 사용자/환경 맥락 payload
+ * @property {unknown} [key] 디버깅을 위한 사용자 동작/환경 스냅샷
+ */
+// 변경 설명: user_context는 서비스별 arbitrary object 확장 지점이므로 Record 기반 의도를 타입 이름에서 바로 읽히게 맞춘다.
+export interface ServiceInquiryUserContext extends Record<string, unknown> {}

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

@@ -0,0 +1,60 @@
+import type {
+  ServiceInquiryRequestContext,
+  ServiceInquiryUserContext,
+} from "./form-context";
+
+/**
+ * Service Inquiry Hook; 모듈 내부 공유 context 값
+ * @property {string[]} [labels] 문의 request에 포함할 labels
+ * @property {string} [pagePath] 문의를 연 페이지 경로
+ * @property {ServiceInquiryUserContext | null} [userContext] 페이지/폼이 제공하는 추가 user_context
+ */
+export interface ServiceInquiryProvidedContext {
+  /**
+   * 문의 request에 포함할 labels
+   */
+  labels?: string[];
+  /**
+   * 문의를 연 페이지 경로
+   */
+  pagePath?: string;
+  /**
+   * 페이지/폼이 제공하는 추가 user_context
+   */
+  userContext?: ServiceInquiryUserContext | null;
+}
+
+/**
+ * Service Inquiry Hook; user_context 훅 반환값
+ * @property {ServiceInquiryRequestContext} requestContext form submit에 바로 사용할 request context
+ * @property {ServiceInquiryUserContext | null} additionalUserContext trigger/interaction에서 추가된 user_context
+ * @property {(nextUserContext: ServiceInquiryUserContext | null) => void} setAdditionalUserContext 추가 user_context 교체 함수
+ * @property {(nextUserContext?: ServiceInquiryUserContext | null) => void} appendUserContext 추가 user_context 병합 함수
+ * @property {() => void} clearAdditionalUserContext 추가 user_context 초기화 함수
+ */
+export interface UseServiceInquiryUserContextReturn {
+  /**
+   * form submit에 바로 사용할 request context
+   */
+  requestContext: ServiceInquiryRequestContext;
+  /**
+   * trigger/interaction에서 추가된 user_context
+   */
+  additionalUserContext: ServiceInquiryUserContext | null;
+  /**
+   * 추가 user_context 교체 함수
+   */
+  setAdditionalUserContext: (
+    nextUserContext: ServiceInquiryUserContext | null,
+  ) => void;
+  /**
+   * 추가 user_context 병합 함수
+   */
+  appendUserContext: (
+    nextUserContext?: ServiceInquiryUserContext | null,
+  ) => void;
+  /**
+   * 추가 user_context 초기화 함수
+   */
+  clearAdditionalUserContext: () => void;
+}

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

@@ -0,0 +1,4 @@
+export type * from "./api";
+export type * from "./form-context";
+export type * from "./hooks";
+export type * from "./props";

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

@@ -0,0 +1,146 @@
+import type { ReactNode } from "react";
+import type { SubmitHandler } from "react-hook-form";
+import type { DialogTemplateOptions } from "../../modal/types";
+import type { ServiceInquiryFormValues } from "./form-context";
+
+/**
+ * Service Inquiry; 노출 필드 키
+ */
+export type ServiceInquiryFieldKey = "farm_name" | "contact" | "text";
+
+/**
+ * Service Inquiry Form; field 입력 모드
+ * @typedef {"editable" | "readonly"} ServiceInquiryFieldMode
+ */
+export type ServiceInquiryFieldMode = "editable" | "readonly";
+
+/**
+ * Service Inquiry Form; 공통 field 설정
+ * @property {ReactNode} [label] field label
+ * @property {ReactNode} [helper] field helper
+ * @property {boolean} [required] required 표시 여부
+ */
+export interface ServiceInquiryFieldBaseProps {
+  /**
+   * field label
+   */
+  label?: ReactNode;
+  /**
+   * field helper
+   */
+  helper?: ReactNode;
+  /**
+   * required 표시 여부
+   */
+  required?: boolean;
+}
+
+/**
+ * Service Inquiry Form; 단일 line input field 설정
+ * @property {"editable" | "readonly"} [mode] 서비스가 제어하는 field 입력 모드
+ * @property {string} [placeholder] input placeholder
+ */
+export interface ServiceInquiryInputFieldProps extends ServiceInquiryFieldBaseProps {
+  /**
+   * 서비스가 제어하는 field 입력 모드
+   */
+  mode?: ServiceInquiryFieldMode;
+  /**
+   * input placeholder
+   */
+  placeholder?: string;
+}
+
+/**
+ * Service Inquiry Form; textarea field 설정
+ * @property {string} [placeholder] textarea placeholder
+ */
+export interface ServiceInquiryTextAreaFieldProps extends ServiceInquiryFieldBaseProps {
+  /**
+   * textarea placeholder
+   */
+  placeholder?: string;
+}
+
+/**
+ * Service Inquiry Form; 문의 입력 폼 props
+ * @property {string} [className] form className
+ * @property {ServiceInquiryFieldKey[]} [visibleFields] 노출 필드 목록
+ * @property {ServiceInquiryInputFieldProps} [farmNameField] 농장명 필드 설정
+ * @property {ServiceInquiryInputFieldProps} [contactField] 연락처 필드 설정
+ * @property {ServiceInquiryTextAreaFieldProps} [textField] 문의 본문 필드 설정
+ * @property {SubmitHandler<ServiceInquiryFormValues>} props.onSubmit 문의 제출 핸들러
+ */
+export interface ServiceInquiryFormProps {
+  /**
+   * form className
+   */
+  className?: string;
+  /**
+   * 노출 필드 목록
+   */
+  visibleFields?: ServiceInquiryFieldKey[];
+  /**
+   * 농장명 필드 설정
+   */
+  farmNameField?: ServiceInquiryInputFieldProps;
+  /**
+   * 연락처 필드 설정
+   */
+  contactField?: ServiceInquiryInputFieldProps;
+  /**
+   * 문의 본문 필드 설정
+   */
+  textField?: ServiceInquiryTextAreaFieldProps;
+  /**
+   * 문의 제출 핸들러
+   */
+  onSubmit: SubmitHandler<ServiceInquiryFormValues>;
+}
+
+/**
+ * Service Inquiry Modal; 문의 모달 preset 생성 옵션
+ * @property {string} stackKey modal stack key
+ * @property {ServiceInquiryFormProps} formProps 문의 form props
+ * @property {Partial<DialogTemplateOptions<ServiceInquiryFormValues>>} [dialogOptions] 문의 모달 preset 위에 덮어쓸 dialog option
+ */
+// 변경 설명: DialogTemplateOptions를 거의 다시 적는 wrapper 대신, 모듈 고유 필드와 dialog override bag만 가진 preset 입력 타입으로 줄인다.
+export interface ServiceInquiryCreateModalOptions {
+  /**
+   * modal stack key
+   */
+  stackKey: string;
+  /**
+   * 문의 form props
+   */
+  formProps: ServiceInquiryFormProps;
+  /**
+   * 문의 모달 preset 위에 덮어쓸 dialog option
+   */
+  dialogOptions?: Partial<DialogTemplateOptions<ServiceInquiryFormValues>>;
+}
+
+/**
+ * Service Inquiry Hook; 문의 모달 열기 훅 옵션
+ * @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 UseOpenServiceInquiryOptions extends ServiceInquiryCreateModalOptions {
+  /**
+   * 모달 open 직전 콜백
+   */
+  onOpen?: () => void;
+}
+
+/**
+ * Service Inquiry Hook; 문의 모달 열기 훅 반환값
+ * @property {() => void} openServiceInquiry 문의 모달 open 함수
+ */
+export interface UseOpenServiceInquiryReturn {
+  /**
+   * 문의 모달 open 함수
+   */
+  openServiceInquiry: () => void;
+}

package/src/service-inquiry/utils/modal-option.tsx

@@ -0,0 +1,38 @@
+import { createDialogModal } from "../../modal/components/dialog/Template";
+import ServiceInquiryForm from "../components/Form";
+import type {
+  ServiceInquiryCreateModalOptions,
+  ServiceInquiryFormValues,
+} from "../types";
+
+/**
+ * Service Inquiry Modal; 문의 form이 포함된 Dialog option 생성기
+ * @component
+ * @param {ServiceInquiryCreateModalOptions} options 문의 모달 preset 생성 옵션
+ * @param {string} options.stackKey modal stack key
+ * @param {ServiceInquiryFormProps} options.formProps 문의 form props
+ * @param {Partial<DialogTemplateOptions<ServiceInquiryFormValues>>} [options.dialogOptions] 문의 모달 preset 위에 덮어쓸 dialog option
+ * @example
+ * createServiceInquiryModal({
+ *   stackKey: "service-inquiry",
+ *   formProps: { onSubmit: values => console.info(values) },
+ * })
+ */
+export function createServiceInquiryModal({
+  stackKey,
+  formProps,
+  dialogOptions,
+}: ServiceInquiryCreateModalOptions) {
+  return createDialogModal<ServiceInquiryFormValues>({
+    ...dialogOptions,
+    stackKey,
+    title: dialogOptions?.title ?? "문의하기",
+    // 변경 설명: 문의 모달은 title과 안내 문구를 좌측 정렬로 읽히게 하기 위해 split header를 기본값으로 사용한다.
+    headerLayout: dialogOptions?.headerLayout ?? "split",
+    content: <ServiceInquiryForm {...formProps} />,
+    confirm: {
+      label: "문의 접수",
+      ...dialogOptions?.confirm,
+    },
+  });
+}