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,408 @@
1
+ # Reagent + Tyrell Guide
2
+
3
+ Reagent's model is hiccup vectors and reactive atoms. Components are plain `defn`, instantiated with `[my-comp props]`, and React interop happens through the `:>` reader. State lives in `r/atom`s — derefing one inside a component subscribes that component to changes.
4
+
5
+ This guide focuses on what's specific to Reagent + Tyrell. For shadow-cljs, CSS, and icon basics, see [CLOJURESCRIPT_GUIDE.md](CLOJURESCRIPT_GUIDE.md). Working example: [`examples/reagent/`](../../examples/reagent/).
6
+
7
+ ## Setup
8
+
9
+ `deps.edn`:
10
+
11
+ ```clojure
12
+ {:deps {reagent/reagent {:mvn/version "1.2.0"}
13
+ dev.gersak/tyrell {:mvn/version "1.0.0-RC20"}
14
+ dev.gersak/tyrell-icons-lucide {:mvn/version "1.0.0-RC20"}}} ; tyrell.lucide
15
+ ```
16
+
17
+ `tyrell.react` ships inside `dev.gersak/tyrell` and re-exports the npm wrappers. The npm package isn't auto-pulled — install it explicitly:
18
+
19
+ ```bash
20
+ npm install react@18 react-dom@18 tyrell-react
21
+ ```
22
+
23
+ Reagent 1.2 supports React 18 via `reagent.dom.client`. If you're on Reagent <1.2, upgrade — the older `reagent.dom/render` API is deprecated.
24
+
25
+ Load the CSS:
26
+
27
+ ```html
28
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components/css/tyrell.css">
29
+ <!-- tyrell-theme.css: auto-contrast, seed-based rebranding, themes. See TY_GUIDE.md#quick-start -->
30
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components/css/tyrell-theme.css">
31
+ ```
32
+
33
+ ## Mount — React 18 + Reagent
34
+
35
+ ```clojure
36
+ (ns my-app.core
37
+ (:require [tyrell.components] ; side-effect: registers all <ty-*> elements
38
+ [tyrell.react :as ty]
39
+ [tyrell.icons :as icons]
40
+ [tyrell.lucide :as lucide]
41
+ [reagent.core :as r]
42
+ [reagent.dom.client :as rdom]))
43
+
44
+ (defn app []
45
+ [:div.ty-canvas.min-h-screen.p-8
46
+ [:> ty/Button {:flavor "primary"} "Hello"]])
47
+
48
+ (defonce root
49
+ (rdom/create-root (.getElementById js/document "app")))
50
+
51
+ (defn render! []
52
+ (rdom/render root [app]))
53
+
54
+ (defn ^:export init []
55
+ (icons/register! {:check lucide/check})
56
+ (render!))
57
+
58
+ (defn ^:after-load reload []
59
+ (render!))
60
+ ```
61
+
62
+ `defonce` keeps the root stable across reloads. The vector form `[app]` is what Reagent expects — not `(app)` and not React elements; Reagent converts hiccup to React internally.
63
+
64
+ ## Components — plain functions, hiccup vectors
65
+
66
+ A Reagent component is a function returning hiccup. Call it with a vector:
67
+
68
+ ```clojure
69
+ (defn labeled-input [{:keys [label value on-change]}]
70
+ [:div.flex.flex-col.gap-1
71
+ [:label.ty-text+ label]
72
+ [:> ty/Input {:value value :onChange on-change}]])
73
+
74
+ (defn form []
75
+ (let [email (r/atom "")]
76
+ (fn [] ; Form-2: returns the render fn
77
+ [:div
78
+ [labeled-input
79
+ {:label "Email"
80
+ :value @email
81
+ :on-change #(reset! email (.. % -detail -value))}]])))
82
+ ```
83
+
84
+ Reagent has three component shapes:
85
+
86
+ - **Form-1** — `(defn x [] [:div])` — pure render. Re-runs on every prop change.
87
+ - **Form-2** — `(defn x [] (let [a (r/atom 0)] (fn [] [:div @a])))` — outer `let` runs once for setup; inner fn is the render. Use this when you need component-local state.
88
+ - **Form-3** — `r/create-class` with explicit lifecycle methods. Rarely needed; mostly use form-2 or form-1 with `r/with-let`.
89
+
90
+ For most Tyrell-driven UIs, form-2 with a local `r/atom` is the workhorse for unsaved-edit state, modal toggles, etc.
91
+
92
+ ## Props — kebab-case for hiccup, camelCase for `:>` interop
93
+
94
+ Reagent normalizes `:on-change` → `onChange` for **HTML elements** in hiccup (`[:input {:on-change …}]`). But when you cross into React-component territory via `:>`, **you write camelCase yourself** — Reagent doesn't transform props that pass through `:>`:
95
+
96
+ ```clojure
97
+ ;; HTML element — kebab-case is fine, Reagent converts it
98
+ [:button {:on-click handler} "Click"]
99
+
100
+ ;; React component via :> — write camelCase explicitly
101
+ [:> ty/Input {:onChange handler ; ← camelCase!
102
+ :className "w-full" ; ← className, not :class
103
+ :value @v}]
104
+ ```
105
+
106
+ This is the most common Reagent + Tyrell mistake. Look at any working file and you'll see `:onChange`, `:onClick`, `:className` everywhere wrappers are involved. The `examples/reagent/` source uses this convention throughout.
107
+
108
+ ## State — `r/atom`s and reactivity
109
+
110
+ Deref a reagent atom inside a component, and the component re-renders when it changes:
111
+
112
+ ```clojure
113
+ (defonce form-state
114
+ (r/atom {:email "" :role "" :errors {}}))
115
+
116
+ (defn email-field []
117
+ (let [{:keys [email errors]} @form-state] ; deref → subscribe
118
+ [:> ty/Input
119
+ {:label "Email"
120
+ :type "email"
121
+ :value email
122
+ :error (:email errors)
123
+ :onChange (fn [e]
124
+ (let [v (.. e -detail -value)]
125
+ (swap! form-state assoc :email v)
126
+ (swap! form-state update :errors
127
+ (fn [errs]
128
+ (if (re-find #"@" v)
129
+ (dissoc errs :email)
130
+ (assoc errs :email "Looks invalid"))))))}]))
131
+ ```
132
+
133
+ `r/track` and reactions (`r/reaction`) give you derived values that re-compute lazily. For most Tyrell forms, plain `swap!` + a single atom is enough.
134
+
135
+ ## Event handling — `event.detail.value`
136
+
137
+ `tyrell.react` wrappers attach `addEventListener` on the underlying custom element and pass the native `CustomEvent` through to your handler. Access the payload off `.-detail`:
138
+
139
+ ```clojure
140
+ [:> ty/Input
141
+ {:label "Email"
142
+ :value @email
143
+ :onChange #(reset! email (.. % -detail -value))}]
144
+
145
+ [:> ty/Checkbox
146
+ {:checked @subscribed?
147
+ :onChange #(reset! subscribed? (.. % -detail -checked))}]
148
+
149
+ [:> ty/Select
150
+ {:multiple true
151
+ :value (str/join "," @skills)
152
+ :onChange (fn [^js e]
153
+ (reset! skills (vec (.. e -detail -values))))}
154
+ [:> ty/Option {:value "clojure" :flavor "primary"} "Clojure"]
155
+ [:> ty/Option {:value "react" :flavor "primary"} "React"]]
156
+ ```
157
+
158
+ | Component | Access |
159
+ |---|---|
160
+ | `ty/Input`, `ty/Textarea`, `ty/Switch`, `ty/DatePicker` | `(.. e -detail -value)` |
161
+ | `ty/Checkbox` | `(.. e -detail -checked)` |
162
+ | `ty/Select` | `(.. e -detail -value)`; with `:multiple`, `(.. e -detail -values)` → JS array |
163
+ | `ty/RadioGroup` | `(.. e -detail -value)` |
164
+ | `ty/Tabs` | `(.. e -detail -tab)` |
165
+ | `ty/Sortable` | `(.. e -detail -value)` → `{key, group, source, from, to, order}` |
166
+
167
+ ## Composition — children with slots
168
+
169
+ Pass children after the props map in the same hiccup vector. Use `:slot` on Tyrell icon children:
170
+
171
+ ```clojure
172
+ [:> ty/Input
173
+ {:label "Search" :value @q
174
+ :onChange #(reset! q (.. % -detail -value))}
175
+ [:> ty/Icon {:slot "start" :name "search"}]]
176
+
177
+ [:> ty/Select
178
+ {:label "Country" :value @country
179
+ :onChange #(reset! country (.. % -detail -value))}
180
+ [:> ty/Option {:value "us"} "United States"]
181
+ [:> ty/Option {:value "de"} "Germany"]]
182
+ ```
183
+
184
+ ## Refs — modal control
185
+
186
+ `use-state`-style hooks aren't idiomatic Reagent. For imperative refs on `ty-modal` / `ty-popup`, the `:ref` prop accepts a callback:
187
+
188
+ ```clojure
189
+ (defn modal-demo []
190
+ (let [modal-el (r/atom nil)]
191
+ (fn []
192
+ [:div
193
+ [:> ty/Button
194
+ {:flavor "primary"
195
+ :onClick #(some-> @modal-el (.show))}
196
+ "Open"]
197
+ [:> ty/Modal
198
+ {:ref #(reset! modal-el %)}
199
+ [:div.ty-elevated.p-6.rounded-2xl
200
+ [:h3.ty-text++ "Hello"]
201
+ [:> ty/Button
202
+ {:onClick #(some-> @modal-el (.hide))}
203
+ "Close"]]]])))
204
+ ```
205
+
206
+ Storing the DOM node in an atom isn't reactive in the usual sense (you don't deref it inside render), but it gives you a stable handle for imperative calls.
207
+
208
+ ## Forms — `<form>` + Tyrell's form-association
209
+
210
+ Every form-associated Tyrell component (`ty/Input`, `ty/Textarea`, `ty/Checkbox`, `ty/Switch`, `ty/RadioGroup`, `ty/Select`, `ty/DatePicker`) calls `setFormValue()` internally. A wrapping `<form>` with an `onSubmit` handler picks them up:
211
+
212
+ ```clojure
213
+ (defn signup-form []
214
+ (let [profile (r/atom {:email "" :role "" :news? false :errors {}})]
215
+ (fn []
216
+ (let [{:keys [email role news? errors]} @profile
217
+ update-field (fn [k v]
218
+ (swap! profile assoc k v)
219
+ (swap! profile update :errors dissoc k))
220
+ on-submit (fn [^js e]
221
+ (.preventDefault e)
222
+ (js/console.log "submit:" (clj->js @profile)))]
223
+ [:form {:on-submit on-submit
224
+ :class "ty-elevated p-6 rounded-lg flex flex-col gap-4"}
225
+ [:> ty/Input
226
+ {:label "Email" :name "email" :type "email" :required true
227
+ :value email :error (:email errors)
228
+ :onChange #(update-field :email (.. % -detail -value))}]
229
+ [:> ty/Select
230
+ {:label "Role" :name "role" :value role
231
+ :onChange #(update-field :role (.. % -detail -value))}
232
+ [:> ty/Option {:value "developer"} "Developer"]
233
+ [:> ty/Option {:value "designer"} "Designer"]]
234
+ [:label.flex.items-center.gap-2.cursor-pointer
235
+ [:> ty/Checkbox
236
+ {:name "news" :checked news?
237
+ :onChange #(update-field :news? (.. % -detail -checked))}]
238
+ "Subscribe to newsletter"]
239
+ [:> ty/Button {:type "submit" :flavor "primary"} "Submit"]]))))
240
+ ```
241
+
242
+ The `[:form …]` element here is HTML, so `:on-submit` (kebab) is correct; the Tyrell components inside use `:onChange` (camel) because they're routed through `:>`.
243
+
244
+ ## Subscribing to non-Reagent atoms
245
+
246
+ Tyrell's router state lives in a non-Reagent atom (`tyrell.router/*router*`). Reagent doesn't auto-subscribe to it — but a one-line trick makes it reactive: deref it inside the component, *and* derefing a regular atom inside a Reagent component triggers re-render only if Reagent considers it reactive (it doesn't, by default). Two patterns work:
247
+
248
+ **A. Wrap the foreign atom in a Reagent ratom mirror** — keep them in sync via `add-watch`:
249
+
250
+ ```clojure
251
+ (defonce router-state (r/atom @tyrell.router/*router*))
252
+
253
+ (defonce _watch
254
+ (add-watch tyrell.router/*router* ::mirror
255
+ (fn [_ _ _ new] (reset! router-state new))))
256
+ ```
257
+
258
+ Then `[:span @router-state]` re-renders normally.
259
+
260
+ **B. Re-render the whole tree on watch** — what `examples/reagent/` does:
261
+
262
+ ```clojure
263
+ (defn render! []
264
+ (rdom/render root [main-layout]))
265
+
266
+ (defn init []
267
+ ;; …
268
+ (add-watch tyrell.router/*router* ::render
269
+ (fn [_ _ _ _] (render!))))
270
+ ```
271
+
272
+ This is heavier but simpler — fine for small apps. For larger apps, pattern A is cleaner.
273
+
274
+ ## Icons
275
+
276
+ ```clojure
277
+ (ns my-app.icons
278
+ (:require [tyrell.icons :as icons]
279
+ [tyrell.lucide :as lucide]))
280
+
281
+ (icons/register! {:check lucide/check
282
+ :user lucide/user}) ; the key is the name
283
+ ```
284
+
285
+ Then `[:> ty/Icon {:name "check"}]`, or `[:ty-icon {:name "check"}]` for a render-only icon.
286
+
287
+ Sets, tree-shaking, custom SVGs and troubleshooting: [ICONS_GUIDE.md](../ICONS_GUIDE.md#in-clojure).
288
+
289
+ ## Calendar and wizard
290
+
291
+ ### ty-calendar
292
+
293
+ ```clojure
294
+ (defn calendar-demo []
295
+ (let [now (js/Date.)
296
+ sel (r/atom {:year (.getFullYear now)
297
+ :month (inc (.getMonth now))
298
+ :day nil})]
299
+ (fn []
300
+ (let [{:keys [year month day]} @sel]
301
+ [:div.flex.flex-col.gap-4
302
+ [:> ty/Calendar
303
+ {:year year
304
+ :month month
305
+ :day day
306
+ :onChange (fn [^js e]
307
+ (reset! sel {:year (.. e -detail -year)
308
+ :month (.. e -detail -month)
309
+ :day (.. e -detail -day)}))}]
310
+ (when day
311
+ [:p.ty-text- (str "Selected: " year "-" (when (< month 10) "0") month "-" (when (< day 10) "0") day)])]))))
312
+ ```
313
+
314
+ Event detail: `{ year, month, day, action, source }`. Form value is ISO `YYYY-MM-DD` when wrapped in `<form>` with a `name` attribute.
315
+
316
+ ### ty-wizard
317
+
318
+ ```clojure
319
+ (defn wizard-demo []
320
+ (let [step (r/atom "info")
321
+ completed (r/atom [])]
322
+ (fn []
323
+ (let [advance #(do (swap! completed conj @step)
324
+ (reset! step %))]
325
+ [:> ty/Wizard
326
+ {:height "400px"
327
+ :active @step
328
+ :completed (str/join "," @completed)}
329
+ [:> ty/Step {:id "info" :label "Info"}
330
+ [:div.p-6.flex.flex-col.gap-4
331
+ [:> ty/Input {:label "Name" :required true}]
332
+ [:> ty/Button {:flavor "primary"
333
+ :onClick #(advance "review")} "Next"]]]
334
+ [:> ty/Step {:id "review" :label "Review"}
335
+ [:div.p-6.flex.gap-2
336
+ [:> ty/Button {:onClick #(reset! step "info")} "Back"]
337
+ [:> ty/Button {:flavor "success"
338
+ :onClick #(advance "done")} "Finish"]]]
339
+ [:> ty/Step {:id "done" :label "Done"}
340
+ [:div.p-6 "All done!"]]]))))
341
+ ```
342
+
343
+ Event detail: `{ activeId, activeIndex, previousId, previousIndex, direction }` via `onChange` — or listen on the element directly for `ty-wizard-step-change`.
344
+
345
+ ## Reorderable lists (ty-sortable)
346
+
347
+ `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 Reagent renders the items in the new order. Give each item a `:key` and a `:data-key` (or `:id`):
348
+
349
+ ```clojure
350
+ (defonce board (r/atom {"todo" ["a" "b"] "done" ["c"]}))
351
+ (defonce saving? (r/atom false))
352
+
353
+ (defn on-move [^js e]
354
+ (let [value (.. e -detail -value)]
355
+ (reset! saving? true)
356
+ (-> (save value)
357
+ (.then #(swap! board merge (js->clj (.-order value)))) ; new key order per touched list
358
+ (.finally #(reset! saving? false))))) ; order unchanged: snaps back
359
+
360
+ (defn column [id label]
361
+ [:> ty/Sortable {:id id :group "board" :label label
362
+ :aria-busy (when @saving? "true")
363
+ :onChange on-move}
364
+ (for [k (get @board id)]
365
+ ^{:key k}
366
+ [:div {:data-key k}
367
+ [:button {:type "button" :data-handle "" :aria-label (str "Move " k)}
368
+ [:> ty/Icon {:name "grip-vertical"}]]
369
+ k])])
370
+ ```
371
+
372
+ - `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.
373
+ - `: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.
374
+ - 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.
375
+ - Props: `:group`, `:axis`, `:handle`, `:accepts`, `:disabled`, `:keyAttr`, `:holdTimeout`, `:label`, `:canDrop`, `:labels`, and `:onStart` / `:onCancel` / `:onSettle`.
376
+
377
+ ---
378
+
379
+ ## Common pitfalls
380
+
381
+ - **`:on-change` vs `:onChange`** — easy to mix up. Through `:>`, you must write camelCase. In a plain `[:input ...]` (HTML), kebab-case works. Reagent does *not* transform props for `:>` components.
382
+ - **`:className`, not `:class`, when going through `:>`** — same reason. (Reagent's hiccup converts `:class` for HTML elements only.)
383
+ - **Don't destructure props in the outer Form-2 fn** — only the inner returned fn gets the latest props. Destructure inside the render fn:
384
+ ```clojure
385
+ ;; Wrong
386
+ (defn x [{:keys [v]}]
387
+ (let [a (r/atom 0)]
388
+ (fn [] [:div v]))) ; v is stale on update
389
+
390
+ ;; Right
391
+ (defn x []
392
+ (let [a (r/atom 0)]
393
+ (fn [{:keys [v]}] [:div v])))
394
+ ```
395
+ - **Don't pass CLJS persistent vectors as props** to `Select` with `:multiple`. Convert to a comma-string or JS array on the way in:
396
+ ```clojure
397
+ :value (str/join "," @skills)
398
+ ```
399
+ - **`reagent.dom/render` is deprecated** in React 18 mode — use `reagent.dom.client`.
400
+ - **`r/as-element`** is rarely needed. Only reach for it if a third-party React component asks for a React element directly (e.g. `Suspense`'s `:fallback`).
401
+ - **Children of `Select`** must be `ty/Option` (or raw `[:ty-option …]`) — not native `<option>`s or `ty/Tag`. The selection is the select's `:value`; `:selected` on an option does nothing without `:external-selection`.
402
+
403
+ ## See also
404
+
405
+ - [QUICKSTART.md](QUICKSTART.md) — Track A entry point
406
+ - [CLOJURESCRIPT_GUIDE.md](CLOJURESCRIPT_GUIDE.md) — substrate (deps, CSS, shadow-cljs)
407
+ - [UIX_TY_GUIDE.md](UIX_TY_GUIDE.md) — same React wrapper, hooks-only model
408
+ - [`examples/reagent/`](../../examples/reagent/) — full working app: routing, forms, validation