moru-krds-react 0.1.0

package/src/skeleton/index.tsx

@@ -0,0 +1,172 @@
+import type { ComponentPropsWithRef, ReactNode } from 'react';
+import { cx, type KrdsSize } from '../lib/krds';
+
+/**
+ * 스켈레톤(로딩 자리표시) — 킷에 클래스가 없다. KRDS 토큰으로 그리는 보충 부품이다.
+ *
+ * **올 것의 모양을 이미 아는 자리**(목록 행·카드·본문 문단)에 쓴다. 모양을 모르거나 좁은 자리는
+ * `ui/spinner`, 오래 걸리는 작업은 `ui/progress` 의 진행 막대다 — 한 화면에 섞어 쓰지 않는다.
+ * **크기는 `className` 으로 준다**(`<Skeleton className="h-4 w-40" />`).
+ * 자리표시는 전부 `aria-hidden` 이라 **`SkeletonGroup` 으로 감싸야** 로딩이 소리로 전해진다.
+ * 그 라이브 영역은 항상 DOM 에 두고 안의 내용만 바꾼다. 1초 미만이면 아예 쓰지 않는다.
+ *
+ * @example
+ * <SkeletonGroup loading={pending} label="목록을 불러오는 중" done="목록을 불러왔습니다">
+ *   <SkeletonText lines={5} />
+ * </SkeletonGroup>
+ * {!pending && <List items={items} />}
+ *
+ * 자세히: docs/krds/09-부품-노트.md#스켈레톤
+ */
+
+/** 자리표시의 모양. 둥글기가 갈린다. */
+export type SkeletonShape = 'block' | 'text' | 'circle';
+
+/** 모양 → 둥글기 유틸리티. 완성된 문자열로 적는다 — 조립하면 Tailwind 가 클래스를 만들지 않는다. */
+const SHAPE_RADIUS: Record<SkeletonShape, string> = {
+  block: 'rounded-md', // 6 — 버튼·입력칸과 같은 둥글기(--krds-radius-medium1)
+  text: 'rounded-sm', // 4 — 글줄 막대(--krds-radius-small1)
+  circle: 'rounded-full', // 아바타·아이콘 자리
+};
+
+export type SkeletonProps = ComponentPropsWithRef<'div'> & {
+  /** 모양. 기본 `block`(버튼·입력칸과 같은 둥글기). */
+  shape?: SkeletonShape;
+  /** 맥동을 끈다. 자리표시를 아주 많이 깔 때는 꺼서 시선을 덜 흔든다. */
+  animated?: boolean;
+};
+
+/**
+ * 자리표시 막대 하나. **크기는 반드시 `className` 으로 준다** — 부품에 기본 크기가 없다.
+ *
+ * @example
+ * <Skeleton className="h-4 w-40" />
+ * <Skeleton shape="circle" className="size-12" />
+ */
+export function Skeleton({ shape = 'block', animated = true, className, ...rest }: SkeletonProps) {
+  return (
+    <div
+      // aria-hidden 은 rest 보다 앞에 둔다 — 바깥에서 지울 길은 열어 두되 기본은 숨김이다.
+      aria-hidden="true"
+      className={cx(
+        'bg-surface-subtle',
+        SHAPE_RADIUS[shape],
+        // 기본 정지. 모션을 막지 않은 사용자에게만 맥동한다.
+        animated && 'motion-safe:animate-pulse',
+        className,
+      )}
+      {...rest}
+    />
+  );
+}
+
+/** 글줄 크기. KRDS 본문 글자 축과 같다 — 13 / 15 / 17 / 19px. */
+export type SkeletonTextSize = Exclude<KrdsSize, 'xlarge'>;
+
+/**
+ * 글줄 크기 → 막대 높이 + 줄 간격. 자리표시를 진짜 글로 바꿔도 높이가 변하지 않도록
+ * KRDS 줄 상자(글자 × 1.5)에 맞춰 골랐다.
+ */
+const TEXT_METRIC: Record<SkeletonTextSize, { bar: string; gap: string }> = {
+  xsmall: { bar: 'h-3', gap: 'gap-2' },
+  small: { bar: 'h-3', gap: 'gap-2.5' },
+  medium: { bar: 'h-4', gap: 'gap-2.5' },
+  large: { bar: 'h-4', gap: 'gap-3' },
+};
+
+/** 마지막 줄 폭. 문단 끝줄이 짧은 것을 흉내 낸다. */
+export type SkeletonLastLineWidth = 'full' | '4/5' | '3/5' | '1/2' | '2/5';
+
+/** 완성된 문자열로 적는다(Tailwind 스캐너). */
+const LAST_WIDTH: Record<SkeletonLastLineWidth, string> = {
+  full: 'w-full',
+  '4/5': 'w-4/5',
+  '3/5': 'w-3/5',
+  '1/2': 'w-1/2',
+  '2/5': 'w-2/5',
+};
+
+export type SkeletonTextProps = Omit<ComponentPropsWithRef<'div'>, 'children'> & {
+  /** 줄 수. **실제로 올 줄 수와 맞춘다** — 어긋나면 내용이 도착할 때 화면이 접힌다. */
+  lines?: number;
+  /** 글줄 크기. 기본 medium(17px 줄). */
+  size?: SkeletonTextSize;
+  /** 마지막 줄 폭. 기본 3/5. */
+  lastLineWidth?: SkeletonLastLineWidth;
+  /** 맥동을 끈다. */
+  animated?: boolean;
+};
+
+/**
+ * 여러 줄짜리 글 자리표시. 한 줄일 때는 끝줄을 줄이지 않는다.
+ *
+ * @example
+ * <SkeletonText lines={3} />
+ * <SkeletonText lines={1} size="large" className="w-1/3" />
+ */
+export function SkeletonText({
+  lines = 3,
+  size = 'medium',
+  lastLineWidth = '3/5',
+  animated = true,
+  className,
+  ...rest
+}: SkeletonTextProps) {
+  const { bar, gap } = TEXT_METRIC[size];
+  // 0줄·음수·소수를 막는다. 부모가 목록 길이를 그대로 넘기는 일이 흔하다.
+  const count = Math.max(1, Math.trunc(lines) || 1);
+
+  return (
+    <div aria-hidden="true" className={cx('flex flex-col', gap, className)} {...rest}>
+      {Array.from({ length: count }, (_, i) => (
+        <Skeleton
+          key={i}
+          shape="text"
+          animated={animated}
+          className={cx(bar, i === count - 1 && count > 1 ? LAST_WIDTH[lastLineWidth] : 'w-full')}
+        />
+      ))}
+    </div>
+  );
+}
+
+export type SkeletonGroupProps = ComponentPropsWithRef<'div'> & {
+  /** 참이면 자리표시를, 거짓이면 완료 문구만 라이브 영역에 담는다. */
+  loading: boolean;
+  /** 로딩 중 스크린리더 문구. */
+  label?: string;
+  /** 완료 시 스크린리더 문구. 빈 문자열이면 완료를 알리지 않는다. */
+  done?: string;
+  /** 자리표시들. */
+  children?: ReactNode;
+};
+
+/**
+ * 자리표시 묶음 + 로딩 알림 — 스켈레톤을 쓸 때 **이것으로 감싸는 것이 기본**이다.
+ *
+ * 이 라이브 영역은 **항상 DOM 에 두고 안의 내용만 바꾼다** — 통째로 넣었다 뺐다 하면
+ * 완료를 알릴 자리가 사라진다. `aria-live` · `aria-busy` 를 손으로 덮어쓰지 마라.
+ * 스피너 쪽 짝은 `ui/spinner` 의 `LoadingStatus` 다.
+ */
+export function SkeletonGroup({
+  loading,
+  label = '불러오는 중',
+  done = '불러왔습니다',
+  className,
+  children,
+  ...rest
+}: SkeletonGroupProps) {
+  return (
+    <div role="status" className={className} {...rest}>
+      {loading ? (
+        <>
+          {/* 킷 `.sr-only` — 화면에서 숨고 스크린리더만 읽는다. */}
+          <span className="sr-only">{label}</span>
+          {children}
+        </>
+      ) : (
+        <span className="sr-only">{done}</span>
+      )}
+    </div>
+  );
+}

package/src/skip-link/index.tsx

@@ -0,0 +1,89 @@
+import type { ComponentPropsWithRef, ReactNode } from 'react';
+import { cx } from '../lib/krds';
+
+/**
+ * 건너뛰기 링크 — KRDS `#krds-skip-link`.
+ *
+ * `<body>` 를 열자마자, 문서의 가장 첫 요소로 둔다. 링크는 3개까지고 첫 번째가 핵심 영역이다.
+ * 목적지에는 브레드크럼·사이드 메뉴 같은 반복 영역이 들어가면 안 된다 —
+ * 본문에 별도 앵커를 두고 `skipTargetProps()`(또는 `SkipTarget`)로 `tabIndex={-1}` 을 붙인다.
+ * 킷이 아이디 선택자로 모양을 잡으므로 한 문서에 하나만 둔다.
+ *
+ * @example
+ * <SkipLink links={[{ href: '#content', label: '본문 바로가기' }]} />
+ * <div {...skipTargetProps('content')}>…본문…</div>
+ *
+ * 자세히: docs/krds/09-부품-노트.md#건너뛰기링크
+ */
+
+/** 건너뛰기 링크 한 줄. */
+export type SkipLinkItem = {
+  /** 목적지 앵커. `#` 로 시작한다. */
+  href: string;
+  /** 링크 글자. 예: 「본문 바로가기」 */
+  label: string;
+};
+
+export type SkipLinkProps = Omit<ComponentPropsWithRef<'div'>, 'id' | 'children'> & {
+  /** 링크 목록. 첫 번째가 핵심 영역이다. 3개를 넘기면 개발 모드에서 경고하고 앞 3개만 그린다. */
+  links: SkipLinkItem[];
+  /** 탐색 랜드마크 이름. 기본 「건너뛰기 링크」. */
+  label?: string;
+};
+
+/** 규격이 정한 상한. */
+const MAX_LINKS = 3;
+
+export function SkipLink({ links, label = '건너뛰기 링크', className, ...rest }: SkipLinkProps) {
+  const shown = links.slice(0, MAX_LINKS);
+
+  if (process.env.NODE_ENV !== 'production' && links.length > MAX_LINKS) {
+    // 규격: 「개수는 3개 이내」. 조용히 자르지 않고 알린다.
+    console.warn(
+      `[SkipLink] 건너뛰기 링크는 3개 이내여야 한다(받은 개수 ${links.length}). 앞 ${MAX_LINKS}개만 그린다.`,
+    );
+  }
+
+  return (
+    <div
+      // 킷이 이 id 에 모양을 전부 걸어 두어 기본 클래스가 없다 — 빈 class 를 남기지 않는다.
+      className={cx(className) || undefined}
+      role="navigation"
+      aria-label={label}
+      {...rest}
+      // id 는 킷 CSS 가 물고 있는 선택자다. rest 로 덮이지 않도록 마지막에 고정한다.
+      id="krds-skip-link"
+    >
+      {shown.map((item) => (
+        <a key={item.href} href={item.href}>
+          {item.label}
+        </a>
+      ))}
+    </div>
+  );
+}
+
+/**
+ * 건너뛰기 목적지에 붙일 속성. `tabIndex={-1}` 이 있어야 앵커 이동이 초점까지 옮긴다.
+ *
+ * @example
+ * <div {...skipTargetProps('content')}>…본문…</div>
+ */
+export function skipTargetProps(id: string): { id: string; tabIndex: number } {
+  return { id, tabIndex: -1 };
+}
+
+/** 목적지 감싸개 — {@link skipTargetProps} 를 바로 쓰는 형태. 클래스는 붙이지 않는다. */
+export type SkipTargetProps = ComponentPropsWithRef<'div'> & {
+  id: string;
+  children?: ReactNode;
+};
+
+export function SkipTarget({ id, className, children, ...rest }: SkipTargetProps) {
+  return (
+    // tabIndex 는 규격이 요구하는 것이라 rest 로 덮이지 않게 뒤에 둔다.
+    <div className={cx(className) || undefined} {...rest} {...skipTargetProps(id)}>
+      {children}
+    </div>
+  );
+}

package/src/spinner/index.tsx

@@ -0,0 +1,98 @@
+import type { ComponentPropsWithRef, ReactNode } from 'react';
+import { cx } from '../lib/krds';
+
+/**
+ * 스피너 — KRDS `krds-spinner`.
+ *
+ * **모양을 모르거나 좁은 자리**(버튼 안·입력칸 안·화면 한복판)의 로딩 표시다.
+ * 올 것의 모양을 아는 목록·카드는 `ui/skeleton`, 진행을 셀 수 있으면 `ui/progress` 다 —
+ * 한 화면에 섞어 쓰지 않는다. 1초 미만이면 아예 쓰지 않는다.
+ * 크기 변형이 없다(지름 20px 고정) — 넓은 영역에서는 `className` 으로 여백을 벌린다.
+ * 시작과 완료를 둘 다 알리려면 {@link LoadingStatus} 로 감싼다.
+ * 입력칸 안에 겹치려면 {@link FormSpinner} 안에 넣는다.
+ *
+ * @example
+ * <LoadingStatus loading={busy} label="목록을 불러오는 중" done="목록을 불러왔습니다">
+ *   불러오는 중…
+ * </LoadingStatus>
+ * <FormSpinner>
+ *   <TextInput id="q" readOnly />
+ *   <Spinner label="조회 중" />
+ * </FormSpinner>
+ *
+ * 자세히: docs/krds/09-부품-노트.md#스피너
+ */
+export type SpinnerProps = ComponentPropsWithRef<'div'> & {
+  /** 스크린리더가 읽을 상태 문구. 회전 원뿐이라 이것이 없으면 소리로 아무것도 남지 않는다. */
+  label?: string;
+  /** 눈에 보이는 문구. 없어도 된다. */
+  children?: ReactNode;
+};
+
+export function Spinner({ label = '로딩 중', className, children, ...rest }: SpinnerProps) {
+  return (
+    // role 은 rest 보다 앞에 둔다 — 바깥에 라이브 영역이 이미 있으면 `role={undefined}` 로 지운다.
+    <div role="status" className={cx('krds-spinner', className)} {...rest}>
+      <span className="sr-only">{label}</span>
+      {children}
+    </div>
+  );
+}
+
+/**
+ * 입력칸 안 스피너 감싸개 — 킷 `form-spinner`. 이 안에 넣어야 스피너가 입력칸 오른쪽 안쪽에 겹친다.
+ * 스피너가 글자 위를 덮으므로 조회 중에는 입력칸을 `readOnly` 로 두는 편이 낫다.
+ *
+ * @example
+ * <FormSpinner>
+ *   <TextInput id="q" readOnly />
+ *   <Spinner label="조회 중" />
+ * </FormSpinner>
+ */
+export function FormSpinner({ className, children, ...rest }: ComponentPropsWithRef<'div'>) {
+  return (
+    <div className={cx('form-spinner', className)} {...rest}>
+      {children}
+    </div>
+  );
+}
+
+/**
+ * 로딩 상태 알림 — 킷에 없다. 시작과 완료 **두 시점**을 소리로 알리려고 덧붙인 조합이다.
+ *
+ * 이 라이브 영역은 **항상 DOM 에 두고 안의 내용만 바꾼다** — 통째로 넣었다 뺐다 하면
+ * 완료를 알릴 자리가 사라진다. 스켈레톤 쪽 짝은 `ui/skeleton` 의 `SkeletonGroup` 이다.
+ */
+export type LoadingStatusProps = Omit<ComponentPropsWithRef<'div'>, 'children'> & {
+  /** 참이면 스피너를, 거짓이면 완료 문구를 라이브 영역에 담는다. */
+  loading: boolean;
+  /** 로딩 중 스크린리더 문구. */
+  label?: string;
+  /** 완료 시 스크린리더 문구. 빈 문자열이면 완료를 알리지 않는다. */
+  done?: string;
+  /** 로딩 중 눈에 보이는 문구. */
+  children?: ReactNode;
+};
+
+export function LoadingStatus({
+  loading,
+  label = '로딩 중',
+  done = '로딩이 완료되었습니다',
+  className,
+  children,
+  ...rest
+}: LoadingStatusProps) {
+  return (
+    <div role="status" className={className} {...rest}>
+      {loading ? (
+        // 바깥이 이미 라이브 영역이라 안쪽 role 은 지운다.
+        <Spinner role={undefined} label={label}>
+          {children}
+        </Spinner>
+      ) : (
+        // 완료 문구는 눈에 보일 필요가 없다. 킷 `.sr-only` 로 숨긴다.
+        <span className="sr-only">{done}</span>
+      )}
+    </div>
+  );
+}

package/src/step-indicator/index.tsx

@@ -0,0 +1,122 @@
+import type { ComponentPropsWithRef, ReactNode } from 'react';
+import { cx } from '../lib/krds';
+
+/**
+ * 단계 표시기 — KRDS `krds-step-wrap`.
+ *
+ * 다단계 신청 화면 위에 놓는다. **단계는 3~7개**이고 어기면 개발 모드에서 경고한다.
+ * `current` 는 0부터 센다 — `steps.length` 를 주면 전부 완료, 음수면 전부 예정이다.
+ * 연결선·완료 체크 아이콘·여백은 킷이 그리므로 마크업이나 `mb-*` 를 더하지 마라.
+ * 레이블은 짧게 쓴다 — 킷이 줄바꿈을 막아 길면 넘쳐 잘린다.
+ * 좁은 화면에서 킷이 글자를 전부 숨기므로 「N단계 중 M단계」 요약을 부품이 대신 그린다.
+ *
+ * @example
+ * <StepIndicator current={2} steps={['유의 사항 확인', '신청인 정보', '이사 전 살던 곳', '이사 온 곳']} />
+ *
+ * 자세히: docs/krds/09-부품-노트.md#단계표시
+ */
+
+/** 단계 하나의 상태. 완료 `done` · 현재 `active` · 예정 `todo`. */
+export type StepStatus = 'done' | 'active' | 'todo';
+
+export type StepItem = {
+  /** 단계 레이블. 짧은 단어·문구로 — 길면 줄바꿈 없이 잘린다. */
+  label: ReactNode;
+  /** 단계 번호 글자. 생략하면 「N단계」. 다국어는 여기로 넘긴다. */
+  number?: ReactNode;
+  /** 상태를 손으로 정한다. 생략하면 `current` 로 계산한다 — 순서대로 떨어지지 않을 때만 쓴다. */
+  status?: StepStatus;
+};
+
+export type StepIndicatorProps = Omit<ComponentPropsWithRef<'div'>, 'children'> & {
+  /** 단계 목록. 문자열만 주면 레이블로 본다. 규격 상한·하한은 3~7 이다. */
+  steps: Array<string | StepItem>;
+  /** 현재 단계의 **0부터 센 번호**. `steps.length` 면 전부 완료, 음수면 전부 예정이다. */
+  current: number;
+  /** 현재 단계임을 알리는 숨은 글자. 기본 「현재단계」. */
+  currentLabel?: string;
+  /** 좁은 화면 요약을 직접 정한다. 생략하면 「N단계 중 M단계 + 레이블」. */
+  summary?: ReactNode;
+  /** 좁은 화면 요약을 끄고 킷 그대로(원만 남는 모습) 둔다. */
+  hideSummary?: boolean;
+  /** 감싸개에 붙일 클래스. */
+  className?: string;
+};
+
+/** 규격이 정한 단계 수의 하한·상한. */
+const MIN_STEPS = 3;
+const MAX_STEPS = 7;
+
+export function StepIndicator({
+  steps,
+  current,
+  currentLabel = '현재단계',
+  summary,
+  hideSummary,
+  className,
+  ...rest
+}: StepIndicatorProps) {
+  if (!steps.length) return null;
+
+  if (
+    process.env.NODE_ENV !== 'production' &&
+    (steps.length < MIN_STEPS || steps.length > MAX_STEPS)
+  ) {
+    console.warn(
+      `[StepIndicator] 단계는 ${MIN_STEPS}개 이상 ${MAX_STEPS}개 이하여야 한다(받은 개수 ${steps.length}). 그대로 그리되 절차를 다시 나눠라.`,
+    );
+  }
+
+  const items: StepItem[] = steps.map((step) =>
+    typeof step === 'string' ? { label: step } : step,
+  );
+
+  // 현재 단계가 목록 안에 있을 때만 요약을 그린다(전부 완료·전부 예정이면 셀 「M단계」가 없다).
+  const activeIndex = current >= 0 && current < items.length ? current : -1;
+
+  return (
+    // 킷에 감싸개 클래스가 없다. 빈 class 를 남기지 않는다.
+    <div className={cx(className) || undefined} {...rest}>
+      {!hideSummary && activeIndex >= 0 && (
+        // 좁은 화면 요약. 킷이 글자를 전부 숨기는 767px 이하에서만 보인다.
+        // 숨긴 글자는 DOM 에 남아 스크린리더가 읽으므로 이 요약은 aria-hidden 이다.
+        <p className="mb-2 text-sm md:hidden" aria-hidden="true">
+          {summary ?? (
+            <>
+              <span className="text-fg-subtle">{`${items.length}단계 중 ${activeIndex + 1}단계`}</span>
+              <span className="ml-2 font-bold text-fg">{items[activeIndex]!.label}</span>
+            </>
+          )}
+        </p>
+      )}
+
+      <ol
+        className="krds-step-wrap"
+        // 킷 전역 `ol,ul{list-style:none}` 이 목록 의미를 떨어뜨리는 브라우저가 있어 되돌린다.
+        role="list"
+      >
+        {items.map((item, i) => {
+          const status: StepStatus =
+            item.status ?? (i < current ? 'done' : i === current ? 'active' : 'todo');
+          const isActive = status === 'active';
+
+          return (
+            <li
+              key={i}
+              className={status === 'todo' ? undefined : status}
+              // ARIA 에 더 정확한 값 `step` 이 있지만 KRDS 가 적은 값은 `true` 다 — 규격을 따른다.
+              aria-current={isActive ? 'true' : undefined}
+            >
+              <span>
+                {/* 킷이 `.sr-only` 를 !important 로 숨긴다 — 화면에는 안 보이고 낭독만 된다. */}
+                {isActive && <em className="sr-only">{currentLabel}</em>}
+                <i className="step">{item.number ?? `${i + 1}단계`}</i>
+                <span className="step-tit">{item.label}</span>
+              </span>
+            </li>
+          );
+        })}
+      </ol>
+    </div>
+  );
+}