Alert#

다양한 상태(정보, 성공, 경고, 오류)를 시각적으로 구분하여 메시지를 표시하는 알림 영역 컴포넌트입니다. Flutter와 Web이 동일한 named properties API(title, description, variant, onDismiss, action)를 사용합니다.

Live Preview#

class AlertDefaultExample extends StatefulComponent {
  const AlertDefaultExample({super.key});

  @override
  State<AlertDefaultExample> createState() => _AlertDefaultExampleState();
}

class _AlertDefaultExampleState extends State<AlertDefaultExample> {
  bool _show = true;

  @override
  Component build(BuildContext context) {
    if (_show) {
      return Alert(
        title: 'Heads up!',
        description: 'You can add components to your app using the cli.',
        onDismiss: () => setState(() => _show = false),
      );
    }
    return Button(
      variant: CoreButtonVariant.outline,
      onPressed: () => setState(() => _show = true),
      child: const Text('Show alert'),
    );
  }
}

class AlertDefaultExample extends StatefulWidget {
  const AlertDefaultExample({super.key});

  @override
  State<AlertDefaultExample> createState() => _AlertDefaultExampleState();
}

class _AlertDefaultExampleState extends State<AlertDefaultExample> {
  bool _show = true;

  @override
  Widget build(BuildContext context) {
    if (_show) {
      return Alert(
        title: 'Heads up!',
        description: 'You can add components to your app using the cli.',
        onDismiss: () => setState(() => _show = false),
      );
    }
    return Button(
      variant: CoreButtonVariant.outline,
      onPressed: () => setState(() => _show = true),
      child: const Text('Show alert'),
    );
  }
}

class AlertInfoExample extends StatefulComponent {
  const AlertInfoExample({super.key});

  @override
  State<AlertInfoExample> createState() => _AlertInfoExampleState();
}

class _AlertInfoExampleState extends State<AlertInfoExample> {
  bool _show = true;

  @override
  Component build(BuildContext context) {
    if (_show) {
      return Alert.info(
        title: '정보',
        description: '새로운 업데이트가 있습니다.',
        onDismiss: () => setState(() => _show = false),
      );
    }
    return Button(
      variant: CoreButtonVariant.outline,
      onPressed: () => setState(() => _show = true),
      child: const Text('Show alert'),
    );
  }
}

class AlertInfoExample extends StatefulWidget {
  const AlertInfoExample({super.key});

  @override
  State<AlertInfoExample> createState() => _AlertInfoExampleState();
}

class _AlertInfoExampleState extends State<AlertInfoExample> {
  bool _show = true;

  @override
  Widget build(BuildContext context) {
    if (_show) {
      return Alert.info(
        title: '정보',
        description: '새로운 업데이트가 있습니다.',
        onDismiss: () => setState(() => _show = false),
      );
    }
    return Button(
      variant: CoreButtonVariant.outline,
      onPressed: () => setState(() => _show = true),
      child: const Text('Show alert'),
    );
  }
}

class AlertSuccessExample extends StatefulComponent {
  const AlertSuccessExample({super.key});

  @override
  State<AlertSuccessExample> createState() => _AlertSuccessExampleState();
}

class _AlertSuccessExampleState extends State<AlertSuccessExample> {
  bool _show = true;

  @override
  Component build(BuildContext context) {
    if (_show) {
      return Alert.success(
        title: '저장 완료',
        description: '변경 사항이 성공적으로 저장되었습니다.',
        onDismiss: () => setState(() => _show = false),
      );
    }
    return Button(
      variant: CoreButtonVariant.outline,
      onPressed: () => setState(() => _show = true),
      child: const Text('Show alert'),
    );
  }
}

class AlertSuccessExample extends StatefulWidget {
  const AlertSuccessExample({super.key});

  @override
  State<AlertSuccessExample> createState() => _AlertSuccessExampleState();
}

class _AlertSuccessExampleState extends State<AlertSuccessExample> {
  bool _show = true;

  @override
  Widget build(BuildContext context) {
    if (_show) {
      return Alert.success(
        title: '저장 완료',
        description: '변경 사항이 성공적으로 저장되었습니다.',
        onDismiss: () => setState(() => _show = false),
      );
    }
    return Button(
      variant: CoreButtonVariant.outline,
      onPressed: () => setState(() => _show = true),
      child: const Text('Show alert'),
    );
  }
}

class AlertWarningExample extends StatefulComponent {
  const AlertWarningExample({super.key});

  @override
  State<AlertWarningExample> createState() => _AlertWarningExampleState();
}

class _AlertWarningExampleState extends State<AlertWarningExample> {
  bool _show = true;

  @override
  Component build(BuildContext context) {
    if (_show) {
      return Alert.warning(
        title: '주의',
        description: '이 작업은 되돌릴 수 없습니다.',
        onDismiss: () => setState(() => _show = false),
      );
    }
    return Button(
      variant: CoreButtonVariant.outline,
      onPressed: () => setState(() => _show = true),
      child: const Text('Show alert'),
    );
  }
}

class AlertWarningExample extends StatefulWidget {
  const AlertWarningExample({super.key});

  @override
  State<AlertWarningExample> createState() => _AlertWarningExampleState();
}

class _AlertWarningExampleState extends State<AlertWarningExample> {
  bool _show = true;

  @override
  Widget build(BuildContext context) {
    if (_show) {
      return Alert.warning(
        title: '주의',
        description: '이 작업은 되돌릴 수 없습니다.',
        onDismiss: () => setState(() => _show = false),
      );
    }
    return Button(
      variant: CoreButtonVariant.outline,
      onPressed: () => setState(() => _show = true),
      child: const Text('Show alert'),
    );
  }
}

class AlertDestructiveExample extends StatefulComponent {
  const AlertDestructiveExample({super.key});

  @override
  State<AlertDestructiveExample> createState() =>
      _AlertDestructiveExampleState();
}

class _AlertDestructiveExampleState extends State<AlertDestructiveExample> {
  bool _show = true;

  @override
  Component build(BuildContext context) {
    if (_show) {
      return Alert.destructive(
        title: '오류 발생',
        description: '요청을 처리하는 중 문제가 발생했습니다.',
        onDismiss: () => setState(() => _show = false),
      );
    }
    return Button(
      variant: CoreButtonVariant.outline,
      onPressed: () => setState(() => _show = true),
      child: const Text('Show alert'),
    );
  }
}

class AlertDestructiveExample extends StatefulWidget {
  const AlertDestructiveExample({super.key});

  @override
  State<AlertDestructiveExample> createState() =>
      _AlertDestructiveExampleState();
}

class _AlertDestructiveExampleState extends State<AlertDestructiveExample> {
  bool _show = true;

  @override
  Widget build(BuildContext context) {
    if (_show) {
      return Alert.destructive(
        title: '오류 발생',
        description: '요청을 처리하는 중 문제가 발생했습니다.',
        onDismiss: () => setState(() => _show = false),
      );
    }
    return Button(
      variant: CoreButtonVariant.outline,
      onPressed: () => setState(() => _show = true),
      child: const Text('Show alert'),
    );
  }
}

사용 시기 (When to Use)#

이 컴포넌트를 사용하세요:

• 페이지 내 고정된 위치에서 중요한 상태 메시지를 안내할 때
• 폼 제출 결과(성공/오류)를 인라인으로 표시할 때
• 사용자가 반드시 인지해야 하는 경고나 안내를 표시할 때

대신 다른 컴포넌트를 사용하세요:

• Toast: 일시적으로 나타났다 사라지는 짧은 알림에는 Toast 사용
• Banner: 페이지 최상단 전체 폭으로 중요 공지를 표시할 때 사용
• Dialog: 사용자의 확인 액션이 필요한 경고성 메시지에는 Dialog 사용

기본 사용법 (Basic Usage)#

// 기본 알림
Alert(
  title: 'Heads up!',
  description: 'You can add components to your app using the cli.',
)

// 정보 알림 (variant named constructor)
Alert.info(
  title: '안내',
  description: '새로운 업데이트가 있습니다.',
)

// 성공 알림 (닫기 버튼 포함)
Alert.success(
  title: '저장 완료',
  description: '변경 사항이 성공적으로 저장되었습니다.',
  onDismiss: handleDismiss,
)

// 오류 알림
Alert.destructive(
  title: '오류 발생',
  description: '요청을 처리하는 중 문제가 발생했습니다.',
)

// 기본 알림
Alert(
  title: 'Heads up!',
  description: 'You can add components to your app using the cli.',
)

// 정보 알림
Alert.info(
  title: '안내',
  description: '새로운 업데이트가 있습니다.',
)

// 성공 알림 (닫기 버튼 포함)
Alert.success(
  title: '저장 완료',
  description: '변경 사항이 성공적으로 저장되었습니다.',
  onDismiss: handleDismiss,
)

// 오류 알림
Alert.destructive(
  title: '오류 발생',
  description: '요청을 처리하는 중 문제가 발생했습니다.',
)

Props / Parameters#

스타일 시스템 (Style System)#

Alert 의 모든 chrome / dimensional / nested-slot 오버라이드는 CoreAlertStyle<Clr> 단일 슬롯으로 흐릅니다 (Epic #1302 원칙 6/7/8). 시맨틱 enum (variant) 과 behaviour (title / description / action / onDismiss) 는 위젯 파라미터로 직접 전달합니다.

시맨틱 vs 스타일#

• 시맨틱 enum / behaviour: 위젯/컴포넌트 파라미터로 직접 (variant, title, description, action, onDismiss)
• chrome / dimensional / 슬롯 스타일: CoreAlertStyle 한 곳으로 (backgroundColor / foregroundColor / borderColor / borderWidth / borderRadius / padding / gap / titleStyle / descriptionStyle / iconStyle / actionButtonStyle / closeButtonStyle)

Resolve chain#

design system default for alert
  → CoreAlertTheme.style                   // 프로젝트 공통
  → parent component slot override
  → widget.alertStyle                      // 인스턴스별

각 nested 슬롯 스타일 (titleStyle / descriptionStyle / iconStyle / actionButtonStyle / closeButtonStyle) 은 자기 컴포넌트의 자체 resolve chain 으로 다시 한 번 머지됩니다.

슬롯 매핑 (CoreAlertStyle 13 필드)#

Migration — 옛 평면 chrome → 새 위치 매핑#

기존 CoreAlertTheme 의 평면 chrome (backgroundColor / borderColor / borderRadius) 은 호환을 위해 유지되지만, 새 코드는 alertStyle 슬롯을 사용하세요:

사용 예 (Flutter)#

Alert.success(
  title: '저장 완료',
  description: '변경 사항이 성공적으로 저장되었습니다.',
  alertStyle: CoreAlertStyle(
    padding: CoreEdgeInsets.symmetric(horizontal: 24, vertical: 16),
    borderRadius: CoreBorderRadius.all(12),
    titleStyle: CoreTextStyle(fontSize: 14, fontWeight: 600),
    descriptionStyle: CoreTextStyle(fontSize: 12),
    iconStyle: CoreIconStyle(size: 20),
  ),
  onDismiss: handleDismiss,
)

사용 예 (Web)#

Alert.success(
  title: '저장 완료',
  description: '변경 사항이 성공적으로 저장되었습니다.',
  alertStyle: CoreAlertStyle(
    padding: CoreEdgeInsets.symmetric(horizontal: 24, vertical: 16),
    borderRadius: CoreBorderRadius.all(12),
  ),
  onDismiss: handleDismiss,
)

Named constructors#

• Alert.info(...), Alert.success(...), Alert.warning(...), Alert.destructive(...) — 각 variant에 대한 편의 생성자.

변형 (Variants)#

Default#

Alert(
  title: 'Heads up!',
  description: '표준 surface 색상을 사용하는 기본 알림입니다.',
)

Info#

Alert.info(
  title: '정보',
  description: '시스템 점검이 예정되어 있습니다.',
)

Success#

Alert.success(
  title: '완료',
  description: '파일이 성공적으로 업로드되었습니다.',
  onDismiss: handleDismiss,
)

Warning#

Alert.warning(
  title: '주의',
  description: '이 작업은 되돌릴 수 없습니다.',
)

Destructive (Error)#

Alert.destructive(
  title: '오류',
  description: '네트워크 연결을 확인해 주세요.',
)

동작 스펙 (Behavior)#

인터랙션#

• 닫기: onDismiss가 제공되면 우측에 닫기 버튼 표시, 클릭 시 콜백 실행. 실제 숨김 처리는 부모 위젯이 담당.
• 액션: action은 닫기 버튼 왼쪽에 표시. 버튼 등 임의 위젯을 전달할 수 있습니다.
• 아이콘: variant별 아이콘(info/success/warning/destructive)이 자동 표시됩니다.

토큰#

• Border radius: CoreRadius.box (16px)
• Border width: CoreBorderWidth.thin (1px)
• Padding: CoreSpace.space12 세로 × CoreSpace.space16 가로
• Icon size: CoreSpace.space16 (16px)
• Icon gap: CoreSpace.space12 (12px)

사용 가이드라인 (Usage Guidelines)#

✅ Do#

Alert.warning(
  title: '주의',
  description: '이 작업은 되돌릴 수 없습니다.',
)

❌ Don't#

// ❌ 일반 안내에 destructive 사용
Alert.destructive(
  description: '새 버전이 출시되었습니다.',
)

✅ Do#

Alert.success(
  title: '저장 완료',
  description: '변경 사항이 저장되었습니다.',
  onDismiss: handleDismiss,
)

❌ Don't#

// ❌ 너무 긴 description
Alert.warning(
  description: '시스템 점검으로 인해 2024년 3월 15일 오전 2시부터 4시까지 서비스가 일시 중단됩니다. 이용에 불편을 드려 죄송합니다.',
)

접근성 (Accessibility)#

스크린 리더#

• Flutter: Semantics(container: true, label: title ?? 'Alert') 자동 적용.
• Web: role="alert" 속성이 루트에 자동 부여됩니다.

키보드 인터랙션#

크로스 플랫폼 차이점 (Platform Differences)#

v3.0부터 title, description, variant, onDismiss, action API가 통일되었습니다. 아래는 플랫폼 고유 차이점만 나열합니다.

관련 컴포넌트 (Related Components)#

• Banner: 페이지 최상단 전체 폭 공지에 사용
• Toast: 자동으로 사라지는 일시적 알림에 사용
• Dialog: 사용자 확인이 필요한 경고 메시지에 사용

조합 예제#

// 폼 제출 후 결과 표시
Column(
  children: [
    if (submitError != null)
      Alert.destructive(
        title: '오류',
        description: submitError!,
        onDismiss: handleErrorDismissed,
      ),
    // ... form fields
  ],
)