feat: provide reusable UI and state galleries

2026-07-25 23:59:12 +09:00
parent a8e3db1aec
commit 3581ead595
17 changed files with 1167 additions and 34 deletions
@@ -1,23 +1,40 @@
+import { useId } from "react";
+
+import { errorMessage } from "./error-copy.js";
+import { Button } from "./ui/button.jsx";
+
 /** @param {{ label?: string }} props */
 export function LoadingSurface({ label = "불러오는 중" }) {
  return (
    <section
+      className="state-surface state-surface--loading"
      aria-busy="true"
      aria-label={label}
      aria-live="polite"
      aria-atomic="true"
    >
      <div className="ui-skeleton" aria-hidden="true" />
-      <span className="sr-only">{label}</span>
+      <span className="visually-hidden">{label}</span>
    </section>
  );
 }

-/** @param {{ title?: string, action?: React.ReactNode }} props */
-export function EmptySurface({ title = "표시할 항목이 없습니다.", action }) {
+/**
+ * @param {{
+ *   title?: string,
+ *   description?: string,
+ *   action?: React.ReactNode
+ * }} props
+ */
+export function EmptySurface({
+  title = "표시할 항목이 없습니다.",
+  description,
+  action,
+}) {
  return (
-    <section className="ui-empty" aria-live="polite">
-      <p>{title}</p>
+    <section className="ui-empty state-surface" aria-live="polite">
+      <h2>{title}</h2>
+      {description ? <p>{description}</p> : null}
      {action}
    </section>
  );
@@ -32,17 +49,24 @@ export function EmptySurface({ title = "표시할 항목이 없습니다.", acti
 * }} props
 */
 export function TerminalErrorSurface({ userMessageKey, action, onAction }) {
+  const messageId = useId();
+  const actionLabels = Object.freeze({
+    retry: "다시 시도",
+    reauth: "로그인",
+    navigate: "안전한 화면으로 이동",
+    "reload-once": "한 번 새로고침",
+    "contact-support": "지원 정보 확인",
+  });
  return (
    <section
-      className="ui-terminal-error"
+      className="ui-terminal-error state-surface state-surface--danger"
      role="alert"
-      aria-labelledby="terminal-error-message"
+      aria-labelledby={messageId}
+      data-message-key={userMessageKey}
    >
-      <p id="terminal-error-message">{userMessageKey}</p>
+      <h2 id={messageId}>{errorMessage(userMessageKey)}</h2>
      {action !== "none" && (
-        <button className="ui-button" type="button" onClick={onAction}>
-          {action}
-        </button>
+        <Button onClick={onAction}>{actionLabels[action]}</Button>
      )}
    </section>
  );
@@ -0,0 +1,21 @@
+const ERROR_MESSAGES = Object.freeze({
+  "error.network_unreachable": "네트워크에 연결할 수 없습니다.",
+  "error.request_timeout": "요청 시간이 초과되었습니다.",
+  "error.auth_required": "계속하려면 로그인이 필요합니다.",
+  "error.auth_integration_failure": "로그인 연동을 사용할 수 없습니다.",
+  "error.forbidden": "이 작업을 수행할 권한이 없습니다.",
+  "error.not_found": "요청한 항목을 찾을 수 없습니다.",
+  "error.rate_limited": "요청이 많습니다. 잠시 후 다시 시도해 주세요.",
+  "error.server_failure": "요청을 완료하지 못했습니다.",
+  "error.chunk_load_failure": "새 화면 파일을 불러오지 못했습니다.",
+  "error.render_failure": "화면을 표시하지 못했습니다.",
+  "error.unknown_failure": "예상하지 못한 문제가 발생했습니다.",
+});
+
+/** @param {string} messageKey */
+export function errorMessage(messageKey) {
+  const messages = /** @type {Readonly<Record<string, string>>} */ (
+    ERROR_MESSAGES
+  );
+  return messages[messageKey] ?? "요청을 완료하지 못했습니다.";
+}
@@ -0,0 +1,69 @@
+import { Button } from "./ui/button.jsx";
+
+/**
+ * @param {{
+ *   eyebrow: string,
+ *   title: string,
+ *   description: string,
+ *   actionLabel?: string,
+ *   onAction?: () => void,
+ *   tone?: "neutral" | "danger" | "warning"
+ * }} props
+ */
+function StateSurface({
+  eyebrow,
+  title,
+  description,
+  actionLabel,
+  onAction,
+  tone = "neutral",
+}) {
+  return (
+    <section className={`state-surface state-surface--${tone}`}>
+      <p className="state-surface__eyebrow">{eyebrow}</p>
+      <h2>{title}</h2>
+      <p>{description}</p>
+      {actionLabel ? <Button onClick={onAction}>{actionLabel}</Button> : null}
+    </section>
+  );
+}
+
+/** @param {{ onSignIn?: () => void }} props */
+export function AuthRequiredSurface({ onSignIn }) {
+  return (
+    <StateSurface
+      eyebrow="401 · 인증 필요"
+      title="로그인이 필요합니다."
+      description="세션을 시작한 뒤 이전 작업을 안전하게 계속할 수 있습니다."
+      actionLabel="로그인 시작"
+      onAction={onSignIn}
+    />
+  );
+}
+
+/** @param {{ onNavigate?: () => void }} props */
+export function ForbiddenSurface({ onNavigate }) {
+  return (
+    <StateSurface
+      eyebrow="403 · 권한 없음"
+      title="접근할 수 없습니다."
+      description="권한을 확인하거나 접근 가능한 화면으로 이동하세요."
+      actionLabel="안전한 화면으로 이동"
+      onAction={onNavigate}
+      tone="warning"
+    />
+  );
+}
+
+/** @param {{ onNavigate?: () => void }} props */
+export function NotFoundSurface({ onNavigate }) {
+  return (
+    <StateSurface
+      eyebrow="404 · 찾을 수 없음"
+      title="요청한 화면이 없습니다."
+      description="주소를 확인하거나 시작 화면으로 돌아가세요."
+      actionLabel="시작 화면으로 이동"
+      onAction={onNavigate}
+    />
+  );
+}
@@ -0,0 +1,36 @@
+/**
+ * @param {{
+ *   title: string,
+ *   children?: React.ReactNode,
+ *   variant?: "info" | "success" | "warning" | "danger",
+ *   onDismiss?: () => void
+ * }} props
+ */
+export function Alert({
+  title,
+  children,
+  variant = "info",
+  onDismiss,
+}) {
+  return (
+    <section
+      className={`ui-alert ui-alert--${variant}`}
+      role={variant === "danger" ? "alert" : "status"}
+    >
+      <div>
+        <strong>{title}</strong>
+        {children ? <div className="ui-alert__content">{children}</div> : null}
+      </div>
+      {onDismiss ? (
+        <button
+          className="ui-alert__dismiss"
+          type="button"
+          aria-label={`${title} 알림 닫기`}
+          onClick={onDismiss}
+        >
+          ×
+        </button>
+      ) : null}
+    </section>
+  );
+}
@@ -0,0 +1,9 @@
+/**
+ * @param {{
+ *   children: React.ReactNode,
+ *   variant?: "neutral" | "info" | "success" | "warning" | "danger"
+ * }} props
+ */
+export function Badge({ children, variant = "neutral" }) {
+  return <span className={`ui-badge ui-badge--${variant}`}>{children}</span>;
+}
@@ -0,0 +1,24 @@
+/**
+ * @param {React.ButtonHTMLAttributes<HTMLButtonElement> & {
+ *   variant?: "primary" | "secondary" | "danger" | "ghost",
+ *   size?: "default" | "compact"
+ * }} props
+ */
+export function Button({
+  variant = "primary",
+  size = "default",
+  className = "",
+  type = "button",
+  ...props
+}) {
+  const classes = [
+    "ui-button",
+    `ui-button--${variant}`,
+    size === "compact" ? "ui-button--compact" : "",
+    className,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  return <button {...props} className={classes} type={type} />;
+}
@@ -0,0 +1,28 @@
+import { useId } from "react";
+
+/**
+ * @param {{
+ *   title: string,
+ *   description?: string,
+ *   children?: React.ReactNode,
+ *   footer?: React.ReactNode,
+ *   className?: string
+ * }} props
+ */
+export function Card({ title, description, children, footer, className = "" }) {
+  const titleId = useId();
+
+  return (
+    <article
+      className={`ui-card ${className}`.trim()}
+      aria-labelledby={titleId}
+    >
+      <div className="ui-card__header">
+        <h3 id={titleId}>{title}</h3>
+        {description ? <p>{description}</p> : null}
+      </div>
+      {children ? <div className="ui-card__content">{children}</div> : null}
+      {footer ? <footer className="ui-card__footer">{footer}</footer> : null}
+    </article>
+  );
+}
@@ -0,0 +1,88 @@
+import { useEffect, useId, useRef } from "react";
+
+/**
+ * @param {{
+ *   open: boolean,
+ *   onClose: () => void,
+ *   title: string,
+ *   description?: string,
+ *   children?: React.ReactNode,
+ *   actions?: React.ReactNode
+ * }} props
+ */
+export function Dialog({
+  open,
+  onClose,
+  title,
+  description,
+  children,
+  actions,
+}) {
+  const dialogRef = useRef(/** @type {HTMLDialogElement | null} */ (null));
+  const previousFocusRef = useRef(/** @type {HTMLElement | null} */ (null));
+  const titleId = useId();
+  const descriptionId = useId();
+
+  useEffect(() => {
+    const dialog = dialogRef.current;
+    if (!dialog) return;
+
+    if (open) {
+      previousFocusRef.current =
+        document.activeElement instanceof HTMLElement
+          ? document.activeElement
+          : null;
+      if (!dialog.open) {
+        if (typeof dialog.showModal === "function") dialog.showModal();
+        else dialog.setAttribute("open", "");
+      }
+      const firstFocusable = dialog.querySelector(
+        "[autofocus], button, [href], input, select, textarea, [tabindex]:not([tabindex='-1'])",
+      );
+      if (firstFocusable instanceof HTMLElement) firstFocusable.focus();
+      return;
+    }
+
+    if (dialog.open) {
+      if (typeof dialog.close === "function") dialog.close();
+      else dialog.removeAttribute("open");
+    }
+    previousFocusRef.current?.focus();
+    previousFocusRef.current = null;
+  }, [open]);
+
+  return (
+    <dialog
+      className="ui-dialog"
+      ref={dialogRef}
+      aria-labelledby={titleId}
+      aria-describedby={description ? descriptionId : undefined}
+      onCancel={(event) => {
+        event.preventDefault();
+        onClose();
+      }}
+      onClick={(event) => {
+        if (event.target === event.currentTarget) onClose();
+      }}
+    >
+      <div className="ui-dialog__surface">
+        <header className="ui-dialog__header">
+          <div>
+            <h2 id={titleId}>{title}</h2>
+            {description ? <p id={descriptionId}>{description}</p> : null}
+          </div>
+          <button
+            className="ui-dialog__close"
+            type="button"
+            aria-label={`${title} 닫기`}
+            onClick={onClose}
+          >
+            ×
+          </button>
+        </header>
+        {children ? <div className="ui-dialog__content">{children}</div> : null}
+        {actions ? <footer className="ui-dialog__actions">{actions}</footer> : null}
+      </div>
+    </dialog>
+  );
+}
@@ -0,0 +1,52 @@
+import { useId } from "react";
+
+/**
+ * @param {Omit<React.InputHTMLAttributes<HTMLInputElement>, "id"> & {
+ *   id?: string,
+ *   label: string,
+ *   description?: string,
+ *   error?: string
+ * }} props
+ */
+export function TextField({
+  id,
+  label,
+  description,
+  error,
+  className = "",
+  required,
+  ...inputProps
+}) {
+  const generatedId = useId();
+  const inputId = id ?? `field-${generatedId}`;
+  const descriptionId = description ? `${inputId}-description` : undefined;
+  const errorId = error ? `${inputId}-error` : undefined;
+  const describedBy = [descriptionId, errorId].filter(Boolean).join(" ");
+
+  return (
+    <div className={`ui-field ${className}`.trim()}>
+      <label className="ui-field__label" htmlFor={inputId}>
+        {label}
+        {required ? <span aria-hidden="true"> *</span> : null}
+      </label>
+      {description ? (
+        <p className="ui-field__description" id={descriptionId}>
+          {description}
+        </p>
+      ) : null}
+      <input
+        {...inputProps}
+        className="ui-field__input"
+        id={inputId}
+        required={required}
+        aria-describedby={describedBy || undefined}
+        aria-invalid={error ? "true" : undefined}
+      />
+      {error ? (
+        <p className="ui-field__error" id={errorId}>
+          {error}
+        </p>
+      ) : null}
+    </div>
+  );
+}