moru-krds-react 0.1.0

package/src/accordion/index.tsx

@@ -0,0 +1,251 @@
+'use client';
+
+import {
+  createContext,
+  useContext,
+  useId,
+  useMemo,
+  useState,
+  type ComponentPropsWithRef,
+  type MouseEvent as ReactMouseEvent,
+  type ReactNode,
+} from 'react';
+import { cx } from '../lib/krds';
+
+/**
+ * 아코디언 — KRDS `krds-accordion`.
+ *
+ * 헤더를 눌러 한 덩이씩 펼쳐 보는 목록. FAQ 는 `line`(킷 `type-line`)이 규격이다 — 표로 그리지 않는다.
+ * 기본은 한 번에 하나만 열리고, `multiple` 을 주면 여러 개가 함께 열린다.
+ * 부가 안내 한 덩이만 접었다 펴려면 `Disclosure` 를, 내용을 갈아 끼우려면 `Tab` 을 쓴다.
+ *
+ * @example
+ * <Accordion.Root line multiple toggleAll headingLevel={3}>
+ *   <Accordion.Item title="신청 자격이 어떻게 되나요?">…</Accordion.Item>
+ *   <Accordion.Item title="처리 기간은 얼마나 걸리나요?" defaultOpen>…</Accordion.Item>
+ * </Accordion.Root>
+ *
+ * 자세히: docs/krds/09-부품-노트.md#아코디언
+ */
+
+/** 헤더 제목의 헤딩 단계. 페이지의 앞선 헤딩보다 한 단계 아래로 준다. */
+export type AccordionHeadingLevel = 2 | 3 | 4 | 5 | 6;
+
+/**
+ * 열림 상태.
+ *
+ * 항목 목록을 부모가 모르고도(등록 절차 없이) 「전체 열기」를 지원하려고 이렇게 잡았다.
+ * - `all: null` — 전체 열기/닫기를 아직 누르지 않았다 → 손대지 않은 항목은 제 `defaultOpen` 을 따른다
+ * - `all: true|false` — 전체 열기/닫기를 눌렀다 → 손대지 않은 항목은 전부 그 값을 따른다
+ * - `touched` — 헤더를 눌러 개별로 손댄 항목만. 언제나 `all` 보다 우선한다
+ */
+type AccordionOpenState = {
+  all: boolean | null;
+  touched: Record<string, boolean>;
+};
+
+type AccordionContextValue = {
+  /** 이 항목이 열려 있나. 손댄 적 없으면 항목 제 `defaultOpen` 이 산다. */
+  isOpen: (key: string, defaultOpen: boolean) => boolean;
+  toggle: (key: string, defaultOpen: boolean) => void;
+  expandAll: () => void;
+  collapseAll: () => void;
+  /** 「전체 열기」를 누른 뒤 하나도 닫지 않은 상태. 전체 단추의 글자를 여기서 고른다. */
+  allOpen: boolean;
+  /** 다중 열림인가(킷 JS 의 `data-type="multiOpen"`). */
+  multiple: boolean;
+  headingLevel: AccordionHeadingLevel;
+};
+
+const AccordionContext = createContext<AccordionContextValue | null>(null);
+
+function useAccordionContext(who: string): AccordionContextValue {
+  const ctx = useContext(AccordionContext);
+  if (!ctx) throw new Error(`${who} 은(는) <Accordion.Root> 안에서만 쓴다.`);
+  return ctx;
+}
+
+export type AccordionRootProps = Omit<ComponentPropsWithRef<'div'>, 'onToggle'> & {
+  /** 여러 항목을 동시에 연다. 기본은 킷과 같은 단일 열림 — 하나를 열면 나머지가 닫힌다. */
+  multiple?: boolean;
+  /** 라인형(`type-line`). 상자 배경 없이 구분선만 남는다. FAQ 목록에 이 모양을 쓴다. */
+  line?: boolean;
+  /** 처음부터 전부 펼친다. `multiple` 일 때만 뜻이 있다. */
+  defaultAllOpen?: boolean;
+  /** 헤더 제목의 헤딩 단계. 기본 `h3`. 페이지의 앞선 헤딩보다 한 단계 아래로 준다. */
+  headingLevel?: AccordionHeadingLevel;
+  /** 목록 위 오른쪽에 「전체 열기 / 전체 닫기」 단추를 그린다. `multiple` 일 때만 그려진다. */
+  toggleAll?: boolean;
+  /** 항목을 열고 닫을 때. 뜻 있는 `id` 를 받으려면 항목마다 `id` 를 직접 준다. */
+  onToggle?: (id: string, open: boolean) => void;
+};
+
+export function AccordionRoot({
+  multiple = false,
+  line,
+  defaultAllOpen,
+  headingLevel = 3,
+  toggleAll,
+  onToggle,
+  className,
+  children,
+  ...rest
+}: AccordionRootProps) {
+  const [state, setState] = useState<AccordionOpenState>(() => ({
+    // 단일 열림에서 「처음부터 전부 펼침」은 성립하지 않는다.
+    all: defaultAllOpen && multiple ? true : null,
+    touched: {},
+  }));
+
+  const value = useMemo<AccordionContextValue>(() => {
+    const isOpen = (key: string, defaultOpen: boolean) =>
+      key in state.touched ? state.touched[key] : (state.all ?? defaultOpen);
+
+    return {
+      isOpen,
+      toggle: (key, defaultOpen) => {
+        const next = !isOpen(key, defaultOpen);
+        setState((prev) =>
+          multiple
+            ? // 다중 열림 — 누른 항목만 뒤집는다. 나머지는 그대로 둔다.
+              { all: prev.all, touched: { ...prev.touched, [key]: next } }
+            : // 단일 열림 — 누른 항목만 남긴다. `all: false` 라서 나머지는 전부 닫힌다.
+              { all: false, touched: { [key]: next } },
+        );
+        onToggle?.(key, next);
+      },
+      expandAll: () => setState({ all: true, touched: {} }),
+      collapseAll: () => setState({ all: false, touched: {} }),
+      allOpen: state.all === true && Object.values(state.touched).every(Boolean),
+      multiple,
+      headingLevel,
+    };
+  }, [state, multiple, headingLevel, onToggle]);
+
+  return (
+    <AccordionContext.Provider value={value}>
+      {toggleAll && multiple && (
+        // 킷에 전체 열기 단추 자리가 없다 — 목록 위 오른쪽에 Tailwind 로 둔다(mb-2 = 8px).
+        <div className="mb-2 flex justify-end">
+          <AccordionToggleAll />
+        </div>
+      )}
+      <div
+        className={cx('krds-accordion', line && 'type-line', className)}
+        // 킷 JS 가 읽던 값. 우리 렌더에는 필요 없지만 DOM 만 봐도 모드를 알 수 있게 남긴다.
+        data-type={multiple ? 'multiOpen' : 'singleOpen'}
+        {...rest}
+      >
+        {children}
+      </div>
+    </AccordionContext.Provider>
+  );
+}
+
+export type AccordionItemProps = Omit<ComponentPropsWithRef<'div'>, 'title'> & {
+  /** 헤더 제목. 헤더 전체가 단추가 된다. */
+  title: ReactNode;
+  /** 처음부터 이 항목을 펼친다. 단일 열림에서는 하나에만 준다. */
+  defaultOpen?: boolean;
+  /** 이 항목만 헤딩 단계를 달리한다. 보통은 `Accordion.Root` 쪽에서 정한다. */
+  headingLevel?: AccordionHeadingLevel;
+  /** 헤더 단추(`btn-accordion`)에 붙일 클래스. */
+  buttonClassName?: string;
+  /** 내용 영역(`accordion-body`)에 붙일 클래스. */
+  bodyClassName?: string;
+};
+
+export function AccordionItem({
+  title,
+  defaultOpen = false,
+  headingLevel,
+  buttonClassName,
+  bodyClassName,
+  id,
+  className,
+  children,
+  ...rest
+}: AccordionItemProps) {
+  const uid = useId();
+  const ctx = useAccordionContext('<Accordion.Item>');
+
+  // 킷 JS 는 `accordionHeader-id-*` / `accordionCollapse-id-*` 를 난수로 만든다.
+  // React 는 `useId()` 가 서버·클라이언트에서 같은 값을 주므로 그것을 쓴다.
+  const key = id ?? uid;
+  const headerId = `${key}-header`;
+  const panelId = `${key}-panel`;
+
+  const open = ctx.isOpen(key, defaultOpen);
+  const Heading = `h${headingLevel ?? ctx.headingLevel}` as 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+
+  return (
+    <div id={id} className={cx('accordion-item', open && 'active', className)} {...rest}>
+      <Heading className="accordion-header">
+        <button
+          type="button"
+          id={headerId}
+          className={cx('btn-accordion', open && 'active', buttonClassName)}
+          aria-expanded={open}
+          aria-controls={panelId}
+          onClick={() => ctx.toggle(key, defaultOpen)}
+        >
+          {title}
+        </button>
+      </Heading>
+      {/* `collapse` 는 킷 CSS 에 규칙이 없다. 킷 마크업과 맞추려고 그대로 둔다.
+          닫힘/열림은 `.accordion-item.active` 가 이 요소의 max-height·visibility 를 바꿔 만든다. */}
+      <div id={panelId} className="accordion-collapse collapse" role="region" aria-labelledby={headerId}>
+        <div className={cx('accordion-body', bodyClassName)}>{children}</div>
+      </div>
+    </div>
+  );
+}
+
+export type AccordionToggleAllProps = Omit<ComponentPropsWithRef<'button'>, 'children'> & {
+  expandLabel?: string;
+  collapseLabel?: string;
+};
+
+/**
+ * 전체 열기 / 전체 닫기 — 킷에 없어 `krds-btn xsmall text` 로 보충한 단추.
+ *
+ * `Accordion.Root` 에 `toggleAll` 을 주면 제자리에 알아서 그려진다. 직접 쓸 때는
+ * `Accordion.Root` 안에 둔다(문맥을 읽는다). 단일 열림에서는 아무것도 그리지 않는다.
+ */
+export function AccordionToggleAll({
+  expandLabel = '전체 열기',
+  collapseLabel = '전체 닫기',
+  className,
+  onClick,
+  ...rest
+}: AccordionToggleAllProps) {
+  const ctx = useAccordionContext('<Accordion.ToggleAll>');
+
+  // 단일 열림에서는 「전체 열기」가 성립하지 않는다.
+  if (!ctx.multiple) return null;
+
+  const handleClick = (event: ReactMouseEvent<HTMLButtonElement>) => {
+    onClick?.(event);
+    if (event.defaultPrevented) return;
+    if (ctx.allOpen) ctx.collapseAll();
+    else ctx.expandAll();
+  };
+
+  return (
+    <button
+      type="button"
+      className={cx('krds-btn xsmall text', className)}
+      onClick={handleClick}
+      {...rest}
+    >
+      {ctx.allOpen ? collapseLabel : expandLabel}
+      <i className={cx('svg-icon ico-angle', ctx.allOpen && 'rotate-180')} aria-hidden="true" />
+    </button>
+  );
+}
+
+export const Accordion = {
+  Root: AccordionRoot,
+  Item: AccordionItem,
+  ToggleAll: AccordionToggleAll,
+};

package/src/alert/index.tsx

@@ -0,0 +1,111 @@
+import type { ComponentPropsWithRef, ReactNode } from 'react';
+import { cx, type KrdsIcon, type KrdsTone } from '../lib/krds';
+
+/**
+ * 인라인 안내 상자 — KRDS 에 없다. shadcn `Alert` 형태에 KRDS 토큰을 입힌 보충 부품이다.
+ *
+ * 본문 흐름 안에서 「이 화면을 쓰기 전에 알아야 할 것」을 한 덩이로 알린다.
+ * 떴다 사라지는 알림은 `Toast`, 폼 필드 하나에 붙는 문구는 `Field` 의 `hint`·`message`,
+ * 재난·장애 배너는 `CriticalAlert` 다 — 그쪽에 이 상자를 갖다 쓰지 마라(규격이 금지한다).
+ * `AlertTitle` · `AlertDescription` 말고 다른 것을 바로 넣지 않는다.
+ *
+ * @example
+ * <Alert tone="information">
+ *   <AlertTitle>열람 신청 전에 확인하세요.</AlertTitle>
+ *   <AlertDescription>비공개 기록물은 소속 기관 승인 뒤에 열립니다.</AlertDescription>
+ * </Alert>
+ * <Alert tone="danger" announce="assertive">
+ *   <AlertTitle>저장하지 못했습니다.</AlertTitle>
+ * </Alert>
+ *
+ * 자세히: docs/krds/09-부품-노트.md#안내상자
+ */
+
+/** 색조. `KrdsTone` 에서 이 상자가 쓰는 다섯만 좁힌 것이다. */
+export type AlertTone = Extract<KrdsTone, 'information' | 'warning' | 'danger' | 'success' | 'gray'>;
+
+/**
+ * 낭독 방식. 생략하면 role 이 없다(늘 떠 있는 안내의 기본값).
+ * `polite` = `role="status"`(새로 나타나는 안내) · `assertive` = `role="alert"`(긴급한 것에만).
+ */
+export type AlertAnnounce = 'polite' | 'assertive';
+
+const ROLE: Record<AlertAnnounce, 'status' | 'alert'> = {
+  polite: 'status',
+  assertive: 'alert',
+};
+
+/**
+ * 색조별 유틸리티. 선 `border-*-line` · 면 `bg-*-surface` · 글자 `text-*` · mask 아이콘 색 `tint`.
+ * 완성된 문자열로 적는다(Tailwind 는 글자 그대로 적힌 클래스만 만든다).
+ */
+const TONE: Record<AlertTone, { box: string; tint: string; icon: KrdsIcon | null }> = {
+  information: {
+    box: 'border-information-line bg-information-surface text-information',
+    tint: 'bg-information',
+    icon: 'information-fill',
+  },
+  // 경고 아이콘은 킷에 없다 — 위 「경고에 아이콘이 없는 것은 일부러다」 참고.
+  warning: { box: 'border-warning-line bg-warning-surface text-warning', tint: 'bg-warning', icon: null },
+  danger: { box: 'border-danger-line bg-danger-surface text-danger', tint: 'bg-danger', icon: 'error-fill' },
+  success: { box: 'border-success-line bg-success-surface text-success', tint: 'bg-success', icon: 'success-fill' },
+  gray: { box: 'border-line bg-surface-subtler text-fg', tint: 'bg-fg', icon: null },
+};
+
+export type AlertProps = Omit<ComponentPropsWithRef<'div'>, 'title'> & {
+  /** 기본 `information`. 선·면·글자색과 기본 아이콘이 여기서 정해진다. */
+  tone?: AlertTone;
+  /** 킷 아이콘 이름(`ico-` 뺀 것). 색조 기본값을 덮는다. `null` 이면 그리지 않는다. */
+  icon?: KrdsIcon | null;
+  /** 낭독 방식. 기본은 role 없음. `assertive`(=`role="alert"`)는 긴급한 것에만. */
+  announce?: AlertAnnounce;
+  /** `AlertTitle` · `AlertDescription` 을 넣는다. */
+  children?: ReactNode;
+};
+
+export function Alert({ tone = 'information', icon, announce, className, children, ...rest }: AlertProps) {
+  const t = TONE[tone];
+  // `undefined` 는 「색조 기본값을 쓴다」, `null` 은 「그리지 않는다」. 둘을 구분해야 한다.
+  const iconName = icon === undefined ? t.icon : icon;
+
+  const iconNode = iconName ? (
+    <i
+      className={cx(
+        'svg-icon',
+        `ico-${iconName}`,
+        // shadcn 이 자식 svg 에 거는 16px + 아래로 2px 자리. 킷 `.svg-icon` 기본이 large 라 줄여야 한다.
+        'col-start-1 row-start-1 size-4 translate-y-0.5',
+        // `-fill` 은 background-image 라 색을 못 바꾼다(함정 1).
+        !iconName.endsWith('-fill') && t.tint,
+      )}
+      aria-hidden="true"
+    />
+  ) : null;
+
+  return (
+    <div
+      role={announce ? ROLE[announce] : undefined}
+      className={cx(
+        'relative grid w-full items-start gap-y-0.5 rounded-lg border border-solid px-4 py-3 text-sm',
+        // 아이콘이 있을 때만 첫 칸이 열린다 — shadcn 의 `has-[>svg]:` 분기를 코드로 옮긴 것.
+        iconNode ? 'grid-cols-[calc(var(--spacing)*4)_1fr] gap-x-3' : 'grid-cols-[0_1fr]',
+        t.box,
+        className,
+      )}
+      {...rest}
+    >
+      {iconNode}
+      {children}
+    </div>
+  );
+}
+
+/** 안내 제목 한 줄. 둘째 칸에 놓인다. 색은 상자에서 물려받는다. */
+export function AlertTitle({ className, ...rest }: ComponentPropsWithRef<'div'>) {
+  return <div className={cx('col-start-2 min-h-4 font-bold', className)} {...rest} />;
+}
+
+/** 안내 본문. 여러 줄·목록을 넣어도 `gap-1` 로 벌어진다. 색은 상자에서 물려받는다. */
+export function AlertDescription({ className, ...rest }: ComponentPropsWithRef<'div'>) {
+  return <div className={cx('col-start-2 grid justify-items-start gap-1 text-sm', className)} {...rest} />;
+}

package/src/avatar/index.tsx

@@ -0,0 +1,272 @@
+import type { ComponentPropsWithRef } from 'react';
+import { cx, type KrdsSize, type KrdsTone } from '../lib/krds';
+
+/**
+ * 아바타(사용자 표식) — KRDS 킷에 없다. KRDS 토큰을 입힌 보충 부품이다.
+ *
+ * 사람 이름 옆에 놓아 목록에서 행을 구분한다. 스스로 누를 수 없는 `<span>` 이다 —
+ * 누르는 일은 감싸는 `<Link>`·`<button>` 이 한다.
+ * 이름이 곁에 이미 적혀 있으면 `decorative` 를 켠다(안 켜면 이름이 두 번 읽힌다).
+ * 여러 사람을 겹쳐 늘어놓을 때는 `AvatarGroup` 을 쓴다.
+ *
+ * @example
+ * <Avatar name="홍길동" />
+ * <Avatar name="홍길동" src="/files/1.jpg" size="small" />
+ * <span className="flex items-center gap-2">
+ *   <Avatar name={p.author} size="xsmall" decorative /> {p.author}
+ * </span>
+ * <AvatarGroup label="참여자" items={members} max={4} />
+ *
+ * 자세히: docs/krds/09-부품-노트.md#아바타
+ */
+
+/** 채움 방식. 킷 배지의 `bg-light-*` · `bg-*` 짝을 유틸리티로 옮긴 것이다. */
+export type AvatarFill = 'light' | 'solid';
+
+/**
+ * 크기 → 상자·글자·아이콘·겹침. 상자 높이는 버튼·입력칸과 같은 눈금이고 글자는 레이블 축이다.
+ * 아이콘은 상자의 절반, 겹침 폭은 원의 1/4쯤이다.
+ */
+const SIZE: Record<KrdsSize, { box: string; text: string; icon: string; overlap: string }> = {
+  xsmall: { box: 'size-8', text: 'text-label-xs', icon: 'size-4', overlap: '-ml-2' }, // 32 / 13 / 16
+  small: { box: 'size-10', text: 'text-label-sm', icon: 'size-5', overlap: '-ml-2' }, // 40 / 15 / 20
+  medium: { box: 'size-12', text: 'text-label-md', icon: 'size-6', overlap: '-ml-3' }, // 48 / 17 / 24
+  large: { box: 'size-14', text: 'text-label-lg', icon: 'size-7', overlap: '-ml-4' }, // 56 / 19 / 28
+  xlarge: { box: 'size-16', text: 'text-label-lg', icon: 'size-8', overlap: '-ml-4' }, // 64 / 19 / 32
+};
+
+/**
+ * 옅은 채움. 킷 배지 `bg-light-*` 와 같은 색 짝이다(대비를 킷이 이미 검증했다).
+ * 완성된 문자열로 적는다 — Tailwind 는 글자 그대로 적힌 클래스만 만든다.
+ */
+const TONE_LIGHT: Record<KrdsTone, string> = {
+  primary: 'bg-primary-surface text-primary',
+  secondary: 'bg-secondary-surface text-secondary',
+  gray: 'bg-surface-subtle text-fg-subtle',
+  point: 'bg-point-surface text-point',
+  danger: 'bg-danger-surface text-danger',
+  warning: 'bg-warning-surface text-warning',
+  success: 'bg-success-surface text-success',
+  information: 'bg-information-surface text-information',
+};
+
+/**
+ * 꽉 찬 채움. 킷 배지 `bg-*`(element 바탕 + 흰 글자)와 같은 짝이다.
+ * gray 만 solid 토큰이 없어 `bg-fg-subtle` 로 잇는다.
+ */
+const TONE_SOLID: Record<KrdsTone, string> = {
+  primary: 'bg-primary-solid text-fg-inverse',
+  secondary: 'bg-secondary-solid text-fg-inverse',
+  gray: 'bg-fg-subtle text-fg-inverse',
+  point: 'bg-point-solid text-fg-inverse',
+  danger: 'bg-danger-solid text-fg-inverse',
+  warning: 'bg-warning-solid text-fg-inverse',
+  success: 'bg-success-solid text-fg-inverse',
+  information: 'bg-information-solid text-fg-inverse',
+};
+
+/** 한글 — 완성형 가나다(AC00~D7A3)와 호환 자모(3131~318E). */
+const HANGUL = /[ㄱ-ㆎ가-힣]/;
+
+/**
+ * 이름에서 이니셜을 뽑는다. 한글은 성 한 글자, 서양식 이름은 첫 두 낱말의 머리글자다.
+ *
+ * @example
+ * avatarInitials('홍길동')       // '홍'
+ * avatarInitials('남궁 민수')    // '남'
+ * avatarInitials('Hong Gildong') // 'HG'
+ * avatarInitials('gildong')      // 'G'
+ */
+export function avatarInitials(name: string): string {
+  const words = name.trim().split(/\s+/).filter(Boolean);
+  const first = Array.from(words[0] ?? '')[0] ?? '';
+  if (!first) return '';
+  if (HANGUL.test(first)) return first;
+  const second = words.length > 1 ? (Array.from(words[1] ?? '')[0] ?? '') : '';
+  return (first + second).toUpperCase();
+}
+
+type AvatarBase = {
+  /** 기본 medium(48px). 같은 줄의 버튼·입력칸과 **같은 값**을 준다. */
+  size?: KrdsSize;
+  /** 기본 gray. 뜻이 있을 때만 다른 색을 준다 — 이름 해시로 색을 흩뿌리지 않는다. */
+  tone?: KrdsTone;
+  fill?: AvatarFill;
+  /** 프로필 사진 주소. 불러오기에 실패하면 밑의 이니셜이 드러난다. */
+  src?: string;
+  /** 이니셜을 직접 준다. 생략하면 `name` 에서 뽑는다. */
+  initials?: string;
+  /** 겹쳐 놓을 때 서로 떨어져 보이도록 바탕색 테두리를 두른다. `AvatarGroup` 이 켜 준다. */
+  bordered?: boolean;
+  className?: string;
+};
+
+/** 아바타 하나가 사람을 대신하는 자리. 보조기술이 이름을 읽는다. */
+export type AvatarProps = Omit<ComponentPropsWithRef<'span'>, 'children'> &
+  AvatarBase & {
+    decorative?: false;
+    /** 사람 이름. 이니셜과 보조기술 이름이 여기서 나온다. */
+    name: string;
+    /** 읽을 문구를 이름과 다르게 하고 싶을 때(예: `홍길동 (관리자)`). */
+    label?: string;
+  };
+
+/** 곁에 이름이 이미 적혀 있는 자리. 보조기술에서 감춘다(이름이 두 번 읽히지 않게). */
+export type DecorativeAvatarProps = Omit<ComponentPropsWithRef<'span'>, 'children'> &
+  AvatarBase & {
+    decorative: true;
+    /** 이니셜을 뽑는 데만 쓴다. 읽히지는 않는다. */
+    name?: string;
+  };
+
+/** 두 갈래를 한 번에 꺼내기 위한 내부 형. 밖으로 내보내지 않는다. */
+type AvatarAnyProps = Omit<ComponentPropsWithRef<'span'>, 'children'> &
+  AvatarBase & { decorative?: boolean; name?: string; label?: string };
+
+/**
+ * 사용자 표식 하나. 이니셜을 깔고 `src` 가 있으면 그 위에 사진을 덮는다.
+ * 이름도 이미지도 없으면 킷 아이콘 `ico-my` 를 그린다(비회원 글 등).
+ *
+ * @example
+ * <Avatar name="홍길동" size="small" src={user.photo} />
+ */
+export function Avatar(props: AvatarProps | DecorativeAvatarProps) {
+  const {
+    size = 'medium',
+    tone = 'gray',
+    fill = 'light',
+    src,
+    initials,
+    bordered,
+    decorative = false,
+    name,
+    label,
+    className,
+    ...rest
+  } = props as AvatarAnyProps;
+
+  const metric = SIZE[size];
+  const text = initials ?? (name ? avatarInitials(name) : '');
+
+  return (
+    <span
+      // 장식용이면 통째로 감춘다. 아니면 그림 하나로 읽히고 이름은 aria-label 이 준다.
+      role={decorative ? undefined : 'img'}
+      aria-label={decorative ? undefined : (label ?? name)}
+      aria-hidden={decorative ? true : undefined}
+      className={cx(
+        // relative/overflow-hidden — 사진을 원 안에 가둔다. shrink-0 — 좁은 flex 줄에서 눌려 찌그러지지 않게.
+        'relative inline-flex shrink-0 select-none items-center justify-center overflow-hidden rounded-full align-middle font-bold leading-none',
+        metric.box,
+        metric.text,
+        fill === 'solid' ? TONE_SOLID[tone] : TONE_LIGHT[tone],
+        // ★ 함정 4 — outline-solid 를 빼면 폭만 있고 선이 없을 수 있다
+        bordered && 'outline-2 outline-solid outline-bg',
+        className,
+      )}
+      {...rest}
+    >
+      {text ? (
+        // role="img" 는 자손을 읽지 않지만, 그 규칙을 안 지키는 보조기술이 있어 명시해 둔다.
+        <span aria-hidden="true">{text}</span>
+      ) : (
+        <i className={cx('svg-icon ico-my bg-current', metric.icon)} aria-hidden="true" />
+      )}
+      {src && (
+        /* 이니셜 위에 덮는다. 실패하면 아무것도 안 그려져 밑의 이니셜이 드러난다(함정 2).
+           프레임워크의 이미지 부품이 아니라 맨 `<img>` 다 — 프로필 사진은 기관이 올린 파일이라 호스트가
+           미리 정해져 있지 않다. 저장소 eslint 설정이 `no-img-element` 를 경고로 낮춰 둔 이유가 이것이다. */
+        <img
+          src={src}
+          alt=""
+          loading="lazy"
+          decoding="async"
+          className="absolute inset-0 size-full object-cover"
+        />
+      )}
+    </span>
+  );
+}
+
+/** 묶음에 넣을 한 사람. */
+export type AvatarGroupItem = {
+  name: string;
+  src?: string;
+  tone?: KrdsTone;
+  /** 읽을 문구를 이름과 다르게 할 때. */
+  label?: string;
+};
+
+export type AvatarGroupProps = Omit<ComponentPropsWithRef<'ul'>, 'children'> & {
+  items: AvatarGroupItem[];
+  /** 몇 칸까지 보일지. 나머지는 `+N` 한 칸으로 접는다. 기본 4. */
+  max?: number;
+  /** 기본 small(40px) — 목록 안에 들어가는 일이 많아 하나짜리보다 작다. */
+  size?: KrdsSize;
+  fill?: AvatarFill;
+  /** 모든 칸의 기본 색. 항목이 `tone` 을 주면 그것이 이긴다. */
+  tone?: KrdsTone;
+  /** 겹치지 않고 나란히 놓는다. */
+  spaced?: boolean;
+  /** 묶음 전체의 이름(`<ul>` 의 aria-label). 예: 「참여자」 */
+  label?: string;
+};
+
+/**
+ * 아바타 묶음 — 담당자·참여자를 겹쳐 늘어놓는다.
+ *
+ * `children` 이 아니라 `items` 를 받는다. 겹침 간격·테두리·`+N` 칸을 묶음이 정해야 하기 때문이다.
+ * `<ul>/<li>` 라 스크린리더가 개수를 세어 준다 — 각 칸의 이름도 그대로 읽힌다.
+ *
+ * @example
+ * <AvatarGroup label="참여자" items={members} max={4} />
+ */
+export function AvatarGroup({
+  items,
+  max = 4,
+  size = 'small',
+  fill = 'light',
+  tone = 'gray',
+  spaced,
+  label,
+  className,
+  ...rest
+}: AvatarGroupProps) {
+  // 0·음수·소수를 막는다. 부모가 화면 폭에서 계산한 값을 그대로 넘기는 일이 흔하다.
+  const limit = Math.max(1, Math.trunc(max) || 1);
+  const shown = items.slice(0, limit);
+  const rest_ = items.length - shown.length;
+  const step = spaced ? 'ml-2' : SIZE[size].overlap;
+
+  return (
+    <ul aria-label={label} className={cx('flex items-center', className)} {...rest}>
+      {shown.map((it, i) => (
+        <li key={`${it.name}-${i}`} className={cx('shrink-0 first:ml-0', step)}>
+          <Avatar
+            name={it.name}
+            label={it.label}
+            src={it.src}
+            size={size}
+            fill={fill}
+            tone={it.tone ?? tone}
+            bordered
+          />
+        </li>
+      ))}
+      {rest_ > 0 && (
+        <li className={cx('shrink-0 first:ml-0', step)}>
+          {/* 화면에는 `+3`, 보조기술에는 「외 3명」. 숫자는 tabular-nums 로 폭을 고정한다. */}
+          <Avatar
+            name={`외 ${rest_}명`}
+            initials={`+${rest_}`}
+            size={size}
+            fill={fill}
+            tone="gray"
+            bordered
+            className="tabular-nums"
+          />
+        </li>
+      )}
+    </ul>
+  );
+}