create-mendix-widget-gleam 4.0.1 → 4.0.2

package/README.md

@@ -28,7 +28,7 @@ my-widget/
     components/
       hello_world.gleam      # Hello World 공유 컴포넌트
   package.json                   # npm 의존성 (React, 외부 라이브러리 등)
-  gleam.toml                   # Gleam 프로젝트 설정 (glendix >= 4.0.3 + mendraw >= 1.1.11 의존성 포함)
+  gleam.toml                   # Gleam 프로젝트 설정 (glendix >= 4.0.4 + mendraw >= 1.2.1 의존성 포함)
   CLAUDE.md                    # AI 어시스턴트용 프로젝트 컨텍스트
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-mendix-widget-gleam",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "description": "Scaffold a Mendix Pluggable Widget powered by Gleam",
   "type": "module",
   "license": "Apache-2.0",

package/src/templates/claude_md.mjs

@@ -93,7 +93,7 @@ src/*.gleam → gleam build → build/dev/javascript/**/*.mjs → Bridge JS (aut
 For detailed glendix API and Gleam syntax, see:
 
 - docs/glendix_guide.md — Complete React/Mendix bindings guide (elements, Hooks, events, Mendix types, practical patterns, troubleshooting)
-- docs/mendraw_guide.md — mendraw usage guide (Marketplace download, classic widget support)
+- docs/mendraw_guide.md — mendraw usage guide (widget binding generation, Marketplace download, Classic widgets, Synthetic Data, Mendix type API)
 - docs/gleam_language_tour.md — Gleam syntax reference (types, pattern matching, FFI, use keyword, etc.)
 
 ## Mendix Documentation Sources

package/src/templates/readme_md.mjs

@@ -125,7 +125,7 @@ src/
 package.json                       # npm dependencies (React, external libraries, etc.)
 \`\`\`
 
-React bindings come from [redraw](https://hexdocs.pm/redraw/)/[redraw_dom](https://hexdocs.pm/redraw_dom/), while Mendix API and JS Interop bindings are provided by [mendraw](https://hexdocs.pm/mendraw/).
+React bindings come from [redraw](https://hexdocs.pm/redraw/)/[redraw_dom](https://hexdocs.pm/redraw_dom/), Mendix API bindings from [mendraw](https://hexdocs.pm/mendraw/), and JS Interop from [glendix](https://hexdocs.pm/glendix/).
 
 ## Using External React Components
 
@@ -293,7 +293,7 @@ src/
 package.json                       # npm 의존성 (React, 외부 라이브러리 등)
 \`\`\`
 
-React 바인딩은 [redraw](https://hexdocs.pm/redraw/)/[redraw_dom](https://hexdocs.pm/redraw_dom/)이, Mendix API 및 JS Interop 바인딩은 [mendraw](https://hexdocs.pm/mendraw/)가 제공합니다.
+React 바인딩은 [redraw](https://hexdocs.pm/redraw/)/[redraw_dom](https://hexdocs.pm/redraw_dom/)이, Mendix API 바인딩은 [mendraw](https://hexdocs.pm/mendraw/)가, JS Interop은 [glendix](https://hexdocs.pm/glendix/)가 제공합니다.
 
 ## 외부 React 컴포넌트 사용
 
@@ -461,7 +461,7 @@ src/
 package.json                       # npm依存関係（React、外部ライブラリなど）
 \`\`\`
 
-Reactバインディングは[redraw](https://hexdocs.pm/redraw/)/[redraw_dom](https://hexdocs.pm/redraw_dom/)が、Mendix APIおよびJS Interopバインディングは[mendraw](https://hexdocs.pm/mendraw/)が提供する。
+Reactバインディングは[redraw](https://hexdocs.pm/redraw/)/[redraw_dom](https://hexdocs.pm/redraw_dom/)が、Mendix APIバインディングは[mendraw](https://hexdocs.pm/mendraw/)が、JS Interopは[glendix](https://hexdocs.pm/glendix/)が提供する。
 
 ## 外部Reactコンポーネントの使用
 

package/template/docs/glendix_guide.md

@@ -1,4 +1,4 @@
-# glendix v4.0.3 — Agent Reference Guide
+# glendix v4.0.4 — Agent Reference Guide
 
 > 이 문서는 AI 에이전트(LLM)가 glendix 코드를 작성할 때 참조하는 가이드입니다. 각 섹션은 독립적으로 읽을 수 있습니다.
 
@@ -46,8 +46,8 @@ glendix는 Gleam으로 Mendix Pluggable Widget을 작성하는 FFI 라이브러
 
 ```toml
 [dependencies]
-glendix = ">= 4.0.3 and < 5.0.0"
-mendraw = ">= 1.1.11 and < 2.0.0"
+glendix = ">= 4.0.4 and < 5.0.0"
+mendraw = ">= 1.2.1 and < 2.0.0"
 ```
 
 Peer dependency (위젯 프로젝트 `package.json`):

package/template/docs/mendraw_guide.md

@@ -1,7 +1,7 @@
 # mendraw 사용 가이드
 
-Mendix 위젯 Gleam/[redraw](https://hexdocs.pm/redraw/) 바인딩 라이브러리.
-Classic(Dojo) 위젯 지원과 Marketplace 검색/다운로드 기능을 제공한다.
+Mendix 위젯 `.mpk` 파일에서 Gleam/[redraw](https://hexdocs.pm/redraw/) 바인딩을 자동 생성하는 라이브러리.
+Pluggable(React) 위젯과 Classic(Dojo) 위젯을 모두 지원한다.
 
 ---
 
@@ -9,18 +9,36 @@ Classic(Dojo) 위젯 지원과 Marketplace 검색/다운로드 기능을 제공
 
 - [사전 준비](#사전-준비)
 - [설치](#설치)
+- [빠른 시작](#빠른-시작)
 - [Marketplace에서 위젯 다운로드](#marketplace에서-위젯-다운로드)
-- [Classic (Dojo) 위젯](#classic-dojo-위젯)
-  - [Classic 위젯 직접 렌더링](#classic-위젯-직접-렌더링)
+- [생성된 바인딩 사용하기](#생성된-바인딩-사용하기)
+  - [Pluggable 위젯](#pluggable-위젯)
+  - [Classic (Dojo) 위젯](#classic-dojo-위젯)
+- [저수준 API로 직접 조립하기](#저수준-api로-직접-조립하기)
+  - [위젯 컴포넌트 조회](#위젯-컴포넌트-조회)
+  - [Prop 래핑](#prop-래핑)
+  - [컴포넌트 렌더링](#컴포넌트-렌더링)
 - [JsProps 다루기](#jsprops-다루기)
   - [Prop 접근자](#prop-접근자)
   - [ValueStatus](#valuestatus)
   - [Option 변환](#option-변환)
+- [생성된 코드 구조](#생성된-코드-구조)
+  - [Pluggable 위젯 바인딩 예시](#pluggable-위젯-바인딩-예시)
+  - [Classic 위젯 바인딩 예시](#classic-위젯-바인딩-예시)
+  - [파일명 변환 규칙](#파일명-변환-규칙)
+- [생성된 바인딩 커스터마이징](#생성된-바인딩-커스터마이징)
 - [API 레퍼런스](#api-레퍼런스)
   - [mendraw/mendix](#mendrawmendix)
+  - [mendraw/widget](#mendrawwidget)
   - [mendraw/interop](#mendrawinterop)
   - [mendraw/classic](#mendrawclassic)
   - [mendraw/marketplace](#mendrawmarketplace)
+- [외부 API 데이터를 Mendix 위젯에 전달 (Synthetic Data)](#외부-api-데이터를-mendix-위젯에-전달-synthetic-data)
+  - [개요](#synthetic-개요)
+  - [기본 사용법](#synthetic-기본-사용법)
+  - [차트 위젯에 사용하기](#차트-위젯에-사용하기)
+  - [DynamicDataGrid에 사용하기](#dynamicdatagrid에-사용하기)
+  - [API 레퍼런스 (synthetic)](#api-레퍼런스-synthetic)
 - [glendix 프로젝트에서 사용하기](#glendix-프로젝트에서-사용하기)
 - [문제 해결](#문제-해결)
 
@@ -45,7 +63,7 @@ gleam add mendraw@1
 
 ```toml
 [dependencies]
-mendraw = ">= 1.1.11 and < 2.0.0"
+mendraw = ">= 1.0.0 and < 2.0.0"
 ```
 
 mendraw는 `gleam_stdlib`, `gleam_javascript`, `redraw`, `redraw_dom`을 함께 가져온다.
@@ -53,9 +71,61 @@ mendraw는 `gleam_stdlib`, `gleam_javascript`, `redraw`, `redraw_dom`을 함께
 
 ---
 
+## 빠른 시작
+
+### 1단계: 위젯 등록
+
+**`gleam.toml`로 자동 다운로드**
+
+```toml
+[tools.mendraw.widgets.Charts]
+version = "3.0.0"
+# s3_id = "com/..."   ← 있으면 인증 없이 직접 다운로드
+```
+
+`gleam run -m mendraw/install` 실행 시 `build/widgets/`에 캐시하고 바인딩을 자동 생성한다.
+Marketplace TUI(`gleam run -m mendraw/marketplace`)에서 다운로드하면 gleam.toml에 자동 추가된다.
+
+### 2단계: 바인딩 생성
+
+```sh
+gleam run -m mendraw/install
+```
+
+실행 결과:
+
+- TOML에 등록된 위젯을 `build/widgets/`에 다운로드/캐시
+- `src/widgets/`에 위젯별 `.gleam` 바인딩 파일이 생성된다
+- 빌드 경로에 `widget_ffi.mjs`(컴포넌트 레지스트리)가 생성된다
+- Classic 위젯이 있으면 `classic_ffi.mjs`(런타임)도 생성된다
+
+```
+src/widgets/
+├── switch.gleam           ← Pluggable 위젯
+├── area_chart.gleam       ← Charts.mpk에서 추출
+├── bar_chart.gleam
+└── camera_widget.gleam    ← Classic 위젯
+```
+
+### 3단계: 바인딩 사용
+
+```gleam
+import widgets/switch
+import mendraw/mendix.{type JsProps}
+import redraw.{type Element}
+
+pub fn my_view(props: JsProps) -> Element {
+  switch.render(props)
+}
+```
+
+이것으로 끝이다. 아래에서 각 단계를 자세히 설명한다.
+
+---
+
 ## Marketplace에서 위젯 다운로드
 
-Mendix Marketplace에서 위젯을 검색하고 다운로드할 수 있는 TUI를 제공한다.
+`.mpk` 파일을 직접 구하는 대신, Mendix Marketplace에서 위젯을 검색하고 다운로드할 수 있는 TUI를 제공한다.
 
 ### 사전 설정
 
@@ -112,7 +182,8 @@ gleam run -m mendraw/marketplace
 
 ### 다운로드 후
 
-다운로드한 위젯은 `gleam.toml`의 `[tools.mendraw.widgets.*]`에 자동 추가된다.
+다운로드한 위젯은 `build/widgets/`에 캐시되고 `gleam.toml`의 `[tools.mendraw.widgets.*]`에 자동 추가된다.
+다운로드가 1개 이상 완료되면 자동으로 `cmd.generate_widget_bindings()`가 실행되어 바인딩이 생성된다.
 
 > **참고**: 첫 다운로드 시 chrobot_extra 사이드카를 통한 Mendix 로그인이 필요할 수 있다.
 > 로그인 세션은 `.marketplace-cache/session.json`에 캐시된다.
@@ -120,7 +191,124 @@ gleam run -m mendraw/marketplace
 
 ---
 
-## Classic (Dojo) 위젯
+## 생성된 바인딩 사용하기
+
+`gleam run -m mendraw/install`이 생성하는 `.gleam` 파일에는 `render` 함수가 포함된다.
+이 함수는 Mendix가 전달하는 `JsProps`를 받아 `redraw` `Element`를 반환한다.
+
+### Pluggable 위젯
+
+Pluggable 위젯(React 기반)의 생성된 바인딩:
+
+```gleam
+import widgets/switch
+import mendraw/mendix.{type JsProps}
+import redraw.{type Element}
+
+/// Mendix가 위젯에 전달하는 props를 그대로 넘긴다
+pub fn view(props: JsProps) -> Element {
+  switch.render(props)
+}
+```
+
+생성된 `render` 함수는 내부적으로:
+1. `mendix.get_prop_required`/`mendix.get_prop`으로 props에서 속성을 추출
+2. `widget.component`로 원본 React 컴포넌트를 가져옴
+3. `interop.component_el`로 redraw Element를 생성
+
+### Classic (Dojo) 위젯
+
+Classic 위젯(Dojo 기반)의 생성된 바인딩:
+
+```gleam
+import widgets/camera_widget
+import mendraw/mendix.{type JsProps}
+import redraw.{type Element}
+
+pub fn view(props: JsProps) -> Element {
+  camera_widget.render(props)
+}
+```
+
+Classic 위젯은 내부적으로 DOM 컨테이너를 생성하고, `useEffect`로 위젯의 마운트/언마운트를 관리한다.
+
+---
+
+## 저수준 API로 직접 조립하기
+
+생성된 바인딩 대신, `mendraw/widget`과 `mendraw/interop` 모듈을 직접 사용하여
+위젯 렌더링을 세밀하게 제어할 수 있다.
+
+### 위젯 컴포넌트 조회
+
+```gleam
+import mendraw/widget
+
+// 위젯 이름으로 React 컴포넌트를 가져온다
+let comp = widget.component("Switch")
+```
+
+위젯 이름은 `.mpk` 파일의 `widget.xml`에 정의된 `<name>` 값이다.
+
+### Prop 래핑
+
+Mendix 위젯은 일반 값이 아닌 래핑된 값 객체를 기대한다.
+mendraw는 세 가지 prop 래퍼를 제공한다:
+
+```gleam
+import mendraw/widget
+
+// 1. 읽기 전용 prop (DynamicValue)
+// expression, textTemplate 등 읽기 전용 속성에 사용
+widget.prop("caption", "제목 텍스트")
+
+// 2. 편집 가능한 prop (EditableValue)
+// 사용자 입력이 필요한 속성에 사용
+widget.editable_prop("textAttr", current_value, "표시값", fn(new_val) {
+  // 값이 변경되었을 때의 처리
+  Nil
+})
+
+// 3. 액션 prop (ActionValue)
+// onClick, onLeave 등 이벤트 핸들러에 사용
+widget.action_prop("onClick", fn() {
+  // 클릭 시 처리
+  Nil
+})
+```
+
+각 래퍼가 생성하는 Mendix 값 객체:
+
+| 래퍼 | Mendix 타입 | 구조 |
+|------|------------|------|
+| `prop` | `DynamicValue` | `{ status: "available", value }` |
+| `editable_prop` | `EditableValue` | `{ status: "available", value, displayValue, readOnly: false, setValue, ... }` |
+| `action_prop` | `ActionValue` | `{ canExecute: true, isExecuting: false, execute }` |
+
+### 컴포넌트 렌더링
+
+```gleam
+import mendraw/interop
+import mendraw/widget
+import redraw/dom/attribute
+
+let comp = widget.component("Switch")
+
+// 속성 + 자식 엘리먼트
+interop.component_el(comp, [
+  widget.prop("caption", "제목"),
+  widget.editable_prop("textAttr", value, "표시값", set_value),
+  widget.action_prop("onClick", handler),
+], [])
+
+// 속성 없이 자식만
+interop.component_el_(comp, [child1, child2])
+
+// 자식 없는 self-closing 컴포넌트
+interop.void_component_el(comp, [
+  widget.prop("caption", "읽기 전용"),
+])
+```
 
 ### Classic 위젯 직접 렌더링
 
@@ -213,6 +401,118 @@ let js_value = mendix.from_option(gleam_option)
 
 ---
 
+## 생성된 코드 구조
+
+### Pluggable 위젯 바인딩 예시
+
+Switch 위젯에서 생성되는 `src/widgets/switch.gleam`:
+
+```gleam
+// @generated mendraw/install — 직접 수정 금지
+
+import gleam/option.{None, Some}
+import mendraw/interop
+import mendraw/mendix.{type JsProps}
+import mendraw/widget
+import redraw.{type Element}
+import redraw/dom/attribute
+
+pub fn render(props: JsProps) -> Element {
+  // 필수 속성
+  let text_attr = mendix.get_prop_required(props, "textAttr")
+  // 선택 속성
+  let caption = mendix.get_prop(props, "caption")
+
+  let comp = widget.component("Switch")
+  interop.component_el(
+    comp,
+    [
+      attribute.attribute("textAttr", text_attr),
+      // 선택 속성은 있을 때만 전달
+      ..optional_attr("caption", caption)
+    ],
+    [],
+  )
+}
+
+fn optional_attr(key: String, value: option.Option(a)) -> List(attribute.Attribute) {
+  case value {
+    Some(v) -> [attribute.attribute(key, v)]
+    None -> []
+  }
+}
+```
+
+### Classic 위젯 바인딩 예시
+
+CameraWidget 위젯에서 생성되는 `src/widgets/camera_widget.gleam`:
+
+```gleam
+// @generated mendraw/install — 직접 수정 금지
+
+import gleam/option.{None, Some}
+import mendraw/classic
+import mendraw/mendix.{type JsProps}
+import redraw.{type Element}
+
+pub fn render(props: JsProps) -> Element {
+  let mf_to_execute = mendix.get_prop_required(props, "mfToExecute")
+  let prefer_rear_camera = mendix.get_prop_required(props, "preferRearCamera")
+
+  classic.render("CameraWidget.widget.CameraWidget", [
+    #("mfToExecute", classic.to_dynamic(mf_to_execute)),
+    #("preferRearCamera", classic.to_dynamic(prefer_rear_camera)),
+  ])
+}
+```
+
+### 파일명 변환 규칙
+
+위젯 이름은 Gleam 모듈명 규칙에 맞게 snake_case로 변환된다:
+
+| 위젯 이름 | 파일명 | 모듈 경로 |
+|-----------|--------|----------|
+| `Switch` | `switch.gleam` | `widgets/switch` |
+| `AreaChart` | `area_chart.gleam` | `widgets/area_chart` |
+| `BarChart` | `bar_chart.gleam` | `widgets/bar_chart` |
+| `CameraWidget` | `camera_widget.gleam` | `widgets/camera_widget` |
+| `Progress Bar` | `progress_bar.gleam` | `widgets/progress_bar` |
+
+---
+
+## 생성된 바인딩 커스터마이징
+
+생성된 `src/widgets/*.gleam` 파일은 한 번 생성된 후 **덮어쓰지 않는다**.
+따라서 생성된 파일을 직접 수정하여 커스터마이징할 수 있다:
+
+```gleam
+// src/widgets/switch.gleam — 사용자가 수정한 버전
+import mendraw/interop
+import mendraw/mendix.{type JsProps}
+import mendraw/widget
+import redraw.{type Element}
+import redraw/dom/attribute
+
+pub fn render(props: JsProps) -> Element {
+  let text_attr = mendix.get_prop_required(props, "textAttr")
+  let comp = widget.component("Switch")
+  interop.component_el(
+    comp,
+    [
+      widget.editable_prop("textAttr", text_attr, "표시값", fn(v) { Nil }),
+      // 커스텀: 고정 캡션 추가
+      widget.prop("caption", "내 스위치"),
+    ],
+    [],
+  )
+}
+```
+
+> **주의**: 수정한 파일은 `gleam run -m mendraw/install`을 다시 실행해도 덮어쓰지 않는다.
+> 바인딩을 재생성하려면 해당 파일을 삭제한 후 install을 다시 실행한다.
+
+---
+
 ## API 레퍼런스
 
 ### mendraw/mendix
@@ -241,6 +541,17 @@ Mendix Pluggable Widget API의 핵심 타입과 props 접근자.
 | `to_option` | `(a) -> Option(a)` | JS undefined/null → `None` |
 | `from_option` | `(Option(a)) -> a` | Gleam `Option` → JS 값 (`None` → undefined) |
 
+### mendraw/widget
+
+Pluggable 위젯 컴포넌트 조회 및 prop 래핑.
+
+| 함수 | 시그니처 | 설명 |
+|------|----------|------|
+| `component` | `(String) -> JsComponent` | 이름으로 위젯 컴포넌트 조회 |
+| `prop` | `(String, a) -> Attribute` | `DynamicValue`로 래핑 (읽기 전용) |
+| `editable_prop` | `(String, a, String, fn(a) -> Nil) -> Attribute` | `EditableValue`로 래핑 (편집 가능) |
+| `action_prop` | `(String, fn() -> Nil) -> Attribute` | `ActionValue`로 래핑 (이벤트 핸들러) |
+
 ### mendraw/interop
 
 외부 JS React 컴포넌트를 redraw Element로 변환하는 브릿지.
@@ -274,8 +585,10 @@ Classic (Dojo) 위젯을 React 내부에서 렌더링.
 | 함수 | 시그니처 | 설명 |
 |------|----------|------|
 | `file_exists` | `(String) -> Bool` | 파일 존재 여부 |
-| `resolve_toml_widgets` | `() -> Nil` | gleam.toml [tools.mendraw.widgets.*] 다운로드 |
+| `generate_widget_bindings` | `() -> Nil` | build/widgets/ 캐시에서 바인딩 생성 |
+| `resolve_toml_widgets` | `() -> Nil` | gleam.toml [tools.mendraw.widgets.*] 다운로드/캐시 |
 | `write_widget_toml` | `(String, String, Option(Int), Option(String)) -> Nil` | gleam.toml에 위젯 항목 쓰기 |
+| `download_to_cache` | `(String, String, String, Option(Int)) -> Bool` | URL에서 build/widgets/{name}/에 다운로드+추출 |
 
 ### mendraw/marketplace
 
@@ -289,6 +602,8 @@ Mendix Marketplace 위젯 검색·다운로드 TUI. `gleam run -m mendraw/market
 | 백그라운드 로딩 | 전체 위젯 목록을 백그라운드에서 점진적으로 로드 |
 | 버전 선택 | Content API + chrobot_extra 사이드카(XAS)로 버전별 다운로드 정보 조회 |
 | 자동 TOML 기록 | 다운로드 시 gleam.toml에 위젯 항목 자동 추가 |
+| 캐시 다운로드 | build/widgets/에 캐시 (소스 컨트롤에 .mpk 불필요) |
+| 자동 바인딩 | 다운로드 완료 후 `generate_widget_bindings()` 자동 호출 |
 
 #### 의존성
 
@@ -298,10 +613,211 @@ Mendix Marketplace 위젯 검색·다운로드 TUI. `gleam run -m mendraw/market
 
 ---
 
+## 외부 API 데이터를 Mendix 위젯에 전달 (Synthetic Data)
+
+### Synthetic 개요
+
+Mendix 차트/그리드 위젯은 `ListValue`, `ObjectItem`, `ListAttributeValue` 등 Mendix 런타임에서만 생성되는 opaque 객체를 데이터 소스로 사용한다. `mendraw/synthetic` 모듈은 이 인터페이스를 모사하는 객체를 Gleam에서 직접 생성하여, 외부 API 데이터(CoinGecko, 날씨 API 등)를 Mendix Marketplace 위젯에 직접 전달할 수 있게 한다.
+
+지원하는 위젯 유형:
+- **Charts** (Line, Area, Bar, Column, Pie, Time Series, Heat Map, Bubble, Custom)
+- **Dynamic Data Grid** (3단계 cell/row/column 계층 포함)
+
+### Synthetic 기본 사용법
+
+```gleam
+import mendraw/synthetic
+import gleam/float
+
+// 1. ObjectItem 생성 — 데이터 행 수만큼
+let items = synthetic.object_items(3)  // synth_0, synth_1, synth_2
+
+// 2. ListValue 생성 — ObjectItem 목록을 감싸는 데이터 소스
+let lv = synthetic.list_value(items)
+
+// 3. ListAttributeValue 생성 — 각 아이템의 특정 필드값 + 표시 함수 + Mendix 타입
+let prices = [100.0, 200.0, 150.0]
+let price_attr = synthetic.list_attribute(items, prices, float.to_string, "Decimal")
+// price_attr.get(synth_0) → EditableValue { value: BigNumber(100.0), displayValue: "100.0" }
+
+// 4. TextTemplate 생성
+let static_name = synthetic.text_template("My Series")
+// chart에서 .value로 직접 접근하거나 .get(item)으로 접근 모두 지원
+
+// 5. List-bound TextTemplate — 아이템별 다른 텍스트
+let names = ["Bitcoin", "Ethereum", "Solana"]
+let name_tmpl = synthetic.list_text_template(items, names)
+// name_tmpl.get(synth_0) → { status: "available", value: "Bitcoin" }
+```
+
+**타입 래핑 규칙:**
+
+| Mendix 타입 | Gleam 값 | JS 래핑 |
+|---|---|---|
+| `"Decimal"`, `"Integer"`, `"Long"` | `Float` / `Int` | Big.js 호환 객체 (`.toNumber()`, `.toFixed()` 등) |
+| `"DateTime"` | `Float` (밀리초 타임스탬프) | `new Date(timestamp)` |
+| `"String"` | `String` | 그대로 전달 |
+
+### 차트 위젯에 사용하기
+
+Mendix 차트 위젯의 `lines`/`series` prop은 시리즈 설정 객체의 JS 배열을 기대한다.
+`chart_series_static()`으로 이 객체를 생성하고, `to_js_array()`로 Gleam List를 JS Array로 변환한다.
+
+#### Line Chart / Time Series 예시
+
+```gleam
+import mendraw/synthetic
+import mendraw/interop
+import mendraw/widget
+import redraw/dom/attribute
+import gleam/float
+
+let items = synthetic.object_items(100)
+let lv = synthetic.list_value(items)
+let x_attr = synthetic.list_attribute(items, timestamps, float.to_string, "DateTime")
+let y_attr = synthetic.list_attribute(items, prices, float.to_string, "Decimal")
+
+// 시리즈 설정 객체 생성
+let series = synthetic.chart_series_static(
+  lv, x_attr, y_attr,
+  synthetic.text_template("BTC Price"),
+  "none",     // aggregation: "none" | "count" | "sum" | "avg" ...
+  "linear",   // interpolation: "linear" | "spline"
+  "line",     // lineStyle: "line" | "lines+markers"
+  "",         // lineColor (빈 문자열 = 기본값)
+  "",         // barColor
+)
+
+let comp = widget.component("Line chart")
+interop.component_el(comp, [
+  attribute.attribute("lines", synthetic.to_js_array([series])),
+  attribute.attribute("showLegend", True),
+  attribute.attribute("gridLines", "horizontal"),
+  attribute.attribute("widthUnit", "percentage"),
+  attribute.attribute("width", 100),
+  attribute.attribute("heightUnit", "pixels"),
+  attribute.attribute("height", 400),
+], [])
+```
+
+Time Series 위젯도 동일한 구조이며, `showRangeSlider` prop을 추가하면 범위 슬라이더가 표시된다.
+
+#### Pie Chart 예시
+
+Pie Chart는 `seriesDataSource`, `seriesName`, `seriesValueAttribute`를 직접 전달한다 (시리즈 배열 없음).
+
+```gleam
+let items = synthetic.object_items(10)
+let lv = synthetic.list_value(items)
+let name_tmpl = synthetic.list_text_template(items, coin_names)
+let value_attr = synthetic.list_attribute(items, market_caps, float.to_string, "Decimal")
+
+let comp = widget.component("Pie chart")
+interop.component_el(comp, [
+  attribute.attribute("seriesDataSource", lv),
+  attribute.attribute("seriesName", name_tmpl),
+  attribute.attribute("seriesValueAttribute", value_attr),
+  attribute.attribute("showLegend", True),
+], [])
+```
+
+#### Column / Bar Chart 예시
+
+Column/Bar 차트는 Line Chart와 동일한 시리즈 구조를 사용하되, prop 키가 `"series"`이다.
+
+```gleam
+let series = synthetic.chart_series_static(
+  lv, x_attr, y_attr,
+  synthetic.text_template("Volume"),
+  "none", "", "", "", "#3b82f6",  // barColor 지정
+)
+
+let comp = widget.component("Column chart")
+interop.component_el(comp, [
+  attribute.attribute("series", synthetic.to_js_array([series])),
+  // ...
+], [])
+```
+
+### DynamicDataGrid에 사용하기
+
+DynamicDataGrid는 3단계 계층 구조를 사용한다:
+- **Row** — 행 (예: 각 코인)
+- **Column** — 열 (예: Price, Volume, Market Cap)
+- **Cell** — 행×열 교차점의 값 (N rows × M columns = N*M cells)
+
+Cell은 `referenceRow`와 `referenceColumn` association으로 자신이 속한 행/열을 참조한다.
+
+```gleam
+import mendraw/synthetic
+
+let num_rows = 20   // 코인 수
+let num_cols = 5    // 속성 수
+let num_cells = num_rows * num_cols
+
+let row_items = synthetic.object_items(num_rows)
+let col_items = synthetic.object_items(num_cols)
+let cell_items = synthetic.object_items(num_cells)
+
+// 데이터 소스
+let cell_source = synthetic.list_value(cell_items)
+let row_source = synthetic.list_value(row_items)
+let col_source = synthetic.list_value(col_items)
+
+// Cell→Row, Cell→Column 참조 (각 cell이 어느 행/열에 속하는지)
+let ref_row = synthetic.association(cell_items, cell_to_row_mapping)
+let ref_col = synthetic.association(cell_items, cell_to_col_mapping)
+
+// 표시 속성
+let cell_attr = synthetic.list_attribute(cell_items, cell_values, fn(s) { s }, "String")
+let row_attr = synthetic.list_attribute(row_items, row_names, fn(s) { s }, "String")
+let col_attr = synthetic.list_attribute(col_items, column_headers, fn(s) { s }, "String")
+
+let comp = widget.component("Dynamic data grid")
+interop.component_el(comp, [
+  attribute.attribute("dataSourceCell", cell_source),
+  attribute.attribute("dataSourceRow", row_source),
+  attribute.attribute("dataSourceColumn", col_source),
+  attribute.attribute("referenceRow", ref_row),
+  attribute.attribute("referenceColumn", ref_col),
+  attribute.attribute("showCellAs", "attribute"),
+  attribute.attribute("cellAttribute", cell_attr),
+  attribute.attribute("showRowAs", "attribute"),
+  attribute.attribute("rowAttribute", row_attr),
+  attribute.attribute("showHeaderAs", "attribute"),
+  attribute.attribute("headerAttribute", col_attr),
+  attribute.attribute("renderAs", "table"),
+], [])
+```
+
+### API 레퍼런스 (synthetic)
+
+#### 데이터 생성
+
+| 함수 | 시그니처 | 설명 |
+|------|----------|------|
+| `object_item` | `(String) -> ObjectItem` | 지정 id로 ObjectItem 생성 |
+| `object_items` | `(Int) -> List(ObjectItem)` | N개 ObjectItem 생성 (`synth_0`, `synth_1`, ...) |
+| `list_value` | `(List(ObjectItem)) -> ListValue` | ObjectItem 목록을 ListValue로 래핑 |
+| `list_attribute` | `(List(ObjectItem), List(a), fn(a) -> String, String) -> ListAttributeValue` | 아이템별 속성값 + 표시함수 + Mendix 타입 |
+| `text_template` | `(String) -> a` | 정적 텍스트 템플릿 (`.value` + `.get()` 양쪽 지원) |
+| `list_text_template` | `(List(ObjectItem), List(String)) -> ListExpressionValue` | 아이템별 텍스트 템플릿 |
+| `list_expression` | `(List(ObjectItem), List(a)) -> ListExpressionValue` | 아이템별 표현식 값 |
+| `association` | `(List(ObjectItem), List(ObjectItem)) -> a` | 소스→타겟 연관 관계 |
+
+#### 차트 시리즈
+
+| 함수 | 시그니처 | 설명 |
+|------|----------|------|
+| `chart_series_static` | `(ListValue, ListAttributeValue, ListAttributeValue, a, String, String, String, String, String) -> b` | 정적 차트 시리즈 설정 객체 생성 (dataSource, x, y, name, aggregation, interpolation, lineStyle, lineColor, barColor) |
+| `to_js_array` | `(List(a)) -> b` | Gleam List → JS Array 변환 |
+
+---
+
 ## glendix 프로젝트에서 사용하기
 
 [glendix](https://github.com/) 프로젝트에서 mendraw를 의존성으로 추가하면,
-위젯 TOML 해석을 mendraw에 위임할 수 있다:
+MPK 바인딩 생성을 mendraw에 위임할 수 있다:
 
 ```gleam
 // glendix의 install.gleam
@@ -310,7 +826,8 @@ import mendraw/cmd as mendraw_cmd
 pub fn main() {
   cmd.exec(cmd.detect_install_command())
   cmd.generate_bindings()
-  mendraw_cmd.resolve_toml_widgets()
+  // MPK 위젯 바인딩 생성을 mendraw에 위임
+  mendraw_cmd.generate_widget_bindings()
 }
 ```
 
@@ -318,11 +835,61 @@ pub fn main() {
 
 ## 문제 해결
 
+### `gleam run -m mendraw/install` 실행 시 아무것도 생성되지 않는다
+
+- `gleam.toml`에 `[tools.mendraw.widgets.*]` 섹션이 있는지 확인
+- `.mpk` 파일이 유효한 ZIP 형식인지 확인
+- 콘솔 출력을 확인하여 파싱 오류가 없는지 점검
+
+### 이미 존재하는 바인딩 파일이 업데이트되지 않는다
+
+mendraw는 `src/widgets/`에 이미 존재하는 `.gleam` 파일을 **덮어쓰지 않는다** (사용자 수정 보호).
+바인딩을 재생성하려면:
+
+```sh
+# 특정 파일만 재생성
+rm src/widgets/switch.gleam
+gleam run -m mendraw/install
+
+# 전체 재생성
+rm src/widgets/*.gleam
+gleam run -m mendraw/install
+```
+
+### "widget_ffi.mjs not generated" 에러
+
+`widget_ffi.mjs`와 `classic_ffi.mjs`는 스텁 파일로 시작한다.
+`gleam run -m mendraw/install`을 실행하면 빌드 경로에 실제 파일이 생성된다.
+install을 실행하지 않고 위젯 모듈을 import하면 이 에러가 발생한다.
+
 ### Classic 위젯이 렌더링되지 않는다
 
 - Classic 위젯은 DOM 컨테이너를 생성하고 imperative하게 마운트한다
 - `classic_ffi.mjs`가 빌드 경로에 정상적으로 생성되었는지 확인
 - `widget_id`가 정확한지 확인 (예: `"CameraWidget.widget.CameraWidget"`)
 
+### Synthetic 데이터 차트에서 `toNumber is not a function` 에러
+
+차트 위젯은 Decimal 값에 Big.js의 `.toNumber()` 메서드를 호출한다.
+`list_attribute`의 `attr_type` 파라미터가 `"Decimal"`, `"Integer"`, `"Long"` 중 하나인지 확인한다.
+해당 타입으로 지정하면 synthetic 모듈이 자동으로 Big.js 호환 객체로 래핑한다.
+
+### Synthetic 데이터 차트에서 `get is not a function` 에러
+
+차트 위젯이 `staticName` 등 textTemplate 속성에서 `.get(item)` 메서드를 호출한다.
+`synthetic.text_template()`은 `.get()` 메서드를 포함하므로 정상 동작해야 한다.
+커스텀 JS 객체를 직접 전달하는 경우 `.get(item)` 메서드가 있는지 확인한다.
+
+### Chart 위젯의 shared-charts.mjs 경로 에러
+
+`Could not resolve "../../../shared/charts/esm/shared-charts.mjs"` 에러가 발생하면
+`gleam run -m mendraw/install`을 다시 실행한다. mendraw가 자동으로 공유 의존성 파일을 복사하고 import 경로를 재작성한다.
+
+### Pluggable 위젯과 Classic 위젯을 구분하는 기준
+
+mendraw는 `.mpk` 파일 내부의 구조로 자동 판별한다:
+
+- `.mjs` 파일이 포함되어 있으면 → **Pluggable** 위젯
+- `.mjs` 없이 `.js`만 포함되어 있으면 → **Classic** 위젯
 
 사용자가 별도로 지정할 필요 없다.

package/template/gleam.toml

@@ -8,8 +8,8 @@ runtime = "node"
 
 [dependencies]
 gleam_stdlib = ">= 0.44.0 and < 2.0.0"
-glendix = ">= 4.0.3 and < 5.0.0"
-mendraw = ">= 1.1.11 and < 2.0.0"
+glendix = ">= 4.0.4 and < 5.0.0"
+mendraw = ">= 1.2.1 and < 2.0.0"
 dee = ">= 1.0.0 and < 2.0.0"
 redraw = ">= 19.2.2 and < 20.0.0"
 redraw_dom = ">= 19.2.2 and < 20.0.0"