create-mendix-widget-gleam 1.0.8 → 1.1.1

package/README.md

@@ -27,7 +27,7 @@ my-widget/
     editor_preview.gleam       # Studio Pro 디자인 뷰 미리보기
     components/
       hello_world.gleam      # Hello World 공유 컴포넌트
-  gleam.toml                   # Gleam 프로젝트 설정 (glendix >= 1.1.0 의존성 포함)
+  gleam.toml                   # Gleam 프로젝트 설정 (glendix >= 1.2.0 의존성 포함)
   CLAUDE.md                    # AI 어시스턴트용 프로젝트 컨텍스트
 ```
 

package/package.json

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

package/src/index.mjs

@@ -176,7 +176,7 @@ Gleam 언어로 Mendix Pluggable Widget을 개발하여 "Hello World"를 화면
 - **Gleam** → JavaScript 컴파일 (target: javascript)
 - **[glendix](https://hexdocs.pm/glendix/)** — React + Mendix Pluggable Widget API의 Gleam FFI 바인딩 (Hex 패키지)
 - **Mendix Pluggable Widget** (React 19)
-- **Package Manager**: ${pm} (npm 의존성은 \`gleam run -m glendix/install\`로 설치)
+- **Package Manager**: ${pm} (기본 npm 의존성은 \`gleam run -m glendix/install\`로 설치, \`bindings.json\` 외부 React 패키지는 수동 설치 필요)
 - **Build**: \`@mendix/pluggable-widgets-tools\` (Rollup 기반)
 
 ## Architecture
@@ -215,7 +215,7 @@ React/Mendix FFI 바인딩은 이 프로젝트에 포함되지 않으며, [glend
 ## Commands
 
 \`\`\`bash
-gleam run -m glendix/install   # 의존성 설치
+gleam run -m glendix/install   # 의존성 설치 + 바인딩 코드 생성 (외부 React 패키지는 사전에 수동 설치 필요)
 gleam run -m glendix/build     # 위젯 프로덕션 빌드 (.mpk 생성)
 gleam run -m glendix/dev       # 개발 서버 (HMR, port 3000)
 gleam run -m glendix/start     # Mendix 테스트 프로젝트와 연동 개발
@@ -245,6 +245,7 @@ React:
 - \`glendix/react/hook\` — React Hooks (useState, useEffect 등)
 - \`glendix/react/event\` — 이벤트 타입 + 값 추출
 - \`glendix/react/html\` — HTML 태그 편의 함수
+- \`glendix/binding\` — 외부 React 컴포넌트 바인딩
 
 Mendix:
 - \`glendix/mendix\` — \`ValueStatus\`, \`ObjectItem\`, Props 접근자

package/template/docs/glendix_guide.md

@@ -45,9 +45,11 @@ glendix = { path = "../glendix" }
 ```
 
 ```bash
-npm install
+gleam run -m glendix/install
 ```
 
+> `glendix/install`은 패키지 매니저를 자동 감지하여 의존성을 설치하고, `bindings.json`이 있으면 외부 React 컴포넌트 바인딩도 자동 생성합니다.
+
 #### 4) 빌드 확인
 
 ```bash
@@ -198,11 +200,87 @@ react.none()  // React null 반환
 
 #### 외부 React 컴포넌트 사용
 
+`glendix/binding` 모듈로 외부 React 라이브러리를 **`.mjs` 없이** 사용합니다.
+
+**1단계: `bindings.json` 작성** (프로젝트 루트)
+
+```json
+{
+  "recharts": {
+    "components": ["PieChart", "Pie", "Cell", "LineChart", "Line",
+                   "XAxis", "YAxis", "CartesianGrid", "Tooltip", "Legend",
+                   "ResponsiveContainer"]
+  }
+}
+```
+
+**2단계: 패키지 설치** — `bindings.json`에 등록한 패키지는 위젯 프로젝트의 `node_modules`에 설치되어 있어야 합니다. 생성된 `binding_ffi.mjs`가 해당 패키지를 직접 import하므로, Rollup이 번들링할 때 resolve할 수 있어야 합니다.
+
+```bash
+# 사용 중인 패키지 매니저에 맞게 설치
+npm install recharts
+# 또는
+pnpm add recharts
+# 또는
+yarn add recharts
+# 또는
+bun add recharts
+```
+
+**3단계: `gleam run -m glendix/install`** 실행 (바인딩 자동 생성)
+
+**4단계: 순수 Gleam 래퍼 모듈 작성** (편의용, 선택사항)
+
 ```gleam
-// 다른 React 컴포넌트를 합성할 때
-react.component(my_component, prop.new() |> prop.string("title", "Hello"), [
-  // children
-])
+// src/chart/recharts.gleam — 순수 Gleam, FFI 없음!
+import glendix/binding
+import glendix/react.{type Component}
+
+fn m() { binding.module("recharts") }
+
+pub fn pie_chart() -> Component       { binding.resolve(m(), "PieChart") }
+pub fn pie() -> Component             { binding.resolve(m(), "Pie") }
+pub fn cell() -> Component            { binding.resolve(m(), "Cell") }
+pub fn tooltip() -> Component         { binding.resolve(m(), "Tooltip") }
+pub fn legend() -> Component          { binding.resolve(m(), "Legend") }
+pub fn responsive_container() -> Component {
+  binding.resolve(m(), "ResponsiveContainer")
+}
+```
+
+**5단계: 위젯에서 사용**
+
+```gleam
+import chart/recharts
+import glendix/react
+import glendix/react/prop
+
+pub fn my_pie_chart(data) -> react.ReactElement {
+  react.component(recharts.responsive_container(),
+    prop.new() |> prop.int("width", 400) |> prop.int("height", 300),
+    [
+      react.component(recharts.pie_chart(), prop.new(), [
+        react.component(recharts.pie(),
+          prop.new()
+          |> prop.any("data", data)
+          |> prop.string("dataKey", "value"),
+          [],
+        ),
+        react.component(recharts.tooltip(), prop.new(), []),
+        react.component(recharts.legend(), prop.new(), []),
+      ]),
+    ],
+  )
+}
+```
+
+래퍼 모듈 없이 직접 사용하는 것도 가능합니다:
+
+```gleam
+import glendix/binding
+
+let rc = binding.module("recharts")
+react.component(binding.resolve(rc, "PieChart"), props, children)
 ```
 
 ### 3.2 Props 빌더
@@ -1305,8 +1383,8 @@ pub fn dashboard(props) -> ReactElement {
 | 문제 | 원인 | 해결 |
 |---|---|---|
 | `gleam build` 실패: glendix를 찾을 수 없음 | `gleam.toml`의 경로가 잘못됨 | `path = "../glendix"` 경로 확인 |
-| `react is not defined` | peer dependency 미설치 | `npm install react@^19.0.0` |
-| `Big is not a constructor` | big.js 미설치 | `npm install big.js@^6.0.0` |
+| `react is not defined` | peer dependency 미설치 | `gleam run -m glendix/install` |
+| `Big is not a constructor` | big.js 미설치 | `gleam run -m glendix/install` |
 
 ### 런타임 에러
 
@@ -1315,6 +1393,10 @@ pub fn dashboard(props) -> ReactElement {
 | `Cannot read property of undefined` | 존재하지 않는 prop 접근 | `get_prop` (Option) 대신 `get_prop_required` 사용 시 prop 이름 확인 |
 | `set_value` 호출 시 에러 | read_only 상태에서 값 설정 | `ev.is_editable(attr)` 확인 후 설정 |
 | Hook 순서 에러 | 조건부로 Hook 호출 | Hook은 항상 동일한 순서로 호출해야 함 (React Rules of Hooks) |
+| `바인딩이 생성되지 않았습니다` | `binding_ffi.mjs`가 스텁 상태 | `gleam run -m glendix/install` 실행 |
+| `could not be resolved – treating it as an external dependency` | `bindings.json`에 등록한 패키지가 `node_modules`에 없음 | `npm install <패키지명>` 등으로 설치 후 재빌드 |
+| `바인딩에 등록되지 않은 모듈` | `bindings.json`에 해당 패키지 미등록 | `bindings.json`에 패키지와 컴포넌트 추가 후 재설치 |
+| `모듈에 없는 컴포넌트` | `bindings.json`의 `components`에 해당 컴포넌트 미등록 | `components` 배열에 추가 후 재설치 |
 
 ### 일반적인 실수
 
@@ -1361,5 +1443,28 @@ list.map(items, fn(item) {
 let month = date.month(my_date)  // 1~12 (Gleam 기준, 변환 불필요)
 ```
 
+**4. 외부 React 컴포넌트용 `.mjs` 파일을 직접 작성하지 마세요:**
+
+```gleam
+// 잘못된 방법 — 수동 FFI 작성
+// recharts_ffi.mjs를 만들고 @external로 연결하는 것
+
+// 올바른 방법 — bindings.json + glendix/binding 사용
+import glendix/binding
+let rc = binding.module("recharts")
+let pie = binding.resolve(rc, "PieChart")
+react.component(pie, props, children)
+```
+
+**5. `binding.resolve()`에서 컴포넌트 이름을 snake_case로 바꾸지 마세요:**
+
+```gleam
+// 잘못된 예
+binding.resolve(m(), "pie_chart")
+
+// 올바른 예 — JavaScript 원본 이름(PascalCase) 그대로 사용
+binding.resolve(m(), "PieChart")
+```
+
 ---
 

package/template/gleam.toml

@@ -8,4 +8,4 @@ runtime = "node"
 
 [dependencies]
 gleam_stdlib = ">= 0.44.0 and < 2.0.0"
-glendix = ">= 1.1.1 and < 2.0.0"
+glendix = ">= 1.2.0 and < 2.0.0"

package/template/manifest.toml

@@ -1,11 +0,0 @@
-# This file was generated by Gleam
-# You typically do not need to edit this file
-
-packages = [
-  { name = "gleam_stdlib", version = "0.70.0", build_tools = ["gleam"], requirements = [], otp_app = "gleam_stdlib", source = "hex", outer_checksum = "86949BF5D1F0E4AC0AB5B06F235D8A5CC11A2DFC33BF22F752156ED61CA7D0FF" },
-  { name = "glendix", version = "1.0.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "glendix", source = "hex", outer_checksum = "9E1B78EEABCC0193F028BB271C3E60565C587E5E901FE553509ECF38D981B58A" },
-]
-
-[requirements]
-gleam_stdlib = { version = ">= 0.44.0 and < 2.0.0" }
-glendix = { version = ">= 1.0.0 and < 2.0.0" }