sd-render 1.2.4 → 1.2.6

package/field-docs.html

@@ -142,9 +142,10 @@ td code { background: #313244; padding: 1px 6px; border-radius: 3px; font-size:
     <a href="#icon-input">Icon List</a>
   </div>
   <div class="group">
-    <div class="group-title">Display UI (25)</div>
+    <div class="group-title">Display UI (26)</div>
     <a href="#text-ui">Static Text</a>
     <a href="#html-ui">Content</a>
+    <a href="#vue-ui">Components</a>
     <a href="#link-ui">Link Text</a>
     <a href="#divider-ui">Divider</a>
     <a href="#progress-ui">Progress Bar</a>
@@ -186,10 +187,15 @@ td code { background: #313244; padding: 1px 6px; border-radius: 3px; font-size:
     <a href="#sub-form">Sub Form</a>
     <a href="#object-group">Object Group</a>
   </div>
+  <div class="group">
+    <div class="group-title">Special Widget (1)</div>
+    <a href="#sd-custom-content">SD Custom Content</a>
+  </div>
   <div class="group">
     <div class="group-title">Functions</div>
     <a href="#field-functions">Field Functions</a>
     <a href="#form-functions">Form Functions</a>
+    <a href="#popup-form-guide">Popup Form Guide</a>
     <a href="#api-functions">API Functions</a>
     <a href="#variables">Variables</a>
   </div>
@@ -8679,6 +8685,145 @@ td code { background: #313244; padding: 1px 6px; border-radius: 3px; font-size:
       </table>
     </div>
   </div>
+  <div class="card" id="vue-ui">
+    <div class="card-head">
+      <h3>Components</h3>
+      <div class="tags">
+
+
+
+      </div>
+    </div>
+    <div class="tab-bar">
+      <button class="tab-btn active" onclick="showTab(this,0)">COMMON <span class="tab-count">5</span></button>
+      <button class="tab-btn" onclick="showTab(this,1)">ADVANCED <span class="tab-count">0</span></button>
+      <button class="tab-btn" onclick="showTab(this,2)">EVENTS <span class="tab-count">2</span></button>
+    </div>
+    <div class="tab-panel active" data-idx="0">
+      <table>
+        <tr><th>Option</th><th>Label</th><th>Default</th><th>Description</th></tr>
+        <tr>
+    <td class="opt-key">name</td>
+    <td class="opt-label">Variable Name</td>
+    <td><span class="v-empty">''</span></td>
+    <td class="opt-hint"></td>
+  </tr>
+        <tr>
+    <td class="opt-key">columnSpan</td>
+    <td class="opt-label">Column Span</td>
+    <td><span class="v-num">4</span></td>
+    <td class="opt-hint"></td>
+  </tr>
+        <tr>
+    <td class="opt-key">hidden</td>
+    <td class="opt-label">Hide</td>
+    <td><span class="v-bool">false</span></td>
+    <td class="opt-hint"></td>
+  </tr>
+        <tr>
+    <td class="opt-key">content</td>
+    <td class="opt-label">Template</td>
+    <td><span class="v-str">'&lt;el-alert title=&quot;Vue UI&quot; type=&quot;info&quot; :closable=&quot;false&quot; /&gt;'</span></td>
+    <td class="opt-hint">Vue Template (el-*, {{data}}, v-if/v-for)</td>
+  </tr>
+        <tr>
+    <td class="opt-key">customClass</td>
+    <td class="opt-label">Custom Class</td>
+    <td><span class="v-empty">''</span></td>
+    <td class="opt-hint"></td>
+  </tr>
+      </table>
+    </div>
+    <div class="tab-panel" data-idx="1">
+      <table>
+        <tr><th>Option</th><th>Label</th><th>Default</th><th>Description</th></tr>
+      </table>
+    </div>
+    <div class="tab-panel" data-idx="2">
+      <table>
+        <tr><th>Event</th><th>Label</th><th>Parameters</th><th>Description</th></tr>
+        <tr>
+    <td class="opt-key">onCreated</td>
+    <td class="opt-label">onCreated</td>
+    <td class="opt-params"></td>
+    <td class="opt-hint"></td>
+  </tr>
+        <tr>
+    <td class="opt-key">onMounted</td>
+    <td class="opt-label">onMounted</td>
+    <td class="opt-params"></td>
+    <td class="opt-hint"></td>
+  </tr>
+      </table>
+    </div>
+
+    <div style="padding: 12px 14px; border-top: 1px solid #232336;">
+      <div class="example-label" style="font-size: 12px; color: #89b4fa; margin-bottom: 4px;">📘 ตัวอย่างการใช้งาน — vueState (zone เขียนสคริปประจำ widget)</div>
+      <div style="color: #585b70; font-size: 11px; margin-bottom: 12px;">
+        template เข้าถึง 3 scope: <code>params</code> (context/system) &gt; <code>vueState</code> (zone ของ widget) &gt; <code>data</code> (form model).
+        เก็บ data/function/instance ใน <code>vueState</code> แล้ว push/assign ได้ — UI re-render เอง · ไม่ถูก submit
+      </div>
+
+      <div class="fn-item">
+        <div class="fn-head">
+          <span class="fn-name">1. el-tree + ปุ่มเพิ่ม node</span>
+          <span class="fn-returns">reactive list</span>
+        </div>
+        <div class="fn-desc">ใส่ default ใน <code>onCreated</code> (พร้อมก่อน render) · field อื่นแก้ผ่าน <code>refField</code></div>
+        <div class="fn-example">
+          <div class="example-label">vue_ui · content (template)</div>
+          <pre><code>&lt;el-tree style="max-width: 600px" :data="items" /&gt;</code></pre>
+          <div class="example-label" style="margin-top: 8px;">vue_ui · onCreated</div>
+          <pre><code>this.vueState.items = [
+  { label: 'Level one 1', children: [{ label: 'Level two 1-1', children: [] }] }
+]</code></pre>
+          <div class="example-label" style="margin-top: 8px;">button · onClick (ชื่อ vue_ui ต้องตรง options.name)</div>
+          <pre><code>this.refField('vue_ui').vueState.items.push({ label: 'Level one 2', children: [] })
+// → reactive, el-tree อัปเดตทันที</code></pre>
+        </div>
+      </div>
+
+      <div class="fn-item">
+        <div class="fn-head">
+          <span class="fn-name">2. เก็บ function ในโซน</span>
+          <span class="fn-returns">arrow fn</span>
+        </div>
+        <div class="fn-desc">เก็บ method ใน <code>vueState</code> แล้วเรียกจาก <code>@click</code> ได้ตรงๆ (ใช้ arrow → closure อ้าง <code>s</code>)</div>
+        <div class="fn-example">
+          <div class="example-label">vue_ui · onCreated</div>
+          <pre><code>const s = this.vueState
+s.count = 0
+s.add = (label) =&gt; { s.items.push({ label }); s.count++ }</code></pre>
+          <div class="example-label" style="margin-top: 8px;">vue_ui · content</div>
+          <pre><code>&lt;el-button @click="add('node ' + (count + 1))"&gt;เพิ่ม ({{ count }})&lt;/el-button&gt;
+&lt;el-tree :data="items" /&gt;</code></pre>
+        </div>
+      </div>
+
+      <div class="fn-item">
+        <div class="fn-head">
+          <span class="fn-name">⚠️ ข้อควรระวัง</span>
+          <span class="fn-returns" style="background: #3a2f1e; color: #fab387;">กันพลาด</span>
+        </div>
+        <div class="fn-example">
+          <pre><code>// ❌ key ห้ามขึ้นต้น _ หรือ $  → template มองไม่เห็น
+s._tmp = 1            // ใช้ s.tmp แทน
+
+// ❌ ชื่ออย่าชนกับ params (params ชนะ → ค่า zone โดนบัง)
+s.userInfo = {...}    // ชนระบบ — ใช้ชื่อเฉพาะตัว เช่น s.treeData
+
+// ❌ instance ต้อง markRaw (กัน deep reactive wrap จนเพี้ยน/ช้า)
+s.chart = markRaw(echarts.init(el))
+
+// ❌ vueState ไม่ persist — รีโหลดฟอร์มหาย
+//    ถ้าต้องเก็บค่า sync เข้า data.xxx (form model) หรือยิง API
+
+// ❌ ส่ง vueState เป็น primitive จะขึ้น error box แจ้ง designer
+this.vueState = 'x'   // ต้องเป็น object เสมอ — ใช้ s.key = ... แทน</code></pre>
+        </div>
+      </div>
+    </div>
+  </div>
   <div class="card" id="link-ui">
     <div class="card-head">
       <h3>Link Text</h3>
@@ -10454,7 +10599,7 @@ td code { background: #313244; padding: 1px 6px; border-radius: 3px; font-size:
     </div>
     <div class="tab-bar">
       <button class="tab-btn active" onclick="showTab(this,0)">COMMON <span class="tab-count">23</span></button>
-      <button class="tab-btn" onclick="showTab(this,1)">ADVANCED <span class="tab-count">13</span></button>
+      <button class="tab-btn" onclick="showTab(this,1)">ADVANCED <span class="tab-count">18</span></button>
       <button class="tab-btn" onclick="showTab(this,2)">EVENTS <span class="tab-count">8</span></button>
     </div>
     <div class="tab-panel active" data-idx="0">
@@ -10604,6 +10749,36 @@ td code { background: #313244; padding: 1px 6px; border-radius: 3px; font-size:
       <table>
         <tr><th>Option</th><th>Label</th><th>Default</th><th>Description</th></tr>
         <tr>
+    <td class="opt-key">customContentEnable</td>
+    <td class="opt-label">Custom Content</td>
+    <td><span class="v-bool">false</span></td>
+    <td class="opt-hint">render ผ่าน SDCustomContent แทน Display Fields</td>
+  </tr>
+        <tr>
+    <td class="opt-key">customContent</td>
+    <td class="opt-label">Content Temp</td>
+    <td><span class="v-empty">''</span></td>
+    <td class="opt-hint">Vue Template — {{field}}, fmt('field'), can.* / actions.*</td>
+  </tr>
+        <tr>
+    <td class="opt-key">autoActionFooter</td>
+    <td class="opt-label">Auto Action Footer</td>
+    <td><span class="v-bool">true</span></td>
+    <td class="opt-hint">widget render ปุ่ม action footer ให้ · ปิด = เขียนเองใน Content Temp ผ่าน can/actions</td>
+  </tr>
+        <tr>
+    <td class="opt-key">metaByField</td>
+    <td class="opt-label">Footer By Field</td>
+    <td><span class="v-empty">''</span></td>
+    <td class="opt-hint"></td>
+  </tr>
+        <tr>
+    <td class="opt-key">metaTimeField</td>
+    <td class="opt-label">Footer Time Field</td>
+    <td><span class="v-empty">''</span></td>
+    <td class="opt-hint"></td>
+  </tr>
+        <tr>
     <td class="opt-key">enableWs</td>
     <td class="opt-label">WebSocket Enable</td>
     <td><span class="v-bool">true</span></td>
@@ -13673,6 +13848,226 @@ td code { background: #313244; padding: 1px 6px; border-radius: 3px; font-size:
   </div>
 </section>
 
+<section class="section" id="sec-special-widget">
+  <h2>Special Widget <span class="count">advanced / dev only</span></h2>
+
+  <div class="card" id="sd-custom-content">
+    <div class="card-head">
+      <h3>SD Custom Content</h3>
+      <div class="tags">
+        <span class="tag tag-type">DisplayUi</span>
+        <span class="tag tag-pro">pro</span>
+        <span class="tag tag-pro">dev only</span>
+      </div>
+    </div>
+    <div class="fn-desc">
+      Render <b>HTML / Vue template string</b> อย่างปลอดภัย — รองรับ HTML tag ปกติ, component ของ Element Plus (<code>el-*</code>) + widget,
+      directive (<code>v-if</code> / <code>v-for</code> / <code>v-show</code> / <code>:</code> / <code>@</code>) และ interpolation <code>{{ varname }}</code> จาก prop <code>data</code> / <code>params</code>.
+      <br>เทคนิค: Vue runtime compiler (lazy import) + DOMPurify sanitize + cache render function.
+    </div>
+    <div class="tab-bar">
+      <button class="tab-btn active" onclick="showTab(this,0)">PROPS <span class="tab-count">5</span></button>
+      <button class="tab-btn" onclick="showTab(this,1)">HELPERS <span class="tab-count">4</span></button>
+      <button class="tab-btn" onclick="showTab(this,2)">EVENTS <span class="tab-count">1</span></button>
+    </div>
+    <div class="tab-panel active" data-idx="0">
+      <table>
+        <tr><th>Prop</th><th>Type</th><th>Default</th><th>Description</th></tr>
+        <tr>
+          <td class="opt-key">content</td>
+          <td class="param-type">string</td>
+          <td><span class="v-empty">''</span></td>
+          <td class="opt-hint">HTML / Vue template string ที่จะ render</td>
+        </tr>
+        <tr>
+          <td class="opt-key">data</td>
+          <td class="param-type">object</td>
+          <td><span class="v-str">{}</span></td>
+          <td class="opt-hint">ตัวแปรสำหรับ binding — {{ name }}, v-for="i in list", v-if="ok"</td>
+        </tr>
+        <tr>
+          <td class="opt-key">params</td>
+          <td class="param-type">object</td>
+          <td><span class="v-str">{}</span></td>
+          <td class="opt-hint">context เพิ่มเติม (override data เมื่อ key ชนกัน) เช่น params จากฟอร์ม</td>
+        </tr>
+        <tr>
+          <td class="opt-key">components</td>
+          <td class="param-type">object</td>
+          <td><span class="v-str">{}</span></td>
+          <td class="opt-hint">widget เพิ่มเติมที่ไม่ได้ register global (el-* ไม่ต้องส่ง)</td>
+        </tr>
+        <tr>
+          <td class="opt-key">sanitize</td>
+          <td class="param-type">boolean</td>
+          <td><span class="v-bool">true</span></td>
+          <td class="opt-hint">เปิด DOMPurify sanitize (กรอง &lt;script&gt;, onerror=, javascript:)</td>
+        </tr>
+      </table>
+    </div>
+    <div class="tab-panel" data-idx="1">
+      <table>
+        <tr><th>Method</th><th>Returns</th><th>Parameter</th><th>Description</th></tr>
+        <tr>
+          <td class="opt-key">getRef</td>
+          <td class="param-type">instance | element</td>
+          <td class="opt-params">name: string</td>
+          <td class="opt-hint">เข้าถึงสิ่งที่เขียน ref="name" ใน template (widget instance หรือ DOM element)</td>
+        </tr>
+        <tr>
+          <td class="opt-key">getEl</td>
+          <td class="param-type">HTMLElement</td>
+          <td class="opt-params">name: string</td>
+          <td class="opt-hint">DOM element ของ ref — component คืน $el, tag ปกติคืน element</td>
+        </tr>
+        <tr>
+          <td class="opt-key">getRefs</td>
+          <td class="param-type">object</td>
+          <td class="opt-params"></td>
+          <td class="opt-hint">ref ทั้งหมดเป็น object { name: ref }</td>
+        </tr>
+        <tr>
+          <td class="opt-key">getInner</td>
+          <td class="param-type">instance</td>
+          <td class="opt-params"></td>
+          <td class="opt-hint">inner component instance (low-level เผื่อต้องเข้าถึงลึก)</td>
+        </tr>
+      </table>
+    </div>
+    <div class="tab-panel" data-idx="2">
+      <table>
+        <tr><th>Event</th><th>Parameters</th><th>Description</th></tr>
+        <tr>
+          <td class="opt-key">rendered</td>
+          <td class="opt-params">refs: object</td>
+          <td class="opt-hint">emit หลัง render เสร็จ + DOM mount แล้ว (ref พร้อมใช้) ส่ง refs มาด้วย</td>
+        </tr>
+      </table>
+    </div>
+  </div>
+
+  <div class="fn-list">
+
+    <div class="fn-item">
+      <div class="fn-head">
+        <span class="fn-name">1. การใช้งานพื้นฐาน</span>
+        <span class="fn-returns">interpolation + el- + v-if</span>
+      </div>
+      <div class="fn-desc">ส่ง template เข้า <code>content</code> และตัวแปรเข้า <code>data</code> — {{ }} แสดงค่าแบบ escape เป็น text (ปลอดภัย)</div>
+      <div class="fn-example">
+        <div class="example-label">Host component</div>
+        <pre><code>&lt;SDCustomContent :content="tpl" :data="vars" /&gt;
+
+// ใน data() ของ host
+tpl: `&lt;div&gt;
+  &lt;h3&gt;สวัสดี {{ user.name }}&lt;/h3&gt;
+  &lt;el-tag :type="user.vip ? 'success' : 'info'"&gt;
+    {{ user.vip ? 'VIP' : 'ทั่วไป' }}
+  &lt;/el-tag&gt;
+  &lt;p v-if="user.vip"&gt;สมาชิก VIP&lt;/p&gt;
+&lt;/div&gt;`,
+vars: { user: { name: 'พี่', vip: true } }</code></pre>
+      </div>
+    </div>
+
+    <div class="fn-item">
+      <div class="fn-head">
+        <span class="fn-name">2. v-for แสดง array</span>
+        <span class="fn-returns">el-table / list</span>
+      </div>
+      <div class="fn-desc">วน array จาก data ด้วย v-for — เปลี่ยน array แล้ว re-render อัตโนมัติ</div>
+      <div class="fn-example">
+        <div class="example-label">Template</div>
+        <pre><code>&lt;el-table :data="rows" size="small" border&gt;
+  &lt;el-table-column prop="name" label="สินค้า" /&gt;
+  &lt;el-table-column prop="price" label="ราคา" width="120" /&gt;
+&lt;/el-table&gt;
+
+// data
+rows: [
+  { name: 'ปูนซีเมนต์', price: 175 },
+  { name: 'เหล็กเส้น', price: 240 },
+]</code></pre>
+      </div>
+    </div>
+
+    <div class="fn-item">
+      <div class="fn-head">
+        <span class="fn-name">3. Event handler (@click)</span>
+        <span class="fn-returns">method ใน data</span>
+      </div>
+      <div class="fn-desc">ใส่ <b>ฟังก์ชัน</b>ใน data แล้ว template เรียกผ่าน @click / @change ได้เลย</div>
+      <div class="fn-example">
+        <div class="example-label">Template + data</div>
+        <pre><code>&lt;el-button @click="greet(user.name)"&gt;ทักทาย&lt;/el-button&gt;
+&lt;el-button @click="addItem"&gt;เพิ่ม ({{ list.length }})&lt;/el-button&gt;
+
+// data
+{
+  user: { name: 'พี่' },
+  list: myReactiveList,
+  greet: (name) =&gt; ElMessage.success('สวัสดี ' + name),
+  addItem: () =&gt; myReactiveList.push('item'),
+}
+
+// ⚠️ inline mutation ไม่ persist: @click="counter++" เขียนกลับ data ไม่ได้
+//    ต้องผ่าน method เช่น @click="inc()" โดย inc: () =&gt; data.counter++</code></pre>
+      </div>
+    </div>
+
+    <div class="fn-item">
+      <div class="fn-head">
+        <span class="fn-name">4. Ref helper</span>
+        <span class="fn-returns">เข้าถึง widget ภายใน</span>
+      </div>
+      <div class="fn-desc">เขียน ref="name" ใน template แล้ว host เข้าถึงผ่าน getRef — ใช้ได้หลัง render เสร็จ (ดัก @rendered หรือรอ $nextTick)</div>
+      <div class="fn-example">
+        <div class="example-label">Host</div>
+        <pre><code>&lt;SDCustomContent ref="cc" :content="tpl" @rendered="onReady" /&gt;
+
+// template มี: &lt;el-input ref="nameInput" /&gt;
+
+methods: {
+  onReady(refs) {
+    // refs = { nameInput: ElInputInstance }
+  },
+  focusInput() {
+    this.$refs.cc.getRef('nameInput')?.focus()
+    // getEl('nameInput') → DOM element
+    // getRefs()          → ref ทั้งหมด
+  }
+}</code></pre>
+      </div>
+    </div>
+
+    <div class="fn-item">
+      <div class="fn-head">
+        <span class="fn-name">⚠️ Security</span>
+        <span class="fn-returns">ต้องอ่าน</span>
+      </div>
+      <div class="fn-desc">
+        template = รัน JavaScript จริง (compile ด้วย runtime compiler) — expression เข้าถึง global ได้ (window, document, fetch)
+        DOMPurify กรองได้แค่โครง HTML <b>ไม่ได้</b> sandbox JS
+      </div>
+      <div class="fn-example">
+        <div class="example-label">กฎความปลอดภัย</div>
+        <pre><code>// ✅ ปลอดภัย: content มาจาก dev / form schema เท่านั้น
+//    (designer เขียน JS ได้อยู่แล้วผ่าน field events — trust เท่าเดิม)
+// ✅ ปลอดภัย: data แสดงผ่าน {{ }} (Vue escape เป็น text เสมอ)
+
+// ❌ ห้าม: เอา content จาก user input / URL / external API
+//          → รัน JS ได้เต็มที่ (อ่าน cookie, ส่งข้อมูลออก)
+// ❌ ระวัง: v-html="untrustedData" → XSS (ใช้ {{ }} แทนถ้าได้)
+
+// กฎจำง่าย:
+//   1) content รับจาก dev/schema เท่านั้น
+//   2) ที่เก็บ content ต้อง write ได้เฉพาะ dev (permission guard)</code></pre>
+      </div>
+    </div>
+
+  </div>
+</section>
+
 <section class="section" id="field-functions">
   <h2>Field Functions <span class="count">this.*</span></h2>
   <div class="fn-list">
@@ -14640,25 +15035,27 @@ const total = rows.reduce((s, r) =&gt; s + r.amount, 0)</code></pre>
         </tr>
         <tr>
           <td class="opt-key">options</td>
-          <td class="param-type">{width?,fullscreen?,readonly?}</td>
+          <td class="param-type">object</td>
           <td class="param-opt"><span class="opt-badge">optional</span></td>
-          <td class="opt-hint">Dialog options</td>
+          <td class="opt-hint">Popup options: params, backdrop, readonly, annotated, callbacks &mdash; see <a href="#popup-form-guide" style="color:#cba6f7">Popup Form Guide</a></td>
         </tr>
       </table>
       
       <div class="fn-example">
         <div class="example-label">Example</div>
         <pre><code>// Open new record
-this.getFormRef().openForm('form_abc123')
+this.getFormRef().openForm('6a2f90e949fcdf666f694b60')
 
-// Open existing record
-this.getFormRef().openForm('form_abc123', dataId)
+// Open existing record (edit mode)
+this.getFormRef().openForm('6a2f90e949fcdf666f694b60', dataId)
 
 // Open with pre-filled data
-this.getFormRef().openForm('form_abc123', null, null, { dept: 'IT' })
+this.getFormRef().openForm('6a2f90e949fcdf666f694b60', null, null, { dept: 'IT' })
 
-// Read-only fullscreen
-this.getFormRef().openForm('form_abc123', dataId, null, null, { readonly: true, fullscreen: true })</code></pre>
+// Read-only (popup width comes from the target form's popup_size, not options)
+this.getFormRef().openForm('6a2f90e949fcdf666f694b60', dataId, null, null, { readonly: true })
+
+// → Full options &amp; step-by-step examples: see "Popup Form Guide" below</code></pre>
       </div>
     </div>
     <div class="fn-item">
@@ -14894,6 +15291,172 @@ this.getFormRef().subFormOpen('items', 2)</code></pre>
     </div>
   </div>
 </section>
+<section class="section" id="popup-form-guide">
+  <h2>Popup Form Guide <span class="count">openForm() &mdash; ง่าย → full options</span></h2>
+  <p style="color:#bac2de;font-size:13px;margin:-4px 0 14px;line-height:1.6;">เปิดอีกฟอร์มขึ้นมาเป็น dialog ด้วย <code>this.getFormRef().openForm(formId, dataId, parentId, initData, options)</code> &mdash; ไล่จากใช้งานพื้นฐานไปจนครบทุก option (ตัวอย่างใช้ form id <code>6a2f90e949fcdf666f694b60</code>)</p>
+
+  <div class="fn-list">
+
+    <div class="fn-item">
+      <div class="fn-head">
+        <span class="fn-name">Signature</span>
+        <span class="fn-returns">→ void</span>
+      </div>
+      <div class="fn-desc">4 อาร์กิวเมนต์แรกคือ shortcut ของ option ที่ใช้บ่อย ส่วนตัวที่ 5 (<code>options</code>) ใส่ key ที่เหลือได้ทั้งหมด</div>
+      <div class="fn-example">
+        <div class="example-label">Signature</div>
+        <pre><code>openForm(formId, dataId, parentId, initData, options)
+//       ───────  ──────  ────────  ────────  ───────────────────────────
+//       required  edit    child     prefill   { params, backdrop, readonly,
+//                                                annotated, cancelCallback,
+//                                                afterSaveCallback,
+//                                                beforeSaveCallback, fixApiUrl }</code></pre>
+      </div>
+    </div>
+
+    <div class="fn-item">
+      <div class="fn-head"><span class="fn-name">Level 1 · สร้างใหม่</span><span class="fn-returns">basic</span></div>
+      <div class="fn-desc">เปิดฟอร์มเปล่าเพื่อสร้าง record ใหม่ &mdash; ใส่แค่ formId</div>
+      <div class="fn-example"><div class="example-label">Example</div>
+        <pre><code>await this.getFormRef().openForm('6a2f90e949fcdf666f694b60')</code></pre>
+      </div>
+    </div>
+
+    <div class="fn-item">
+      <div class="fn-head"><span class="fn-name">Level 2 · แก้ไข record เดิม</span><span class="fn-returns">edit</span></div>
+      <div class="fn-desc">ส่ง dataId (ค่า _id ของ record) เป็นอาร์กิวเมนต์ที่ 2 → ฟอร์มจะโหลดข้อมูลขึ้นมาแก้</div>
+      <div class="fn-example"><div class="example-label">Example</div>
+        <pre><code>const id = this.getValue()   // หรือ data.order_id
+await this.getFormRef().openForm('6a2f90e949fcdf666f694b60', id)</code></pre>
+      </div>
+    </div>
+
+    <div class="fn-item">
+      <div class="fn-head"><span class="fn-name">Level 3 · pre-fill ค่าเริ่มต้น</span><span class="fn-returns">initData</span></div>
+      <div class="fn-desc">สร้างใหม่ (dataId = null) แต่เติมค่าตั้งต้นให้ฟอร์มผ่านอาร์กิวเมนต์ที่ 4 (initData)</div>
+      <div class="fn-example"><div class="example-label">Example</div>
+        <pre><code>await this.getFormRef().openForm(
+  '6a2f90e949fcdf666f694b60',
+  null,                        // dataId = null → สร้างใหม่
+  null,                        // parentId
+  {                            // initData → เติมค่าลงฟอร์ม
+    customer_name: data.customer_name,
+    order_date: new Date(),
+    status: 'draft',
+  }
+)</code></pre>
+      </div>
+    </div>
+
+    <div class="fn-item">
+      <div class="fn-head"><span class="fn-name">Level 4 · เปิดเป็น child</span><span class="fn-returns">parentId</span></div>
+      <div class="fn-desc">ผูก record ใหม่กับ record ปัจจุบันด้วย parentId (อาร์กิวเมนต์ที่ 3) &mdash; ฟอร์มปลายทางอ่านผ่าน parentId / parentData</div>
+      <div class="fn-example"><div class="example-label">Example</div>
+        <pre><code>await this.getFormRef().openForm(
+  '6a2f90e949fcdf666f694b60',
+  null,
+  dataId,                      // parentId = record ปัจจุบัน
+  { ref_no: data.doc_no }
+)</code></pre>
+      </div>
+    </div>
+
+    <div class="fn-item">
+      <div class="fn-head"><span class="fn-name">Level 5 · ส่ง params</span><span class="fn-returns">options.params</span></div>
+      <div class="fn-desc">ส่งค่าผ่าน <code>params</code> ในตัวที่ 5 &mdash; ต่างจาก initData ตรงที่ params เป็น read-only context (ไม่ผูกกับ field) ฟอร์มปลายทางอ่านผ่าน <code>formParams</code></div>
+      <div class="fn-example"><div class="example-label">Example</div>
+        <pre><code>await this.getFormRef().openForm(
+  '6a2f90e949fcdf666f694b60',
+  null, null, {},
+  {
+    params: {                  // อ่านที่ฟอร์มปลายทางผ่าน formParams
+      from_form: formId,
+      mode: 'review',
+    },
+  }
+)
+// ฟอร์มปลายทาง:  formParams.from_form  /  formParams.mode</code></pre>
+      </div>
+    </div>
+
+    <div class="fn-item">
+      <div class="fn-head"><span class="fn-name">Level 6 · callbacks</span><span class="fn-returns">before / after save</span></div>
+      <div class="fn-desc">รับ hook ก่อน/หลัง save ของฟอร์มลูก &mdash; เหมาะกับ refresh datagrid หรือคำนวณต่อหลังบันทึก</div>
+      <div class="fn-example"><div class="example-label">Example</div>
+        <pre><code>await this.getFormRef().openForm(
+  '6a2f90e949fcdf666f694b60',
+  null, null, {},
+  {
+    // ก่อน save: รับ formData, return object ที่จะ merge เป็น initData
+    beforeSaveCallback: (formData) => {
+      return { created_by: userInfo.username }
+    },
+
+    // หลัง save สำเร็จ: (data = record ที่บันทึก, autoSave = boolean)
+    afterSaveCallback: (data, autoSave) => {
+      this.reloadOptionData('order_items')   // refresh datagrid
+    },
+  }
+)</code></pre>
+      </div>
+    </div>
+
+    <div class="fn-item">
+      <div class="fn-head"><span class="fn-name">Full options</span><span class="fn-returns">ครบทุก key</span></div>
+      <div class="fn-desc">ตัวอย่างใช้ทุก option พร้อมกัน</div>
+      <div class="fn-example"><div class="example-label">Example</div>
+        <pre><code>await this.getFormRef().openForm(
+  '6a2f90e949fcdf666f694b60',  // formId  (required)
+  null,                        // dataId  (null = สร้างใหม่)
+  dataId,                      // parentId
+  {                            // initData
+    customer_name: data.customer_name,
+    status: 'draft',
+  },
+  {                            // options (arg 5)
+    params: { from_form: formId, ref_doc: data.doc_no },
+    backdrop: true,            // คลิกฉากหลังเพื่อปิดได้
+    readonly: false,           // เปิดแบบอ่านอย่างเดียว
+    annotated: false,          // โหมด annotated
+    fixApiUrl: '',             // override api url (ปกติเว้นว่าง)
+    beforeSaveCallback: (formData) => ({ created_by: userInfo.username }),
+    afterSaveCallback: (data, autoSave) => {
+      this.reloadOptionData('order_items')
+    },
+    // cancelCallback: () => { ... }   // ดูข้อควรระวังด้านล่าง
+  }
+)</code></pre>
+      </div>
+    </div>
+
+    <div class="fn-item">
+      <div class="fn-head"><span class="fn-name">options reference</span><span class="fn-returns">arg 5</span></div>
+      <div class="fn-desc">key ทั้งหมดที่ใส่ใน object ตัวที่ 5 ได้</div>
+      <table class="fn-params">
+        <tr><th>Key</th><th>Type</th><th>Default</th><th>Description</th></tr>
+        <tr><td class="opt-key">params</td><td class="param-type">object</td><td class="opt-hint">formParams</td><td class="opt-hint">read-only context ส่งเข้าฟอร์มปลายทาง อ่านผ่าน formParams (ทับ params เดิมทั้งก้อน)</td></tr>
+        <tr><td class="opt-key">backdrop</td><td class="param-type">boolean</td><td class="opt-hint">false</td><td class="opt-hint">คลิกฉากหลัง (close-on-click-modal) เพื่อปิด popup</td></tr>
+        <tr><td class="opt-key">readonly</td><td class="param-type">boolean</td><td class="opt-hint">false</td><td class="opt-hint">เปิดฟอร์มแบบอ่านอย่างเดียว</td></tr>
+        <tr><td class="opt-key">annotated</td><td class="param-type">boolean</td><td class="opt-hint">false</td><td class="opt-hint">โหมด annotated</td></tr>
+        <tr><td class="opt-key">beforeSaveCallback</td><td class="param-type">(formData) ⇒ object</td><td class="opt-hint">—</td><td class="opt-hint">เรียกก่อน save, return ค่าที่ merge เป็น initData</td></tr>
+        <tr><td class="opt-key">afterSaveCallback</td><td class="param-type">(data, autoSave) ⇒ void</td><td class="opt-hint">—</td><td class="opt-hint">เรียกหลัง save สำเร็จ</td></tr>
+        <tr><td class="opt-key">cancelCallback</td><td class="param-type">() ⇒ void</td><td class="opt-hint">subFormClose</td><td class="opt-hint">เรียกตอนปิด/ยกเลิก &mdash; ดูข้อควรระวัง</td></tr>
+        <tr><td class="opt-key">fixApiUrl</td><td class="param-type">string</td><td class="opt-hint">''</td><td class="opt-hint">override api url ของฟอร์มปลายทาง</td></tr>
+      </table>
+    </div>
+
+    <div class="fn-item">
+      <div class="fn-head"><span class="fn-name">⚠ ข้อควรระวัง</span><span class="fn-returns">gotchas</span></div>
+      <div class="fn-desc" style="line-height:1.8;">
+        <strong style="color:#f9e2af;">ไม่มี width / fullscreen ใน options</strong> &mdash; ความกว้าง popup มาจาก <code>form_options.popup_size</code> ของ <em>ฟอร์มปลายทาง</em> (ตั้งใน builder) ไม่ได้กำหนดผ่าน openForm<br>
+        <strong style="color:#f9e2af;">cancelCallback ทับตัว default</strong> &mdash; default คือ <code>subFormClose</code> ที่ปิด popup ให้ ถ้าส่งเอง popup จะไม่ปิดอัตโนมัติ ต้องเรียกปิดเองในฟังก์ชัน<br>
+        <strong style="color:#f9e2af;">params ทับทั้งก้อน</strong> &mdash; default = formParams ของฟอร์มปัจจุบัน ถ้าส่ง params เอง ค่าเดิมจะหายทั้งหมด<br>
+        <strong style="color:#f9e2af;">openForm vs subFormOpen</strong> &mdash; <code>openForm</code> เปิด<em>อีกฟอร์ม</em>ทั้งฟอร์ม ส่วน <code>subFormOpen(name, rowIndex)</code> เปิด row ของ sub-form field ในฟอร์มเดียวกัน
+      </div>
+    </div>
+
+  </div>
+</section>
 <section class="section" id="api-functions">
   <h2>API Functions <span class="count">this.getFormRef().userState.*</span></h2>
   <div class="fn-list">