@unikit-bridge/ui 0.1.0 → 0.2.0

package/src/components/accordion.tsx

@@ -0,0 +1,231 @@
+// Accordion — shadcn/ui(new-york-v4) accordion.tsx 유니버설 포팅 (사이클 30, T-3b).
+// 원본: shadcn-ref/src/accordion/accordion.tsx — radix Accordion 엔진을 제거하고
+// 전개 상태는 React state + context로 직접 관리한다(collapsible.tsx의 다중 항목
+// 확장 구조). 원본의 data-state·셀렉터 클래스는 조건부 클래스·글리프 교체로 전개.
+//
+// 포팅 판단(원본 대비 차이):
+// - ChevronDown 아이콘 → 글리프 Text(닫힘 ⌄ / 펼침 ⌃ 교체). 원본의 회전 전이
+//   애니메이션은 상실(로드맵) — 글자 교체로 상태를 즉시 표시한다.
+// - 항목 구분선의 마지막 항목 제외(last 변형)는 위치 셀렉터라 네이티브 재현 불가
+//   — 제거. 마지막 항목 하단선 제거는 사용처 className 오버라이드로 한다.
+// - 콘텐츠 전이 애니메이션 미지원 — value 일치 시에만 마운트(즉시 전환).
+//   원본의 이중 뷰(애니메이션용 바깥쪽 + 패딩 안쪽)는 애니메이션 상실로 한 벌로
+//   통합하고 사용처 className은 같은 패딩 토큰 위에 병합된다.
+// - single 모드의 collapsible은 기본 true(shadcn 관용 — 원본 radix 기본값은 false).
+// - aria-controls ↔ 콘텐츠 nativeID를 루트 useId 토대로 결정적으로 연결한다.
+import {
+  createContext,
+  forwardRef,
+  useContext,
+  useId,
+  useState,
+  type ReactNode,
+} from "react";
+import {
+  Pressable,
+  Text,
+  View,
+  type BridgePressableRef,
+  type BridgeViewRef,
+  type PressableProps,
+  type ViewProps,
+} from "@unikit-bridge/ui/primitives";
+
+import { cn } from "../lib/utils";
+
+type AccordionContextValue = {
+  type: "single" | "multiple";
+  collapsible: boolean;
+  openItems: string[];
+  toggleItem: (value: string) => void;
+  /** 트리거 aria-controls ↔ 콘텐츠 nativeID 연결용 토대 ID */
+  baseId: string;
+};
+
+const AccordionContext = createContext<AccordionContextValue | null>(null);
+
+function useAccordionContext(component: string): AccordionContextValue {
+  const ctx = useContext(AccordionContext);
+  if (!ctx) {
+    throw new Error(`<${component}>는 <Accordion> 안에서 사용해야 합니다.`);
+  }
+  return ctx;
+}
+
+type AccordionItemContextValue = {
+  value: string;
+  open: boolean;
+  toggle: () => void;
+  contentId: string;
+};
+
+const AccordionItemContext = createContext<AccordionItemContextValue | null>(
+  null,
+);
+
+function useAccordionItemContext(
+  component: string,
+): AccordionItemContextValue {
+  const ctx = useContext(AccordionItemContext);
+  if (!ctx) {
+    throw new Error(`<${component}>는 <AccordionItem> 안에서 사용해야 합니다.`);
+  }
+  return ctx;
+}
+
+// 콘텐츠 패널 ID — value의 공백은 ID에 쓸 수 없어 치환.
+function contentIdOf(baseId: string, value: string) {
+  return `${baseId}-accordion-content-${value.replace(/\s+/g, "-")}`;
+}
+
+function toItems(value: string | string[] | undefined): string[] {
+  if (value === undefined) return [];
+  return Array.isArray(value) ? value : [value];
+}
+
+export type AccordionProps = ViewProps & {
+  type?: "single" | "multiple";
+  /** single 모드에서 펼친 항목 다시 접기 허용 여부(기본 true — shadcn 관용) */
+  collapsible?: boolean;
+  /** single 모드에서는 문자열 1개, multiple 모드에서는 펼친 value 배열 */
+  value?: string | string[];
+  defaultValue?: string | string[];
+  onValueChange?: (value: string | string[]) => void;
+};
+
+const Accordion = forwardRef<BridgeViewRef, AccordionProps>(
+  (
+    { type = "single", collapsible = true, value, defaultValue, onValueChange, children, ...props },
+    ref,
+  ) => {
+    // 비제어 상태 — 제어(value 지정)면 무시된다.
+    const [internalItems, setInternalItems] = useState(() =>
+      toItems(defaultValue),
+    );
+    const openItems = value !== undefined ? toItems(value) : internalItems;
+    const toggleItem = (itemValue: string) => {
+      const isOpen = openItems.includes(itemValue);
+      let next: string[];
+      if (isOpen) {
+        // single 비접이형(collapsible=false)은 마지막 펼침 항목을 유지한다.
+        if (type === "single" && !collapsible) return;
+        next = openItems.filter((v) => v !== itemValue);
+      } else {
+        next =
+          type === "single"
+            ? [itemValue]
+            : [...openItems, itemValue];
+      }
+      if (value === undefined) setInternalItems(next);
+      if (type === "single") onValueChange?.(next[0] ?? "");
+      else onValueChange?.(next);
+    };
+    const baseId = useId();
+    return (
+      <AccordionContext.Provider
+        value={{ type, collapsible, openItems, toggleItem, baseId }}
+      >
+        <View ref={ref} {...props}>
+          {children}
+        </View>
+      </AccordionContext.Provider>
+    );
+  },
+);
+Accordion.displayName = "Accordion";
+
+export type AccordionItemProps = ViewProps & {
+  value: string;
+};
+
+const AccordionItem = forwardRef<BridgeViewRef, AccordionItemProps>(
+  ({ value, className, children, ...props }, ref) => {
+    const accordion = useAccordionContext("AccordionItem");
+    const open = accordion.openItems.includes(value);
+    return (
+      <AccordionItemContext.Provider
+        value={{
+          value,
+          open,
+          toggle: () => accordion.toggleItem(value),
+          contentId: contentIdOf(accordion.baseId, value),
+        }}
+      >
+        <View
+          ref={ref}
+          className={cn("border-b border-border", className)}
+          {...props}
+        >
+          {children}
+        </View>
+      </AccordionItemContext.Provider>
+    );
+  },
+);
+AccordionItem.displayName = "AccordionItem";
+
+export type AccordionTriggerProps = PressableProps & {
+  // 함수형 children은 내부 Text 래핑 구조와 양립하지 않아 문자열 children 권장.
+  children?: ReactNode;
+};
+
+const AccordionTrigger = forwardRef<BridgePressableRef, AccordionTriggerProps>(
+  ({ className, children, disabled, onPress, ...props }, ref) => {
+    const item = useAccordionItemContext("AccordionTrigger");
+    return (
+      <Pressable
+        ref={ref}
+        accessibilityRole="button"
+        aria-expanded={item.open}
+        aria-controls={item.contentId}
+        disabled={disabled}
+        onPress={() => {
+          item.toggle();
+          onPress?.();
+        }}
+        className={cn(
+          "flex-row items-start justify-between gap-4 rounded-md py-4 web:transition-all",
+          "web:focus-visible:ring-2 web:focus-visible:ring-ring web:focus-visible:ring-offset-2 web:focus-visible:ring-offset-background",
+          disabled && "web:pointer-events-none opacity-50",
+          className,
+        )}
+        {...props}
+      >
+        {/* 이중 지정: 전경색·밑줄은 내부 Text에(네이티브는 색 상속 불가) */}
+        <Text className="flex-1 font-sans text-left text-sm font-medium text-foreground web:hover:underline">
+          {children}
+        </Text>
+        {/* 펼침 표시 글리프 — 원본 svg 회전 대신 글자 교체(⌄ 닫힘 / ⌃ 펼침) */}
+        <View aria-hidden>
+          <Text className="text-base text-muted-foreground web:select-none">
+            {item.open ? "⌃" : "⌄"}
+          </Text>
+        </View>
+      </Pressable>
+    );
+  },
+);
+AccordionTrigger.displayName = "AccordionTrigger";
+
+export type AccordionContentProps = ViewProps;
+
+const AccordionContent = forwardRef<BridgeViewRef, AccordionContentProps>(
+  ({ className, children, nativeID, ...props }, ref) => {
+    const item = useAccordionItemContext("AccordionContent");
+    // 펼침 항목만 렌더 — 마운트/언마운트 방식(애니메이션 없음).
+    if (!item.open) return null;
+    return (
+      <View
+        ref={ref}
+        nativeID={nativeID ?? item.contentId}
+        className={cn("overflow-hidden pb-4 pt-0", className)}
+        {...props}
+      >
+        {children}
+      </View>
+    );
+  },
+);
+AccordionContent.displayName = "AccordionContent";
+
+export { Accordion, AccordionItem, AccordionTrigger, AccordionContent };

package/src/components/alert.tsx

@@ -0,0 +1,157 @@
+// Alert — shadcn/ui new-york-v4 alert 포팅(/tmp/shadcn-ref/src/alert). 3종 export.
+// 포팅 판단:
+// - 원본은 grid + has-자손 셀렉터로 선택적 아이콘 열을 배치한다.
+//   data·자손 셀렉터는 네이티브에서 동작하지 않으므로 flex-row(글리프 + 콘텐츠 열)
+//   구조로 재작성하고, 좌측 아이콘은 글리프 Text(default ⓘ / destructive ⚠)로
+//   표시한다(아이콘 없는 배치는 미지원). 색·여백·rounding 토큰은 유지.
+// - 원본의 텍스트 색 상속(text-card-foreground / text-destructive)은 이중 지정
+//   원칙에 따라 내부 Text로 이동. 특히 AlertDescription의 destructive 톤(원본은
+//   data-slot=alert-description 자손 셀렉터의 text-destructive/90)은 셀렉터를
+//   쓸 수 없어 React context로 variant를 전달한다 — variant prop은 원본대로
+//   Alert에만 존재한다(Alert 단독 사용 시 하위 컴포넌트는 default 톤).
+// - role="alert"은 원본 그대로 유지(신규 접근성 계약 BridgeRole "alert").
+// - 웹 전용 토큰 처리: line-clamp-1·tracking-tight은 web: 접두, 그리드 전용
+//   col-start-*·min-h-4와 [&_p]:leading-relaxed(단락 자손 스타일)은 소실.
+import { createContext, forwardRef, useContext } from "react";
+import {
+  Text,
+  View,
+  type BridgeTextRef,
+  type BridgeViewRef,
+  type TextProps,
+  type ViewProps,
+} from "@unikit-bridge/ui/primitives";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn } from "../lib/utils";
+
+// 컨테이너(View) — 배경·테두리. 원본의 grid 배치를 flex-row(글리프+콘텐츠 열)로 치환.
+const alertVariants = cva(
+  "relative w-full flex-row items-start gap-3 rounded-lg border px-4 py-3",
+  {
+    variants: {
+      variant: {
+        default: "bg-card",
+        // 원본 destructive의 border-destructive/50 토큰 유지(사소 5 — 포팅
+        // 초판에서 누락돼 destructive가 글자색으로만 구분됐다).
+        destructive: "bg-card border-destructive/50",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  },
+);
+
+// 좌측 글리프 Text — 원본 [&>svg]:size-4·text-current 아이콘의 글리프 대체.
+const alertGlyphVariants = cva("text-base leading-none", {
+  variants: {
+    variant: {
+      default: "text-card-foreground",
+      destructive: "text-destructive",
+    },
+  },
+  defaultVariants: {
+    variant: "default",
+  },
+});
+
+// 제목 Text — 원본 col-start-2 line-clamp-1 font-medium tracking-tight.
+const alertTitleVariants = cva(
+  "font-sans text-sm font-medium leading-none web:line-clamp-1 web:tracking-tight",
+  {
+    variants: {
+      variant: {
+        default: "text-card-foreground",
+        destructive: "text-destructive",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  },
+);
+
+// 설명 Text — 원본 text-muted-foreground, destructive는 /90 톤(자손 셀렉터 대체).
+const alertDescriptionVariants = cva(
+  "font-sans text-sm text-muted-foreground",
+  {
+    variants: {
+      variant: {
+        default: "",
+        destructive: "text-destructive/90",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  },
+);
+
+// variant 전파용 React context — 원본의 `*:` 자손 셀렉터를 대체한다.
+const AlertContext = createContext<
+  NonNullable<VariantProps<typeof alertVariants>["variant"]>
+>("default");
+
+export type AlertProps = ViewProps & VariantProps<typeof alertVariants>;
+export type AlertTitleProps = TextProps;
+export type AlertDescriptionProps = TextProps;
+
+const Alert = forwardRef<BridgeViewRef, AlertProps>(
+  ({ className, variant, children, ...props }, ref) => (
+    <AlertContext.Provider value={variant ?? "default"}>
+      <View
+        ref={ref}
+        accessibilityRole="alert"
+        className={cn(alertVariants({ variant }), className)}
+        {...props}
+      >
+        <View aria-hidden className="mt-0.5 shrink-0">
+          <Text className={cn(alertGlyphVariants({ variant }))}>
+            {variant === "destructive" ? "⚠" : "ⓘ"}
+          </Text>
+        </View>
+        <View className="flex flex-col gap-0.5">{children}</View>
+      </View>
+    </AlertContext.Provider>
+  ),
+);
+Alert.displayName = "Alert";
+
+const AlertTitle = forwardRef<BridgeTextRef, AlertTitleProps>(
+  ({ className, ...props }, ref) => {
+    const variant = useContext(AlertContext);
+    return (
+      <Text
+        ref={ref}
+        className={cn(alertTitleVariants({ variant }), className)}
+        {...props}
+      />
+    );
+  },
+);
+AlertTitle.displayName = "AlertTitle";
+
+const AlertDescription = forwardRef<BridgeTextRef, AlertDescriptionProps>(
+  ({ className, ...props }, ref) => {
+    const variant = useContext(AlertContext);
+    return (
+      <Text
+        ref={ref}
+        className={cn(alertDescriptionVariants({ variant }), className)}
+        {...props}
+      />
+    );
+  },
+);
+AlertDescription.displayName = "AlertDescription";
+
+export {
+  Alert,
+  AlertTitle,
+  AlertDescription,
+  alertVariants,
+  alertGlyphVariants,
+  alertTitleVariants,
+  alertDescriptionVariants,
+};

package/src/components/aspect-ratio.tsx

@@ -0,0 +1,40 @@
+// AspectRatio — shadcn/ui(new-york-v4) aspect-ratio.tsx 유니버설 포팅 (사이클 30, T-3b).
+// 원본: shadcn-ref/src/aspect-ratio/aspect-ratio.tsx — radix AspectRatio 엔진을
+// 제거하고 비율은 BridgeStyle 동적 인라인 스타일 계약으로 표현한다.
+//
+// 포팅 판단(원본 대비 차이):
+// - 원본(radix)은 웹 구형 호환을 위해 패딩 핵으로 비율을 만들었다. 브리지 계약의
+//   aspectRatio는 숫자 값이 웹 DOM(단위 없는 비율)·RN(원시 프로퍼티) 양쪽에
+//   유효해 style 지정으로 대체한다(정적 스타일이 아닌 사용자 지정 비율 값이므로
+//   className 원칙의 동적 값 예외에 해당).
+// - 원본의 overflow hidden은 className(overflow-hidden)으로 유지.
+import { forwardRef } from "react";
+import {
+  View,
+  type BridgeViewRef,
+  type ViewProps,
+} from "@unikit-bridge/ui/primitives";
+
+import { cn } from "../lib/utils";
+
+export type AspectRatioProps = ViewProps & {
+  /** 가로세로 비율(가로 ÷ 세로, 기본 1 — 정사각형) */
+  ratio?: number;
+};
+
+const AspectRatio = forwardRef<BridgeViewRef, AspectRatioProps>(
+  ({ ratio = 1, className, style, children, ...props }, ref) => (
+    <View
+      ref={ref}
+      className={cn("overflow-hidden", className)}
+      // 사용자 style이 있으면 병합 — 비율은 컴포넌트 계약값이 우선한다.
+      style={{ ...style, aspectRatio: ratio }}
+      {...props}
+    >
+      {children}
+    </View>
+  ),
+);
+AspectRatio.displayName = "AspectRatio";
+
+export { AspectRatio };

package/src/components/avatar.tsx

@@ -0,0 +1,275 @@
+// Avatar — shadcn/ui new-york-v4 avatar(Radix Avatar 기반)를 UniKit 유니버설로 이식.
+//
+// 포팅 판단(radix 엔진 의존 제거):
+// - 로드 실패 상태 공유는 React context로 재현 — Avatar(루트)가
+//   { size, hasImage, imageFailed }를 제공하고, AvatarImage가 마운트 등록/
+//   실패 보고(브리지 Image onError), AvatarFallback이
+//   "소스 없음 또는 로드 실패"일 때만 렌더된다.
+// - 브리지 Image에 onLoad 계약이 없어 '로드 성공'을 알 수 없으므로 폴백
+//   표시 조건을 Radix의 "로드 전+실패"에서 "소스 없음+실패"로 단순화했다.
+//   실패한 AvatarImage는 렌더를 중단한다(Radix는 깨진 img를 남긴다).
+// - 원본의 data-size + group-data size/avatar 셀렉터(폴백 글자 크기·배지
+//   크기 연동)는 아래 조회 테이블로 치환 — 각 컴포넌트가 context size를 읽어
+//   자기 크기 클래스를 적용한다.
+// - AvatarGroup의 겹침(-space-x-2)과 data-slot=avatar 자식 링은 자식 셀렉터가
+//   필요하다. 겹침은 웹 전용 클래스로 유지(네이티브은 나란히 배치)하고, 링은
+//   Avatar가 AvatarGroupContext를 읽어 자신에게 ring-2를 건다.
+// - AvatarGroupCount의 그룹 크기 반응(group-has-data-...)은 고정 토큰(size-8)으로
+//   단순화. AvatarBadge 내용은 글리프 Text 또는 비움(배경 자체가 상태 점).
+import {
+  createContext,
+  forwardRef,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  type ReactNode,
+} from "react";
+import {
+  Image,
+  Text,
+  View,
+  type BridgeImageRef,
+  type BridgeViewRef,
+  type ImageProps,
+  type ViewProps,
+} from "@unikit-bridge/ui/primitives";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn } from "../lib/utils";
+
+export type AvatarSize = "default" | "sm" | "lg";
+
+// 루트 크기 — 원본 data-size 셀렉터(size-8 · sm:size-6 · lg:size-10) 치환.
+const avatarVariants = cva(
+  "relative flex shrink-0 overflow-hidden rounded-full web:select-none",
+  {
+    variants: {
+      size: {
+        default: "size-8",
+        sm: "size-6",
+        lg: "size-10",
+      },
+    },
+    defaultVariants: {
+      size: "default",
+    },
+  },
+);
+
+// 폴백 글자 크기(원본의 group-data size=sm → text-xs)·배지 크기
+// (sm 2 · default 2.5 · lg 3) — context size 값으로 조회하는 치환 테이블.
+const AVATAR_FALLBACK_TEXT: Record<AvatarSize, string> = {
+  default: "text-sm",
+  sm: "text-xs",
+  lg: "text-sm",
+};
+const AVATAR_BADGE_SIZE: Record<AvatarSize, string> = {
+  default: "size-2.5",
+  sm: "size-2",
+  lg: "size-3",
+};
+
+// 루트가 제공하는 상태 — 폴백 전환 판단의 단일 출처.
+type AvatarContextValue = {
+  size: AvatarSize;
+  /** AvatarImage 마운트 여부 — false면 "소스 없음"으로 폴백 렌더 */
+  hasImage: boolean;
+  /** AvatarImage 로드 실패 — 폴백으로 전환 */
+  imageFailed: boolean;
+  reportImageMounted: (mounted: boolean) => void;
+  reportImageFailed: () => void;
+};
+
+const AvatarContext = createContext<AvatarContextValue | null>(null);
+
+// AvatarGroup 내부 여부 — Avatar가 겹침 경계 링을 자신에게 적용한다.
+const AvatarGroupContext = createContext(false);
+
+// ---------------------------------------------------------------------------
+// Avatar — 루트 컨테이너. 상태 제공자역도 겸한다(원본 AvatarPrimitive.Root).
+// ---------------------------------------------------------------------------
+export type AvatarProps = ViewProps &
+  VariantProps<typeof avatarVariants> & {
+    children?: ReactNode;
+  };
+
+const Avatar = forwardRef<BridgeViewRef, AvatarProps>(
+  ({ className, size, ...props }, ref) => {
+    const [hasImage, setHasImage] = useState(false);
+    const [imageFailed, setImageFailed] = useState(false);
+    const grouped = useContext(AvatarGroupContext);
+    const resolvedSize = size ?? "default";
+    const contextValue = useMemo<AvatarContextValue>(
+      () => ({
+        size: resolvedSize,
+        hasImage,
+        imageFailed,
+        // setState 설정자는 참조가 안정적이라 그대로 노출해도 안전하다.
+        reportImageMounted: setHasImage,
+        reportImageFailed: () => setImageFailed(true),
+      }),
+      [resolvedSize, hasImage, imageFailed],
+    );
+    return (
+      <AvatarContext.Provider value={contextValue}>
+        <View
+          ref={ref}
+          className={cn(
+            avatarVariants({ size }),
+            grouped && "ring-2 ring-background",
+            className,
+          )}
+          {...props}
+        />
+      </AvatarContext.Provider>
+    );
+  },
+);
+Avatar.displayName = "Avatar";
+
+// ---------------------------------------------------------------------------
+// AvatarImage — 브리지 Image(원격 {uri}만). 실패 보고는 context로.
+// ---------------------------------------------------------------------------
+// onError는 폴백 전환의 통로이므로 props에서 제외하고 컴포넌트가 소유한다.
+export type AvatarImageProps = Omit<ImageProps, "onError">;
+
+const AvatarImage = forwardRef<BridgeImageRef, AvatarImageProps>(
+  ({ className, source, ...props }, ref) => {
+    const avatar = useContext(AvatarContext);
+    // 마운트 등록/해제 — 폴백의 "소스 없음" 판단 근거(provider는 안정적).
+    useEffect(() => {
+      avatar?.reportImageMounted(true);
+      return () => avatar?.reportImageMounted(false);
+    }, [avatar]);
+    // 실패한 이미지는 렌더하지 않는다(포팅 노트 — Radix는 깨진 img를 남김).
+    if (avatar?.imageFailed) {
+      return null;
+    }
+    return (
+      <Image
+        ref={ref}
+        source={source}
+        onError={avatar ? avatar.reportImageFailed : undefined}
+        className={cn("aspect-square size-full", className)}
+        {...props}
+      />
+    );
+  },
+);
+AvatarImage.displayName = "AvatarImage";
+
+// ---------------------------------------------------------------------------
+// AvatarFallback — 이니셜/글리프. "소스 없음 또는 실패"일 때만 렌더.
+// ---------------------------------------------------------------------------
+export type AvatarFallbackProps = ViewProps & {
+  children?: ReactNode;
+};
+
+const AvatarFallback = forwardRef<BridgeViewRef, AvatarFallbackProps>(
+  ({ className, children, ...props }, ref) => {
+    const avatar = useContext(AvatarContext);
+    // Avatar 밖 단독 사용(문맥 없음)이면 항상 렌드한다.
+    const visible = avatar ? !avatar.hasImage || avatar.imageFailed : true;
+    if (!visible) {
+      return null;
+    }
+    return (
+      <View
+        ref={ref}
+        className={cn(
+          "flex size-full items-center justify-center rounded-full bg-muted",
+          className,
+        )}
+        {...props}
+      >
+        {/* 이중 지정 원칙: 전경색은 내부 Text에 — children은 이니셜/글리프 문자열 권장 */}
+        <Text
+          className={cn(
+            "font-sans text-muted-foreground",
+            avatar && AVATAR_FALLBACK_TEXT[avatar.size],
+          )}
+        >
+          {children}
+        </Text>
+      </View>
+    );
+  },
+);
+AvatarFallback.displayName = "AvatarFallback";
+
+// ---------------------------------------------------------------------------
+// AvatarBadge — 우하단 상태 점. 크기는 context size 연동.
+// ---------------------------------------------------------------------------
+export type AvatarBadgeProps = ViewProps;
+
+const AvatarBadge = forwardRef<BridgeViewRef, AvatarBadgeProps>(
+  ({ className, ...props }, ref) => {
+    const avatar = useContext(AvatarContext);
+    return (
+      <View
+        ref={ref}
+        className={cn(
+          "absolute right-0 bottom-0 z-10 flex items-center justify-center rounded-full bg-primary ring-2 ring-background web:select-none",
+          avatar && AVATAR_BADGE_SIZE[avatar.size],
+          className,
+        )}
+        {...props}
+      />
+    );
+  },
+);
+AvatarBadge.displayName = "AvatarBadge";
+
+// ---------------------------------------------------------------------------
+// AvatarGroup — 아바타 무리. 겹침은 웹 전용(네이티브은 나란히).
+// ---------------------------------------------------------------------------
+export type AvatarGroupProps = ViewProps;
+
+const AvatarGroup = forwardRef<BridgeViewRef, AvatarGroupProps>(
+  ({ className, ...props }, ref) => (
+    <AvatarGroupContext.Provider value={true}>
+      <View
+        ref={ref}
+        className={cn("flex flex-row items-center web:-space-x-2", className)}
+        {...props}
+      />
+    </AvatarGroupContext.Provider>
+  ),
+);
+AvatarGroup.displayName = "AvatarGroup";
+
+// ---------------------------------------------------------------------------
+// AvatarGroupCount — 넘친 인원 표시("+9" 등 문자열 children).
+// ---------------------------------------------------------------------------
+export type AvatarGroupCountProps = ViewProps & {
+  children?: ReactNode;
+};
+
+const AvatarGroupCount = forwardRef<BridgeViewRef, AvatarGroupCountProps>(
+  ({ className, children, ...props }, ref) => (
+    <View
+      ref={ref}
+      className={cn(
+        "relative flex size-8 shrink-0 items-center justify-center rounded-full bg-muted ring-2 ring-background",
+        className,
+      )}
+      {...props}
+    >
+      {/* 이중 지정 원칙: 전경색은 내부 Text에 */}
+      <Text className="font-sans text-sm text-muted-foreground">
+        {children}
+      </Text>
+    </View>
+  ),
+);
+AvatarGroupCount.displayName = "AvatarGroupCount";
+
+export {
+  Avatar,
+  AvatarImage,
+  AvatarFallback,
+  AvatarBadge,
+  AvatarGroup,
+  AvatarGroupCount,
+};