tyrell-components 1.0.0-TC8 → 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 (386) 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 +42 -18
  37. package/lib/components/button.js +318 -235
  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 +122 -0
  51. package/lib/components/file-upload.js +451 -0
  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 +17 -55
  83. package/lib/components/tag.js +235 -308
  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 +15 -4
  117. package/lib/index.js +28 -38
  118. package/lib/styles/button.d.ts +24 -7
  119. package/lib/styles/button.js +298 -417
  120. package/lib/styles/calendar-month.d.ts +7 -6
  121. package/lib/styles/calendar-month.js +157 -179
  122. package/lib/styles/calendar-navigation.d.ts +2 -6
  123. package/lib/styles/calendar-navigation.js +108 -109
  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 +320 -352
  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 -0
  137. package/lib/styles/file-upload.js +196 -0
  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 +170 -359
  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 +34 -0
  189. package/lib/utils/loader-registry.js +11 -0
  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 +66 -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 -402
  232. package/lib/components/dropdown.d.ts.map +0 -1
  233. package/lib/components/dropdown.js +0 -1564
  234. package/lib/components/dropdown.js.map +0 -1
  235. package/lib/components/icon.d.ts.map +0 -1
  236. package/lib/components/icon.js.map +0 -1
  237. package/lib/components/input.d.ts.map +0 -1
  238. package/lib/components/input.js.map +0 -1
  239. package/lib/components/modal.d.ts.map +0 -1
  240. package/lib/components/modal.js.map +0 -1
  241. package/lib/components/multiselect.d.ts +0 -397
  242. package/lib/components/multiselect.d.ts.map +0 -1
  243. package/lib/components/multiselect.js +0 -1580
  244. package/lib/components/multiselect.js.map +0 -1
  245. package/lib/components/option.d.ts.map +0 -1
  246. package/lib/components/option.js.map +0 -1
  247. package/lib/components/popup.d.ts.map +0 -1
  248. package/lib/components/popup.js.map +0 -1
  249. package/lib/components/radio.d.ts.map +0 -1
  250. package/lib/components/radio.js.map +0 -1
  251. package/lib/components/resize-observer.d.ts.map +0 -1
  252. package/lib/components/resize-observer.js.map +0 -1
  253. package/lib/components/scroll-container.d.ts.map +0 -1
  254. package/lib/components/scroll-container.js.map +0 -1
  255. package/lib/components/step.d.ts.map +0 -1
  256. package/lib/components/step.js.map +0 -1
  257. package/lib/components/switch.d.ts.map +0 -1
  258. package/lib/components/switch.js.map +0 -1
  259. package/lib/components/tab.d.ts.map +0 -1
  260. package/lib/components/tab.js.map +0 -1
  261. package/lib/components/tabs.d.ts.map +0 -1
  262. package/lib/components/tabs.js.map +0 -1
  263. package/lib/components/tag.d.ts.map +0 -1
  264. package/lib/components/tag.js.map +0 -1
  265. package/lib/components/textarea.d.ts.map +0 -1
  266. package/lib/components/textarea.js.map +0 -1
  267. package/lib/components/tooltip.d.ts.map +0 -1
  268. package/lib/components/tooltip.js.map +0 -1
  269. package/lib/components/wizard.d.ts.map +0 -1
  270. package/lib/components/wizard.js.map +0 -1
  271. package/lib/icons/fontawesome/brands.d.ts.map +0 -1
  272. package/lib/icons/fontawesome/brands.js.map +0 -1
  273. package/lib/icons/fontawesome/regular.d.ts.map +0 -1
  274. package/lib/icons/fontawesome/regular.js.map +0 -1
  275. package/lib/icons/fontawesome/solid.d.ts.map +0 -1
  276. package/lib/icons/fontawesome/solid.js.map +0 -1
  277. package/lib/icons/heroicons/micro.d.ts.map +0 -1
  278. package/lib/icons/heroicons/micro.js.map +0 -1
  279. package/lib/icons/heroicons/mini.d.ts.map +0 -1
  280. package/lib/icons/heroicons/mini.js.map +0 -1
  281. package/lib/icons/heroicons/outline.d.ts.map +0 -1
  282. package/lib/icons/heroicons/outline.js.map +0 -1
  283. package/lib/icons/heroicons/solid.d.ts.map +0 -1
  284. package/lib/icons/heroicons/solid.js.map +0 -1
  285. package/lib/icons/lucide.d.ts.map +0 -1
  286. package/lib/icons/lucide.js.map +0 -1
  287. package/lib/icons/material/filled.d.ts.map +0 -1
  288. package/lib/icons/material/filled.js.map +0 -1
  289. package/lib/icons/material/outlined.d.ts.map +0 -1
  290. package/lib/icons/material/outlined.js.map +0 -1
  291. package/lib/icons/material/round.d.ts.map +0 -1
  292. package/lib/icons/material/round.js.map +0 -1
  293. package/lib/icons/material/sharp.d.ts.map +0 -1
  294. package/lib/icons/material/sharp.js.map +0 -1
  295. package/lib/icons/material/two-tone.d.ts.map +0 -1
  296. package/lib/icons/material/two-tone.js.map +0 -1
  297. package/lib/index.d.ts.map +0 -1
  298. package/lib/index.js.map +0 -1
  299. package/lib/styles/button.d.ts.map +0 -1
  300. package/lib/styles/button.js.map +0 -1
  301. package/lib/styles/calendar-month.d.ts.map +0 -1
  302. package/lib/styles/calendar-month.js.map +0 -1
  303. package/lib/styles/calendar-navigation.d.ts.map +0 -1
  304. package/lib/styles/calendar-navigation.js.map +0 -1
  305. package/lib/styles/calendar.d.ts.map +0 -1
  306. package/lib/styles/calendar.js.map +0 -1
  307. package/lib/styles/checkbox.d.ts.map +0 -1
  308. package/lib/styles/checkbox.js.map +0 -1
  309. package/lib/styles/copy.d.ts.map +0 -1
  310. package/lib/styles/copy.js.map +0 -1
  311. package/lib/styles/custom-scrollbar.d.ts.map +0 -1
  312. package/lib/styles/custom-scrollbar.js.map +0 -1
  313. package/lib/styles/date-picker.d.ts.map +0 -1
  314. package/lib/styles/date-picker.js.map +0 -1
  315. package/lib/styles/dropdown.d.ts +0 -12
  316. package/lib/styles/dropdown.d.ts.map +0 -1
  317. package/lib/styles/dropdown.js +0 -983
  318. package/lib/styles/dropdown.js.map +0 -1
  319. package/lib/styles/icon.d.ts.map +0 -1
  320. package/lib/styles/icon.js.map +0 -1
  321. package/lib/styles/input.d.ts.map +0 -1
  322. package/lib/styles/input.js.map +0 -1
  323. package/lib/styles/modal.d.ts.map +0 -1
  324. package/lib/styles/modal.js.map +0 -1
  325. package/lib/styles/multiselect.d.ts +0 -6
  326. package/lib/styles/multiselect.d.ts.map +0 -1
  327. package/lib/styles/multiselect.js +0 -774
  328. package/lib/styles/multiselect.js.map +0 -1
  329. package/lib/styles/option.d.ts.map +0 -1
  330. package/lib/styles/option.js.map +0 -1
  331. package/lib/styles/popup.d.ts.map +0 -1
  332. package/lib/styles/popup.js.map +0 -1
  333. package/lib/styles/radio.d.ts.map +0 -1
  334. package/lib/styles/radio.js.map +0 -1
  335. package/lib/styles/resize-observer.d.ts.map +0 -1
  336. package/lib/styles/resize-observer.js.map +0 -1
  337. package/lib/styles/scroll-container.d.ts.map +0 -1
  338. package/lib/styles/scroll-container.js.map +0 -1
  339. package/lib/styles/step.d.ts.map +0 -1
  340. package/lib/styles/step.js.map +0 -1
  341. package/lib/styles/switch.d.ts.map +0 -1
  342. package/lib/styles/switch.js.map +0 -1
  343. package/lib/styles/tab.d.ts.map +0 -1
  344. package/lib/styles/tab.js.map +0 -1
  345. package/lib/styles/tabs.d.ts.map +0 -1
  346. package/lib/styles/tabs.js.map +0 -1
  347. package/lib/styles/tag.d.ts.map +0 -1
  348. package/lib/styles/tag.js.map +0 -1
  349. package/lib/styles/textarea.d.ts.map +0 -1
  350. package/lib/styles/textarea.js.map +0 -1
  351. package/lib/styles/tooltip.d.ts.map +0 -1
  352. package/lib/styles/tooltip.js.map +0 -1
  353. package/lib/styles/wizard.d.ts.map +0 -1
  354. package/lib/styles/wizard.js.map +0 -1
  355. package/lib/types/common.d.ts.map +0 -1
  356. package/lib/types/common.js.map +0 -1
  357. package/lib/utils/calendar-utils.d.ts.map +0 -1
  358. package/lib/utils/calendar-utils.js.map +0 -1
  359. package/lib/utils/custom-scrollbar.d.ts.map +0 -1
  360. package/lib/utils/custom-scrollbar.js.map +0 -1
  361. package/lib/utils/icon-registry.d.ts.map +0 -1
  362. package/lib/utils/icon-registry.js.map +0 -1
  363. package/lib/utils/locale.d.ts.map +0 -1
  364. package/lib/utils/locale.js.map +0 -1
  365. package/lib/utils/mobile.d.ts.map +0 -1
  366. package/lib/utils/mobile.js.map +0 -1
  367. package/lib/utils/number-format.d.ts.map +0 -1
  368. package/lib/utils/number-format.js.map +0 -1
  369. package/lib/utils/parse-boolean.d.ts +0 -39
  370. package/lib/utils/parse-boolean.d.ts.map +0 -1
  371. package/lib/utils/parse-boolean.js +0 -58
  372. package/lib/utils/parse-boolean.js.map +0 -1
  373. package/lib/utils/positioning.d.ts.map +0 -1
  374. package/lib/utils/positioning.js.map +0 -1
  375. package/lib/utils/property-capture.d.ts.map +0 -1
  376. package/lib/utils/property-capture.js.map +0 -1
  377. package/lib/utils/property-manager.d.ts.map +0 -1
  378. package/lib/utils/property-manager.js.map +0 -1
  379. package/lib/utils/resize-observer.d.ts.map +0 -1
  380. package/lib/utils/resize-observer.js.map +0 -1
  381. package/lib/utils/scroll-lock.d.ts.map +0 -1
  382. package/lib/utils/scroll-lock.js.map +0 -1
  383. package/lib/utils/styles.d.ts.map +0 -1
  384. package/lib/utils/styles.js.map +0 -1
  385. package/lib/version.d.ts.map +0 -1
  386. 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-RC20"}
15
+ dev.gersak/tyrell-icons-lucide {:mvn/version "1.0.0-RC20"}}} ; 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