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,346 @@
1
+ # Tyrell Router — ClojureScript Routing Guide
2
+
3
+ The `tyrell.router` namespace provides client-side routing for any ClojureScript framework (Replicant, UIx, Reagent, etc.). It uses a zipper-based tree structure with browser history integration.
4
+
5
+ ## Setup
6
+
7
+ ```clojure
8
+ (ns my-app.core
9
+ (:require [tyrell.router :as router]))
10
+ ```
11
+
12
+ ## Defining Routes
13
+
14
+ Routes are linked to parent nodes in a tree. The root is `::router/root`.
15
+
16
+ ```clojure
17
+ ;; Top-level routes
18
+ (router/link ::router/root
19
+ [{:id ::home
20
+ :segment "home"
21
+ :landing 10} ; highest :landing = default route
22
+ {:id ::about
23
+ :segment "about"}
24
+ {:id ::settings
25
+ :segment "settings"}])
26
+
27
+ ;; Nested routes — link to parent
28
+ (router/link ::settings
29
+ [{:id ::settings-general
30
+ :segment "general"}
31
+ {:id ::settings-account
32
+ :segment "account"}])
33
+ ```
34
+
35
+ **Route map keys:**
36
+
37
+ | Key | Description |
38
+ |-----|-------------|
39
+ | `:id` | Unique keyword identifying the route |
40
+ | `:segment` | URL path segment |
41
+ | `:landing` | Priority number — highest wins as default redirect |
42
+ | `:hash` | Hash fragment appended to URL. Routes can share a segment and differ only by hash (`/welcome#top`, `/welcome#examples`) |
43
+ | `:roles` | Set of roles required to access (optional) |
44
+ | `:permissions` | Set of permissions required to access (optional) |
45
+
46
+ ## Initialization
47
+
48
+ ```clojure
49
+ ;; Initialize with optional base path
50
+ (router/init! "") ; root-level app
51
+ (router/init! "/my-app") ; app served under /my-app/
52
+ ```
53
+
54
+ `init!` does:
55
+ 1. Sets the base path
56
+ 2. Reads the current browser URL
57
+ 3. Handles landing redirect if needed (404 or unauthorized → best landing route)
58
+ 4. Listens for `popstate` and `hashchange` events
59
+
60
+ ## Navigation
61
+
62
+ ```clojure
63
+ ;; Navigate by route id
64
+ (router/navigate! ::home)
65
+ (router/navigate! ::about)
66
+
67
+ ;; Navigate with query parameters
68
+ (router/navigate! ::user {:id 123})
69
+ ;; → /user?id=123
70
+ ```
71
+
72
+ ## Checking Active Route
73
+
74
+ ```clojure
75
+ ;; Is route anywhere in the current path?
76
+ (router/rendered? ::settings) ; true if /settings, /settings/general, etc.
77
+
78
+ ;; Exact match only
79
+ (router/rendered? ::settings true) ; true only if exactly /settings
80
+ ```
81
+
82
+ Hashes in exact matching: a route with a `:hash` matches only that hash. A route without one also matches when the URL's hash isn't a route of its own, because that hash is an in-page anchor: `/settings#billing` still renders `::settings`.
83
+
84
+ ## The Key Pattern: Self-Contained Views
85
+
86
+ Each view checks its own visibility. No `cond` or `case` in the parent — just list all views and each one decides whether to render.
87
+
88
+ ```clojure
89
+ ;; Each view owns its visibility
90
+ (defn home-view []
91
+ (when (router/rendered? ::home)
92
+ [:div.ty-elevated.p-6
93
+ [:h2 "Welcome Home"]]))
94
+
95
+ (defn about-view []
96
+ (when (router/rendered? ::about)
97
+ [:div.ty-elevated.p-6
98
+ [:h2 "About Us"]]))
99
+
100
+ ;; App just lists all views — no cond needed
101
+ (defn app []
102
+ [:div.ty-canvas
103
+ (nav)
104
+ (home-view)
105
+ (about-view)])
106
+ ```
107
+
108
+ This works the same in Replicant, UIx, Reagent, or any hiccup-based framework.
109
+
110
+ ## Navigation UI
111
+
112
+ ```clojure
113
+ (defn nav-button [route-id label icon-name]
114
+ (let [active? (router/rendered? route-id)]
115
+ [:button.px-4.py-2.rounded.flex.items-center.gap-2.transition-colors
116
+ {:class (if active?
117
+ ["ty-bg-primary" "ty-text++"]
118
+ ["ty-bg-neutral-" "ty-text" "hover:ty-bg-neutral"])
119
+ :on {:click #(router/navigate! route-id)}}
120
+ [:ty-icon {:name icon-name :size "sm"}]
121
+ label]))
122
+
123
+ (defn nav []
124
+ [:nav.ty-elevated.p-4.rounded-lg.mb-6
125
+ [:div.flex.gap-2
126
+ (nav-button ::home "Home" "home")
127
+ (nav-button ::about "About" "info")
128
+ (nav-button ::settings "Settings" "settings")]])
129
+ ```
130
+
131
+ ## Query Parameters
132
+
133
+ ```clojure
134
+ ;; Get current query params
135
+ (router/query-params)
136
+ ;; => {:id 123, :tab "settings"}
137
+
138
+ ;; Set query params (replaces history entry by default)
139
+ (router/set-query! {:page 2 :sort "name"})
140
+
141
+ ;; Push new history entry
142
+ (router/set-query! {:page 3} :push)
143
+
144
+ ;; Clear query params
145
+ (router/set-query! nil)
146
+ ```
147
+
148
+ ## Authorization
149
+
150
+ Routes can restrict access by requiring `:roles` or `:permissions` (both are sets of keywords):
151
+
152
+ ```clojure
153
+ (router/link ::router/root
154
+ [{:id ::home
155
+ :segment "home"
156
+ :landing 10}
157
+ {:id ::admin
158
+ :segment "admin"
159
+ :roles #{:admin}}
160
+ {:id ::dashboard
161
+ :segment "dashboard"
162
+ :permissions #{:view-dashboard}}
163
+ {:id ::reports
164
+ :segment "reports"
165
+ :roles #{:admin :analyst}
166
+ :permissions #{:view-reports}}])
167
+ ```
168
+
169
+ ### Setting Current User Context
170
+
171
+ The router exposes three dynamic vars for access control:
172
+
173
+ ```clojure
174
+ ;; *roles* and *permissions* are plain values (not atoms) — set! them directly
175
+ (set! router/*roles* #{:admin :user})
176
+ (set! router/*permissions* #{:view-dashboard :view-reports})
177
+
178
+ ;; *user* is an atom — use reset! or swap!
179
+ (reset! router/*user* {:id 1 :name "Alice"})
180
+ ```
181
+
182
+ Typically you set these after login and clear them on logout:
183
+
184
+ ```clojure
185
+ (defn on-login [user]
186
+ (reset! router/*user* user)
187
+ (set! router/*roles* (:roles user))
188
+ (set! router/*permissions* (:permissions user))
189
+ (router/navigate! ::home))
190
+
191
+ (defn on-logout []
192
+ (reset! router/*user* nil)
193
+ (set! router/*roles* nil)
194
+ (set! router/*permissions* nil)
195
+ (router/navigate! ::home))
196
+ ```
197
+
198
+ ### How Authorization Works
199
+
200
+ `authorized?` checks whether the current user can access a route:
201
+
202
+ ```clojure
203
+ (router/authorized? ::admin) ; => true/false
204
+ ```
205
+
206
+ The logic:
207
+ 1. If the route has **no roles and no permissions** — access is allowed (public route)
208
+ 2. If the route has `:roles` — allowed if **any** of the user's `*roles*` intersect with the route's roles
209
+ 3. If the route has `:permissions` — allowed if **any** of the user's `*permissions*` intersect with the route's permissions
210
+ 4. Roles and permissions are OR'd — matching either one grants access
211
+
212
+ ```clojure
213
+ ;; Route: {:roles #{:admin :analyst} :permissions #{:view-reports}}
214
+ ;; User has *roles* = #{:analyst} → authorized (role match)
215
+ ;; User has *permissions* = #{:view-reports} → authorized (permission match)
216
+ ;; User has *roles* = #{:user} and *permissions* = #{} → NOT authorized
217
+ ```
218
+
219
+ ### Automatic Redirect on Unauthorized Access
220
+
221
+ When the router initializes or the URL changes, `handle-landing!` runs automatically. It checks:
222
+ 1. If the current URL matches **no known routes** (404) — redirect to the best landing route
223
+ 2. If **any route** in the current path is unauthorized — redirect to the best landing route
224
+ 3. If the path only has routes **with a hash** and the URL has none (`/welcome` when only `#top` and `#examples` exist) — redirect to the best of those (highest `:landing`, then tree order)
225
+
226
+ A path *below* a route stays put (`/users/123` under `::users`), so views can read dynamic segments with non-exact `rendered?`. Redirects replace the history entry, so Back doesn't land on the URL that redirected.
227
+
228
+ The "best landing route" is the route with the highest `:landing` value that the user is authorized to access. This means different users can land on different default pages based on their roles.
229
+
230
+ ```clojure
231
+ ;; Admin lands on ::admin-dashboard, regular user lands on ::home
232
+ (router/link ::router/root
233
+ [{:id ::home
234
+ :segment "home"
235
+ :landing 10}
236
+ {:id ::admin-dashboard
237
+ :segment "admin"
238
+ :roles #{:admin}
239
+ :landing 20}]) ; higher priority, but only for admins
240
+ ```
241
+
242
+ ### Using rendered? with Authorization
243
+
244
+ Views should combine `rendered?` with `authorized?` for defense in depth:
245
+
246
+ ```clojure
247
+ (defn admin-panel []
248
+ (when (and (router/rendered? ::admin)
249
+ (router/authorized? ::admin))
250
+ [:div.ty-elevated.p-6
251
+ [:h2 "Admin Panel"]
252
+ ;; admin content
253
+ ]))
254
+ ```
255
+
256
+ ## Watching Router Changes
257
+
258
+ The router state lives in `router/*router*` (an atom). Watch it to trigger re-renders in your framework:
259
+
260
+ ```clojure
261
+ ;; Replicant
262
+ (add-watch router/*router* ::render
263
+ (fn [_ _ _ _] (render!)))
264
+
265
+ ;; Reagent — use ratom or re-frame subscription instead
266
+ ;; UIx — use a hook that derefs the atom
267
+ ```
268
+
269
+ ## Router State
270
+
271
+ `@router/*router*` contains:
272
+
273
+ | Key | Description |
274
+ |-----|-------------|
275
+ | `:tree` | Route tree (zipper root node) |
276
+ | `:current` | Current URL path (without base) |
277
+ | `:base` | Base path prefix |
278
+ | `:known` | Set of registered route ids |
279
+ | `:unknown` | Queue of routes whose parent isn't registered yet |
280
+ | `:query` | Current query parameters |
281
+
282
+ ## Utility Functions
283
+
284
+ ```clojure
285
+ ;; Get URL path for a route
286
+ (router/component-path (:tree @router/*router*) ::settings-general)
287
+ ;; => "/settings/general"
288
+
289
+ ;; Get all components rendered for current URL
290
+ (router/url->components)
291
+
292
+ ;; Debug: see landing candidates
293
+ (router/landing-candidates)
294
+ ```
295
+
296
+ ## Complete Example
297
+
298
+ ```clojure
299
+ (ns my-app.core
300
+ (:require [replicant.dom :as dom]
301
+ [tyrell.router :as router]
302
+ [tyrell.icons :as icons]
303
+ [tyrell.lucide :as lucide]))
304
+
305
+ (defonce state (atom {:counter 0}))
306
+
307
+ ;; Routes
308
+ (router/link ::router/root
309
+ [{:id ::home :segment "home" :landing 10}
310
+ {:id ::about :segment "about"}])
311
+
312
+ ;; Views
313
+ (defn home-view []
314
+ (when (router/rendered? ::home)
315
+ [:div.ty-elevated.p-6.rounded-lg
316
+ [:h2.ty-text++.text-2xl.mb-4 "Home"]
317
+ [:p.ty-text "Counter: " (:counter @state)]
318
+ [:ty-button {:flavor "primary"
319
+ :on {:click #(swap! state update :counter inc)}}
320
+ "Increment"]]))
321
+
322
+ (defn about-view []
323
+ (when (router/rendered? ::about)
324
+ [:div.ty-elevated.p-6.rounded-lg
325
+ [:h2.ty-text++.text-2xl.mb-4 "About"]
326
+ [:p.ty-text "This is the about page."]]))
327
+
328
+ (defn app []
329
+ [:div.ty-canvas.min-h-screen.p-6
330
+ (nav)
331
+ (home-view)
332
+ (about-view)])
333
+
334
+ ;; Init
335
+ (defn render! []
336
+ (dom/render (.getElementById js/document "app") (app)))
337
+
338
+ (defn init []
339
+ (icons/register! {:home lucide/home :info lucide/info})
340
+ (router/init! "")
341
+ (add-watch router/*router* ::render (fn [_ _ _ _] (render!)))
342
+ (add-watch state ::render (fn [_ _ _ _] (render!)))
343
+ (render!))
344
+ ```
345
+
346
+ Replace `replicant.dom` with your framework's render call — the router API is identical.
@@ -0,0 +1,319 @@
1
+ # UIx + Tyrell Guide
2
+
3
+ [UIx](https://github.com/pitch-io/uix) is a thin macro layer over React. It speaks hiccup-shaped syntax via `$`, defines components with `defui`, and uses React hooks directly — no `r/atom`, no reactions. Tyrell ships React wrappers via `tyrell.react` so you write `($ ty/Input {:value v :on-change h})` and the wrapper bridges `event.detail.value` for you.
4
+
5
+ This guide covers what's specific to UIx + Tyrell. For framework-agnostic CLJS substrate concerns (icons, CSS, shadow-cljs), see [CLOJURESCRIPT_GUIDE.md](CLOJURESCRIPT_GUIDE.md). Working example: [`examples/uix/`](../../examples/uix/).
6
+
7
+ ## Setup
8
+
9
+ `deps.edn`:
10
+
11
+ ```clojure
12
+ {:deps {com.pitch/uix.core {:mvn/version "1.4.4"}
13
+ com.pitch/uix.dom {:mvn/version "1.4.4"}
14
+ dev.gersak/tyrell {:mvn/version "1.0.0-rc.21"}
15
+ dev.gersak/tyrell-icons-lucide {:mvn/version "1.0.0-rc.21"}}} ; tyrell.lucide
16
+ ```
17
+
18
+ `tyrell.react` is part of `dev.gersak/tyrell`, but the npm wrapper package isn't auto-pulled. Install it explicitly the same way you install React itself:
19
+
20
+ ```bash
21
+ npm install react react-dom tyrell-react
22
+ ```
23
+
24
+ `shadow-cljs.edn`:
25
+
26
+ ```clojure
27
+ {:dependencies []
28
+ :builds {:app {:target :browser
29
+ :modules {:main {:init-fn my-app.core/init}}}}}
30
+ ```
31
+
32
+ `tyrell-components` (the web components themselves) is declared in tyrell's `deps.cljs` and shadow-cljs auto-installs it on first build — no manual `npm install tyrell-components`.
33
+
34
+ Load the CSS once, in your HTML or via your CSS pipeline:
35
+
36
+ ```html
37
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components/css/tyrell.css">
38
+ <!-- tyrell-theme.css: auto-contrast, seed-based rebranding, themes. See TY_GUIDE.md#quick-start -->
39
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components/css/tyrell-theme.css">
40
+ ```
41
+
42
+ ## Mount
43
+
44
+ UIx targets React 18. Create the root once, store it, re-render on `^:after-load`:
45
+
46
+ ```clojure
47
+ (ns my-app.core
48
+ (:require [tyrell.components] ; side-effect: registers all <ty-*> elements
49
+ [tyrell.react :as ty]
50
+ [tyrell.icons :as icons]
51
+ [tyrell.lucide :as lucide]
52
+ [uix.core :as uix :refer [defui $]]
53
+ [uix.dom]))
54
+
55
+ (defui app []
56
+ ($ :div.ty-canvas.min-h-screen.p-8
57
+ ($ ty/Button {:flavor "primary"} "Hello")))
58
+
59
+ (defonce root
60
+ (uix.dom/create-root (js/document.getElementById "app")))
61
+
62
+ (defn ^:export init []
63
+ (icons/register! {:check lucide/check})
64
+ (.render root ($ app)))
65
+
66
+ (defn ^:after-load reload []
67
+ (.render root ($ app)))
68
+ ```
69
+
70
+ `defonce` is what keeps the root from being recreated on hot reload. Without it, every save would orphan a React tree.
71
+
72
+ ## Components — `defui` and `$`
73
+
74
+ `defui` defines a component, `$` instantiates one (or any DOM element). UIx auto-camelCases prop names you pass to React components, so kebab-case on CLJS side maps to camelCase the wrapper expects:
75
+
76
+ ```clojure
77
+ (defui labeled-input [{:keys [label value on-change]}]
78
+ ($ :div.flex.flex-col.gap-1
79
+ ($ :label.ty-text+ label)
80
+ ($ ty/Input {:value value
81
+ :on-change on-change}))) ; UIx → onChange for React
82
+
83
+ (defui form []
84
+ (let [[email set-email] (uix/use-state "")]
85
+ ($ labeled-input
86
+ {:label "Email"
87
+ :value email
88
+ :on-change #(set-email (.. % -detail -value))})))
89
+ ```
90
+
91
+ CLJS class shortcuts on DOM elements work — `($ :div.foo.bar)` is the idiomatic way to set classes; pass `:class` for dynamic ones:
92
+
93
+ ```clojure
94
+ ($ :div.ty-elevated.p-6.rounded-lg
95
+ {:class (when active? "ty-bg-primary-")}
96
+ "Content")
97
+ ```
98
+
99
+ `$` accepts children as varargs after the props map. For lists, attach `:key` on the props of the iterated element (not as metadata — that's a Reagent idiom):
100
+
101
+ ```clojure
102
+ ($ :ul
103
+ (for [item items]
104
+ ($ :li {:key (:id item)} (:name item))))
105
+ ```
106
+
107
+ ## State — pure hooks, no atoms
108
+
109
+ UIx is hooks-first. `r/atom` is not part of the model. `use-state` returns `[value setter]`:
110
+
111
+ ```clojure
112
+ (defui counter []
113
+ (let [[n set-n] (uix/use-state 0)]
114
+ ($ :div.flex.items-center.gap-2
115
+ ($ ty/Button {:flavor "primary"
116
+ :on-click #(set-n inc)}
117
+ "Inc")
118
+ ($ :span.ty-text++.text-xl n))))
119
+ ```
120
+
121
+ For derived state, use `use-memo`. For side effects, `use-effect` with an explicit dependency vector — UIx will warn at compile time if you reference state in the body that isn't declared:
122
+
123
+ ```clojure
124
+ (uix/use-effect
125
+ (fn []
126
+ (js/document.title (str "Count: " n))
127
+ ;; Cleanup is the function returned
128
+ (fn [] (js/console.log "unmount")))
129
+ [n])
130
+ ```
131
+
132
+ ## Event handling — `event.detail.value`
133
+
134
+ Tyrell's React wrappers attach `addEventListener` on the underlying custom element and forward the native `CustomEvent`. So `e.detail.value` is the same access path you'd use in plain JS:
135
+
136
+ ```clojure
137
+ (defui email-field []
138
+ (let [[email set-email] (uix/use-state "")
139
+ [error set-error] (uix/use-state nil)]
140
+ ($ ty/Input
141
+ {:label "Email"
142
+ :type "email"
143
+ :value email
144
+ :error error
145
+ :on-change (fn [e]
146
+ (let [v (.. e -detail -value)]
147
+ (set-email v)
148
+ (set-error (when-not (re-find #"@" v)
149
+ "Looks invalid"))))}
150
+ ($ ty/Icon {:slot "start" :name "mail"}))))
151
+ ```
152
+
153
+ **Component-specific event payloads** (matches what the wrapper exposes):
154
+
155
+ | Component | Access |
156
+ |---|---|
157
+ | `ty/Input`, `ty/Textarea`, `ty/Switch`, `ty/DatePicker` | `(.. e -detail -value)` |
158
+ | `ty/Checkbox` | `(.. e -detail -checked)` |
159
+ | `ty/Select` | `(.. e -detail -value)`; with `:multiple`, `(.. e -detail -values)` → JS array |
160
+ | `ty/RadioGroup` | `(.. e -detail -value)` |
161
+ | `ty/Tabs` | `(.. e -detail -tab)` |
162
+ | `ty/Wizard` step nav | `(.. e -detail -step)` |
163
+
164
+ For `Select` with `:multiple`, convert the JS array to a CLJS vector if you need it:
165
+
166
+ ```clojure
167
+ :on-change (fn [e]
168
+ (let [vs (.. e -detail -values)]
169
+ (set-skills (vec vs))))
170
+ ```
171
+
172
+ ## Composition — children with slots
173
+
174
+ Tyrell components accept slotted children — pass them as `$` children with a `:slot` attribute:
175
+
176
+ ```clojure
177
+ ($ ty/Input
178
+ {:label "Search" :placeholder "Type to search…"
179
+ :value q :on-change #(set-q (.. % -detail -value))}
180
+ ($ ty/Icon {:slot "start" :name "search"}))
181
+ ```
182
+
183
+ `Select` takes `Option` children directly:
184
+
185
+ ```clojure
186
+ ($ ty/Select
187
+ {:label "Country" :value country
188
+ :on-change #(set-country (.. % -detail -value))}
189
+ ($ ty/Option {:value "us"} "United States")
190
+ ($ ty/Option {:value "de"} "Germany"))
191
+
192
+ ($ ty/Select
193
+ {:label "Skills" :multiple true :value (str/join "," skills)
194
+ :on-change (fn [e]
195
+ (set-skills (vec (.. e -detail -values))))}
196
+ ($ ty/Option {:value "clojure" :flavor "primary"} "Clojure")
197
+ ($ ty/Option {:value "react" :flavor "primary"} "React"))
198
+ ```
199
+
200
+ ## Refs and imperative APIs — modals, popups
201
+
202
+ `ty-modal` exposes `.show()` / `.hide()` methods. `use-ref` + the wrapper's ref forwarding gives you that handle:
203
+
204
+ ```clojure
205
+ (defui modal-demo []
206
+ (let [modal-ref (uix/use-ref nil)
207
+ open (fn [_] (some-> modal-ref .-current (.show)))
208
+ close (fn [_] (some-> modal-ref .-current (.hide)))]
209
+ ($ :div
210
+ ($ ty/Button {:flavor "primary" :on-click open} "Open")
211
+ ($ ty/Modal {:ref modal-ref}
212
+ ($ :div.ty-elevated.p-6.rounded-2xl
213
+ ($ :h3.ty-text++ "Hello")
214
+ ($ ty/Button {:on-click close} "Close"))))))
215
+ ```
216
+
217
+ The same pattern works for `ty-popup` (`.openPopup()` / `.closePopup()` / `.togglePopup()`).
218
+
219
+ ## Forms — controlled state
220
+
221
+ Tyrell components are form-associated, so a wrapping `<form>` element with a submit handler works without any extra wiring. UIx-side, treat the form like any controlled React form:
222
+
223
+ ```clojure
224
+ (defui signup-form []
225
+ (let [[profile set-profile] (uix/use-state {:email "" :role "" :news? false})
226
+ update-field (uix/use-callback
227
+ (fn [k v] (set-profile #(assoc % k v)))
228
+ [])
229
+ on-submit (fn [^js e]
230
+ (.preventDefault e)
231
+ (js/console.log "submit:" (clj->js profile)))]
232
+ ($ :form {:on-submit on-submit
233
+ :class "ty-elevated p-6 rounded-lg flex flex-col gap-4"}
234
+ ($ ty/Input
235
+ {:label "Email" :type "email" :required true
236
+ :value (:email profile)
237
+ :on-change #(update-field :email (.. % -detail -value))})
238
+ ($ ty/Select
239
+ {:label "Role" :value (:role profile)
240
+ :on-change #(update-field :role (.. % -detail -value))}
241
+ ($ ty/Option {:value "developer"} "Developer")
242
+ ($ ty/Option {:value "designer"} "Designer"))
243
+ ($ :label.flex.items-center.gap-2.cursor-pointer
244
+ ($ ty/Checkbox
245
+ {:checked (:news? profile)
246
+ :on-change #(update-field :news? (.. % -detail -checked))})
247
+ "Subscribe to newsletter")
248
+ ($ ty/Button {:type "submit" :flavor "primary"} "Submit"))))
249
+ ```
250
+
251
+ ## Subscribing to non-React state
252
+
253
+ UIx hooks-only model means non-React atoms (e.g. `tyrell.router/*router*`, app state in a `defonce` atom) need explicit subscription. The pattern: a custom hook that adds a watch in `use-effect`:
254
+
255
+ ```clojure
256
+ (defn use-watch
257
+ "Re-render when `a` (an IDeref + IWatchable) changes."
258
+ [a]
259
+ (let [[v set-v] (uix/use-state @a)]
260
+ (uix/use-effect
261
+ (fn []
262
+ (let [k (gensym "uix-watch")]
263
+ (add-watch a k (fn [_ _ _ new] (set-v new)))
264
+ (fn [] (remove-watch a k))))
265
+ [a])
266
+ v))
267
+
268
+ (defui current-route []
269
+ (let [router (use-watch tyrell.router/*router*)]
270
+ ($ :div.ty-text- (str "Current: " (:current router)))))
271
+ ```
272
+
273
+ This is the same approach the [`examples/uix/`](../../examples/uix/) app uses to subscribe to the Tyrell router.
274
+
275
+ ## Icons — register at startup
276
+
277
+ ```clojure
278
+ (ns my-app.icons
279
+ (:require [tyrell.icons :as icons]
280
+ [tyrell.lucide :as lucide]))
281
+
282
+ (icons/register! {:check lucide/check
283
+ :user lucide/user}) ; the key is the name
284
+ ```
285
+
286
+ Call it in `init` before the first render. Then `($ ty/Icon {:name "check"})`, or `($ :ty-icon {:name "check"})` for the plain element.
287
+
288
+ Sets, tree-shaking, custom SVGs and troubleshooting: [ICONS_GUIDE.md](../ICONS_GUIDE.md#in-clojure).
289
+
290
+ ## Lazy loading — UIx native
291
+
292
+ UIx ships `uix.core/lazy` for component-level code splitting, paired with shadow-cljs `:modules`:
293
+
294
+ ```clojure
295
+ (def calendar-page
296
+ (uix/lazy #(js/Promise.resolve (resolve 'my-app.calendar/page))))
297
+
298
+ ($ uix/Suspense {:fallback ($ :div "Loading…")}
299
+ ($ calendar-page))
300
+ ```
301
+
302
+ For shadow-cljs module setup, see [CODE_SPLITTING.md](CODE_SPLITTING.md).
303
+
304
+ ## Common pitfalls
305
+
306
+ - **Don't pass CLJS data structures as props** to wrapper components without conversion. `:value [:a :b]` will arrive as a CLJS persistent vector, which the underlying web component doesn't understand. Convert: `:value (clj->js skills)` or join into a string format the component expects (`Select` with `:multiple` accepts comma-separated `value="a,b"`).
307
+ - **`:variant` is not a valid prop** — Tyrell uses `:flavor` (mapped to the `flavor` attribute). The older example code may show `:variant`; that's outdated.
308
+ - **Don't render `<ty-*>` directly without the wrapper** if you need React-style event handling. `($ :ty-input {:on-change h})` will not fire — React's synthetic event system doesn't bridge custom element events. Either use `ty/Input` (recommended), or attach `addEventListener` manually in `use-effect` on a ref.
309
+ - **Boolean attributes**: pass them as `true`/`false`, not as strings. `($ ty/Modal {:open true})` works; `:open "true"` does not.
310
+ - **Don't forget `defonce` on the root**. Re-creating it on every reload leaks state.
311
+ - **Children of `Select`** must be `ty/Option` — not a plain `($ :option ...)` or `ty/Tag`. The selection is the select's `:value`; `:selected` on an option does nothing without `:external-selection`.
312
+
313
+ ## See also
314
+
315
+ - [QUICKSTART.md](QUICKSTART.md) — Track A entry point
316
+ - [CLOJURESCRIPT_GUIDE.md](CLOJURESCRIPT_GUIDE.md) — substrate (deps, CSS, shadow-cljs)
317
+ - [REPLICANT_TY_GUIDE.md](REPLICANT_TY_GUIDE.md) — non-React alternative
318
+ - [CODE_SPLITTING.md](CODE_SPLITTING.md) — shadow-cljs module setup
319
+ - [`examples/uix/`](../../examples/uix/) — full working app: routing, forms, modals, layouts