moru-krds-react 0.1.0

package/src/empty-state/index.tsx

@@ -0,0 +1,256 @@
+import { UiLink } from '../lib/link';
+import type { ComponentPropsWithRef, ReactNode } from 'react';
+import { cx, type KrdsIcon, type KrdsTone } from '../lib/krds';
+
+/**
+ * 빈 상태 상자 — KRDS 에 없다. shadcn `Empty` 형태에 KRDS 토큰을 입힌 보충 부품이다.
+ *
+ * 「보여 줄 것이 없다」를 알린다 — 등록된 것이 없음 · 조건에 맞는 것이 없음 · 권한 없음 · 불러오기 실패.
+ * 「알아 둘 것이 있다」는 `Alert`, 표 안 한 행짜리 빈 칸은 `ui/table` 의 `TableEmpty` 다.
+ * **막다른 골목을 만들지 마라** — `hints` 나 `actions` 중 하나는 준다.
+ * 검색 결과 없음은 규격이 문구와 대안 4개까지 못 박았으므로 {@link SearchEmptyState} 를 쓴다.
+ *
+ * @example
+ * <EmptyState reason="no-results" actions={<Button onClick={reset}>조건 초기화</Button>} />
+ * <EmptyState reason="forbidden" layout="inline" />
+ * <SearchEmptyState query={q} count={0} helpHref="/help/search" />
+ *
+ * 자세히: docs/krds/09-부품-노트.md#빈상태
+ */
+
+/** 왜 비었는가. 색·아이콘·기본 문구가 여기서 갈린다. */
+export type EmptyStateReason =
+  /** 아직 등록된 것이 없다(조건 문제가 아니다) */
+  | 'empty'
+  /** 검색어·필터에 맞는 것이 없다 */
+  | 'no-results'
+  /** 볼 권한이 없다 */
+  | 'forbidden'
+  /** 불러오지 못했다 */
+  | 'error';
+
+/** 색. `KrdsTone` 에서 이 상자가 쓰는 넷만 좁힌 것이다. */
+export type EmptyStateTone = Extract<KrdsTone, 'gray' | 'information' | 'warning' | 'danger'>;
+
+/**
+ * 배치. `panel` 은 목록이 있던 넓은 자리(가운데 정렬), `inline` 은 폼 옆·카드 안처럼 좁은 자리다.
+ * 테두리는 둘 다 같은 사방 점선이고 정렬과 여백만 다르다.
+ */
+export type EmptyStateLayout = 'panel' | 'inline';
+
+/** 사유별 기본값. `forbidden` 에 아이콘이 없는 것은 일부러다 — 킷에 자물쇠·경고 아이콘이 없다. */
+const REASON: Record<EmptyStateReason, { tone: EmptyStateTone; icon: KrdsIcon | null; title: string }> = {
+  empty: { tone: 'gray', icon: 'file', title: '등록된 자료가 없습니다.' },
+  'no-results': { tone: 'gray', icon: 'sch', title: '조건에 맞는 결과가 없습니다.' },
+  forbidden: { tone: 'warning', icon: null, title: '이 내용을 볼 권한이 없습니다.' },
+  error: { tone: 'danger', icon: 'error-fill', title: '불러오지 못했습니다.' },
+};
+
+/** 색조별 유틸리티. 선 `border-*-line` · 면 `bg-*-surface` · mask 아이콘 색 `tint`. */
+const TONE: Record<EmptyStateTone, { line: string; surface: string; tint: string }> = {
+  gray: { line: 'border-line', surface: 'bg-surface-subtler', tint: 'bg-fg-disabled' },
+  information: { line: 'border-information-line', surface: 'bg-information-surface', tint: 'bg-information' },
+  warning: { line: 'border-warning-line', surface: 'bg-warning-surface', tint: 'bg-warning' },
+  danger: { line: 'border-danger-line', surface: 'bg-danger-surface', tint: 'bg-danger' },
+};
+
+export type EmptyStateProps = Omit<ComponentPropsWithRef<'div'>, 'title'> & {
+  /** 기본 `empty`. 색·아이콘·기본 문구가 여기서 정해진다. */
+  reason?: EmptyStateReason;
+  /** 사유의 기본 색을 덮는다. 굳이 필요할 때만. */
+  tone?: EmptyStateTone;
+  /** 기본 `panel`. 좁은 자리에는 `inline`. */
+  layout?: EmptyStateLayout;
+  /** 킷 아이콘 이름(`ico-` 뺀 것). 사유 기본값을 덮는다. `null` 이면 그리지 않는다. */
+  icon?: KrdsIcon | null;
+  /** 제목 한 줄. 생략하면 사유의 기본 문구. */
+  title?: ReactNode;
+  /** 제목 위에 오는 줄. 검색 결과 수처럼 제목보다 먼저 와야 하는 것이 여기 온다. */
+  lead?: ReactNode;
+  /** 제목 아래 보충 설명. */
+  description?: ReactNode;
+  /** 대안 행동 목록. 결과 없음에는 반드시 채운다 — 막다른 골목을 만들지 않는다. */
+  hints?: ReactNode[];
+  /** 아래쪽 단추 자리(`ui/button` 의 Button·LinkButton 을 넣는다). */
+  actions?: ReactNode;
+  /**
+   * `role="status"` 를 붙인다. 클라이언트에서 목록이 바뀌는 화면에서만 켠다 —
+   * 이때 상자는 내용이 바뀌기 전부터 DOM 에 있어야 낭독된다.
+   */
+  live?: boolean;
+  children?: ReactNode;
+};
+
+export function EmptyState({
+  reason = 'empty',
+  tone,
+  layout = 'panel',
+  icon,
+  title,
+  lead,
+  description,
+  hints,
+  actions,
+  live,
+  className,
+  children,
+  ...rest
+}: EmptyStateProps) {
+  const preset = REASON[reason];
+  const t = TONE[tone ?? preset.tone];
+  const panel = layout === 'panel';
+
+  // `undefined` 는 「기본값을 쓴다」, `null` 은 「아이콘을 그리지 않는다」. 둘을 구분해야 한다.
+  const iconName = icon === undefined ? preset.icon : icon;
+  // `-fill` 아이콘은 background-image 라 색을 못 바꾼다 — 색 유틸리티를 붙이지 않는다(함정 1).
+  const iconNode = iconName ? (
+    <i
+      className={cx(
+        'svg-icon',
+        `ico-${iconName}`,
+        panel ? 'size-12' : 'size-6 shrink-0',
+        !iconName.endsWith('-fill') && t.tint,
+      )}
+      aria-hidden="true"
+    />
+  ) : null;
+
+  const hintList =
+    hints && hints.length > 0 ? (
+      // 킷 전역 `ol,ul{list-style:none}` 때문에 목록 의미가 떨어진다 — `ui/text-list` 와 같이 role 을 명시한다.
+      <ul role="list" className={cx('krds-info-list dash', panel && 'w-fit text-left')}>
+        {hints.map((hint, i) => (
+          <li key={i} role="listitem">
+            {hint}
+          </li>
+        ))}
+      </ul>
+    ) : null;
+
+  // shadcn `EmptyHeader` 자리 — 아이콘·제목·설명이 한 덩이로 `gap-2`(8px) 씩 벌어진다.
+  // panel 은 아이콘이 글 **위**에 서고(shadcn `EmptyMedia`), inline 은 좁은 자리라 글 **왼쪽**에 선다.
+  const header = (
+    <div className={cx('flex flex-col gap-2', panel && 'items-center text-center')}>
+      {panel && iconNode}
+      {lead && <p className="m-0 text-sm text-fg-subtle">{lead}</p>}
+      <p className={cx('m-0 font-bold text-fg', panel ? 'text-heading-xs' : 'text-sm')}>{title ?? preset.title}</p>
+      {description && <p className="m-0 text-sm text-fg-subtle">{description}</p>}
+    </div>
+  );
+
+  const body = (
+    <>
+      {header}
+      {hintList}
+      {children}
+      {/* shadcn `EmptyContent` 자리 — 단추 줄. */}
+      {actions && <div className={cx('flex flex-wrap items-center gap-2', panel && 'justify-center')}>{actions}</div>}
+    </>
+  );
+
+  return (
+    <div
+      role={live ? 'status' : undefined}
+      className={cx(
+        // shadcn `Empty` — 점선 사방 테두리 + 둥글기. `border-solid` 가 아니라 `border-dashed` 라야
+        // 선이 그려진다(preflight 가 없어 border-style 기본값이 none 이다. `ui/separator` 함정 2).
+        'rounded-lg border border-dashed',
+        panel
+          ? // 가운데 정렬 + 세로 흐름 `gap-6`(24px). 위아래 40px 은 킷 `.no-results` 실측(`--krds-padding-10`).
+            'flex flex-col items-center gap-6 px-6 py-10 text-center'
+          : // 좁은 자리 — 아이콘을 왼쪽에 세우고 글은 왼쪽 정렬. 여백 24/16px.
+            'flex items-start gap-2 px-6 py-4 text-left',
+        t.line,
+        t.surface,
+        className,
+      )}
+      {...rest}
+    >
+      {panel ? (
+        body
+      ) : (
+        <>
+          {iconNode}
+          <div className="flex min-w-0 flex-1 flex-col gap-4">{body}</div>
+        </>
+      )}
+    </div>
+  );
+}
+
+/**
+ * 검색 결과 없음 — KRDS 가 문구와 대안까지 못 박은 화면이다.
+ *
+ * 결과 수 0 · 규격 문구 · 대안 4개(철자 확인 · 다른 검색어 · 더 일반적인 검색어 · 검색 도움말)를
+ * 기본값으로 담는다. `<SearchEmptyState query={q} />` 만으로 규격을 채운다.
+ *
+ * **`helpHref` 를 주지 않으면 대안 ④가 갈 곳 없는 문장으로 남는다** —
+ * 도움말 문서가 아직 없다면 `hints` 를 직접 넘겨 그 화면에서 할 수 있는 행동으로 바꿔라.
+ */
+
+/** 규격이 든 안내 문구 그대로. 바꾸지 마라. */
+export const SEARCH_NO_RESULT_MESSAGE = '검색어와 일치하는 결과를 찾을 수 없습니다.';
+
+/** 규격 대안 4개 중 링크가 필요 없는 셋. ④는 `helpHref` 에 따라 아래에서 만든다. */
+export const SEARCH_NO_RESULT_HINTS: readonly string[] = [
+  '검색어의 철자가 정확한지 확인해 보세요.',
+  '다른 검색어로 다시 검색해 보세요.',
+  '더 일반적인 검색어를 사용해 보세요.',
+];
+
+export type SearchEmptyStateProps = Omit<EmptyStateProps, 'reason' | 'lead'> & {
+  /** 사용자가 넣은 검색어. 결과 수 줄에 굵게 되짚어 준다. */
+  query?: string;
+  /** 결과 수. 규격상 0을 반드시 표시한다. 화면 위쪽에서 이미 세고 있으면 `null` 로 숨긴다. */
+  count?: number | null;
+  /** 검색 도움말 문서 주소. 규격 대안 ④가 링크가 되려면 있어야 한다. */
+  helpHref?: string;
+  /** 도움말 링크 글자. 기본 「검색 도움말」 — 바꾸면 뒤따르는 조사가 어긋날 수 있다. */
+  helpLabel?: string;
+};
+
+export function SearchEmptyState({
+  query,
+  count = 0,
+  helpHref,
+  helpLabel = '검색 도움말',
+  hints,
+  title = SEARCH_NO_RESULT_MESSAGE,
+  ...rest
+}: SearchEmptyStateProps) {
+  // 킷에 문장 속 텍스트 링크 클래스가 없어(그쪽은 높이가 박힌 버튼이다) 유틸리티로 보충한다.
+  const helpLink = helpHref ? (
+    helpHref.startsWith('/') ? (
+      <UiLink href={helpHref} className="text-link underline hover:text-link-hover">
+        {helpLabel}
+      </UiLink>
+    ) : (
+      <a href={helpHref} className="text-link underline hover:text-link-hover">
+        {helpLabel}
+      </a>
+    )
+  ) : null;
+
+  const specHints: ReactNode[] = [
+    ...SEARCH_NO_RESULT_HINTS,
+    helpLink ? <>{helpLink}을 참고하세요.</> : `${helpLabel}을 참고하세요.`,
+  ];
+
+  return (
+    <EmptyState
+      reason="no-results"
+      title={title}
+      // 규격 순서: 결과 수 → 안내 메시지 → 대안. 그래서 결과 수는 제목 위(`lead`)에 온다.
+      lead={
+        count === null ? undefined : (
+          <>
+            {query ? <>「<b className="text-fg">{query}</b>」에 대한 검색 결과 </> : '검색 결과 '}
+            <b className="text-fg">{count.toLocaleString('ko-KR')}</b>건
+          </>
+        )
+      }
+      hints={hints ?? specHints}
+      {...rest}
+    />
+  );
+}

package/src/env.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `process.env.NODE_ENV` 만을 위한 최소 선언.
+ *
+ * 부품 몇 개가 개발 중에만 콘솔 경고를 낸다(예: `<table>` 에 display 를 바꾸는 클래스가 붙었을 때).
+ * 번들러(Next·Vite·webpack)가 이 값을 빌드 때 문자열로 갈아 끼우므로 운영 번들에는 남지 않는다.
+ *
+ * `@types/node` 를 통째로 끌어오지 않는 이유 — 이것은 브라우저에서 도는 UI 부품 묶음이라
+ * Node 전역(`Buffer`·`__dirname` 등)이 타입에 보이면 잘못 쓰기 쉽다.
+ */
+declare const process: { env: { NODE_ENV?: string } };

package/src/field/index.tsx

@@ -0,0 +1,307 @@
+import type { ComponentPropsWithRef, ReactNode } from 'react';
+import { cx, stateClass, type KrdsFieldState } from '../lib/krds';
+
+/**
+ * 폼 필드 골격 — KRDS `fieldset` · `form-group` · `form-tit` · `form-conts` · `form-hint`.
+ *
+ * 레이블 · 컨트롤 · 도움말 · 상태 메시지를 한 골격으로 묶고 접근성 속성을 이어 준다.
+ * 컨트롤은 `TextInput` · `Select` · `Textarea` 가 스스로 그린다 — 여기서 겹쳐 그리지 않는다.
+ * **`hint` 는 상태와 무관한 입력 규칙 안내**(회색)이고, 파란 「정보」 메시지는
+ * `state="information"` + `message` 다. 둘을 바꿔 쓰면 평범한 안내가 상태 메시지로 보인다.
+ * 레이블 달린 텍스트 한 줄이면 `ui/text-input` 의 `TextField` 가 이 조립을 대신한다.
+ * 서버 컴포넌트라 `id` 가 필수다.
+ *
+ * @example
+ * <Fieldset>
+ *   <Field id="user_id" label="아이디" hint="4~30자" required>
+ *     {(a) => <TextInput {...a} placeholder="아이디" />}
+ *   </Field>
+ *   <Field id="user_pw" label="비밀번호" state="error" message="8자 이상이어야 합니다."
+ *          action={<Button iconOnly label="비밀번호 보기" icon="pw-visible" />}>
+ *     {(a) => <TextInput {...a} type="password" />}
+ *   </Field>
+ * </Fieldset>
+ *
+ * 자세히: docs/krds/09-부품-노트.md#폼필드
+ */
+
+/* ────────────────────────────── 골격 조각 ────────────────────────────── */
+
+/**
+ * `<div class="fieldset">` — 폼그룹 여럿을 세로로 묶는다.
+ * 필드 사이 세로 간격이 여기서 나온다 — `mt-*` 를 손으로 붙이지 마라.
+ */
+export function Fieldset({ className, children, ...rest }: ComponentPropsWithRef<'div'>) {
+  return (
+    <div className={cx('fieldset', className)} {...rest}>
+      {children}
+    </div>
+  );
+}
+
+/**
+ * `<div class="form-col-group">` — 폼그룹 여럿을 가로로 늘어놓는다(성/이름, 시작일/종료일).
+ * 좁은 화면(767px 이하)에서는 킷이 알아서 세로로 접는다.
+ *
+ * 컨트롤 하나에 딸린 버튼·기호를 묶는 것은 `ui/input-group` 의 `InputGroup` 이다.
+ */
+export function FieldRow({ className, children, ...rest }: ComponentPropsWithRef<'div'>) {
+  return (
+    <div className={cx('form-col-group', className)} {...rest}>
+      {children}
+    </div>
+  );
+}
+
+/**
+ * `<div class="form-group">` — 필드 하나.
+ * 도움말 선택자와 상태 토큰이 전부 여기 매여 있다 — 이 감싸개 없이 조각만 쓰면 모양이 나오지 않는다.
+ */
+export function FormGroup({ className, children, ...rest }: ComponentPropsWithRef<'div'>) {
+  return (
+    <div className={cx('form-group', className)} {...rest}>
+      {children}
+    </div>
+  );
+}
+
+export type FieldLabelProps = Omit<ComponentPropsWithRef<'label'>, 'htmlFor'> & {
+  /** 이을 컨트롤의 id. `<label for>` 라 필수다. */
+  htmlFor: string;
+  /** 필수 입력 표시(`*`). 킷에 클래스가 없어 보충한 부분이다. */
+  required?: boolean;
+  /** 눈에서만 감춘다(`sr-only`). 이름 자체는 남는다 — 검색창처럼 레이블을 못 두는 자리에. */
+  srOnly?: boolean;
+  /** `.form-tit` 감싸개에 붙는다. `className` 은 `<label>` 로 간다. */
+  boxClassName?: string;
+};
+
+/**
+ * 레이블 — `<div class="form-tit"><label for>…</label></div>`.
+ * 라디오·체크박스 묶음의 **소제목**은 이것이 아니라 `.form-conts` 안의 `.form-label` 자리다.
+ */
+export function FieldLabel({
+  htmlFor,
+  required,
+  srOnly,
+  boxClassName,
+  className,
+  children,
+  ...rest
+}: FieldLabelProps) {
+  const label = (
+    <label htmlFor={htmlFor} className={cx(srOnly && 'sr-only', className)} {...rest}>
+      {children}
+      {required && (
+        // 킷에 필수 표시 클래스가 없어 보충한 부분. 소리로는 컨트롤의 required/aria-required 가 알린다.
+        <em className="not-italic text-danger ml-1" aria-hidden="true">
+          *
+        </em>
+      )}
+    </label>
+  );
+
+  // 감춘 레이블은 `.form-tit` 로 감싸지 않는다 — 감싸개만 남아 gap 이 한 칸 더 벌어진다.
+  return srOnly ? label : <div className={cx('form-tit', boxClassName)}>{label}</div>;
+}
+
+/** `data-*` 속성. React 타입에 자리가 없어 객체 리터럴로 넘기면 `TS2353` 이 나므로 열어 둔다. */
+export type KrdsDataAttrs = {
+  [key: `data-${string}`]: string | number | boolean | undefined;
+};
+
+export type FieldControlProps = ComponentPropsWithRef<'div'> &
+  KrdsDataAttrs & {
+    /** 필드 상태. 킷의 `is-*` 클래스가 이 감싸개에 붙는다. */
+    state?: KrdsFieldState;
+    /**
+     * 컨트롤 오른쪽에 겹쳐 놓을 아이콘 버튼(비밀번호 보기, 내용 지우기 등).
+     * 킷 클래스 `btn-ico-wrap` 은 부품이 붙인다. 둘 이상이면 `<div class="btn-group">` 으로 묶어 넘긴다.
+     */
+    action?: ReactNode;
+    /**
+     * 「내용 지우기」 버튼을 킷 CSS 로 여닫는다. **`placeholder` 가 없으면 영영 보이지 않는다.**
+     * 버튼 자체는 `action` 으로 넘겨 입력칸의 형제가 되게 한다.
+     */
+    deletable?: boolean;
+  };
+
+/**
+ * `<div class="form-conts">` — 컨트롤 감싸개. **상태 클래스가 붙는 자리다.**
+ *
+ * 킷이 여기 얹어 쓰는 클래스가 더 있다 — 날짜 입력 `calendar-conts`,
+ * 검색 키워드 입력 `keyword-sch`. 필요하면 `className` 으로 더한다.
+ */
+export function FieldControl({
+  state,
+  action,
+  deletable,
+  className,
+  children,
+  ...rest
+}: FieldControlProps) {
+  return (
+    <div
+      className={cx('form-conts', stateClass(state), action ? 'btn-ico-wrap' : undefined, className)}
+      // 킷 선택자가 `.form-conts[data-delete=true]` 라 문자열 "true" 여야 한다.
+      data-delete={deletable ? 'true' : undefined}
+      {...rest}
+    >
+      {children}
+      {action}
+    </div>
+  );
+}
+
+/** 메시지 클래스 4종. `state` 를 생략하면 중립(`form-hint`, 회색)이다. */
+export const FIELD_HINT_CLASS: Record<KrdsFieldState | 'neutral', string> = {
+  neutral: 'form-hint',
+  error: 'form-hint-invalid',
+  success: 'form-hint-success',
+  information: 'form-hint-information',
+};
+
+/** 상태 → 메시지 클래스. `undefined` 는 중립이다. */
+export function fieldHintClass(state?: KrdsFieldState): string {
+  return FIELD_HINT_CLASS[state ?? 'neutral'];
+}
+
+export type FieldHintProps = ComponentPropsWithRef<'p'> & {
+  /** 생략하면 중립 도움말(`form-hint`). 상태를 주면 그 상태의 메시지가 된다. */
+  state?: KrdsFieldState;
+};
+
+/**
+ * `<p class="form-hint…">` — 도움말·상태 메시지. `.form-group` 안에 두어야 모양을 받는다.
+ * 아이콘은 킷이 `::before` 로 붙인다 — 따로 넣지 마라.
+ */
+export function FieldHint({ state, className, children, ...rest }: FieldHintProps) {
+  return (
+    <p className={cx(fieldHintClass(state), className)} {...rest}>
+      {children}
+    </p>
+  );
+}
+
+/* ────────────────────────────── 완성형 ────────────────────────────── */
+
+/** 컨트롤에 그대로 펼쳐 넣는 속성. `<input {...control} />` 처럼 쓴다. */
+export type FieldControlAttrs = {
+  id: string;
+  /** 도움말·상태 메시지의 id 를 잇는다(둘 다 있으면 공백으로 이어 붙인다). */
+  'aria-describedby'?: string;
+  'aria-invalid'?: true;
+  'aria-required'?: true;
+  required?: boolean;
+};
+
+export type FieldProps = Omit<ComponentPropsWithRef<'div'>, 'children'> & {
+  /** 컨트롤의 id. `<label for>` 와 `aria-describedby` 가 여기서 갈라져 나온다. 서버 컴포넌트라 필수다. */
+  id: string;
+  /** 레이블 글자. */
+  label: ReactNode;
+  /** 레이블을 눈에서만 감춘다. 이름은 남는다. */
+  hideLabel?: boolean;
+  /** 중립 도움말(회색). 상태와 무관한 입력 규칙 안내는 여기에 쓴다. */
+  hint?: ReactNode;
+  /** 필드 상태. `is-*` 는 `.form-conts` 에, 색은 `message` 에 걸린다. */
+  state?: KrdsFieldState;
+  /** 상태 메시지. `state` 와 짝으로 쓴다. */
+  message?: ReactNode;
+  /** 오류 문구 지름길. `state="error"` + `message` 와 같다(직접 준 쪽이 이긴다). */
+  error?: ReactNode;
+  /** 필수 입력. 레이블에 `*`, 컨트롤에 `required`·`aria-required` 를 함께 붙인다. */
+  required?: boolean;
+  /** 이미 있는 설명 요소를 더 잇고 싶을 때(공백으로 이어진 id 목록). */
+  describedBy?: string;
+  /** 컨트롤 오른쪽에 겹쳐 놓을 아이콘 버튼. {@link FieldControlProps.action} 참고. */
+  action?: ReactNode;
+  /** 「내용 지우기」 버튼을 연다. {@link FieldControlProps.deletable} 참고. */
+  deletable?: boolean;
+  /** `.form-conts` 에 그대로 흘릴 속성(`className="calendar-conts"` · `data-*` 등). */
+  contentProps?: Omit<ComponentPropsWithRef<'div'>, 'children'> & KrdsDataAttrs;
+  /** 이 필드 하나만 놓일 때 `<div class="fieldset">` 로 감싼다. 여럿이면 바깥에서 한 번만 감싼다. */
+  standalone?: boolean;
+  /**
+   * 컨트롤. 함수로 주면 접근성 속성을 받는다 — **반드시 펼쳐 넣어야** 레이블·도움말이 이어진다.
+   * 킷 클래스는 여기서 넘기지 않는다(컨트롤 부품이 스스로 붙인다).
+   */
+  children: ReactNode | ((control: FieldControlAttrs) => ReactNode);
+};
+
+/**
+ * 레이블 · 컨트롤 · 도움말 · 상태 메시지를 KRDS 골격 하나로 묶는다.
+ *
+ * 레이블 달린 텍스트 한 줄이면 `ui/text-input` 의 `TextField` 가 이 조립을 대신한다.
+ *
+ * @example
+ * <Field id="user_id" label="아이디" hint="4~30자" required>
+ *   {(a) => <TextInput {...a} placeholder="아이디" />}
+ * </Field>
+ */
+export function Field({
+  id,
+  label,
+  hideLabel,
+  hint,
+  state,
+  message,
+  error,
+  required,
+  describedBy,
+  action,
+  deletable,
+  contentProps,
+  standalone,
+  className,
+  children,
+  ...rest
+}: FieldProps) {
+  // `error` 지름길. 직접 준 state·message 가 이긴다.
+  // 빈 값(undefined·null·'' ·false)은 「메시지 없음」으로 본다 — 빈 <p> 가 남으면 gap 만 벌어진다.
+  const finalState: KrdsFieldState | undefined = state ?? (error ? 'error' : undefined);
+  const finalMessage = message || error;
+
+  const hintId = hint ? `${id}-hint` : undefined;
+  const messageId = finalMessage ? `${id}-message` : undefined;
+
+  const control: FieldControlAttrs = { id };
+  // KRDS 는 규정하지 않지만 WAI-ARIA 상 옳다 — 초과 준수로 붙인다.
+  const described = cx(describedBy, hintId, messageId);
+  if (described) control['aria-describedby'] = described;
+  if (finalState === 'error') control['aria-invalid'] = true;
+  if (required) {
+    control.required = true;
+    control['aria-required'] = true;
+  }
+
+  const { className: contentClassName, ...contentRest } = contentProps ?? {};
+
+  const group = (
+    <FormGroup className={className} {...rest}>
+      <FieldLabel htmlFor={id} required={required} srOnly={hideLabel}>
+        {label}
+      </FieldLabel>
+
+      <FieldControl
+        state={finalState}
+        action={action}
+        deletable={deletable}
+        className={contentClassName}
+        {...contentRest}
+      >
+        {typeof children === 'function' ? children(control) : children}
+      </FieldControl>
+
+      {/* 중립 도움말. 상태 메시지와 **다른 줄**이다 — 규칙 안내는 오류가 떠도 그대로 남는다. */}
+      {hint && <FieldHint id={hintId}>{hint}</FieldHint>}
+      {finalMessage && (
+        <FieldHint id={messageId} state={finalState}>
+          {finalMessage}
+        </FieldHint>
+      )}
+    </FormGroup>
+  );
+
+  return standalone ? <Fieldset>{group}</Fieldset> : group;
+}