moru-krds-react 0.1.0

package/src/pagination/index.tsx

@@ -0,0 +1,198 @@
+import { UiLink } from '../lib/link';
+import type { ComponentPropsWithRef } from 'react';
+import { cx } from '../lib/krds';
+
+/**
+ * 페이지네이션 — KRDS `krds-pagination`.
+ *
+ * 쪽 번호는 **화면에 보이는 그대로 1부터** 센다. 전체 쪽이 1 이하면 아무것도 그리지 않는다.
+ * 쪽이 주소에 실리면 `href`, 상태로만 있으면 `onPageChange` 를 준다(둘 중 하나만).
+ * 전체 쪽을 다 그리지 않고 `maxLinks`(기본 10) 안에서 말줄임으로 줄인다 — 규격 상한은 11 이다.
+ * 여백은 킷이 잡으므로 `mt-*` 를 더하지 마라. 한 화면에 하나만 둔다.
+ *
+ * @example
+ * <Pagination page={page} totalPages={total} href={(p) => `?page=${p}`} label="공지사항 페이지네이션" />
+ * <Pagination page={page} totalPages={total} onPageChange={setPage} maxLinks={7} />
+ *
+ * 자세히: docs/krds/09-부품-노트.md#페이지네이션
+ */
+
+/** 숫자 칸 하나. 숫자이거나 말줄임(`null`)이다. */
+export type PageSlot = number | null;
+
+const range = (from: number, to: number): number[] =>
+  Array.from({ length: to - from + 1 }, (_, i) => from + i);
+
+/**
+ * 그릴 칸을 고른다 — 첫 쪽·마지막 쪽은 항상, 가운데는 현재 쪽 둘레만, 나머지는 말줄임(`null`).
+ * `totalPages > maxLinks` 이면 길이가 정확히 `maxLinks` 다.
+ *
+ * @example
+ * pageSlots(4, 99)  // [1,2,3,4,5,6,7,8,null,99]
+ * pageSlots(50, 99) // [1,null,48,49,50,51,52,53,null,99]
+ */
+export function pageSlots(page: number, totalPages: number, maxLinks = 10): PageSlot[] {
+  const total = Math.max(1, Math.floor(totalPages));
+  const cur = Math.min(Math.max(1, Math.floor(page)), total);
+  // 첫 쪽·말줄임·현재 쪽·말줄임·마지막 쪽 — 최소 5칸은 있어야 한다.
+  const n = Math.max(5, Math.floor(maxLinks));
+
+  if (total <= n) return range(1, total);
+
+  // 가운데 창 = 전체 칸 - (첫·마지막 숫자 2 + 말줄임 2)
+  const win = n - 4;
+  let start = cur - Math.floor((win - 1) / 2);
+  let end = start + win - 1;
+
+  if (start <= 3) {
+    // 앞쪽에 붙었다 — 왼쪽 말줄임이 필요 없으니 창이 한 칸 넓어진다.
+    start = 2;
+    end = start + (n - 3) - 1;
+    return [1, ...range(start, end), null, total];
+  }
+  if (end >= total - 2) {
+    // 뒤쪽에 붙었다.
+    end = total - 1;
+    start = end - (n - 3) + 1;
+    return [1, null, ...range(start, end), total];
+  }
+  return [1, null, ...range(start, end), null, total];
+}
+
+type PaginationBaseProps = {
+  /** 현재 쪽. 화면에 보이는 번호 그대로 1부터 센다. */
+  page: number;
+  /** 전체 쪽수. 1 이하면 아무것도 그리지 않는다. */
+  totalPages: number;
+  /** 말줄임을 포함한 숫자 칸 최대 개수. 기본 10(규격 상한 11, 좁은 화면 권장 7). */
+  maxLinks?: number;
+  /** `<nav>` 의 이름. 「공지사항 페이지네이션」처럼 어떤 목록인지 담는다. */
+  label?: string;
+  /** 이전 단추 글자. */
+  prevLabel?: string;
+  /** 다음 단추 글자. */
+  nextLabel?: string;
+  /** `<nav>` 에 붙일 클래스. */
+  className?: string;
+};
+
+/** 링크 방식(기본). 쪽이 주소에 실릴 때 — 공유·뒤로가기가 되어야 하는 목록. */
+export type PaginationLinkProps = PaginationBaseProps & {
+  /** 1부터 센 쪽 번호를 받아 주소를 돌려준다. 서버가 0부터 세면 여기서 낮춘다. */
+  href: (page: number) => string;
+  onPageChange?: never;
+};
+
+/** 단추 방식. 쪽이 주소에 없고 상태로만 있을 때. 부르는 쪽이 클라이언트 컴포넌트여야 한다. */
+export type PaginationButtonProps = PaginationBaseProps & {
+  /** 쪽을 옮길 때. */
+  onPageChange: (page: number) => void;
+  href?: never;
+};
+
+export type PaginationProps = Omit<ComponentPropsWithRef<'nav'>, 'children' | 'className'> &
+  (PaginationLinkProps | PaginationButtonProps);
+
+/** 위 합집합을 안에서 풀어 쓰기 위한 형태. */
+type ResolvedPaginationProps = PaginationBaseProps &
+  Omit<ComponentPropsWithRef<'nav'>, 'children' | 'className'> & {
+    href?: (page: number) => string;
+    onPageChange?: (page: number) => void;
+  };
+
+export function Pagination(props: PaginationProps) {
+  const {
+    page,
+    totalPages,
+    maxLinks = 10,
+    label = '페이지네이션',
+    prevLabel = '이전',
+    nextLabel = '다음',
+    href,
+    onPageChange,
+    className,
+    ...rest
+  } = props as ResolvedPaginationProps;
+
+  const total = Math.max(0, Math.floor(totalPages));
+  // 규격: 전체 데이터가 적을 때(화면이 하나뿐일 때)는 페이지네이션을 쓰지 않는다.
+  if (total <= 1) return null;
+
+  const cur = Math.min(Math.max(1, Math.floor(page)), total);
+
+  // 현재 쪽만 `href` 를 빼고 `aria-current="true"` 를 준다(규격). 이름은 가이드 예문 그대로다.
+  const renderPage = (n: number) => {
+    if (n === cur) {
+      return (
+        <a className="page-link active" aria-current="true">
+          <span className="sr-only">현재페이지 </span>
+          {n}
+        </a>
+      );
+    }
+    const name = n === total ? `마지막 페이지, ${n}` : `페이지 ${n}`;
+    return href ? (
+      <UiLink className="page-link" href={href(n)} aria-label={name}>
+        {n}
+      </UiLink>
+    ) : (
+      <button type="button" className="page-link" aria-label={name} onClick={() => onPageChange?.(n)}>
+        {n}
+      </button>
+    );
+  };
+
+  // 이전/다음. 끝에 닿으면 킷 샘플대로 `<span class="disabled">` 다.
+  // hover 배경은 킷이 없는 토큰을 참조하는 결함이 있어 킷의 자기 토큰으로 되돌린다.
+  //
+  // `aria-disabled` 를 반드시 붙인다. 킷 글자색이 흐려(#8a949e, 배경 #f4f5f6 위 2.82:1) 그냥 두면
+  // axe 가 「읽으라고 둔 글자인데 대비가 모자라다」로 본다(WCAG 1.4.3). 비활성 컨트롤은 대비 요구에서
+  // 빠지지만, `<span>` 만으로는 「비활성」임을 알릴 방법이 없어 판정에 걸린다 — 실측으로 잡은 것이다.
+  const renderNavi = (dir: 'prev' | 'next') => {
+    const to = dir === 'prev' ? cur - 1 : cur + 1;
+    const text = dir === 'prev' ? prevLabel : nextLabel;
+    const off = dir === 'prev' ? cur <= 1 : cur >= total;
+    if (off) {
+      return (
+        <span
+          aria-disabled="true"
+          className={cx(
+            'page-navi',
+            dir,
+            'disabled',
+            'hover:bg-[var(--krds-pagination--color-action)] active:bg-[var(--krds-pagination--color-action)]',
+          )}
+        >
+          {text}
+        </span>
+      );
+    }
+    return href ? (
+      <UiLink className={cx('page-navi', dir)} href={href(to)}>
+        {text}
+      </UiLink>
+    ) : (
+      <button type="button" className={cx('page-navi', dir)} onClick={() => onPageChange?.(to)}>
+        {text}
+      </button>
+    );
+  };
+
+  return (
+    <nav aria-label={label} className={cx('krds-pagination', className)} {...rest}>
+      {renderNavi('prev')}
+      <ul className="page-links">
+        {pageSlots(cur, total, maxLinks).map((slot, i) => (
+          <li key={slot === null ? `dot-${i}` : slot}>
+            {slot === null ? (
+              <span className="page-link link-dot" aria-hidden="true" />
+            ) : (
+              renderPage(slot)
+            )}
+          </li>
+        ))}
+      </ul>
+      {renderNavi('next')}
+    </nav>
+  );
+}

package/src/progress/index.tsx

@@ -0,0 +1,198 @@
+import type { ComponentPropsWithRef, ReactNode } from 'react';
+import { cx, type KrdsSize, type KrdsTone } from '../lib/krds';
+
+/**
+ * 진행 막대 — 킷에 없다. KRDS 토큰으로 그리는 보충 부품이다.
+ *
+ * **끝이 있는 일의 진행**에 쓴다. 한도 사용량·준수율처럼 오르내리는 값은 {@link Meter} 다
+ * (ARIA 가 둘을 다른 역할로 나눠 두었다). 1초 미만이면 아예 쓰지 않는다.
+ * `value` 를 생략하면 불확정(맥동)이 되고 `aria-valuenow` 가 빠진다.
+ * 진행 자체는 조용히 두고, 알릴 말은 `status`(= `role="status"`)로 보낸다.
+ * 모양을 모르거나 좁은 자리는 `ui/spinner`, 목록·카드 자리는 `ui/skeleton` 이다.
+ *
+ * @example
+ * <Progress label="파일 올리는 중" value={42} status={`3/12 — 「${name}」 처리 중`} />
+ * <Progress label="집계 중" size="small" />
+ * <Meter label="오늘 한도 사용량" value={used} max={quota} valueText={`${used}건 / ${quota}건`} />
+ *
+ * 자세히: docs/krds/09-부품-노트.md#진행상태
+ */
+
+/** 굵기 — 8 / 12 / 16px. KRDS 모서리 표의 프로그레스 바 컨테이너 크기다. */
+export type ProgressSize = Extract<KrdsSize, 'small' | 'medium' | 'large'>;
+
+/** 색. `gray`(solid 토큰 없음)와 `warning`(트랙 대비 1.48:1 로 규격 미달)은 뺐다. */
+export type ProgressTone = Exclude<KrdsTone, 'gray' | 'warning'>;
+
+/** 굵기 → 높이 유틸리티. */
+const SIZE_CLASS: Record<ProgressSize, string> = {
+  small: 'h-2',
+  medium: 'h-3',
+  large: 'h-4',
+};
+
+/** 색 → 채움 유틸리티. 완성된 문자열로 적는다 — 조립하면 Tailwind 가 클래스를 만들지 않는다. */
+const TONE_CLASS: Record<ProgressTone, string> = {
+  primary: 'bg-primary-solid',
+  secondary: 'bg-secondary-solid',
+  point: 'bg-point-solid',
+  danger: 'bg-danger-solid',
+  success: 'bg-success-solid',
+  information: 'bg-information-solid',
+};
+
+/** 트랙. 채움과의 대비를 3:1 위로 올려 두는 값이다. */
+const TRACK_CLASS = 'w-full overflow-hidden rounded-xs bg-surface-subtle';
+
+export type ProgressProps = Omit<ComponentPropsWithRef<'div'>, 'children'> & {
+  /** 무엇의 진행인지. 필수다 — 막대의 `aria-label` 이 되므로 `string` 이어야 한다. */
+  label: string;
+  /** 레이블을 눈에 보이지 않게 한다. 이미 머리글이 있는 자리에서만. */
+  labelHidden?: boolean;
+  /** 현재 값. **생략하면 불확정**(`aria-valuenow` 를 빼고 맥동한다). */
+  value?: number;
+  /** 값의 아래끝. 기본 0. */
+  min?: number;
+  /** 값의 위끝. 기본 100. */
+  max?: number;
+  /** 스크린리더가 읽을 값 문구. 「12개 중 5개 끝남」처럼. 주면 보이는 수치도 이 문구가 된다. */
+  valueText?: string;
+  /** 눈에 보이는 수치를 그린다. 기본 true(불확정이면 그리지 않는다). */
+  showValue?: boolean;
+  /** 굵기. 기본 medium(12px). */
+  size?: ProgressSize;
+  /** 채움 색. 기본 primary. */
+  tone?: ProgressTone;
+  /** 막대 아래 한 줄 설명. `role="status"` 라 바뀌면 스크린리더가 읽어 준다. */
+  status?: ReactNode;
+};
+
+export function Progress({
+  label,
+  labelHidden,
+  value,
+  min = 0,
+  max = 100,
+  valueText,
+  showValue = true,
+  size = 'medium',
+  tone = 'primary',
+  status,
+  className,
+  ...rest
+}: ProgressProps) {
+  const span = max - min;
+  const indeterminate = value === undefined || !Number.isFinite(value);
+
+  if (process.env.NODE_ENV !== 'production') {
+    if (span <= 0) {
+      console.warn(`[Progress] max(${max})가 min(${min})보다 커야 한다. 0% 로 그린다.`);
+    } else if (!indeterminate && (value! < min || value! > max)) {
+      console.warn(
+        `[Progress] value(${value})가 ${min}~${max} 밖이다. 잘라서 그리지만 보이는 값과 계산이 어긋난다.`,
+      );
+    }
+  }
+
+  // 폭은 자르지 않은 소수 그대로, 글자는 반올림. 「보이는 폭 ≠ 읽히는 값」을 만들지 않는다.
+  const ratio = indeterminate || span <= 0 ? 0 : Math.min(1, Math.max(0, (value! - min) / span));
+  const percent = ratio * 100;
+  const readout = valueText ?? `${Math.round(percent)}%`;
+  const showReadout = showValue && !indeterminate;
+
+  return (
+    <div className={cx('w-full', className)} {...rest}>
+      {(!labelHidden || showReadout) && (
+        // 이름과 값은 ARIA 로 이미 준다 — 여기 글자는 눈으로 볼 몫이라 가린다.
+        <div className="mb-2 flex items-baseline justify-between gap-2" aria-hidden="true">
+          {labelHidden ? <span /> : <span className="text-sm text-fg-subtle">{label}</span>}
+          {showReadout && <span className="text-sm font-bold text-fg tabular-nums">{readout}</span>}
+        </div>
+      )}
+
+      <div
+        role="progressbar"
+        aria-label={label}
+        aria-valuemin={min}
+        aria-valuemax={max}
+        // 불확정은 valuenow 를 「빼는 것」이 신호다. 0 을 넣으면 멈춘 0% 가 된다.
+        aria-valuenow={indeterminate ? undefined : Math.min(max, Math.max(min, value!))}
+        aria-valuetext={indeterminate ? undefined : valueText}
+        aria-busy={indeterminate || undefined}
+        className={cx(TRACK_CLASS, SIZE_CLASS[size])}
+      >
+        {indeterminate ? (
+          // 가운데 3분의 1. 움직임을 끈 사용자에게 「가득 찬 채 멈춘 막대」를 남기지 않는다.
+          <div className={cx('mx-auto h-full w-1/3 animate-pulse rounded-xs', TONE_CLASS[tone])} />
+        ) : (
+          <div
+            className={cx('h-full rounded-xs transition-[width]', TONE_CLASS[tone])}
+            style={{ width: `${percent}%` }}
+          />
+        )}
+      </div>
+
+      {status !== undefined && status !== null && (
+        <p className="mt-2 text-sm text-fg-subtle" role="status">
+          {status}
+        </p>
+      )}
+    </div>
+  );
+}
+
+/**
+ * 비율 막대 — `role="meter"`. **진행이 아니라 「지금 얼마」다.**
+ *
+ * 한도 사용량·준수율처럼 오르내릴 수 있고 끝나지 않는 값에 쓴다. 불확정은 없다(`value` 필수).
+ * `role="meter"` 는 스크린리더 지원이 고르지 않으니 `label` 을 값 없이도 뜻이 서는 말로 짓고
+ * 정확한 수치는 `valueText` 로 준다.
+ */
+export type MeterProps = Omit<ProgressProps, 'value' | 'showValue' | 'status'> & {
+  value: number;
+  showValue?: boolean;
+};
+
+export function Meter({
+  label,
+  labelHidden,
+  value,
+  min = 0,
+  max = 100,
+  valueText,
+  showValue = true,
+  size = 'medium',
+  tone = 'primary',
+  className,
+  ...rest
+}: MeterProps) {
+  const span = max - min;
+  const ratio = span <= 0 ? 0 : Math.min(1, Math.max(0, (value - min) / span));
+  const percent = ratio * 100;
+  const readout = valueText ?? `${Math.round(percent)}%`;
+
+  return (
+    <div className={cx('w-full', className)} {...rest}>
+      {(!labelHidden || showValue) && (
+        <div className="mb-2 flex items-baseline justify-between gap-2" aria-hidden="true">
+          {labelHidden ? <span /> : <span className="text-sm text-fg-subtle">{label}</span>}
+          {showValue && <span className="text-sm font-bold text-fg tabular-nums">{readout}</span>}
+        </div>
+      )}
+      <div
+        role="meter"
+        aria-label={label}
+        aria-valuemin={min}
+        aria-valuemax={max}
+        aria-valuenow={Math.min(max, Math.max(min, value))}
+        aria-valuetext={valueText}
+        className={cx(TRACK_CLASS, SIZE_CLASS[size])}
+      >
+        <div
+          className={cx('h-full rounded-xs transition-[width]', TONE_CLASS[tone])}
+          style={{ width: `${percent}%` }}
+        />
+      </div>
+    </div>
+  );
+}

package/src/radio/index.tsx

@@ -0,0 +1,283 @@
+import type { ChangeEvent, ComponentPropsWithRef, ReactNode } from 'react';
+import { cx, type KrdsSize } from '../lib/krds';
+
+/**
+ * 라디오 버튼 — KRDS `krds-form-check` · `krds-form-chip`.
+ *
+ * `name` 을 공유하는 것끼리 한 묶음이 되고 방향키 이동은 브라우저가 한다.
+ * **`<label>` 안에 `<input>` 을 넣으면 동그라미가 아예 안 그려진다** — 이 부품이 그 골격을 강제한다.
+ * 보통은 {@link RadioGroup} 에 `options` 를 넘겨 한 번에 그린다(그래야 `<fieldset>`/`<legend>` 가 붙는다).
+ * 여러 값을 고르는 자리는 `ui/checkbox` 다.
+ *
+ * @example
+ * <RadioGroup label="공개 범위" name="scope" options={[
+ *   { value: 'all', label: '전체 공개' },
+ *   { value: 'org', label: '기관 내부', description: '소속 기관 승인 뒤 열립니다.' },
+ * ]} />
+ * <RadioGroup label="동의" name="agree" chip equalWidth options={[
+ *   { value: 'y', label: '예' }, { value: 'n', label: '아니오' },
+ * ]} />
+ *
+ * 자세히: docs/krds/09-부품-노트.md#라디오
+ */
+
+/** 항목 크기. 킷에 있는 둘뿐이다 — 동그라미 20px / 24px, 글자 17px / 19px. */
+export type RadioSize = Extract<KrdsSize, 'medium' | 'large'>;
+
+/** 칩 크기. 높이 40 / 48 / 56px — 버튼·입력칸과 같은 눈금이라 한 줄에 섞어도 어긋나지 않는다. */
+export type RadioChipSize = Extract<KrdsSize, 'small' | 'medium' | 'large'>;
+
+/** id 를 `name`+`value` 로 만든다. `useId()` 를 쓰면 부품이 클라이언트로 내려가는데 그럴 이유가 없다. */
+function radioId(name: string, value: string): string {
+  return `${name}-${value}`.replace(/\s+/g, '-');
+}
+
+/* ────────────────────────────────────────────────────────────────────────── */
+
+export type RadioProps = Omit<
+  ComponentPropsWithRef<'input'>,
+  'type' | 'size' | 'value' | 'className'
+> & {
+  /** 그룹 이름. 같은 값을 가진 라디오끼리 한 묶음이 되고 방향키가 그 안에서 돈다. */
+  name: string;
+  /** 값. 같은 `name` 안에서 유일해야 한다 — `id` 를 이 값으로 만든다. */
+  value: string;
+  /** `<label>` 에 들어갈 글. */
+  label: ReactNode;
+  /** 부가 설명. 세로 배치와 함께 쓴다. `aria-describedby` 로 이어진다. */
+  description?: ReactNode;
+  /** 크기. 기본 medium. */
+  size?: RadioSize;
+  /** 감싸개 `div.krds-form-check` 에 붙는다(여백 조절은 여기서). */
+  className?: string;
+  /** `<input>` 에 붙는다. */
+  inputClassName?: string;
+};
+
+/** 라디오 한 개. `id` 를 주지 않으면 `name`-`value` 로 만든다. 묶음은 {@link RadioGroup} 이다. */
+export function Radio({
+  name,
+  value,
+  label,
+  description,
+  size = 'medium',
+  className,
+  inputClassName,
+  id,
+  'aria-describedby': describedBy,
+  ...rest
+}: RadioProps) {
+  const inputId = id ?? radioId(name, value);
+  const descId = description ? `${inputId}-desc` : undefined;
+
+  return (
+    <div className={cx('krds-form-check', size, className)}>
+      <input
+        type="radio"
+        id={inputId}
+        name={name}
+        value={value}
+        className={inputClassName}
+        aria-describedby={cx(describedBy, descId) || undefined}
+        {...rest}
+      />
+      <label htmlFor={inputId}>{label}</label>
+      {description ? (
+        // 킷 규칙이 `label + .krds-form-check-cnt` 라 label 바로 다음 형제여야 왼쪽 들여쓰기가 맞는다.
+        <div className="krds-form-check-cnt">
+          <p className="krds-form-check-p" id={descId}>
+            {description}
+          </p>
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * 칩 포커스 테두리. 킷은 JS 가 붙이는 `.focus` 클래스를 전제하는데 그 JS 가 없어
+ * CSS 형제 선택(`peer` / `peer-focus`)으로 같은 그림을 만든다. 값은 킷 토큰 그대로다.
+ */
+const CHIP_FOCUS_RING = 'peer-focus:[box-shadow:var(--krds-box-shadow-outline-inset)]';
+
+export type RadioChipProps = Omit<
+  ComponentPropsWithRef<'input'>,
+  'type' | 'size' | 'value' | 'className'
+> & {
+  /** 그룹 이름. */
+  name: string;
+  /** 값. 같은 `name` 안에서 유일해야 한다. */
+  value: string;
+  /** 칩에 보이는 글. */
+  label: ReactNode;
+  /** 크기. 기본 medium(48px). */
+  size?: RadioChipSize;
+  /** 감싸개 `div.krds-form-chip` 에 붙는다. */
+  className?: string;
+  /** `<input>` 에 붙는다. */
+  inputClassName?: string;
+};
+
+/**
+ * 칩 라디오 — 테두리 알약을 눌러 고른다. 예/아니오처럼 선택지가 짧을 때 쓴다.
+ * 체크 아이콘은 킷이 알아서 켜고 끈다.
+ */
+export function RadioChip({
+  name,
+  value,
+  label,
+  size = 'medium',
+  className,
+  inputClassName,
+  id,
+  ...rest
+}: RadioChipProps) {
+  const inputId = id ?? radioId(name, value);
+
+  return (
+    <div className={cx('krds-form-chip', size, className)}>
+      <input
+        type="radio"
+        // `radio` 는 킷 샘플이 붙이는 클래스다(chip-wrap 안에서 선택자로 쓰인다).
+        className={cx('radio peer', inputClassName)}
+        id={inputId}
+        name={name}
+        value={value}
+        {...rest}
+      />
+      <label className={cx('krds-form-chip-outline', CHIP_FOCUS_RING)} htmlFor={inputId}>
+        {label}
+      </label>
+    </div>
+  );
+}
+
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/** `RadioGroup` 이 직접 그릴 항목. */
+export type RadioOption<T extends string = string> = {
+  /** 값. */
+  value: T;
+  /** 화면에 보이는 글. */
+  label: ReactNode;
+  /** 부가 설명. 하나라도 있으면 세로 배치가 맞는다. */
+  description?: ReactNode;
+  /** 비활성. */
+  disabled?: boolean;
+  /** 기본값은 `name`-`value`. 한 페이지에 같은 `name` 을 두 번 쓸 때만 손으로 준다. */
+  id?: string;
+};
+
+export type RadioGroupProps<T extends string = string> = Omit<
+  ComponentPropsWithRef<'fieldset'>,
+  'onChange' | 'children'
+> & {
+  /** 묶음 이름. `<legend>` 로 들어간다 — 킷이 화면에서 감추지만 스크린리더는 읽는다. */
+  label: ReactNode;
+  /** 소제목을 화면에도 보이게 한다. 사본이라 낭독에서는 빠진다. */
+  labelVisible?: boolean;
+  /** 그룹 이름. 방향키 이동이 이 값을 공유하는 라디오 안에서 돈다. */
+  name: string;
+  /** 항목. 주면 `RadioGroup` 이 직접 그린다. 생략하고 `children` 으로 손수 넣어도 된다. */
+  options?: readonly RadioOption<T>[];
+  /** 통제 컴포넌트로 쓸 때의 현재 값. */
+  value?: T;
+  /** 비통제로 쓸 때의 처음 값. 정확한 값이 중요하면 **기본 선택값을 주지 않는다**(규격). */
+  defaultValue?: T;
+  /** 값이 바뀔 때. */
+  onValueChange?: (value: T) => void;
+  /** 항목 크기. 기본 medium. */
+  size?: RadioSize;
+  /** 칩 크기. 기본 medium. */
+  chipSize?: RadioChipSize;
+  /** 칩 형태로 그린다. */
+  chip?: boolean;
+  /** 배치. 기본은 세로다(규격). 칩은 성질상 가로가 기본. */
+  orientation?: 'vertical' | 'horizontal';
+  /** 칩을 같은 너비로 늘린다(킷 `chip-wrap`). */
+  equalWidth?: boolean;
+  /** `div.krds-check-area` 에 붙는다. `className` 은 바깥 `<fieldset>` 에 붙는다. */
+  areaClassName?: string;
+  children?: ReactNode;
+};
+
+/**
+ * 라디오 묶음 — `fieldset > legend + div.krds-check-area`. 규격이 요구하는 골격이다.
+ *
+ * `disabled` 를 주면 안에 든 라디오가 전부 잠긴다(브라우저 기본 동작).
+ */
+export function RadioGroup<T extends string = string>({
+  label,
+  labelVisible,
+  name,
+  options,
+  value,
+  defaultValue,
+  onValueChange,
+  size = 'medium',
+  chipSize = 'medium',
+  chip,
+  orientation,
+  equalWidth,
+  className,
+  areaClassName,
+  children,
+  ...rest
+}: RadioGroupProps<T>) {
+  const vertical = (orientation ?? (chip ? 'horizontal' : 'vertical')) === 'vertical';
+  const controlled = value !== undefined;
+
+  const handleChange = (e: ChangeEvent<HTMLInputElement>) => {
+    onValueChange?.(e.currentTarget.value as T);
+  };
+
+  return (
+    <fieldset
+      // 브라우저 기본 테두리를 지우고, flex/grid 안에서 줄어들지 못하는 기본값을 푼다.
+      className={cx('border-0 min-w-0', className)}
+      {...rest}
+    >
+      <legend>{label}</legend>
+      {labelVisible ? (
+        // `<legend>` 가 이미 읽히므로 사본은 낭독에서 뺀다.
+        <p className="form-label mb-3" aria-hidden="true">
+          {label}
+        </p>
+      ) : null}
+
+      <div
+        className={cx(
+          'krds-check-area',
+          vertical && 'chk-column',
+          equalWidth && 'chip-wrap',
+          areaClassName,
+        )}
+      >
+        {options?.map((o) => {
+          const common = {
+            name,
+            value: o.value,
+            label: o.label,
+            id: o.id,
+            disabled: o.disabled,
+            onChange: handleChange,
+            ...(controlled
+              ? { checked: o.value === value }
+              : defaultValue !== undefined
+                ? { defaultChecked: o.value === defaultValue }
+                : null),
+          };
+          // key 는 spread 밖에 둔다 — props 객체에 섞으면 React 가 경고한다.
+          return chip ? (
+            <RadioChip key={o.value} {...common} size={chipSize} />
+          ) : (
+            <Radio key={o.value} {...common} size={size} description={o.description} />
+          );
+        })}
+        {children}
+      </div>
+    </fieldset>
+  );
+}