moru-krds-react 0.1.0

package/dist/drawer/index.js

@@ -0,0 +1,352 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState
+} from "react";
+import { createPortal } from "react-dom";
+import { cx } from "../lib/krds.js";
+const WIDTH = {
+  small: "40rem",
+  // 400px — 킷 --krds-modal--size-small
+  medium: "56rem",
+  // 560px — 킷 --krds-modal--size-medium
+  large: "76rem"
+  // 760px — 킷 --krds-modal--size-large
+};
+const TRANSITION_MS = 400;
+const Z_BASE = 1010;
+const FOCUSABLE_SELECTOR = [
+  "a[href]",
+  "area[href]",
+  "button:not([disabled])",
+  'input:not([disabled]):not([type="hidden"])',
+  "select:not([disabled])",
+  "textarea:not([disabled])",
+  "details > summary",
+  "audio[controls]",
+  "video[controls]",
+  '[contenteditable]:not([contenteditable="false"])',
+  '[tabindex]:not([tabindex="-1"])'
+].join(",");
+function focusables(root) {
+  return Array.from(root.querySelectorAll(FOCUSABLE_SELECTOR)).filter(
+    (el) => !el.hasAttribute("inert") && (el.offsetWidth > 0 || el.offsetHeight > 0 || el.getClientRects().length > 0)
+  );
+}
+let openDrawers = 0;
+let scrollLocks = 0;
+let savedOverflow = "";
+function lockScroll() {
+  if (scrollLocks++ > 0) return;
+  savedOverflow = document.body.style.overflow;
+  document.body.style.overflow = "hidden";
+}
+function unlockScroll() {
+  scrollLocks = Math.max(0, scrollLocks - 1);
+  if (scrollLocks > 0) return;
+  document.body.style.overflow = savedOverflow;
+}
+const DrawerContext = createContext(null);
+function useDrawerContext(name) {
+  const ctx = useContext(DrawerContext);
+  if (!ctx) throw new Error(`<${name}> \uC740 <Drawer.Root> \uC548\uC5D0\uC11C\uB9CC \uC4F8 \uC218 \uC788\uB2E4.`);
+  return ctx;
+}
+function DrawerRoot({
+  open,
+  onClose,
+  side = "right",
+  size = "small",
+  modal = true,
+  dismissible = true,
+  closeOnBackdrop = true,
+  initialFocus = "panel",
+  container,
+  panelClassName,
+  panelStyle,
+  className,
+  style,
+  children,
+  onKeyDown,
+  onMouseDown,
+  ...rest
+}) {
+  const reactId = useId();
+  const titleId = `${reactId}-title`;
+  const panelRef = useRef(null);
+  const [mounted, setMounted] = useState(false);
+  const [present, setPresent] = useState(false);
+  const [entered, setEntered] = useState(false);
+  const [hasTitle, setHasTitle] = useState(false);
+  const [stack, setStack] = useState(1);
+  const initialFocusRef = useRef(initialFocus);
+  initialFocusRef.current = initialFocus;
+  const modalRef = useRef(modal);
+  modalRef.current = modal;
+  useEffect(() => {
+    setMounted(true);
+  }, []);
+  useEffect(() => {
+    if (!open) return;
+    const restore = document.activeElement;
+    openDrawers += 1;
+    setStack(openDrawers);
+    setPresent(true);
+    const didLock = modalRef.current;
+    if (didLock) lockScroll();
+    let inner = 0;
+    const outer = requestAnimationFrame(() => {
+      inner = requestAnimationFrame(() => setEntered(true));
+    });
+    const focusTimer = window.setTimeout(() => {
+      const panel = panelRef.current;
+      if (!panel) return;
+      if (initialFocusRef.current === "first") {
+        const first = focusables(panel)[0];
+        if (first) {
+          first.focus();
+          return;
+        }
+      }
+      panel.focus();
+    }, 0);
+    return () => {
+      cancelAnimationFrame(outer);
+      cancelAnimationFrame(inner);
+      window.clearTimeout(focusTimer);
+      openDrawers = Math.max(0, openDrawers - 1);
+      setEntered(false);
+      if (didLock) unlockScroll();
+      restore?.focus?.();
+    };
+  }, [open]);
+  useEffect(() => {
+    if (open || !present) return;
+    const timer = window.setTimeout(() => setPresent(false), TRANSITION_MS);
+    return () => window.clearTimeout(timer);
+  }, [open, present]);
+  const ctx = useMemo(
+    () => ({ titleId, close: onClose, registerTitle: setHasTitle }),
+    [titleId, onClose]
+  );
+  function handleKeyDown(event) {
+    onKeyDown?.(event);
+    if (event.defaultPrevented) return;
+    if (event.key === "Escape" || event.key === "Esc") {
+      if (!dismissible) return;
+      event.stopPropagation();
+      onClose();
+      return;
+    }
+    if (!modal) return;
+    if (event.key !== "Tab") return;
+    const panel = panelRef.current;
+    if (!panel) return;
+    const nodes = focusables(panel);
+    if (nodes.length === 0) {
+      event.preventDefault();
+      panel.focus();
+      return;
+    }
+    const first = nodes[0];
+    const last = nodes[nodes.length - 1];
+    const active = document.activeElement;
+    if (event.shiftKey && (active === first || active === panel)) {
+      event.preventDefault();
+      last.focus();
+    } else if (!event.shiftKey && active === last) {
+      event.preventDefault();
+      first.focus();
+    }
+  }
+  function handleMouseDown(event) {
+    onMouseDown?.(event);
+    if (event.defaultPrevented) return;
+    if (!modal) return;
+    const target = event.target;
+    if (target && panelRef.current?.contains(target)) return;
+    if (closeOnBackdrop && dismissible) {
+      onClose();
+      return;
+    }
+    panelRef.current?.focus();
+  }
+  if (!mounted || !present) return null;
+  const slideOut = side === "right" ? "translate-x-full" : "-translate-x-full";
+  return createPortal(
+    /* @__PURE__ */ jsx(DrawerContext.Provider, { value: ctx, children: /* @__PURE__ */ jsxs(
+      "div",
+      {
+        role: "dialog",
+        "aria-modal": modal ? true : void 0,
+        "aria-labelledby": hasTitle ? titleId : void 0,
+        className: cx("fixed inset-0", !modal && "pointer-events-none", className),
+        style: { zIndex: Z_BASE + stack, ...style },
+        onKeyDown: handleKeyDown,
+        onMouseDown: handleMouseDown,
+        ...rest,
+        children: [
+          modal && /* @__PURE__ */ jsx(
+            "div",
+            {
+              "aria-hidden": "true",
+              className: cx(
+                "absolute inset-0 bg-bg-dim transition-opacity duration-400 ease-in-out motion-reduce:transition-none",
+                entered ? "opacity-100" : "opacity-0"
+              )
+            }
+          ),
+          /* @__PURE__ */ jsx(
+            "div",
+            {
+              ref: panelRef,
+              tabIndex: -1,
+              className: cx(
+                "pointer-events-auto absolute inset-y-0 flex h-full max-w-full flex-col bg-surface text-fg",
+                "transition-transform duration-400 ease-in-out motion-reduce:transition-none",
+                "focus:[box-shadow:var(--krds-box-shadow-outline-inset)] focus:outline-none",
+                side === "right" ? "right-0 border-l border-line" : "left-0 border-r border-line",
+                !entered && slideOut,
+                panelClassName
+              ),
+              style: { width: WIDTH[size], ...panelStyle },
+              children
+            }
+          )
+        ]
+      }
+    ) }),
+    container ?? document.body
+  );
+}
+function DrawerHeader({
+  level = 2,
+  hideTitle,
+  titleClassName,
+  extra,
+  className,
+  children,
+  ...rest
+}) {
+  const { titleId, registerTitle } = useDrawerContext("Drawer.Header");
+  useEffect(() => {
+    registerTitle(true);
+    return () => registerTitle(false);
+  }, [registerTitle]);
+  const Heading = `h${level}`;
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className: cx(
+        "flex shrink-0 items-center justify-between gap-4 border-b border-line px-4 py-5 md:px-10",
+        className
+      ),
+      ...rest,
+      children: [
+        /* @__PURE__ */ jsx(
+          Heading,
+          {
+            id: titleId,
+            className: cx(
+              hideTitle ? "sr-only" : "truncate text-heading-sm font-bold text-fg-bolder",
+              titleClassName
+            ),
+            children
+          }
+        ),
+        extra
+      ]
+    }
+  );
+}
+function DrawerBody({ className, children, ref, ...rest }) {
+  const innerRef = useRef(null);
+  useEffect(() => {
+    const node = innerRef.current;
+    if (!node) return;
+    const sync = () => {
+      if (node.scrollHeight > node.clientHeight) node.setAttribute("tabindex", "0");
+      else node.removeAttribute("tabindex");
+    };
+    sync();
+    if (typeof ResizeObserver === "undefined") return;
+    const observer = new ResizeObserver(sync);
+    observer.observe(node);
+    for (const child of Array.from(node.children)) observer.observe(child);
+    return () => observer.disconnect();
+  }, []);
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      className: cx("min-h-0 flex-1 overflow-y-auto px-4 py-6 md:px-10", className),
+      ref: (node) => {
+        innerRef.current = node;
+        if (typeof ref === "function") ref(node);
+        else if (ref) ref.current = node;
+      },
+      ...rest,
+      children
+    }
+  );
+}
+function DrawerFooter({ split, className, children, ...rest }) {
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      className: cx(
+        "btn-wrap flex shrink-0 flex-wrap items-center gap-2 border-t border-line px-4 py-5 md:px-10",
+        split ? "justify-between" : "justify-end",
+        className
+      ),
+      ...rest,
+      children
+    }
+  );
+}
+function DrawerClose({
+  label = "\uB2EB\uAE30",
+  className,
+  onClick,
+  type = "button",
+  ...rest
+}) {
+  const { close } = useDrawerContext("Drawer.Close");
+  return /* @__PURE__ */ jsxs(
+    "button",
+    {
+      type,
+      className: cx("krds-btn small icon shrink-0", className),
+      onClick: (event) => {
+        onClick?.(event);
+        if (!event.defaultPrevented) close();
+      },
+      ...rest,
+      children: [
+        /* @__PURE__ */ jsx("span", { className: "sr-only", children: label }),
+        /* @__PURE__ */ jsx("i", { className: "svg-icon ico-popup-close", "aria-hidden": "true" })
+      ]
+    }
+  );
+}
+const Drawer = {
+  Root: DrawerRoot,
+  Header: DrawerHeader,
+  Body: DrawerBody,
+  Footer: DrawerFooter,
+  Close: DrawerClose
+};
+export {
+  Drawer,
+  DrawerBody,
+  DrawerClose,
+  DrawerFooter,
+  DrawerHeader,
+  DrawerRoot
+};
+//# sourceMappingURL=index.js.map

package/dist/drawer/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/drawer/index.tsx"],"sourcesContent":["'use client';\n\nimport {\n  createContext,\n  useContext,\n  useEffect,\n  useId,\n  useMemo,\n  useRef,\n  useState,\n  type ComponentPropsWithRef,\n  type CSSProperties,\n  type KeyboardEvent as ReactKeyboardEvent,\n  type MouseEvent as ReactMouseEvent,\n  type ReactNode,\n} from 'react';\nimport { createPortal } from 'react-dom';\nimport { cx } from '../lib/krds';\n\n/**\n * 서랍(측면 패널) — KRDS 에 없다. 모양은 KRDS 토큰, 동작은 `Modal` 과 같은 보충 부품이다.\n *\n * 목록 옆에서 필터·상세를 여는 자리. 폭은 `size` 3단에서 고른다(픽셀을 넘기지 마라).\n * 확정·취소는 `Drawer.Footer` 에 두고 제출이 가장 오른쪽이다.\n * 뒤 화면을 계속 쓸 수 있어야 하면 `modal={false}` — 이때는 초점을 가두지 않는다.\n * 화면 한복판에 띄우는 대화상자는 `ui/modal` 이다.\n *\n * @example\n * <Drawer.Root open={open} onClose={close} side=\"right\" size=\"small\">\n *   <Drawer.Header extra={<Drawer.Close />}>검색 조건</Drawer.Header>\n *   <Drawer.Body>…필터 폼…</Drawer.Body>\n *   <Drawer.Footer split>\n *     <Button variant=\"text\" onClick={reset}>초기화</Button>\n *     <Button variant=\"primary\" onClick={apply}>적용</Button>\n *   </Drawer.Footer>\n * </Drawer.Root>\n *\n * 자세히: docs/krds/09-부품-노트.md#서랍\n */\n\n/** 어느 쪽에서 나오는가. 아래에서 올라오는 것은 킷의 바텀시트(`ui/modal` 의 `type`) 자리다. */\nexport type DrawerSide = 'left' | 'right';\n\n/** 폭 3단 — 400 / 560 / 760px. 킷 모달과 같은 눈금이다. */\nexport type DrawerSize = 'small' | 'medium' | 'large';\n\nconst WIDTH: Record<DrawerSize, string> = {\n  small: '40rem', // 400px — 킷 --krds-modal--size-small\n  medium: '56rem', // 560px — 킷 --krds-modal--size-medium\n  large: '76rem', // 760px — 킷 --krds-modal--size-large\n};\n\n/** 전환 시간(ms). 킷 `--krds-transition-base` 와 같은 값이고 `duration-400` 과 짝이다. */\nconst TRANSITION_MS = 400;\n\n/** 겹침 층. 킷 모달과 같은 값이라 서랍과 모달이 함께 열려도 순서가 뒤집히지 않는다. */\nconst Z_BASE = 1010;\n\n/** 초점 가둠 대상. `Modal` 과 같은 목록이다. */\nconst FOCUSABLE_SELECTOR = [\n  'a[href]',\n  'area[href]',\n  'button:not([disabled])',\n  'input:not([disabled]):not([type=\"hidden\"])',\n  'select:not([disabled])',\n  'textarea:not([disabled])',\n  'details > summary',\n  'audio[controls]',\n  'video[controls]',\n  '[contenteditable]:not([contenteditable=\"false\"])',\n  '[tabindex]:not([tabindex=\"-1\"])',\n].join(',');\n\nfunction focusables(root: HTMLElement): HTMLElement[] {\n  return Array.from(root.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)).filter(\n    (el) =>\n      !el.hasAttribute('inert') &&\n      (el.offsetWidth > 0 || el.offsetHeight > 0 || el.getClientRects().length > 0),\n  );\n}\n\n/** 열려 있는 서랍 수. 겹쳐 열릴 때 z-index 를 킷 모달과 같은 방식으로 올린다. */\nlet openDrawers = 0;\n\n/**\n * 뒤 문서 스크롤 잠금. 킷의 `body.scroll-no` 는 CSS 규칙이 없어 `body.style.overflow` 를 직접 다룬다.\n * 셈은 이 모듈 안에서만 유효하다 — 모달과 겹쳐 열리면 어긋날 수 있다.\n */\nlet scrollLocks = 0;\nlet savedOverflow = '';\n\nfunction lockScroll() {\n  if (scrollLocks++ > 0) return;\n  savedOverflow = document.body.style.overflow;\n  document.body.style.overflow = 'hidden';\n}\n\nfunction unlockScroll() {\n  scrollLocks = Math.max(0, scrollLocks - 1);\n  if (scrollLocks > 0) return;\n  document.body.style.overflow = savedOverflow;\n}\n\ntype DrawerContextValue = {\n  /** 제목 요소의 id. `Drawer.Header` 가 붙이고 `Drawer.Root` 가 `aria-labelledby` 로 가리킨다. */\n  titleId: string;\n  close: () => void;\n  /** 제목이 실제로 있는지 알린다 — 없으면 `aria-labelledby` 가 허공을 가리킨다. */\n  registerTitle: (has: boolean) => void;\n};\n\nconst DrawerContext = createContext<DrawerContextValue | null>(null);\n\nfunction useDrawerContext(name: string): DrawerContextValue {\n  const ctx = useContext(DrawerContext);\n  if (!ctx) throw new Error(`<${name}> 은 <Drawer.Root> 안에서만 쓸 수 있다.`);\n  return ctx;\n}\n\nexport type DrawerRootProps = ComponentPropsWithRef<'div'> & {\n  /** 열림 여부. 상태는 화면 쪽이 쥔다. */\n  open: boolean;\n  /** 닫아 달라는 요청 — Esc·딤 클릭·`Drawer.Close` 에서 온다. */\n  onClose: () => void;\n  /** 나오는 방향. 기본 오른쪽. */\n  side?: DrawerSide;\n  /** 기본 small(400px). 3단에서 고른다. */\n  size?: DrawerSize;\n  /** 딤을 깔고 초점을 가두는가. 기본 true — false 면 뒤 화면을 계속 쓸 수 있다. */\n  modal?: boolean;\n  /** Esc 로 닫을 수 있는가. */\n  dismissible?: boolean;\n  /** 딤을 눌렀을 때 닫는가. 기본 true — 값을 잃으면 곤란한 서랍에서는 꺼라. */\n  closeOnBackdrop?: boolean;\n  /** 열릴 때 첫 초점. 기본 `panel`(보조기술이 이름부터 읽는다) · `first` 는 첫 초점 요소로 보낸다. */\n  initialFocus?: 'panel' | 'first';\n  /** 포털 대상. 기본 `document.body`. */\n  container?: Element | null;\n  /** 패널(흰 면)에 붙일 클래스. 바깥틀은 `className` 이 받는다. */\n  panelClassName?: string;\n  /** 패널에 붙일 인라인 style. 폭을 3단 밖으로 바꿔야 할 때. */\n  panelStyle?: CSSProperties;\n  children?: ReactNode;\n};\n\n/**\n * 서랍 바깥틀. 포털 · 초점 가둠 · Esc · 스크롤 잠금 · 초점 복귀를 여기서 한다.\n *\n * `Drawer.Header` 를 두면 `aria-labelledby` 가 자동으로 붙는다. 헤더 없이 쓸 거면\n * `aria-label` 을 직접 넘겨라 — 대화상자에는 반드시 이름이 있어야 한다.\n */\nexport function DrawerRoot({\n  open,\n  onClose,\n  side = 'right',\n  size = 'small',\n  modal = true,\n  dismissible = true,\n  closeOnBackdrop = true,\n  initialFocus = 'panel',\n  container,\n  panelClassName,\n  panelStyle,\n  className,\n  style,\n  children,\n  onKeyDown,\n  onMouseDown,\n  ...rest\n}: DrawerRootProps) {\n  const reactId = useId();\n  const titleId = `${reactId}-title`;\n  const panelRef = useRef<HTMLDivElement | null>(null);\n  const [mounted, setMounted] = useState(false);\n  /** DOM 에 붙어 있는가. 닫힌 뒤에도 미끄러져 나가는 동안 유지한다. */\n  const [present, setPresent] = useState(false);\n  /** 다 들어왔는가(= 딤이 보이고 패널이 제자리). 첫 그림 뒤에 켜야 전환이 돈다. */\n  const [entered, setEntered] = useState(false);\n  const [hasTitle, setHasTitle] = useState(false);\n  /** 몇 번째로 열린 서랍인가(1부터). */\n  const [stack, setStack] = useState(1);\n\n  // 초점 정책이 도중에 바뀌어도 열림 효과가 다시 돌지 않게 ref 로 읽는다.\n  const initialFocusRef = useRef(initialFocus);\n  initialFocusRef.current = initialFocus;\n  const modalRef = useRef(modal);\n  modalRef.current = modal;\n\n  // 서버에서는 포털을 만들지 않는다(hydration 어긋남 방지).\n  useEffect(() => {\n    setMounted(true);\n  }, []);\n\n  // 열림 — 스크롤 잠금 · 상태 · 초점 이동. 정리 단계에서 잠금 해제와 초점 복귀.\n  useEffect(() => {\n    if (!open) return;\n    const restore = document.activeElement as HTMLElement | null;\n    openDrawers += 1;\n    setStack(openDrawers);\n    setPresent(true);\n    // 잠갔는지를 지역 변수로 들고 있는다 — 열려 있는 동안 `modal` 이 바뀌어도\n    // 잠금과 해제가 짝을 이루게 한다(ref 를 정리 단계에서 다시 읽으면 한쪽만 돌 수 있다).\n    const didLock = modalRef.current;\n    if (didLock) lockScroll();\n\n    // 프레임을 두 번 넘겨야 브라우저가 「밖 → 안」을 전환으로 본다.\n    let inner = 0;\n    const outer = requestAnimationFrame(() => {\n      inner = requestAnimationFrame(() => setEntered(true));\n    });\n\n    // 서랍은 visibility 를 쓰지 않아 전환을 기다리지 않고 바로 초점을 줄 수 있다.\n    const focusTimer = window.setTimeout(() => {\n      const panel = panelRef.current;\n      if (!panel) return;\n      if (initialFocusRef.current === 'first') {\n        const first = focusables(panel)[0];\n        if (first) {\n          first.focus();\n          return;\n        }\n      }\n      panel.focus();\n    }, 0);\n\n    return () => {\n      cancelAnimationFrame(outer);\n      cancelAnimationFrame(inner);\n      window.clearTimeout(focusTimer);\n      openDrawers = Math.max(0, openDrawers - 1);\n      setEntered(false);\n      if (didLock) unlockScroll();\n      // 서랍을 열었던 요소로 초점 복귀 — 킷 도움 패널의 `lastFocusedButton.focus()` 에 해당한다.\n      restore?.focus?.();\n    };\n  }, [open]);\n\n  // 닫힘 — 전환이 끝난 뒤에 DOM 에서 뗀다.\n  useEffect(() => {\n    if (open || !present) return;\n    const timer = window.setTimeout(() => setPresent(false), TRANSITION_MS);\n    return () => window.clearTimeout(timer);\n  }, [open, present]);\n\n  const ctx = useMemo<DrawerContextValue>(\n    () => ({ titleId, close: onClose, registerTitle: setHasTitle }),\n    [titleId, onClose],\n  );\n\n  function handleKeyDown(event: ReactKeyboardEvent<HTMLDivElement>) {\n    onKeyDown?.(event);\n    if (event.defaultPrevented) return;\n\n    if (event.key === 'Escape' || event.key === 'Esc') {\n      if (!dismissible) return;\n      // 겹쳐 열린 경우 바깥 서랍·모달까지 닫히지 않도록 여기서 끊는다.\n      event.stopPropagation();\n      onClose();\n      return;\n    }\n\n    // 딤 없는 서랍은 가두지 않는다 — 뒤 화면을 계속 쓸 수 있어야 하므로 Tab 이 나가야 한다.\n    if (!modal) return;\n    if (event.key !== 'Tab') return;\n    const panel = panelRef.current;\n    if (!panel) return;\n    const nodes = focusables(panel);\n    if (nodes.length === 0) {\n      event.preventDefault();\n      panel.focus();\n      return;\n    }\n    const first = nodes[0];\n    const last = nodes[nodes.length - 1];\n    const active = document.activeElement;\n    if (event.shiftKey && (active === first || active === panel)) {\n      event.preventDefault();\n      last.focus();\n    } else if (!event.shiftKey && active === last) {\n      event.preventDefault();\n      first.focus();\n    }\n  }\n\n  function handleMouseDown(event: ReactMouseEvent<HTMLDivElement>) {\n    onMouseDown?.(event);\n    if (event.defaultPrevented) return;\n    if (!modal) return;\n    // 패널 안을 누른 것은 딤 클릭이 아니다. `mousedown` 으로 보는 이유는 킷 모달과 같다 —\n    // 패널 안에서 시작해 딤에서 끝나는 드래그를 「바깥 클릭」으로 오해하지 않기 위해서다.\n    const target = event.target as Node | null;\n    if (target && panelRef.current?.contains(target)) return;\n    if (closeOnBackdrop && dismissible) {\n      onClose();\n      return;\n    }\n    // 닫지 않기로 했으면 초점만 되돌린다 — 킷 모달의 바깥 클릭 동작이 이것이다.\n    panelRef.current?.focus();\n  }\n\n  if (!mounted || !present) return null;\n\n  const slideOut = side === 'right' ? 'translate-x-full' : '-translate-x-full';\n\n  return createPortal(\n    <DrawerContext.Provider value={ctx}>\n      <div\n        role=\"dialog\"\n        aria-modal={modal ? true : undefined}\n        aria-labelledby={hasTitle ? titleId : undefined}\n        // 딤이 없을 때는 바깥틀이 화면을 덮은 채 클릭을 먹지 않게 한다(뒤 화면을 계속 쓴다).\n        className={cx('fixed inset-0', !modal && 'pointer-events-none', className)}\n        style={{ zIndex: Z_BASE + stack, ...style }}\n        onKeyDown={handleKeyDown}\n        onMouseDown={handleMouseDown}\n        {...rest}\n      >\n        {modal && (\n          <div\n            aria-hidden=\"true\"\n            className={cx(\n              'absolute inset-0 bg-bg-dim transition-opacity duration-400 ease-in-out motion-reduce:transition-none',\n              entered ? 'opacity-100' : 'opacity-0',\n            )}\n          />\n        )}\n        {/*\n          패널. tabIndex -1 로 초점만 받고 Tab 순서에는 들어가지 않는다.\n          `:focus` 테두리는 킷 모달(`.modal-content:focus`)과 같은 토큰\n          `--krds-box-shadow-outline-inset` 을 그대로 쓴다. 표기는 `ui/radio` 와 맞춘 임의 속성 형태다.\n          (선명한 화면 모드에서 이 토큰 색이 안 바뀌는 것은 킷 결함이다 —\n           `[data-krds-mode=high-contrast] :root` 는 :root 가 자기 후손일 수 없어 맞지 않는다.\n           킷 컴포넌트 전부가 같은 상태라 여기서만 따로 고치지 않는다. `ui/resize` 주석 참조.)\n        */}\n        <div\n          ref={panelRef}\n          tabIndex={-1}\n          className={cx(\n            'pointer-events-auto absolute inset-y-0 flex h-full max-w-full flex-col bg-surface text-fg',\n            'transition-transform duration-400 ease-in-out motion-reduce:transition-none',\n            'focus:[box-shadow:var(--krds-box-shadow-outline-inset)] focus:outline-none',\n            side === 'right' ? 'right-0 border-l border-line' : 'left-0 border-r border-line',\n            !entered && slideOut,\n            panelClassName,\n          )}\n          style={{ width: WIDTH[size], ...panelStyle }}\n        >\n          {children}\n        </div>\n      </div>\n    </DrawerContext.Provider>,\n    container ?? document.body,\n  );\n}\n\nexport type DrawerHeaderProps = ComponentPropsWithRef<'div'> & {\n  /** 제목 태그 단계. 기본 h2 — 화면의 제목 위계에 맞춘다. */\n  level?: 1 | 2 | 3 | 4 | 5 | 6;\n  /** 제목을 눈에서만 감춘다. 이름 자체는 남는다. */\n  hideTitle?: boolean;\n  /** 제목 요소에 붙일 클래스. */\n  titleClassName?: string;\n  /** 제목 오른쪽 자리. 닫기 버튼(`Drawer.Close`)을 여기에 둔다. */\n  extra?: ReactNode;\n};\n\n/**\n * 제목 줄. 이 부품을 두면 서랍의 접근 가능한 이름이 자동으로 이어진다.\n *\n * @example\n * <Drawer.Header extra={<Drawer.Close />}>검색 조건</Drawer.Header>\n */\nexport function DrawerHeader({\n  level = 2,\n  hideTitle,\n  titleClassName,\n  extra,\n  className,\n  children,\n  ...rest\n}: DrawerHeaderProps) {\n  const { titleId, registerTitle } = useDrawerContext('Drawer.Header');\n\n  useEffect(() => {\n    registerTitle(true);\n    return () => registerTitle(false);\n  }, [registerTitle]);\n\n  const Heading = `h${level}` as 'h2';\n\n  return (\n    <div\n      className={cx(\n        'flex shrink-0 items-center justify-between gap-4 border-b border-line px-4 py-5 md:px-10',\n        className,\n      )}\n      {...rest}\n    >\n      <Heading\n        id={titleId}\n        className={cx(\n          hideTitle ? 'sr-only' : 'truncate text-heading-sm font-bold text-fg-bolder',\n          titleClassName,\n        )}\n      >\n        {children}\n      </Heading>\n      {extra}\n    </div>\n  );\n}\n\n/** 본문. 스크롤이 생기면 `tabindex=\"0\"` 을 붙여 키보드로도 굴릴 수 있게 한다. */\nexport function DrawerBody({ className, children, ref, ...rest }: ComponentPropsWithRef<'div'>) {\n  const innerRef = useRef<HTMLDivElement | null>(null);\n\n  useEffect(() => {\n    const node = innerRef.current;\n    if (!node) return;\n    const sync = () => {\n      if (node.scrollHeight > node.clientHeight) node.setAttribute('tabindex', '0');\n      else node.removeAttribute('tabindex');\n    };\n    sync();\n    if (typeof ResizeObserver === 'undefined') return;\n    const observer = new ResizeObserver(sync);\n    observer.observe(node);\n    for (const child of Array.from(node.children)) observer.observe(child);\n    return () => observer.disconnect();\n  }, []);\n\n  return (\n    <div\n      className={cx('min-h-0 flex-1 overflow-y-auto px-4 py-6 md:px-10', className)}\n      ref={(node) => {\n        innerRef.current = node;\n        if (typeof ref === 'function') ref(node);\n        else if (ref) (ref as { current: HTMLDivElement | null }).current = node;\n      }}\n      {...rest}\n    >\n      {children}\n    </div>\n  );\n}\n\nexport type DrawerFooterProps = ComponentPropsWithRef<'div'> & {\n  /** 좌우로 갈라 놓는다. 왼쪽에 보조 액션, 오른쪽에 확정 액션을 둘 때. */\n  split?: boolean;\n};\n\n/**\n * 푸터 — 확정·취소 액션 자리. 제출(primary)이 가장 오른쪽이다.\n * `split` 을 주면 왼쪽 보조 액션과 오른쪽 확정 액션으로 갈라 놓는다.\n */\nexport function DrawerFooter({ split, className, children, ...rest }: DrawerFooterProps) {\n  return (\n    <div\n      className={cx(\n        'btn-wrap flex shrink-0 flex-wrap items-center gap-2 border-t border-line px-4 py-5 md:px-10',\n        split ? 'justify-between' : 'justify-end',\n        className,\n      )}\n      {...rest}\n    >\n      {children}\n    </div>\n  );\n}\n\nexport type DrawerCloseProps = Omit<ComponentPropsWithRef<'button'>, 'children'> & {\n  /** 스크린리더가 읽을 이름. 아이콘만 있는 버튼이라 반드시 있어야 한다. */\n  label?: string;\n};\n\n/**\n * 닫기 버튼 — 킷 `krds-btn small icon` + `ico-popup-close`.\n * **모달과 달리 `Drawer.Header` 의 `extra` 에 넣는다.**\n *\n * @example\n * <Drawer.Header extra={<Drawer.Close />}>필터</Drawer.Header>\n */\nexport function DrawerClose({\n  label = '닫기',\n  className,\n  onClick,\n  type = 'button',\n  ...rest\n}: DrawerCloseProps) {\n  const { close } = useDrawerContext('Drawer.Close');\n\n  return (\n    <button\n      type={type}\n      // small(40px) — 헤더 한 줄에 들어가야 해서 모달의 medium(48px)보다 한 단 작다.\n      className={cx('krds-btn small icon shrink-0', className)}\n      onClick={(event) => {\n        onClick?.(event);\n        if (!event.defaultPrevented) close();\n      }}\n      {...rest}\n    >\n      <span className=\"sr-only\">{label}</span>\n      <i className=\"svg-icon ico-popup-close\" aria-hidden=\"true\" />\n    </button>\n  );\n}\n\n/** 합성용 묶음. `Root` · `Header` · `Body` · `Footer` · `Close`. */\nexport const Drawer = {\n  Root: DrawerRoot,\n  Header: DrawerHeader,\n  Body: DrawerBody,\n  Footer: DrawerFooter,\n  Close: DrawerClose,\n};\n"],"mappings":"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","names":[]}

package/dist/empty-state/index.d.ts

@@ -0,0 +1,86 @@
+import type { ComponentPropsWithRef, ReactNode } from 'react';
+import { 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';
+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 declare function EmptyState({ reason, tone, layout, icon, title, lead, description, hints, actions, live, className, children, ...rest }: EmptyStateProps): import("react").JSX.Element;
+/**
+ * 검색 결과 없음 — KRDS 가 문구와 대안까지 못 박은 화면이다.
+ *
+ * 결과 수 0 · 규격 문구 · 대안 4개(철자 확인 · 다른 검색어 · 더 일반적인 검색어 · 검색 도움말)를
+ * 기본값으로 담는다. `<SearchEmptyState query={q} />` 만으로 규격을 채운다.
+ *
+ * **`helpHref` 를 주지 않으면 대안 ④가 갈 곳 없는 문장으로 남는다** —
+ * 도움말 문서가 아직 없다면 `hints` 를 직접 넘겨 그 화면에서 할 수 있는 행동으로 바꿔라.
+ */
+/** 규격이 든 안내 문구 그대로. 바꾸지 마라. */
+export declare const SEARCH_NO_RESULT_MESSAGE = "\uAC80\uC0C9\uC5B4\uC640 \uC77C\uCE58\uD558\uB294 \uACB0\uACFC\uB97C \uCC3E\uC744 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.";
+/** 규격 대안 4개 중 링크가 필요 없는 셋. ④는 `helpHref` 에 따라 아래에서 만든다. */
+export declare 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 declare function SearchEmptyState({ query, count, helpHref, helpLabel, hints, title, ...rest }: SearchEmptyStateProps): import("react").JSX.Element;
+//# sourceMappingURL=index.d.ts.map

package/dist/empty-state/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/empty-state/index.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAC9D,OAAO,EAAM,KAAK,QAAQ,EAAE,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE/D;;;;;;;;;;;;;;GAcG;AAEH,oCAAoC;AACpC,MAAM,MAAM,gBAAgB;AAC1B,+BAA+B;AAC7B,OAAO;AACT,uBAAuB;GACrB,YAAY;AACd,eAAe;GACb,WAAW;AACb,eAAe;GACb,OAAO,CAAC;AAEZ,2CAA2C;AAC3C,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,GAAG,QAAQ,CAAC,CAAC;AAE9F;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,QAAQ,CAAC;AAkBlD,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,qBAAqB,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,GAAG;IAC1E,yCAAyC;IACzC,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,gCAAgC;IAChC,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,oCAAoC;IACpC,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,4DAA4D;IAC5D,IAAI,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;IACvB,8BAA8B;IAC9B,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,oDAAoD;IACpD,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,mBAAmB;IACnB,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,mDAAmD;IACnD,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC;IACpB,wDAAwD;IACxD,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB,CAAC;AAEF,wBAAgB,UAAU,CAAC,EACzB,MAAgB,EAChB,IAAI,EACJ,MAAgB,EAChB,IAAI,EACJ,KAAK,EACL,IAAI,EACJ,WAAW,EACX,KAAK,EACL,OAAO,EACP,IAAI,EACJ,SAAS,EACT,QAAQ,EACR,GAAG,IAAI,EACR,EAAE,eAAe,+BAiFjB;AAED;;;;;;;;GAQG;AAEH,+BAA+B;AAC/B,eAAO,MAAM,wBAAwB,uHAA6B,CAAC;AAEnE,2DAA2D;AAC3D,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAInD,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG,IAAI,CAAC,eAAe,EAAE,QAAQ,GAAG,MAAM,CAAC,GAAG;IAC7E,sCAAsC;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,EAC/B,KAAK,EACL,KAAS,EACT,QAAQ,EACR,SAAoB,EACpB,KAAK,EACL,KAAgC,EAChC,GAAG,IAAI,EACR,EAAE,qBAAqB,+BAoCvB"}

package/dist/empty-state/index.js

@@ -0,0 +1,138 @@
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { UiLink } from "../lib/link.js";
+import { cx } from "../lib/krds.js";
+const REASON = {
+  empty: { tone: "gray", icon: "file", title: "\uB4F1\uB85D\uB41C \uC790\uB8CC\uAC00 \uC5C6\uC2B5\uB2C8\uB2E4." },
+  "no-results": { tone: "gray", icon: "sch", title: "\uC870\uAC74\uC5D0 \uB9DE\uB294 \uACB0\uACFC\uAC00 \uC5C6\uC2B5\uB2C8\uB2E4." },
+  forbidden: { tone: "warning", icon: null, title: "\uC774 \uB0B4\uC6A9\uC744 \uBCFC \uAD8C\uD55C\uC774 \uC5C6\uC2B5\uB2C8\uB2E4." },
+  error: { tone: "danger", icon: "error-fill", title: "\uBD88\uB7EC\uC624\uC9C0 \uBABB\uD588\uC2B5\uB2C8\uB2E4." }
+};
+const TONE = {
+  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" }
+};
+function EmptyState({
+  reason = "empty",
+  tone,
+  layout = "panel",
+  icon,
+  title,
+  lead,
+  description,
+  hints,
+  actions,
+  live,
+  className,
+  children,
+  ...rest
+}) {
+  const preset = REASON[reason];
+  const t = TONE[tone ?? preset.tone];
+  const panel = layout === "panel";
+  const iconName = icon === void 0 ? preset.icon : icon;
+  const iconNode = iconName ? /* @__PURE__ */ jsx(
+    "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 을 명시한다.
+    /* @__PURE__ */ jsx("ul", { role: "list", className: cx("krds-info-list dash", panel && "w-fit text-left"), children: hints.map((hint, i) => /* @__PURE__ */ jsx("li", { role: "listitem", children: hint }, i)) })
+  ) : null;
+  const header = /* @__PURE__ */ jsxs("div", { className: cx("flex flex-col gap-2", panel && "items-center text-center"), children: [
+    panel && iconNode,
+    lead && /* @__PURE__ */ jsx("p", { className: "m-0 text-sm text-fg-subtle", children: lead }),
+    /* @__PURE__ */ jsx("p", { className: cx("m-0 font-bold text-fg", panel ? "text-heading-xs" : "text-sm"), children: title ?? preset.title }),
+    description && /* @__PURE__ */ jsx("p", { className: "m-0 text-sm text-fg-subtle", children: description })
+  ] });
+  const body = /* @__PURE__ */ jsxs(Fragment, { children: [
+    header,
+    hintList,
+    children,
+    actions && /* @__PURE__ */ jsx("div", { className: cx("flex flex-wrap items-center gap-2", panel && "justify-center"), children: actions })
+  ] });
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      role: live ? "status" : void 0,
+      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,
+      children: panel ? body : /* @__PURE__ */ jsxs(Fragment, { children: [
+        iconNode,
+        /* @__PURE__ */ jsx("div", { className: "flex min-w-0 flex-1 flex-col gap-4", children: body })
+      ] })
+    }
+  );
+}
+const SEARCH_NO_RESULT_MESSAGE = "\uAC80\uC0C9\uC5B4\uC640 \uC77C\uCE58\uD558\uB294 \uACB0\uACFC\uB97C \uCC3E\uC744 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.";
+const SEARCH_NO_RESULT_HINTS = [
+  "\uAC80\uC0C9\uC5B4\uC758 \uCCA0\uC790\uAC00 \uC815\uD655\uD55C\uC9C0 \uD655\uC778\uD574 \uBCF4\uC138\uC694.",
+  "\uB2E4\uB978 \uAC80\uC0C9\uC5B4\uB85C \uB2E4\uC2DC \uAC80\uC0C9\uD574 \uBCF4\uC138\uC694.",
+  "\uB354 \uC77C\uBC18\uC801\uC778 \uAC80\uC0C9\uC5B4\uB97C \uC0AC\uC6A9\uD574 \uBCF4\uC138\uC694."
+];
+function SearchEmptyState({
+  query,
+  count = 0,
+  helpHref,
+  helpLabel = "\uAC80\uC0C9 \uB3C4\uC6C0\uB9D0",
+  hints,
+  title = SEARCH_NO_RESULT_MESSAGE,
+  ...rest
+}) {
+  const helpLink = helpHref ? helpHref.startsWith("/") ? /* @__PURE__ */ jsx(UiLink, { href: helpHref, className: "text-link underline hover:text-link-hover", children: helpLabel }) : /* @__PURE__ */ jsx("a", { href: helpHref, className: "text-link underline hover:text-link-hover", children: helpLabel }) : null;
+  const specHints = [
+    ...SEARCH_NO_RESULT_HINTS,
+    helpLink ? /* @__PURE__ */ jsxs(Fragment, { children: [
+      helpLink,
+      "\uC744 \uCC38\uACE0\uD558\uC138\uC694."
+    ] }) : `${helpLabel}\uC744 \uCC38\uACE0\uD558\uC138\uC694.`
+  ];
+  return /* @__PURE__ */ jsx(
+    EmptyState,
+    {
+      reason: "no-results",
+      title,
+      lead: count === null ? void 0 : /* @__PURE__ */ jsxs(Fragment, { children: [
+        query ? /* @__PURE__ */ jsxs(Fragment, { children: [
+          "\u300C",
+          /* @__PURE__ */ jsx("b", { className: "text-fg", children: query }),
+          "\u300D\uC5D0 \uB300\uD55C \uAC80\uC0C9 \uACB0\uACFC "
+        ] }) : "\uAC80\uC0C9 \uACB0\uACFC ",
+        /* @__PURE__ */ jsx("b", { className: "text-fg", children: count.toLocaleString("ko-KR") }),
+        "\uAC74"
+      ] }),
+      hints: hints ?? specHints,
+      ...rest
+    }
+  );
+}
+export {
+  EmptyState,
+  SEARCH_NO_RESULT_HINTS,
+  SEARCH_NO_RESULT_MESSAGE,
+  SearchEmptyState
+};
+//# sourceMappingURL=index.js.map