@idbrnd/design-system 1.9.0 → 1.10.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.10.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,7 @@ export default function App() {
   - [ChipGroup](#chipgroup)
   - [FilterChip](#filterchip)
   - [FilterBar](#filterbar)
+- [SegmentedControl](#segmentedcontrol)
 - [테이블](#테이블)
   - [TableContainer](#tablecontainer)
   - [Table](#table)
@@ -1118,6 +1119,103 @@ 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로 첫/끝 이동을 지원합니다.
+- 비활성화된 세그먼트는 키보드 이동에서 건너뜁니다.
+
+---
+
 ## 테이블
 
 `TableContainer`, `Table`, `Pagination` 3개의 컴포넌트로 구성됩니다. 내부적으로 [TanStack Table v8](https://tanstack.com/table/v8)을 사용하므로 `@tanstack/react-table` 패키지가 필요합니다.
@@ -1505,6 +1603,13 @@ import type {
   DropdownType,
   DropdownAlign,
 
+  // SegmentedControl
+  SegmentedControlProps,
+  SegmentedControlVariant,
+  SegmentedControlType,
+  SegmentedControlSize,
+  SegmentedControlItem,
+
   // 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/index.d.ts

@@ -54,6 +54,8 @@ 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 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";