@lucian-seo/lucian-ui 0.1.4 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,127 @@
1
+ # DataGrid 전체 기능
2
+
3
+ `features="all"`을 지정하면 TanStack Table v9의 정식 기능 17개와 행·열 가상 스크롤을 제공합니다.
4
+ `features`를 생략하면 기존 controlled API 동작을 유지합니다.
5
+ 갤러리의 첫 예제에서 모든 기능, 트리·상세, 병합, 10,000행·201열, 서버 처리 예제를 전환합니다.
6
+
7
+ ```tsx
8
+ import { DataGrid } from '@lucian-seo/lucian-ui/extended';
9
+ import type { DataGridColumn, DataGridViewState } from '@lucian-seo/lucian-ui/extended';
10
+ import '@lucian-seo/lucian-ui/styles.css';
11
+
12
+ const columns: DataGridColumn<Order>[] = [
13
+ { id: 'name', header: '이름', cell: row => row.name, accessor: row => row.name, hideable: false },
14
+ { id: 'team', header: '팀', cell: row => row.team, filter: 'select' },
15
+ { id: 'amount', header: '금액', cell: row => row.amount, numeric: true, filter: 'number', aggregation: ['sum', 'mean'] },
16
+ ];
17
+ <DataGrid rows={orders} columns={columns} rowKey={row => row.id} label="주문" features="all" />
18
+ ```
19
+
20
+ ## 기능과 조작
21
+
22
+ | 정식 기능 | API | 화면 조작 |
23
+ |---|---|---|
24
+ | Column visibility | `state.hiddenColumns` | 열 목록 체크박스·열 메뉴 |
25
+ | Column ordering | `state.columnOrder` | 헤더 드래그 또는 열 메뉴의 앞으로·뒤로 이동 |
26
+ | Column sizing | 열 `size`·`minSize`·`maxSize`, `state.columnSizes` | 조절한 너비 유지·초기화 |
27
+ | Column resizing | `columnResizing` | 헤더 끝 핸들 드래그·터치 또는 핸들에 포커스 후 방향키 |
28
+ | Column pinning | `state.columnPinning: {start,end}` | 열 메뉴에서 좌우 복수 열 고정·해제 |
29
+ | Column filtering | `state.filters`, 열 `filter`·`filterOperator`·`parseFilter` | 텍스트·선택·숫자 범위 필터 |
30
+ | Global filtering | `state.search` | 도구 모음 검색 |
31
+ | Column faceting | `faceting`, `facets`·`ranges` | 선택 필터의 값별 개수·숫자 범위 플레이스홀더 |
32
+ | Row sorting | `state.sorting`, `multiSort`, 열 `sortType` | 헤더 클릭·Shift+클릭·열 메뉴 |
33
+ | Row selection | `state.selectedKeys` 또는 기존 `selectedKeys/onSelectedChange` | 체크박스·Space. 전체 선택은 현재 페이지에 한정 |
34
+ | Row pagination | `state.pagination`, `pageSizes` | 페이지 번호·이전/다음·페이지당 행 수 |
35
+ | Column grouping | `state.grouping` | 열 메뉴에서 그룹 추가·해제 |
36
+ | Row aggregation | 열 `aggregation`, 서버 `totals` | 그룹 행과 footer의 실제 집계 |
37
+ | Row expanding | `state.expanded`, `getSubRows`, `renderDetail` | 펼치기 버튼·Enter·모두 펼치기 |
38
+ | Row pinning | `state.rowPinning: {top,bottom}` | 행 메뉴에서 위·아래 고정·해제 |
39
+ | Cell selection | `state.cellSelection` | 드래그·Shift+클릭·Shift+방향키, Ctrl+A, Ctrl+Space로 범위 추가·제외 |
40
+ | Cell spanning | 열 `spanRows`·`spanColumns`, `cellSpanning` | 같은 값의 행 병합·조건부 열 병합 |
41
+
42
+ 추가로 fuzzy 검색, 키보드 이동, Ctrl+C의 TSV 복사, 셀 편집·IME 이벤트 처리, 저장 중·실패·초안 복구,
43
+ 로딩·빈 결과·오류·이전 결과 유지, 행·열 가상 스크롤을 제공합니다.
44
+ 실험적 Worker API와 사용자가 작성하는 custom plugin은 이 정식 기능 목록에 포함하지 않습니다.
45
+
46
+ ## 상태와 처리 위치
47
+
48
+ `features`에는 `"all"` 대신 설정 객체를 전달할 수 있습니다.
49
+ 각 기능은 기본적으로 켜져 있으며 해당 옵션을 `false`로 지정해 조작 UI를 끕니다.
50
+ 행 가상화는 기존 `virtualize` prop, 열 가상화는 `features.columnVirtualization`으로 제어합니다.
51
+
52
+ | 설정 | 의미 |
53
+ |---|---|
54
+ | `processing: 'client'` | 기본값. 전달한 전체 데이터에 필터→그룹→정렬→펼치기→페이지를 적용합니다 |
55
+ | `processing: 'server'` | 전달한 페이지 순서를 유지합니다. 검색·정렬·필터·그룹·집계·페이지의 처리는 호출자가 맡습니다 |
56
+ | `state: Partial<DataGridViewState>` | 지정한 필드만 controlled로 동작합니다 |
57
+ | `defaultState` | 나머지 내부 상태의 초기값입니다. `createDataGridViewState(seed)`로 전체 초기 상태를 만들 수도 있습니다 |
58
+ | `onStateChange(next)` | 다음 전체 상태를 전달합니다. 서버 요청·보기 저장에 사용합니다 |
59
+ | `rowCount` | 서버 전체 결과 수입니다. 현재 페이지 길이를 전달하지 않습니다 |
60
+ | `facets`·`ranges`·`totals` | 서버에서 계산한 후보 값·범위·집계입니다. 현재 페이지로 전체 결과를 추정하지 않습니다 |
61
+
62
+ 기존 `sort`·`hiddenColumns`·`selectedKeys` prop을 함께 주면 그 필드의 기존 prop이 우선합니다.
63
+ 다중 정렬과 복합 보기 상태를 사용할 때는 `features.state/onStateChange`를 사용합니다.
64
+ `state`로 지정한 필드는 콜백에서 새 값을 다시 전달해야 화면에 반영됩니다.
65
+
66
+ 서버 모드에서는 요청 취소·응답 순서·권한·충돌 처리를 호출자가 구현해야 합니다.
67
+ 갤러리 서버 예제는 합성 데이터를 지연 처리하는 예제이며 실제 업무 API 연결이 아닙니다.
68
+ 예제가 제공하는 서버 계약은 검색·필터·정렬·페이지입니다. 그룹·집계를 처리할 서버가 없는 이 예제에서는
69
+ 해당 조작을 끕니다. DataGrid API는 서버 그룹·집계 상태와 사전 계산 값을 받을 수 있습니다.
70
+
71
+ ## 열 데이터와 표시
72
+
73
+ | 열 설정 | 의미 |
74
+ |---|---|
75
+ | `cell(row)` | 기존 자체 UI 렌더링을 유지합니다 |
76
+ | `accessor(row)` | 정렬·필터·그룹·집계에 쓰는 원시 데이터입니다. Badge 등의 ReactNode와 구분합니다 |
77
+ | `value(row)` | 기존 문자열 편집 값입니다. accessor가 없으면 데이터 값으로도 사용합니다 |
78
+ | `size/minSize/maxSize` | Table이 관리하는 px 너비입니다. 조작값은 자체 CSS custom property로 전달합니다 |
79
+ | `width` | 기존 sm/md/lg/grow 기본 너비를 계속 받습니다 |
80
+ | `headerGroup` | 같은 이름의 열을 그룹 헤더 아래 배치합니다 |
81
+ | `filter` | text/select/number/fuzzy 또는 false입니다 |
82
+ | `filterOperator` | TanStack의 정식 built-in filter 함수 이름과 fuzzy를 지원합니다 |
83
+ | `filterOptions` | 서버 조회 등에서 선택 필터의 고정 옵션을 지정합니다 |
84
+ | `parseFilter(text)` | 배열·날짜 등 복합 필터 값을 만듭니다. controlled filters로 직접 전달할 수도 있습니다 |
85
+ | `sortType` | auto 또는 TanStack built-in sort 함수 이름입니다. Date accessor는 auto/datetime을 사용합니다 |
86
+ | `aggregation` | sum/min/max/mean/median/count/uniqueCount/first/last/extent/unique 또는 그 배열입니다 |
87
+ | `spanRows` | true이면 인접한 동일 값, 함수이면 `(anchor,row)`가 true인 행을 병합합니다 |
88
+ | `spanColumns` | 숫자 또는 `(row)=>number`입니다. 고정 열의 반대편 영역까지 합치지 않습니다 |
89
+
90
+ 필터 후보 개수와 집계는 필터를 반영한 데이터 기준이며 현재 렌더링한 가상 행의 합계가 아닙니다.
91
+ 기존 `footer(rows)` callback의 rows는 전달한 원본 rows입니다. 전체 결과의 집계가 필요하면 aggregation이나 서버 totals를 사용합니다.
92
+
93
+ ## 키보드와 편집
94
+
95
+ | 입력 | 동작 |
96
+ |---|---|
97
+ | 방향키·PageUp/Down | 현재 페이지의 셀 이동. 병합에 가려진 위치는 건너뜁니다 |
98
+ | Home/End | 현재 행의 처음·마지막 셀 |
99
+ | Ctrl/Meta+Home/End | 현재 페이지의 처음·마지막 셀 |
100
+ | Shift+방향키 | 셀 범위 확장 |
101
+ | Ctrl/Meta+Space | 현재 셀을 범위에 추가하거나 제외 |
102
+ | Ctrl/Meta+A | 현재 Table 모델의 모든 선택 가능한 셀 선택 |
103
+ | Ctrl/Meta+C | 선택 값을 TSV로 복사 |
104
+ | Enter/F2 | 편집 가능한 셀의 편집 시작. 그 외에는 행 펼치기 또는 행 열기 |
105
+ | 편집 중 Enter/Escape | 저장 요청·취소. IME 조합 Enter는 편집을 끝내지 않습니다 |
106
+ | Space | 행 선택·해제 |
107
+ | 너비 핸들 방향키 | 열 너비 조절 |
108
+
109
+ 셀은 하나의 roving tab stop을 사용합니다. Checkbox·Menu·Input 등의 네이티브 조작은 유지합니다.
110
+ 그룹 선택은 실제 데이터 ID만 전달합니다. 다른 페이지의 선택은 유지합니다.
111
+ 편집 중인 행은 가상 범위 밖에서도 DOM에 남습니다. 스크롤만으로 저장하지 않습니다.
112
+ 저장 실패의 `cellState.draft`를 유지하면 입력 복구 버튼으로 해당 페이지·열·편집기를 다시 엽니다.
113
+ 저장과 validation은 기존 `onCellCommit`의 호출자가 처리합니다. DataGrid가 서버 저장 성공을 가정하지 않습니다.
114
+
115
+ ## 가상화와 지원 범위
116
+
117
+ - 브라우저 찾기·스크린 리더 탐색은 DOM에 있는 행·열에 한정됩니다. 전체 결과 검색 UI를 사용하거나 가상화를 끕니다.
118
+ - 병합 셀의 anchor는 가상 범위 밖에서도 유지합니다. 병합을 유지하기 위해 일부 행·열이 추가로 렌더링될 수 있습니다.
119
+ - 실제 높이를 측정하며, 처음 보는 행의 추정 높이가 보정될 수 있습니다.
120
+ - 열 너비·고정 offset·전체 크기는 자체 CSS custom property입니다. inline height/width/transform/색을 생성하지 않습니다.
121
+ - 평면 데이터는 grid, 그룹·트리·상세 데이터는 treegrid를 사용합니다.
122
+ - 서버의 전체 행 수가 없거나 서버 상세 행 수가 알려지지 않으면 ARIA 전체 수는 -1(미상)입니다.
123
+ - 선택 데이터가 매우 크면 복사할 때 그 범위의 값을 읽습니다. DOM 가상화와 데이터 다운로드·메모리 사용은 별개입니다.
124
+ - 실제 OS IME·스크린 리더·실제 모바일 기기 검증 결과와 Windows Chrome 자동 검사를 구분합니다.
125
+
126
+ 공식 범위는 [TanStack Features](https://tanstack.com/table/latest/docs/guide/features)와
127
+ [Virtual API](https://tanstack.com/virtual/latest/docs/api/virtualizer)를 기준으로 했습니다.
package/docs/README.md ADDED
@@ -0,0 +1,37 @@
1
+ # 문서 지도
2
+
3
+ ## 현재
4
+
5
+ | 파일 | 무엇 |
6
+ |---|---|
7
+ | `../AGENTS.md` | 작업 규칙. 세션을 시작하면 먼저 읽으세요 |
8
+ | `../PROJECT_STATE.md` | 지금 상태와 정확한 다음 행동 |
9
+ | `COMPONENTS.md` | **도출 기록.** 무엇을 왜 만들기로 했는지, Mobbin 근거, 층위별 규칙, 아래 층위에 요청한 것. 81개 시점에 작성했고 현재 목록이 아닙니다 |
10
+ | `COMPONENT-AUDIT.md` | 갓코드 점검. 층 뒤집힘 0건, `DataGrid` 하나, 목록 키보드 모델 네 벌 |
11
+ | `NPM-PUBLISH.md` | 공개 npm 계정·라이선스·첫 등록과 GitHub Actions 배포 절차 |
12
+ | `FOUNDATION.md` | 토큰 · 그리드 · 글꼴 |
13
+ | `CHARTS.md` | **차트는 채택자가 ECharts로 가져옵니다.** 사용처는 `MetricCard`의 `chart` 슬롯 하나이고, 토큰을 ECharts 테마로 옮기는 방법을 적었습니다 |
14
+ | `DESIGN.md` | **어떤 느낌이어야 하는가.** 규칙이 아니라 의도이고, 주장은 전부 CSS를 세어서 나왔고, 셀 때마다 갱신합니다 |
15
+ | `VISUAL-INTERACTION-PLAN.md` | 시각·인터랙션 확장 계획. 단계는 모두 끝났습니다. 8절에 **하지 않기로 한 것**과 그중 결정을 뒤집은 것, 10절에 **장식 층**의 기준과 도출 과정을 적었습니다 |
16
+ | `PRODUCTION-READINESS.md` | 프로덕션까지 남은 것. Mobbin 실제 제품 화면 9장과 저장소 측정 |
17
+
18
+ ## 소스 문서
19
+
20
+ 컴포넌트 목록이 여기서 나왔습니다. 아직 만들지 않은 것이 남아 있습니다 — 음성 시각화,
21
+ 전사 동기화, 세션 제어 바.
22
+
23
+ - `음성-특화-컴포넌트.md`
24
+ - `최신-UI-신규-컴포넌트.md`
25
+ - `추가-컴포넌트-종류.md`
26
+ - `GLASS.md` — Apple Liquid Glass. **받아 온 대화록이고 이 저장소의 규약이 아닙니다.**
27
+ 무엇을 따르고 무엇을 따르지 않았는지는 `VISUAL-INTERACTION-PLAN.md` 8절에 있습니다
28
+
29
+ ## 이전 작업선
30
+
31
+ `../archive/docs/`에 v1의 문서가 있습니다 — `foundry/`의 Golden Set · Candidate · Atlas ·
32
+ QUALITY-GATE 규약, `experience-strategy.md`, `review-workflow.md`.
33
+
34
+ **현재 방향이 아닙니다.** 태그 `archive/v1-2026-08-24`.
35
+
36
+ - **`DESIGN.md`** — 이 라이브러리가 어떤 느낌이어야 하는가. 규칙이 아니라 의도이고,
37
+ 주장은 전부 CSS를 세어서 나왔고, 셀 때마다 갱신합니다.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lucian-seo/lucian-ui",
3
- "version": "0.1.4",
3
+ "version": "0.2.0",
4
4
  "description": "React components, design tokens, and layout foundations for Gwang-eon's products.",
5
5
  "type": "module",
6
6
  "repository": {
@@ -19,7 +19,8 @@
19
19
  ],
20
20
  "files": [
21
21
  "dist/lib",
22
- "README.md"
22
+ "README.md",
23
+ "docs/DATAGRID.md"
23
24
  ],
24
25
  "exports": {
25
26
  ".": {
@@ -67,6 +68,8 @@
67
68
  "@radix-ui/react-dropdown-menu": "^2.1.24",
68
69
  "@radix-ui/react-popover": "^1.1.23",
69
70
  "@radix-ui/react-tooltip": "^1.2.16",
71
+ "@tanstack/react-table": "9.3.1",
72
+ "@tanstack/react-virtual": "3.14.25",
70
73
  "lucide-react": "^1.32.0"
71
74
  },
72
75
  "peerDependencies": {
@@ -81,6 +84,7 @@
81
84
  "@types/react": "^19.2.0",
82
85
  "@types/react-dom": "^19.2.0",
83
86
  "@vitejs/plugin-react": "^6.1.0",
87
+ "axe-core": "4.14.0",
84
88
  "postcss": "^8.5.26",
85
89
  "react": "^19.2.8",
86
90
  "react-dom": "^19.2.8",