open-grid 1.5.2 → 1.6.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.
Files changed (77) hide show
  1. package/CHANGELOG.md +475 -416
  2. package/README.ja.md +39 -0
  3. package/README.md +39 -0
  4. package/README.zh.md +39 -0
  5. package/dist/{OpenGrid-CT9bV6On.cjs → OpenGrid-CLk8Vt7j.cjs} +1390 -1316
  6. package/dist/{OpenGrid-DACnZdEy.js → OpenGrid-D6YxCsnV.js} +1757 -1683
  7. package/dist/angular/fesm2022/open-grid-angular.mjs +247 -0
  8. package/dist/angular/index.d.ts +5 -0
  9. package/dist/angular/lib/open-grid.component.d.ts +97 -0
  10. package/dist/angular/public-api.d.ts +6 -0
  11. package/dist/{index-Brfso4Ry.cjs → index-D0DJtKYI.cjs} +2 -2
  12. package/dist/{index-al9Mbv3E.js → index-VkKgQ506.js} +2 -2
  13. package/dist/open-grid-a11y.cjs +216 -0
  14. package/dist/open-grid-a11y.js +219 -0
  15. package/dist/open-grid-base.css +13 -4
  16. package/dist/open-grid-header.cjs +4 -4
  17. package/dist/open-grid-header.css +18 -27
  18. package/dist/open-grid-header.js +4 -4
  19. package/dist/open-grid-react.cjs +1 -1
  20. package/dist/open-grid-react.js +1 -1
  21. package/dist/open-grid-skins.css +2 -2
  22. package/dist/open-grid-themes.css +19 -19
  23. package/dist/open-grid-typography.cjs +2 -2
  24. package/dist/open-grid-typography.js +2 -2
  25. package/dist/open-grid-vue.cjs +1 -1
  26. package/dist/open-grid-vue.js +1 -1
  27. package/dist/open-grid.cjs +5 -2
  28. package/dist/open-grid.js +6 -3
  29. package/dist/types/a11y/index.d.ts +37 -0
  30. package/dist/types/core/ColumnLayout.d.ts +3 -3
  31. package/dist/types/core/DetailManager.d.ts +1 -1
  32. package/dist/types/core/ExportManager.d.ts +9 -6
  33. package/dist/types/core/ExtensionPointRegistry.d.ts +2 -2
  34. package/dist/types/core/FlatRowModel.d.ts +8 -0
  35. package/dist/types/core/MergeEngine.d.ts +45 -5
  36. package/dist/types/core/MutationService.d.ts +4 -9
  37. package/dist/types/core/OpenGrid.d.ts +357 -16
  38. package/dist/types/core/OrgChart.d.ts +24 -0
  39. package/dist/types/core/RowDragDrop.d.ts +2 -0
  40. package/dist/types/core/SortFilterManager.d.ts +8 -0
  41. package/dist/types/core/WorksheetManager.d.ts +2 -2
  42. package/dist/types/core/a11y/KeyboardInteractionModel.d.ts +321 -20
  43. package/dist/types/core/a11y/LiveRegionController.d.ts +229 -27
  44. package/dist/types/core/a11y/VisualEquivRegistry.d.ts +199 -14
  45. package/dist/types/core/appearance/AppearanceAxis.d.ts +54 -6
  46. package/dist/types/core/appearance/HeaderRegistry.d.ts +213 -21
  47. package/dist/types/core/appearance/TextureRegistry.d.ts +10 -0
  48. package/dist/types/core/appearance/TypographyRegistry.d.ts +63 -3
  49. package/dist/types/core/cf/CFRule.d.ts +145 -22
  50. package/dist/types/core/chart/DataExtractor.d.ts +1 -1
  51. package/dist/types/core/detail/DetailGlyph.d.ts +3 -3
  52. package/dist/types/core/types.d.ts +511 -31
  53. package/dist/types/header/index.d.ts +146 -6
  54. package/dist/types/index.d.ts +31 -1
  55. package/dist/types/typography/index.d.ts +134 -4
  56. package/dist/types/vue/OpenGrid.vue.d.ts +1 -1
  57. package/package.json +47 -13
  58. package/dist/OpenGrid-CT9bV6On.cjs.map +0 -1
  59. package/dist/OpenGrid-DACnZdEy.js.map +0 -1
  60. package/dist/Registry-CPJYOqCn.js.map +0 -1
  61. package/dist/Registry-D74ZmdDz.cjs.map +0 -1
  62. package/dist/index-Brfso4Ry.cjs.map +0 -1
  63. package/dist/index-CeJ-0-80.cjs.map +0 -1
  64. package/dist/index-DnarQ4eR.js.map +0 -1
  65. package/dist/index-al9Mbv3E.js.map +0 -1
  66. package/dist/open-grid-header.cjs.map +0 -1
  67. package/dist/open-grid-header.js.map +0 -1
  68. package/dist/open-grid-react.cjs.map +0 -1
  69. package/dist/open-grid-react.js.map +0 -1
  70. package/dist/open-grid-typography.cjs.map +0 -1
  71. package/dist/open-grid-typography.js.map +0 -1
  72. package/dist/open-grid-vue.cjs.map +0 -1
  73. package/dist/open-grid-vue.js.map +0 -1
  74. package/dist/open-grid.cjs.map +0 -1
  75. package/dist/open-grid.js.map +0 -1
  76. package/dist/xlsx.min-BQ1o3sB6.cjs.map +0 -1
  77. package/dist/xlsx.min-Bbz2ZypC.js.map +0 -1
@@ -1,47 +1,178 @@
1
1
  import { MessageParams } from '../i18n/types.js';
2
2
  import { IAriaRenderPort, LiveChannel } from './ports.js';
3
3
  /**
4
- * 공지 1건 — 텍스트가 아니라 (채널·우선순위·병합키·메시지키·페이로드) 구조. 병합·중복억제의 단위.
5
- * / One announcement — a (channel, priority, mergeKey, messageKey, payload) structure, not raw text.
4
+ * 화면 낭독기에 알릴 공지 한 건. 글 자체가 아니라 메시지 키와 값으로 주면, 컨트롤러가 겹친 공지를 합치고 순서를 정해 한 번에 읽힌다.
5
+ *
6
+ * One announcement for screen readers. Give a message key and values rather than the text itself; the controller merges overlapping announcements, orders them and has them read once.
7
+ *
8
+ * スクリーンリーダーに知らせるお知らせ 1 件。文そのものではなくメッセージキーと値で渡すと、コントローラーが重なったお知らせをまとめ、順番を決めて一度に読ませます。
9
+ *
10
+ * 要告知屏幕阅读器的一条通知。不是直接给文字,而是给消息键和值;控制器会合并重叠的通知、排好顺序后一次性朗读。
6
11
  */
7
12
  export interface Announcement {
8
- /** 라이브영역 채널. polite=대기열 합류, assertive=즉시(오류). / Live channel. */
13
+ /**
14
+ * `polite`=지금 읽는 것이 끝난 뒤 읽는다, `assertive`=곧바로 끼어들어 읽는다(오류 등).
15
+ *
16
+ * `polite` = read after the current speech; `assertive` = interrupt and read at once (errors, etc.).
17
+ *
18
+ * `polite`=いま読んでいるものが終わってから読む、`assertive`=すぐ割り込んで読む(エラーなど)。
19
+ *
20
+ * `polite`=等当前朗读结束后再读;`assertive`=立即插入朗读(错误等)。
21
+ */
9
22
  readonly channel: LiveChannel;
10
- /** 우선순위(같은 채널 내 경합 시 큰 값 우선). 예 오류>편집완료>선택. / Priority (higher wins within a channel). */
23
+ /**
24
+ * 우선순위. 같은 채널에서 여러 건이 한꺼번에 나갈 때 큰 값을 먼저 읽는다(예: 오류 > 편집 완료 > 선택).
25
+ *
26
+ * Priority. When several go out together on one channel, higher values are read first (e.g. error > edit done > selection).
27
+ *
28
+ * 優先度。同じチャンネルで複数件が一度に出るとき、大きい値から先に読みます(例: エラー > 編集完了 > 選択)。
29
+ *
30
+ * 优先级。同一通道上有多条同时发出时,值大的先读(例如 错误 > 编辑完成 > 选择)。
31
+ */
11
32
  readonly priority: number;
12
33
  /**
13
- * 병합키 — 같은 키의 연속 공지는 마지막 1건으로 병합(coalesce). 예 'sort'·'selection'·'bg-update'.
14
- * 빠른 연속 정렬이 마지막 상태만 1회 발화되게 하는 핵심(REQ-T9-821 AC).
15
- * / Merge key — successive announcements with the same key coalesce to the latest one.
34
+ * 합치기 키. 같은 키로 잇달아 들어온 공지는 마지막 한 건만 읽는다(예: 'sort'·'selection'). 정렬을 빠르게 여러 번 바꿔도 마지막 상태만 한 번 읽힌다.
35
+ *
36
+ * Merge key. Announcements arriving in a row with the same key are read only once, as the latest (e.g. 'sort', 'selection'). Changing the sort quickly several times reads only the final state once.
37
+ *
38
+ * まとめキー。同じキーで続けて入ったお知らせは最後の 1 件だけを読みます(例: 'sort'・'selection')。並べ替えを素早く何度変えても、最後の状態だけが一度読まれます。
39
+ *
40
+ * 合并键。以同一键连续到来的通知只读最后一条(例如 'sort'、'selection')。即使快速多次改变排序,也只读一次最终状态。
16
41
  */
17
42
  readonly mergeKey: string;
18
- /** i18n 메시지 키(컨트롤러가 `t()` 로 해석; 하드코딩 문자열 금지). / i18n message key (resolved via `t()`). */
43
+ /**
44
+ * 메시지 키. 컨트롤러가 `t` 옵션으로 글로 바꾼다(`t` 를 안 주면 키를 그대로 읽는다).
45
+ *
46
+ * Message key. The controller turns it into text with the `t` option (without `t`, the key itself is read).
47
+ *
48
+ * メッセージキー。コントローラーが `t` オプションで文に変えます(`t` を渡さなければキーをそのまま読みます)。
49
+ *
50
+ * 消息键。控制器用 `t` 选项把它变成文字(不传 `t` 则直接朗读键本身)。
51
+ */
19
52
  readonly messageKey: string;
20
- /** 보간 파라미터. / Interpolation params. */
53
+ /**
54
+ * 메시지에 끼울 값(예: `{ field: '이름' }`).
55
+ *
56
+ * Values to fill into the message (e.g. `{ field: 'Name' }`).
57
+ *
58
+ * メッセージに差し込む値(例: `{ field: '名前' }`)。
59
+ *
60
+ * 要填入消息的值(例如 `{ field: '名称' }`)。
61
+ */
21
62
  readonly params?: MessageParams;
22
- /** 배경(비-사용자) 변경 표식 — 편집/포커스 중 억제 대상(REQ-T9-822). / Background (non-user) change flag. */
63
+ /**
64
+ * 사용자가 한 일이 아닌 바탕 변경(실시간 갱신 등)이면 `true`. 사용자가 편집 중일 때(`setUserBusy(true)`)는 미뤄 두었다가 끝나면 읽는다.
65
+ *
66
+ * `true` for a background change the user did not make (live updates, etc.). While the user is busy (`setUserBusy(true)`) it is held and read afterwards.
67
+ *
68
+ * 利用者の操作ではない裏側の変更(リアルタイム更新など)なら `true`。利用者が編集中(`setUserBusy(true)`)は保留し、終わってから読みます。
69
+ *
70
+ * 如果是非用户操作的后台变化(实时更新等)则为 `true`。用户正在编辑时(`setUserBusy(true)`)会暂缓,结束后再读。
71
+ */
23
72
  readonly background?: boolean;
24
73
  }
25
- /** 주입 가능한 타이머 핸들·스케줄러(결정론 테스트용). / Injectable timer handle & scheduler (for deterministic tests). */
74
+ /**
75
+ * `schedule` 옵션이 돌려주는 타이머 손잡이(`setTimeout` 의 반환값과 같은 역할).
76
+ *
77
+ * The timer handle the `schedule` option returns (the same role as `setTimeout`'s return value).
78
+ *
79
+ * `schedule` オプションが返すタイマーのハンドル(`setTimeout` の戻り値と同じ役割)。
80
+ *
81
+ * `schedule` 选项返回的定时器句柄(作用与 `setTimeout` 的返回值相同)。
82
+ */
26
83
  export type TimerHandle = unknown;
27
- /** `LiveRegionController` 구성. render 는 필수 의존(교차리뷰 R: opts 전체 옵셔널 금지). / Controller config. */
84
+ /**
85
+ * `LiveRegionController` 설정. `render` 만 필수다.
86
+ *
87
+ * `LiveRegionController` settings. Only `render` is required.
88
+ *
89
+ * `LiveRegionController` の設定。必須は `render` だけです。
90
+ *
91
+ * `LiveRegionController` 的设置。只有 `render` 是必需的。
92
+ */
28
93
  export interface LiveRegionControllerOpts {
29
- /** aria/공지 물질화 포트(필수). / aria/announcement materialization port (required). */
30
- readonly render: IAriaRenderPort;
31
- /** 메시지 해석기(하드코딩 금지). 미주입 시 키 원문 반환(항등). / Message resolver; defaults to identity (key). */
94
+ /**
95
+ * 공지를 실제로 화면(aria-live 영역)에 적는 곳. `announce(channel, text)` 하나만 있으면 된다.
96
+ *
97
+ * Where announcements are actually written to the page (an aria-live region). Only `announce(channel, text)` is needed.
98
+ *
99
+ * お知らせを実際に画面(aria-live 領域)へ書く場所。`announce(channel, text)` が一つあれば足ります。
100
+ *
101
+ * 把通知实际写到页面(aria-live 区域)的地方。只需要一个 `announce(channel, text)`。
102
+ */
103
+ readonly render: Pick<IAriaRenderPort, 'announce'>;
104
+ /**
105
+ * 메시지 키를 글로 바꾸는 함수. 주지 않으면 키를 그대로 쓴다.
106
+ *
107
+ * Turns a message key into text. Without it the key is used as is.
108
+ *
109
+ * メッセージキーを文に変える関数。渡さなければキーをそのまま使います。
110
+ *
111
+ * 把消息键变成文字的函数。不传则直接使用键。
112
+ */
32
113
  readonly t?: (key: string, params?: MessageParams) => string;
33
- /** polite 디바운스(ms). 기본 150. / polite debounce (ms). Default 150. */
114
+ /**
115
+ * `polite` 공지를 모았다가 읽기까지 기다리는 시간(ms). 기본 150.
116
+ *
117
+ * How long `polite` announcements are collected before being read (ms). Default 150.
118
+ *
119
+ * `polite` のお知らせを集めてから読むまで待つ時間(ms)。既定 150。
120
+ *
121
+ * 收集 `polite` 通知后等待朗读的时间(毫秒)。默认 150。
122
+ */
34
123
  readonly debounceMs?: number;
35
- /** assertive 즉시 발화(디바운스 우회, R1). 기본 true. / assertive immediate (bypass debounce). Default true. */
124
+ /**
125
+ * `assertive` 공지를 기다리지 않고 곧바로 읽을지. 기본 `true`.
126
+ *
127
+ * Whether `assertive` announcements are read at once without waiting. Default `true`.
128
+ *
129
+ * `assertive` のお知らせを待たずにすぐ読むかどうか。既定 `true`。
130
+ *
131
+ * 是否不等待立即朗读 `assertive` 通知。默认 `true`。
132
+ */
36
133
  readonly assertiveImmediate?: boolean;
37
- /** 타이머 예약(기본 setTimeout). / Schedule a timer (defaults to setTimeout). */
134
+ /**
135
+ * 타이머 걸기(기본 `setTimeout`). 테스트에서 시간을 직접 돌릴 때 바꿔 끼운다.
136
+ *
137
+ * Schedules a timer (default `setTimeout`). Swap it in tests to drive time yourself.
138
+ *
139
+ * タイマーを掛ける(既定 `setTimeout`)。テストで時間を自分で進めるときに差し替えます。
140
+ *
141
+ * 设置定时器(默认 `setTimeout`)。在测试中自己推进时间时替换它。
142
+ */
38
143
  readonly schedule?: (fn: () => void, ms: number) => TimerHandle;
39
- /** 타이머 취소(기본 clearTimeout). / Cancel a timer (defaults to clearTimeout). */
144
+ /**
145
+ * 타이머 취소(기본 `clearTimeout`).
146
+ *
147
+ * Cancels a timer (default `clearTimeout`).
148
+ *
149
+ * タイマーの取り消し(既定 `clearTimeout`)。
150
+ *
151
+ * 取消定时器(默认 `clearTimeout`)。
152
+ */
40
153
  readonly cancel?: (h: TimerHandle) => void;
41
154
  }
42
155
  /**
43
- * aria-live 경계의 문지기. 위젯의 직접 라이브영역 `textContent =` 접근을 대체한다(불변식 4).
44
- * / Gatekeeper of the aria-live boundary; replaces direct live-region `textContent =` access.
156
+ * 화면 낭독기 공지를 한곳에서 관리한다. 여러 곳에서 공지를 넣어도 같은 종류는 마지막 것만, 중요한 것부터, 잠깐 모았다가 한 번에 읽힌다.
157
+ * 그래서 정렬을 빠르게 바꾸거나 값이 쏟아져도 낭독기가 같은 말을 되풀이하지 않는다.
158
+ *
159
+ * Manages screen-reader announcements in one place. However many places enqueue, only the latest of each kind is read, most important first, after a short wait.
160
+ * So rapid sort changes or a flood of updates do not make the screen reader repeat itself.
161
+ *
162
+ * スクリーンリーダーへのお知らせを一か所で管理します。何か所からお知らせを入れても、同じ種類は最後のものだけを、重要なものから、少しまとめてから一度に読ませます。
163
+ * そのため、並べ替えを素早く変えたり値が次々に変わったりしても、スクリーンリーダーが同じことを繰り返しません。
164
+ *
165
+ * 在一处管理屏幕阅读器的通知。无论从多少处放入通知,同类只读最后一条,从重要的开始,稍作收集后一次朗读。
166
+ * 因此即使快速改变排序或数值大量涌入,屏幕阅读器也不会重复同样的话。
167
+ *
168
+ * @example
169
+ * const politeEl = document.getElementById('live-polite')!; // <div aria-live="polite">
170
+ * const alertEl = document.getElementById('live-assertive')!; // <div aria-live="assertive">
171
+ * const live = new LiveRegionController({
172
+ * render: { announce: (channel, text) => { (channel === 'assertive' ? alertEl : politeEl).textContent = text; } },
173
+ * t: (key, params) => myMessages(key, params), // 번역 함수가 없으면 이 줄을 빼고 messageKey 에 문장을 그대로 넣어도 된다
174
+ * });
175
+ * grid.on('sortChange', (e) => live.enqueue({ channel: 'polite', priority: 1, mergeKey: 'sort', messageKey: 'sorted', params: { field: e.field } }));
45
176
  */
46
177
  export declare class LiveRegionController {
47
178
  private readonly _render;
@@ -62,23 +193,94 @@ export declare class LiveRegionController {
62
193
  private _dropped;
63
194
  constructor(opts: LiveRegionControllerOpts);
64
195
  /**
65
- * 공지 투입 — 즉시 발화 아님(assertive-immediate 제외). 같은 mergeKey 는 큐에서 최신으로 대체(병합).
66
- * / Enqueue — not spoken immediately (except assertive-immediate). Same mergeKey replaces (coalesce).
196
+ * 공지를 넣는다. 곧바로 읽지 않고 잠깐 모은다(`assertive` 는 곧바로). 같은 `mergeKey` 가 기다리고 있으면 새 것으로 바꾼다.
197
+ *
198
+ * Enqueues an announcement. It is not read at once but collected briefly (`assertive` is read at once). If one with the same `mergeKey` is waiting, it is replaced by the new one.
199
+ *
200
+ * お知らせを入れます。すぐには読まず少しまとめます(`assertive` はすぐ)。同じ `mergeKey` が待っていれば新しいものに置き換えます。
201
+ *
202
+ * 放入通知。不会立即朗读,而是稍作收集(`assertive` 立即读)。如果有相同 `mergeKey` 的通知在等待,就换成新的。
203
+ *
204
+ * @param a - 공지
205
+ *
206
+ * The announcement
207
+ *
208
+ * お知らせ
209
+ *
210
+ * 通知
67
211
  */
68
212
  enqueue(a: Announcement): void;
69
- /** 편집/포커스 중 배경 공지 억제 게이트(REQ-T9-822). false 전환 시 억제분 방출. / Suppress background while busy. */
213
+ /**
214
+ * 사용자가 편집 중인지 알린다. `true` 인 동안 바탕 변경 공지(`background: true`)는 미뤄 두고, `false` 로 돌아오면 모아 둔 것을 읽는다.
215
+ *
216
+ * Tells whether the user is busy editing. While `true`, background announcements (`background: true`) are held; when it goes back to `false` the held ones are read.
217
+ *
218
+ * 利用者が編集中かどうかを知らせます。`true` の間は裏側の変更のお知らせ(`background: true`)を保留し、`false` に戻るとためておいたものを読みます。
219
+ *
220
+ * 告知用户是否正在编辑。为 `true` 期间,后台变化通知(`background: true`)会暂缓;回到 `false` 时朗读暂存的通知。
221
+ *
222
+ * @param busy - 편집 중이면 `true`
223
+ *
224
+ * `true` while editing
225
+ *
226
+ * 編集中なら `true`
227
+ *
228
+ * 编辑中为 `true`
229
+ *
230
+ * @example
231
+ * grid.on('editStart', () => live.setUserBusy(true));
232
+ * grid.on('editEnd', () => live.setUserBusy(false));
233
+ */
70
234
  setUserBusy(busy: boolean): void;
71
235
  /**
72
- * stale 공지 취소 — 큐에서 mergeKey 를 제거하고 dropped 계측(UC-2 E1: 정렬 대상 소멸).
73
- * / Drop a stale announcement — remove the mergeKey from queues, count as dropped.
236
+ * 기다리던 공지를 버린다(예: 알릴 대상이 사라졌을 때).
237
+ *
238
+ * Discards a waiting announcement (e.g. when what it was about is gone).
239
+ *
240
+ * 待っていたお知らせを捨てます(例: 知らせる対象がなくなったとき)。
241
+ *
242
+ * 丢弃正在等待的通知(例如要告知的对象已经消失时)。
243
+ *
244
+ * @param mergeKey - 버릴 공지의 합치기 키
245
+ *
246
+ * Merge key of the announcement to discard
247
+ *
248
+ * 捨てるお知らせのまとめキー
249
+ *
250
+ * 要丢弃的通知的合并键
74
251
  */
75
252
  drop(mergeKey: string): void;
76
- /** 계측: 발화 수·병합으로 삭제된 중복 수·drop 수(REQ-T9-821 중복률 0 계측 SSOT). / Metrics. */
253
+ /**
254
+ * 지금까지의 수: 읽힌 수(`spoken`)·합쳐져 빠진 수(`coalesced`)·버린 수(`dropped`).
255
+ *
256
+ * Counts so far: read (`spoken`), merged away (`coalesced`), discarded (`dropped`).
257
+ *
258
+ * これまでの数: 読まれた数(`spoken`)・まとめられて消えた数(`coalesced`)・捨てた数(`dropped`)。
259
+ *
260
+ * 到目前为止的数量:已朗读(`spoken`)、被合并掉(`coalesced`)、已丢弃(`dropped`)。
261
+ *
262
+ * @returns 세 가지 수
263
+ *
264
+ * The three counts
265
+ *
266
+ * 三つの数
267
+ *
268
+ * 三个数量
269
+ */
77
270
  metrics(): {
78
271
  spoken: number;
79
272
  coalesced: number;
80
273
  dropped: number;
81
274
  };
275
+ /**
276
+ * 정리한다: 기다리던 공지와 타이머를 버리고, 이후 `enqueue` 는 무시한다.
277
+ *
278
+ * Cleans up: discards waiting announcements and the timer; later `enqueue` calls are ignored.
279
+ *
280
+ * 後片付けをします: 待っていたお知らせとタイマーを捨て、その後の `enqueue` は無視します。
281
+ *
282
+ * 清理:丢弃等待中的通知和定时器,之后的 `enqueue` 会被忽略。
283
+ */
82
284
  dispose(): void;
83
285
  private _scheduleFlush;
84
286
  /** 디바운스 만료 flush — 채널별 우선순위 정렬 → mergeKey 최신 1건씩 발화. / Debounced flush. */
@@ -1,37 +1,222 @@
1
1
  import { RegisterOptions, RegisterResult } from '../extension/Registry.js';
2
2
  /**
3
- * 시각 인코딩 종류 → 텍스트 등가 provider. `describe` 는 시각 모델을 받아 낭독 문자열을 산출한다
4
- * (헤드리스 순수 — DOM 미참조). 차트는 기존 `chart/a11y.chartAriaLabel` 을 감싸 등록할 수 있다.
5
- * / A text-equivalent provider for a visual-encoding kind. `describe` produces the spoken string
6
- * from a visual model (headless/pure). Charts can wrap `chart/a11y.chartAriaLabel`.
3
+ * 그림(스파크라인·데이터바·증감 화살표 등) 한 종류를 말로 바꾸는 방법. `describe` 가 그림의 값을 받아 낭독할 글을 돌려준다.
4
+ *
5
+ * How to put one kind of picture (sparkline, data bar, up/down arrow, …) into words. `describe` takes the picture's values and returns the text to read.
6
+ *
7
+ * 絵(スパークライン・データバー・増減の矢印など)一種類を言葉に変える方法。`describe` が絵の値を受け取り、読み上げる文を返します。
8
+ *
9
+ * 把一种图形(迷你折线、数据条、增减箭头等)转换成文字的方法。`describe` 接收图形的值并返回要朗读的文字。
7
10
  */
8
11
  export interface VisualEquivProvider<M = unknown> {
9
- /** 'chart' | 'sparkline' | 'databar' | 'delta' | 'iconset' … / Visual-encoding kind. */
12
+ /**
13
+ * 그림 종류 이름(예: 'sparkline'·'delta').
14
+ *
15
+ * The picture kind (e.g. 'sparkline', 'delta').
16
+ *
17
+ * 絵の種類の名前(例: 'sparkline'・'delta')。
18
+ *
19
+ * 图形种类名称(例如 'sparkline'、'delta')。
20
+ */
10
21
  readonly kind: string;
11
- /** 시각 모델 → 낭독 텍스트. / Visual model → spoken text. */
22
+ /**
23
+ * 그림의 값을 받아 낭독할 글을 돌려준다.
24
+ *
25
+ * Takes the picture's values and returns the text to read.
26
+ *
27
+ * 絵の値を受け取り、読み上げる文を返します。
28
+ *
29
+ * 接收图形的值并返回要朗读的文字。
30
+ */
12
31
  describe(model: M): string;
13
32
  }
14
33
  /**
15
- * 텍스트 등가 provider 등록 게이트. `TypedRegistry` 를 감싸 도메인 API 를 제공한다(재구현 0, C1).
16
- * / The text-equivalent provider gate. Wraps `TypedRegistry` with a domain API (no reimplementation).
34
+ * 그림을 말로 바꾸는 방법(`VisualEquivProvider`)을 종류별로 모아 둔다. 등록 안 된 종류를 읽으려 하면 빈 글을 돌려주고 경고로 알려 준다 — 그림 셀이 낭독에서 빠지는 것을 조용히 넘기지 않게.
35
+ * 셀에 붙이려면 컬럼의 `ariaLabel` 에서 `describe` 를 부른다.
36
+ *
37
+ * Collects, per kind, the ways to put pictures into words (`VisualEquivProvider`). Reading a kind that is not registered returns empty text and raises a warning, so a picture cell missing from speech is not passed over silently.
38
+ * To attach it to cells, call `describe` from the column's `ariaLabel`.
39
+ *
40
+ * 絵を言葉に変える方法(`VisualEquivProvider`)を種類ごとにまとめておきます。登録されていない種類を読もうとすると空の文を返し、警告で知らせます — 絵のセルが読み上げから抜けるのを黙って見過ごさないように。
41
+ * セルに付けるには、列の `ariaLabel` から `describe` を呼びます。
42
+ *
43
+ * 按种类收集把图形转换成文字的方法(`VisualEquivProvider`)。试图朗读未注册的种类时返回空文字并发出警告 — 以免图形单元格从朗读中漏掉却无人察觉。
44
+ * 要用到单元格上,请在列的 `ariaLabel` 中调用 `describe`。
45
+ *
46
+ * @example
47
+ * const equiv = new VisualEquivRegistry(console.warn);
48
+ * equiv.register({ kind: 'sparkline', describe: (s: number[]) => `최근 ${s.length}개월, 마지막 값 ${s[s.length - 1]}` });
49
+ * columns: [{ field: 'trend', header: '추세', ariaLabel: (v) => equiv.describe('sparkline', v) }]
17
50
  */
18
51
  export declare class VisualEquivRegistry {
19
52
  private readonly _reg;
20
53
  private readonly _onWarn;
54
+ /**
55
+ * 등록소를 만든다.
56
+ *
57
+ * Creates the registry.
58
+ *
59
+ * 登録所を作ります。
60
+ *
61
+ * 创建注册表。
62
+ *
63
+ * @param onWarn - 경고를 받을 함수(예: `console.warn`). 주지 않으면 경고를 버린다.
64
+ *
65
+ * Receives warnings (e.g. `console.warn`). Without it warnings are dropped.
66
+ *
67
+ * 警告を受け取る関数(例: `console.warn`)。渡さなければ警告は捨てます。
68
+ *
69
+ * 接收警告的函数(例如 `console.warn`)。不传则丢弃警告。
70
+ */
21
71
  constructor(onWarn?: (msg: string) => void);
22
- /** provider 등록(정책 적용, never-throw). / Register a provider (policy-applied, never-throw). */
72
+ /**
73
+ * 그림 한 종류를 말로 바꾸는 방법을 등록한다. 예외를 던지지 않고 결과로 알려 준다.
74
+ *
75
+ * Registers how to put one picture kind into words. It never throws; the outcome is in the result.
76
+ *
77
+ * 絵一種類を言葉に変える方法を登録します。例外は投げず、結果で知らせます。
78
+ *
79
+ * 注册把一种图形转换成文字的方法。不会抛出异常,结果通过返回值告知。
80
+ *
81
+ * @param provider - 등록할 방법
82
+ *
83
+ * The provider to register
84
+ *
85
+ * 登録する方法
86
+ *
87
+ * 要注册的方法
88
+ *
89
+ * @param opts - 등록 규칙(같은 종류가 있을 때 등)
90
+ *
91
+ * Registration rules (e.g. when the kind already exists)
92
+ *
93
+ * 登録の規則(同じ種類があるときなど)
94
+ *
95
+ * 注册规则(例如已存在同一种类时)
96
+ *
97
+ * @returns 등록 결과
98
+ *
99
+ * The registration result
100
+ *
101
+ * 登録の結果
102
+ *
103
+ * 注册结果
104
+ */
23
105
  register(provider: VisualEquivProvider, opts?: RegisterOptions): RegisterResult;
24
- /** 등록 여부(게이트 판정 — 미등록 시 CI 실패의 근거). / Whether the kind is registered (CI-gate basis). */
106
+ /**
107
+ * 그 종류가 등록돼 있는지.
108
+ *
109
+ * Whether the kind is registered.
110
+ *
111
+ * その種類が登録されているかどうか。
112
+ *
113
+ * 该种类是否已注册。
114
+ *
115
+ * @param kind - 그림 종류 이름
116
+ *
117
+ * Picture kind
118
+ *
119
+ * 絵の種類の名前
120
+ *
121
+ * 图形种类名称
122
+ */
25
123
  has(kind: string): boolean;
124
+ /**
125
+ * 그 종류의 방법을 돌려준다(없으면 `undefined`).
126
+ *
127
+ * Returns the provider for the kind (`undefined` if none).
128
+ *
129
+ * その種類の方法を返します(なければ `undefined`)。
130
+ *
131
+ * 返回该种类的方法(没有则为 `undefined`)。
132
+ *
133
+ * @param kind - 그림 종류 이름
134
+ *
135
+ * Picture kind
136
+ *
137
+ * 絵の種類の名前
138
+ *
139
+ * 图形种类名称
140
+ */
26
141
  get(kind: string): VisualEquivProvider | undefined;
27
- /** 등록된 종류 목록. / Registered kinds. */
142
+ /**
143
+ * 등록된 종류 이름들.
144
+ *
145
+ * Names of the registered kinds.
146
+ *
147
+ * 登録されている種類の名前。
148
+ *
149
+ * 已注册的种类名称。
150
+ */
28
151
  list(): string[];
29
152
  /**
30
- * 텍스트 등가 산출(never-throw). 미등록 종류면 빈 문자열 + 경고(침묵 금지·게이트 신호).
31
- * / Produce the text equivalent (never-throw). Unregistered kind → empty string + warning.
153
+ * 그림의 값을 낭독할 글로 바꾼다. 등록 안 된 종류면 빈 글을 돌려주고 `onWarn` 으로 알린다(예외는 던지지 않는다).
154
+ *
155
+ * Turns a picture's values into text to read. For an unregistered kind it returns empty text and reports through `onWarn` (it never throws).
156
+ *
157
+ * 絵の値を読み上げる文に変えます。登録されていない種類なら空の文を返し、`onWarn` で知らせます(例外は投げません)。
158
+ *
159
+ * 把图形的值转换成要朗读的文字。未注册的种类返回空文字并通过 `onWarn` 告知(不会抛出异常)。
160
+ *
161
+ * @param kind - 그림 종류 이름
162
+ *
163
+ * Picture kind
164
+ *
165
+ * 絵の種類の名前
166
+ *
167
+ * 图形种类名称
168
+ *
169
+ * @param model - 그림의 값
170
+ *
171
+ * The picture's values
172
+ *
173
+ * 絵の値
174
+ *
175
+ * 图形的值
176
+ *
177
+ * @returns 낭독할 글
178
+ *
179
+ * The text to read
180
+ *
181
+ * 読み上げる文
182
+ *
183
+ * 要朗读的文字
32
184
  */
33
185
  describe(kind: string, model: unknown): string;
34
- /** 플러그인 단위 일괄 해제. / Batch dispose by plugin. */
186
+ /**
187
+ * 한 플러그인이 등록한 것을 한꺼번에 뺀다.
188
+ *
189
+ * Removes everything one plugin registered.
190
+ *
191
+ * 一つのプラグインが登録したものをまとめて外します。
192
+ *
193
+ * 一次性移除某个插件注册的全部内容。
194
+ *
195
+ * @param pluginId - 플러그인 이름
196
+ *
197
+ * Plugin id
198
+ *
199
+ * プラグイン名
200
+ *
201
+ * 插件名
202
+ *
203
+ * @returns 뺀 수
204
+ *
205
+ * How many were removed
206
+ *
207
+ * 外した数
208
+ *
209
+ * 移除的数量
210
+ */
35
211
  disposePlugin(pluginId: string): number;
212
+ /**
213
+ * 등록소를 비우고 정리한다.
214
+ *
215
+ * Empties and cleans up the registry.
216
+ *
217
+ * 登録所を空にして後片付けします。
218
+ *
219
+ * 清空并清理注册表。
220
+ */
36
221
  dispose(): void;
37
222
  }
@@ -1,6 +1,14 @@
1
1
  /** 외관 축 식별자. 이름공간(prefix)이 물리 직교의 열쇠. / Appearance axis id; the token prefix is the key to physical orthogonality. */
2
2
  export type AxisId = 'theme' | 'skin' | 'density' | 'texture' | 'icon' | 'typography' | 'header';
3
- /** 한 축의 CSS 변수 델타(자기 이름공간만). / A CSS-var delta for one axis (own namespace only). */
3
+ /**
4
+ * 한 축의 CSS 변수 델타(자기 이름공간만).
5
+ *
6
+ * A CSS-var delta for one axis (own namespace only).
7
+ *
8
+ * 一つの軸の CSS 変数デルタ(自分の名前空間だけ)。
9
+ *
10
+ * 一个轴的 CSS 变量增量(只含自己的命名空间)。
11
+ */
4
12
  export type TokenDelta = Readonly<Record<string, string>>;
5
13
  /** 컨테이너에 붙일 data-* 속성. / A data-* attribute to place on the container. */
6
14
  export interface AxisAttr {
@@ -19,7 +27,15 @@ export interface AxisResolution {
19
27
  /** 이 선택이 재계산을 요구하는가(밀도 = 행높이 relayout). / Does this selection require recompute (density → row-height relayout)? */
20
28
  readonly requiresRelayout?: boolean;
21
29
  }
22
- /** 축 정의 결과 — 등록된(가드레일 반영) 델타 + 경고. / Axis-definition result — registered (clamped) delta + warnings. */
30
+ /**
31
+ * 축 정의 결과 — 등록된(가드레일 반영) 델타 + 경고.
32
+ *
33
+ * Axis-definition result — registered (clamped) delta + warnings.
34
+ *
35
+ * 軸の定義結果 — 登録された(ガードレール反映後の)デルタ + 警告。
36
+ *
37
+ * 轴的定义结果 — 注册后(经护栏钳制)的增量 + 警告。
38
+ */
23
39
  export interface AxisDefineResult {
24
40
  readonly delta: TokenDelta;
25
41
  readonly warnings: string[];
@@ -31,15 +47,47 @@ export interface AxisDefineResult {
31
47
  */
32
48
  export interface IAppearanceAxis {
33
49
  readonly id: AxisId;
34
- /** 이 축이 소유하는 토큰 이름공간(검증용). / Token namespace this axis owns (for validation). */
50
+ /**
51
+ * 이 축이 소유하는 토큰 이름공간(검증용).
52
+ *
53
+ * Token namespace this axis owns (for validation).
54
+ *
55
+ * この軸が所有するトークンの名前空間(検証用)。
56
+ *
57
+ * 这个轴所有的令牌命名空间(供校验使用)。
58
+ */
35
59
  readonly namespace: ReadonlySet<string>;
36
60
  /** 값 등록(사용자 확장). 축 오염·정직성 위반 시 throw 또는 클램프+경고. / Register a value; throws on axis-pollution, clamps+warns on honesty violations. */
37
61
  define(id: string, delta: TokenDelta): AxisDefineResult;
38
- /** 등록 여부. / Whether registered. */
62
+ /**
63
+ * 등록 여부.
64
+ *
65
+ * Whether registered.
66
+ *
67
+ * 登録されているか。
68
+ *
69
+ * 是否已注册。
70
+ */
39
71
  has(id: string): boolean;
40
- /** 축값 → 해소(토큰·속성·relayout 플래그). 미등록/default → 빈 델타. / Value id → resolution; unknown/default → empty delta. */
72
+ /**
73
+ * 축값 → 해소(토큰·속성·relayout 플래그). 미등록/default → 빈 델타.
74
+ *
75
+ * Value id → resolution; unknown/default → empty delta.
76
+ *
77
+ * 軸の値 → 解決(トークン・属性・relayout フラグ)。未登録/default → 空のデルタ。
78
+ *
79
+ * 轴的值 → 解析(令牌、属性、relayout 标志)。未注册/default → 空增量。
80
+ */
41
81
  resolve(valueId: string): AxisResolution;
42
- /** 등록된 값 id 목록(카탈로그·인스펙터용). / Registered value ids (for catalog/inspector). */
82
+ /**
83
+ * 등록된 값 id 목록(카탈로그·인스펙터용).
84
+ *
85
+ * Registered value ids (for catalog/inspector).
86
+ *
87
+ * 登録された値 id の一覧(カタログ・インスペクター用)。
88
+ *
89
+ * 已注册的值 id 列表(供目录与检查器使用)。
90
+ */
43
91
  list(): string[];
44
92
  }
45
93
  /** 축값이 default 인가(빈-델타·attr 생략 경로). / Is a value id the default (empty-delta / attr-omitted path)? */