@idbrnd/design-system 1.8.0 → 1.10.0

package/README.md

@@ -1,6 +1,6 @@
 # @idbrnd/design-system
 
-![Version](https://img.shields.io/badge/version-1.7.3-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` 패키지가 필요합니다.
@@ -1211,22 +1309,29 @@ const table = useReactTable({
   emptyTitle="데이터가 없습니다"
   emptyDescription="새 항목을 추가해 주세요"
 />
+
+// 최대 행 수 제한 (초과 시 tbody 세로 스크롤, 헤더 고정)
+<Table table={table} maxRows={10} />
 ```
 
-| Prop               | 타입                        | 기본값     | 설명                                                          |
-| ------------------ | --------------------------- | ---------- | ------------------------------------------------------------- |
-| `table`            | `Table<TData>`              | —          | `useReactTable()`로 생성한 TanStack Table 인스턴스 (필수)     |
-| `variant`          | `"normal"` \| `"content"`   | `"normal"` | 테이블 스타일 변형                                            |
-| `selectable`       | `boolean`                   | `false`    | 첫 번째 컬럼에 체크박스 표시. `enableRowSelection` 설정 필요  |
-| `interactive`      | `boolean`                   | `false`    | 행 hover/focus/pressed 인터랙션 활성화                        |
-| `onRowClick`       | `(row: Row<TData>) => void` | —          | 행 클릭 콜백. 제공 시 체크박스 없이도 행에 인터랙션 효과 적용 |
-| `loading`          | `boolean`                   | `false`    | 로딩 스켈레톤 표시                                            |
-| `skeletonRowCount` | `number`                    | `5`        | 로딩 스켈레톤 행 수                                           |
-| `emptyContent`     | `ReactNode`                 | —          | 데이터 없을 때 표시할 커스텀 콘텐츠 (전체 오버라이드)         |
-| `emptyTitle`       | `string`                    | —          | 빈 상태 제목                                                  |
-| `emptyDescription` | `string`                    | —          | 빈 상태 설명                                                  |
-| `customStyle`      | `CSSProperties`             | —          | 추가 인라인 스타일                                            |
-| `className`        | `string`                    | —          | 추가 클래스명                                                 |
+| Prop                     | 타입                             | 기본값     | 설명                                                                        |
+| ------------------------ | -------------------------------- | ---------- | --------------------------------------------------------------------------- |
+| `table`                  | `Table<TData>`                   | —          | `useReactTable()`로 생성한 TanStack Table 인스턴스 (필수)                   |
+| `variant`                | `"normal"` \| `"content"`        | `"normal"` | 테이블 스타일 변형                                                          |
+| `selectable`             | `boolean`                        | `false`    | 첫 번째 컬럼에 체크박스 표시. `enableRowSelection` 설정 필요                |
+| `interactive`            | `boolean`                        | `false`    | 행 hover/focus/pressed 인터랙션 활성화                                      |
+| `onRowClick`             | `(row: Row<TData>) => void`      | —          | 행 클릭 콜백. 제공 시 체크박스 없이도 행에 인터랙션 효과 적용               |
+| `loading`                | `boolean`                        | `false`    | 로딩 스켈레톤 표시                                                          |
+| `skeletonRowCount`       | `number`                         | `5`        | 로딩 스켈레톤 행 수                                                         |
+| `emptyContent`           | `ReactNode`                      | —          | 데이터 없을 때 표시할 커스텀 콘텐츠 (전체 오버라이드)                       |
+| `emptyTitle`             | `string`                         | —          | 빈 상태 제목                                                                |
+| `emptyDescription`       | `string`                         | —          | 빈 상태 설명                                                                |
+| `customStyle`            | `CSSProperties`                  | —          | 추가 인라인 스타일                                                          |
+| `className`              | `string`                         | —          | 추가 클래스명                                                               |
+| `maxRows`                | `number`                         | —          | 표시할 최대 행 수. 초과 시 세로 스크롤, 헤더는 항상 고정                    |
+| `accordion`              | `boolean`                        | `false`    | 아코디언 토글 컬럼 활성화. `canExpand`·`renderAccordionContent`와 함께 사용 |
+| `canExpand`              | `(row: Row<TData>) => boolean`   | —          | 쉐브론을 표시할 행 결정. 미제공 시 모든 행에 쉐브론 표시                    |
+| `renderAccordionContent` | `(row: Row<TData>) => ReactNode` | —          | 펼쳐진 행의 콘텐츠. 최초 열릴 때 1회 호출 후 DOM에 유지                     |
 
 **단일 행 선택**
 
@@ -1251,6 +1356,55 @@ const table = useReactTable({
 });
 ```
 
+**아코디언 (행 펼치기)**
+
+쉐브론 버튼 클릭 시 행 하단에 콘텐츠를 슬라이드 애니메이션으로 펼칩니다.
+
+```tsx
+const table = useReactTable({
+  data,
+  columns,
+  getCoreRowModel: getCoreRowModel(),
+  getRowId: (row) => String(row.id), // 정렬·필터 사용 시 필수
+});
+
+<Table
+  table={table}
+  accordion
+  canExpand={(row) => !!row.original.hasDetail} // 쉐브론 표시 여부를 가볍게 판단
+  renderAccordionContent={(
+    row, // 실제 콘텐츠는 펼쳐질 때만 렌더
+  ) => <DetailPanel data={row.original} />}
+/>;
+```
+
+- `canExpand`로 쉐브론 표시 여부를 결정하고, `renderAccordionContent`는 행이 최초로 펼쳐질 때 한 번만 호출됩니다. 이후 닫혀도 DOM에 유지되어 재렌더 없이 부드럽게 닫힙니다.
+- 쉐브론 버튼은 키보드 Tab+Enter 동작과 `aria-expanded` / `aria-controls`를 지원합니다.
+
+**중첩 테이블 패턴**
+
+```tsx
+<Table
+  table={parentTable}
+  accordion
+  canExpand={(row) => row.original.orderCount > 0}
+  renderAccordionContent={(row) => <OrderTable userId={row.original.id} />}
+/>;
+
+function OrderTable({ userId }: { userId: number }) {
+  const table = useReactTable({
+    data: getOrders(userId),
+    columns,
+    getCoreRowModel: getCoreRowModel(),
+  });
+  return (
+    <TableContainer variant="content">
+      <Table table={table} variant="content" maxRows={6} />
+    </TableContainer>
+  );
+}
+```
+
 ---
 
 ### Pagination
@@ -1449,6 +1603,13 @@ import type {
   DropdownType,
   DropdownAlign,
 
+  // SegmentedControl
+  SegmentedControlProps,
+  SegmentedControlVariant,
+  SegmentedControlType,
+  SegmentedControlSize,
+  SegmentedControlItem,
+
   // Table
   TableProps,
   TableVariant,
@@ -1470,5 +1631,6 @@ import type {
 - `Table`은 `@tanstack/react-table`의 `useReactTable()`로 생성한 인스턴스를 필수로 받습니다. TanStack Table을 별도 설치해야 합니다.
 - `TableContainer`의 `variant`는 `Table`의 `variant`와 반드시 동일하게 맞춰야 레이아웃이 올바르게 적용됩니다.
 - `Table`에서 `selectable` 사용 시 `useReactTable`에 `enableRowSelection`, `state.rowSelection`, `onRowSelectionChange`를 함께 설정해야 합니다.
+- `Table`에서 `accordion` 사용 시 정렬·필터 기능과 함께 쓴다면 `useReactTable`에 `getRowId: (row) => String(row.id)`를 설정해야 합니다. 기본값(배열 인덱스)은 정렬 변경 시 엉뚱한 행이 펼쳐진 상태가 됩니다.
 - `Pagination`에서 서버사이드 페이지네이션을 사용할 경우 `pageCount`를 서버 응답 기준으로 직접 계산해 전달해야 합니다.
 - CSS 변수/타이포그래피를 포함한 스타일을 위해 `@idbrnd/design-system/style.css` import를 권장합니다.

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/Table/Table.d.ts

@@ -1,5 +1,5 @@
 import type { TableProps, TableVariant } from "./Table.types";
 export type { TableVariant };
 export type { TableProps };
-declare function Table<TData>({ table, variant, selectable, interactive, loading, skeletonRowCount, emptyContent, emptyTitle, emptyDescription, customStyle, className, onRowClick, }: TableProps<TData>): import("react/jsx-runtime").JSX.Element;
+declare function Table<TData>({ table, variant, selectable, interactive, loading, skeletonRowCount, emptyContent, emptyTitle, emptyDescription, customStyle, className, onRowClick, accordion, canExpand, renderAccordionContent, maxRows, }: TableProps<TData>): import("react/jsx-runtime").JSX.Element;
 export default Table;

package/dist/components/Table/Table.types.d.ts

@@ -1,7 +1,7 @@
 import type { CSSProperties, ReactNode } from "react";
 import type { Row, Table } from "@tanstack/react-table";
 export type TableVariant = "normal" | "content";
-export interface TableProps<TData> {
+interface BaseTableProps<TData> {
     /** useReactTable()로 생성한 TanStack Table 인스턴스 */
     table: Table<TData>;
     /** 테이블 스타일 변형
@@ -35,4 +35,34 @@ export interface TableProps<TData> {
     customStyle?: CSSProperties;
     /** 추가 클래스명 */
     className?: string;
+    /** 표시할 최대 행 수. 초과 시 세로 스크롤 발생. 헤더는 항상 고정 */
+    maxRows?: number;
 }
+type AccordionProps<TData> = {
+    accordion?: false;
+    canExpand?: never;
+    renderAccordionContent?: never;
+} | {
+    /** 행마다 아코디언 토글(쉐브론) 컬럼을 활성화할지 여부.
+     * `renderAccordionContent`를 함께 제공해야 동작합니다.
+     */
+    accordion: true;
+    /** 행마다 쉐브론(토글)을 표시할지 결정하는 함수.
+     * 미제공 시 모든 행에 토글 표시.
+     * renderAccordionContent 호출을 펼쳐진 행으로만 제한하므로
+     * 콘텐츠 생성 비용이 클 때 반드시 제공하세요.
+     */
+    canExpand?: (row: Row<TData>) => boolean;
+    /** 확장된 행에 렌더링할 콘텐츠.
+     * 행이 펼쳐질 때 해당 row를 인수로 받아 ReactNode를 반환.
+     *
+     * **주의 — row.id 안정성**: TanStack Table은 기본적으로 배열 인덱스를
+     * row.id로 사용합니다. 정렬·필터 변경 시 같은 id가 다른 데이터를 가리켜
+     * 엉뚱한 행이 열린 상태가 됩니다.
+     * accordion 사용 시 useReactTable에 반드시
+     * `getRowId: (originalRow) => originalRow.id` 를 설정하세요.
+     */
+    renderAccordionContent: (row: Row<TData>) => ReactNode;
+};
+export type TableProps<TData> = BaseTableProps<TData> & AccordionProps<TData>;
+export {};

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";