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

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 (393) hide show
  1. package/AGENTS.md +122 -0
  2. package/CHANGELOG.md +1541 -0
  3. package/README.md +71 -53
  4. package/bin/tyrell.mjs +77 -0
  5. package/css/tyrell-colors-static.css +1 -0
  6. package/css/tyrell-theme.css +1 -0
  7. package/css/tyrell.css +1 -1783
  8. package/dist/tyrell-colors-static.css +1 -0
  9. package/dist/tyrell-theme.css +1 -0
  10. package/dist/tyrell.css +1 -1783
  11. package/dist/tyrell.js +1 -1
  12. package/guides/AGENT_INSTRUCTIONS.md +124 -0
  13. package/guides/AI_GUIDE.md +53 -0
  14. package/guides/CSS_GUIDE.md +1016 -0
  15. package/guides/DATASTAR_TY_GUIDE.md +657 -0
  16. package/guides/ICONS_GUIDE.md +212 -0
  17. package/guides/TY_GUIDE.md +937 -0
  18. package/guides/clj/CLOJURESCRIPT_GUIDE.md +300 -0
  19. package/guides/clj/CODE_SPLITTING.md +279 -0
  20. package/guides/clj/COMPONENT_GUIDE.md +391 -0
  21. package/guides/clj/HELIX_TY_GUIDE.md +428 -0
  22. package/guides/clj/I18N_GUIDE.md +478 -0
  23. package/guides/clj/LAYOUT_GUIDE.md +273 -0
  24. package/guides/clj/QUICKSTART.md +266 -0
  25. package/guides/clj/REAGENT_TY_GUIDE.md +408 -0
  26. package/guides/clj/REPLICANT_TY_GUIDE.md +623 -0
  27. package/guides/clj/ROUTING_GUIDE.md +346 -0
  28. package/guides/clj/UIX_TY_GUIDE.md +319 -0
  29. package/guides/js/HTMX_TY_GUIDE.md +252 -0
  30. package/guides/js/JAVASCRIPT_GUIDE.md +388 -0
  31. package/guides/js/REACT_TY_GUIDE.md +983 -0
  32. package/guides/js/SVELTE_TY_GUIDE.md +682 -0
  33. package/guides/js/TYCOMPONENT_GUIDE.md +962 -0
  34. package/guides/js/VUE_TY_GUIDE.md +738 -0
  35. package/lib/base/ty-component.d.ts +57 -13
  36. package/lib/base/ty-component.js +266 -292
  37. package/lib/components/button.d.ts +33 -18
  38. package/lib/components/button.js +317 -267
  39. package/lib/components/calendar-month.d.ts +30 -47
  40. package/lib/components/calendar-month.js +455 -429
  41. package/lib/components/calendar-navigation.d.ts +41 -49
  42. package/lib/components/calendar-navigation.js +287 -346
  43. package/lib/components/calendar.d.ts +73 -83
  44. package/lib/components/calendar.js +837 -762
  45. package/lib/components/checkbox.d.ts +26 -75
  46. package/lib/components/checkbox.js +298 -391
  47. package/lib/components/copy.d.ts +20 -60
  48. package/lib/components/copy.js +276 -380
  49. package/lib/components/date-picker.d.ts +100 -183
  50. package/lib/components/date-picker.js +1155 -1570
  51. package/lib/components/file-upload.d.ts +16 -15
  52. package/lib/components/file-upload.js +436 -426
  53. package/lib/components/icon.d.ts +3 -24
  54. package/lib/components/icon.js +141 -230
  55. package/lib/components/input.d.ts +93 -108
  56. package/lib/components/input.js +734 -710
  57. package/lib/components/modal.d.ts +39 -29
  58. package/lib/components/modal.js +419 -438
  59. package/lib/components/option.d.ts +20 -35
  60. package/lib/components/option.js +184 -309
  61. package/lib/components/popup.d.ts +2 -17
  62. package/lib/components/popup.js +353 -347
  63. package/lib/components/radio.d.ts +33 -25
  64. package/lib/components/radio.js +433 -422
  65. package/lib/components/resize-observer.d.ts +3 -30
  66. package/lib/components/resize-observer.js +71 -103
  67. package/lib/components/scroll-container.d.ts +21 -14
  68. package/lib/components/scroll-container.js +292 -234
  69. package/lib/components/select.d.ts +458 -0
  70. package/lib/components/select.js +1458 -0
  71. package/lib/components/selected-tags.d.ts +60 -0
  72. package/lib/components/selected-tags.js +225 -0
  73. package/lib/components/sortable.d.ts +175 -0
  74. package/lib/components/sortable.js +1844 -0
  75. package/lib/components/step.d.ts +1 -6
  76. package/lib/components/step.js +62 -68
  77. package/lib/components/switch.d.ts +15 -15
  78. package/lib/components/switch.js +237 -231
  79. package/lib/components/tab.d.ts +50 -7
  80. package/lib/components/tab.js +203 -69
  81. package/lib/components/tabs.d.ts +19 -64
  82. package/lib/components/tabs.js +600 -618
  83. package/lib/components/tag.d.ts +14 -52
  84. package/lib/components/tag.js +231 -306
  85. package/lib/components/textarea.d.ts +58 -89
  86. package/lib/components/textarea.js +523 -573
  87. package/lib/components/tooltip.d.ts +8 -13
  88. package/lib/components/tooltip.js +322 -409
  89. package/lib/components/wizard.d.ts +7 -54
  90. package/lib/components/wizard.js +376 -606
  91. package/lib/icons/fontawesome/brands.d.ts +0 -1
  92. package/lib/icons/fontawesome/brands.js +0 -8
  93. package/lib/icons/fontawesome/regular.d.ts +0 -1
  94. package/lib/icons/fontawesome/regular.js +0 -8
  95. package/lib/icons/fontawesome/solid.d.ts +0 -1
  96. package/lib/icons/fontawesome/solid.js +0 -8
  97. package/lib/icons/heroicons/micro.d.ts +0 -1
  98. package/lib/icons/heroicons/micro.js +392 -400
  99. package/lib/icons/heroicons/mini.d.ts +0 -1
  100. package/lib/icons/heroicons/mini.js +382 -390
  101. package/lib/icons/heroicons/outline.d.ts +0 -1
  102. package/lib/icons/heroicons/outline.js +337 -345
  103. package/lib/icons/heroicons/solid.d.ts +0 -1
  104. package/lib/icons/heroicons/solid.js +407 -415
  105. package/lib/icons/lucide.d.ts +0 -1
  106. package/lib/icons/lucide.js +24479 -26351
  107. package/lib/icons/material/filled.d.ts +0 -1
  108. package/lib/icons/material/filled.js +9653 -9663
  109. package/lib/icons/material/outlined.d.ts +0 -1
  110. package/lib/icons/material/outlined.js +10271 -10281
  111. package/lib/icons/material/round.d.ts +0 -1
  112. package/lib/icons/material/round.js +10495 -10505
  113. package/lib/icons/material/sharp.d.ts +0 -1
  114. package/lib/icons/material/sharp.js +9905 -9915
  115. package/lib/icons/material/two-tone.d.ts +0 -1
  116. package/lib/icons/material/two-tone.js +12792 -12802
  117. package/lib/index.d.ts +7 -4
  118. package/lib/index.js +26 -39
  119. package/lib/styles/button.d.ts +24 -7
  120. package/lib/styles/button.js +285 -445
  121. package/lib/styles/calendar-month.d.ts +7 -6
  122. package/lib/styles/calendar-month.js +158 -226
  123. package/lib/styles/calendar-navigation.d.ts +2 -6
  124. package/lib/styles/calendar-navigation.js +108 -127
  125. package/lib/styles/calendar.d.ts +3 -3
  126. package/lib/styles/calendar.js +87 -23
  127. package/lib/styles/checkbox.d.ts +7 -6
  128. package/lib/styles/checkbox.js +101 -15
  129. package/lib/styles/copy.d.ts +3 -2
  130. package/lib/styles/copy.js +91 -71
  131. package/lib/styles/custom-scrollbar.d.ts +1 -2
  132. package/lib/styles/custom-scrollbar.js +80 -115
  133. package/lib/styles/date-picker.d.ts +4 -6
  134. package/lib/styles/date-picker.js +321 -388
  135. package/lib/styles/field-size.d.ts +6 -0
  136. package/lib/styles/field-size.js +91 -0
  137. package/lib/styles/file-upload.d.ts +1 -2
  138. package/lib/styles/file-upload.js +143 -188
  139. package/lib/styles/icon.d.ts +2 -6
  140. package/lib/styles/icon.js +92 -170
  141. package/lib/styles/input.d.ts +4 -7
  142. package/lib/styles/input.js +148 -643
  143. package/lib/styles/modal.d.ts +1 -2
  144. package/lib/styles/modal.js +127 -108
  145. package/lib/styles/option.d.ts +2 -6
  146. package/lib/styles/option.js +53 -96
  147. package/lib/styles/popup.d.ts +1 -2
  148. package/lib/styles/popup.js +47 -77
  149. package/lib/styles/radio.d.ts +3 -2
  150. package/lib/styles/radio.js +90 -116
  151. package/lib/styles/resize-observer.d.ts +1 -2
  152. package/lib/styles/resize-observer.js +2 -12
  153. package/lib/styles/scroll-container.d.ts +1 -2
  154. package/lib/styles/scroll-container.js +103 -146
  155. package/lib/styles/select-base.d.ts +8 -0
  156. package/lib/styles/select-base.js +752 -0
  157. package/lib/styles/select.d.ts +11 -0
  158. package/lib/styles/select.js +229 -0
  159. package/lib/styles/sortable.d.ts +16 -0
  160. package/lib/styles/sortable.js +85 -0
  161. package/lib/styles/step.d.ts +1 -2
  162. package/lib/styles/step.js +15 -34
  163. package/lib/styles/switch.d.ts +3 -2
  164. package/lib/styles/switch.js +52 -68
  165. package/lib/styles/tab.d.ts +1 -2
  166. package/lib/styles/tab.js +86 -34
  167. package/lib/styles/tabs.d.ts +3 -11
  168. package/lib/styles/tabs.js +204 -162
  169. package/lib/styles/tag.d.ts +2 -6
  170. package/lib/styles/tag.js +168 -362
  171. package/lib/styles/textarea.d.ts +1 -2
  172. package/lib/styles/textarea.js +238 -306
  173. package/lib/styles/tooltip.d.ts +4 -3
  174. package/lib/styles/tooltip.js +3 -131
  175. package/lib/styles/wizard.d.ts +8 -20
  176. package/lib/styles/wizard.js +306 -295
  177. package/lib/types/common.d.ts +9 -8
  178. package/lib/types/common.js +8 -5
  179. package/lib/utils/calendar-utils.d.ts +49 -65
  180. package/lib/utils/calendar-utils.js +158 -343
  181. package/lib/utils/custom-scrollbar.d.ts +6 -20
  182. package/lib/utils/custom-scrollbar.js +273 -317
  183. package/lib/utils/flavor-sheet.d.ts +31 -0
  184. package/lib/utils/flavor-sheet.js +17 -0
  185. package/lib/utils/icon-registry.d.ts +0 -15
  186. package/lib/utils/icon-registry.js +138 -279
  187. package/lib/utils/icons.d.ts +9 -0
  188. package/lib/utils/icons.js +1 -0
  189. package/lib/utils/loader-registry.d.ts +2 -3
  190. package/lib/utils/loader-registry.js +3 -35
  191. package/lib/utils/locale.d.ts +2 -80
  192. package/lib/utils/locale.js +30 -205
  193. package/lib/utils/mobile.d.ts +0 -1
  194. package/lib/utils/mobile.js +1 -18
  195. package/lib/utils/number-format.d.ts +6 -24
  196. package/lib/utils/number-format.js +53 -136
  197. package/lib/utils/positioning.d.ts +72 -22
  198. package/lib/utils/positioning.js +224 -298
  199. package/lib/utils/property-capture.d.ts +5 -27
  200. package/lib/utils/property-capture.js +36 -144
  201. package/lib/utils/property-manager.d.ts +6 -6
  202. package/lib/utils/property-manager.js +127 -196
  203. package/lib/utils/resize-observer.d.ts +0 -1
  204. package/lib/utils/resize-observer.js +23 -59
  205. package/lib/utils/scroll-lock.d.ts +10 -11
  206. package/lib/utils/scroll-lock.js +165 -173
  207. package/lib/utils/styles.d.ts +0 -6
  208. package/lib/utils/styles.js +17 -48
  209. package/lib/utils/upgrade-properties.d.ts +21 -0
  210. package/lib/utils/upgrade-properties.js +47 -0
  211. package/lib/utils/validity.d.ts +122 -0
  212. package/lib/utils/validity.js +289 -0
  213. package/lib/version.d.ts +1 -2
  214. package/lib/version.js +1 -11
  215. package/package.json +66 -18
  216. package/lib/base/ty-component.d.ts.map +0 -1
  217. package/lib/base/ty-component.js.map +0 -1
  218. package/lib/components/button.d.ts.map +0 -1
  219. package/lib/components/button.js.map +0 -1
  220. package/lib/components/calendar-month.d.ts.map +0 -1
  221. package/lib/components/calendar-month.js.map +0 -1
  222. package/lib/components/calendar-navigation.d.ts.map +0 -1
  223. package/lib/components/calendar-navigation.js.map +0 -1
  224. package/lib/components/calendar.d.ts.map +0 -1
  225. package/lib/components/calendar.js.map +0 -1
  226. package/lib/components/checkbox.d.ts.map +0 -1
  227. package/lib/components/checkbox.js.map +0 -1
  228. package/lib/components/copy.d.ts.map +0 -1
  229. package/lib/components/copy.js.map +0 -1
  230. package/lib/components/date-picker.d.ts.map +0 -1
  231. package/lib/components/date-picker.js.map +0 -1
  232. package/lib/components/dropdown.d.ts +0 -404
  233. package/lib/components/dropdown.d.ts.map +0 -1
  234. package/lib/components/dropdown.js +0 -1563
  235. package/lib/components/dropdown.js.map +0 -1
  236. package/lib/components/file-upload.d.ts.map +0 -1
  237. package/lib/components/file-upload.js.map +0 -1
  238. package/lib/components/icon.d.ts.map +0 -1
  239. package/lib/components/icon.js.map +0 -1
  240. package/lib/components/input.d.ts.map +0 -1
  241. package/lib/components/input.js.map +0 -1
  242. package/lib/components/modal.d.ts.map +0 -1
  243. package/lib/components/modal.js.map +0 -1
  244. package/lib/components/multiselect.d.ts +0 -408
  245. package/lib/components/multiselect.d.ts.map +0 -1
  246. package/lib/components/multiselect.js +0 -1611
  247. package/lib/components/multiselect.js.map +0 -1
  248. package/lib/components/option.d.ts.map +0 -1
  249. package/lib/components/option.js.map +0 -1
  250. package/lib/components/popup.d.ts.map +0 -1
  251. package/lib/components/popup.js.map +0 -1
  252. package/lib/components/radio.d.ts.map +0 -1
  253. package/lib/components/radio.js.map +0 -1
  254. package/lib/components/resize-observer.d.ts.map +0 -1
  255. package/lib/components/resize-observer.js.map +0 -1
  256. package/lib/components/scroll-container.d.ts.map +0 -1
  257. package/lib/components/scroll-container.js.map +0 -1
  258. package/lib/components/step.d.ts.map +0 -1
  259. package/lib/components/step.js.map +0 -1
  260. package/lib/components/switch.d.ts.map +0 -1
  261. package/lib/components/switch.js.map +0 -1
  262. package/lib/components/tab.d.ts.map +0 -1
  263. package/lib/components/tab.js.map +0 -1
  264. package/lib/components/tabs.d.ts.map +0 -1
  265. package/lib/components/tabs.js.map +0 -1
  266. package/lib/components/tag.d.ts.map +0 -1
  267. package/lib/components/tag.js.map +0 -1
  268. package/lib/components/textarea.d.ts.map +0 -1
  269. package/lib/components/textarea.js.map +0 -1
  270. package/lib/components/tooltip.d.ts.map +0 -1
  271. package/lib/components/tooltip.js.map +0 -1
  272. package/lib/components/wizard.d.ts.map +0 -1
  273. package/lib/components/wizard.js.map +0 -1
  274. package/lib/icons/fontawesome/brands.d.ts.map +0 -1
  275. package/lib/icons/fontawesome/brands.js.map +0 -1
  276. package/lib/icons/fontawesome/regular.d.ts.map +0 -1
  277. package/lib/icons/fontawesome/regular.js.map +0 -1
  278. package/lib/icons/fontawesome/solid.d.ts.map +0 -1
  279. package/lib/icons/fontawesome/solid.js.map +0 -1
  280. package/lib/icons/heroicons/micro.d.ts.map +0 -1
  281. package/lib/icons/heroicons/micro.js.map +0 -1
  282. package/lib/icons/heroicons/mini.d.ts.map +0 -1
  283. package/lib/icons/heroicons/mini.js.map +0 -1
  284. package/lib/icons/heroicons/outline.d.ts.map +0 -1
  285. package/lib/icons/heroicons/outline.js.map +0 -1
  286. package/lib/icons/heroicons/solid.d.ts.map +0 -1
  287. package/lib/icons/heroicons/solid.js.map +0 -1
  288. package/lib/icons/lucide.d.ts.map +0 -1
  289. package/lib/icons/lucide.js.map +0 -1
  290. package/lib/icons/material/filled.d.ts.map +0 -1
  291. package/lib/icons/material/filled.js.map +0 -1
  292. package/lib/icons/material/outlined.d.ts.map +0 -1
  293. package/lib/icons/material/outlined.js.map +0 -1
  294. package/lib/icons/material/round.d.ts.map +0 -1
  295. package/lib/icons/material/round.js.map +0 -1
  296. package/lib/icons/material/sharp.d.ts.map +0 -1
  297. package/lib/icons/material/sharp.js.map +0 -1
  298. package/lib/icons/material/two-tone.d.ts.map +0 -1
  299. package/lib/icons/material/two-tone.js.map +0 -1
  300. package/lib/index.d.ts.map +0 -1
  301. package/lib/index.js.map +0 -1
  302. package/lib/styles/button.d.ts.map +0 -1
  303. package/lib/styles/button.js.map +0 -1
  304. package/lib/styles/calendar-month.d.ts.map +0 -1
  305. package/lib/styles/calendar-month.js.map +0 -1
  306. package/lib/styles/calendar-navigation.d.ts.map +0 -1
  307. package/lib/styles/calendar-navigation.js.map +0 -1
  308. package/lib/styles/calendar.d.ts.map +0 -1
  309. package/lib/styles/calendar.js.map +0 -1
  310. package/lib/styles/checkbox.d.ts.map +0 -1
  311. package/lib/styles/checkbox.js.map +0 -1
  312. package/lib/styles/copy.d.ts.map +0 -1
  313. package/lib/styles/copy.js.map +0 -1
  314. package/lib/styles/custom-scrollbar.d.ts.map +0 -1
  315. package/lib/styles/custom-scrollbar.js.map +0 -1
  316. package/lib/styles/date-picker.d.ts.map +0 -1
  317. package/lib/styles/date-picker.js.map +0 -1
  318. package/lib/styles/dropdown.d.ts +0 -12
  319. package/lib/styles/dropdown.d.ts.map +0 -1
  320. package/lib/styles/dropdown.js +0 -1048
  321. package/lib/styles/dropdown.js.map +0 -1
  322. package/lib/styles/file-upload.d.ts.map +0 -1
  323. package/lib/styles/file-upload.js.map +0 -1
  324. package/lib/styles/icon.d.ts.map +0 -1
  325. package/lib/styles/icon.js.map +0 -1
  326. package/lib/styles/input.d.ts.map +0 -1
  327. package/lib/styles/input.js.map +0 -1
  328. package/lib/styles/modal.d.ts.map +0 -1
  329. package/lib/styles/modal.js.map +0 -1
  330. package/lib/styles/multiselect.d.ts +0 -6
  331. package/lib/styles/multiselect.d.ts.map +0 -1
  332. package/lib/styles/multiselect.js +0 -837
  333. package/lib/styles/multiselect.js.map +0 -1
  334. package/lib/styles/option.d.ts.map +0 -1
  335. package/lib/styles/option.js.map +0 -1
  336. package/lib/styles/popup.d.ts.map +0 -1
  337. package/lib/styles/popup.js.map +0 -1
  338. package/lib/styles/radio.d.ts.map +0 -1
  339. package/lib/styles/radio.js.map +0 -1
  340. package/lib/styles/resize-observer.d.ts.map +0 -1
  341. package/lib/styles/resize-observer.js.map +0 -1
  342. package/lib/styles/scroll-container.d.ts.map +0 -1
  343. package/lib/styles/scroll-container.js.map +0 -1
  344. package/lib/styles/step.d.ts.map +0 -1
  345. package/lib/styles/step.js.map +0 -1
  346. package/lib/styles/switch.d.ts.map +0 -1
  347. package/lib/styles/switch.js.map +0 -1
  348. package/lib/styles/tab.d.ts.map +0 -1
  349. package/lib/styles/tab.js.map +0 -1
  350. package/lib/styles/tabs.d.ts.map +0 -1
  351. package/lib/styles/tabs.js.map +0 -1
  352. package/lib/styles/tag.d.ts.map +0 -1
  353. package/lib/styles/tag.js.map +0 -1
  354. package/lib/styles/textarea.d.ts.map +0 -1
  355. package/lib/styles/textarea.js.map +0 -1
  356. package/lib/styles/tooltip.d.ts.map +0 -1
  357. package/lib/styles/tooltip.js.map +0 -1
  358. package/lib/styles/wizard.d.ts.map +0 -1
  359. package/lib/styles/wizard.js.map +0 -1
  360. package/lib/types/common.d.ts.map +0 -1
  361. package/lib/types/common.js.map +0 -1
  362. package/lib/utils/calendar-utils.d.ts.map +0 -1
  363. package/lib/utils/calendar-utils.js.map +0 -1
  364. package/lib/utils/custom-scrollbar.d.ts.map +0 -1
  365. package/lib/utils/custom-scrollbar.js.map +0 -1
  366. package/lib/utils/icon-registry.d.ts.map +0 -1
  367. package/lib/utils/icon-registry.js.map +0 -1
  368. package/lib/utils/loader-registry.d.ts.map +0 -1
  369. package/lib/utils/loader-registry.js.map +0 -1
  370. package/lib/utils/locale.d.ts.map +0 -1
  371. package/lib/utils/locale.js.map +0 -1
  372. package/lib/utils/mobile.d.ts.map +0 -1
  373. package/lib/utils/mobile.js.map +0 -1
  374. package/lib/utils/number-format.d.ts.map +0 -1
  375. package/lib/utils/number-format.js.map +0 -1
  376. package/lib/utils/parse-boolean.d.ts +0 -39
  377. package/lib/utils/parse-boolean.d.ts.map +0 -1
  378. package/lib/utils/parse-boolean.js +0 -58
  379. package/lib/utils/parse-boolean.js.map +0 -1
  380. package/lib/utils/positioning.d.ts.map +0 -1
  381. package/lib/utils/positioning.js.map +0 -1
  382. package/lib/utils/property-capture.d.ts.map +0 -1
  383. package/lib/utils/property-capture.js.map +0 -1
  384. package/lib/utils/property-manager.d.ts.map +0 -1
  385. package/lib/utils/property-manager.js.map +0 -1
  386. package/lib/utils/resize-observer.d.ts.map +0 -1
  387. package/lib/utils/resize-observer.js.map +0 -1
  388. package/lib/utils/scroll-lock.d.ts.map +0 -1
  389. package/lib/utils/scroll-lock.js.map +0 -1
  390. package/lib/utils/styles.d.ts.map +0 -1
  391. package/lib/utils/styles.js.map +0 -1
  392. package/lib/version.d.ts.map +0 -1
  393. 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-rc.21"}
14
+ dev.gersak/tyrell-icons-lucide {:mvn/version "1.0.0-rc.21"}}} ; 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