flutter_ui_kit_widget 0.0.18

Reusable UI widget components for the flutter_ui_kit ecosystem.

flutter_ui_kit_widget

flutter_ui_kit 에코시스템에서 공통으로 재활용하는 UI 위젯 컴포넌트 모음.

내부 구현은 shadcn_ui(ShadIconButton, ShadTooltip, ShadTheme) 기반으로 작성되며, glassmorphism 표면처럼 shadcn에 1:1 대응이 없는 영역만 Flutter primitive(BackdropFilter, LinearGradient, Border)를 보조적으로 사용한다.

---

사전 요구사항

본 패키지의 토글 컴포넌트는 내부에서 ShadIconButton을 사용하며, ShadIconButton은 빌드 시 상위 트리에 ShadTheme ancestor가 있는지 어서션으로 검사한다. 따라서 두 가지 사용 패턴이 가능하다.

권장: 앱 루트에 ShadApp 사용

import 'package:shadcn_ui/shadcn_ui.dart';

void main() {
  runApp(const ShadApp(home: MyHomePage()));
}

폴백: Material 앱에서 그대로 사용

ShadApp을 적용하지 않은 Material 기반 앱에서도 본 패키지 위젯은 정상 동작한다. 각 위젯이 내부적으로 UiKitShadGuard를 통해 ShadTheme ancestor가 없을 때 Material Brightness에 맞춘 기본 ShadThemeData를 자동 주입한다.

void main() {
  runApp(MaterialApp(home: MyHomePage())); // ShadApp 없이도 OK
}

색상은 모든 컴포넌트에서 ShadTheme.of(context)(존재 시)와 Material Theme(폴백)을 자동으로 조합해 해결한다.

---

컴포넌트

Toggle 계열 — DsIconToggle, DsTextToggle, DsToggleButton

아이콘 또는 짧은 텍스트를 표시하고, 탭하면 상태를 전환하는 범용 토글 버튼.

• 내부 구현: ShadIconButton (ghost variant) + ShadTooltip 합성
• 외곽: stadium-pill 형태 (sizedBoxDimension의 절반을 corner radius로 적용)
• child 교체 시 rotate + scale + fade 애니메이션 (AnimatedSwitcher)
• 접근성: Semantics 기본 포함
• 색상 기본값은 ShadTheme.colorScheme에서 자동 해결 (라이트/다크 자동 대응)

DsIconToggle 파라미터

파라미터	타입	기본값	설명
icon	IconData	필수	현재 표시할 아이콘
onTap	VoidCallback	필수	탭 콜백
semanticLabel	String	필수	스크린리더용 레이블
tooltipMessage	String	필수	툴팁 메시지
iconKey	Key?	ValueKey(icon)	아이콘 전환 애니메이션 트리거 키
iconColor	Color?	ShadTheme.primary	아이콘 색상
backgroundColor	Color?	ShadTheme.muted	버튼 배경색
sizedBoxDimension	double	48	탭 영역 한 변 크기
iconSize	double	22	아이콘 크기

DsTextToggle은 icon 대신 label: String, iconColor 대신 labelColor를 사용하며 fontSize/fontWeight 파라미터를 추가로 받는다.

사용 예시

import 'package:flutter_ui_kit_widget/flutter_ui_kit_widget.dart';

DsIconToggle(
  icon: Icons.wb_sunny_rounded,
  iconKey: ValueKey(themeMode),
  onTap: () => setState(() => /* 상태 변경 */),
  semanticLabel: 'Light is active. Tap to switch to Dark.',
  tooltipMessage: 'light',
);

// ValueNotifier 패턴
final modeNotifier = ValueNotifier(ThemeMode.light);

ValueListenableBuilder<ThemeMode>(
  valueListenable: modeNotifier,
  builder: (_, mode, __) => DsIconToggle(
    icon: mode == ThemeMode.light
        ? Icons.wb_sunny_rounded
        : Icons.nightlight_rounded,
    iconKey: ValueKey(mode),
    onTap: () => modeNotifier.value =
        mode == ThemeMode.light ? ThemeMode.dark : ThemeMode.light,
    semanticLabel: '...',
    tooltipMessage: '...',
  ),
);

---

Glass 계열 — GlassPanel, GlassContainer, GlassButton

glassmorphism 표면 빌딩블록. BackdropFilter + 반투명 그라데이션 + 미세 보더로 유리 질감을 표현한다. 색상·보더·radius 기본값은 ShadTheme(존재 시) 또는 Material Theme(폴백)에서 자동 해결.

위젯	용도
GlassPanel	child 크기에 맞춰 늘어나는 glass 표면 (가장 기본 빌딩블록)
GlassContainer	명시적 width/height + 마진을 갖는 glass 박스 (카드/배지용)
GlassButton	glass 표면 위 라벨/아이콘 버튼, isLoading 상태 지원

저사양 기기·리스트 다량 렌더 환경에서는 enableBlur: false로 BackdropFilter를 비활성화할 수 있다.

GlassPanel(
  enableBlur: true,
  blurSigma: 12,
  child: Text('Hello'),
);

GlassButton(
  label: 'Sign in',
  icon: Icon(Icons.login),
  onPressed: () { /* ... */ },
);

---

OnboardingScreen

다중 OnboardingStep을 PageView로 보여주는 온보딩 플로우. 표면은 GlassPanel 기반의 glassmorphism이며, 페이지 도트 + 다음/이전/완료 버튼이 하단에 자동 배치된다.

OnboardingScreen(
  steps: [
    OnboardingStep(
      title: '환영합니다',
      description: '설명 텍스트',
      image: Image.asset('assets/playstore.png'),
    ),
  ],
  onComplete: () => Navigator.of(context).pushReplacement(...),
);

라벨 외부 주입(nextLabel, backLabel, completeLabel)으로 다국어 처리 가능.

---

이 패키지를 사용하는 패키지

패키지	위젯	설명
flutter_ui_kit_theme	DsThemeToggle	Light / Dark / System 전환 토글
flutter_ui_kit_theme	DsBrandToggle	Violet / Emerald 브랜드 전환 토글

---

설치

pubspec.yaml에 추가:

dependencies:
  flutter_ui_kit_widget: ^0.0.16
  shadcn_ui: ^0.53.6   # 권장: 앱 루트에 ShadApp 적용 시 필요

workspace 환경에서는 resolution: workspace와 루트 pubspec.yaml의 workspace: 목록에 경로를 추가해야 한다.

lib/flutter_ui_kit_widget.dart barrel만 import한다 (lib/src/ 내부 직접 import는 비공개).

import 'package:flutter_ui_kit_widget/flutter_ui_kit_widget.dart';

---

변경 이력

자세한 내역은 CHANGELOG.md 참고.

0.0.16

• 토글 3종 내부 구현을 shadcn_ui 기반(ShadIconButton ghost + ShadTooltip)으로 교체. 공개 API 100% 호환.
• Glass 3종의 색상·보더 기본값을 ShadTheme 토큰 기반으로 변경 (ShadTheme 미존재 시 Material Theme 자동 폴백).
• 디렉터리 재구성: lib/src/components/toggle/, lib/src/glass/로 정리. barrel만 사용한 외부 import는 영향 없음.

0.0.1

• DsIconToggle 추가