@tide-tds/components 0.3.0 → 0.4.0

package/dist/Popover.js

@@ -0,0 +1,147 @@
+"use client";
+
+import { cn } from "./cn.js";
+import { OverlayPortal, useOverlayPresence, useOverlayTheme, usePopoverOverlay } from "./overlay.js";
+import { overlaySurfaceClass, popoverMotionClass } from "./overlay-style.js";
+import { renderElement } from "./render.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { createContext, createElement, use, useId, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { DismissButton, mergeProps, mergeRefs, useDialog, useOverlayTrigger, usePress } from "react-aria";
+import { useOverlayTriggerState } from "react-stately";
+
+// src/Popover.tsx
+const PopoverContext = createContext(null);
+function usePopoverContext(part) {
+	const context = use(PopoverContext);
+	if (!context) throw new Error(`${part}는 Popover 안에 둔다.`);
+	return context;
+}
+/**
+* 트리거와 내용을 잇는 열림 상태. DOM 요소를 만들지 않는다.
+* 안에 `PopoverTrigger` 하나와 `PopoverContent` 하나를 둔다.
+*/
+function Popover({ open, defaultOpen, onOpenChange, children }) {
+	const state = useOverlayTriggerState({
+		isOpen: open,
+		defaultOpen,
+		onOpenChange
+	});
+	const triggerRef = useRef(null);
+	const { triggerProps, overlayProps } = useOverlayTrigger({ type: "dialog" }, state, triggerRef);
+	const generatedTriggerId = useId();
+	const [triggerId, setTriggerId] = useState(generatedTriggerId);
+	const value = useMemo(() => ({
+		state,
+		triggerRef,
+		triggerProps,
+		contentId: overlayProps.id,
+		triggerId,
+		setTriggerId
+	}), [
+		state,
+		triggerProps,
+		overlayProps.id,
+		triggerId
+	]);
+	return /* @__PURE__ */ jsx(PopoverContext, {
+		value,
+		children
+	});
+}
+/**
+* Popover를 여닫는 버튼. 누르면(마우스, 터치, Enter, Space) 열림 상태를 뒤집는다.
+* `aria-expanded`, 열렸을 때 `aria-controls`, 열렸을 때 `data-open`이 붙는다.
+*/
+function PopoverTrigger({ render, ref, id, className, ...props }) {
+	const { state, triggerRef, triggerProps, triggerId, setTriggerId } = usePopoverContext("PopoverTrigger");
+	const { onPress, ...ariaProps } = triggerProps;
+	const { pressProps } = usePress({
+		onPress,
+		ref: triggerRef
+	});
+	const mergedRef = useMemo(() => mergeRefs(ref, triggerRef), [ref, triggerRef]);
+	const resolvedId = id ?? triggerId;
+	useLayoutEffect(() => {
+		if (resolvedId !== triggerId) setTriggerId(resolvedId);
+	}, [
+		resolvedId,
+		triggerId,
+		setTriggerId
+	]);
+	const merged = {
+		...mergeProps(props, ariaProps, pressProps),
+		id: resolvedId,
+		ref: mergedRef,
+		"data-open": state.isOpen ? "" : void 0
+	};
+	if (!render) return createElement("button", {
+		type: "button",
+		...merged,
+		className
+	});
+	return renderElement({
+		defaultElement: "button",
+		render,
+		baseClassName: "",
+		props: {
+			...merged,
+			className
+		}
+	});
+}
+const contentClass = `isolate z-popover max-w-80 overflow-auto p-4 text-body-md outline-none ${overlaySurfaceClass} ${popoverMotionClass}`;
+/**
+* 트리거 옆에 뜨는 내용(`role="dialog"`). 열릴 때만 `document.body`에 portal로 렌더하고 `z-popover`로 쌓는다.
+* 등장은 opacity + blur 4px + 4px 이동(`normal`), 퇴장은 그 절반(`fast`)이다. 움직임 줄이기에서는 opacity만 바뀐다.
+* 열려 있으면 `data-open`이, 트리거 기준 방향이 `data-placement`(`top`/`bottom`/`left`/`right`)로 붙는다.
+*/
+function PopoverContent(props) {
+	const context = usePopoverContext("PopoverContent");
+	const popoverRef = useRef(null);
+	if (!useOverlayPresence(context.state.isOpen, popoverRef)) return null;
+	return /* @__PURE__ */ jsx(OverlayPortal, {
+		isExiting: !context.state.isOpen,
+		children: /* @__PURE__ */ jsx(PopoverContentInner, {
+			...props,
+			context,
+			popoverRef
+		})
+	});
+}
+/** DOM에 있는 동안만 portal 안에서 렌더한다. React Aria 오버레이 hook은 요소가 있다고 보고 동작한다. */
+function PopoverContentInner({ context, popoverRef, placement = "bottom", offset = 8, ref, className, children, ...props }) {
+	const { state, triggerRef, contentId, triggerId } = context;
+	useOverlayTheme(triggerRef, popoverRef);
+	const { overlayProps } = usePopoverOverlay({
+		triggerRef,
+		popoverRef,
+		placement,
+		offset
+	}, state);
+	const { dialogProps } = useDialog({
+		"aria-label": props["aria-label"],
+		"aria-labelledby": props["aria-labelledby"]
+	}, popoverRef);
+	const labelledBy = dialogProps["aria-labelledby"] ?? (props["aria-label"] ? void 0 : triggerId);
+	const mergedRef = useMemo(() => mergeRefs(ref, popoverRef), [ref, popoverRef]);
+	const { style: _style, ...rest } = mergeProps(props, overlayProps, dialogProps);
+	return /* @__PURE__ */ jsxs("div", {
+		...rest,
+		id: contentId,
+		ref: mergedRef,
+		"aria-labelledby": labelledBy,
+		"data-open": state.isOpen ? "" : void 0,
+		className: cn(contentClass, className),
+		style: {
+			...overlayProps.style,
+			...props.style
+		},
+		children: [
+			/* @__PURE__ */ jsx(DismissButton, { onDismiss: state.close }),
+			children,
+			/* @__PURE__ */ jsx(DismissButton, { onDismiss: state.close })
+		]
+	});
+}
+
+export { Popover, PopoverContent, PopoverTrigger };

package/dist/Select.d.ts

@@ -0,0 +1,62 @@
+import { InputSize } from "./input-style.js";
+import { ListBoxOptionProps, ListBoxSectionProps } from "./listbox.js";
+import { ComponentProps, ReactElement, ReactNode } from "react";
+export interface SelectProps extends Omit<ComponentProps<"button">, "value" | "defaultValue" | "onChange" | "type" | "size" | "children" | "name" | "form"> {
+  /** 고른 값(제어). 고른 옵션의 `value`다. `null`이면 아무것도 고르지 않은 상태다. 주면 `onValueChange`로 바꾼다. */
+  value?: string | null;
+  /** 처음 고른 값(비제어). 주지 않으면 아무것도 고르지 않은 상태로 시작한다. 폼을 reset하면 이 값으로 돌아간다. */
+  defaultValue?: string;
+  /** 사용자가 다른 옵션을 고르면 그 옵션의 `value`로 부른다. */
+  onValueChange?: (value: string) => void;
+  /** 목록 열림 상태(제어). 주면 `onOpenChange`로 바꾼다. */
+  open?: boolean;
+  /** 처음 목록 열림 상태(비제어). 기본값은 `false`다. */
+  defaultOpen?: boolean;
+  /** 목록 열림 상태가 바뀌려 할 때 새 값으로 부른다. 옵션을 골라 닫힐 때도 부른다. */
+  onOpenChange?: (open: boolean) => void;
+  /** 폼 제출 이름. 숨은 `<select>`에 붙어 고른 값이 이 이름으로 제출된다(트리거 버튼에는 붙지 않는다). */
+  name?: string;
+  /** 숨은 `<select>`가 속할 `<form>`의 id. 폼 밖에 둘 때 쓴다. */
+  form?: string;
+  /** 브라우저 자동 완성 힌트. 숨은 `<select>`에 붙는다. */
+  autoComplete?: string;
+  /** 아무것도 고르지 않았을 때 트리거에 보이는 글자. 기본값은 `"선택하세요"`다. */
+  placeholder?: string;
+  /** 높이 `sm` 32px, `md` 40px, `lg` 48px. 같은 size의 Input·Button과 높이가 같다. 기본값은 `md`다. */
+  size?: InputSize;
+  /**
+   * 오류 상태. 트리거에 `aria-invalid="true"`와 `data-invalid`가 붙고 경계가 danger 색이 된다.
+   * Field 안에서는 Field의 값을 따르고, 여기에 준 값이 이긴다.
+   */
+  invalid?: boolean;
+  /**
+   * 필수. 고르지 않고 폼을 제출하면 제출이 막히고 트리거로 포커스가 오며 오류 상태가 된다(브라우저 오류 말풍선은
+   * 없다). 메시지는 Field의 `error`로 앱이 보여 준다. Field 안에서는 Field의 값을 따른다.
+   */
+  required?: boolean;
+  /** `SelectItem`과 `SelectSection`. 이 요소들을 바로 아래(또는 Fragment·배열 안)에 둔다. */
+  children?: ReactNode;
+}
+/**
+ * 값 하나를 고르는 입력. 트리거를 누르거나(마우스는 누르는 순간) Enter·Space·↓·↑로 목록을 열고, 화살표·Home/End·
+ * 영문 글자로 옵션을 옮겨 Enter·Space·누름으로 고른다. 닫힌 채로 글자를 치면 바로 그 옵션을 고른다.
+ * 고르면 닫히고 포커스는 트리거로 돌아온다. Esc·바깥 누름·Tab으로도 닫힌다.
+ * Field 안에 두면 label·설명·오류가 자동으로 연결되고, `name`을 주면 고른 값이 폼에 제출된다.
+ * 상태는 `data-open`(트리거·목록), `data-invalid`(트리거), 네이티브 `:disabled`(트리거),
+ * `data-highlighted`·`data-selected`·`data-disabled`(옵션)로 노출한다.
+ */
+export declare function Select({ value, defaultValue, onValueChange, open, defaultOpen, onOpenChange, name, form, autoComplete, placeholder, size, invalid, disabled, required, id, ref, className, children, "aria-describedby": ariaDescribedBy, "aria-invalid": ariaInvalid, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, ...props }: SelectProps): ReactElement;
+export interface SelectItemProps extends ListBoxOptionProps {}
+/**
+ * Select의 옵션(`role="option"`). `Select`나 `SelectSection` 바로 안에 둔다. `value`가 고른 값이고 폼에 제출된다.
+ * 내용(아이콘과 글자)은 고르면 트리거에도 보인다. 키보드 위치와 마우스를 올린 옵션은 highlight(primary subtle 배경,
+ * primary 글자), 고른 옵션은 neutral subtle-active 배경과 끝의 체크 아이콘이다.
+ * 상태는 `data-highlighted`, `data-selected`, `data-disabled`로 노출한다.
+ */
+export declare function SelectItem(_props: SelectItemProps): null;
+export interface SelectSectionProps extends ListBoxSectionProps {}
+/**
+ * 옵션 묶음(`role="group"`). `heading`이 화면에 보이는 제목이자 묶음의 이름이고, 없으면 `aria-label`이 이름이다.
+ * 앞뒤 다른 옵션·묶음과의 사이에 구분선이 그려진다.
+ */
+export declare function SelectSection(_props: SelectSectionProps): null;

package/dist/Select.js

@@ -0,0 +1,169 @@
+"use client";
+
+import { cn } from "./cn.js";
+import { FieldContext, useFieldControl } from "./field-context.js";
+import { inputBaseClass, inputSizeClass } from "./input-style.js";
+import { asCollectionComponent, resolveCollectionChildren, sectionCollectionNode, valueItemCollectionNode } from "./list-collection.js";
+import { listPopupClass } from "./list-style.js";
+import { ListBoxNodes } from "./listbox.js";
+import { OverlayPortal, useCloseOnTab, useOverlayPresence, useOverlayTheme, usePopoverOverlay } from "./overlay.js";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { use, useLayoutEffect, useMemo, useRef } from "react";
+import { ChevronDownIcon } from "@tide-tds/icons";
+import { DismissButton, HiddenSelect, mergeProps, mergeRefs, useButton, useListBox, useSelect } from "react-aria";
+import { useSelectState } from "react-stately";
+
+// src/Select.tsx
+const triggerClass = "group inline-flex items-center justify-between gap-2 text-start";
+const valueClass = "min-w-0 flex-1 truncate [&>svg]:me-2 [&>svg]:inline-block [&>svg]:size-4 [&>svg]:align-[-0.125em]";
+const placeholderClass = "text-muted group-disabled:text-disabled";
+const chevronClass = "shrink-0 text-muted group-disabled:text-disabled";
+/**
+* 값 하나를 고르는 입력. 트리거를 누르거나(마우스는 누르는 순간) Enter·Space·↓·↑로 목록을 열고, 화살표·Home/End·
+* 영문 글자로 옵션을 옮겨 Enter·Space·누름으로 고른다. 닫힌 채로 글자를 치면 바로 그 옵션을 고른다.
+* 고르면 닫히고 포커스는 트리거로 돌아온다. Esc·바깥 누름·Tab으로도 닫힌다.
+* Field 안에 두면 label·설명·오류가 자동으로 연결되고, `name`을 주면 고른 값이 폼에 제출된다.
+* 상태는 `data-open`(트리거·목록), `data-invalid`(트리거), 네이티브 `:disabled`(트리거),
+* `data-highlighted`·`data-selected`·`data-disabled`(옵션)로 노출한다.
+*/
+function Select({ value, defaultValue, onValueChange, open, defaultOpen, onOpenChange, name, form, autoComplete, placeholder = "선택하세요", size = "md", invalid, disabled, required, id, ref, className, children, "aria-describedby": ariaDescribedBy, "aria-invalid": ariaInvalid, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, ...props }) {
+	const field = use(FieldContext);
+	const control = useFieldControl({
+		id,
+		invalid,
+		disabled,
+		required,
+		"aria-describedby": ariaDescribedBy,
+		"aria-invalid": ariaInvalid
+	});
+	const isDisabled = control.disabled ?? false;
+	const isRequired = control.required ?? false;
+	const items = useMemo(() => resolveCollectionChildren(children), [children]);
+	const state = useSelectState({
+		children: items,
+		value,
+		defaultValue,
+		onChange: (key) => {
+			if (key != null) onValueChange?.(String(key));
+		},
+		isOpen: open,
+		defaultOpen,
+		onOpenChange,
+		isDisabled,
+		isRequired,
+		validationBehavior: "native"
+	});
+	const triggerRef = useRef(null);
+	const { triggerProps, valueProps, menuProps, hiddenSelectProps, isInvalid } = useSelect({
+		id: control.id,
+		"aria-label": ariaLabel,
+		"aria-labelledby": ariaLabelledBy ?? field?.labelId,
+		isDisabled,
+		isRequired,
+		validationBehavior: "native",
+		name,
+		form,
+		autoComplete
+	}, state, triggerRef);
+	const { buttonProps } = useButton(triggerProps, triggerRef);
+	const mergedRef = useMemo(() => mergeRefs(ref, triggerRef), [ref, triggerRef]);
+	const showInvalid = control["data-invalid"] === "" || isInvalid;
+	const selected = state.selectedItem;
+	return /* @__PURE__ */ jsxs(Fragment, { children: [
+		/* @__PURE__ */ jsxs("button", {
+			...mergeProps(props, buttonProps),
+			ref: mergedRef,
+			"aria-describedby": control["aria-describedby"],
+			"aria-invalid": showInvalid ? true : control["aria-invalid"],
+			"data-invalid": showInvalid ? "" : void 0,
+			"data-open": state.isOpen ? "" : void 0,
+			className: cn(inputSizeClass[size], inputBaseClass, triggerClass, className),
+			children: [/* @__PURE__ */ jsx("span", {
+				...valueProps,
+				className: cn(valueClass, !selected && placeholderClass),
+				children: selected ? selected.rendered : placeholder
+			}), /* @__PURE__ */ jsx(ChevronDownIcon, {
+				size: 16,
+				className: chevronClass
+			})]
+		}),
+		/* @__PURE__ */ jsx(HiddenSelect, {
+			...hiddenSelectProps,
+			autoComplete
+		}),
+		/* @__PURE__ */ jsx(SelectPopover, {
+			state,
+			triggerRef,
+			menuProps
+		})
+	] });
+}
+/** 목록을 DOM에 둘지 정하고 portal한다. 닫혀도 퇴장 전환이 끝날 때까지 남긴다(ADR 0018). */
+function SelectPopover(props) {
+	const popoverRef = useRef(null);
+	if (!useOverlayPresence(props.state.isOpen, popoverRef)) return null;
+	return /* @__PURE__ */ jsx(OverlayPortal, {
+		isExiting: !props.state.isOpen,
+		children: /* @__PURE__ */ jsx(SelectPopoverInner, {
+			...props,
+			popoverRef
+		})
+	});
+}
+/**
+* 목록 표면(`listPopupClass`)과 그 안의 `role="listbox"`. 트리거 아래 시작 끝에 4px 떨어져 붙고(Menu와 같다),
+* 폭은 트리거보다 좁지 않다.
+*/
+function SelectPopoverInner({ state, triggerRef, menuProps, popoverRef }) {
+	const listRef = useRef(null);
+	useOverlayTheme(triggerRef, popoverRef);
+	useLayoutEffect(() => {
+		const popover = popoverRef.current;
+		const width = triggerRef.current?.offsetWidth;
+		if (popover && width) popover.style.minWidth = `${width}px`;
+	}, [triggerRef, popoverRef]);
+	const { overlayProps } = usePopoverOverlay({
+		triggerRef,
+		popoverRef,
+		placement: "bottom start",
+		offset: 4
+	}, state);
+	const { listBoxProps } = useListBox(menuProps, state, listRef);
+	useCloseOnTab(popoverRef, state.close);
+	return /* @__PURE__ */ jsxs("div", {
+		...overlayProps,
+		ref: popoverRef,
+		"data-open": state.isOpen ? "" : void 0,
+		className: listPopupClass,
+		children: [
+			/* @__PURE__ */ jsx(DismissButton, { onDismiss: state.close }),
+			/* @__PURE__ */ jsx("div", {
+				...listBoxProps,
+				ref: listRef,
+				className: "outline-none",
+				children: /* @__PURE__ */ jsx(ListBoxNodes, { state })
+			}),
+			/* @__PURE__ */ jsx(DismissButton, { onDismiss: state.close })
+		]
+	});
+}
+/**
+* Select의 옵션(`role="option"`). `Select`나 `SelectSection` 바로 안에 둔다. `value`가 고른 값이고 폼에 제출된다.
+* 내용(아이콘과 글자)은 고르면 트리거에도 보인다. 키보드 위치와 마우스를 올린 옵션은 highlight(primary subtle 배경,
+* primary 글자), 고른 옵션은 neutral subtle-active 배경과 끝의 체크 아이콘이다.
+* 상태는 `data-highlighted`, `data-selected`, `data-disabled`로 노출한다.
+*/
+function SelectItem(_props) {
+	return null;
+}
+asCollectionComponent(SelectItem, valueItemCollectionNode);
+/**
+* 옵션 묶음(`role="group"`). `heading`이 화면에 보이는 제목이자 묶음의 이름이고, 없으면 `aria-label`이 이름이다.
+* 앞뒤 다른 옵션·묶음과의 사이에 구분선이 그려진다.
+*/
+function SelectSection(_props) {
+	return null;
+}
+asCollectionComponent(SelectSection, sectionCollectionNode);
+
+export { Select, SelectItem, SelectSection };

package/dist/Tabs.d.ts

@@ -0,0 +1,66 @@
+import { CollectionValueItemProps } from "./list-collection.js";
+import { ComponentProps, ReactElement, ReactNode } from "react";
+/** 탭 목록의 방향. 세로면 ↓↑로 옮기고 탭 목록이 패널의 시작쪽에 선다. */
+export type TabsOrientation = "horizontal" | "vertical";
+/** 키보드로 탭을 옮겼을 때 바로 고를지(`automatic`), Enter·Space로 고를지(`manual`). */
+export type TabsActivationMode = "automatic" | "manual";
+type TabsValueProps = {
+  /** 고른 탭의 값(제어). 주면 `onValueChange`로 바꾼다. */
+  value: string;
+  defaultValue?: undefined;
+} | {
+  value?: undefined;
+  /** 처음 고른 탭의 값(비제어). 서버 렌더에서도 그 패널이 바로 보이도록 `value`나 `defaultValue` 하나는 꼭 준다. */
+  defaultValue: string;
+};
+interface TabsBaseProps extends Omit<ComponentProps<"div">, "defaultValue" | "onChange"> {
+  /**
+   * 고른 탭이 바뀌려 할 때 새 값으로 부른다. 이미 고른 탭을 다시 눌러도 부르지 않는다.
+   * 준 값과 같은 탭이 없으면 첫 활성 탭을 고르며 부른다.
+   */
+  onValueChange?: (value: string) => void;
+  /** 탭 목록의 방향. 기본값은 `horizontal`이다. 세로면 ↓↑로 옮기고 탭 목록이 패널의 시작쪽에 선다. */
+  orientation?: TabsOrientation;
+  /**
+   * 키보드로 탭을 옮겼을 때 바로 고를지(`automatic`, 기본값), Enter·Space로 고를지(`manual`)다.
+   * 패널을 그리는 데 시간이 걸리면(데이터를 불러오는 패널) `manual`을 쓴다(WAI-ARIA APG).
+   */
+  activationMode?: TabsActivationMode;
+  /** `TabList` 하나와 `TabPanel`들 */
+  children?: ReactNode;
+}
+export type TabsProps = TabsBaseProps & TabsValueProps;
+/**
+ * 같은 영역의 여러 패널 중 하나를 고르는 탭 묶음. 루트는 `<div>`이고 방향이 `data-orientation`으로 붙는다.
+ * 안에 `TabList` 하나와 탭마다 `TabPanel`을 둔다.
+ */
+export declare function Tabs({ value: valueProp, defaultValue, onValueChange, orientation, activationMode, ref, className, children, ...props }: TabsProps): ReactElement;
+export interface TabListProps extends Omit<ComponentProps<"div">, "role" | "children"> {
+  /** `Tab`. 바로 아래(또는 Fragment·배열 안)에 둔다. */
+  children?: ReactNode;
+}
+/**
+ * 탭 목록(`role="tablist"`). 화살표로 탭을 옮기고(끝에서 처음으로 돈다) Home·End로 처음·마지막 탭에 간다.
+ * 비활성 탭은 건너뛴다. 이름은 `aria-label`이나 `aria-labelledby`로 준다.
+ */
+export declare function TabList({ ref, className, children, ...props }: TabListProps): ReactElement;
+export interface TabProps extends Omit<ComponentProps<"button">, "value" | "type" | "role" | "id" | "disabled" | "children">, Omit<CollectionValueItemProps, "textValue"> {
+  /** 탭 글자. 아이콘(장식용)과 글자를 함께 둘 수 있다. */
+  children?: ReactNode;
+}
+/**
+ * 탭 하나(`role="tab"`). `TabList` 바로 안에 두고, 같은 `value`의 `TabPanel`과 이어진다.
+ * 고른 탭은 `data-selected`와 `aria-selected="true"`이고 primary 글자와 아래(세로면 끝쪽) 막대로 보인다.
+ * `disabled`면 네이티브 `disabled`라 고를 수 없고 키보드 이동도 건너뛴다.
+ */
+export declare function Tab(_props: TabProps): null;
+export interface TabPanelProps extends Omit<ComponentProps<"div">, "id" | "role"> {
+  /** 이어지는 `Tab`의 값. 그 탭을 고른 동안만 렌더한다. */
+  value: string;
+}
+/**
+ * 탭 하나의 내용(`role="tabpanel"`). 같은 `value`의 탭을 고른 동안만 렌더하고, 그 탭이 이름이 된다(`aria-labelledby`).
+ * 탭 다음 Tab 순서에 들어간다(`tabIndex` 기본 `0`). 첫 내용이 조작 요소면 `tabIndex={-1}`로 뺄 수 있다.
+ */
+export declare function TabPanel({ value, ref, className, tabIndex, ...props }: TabPanelProps): ReactElement | null;
+export {};

package/dist/Tabs.js

@@ -0,0 +1,159 @@
+"use client";
+
+import { cn } from "./cn.js";
+import { asCollectionComponent, resolveCollectionChildren, valueItemCollectionNode } from "./list-collection.js";
+import { jsx } from "react/jsx-runtime";
+import { createContext, isValidElement, use, useCallback, useId, useMemo, useRef, useState } from "react";
+import { mergeProps, mergeRefs, useTab, useTabList } from "react-aria";
+import { useTabListState } from "react-stately";
+
+// src/Tabs.tsx
+const TabsContext = createContext(null);
+function useTabsContext(part) {
+	const context = use(TabsContext);
+	if (!context) throw new Error(`${part}는 Tabs 안에 둔다.`);
+	return context;
+}
+const tabsOrientationClass = {
+	horizontal: "flex flex-col gap-4",
+	vertical: "flex flex-row gap-6"
+};
+const tabListOrientationClass = {
+	horizontal: "flex shrink-0 gap-1 border-b border-default",
+	vertical: "flex shrink-0 flex-col gap-1 border-e border-default"
+};
+const tabBaseClass = [
+	"relative flex cursor-pointer items-center gap-2 rounded-md px-3 py-2 text-label-md whitespace-nowrap text-muted outline-none select-none [&>svg]:size-4 [&>svg]:shrink-0",
+	"hover:not-data-selected:enabled:text-default data-selected:text-primary focus-visible:focus-ring",
+	"disabled:cursor-not-allowed disabled:text-disabled",
+	"after:pointer-events-none after:absolute after:border-primary after:opacity-0 after:transition-opacity data-selected:after:opacity-100",
+	"forced-colors:after:forced-color-adjust-none forced-colors:after:border-[Highlight]"
+].join(" ");
+const tabOrientationClass = {
+	horizontal: "after:inset-x-0 after:-bottom-px after:border-b-2 motion-safe:after:scale-x-0 motion-safe:after:transition-[opacity,scale] motion-safe:data-selected:after:scale-x-100",
+	vertical: "after:inset-y-0 after:-end-px after:border-e-2 motion-safe:after:scale-y-0 motion-safe:after:transition-[opacity,scale] motion-safe:data-selected:after:scale-y-100"
+};
+const tabPanelClass = "min-w-0 flex-1 rounded-md outline-none focus-visible:focus-ring";
+/** id에 쓸 수 없는 공백을 뺀다(React Aria 탭 id와 같은 규칙). */
+const idPart = (value) => value.replace(/\s+/g, "");
+/**
+* 같은 영역의 여러 패널 중 하나를 고르는 탭 묶음. 루트는 `<div>`이고 방향이 `data-orientation`으로 붙는다.
+* 안에 `TabList` 하나와 탭마다 `TabPanel`을 둔다.
+*/
+function Tabs({ value: valueProp, defaultValue, onValueChange, orientation = "horizontal", activationMode = "automatic", ref, className, children, ...props }) {
+	const [internal, setInternal] = useState(defaultValue ?? "");
+	const controlled = valueProp !== void 0;
+	const value = controlled ? valueProp : internal;
+	const setValue = useCallback((next) => {
+		if (next === value) return;
+		if (!controlled) setInternal(next);
+		onValueChange?.(next);
+	}, [
+		controlled,
+		onValueChange,
+		value
+	]);
+	const baseId = useId();
+	const context = useMemo(() => ({
+		value,
+		setValue,
+		orientation,
+		activationMode,
+		tabId: (tab) => `${baseId}-tab-${idPart(tab)}`,
+		panelId: (tab) => `${baseId}-tabpanel-${idPart(tab)}`
+	}), [
+		value,
+		setValue,
+		orientation,
+		activationMode,
+		baseId
+	]);
+	return /* @__PURE__ */ jsx("div", {
+		...props,
+		ref,
+		"data-orientation": orientation,
+		className: cn(tabsOrientationClass[orientation], className),
+		children: /* @__PURE__ */ jsx(TabsContext, {
+			value: context,
+			children
+		})
+	});
+}
+/**
+* 탭 목록(`role="tablist"`). 화살표로 탭을 옮기고(끝에서 처음으로 돈다) Home·End로 처음·마지막 탭에 간다.
+* 비활성 탭은 건너뛴다. 이름은 `aria-label`이나 `aria-labelledby`로 준다.
+*/
+function TabList({ ref, className, children, ...props }) {
+	const context = useTabsContext("TabList");
+	const listRef = useRef(null);
+	const items = useMemo(() => resolveCollectionChildren(children), [children]);
+	const known = items.some((item) => isValidElement(item) && item.props.value === context.value);
+	const state = useTabListState({
+		children: items,
+		selectedKey: known ? context.value : null,
+		onSelectionChange: (key) => context.setValue(String(key))
+	});
+	const { tabListProps } = useTabList({
+		orientation: context.orientation,
+		keyboardActivation: context.activationMode,
+		"aria-label": props["aria-label"],
+		"aria-labelledby": props["aria-labelledby"]
+	}, state, listRef);
+	const mergedRef = useMemo(() => mergeRefs(ref, listRef), [ref, listRef]);
+	return /* @__PURE__ */ jsx("div", {
+		...mergeProps(props, tabListProps),
+		ref: mergedRef,
+		className: cn(tabListOrientationClass[context.orientation], className),
+		children: [...state.collection].map((node) => /* @__PURE__ */ jsx(TabView, {
+			node,
+			state,
+			context
+		}, node.key))
+	});
+}
+/**
+* 탭 하나(`role="tab"`). `TabList` 바로 안에 두고, 같은 `value`의 `TabPanel`과 이어진다.
+* 고른 탭은 `data-selected`와 `aria-selected="true"`이고 primary 글자와 아래(세로면 끝쪽) 막대로 보인다.
+* `disabled`면 네이티브 `disabled`라 고를 수 없고 키보드 이동도 건너뛴다.
+*/
+function Tab(_props) {
+	return null;
+}
+asCollectionComponent(Tab, valueItemCollectionNode);
+/** 탭 하나를 그린다. node.props는 앱이 Tab에 준 props(와 컬렉션이 더한 isDisabled)다. */
+function TabView({ node, state, context }) {
+	const tabRef = useRef(null);
+	const { ref, className, value, disabled: _disabled, isDisabled: _isDisabled, children: _children, onFocus: _onFocus, onBlur: _onBlur, onKeyDown: _onKeyDown, onKeyUp: _onKeyUp, autoFocus: _autoFocus, ...props } = node.props;
+	const { tabProps, isSelected, isDisabled } = useTab({ key: node.key }, state, tabRef);
+	const mergedRef = useMemo(() => mergeRefs(ref, tabRef), [ref, tabRef]);
+	return /* @__PURE__ */ jsx("button", {
+		...mergeProps(props, tabProps),
+		ref: mergedRef,
+		type: "button",
+		id: context.tabId(value),
+		"aria-controls": isSelected ? context.panelId(value) : void 0,
+		disabled: isDisabled || void 0,
+		"data-selected": isSelected ? "" : void 0,
+		className: cn(tabBaseClass, tabOrientationClass[context.orientation], className),
+		children: node.rendered
+	});
+}
+/**
+* 탭 하나의 내용(`role="tabpanel"`). 같은 `value`의 탭을 고른 동안만 렌더하고, 그 탭이 이름이 된다(`aria-labelledby`).
+* 탭 다음 Tab 순서에 들어간다(`tabIndex` 기본 `0`). 첫 내용이 조작 요소면 `tabIndex={-1}`로 뺄 수 있다.
+*/
+function TabPanel({ value, ref, className, tabIndex = 0, ...props }) {
+	const context = useTabsContext("TabPanel");
+	if (context.value !== value) return null;
+	return /* @__PURE__ */ jsx("div", {
+		...props,
+		ref,
+		role: "tabpanel",
+		id: context.panelId(value),
+		"aria-labelledby": context.tabId(value),
+		tabIndex,
+		className: cn(tabPanelClass, className)
+	});
+}
+
+export { Tab, TabList, TabPanel, Tabs };

package/dist/Tag.d.ts

@@ -0,0 +1,48 @@
+import { CollectionValueItemProps } from "./list-collection.js";
+import { ColorFamilyName } from "./types.js";
+import { ComponentProps, ReactElement, ReactNode } from "react";
+type TagGroupNameProps = {
+  /** 묶음 이름(예: `"고른 필터"`). 화면에 보이는 제목이 있으면 `aria-labelledby`를 쓴다. */
+  "aria-label": string;
+  "aria-labelledby"?: string;
+} | {
+  "aria-label"?: string;
+  /** 묶음 이름이 되는 요소의 id. 이름(`aria-label`이나 `aria-labelledby`) 하나는 꼭 준다. */
+  "aria-labelledby": string;
+};
+interface TagGroupBaseProps extends Omit<ComponentProps<"div">, "role" | "children" | "aria-label" | "aria-labelledby"> {
+  /**
+   * 태그를 지우려 할 때 지울 태그의 `value`로 부른다. 지우기 버튼을 누르거나 태그에서 Delete·Backspace를 누르면 불린다.
+   * 주면 태그마다 지우기 버튼이 생긴다. 태그를 목록에서 빼는 일은 앱이 한다.
+   */
+  onRemove?: (value: string) => void;
+  /**
+   * 지우기 버튼 이름의 앞부분. 기본값은 `"제거"`다. 버튼 이름은 이 글자와 태그 글자를 이어 읽는다(예: 「제거 디자인」).
+   */
+  removeLabel?: string;
+  /** `Tag`. 바로 아래(또는 Fragment·배열 안)에 둔다. */
+  children?: ReactNode;
+}
+export type TagGroupProps = TagGroupBaseProps & TagGroupNameProps;
+/**
+ * 고르거나 입력한 값을 보여 주는 태그 묶음(`role="grid"`). ←→로 태그를 옮기고(끝에서 처음으로 돈다) Home·End로
+ * 처음·마지막 태그에 간다. `onRemove`를 주면 Delete·Backspace와 지우기 버튼으로 태그를 지운다.
+ * 지운 뒤 포커스는 옆 태그로 옮겨 간다. 이름은 `aria-label`이나 `aria-labelledby`로 꼭 준다.
+ */
+export declare function TagGroup({ onRemove, removeLabel, ref, className, children, id, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledby, "aria-describedby": ariaDescribedby, ...props }: TagGroupProps): ReactElement;
+export interface TagProps extends Omit<ComponentProps<"div">, "color" | "role" | "id" | "tabIndex" | "children">, CollectionValueItemProps {
+  /** 태그 글자. 필수다. 아이콘(장식용)을 앞에 함께 둘 수 있다. */
+  children: ReactNode;
+  /**
+   * 색 계열 이름. Tide 색 계열 6개와 앱이 `ColorFamilyRegistry`에 더한 계열을 받는다. 기본값은 `gray`다.
+   * 분류를 구분하는 뜻 없는 색이라 Role(`primary`·`danger` 등)은 받지 않는다(ADR 0016·0017 후속).
+   * 루트에 `data-color`로 붙고 바깥 요소의 색을 물려받지 않는다.
+   */
+  color?: ColorFamilyName;
+}
+/**
+ * 태그 하나(`role="row"`). `TagGroup` 바로 안에 둔다. `value`가 묶음 안의 key이고 `onRemove`에 넘어오는 값이다.
+ * `disabled`면 지울 수 없고 키보드 이동도 건너뛴다(`aria-disabled`).
+ */
+export declare function Tag(_props: TagProps): null;
+export {};