naeileun_pin_input 0.0.1

6자리 PIN(간편 비밀번호) 입력용 모달 바텀시트 위젯. 입력 완료 후 외부 검증 → controller로 success/error/close 제어.

naeileun_pin_input

naeileun_pin_input은 6자리 PIN(간편 비밀번호) 입력용 모달 바텀시트 위젯을 제공하는 Flutter 패키지입니다.
입력이 완료되면 즉시 콜백으로 코드를 전달하고, 외부에서 컨트롤러로 성공/실패/닫기 타이밍을 제어할 수 있습니다.

주요 기능

• 6자리 PIN 입력 바텀시트(SimpleVerificationBottomSheet)
• 컨트롤러 기반 제어(PinInputController)
  • text로 입력 완료 코드 확인 (TextEditingController처럼)
  • success() / error(...) / close() / clear() 제공
• 입력 완료 즉시 콜백: onInputComplete(code) → 외부에서 유효성 검증 후 처리
• 실패 UX
  • error() 호출 시 도트(dot)만 빨간색으로 변경
  • 흔들림(shake) 애니메이션
  • 에러 텍스트 표시(사라지지 않고 유지, 다음 입력/삭제 또는 success 시 해제)
• UI 스타일 완전 커스터마이징
  • 타이틀/설명/숫자/버튼/재배열/스킵/에러텍스트/도트 스타일 주입 가능
• 추가 의존성 없음
  • flutter_screenutil 미사용

시작하기

/example 폴더를 실행하면 모든 동작을 바로 확인할 수 있습니다.

cd example
flutter pub get
flutter run

사용 예시

1) 기본 플로우 (입력 완료 → 외부 검증 → error/success → close)

동작 흐름은 아래처럼 생각하면 됩니다.

• 사용자가 6자리 입력 완료
• 위젯이 즉시 onInputComplete(code) 호출 (이 시점에 시트는 닫히지 않음)
• 외부에서 code 유효성 검증
• 검증 결과에 따라 컨트롤러로:
  • 실패: controller.error(...) (도트만 빨강 + 흔들림 + 에러 텍스트)
  • 성공: controller.success()
• 시트를 닫고 싶은 타이밍에: controller.close()

final controller = PinInputController();

SimpleVerificationBottomSheet.show(
  context: context,
  controller: controller,
  title: '간편 비밀번호를 입력해 주세요',
  description: '6자리 숫자를 입력해주세요.',
  errorText: '비밀번호가 올바르지 않습니다.',
  onInputComplete: (code) async {
    final ok = await validatePin(code); // 외부 유효성 검증
    if (ok) {
      controller.success();
      controller.close(); // 원하는 타이밍에 닫기
    } else {
      controller.error(message: 'PIN이 틀렸어요', clearOnError: true);
    }
  },
);

2) PinInputController 사용법

PinInputController는 “값 보관 + 이벤트(효과/닫기) 트리거” 역할입니다.

• 입력 완료 코드 읽기: controller.text
• 값 초기화: controller.clear()
• 변화 감지: controller.addListener(() { ... })
• 수명주기: 화면에서 더 이상 안 쓰면 controller.dispose() 권장

final controller = PinInputController();

@override
void initState() {
  super.initState();
  controller.addListener(() {
    // 6자리 입력이 완료되면 controller.text가 채워집니다.
    debugPrint('PIN: ${controller.text}');
  });
}

@override
void dispose() {
  controller.dispose();
  super.dispose();
}

3) 실패(에러) 동작 규칙 (중요)

controller.error(...)를 호출하면:

• 도트(dot)만 빨간색으로 표시됩니다.
• 흔들림(shake) 애니메이션이 실행됩니다.
• 에러 텍스트는 아래 우선순위로 표시됩니다.
  • controller.error(message: ...)의 message
  • 없으면 SimpleVerificationBottomSheet.errorText

그리고 에러 텍스트는 자동으로 사라지지 않습니다.

• 다음 입력(숫자 입력) 또는 삭제를 누르면 에러 텍스트가 해제됩니다.
• controller.success() 호출 시에도 해제됩니다.
• revertAfter는 “도트 빨간 표시를 원복하는 시간”으로 동작합니다. (텍스트는 유지)

4) 스타일 커스터마이징 목록

아래 파라미터로 UI를 전부 직접 제어할 수 있습니다.

• 텍스트 스타일
  • titleStyle
  • descriptionStyle
  • numberTextStyle (숫자 버튼)
  • buttonTextStyle (하단 좌, 우측 공통 버튼 텍스트)
  • shuffleTextStyle (재배열 텍스트)
  • skipTextStyle (건너뛰기)
  • errorTextStyle
• 도트 스타일
  • dotStyle: PinDotStyle(...)
    • filledColor / emptyColor
    • errorFilledColor / errorEmptyColor
    • size / spacing / shape

실제 적용 예시는 /example 코드에 모두 포함되어 있습니다.