ValidationBadge#

폼 필드의 유효성 검증 결과를 아이콘과 텍스트로 시각적으로 표시하는 배지 컴포넌트입니다. 비밀번호 강도, 이메일 형식 등 검증 상태 안내에 적합합니다.

Live Preview#

class ValidationBadgeDefaultExample extends StatelessComponent {
  const ValidationBadgeDefaultExample({super.key});

  @override
  Component build(BuildContext context) {
    return const CoValidationBadge(
      label: 'At least 8 characters',
      state: CoreValidationState.valid,
    );
  }
}

class ValidationBadgeDefaultExample extends StatelessWidget {
  const ValidationBadgeDefaultExample({super.key});

  @override
  Widget build(BuildContext context) {
    return const CoValidationBadge(
      label: 'At least 8 characters',
      state: CoreValidationState.valid,
    );
  }
}

class ValidationBadgePendingExample extends StatelessComponent {
  const ValidationBadgePendingExample({super.key});

  @override
  Component build(BuildContext context) {
    return const CoValidationBadge(
      label: 'Awaiting input',
      state: CoreValidationState.pending,
    );
  }
}

class ValidationBadgePendingExample extends StatelessWidget {
  const ValidationBadgePendingExample({super.key});

  @override
  Widget build(BuildContext context) {
    return const CoValidationBadge(
      label: 'Awaiting input',
      state: CoreValidationState.pending,
    );
  }
}

class ValidationBadgeInvalidExample extends StatelessComponent {
  const ValidationBadgeInvalidExample({super.key});

  @override
  Component build(BuildContext context) {
    return const CoValidationBadge(
      label: 'Must contain a digit',
      state: CoreValidationState.invalid,
    );
  }
}

class ValidationBadgeInvalidExample extends StatelessWidget {
  const ValidationBadgeInvalidExample({super.key});

  @override
  Widget build(BuildContext context) {
    return const CoValidationBadge(
      label: 'Must contain a digit',
      state: CoreValidationState.invalid,
    );
  }
}

class ValidationBadgeMediumExample extends StatelessComponent {
  const ValidationBadgeMediumExample({super.key});

  @override
  Component build(BuildContext context) {
    return const CoValidationBadge(
      label: 'At least one uppercase letter',
      state: CoreValidationState.valid,
      size: CoreValidationBadgeSize.medium,
    );
  }
}

class ValidationBadgeMediumExample extends StatelessWidget {
  const ValidationBadgeMediumExample({super.key});

  @override
  Widget build(BuildContext context) {
    return const CoValidationBadge(
      label: 'At least one uppercase letter',
      state: CoreValidationState.valid,
      size: CoreValidationBadgeSize.medium,
    );
  }
}

사용 시기 (When to Use)#

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

• 비밀번호 설정 시 각 조건(길이, 대문자, 숫자 포함 등)의 충족 여부를 실시간으로 표시할 때
• 아이디, 이메일 중복 확인 결과를 시각적으로 안내할 때
• 폼 필드 아래에 여러 검증 규칙을 체크리스트 형태로 나열할 때
• 입력 진행 중 실시간 유효성 상태를 사용자에게 보여줄 때

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

• Status: 시스템이나 사용자 상태(온라인/오프라인)를 표시할 때
• Banner 또는 Toast: 전체 폼 제출 후 오류 메시지를 표시할 때
• Text: 단순한 에러 메시지 텍스트만 필요할 때

기본 사용법 (Basic Usage)#

// 유효한 상태 (기본)
CoValidationBadge(
  label: '8자 이상',
  state: CoreValidationState.valid,
)

// 무효한 상태
CoValidationBadge(
  label: '숫자 포함',
  state: CoreValidationState.invalid,
)

// 입력 전(pending) 상태
CoValidationBadge(
  label: '대문자 포함',
  state: CoreValidationState.pending,
)

// bool로 간편 생성 (true → valid, false → invalid)
CoValidationBadge.fromBool(
  label: '대문자 포함',
  isValid: hasUpperCase,
)

// hasInput → !hasInput 이면 pending, 그 외엔 isValid 기준
CoValidationBadge.withPending(
  label: '숫자 포함',
  hasInput: password.isNotEmpty,
  isValid: hasNumber,
)

// 유효한 상태 (기본)
CoValidationBadge(
  label: '8자 이상',
  state: CoreValidationState.valid,
)

// 무효한 상태
CoValidationBadge(
  label: '숫자 포함',
  state: CoreValidationState.invalid,
)

// 입력 전(pending) 상태
CoValidationBadge(
  label: '대문자 포함',
  state: CoreValidationState.pending,
)

// bool로 간편 생성
CoValidationBadge.fromBool(
  label: '대문자 포함',
  isValid: hasUpperCase,
)

// hasInput 기반 3-state factory
CoValidationBadge.withPending(
  label: '숫자 포함',
  hasInput: password.isNotEmpty,
  isValid: hasNumber,
)

Props / Parameters#

변형 (Variants)#

Default (valid)#

가장 흔한 success 상태. soft success tint + check 아이콘.

CoValidationBadge(
  label: '8자 이상',
  state: CoreValidationState.valid,
)

Pending#

입력 전 중립 상태. surface 배경 + 옅은 onSurface 텍스트 + dot 아이콘.

CoValidationBadge(
  label: '대문자 포함',
  state: CoreValidationState.pending,
)

Invalid#

실패 상태. soft error tint + X 아이콘.

CoValidationBadge(
  label: '숫자 포함',
  state: CoreValidationState.invalid,
)

Medium size#

typography 가 한 단계 크고 padding 도 더 넉넉한 변형.

CoValidationBadge(
  label: '대문자 포함',
  state: CoreValidationState.valid,
  size: CoreValidationBadgeSize.medium,
)

크기 (Sizes)#

동작 스펙 (Behavior)#

인터랙션#

• 표시 전용. 인터랙션 없음.
• state prop 변경 시 색상/아이콘 즉시 업데이트.

상태 전환#

• pending → valid: 회색 배경 + dot 아이콘 → 옅은 success tint + check.
• valid → invalid: success tint → error tint + X.

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

✅ Do#

Column(
  crossAxisAlignment: CrossAxisAlignment.start,
  children: [
    CoValidationBadge.withPending(
      label: '8자 이상',
      hasInput: password.isNotEmpty,
      isValid: password.length >= 8,
    ),
    CoValidationBadge.withPending(
      label: '대문자 포함',
      hasInput: password.isNotEmpty,
      isValid: hasUpperCase,
    ),
  ],
)

❌ Don't#

// ❌ 입력 전부터 모든 조건이 빨간 X
CoValidationBadge(label: '8자 이상', state: CoreValidationState.invalid)
CoValidationBadge(label: '대문자', state: CoreValidationState.invalid)

✅ Do#

CoValidationBadge.fromBool(label: '영문 대문자 포함', isValid: hasUpperCase)
CoValidationBadge.fromBool(label: '숫자 1개 이상', isValid: hasNumber)

❌ Don't#

접근성 (Accessibility)#

• Flutter: Semantics(label: '$label: ${state.name}') 적용 권장.
• Web: 컨테이너 role="status" 자동 적용 (필요 시 aria-live="polite" 추가).

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

관련 컴포넌트 (Related Components)#

• Input: ValidationBadge 와 함께 폼 필드 검증 UI 구성.
• Form: 전체 폼 수준의 검증 관리.
• Status: 시스템/사용자 상태 표시 (ValidationBadge 와 구분).

조합 예제#

// ValidationBadge + Input 조합으로 비밀번호 설정 UI
Column(
  crossAxisAlignment: CrossAxisAlignment.start,
  children: [
    CoInput(label: '새 비밀번호', obscureText: true, onChanged: handlePasswordChange),
    CoGap(size: CoreSpace.space12),
    CoValidationBadge.withPending(
      label: '8자 이상',
      hasInput: password.isNotEmpty,
      isValid: password.length >= 8,
    ),
    CoValidationBadge.withPending(
      label: '영문 대문자 1자 이상',
      hasInput: password.isNotEmpty,
      isValid: hasUpperCase,
    ),
    CoValidationBadge.withPending(
      label: '숫자 1자 이상',
      hasInput: password.isNotEmpty,
      isValid: hasNumber,
    ),
  ],
)