open-grid 1.3.0 → 1.4.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.
@@ -1,39 +1,122 @@
1
1
  /**
2
2
  * render() 옵션. size 미지정 시 svg 는 viewBox/CSS 로 크기를 상속(width/height 속성 생략).
3
- * / render() options. When size is omitted, the svg inherits its size from viewBox/CSS (width/height attrs skipped).
3
+ *
4
+ * render() options. When size is omitted, the svg inherits its size from viewBox/CSS (width/height attrs skipped).
5
+ *
6
+ * render() のオプション。size を指定しない場合、svg は viewBox/CSS からサイズを継承します(width/height 属性は省略)。
7
+ *
8
+ * render() 选项。未指定 size 时,svg 从 viewBox/CSS 继承尺寸(省略 width/height 属性)。
4
9
  */
5
10
  export interface IconRenderOptions {
6
- /** px 정사각 크기(width=height). 미지정 시 속성 생략(CSS/컨테이너가 결정). / Square size in px (width=height); omitted when unset (CSS/container decides). */
11
+ /**
12
+ * px 정사각 크기(width=height). 미지정 시 속성 생략(CSS/컨테이너가 결정).
13
+ *
14
+ * Square size in px (width=height); omitted when unset (CSS/container decides).
15
+ *
16
+ * px 単位の正方形サイズ(width=height)。未指定時は属性を省略(CSS/コンテナが決定)。
17
+ *
18
+ * 以 px 为单位的正方形尺寸(width=height)。未指定时省略该属性(由 CSS/容器决定)。
19
+ */
7
20
  size?: number;
8
- /** 접근성 제목. 지정 시 <title> + role="img" 추가(스크린리더). 미지정 시 장식용(부모가 aria 담당). / Accessible title; adds <title> + role="img" when set (screen readers). Decorative otherwise (parent owns aria). */
21
+ /**
22
+ * 접근성 제목. 지정 시 <title> + role="img" 추가(스크린리더). 미지정 시 장식용(부모가 aria 담당).
23
+ *
24
+ * Accessible title; adds <title> + role="img" when set (screen readers). Decorative otherwise (parent owns aria).
25
+ *
26
+ * アクセシビリティ用のタイトル。指定時は <title> と role="img" を追加(スクリーンリーダー)。未指定時は装飾用(aria は親が担当)。
27
+ *
28
+ * 无障碍标题。指定时添加 <title> 和 role="img"(供屏幕阅读器)。未指定时为装饰性图标(aria 由父元素负责)。
29
+ */
9
30
  title?: string;
10
- /** true → SVGElement(DOMParser) 반환. 기본 false → SVG 마크업 문자열. / true → return an SVGElement (DOMParser). Default false → SVG markup string. @defaultValue false */
31
+ /**
32
+ * true → SVGElement(DOMParser) 반환. 기본 false → SVG 마크업 문자열.
33
+ *
34
+ * true → return an SVGElement (DOMParser). Default false → SVG markup string.
35
+ *
36
+ * true → SVGElement(DOMParser)を返します。既定の false → SVG マークアップ文字列。
37
+ *
38
+ * true → 返回 SVGElement(DOMParser)。默认 false → 返回 SVG 标记字符串。
39
+ *
40
+ * @defaultValue false
41
+ */
11
42
  el?: boolean;
12
43
  }
13
44
  /**
14
- * 시맨틱 ROLE → 아이콘 key(`BOOTSTRAP_ICONS` 의 symbolId) 기본 매핑.
15
- * / Default map of semantic ROLE → icon key (a `BOOTSTRAP_ICONS` symbolId).
45
+ * 시맨틱 role → 아이콘 key(`BOOTSTRAP_ICONS` 의 symbolId) 기본 매핑. 이 표 자체를 고치는 것은
46
+ * 라이브러리 소스에 손대는 것과 같으므로, 앱에서 아이콘을 바꾸고 싶으면 이 표 대신
47
+ * `grid.setIcon(role, key)`(인스턴스 한정) 또는 `defineIconSet()`(전역)으로 등록하는 것이 정석이다.
48
+ *
49
+ * Default map of semantic role → icon key (a `BOOTSTRAP_ICONS` symbolId). Editing this table
50
+ * means touching library source, so apps that want a different icon should instead register one
51
+ * via `grid.setIcon(role, key)` (per instance) or `defineIconSet()` (globally).
16
52
  *
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).
53
+ * セマンティックな role → アイコン key(`BOOTSTRAP_ICONS` の symbolId)の既定マッピング。この表そのものを直すことは
54
+ * ライブラリのソースに手を入れるのと同じなので、アプリでアイコンを変えたい場合はこの表ではなく
55
+ * `grid.setIcon(role, key)`(インスタンス限定)または `defineIconSet()`(グローバル)で登録するのが定石です。
56
+ *
57
+ * 语义 role → 图标 key(`BOOTSTRAP_ICONS` 中的 symbolId)的默认映射。改这张表等于改动库的源码,
58
+ * 所以应用要换图标时,不要动这张表,而应通过 `grid.setIcon(role, key)`(限当前实例)
59
+ * 或 `defineIconSet()`(全局)注册。
60
+ *
61
+ * 렌더 코드는 이 역할 이름만 참조한다.
62
+ * 참고 스왑: `row.delete`→`trash3`(Bootstrap 의 표준 휴지통), `chart.line`→`graph-up`.
63
+ *
64
+ * Render code references only these role names.
65
+ * Example swap: `row.delete`→`trash3` (Bootstrap's standard trash-can icon), `chart.line`→`graph-up`.
66
+ *
67
+ * レンダーコードはこの役割名だけを参照します。
68
+ * 参考スワップ: `row.delete`→`trash3`(Bootstrap の標準ゴミ箱), `chart.line`→`graph-up`。
69
+ *
70
+ * 渲染代码只引用这些角色名。
71
+ * 替换示例: `row.delete`→`trash3`(Bootstrap 的标准垃圾桶图标), `chart.line`→`graph-up`。
20
72
  */
21
73
  export declare const DEFAULT_ICON_ROLES: Readonly<Record<string, string>>;
22
74
  /**
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) 는
75
+ * IconRegistry — 시맨틱 role(예: 'sort.asc') 을 실제 아이콘 SVG 로 바꿔주는 등록소.
76
+ * 정렬 화살표·필터 깔때기 같은 아이콘을 코드 곳곳에 인라인 SVG 로 박아 두면, 아이콘 하나를
77
+ * 바꾸려 해도 렌더러 파일들을 찾아 고쳐야 한다 — 대신 렌더 코드는 "sort.asc 를 그려줘"라고만
78
+ * 요청하고, 실제 어떤 글리프인지는 이 레지스트리가 결정한다. 동작 순서: ① `register(role,
79
+ * svgOrKey)` 로 role↔글리프 매핑을 등록해 두면 → ② 렌더 시점에 `render(role)` 가 호출되어
80
+ * → ③ 등록된 본문을 `<svg>` 로 감싸 문자열(또는 SVGElement)로 돌려준다. 저장 단위는
81
+ * **글리프 본문 문자열**(<path>/<g> 마크업)뿐이라, register(role, svgOrKey) 는
27
82
  * - svgOrKey 가 `BOOTSTRAP_ICONS` 의 알려진 key 면 그 본문으로,
28
83
  * - 아니면 **원시 SVG 본문**(사용자 커스텀 <path…>)으로 저장한다.
29
84
  * 부모 체인(_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).
85
+ *
86
+ * IconRegistry — a registry that turns a semantic role (e.g. 'sort.asc') into an actual icon
87
+ * SVG. Hardcoding inline SVG for every sort arrow or filter funnel across render code means
88
+ * hunting down every renderer file just to swap one icon — instead render code simply asks "draw
89
+ * sort.asc", and this registry decides which glyph that is. Flow: ① `register(role, svgOrKey)`
90
+ * records a role↔glyph mapping → ② at render time `render(role)` is called → ③ it wraps the
91
+ * registered body in an `<svg>` and returns a string (or SVGElement). The storage unit is only
92
+ * the glyph body string (<path>/<g> markup), so register(role, svgOrKey) stores either the body
93
+ * of a known `BOOTSTRAP_ICONS` key, or the raw SVG body otherwise. A parent chain (_parent)
94
+ * layers a per-instance override registry on top of the global one (multi-grid isolation).
95
+ *
96
+ * IconRegistry — セマンティックな role(例: 'sort.asc')を実際のアイコン SVG に変えてくれるレジストリ。
97
+ * ソート矢印やフィルターの漏斗のようなアイコンをコードのあちこちにインライン SVG で埋め込んでおくと、
98
+ * アイコン一つを変えるだけでもレンダラーのファイルを探して直さなければなりません — 代わりにレンダーコードは
99
+ * 「sort.asc を描いて」と頼むだけで、実際にどのグリフなのかはこのレジストリが決めます。動作の順序:
100
+ * ① `register(role, svgOrKey)` で role↔グリフのマッピングを登録しておくと → ② レンダー時点で `render(role)`
101
+ * が呼ばれ → ③ 登録された本文を `<svg>` で包んで文字列(または SVGElement)として返します。保存の単位は
102
+ * **グリフ本文の文字列**(<path>/<g> マークアップ)だけなので、register(role, svgOrKey) は
103
+ * - svgOrKey が `BOOTSTRAP_ICONS` の既知の key であればその本文として、
104
+ * - そうでなければ **生の SVG 本文**(ユーザーのカスタム <path…>)として保存します。
105
+ * 親チェーン(_parent)で per-instance のオーバーライドレジストリをグローバルの上に重ねます(マルチグリッドの分離)。
106
+ *
107
+ * IconRegistry — 把语义 role(例: 'sort.asc')换成实际图标 SVG 的注册表。
108
+ * 若把排序箭头、筛选漏斗这类图标以内联 SVG 硬编码在渲染代码各处,只换一个图标也得翻遍渲染器文件逐一修改 —
109
+ * 改由渲染代码只提出「画出 sort.asc」的请求,具体是哪个字形则交给这个注册表决定。执行顺序:
110
+ * ① 用 `register(role, svgOrKey)` 登记 role↔字形的映射 → ② 渲染时调用 `render(role)`
111
+ * → ③ 把登记的主体包进 `<svg>`,返回字符串(或 SVGElement)。存储单位只有
112
+ * **字形主体字符串**(<path>/<g> 标记),因此 register(role, svgOrKey) 的存储方式为:
113
+ * - svgOrKey 是 `BOOTSTRAP_ICONS` 的已知 key 时,存其主体;
114
+ * - 否则存为 **原始 SVG 主体**(用户自定义的 <path…>)。
115
+ * 通过父链(_parent)把 per-instance 的覆盖注册表叠加在全局之上(多表格隔离)。
33
116
  *
34
117
  * @example
35
118
  * const reg = iconRegistry.child();
36
- * reg.register('sort.asc', 'arrow-up');
119
+ * reg.register('sort.asc', 'arrow-up'); // swap the arrow for this grid instance only
37
120
  * const svg = reg.render('sort.asc', { size: 16 }) as string;
38
121
  */
39
122
  export declare class IconRegistry {
@@ -43,59 +126,202 @@ export declare class IconRegistry {
43
126
  /**
44
127
  * role 에 글리프를 등록/교체. svgOrKey 가 알려진 아이콘 key 면 그 본문을, 아니면 원시 SVG
45
128
  * 본문 마크업으로 간주한다(코어 편집 없이 아이콘 교체 — OCP).
46
- * / Register/replace a glyph for a role. A known icon key resolves to its body; otherwise svgOrKey is
129
+ *
130
+ * Register/replace a glyph for a role. A known icon key resolves to its body; otherwise svgOrKey is
47
131
  * treated as raw SVG body markup (swap icons without editing core — OCP).
48
132
  *
49
- * @param role - 시맨틱 역할 키(예: 'sort.asc') / Semantic role key (e.g. 'sort.asc')
50
- * @param svgOrKey - 알려진 아이콘 key 또는 원시 SVG 본문 / A known icon key or raw SVG body
51
- * @returns 체이닝용 this / this for chaining
133
+ * role にグリフを登録/差し替え。svgOrKey が既知のアイコン key であればその本文を、そうでなければ生の SVG
134
+ * 本文マークアップとみなします(コアを編集せずにアイコンを差し替え — OCP)。
135
+ *
136
+ * 为 role 注册/替换字形。svgOrKey 是已知图标 key 时取其主体,否则视为原始 SVG 主体标记
137
+ * (无需编辑核心即可替换图标 — OCP)。
138
+ *
139
+ * @param role - 시맨틱 역할 키(예: 'sort.asc')
140
+ *
141
+ * Semantic role key (e.g. 'sort.asc')
142
+ *
143
+ * セマンティックな役割キー(例: 'sort.asc')
144
+ *
145
+ * 语义角色键(例: 'sort.asc')
146
+ *
147
+ * @param svgOrKey - 알려진 아이콘 key 또는 원시 SVG 본문
148
+ *
149
+ * A known icon key or raw SVG body
150
+ *
151
+ * 既知のアイコン key または生の SVG 本文
152
+ *
153
+ * 已知的图标 key 或原始 SVG 主体
154
+ *
155
+ * @returns 체이닝용 this
156
+ *
157
+ * this for chaining
158
+ *
159
+ * チェーン用の this
160
+ *
161
+ * 用于链式调用的 this
162
+ *
163
+ * @example
164
+ * // Swap to a different Bootstrap icon key
165
+ * iconRegistry.register('row.delete', 'x-circle');
166
+ * // Replace entirely with a custom raw SVG body
167
+ * iconRegistry.register('menu', '<path d="M2 4h12v2H2z"/>');
52
168
  */
53
169
  register(role: string, svgOrKey: string): this;
54
- /** role 이 (자신 또는 부모 체인에) 등록돼 있는가. / Whether a role is registered (self or parent chain). */
170
+ /**
171
+ * role 이 (자신 또는 부모 체인에) 등록돼 있는가.
172
+ *
173
+ * Whether a role is registered (self or parent chain).
174
+ *
175
+ * role が(自身または親チェーンに)登録されているか。
176
+ *
177
+ * role 是否已注册(在自身或父链中)。
178
+ */
55
179
  has(role: string): boolean;
56
180
  /**
57
181
  * role → 글리프 본문(inner markup). 미등록이면 null(부모 체인까지 조회).
58
- * / role → glyph body (inner markup); null if unregistered (searches up the parent chain).
59
182
  *
60
- * @param role - 조회할 역할 키 / Role key to resolve
61
- * @returns 글리프 본문 또는 null / Glyph body or null
183
+ * role → glyph body (inner markup); null if unregistered (searches up the parent chain).
184
+ *
185
+ * role → グリフ本文(inner markup)。未登録なら null(親チェーンまで照会)。
186
+ *
187
+ * role → 字形主体(inner markup)。未注册则返回 null(沿父链向上查找)。
188
+ *
189
+ * @param role - 조회할 역할 키
190
+ *
191
+ * Role key to resolve
192
+ *
193
+ * 照会する役割キー
194
+ *
195
+ * 要查找的角色键
196
+ *
197
+ * @returns 글리프 본문 또는 null
198
+ *
199
+ * Glyph body or null
200
+ *
201
+ * グリフ本文または null
202
+ *
203
+ * 字形主体或 null
62
204
  */
63
205
  resolveBody(role: string): string | null;
64
- /** 이 레지스트리를 부모로 하는 자식(per-instance 오버라이드용) 생성. / Create a child registry with this as parent (for per-instance overrides). */
206
+ /**
207
+ * 이 레지스트리를 부모로 하는 자식(per-instance 오버라이드용) 생성.
208
+ *
209
+ * Create a child registry with this as parent (for per-instance overrides).
210
+ *
211
+ * このレジストリを親とする子(per-instance のオーバーライド用)を生成。
212
+ *
213
+ * 创建以本注册表为父的子注册表(用于 per-instance 覆盖)。
214
+ */
65
215
  child(): IconRegistry;
66
216
  /**
67
217
  * role 을 `<svg viewBox=ICON_VIEWBOX>` 로 렌더. 기본 반환은 SVG 마크업 문자열(innerHTML 용);
68
218
  * opts.el 이면 SVGElement. 미지원 role 은 빈 svg 폴백(never throw).
69
219
  * 스킨 토큰: fill=currentColor(presentation attr) + stroke-linejoin=var(--og-icon-corner,miter).
70
- * / Render a role as `<svg viewBox=ICON_VIEWBOX>`. Returns SVG markup string by default (for innerHTML);
220
+ *
221
+ * Render a role as `<svg viewBox=ICON_VIEWBOX>`. Returns SVG markup string by default (for innerHTML);
71
222
  * opts.el returns an SVGElement. Unknown roles fall back to an empty svg (never throws).
72
223
  *
73
- * @param role - 렌더할 역할 키 / Role key to render
74
- * @param opts - 렌더 옵션 / Render options
75
- * @returns SVG 마크업 문자열 또는 SVGElement(opts.el) / SVG markup string, or SVGElement when opts.el
224
+ * role を `<svg viewBox=ICON_VIEWBOX>` としてレンダー。既定の戻り値は SVG マークアップ文字列(innerHTML 用)、
225
+ * opts.el なら SVGElement。未対応の role は空の svg にフォールバック(never throw)。
226
+ * スキントークン: fill=currentColor(presentation attr) + stroke-linejoin=var(--og-icon-corner,miter)。
227
+ *
228
+ * 把 role 渲染为 `<svg viewBox=ICON_VIEWBOX>`。默认返回 SVG 标记字符串(供 innerHTML 使用);
229
+ * 指定 opts.el 则返回 SVGElement。不支持的 role 回退为空 svg(never throw)。
230
+ * 皮肤令牌: fill=currentColor(presentation attr) + stroke-linejoin=var(--og-icon-corner,miter)。
231
+ *
232
+ * @param role - 렌더할 역할 키
233
+ *
234
+ * Role key to render
235
+ *
236
+ * レンダーする役割キー
237
+ *
238
+ * 要渲染的角色键
239
+ *
240
+ * @param opts - 렌더 옵션
241
+ *
242
+ * Render options
243
+ *
244
+ * レンダーオプション
245
+ *
246
+ * 渲染选项
247
+ *
248
+ * @returns SVG 마크업 문자열 또는 SVGElement(opts.el)
249
+ *
250
+ * SVG markup string, or SVGElement when opts.el
251
+ *
252
+ * SVG マークアップ文字列、または SVGElement(opts.el の場合)
253
+ *
254
+ * SVG 标记字符串,或指定 opts.el 时返回 SVGElement
76
255
  */
77
256
  render(role: string, opts?: IconRenderOptions): string | SVGElement;
78
- /** 등록된 role 목록(자신만, 디버깅/테스트용). / List of registered roles (self only; for debugging/tests). */
257
+ /**
258
+ * 등록된 role 목록(자신만, 디버깅/테스트용).
259
+ *
260
+ * List of registered roles (self only; for debugging/tests).
261
+ *
262
+ * 登録された role の一覧(自身のみ、デバッグ/テスト用)。
263
+ *
264
+ * 已注册的 role 列表(仅自身,供调试/测试用)。
265
+ */
79
266
  roles(): string[];
80
267
  }
81
268
  /**
82
269
  * 프로세스 공유 기본 아이콘 레지스트리(시맨틱 role 시드 완료).
83
- * / Process-shared default icon registry (seeded with semantic roles).
270
+ *
271
+ * Process-shared default icon registry (seeded with semantic roles).
272
+ *
273
+ * プロセス共有の既定アイコンレジストリ(セマンティックな role のシード済み)。
274
+ *
275
+ * 进程共享的默认图标注册表(已用语义 role 完成种子填充)。
84
276
  *
85
277
  * CellRenderer 등 팩토리 생성 렌더러(인스턴스 컨텍스트 없음)가 이 초크포인트로 아이콘을 얻는다.
86
278
  * per-instance 교체는 `grid.setIcon()`(이 레지스트리의 child) 로, 전역 확장은 `defineIconSet()` 로.
87
- * / Factory-created renderers (e.g. CellRenderer, without instance context) obtain icons through this
279
+ *
280
+ * Factory-created renderers (e.g. CellRenderer, without instance context) obtain icons through this
88
281
  * chokepoint. Per-instance swaps go through `grid.setIcon()` (a child of this registry); global extension
89
282
  * through `defineIconSet()`.
283
+ *
284
+ * CellRenderer など、ファクトリが生成するレンダラー(インスタンスコンテキストなし)は、このチョークポイントから
285
+ * アイコンを得ます。per-instance の差し替えは `grid.setIcon()`(このレジストリの child)で、グローバルな拡張は
286
+ * `defineIconSet()` で行います。
287
+ *
288
+ * CellRenderer 等由工厂创建的渲染器(没有实例上下文)通过这个必经点获取图标。
289
+ * per-instance 的替换走 `grid.setIcon()`(本注册表的 child),全局扩展走 `defineIconSet()`。
90
290
  */
91
291
  export declare const iconRegistry: IconRegistry;
92
292
  /**
93
293
  * 편의 정적 render — 공유 기본 레지스트리로 위임(`IconRegistry.render(role, opts)`).
94
- * / Convenience static render — delegates to the shared default registry (`IconRegistry.render(role, opts)`).
95
294
  *
96
- * @param role - 렌더할 역할 키 / Role key to render
97
- * @param opts - 렌더 옵션 / Render options
98
- * @returns SVG 마크업 문자열 또는 SVGElement(opts.el) / SVG markup string, or SVGElement when opts.el
295
+ * Convenience static render — delegates to the shared default registry (`IconRegistry.render(role, opts)`).
296
+ *
297
+ * 便利な静的 render — 共有の既定レジストリに委譲します(`IconRegistry.render(role, opts)`)。
298
+ *
299
+ * 便捷的静态 render — 委托给共享的默认注册表(`IconRegistry.render(role, opts)`)。
300
+ *
301
+ * @param role - 렌더할 역할 키
302
+ *
303
+ * Role key to render
304
+ *
305
+ * レンダーする役割キー
306
+ *
307
+ * 要渲染的角色键
308
+ *
309
+ * @param opts - 렌더 옵션
310
+ *
311
+ * Render options
312
+ *
313
+ * レンダーオプション
314
+ *
315
+ * 渲染选项
316
+ *
317
+ * @returns SVG 마크업 문자열 또는 SVGElement(opts.el)
318
+ *
319
+ * SVG markup string, or SVGElement when opts.el
320
+ *
321
+ * SVG マークアップ文字列、または SVGElement(opts.el の場合)
322
+ *
323
+ * SVG 标记字符串,或指定 opts.el 时返回 SVGElement
324
+ *
99
325
  * @example
100
326
  * el.innerHTML = renderIcon('filter') as string;
101
327
  */