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,300 @@
1
+ # ClojureScript + Tyrell Substrate Reference
2
+
3
+ > **Looking for the quickstart?** → [QUICKSTART.md](QUICKSTART.md) — two-track entry point (Reagent / re-frame / UIx / Helix via `tyrell.react`, or Replicant / vanilla via raw `<ty-*>`).
4
+
5
+ Use Tyrell from any ClojureScript app — Replicant, Reagent, UIx, Rum, or vanilla CLJS with no UI framework. This guide is the **substrate reference**: distribution, shadow-cljs setup, raw interop with web components, and icon tree-shaking.
6
+
7
+ For framework-specific patterns, see [REPLICANT_TY_GUIDE.md](REPLICANT_TY_GUIDE.md). The infrastructure guides ([ROUTING_GUIDE.md](ROUTING_GUIDE.md), [I18N_GUIDE.md](I18N_GUIDE.md), [LAYOUT_GUIDE.md](LAYOUT_GUIDE.md)) are already framework-agnostic.
8
+
9
+ ## What you get
10
+
11
+ CLJS users add **one Clojars dep** — `dev.gersak/tyrell` — and that brings everything they need:
12
+
13
+ | What you get | Where it comes from |
14
+ |---|---|
15
+ | Routing, i18n, layout, icon registry, shim | CLJS namespaces in the JAR (`tyrell.router`, `tyrell.i18n`, `tyrell.layout`, `tyrell.icons`, `tyrell.shim`) |
16
+ | Web Components — `<ty-button>`, `<ty-input>`, etc. | npm `tyrell-components`, declared in this artifact's `deps.cljs` and **auto-installed** into your `package.json` by shadow-cljs |
17
+ | `tyrell.components` shim | A side-effect-import wrapper around npm `tyrell-components`, so CLJS users only ever require `tyrell.*` namespaces |
18
+ | React wrappers — `tyrell.react/Button`, `tyrell.react/Input`, ... | CLJS namespace re-exporting npm `tyrell-react`. Track A (React-based CLJS) only — npm package is **not** auto-pulled (opt-in) |
19
+
20
+ Icons are separate Clojars artifacts, one per set: `dev.gersak/tyrell-icons-lucide` (`tyrell.lucide`), `-heroicons` (`tyrell.heroicons.*`), `-material` (`tyrell.material.*`) and `-fontawesome` (`tyrell.fav6.*`). `dev.gersak/tyrell-icons` pulls in all four. Each icon is an individual CLJS `def` — shadow-cljs `:advanced` removes unused ones automatically.
21
+
22
+ > **How npm auto-install works.** The `dev.gersak/tyrell` JAR ships with a `deps.cljs` at the classpath root that declares `{:npm-deps {"tyrell-components" "<pinned-version>"}}`. shadow-cljs reads it on each build and runs `npm install --save --save-exact tyrell-components@<version>`, so you never write that line manually. The entry will appear in your `package.json` after the first build — that's the standard shadow-cljs contract for library-declared npm deps.
23
+
24
+ ## Setup
25
+
26
+ [![Clojars Project](https://img.shields.io/clojars/v/dev.gersak/tyrell.svg)](https://clojars.org/dev.gersak/tyrell)
27
+
28
+ ### 1. Add one Clojars dep
29
+
30
+ `deps.edn`:
31
+
32
+ ```clojure
33
+ {:deps {dev.gersak/tyrell {:mvn/version "..."}}} ; latest from Clojars badge above
34
+ ```
35
+
36
+ That single dep brings:
37
+ - The CLJS infrastructure (`tyrell.router`, `tyrell.i18n`, `tyrell.layout`, `tyrell.icons`, `tyrell.shim`)
38
+ - The `tyrell.components` shim namespace that side-effect-imports the npm package
39
+
40
+ The npm `tyrell-components` package is declared in this artifact's `deps.cljs`, so shadow-cljs auto-installs it into your `package.json` on first build. No manual `npm install tyrell-components` needed.
41
+
42
+ Icons are not included. Add the set jars you use:
43
+ ```clojure
44
+ {:deps {dev.gersak/tyrell {:mvn/version "..."}
45
+ dev.gersak/tyrell-icons-lucide {:mvn/version "..."}}} ; tyrell.lucide
46
+ ```
47
+
48
+ ### 2. Load `tyrell.css`
49
+
50
+ Component classes only work once the stylesheet is loaded. shadow-cljs doesn't process CSS imports from CLJS, so you load it separately. Pick one of the paths in [`### CSS handling`](#css-handling) below — recap:
51
+
52
+ ```html
53
+ <!-- A. CDN <link> -->
54
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components@latest/css/tyrell.css">
55
+ <!-- tyrell-theme.css: auto-contrast, seed-based rebranding, themes. See TY_GUIDE.md#quick-start -->
56
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components@latest/css/tyrell-theme.css">
57
+ ```
58
+
59
+ ```bash
60
+ # B. Fetch into your public/ once
61
+ cp node_modules/tyrell-components/css/tyrell.css public/css/tyrell.css
62
+ cp node_modules/tyrell-components/css/tyrell-theme.css public/css/tyrell-theme.css
63
+ # Then <link> both in your HTML, brand.css after tyrell.css
64
+ ```
65
+
66
+ ```css
67
+ /* C. Tailwind / PostCSS pipeline — add to your CSS entrypoint */
68
+ @import "../node_modules/tyrell-components/css/tyrell.css";
69
+ @import "../node_modules/tyrell-components/css/tyrell-theme.css";
70
+ @import "tailwindcss";
71
+ ```
72
+
73
+ ### 3. Load components in your app
74
+
75
+ Two paths — pick one:
76
+
77
+ #### Path A — `tyrell.components` shim (recommended)
78
+
79
+ ```clojure
80
+ (ns my-app.core
81
+ (:require [tyrell.components])) ; side-effect: registers all <ty-*> elements
82
+ ```
83
+
84
+ That single CLJS require pulls in the npm package transitively (already declared via `deps.cljs`). Components are marked side-effectful in the npm package's `package.json`; icons are not — they only enter your bundle when you reference them.
85
+
86
+ For fine-grained tree-shaking, you can bypass the shim and import npm subpaths directly:
87
+
88
+ ```clojure
89
+ (ns my-app.core
90
+ (:require ["tyrell-components/button"]
91
+ ["tyrell-components/input"]
92
+ ["tyrell-components/dropdown"]
93
+ ["tyrell-components/modal"]))
94
+ ```
95
+
96
+ Subpaths match component names: `button`, `input`, `textarea`, `checkbox`, `dropdown`, `option`, `multiselect`, `tag`, `modal`, `popup`, `tooltip`, `tabs`, `tab`, `wizard`, `step`, `calendar`, `calendar-month`, `date-picker`, `icon`, `copy`, `resize-observer`, `scroll-container`.
97
+
98
+ #### Path B — CDN script tag
99
+
100
+ For server-rendered apps or when you don't want NPM in the loop:
101
+
102
+ ```html
103
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components@latest/css/tyrell.css">
104
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components@latest/css/tyrell-theme.css">
105
+ <script type="module" src="https://cdn.jsdelivr.net/npm/tyrell-components@latest/dist/tyrell.js"></script>
106
+ ```
107
+
108
+ The CDN bundle registers all components. From CLJS, you don't need to require anything — just use `<ty-*>` tags in your hiccup or DOM.
109
+
110
+ ### 4. Verify
111
+
112
+ ```clojure
113
+ (.appendChild js/document.body
114
+ (doto (js/document.createElement "ty-button")
115
+ (set! -textContent "Hello")))
116
+ ```
117
+
118
+ If a styled button renders, you're set.
119
+
120
+ ## Using Web Components from CLJS
121
+
122
+ The same three rules apply across every CLJS framework:
123
+
124
+ 1. **Event payload lives on `event.detail`.** In CLJS: `(.. e -detail -value)` or `(j/get-in e [:detail :value])`.
125
+ 2. **Properties vs attributes.** Booleans, arrays, objects must be set as JS properties, not attributes. Strings work as either.
126
+ 3. **Don't conflate CLJS data and the DOM.** A `ty-select multiple` `value` is a JS array, not a CLJS vector — convert with `(clj->js)` going in and `(js->clj)` coming out (or use `js/Array.from`).
127
+
128
+ ### Vanilla CLJS (no UI framework)
129
+
130
+ ```clojure
131
+ (ns my-app.core
132
+ (:require [tyrell.components]
133
+ [tyrell.icons :as icons]
134
+ [tyrell.lucide :as lucide]))
135
+
136
+ (defn render []
137
+ (let [root (js/document.getElementById "app")
138
+ input (doto (js/document.createElement "ty-input")
139
+ (.setAttribute "label" "Email")
140
+ (.setAttribute "type" "email"))
141
+ button (doto (js/document.createElement "ty-button")
142
+ (.setAttribute "flavor" "primary")
143
+ (set! -textContent "Submit"))]
144
+ (.addEventListener input "change"
145
+ (fn [e]
146
+ (js/console.log "email:" (.. e -detail -value))))
147
+ (.addEventListener button "click"
148
+ (fn [_]
149
+ (js/console.log "value:" (.-value input))))
150
+ (.appendChild root input)
151
+ (.appendChild root button)))
152
+
153
+ (defn ^:export init []
154
+ (icons/register! {:check lucide/check})
155
+ (render))
156
+ ```
157
+
158
+ ### Hiccup (Replicant, Reagent, UIx, Rum)
159
+
160
+ Hiccup-based frameworks render `<ty-*>` tags directly. Each framework's idioms differ slightly — see [REPLICANT_TY_GUIDE.md](REPLICANT_TY_GUIDE.md) for one full example. The key concerns are framework-specific:
161
+
162
+ | Framework | Set property (not attribute) | Listen to event |
163
+ |---|---|---|
164
+ | Replicant | `:replicant/key` for stable identity; properties via DOM ops or `:dom/on-mount` | `[:on/change handler]` |
165
+ | Reagent | `:value-for-typeahead` etc. work as attrs; complex → use `:ref` | `:on-change` (lowercased) |
166
+ | UIx (Helix) | `$d` for DOM elements; props are camelCased | `:on-change` |
167
+ | Rum | Refs for property setting | `:on-change` |
168
+
169
+ Across all of them, `event.detail.value` access in CLJS:
170
+
171
+ ```clojure
172
+ (fn [e] (.. e -detail -value))
173
+ ```
174
+
175
+ ### React-based CLJS — use `tyrell.react`
176
+
177
+ For Reagent, re-frame, UIx, and Helix, prefer the wrappers from `tyrell.react` over raw `<ty-*>` tags. React's synthetic event system doesn't bridge custom events — `[:> :ty-input {:on-change ...}]` would never fire with `event.detail.value`. The wrappers attach `addEventListener` on the underlying element so `:on-change` works the way React libs expect.
178
+
179
+ ```clojure
180
+ (ns my-app.core
181
+ (:require [tyrell.components] ; side-effect: registers <ty-*> elements
182
+ [tyrell.react :as ty] ; React component vars
183
+ [reagent.core :as r]))
184
+
185
+ [:> ty/Input
186
+ {:label "Email"
187
+ :value @email
188
+ :on-change #(reset! email (.. % -detail -value))}]
189
+
190
+ [:> ty/Button {:flavor "primary"} "Save"]
191
+ ```
192
+
193
+ `tyrell.react` is a CLJS shim inside `dev.gersak/tyrell` that re-exports the wrappers from npm `tyrell-react`. The npm package itself is **not** auto-installed — install it explicitly the same way you install `react` and `react-dom`:
194
+
195
+ ```bash
196
+ npm install tyrell-react
197
+ ```
198
+
199
+ Track B users (Replicant, vanilla) skip this step. Each wrapper exports under both `TyButton`/`TyInput` and short `Button`/`Input` names — pick one style.
200
+
201
+ ## Icon registration in CLJS
202
+
203
+ `<ty-icon name="…">` is a runtime lookup, so register the icons you use. Each icon is a `def` holding an SVG string; `:advanced` drops the ones you don't reference.
204
+
205
+ ```clojure
206
+ (ns my-app.icons
207
+ (:require [tyrell.icons :as icons]
208
+ [tyrell.lucide :as lucide]))
209
+
210
+ (icons/register! {:check lucide/check
211
+ :user lucide/user}) ; the key is the name
212
+ ```
213
+
214
+ Don't build names at runtime (`(symbol "lucide" name)`): the compiler can't see them. Register every candidate up front.
215
+
216
+ Sets, tree-shaking, custom SVGs and troubleshooting: [ICONS_GUIDE.md](../ICONS_GUIDE.md#in-clojure).
217
+
218
+ ## Shadow-cljs configuration tips
219
+
220
+ ### `:js-options` for npm interop
221
+
222
+ Default config works. If you see issues with `tyrell-components` ESM imports:
223
+
224
+ ```clojure
225
+ {:builds
226
+ {:app
227
+ {:target :browser
228
+ :js-options {:resolve {"tyrell-components" {:target :npm
229
+ :require "tyrell-components"}}}}}}
230
+ ```
231
+
232
+ Usually unnecessary — shadow-cljs autodetects.
233
+
234
+ ### CSS handling
235
+
236
+ Shadow-cljs doesn't process CSS imports from CLJS — `tyrell.css` lives outside the JS module graph and must be loaded separately. The simplest path is a `<link>` to the CDN:
237
+
238
+ ```html
239
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components@latest/css/tyrell.css">
240
+ <!-- tyrell-theme.css: auto-contrast, seed-based rebranding, themes. See TY_GUIDE.md#quick-start -->
241
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components@latest/css/tyrell-theme.css">
242
+ ```
243
+
244
+ For offline-friendly local dev, fetch the files once into your static directory:
245
+
246
+ ```bash
247
+ # Pin a version, no npm install required (use the version from the badge or your package.json)
248
+ curl -o public/css/tyrell.css https://cdn.jsdelivr.net/npm/tyrell-components@latest/css/tyrell.css
249
+ curl -o public/css/tyrell-theme.css https://cdn.jsdelivr.net/npm/tyrell-components@latest/css/tyrell-theme.css
250
+
251
+ # Or copy from the version shadow-cljs already installed (after first build)
252
+ cp node_modules/tyrell-components/css/tyrell.css public/css/tyrell.css
253
+ cp node_modules/tyrell-components/css/tyrell-theme.css public/css/tyrell-theme.css
254
+ ```
255
+
256
+ Wire the second form as a `postinstall` script in `package.json` to keep the files in sync with whatever shadow-cljs installs:
257
+
258
+ ```json
259
+ "scripts": {
260
+ "postinstall": "mkdir -p public/css && cp node_modules/tyrell-components/css/tyrell*.css public/css/"
261
+ }
262
+ ```
263
+
264
+ Then reference both with `<link>`, brand.css after tyrell.css. The `cp` form auto-tracks whatever version is installed by your deps.
265
+
266
+ Projects with a CSS pipeline (Tailwind, PostCSS) can import the files directly into their entrypoint instead:
267
+
268
+ ```css
269
+ @import "../node_modules/tyrell-components/css/tyrell.css";
270
+ @import "../node_modules/tyrell-components/css/tyrell-theme.css";
271
+ @import "tailwindcss";
272
+ ```
273
+
274
+ Tyrell's CSS gets bundled into your output stylesheet alongside everything else.
275
+
276
+ ### Code splitting (lazy loading)
277
+
278
+ See [CODE_SPLITTING.md](CODE_SPLITTING.md) for shadow-cljs `:modules` setup. Pattern: defer heavy components (calendar/date-picker/dropdown) until the route that needs them loads.
279
+
280
+ ## What's CLJS-specific
281
+
282
+ A few things differ from JS:
283
+
284
+ - **One Clojars dep covers everything** — `dev.gersak/tyrell` declares the npm `tyrell-components` package via `deps.cljs`, so you `:require [tyrell.components]` once and shadow-cljs handles npm install + module resolution. JS users do `npm install tyrell-components` directly; CLJS users don't need to.
285
+ - **No `'use client'` boundary** — shadow-cljs targets the browser by default. SSR with `:target :node` requires extra care; see existing CLJS SSR docs (out of scope here).
286
+ - **Icons can use keyword names** — `(icons/register! {:check lucide/check})` is idiomatic. Strings also work.
287
+ - **Property setting** — CLJS hiccup renderers (Reagent, Replicant, UIx) all have framework-specific quirks for setting JS properties vs HTML attributes. The component itself doesn't care; the framework's bridge does.
288
+ - **React wrappers via CLJS namespace** — `tyrell.react` re-exports `tyrell-react`'s components, so React-based CLJS frameworks alias `[tyrell.react :as ty]` instead of `["tyrell-react" :as ty]`. The npm package still needs to be installed manually (Track A only).
289
+
290
+ ## See also
291
+
292
+ - [TY_GUIDE.md](../TY_GUIDE.md) — universal component API reference
293
+ - [CSS_GUIDE.md](../CSS_GUIDE.md) — design system
294
+ - [REPLICANT_TY_GUIDE.md](REPLICANT_TY_GUIDE.md) — Replicant-specific integration patterns
295
+ - [ROUTING_GUIDE.md](ROUTING_GUIDE.md) — `tyrell.router` (framework-agnostic)
296
+ - [I18N_GUIDE.md](I18N_GUIDE.md) — `tyrell.i18n` (framework-agnostic)
297
+ - [LAYOUT_GUIDE.md](LAYOUT_GUIDE.md) — `tyrell.layout` (framework-agnostic)
298
+ - [COMPONENT_GUIDE.md](COMPONENT_GUIDE.md) — `tyrell.shim` for building Web Components in CLJS
299
+ - [CODE_SPLITTING.md](CODE_SPLITTING.md) — shadow-cljs lazy loading
300
+ - [../js/JAVASCRIPT_GUIDE.md](../js/JAVASCRIPT_GUIDE.md) — JS-side substrate (bundlers, side-effects, SSR)
@@ -0,0 +1,279 @@
1
+ # Code Splitting & Lazy Loading
2
+
3
+ > **Note:** This guide describes patterns and strategies, not exact code to copy. File names, module names, and folder structures are illustrative examples — adapt them to your project's conventions.
4
+
5
+ ## Overview
6
+
7
+ Tyrell uses shadow-cljs module system to split components into separate chunks:
8
+
9
+ ```
10
+ ty-lazy.js (core + lightweight components)
11
+ ty-select.js (loaded when <ty-select> is used)
12
+ ty-calendar.js (loaded when <ty-calendar> is used)
13
+ ty-date-picker.js (loaded when <ty-date-picker> is used)
14
+ ```
15
+
16
+ ---
17
+
18
+ ## shadow-cljs Configuration
19
+
20
+ ```clojure
21
+ ;; shadow-cljs.edn
22
+ {:builds
23
+ {:lib
24
+ {:target :browser
25
+ :output-dir "dist/"
26
+ :module-loader true ;; Enable dynamic loading
27
+
28
+ :modules
29
+ {;; Core module - always loaded
30
+ :ty-core
31
+ {:entries [tyrell.core]
32
+ :init-fn tyrell.core/init}
33
+
34
+ ;; Lazy modules - loaded on demand
35
+ :ty-select
36
+ {:entries [tyrell.components.select]
37
+ :depends-on #{:ty-core}}
38
+
39
+ :ty-calendar
40
+ {:entries [tyrell.components.calendar
41
+ tyrell.components.calendar-navigation
42
+ tyrell.components.calendar-month]
43
+ :depends-on #{:ty-core}}
44
+
45
+ :ty-date-picker
46
+ {:entries [tyrell.components.date-picker]
47
+ :depends-on #{:ty-calendar}}
48
+
49
+ :ty-selected-options
50
+ {:entries [tyrell.components.selected-tags]
51
+ :depends-on #{:ty-select}}}}}}
52
+ ```
53
+
54
+ ---
55
+
56
+ ## Creating a Lazy Component Wrapper
57
+
58
+ ### 1. The Real Component
59
+
60
+ ```clojure
61
+ ;; src/app/components/heavy_chart.cljs
62
+ (ns app.components.heavy-chart
63
+ (:require [tyrell.shim :as shim]
64
+ ["chart.js" :as Chart])) ;; Heavy dependency
65
+
66
+ (defn render! [^js el]
67
+ ;; Complex chart rendering...
68
+ )
69
+
70
+ (def configuration
71
+ {:observed [:data :type]
72
+ :connected render!
73
+ :attr (fn [el _] (render! el))})
74
+ ```
75
+
76
+ ### 2. The Lazy Wrapper
77
+
78
+ ```clojure
79
+ ;; src/app/components/lazy/heavy_chart.cljs
80
+ (ns app.components.lazy.heavy-chart
81
+ (:require [shadow.lazy :as lazy]
82
+ [tyrell.shim :as shim]))
83
+
84
+ ;; Mark the config as loadable
85
+ (def config (lazy/loadable app.components.heavy-chart/configuration))
86
+
87
+ ;; Define component with lazy lifecycle
88
+ (defn lazy-connected [^js el]
89
+ (-> (lazy/load config)
90
+ (.then (fn [cfg]
91
+ ((:connected cfg) el)))))
92
+
93
+ (defn lazy-attr [^js el delta]
94
+ (-> (lazy/load config)
95
+ (.then (fn [cfg]
96
+ ((:attr cfg) el delta)))))
97
+
98
+ (shim/define! "app-heavy-chart"
99
+ {:observed [:data :type]
100
+ :connected lazy-connected
101
+ :attr lazy-attr})
102
+ ```
103
+
104
+ ### 3. Configure Module
105
+
106
+ ```clojure
107
+ ;; shadow-cljs.edn
108
+ :modules
109
+ {:app-core
110
+ {:entries [app.core
111
+ app.components.lazy.heavy-chart] ;; Wrapper in core
112
+ :init-fn app.core/init}
113
+
114
+ :app-heavy-chart
115
+ {:entries [app.components.heavy-chart] ;; Real component separate
116
+ :depends-on #{:app-core}}}
117
+ ```
118
+
119
+ ---
120
+
121
+ ## Utility Helper
122
+
123
+ Simplify with a reusable helper:
124
+
125
+ ```clojure
126
+ ;; src/app/lazy_util.cljs
127
+ (ns app.lazy-util
128
+ (:require [shadow.lazy :as lazy]))
129
+
130
+ (defn create-lazy-lifecycle
131
+ "Create lazy-loading lifecycle hooks from a loadable config"
132
+ [loadable-config]
133
+ {:connected
134
+ (fn [^js el]
135
+ (-> (lazy/load loadable-config)
136
+ (.then #((:connected %) el))))
137
+
138
+ :disconnected
139
+ (fn [^js el]
140
+ (-> (lazy/load loadable-config)
141
+ (.then #(when-let [f (:disconnected %)] (f el)))))
142
+
143
+ :attr
144
+ (fn [^js el delta]
145
+ (-> (lazy/load loadable-config)
146
+ (.then #((:attr %) el delta))))
147
+
148
+ :prop
149
+ (fn [^js el delta]
150
+ (-> (lazy/load loadable-config)
151
+ (.then #((:prop %) el delta))))})
152
+ ```
153
+
154
+ Then your lazy wrapper becomes:
155
+
156
+ ```clojure
157
+ (ns app.components.lazy.heavy-chart
158
+ (:require [shadow.lazy :as lazy]
159
+ [app.lazy-util :as lazy-util]
160
+ [tyrell.shim :as shim]))
161
+
162
+ (def config (lazy/loadable app.components.heavy-chart/configuration))
163
+
164
+ (shim/define! "app-heavy-chart"
165
+ (merge
166
+ {:observed [:data :type]}
167
+ (lazy-util/create-lazy-lifecycle config)))
168
+ ```
169
+
170
+ ---
171
+
172
+ ## Loading States
173
+
174
+ Show a placeholder while the component loads:
175
+
176
+ ```clojure
177
+ (defn lazy-connected [^js el]
178
+ (let [root (shim/ensure-shadow el)]
179
+ ;; Show loading state immediately
180
+ (set! (.-innerHTML root)
181
+ "<div class='ty-text- animate-pulse'>Loading...</div>")
182
+
183
+ ;; Load and render real component
184
+ (-> (lazy/load config)
185
+ (.then (fn [cfg]
186
+ ((:connected cfg) el))))))
187
+ ```
188
+
189
+ ---
190
+
191
+ ## Preloading
192
+
193
+ Preload modules you expect to need soon:
194
+
195
+ ```clojure
196
+ (ns app.core
197
+ (:require [shadow.lazy :as lazy]))
198
+
199
+ ;; Preload on hover
200
+ (defn preload-on-hover! [trigger-el loadable]
201
+ (.addEventListener trigger-el "mouseenter"
202
+ (fn [] (lazy/load loadable)) #js {:once true}))
203
+
204
+ ;; Preload after idle
205
+ (defn preload-when-idle! [loadable]
206
+ (if js/requestIdleCallback
207
+ (js/requestIdleCallback #(lazy/load loadable))
208
+ (js/setTimeout #(lazy/load loadable) 200)))
209
+ ```
210
+
211
+ ---
212
+
213
+ ## Bundle Analysis
214
+
215
+ Check your bundle sizes:
216
+
217
+ ```bash
218
+ # Build with report
219
+ npx shadow-cljs release lib --config-merge '{:build-report true}'
220
+
221
+ # View report
222
+ open target/shadow-cljs/build-report.html
223
+ ```
224
+
225
+ ---
226
+
227
+ ## Best Practices
228
+
229
+ 1. **Core module should be small** - Only essential components and initialization
230
+ 2. **Group related components** - Calendar + navigation + month in one module
231
+ 3. **Consider dependencies** - If A always needs B, put them together
232
+ 4. **Lazy load heavy dependencies** - Chart libs, date libs, etc.
233
+ 5. **Preload predictable paths** - User will likely click "Settings"? Preload it
234
+
235
+ ---
236
+
237
+ ## Example: Full App Structure
238
+
239
+ ```
240
+ src/
241
+ ├── app/
242
+ │ ├── core.cljs ;; Init, router, lightweight components
243
+ │ ├── components/
244
+ │ │ ├── button.cljs ;; In core (used everywhere)
245
+ │ │ ├── input.cljs ;; In core
246
+ │ │ ├── heavy_table.cljs ;; Separate module
247
+ │ │ ├── chart.cljs ;; Separate module
248
+ │ │ └── lazy/
249
+ │ │ ├── heavy_table.cljs
250
+ │ │ └── chart.cljs
251
+ │ └── lazy_util.cljs
252
+ ```
253
+
254
+ ```clojure
255
+ ;; shadow-cljs.edn
256
+ :modules
257
+ {:app-core
258
+ {:entries [app.core
259
+ app.components.button
260
+ app.components.input
261
+ app.components.lazy.heavy-table
262
+ app.components.lazy.chart]
263
+ :init-fn app.core/init}
264
+
265
+ :app-table
266
+ {:entries [app.components.heavy-table]
267
+ :depends-on #{:app-core}}
268
+
269
+ :app-chart
270
+ {:entries [app.components.chart]
271
+ :depends-on #{:app-core}}}
272
+ ```
273
+
274
+ ---
275
+
276
+ ## See Also
277
+
278
+ - [shadow-cljs Code Splitting](https://shadow-cljs.github.io/docs/UsersGuide.html#CodeSplitting)
279
+ - [Component Building Guide](COMPONENT_GUIDE.md) - tyrell.shim API for defining web components