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,962 @@
1
+ # Building Web Components with TyComponent
2
+
3
+ ## 🎯 Overview
4
+
5
+ **TyComponent** is an abstract base class that provides a unified, declarative property/attribute lifecycle for web components. It eliminates boilerplate code, ensures consistency, and makes components predictable and easy to maintain.
6
+
7
+ > The examples below use `ty-select` as the running case study of TyComponent internals — the same patterns apply to every ty component.
8
+
9
+ ### Key Benefits
10
+
11
+ ✅ **Single Code Path** - All property updates flow through one lifecycle
12
+ ✅ **Declarative Configuration** - Define properties once, not in multiple places
13
+ ✅ **Predictable Updates** - State → Render → Events (always in this order)
14
+ ✅ **Smart Rendering** - Only render when visual properties change
15
+ ✅ **Framework Agnostic** - Works with React, Vue, Reagent, vanilla JS
16
+ ✅ **Form Integration** - Built-in ElementInternals support
17
+ ✅ **Property Validation** - Automatic type coercion and validation
18
+ ✅ **Attribute Aliases** - Extra attribute names that set a property to a fixed value
19
+ ✅ **Dual Event System** - Separate 'prop:change' and 'change' events for clarity
20
+
21
+ ---
22
+
23
+ ## 📦 Architecture
24
+
25
+ ### The Unified Property Lifecycle
26
+
27
+ ```
28
+ Property Update (via attribute or property setter)
29
+ ↓
30
+ PropertyManager.updateProperty()
31
+ ↓
32
+ [Validation & Coercion]
33
+ ↓
34
+ PropertyChange emitted
35
+ ↓
36
+ TyComponent._handlePropertyChanges()
37
+ ↓
38
+ ┌─────────────────────────────────────┐
39
+ │ 1. onPropertiesChanged() hook │ ← Update internal state
40
+ │ 2. updateFormValue() (if formValue) │ ← Sync to form
41
+ │ 3. render() (if visual changed) │ ← Update DOM
42
+ │ 4. Emit 'change' event (if needed) │ ← Notify listeners
43
+ └─────────────────────────────────────┘
44
+ ```
45
+
46
+ ### Core Components
47
+
48
+ 1. **PropertyManager** (`/utils/property-manager.ts`)
49
+ - Stores property values in a Map
50
+ - Handles type coercion (string/boolean/number/object/array)
51
+ - Validates property values
52
+ - Tracks property changes
53
+
54
+ 2. **TyComponent** (`/base/ty-component.ts`)
55
+ - Base class for all components
56
+ - Unified `attributeChangedCallback`
57
+ - Automatic property capture for React/Reagent
58
+ - Lifecycle hooks (onConnect, onDisconnect, onPropertiesChanged)
59
+ - Form value handling via ElementInternals
60
+
61
+ 3. **Your Component** (extends TyComponent)
62
+ - Property configuration
63
+ - Property accessors (getters/setters)
64
+ - Internal state management
65
+ - Render implementation
66
+
67
+ ### Event System: `prop:change` vs `change`
68
+
69
+ TyComponent uses **two distinct event types** to avoid conflicts:
70
+
71
+ **`prop:change`** - Property Change Events
72
+ - Emitted when properties marked with `emitChange: true` change
73
+ - Triggered by: attribute changes, property setters, external updates
74
+ - Detail: `{ property: 'name', oldValue: any, newValue: any }`
75
+ - Use case: Reactive frameworks, property watchers, debugging
76
+ - Example: `<ty-select onPropChange={...} />` in React
77
+
78
+ **`change`** - User Interaction Events
79
+ - Emitted by component business logic (manually dispatched)
80
+ - Triggered by: user clicks, selections, form interactions
81
+ - Detail: Component-specific (e.g., ty-select emits `{ value, values, items, action, item }` — `value` is a scalar for single select, an array with `multiple`)
82
+ - Use case: Application logic, form handling, user actions
83
+ - Example: `<ty-select onChange={...} />` in React
84
+
85
+ **Why separate events?**
86
+ ```javascript
87
+ // React example - clear distinction
88
+ <ty-select
89
+ // Listen to user interactions
90
+ onChange={(e) => console.log('User selected:', e.detail.value)}
91
+
92
+ // Listen to any property changes (including programmatic)
93
+ onPropChange={(e) => console.log('Value changed:', e.detail.newValue)}
94
+ />
95
+ ```
96
+
97
+ This prevents double-event issues where frameworks would receive both property updates AND user interaction events for the same action.
98
+
99
+ ---
100
+
101
+ ## 🚀 Step-by-Step Guide
102
+
103
+ ### Step 1: Extend TyComponent
104
+
105
+ ```typescript
106
+ import { TyComponent } from '../base/ty-component.js'
107
+ import type { PropertyChange } from '../utils/property-manager.js'
108
+ import type { Flavor, Size } from '../types/common.js'
109
+
110
+ // Define your component's internal state interface
111
+ interface SelectState {
112
+ open: boolean
113
+ search: string
114
+ highlightedIndex: number
115
+ filteredOptions: OptionData[]
116
+ currentValue: string | null
117
+ mode: 'desktop' | 'mobile'
118
+ }
119
+
120
+ export class TySelect extends TyComponent<SelectState> {
121
+ // Component implementation here...
122
+ }
123
+ ```
124
+
125
+ ### Step 2: Configure Properties (Declarative)
126
+
127
+ This is the **most important part** - define all your properties in one place:
128
+
129
+ ```typescript
130
+ export class TySelect extends TyComponent<SelectState> {
131
+ // ============================================================================
132
+ // PROPERTY CONFIGURATION - Single source of truth
133
+ // ============================================================================
134
+ protected static properties = {
135
+ // String property with form value and property change events
136
+ value: {
137
+ type: 'string' as const,
138
+ visual: true, // Triggers render when changed
139
+ formValue: true, // Syncs to form value
140
+ emitChange: true, // Emits 'prop:change' event (separate from user 'change')
141
+ default: '' // Default value
142
+ },
143
+
144
+ // String property (non-visual)
145
+ name: {
146
+ type: 'string' as const,
147
+ default: ''
148
+ },
149
+
150
+ // String property with visual impact
151
+ placeholder: {
152
+ type: 'string' as const,
153
+ visual: true,
154
+ default: 'Select...'
155
+ },
156
+
157
+ // Boolean property
158
+ disabled: {
159
+ type: 'boolean' as const,
160
+ visual: true,
161
+ default: false
162
+ },
163
+
164
+ // camelCase property ↔ kebab-case attribute: <ty-select external-search>
165
+ externalSearch: {
166
+ type: 'boolean' as const,
167
+ visual: true,
168
+ default: false
169
+ },
170
+
171
+ // String property with validation
172
+ size: {
173
+ type: 'string' as const,
174
+ visual: true,
175
+ default: 'md',
176
+ validate: (v: any) => ['sm', 'md', 'lg'].includes(v),
177
+ coerce: (v: any) => {
178
+ if (!['sm', 'md', 'lg'].includes(v)) {
179
+ console.warn(`[ty-select] Invalid size. Using md.`)
180
+ return 'md'
181
+ }
182
+ return v
183
+ }
184
+ },
185
+
186
+ // Number property with bounds
187
+ debounce: {
188
+ type: 'number' as const,
189
+ default: 0,
190
+ validate: (v: any) => v >= 0 && v <= 5000,
191
+ coerce: (v: any) => {
192
+ const num = Number(v)
193
+ if (isNaN(num)) return 0
194
+ return Math.max(0, Math.min(5000, num))
195
+ }
196
+ }
197
+ }
198
+ }
199
+ ```
200
+
201
+ #### Property Configuration Options
202
+
203
+ | Option | Type | Description |
204
+ |--------|------|-------------|
205
+ | `type` | `'string' \| 'boolean' \| 'number' \| 'object' \| 'array'` | Data type for automatic coercion |
206
+ | `visual` | `boolean` | If true, changing this property triggers `render()` |
207
+ | `formValue` | `boolean` | If true, changing this property updates form value |
208
+ | `emitChange` | `boolean` | If true, changing this property emits 'prop:change' event (distinct from user 'change' events) |
209
+ | `default` | `any` | Default value when property is undefined |
210
+ | `validate` | `(value: any) => boolean` | Custom validation function |
211
+ | `coerce` | `(value: any) => any` | Custom coercion/transformation function |
212
+
213
+ ### Step 3: Create Property Accessors (Simple!)
214
+
215
+ These are **simple wrappers** with **no logic** - TyComponent handles everything:
216
+
217
+ ```typescript
218
+ export class TySelect extends TyComponent<SelectState> {
219
+ // ... property configuration ...
220
+
221
+ // ============================================================================
222
+ // PROPERTY ACCESSORS - Just call getProperty/setProperty
223
+ // ============================================================================
224
+
225
+ get value(): string {
226
+ return this.getProperty('value')
227
+ }
228
+ set value(v: string) {
229
+ this.setProperty('value', v)
230
+ }
231
+
232
+ get placeholder(): string {
233
+ return this.getProperty('placeholder')
234
+ }
235
+ set placeholder(v: string) {
236
+ this.setProperty('placeholder', v)
237
+ }
238
+
239
+ get disabled(): boolean {
240
+ return this.getProperty('disabled')
241
+ }
242
+ set disabled(v: boolean) {
243
+ this.setProperty('disabled', v)
244
+ }
245
+
246
+ get externalSearch(): boolean {
247
+ return this.getProperty('externalSearch')
248
+ }
249
+ set externalSearch(v: boolean) {
250
+ this.setProperty('externalSearch', v)
251
+ }
252
+
253
+ get size(): Size {
254
+ return this.getProperty('size') as Size
255
+ }
256
+ set size(v: Size) {
257
+ this.setProperty('size', v)
258
+ }
259
+
260
+ get debounce(): number {
261
+ return this.getProperty('debounce')
262
+ }
263
+ set debounce(v: number) {
264
+ this.setProperty('debounce', v)
265
+ }
266
+ }
267
+ ```
268
+
269
+ **Important**: Property accessors should **never** contain logic. All validation, coercion, and side effects are handled by PropertyManager and lifecycle hooks.
270
+
271
+ ### Step 4: Initialize Internal State
272
+
273
+ ```typescript
274
+ export class TySelect extends TyComponent<SelectState> {
275
+ // ... properties and accessors ...
276
+
277
+ // ============================================================================
278
+ // INTERNAL STATE - Component-specific state
279
+ // ============================================================================
280
+
281
+ private _state: SelectState = {
282
+ open: false,
283
+ search: '',
284
+ highlightedIndex: -1,
285
+ filteredOptions: [],
286
+ currentValue: null,
287
+ mode: isMobileDevice() ? 'mobile' : 'desktop'
288
+ }
289
+
290
+ // Other internal fields (not properties)
291
+ private _scrollLockId: string | null = null
292
+ private _searchDebounceTimer: number | null = null
293
+ }
294
+ ```
295
+
296
+ ### Step 5: Implement Constructor
297
+
298
+ ```typescript
299
+ export class TySelect extends TyComponent<SelectState> {
300
+ // ... properties, accessors, state ...
301
+
302
+ constructor() {
303
+ super() // TyComponent handles attachInternals() and attachShadow()
304
+
305
+ const shadow = this.shadowRoot!
306
+ ensureStyles(shadow, { css: selectStyles, id: 'ty-select' })
307
+ }
308
+ }
309
+ ```
310
+
311
+ **Note**: TyComponent's constructor automatically:
312
+ - Creates PropertyManager with your property configuration
313
+ - Calls `attachInternals()` for form association
314
+ - Calls `attachShadow({ mode: 'open' })`
315
+
316
+ ### Step 6: Implement Lifecycle Hooks
317
+
318
+ #### `onConnect()` - Called when component connects to DOM
319
+
320
+ Use this instead of overriding `connectedCallback`:
321
+
322
+ ```typescript
323
+ protected onConnect(): void {
324
+ // Initialize state
325
+ this.initializeState()
326
+
327
+ // Set up observers, resize listeners, etc.
328
+ this.setupResizeObserver()
329
+ }
330
+ ```
331
+
332
+ #### `onDisconnect()` - Called when component disconnects from DOM
333
+
334
+ Use this for cleanup instead of overriding `disconnectedCallback`:
335
+
336
+ ```typescript
337
+ protected onDisconnect(): void {
338
+ // Clean up document-level listeners
339
+ const outsideClickHandler = (this as any).tyOutsideClickHandler
340
+ const keyboardHandler = (this as any).tyKeyboardHandler
341
+
342
+ if (outsideClickHandler) {
343
+ document.removeEventListener('click', outsideClickHandler)
344
+ ;(this as any).tyOutsideClickHandler = null
345
+ }
346
+
347
+ if (keyboardHandler) {
348
+ document.removeEventListener('keydown', keyboardHandler)
349
+ ;(this as any).tyKeyboardHandler = null
350
+ }
351
+
352
+ // Clear any pending timers
353
+ if (this._searchDebounceTimer !== null) {
354
+ clearTimeout(this._searchDebounceTimer)
355
+ this._searchDebounceTimer = null
356
+ }
357
+ }
358
+ ```
359
+
360
+ #### `onPropertiesChanged()` - Called when properties change
361
+
362
+ This is where you update internal state **before rendering**:
363
+
364
+ ```typescript
365
+ protected onPropertiesChanged(changes: PropertyChange[]): void {
366
+ for (const { name, newValue } of changes) {
367
+ switch (name) {
368
+ case 'value':
369
+ // Update internal state when value changes
370
+ this._state.currentValue = newValue || null
371
+ this.syncSelectedOption()
372
+ break
373
+
374
+ case 'placeholder':
375
+ // Update placeholder in DOM if already rendered
376
+ this.updatePlaceholderInDOM()
377
+ break
378
+
379
+ case 'externalSearch':
380
+ // Update search row visibility
381
+ this.updateSearchRow()
382
+ break
383
+
384
+ case 'disabled':
385
+ // Update disabled state in DOM
386
+ this.updateDisabledState()
387
+ break
388
+ }
389
+ }
390
+ }
391
+ ```
392
+
393
+ **Important**:
394
+ - This hook runs **before** `render()`
395
+ - Use it to update `_state` or other internal fields
396
+ - Don't call `render()` manually - TyComponent handles it
397
+ - Only visual properties trigger `render()` automatically
398
+
399
+ ### Step 7: Implement Form Value Handling (Optional)
400
+
401
+ If your component is a form control, override `getFormValue()`:
402
+
403
+ ```typescript
404
+ protected getFormValue(): FormDataEntryValue | null {
405
+ return this._state.currentValue || null
406
+ }
407
+ ```
408
+
409
+ TyComponent automatically:
410
+ - Calls `getFormValue()` when a `formValue: true` property changes
411
+ - Syncs the value to the form via `this._internals.setFormValue()`
412
+
413
+ ### Step 8: Implement Render Method
414
+
415
+ This is where you update the DOM. Focus on **pure rendering** - no property synchronization:
416
+
417
+ ```typescript
418
+ protected render(): void {
419
+ if (this._state.mode === 'mobile') {
420
+ this.renderMobile()
421
+ } else {
422
+ this.renderDesktop()
423
+ }
424
+ }
425
+
426
+ private renderDesktop(): void {
427
+ const shadow = this.shadowRoot!
428
+
429
+ shadow.innerHTML = `
430
+ <div class="ty-select ${this.size}">
431
+ ${this.label ? `<label>${this.label}</label>` : ''}
432
+ <div class="ty-select-trigger">
433
+ <span class="selected-display">${this.placeholder}</span>
434
+ <button class="chevron-btn">▼</button>
435
+ </div>
436
+ <div class="ty-select-popup">
437
+ <!-- Search row + options rendered here -->
438
+ </div>
439
+ </div>
440
+ `
441
+
442
+ // Attach event listeners
443
+ this.attachEventListeners()
444
+ }
445
+ ```
446
+
447
+ **Important**:
448
+ - `render()` is called automatically when visual properties change
449
+ - Don't manually sync properties to DOM - they're already in `this.getProperty(name)`
450
+ - Use property getters to access values: `this.placeholder`, `this.disabled`, etc.
451
+
452
+ ---
453
+
454
+ ## 🎨 Common Patterns
455
+
456
+ ### Pattern 1: Default-On Features
457
+
458
+ A feature that's on by default gets a boolean that names the deviation and defaults to `false`, like native `disabled`. Never a `default: true` boolean: frameworks render `false` by dropping the attribute, which would turn it back on.
459
+
460
+ ```typescript
461
+ protected static properties = {
462
+ noClear: {
463
+ type: 'boolean' as const,
464
+ visual: true,
465
+ default: false
466
+ }
467
+ }
468
+ ```
469
+
470
+ **Usage** (this is how `ty-date-picker` defines its clear button):
471
+ ```html
472
+ <ty-date-picker></ty-date-picker> <!-- clear button -->
473
+ <ty-date-picker no-clear></ty-date-picker> <!-- none -->
474
+ ```
475
+
476
+ ### Pattern 2: Validated String Properties
477
+
478
+ ```typescript
479
+ protected static properties = {
480
+ size: {
481
+ type: 'string' as const,
482
+ visual: true,
483
+ default: 'md',
484
+ validate: (v: any) => ['sm', 'md', 'lg'].includes(v),
485
+ coerce: (v: any) => {
486
+ const valid = ['sm', 'md', 'lg']
487
+ if (!valid.includes(v)) {
488
+ console.warn(`[my-component] Invalid size '${v}'. Using 'md'.`)
489
+ return 'md'
490
+ }
491
+ return v
492
+ }
493
+ }
494
+ }
495
+ ```
496
+
497
+ ### Pattern 3: Number Properties with Bounds
498
+
499
+ ```typescript
500
+ protected static properties = {
501
+ debounce: {
502
+ type: 'number' as const,
503
+ default: 0,
504
+ validate: (v: any) => v >= 0 && v <= 5000,
505
+ coerce: (v: any) => {
506
+ const num = Number(v)
507
+ if (isNaN(num)) return 0
508
+ return Math.max(0, Math.min(5000, num))
509
+ }
510
+ }
511
+ }
512
+ ```
513
+
514
+ ### Pattern 4: Object/Array Properties
515
+
516
+ ```typescript
517
+ protected static properties = {
518
+ options: {
519
+ type: 'array' as const,
520
+ visual: true,
521
+ default: [],
522
+ validate: (v: any) => Array.isArray(v),
523
+ coerce: (v: any) => {
524
+ // Handle string attribute: options='[{"value":"1","label":"One"}]'
525
+ if (typeof v === 'string') {
526
+ try {
527
+ return JSON.parse(v)
528
+ } catch {
529
+ console.warn('[my-component] Failed to parse options')
530
+ return []
531
+ }
532
+ }
533
+ return Array.isArray(v) ? v : []
534
+ }
535
+ }
536
+ }
537
+ ```
538
+
539
+ ### Pattern 5: Form-Associated Properties
540
+
541
+ ```typescript
542
+ protected static properties = {
543
+ value: {
544
+ type: 'string' as const,
545
+ visual: true,
546
+ formValue: true, // ← Syncs to form
547
+ emitChange: true, // ← Emits 'prop:change' event
548
+ default: ''
549
+ }
550
+ }
551
+
552
+ // Override form value handling if needed
553
+ protected getFormValue(): FormDataEntryValue | null {
554
+ // Can return string, File, or FormData
555
+ return this._state.currentValue || null
556
+ }
557
+ ```
558
+
559
+ ### Pattern 6: Non-Visual Properties
560
+
561
+ Some properties don't require re-rendering (like `name` or `debounce`):
562
+
563
+ ```typescript
564
+ protected static properties = {
565
+ name: {
566
+ type: 'string' as const,
567
+ // No 'visual: true' - changing this doesn't trigger render
568
+ default: ''
569
+ },
570
+ debounce: {
571
+ type: 'number' as const,
572
+ // No 'visual: true' - only affects event emission timing
573
+ default: 0
574
+ }
575
+ }
576
+ ```
577
+
578
+ ---
579
+
580
+ ## 🔍 Real-World Example: TySelect
581
+
582
+ Here's how the actual `TySelect` component is structured:
583
+
584
+ ```typescript
585
+ export class TySelect extends TyComponent<SelectState> {
586
+ // ============================================================================
587
+ // 1. PROPERTY CONFIGURATION
588
+ // ============================================================================
589
+ protected static properties = {
590
+ value: {
591
+ type: 'string' as const,
592
+ visual: true,
593
+ formValue: true,
594
+ emitChange: true,
595
+ default: ''
596
+ },
597
+ placeholder: {
598
+ type: 'string' as const,
599
+ visual: true,
600
+ default: 'Select...'
601
+ },
602
+ multiple: {
603
+ type: 'boolean' as const,
604
+ visual: true,
605
+ default: false
606
+ },
607
+ externalSearch: {
608
+ type: 'boolean' as const,
609
+ visual: true,
610
+ default: false
611
+ },
612
+ size: {
613
+ type: 'string' as const,
614
+ visual: true,
615
+ default: 'md',
616
+ validate: (v: any) => ['sm', 'md', 'lg'].includes(v),
617
+ coerce: (v: any) => {
618
+ if (!['sm', 'md', 'lg'].includes(v)) {
619
+ console.warn(`[ty-select] Invalid size. Using md.`)
620
+ return 'md'
621
+ }
622
+ return v
623
+ }
624
+ }
625
+ // ... more properties
626
+ }
627
+
628
+ // ============================================================================
629
+ // 2. INTERNAL STATE
630
+ // ============================================================================
631
+ private _state: SelectState = {
632
+ open: false,
633
+ search: '',
634
+ highlightedIndex: -1,
635
+ filteredOptions: [],
636
+ currentValue: null,
637
+ mode: isMobileDevice() ? 'mobile' : 'desktop'
638
+ }
639
+
640
+ // ============================================================================
641
+ // 3. PROPERTY ACCESSORS (Simple!)
642
+ // ============================================================================
643
+ get value(): string { return this.getProperty('value') }
644
+ set value(v: string) { this.setProperty('value', v) }
645
+
646
+ get placeholder(): string { return this.getProperty('placeholder') }
647
+ set placeholder(v: string) { this.setProperty('placeholder', v) }
648
+
649
+ get multiple(): boolean { return this.getProperty('multiple') }
650
+ set multiple(v: boolean) { this.setProperty('multiple', v) }
651
+
652
+ get externalSearch(): boolean { return this.getProperty('externalSearch') }
653
+ set externalSearch(v: boolean) { this.setProperty('externalSearch', v) }
654
+
655
+ get size(): Size { return this.getProperty('size') as Size }
656
+ set size(v: Size) { this.setProperty('size', v) }
657
+
658
+ // ============================================================================
659
+ // 4. CONSTRUCTOR
660
+ // ============================================================================
661
+ constructor() {
662
+ super()
663
+ const shadow = this.shadowRoot!
664
+ ensureStyles(shadow, { css: selectStyles, id: 'ty-select' })
665
+ }
666
+
667
+ // ============================================================================
668
+ // 5. LIFECYCLE HOOKS
669
+ // ============================================================================
670
+ protected onConnect(): void {
671
+ this.initializeState()
672
+ }
673
+
674
+ protected onDisconnect(): void {
675
+ // Cleanup listeners
676
+ }
677
+
678
+ protected onPropertiesChanged(changes: PropertyChange[]): void {
679
+ for (const { name, newValue } of changes) {
680
+ switch (name) {
681
+ case 'value':
682
+ this._state.currentValue = newValue || null
683
+ this.syncSelectedOption()
684
+ break
685
+ case 'externalSearch':
686
+ this.updateSearchRow()
687
+ break
688
+ }
689
+ }
690
+ }
691
+
692
+ protected getFormValue(): FormDataEntryValue | null {
693
+ return this._state.currentValue || null
694
+ }
695
+
696
+ // ============================================================================
697
+ // 6. RENDER
698
+ // ============================================================================
699
+ protected render(): void {
700
+ if (this._state.mode === 'mobile') {
701
+ this.renderMobile()
702
+ } else {
703
+ this.renderDesktop()
704
+ }
705
+ }
706
+
707
+ private renderDesktop(): void {
708
+ // Pure rendering logic
709
+ }
710
+
711
+ // ============================================================================
712
+ // 7. PRIVATE METHODS (Business Logic)
713
+ // ============================================================================
714
+ private initializeState(): void { /* ... */ }
715
+ private syncSelectedOption(): void { /* ... */ }
716
+ private updateSearchRow(): void { /* ... */ }
717
+ private attachEventListeners(): void { /* ... */ }
718
+ }
719
+ ```
720
+
721
+ ---
722
+
723
+ ## ✅ Best Practices
724
+
725
+ ### DO ✅
726
+
727
+ ✅ **Use property configuration** for all component properties
728
+ ✅ **Keep accessors simple** - just call `getProperty`/`setProperty`
729
+ ✅ **Use `onPropertiesChanged`** for state updates before render
730
+ ✅ **Mark visual properties** with `visual: true`
731
+ ✅ **Mark form properties** with `formValue: true`
732
+ ✅ **Provide validation** for properties with constraints
733
+ ✅ **Provide coercion** for properties needing transformation
734
+ ✅ **Use hooks** (`onConnect`, `onDisconnect`, `onPropertiesChanged`)
735
+ ✅ **Focus on pure rendering** in `render()` method
736
+
737
+ ### DON'T ❌
738
+
739
+ ❌ **Don't put logic in property accessors** - use hooks instead
740
+ ❌ **Don't manually call `render()`** - TyComponent handles it
741
+ ❌ **Don't manually sync attributes** - TyComponent handles it
742
+ ❌ **Don't override lifecycle methods** - use hooks instead
743
+ ❌ **Don't update properties inside `render()`** - update in `onPropertiesChanged`
744
+ ❌ **Don't forget `super()` in constructor**
745
+ ❌ **Don't access `_internals` directly** - use `getFormValue()` hook
746
+
747
+ ---
748
+
749
+ ## 🧪 Testing Your Component
750
+
751
+ ### Property Setting
752
+
753
+ ```typescript
754
+ // Via attribute
755
+ select.setAttribute('value', 'test')
756
+ console.assert(select.value === 'test')
757
+
758
+ // Via property
759
+ select.value = 'test2'
760
+ console.assert(select.getAttribute('value') === 'test2')
761
+
762
+ // Before connectedCallback (React pattern)
763
+ const select = document.createElement('ty-select')
764
+ select.value = 'preset' // ← Set before mounting
765
+ document.body.appendChild(select)
766
+ console.assert(select.value === 'preset') // ← Should work!
767
+ ```
768
+
769
+ ### Boolean Properties
770
+
771
+ ```typescript
772
+ // Attribute presence
773
+ select.setAttribute('disabled', '')
774
+ console.assert(select.disabled === true)
775
+
776
+ // Attribute absence
777
+ select.removeAttribute('disabled')
778
+ console.assert(select.disabled === false)
779
+
780
+ // kebab-case attribute → camelCase property
781
+ select.setAttribute('external-search', '')
782
+ console.assert(select.externalSearch === true)
783
+
784
+ // "false" is off, like every boolean attribute here
785
+ select.setAttribute('external-search', 'false')
786
+ console.assert(select.externalSearch === false)
787
+ ```
788
+
789
+ ### Form Integration
790
+
791
+ ```typescript
792
+ const form = document.createElement('form')
793
+ const select = document.createElement('ty-select')
794
+ select.name = 'country'
795
+ select.value = 'us'
796
+
797
+ form.appendChild(select)
798
+ document.body.appendChild(form)
799
+
800
+ const formData = new FormData(form)
801
+ console.assert(formData.get('country') === 'us')
802
+ ```
803
+
804
+ ### Change Events
805
+
806
+ ```typescript
807
+ // Listen to property changes (reactive frameworks)
808
+ select.addEventListener('prop:change', (e) => {
809
+ console.log('Property changed:', e.detail)
810
+ // { property: 'value', oldValue: 'old', newValue: 'new' }
811
+ })
812
+
813
+ // Listen to user interaction changes (business logic)
814
+ select.addEventListener('change', (e) => {
815
+ console.log('User changed:', e.detail)
816
+ // { value: 'new', values: ['new'], items: [...], action: 'add', item: 'new' }
817
+ })
818
+
819
+ select.value = 'new' // ← Triggers 'prop:change' if emitChange: true
820
+ ```
821
+
822
+ ---
823
+
824
+ ## 🎯 Migration Checklist
825
+
826
+ When migrating an existing component to TyComponent:
827
+
828
+ - [ ] Create property configuration object
829
+ - [ ] Remove private field declarations for properties
830
+ - [ ] Simplify property accessors (use get/setProperty)
831
+ - [ ] Remove `observedAttributes` getter (auto-generated)
832
+ - [ ] Remove `attributeChangedCallback` method (inherited)
833
+ - [ ] Remove property capture code from `connectedCallback`
834
+ - [ ] Move initialization to `onConnect()` hook
835
+ - [ ] Move cleanup to `onDisconnect()` hook
836
+ - [ ] Move state updates to `onPropertiesChanged()` hook
837
+ - [ ] Remove manual `setAttribute` calls in setters
838
+ - [ ] Remove manual `render()` calls in setters
839
+ - [ ] Override `getFormValue()` instead of `updateFormValue()`
840
+ - [ ] Test all property setting scenarios
841
+
842
+ ---
843
+
844
+ ## 🚨 Common Pitfalls
845
+
846
+ ### Pitfall 1: Logic in Property Accessors
847
+
848
+ ❌ **Wrong**:
849
+ ```typescript
850
+ set value(v: string) {
851
+ this.setProperty('value', v)
852
+ this._state.currentValue = v // ← Don't do this here!
853
+ this.render() // ← Don't do this here!
854
+ }
855
+ ```
856
+
857
+ ✅ **Correct**:
858
+ ```typescript
859
+ set value(v: string) {
860
+ this.setProperty('value', v) // ← That's it!
861
+ }
862
+
863
+ protected onPropertiesChanged(changes: PropertyChange[]): void {
864
+ for (const { name, newValue } of changes) {
865
+ if (name === 'value') {
866
+ this._state.currentValue = newValue // ← Do it here instead
867
+ }
868
+ }
869
+ // render() is called automatically by TyComponent
870
+ }
871
+ ```
872
+
873
+ ### Pitfall 2: Forgetting to Mark Visual Properties
874
+
875
+ ❌ **Wrong**:
876
+ ```typescript
877
+ protected static properties = {
878
+ placeholder: {
879
+ type: 'string' as const,
880
+ // Missing: visual: true
881
+ default: 'Select...'
882
+ }
883
+ }
884
+ ```
885
+
886
+ **Result**: Changing `placeholder` won't trigger re-render!
887
+
888
+ ✅ **Correct**:
889
+ ```typescript
890
+ protected static properties = {
891
+ placeholder: {
892
+ type: 'string' as const,
893
+ visual: true, // ← Add this!
894
+ default: 'Select...'
895
+ }
896
+ }
897
+ ```
898
+
899
+ ### Pitfall 3: Updating Properties During Render
900
+
901
+ ❌ **Wrong**:
902
+ ```typescript
903
+ protected render(): void {
904
+ // Don't update properties inside render!
905
+ if (this._state.open) {
906
+ this.placeholder = 'Search...' // ← Triggers another render!
907
+ }
908
+ }
909
+ ```
910
+
911
+ ✅ **Correct**:
912
+ ```typescript
913
+ protected onPropertiesChanged(changes: PropertyChange[]): void {
914
+ // Update before render
915
+ if (changes.some(c => c.name === 'open')) {
916
+ if (this._state.open) {
917
+ // Update internal state, not properties
918
+ this._effectivePlaceholder = 'Search...'
919
+ }
920
+ }
921
+ }
922
+
923
+ protected render(): void {
924
+ // Use computed state
925
+ const placeholder = this._effectivePlaceholder || this.placeholder
926
+ }
927
+ ```
928
+
929
+ ---
930
+
931
+ ## 📚 Summary
932
+
933
+ **TyComponent provides**:
934
+ 1. ✅ Unified property/attribute synchronization
935
+ 2. ✅ Automatic type coercion and validation
936
+ 3. ✅ Declarative property configuration
937
+ 4. ✅ Predictable lifecycle (State → Render → Events)
938
+ 5. ✅ Form association support
939
+ 6. ✅ Framework compatibility (React, Vue, Reagent)
940
+ 7. ✅ Default-on features as `no-*` booleans (e.g., `no-clear`)
941
+
942
+ **You implement**:
943
+ 1. Property configuration object
944
+ 2. Simple property accessors
945
+ 3. Internal state structure
946
+ 4. Lifecycle hooks (onConnect, onDisconnect, onPropertiesChanged)
947
+ 5. Render method (pure DOM updates)
948
+ 6. Business logic (event handlers, etc.)
949
+
950
+ **Result**: Components are **consistent**, **maintainable**, and **work everywhere**!
951
+
952
+ ---
953
+
954
+ ## 🔗 Related Files
955
+
956
+ - `/packages/core/src/base/ty-component.ts` - Base class implementation
957
+ - `/packages/core/src/utils/property-manager.ts` - Property lifecycle manager
958
+ - `/packages/core/src/components/select.ts` - Complete real-world example
959
+
960
+ ---
961
+
962
+ **Built with TyComponent. Framework-agnostic by design. Standards-based for longevity.**