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.
@@ -8,7 +8,10 @@ export interface OrgChartColumnDef {
8
8
  className?: string;
9
9
  /** 인라인 스타일 문자열 또는 (값, 행)→스타일 함수. / Inline style string or (value, row)→style function. */
10
10
  style?: string | ((value: any, row: Record<string, any>) => string);
11
- /** 커스텀 렌더러. 문자열 반환 시 innerHTML, 엘리먼트 반환 시 append. / Custom renderer; a string is set as innerHTML, an element is appended. */
11
+ /** 커스텀 렌더러. 값을 텍스트 그대로 보여주는 대신 아바타·배지·아이콘 같은 커스텀 마크업을
12
+ * 넣고 싶을 때 지정한다. 문자열 반환 시 innerHTML, 엘리먼트 반환 시 append.
13
+ * / Custom renderer. Set this when you need avatars, badges, or icons instead of plain text.
14
+ * A string return is set as innerHTML; an element return is appended. */
12
15
  renderer?: (value: any, row: Record<string, any>) => HTMLElement | string;
13
16
  }
14
17
  /**
@@ -37,10 +40,17 @@ export interface OrgChartOptions {
37
40
  /**
38
41
  * 조직도 컴포넌트. / Org-chart component.
39
42
  *
40
- * 부모/자식 관계(idField/parentIdField)를 가진 평면 데이터를 트리로 구성해
41
- * SVG 연결선 + 노드 카드로 렌더한다. 그리드와 독립된 standalone 컴포넌트다.
42
- * / Builds a tree from flat parent/child data (idField/parentIdField) and renders it as
43
- * SVG connectors plus node cards. A standalone component independent of the grid.
43
+ * 보고 라인·조직 구조·계층형 카테고리처럼 "누가 누구 밑에 있는가"를 시각적으로 보여주고 싶을 때
44
+ * 쓴다. 그리드와 별개의 독립 컴포넌트라서, 그리드 없이 조직도 하나만 페이지에 넣어도 동작한다.
45
+ * 동작 순서: `setData()`로 평면 행 배열(각 행에 id/parentId만 있으면 됨)을 넘기면 → 내부에서
46
+ * 부모/자식 관계(idField/parentIdField)를 따라 트리로 구성하고 → 그 결과를 SVG 연결선 + 노드
47
+ * 카드로 화면에 그린다.
48
+ * / Use this when you need to show "who reports to whom" — org structure, reporting lines, or
49
+ * hierarchical categories. It's a standalone component independent of the grid, so it works on
50
+ * its own with no grid on the page. Operation order: pass a flat row array to `setData()` (each
51
+ * row just needs an id/parentId) → internally it's built into a tree following the parent/child
52
+ * relation (idField/parentIdField) → the result is drawn on screen as SVG connectors plus node
53
+ * cards.
44
54
  *
45
55
  * @example
46
56
  * const chart = new OrgChart('#org', {
@@ -62,27 +72,38 @@ export declare class OrgChart {
62
72
  */
63
73
  constructor(selector: string | HTMLElement, opts: OrgChartOptions);
64
74
  /**
65
- * 조직도 데이터를 설정하고 렌더한다. / Set org-chart data and render.
75
+ * 조직도 데이터를 설정하고 렌더한다. 최초 로드는 물론, 데이터를 새로 받아올 때마다
76
+ * 다시 호출하면 트리를 재구성해 다시 그린다. / Set org-chart data and render. Call this on
77
+ * initial load and again whenever fresh data arrives — it rebuilds the tree and redraws.
66
78
  *
67
79
  * @param data - 부모/자식 관계를 가진 평면 행 배열 / Flat array of rows with parent/child relations
68
80
  */
69
81
  setData(data: Record<string, any>[]): void;
70
82
  /**
71
- * COLOR 축 테마를 컨테이너에 설정한다. / Set the COLOR-axis theme on the container.
83
+ * 색 테마(라이트/다크 등)를 컨테이너에 설정한다. 호스트 페이지의 다크모드 토글에 맞춰 전환할
84
+ * 때 호출한다. / Set the color theme (light/dark, etc.) on the container. Call this when
85
+ * switching to match the host page's dark-mode toggle.
72
86
  *
73
87
  * @param theme - data-og-theme 값 / data-og-theme value
74
88
  */
75
89
  setTheme(theme: string): void;
76
90
  /**
77
- * R12b: FORM(스킨) 축 — data-og-skin 을 자기 컨테이너에 설정(setTheme 과 동형, 색과 직교).
78
- * / R12b: FORM (skin) axis — set data-og-skin on the container (symmetric to setTheme, orthogonal to color).
91
+ * 형태(스킨) 테마를 컨테이너에 설정한다. 색은 그대로 두고 모서리·밀도 같은 겉모양만 바꾸고
92
+ * 싶을 때 쓴다. `setTheme`(색)과 서로 독립된 축이라, 색 테마는 그대로 두고 스킨만 바꾸거나
93
+ * 그 반대로 자유롭게 조합할 수 있다.
94
+ * / Set the form (skin) theme on the container. Use this to change the look (corner radius,
95
+ * density, etc.) while leaving color untouched. This is an axis independent from `setTheme`
96
+ * (color), so you can swap the skin alone, the color theme alone, or both freely.
79
97
  *
80
98
  * @param skin - data-og-skin 값 / data-og-skin value
81
99
  */
82
100
  setSkin(skin: string): void;
83
- /** 모든 노드를 펼친다. / Expand all nodes. */
101
+ /** 모든 노드를 펼친다. 조직 전체를 한눈에 훑어보고 싶을 때 호출. / Expand all nodes. Call when
102
+ * the viewer wants to see the whole organization at a glance. */
84
103
  expandAll(): void;
85
- /** 모든 노드를 접는다(루트만 표시). / Collapse all nodes (roots only). */
104
+ /** 모든 노드를 접는다(루트만 표시). 큰 조직도를 처음 접했을 때 최상위 구조부터 보여주고 싶을
105
+ * 때 호출. / Collapse all nodes (roots only). Call to show top-level structure first when a
106
+ * large org chart is first opened. */
86
107
  collapseAll(): void;
87
108
  private _toggle;
88
109
  private _rebuild;
@@ -1,7 +1,16 @@
1
1
  import { SkinTokenDelta } from './types.js';
2
- /** 허용되는 FORM 토큰 이름(SkinTokenName 과 동일 집합의 런타임 가드).
3
- * export 이유(DD-11): 테마 델타의 대칭 검증 `assertColorOnly` 가 이 집합을 denylist 로 재사용해
4
- * 색축⊥형태축을 양방향으로 기계강제한다(형태/밀도/질감 shape 토큰이 테마 델타에 오면 거부). */
2
+ /**
3
+ * 스킨(FORM) 델타에 등장할 수 있는 CSS 커스텀 프로퍼티 이름의 허용 목록(런타임 가드).
4
+ * 스킨은 형태(모서리·테두리·그림자·밀도 등)만 다루고 색은 다루지 않는다는 규칙을, 이 목록이
5
+ * 물리적으로 강제한다 — `define()`/`registerBuiltin()` 이 델타를 검사할 때 이 집합에 없는
6
+ * 키는 거부한다. 반대 방향(테마 델타에 형태 토큰이 섞이는 것)도 이 집합을 재사용해 막는다
7
+ * (색⊥형태 축 분리를 양방향으로 기계 강제).
8
+ * / Allow-list of CSS custom-property names permitted in a skin (FORM) delta (runtime guard).
9
+ * It physically enforces the rule that skins own shape only (radius/border/elevation/density/…)
10
+ * and never color — `define()`/`registerBuiltin()` reject any key outside this set. The reverse
11
+ * direction (shape tokens leaking into a theme delta) reuses this same set, so the color⊥shape
12
+ * axis separation is mechanically enforced both ways.
13
+ */
5
14
  export declare const FORM_TOKENS: ReadonlySet<string>;
6
15
  /** 스킨 정의 결과. / Result of a skin definition. */
7
16
  export interface SkinDefineResult {
@@ -11,23 +20,37 @@ export interface SkinDefineResult {
11
20
  readonly warnings: string[];
12
21
  }
13
22
  /**
14
- * 스킨 델타가 색 리터럴을 담고 있는지 검사하고, 위반 시 던진다(FORM-only, Rule 2).
15
- * / Assert a skin delta carries no color literal; throws on violation (FORM-only, Rule 2).
23
+ * 스킨(FORM)에는 형태만 담고 색은 담지 않는다는 규칙을 실제로 검사하는 함수. 왜 필요한가:
24
+ * 스킨과 테마(색)를 분리해 두어도, 개발자가 실수로 스킨 델타에 `#fff` 같은 색을 넣으면 그
25
+ * 분리가 눈에 안 띄게 무너진다 — 그래서 등록 시점에 색 리터럴이 섞이면 즉시 던져서 알아채게
26
+ * 한다(조용히 무시하지 않음).
27
+ * / Actually enforces the rule that a skin (FORM) carries shape only, never color. Why: even with
28
+ * skin/theme separation on paper, a developer slipping `#fff` into a skin delta would quietly
29
+ * break that separation — so this throws immediately at registration time instead of ignoring it.
16
30
  *
17
31
  * @param id - 스킨 id / Skin id
18
32
  * @param delta - 검사할 토큰 델타 / Token delta to validate
19
33
  * @throws FORM 토큰이 아니거나 색 리터럴이 있으면 Error / Throws if a non-FORM token or a color literal is present
34
+ * @example
35
+ * skinRegistry.define('my-skin', { '--og-radius-md': '#fff' }); // throws — 색 리터럴 검출 / color literal detected
20
36
  */
21
37
  export declare function assertFormOnly(id: string, delta: SkinTokenDelta): void;
22
38
  /**
23
- * 접근성 가드레일(불변식) 적용 — 정의 시점 클램프(§6.4).
24
- * / Apply accessibility guardrails (invariants) — clamp at definition time (§6.4).
25
- *
26
- * - focus-width < 2px → 2px 로 클램프(가시 포커스 비협상). / clamp to 2px (visible focus is non-negotiable).
39
+ * 접근성 가드레일(불변식)을 적용해 델타를 정의 시점에 안전값으로 클램프한다. `define()`/
40
+ * `registerBuiltin()` 내부에서 자동 호출되므로 보통 직접 부를 일은 없다(커스텀 등록 파이프라인·
41
+ * 테스트에서 직접 검증할 때만 예외적으로 사용). 스킨 저자가 접근성 최소 기준 이하로 값을
42
+ * 설정해도 조용히 그대로 등록되지 않도록 막는다.
43
+ * - focus-width < 2px → 2px 로 클램프(가시 포커스 비협상).
27
44
  * - focus-style: none → solid.
28
- *
29
45
  * 반환은 조정된 델타 + 경고 목록(silent override 아님 — 무엇을 클램프했는지 알린다).
30
- * / Returns the adjusted delta plus a warning list (not a silent override — it reports what was clamped).
46
+ * / Applies accessibility guardrails (invariants), clamping the delta to a safe value at
47
+ * definition time. Called automatically inside `define()`/`registerBuiltin()`, so you rarely
48
+ * call it directly (only in a custom registration pipeline or a test that checks it directly).
49
+ * Prevents a skin author from silently registering values below the minimum accessibility bar.
50
+ * - focus-width < 2px → clamped to 2px (visible focus is non-negotiable).
51
+ * - focus-style: none → solid.
52
+ * Returns the adjusted delta plus a warning list (not a silent override — it reports what was
53
+ * clamped).
31
54
  *
32
55
  * @param id - 스킨 id / Skin id
33
56
  * @param delta - 조정할 토큰 델타 / Token delta to adjust
@@ -35,10 +58,19 @@ export declare function assertFormOnly(id: string, delta: SkinTokenDelta): void;
35
58
  */
36
59
  export declare function applyGuardrails(id: string, delta: SkinTokenDelta): SkinDefineResult;
37
60
  /**
38
- * 프로세스 전역 스킨 등록소. defineSkin(사용자) 는 검증+가드레일+`<style>` 주입,
39
- * registerBuiltin(내장) 은 검증+가드레일만(CSS 는 skins.css 정적 번들 소유).
40
- * / Process-global skin registry. `define` (user) does validation + guardrails + `<style>` injection;
41
- * `registerBuiltin` (built-in) does validation + guardrails only (CSS is owned by the skins.css static bundle).
61
+ * 스킨(FORM 축 — 모서리·테두리·그림자·밀도 등 "생김새")을 등록하는 전역 레지스트리. 등록하면
62
+ * 내부에서 벌어지는 일: `define()` 은 색 리터럴이 없는지 검사 → 접근성 가드레일 클램프 →
63
+ * `.og-container[data-og-skin="id"] { ... }` 규칙을 담은 `<style>` 태그를 문서 head 에 주입한다.
64
+ * 그리드 쪽에서 `data-og-skin="id"` 속성만 설정하면 이 CSS 가 매치되어 적용된다. 내장 스킨은
65
+ * `registerBuiltin()` 으로 검증+가드레일만 거치고 실제 CSS 는 정적 번들 skins.css 가 이미
66
+ * 담당하므로 별도 주입이 없다.
67
+ * / A global registry for registering skins (the FORM axis — corner/border/shadow/density, i.e.
68
+ * "shape"). What happens internally when you register: `define()` checks for no color literals
69
+ * → clamps via accessibility guardrails → injects a `<style>` tag into document head containing
70
+ * a `.og-container[data-og-skin="id"] { ... }` rule. The grid side only needs to set the
71
+ * `data-og-skin="id"` attribute for this CSS to match and apply. Built-in skins go through
72
+ * `registerBuiltin()` for validation + guardrails only — their CSS is already owned by the
73
+ * static skins.css bundle, so no injection happens.
42
74
  *
43
75
  * @example
44
76
  * skinRegistry.define('my-skin', { '--og-radius-md': '10px', '--og-border-style': 'solid' });
@@ -74,19 +106,50 @@ export declare class SkinRegistry {
74
106
  /** 런타임 `<style>` 주입(테스트/SSR 등 document 없으면 no-op). 같은 태그를 누적 사용. */
75
107
  private _inject;
76
108
  }
77
- /** Sharp/Gothic — 엔터프라이즈 고밀도·각짐(§3.1). / Sharp/Gothic — enterprise high-density, squared corners (§3.1). */
109
+ /**
110
+ * Sharp/Gothic — 엔터프라이즈 고밀도 화면에 맞춘 각진(라운드 0) 형태. 데이터 밀도가 중요한
111
+ * 백오피스·트레이딩 화면에 어울린다.
112
+ * / Sharp/Gothic — squared (zero-radius) shape tuned for high-density enterprise screens; suits
113
+ * back-office/trading UIs where data density matters.
114
+ */
78
115
  export declare const SKIN_SHARP: SkinTokenDelta;
79
- /** Rounded — 소비자 SaaS 소프트(§3.2). / Rounded — consumer-SaaS soft look (§3.2). */
116
+ /**
117
+ * Rounded — 소비자 SaaS 에 어울리는 부드러운(둥근 모서리·큰 그림자) 형태.
118
+ * / Rounded — soft shape (rounded corners, larger shadows) suited to consumer-SaaS products.
119
+ */
80
120
  export declare const SKIN_ROUNDED: SkinTokenDelta;
81
- /** Stitch — 핸드크래프트(§3.3). 색(리넨/자수)은 theme 축. / Stitch — handcrafted look (§3.3); color (linen/embroidery) lives on the theme axis. */
121
+ /**
122
+ * Stitch — 손바느질/리넨 소재 느낌을 주는 형태(점선 테두리·텍스처). 리넨 색·자수 색 자체는
123
+ * 이 스킨이 아니라 theme(색) 축이 담당한다(색⊥형태 분리).
124
+ * / Stitch — a handcrafted, linen-textured shape (dashed borders, texture). The linen/embroidery
125
+ * color itself belongs to the theme (color) axis, not this skin (color⊥shape separation).
126
+ */
82
127
  export declare const SKIN_STITCH: SkinTokenDelta;
83
- /** Flat/Minimal — 플랫 2.0(§3.5). / Flat/Minimal — flat 2.0 (§3.5). */
128
+ /**
129
+ * Flat/Minimal — 그림자·입체감을 없앤 평평한(flat 2.0) 형태. 미니멀한 대시보드에 어울린다.
130
+ * / Flat/Minimal — a flat (flat 2.0) shape with shadows/depth removed; suits minimal dashboards.
131
+ */
84
132
  export declare const SKIN_FLAT: SkinTokenDelta;
85
- /** High-Contrast — 접근성 우선·레퍼런스(§3.6). / High-Contrast — accessibility-first reference skin (§3.6). */
133
+ /**
134
+ * High-Contrast — 접근성을 최우선에 둔 레퍼런스 스킨(굵은 테두리·큰 포커스 링·굵은 아이콘 획).
135
+ * 다른 스킨을 만들 때 "접근성 하한선이 뭔가"를 확인하는 기준으로도 쓸 수 있다.
136
+ * / High-Contrast — a reference skin that puts accessibility first (thick borders, a large focus
137
+ * ring, bold icon strokes). Also useful as a baseline for "what's the accessibility floor" when
138
+ * authoring other skins.
139
+ */
86
140
  export declare const SKIN_HIGH_CONTRAST: SkinTokenDelta;
87
- /** Material/Elevated — 중간 반경 + 정직한 그림자 엘리베이션. / Material/Elevated — medium radius plus honest shadow elevation. */
141
+ /**
142
+ * Material/Elevated — 중간 정도 반경 + 과장 없는 그림자 엘리베이션을 쓰는 형태.
143
+ * / Material/Elevated — a shape using medium-radius corners plus restrained (non-exaggerated)
144
+ * shadow elevation.
145
+ */
88
146
  export declare const SKIN_MATERIAL: SkinTokenDelta;
89
- /** 내장 스킨 카탈로그(확정 6종). id → 델타. / Built-in skin catalog (6 finalized skins). id → delta. */
147
+ /**
148
+ * 내장 스킨 카탈로그(확정 6종, id → 델타). `skinRegistry.list()`/설정 UI 에서 선택지를 보여줄 때
149
+ * 이 배열을 순회하면 된다.
150
+ * / Built-in skin catalog (6 finalized skins, id → delta). Iterate this array when building a
151
+ * picker UI or listing options via `skinRegistry.list()`.
152
+ */
90
153
  export declare const BUILTIN_SKINS: ReadonlyArray<readonly [string, SkinTokenDelta]>;
91
154
  /** 프로세스 전역 기본 레지스트리 — 내장 스킨을 부트스트랩 등록(주입 없음, CSS=skins.css).
92
155
  * / Process-global default registry — bootstraps the built-in skins (no injection; CSS=skins.css). */
@@ -2,6 +2,16 @@
2
2
  * XmlConverter — XML ↔ 그리드 데이터 양방향 변환 유틸리티.
3
3
  * / XmlConverter — bidirectional XML ↔ grid-data conversion utility.
4
4
  *
5
+ * SAP·레거시 백엔드처럼 JSON이 아니라 XML로 응답을 주는 시스템과 그리드를 연결할 때 쓴다.
6
+ * 데이터가 흐르는 방향은 두 가지다: **입력**(서버가 준 XML 문자열) → **변환**(태그/속성을
7
+ * 파싱해 행 객체 배열로 정규화) → **출력**(그리드가 바로 `setData()`에 넣을 수 있는
8
+ * `Record<string, any>[]`). 반대 방향(그리드에서 편집한 데이터 → XML)도 동일한 변환기로 처리한다.
9
+ * / Use this to bridge the grid with systems that answer in XML instead of JSON — SAP and other
10
+ * legacy backends being the common case. Data flows in two directions: **input** (the XML string
11
+ * a server returned) → **transform** (tags/attributes parsed and normalized into row objects) →
12
+ * **output** (a `Record<string, any>[]` the grid can pass straight to `setData()`). The reverse
13
+ * direction (grid-edited data → XML) goes through the same converter.
14
+ *
5
15
  * 지원 포맷 / Supported formats:
6
16
  * A. Element 방식 <row><name>홍길동</name></row>
7
17
  * B. Attribute 방식 <row name="홍길동" />
@@ -70,6 +80,10 @@ export declare class XmlConverter {
70
80
  * @param options - 파싱 옵션 / Parse options
71
81
  * @returns 행 객체 배열 / Array of row objects
72
82
  * @throws XML 파싱 오류 시 Error 발생 / Throws an Error on XML parse failure
83
+ * @example
84
+ * // <rows><row><name>Kim</name><dept>Sales</dept></row></rows>
85
+ * const rows = XmlConverter.parse(xmlText);
86
+ * grid.setData(rows); // → [{ name: 'Kim', dept: 'Sales' }]
73
87
  */
74
88
  static parse(xml: string, options?: XmlParseOptions): Record<string, any>[];
75
89
  /**
@@ -78,12 +92,24 @@ export declare class XmlConverter {
78
92
  * @param data - 직렬화할 행 배열 / Row array to serialize
79
93
  * @param options - 직렬화 옵션 / Serialize options
80
94
  * @returns XML 문자열 / XML string
95
+ * @example
96
+ * // 그리드에서 수정된 행을 서버로 보낼 때 / Sending grid-edited rows back to a server
97
+ * const xml = XmlConverter.stringify(grid.getEditedRows(), { mode: 'attribute' });
81
98
  */
82
99
  static stringify(data: Record<string, any>[], options?: XmlStringifyOptions): string;
83
100
  /**
84
101
  * SAP BAPI XML 응답을 파싱하여 { header, items, returns } 구조로 반환.
85
102
  * / Parse a SAP BAPI XML response into a { header, items, returns } structure.
86
103
  *
104
+ * SAP BAPI 응답은 "행이 죽 나열된" 단순 목록이 아니라 문서 헤더(DOCUMENTHEADER)·라인
105
+ * 아이템(ACCOUNTGL 등)·처리 결과 메시지(RETURN)가 뒤섞여 한 응답 안에 들어온다. 그래서 범용
106
+ * `parse()`(단일 rowTag 기준)로는 못 풀고, 이 메서드가 세 부분을 각각 알아서 찾아 분리해 준다.
107
+ * 라인 아이템은 그리드에 그대로 `setData()`할 수 있는 배열로 나온다.
108
+ * / A SAP BAPI response isn't a flat list of rows — a document header (DOCUMENTHEADER), line
109
+ * items (e.g. ACCOUNTGL), and result messages (RETURN) are all mixed into one response. The
110
+ * generic `parse()` (which assumes a single rowTag) can't untangle that, so this method locates
111
+ * and splits all three parts for you. `items` comes out ready to hand to the grid's `setData()`.
112
+ *
87
113
  * 지원 패턴 / Supported patterns:
88
114
  * <DOCUMENTHEADER>...</DOCUMENTHEADER>
89
115
  * <ACCOUNTGL><ITEM>...</ITEM></ACCOUNTGL>
@@ -91,14 +117,28 @@ export declare class XmlConverter {
91
117
  *
92
118
  * @param xml - SAP BAPI XML 응답 문자열 / SAP BAPI XML response string
93
119
  * @returns 파싱 결과 구조 / Parsed result structure
120
+ * @example
121
+ * const { header, items, returns } = XmlConverter.parseSap(sapResponseXml);
122
+ * grid.setData(items);
123
+ * if (returns.some(r => r.TYPE === 'E')) console.error('SAP 오류 응답', returns);
94
124
  */
95
125
  static parseSap(xml: string): SapParseResult;
96
126
  /**
97
127
  * BAPI 페이로드 객체를 SAP XML 형식으로 직렬화. sapGenPayload() 결과 또는 단일 document 객체를 받음.
98
128
  * / Serialize a BAPI payload object into SAP XML. Accepts a sapGenPayload() result or a single document object.
99
129
  *
130
+ * `parseSap()`의 반대 방향 — 그리드에서 만든/편집한 전표 데이터를 SAP가 받을 수 있는
131
+ * BAPI 호출용 XML로 만들 때 쓴다. / The reverse of `parseSap()` — use this to turn
132
+ * grid-built/edited document data into the BAPI-call XML that SAP expects.
133
+ *
100
134
  * @param payload - BAPI 페이로드 객체 / BAPI payload object
101
135
  * @returns SAP XML 문자열 / SAP XML string
136
+ * @example
137
+ * const xml = XmlConverter.stringifySap({
138
+ * BAPI_FUNCTION: 'BAPI_ACC_DOCUMENT_POST',
139
+ * DOCUMENTHEADER: { COMP_CODE: '1000', DOC_DATE: '20260101' },
140
+ * ACCOUNTGL: grid.getData(),
141
+ * });
102
142
  */
103
143
  static stringifySap(payload: {
104
144
  BAPI_FUNCTION?: string;
@@ -1,10 +1,20 @@
1
1
  import { CellRange } from '../types.js';
2
2
  /**
3
- * Phase1 MVP = 'bar'|'line'. 나머지는 Phase2/3 예약(타입만 선언, 미구현).
3
+ * 그리드 데이터를 어떤 모양의 차트로 그릴지 고르는 값. / Picks which shape of chart to draw the
4
+ * grid data as.
4
5
  *
5
- * ⚠️ 'bar-stacked': 공개 타입으로 노출되어 있으나 내장(builtin-canvas) 렌더러는 현재 스택
6
- * 누적을 구현하지 않는다 — 지정해도 'bar-grouped'와 동일하게 그룹형(side-by-side)으로
7
- * 폴백 렌더된다(CanvasAdapter._computeGeometry). 하위호환을 위해 타입 자체는 유지한다.
6
+ * 현재(Phase1 MVP) 실제로 렌더되는 값은 'bar'|'line' 뿐이다. 나머지는 Phase2/3 를 위해 타입만
7
+ * 미리 선언해 둔 예약값이며 아직 구현되지 않았다.
8
+ * / Right now (Phase1 MVP) only 'bar' and 'line' actually render. The rest are reserved values —
9
+ * the type exists for Phase2/3 but nothing implements them yet.
10
+ *
11
+ * ⚠️ 'bar-stacked': 공개 타입으로는 노출돼 있지만, 내장(builtin-canvas) 렌더러는 아직 누적
12
+ * 스택을 그리지 못한다 — 지정해도 'bar-grouped'와 똑같이 그룹형(막대를 나란히)으로 대신
13
+ * 그려진다. 하위 호환을 위해(이미 이 값을 쓰는 코드가 깨지지 않도록) 타입 자체는 남겨 둔다.
14
+ * / ⚠️ 'bar-stacked': exposed as a public type, but the built-in canvas renderer can't draw a
15
+ * stacked bar yet — specifying it falls back to the same grouped (side-by-side) rendering as
16
+ * 'bar-grouped'. The type itself is kept for backward compatibility, so existing code using this
17
+ * value doesn't break.
8
18
  */
9
19
  export type ChartType = 'bar' | 'line' | 'area' | 'pie' | 'doughnut' | 'bar-stacked' | 'bar-grouped';
10
20
  /** 시리즈(컬럼) 명세. / Series (column) spec. */
@@ -20,7 +30,18 @@ export interface ChartSeriesSpec {
20
30
  /** 시리즈별 렌더 타입(혼합 차트). / Per-series render type (mixed charts). */
21
31
  type?: 'bar' | 'line' | 'area';
22
32
  }
23
- /** 차트 데이터 소스(범위/선택/체크/전체/컬럼 지정). / Chart data source (range/selection/checked/all/explicit columns). */
33
+ /**
34
+ * 차트 파이프라인의 첫 단계 — "그리드의 어느 데이터를 그릴 것인가"를 고른다.
35
+ * / The first stage of the chart pipeline — picks which grid data to draw.
36
+ *
37
+ * `'range'`(지정 범위)·`'selection'`(현재 드래그 선택)·`'checked'`(체크된 행)·`'all'`(전체
38
+ * 데이터) 는 "사용자가 화면에서 고른 것을 그대로 차트로" 만들 때 쓰고, `'columns'` 는 화면 선택과
39
+ * 무관하게 카테고리/시리즈 컬럼을 코드로 직접 지정하고 싶을 때 쓴다.
40
+ * / `'range'` (a given cell range), `'selection'` (the current drag selection), `'checked'`
41
+ * (checked rows), and `'all'` (the whole dataset) turn whatever the user picked on screen
42
+ * straight into a chart. `'columns'` is for when you want to specify the category/series columns
43
+ * in code, independent of any on-screen selection.
44
+ */
24
45
  export type ChartSource = {
25
46
  kind: 'range';
26
47
  range?: CellRange;
@@ -56,7 +77,11 @@ export interface ChartSeries {
56
77
  data: Array<number | null>;
57
78
  /** 시리즈 색. / Series color. */
58
79
  color?: string;
59
- /** 색 외 구분(HANMS-19). / Non-color distinction (HANMS-19). */
80
+ /** 색만으로 시리즈를 구분하기 어려운 사용자(색약 등)를 위해, 색과 함께(또는 색 대신) 채움
81
+ * 무늬로도 시리즈를 구분한다. 'solid'=무늬 없음(기본), 'hatch'=사선, 'dot'=점, 'cross'=십자.
82
+ * / A fill pattern that distinguishes series by shape, not just color — for viewers who can't
83
+ * rely on color alone (color-vision deficiency, etc.). 'solid' = no pattern (default),
84
+ * 'hatch' = diagonal lines, 'dot' = dots, 'cross' = crosshatch. */
60
85
  pattern?: 'solid' | 'hatch' | 'dot' | 'cross';
61
86
  }
62
87
  /** 차트 데이터 모델 메타(출처·샘플링·집계 배지 정보). / Chart data model meta (source, sampling, aggregation badge info). */
@@ -65,11 +90,15 @@ export interface ChartDataModelMeta {
65
90
  sourceKind: ChartSource['kind'];
66
91
  /** 원본 포인트(행) 수. / Original point (row) count. */
67
92
  total: number;
68
- /** LTTB 다운샘플 또는 category 집계로 축약됐는가 → 배지(§C). / Whether reduced by LTTB downsample or category aggregation → badge (§C). */
93
+ /** 원본 데이터가 LTTB 다운샘플링이나 카테고리 집계로 축약됐는가. true 면 화면에 그려진 값이
94
+ * 원본 그대로가 아니라는 뜻이므로, 이 값을 보고 UI에서 축약 사실을 배지로 고지해야 한다.
95
+ * / Whether the original data was reduced via LTTB downsampling or category aggregation. When
96
+ * true, what's drawn on screen isn't the raw data verbatim — the UI should surface a badge
97
+ * using this flag so the reduction isn't hidden from the viewer. */
69
98
  sampled: boolean;
70
- /** 다운샘플 전 포인트 수. / Point count before downsampling. */
99
+ /** 다운샘플링 전 포인트 수. / Point count before downsampling. */
71
100
  sampledFrom?: number;
72
- /** 다운샘플 후 포인트 수. / Point count after downsampling. */
101
+ /** 다운샘플링 후 포인트 수. / Point count after downsampling. */
73
102
  sampledTo?: number;
74
103
  /** 적용된 집계 연산. / Applied aggregation op. */
75
104
  aggregatedOp?: 'sum' | 'avg' | 'count' | 'min' | 'max' | 'custom';
@@ -77,7 +106,11 @@ export interface ChartDataModelMeta {
77
106
  pieReducedToFirst?: boolean;
78
107
  /** pie 에서 음수를 절댓값 처리했는가. / Whether pie used absolute values for negatives. */
79
108
  negativesAbsInPie?: boolean;
80
- /** SR 폴백 — extractor 가 렌더러와 무관하게 항상 채운다(§B 하드 게이트). / SR fallback — always filled by the extractor regardless of renderer (§B hard gate). */
109
+ /** 스크린리더 사용자를 위한 표 형태의 텍스트 등가물. 어떤 렌더 엔진(내장 canvas·외부 lib)을
110
+ * 쓰든 추출(extractor) 단계에서 항상 채워지므로, 렌더러가 접근성을 신경 쓰지 않아도 이 값은
111
+ * 항상 존재한다. / A table-shaped text alternative for screen-reader users. It's always filled
112
+ * during extraction regardless of which render engine (built-in canvas or an external lib) is
113
+ * used, so it's guaranteed to exist even if the renderer itself doesn't handle accessibility. */
81
114
  a11yTable: A11yTableModel;
82
115
  }
83
116
  /** 헤드리스 차트 데이터 모델(추출 산출물). / Headless chart data model (extraction output). */
@@ -154,8 +187,26 @@ export interface ChartPoint {
154
187
  rowId?: string;
155
188
  }
156
189
  /**
157
- * 차트 렌더 어댑터(교체 seam) — 내장 canvas / 외부 lib 백엔드를 통일된 인터페이스로 감싼다.
158
- * / Chart render adapter (swap seam) — wraps the built-in canvas / external-lib backends behind one interface.
190
+ * 차트 렌더 어댑터(교체 seam) — 내장 canvas 렌더러와 외부 차트 라이브러리(ECharts 등) 백엔드를
191
+ * 하나의 공통 인터페이스로 감싼다. 내장 렌더러로는 부족해서 다른 차트 라이브러리로 실제 그리는
192
+ * 부분만 바꿔치기하고 싶을 때, 이 인터페이스를 구현해 `ChartConfig.engine`에 넘긴다.
193
+ * / Chart render adapter (swap seam) — wraps the built-in canvas renderer and external chart
194
+ * library backends (e.g. ECharts) behind one common interface. Implement this when the built-in
195
+ * renderer isn't enough and you want to swap in a different charting library for the actual
196
+ * drawing, then pass it via `ChartConfig.engine`.
197
+ *
198
+ * @example
199
+ * const myAdapter: ChartAdapter = {
200
+ * id: 'my-echarts-adapter',
201
+ * // 차트 라이브러리 인스턴스 생성 / create the chart-lib instance
202
+ * async init(host, spec) { echartsInstance = echarts.init(host); },
203
+ * // model.categories/series 를 라이브러리 포맷으로 변환해 그리기 / map the model into the lib's format and draw
204
+ * render(model, spec) { echartsInstance.setOption(toEchartsOption(model, spec)); },
205
+ * // 라이브러리 resize 호출 / call the lib's resize
206
+ * resize(w, h) { echartsInstance.resize({ width: w, height: h }); },
207
+ * // 라이브러리 인스턴스 정리 / tear down the lib instance
208
+ * destroy() { echartsInstance.dispose(); },
209
+ * };
159
210
  */
160
211
  export interface ChartAdapter {
161
212
  /** 어댑터 식별자. / Adapter identifier. */
@@ -173,19 +224,29 @@ export interface ChartAdapter {
173
224
  /** 어댑터 정리. / Tear down the adapter. */
174
225
  destroy(): void;
175
226
  }
176
- /** createChart 반환 핸들(§6). 구현은 ChartManager. / Handle returned by createChart (§6); implemented by ChartManager. */
227
+ /** `grid.createChart()`가 반환하는, 살아있는 차트를 다루는 핸들. 실제 구현체는 ChartManager.
228
+ * 이 핸들로 타입 전환·갱신·이미지 추출·파기까지 차트의 생애주기 전체를 조작한다.
229
+ * / The handle returned by `grid.createChart()` for controlling a live chart; implemented by
230
+ * ChartManager. Use it to change type, refresh, export an image, and destroy — the chart's
231
+ * whole lifecycle. */
177
232
  export interface ChartInstance {
178
233
  /** 차트 인스턴스 id. / Chart instance id. */
179
234
  readonly id: string;
180
235
  /** 설정 패치 후 갱신. / Patch config and update. */
181
236
  update(patch?: Partial<ChartConfig>): void;
182
237
  /**
183
- * 모델을 재추출하고 렌더 스펙(테마 포함)을 재스냅샷해 재렌더한다(§5.3). 그리드는 테마 변경
184
- * 이벤트를 발행하지 않으므로(`setTheme`/`setThemeVar`는 CSS 만 갱신) 다크모드 토글처럼 데이터
185
- * 변화 없는 순수 테마 전환 후에는, 열려 있는 각 차트에 대해 이 메서드를 호출해야 새 테마
186
- * (색·글꼴·팔레트)가 재적용된다. `update()`/`setType()`도 내부적으로 동일 경로를 탄다.
238
+ * 모델을 재추출하고 렌더 스펙(테마 포함)을 다시 계산해 재렌더한다.
239
+ * / Re-extract the model and recompute the render spec (incl. theme), then re-render.
240
+ *
241
+ * 그리드는 테마가 바뀌어도 별도 이벤트를 발행하지 않는다(`setTheme`/`setThemeVar`는 CSS만
242
+ * 갱신). 그래서 다크모드 토글처럼 데이터는 그대로고 테마만 바뀐 경우, 열려 있는 각 차트에
243
+ * 대해 이 메서드를 직접 호출해야 새 테마(색·글꼴·팔레트)가 반영된다. `update()`/`setType()`도
244
+ * 내부적으로 이 경로를 그대로 탄다.
245
+ * / The grid doesn't emit a dedicated event when only the theme changes (`setTheme`/
246
+ * `setThemeVar` update CSS only). So after a pure theme switch with no data change — e.g. a
247
+ * dark-mode toggle — call this on each open chart to apply the new theme (colors, fonts,
248
+ * palette). `update()` and `setType()` internally follow the same path.
187
249
  */
188
- /** 모델을 재추출하고 렌더 스펙(테마 포함)을 재스냅샷해 재렌더. / Re-extract the model and re-snapshot the render spec (incl. theme), then re-render. */
189
250
  refresh(): void;
190
251
  /** 차트 타입 변경. / Change the chart type. */
191
252
  setType(type: ChartType): void;
@@ -198,7 +259,11 @@ export interface ChartInstance {
198
259
  /** 차트 이벤트 리스너 등록. / Register a chart event listener. */
199
260
  on(ev: 'chartRender' | 'chartPointClick', cb: (...a: any[]) => void): void;
200
261
  }
201
- /** GridOptions.chart 로 중첩되는 전역 옵션(C5.1, 최상위 flat 키 금지). / Global options nested under GridOptions.chart (C5.1; no top-level flat keys). */
262
+ /** `GridOptions.chart`에 중첩해서 넣는, 그리드 전체에 적용되는 차트 기본값. 그리드 인스턴스를
263
+ * 만들 때 한 번 설정해 두면 이후 `createChart()` 호출마다 반복하지 않아도 되는 공통값(기본
264
+ * 엔진·팔레트·포인트 상한 등)이다. / Chart defaults applied grid-wide, nested under
265
+ * `GridOptions.chart`. Set once when constructing the grid, and every later `createChart()` call
266
+ * inherits the shared defaults (default engine, palette, point cap, etc.) without repeating them. */
202
267
  export interface ChartGlobalOptions {
203
268
  /** 차트 기능 활성화. / Enable the chart feature. */
204
269
  enabled?: boolean;
@@ -208,7 +273,7 @@ export interface ChartGlobalOptions {
208
273
  defaultType?: ChartType;
209
274
  /** 기본 배치 방식. / Default placement. */
210
275
  placement?: 'docked' | 'modal' | 'inline' | 'floating';
211
- /** 렌더 포인트 상한(초과 시 다운샘플). / Max render points (downsample above this). */
276
+ /** 렌더 포인트 상한(초과 시 다운샘플링). / Max render points (downsample above this). */
212
277
  maxPoints?: number;
213
278
  /** live 갱신 디바운스(ms). / Debounce for live updates (ms). */
214
279
  debounceMs?: number;
@@ -236,7 +301,23 @@ export interface ChartGlobalOptions {
236
301
  id: string;
237
302
  }) => void;
238
303
  }
239
- /** createChart() 공개 설정(§6). / Public config for createChart() (§6). */
304
+ /**
305
+ * `grid.createChart(config)`에 넘기는 공개 설정. 어떤 데이터를(source) 어떤 모양으로(type)
306
+ * 그릴지가 필수고, 나머지는 배치·엔진·꾸밈(제목/범례/축 등)을 위한 선택 옵션이다.
307
+ * / The public config passed to `grid.createChart(config)`. Only which data (source) and what
308
+ * shape (type) to draw are required; the rest are optional placement/engine/decoration
309
+ * (title, legend, axis, etc.) settings.
310
+ *
311
+ * @example
312
+ * const chart = grid.createChart({
313
+ * source: { kind: 'all' },
314
+ * type: 'bar',
315
+ * category: 'region',
316
+ * series: ['sales'],
317
+ * placement: 'inline',
318
+ * mount: document.querySelector('#chart-host')!,
319
+ * });
320
+ */
240
321
  export interface ChartConfig {
241
322
  /** 데이터 소스. / Data source. */
242
323
  source: ChartSource;
@@ -2,17 +2,31 @@
2
2
  export type MessageParams = Readonly<Record<string, string | number>>;
3
3
  /**
4
4
  * 메시지 값: 평문 문자열('{name}' 보간) 또는 함수(복수형·조사 등 "문법이 데이터인" 케이스의 탈출구).
5
- * ICU/CLDR 복수 엔진은 zero-dependency 정체성 때문에 도입하지 않는다(규칙은 로케일 파일에 둔다).
5
+ * 왜 함수까지 허용하나: "사과 1개/사과 2개"처럼 복수형 규칙이 언어마다 다른데, ICU/CLDR 같은
6
+ * 범용 복수형 엔진을 넣으면 zero-dependency 원칙이 깨진다. 그래서 그 규칙 자체를 로케일 파일
7
+ * 안의 함수로 옮겨, 각 언어가 자기 문법을 직접 결정하게 한다.
6
8
  * / A message value: a plain string ('{name}' interpolation) or a function (escape hatch for
7
- * plurals/particles where "grammar is data"). No ICU/CLDR plural engine (zero-dependency).
9
+ * plurals/particles where "grammar is data"). Why allow a function at all: plural rules differ
10
+ * per language, and pulling in a general ICU/CLDR plural engine would break the
11
+ * zero-dependency principle — so the rule itself moves into a function inside the locale file,
12
+ * letting each language own its own grammar.
13
+ *
14
+ * @example
15
+ * const countBadge: MessageValue = (p) => `${p.n}건`; // 한국어는 복수형이 없음 / Korean has no plural form
8
16
  */
9
17
  export type MessageValue = string | ((params: MessageParams) => string);
10
18
  /**
11
- * 로케일 메시지 카탈로그(2단 중첩, 최상위 섹션 = 소비 UI 표면). 파라미터를 받는 값만 `MessageValue`
12
- * (함수형 복수 허용), 정적 라벨은 `string`. 내장 ko 가 SSOT 이며 en 은 동일 키 집합을 갖는다.
13
- * / The locale message catalog (2-level nested, top-level section = consuming UI surface). Only
14
- * parameterized entries are `MessageValue` (allowing plural functions); static labels are
15
- * `string`. Built-in ko is the SSOT; en carries the same key set.
19
+ * 로케일 메시지 카탈로그 전체 형태(2단 중첩, 최상위 섹션 = 소비하는 UI 표면 — 필터 패널, 찾기
20
+ * 바 등). 새 언어를 추가하거나 커스텀 로케일을 만들 때 이 타입에 맞춰 객체를 작성하면 된다.
21
+ * 파라미터를 받는 값만 `MessageValue`(함수형 복수 허용), 정적 라벨은 `string`. 내장 ko 가
22
+ * 단일 진실 공급원(SSOT)이며 en 은 동일 키 집합을 갖는다 — 새 언어도 이 키 집합을 채우면(또는
23
+ * 부분만 채우고 `register()` 의 `missingKeys` 로 진행률을 보면) 된다.
24
+ * / Shape of a full locale message catalog (2-level nested; the top-level section is the
25
+ * consuming UI surface — filter panel, find bar, etc.). When adding a new language or building a
26
+ * custom locale, shape your object to satisfy this type. Only parameterized entries are
27
+ * `MessageValue` (allowing plural functions); static labels are `string`. Built-in ko is the
28
+ * single source of truth (SSOT), and en carries the same key set — fill the same keys for a new
29
+ * language (or fill partially and track progress via `register()`'s `missingKeys`).
16
30
  */
17
31
  export interface LocaleMessages {
18
32
  /** 우클릭 컨텍스트 메뉴 라벨. / Right-click context-menu labels. */
@@ -226,21 +240,38 @@ export interface LocaleMessages {
226
240
  printSummary: MessageValue;
227
241
  };
228
242
  }
229
- /** 부분 오버라이드(2단 딥머지, 카탈로그 위). / Partial override (2-level deep-merge over the catalog). */
243
+ /**
244
+ * `register()`/`extend()` 에 일부 섹션·키만 넘길 때 쓰는 타입(2단 딥머지로 카탈로그 위에 얹힌다).
245
+ * 전체 언어를 다 채우지 않아도 로케일을 등록할 수 있게 해 준다.
246
+ * / Type used when passing only some sections/keys to `register()`/`extend()` (layered onto the
247
+ * catalog via 2-level deep-merge) — lets you register a locale before every key is translated.
248
+ */
230
249
  export type PartialLocaleMessages = {
231
250
  [S in keyof LocaleMessages]?: Partial<LocaleMessages[S]>;
232
251
  };
233
- /** dot-key 유니온(`'filter.apply'` 등) — 오타를 컴파일 에러화. / Dot-key union (e.g. `'filter.apply'`) — typos become compile errors. */
252
+ /**
253
+ * `t()` 에 넘길 수 있는 모든 유효 키의 유니온 타입(예: `'filter.apply'`). 왜 필요한가:
254
+ * `t('filter.aply')` 처럼 오타가 나면 이 타입이 없을 때는 런타임에야 "키 없음" 경고로 드러난다 —
255
+ * 유니온으로 묶어 두면 컴파일 타임에 바로 에러가 난다.
256
+ * / Union of every key valid for `t()` (e.g. `'filter.apply'`). Why this exists: without it, a typo
257
+ * like `t('filter.aply')` only surfaces as a runtime "unknown key" warning; unioning the keys
258
+ * turns it into a compile-time error instead.
259
+ */
234
260
  export type LocaleMessageKey = {
235
261
  [S in keyof LocaleMessages]: `${S & string}.${keyof LocaleMessages[S] & string}`;
236
262
  }[keyof LocaleMessages];
237
263
  /**
238
- * 문화 규칙 단일 컨텍스트(REQ-T9-816, DD-12 §2.4). 값객체·포맷터·정렬·검색이 문화를 **오직 여기서만**
239
- * 조회한다(불변식 3). 아래 확장 필드는 전부 additive·옵셔널 — 기존 3필드·소비처 불변(semver 하위호환).
240
- * ★대표 소유 = DD-12: DD-04 `FormatContext.locale`·DD-15 `ExportRunCtx.locale` 는 이 타입을 import(재선언 금지).
241
- * / Single culture context (REQ-T9-816, DD-12 §2.4). The only lawful culture-lookup path (invariant 3).
242
- * The extension fields below are all additive & optional — original 3 fields/consumers unchanged.
243
- * ★Canonical owner = DD-12; DD-04/DD-15 import this type (no re-declaration).
264
+ * 문화(지역) 규칙을 담는 단일 컨텍스트 타입. 통화·날짜·정렬·검색 등 "문화마다 다른 규칙"을
265
+ * 여러 군데서 각자 조회하게 두면, 그리드와 내보내기(export) 가 서로 다른 로케일을 참조하는
266
+ * 불일치가 생길 수 있다 — 그래서 값객체·포맷터·정렬·검색이 문화 정보를 **오직 이 타입을
267
+ * 통해서만** 조회하도록 강제한다(단일 진실 공급원). 아래 확장 필드는 전부 추가·옵셔널이라
268
+ * 기존 3필드를 쓰던 코드는 그대로 동작한다(semver 하위 호환).
269
+ * / A single context type carrying culture (locale) rules. Letting currency/date/sort/search each
270
+ * look up their own culture rules independently could let the grid and the export path silently
271
+ * disagree on locale — so value objects, formatters, sort, and search look up culture
272
+ * information **only through this type** (single source of truth). The extension fields below
273
+ * are all additive and optional, so code written against the original 3 fields keeps working
274
+ * unchanged (semver-compatible).
244
275
  */
245
276
  export interface LocaleMeta {
246
277
  /** BCP-47 태그(toLocaleString/lang/인쇄 템플릿용). 예 'ko-KR'. / BCP-47 tag (for toLocaleString/lang/print template). e.g. 'ko-KR'. */
@@ -268,7 +299,7 @@ export interface LocaleMeta {
268
299
  /** 텍스트팽창 계수(레이아웃 예산 힌트·의사로케일). 예 de≈1.35, 의사로케일=1.4(REQ-T9-817). / Text-expansion factor. */
269
300
  readonly textExpansion?: number;
270
301
  }
271
- /** register() 결과 — 누락 키 정직 신호(막지 않음). / register() result — honest missing-key signal (never blocks). */
302
+ /** register() 결과 — 누락 키 신호(막지 않음). / register() result — missing-key signal (never blocks). */
272
303
  export interface LocaleRegisterResult {
273
304
  readonly missingKeys: string[];
274
305
  }