@tide-tds/components 0.3.1 → 0.4.0

package/dist/Tooltip.js

@@ -0,0 +1,129 @@
+"use client";
+
+import { cn } from "./cn.js";
+import { OverlayPortal, overlayPositionProps, useOverlayPresence, useOverlayTheme } from "./overlay.js";
+import { frequentMotionClass, overlaySurfaceClass } from "./overlay-style.js";
+import { renderElement } from "./render.js";
+import { jsx } from "react/jsx-runtime";
+import { createContext, createElement, use, useMemo, useRef } from "react";
+import { mergeProps, mergeRefs, useOverlayPosition, useTooltip, useTooltipTrigger } from "react-aria";
+import { useTooltipTriggerState } from "react-stately";
+
+// src/Tooltip.tsx
+const TooltipContext = createContext(null);
+function useTooltipContext(part) {
+	const context = use(TooltipContext);
+	if (!context) throw new Error(`${part}는 Tooltip 안에 둔다.`);
+	return context;
+}
+/**
+* 트리거와 설명을 잇는 열림 상태. DOM 요소를 만들지 않는다.
+* 안에 `TooltipTrigger` 하나와 `TooltipContent` 하나를 둔다.
+*/
+function Tooltip({ open, defaultOpen, onOpenChange, delay = 500, closeDelay = 300, disabled, children }) {
+	const options = {
+		isOpen: open,
+		defaultOpen,
+		onOpenChange,
+		delay,
+		closeDelay,
+		isDisabled: disabled
+	};
+	const state = useTooltipTriggerState(options);
+	const triggerRef = useRef(null);
+	const { triggerProps, tooltipProps } = useTooltipTrigger(options, state, triggerRef);
+	const value = useMemo(() => ({
+		state,
+		triggerRef,
+		triggerProps,
+		tooltipId: tooltipProps.id
+	}), [
+		state,
+		triggerProps,
+		tooltipProps.id
+	]);
+	return /* @__PURE__ */ jsx(TooltipContext, {
+		value,
+		children
+	});
+}
+/**
+* Tooltip을 여는 요소. 마우스를 올리면 `delay` 뒤에, 키보드로 포커스하면 바로 열린다.
+* 누르면(마우스, 터치, 키) 닫힌다. 열린 동안 `aria-describedby`에 설명 id가 더해진다.
+*/
+function TooltipTrigger({ render, ref, className, "aria-describedby": describedBy, ...props }) {
+	const { triggerRef, triggerProps } = useTooltipContext("TooltipTrigger");
+	const { tabIndex: _tabIndex, "aria-describedby": tooltipDescribedBy, ...ariaProps } = triggerProps;
+	const mergedRef = useMemo(() => mergeRefs(ref, triggerRef), [ref, triggerRef]);
+	const merged = {
+		...mergeProps(props, ariaProps),
+		"aria-describedby": [describedBy, tooltipDescribedBy].filter(Boolean).join(" ") || void 0,
+		ref: mergedRef
+	};
+	if (!render) return createElement("button", {
+		type: "button",
+		...merged,
+		className
+	});
+	return renderElement({
+		defaultElement: "button",
+		render,
+		baseClassName: "",
+		props: {
+			...merged,
+			className
+		}
+	});
+}
+const contentClass = `isolate z-tooltip max-w-60 px-2 py-1 text-body-sm ${overlaySurfaceClass} ${frequentMotionClass}`;
+/**
+* 트리거에 붙는 설명(`role="tooltip"`). 열릴 때만 `document.body`에 portal로 렌더하고 `z-tooltip`으로 쌓는다.
+* 바로 나타나고, 닫히면 opacity만 `fast`(150ms)로 사라진다. 조작 요소(버튼, 링크)는 넣지 않는다.
+* 열려 있으면 `data-open`이, 트리거 기준 방향이 `data-placement`(`top`/`bottom`/`left`/`right`)로 붙는다.
+*/
+function TooltipContent(props) {
+	const context = useTooltipContext("TooltipContent");
+	const tooltipRef = useRef(null);
+	if (!useOverlayPresence(context.state.isOpen, tooltipRef)) return null;
+	return /* @__PURE__ */ jsx(OverlayPortal, {
+		isExiting: !context.state.isOpen,
+		focusManagement: false,
+		children: /* @__PURE__ */ jsx(TooltipContentInner, {
+			...props,
+			context,
+			tooltipRef
+		})
+	});
+}
+/** DOM에 있는 동안만 portal 안에서 렌더한다. 위치 hook은 요소가 있다고 보고 동작한다. */
+function TooltipContentInner({ context, tooltipRef, placement = "top", offset = 4, ref, className, children, ...props }) {
+	const { state, triggerRef, tooltipId } = context;
+	useOverlayTheme(triggerRef, tooltipRef);
+	const position = useOverlayPosition({
+		targetRef: triggerRef,
+		overlayRef: tooltipRef,
+		placement,
+		offset,
+		isOpen: state.isOpen,
+		onClose: () => state.close(true)
+	});
+	const overlayProps = overlayPositionProps(position.overlayProps, position.placement, placement);
+	const { tooltipProps } = useTooltip({}, state);
+	const mergedRef = useMemo(() => mergeRefs(ref, tooltipRef), [ref, tooltipRef]);
+	const { style: _style, ...rest } = mergeProps(props, overlayProps, tooltipProps);
+	return /* @__PURE__ */ jsx("div", {
+		...rest,
+		id: tooltipId,
+		ref: mergedRef,
+		"data-open": state.isOpen ? "" : void 0,
+		"data-react-aria-top-layer": "",
+		className: cn(contentClass, !state.isOpen && state.shouldSkipAnimation && "transition-none", className),
+		style: {
+			...overlayProps.style,
+			...props.style
+		},
+		children
+	});
+}
+
+export { Tooltip, TooltipContent, TooltipTrigger };

package/dist/index.d.ts

@@ -23,6 +23,15 @@ import { Progress, ProgressProps } from "./Progress.js";
 import { Table, TableBody, TableBodyProps, TableCell, TableCellProps, TableHead, TableHeadProps, TableHeaderCell, TableHeaderCellProps, TableProps, TableRow, TableRowProps } from "./Table.js";
 import { Breadcrumb, BreadcrumbCurrent, BreadcrumbCurrentProps, BreadcrumbItem, BreadcrumbItemProps, BreadcrumbLink, BreadcrumbLinkProps, BreadcrumbProps } from "./Breadcrumb.js";
 import { Pagination, PaginationEllipsis, PaginationEllipsisProps, PaginationItem, PaginationItemProps, PaginationLink, PaginationLinkProps, PaginationNext, PaginationNextProps, PaginationPrevious, PaginationPreviousProps, PaginationProps } from "./Pagination.js";
+import { Menu, MenuContent, MenuContentProps, MenuItem, MenuItemProps, MenuPlacement, MenuProps, MenuSection, MenuSectionProps, MenuTrigger, MenuTriggerProps } from "./Menu.js";
 import { Popover, PopoverContent, PopoverContentProps, PopoverPlacement, PopoverProps, PopoverTrigger, PopoverTriggerProps } from "./Popover.js";
+import { Combobox, ComboboxItem, ComboboxItemProps, ComboboxProps, ComboboxSection, ComboboxSectionProps } from "./Combobox.js";
+import { Select, SelectItem, SelectItemProps, SelectProps, SelectSection, SelectSectionProps } from "./Select.js";
+import { AlertDialog, AlertDialogProps } from "./AlertDialog.js";
+import { Dialog, DialogClose, DialogCloseProps, DialogContent, DialogContentProps, DialogDescription, DialogDescriptionProps, DialogFooter, DialogFooterProps, DialogProps, DialogSize, DialogTitle, DialogTitleProps, DialogTrigger, DialogTriggerProps } from "./Dialog.js";
+import { Accordion, AccordionHeadingLevel, AccordionItem, AccordionItemProps, AccordionPanel, AccordionPanelProps, AccordionProps, AccordionTrigger, AccordionTriggerProps } from "./Accordion.js";
+import { Tab, TabList, TabListProps, TabPanel, TabPanelProps, TabProps, Tabs, TabsActivationMode, TabsOrientation, TabsProps } from "./Tabs.js";
+import { Tag, TagGroup, TagGroupProps, TagProps } from "./Tag.js";
+import { Tooltip, TooltipContent, TooltipContentProps, TooltipPlacement, TooltipProps, TooltipTrigger, TooltipTriggerProps } from "./Tooltip.js";
 import { Color, ColorFamilyName, ColorFamilyRegistry, FillVariant, Role, RoleRegistry, Size } from "./types.js";
-export { Alert, type AlertProps, Avatar, type AvatarProps, Badge, type BadgeProps, Breadcrumb, BreadcrumbCurrent, type BreadcrumbCurrentProps, BreadcrumbItem, type BreadcrumbItemProps, BreadcrumbLink, type BreadcrumbLinkProps, type BreadcrumbProps, Button, type ButtonProps, Card, type CardProps, Checkbox, CheckboxGroup, type CheckboxGroupProps, type CheckboxProps, type ChoiceOrientation, type Color, type ColorFamilyName, type ColorFamilyRegistry, Field, type FieldProps, type FillVariant, IconButton, type IconButtonProps, Input, type InputProps, Link, type LinkProps, Pagination, PaginationEllipsis, type PaginationEllipsisProps, PaginationItem, type PaginationItemProps, PaginationLink, type PaginationLinkProps, PaginationNext, type PaginationNextProps, PaginationPrevious, type PaginationPreviousProps, type PaginationProps, Popover, PopoverContent, type PopoverContentProps, type PopoverPlacement, type PopoverProps, PopoverTrigger, type PopoverTriggerProps, Progress, type ProgressProps, Radio, RadioGroup, type RadioGroupProps, type RadioProps, type Role, type RoleRegistry, Separator, type SeparatorProps, type Size, Skeleton, type SkeletonProps, Spinner, type SpinnerProps, Switch, type SwitchProps, Table, TableBody, type TableBodyProps, TableCell, type TableCellProps, TableHead, type TableHeadProps, TableHeaderCell, type TableHeaderCellProps, type TableProps, TableRow, type TableRowProps, Textarea, type TextareaProps, Typography, type TypographyProps, VisuallyHidden, type VisuallyHiddenProps, cn };
+export { Accordion, type AccordionHeadingLevel, AccordionItem, type AccordionItemProps, AccordionPanel, type AccordionPanelProps, type AccordionProps, AccordionTrigger, type AccordionTriggerProps, Alert, AlertDialog, type AlertDialogProps, type AlertProps, Avatar, type AvatarProps, Badge, type BadgeProps, Breadcrumb, BreadcrumbCurrent, type BreadcrumbCurrentProps, BreadcrumbItem, type BreadcrumbItemProps, BreadcrumbLink, type BreadcrumbLinkProps, type BreadcrumbProps, Button, type ButtonProps, Card, type CardProps, Checkbox, CheckboxGroup, type CheckboxGroupProps, type CheckboxProps, type ChoiceOrientation, type Color, type ColorFamilyName, type ColorFamilyRegistry, Combobox, ComboboxItem, type ComboboxItemProps, type ComboboxProps, ComboboxSection, type ComboboxSectionProps, Dialog, DialogClose, type DialogCloseProps, DialogContent, type DialogContentProps, DialogDescription, type DialogDescriptionProps, DialogFooter, type DialogFooterProps, type DialogProps, type DialogSize, DialogTitle, type DialogTitleProps, DialogTrigger, type DialogTriggerProps, Field, type FieldProps, type FillVariant, IconButton, type IconButtonProps, Input, type InputProps, Link, type LinkProps, Menu, MenuContent, type MenuContentProps, MenuItem, type MenuItemProps, type MenuPlacement, type MenuProps, MenuSection, type MenuSectionProps, MenuTrigger, type MenuTriggerProps, Pagination, PaginationEllipsis, type PaginationEllipsisProps, PaginationItem, type PaginationItemProps, PaginationLink, type PaginationLinkProps, PaginationNext, type PaginationNextProps, PaginationPrevious, type PaginationPreviousProps, type PaginationProps, Popover, PopoverContent, type PopoverContentProps, type PopoverPlacement, type PopoverProps, PopoverTrigger, type PopoverTriggerProps, Progress, type ProgressProps, Radio, RadioGroup, type RadioGroupProps, type RadioProps, type Role, type RoleRegistry, Select, SelectItem, type SelectItemProps, type SelectProps, SelectSection, type SelectSectionProps, Separator, type SeparatorProps, type Size, Skeleton, type SkeletonProps, Spinner, type SpinnerProps, Switch, type SwitchProps, Tab, TabList, type TabListProps, TabPanel, type TabPanelProps, type TabProps, Table, TableBody, type TableBodyProps, TableCell, type TableCellProps, TableHead, type TableHeadProps, TableHeaderCell, type TableHeaderCellProps, type TableProps, TableRow, type TableRowProps, Tabs, type TabsActivationMode, type TabsOrientation, type TabsProps, Tag, TagGroup, type TagGroupProps, type TagProps, Textarea, type TextareaProps, Tooltip, TooltipContent, type TooltipContentProps, type TooltipPlacement, type TooltipProps, TooltipTrigger, type TooltipTriggerProps, Typography, type TypographyProps, VisuallyHidden, type VisuallyHiddenProps, cn };

package/dist/index.js

@@ -23,6 +23,15 @@ import { Progress } from "./Progress.js";
 import { Table, TableBody, TableCell, TableHead, TableHeaderCell, TableRow } from "./Table.js";
 import { Breadcrumb, BreadcrumbCurrent, BreadcrumbItem, BreadcrumbLink } from "./Breadcrumb.js";
 import { Pagination, PaginationEllipsis, PaginationItem, PaginationLink, PaginationNext, PaginationPrevious } from "./Pagination.js";
+import { Menu, MenuContent, MenuItem, MenuSection, MenuTrigger } from "./Menu.js";
 import { Popover, PopoverContent, PopoverTrigger } from "./Popover.js";
+import { Combobox, ComboboxItem, ComboboxSection } from "./Combobox.js";
+import { Select, SelectItem, SelectSection } from "./Select.js";
+import { AlertDialog } from "./AlertDialog.js";
+import { Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogTitle, DialogTrigger } from "./Dialog.js";
+import { Accordion, AccordionItem, AccordionPanel, AccordionTrigger } from "./Accordion.js";
+import { Tab, TabList, TabPanel, Tabs } from "./Tabs.js";
+import { Tag, TagGroup } from "./Tag.js";
+import { Tooltip, TooltipContent, TooltipTrigger } from "./Tooltip.js";
 
-export { Alert, Avatar, Badge, Breadcrumb, BreadcrumbCurrent, BreadcrumbItem, BreadcrumbLink, Button, Card, Checkbox, CheckboxGroup, Field, IconButton, Input, Link, Pagination, PaginationEllipsis, PaginationItem, PaginationLink, PaginationNext, PaginationPrevious, Popover, PopoverContent, PopoverTrigger, Progress, Radio, RadioGroup, Separator, Skeleton, Spinner, Switch, Table, TableBody, TableCell, TableHead, TableHeaderCell, TableRow, Textarea, Typography, VisuallyHidden, cn };
+export { Accordion, AccordionItem, AccordionPanel, AccordionTrigger, Alert, AlertDialog, Avatar, Badge, Breadcrumb, BreadcrumbCurrent, BreadcrumbItem, BreadcrumbLink, Button, Card, Checkbox, CheckboxGroup, Combobox, ComboboxItem, ComboboxSection, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogTitle, DialogTrigger, Field, IconButton, Input, Link, Menu, MenuContent, MenuItem, MenuSection, MenuTrigger, Pagination, PaginationEllipsis, PaginationItem, PaginationLink, PaginationNext, PaginationPrevious, Popover, PopoverContent, PopoverTrigger, Progress, Radio, RadioGroup, Select, SelectItem, SelectSection, Separator, Skeleton, Spinner, Switch, Tab, TabList, TabPanel, Table, TableBody, TableCell, TableHead, TableHeaderCell, TableRow, Tabs, Tag, TagGroup, Textarea, Tooltip, TooltipContent, TooltipTrigger, Typography, VisuallyHidden, cn };

package/dist/input-style.d.ts

@@ -0,0 +1,3 @@
+import { Size } from "./types.js";
+/** 입력창의 size. `xs`(24px)는 입력하기에 작아서 받지 않는다. Input·Select 트리거가 같다. */
+export type InputSize = Extract<Size, "sm" | "md" | "lg">;

package/dist/input-style.js

@@ -1,5 +1,11 @@
 // src/input-style.ts
 /** 입력창의 공통 모양. size class 뒤에 넣는다. */
 const inputBaseClass = "w-full min-w-0 rounded-md border border-strong bg-canvas font-normal text-default transition-colors placeholder:text-muted aria-invalid:border-danger focus:focus-field disabled:cursor-not-allowed disabled:border-default disabled:bg-disabled disabled:text-disabled disabled:placeholder:text-disabled";
+/** 높이, 좌우 padding, 텍스트 스타일(spec size 표). radius는 모든 size에서 `md`다. */
+const inputSizeClass = {
+	sm: "h-8 px-2.5 text-label-sm",
+	md: "h-10 px-3 text-label-md",
+	lg: "h-12 px-4 text-label-lg"
+};
 
-export { inputBaseClass };
+export { inputBaseClass, inputSizeClass };

package/dist/list-collection.d.ts

@@ -0,0 +1,23 @@
+import { ReactNode } from "react";
+/** 항목 Component의 공통 props. Tide 이름(`disabled`)을 React Stately 이름(`isDisabled`)으로 바꿔 node에 넣는다. */
+export interface CollectionItemProps {
+  /** `true`면 고르거나 실행할 수 없고 키보드 위치도 건너뛴다. */
+  disabled?: boolean;
+  /** 타입어헤드(글자를 쳐서 항목으로 옮겨 가기)에 쓰는 글자. 없으면 children의 글자를 모은다. */
+  textValue?: string;
+  "aria-label"?: string;
+  children?: ReactNode;
+}
+/** 항목 묶음 Component의 공통 props */
+export interface CollectionSectionProps {
+  /** 묶음 제목. 화면에 보이고 묶음(`group`)의 이름이 된다. */
+  heading?: ReactNode;
+  /** 제목이 없을 때 묶음의 이름 */
+  "aria-label"?: string;
+  children?: ReactNode;
+}
+/** 값을 고르는 옵션 Component(Select·Combobox 옵션)의 공통 props. `value`가 컬렉션 key가 된다. */
+export interface CollectionValueItemProps extends CollectionItemProps {
+  /** 옵션의 값. 고르면 이 값이 목록의 값이 되고 폼에 제출된다. 같은 목록 안에서 겹치지 않아야 한다. */
+  value: string;
+}

package/dist/list-collection.js

@@ -0,0 +1,99 @@
+import { Children, Fragment, createElement, isValidElement } from "react";
+
+// src/list-collection.ts
+const lazyType = Symbol.for("react.lazy");
+const isLazy = (type) => typeof type === "object" && type !== null && type.$$typeof === lazyType;
+/**
+* children 안의 React node에서 글자만 모은다. 항목의 기본 타입어헤드 글자다. 아이콘(글자 없는 요소)은 빠진다.
+*/
+function textOf(node) {
+	if (typeof node === "string" || typeof node === "number") return String(node);
+	if (Array.isArray(node)) return node.map((child) => textOf(child)).join("");
+	if (isValidElement(node)) return textOf(node.props.children);
+	return "";
+}
+/**
+* 목록에 넘길 children을 컬렉션 빌더가 읽을 수 있게 고친다.
+*
+* - 서버 컴포넌트가 만든 요소는 client Component type이 React lazy 참조(RSC payload의 `$L`)로 온다. 컬렉션 빌더는
+*   type의 `getCollectionNode`를 직접 보므로 lazy를 풀어 실제 Component로 바꾼다. 목록 Component와 항목 Component는
+*   같은 모듈이라 목록이 렌더되는 시점에는 이미 불러와져 있다(풀 때 기다리지 않는다).
+* - Fragment는 펼친다. 배열·Fragment 안의 lazy도 같이 푼다.
+* - 묶음 안의 항목은 묶음의 `getCollectionNode`(`sectionCollectionNode`)가 같은 함수로 푼다.
+*/
+function resolveCollectionChildren(children) {
+	const resolved = [];
+	Children.forEach(children, (child) => {
+		if (!isValidElement(child)) {
+			if (child != null && typeof child !== "boolean") resolved.push(child);
+			return;
+		}
+		if (child.type === Fragment) {
+			resolved.push(...resolveCollectionChildren(child.props.children));
+			return;
+		}
+		if (isLazy(child.type)) {
+			const type = child.type._init(child.type._payload);
+			resolved.push(createElement(type, {
+				...child.props,
+				key: child.key
+			}));
+			return;
+		}
+		resolved.push(child);
+	});
+	return resolved;
+}
+/**
+* 항목 Component의 `getCollectionNode`. node의 props에 `isDisabled`를 더한다(React Stately `SelectionManager`·
+* 키보드 이동이 `props.isDisabled`를 읽는다). 렌더는 목록 Component가 node.props(항목에 준 props 그대로)로 한다.
+*/
+function* itemCollectionNode(props) {
+	yield {
+		type: "item",
+		props: {
+			...props,
+			isDisabled: props.disabled ?? false
+		},
+		rendered: props.children,
+		textValue: props.textValue ?? textOf(props.children).trim(),
+		"aria-label": props["aria-label"],
+		hasChildNodes: false
+	};
+}
+/**
+* 옵션 Component의 `getCollectionNode`. `itemCollectionNode`와 같고, `value`를 node의 key로 yield한다.
+* 컬렉션 빌더는 yield한 node에 key가 있으면 요소 key·자리 번호 대신 그 값을 쓴다(react-stately 3.51.0
+* `CollectionBuilder.getFullNode`). 그래서 목록 상태의 선택 key가 곧 앱의 값이고, 묶음 안에 있어도 앞에 묶음 key가
+* 붙지 않는다(묶음은 key 없는 부분 node로 항목을 넘긴다).
+*/
+function* valueItemCollectionNode(props) {
+	for (const node of itemCollectionNode(props)) yield {
+		...node,
+		key: props.value
+	};
+}
+/** 묶음 Component의 `getCollectionNode`. 안의 항목도 `resolveCollectionChildren`으로 고쳐 넘긴다. */
+function* sectionCollectionNode(props) {
+	yield {
+		type: "section",
+		props,
+		rendered: props.heading,
+		"aria-label": props["aria-label"],
+		hasChildNodes: true,
+		*childNodes() {
+			for (const child of resolveCollectionChildren(props.children)) if (isValidElement(child)) yield {
+				type: "item",
+				element: child
+			};
+		}
+	};
+}
+/**
+* 렌더하지 않는 표시 Component에 컬렉션 node 생성 함수를 붙인다. 공개 타입에는 드러나지 않는다.
+*/
+function asCollectionComponent(component, getCollectionNode) {
+	component.getCollectionNode = getCollectionNode;
+}
+
+export { asCollectionComponent, itemCollectionNode, resolveCollectionChildren, sectionCollectionNode, textOf, valueItemCollectionNode };

package/dist/list-style.js

@@ -0,0 +1,45 @@
+import { frequentMotionClass, overlaySurfaceClass } from "./overlay-style.js";
+
+// src/list-style.ts
+/**
+* 목록 오버레이(Menu 목록, Select·Combobox 목록)의 루트. 요소에 `data-open`이 있어야 한다(`frequentMotionClass`).
+*
+* - 표면: raised + `shadow-md` + radius `lg` + `border-raised`(overlaySurfaceClass).
+* - 여백: 3px. 바깥 radius 8px = 항목 radius 4px + 여백 3px + border 1px(spec 중첩 규칙).
+* - 크기: 폭은 내용에 맞추되 10rem(`min-w-40`)~20rem(`max-w-80`). 높이는 React Aria가 `max-height`로 화면 안에
+*   맞추고 넘치면 스크롤한다(`overflow-auto`).
+* - 쌓임: `z-popover`(300)라 Dialog(`z-modal`) 위에 보인다. 루트 `isolate`.
+* - 포커스: 목록 자신이 포커스를 받을 때(마우스로 연 직후)는 표시가 없다. 위치 표시는 항목의 highlight가 맡는다.
+* - motion: 「자주 씀」. 바로 나타나고 사라질 때만 opacity `fast`.
+*/
+const listPopupClass = `isolate z-popover min-w-40 max-w-80 overflow-auto p-[3px] outline-none ${overlaySurfaceClass} ${frequentMotionClass}`;
+/**
+* 목록 안 항목(Menu 항목, Select·Combobox 옵션). 상태는 boolean `data-*`로 받는다.
+*
+* - `data-highlighted`: 키보드 위치(React Aria가 옮긴 포커스 위치)이고, 마우스를 올리면 React Aria가 그 항목으로
+*   위치를 옮기므로 hover도 같은 모양이다. highlight = primary subtle 배경 + primary text 글자 + 투명 outline 2px.
+*   투명 outline은 평소에는 보이지 않고 forced-colors에서 시스템 색으로 그려져 위치가 남는다(그 모드는 배경을 덮는다).
+*   기본 `outline-none`이 outline 모양 변수를 none으로 두므로 `outline-solid`를 함께 쓴다.
+*   항목 안쪽(`-outline-offset-2`)에 그려 이웃 항목·목록 경계와 겹치지 않는다.
+* - `hover`(highlight가 아닐 때): raised 위 항목 규칙의 `subtle-hover`(neutral). 키보드로 옮긴 위치가 따로 있을 때
+*   마우스가 다른 항목 위에 있는 경우다.
+* - `data-selected`(highlight가 아닐 때): 선택 유지 `subtle-active`(neutral). Select·Combobox의 고른 옵션이 쓴다.
+* - `data-disabled`: `text-disabled`, `cursor-not-allowed`. hover 배경이 없다.
+* - 상태끼리 겹칠 때 순서에 기대지 않도록 `not-data-highlighted:`로 서로 뺀다.
+* - transition이 없다. 반복되는 목록 항목은 바로 바뀐다(spec 「motion 적용」).
+* - 크기: 세로 6px·가로 8px 여백, `text-body-md`(16/24)라 높이 36px. 바로 안의 아이콘(svg, 장식용)은 16px이고
+*   아이콘과 글자 사이는 8px다(Button md와 같은 아이콘 크기).
+*/
+const listItemClass = [
+	"flex cursor-pointer items-center gap-2 rounded-sm px-2 py-1.5 text-body-md text-default outline-none select-none [&>svg]:size-4 [&>svg]:shrink-0",
+	"hover:not-data-highlighted:not-data-disabled:bg-neutral-subtle-hover",
+	"data-selected:not-data-highlighted:bg-neutral-subtle-active",
+	"data-highlighted:bg-primary-subtle data-highlighted:text-primary data-highlighted:outline-2 data-highlighted:outline-solid data-highlighted:-outline-offset-2 data-highlighted:outline-transparent",
+	"data-disabled:cursor-not-allowed data-disabled:text-disabled"
+].join(" ");
+/** 항목 묶음의 제목. `text-label-sm`(12px), `text-muted`. 항목과 같은 가로 여백이라 글자 시작이 맞는다. */
+const listHeadingClass = "px-2 pt-1.5 pb-1 text-label-sm text-muted select-none";
+/** 묶음 사이 구분선. 장식용 `border-default` 1px, 위아래 4px. */
+const listSeparatorClass = "my-1 h-0 border-t border-default";
+
+export { listHeadingClass, listItemClass, listPopupClass, listSeparatorClass };

package/dist/listbox.d.ts

@@ -0,0 +1,15 @@
+import { CollectionSectionProps, CollectionValueItemProps } from "./list-collection.js";
+import { ComponentProps, ReactNode } from "react";
+import "react-stately";
+/** 옵션 Component(Select·Combobox 옵션)의 props. 옵션 요소는 `<div role="option">`이다. */
+export interface ListBoxOptionProps extends Omit<ComponentProps<"div">, "role" | "children">, CollectionValueItemProps {
+  /** 옵션 내용. 아이콘(장식용)과 글자를 함께 둘 수 있다. Select 트리거에도 이 내용이 보인다. */
+  children?: ReactNode;
+}
+/** 옵션 묶음 Component의 props */
+export interface ListBoxSectionProps extends CollectionSectionProps {
+  /** 묶음 감싸개(`<div role="presentation">`)에 붙는 class */
+  className?: string;
+  /** 옵션. 바로 아래(또는 Fragment·배열 안)에 둔다. */
+  children?: ReactNode;
+}

package/dist/listbox.js

@@ -0,0 +1,90 @@
+"use client";
+
+import { cn } from "./cn.js";
+import { listHeadingClass, listItemClass, listSeparatorClass } from "./list-style.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useMemo, useRef } from "react";
+import { CheckIcon } from "@tide-tds/icons";
+import { mergeProps, mergeRefs, useListBoxSection, useOption } from "react-aria";
+
+// src/listbox.tsx
+/**
+* 고른 옵션 끝의 체크 아이콘. 장식용이다(선택은 `aria-selected`가 알린다). 배경(subtle-active)이 지워지는 고대비
+* 모드에서도 고른 옵션이 보이게 한다. 글자와의 간격은 항목의 gap(8px)이고 `ms-auto`로 오른쪽 끝에 붙는다.
+*/
+const checkClass = "ms-auto";
+/**
+* 목록 상태의 옵션·묶음을 그린다. 묶음과 이웃한 옵션·묶음 사이에 장식용 구분선을 둔다. 목록의 처음·끝과 이어진
+* 구분선은 그리지 않는다(Menu와 같다). listbox의 자식은 option·group만 될 수 있어(WAI-ARIA, axe
+* aria-required-children) Menu와 달리 구분선은 `separator` 역할 없이 보조기술에서 숨긴다. 묶음 경계는 group이 알린다.
+*/
+function ListBoxNodes({ state }) {
+	const nodes = [...state.collection];
+	return nodes.map((node, index) => {
+		const previous = nodes[index - 1];
+		const separator = previous !== void 0 && (node.type === "section" || previous.type === "section");
+		const element = node.type === "section" ? /* @__PURE__ */ jsx(ListBoxSectionView, {
+			node,
+			state
+		}, node.key) : /* @__PURE__ */ jsx(ListBoxOptionView, {
+			node,
+			state
+		}, node.key);
+		if (!separator) return element;
+		return [/* @__PURE__ */ jsx("div", {
+			role: "presentation",
+			"aria-hidden": "true",
+			className: listSeparatorClass
+		}, `${String(node.key)}-separator`), element];
+	});
+}
+/** 옵션 하나를 그린다. node.props는 앱이 옵션에 준 props(와 컬렉션이 더한 isDisabled)다. */
+function ListBoxOptionView({ node, state }) {
+	const optionRef = useRef(null);
+	const { ref, className, value: _value, disabled: _disabled, textValue: _textValue, isDisabled: _isDisabled, children: _children, id: _id, ...props } = node.props;
+	const { optionProps, isFocused, isSelected, isDisabled } = useOption({
+		key: node.key,
+		"aria-label": props["aria-label"]
+	}, state, optionRef);
+	const mergedRef = useMemo(() => mergeRefs(ref, optionRef), [ref, optionRef]);
+	const merged = mergeProps(props, optionProps);
+	return /* @__PURE__ */ jsxs("div", {
+		...merged,
+		ref: mergedRef,
+		"aria-labelledby": props["aria-labelledby"],
+		"aria-describedby": props["aria-describedby"],
+		"data-highlighted": isFocused ? "" : void 0,
+		"data-selected": isSelected ? "" : void 0,
+		"data-disabled": isDisabled ? "" : void 0,
+		className: cn(listItemClass, className),
+		children: [node.rendered, isSelected ? /* @__PURE__ */ jsx(CheckIcon, {
+			size: 16,
+			className: checkClass
+		}) : null]
+	});
+}
+/** 묶음 하나를 그린다. 제목은 보조기술에서 숨기고(`presentation`) 묶음의 이름으로만 쓴다(useListBoxSection). */
+function ListBoxSectionView({ node, state }) {
+	const { className } = node.props;
+	const { itemProps, headingProps, groupProps } = useListBoxSection({
+		heading: node.rendered,
+		"aria-label": node["aria-label"]
+	});
+	return /* @__PURE__ */ jsxs("div", {
+		...itemProps,
+		className,
+		children: [node.rendered != null && /* @__PURE__ */ jsx("div", {
+			...headingProps,
+			className: "px-2 pt-1.5 pb-1 text-label-sm text-muted select-none",
+			children: node.rendered
+		}), /* @__PURE__ */ jsx("div", {
+			...groupProps,
+			children: [...node.childNodes].map((child) => /* @__PURE__ */ jsx(ListBoxOptionView, {
+				node: child,
+				state
+			}, child.key))
+		})]
+	});
+}
+
+export { ListBoxNodes };

package/dist/overlay-style.js

@@ -31,5 +31,54 @@ const popoverMotionClass = [
 	"motion-safe:data-[placement=bottom]:starting:-translate-y-1 motion-safe:data-[placement=top]:starting:translate-y-1",
 	"motion-safe:data-[placement=right]:starting:-translate-x-1 motion-safe:data-[placement=left]:starting:translate-x-1"
 ].join(" ");
+/**
+* 「자주 씀」 오버레이(Tooltip, Menu, Select·Combobox 목록)의 등장·퇴장(spec 「motion 적용」, 티켓 26).
+* 요소에 `data-open`(열림)이 있어야 한다.
+*
+* - 등장: 바로 나타난다. 열린 동안은 `transition-none`이라 퇴장 중에 다시 열려도 바로 불투명해진다.
+*   새로 넣은 요소는 이전 스타일이 없어 전환이 생기지 않으므로 `starting:`도 두지 않는다.
+* - 퇴장: `data-open`이 빠지면 opacity만 `fast`(150ms), out으로 사라진다. 전환 대상은 opacity와 display다.
+*   duration·전환 대상은 도착 상태의 값을 쓰므로 닫힌 상태에서만 전환이 있다.
+* - 닫힌 상태는 `display: none`(`hidden`)이고 `transition-discrete`로 퇴장이 끝날 때 사라진다(popoverMotionClass와 같다).
+*   DOM에서 빼는 시점은 `useOverlayPresence`가 정한다. 퇴장 중에는 `pointer-events-none`이다.
+* - reduced-motion: 이동·blur·확대가 없으므로 바꿀 것이 없다. opacity 전환은 그대로 둔다.
+*/
+const frequentMotionClass = ["transition-[opacity,display] transition-discrete duration-fast ease-out data-open:transition-none", "not-data-open:pointer-events-none not-data-open:hidden not-data-open:opacity-0"].join(" ");
+/**
+* Dialog류(Dialog, AlertDialog) 표면(spec radius·Elevation, 티켓 30). 가운데에 뜨는 모달이라 트리거에 붙는
+* 오버레이보다 한 단계 높다. raised 표면(`bg-raised`), `shadow-lg`, radius `xl`, 경계 `border-raised`.
+* 글자·경계·forced-colors 처리는 `overlaySurfaceClass`와 같다(`text-default × bg-raised` 4.5:1 등록, `border-raised`는 장식용).
+*/
+const dialogSurfaceClass = "rounded-xl border border-raised bg-raised text-default shadow-lg";
+/**
+* 모달 뒤를 가리는 반투명 막(backdrop, `bg-overlay`)의 등장·퇴장(티켓 30). 요소에 `data-open`이 있어야 한다.
+*
+* - 등장: `starting:`에서 opacity 0으로 시작해 `normal`(300ms)로 나타난다. 퇴장: `data-open`이 빠지면 `fast`(150ms)로 사라진다.
+* - 닫힌 상태는 `display: none`(`hidden`) + `transition-discrete`로 퇴장이 끝날 때 사라지고, 퇴장 중에는
+*   `pointer-events-none`이다(popoverMotionClass와 같은 구조). 안의 Dialog도 이 값을 물려받아 눌리지 않는다.
+* - opacity만 바뀌므로 움직임 줄이기에서도 같다.
+* - `useOverlayPresence`는 이 요소(막)의 전환이 끝나기를 기다린다. 안의 Dialog 전환(`dialogMotionClass`)도 같은
+*   duration이라 함께 끝난다.
+*/
+const backdropMotionClass = [
+	"transition-[opacity,display] transition-discrete duration-fast ease-out data-open:duration-normal",
+	"not-data-open:pointer-events-none not-data-open:hidden not-data-open:opacity-0",
+	"starting:opacity-0"
+].join(" ");
+/**
+* Dialog류의 등장·퇴장(spec 「motion 적용」 「가끔 씀」 Dialog류, 티켓 30). 요소에 `data-open`이 있어야 한다.
+*
+* - 등장: `starting:`에서 opacity 0 + scale 0.96(`scale-96`)으로 시작해 `normal`(300ms), out으로 제자리에 온다.
+* - 퇴장: `data-open`이 빠지면 같은 조합을 약하게(scale 0.98, `scale-98`) `fast`(150ms)로 사라진다.
+*   duration은 도착 상태의 값을 쓰므로 기본 `duration-fast`에 열림만 `data-open:duration-normal`이다.
+* - 화면에서 빼는 일(display)은 바깥 막(`backdropMotionClass`)이 한다. 이 요소는 opacity·scale만 전환한다.
+* - reduced-motion: 확대(scale)와 그 전환 대상은 `motion-safe:`일 때만 둔다. 움직임 줄이기에서는 opacity만 바뀐다.
+* - `transition-all`은 쓰지 않는다.
+*/
+const dialogMotionClass = [
+	"transition-[opacity] duration-fast ease-out data-open:duration-normal motion-safe:transition-[opacity,scale]",
+	"not-data-open:opacity-0 motion-safe:not-data-open:scale-98",
+	"starting:opacity-0 motion-safe:starting:scale-96"
+].join(" ");
 
-export { overlaySurfaceClass, popoverMotionClass };
+export { backdropMotionClass, dialogMotionClass, dialogSurfaceClass, frequentMotionClass, overlaySurfaceClass, popoverMotionClass };

package/dist/overlay.js

@@ -1,7 +1,7 @@
 "use client";
 
 import { jsx } from "react/jsx-runtime";
-import { useLayoutEffect, useState } from "react";
+import { useEffect, useLayoutEffect, useState } from "react";
 import { Overlay, usePopover } from "react-aria";
 
 // src/overlay.tsx
@@ -92,15 +92,39 @@ function useOverlayTheme(triggerRef, overlayRef) {
 	}, [triggerRef, overlayRef]);
 }
 /**
+* 오버레이 안에서 Tab을 누르면 기본 동작을 막고 닫는다(포커스는 `OverlayPortal`의 FocusScope가 트리거로 돌린다).
+* 목록 오버레이(Menu, Select)가 쓴다(WAI-ARIA APG Menu Button·Select-Only Combobox: Tab은 목록을 닫는다).
+*
+* React Aria 목록 hook(useMenu·useListBox)은 Tab으로 닫지 않고, 항목의 keydown 처리가 전파를 멈추며 FocusScope가
+* document capture에서 Tab을 먼저 다룬다. 열린 동안 바깥은 inert라 브라우저 기본 Tab은 갈 곳이 없다. 그래서 그보다
+* 앞인 window capture에서 받는다(티켓 27에서 Menu 안에 두었다가 티켓 28에서 이곳으로 옮겼다).
+* 전파도 멈춘다. listbox(useListBox 안의 useSelectableCollection)는 Tab에서 포커스를 목록 안 요소로 옮기는데, 그러면
+* 닫힌 뒤 포커스가 트리거로 돌아오지 않았다(Select 테스트로 확인).
+*/
+function useCloseOnTab(overlayRef, close) {
+	useEffect(() => {
+		const onKeyDown = (event) => {
+			if (event.key !== "Tab" || !overlayRef.current?.contains(event.target)) return;
+			event.preventDefault();
+			event.stopPropagation();
+			close();
+		};
+		window.addEventListener("keydown", onKeyDown, true);
+		return () => window.removeEventListener("keydown", onKeyDown, true);
+	}, [close, overlayRef]);
+}
+/**
 * 오버레이를 `document.body`에 portal한다(React Aria `Overlay`). top-layer(`<dialog>`, popover API)는 쓰지 않는다.
 * 안을 `FocusScope`(`restoreFocus`)로 감싸서, DOM에서 빠질 때 포커스가 열기 전 요소(보통 트리거)로 돌아간다.
 * 역할 hook이 포커스 가두기를 요청하면(`useDialog` 등) Tab이 안에서 돈다. 서버 렌더에서는 아무것도 그리지 않는다.
+* `focusManagement={false}`면 FocusScope 없이 portal만 한다(Tooltip).
 */
-function OverlayPortal({ isExiting, children }) {
+function OverlayPortal({ isExiting, focusManagement = true, children }) {
 	return /* @__PURE__ */ jsx(Overlay, {
 		isExiting,
+		disableFocusManagement: !focusManagement,
 		children
 	});
 }
 
-export { OverlayPortal, overlayPositionProps, useOverlayPresence, useOverlayTheme, usePopoverOverlay };
+export { OverlayPortal, overlayPositionProps, useCloseOnTab, useOverlayPresence, useOverlayTheme, usePopoverOverlay };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tide-tds/components",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Tide 디자인 시스템의 React Component",
   "license": "MIT",
   "repository": {
@@ -23,8 +23,8 @@
     "./styles.css": "./dist/styles.css"
   },
   "dependencies": {
-    "@tide-tds/foundation": "0.3.1",
-    "@tide-tds/icons": "0.3.1",
+    "@tide-tds/foundation": "0.4.0",
+    "@tide-tds/icons": "0.4.0",
     "clsx": "^2.1.1",
     "react-aria": "^3.53.1",
     "react-stately": "^3.51.0",