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,983 @@
1
+ # React + Tyrell Guide
2
+
3
+ Use Tyrell web components in React with `tyrell-react` — typed wrappers with React-idiomatic event handling, ref forwarding, and controlled component patterns.
4
+
5
+ ## Setup
6
+
7
+ ### 1. Install packages
8
+
9
+ ```bash
10
+ npm install tyrell-components tyrell-react
11
+ ```
12
+
13
+ Two packages, two roles:
14
+ - **`tyrell-components`** — the web components, CSS, and 1,600+ tree-shakeable icons.
15
+ - **`tyrell-react`** — typed React wrappers that render `<ty-*>` elements with React-idiomatic props and event handlers.
16
+
17
+ ### 2. Load Tyrell's web components
18
+
19
+ You have two options. Pick one — they're mutually exclusive.
20
+
21
+ #### Option A — Bundler imports (recommended)
22
+
23
+ Import `tyrell-components` once at your app's entry point. Each component file runs `customElements.define(...)` as a side effect when imported, registering all `<ty-*>` elements:
24
+
25
+ ```tsx
26
+ // app/layout.tsx (Next.js) or src/main.tsx (Vite)
27
+ import 'tyrell-components/css/tyrell.css' // structure — no color tokens
28
+ import 'tyrell-components/css/tyrell-theme.css' // colors — auto-contrast, seed-based rebranding
29
+ import 'tyrell-components' // registers all <ty-*> components
30
+ ```
31
+
32
+ For smaller bundles, register only the components you use:
33
+
34
+ ```tsx
35
+ import 'tyrell-components/css/tyrell.css'
36
+ import 'tyrell-components/css/tyrell-theme.css'
37
+ import 'tyrell-components/button'
38
+ import 'tyrell-components/input'
39
+ import 'tyrell-components/select'
40
+ import 'tyrell-components/modal'
41
+ ```
42
+
43
+ Available subpaths match the component names — `button`, `input`, `select`, `selected-tags`, `modal`, `popup`, `tooltip`, `tag`, `option`, `icon`, `checkbox`, `textarea`, `copy`, `tabs`, `tab`, `calendar`, `calendar-month`, `calendar-navigation`, `date-picker`.
44
+
45
+ #### Option B — CDN script tag
46
+
47
+ Skip the bundler — load Tyrell from a `<script>` tag in your HTML head:
48
+
49
+ ```html
50
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components@latest/css/tyrell.css">
51
+ <!-- tyrell-theme.css: auto-contrast, seed-based rebranding, themes. See TY_GUIDE.md#quick-start -->
52
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components@latest/css/tyrell-theme.css">
53
+ <script type="module" src="https://cdn.jsdelivr.net/npm/tyrell-components@latest/dist/tyrell.js"></script>
54
+ ```
55
+
56
+ Or self-host by copying `node_modules/tyrell-components/dist/tyrell.js`, `node_modules/tyrell-components/css/tyrell.css`, and `node_modules/tyrell-components/css/tyrell-theme.css` into your `public/` directory and pointing the tags there.
57
+
58
+ #### Which should I pick?
59
+
60
+ | | Bundler imports | CDN script tag |
61
+ |--|--|--|
62
+ | Component tree-shaking | ✅ Selective subpath imports | ❌ Whole bundle (~all components) |
63
+ | Icon registration | ✅ `registerIcons` directly imported | ⚠️ Must use `window.tyIcons.register` (timing-sensitive) |
64
+ | Build complexity | Standard import | One-time `<script>` tag in HTML |
65
+ | First paint | Same bundle as your app | Separate request, can FOUC |
66
+
67
+ Bundler imports are the better default for SPAs and SSR apps (Next.js, Remix, Vite). CDN is fine for prototyping or when you don't control the bundler.
68
+
69
+ ### 3. Import and use
70
+
71
+ ```tsx
72
+ import { TyButton, TyInput, TySelect } from 'tyrell-react'
73
+
74
+ function App() {
75
+ const [name, setName] = useState('')
76
+
77
+ return (
78
+ <div className="ty-canvas p-8">
79
+ <TyInput
80
+ label="Name"
81
+ value={name}
82
+ onChange={(e) => setName(e.detail.value)}
83
+ />
84
+ <TyButton flavor="primary" onClick={() => alert(name)}>
85
+ Submit
86
+ </TyButton>
87
+ </div>
88
+ )
89
+ }
90
+ ```
91
+
92
+ ## Import Styles
93
+
94
+ Two naming conventions:
95
+
96
+ ```tsx
97
+ // Tyrell-prefixed (explicit)
98
+ import { TyButton, TyInput, TySelect } from 'tyrell-react'
99
+
100
+ // Short names (clean)
101
+ import { Button, Input, Select } from 'tyrell-react'
102
+ ```
103
+
104
+ ## Event Handling
105
+
106
+ Always access values through `event.detail.value`:
107
+
108
+ ```tsx
109
+ // Correct
110
+ <TyInput onChange={(e) => setValue(e.detail.value)} />
111
+
112
+ // Wrong — event.value does not exist
113
+ <TyInput onChange={(e) => setValue(e.value)} />
114
+ ```
115
+
116
+ ### Input Components
117
+
118
+ - `onChange` fires on every keystroke (mapped from `input` event)
119
+ - `onChangeCommit` fires on blur (mapped from `change` event)
120
+
121
+ ```tsx
122
+ <TyInput
123
+ value={query}
124
+ onChange={(e) => setQuery(e.detail.value)}
125
+ onChangeCommit={(e) => search(e.detail.value)}
126
+ />
127
+ ```
128
+
129
+ Event detail structure:
130
+ ```ts
131
+ interface TyInputEventDetail {
132
+ value: any
133
+ formattedValue: string
134
+ rawValue: string
135
+ originalEvent: Event
136
+ }
137
+ ```
138
+
139
+ ### Selection Components
140
+
141
+ ```tsx
142
+ <TySelect onChange={(e) => setCountry(e.detail.value)}>
143
+ <TyOption value="us">United States</TyOption>
144
+ <TyOption value="de">Germany</TyOption>
145
+ </TySelect>
146
+ ```
147
+
148
+ `TySelect` is THE select control.
149
+ Single select by default — `e.detail.value` is the scalar value. Add `multiple`
150
+ for multi-select (`e.detail.value` becomes an array; `e.detail.values` is always
151
+ the array form):
152
+
153
+ ```tsx
154
+ <TySelect multiple value={tags} onChange={(e) => setTags(e.detail.values)}>
155
+ <TyOption value="react">React</TyOption>
156
+ <TyOption value="vue">Vue</TyOption>
157
+ </TySelect>
158
+ ```
159
+
160
+ ### Checkbox
161
+
162
+ ```tsx
163
+ <TyCheckbox
164
+ checked={agreed}
165
+ onChange={(e) => setAgreed(e.detail.value)}
166
+ />
167
+ ```
168
+
169
+ ### Modal Events
170
+
171
+ ```tsx
172
+ <TyModal
173
+ open={isOpen}
174
+ onOpen={() => console.log('opened')}
175
+ onClose={(e) => {
176
+ setIsOpen(false)
177
+ console.log('reason:', e.detail.reason)
178
+ }}
179
+ >
180
+ <div className="p-6 ty-elevated rounded-lg">
181
+ Modal content
182
+ </div>
183
+ </TyModal>
184
+ ```
185
+
186
+ When React controls the `open` state, the modal can still close itself via backdrop click or ESC — firing `onClose` — but if you haven't updated your state in the handler, the next render reopens it. For full React control, disable those close paths explicitly:
187
+
188
+ ```tsx
189
+ <TyModal
190
+ open={isOpen}
191
+ preventOutsideClick
192
+ preventEscape
193
+ onClose={() => setIsOpen(false)}
194
+ >
195
+ ...
196
+ </TyModal>
197
+ ```
198
+
199
+ Now only programmatic state changes (`setIsOpen(false)`) close the modal — note a fully guarded modal hides the built-in ✕, so render your own close button inside (WCAG 2.1.2). The older `closeOnOutsideClick={false}` / `closeOnEscape={false}` props are deprecated but still work.
200
+
201
+ ### Tag Events
202
+
203
+ ```tsx
204
+ <TyTag
205
+ value="react"
206
+ dismissible
207
+ onTagClick={(e) => console.log('clicked', e.detail.value)}
208
+ onTagDismiss={(e) => removeTag(e.detail.value)}
209
+ >
210
+ React
211
+ </TyTag>
212
+ ```
213
+
214
+ ## Controlled Components
215
+
216
+ ```tsx
217
+ function ContactForm() {
218
+ const [form, setForm] = useState({
219
+ name: '',
220
+ email: '',
221
+ country: '',
222
+ message: ''
223
+ })
224
+
225
+ const update = (field: string) => (e: any) =>
226
+ setForm(prev => ({ ...prev, [field]: e.detail.value }))
227
+
228
+ return (
229
+ <form onSubmit={handleSubmit}>
230
+ <TyInput label="Name" value={form.name} onChange={update('name')} required />
231
+ <TyInput label="Email" type="email" value={form.email} onChange={update('email')} required />
232
+ <TySelect label="Country" value={form.country} onChange={update('country')}>
233
+ <TyOption value="us">United States</TyOption>
234
+ <TyOption value="de">Germany</TyOption>
235
+ </TySelect>
236
+ <TyTextarea label="Message" value={form.message} onChange={update('message')} rows={4} />
237
+ <TyButton type="submit" flavor="primary">Send</TyButton>
238
+ </form>
239
+ )
240
+ }
241
+ ```
242
+
243
+ ## Multi-select — `<TySelect multiple>`
244
+
245
+ > With `multiple`, options are `<TyOption>` children (not `<TyTag>`), and selected
246
+ > chips render out-of-band via `<TySelectedOptions>` wherever you want them.
247
+
248
+ ```tsx
249
+ const [selected, setSelected] = useState<string[]>([])
250
+
251
+ <TySelect
252
+ multiple
253
+ id="tags"
254
+ value={selected}
255
+ onChange={(e) => setSelected(e.detail.values)}
256
+ label="Tags"
257
+ placeholder="Select tags..."
258
+ >
259
+ <TyOption value="react">React</TyOption>
260
+ <TyOption value="vue">Vue</TyOption>
261
+ <TyOption value="angular">Angular</TyOption>
262
+ </TySelect>
263
+
264
+ {/* dismissible chips — anywhere in the layout */}
265
+ <TySelectedOptions htmlFor="tags" />
266
+ ```
267
+
268
+ `TyOption` supports rich HTML children; give it a `label` prop for clean display
269
+ text in summaries/chips, and `data-*` attributes to feed `TySelectedOptions`
270
+ `<template>` chips.
271
+
272
+ ## Select with Data
273
+
274
+ Map your data to `<TyOption>` children:
275
+
276
+ ```tsx
277
+ <TySelect value={country} onChange={(e) => setCountry(e.detail.value)}>
278
+ {countries.map(({ value, text }) => (
279
+ <TyOption key={value} value={value}>{text}</TyOption>
280
+ ))}
281
+ </TySelect>
282
+ ```
283
+
284
+ `value` is the only selection input; `<TyOption selected>` selects nothing, except with `externalSelection`.
285
+
286
+ ## App-held selection — `externalSelection`
287
+
288
+ For hundreds of picks or a remote list, the app keeps the selection. Mark the picked options `selected`; a pick fires `onChange` with `{ value, selected }` (the option and its requested state) and changes nothing until you re-render. The select holds no `value`, submits nothing and doesn't enforce `required`, so show your own summary. Usually paired with `externalSearch`.
289
+
290
+ ```tsx
291
+ <TySelect multiple externalSelection
292
+ onChange={(e) => toggle(e.detail.value, e.detail.selected)}>
293
+ {rows.map((r) => (
294
+ <TyOption key={r.id} value={r.id} selected={picked.has(r.id)}>{r.name}</TyOption>
295
+ ))}
296
+ </TySelect>
297
+ ```
298
+
299
+ ## Refs and Imperative API
300
+
301
+ ### Modal
302
+
303
+ ```tsx
304
+ const modalRef = useRef<TyModalRef>(null)
305
+
306
+ <TyButton onClick={() => modalRef.current?.show()}>Open Modal</TyButton>
307
+
308
+ <TyModal ref={modalRef} onClose={() => console.log('closed')}>
309
+ <div className="p-6 ty-elevated rounded-lg">
310
+ <p>Modal content</p>
311
+ <TyButton onClick={() => modalRef.current?.hide()}>Close</TyButton>
312
+ </div>
313
+ </TyModal>
314
+ ```
315
+
316
+ ### Popup
317
+
318
+ ```tsx
319
+ const popupRef = useRef<TyPopupElement>(null)
320
+
321
+ // The popup's parent is its trigger: a click, Enter or Space toggles it.
322
+ // type="button" keeps the trigger from submitting a form it sits in.
323
+ <TyButton type="button">
324
+ Share
325
+ <TyPopup ref={popupRef}>
326
+ <div className="p-4 ty-floating rounded-lg">
327
+ Popup content
328
+ <TyButton onClick={() => popupRef.current?.closePopup()}>Done</TyButton>
329
+ </div>
330
+ </TyPopup>
331
+ </TyButton>
332
+ ```
333
+
334
+ ### Scroll Container
335
+
336
+ ```tsx
337
+ const scrollRef = useRef<TyScrollContainerRef>(null)
338
+
339
+ <TyScrollContainer ref={scrollRef} maxHeight="300px" shadow>
340
+ {/* Long content */}
341
+ </TyScrollContainer>
342
+
343
+ <TyButton onClick={() => scrollRef.current?.scrollToTop()}>Back to top</TyButton>
344
+ ```
345
+
346
+ ## Calendar with Custom Rendering
347
+
348
+ ```tsx
349
+ <TyCalendar
350
+ value="2026-03-24"
351
+ onChange={(e) => setDate(e.detail.value)}
352
+ dayContentFn={(ctx) => {
353
+ const el = document.createElement('div')
354
+ el.textContent = ctx.day
355
+ if (ctx.day === 25) {
356
+ el.style.fontWeight = 'bold'
357
+ el.style.color = 'var(--ty-color-primary)'
358
+ }
359
+ return el
360
+ }}
361
+ customCSS=".day-cell { border-radius: 8px; }"
362
+ />
363
+ ```
364
+
365
+ ## Custom Styling via CSS Variables
366
+
367
+ All components accept a typed `style` prop that supports CSS custom properties for per-instance color overrides. These cascade into the shadow DOM so they work despite encapsulation.
368
+
369
+ ### Input components
370
+
371
+ `TyInput`, `TyTextarea`, and `TySelect` all share the same tokens:
372
+
373
+ | Token | Purpose |
374
+ |-------|---------|
375
+ | `--input-bg` | Background |
376
+ | `--input-color` | Text color |
377
+ | `--input-border` | Border (default) |
378
+ | `--input-border-hover` | Border on hover |
379
+ | `--input-border-focus` | Border when focused |
380
+ | `--input-shadow-focus` | Focus ring (3px outer glow) |
381
+ | `--input-placeholder` | Placeholder text color |
382
+ | `--input-disabled-bg` | Disabled background |
383
+ | `--input-disabled-border` | Disabled border |
384
+ | `--input-disabled-color` | Disabled text |
385
+
386
+ ```tsx
387
+ <TyInput
388
+ label="Custom input"
389
+ style={{
390
+ '--input-bg': '#fdf4ff',
391
+ '--input-border': '#c084fc',
392
+ '--input-color': '#7e22ce',
393
+ '--input-border-focus': '#a855f7',
394
+ '--input-shadow-focus': 'rgba(168, 85, 247, 0.2)',
395
+ }}
396
+ />
397
+
398
+ <TySelect style={{ '--input-bg': '#fdf4ff', '--input-border': '#c084fc' }}>
399
+ <TyOption value="a">Option A</TyOption>
400
+ </TySelect>
401
+ ```
402
+
403
+ You can also scope overrides to a container — all input components inside inherit:
404
+
405
+ ```tsx
406
+ <div style={{ '--input-border': '#16a34a', '--input-border-focus': '#15803d' } as any}>
407
+ <TyInput label="Name" value={name} onChange={...} />
408
+ <TySelect label="Role" value={role} onChange={...}>...</TySelect>
409
+ </div>
410
+ ```
411
+
412
+ ### Button
413
+
414
+ ```tsx
415
+ <TyButton
416
+ appearance="outlined"
417
+ style={{
418
+ '--ty-button-color': '#8b5cf6',
419
+ '--ty-button-border': '#8b5cf6',
420
+ '--ty-button-bg-hover': '#ede9fe',
421
+ }}
422
+ >
423
+ Custom button
424
+ </TyButton>
425
+ ```
426
+
427
+ Available button tokens: `--ty-button-bg`, `--ty-button-bg-hover`, `--ty-button-color`, `--ty-button-border`.
428
+
429
+ ### Tag
430
+
431
+ ```tsx
432
+ <TyTag style={{ '--tag-color': '#e53e3e', '--tag-border-color': '#e53e3e' }}>
433
+ 12 / 12
434
+ </TyTag>
435
+ ```
436
+
437
+ Available tag tokens: `--tag-bg`, `--tag-color`, `--tag-border-color`. For stylesheet-level overrides use `::part(container)`:
438
+
439
+ ```css
440
+ ty-tag.my-tag::part(container) {
441
+ color: #e53e3e;
442
+ border-color: #e53e3e;
443
+ }
444
+ ```
445
+
446
+ ## Surface Levels
447
+
448
+ Surfaces are CSS classes — apply them via `className` on any HTML element. No React component required.
449
+
450
+ Five levels, from lowest to highest elevation:
451
+
452
+ | Class | Typical use |
453
+ |-------|------------|
454
+ | `ty-canvas` | App background, outermost wrapper |
455
+ | `ty-content` | Main content areas, page bodies |
456
+ | `ty-elevated` | Cards, panels, sidebars |
457
+ | `ty-floating` | Modals, drawers, sticky headers |
458
+ | `ty-input` | Form controls (handled automatically by form components) |
459
+
460
+ ```tsx
461
+ // App shell
462
+ <div className="ty-canvas min-h-screen p-8">
463
+
464
+ {/* Card */}
465
+ <div className="ty-elevated rounded-xl p-6 border ty-border">
466
+ <h2 className="ty-text++ text-xl font-bold">Card title</h2>
467
+ <p className="ty-text-">Card body</p>
468
+ </div>
469
+
470
+ {/* Modal content panel */}
471
+ <TyModal open={isOpen} onClose={() => setIsOpen(false)}>
472
+ <div className="ty-floating p-6 rounded-xl max-w-md">
473
+ Modal content
474
+ </div>
475
+ </TyModal>
476
+
477
+ </div>
478
+ ```
479
+
480
+ Surfaces handle background color and text color automatically via the Tyrell design system. Pair with Tailwind for spacing, layout, and typography — but use only Tyrell classes for colors:
481
+
482
+ ```tsx
483
+ // Correct: Tyrell for color, Tailwind for everything else
484
+ <div className="ty-elevated p-6 rounded-lg flex items-center gap-4">
485
+
486
+ // Wrong: mixing color systems
487
+ <div className="bg-white p-6 rounded-lg">
488
+ ```
489
+
490
+ ## Text Classes
491
+
492
+ Five emphasis levels — no color, just weight:
493
+
494
+ ```tsx
495
+ <h1 className="ty-text++ text-3xl">Page title</h1>
496
+ <h2 className="ty-text+ text-xl">Section heading</h2>
497
+ <p className="ty-text">Body text</p>
498
+ <span className="ty-text-">Secondary info</span>
499
+ <small className="ty-text--">Fine print</small>
500
+ ```
501
+
502
+ Semantic text colors follow the same five-variant pattern:
503
+
504
+ ```tsx
505
+ <p className="ty-text-primary">Primary</p>
506
+ <p className="ty-text-primary+">Stronger primary</p>
507
+ <p className="ty-text-primary-">Softer primary</p>
508
+ ```
509
+
510
+ Available colors: `primary`, `success`, `danger`, `warning`, `neutral`.
511
+
512
+ ## Border Classes
513
+
514
+ Five emphasis levels:
515
+
516
+ ```tsx
517
+ <div className="border ty-border++">Strong border</div>
518
+ <div className="border ty-border+">Heavy border</div>
519
+ <div className="border ty-border">Normal border</div>
520
+ <div className="border ty-border-">Soft border</div>
521
+ <div className="border ty-border--">Minimal border</div>
522
+ ```
523
+
524
+ Semantic borders:
525
+
526
+ ```tsx
527
+ <div className="border ty-border-primary">Primary border</div>
528
+ <div className="border ty-border-danger">Danger border</div>
529
+ <div className="border ty-border-success">Success border</div>
530
+ ```
531
+
532
+ Available colors: `primary`, `success`, `danger`, `warning`, `neutral`.
533
+
534
+ ## Background Colors
535
+
536
+ Use `ty-bg-*` for small UI elements — badges, alerts, status indicators. Not for cards or layout areas (use surfaces for those).
537
+
538
+ ```tsx
539
+ {/* Status badge */}
540
+ <span className="ty-bg-success- ty-text-success rounded-full px-2 py-0.5 text-xs">Active</span>
541
+
542
+ {/* Alert banner */}
543
+ <div className="ty-bg-danger- ty-text-danger rounded-lg p-4">
544
+ Something went wrong
545
+ </div>
546
+ ```
547
+
548
+ Three variants per color — stronger (`+`), base, softer (`-`):
549
+
550
+ ```tsx
551
+ <div className="ty-bg-primary+">Stronger</div>
552
+ <div className="ty-bg-primary">Base</div>
553
+ <div className="ty-bg-primary-">Softer</div>
554
+ ```
555
+
556
+ Available colors: `primary`, `success`, `danger`, `warning`, `neutral`.
557
+
558
+ ## Dark Mode
559
+
560
+ Tyrell responds to a `dark` class on `<html>`. All color variables switch automatically.
561
+
562
+ ```tsx
563
+ // Simple toggle hook
564
+ function useTheme() {
565
+ const [dark, setDark] = useState(
566
+ () => localStorage.getItem('theme') === 'dark'
567
+ || window.matchMedia('(prefers-color-scheme: dark)').matches
568
+ )
569
+
570
+ useEffect(() => {
571
+ document.documentElement.classList.toggle('dark', dark)
572
+ localStorage.setItem('theme', dark ? 'dark' : 'light')
573
+ }, [dark])
574
+
575
+ return { dark, toggleTheme: () => setDark(d => !d) }
576
+ }
577
+ ```
578
+
579
+ Restore preference before first render to avoid flash (add to your HTML `<head>`):
580
+
581
+ ```html
582
+ <script>
583
+ const theme = localStorage.getItem('theme')
584
+ || (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light')
585
+ if (theme === 'dark') document.documentElement.classList.add('dark')
586
+ </script>
587
+ ```
588
+
589
+ ### Next.js
590
+
591
+ In Next.js, add the script to your root layout and mark it `suppressHydrationWarning` on `<html>`:
592
+
593
+ ```tsx
594
+ // app/layout.tsx
595
+ export default function RootLayout({ children }) {
596
+ return (
597
+ <html lang="en" suppressHydrationWarning>
598
+ <head>
599
+ <script dangerouslySetInnerHTML={{ __html: `
600
+ const t = localStorage.getItem('theme')
601
+ || (matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light')
602
+ if (t === 'dark') document.documentElement.classList.add('dark')
603
+ `}} />
604
+ </head>
605
+ <body className="ty-canvas">{children}</body>
606
+ </html>
607
+ )
608
+ }
609
+ ```
610
+
611
+ ## Global Color Customization
612
+
613
+ Override the whole palette at `:root` level to rebrand Tyrell:
614
+
615
+ ```css
616
+ :root {
617
+ --ty-color-primary-strong: #0034c7;
618
+ --ty-color-primary-bold: #1c40a8;
619
+ --ty-color-primary: #4367cd;
620
+ --ty-color-primary-soft: #60a5fa;
621
+ --ty-color-primary-faint: #93c5fd;
622
+ --ty-bg-primary-bold: #bfdbfe;
623
+ --ty-bg-primary: #dbeafe;
624
+ --ty-bg-primary-soft: #eff6ff;
625
+ }
626
+
627
+ :root.dark {
628
+ --ty-color-primary-strong: #93c5fd;
629
+ --ty-color-primary: #3b82f6;
630
+ --ty-bg-primary: #172554;
631
+ }
632
+ ```
633
+
634
+ Token pattern: `--ty-color-{name}-{strong|bold|soft|faint}`, `--ty-bg-{name}-{bold|soft}`, `--ty-border-{name}`.
635
+
636
+ This retunes every component that uses that color. To override a single instance only, use the per-component CSS variables in the section above.
637
+
638
+ ## Numeric Input Types
639
+
640
+ ```tsx
641
+ // Currency
642
+ <TyInput type="currency" currency="EUR" locale="de-DE" value={price}
643
+ onChange={(e) => setPrice(e.detail.value)} />
644
+
645
+ // Percentage
646
+ <TyInput type="percent" precision={1} value={rate}
647
+ onChange={(e) => setRate(e.detail.value)} />
648
+
649
+ // Compact numbers (1K, 1M)
650
+ <TyInput type="compact" value={count}
651
+ onChange={(e) => setCount(e.detail.value)} />
652
+ ```
653
+
654
+ ## Tabs and Wizard
655
+
656
+ `TyTabs` dispatches its change event with detail `{ activeId, activeIndex, previousId, previousIndex }` — read `event.detail.activeId` (not `value`):
657
+
658
+ ```tsx
659
+ import { TyTabs, TyTab, type TabChangeDetail } from 'tyrell-react'
660
+
661
+ const [activeTab, setActiveTab] = useState('overview')
662
+
663
+ <TyTabs
664
+ active={activeTab}
665
+ onChange={(e: CustomEvent<TabChangeDetail>) => setActiveTab(e.detail.activeId)}
666
+ >
667
+ <TyTab id="overview" label="Overview">
668
+ <p>Overview content</p>
669
+ </TyTab>
670
+ <TyTab id="settings" label="Settings">
671
+ <p>Settings content</p>
672
+ </TyTab>
673
+ </TyTabs>
674
+ ```
675
+
676
+ A `lazy` tab with no content calls `onTabLoad` when it's shown (never the tab
677
+ shown first, the `active` one: render its content up front). It spins until children arrive;
678
+ if loading fails, call `loadFailed()` on the element for an error and Retry:
679
+
680
+ ```tsx
681
+ const ref = useRef<HTMLElement & { loadFailed(): void }>(null);
682
+
683
+ <TyTab ref={ref} id="reports" label="Reports" lazy
684
+ onTabLoad={() => fetchReports().then(setReports, () => ref.current?.loadFailed())}>
685
+ {reports && <ReportList reports={reports} />}
686
+ </TyTab>
687
+ ```
688
+
689
+ Tabs scroll by default — each button has a `min-width: 72px` floor
690
+ (`--ty-tab-min-width`) and the bar grows a `…` jump menu once they no longer fit. Pass `fixed` to divide the bar
691
+ equally between them instead: no floor, no overflow, no jump menu, labels
692
+ ellipsize if squeezed. It's a presence boolean, so `fixed={false}` renders no
693
+ attribute at all. Use it for **2–5** tabs — past that the shares are too narrow
694
+ to read, and the scrollable default with its `…` menu is the right tool:
695
+
696
+ ```tsx
697
+ <TyTabs fixed height="300px" active={activeTab} onChange={…}>
698
+ ```
699
+
700
+ ```tsx
701
+ <TyWizard active={step} completed={completedSteps.join(',')}>
702
+ <TyStep id="info" label="Information">Step 1 content</TyStep>
703
+ <TyStep id="review" label="Review">Step 2 content</TyStep>
704
+ <TyStep id="confirm" label="Confirm">Step 3 content</TyStep>
705
+ </TyWizard>
706
+ ```
707
+
708
+ ## Reorderable lists (ty-sortable)
709
+
710
+ `TySortable` never moves its children. A drop (or a keyboard move) calls `onChange` (`ty-sortable-change`) on the destination list, and the list holds the result on screen until you re-render the items in the new order. Give each item a stable `key` and a `data-key` (or `id`):
711
+
712
+ ```tsx
713
+ import { useState } from 'react'
714
+ import { TySortable, TyIcon, type TySortableChangeDetail } from 'tyrell-react'
715
+
716
+ function Board() {
717
+ const [cols, setCols] = useState<Record<string, string[]>>({ todo: ['a', 'b'], done: ['c'] })
718
+ const [saving, setSaving] = useState(false)
719
+
720
+ const onChange = async (e: CustomEvent<TySortableChangeDetail>) => {
721
+ const { value } = e.detail
722
+ setSaving(true)
723
+ try {
724
+ await save(value)
725
+ setCols((c) => ({ ...c, ...value.order })) // new key order per touched list
726
+ } finally {
727
+ setSaving(false) // order unchanged: the item snaps back
728
+ }
729
+ }
730
+
731
+ const column = (id: string, label: string) => (
732
+ <TySortable id={id} group="board" label={label} aria-busy={saving || undefined} onChange={onChange}>
733
+ {cols[id].map((k) => (
734
+ <div key={k} data-key={k}>
735
+ <button type="button" data-handle aria-label={`Move ${k}`}>
736
+ <TyIcon name="grip-vertical" />
737
+ </button>
738
+ {k}
739
+ </div>
740
+ ))}
741
+ </TySortable>
742
+ )
743
+
744
+ return <>{column('todo', 'To do')}{column('done', 'Done')}</>
745
+ }
746
+ ```
747
+
748
+ - `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, save a rank between `value.to.prev` and `value.to.next` instead.
749
+ - `aria-busy` while saving makes a refused save snap back as soon as it clears. Without it, call `settle('rejected')` on the element (`e.currentTarget`, read before the first `await`), or `e.preventDefault()` to reject at once. To update optimistically, call `setCols` before saving.
750
+ - 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.
751
+ - `onStart`, `onCancel` and `onSettle` map the other events. `canDrop` and `labels` are set as properties; the ref's `move('a', { to: 'done', index: 0 })` moves without a pointer. Full prop list: [tyrell-react README](../../packages/react/README.md#sortable-lists).
752
+
753
+ ## Icons
754
+
755
+ Register once, from the same client-side entry that imports `tyrell-components` (in Next.js, a `'use client'` module):
756
+
757
+ ```js
758
+ import { registerIcons } from 'tyrell-components/icons/registry'
759
+ import { check, chevronDown } from 'tyrell-components/icons/lucide'
760
+
761
+ registerIcons({ check, 'action-down': chevronDown }) // the key is the name
762
+ ```
763
+
764
+ ```tsx
765
+ <TyIcon name="check" size="sm" />
766
+ <TyIcon name="action-down" />
767
+ ```
768
+
769
+ On the CDN setup, register with `window.tyIcons.register` instead: `registerIcons` from npm would write to a second copy of the registry that the CDN components never read.
770
+
771
+ Sets, tree-shaking, custom SVGs and troubleshooting: [ICONS_GUIDE.md](../ICONS_GUIDE.md#in-javascript).
772
+
773
+ ## Slots
774
+
775
+ Use `slot="start"` and `slot="end"` for icons inside buttons, inputs, and tags. The component handles spacing automatically.
776
+
777
+ ```tsx
778
+ {/* Button with start icon */}
779
+ <TyButton flavor="primary">
780
+ <TyIcon slot="start" name="save" size="sm" />
781
+ Save
782
+ </TyButton>
783
+
784
+ {/* Button with end icon */}
785
+ <TyButton flavor="neutral">
786
+ Next
787
+ <TyIcon slot="end" name="chevron-right" size="sm" />
788
+ </TyButton>
789
+
790
+ {/* Input with icon slots */}
791
+ <TyInput type="currency" currency="EUR" label="Price">
792
+ <TyIcon slot="start" name="euro" />
793
+ </TyInput>
794
+
795
+ <TyInput type="email" label="Email">
796
+ <TyIcon slot="start" name="mail" size="sm" />
797
+ <TyIcon slot="end" name="check" size="sm" />
798
+ </TyInput>
799
+
800
+ {/* Tag with icon */}
801
+ <TyTag flavor="primary" dismissible>
802
+ <TyIcon slot="start" name="star" size="sm" />
803
+ Featured
804
+ </TyTag>
805
+
806
+ {/* Rich tab labels via slot="label-{id}" */}
807
+ <TyTabs height="400px">
808
+ <span slot="label-settings" className="flex items-center gap-2">
809
+ <TyIcon name="settings" size="sm" />
810
+ Settings
811
+ </span>
812
+ <TyTab id="settings" label="Settings">Content</TyTab>
813
+ </TyTabs>
814
+ ```
815
+
816
+ ## Form Integration
817
+
818
+ Tyrell components participate in HTML forms via `ElementInternals`:
819
+
820
+ ```tsx
821
+ <form onSubmit={(e) => {
822
+ e.preventDefault()
823
+ const data = new FormData(e.currentTarget)
824
+ console.log(Object.fromEntries(data.entries()))
825
+ }}>
826
+ <TyInput name="email" type="email" required label="Email" />
827
+ <TySelect name="role" label="Role">
828
+ <TyOption value="admin">Admin</TyOption>
829
+ <TyOption value="user">User</TyOption>
830
+ </TySelect>
831
+ <label><TyCheckbox name="agree" required /> I agree to terms</label>
832
+ <TyButton type="submit" flavor="primary">Submit</TyButton>
833
+ </form>
834
+ ```
835
+
836
+ The browser validates before `submit` fires, so `onSubmit` only runs when every field passes. Failing fields show their message under the field; see [TY_GUIDE → Forms and validation](../TY_GUIDE.md#forms-and-validation).
837
+
838
+ ### Validation and form props
839
+
840
+ | Component | Props |
841
+ |-----------|-------|
842
+ | `TyInput` | `required`, `pattern`, `minLength`, `maxLength`, `min`, `max`, `tooShortMessage`, `tooLongMessage`, `error` |
843
+ | `TyTextarea` | `required`, `minLength`, `maxLength`, `tooShortMessage`, `tooLongMessage`, `error`. Passed as the `minlength`, `maxlength`, `too-short-message` and `too-long-message` attributes, same as `TyInput` |
844
+ | `TySelect` | `required`, `error?: string` (message under the field; `''` or leaving it out clears it) |
845
+ | `TyDatePicker` | `required`, `error?: string`, `native` (submit `YYYY-MM-DD` / `YYYY-MM-DDTHH:mm` like `<input type="date">` instead of a UTC instant). `value` takes any string the element reads, or epoch milliseconds |
846
+ | `TyCalendar` | `required`, `min`, `max`, `name`. No error line: the browser shows its bubble on the day grid |
847
+ | `TyButton` | `type`, `name`, `value`, `form` (id of the form to submit or reset when the button sits outside it), `loading`, `disabled` |
848
+
849
+ `error` is yours: validation never overwrites or removes it, so set it to `''` to let the field's own messages show again.
850
+
851
+ `TyButton` submits through `form.requestSubmit()`, so validation runs and `onSubmit` gets the browser's real submit event. `onClick` runs first, and `e.preventDefault()` there stops the submit:
852
+
853
+ ```tsx
854
+ <TyButton type="submit" onClick={(e) => { if (!confirm('Send?')) e.preventDefault() }}>
855
+ Send
856
+ </TyButton>
857
+ ```
858
+
859
+ To show a spinner while saving, set `loading` from the click handler: that press still submits, and later presses are blocked until `loading` is cleared. A disabled or loading button fires no `onClick`.
860
+
861
+ ### File uploads
862
+
863
+ `TyFileUpload` is uncontrolled — it owns the `File[]`. Read it from `event.detail.files` in `onChange`, or pull it off the form via `FormData` on submit:
864
+
865
+ ```tsx
866
+ import { TyFileUpload } from 'tyrell-react'
867
+
868
+ function UploadForm() {
869
+ return (
870
+ <form
871
+ encType="multipart/form-data"
872
+ onSubmit={async (e) => {
873
+ e.preventDefault()
874
+ const fd = new FormData(e.currentTarget)
875
+ await fetch('/api/upload', { method: 'POST', body: fd })
876
+ }}
877
+ >
878
+ <TyFileUpload
879
+ name="docs"
880
+ label="Attachments"
881
+ multiple
882
+ accept=".pdf,.docx"
883
+ onChange={(e) => console.log(e.detail.files)}
884
+ />
885
+ <TyButton type="submit" flavor="primary">Upload</TyButton>
886
+ </form>
887
+ )
888
+ }
889
+ ```
890
+
891
+ The `change` event fires on browse, drop, and remove (including the empty array when the last file is removed). For per-file upload progress, drive an `XMLHttpRequest.upload.onprogress` from your own state — the component is a picker, not an uploader.
892
+
893
+ ## Next.js Integration
894
+
895
+ ### App Router Setup
896
+
897
+ ```tsx
898
+ // app/layout.tsx
899
+ export default function RootLayout({ children }: { children: React.ReactNode }) {
900
+ return (
901
+ <html lang="en">
902
+ <head>
903
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components@latest/css/tyrell.css" />
904
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components@latest/css/tyrell-theme.css" />
905
+ <script type="module" src="https://cdn.jsdelivr.net/npm/tyrell-components@latest/dist/tyrell.js" />
906
+ </head>
907
+ <body className="ty-canvas">{children}</body>
908
+ </html>
909
+ )
910
+ }
911
+ ```
912
+
913
+ ### Client Components
914
+
915
+ Tyrell components require the browser — use `'use client'` directive:
916
+
917
+ ```tsx
918
+ 'use client'
919
+
920
+ import { useState } from 'react'
921
+ import { TyInput, TyButton } from 'tyrell-react'
922
+
923
+ export default function SearchForm() {
924
+ const [query, setQuery] = useState('')
925
+ return (
926
+ <div className="flex gap-2">
927
+ <TyInput value={query} onChange={(e) => setQuery(e.detail.value)} placeholder="Search..." />
928
+ <TyButton flavor="primary" onClick={() => search(query)}>Search</TyButton>
929
+ </div>
930
+ )
931
+ }
932
+ ```
933
+
934
+ ### Wait for Components
935
+
936
+ If you see FOUC (flash of unstyled content), gate rendering until Tyrell is loaded:
937
+
938
+ ```tsx
939
+ 'use client'
940
+ import { useState, useEffect } from 'react'
941
+
942
+ export function TyLoader({ children }: { children: React.ReactNode }) {
943
+ const [loaded, setLoaded] = useState(false)
944
+
945
+ useEffect(() => {
946
+ const check = () => {
947
+ if (window.customElements?.get('ty-button')) {
948
+ setLoaded(true)
949
+ } else {
950
+ setTimeout(check, 50)
951
+ }
952
+ }
953
+ check()
954
+ }, [])
955
+
956
+ if (!loaded) return null
957
+ return <>{children}</>
958
+ }
959
+ ```
960
+
961
+ ## Component Reference
962
+
963
+ | Component | Value Prop | Event | Ref Methods |
964
+ |-----------|-----------|-------|-------------|
965
+ | `TyButton` | -- | `onClick` | -- |
966
+ | `TyInput` | `value` | `onChange` / `onChangeCommit` | -- |
967
+ | `TyTextarea` | `value` | `onChange` / `onChangeCommit` | -- |
968
+ | `TyCheckbox` | `checked` | `onChange` | -- |
969
+ | `TySelect` | `value` (string, or array when `multiple`) | `onChange` / `onSearch` / `onOpen` / `onClose` | -- |
970
+ | `TySelectedOptions` | `htmlFor` | -- | -- |
971
+ | `TyDatePicker` | `value` (ISO string or epoch ms; `native` for `YYYY-MM-DD`) | `onChange` / `onOpen` / `onClose` | -- |
972
+ | `TyCalendar` | `value` (ISO) | `onChange` / `onNavigate` | -- |
973
+ | `TyTabs` | `active` | `onChange` | -- |
974
+ | `TyModal` | `open` | `onOpen` / `onClose` | `show()` / `hide()` |
975
+ | `TyPopup` | `manual` | -- | `openPopup()` / `closePopup()` / `togglePopup()` |
976
+ | `TyTag` | `value` | `onTagClick` / `onTagDismiss` | -- |
977
+ | `TyIcon` | `name` | -- | -- |
978
+ | `TyCopy` | `value` | -- | -- |
979
+ | `TyFileUpload` | -- (uncontrolled, read `files` from event) | `onChange` | -- |
980
+ | `TyTooltip` | -- | -- | -- |
981
+ | `TyScrollContainer` | -- | -- | `scrollToTop()` / `scrollToBottom()` / `updateShadows()` |
982
+ | `TyWizard` | `active` | -- | -- |
983
+ | `TySortable` | -- (render children in `detail.value.order`) | `onChange` / `onStart` / `onCancel` / `onSettle` | `move()` / `settle()` |