moru-krds-react 0.1.0

package/src/text-input/index.tsx

@@ -0,0 +1,156 @@
+import type { ComponentPropsWithRef } from 'react';
+import { Field, type FieldProps } from '../field';
+import { cx, type KrdsFieldSize } from '../lib/krds';
+
+/**
+ * 텍스트 입력 — KRDS `krds-input`.
+ *
+ * `TextInput` 은 `<input>` 하나만 그린다. 레이블·도움말까지 한꺼번에 필요하면 {@link TextField},
+ * 골격을 조각으로 짤 때는 `ui/field` 의 `Field` 를 쓴다.
+ * 크기 기본이 medium(48px)이라 같은 줄의 버튼과 어긋나지 않는다(킷 기본은 large 56px).
+ * **`size` 를 `<textarea>` 에 붙이면 높이가 48px 로 찌부러진다** — 그래서 `ui/textarea` 에는 없다.
+ * 돋보기가 겹친 검색칸은 {@link SearchInput}, 제안 목록까지 필요하면 `ui/combobox` 다.
+ *
+ * @example
+ * <TextField id="consult_name" label="성명" hint="주민등록상 성명" required placeholder="예) 김모루" />
+ * <InputGroup>
+ *   <InputGroupItem><TextInput id="q" /></InputGroupItem>
+ *   <Button variant="primary" type="submit">검색</Button>
+ * </InputGroup>
+ *
+ * 자세히: docs/krds/09-부품-노트.md#텍스트입력
+ */
+
+/* ────────────────────────────── 입력칸 ────────────────────────────── */
+
+/**
+ * 입력칸 하나 — `<input class="krds-input">`. 골격은 `ui/field` 가 맡는다.
+ * HTML `size` 속성(글자 수)은 지원하지 않는다 — 너비는 `className` 으로 잡는다.
+ */
+export type TextInputProps = Omit<ComponentPropsWithRef<'input'>, 'size'> & {
+  /** 기본 medium(48px). 같은 줄의 버튼과 같은 값을 준다. */
+  size?: KrdsFieldSize;
+};
+
+export function TextInput({ size = 'medium', type = 'text', className, ...rest }: TextInputProps) {
+  return <input type={type} className={cx('krds-input', size, className)} {...rest} />;
+}
+
+/* ────────────────────────────── 레이블·도움말까지 붙은 완성형 ────────────────────────────── */
+
+/**
+ * 레이블 · 도움말까지 붙은 텍스트 한 줄 — `Field` + `TextInput` 을 조립한 편의 부품이다.
+ *
+ * 골격 prop(`hint` · `state` · `message` · `error` · `required` · `action` · `deletable` …)은
+ * `Field` 의 것을 그대로 받고 나머지는 `<input>` 으로 간다.
+ * 컨트롤이 입력칸이 아니거나 한 칸에 요소가 여럿이면 `Field` 를 직접 쓴다.
+ */
+export type TextFieldProps = Omit<TextInputProps, 'className'> &
+  Pick<
+    FieldProps,
+    | 'label'
+    | 'hideLabel'
+    | 'hint'
+    | 'state'
+    | 'message'
+    | 'error'
+    | 'action'
+    | 'deletable'
+    | 'describedBy'
+    | 'contentProps'
+    | 'standalone'
+  > & {
+    /** `<label for>` 로 이어야 하므로 필수다(서버 컴포넌트라 `useId` 를 쓸 수 없다). */
+    id: string;
+    /** `.form-group` 에 붙는다. 바깥 여백은 여기서 조절한다. */
+    className?: string;
+    /** `<input>` 에 붙는다(너비 고정 등). */
+    inputClassName?: string;
+  };
+
+export function TextField({
+  id,
+  label,
+  hideLabel,
+  hint,
+  state,
+  message,
+  error,
+  required,
+  action,
+  deletable,
+  describedBy,
+  contentProps,
+  standalone,
+  className,
+  inputClassName,
+  size = 'medium',
+  'aria-describedby': ariaDescribedBy,
+  ...rest
+}: TextFieldProps) {
+  return (
+    <Field
+      id={id}
+      label={label}
+      hideLabel={hideLabel}
+      hint={hint}
+      state={state}
+      message={message}
+      error={error}
+      required={required}
+      // 바깥에서 준 aria-describedby 는 버리지 않는다 — `Field` 가 도움말·메시지 id 를 뒤에 잇는다.
+      describedBy={cx(describedBy, ariaDescribedBy) || undefined}
+      action={action}
+      deletable={deletable}
+      contentProps={contentProps}
+      standalone={standalone}
+      className={className}
+    >
+      {(a) => <TextInput {...a} size={size} className={inputClassName} {...rest} />}
+    </Field>
+  );
+}
+
+/* ────────────────────────────── 검색 입력 ────────────────────────────── */
+
+/**
+ * 돋보기가 겹쳐진 검색 입력 — 킷 `sch-input`.
+ *
+ * 기본이 `type="submit"` 이라 `<form action>` 안에 두면 JS 없이도 검색이 된다.
+ * 실시간 제안 목록·검색어 삭제까지 필요하면 `ui/combobox` 의 `SearchCombobox` 다.
+ *
+ * @example
+ * <form action="/search">
+ *   <SearchInput name="q" placeholder="검색어를 입력하세요" />
+ * </form>
+ */
+export type SearchInputProps = Omit<TextInputProps, 'type'> & {
+  /** 돋보기 버튼의 접근 가능한 이름. 아이콘만 있는 버튼이라 반드시 있어야 한다. */
+  buttonLabel?: string;
+  /** 버튼에 그대로 흘릴 속성(onClick 등). */
+  buttonProps?: Omit<ComponentPropsWithRef<'button'>, 'type' | 'className' | 'children'>;
+  /** 버튼 종류. 기본 `submit`. */
+  buttonType?: 'submit' | 'button';
+  /** `.sch-input` 감싸개에 붙는다. 너비·여백은 여기서 조절한다. */
+  wrapperClassName?: string;
+};
+
+export function SearchInput({
+  size = 'medium',
+  buttonLabel = '검색',
+  buttonProps,
+  buttonType = 'submit',
+  wrapperClassName,
+  className,
+  ...rest
+}: SearchInputProps) {
+  return (
+    <div className={cx('sch-input', wrapperClassName)}>
+      <TextInput type="text" size={size} className={className} {...rest} />
+      <button type={buttonType} className="krds-btn medium icon ico-search" {...buttonProps}>
+        <span className="sr-only">{buttonLabel}</span>
+        <i className="svg-icon ico-sch" aria-hidden="true" />
+      </button>
+    </div>
+  );
+}

package/src/text-list/index.tsx

@@ -0,0 +1,177 @@
+import { Children, cloneElement, isValidElement } from 'react';
+import type { ComponentPropsWithRef, ReactNode } from 'react';
+import { cx } from '../lib/krds';
+
+/**
+ * 텍스트 목록 — KRDS `krds-info-list`.
+ *
+ * 안내 문구 묶음·절차·요건처럼 **줄 단위로 끊어 읽는 글**에 쓴다.
+ * 순서가 없으면 `TextList`, 순서·순위가 있으면 `OrderedTextList` 다(번호는 부품이 채운다).
+ * 들여쓰기·간격·글자 크기는 킷이 **DOM 깊이**로 정한다 — 중첩 목록은 `TextListItem` 의
+ * **직계 자식**으로 넣어야 하고, 사이에 `<div>` 를 하나만 끼워도 깊이 1 로 돌아간다.
+ * 수준은 3 이내다. 여러 차원의 자료는 표, 긴 서술은 문단으로 간다.
+ *
+ * @example
+ * <TextList marker="dot">
+ *   <TextListItem>
+ *     신청 자격
+ *     <TextList marker="dash">
+ *       <TextListItem>만 18세 이상</TextListItem>
+ *     </TextList>
+ *   </TextListItem>
+ * </TextList>
+ * <OrderedTextList numbering="decimal">
+ *   <TextListItem>신청서를 내려받습니다.</TextListItem>
+ *   <TextListItem>작성해 방문 접수합니다.</TextListItem>
+ * </OrderedTextList>
+ *
+ * 자세히: docs/krds/09-부품-노트.md#텍스트목록
+ */
+
+/**
+ * 글머리 기호. `dot` ● (1수준) · `dash` - (2수준) · `circle` ○ (3수준)이 킷 샘플의 관례다.
+ * **1수준에 `circle` 을 주면 들여쓰기가 얕아진다** — 킷이 ○ 를 막내 수준으로 전제한다.
+ */
+export type TextListMarker = 'dot' | 'dash' | 'circle';
+
+/** 뜻 → 킷 클래스. 킷의 `decimal` 은 숫자가 아니라 **채운 점(●)** 이라 이름을 한 겹 감쌌다. */
+const MARKER_CLASS: Record<TextListMarker, string> = {
+  dot: 'decimal',
+  dash: 'dash',
+  circle: 'hollow',
+};
+
+export type TextListProps = ComponentPropsWithRef<'ul'> & {
+  /** 글머리 기호. 기본 `dot`(●). */
+  marker?: TextListMarker;
+};
+
+/** 순서 없는 텍스트 목록. 순서·순위가 있으면 {@link OrderedTextList} 로 간다. */
+export function TextList({
+  marker = 'dot',
+  className,
+  children,
+  role = 'list',
+  ...rest
+}: TextListProps) {
+  return (
+    <ul role={role} className={cx('krds-info-list', MARKER_CLASS[marker], className)} {...rest}>
+      {children}
+    </ul>
+  );
+}
+
+/** 번호 표기 방식. 킷 샘플의 수준별 관례는 1수준 `1. ` · 2수준 `a. ` · 3수준 `①` 이다. */
+export type TextListNumbering = 'decimal' | 'alpha' | 'circled' | 'hangul';
+
+/** 가·나·다… 14자. 넘으면 숫자로 되돌린다. */
+const HANGUL_ORDINALS = ['가', '나', '다', '라', '마', '바', '사', '아', '자', '차', '카', '타', '파', '하'];
+
+/** a, b, … z, aa, ab … (26 넘어가면 두 글자). */
+function alphaOrdinal(n: number): string {
+  let out = '';
+  let v = n;
+  while (v > 0) {
+    const r = (v - 1) % 26;
+    out = String.fromCharCode(97 + r) + out;
+    v = Math.floor((v - 1) / 26);
+  }
+  return out;
+}
+
+/** 번호 글자를 만든다. `decimal`·`alpha`·`hangul` 은 뒤에 공백이 붙고 `circled` 는 붙지 않는다. */
+function formatOrdinal(kind: TextListNumbering, n: number): string {
+  switch (kind) {
+    // ①~⑳ 는 U+2460 부터 20자뿐이다. 넘어가면 숫자로 되돌린다.
+    case 'circled':
+      return n >= 1 && n <= 20 ? String.fromCharCode(0x2460 + n - 1) : `${n}. `;
+    case 'alpha':
+      return `${alphaOrdinal(n)}. `;
+    case 'hangul':
+      return n >= 1 && n <= HANGUL_ORDINALS.length ? `${HANGUL_ORDINALS[n - 1]}. ` : `${n}. `;
+    default:
+      return `${n}. `;
+  }
+}
+
+export type OrderedTextListProps = ComponentPropsWithRef<'ol'> & {
+  /**
+   * 자식 항목에 번호 글자를 자동으로 채운다. 기본 `decimal`. 항목이 `num` 을 주면 그쪽이 이긴다.
+   * `false` 면 채우지 않는다 — 이때 `num` 을 안 주면 화면에 기호가 하나도 안 나온다.
+   */
+  numbering?: TextListNumbering | false;
+};
+
+/**
+ * 순서 있는 텍스트 목록. **킷은 번호를 CSS 로 그리지 않아** 이 부품이 자식을 세어 채운다.
+ *
+ * 번호 자리는 들여쓰기 폭만큼이라 **넘치면 본문 글자와 겹친다** —
+ * 깊이 3 에서 두 자리 숫자를 쓰면 겹치므로 그 수준은 `circled` 가 안전하다.
+ */
+export function OrderedTextList({
+  numbering = 'decimal',
+  className,
+  children,
+  role = 'list',
+  ...rest
+}: OrderedTextListProps) {
+  let seq = 0;
+  const numbered =
+    numbering === false
+      ? children
+      : Children.map(children, (child) => {
+          // TextListItem 이 아닌 것(문자열·조건부 false·다른 요소)은 세지도 건드리지도 않는다.
+          if (!isValidElement<TextListItemProps>(child) || child.type !== TextListItem) return child;
+          seq += 1;
+          // 직접 적은 번호가 우선이다. 순서는 이미 셌으니 다음 항목이 이어받는다.
+          if (child.props.num !== undefined && child.props.num !== null) return child;
+          return cloneElement(child, { num: formatOrdinal(numbering, seq) });
+        });
+
+  return (
+    <ol role={role} className={cx('krds-info-list', 'ordered', className)} {...rest}>
+      {numbered}
+    </ol>
+  );
+}
+
+export type TextListItemProps = ComponentPropsWithRef<'li'> & {
+  /**
+   * 번호 글자. 보통 `OrderedTextList` 가 채워 주므로 직접 줄 일이 드물다
+   * (조문 번호처럼 연속이 아닌 번호를 쓸 때만). 순서 없는 목록에는 주지 않는다.
+   */
+  num?: ReactNode;
+};
+
+/**
+ * 목록 항목 — `<li>`. 모양은 전부 부모 목록의 **DOM 깊이**에서 온다.
+ * 중첩 목록은 이 안에 **바로** 넣는다 — 사이에 요소를 끼우면 깊이가 깨진다.
+ */
+export function TextListItem({
+  num,
+  className,
+  children,
+  role = 'listitem',
+  ...rest
+}: TextListItemProps) {
+  return (
+    <li role={role} className={className} {...rest}>
+      {num !== undefined && num !== null && <span className="num">{num}</span>}
+      {children}
+    </li>
+  );
+}
+
+/**
+ * 항목에 딸린 보조 설명 — 킷 `info-txt`. **`TextListItem` 의 직계 자식일 때만** 여백이 붙는다.
+ * 항목 본문을 한 줄 더 잇는 용도지 독립한 문단이 아니다.
+ */
+export function TextListNote({ className, children, ...rest }: ComponentPropsWithRef<'p'>) {
+  return (
+    <p className={cx('info-txt', className)} {...rest}>
+      {children}
+    </p>
+  );
+}
+
+// 킷에 모양이 없어 지원하지 않는 것: `fraction`(클래스 이름만 있고 규칙이 0건이다).

package/src/textarea/index.tsx

@@ -0,0 +1,113 @@
+'use client';
+
+import {
+  useId,
+  useState,
+  type ChangeEvent,
+  type ComponentPropsWithRef,
+  type ReactNode,
+} from 'react';
+import { cx, stateClass, type KrdsFieldState } from '../lib/krds';
+
+/**
+ * 텍스트 영역 — KRDS `textarea-wrap` + `krds-input`.
+ *
+ * **`maxLength` 를 주면 글자 수 표시가 저절로 켜진다**(규격 요구) — 끄려면 `showCount={false}`.
+ * 크기 prop 이 없다. 킷 크기 클래스를 붙이면 높이가 한 줄 입력칸(48px)으로 찌부러지기 때문이다 —
+ * 높이는 `className="h-60"` 처럼 유틸리티로 준다(킷 기본은 144px). `rows` 는 아무 영향이 없다.
+ * `error` 의 붉은 글씨·아이콘은 `.form-group` 안에서만 나오므로 `ui/field` 의 `Field` 안에 둔다.
+ *
+ * @example
+ * <Field id="content" label="내용">
+ *   {(a) => <Textarea {...a} maxLength={500} placeholder="500자 이내로 입력하세요" />}
+ * </Field>
+ *
+ * 자세히: docs/krds/09-부품-노트.md#텍스트영역
+ */
+export type TextareaProps = ComponentPropsWithRef<'textarea'> & {
+  /** 필드 상태. */
+  state?: KrdsFieldState;
+  /** 오류 문구. 주면 글자 수와 한 줄에 나란히 놓고 `aria-invalid`·`aria-describedby` 를 건다. */
+  error?: ReactNode;
+  /** 글자 수 표시. 기본값은 `maxLength` 가 있으면 켬(규격 요구). */
+  showCount?: boolean;
+  /** 감싸개에 붙일 클래스(바깥 여백 등). `className` 은 `<textarea>` 로 간다. */
+  wrapClassName?: string;
+};
+
+/** `value`·`defaultValue` 가 받아들이는 세 형태를 글자열로 맞춘다. */
+function toText(value: TextareaProps['value'] | TextareaProps['defaultValue']): string {
+  if (value == null) return '';
+  return Array.isArray(value) ? value.join('') : String(value);
+}
+
+export function Textarea({
+  state,
+  error,
+  showCount,
+  wrapClassName,
+  className,
+  maxLength,
+  value,
+  defaultValue,
+  onChange,
+  'aria-describedby': ariaDescribedBy,
+  ...rest
+}: TextareaProps) {
+  const uid = useId();
+  const countId = `${uid}-count`;
+  const errorId = `${uid}-error`;
+
+  // 규격: 글자 수 제한이 있으면 글자 수를 보여 준다. 세는 값은 브라우저와 같은 UTF-16 길이다.
+  const counting = showCount ?? maxLength !== undefined;
+  const controlled = value !== undefined;
+
+  const [typed, setTyped] = useState(() => toText(defaultValue));
+  const length = (controlled ? toText(value) : typed).length;
+
+  function handleChange(event: ChangeEvent<HTMLTextAreaElement>) {
+    // 세지 않거나 바깥에서 값을 쥐고 있으면 여기서 다시 그릴 이유가 없다.
+    if (counting && !controlled) setTyped(event.target.value);
+    onChange?.(event);
+  }
+
+  const fieldState = state ?? (error ? 'error' : undefined);
+
+  // 도움말·글자 수를 스크린리더에 연결한다. 바깥에서 준 aria-describedby 는 버리지 않고 앞에 둔다.
+  const describedBy =
+    cx(ariaDescribedBy, error ? errorId : undefined, counting ? countId : undefined) || undefined;
+
+  const count = counting ? (
+    <p className="textarea-count" id={countId}>
+      {/* 킷 샘플에는 없는 보충 — 숫자만으로는 무엇인지 읽히지 않는다. */}
+      <span className="sr-only">입력 글자 수</span>
+      <span className="count-now">{length}</span>
+      {maxLength !== undefined && <span className="count-total">/{maxLength}</span>}
+    </p>
+  ) : null;
+
+  return (
+    <div className={cx('textarea-wrap', stateClass(fieldState), wrapClassName)}>
+      <textarea
+        className={cx('krds-input', className)}
+        maxLength={maxLength}
+        value={value}
+        defaultValue={defaultValue}
+        onChange={handleChange}
+        aria-describedby={describedBy}
+        aria-invalid={fieldState === 'error' || undefined}
+        {...rest}
+      />
+      {error ? (
+        <div className="textarea-bottom">
+          <p className="form-hint-invalid" id={errorId}>
+            {error}
+          </p>
+          {count}
+        </div>
+      ) : (
+        count
+      )}
+    </div>
+  );
+}