@thewrong/ui 0.2.0 → 0.4.0

package/dist/components/segmented-code-input/index.d.ts

@@ -0,0 +1,2 @@
+export { SegmentedCodeInput } from './SegmentedCodeInput.js';
+export type { SegmentedCodeInputProps } from './SegmentedCodeInput.js';

package/dist/components/segmented-control/SegmentedControl.cjs

@@ -0,0 +1 @@
+const e=require("../../lib/utils.cjs");let t=require("react"),n=require("react/jsx-runtime");function r({value:r,onChange:i,options:a,name:o,"aria-label":s,"aria-labelledby":c,disabled:l,className:u}){let d=(0,t.useId)(),f=o??d,p=(0,t.useRef)(new Map),m=(0,t.useRef)(null),[h,g]=(0,t.useState)(null),_=(0,t.useCallback)(()=>{let e=p.current.get(r);if(!e){g(null);return}g(t=>({left:e.offsetLeft,width:e.offsetWidth,animate:t!==null}))},[r]);(0,t.useLayoutEffect)(()=>{_()},[_]),(0,t.useLayoutEffect)(()=>{if(typeof ResizeObserver>`u`)return;let e=new ResizeObserver(_);return m.current=e,p.current.forEach(t=>e.observe(t)),()=>{e.disconnect(),m.current=null}},[_]);let v=(0,t.useCallback)(e=>t=>{let n=p.current.get(e);n&&m.current?.unobserve(n),t?(p.current.set(e,t),m.current?.observe(t)):p.current.delete(e)},[]),y=e=>{let t=e.key===`ArrowRight`||e.key===`ArrowDown`?1:e.key===`ArrowLeft`||e.key===`ArrowUp`?-1:0;if(t===0)return;let n=e.currentTarget,r=Array.from(n.ownerDocument.getElementsByName(n.name)).filter(e=>e instanceof HTMLInputElement&&e.type===`radio`&&e.form===n.form&&!e.disabled),i=r.indexOf(n);if(i<0||r.length<2)return;e.preventDefault();let a=r[(i+t+r.length)%r.length];a?.focus(),a?.click()};return(0,n.jsxs)(`div`,{role:`radiogroup`,"aria-label":s,"aria-labelledby":c,className:e.cn(`relative inline-flex items-stretch gap-1 rounded-control-medium border-control border-border-subtle bg-bg-surface p-1`,u),children:[(0,n.jsx)(`span`,{"aria-hidden":`true`,"data-segmented-control-indicator":!0,className:e.cn(`pointer-events-none absolute top-1 bottom-1 left-0 rounded-control-small bg-bg-subtle transition-[transform,width] duration-200 ease-out motion-reduce:transition-none`,!h?.animate&&`transition-none`,!h&&`hidden`),style:{transform:`translateX(${h?.left??0}px)`,width:`${h?.width??0}px`}}),a.map(t=>{let a=t.value===r,o=l||t.disabled;return(0,n.jsxs)(`label`,{ref:v(t.value),className:e.cn(`relative flex flex-1 items-center justify-center`,o?`cursor-not-allowed`:`cursor-pointer`),children:[(0,n.jsx)(`input`,{type:`radio`,className:`peer sr-only`,name:f,value:t.value,checked:a,disabled:o,onChange:()=>i(t.value),onKeyDown:y}),(0,n.jsxs)(`span`,{className:e.cn(`relative z-10 flex h-full w-full min-w-0 items-center justify-center gap-slot-small rounded-control-small px-2 py-1.5 text-control-small font-control-field font-medium text-fg-muted outline-none transition-colors duration-control ease-control`,!o&&`hover:text-fg-default`,`peer-checked:font-semibold peer-checked:text-fg-default`,`peer-focus:ring-control peer-focus:ring-focus-primary peer-focus:ring-offset-2 peer-focus:ring-offset-bg-surface`,`peer-disabled:text-fg-disabled peer-disabled:hover:bg-transparent`),children:[t.icon?(0,n.jsx)(`span`,{"aria-hidden":`true`,"data-segmented-control-leading":!0,className:`flex h-slot-icon-small w-slot-icon-small shrink-0 items-center justify-center [&>*]:h-slot-icon-small [&>*]:w-slot-icon-small`,children:t.icon}):null,(0,n.jsx)(`span`,{"data-segmented-control-label":!0,className:`min-w-0 truncate`,children:t.label})]})]},t.value)})]})}exports.SegmentedControl=r;

package/dist/components/segmented-control/SegmentedControl.d.ts

@@ -0,0 +1,27 @@
+import { SegmentedControlProps } from './types.js';
+/**
+ * 알약형 컨테이너 하나 안에 칸으로 나뉜 세그먼트 컨트롤.
+ *
+ * 2~3택 짧은 선택지가 여러 줄 쌓이는 설정 화면에 적합하다. 원형 indicator
+ * 없이 흰 바탕+테두리 컨테이너 안에서 칸이 폭을 균등 분배(2택=50%,
+ * 3택=33%)하며, 선택 표시는 각 칸의 배경이 아니라 컨테이너 안에서
+ * 미끄러지는 인디케이터 하나(`bg-bg-subtle`)가 담당한다.
+ *
+ * 네이티브 semantics(`role="radiogroup"` + sr-only `type="radio"` input)를
+ * 유지해 방향키 roving focus·Space 선택·스크린리더 announcement가 그대로
+ * 동작한다.
+ *
+ * @example
+ * ```tsx
+ * <SegmentedControl
+ *   aria-label="주기"
+ *   value={period}
+ *   onChange={setPeriod}
+ *   options={[
+ *     { value: "month", label: "월간" },
+ *     { value: "year", label: "연간" },
+ *   ]}
+ * />
+ * ```
+ */
+export declare function SegmentedControl<V extends string>({ value, onChange, options, name, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, disabled, className, }: SegmentedControlProps<V>): import("react").JSX.Element;

package/dist/components/segmented-control/SegmentedControl.esm.js

@@ -0,0 +1,84 @@
+import { cn as e } from "../../lib/utils.esm.js";
+import { useCallback as t, useId as n, useLayoutEffect as r, useRef as i, useState as a } from "react";
+import { jsx as o, jsxs as s } from "react/jsx-runtime";
+//#region src/components/segmented-control/SegmentedControl.tsx
+function c({ value: c, onChange: l, options: u, name: d, "aria-label": f, "aria-labelledby": p, disabled: m, className: h }) {
+	let g = n(), _ = d ?? g, v = i(/* @__PURE__ */ new Map()), y = i(null), [b, x] = a(null), S = t(() => {
+		let e = v.current.get(c);
+		if (!e) {
+			x(null);
+			return;
+		}
+		x((t) => ({
+			left: e.offsetLeft,
+			width: e.offsetWidth,
+			animate: t !== null
+		}));
+	}, [c]);
+	r(() => {
+		S();
+	}, [S]), r(() => {
+		if (typeof ResizeObserver > "u") return;
+		let e = new ResizeObserver(S);
+		return y.current = e, v.current.forEach((t) => e.observe(t)), () => {
+			e.disconnect(), y.current = null;
+		};
+	}, [S]);
+	let C = t((e) => (t) => {
+		let n = v.current.get(e);
+		n && y.current?.unobserve(n), t ? (v.current.set(e, t), y.current?.observe(t)) : v.current.delete(e);
+	}, []), w = (e) => {
+		let t = e.key === "ArrowRight" || e.key === "ArrowDown" ? 1 : e.key === "ArrowLeft" || e.key === "ArrowUp" ? -1 : 0;
+		if (t === 0) return;
+		let n = e.currentTarget, r = Array.from(n.ownerDocument.getElementsByName(n.name)).filter((e) => e instanceof HTMLInputElement && e.type === "radio" && e.form === n.form && !e.disabled), i = r.indexOf(n);
+		if (i < 0 || r.length < 2) return;
+		e.preventDefault();
+		let a = r[(i + t + r.length) % r.length];
+		a?.focus(), a?.click();
+	};
+	return /* @__PURE__ */ s("div", {
+		role: "radiogroup",
+		"aria-label": f,
+		"aria-labelledby": p,
+		className: e("relative inline-flex items-stretch gap-1 rounded-control-medium border-control border-border-subtle bg-bg-surface p-1", h),
+		children: [/* @__PURE__ */ o("span", {
+			"aria-hidden": "true",
+			"data-segmented-control-indicator": !0,
+			className: e("pointer-events-none absolute top-1 bottom-1 left-0 rounded-control-small bg-bg-subtle transition-[transform,width] duration-200 ease-out motion-reduce:transition-none", !b?.animate && "transition-none", !b && "hidden"),
+			style: {
+				transform: `translateX(${b?.left ?? 0}px)`,
+				width: `${b?.width ?? 0}px`
+			}
+		}), u.map((t) => {
+			let n = t.value === c, r = m || t.disabled;
+			return /* @__PURE__ */ s("label", {
+				ref: C(t.value),
+				className: e("relative flex flex-1 items-center justify-center", r ? "cursor-not-allowed" : "cursor-pointer"),
+				children: [/* @__PURE__ */ o("input", {
+					type: "radio",
+					className: "peer sr-only",
+					name: _,
+					value: t.value,
+					checked: n,
+					disabled: r,
+					onChange: () => l(t.value),
+					onKeyDown: w
+				}), /* @__PURE__ */ s("span", {
+					className: e("relative z-10 flex h-full w-full min-w-0 items-center justify-center gap-slot-small rounded-control-small px-2 py-1.5 text-control-small font-control-field font-medium text-fg-muted outline-none transition-colors duration-control ease-control", !r && "hover:text-fg-default", "peer-checked:font-semibold peer-checked:text-fg-default", "peer-focus:ring-control peer-focus:ring-focus-primary peer-focus:ring-offset-2 peer-focus:ring-offset-bg-surface", "peer-disabled:text-fg-disabled peer-disabled:hover:bg-transparent"),
+					children: [t.icon ? /* @__PURE__ */ o("span", {
+						"aria-hidden": "true",
+						"data-segmented-control-leading": !0,
+						className: "flex h-slot-icon-small w-slot-icon-small shrink-0 items-center justify-center [&>*]:h-slot-icon-small [&>*]:w-slot-icon-small",
+						children: t.icon
+					}) : null, /* @__PURE__ */ o("span", {
+						"data-segmented-control-label": !0,
+						className: "min-w-0 truncate",
+						children: t.label
+					})]
+				})]
+			}, t.value);
+		})]
+	});
+}
+//#endregion
+export { c as SegmentedControl };

package/dist/components/segmented-control/index.d.ts

@@ -0,0 +1,2 @@
+export { SegmentedControl } from './SegmentedControl.js';
+export type { SegmentedControlOption, SegmentedControlProps } from './types.js';

package/dist/components/segmented-control/types.d.ts

@@ -0,0 +1,30 @@
+import { ReactNode } from 'react';
+export interface SegmentedControlOption<V extends string> {
+    /** 이 칸이 나타내는 값. */
+    value: V;
+    /** 칸에 표시할 라벨. */
+    label: ReactNode;
+    /** 라벨 앞에 표시할 선택적 아이콘. */
+    icon?: ReactNode;
+    /** 이 칸만 개별적으로 비활성화합니다. */
+    disabled?: boolean;
+}
+export interface SegmentedControlProps<V extends string> {
+    /** 현재 선택된 값. */
+    value: V;
+    /** 값이 바뀌면 호출됩니다. */
+    onChange: (next: V) => void;
+    /** 표시할 옵션 목록. */
+    options: readonly SegmentedControlOption<V>[];
+    /**
+     * 내부 네이티브 radio input들이 공유할 `name`.
+     * @default useId()로 생성된 고유 값
+     */
+    name?: string;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    /** 전체 컨트롤을 비활성화합니다. */
+    disabled?: boolean;
+    /** 컨테이너에 추가할 클래스. */
+    className?: string;
+}

package/dist/components/select/MultiSelect.cjs

@@ -0,0 +1 @@
+const e=require("../../lib/utils.cjs"),t=require("../../node_modules/lucide-react/dist/esm/icons/check.cjs"),n=require("../../node_modules/lucide-react/dist/esm/icons/chevron-down.cjs"),r=require("../../node_modules/lucide-react/dist/esm/icons/circle-x.cjs"),i=require("../../node_modules/lucide-react/dist/esm/icons/search.cjs"),a=require("../_shared/form-size-tokens.cjs"),o=require("../input/utils.cjs"),ee=require("./loading-dots.cjs"),te=require("./panel-width.cjs");let s=require("react"),c=require("react/jsx-runtime"),l=require("@floating-ui/react");var ne=e=>e.length===0?``:e.map(e=>e.label).join(`, `),re=e=>e.length===0?``:`${e.length}개 선택`,u=(0,s.forwardRef)(function({options:u,value:d,onChange:f,variant:ie,selectSize:p=`medium`,label:m,"aria-label":ae,"aria-labelledby":oe,labelOption:h=`appear`,help:g,placeholder:se=`선택해주세요`,hasError:_=!1,disabled:v=!1,suffix:y,trailingIcon:ce,clearable:b=!1,badge:x,searchable:S=!1,searchPlaceholder:le=`검색...`,onSearchChange:C,isSearchLoading:ue=!1,containerProps:de,containerRef:fe,className:pe=``,panelClassName:me=``,formatTrigger:he=ne,formatCollapsed:ge=re,disableAutoCollapse:w=!1,showSelectAll:_e=!1,id:ve,name:T,"data-testid":ye},E){let[D,be]=(0,s.useState)(!1),[O,k]=(0,s.useState)(null),[A,j]=(0,s.useState)(``),[xe,M]=(0,s.useState)(!1),N=(0,s.useRef)([]),P=(0,s.useRef)(null),F=(0,s.useRef)(null),I=(0,s.useRef)(null),L=(0,s.useRef)(null),R=(0,s.useId)(),Se=(0,s.useId)(),z=ve??Se,B=e=>`${R}-opt-${e}`,Ce=O===null?void 0:B(O),V=typeof C==`function`,H=(0,s.useRef)(C);H.current=C;let U=(0,s.useMemo)(()=>{if(!S||V||A.length===0)return u;let e=A.toLowerCase();return u.filter(t=>t.label.toLowerCase().includes(e))},[u,S,V,A]),W=(0,s.useMemo)(()=>new Set(d),[d]),G=(0,s.useMemo)(()=>u.filter(e=>W.has(String(e.value))),[u,W]),{refs:K,floatingStyles:we,context:q}=(0,l.useFloating)({open:D,onOpenChange:be,placement:`bottom-start`,whileElementsMounted:l.autoUpdate,middleware:[(0,l.offset)(4),(0,l.flip)({padding:8}),(0,l.shift)({padding:8}),(0,l.size)({apply({rects:e,elements:t,availableHeight:n,availableWidth:r}){Object.assign(t.floating.style,{minWidth:`${e.reference.width}px`,maxWidth:`${te.computeSelectPanelMaxWidth(e.reference.width,r)}px`,maxHeight:`${Math.min(n,320)}px`})},padding:8})]}),{getReferenceProps:Te,getFloatingProps:Ee,getItemProps:De}=(0,l.useInteractions)([(0,l.useClick)(q,{enabled:!v}),(0,l.useDismiss)(q),(0,l.useRole)(q,{role:`listbox`}),(0,l.useListNavigation)(q,{listRef:N,activeIndex:O,onNavigate:k,virtual:S,loop:!0})]),Oe=(0,s.useRef)(!1);(0,s.useEffect)(()=>{D?Oe.current=!0:(j(``),k(null),Oe.current&&H.current?.(``))},[D]),(0,s.useEffect)(()=>{D&&S&&P.current&&P.current.focus()},[D,S]),(0,s.useLayoutEffect)(()=>{if(w){M(!1);return}let e=I.current,t=L.current;if(!e||!t)return;let n=()=>{let n=t.scrollWidth,r=e.clientWidth;M(n>r-1)};n();let r=new ResizeObserver(()=>{requestAnimationFrame(n)});return r.observe(e),()=>r.disconnect()},[w,d.join(`,`)]);let J=e=>{let t=new Set(W);t.has(e)?t.delete(e):t.add(e),f(u.filter(e=>t.has(String(e.value))).map(e=>String(e.value)))},ke=e=>{e.stopPropagation(),f([])},Y=U.filter(e=>!e.disabled).map(e=>String(e.value)),Ae=Y.length>0&&Y.every(e=>W.has(e)),je=()=>{if(Ae){let e=new Set(Y);f(d.filter(t=>!e.has(t)))}else{let e=new Set([...d,...Y]);f(u.filter(t=>e.has(String(t.value))).map(e=>String(e.value)))}},Me=e=>{!b||v||d.length===0||D||(e.key===`Backspace`||e.key===`Delete`)&&(e.preventDefault(),f([]))},Ne=e=>{let t=e.target.value;t!==A&&(F.current&&(F.current.scrollTop=0),k(null)),j(t),H.current?.(t)},Pe=e=>{if(!e.nativeEvent.isComposing&&e.key===`Enter`&&O!==null){e.preventDefault();let t=U[O];t&&!t.disabled&&J(String(t.value))}},X=G.length>0,Fe=h===`sustain`||h===`appear`&&X,Ie=X?he(G):``,Le=X?ge(G):``,Re=X?xe?Le:Ie:se,ze=a.SLOT_GAP_CLASS[p],Z=a.SLOT_CHILD_ICON_CLASS[p],Be=a.SLOT_BADGE_TEXT_CLASS[p],Ve=a.SLOT_ICON_SIZE_CLASS[p],He=a.CHEVRON_SIZE_CLASS[p],Ue=o.getInputVariantClasses(ie,_,v,p),Q=o.getInputTrailingIconColor(_,v,X||D),$=a.CONTROL_TEXT_CLASS[p],We=v?`text-fg-disabled`:_?`text-fg-danger`:X?`text-fg-default`:`text-fg-subtle`;return(0,c.jsxs)(`div`,{ref:fe,className:e.cn(o.getInputContainerClasses(),`min-w-0`),...de,children:[!w&&X&&(0,c.jsx)(`span`,{ref:L,"aria-hidden":!0,className:e.cn(`pointer-events-none fixed left-0 -top-[9999px] whitespace-nowrap`,$),children:Ie}),Fe&&m&&(0,c.jsx)(`label`,{className:o.getInputLabelClasses(ie,_),htmlFor:z,children:m}),(0,c.jsxs)(`button`,{ref:e=>{K.setReference(e),typeof E==`function`?E(e):E&&(E.current=e)},id:z,type:`button`,disabled:v,"aria-haspopup":`listbox`,"aria-expanded":D,"aria-controls":D?R:void 0,"aria-activedescendant":Ce,"data-testid":ye,...Te({onKeyDown:Me}),"aria-label":ae,"aria-labelledby":oe,className:e.cn(Ue,`flex w-full min-w-0 items-center`,ze,v?`cursor-not-allowed`:`cursor-pointer`,pe),children:[(0,c.jsx)(`span`,{ref:I,className:e.cn(`min-w-0 flex-1 truncate text-left`,$,We),children:Re}),y&&(0,c.jsx)(`span`,{className:e.cn(`shrink-0 whitespace-nowrap`,$,Q),children:y}),ce&&(0,c.jsx)(`span`,{className:e.cn(`flex shrink-0 items-center`,Q,Z),children:ce}),b&&!v&&X&&(0,c.jsx)(`span`,{role:`button`,tabIndex:-1,onClick:ke,"aria-label":`선택 모두 지우기`,className:e.cn(`flex shrink-0 cursor-pointer items-center`,Q,`hover:text-fg-default`),children:(0,c.jsx)(r.CircleX,{className:Ve,strokeWidth:1.5,"aria-hidden":!0})}),x&&(0,c.jsx)(`span`,{className:e.cn(`flex shrink-0 items-center`,Z,Be),children:x}),(0,c.jsx)(n.ChevronDown,{className:e.cn(`shrink-0 transition-transform`,He,Q,D&&`rotate-180`),strokeWidth:1.5,"aria-hidden":!0})]}),T&&(0,c.jsx)(`input`,{type:`hidden`,name:T,value:d.join(`,`)}),D&&(0,c.jsx)(l.FloatingPortal,{children:(0,c.jsx)(l.FloatingFocusManager,{context:q,modal:!1,initialFocus:S?-1:0,children:(0,c.jsxs)(`div`,{ref:K.setFloating,id:R,style:we,...Ee(),className:e.cn(`z-floating overflow-hidden rounded-surface border border-border-subtle bg-bg-surface text-fg-default shadow-overlay`,me),children:[S&&(0,c.jsxs)(`div`,{className:`flex items-center gap-2 border-b border-border-subtle px-3 py-2`,children:[(0,c.jsx)(i.Search,{className:`h-4 w-4 shrink-0 text-fg-subtle`,"aria-hidden":!0}),(0,c.jsx)(`input`,{ref:P,type:`text`,value:A,onChange:Ne,onKeyDown:Pe,placeholder:le,className:`flex-1 bg-transparent text-sm outline-hidden placeholder:text-fg-subtle`}),ue&&(0,c.jsx)(ee.LoadingDots,{className:`h-4 w-4 shrink-0 text-fg-subtle`})]}),_e&&U.length>0&&(0,c.jsxs)(`button`,{type:`button`,onClick:je,className:`flex w-full items-center justify-between border-b border-border-subtle px-3 py-2 text-xs text-fg-muted transition-colors hover:bg-bg-subtle`,children:[(0,c.jsx)(`span`,{children:Ae?`전체 해제`:`전체 선택`}),(0,c.jsxs)(`span`,{className:`text-fg-subtle`,children:[Y.length,`개`]})]}),(0,c.jsx)(`div`,{ref:F,className:`max-h-72 overflow-y-auto py-1`,children:U.length===0?(0,c.jsx)(`div`,{className:`px-3 py-4 text-center text-sm text-fg-subtle`,children:ue?`검색 중...`:`옵션이 없어요`}):U.map((n,r)=>{let i=String(n.value),a=W.has(i),o=O===r;return(0,c.jsxs)(`div`,{id:B(r),ref:e=>{N.current[r]=e},role:`option`,"aria-selected":a,"aria-disabled":n.disabled||void 0,tabIndex:o?0:-1,...De({onClick:()=>{n.disabled||J(i)},onKeyDown:e=>{n.disabled||(e.key===`Enter`||e.key===` `)&&(e.preventDefault(),J(i))}}),className:e.cn(`flex cursor-pointer items-start gap-3 px-3 py-2 text-sm transition-colors`,n.disabled?`cursor-not-allowed text-fg-disabled`:o?`bg-bg-subtle text-fg-default`:`text-fg-default hover:bg-bg-subtle`),children:[(0,c.jsx)(`span`,{className:e.cn(`mt-0.5 flex h-4 w-4 shrink-0 items-center justify-center rounded-checkbox border`,a?`border-primary bg-primary text-fg-inverse`:`border-border-subtle`),"aria-hidden":!0,children:a&&(0,c.jsx)(t.Check,{className:`h-3 w-3`,strokeWidth:3})}),(0,c.jsxs)(`div`,{className:`min-w-0 flex-1`,children:[(0,c.jsx)(`div`,{className:e.cn(`truncate`,a&&`font-medium`),children:n.label}),n.description&&(0,c.jsx)(`div`,{className:`mt-0.5 truncate text-xs text-fg-subtle`,children:n.description})]}),n.trailing&&(0,c.jsx)(`span`,{className:`shrink-0 text-xs text-fg-subtle`,children:n.trailing})]},i)})})]})})}),g&&(0,c.jsx)(`div`,{className:o.getInputHelpClasses(_),children:g})]})});exports.MultiSelect=u;

package/dist/{src/components → components}/select/MultiSelect.d.ts

@@ -1,4 +1,4 @@
-import { SelectCommonProps, SelectOption } from './types';
+import { SelectCommonProps, SelectOption } from './types.js';
 /**
  * MultiSelect의 search 관련 props discriminated union.
  * `searchable=true`일 때만 검색 prop이 의미가 있다 — Select와 동일 패턴.
@@ -12,7 +12,11 @@ type MultiSelectSearchProps = {
     searchable: true;
     /** 패널 검색 input placeholder. */
     searchPlaceholder?: string;
-    /** 외부 검색(서버) 콜백. 제공 시 클라이언트 필터를 끄고 입력만 외부에 전달. */
+    /**
+     * 외부 검색(서버) 콜백. 제공 시 클라이언트 필터를 끄고 입력만 외부에 전달.
+     * 마운트 시점에는 호출되지 않으며, 한 번 열렸다 닫힐 때 빈 문자열로 호출된다.
+     * 초기 옵션은 소비자가 직접 불러온다.
+     */
     onSearchChange?: (query: string) => void;
     /** 외부 검색 로딩 상태. 패널 검색 input 옆 LoadingDots. */
     isSearchLoading?: boolean;
@@ -26,7 +30,11 @@ type MultiSelectBaseProps = Omit<SelectCommonProps, "searchable" | "searchPlaceh
     onChange: (values: string[]) => void;
     /** 트리거 추가 className. */
     className?: string;
-    /** 드롭다운 패널 추가 className. */
+    /**
+     * 드롭다운 패널 추가 className. 긴 라벨이 패널을 뷰포트 밖으로 밀어내지 않도록 인라인 maxWidth가
+     * 패널 폭을 `max(트리거 폭, min(가용 폭, 420px))`로 제한하므로 `max-w-*`/`min-w-*`로
+     * 이 범위를 넘길 수 없다. 범위 안에서는 `w-*`로 지정하고, 더 큰 폭이 필요하면 트리거 폭을 조정한다.
+     */
     panelClassName?: string;
     /**
      * 트리거에 보여줄 풀 텍스트 포맷터. 기본은 라벨을 콤마로 연결.