sellmate-design-system-react 0.11.0 → 1.0.0

package/dist/components/SModal/SModal.d.ts

@@ -0,0 +1,121 @@
+import { type ComponentType } from 'react';
+import { type SConfirmModalProps } from '../SConfirmModal';
+import { type SLoadingModalProps } from '../SLoadingModal';
+/** SModal.confirm 옵션 — 제어 흐름을 서비스가 담당하므로 관련 props 는 제외 */
+export type SConfirmOptions = Omit<SConfirmModalProps, 'open' | 'onOpenChange' | 'onOk' | 'onCancel' | 'onClose'>;
+/** SModal.loading 옵션 — 제어 흐름을 서비스가 담당하므로 관련 props 는 제외 */
+export type SLoadingOptions = Omit<SLoadingModalProps, 'open' | 'onOpenChange' | 'onClose' | 'onButtonClick'>;
+/**
+ * create() 가 컴포넌트에 주입하는 prop.
+ *
+ * 컴포넌트는 `open`/`onOpenChange`/`onClose` 를 루트의 SActionModal 에 **그대로 전달**해야 한다.
+ * 전달하지 않으면 모달이 열리지도, 닫히지도 않는다.
+ *
+ * (컴포넌트 문서 생성기 docs:gen 은 `*Props` interface 를 "컴포넌트"로 취급하므로,
+ *  서비스인 SModal 이 컴포넌트로 잘못 문서화되지 않도록 type 별칭으로 둔다. README 는 수작성.)
+ */
+export type SModalCreateComponentProps = {
+    /** 표시 여부 — SActionModal 의 open 에 그대로 전달 */
+    open: boolean;
+    /** 표시 상태 변경 — SActionModal 의 onOpenChange 에 그대로 전달 */
+    onOpenChange: (open: boolean) => void;
+    /** 닫기(X) 클릭 — SActionModal 의 onClose 에 그대로 전달 */
+    onClose: () => void;
+    /** 모달 제어 핸들. 컴포넌트에서 ok()/cancel()/close()/submit()/onSubmit() 호출 */
+    modalRef: SModalRef;
+};
+/**
+ * SModal.create 옵션 — SActionModal 을 루트로 렌더하는 컴포넌트를 띄운다.
+ *
+ * 디자인 시스템이 띄우는 모달은 SActionModal / SConfirmModal / SLoadingModal 세 가지뿐이고,
+ * 서비스 메서드가 1:1 로 대응한다 — create → SActionModal, confirm → SConfirmModal,
+ * loading → SLoadingModal. create 는 컨테이너를 덧씌우지 않고 component 를 그대로 렌더하며,
+ * 표시 제어(open/onOpenChange/onClose/modalRef)만 주입하고 닫힘 후 정리를 담당한다.
+ */
+export interface SCreateOptions<P extends object = Record<string, never>> {
+    /**
+     * 띄울 컴포넌트. **루트에 SActionModal 을 렌더**하고 주입받은 open/onOpenChange/onClose 를
+     * 그대로 전달해야 한다. 모달 껍데기 없이 본문만 렌더하면 딤·카드 없이 콘텐츠가 그대로
+     * 화면에 붙는다 — 개발 모드에서는 이를 감지해 경고한다.
+     */
+    component: ComponentType<P & SModalCreateComponentProps>;
+    /** component 에 전달할 추가 props (주입 prop 과 이름이 겹치면 주입 쪽이 이긴다) */
+    componentProps?: P;
+}
+/**
+ * SModal.confirm / loading / create 반환 핸들 — 체이닝 콜백 등록 + 트리거/update/close.
+ * 원본 sdModal 의 ModalDialogRef 와 동일하게 단일 타입이며, 모달 종류에 따라 관련 있는
+ * 메서드만 실제 발화한다(예: onOk/onCancel 은 confirm, onClick 은 loading, onSubmit 은 create).
+ */
+export interface SModalRef {
+    /** 확인 버튼 클릭 (confirm) 또는 ok() 트리거 */
+    onOk(fn: () => void): SModalRef;
+    /** 취소(서브) 버튼 클릭 (confirm) 또는 cancel() 트리거 */
+    onCancel(fn: () => void): SModalRef;
+    /** 닫기(X) 버튼 클릭 또는 close() 트리거 */
+    onClose(fn: () => void): SModalRef;
+    /**
+     * 단일 버튼 모달(loading error 등)의 버튼 클릭. 자동 닫힘이 없으므로
+     * consumer 가 update()/close() 로 후속 동작을 결정한다. (원본 sdModal onClick)
+     */
+    onClick(fn: () => void): SModalRef;
+    /**
+     * create 커스텀 모달의 제출(submit). 자동 닫힘 없이 fn 만 호출하므로 API 응답을
+     * 받은 뒤 ok()/close()/update() 로 후속 동작을 결정한다. (원본 sdModal onSubmit)
+     */
+    onSubmit(fn: () => void): SModalRef;
+    /** 사유와 무관하게 모달이 완전히 닫혀 언마운트된 뒤 (백드롭·ESC 닫힘 포함) */
+    onDismissed(fn: () => void): SModalRef;
+    /** 표시 중 옵션 갱신 (loading→error, progress, 메시지 등). create 는 미지원. */
+    update(patch: Partial<SConfirmOptions & SLoadingOptions>): SModalRef;
+    /** onOk 트리거 + 닫기 (저장/처리 성공 시맨틱) */
+    ok(): SModalRef;
+    /** onCancel 트리거 + 닫기 (작업 취소 시맨틱) */
+    cancel(): SModalRef;
+    /** onClose 트리거 + 닫기 (중립적 닫기, persistent 여부와 무관) */
+    close(): SModalRef;
+    /** onSubmit 트리거 (닫힘 없음) — create 커스텀 컴포넌트가 제출 버튼에서 호출 */
+    submit(): SModalRef;
+}
+/**
+ * SModal — 명령형 모달 서비스.
+ *
+ * @example
+ * // 확인/취소
+ * SModal.confirm({ type: 'negative', modalTitle: '삭제하시겠습니까?', mainButtonLabel: '삭제', subButtonLabel: '취소' })
+ *   .onOk(() => deleteItem())
+ *   .onCancel(() => {});
+ *
+ * @example
+ * // 로딩 → 완료 or 에러
+ * const ref = SModal.loading({ message: '업로드 중...' });
+ * try { await upload(); ref.close(); }
+ * catch { ref.update({ state: 'error', message: '업로드 실패' }).onClick(() => retry()); }
+ *
+ * @example
+ * // SActionModal 을 루트로 렌더하는 컴포넌트를 만들어 넘긴다 — 주입 prop 은 그대로 전달
+ * function OrderModal({ open, onOpenChange, onClose, modalRef, orderId }: OrderModalProps) {
+ *   return (
+ *     <SActionModal open={open} onOpenChange={onOpenChange} onClose={onClose}
+ *       modalTitle="주문 처리" button={{ label: '처리', onClick: () => modalRef.ok() }}>
+ *       <OrderBody orderId={orderId} />
+ *     </SActionModal>
+ *   );
+ * }
+ * SModal.create({ component: OrderModal, componentProps: { orderId } }).onOk(() => refetch());
+ */
+export declare const SModal: {
+    /** 확인/취소 모달을 즉시 띄운다. 반환 핸들에 onOk/onCancel/onClose/onDismissed 체이닝. */
+    confirm(options: SConfirmOptions): SModalRef;
+    /**
+     * 로딩(스피너/에러) 모달을 즉시 띄운다. 로딩 중 임의 닫힘 방지를 위해 persistent 기본 true.
+     * 버튼 클릭은 자동 닫힘 없이 onClick 만 발화 — update()/close() 로 후속 동작을 결정한다.
+     */
+    loading(options?: SLoadingOptions): SModalRef;
+    /**
+     * SActionModal 을 루트로 렌더하는 컴포넌트를 띄운다. 컨테이너를 덧씌우지 않고 표시 제어
+     * (open/onOpenChange/onClose)와 modalRef 만 주입하며, 닫힘 애니메이션 종료 후 자동으로
+     * 언마운트한다. 컴포넌트가 모달을 띄우지 않으면 개발 모드에서 경고한다.
+     */
+    create<P extends object = Record<string, never>>(options: SCreateOptions<P>): SModalRef;
+};