@idbrnd/design-system 1.9.0 → 1.11.0

package/README.md

@@ -1,6 +1,6 @@
 # @idbrnd/design-system
 
-![Version](https://img.shields.io/badge/version-1.9.0-4B5FE1?style=flat-square)
+![Version](https://img.shields.io/badge/version-1.11.0-4B5FE1?style=flat-square)
 ![React](https://img.shields.io/badge/React-18.3.1-61DAFB?style=flat-square&logo=react&logoColor=white)
 ![Vite](https://img.shields.io/badge/Vite-7.3.0-646CFF?style=flat-square&logo=vite&logoColor=white)
 ![TypeScript](https://img.shields.io/badge/TypeScript-5.9.3-3178C6?style=flat-square&logo=typescript&logoColor=white)
@@ -68,6 +68,8 @@ export default function App() {
   - [ChipGroup](#chipgroup)
   - [FilterChip](#filterchip)
   - [FilterBar](#filterbar)
+- [SegmentedControl](#segmentedcontrol)
+- [Tab](#tab)
 - [테이블](#테이블)
   - [TableContainer](#tablecontainer)
   - [Table](#table)
@@ -1118,6 +1120,201 @@ import { FilterBar, FilterChip } from "@idbrnd/design-system";
 
 ---
 
+## SegmentedControl
+
+탭 형태로 옵션을 전환하는 컴포넌트입니다. WAI-ARIA `tablist` 패턴을 따르며 키보드(Arrow, Home, End)로 탐색할 수 있습니다.
+
+```tsx
+import { useState } from "react";
+import { SegmentedControl } from "@idbrnd/design-system";
+import type { SegmentedControlItem } from "@idbrnd/design-system";
+
+const items: SegmentedControlItem[] = [
+  { value: "day", label: "일" },
+  { value: "week", label: "주" },
+  { value: "month", label: "월" },
+];
+
+function Example() {
+  const [period, setPeriod] = useState("day");
+
+  return <SegmentedControl items={items} value={period} onChange={setPeriod} />;
+}
+```
+
+**outlined 타입 + large 크기**
+
+```tsx
+<SegmentedControl
+  type="outlined"
+  size="large"
+  items={items}
+  value={period}
+  onChange={setPeriod}
+/>
+```
+
+**아이콘 + 텍스트 (`icon=true`)**
+
+```tsx
+<SegmentedControl
+  icon
+  items={[
+    { value: "list", label: "목록", icon: <ListIcon /> },
+    { value: "grid", label: "그리드", icon: <GridIcon /> },
+    { value: "map", label: "지도", icon: <MapIcon /> },
+  ]}
+  value={view}
+  onChange={setView}
+/>
+```
+
+**아이콘 전용 (`variant="icon"`)**
+
+```tsx
+<SegmentedControl
+  variant="icon"
+  label="뷰 전환"
+  items={[
+    { value: "list", icon: <ListIcon />, ariaLabel: "목록 보기" },
+    { value: "grid", icon: <GridIcon />, ariaLabel: "그리드 보기" },
+    { value: "map", icon: <MapIcon />, ariaLabel: "지도 보기" },
+  ]}
+  value={view}
+  onChange={setView}
+/>
+```
+
+| Prop          | 타입                                 | 기본값     | 설명                                              |
+| ------------- | ------------------------------------ | ---------- | ------------------------------------------------- |
+| `items`       | `SegmentedControlItem[]`             | —          | **(필수)** 세그먼트 목록                          |
+| `value`       | `string`                             | —          | **(필수)** 현재 선택된 세그먼트 값                |
+| `onChange`    | `(value: string) => void`            | —          | 세그먼트 변경 콜백                                |
+| `variant`     | `"basic"` \| `"icon"`                | `"basic"`  | `"icon"`: 아이콘 전용 정사각형 세그먼트           |
+| `type`        | `"fill"` \| `"outlined"`             | `"fill"`   | 컴포넌트 외형                                     |
+| `size`        | `"small"` \| `"medium"` \| `"large"` | `"medium"` | 크기. small: 32px, medium: 40px, large: 48px      |
+| `icon`        | `boolean`                            | `false`    | `variant="basic"`에서 아이콘을 텍스트와 함께 표시 |
+| `label`       | `string`                             | —          | 스크린 리더용 그룹 레이블 (`aria-label`)          |
+| `customStyle` | `CSSProperties`                      | —          | 추가 인라인 스타일                                |
+
+**`SegmentedControlItem`**
+
+| 필드        | 타입        | 설명                                          |
+| ----------- | ----------- | --------------------------------------------- |
+| `value`     | `string`    | **(필수)** 세그먼트 고유 값                   |
+| `label`     | `ReactNode` | 텍스트 라벨 (`variant="basic"`에서 사용)      |
+| `icon`      | `ReactNode` | 아이콘 (`icon=true` 또는 `variant="icon"`)    |
+| `disabled`  | `boolean`   | 비활성화                                      |
+| `ariaLabel` | `string`    | `variant="icon"` 시 스크린 리더용 버튼 레이블 |
+
+유의사항:
+
+- `variant="icon"` 사용 시 각 item에 `ariaLabel`을 반드시 지정해야 합니다. 미지정 시 개발 모드에서 경고가 출력됩니다.
+- `variant="basic"`에서 `icon=true`이면 세그먼트 왼쪽에 아이콘, 나머지 공간에 텍스트가 배치됩니다.
+- `value`에 해당하는 item이 없으면 슬라이딩 인디케이터가 숨겨지고, 첫 번째 활성 항목에 키보드 포커스가 유지됩니다.
+- 키보드 ArrowLeft/Right(또는 Up/Down)로 세그먼트 이동, Home/End로 첫/끝 이동을 지원합니다.
+- 비활성화된 세그먼트는 키보드 이동에서 건너뜁니다.
+
+---
+
+## Tab
+
+`value` + `onChange`를 받는 controlled 탭 컴포넌트입니다. WAI-ARIA `tablist` 패턴을 따르며 키보드(ArrowLeft/Right, Home, End)로 탐색할 수 있습니다. 탭이 뷰포트를 초과하면 드래그 가능한 캐러셀이 자동으로 활성화됩니다.
+
+```tsx
+import { useState } from "react";
+import { Tab } from "@idbrnd/design-system";
+import type { TabItem } from "@idbrnd/design-system";
+
+const items: TabItem[] = [
+  { value: "all", label: "전체" },
+  { value: "active", label: "진행 중" },
+  { value: "done", label: "완료" },
+];
+
+function TabExample() {
+  const [tab, setTab] = useState("all");
+
+  return <Tab items={items} value={tab} onChange={setTab} />;
+}
+```
+
+**뱃지 + 숫자 뱃지**
+
+```tsx
+const items: TabItem[] = [
+  { value: "inbox", label: "받은 메시지" },
+  { value: "unread", label: "안읽은 메시지", badge: true },
+  { value: "sent", label: "보낸 메시지", numberBadge: 12 },
+];
+
+<Tab items={items} value={tab} onChange={setTab} />;
+```
+
+**fill 모드 (균등 분배)**
+
+```tsx
+<Tab items={items} value={tab} onChange={setTab} resize="fill" />
+```
+
+**왼쪽 패딩 + trailing 아이콘 버튼**
+
+```tsx
+<Tab
+  items={items}
+  value={tab}
+  onChange={setTab}
+  horizontalPadding
+  trailingIcon={
+    <button type="button" onClick={handleAdd}>
+      <PlusIcon />
+    </button>
+  }
+/>
+```
+
+**비활성화 탭 포함**
+
+```tsx
+const items: TabItem[] = [
+  { value: "a", label: "사용 가능" },
+  { value: "b", label: "비활성화", disabled: true },
+  { value: "c", label: "사용 가능" },
+];
+```
+
+| Prop                | 타입                                 | 기본값     | 설명                                                                   |
+| ------------------- | ------------------------------------ | ---------- | ---------------------------------------------------------------------- |
+| `items`             | `TabItem[]`                          | —          | **(필수)** 탭 목록                                                     |
+| `value`             | `string \| number`                   | —          | **(필수)** 현재 선택된 탭 값                                           |
+| `onChange`          | `(value: string \| number) => void`  | —          | 탭 변경 콜백                                                           |
+| `size`              | `"large"` \| `"medium"` \| `"small"` | `"medium"` | 크기. 폰트 기준: large = heading-1, medium = heading-2, small = body-1 |
+| `resize`            | `"hug"` \| `"fill"`                  | `"hug"`    | `hug`: 탭이 자연 폭, `fill`: 탭이 컨테이너를 균등 분배                 |
+| `horizontalPadding` | `boolean`                            | `false`    | `true` 시 왼쪽 20px 패딩 적용                                          |
+| `trailingIcon`      | `ReactNode`                          | —          | 탭 목록 오른쪽에 고정 노출되는 아이콘 슬롯. `resize="hug"`일 때만 적용 |
+| `label`             | `string`                             | —          | 스크린 리더용 그룹 레이블 (`aria-label`)                               |
+| `customStyle`       | `CSSProperties`                      | —          | 추가 인라인 스타일                                                     |
+
+**`TabItem`**
+
+| 필드          | 타입               | 설명                                                                                  |
+| ------------- | ------------------ | ------------------------------------------------------------------------------------- |
+| `value`       | `string \| number` | **(필수)** 탭 고유 값                                                                 |
+| `label`       | `ReactNode`        | **(필수)** 탭 레이블                                                                  |
+| `badge`       | `boolean`          | `true` 시 레이블 우측 상단에 빨간 점(dot) 뱃지 표시                                   |
+| `numberBadge` | `number`           | 양수일 때 레이블 우측에 숫자 뱃지 표시. 999 초과 시 "999+"로 클리핑. `badge`보다 우선 |
+| `disabled`    | `boolean`          | 비활성화. 키보드 탐색에서도 건너뜀                                                    |
+
+유의사항:
+
+- 탭이 뷰포트를 초과하면 드래그 가능한 캐러셀이 자동으로 활성화되고, 선택된 탭으로 자동 스크롤됩니다.
+- `resize="fill"` 모드에서도 탭 개수가 많아 초과하면 캐러셀이 활성화됩니다.
+- `trailingIcon`은 `resize="hug"`일 때만 렌더링됩니다.
+- `value`에 해당하는 item이 없으면 슬라이딩 인디케이터가 숨겨지고, 첫 번째 활성 탭에 키보드 포커스가 유지됩니다.
+- `numberBadge={0}` 또는 음수이면 뱃지가 표시되지 않습니다.
+
+---
+
 ## 테이블
 
 `TableContainer`, `Table`, `Pagination` 3개의 컴포넌트로 구성됩니다. 내부적으로 [TanStack Table v8](https://tanstack.com/table/v8)을 사용하므로 `@tanstack/react-table` 패키지가 필요합니다.
@@ -1505,6 +1702,19 @@ import type {
   DropdownType,
   DropdownAlign,
 
+  // SegmentedControl
+  SegmentedControlProps,
+  SegmentedControlVariant,
+  SegmentedControlType,
+  SegmentedControlSize,
+  SegmentedControlItem,
+
+  // Tab
+  TabProps,
+  TabItem,
+  TabSize,
+  TabResize,
+
   // Table
   TableProps,
   TableVariant,

package/dist/components/SegmentedControl/SegmentedControl.d.ts

@@ -0,0 +1,27 @@
+import { type CSSProperties, type ReactNode } from "react";
+export type SegmentedControlVariant = "basic" | "icon";
+export type SegmentedControlType = "fill" | "outlined";
+export type SegmentedControlSize = "small" | "medium" | "large";
+export interface SegmentedControlItem {
+    value: string;
+    label?: ReactNode;
+    icon?: ReactNode;
+    disabled?: boolean;
+    /** variant="icon"일 때 스크린 리더용 레이블 */
+    ariaLabel?: string;
+}
+export interface SegmentedControlProps {
+    variant?: SegmentedControlVariant;
+    type?: SegmentedControlType;
+    size?: SegmentedControlSize;
+    /** basic variant에서 icon을 함께 표시할지 여부 */
+    icon?: boolean;
+    /** 스크린 리더용 그룹 레이블 */
+    label?: string;
+    items: SegmentedControlItem[];
+    value: string;
+    onChange?: (value: string) => void;
+    customStyle?: CSSProperties;
+}
+declare function SegmentedControl({ variant, type, size, icon, label, items, value, onChange, customStyle, }: SegmentedControlProps): import("react/jsx-runtime").JSX.Element;
+export default SegmentedControl;

package/dist/components/Tab/Tab.d.ts

@@ -0,0 +1,23 @@
+import { type CSSProperties, type ReactNode } from "react";
+export type TabSize = "large" | "medium" | "small";
+export type TabResize = "hug" | "fill";
+export interface TabItem {
+    value: string | number;
+    label: ReactNode;
+    badge?: boolean;
+    numberBadge?: number;
+    disabled?: boolean;
+}
+export interface TabProps {
+    resize?: TabResize;
+    size?: TabSize;
+    items: TabItem[];
+    value: string | number;
+    onChange?: (value: string | number) => void;
+    horizontalPadding?: boolean;
+    trailingIcon?: ReactNode;
+    label?: string;
+    customStyle?: CSSProperties;
+}
+declare function Tab({ items, value, onChange, size, resize, horizontalPadding, trailingIcon, label, customStyle, }: TabProps): import("react/jsx-runtime").JSX.Element;
+export default Tab;

package/dist/index.d.ts

@@ -54,6 +54,10 @@ export type { FilterChipProps } from "./components/Chip/FilterChip/FilterChip";
 export type { FilterBarProps, FilterBarSize, } from "./components/Chip/FilterBar/FilterBar";
 export { default as Tooltip } from "./components/Tooltip/Tooltip";
 export type { TooltipProps, TooltipPosition, TooltipVariant, TooltipTrigger, TooltipContent, } from "./components/Tooltip/Tooltip.types";
+export { default as Tab } from "./components/Tab/Tab";
+export type { TabProps, TabItem, TabSize, TabResize, } from "./components/Tab/Tab";
+export { default as SegmentedControl } from "./components/SegmentedControl/SegmentedControl";
+export type { SegmentedControlProps, SegmentedControlVariant, SegmentedControlType, SegmentedControlSize, SegmentedControlItem, } from "./components/SegmentedControl/SegmentedControl";
 export { default as Table } from "./components/Table/Table";
 export type { TableProps, TableVariant, } from "./components/Table/Table.types";
 export { default as TableContainer } from "./components/Table/TableContainer";