moru-krds-react 0.1.0

package/src/in-page-navigation/index.tsx

@@ -0,0 +1,258 @@
+'use client';
+
+import {
+  useCallback,
+  useEffect,
+  useState,
+  type ComponentPropsWithRef,
+  type MouseEvent as ReactMouseEvent,
+  type ReactNode,
+} from 'react';
+import { cx } from '../lib/krds';
+
+/**
+ * 콘텐츠 내 탐색(목차) — KRDS `krds-in-page-navigation-area`.
+ *
+ * 긴 상세 화면의 섹션 목차. 본문 섹션에 `id` 만 주면 스크롤 감시·부드러운 이동·초점 이동을
+ * 이 부품이 한다(킷 JS 를 싣지 않는다). 항목 이름은 **연결된 섹션 제목과 같은 문구**로 쓴다.
+ * 컨테이너에 {@link InPageNavigationLayout} 을 붙여야 목차 자리가 열린다 —
+ * 목차에만 붙이면 고정된 목차가 본문 위를 덮는다.
+ * 마크업 자리는 제목과 본문 **사이**다. 서비스 정보구조 탐색은 이것이 아니라 `ui/side-navigation` 이다.
+ * `action` 에 넣은 버튼은 **모바일에서 킷이 숨기므로** 유일한 실행 수단을 여기 두지 마라.
+ *
+ * @example
+ * <InPageNavigationLayout id="container">
+ *   <div className="inner">
+ *     <div className="contents">
+ *       <InPageNavigation
+ *         title="장애아동수당"
+ *         items={[
+ *           { id: 'sec-overview', label: '서비스 개요' },
+ *           { id: 'sec-detail', label: '서비스 상세' },
+ *         ]}
+ *       />
+ *       <section id="sec-overview"><h2>서비스 개요</h2>…</section>
+ *     </div>
+ *   </div>
+ * </InPageNavigationLayout>
+ *
+ * 자세히: docs/krds/09-부품-노트.md#페이지내탐색
+ */
+
+/** 목차 한 줄. `id` 는 본문 섹션 요소의 `id`(`#` 없이). */
+export type InPageNavigationItem = {
+  /** 이동 대상 섹션의 `id`. `href="#{id}"` 로 나간다. */
+  id: string;
+  /** 목록에 보일 글자. 연결된 섹션 제목과 같은 문구여야 한다. 길면 두 줄로 접힌다. */
+  label: ReactNode;
+};
+
+export type InPageNavigationProps = Omit<ComponentPropsWithRef<'div'>, 'children' | 'title'> & {
+  /** 목차 항목. 빈 배열이면 아무것도 그리지 않는다. 8개 안팎으로 줄인다. */
+  items: InPageNavigationItem[];
+  /** 머리말 위 작은 글자. 기본 「이 페이지의 구성」. `null` 을 주면 그리지 않는다. */
+  caption?: ReactNode;
+  /** 머리말 제목. 보통 현재 화면 이름. 제목 태그가 아니라 `<p>` 로 그린다. */
+  title?: ReactNode;
+  /** `<nav>` 의 접근 이름. 생략하면 `caption` 을 쓴다. */
+  navLabel?: string;
+  /** 목록 아래 실행 버튼. **모바일에서는 킷이 숨긴다.** */
+  action?: ReactNode;
+  /** 실행 버튼 아래 보조 문구. */
+  info?: ReactNode;
+  /** 활성 항목을 밖에서 정한다. 주면 스크롤 감시를 끄고 이 값만 따른다. */
+  activeId?: string;
+  /** 이동한 뒤 섹션 위에 남길 여백(px). 안 주면 마스트헤드 + 헤더 높이를 잰다. */
+  offsetTop?: number;
+};
+
+/** 고정 헤더 높이. 킷 JS `calculateHeaderHeight()` 와 같은 계산이다. */
+function headerHeight(): number {
+  const masthead = document.getElementById('krds-masthead')?.clientHeight ?? 0;
+  const headerIn =
+    document.querySelector<HTMLElement>('#krds-header .header-in')?.clientHeight ?? 0;
+  return masthead + headerIn;
+}
+
+/**
+ * 지금 보고 있는 섹션을 고른다. 킷 JS `updateActiveSection()` 을 옮기되
+ * 문서 기준 좌표로 재고, 섹션 사이 빈틈에서는 **지나온 마지막 섹션**을 고른다.
+ */
+function pickActiveId(ids: string[]): string | undefined {
+  const found = ids
+    .map((id) => ({ id, el: document.getElementById(id) }))
+    .filter((s): s is { id: string; el: HTMLElement } => s.el !== null);
+  if (found.length === 0) return undefined;
+
+  const y = window.scrollY;
+  // 스크롤이 문서 끝에 닿으면 마지막 항목(짧은 마지막 섹션이 영영 활성화되지 못하는 것을 막는다).
+  if (y + window.innerHeight >= document.documentElement.scrollHeight - 1) {
+    return found[found.length - 1]!.id;
+  }
+
+  const guard = Math.ceil(window.innerHeight / 5); // 킷과 같은 「윈도우의 20%」
+  let active = found[0]!.id;
+  for (const { id, el } of found) {
+    if (y >= el.getBoundingClientRect().top + y - guard) active = id;
+  }
+  return active;
+}
+
+export function InPageNavigation({
+  items,
+  caption = '이 페이지의 구성',
+  title,
+  navLabel,
+  action,
+  info,
+  activeId,
+  offsetTop,
+  className,
+  ...rest
+}: InPageNavigationProps) {
+  const [spyId, setSpyId] = useState<string | undefined>(undefined);
+  const controlled = activeId !== undefined;
+  const active = controlled ? activeId : spyId;
+
+  // 항목 id 를 문자열 하나로 굳혀 effect 의존성에 쓴다(배열이 매번 새로 만들어져도 다시 붙지 않게).
+  const idKey = items.map((it) => it.id).join(' ');
+
+  useEffect(() => {
+    if (controlled) return;
+    const ids = idKey ? idKey.split(' ') : [];
+    if (ids.length === 0) return;
+
+    let frame = 0;
+    const update = () => {
+      frame = 0;
+      setSpyId(pickActiveId(ids));
+    };
+    // 스크롤마다 레이아웃을 재는 계산이라 프레임당 한 번으로 묶는다.
+    const schedule = () => {
+      if (frame === 0) frame = window.requestAnimationFrame(update);
+    };
+
+    update();
+    window.addEventListener('scroll', schedule, { passive: true });
+    window.addEventListener('resize', schedule);
+    return () => {
+      if (frame !== 0) window.cancelAnimationFrame(frame);
+      window.removeEventListener('scroll', schedule);
+      window.removeEventListener('resize', schedule);
+    };
+  }, [controlled, idKey]);
+
+  const goToSection = useCallback(
+    (id: string): boolean => {
+      const target = document.getElementById(id);
+      if (!target) return false; // 대상이 없으면 브라우저 기본 앵커 이동에 맡긴다
+
+      const gap = offsetTop ?? headerHeight();
+      const reduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+      window.scrollTo({
+        left: 0,
+        top: target.getBoundingClientRect().top + window.scrollY - gap,
+        behavior: reduced ? 'auto' : 'smooth',
+      });
+
+      // 스크롤만 하고 초점을 두면 규격 위반이다(「스크롤과 함께 목적지 섹션으로 Focus 이벤트」).
+      // 킷은 `.sec-tit` 을 찾지만 그 클래스는 킷 CSS 에 없다 — 섹션의 첫 제목 태그를 쓴다.
+      const focusTarget = target.querySelector<HTMLElement>('h1, h2, h3, h4, h5, h6') ?? target;
+      focusTarget.setAttribute('tabindex', '-1');
+      focusTarget.focus({ preventScroll: true });
+      return true;
+    },
+    [offsetTop],
+  );
+
+  const handleClick = (event: ReactMouseEvent<HTMLAnchorElement>, id: string) => {
+    // 새 탭·새 창으로 여는 조작은 그대로 둔다(킷 JS 는 이것까지 막는다).
+    if (
+      event.defaultPrevented ||
+      event.button !== 0 ||
+      event.metaKey ||
+      event.ctrlKey ||
+      event.shiftKey ||
+      event.altKey
+    ) {
+      return;
+    }
+    if (goToSection(id)) {
+      event.preventDefault();
+      if (!controlled) setSpyId(id);
+    }
+  };
+
+  if (items.length === 0) return null;
+
+  const hasHeader = caption != null || title != null;
+
+  return (
+    <div className={cx('krds-in-page-navigation-area', className)} {...rest}>
+      {hasHeader && (
+        <div className="in-page-navigation-header">
+          {caption != null && <p className="quick-caption">{caption}</p>}
+          {/* 제목 태그가 아니라 `<p>` 다 — 본문 제목 계층을 흐리지 않으려는 킷 샘플 그대로. */}
+          {title != null && <p className="quick-title">{title}</p>}
+        </div>
+      )}
+
+      <nav
+        className="in-page-navigation-list"
+        aria-label={navLabel ?? (typeof caption === 'string' ? caption : '이 페이지의 구성')}
+      >
+        <ul>
+          {items.map((item) => {
+            const isActive = item.id === active;
+            return (
+              <li key={item.id}>
+                <a
+                  href={`#${item.id}`}
+                  className={isActive ? 'active' : undefined}
+                  aria-current={isActive ? 'true' : undefined}
+                  onClick={(event) => handleClick(event, item.id)}
+                >
+                  {item.label}
+                </a>
+              </li>
+            );
+          })}
+        </ul>
+      </nav>
+
+      {(action != null || info != null) && (
+        // 767px 이하에서 킷이 이 블록을 통째로 `display:none` 한다. 유일한 실행 수단을 여기 두지 마라.
+        <div className="in-page-navigation-action">
+          {action}
+          {info != null && <p className="quick-info">{info}</p>}
+        </div>
+      )}
+    </div>
+  );
+}
+
+/**
+ * 목차가 있는 화면의 컨테이너 — 킷 `krds-in-page-navigation-type`.
+ *
+ * **목차가 아니라 컨테이너에 붙인다** — 이 클래스가 본문 오른쪽에 목차 자리를 파 준다.
+ * 안쪽은 `.inner`(LNB 가 같이 있으면 `.inner.in-between`) → `.contents` 순서다.
+ *
+ * @example
+ * <InPageNavigationLayout id="container">
+ *   <div className="inner in-between">
+ *     <SideNav … />
+ *     <div className="contents">…<InPageNavigation … />…</div>
+ *   </div>
+ * </InPageNavigationLayout>
+ */
+export function InPageNavigationLayout({
+  className,
+  children,
+  ...rest
+}: ComponentPropsWithRef<'div'>) {
+  return (
+    <div className={cx('krds-in-page-navigation-type', className)} {...rest}>
+      {children}
+    </div>
+  );
+}

package/src/index.ts

@@ -0,0 +1,72 @@
+/**
+ * KRDS(디지털정부서비스 UI/UX 가이드라인) React 부품.
+ *
+ * 두 갈래다.
+ *  1. **KRDS 부품** — 킷(`krds-uiux`)의 클래스를 그대로 쓰는 껍데기.
+ *     모양·색·크기는 전부 킷에서 오고, 이 층은 마크업 구조와 접근성 속성을 고정한다.
+ *  2. **보충 부품** — KRDS 가 다루지 않는 업무시스템(백오피스)용. KRDS 토큰으로 그린다.
+ *     KRDS 는 국민용 누리집이 대상이라 표 정렬·콤보박스·서랍·토스트 같은 것이 없다.
+ *
+ */
+
+/* ── 공통 타입 ─────────────────────────────────────────────── */
+export * from './lib/krds';
+
+/* ── 액션 ─────────────────────────────────────────────────── */
+export * from './button';
+
+/* ── 폼 ───────────────────────────────────────────────────── */
+export * from './field';
+export * from './text-input';
+export * from './textarea';
+export * from './select';
+export * from './checkbox';
+export * from './radio';
+export * from './file-upload';
+export * from './combobox';
+export * from './input-group';
+
+/* ── 표현 ─────────────────────────────────────────────────── */
+export * from './badge';
+export * from './tag';
+export * from './table';
+export * from './data-table';
+export * from './structured-list';
+export * from './text-list';
+export * from './critical-alert';
+export * from './alert';
+export * from './empty-state';
+
+/* ── 탐색 ─────────────────────────────────────────────────── */
+export * from './skip-link';
+export * from './masthead';
+export * from './header';
+export * from './main-menu';
+export * from './breadcrumb';
+export * from './side-navigation';
+export * from './in-page-navigation';
+export * from './pagination';
+export * from './footer';
+export * from './identifier';
+
+/* ── 열고 닫기 ─────────────────────────────────────────────── */
+export * from './accordion';
+export * from './disclosure';
+export * from './tab';
+export * from './modal';
+export * from './drawer';
+export * from './tooltip';
+export * from './context-menu';
+
+/* ── 피드백 ───────────────────────────────────────────────── */
+export * from './spinner';
+export * from './step-indicator';
+export * from './progress';
+export * from './skeleton';
+export * from './toast';
+
+/* ── 그 밖 ────────────────────────────────────────────────── */
+export * from './avatar';
+export * from './separator';
+export * from './scroll-area';
+export * from './resize';

package/src/input-group/index.tsx

@@ -0,0 +1,197 @@
+import { Children, cloneElement, Fragment, isValidElement } from 'react';
+import type { ComponentPropsWithRef, ReactElement, ReactNode } from 'react';
+import { cx, type KrdsFieldSize } from '../lib/krds';
+
+/**
+ * 입력 묶음 — 킷 `input-group`.
+ *
+ * 컨트롤 하나와 그에 딸린 버튼·기호를 한 줄로 묶고 **크기를 한 번만 정해 자식에게 내려보낸다.**
+ * 그래서 입력칸과 옆 버튼의 높이가 어긋나지 않는다(기본 medium · 48px).
+ * 레이블까지 갖춘 필드 여럿을 가로로 늘어놓는 것은 `ui/field` 의 `FieldRow` 다.
+ * 기간(시작~끝)은 {@link InputGroupRange} 를 쓴다.
+ * 크기는 `TextInput`·`Select`·`Button` 같은 **부품**에만 내려간다 — 맨 `<input>` 은 그대로 남는다.
+ *
+ * @example
+ * <InputGroup size="medium">
+ *   <InputGroupItem>
+ *     <TextField id="q" label="검색어" hideLabel placeholder="검색어를 입력하세요" />
+ *   </InputGroupItem>
+ *   <Button variant="primary" type="submit">검색</Button>
+ * </InputGroup>
+ * <InputGroup>
+ *   <InputGroupItem><TextInput id="amount" inputMode="numeric" /></InputGroupItem>
+ *   <InputGroupText>원</InputGroupText>
+ * </InputGroup>
+ *
+ * 자세히: docs/krds/09-부품-노트.md#입력묶음
+ */
+
+/* ────────────────────────────── 크기 전파 ────────────────────────────── */
+
+/**
+ * 자식 부품에 `size` 를 내려보낸다. DOM 태그와 Fragment 에는 넘기지 않고(HTML `size` 속성과 뜻이 다르다),
+ * 자식이 이미 `size` 를 갖고 있으면 그대로 둔다.
+ */
+function withSize(children: ReactNode, size: KrdsFieldSize): ReactNode {
+  return Children.map(children, (child) => {
+    if (!isValidElement(child)) return child;
+    if (typeof child.type === 'string' || child.type === Fragment) return child;
+    // React 19 타입에서 `props` 는 unknown 이라 좁혀서 본다.
+    const props = child.props as { size?: unknown };
+    if (props.size !== undefined) return child;
+    return cloneElement(child as ReactElement<{ size?: KrdsFieldSize }>, { size });
+  });
+}
+
+/* ────────────────────────────── 기본형 ────────────────────────────── */
+
+export type InputGroupProps = Omit<ComponentPropsWithRef<'div'>, 'children'> & {
+  /** 묶음 전체의 크기. 기본 medium(48px). **자식이 저마다 적지 않고 여기서 한 번만 정한다.** */
+  size?: KrdsFieldSize;
+  /** 세로 정렬. 기본 `center` — 자식이 레이블까지 달고 있으면 `end` 로 밑선을 맞춘다. */
+  align?: 'center' | 'end';
+  /** 간격을 16px 에서 8px 로 좁힌다. 입력칸과 버튼을 한 덩어리처럼 보이게 할 때. */
+  tight?: boolean;
+  children?: ReactNode;
+};
+
+/**
+ * `<div class="input-group">` — 컨트롤 하나와 그에 딸린 버튼·기호를 한 줄로 묶는다.
+ * `size` 를 하나 바꾸면 입력칸·버튼이 함께 움직인다.
+ *
+ * **`className="row"` 안에서는 세로로 쌓인다** — 킷에 그런 규칙이 있다.
+ */
+export function InputGroup({
+  size = 'medium',
+  align = 'center',
+  tight,
+  className,
+  children,
+  ...rest
+}: InputGroupProps) {
+  return (
+    <div
+      className={cx('input-group', align === 'end' && 'items-end', tight && 'gap-2', className)}
+      {...rest}
+    >
+      {withSize(children, size)}
+    </div>
+  );
+}
+
+/* ────────────────────────────── 폭을 차지하는 칸 ────────────────────────────── */
+
+export type InputGroupItemProps = ComponentPropsWithRef<'div'> & {
+  /** 안쪽 자식에 내려보낸다. 보통 {@link InputGroup} 이 알아서 넣어 준다. */
+  size?: KrdsFieldSize;
+  /** 남는 폭을 차지한다. 기본 true — 이 상자에 넣는 것이 대개 입력칸이라서다. */
+  grow?: boolean;
+};
+
+/**
+ * 늘어나는 칸. **입력칸은 이 상자로 감싼다** — 감싸지 않으면 기준 폭이 컨테이너 전체가 되어
+ * 옆 버튼을 찌그러뜨린다. 늘어나지 않아야 하면 `grow={false}`.
+ */
+export function InputGroupItem({
+  size = 'medium',
+  grow = true,
+  className,
+  children,
+  ...rest
+}: InputGroupItemProps) {
+  return (
+    <div className={cx(grow ? 'min-w-0 flex-1' : 'shrink-0', className)} {...rest}>
+      {withSize(children, size)}
+    </div>
+  );
+}
+
+/* ────────────────────────────── 접두사·접미사 ────────────────────────────── */
+
+/** 크기별 상자 높이와 글자 크기. 킷 입력칸 토큰과 같은 값이다(40 / 48 / 56 / 80px). */
+const ADDON_BOX: Record<KrdsFieldSize, string> = {
+  small: 'h-10 text-label-sm',
+  medium: 'h-12 text-label-md',
+  large: 'h-14 text-label-lg',
+  xlarge: 'h-20 text-heading-md',
+};
+
+export type InputGroupTextProps = ComponentPropsWithRef<'span'> & {
+  /** 보통 {@link InputGroup} 이 넣어 준다. 기본 medium(48px). */
+  size?: KrdsFieldSize;
+};
+
+/**
+ * 입력칸에 붙는 글자 — 접두사(`https://`), 단위(`원`·`건`), 구분 기호(`~`).
+ * 킷에 클래스가 없어 보충했다. 입력칸과 같은 높이로 서서 밑선이 맞는다.
+ *
+ * 「원」처럼 **뜻이 있는 단위는 읽혀야 하고**, `~` 처럼 시각적 기호는 `aria-hidden` 을 직접 붙여
+ * 소리에서 뺀다 — 어느 쪽인지는 부품이 판단할 수 없어 기본값을 두지 않았다.
+ */
+export function InputGroupText({
+  size = 'medium',
+  className,
+  children,
+  ...rest
+}: InputGroupTextProps) {
+  return (
+    <span
+      className={cx(
+        'inline-flex shrink-0 items-center whitespace-nowrap text-fg-subtle',
+        ADDON_BOX[size],
+        className,
+      )}
+      {...rest}
+    >
+      {children}
+    </span>
+  );
+}
+
+/* ────────────────────────────── 기간 입력 ────────────────────────────── */
+
+/** 기간 입력이 쓰는 크기. 킷에 구분 기호의 xlarge 규칙이 없어 덜어냈다. */
+export type InputGroupRangeSize = Exclude<KrdsFieldSize, 'xlarge'>;
+
+export type InputGroupRangeProps = Omit<ComponentPropsWithRef<'ul'>, 'children'> & {
+  /** 기본 medium(48px). 두 칸과 가운데 기호에 함께 내려간다. */
+  size?: InputGroupRangeSize;
+  /** 시작 칸. 레이블까지 갖춘 필드를 그대로 넣어도 된다. */
+  from: ReactNode;
+  /** 끝 칸. */
+  to: ReactNode;
+  /** 가운데 구분 기호. 기본 `-`. 장식이라 소리에서는 빠진다. */
+  separator?: ReactNode;
+  /** 킷 달력 스크립트가 잡는 손잡이 클래스(`set`)를 붙인다. 킷 달력을 물릴 때만 켠다. */
+  set?: boolean;
+};
+
+/**
+ * 기간 입력 — 킷 `input-group range`. 두 칸이 폭을 반씩 나눠 갖고 입력칸 밑선이 맞는다.
+ *
+ * @example
+ * <InputGroupRange
+ *   from={<TextField id="from" label="시작일" type="date" />}
+ *   to={<TextField id="to" label="종료일" type="date" />}
+ * />
+ */
+export function InputGroupRange({
+  size = 'medium',
+  from,
+  to,
+  separator = '-',
+  set,
+  className,
+  ...rest
+}: InputGroupRangeProps) {
+  return (
+    <ul className={cx('input-group range', set && 'set', className)} {...rest}>
+      <li>{withSize(from, size)}</li>
+      {/* 크기 클래스를 반드시 붙인다 — 빼면 킷 기본 56px 이라 medium 입력 사이에서 혼자 커진다. */}
+      <li className={cx('mark', size)} aria-hidden="true">
+        {separator}
+      </li>
+      <li>{withSize(to, size)}</li>
+    </ul>
+  );
+}

package/src/lib/krds.ts

@@ -0,0 +1,75 @@
+/**
+ * KRDS 공통 타입과 도우미.
+ *
+ * 여기 있는 값은 전부 킷(`public/krds/krds.min.css`)에서 실측한 것이다. 지어낸 값이 없다.
+ */
+
+/**
+ * 크기.
+ *
+ * ★ 버튼과 입력칸이 **같은 이름에 같은 높이**다. 실측(1rem = 10px):
+ *
+ * | 이름    | 높이 | 버튼 | 입력·셀렉트 |
+ * |---------|-----|------|------------|
+ * | xsmall  | 32  | ○    | —          |
+ * | small   | 40  | ○    | ○          |
+ * | medium  | 48  | ○    | ○          |
+ * | large   | 56  | ○    | ○          |
+ * | xlarge  | 64  | ○    | 80(예외)   |
+ *
+ * 그래서 한 줄에 놓을 버튼과 입력칸에는 **같은 size 를 준다.**
+ * 예전에 입력칸에 크기를 안 줘서 킷 기본값 large(56)로 렌더되고 옆 버튼은 small(40)이라
+ * 16px 이 어긋났다 — 부품에서 기본값을 명시해 이 실수를 구조적으로 막는다.
+ */
+export type KrdsSize = 'xsmall' | 'small' | 'medium' | 'large' | 'xlarge';
+
+/** 폼 요소가 실제로 지원하는 크기(킷에 xsmall 규칙이 없다). */
+export type KrdsFieldSize = Exclude<KrdsSize, 'xsmall'>;
+
+/**
+ * 의미 색상. 킷의 배지·태그·알림이 공통으로 쓰는 이름이다.
+ */
+export type KrdsTone =
+  | 'primary'
+  | 'secondary'
+  | 'gray'
+  | 'point'
+  | 'danger'
+  | 'warning'
+  | 'success'
+  | 'information';
+
+/** 폼 필드 상태. 킷 클래스는 `.is-error` · `.is-success` · `.is-information`. */
+export type KrdsFieldState = 'error' | 'success' | 'information';
+
+/**
+ * 킷이 제공하는 아이콘 이름(`ico-` 접두사를 뺀 것).
+ * `<i className="svg-icon ico-sch" />` 처럼 쓴다.
+ *
+ * 킷의 아이콘 파일은 `public/krds/img/component/icon/ico_*.svg` 에 있고 CSS 가 mask 로 물린다.
+ * **여기 없는 이름을 쓰면 검은 네모가 나온다** — 그래서 타입으로 좁혀 둔다.
+ * 아래 목록은 킷 CSS 에서 `\\.ico-([a-z0-9-]+)` 로 뽑은 68종 전부다. 킷을 올릴 때 다시 뽑는다.
+ */
+export type KrdsIcon =
+  | 'all' | 'angle' | 'blog' | 'bread-home' | 'cal-move' | 'calendar'
+  | 'call' | 'checkbox' | 'complete-fill' | 'del' | 'delete-fill' | 'down'
+  | 'ellipsis' | 'email' | 'error-fill' | 'facebook' | 'faq' | 'file'
+  | 'filter' | 'flag' | 'fold' | 'func' | 'global' | 'go'
+  | 'go-top' | 'help' | 'information-fill' | 'instagram' | 'invalid' | 'join'
+  | 'like' | 'link' | 'log' | 'login-go' | 'login-type01' | 'login-type02'
+  | 'login-type03' | 'login-type04' | 'login-type05' | 'login-type06' | 'logout' | 'modal-close'
+  | 'more' | 'my' | 'page-next' | 'plus' | 'popup-close' | 'print'
+  | 'pw-visible' | 'pw-visible-on' | 'refresh' | 'reset' | 'sch' | 'sch-plus'
+  | 'scrap' | 'search' | 'setting' | 'share' | 'sns-x' | 'success-fill'
+  | 'swiper-play' | 'swiper-stop' | 'toggle' | 'tooltip' | 'upload' | 'urgent-danger'
+  | 'view-mode' | 'youtube';
+
+/** 클래스 이름을 합친다. falsy 는 버린다. */
+export function cx(...parts: Array<string | false | null | undefined>): string {
+  return parts.filter(Boolean).join(' ');
+}
+
+/** 상태 → 킷 클래스. */
+export function stateClass(state?: KrdsFieldState): string | undefined {
+  return state && `is-${state}`;
+}

package/src/lib/link.tsx

@@ -0,0 +1,35 @@
+/**
+ * 링크 구현 — **이 묶음이 프레임워크에 닿는 유일한 자리다.**
+ *
+ * 부품 안에서 화면 이동이 필요할 때는 프레임워크의 링크를 직접 부르지 않고 여기 `UiLink` 를 쓴다.
+ * 그래서 Next·React Router·순수 React 어디에 올리든 **고칠 파일이 이 하나**다.
+ *
+ * 기본값은 맨 `<a>` 다 — 아무 프레임워크에도 묶이지 않는다.
+ * 클라이언트 라우팅을 쓰고 있다면 아래처럼 이 파일만 바꾼다.
+ *
+ * ```tsx
+ * // Next.js (App Router · Pages Router 공통)
+ * import NextLink from 'next/link';
+ * export function UiLink({ href, ...rest }: UiLinkProps) {
+ *   return <NextLink href={href} {...rest} />;
+ * }
+ *
+ * // React Router
+ * import { Link } from 'react-router';
+ * export function UiLink({ href, ...rest }: UiLinkProps) {
+ *   return <Link to={href} {...rest} />;
+ * }
+ * ```
+ *
+ * 왜 context 나 전역 등록이 아닌가 — 부품 중 절반이 서버 컴포넌트로도 쓰인다.
+ * React context 는 서버 컴포넌트에서 못 쓰고, 모듈 전역 등록은 서버와 클라이언트의
+ * 모듈 그래프가 갈라져 있어 한쪽만 설정되는 함정이 있다. 그냥 import 를 한 곳에 모으는 것이
+ * 가장 단순하고 양쪽에서 똑같이 동작한다.
+ */
+import type { ComponentPropsWithRef } from 'react';
+
+export type UiLinkProps = ComponentPropsWithRef<'a'> & { href: string };
+
+export function UiLink({ href, ...rest }: UiLinkProps) {
+  return <a href={href} {...rest} />;
+}