tyrell-components 1.0.0-TC9 → 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 (392) 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 +33 -18
  37. package/lib/components/button.js +317 -267
  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 +16 -15
  51. package/lib/components/file-upload.js +436 -426
  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 +14 -52
  83. package/lib/components/tag.js +231 -306
  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 +7 -4
  117. package/lib/index.js +26 -39
  118. package/lib/styles/button.d.ts +24 -7
  119. package/lib/styles/button.js +285 -445
  120. package/lib/styles/calendar-month.d.ts +7 -6
  121. package/lib/styles/calendar-month.js +158 -226
  122. package/lib/styles/calendar-navigation.d.ts +2 -6
  123. package/lib/styles/calendar-navigation.js +108 -127
  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 +321 -388
  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 -2
  137. package/lib/styles/file-upload.js +143 -188
  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 +168 -362
  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 +2 -3
  189. package/lib/utils/loader-registry.js +3 -35
  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 +62 -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 -404
  232. package/lib/components/dropdown.d.ts.map +0 -1
  233. package/lib/components/dropdown.js +0 -1563
  234. package/lib/components/dropdown.js.map +0 -1
  235. package/lib/components/file-upload.d.ts.map +0 -1
  236. package/lib/components/file-upload.js.map +0 -1
  237. package/lib/components/icon.d.ts.map +0 -1
  238. package/lib/components/icon.js.map +0 -1
  239. package/lib/components/input.d.ts.map +0 -1
  240. package/lib/components/input.js.map +0 -1
  241. package/lib/components/modal.d.ts.map +0 -1
  242. package/lib/components/modal.js.map +0 -1
  243. package/lib/components/multiselect.d.ts +0 -408
  244. package/lib/components/multiselect.d.ts.map +0 -1
  245. package/lib/components/multiselect.js +0 -1611
  246. package/lib/components/multiselect.js.map +0 -1
  247. package/lib/components/option.d.ts.map +0 -1
  248. package/lib/components/option.js.map +0 -1
  249. package/lib/components/popup.d.ts.map +0 -1
  250. package/lib/components/popup.js.map +0 -1
  251. package/lib/components/radio.d.ts.map +0 -1
  252. package/lib/components/radio.js.map +0 -1
  253. package/lib/components/resize-observer.d.ts.map +0 -1
  254. package/lib/components/resize-observer.js.map +0 -1
  255. package/lib/components/scroll-container.d.ts.map +0 -1
  256. package/lib/components/scroll-container.js.map +0 -1
  257. package/lib/components/step.d.ts.map +0 -1
  258. package/lib/components/step.js.map +0 -1
  259. package/lib/components/switch.d.ts.map +0 -1
  260. package/lib/components/switch.js.map +0 -1
  261. package/lib/components/tab.d.ts.map +0 -1
  262. package/lib/components/tab.js.map +0 -1
  263. package/lib/components/tabs.d.ts.map +0 -1
  264. package/lib/components/tabs.js.map +0 -1
  265. package/lib/components/tag.d.ts.map +0 -1
  266. package/lib/components/tag.js.map +0 -1
  267. package/lib/components/textarea.d.ts.map +0 -1
  268. package/lib/components/textarea.js.map +0 -1
  269. package/lib/components/tooltip.d.ts.map +0 -1
  270. package/lib/components/tooltip.js.map +0 -1
  271. package/lib/components/wizard.d.ts.map +0 -1
  272. package/lib/components/wizard.js.map +0 -1
  273. package/lib/icons/fontawesome/brands.d.ts.map +0 -1
  274. package/lib/icons/fontawesome/brands.js.map +0 -1
  275. package/lib/icons/fontawesome/regular.d.ts.map +0 -1
  276. package/lib/icons/fontawesome/regular.js.map +0 -1
  277. package/lib/icons/fontawesome/solid.d.ts.map +0 -1
  278. package/lib/icons/fontawesome/solid.js.map +0 -1
  279. package/lib/icons/heroicons/micro.d.ts.map +0 -1
  280. package/lib/icons/heroicons/micro.js.map +0 -1
  281. package/lib/icons/heroicons/mini.d.ts.map +0 -1
  282. package/lib/icons/heroicons/mini.js.map +0 -1
  283. package/lib/icons/heroicons/outline.d.ts.map +0 -1
  284. package/lib/icons/heroicons/outline.js.map +0 -1
  285. package/lib/icons/heroicons/solid.d.ts.map +0 -1
  286. package/lib/icons/heroicons/solid.js.map +0 -1
  287. package/lib/icons/lucide.d.ts.map +0 -1
  288. package/lib/icons/lucide.js.map +0 -1
  289. package/lib/icons/material/filled.d.ts.map +0 -1
  290. package/lib/icons/material/filled.js.map +0 -1
  291. package/lib/icons/material/outlined.d.ts.map +0 -1
  292. package/lib/icons/material/outlined.js.map +0 -1
  293. package/lib/icons/material/round.d.ts.map +0 -1
  294. package/lib/icons/material/round.js.map +0 -1
  295. package/lib/icons/material/sharp.d.ts.map +0 -1
  296. package/lib/icons/material/sharp.js.map +0 -1
  297. package/lib/icons/material/two-tone.d.ts.map +0 -1
  298. package/lib/icons/material/two-tone.js.map +0 -1
  299. package/lib/index.d.ts.map +0 -1
  300. package/lib/index.js.map +0 -1
  301. package/lib/styles/button.d.ts.map +0 -1
  302. package/lib/styles/button.js.map +0 -1
  303. package/lib/styles/calendar-month.d.ts.map +0 -1
  304. package/lib/styles/calendar-month.js.map +0 -1
  305. package/lib/styles/calendar-navigation.d.ts.map +0 -1
  306. package/lib/styles/calendar-navigation.js.map +0 -1
  307. package/lib/styles/calendar.d.ts.map +0 -1
  308. package/lib/styles/calendar.js.map +0 -1
  309. package/lib/styles/checkbox.d.ts.map +0 -1
  310. package/lib/styles/checkbox.js.map +0 -1
  311. package/lib/styles/copy.d.ts.map +0 -1
  312. package/lib/styles/copy.js.map +0 -1
  313. package/lib/styles/custom-scrollbar.d.ts.map +0 -1
  314. package/lib/styles/custom-scrollbar.js.map +0 -1
  315. package/lib/styles/date-picker.d.ts.map +0 -1
  316. package/lib/styles/date-picker.js.map +0 -1
  317. package/lib/styles/dropdown.d.ts +0 -12
  318. package/lib/styles/dropdown.d.ts.map +0 -1
  319. package/lib/styles/dropdown.js +0 -1048
  320. package/lib/styles/dropdown.js.map +0 -1
  321. package/lib/styles/file-upload.d.ts.map +0 -1
  322. package/lib/styles/file-upload.js.map +0 -1
  323. package/lib/styles/icon.d.ts.map +0 -1
  324. package/lib/styles/icon.js.map +0 -1
  325. package/lib/styles/input.d.ts.map +0 -1
  326. package/lib/styles/input.js.map +0 -1
  327. package/lib/styles/modal.d.ts.map +0 -1
  328. package/lib/styles/modal.js.map +0 -1
  329. package/lib/styles/multiselect.d.ts +0 -6
  330. package/lib/styles/multiselect.d.ts.map +0 -1
  331. package/lib/styles/multiselect.js +0 -837
  332. package/lib/styles/multiselect.js.map +0 -1
  333. package/lib/styles/option.d.ts.map +0 -1
  334. package/lib/styles/option.js.map +0 -1
  335. package/lib/styles/popup.d.ts.map +0 -1
  336. package/lib/styles/popup.js.map +0 -1
  337. package/lib/styles/radio.d.ts.map +0 -1
  338. package/lib/styles/radio.js.map +0 -1
  339. package/lib/styles/resize-observer.d.ts.map +0 -1
  340. package/lib/styles/resize-observer.js.map +0 -1
  341. package/lib/styles/scroll-container.d.ts.map +0 -1
  342. package/lib/styles/scroll-container.js.map +0 -1
  343. package/lib/styles/step.d.ts.map +0 -1
  344. package/lib/styles/step.js.map +0 -1
  345. package/lib/styles/switch.d.ts.map +0 -1
  346. package/lib/styles/switch.js.map +0 -1
  347. package/lib/styles/tab.d.ts.map +0 -1
  348. package/lib/styles/tab.js.map +0 -1
  349. package/lib/styles/tabs.d.ts.map +0 -1
  350. package/lib/styles/tabs.js.map +0 -1
  351. package/lib/styles/tag.d.ts.map +0 -1
  352. package/lib/styles/tag.js.map +0 -1
  353. package/lib/styles/textarea.d.ts.map +0 -1
  354. package/lib/styles/textarea.js.map +0 -1
  355. package/lib/styles/tooltip.d.ts.map +0 -1
  356. package/lib/styles/tooltip.js.map +0 -1
  357. package/lib/styles/wizard.d.ts.map +0 -1
  358. package/lib/styles/wizard.js.map +0 -1
  359. package/lib/types/common.d.ts.map +0 -1
  360. package/lib/types/common.js.map +0 -1
  361. package/lib/utils/calendar-utils.d.ts.map +0 -1
  362. package/lib/utils/calendar-utils.js.map +0 -1
  363. package/lib/utils/custom-scrollbar.d.ts.map +0 -1
  364. package/lib/utils/custom-scrollbar.js.map +0 -1
  365. package/lib/utils/icon-registry.d.ts.map +0 -1
  366. package/lib/utils/icon-registry.js.map +0 -1
  367. package/lib/utils/loader-registry.d.ts.map +0 -1
  368. package/lib/utils/loader-registry.js.map +0 -1
  369. package/lib/utils/locale.d.ts.map +0 -1
  370. package/lib/utils/locale.js.map +0 -1
  371. package/lib/utils/mobile.d.ts.map +0 -1
  372. package/lib/utils/mobile.js.map +0 -1
  373. package/lib/utils/number-format.d.ts.map +0 -1
  374. package/lib/utils/number-format.js.map +0 -1
  375. package/lib/utils/parse-boolean.d.ts +0 -39
  376. package/lib/utils/parse-boolean.d.ts.map +0 -1
  377. package/lib/utils/parse-boolean.js +0 -58
  378. package/lib/utils/parse-boolean.js.map +0 -1
  379. package/lib/utils/positioning.d.ts.map +0 -1
  380. package/lib/utils/positioning.js.map +0 -1
  381. package/lib/utils/property-capture.d.ts.map +0 -1
  382. package/lib/utils/property-capture.js.map +0 -1
  383. package/lib/utils/property-manager.d.ts.map +0 -1
  384. package/lib/utils/property-manager.js.map +0 -1
  385. package/lib/utils/resize-observer.d.ts.map +0 -1
  386. package/lib/utils/resize-observer.js.map +0 -1
  387. package/lib/utils/scroll-lock.d.ts.map +0 -1
  388. package/lib/utils/scroll-lock.js.map +0 -1
  389. package/lib/utils/styles.d.ts.map +0 -1
  390. package/lib/utils/styles.js.map +0 -1
  391. package/lib/version.d.ts.map +0 -1
  392. package/lib/version.js.map +0 -1
@@ -0,0 +1,252 @@
1
+ # HTMX + Tyrell Guide
2
+
3
+ Tyrell ships standard Web Components, so they integrate with HTMX without a wrapper. Form-associated ty components participate in `FormData` automatically; `change` events bubble like native ones; swapped HTML upgrades into components on every swap.
4
+
5
+ This guide covers what's specific to that combination — the rest is just HTMX.
6
+
7
+ ## Setup
8
+
9
+ Single CDN script tag, single stylesheet:
10
+
11
+ ```html
12
+ <!DOCTYPE html>
13
+ <html>
14
+ <head>
15
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components/css/tyrell.css">
16
+ <!-- tyrell-theme.css: auto-contrast, seed-based rebranding, themes. See TY_GUIDE.md#quick-start -->
17
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components/css/tyrell-theme.css">
18
+ <script src="https://cdn.jsdelivr.net/npm/tyrell-components/dist/tyrell.js"></script>
19
+ <script src="https://unpkg.com/htmx.org@2"></script>
20
+ </head>
21
+ <body>
22
+ <main hx-boost="true">
23
+ <ty-button flavor="primary" hx-get="/api/hello" hx-target="#out">
24
+ Click me
25
+ </ty-button>
26
+ <div id="out"></div>
27
+ </main>
28
+ </body>
29
+ </html>
30
+ ```
31
+
32
+ That's it. `<ty-*>` elements work as HTMX targets, triggers, and form fields with no glue code.
33
+
34
+ ## Form submission — `FormData` works automatically
35
+
36
+ Every form-associated ty component (`ty-input`, `ty-textarea`, `ty-checkbox`, `ty-switch`, `ty-radio-group`, `ty-select`, `ty-date-picker`, `ty-file-upload`) calls `internals.setFormValue()` on every change. HTMX's `hx-post` / `hx-put` on a `<form>` includes them in the serialized payload under their `name` attribute — same as `<input>`.
37
+
38
+ ```html
39
+ <form hx-post="/api/contact" hx-target="#result">
40
+ <ty-input name="email" type="email" label="Email" required></ty-input>
41
+
42
+ <ty-select name="topic" label="Topic">
43
+ <ty-option value="sales">Sales</ty-option>
44
+ <ty-option value="support">Support</ty-option>
45
+ </ty-select>
46
+
47
+ <ty-textarea name="message" label="Message" rows="4"></ty-textarea>
48
+
49
+ <ty-button type="submit" flavor="primary">Send</ty-button>
50
+ </form>
51
+
52
+ <div id="result"></div>
53
+ ```
54
+
55
+ The server receives `email`, `topic`, `message` in the request body. No `hx-vals`, no `hx-include` needed.
56
+
57
+ **Multi-value fields** (`ty-select multiple`) post repeated `name=` entries — your framework's body parser must support multi-value form fields (most do).
58
+
59
+ **File uploads** (`ty-file-upload`) need `hx-encoding="multipart/form-data"` on the form, just like a native file input. Each selected file is appended to the body under the component's `name` attribute (multiple entries when `multiple` is set):
60
+
61
+ ```html
62
+ <form hx-post="/api/upload"
63
+ hx-target="#result"
64
+ hx-encoding="multipart/form-data">
65
+ <ty-file-upload name="docs" label="Attachments" multiple
66
+ accept=".pdf,.docx"></ty-file-upload>
67
+ <ty-button type="submit" flavor="primary">Upload</ty-button>
68
+ </form>
69
+ ```
70
+
71
+ Server-side: read repeated `docs` parts (Flask `request.files.getlist('docs')`, Rails `params[:docs]`, Express `req.files`, etc.).
72
+
73
+ ## Triggering on user changes — `hx-trigger="change"`
74
+
75
+ Tyrell components emit a bubbling `change` event when the user commits a new value. HTMX picks that up the same way it does for native inputs:
76
+
77
+ ```html
78
+ <ty-select name="country"
79
+ hx-get="/api/cities"
80
+ hx-trigger="change"
81
+ hx-target="#city-picker"
82
+ hx-vals='js:{country: event.detail.value}'>
83
+ <ty-option value="us">United States</ty-option>
84
+ <ty-option value="de">Germany</ty-option>
85
+ </ty-select>
86
+
87
+ <div id="city-picker"></div>
88
+ ```
89
+
90
+ The `hx-vals='js:{...}'` form lets you pull the actual value off `event.detail.value` rather than relying on serialization. For a single select inside a `<form>`, you can skip `hx-vals` and let normal form serialization handle it.
91
+
92
+ **Debouncing.** Use HTMX's built-in modifier — `hx-trigger="change delay:300ms"`. `ty-input` *also* has a built-in `debounce` attribute (ms) that debounces its own `change` event before HTMX ever sees it; pick one, don't double up.
93
+
94
+ ## Swapped content auto-upgrades
95
+
96
+ `customElements.define()` is global, so any `<ty-*>` tag arriving via an HTMX swap becomes a fully functional component immediately — no `htmx:afterSwap` hook needed.
97
+
98
+ ```html
99
+ <button hx-get="/fragments/wizard" hx-target="#region" hx-swap="innerHTML">
100
+ Load wizard
101
+ </button>
102
+ <div id="region"></div>
103
+ ```
104
+
105
+ Server returns:
106
+ ```html
107
+ <ty-wizard>
108
+ <ty-step id="info" label="Info">…</ty-step>
109
+ <ty-step id="confirm" label="Confirm">…</ty-step>
110
+ </ty-wizard>
111
+ ```
112
+
113
+ The wizard renders, navigates, and animates as if it had been on the page from the start.
114
+
115
+ **Out-of-band swaps** (`hx-swap-oob`) work the same way. Modal-driven flows often pair `hx-target` with an OOB swap that injects `<ty-modal open>` into a slot at the bottom of `<body>`.
116
+
117
+ ## Icons
118
+
119
+ Put the SVG inside the tag. The server already has it, so there's no registry and no boot script, and it works in every swap (regular, OOB, `hx-boost`):
120
+
121
+ ```html
122
+ <ty-icon size="md">
123
+ <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">…</svg>
124
+ </ty-icon>
125
+ ```
126
+
127
+ A template helper (Jinja macro, Go template func, Clojure fn) keeps templates short. To use `name="…"` instead, register once per page with `tyIcons.register`; swapped-in content reads the same registry.
128
+
129
+ Sets, tree-shaking, custom SVGs and troubleshooting: [ICONS_GUIDE.md](../ICONS_GUIDE.md#in-html).
130
+
131
+ ## Modals and HTMX
132
+
133
+ `<ty-modal>` is a `<dialog>` wrapper. Two ergonomic patterns:
134
+
135
+ **Server controls open state** — toggle the `open` attribute via OOB swap:
136
+
137
+ ```html
138
+ <!-- Trigger -->
139
+ <ty-button hx-get="/fragments/edit-modal" hx-target="#modal-slot" hx-swap="innerHTML">
140
+ Edit
141
+ </ty-button>
142
+
143
+ <div id="modal-slot"></div>
144
+ ```
145
+
146
+ Server returns the populated modal with `open` already set:
147
+ ```html
148
+ <ty-modal open>
149
+ <form hx-post="/api/save"
150
+ hx-target="#modal-slot"
151
+ hx-swap="innerHTML">
152
+ …
153
+ <ty-button type="submit" flavor="primary">Save</ty-button>
154
+ </form>
155
+ </ty-modal>
156
+ ```
157
+
158
+ After save, server returns an empty fragment, `#modal-slot` becomes empty, modal disappears.
159
+
160
+ **Client closes on success** — listen for the `htmx:afterRequest` event on the modal:
161
+
162
+ ```html
163
+ <ty-modal id="m" open>
164
+ <form hx-post="/api/save"
165
+ hx-on::after-request="if (event.detail.successful) document.getElementById('m').removeAttribute('open')">
166
+ …
167
+ </form>
168
+ </ty-modal>
169
+ ```
170
+
171
+ ## Validation feedback
172
+
173
+ `hx-target-error` (or HTMX's response-target extension) lets the server return validation errors to a specific region. Pair with `ty-input`'s `error` attribute:
174
+
175
+ ```html
176
+ <form hx-post="/api/signup" hx-target="#result">
177
+ <ty-input id="email" name="email" type="email" label="Email"></ty-input>
178
+ <div id="result"></div>
179
+ </form>
180
+ ```
181
+
182
+ Server returns on 422:
183
+ ```html
184
+ <ty-input id="email" name="email" type="email" label="Email"
185
+ value="not-an-email"
186
+ error="Enter a valid email"
187
+ hx-swap-oob="true"></ty-input>
188
+ ```
189
+
190
+ The OOB swap replaces the input with one carrying the error message. Tyrell renders the error text and the danger colors automatically. The server owns `error`: the next response that renders the input without it clears the message.
191
+
192
+ ## Reorderable lists (ty-sortable)
193
+
194
+ `ty-sortable` never moves its children. A drop (or a keyboard move) fires `ty-sortable-change` on the destination list; post `event.detail.value` and let the server render the lists in the new order. Until the swap lands, the item stays where it was dropped. Use the idiomorph extension so the swap moves the existing item nodes:
195
+
196
+ ```html
197
+ <script src="https://cdn.jsdelivr.net/npm/idiomorph@0.7.4/dist/idiomorph-ext.min.js"></script>
198
+
199
+ <div id="board" hx-ext="morph">
200
+ <ty-sortable id="todo" group="board" label="To do"
201
+ hx-post="/board/move"
202
+ hx-trigger="ty-sortable-change"
203
+ hx-vals='js:{move: JSON.stringify(event.detail.value)}'
204
+ hx-target="#board"
205
+ hx-swap="morph:innerHTML">
206
+ <div id="card-12">
207
+ <button type="button" data-handle aria-label="Move Fix login">
208
+ <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">…</svg>
209
+ </button>
210
+ Fix login
211
+ </div>
212
+ </ty-sortable>
213
+ <ty-sortable id="done" group="board" label="Done" hx-post="/board/move" …>…</ty-sortable>
214
+ </div>
215
+ ```
216
+
217
+ The server parses `move`, saves it and returns both `<ty-sortable>` lists, with the same attributes, in the stored order.
218
+
219
+ - **Key every item** with `id` (or `data-key`). The key is what `value` reports and what idiomorph uses to move the node.
220
+ - **`value`** is `{ key, group, source, from, to, order }`. `order` is the new key order of each list the move touched, by list id. For fractional ranking, store a rank between `value.to.prev` and `value.to.next` instead.
221
+ - **Refusing a move:** htmx puts `htmx-request` on the list while the request runs, and ty reads it like `aria-busy="true"`. If the response renders the old order (or the request fails and nothing is swapped), the item snaps back when the request ends. Put `hx-post` on each list, not on a wrapper, so the class lands on the list.
222
+ - **Touch:** a `[data-handle]` drags at once and leaves the rest of the row to scroll; give it a 44px target. Without a handle the whole item drags after a 250 ms press.
223
+ - `group` lets lists trade items, `accepts="[data-kind=bug]"` limits what a list takes, `data-locked` pins an item. Full API: [TY_GUIDE.md](../TY_GUIDE.md#ty-sortable).
224
+
225
+ ## Common pitfalls
226
+
227
+ - **Don't put HTMX attributes on the `<ty-option>` / `<ty-tab>` / `<ty-step>` children** — they're internal slots, not interactive. Put them on `<ty-select>` / `<ty-tabs>` / `<ty-wizard>` and use `hx-trigger="change"` (`hx-trigger="ty-tab-change"` for tabs). The exception is a lazy `<ty-tab>`, which loads itself:
228
+
229
+ ```html
230
+ <ty-tab id="reports" label="Reports" lazy
231
+ hx-get="/tabs/reports" hx-trigger="ty-tab-load"
232
+ hx-on::response-error="this.loadFailed()"
233
+ hx-on::send-error="this.loadFailed()"></ty-tab>
234
+ ```
235
+
236
+ The response is the panel's content (`innerHTML` of the tab). A failed request shows the tab's error and Retry only through `loadFailed()`; ty-tab doesn't watch htmx events itself.
237
+ - **Boolean values from `ty-checkbox`** post as `"on"` (or absent) — same as native `<input type="checkbox">`. `ty-switch` follows the same rule. If you need explicit `true`/`false`, wire it via `hx-vals='js:{enabled: this.checked}'`.
238
+ - **`ty-select multiple` posts repeated `name=` entries** (one per selected value). Confirm your backend reads multi-value fields (Express `body-parser` does, Ring's wrap-params does, Rails' `permit(:tags => [])` does).
239
+ - **A swapped `ty-select` takes its selection from `value`** — `<ty-option selected>` selects nothing. With idiomorph a different `value` wins, the same one changes nothing, none clears it. A server that re-renders a select renders `value="…"` with the current selection. For dependent selects (country → city), swap the whole select, not only its options: a swap of the options alone keeps the old value. A `ty-selected-options` outside the swapped region stays on the old select: swap it too, or use idiomorph, which keeps the select.
240
+ - **Date format**: `ty-date-picker` posts a UTC ISO instant (date-only: when the day starts in the browser's timezone, e.g. `2026-10-15T22:00:00.000Z` for Oct 16 in Zagreb). Add `native` to post `YYYY-MM-DD`, or `YYYY-MM-DDTHH:mm` with `with-time`, like `<input type="date">`. An empty picker posts `name=`.
241
+ - **Don't manually re-register components after a swap** — `customElements.define` is global, registration persists across swaps. Re-running the CDN bundle script will throw `NotSupportedError: already defined`.
242
+
243
+ ## Why no wrapper package?
244
+
245
+ HTMX speaks HTML. Web Components speak HTML. There is no impedance mismatch to bridge — you're already at the same layer. Anything a wrapper would do (`hx-on`, `hx-vals`, `hx-trigger`) HTMX already gives you, and ty's form-associated internals + bubbling events do the rest.
246
+
247
+ ## See also
248
+
249
+ - [TY_GUIDE.md](../TY_GUIDE.md) — universal component API
250
+ - [JAVASCRIPT_GUIDE.md](JAVASCRIPT_GUIDE.md) — bundlers, subpath imports, icon tree-shaking (when you outgrow the CDN script tag)
251
+ - [DATASTAR_TY_GUIDE.md](../DATASTAR_TY_GUIDE.md) — sibling server-driven approach using SSE + signals
252
+ - [CSS_GUIDE.md](../CSS_GUIDE.md) — color and surface classes
@@ -0,0 +1,388 @@
1
+ # JavaScript + Tyrell Guide
2
+
3
+ Use Tyrell web components from vanilla JavaScript and any bundler. This guide covers distribution, the side-effects model, subpath imports, icon tree-shaking, code splitting, and the SSR boundary — the substrate every framework integration sits on.
4
+
5
+ For framework-specific patterns, see [REACT_TY_GUIDE.md](./REACT_TY_GUIDE.md), [VUE_TY_GUIDE.md](./VUE_TY_GUIDE.md), and [SVELTE_TY_GUIDE.md](./SVELTE_TY_GUIDE.md).
6
+
7
+ ## Two distribution channels
8
+
9
+ Tyrell ships through two channels — pick one based on your build setup, not both at once.
10
+
11
+ ### CDN — zero build
12
+
13
+ ```html
14
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components@latest/css/tyrell.css">
15
+ <!-- tyrell-theme.css: auto-contrast, seed-based rebranding, themes. See TY_GUIDE.md#quick-start -->
16
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components@latest/css/tyrell-theme.css">
17
+ <script type="module" src="https://cdn.jsdelivr.net/npm/tyrell-components@latest/dist/tyrell.js"></script>
18
+ ```
19
+
20
+ The CDN bundle (`dist/tyrell.js`) registers every component and exposes the icon registry on `window.tyIcons`. Use this for HTMX, server-rendered apps, prototypes, multi-app domains where browser cache wins, or strict no-bundler workflows.
21
+
22
+ ### NPM — tree-shakeable
23
+
24
+ ```bash
25
+ npm install tyrell-components
26
+ ```
27
+
28
+ ```js
29
+ import 'tyrell-components/css/tyrell.css' // structure — no color tokens
30
+ import 'tyrell-components/css/tyrell-theme.css' // colors — auto-contrast, seed-based rebranding
31
+ import 'tyrell-components' // registers everything
32
+ ```
33
+
34
+ Use this when you have a bundler (Vite, Webpack, Rollup, esbuild, Parcel, Bun). Subpath imports let you ship only the components you use.
35
+
36
+ ## How registration works
37
+
38
+ Each component file ends with the same pattern:
39
+
40
+ ```ts
41
+ // src/components/button.ts
42
+ export class TyButton extends TyComponent { ... }
43
+
44
+ if (!customElements.get("ty-button")) {
45
+ customElements.define("ty-button", TyButton);
46
+ }
47
+ ```
48
+
49
+ `customElements.define(...)` is a **side effect** — calling it makes `<ty-button>` work in the DOM. Importing the file triggers that side effect; once registered, the component class is rarely referenced from your code (you write `<ty-button>` in HTML or JSX, not `new TyButton()`).
50
+
51
+ This matters because modern bundlers eliminate "unused" code aggressively. Tyrell's `package.json` declares the side-effectful files explicitly:
52
+
53
+ ```json
54
+ "sideEffects": [
55
+ "./lib/index.js",
56
+ "./lib/components/**/*.js",
57
+ "./dist/*.js"
58
+ ]
59
+ ```
60
+
61
+ Translation: "These files do real work just by being imported — keep them in the bundle even if no exported symbols are referenced." Everything else (utils, types, icon data) is pure and freely tree-shaken.
62
+
63
+ ## Subpath imports
64
+
65
+ Import only the components you use:
66
+
67
+ ```js
68
+ import 'tyrell-components/button'
69
+ import 'tyrell-components/input'
70
+ import 'tyrell-components/dropdown'
71
+ import 'tyrell-components/option' // dropdown children
72
+ import 'tyrell-components/modal'
73
+ ```
74
+
75
+ Available subpaths (each registers exactly one custom element):
76
+
77
+ ```
78
+ button input textarea checkbox
79
+ dropdown option multiselect tag
80
+ modal popup tooltip
81
+ calendar calendar-month calendar-navigation date-picker
82
+ tabs tab wizard
83
+ icon copy file-upload sortable
84
+ ```
85
+
86
+ Subpath imports compose with `import('...')` for code splitting:
87
+
88
+ ```js
89
+ // Calendar/date-picker is the heaviest component — defer until needed
90
+ async function openDatePicker() {
91
+ await import('tyrell-components/date-picker')
92
+ document.getElementById('picker').showModal()
93
+ }
94
+ ```
95
+
96
+ Webpack, Rollup, Vite, esbuild, and Parcel all honor subpath exports. Bun and Deno also work via the standard `exports` field.
97
+
98
+ ## CSS distribution
99
+
100
+ Two files, both required: `css/tyrell.css` (structure — spacing, typography, shadows, component CSS; zero color tokens) and `css/tyrell-theme.css` (every color, via an OKLCH engine — auto-contrast, seed-based rebranding, themes). Load `tyrell-theme.css` after `tyrell.css`. Don't want the theme engine? Swap it for `css/tyrell-colors-static.css` — a plain hardcoded hex fallback, no theming API. Two consumption modes — pick whichever fits your build:
101
+
102
+ ```js
103
+ // Bundler picks it up (Vite, Webpack, Next.js, etc.)
104
+ import 'tyrell-components/css/tyrell.css'
105
+ import 'tyrell-components/css/tyrell-theme.css'
106
+ ```
107
+
108
+ ```html
109
+ <!-- Or load directly -->
110
+ <link rel="stylesheet" href="/node_modules/tyrell-components/css/tyrell.css">
111
+ <link rel="stylesheet" href="/node_modules/tyrell-components/css/tyrell-theme.css">
112
+ ```
113
+
114
+ Neither file is split per-component. Both are small enough that splitting would cost more in HTTP overhead than it saves, and the design tokens (colors, surfaces, text classes) need to be globally available regardless of which components are loaded.
115
+
116
+ ## Icons
117
+
118
+ `<ty-icon name="…">` is a runtime lookup, so the bundler can't see which icons you use. Import them by name and register them; everything you don't import is dropped.
119
+
120
+ ```js
121
+ import { registerIcons } from 'tyrell-components/icons/registry'
122
+ import { check, chevronDown } from 'tyrell-components/icons/lucide'
123
+
124
+ registerIcons({ check, 'action-down': chevronDown }) // the key is the name
125
+ ```
126
+
127
+ Avoid `import * as lucide` + `registerIcons(lucide)`: it ships the whole set. On the CDN build, use `window.tyIcons.register`.
128
+
129
+ Sets, tree-shaking, custom SVGs and troubleshooting: [ICONS_GUIDE.md](../ICONS_GUIDE.md#in-javascript).
130
+
131
+ ## Vanilla JS usage
132
+
133
+ Once components are registered, write plain HTML and listen for events:
134
+
135
+ ```html
136
+ <ty-input id="email" type="email" label="Email"></ty-input>
137
+ <ty-button id="submit" flavor="primary">Submit</ty-button>
138
+
139
+ <script>
140
+ const email = document.getElementById('email')
141
+ const submit = document.getElementById('submit')
142
+
143
+ email.addEventListener('change', (e) => {
144
+ console.log('email:', e.detail.value)
145
+ })
146
+
147
+ submit.addEventListener('click', () => {
148
+ if (email.value) {
149
+ // submit form
150
+ }
151
+ })
152
+ </script>
153
+ ```
154
+
155
+ Three things to remember:
156
+
157
+ 1. **Event payload lives on `event.detail`**, not `event` directly. Access values via `event.detail.value`.
158
+ 2. **Properties vs attributes** — set primitives via attributes, set complex values (arrays, objects, functions) via JS properties:
159
+ ```js
160
+ el.setAttribute('label', 'Email') // string attribute
161
+ el.disabled = true // boolean property
162
+ el.value = ['a', 'b', 'c'] // array property (multiselect)
163
+ ```
164
+ 3. **Wait for definition before scripting** if you call methods immediately:
165
+ ```js
166
+ await customElements.whenDefined('ty-modal')
167
+ document.querySelector('ty-modal').show()
168
+ ```
169
+
170
+ ## Reorderable lists (ty-sortable)
171
+
172
+ `ty-sortable` never moves its children. A drop (or a keyboard move) fires `ty-sortable-change` on the destination list, and the list holds the result on screen until your code puts the items in the new order. Key each item with `data-key` (or `id`):
173
+
174
+ ```html
175
+ <ty-sortable id="todo" group="board" label="To do">
176
+ <div data-key="a">
177
+ <button type="button" data-handle aria-label="Move Design review">
178
+ <ty-icon name="grip-vertical"></ty-icon>
179
+ </button>
180
+ Design review
181
+ </div>
182
+ </ty-sortable>
183
+ <ty-sortable id="done" group="board" label="Done"></ty-sortable>
184
+
185
+ <script>
186
+ document.addEventListener('ty-sortable-change', async (e) => {
187
+ const { value, fromContainer, toContainer } = e.detail
188
+ const lists = [fromContainer, toContainer]
189
+ lists.forEach((l) => l.setAttribute('aria-busy', 'true'))
190
+ try {
191
+ await save(value)
192
+ // value.order: the new key order of each touched list, by list id
193
+ for (const [id, keys] of Object.entries(value.order)) {
194
+ const list = document.getElementById(id)
195
+ list.replaceChildren(...keys.map((k) => document.querySelector(`[data-key="${k}"]`)))
196
+ }
197
+ } finally {
198
+ lists.forEach((l) => l.removeAttribute('aria-busy')) // order unchanged: the item snaps back
199
+ }
200
+ })
201
+ </script>
202
+ ```
203
+
204
+ - `value` is `{ key, group, source, from, to, order }`; `from` / `to` are `{ list, index, prev, next }`. For fractional ranking, save a rank between `value.to.prev` and `value.to.next` instead of the whole order.
205
+ - `aria-busy="true"` while saving makes a refused save snap back as soon as it is removed. Without it, call `toContainer.settle('rejected')`, or `e.preventDefault()` to reject at once. With no busy signal and no render, the hold ends after `hold-timeout` (5000 ms).
206
+ - On touch, a `[data-handle]` drags at once and leaves the rest of the row to scroll; give it a 44px target. Without a handle the whole item drags after a 250 ms press.
207
+ - `list.move('a', { to: 'done', index: 0 })` moves without a pointer and resolves `'accepted'`, `'rejected'`, `'reconciled'` or `'unknown'`. Full API: [TY_GUIDE.md](../TY_GUIDE.md#ty-sortable).
208
+
209
+ ## Bundler notes
210
+
211
+ ### Vite
212
+
213
+ Works out of the box. Subpath imports, CSS imports, and `import()` splits all behave correctly:
214
+
215
+ ```js
216
+ // vite.config.js — no special config required
217
+ export default {
218
+ // ...
219
+ }
220
+ ```
221
+
222
+ For Vue 3 inside Vite, see [VUE_TY_GUIDE.md](./VUE_TY_GUIDE.md).
223
+
224
+ ### Webpack 5
225
+
226
+ Honors `sideEffects` and subpath exports. If you've manually overridden `sideEffects: false` for the project, you need to allow Tyrell's modules:
227
+
228
+ ```js
229
+ // webpack.config.js
230
+ module.exports = {
231
+ module: {
232
+ rules: [{
233
+ test: /\.js$/,
234
+ // do NOT mark tyrell-components as side-effect-free
235
+ sideEffects: (resourcePath) => !resourcePath.includes('tyrell-components'),
236
+ }]
237
+ }
238
+ }
239
+ ```
240
+
241
+ ### Rollup
242
+
243
+ Use `@rollup/plugin-node-resolve` with `exportConditions: ['import']`. `sideEffects` is honored automatically.
244
+
245
+ ### esbuild / Bun
246
+
247
+ Both honor `exports` and `sideEffects`. No configuration needed.
248
+
249
+ ### Parcel
250
+
251
+ Works automatically. Parcel respects `sideEffects` and resolves subpath exports.
252
+
253
+ ## SSR and the registration boundary
254
+
255
+ `customElements.define` requires a browser. On Node.js, `customElements` is undefined. Server-side rendering tools must either:
256
+
257
+ - **Skip the registration import on the server**, importing it only in the client boundary, or
258
+ - **Render `<ty-*>` tags as opaque strings on the server** and let registration hydrate them on the client.
259
+
260
+ Most frameworks already handle this correctly when you import inside a client-only context. Specifics:
261
+
262
+ - **Next.js (App Router)** — Add `'use client'` to any file that imports `tyrell-components/...`, or perform the import inside a `useEffect` for purely client-side registration. See REACT_TY_GUIDE.md § Next.js Integration.
263
+ - **Nuxt 3** — Wrap registration in `if (process.client)` or place imports inside `<ClientOnly>` boundaries / `onMounted` hooks.
264
+ - **SvelteKit** — Use `import { browser } from '$app/environment'` and guard with `if (browser)`, or place imports inside `onMount`.
265
+ - **Astro** — Use `client:load` / `client:idle` directives on islands that contain `<ty-*>` elements; do not import `tyrell-components` from `.astro` files.
266
+ - **Remix** — Import inside `useEffect` or wrap with `ClientOnly` from `remix-utils`.
267
+
268
+ What you should **not** do is render `<ty-*>` tags on the server expecting them to "work" — they'll render as inert HTML until registration runs on the client. That's usually fine (graceful upgrade), but means initial paint shows unstyled content. Either:
269
+
270
+ - Accept the brief flash (acceptable for most apps), or
271
+ - Wrap critical UI with a skeleton until `customElements.whenDefined()` resolves, or
272
+ - Use Declarative Shadow DOM for SSR-friendly initial markup (advanced; not currently supported by Tyrell out of the box).
273
+
274
+ ## Bundle size — what to expect
275
+
276
+ Approximate sizes for the most common configurations:
277
+
278
+ | Configuration | Minified |
279
+ |---|---:|
280
+ | Single primitive (`button`, `input`, `tag`) | 3–8 KB |
281
+ | Dropdown + option | ~15 KB |
282
+ | Modal + popup + tooltip | ~20 KB |
283
+ | Calendar + date-picker | ~25 KB |
284
+ | All components (full bundle) | ~150–200 KB |
285
+ | Per-icon SVG | 300–600 bytes |
286
+ | All lucide icons (mistake) | ~600 KB |
287
+
288
+ Components are bounded — even importing all 23 caps at ~200 KB. Icons are unbounded if you namespace-import a family. **The icon import pattern matters more than the component import pattern.**
289
+
290
+ ## Code-splitting patterns
291
+
292
+ ### Per-route splits
293
+
294
+ ```js
295
+ // Defer calendar to the page that uses it
296
+ const DatePickerPage = () => import('./pages/date-picker.js')
297
+ const router = {
298
+ '/booking': DatePickerPage,
299
+ }
300
+ ```
301
+
302
+ The dynamic `import()` triggers the route's components to register on demand.
303
+
304
+ ### Component-level splits
305
+
306
+ ```js
307
+ async function showModal() {
308
+ // Modal not registered yet
309
+ if (!customElements.get('ty-modal')) {
310
+ await import('tyrell-components/modal')
311
+ }
312
+ document.querySelector('ty-modal').show()
313
+ }
314
+ ```
315
+
316
+ ### Icon-bundle splits
317
+
318
+ For very icon-heavy apps, split icon registration by feature:
319
+
320
+ ```js
321
+ // chart-icons.js
322
+ import { registerIcons } from 'tyrell-components/icons/registry'
323
+ import { trendingUp, trendingDown, barChart } from 'tyrell-components/icons/lucide'
324
+ export function registerChartIcons() {
325
+ registerIcons({ trendingUp, trendingDown, barChart })
326
+ }
327
+
328
+ // chart.js
329
+ import { registerChartIcons } from './chart-icons.js'
330
+ registerChartIcons()
331
+ ```
332
+
333
+ Combined with route-level splits, only the route that renders the chart pays the cost.
334
+
335
+ ## Performance — startup ordering
336
+
337
+ If you load Tyrell via NPM and have hundreds of `<ty-*>` elements in initial HTML:
338
+
339
+ ```js
340
+ // main.js — register first, paint second
341
+ import 'tyrell-components/css/tyrell.css'
342
+ import 'tyrell-components/css/tyrell-theme.css'
343
+ import 'tyrell-components'
344
+
345
+ import { registerIcons } from 'tyrell-components/icons/registry'
346
+ import { check, x } from 'tyrell-components/icons/lucide'
347
+ registerIcons({ check, x })
348
+
349
+ // Then mount your app
350
+ mountApp()
351
+ ```
352
+
353
+ Registering before mounting avoids a flash of unregistered elements. With code splitting, accept the flash for offscreen content but prefetch eagerly for above-the-fold UI.
354
+
355
+ ## TypeScript
356
+
357
+ The package ships `.d.ts` files for the component classes:
358
+
359
+ ```ts
360
+ import type { TyButton } from 'tyrell-components/button'
361
+
362
+ const btn = document.querySelector('ty-button') as TyButton
363
+ btn.disabled = true
364
+ ```
365
+
366
+ For framework-specific JSX types, see the framework guides. Plain TypeScript with `lib.dom.d.ts` does not know about `<ty-button>` — you'll need either the React wrapper types, the Vue/Svelte template type registration, or a manual `HTMLElementTagNameMap` augmentation.
367
+
368
+ ## Quick reference — what to import where
369
+
370
+ | Goal | Import |
371
+ |---|---|
372
+ | Register everything | `import 'tyrell-components'` |
373
+ | Register one component | `import 'tyrell-components/button'` |
374
+ | Multiple components | One import line per component |
375
+ | Stylesheet — structure (bundler) | `import 'tyrell-components/css/tyrell.css'` |
376
+ | Stylesheet — colors (bundler) | `import 'tyrell-components/css/tyrell-theme.css'` |
377
+ | Icon registry function | `import { registerIcons } from 'tyrell-components/icons/registry'` |
378
+ | Specific icons | `import { check, heart } from 'tyrell-components/icons/lucide'` |
379
+ | Component class (typing) | `import type { TyButton } from 'tyrell-components/button'` |
380
+
381
+ ## See also
382
+
383
+ - [TY_GUIDE.md](../TY_GUIDE.md) — universal HTML/JS API reference
384
+ - [CSS_GUIDE.md](../CSS_GUIDE.md) — design system (colors, surfaces, text)
385
+ - [REACT_TY_GUIDE.md](./REACT_TY_GUIDE.md) — React + `tyrell-react`
386
+ - [VUE_TY_GUIDE.md](./VUE_TY_GUIDE.md) — Vue 3 / Nuxt
387
+ - [SVELTE_TY_GUIDE.md](./SVELTE_TY_GUIDE.md) — Svelte 5 / SvelteKit
388
+ - [TYCOMPONENT_GUIDE.md](./TYCOMPONENT_GUIDE.md) — building custom components on `TyComponent`