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,682 @@
1
+ # Svelte + Tyrell Guide
2
+
3
+ Use Tyrell web components in Svelte 5 (and Svelte 4) natively — no wrapper package needed. Svelte has the cleanest custom-element story of any major framework: tags work as-is, events work via `on:event`, and reactivity flows through `bind:` and `$state` without ceremony.
4
+
5
+ For installation, subpath imports, and the side-effects model, see [JAVASCRIPT_GUIDE.md](./JAVASCRIPT_GUIDE.md).
6
+
7
+ ## Setup
8
+
9
+ ### 1. Install
10
+
11
+ ```bash
12
+ npm install tyrell-components
13
+ ```
14
+
15
+ ### 2. Register components and CSS
16
+
17
+ In your app entry (`src/app.js`, `src/main.ts`, or a layout):
18
+
19
+ ```js
20
+ import 'tyrell-components/css/tyrell.css'
21
+ import 'tyrell-components/css/tyrell-theme.css' // auto-contrast, seed rebranding, themes — see TY_GUIDE.md#quick-start
22
+ import 'tyrell-components' // or specific subpaths
23
+ ```
24
+
25
+ That's it — Svelte's compiler does not need configuration to recognize custom elements. Any tag with a hyphen is treated as a custom element automatically.
26
+
27
+ ## Native usage (Svelte 5)
28
+
29
+ ```svelte
30
+ <script>
31
+ let email = $state('')
32
+ function submit() {
33
+ console.log('submit:', email)
34
+ }
35
+ </script>
36
+
37
+ <ty-input
38
+ label="Email"
39
+ type="email"
40
+ value={email}
41
+ onchange={(e) => email = e.detail.value}
42
+ />
43
+ <ty-button flavor="primary" onclick={submit}>Submit</ty-button>
44
+ ```
45
+
46
+ Svelte 5 uses standard DOM event handler attributes (`onclick`, `onchange`) — these work directly with custom events. Event payload lives on `e.detail`.
47
+
48
+ ## Native usage (Svelte 4)
49
+
50
+ ```svelte
51
+ <script>
52
+ let email = ''
53
+ </script>
54
+
55
+ <ty-input
56
+ label="Email"
57
+ type="email"
58
+ value={email}
59
+ on:change={(e) => email = e.detail.value}
60
+ />
61
+ <ty-button flavor="primary" on:click={() => console.log(email)}>
62
+ Submit
63
+ </ty-button>
64
+ ```
65
+
66
+ Svelte 4's `on:event` directive registers `addEventListener`. Payload still on `e.detail`.
67
+
68
+ ## Attribute vs property
69
+
70
+ Svelte sets attributes by default. For boolean and complex values, use `prop:` to set the JS property explicitly:
71
+
72
+ ```svelte
73
+ <!-- attribute (string only) -->
74
+ <ty-button disabled={isLoading}>Save</ty-button>
75
+
76
+ <!-- property (any type) -->
77
+ <ty-select multiple prop:value={selected}>
78
+ {#each tags as t}
79
+ <ty-option value={t}>{t}</ty-option>
80
+ {/each}
81
+ </ty-select>
82
+ ```
83
+
84
+ Rules of thumb:
85
+ - **Strings, simple booleans** — attributes are fine: `disabled`, `label="Email"`, `flavor="primary"`.
86
+ - **Arrays, objects, callbacks** — must use `prop:` (attributes serialize to strings).
87
+ - **Multi-select values when array** — `prop:value={[...]}` on `ty-select multiple`.
88
+
89
+ ## Two-way binding
90
+
91
+ Svelte's `bind:value` works on web components for the `value` property:
92
+
93
+ ```svelte
94
+ <script>
95
+ let email = $state('')
96
+ </script>
97
+
98
+ <ty-input bind:value={email} label="Email" />
99
+ <p>You typed: {email}</p>
100
+ ```
101
+
102
+ This is reactive in both directions — typing updates `email`, programmatically changing `email` updates the input.
103
+
104
+ For multiselect or any case where you need `event.detail.values` (plural), use explicit handlers:
105
+
106
+ ```svelte
107
+ <script>
108
+ let selected = $state([])
109
+ </script>
110
+
111
+ <ty-select
112
+ multiple
113
+ prop:value={selected}
114
+ onchange={(e) => selected = e.detail.values}
115
+ >
116
+ <ty-option value="apple">Apple</ty-option>
117
+ <ty-option value="banana">Banana</ty-option>
118
+ <ty-option value="cherry">Cherry</ty-option>
119
+ </ty-select>
120
+ ```
121
+
122
+ ## Composition with child elements
123
+
124
+ Slotted children work naturally — `{#each}` blocks render reactive options:
125
+
126
+ ```svelte
127
+ <script>
128
+ let country = $state('us')
129
+ const countries = [
130
+ { code: 'us', name: 'United States' },
131
+ { code: 'uk', name: 'United Kingdom' },
132
+ { code: 'fr', name: 'France' },
133
+ ]
134
+ </script>
135
+
136
+ <ty-select
137
+ label="Country"
138
+ value={country}
139
+ onchange={(e) => country = e.detail.value}
140
+ >
141
+ {#each countries as c (c.code)}
142
+ <ty-option value={c.code}>{c.name}</ty-option>
143
+ {/each}
144
+ </ty-select>
145
+
146
+ <!-- ty-select: single by default,
147
+ add `multiple` for multi-select ({e.detail.values} = array). -->
148
+ ```
149
+
150
+ ## Icons
151
+
152
+ Register at startup, next to the component import:
153
+
154
+ ```js
155
+ import { registerIcons } from 'tyrell-components/icons/registry'
156
+ import { check, chevronDown } from 'tyrell-components/icons/lucide'
157
+
158
+ registerIcons({ check, 'action-down': chevronDown }) // the key is the name
159
+ ```
160
+
161
+ ```svelte
162
+ <ty-icon name="check" size="md" />
163
+ ```
164
+
165
+ Sets, tree-shaking, custom SVGs and troubleshooting: [ICONS_GUIDE.md](../ICONS_GUIDE.md#in-javascript).
166
+
167
+ ## Refs and imperative API
168
+
169
+ `bind:this` gives you the underlying element:
170
+
171
+ ```svelte
172
+ <script>
173
+ let modal
174
+ function showModal() { modal.show() }
175
+ function closeModal() { modal.close() }
176
+ </script>
177
+
178
+ <ty-button onclick={showModal}>Open</ty-button>
179
+
180
+ <ty-modal bind:this={modal}>
181
+ <h2 class="ty-text++">Confirm</h2>
182
+ <p class="ty-text">Are you sure?</p>
183
+ <ty-button flavor="primary" onclick={closeModal}>OK</ty-button>
184
+ </ty-modal>
185
+ ```
186
+
187
+ If you need to call methods at mount time, wait for definition:
188
+
189
+ ```svelte
190
+ <script>
191
+ import { onMount } from 'svelte'
192
+ let modal
193
+
194
+ onMount(async () => {
195
+ await customElements.whenDefined('ty-modal')
196
+ // safe to call modal.show() now
197
+ })
198
+ </script>
199
+ ```
200
+
201
+ ## Form controls
202
+
203
+ ### ty-textarea
204
+
205
+ ```svelte
206
+ <script>
207
+ let bio = $state('')
208
+ </script>
209
+
210
+ <ty-textarea
211
+ label="Bio"
212
+ placeholder="Tell us about yourself..."
213
+ rows="4"
214
+ max-height="200px"
215
+ value={bio}
216
+ onchange={(e) => bio = e.detail.value}
217
+ />
218
+ ```
219
+
220
+ Svelte 4: `on:change={(e) => bio = e.detail.value}`.
221
+
222
+ Attrs: `rows`, `min-height`, `max-height`, `resize` (`none`|`both`|`horizontal`|`vertical`).
223
+
224
+ ### ty-checkbox and ty-switch
225
+
226
+ Both are "just the control" primitives — wrap in `<label>` to make the text clickable:
227
+
228
+ ```svelte
229
+ <script>
230
+ let agreed = $state(false)
231
+ let darkMode = $state(false)
232
+ </script>
233
+
234
+ <label class="flex items-center gap-2">
235
+ <ty-checkbox
236
+ checked={agreed}
237
+ onchange={(e) => agreed = e.detail.checked}
238
+ />
239
+ I agree to the terms
240
+ </label>
241
+
242
+ <label class="flex items-center gap-2">
243
+ <ty-switch
244
+ checked={darkMode}
245
+ onchange={(e) => darkMode = e.detail.checked}
246
+ />
247
+ Dark mode
248
+ </label>
249
+ ```
250
+
251
+ Event detail: `{ value, checked, formValue, originalEvent }`.
252
+
253
+ ### ty-radio-group / ty-radio
254
+
255
+ ```svelte
256
+ <script>
257
+ let plan = $state('starter')
258
+ const plans = [
259
+ { value: 'starter', label: 'Starter' },
260
+ { value: 'pro', label: 'Pro' },
261
+ { value: 'enterprise', label: 'Enterprise' },
262
+ ]
263
+ </script>
264
+
265
+ <ty-radio-group
266
+ label="Plan"
267
+ value={plan}
268
+ onchange={(e) => plan = e.detail.value}
269
+ >
270
+ {#each plans as p (p.value)}
271
+ <label class="flex items-center gap-2">
272
+ <ty-radio value={p.value} />
273
+ {p.label}
274
+ </label>
275
+ {/each}
276
+ </ty-radio-group>
277
+ ```
278
+
279
+ Add `orientation="horizontal"` to `ty-radio-group` for a side-by-side layout.
280
+
281
+ ### ty-file-upload
282
+
283
+ ```svelte
284
+ <script>
285
+ let files = $state([])
286
+ </script>
287
+
288
+ <ty-file-upload
289
+ label="Attachments"
290
+ accept="image/*,.pdf"
291
+ multiple
292
+ onchange={(e) => files = e.detail.files}
293
+ />
294
+ {#if files.length}
295
+ <p>{files.length} file(s) selected</p>
296
+ {/if}
297
+ ```
298
+
299
+ Event detail: `{ value: File[], files: File[], names: string[] }`. Files appear in `FormData` automatically on form submit.
300
+
301
+ ---
302
+
303
+ ## Date picker and calendar
304
+
305
+ ### ty-date-picker
306
+
307
+ ```svelte
308
+ <script>
309
+ let date = $state(null)
310
+ </script>
311
+
312
+ <ty-date-picker
313
+ label="Start Date"
314
+ placeholder="Select a date..."
315
+ value={date}
316
+ onchange={(e) => date = e.detail.value}
317
+ />
318
+ ```
319
+
320
+ Value is a UTC ISO string (`2024-09-21T08:30:00.000Z`). Date-only, it's the instant the day starts in the browser's timezone, so it reads a day early east of UTC (Sept 21 in Zagreb is `2024-09-20T22:00:00.000Z`). Add `native` for `YYYY-MM-DD` / `YYYY-MM-DDTHH:mm` like `<input type="date">`; `e.detail.localValue` has that shape either way. Pass `null` or empty string to clear. Add `with-time` for datetime selection, `locale="de-DE"` for locale-aware display.
321
+
322
+ ### ty-calendar (standalone)
323
+
324
+ ```svelte
325
+ <script>
326
+ const now = new Date()
327
+ let year = $state(now.getFullYear())
328
+ let month = $state(now.getMonth() + 1)
329
+ let day = $state(null)
330
+
331
+ function onDaySelect(e) {
332
+ year = e.detail.year
333
+ month = e.detail.month
334
+ day = e.detail.day
335
+ }
336
+ </script>
337
+
338
+ <ty-calendar
339
+ {year}
340
+ {month}
341
+ {day}
342
+ onchange={onDaySelect}
343
+ />
344
+ ```
345
+
346
+ Event detail: `{ year, month, day, action, source }`. Form value is ISO `YYYY-MM-DD`.
347
+
348
+ ---
349
+
350
+ ## Tabs and wizard
351
+
352
+ Svelte 5 binds hyphenated event names as attributes: `onty-tab-change`, `onty-wizard-step-change`.
353
+
354
+ ### ty-tabs
355
+
356
+ ```svelte
357
+ <script>
358
+ let activeTab = $state('overview')
359
+ </script>
360
+
361
+ <ty-tabs height="300px" active={activeTab} onty-tab-change={(e) => activeTab = e.detail.activeId}>
362
+ <ty-tab id="overview" label="Overview">
363
+ <div class="p-4">Overview content</div>
364
+ </ty-tab>
365
+ <ty-tab id="details" label="Details">
366
+ <div class="p-4">Details content</div>
367
+ </ty-tab>
368
+ </ty-tabs>
369
+ ```
370
+
371
+ Svelte 4 can use `on:ty-tab-change` directly:
372
+
373
+ ```svelte
374
+ <ty-tabs height="300px" active={activeTab} on:ty-tab-change={(e) => activeTab = e.detail.activeId}>
375
+ ```
376
+
377
+ Rich tab labels via named slots:
378
+
379
+ ```svelte
380
+ <ty-tabs height="300px" active="overview">
381
+ <span slot="label-overview" class="flex items-center gap-2">
382
+ <ty-icon name="layout-dashboard" size="sm" />
383
+ Overview
384
+ </span>
385
+ <ty-tab id="overview" label="Overview">…</ty-tab>
386
+ </ty-tabs>
387
+ ```
388
+
389
+ Event detail: `{ activeId, activeIndex, previousId, previousIndex }`.
390
+
391
+ ### ty-wizard
392
+
393
+ ```svelte
394
+ <script>
395
+ let step = $state('info')
396
+ let completed = $state([])
397
+
398
+ function advance(nextId) {
399
+ completed = [...completed, step]
400
+ step = nextId
401
+ }
402
+ </script>
403
+
404
+ <ty-wizard
405
+ height="400px"
406
+ active={step}
407
+ completed={completed.join(',')}
408
+ onty-wizard-step-change={(e) => step = e.detail.activeId}
409
+ >
410
+ <ty-step id="info" label="Info">
411
+ <div class="p-6">
412
+ <ty-input label="Name" required />
413
+ <ty-button flavor="primary" onclick={() => advance('review')}>Next</ty-button>
414
+ </div>
415
+ </ty-step>
416
+ <ty-step id="review" label="Review">
417
+ <div class="p-6">
418
+ <ty-button onclick={() => step = 'info'}>Back</ty-button>
419
+ <ty-button flavor="success" onclick={() => advance('done')}>Finish</ty-button>
420
+ </div>
421
+ </ty-step>
422
+ <ty-step id="done" label="Done">
423
+ <div class="p-6">All done!</div>
424
+ </ty-step>
425
+ </ty-wizard>
426
+ ```
427
+
428
+ Svelte 4: `on:ty-wizard-step-change={handler}`.
429
+
430
+ Event detail: `{ activeId, activeIndex, previousId, previousIndex, direction }`.
431
+
432
+ ---
433
+
434
+ ## Tooltip and popup
435
+
436
+ ### ty-tooltip
437
+
438
+ Nest `<ty-tooltip>` inside the trigger — it positions itself automatically:
439
+
440
+ ```svelte
441
+ <ty-button>
442
+ Save
443
+ <ty-tooltip placement="top">Changes saved to your account</ty-tooltip>
444
+ </ty-button>
445
+
446
+ <ty-icon name="info">
447
+ <ty-tooltip flavor="primary" delay={300}>Required field</ty-tooltip>
448
+ </ty-icon>
449
+ ```
450
+
451
+ Attrs: `placement` (default `top`), `delay` (ms), `flavor` (`dark`|`light`|semantic colors), `disabled`.
452
+
453
+ ### ty-popup
454
+
455
+ Nest `<ty-popup>` inside the trigger — opens on click, closes on outside click or ESC:
456
+
457
+ ```svelte
458
+ <ty-button>
459
+ Options
460
+ <ty-popup placement="bottom-start">
461
+ <div class="ty-elevated p-2 rounded-lg min-w-40">
462
+ <div class="px-3 py-2 hover:ty-bg-neutral- rounded cursor-pointer">Edit</div>
463
+ <div class="px-3 py-2 hover:ty-bg-danger- ty-text-danger rounded cursor-pointer">Delete</div>
464
+ </div>
465
+ </ty-popup>
466
+ </ty-button>
467
+ ```
468
+
469
+ For programmatic control, add `manual` and call `popupEl.openPopup()` / `popupEl.closePopup()` after `bind:this`.
470
+
471
+ ---
472
+
473
+ ## Utilities
474
+
475
+ ### ty-copy
476
+
477
+ ```svelte
478
+ <ty-copy
479
+ label="Install"
480
+ format="code"
481
+ value="npm install tyrell-components"
482
+ />
483
+ ```
484
+
485
+ `format="code"` renders monospace styling. Copy happens internally — no event handling needed.
486
+
487
+ ### ty-scroll-container
488
+
489
+ ```svelte
490
+ <ty-scroll-container max-height="400px">
491
+ {#each items as item (item.id)}
492
+ <div class="p-3 border-b ty-divide-y">{item.name}</div>
493
+ {/each}
494
+ </ty-scroll-container>
495
+ ```
496
+
497
+ Attrs: `max-height`, `no-shadow`, `hide-scrollbar`, `custom-scrollbar`, `overflow-x`.
498
+
499
+ ---
500
+
501
+ ## Reorderable lists (ty-sortable)
502
+
503
+ `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 Svelte renders the items in the new order. Use a keyed `{#each}` and put `data-key` (or `id`) on each item. Svelte 5 binds the hyphenated event as `onty-sortable-change`:
504
+
505
+ ```svelte
506
+ <script>
507
+ let cols = $state({ todo: ['a', 'b'], done: ['c'] })
508
+ let saving = $state(false)
509
+
510
+ async function onMove(e) {
511
+ const { value } = e.detail
512
+ saving = true
513
+ try {
514
+ await save(value)
515
+ cols = { ...cols, ...value.order } // new key order per touched list
516
+ } finally {
517
+ saving = false // order unchanged: the item snaps back
518
+ }
519
+ }
520
+ </script>
521
+
522
+ {#each [['todo', 'To do'], ['done', 'Done']] as [id, label] (id)}
523
+ <ty-sortable {id} group="board" {label} aria-busy={saving ? 'true' : undefined}
524
+ onty-sortable-change={onMove}>
525
+ {#each cols[id] as k (k)}
526
+ <div data-key={k}>
527
+ <button type="button" data-handle aria-label="Move {k}">
528
+ <ty-icon name="grip-vertical" />
529
+ </button>
530
+ {k}
531
+ </div>
532
+ {/each}
533
+ </ty-sortable>
534
+ {/each}
535
+ ```
536
+
537
+ Svelte 4, and Svelte 5 in legacy mode, use `on:ty-sortable-change={onMove}` instead.
538
+
539
+ - `e.detail.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.
540
+ - `aria-busy` while saving makes a refused save snap back as soon as it clears. Without it, call `e.detail.toContainer.settle('rejected')`, or `e.preventDefault()` to reject at once.
541
+ - 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.
542
+ - Attrs: `group`, `axis`, `handle`, `accepts`, `disabled`, `key-attr`, `hold-timeout`, `label`. Item attrs: `data-locked`, `data-no-drag`, `data-sortable-ignore`. `canDrop={fn}` and `labels={{…}}` are set as properties (Svelte sets a custom element's existing properties); `el.move('a', { to: 'done', index: 0 })` moves without a pointer, with `el` from `bind:this`.
543
+
544
+ ---
545
+
546
+ ## TypeScript
547
+
548
+ Add JSX-style type augmentation for Svelte's HTML element map:
549
+
550
+ ```ts
551
+ // src/ty-types.d.ts
552
+ declare namespace svelteHTML {
553
+ interface IntrinsicElements {
554
+ 'ty-button': {
555
+ flavor?: 'primary' | 'success' | 'danger' | 'warning' | 'neutral'
556
+ size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl'
557
+ disabled?: boolean
558
+ pill?: boolean
559
+ action?: boolean
560
+ type?: 'button' | 'submit' | 'reset'
561
+ onclick?: (e: MouseEvent) => void
562
+ children?: any
563
+ }
564
+ 'ty-input': {
565
+ label?: string
566
+ type?: string
567
+ value?: string | number
568
+ placeholder?: string
569
+ error?: string
570
+ disabled?: boolean
571
+ required?: boolean
572
+ onchange?: (e: CustomEvent<{ value: string }>) => void
573
+ }
574
+ // ...add other components as needed
575
+ }
576
+ }
577
+ ```
578
+
579
+ For underlying class types:
580
+
581
+ ```ts
582
+ import type { TyButton } from 'tyrell-components/button'
583
+ let btn: TyButton
584
+ ```
585
+
586
+ ## SvelteKit (SSR)
587
+
588
+ `customElements` is undefined on the server. Three patterns:
589
+
590
+ ### Pattern A — Browser guard in root layout
591
+
592
+ ```svelte
593
+ <!-- src/routes/+layout.svelte -->
594
+ <script>
595
+ import { browser } from '$app/environment'
596
+ import { onMount } from 'svelte'
597
+
598
+ onMount(async () => {
599
+ if (browser) {
600
+ await import('tyrell-components/css/tyrell.css')
601
+ await import('tyrell-components/css/tyrell-theme.css')
602
+ await import('tyrell-components')
603
+ const { registerIcons } = await import('tyrell-components/icons/registry')
604
+ const { check, x } = await import('tyrell-components/icons/lucide')
605
+ registerIcons({ check, x })
606
+ }
607
+ })
608
+ </script>
609
+
610
+ <slot />
611
+ ```
612
+
613
+ ### Pattern B — Client-only module
614
+
615
+ Create `src/lib/tyrell.client.ts`:
616
+
617
+ ```ts
618
+ import 'tyrell-components/css/tyrell.css'
619
+ import 'tyrell-components/css/tyrell-theme.css'
620
+ import 'tyrell-components'
621
+ import { registerIcons } from 'tyrell-components/icons/registry'
622
+ import { check, x } from 'tyrell-components/icons/lucide'
623
+
624
+ registerIcons({ check, x })
625
+ ```
626
+
627
+ Import it from a layout's `onMount`:
628
+
629
+ ```svelte
630
+ <script>
631
+ import { onMount } from 'svelte'
632
+ onMount(() => import('$lib/tyrell.client'))
633
+ </script>
634
+ ```
635
+
636
+ ### Pattern C — Disable SSR for routes using Tyrell
637
+
638
+ If a route can't tolerate the brief unstyled flash:
639
+
640
+ ```js
641
+ // src/routes/+page.js
642
+ export const ssr = false
643
+ ```
644
+
645
+ Most apps want Pattern A or B — graceful upgrade is fine because `<ty-*>` tags render as inert HTML during SSR, then "come alive" when registration runs in the browser.
646
+
647
+ ### `<ty-*>` in SSR HTML
648
+
649
+ The server emits raw `<ty-button>Save</ty-button>` in the HTML response. Browsers ignore unknown tags but still render their text content, so users see the button label as plain text until JavaScript loads. This is usually invisible (sub-100ms on fast connections) but can flash on slow networks. If it matters, add a CSS rule:
650
+
651
+ ```css
652
+ ty-button:not(:defined),
653
+ ty-input:not(:defined),
654
+ ty-select:not(:defined) {
655
+ visibility: hidden;
656
+ }
657
+ ```
658
+
659
+ The `:not(:defined)` selector matches elements whose custom element class hasn't registered yet, hiding them until ready.
660
+
661
+ ## Common pitfalls
662
+
663
+ 1. **Setting array values via attribute** — `value={[1,2,3]}` becomes the string `"1,2,3"`. Use `prop:value={[1,2,3]}`.
664
+ 2. **Reading `e.value` instead of `e.detail.value`** — Tyrell events follow the standard CustomEvent pattern.
665
+ 3. **Importing `tyrell-components` at module top-level in SvelteKit** — `customElements is not defined` during SSR. Move imports inside `onMount` or use `if (browser)`.
666
+ 4. **Forgetting `bind:this` is async** — the binding fires after mount, not synchronously. Call methods inside `onMount` or in event handlers.
667
+ 5. **Svelte 4 `on:click` vs Svelte 5 `onclick`** — Svelte 5 uses standard event handler attributes; Svelte 4 uses the `on:` directive. Either works on custom elements; just match your Svelte version.
668
+
669
+ ## Why no wrapper package?
670
+
671
+ Other frameworks (notably React ≤18) need wrapper packages because they:
672
+ - Pass everything as attributes (broken booleans, complex values),
673
+ - Convert event names to `onCamelCase` (don't match custom event names),
674
+ - Don't support property setting cleanly.
675
+
676
+ Svelte does none of those — it sets attributes for primitives, allows `prop:` for properties, and `on:event` / `onevent` works on any DOM event. Wrappers would only add overhead. Use the components directly.
677
+
678
+ ## See also
679
+
680
+ - [JAVASCRIPT_GUIDE.md](./JAVASCRIPT_GUIDE.md) — distribution, subpaths, icons, SSR
681
+ - [TY_GUIDE.md](../TY_GUIDE.md) — universal API reference
682
+ - [CSS_GUIDE.md](../CSS_GUIDE.md) — design system