ValidationBadge

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

기본 사용법 (Basic Usage)#

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

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

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

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

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

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

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

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

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

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

Live Preview#

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

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

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

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

사용 시기 (When to Use)#

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

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

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

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

Props / Parameters#

스타일 시스템 (Style System)#

CoreValidationBadgeStyle 필드#

빠른 오버라이드 (Chain)#

이미 만든 ValidationBadge 인스턴스에 스타일을 빠르게 덧붙이고 싶다면 withStyle 체인을 쓸 수 있습니다. 생성자의 style 슬롯 인자와 동일하게 동작하지만, 이미 구성된 위젯 위에서 바로 이어 쓸 수 있습니다.

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

  @override
  Widget build(BuildContext context) {
    return const ValidationBadge(
      label: 'At least 8 characters',
      state: CoreValidationState.valid,
    ).withStyle(
      const CoreValidationBadgeStyle(
        validBackgroundColor: CoreColor.token(
          CoreColors.primary,
          opacity: CoreOpacity.opacity10,
        ),
        validBorderColor: CoreColor.token(CoreColors.primary),
        validLabelTextStyle: CoreTextStyle.token(
          CoreTextStyles.labelMedium,
          color: CoreColor.token(CoreColors.primary),
        ),
        borderWidth: CoreStrokeWidth.stroke2,
        iconStyle: CoreIconStyle(
          size: CoreIconSize.size16,
          color: CoreColor.token(CoreColors.primary),
        ),
        iconLabelGapStyle: CoreGapStyle(size: CoreSpace.space8),
      ),
    );
  }
}

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

  @override
  Component build(BuildContext context) {
    return const ValidationBadge(
      label: 'At least 8 characters',
      state: CoreValidationState.valid,
    ).withStyle(
      const CoreValidationBadgeStyle(
        validBackgroundColor: CoreColor.token(
          CoreColors.primary,
          opacity: CoreOpacity.opacity10,
        ),
        validBorderColor: CoreColor.token(CoreColors.primary),
        validLabelTextStyle: CoreTextStyle.token(
          CoreTextStyles.labelMedium,
          color: CoreColor.token(CoreColors.primary),
        ),
        borderWidth: CoreStrokeWidth.stroke2,
        iconStyle: CoreIconStyle(
          size: CoreIconSize.size16,
          color: CoreColor.token(CoreColors.primary),
        ),
        iconLabelGapStyle: CoreGapStyle(size: CoreSpace.space8),
      ),
    );
  }
}

변형 (Variants)#

Default (valid)#

가장 흔한 success 상태. success container 배경 + check 아이콘.

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

Pending#

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

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

Invalid#

실패 상태. error container 배경 + X 아이콘.

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

Medium size#

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

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

크기 (Sizes)#

높이는 고정이고 내용은 그 안에서 세로 가운데에 놓입니다. 테두리는 기본으로 그리지 않습니다(borderWidth 기본 0) — 채움 · 아이콘 · 글자로 상태를 말합니다.

동작 스펙 (Behavior)#

인터랙션#

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

상태 전환#

• pending → valid: 회색 배경 + clock 아이콘 → success container 배경 + check.
• valid → invalid: success container → error container 배경 + X.

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

개별 검증 규칙의 pending/valid/invalid 상태를 작은 배지로 표시하려면 ValidationBadge를 사용합니다. 메시지 한 줄은 ValidatorHint, 필드와 메시지의 상태 전파는 Validated, 검증 이외의 상태 라벨은 Badge를 선택합니다. 배지는 검증을 실행하지 않고 전달된 state를 표시합니다.

✅ Do#

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

❌ Don't#

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

✅ Do#

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

❌ Don't#

접근성 (Accessibility)#

역할#

• Flutter — Semantics(liveRegion: true). 역할 플래그는 세우지 않고 live region 만 걸며, 이름은 자식 Text(label) 에서 옵니다.
• Web — 루트 <span> 에 role="status"(암묵적 aria-live="polite"). 이 role 은 caller attributes 뒤에 병합되어 caller 가 바꿀 수 없고, 나머지 aria-* 는 그대로 통과합니다.

키보드#

없음. 표시 전용이라 포커스를 받지 않고 처리하는 키도 없습니다.

스크린 리더#

• 이름 — label 문자열입니다. Flutter 는 자식 Text(label), Web 은 라벨 <span> 의 텍스트 노드에서 옵니다.
• 통보 — 양 플랫폼 모두 live region 이라 state 가 바뀌어 다시 그려지면 읽힙니다 (Flutter liveRegion: true, Web role="status").
• 상태 아이콘에는 텍스트 대체가 없습니다. Flutter 의 Icon 은 semanticsLabel 없이 SvgPicture 를 그리고, Web 의 <iconify-icon> 에는 aria-label 도 aria-hidden 도 붙지 않습니다. 그래서 리더가 읽는 것은 규칙 문구뿐이고 통과 / 실패 / 대기라는 상태 자체는 이름에 들어가지 않습니다 — valid 와 invalid 가 같은 문장으로 읽힙니다.

포커스 관리#

없음. 오버레이가 아니고 포커스 가능 요소도 아니라 진입·이탈·트랩이 모두 해당되지 않습니다.

알려진 제약#

• 상태를 이름에 넣으려면 label 에 직접 씁니다 — ValidationBadge(label: '8자 이상 — 충족', state: .valid). Web 은 attributes: {'aria-label': ...} 로 루트 이름을 덮을 수도 있지만(caller attributes 는 role 을 빼고 그대로 통과), Flutter 에는 대응하는 진입점이 없어 label 이 유일한 경로입니다.
• live region 을 끄는 파라미터가 없습니다. 배지를 나열한 폼에서 조건들이 한 번에 갱신되면 배지 수만큼 통보됩니다 — 각 배지가 자기 루트에 live region 을 답니다. 대안: 한 화면에 두는 배지 수를 줄입니다(위 가이드라인의 5~6개 권장과 같은 이유입니다).

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

관련 컴포넌트 (Related Components)#

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

조합 예제#

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