@uniai-fe/uds-templates 0.4.1 → 0.4.3

package/README.md

@@ -55,6 +55,15 @@ Next.js 서비스에서 primitives와 동일한 방식으로 **Raw TypeScript**
   - `weatherCoordinate`
   - `useWeatherKorea`
   - `useOpenWeatherMap`
+- `/service-inquiry`
+  - `ServiceInquiry.Form`
+  - `ServiceInquiry.OpenButton`
+  - `ServiceInquiry.useOpen`
+  - `ServiceInquiry.useUserContext`
+  - `ServiceInquiry.createModal`
+  - `ServiceInquiryFieldMode`
+  - `ServiceInquiryFormProps`
+  - `ServiceInquiryFormValues`
 - `/cctv`
   - `CCTV.Provider`
   - `CCTV.CamList.Container`
@@ -95,6 +104,10 @@ 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, request context 조립 hook, modal preset factory를 제공한다.
+  - submit transport, React Query mutation, Next.js route handler, 에러 피드백(`Modal.Alert`)은 서비스 앱이 소유한다.
+  - 로그인 후 `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 +117,16 @@ Next.js 서비스에서 primitives와 동일한 방식으로 **Raw TypeScript**
 
 각 템플릿의 상세한 범위와 의사결정은 `CONTEXT-*.md` 문서에서 관리합니다.
 
+### 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` 조합으로 처리한다.
+
+`service-inquiry`는 구조와 request context까지만 제공하고, 네트워크 상태/재시도/성공·실패 피드백은 서비스 앱이 소유합니다.
+
 ### 회원가입 Step 구조
 
 1. **Step1 — User Info (name + phone)**: 기본 정보 입력. PhoneInput은 인증 UI 없이 마스킹만 제공한다.

package/dist/styles.css

@@ -746,6 +746,46 @@
     transition: none;
   }
 }
+.auth-stage-header {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-padding-5, 20px);
+  padding: 0 var(--spacing-padding-1, 4px);
+}
+
+.auth-stage-step {
+  display: flex;
+  justify-content: flex-start;
+}
+
+.auth-stage-step-pagination {
+  --pagination-carousel-gap: 6px;
+}
+
+.auth-stage-headline {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-padding-1, 4px);
+}
+
+.auth-stage-headline-text {
+  margin: 0;
+  font-size: 24px;
+  font-weight: 600;
+  line-height: 1.4;
+  letter-spacing: 0.2px;
+  color: var(--color-label-standard);
+  font-family: "Pretendard JP Variable", "Pretendard", system-ui, -apple-system, BlinkMacSystemFont, sans-serif;
+}
+
+.auth-stage-headline-description {
+  margin: 0;
+  font-size: 14px;
+  line-height: 1.4;
+  color: var(--color-label-assistive);
+  font-family: "Pretendard", system-ui, -apple-system, BlinkMacSystemFont, sans-serif;
+}
+
 
 
 .auth-container {
@@ -826,6 +866,10 @@
   margin-top: var(--spacing-padding-4, 16px);
 }
 
+.auth-code-field {
+  margin-top: var(--spacing-gap-6);
+}
+
 .auth-login-form {
   display: flex;
   flex-direction: column;
@@ -1067,6 +1111,59 @@
   margin: 0;
 }
 
+.password-confirm-field {
+  margin-top: var(--spacing-gap-6);
+}
+
+.auth-password-helper {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--spacing-gap-3);
+  margin-top: var(--spacing-gap-2);
+}
+
+.auth-password-helper-column {
+  flex-direction: column;
+  align-items: flex-start;
+  gap: var(--spacing-gap-1);
+}
+
+.auth-set-password-icon {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 0;
+}
+.auth-set-password-icon svg path {
+  fill: var(--color-label-assistive);
+}
+
+.auth-password-helper-text {
+  font-size: var(--font-label-small-size);
+  line-height: var(--font-label-small-line-height);
+  font-weight: var(--font-label-small-weight);
+  color: var(--color-label-assistive);
+}
+
+.auth-password-helper-item {
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-gap-1);
+}
+.auth-password-helper-item[data-state=complete] .auth-password-helper-text {
+  color: var(--color-success);
+}
+.auth-password-helper-item[data-state=complete] .auth-set-password-icon svg path {
+  fill: var(--color-success);
+}
+.auth-password-helper-item[data-state=error] .auth-password-helper-text {
+  color: var(--color-error);
+}
+.auth-password-helper-item[data-state=error] .auth-set-password-icon svg path {
+  fill: var(--color-error);
+}
+
 .auth-signup-form {
   display: flex;
   flex-direction: column;
@@ -1635,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.1",
+  "version": "0.4.3",
   "description": "UNIAI Design System; UI Templates Package",
   "type": "module",
   "private": false,
@@ -12,7 +12,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "packageManager": "pnpm@10.32.1",
+  "packageManager": "pnpm@10.33.0",
   "engines": {
     "node": ">=24",
     "pnpm": ">=10"
@@ -70,7 +70,7 @@
   },
   "devDependencies": {
     "@svgr/webpack": "^8.1.0",
-    "@tanstack/react-query": "^5.91.2",
+    "@tanstack/react-query": "^5.95.2",
     "@types/node": "^24.10.2",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
@@ -86,10 +86,10 @@
     "@uniai-fe/util-next": "workspace:*",
     "@uniai-fe/util-rtc": "workspace:*",
     "eslint": "^9.39.2",
-    "jotai": "^2.18.1",
+    "jotai": "^2.19.0",
     "next": "^15.5.11",
     "prettier": "^3.8.1",
-    "react-hook-form": "^7.71.2",
+    "react-hook-form": "^7.72.0",
     "sass": "^1.98.0",
     "typescript": "~5.9.3"
   }

package/src/auth/common/container/index.scss

@@ -1,3 +1,5 @@
+@use "./header/stage-header.scss";
+
 :root {
   --auth-container-max-width: 335px;
   --auth-container-gap: var(--spacing-padding-7, 28px);

package/src/auth/common/container/index.tsx

@@ -1,5 +1,4 @@
 import "./index.scss";
-import "./header/stage-header.scss";
 
 export { AuthStageHeader } from "./header";
 export { AuthContainer } from "./AuthContainer";

package/src/auth/find-id/markup/StepComplete.tsx

@@ -24,7 +24,7 @@ export default function FindIdStepComplete({
       title={title ?? "아이디 찾기 완료"}
       description={description ?? "로그인 페이지로 이동하여 로그인합니다."}
       cta={{
-        label: cta?.label ?? "로그인하기",
+        label: cta?.label ?? "확인",
         buttonProps: cta?.buttonProps,
       }}
     >

package/src/auth/find-password/index.scss

@@ -1 +1,3 @@
 @use "../common/find/styles/find-account.scss";
+// StepReset password helper는 외부 앱의 `@uniai-fe/uds-templates/css` 엔트리에도 포함돼야 한다.
+@use "../common/password/styles/set-password.scss";

package/src/auth/find-password/markup/StepComplete.tsx

@@ -20,7 +20,7 @@ export default function FindPasswordStepComplete({
       title={title ?? "비밀번호 변경 완료"}
       description={description ?? "로그인 페이지로 이동하여 로그인해 주세요."}
       cta={{
-        label: cta?.label ?? "로그인하기",
+        label: cta?.label ?? "확인",
         buttonProps: cta?.buttonProps,
       }}
     />

package/src/auth/index.scss

@@ -0,0 +1,7 @@
+@use "./common/container/index.scss" as authCommonContainer;
+@use "./common/complete/index.scss" as authCommonComplete;
+@use "./common/auth-code/styles/index.scss" as authCommonAuthCode;
+@use "./login/index.scss" as authLogin;
+@use "./find-id/index.scss" as authFindId;
+@use "./find-password/index.scss" as authFindPassword;
+@use "./signup/styles/signup.scss" as authSignup;

package/src/auth/index.tsx

@@ -1,4 +1,4 @@
-import "./login/index.scss";
+import "./index.scss";
 
 import {
   AuthContainer,

package/src/auth/login/types/api.ts

@@ -51,6 +51,58 @@ export interface API_Res_LoginUserFarm {
   user_access_role: string;
 }
 
+/**
+ * 로그인 API; 응답 - 소속 부서 정보
+ * @route /auth/user/login
+ * @property {number} org_id 소속 조직 인덱스
+ * @property {string} org_name 소속 조직명
+ * @property {string} org_type 소속 조직 유형 코드
+ * @property {number} parent_org_id 상위 조직 인덱스
+ * @property {string} parent_org_name 상위 조직명
+ * @property {number} root_org_id 최상위 조직 인덱스
+ * @property {string} root_org_name 최상위 조직명
+ * @property {number} position_id 직책 인덱스
+ * @property {string} position_name 직책명
+ */
+export interface API_Res_LoginUserAuth {
+  /**
+   * 소속 조직 인덱스
+   */
+  org_id: number;
+  /**
+   * 소속 조직명
+   */
+  org_name: string;
+  /**
+   * 소속 조직 유형 코드
+   */
+  org_type: string;
+  /**
+   * 상위 조직 인덱스
+   */
+  parent_org_id: number;
+  /**
+   * 상위 조직명
+   */
+  parent_org_name: string;
+  /**
+   * 최상위 조직 인덱스
+   */
+  root_org_id: number;
+  /**
+   * 최상위 조직명
+   */
+  root_org_name: string;
+  /**
+   * 직책 인덱스
+   */
+  position_id: number;
+  /**
+   * 직책명
+   */
+  position_name: string;
+}
+
 /**
  * 로그인 API; 응답 - 유저 정보
  * @route /auth/user/login
@@ -120,6 +172,19 @@ export interface API_Res_LoginUserInfo {
    * @property {string} user_access_role 계정 권한/직책 코드 (OWNER: 농장주, EMPLOYEE: 농장직원, REGIONAL_MANAGER: 지역소장)
    */
   user_farms: API_Res_LoginUserFarm[];
+  /**
+   * (avic 전용) 소속부서 정보
+   * @property {number} org_id 소속 조직 인덱스
+   * @property {string} org_name 소속 조직명
+   * @property {string} org_type 소속 조직 유형 코드
+   * @property {number} parent_org_id 상위 조직 인덱스
+   * @property {string} parent_org_name 상위 조직명
+   * @property {number} root_org_id 최상위 조직 인덱스
+   * @property {string} root_org_name 최상위 조직명
+   * @property {number} position_id 직책 인덱스
+   * @property {string} position_name 직책명
+   */
+  avic_organizations: API_Res_LoginUserAuth[];
   /**
    * 가입일 (UTC)
    * - yyyy-MM-ddTHH:mm:ss

package/src/cctv/index.tsx

@@ -1,5 +1,3 @@
-import "./index.scss";
-
 /**
  * CCTV; viewer, cam-list, pagination, api/hook/jotai 도구를 함께 제공하는 엔트리
  */

package/src/index.scss

@@ -3,15 +3,10 @@
 
 /* 템플릿 레벨 스타일을 통합해 서비스 앱이 단일 엔트리만 import하도록 구성한다. */
 /* namespace 충돌을 막기 위해 모든 @use 경로에 고유 alias를 부여한다. */
-@use "./page-frame/desktop/index.scss" as pageFrameDesktop;
-@use "./page-frame/mobile/index.scss" as pageFrameMobile;
+@use "./page-frame/index.scss" as pageFrameStyles;
 @use "./modal/index.scss" as modalStyles;
 
-@use "./auth/common/container/index.scss" as authCommonContainer;
-@use "./auth/common/complete/index.scss" as authCommonComplete;
-@use "./auth/login/index.scss" as authLogin;
-@use "./auth/find-id/index.scss" as authFindId;
-@use "./auth/find-password/index.scss" as authFindPassword;
-@use "./auth/signup/styles/signup.scss" as authSignup;
+@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

@@ -1,7 +1,11 @@
+import "./modal/index.scss";
+import "./cctv/index.scss";
+
 export * from "./page-frame";
 export * from "./auth";
 export * from "./modal";
 export * from "./weather";
 export * from "./cctv";
+export * from "./service-inquiry";
 
 export type * from "./types";

package/src/modal/index.tsx

@@ -1,5 +1,3 @@
-import "./index.scss";
-
 import { modalStackAtom } from "./jotai/atoms";
 import {
   ModalNamespace,

package/src/page-frame/desktop/components/header/util/setting/Button.tsx

@@ -64,8 +64,9 @@ export default function PageHeaderSettingButton({
   }, [menuItems]);
 
   const isMatchRouteGroup = useMemo(
-    () => pathname.startsWith(commonRoute),
-    [pathname, commonRoute],
+    // Storybook의 next/navigation mock에서는 pathname이 null일 수 있어 fallback 경로를 재사용한다.
+    () => resolvedPath.startsWith(commonRoute),
+    [resolvedPath, commonRoute],
   );
 
   const dropdownItems: DropdownTemplateItem[] = useMemo(

package/src/page-frame/desktop/index.tsx

@@ -1,5 +1,3 @@
-import "./index.scss";
-
 import Frame from "./components";
 
 /**

package/src/page-frame/index.scss

@@ -0,0 +1,2 @@
+@use "./desktop/index.scss" as pageFrameDesktop;
+@use "./mobile/index.scss" as pageFrameMobile;

package/src/page-frame/index.tsx

@@ -1,3 +1,5 @@
+import "./index.scss";
+
 import { DesktopFrame } from "./desktop";
 import { MobileFrame } from "./mobile";
 

package/src/page-frame/mobile/components/header/Header.tsx

@@ -2,7 +2,6 @@ import clsx from "clsx";
 import type { ReactNode } from "react";
 
 import IconBackward from "../../img/chevron-backward.svg";
-import "../../styles/header.scss";
 
 export interface MobileFrameHeaderProps {
   className?: string;

package/src/page-frame/mobile/components/header/index.ts

@@ -1,3 +1,5 @@
+// MobileFrameHeader direct barrel 소비에서도 header 스타일을 함께 로드한다.
+import "../../styles/header.scss";
 import { MobileFrameHeader } from "./Header";
 
 const Header = {

package/src/page-frame/mobile/index.tsx

@@ -1,5 +1,3 @@
-import "./index.scss";
-
 import { MobileFrame } from "./components/page/Frame";
 
 /**

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

@@ -0,0 +1,157 @@
+"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",
+              farmNameField?.className,
+            )}
+            width={farmNameField?.inputProps?.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={farmNameField?.inputProps?.block ?? true}
+              readOnly={
+                farmNameField?.mode === "readonly" ||
+                farmNameField?.inputProps?.readOnly === true
+              }
+              placeholder={farmNameField?.placeholder ?? "농장명 입력"}
+              {...farmNameField?.inputProps}
+              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",
+              contactField?.className,
+            )}
+            width={contactField?.inputProps?.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={contactField?.inputProps?.block ?? true}
+              readOnly={
+                contactField?.mode === "readonly" ||
+                contactField?.inputProps?.readOnly === true
+              }
+              placeholder={
+                contactField?.placeholder ?? "이메일 또는 전화번호 입력"
+              }
+              {...contactField?.inputProps}
+              register={form.register("contact")}
+            />
+          </Form.Field.Template>
+        ) : null}
+
+        {(visibleFields?.includes("text") ?? true) ? (
+          <Form.Field.Template
+            className={clsx(
+              "service-inquiry-field",
+              "service-inquiry-field-text",
+              textField?.className,
+            )}
+            width={textField?.inputProps?.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={textField?.inputProps?.block ?? true}
+              placeholder={
+                textField?.placeholder ?? "문의 내용을 자세히 입력해 주세요."
+              }
+              height={textField?.inputProps?.height ?? 160}
+              length={textField?.inputProps?.length ?? 10000}
+              {...textField?.inputProps}
+              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 { ServiceInquiryOpenButtonProps } from "../types";
+
+/**
+ * Service Inquiry Open Button; 문의 모달 trigger adapter
+ * @component
+ * @param {ServiceInquiryOpenButtonProps} 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,
+}: ServiceInquiryOpenButtonProps) => {
+  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,2 @@
+export * from "./useOpenServiceInquiry";
+export * from "./useServiceInquiryUserContext";