@thewrong/ui 0.2.0 → 0.3.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:p,selectSize:m=`medium`,label:h,labelOption:g=`appear`,help:_,placeholder:ie=`선택해주세요`,hasError:v=!1,disabled:y=!1,suffix:ae,trailingIcon:oe,clearable:b=!1,badge:x,searchable:S=!1,searchPlaceholder:se=`검색...`,onSearchChange:C,isSearchLoading:w=!1,containerProps:ce,containerRef:le,className:ue=``,panelClassName:de=``,formatTrigger:fe=ne,formatCollapsed:pe=re,disableAutoCollapse:T=!1,showSelectAll:me=!1,id:he,name:E,"data-testid":ge},D){let[O,_e]=(0,s.useState)(!1),[k,A]=(0,s.useState)(null),[j,M]=(0,s.useState)(``),[ve,N]=(0,s.useState)(!1),P=(0,s.useRef)([]),F=(0,s.useRef)(null),I=(0,s.useRef)(null),L=(0,s.useRef)(null),R=(0,s.useRef)(null),z=(0,s.useId)(),ye=(0,s.useId)(),B=he??ye,V=e=>`${z}-opt-${e}`,be=k===null?void 0:V(k),H=typeof C==`function`,U=(0,s.useRef)(C);U.current=C;let W=(0,s.useMemo)(()=>{if(!S||H||j.length===0)return u;let e=j.toLowerCase();return u.filter(t=>t.label.toLowerCase().includes(e))},[u,S,H,j]),G=(0,s.useMemo)(()=>new Set(d),[d]),K=(0,s.useMemo)(()=>u.filter(e=>G.has(String(e.value))),[u,G]),{refs:q,floatingStyles:xe,context:J}=(0,l.useFloating)({open:O,onOpenChange:_e,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:Se,getFloatingProps:Ce,getItemProps:we}=(0,l.useInteractions)([(0,l.useClick)(J,{enabled:!y}),(0,l.useDismiss)(J),(0,l.useRole)(J,{role:`listbox`}),(0,l.useListNavigation)(J,{listRef:P,activeIndex:k,onNavigate:A,virtual:S,loop:!0})]),Te=(0,s.useRef)(!1);(0,s.useEffect)(()=>{O?Te.current=!0:(M(``),A(null),Te.current&&U.current?.(``))},[O]),(0,s.useEffect)(()=>{O&&S&&F.current&&F.current.focus()},[O,S]),(0,s.useLayoutEffect)(()=>{if(T){N(!1);return}let e=L.current,t=R.current;if(!e||!t)return;let n=()=>{let n=t.scrollWidth,r=e.clientWidth;N(n>r-1)};n();let r=new ResizeObserver(()=>{requestAnimationFrame(n)});return r.observe(e),()=>r.disconnect()},[T,d.join(`,`)]);let Y=e=>{let t=new Set(G);t.has(e)?t.delete(e):t.add(e),f(u.filter(e=>t.has(String(e.value))).map(e=>String(e.value)))},Ee=e=>{e.stopPropagation(),f([])},X=W.filter(e=>!e.disabled).map(e=>String(e.value)),De=X.length>0&&X.every(e=>G.has(e)),Oe=()=>{if(De){let e=new Set(X);f(d.filter(t=>!e.has(t)))}else{let e=new Set([...d,...X]);f(u.filter(t=>e.has(String(t.value))).map(e=>String(e.value)))}},ke=e=>{!b||y||d.length===0||O||(e.key===`Backspace`||e.key===`Delete`)&&(e.preventDefault(),f([]))},Ae=e=>{let t=e.target.value;t!==j&&(I.current&&(I.current.scrollTop=0),A(null)),M(t),U.current?.(t)},je=e=>{if(!e.nativeEvent.isComposing&&e.key===`Enter`&&k!==null){e.preventDefault();let t=W[k];t&&!t.disabled&&Y(String(t.value))}},Z=K.length>0,Me=g===`sustain`||g===`appear`&&Z,Ne=Z?fe(K):``,Pe=Z?pe(K):``,Fe=Z?ve?Pe:Ne:ie,Ie=a.SLOT_GAP_CLASS[m],Le=a.SLOT_CHILD_ICON_CLASS[m],Re=a.SLOT_BADGE_TEXT_CLASS[m],ze=a.SLOT_ICON_SIZE_CLASS[m],Be=a.CHEVRON_SIZE_CLASS[m],Ve=o.getInputVariantClasses(p,v,y,m),Q=o.getInputTrailingIconColor(v,y,Z||O),$=a.CONTROL_TEXT_CLASS[m],He=y?`text-fg-disabled`:v?`text-fg-danger`:Z?`text-fg-default`:`text-fg-subtle`;return(0,c.jsxs)(`div`,{ref:le,className:e.cn(o.getInputContainerClasses(),`min-w-0`),...ce,children:[!T&&Z&&(0,c.jsx)(`span`,{ref:R,"aria-hidden":!0,className:e.cn(`pointer-events-none fixed left-0 -top-[9999px] whitespace-nowrap`,$),children:Ne}),Me&&h&&(0,c.jsx)(`label`,{className:o.getInputLabelClasses(p,v),htmlFor:B,children:h}),(0,c.jsxs)(`button`,{ref:e=>{q.setReference(e),typeof D==`function`?D(e):D&&(D.current=e)},id:B,type:`button`,disabled:y,"aria-haspopup":`listbox`,"aria-expanded":O,"aria-controls":O?z:void 0,"aria-activedescendant":be,"data-testid":ge,...Se({onKeyDown:ke}),className:e.cn(Ve,`flex w-full min-w-0 items-center`,Ie,y?`cursor-not-allowed`:`cursor-pointer`,ue),children:[(0,c.jsx)(`span`,{ref:L,className:e.cn(`min-w-0 flex-1 truncate text-left`,$,He),children:Fe}),ae&&(0,c.jsx)(`span`,{className:e.cn(`shrink-0 whitespace-nowrap`,$,Q),children:ae}),oe&&(0,c.jsx)(`span`,{className:e.cn(`flex shrink-0 items-center`,Q,Le),children:oe}),b&&!y&&Z&&(0,c.jsx)(`span`,{role:`button`,tabIndex:-1,onClick:Ee,"aria-label":`선택 모두 지우기`,className:e.cn(`flex shrink-0 cursor-pointer items-center`,Q,`hover:text-fg-default`),children:(0,c.jsx)(r.CircleX,{className:ze,strokeWidth:1.5,"aria-hidden":!0})}),x&&(0,c.jsx)(`span`,{className:e.cn(`flex shrink-0 items-center`,Le,Re),children:x}),(0,c.jsx)(n.ChevronDown,{className:e.cn(`shrink-0 transition-transform`,Be,Q,O&&`rotate-180`),strokeWidth:1.5,"aria-hidden":!0})]}),E&&(0,c.jsx)(`input`,{type:`hidden`,name:E,value:d.join(`,`)}),O&&(0,c.jsx)(l.FloatingPortal,{children:(0,c.jsx)(l.FloatingFocusManager,{context:J,modal:!1,initialFocus:S?-1:0,children:(0,c.jsxs)(`div`,{ref:q.setFloating,id:z,style:xe,...Ce(),className:e.cn(`z-floating overflow-hidden rounded-surface border border-border-subtle bg-bg-surface text-fg-default shadow-overlay`,de),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:F,type:`text`,value:j,onChange:Ae,onKeyDown:je,placeholder:se,className:`flex-1 bg-transparent text-sm outline-hidden placeholder:text-fg-subtle`}),w&&(0,c.jsx)(ee.LoadingDots,{className:`h-4 w-4 shrink-0 text-fg-subtle`})]}),me&&W.length>0&&(0,c.jsxs)(`button`,{type:`button`,onClick:Oe,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:De?`전체 해제`:`전체 선택`}),(0,c.jsxs)(`span`,{className:`text-fg-subtle`,children:[X.length,`개`]})]}),(0,c.jsx)(`div`,{ref:I,className:`max-h-72 overflow-y-auto py-1`,children:W.length===0?(0,c.jsx)(`div`,{className:`px-3 py-4 text-center text-sm text-fg-subtle`,children:w?`검색 중...`:`옵션이 없어요`}):W.map((n,r)=>{let i=String(n.value),a=G.has(i),o=k===r;return(0,c.jsxs)(`div`,{id:V(r),ref:e=>{P.current[r]=e},role:`option`,"aria-selected":a,"aria-disabled":n.disabled||void 0,tabIndex:o?0:-1,...we({onClick:()=>{n.disabled||Y(i)},onKeyDown:e=>{n.disabled||(e.key===`Enter`||e.key===` `)&&(e.preventDefault(),Y(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)})})]})})}),_&&(0,c.jsx)(`div`,{className:o.getInputHelpClasses(v),children:_})]})});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;
     /**
      * 트리거에 보여줄 풀 텍스트 포맷터. 기본은 라벨을 콤마로 연결.