sellmate-design-system-react 0.11.0 → 0.12.0

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

@@ -0,0 +1,102 @@
+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.
+ * (컴포넌트 문서 생성기 docs:gen 은 `*Props` interface 를 "컴포넌트"로 취급하므로,
+ *  서비스인 SModal 이 컴포넌트로 잘못 문서화되지 않도록 type 별칭으로 둔다. README 는 수작성.)
+ */
+export type SModalCreateComponentProps = {
+    /** 모달 제어 핸들. 컴포넌트에서 ok()/cancel()/close()/submit()/onSubmit() 호출 */
+    modalRef: SModalRef;
+};
+/** SModal.create 옵션 — 커스텀 React 컴포넌트를 SModalContainer(딤+카드) 안에 렌더 */
+export interface SCreateOptions<P extends object = Record<string, never>> {
+    /** 모달 본문으로 렌더할 컴포넌트. modalRef 가 prop 으로 주입된다. */
+    component: ComponentType<P & SModalCreateComponentProps>;
+    /** component 에 전달할 추가 props (modalRef 제외) */
+    componentProps?: P;
+    /** 백드롭·ESC 로 안 닫히고 흔들림 */
+    persistent?: boolean;
+    /** 우측 상단 닫기(X) 버튼 (기본 false) */
+    showClose?: boolean;
+    width?: number | string;
+    height?: number | string;
+    className?: string;
+    /** 접근성 제목 (스크린리더용) */
+    ariaTitle?: string;
+}
+/**
+ * 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
+ * // 커스텀 컴포넌트 모달 — 컴포넌트가 modalRef 로 자기 모달 제어
+ * SModal.create({ component: OrderFormModal, componentProps: { orderId }, persistent: true })
+ *   .onSubmit(async () => { await save(); ref.ok(); })
+ *   .onDismissed(() => {});
+ */
+export declare const SModal: {
+    /** 확인/취소 모달을 즉시 띄운다. 반환 핸들에 onOk/onCancel/onClose/onDismissed 체이닝. */
+    confirm(options: SConfirmOptions): SModalRef;
+    /**
+     * 로딩(스피너/에러) 모달을 즉시 띄운다. 로딩 중 임의 닫힘 방지를 위해 persistent 기본 true.
+     * 버튼 클릭은 자동 닫힘 없이 onClick 만 발화 — update()/close() 로 후속 동작을 결정한다.
+     */
+    loading(options?: SLoadingOptions): SModalRef;
+    /**
+     * 커스텀 React 컴포넌트를 SModalContainer(딤+카드) 안에 띄운다. component 에 modalRef 가
+     * prop 으로 주입되어 컴포넌트가 ok()/cancel()/close()/submit()/onSubmit() 으로 자기 모달을 제어한다.
+     */
+    create<P extends object = Record<string, never>>(options: SCreateOptions<P>): SModalRef;
+};