API 참조

grunfeld.add()#

grunfeld.add() 메서드는 새로운 대화상자를 생성하는 핵심 API입니다. 두 가지 오버로드를 제공하여 다양한 사용 사례를 지원합니다.

알림 오버로드#

매개변수 없는 팩토리 함수를 사용하면 간단한 알림을 생성합니다:

grunfeld.add(() => React.ReactNode | GrunfeldProps): void

이 오버로드는 void를 반환하며, 즉시 실행됩니다. React 요소를 직접 반환하거나 GrunfeldProps 객체를 반환할 수 있습니다.

// Direct React element return
grunfeld.add(() => <div>Simple alert</div>);

// With options
grunfeld.add(() => ({
  element: <div>Positioned alert</div>,
  position: "top-right",
  lightDismiss: false,
}));

응답 오버로드#

removeWith 매개변수를 받는 팩토리 함수를 사용하면 사용자 응답을 받을 수 있습니다:

grunfeld.add<T>((removeWith: (data: T) => void) => GrunfeldProps): Promise<T | undefined>

이 오버로드는 Promise<T | undefined>를 반환합니다. 사용자가 removeWith(value)를 호출하면 Promise가 해당 값으로 resolve됩니다.

const result = await grunfeld.add<boolean>((removeWith) => ({
  element: (
    <div>
      <p>Are you sure?</p>
      <button onClick={() => removeWith(true)}>Yes</button>
      <button onClick={() => removeWith(false)}>No</button>
    </div>
  ),
}));

// Receive string input
const input = await grunfeld.add<string>((removeWith) => ({
  element: <InputForm onSubmit={removeWith} />,
}));

GrunfeldProps#

대화상자의 옵션을 지정하는 객체입니다:

interface GrunfeldProps {
  element: React.ReactNode;
  position?: Position;
  lightDismiss?: boolean;
  backdropStyle?: React.CSSProperties;
  dismissCallback?: () => unknown;
  renderMode?: "inline" | "top-layer";
}

element: 대화상자에 표시할 React 요소
position: 대화상자의 위치 (기본값: 'center')
lightDismiss: 배경 클릭으로 닫을지 여부 (기본값: true)
renderMode: 렌더링 모드 ('inline' | 'top-layer', 기본값: 'inline')
backdropStyle: 백드롭의 CSS 스타일
dismissCallback: 대화상자가 닫힐 때 실행되는 콜백

Promise 중단#

grunfeld.remove() 또는 grunfeld.clear()로 대화상자가 강제로 닫히면 Promise는 undefined로 resolve됩니다:

const promise = grunfeld.add<boolean>((removeWith) => ({
  element: (
    <div>
      <p>Are you sure?</p>
      <button onClick={() => removeWith(true)}>Yes</button>
      <button onClick={() => removeWith(false)}>No</button>
    </div>
  ),
}));

// Force remove dialog from elsewhere
setTimeout(() => {
  grunfeld.remove(); // promise resolves to undefined
}, 1000);

const result = await promise; // result is undefined
if (result === undefined) {
  console.log("Dialog was interrupted");
}

이를 활용하여 타임아웃이나 외부 이벤트로 인한 중단을 처리할 수 있습니다.

remove & clear#

Grunfeld는 대화상자를 제거하는 두 가지 메서드를 제공합니다.

grunfeld.remove()#

가장 최근에 추가된 대화상자를 제거합니다. 대화상자는 LIFO (Last In First Out) 순서로 제거됩니다:

// Remove most recent dialog
grunfeld.remove();

// Usage example
grunfeld.add(() => <div>First</div>);
grunfeld.add(() => <div>Second</div>);
grunfeld.add(() => <div>Third</div>);

grunfeld.remove(); // "Third" is removed
grunfeld.remove(); // "Second" is removed

이 메서드는 대화상자의 Promise를 undefined로 resolve합니다. 여러 대화상자가 스택되어 있는 경우, 가장 위의 대화상자만 제거됩니다.

grunfeld.clear()#

모든 대화상자를 한 번에 제거합니다:

// Remove all dialogs
grunfeld.clear();

// Usage example
grunfeld.add(() => <div>First</div>);
grunfeld.add(() => <div>Second</div>);
grunfeld.add(() => <div>Third</div>);

grunfeld.clear(); // All dialogs are removed

이 메서드는 모든 대화상자의 Promise를 undefined로 resolve합니다. 긴급 상황이나 라우트 변경 시 유용합니다.

ESC 키와 Light Dismiss#

사용자는 다음 방법으로도 대화상자를 닫을 수 있습니다:

ESC 키: 가장 최근 대화상자를 닫습니다 (grunfeld.remove()와 동일)
배경 클릭: lightDismiss: true인 경우 해당 대화상자를 닫습니다

이러한 사용자 액션도 Promise를 undefined로 resolve합니다.

TypeScript 타입#

Grunfeld는 완전한 TypeScript 지원을 제공합니다. 모든 타입은 패키지에서 import할 수 있습니다.

핵심 타입#

주요 타입 정의:

import type { 
  GrunfeldProps, 
  Position, 
  RenderMode 
} from "@ilokesto/grunfeld";

interface GrunfeldProps {
  element: React.ReactNode;
  position?: Position;
  lightDismiss?: boolean;
  backdropStyle?: React.CSSProperties;
  dismissCallback?: () => unknown;
  renderMode?: RenderMode;
}

type RenderMode = "inline" | "top-layer";

Position 타입#

대화상자의 위치를 지정하는 타입입니다. 화면을 9분할하여 정확한 위치를 지정할 수 있습니다:

type PositionX = "left" | "center" | "right";
type PositionY = "top" | "center" | "bottom";

type Position = `${PositionY}-${PositionX}` | "center";

// All available Position values:
// "top-left", "top-center", "top-right",
// "center-left", "center", "center-right",
// "bottom-left", "bottom-center", "bottom-right"

제네릭 타입 매개변수#

grunfeld.add<T>()의 제네릭 매개변수는 removeWith 함수의 인자 타입과 반환되는 Promise의 타입을 결정합니다:

// Return boolean
const result = await grunfeld.add<boolean>((removeWith) => ({
  element: <ConfirmDialog onConfirm={removeWith} />,
}));
// result type: boolean | undefined

// Return custom object
interface FormData {
  email: string;
  password: string;
}

const data = await grunfeld.add<FormData>((removeWith) => ({
  element: <LoginForm onSubmit={removeWith} />,
}));
// data type: FormData | undefined

타입 안정성을 위해 항상 명시적으로 제네릭 타입을 지정하는 것을 권장합니다.