tyrell-components 1.0.0-TC8 → 1.0.0-rc.21

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (386) hide show
  1. package/AGENTS.md +122 -0
  2. package/CHANGELOG.md +1531 -0
  3. package/README.md +71 -53
  4. package/css/tyrell-colors-static.css +1 -0
  5. package/css/tyrell-theme.css +1 -0
  6. package/css/tyrell.css +1 -1783
  7. package/dist/tyrell-colors-static.css +1 -0
  8. package/dist/tyrell-theme.css +1 -0
  9. package/dist/tyrell.css +1 -1783
  10. package/dist/tyrell.js +1 -1
  11. package/guides/AGENT_INSTRUCTIONS.md +124 -0
  12. package/guides/AI_GUIDE.md +53 -0
  13. package/guides/CSS_GUIDE.md +1016 -0
  14. package/guides/DATASTAR_TY_GUIDE.md +657 -0
  15. package/guides/ICONS_GUIDE.md +212 -0
  16. package/guides/TY_GUIDE.md +935 -0
  17. package/guides/clj/CLOJURESCRIPT_GUIDE.md +300 -0
  18. package/guides/clj/CODE_SPLITTING.md +279 -0
  19. package/guides/clj/COMPONENT_GUIDE.md +391 -0
  20. package/guides/clj/HELIX_TY_GUIDE.md +428 -0
  21. package/guides/clj/I18N_GUIDE.md +478 -0
  22. package/guides/clj/LAYOUT_GUIDE.md +273 -0
  23. package/guides/clj/QUICKSTART.md +266 -0
  24. package/guides/clj/REAGENT_TY_GUIDE.md +408 -0
  25. package/guides/clj/REPLICANT_TY_GUIDE.md +623 -0
  26. package/guides/clj/ROUTING_GUIDE.md +346 -0
  27. package/guides/clj/UIX_TY_GUIDE.md +319 -0
  28. package/guides/js/HTMX_TY_GUIDE.md +252 -0
  29. package/guides/js/JAVASCRIPT_GUIDE.md +388 -0
  30. package/guides/js/REACT_TY_GUIDE.md +983 -0
  31. package/guides/js/SVELTE_TY_GUIDE.md +682 -0
  32. package/guides/js/TYCOMPONENT_GUIDE.md +962 -0
  33. package/guides/js/VUE_TY_GUIDE.md +738 -0
  34. package/lib/base/ty-component.d.ts +57 -13
  35. package/lib/base/ty-component.js +266 -292
  36. package/lib/components/button.d.ts +42 -18
  37. package/lib/components/button.js +318 -235
  38. package/lib/components/calendar-month.d.ts +30 -47
  39. package/lib/components/calendar-month.js +455 -429
  40. package/lib/components/calendar-navigation.d.ts +41 -49
  41. package/lib/components/calendar-navigation.js +287 -346
  42. package/lib/components/calendar.d.ts +73 -83
  43. package/lib/components/calendar.js +837 -762
  44. package/lib/components/checkbox.d.ts +26 -75
  45. package/lib/components/checkbox.js +298 -391
  46. package/lib/components/copy.d.ts +20 -60
  47. package/lib/components/copy.js +276 -380
  48. package/lib/components/date-picker.d.ts +100 -183
  49. package/lib/components/date-picker.js +1155 -1570
  50. package/lib/components/file-upload.d.ts +122 -0
  51. package/lib/components/file-upload.js +451 -0
  52. package/lib/components/icon.d.ts +3 -24
  53. package/lib/components/icon.js +141 -230
  54. package/lib/components/input.d.ts +93 -108
  55. package/lib/components/input.js +734 -710
  56. package/lib/components/modal.d.ts +39 -29
  57. package/lib/components/modal.js +419 -438
  58. package/lib/components/option.d.ts +20 -35
  59. package/lib/components/option.js +184 -309
  60. package/lib/components/popup.d.ts +2 -17
  61. package/lib/components/popup.js +353 -347
  62. package/lib/components/radio.d.ts +33 -25
  63. package/lib/components/radio.js +433 -422
  64. package/lib/components/resize-observer.d.ts +3 -30
  65. package/lib/components/resize-observer.js +71 -103
  66. package/lib/components/scroll-container.d.ts +21 -14
  67. package/lib/components/scroll-container.js +292 -234
  68. package/lib/components/select.d.ts +446 -0
  69. package/lib/components/select.js +1381 -0
  70. package/lib/components/selected-tags.d.ts +60 -0
  71. package/lib/components/selected-tags.js +225 -0
  72. package/lib/components/sortable.d.ts +175 -0
  73. package/lib/components/sortable.js +1844 -0
  74. package/lib/components/step.d.ts +1 -6
  75. package/lib/components/step.js +62 -68
  76. package/lib/components/switch.d.ts +15 -15
  77. package/lib/components/switch.js +237 -231
  78. package/lib/components/tab.d.ts +50 -7
  79. package/lib/components/tab.js +203 -69
  80. package/lib/components/tabs.d.ts +19 -64
  81. package/lib/components/tabs.js +600 -618
  82. package/lib/components/tag.d.ts +17 -55
  83. package/lib/components/tag.js +235 -308
  84. package/lib/components/textarea.d.ts +58 -89
  85. package/lib/components/textarea.js +523 -573
  86. package/lib/components/tooltip.d.ts +8 -13
  87. package/lib/components/tooltip.js +322 -409
  88. package/lib/components/wizard.d.ts +7 -54
  89. package/lib/components/wizard.js +376 -606
  90. package/lib/icons/fontawesome/brands.d.ts +0 -1
  91. package/lib/icons/fontawesome/brands.js +0 -8
  92. package/lib/icons/fontawesome/regular.d.ts +0 -1
  93. package/lib/icons/fontawesome/regular.js +0 -8
  94. package/lib/icons/fontawesome/solid.d.ts +0 -1
  95. package/lib/icons/fontawesome/solid.js +0 -8
  96. package/lib/icons/heroicons/micro.d.ts +0 -1
  97. package/lib/icons/heroicons/micro.js +392 -400
  98. package/lib/icons/heroicons/mini.d.ts +0 -1
  99. package/lib/icons/heroicons/mini.js +382 -390
  100. package/lib/icons/heroicons/outline.d.ts +0 -1
  101. package/lib/icons/heroicons/outline.js +337 -345
  102. package/lib/icons/heroicons/solid.d.ts +0 -1
  103. package/lib/icons/heroicons/solid.js +407 -415
  104. package/lib/icons/lucide.d.ts +0 -1
  105. package/lib/icons/lucide.js +24479 -26351
  106. package/lib/icons/material/filled.d.ts +0 -1
  107. package/lib/icons/material/filled.js +9653 -9663
  108. package/lib/icons/material/outlined.d.ts +0 -1
  109. package/lib/icons/material/outlined.js +10271 -10281
  110. package/lib/icons/material/round.d.ts +0 -1
  111. package/lib/icons/material/round.js +10495 -10505
  112. package/lib/icons/material/sharp.d.ts +0 -1
  113. package/lib/icons/material/sharp.js +9905 -9915
  114. package/lib/icons/material/two-tone.d.ts +0 -1
  115. package/lib/icons/material/two-tone.js +12792 -12802
  116. package/lib/index.d.ts +15 -4
  117. package/lib/index.js +28 -38
  118. package/lib/styles/button.d.ts +24 -7
  119. package/lib/styles/button.js +298 -417
  120. package/lib/styles/calendar-month.d.ts +7 -6
  121. package/lib/styles/calendar-month.js +157 -179
  122. package/lib/styles/calendar-navigation.d.ts +2 -6
  123. package/lib/styles/calendar-navigation.js +108 -109
  124. package/lib/styles/calendar.d.ts +3 -3
  125. package/lib/styles/calendar.js +87 -23
  126. package/lib/styles/checkbox.d.ts +7 -6
  127. package/lib/styles/checkbox.js +101 -15
  128. package/lib/styles/copy.d.ts +3 -2
  129. package/lib/styles/copy.js +91 -71
  130. package/lib/styles/custom-scrollbar.d.ts +1 -2
  131. package/lib/styles/custom-scrollbar.js +80 -115
  132. package/lib/styles/date-picker.d.ts +4 -6
  133. package/lib/styles/date-picker.js +320 -352
  134. package/lib/styles/field-size.d.ts +6 -0
  135. package/lib/styles/field-size.js +91 -0
  136. package/lib/styles/file-upload.d.ts +1 -0
  137. package/lib/styles/file-upload.js +196 -0
  138. package/lib/styles/icon.d.ts +2 -6
  139. package/lib/styles/icon.js +92 -170
  140. package/lib/styles/input.d.ts +4 -7
  141. package/lib/styles/input.js +148 -643
  142. package/lib/styles/modal.d.ts +1 -2
  143. package/lib/styles/modal.js +127 -108
  144. package/lib/styles/option.d.ts +2 -6
  145. package/lib/styles/option.js +53 -96
  146. package/lib/styles/popup.d.ts +1 -2
  147. package/lib/styles/popup.js +47 -77
  148. package/lib/styles/radio.d.ts +3 -2
  149. package/lib/styles/radio.js +90 -116
  150. package/lib/styles/resize-observer.d.ts +1 -2
  151. package/lib/styles/resize-observer.js +2 -12
  152. package/lib/styles/scroll-container.d.ts +1 -2
  153. package/lib/styles/scroll-container.js +103 -146
  154. package/lib/styles/select-base.d.ts +8 -0
  155. package/lib/styles/select-base.js +747 -0
  156. package/lib/styles/select.d.ts +11 -0
  157. package/lib/styles/select.js +229 -0
  158. package/lib/styles/sortable.d.ts +16 -0
  159. package/lib/styles/sortable.js +85 -0
  160. package/lib/styles/step.d.ts +1 -2
  161. package/lib/styles/step.js +15 -34
  162. package/lib/styles/switch.d.ts +3 -2
  163. package/lib/styles/switch.js +52 -68
  164. package/lib/styles/tab.d.ts +1 -2
  165. package/lib/styles/tab.js +86 -34
  166. package/lib/styles/tabs.d.ts +3 -11
  167. package/lib/styles/tabs.js +204 -162
  168. package/lib/styles/tag.d.ts +2 -6
  169. package/lib/styles/tag.js +170 -359
  170. package/lib/styles/textarea.d.ts +1 -2
  171. package/lib/styles/textarea.js +238 -306
  172. package/lib/styles/tooltip.d.ts +4 -3
  173. package/lib/styles/tooltip.js +3 -131
  174. package/lib/styles/wizard.d.ts +8 -20
  175. package/lib/styles/wizard.js +306 -295
  176. package/lib/types/common.d.ts +9 -8
  177. package/lib/types/common.js +8 -5
  178. package/lib/utils/calendar-utils.d.ts +49 -65
  179. package/lib/utils/calendar-utils.js +158 -343
  180. package/lib/utils/custom-scrollbar.d.ts +6 -20
  181. package/lib/utils/custom-scrollbar.js +273 -317
  182. package/lib/utils/flavor-sheet.d.ts +31 -0
  183. package/lib/utils/flavor-sheet.js +17 -0
  184. package/lib/utils/icon-registry.d.ts +0 -15
  185. package/lib/utils/icon-registry.js +138 -279
  186. package/lib/utils/icons.d.ts +9 -0
  187. package/lib/utils/icons.js +1 -0
  188. package/lib/utils/loader-registry.d.ts +34 -0
  189. package/lib/utils/loader-registry.js +11 -0
  190. package/lib/utils/locale.d.ts +2 -80
  191. package/lib/utils/locale.js +30 -205
  192. package/lib/utils/mobile.d.ts +0 -1
  193. package/lib/utils/mobile.js +1 -18
  194. package/lib/utils/number-format.d.ts +6 -24
  195. package/lib/utils/number-format.js +53 -136
  196. package/lib/utils/positioning.d.ts +72 -22
  197. package/lib/utils/positioning.js +224 -298
  198. package/lib/utils/property-capture.d.ts +5 -27
  199. package/lib/utils/property-capture.js +36 -144
  200. package/lib/utils/property-manager.d.ts +6 -6
  201. package/lib/utils/property-manager.js +127 -196
  202. package/lib/utils/resize-observer.d.ts +0 -1
  203. package/lib/utils/resize-observer.js +23 -59
  204. package/lib/utils/scroll-lock.d.ts +10 -11
  205. package/lib/utils/scroll-lock.js +165 -173
  206. package/lib/utils/styles.d.ts +0 -6
  207. package/lib/utils/styles.js +17 -48
  208. package/lib/utils/upgrade-properties.d.ts +21 -0
  209. package/lib/utils/upgrade-properties.js +47 -0
  210. package/lib/utils/validity.d.ts +122 -0
  211. package/lib/utils/validity.js +289 -0
  212. package/lib/version.d.ts +1 -2
  213. package/lib/version.js +1 -11
  214. package/package.json +66 -18
  215. package/lib/base/ty-component.d.ts.map +0 -1
  216. package/lib/base/ty-component.js.map +0 -1
  217. package/lib/components/button.d.ts.map +0 -1
  218. package/lib/components/button.js.map +0 -1
  219. package/lib/components/calendar-month.d.ts.map +0 -1
  220. package/lib/components/calendar-month.js.map +0 -1
  221. package/lib/components/calendar-navigation.d.ts.map +0 -1
  222. package/lib/components/calendar-navigation.js.map +0 -1
  223. package/lib/components/calendar.d.ts.map +0 -1
  224. package/lib/components/calendar.js.map +0 -1
  225. package/lib/components/checkbox.d.ts.map +0 -1
  226. package/lib/components/checkbox.js.map +0 -1
  227. package/lib/components/copy.d.ts.map +0 -1
  228. package/lib/components/copy.js.map +0 -1
  229. package/lib/components/date-picker.d.ts.map +0 -1
  230. package/lib/components/date-picker.js.map +0 -1
  231. package/lib/components/dropdown.d.ts +0 -402
  232. package/lib/components/dropdown.d.ts.map +0 -1
  233. package/lib/components/dropdown.js +0 -1564
  234. package/lib/components/dropdown.js.map +0 -1
  235. package/lib/components/icon.d.ts.map +0 -1
  236. package/lib/components/icon.js.map +0 -1
  237. package/lib/components/input.d.ts.map +0 -1
  238. package/lib/components/input.js.map +0 -1
  239. package/lib/components/modal.d.ts.map +0 -1
  240. package/lib/components/modal.js.map +0 -1
  241. package/lib/components/multiselect.d.ts +0 -397
  242. package/lib/components/multiselect.d.ts.map +0 -1
  243. package/lib/components/multiselect.js +0 -1580
  244. package/lib/components/multiselect.js.map +0 -1
  245. package/lib/components/option.d.ts.map +0 -1
  246. package/lib/components/option.js.map +0 -1
  247. package/lib/components/popup.d.ts.map +0 -1
  248. package/lib/components/popup.js.map +0 -1
  249. package/lib/components/radio.d.ts.map +0 -1
  250. package/lib/components/radio.js.map +0 -1
  251. package/lib/components/resize-observer.d.ts.map +0 -1
  252. package/lib/components/resize-observer.js.map +0 -1
  253. package/lib/components/scroll-container.d.ts.map +0 -1
  254. package/lib/components/scroll-container.js.map +0 -1
  255. package/lib/components/step.d.ts.map +0 -1
  256. package/lib/components/step.js.map +0 -1
  257. package/lib/components/switch.d.ts.map +0 -1
  258. package/lib/components/switch.js.map +0 -1
  259. package/lib/components/tab.d.ts.map +0 -1
  260. package/lib/components/tab.js.map +0 -1
  261. package/lib/components/tabs.d.ts.map +0 -1
  262. package/lib/components/tabs.js.map +0 -1
  263. package/lib/components/tag.d.ts.map +0 -1
  264. package/lib/components/tag.js.map +0 -1
  265. package/lib/components/textarea.d.ts.map +0 -1
  266. package/lib/components/textarea.js.map +0 -1
  267. package/lib/components/tooltip.d.ts.map +0 -1
  268. package/lib/components/tooltip.js.map +0 -1
  269. package/lib/components/wizard.d.ts.map +0 -1
  270. package/lib/components/wizard.js.map +0 -1
  271. package/lib/icons/fontawesome/brands.d.ts.map +0 -1
  272. package/lib/icons/fontawesome/brands.js.map +0 -1
  273. package/lib/icons/fontawesome/regular.d.ts.map +0 -1
  274. package/lib/icons/fontawesome/regular.js.map +0 -1
  275. package/lib/icons/fontawesome/solid.d.ts.map +0 -1
  276. package/lib/icons/fontawesome/solid.js.map +0 -1
  277. package/lib/icons/heroicons/micro.d.ts.map +0 -1
  278. package/lib/icons/heroicons/micro.js.map +0 -1
  279. package/lib/icons/heroicons/mini.d.ts.map +0 -1
  280. package/lib/icons/heroicons/mini.js.map +0 -1
  281. package/lib/icons/heroicons/outline.d.ts.map +0 -1
  282. package/lib/icons/heroicons/outline.js.map +0 -1
  283. package/lib/icons/heroicons/solid.d.ts.map +0 -1
  284. package/lib/icons/heroicons/solid.js.map +0 -1
  285. package/lib/icons/lucide.d.ts.map +0 -1
  286. package/lib/icons/lucide.js.map +0 -1
  287. package/lib/icons/material/filled.d.ts.map +0 -1
  288. package/lib/icons/material/filled.js.map +0 -1
  289. package/lib/icons/material/outlined.d.ts.map +0 -1
  290. package/lib/icons/material/outlined.js.map +0 -1
  291. package/lib/icons/material/round.d.ts.map +0 -1
  292. package/lib/icons/material/round.js.map +0 -1
  293. package/lib/icons/material/sharp.d.ts.map +0 -1
  294. package/lib/icons/material/sharp.js.map +0 -1
  295. package/lib/icons/material/two-tone.d.ts.map +0 -1
  296. package/lib/icons/material/two-tone.js.map +0 -1
  297. package/lib/index.d.ts.map +0 -1
  298. package/lib/index.js.map +0 -1
  299. package/lib/styles/button.d.ts.map +0 -1
  300. package/lib/styles/button.js.map +0 -1
  301. package/lib/styles/calendar-month.d.ts.map +0 -1
  302. package/lib/styles/calendar-month.js.map +0 -1
  303. package/lib/styles/calendar-navigation.d.ts.map +0 -1
  304. package/lib/styles/calendar-navigation.js.map +0 -1
  305. package/lib/styles/calendar.d.ts.map +0 -1
  306. package/lib/styles/calendar.js.map +0 -1
  307. package/lib/styles/checkbox.d.ts.map +0 -1
  308. package/lib/styles/checkbox.js.map +0 -1
  309. package/lib/styles/copy.d.ts.map +0 -1
  310. package/lib/styles/copy.js.map +0 -1
  311. package/lib/styles/custom-scrollbar.d.ts.map +0 -1
  312. package/lib/styles/custom-scrollbar.js.map +0 -1
  313. package/lib/styles/date-picker.d.ts.map +0 -1
  314. package/lib/styles/date-picker.js.map +0 -1
  315. package/lib/styles/dropdown.d.ts +0 -12
  316. package/lib/styles/dropdown.d.ts.map +0 -1
  317. package/lib/styles/dropdown.js +0 -983
  318. package/lib/styles/dropdown.js.map +0 -1
  319. package/lib/styles/icon.d.ts.map +0 -1
  320. package/lib/styles/icon.js.map +0 -1
  321. package/lib/styles/input.d.ts.map +0 -1
  322. package/lib/styles/input.js.map +0 -1
  323. package/lib/styles/modal.d.ts.map +0 -1
  324. package/lib/styles/modal.js.map +0 -1
  325. package/lib/styles/multiselect.d.ts +0 -6
  326. package/lib/styles/multiselect.d.ts.map +0 -1
  327. package/lib/styles/multiselect.js +0 -774
  328. package/lib/styles/multiselect.js.map +0 -1
  329. package/lib/styles/option.d.ts.map +0 -1
  330. package/lib/styles/option.js.map +0 -1
  331. package/lib/styles/popup.d.ts.map +0 -1
  332. package/lib/styles/popup.js.map +0 -1
  333. package/lib/styles/radio.d.ts.map +0 -1
  334. package/lib/styles/radio.js.map +0 -1
  335. package/lib/styles/resize-observer.d.ts.map +0 -1
  336. package/lib/styles/resize-observer.js.map +0 -1
  337. package/lib/styles/scroll-container.d.ts.map +0 -1
  338. package/lib/styles/scroll-container.js.map +0 -1
  339. package/lib/styles/step.d.ts.map +0 -1
  340. package/lib/styles/step.js.map +0 -1
  341. package/lib/styles/switch.d.ts.map +0 -1
  342. package/lib/styles/switch.js.map +0 -1
  343. package/lib/styles/tab.d.ts.map +0 -1
  344. package/lib/styles/tab.js.map +0 -1
  345. package/lib/styles/tabs.d.ts.map +0 -1
  346. package/lib/styles/tabs.js.map +0 -1
  347. package/lib/styles/tag.d.ts.map +0 -1
  348. package/lib/styles/tag.js.map +0 -1
  349. package/lib/styles/textarea.d.ts.map +0 -1
  350. package/lib/styles/textarea.js.map +0 -1
  351. package/lib/styles/tooltip.d.ts.map +0 -1
  352. package/lib/styles/tooltip.js.map +0 -1
  353. package/lib/styles/wizard.d.ts.map +0 -1
  354. package/lib/styles/wizard.js.map +0 -1
  355. package/lib/types/common.d.ts.map +0 -1
  356. package/lib/types/common.js.map +0 -1
  357. package/lib/utils/calendar-utils.d.ts.map +0 -1
  358. package/lib/utils/calendar-utils.js.map +0 -1
  359. package/lib/utils/custom-scrollbar.d.ts.map +0 -1
  360. package/lib/utils/custom-scrollbar.js.map +0 -1
  361. package/lib/utils/icon-registry.d.ts.map +0 -1
  362. package/lib/utils/icon-registry.js.map +0 -1
  363. package/lib/utils/locale.d.ts.map +0 -1
  364. package/lib/utils/locale.js.map +0 -1
  365. package/lib/utils/mobile.d.ts.map +0 -1
  366. package/lib/utils/mobile.js.map +0 -1
  367. package/lib/utils/number-format.d.ts.map +0 -1
  368. package/lib/utils/number-format.js.map +0 -1
  369. package/lib/utils/parse-boolean.d.ts +0 -39
  370. package/lib/utils/parse-boolean.d.ts.map +0 -1
  371. package/lib/utils/parse-boolean.js +0 -58
  372. package/lib/utils/parse-boolean.js.map +0 -1
  373. package/lib/utils/positioning.d.ts.map +0 -1
  374. package/lib/utils/positioning.js.map +0 -1
  375. package/lib/utils/property-capture.d.ts.map +0 -1
  376. package/lib/utils/property-capture.js.map +0 -1
  377. package/lib/utils/property-manager.d.ts.map +0 -1
  378. package/lib/utils/property-manager.js.map +0 -1
  379. package/lib/utils/resize-observer.d.ts.map +0 -1
  380. package/lib/utils/resize-observer.js.map +0 -1
  381. package/lib/utils/scroll-lock.d.ts.map +0 -1
  382. package/lib/utils/scroll-lock.js.map +0 -1
  383. package/lib/utils/styles.d.ts.map +0 -1
  384. package/lib/utils/styles.js.map +0 -1
  385. package/lib/version.d.ts.map +0 -1
  386. package/lib/version.js.map +0 -1
@@ -0,0 +1,738 @@
1
+ # Vue + Tyrell Guide
2
+
3
+ Use Tyrell web components in Vue 3 natively — no wrapper package needed. Vue 3 has first-class custom element support; one config line and `v-bind` / `v-model` / `@event` work as expected.
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. Tell Vue's compiler that `ty-*` are custom elements
16
+
17
+ Without this, Vue tries to resolve `<ty-button>` as a Vue component and warns about unknown components.
18
+
19
+ #### Vite
20
+
21
+ ```js
22
+ // vite.config.js
23
+ import { defineConfig } from 'vite'
24
+ import vue from '@vitejs/plugin-vue'
25
+
26
+ export default defineConfig({
27
+ plugins: [
28
+ vue({
29
+ template: {
30
+ compilerOptions: {
31
+ isCustomElement: (tag) => tag.startsWith('ty-'),
32
+ },
33
+ },
34
+ }),
35
+ ],
36
+ })
37
+ ```
38
+
39
+ #### Vue CLI / webpack
40
+
41
+ ```js
42
+ // vue.config.js
43
+ module.exports = {
44
+ chainWebpack: (config) => {
45
+ config.module
46
+ .rule('vue')
47
+ .use('vue-loader')
48
+ .tap((options) => ({
49
+ ...options,
50
+ compilerOptions: {
51
+ isCustomElement: (tag) => tag.startsWith('ty-'),
52
+ },
53
+ }))
54
+ },
55
+ }
56
+ ```
57
+
58
+ ### 3. Register components and CSS
59
+
60
+ In your app entry (`src/main.js` or `src/main.ts`):
61
+
62
+ ```js
63
+ import { createApp } from 'vue'
64
+ import App from './App.vue'
65
+
66
+ import 'tyrell-components/css/tyrell.css'
67
+ import 'tyrell-components/css/tyrell-theme.css' // auto-contrast, seed rebranding, themes — see TY_GUIDE.md#quick-start
68
+ import 'tyrell-components' // or specific subpaths: 'tyrell-components/button', etc.
69
+
70
+ createApp(App).mount('#app')
71
+ ```
72
+
73
+ ## Native usage
74
+
75
+ ```vue
76
+ <script setup>
77
+ import { ref } from 'vue'
78
+ const email = ref('')
79
+ const submit = () => console.log('submit:', email.value)
80
+ </script>
81
+
82
+ <template>
83
+ <ty-input
84
+ label="Email"
85
+ type="email"
86
+ :value="email"
87
+ @change="email = $event.detail.value"
88
+ />
89
+ <ty-button flavor="primary" @click="submit">Submit</ty-button>
90
+ </template>
91
+ ```
92
+
93
+ Three Vue idioms to remember:
94
+
95
+ 1. **`:prop` binds the JS property**, `prop=""` sets an HTML attribute. Always prefer `:` for booleans, arrays, objects, and computed values.
96
+ 2. **`@event="..."`** registers a `addEventListener` — works for any custom event including `change`, `input`, `popup-close`, `tag-dismiss`, etc.
97
+ 3. **Event payload** lives on `$event.detail`, not `$event`.
98
+
99
+ ## v-model
100
+
101
+ Vue's `v-model` does not work out of the box on web components — Vue's default `v-model` expects `value` + `@input` (for native inputs). Tyrell inputs emit `change` events with `event.detail.value`.
102
+
103
+ Use the `:value` + `@change` pattern explicitly, or build a small `v-model` wrapper:
104
+
105
+ ### Pattern 1 — Explicit binding (simple, readable)
106
+
107
+ ```vue
108
+ <ty-input
109
+ :value="email"
110
+ @change="email = $event.detail.value"
111
+ label="Email"
112
+ />
113
+ ```
114
+
115
+ ### Pattern 2 — Custom `v-model` modifier
116
+
117
+ ```vue
118
+ <ty-input
119
+ v-model:value.detail="email"
120
+ label="Email"
121
+ />
122
+ ```
123
+
124
+ This requires a directive that reads `event.detail.value`. Or define your own once:
125
+
126
+ ```js
127
+ // directives/v-ty-model.js
128
+ export const vTyModel = {
129
+ mounted(el, binding) {
130
+ el.value = binding.value
131
+ el._handler = (e) => binding.instance[binding.arg] = e.detail.value
132
+ el.addEventListener('change', el._handler)
133
+ },
134
+ updated(el, binding) {
135
+ if (el.value !== binding.value) el.value = binding.value
136
+ },
137
+ unmounted(el) {
138
+ el.removeEventListener('change', el._handler)
139
+ },
140
+ }
141
+ ```
142
+
143
+ ```vue
144
+ <script setup>
145
+ import { vTyModel } from './directives/v-ty-model.js'
146
+ const email = ref('')
147
+ </script>
148
+
149
+ <template>
150
+ <ty-input v-ty-model="email" label="Email" />
151
+ </template>
152
+ ```
153
+
154
+ For most apps, Pattern 1 is fine and explicit.
155
+
156
+ ## Composition with child elements
157
+
158
+ `ty-select` / `ty-tabs` use slotted children. Vue renders them naturally — reactive lists work as expected.
159
+
160
+ ```vue
161
+ <script setup>
162
+ import { ref } from 'vue'
163
+
164
+ const country = ref('us')
165
+ const countries = [
166
+ { code: 'us', name: 'United States' },
167
+ { code: 'uk', name: 'United Kingdom' },
168
+ { code: 'fr', name: 'France' },
169
+ ]
170
+ </script>
171
+
172
+ <template>
173
+ <ty-select
174
+ label="Country"
175
+ :value="country"
176
+ @change="country = $event.detail.value"
177
+ >
178
+ <ty-option
179
+ v-for="c in countries"
180
+ :key="c.code"
181
+ :value="c.code"
182
+ >
183
+ {{ c.name }}
184
+ </ty-option>
185
+ </ty-select>
186
+ </template>
187
+ ```
188
+
189
+ For multi-select add `multiple` — children stay `ty-option`, and
190
+ `$event.detail.values` is the selected array. Pair with `<ty-selected-options>`
191
+ for dismissible chips anywhere in the layout:
192
+
193
+ ```vue
194
+ <ty-select
195
+ multiple
196
+ id="tags"
197
+ :value="selected"
198
+ @change="selected = $event.detail.values"
199
+ >
200
+ <ty-option v-for="t in tags" :key="t" :value="t">{{ t }}</ty-option>
201
+ </ty-select>
202
+ <ty-selected-options for="tags"></ty-selected-options>
203
+ ```
204
+
205
+ ## Icons
206
+
207
+ Register in `src/main.js`, next to the component import:
208
+
209
+ ```js
210
+ import { registerIcons } from 'tyrell-components/icons/registry'
211
+ import { check, chevronDown } from 'tyrell-components/icons/lucide'
212
+
213
+ registerIcons({ check, 'action-down': chevronDown }) // the key is the name
214
+ ```
215
+
216
+ ```vue
217
+ <ty-icon name="check" size="md" />
218
+ ```
219
+
220
+ Sets, tree-shaking, custom SVGs and troubleshooting: [ICONS_GUIDE.md](../ICONS_GUIDE.md#in-javascript).
221
+
222
+ ## Refs and imperative API
223
+
224
+ Vue's `ref` gives you the underlying element:
225
+
226
+ ```vue
227
+ <script setup>
228
+ import { ref, onMounted } from 'vue'
229
+
230
+ const modalRef = ref(null)
231
+ const showModal = () => modalRef.value.show()
232
+ const closeModal = () => modalRef.value.close()
233
+ </script>
234
+
235
+ <template>
236
+ <ty-button @click="showModal">Open</ty-button>
237
+ <ty-modal ref="modalRef">
238
+ <h2 class="ty-text++">Confirm</h2>
239
+ <p class="ty-text">Are you sure?</p>
240
+ <ty-button flavor="primary" @click="closeModal">OK</ty-button>
241
+ </ty-modal>
242
+ </template>
243
+ ```
244
+
245
+ If you need to call methods immediately on mount, await registration:
246
+
247
+ ```vue
248
+ <script setup>
249
+ import { onMounted } from 'vue'
250
+
251
+ onMounted(async () => {
252
+ await customElements.whenDefined('ty-modal')
253
+ // safe to call modalRef.value.show() now
254
+ })
255
+ </script>
256
+ ```
257
+
258
+ ## Form controls
259
+
260
+ ### ty-textarea
261
+
262
+ ```vue
263
+ <script setup>
264
+ import { ref } from 'vue'
265
+ const bio = ref('')
266
+ </script>
267
+
268
+ <template>
269
+ <ty-textarea
270
+ label="Bio"
271
+ placeholder="Tell us about yourself..."
272
+ rows="4"
273
+ max-height="200px"
274
+ :value="bio"
275
+ @change="bio = $event.detail.value"
276
+ />
277
+ </template>
278
+ ```
279
+
280
+ Attrs: `rows`, `min-height`, `max-height`, `resize` (`none`|`both`|`horizontal`|`vertical`).
281
+
282
+ ### ty-checkbox and ty-switch
283
+
284
+ Both are "just the control" primitives — wrap in `<label>` to make the text clickable:
285
+
286
+ ```vue
287
+ <script setup>
288
+ import { ref } from 'vue'
289
+ const agreed = ref(false)
290
+ const darkMode = ref(false)
291
+ </script>
292
+
293
+ <template>
294
+ <label class="flex items-center gap-2">
295
+ <ty-checkbox
296
+ :checked="agreed"
297
+ @change="agreed = $event.detail.checked"
298
+ />
299
+ I agree to the terms
300
+ </label>
301
+
302
+ <label class="flex items-center gap-2">
303
+ <ty-switch
304
+ :checked="darkMode"
305
+ @change="darkMode = $event.detail.checked"
306
+ />
307
+ Dark mode
308
+ </label>
309
+ </template>
310
+ ```
311
+
312
+ Event detail: `{ value, checked, formValue, originalEvent }`.
313
+
314
+ ### ty-radio-group / ty-radio
315
+
316
+ ```vue
317
+ <script setup>
318
+ import { ref } from 'vue'
319
+ const plan = ref('starter')
320
+ const plans = [
321
+ { value: 'starter', label: 'Starter' },
322
+ { value: 'pro', label: 'Pro' },
323
+ { value: 'enterprise', label: 'Enterprise' },
324
+ ]
325
+ </script>
326
+
327
+ <template>
328
+ <ty-radio-group
329
+ label="Plan"
330
+ :value="plan"
331
+ @change="plan = $event.detail.value"
332
+ >
333
+ <label
334
+ v-for="p in plans"
335
+ :key="p.value"
336
+ class="flex items-center gap-2"
337
+ >
338
+ <ty-radio :value="p.value" />
339
+ {{ p.label }}
340
+ </label>
341
+ </ty-radio-group>
342
+ </template>
343
+ ```
344
+
345
+ Add `orientation="horizontal"` to `ty-radio-group` for a side-by-side layout.
346
+
347
+ ### ty-file-upload
348
+
349
+ ```vue
350
+ <script setup>
351
+ import { ref } from 'vue'
352
+ const files = ref([])
353
+ </script>
354
+
355
+ <template>
356
+ <ty-file-upload
357
+ label="Attachments"
358
+ accept="image/*,.pdf"
359
+ multiple
360
+ @change="files = $event.detail.files"
361
+ />
362
+ <p v-if="files.length">{{ files.length }} file(s) selected</p>
363
+ </template>
364
+ ```
365
+
366
+ Event detail: `{ value: File[], files: File[], names: string[] }`. Files appear in `FormData` under the `name` attribute automatically on form submit.
367
+
368
+ ---
369
+
370
+ ## Date picker and calendar
371
+
372
+ ### ty-date-picker
373
+
374
+ ```vue
375
+ <script setup>
376
+ import { ref } from 'vue'
377
+ const date = ref(null)
378
+ </script>
379
+
380
+ <template>
381
+ <ty-date-picker
382
+ label="Start Date"
383
+ placeholder="Select a date..."
384
+ :value="date"
385
+ @change="date = $event.detail.value"
386
+ />
387
+ </template>
388
+ ```
389
+
390
+ 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.
391
+
392
+ ### ty-calendar (standalone)
393
+
394
+ For inline date pickers or custom date UIs:
395
+
396
+ ```vue
397
+ <script setup>
398
+ import { ref } from 'vue'
399
+ const now = new Date()
400
+ const year = ref(now.getFullYear())
401
+ const month = ref(now.getMonth() + 1)
402
+ const day = ref(null)
403
+
404
+ function onDaySelect(e) {
405
+ year.value = e.detail.year
406
+ month.value = e.detail.month
407
+ day.value = e.detail.day
408
+ }
409
+ </script>
410
+
411
+ <template>
412
+ <ty-calendar
413
+ :year="year"
414
+ :month="month"
415
+ :day="day"
416
+ @change="onDaySelect"
417
+ />
418
+ </template>
419
+ ```
420
+
421
+ Event detail: `{ year, month, day, action, source }`. Form value is ISO `YYYY-MM-DD`.
422
+
423
+ ---
424
+
425
+ ## Tabs and wizard
426
+
427
+ ### ty-tabs
428
+
429
+ ```vue
430
+ <script setup>
431
+ import { ref } from 'vue'
432
+ const activeTab = ref('overview')
433
+ </script>
434
+
435
+ <template>
436
+ <ty-tabs
437
+ height="300px"
438
+ :active="activeTab"
439
+ @ty-tab-change="activeTab = $event.detail.activeId"
440
+ >
441
+ <ty-tab id="overview" label="Overview">
442
+ <div class="p-4">Overview content</div>
443
+ </ty-tab>
444
+ <ty-tab id="details" label="Details">
445
+ <div class="p-4">Details content</div>
446
+ </ty-tab>
447
+ </ty-tabs>
448
+ </template>
449
+ ```
450
+
451
+ Rich tab labels via named slots on `ty-tabs`:
452
+
453
+ ```vue
454
+ <template>
455
+ <ty-tabs height="300px" active="overview">
456
+ <span slot="label-overview" class="flex items-center gap-2">
457
+ <ty-icon name="layout-dashboard" size="sm" />
458
+ Overview
459
+ </span>
460
+ <ty-tab id="overview" label="Overview">…</ty-tab>
461
+ </ty-tabs>
462
+ </template>
463
+ ```
464
+
465
+ Event detail: `{ activeId, activeIndex, previousId, previousIndex }`.
466
+
467
+ ### ty-wizard
468
+
469
+ ```vue
470
+ <script setup>
471
+ import { ref } from 'vue'
472
+ const step = ref('info')
473
+ const completed = ref([])
474
+
475
+ function advance(nextId) {
476
+ completed.value = [...completed.value, step.value]
477
+ step.value = nextId
478
+ }
479
+ </script>
480
+
481
+ <template>
482
+ <ty-wizard
483
+ height="400px"
484
+ :active="step"
485
+ :completed="completed.join(',')"
486
+ >
487
+ <ty-step id="info" label="Info">
488
+ <div class="p-6">
489
+ <ty-input label="Name" required />
490
+ <ty-button flavor="primary" @click="advance('review')">Next</ty-button>
491
+ </div>
492
+ </ty-step>
493
+ <ty-step id="review" label="Review">
494
+ <div class="p-6">
495
+ <ty-button @click="step = 'info'">Back</ty-button>
496
+ <ty-button flavor="success" @click="advance('done')">Finish</ty-button>
497
+ </div>
498
+ </ty-step>
499
+ <ty-step id="done" label="Done">
500
+ <div class="p-6">All done!</div>
501
+ </ty-step>
502
+ </ty-wizard>
503
+ </template>
504
+ ```
505
+
506
+ Event detail: `{ activeId, activeIndex, previousId, previousIndex, direction }`.
507
+
508
+ ---
509
+
510
+ ## Tooltip and popup
511
+
512
+ ### ty-tooltip
513
+
514
+ Nest `<ty-tooltip>` inside the trigger — it positions itself automatically:
515
+
516
+ ```vue
517
+ <template>
518
+ <ty-button>
519
+ Save
520
+ <ty-tooltip placement="top">Changes saved to your account</ty-tooltip>
521
+ </ty-button>
522
+
523
+ <ty-icon name="info">
524
+ <ty-tooltip flavor="primary" :delay="300">Required field</ty-tooltip>
525
+ </ty-icon>
526
+ </template>
527
+ ```
528
+
529
+ Attrs: `placement` (default `top`), `delay` (ms), `flavor` (`dark`|`light`|semantic colors), `disabled`.
530
+
531
+ ### ty-popup
532
+
533
+ Nest `<ty-popup>` inside the trigger — it opens on click and closes on outside click or ESC:
534
+
535
+ ```vue
536
+ <template>
537
+ <ty-button>
538
+ Options
539
+ <ty-popup placement="bottom-start">
540
+ <div class="ty-elevated p-2 rounded-lg min-w-40">
541
+ <div class="px-3 py-2 hover:ty-bg-neutral- rounded cursor-pointer">Edit</div>
542
+ <div class="px-3 py-2 hover:ty-bg-danger- ty-text-danger rounded cursor-pointer">Delete</div>
543
+ </div>
544
+ </ty-popup>
545
+ </ty-button>
546
+ </template>
547
+ ```
548
+
549
+ For programmatic control, add `manual` and call `ref.value.show()` / `ref.value.hide()`.
550
+
551
+ ---
552
+
553
+ ## Utilities
554
+
555
+ ### ty-copy
556
+
557
+ ```vue
558
+ <template>
559
+ <ty-copy
560
+ label="Install"
561
+ format="code"
562
+ value="npm install tyrell-components"
563
+ />
564
+ </template>
565
+ ```
566
+
567
+ `format="code"` renders monospace styling. Copy happens internally — no event handling needed.
568
+
569
+ ### ty-scroll-container
570
+
571
+ ```vue
572
+ <template>
573
+ <ty-scroll-container max-height="400px">
574
+ <div
575
+ v-for="item in items"
576
+ :key="item.id"
577
+ class="p-3 border-b ty-divide-y"
578
+ >
579
+ {{ item.name }}
580
+ </div>
581
+ </ty-scroll-container>
582
+ </template>
583
+ ```
584
+
585
+ Attrs: `max-height`, `no-shadow`, `hide-scrollbar`, `custom-scrollbar`, `overflow-x`.
586
+
587
+ ---
588
+
589
+ ## Reorderable lists (ty-sortable)
590
+
591
+ `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 Vue renders the items in the new order. Key each item with `:key` and `:data-key` (or `id`):
592
+
593
+ ```vue
594
+ <script setup>
595
+ import { ref } from 'vue'
596
+ const cols = ref({ todo: ['a', 'b'], done: ['c'] })
597
+ const saving = ref(false)
598
+
599
+ async function onMove(e) {
600
+ const { value } = e.detail
601
+ saving.value = true
602
+ try {
603
+ await save(value)
604
+ Object.assign(cols.value, value.order) // new key order per touched list
605
+ } finally {
606
+ saving.value = false // order unchanged: the item snaps back
607
+ }
608
+ }
609
+ </script>
610
+
611
+ <template>
612
+ <ty-sortable
613
+ v-for="(label, id) in { todo: 'To do', done: 'Done' }"
614
+ :key="id"
615
+ :id="id"
616
+ group="board"
617
+ :label="label"
618
+ :aria-busy="saving ? 'true' : null"
619
+ @ty-sortable-change="onMove"
620
+ >
621
+ <div v-for="k in cols[id]" :key="k" :data-key="k">
622
+ <button type="button" data-handle :aria-label="`Move ${k}`">
623
+ <ty-icon name="grip-vertical" />
624
+ </button>
625
+ {{ k }}
626
+ </div>
627
+ </ty-sortable>
628
+ </template>
629
+ ```
630
+
631
+ - `$event.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.
632
+ - `aria-busy` while saving makes a refused save snap back as soon as it clears. Without it, call `e.currentTarget.settle('rejected')` (read `currentTarget` before the first `await`), or `e.preventDefault()` to reject at once.
633
+ - 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.
634
+ - Attrs: `group`, `axis`, `handle`, `accepts`, `disabled`, `key-attr`, `hold-timeout`, `label`. Item attrs: `data-locked`, `data-no-drag`, `data-sortable-ignore`. Set `canDrop` and `labels` with `:prop`; `ref.value.move('a', { to: 'done', index: 0 })` moves without a pointer.
635
+
636
+ ---
637
+
638
+ ## TypeScript
639
+
640
+ Augment Vue's JSX intrinsic elements once:
641
+
642
+ ```ts
643
+ // src/ty-types.d.ts
644
+ import type { DefineComponent } from 'vue'
645
+
646
+ declare module 'vue' {
647
+ interface GlobalComponents {
648
+ 'ty-button': DefineComponent<{
649
+ flavor?: 'primary' | 'success' | 'danger' | 'warning' | 'neutral'
650
+ size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl'
651
+ disabled?: boolean
652
+ pill?: boolean
653
+ action?: boolean
654
+ type?: 'button' | 'submit' | 'reset'
655
+ }>
656
+ 'ty-input': DefineComponent<{
657
+ label?: string
658
+ type?: string
659
+ value?: string | number
660
+ placeholder?: string
661
+ error?: string
662
+ disabled?: boolean
663
+ required?: boolean
664
+ }>
665
+ // ...add other components as needed
666
+ }
667
+ }
668
+ ```
669
+
670
+ Or import the underlying class types from `tyrell-components`:
671
+
672
+ ```ts
673
+ import type { TyButton } from 'tyrell-components/button'
674
+ const btn = ref<TyButton>()
675
+ ```
676
+
677
+ ## Nuxt 3 (SSR)
678
+
679
+ `customElements` does not exist on the server. Two options:
680
+
681
+ ### Option A — Client-only plugin
682
+
683
+ ```ts
684
+ // plugins/tyrell.client.ts
685
+ import 'tyrell-components/css/tyrell.css'
686
+ import 'tyrell-components/css/tyrell-theme.css'
687
+ import 'tyrell-components'
688
+ import { registerIcons } from 'tyrell-components/icons/registry'
689
+ import { check, x } from 'tyrell-components/icons/lucide'
690
+
691
+ export default defineNuxtPlugin(() => {
692
+ registerIcons({ check, x })
693
+ })
694
+ ```
695
+
696
+ The `.client.ts` suffix tells Nuxt to load it only in the browser.
697
+
698
+ ### Option B — `<ClientOnly>` boundaries
699
+
700
+ ```vue
701
+ <template>
702
+ <ClientOnly>
703
+ <ty-date-picker @change="handleChange" />
704
+ <template #fallback>
705
+ <div class="skeleton" />
706
+ </template>
707
+ </ClientOnly>
708
+ </template>
709
+ ```
710
+
711
+ Use this when only specific components need to be client-rendered. The `<ty-*>` markup in initial HTML will render as inert tags until hydration — usually invisible to users, but use the fallback slot if the brief unstyled state is noticeable.
712
+
713
+ ### Configure Vue compiler in Nuxt
714
+
715
+ ```ts
716
+ // nuxt.config.ts
717
+ export default defineNuxtConfig({
718
+ vue: {
719
+ compilerOptions: {
720
+ isCustomElement: (tag) => tag.startsWith('ty-'),
721
+ },
722
+ },
723
+ })
724
+ ```
725
+
726
+ ## Common pitfalls
727
+
728
+ 1. **Forgetting `isCustomElement`** — Vue warns "Failed to resolve component: ty-button". Add the compiler option.
729
+ 2. **Using `prop="value"` instead of `:prop="value"`** for booleans — `disabled="false"` becomes a truthy string `"false"`. Always use `:disabled="false"`.
730
+ 3. **Reading `$event.value` instead of `$event.detail.value`** — Tyrell events follow the standard CustomEvent pattern.
731
+ 4. **Importing `tyrell-components` outside a client boundary in Nuxt** — `customElements is not defined` errors during SSR. Use `.client.ts` suffix or move the import.
732
+ 5. **Two-way binding with `v-model` on ty-input** — Vue's default `v-model` doesn't read `event.detail.value`. Use explicit `:value` + `@change`, or write a custom directive.
733
+
734
+ ## See also
735
+
736
+ - [JAVASCRIPT_GUIDE.md](./JAVASCRIPT_GUIDE.md) — distribution, subpaths, icons, SSR
737
+ - [TY_GUIDE.md](../TY_GUIDE.md) — universal API reference
738
+ - [CSS_GUIDE.md](../CSS_GUIDE.md) — design system