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,273 @@
1
+ # Tyrell Layout — Responsive Layout System
2
+
3
+ The `tyrell.layout` namespace provides container-aware responsive layout for ClojureScript. It uses dynamic vars to propagate container dimensions down the render tree, with Tailwind-matching breakpoints.
4
+
5
+ ## Core Concept
6
+
7
+ Instead of CSS media queries (which respond to the **window**), `tyrell.layout` responds to the **container** — the actual available space for your content. This enables nested responsive layouts where a sidebar panel can respond to its own width, not the window width.
8
+
9
+ The `*container*` dynamic var holds the current dimensions. Macros like `with-window`, `with-container`, and `with-resize-observer` bind it for their body.
10
+
11
+ ---
12
+
13
+ ## Setup
14
+
15
+ ```clojure
16
+ (ns my-app.core
17
+ (:require [tyrell.layout :as layout]))
18
+ ```
19
+
20
+ ---
21
+
22
+ ## `with-window`
23
+
24
+ Binds `*container*` to window dimensions. Automatically tracks resize events. Use this at the root of your app:
25
+
26
+ ```clojure
27
+ (defn app []
28
+ (layout/with-window
29
+ (let [mobile? (layout/breakpoint<= :sm)]
30
+ [:div.ty-canvas
31
+ (when-not mobile? (sidebar))
32
+ (main-content)])))
33
+ ```
34
+
35
+ `with-window` registers a resize listener on `js/window` and reads from the `window-size` atom.
36
+
37
+ ## `with-container`
38
+
39
+ Binds `*container*` to explicit dimensions. Use this when you know the available space (e.g., after subtracting a header or sidebar):
40
+
41
+ ```clojure
42
+ (layout/with-container {:width 800 :height 600}
43
+ (my-component))
44
+ ```
45
+
46
+ Automatically calculates `:breakpoint`, `:orientation`, and `:density` from the given dimensions.
47
+
48
+ You can nest `with-container` — inner bindings merge with outer ones:
49
+
50
+ ```clojure
51
+ (layout/with-window
52
+ ;; *container* = window dimensions
53
+ (let [sidebar-width 220
54
+ header-height 60]
55
+ (layout/with-container
56
+ {:width (- (layout/container-width) sidebar-width)
57
+ :height (- (layout/container-height) header-height)}
58
+ ;; *container* = content area dimensions
59
+ (content-area))))
60
+ ```
61
+
62
+ ## `with-resize-observer`
63
+
64
+ Binds `*container*` from a `ty-resize-observer` web component's tracked dimensions. The observer is registered on the TypeScript side — this macro reads from it:
65
+
66
+ ```clojure
67
+ ;; HTML: <ty-resize-observer id="sidebar"></ty-resize-observer>
68
+
69
+ (layout/with-resize-observer "sidebar"
70
+ ;; *container* = sidebar's actual dimensions
71
+ (sidebar-content))
72
+ ```
73
+
74
+ If the element hasn't mounted yet (no size available), the body executes without binding — so it's safe to use during initial render.
75
+
76
+ ---
77
+
78
+ ## Querying Container State
79
+
80
+ ### Dimensions
81
+
82
+ ```clojure
83
+ (layout/container-width) ; => 1024
84
+ (layout/container-height) ; => 768
85
+ (layout/current-container) ; => {:width 1024 :height 768 :breakpoint :lg ...}
86
+ ```
87
+
88
+ ### Breakpoints
89
+
90
+ Matches Tailwind defaults:
91
+
92
+ | Breakpoint | Min Width |
93
+ |------------|-----------|
94
+ | `:xs` | 0px |
95
+ | `:sm` | 640px |
96
+ | `:md` | 768px |
97
+ | `:lg` | 1024px |
98
+ | `:xl` | 1280px |
99
+ | `:2xl` | 1536px |
100
+
101
+ ```clojure
102
+ (layout/container-breakpoint) ; => :lg
103
+
104
+ (layout/breakpoint>= :md) ; true if container is md or larger
105
+ (layout/breakpoint<= :sm) ; true if container is sm or smaller
106
+ (layout/breakpoint= :lg) ; true if exactly lg
107
+ (layout/breakpoint-between :sm :lg) ; true if sm, md, or lg
108
+ ```
109
+
110
+ ### Orientation
111
+
112
+ ```clojure
113
+ (layout/container-orientation) ; => :landscape, :portrait, or :square
114
+ (layout/portrait?) ; => true/false
115
+ (layout/landscape?)
116
+ (layout/square?)
117
+ ```
118
+
119
+ Calculated from width/height ratio: < 0.95 = portrait, > 1.05 = landscape, between = square.
120
+
121
+ ### Density
122
+
123
+ ```clojure
124
+ (layout/container-density) ; => :compact, :normal, or :comfortable
125
+ (layout/compact?) ; true if width < 768 (mobile)
126
+ (layout/comfortable?) ; true if width >= 1280 (large desktop)
127
+ ```
128
+
129
+ ---
130
+
131
+ ## Responsive Values
132
+
133
+ Pick a value based on the current breakpoint. Falls back to the next smaller breakpoint if the current one isn't specified:
134
+
135
+ ```clojure
136
+ (layout/responsive-value
137
+ {:xs 1
138
+ :sm 2
139
+ :md 3
140
+ :lg 4
141
+ :xl 6})
142
+ ; => 4 (when breakpoint is :lg)
143
+ ; => 3 (when breakpoint is :md)
144
+ ; => 2 (when breakpoint is :sm or :xs, since :xs falls to :xs=1, :sm=2)
145
+
146
+ ;; Use for classes
147
+ (layout/responsive-class
148
+ {:xs "flex-col"
149
+ :md "flex-row"})
150
+ ; => "flex-row" (when breakpoint >= :md)
151
+ ```
152
+
153
+ ---
154
+
155
+ ## Grid Helpers
156
+
157
+ ```clojure
158
+ ;; Get columns for current breakpoint (with defaults)
159
+ (layout/grid-columns)
160
+ ; => 1 (xs), 2 (sm), 3 (md), 4 (lg), 6 (xl), 8 (2xl)
161
+
162
+ ;; Custom column map
163
+ (layout/grid-columns {:xs 1 :md 2 :xl 3})
164
+
165
+ ;; Get gap for current breakpoint (with defaults)
166
+ (layout/grid-gap)
167
+ ; => 8 (xs), 12 (sm), 16 (md), 20 (lg), 24 (xl)
168
+
169
+ (layout/grid-gap {:xs 4 :md 8 :lg 16})
170
+ ```
171
+
172
+ ---
173
+
174
+ ## Percentage and Aspect Ratio
175
+
176
+ ```clojure
177
+ ;; Percentage of container dimensions
178
+ (layout/width% 50) ; => 512 (if container width is 1024)
179
+ (layout/height% 25) ; => 192 (if container height is 768)
180
+
181
+ ;; Current aspect ratio
182
+ (layout/aspect-ratio) ; => 1.333 (1024/768)
183
+
184
+ ;; Fit within container while maintaining target ratio
185
+ (layout/maintain-aspect-ratio (/ 16 9))
186
+ ; => {:width 1024 :height 576}
187
+ ```
188
+
189
+ ---
190
+
191
+ ## Resize Observer Integration
192
+
193
+ Read dimensions from the TypeScript `ty-resize-observer` registry directly:
194
+
195
+ ```clojure
196
+ ;; Get size of a specific observed element
197
+ (layout/get-observer-size "my-container")
198
+ ; => {:width 400 :height 300}
199
+
200
+ ;; Get all observed sizes
201
+ (layout/get-all-observer-sizes)
202
+ ; => {"container-1" {:width 400 :height 300}
203
+ ; "container-2" {:width 800 :height 600}}
204
+
205
+ ;; Observe an element directly (returns cleanup fn)
206
+ (let [cleanup (layout/observe-element! my-dom-element
207
+ (fn [{:keys [width height]}]
208
+ (println "Resized to" width "x" height)))]
209
+ ;; Later:
210
+ (cleanup))
211
+ ```
212
+
213
+ ---
214
+
215
+ ## Window Tracking
216
+
217
+ ```clojure
218
+ ;; Window size is tracked automatically when with-window is used.
219
+ ;; Read it directly if needed:
220
+ @layout/window-size ; => {:width 1920 :height 1080}
221
+
222
+ ;; Stop tracking (cleanup)
223
+ (layout/stop-window-tracking!)
224
+ ```
225
+
226
+ ---
227
+
228
+ ## Complete Example
229
+
230
+ ```clojure
231
+ (ns my-app.core
232
+ (:require [tyrell.layout :as layout]
233
+ [tyrell.router :as router]))
234
+
235
+ (defn sidebar []
236
+ (when (layout/breakpoint>= :lg)
237
+ [:nav.ty-elevated.p-4.rounded-lg
238
+ {:style {:width "220px"}}
239
+ [:h3.ty-text+.font-bold.mb-4 "Navigation"]
240
+ ;; nav items...
241
+ ]))
242
+
243
+ (defn card-grid [items]
244
+ (let [cols (layout/grid-columns {:xs 1 :sm 2 :lg 3})
245
+ gap (layout/grid-gap {:xs 8 :md 16})]
246
+ [:div {:style {:display "grid"
247
+ :grid-template-columns (str "repeat(" cols ", 1fr)")
248
+ :gap (str gap "px")}}
249
+ (for [item items]
250
+ ^{:key (:id item)}
251
+ [:div.ty-elevated.p-4.rounded-lg
252
+ [:h3.ty-text++ (:title item)]
253
+ [:p.ty-text- (:desc item)]])]))
254
+
255
+ (defn content []
256
+ [:main.min-w-0
257
+ [:h1.ty-text++.text-2xl.mb-6 "Dashboard"]
258
+ (card-grid items)])
259
+
260
+ (defn app []
261
+ (layout/with-window
262
+ (let [show-sidebar? (layout/breakpoint>= :lg)
263
+ header-height 60]
264
+ [:div.ty-canvas.flex.flex-col {:style {:height "100vh"}}
265
+ (header)
266
+ [:div.flex.flex-1.overflow-hidden
267
+ (sidebar)
268
+ (layout/with-container
269
+ {:width (cond-> (layout/container-width)
270
+ show-sidebar? (- 220 48))
271
+ :height (- (layout/container-height) header-height)}
272
+ (content))]])))
273
+ ```
@@ -0,0 +1,266 @@
1
+ # Tyrell + ClojureScript Quickstart
2
+
3
+ Get Tyrell running in your CLJS app in under five minutes. Pick the track that matches your view layer.
4
+
5
+ | You're using | Track | Component access |
6
+ |-------------------------------------------|-------|------------------|
7
+ | Reagent, re-frame, UIx, Helix | **A** | `tyrell.react` — React wrappers that bridge `event.detail.value` |
8
+ | Replicant, vanilla CLJS, server-rendered | **B** | Raw `<ty-*>` web components — no wrapper needed |
9
+
10
+ The infrastructure — routing, i18n, layout, icons — comes from `dev.gersak/tyrell` (Clojars) and works **on both tracks**.
11
+
12
+ ---
13
+
14
+ ## Common setup (both tracks)
15
+
16
+ [![Clojars Project](https://img.shields.io/clojars/v/dev.gersak/tyrell.svg)](https://clojars.org/dev.gersak/tyrell)
17
+
18
+ ### 1. Add one Clojars dep
19
+
20
+ `deps.edn`:
21
+
22
+ ```clojure
23
+ {:deps {dev.gersak/tyrell {:mvn/version "..."}}} ; latest from Clojars badge above
24
+ ```
25
+
26
+ That single dep brings the CLJS side:
27
+ - `tyrell.router`, `tyrell.i18n`, `tyrell.layout`, `tyrell.icons`, `tyrell.components`, `tyrell.react` — infrastructure + shims
28
+ - npm `tyrell-components` — declared in `deps.cljs`, shadow-cljs auto-installs it into your `package.json` on first build. No manual `npm install` for components.
29
+
30
+ Icons are separate jars, one per set. Add the ones you use:
31
+ ```clojure
32
+ {:deps {dev.gersak/tyrell {:mvn/version "..."}
33
+ dev.gersak/tyrell-icons-lucide {:mvn/version "..."}}} ; tyrell.lucide
34
+ ```
35
+ `-heroicons`, `-material` and `-fontawesome` work the same way; `dev.gersak/tyrell-icons` brings all four.
36
+
37
+ **Track A only** — React-based CLJS (Reagent, re-frame, UIx, Helix) needs `tyrell-react` installed explicitly, same way you install React itself:
38
+
39
+ ```bash
40
+ npm install tyrell-react
41
+ ```
42
+
43
+ ### 2. Load the CSS
44
+
45
+ `tyrell.css` lives outside the JS module graph and must be loaded separately. Pick one:
46
+
47
+ ```html
48
+ <!-- A. CDN <link> -->
49
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components@latest/css/tyrell.css">
50
+ <!-- tyrell-theme.css: auto-contrast, seed-based rebranding, themes. See TY_GUIDE.md#quick-start -->
51
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components@latest/css/tyrell-theme.css">
52
+ ```
53
+
54
+ ```bash
55
+ # B. Fetch into your public/ once (offline-friendly)
56
+ curl -o public/css/tyrell.css \
57
+ https://cdn.jsdelivr.net/npm/tyrell-components@latest/css/tyrell.css
58
+ curl -o public/css/tyrell-theme.css \
59
+ https://cdn.jsdelivr.net/npm/tyrell-components@latest/css/tyrell-theme.css
60
+
61
+ # Or copy from the version shadow-cljs already installed
62
+ cp node_modules/tyrell-components/css/tyrell.css public/css/tyrell.css
63
+ cp node_modules/tyrell-components/css/tyrell-theme.css public/css/tyrell-theme.css
64
+ ```
65
+
66
+ ```css
67
+ /* C. Tailwind / PostCSS — add to your input.css */
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
+ Wire (B) as a `postinstall` script in `package.json` to keep it in sync with installed versions automatically.
74
+
75
+ ### 3. Register web components
76
+
77
+ ```clojure
78
+ (ns my-app.core
79
+ (:require [tyrell.components])) ; side-effect: registers all <ty-*> elements
80
+ ```
81
+
82
+ That single require is enough. Components are marked side-effectful in npm's `package.json`; icons are not — they only enter your bundle when you reference them.
83
+
84
+ > **How does the npm package get there?** `dev.gersak/tyrell` ships with a `deps.cljs` declaring `{:npm-deps {"tyrell-components" "<pinned>"}}`. shadow-cljs reads it on first build and runs `npm install --save --save-exact`, so the entry lands in your `package.json` automatically. You'll see it there after the first build — that's expected, it's the standard shadow-cljs contract for library-declared npm deps.
85
+
86
+ ---
87
+
88
+ ## Track A — React-based CLJS
89
+
90
+ ### Reagent / re-frame
91
+
92
+ ```clojure
93
+ (ns my-app.core
94
+ (:require [tyrell.components]
95
+ [tyrell.react :refer [Button Input]]
96
+ [reagent.core :as r]))
97
+
98
+ (defn login-form []
99
+ (let [email (r/atom "")]
100
+ (fn []
101
+ [:form.flex.flex-col.gap-3
102
+ [:> Input {:label "Email"
103
+ :type "email"
104
+ :value @email
105
+ :on-change #(reset! email (.. % -detail -value))}]
106
+ [:> Button {:flavor "primary" :type "submit"} "Sign in"]])))
107
+ ```
108
+
109
+ re-frame is identical — swap `r/atom` and `reset!` for `subscribe`/`dispatch`:
110
+
111
+ ```clojure
112
+ [:> Input {:value @(rf/subscribe [:email])
113
+ :on-change #(rf/dispatch [:set-email (.. % -detail -value)])}]
114
+ ```
115
+
116
+ ### UIx
117
+
118
+ ```clojure
119
+ (ns my-app.core
120
+ (:require [tyrell.components]
121
+ [tyrell.react :refer [Button Input]]
122
+ [uix.core :refer [defui $ use-state]]))
123
+
124
+ (defui login-form []
125
+ (let [[email set-email] (use-state "")]
126
+ ($ :form {:class "flex flex-col gap-3"}
127
+ ($ Input {:label "Email"
128
+ :type "email"
129
+ :value email
130
+ :on-change #(set-email (.. % -detail -value))})
131
+ ($ Button {:flavor "primary" :type "submit"} "Sign in"))))
132
+ ```
133
+
134
+ ### Helix
135
+
136
+ ```clojure
137
+ (ns my-app.core
138
+ (:require [tyrell.components]
139
+ [tyrell.react :refer [Button Input]]
140
+ [helix.core :refer [defnc $]]
141
+ [helix.dom :as d]
142
+ [helix.hooks :refer [use-state]]))
143
+
144
+ (defnc login-form []
145
+ (let [[email set-email] (use-state "")]
146
+ (d/form {:class "flex flex-col gap-3"}
147
+ ($ Input {:label "Email"
148
+ :type "email"
149
+ :value email
150
+ :on-change #(set-email (.. % -detail -value))})
151
+ ($ Button {:flavor "primary" :type "submit"} "Sign in"))))
152
+ ```
153
+
154
+ ### Why `tyrell.react` here
155
+
156
+ Web components dispatch custom events with `event.detail`. React's synthetic event system doesn't bridge those — `[:> :ty-input {:on-change ...}]` would only catch native bubbling events, not `<ty-input>`'s `change` with `event.detail.value`. The wrappers add the listener on the underlying element so `:on-change` works the way you'd expect.
157
+
158
+ `tyrell.react` is a thin CLJS namespace inside `dev.gersak/tyrell` that re-exports the wrappers from the npm `tyrell-react` package — so you `:require [tyrell.react :as ty]` instead of `["tyrell-react" :as ty]`. The npm package is **not** auto-installed (Track B users wouldn't need it), so make sure you ran `npm install tyrell-react` from step 1 — it's a peer of `react` and `react-dom`.
159
+
160
+ Each wrapper exports under two names: `TyButton` (explicit) and `Button` (short). Use whichever fits your style — the short names tend to read better in CLJS.
161
+
162
+ ---
163
+
164
+ ## Track B — Non-React (Replicant, vanilla CLJS)
165
+
166
+ No wrapper package. Web components emit normal DOM events; non-React renderers handle them directly.
167
+
168
+ ### Replicant
169
+
170
+ ```clojure
171
+ (ns my-app.core
172
+ (:require [tyrell.components]
173
+ [replicant.dom :as r.dom]))
174
+
175
+ (defonce !state (atom {:email ""}))
176
+
177
+ (defn login-form [{:keys [email]}]
178
+ [:form.flex.flex-col.gap-3
179
+ [:ty-input {:label "Email"
180
+ :type "email"
181
+ :value email
182
+ :on {:change (fn [^js e]
183
+ (swap! !state assoc :email (.. e -detail -value)))}}]
184
+ [:ty-button {:flavor "primary" :type "submit"} "Sign in"]])
185
+
186
+ (defn render! []
187
+ (r.dom/render (.getElementById js/document "app") (login-form @!state)))
188
+
189
+ (add-watch !state ::render (fn [_ _ _ _] (render!)))
190
+ ```
191
+
192
+ For action-dispatch idioms (`:on {:change [:set-email]}` + `replicant.dom/set-dispatch!`), see [REPLICANT_TY_GUIDE.md](REPLICANT_TY_GUIDE.md).
193
+
194
+ ### Vanilla CLJS
195
+
196
+ ```clojure
197
+ (ns my-app.core
198
+ (:require [tyrell.components]))
199
+
200
+ (defn render! []
201
+ (let [root (js/document.getElementById "app")
202
+ input (doto (js/document.createElement "ty-input")
203
+ (.setAttribute "label" "Email")
204
+ (.setAttribute "type" "email"))
205
+ btn (doto (js/document.createElement "ty-button")
206
+ (.setAttribute "flavor" "primary")
207
+ (set! -textContent "Sign in"))]
208
+ (.addEventListener input "change"
209
+ #(js/console.log "email:" (.. % -detail -value)))
210
+ (.appendChild root input)
211
+ (.appendChild root btn)))
212
+
213
+ (defn ^:export init [] (render!))
214
+ ```
215
+
216
+ ---
217
+
218
+ ## Icons (both tracks)
219
+
220
+ ```clojure
221
+ (ns my-app.icons
222
+ (:require [tyrell.icons :as icons]
223
+ [tyrell.lucide :as lucide]))
224
+
225
+ (icons/register! {:check lucide/check
226
+ :user lucide/user}) ; the key is the name
227
+ ```
228
+
229
+ Call it once at startup, then `[:ty-icon {:name "check"}]` (or `[:> ty/Icon {:name "check"}]` on Track A). `:advanced` drops every def you don't reference.
230
+
231
+ Sets, tree-shaking, custom SVGs and troubleshooting: [ICONS_GUIDE.md](../ICONS_GUIDE.md#in-clojure).
232
+
233
+ ---
234
+
235
+ ## What `dev.gersak/tyrell` brings (both tracks)
236
+
237
+ CLJS-first infrastructure that complements components, framework-agnostic:
238
+
239
+ | Namespace | Purpose |
240
+ |--------------------|------------------------------------------------------------------------|
241
+ | `tyrell.router` | Zipper-based client-side routing |
242
+ | `tyrell.i18n` | Translations + Intl number/date formatting (`.keyword`, `.number`, …) |
243
+ | `tyrell.layout` | Container-aware responsive breakpoints (`with-window`, `with-container`) |
244
+ | `tyrell.icons` | Icon registry — `register!` and use `<ty-icon>` |
245
+ | `tyrell.shim` | Build your own web components in CLJS |
246
+ | `tyrell.positioning` | Smart popup/tooltip positioning helpers |
247
+ | `tyrell.value` | Form-value coercion utilities |
248
+
249
+ These work the same whether you're on Track A or Track B — they're independent of the view layer. See the deep-dive guides:
250
+
251
+ - [ROUTING_GUIDE.md](ROUTING_GUIDE.md)
252
+ - [I18N_GUIDE.md](I18N_GUIDE.md)
253
+ - [LAYOUT_GUIDE.md](LAYOUT_GUIDE.md)
254
+ - [COMPONENT_GUIDE.md](COMPONENT_GUIDE.md) — `tyrell.shim`
255
+
256
+ ---
257
+
258
+ ## Next steps
259
+
260
+ - [CLOJURESCRIPT_GUIDE.md](CLOJURESCRIPT_GUIDE.md) — substrate reference (shadow-cljs config, SSR, property-vs-attribute rules, code splitting hooks)
261
+ - [REPLICANT_TY_GUIDE.md](REPLICANT_TY_GUIDE.md) — Replicant-specific patterns
262
+ - [CODE_SPLITTING.md](CODE_SPLITTING.md) — lazy-loading components by route
263
+ - [../TY_GUIDE.md](../TY_GUIDE.md) — universal component API reference
264
+ - [../CSS_GUIDE.md](../CSS_GUIDE.md) — design system (colors, surfaces, text)
265
+
266
+ If something doesn't render or events don't fire: 9 times out of 10 it's a property-vs-attribute issue (boolean/array values must be set as JS properties, not HTML attributes). See `CLOJURESCRIPT_GUIDE.md` § "Using Web Components from CLJS".