moru-krds-react 0.1.0

package/src/badge/index.tsx

@@ -0,0 +1,91 @@
+import type { ComponentPropsWithRef } from 'react';
+import { cx, type KrdsTone } from '../lib/krds';
+
+/**
+ * 배지 — KRDS `krds-badge`.
+ *
+ * 상태·분류를 한 낱말로 표시한다. 누르는 것이 아니다 —
+ * 필터 조건처럼 누르거나 지우는 표시는 `ui/tag` 의 `Tag` · `TagButton` 이다.
+ * 여럿을 늘어놓을 때는 `BadgeWrap` 으로 감싼다(간격은 킷이 잡는다).
+ *
+ * @example
+ * <Badge tone="success">승인</Badge>
+ * <Badge tone="primary" fill="solid" number>5</Badge>
+ * <BadgeWrap>
+ *   <Badge tone="danger">반려</Badge>
+ *   <Badge tone="gray">보관</Badge>
+ * </BadgeWrap>
+ *
+ * 자세히: docs/krds/09-부품-노트.md#배지
+ */
+
+/** 채움 방식. 킷 클래스는 각각 `bg-*` · `bg-light-*` · `outline-*`. */
+export type BadgeFill = 'solid' | 'light' | 'outline';
+
+/** 배지 크기. 킷에 규칙이 있는 것은 `large` 하나뿐이라 그것만 연다. */
+export type BadgeSize = 'large';
+
+export type BadgeProps = ComponentPropsWithRef<'span'> & {
+  /** 색조. 기본 `gray`. */
+  tone?: KrdsTone | 'disabled';
+  /** 채움 방식. 기본 `light`. */
+  fill?: BadgeFill;
+  /** 크기. 생략하면 킷 기본 크기. */
+  size?: BadgeSize;
+  /** 숫자 배지(`number`). 알림 개수처럼 수를 담을 때. */
+  number?: boolean;
+  /** 점 배지(`dot`). 글자 없이 점만 찍는다 — 곁에 `sr-only` 설명이나 부모 `aria-label` 이 필요하다. */
+  dot?: boolean;
+};
+
+const FILL_PREFIX: Record<BadgeFill, string> = {
+  solid: 'bg-',
+  light: 'bg-light-',
+  outline: 'outline-',
+};
+
+export function Badge({
+  tone = 'gray',
+  fill = 'light',
+  size,
+  number,
+  dot,
+  className,
+  children,
+  ...rest
+}: BadgeProps) {
+  return (
+    <span
+      className={cx(
+        'krds-badge',
+        size,
+        `${FILL_PREFIX[fill]}${tone}`,
+        number && 'number',
+        dot && 'dot',
+        className,
+      )}
+      {...rest}
+    >
+      {children}
+    </span>
+  );
+}
+
+/**
+ * 배지 묶음 — 킷 `krds-badge-wrap`.
+ *
+ * 배지를 여럿 늘어놓을 때 간격을 킷이 잡아 준다. `ml-*` 를 손으로 붙이지 않는다.
+ *
+ * @example
+ * <BadgeWrap>
+ *   <Badge tone="primary">공지</Badge>
+ *   <Badge tone="gray">보관</Badge>
+ * </BadgeWrap>
+ */
+export function BadgeWrap({ className, children, ...rest }: ComponentPropsWithRef<'div'>) {
+  return (
+    <div className={cx('krds-badge-wrap', className)} {...rest}>
+      {children}
+    </div>
+  );
+}

package/src/breadcrumb/index.tsx

@@ -0,0 +1,125 @@
+import { UiLink } from '../lib/link';
+import type { ComponentPropsWithRef, ReactNode } from 'react';
+import { cx } from '../lib/krds';
+
+/**
+ * 브레드크럼 — KRDS `krds-breadcrumb-wrap`.
+ *
+ * 홈은 부품이 늘 앞에 붙이므로 `items` 에는 **홈 다음부터**의 경로만 넣는다.
+ * 주소가 없는 칸(`href` 생략)은 링크가 아니라 계층 표시로만 그려진다.
+ * 메인·랜딩 화면과 1수준 사이트에는 쓰지 않는다 — `items` 가 비면 아무것도 그리지 않는다.
+ * 여백은 킷이 잡으므로 `mb-*` 를 더하지 마라.
+ *
+ * @example
+ * <Breadcrumb
+ *   items={[
+ *     { label: '정보공개', href: '/open' },
+ *     { label: '사전정보공표' },
+ *   ]}
+ * />
+ *
+ * 자세히: docs/krds/09-부품-노트.md#브레드크럼
+ */
+
+/** 경로 한 칸. */
+export type BreadcrumbItem = {
+  /** 화면에 보이는 이름. */
+  label: ReactNode;
+  /** 이동 주소. 없으면 링크로 그리지 않는다 — 마지막 칸은 현재 화면, 가운데 칸은 흐린 글자가 된다. */
+  href?: string;
+  /** 바깥 주소 — `UiLink` 대신 맨 `<a>` 로 그린다. */
+  external?: boolean;
+};
+
+export type BreadcrumbProps = Omit<ComponentPropsWithRef<'nav'>, 'children'> & {
+  /** 홈 다음부터의 경로. 홈은 부품이 늘 앞에 붙인다. */
+  items: BreadcrumbItem[];
+  /** 홈 칸 이름. 다국어는 화면에서 넘긴다. */
+  homeLabel?: string;
+  /** 홈 칸 주소. */
+  homeHref?: string;
+  /** `<nav>` 의 이름. 기본 「현재 경로」(킷 샘플 문구). */
+  label?: string;
+  /** PC 에서 보일 최대 칸 수 — 홈 포함. 기본 4. 넘으면 말줄임으로 줄이되 계층은 `sr-only` 로 남는다. */
+  maxItems?: number;
+  className?: string;
+};
+
+export function Breadcrumb({
+  items,
+  homeLabel = '홈',
+  homeHref = '/',
+  label = '현재 경로',
+  maxItems = 4,
+  className,
+  ...rest
+}: BreadcrumbProps) {
+  // 규격: 메인 화면에는 브레드크럼을 쓰지 않는다. 홈 하나만 남는 경우가 그것이다.
+  if (!items.length) return null;
+
+  // 홈 한 칸은 반드시 남으므로 최소 2. 뒤에 남길 칸 수 = 상한 - 홈.
+  const max = Math.max(2, Math.floor(maxItems));
+  const tail = max - 1;
+  // 홈까지 세어 상한을 넘으면 줄인다. 예) 상한 4 · items 4개 → 홈 · … · 뒤 3개.
+  const collapsed = items.length > tail;
+  const hidden = collapsed ? items.slice(0, items.length - tail) : [];
+  const shown = collapsed ? items.slice(items.length - tail) : items;
+
+  const crumb = (item: BreadcrumbItem, key: string, isLast: boolean, offscreen: boolean) => {
+    const { label: text, href, external } = item;
+
+    // 주소가 없으면 `<span class="txt">` 다(킷의 `a.txt.disabled` 는 밑줄이 남아 쓰지 않는다).
+    // 흐린 글자색만 보충한다 — 배경·둥글기·여백은 `li .txt` 가 span 에도 걸어 준다.
+    const inner = href ? (
+      external ? (
+        <a className="txt" href={href}>
+          {text}
+        </a>
+      ) : (
+        <UiLink className="txt" href={href}>
+          {text}
+        </UiLink>
+      )
+    ) : (
+      <span
+        // 링크가 아닌 중간 단계. `text-fg-disabled`(#8a949e, 흰 바탕 3.08:1)는 **비활성 컨트롤 전용**이라
+        // 읽으라고 둔 글자에 쓰면 WCAG 1.4.3(4.5:1) 위반이다 — axe 실측으로 걸렸다. 흐리게는 `subtle`(8.68:1)로.
+        className={cx('txt', !isLast && 'text-fg-subtle')}
+        aria-current={isLast ? 'page' : undefined}
+      >
+        {text}
+      </span>
+    );
+
+    return (
+      <li key={key} className={cx(offscreen && 'sr-only')}>
+        {inner}
+      </li>
+    );
+  };
+
+  return (
+    <nav className={cx('krds-breadcrumb-wrap', className)} aria-label={label} {...rest}>
+      <ol className="breadcrumb">
+        {/* 홈 — 집 아이콘은 킷이 `.home .txt::before` 로 그린다. */}
+        <li className="home">
+          <UiLink className="txt" href={homeHref}>
+            {homeLabel}
+          </UiLink>
+        </li>
+
+        {hidden.map((item, i) => crumb(item, `hidden-${i}`, false, true))}
+
+        {collapsed && (
+          // PC 말줄임 칸. 킷에는 PC 용 말줄임 규칙이 없어 `ico-ellipsis` 로 직접 그린다.
+          // 계층은 위의 `sr-only` 칸들이 읽어 주므로 이 칸은 장식이다.
+          <li aria-hidden="true">
+            <i className="svg-icon ico-ellipsis size-4" />
+          </li>
+        )}
+
+        {shown.map((item, i) => crumb(item, `shown-${i}`, i === shown.length - 1, false))}
+      </ol>
+    </nav>
+  );
+}

package/src/button/index.tsx

@@ -0,0 +1,190 @@
+import type { ComponentPropsWithRef, ReactNode } from 'react';
+import { cx, type KrdsIcon, type KrdsSize } from '../lib/krds';
+
+/**
+ * 버튼 — KRDS `krds-btn`.
+ *
+ * 이동은 `LinkButton`, 동작은 `Button` 을 쓴다(규격상 다른 것이다).
+ * 같은 줄의 입력칸과 같은 `size` 를 준다(기본 medium · 48px).
+ * 글자 없이 아이콘만 두려면 `iconOnly` 와 `label` 을 함께 준다.
+ * 버튼 여럿은 `ButtonGroup` 으로 묶는다 — 제출은 가장 오른쪽이다.
+ *
+ * @example
+ * <Button variant="primary">저장</Button>
+ * <Button size="small" variant="secondary" icon="down">내려받기</Button>
+ * <Button iconOnly icon="sch" label="검색" />
+ * <LinkButton href="/notice" icon="angle" iconDirection="right">공지 전체보기</LinkButton>
+ *
+ * 자세히: docs/krds/09-부품-노트.md#버튼
+ */
+
+/** 위계. 한 화면에 최상위 강조(`primary`)는 하나만 둔다. */
+export type ButtonVariant = 'primary' | 'secondary' | 'tertiary' | 'text' | 'link';
+
+type BaseProps = {
+  /** 기본 medium(48px). 같은 줄의 입력칸과 같은 값을 준다. */
+  size?: KrdsSize;
+  /** 위계. 생략하면 킷 기본 버튼. */
+  variant?: ButtonVariant;
+  /** 킷 아이콘 이름(`ico-` 뺀 것). 예: `sch` · `down` · `go` */
+  icon?: KrdsIcon;
+  /** 아이콘 회전. 방향은 이름의 일부가 아니라 별도 클래스다 — `icon="angle right"` 로 쓰지 마라. */
+  iconDirection?: 'up' | 'down' | 'left' | 'right';
+  /** 아이콘 위치. 기본 `end` — 킷 샘플은 xlarge 만 앞에 둔다. */
+  iconPosition?: 'start' | 'end';
+  /** 테두리 있는 아이콘 버튼(`krds-btn icon border`). iconOnly 일 때만 뜻이 있다. */
+  bordered?: boolean;
+  className?: string;
+  children?: ReactNode;
+};
+
+export type ButtonProps = Omit<ComponentPropsWithRef<'button'>, 'children'> &
+  BaseProps & {
+    /** 글자 없이 아이콘만 두려면 `true` 와 함께 `label`·`icon` 을 준다({@link IconButtonProps}). */
+    iconOnly?: false;
+  };
+
+export type IconButtonProps = Omit<ComponentPropsWithRef<'button'>, 'children'> &
+  BaseProps & {
+    iconOnly: true;
+    /** 스크린리더가 읽을 이름. 아이콘 버튼에는 반드시 있어야 한다. */
+    label: string;
+    icon: KrdsIcon;
+  };
+
+export function Button(props: ButtonProps | IconButtonProps) {
+  const {
+    size = 'medium',
+    variant,
+    icon,
+    iconDirection,
+    iconPosition = 'end',
+    bordered,
+    className,
+    children,
+    type = 'button',
+    ...rest
+  } = props as ButtonProps & Partial<IconButtonProps>;
+
+  const iconOnly = 'iconOnly' in props && props.iconOnly === true;
+  const label = 'label' in props ? props.label : undefined;
+
+  const cls = cx(
+    'krds-btn',
+    size,
+    variant,
+    iconOnly && 'icon',
+    iconOnly && bordered && 'border',
+    className,
+  );
+
+  const iconNode = icon ? (
+    <i className={cx(`svg-icon ico-${icon}`, iconDirection)} aria-hidden="true" />
+  ) : null;
+
+  return (
+    <button type={type} className={cls} {...rest}>
+      {iconOnly ? (
+        <>
+          <span className="sr-only">{label}</span>
+          {iconNode}
+        </>
+      ) : (
+        <>
+          {iconPosition === 'start' && iconNode}
+          {children}
+          {iconPosition === 'end' && iconNode}
+        </>
+      )}
+    </button>
+  );
+}
+
+/**
+ * 링크 — KRDS `krds-btn link`. **이동에만 쓴다**(동작은 `Button`).
+ *
+ * 밑줄은 킷이 안쪽 `<span class="underline">` 에 건다 — `hiddenUnderline` · `noUnderline` 로 끈다.
+ * `target="_blank"` 면 「새 창 열림」 안내가 `title` 로 붙는다.
+ */
+export type LinkButtonProps = Omit<ComponentPropsWithRef<'a'>, 'children'> &
+  // `variant`·`bordered` 는 버튼 전용이라 뺀다 — 안 빼면 `<a variant="primary">` 로 새어 나간다.
+  Omit<BaseProps, 'variant' | 'bordered'> & {
+    /** `basic` = 본문 글자색 링크 · `pure` = 가상클래스에서도 색 유지 */
+    linkStyle?: 'basic' | 'pure';
+    /** 비활성. 킷 클래스 `.disabled` + `aria-disabled` 로 알린다. 이동까지 막으려면 `href` 를 빼라. */
+    disabled?: boolean;
+    /** 밑줄을 평소엔 감추고 hover/focus 에서만 보인다(`hidden-underline`). */
+    hiddenUnderline?: boolean;
+    /** 밑줄 자체를 쓰지 않는다. 킷 샘플의 「밑줄 없음」 형태. */
+    noUnderline?: boolean;
+  };
+
+export function LinkButton({
+  size = 'medium',
+  icon,
+  iconDirection,
+  iconPosition = 'end',
+  linkStyle,
+  hiddenUnderline,
+  noUnderline,
+  disabled,
+  className,
+  children,
+  target,
+  title,
+  ...rest
+}: LinkButtonProps) {
+  const cls = cx('krds-btn', size, 'link', linkStyle, disabled && 'disabled', className);
+  const iconNode = icon ? (
+    <i className={cx(`svg-icon ico-${icon}`, iconDirection)} aria-hidden="true" />
+  ) : null;
+
+  return (
+    <a
+      className={cls}
+      aria-disabled={disabled || undefined}
+      target={target}
+      // 새 창으로 열리면 미리 알린다 — KRDS 접근성 요구.
+      title={title ?? (target === '_blank' ? '새 창 열림' : undefined)}
+      {...rest}
+    >
+      {iconPosition === 'start' && iconNode}
+      {noUnderline ? (
+        <span>{children}</span>
+      ) : (
+        <span className={cx('underline', hiddenUnderline && 'hidden-underline')}>{children}</span>
+      )}
+      {iconPosition === 'end' && iconNode}
+    </a>
+  );
+}
+
+/**
+ * 버튼 묶음 — 킷 `btn-group`. 기본 오른쪽 정렬이고 **제출 버튼이 가장 오른쪽**이다.
+ *
+ * @example
+ * <ButtonGroup>
+ *   <Button variant="tertiary">취소</Button>
+ *   <Button variant="primary" type="submit">제출</Button>
+ * </ButtonGroup>
+ */
+export function ButtonGroup({
+  align = 'end',
+  className,
+  children,
+  ...rest
+}: ComponentPropsWithRef<'div'> & { align?: 'start' | 'center' | 'end' | 'between' }) {
+  const justify =
+    align === 'start'
+      ? 'justify-start'
+      : align === 'center'
+        ? 'justify-center'
+        : align === 'between'
+          ? 'justify-between'
+          : 'justify-end';
+  return (
+    <div className={cx('btn-group flex flex-wrap items-center gap-2', justify, className)} {...rest}>
+      {children}
+    </div>
+  );
+}

package/src/checkbox/index.tsx

@@ -0,0 +1,247 @@
+import type { ComponentPropsWithRef, ReactNode, Ref } from 'react';
+import { cx, type KrdsSize } from '../lib/krds';
+
+/**
+ * 체크박스 — KRDS `krds-form-check` · `krds-check-area` · `krds-form-chip`.
+ *
+ * `id` 가 필수다 — 킷이 `input ~ label` 형제 선택자로 네모를 그려서 `<label for>` 로만 이을 수 있다.
+ * **`<label>` 안에 `<input>` 을 넣으면 네모가 아예 안 그려진다.**
+ * 여러 개는 `CheckArea`(배치만) 나 `CheckboxGroup`(fieldset + legend + 도움말)으로 묶는다.
+ * 한 값만 고르는 자리는 `ui/radio`, 검색 필터처럼 알약 꼴이 필요하면 `CheckboxChip` 이다.
+ *
+ * @example
+ * <CheckboxGroup legend="수신 동의" hint="언제든 해지할 수 있습니다.">
+ *   <Checkbox id="agree-sms" name="agree" value="sms" label="문자" />
+ *   <Checkbox id="agree-mail" name="agree" value="mail" label="이메일" description="주 1회 발송" />
+ * </CheckboxGroup>
+ * <Checkbox id="agree-all" label="전체 선택" indeterminate={some} />
+ *
+ * 자세히: docs/krds/09-부품-노트.md#체크박스
+ */
+
+/** 체크박스 크기. 킷에 있는 둘뿐이다 — 네모 20px / 24px, 글자 17px / 19px. */
+export type CheckboxSize = Extract<KrdsSize, 'medium' | 'large'>;
+
+/** 칩 크기. 킷에 있는 셋. 높이가 버튼·입력칸과 같은 눈금이다. */
+export type CheckboxChipSize = Extract<KrdsSize, 'small' | 'medium' | 'large'>;
+
+/**
+ * 중간 상태 표시 — 킷에 `:indeterminate` 규칙이 없어 보충했다. 네모만 primary 로 채운다.
+ * 「일부 선택됨」은 화면 쪽에서 글로도 알려야 규격을 채운다.
+ */
+const INDETERMINATE_MARK =
+  '[&>input:indeterminate~label]:before:bg-primary-solid ' +
+  '[&>input:indeterminate~label]:before:border-primary-line';
+
+/**
+ * `indeterminate` 는 속성이 아니라 DOM 프로퍼티라 ref 콜백에서 넣는다.
+ * `true` 일 때만 만들고(서버 컴포넌트가 함수를 실어 보내지 않게), 떼어낼 때 프로퍼티를 되돌린다.
+ */
+function indeterminateRef(ref: Ref<HTMLInputElement> | undefined): Ref<HTMLInputElement> {
+  return (node: HTMLInputElement | null) => {
+    if (node) node.indeterminate = true;
+    const inner = typeof ref === 'function' ? ref(node) : undefined;
+    if (ref && typeof ref !== 'function') ref.current = node;
+
+    return () => {
+      if (node) node.indeterminate = false;
+      if (typeof inner === 'function') inner();
+      else if (typeof ref === 'function') ref(null);
+      else if (ref) ref.current = null;
+    };
+  };
+}
+
+type CheckboxBaseProps = {
+  /** `<label for>` 로 이을 id. 필수다. 목록에서는 값에서 만든다(`agree-${item.code}`). */
+  id: string;
+  /** 레이블. `for`/`id` 로 이어져 레이블 클릭으로도 토글된다. */
+  label: ReactNode;
+  /** `.krds-form-check` 감싸개에 붙는다. `...rest` 는 `<input>` 으로 흘린다. */
+  className?: string;
+};
+
+export type CheckboxProps = Omit<
+  ComponentPropsWithRef<'input'>,
+  'type' | 'size' | 'children' | 'className' | 'id'
+> &
+  CheckboxBaseProps & {
+    size?: CheckboxSize;
+    /** 부가 설명. 레이블 바로 다음에 놓여 들여쓰기가 걸린다. */
+    description?: ReactNode;
+    /** 중간 상태. 「전체 선택」에서 하위 일부만 선택되었을 때 켠다. */
+    indeterminate?: boolean;
+  };
+
+export function Checkbox({
+  id,
+  label,
+  description,
+  size = 'medium',
+  indeterminate,
+  className,
+  ref,
+  ...rest
+}: CheckboxProps) {
+  // 참일 때만 표시도 ref 도 만든다 — `indeterminate={false}` 는 그냥 보통 체크박스다.
+  const mixed = indeterminate === true;
+
+  return (
+    <div className={cx('krds-form-check', size, mixed && INDETERMINATE_MARK, className)}>
+      <input
+        type="checkbox"
+        id={id}
+        ref={mixed ? indeterminateRef(ref) : ref}
+        {...rest}
+      />
+      <label htmlFor={id}>{label}</label>
+      {description != null && (
+        // 킷 규칙이 `label + .krds-form-check-cnt` 라 레이블 바로 뒤에 붙어야 한다.
+        <div className="krds-form-check-cnt">
+          <p className="krds-form-check-p">{description}</p>
+        </div>
+      )}
+    </div>
+  );
+}
+
+/**
+ * 칩 꼴 체크박스 — 킷 `krds-form-chip`. 네모 대신 테두리 알약을 눌러 고른다.
+ *
+ * 검색 필터처럼 여러 값을 한 줄에 늘어놓을 때 쓴다. 높이가 버튼·입력칸과 같은 눈금이다.
+ *
+ * @example
+ * <CheckArea layout="inline">
+ *   <CheckboxChip id="f-open" label="공개" />
+ *   <CheckboxChip id="f-closed" label="비공개" />
+ * </CheckArea>
+ */
+export type CheckboxChipProps = Omit<
+  ComponentPropsWithRef<'input'>,
+  'type' | 'size' | 'children' | 'className' | 'id'
+> &
+  CheckboxBaseProps & {
+    size?: CheckboxChipSize;
+  };
+
+export function CheckboxChip({
+  id,
+  label,
+  size = 'medium',
+  className,
+  ...rest
+}: CheckboxChipProps) {
+  return (
+    <div className={cx('krds-form-chip', size, className)}>
+      <input type="checkbox" className="checkbox" id={id} {...rest} />
+      <label className="krds-form-chip-outline" htmlFor={id}>
+        {label}
+      </label>
+    </div>
+  );
+}
+
+/**
+ * 배치. `column` 세로(20px) · `row` 가로(20px) · `inline` 가로 좁은 간격(12px).
+ * `inline` 은 칩처럼 폭이 넓은 항목을 한 줄에 여럿 놓을 때만 쓴다.
+ */
+export type CheckAreaLayout = 'column' | 'row' | 'inline';
+
+export type CheckAreaProps = ComponentPropsWithRef<'div'> & {
+  /** 배치. 기본 `column` — 규격이 수직 배치를 요구한다. */
+  layout?: CheckAreaLayout;
+};
+
+/**
+ * 체크박스 묶음 영역 — 킷 `krds-check-area`. 배치만 맡는다.
+ *
+ * 기본이 세로다(규격). 가로가 필요하면 `layout="row"` 를 명시한다.
+ * 그룹 이름·도움말·오류까지 필요하면 `CheckboxGroup` 을 쓴다.
+ */
+export function CheckArea({ layout = 'column', className, children, ...rest }: CheckAreaProps) {
+  return (
+    <div
+      className={cx(
+        'krds-check-area',
+        layout === 'column' && 'chk-column',
+        layout === 'inline' && 'krds-form-checks-inline',
+        className,
+      )}
+      {...rest}
+    >
+      {children}
+    </div>
+  );
+}
+
+export type CheckboxGroupProps = Omit<ComponentPropsWithRef<'fieldset'>, 'children' | 'title'> & {
+  /** 묶음의 접근 가능한 이름(`<legend>`). 킷이 화면에서 감추고 스크린리더에만 남긴다. */
+  legend: string;
+  /** 보이는 제목. 생략하면 `legend` 를 쓰고, `null` 을 주면 그리지 않는다. */
+  title?: ReactNode | null;
+  /** 도움말. 킷이 회색 정보 아이콘을 앞에 붙인다. */
+  hint?: ReactNode;
+  /** 오류 메시지. 붉은 글자 + 오류 아이콘. 색만으로 알리지 말고 반드시 문구를 넣는다. */
+  error?: ReactNode;
+  /** 배치. 기본 `column`. */
+  layout?: CheckAreaLayout;
+  children?: ReactNode;
+};
+
+/**
+ * 체크박스 묶음 — `<fieldset class="form-group">` + `krds-check-area`.
+ *
+ * 그룹 이름(`legend`) · 보이는 소제목 · 도움말 · 오류 메시지를 한 골격으로 묶는다.
+ * `id` 를 주면 도움말·오류가 `aria-describedby` 로 이어진다.
+ *
+ * @example
+ * <CheckboxGroup id="agree" legend="수신 동의" hint="언제든 해지할 수 있습니다.">
+ *   <Checkbox id="agree-sms" label="문자" />
+ * </CheckboxGroup>
+ */
+export function CheckboxGroup({
+  legend,
+  title,
+  hint,
+  error,
+  layout = 'column',
+  id,
+  className,
+  children,
+  ...rest
+}: CheckboxGroupProps) {
+  const hintId = id && hint != null ? `${id}-hint` : undefined;
+  const errorId = id && error != null ? `${id}-error` : undefined;
+  const describedBy = cx(hintId, errorId) || undefined;
+  const visibleTitle = title === undefined ? legend : title;
+
+  return (
+    <fieldset
+      id={id}
+      className={cx('form-group', className)}
+      aria-describedby={describedBy}
+      {...rest}
+    >
+      {/* legend 는 fieldset 의 첫 자식이어야 한다. 킷이 화면에서 감추지만 이름은 그대로 읽힌다. */}
+      <legend>{legend}</legend>
+      <div className="form-conts">
+        {visibleTitle != null && (
+          <p className="form-label" aria-hidden="true">
+            {visibleTitle}
+          </p>
+        )}
+        <CheckArea layout={layout}>{children}</CheckArea>
+      </div>
+      {hint != null && (
+        <p id={hintId} className="form-hint">
+          {hint}
+        </p>
+      )}
+      {error != null && (
+        <p id={errorId} className="form-hint-invalid">
+          {error}
+        </p>
+      )}
+    </fieldset>
+  );
+}