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,935 @@
1
+ # Tyrell Component Library — Guide
2
+
3
+ **Tyrell** is a framework-agnostic web component library. TypeScript core (`tyrell-components`), React wrappers (`tyrell-react`), ClojureScript infra (`dev.gersak/tyrell`).
4
+
5
+ ---
6
+
7
+ ## Use Tyrell Components
8
+
9
+ When a Tyrell component exists, use it. Do not improvise HTML.
10
+
11
+ | Need | Use | Not |
12
+ |------|-----|-----|
13
+ | Button | `<ty-button>` | `<button>`, `<div onclick>` |
14
+ | Text input | `<ty-input>` | `<input>` |
15
+ | Money/currency | `<ty-input type="currency">` | `<input type="number">` + manual formatting |
16
+ | Percentage | `<ty-input type="percent">` | `<input type="number">` + `%` suffix |
17
+ | Large numbers | `<ty-input type="compact">` | `<input type="number">` + abbreviation |
18
+ | Checkbox | `<ty-checkbox>` | `<input type="checkbox">` |
19
+ | Textarea | `<ty-textarea>` | `<textarea>` |
20
+ | File upload | `<ty-file-upload>` | `<input type="file">` + custom drop zones |
21
+ | Select (single or multi) | `<ty-select>` | `<select>`, custom menus, multiple checkboxes |
22
+ | Modal | `<ty-modal>` | `<dialog>`, custom overlays |
23
+ | Tooltip | `<ty-tooltip>` | `title` attr, custom divs |
24
+ | Popup | `<ty-popup>` | Custom positioned divs |
25
+ | Tabs | `<ty-tabs>` + `<ty-tab>` | Custom tab implementations |
26
+ | Wizard | `<ty-wizard>` + `<ty-step>` | Custom step indicators |
27
+ | Date picker | `<ty-date-picker>` | `<input type="date">` |
28
+ | Calendar | `<ty-calendar>` | Custom calendar grids |
29
+ | Tags/Chips | `<ty-tag>` | `<span>` with classes |
30
+ | Icons | `<ty-icon>` | `<svg>`, `<img>`, icon fonts |
31
+ | Copy button | `<ty-copy>` | Custom copy buttons |
32
+ | Scrollable area | `<ty-scroll-container>` | `overflow-auto` + manual indicators |
33
+ | Reorderable list | `<ty-sortable>` | Drag-and-drop libraries, custom drag code |
34
+ | Field label | `label` attribute on component | `<label>` element |
35
+ | Error message | `error` attribute on component | `<span class="text-red-500">` |
36
+ | Debounced input | `debounce` attribute | Manual `setTimeout`/debounce |
37
+
38
+ Plain HTML is OK for: layout (`<div>`, `<section>`), text (`<h1>`-`<h6>`, `<p>`, `<span>` with Tyrell classes), lists, links, images.
39
+
40
+ ---
41
+
42
+ ## Built-in Attributes
43
+
44
+ Form components have built-in `label`, `error`, `placeholder`, `required`, `disabled`, `flavor`, and `size`.
45
+
46
+ ```html
47
+ <!-- Use built-in label and error -->
48
+ <ty-input type="email" label="Email" placeholder="you@example.com" error="Invalid email"></ty-input>
49
+ ```
50
+
51
+ ```clojure
52
+ [:ty-input {:type "email" :label "Email" :placeholder "you@example.com" :error "Invalid email"}]
53
+ ```
54
+
55
+ ---
56
+
57
+ ## Slots for Icons
58
+
59
+ Components with `start`/`end` slots handle spacing automatically.
60
+
61
+ ```html
62
+ <ty-button flavor="primary">
63
+ <ty-icon slot="start" name="save" size="sm"></ty-icon>
64
+ Save
65
+ </ty-button>
66
+
67
+ <ty-input type="currency" currency="EUR" label="Price">
68
+ <ty-icon slot="start" name="euro"></ty-icon>
69
+ </ty-input>
70
+ ```
71
+
72
+ ```clojure
73
+ [:ty-button {:flavor "primary"}
74
+ [:ty-icon {:slot "start" :name "save" :size "sm"}]
75
+ "Save"]
76
+ ```
77
+
78
+ ### All Slots
79
+
80
+ ```
81
+ ty-button slot="start" | (default text) | slot="end"
82
+ ty-input slot="start" | (input field) | slot="end"
83
+ ty-tag slot="start" | (tag text) | slot="end"
84
+ ty-select slot="start" | slot="end" | slot="trigger" (custom chrome) | slot="loading"
85
+ ty-tabs slot="label-{id}" (rich tab label) | slot="marker" (active indicator)
86
+ ty-tab (default: panel) | slot="loading" | slot="error" (lazy tabs)
87
+ ty-wizard slot="indicator-{id}" (custom step indicator)
88
+ ```
89
+
90
+ ---
91
+
92
+ ## Input Types
93
+
94
+ | Type | When | Display (on blur) | Value |
95
+ |------|------|-------------------|-------|
96
+ | `"currency"` | Money (prices, budgets, transactions) | `$1,234.56` / `€1.234,56` | `1234.56` |
97
+ | `"percent"` | Rates, discounts | `15.00%` | `15` |
98
+ | `"compact"` | Large numbers, stats | `1.2M` / `1.2K` | `1234567` |
99
+ | `"number"` | Plain numeric, no formatting | `1234.56` | `1234.56` |
100
+
101
+ Raw number while editing, formatted on blur. Uses `Intl.NumberFormat`.
102
+
103
+ Attributes: `currency` (ISO 4217 code, default `"USD"`), `locale` (default `"en-US"`), `precision` (decimal places).
104
+
105
+ Events: `detail: { value, formattedValue, rawValue, originalEvent }`.
106
+
107
+ FormData: submits raw number, not formatted string.
108
+
109
+ ```html
110
+ <ty-input type="currency" currency="EUR" locale="de-DE" label="Price" placeholder="0.00">
111
+ <ty-icon slot="start" name="euro"></ty-icon>
112
+ </ty-input>
113
+
114
+ <ty-input type="percent" label="Discount" precision="1"></ty-input>
115
+ <ty-input type="compact" label="Revenue"></ty-input>
116
+ ```
117
+
118
+ ---
119
+
120
+ ## Flavors
121
+
122
+ | Flavor | Intent | Examples |
123
+ |--------|--------|---------|
124
+ | `primary` | Main action | Submit, Save, Confirm |
125
+ | `success` | Positive | Income, completed, "Added!" |
126
+ | `danger` | Destructive/negative | Delete, expenses, errors |
127
+ | `warning` | Caution | Unsaved changes, limits |
128
+ | `neutral` | Default, no weight | Cancel, Close |
129
+
130
+ Any other string is a **custom flavor**. Easiest: one seed color (`--ty-X-seed: #784011`) plus a once-pasted engine block from the Theming page's flavor builder, and the flavor follows the dials and dark mode like a built-in. Or hand-pick the 16 `--ty-color-X` / `--ty-bg-X` / `--ty-solid-X` tokens. Either way the component themes itself, `+`/`-` shades included. Every flavored component supports this (`ty-button`, `ty-tag`, `ty-switch`, `ty-radio-group`, `ty-checkbox`, `ty-input`, `ty-select`, `ty-date-picker`, `ty-copy`, `ty-tooltip`, `ty-calendar`); missing tokens degrade to neutral. See [CSS_GUIDE.md → Custom Flavors](./CSS_GUIDE.md#custom-flavors-add-your-own).
131
+
132
+ ---
133
+
134
+ ## Child Elements
135
+
136
+ | Parent | Children | Example |
137
+ |--------|----------|---------|
138
+ | `ty-select` | `<ty-option>` (rich HTML; `label` attr = clean display text) | `<ty-option value="us">US</ty-option>` |
139
+ | `ty-selected-options` | optional `<template>` with `{value}`/`{label}`/`{flavor}`/`{data-*}` placeholders | `<template><ty-tag flavor="{flavor}">{label}</ty-tag></template>` |
140
+
141
+ ---
142
+
143
+ ## Forms and validation
144
+
145
+ Put fields in a real `<form>` and validation needs no code, in any framework. The browser validates before `submit` fires, so React `onSubmit`, Vue `@submit.prevent`, Svelte `on:submit`, htmx `hx-post` and Datastar `data-on:submit__prevent` only run when every field passes.
146
+
147
+ ```html
148
+ <form>
149
+ <ty-input name="email" label="Email" type="email" required></ty-input>
150
+ <ty-select name="robot" label="Robot" required>…</ty-select>
151
+ <ty-date-picker name="day" label="Day" native required></ty-date-picker>
152
+ <ty-button flavor="primary">Send</ty-button>
153
+ </form>
154
+ ```
155
+
156
+ - **Where messages show.** Fields with their own error line: `ty-input`, `ty-textarea`, `ty-select`, `ty-date-picker`, `ty-radio-group`, `ty-file-upload`. The message goes under the field, no browser bubble. `ty-checkbox`, `ty-switch` and `ty-calendar` have none, so the browser shows its bubble.
157
+ - **When.** On a submit, on `reportValidity()` and on `checkValidity()` (the field's or its form's). A field the user edited also shows its message when it loses focus. That message waits until the click or tap that moved focus has finished, so the button below the field doesn't move under the pointer; on touch it shows at most about 1 s after a press that never becomes a click (a long press or a drag). `ty-select` shows it as soon as a user change leaves it empty. `ty-date-picker` shows it after a user change (pick, clear, time edit); an untouched picker shows nothing on blur, by design. A shown message clears as soon as the value is valid. For a check that shows nothing, read `field.validity.valid` or `form.matches(':invalid')`.
158
+ - **Focus.** A submit button click, Enter in a single-line field, `form.requestSubmit()` and `form.reportValidity()` focus the first invalid field in form order, like a native form, also when error-line fields and bubble fields (`ty-checkbox`, `ty-switch`, native inputs) are mixed. Disabled fields and fields that are not shown (`display: none`, `visibility: hidden`, an inactive `ty-wizard` step) are skipped. Only `checkValidity()` never moves focus. Enter in a textarea or contenteditable, or Enter that confirms IME input, is not a submit. Forms inside a shadow root (Lit, Stencil) work the same. Every field's `focus()` reaches its interactive element.
159
+ - **Your own `error`.** Server-side errors go in `error` (Datastar: `data-attr:error="$errors.email"`). Once you set `error`, validation never overwrites or removes it: not on blur, submit or `reportValidity()`, not when the field becomes valid, not on `form.reset()`. The field still blocks the form while a rule fails. Set `error` to `''` to let validation messages show again. With server rendering the server owns `error`: a morph or swap that renders the field without it clears the message, so render it again while the error stands. Messages that validation wrote itself are cleared when the field becomes valid or the form is reset.
160
+ - **Reset.** `form.reset()` restores values from their attributes and clears every message validation wrote (after a submit, a blur after editing, or `reportValidity()`). Fields count as untouched again. Your `error` stays, and `setCustomValidity()` is not cleared, same as native.
161
+ - **Validate without submitting** (a wizard's Next): `form.reportValidity()` or `field.reportValidity()` (needs a ref).
162
+ - **Empty values** submit what native controls do: input, textarea, single select and date picker `name=`, file upload an empty file, unchecked checkbox/switch and unpicked radio group nothing.
163
+
164
+ ---
165
+
166
+ ## Components Reference
167
+
168
+ ### ty-button
169
+
170
+ | Attribute | Type | Default | Description |
171
+ |-----------|------|---------|-------------|
172
+ | `flavor` | string | `'neutral'` | Built-in: `primary` \| `success` \| `danger` \| `warning` \| `neutral`. Append `+` for stronger or `-` for softer shade (e.g. `"primary+"`, `"danger-"`). Any other string is a custom flavor: define `--ty-solid-X`(`-fg/-hover/...`), `--ty-color-X-*`, `--ty-bg-X-soft` tokens and it themes like a built-in (missing tokens fall back to neutral); `--ty-button-*` variables still override per instance. `ty-tag` works the same way via `--ty-bg-X` / `--ty-color-X` / `--ty-border-X`. |
173
+ | `appearance` | string | `'solid'` | `solid` (saturated brand fill) \| `outlined` (transparent bg, text === border) \| `ghost` (text only with hover bg) |
174
+ | `size` | string | `'sm'` | `xs` \| `sm` \| `md` \| `lg` \| `xl` — 24/28/32/36/40px |
175
+ | `type` | string | `'submit'` | `button` \| `submit` \| `reset` |
176
+ | `name` / `value` | string | - | Sent with the form only when this button submits it |
177
+ | `form` | string | - | `id` of the form to submit or reset when the button sits outside it |
178
+ | `disabled` | boolean | `false` | Also set by an ancestor `<fieldset disabled>`; the host then matches `:disabled` (its own `disabled` property doesn't change) |
179
+ | `loading` | boolean | `false` | Spinner, width kept, clicks blocked, `aria-busy` + `aria-disabled`; stays focusable |
180
+ | `pill` | boolean | `false` | Rounded ends. A round icon-only button is `action pill`; a plain `pill` with only an icon is not made round |
181
+ | `action` | boolean | `false` | Square icon-only button |
182
+ | `wide` | boolean | `false` | Fills a flex row; keeps its rung height |
183
+ | `muted` | boolean | `false` | Desaturates the flavor to neutral at rest; reveals real color on hover (pointer only, gated via `(hover: hover)`) and on `:active`/`:focus-visible` so touch still gets it on tap. Works across all three appearances and respects `+`/`-` tone. |
184
+
185
+ **Slots:** `start`, (default), `end` | **Events:** `click` -> `{ originalEvent }`, cancelable
186
+
187
+ **Clicks and forms:** `click` fires once per press, before the default action, for bubbling listeners (React `onClick`). `preventDefault()` cancels the submit/reset, as with a native button. A submit goes through `form.requestSubmit()`, so validation runs and the form's `submit` event is the browser's own. No `click` while disabled, loading or inside a disabled fieldset. Capture-phase listeners above the button also see the browser's native click on the way in, so put button logic in bubbling listeners. `tyButton.click()`, a wrapping `<label>` and Testing Library `fireEvent.click(tyButton)` act like a real press: `click`, then submit/reset. Enter in a `ty-input` doesn't submit through a loading or disabled button; a native `<input>` in the same form follows the browser's own implicit submission, which doesn't see `ty-button`.
188
+
189
+ To show a spinner while saving, set `loading` in the click handler: that press still submits, and later presses are blocked until you clear `loading`.
190
+
191
+ **Sizing:** buttons run a 24-40px 4px ladder, sharing its top three steps with the fields' 32/36/40px ladder. Pairing with a field: **alongside** in a row, field `sm`/`md`/`lg` match button `md`/`lg`/`xl` exactly (32/36/40); **embedded** in a field's `end` slot, use the **same** size name — it nests with a consistent ~4px margin. See [CSS_GUIDE.md → Component Sizing](./CSS_GUIDE.md#component-sizing).
192
+
193
+ **Custom colors:** override per button with `--ty-button-bg`, `--ty-button-bg-hover`, `--ty-button-color`, `--ty-button-border`. See [CSS_GUIDE.md → Per-Component Color Overrides](./CSS_GUIDE.md#per-component-color-overrides).
194
+
195
+ **Custom sizing.** The control (the `<button>` inside the shadow root) fills
196
+ whatever box the host gets: `width`, `height` or `min-height` on `ty-button`, a
197
+ flex column or a grid cell stretching it. So a button that is a direct child of
198
+ a flex column spans its full width; add `align-self: start` (Tailwind
199
+ `self-start`) to keep it at its label width. Exceptions:
200
+
201
+ - A flex or grid **row** doesn't stretch it to a taller neighbor. To opt in,
202
+ set `height: auto` on the host (Tailwind `h-auto`).
203
+ - A `wide` button keeps its rung height, element included, also in a flex
204
+ column with room to spare. A height on it or on its `::part(button)` is
205
+ ignored; make it taller with `size` or the dials below.
206
+ - An `action` button stays square: a height or a width alone gives a bigger
207
+ square.
208
+
209
+ To change the rung itself, use the size dials:
210
+
211
+ ```css
212
+ ty-button.tap {
213
+ --ty-button-height: 44px; /* control height (24/28/32/36/40 by rung) */
214
+ --ty-button-min-width: 0; /* default 4rem; ignored by [action] */
215
+ --ty-button-pad-x: 12px;
216
+ --ty-button-pad-y: 0;
217
+ --ty-button-font: 0.875rem;
218
+ --ty-button-leading: 20px;
219
+ --ty-button-tracking: 0;
220
+ --ty-button-gap: 8px;
221
+ --ty-button-action-size: 44px; /* [action] square box */
222
+ --ty-button-action-icon: 20px; /* icon inside it */
223
+ }
224
+ ```
225
+
226
+ `::part(button)` reaches the control for anything the dials don't cover. Leave
227
+ its `min-height` alone: that is how the control fills a taller host, so
228
+ `::part(button) { min-height: 44px }` leaves a dead strip under the control in
229
+ a host taller than 44px. A `::part(button)` height below the rung is raised to
230
+ the rung; use `--ty-button-height` to go smaller.
231
+
232
+ > **Touch targets:** the ladder tops out at 40px, below iOS's 44pt and
233
+ > Material's 48dp. Phone-facing UIs should raise `xs`/`sm` themselves —
234
+ > `--ty-button-height` under a `(pointer: coarse)` media query is the
235
+ > straightforward way — and give the fields beside them the same floor via
236
+ > `--ty-field-height`, or rows stop sitting flush.
237
+
238
+ ---
239
+
240
+ ### ty-input
241
+
242
+ | Attribute | Type | Default | Description |
243
+ |-----------|------|---------|-------------|
244
+ | `type` | string | `'text'` | `text` \| `email` \| `password` \| `number` \| `tel` \| `url` \| `currency` \| `percent` \| `compact` |
245
+ | `value` | string | `''` | |
246
+ | `name` | string | - | Form name |
247
+ | `placeholder` | string | - | |
248
+ | `label` | string | - | Built-in label |
249
+ | `error` | string | - | Message under the field; `''` clears it. While it is set, the field looks like `flavor="danger"` on a red tint, whatever its flavor. When it clears, your flavor's look comes back. `flavor` keeps what you set, so `[flavor="danger"]` doesn't match a field that only has an error |
250
+ | `disabled` | boolean | `false` | |
251
+ | `required` | boolean | `false` | |
252
+ | `pattern` | string | | Regex the whole value must match (text types) → `patternMismatch` |
253
+ | `minlength` / `maxlength` | number | | Character limits (text types) → `tooShort` / `tooLong`; typing stops at `maxlength` |
254
+ | `min` / `max` | number | | Numeric bounds for `number`, `currency`, `percent`, `compact` → `rangeUnderflow` / `rangeOverflow` |
255
+ | `too-short-message` / `too-long-message` | string | | Wording for the length messages; `{minlength}` `{maxlength}` `{length}` are filled in. Without it, too-short is the browser's own (localized) for typed text, like every other message |
256
+ | `size` | string | `'sm'` | `xs` \| `sm` \| `md` \| `lg` \| `xl` — 28/32/36/40/44px, shared by every field. In a row with a button: field `md` + button `lg` (36). See [CSS_GUIDE.md → Component Sizing](./CSS_GUIDE.md#component-sizing) |
257
+ | `flavor` | string | `'neutral'` | Built-ins, `+`/`-` shades, or a custom flavor from `--ty-color-X` tokens. Colors the border + focus ring; per-instance override via `--input-accent` / `--input-accent-bold` / `--input-ring`. |
258
+ | `currency` | string | `'USD'` | ISO 4217 code (for `type="currency"`) |
259
+ | `locale` | string | `'en-US'` | Locale for numeric formatting |
260
+ | `precision` | number | - | Decimal places |
261
+ | `debounce` | number | `0` | Debounce ms (0-5000) |
262
+
263
+ **Slots:** `start`, `end` | **Events:** `input`, `change` -> `{ value, formattedValue, rawValue, originalEvent }` | `focus`, `blur`
264
+
265
+ **Forms and validation:** the rules above block the form and show their message under the field, with no code. See [Forms and validation](#forms-and-validation).
266
+
267
+ **Password reveal:** `type="password"` renders a built-in eye toggle after the end slot — toggles visibility of the typed value (native input type only; component `type` and form value unchanged).
268
+
269
+ **Custom colors:** override per input with `--ty-input-bg`, `--ty-input-color`, `--ty-input-border`, `--ty-input-border-hover`, `--ty-input-border-focus`, `--ty-input-shadow-focus`. See [CSS_GUIDE.md → Per-Component Color Overrides](./CSS_GUIDE.md#per-component-color-overrides).
270
+
271
+ ---
272
+
273
+ ### ty-checkbox
274
+
275
+ | Attribute | Type | Default | Description |
276
+ |-----------|------|---------|-------------|
277
+ | `checked` | boolean | `false` | |
278
+ | `indeterminate` | boolean | `false` | Mixed state (dash); clicking resolves to checked |
279
+ | `value` | string | `'on'` | Form value when checked |
280
+ | `name` | string | - | |
281
+ | `disabled` | boolean | `false` | |
282
+ | `required` | boolean | `false` | Unchecked blocks submit; the browser shows its own bubble |
283
+ | `size` | string | `'sm'` | `xs` \| `sm` \| `md` \| `lg` \| `xl` |
284
+ | `flavor` | string | `'neutral'` | Built-ins, `+`/`-` shades, or a custom flavor from `--ty-color-X` tokens. Per-instance override via `--checkbox-color` / `--checkbox-color-off`. |
285
+
286
+ **Slots:** none | **Events:** `input`, `change` -> `{ value, checked, formValue, originalEvent }`
287
+
288
+ Just the box: no label text, no error line. Wrap it in a `<label>`, so the whole line toggles it and names it for screen readers.
289
+
290
+ ```html
291
+ <label><ty-checkbox name="terms" required></ty-checkbox> Accept the terms</label>
292
+ ```
293
+
294
+ ---
295
+
296
+ ### ty-textarea
297
+
298
+ | Attribute | Type | Default | Description |
299
+ |-----------|------|---------|-------------|
300
+ | `value` | string | `''` | |
301
+ | `name` | string | - | |
302
+ | `placeholder` | string | - | |
303
+ | `label` | string | - | |
304
+ | `error` | string | - | |
305
+ | `disabled` | boolean | `false` | |
306
+ | `required` | boolean | `false` | |
307
+ | `minlength` / `maxlength` | number | - | Character limits → `tooShort` / `tooLong`; typing stops at `maxlength`. An empty value only fails `required` |
308
+ | `too-short-message` / `too-long-message` | string | - | Wording for the length messages; `{minlength}` `{maxlength}` `{length}` are filled in. Defaults: "Use at least {minlength} characters (now {length})" / "Use at most {maxlength} characters (now {length})". After the user types, too-short is the browser's own unless `too-short-message` is set |
309
+ | `size` | string | `'sm'` | `xs` \| `sm` \| `md` \| `lg` \| `xl` — text size and padding follow the field ladder |
310
+ | `rows` | string | `'3'` | |
311
+ | `resize` | string | `'none'` | `none` \| `both` \| `horizontal` \| `vertical` |
312
+ | `min-height` | string | - | |
313
+ | `max-height` | string | - | |
314
+
315
+ **Properties:** `minLength` / `maxLength` (number, `-1` when unset; a negative value removes the rule), `tooShortMessage`, `tooLongMessage`.
316
+
317
+ **Events:** `input`, `change` -> `{ value, originalEvent }`. `input` fires once per edit; `change` on blur, if the value changed, like native.
318
+
319
+ ```html
320
+ <ty-textarea name="bio" label="Bio" minlength="20" maxlength="500"
321
+ too-short-message="At least {minlength} characters ({length} so far)"></ty-textarea>
322
+ ```
323
+
324
+ ---
325
+
326
+ ### ty-copy
327
+
328
+ Also registered as **`ty-copy-field`** — same element, descriptive name.
329
+
330
+ | Attribute | Type | Default | Description |
331
+ |-----------|------|---------|-------------|
332
+ | `value` | string | - | Text to copy |
333
+ | `label` | string | - | |
334
+ | `format` | string | `'text'` | `text` \| `code` |
335
+ | `multiline` | boolean | `false` | Wrap and show the full value instead of one ellipsized line. Scrolls vertically past 200px; the copy button pins to the top-right. |
336
+ | `horizontal-scroll` | boolean | `false` | Scroll long content sideways instead of clipping with an ellipsis. Combine with `multiline` for code blocks that keep their line breaks and scroll on both axes. |
337
+ | `flavor` | string | `'neutral'` | Built-ins, `+`/`-` shades, or a custom flavor. Colors the copy button + hover tint; per-instance override via `--copy-color` / `--copy-color-hover` / `--copy-bg-hover`. |
338
+ | `disabled` | boolean | `false` | |
339
+
340
+ **The default is one ellipsized line** — ty-copy is a compact field, so a long
341
+ value is clipped rather than allowed to grow the layout. Opt into `multiline`
342
+ or `horizontal-scroll` when the whole value has to be readable.
343
+
344
+ The copy button is icon-only and carries `aria-label`, updated live through its states: "Copy to clipboard" → "Copied!" / "Copy failed" → back.
345
+
346
+ ---
347
+
348
+ ### ty-file-upload
349
+
350
+ Drop zone + file picker. Click to browse or drag-and-drop. Form-associated — selected files appear in `FormData` on submit.
351
+
352
+ | Attribute | Type | Default | Description |
353
+ |-----------|------|---------|-------------|
354
+ | `name` | string | - | FormData key |
355
+ | `multiple` | boolean | `false` | Allow more than one file |
356
+ | `accept` | string | - | File-type filter (`image/*`, `.pdf,.docx`, etc.) |
357
+ | `label` | string | - | |
358
+ | `placeholder` | string | `'Drop files here or click to browse'` | Hint inside the drop zone, shown as plain text |
359
+ | `disabled` | boolean | `false` | |
360
+ | `required` | boolean | `false` | |
361
+ | `error` | string | - | Validation message + danger border |
362
+
363
+ **Properties:** `files` (read-only `File[]`)
364
+
365
+ **Events:** `change` -> `{ value: File[], files: File[], names: string[] }` — fires on browse, drop, and remove (including when last file is removed → empty array)
366
+
367
+ **Form integration:** files appear under the `name` attribute as multiple `FormData` entries; `form.reset()` clears the selection.
368
+
369
+ ---
370
+
371
+ ### ty-select
372
+
373
+ THE select control. Single select by default with a form-field look matching `ty-input`; `multiple` for multi-select. Built for lists up to about 20–30 options (the search row appears above 7). Longer or remote lists: `external-search`. Hundreds of picks: `external-selection`.
374
+
375
+ | Attribute | Type | Default | Description |
376
+ |-----------|------|---------|-------------|
377
+ | `multiple` | boolean | `false` | Multi select (native `<select multiple>` semantics). Absent = single: picking replaces the selection and closes the popup |
378
+ | `compact` | boolean | `false` | Content-hugging trigger for toolbars/filter bars instead of the full-width field. Single shows the selected label; multiple shows placeholder + count badge |
379
+ | `value` | string | `''` | The selection, and the only way to set it; comma-separated in pick order when multiple (arrays accepted from frameworks). The select keeps the attribute on the current selection. `<ty-option selected>` selects nothing |
380
+ | `name` | string | - | Single submits one FormData entry; multiple submits repeated `name=` entries |
381
+ | `label` | string | - | |
382
+ | `placeholder` | string | `'Select...'` | Shown while empty; selection shows the option itself (single) or joined labels (multiple) |
383
+ | `selected-label` | string | `'Selected'` | Mobile dialog only: heading of the pinned selection strip; the count is appended (`Selected (3)`) |
384
+ | `available-label` | string | `'Available'` | Mobile dialog only: heading of the option list; counts what's still on offer (excludes selected, `hidden` and searched-out options) |
385
+ | `not-searchable` | boolean | `false` | Drop the popup search row. A select is searchable by default; this is the single opt-out — bare presence attribute, like `disabled`. Can't override `external-search`/`allow-create`, where the input is the only way to type a query |
386
+ | `external-search` | boolean | `false` | Delegate filtering: emits debounced `search` events; replace the option children in response. Labels come from the options present, so the app keeps the picked ones in the list (`hidden` if they aren't results) |
387
+ | `external-selection` | boolean | `false` | The app holds the selection — see below |
388
+ | `allow-create` | boolean | `false` | Enter on unmatched search text mints a new `<ty-option>` and selects it. Exact match (value or label, case-insensitive) selects the existing option instead of duplicating. Single: replaces selection, closes. Multiple: appends, clears search, stays open (tags-input pattern). Fires the cancelable `create` event first — see below |
389
+ | `create-transform` | string | `'none'` | `'slug'`: normalizes the **value** allow-create mints (lowercase, spaces → `_`, strips non-alphanumeric). The display label is always kept verbatim regardless |
390
+ | `debounce` | number | `0` | Search event debounce (0-5000ms) |
391
+ | `loading` | boolean | `false` | Spinner in the options area (external search in flight) |
392
+ | `disabled` / `readonly` / `required` | boolean | `false` | |
393
+ | `error` | string | `''` | Message under the field; `''` clears it. While it is set, the select looks the same as `ty-input` with an `error`. Validation also writes it (submit, `reportValidity()`, `checkValidity()`) and clears it once the select is valid |
394
+ | `size` | string | `'sm'` | `xs` \| `sm` \| `md` \| `lg` \| `xl` — the field ladder shared with `ty-input`/`ty-date-picker`, 28/32/36/40/44px; see [CSS_GUIDE.md → Component Sizing](./CSS_GUIDE.md#component-sizing) |
395
+ | `placement` | string | - | Where the list opens: `bottom` / `top`, optionally `-start` / `-end` (`bottom-end`, …). Unset: below when it fits, else the side with more room, start-aligned. Flips rather than clips. `left-*`/`right-*` keep their alignment but leave the side automatic. See [Placement](#placement). Width: at least 320px or the trigger's; `--ty-select-popup-width` sets it |
396
+ | `no-clear` | boolean | `false` | No built-in × clear button. Normally it sits in the default/compact trigger, shown once something is selected. Not shown with `slot="trigger"` (lives in the slot's fallback content, same mechanism that already hides the chevron there) — call the `clear()` method instead. Suppressed while `disabled`/`readonly`. |
397
+ | `flavor` | string | `'neutral'` | Built-ins, `+`/`-` shades, or a custom flavor from `--ty-color-X` tokens. Colors the field border + hover, and adds a focus ring while the dropdown is open; per-instance override via `--select-accent` / `--select-accent-bold` / `--select-ring`. |
398
+
399
+ **Children:** `<ty-option>` only (`<ty-tag>` is not an option) — supports rich HTML content; a `label` attribute (native `<option label>` semantics) provides clean display text for summaries/chips; `data-*` attributes feed `ty-selected-options` templates.
400
+
401
+ **Trigger:** a closed single select shows the selected option itself (rich HTML and your page CSS intact — icons, prices, flags); nothing is added to its children, so React hydration and Replicant diffing see exactly what they rendered. A closed multiple select shows the labels, comma-joined (`compact`: placeholder + count); give rich options a `label` so this reads clean. Open, the trigger shows the placeholder; the list shows the picks.
402
+
403
+ **Methods:** `clear()` — empties the entire selection and fires `change` (`action: 'clear'`); no-op if nothing is selected. It shows no validation message, so it's safe for resetting a form in code (the built-in × does show it). Works regardless of `no-clear`/skin, so `slot="trigger"` consumers can wire their own clear icon's click handler to it directly. `deselectValue(value)` — removes one value and fires `change` (`action: 'remove'`); used internally by `ty-selected-options` chip dismissal.
404
+
405
+ **Slots:** `start` / `end` (adornments), `trigger` (replaces field/compact chrome entirely; behavior/form/ARIA stay), `loading` | **Events:** `change` -> `{ value, values, items: [{value,label,flavor}], action, item }` (`value` scalar for single, array for multiple; `values` in pick order; `action` is `'set' | 'add' | 'remove' | 'clear' | 'create'` — `'clear'` from the clear button or `clear()`, `'create'` when allow-create minted the option) | `search` -> `{ query, element }` | `open` / `close` | `create` -> `{ value, label }` — **cancelable**: mutate `detail.value` to change the id that gets created (e.g. slugify it yourself), or `preventDefault()` to create the option yourself (e.g. after a server round-trip)
406
+
407
+ **Companion:** `<ty-selected-options for="id">` renders the selection as dismissible chips anywhere in the layout. Each chip is the option's own content (a rich option makes a rich chip); `label` on the option makes it plain text. Optional `<template>` child with `{value}` `{label}` `{flavor}` `{data-*}` placeholders for custom chip markup. It follows the select's `value` attribute, `change`, and options added or renamed (options that arrive after the value relabel the chips). It binds to its `for` select when it connects: if a swap replaces the select (htmx `outerHTML`, a remount), swap the chips with it, or morph instead, which keeps the same select. Not for `external-selection`. Also registered as **`ty-selected-tags`** — original tag name, kept working indefinitely.
408
+
409
+ **Server rendering / morph:** the select writes no selection state onto its options; the check and `aria-selected` come from `option.checked`, a property it sets. A server morph (Datastar `patch-elements`, htmx idiomorph) does what the server renders: a different `value` wins, the same one changes nothing, none means no selection. A server that re-renders a select renders `value="…"` with the current selection.
410
+
411
+ **External selection:** with `external-selection` the app owns the selection, for hundreds or thousands of selected values or a remote list; usually paired with `external-search`. The app marks the options it shows `selected` (attribute, or the `option.selected` property). A pick fires `change` with `{ value, selected, action, item, values: [], items: [] }` — `value` is the picked option, `selected` its requested state, `action` `'add' | 'remove'` (`'set'` for single) — and changes nothing; the app re-renders the marks. `.value` is `''`, nothing is submitted to the form and `required` is not enforced, so the app submits and summarizes the selection itself.
412
+
413
+ ```html
414
+ <ty-select multiple external-selection external-search>
415
+ <ty-option value="r1" selected>Rob Roy</ty-option>
416
+ <ty-option value="r2">Aerobot</ty-option>
417
+ </ty-select>
418
+ ```
419
+
420
+ **Full keyboard + ARIA combobox pattern:** the field is in the tab order (`tabindex="0"`; `-1` when `disabled`) and carries `role="combobox"` / `aria-haspopup="listbox"` / `aria-expanded` / `aria-controls` (the popup's `role="listbox"`, `aria-multiselectable` when `multiple`) / `aria-labelledby` (when `label` is set — the visible label text, programmatically associated, not just nearby). Each `<ty-option>` has `role="option"` (its own attribute) and a live `aria-selected` from its internals. `Enter`/`Space`/`ArrowDown` open the closed, focused field — not just a mouse click. With an `error` set, the combobox has `aria-invalid="true"` and `aria-describedby` pointing at the error line. `focus()` on a disabled select does nothing. The list's keys work inside `ty-popup` and `ty-modal`; Escape closes the list and returns focus to the select.
421
+
422
+ **In a form, no JS needed:**
423
+
424
+ ```html
425
+ <form>
426
+ <ty-select name="robot" label="Robot" required>…</ty-select>
427
+ <button>Send</button>
428
+ </form>
429
+ ```
430
+
431
+ On Send, the browser's message for a native `<select>` appears under the field and the trigger takes focus. A user change that leaves it empty shows the message at once; setting the value in code does not.
432
+
433
+ **Error line under a custom trigger:** compact and `slot="trigger"` selects show the error line under the trigger. It wraps at a readable width (about 20em), can extend past a narrow trigger, and doesn't widen the host; under a slotted trigger it starts at the trigger's left edge. A slotted trigger keeps its own look (no danger border) and gets `aria-invalid="true"` plus `aria-description` holding the message, both removed when the error clears. Focus from validation lands on the slotted trigger; when the trigger can't take focus (a `<span>`), on the select's own field.
434
+
435
+ **Custom colors:** uses the shared `--ty-input-*` variable family — override per select with `--ty-input-bg`, `--ty-input-border`, `--ty-input-border-focus`, `--ty-input-shadow-focus`, etc. See [CSS_GUIDE.md → Per-Component Color Overrides](./CSS_GUIDE.md#per-component-color-overrides).
436
+
437
+ ---
438
+
439
+ ### ty-option
440
+
441
+ Rich HTML option for `<ty-select>`. Attrs: `value`, `label` (clean display text — native `<option label>` semantics), `disabled`, `hidden` (not offered: left out of the list, the arrow keys and the search, but it can still be the value, like `<option hidden>`), `selected` (the app's mark, read only with `external-selection`; otherwise the select's `value` decides). The `checked` property, set by the select, draws the check and `aria-selected`. The select sets `highlighted` and `filtered-out` (left out by the search) itself. Default slot for content; `data-*` attributes feed `ty-selected-options` chip templates.
442
+
443
+ ---
444
+
445
+ ### ty-tag
446
+
447
+ The pill/**chip** component (Material's "chip" == Tyrell's tag).
448
+
449
+ | Attribute | Type | Default | Description |
450
+ |-----------|------|---------|-------------|
451
+ | `flavor` | string | `'neutral'` | Built-ins plus `+`/`-` shades, same as ty-button. Custom flavor `X` themes from `--ty-bg-X` / `--ty-color-X` / `--ty-border-X` tokens; `ty-tag[flavor="X"] { --tag-bg: ...; --tag-color: ...; --tag-border-color: ...; }` still overrides. |
452
+ | `size` | string | `'sm'` | `xs` \| `sm` \| `md` \| `lg` \| `xl` — 20/24/28/32/36px. Beside a button or field, match heights: tag `lg` = button `md` = field `sm` (32), tag `xl` = button `lg` = field `md` (36) |
453
+ | `value` | string | - | |
454
+ | `no-pill` | boolean | `false` | Square corners instead of fully rounded |
455
+ | `clickable` | boolean | `false` | |
456
+ | `dismissible` | boolean | `false` | |
457
+ | `disabled` | boolean | `false` | |
458
+
459
+ **Slots:** `start`, (default), `end` | **Events:** `click`, `dismiss`
460
+
461
+ **Layout:** a tag hugs its content in block flow, flex columns and grid cells. Give it a width (`w-full`) to stretch it.
462
+
463
+ ---
464
+
465
+ ### ty-tabs / ty-tab
466
+
467
+ **ty-tabs:** `width` (default `'100%'`), `height` (required), `active` (tab id), `placement` (`top` | `bottom`), `fixed` (presence boolean)
468
+
469
+ By default tabs are **scrollable**: each button keeps its natural width (floored at `min-width: 72px` via `--ty-tab-min-width`) and never squeezes — the bar scrolls instead, with a `…` jump menu, once they no longer fit. `fixed` divides the bar equally between the tabs instead: no floor, no overflow, no jump menu, labels ellipsize if squeezed.
470
+
471
+ **Use `fixed` for 2–5 tabs.** Equal shares only read as tabs while each share fits its label — split a bar between 17 and every one becomes an ellipsis. Rough check: if *widest label × tab count* exceeds the narrowest width you support, stay on the scrollable default and let the `…` menu carry the rest. Keep it off for open-ended or user-generated tab sets.
472
+
473
+ **ty-tab:** `id` (required), `label` (required), `lazy` (presence boolean)
474
+
475
+ **Slots:** `label-{id}` (rich label), `marker` (active indicator); on a lazy `ty-tab`: `loading`, `error`
476
+
477
+ **Events:** `ty-tab-change` -> `{ activeId, activeIndex, previousId, previousIndex }`; `ty-tab-load` -> `{ id, index }` (fired on the ty-tab, doesn't bubble)
478
+
479
+ **ARIA:** full tab pattern — `role="tablist"` / `role="tab"` (+ `aria-selected`) on the buttons; each `<ty-tab>`'s panel is a `tabpanel` named after its label. Role and name sit inside the ty-tab's shadow root, not on the element, so a server morph can't strip them; hidden panels are `inert`. No `aria-controls` / `aria-labelledby`: buttons live in shadow DOM, panels in light DOM, and ARIA id-references don't cross that boundary.
480
+
481
+ **Server morphs (Datastar, htmx/idiomorph):** re-rendering `ty-tabs` keeps the shown tab, size and panel visibility — no `data-preserve-attr` needed. `active` is a request: a morph that sends a different `active` switches to it (and fires `ty-tab-change`); one that omits it keeps the current tab. Read the shown tab from the `activeTab` property.
482
+
483
+ **Lazy tabs:** a `lazy` ty-tab with no content fires `ty-tab-load` when it's shown, after `ty-tab-change`. The event doesn't bubble, so a lazy tab nested in another one never triggers the outer tab's listener; listen on the tab, or on `ty-tabs` with `{ capture: true }`. The tab shown first never fires: render its content with the page. Until content arrives the tab shows a spinner (`setLoaderSvg()` changes it) or your `slot="loading"`, fading in after 150ms so fast loads don't flash it; the panel is `aria-busy`. Switching away and back while it loads doesn't fire again. If loading fails, call `tab.loadFailed()`: the tab shows `slot="error"` (default "Couldn't load.") and a Retry button (`::part(retry)`). Retry, or showing the tab again, fires `ty-tab-load` once more. ty-tab doesn't watch htmx or Datastar requests: report failures yourself. Content that goes away again (a morph with the server's empty tab) loads again: at once if the tab is shown, otherwise when it's next shown.
484
+
485
+ ```html
486
+ <ty-tab id="reports" label="Reports" lazy>
487
+ <div slot="loading">Loading reports…</div> <!-- optional -->
488
+ <span slot="error">Couldn't load reports.</span> <!-- optional -->
489
+ </ty-tab>
490
+ <script>
491
+ tabs.addEventListener('ty-tab-load', async (e) => {
492
+ const res = await fetch(`/tabs/${e.detail.id}`).catch(() => null);
493
+ if (res?.ok) e.target.innerHTML = await res.text();
494
+ else e.target.loadFailed();
495
+ }, { capture: true });
496
+ </script>
497
+ ```
498
+
499
+ ```html
500
+ <ty-tabs height="400px" active="overview">
501
+ <span slot="label-overview" class="flex items-center gap-2">
502
+ <ty-icon name="layout-dashboard" size="sm"></ty-icon>
503
+ Overview
504
+ </span>
505
+ <ty-tab id="overview" label="Overview">Content here</ty-tab>
506
+ <ty-tab id="details" label="Details">Details here</ty-tab>
507
+ </ty-tabs>
508
+ ```
509
+
510
+ **CSS Variables:**
511
+
512
+ ```css
513
+ --ty-tab-min-width /* 72px — scrollable tab button floor; ignored by `fixed` */
514
+ --ty-tabs-separator /* line between bar and panel; transparent removes it */
515
+ --ty-tabs-transition-duration /* marker glide + carousel slide 300ms, panel fade 400ms; setting it applies to all three */
516
+ --ty-tabs-transition-easing /* ease-in-out */
517
+ ```
518
+
519
+ ---
520
+
521
+ ### ty-wizard / ty-step
522
+
523
+ **ty-wizard:** `width`, `height` (required), `active` (step id), `completed` (comma-separated ids), `orientation` (`horizontal` | default)
524
+
525
+ **ty-step:** `id` (required), `label` (required)
526
+
527
+ **Slots:** `indicator-{id}` (custom step indicator)
528
+
529
+ **Events:** `ty-wizard-step-change` -> `{ activeId, activeIndex, previousId, previousIndex, direction }`
530
+
531
+ **ARIA:** same tab pattern as `ty-tabs` — step indicators are `role="tab"` inside a dedicated `role="tablist"` (kept separate from the progress line, which is its own `role="progressbar"` with an `aria-label` — a `tablist` may only contain tabs), each `<ty-step>` is `role="tabpanel"` + `aria-labelledby` + `tabindex="0"`.
532
+
533
+ ---
534
+
535
+ ### ty-calendar
536
+
537
+ Attrs: `value` (sets selection *and* the displayed month; reflects to `year`/`month`/`day`. Reads what `ty-date-picker` reads: `YYYY-MM-DD`, `YYYY-MM-DDTHH:mm[:ss]`, an ISO instant with `Z`/offset, and as a property epoch ms or a `Date`; an instant is its local day. The value, `change` and form value are always `YYYY-MM-DD`, so `calendar.value = picker.value` needs no conversion), `year`, `month`, `day`, `name`, `required` (empty blocks the form), `min`, `max` (`YYYY-MM-DD` or an instant's local day — out-of-bounds days disabled, navigation clamped), `flavor` (default `'primary'` — built-ins, `+`/`-` shades, or a custom flavor; colors the selected/today day in the nested `ty-calendar-month`, navigation stays neutral chrome), `locale` (day and month names; unset, the nearest `lang`, then the browser's language). Property: `dayContentFn`.
538
+
539
+ **Events:** `change` -> `{ year, month, day, action, source, dayContext }` | `navigate` -> `{ month, year, action, source }`
540
+
541
+ **Form value:** ISO date `YYYY-MM-DD`. On a submit that `required`, `min` or `max` fails, the day grid takes the focus and the browser shows its bubble there.
542
+
543
+ **Keyboard + ARIA:** the day grid (in the nested `ty-calendar-month`) is a real WAI-ARIA grid — `role="grid"`/`row`/`columnheader`/`gridcell`, with roving `tabindex` (exactly one day is in the tab order at a time; arrow keys move it — `←`/`→` by a day, `↑`/`↓` by a week — and `Enter`/`Space` select; focus stays on the picked day). Disabled (out-of-`min`/`max`) days are excluded from the roving set. Each day's `aria-label` is a full readable date (e.g. "Wednesday, July 15, 2026"), not just the visible number.
544
+
545
+ ---
546
+
547
+ ### ty-date-picker
548
+
549
+ | Attribute | Type | Default | Description |
550
+ |-----------|------|---------|-------------|
551
+ | `value` | string | - | Reads `YYYY-MM-DD` (that day), `YYYY-MM-DDTHH:mm[:ss]` (local wall-clock, kept as written) or an ISO instant with `Z`/offset (its local day and time). The property also takes a `Date` or epoch milliseconds. Holds what the form submits (see Form value); `null` when empty |
552
+ | `name` | string | - | |
553
+ | `label` | string | - | |
554
+ | `placeholder` | string | - | |
555
+ | `error` | string | - | Message under the field. While it is set, the picker looks the same as `ty-input` with an `error`, and its calendar opens in danger. Validation messages (`required`) show here |
556
+ | `with-time` | boolean | `false` | Hours and minutes under the calendar; the value includes the time. Turning it on or off keeps the picked day and time and rewrites the value in the new shape |
557
+ | `native` | boolean | `false` | Submit wall-clock values like `<input type="date">` / `<input type="datetime-local">`: `2026-10-16`, or `2026-10-16T14:30` with `with-time` (seconds only when they're not zero), instead of a UTC instant |
558
+ | `min` | string | - | Earliest selectable date (ISO `YYYY-MM-DD`) |
559
+ | `max` | string | - | Latest selectable date (ISO `YYYY-MM-DD`) |
560
+ | `disabled` | boolean | `false` | |
561
+ | `required` | boolean | `false` | |
562
+ | `locale` | string | `'en-US'` | |
563
+ | `size` | string | `'sm'` | `xs` \| `sm` \| `md` \| `lg` \| `xl` — the field ladder, 28/32/36/40/44px; see [CSS_GUIDE.md → Component Sizing](./CSS_GUIDE.md#component-sizing) |
564
+ | `placement` | string | - | Calendar popup side + cross-axis alignment — `bottom-start`, `top-end`, … See [Placement](#placement). Vertical-only: `left-*`/`right-*` keep their alignment but leave the side automatic |
565
+ | `no-clear` | boolean | `false` | No built-in × clear button. Normally it shows in the stub once a date is selected, except while `disabled`. |
566
+ | `flavor` | string | `'default'` | Built-ins, `+`/`-` shades, or a custom flavor. Colors the stub border + focus ring (override via `--date-picker-accent` / `--date-picker-accent-bold` / `--date-picker-ring`) and the popup calendar's selected/today day (forwarded to the nested `ty-calendar`). |
567
+
568
+ **Methods:** `clear()` — clears the value programmatically and fires `change` (`detail.source: 'clear'`); works regardless of `no-clear`, for any external trigger that wants to clear the field without the built-in button.
569
+
570
+ **Events:** `change` -> `{ value, localValue, milliseconds, formatted, source }` (`source` is `'selection' | 'time-change' | 'clear' | 'external'`). `value` is what the form submits. `localValue` is local wall-clock (`YYYY-MM-DD`, or `YYYY-MM-DDTHH:mm` with time). `milliseconds` is epoch ms (date-only: when the day starts locally).
571
+
572
+ **Form value**, by default a UTC ISO instant. With `with-time`, the picked moment (`2026-10-16T12:30:00.000Z` for 14:30 in Zagreb). Date-only, the moment the picked day starts in the browser's timezone (Oct 16 in Zagreb → `2026-10-15T22:00:00.000Z`; Oct 26, after the clocks change, → `2026-10-25T23:00:00.000Z`). With `native`: `2026-10-16` / `2026-10-16T14:30`. Empty: `.value` and `detail.value` are `null`; the form submits `name=` like a native date input (before this release, an empty picker was left out of the form data). `.value`, the form data and `change` `detail.value` are always the same string.
573
+
574
+ ```html
575
+ <ty-date-picker name="day" value="2026-10-16"></ty-date-picker>
576
+ <!-- day=2026-10-15T22:00:00.000Z in Zagreb -->
577
+ <ty-date-picker name="day" native value="2026-10-16"></ty-date-picker>
578
+ <!-- day=2026-10-16 -->
579
+ <ty-date-picker name="at" native with-time value="2026-10-16T14:30"></ty-date-picker>
580
+ <!-- at=2026-10-16T14:30 -->
581
+ ```
582
+
583
+ **Validation:** `required` shows its message in the error line after a user change (pick, clear, time edit), on submit, on `reportValidity()` and on `checkValidity()` (the field's or its form's). An untouched picker shows nothing on blur, by design. See [Forms and validation](#forms-and-validation).
584
+
585
+ **Keyboard + ARIA:** the field is in the tab order (`tabindex="0"`; `-1` when `disabled`) and carries `role="button"` (it's a trigger, not editable text) / `aria-haspopup="dialog"` / `aria-expanded` / `aria-labelledby` (when `label` is set). `Enter`/`Space` open the closed, focused field, not just a mouse click. The popup itself is a native `<dialog>` opened via `showModal()`, so it already gets `role="dialog"` + focus-trap semantics from the browser for free. With `error`, the field is `aria-describedby` the error line. Enter or Space on the focused × clears the value. Focus stays on the field when it redraws (an `error` set or cleared, a new value, a clear), and returns to it after a pick or Escape, also inside `ty-modal`. `focus()` does nothing while disabled.
586
+
587
+ ---
588
+
589
+ ### ty-modal
590
+
591
+ Also registered as **`ty-dialog`** — same element, platform/ARIA name (wraps native `<dialog>`).
592
+
593
+ Attrs: `open`, **`no-backdrop`**, **`no-zoom`**, **`sheet`**, **`prevent-escape`**, **`prevent-outside-click`** (presence booleans — see below). `sheet` makes the modal full screen below 768px, sliding up from the bottom; the panel fills it whatever width it sets itself, and wider screens keep the centered dialog. The `<dialog>` is exposed as `ty-modal::part(dialog)` for anything else (size, position, padding). By default the page body scales down slightly while a modal is open, Vaul-style; the modal itself renders in the top layer and is unaffected. Set `no-zoom` if your app has `position: fixed` chrome, since a scaled body becomes its containing block. `no-backdrop` is still a modal, just without the dim: the page behind isn't usable, a click anywhere outside or Escape closes it, and it never zooms the page. `label` sets `aria-label` on the internal `<dialog>`. `<dialog>` gets `role="dialog"` for free, but nothing names it unless you set this (or wire your own `aria-labelledby` to a slotted heading yourself); unset is not a regression, just unlabeled, same as before.
594
+
595
+ **Guarding the close paths.** Closing on ESC and on backdrop click is the default, so the switches follow the HTML convention of naming the *deviation*, like `disabled`:
596
+
597
+ ```html
598
+ <ty-modal prevent-outside-click>…</ty-modal> <!-- backdrop click does nothing -->
599
+ <ty-modal prevent-escape prevent-outside-click>…</ty-modal> <!-- fully guarded -->
600
+ <ty-modal no-backdrop>…</ty-modal> <!-- no dim, still modal -->
601
+ ```
602
+
603
+ Property mirrors `preventEscape` / `preventOutsideClick` take real booleans (true sets the attribute, false removes it). `prevent-escape` consumes the Escape *keydown*, so the browser's CloseWatcher anti-trap (which force-closes on a second consecutive ESC after one canceled close request) never engages; the Android back gesture deliberately remains force-closable as the last-resort escape hatch.
604
+
605
+ **Accessibility contract:** a fully guarded modal has no built-in ✕ (the ✕ follows the outside-click setting), so **you must render your own keyboard-reachable close control inside it** — otherwise it's a WCAG 2.1.2 keyboard trap in your app. ESC-closing is also the ARIA APG convention; reserve `prevent-escape` for real guards (unsaved changes, payment in flight), and prefer the gentler `beforeclose` + `hide({ force: true })` confirm pattern where a response to ESC is acceptable.
606
+
607
+ Events: `open`, `close`, **`beforeclose`** (cancellable). Listen to `beforeclose` and call `event.preventDefault()` to guard against unsaved-state dismissal. The detail contains `reason: 'programmatic' | 'backdrop' | 'escape' | 'close-button' | 'native'` — `close` reports the same reason. Once your custom confirm UI captures consent, call `.hide({ force: true })` to bypass the event.
608
+
609
+ None of the three bubble, so a modal opened from inside another modal never trips the outer modal's listeners — and neither does a `ty-select` / `ty-date-picker` / `ty-popup` closing its own popup inside the modal. Attach listeners to the element itself.
610
+
611
+ **Popups inside a modal.** A popup opened inside a modal (a `ty-select` list, the `ty-date-picker` calendar, a `ty-popup`, a nested modal) closes first on Escape, and the next Escape closes the modal. With a `ty-select` in a `ty-popup` in a `ty-modal`, Escape closes the list, then the popup, then the modal; escaping a select list returns focus to the select. Closing the modal (`hide()`, removing `open`, removing it from the page) closes any popup still open inside it, also in content a wrapper component slots into the modal; their `aria-expanded` and scroll lock update at once. A nested `ty-modal`, with or without a backdrop, also closes when the outer one closes natively; it fires its own `close` with reason `'programmatic'` and releases its scroll lock. A modal removed with `open` still set and put back (a framework moving it) opens again as it was, without `close` or `open` events.
612
+
613
+ **Methods:** `show()`, `hide()` | **Events:** `close` -> `{ reason, returnValue? }`
614
+
615
+ Always render modals in DOM. Control with `open` attribute or `show()`/`hide()`.
616
+
617
+ ---
618
+
619
+ ### ty-tooltip
620
+
621
+ Attrs: `placement` (default `'top'` — see [Placement](#placement)), `offset` (8), `delay` (600ms), `disabled`, `flavor` (default `'neutral'`, alias `dark`). `primary`, `success`, `danger`, `warning` and custom flavors are solid fills from `--ty-solid-X` / `--ty-solid-X-fg`, with `+`/`-` shades.
622
+
623
+ Nest as child of target: `<ty-button>Hover<ty-tooltip>Help text</ty-tooltip></ty-button>`
624
+
625
+ **Content is real HTML**, not plain text — `<ty-tooltip><kbd>Ctrl+S</kbd> to save</ty-tooltip>` renders the `<kbd>` tag, not the literal text.
626
+
627
+ **Accessible by default:** the popover gets `role="tooltip"` and the trigger (`ty-tooltip`'s parent element — must be the actual interactive/focusable element, not a wrapping `<div>`) gets a matching `aria-describedby`, wired eagerly on connect — a keyboard user tabbing to the trigger doesn't have to wait out the hover `delay` to get an accessible description. An existing `aria-describedby` on the trigger is appended to, not overwritten.
628
+
629
+ **The default `neutral` chip is theme-independent by design** — a fixed dark chip in both light and dark pages (matches Material/Bootstrap/Ant/Shoelace), so it always pops regardless of what it's sitting on. Colors come from `--ty-tooltip-bg` / `--ty-tooltip-color` / `--ty-tooltip-border`, defined once on `:root` (not redeclared per theme) — override them globally, or per instance with `<ty-tooltip style="--ty-tooltip-bg: #000">`. The other flavors follow the theme. The popover lives in `<body>`, so define custom-flavor tokens on `:root`.
630
+
631
+ ---
632
+
633
+ ### ty-popup
634
+
635
+ Attrs: `manual`, `disable-close`, `placement` (default `'bottom'` — see [Placement](#placement)), `offset` (8).
636
+
637
+ **Methods:** `openPopup()`, `closePopup()`, `togglePopup()` | **Events:** `open`, `close` (don't bubble)
638
+
639
+ Nest as child of the trigger: `<button>Click me<ty-popup>...</ty-popup></button>`. Unless `manual`, the trigger automatically gets `aria-haspopup="dialog"` and a live `aria-expanded` (the popup itself is a real `<dialog>` via `showModal()`, so it already has `role="dialog"` + focus-trap for free).
640
+
641
+ **Opening.** Unless `manual`, a press on the trigger toggles the popup, and so do Enter or Space on the focused trigger and `trigger.click()`, for a native `<button>` and a `ty-button` alike. A `<label>` around a `ty-button` trigger opens it too; around a native `<button>` it doesn't in Chromium and Firefox. Clicks and keys inside the popup content don't toggle it. In a `ty-button` trigger they aren't presses of the button either: they don't submit its form, and listeners see the real target. The trigger's own press still submits, so give a `ty-button` trigger inside a form `type="button"`.
642
+
643
+ **Keys.** Opening moves focus into the popup: to an `[autofocus]` control in it, else the popup itself. Escape closes the popup unless `disable-close`. A `ty-select` list or `ty-date-picker` calendar open inside it takes its keys first: Escape closes that, the next Escape closes the popup.
644
+
645
+ ---
646
+
647
+ ### Placement
648
+
649
+ Shared by `ty-popup`, `ty-tooltip`, `ty-select` and `ty-date-picker`. A placement is a **side** plus an optional **cross-axis alignment**:
650
+
651
+ ```
652
+ <side> centered on the anchor
653
+ <side>-start leading edges flush
654
+ <side>-end trailing edges flush
655
+ ```
656
+
657
+ Twelve values in total — `top` `top-start` `top-end`, `right` `right-start` `right-end`, `bottom` `bottom-start` `bottom-end`, `left` `left-start` `left-end`.
658
+
659
+ For **top/bottom** the alignment runs horizontally (`-start` = left edges flush, `-end` = right edges flush). For **left/right** it runs vertically (`-start` = top edges flush, `-end` = bottom edges flush).
660
+
661
+ **The geometry contract** (what you can rely on, identical for popup and tooltip): measurements are of the **visible surface**, never any internal shadow-room wrapper — on the chosen side there is an **8px gap** (the `offset` attribute) between trigger edge and surface edge, `-start`/`-end` put the aligned edges **exactly flush**, and no suffix **centers** the surface on the trigger. `ty-select` / `ty-date-picker` use the same 8px visual gap below/above their field.
662
+
663
+ ```html
664
+ <ty-button>Menu
665
+ <ty-popup placement="bottom-start">…</ty-popup> <!-- below, left edges flush -->
666
+ </ty-button>
667
+
668
+ <ty-button>Help
669
+ <ty-tooltip placement="right-start">…</ty-tooltip> <!-- right, top edges flush -->
670
+ </ty-button>
671
+ ```
672
+
673
+ **Auto-flip keeps your alignment.** When the requested position doesn't fit, the popup tries, in order: the *opposite* side with the same alignment, the other alignments on the requested side, the other alignments on the opposite side, then the two perpendicular sides. It takes the first that fits, else the one that overflows least. So `left-start` becomes `right-start` — still top-aligned — long before it becomes `bottom`.
674
+
675
+ **Dropdowns are vertical-only.** `ty-select` and `ty-date-picker` open above or below their trigger, so they accept `bottom*` / `top*` directly; a `left-*` / `right-*` value keeps its alignment but leaves the side automatic. Both still flip rather than clip.
676
+
677
+ ```html
678
+ <ty-select placement="bottom-end">…</ty-select>
679
+ <ty-date-picker placement="top-start"></ty-date-picker>
680
+ ```
681
+
682
+ ---
683
+
684
+ ### ty-icon
685
+
686
+ Attrs: `name`, `size` (`xs` | `sm` | `md` | `lg` | `xl`), `spin`, `pulse`, `tempo`.
687
+
688
+ **Two rendering paths:**
689
+
690
+ 1. **Registry lookup** (`name="check"`) — bundler-friendly, tree-shakeable. See the JavaScript guide for `registerIcons` / `window.tyIcons`.
691
+ 2. **Inline SVG via slot** — pass raw `<svg>` as a child and the registry is bypassed. No JS registration required. Ideal for server-rendered apps (HTMX, Datastar, Phoenix, Rails, JSF…) where the backend already has the SVG.
692
+
693
+ ```html
694
+ <!-- Path 1: registry -->
695
+ <ty-icon name="check" size="md"></ty-icon>
696
+
697
+ <!-- Path 2: slotted SVG (no registry needed) -->
698
+ <ty-icon size="md" class="ty-text-primary">
699
+ <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
700
+ <polyline points="20 6 9 17 4 12"/>
701
+ </svg>
702
+ </ty-icon>
703
+ ```
704
+
705
+ `size`, `spin`, `pulse`, `tempo`, and `ty-text-*` color classes apply to the host element — they work identically on both paths. Use `currentColor` for `fill`/`stroke` so text-color classes still tint the SVG.
706
+
707
+ ---
708
+
709
+ ### ty-scroll-container
710
+
711
+ | Attribute | Type | Default | Description |
712
+ |-----------|------|---------|-------------|
713
+ | `no-shadow` | boolean | `false` | No top/bottom shadow indicators |
714
+ | `max-height` | string | - | Constrain height (e.g. `"400px"`, `"50vh"`) |
715
+ | `hide-scrollbar` | boolean | `false` | Hide native scrollbar |
716
+ | `custom-scrollbar` | boolean | `false` | Render custom styled scrollbar |
717
+ | `overflow-x` | boolean | `false` | Enable horizontal scrolling |
718
+
719
+ ```html
720
+ <ty-scroll-container max-height="400px">
721
+ <div>Item 1</div>
722
+ <div>Item 2</div>
723
+ </ty-scroll-container>
724
+ ```
725
+
726
+ ---
727
+
728
+ ### ty-resize-observer
729
+
730
+ Attrs: `id` (required), `debounce`. Query: `window.tyResizeObserver.getSize(id)`
731
+
732
+ ---
733
+
734
+ ### ty-sortable
735
+
736
+ Reorders its element children, or moves them into another `ty-sortable` with the same `group`, by pointer, keyboard or `move()`. It never moves the nodes itself: a drop fires `ty-sortable-change` on the destination list, your code renders the new order, and the result holds on screen until it does.
737
+
738
+ | Attribute | Type | Default | Description |
739
+ |-----------|------|---------|-------------|
740
+ | `group` | string | - | Lists with the same group trade items. Each needs an `id` |
741
+ | `axis` | string | `"vertical"` | `vertical` or `horizontal` |
742
+ | `handle` | selector | `"[data-handle]"` | If an item contains a match, drags start only there |
743
+ | `accepts` | selector | - | Items from other lists must match it to drop here |
744
+ | `disabled` | boolean | `false` | No drags from or into this list |
745
+ | `key-attr` | string | - | Attribute holding the item key, checked before `data-key` and `id` |
746
+ | `hold-timeout` | number | `5000` | ms to hold a result with no render and no busy signal |
747
+ | `label` | string | - | List name in announcements (falls back to `aria-label`, then `id`) |
748
+ | `drop-line` | boolean | `false` | A drop line marks the slot and nothing moves. Without it the other items move aside while dragging. The list under the pointer decides |
749
+ | `flash` | boolean | `false` | Outline the item briefly where it lands |
750
+ | `aria-busy` | `"true"` | - | A save is in flight: the hold waits for it (htmx's `htmx-request` class counts too) |
751
+
752
+ **Items:** `data-key` / `id` (the key in `value`), `data-locked` (can't be dragged), `data-sortable-ignore` (not an item: headers, empty states), `data-no-drag` (pressing inside never starts a drag).
753
+
754
+ **Methods:** `move(itemOrKey, { to, index, before, after })` → `Promise<'accepted' | 'rejected' | 'reconciled' | 'unknown'>`; `settle('accepted' | 'rejected')` ends the hold now. **Properties:** `canDrop` (`({ item, key, from, to, index }) => boolean`, `false` blocks the slot), `labels` (announcement overrides), `items`, `keyOf(item)`.
755
+
756
+ **Events:** `ty-sortable-change` → `{ value: { key, group, source, from, to, order }, item, fromContainer, toContainer }`. `from` / `to` are `{ list, index, prev, next }`; `order` is the new key order of each touched list, by id.
757
+
758
+ ```html
759
+ <ty-sortable id="tasks" label="Tasks">
760
+ <div data-key="a">
761
+ <button type="button" data-handle aria-label="Move Design review">
762
+ <ty-icon name="grip-vertical"></ty-icon>
763
+ </button>
764
+ Design review
765
+ </div>
766
+ </ty-sortable>
767
+ ```
768
+
769
+ **Styling:** `--ty-sortable-indicator-color`, `--ty-sortable-blocked-color`, `--ty-sortable-indicator-size`, `--ty-sortable-source-opacity`, `--ty-sortable-source-outline`, `--ty-sortable-ghost-shadow`, `--ty-sortable-ghost-scale`, `--ty-sortable-ghost-rotate`, `--ty-sortable-flash-color`, `--ty-sortable-duration`. The dragged copy carries `data-ty-sortable-ghost` for page CSS.
770
+
771
+ Apply `value.order` (or save a rank between `value.to.prev` and `value.to.next`). Set `aria-busy="true"` on the list while saving: if it clears and the order didn't change, the item snaps back. On touch, a handle drags at once and leaves the row to scroll; without one, press and hold 250 ms.
772
+
773
+ ---
774
+
775
+ ## Icon System
776
+
777
+ ```clojure
778
+ (ns my-app.icons
779
+ (:require [tyrell.icons :as icons]
780
+ [tyrell.lucide :as lucide]))
781
+
782
+ (icons/register! {:check lucide/check
783
+ :user lucide/user}) ; the key is the name
784
+ ```
785
+
786
+ ```js
787
+ import { registerIcons } from 'tyrell-components/icons/registry'
788
+ import { check, chevronDown } from 'tyrell-components/icons/lucide'
789
+
790
+ registerIcons({ check, 'action-down': chevronDown }) // the key is the name
791
+ ```
792
+
793
+ ```html
794
+ <ty-icon name="check" size="sm"></ty-icon>
795
+ ```
796
+
797
+ Registry API on `window.tyIcons`: `register`, `has`, `get`, `list`, `cacheInfo`, `clearCache`.
798
+
799
+ Sets, tree-shaking, custom SVGs and troubleshooting: [ICONS_GUIDE.md](ICONS_GUIDE.md).
800
+
801
+ ---
802
+
803
+ ## Installation
804
+
805
+ ```bash
806
+ # NPM
807
+ npm install tyrell-components
808
+
809
+ # React
810
+ npm install tyrell-react
811
+ ```
812
+
813
+ ```html
814
+ <!-- CDN -->
815
+ <script src="https://cdn.jsdelivr.net/npm/tyrell-components@latest/dist/tyrell.js"></script>
816
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components@latest/css/tyrell.css">
817
+ <!-- tyrell.css alone has no color tokens. tyrell-theme.css supplies them via
818
+ auto-contrast text, seed-based rebranding, named/scoped themes, animated
819
+ theme transitions. See CSS_GUIDE.md → Color Customization. -->
820
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components@latest/css/tyrell-theme.css">
821
+ ```
822
+
823
+ Don't want the theme engine? Swap `tyrell-theme.css` for `tyrell-colors-static.css` — a plain hardcoded hex fallback palette, maximum-compatibility (no relative-color-syntax requirement, works on older browsers), no theming API. Use it only if you've made that trade-off deliberately.
824
+
825
+ ```clojure
826
+ ;; ClojureScript (Clojars)
827
+ [dev.gersak/tyrell "0.4.0"]
828
+ ```
829
+
830
+ ---
831
+
832
+ ## Positioning
833
+
834
+ Smart positioning for floating elements.
835
+
836
+ ```javascript
837
+ import { findBestPosition, autoUpdate, placementPreferences } from 'tyrell-components';
838
+
839
+ const result = findBestPosition({
840
+ targetEl: button,
841
+ floatingEl: tooltip,
842
+ preferences: placementPreferences.tooltip,
843
+ offset: 8,
844
+ padding: 8
845
+ });
846
+
847
+ tooltip.style.left = result.x + 'px';
848
+ tooltip.style.top = result.y + 'px';
849
+
850
+ // Continuous positioning (updates on scroll/resize)
851
+ const cleanup = autoUpdate(targetEl, floatingEl,
852
+ (position) => {
853
+ floatingEl.style.left = position.x + 'px';
854
+ floatingEl.style.top = position.y + 'px';
855
+ },
856
+ { preferences: placementPreferences.dropdown }
857
+ );
858
+ cleanup(); // Stop auto-updating
859
+ ```
860
+
861
+ ---
862
+
863
+ ## Framework Integration
864
+
865
+ **Properties set before the definition loads.** A framework that binds properties (React 19, Vue) or lazy loading can set `value`, `error`, `open` and the like on a Ty element before its script has run. Every Ty element applies those when it connects, and later assignments work normally. The early value wins over the matching attribute; `form.reset()` still goes back to the attribute, as on a native field.
866
+
867
+ ### React
868
+
869
+ ```typescript
870
+ import { TyButton, TyInput, TyModal } from 'tyrell-react';
871
+ // or short names:
872
+ import { Button, Input, Modal } from 'tyrell-react';
873
+ ```
874
+
875
+ | React Prop | Web Component Event | When |
876
+ |------------|---------------------|------|
877
+ | `onChange` | `input` | Every keystroke |
878
+ | `onChangeCommit` | `change` | On blur |
879
+ | `onFocus` | `focus` | Focus |
880
+ | `onBlur` | `blur` | Blur |
881
+
882
+ Imperative methods via refs: `useRef<TyModalRef>()` -> `.current?.show()` / `.hide()`
883
+
884
+ ### ClojureScript
885
+
886
+ ```clojure
887
+ ;; Event handling
888
+ [:ty-input {:on {:input (fn [e] (-> e .-detail .-value))
889
+ :change (fn [e] (-> e .-detail .-value))}}]
890
+
891
+ ;; Dynamic classes — use vectors, not string concatenation
892
+ [:div {:class ["ty-elevated" "p-4" (when active? "ty-bg-primary-")]}]
893
+ ```
894
+
895
+ ---
896
+
897
+ ## Utility Functions
898
+
899
+ ```javascript
900
+ // Resize observer
901
+ window.tyResizeObserver.getSize('element-id') // { width, height }
902
+ window.tyResizeObserver.onResize('id', ({ width, height }) => { ... })
903
+
904
+ // Scroll lock (used by modals)
905
+ import { lockScroll, unlockScroll, isLocked, forceUnlockAll } from 'tyrell-components';
906
+
907
+ // Positioning for floating elements
908
+ import { findBestPosition, autoUpdate, placementPreferences } from 'tyrell-components';
909
+ ```
910
+
911
+ ---
912
+
913
+ ## All Events Reference
914
+
915
+ | Component | Event | Detail |
916
+ |-----------|-------|--------|
917
+ | `ty-input` | `input`, `change` | `{ value, formattedValue, rawValue, originalEvent }` |
918
+ | `ty-checkbox` | `input`, `change` | `{ value, checked, formValue, originalEvent }` |
919
+ | `ty-select` | `change` | `{ value (scalar / array when multiple), values, items, action, item }`; with `external-selection` also `selected`, and `value` is the picked option |
920
+ | `ty-select` | `search` | `{ query, element }` |
921
+ | `ty-file-upload` | `change` | `{ value: File[], files: File[], names: string[] }` |
922
+ | `ty-date-picker` | `change` | `{ value, localValue, milliseconds, formatted, source }` |
923
+ | `ty-calendar` | `change` | `{ year, month, day, action, source, dayContext }` |
924
+ | `ty-tabs` | `ty-tab-change` | `{ activeId, activeIndex, previousId, previousIndex }` |
925
+ | `ty-tab` | `ty-tab-load` | `{ id, index }` (lazy tab shown with no content; doesn't bubble) |
926
+ | `ty-wizard` | `ty-wizard-step-change` | `{ activeId, activeIndex, previousId, previousIndex, direction }` |
927
+ | `ty-sortable` | `ty-sortable-change` | `{ value: { key, group, source, from, to, order }, item, fromContainer, toContainer }` (on the destination list; bubbles; `preventDefault()` rejects) |
928
+ | `ty-sortable` | `ty-sortable-start`, `ty-sortable-cancel`, `ty-sortable-settle` | `{ value, item }`, `{ value, item, reason }`, `{ value, outcome }` (don't bubble) |
929
+ | `ty-modal` | `close` | `{ reason, returnValue? }` |
930
+ | `ty-tag` | `dismiss` | -- |
931
+ | `ty-button` | `click` | `{ originalEvent }` (cancelable: `preventDefault()` cancels submit/reset) |
932
+
933
+ Always access via `event.detail.value`, never `event.target.value`.
934
+
935
+ **Bubbling:** `change` / `input` bubble like their native counterparts — delegation works. Popup lifecycle events (`open`, `close`, `beforeclose` on `ty-modal`, `ty-select`, `ty-date-picker`, `ty-popup`) **do not**, matching native `<dialog>`. Listen on the element itself; a container listener hears nothing, which is what keeps a dropdown closing inside a modal from closing the modal.