@vmscloud/moz-ui-grid-vue 0.2.20 → 0.2.22

package/docs/manual/reference.md

@@ -227,6 +227,7 @@ grid.on('row:click', ({ rowIndex }) => {
 | `rowHeader` | `boolean \| RowHeaderConfig` | `false` | 좌측 행 헤더 컬럼(`_rowHeader`) 표시. `true`면 빈 셀(너비 40, 체크박스 트리거 시 체크박스), 객체면 `width`/`cellRenderer`/`headerRenderer`/`includeGroupRows`로 커스터마이즈 (→ [RowHeaderConfig](#rowheaderconfig)). `rowSelection.trigger`가 `'rowHeader'`/`'checkbox'`면 미지정이어도 자동 ON. (구 `showRowHeader` — deprecated alias 유지) |
 | `showStatusBar` | `boolean` | `true` | 상태 바 표시 |
 | `summaryRow` | `'none' \| 'pinnedTop' \| 'pinnedBottom'` | `'none'` | 집계(총합계) 행 표시 위치. `FieldDef.aggregate` 가 지정된 컬럼을 모아 core 가 행을 직접 소유하며, `getConfig()` 에 실려 레이아웃 프리셋으로 저장·복원된다. `'pinnedBottom'` 은 행이 뷰포트를 다 못 채우면 마지막 행 바로 아래, 넘치면 뷰포트 하단에 고정되며, 그룹·트리 펼침/접힘·필터·데이터 교체로 행 수가 바뀌면 위치를 다시 계산한다(데이터 행을 가리지 않음). `'pinnedTop'` 은 헤더 바로 아래에 고정되고 본문 행은 그 아래에서 시작한다 |
+| `nullsPosition` | `'last' \| 'first' \| 'natural'` | `'last'` | 정렬에서 빈 값(null/undefined) 위치 — 그리드 전체 적용. `'last'` 방향과 관계없이 맨 뒤(Excel·Wijmo 와 같음), `'first'` 맨 앞, `'natural'` 오름차순 앞·내림차순 뒤. 명시 정렬과 그룹 값·피벗 행/열 헤더 기본 순서에 모두 적용(정렬 없는 플랫·트리는 원본 순서). 실행 중 변경 `setNullsPosition()`. `getConfig()` 에 실리지만 래퍼 사용자 레이아웃에는 저장하지 않는다. 자세한 규칙은 [정렬에서 빈 값 위치](#정렬에서-빈-값-위치-nullsposition) |
 | `alternatingRows` | `boolean` | `false` | 줄무늬 행 스타일 |
 | `rowStyle` | `string` | — | 행 높이 alias: `height:Npx`만 추출 (일반 CSS 적용 아님). truthy `rowHeight`가 우선 |
 | `headerStyle` | `string` | — | 헤더 높이 alias: `height:Npx`만 추출 (일반 CSS 적용 아님). truthy `headerHeight`가 우선 |
@@ -839,6 +840,8 @@ grid.clearSearch();                    // 종료
 |---|---|---|
 | `repaintRow(rowId: RowId)` | `void` | `repaintRows([rowId])`의 단일 행 편의 함수 |
 | `getSummaryRow()` | `SummaryRowPosition` | 현재 합계 행 위치: `'none' \| 'pinnedTop' \| 'pinnedBottom'` |
+| `setNullsPosition(position: NullsPosition)` | `Promise<void>` | 정렬에서 빈 값 위치 변경(`'last' \| 'first' \| 'natural'`). 지금 화면 순서(정렬·그룹·피벗)를 다시 계산하고 서버 행 모델은 다시 요청한다. 정렬 상태·`sort:changed` 는 그대로. 허용 값이 아니면 `PS005` 경고 후 무시 |
+| `getNullsPosition()` | `NullsPosition` | 현재 빈 값 위치(기본 `'last'`) |
 | `registerShortcut(combo: string, handler: () => void \| Promise<void>)` | `Unsubscribe` | 단축키 등록. 같은 combo는 기존/기본 단축키를 덮어씀. 반환 해제 함수를 소비처 lifecycle에서 호출 |
 | `hasShortcut(combo: string)` | `boolean` | 해당 단축키 등록 여부 |
 
@@ -960,7 +963,7 @@ interface GridConfigExport {
 | `fields` 에 없는 컬럼 | baseline 값, 순서는 저장본 컬럼 뒤(baseline 순) |
 | `sorts`/`sortGroups`, `filters`/`filterGroups` | 생성 시점(빈 정렬·필터) |
 | `rowGroupConfig`, `columnGroups`, `treeConfig`, `masterDetailConfig` | 생성 시 config 값 |
-| UI 옵션(아래 목록), `summaryRow`, `locale`, `translations`, `rowModel`, `endReachedThresholdRows` | 생성 시 값(미지정이면 라이브러리 기본값) |
+| UI 옵션(아래 목록), `summaryRow`, `nullsPosition`, `locale`, `translations`, `rowModel`, `endReachedThresholdRows` | 생성 시 값(미지정이면 라이브러리 기본값) |
 | `mode` | 생성 시 모드 |
 | 피벗 하위 옵션(`rowFields`/`valueFields` 를 준 경우) | 라이브러리 기본값 — 피벗 정의는 `pivot.setConfig` 로 통째 교체되는 한 단위. `keep` 이면 현재 피벗 설정 값 유지 |
 
@@ -995,7 +998,7 @@ interface GridConfigExport {
 | **뷰 상태** | `sorts`, `filters` |
 | **서버/수동 row-model** | `rowModel`, `endReachedThresholdRows` |
 | **트리/디테일** | `treeConfig`, `masterDetailConfig` |
-| **UI 옵션** | `theme`, `rowHeight`, `headerHeight`, `rowSelection`, `cellSelection`, `cellSelectionImpliesRows`, `editable`, `tooltipMode`, `alternatingRows`, `showHeader`, `resizableColumns`, `reorderableColumns`, `rowHeader`, `reorderableRows`, `showDragHandleColumn`, `autoFitColumns`, `showStatusBar`, `summaryRow`, `locale`, `translations`, `keyFields` 등 |
+| **UI 옵션** | `theme`, `rowHeight`, `headerHeight`, `rowSelection`, `cellSelection`, `cellSelectionImpliesRows`, `editable`, `tooltipMode`, `alternatingRows`, `showHeader`, `resizableColumns`, `reorderableColumns`, `rowHeader`, `reorderableRows`, `showDragHandleColumn`, `autoFitColumns`, `showStatusBar`, `summaryRow`, `nullsPosition`, `locale`, `translations`, `keyFields` 등 |
 
 **제외되는 항목**
 
@@ -1688,7 +1691,7 @@ interface AggregateContext {
 - 함수형 컬럼 aggregate가 하나라도 있으면 선언된 문자열 컬럼 aggregate를 모두(숨김·배너 아래 컬럼 포함) 계산만 합니다. 이 값들은 배너 글자에 나오지 않습니다.
 - 함수형 aggregate는 프리셋(JSON)에 저장되지 않고 코드가 소유합니다 — `applyConfig`가 지우거나 문자열로 바꾸지 않으며, wrapper 집계 탭은 "사용자 함수"로 표시하고 변경을 막습니다.
 - **선택 영역 집계**(`rows.selectionAggregates()`·`selection:changed`의 `aggregates`·컨텍스트 메뉴): 함수형 컬럼은 그 컬럼 셀이 선택된 행들을 **하나의 그룹처럼** 보고 함수를 적용합니다. `columns[]` 항목은 `aggregate: 'custom'`, `value` = 함수 값(`formattedValue`는 그 컬럼 mask 적용), `count` = 숫자 셀 수(기존 의미)입니다. `ctx.sum('x')` 등은 선택 범위에 `x` 셀이 없어도(숨김 컬럼 포함) 선택된 **행** 기준이고 `ctx.group`은 없습니다. 읽을 수 있는 조합은 고정 합계 행과 같이 컬럼 정의의 문자열 `aggregate`이며, 미선언 조합은 `console.error`(PS312) 후 빈 값입니다. 화면 밖 선택 행·그룹/트리 모드(데이터 행만)·Worker 모드 모두 같은 값이고, 컬럼 전체 선택(Ctrl+Space/Ctrl+A)은 표시 중인 전체 데이터 행으로 계산합니다(이때만 행을 한 번 받아 옵니다). `total`(합계·평균·개수·최소·최대)은 기존대로 **선택 셀 값** 기준입니다. wrapper 컨텍스트 메뉴는 `custom`에 함수 라벨 없이 `헤더 값`만 표시합니다.
-- 그룹 정렬 `basis: 'aggregate'`와 그룹 결과 필터(`basis: 'aggregate'`·수식 `GROUP(id, "aggregate", by)`)는 `rowGroupConfig.aggregates`의 **함수형 항목도** 공개 ID로 참조할 수 있습니다. 엔진은 함수를 실행하지 않으므로 메인 스레드가 그룹별 함수 값을 계산해 엔진에 다시 질의합니다(필터 참조 시 필터 전 snapshot A 값 1회 + 정렬 참조 시 1회 추가 질의 — 대용량에서 그만큼 느려집니다). 오름/내림·null 위치(오름차순 맨 앞)는 문자열 집계 정렬과 같고, Main/Worker·lazy/dense 결과가 같으며 접기/펼치기·필터·편집 뒤에도 유지됩니다. 컬럼 정의 `aggregate`(자기 칸 집계)는 정렬·필터 ID로 참조할 수 없습니다(문자열·함수 모두 기존과 같음).
+- 그룹 정렬 `basis: 'aggregate'`와 그룹 결과 필터(`basis: 'aggregate'`·수식 `GROUP(id, "aggregate", by)`)는 `rowGroupConfig.aggregates`의 **함수형 항목도** 공개 ID로 참조할 수 있습니다. 엔진은 함수를 실행하지 않으므로 메인 스레드가 그룹별 함수 값을 계산해 엔진에 다시 질의합니다(필터 참조 시 필터 전 snapshot A 값 1회 + 정렬 참조 시 1회 추가 질의 — 대용량에서 그만큼 느려집니다). 오름/내림·null 위치(`nullsPosition`, 기본 맨 뒤)는 문자열 집계 정렬과 같고, Main/Worker·lazy/dense 결과가 같으며 접기/펼치기·필터·편집 뒤에도 유지됩니다. 컬럼 정의 `aggregate`(자기 칸 집계)는 정렬·필터 ID로 참조할 수 없습니다(문자열·함수 모두 기존과 같음).
 - `scope`가 붙은 `rowGroupConfig.aggregates` 항목이 있어도 그룹행 자기 칸 집계(컬럼 정의 `aggregate` — 문자열·함수)는 모든 레벨에 남습니다. scope는 배너 집계의 표시 레벨만 정합니다(자기 칸 컬럼의 `rowGroupConfig` 항목도 scope 단계 배너에만 나옵니다).
 
 ```ts
@@ -1747,12 +1750,40 @@ await grid.rowGroup.setConfig({
 저장본 0.4 → 0.5 마이그레이션은 옛 그룹 정렬 `column`/객체 `by`를 새 모델로 변환하고,
 피벗 `SortState.byValue`는 동일한 scalar 값 그대로 `by`로 개명합니다. 피벗 집계/정렬 의미는 변하지 않습니다.
 
-그룹 내부 데이터 행의 일반 정렬은 별도로 유지됩니다. 일반·계산 필드·그룹·트리·피벗 정렬에서
-null/undefined는 **오름차순(ASC)에서는 앞, 내림차순(DESC)에서는 뒤**에 위치합니다.
+그룹 내부 데이터 행의 일반 정렬은 별도로 유지됩니다.
+
+#### 정렬에서 빈 값 위치 (nullsPosition)
+
+일반·계산 필드·그룹·트리·피벗 정렬에서
+null/undefined(빈 값) 위치는 그리드 설정 **`nullsPosition`**이 정합니다(기본 `'last'`).
+
+| `nullsPosition` | 오름차순(ASC) | 내림차순(DESC) | 같은 동작 |
+|---|---|---|---|
+| `'last'` (기본) | 맨 뒤 | 맨 뒤 | Excel, Wijmo `sortNulls: Last`, SQL `NULLS LAST` |
+| `'first'` | 맨 앞 | 맨 앞 | SQL `NULLS FIRST` |
+| `'natural'` | 맨 앞 | 맨 뒤 | 빈 값을 가장 작은 값으로 봄 (AG Grid·MUI X 기본, 이전 moz-ui-grid 기본) |
+
+```ts
+// 예) amount = [2, null, 1]
+// 'last'    asc → 1, 2, null   desc → 2, 1, null
+// 'first'   asc → null, 1, 2   desc → null, 2, 1
+// 'natural' asc → null, 1, 2   desc → 2, 1, null
+const grid = new PureSheet(el, { ...config, nullsPosition: 'last' });
+await grid.setNullsPosition('first'); // 실행 중 변경 — 지금 화면 순서를 다시 계산(정렬 상태는 그대로)
+grid.getNullsPosition();              // 'first'
+```
+
+- 명시 정렬뿐 아니라 **정렬하지 않았을 때의 순서**에도 적용됩니다: 그룹 값 기본 순서(그룹 이름 오름차순),
+  피벗 행·열 헤더 기본 순서, 그룹 정렬(`basis: 'groupValue'`/`'aggregate'`), 피벗 후정렬, 필터 고유값 목록.
+  정렬이 없는 플랫·트리는 원본 순서를 유지합니다.
+- 그리드 전체에 하나만 둡니다(정렬 키·컬럼별 지정은 없음).
+- `getConfig()`/`applyConfig()` 왕복 대상입니다(UI 옵션 묶음). Vue 래퍼의 **사용자 레이아웃 프리셋(`useGridPreset`)에는 저장하지 않으며**,
+  프리셋을 불러와도 현재 값을 유지합니다.
+- 서버 행 모델은 요청 최상위의 `nullsPosition` 으로 받습니다(아래 `FetchRangeRequest`). 바꾸면 처음부터 다시 요청합니다.
+
 두 값이 모두 null/undefined이면 동률이며, 다음 정렬 키를 비교하고 모든 키가 같으면 기존 순서를 유지합니다.
 빈 문자열(`''`), 공백 문자열, `0`, `false`는 null/undefined로 취급하지 않습니다.
 `sortKey`가 있으면 원본 값이 아닌 변환된 키를 비교합니다.
-이는 이전 ASC 뒤/DESC 앞 기본정책의 변경이며, 저장된 정렬 방향에도 새 기본정책이 적용됩니다.
 wrapper 정렬 패널의 **그룹 정렬 → 정렬 기준**에서도
 ‘그룹 이름’을 선택할 수 있습니다. 정렬 규칙이 없을 때와 새 규칙을 추가할 때 모두
 **그룹 이름 오름차순**이 기본입니다. 기존에 저장한 하위 행 개수·집계 정렬은 그대로 유지됩니다.
@@ -3319,6 +3350,7 @@ interface EditorConfig {
   inputMask?: string;          // text 전용, 입력 마스크 (예: '99:99') — 표시 mask와 별개
   options?: EditorOption[] | CellObject[];  // dropdown/select/multiselect 옵션 (객체 값 열은 객체 배열만 줘도 됨 → FieldDef 의 "객체 값 열" 절)
   searchable?: boolean;        // 검색 활성화 (dropdown, multiselect)
+  showIcon?: boolean;          // dropdown 전용, 셀 끝 ▼ 상시 표시 (기본 true) — 아래 "드롭다운 셀 ▼"
   placeholder?: string;        // placeholder 텍스트
   dateFormat?: string;         // datepicker 포맷 (기본: 'yyyy-MM-dd')
   separator?: string;          // multiselect 구분자 (기본: ',')
@@ -3328,6 +3360,18 @@ interface EditorConfig {
 }
 ```
 
+**드롭다운 셀 ▼** (ITSM-2026-004445 버그 21) — `editor: { type: 'dropdown' }` 열의 데이터 셀 끝에 `<span class="ps-dropdown-icon">` 을 두고 글리프를 CSS `::before`(▼)로 그린다. 헤더 정렬·필터 아이콘과 같은 규약이라 모양은 `.ps-dropdown-icon::before` 를 덮어 바꾼다(Vue/React 래퍼는 moz-ui Select 쉐브론으로 덮는다). ▼ 를 클릭하면 더블클릭 없이 바로 목록이 열린다(Shift/Ctrl 클릭은 선택 확장만).
+
+| 조건 | ▼ |
+|---|---|
+| 그리드 `editable: true` + 편집 가능한 데이터 셀 | 보임 (그리드 컨테이너에 `ps-editable` 클래스) |
+| 그리드 `editable: false` | 숨김 (CSS) |
+| 열 `readonly` / `editable: false` / `editor.showIcon: false` | 만들지 않음 |
+| 읽기 전용 칸·행(`ps-cell-readonly` — 키 열 보호 포함, `ps-row-readonly`) | 숨김 (CSS) |
+| 그룹·소계·합계 행 | 만들지 않음 |
+
+정적 `editor` 만 본다 — `editorResolver` 가 행마다 고른 dropdown 과 `editableWhen` 으로 막힌 칸은 표시에 반영하지 않는다. 병합 셀(오버레이)과 Multi-Row 레이아웃에도 그리지 않는다.
+
 **커스텀 에디터의 `getValue`** — 그리드가 값을 **가져가는** 함수입니다. 에디터가 `onCommit` 을 부르지 않은 채 그리드가 스스로 편집을 확정할 때(창 밖 클릭·다른 셀 클릭/편집 시작·Enter/Tab 이 그리드까지 올라옴·`commitEdit()` API·설정 적용 전 확정) renderer 가 돌려준 요소를 받아 **셀에 저장할 데이터 값**을 돌려줍니다.
 
 | `getValue` | 결과 |
@@ -4088,6 +4132,10 @@ interface AddedRow {
   rowId: string | number;
   data: Row;
   insertIndex: number;
+  /** 데이터 순서에서 바로 앞 행 id. 맨 앞 null, 모르면 undefined */
+  afterRowId?: string | number | null;
+  /** 데이터 순서에서 바로 뒤 행 id. 맨 끝 null, 모르면 undefined */
+  beforeRowId?: string | number | null;
 }
 
 interface ModifiedRow {
@@ -4110,6 +4158,22 @@ interface DeletedRow {
 }
 ```
 
+**저장 전 새 행의 위치 — `afterRowId` / `beforeRowId`**
+
+백엔드가 행 순서를 저장할 때 "어느 행 바로 뒤(앞)에 넣었는지"를 기준 행 id 로 넘길 수 있습니다. `getAll()` 을 부를 때 그 순간의 이웃으로 계산합니다(추가할 때 드는 비용 없음).
+
+- 기준은 **그리드 데이터 순서**(원본 행 사이에 새 행을 끼운 순서)입니다. 화면 정렬·필터와 무관합니다. 드래그로 순서를 바꿨으면 `reorderedOrder` 기준입니다.
+- **삭제 표시한 행은 건너뜁니다**(저장하면 사라지므로). 맨 앞/맨 끝이면 `null`.
+- 새 행끼리 붙어 있으면 서로의 id 를 가리킵니다. `added` 를 `afterRowId` 사슬 순서대로 넣으면 그리드와 같은 순서가 됩니다.
+- Worker(`loader.worker`)·서버 행 모델에서는 메인 스레드에 원본이 없어, 이웃이 원본 행이면 `undefined` 입니다(이웃이 새 행이거나 맨 앞이면 채워짐).
+
+```ts
+// 원본 A, B, C — B 를 선택하고 X 를 위에, Y 를 아래에 추가 → A, X, B, Y, C
+grid.changes.getAll().added;
+// [{ rowId: 'X', afterRowId: 'A', beforeRowId: 'B', ... },
+//  { rowId: 'Y', afterRowId: 'B', beforeRowId: 'C', ... }]
+```
+
 #### PerformanceTiming
 
 ```typescript
@@ -4791,6 +4855,7 @@ interface GridConfigSnapshot {
   autoFitColumns?: boolean;
   showStatusBar?: boolean;
   summaryRow?: 'none' | 'pinnedTop' | 'pinnedBottom';
+  nullsPosition?: 'last' | 'first' | 'natural';
   locale?: string;
   translations?: PartialTranslationMap;
   keyFields?: string[];
@@ -5656,6 +5721,7 @@ new PureSheet(container, {
 |---|---|
 | `startRow`, `endRow` | 요청 구간 `[startRow, endRow)` — 항상 블록 경계 |
 | `sortModel`, `filterModel` | 현재 정렬·필터 상태(`SortState[]`, `ServerFilterState[]`). **서버가 적용**. 수식 필터(`operator: 'formula'`)에는 `expression` 과 함께 수식 트리 `ast`(JSON)가 실려, 서버가 문자열을 해석하지 않고 트리를 따라 SQL 등으로 바꿀 수 있습니다. JS 서버는 `createRowFilterPredicate(filterModel, { columnTypes })` 로 그리드와 같은 판정 함수를 쓸 수 있습니다(아래) |
+| `nullsPosition` | 정렬에서 빈 값(null) 위치 — 그리드 설정 `nullsPosition` 값(`'last'` \| `'first'` \| `'natural'`). `sortModel` 항목에는 따로 싣지 않으니 서버가 모든 정렬 키에 같은 규칙을 씁니다: `'last'` = 모든 키 `NULLS LAST`, `'first'` = 모든 키 `NULLS FIRST`, `'natural'` = 오름차순 키 `NULLS FIRST`·내림차순 키 `NULLS LAST`. 정렬 없이 서버가 그룹 순서를 정할 때도 같은 규칙입니다. 그룹·검색·경로 요청에도 실립니다. `grid.setNullsPosition()` 으로 바꾸면 처음부터 다시 요청합니다 |
 | `groupColumns`, `groupKeys` | 행 그룹이 있으면 그룹 열(레벨 순)과 이 행들이 속한 그룹의 값 경로(예: `['서울', '강남구']`). 서버는 이 그룹 안의 행만 돌려줍니다. 그룹이 없으면 둘 다 `[]`. 객체 값 그룹 열이면 `groupKeys` 에는 객체 대신 `objectKey` 값이 옵니다(→ [서버 계약](#객체-값-열점-표기-필드의-서버-계약)) |
 | `parentIds` | 트리(`treeConfig`)면 이 행들의 부모 노드 ID 경로(최상위부터). `[]` = 최상위 노드, `['A', 'A-0']` = A 아래 A-0 의 자식들. 트리가 아니면 `[]` |
 | `aggregateModel?` | 트리에서 `treeConfig.aggregates` 나 부모가 자손을 포함하는 체크박스 열(`checkboxIncludesDescendants`)이 있을 때만 — 노드별 **자기 + 자손**(서브트리) 집계 요청 (아래 트리 참조) |

package/docs/manual/reference_vue.md

@@ -1021,6 +1021,7 @@ const cleanupPopup = () => {
 | `current` (모드·컬럼 너비/고정/숨김/순서/집계·정렬·필터·행 그룹·트리/디테일·피벗 축·테마·`summaryRow` 등) | `grid.getConfig()` | core | `grid.applyConfig(config, { missing })` |
 | `current` 의 UI 옵션(`rowHeight`·`headerHeight`·`editable`·`tooltipMode`·`alternatingRows`·`showHeader`·`showStatusBar`·선택 모드 등) | `grid.getConfig()` | core | core `applyConfig`의 runtime UI 복원 대상. 모든 생성 옵션의 복원을 뜻하지 않음. `showStatusBar`는 core 지원과 별개로 wrapper 생성 설정에서 자체 Footer를 위해 false로 override하며 prop reconcile 대상에서도 제외 |
 | `snapshot` | `grid.getConfig()` | core | 컬럼 reset baseline |
+| ~~`current.nullsPosition`~~ | 저장하지 않음 | — | 정렬에서 빈 값 위치는 화면(메뉴)이 정하는 그리드 설정이라 사용자 레이아웃에서 뺀다. 불러올 때도 저장본 값·`missing: 'reset'` 과 관계없이 **현재 값 유지**. core `getConfig()`/`applyConfig()` 에는 그대로 있다 |
 | `customCellConfig` | `getCustomCellState() ?? null` | wrapper | `setCustomCellState` |
 | `columnFormatConfig` | `getColumnFormatState() ?? null` | wrapper | `setColumnFormatState` |
 | `viewOptionsConfig` | `getViewOptionsState()` = `GridChrome.getPresetViewState()` (툴바 펼침·푸터·그룹 패널·피벗 바) | wrapper | `setViewOptionsState` = `GridChrome.setPresetViewState` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vmscloud/moz-ui-grid-vue",
-  "version": "0.2.20",
+  "version": "0.2.22",
   "description": "MozGrid - Vue 3 wrapping library for @vmscloud/moz-ui-grid-core",
   "license": "ISC",
   "type": "module",