@x-plat/design-system 0.9.0 → 0.11.0

package/dist/components/Select/index.cjs

@@ -36,7 +36,7 @@ __export(Select_exports, {
 module.exports = __toCommonJS(Select_exports);
 
 // src/components/Select/Select.tsx
-var import_react5 = __toESM(require("react"), 1);
+var import_react6 = __toESM(require("react"), 1);
 
 // src/tokens/hooks/Portal.tsx
 var import_react_dom = __toESM(require("react-dom"), 1);
@@ -133,6 +133,30 @@ var useClickOutside = (refs, handler, enabled = true) => {
 };
 var useClickOutside_default = useClickOutside;
 
+// src/tokens/hooks/useOverlayKeyboard.ts
+var import_react3 = __toESM(require("react"), 1);
+var FOCUSABLE = [
+  "a[href]",
+  "button:not([disabled])",
+  "input:not([disabled]):not([type='hidden'])",
+  "select:not([disabled])",
+  "textarea:not([disabled])",
+  "[tabindex]:not([tabindex='-1'])"
+].join(",");
+var useEscapeKey = (enabled, onEscape) => {
+  import_react3.default.useEffect(() => {
+    if (!enabled) return;
+    const onKey = (e) => {
+      if (e.key !== "Escape") return;
+      if (e.defaultPrevented) return;
+      e.preventDefault();
+      onEscape();
+    };
+    document.addEventListener("keydown", onKey);
+    return () => document.removeEventListener("keydown", onKey);
+  }, [enabled, onEscape]);
+};
+
 // src/tokens/svg/action/CopyIcon.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
 
@@ -1163,27 +1187,32 @@ var FieldMessage = (props) => {
 };
 FieldMessage.displayName = "FieldMessage";
 var Field = (props) => {
-  const { validations, children } = props;
-  if (!validations || validations.length === 0) return /* @__PURE__ */ (0, import_jsx_runtime295.jsx)(import_jsx_runtime295.Fragment, { children });
+  const { label, required = false, htmlFor, validations, children } = props;
+  const hasMessages = !!validations && validations.length > 0;
+  if (!label && !hasMessages) return /* @__PURE__ */ (0, import_jsx_runtime295.jsx)(import_jsx_runtime295.Fragment, { children });
   return /* @__PURE__ */ (0, import_jsx_runtime295.jsxs)("div", { className: "lib-xplat-field", children: [
+    label && /* @__PURE__ */ (0, import_jsx_runtime295.jsxs)("label", { className: "lib-xplat-field-label", htmlFor, children: [
+      label,
+      required && /* @__PURE__ */ (0, import_jsx_runtime295.jsx)("span", { className: "required", "aria-hidden": "true", children: "*" })
+    ] }),
     children,
-    /* @__PURE__ */ (0, import_jsx_runtime295.jsx)(FieldMessage, { validations })
+    hasMessages && /* @__PURE__ */ (0, import_jsx_runtime295.jsx)(FieldMessage, { validations })
   ] });
 };
 Field.displayName = "Field";
 var hasError = (validations) => !!validations?.some((v) => v.status === "error");
 
 // src/components/Select/context.ts
-var import_react3 = __toESM(require("react"), 1);
-var SelectContext = import_react3.default.createContext(null);
+var import_react4 = __toESM(require("react"), 1);
+var SelectContext = import_react4.default.createContext(null);
 var context_default = SelectContext;
 
 // src/components/Select/SelectItem.tsx
-var import_react4 = __toESM(require("react"), 1);
+var import_react5 = __toESM(require("react"), 1);
 var import_jsx_runtime296 = require("react/jsx-runtime");
 var SelectItem = (props) => {
   const { children, value, onClick, disabled = false } = props;
-  const ctx = import_react4.default.useContext(context_default);
+  const ctx = import_react5.default.useContext(context_default);
   const handleClick = (e) => {
     e.preventDefault();
     e.stopPropagation();
@@ -1223,32 +1252,37 @@ var SelectRoot = (props) => {
     onChange,
     children,
     disabled = false,
+    searchable = false,
+    searchPlaceholder = "\uAC80\uC0C9",
     error = false,
     validations,
+    label,
+    required,
     size = "md"
   } = props;
-  const itemChildren = import_react5.default.Children.toArray(children).filter(
-    (child) => import_react5.default.isValidElement(child) && child.type === SelectItem_default
+  const fieldId = import_react6.default.useId();
+  const itemChildren = import_react6.default.Children.toArray(children).filter(
+    (child) => import_react6.default.isValidElement(child) && child.type === SelectItem_default
   );
   const isControlled = valueProp !== void 0;
-  const [isOpen, setOpen] = import_react5.default.useState(false);
-  const [uncontrolledLabel, setUncontrolledLabel] = import_react5.default.useState(null);
-  const [uncontrolledValue, setUncontrolledValue] = import_react5.default.useState(void 0);
-  const controlledLabel = import_react5.default.useMemo(() => {
+  const [isOpen, setOpen] = import_react6.default.useState(false);
+  const [uncontrolledLabel, setUncontrolledLabel] = import_react6.default.useState(null);
+  const [uncontrolledValue, setUncontrolledValue] = import_react6.default.useState(void 0);
+  const controlledLabel = import_react6.default.useMemo(() => {
     if (!isControlled) return null;
     const match = itemChildren.find((child) => child.props.value === valueProp);
     return match ? match.props.children : null;
   }, [isControlled, valueProp, itemChildren]);
   const selectedLabel = isControlled ? controlledLabel : uncontrolledLabel;
   const selectedValue = isControlled ? valueProp : uncontrolledValue;
-  const triggerRef = import_react5.default.useRef(null);
-  const contentRef = import_react5.default.useRef(null);
-  const [mounted, setMounted] = import_react5.default.useState(false);
-  const [visible, setVisible] = import_react5.default.useState(false);
-  import_react5.default.useEffect(() => {
+  const triggerRef = import_react6.default.useRef(null);
+  const contentRef = import_react6.default.useRef(null);
+  const [mounted, setMounted] = import_react6.default.useState(false);
+  const [visible, setVisible] = import_react6.default.useState(false);
+  import_react6.default.useEffect(() => {
     if (disabled && isOpen) setOpen(false);
   }, [disabled, isOpen]);
-  import_react5.default.useEffect(() => {
+  import_react6.default.useEffect(() => {
     if (isOpen) {
       setMounted(true);
       const t2 = setTimeout(() => setVisible(true), 1);
@@ -1258,22 +1292,42 @@ var SelectRoot = (props) => {
     const t = setTimeout(() => setMounted(false), ANIMATION_DURATION_MS);
     return () => clearTimeout(t);
   }, [isOpen]);
-  const open = import_react5.default.useCallback(() => setOpen(true), []);
-  const close = import_react5.default.useCallback(() => setOpen(false), []);
-  const toggle = import_react5.default.useCallback(() => setOpen((prev) => !prev), []);
+  const [query, setQuery] = import_react6.default.useState("");
+  const textOf = (node) => {
+    if (node === null || node === void 0 || typeof node === "boolean") return "";
+    if (typeof node === "string" || typeof node === "number") return String(node);
+    if (Array.isArray(node)) return node.map(textOf).join("");
+    if (import_react6.default.isValidElement(node)) return textOf(node.props.children);
+    return "";
+  };
+  const visibleItems = import_react6.default.useMemo(() => {
+    if (!searchable || !query.trim()) return itemChildren;
+    const q = query.trim().toLowerCase();
+    return itemChildren.filter((c) => textOf(c.props.children).toLowerCase().includes(q));
+  }, [searchable, query, itemChildren]);
+  const open = import_react6.default.useCallback(() => setOpen(true), []);
+  const close = import_react6.default.useCallback(() => {
+    setOpen(false);
+    setQuery("");
+  }, []);
+  const toggle = import_react6.default.useCallback(() => setOpen((prev) => !prev), []);
   useClickOutside_default([contentRef, triggerRef], close, isOpen);
+  useEscapeKey(isOpen, () => {
+    close();
+    triggerRef.current?.focus({ preventScroll: true });
+  });
   const position = useAutoPosition_default(triggerRef, contentRef, mounted);
-  const setSelected = import_react5.default.useCallback(
-    (label, itemValue) => {
+  const setSelected = import_react6.default.useCallback(
+    (label2, itemValue) => {
       if (!isControlled) {
-        setUncontrolledLabel(label);
+        setUncontrolledLabel(label2);
         setUncontrolledValue(itemValue);
       }
-      onChange?.(itemValue, label);
+      onChange?.(itemValue, label2);
     },
     [isControlled, onChange]
   );
-  const ctxValue = import_react5.default.useMemo(
+  const ctxValue = import_react6.default.useMemo(
     () => ({
       isOpen,
       mounted,
@@ -1309,6 +1363,7 @@ var SelectRoot = (props) => {
         /* @__PURE__ */ (0, import_jsx_runtime297.jsxs)(
           "div",
           {
+            id: fieldId,
             ref: triggerRef,
             className: clsx_default(
               "select-trigger",
@@ -1351,20 +1406,33 @@ var SelectRoot = (props) => {
             ]
           }
         ),
-        mounted && /* @__PURE__ */ (0, import_jsx_runtime297.jsx)(Portal_default, { children: /* @__PURE__ */ (0, import_jsx_runtime297.jsx)(
+        mounted && /* @__PURE__ */ (0, import_jsx_runtime297.jsx)(Portal_default, { children: /* @__PURE__ */ (0, import_jsx_runtime297.jsxs)(
           "div",
           {
             className: clsx_default("lib-xplat-select-content", size, position.direction, stateClass),
             ref: contentRef,
             style: { ...position.position, width: triggerRef.current?.offsetWidth },
             role: "listbox",
-            children: /* @__PURE__ */ (0, import_jsx_runtime297.jsx)(context_default.Provider, { value: ctxValue, children: itemChildren })
+            children: [
+              searchable && /* @__PURE__ */ (0, import_jsx_runtime297.jsx)("div", { className: "select-search", children: /* @__PURE__ */ (0, import_jsx_runtime297.jsx)(
+                "input",
+                {
+                  type: "text",
+                  value: query,
+                  placeholder: searchPlaceholder,
+                  onChange: (e) => setQuery(e.target.value),
+                  autoFocus: true,
+                  "aria-label": searchPlaceholder
+                }
+              ) }),
+              /* @__PURE__ */ (0, import_jsx_runtime297.jsx)(context_default.Provider, { value: ctxValue, children: visibleItems.length > 0 ? visibleItems : /* @__PURE__ */ (0, import_jsx_runtime297.jsx)("div", { className: "select-empty", children: "\uACB0\uACFC\uAC00 \uC5C6\uC2B5\uB2C8\uB2E4" }) })
+            ]
           }
         ) })
       ]
     }
   ) });
-  return /* @__PURE__ */ (0, import_jsx_runtime297.jsx)(Field, { validations, children: control });
+  return /* @__PURE__ */ (0, import_jsx_runtime297.jsx)(Field, { validations, label, required, htmlFor: fieldId, children: control });
 };
 SelectRoot.displayName = "Select";
 var Select = Object.assign(SelectRoot, {

package/dist/components/Select/index.css

@@ -6,6 +6,21 @@
   flex-direction: column;
   gap: var(--spacing-space-2);
 }
+.lib-xplat-field-label {
+  font-family: var(--semantic-typo-label-2-m-font);
+  font-size: var(--semantic-typo-label-2-m-size);
+  line-height: var(--semantic-typo-label-2-m-lh);
+  font-weight: var(--semantic-typo-label-2-m-weight);
+  letter-spacing: var(--semantic-typo-label-2-m-ls);
+  color: var(--semantic-text-secondary);
+  display: inline-flex;
+  align-items: center;
+  gap: var(--spacing-space-1);
+  cursor: pointer;
+}
+.lib-xplat-field-label > .required {
+  color: var(--semantic-text-error);
+}
 .lib-xplat-field-message-wrap {
   display: flex;
   gap: var(--spacing-space-2);
@@ -144,6 +159,45 @@
 .lib-xplat-select .select-trigger .select-trigger-icon svg {
   font-size: var(--semantic-typo-label-1-m-size);
 }
+.lib-xplat-select-content .select-search {
+  position: sticky;
+  top: 0;
+  z-index: 1;
+  padding: var(--spacing-space-2);
+  background-color: var(--semantic-surface-neutral-primary);
+  border-bottom: 1px solid var(--semantic-border-secondary);
+}
+.lib-xplat-select-content .select-search > input {
+  width: 100%;
+  border: 1px solid var(--semantic-border-primary);
+  border-radius: var(--spacing-radius-sm);
+  padding: var(--spacing-space-1) var(--spacing-space-2);
+  outline: none;
+  color: var(--semantic-text-primary);
+  background-color: var(--semantic-surface-neutral-primary);
+  font-family: var(--semantic-typo-label-2-m-font);
+  font-size: var(--semantic-typo-label-2-m-size);
+  line-height: var(--semantic-typo-label-2-m-lh);
+  font-weight: var(--semantic-typo-label-2-m-weight);
+  letter-spacing: var(--semantic-typo-label-2-m-ls);
+  transition: border-color 0.28s cubic-bezier(0.25, 0.46, 0.45, 0.94), box-shadow 0.28s cubic-bezier(0.25, 0.46, 0.45, 0.94);
+}
+.lib-xplat-select-content .select-search > input:focus {
+  border-color: var(--semantic-interaction-focus-ring);
+  box-shadow: 0 0 0 2px var(--semantic-interaction-overlay-10);
+  outline: 2px solid transparent;
+  outline-offset: 2px;
+}
+.lib-xplat-select-content .select-empty {
+  padding: var(--spacing-space-3);
+  text-align: center;
+  color: var(--semantic-text-tertiary);
+  font-family: var(--semantic-typo-label-2-m-font);
+  font-size: var(--semantic-typo-label-2-m-size);
+  line-height: var(--semantic-typo-label-2-m-lh);
+  font-weight: var(--semantic-typo-label-2-m-weight);
+  letter-spacing: var(--semantic-typo-label-2-m-ls);
+}
 .lib-xplat-select-content {
   position: fixed;
   z-index: 1000;

package/dist/components/Select/index.d.cts

@@ -8,6 +8,7 @@ interface SelectItemProps {
     value?: string | number;
     /** 클릭 시 추가로 실행할 핸들러 (선택 처리 후 호출) */
     onClick?: () => void;
+    /** 열리지 않게 막는다 */
     disabled?: boolean;
 }
 declare const SelectItem: {
@@ -18,7 +19,9 @@ declare const SelectItem: {
 /** Select.Item 으로만 만든 엘리먼트 (다른 컴포넌트/노드 넣으면 타입 오류) */
 type SelectItemElement = React.ReactElement<SelectItemProps, typeof SelectItem>;
 /** 값 변경 시 호출 (value: 아이템 value, label: 표시 텍스트) */
-type SelectChangeHandler = (value: string | number | undefined, label: React.ReactNode) => void;
+type SelectChangeHandler = (
+/** 선택된 값. 주면 controlled 가 된다 */
+value: string | number | undefined, label: React.ReactNode) => void;
 type SelectSize = "sm" | "md" | "lg";
 interface SelectProps {
     /** 선택 전 표시할 문구 */
@@ -34,6 +37,18 @@ interface SelectProps {
     /** 에러 상태 */
     /** 컨트롤 아래에 표시할 검증 메시지. DS 폼 컴포넌트 공통 */
     validations?: Validation[];
+    /** 메시지 없이 테두리만 붉게 한다. validations 와 함께 쓰면 둘 중 하나만 참이어도 적용된다 */
+    /** 컨트롤 위에 붙는 라벨. 클릭하면 컨트롤에 포커스가 간다 */
+    label?: React.ReactNode;
+    /** 라벨 뒤에 필수 표시(*)를 붙인다 */
+    required?: boolean;
+    /**
+     * 목록 위에 검색칸을 띄운다. 항목이 많아 스크롤로 찾기 어려울 때 켠다.
+     * 항목의 children 텍스트로 걸러낸다
+     */
+    searchable?: boolean;
+    /** 검색칸 안내 문구 */
+    searchPlaceholder?: string;
     error?: boolean;
     /** 사이즈 */
     size?: SelectSize;

package/dist/components/Select/index.d.ts

@@ -8,6 +8,7 @@ interface SelectItemProps {
     value?: string | number;
     /** 클릭 시 추가로 실행할 핸들러 (선택 처리 후 호출) */
     onClick?: () => void;
+    /** 열리지 않게 막는다 */
     disabled?: boolean;
 }
 declare const SelectItem: {
@@ -18,7 +19,9 @@ declare const SelectItem: {
 /** Select.Item 으로만 만든 엘리먼트 (다른 컴포넌트/노드 넣으면 타입 오류) */
 type SelectItemElement = React.ReactElement<SelectItemProps, typeof SelectItem>;
 /** 값 변경 시 호출 (value: 아이템 value, label: 표시 텍스트) */
-type SelectChangeHandler = (value: string | number | undefined, label: React.ReactNode) => void;
+type SelectChangeHandler = (
+/** 선택된 값. 주면 controlled 가 된다 */
+value: string | number | undefined, label: React.ReactNode) => void;
 type SelectSize = "sm" | "md" | "lg";
 interface SelectProps {
     /** 선택 전 표시할 문구 */
@@ -34,6 +37,18 @@ interface SelectProps {
     /** 에러 상태 */
     /** 컨트롤 아래에 표시할 검증 메시지. DS 폼 컴포넌트 공통 */
     validations?: Validation[];
+    /** 메시지 없이 테두리만 붉게 한다. validations 와 함께 쓰면 둘 중 하나만 참이어도 적용된다 */
+    /** 컨트롤 위에 붙는 라벨. 클릭하면 컨트롤에 포커스가 간다 */
+    label?: React.ReactNode;
+    /** 라벨 뒤에 필수 표시(*)를 붙인다 */
+    required?: boolean;
+    /**
+     * 목록 위에 검색칸을 띄운다. 항목이 많아 스크롤로 찾기 어려울 때 켠다.
+     * 항목의 children 텍스트로 걸러낸다
+     */
+    searchable?: boolean;
+    /** 검색칸 안내 문구 */
+    searchPlaceholder?: string;
     error?: boolean;
     /** 사이즈 */
     size?: SelectSize;

package/dist/components/Select/index.js

@@ -1,5 +1,5 @@
 // src/components/Select/Select.tsx
-import React5 from "react";
+import React6 from "react";
 
 // src/tokens/hooks/Portal.tsx
 import ReactDOM from "react-dom";
@@ -96,6 +96,30 @@ var useClickOutside = (refs, handler, enabled = true) => {
 };
 var useClickOutside_default = useClickOutside;
 
+// src/tokens/hooks/useOverlayKeyboard.ts
+import React3 from "react";
+var FOCUSABLE = [
+  "a[href]",
+  "button:not([disabled])",
+  "input:not([disabled]):not([type='hidden'])",
+  "select:not([disabled])",
+  "textarea:not([disabled])",
+  "[tabindex]:not([tabindex='-1'])"
+].join(",");
+var useEscapeKey = (enabled, onEscape) => {
+  React3.useEffect(() => {
+    if (!enabled) return;
+    const onKey = (e) => {
+      if (e.key !== "Escape") return;
+      if (e.defaultPrevented) return;
+      e.preventDefault();
+      onEscape();
+    };
+    document.addEventListener("keydown", onKey);
+    return () => document.removeEventListener("keydown", onKey);
+  }, [enabled, onEscape]);
+};
+
 // src/tokens/svg/action/CopyIcon.tsx
 import { jsx, jsxs } from "react/jsx-runtime";
 
@@ -1126,27 +1150,32 @@ var FieldMessage = (props) => {
 };
 FieldMessage.displayName = "FieldMessage";
 var Field = (props) => {
-  const { validations, children } = props;
-  if (!validations || validations.length === 0) return /* @__PURE__ */ jsx295(Fragment, { children });
+  const { label, required = false, htmlFor, validations, children } = props;
+  const hasMessages = !!validations && validations.length > 0;
+  if (!label && !hasMessages) return /* @__PURE__ */ jsx295(Fragment, { children });
   return /* @__PURE__ */ jsxs189("div", { className: "lib-xplat-field", children: [
+    label && /* @__PURE__ */ jsxs189("label", { className: "lib-xplat-field-label", htmlFor, children: [
+      label,
+      required && /* @__PURE__ */ jsx295("span", { className: "required", "aria-hidden": "true", children: "*" })
+    ] }),
     children,
-    /* @__PURE__ */ jsx295(FieldMessage, { validations })
+    hasMessages && /* @__PURE__ */ jsx295(FieldMessage, { validations })
   ] });
 };
 Field.displayName = "Field";
 var hasError = (validations) => !!validations?.some((v) => v.status === "error");
 
 // src/components/Select/context.ts
-import React3 from "react";
-var SelectContext = React3.createContext(null);
+import React4 from "react";
+var SelectContext = React4.createContext(null);
 var context_default = SelectContext;
 
 // src/components/Select/SelectItem.tsx
-import React4 from "react";
+import React5 from "react";
 import { jsx as jsx296 } from "react/jsx-runtime";
 var SelectItem = (props) => {
   const { children, value, onClick, disabled = false } = props;
-  const ctx = React4.useContext(context_default);
+  const ctx = React5.useContext(context_default);
   const handleClick = (e) => {
     e.preventDefault();
     e.stopPropagation();
@@ -1186,32 +1215,37 @@ var SelectRoot = (props) => {
     onChange,
     children,
     disabled = false,
+    searchable = false,
+    searchPlaceholder = "\uAC80\uC0C9",
     error = false,
     validations,
+    label,
+    required,
     size = "md"
   } = props;
-  const itemChildren = React5.Children.toArray(children).filter(
-    (child) => React5.isValidElement(child) && child.type === SelectItem_default
+  const fieldId = React6.useId();
+  const itemChildren = React6.Children.toArray(children).filter(
+    (child) => React6.isValidElement(child) && child.type === SelectItem_default
   );
   const isControlled = valueProp !== void 0;
-  const [isOpen, setOpen] = React5.useState(false);
-  const [uncontrolledLabel, setUncontrolledLabel] = React5.useState(null);
-  const [uncontrolledValue, setUncontrolledValue] = React5.useState(void 0);
-  const controlledLabel = React5.useMemo(() => {
+  const [isOpen, setOpen] = React6.useState(false);
+  const [uncontrolledLabel, setUncontrolledLabel] = React6.useState(null);
+  const [uncontrolledValue, setUncontrolledValue] = React6.useState(void 0);
+  const controlledLabel = React6.useMemo(() => {
     if (!isControlled) return null;
     const match = itemChildren.find((child) => child.props.value === valueProp);
     return match ? match.props.children : null;
   }, [isControlled, valueProp, itemChildren]);
   const selectedLabel = isControlled ? controlledLabel : uncontrolledLabel;
   const selectedValue = isControlled ? valueProp : uncontrolledValue;
-  const triggerRef = React5.useRef(null);
-  const contentRef = React5.useRef(null);
-  const [mounted, setMounted] = React5.useState(false);
-  const [visible, setVisible] = React5.useState(false);
-  React5.useEffect(() => {
+  const triggerRef = React6.useRef(null);
+  const contentRef = React6.useRef(null);
+  const [mounted, setMounted] = React6.useState(false);
+  const [visible, setVisible] = React6.useState(false);
+  React6.useEffect(() => {
     if (disabled && isOpen) setOpen(false);
   }, [disabled, isOpen]);
-  React5.useEffect(() => {
+  React6.useEffect(() => {
     if (isOpen) {
       setMounted(true);
       const t2 = setTimeout(() => setVisible(true), 1);
@@ -1221,22 +1255,42 @@ var SelectRoot = (props) => {
     const t = setTimeout(() => setMounted(false), ANIMATION_DURATION_MS);
     return () => clearTimeout(t);
   }, [isOpen]);
-  const open = React5.useCallback(() => setOpen(true), []);
-  const close = React5.useCallback(() => setOpen(false), []);
-  const toggle = React5.useCallback(() => setOpen((prev) => !prev), []);
+  const [query, setQuery] = React6.useState("");
+  const textOf = (node) => {
+    if (node === null || node === void 0 || typeof node === "boolean") return "";
+    if (typeof node === "string" || typeof node === "number") return String(node);
+    if (Array.isArray(node)) return node.map(textOf).join("");
+    if (React6.isValidElement(node)) return textOf(node.props.children);
+    return "";
+  };
+  const visibleItems = React6.useMemo(() => {
+    if (!searchable || !query.trim()) return itemChildren;
+    const q = query.trim().toLowerCase();
+    return itemChildren.filter((c) => textOf(c.props.children).toLowerCase().includes(q));
+  }, [searchable, query, itemChildren]);
+  const open = React6.useCallback(() => setOpen(true), []);
+  const close = React6.useCallback(() => {
+    setOpen(false);
+    setQuery("");
+  }, []);
+  const toggle = React6.useCallback(() => setOpen((prev) => !prev), []);
   useClickOutside_default([contentRef, triggerRef], close, isOpen);
+  useEscapeKey(isOpen, () => {
+    close();
+    triggerRef.current?.focus({ preventScroll: true });
+  });
   const position = useAutoPosition_default(triggerRef, contentRef, mounted);
-  const setSelected = React5.useCallback(
-    (label, itemValue) => {
+  const setSelected = React6.useCallback(
+    (label2, itemValue) => {
       if (!isControlled) {
-        setUncontrolledLabel(label);
+        setUncontrolledLabel(label2);
         setUncontrolledValue(itemValue);
       }
-      onChange?.(itemValue, label);
+      onChange?.(itemValue, label2);
     },
     [isControlled, onChange]
   );
-  const ctxValue = React5.useMemo(
+  const ctxValue = React6.useMemo(
     () => ({
       isOpen,
       mounted,
@@ -1272,6 +1326,7 @@ var SelectRoot = (props) => {
         /* @__PURE__ */ jsxs190(
           "div",
           {
+            id: fieldId,
             ref: triggerRef,
             className: clsx_default(
               "select-trigger",
@@ -1314,20 +1369,33 @@ var SelectRoot = (props) => {
             ]
           }
         ),
-        mounted && /* @__PURE__ */ jsx297(Portal_default, { children: /* @__PURE__ */ jsx297(
+        mounted && /* @__PURE__ */ jsx297(Portal_default, { children: /* @__PURE__ */ jsxs190(
           "div",
           {
             className: clsx_default("lib-xplat-select-content", size, position.direction, stateClass),
             ref: contentRef,
             style: { ...position.position, width: triggerRef.current?.offsetWidth },
             role: "listbox",
-            children: /* @__PURE__ */ jsx297(context_default.Provider, { value: ctxValue, children: itemChildren })
+            children: [
+              searchable && /* @__PURE__ */ jsx297("div", { className: "select-search", children: /* @__PURE__ */ jsx297(
+                "input",
+                {
+                  type: "text",
+                  value: query,
+                  placeholder: searchPlaceholder,
+                  onChange: (e) => setQuery(e.target.value),
+                  autoFocus: true,
+                  "aria-label": searchPlaceholder
+                }
+              ) }),
+              /* @__PURE__ */ jsx297(context_default.Provider, { value: ctxValue, children: visibleItems.length > 0 ? visibleItems : /* @__PURE__ */ jsx297("div", { className: "select-empty", children: "\uACB0\uACFC\uAC00 \uC5C6\uC2B5\uB2C8\uB2E4" }) })
+            ]
           }
         ) })
       ]
     }
   ) });
-  return /* @__PURE__ */ jsx297(Field, { validations, children: control });
+  return /* @__PURE__ */ jsx297(Field, { validations, label, required, htmlFor: fieldId, children: control });
 };
 SelectRoot.displayName = "Select";
 var Select = Object.assign(SelectRoot, {

package/dist/components/Skeleton/index.d.cts

@@ -3,8 +3,11 @@ import React from 'react';
 type SkeletonVariant = "text" | "circular" | "rectangular";
 type SizeToken = "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "full";
 interface SkeletonProps {
+    /** 자리표시자 모양 */
     variant?: SkeletonVariant;
+    /** 가로 크기 */
     width?: SizeToken;
+    /** 세로 크기 */
     height?: SizeToken;
 }
 declare const Skeleton: React.FC<SkeletonProps>;

package/dist/components/Skeleton/index.d.ts

@@ -3,8 +3,11 @@ import React from 'react';
 type SkeletonVariant = "text" | "circular" | "rectangular";
 type SizeToken = "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "full";
 interface SkeletonProps {
+    /** 자리표시자 모양 */
     variant?: SkeletonVariant;
+    /** 가로 크기 */
     width?: SizeToken;
+    /** 세로 크기 */
     height?: SizeToken;
 }
 declare const Skeleton: React.FC<SkeletonProps>;

package/dist/components/Spinner/index.cjs

@@ -24,6 +24,9 @@ __export(Spinner_exports, {
 });
 module.exports = __toCommonJS(Spinner_exports);
 
+// src/tokens/interface/status.ts
+var normalizeStatus = (value) => value === "brand" ? "primary" : value;
+
 // ../../node_modules/clsx/dist/clsx.mjs
 function r(e) {
   var t, f, n = "";
@@ -45,12 +48,13 @@ var import_jsx_runtime = require("react/jsx-runtime");
 var Spinner = (props) => {
   const {
     size = "md",
-    type = "brand"
+    type = "primary"
   } = props;
+  const statusType = normalizeStatus(type);
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
     "div",
     {
-      className: clsx_default("lib-xplat-spinner", size, type),
+      className: clsx_default("lib-xplat-spinner", size, statusType),
       role: "status",
       "aria-label": "\uB85C\uB529 \uC911",
       children: /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("svg", { viewBox: "0 0 24 24", fill: "none", xmlns: "http://www.w3.org/2000/svg", children: [

package/dist/components/Spinner/index.css

@@ -33,6 +33,7 @@
   stroke-dasharray: 42;
   stroke-dashoffset: 28;
 }
+.lib-xplat-spinner.primary .indicator,
 .lib-xplat-spinner.brand .indicator {
   stroke: var(--semantic-surface-brand-default);
 }