tyrell-components 1.0.0-TC9 → 1.0.0-rc.21

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 (392) hide show
  1. package/AGENTS.md +122 -0
  2. package/CHANGELOG.md +1531 -0
  3. package/README.md +71 -53
  4. package/css/tyrell-colors-static.css +1 -0
  5. package/css/tyrell-theme.css +1 -0
  6. package/css/tyrell.css +1 -1783
  7. package/dist/tyrell-colors-static.css +1 -0
  8. package/dist/tyrell-theme.css +1 -0
  9. package/dist/tyrell.css +1 -1783
  10. package/dist/tyrell.js +1 -1
  11. package/guides/AGENT_INSTRUCTIONS.md +124 -0
  12. package/guides/AI_GUIDE.md +53 -0
  13. package/guides/CSS_GUIDE.md +1016 -0
  14. package/guides/DATASTAR_TY_GUIDE.md +657 -0
  15. package/guides/ICONS_GUIDE.md +212 -0
  16. package/guides/TY_GUIDE.md +935 -0
  17. package/guides/clj/CLOJURESCRIPT_GUIDE.md +300 -0
  18. package/guides/clj/CODE_SPLITTING.md +279 -0
  19. package/guides/clj/COMPONENT_GUIDE.md +391 -0
  20. package/guides/clj/HELIX_TY_GUIDE.md +428 -0
  21. package/guides/clj/I18N_GUIDE.md +478 -0
  22. package/guides/clj/LAYOUT_GUIDE.md +273 -0
  23. package/guides/clj/QUICKSTART.md +266 -0
  24. package/guides/clj/REAGENT_TY_GUIDE.md +408 -0
  25. package/guides/clj/REPLICANT_TY_GUIDE.md +623 -0
  26. package/guides/clj/ROUTING_GUIDE.md +346 -0
  27. package/guides/clj/UIX_TY_GUIDE.md +319 -0
  28. package/guides/js/HTMX_TY_GUIDE.md +252 -0
  29. package/guides/js/JAVASCRIPT_GUIDE.md +388 -0
  30. package/guides/js/REACT_TY_GUIDE.md +983 -0
  31. package/guides/js/SVELTE_TY_GUIDE.md +682 -0
  32. package/guides/js/TYCOMPONENT_GUIDE.md +962 -0
  33. package/guides/js/VUE_TY_GUIDE.md +738 -0
  34. package/lib/base/ty-component.d.ts +57 -13
  35. package/lib/base/ty-component.js +266 -292
  36. package/lib/components/button.d.ts +33 -18
  37. package/lib/components/button.js +317 -267
  38. package/lib/components/calendar-month.d.ts +30 -47
  39. package/lib/components/calendar-month.js +455 -429
  40. package/lib/components/calendar-navigation.d.ts +41 -49
  41. package/lib/components/calendar-navigation.js +287 -346
  42. package/lib/components/calendar.d.ts +73 -83
  43. package/lib/components/calendar.js +837 -762
  44. package/lib/components/checkbox.d.ts +26 -75
  45. package/lib/components/checkbox.js +298 -391
  46. package/lib/components/copy.d.ts +20 -60
  47. package/lib/components/copy.js +276 -380
  48. package/lib/components/date-picker.d.ts +100 -183
  49. package/lib/components/date-picker.js +1155 -1570
  50. package/lib/components/file-upload.d.ts +16 -15
  51. package/lib/components/file-upload.js +436 -426
  52. package/lib/components/icon.d.ts +3 -24
  53. package/lib/components/icon.js +141 -230
  54. package/lib/components/input.d.ts +93 -108
  55. package/lib/components/input.js +734 -710
  56. package/lib/components/modal.d.ts +39 -29
  57. package/lib/components/modal.js +419 -438
  58. package/lib/components/option.d.ts +20 -35
  59. package/lib/components/option.js +184 -309
  60. package/lib/components/popup.d.ts +2 -17
  61. package/lib/components/popup.js +353 -347
  62. package/lib/components/radio.d.ts +33 -25
  63. package/lib/components/radio.js +433 -422
  64. package/lib/components/resize-observer.d.ts +3 -30
  65. package/lib/components/resize-observer.js +71 -103
  66. package/lib/components/scroll-container.d.ts +21 -14
  67. package/lib/components/scroll-container.js +292 -234
  68. package/lib/components/select.d.ts +446 -0
  69. package/lib/components/select.js +1381 -0
  70. package/lib/components/selected-tags.d.ts +60 -0
  71. package/lib/components/selected-tags.js +225 -0
  72. package/lib/components/sortable.d.ts +175 -0
  73. package/lib/components/sortable.js +1844 -0
  74. package/lib/components/step.d.ts +1 -6
  75. package/lib/components/step.js +62 -68
  76. package/lib/components/switch.d.ts +15 -15
  77. package/lib/components/switch.js +237 -231
  78. package/lib/components/tab.d.ts +50 -7
  79. package/lib/components/tab.js +203 -69
  80. package/lib/components/tabs.d.ts +19 -64
  81. package/lib/components/tabs.js +600 -618
  82. package/lib/components/tag.d.ts +14 -52
  83. package/lib/components/tag.js +231 -306
  84. package/lib/components/textarea.d.ts +58 -89
  85. package/lib/components/textarea.js +523 -573
  86. package/lib/components/tooltip.d.ts +8 -13
  87. package/lib/components/tooltip.js +322 -409
  88. package/lib/components/wizard.d.ts +7 -54
  89. package/lib/components/wizard.js +376 -606
  90. package/lib/icons/fontawesome/brands.d.ts +0 -1
  91. package/lib/icons/fontawesome/brands.js +0 -8
  92. package/lib/icons/fontawesome/regular.d.ts +0 -1
  93. package/lib/icons/fontawesome/regular.js +0 -8
  94. package/lib/icons/fontawesome/solid.d.ts +0 -1
  95. package/lib/icons/fontawesome/solid.js +0 -8
  96. package/lib/icons/heroicons/micro.d.ts +0 -1
  97. package/lib/icons/heroicons/micro.js +392 -400
  98. package/lib/icons/heroicons/mini.d.ts +0 -1
  99. package/lib/icons/heroicons/mini.js +382 -390
  100. package/lib/icons/heroicons/outline.d.ts +0 -1
  101. package/lib/icons/heroicons/outline.js +337 -345
  102. package/lib/icons/heroicons/solid.d.ts +0 -1
  103. package/lib/icons/heroicons/solid.js +407 -415
  104. package/lib/icons/lucide.d.ts +0 -1
  105. package/lib/icons/lucide.js +24479 -26351
  106. package/lib/icons/material/filled.d.ts +0 -1
  107. package/lib/icons/material/filled.js +9653 -9663
  108. package/lib/icons/material/outlined.d.ts +0 -1
  109. package/lib/icons/material/outlined.js +10271 -10281
  110. package/lib/icons/material/round.d.ts +0 -1
  111. package/lib/icons/material/round.js +10495 -10505
  112. package/lib/icons/material/sharp.d.ts +0 -1
  113. package/lib/icons/material/sharp.js +9905 -9915
  114. package/lib/icons/material/two-tone.d.ts +0 -1
  115. package/lib/icons/material/two-tone.js +12792 -12802
  116. package/lib/index.d.ts +7 -4
  117. package/lib/index.js +26 -39
  118. package/lib/styles/button.d.ts +24 -7
  119. package/lib/styles/button.js +285 -445
  120. package/lib/styles/calendar-month.d.ts +7 -6
  121. package/lib/styles/calendar-month.js +158 -226
  122. package/lib/styles/calendar-navigation.d.ts +2 -6
  123. package/lib/styles/calendar-navigation.js +108 -127
  124. package/lib/styles/calendar.d.ts +3 -3
  125. package/lib/styles/calendar.js +87 -23
  126. package/lib/styles/checkbox.d.ts +7 -6
  127. package/lib/styles/checkbox.js +101 -15
  128. package/lib/styles/copy.d.ts +3 -2
  129. package/lib/styles/copy.js +91 -71
  130. package/lib/styles/custom-scrollbar.d.ts +1 -2
  131. package/lib/styles/custom-scrollbar.js +80 -115
  132. package/lib/styles/date-picker.d.ts +4 -6
  133. package/lib/styles/date-picker.js +321 -388
  134. package/lib/styles/field-size.d.ts +6 -0
  135. package/lib/styles/field-size.js +91 -0
  136. package/lib/styles/file-upload.d.ts +1 -2
  137. package/lib/styles/file-upload.js +143 -188
  138. package/lib/styles/icon.d.ts +2 -6
  139. package/lib/styles/icon.js +92 -170
  140. package/lib/styles/input.d.ts +4 -7
  141. package/lib/styles/input.js +148 -643
  142. package/lib/styles/modal.d.ts +1 -2
  143. package/lib/styles/modal.js +127 -108
  144. package/lib/styles/option.d.ts +2 -6
  145. package/lib/styles/option.js +53 -96
  146. package/lib/styles/popup.d.ts +1 -2
  147. package/lib/styles/popup.js +47 -77
  148. package/lib/styles/radio.d.ts +3 -2
  149. package/lib/styles/radio.js +90 -116
  150. package/lib/styles/resize-observer.d.ts +1 -2
  151. package/lib/styles/resize-observer.js +2 -12
  152. package/lib/styles/scroll-container.d.ts +1 -2
  153. package/lib/styles/scroll-container.js +103 -146
  154. package/lib/styles/select-base.d.ts +8 -0
  155. package/lib/styles/select-base.js +747 -0
  156. package/lib/styles/select.d.ts +11 -0
  157. package/lib/styles/select.js +229 -0
  158. package/lib/styles/sortable.d.ts +16 -0
  159. package/lib/styles/sortable.js +85 -0
  160. package/lib/styles/step.d.ts +1 -2
  161. package/lib/styles/step.js +15 -34
  162. package/lib/styles/switch.d.ts +3 -2
  163. package/lib/styles/switch.js +52 -68
  164. package/lib/styles/tab.d.ts +1 -2
  165. package/lib/styles/tab.js +86 -34
  166. package/lib/styles/tabs.d.ts +3 -11
  167. package/lib/styles/tabs.js +204 -162
  168. package/lib/styles/tag.d.ts +2 -6
  169. package/lib/styles/tag.js +168 -362
  170. package/lib/styles/textarea.d.ts +1 -2
  171. package/lib/styles/textarea.js +238 -306
  172. package/lib/styles/tooltip.d.ts +4 -3
  173. package/lib/styles/tooltip.js +3 -131
  174. package/lib/styles/wizard.d.ts +8 -20
  175. package/lib/styles/wizard.js +306 -295
  176. package/lib/types/common.d.ts +9 -8
  177. package/lib/types/common.js +8 -5
  178. package/lib/utils/calendar-utils.d.ts +49 -65
  179. package/lib/utils/calendar-utils.js +158 -343
  180. package/lib/utils/custom-scrollbar.d.ts +6 -20
  181. package/lib/utils/custom-scrollbar.js +273 -317
  182. package/lib/utils/flavor-sheet.d.ts +31 -0
  183. package/lib/utils/flavor-sheet.js +17 -0
  184. package/lib/utils/icon-registry.d.ts +0 -15
  185. package/lib/utils/icon-registry.js +138 -279
  186. package/lib/utils/icons.d.ts +9 -0
  187. package/lib/utils/icons.js +1 -0
  188. package/lib/utils/loader-registry.d.ts +2 -3
  189. package/lib/utils/loader-registry.js +3 -35
  190. package/lib/utils/locale.d.ts +2 -80
  191. package/lib/utils/locale.js +30 -205
  192. package/lib/utils/mobile.d.ts +0 -1
  193. package/lib/utils/mobile.js +1 -18
  194. package/lib/utils/number-format.d.ts +6 -24
  195. package/lib/utils/number-format.js +53 -136
  196. package/lib/utils/positioning.d.ts +72 -22
  197. package/lib/utils/positioning.js +224 -298
  198. package/lib/utils/property-capture.d.ts +5 -27
  199. package/lib/utils/property-capture.js +36 -144
  200. package/lib/utils/property-manager.d.ts +6 -6
  201. package/lib/utils/property-manager.js +127 -196
  202. package/lib/utils/resize-observer.d.ts +0 -1
  203. package/lib/utils/resize-observer.js +23 -59
  204. package/lib/utils/scroll-lock.d.ts +10 -11
  205. package/lib/utils/scroll-lock.js +165 -173
  206. package/lib/utils/styles.d.ts +0 -6
  207. package/lib/utils/styles.js +17 -48
  208. package/lib/utils/upgrade-properties.d.ts +21 -0
  209. package/lib/utils/upgrade-properties.js +47 -0
  210. package/lib/utils/validity.d.ts +122 -0
  211. package/lib/utils/validity.js +289 -0
  212. package/lib/version.d.ts +1 -2
  213. package/lib/version.js +1 -11
  214. package/package.json +62 -18
  215. package/lib/base/ty-component.d.ts.map +0 -1
  216. package/lib/base/ty-component.js.map +0 -1
  217. package/lib/components/button.d.ts.map +0 -1
  218. package/lib/components/button.js.map +0 -1
  219. package/lib/components/calendar-month.d.ts.map +0 -1
  220. package/lib/components/calendar-month.js.map +0 -1
  221. package/lib/components/calendar-navigation.d.ts.map +0 -1
  222. package/lib/components/calendar-navigation.js.map +0 -1
  223. package/lib/components/calendar.d.ts.map +0 -1
  224. package/lib/components/calendar.js.map +0 -1
  225. package/lib/components/checkbox.d.ts.map +0 -1
  226. package/lib/components/checkbox.js.map +0 -1
  227. package/lib/components/copy.d.ts.map +0 -1
  228. package/lib/components/copy.js.map +0 -1
  229. package/lib/components/date-picker.d.ts.map +0 -1
  230. package/lib/components/date-picker.js.map +0 -1
  231. package/lib/components/dropdown.d.ts +0 -404
  232. package/lib/components/dropdown.d.ts.map +0 -1
  233. package/lib/components/dropdown.js +0 -1563
  234. package/lib/components/dropdown.js.map +0 -1
  235. package/lib/components/file-upload.d.ts.map +0 -1
  236. package/lib/components/file-upload.js.map +0 -1
  237. package/lib/components/icon.d.ts.map +0 -1
  238. package/lib/components/icon.js.map +0 -1
  239. package/lib/components/input.d.ts.map +0 -1
  240. package/lib/components/input.js.map +0 -1
  241. package/lib/components/modal.d.ts.map +0 -1
  242. package/lib/components/modal.js.map +0 -1
  243. package/lib/components/multiselect.d.ts +0 -408
  244. package/lib/components/multiselect.d.ts.map +0 -1
  245. package/lib/components/multiselect.js +0 -1611
  246. package/lib/components/multiselect.js.map +0 -1
  247. package/lib/components/option.d.ts.map +0 -1
  248. package/lib/components/option.js.map +0 -1
  249. package/lib/components/popup.d.ts.map +0 -1
  250. package/lib/components/popup.js.map +0 -1
  251. package/lib/components/radio.d.ts.map +0 -1
  252. package/lib/components/radio.js.map +0 -1
  253. package/lib/components/resize-observer.d.ts.map +0 -1
  254. package/lib/components/resize-observer.js.map +0 -1
  255. package/lib/components/scroll-container.d.ts.map +0 -1
  256. package/lib/components/scroll-container.js.map +0 -1
  257. package/lib/components/step.d.ts.map +0 -1
  258. package/lib/components/step.js.map +0 -1
  259. package/lib/components/switch.d.ts.map +0 -1
  260. package/lib/components/switch.js.map +0 -1
  261. package/lib/components/tab.d.ts.map +0 -1
  262. package/lib/components/tab.js.map +0 -1
  263. package/lib/components/tabs.d.ts.map +0 -1
  264. package/lib/components/tabs.js.map +0 -1
  265. package/lib/components/tag.d.ts.map +0 -1
  266. package/lib/components/tag.js.map +0 -1
  267. package/lib/components/textarea.d.ts.map +0 -1
  268. package/lib/components/textarea.js.map +0 -1
  269. package/lib/components/tooltip.d.ts.map +0 -1
  270. package/lib/components/tooltip.js.map +0 -1
  271. package/lib/components/wizard.d.ts.map +0 -1
  272. package/lib/components/wizard.js.map +0 -1
  273. package/lib/icons/fontawesome/brands.d.ts.map +0 -1
  274. package/lib/icons/fontawesome/brands.js.map +0 -1
  275. package/lib/icons/fontawesome/regular.d.ts.map +0 -1
  276. package/lib/icons/fontawesome/regular.js.map +0 -1
  277. package/lib/icons/fontawesome/solid.d.ts.map +0 -1
  278. package/lib/icons/fontawesome/solid.js.map +0 -1
  279. package/lib/icons/heroicons/micro.d.ts.map +0 -1
  280. package/lib/icons/heroicons/micro.js.map +0 -1
  281. package/lib/icons/heroicons/mini.d.ts.map +0 -1
  282. package/lib/icons/heroicons/mini.js.map +0 -1
  283. package/lib/icons/heroicons/outline.d.ts.map +0 -1
  284. package/lib/icons/heroicons/outline.js.map +0 -1
  285. package/lib/icons/heroicons/solid.d.ts.map +0 -1
  286. package/lib/icons/heroicons/solid.js.map +0 -1
  287. package/lib/icons/lucide.d.ts.map +0 -1
  288. package/lib/icons/lucide.js.map +0 -1
  289. package/lib/icons/material/filled.d.ts.map +0 -1
  290. package/lib/icons/material/filled.js.map +0 -1
  291. package/lib/icons/material/outlined.d.ts.map +0 -1
  292. package/lib/icons/material/outlined.js.map +0 -1
  293. package/lib/icons/material/round.d.ts.map +0 -1
  294. package/lib/icons/material/round.js.map +0 -1
  295. package/lib/icons/material/sharp.d.ts.map +0 -1
  296. package/lib/icons/material/sharp.js.map +0 -1
  297. package/lib/icons/material/two-tone.d.ts.map +0 -1
  298. package/lib/icons/material/two-tone.js.map +0 -1
  299. package/lib/index.d.ts.map +0 -1
  300. package/lib/index.js.map +0 -1
  301. package/lib/styles/button.d.ts.map +0 -1
  302. package/lib/styles/button.js.map +0 -1
  303. package/lib/styles/calendar-month.d.ts.map +0 -1
  304. package/lib/styles/calendar-month.js.map +0 -1
  305. package/lib/styles/calendar-navigation.d.ts.map +0 -1
  306. package/lib/styles/calendar-navigation.js.map +0 -1
  307. package/lib/styles/calendar.d.ts.map +0 -1
  308. package/lib/styles/calendar.js.map +0 -1
  309. package/lib/styles/checkbox.d.ts.map +0 -1
  310. package/lib/styles/checkbox.js.map +0 -1
  311. package/lib/styles/copy.d.ts.map +0 -1
  312. package/lib/styles/copy.js.map +0 -1
  313. package/lib/styles/custom-scrollbar.d.ts.map +0 -1
  314. package/lib/styles/custom-scrollbar.js.map +0 -1
  315. package/lib/styles/date-picker.d.ts.map +0 -1
  316. package/lib/styles/date-picker.js.map +0 -1
  317. package/lib/styles/dropdown.d.ts +0 -12
  318. package/lib/styles/dropdown.d.ts.map +0 -1
  319. package/lib/styles/dropdown.js +0 -1048
  320. package/lib/styles/dropdown.js.map +0 -1
  321. package/lib/styles/file-upload.d.ts.map +0 -1
  322. package/lib/styles/file-upload.js.map +0 -1
  323. package/lib/styles/icon.d.ts.map +0 -1
  324. package/lib/styles/icon.js.map +0 -1
  325. package/lib/styles/input.d.ts.map +0 -1
  326. package/lib/styles/input.js.map +0 -1
  327. package/lib/styles/modal.d.ts.map +0 -1
  328. package/lib/styles/modal.js.map +0 -1
  329. package/lib/styles/multiselect.d.ts +0 -6
  330. package/lib/styles/multiselect.d.ts.map +0 -1
  331. package/lib/styles/multiselect.js +0 -837
  332. package/lib/styles/multiselect.js.map +0 -1
  333. package/lib/styles/option.d.ts.map +0 -1
  334. package/lib/styles/option.js.map +0 -1
  335. package/lib/styles/popup.d.ts.map +0 -1
  336. package/lib/styles/popup.js.map +0 -1
  337. package/lib/styles/radio.d.ts.map +0 -1
  338. package/lib/styles/radio.js.map +0 -1
  339. package/lib/styles/resize-observer.d.ts.map +0 -1
  340. package/lib/styles/resize-observer.js.map +0 -1
  341. package/lib/styles/scroll-container.d.ts.map +0 -1
  342. package/lib/styles/scroll-container.js.map +0 -1
  343. package/lib/styles/step.d.ts.map +0 -1
  344. package/lib/styles/step.js.map +0 -1
  345. package/lib/styles/switch.d.ts.map +0 -1
  346. package/lib/styles/switch.js.map +0 -1
  347. package/lib/styles/tab.d.ts.map +0 -1
  348. package/lib/styles/tab.js.map +0 -1
  349. package/lib/styles/tabs.d.ts.map +0 -1
  350. package/lib/styles/tabs.js.map +0 -1
  351. package/lib/styles/tag.d.ts.map +0 -1
  352. package/lib/styles/tag.js.map +0 -1
  353. package/lib/styles/textarea.d.ts.map +0 -1
  354. package/lib/styles/textarea.js.map +0 -1
  355. package/lib/styles/tooltip.d.ts.map +0 -1
  356. package/lib/styles/tooltip.js.map +0 -1
  357. package/lib/styles/wizard.d.ts.map +0 -1
  358. package/lib/styles/wizard.js.map +0 -1
  359. package/lib/types/common.d.ts.map +0 -1
  360. package/lib/types/common.js.map +0 -1
  361. package/lib/utils/calendar-utils.d.ts.map +0 -1
  362. package/lib/utils/calendar-utils.js.map +0 -1
  363. package/lib/utils/custom-scrollbar.d.ts.map +0 -1
  364. package/lib/utils/custom-scrollbar.js.map +0 -1
  365. package/lib/utils/icon-registry.d.ts.map +0 -1
  366. package/lib/utils/icon-registry.js.map +0 -1
  367. package/lib/utils/loader-registry.d.ts.map +0 -1
  368. package/lib/utils/loader-registry.js.map +0 -1
  369. package/lib/utils/locale.d.ts.map +0 -1
  370. package/lib/utils/locale.js.map +0 -1
  371. package/lib/utils/mobile.d.ts.map +0 -1
  372. package/lib/utils/mobile.js.map +0 -1
  373. package/lib/utils/number-format.d.ts.map +0 -1
  374. package/lib/utils/number-format.js.map +0 -1
  375. package/lib/utils/parse-boolean.d.ts +0 -39
  376. package/lib/utils/parse-boolean.d.ts.map +0 -1
  377. package/lib/utils/parse-boolean.js +0 -58
  378. package/lib/utils/parse-boolean.js.map +0 -1
  379. package/lib/utils/positioning.d.ts.map +0 -1
  380. package/lib/utils/positioning.js.map +0 -1
  381. package/lib/utils/property-capture.d.ts.map +0 -1
  382. package/lib/utils/property-capture.js.map +0 -1
  383. package/lib/utils/property-manager.d.ts.map +0 -1
  384. package/lib/utils/property-manager.js.map +0 -1
  385. package/lib/utils/resize-observer.d.ts.map +0 -1
  386. package/lib/utils/resize-observer.js.map +0 -1
  387. package/lib/utils/scroll-lock.d.ts.map +0 -1
  388. package/lib/utils/scroll-lock.js.map +0 -1
  389. package/lib/utils/styles.d.ts.map +0 -1
  390. package/lib/utils/styles.js.map +0 -1
  391. package/lib/version.d.ts.map +0 -1
  392. package/lib/version.js.map +0 -1
@@ -0,0 +1,428 @@
1
+ # Helix + Tyrell Guide
2
+
3
+ [Helix](https://github.com/lilactown/helix) is a thin macro layer over React with a JSX-feeling API: `defnc` for components, `$` for component instantiation, `(d/div …)` for DOM elements, and `helix.hooks` for the React hooks. Props stay camelCase to match the underlying React contract — Helix doesn't auto-translate prop names. This is the framework Toddler was built on, so if you came from Toddler the muscle memory carries over.
4
+
5
+ Tyrell ships React wrappers via `tyrell.react`, so `($ ty/Input {:onChange h})` works the same way it does in any React-land — and `e.detail.value` is the access path because the wrapper forwards the native `CustomEvent`.
6
+
7
+ For shadow-cljs, CSS, and icon basics, see [CLOJURESCRIPT_GUIDE.md](CLOJURESCRIPT_GUIDE.md). Working example: [`examples/helix/`](../../examples/helix/).
8
+
9
+ ## Setup
10
+
11
+ `deps.edn`:
12
+
13
+ ```clojure
14
+ {:deps {lilactown/helix {:mvn/version "0.2.0"}
15
+ dev.gersak/tyrell {:mvn/version "1.0.0-RC20"}
16
+ dev.gersak/tyrell-icons-lucide {:mvn/version "1.0.0-RC20"}}} ; tyrell.lucide
17
+ ```
18
+
19
+ `tyrell.react` is part of `dev.gersak/tyrell`; install React + the wrapper package via npm:
20
+
21
+ ```bash
22
+ npm install react@18 react-dom@18 tyrell-react
23
+ ```
24
+
25
+ Helix doesn't ship a React DOM render helper of its own — use `react-dom/client` directly:
26
+
27
+ ```clojure
28
+ (:require ["react-dom/client" :as rdom])
29
+ ```
30
+
31
+ Load the CSS:
32
+
33
+ ```html
34
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components/css/tyrell.css">
35
+ <!-- tyrell-theme.css: auto-contrast, seed-based rebranding, themes. See TY_GUIDE.md#quick-start -->
36
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components/css/tyrell-theme.css">
37
+ ```
38
+
39
+ ## Mount
40
+
41
+ ```clojure
42
+ (ns my-app.core
43
+ (:require [tyrell.components] ; side-effect: registers all <ty-*> elements
44
+ [tyrell.react :as ty]
45
+ [tyrell.icons :as icons]
46
+ [tyrell.lucide :as lucide]
47
+ [helix.core :refer [defnc $ <>]]
48
+ [helix.dom :as d]
49
+ [helix.hooks :as hooks]
50
+ ["react-dom/client" :as rdom]))
51
+
52
+ (defnc app []
53
+ (d/div {:class "ty-canvas min-h-screen p-8"}
54
+ ($ ty/Button {:flavor "primary"} "Hello")))
55
+
56
+ (defonce root
57
+ (rdom/createRoot (.getElementById js/document "app")))
58
+
59
+ (defn render! []
60
+ (.render root ($ app)))
61
+
62
+ (defn ^:export init []
63
+ (icons/register! {:check lucide/check})
64
+ (render!))
65
+
66
+ (defn ^:after-load reload []
67
+ (render!))
68
+ ```
69
+
70
+ `defonce` on the root is mandatory for hot reload — recreating the React root on every save throws.
71
+
72
+ ## Components — `defnc`, `$`, `d/`
73
+
74
+ Helix splits the syntax cleanly:
75
+
76
+ - `(defnc my-comp [props] …)` defines a function component. `props` is a CLJS map you destructure with `{:keys [...]}`.
77
+ - `($ Component {…} children)` creates an element from a component (Helix's own `defnc` components, or React components like `tyrell.react/Button`).
78
+ - `(d/div {…} children)` creates a DOM element. Each HTML tag has a corresponding `d/` function — `d/section`, `d/form`, `d/label`, etc.
79
+
80
+ ```clojure
81
+ (defnc labeled-input [{:keys [label value onChange]}]
82
+ (d/div {:class "flex flex-col gap-1"}
83
+ (d/label {:class "ty-text+"} label)
84
+ ($ ty/Input {:value value :onChange onChange})))
85
+
86
+ (defnc form []
87
+ (let [[email setEmail] (hooks/use-state "")]
88
+ ($ labeled-input
89
+ {:label "Email"
90
+ :value email
91
+ :onChange #(setEmail (.. % -detail -value))})))
92
+ ```
93
+
94
+ **Props are camelCase.** Helix does *not* convert `:on-change` → `onChange` for you. Write the React-native form:
95
+
96
+ ```clojure
97
+ ($ ty/Input {:onChange handler ; not :on-change
98
+ :className "w-full" ; not :class on $-components for React
99
+ :value v})
100
+ ```
101
+
102
+ For DOM elements via `d/`, you can use `:class` (Helix's `d/` macros do convert it to `className` under the hood) and either case form for events — Helix accepts `:on-click` on `d/button`. The asymmetry is jarring at first; the rule is: **`d/*` forgives, `$ Component` doesn't.**
103
+
104
+ ## State — `helix.hooks`
105
+
106
+ `helix.hooks` mirrors React's hook API. The setter naming convention in the example uses `setX` (camelCase, JS-style) rather than `set-x`, matching the JSX feel:
107
+
108
+ ```clojure
109
+ (defnc counter []
110
+ (let [[n setN] (hooks/use-state 0)]
111
+ (d/div {:class "flex items-center gap-2"}
112
+ ($ ty/Button {:flavor "primary" :onClick #(setN inc)} "Inc")
113
+ (d/span {:class "ty-text++ text-xl"} n))))
114
+ ```
115
+
116
+ Side effects — `helix.hooks/use-effect` takes a deps vector first, body second (opposite of UIx, which takes the function first):
117
+
118
+ ```clojure
119
+ (hooks/use-effect [n]
120
+ (set! (.-title js/document) (str "Count: " n))
121
+ ;; Return cleanup, if any
122
+ (fn [] (js/console.log "unmount")))
123
+ ```
124
+
125
+ Helix has a useful shortcut — `:auto-deps` — that lets the macro infer the dependency vector from referenced symbols:
126
+
127
+ ```clojure
128
+ (hooks/use-callback :auto-deps
129
+ (fn [k v]
130
+ (setProfile #(assoc % k v))))
131
+ ```
132
+
133
+ `use-ref`, `use-memo`, `use-callback`, `use-context` all live in `helix.hooks`. Because `helix.hooks` is a namespace and not magic, you'll also see `(:require [helix.hooks :as hooks])` in real code.
134
+
135
+ ## Event handling — `event.detail.value`
136
+
137
+ The wrapper hands you the native `CustomEvent`:
138
+
139
+ ```clojure
140
+ ($ ty/Input
141
+ {:label "Email"
142
+ :type "email"
143
+ :value (:email profile)
144
+ :error (:email errors)
145
+ :onChange #(setProfile (fn [p] (assoc p :email (.. % -detail -value))))}
146
+ ($ ty/Icon {:slot "start" :name "mail"}))
147
+ ```
148
+
149
+ | Component | Access |
150
+ |---|---|
151
+ | `ty/Input`, `ty/Textarea`, `ty/Switch`, `ty/DatePicker` | `(.. e -detail -value)` |
152
+ | `ty/Checkbox` | `(.. e -detail -checked)` |
153
+ | `ty/Select` | `(.. e -detail -value)`; with `:multiple`, `(.. e -detail -values)` → JS array |
154
+ | `ty/RadioGroup` | `(.. e -detail -value)` |
155
+ | `ty/Tabs` | `(.. e -detail -tab)` |
156
+ | `ty/Sortable` | `(.. e -detail -value)` → `{key, group, source, from, to, order}` |
157
+
158
+ For `Select` with `:multiple`, convert the JS array:
159
+
160
+ ```clojure
161
+ :onChange (fn [^js e]
162
+ (let [vs (.. e -detail -values)]
163
+ (setSkills (vec vs))))
164
+ ```
165
+
166
+ ## Composition — `$ ty/X` with slotted children
167
+
168
+ Children come after the props map. `:slot` tells the host component where to render them:
169
+
170
+ ```clojure
171
+ ($ ty/Input
172
+ {:label "Search"
173
+ :value q
174
+ :onChange #(setQ (.. % -detail -value))}
175
+ ($ ty/Icon {:slot "start" :name "search"}))
176
+
177
+ ($ ty/Select
178
+ {:label "Country"
179
+ :value country
180
+ :onChange #(setCountry (.. % -detail -value))}
181
+ ($ ty/Option {:value "us"} "United States")
182
+ ($ ty/Option {:value "de"} "Germany"))
183
+
184
+ ($ ty/Select
185
+ {:label "Skills"
186
+ :multiple true
187
+ :value (str/join "," skills)
188
+ :onChange #(setSkills (vec (.. % -detail -values)))}
189
+ ($ ty/Option {:value "clojure" :flavor "primary"} "Clojure")
190
+ ($ ty/Option {:value "react" :flavor "primary"} "React"))
191
+ ```
192
+
193
+ `<>` from `helix.core` gives you a fragment when you need to return siblings without a wrapper:
194
+
195
+ ```clojure
196
+ (defnc badges [{:keys [items]}]
197
+ (<>
198
+ (for [i items]
199
+ ($ ty/Tag {:key (:id i) :value (:value i)} (:label i)))))
200
+ ```
201
+
202
+ ## Refs — modal control
203
+
204
+ `use-ref` returns an object with a `.current` property — same as React. The wrapper forwards refs to the underlying custom element, so `.show()` / `.hide()` are available:
205
+
206
+ ```clojure
207
+ (defnc modal-demo []
208
+ (let [modal-ref (hooks/use-ref nil)
209
+ open-modal (hooks/use-callback :auto-deps
210
+ (fn [_]
211
+ (when-let [^js m (.-current modal-ref)]
212
+ (.show m))))
213
+ close-modal (hooks/use-callback :auto-deps
214
+ (fn [_]
215
+ (when-let [^js m (.-current modal-ref)]
216
+ (.hide m))))]
217
+ (d/div nil
218
+ ($ ty/Button {:flavor "primary" :onClick open-modal} "Open")
219
+ ($ ty/Modal {:ref modal-ref}
220
+ (d/div {:class "ty-elevated p-6 rounded-2xl"}
221
+ (d/h3 {:class "ty-text++"} "Hello")
222
+ ($ ty/Button {:onClick close-modal} "Close"))))))
223
+ ```
224
+
225
+ The `^js` type hint on the destructured ref helps the compiler skip externs for `.show` / `.hide`.
226
+
227
+ ## Forms — controlled, with form-association
228
+
229
+ Tyrell's form-associated components participate in `<form>` submission via `setFormValue()`. Wrap them in `d/form` and listen for `:onSubmit`:
230
+
231
+ ```clojure
232
+ (def empty-profile
233
+ {:name "" :email "" :role "" :news? false})
234
+
235
+ (defn validate [p]
236
+ (cond-> {}
237
+ (str/blank? (:email p))
238
+ (assoc :email "Email is required")
239
+
240
+ (and (not (str/blank? (:email p)))
241
+ (not (re-matches #".+@.+\..+" (:email p))))
242
+ (assoc :email "Doesn't look like an email")))
243
+
244
+ (defnc signup-form []
245
+ (let [[profile setProfile] (hooks/use-state empty-profile)
246
+ [errors setErrors] (hooks/use-state {})
247
+ update-field (hooks/use-callback :auto-deps
248
+ (fn [k v]
249
+ (setProfile #(assoc % k v))
250
+ (setErrors #(dissoc % k))))
251
+ on-submit (hooks/use-callback [profile]
252
+ (fn [^js e]
253
+ (.preventDefault e)
254
+ (let [errs (validate profile)]
255
+ (setErrors errs)
256
+ (when (empty? errs)
257
+ (js/console.log "submit:" (clj->js profile))))))]
258
+ (d/form {:onSubmit on-submit
259
+ :class "ty-elevated p-6 rounded-lg flex flex-col gap-4"}
260
+ ($ ty/Input
261
+ {:label "Email"
262
+ :name "email"
263
+ :type "email"
264
+ :required true
265
+ :value (:email profile)
266
+ :error (:email errors)
267
+ :onChange #(update-field :email (.. % -detail -value))})
268
+
269
+ ($ ty/Select
270
+ {:label "Role"
271
+ :name "role"
272
+ :value (:role profile)
273
+ :onChange #(update-field :role (.. % -detail -value))}
274
+ ($ ty/Option {:value "developer"} "Developer")
275
+ ($ ty/Option {:value "designer"} "Designer"))
276
+
277
+ (d/label {:class "flex items-center gap-2 cursor-pointer"}
278
+ ($ ty/Checkbox
279
+ {:name "news"
280
+ :checked (:news? profile)
281
+ :onChange #(update-field :news? (.. % -detail -checked))})
282
+ "Subscribe to newsletter")
283
+
284
+ ($ ty/Button {:type "submit" :flavor "primary"} "Submit"))))
285
+ ```
286
+
287
+ This is essentially the structure of [`examples/helix/src/hello/core.cljs`](../../examples/helix/src/hello/core.cljs) — clone the example to see the same pattern at full scale, including a multiple Select for skills, a DatePicker, a Tooltip, and the imperative-ref modal.
288
+
289
+ ## Subscribing to non-React state
290
+
291
+ Helix's hooks-first model means non-React atoms (e.g. `tyrell.router/*router*`) need explicit subscription. Same shape as the UIx hook:
292
+
293
+ ```clojure
294
+ (defn use-watch [a]
295
+ (let [[v setV] (hooks/use-state @a)]
296
+ (hooks/use-effect [a]
297
+ (let [k (gensym "helix-watch")]
298
+ (add-watch a k (fn [_ _ _ new] (setV new)))
299
+ (fn [] (remove-watch a k))))
300
+ v))
301
+
302
+ (defnc current-route []
303
+ (let [router (use-watch tyrell.router/*router*)]
304
+ (d/div {:class "ty-text-"} (str "Current: " (:current router)))))
305
+ ```
306
+
307
+ ## Icons
308
+
309
+ ```clojure
310
+ (ns my-app.icons
311
+ (:require [tyrell.icons :as icons]
312
+ [tyrell.lucide :as lucide]))
313
+
314
+ (icons/register! {:check lucide/check
315
+ :user lucide/user}) ; the key is the name
316
+ ```
317
+
318
+ Then `($ ty/Icon {:name "check" :size "sm"})`. The registry is global, so one call at init is enough.
319
+
320
+ Sets, tree-shaking, custom SVGs and troubleshooting: [ICONS_GUIDE.md](../ICONS_GUIDE.md#in-clojure).
321
+
322
+ ## Calendar and wizard
323
+
324
+ ### ty-calendar
325
+
326
+ ```clojure
327
+ (defnc calendar-demo []
328
+ (let [now (js/Date.)
329
+ [[year month day] set-date]
330
+ (hooks/use-state [(.getFullYear now)
331
+ (inc (.getMonth now))
332
+ nil])]
333
+ (d/div {:class "flex flex-col gap-4"}
334
+ ($ ty/Calendar
335
+ {:year year
336
+ :month month
337
+ :day day
338
+ :onChange (fn [^js e]
339
+ (set-date [(.. e -detail -year)
340
+ (.. e -detail -month)
341
+ (.. e -detail -day)]))})
342
+ (when day
343
+ (d/p {:class "ty-text-"}
344
+ (str "Selected: " year "-" month "-" day))))))
345
+ ```
346
+
347
+ Event detail: `{ year, month, day, action, source }`. Form value is ISO `YYYY-MM-DD` when wrapped in `d/form` with a `name` attribute.
348
+
349
+ ### ty-wizard
350
+
351
+ ```clojure
352
+ (defnc wizard-demo []
353
+ (let [[step setStep] (hooks/use-state "info")
354
+ [completed setCompleted] (hooks/use-state [])
355
+ advance (hooks/use-callback :auto-deps
356
+ (fn [next-id]
357
+ (setCompleted #(conj % step))
358
+ (setStep next-id)))]
359
+ ($ ty/Wizard
360
+ {:height "400px"
361
+ :active step
362
+ :completed (str/join "," completed)}
363
+ ($ ty/Step {:id "info" :label "Info"}
364
+ (d/div {:class "p-6 flex flex-col gap-4"}
365
+ ($ ty/Input {:label "Name" :required true})
366
+ ($ ty/Button {:flavor "primary"
367
+ :onClick #(advance "review")} "Next")))
368
+ ($ ty/Step {:id "review" :label "Review"}
369
+ (d/div {:class "p-6 flex gap-2"}
370
+ ($ ty/Button {:onClick #(setStep "info")} "Back")
371
+ ($ ty/Button {:flavor "success"
372
+ :onClick #(advance "done")} "Finish")))
373
+ ($ ty/Step {:id "done" :label "Done"}
374
+ (d/div {:class "p-6"} "All done!")))))
375
+ ```
376
+
377
+ Event detail: `{ activeId, activeIndex, previousId, previousIndex, direction }`.
378
+
379
+ ## Reorderable lists (ty-sortable)
380
+
381
+ `ty/Sortable` never moves its children. A drop (or a keyboard move) calls `:onChange` (`ty-sortable-change`) on the destination list, and the list holds the result on screen until React renders the items in the new order. Give each item a `:key` and a `:data-key` (or `:id`):
382
+
383
+ ```clojure
384
+ (defnc board []
385
+ (let [[cols setCols] (hooks/use-state {"todo" ["a" "b"] "done" ["c"]})
386
+ [saving? setSaving] (hooks/use-state false)
387
+ on-move (fn [^js e]
388
+ (let [value (.. e -detail -value)]
389
+ (setSaving true)
390
+ (-> (save value)
391
+ (.then #(setCols (fn [c] (merge c (js->clj (.-order value))))))
392
+ (.finally #(setSaving false))))) ; order unchanged: snaps back
393
+ column (fn [id label]
394
+ ($ ty/Sortable {:key id :id id :group "board" :label label
395
+ :aria-busy (when saving? "true")
396
+ :onChange on-move}
397
+ (for [k (get cols id)]
398
+ (d/div {:key k :data-key k}
399
+ (d/button {:type "button" :data-handle "" :aria-label (str "Move " k)}
400
+ ($ ty/Icon {:name "grip-vertical"}))
401
+ k))))]
402
+ (<> (column "todo" "To do") (column "done" "Done"))))
403
+ ```
404
+
405
+ - `order` is the new key order of each list the move touched, by list id, so one `merge` renders both lists. For fractional ranking, save a rank between `(.. value -to -prev)` and `(.. value -to -next)` instead.
406
+ - `:aria-busy` while saving makes a refused save snap back as soon as it clears. Without it, call `(.settle (.. e -detail -toContainer) "rejected")`, or `(.preventDefault e)` to reject at once.
407
+ - On touch, a `:data-handle` drags at once and leaves the rest of the row to scroll; give it a 44px target. Without a handle the whole item drags after a 250 ms press.
408
+ - Props (camelCase, as for every `$` wrapper): `:group`, `:axis`, `:handle`, `:accepts`, `:disabled`, `:keyAttr`, `:holdTimeout`, `:label`, `:canDrop`, `:labels`, and `:onStart` / `:onCancel` / `:onSettle`.
409
+
410
+ ---
411
+
412
+ ## Common pitfalls
413
+
414
+ - **camelCase props on `$ Component`** — `:on-click` on a Tyrell wrapper component **does nothing**. It must be `:onClick`. Helix passes props through verbatim. The compiler won't warn.
415
+ - **`:class` on `$ Component`** — same rule: `:className` is the React prop name. `d/*` macros translate `:class`, but `$` does not.
416
+ - **`use-effect` deps are first, body is rest** — opposite of UIx. `(hooks/use-effect [n] body…)`. Easy to flip.
417
+ - **`:auto-deps` is a literal keyword** — not a value the macro infers. Pass `:auto-deps` as the *first* argument to `use-effect` / `use-callback` / `use-memo` to let Helix derive the dep vector by static analysis. Use it when the deps are obvious; provide an explicit vector when they aren't.
418
+ - **Don't pass CLJS data structures as wrapper props** unless you know the wrapper accepts them. `Select`'s `:value` with `:multiple` expects a comma string or JS array, not a CLJS vector.
419
+ - **Children of `Select`** must be `ty/Option` (or raw `<ty-option>`) — not native HTML `<option>`s or `ty/Tag`. The selection is the select's `:value`; `:selected` on an option does nothing without `:externalSelection`.
420
+ - **Setter naming is just convention** — `setProfile` vs `set-profile`. The example uses camelCase to match the JS-React feel; both compile.
421
+
422
+ ## See also
423
+
424
+ - [QUICKSTART.md](QUICKSTART.md) — Track A entry point
425
+ - [CLOJURESCRIPT_GUIDE.md](CLOJURESCRIPT_GUIDE.md) — substrate (deps, CSS, shadow-cljs)
426
+ - [UIX_TY_GUIDE.md](UIX_TY_GUIDE.md) — same wrappers, kebab-case props, auto camelCase translation
427
+ - [REAGENT_TY_GUIDE.md](REAGENT_TY_GUIDE.md) — same wrappers, hiccup-and-`r/atom` model
428
+ - [`examples/helix/`](../../examples/helix/) — single-file demo: form, modal, tooltip, multiselect, live-state pane