@20baht/ui 0.0.0-stage → 0.1.0

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.
Files changed (246) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +501 -2
  3. package/dist/components/baht-form.d.ts +191 -0
  4. package/dist/components/baht-form.js +614 -0
  5. package/dist/components/baht-workflow.d.ts +173 -0
  6. package/dist/components/baht-workflow.js +430 -0
  7. package/dist/components/base.d.ts +92 -0
  8. package/dist/components/base.js +138 -0
  9. package/dist/components/combobox-controller.d.ts +65 -0
  10. package/dist/components/combobox-controller.js +82 -0
  11. package/dist/components/define.d.ts +7 -0
  12. package/dist/components/define.js +16 -0
  13. package/dist/components/field-base.d.ts +84 -0
  14. package/dist/components/field-base.js +152 -0
  15. package/dist/components/floating.d.ts +84 -0
  16. package/dist/components/floating.js +182 -0
  17. package/dist/components/form-layout.d.ts +39 -0
  18. package/dist/components/form-layout.js +67 -0
  19. package/dist/components/form-options.d.ts +39 -0
  20. package/dist/components/form-options.js +65 -0
  21. package/dist/components/form-readonly.d.ts +20 -0
  22. package/dist/components/form-readonly.js +70 -0
  23. package/dist/components/layers.d.ts +4 -0
  24. package/dist/components/layers.js +15 -0
  25. package/dist/components/menu-controller.d.ts +65 -0
  26. package/dist/components/menu-controller.js +134 -0
  27. package/dist/components/motion.d.ts +9 -0
  28. package/dist/components/motion.js +16 -0
  29. package/dist/components/primitives/baht-accordion.d.ts +29 -0
  30. package/dist/components/primitives/baht-accordion.js +66 -0
  31. package/dist/components/primitives/baht-alert.d.ts +20 -0
  32. package/dist/components/primitives/baht-alert.js +62 -0
  33. package/dist/components/primitives/baht-app-shell.d.ts +81 -0
  34. package/dist/components/primitives/baht-app-shell.js +161 -0
  35. package/dist/components/primitives/baht-approval-chain.d.ts +59 -0
  36. package/dist/components/primitives/baht-approval-chain.js +80 -0
  37. package/dist/components/primitives/baht-avatar.d.ts +19 -0
  38. package/dist/components/primitives/baht-avatar.js +43 -0
  39. package/dist/components/primitives/baht-badge.d.ts +24 -0
  40. package/dist/components/primitives/baht-badge.js +41 -0
  41. package/dist/components/primitives/baht-bar-chart.d.ts +78 -0
  42. package/dist/components/primitives/baht-bar-chart.js +361 -0
  43. package/dist/components/primitives/baht-breadcrumbs.d.ts +23 -0
  44. package/dist/components/primitives/baht-breadcrumbs.js +45 -0
  45. package/dist/components/primitives/baht-button.d.ts +89 -0
  46. package/dist/components/primitives/baht-button.js +146 -0
  47. package/dist/components/primitives/baht-calendar.d.ts +96 -0
  48. package/dist/components/primitives/baht-calendar.js +398 -0
  49. package/dist/components/primitives/baht-card.d.ts +34 -0
  50. package/dist/components/primitives/baht-card.js +70 -0
  51. package/dist/components/primitives/baht-catalog-card.d.ts +52 -0
  52. package/dist/components/primitives/baht-catalog-card.js +90 -0
  53. package/dist/components/primitives/baht-checkbox.d.ts +7 -0
  54. package/dist/components/primitives/baht-checkbox.js +40 -0
  55. package/dist/components/primitives/baht-choice-group.d.ts +52 -0
  56. package/dist/components/primitives/baht-choice-group.js +71 -0
  57. package/dist/components/primitives/baht-code.d.ts +18 -0
  58. package/dist/components/primitives/baht-code.js +33 -0
  59. package/dist/components/primitives/baht-column-picker.d.ts +69 -0
  60. package/dist/components/primitives/baht-column-picker.js +234 -0
  61. package/dist/components/primitives/baht-comments.d.ts +38 -0
  62. package/dist/components/primitives/baht-comments.js +102 -0
  63. package/dist/components/primitives/baht-currency.d.ts +13 -0
  64. package/dist/components/primitives/baht-currency.js +69 -0
  65. package/dist/components/primitives/baht-datepicker.d.ts +77 -0
  66. package/dist/components/primitives/baht-datepicker.js +235 -0
  67. package/dist/components/primitives/baht-donut-chart.d.ts +24 -0
  68. package/dist/components/primitives/baht-donut-chart.js +88 -0
  69. package/dist/components/primitives/baht-edit-table.d.ts +45 -0
  70. package/dist/components/primitives/baht-edit-table.js +176 -0
  71. package/dist/components/primitives/baht-empty-state.d.ts +26 -0
  72. package/dist/components/primitives/baht-empty-state.js +51 -0
  73. package/dist/components/primitives/baht-error-state.d.ts +21 -0
  74. package/dist/components/primitives/baht-error-state.js +44 -0
  75. package/dist/components/primitives/baht-facts.d.ts +42 -0
  76. package/dist/components/primitives/baht-facts.js +49 -0
  77. package/dist/components/primitives/baht-fieldset.d.ts +19 -0
  78. package/dist/components/primitives/baht-fieldset.js +42 -0
  79. package/dist/components/primitives/baht-file.d.ts +27 -0
  80. package/dist/components/primitives/baht-file.js +158 -0
  81. package/dist/components/primitives/baht-filter-builder.d.ts +39 -0
  82. package/dist/components/primitives/baht-filter-builder.js +201 -0
  83. package/dist/components/primitives/baht-filter.d.ts +36 -0
  84. package/dist/components/primitives/baht-filter.js +64 -0
  85. package/dist/components/primitives/baht-heatmap.d.ts +49 -0
  86. package/dist/components/primitives/baht-heatmap.js +168 -0
  87. package/dist/components/primitives/baht-input.d.ts +10 -0
  88. package/dist/components/primitives/baht-input.js +44 -0
  89. package/dist/components/primitives/baht-keyvalue-editor.d.ts +28 -0
  90. package/dist/components/primitives/baht-keyvalue-editor.js +106 -0
  91. package/dist/components/primitives/baht-line-chart.d.ts +45 -0
  92. package/dist/components/primitives/baht-line-chart.js +183 -0
  93. package/dist/components/primitives/baht-link.d.ts +26 -0
  94. package/dist/components/primitives/baht-link.js +48 -0
  95. package/dist/components/primitives/baht-list.d.ts +29 -0
  96. package/dist/components/primitives/baht-list.js +79 -0
  97. package/dist/components/primitives/baht-loading-overlay.d.ts +15 -0
  98. package/dist/components/primitives/baht-loading-overlay.js +33 -0
  99. package/dist/components/primitives/baht-markdown-view.d.ts +17 -0
  100. package/dist/components/primitives/baht-markdown-view.js +39 -0
  101. package/dist/components/primitives/baht-markdown.d.ts +34 -0
  102. package/dist/components/primitives/baht-markdown.js +177 -0
  103. package/dist/components/primitives/baht-menu.d.ts +53 -0
  104. package/dist/components/primitives/baht-menu.js +100 -0
  105. package/dist/components/primitives/baht-meter.d.ts +67 -0
  106. package/dist/components/primitives/baht-meter.js +107 -0
  107. package/dist/components/primitives/baht-modal.d.ts +71 -0
  108. package/dist/components/primitives/baht-modal.js +164 -0
  109. package/dist/components/primitives/baht-multiselect.d.ts +8 -0
  110. package/dist/components/primitives/baht-multiselect.js +47 -0
  111. package/dist/components/primitives/baht-notification-bell.d.ts +54 -0
  112. package/dist/components/primitives/baht-notification-bell.js +143 -0
  113. package/dist/components/primitives/baht-number.d.ts +5 -0
  114. package/dist/components/primitives/baht-number.js +39 -0
  115. package/dist/components/primitives/baht-order-box.d.ts +24 -0
  116. package/dist/components/primitives/baht-order-box.js +50 -0
  117. package/dist/components/primitives/baht-otp.d.ts +49 -0
  118. package/dist/components/primitives/baht-otp.js +109 -0
  119. package/dist/components/primitives/baht-page-header.d.ts +43 -0
  120. package/dist/components/primitives/baht-page-header.js +78 -0
  121. package/dist/components/primitives/baht-pagination.d.ts +33 -0
  122. package/dist/components/primitives/baht-pagination.js +86 -0
  123. package/dist/components/primitives/baht-popover.d.ts +45 -0
  124. package/dist/components/primitives/baht-popover.js +112 -0
  125. package/dist/components/primitives/baht-progress-ring.d.ts +22 -0
  126. package/dist/components/primitives/baht-progress-ring.js +62 -0
  127. package/dist/components/primitives/baht-progress.d.ts +17 -0
  128. package/dist/components/primitives/baht-progress.js +48 -0
  129. package/dist/components/primitives/baht-radio.d.ts +7 -0
  130. package/dist/components/primitives/baht-radio.js +74 -0
  131. package/dist/components/primitives/baht-range.d.ts +38 -0
  132. package/dist/components/primitives/baht-range.js +88 -0
  133. package/dist/components/primitives/baht-rating.d.ts +40 -0
  134. package/dist/components/primitives/baht-rating.js +107 -0
  135. package/dist/components/primitives/baht-record-bar.d.ts +30 -0
  136. package/dist/components/primitives/baht-record-bar.js +60 -0
  137. package/dist/components/primitives/baht-reference-dialog.d.ts +87 -0
  138. package/dist/components/primitives/baht-reference-dialog.js +418 -0
  139. package/dist/components/primitives/baht-reference-picker.d.ts +110 -0
  140. package/dist/components/primitives/baht-reference-picker.js +321 -0
  141. package/dist/components/primitives/baht-repeater.d.ts +59 -0
  142. package/dist/components/primitives/baht-repeater.js +315 -0
  143. package/dist/components/primitives/baht-rule-builder.d.ts +24 -0
  144. package/dist/components/primitives/baht-rule-builder.js +177 -0
  145. package/dist/components/primitives/baht-saved-filters.d.ts +41 -0
  146. package/dist/components/primitives/baht-saved-filters.js +126 -0
  147. package/dist/components/primitives/baht-search.d.ts +34 -0
  148. package/dist/components/primitives/baht-search.js +71 -0
  149. package/dist/components/primitives/baht-section-header.d.ts +28 -0
  150. package/dist/components/primitives/baht-section-header.js +48 -0
  151. package/dist/components/primitives/baht-section.d.ts +23 -0
  152. package/dist/components/primitives/baht-section.js +49 -0
  153. package/dist/components/primitives/baht-select.d.ts +49 -0
  154. package/dist/components/primitives/baht-select.js +197 -0
  155. package/dist/components/primitives/baht-skeleton.d.ts +16 -0
  156. package/dist/components/primitives/baht-skeleton.js +37 -0
  157. package/dist/components/primitives/baht-sparkline.d.ts +23 -0
  158. package/dist/components/primitives/baht-sparkline.js +56 -0
  159. package/dist/components/primitives/baht-spinner.d.ts +13 -0
  160. package/dist/components/primitives/baht-spinner.js +30 -0
  161. package/dist/components/primitives/baht-split-button.d.ts +43 -0
  162. package/dist/components/primitives/baht-split-button.js +87 -0
  163. package/dist/components/primitives/baht-stat-chart.d.ts +14 -0
  164. package/dist/components/primitives/baht-stat-chart.js +38 -0
  165. package/dist/components/primitives/baht-stat.d.ts +56 -0
  166. package/dist/components/primitives/baht-stat.js +117 -0
  167. package/dist/components/primitives/baht-steps.d.ts +33 -0
  168. package/dist/components/primitives/baht-steps.js +60 -0
  169. package/dist/components/primitives/baht-swipe-row.d.ts +64 -0
  170. package/dist/components/primitives/baht-swipe-row.js +178 -0
  171. package/dist/components/primitives/baht-table.d.ts +315 -0
  172. package/dist/components/primitives/baht-table.js +640 -0
  173. package/dist/components/primitives/baht-tabs.d.ts +54 -0
  174. package/dist/components/primitives/baht-tabs.js +128 -0
  175. package/dist/components/primitives/baht-tags.d.ts +96 -0
  176. package/dist/components/primitives/baht-tags.js +323 -0
  177. package/dist/components/primitives/baht-text.d.ts +10 -0
  178. package/dist/components/primitives/baht-text.js +29 -0
  179. package/dist/components/primitives/baht-textarea.d.ts +5 -0
  180. package/dist/components/primitives/baht-textarea.js +40 -0
  181. package/dist/components/primitives/baht-theme-toggle.d.ts +44 -0
  182. package/dist/components/primitives/baht-theme-toggle.js +101 -0
  183. package/dist/components/primitives/baht-timeline.d.ts +21 -0
  184. package/dist/components/primitives/baht-timeline.js +42 -0
  185. package/dist/components/primitives/baht-toast.d.ts +29 -0
  186. package/dist/components/primitives/baht-toast.js +83 -0
  187. package/dist/components/primitives/baht-toggle.d.ts +6 -0
  188. package/dist/components/primitives/baht-toggle.js +42 -0
  189. package/dist/components/primitives/baht-tooltip.d.ts +34 -0
  190. package/dist/components/primitives/baht-tooltip.js +85 -0
  191. package/dist/components/primitives/baht-tree.d.ts +58 -0
  192. package/dist/components/primitives/baht-tree.js +159 -0
  193. package/dist/components/primitives/baht-typeahead.d.ts +92 -0
  194. package/dist/components/primitives/baht-typeahead.js +258 -0
  195. package/dist/components/primitives/baht-upload.d.ts +108 -0
  196. package/dist/components/primitives/baht-upload.js +325 -0
  197. package/dist/components/primitives/baht-wizard.d.ts +57 -0
  198. package/dist/components/primitives/baht-wizard.js +147 -0
  199. package/dist/components/primitives/charts.d.ts +134 -0
  200. package/dist/components/primitives/charts.js +184 -0
  201. package/dist/components/primitives/column-map.d.ts +56 -0
  202. package/dist/components/primitives/column-map.js +70 -0
  203. package/dist/components/primitives/control-icons.d.ts +2 -0
  204. package/dist/components/primitives/control-icons.js +40 -0
  205. package/dist/components/primitives/icons.d.ts +24 -0
  206. package/dist/components/primitives/icons.js +86 -0
  207. package/dist/components/primitives/illustrations.d.ts +21 -0
  208. package/dist/components/primitives/illustrations.js +78 -0
  209. package/dist/components/primitives/index.d.ts +89 -0
  210. package/dist/components/primitives/kbd.d.ts +6 -0
  211. package/dist/components/primitives/kbd.js +9 -0
  212. package/dist/components/primitives/listbox.d.ts +2 -0
  213. package/dist/components/primitives/listbox.js +7 -0
  214. package/dist/components/primitives/markdown-render.d.ts +9 -0
  215. package/dist/components/primitives/markdown-render.js +77 -0
  216. package/dist/components/primitives/rule-rows.d.ts +55 -0
  217. package/dist/components/primitives/rule-rows.js +75 -0
  218. package/dist/components/primitives/tag-map.d.ts +6 -0
  219. package/dist/components/primitives/tag-map.js +39 -0
  220. package/dist/components/reference-labels.d.ts +22 -0
  221. package/dist/components/reference-labels.js +29 -0
  222. package/dist/components/shortcuts.d.ts +7 -0
  223. package/dist/components/shortcuts.js +43 -0
  224. package/dist/css/components.css +7517 -0
  225. package/dist/css/datepicker.css +346 -0
  226. package/dist/css/tokens.css +679 -0
  227. package/dist/custom-elements.json +45110 -0
  228. package/dist/engine.d.ts +1 -0
  229. package/dist/engine.js +1 -0
  230. package/dist/hydrate.d.ts +9 -0
  231. package/dist/hydrate.js +46 -0
  232. package/dist/index.d.ts +7 -0
  233. package/dist/index.js +210 -0
  234. package/dist/overlay.d.ts +50 -0
  235. package/dist/overlay.js +140 -0
  236. package/dist/react.d.ts +557 -0
  237. package/dist/react.js +1 -0
  238. package/dist/register.d.ts +106 -0
  239. package/dist/register.js +99 -0
  240. package/dist/ssr.d.ts +16 -0
  241. package/dist/ssr.js +125 -0
  242. package/dist/tokens.css +8197 -0
  243. package/dist/vscode.css-custom-data.json +6 -0
  244. package/dist/vscode.html-custom-data.json +2261 -0
  245. package/dist/web-types.json +6523 -0
  246. package/package.json +157 -4
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Nattapong Promthong
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,502 @@
1
- # Temporary Holding Version
1
+ # bahtui
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ **JSON in, interactive form out.** A framework-neutral form + workflow engine shipped as Web
4
+ Components (Lit, light DOM) with a pure-TypeScript rules core.
5
+
6
+ ```
7
+ npm i @20baht/ui
8
+ npm i flatpickr # peer dependency — only if you render date fields / <baht-datepicker>
9
+ ```
10
+
11
+ ## Quick start — one form (Level 1)
12
+
13
+ ```html
14
+ <script type="module">
15
+ import '@20baht/ui'; // registers <baht-form> / <baht-workflow>
16
+ </script>
17
+ <link rel="stylesheet" href="@20baht/ui/tokens.css" />
18
+
19
+ <baht-form id="f"></baht-form>
20
+ <script>
21
+ const el = document.getElementById('f');
22
+ el.form = {
23
+ form_id: 'f1',
24
+ form_name: 'Person',
25
+ fields: [
26
+ { order: 1, type: 'text', key: 'firstName', label: 'First name', width: '1/2', required: true, value: '' },
27
+ { order: 2, type: 'text', key: 'lastName', label: 'Last name', width: '1/2', required: true, value: '' },
28
+ { order: 3, type: 'number', key: 'age', label: 'Age', width: '1/4', min: 0, value: null }
29
+ ]
30
+ };
31
+ el.addEventListener('baht-change', (e) => console.log(e.detail.data));
32
+ // el.validate() / el.getData() / el.setValue({...}) / el.reset()
33
+ </script>
34
+ ```
35
+
36
+ `<baht-form>` is a **dumb controlled component**: props in → UI → `baht-change` out. No buttons, no
37
+ cross-field logic, no fetch. Your app owns the state (mutate the JSON, feed it back).
38
+
39
+ ### Views — show a subset of one form
40
+
41
+ Define named display projections on the schema (e.g. per user role); select one with the
42
+ `view` attribute:
43
+
44
+ ```js
45
+ el.form = {
46
+ ...form,
47
+ views: [{ name: 'summary', fields: ['age', 'firstName'] }], // view order = display order
48
+ };
49
+ el.view = 'summary'; // or <baht-form view="summary">; unset = full form
50
+ ```
51
+
52
+ Views are **client-side display only**: the view picks which fields render (and validate —
53
+ the user can only fix what they see), but `getData()` still returns the full form and the
54
+ server (`@20baht/validator`) always validates the complete schema. In a workflow, set
55
+ `view: 'summary'` on a step's form to pin the view that step renders.
56
+
57
+ ### Read-only display
58
+
59
+ `<baht-form readonly>` shows a submission instead of editing it: values as text, option
60
+ labels instead of keys, chips for multi-picks, Yes/No, no help text, "Not provided" for
61
+ blanks. Same grid, same widths. `displayValue(field, value)` from `@20baht/ui/engine`
62
+ gives you the same formatting for tables.
63
+
64
+ ### Repeater — line items / repeating rows
65
+
66
+ ```js
67
+ { order: 5, type: 'repeater', key: 'items', label: 'Line items', min_rows: 1,
68
+ fields: [
69
+ { order: 1, type: 'text', key: 'name', width: '1/2', required: true },
70
+ { order: 2, type: 'number', key: 'qty', width: '1/4', min: 1 },
71
+ ] }
72
+ ```
73
+
74
+ Value is an array of row objects (`getData().items → [{ name, qty }, …]`). Rows add/remove in
75
+ the UI (`min_rows`/`max_rows` bound the count), each row validates its sub-fields — errors come
76
+ back as `items[0].name`, on both the client and `@20baht/validator`. One level deep only.
77
+
78
+ ### Dependent / async dropdowns
79
+
80
+ ```js
81
+ // schema — functions never live in JSON, only registry names:
82
+ { order: 2, type: 'dropdown', key: 'amphoe', options_from: 'amphoeFor', options_deps: ['province'] }
83
+
84
+ // registry:
85
+ el.registry = {
86
+ options: { amphoeFor: (data) => fetch(`/api/amphoe?p=${data.province}`).then(r => r.json()) },
87
+ };
88
+ ```
89
+
90
+ Options resolve from the registry with the form's current data (sync or Promise). When a
91
+ dep changes, options refetch and the dependent value clears — cascading down chains
92
+ (จังหวัด → อำเภอ → ตำบล).
93
+
94
+ ### Cross-field validation
95
+
96
+ ```js
97
+ { order: 2, type: 'date', key: 'end',
98
+ validators: [{ type: 'compare', op: 'gte', field: 'start' }] }
99
+ ```
100
+
101
+ `compare` checks against a sibling field (confirm email = `op: 'eq'`): `eq`/`ne` are strict like a
102
+ rule's (`"0123"` is not `"123"`), the ordering ops are numeric/date-aware; it skips while either side is empty. Works inside repeater rows and on the server.
103
+
104
+ ### Feature flags — deploy dark, flip a JSON file
105
+
106
+ ```js
107
+ // schema: gate a field / workflow step / rule
108
+ { order: 9, type: 'text', key: 'promoCode', flag: 'promo' } // '!promo' = the old path
109
+
110
+ // host: flags from one static file — edit it, features flip
111
+ el.flags = await fetch('/flags.json').then((r) => r.json()); // { "promo": true }
112
+ ```
113
+
114
+ Flag-off means **not in the schema**: no render, no validation (a dark `required` can't
115
+ block), nothing in the payload. Missing keys count as off, so new features stay dark until
116
+ the file turns them on. Server side: `validateSubmission(applyFlags(schema, flags), data)`
117
+ with the same JSON — `@20baht/validator` re-exports `applyFlags`.
118
+
119
+ ### File upload
120
+
121
+ ```js
122
+ // schema:
123
+ { order: 6, type: 'file', key: 'doc', uploader: 'default', accept: '.pdf,image/*', max_size: 10_485_760 }
124
+
125
+ // registry — File in, serializable ref out:
126
+ el.registry = {
127
+ uploaders: { default: async (file) => {
128
+ const fd = new FormData(); fd.append('file', file);
129
+ return (await fetch('/api/uploads', { method: 'POST', body: fd })).json();
130
+ } },
131
+ };
132
+ ```
133
+
134
+ Picking a file uploads immediately; the value becomes `{ name, size, type, url }` — plain
135
+ JSON, chips with remove buttons in the UI, `max_size`/`accept` validated on both client and
136
+ server. Omit `uploader` for the old capture-only mode.
137
+
138
+ No registry function at all? `<baht-upload>` talks to an endpoint straight from attributes:
139
+ the file is POSTed as multipart on pick, the endpoint returns the stored URL, and that URL is
140
+ the value (`baht-change` → `{ value, files }`; progress and error events included).
141
+
142
+ ```html
143
+ <baht-upload url="/api/uploads" accept=".pdf,image/*" max-size="10485760" label="Attachment"></baht-upload>
144
+ ```
145
+
146
+ ### Drafts / autosave (host pattern)
147
+
148
+ The library is controlled — autosave is three lines in your app:
149
+
150
+ ```js
151
+ el.addEventListener('baht-change', (e) => localStorage.setItem(key, JSON.stringify(e.detail.data)));
152
+ // (workflow: listen to baht-data-change instead)
153
+ el.value = JSON.parse(localStorage.getItem(key) ?? '{}'); // restore on mount
154
+ // clear the key after the server accepts the submission
155
+ ```
156
+
157
+ The `/builder` page of the docs site (`bun run --filter docs dev`) shows the same flow live.
158
+
159
+ ### i18n — Thai (or any) built-in strings
160
+
161
+ All built-in strings — validation messages, Next/Submit/Back, the approval step —
162
+ come from one catalog:
163
+
164
+ ```js
165
+ import { setLocale } from '@20baht/ui';
166
+
167
+ setLocale('th'); // built-ins: 'en' (default), 'th'
168
+ setLocale('th', { required: 'ห้ามว่าง' }); // locale + your own overrides
169
+ ```
170
+
171
+ Call it once before mounting. Per-field `message` and label attributes
172
+ (`next-label`, `approval.approve_label`, …) still win over the catalog. The server can
173
+ localize too: `@20baht/validator` re-exports `setLocale`, so validation issues come
174
+ back in the same language the client shows.
175
+
176
+ ## Quick start — wizard with rules (Level 2)
177
+
178
+ ```js
179
+ document.querySelector('baht-workflow').workflow = {
180
+ workflow_id: 'wf-1',
181
+ forms: [/* {form_id, form_name, order, fields}, ... */],
182
+ rules: [
183
+ { id: 'skip-person',
184
+ when: { field: 'Intro.kind', op: 'eq', value: 'company' },
185
+ then: [{ action: 'skipForm', target: { form: 'Person' } }] },
186
+ { id: 'vat',
187
+ when: { field: 'Company.hasVat', op: 'eq', value: true },
188
+ then: [{ action: 'show', target: { form: 'Company', field: 'vatId' } },
189
+ { action: 'required', target: { form: 'Company', field: 'vatId' } }],
190
+ else: [{ action: 'hide', target: { form: 'Company', field: 'vatId' } }] }
191
+ ]
192
+ };
193
+ ```
194
+
195
+ `<baht-workflow>` walks the forms in `order`, evaluates the rules on every change
196
+ (show/hide/enable/disable/readonly/required/setValue/skipForm…), renders the single
197
+ Next→Submit button, and emits `baht-next` / `baht-submit` / `baht-complete` / `baht-data-change` /
198
+ `baht-step-change`. **The runtime navigates; your app acts.**
199
+
200
+ ## Headless core (any framework, no DOM)
201
+
202
+ ```ts
203
+ import { evaluate, validateField } from '@20baht/ui/engine';
204
+
205
+ const derived = evaluate(workflow, { Intro: { kind: 'company' } });
206
+ // derived.forms -> { Person: { visible: false }, ... }
207
+ // derived.fields -> { 'Company.vatId': { visible, enabled, readonly, required, computed } }
208
+ // derived.data -> nested output (hidden/skipped values cleared + excluded)
209
+ ```
210
+
211
+ The engine is its own package, [`@20baht/engine`](https://www.npmjs.com/package/@20baht/engine) (no
212
+ DOM, no Lit, no dependencies); `@20baht/ui/engine` re-exports it. A server that renders nothing can
213
+ install that one alone.
214
+
215
+ The engine is a pure function with fixpoint evaluation (cycle-guarded), per-rule `priority`
216
+ conflict resolution, and clear-on-hide/skip semantics. Build a React/Vue renderer on top of it
217
+ without touching the Web Components.
218
+
219
+ ### A whole run, headless
220
+
221
+ `updateWorkflow` is the workflow's runtime as one pure function: a run is a plain value, a press or
222
+ an edit is a message, and each step returns the next state plus the events `<baht-workflow>` would
223
+ dispatch, in order. No DOM, nothing kept between calls.
224
+
225
+ ```ts
226
+ import { updateWorkflow, nextTarget } from '@20baht/ui/engine';
227
+
228
+ let { state } = updateWorkflow(workflow, null, { type: 'start', value: {} });
229
+ ({ state } = updateWorkflow(workflow, state, { type: 'edit', form_name: 'Intro', key: 'kind', value: 'company' }));
230
+ const { state: after, events } = updateWorkflow(workflow, state, {
231
+ type: 'next',
232
+ validity: { valid: true, errors: [] }, // you validate the form (validateField); the runtime gates on it
233
+ gate: true,
234
+ });
235
+ // after.current -> 'Company'; after.history -> ['Intro']; after.derived.data -> the data
236
+ // events -> [{ name: 'baht-next', detail }, { name: 'baht-step-change', detail }]
237
+ nextTarget(workflow, after); // the step after this one, or 'end'
238
+ ```
239
+
240
+ Messages: `start`, `edit`, `patch`, `comment`, `next`, `decide`, `back`, `gotoStart`, `flags`, `restore`.
241
+ `snapshotOf(state)` is the run as JSON (`{ data, current, history }`) and `restore` picks it up again;
242
+ `<baht-workflow>` has the same pair as `getState()` / `restore(snapshot)`, for drafts, resume and undo. Pass
243
+ the workflow with its flags applied (`applyFlags`). Typed-input debounce and form validation stay
244
+ with the caller: they are the renderer's business.
245
+
246
+ `<baht-workflow>` tells every step it takes as `baht-transition { msg, before, after, events }`, after
247
+ the step's own events. That is a log, a replay and an undo:
248
+
249
+ ```ts
250
+ const log: WorkflowTransition[] = [];
251
+ el.addEventListener('baht-transition', (e) => log.push(e.detail));
252
+
253
+ replayWorkflow(workflow, log.map((t) => t.msg)); // { state, events }: the same run, no DOM
254
+ el.restore(snapshotOf(log.at(-1).before)); // undo the last step
255
+ ```
256
+
257
+ A replay is exact for the rules and the navigation. What a host script wrote during the run is in the log
258
+ only as the edits it made; the script does not run again.
259
+
260
+ ### A form, headless
261
+
262
+ One form has the same shape: `updateForm(input, state, msg)` returns the next state and the events
263
+ `<baht-form>` would dispatch. `input` is what the host owns (the definition with its flags applied, the
264
+ starting `value`, the registry, rule-derived `fieldStates`, a `view`); `state` is what the form remembers
265
+ (the edits, the errors, what scripts set).
266
+
267
+ ```ts
268
+ import { emptyFormState, formData, updateForm } from '@20baht/ui/engine';
269
+
270
+ const input = { form, value: { name: 'Ann' }, registry };
271
+ let { state } = updateForm(input, emptyFormState, { type: 'load' }); // load scripts
272
+ ({ state } = updateForm(input, state, { type: 'input', key: 'age', value: 30 }));
273
+ const { state: checked, events } = updateForm(input, state, { type: 'validate' });
274
+ // checked.errors -> what is wrong; events -> [{ name: 'baht-validity', detail }]
275
+ formData(input, checked); // { name: 'Ann', age: 30, ... } the whole form, whatever the view
276
+ ```
277
+
278
+ Messages: `input`, `set`, `revert`, `value`, `form`, `load`, `validate`, `blur`, `script`, `reset`. Formatters,
279
+ dependent options (`options_deps`) and client scripts run inside the step. A script handler that keeps `g`
280
+ past its step (after an `await`) needs a host that lends it one: pass `{ context }` as the fourth argument
281
+ and forward late calls as a `script` message, as `<baht-form>` does. `validateShownField` and
282
+ `submitScriptErrors` are the two checks the browser and `@20baht/validator` share.
283
+
284
+ ## Functions never travel in JSON
285
+
286
+ Formatters and custom validators are referenced **by name** and resolved from a registry you
287
+ pass as a prop:
288
+
289
+ ```js
290
+ el.registry = {
291
+ formatters: { uppercase: (v) => String(v).toUpperCase() },
292
+ validators: { idCardTH: (v) => isThaiId(v) ? null : 'บัตรประชาชนไม่ถูกต้อง' }
293
+ };
294
+ // JSON side: { formatter: 'uppercase', validators: [{ type: 'custom', fn: 'idCardTH' }] }
295
+ ```
296
+
297
+ ### Client scripts — ServiceNow-style `load` / `change` / `submit`
298
+
299
+ When rules JSON isn't enough, register imperative hooks the same way — by name:
300
+
301
+ ```js
302
+ // JSON side
303
+ form.scripts = [
304
+ { on: 'change', field: 'type', handler: 'typeChanged' },
305
+ { on: 'submit', handler: 'checkQuota' },
306
+ ];
307
+ // host side — `g` is the g_form equivalent, scoped to this form
308
+ el.registry.scripts = {
309
+ typeChanged: (g, { newValue, isLoading }) => {
310
+ if (isLoading) return;
311
+ g.setRequired('doc', newValue === 'sick');
312
+ g.showFieldMsg('doc', 'แนบใบรับรองแพทย์', 'info');
313
+ },
314
+ checkQuota: (g) => {
315
+ if (g.getValue('days') > 10) { g.addErrorMessage('เกินโควตา'); return false; } // blocks submit
316
+ },
317
+ };
318
+ ```
319
+
320
+ `g` reads (`getValue`, `getData`), writes (`setValue` — cascades to that field's `change`
321
+ script, depth-guarded), overrides UI state (`setVisible` / `setReadOnly` / `setRequired` /
322
+ `setDisabled`, on top of rule-derived states) and shows messages. `@20baht/validator`
323
+ re-runs `submit` scripts on the server; `load`/`change` are UI-only. See
324
+ `docs/components/baht-form.md` and spec 01 §14.
325
+
326
+ ## Design system — 20baht
327
+
328
+ Ships themed as the **20baht design system**, "ledger" retone: minimal and flat —
329
+ near-black ink (`#171717`) on white, hairline neutral borders, 44px controls, one indigo accent
330
+ (`#444FBF`), status as tint pills, hand-drawn koboyo spot illustrations for empty /
331
+ error / upload states, IBM Plex Sans Thai / IBM Plex Mono (load the
332
+ fonts yourself), borders-over-shadows, "paper" easing — plus an opt-in dark theme
333
+ (`<html data-baht-theme="dark">`). 64 elements:
334
+
335
+ ```html
336
+ <baht-button variant="secondary" size="sm">Cancel</baht-button>
337
+ <baht-badge tone="success" label="Running"></baht-badge>
338
+ <baht-table></baht-table> <baht-modal></baht-modal> <baht-toast></baht-toast> …
339
+ ```
340
+
341
+ - **Data (server-side paging)** — `baht-table` · `baht-list` · `baht-swipe-row` · `baht-pagination` · `baht-filter`.
342
+ `baht-table` ships a ServiceNow-style column picker with dot-walking into reference columns (`requester.department`) and emits `baht-columns-change` so the host can persist the layout.
343
+ `items` is one page; `baht-page-change` asks your app to fetch the next one.
344
+ - **Actions** — `baht-button` (`shortcut="alt+q"`: bound key + tooltip hint) · `baht-split-button` (main action + menu with shortcut hints) · `baht-menu` (⋯ / labelled action menu) · `baht-theme-toggle` (light / dark switch)
345
+ - **Feedback** — `baht-modal` · `baht-toast` · `baht-alert` · `baht-tooltip` · `baht-popover` · `baht-progress` ·
346
+ `baht-spinner` · `baht-skeleton`
347
+ - **Inputs** — `baht-rating` · `baht-range` · `baht-otp` · `baht-typeahead` · `baht-reference-picker` ·
348
+ `baht-keyvalue-editor` · `baht-upload` (+ the 15 form field primitives). Typed fields debounce keystrokes
349
+ (150 ms, `debounce`); `dropdown` renders its own listbox, never the OS picker.
350
+ - **Stats & charts** — `baht-stat` · `baht-stat-chart` · `baht-meter` · `baht-sparkline` · `baht-bar-chart` ·
351
+ `baht-line-chart` · `baht-donut-chart` · `baht-heatmap` · `baht-progress-ring`
352
+ - **Structure & nav** — `baht-card` · `baht-fieldset` · `baht-timeline` · `baht-accordion` · `baht-steps` ·
353
+ `baht-link` · `baht-breadcrumbs` · `baht-tabs` · `baht-avatar` · `baht-code` · `baht-empty-state` · `baht-error-state` ·
354
+ `baht-loading-overlay`
355
+
356
+ ## Theming — design tokens + light DOM
357
+
358
+ Everything renders in light DOM and reads `--baht-*` CSS custom properties — override
359
+ at build time, at runtime, or inject your own sheet entirely:
360
+
361
+ ```css
362
+ .my-app {
363
+ --baht-color-primary: #047857;
364
+ --baht-radius-md: 6px;
365
+ }
366
+ .my-app .baht-label { text-transform: uppercase; } /* your CSS reaches every node */
367
+ ```
368
+
369
+ Styling API: `.baht-form`, `.baht-field`, `.baht-field--w-1-2`, `.baht-field--hidden`, `.baht-label`,
370
+ `.baht-control`, `.baht-error`, `.baht-button`, `.baht-badge` (+ the token list in `tokens.css`).
371
+ Full reference: [docs/theming.md](./docs/theming.md).
372
+
373
+ ## Import only what you use
374
+
375
+ `import '@20baht/ui'` registers every element (~230 KB min). Three lighter routes:
376
+
377
+ ```ts
378
+ // 1. per-element subpath — one module per tag, plus only what it imports
379
+ import '@20baht/ui/components/button'; // <baht-button>
380
+ import { BahtTable } from '@20baht/ui/components/table';
381
+ import '@20baht/ui/components/form'; // <baht-form> + the 15 field primitives
382
+ import '@20baht/ui/components/workflow';
383
+
384
+ // 2. by tag list — each tag is a dynamic import, fetched on demand
385
+ import { registerElements } from '@20baht/ui/register';
386
+ await registerElements(['baht-button', 'baht-avatar']);
387
+ ```
388
+
389
+ ```css
390
+ /* 3. split stylesheets instead of the all-in-one tokens.css (~115 KB) */
391
+ @import '@20baht/ui/css/tokens.css'; /* custom properties only, 18 KB */
392
+ @import '@20baht/ui/css/components.css'; /* .baht-* classes */
393
+ ```
394
+
395
+ `@20baht/ui/tokens.css` = the two sheets above in one import. The calendar is opt-in:
396
+
397
+ ```css
398
+ /* with <baht-datepicker> / date fields — flatpickr's base sheet + the token re-skin */
399
+ @import '@20baht/ui/css/datepicker.css';
400
+ ```
401
+
402
+ flatpickr itself is a **peer dependency** (`npm i flatpickr`) loaded with a dynamic
403
+ `import()` the first time a `<baht-datepicker>` mounts, so apps without date fields never
404
+ bundle it and apps with them get it as its own chunk. `await el.updateComplete` on the
405
+ element resolves once the calendar is attached.
406
+
407
+ **With Native Federation (or any setup that shares packages by name), list `@20baht/engine` in the app's
408
+ own `dependencies`, at the same version as `@20baht/ui`.** The element modules import the engine by its
409
+ package name rather than bundling it, so the elements, `@20baht/ui/engine` and `@20baht/validator`
410
+ share one copy (one locale catalog). Federation shares only the dependencies an app lists: without it the
411
+ import map has no `@20baht/engine`, the build passes, and the browser fails to load the elements.
412
+ A plain Vite, webpack or esbuild build resolves it on its own and needs nothing.
413
+
414
+ ## One install, typed everywhere
415
+
416
+ `npm i @20baht/ui` ships the runtime **and** the metadata every editor/framework needs —
417
+ no hand-written type declarations in your app:
418
+
419
+ | You use | What you get | Setup |
420
+ |---|---|---|
421
+ | **JetBrains / WebStorm** (any framework) | autocomplete + docs for every `<baht-*>` tag | none — `web-types` is auto-detected |
422
+ | **VS Code** (HTML / Angular templates) | tag + attribute completion | one line, see below |
423
+ | **React (TSX)** | full JSX typings, typed props per element | `import '@20baht/ui/react'` once |
424
+ | **Angular** | template binding on properties/events | `CUSTOM_ELEMENTS_SCHEMA`, see below |
425
+ | **Vue 3** | keep Vue from treating `baht-*` as components | `isCustomElement`, see below |
426
+ | **Phoenix / Rails / plain HTML** | it's just HTML — works as-is | none |
427
+ | **Tooling** (Storybook, docgen, custom) | machine-readable API of all 64 elements | read `dist/custom-elements.json` ([CEM standard](https://github.com/webcomponents/custom-elements-manifest)) |
428
+
429
+ **VS Code** — `.vscode/settings.json`:
430
+
431
+ ```json
432
+ { "html.customData": ["./node_modules/@20baht/ui/dist/vscode.html-custom-data.json"] }
433
+ ```
434
+
435
+ **React** — once, in your app entry (or load it globally without a runtime import via
436
+ `"types": ["@20baht/ui/react"]` in `tsconfig.json`):
437
+
438
+ ```ts
439
+ import '@20baht/ui/react'; // JSX typings for every <baht-*> element
440
+ ```
441
+
442
+ React 19+ sets non-string JSX props as DOM properties, so object props (`form`,
443
+ `workflow`, `items`, …) work inline; on React 18 set those via a ref.
444
+
445
+ **Angular** — the compiler must be told `baht-*` tags are custom elements:
446
+
447
+ ```ts
448
+ @Component({ schemas: [CUSTOM_ELEMENTS_SCHEMA], /* … */ })
449
+ ```
450
+
451
+ Bind `readonly` as an attribute (`[attr.readonly]="x ? '' : null"`), not a property — Angular
452
+ rewrites `[readonly]` to the native `readOnly`. Zoneless Angular may connect an element before
453
+ binding its props; since 0.2.3 every field primitive renders empty until `field` arrives. Full
454
+ list of gotchas: [docs/frameworks/angular.md](./docs/frameworks/angular.md#gotchas).
455
+
456
+ **Vue 3** — `vite.config.ts`:
457
+
458
+ ```ts
459
+ vue({ template: { compilerOptions: { isCustomElement: (tag) => tag.startsWith('baht-') } } })
460
+ ```
461
+
462
+ ## Server-side rendering
463
+
464
+ `@20baht/ui/ssr` (Node) renders any Lit template with `@lit-labs/ssr` and moves each
465
+ `baht-*` element's shadow template into its light DOM, so the HTML string it returns is
466
+ exactly what the client would have rendered. `@20baht/ui/hydrate` (browser, imported
467
+ **before** `@20baht/ui`) picks that markup up instead of re-rendering it:
468
+
469
+ ```js
470
+ // server
471
+ import { html } from 'lit';
472
+ import { renderToString } from '@20baht/ui/ssr';
473
+ const page = await renderToString(html`<baht-button variant="primary" label="Save"></baht-button>`);
474
+
475
+ // client — import order matters
476
+ import '@20baht/ui/hydrate';
477
+ import '@20baht/ui';
478
+ ```
479
+
480
+ `@lit-labs/ssr` is an optional peer dependency (server only). Full guide, limitations
481
+ (light-DOM children, ids, i18n locale) and troubleshooting: [docs/ssr.md](./docs/ssr.md).
482
+
483
+ ## Docs
484
+
485
+ - **Per-component docs**: [`docs/`](./docs/README.md) — one .md per element + framework
486
+ guides (vanilla / React / Angular) + theming + SSR.
487
+ - **Docs site with live specimens**: https://bahtui-docs.pages.dev (source: `apps/docs`).
488
+ - **For agents**: the `bahtui-mcp` server (`apps/mcp`) serves these docs and runs the engine on your JSON.
489
+
490
+ ## Field types (22)
491
+
492
+ `text · textarea · markdown · number · currency · email · password · dropdown · multiselect · tags · checkbox · radio ·
493
+ toggle · rating · range · reference · date · time (`HH:mm`) · file · repeater (one level of rows) · label (static) · section (divider)`
494
+
495
+ Each field descriptor: `{ order, type, key, label, placeholder, width: '1/4'|'1/2'|'3/4'|'full',
496
+ value, disabled, required, options | options_from, max_length, min, max, validators[], formatter, flag }`.
497
+
498
+ ## Visual Builder
499
+
500
+ The docs site ships a two-mode Visual Builder (Form mode: palette/WYSIWYG canvas/properties;
501
+ Workflow mode: sequence + rules with a live preview running the real `<baht-workflow>`), with
502
+ Import/Export JSON. Run it from the monorepo: `bun run --filter docs dev` → `/builder`.