ValidatorHint#

폼 입력 아래에 유효성 메시지(error / warning / info / success)를 선두 심각도 아이콘과 함께 표시합니다. visible 이 false 면 0 크기로 접히고, type 이 per-type 강조 색(아이콘·메시지 모두)과 기본 선두 아이콘을 결정합니다. Flutter / Web 1:1 동일 API 입니다.

Live Preview#

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

  @override
  Component build(BuildContext context) {
    return ValidatorHint(
      message: Text('비밀번호는 8자 이상이어야 합니다.'),
      type: CoreValidatorHintType.error,
    );
  }
}

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

  @override
  Widget build(BuildContext context) {
    return ValidatorHint(
      message: const Text('비밀번호는 8자 이상이어야 합니다.'),
      type: CoreValidatorHintType.error,
    );
  }
}

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

  @override
  Component build(BuildContext context) {
    return ValidatorHint(
      message: Text('비밀번호는 8자 이상이어야 합니다.'),
      type: CoreValidatorHintType.error,
    ).withStyle(
      const CoreValidatorHintStyle(
        accentColor: CoreColor.token(CoreColors.warning),
        messageTextStyle: CoreTextStyle.token(CoreTextStyles.bodySmall),
        iconStyle: CoreIconStyle(size: CoreIconSize.size16),
        iconLabelGapStyle: CoreGapStyle(size: CoreSpace.space12),
      ),
    );
  }
}

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

  @override
  Widget build(BuildContext context) {
    return ValidatorHint(
      message: const Text('비밀번호는 8자 이상이어야 합니다.'),
      type: CoreValidatorHintType.error,
    ).withStyle(
      const CoreValidatorHintStyle(
        accentColor: CoreColor.token(CoreColors.warning),
        messageTextStyle: CoreTextStyle.token(CoreTextStyles.bodySmall),
        iconStyle: CoreIconStyle(size: CoreIconSize.size16),
        iconLabelGapStyle: CoreGapStyle(size: CoreSpace.space12),
      ),
    );
  }
}

사용법#

ValidatorHint(
  message: const Text('비밀번호는 8자 이상이어야 합니다.'),
  type: CoreValidatorHintType.error,
)

빠른 오버라이드 (Chain)#

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

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

  @override
  Widget build(BuildContext context) {
    return ValidatorHint(
      message: const Text('비밀번호는 8자 이상이어야 합니다.'),
      type: CoreValidatorHintType.error,
    ).withStyle(
      const CoreValidatorHintStyle(
        accentColor: CoreColor.token(CoreColors.warning),
        messageTextStyle: CoreTextStyle.token(CoreTextStyles.bodySmall),
        iconStyle: CoreIconStyle(size: CoreIconSize.size16),
        iconLabelGapStyle: CoreGapStyle(size: CoreSpace.space12),
      ),
    );
  }
}

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

  @override
  Component build(BuildContext context) {
    return ValidatorHint(
      message: Text('비밀번호는 8자 이상이어야 합니다.'),
      type: CoreValidatorHintType.error,
    ).withStyle(
      const CoreValidatorHintStyle(
        accentColor: CoreColor.token(CoreColors.warning),
        messageTextStyle: CoreTextStyle.token(CoreTextStyles.bodySmall),
        iconStyle: CoreIconStyle(size: CoreIconSize.size16),
        iconLabelGapStyle: CoreGapStyle(size: CoreSpace.space12),
      ),
    );
  }
}

Props#

스타일 시스템 (Style System)#

CoreValidatorHintTypeStyle 필드#

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

✅ Do#

ValidatorHint.success(message: const Text('저장되었습니다.'))

❌ Don't#

// ❌ type 생략 → 기본값 error 로 렌더링됨
ValidatorHint(message: const Text('저장되었습니다.'))

접근성 (Accessibility)#

역할 / Semantics#

양 플랫폼 모두 별도의 역할을 내보내지 않습니다. Flutter 는 DefaultTextStyle.merge + Row 로만 그려지고 Semantics 래퍼가 없으며, Web 은 네이티브 <p> 하나로 렌더됩니다 — role 도 aria-live 도 붙지 않습니다. 리더 입장에서 이 힌트는 평범한 문단 텍스트이지 상태 메시지가 아닙니다.

심각도 아이콘은 양쪽 다 의도적으로 침묵시킵니다 — Flutter 는 ExcludeSemantics, Web 은 아이콘 <span> 의 aria-hidden="true".

키보드#

키 입력을 처리하지 않습니다. 표시 전용 컴포넌트라 활성화·이동 키가 없습니다.

포커스#

포커스를 받지 않습니다 — FocusNode(Flutter) 도 tabindex(Web) 도 없고 포커스 링도 그리지 않습니다. Tab 순서에 나타나지 않으므로 키보드 사용자는 주변 텍스트를 읽어 나가다 마주치게 됩니다.

visible: false 일 때의 처리는 플랫폼마다 다릅니다 — Flutter 는 SizedBox.shrink() 로 0 크기 노드를 트리에 남기고, Web 은 DOM 을 아예 만들지 않습니다.

스크린 리더#

읽히는 것은 호출자가 넘긴 message 텍스트 하나뿐입니다. 심각도 접두사도 역할 안내도 붙지 않습니다. type 은 강조 색과 아이콘 글리프로만 표현되고 그 아이콘은 숨겨져 있으므로, 리더에게 error 힌트와 success 힌트는 구분되지 않습니다.

알려진 제약#

• 심각도가 보조 기술에 전혀 전달되지 않습니다. 오류인지 성공인지 알려야 한다면 message 문구 자체에 담으세요 (예: '오류: 비밀번호는 8자 이상이어야 합니다.'). 심각도가 색으로만 남아 있다는 것은 전역 접근성 축의 색 강제 모드에서도 문제가 됩니다 — 시맨틱 색이 시스템 색으로 접히면 남는 단서가 없습니다.
• role="alert" / aria-live 가 없어 검증 후 새로 나타난 힌트가 자동으로 통보되지 않습니다. 사용자가 그 위치까지 이동해야 읽힙니다. 제출 실패처럼 즉시 알려야 하는 흐름이라면 호출자가 live region 을 직접 감싸야 합니다.
• 설명 대상 필드와 연결되어 있지 않습니다. aria-describedby 나 그에 준하는 연결이 없으므로, 입력에 포커스했을 때 이 힌트가 함께 읽히길 원한다면 호출자가 배선해야 합니다.