create-mendix-widget-gleam 2.0.8 → 2.0.11

package/package.json

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

package/template/docs/glendix_guide.md

@@ -322,71 +322,69 @@ react.component_el(binding.resolve(rc, "PieChart"), attrs, children)
 react.void_component_el(binding.resolve(rc, "Tooltip"), attrs)
 ```
 
-#### .mpk 위젯 컴포넌트 사용
+## .mpk 위젯 컴포넌트 사용
 
-`glendix/widget` 모듈로 `widgets/` 디렉토리의 `.mpk` 파일(Mendix 위젯 빌드 결과물)을 React 컴포넌트로 사용합니다. 다른 위젯 안에서 기존 Mendix 위젯을 렌더링할 때 유용합니다.
+`widgets/` 디렉토리에 `.mpk` 파일(Mendix 위젯 빌드 결과물)을 배치하면, 다른 위젯 안에서 기존 Mendix 위젯을 React 컴포넌트로 렌더링할 수 있다.
 
-**1단계: `.mpk` 파일 배치**
-
-프로젝트 루트에 `widgets/` 디렉토리를 만들고 `.mpk` 파일을 복사합니다:
+### 1단계: `.mpk` 파일 배치
 
 ```
-my_widget/
+프로젝트 루트/
 ├── widgets/
 │   ├── Switch.mpk
 │   └── Badge.mpk
 ├── src/
-├── gleam.toml
-└── ...
+└── gleam.toml
 ```
 
-**2단계: `gleam run -m glendix/install`** 실행 (위젯 바인딩 자동 생성)
-
-install 시 두 가지가 자동 수행됩니다:
-- `.mpk` 내부의 `.mjs`와 `.css`가 추출되고, `widget_ffi.mjs`가 생성됩니다
-- `.mpk` XML의 `<property>` 정의가 부모 위젯 XML(`src/{WidgetName}.xml`)에 `<propertyGroup caption="{위젯명}">` 으로 자동 주입됩니다 (동일 caption이 이미 있으면 건너뜀)
+### 2단계: 바인딩 생성
 
-예를 들어 `Switch.mpk`를 설치하면, 부모 위젯 XML에 다음이 자동 추가됩니다:
-
-```xml
-<propertyGroup caption="Switch">
-    <property key="booleanAttribute" type="attribute">
-        <caption>Boolean attribute</caption>
-        <description>Attribute to toggle</description>
-        <attributeTypes>
-            <attributeType name="Boolean" />
-        </attributeTypes>
-    </property>
-    <property key="action" type="action" required="false">
-        <caption>On change</caption>
-        <description>Action to be performed when the switch is toggled</description>
-    </property>
-</propertyGroup>
+```bash
+gleam run -m glendix/install
 ```
 
-**3단계: Gleam 코드에서 사용**
+실행 시 다음이 자동 처리된다:
+- `.mpk`에서 `.mjs`/`.css`를 추출하고 `widget_ffi.mjs`가 생성된다
+- `.mpk` XML의 `<property>` 정의를 파싱하여 `src/widgets/`에 바인딩 `.gleam` 파일이 자동 생성된다 (이미 존재하면 건너뜀)
+
+### 3단계: 자동 생성된 `src/widgets/*.gleam` 파일 확인
 
 ```gleam
+// src/widgets/switch.gleam (자동 생성)
 import glendix/mendix
-import glendix/widget
-import glendix/react
+import glendix/react.{type JsProps, type ReactElement}
 import glendix/react/attribute
+import glendix/widget
 
-// props에서 자동 주입된 속성을 읽어 위젯에 전달
-let boolean_attr = mendix.get_prop_required(props, "booleanAttribute")
-let action = mendix.get_prop_required(props, "action")
+/// Switch 위젯 렌더링 - props에서 속성을 읽어 위젯에 전달
+pub fn render(props: JsProps) -> ReactElement {
+  let boolean_attribute = mendix.get_prop_required(props, "booleanAttribute")
+  let action = mendix.get_prop_required(props, "action")
 
-// widgets/Switch.mpk의 Switch 컴포넌트 사용
-let switch_comp = widget.component("Switch")
-react.component_el(switch_comp, [
-  attribute.attribute("booleanAttribute", boolean_attr),
-  attribute.attribute("action", action),
-], [])
+  let comp = widget.component("Switch")
+  react.component_el(
+    comp,
+    [
+      attribute.attribute("booleanAttribute", boolean_attribute),
+      attribute.attribute("action", action),
+    ],
+    [],
+  )
+}
 ```
 
-위젯의 Props는 기존 `attribute.attribute(key, value)` 범용 함수로 전달합니다. 위젯 이름은 `.mpk` 내부 XML의 `<name>` 태그 값(PascalCase)을, property key는 `.mpk` XML의 원본 key를 그대로 사용합니다.
+required/optional 속성이 자동 구분되며, 필요에 따라 생성된 파일을 자유롭게 수정할 수 있다.
+
+### 4단계: 위젯에서 사용
+
+```gleam
+import widgets/switch
+
+// 컴포넌트 내부에서
+switch.render(props)
+```
 
-> `binding` 모듈과 달리 `widget` 모듈은 1 mpk = 1 컴포넌트이므로 `module` + `resolve` 2단계 없이 `component("Name")` 한 번에 가져옵니다.
+위젯 이름은 `.mpk` 내부 XML의 `<name>` 값을, property key는 `.mpk` XML의 원본 key를 그대로 사용한다.
 
 ### 3.2 HTML 속성
 
@@ -1710,6 +1708,8 @@ case formatter.parse(fmt, "123.45") {
 
 Studio Pro의 editorConfig에서 속성을 조건부로 숨기거나, 그룹을 탭으로 변환하는 등의 작업을 순수 Gleam으로 작성할 수 있습니다. `@mendix/pluggable-widgets-tools`의 헬퍼 함수를 래핑합니다.
 
+> **Jint 호환성**: Studio Pro는 editorConfig를 **Jint**(.NET JavaScript 엔진)로 실행합니다. Jint는 Gleam 컴파일러가 생성하는 `List` 런타임(WeakMap, Symbol.iterator, class inheritance)을 지원하지 않으므로, 이 모듈의 모든 함수는 `List` 타입을 사용하지 않습니다. 여러 키를 전달할 때는 **콤마 구분 String**을 사용합니다.
+
 #### Properties 타입
 
 `Properties`는 Studio Pro가 `getProperties`에 전달하는 `PropertyGroup[]` 배열의 opaque 래퍼입니다. 모든 함수가 `Properties`를 반환하므로 파이프라인 체이닝이 가능합니다.
@@ -1722,14 +1722,14 @@ import glendix/editor_config.{type Properties}
 // 단일 속성 숨기기
 let props = editor_config.hide_property(default_properties, "barWidth")
 
-// 여러 속성 한 번에 숨기기
-let props = editor_config.hide_properties(default_properties, ["barWidth", "barColor"])
+// 여러 속성 한 번에 숨기기 (콤마 구분 String)
+let props = editor_config.hide_properties(default_properties, "barWidth,barColor")
 
 // 중첩 속성 숨기기 (배열 타입 속성의 특정 인덱스 내부)
 let props = editor_config.hide_nested_property(default_properties, "columns", 0, "width")
 
-// 여러 중첩 속성 한 번에 숨기기
-let props = editor_config.hide_nested_properties(default_properties, "columns", 0, ["width", "alignment"])
+// 여러 중첩 속성 한 번에 숨기기 (콤마 구분 String)
+let props = editor_config.hide_nested_properties(default_properties, "columns", 0, "width,alignment")
 ```
 
 #### 탭 변환 / 속성 순서 변경
@@ -1746,11 +1746,17 @@ let props = editor_config.move_property(default_properties, 0, 2)
 
 사용자의 `src/editor_config.gleam`에서 `getProperties` 로직을 작성합니다. 이 파일이 존재하면 `run_with_bridge` 실행 시 editorConfig 브릿지 JS가 자동 생성됩니다.
 
+> **주의**: editorConfig 코드에서는 Gleam `List`를 사용하지 마세요. `["a", "b"]` 같은 리스트 리터럴은 Gleam List 런타임 클래스를 번들에 포함시켜 Jint에서 크래시를 일으킵니다. 여러 키를 조합할 때는 `const`와 String 연결(`<>`)을 사용하세요.
+
 ```gleam
 import glendix/editor_config.{type Properties}
 import glendix/mendix
 import glendix/react.{type JsProps}
 
+const bar_keys = "barWidth,barColor"
+
+const line_keys = "lineStyle,lineCurve"
+
 pub fn get_properties(
   values: JsProps,
   default_properties: Properties,
@@ -1761,10 +1767,10 @@ pub fn get_properties(
   let props = case chart_type {
     "line" ->
       default_properties
-      |> editor_config.hide_properties(["barWidth", "barColor"])
+      |> editor_config.hide_properties(bar_keys)
     "bar" ->
       default_properties
-      |> editor_config.hide_properties(["lineStyle", "lineCurve"])
+      |> editor_config.hide_properties(line_keys)
     _ -> default_properties
   }
 
@@ -1780,9 +1786,9 @@ pub fn get_properties(
 | 함수 | 설명 |
 |------|------|
 | `hide_property(properties, key)` | 단일 속성 숨기기 |
-| `hide_properties(properties, keys)` | 여러 속성 한 번에 숨기기 |
+| `hide_properties(properties, keys)` | 여러 속성 숨기기 (콤마 구분 String) |
 | `hide_nested_property(properties, key, index, nested_key)` | 중첩 속성 숨기기 |
-| `hide_nested_properties(properties, key, index, nested_keys)` | 여러 중첩 속성 숨기기 |
+| `hide_nested_properties(properties, key, index, nested_keys)` | 여러 중첩 속성 숨기기 (콤마 구분 String) |
 | `transform_groups_into_tabs(properties)` | 그룹 → 탭 변환 |
 | `move_property(properties, from_index, to_index)` | 속성 순서 변경 |
 

package/template/gleam.toml

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