sh-ui-cli 0.15.0 → 0.21.0

package/data/registry/flutter/widgets/sh_ui_app_shell.dart

@@ -0,0 +1,267 @@
+import 'package:flutter/material.dart';
+import '../foundation/sh_ui_tokens.dart';
+import 'sh_ui_sidebar.dart';
+
+/// sh-ui App Shell — 사이드바 기반 앱 레이아웃을 한 번에 선언한다.
+///
+/// Scaffold + AppBar + ShUiSidebarProvider + ShUiSidebar + 메인 콘텐츠 교체를
+/// 내장하고, 선택된 아이템에 따라 본문과 AppBar 타이틀을 자동으로 바꾼다.
+/// 모바일에서는 drawer, 데스크탑에서는 inline 사이드바로 자동 전환.
+///
+/// 직접 Navigator push로 라우트를 쌓는 패턴이 필요한 경우에는 [ShUiSidebar]와
+/// [Scaffold]를 직접 조합한다. 이 위젯은 "한 화면에서 콘텐츠를 스위칭하는
+/// 단일 쉘 레이아웃"에 특화되어 있다.
+///
+/// ```dart
+/// ShUiAppShell(
+///   title: 'My App',
+///   groups: [
+///     ShUiAppShellGroup(label: '메뉴', items: [
+///       ShUiAppShellItem(
+///         icon: Icons.home,
+///         label: '홈',
+///         builder: (_) => HomeContent(),
+///       ),
+///       ShUiAppShellItem(
+///         icon: Icons.settings,
+///         label: '설정',
+///         builder: (_) => SettingsContent(),
+///       ),
+///     ]),
+///   ],
+/// )
+/// ```
+
+/// 사이드바 그룹 선언.
+@immutable
+class ShUiAppShellGroup {
+  /// 그룹 카테고리 라벨. 미지정 시 라벨 없이 항목만 노출.
+  final String? label;
+
+  /// 그룹에 속한 메뉴 항목 목록.
+  final List<ShUiAppShellItem> items;
+
+  /// 그룹 라벨 탭으로 접기/펼치기 가능.
+  final bool collapsible;
+
+  /// [collapsible] 활성 시 초기 확장 여부.
+  final bool initiallyExpanded;
+
+  const ShUiAppShellGroup({
+    this.label,
+    required this.items,
+    this.collapsible = true,
+    this.initiallyExpanded = true,
+  });
+}
+
+/// 사이드바 아이템 선언. 탭하면 [builder]가 메인 영역에 렌더된다.
+@immutable
+class ShUiAppShellItem {
+  /// 라벨 좌측에 붙는 아이콘 (선택).
+  final IconData? icon;
+
+  /// 메뉴 라벨. AppBar 타이틀로도 사용된다(item 선택 시 자동 갱신).
+  final String label;
+
+  /// 선택 시 메인 영역에 표시할 위젯을 반환. [Scaffold] 없이 body-only 위젯을 반환해야 한다.
+  final WidgetBuilder builder;
+
+  const ShUiAppShellItem({
+    this.icon,
+    required this.label,
+    required this.builder,
+  });
+}
+
+/// shUi App Shell 위젯. 위 파일 헤더 dartdoc 참고.
+///
+/// 사이드바 그룹/아이템과 AppBar 상수 옵션만 선언하면 한 줄로 앱 셸이 완성된다.
+/// 항상 한 화면에서 콘텐츠를 스위칭하는 단일 쉘 패턴에 사용한다.
+class ShUiAppShell extends StatefulWidget {
+  /// AppBar 좌측 로고/아이콘. 사이드바 헤더에도 동일하게 노출된다.
+  final Widget? logo;
+
+  /// 앱 이름. 사이드바 헤더 텍스트.
+  final String? title;
+
+  /// AppBar 우측 actions.
+  final List<Widget>? actions;
+
+  /// 사이드바 그룹들.
+  final List<ShUiAppShellGroup> groups;
+
+  /// 초기 선택 아이템 인덱스 (group 무관하게 flat 인덱스). 기본 0.
+  final int initialIndex;
+
+  /// 선택 변경 콜백 (flat 인덱스).
+  final ValueChanged<int>? onIndexChanged;
+
+  /// 메인이 비어있을 때(initialIndex가 범위 밖 등) 표시할 placeholder.
+  final WidgetBuilder? emptyBuilder;
+
+  /// 사이드바 variant.
+  final ShUiSidebarVariant sidebarVariant;
+
+  const ShUiAppShell({
+    super.key,
+    this.logo,
+    this.title,
+    this.actions,
+    required this.groups,
+    this.initialIndex = 0,
+    this.onIndexChanged,
+    this.emptyBuilder,
+    this.sidebarVariant = ShUiSidebarVariant.sidebar,
+  });
+
+  @override
+  State<ShUiAppShell> createState() => _ShUiAppShellState();
+}
+
+class _ShUiAppShellState extends State<ShUiAppShell> {
+  late int _selectedIndex;
+
+  @override
+  void initState() {
+    super.initState();
+    _selectedIndex = widget.initialIndex;
+  }
+
+  /// 그룹을 평탄화해 flat 아이템 리스트로 반환.
+  List<ShUiAppShellItem> get _flatItems =>
+      widget.groups.expand((g) => g.items).toList();
+
+  void _select(int flatIndex, BuildContext itemCtx, ShUiTheme shUi) {
+    if (flatIndex == _selectedIndex) {
+      // drawer 모드에서 같은 아이템을 다시 탭해도 drawer는 닫히도록.
+      _maybeCloseDrawer(itemCtx, shUi);
+      return;
+    }
+    setState(() => _selectedIndex = flatIndex);
+    widget.onIndexChanged?.call(flatIndex);
+    _maybeCloseDrawer(itemCtx, shUi);
+  }
+
+  void _maybeCloseDrawer(BuildContext itemCtx, ShUiTheme shUi) {
+    final scope = useSidebar(itemCtx);
+    final isNarrow =
+        MediaQuery.of(itemCtx).size.width < shUi.breakpoint.md;
+    if (scope != null && scope.open && isNarrow) {
+      scope.toggle();
+    }
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    final shUi = Theme.of(context).extension<ShUiTheme>() ?? ShUiTheme.light;
+    final colors = shUi.colors;
+    final items = _flatItems;
+    final selected = (items.isNotEmpty && _selectedIndex < items.length)
+        ? items[_selectedIndex]
+        : null;
+
+    return ShUiSidebarProvider(
+      defaultOpen: true,
+      child: Scaffold(
+        backgroundColor: colors.background,
+        appBar: AppBar(
+          leading: const Padding(
+            padding: EdgeInsets.symmetric(horizontal: 8),
+            child: ShUiSidebarTrigger(),
+          ),
+          title: Text(
+            selected?.label ?? widget.title ?? '',
+            style: TextStyle(
+              color: colors.foreground,
+              fontWeight: shUi.weight.semibold,
+            ),
+          ),
+          backgroundColor: colors.background,
+          elevation: 0,
+          scrolledUnderElevation: 0.5,
+          actions: widget.actions,
+          bottom: PreferredSize(
+            preferredSize: const Size.fromHeight(1),
+            child: Container(height: 1, color: colors.border),
+          ),
+        ),
+        body: Row(
+          children: [
+            ShUiSidebar(
+              variant: widget.sidebarVariant,
+              header: (widget.logo != null || widget.title != null)
+                  ? ShUiSidebarHeader(child: _buildHeader(shUi, colors))
+                  : null,
+              children: [
+                for (final group in widget.groups)
+                  ShUiSidebarGroup(
+                    label: group.label,
+                    collapsible: group.collapsible,
+                    initiallyExpanded: group.initiallyExpanded,
+                    children: [
+                      for (final item in group.items)
+                        _buildItem(item, items.indexOf(item), shUi),
+                    ],
+                  ),
+              ],
+            ),
+            Expanded(
+              child: selected != null
+                  ? Builder(builder: selected.builder)
+                  : (widget.emptyBuilder != null
+                      ? Builder(builder: widget.emptyBuilder!)
+                      : const SizedBox.shrink()),
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+
+  Widget _buildHeader(ShUiTheme shUi, ShUiColorTokens colors) {
+    return Builder(
+      builder: (ctx) {
+        final isOpen = useSidebar(ctx)?.open ?? true;
+        if (!isOpen) {
+          return Center(
+            child: widget.logo ??
+                Icon(Icons.apps, size: 20, color: colors.foreground),
+          );
+        }
+        return Row(
+          children: [
+            if (widget.logo != null) ...[
+              widget.logo!,
+              SizedBox(width: shUi.spacing.s2),
+            ],
+            if (widget.title != null)
+              Expanded(
+                child: Text(
+                  widget.title!,
+                  style: TextStyle(
+                    color: colors.foreground,
+                    fontSize: shUi.text.lg,
+                    fontWeight: shUi.weight.bold,
+                    letterSpacing: -0.5,
+                  ),
+                  overflow: TextOverflow.ellipsis,
+                ),
+              ),
+          ],
+        );
+      },
+    );
+  }
+
+  Widget _buildItem(ShUiAppShellItem item, int flatIndex, ShUiTheme shUi) {
+    return Builder(
+      builder: (itemCtx) => ShUiSidebarItem(
+        icon: item.icon,
+        label: item.label,
+        isActive: flatIndex == _selectedIndex,
+        onTap: () => _select(flatIndex, itemCtx, shUi),
+      ),
+    );
+  }
+}

package/data/registry/flutter/widgets/sh_ui_avatar.dart

@@ -0,0 +1,95 @@
+import 'package:flutter/material.dart';
+import '../foundation/sh_ui_tokens.dart';
+
+enum ShUiAvatarSize { sm, md, lg, xl }
+
+/// sh-ui Avatar — 프로필 이미지 + 이니셜/아이콘 fallback.
+///
+/// [imageUrl]이 주어지면 이미지를 로드하고, 실패 시 [fallback]을 렌더한다.
+/// 이미지 없이 이니셜만 보여주려면 [imageUrl]을 생략하고 [fallback]만 제공.
+class ShUiAvatar extends StatelessWidget {
+  /// 로드할 이미지 URL. 네트워크 또는 asset. null이면 바로 fallback 렌더.
+  final String? imageUrl;
+
+  /// 이미지 로드 실패/미제공 시 표시할 위젯(보통 이니셜 Text 또는 Icon).
+  final Widget? fallback;
+
+  final ShUiAvatarSize size;
+  final String? semanticLabel;
+
+  const ShUiAvatar({
+    super.key,
+    this.imageUrl,
+    this.fallback,
+    this.size = ShUiAvatarSize.md,
+    this.semanticLabel,
+  });
+
+  double _diameter() => switch (size) {
+        ShUiAvatarSize.sm => 28.0,
+        ShUiAvatarSize.md => 40.0,
+        ShUiAvatarSize.lg => 48.0,
+        ShUiAvatarSize.xl => 64.0,
+      };
+
+  double _fontSize() => switch (size) {
+        ShUiAvatarSize.sm => 11.0,
+        ShUiAvatarSize.md => 13.0,
+        ShUiAvatarSize.lg => 14.0,
+        ShUiAvatarSize.xl => 16.0,
+      };
+
+  @override
+  Widget build(BuildContext context) {
+    final shUi = Theme.of(context).extension<ShUiTheme>() ?? ShUiTheme.light;
+    final colors = shUi.colors;
+    final diameter = _diameter();
+
+    final fallbackWidget = DefaultTextStyle(
+      style: TextStyle(
+        color: colors.foregroundMuted,
+        fontSize: _fontSize(),
+        fontWeight: shUi.weight.medium,
+        letterSpacing: 0.3,
+      ),
+      textAlign: TextAlign.center,
+      child: IconTheme(
+        data: IconThemeData(
+          color: colors.foregroundMuted,
+          size: _fontSize() + 4,
+        ),
+        child: fallback ?? const SizedBox.shrink(),
+      ),
+    );
+
+    final content = imageUrl != null
+        ? Image.network(
+            imageUrl!,
+            fit: BoxFit.cover,
+            width: diameter,
+            height: diameter,
+            errorBuilder: (_, __, ___) => fallbackWidget,
+            loadingBuilder: (context, child, progress) {
+              if (progress == null) return child;
+              return fallbackWidget;
+            },
+          )
+        : fallbackWidget;
+
+    return Semantics(
+      label: semanticLabel,
+      image: imageUrl != null,
+      child: Container(
+        width: diameter,
+        height: diameter,
+        alignment: Alignment.center,
+        decoration: BoxDecoration(
+          color: colors.backgroundMuted,
+          shape: BoxShape.circle,
+        ),
+        clipBehavior: Clip.antiAlias,
+        child: content,
+      ),
+    );
+  }
+}

package/data/registry/flutter/widgets/sh_ui_badge.dart

@@ -0,0 +1,82 @@
+import 'package:flutter/material.dart';
+import '../foundation/sh_ui_tokens.dart';
+
+enum ShUiBadgeVariant { primary, secondary, success, warning, danger, outline }
+
+enum ShUiBadgeSize { sm, md }
+
+/// sh-ui Badge — 상태·카테고리·수량을 짧게 표기하는 인라인 라벨.
+///
+/// 색만으로 의미를 전달하지 말고 텍스트·아이콘과 함께 사용한다.
+class ShUiBadge extends StatelessWidget {
+  final Widget child;
+  final ShUiBadgeVariant variant;
+  final ShUiBadgeSize size;
+
+  const ShUiBadge({
+    super.key,
+    required this.child,
+    this.variant = ShUiBadgeVariant.primary,
+    this.size = ShUiBadgeSize.md,
+  });
+
+  /// 텍스트만 넣는 편의 생성자.
+  factory ShUiBadge.text(
+    String text, {
+    Key? key,
+    ShUiBadgeVariant variant = ShUiBadgeVariant.primary,
+    ShUiBadgeSize size = ShUiBadgeSize.md,
+  }) {
+    return ShUiBadge(
+      key: key,
+      variant: variant,
+      size: size,
+      child: Text(text),
+    );
+  }
+
+  (Color bg, Color fg, Color border) _colors(ShUiColorTokens c) {
+    return switch (variant) {
+      ShUiBadgeVariant.primary => (c.primary, c.primaryForeground, Colors.transparent),
+      ShUiBadgeVariant.secondary => (c.backgroundMuted, c.foreground, c.border),
+      ShUiBadgeVariant.success => (const Color(0xFF16A34A), Colors.white, Colors.transparent),
+      ShUiBadgeVariant.warning => (const Color(0xFFD97706), Colors.white, Colors.transparent),
+      ShUiBadgeVariant.danger => (c.danger, c.dangerForeground, Colors.transparent),
+      ShUiBadgeVariant.outline => (Colors.transparent, c.foreground, c.borderStrong),
+    };
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    final shUi = Theme.of(context).extension<ShUiTheme>() ?? ShUiTheme.light;
+    final (bg, fg, border) = _colors(shUi.colors);
+
+    final (double height, double fontSize, EdgeInsets padding) = switch (size) {
+      ShUiBadgeSize.sm => (20.0, 11.0, const EdgeInsets.symmetric(horizontal: 6)),
+      ShUiBadgeSize.md => (24.0, shUi.text.xs, const EdgeInsets.symmetric(horizontal: 8)),
+    };
+
+    return Container(
+      height: height,
+      padding: padding,
+      decoration: BoxDecoration(
+        color: bg,
+        border: Border.all(color: border),
+        borderRadius: BorderRadius.circular(999),
+      ),
+      alignment: Alignment.center,
+      child: DefaultTextStyle(
+        style: TextStyle(
+          color: fg,
+          fontSize: fontSize,
+          fontWeight: shUi.weight.medium,
+          height: 1,
+        ),
+        child: IconTheme(
+          data: IconThemeData(color: fg, size: fontSize + 2),
+          child: child,
+        ),
+      ),
+    );
+  }
+}

package/data/registry/flutter/widgets/sh_ui_breadcrumb.dart

@@ -0,0 +1,107 @@
+import 'package:flutter/material.dart';
+import '../foundation/sh_ui_tokens.dart';
+
+/// sh-ui Breadcrumb — 현재 페이지의 계층 위치를 나타내는 내비게이션.
+///
+/// ShUiBreadcrumb(
+///   items: [
+///     ShUiBreadcrumbItem(label: '홈', onTap: () => ...),
+///     ShUiBreadcrumbItem(label: '컴포넌트', onTap: () => ...),
+///     ShUiBreadcrumbItem(label: 'Breadcrumb', isCurrent: true),
+///   ],
+/// )
+class ShUiBreadcrumb extends StatelessWidget {
+  final List<ShUiBreadcrumbItem> items;
+
+  /// 구분자 위젯. null이면 ▶ 아이콘.
+  final Widget? separator;
+
+  const ShUiBreadcrumb({
+    super.key,
+    required this.items,
+    this.separator,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    final shUi = Theme.of(context).extension<ShUiTheme>() ?? ShUiTheme.light;
+    final colors = shUi.colors;
+
+    final effectiveSeparator = separator ??
+        Icon(
+          Icons.chevron_right,
+          size: 16,
+          color: colors.foregroundMuted.withValues(alpha: 0.6),
+        );
+
+    final children = <Widget>[];
+    for (var i = 0; i < items.length; i++) {
+      children.add(items[i]);
+      if (i < items.length - 1) {
+        children.add(
+          Padding(
+            padding: const EdgeInsets.symmetric(horizontal: 6),
+            child: effectiveSeparator,
+          ),
+        );
+      }
+    }
+
+    return Semantics(
+      label: 'Breadcrumb',
+      container: true,
+      child: Wrap(
+        crossAxisAlignment: WrapCrossAlignment.center,
+        children: children,
+      ),
+    );
+  }
+}
+
+/// Breadcrumb 내 단일 항목.
+///
+/// - [onTap]이 주어지면 링크처럼 동작.
+/// - [isCurrent] = true면 현재 페이지(탭 불가, 강조).
+class ShUiBreadcrumbItem extends StatelessWidget {
+  final String label;
+  final VoidCallback? onTap;
+  final bool isCurrent;
+
+  const ShUiBreadcrumbItem({
+    super.key,
+    required this.label,
+    this.onTap,
+    this.isCurrent = false,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    final shUi = Theme.of(context).extension<ShUiTheme>() ?? ShUiTheme.light;
+    final colors = shUi.colors;
+
+    final text = Text(
+      label,
+      style: TextStyle(
+        color: isCurrent ? colors.foreground : colors.foregroundMuted,
+        fontSize: shUi.text.sm,
+        fontWeight: isCurrent ? shUi.weight.medium : FontWeight.normal,
+      ),
+    );
+
+    if (isCurrent || onTap == null) {
+      return Semantics(
+        header: isCurrent,
+        child: text,
+      );
+    }
+
+    return InkWell(
+      onTap: onTap,
+      borderRadius: BorderRadius.circular(4),
+      child: Padding(
+        padding: const EdgeInsets.symmetric(horizontal: 2),
+        child: text,
+      ),
+    );
+  }
+}