open-grid 1.3.0 → 1.3.1

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.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,18 @@
2
2
 
3
3
  All notable changes to OPEN_GRID will be documented in this file.
4
4
 
5
+ ## [1.3.1] - 2026-07-15
6
+
7
+ ### Docs
8
+ - **공개 API JSDoc 인간화** / **Human-readable public API JSDoc.** TypeDoc 이 소비하는 공개
9
+ 표면(OpenGrid·GridOptions/ColumnDef·i18n·Icon/Skin·GridShuttle·OrgChart·XmlConverter·
10
+ FilterSelect·chart 타입)의 주석을 "언제·왜 쓰나 + 무엇을 얻나" 중심으로 다시 써서
11
+ 읽기 쉽게 승격하고, 표준 IT 용어로 교정했다. `@example` 다수 추가.
12
+ 코드 로직은 한 줄도 바뀌지 않았다(주석 전용).
13
+ / Rewrote the comments on the public API surface consumed by TypeDoc to lead with
14
+ when/why-to-use and what-you-get, added many `@example`s, and normalized terminology.
15
+ No logic changed (comments only).
16
+
5
17
  ## [1.3.0] - 2026-07-15
6
18
 
7
19
  ### Added
@@ -77,10 +77,29 @@ type ResetFn = (field?: string) => void;
77
77
  /**
78
78
  * 캐스케이딩 필터 셀렉트 패널. / Cascading filter-select panel.
79
79
  *
80
- * 그리드 헤더 앞에 fieldset 형태의 셀렉트 필터를 삽입하고, 부모→자식 종속(캐스케이딩)
81
- * 옵션 재계산과 그리드 필터 콜백을 배선한다.
82
- * / Inserts a fieldset of select filters ahead of the grid header and wires parent→child cascading
83
- * option recalculation to the grid filter callbacks.
80
+ * "카테고리를 고르면 브랜드 목록이 그 카테고리에 맞게 좁혀지는" 것처럼, 상위 셀렉트의 선택에
81
+ * 따라 하위 셀렉트의 옵션이 자동으로 걸러지는 드롭다운 필터 묶음이 필요할 때 쓴다. 그리드
82
+ * 헤더 앞에 fieldset 형태로 삽입된다. 동작 순서: 사용자가 셀렉트를 바꾸면 → 내부에서 그리드
83
+ * 필터 콜백(onFilter/onReset)을 호출해 그리드를 걸러내고 → 종속된 자식 셀렉트의 옵션 목록을
84
+ * 새 부모값 기준으로 다시 계산해 넣는다(재귀적으로 손자 셀렉트까지 전파).
85
+ * 보통 직접 생성자를 호출하기보다 `grid.setFilterSelect(config)`를 통해 그리드에 붙인다.
86
+ * / Use this when you need a group of dropdown filters where picking a value in a parent select
87
+ * narrows the options in a child select — e.g. picking a category narrows the brand list. It's
88
+ * inserted as a fieldset ahead of the grid header. Operation order: the user changes a select →
89
+ * internally the grid filter callbacks (onFilter/onReset) run to filter the grid → then the
90
+ * dependent child select's options are recomputed against the new parent value (recursing down
91
+ * to grandchild selects). Usually attached via `grid.setFilterSelect(config)` rather than by
92
+ * calling the constructor directly.
93
+ *
94
+ * @example
95
+ * // 보통 이렇게 그리드를 통해 사용한다 / Typically wired through the grid like this:
96
+ * grid.setFilterSelect({
97
+ * columns: [
98
+ * { field: 'category', label: '카테고리', data: categoryList, valueKey: 'code', textKey: 'name' },
99
+ * { field: 'brand', label: '브랜드', data: brandList, valueKey: 'code', textKey: 'name',
100
+ * dependsOn: 'category', dependsOnKey: 'categoryCode' },
101
+ * ],
102
+ * });
84
103
  */
85
104
  export declare class FilterSelectPanel {
86
105
  private _el;
@@ -114,7 +133,9 @@ export declare class FilterSelectPanel {
114
133
  */
115
134
  private _cascade;
116
135
  private _reset;
117
- /** 모든 필터 선택을 초기화한다. / Reset all filter selections. */
136
+ /** 모든 필터 선택을 초기화한다("전체 초기화" 버튼과 동일 동작을 코드에서 트리거하고 싶을 때).
137
+ * / Reset all filter selections (call this to trigger the same action as the "clear" button
138
+ * from code). */
118
139
  reset(): void;
119
140
  /** 패널을 DOM 에서 제거한다. / Remove the panel from the DOM. */
120
141
  destroy(): void;
@@ -3,13 +3,22 @@ import { OpenGridInstance } from './types.js';
3
3
  * 그리드 셔틀 생성 옵션. / Grid shuttle construction options.
4
4
  */
5
5
  export interface GridShuttleOptions {
6
- /** 버튼 배치 방향. 기본 'vertical'. / Button layout direction. Default 'vertical'.
6
+ /** 버튼 배치 방향. 두 그리드가 가로로 나란히 있으면 'vertical'(위아래 버튼), 세로로 쌓여 있으면
7
+ * 'horizontal'을 쓴다. 기본 'vertical'.
8
+ * / Button layout direction. Use 'vertical' (stacked buttons) when the two grids sit side by side,
9
+ * or 'horizontal' when they're stacked vertically. Default 'vertical'.
7
10
  * @defaultValue 'vertical' */
8
11
  layout?: 'vertical' | 'horizontal';
9
- /** 전체 이동(≫ ≪) 버튼도 표시. 기본 false. / Also show move-all (≫ ≪) buttons. Default false.
12
+ /** 전체 이동(≫ ≪) 버튼도 표시. "전체 선택 후 이동"을 한 번의 클릭으로 줄이고 싶을 때 켠다.
13
+ * 기본 false(개별 이동 버튼만 표시).
14
+ * / Also show move-all (≫ ≪) buttons, so a full transfer takes one click instead of
15
+ * "select all, then move". Default false (only the per-check move buttons are shown).
10
16
  * @defaultValue false */
11
17
  includeAll?: boolean;
12
- /** 버튼 라벨 커스터마이즈. / Customize button labels. */
18
+ /** 버튼 라벨 커스터마이즈(다국어 문구를 직접 넣고 싶을 때). 생략 시 그리드 로케일의 기본
19
+ * 문구(▶ ◀ ⏩ ⏪)를 사용한다.
20
+ * / Customize button labels (e.g. to hardcode a specific phrase). Falls back to the grid's
21
+ * locale defaults (▶ ◀ ⏩ ⏪) when omitted. */
13
22
  labels?: {
14
23
  toRight?: string;
15
24
  toLeft?: string;
@@ -20,12 +29,18 @@ export interface GridShuttleOptions {
20
29
  /**
21
30
  * 두 그리드 사이의 셔틀 UI. / Shuttle UI between two grids.
22
31
  *
23
- * 두 그리드 사이에 화살표 버튼을 두고 "체크된 행"을 드래그 없이 버튼으로 이동(move)시킨다.
24
- * 이동은 `grid.moveCheckedTo()` 를 호출하므로 crossGridMapping(필드 매핑)과 3단계 이벤트가
25
- * 드래그 이동과 100% 동일하게 적용된다.
26
- * / Places arrow buttons between two grids to move "checked rows" without dragging.
27
- * The move delegates to `grid.moveCheckedTo()`, so crossGridMapping (field mapping) and the
28
- * 3-stage events apply identically to drag-based moves.
32
+ * "가용 항목 그리드"와 "선택된 항목 그리드"를 나란히 두고, 그 사이에서 체크한 행을 화살표
33
+ * 버튼으로 옮기고 싶을 때 쓴다(권한 배정, 컬럼 표시 여부 선택 같은 화면에 흔한 UI 패턴).
34
+ * 동작 순서는 이렇다: 사용자가 왼쪽 그리드에서 행을 체크하고 ▶ 버튼을 클릭하면, 내부적으로
35
+ * `grid.moveCheckedTo()` 가 호출되어 오른쪽 그리드로 행이 옮겨진다 — 이때 crossGridMapping
36
+ * (필드 매핑)과 3단계 이벤트가 드래그로 옮길 때와 동일하게 적용되므로, 버튼 이동과 드래그
37
+ * 이동을 섞어 써도 동작이 갈리지 않는다.
38
+ * / Places arrow buttons between an "available items" grid and a "selected items" grid so
39
+ * checked rows can be moved between them without dragging (a common pattern for permission
40
+ * assignment, column visibility pickers, etc.). Operation order: the user checks rows in the
41
+ * left grid and clicks ▶, which internally calls `grid.moveCheckedTo()` to move those rows into
42
+ * the right grid — crossGridMapping (field mapping) and the 3-stage events apply identically to
43
+ * drag-based moves, so mixing button moves with drag moves never behaves differently.
29
44
  *
30
45
  * @example
31
46
  * const shuttle = new GridShuttle(leftGrid, rightGrid, document.querySelector('#mid')!, {
@@ -51,7 +66,8 @@ export declare class GridShuttle {
51
66
  /**
52
67
  * 두 그리드 사이에 셔틀(화살표 이동) 버튼을 만든다. / Create shuttle (arrow-move) buttons between two grids.
53
68
  *
54
- * `new GridShuttle(...)` 의 편의 팩토리. / Convenience factory for `new GridShuttle(...)`.
69
+ * `new GridShuttle(...)` 과 동일하되, `new` 없이 함수 호출 한 줄로 끝내고 싶을 때 쓰는 편의 팩토리.
70
+ * / Same as `new GridShuttle(...)`, but a convenience factory for callers who'd rather skip `new`.
55
71
  *
56
72
  * @param left - 왼쪽 그리드 인스턴스 / Left grid instance
57
73
  * @param right - 오른쪽 그리드 인스턴스 / Right grid instance
@@ -11,29 +11,42 @@ export interface IconRenderOptions {
11
11
  el?: boolean;
12
12
  }
13
13
  /**
14
- * 시맨틱 ROLE → 아이콘 key(`BOOTSTRAP_ICONS` 의 symbolId) 기본 매핑.
15
- * / Default map of semantic ROLE → icon key (a `BOOTSTRAP_ICONS` symbolId).
14
+ * 시맨틱 role → 아이콘 key(`BOOTSTRAP_ICONS` 의 symbolId) 기본 매핑. 이 표 자체를 고치는 것은
15
+ * 라이브러리 소스에 손대는 것과 같으므로, 앱에서 아이콘을 바꾸고 싶으면 이 표 대신
16
+ * `grid.setIcon(role, key)`(인스턴스 한정) 또는 `defineIconSet()`(전역)으로 등록하는 것이 정석이다.
17
+ * / Default map of semantic role → icon key (a `BOOTSTRAP_ICONS` symbolId). Editing this table
18
+ * means touching library source, so apps that want a different icon should instead register one
19
+ * via `grid.setIcon(role, key)` (per instance) or `defineIconSet()` (globally).
16
20
  *
17
- * 렌더 코드는 이 역할 이름만 참조한다. key 교체는 이 표(혹은 register/setIcon)만 고치면 된다.
18
- * 참고 스왑: `row.delete`→`trash3`(Bootstrap 의 표준 휴지통, task 의 'trash' 동족), `chart.line`→`graph-up`.
19
- * / Render code references only these role names; swapping a glyph means editing this table (or register/setIcon).
21
+ * 렌더 코드는 이 역할 이름만 참조한다. / Render code references only these role names.
22
+ * 참고 스왑: `row.delete`→`trash3`(Bootstrap 의 표준 휴지통), `chart.line`→`graph-up`.
23
+ * / Example swap: `row.delete`→`trash3` (Bootstrap's standard trash-can icon), `chart.line`→`graph-up`.
20
24
  */
21
25
  export declare const DEFAULT_ICON_ROLES: Readonly<Record<string, string>>;
22
26
  /**
23
- * IconRegistry — role → 글리프 본문(inner SVG markup) 해석 + svg 래핑.
24
- * / IconRegistry — resolves role → glyph body (inner SVG markup) and wraps it in an svg.
25
- *
26
- * 저장 단위는 **글리프 본문 문자열**(<path>/<g> 마크업). register(role, svgOrKey) 는
27
+ * IconRegistry — 시맨틱 role(예: 'sort.asc') 을 실제 아이콘 SVG 로 바꿔주는 등록소.
28
+ * 정렬 화살표·필터 깔때기 같은 아이콘을 코드 곳곳에 인라인 SVG 로 박아 두면, 아이콘 하나를
29
+ * 바꾸려 해도 렌더러 파일들을 찾아 고쳐야 한다 — 대신 렌더 코드는 "sort.asc 를 그려줘"라고만
30
+ * 요청하고, 실제 어떤 글리프인지는 이 레지스트리가 결정한다. 동작 순서: ① `register(role,
31
+ * svgOrKey)` 로 role↔글리프 매핑을 등록해 두면 → ② 렌더 시점에 `render(role)` 가 호출되어
32
+ * → ③ 등록된 본문을 `<svg>` 로 감싸 문자열(또는 SVGElement)로 돌려준다. 저장 단위는
33
+ * **글리프 본문 문자열**(<path>/<g> 마크업)뿐이라, register(role, svgOrKey) 는
27
34
  * - svgOrKey 가 `BOOTSTRAP_ICONS` 의 알려진 key 면 그 본문으로,
28
35
  * - 아니면 **원시 SVG 본문**(사용자 커스텀 <path…>)으로 저장한다.
29
36
  * 부모 체인(_parent)으로 per-instance 오버라이드 레지스트리를 전역 위에 얹는다(멀티그리드 격리).
30
- * / The storage unit is the glyph body string (<path>/<g> markup). register(role, svgOrKey) stores either
31
- * the body of a known `BOOTSTRAP_ICONS` key, or the raw SVG body otherwise. A parent chain (_parent) layers
32
- * a per-instance override registry on top of the global one (multi-grid isolation).
37
+ * / IconRegistry — a registry that turns a semantic role (e.g. 'sort.asc') into an actual icon
38
+ * SVG. Hardcoding inline SVG for every sort arrow or filter funnel across render code means
39
+ * hunting down every renderer file just to swap one icon — instead render code simply asks "draw
40
+ * sort.asc", and this registry decides which glyph that is. Flow: ① `register(role, svgOrKey)`
41
+ * records a role↔glyph mapping → ② at render time `render(role)` is called → ③ it wraps the
42
+ * registered body in an `<svg>` and returns a string (or SVGElement). The storage unit is only
43
+ * the glyph body string (<path>/<g> markup), so register(role, svgOrKey) stores either the body
44
+ * of a known `BOOTSTRAP_ICONS` key, or the raw SVG body otherwise. A parent chain (_parent)
45
+ * layers a per-instance override registry on top of the global one (multi-grid isolation).
33
46
  *
34
47
  * @example
35
48
  * const reg = iconRegistry.child();
36
- * reg.register('sort.asc', 'arrow-up');
49
+ * reg.register('sort.asc', 'arrow-up'); // 이 그리드 인스턴스만 화살표를 교체 / swap the arrow for this grid instance only
37
50
  * const svg = reg.render('sort.asc', { size: 16 }) as string;
38
51
  */
39
52
  export declare class IconRegistry {
@@ -49,6 +62,11 @@ export declare class IconRegistry {
49
62
  * @param role - 시맨틱 역할 키(예: 'sort.asc') / Semantic role key (e.g. 'sort.asc')
50
63
  * @param svgOrKey - 알려진 아이콘 key 또는 원시 SVG 본문 / A known icon key or raw SVG body
51
64
  * @returns 체이닝용 this / this for chaining
65
+ * @example
66
+ * // 다른 Bootstrap 아이콘 key 로 교체 / Swap to a different Bootstrap icon key
67
+ * iconRegistry.register('row.delete', 'x-circle');
68
+ * // 원시 SVG 본문으로 통째 교체 / Replace entirely with a custom raw SVG body
69
+ * iconRegistry.register('menu', '<path d="M2 4h12v2H2z"/>');
52
70
  */
53
71
  register(role: string, svgOrKey: string): this;
54
72
  /** role 이 (자신 또는 부모 체인에) 등록돼 있는가. / Whether a role is registered (self or parent chain). */